@signal9/era-ui 3.0.1 → 3.2.0

package/dist/docs/css-utilities.d.ts

@@ -1,6 +1,12 @@
 export interface CssUtility {
-    /** Class name, e.g. `era-link`. */
+    /** Class name, e.g. `era-link` — the first of `names` for a ladder. */
     name: string;
+    /**
+     * Every class the doc comment governs. Usually one; a scale documented as a
+     * run of consecutive `@utility` blocks under a single comment (h-xs … h-lg)
+     * lists the whole ladder.
+     */
+    names: string[];
     /** Stylesheet the utility is declared in, relative to src/lib/styles. */
     file: string;
     /** One-line use case from the comment's `@use` line, if present. */
@@ -17,5 +23,5 @@ export interface CssUtility {
 export declare function parseUtilities(sources: Record<string, string>): CssUtility[];
 /** Renders the utilities reference — the generated `utilities.md` body. */
 export declare function buildUtilitiesDoc(utilities: CssUtility[]): string;
-/** One line per utility for llms.txt — name plus its searchable use case. */
+/** One line per utility (or ladder) for llms.txt — plus its searchable use case. */
 export declare function buildUtilitiesIndex(utilities: CssUtility[]): string[];

package/dist/docs/css-utilities.js

@@ -62,11 +62,22 @@ function parseFile(file, source) {
     // between there and the @utility.
     const pattern = /\/\*((?:(?!\*\/)[\s\S])*)\*\/\s*@utility\s+([\w-]+)\s*\{/g;
     for (const match of source.matchAll(pattern)) {
-        const openBrace = match.index + match[0].length - 1;
-        const end = blockEnd(source, openBrace);
+        const names = [match[2]];
+        let end = blockEnd(source, match.index + match[0].length - 1);
+        // One doc comment may govern a RUN of consecutive @utility blocks — a
+        // ladder like h-xs…h-lg shares one story, and repeating it five times
+        // would drown the docs. Attach every block that follows the previous one
+        // with nothing but whitespace in between; the next commented block never
+        // matches here because the outer pattern requires the comment.
+        const next = /^\s*@utility\s+([\w-]+)\s*\{/;
+        for (let m; (m = next.exec(source.slice(end + 1)));) {
+            names.push(m[1]);
+            end = blockEnd(source, end + 1 + m[0].length - 1);
+        }
         const { useCase, description } = splitUseCase(cleanComment(match[1]));
         out.push({
-            name: match[2],
+            name: names[0],
+            names,
             file,
             useCase,
             description,
@@ -89,27 +100,49 @@ export function parseUtilities(sources) {
         .flatMap(([file, source]) => parseFile(file, source));
 }
 const INTRO = [
-    'era ships a handful of Tailwind v4 `@utility` classes for the patterns that are',
-    'styling, not components — an inline link, ink-centred control text, a hidden',
-    'scrollbar. They need no import: they ride along with the stylesheet.',
+    "era's styling API is pure class names — write `h-md rounded-md px-md shadow`,",
+    'never the `h-(--era-h-md)` var-class spelling. Everything below rides along',
+    'with the stylesheet and needs no import:',
     '',
     '```ts',
     'import "@sig-nine/era-ui/css";',
     '```',
     '',
     '```svelte',
-    '<a class="era-link" href="/spacing">the spacing ladder</a>',
-    '```'
+    '<button class="h-md rounded-md px-inset-md shadow text-body">era styled</button>',
+    '```',
+    '',
+    'Alongside the `@utility` classes referenced below, era registers named theme',
+    'scales that OVERLOAD the stock Tailwind names, so ordinary-looking markup',
+    'renders on-design and responds to every axis (density, surface, corners,',
+    'motion):',
+    '',
+    '| Stock-looking class | What it resolves to |',
+    '|---|---|',
+    '| `rounded-xs/xxs/sm/md/lg` | the concentric radius ladder (collapses on `data-corners="square"`) |',
+    '| `rounded-item` | menu-row radius, concentric inside a `rounded-md` panel |',
+    '| `shadow` / `shadow-lg` | resting control edge / floating panel chrome, per surface |',
+    '| `shadow-well` / `shadow-pressed` / `shadow-highlight` | recessed, pressed/latched, hover-material chrome |',
+    '| `bg-well` / `bg-elevated` / `bg-highlight` / `bg-overlay` | surface fills: resting, raised, transient feedback, modal scrim |',
+    '| `transition-*` (bare) | duration + easing default to the motion axis |',
+    '| `ease-base` / `duration-base` | the motion axis, named explicitly |',
+    '| `text-body` | density-derived body/control text size |',
+    '',
+    "Deliberate gaps: `w-*`/`min-w-*` tier names would shadow Tailwind's container",
+    'scale (`min-w-md` stays 28rem), and the concentric-inset tokens are advanced',
+    'enough to stay var-form — `min-w-(--era-h-md)` etc. remain the escape hatch.'
 ].join('\n');
+/** `h-xs` for a single class, `h-xs · h-xxs · … · h-lg` for a ladder. */
+const label = (u) => u.names.join(' · ');
 /** Renders the utilities reference — the generated `utilities.md` body. */
 export function buildUtilitiesDoc(utilities) {
     const lines = ['## Overview', '', INTRO, '', '| Utility | Use it for |', '|---|---|'];
     for (const u of utilities) {
-        lines.push(`| \`${u.name}\` | ${u.useCase ?? '—'} |`);
+        lines.push(`| ${u.names.map((n) => `\`${n}\``).join(' ')} | ${u.useCase ?? '—'} |`);
     }
     lines.push('');
     for (const u of utilities) {
-        lines.push(`## ${u.name}`, '');
+        lines.push(`## ${label(u)}`, '');
         if (u.useCase)
             lines.push(`**Use it for:** ${u.useCase}`, '');
         if (u.description)
@@ -118,7 +151,7 @@ export function buildUtilitiesDoc(utilities) {
     }
     return lines.join('\n');
 }
-/** One line per utility for llms.txt — name plus its searchable use case. */
+/** One line per utility (or ladder) for llms.txt — plus its searchable use case. */
 export function buildUtilitiesIndex(utilities) {
-    return utilities.map((u) => `- \`${u.name}\` — ${u.useCase ?? u.description.split('\n')[0]}`);
+    return utilities.map((u) => `- \`${label(u)}\` — ${u.useCase ?? u.description.split('\n')[0]}`);
 }