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

package/tools/lint-classnames.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * Cross-checks `mx-*` class usage (React JSX, Web Component classList calls,
+ * Twig templates, Storybook stories) against `.mx-*` CSS selectors actually
+ * defined under src/, catching the two repeating bug shapes from
+ * notes/FutureTooling.md: a class emitted with no matching CSS selector (or
+ * vice versa).
+ *
+ * Usage:
+ *   node tools/lint-classnames.mjs [--format text|github] [--strict]
+ */
+
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join, relative, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { parseArgs } from "node:util"
+
+import { walkFiles } from "./lib/walk-components.mjs"
+import {
+  extractCssDefinedClasses,
+  extractJsUsedClasses,
+  extractMixinInvocations,
+  extractMixinTemplates,
+  extractTwigUsedClasses,
+} from "./lib/extract-classnames.mjs"
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..")
+const SRC_DIR = join(REPO_ROOT, "src")
+const ALLOWLIST_PATH = join(REPO_ROOT, "tools", "lint-classnames.allowlist.json")
+const MX_PREFIX_RE = /^mx-/
+
+function levenshtein(a, b) {
+  const rows = a.length + 1
+  const cols = b.length + 1
+  const d = Array.from({ length: rows }, (_, i) => [i, ...Array(cols - 1).fill(0)])
+  for (let j = 0; j < cols; j++) d[0][j] = j
+  for (let i = 1; i < rows; i++) {
+    for (let j = 1; j < cols; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost)
+    }
+  }
+  return d[rows - 1][cols - 1]
+}
+
+function loadAllowlist() {
+  if (!existsSync(ALLOWLIST_PATH)) return { classes: [], prefixes: [], reasons: {} }
+  const allowlist = JSON.parse(readFileSync(ALLOWLIST_PATH, "utf8"))
+  const { classes = [], prefixes = [], reasons = {} } = allowlist
+  for (const entry of [...classes, ...prefixes]) {
+    if (!reasons[entry]) {
+      throw new Error(
+        `tools/lint-classnames.allowlist.json: entry "${entry}" has no matching "reasons" entry — every allowlisted class/prefix must have a reason.`,
+      )
+    }
+  }
+  return { classes, prefixes, reasons }
+}
+
+function isAllowlisted(className, allowlist) {
+  return (
+    allowlist.classes.includes(className) ||
+    allowlist.prefixes.some(prefix => className.startsWith(prefix))
+  )
+}
+
+function relPath(absPath) {
+  return relative(REPO_ROOT, absPath)
+}
+
+function collect() {
+  const definitions = new Map() // className -> { file, line }
+  const usages = [] // { className, file, line } | { prefix, suffix, file, line, raw }
+
+  // postcss-mixins can generate whole class families at build time (e.g.
+  // `@mixin icon chevron-left;` -> `.mx-icon--chevron-left`) that never
+  // appear as literal selector text — collect templates + invocations across
+  // ALL css files first (a definition and its invocations can live in
+  // different files) and synthesize the resulting classes before the normal
+  // literal-selector pass runs.
+  const mixinTemplates = new Map() // mixinName -> prefix[]
+  const mixinInvocations = [] // { mixinName, arg, file, line }
+
+  for (const file of walkFiles(SRC_DIR, [".css"])) {
+    const text = readFileSync(file, "utf8")
+    for (const { mixinName, prefix } of extractMixinTemplates(text)) {
+      if (!mixinTemplates.has(mixinName)) mixinTemplates.set(mixinName, [])
+      mixinTemplates.get(mixinName).push(prefix)
+    }
+    for (const { mixinName, arg, line } of extractMixinInvocations(text)) {
+      mixinInvocations.push({ mixinName, arg, file: relPath(file), line })
+    }
+  }
+
+  // Synthesized combinations are excluded from the stale-CSS check (below) —
+  // a generated utility matrix (e.g. 5 directions x 12 sizes) is expected to
+  // have a long tail unused *within this repo*, since these are consumed by
+  // downstream projects/content editors, not just mxds's own components.
+  const synthesized = new Set()
+
+  for (const { mixinName, arg, file, line } of mixinInvocations) {
+    for (const prefix of mixinTemplates.get(mixinName) ?? []) {
+      const name = `${prefix}${arg}`
+      if (!MX_PREFIX_RE.test(name)) continue
+      if (!definitions.has(name)) definitions.set(name, { file, line })
+      synthesized.add(name)
+    }
+  }
+
+  for (const file of walkFiles(SRC_DIR, [".css"])) {
+    const text = readFileSync(file, "utf8")
+    for (const { name, line } of extractCssDefinedClasses(text)) {
+      if (!MX_PREFIX_RE.test(name)) continue
+      if (!definitions.has(name)) definitions.set(name, { file: relPath(file), line })
+    }
+  }
+
+  for (const file of walkFiles(SRC_DIR, [".tsx", ".ts"])) {
+    const text = readFileSync(file, "utf8")
+    const { static: staticUsed, dynamic } = extractJsUsedClasses(text)
+    for (const [className, locs] of staticUsed) {
+      if (!MX_PREFIX_RE.test(className)) continue
+      for (const { line } of locs) usages.push({ className, file: relPath(file), line })
+    }
+    for (const { prefix, suffix, line, raw } of dynamic) {
+      if (!MX_PREFIX_RE.test(prefix)) continue
+      usages.push({ prefix, suffix, file: relPath(file), line, raw })
+    }
+  }
+
+  for (const file of walkFiles(SRC_DIR, [".twig"])) {
+    const text = readFileSync(file, "utf8")
+    const { static: staticUsed, dynamic } = extractTwigUsedClasses(text)
+    for (const [className, locs] of staticUsed) {
+      if (!MX_PREFIX_RE.test(className)) continue
+      for (const { line } of locs) usages.push({ className, file: relPath(file), line })
+    }
+    for (const { prefix, suffix, line, raw } of dynamic) {
+      if (!MX_PREFIX_RE.test(prefix)) continue
+      usages.push({ prefix, suffix, file: relPath(file), line, raw })
+    }
+  }
+
+  return { definitions, usages, synthesized }
+}
+
+function analyze({ definitions, usages, synthesized }, allowlist) {
+  const errors = []
+  const warnings = []
+  const referenced = new Set()
+
+  for (const usage of usages) {
+    if (usage.className) {
+      referenced.add(usage.className)
+      if (definitions.has(usage.className) || isAllowlisted(usage.className, allowlist)) continue
+
+      const suggestion = [...definitions.keys()]
+        .map(name => ({ name, distance: levenshtein(usage.className, name) }))
+        .filter(({ distance }) => distance <= 2)
+        .sort((a, b) => a.distance - b.distance)[0]
+
+      errors.push({
+        file: usage.file,
+        line: usage.line,
+        message: `class "${usage.className}" is used but has no matching CSS selector${suggestion ? ` (did you mean "${suggestion.name}"?)` : ""}`,
+      })
+    } else {
+      // Dynamic pattern — mark every definition it could plausibly produce as referenced.
+      let matched = false
+      for (const name of definitions.keys()) {
+        if (name.startsWith(usage.prefix) && name.endsWith(usage.suffix)) {
+          referenced.add(name)
+          matched = true
+        }
+      }
+      if (!matched && !isAllowlisted(usage.prefix, allowlist)) {
+        errors.push({
+          file: usage.file,
+          line: usage.line,
+          message: `dynamic class pattern "${usage.raw}" has no CSS selector matching prefix "${usage.prefix}"${usage.suffix ? ` / suffix "${usage.suffix}"` : ""}`,
+        })
+      }
+    }
+  }
+
+  for (const [className, { file, line }] of definitions) {
+    if (
+      referenced.has(className) ||
+      synthesized.has(className) ||
+      isAllowlisted(className, allowlist)
+    )
+      continue
+    warnings.push({
+      file,
+      line,
+      message: `class "${className}" is defined in CSS but never referenced (stale?)`,
+    })
+  }
+
+  errors.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)
+  warnings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line)
+
+  return { errors, warnings }
+}
+
+function printText(errors, warnings) {
+  for (const { file, line, message } of errors) console.log(`${file}:${line}  error  ${message}`)
+  for (const { file, line, message } of warnings)
+    console.log(`${file}:${line}  warning  ${message}`)
+  console.log(`\n${errors.length} error(s), ${warnings.length} warning(s)`)
+}
+
+function printGithub(errors, warnings) {
+  for (const { file, line, message } of errors)
+    console.log(`::error file=${file},line=${line}::${message}`)
+  for (const { file, line, message } of warnings)
+    console.log(`::warning file=${file},line=${line}::${message}`)
+}
+
+function main() {
+  const { values } = parseArgs({
+    options: {
+      format: { type: "string", default: "text" },
+      strict: { type: "boolean", default: false },
+    },
+  })
+
+  const allowlist = loadAllowlist()
+  const { errors, warnings } = analyze(collect(), allowlist)
+
+  if (values.format === "github") {
+    printGithub(errors, warnings)
+  } else {
+    printText(errors, warnings)
+  }
+
+  const failed = errors.length > 0 || (values.strict && warnings.length > 0)
+  process.exit(failed ? 1 : 0)
+}
+
+main()

package/tools/scaffold-component.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * Scaffold a new mxds component (React/Twig/Web-Component) following the
+ * conventions in docs/ComponentArchitecture.md.
+ *
+ * Usage:
+ *   node tools/scaffold-component.mjs <Category> <PascalName> [--react] [--webcomponent] [--twig]
+ *                                      [--description="..."] [--dry-run] [--force] [--prefix=mx]
+ *
+ *   node tools/scaffold-component.mjs --standalone --output=<dir> <PascalName> [--react] [--webcomponent] [--twig]
+ *                                      [--prefix=<project-prefix>] [--dry-run]
+ */
+
+import { parseArgs } from "node:util"
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { execFileSync } from "node:child_process"
+import { createInterface } from "node:readline/promises"
+
+import { assertPascalCase, assertValidCategory, deriveNames } from "./lib/naming.mjs"
+import { Writer, assertDestinationAvailable } from "./lib/write.mjs"
+import { addElementExport, addReactExport } from "./lib/barrel.mjs"
+import { twigTemplate } from "./templates/twig.mjs"
+import { cssTemplate } from "./templates/css.mjs"
+import { reactTemplate } from "./templates/react.mjs"
+import { webComponentTemplate } from "./templates/webComponent.mjs"
+import { entryTemplate } from "./templates/entry.mjs"
+import { storiesHtmlTemplate } from "./templates/storiesHtml.mjs"
+import { storiesReactTemplate } from "./templates/storiesReact.mjs"
+import { readmeTemplate } from "./templates/readme.mjs"
+import { figmaTemplate } from "./templates/figma.mjs"
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..")
+
+function usage() {
+  return `Usage:
+  node tools/scaffold-component.mjs <Category> <PascalName> [--react] [--webcomponent] [--twig]
+                                     [--description="..."] [--dry-run] [--force] [--prefix=mx]
+
+  node tools/scaffold-component.mjs --standalone --output=<dir> <PascalName> [--react] [--webcomponent] [--twig]
+                                     [--prefix=<project-prefix>] [--dry-run]
+
+<Category> must be one of: Atom, Component, Form, Layout`
+}
+
+function parseCliArgs(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      react: { type: "boolean", default: false },
+      webcomponent: { type: "boolean", default: false },
+      twig: { type: "boolean", default: false },
+      description: { type: "string" },
+      "dry-run": { type: "boolean", default: false },
+      force: { type: "boolean", default: false },
+      prefix: { type: "string", default: "mx" },
+      standalone: { type: "boolean", default: false },
+      output: { type: "string" },
+    },
+  })
+  return { values, positionals }
+}
+
+async function promptFor(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    return (await rl.question(question)).trim()
+  } finally {
+    rl.close()
+  }
+}
+
+/**
+ * Returns `current` if it's already set (validating it, same as before).
+ * Otherwise, in an interactive terminal, prompts until a valid value is
+ * given; in a non-interactive context (CI, piped input) throws immediately
+ * rather than hanging.
+ */
+async function resolveArg({ current, prompt, validate }) {
+  if (current) {
+    validate(current)
+    return current
+  }
+
+  if (!process.stdin.isTTY) {
+    throw new Error(`Missing required argument: ${prompt.replace(/:\s*$/, "")}`)
+  }
+
+  for (;;) {
+    const answer = await promptFor(prompt)
+    try {
+      validate(answer)
+      return answer
+    } catch (error) {
+      console.error(error.message)
+    }
+  }
+}
+
+function resolveStacks(values) {
+  const anyRequested = values.react || values.webcomponent || values.twig
+  return {
+    hasReact: anyRequested ? values.react : true,
+    hasWebComponent: anyRequested ? values.webcomponent : true,
+    hasTwig: anyRequested ? values.twig : true,
+  }
+}
+
+function planStandalone({ values, positionals }) {
+  if (!values.output) {
+    throw new Error("--standalone requires --output=<dir>")
+  }
+  const [pascal] = positionals
+  if (!pascal) {
+    throw new Error(`Missing <PascalName> argument.\n\n${usage()}`)
+  }
+
+  const stacks = resolveStacks(values)
+  const names = deriveNames({ prefix: values.prefix, pascal })
+  const outputDir = resolve(process.cwd(), values.output)
+
+  const writer = new Writer({ dryRun: values["dry-run"] })
+  const ctx = { ...names, ...stacks, description: values.description }
+
+  if (stacks.hasTwig) {
+    writer.plan(join(outputDir, `${names.kebab}.twig`), twigTemplate(ctx))
+  }
+  writer.plan(join(outputDir, `${names.kebab}.css`), cssTemplate(ctx))
+  if (stacks.hasReact) {
+    writer.plan(join(outputDir, `${names.pascal}.tsx`), reactTemplate(ctx))
+  }
+  if (stacks.hasWebComponent) {
+    writer.plan(join(outputDir, "Elements", `${names.pascal}.ts`), webComponentTemplate(ctx))
+    writer.plan(join(outputDir, `${names.kebab}.entry.js`), entryTemplate(ctx))
+  }
+
+  return { writer, barrelUpdates: [] }
+}
+
+function planComponent({ values, positionals }) {
+  const [category, pascal] = positionals
+  if (!category || !pascal) {
+    throw new Error(`Missing arguments.\n\n${usage()}`)
+  }
+  assertValidCategory(category)
+
+  const stacks = resolveStacks(values)
+  const names = deriveNames({ prefix: values.prefix, category, pascal })
+  const componentDir = join(REPO_ROOT, "src", category, pascal)
+
+  assertDestinationAvailable(componentDir, { force: values.force })
+
+  const writer = new Writer({ dryRun: values["dry-run"], cwd: REPO_ROOT })
+  const ctx = { ...names, ...stacks, description: values.description }
+
+  if (stacks.hasTwig) {
+    writer.plan(join(componentDir, `${names.kebab}.twig`), twigTemplate(ctx))
+    writer.plan(join(componentDir, `${pascal}.stories.ts`), storiesHtmlTemplate(ctx))
+  }
+  writer.plan(join(componentDir, `${names.kebab}.css`), cssTemplate(ctx))
+  if (stacks.hasReact) {
+    writer.plan(join(componentDir, `${pascal}.tsx`), reactTemplate(ctx))
+    writer.plan(join(componentDir, `${pascal}.stories.tsx`), storiesReactTemplate(ctx))
+    writer.plan(join(componentDir, `${pascal}.figma.ts`), figmaTemplate(ctx))
+  }
+  if (stacks.hasWebComponent) {
+    writer.plan(join(componentDir, "Elements", `${pascal}.ts`), webComponentTemplate(ctx))
+    writer.plan(join(componentDir, `${names.kebab}.entry.js`), entryTemplate(ctx))
+  }
+  writer.plan(join(componentDir, "README.md"), readmeTemplate(ctx))
+
+  const barrelUpdates = []
+
+  if (stacks.hasWebComponent) {
+    const elementsPath = join(REPO_ROOT, "src", "elements.ts")
+    const result = addElementExport(readFileSync(elementsPath, "utf8"), { category, pascal })
+    barrelUpdates.push({ path: elementsPath, ...result })
+  }
+
+  if (stacks.hasReact) {
+    const reactPath = join(REPO_ROOT, "src", "react.ts")
+    const result = addReactExport(readFileSync(reactPath, "utf8"), { category, pascal })
+    barrelUpdates.push({ path: reactPath, ...result })
+  }
+
+  return { writer, barrelUpdates }
+}
+
+function printPlan({ writer, barrelUpdates }, { dryRun }) {
+  console.log(`${dryRun ? "[dry-run] " : ""}Files:`)
+  for (const path of writer.relativePaths()) {
+    console.log(`  ${path}`)
+  }
+
+  if (barrelUpdates.length > 0) {
+    console.log("\nBarrel updates:")
+    for (const update of barrelUpdates) {
+      if (update.alreadyExported) {
+        console.log(`  ${update.path}: already exported, skipping`)
+      } else {
+        console.log(`  ${update.path}: + ${update.insertedLine}`)
+      }
+    }
+  }
+}
+
+/**
+ * Best-effort oxfmt pass over freshly written files so generated output
+ * matches this repo's formatting conventions immediately. Silently skipped
+ * if oxfmt isn't installed (e.g. when this script runs standalone inside a
+ * consuming project's node_modules that hasn't installed it).
+ */
+function formatWrittenFiles(paths) {
+  if (paths.length === 0) return
+  const oxfmtBin = join(REPO_ROOT, "node_modules", ".bin", "oxfmt")
+  if (!existsSync(oxfmtBin)) return
+  try {
+    execFileSync(oxfmtBin, paths, { stdio: "ignore" })
+  } catch {
+    // Best-effort only — formatting failures shouldn't block scaffolding.
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  const parsed = parseCliArgs(argv)
+
+  try {
+    if (parsed.values.standalone) {
+      parsed.positionals[0] = await resolveArg({
+        current: parsed.positionals[0],
+        prompt: "Component name (PascalCase, e.g. SocialShare): ",
+        validate: assertPascalCase,
+      })
+    } else {
+      parsed.positionals[0] = await resolveArg({
+        current: parsed.positionals[0],
+        prompt: "Category (Atom, Component, Form, or Layout): ",
+        validate: assertValidCategory,
+      })
+      parsed.positionals[1] = await resolveArg({
+        current: parsed.positionals[1],
+        prompt: "Component name (PascalCase, e.g. SocialShare): ",
+        validate: assertPascalCase,
+      })
+    }
+  } catch (error) {
+    console.error(`${error.message}\n\n${usage()}`)
+    process.exit(1)
+  }
+
+  const plan = parsed.values.standalone ? planStandalone(parsed) : planComponent(parsed)
+  const dryRun = parsed.values["dry-run"]
+
+  printPlan(plan, { dryRun })
+
+  if (dryRun) {
+    console.log("\n[dry-run] No files written.")
+    return
+  }
+
+  plan.writer.flush()
+
+  for (const update of plan.barrelUpdates) {
+    if (!update.alreadyExported) {
+      writeFileSync(update.path, update.text)
+    }
+  }
+
+  formatWrittenFiles(plan.writer.absolutePaths())
+
+  console.log("\nDone.")
+}
+
+main().catch(error => {
+  console.error(`\nError: ${error.message}`)
+  process.exit(1)
+})

package/tools/templates/css.mjs

@@ -0,0 +1,25 @@
+export const cssTemplate = ctx => {
+  const { pascal, className, hasWebComponent, tagName } = ctx
+
+  const hostBlock = hasWebComponent
+    ? `
+@layer design-system.defaults {
+  ${tagName} {
+    display: block;
+  }
+}
+`
+    : ""
+
+  return `/**
+ * ${pascal}
+ */
+${hostBlock}
+@layer design-system.components {
+  .${className} {
+    /* TODO: add styles */
+    display: block;
+  }
+}
+`
+}

package/tools/templates/entry.mjs

@@ -0,0 +1,4 @@
+export const entryTemplate = ctx => {
+  const { pascal } = ctx
+  return `import "./Elements/${pascal}"\n`
+}

package/tools/templates/figma.mjs

@@ -0,0 +1,17 @@
+export function figmaTemplate(ctx) {
+  const { pascal, kebab, category } = ctx
+  return `// url=TODO: paste this component's Figma frame URL (see the code-to-figma-code-connect skill)
+// source=src/${category}/${pascal}/${pascal}.tsx
+// component=${pascal}
+import figma from "figma"
+
+export default {
+  example: figma.code\`<${pascal} />\`,
+  imports: ['import { ${pascal} } from "@pnx-mixtape/mxds/react"'],
+  id: "${kebab}",
+  metadata: {
+    nestable: true,
+  },
+}
+`
+}

package/tools/templates/react.mjs

@@ -0,0 +1,16 @@
+export const reactTemplate = ctx => {
+  const { pascal, className } = ctx
+  return `import { JSX, PropsWithChildren } from "react"
+import classNames from "classnames"
+
+type ${pascal}Props = PropsWithChildren & {
+  className?: string
+}
+
+const ${pascal} = ({ children, className }: ${pascal}Props): JSX.Element => {
+  return <div className={classNames("${className}", className)}>{children}</div>
+}
+
+export default ${pascal}
+`
+}

package/tools/templates/readme.mjs

@@ -0,0 +1,80 @@
+export const readmeTemplate = ctx => {
+  const {
+    pascal,
+    kebab,
+    category,
+    className,
+    tagName,
+    description,
+    hasReact,
+    hasTwig,
+    hasWebComponent,
+  } = ctx
+
+  const sections = [`# ${pascal}\n\n${description || `TODO: describe ${pascal}.`}`]
+
+  sections.push(`## CSS Import
+
+\`\`\`css
+@import "@pnx-mixtape/mxds/src/${category}/${pascal}/${kebab}.css";
+\`\`\``)
+
+  if (hasTwig) {
+    sections.push(`## Twig
+
+\`\`\`twig
+{% include '@mixtape/${category}/${pascal}/${kebab}.twig' with {
+  content: 'Content goes here',
+} %}
+\`\`\``)
+  }
+
+  sections.push(`## HTML${hasWebComponent ? " + Web Component" : ""}
+
+\`\`\`html
+<div class="${className}">
+  Content goes here
+</div>
+\`\`\`${
+    hasWebComponent
+      ? `
+
+Registers as \`<${tagName}>\`. Import the element to activate its behaviour:
+
+\`\`\`js
+import "@pnx-mixtape/mxds/src/${category}/${pascal}/Elements/${pascal}"
+\`\`\``
+      : ""
+  }`)
+
+  if (hasReact) {
+    sections.push(`## React
+
+\`\`\`tsx
+import { ${pascal} } from "@pnx-mixtape/mxds/react"
+
+<${pascal}>Content goes here</${pascal}>
+\`\`\`
+
+**\`${pascal}\` props:**
+
+| Prop        | Type        | Default | Description             |
+| ----------- | ----------- | ------- | ------------------------ |
+| \`className\` | \`string\`    | —       | Extra class on the root  |
+| \`children\`  | \`ReactNode\` | —       | Content                  |`)
+  }
+
+  sections.push(`## Modifiers
+
+TODO: document any BEM modifier classes.`)
+
+  sections.push(`## Accessibility
+
+TODO: document accessibility considerations.`)
+
+  sections.push(`## Customisation
+
+TODO: document any overridable CSS custom properties.`)
+
+  return sections.join("\n\n---\n\n") + "\n"
+}

package/tools/templates/storiesHtml.mjs

@@ -0,0 +1,22 @@
+export const storiesHtmlTemplate = ctx => {
+  const { pascal, kebab, hasWebComponent } = ctx
+  const elementsImport = hasWebComponent ? `\nimport "./Elements/${pascal}"` : ""
+
+  return `import { Meta, StoryObj } from "@storybook/html-vite"
+import Component from "./${kebab}.twig"
+import "./${kebab}.css"${elementsImport}
+
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  component: Component,
+  args: {
+    content: "${pascal} content",
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const ${pascal}: Story = {}
+`
+}