Merge pull request qld-gov-au#5 from qld-gov-au/develop

QOLOE-8 Commit a baseline to main branch

.eslintrc.cjs

@@ -0,0 +1,52 @@
+module.exports = {
+  "env": {
+    "browser": true,
+    "es2021": true,
+  },
+  "extends": ["eslint:recommended", "plugin:storybook/recommended"],
+  "overrides": [
+    {
+      "env": {
+        "node": true,
+      },
+      "files": [
+        ".eslintrc.{js,cjs}",
+      ],
+      "parserOptions": {
+        "sourceType": "script",
+      },
+    },
+  ],
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module",
+  },
+  "plugins": [
+    "@stylistic/js",
+  ],
+  "rules": {
+    "@stylistic/js/indent": ["warn", 2],
+    "one-var": 0,
+    "no-tabs": 0,
+    "no-path-concat": 0,
+    "valid-jsdoc": "warn",
+    "spaced-comment": 0,
+    "space-before-blocks": 0,
+    "space-before-function-paren": 0,
+    "comma-dangle": [1, "always-multiline"],
+    "eol-last": 1,
+    "no-mixed-spaces-and-tabs": 0,
+    "no-multi-spaces": [
+      2,
+      {
+        "exceptions": {
+          "Property": true,
+          "VariableDeclarator": true,
+          "ImportDeclaration": true,
+          "ObjectExpression": true,
+        },
+      },
+    ],
+    "no-warning-comments": 1,
+  },
+}

.storybook/main.js

@@ -0,0 +1,56 @@
+import fs from "fs";
+import path from "path";
+
+import { mergeConfig } from "vite";
+
+const config = {
+	stories: [
+		// Include all stories found under the src/components directory ( For example: alert/alert.stories.js )
+		// Exlude any stories starting with an underscore ( For example: _exludeme.stories.js )
+		"../src/components/**/!(*_)*.stories.js",
+	],
+	addons: [
+		//Storybook addons
+		//https://storybook.js.org/addons/
+		"@storybook/addon-essentials",
+		"@storybook/addon-interactions",
+		"@storybook/addon-designs",
+		"@storybook/addon-links",
+	],
+
+	framework: {
+		//Build the storybook with html-vite rendered - faster than webpack
+		//https://www.npmjs.com/package/@storybook/html-vite
+		// todo: consider @storybook/builder-vite instead? 
+		name: "@storybook/html-vite",
+		options: {},
+	},
+
+	//Autodocs for each component
+	//https://storybook.js.org/docs/writing-docs/autodocs
+	docs: {
+		autodocs: "tag",
+		defaultName: 'Overview',
+	},
+
+
+	//Each component's JS module, for example Alert.js, imports a HTML string to use for it's template. 
+	//We add a plugin to handle these .mustache extensions. (Or .hbs, .html etc)
+	//https://storybook.js.org/docs/api/main-config-vite-final
+
+	viteFinal: async (config, { configType }) => {
+    	config.plugins.push({
+			name: "html-transform",
+			transform(src, id) {
+				if (id.endsWith(".mustache") || id.endsWith(".html" || id.endsWith(".hbs"))) {
+					// Transform your HTML files here (src is the file content as a string)
+					return src;
+				}
+			},
+		});
+
+		return config;
+	},
+};
+
+export default config;

.storybook/preview-head.html

@@ -0,0 +1,15 @@
+
+<!-- Refer: https://storybook.js.org/docs/configure/story-rendering#adding-to-head -->
+
+<style>
+    #storybook-docs .docblock-argstable-head th:nth-of-type(1) { min-width: 20% !important; }
+    #storybook-docs .docblock-argstable-head th:nth-of-type(2) { min-width: 25% !important; }
+    #storybook-docs .docblock-argstable-head th:nth-of-type(3) { min-width: 20% !important; }
+    #storybook-docs .docblock-argstable-head th:nth-of-type(4) { min-width: 35% !important; }
+
+
+    #storybook-docs .docblock-argstable-body textarea {
+        /* min-height: 100px; */
+    }
+
+</style>

.storybook/preview.js

@@ -0,0 +1,55 @@
+import { themes } from "@storybook/theming";
+
+import "../dist/assets/css/qld.bootstrap.css";
+
+const preview = {
+
+	parameters: {
+		actions: { argTypesRegex: "^on[A-Z].*" },
+		hideNoControlsWarning: true,
+		expanded: true,
+		controls: {
+			matchers: {
+				color: /(background|color)$/i,
+				date: /Date$/i,
+			},
+		},
+		html: {
+			highlighter: {
+				wrapLines: false,
+			},
+		},
+		docs: {
+			source: {
+				excludeDecorators: true,
+			},
+
+			toc: {
+				contentsSelector: '.sbdocs-content',
+				headingSelector: 'h1, h2, h3',
+				ignoreSelector: '#primary',
+				title: 'Table of Contents',
+				disable: false,
+				unsafeTocbotOptions: {
+					orderedList: false,
+				},
+			},
+		},
+	},
+
+	decorators: [
+		(Story) => {
+			return `
+			<div class="container-fluid">
+				<div class="row">
+					<div class="col-12">
+					${Story()}
+					</div>
+				</div>
+			</div>
+      		`;
+		},
+	],
+};
+
+export default preview;

.storybook/webpack.config.js

@@ -0,0 +1,8 @@
+module.exports = async ({ config, mode }) => {
+  config.module.rules.push({
+    test: /src\/components\/.*\/.*\.(html|mustache)$/i,
+    use: "raw-loader",
+  });
+  // Return the altered config
+  return config;
+};

.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+    "accessibility.voice.keywordActivation": "off",
+    "accessibility.voice.speechTimeout": 800
+}

README.md

@@ -1 +1,67 @@
-# qgds-bootstrap-poc
+# Queensland Online Design System development space
+
+## Extends Bootstrap 5.3
+
+## Technical overview
+
+- ES6 Javascript
+- ESbuild for bundling, minification and transpiling
+- Storybook for component development
+- Mustache for component and HTML templating
+- Figma for design and prototyping
+- CSS/SCSS, extending Bootstrap 5.3 core components with custom CSS properties
+- NPM for package management
+
+# Getting started
+
+## 1. Download
+
+```bash
+git clone https://github.com/qld-gov-au/qgds-qol-mvp
+```
+
+## 2. Setup
+
+### Prerequisites
+
+- Node 18.17.1
+- NPM 10.2.5
+
+### Install dependencies
+
+```bash
+npm install
+```
+
+### Build the Desing System CSS, Components and templates
+
+npm run **build** _or_ **node build.js**
+
+### Watch for changes and rebuild automatically
+
+npm run **watch** _or_ **node build.js --watch**
+
+### Start Storybook for component development
+
+npm run **storybook**
+
+### Start a local server from /dist folder
+
+npm run **serve**
+
+### Next steps
+
+- HTML templating using drop in components
+- Dev build and testing branching
+
+## Documentation
+
+- Storybook examples available at [https://qld-gov-au.github.io/qgds-qol-mvp/](https://qld-gov-au.github.io/qgds-qol-mvp/)
+
+## Development
+
+We recommend using VSCode as the IDE for development with the following plugins:
+
+- Prettier
+- ESLint
+- Mustache template support