@pnx-mixtape/mxds 0.0.30 → 0.1.0-rc.0

package/src/enums.ts

@@ -1,13 +1,15 @@
+/**
+ * Stable empty-array reference for use as a default prop/param value, avoiding a
+ * fresh `[]` on every render (satisfies react/no-object-type-as-default-prop).
+ * Typed as `never[]` so it is assignable to any `T[]` default parameter.
+ */
+export const EMPTY_ARRAY: never[] = []
+
 export enum Alignment {
   LEFT = "left",
   RIGHT = "right",
 }
 
-export enum IconAlignment {
-  START = "start",
-  END = "end",
-}
-
 export enum AsTags {
   DIV = "div",
   LI = "li",
@@ -16,15 +18,6 @@ export enum AsTags {
   SECTION = "section",
 }
 
-export enum SectionTags {
-  DIV = "div",
-  SECTION = "section",
-  HEADER = "header",
-  FOOTER = "footer",
-  ASIDE = "aside",
-  LIST = "ul",
-}
-
 export enum TextTags {
   P = "p",
   DIV = "div",
@@ -32,71 +25,29 @@ export enum TextTags {
   ITALIC = "em",
 }
 
-export enum HeadingLevels {
-  ONE = "h1",
-  TWO = "h2",
-  THREE = "h3",
-  FOUR = "h4",
-  FIVE = "h5",
-  P = "p",
-  DIV = "div",
-}
-
 export enum HeadingStyles {
   HEADLINE = "mx-headline",
-  SECTION = "mx-text--section-headline",
-  EMBELLISHED = "mx-text--embellished-headline",
-  TEXT = "mx-text--l",
-  XXL = "mx-heading--xxl",
-  XL = "mx-heading--xl",
-  L = "mx-heading--l",
-  M = "mx-heading--m",
-  S = "mx-heading--s",
-  XS = "mx-heading--xs",
+  EYEBROW = "mx-text--eyebrow",
+  EMBELLISHED = "mx-text--embellished",
   RESET = "mx-spacing--reset",
   RESETTOP = "mx-spacing--top-reset",
   RESETBOTTOM = "mx-spacing--bottom-reset",
 }
 
 export enum TextStyles {
-  HEADLINE = "mx-headline",
-  SECTION = "mx-text--section-headline",
-  EMBELLISHED = "mx-text--embellished-headline",
+  SECTION = "mx-text--eyebrow",
+  EMBELLISHED = "mx-text--embellished",
+  XXXL = "mx-text--xxxl",
+  XXL = "mx-text--xxl",
   XL = "mx-text--xl",
   L = "mx-text--l",
   M = "mx-text--m",
   S = "mx-text--s",
   XS = "mx-text--xs",
-}
-
-export enum LinkStyles {
-  EXTERNAL = "external",
-  MORE = "more",
-}
-
-export enum AccordionStyles {
-  DIVIDED = "divided",
-}
-
-export enum AccordionTypes {
-  DEFAULT = "base",
-  MOBILE = "mobile",
-  DIV = "div",
-}
-
-export enum IconStyles {
-  PRIMARY = "primary",
-}
-
-export enum ButtonStyles {
-  PRIMARY = "primary",
-  TEXT = "text",
-}
-
-export enum ButtonSizes {
-  LARGE = "large",
-  MEDIUM = "medium",
-  SMALL = "small",
+  LEDE = "mx-text--lede",
+  PRIMARY = "mx-text--primary",
+  ACCENT = "mx-text--accent",
+  ALT = "mx-text--alt",
 }
 
 export enum Icons {
@@ -108,6 +59,7 @@ export enum Icons {
   CHEVRON_LEFT = "chevron-left",
   CHEVRON_RIGHT = "chevron-right",
   CHEVRON_UP = "chevron-up",
+  BLUESKY = "bluesky",
   CLOSE = "close",
   COLLAPSE = "collapse",
   DOWNLOAD = "download",
@@ -149,48 +101,6 @@ export enum Icons {
   QUESTION = "question",
 }
 
-export enum GridColumns {
-  DYNAMIC = "dynamic",
-  XS_2 = "xs-2-cols",
-  S_2 = "sm-2-cols",
-  M_2 = "md-2-cols",
-  M_3 = "md-3-cols",
-  L_3 = "lg-3-cols",
-  M_4 = "md-4-cols",
-  L_4 = "lg-4-cols",
-  XL_4 = "xl-4-cols",
-}
-
-export enum GridWidths {
-  ONE = "1",
-  TWO = "2",
-  THREE = "3",
-  FOUR = "4",
-  FIVE = "5",
-  SIX = "6",
-  SEVEN = "7",
-  EIGHT = "8",
-  NINE = "9",
-  TEN = "10",
-  ELEVEN = "11",
-  TWELVE = "12",
-}
-
-export enum SectionStyles {
-  S = "s",
-  M = "m",
-  L = "l",
-  XL = "xl",
-  TOP_S = "top-s",
-  TOP_M = "top-m",
-  TOP_L = "top-l",
-  TOP_XL = "top-xl",
-  BOTTOM_S = "bottom-s",
-  BOTTOM_M = "bottom-m",
-  BOTTOM_L = "bottom-l",
-  BOTTOM_XL = "bottom-xl",
-}
-
 export enum PageWidths {
   NARROW = "narrow",
   FEATURE = "feature",
@@ -202,30 +112,12 @@ export enum SectionFlow {
   GROUP = "group",
 }
 
-export enum MessageTypes {
-  INFO = "info",
-  WARNING = "warning",
-  ERROR = "error",
-  SUCCESS = "success",
-}
-
 export enum SidebarOrder {
   DEFAULT = "",
   REVERSE = "sidebar-rev",
   REVERSE_L = "sidebar-rev-lg",
 }
 
-export enum TileSizes {
-  SMALL = "small",
-  MEDIUM = "medium",
-  LARGE = "large",
-}
-
-export enum DialogStyles {
-  CENTER = "center",
-  FULL = "fullwidth",
-}
-
 export enum BackgroundStyles {
   PRIMARY = "primary",
   ACCENT = "accent",
@@ -233,6 +125,7 @@ export enum BackgroundStyles {
   REVERSE = "reverse",
   RESET = "reset",
   BOX = "box",
+  IMAGE = "image",
 }
 
 export enum TableStyles {
@@ -252,7 +145,6 @@ export enum TabStyles {
   DEFAULT = "default",
   CENTERED = "centered",
   LINED = "lined",
-  SAME_HEIGHT = "same-height",
 }
 
 export enum SocialShareTypes {

package/src/react.ts

@@ -1,9 +1,11 @@
+export * from "./enums"
 export {
   default as ImageComponentProvider,
   useImageComponent,
 } from "./Utility/Context/ImageComponent"
 export { default as LinkComponentProvider, useLinkComponent } from "./Utility/Context/LinkComponent"
 export { default as Heading } from "./Atom/Heading/Heading"
+export { default as DefinitionList, DefinitionListItem } from "./Atom/DefinitionList/DefinitionList"
 export { default as Media } from "./Atom/Media/Media"
 export { default as Link } from "./Atom/Link/Link"
 export { default as Text } from "./Atom/Text/Text"
@@ -33,12 +35,17 @@ export { default as FormLabel } from "./Form/Label/FormLabel"
 export { default as FormRadio, Radio } from "./Form/Radio/FormRadio"
 export { default as FormSelect, Option } from "./Form/Select/FormSelect"
 export { default as FormText } from "./Form/TextInput/FormText"
+export { default as FormTextarea } from "./Form/Textarea/FormTextarea"
+export { default as FormItem } from "./Form/FormItem/FormItem"
 export { default as FormTitle } from "./Form/Form/FormTitle"
 export { default as Form } from "./Form/Form/Form"
 export { default as Icon } from "./Atom/Icon/Icon"
 export { default as Grid } from "./Layout/Grid/Grid"
 export { default as Page } from "./Layout/Page/Page"
 export { default as HeroBanner } from "./Component/HeroBanner/HeroBanner"
+export { default as HeroBannerContent } from "./Component/HeroBanner/Components/HeroBannerContent"
+export { default as HeroBannerAside } from "./Component/HeroBanner/Components/HeroBannerAside"
+export { default as HeroSearch } from "./Component/HeroSearch/HeroSearch"
 export { default as Section } from "./Layout/Section/Section"
 export { default as SectionGrid } from "./Layout/Section/SectionGrid"
 export { default as LinkList, LinkListItem } from "./Component/LinkList/LinkList"
@@ -70,8 +77,23 @@ export { default as DropMenuItem } from "./Component/DropMenu/Components/DropMen
 export { default as ResultsBar } from "./Component/ResultsBar/ResultsBar"
 export { default as ResultsBarInfo } from "./Component/ResultsBar/Components/ResultsBarInfo"
 export { default as ResultsBarSort } from "./Component/ResultsBar/Components/ResultsBarSort"
+export { default as Filters, useFiltersContext } from "./Component/Filters/Filters"
+export { default as FilterItem } from "./Component/Filters/FilterItem"
+export { default as Carousel } from "./Component/Carousel/Carousel"
+export { default as Popover } from "./Component/Popover/Popover"
+export { default as PopoverTrigger } from "./Component/Popover/Components/PopoverTrigger"
+export { default as SideNavigation } from "./Component/SideNavigation/SideNavigation"
+export { default as SideNavigationTree } from "./Component/SideNavigation/Components/SideNavigationTree"
+export { default as CookieConsent } from "./Component/CookieConsent/CookieConsent"
+export { default as Gallery } from "./Component/Gallery/Gallery"
+export { default as GalleryTrigger } from "./Component/Gallery/Components/GalleryTrigger"
+export { default as FormSearch } from "./Form/Search/FormSearch"
+export { default as Autocomplete } from "./Form/Autocomplete/Autocomplete"
+export { default as Masthead } from "./Layout/Masthead/Masthead"
+export { default as Sidebar } from "./Layout/Sidebar/Sidebar"
+export { default as Footer } from "./Layout/Footer/Footer"
+export { default as Header } from "./Layout/Header/Header"
 
 export { default as useLocalStorage } from "./Utility/Hooks/useLocalStorage"
 export { default as useMediaQuery } from "./Utility/Hooks/useMediaQuery"
-export { default as useToggle } from "./Utility/Hooks/useToggle"
 export { default as useUrlParams } from "./Utility/Hooks/useUrlParams"

package/src/tokens.js

@@ -1,3 +1,4 @@
+/* oxlint-disable approx-constant */
 export const global = {
   size: {
     xxxxs: "0.25em",
@@ -15,10 +16,25 @@ export const global = {
     uul: "5em",
     uuul: "5.5em",
   },
+  typeScales: {
+    minorSecond: 1.067,
+    majorSecond: 1.125,
+    minorThird: 1.2,
+    majorThird: 1.25,
+    perfectFourth: 1.333,
+    augmentedFourth: 1.414,
+    perfectFifth: 1.5,
+    goldenRatio: 1.618,
+  },
+  colour: {
+    primary: "hsl(223 100% 50%)",
+    accent: "hsl(60, 94%, 68%)",
+  },
 }
 
 export default {
   breakpoint: {
+    xxs: "320px",
     xs: "420px",
     s: "540px",
     m: "720px",
@@ -31,11 +47,11 @@ export default {
   },
   colour: {
     primary: {
-      colour: "hsl(223 100% 50%)",
+      colour: global.colour.primary,
       scheme: "dark",
     },
     accent: {
-      colour: "hsl(60, 94%, 68%)",
+      colour: global.colour.accent,
       scheme: "light",
     },
     main: {
@@ -44,6 +60,7 @@ export default {
       fgAlt: "hsl(60 30% 20%)",
       bgAlt: "hsl(60 30% 95%)",
       border: "hsl(60 5% 85%)",
+      link: global.colour.primary,
       scheme: "light",
     },
     reverse: {
@@ -52,6 +69,7 @@ export default {
       fgAlt: "hsl(60 5% 60%)",
       bgAlt: "hsl(60 0% 5%)",
       border: "hsl(60 0% 20%)",
+      link: "hsl(223, 100%, 95%)",
       scheme: "dark",
     },
     info: "hsl(223 100% 50%)",
@@ -71,8 +89,8 @@ export default {
       bold: 700,
     },
     size: {
-      ratioSmall: 1.125,
-      ratio: 1.25,
+      ratioSmall: global.typeScales.minorThird,
+      ratio: global.typeScales.augmentedFourth,
       basePx: "16px",
       diff: 0.3,
     },
@@ -113,7 +131,7 @@ export default {
     outline: {
       width: "2px",
       style: "solid",
-      colour: "hsl(223 100% 50%)",
+      colour: global.colour.primary,
     },
     radius: {
       m: "4px",

package/tools/audit-parity.aliases.json

@@ -0,0 +1,5 @@
+{
+  "to": "href",
+  "current": "aria-current",
+  "children": "content"
+}

package/tools/audit-parity.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * Cross-checks React props against Twig template variables (and, where a
+ * same-named type exists, @pnx-mixtape/ids-shape) for the other repeating
+ * bug shape from notes/FutureTooling.md: React/Twig prop divergence on the
+ * same logical component.
+ *
+ * Usage:
+ *   node tools/audit-parity.mjs [--component <Name>] [--write] [--json] [--fail-on-undocumented]
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { parseArgs } from "node:util"
+
+import { classifyComponentFiles, walkComponentDirs } from "./lib/walk-components.mjs"
+import { extractDestructuredDefaults, extractTsTypeMembers } from "./lib/extract-react-props.mjs"
+import { extractTwigProps } from "./lib/extract-twig-props.mjs"
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..")
+const SRC_DIR = join(REPO_ROOT, "src")
+const ALIASES_PATH = join(REPO_ROOT, "tools", "audit-parity.aliases.json")
+const OUTPUT_PATH = join(REPO_ROOT, "docs", "ParityMatrix.md")
+const IDS_SHAPE_INDEX = join(REPO_ROOT, "node_modules", "@pnx-mixtape", "ids-shape", "index.ts")
+
+// React-only plumbing that never needs a Twig counterpart.
+const IGNORED_REACT_ONLY = new Set(["className", "children"])
+
+function loadAliases() {
+  if (!existsSync(ALIASES_PATH)) return {}
+  return JSON.parse(readFileSync(ALIASES_PATH, "utf8"))
+}
+
+function resolveAliasSet(names, aliases) {
+  const resolved = new Set(names)
+  for (const name of names) {
+    if (aliases[name]) resolved.add(aliases[name])
+    for (const [a, b] of Object.entries(aliases)) {
+      if (b === name) resolved.add(a)
+    }
+  }
+  return resolved
+}
+
+function readIdsShapeMembers(pascal) {
+  if (!existsSync(IDS_SHAPE_INDEX)) return null
+  const text = readFileSync(IDS_SHAPE_INDEX, "utf8")
+  const exists = new RegExp(`\\bexport\\s+(?:type|interface)\\s+${pascal}\\b`).test(text)
+  if (!exists) return null
+  return extractTsTypeMembers(text, pascal)
+}
+
+function readReadme(path) {
+  return path && existsSync(path) ? readFileSync(path, "utf8") : ""
+}
+
+function isTwigOnlyDocumented(readme) {
+  if (/<!--\s*parity:twig-only\s*-->/.test(readme)) return true
+  const hasTwigHeading = /^##\s+Twig\b/m.test(readme)
+  const hasReactHeading = /^##\s+React\b/m.test(readme)
+  return hasTwigHeading && !hasReactHeading
+}
+
+function hasParitySubsection(readme) {
+  return /^###.*React.*Twig parity/im.test(readme)
+}
+
+function auditComponent({ category, pascal, dir }, aliases) {
+  const files = classifyComponentFiles({ dir, pascal })
+  const readme = readReadme(files.readme)
+
+  const reactText = files.react ? readFileSync(files.react, "utf8") : null
+  const twigText = files.twig ? readFileSync(files.twig, "utf8") : null
+
+  const reactMembers = reactText ? extractTsTypeMembers(reactText, `${pascal}Props`) : null
+  const reactDefaults = reactText ? extractDestructuredDefaults(reactText, pascal) : new Map()
+  const twigResult = twigText ? extractTwigProps(twigText) : null
+  const idsShapeMembers = readIdsShapeMembers(pascal)
+
+  const reactNames = new Set((reactMembers?.props ?? []).map(p => p.name))
+  if (reactMembers?.hasChildren) reactNames.add("children")
+  const twigNames = twigResult?.props ?? new Set()
+
+  const issues = []
+  let status = "N/A"
+
+  if (reactMembers && twigResult) {
+    status = "OK"
+    const twigOnlyOk = isTwigOnlyDocumented(readme)
+    const documented = hasParitySubsection(readme)
+
+    if (!twigOnlyOk) {
+      for (const name of twigNames) {
+        const aliasSet = resolveAliasSet([name], aliases)
+        if ([...aliasSet].some(n => reactNames.has(n))) continue
+        issues.push(`"${name}" is used in Twig but has no matching React prop`)
+      }
+    }
+
+    for (const name of reactNames) {
+      if (IGNORED_REACT_ONLY.has(name)) continue
+      const aliasSet = resolveAliasSet([name], aliases)
+      if ([...aliasSet].some(n => twigNames.has(n))) continue
+      issues.push(`"${name}" is a React prop but is not used in Twig`)
+    }
+
+    for (const [name, reactDefault] of reactDefaults) {
+      const twigDefault = twigResult.defaults.get(name)
+      if (twigDefault === undefined) continue
+      // Skip enum-namespaced values (e.g. "AsTags.DIV") — not directly comparable to a Twig literal.
+      if (/[.]/.test(reactDefault)) continue
+      if (reactDefault !== twigDefault) {
+        issues.push(
+          `default for "${name}" differs: React=${JSON.stringify(reactDefault)}, Twig=${JSON.stringify(twigDefault)}`,
+        )
+      }
+    }
+
+    if (issues.length > 0) status = documented ? "DOCUMENTED" : "FAIL"
+  }
+
+  return {
+    category,
+    pascal,
+    dir,
+    hasReact: Boolean(files.react),
+    hasTwig: Boolean(files.twig),
+    hasWebComponent: files.webComponents.length > 0,
+    hasIdsShape: Boolean(idsShapeMembers),
+    status,
+    issues,
+  }
+}
+
+function renderMarkdown(results) {
+  const lines = [
+    "# React ⇄ Twig Parity Matrix",
+    "",
+    "Generated by `tools/audit-parity.mjs` — do not hand-edit; regenerate with `pnpm audit-parity-write`.",
+    "",
+    "| Component | Category | React | Twig | Web Component | ids-shape | Status |",
+    "| --- | --- | --- | --- | --- | --- | --- |",
+  ]
+
+  const mark = value => (value ? "✅" : "—")
+
+  for (const r of results) {
+    lines.push(
+      `| ${r.pascal} | ${r.category} | ${mark(r.hasReact)} | ${mark(r.hasTwig)} | ${mark(r.hasWebComponent)} | ${mark(r.hasIdsShape)} | ${r.status} |`,
+    )
+  }
+
+  const withIssues = results.filter(r => r.issues.length > 0)
+  if (withIssues.length > 0) {
+    lines.push("", "## Details", "")
+    for (const r of withIssues) {
+      lines.push(`### ${r.pascal} (${r.status})`, "")
+      for (const issue of r.issues) lines.push(`- ${issue}`)
+      lines.push("")
+    }
+  }
+
+  return lines.join("\n") + "\n"
+}
+
+function main() {
+  const { values } = parseArgs({
+    options: {
+      component: { type: "string" },
+      write: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      "fail-on-undocumented": { type: "boolean", default: false },
+    },
+  })
+
+  const aliases = loadAliases()
+  let components = walkComponentDirs(SRC_DIR)
+  if (values.component) {
+    components = components.filter(c => c.pascal.toLowerCase() === values.component.toLowerCase())
+    if (components.length === 0) {
+      console.error(
+        `No component named "${values.component}" found under src/{Atom,Component,Form,Layout}.`,
+      )
+      process.exit(1)
+    }
+  }
+
+  const results = components
+    .map(c => auditComponent(c, aliases))
+    .sort((a, b) => a.category.localeCompare(b.category) || a.pascal.localeCompare(b.pascal))
+
+  if (values.json) {
+    console.log(JSON.stringify(results, null, 2))
+  } else {
+    const markdown = renderMarkdown(results)
+    if (values.write) {
+      writeFileSync(OUTPUT_PATH, markdown)
+      console.log(`Wrote ${results.length} component(s) to docs/ParityMatrix.md`)
+    } else {
+      console.log(markdown)
+    }
+  }
+
+  const failed = values["fail-on-undocumented"] && results.some(r => r.status === "FAIL")
+  process.exit(failed ? 1 : 0)
+}
+
+main()

package/tools/lib/barrel.mjs

@@ -0,0 +1,76 @@
+/**
+ * Insertion logic for src/elements.ts and src/react.ts. Both files are plain
+ * newline-separated export lists — no AST tool needed, just line splice/join
+ * with a duplicate guard, since these two files are the highest-risk-of-
+ * bad-merge spot in the whole scaffolder.
+ */
+
+const ELEMENTS_ANCHOR_RE = /^export \* from "\.\/Utility\/utilities"$/
+const REACT_HOOKS_ANCHOR_RE = /from "\.\/Utility\/Hooks\//
+
+function splitLines(text) {
+  const trailingNewline = text.endsWith("\n")
+  const lines = text.split("\n")
+  if (trailingNewline) lines.pop()
+  return { lines, trailingNewline }
+}
+
+function join(lines, trailingNewline) {
+  return lines.join("\n") + (trailingNewline ? "\n" : "")
+}
+
+/**
+ * @returns {{ text: string, insertedLine: string|null, alreadyExported: boolean }}
+ */
+export function addElementExport(text, { category, pascal }) {
+  const marker = `/${category}/${pascal}/`
+  const { lines, trailingNewline } = splitLines(text)
+
+  if (lines.some(line => line.includes(marker))) {
+    return { text, insertedLine: null, alreadyExported: true }
+  }
+
+  const anchorIndex = lines.findIndex(line => ELEMENTS_ANCHOR_RE.test(line))
+  if (anchorIndex === -1) {
+    throw new Error(
+      'Could not find the `export * from "./Utility/utilities"` anchor line in src/elements.ts',
+    )
+  }
+
+  const insertedLine = `export { default as ${pascal} } from "./${category}/${pascal}/Elements/${pascal}"`
+  lines.splice(anchorIndex, 0, insertedLine)
+
+  return { text: join(lines, trailingNewline), insertedLine, alreadyExported: false }
+}
+
+/**
+ * @returns {{ text: string, insertedLine: string|null, alreadyExported: boolean }}
+ */
+export function addReactExport(text, { category, pascal }) {
+  const marker = `/${category}/${pascal}/`
+  const { lines, trailingNewline } = splitLines(text)
+
+  if (lines.some(line => line.includes(marker))) {
+    return { text, insertedLine: null, alreadyExported: true }
+  }
+
+  const insertedLine = `export { default as ${pascal} } from "./${category}/${pascal}/${pascal}"`
+
+  const categoryPrefix = `from "./${category}/`
+  let lastCategoryIndex = -1
+  lines.forEach((line, index) => {
+    if (line.includes(categoryPrefix)) lastCategoryIndex = index
+  })
+
+  if (lastCategoryIndex !== -1) {
+    lines.splice(lastCategoryIndex + 1, 0, insertedLine)
+  } else {
+    const hooksAnchorIndex = lines.findIndex(line => REACT_HOOKS_ANCHOR_RE.test(line))
+    if (hooksAnchorIndex === -1) {
+      throw new Error("Could not find the hooks-block anchor in src/react.ts")
+    }
+    lines.splice(hooksAnchorIndex, 0, insertedLine)
+  }
+
+  return { text: join(lines, trailingNewline), insertedLine, alreadyExported: false }
+}