@qld-gov-au/qgds-bootstrap5 2.1.9 → 2.1.11

package/src/stories/Introduction/development.mdx

@@ -0,0 +1,136 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Introduction/Development" />
+
+# QGDS Bootstrap 5 project development
+
+Follow this guide to set up a local development environment for the QGDS Bootstrap 5 project.
+
+Alternatively, you can fork the repository to create your own version for personal use, customisation or contribution.
+
+## Technical summary
+
+**Build and development:**
+
+- ESbuild - Fast bundling, minification, and transpilation
+- Storybook - Component development, testing, and documentation
+- Vitest - Unit testing framework
+
+**Prerequisites:**
+
+- Node v22+
+- NPM 10.9.3+
+- Java 11+ (Optional, for Maven builds)
+
+## Installation
+
+**Quick build (Maven):**
+
+If you have Java and Maven installed, this will pull in a local node/npm version and run through the full lifecycle build.
+
+```bash
+git clone https://github.com/qld-gov-au/qgds-bootstrap5
+cd qgds-bootstrap5
+mvn install
+```
+
+**Standard build (Node/NPM):**
+
+Download and install dependencies:
+
+```bash
+git clone https://github.com/qld-gov-au/qgds-bootstrap5
+npm install
+```
+
+Build the Design System CSS, Components and templates (output to `dist/`):
+
+```bash
+npm run build
+```
+
+**Preview components **
+
+Preview components and documentation locally with Storybook:
+
+```bash
+npm run storybook
+```
+
+## Linting
+
+```bash
+npm run lint
+```
+
+## Husky
+
+Husky is used to manage Git hooks for pre-commit and pre-push actions.
+
+The following hooks are configured:
+
+- **Pre-commit Hook:** Runs linting and unit tests before allowing a commit. This ensures code quality and prevents committing code that fails tests or does not adhere to coding standards.
+- **Pre-push Hook:** Executes unit tests before pushing code to a remote repository. This helps catch issues early and maintains the integrity of the codebase.
+
+## Theming
+
+-- todo
+
+## Unit Tests
+
+In addition to manual testing via storybook, unit tests may be created and run via <code>vitest</code>.
+
+```bash
+npm run test
+```
+
+or use the browser based ui
+
+```bash
+npm run test:ui
+```
+
+See src/components/bs5/accordion/accordion.test.js for example unit test including snapshot and interaction tests with JSDOM.
+
+## Github Actions
+
+This repo includes many workflows to reduce developer overheads. This includes but not limited to:
+
+- CICD on all commit's and PR's
+- GitHub io static document deployment based on develop/main
+- Dependabot auto patching + storybook upgrade feature
+- One click npm versioning publish (patch, minor, major) \*\*
+- Auto generate release notes based on PR's created (On version Tag)
+- Npm js package publish (On version Tag) \*\*\*
+- GitHub package Publish (On version Tag) \*\*\*\*
+
+Must configure GitHub service account ssh private key loaded into GitHub actions secret DEPLOY_KEY
+
+- Must have npm js token loaded into GitHub actions secrets NPM_TOKEN to allow publishing.
+  \*\*\*\* Switch's @qld-gov-au with forked username (lowercase) and publish to your account see .github/workflows/githubPackage.yml step Update package scope, export package name.
+
+## Contributing
+
+This repository is designed to be easily forked for personal development or contribution.
+
+**After forking:**
+
+- Enable GitHub Actions in your repository settings
+- Configure GitHub Pages to deploy via GitHub Actions
+- Set up your own Chromatic account for visual regression testing and change diffing
+
+**External Contributions:**
+
+We welcome contributions from the community! Feel free to submit pull requests with improvements, bug fixes, or new features. Your contributions may be included in the core library and CDN distribution.
+
+## IDE Recommendations
+
+We recommend using VSCode as the IDE for development with the following plugins:
+
+- Prettier
+- ESLint
+- Mustache JS or Handlebars JS template support
+
+Webstorm also works.
+
+---

package/src/stories/Introduction/how-to-use.mdx

@@ -0,0 +1,272 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="Introduction/How to use" />
+
+# How to use QGDS Bootstrap 5
+
+The Queensland Government Design System (QGDS) Bootstrap 5 library provides reusable UI components built on Bootstrap 5 for Queensland Government websites and applications.
+
+Review the [Introduction](./?path=/docs/welcome--overview) page for an overview of the QGDS Bootstrap 5 Storybook and available components.
+
+---
+
+## Technical summary
+
+**Core Technologies:**
+
+- JavaScript (ES6+) - Modern JavaScript for component logic
+- CSS/SCSS - Extends Bootstrap 5.3 with custom CSS properties and design tokens
+- Handlebars - Template engine for component rendering (client and server-side)
+
+**Distribution:**
+
+- NPM - Package distribution for Node.js projects
+- CDN - Direct browser integration via static hosting
+
+**Design:**
+
+- Figma - Design system and UI Kit source
+
+---
+
+## Prerequisites
+
+Before installing QGDS Bootstrap 5, you'll need:
+
+- **Node.js** 22+ or higher (for npm-based projects)
+- **NPM v10.9.3** or higher (for npm-based projects)
+- **Handlebars** 4.7.8 or higher
+- **Bootstrap 5.3** (automatically included with QGDS)
+
+---
+
+## Resources
+
+The QGDS Bootstrap 5 project compiles and distributes the following critical resources for client-side rendering.  
+
+The resources are available via CDN, as tagged Github releases, or via our project NPM package:
+
+### CDN
+[https://static.qgov.net.au/qgds-bootstrap5/v2/v2.x.x-latest/assets/css/qld.bootstrap.css](https://static.qgov.net.au/qgds-bootstrap5/v2/v2.x.x-latest/assets/css/qld.bootstrap.css) (Global Stylesheet)
+[https://static.qgov.net.au/qgds-bootstrap5/v2/v2.x.x-latest/assets/js/handlebars.init.min.js](https://static.qgov.net.au/qgds-bootstrap5/v2/v2.x.x-latest/assets/js/handlebars.init.min.js) (Components - _Handlebars templates_)
+[https://static.qgov.net.au/qgds-bootstrap5/v2/v2.x.x-latest/assets/js/qld.bootstrap.min.js](https://static.qgov.net.au/qgds-bootstrap5/v2/v2.x.x-latest/assets/js/qld.bootstrap.min.js) (Global JS)
+ 
+**Environment-specific CDNs:**
+- Production: https://static.qgov.net.au/qgds-bootstrap5/...
+- Staging: https://staging-static.qgov.net.au/qgds-bootstrap5/...
+- Development: https://dev-static.qgov.net.au/qgds-bootstrap5/...
+
+**Versioning:**
+- Use v2.x.x-latest for automatic minor/patch updates
+- Use specific versions (e.g., v2.1.8) for production stability
+
+### NPM Package
+
+The library is available as an NPM package for Node.js projects:
+[https://www.npmjs.com/package/@qld-gov-au/qgds-bootstrap5](https://www.npmjs.com/package/@qld-gov-au/qgds-bootstrap5)
+
+
+### Github Tagged Releases
+Compiled CSS, JS and sample component data are also available via our Github release repository:
+[https://github.com/qld-gov-au/qgds-bootstrap5-release](https://github.com/qld-gov-au/qgds-bootstrap5-release)
+
+---
+
+## How to use
+
+QGDS Bootstrap 5 supports both server-side and client-side integration. All components are registered as Handlebars.js partials and can be invoked using the `{{> partialName}}` syntax. These partials accept data objects or inline properties for flexible rendering. Refer to the examples below for implementation-specific code snippets.
+
+
+### Server side
+Use this approach for server-side rendering with Node.js, Next.js, Vue JS, etc.
+
+Install QGDS Bootstrap 5 and Handlebars via NPM:
+
+```bash
+npm install @qld-gov-au/qgds-bootstrap5 handlebars
+```
+
+Example usage:
+
+```javascript
+//index.js
+import Handlebars from "handlebars";
+import QGDSBundle from "@qld-gov-au/qgds-bootstrap5/handlebarsInit";
+
+// Initialize QGDS (registers all component partials and helpers)
+QGDSBundle.init(Handlebars);
+
+// Component data (typically from your API or CMS)
+const componentData = {
+  title: "Service update",
+  content:
+    "Our online services will be unavailable for maintenance from 2-4 AM AEST.",
+  variant: "warning",
+  dismissible: true,
+};
+
+// Render the component
+const html = Handlebars.compile("{{> callout}}")(componentData);
+
+// Use composed markup in your application
+console.log(html);
+```
+
+Run in console:
+```bash
+node index.js
+```
+
+### Client side
+
+QGDS Bootstrap 5 components can also be rendered directly in the browser. Use a CDN to load required QGDS resources, and include Handlebars runtime.
+
+Components can be rendered by compiling Handlebars partials with data objects.
+
+```html
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>QGDS Example</title>
+
+    <!-- QGDS Stylesheet -->
+    <link
+      rel="stylesheet"
+      href="https://static.qgov.net.au/qgds-bootstrap5/v2/v2.x.x-latest/assets/css/qld.bootstrap.css"
+    />
+  </head>
+  <body>
+    
+    <div id="app" class="container">
+    </div>
+
+    <!-- Required JavaScript including Handlebars runtime and QGDS scripts -->
+    <script src="https://cdn.jsdelivr.net/npm/handlebars@4.7.8/dist/handlebars.min.js"></script>
+    <script src="https://static.qgov.net.au/qgds-bootstrap5/v2/v2.x.x-latest/assets/js/handlebars.init.min.js"></script>
+    <script src="https://static.qgov.net.au/qgds-bootstrap5/v2/v2.x.x-latest/assets/js/qld.bootstrap.min.js"></script>
+
+    <script>
+      // Setup an component instance using a Handlebars partial
+      const calloutTemplate = Handlebars.compile("{{> callout}}");
+
+      // Setup component data
+      // Refer to QGDS Bootstrap 5 release repository for example data structures
+      // https://github.com/qld-gov-au/qgds-bootstrap5-release/tree/develop/sample-data 
+      const calloutData = {
+        title: "Welcome to QGDS",
+        content: "Get started with Queensland Government Design System",
+        variant: "info",
+      };
+
+      document.getElementById("app").innerHTML = calloutTemplate(calloutData);
+    </script>
+  </body>
+</html>
+```
+
+---
+
+## Working with component data
+
+QGDS components are compiled by pairing a Handlebars JS template with a JSON data object.
+
+Some of these data objects can be complex, containing nested structures for lists, buttons, links, and other sub-components.
+
+The Handlebars JS library provides flexibility in how you pass data to component partials. You can use either:
+
+1. Define data for a component, then pass it to the partial
+
+```javascript
+const mydata = {
+  title: "This is a callout title",
+  content: "This is a callout description",
+};
+const html = Handlebars.compile("{{> callout}}")(mydata);
+```
+
+2. Pass an object directly as the data argument 
+```javascript
+const html = Handlebars.compile("{{> callout}}")({
+  title: "This is a callout title",
+  content: "This is a callout description",
+});
+```
+
+3. Use a partial with inline properties
+```javascript
+const html = Handlebars.compile(
+  "{{> callout title='Click Me' content='This is a callout description'}}",
+)();
+```
+
+### Sample data
+
+Each of our component stories include code references that show example data, partials markup, and guidance on how to use them..
+
+Our Bootstrap 5 release repository also includes sample JSON data files for each component.
+[QGDS Bootstrap 5 Release Repository - Sample Data](https://github.com/qld-gov-au/qgds-bootstrap5-release/tree/develop/sample-data)
+
+
+## Code references
+
+Browse the component library using the sidebar. Each component page in Storybook includes:
+
+- Examples - Interactive component demos with different variants
+- Controls - Adjustable properties to preview changes
+- Code References - View JSON data, Handlebars templates, and rendered HTML
+- Open any story
+  - Press Cmd+A (Mac) or Ctrl+A (Windows) to open the Actions panel
+  - Click the Code References tab
+
+---
+
+## Accessibility
+
+This project is committed to providing accessible and inclusive components for all users.
+
+**Standards Compliance:**
+
+- All components are tested against [WCAG 2.1 Level AA](https://www.w3.org/WAI/WCAG21/quickref/) standards
+- Follows [Queensland Government digital accessibility requirements](https://www.qld.gov.au/web-accessibility)
+- Ensures equal access to information, services, and opportunities
+
+**Reporting Issues:**
+
+If you encounter accessibility barriers or have suggestions for improvement:
+
+- [Open an issue on GitHub](https://github.com/qld-gov-au/qgds-bootstrap5/issues)
+- Contact the QGDS team via the [Design System website](https://designsystem.qld.gov.au)
+
+---
+
+## Additional Resources
+
+Package Repositories
+
+- [QGDS Bootstrap 5 on npm](https://www.npmjs.com/@qld-gov-au/qgds-bootstrap5)
+- [Source code (GitHub)](https://github.com/qld-gov-au/qgds-bootstrap5)
+- [Release repository (GitHub)](https://github.com/qld-gov-au/qgds-bootstrap5-release)
+
+Documentation
+
+- [Storybook component library](https://qld-gov-au.github.io/qgds-bootstrap5)
+- [Design System website](https://designsystem.qld.gov.au)
+
+Design Resources
+
+- [QGDS UI Kit (Figma)](https://www.figma.com/community/file/1577907940583715898)
+
+Related Libraries
+
+- [QGDS Design Tokens](https://www.npmjs.com/@qld-gov-au/qgds-tokens)
+- [QGDS Design Tokens repository](https://github.com/qld-gov-au/qgds-tokens)
+- [QGDS Design System Queensland Health (Vanilla)](https://github.com/Qld-Health-Online-Team/design-system)
+
+---
+
+## Support
+
+For questions, issues, or contributions:
+
+- Open an issue on GitHub
+- Reach out to the QGDS team via the [Design System website](https://designsystem.qld.gov.au)

package/src/stories/Introduction.mdx

@@ -1,23 +1,105 @@
 import { Meta, Markdown } from "@storybook/addon-docs/blocks";
-
-import Readme from "../../README.md?raw";
+import componentList from "./component-list.json";
 
 <Meta title="Welcome" />
 
-[//]: # "# Welcome to QGDS QOL BS MVP Storybook"
-[//]: #
-[//]: # "Welcome to Queensland Government Design System Qld Online Mvp Storybook, this documentation is mainly for development and testing purposes."
-[//]: # "For user orientated documentation, please visit https://www.forgov.qld.gov.au/swe."
+<style>{`
+  .component-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+    gap: 1.5rem;
+    margin: 2rem 0;
+  }
+  .component-card {
+    border: 1px solid #ddd;
+    border-radius: 4px;
+    padding: 1.25rem;
+    background: #fff;
+    transition: box-shadow 0.2s, transform 0.2s;
+    text-decoration: none;
+    color: inherit;
+    display: block;
+  }
+  .component-card:hover {
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+    transform: translateY(-2px);
+    text-decoration: none;
+  }
+  .component-card-title {
+    font-size: 1.125rem;
+    font-weight: 600;
+    margin: 0 0 0.5rem 0;
+    color: #003865;
+  }
+  .component-card-scope {
+    display: inline-block;
+    font-size: 0.75rem;
+    padding: 0.25rem 0.5rem;
+    background: #f5f5f5;
+    border-radius: 3px;
+    margin-bottom: 0.5rem;
+  }
+  .component-card-description {
+    font-size: 0.875rem;
+    color: #666;
+    margin: 0;
+  }
+  .category-section {
+    margin-bottom: 3rem;
+  }
+  .category-title {
+    font-size: 1.5rem;
+    font-weight: 700;
+    margin-bottom: 1rem;
+    color: #003865;
+  }
+`}
+</style>
+
+
+## Welcome to the QGDS Bootstrap 5 library
+
+This Storybook serves as the interactive documentation for the Bootstrap 5 implementation of the Queensland Government Design System (QGDS).
+
+Whether you are starting a new project or updating an existing application, this library provides a robust, accessible, and compliant foundation for building digital services that look and feel like Queensland Government.
+
+## How to navigate this Storybook
+
+Use the sidebar to explore components organised by category.
+
+Find component variations and other information on each Overview tab.
+
+In each individual story, open the Actions panel to explore adjustable properties (Controls) and example code (Code references)
+
+## Components
+
+The following core components are available in this library.  Additional layout and utility components can be found in the sidebar.
+
+<div className="component-grid">
+  {componentList.map(component => (
+    <a 
+      key={component.id} 
+      href={`/?path=${component.storyPath}`}
+      className="component-card"
+    >
+      <div className="component-card-title">{component.title}</div>
+    </a>
+  ))}
+</div>
 
-<Markdown>{Readme}</Markdown>
 
----
+## [How to use](?path=/docs/introduction-how-to-use--overview)
+> Use this guide to implement the QGDS Bootstrap 5 edition in your web page or application.
 
-## Component Badges
+## [Project development](?path=/docs/introduction-development---overview)
+> Use this guide if working on or contributing to the QGDS Bootstrap 5 source code itself. It outlines the architecture, build processes, Github setup and repository forking.
 
-Components are labelled as:
 
-- **Core** — Essential, broadly applicable components that serve as the single source of truth for the Queensland Government design system.
-- **Extended** — Specialised components for needs not covered by the core set.
+## The QGDS Ecosystem
+This library is part of a coordinated suite of tools designed to ensure visual and functional consistency across all Queensland Government digital touchpoints:
 
-Further information is available in the [QGDS UI Kit](https://www.figma.com/design/qKsxl3ogIlBp7dafgxXuCA/QGDS-UI-kit?node-id=8701-244248&m=dev).
+- [Figma UI Kit](https://www.figma.com/community/file/978450410021220739): The design source of truth and visual specification for all components.
+- [QGDS Website](https://www.designsystem.qld.gov.au): The central hgub for Design System and component guidance and documentation.
+- Design Tokens: The foundational variables (colors, spacing, typography) that power our styles.
+- QGDS Web Components: A framework-agnostic implementation of Design System by the Queensland Government.
+- Vanilla Component Library: An independent framework-agnostic implementation of Design System by Queensland Health.

package/src/{components/bs5/accordion/Accordion.mdx → stories/archive/__Accordion.mdx}

@@ -17,13 +17,13 @@ import UsageInstructions from "./mdx/_usageInstructions.mdx";
 <StorybookDocsTabs
   tabs={[
     {
-      label: "Code",
+      label: "HTML",
       id: "code-doc",
       heading: "Component code",
       content: <Source language="html" id="accordion-default" />,
     },
     {
-      label: "JSON",
+      label: "Component Data",
       id: "json-doc",
       heading: "Example Component data",
       content: (
@@ -31,7 +31,7 @@ import UsageInstructions from "./mdx/_usageInstructions.mdx";
       ),
     },
     {
-      label: "Design Resources",
+      label: "UI kit",
       id: "design-resources-doc",
       content: <DesignResources />,
     },

package/src/stories/archive/__Blockquote.mdx

@@ -0,0 +1,13 @@
+import { Canvas, Meta, Story } from "@storybook/addon-docs/blocks";
+import * as BlockquoteStories from "./blockquote.stories";
+
+<Meta of={BlockquoteStories} />
+
+# Blockquote
+
+<Canvas of={BlockquoteStories.Default} />
+
+## Design resources
+
+- [Master component file (Figma)](https://www.figma.com/file/qKsxl3ogIlBp7dafgxXuCA/QLD-GOV-DDS?type=design&node-id=11056-321340&mode=design&t=YLfxdziHdqD2Ty0o-0)
+- [Design System website](https://www.designsystem.qld.gov.au/components/callouts#section__quote-example)

package/src/stories/archive/__BlockquoteCanvas.mdx

@@ -0,0 +1,47 @@
+import { Meta, Story, Canvas, Source } from '@storybook/addon-docs/blocks';
+import * as BlockquoteStories from './blockquote.stories';
+ 
+<Meta of={BlockquoteStories} />
+ 
+<Canvas
+  additionalActions={[
+    {
+      title: 'JSON',
+      onClick: () => {
+
+        const sourceToggleButton = document.querySelector('.docblock-code-toggle'); //Usually the hide/show code button
+
+        const sourcePanelContainer = document.querySelector('pre.prismjs');
+        if(sourcePanelContainer){
+          sourcePanelContainer.innerHTML = JSON.stringify(BlockquoteStories.Default.args, null, 2);
+          sourcePanelContainer.className = 'language-json';
+        }
+      },
+    },
+    {
+      title: 'Template',
+      onClick: () => {
+        // Show the Handlebars template
+        const template = '{{> blockquote}}'; // You can get this dynamically
+        console.log('Template:', template);
+
+        const sourceElement = document.querySelector('[data-docs-source] pre code');
+        if (sourceElement) {
+          sourceElement.textContent = template;
+          sourceElement.className = 'language-handlebars';
+        }
+      },
+    },
+    {
+      title: 'Show HTML',
+      onClick: () => {
+        // Reset to default HTML view
+        // This would restore the original source code
+        window.location.reload(); // Simple reset, or implement proper restoration
+      },
+    }
+
+]}
+of={BlockquoteStories.Default}
+
+/>

package/src/stories/archive/__backToTop.orig.mdx

@@ -0,0 +1,13 @@
+import { Canvas, Meta, Story } from "@storybook/addon-docs/blocks";
+import * as BackToTopStories from "./backToTop.stories";
+
+<Meta of={BackToTopStories} />
+
+# Back to Top
+
+<Canvas of={BackToTopStories.Default} />
+
+## Design resources
+
+- [Master component file (Figma)]()
+- [Design System website](https://www.designsystem.qld.gov.au/components/back-to-top)