@qld-gov-au/qgds-bootstrap5 2.1.10 → 2.1.12

package/.esbuild/plugins/qgds-plugin-clean-output-folders.js

@@ -13,11 +13,11 @@ export default function cleanFoldersPlugin() {
         const { outdir, outfile } = build.initialOptions;
 
         if (outdir && fs.existsSync(outdir)) {
-          fs.rmSync(outdir, { recursive: true });
+          fs.rmSync(outdir, { recursive: true, force: true, maxRetries: 3 });
         }
 
         if (outfile && fs.existsSync(outfile)) {
-          fs.rmSync(outfile);
+          fs.rmSync(outfile, { force: true });
         }
 
         // // Clean the docs folder

package/.esbuild/plugins/qgds-plugin-story-list-builder.js

@@ -0,0 +1,112 @@
+// qgds-plugin-story-list-builder.js
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const COMPONENTS_DIR = path.resolve(__dirname, "./../../src/components/bs5");
+const STORY_LIST_FILE = path.resolve(
+  __dirname,
+  "../../src/stories/component-list.json",
+);
+
+function getAllMetadataFiles(dirPath, arrayOfFiles) {
+  const files = fs.readdirSync(dirPath, { withFileTypes: true });
+
+  arrayOfFiles = arrayOfFiles || [];
+
+  files.forEach((file) => {
+    if (file.isDirectory()) {
+      arrayOfFiles = getAllMetadataFiles(
+        path.join(dirPath, file.name),
+        arrayOfFiles,
+      );
+    } else if (file.isFile() && file.name === "metadata.json") {
+      arrayOfFiles.push(path.join(dirPath, file.name));
+    }
+  });
+
+  return arrayOfFiles;
+}
+
+function readMetadata(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    const metadata = JSON.parse(content);
+
+    // Try to find corresponding .stories.js file
+    const componentDir = path.dirname(filePath);
+    const componentName = path.basename(componentDir);
+    const storyFiles = fs
+      .readdirSync(componentDir)
+      .filter((f) => f.endsWith(".stories.js"));
+
+    let storyTitle = null;
+    if (storyFiles.length > 0) {
+      const storyPath = path.join(componentDir, storyFiles[0]);
+      const storyContent = fs.readFileSync(storyPath, "utf8");
+      const titleMatch = storyContent.match(/title:\s*["']([^"']+)["']/);
+      storyTitle = titleMatch ? titleMatch[1] : null;
+    }
+
+    return {
+      id: metadata.id,
+      title: metadata.title,
+      title_uikit: metadata.title_uikit,
+      type: metadata.type,
+      scope: metadata.scope,
+      group: metadata.group || "Components",
+      status: metadata.status,
+      description: metadata.description,
+      refs: metadata.refs,
+      storyTitle: storyTitle,
+      storyPath: storyTitle
+        ? `/docs/${storyTitle.toLowerCase().replace(/\s+/g, "-").replace(/\//g, "-").replace(/\./g, "")}`
+        : null,
+    };
+  } catch (error) {
+    console.error(`Error reading ${filePath}:`, error);
+    return null;
+  }
+}
+
+export default function QGDSStoryListBuilderPlugin() {
+  return {
+    name: "story-list-builder",
+    setup(build) {
+      build.onStart(async () => {
+        const files = getAllMetadataFiles(COMPONENTS_DIR);
+        // Sort files alphabetically to ensure deterministic ordering
+        files.sort((a, b) =>
+          path
+            .basename(path.dirname(a))
+            .localeCompare(path.basename(path.dirname(b))),
+        );
+
+        const componentList = [];
+
+        for (const file of files) {
+          const metadata = readMetadata(file);
+          if (metadata && metadata.status === "Published") {
+            componentList.push(metadata);
+          }
+        }
+
+        //Sort component list by title
+        componentList.sort((a, b) => a.title.localeCompare(b.title));
+
+        // Write as JSON for easy import
+        fs.writeFileSync(
+          STORY_LIST_FILE,
+          JSON.stringify(componentList, null, 2),
+        );
+
+        console.log(
+          `${componentList.length} components found and written to ${STORY_LIST_FILE}`,
+        );
+      });
+    },
+  };
+}

package/.storybook/DocumentationTemplate.mdx

@@ -0,0 +1,47 @@
+import {
+  Meta,
+  Title,
+  Primary,
+  Canvas,
+  Controls,
+  Stories,
+  Source,
+  useOf,
+} from "@storybook/addon-docs/blocks";
+
+import {
+  ComponentMeta,
+  CodeReferencesInstructions,
+  DesignResources,
+  Notes,
+} from "./customMDXComponents.jsx";
+
+<Meta isTemplate />
+
+<div
+  style={{
+    display: "flex",
+    flexDirection: "row",
+    justifyContent: "space-between",
+    gap: "1rem",
+    marginBottom: "2rem",
+  }}
+>
+
+<Title />
+</div>
+
+<div>
+  <ComponentMeta />
+</div>
+
+## Example
+
+<Primary />
+
+<Notes title="Notes" />
+
+<Stories title="Variants" includePrimary={false} />
+
+<DesignResources title="Design resources" />
+<CodeReferencesInstructions title="How to use" />

package/.storybook/addons/qgds-multi-code-panels/components/Panel.tsx

@@ -0,0 +1,231 @@
+import React, { memo, useState } from "react";
+
+import prettier from "prettier/standalone";
+import parserHtml from "prettier/parser-html";
+import {
+  AddonPanel,
+  TabsState,
+  P,
+  SyntaxHighlighter,
+} from "storybook/internal/components";
+import { useChannel, useStorybookApi } from "storybook/manager-api";
+import { useTheme } from "storybook/theming";
+
+interface PanelProps {
+  active?: boolean;
+}
+
+interface ShowTabs {
+  template?: boolean;
+  json?: boolean;
+  htmlstory?: boolean;
+  htmlcomponent?: boolean;
+  howtouse?: boolean;
+  notes?: boolean;
+}
+
+// Single interface for both incoming data and state
+interface PanelContent {
+  template: string;
+  htmlstory: string;
+  htmlcomponent: string;
+  json: any;
+  notes: string;
+  name: string;
+  partialname: string;
+  showPanel: boolean;
+  showTabs: ShowTabs;
+  metadata: any;
+}
+
+let lastCodeRefs: PanelContent | null = null;
+
+// Format code with Prettier
+const formatCode = async (code: string): Promise<string> => {
+  if (!code) return "";
+
+  try {
+    return await prettier.format(code, {
+      parser: "html",
+      plugins: [parserHtml],
+      printWidth: 120,
+      tabWidth: 2,
+      useTabs: false,
+      htmlWhitespaceSensitivity: "ignore",
+    });
+  } catch (error) {
+    console.warn("Failed to format:", error);
+    return code;
+  }
+};
+
+export const Panel: React.FC<PanelProps> = memo(function MyPanel({ active }) {
+  const api = useStorybookApi();
+  const storyId = api.getCurrentStoryData()?.id || "N/A";
+
+  const theme = useTheme();
+  const [content, setContent] = useState<PanelContent | null>(lastCodeRefs);
+
+  useChannel({
+    CODEREFS_UPDATE: async (data: PanelContent) => {
+      // If showPanel is false or no showTabs defined, clear the content
+      if (!data.showPanel || !data.showTabs) {
+        setContent(null);
+        lastCodeRefs = null;
+        return;
+      }
+
+      const [formattedTemplate, formattedHtmlStory, formattedHtmlComponent] =
+        await Promise.all([
+          formatCode(data.template),
+          formatCode(data.htmlstory),
+          formatCode(data.htmlcomponent),
+        ]);
+
+      const newContent = {
+        template: formattedTemplate,
+        htmlstory: formattedHtmlStory,
+        htmlcomponent: formattedHtmlComponent,
+        json: data.json,
+        notes: data.notes,
+        name: data.name,
+        partialname: data.partialname,
+        metadata: data.metadata,
+        showPanel: data.showPanel,
+        showTabs: data.showTabs,
+      };
+      setContent(newContent);
+      lastCodeRefs = newContent;
+    },
+  });
+
+  // Build visible tabs array
+  const buildTabs = () => {
+    if (!content) return [];
+
+    const tabs: React.ReactElement[] = [];
+
+    if (content.showTabs.htmlstory !== false) {
+      tabs.push(
+        <div
+          key="htmlstory"
+          id="htmlstory"
+          title="HTML (Story)"
+          color={theme.color.defaultText}
+        >
+          <div style={{ padding: "20px" }}>
+            <SyntaxHighlighter language="html" copyable={true}>
+              {content.htmlstory}
+            </SyntaxHighlighter>
+          </div>
+        </div>,
+      );
+    }
+
+    if (content.showTabs.htmlcomponent !== false) {
+      tabs.push(
+        <div
+          key="htmlcomponent"
+          id="htmlcomponent"
+          title="HTML (Component)"
+          color={theme.color.defaultText}
+        >
+          <div style={{ padding: "20px" }}>
+            <SyntaxHighlighter language="html" copyable={true}>
+              {content.htmlcomponent}
+            </SyntaxHighlighter>
+          </div>
+        </div>,
+      );
+    }
+
+    if (content.showTabs.template !== false) {
+      tabs.push(
+        <div
+          key="template"
+          id="template"
+          title="Handlebars"
+          color={theme.color.defaultText}
+        >
+          <div style={{ padding: "20px" }}>
+            <SyntaxHighlighter language="html" copyable={true}>
+              {content.template}
+            </SyntaxHighlighter>
+          </div>
+        </div>,
+      );
+    }
+
+    if (content.showTabs.json !== false) {
+      tabs.push(
+        <div
+          key="params"
+          id="params"
+          title="Data"
+          color={theme.color.defaultText}
+        >
+          <div style={{ padding: "20px" }}>
+            <SyntaxHighlighter language="json" copyable={true}>
+              {JSON.stringify(content.json, null, 2)}
+            </SyntaxHighlighter>
+          </div>
+        </div>,
+      );
+    }
+
+    if (content.showTabs.notes) {
+      tabs.push(
+        <div
+          key="notes"
+          id="notes"
+          title="Notes"
+          color={theme.color.defaultText}
+        >
+          <div style={{ padding: "20px" }}>
+            <P>{content.notes}</P>
+          </div>
+        </div>,
+      );
+    }
+
+    if (content.showTabs.howtouse) {
+      tabs.push(
+        <div
+          key="howtouse"
+          id="howtouse"
+          title="Use"
+          color={theme.color.defaultText}
+        >
+          <div style={{ padding: "20px" }}>
+            <SyntaxHighlighter language="typescript" copyable={true}>
+              {`const data = ${JSON.stringify(content.json, undefined, 2)}; \n\nconst html = Handlebars.compile(\`{{> ${content.partialname} }}\`)(data);`}
+            </SyntaxHighlighter>
+          </div>
+        </div>,
+      );
+    }
+
+    return tabs;
+  };
+
+  const tabs = buildTabs();
+  const initialTab = tabs.length > 0 ? tabs[0].props.id : "template";
+
+  return (
+    <AddonPanel active={active ?? false}>
+      {content === null || tabs.length === 0 ? (
+        <div style={{ padding: "20px", color: "#999" }}>
+          Code references are disabled for this story.
+        </div>
+      ) : (
+        <TabsState
+          initial={initialTab}
+          backgroundColor={theme.background.hoverable}
+          key={`story-codetabs-${storyId}`}
+        >
+          {tabs}
+        </TabsState>
+      )}
+    </AddonPanel>
+  );
+});

package/.storybook/addons/qgds-multi-code-panels/constants.js

@@ -0,0 +1,8 @@
+export const ADDON_ID = "qgds-code-tabs";
+export const PANEL_ID = `${ADDON_ID}/panel`;
+export const KEY = `my-addon`;
+
+export const EVENTS = {
+  RESULT: `${ADDON_ID}/result`,
+  REQUEST: `${ADDON_ID}/request`,
+};

package/.storybook/addons/qgds-multi-code-panels/manager.tsx

@@ -0,0 +1,15 @@
+import React from "react";
+import { addons, types } from "storybook/manager-api";
+import { ADDON_ID, PANEL_ID } from "./constants";
+import { Panel } from "./components/Panel";
+
+// Register the addon
+addons.register(ADDON_ID, (api) => {
+  // Register a panel on each story view
+  addons.add(PANEL_ID, {
+    type: types.PANEL,
+    title: "Code References",
+    match: ({ viewMode }) => viewMode === "story",
+    render: ({ active }) => active && <Panel active={active} />,
+  });
+});

package/.storybook/addons/qgds-multi-code-panels/preset.js

@@ -0,0 +1,12 @@
+// This file is loaded during Storybook's Node.js configuration phase
+// It must not contain JSX or browser-only code
+
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function managerEntries(entry = []) {
+  return [...entry, join(__dirname, "./manager.tsx")];
+}

package/.storybook/codeRefsDecorator.js

@@ -0,0 +1,87 @@
+import { useEffect } from "storybook/preview-api";
+import { addons } from "storybook/preview-api";
+import Handlebars from "handlebars";
+
+/**
+ * Channel Communication Decorator
+ *
+ * Establishes a channel connection between the Storybook preview (inner iframe)
+ * and Storybook manager (outer frame) to send coderefs data to the
+ * "Code References" panel whenever a story is rendered or updated.
+ *
+ * @fires CODEREFS_UPDATE - Emits payload to manager with template, json, html, name, notes, and metadata
+ */
+export const withCodeRefs = (Story, context) => {
+  const { args, parameters } = context;
+
+  const coderefs = parameters.coderefs || {};
+  const metadata = coderefs?.metadata || {};
+  const storyArgs = coderefs?.args || args;
+
+  useEffect(() => {
+    const channel = addons.getChannel();
+
+    // If coderefs.show is explicitly false, send "hide" signal and exit
+    if (coderefs.show === false) {
+      channel.emit("CODEREFS_UPDATE", { showPanel: false });
+      return;
+    }
+
+    // Default tabs to show
+    const showtabs = {
+      htmlstory: coderefs.tabs?.htmlstory !== false,
+      htmlcomponent: coderefs.tabs?.htmlcomponent !== false,
+      json: coderefs.tabs?.json !== false,
+      template: coderefs.tabs?.template !== false,
+      howtouse: coderefs.tabs?.howtouse !== false,
+      notes: coderefs.tabs?.notes !== undefined,
+    };
+
+    // Check if any tabs are visible
+    const hasVisibleTabs = Object.values(showtabs).some(Boolean);
+
+    // If no tabs to show, send "hide" signal and exit
+    if (!hasVisibleTabs) {
+      channel.emit("CODEREFS_UPDATE", { showPanel: false });
+      return;
+    }
+
+    // Get the story's rendered HTML
+
+    // Full Story HTML
+    const htmlstoryContent = Story(args, context);
+
+    // Component only HTML
+    const hbspartial = Handlebars.partials[coderefs.partialname] || false;
+
+    if (!hbspartial) {
+      console.warn(
+        `[CODEREFS] Partial "${coderefs.partialname}" not found in Handlebars partials.`,
+      );
+    }
+
+    const htmlcomponentContent =
+      typeof hbspartial === "string"
+        ? Handlebars.compile(hbspartial)(args)
+        : "Missing partialname in story config, or component does use a handlebars template.";
+
+    // Data we're sending from preview frame to manager frame
+    const payload = {
+      showPanel: true,
+      showTabs: showtabs,
+      template: hbspartial || "No template available",
+      json: storyArgs,
+      htmlstory: htmlstoryContent,
+      htmlcomponent: htmlcomponentContent,
+      notes: coderefs.tabs?.notes || "Nil",
+      name: context.name || "Unknown",
+      partialname: coderefs.partialname || "Unknown",
+      metadata: metadata,
+    };
+
+    console.log("[PREVIEW] Sending CODEREFS_UPDATE:", payload);
+    channel.emit("CODEREFS_UPDATE", payload);
+  }, [args, parameters.coderefs]);
+
+  return Story();
+};