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

package/tools/lib/extract-react-props.mjs

@@ -0,0 +1,148 @@
+import {
+  matchBracket,
+  splitTopLevel,
+  splitTopLevelFirst,
+  stripBlockComments,
+  stripLineComments,
+} from "./split-balanced.mjs"
+
+/**
+ * This repo's oxfmt style omits semicolons entirely, so a type alias has no
+ * terminator to search for — parses `A & B & { ... }` as a sequence of terms
+ * (bare references or balanced `{...}` object literals) joined by top-level
+ * `&`, stopping as soon as no further `&` follows a term.
+ */
+function parseIntersectionTerms(text, startIndex) {
+  const terms = []
+  let i = startIndex
+
+  while (true) {
+    while (i < text.length && /\s/.test(text[i])) i++
+    if (i >= text.length) break
+
+    if (text[i] === "{") {
+      const close = matchBracket(text, i)
+      if (close === -1) {
+        terms.push(text.slice(i))
+        i = text.length
+        break
+      }
+      terms.push(text.slice(i, close + 1))
+      i = close + 1
+    } else {
+      const referenceMatch = text.slice(i).match(/^[A-Za-z_$][A-Za-z0-9_$.]*(?:<[^>{}]*>)?/)
+      if (!referenceMatch) break
+      terms.push(referenceMatch[0])
+      i += referenceMatch[0].length
+    }
+
+    let lookahead = i
+    while (lookahead < text.length && /\s/.test(text[lookahead])) lookahead++
+    if (text[lookahead] === "&") {
+      i = lookahead + 1
+    } else {
+      break
+    }
+  }
+
+  return terms
+}
+
+/**
+ * Regex/bracket-based extraction (deliberately not the TypeScript compiler
+ * API — see notes/ComponentToolingPlan.md's "Reuse by external tooling"
+ * deviation note: TS 7's compiler API dropped the classic
+ * createSourceFile/SyntaxKind surface this would have needed). Same rigor
+ * tier as the Twig extractor below: good enough for this codebase's
+ * consistently-flat, one-member-per-line prop type style, not a full parser.
+ *
+ * @returns {{
+ *   props: { name: string, optional: boolean }[],
+ *   inherited: string[],
+ *   hasChildren: boolean,
+ * } | null} null if no `type ${typeName} = ...` / `interface ${typeName}` is found.
+ */
+export function extractTsTypeMembers(text, typeName) {
+  const cleaned = stripLineComments(stripBlockComments(text))
+
+  const aliasMatch = cleaned.match(new RegExp(`\\btype\\s+${typeName}\\s*=\\s*`))
+  const interfaceMatch = cleaned.match(new RegExp(`\\binterface\\s+${typeName}\\s*`))
+
+  let terms
+  if (aliasMatch) {
+    terms = parseIntersectionTerms(cleaned, aliasMatch.index + aliasMatch[0].length)
+  } else if (interfaceMatch) {
+    const openBrace = cleaned.indexOf("{", interfaceMatch.index + interfaceMatch[0].length)
+    if (openBrace === -1) return null
+    const closeBrace = matchBracket(cleaned, openBrace)
+    if (closeBrace === -1) return null
+    terms = [cleaned.slice(openBrace, closeBrace + 1)]
+  } else {
+    return null
+  }
+
+  const props = []
+  const inherited = []
+  let hasChildren = false
+
+  for (const term of terms) {
+    const trimmed = term.trim()
+    const objectMatch = trimmed.match(/^\{([\s\S]*)\}$/)
+
+    if (objectMatch) {
+      for (const rawLine of objectMatch[1].split("\n")) {
+        const line = rawLine.trim().replace(/,$/, "")
+        if (!line) continue
+        const memberMatch = line.match(/^(?:readonly\s+)?([a-zA-Z_$][a-zA-Z0-9_$]*)(\?)?\s*:\s*.+$/)
+        if (!memberMatch) continue
+        props.push({ name: memberMatch[1], optional: memberMatch[2] === "?" })
+      }
+      continue
+    }
+
+    // A bare type reference in the intersection (PropsWithChildren, a native
+    // ComponentPropsWithoutRef<...>, or another locally-defined *Props type)
+    // — treated as inherited/extended, not diffed member-by-member.
+    const nameMatch = trimmed.match(/^([A-Za-z_$][A-Za-z0-9_$.]*)/)
+    if (nameMatch?.[1] === "PropsWithChildren") hasChildren = true
+    inherited.push(trimmed)
+  }
+
+  return { props, inherited, hasChildren }
+}
+
+const QUOTED_RE = /^'([^']*)'$|^"([^"]*)"$/
+
+/**
+ * Extracts destructured-parameter default values from a component's function
+ * signature, e.g. `const Card = ({ reversed = null, block = false }: CardProps) => ...`.
+ *
+ * @returns {Map<string, string>} prop name -> raw default-value source text
+ * (quotes stripped for plain string literals).
+ */
+export function extractDestructuredDefaults(text, componentName) {
+  const cleaned = stripLineComments(stripBlockComments(text))
+  const defaults = new Map()
+
+  const fnMatch =
+    cleaned.match(new RegExp(`\\b(?:const|function)\\s+${componentName}\\s*=?\\s*\\(\\s*\\{`)) ||
+    cleaned.match(new RegExp(`\\bfunction\\s+${componentName}\\s*\\(\\s*\\{`))
+  if (!fnMatch) return defaults
+
+  const openBrace = fnMatch.index + fnMatch[0].length - 1
+  const closeBrace = matchBracket(cleaned, openBrace)
+  if (closeBrace === -1) return defaults
+
+  const inner = cleaned.slice(openBrace + 1, closeBrace)
+  for (const binding of splitTopLevel(inner, [","])) {
+    const eq = splitTopLevelFirst(binding, "=")
+    if (!eq) continue
+    const name = eq[0].trim()
+    const value = eq[1].trim()
+    if (!/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name)) continue
+    const quoted = value.match(QUOTED_RE)
+    defaults.set(name, quoted ? (quoted[1] ?? quoted[2]) : value)
+  }
+
+  return defaults
+}

package/tools/lib/extract-twig-props.mjs

@@ -0,0 +1,124 @@
+const TWIG_BUILTINS = new Set([
+  "loop",
+  "true",
+  "false",
+  "null",
+  "_self",
+  "_context",
+  "_charset",
+  "create_attribute", // Drupal-Twig extension function, not a variable
+])
+
+const KEYWORD_TOKENS = new Set([
+  "not",
+  "and",
+  "or",
+  "is",
+  "in",
+  "b-and",
+  "b-or",
+  "b-xor",
+  "empty",
+  "defined",
+  "same",
+  "as",
+  "matches",
+  "starts",
+  "with",
+  "ends",
+])
+
+/**
+ * Extracts variable-reference identifiers from a Twig expression: strips
+ * quoted string contents first (so `'mx-tag--dismissible'` doesn't leak
+ * "mx"/"tag"/"dismissible" as fake refs), then excludes any identifier
+ * immediately preceded by `.` or `|` (a property/method/filter name, not a
+ * variable — e.g. `addClass`/`join`/`trim` in `attributes.addClass(...)`).
+ */
+function identifiersIn(expr) {
+  const withoutStrings = expr.replace(/'[^']*'|"[^"]*"/g, match => " ".repeat(match.length))
+  return (withoutStrings.match(/(?<![.|a-zA-Z0-9_])[a-zA-Z_][a-zA-Z0-9_]*/g) ?? []).filter(
+    id => !TWIG_BUILTINS.has(id) && !KEYWORD_TOKENS.has(id),
+  )
+}
+
+/**
+ * Regex-based Twig variable extraction (per plan — same rigor tier as the
+ * historical prior art it explicitly improves on): builds a "locally
+ * defined" set from `{% set %}` targets, loop variables, and macro params,
+ * then subtracts it from every identifier referenced via `{{ }}`/`{% if %}`/
+ * `{% for … in EXPR %}`, so computed locals aren't misreported as props.
+ *
+ * The `{% set attributes = (attributes ?? create_attribute()) %}` idiom is
+ * Drupal/Twig plumbing with no React equivalent by design — excluded
+ * entirely rather than flagged as a twig-only prop.
+ *
+ * @returns {{
+ *   props: Set<string>,
+ *   defaults: Map<string, string>,
+ * }}
+ */
+export function extractTwigProps(text) {
+  const locallyDefined = new Set()
+  const referenced = new Set()
+  const defaults = new Map()
+
+  let match
+
+  // {% set name = ... %} — LHS is local; RHS may still reference real props.
+  const setRe = /\{%\s*set\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*([\s\S]*?)%\}/g
+  while ((match = setRe.exec(text))) {
+    locallyDefined.add(match[1])
+    const rhs = match[2]
+    const selfReferencing = new RegExp(
+      `^\\(?\\s*${match[1]}\\s*(?:\\?\\?|or)\\s*create_attribute\\(\\)\\s*\\)?$`,
+    )
+    if (selfReferencing.test(rhs.trim())) continue // the attributes-idiom — not a real prop
+    for (const id of identifiersIn(rhs)) referenced.add(id)
+  }
+
+  // {% for item in items %} / {% for key, item in items %}
+  const forRe =
+    /\{%\s*for\s+([a-zA-Z_][a-zA-Z0-9_]*)(?:\s*,\s*([a-zA-Z_][a-zA-Z0-9_]*))?\s+in\s+([\s\S]*?)%\}/g
+  while ((match = forRe.exec(text))) {
+    locallyDefined.add(match[1])
+    if (match[2]) locallyDefined.add(match[2])
+    for (const id of identifiersIn(match[3])) referenced.add(id)
+  }
+
+  // {% macro name(a, b) %}
+  const macroRe = /\{%\s*macro\s+[a-zA-Z_][a-zA-Z0-9_]*\s*\(([^)]*)\)/g
+  while ((match = macroRe.exec(text))) {
+    for (const param of match[1].split(",")) {
+      const name = param.trim().split(/\s*=/)[0]
+      if (name) locallyDefined.add(name)
+    }
+  }
+
+  // {% if EXPR %} / {% elseif EXPR %}
+  const ifRe = /\{%\s*(?:if|elseif)\s+([\s\S]*?)%\}/g
+  while ((match = ifRe.exec(text))) {
+    for (const id of identifiersIn(match[1])) referenced.add(id)
+  }
+
+  // {{ EXPR }} — the leading identifier is the referenced variable; `|default(...)`
+  // right after it also gives us a default value.
+  const printRe =
+    /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)((?:\.[a-zA-Z_][a-zA-Z0-9_]*|\|[a-zA-Z_][a-zA-Z0-9_]*(?:\([^)]*\))?)*)/g
+  while ((match = printRe.exec(text))) {
+    referenced.add(match[1])
+    const defaultMatch = match[2].match(/\|default\(([^)]*)\)/)
+    if (defaultMatch) {
+      const value = defaultMatch[1].trim()
+      const quoted = value.match(/^'([^']*)'$|^"([^"]*)"$/)
+      defaults.set(match[1], quoted ? (quoted[1] ?? quoted[2]) : value)
+    }
+  }
+
+  // attr.addClass(...) / attr.setAttribute(...) style chains outside {{ }},
+  // e.g. `{% set attributes = attributes.addClass(...) %}` already covered
+  // above via the set-RHS scan; nothing extra needed here.
+
+  const props = new Set([...referenced].filter(id => !locallyDefined.has(id)))
+  return { props, defaults }
+}

package/tools/lib/naming.mjs

@@ -0,0 +1,53 @@
+/**
+ * Pure name-derivation helpers for the component scaffolder. Deliberately not
+ * reusing src/Utility/utilities (DOM-id/anchor generation is a different
+ * problem domain) — these only ever operate on the PascalName argument.
+ */
+
+const PASCAL_CASE_RE = /^[A-Z][A-Za-z0-9]*$/
+
+export function assertPascalCase(name) {
+  if (!PASCAL_CASE_RE.test(name)) {
+    throw new Error(
+      `Invalid component name "${name}" — must be PascalCase, matching ${PASCAL_CASE_RE} (e.g. "SocialShare").`,
+    )
+  }
+}
+
+export function pascalToKebab(pascal) {
+  return pascal
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase()
+}
+
+export function pascalToCamel(pascal) {
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1)
+}
+
+const VALID_CATEGORIES = ["Atom", "Component", "Form", "Layout"]
+
+export function assertValidCategory(category) {
+  if (!VALID_CATEGORIES.includes(category)) {
+    throw new Error(
+      `Invalid category "${category}" — must be one of: ${VALID_CATEGORIES.join(", ")}.`,
+    )
+  }
+}
+
+/**
+ * @param {{ prefix: string, category?: string, pascal: string }} args
+ */
+export function deriveNames({ prefix, category, pascal }) {
+  assertPascalCase(pascal)
+  const kebab = pascalToKebab(pascal)
+  const camel = pascalToCamel(pascal)
+  return {
+    pascal,
+    kebab,
+    camel,
+    category,
+    className: `${prefix}-${kebab}`,
+    tagName: `${prefix}-${kebab}`,
+  }
+}

package/tools/lib/split-balanced.mjs

@@ -0,0 +1,139 @@
+/**
+ * Small bracket/string-aware text utilities shared by the classname and
+ * parity extractors. Deliberately not a real parser — just enough structural
+ * awareness (nesting depth, string/template-literal skipping) to avoid the
+ * classic regex failure mode of splitting on a comma or brace that's actually
+ * inside a nested object/array/string.
+ */
+
+const OPEN = { "(": ")", "[": "]", "{": "}" }
+const CLOSE = new Set(Object.values(OPEN))
+
+/**
+ * Walks `text` tracking bracket depth and string/template-literal state.
+ * Calls `onChar(index, char, depth, inString)` for every character where
+ * `inString` is truthy while inside a quoted/template string (including
+ * `${...}` interpolation holes, which drop back to code context).
+ */
+function scan(text, onChar) {
+  const stack = []
+  const templateResume = [] // quote char to resume once the current ${...} hole closes
+  let quote = null // ', ", ` — the string is skipped except for `` ` `` interpolation holes
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i]
+    const prev = text[i - 1]
+
+    if (quote) {
+      if (quote === "`" && char === "$" && text[i + 1] === "{") {
+        templateResume.push(quote)
+        quote = null // entering an interpolation hole — back to code context
+        stack.push("${")
+        onChar(i, char, stack.length, true)
+        i++ // consume the `{` too
+        onChar(i, text[i], stack.length, false)
+        continue
+      }
+      if (char === quote && prev !== "\\") {
+        quote = null
+      }
+      onChar(i, char, stack.length, true)
+      continue
+    }
+
+    if (stack.at(-1) === "${" && char === "}") {
+      stack.pop()
+      quote = templateResume.pop() ?? null // resume the enclosing template literal, if any
+      onChar(i, char, stack.length, false)
+      continue
+    }
+
+    if (char === "'" || char === '"' || char === "`") {
+      quote = char
+      onChar(i, char, stack.length, true)
+      continue
+    }
+
+    if (char in OPEN) {
+      stack.push(char)
+      onChar(i, char, stack.length, false)
+      continue
+    }
+
+    if (CLOSE.has(char)) {
+      stack.pop()
+      onChar(i, char, stack.length, false)
+      continue
+    }
+
+    onChar(i, char, stack.length, false)
+  }
+}
+
+/**
+ * Splits `text` on any of `separators` (single characters), only when at
+ * bracket-depth 0 and outside a string/template literal. Returns trimmed,
+ * non-empty segments.
+ */
+export function splitTopLevel(text, separators) {
+  const sepSet = new Set(separators)
+  const segments = []
+  let start = 0
+
+  scan(text, (index, char, depth, inString) => {
+    if (!inString && depth === 0 && sepSet.has(char)) {
+      segments.push(text.slice(start, index))
+      start = index + 1
+    }
+  })
+  segments.push(text.slice(start))
+
+  return segments.map(segment => segment.trim()).filter(Boolean)
+}
+
+/**
+ * Splits `text` at the *first* top-level occurrence of `char` (depth 0,
+ * outside strings). Returns `[before, after]`, or `null` if not found —
+ * used for single-level ternary parsing (`cond ? a : b`) where a plain
+ * `splitTopLevel` would also break on `:`/`?` inside a nested ternary.
+ */
+export function splitTopLevelFirst(text, char) {
+  let foundIndex = -1
+  scan(text, (index, ch, depth, inString) => {
+    if (foundIndex === -1 && !inString && depth === 0 && ch === char) {
+      foundIndex = index
+    }
+  })
+  if (foundIndex === -1) return null
+  return [text.slice(0, foundIndex), text.slice(foundIndex + 1)]
+}
+
+/**
+ * Given the index of an opening bracket character, returns the index of its
+ * matching closing bracket, or -1 if unbalanced.
+ */
+export function matchBracket(text, openIndex) {
+  const openChar = text[openIndex]
+  if (!(openChar in OPEN)) return -1
+  const closeChar = OPEN[openChar]
+
+  let depth = 0
+  let result = -1
+  scan(text.slice(openIndex), (index, char, _depth, inString) => {
+    if (result !== -1 || inString) return
+    if (char === openChar) depth++
+    else if (char === closeChar) {
+      depth--
+      if (depth === 0) result = openIndex + index
+    }
+  })
+  return result
+}
+
+export function stripBlockComments(text) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, match => match.replace(/[^\n]/g, " "))
+}
+
+export function stripLineComments(text) {
+  return text.replace(/\/\/[^\n]*/g, match => " ".repeat(match.length))
+}

package/tools/lib/walk-components.mjs

@@ -0,0 +1,115 @@
+import { readdirSync } from "node:fs"
+import { extname, join, relative } from "node:path"
+
+const CATEGORIES = ["Atom", "Component", "Form", "Layout"]
+const EXCLUDED_DIRS = new Set(["__snapshots__", "images", "node_modules"])
+
+/**
+ * One entry per top-level `src/<Category>/<Pascal>/` component directory.
+ */
+export function walkComponentDirs(srcDir) {
+  const components = []
+  for (const category of CATEGORIES) {
+    const categoryDir = join(srcDir, category)
+    let entries
+    try {
+      entries = readdirSync(categoryDir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      components.push({ category, pascal: entry.name, dir: join(categoryDir, entry.name) })
+    }
+  }
+  return components
+}
+
+/**
+ * Classifies which convention-named files exist directly inside a component
+ * directory (non-recursive, except Elements/*.ts). Best-effort — picks the
+ * first match per slot rather than enforcing exactly-one.
+ */
+export function classifyComponentFiles({ dir, pascal }) {
+  let topLevel
+  try {
+    topLevel = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return {
+      twig: null,
+      css: [],
+      react: null,
+      webComponents: [],
+      storiesHtml: null,
+      storiesReact: null,
+      readme: null,
+    }
+  }
+
+  const files = topLevel.filter(e => e.isFile()).map(e => e.name)
+
+  const twig = files.find(f => f.endsWith(".twig")) ?? null
+  const css = files.filter(f => f.endsWith(".css") && !f.startsWith("_"))
+  const react = files.find(f => f === `${pascal}.tsx`) ?? null
+  const storiesHtml = files.find(f => f === `${pascal}.stories.ts`) ?? null
+  const storiesReact = files.find(f => f === `${pascal}.stories.tsx`) ?? null
+  const readme = files.find(f => f.toLowerCase() === "readme.md") ?? null
+
+  let webComponents = []
+  try {
+    const elementsDir = join(dir, "Elements")
+    webComponents = readdirSync(elementsDir)
+      .filter(f => f.endsWith(".ts"))
+      .map(f => join(elementsDir, f))
+  } catch {
+    // No Elements/ directory — not a Web Component.
+  }
+
+  return {
+    twig: twig ? join(dir, twig) : null,
+    css: css.map(f => join(dir, f)),
+    react: react ? join(dir, react) : null,
+    webComponents,
+    storiesHtml: storiesHtml ? join(dir, storiesHtml) : null,
+    storiesReact: storiesReact ? join(dir, storiesReact) : null,
+    readme: readme ? join(dir, readme) : null,
+  }
+}
+
+/**
+ * Recursively collects every file under `srcDir` matching one of `extensions`
+ * (e.g. [".tsx", ".ts", ".twig", ".css"]), skipping directories that never
+ * contain design-system source (snapshots, images, etc).
+ */
+export function walkFiles(srcDir, extensions) {
+  const results = []
+
+  function visit(dir) {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() && EXCLUDED_DIRS.has(entry.name)) continue
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        visit(full)
+      } else if (
+        extensions.includes(extname(entry.name)) ||
+        entry.name.endsWith(".stories.ts") ||
+        entry.name.endsWith(".stories.tsx")
+      ) {
+        results.push(full)
+      }
+    }
+  }
+
+  visit(srcDir)
+  return results
+}
+
+export function toPosixRelative(from, to) {
+  return relative(from, to).split("\\").join("/")
+}

package/tools/lib/write.mjs

@@ -0,0 +1,50 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { dirname, relative } from "node:path"
+
+/**
+ * Dry-run-aware file writer. Collects every planned write so the CLI can
+ * print a full file list (and, in dry-run mode, write nothing at all).
+ */
+export class Writer {
+  constructor({ dryRun = false, cwd = process.cwd() } = {}) {
+    this.dryRun = dryRun
+    this.cwd = cwd
+    this.planned = []
+  }
+
+  plan(absolutePath, contents) {
+    this.planned.push({ path: absolutePath, contents })
+  }
+
+  relativePaths() {
+    return this.planned.map(({ path }) => {
+      const rel = relative(this.cwd, path)
+      return rel.startsWith("..") ? path : rel
+    })
+  }
+
+  absolutePaths() {
+    return this.planned.map(({ path }) => path)
+  }
+
+  flush() {
+    if (this.dryRun) return
+    for (const { path, contents } of this.planned) {
+      mkdirSync(dirname(path), { recursive: true })
+      writeFileSync(path, contents)
+    }
+  }
+}
+
+/**
+ * Guards against clobbering an existing component directory. `--force` skips
+ * this check (the caller is still responsible for not force-overwriting
+ * files it doesn't intend to touch — this only guards directory existence).
+ */
+export function assertDestinationAvailable(dir, { force = false } = {}) {
+  if (!force && existsSync(dir)) {
+    throw new Error(
+      `Destination "${dir}" already exists. Pass --force to overwrite, or choose a different name.`,
+    )
+  }
+}

package/tools/lint-classnames.allowlist.json

@@ -0,0 +1,7 @@
+{
+  "classes": [],
+  "prefixes": ["mx-alert-"],
+  "reasons": {
+    "mx-alert-": "ClosableAlert.generatedId() builds an mx-alert-<random> string as an element ID (for aria-controls), not a CSS class — the mx- prefix here is an ID-namespacing convention, not a design-system class."
+  }
+}