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

package/.storybook/customMDXComponents.jsx

@@ -0,0 +1,284 @@
+import { Source, useOf, Markdown } from "@storybook/addon-docs/blocks";
+import React, { useState } from "react";
+
+/* Custom MDX components for Storybook documentation pages.
+ * These components provide enhanced functionality for rendering
+ * code references, metadata, design resources, and notes sections.
+ */
+
+/**
+ * Custom hook to fetch and provide documentation data from story parameters.
+ * This centralises data access for all custom MDX components.
+ * @returns {object} An object containing docs data like metadata, template, etc.
+ */
+const useDocsData = () => {
+  // useOf must be called inside a functional component or another hook.
+  const resolvedOf = useOf("meta", ["meta"]);
+  const docs = resolvedOf.preparedMeta?.parameters?.docs || {};
+  const params = resolvedOf.preparedMeta?.parameters || {};
+
+  return {
+    componentMetadata:
+      docs.componentMetadata || params.coderefs?.metadata || {},
+    //codeReferences: docs.codeReferences,
+    notes: docs.notes || "",
+    hasData: (key) => docs[key] !== undefined && docs[key] !== null,
+  };
+};
+
+/**
+ * A simple wrapper for individual tab content.
+ * @param {object} props
+ * @param {string} props.label The text to display on the tab button.
+ * @param {React.ReactNode} props.children The content to render inside the tab panel.
+ */
+export const Tab = ({ children }) => {
+  // This component is a simple wrapper and doesn't render anything on its own.
+  // The Tabs component will handle the rendering.
+  return <>{children}</>;
+};
+
+/**
+ * A container component that renders a tabbed interface.
+ * It uses the children's props to create tab buttons and panels.
+ * @param {object} props
+ * @param {React.ReactElement<typeof Tab>[]} props.children One or more <Tab> components.
+ */
+export const Tabs = ({ title, children }) => {
+  const [activeTab, setActiveTab] = useState(0);
+  const tabs = React.Children.toArray(children).filter(
+    (child) => child.type === Tab,
+  );
+
+  return (
+    <div className="qgds-tabs-container d-flex" style={{ marginTop: "1.5rem" }}>
+      <div
+        className="qgds-tabs-nav"
+        style={{
+          borderRight: "1px solid #e0e0e0",
+          marginRight: "1rem",
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "flex-start",
+        }}
+      >
+        {tabs.map((tab, index) => (
+          <button
+            key={index}
+            onClick={() => setActiveTab(index)}
+            style={{
+              padding: "0.75rem 1.25rem",
+              border: "none",
+              background: "transparent",
+              cursor: "pointer",
+              fontSize: "1rem",
+              fontWeight: activeTab === index ? "bold" : "normal",
+              color: activeTab === index ? "#005f8f" : "#333",
+              borderBottom:
+                activeTab === index
+                  ? "3px solid #005f8f"
+                  : "3px solid transparent",
+              marginBottom: "-1px",
+            }}
+          >
+            {tab.props.label}
+          </button>
+        ))}
+      </div>
+      <div className="qgds-tabs-content">{tabs[activeTab]}</div>
+    </div>
+  );
+};
+
+/**
+ * Conditional wrapper for code reference tabs with granular control
+ * @param {object} props
+ * @param {string} props.title - Title for the section
+ * @returns {JSX.Element|null}
+ */
+export const CodeReferences = ({ title = "Code references" }) => {
+  const { codeReferences } = useDocsData();
+
+  // Don't render if no codeReferences array is provided
+  if (
+    !codeReferences ||
+    !Array.isArray(codeReferences) ||
+    codeReferences.length === 0
+  ) {
+    return null;
+  }
+
+  return (
+    <>
+      <h2 id="code-references">{title} 123</h2>
+      <Tabs>
+        {codeReferences.map((item, index) => {
+          // Handle different content types
+          let sourceContent;
+          let language = item.language || "text";
+          let label = item.label || `Tab ${index + 1}`;
+
+          if (item.language === "json" && typeof item.content === "object") {
+            // JSON objects need to be stringified
+            sourceContent = JSON.stringify(item.content, null, 2);
+          } else {
+            // For strings (handlebars, html, etc.) or other content
+            sourceContent = item.content;
+          }
+
+          return (
+            <Tab key={index} label={label}>
+              <Source
+                format="dedent"
+                dark
+                language={language}
+                code={sourceContent}
+              />
+            </Tab>
+          );
+        })}
+      </Tabs>
+    </>
+  );
+};
+
+/**
+ * Renders component metadata using QGDS tags for Category, Type and Status,
+ * and displays description as a paragraph.
+ * @returns {JSX.Element|null}
+ */
+export const ComponentMeta = () => {
+  const { componentMetadata } = useDocsData();
+
+  if (!componentMetadata) return null;
+
+  const scope = componentMetadata.scope;
+  const type = componentMetadata.type;
+  const status = componentMetadata.status;
+  const description = componentMetadata.description;
+
+  // Don't render if no metadata fields are present
+  if (!scope && !type && !status && !description) {
+    return null;
+  }
+
+  return (
+    <div class="mb-32">
+      {/* Tags for Category, Type, and Status */}
+      {(scope || type || status) && (
+        <ul class="tag-list tag-status m-0 p-0 gap-2">
+          {scope && <li className="tag-item tag-neutral tag-high">{scope}</li>}
+          {type && <li className="tag-item tag-neutral tag-high">{type}</li>}
+          {status && (
+            <li className="tag-item tag-success  tag-high">{status}</li>
+          )}
+        </ul>
+      )}
+
+      {/* Description as paragraph */}
+      {description && (
+        <p
+          class="pb-16 lead"
+          dangerouslySetInnerHTML={{ __html: description }}
+        ></p>
+      )}
+    </div>
+  );
+};
+
+/**
+ * Renders links to design resources like Figma.
+ * @returns {JSX.Element|null}
+ */
+export const DesignResources = () => {
+  const { componentMetadata } = useDocsData();
+  const title_uikit = componentMetadata?.title_uikit || "";
+  const url_uikit = componentMetadata?.refs?.uikit || null;
+  const url_website = componentMetadata?.refs?.website || null;
+  const title = componentMetadata?.title || "this component";
+
+  if (!url_uikit && !url_website) return null;
+
+  return (
+    <>
+      <h2 className="mb-16" id="design-resources">
+        Design resources
+      </h2>
+
+      {/* Link to Figma */}
+      {url_uikit && (
+        <a
+          href={url_uikit}
+          target="_blank"
+          rel="noopener noreferrer"
+          style={{ display: "block", marginBottom: "0.5rem" }}
+          title={`View ${title_uikit} in the QGDS UI Kit (Figma)`}
+        >
+          Figma UI Kit
+        </a>
+      )}
+
+      {/* Link to Design System website */}
+      {url_website && (
+        <a
+          href={url_website}
+          target="_blank"
+          rel="noopener noreferrer"
+          style={{ display: "block", marginBottom: "0.5rem" }}
+          title={`View ${title} on Design System website`}
+        >
+          designsystem.qld.gov.au
+        </a>
+      )}
+    </>
+  );
+};
+
+/**
+ * Renders usage instructions, either default or custom markdown content.
+ * @param {object} props
+ * @param {string} props.title - The title/heading for this section
+ * @returns {JSX.Element|null}
+ */
+export const Notes = ({ title = "Notes" }) => {
+  const { notes } = useDocsData();
+
+  // Hide the section entirely if explicitly set to false
+  if (notes?.show === false || notes?.trim() === "") return null;
+
+  return (
+    <>
+      <h2 id="notes">{title}</h2>
+      <Markdown>{notes}</Markdown>
+    </>
+  );
+};
+
+/**
+ * Renders instructions for accessing the Code References panel.
+ * @returns {JSX.Element}
+ */
+export const CodeReferencesInstructions = ({ title = "Code references" }) => {
+  return (
+    <>
+      <h2 className="mb-16" id="code-references">
+        {title}
+      </h2>
+      <p>To view code examples, templates, and implementation details:</p>
+      <ol>
+        <li>Select any story from the sidebar</li>
+        <li>
+          Open the Actions panel by pressing <kbd>A</kbd>
+        </li>
+        <li>
+          Click the <strong>Code References</strong> tab
+        </li>
+      </ol>
+      <p>
+        The Code References panel provides access to Handlebars templates, JSON
+        data structures, rendered HTML output, and usage guidelines for each
+        component.
+      </p>
+    </>
+  );
+};

package/.storybook/main.mjs

@@ -2,10 +2,13 @@
 // Is an ESM module now
 
 import path from "path";
+import { fileURLToPath } from "url";
+import react from "@vitejs/plugin-react";
 
 const config = {
   stories: [
-    "../src/stories/Introduction.mdx",
+    //"../src/stories/getting-started.mdx",
+    //"../src/stories/Introduction.mdx",
     // 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/**/!(*_)*.mdx",
@@ -21,7 +24,7 @@ const config = {
     "@chromatic-com/storybook",
     "storybook-addon-deep-controls",
     "@storybook/addon-docs",
-    "storybook-addon-tag-badges",
+    "./addons/qgds-multi-code-panels/preset.js",
   ],
 
   framework: {
@@ -45,8 +48,19 @@ const config = {
   //https://storybook.js.org/docs/api/main-config-vite-final
 
   viteFinal: async (config, { configType }) => {
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const addonPath = path.resolve(__dirname, "addons");
+
     config.root = "./dist";
 
+    // Add React plugin for JSX transformation in QGDS addons
+    config.plugins = config.plugins || [];
+    config.plugins.push(
+      react({
+        include: [`${addonPath}/**/*.{js,jsx,ts,tsx}`],
+      }),
+    );
+
     // Define environment variables for the browser
     config.define = {
       ...config.define,
@@ -54,15 +68,6 @@ const config = {
         process.env.ENABLE_DYNAMIC_THEME === "true",
       ),
     };
-    // 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;
-    //         }
-    //     },
-    // });
 
     config.server = {
       ...config.server,

package/.storybook/manager.js

@@ -1,5 +1,5 @@
 import { addons } from "storybook/internal/manager-api";
-import { defaultConfig } from "storybook-addon-tag-badges/manager-helpers";
+//import { defaultConfig } from "storybook-addon-tag-badges/manager-helpers";
 
 /**
  * Custom badge configuration for QGDS component library
@@ -26,6 +26,6 @@ addons.setConfig({
     },
 
     // Include default badges from the addon (new, deprecated, experimental, etc.)
-    ...defaultConfig,
+    //...defaultConfig,
   ],
 });

package/.storybook/preview.js

@@ -1,3 +1,18 @@
+import * as React from "react";
+import { useEffect } from "storybook/preview-api";
+import { addons } from "storybook/preview-api";
+import DocumentationTemplate from "./DocumentationTemplate.mdx";
+
+import {
+  Title,
+  Subtitle,
+  Description,
+  Primary,
+  Controls,
+  Stories,
+  Markdown,
+} from "@storybook/addon-docs/blocks";
+
 import "../node_modules/bootstrap/dist/js/bootstrap.bundle.min.js";
 import "../src/css/main.scss";
 import { withThemeByClassName } from "@storybook/addon-themes";
@@ -5,6 +20,8 @@ import {
   withDynamicTheme,
   dynamicThemeGlobalTypes,
 } from "./dynamicThemeDecorator.js";
+
+import { withCodeRefs } from "./codeRefsDecorator.js";
 import { breakpoints } from "../src/js/constants.js";
 
 // Check if dynamic theme should be enabled via environment variable
@@ -90,9 +107,18 @@ const preview = {
       },
     },
     docs: {
+      page: DocumentationTemplate,
+      toc: {
+        disable: false,
+        headingSelector: "h2, h3",
+        title: "",
+      },
       source: {
         excludeDecorators: true,
+        state: "open",
+        type: "dynamic",
       },
+      codePanel: false,
     },
     backgrounds: {
       options: {
@@ -108,7 +134,13 @@ const preview = {
       storySort: {
         method: "alphabetical",
         // Set order of components in the Layout category
-        order: ["*", ["Header", "Footer", "Breadcrumbs", "Side navigation"]],
+        order: [
+          "Welcome",
+          "Introduction",
+          ["How to use", "Development", "*"],
+          "*",
+          ["Header", "Footer", "Breadcrumbs", "Side navigation"],
+        ],
       },
     },
     a11y: {
@@ -128,7 +160,13 @@ const preview = {
     },
   },
 
+  sidebar: {
+    showRoots: false,
+  },
+
   decorators: [
+    withCodeRefs,
+
     ...(ENABLE_DYNAMIC_THEME ? [withDynamicTheme] : []),
     // data-bs-theme="dark" won't be used
     withThemeByClassName({

package/dist/assets/components/bs5/directionLinks/directionLinks.hbs

@@ -5,6 +5,5 @@
     {{~#if target}} target="{{target}}"{{/if~}}
     {{~#if arialabel}} aria-label="{{arialabel}}" {{/if~}}>
   {{{label}}}
-  {{!-- <span class="icon" aria-hidden="true"></span> --}}
   <span class="qld-icon qld-icon-md qld-icon-arrow-{{class}}" aria-hidden="true"></span>
 </a>

package/dist/assets/components/bs5/head/head.hbs

@@ -1,5 +1,5 @@
 
-<!-- VERSION_DETAILS={"project_id":"@qld-gov-au/qgds-bootstrap5","version":"2.1.9","branch":"HEAD","tag":"v2.1.9","commit":"228f45b9dea4dd6674147c93a086038ac167746f","majorVersion":"v2"} -->
+<!-- VERSION_DETAILS={"project_id":"@qld-gov-au/qgds-bootstrap5","version":"2.1.11","branch":"HEAD","tag":"v2.1.11","commit":"5a3e313339341709791de452b0963964578103a8","majorVersion":"v2"} -->
 
 {{! Select environment, used verbatium if not using predefind key
 cdn := PROD|STAGING|BETA|TEST|DEV|???

package/dist/assets/components/bs5/pagination/pagination.hbs

@@ -1,10 +1,3 @@
-{{!
-Component Name: QGDS QOL Pagination
-Component Version: 1.0
-Framework: Bootstrap 5.3
-Reference: https://getbootstrap.com/docs/5.0/components/pagination/
-}}
-
 <nav aria-label="{{ arialabel }}">
 
     <ul class="pagination">