@signal9/era-ui 10.0.0 → 11.0.0

package/dist/docs/css-utilities.js

@@ -19,6 +19,64 @@
  */
 /** Files whose utilities are library API. Order fixes the doc's order. */
 const FILE_ORDER = ['index.css', 'surfaces/glass.css'];
+/**
+ * `@theme` namespace → the utility prefixes it generates.
+ *
+ * Half of era's public class API is registered this way rather than as
+ * `@utility` blocks — `rounded-control` from `--radius-control`, `shadow-lg`,
+ * `bg-highlight`, `text-body`, and the whole spacing scale. They are classes a
+ * consumer writes exactly like the others, and until this table existed the
+ * doc pipeline could not see any of them: `@utility` was the only thing it
+ * parsed, so era's most-used names were also its least-documented.
+ *
+ * The list per namespace is the SPELLINGS WORTH DOCUMENTING, not everything
+ * Tailwind derives — a spacing token really does generate `mt-`, `gap-x-`,
+ * `inset-`, `translate-` and a dozen more, and printing all of them per name
+ * would bury the point. The prose says the rest.
+ */
+export const THEME_CLASS_PREFIXES = {
+    radius: ['rounded'],
+    shadow: ['shadow'],
+    text: ['text'],
+    leading: ['leading'],
+    ease: ['ease'],
+    color: ['bg', 'text', 'border'],
+    spacing: ['p', 'px', 'py', 'gap']
+};
+/** Every prefix a namespace really generates — the map the codemod needs. */
+export const THEME_ALL_PREFIXES = {
+    ...THEME_CLASS_PREFIXES,
+    radius: [
+        'rounded',
+        ...'t,r,b,l,tl,tr,bl,br,s,e,ss,se,es,ee'.split(',').map((s) => `rounded-${s}`)
+    ],
+    color: [
+        'bg',
+        'text',
+        'border',
+        'fill',
+        'stroke',
+        'ring',
+        'outline',
+        'divide',
+        'decoration',
+        'caret',
+        'accent',
+        'from',
+        'via',
+        'to'
+    ],
+    spacing: [
+        'p,px,py,pt,pr,pb,pl,ps,pe',
+        'm,mx,my,mt,mr,mb,ml,ms,me',
+        'gap,gap-x,gap-y',
+        'w,h,size,min-w,min-h,max-w,max-h',
+        'inset,inset-x,inset-y,top,right,bottom,left,start,end',
+        'translate,translate-x,translate-y,scroll-m,scroll-p,basis,indent'
+    ]
+        .join(',')
+        .split(',')
+};
 function cleanComment(raw) {
     return raw
         .split('\n')
@@ -86,6 +144,62 @@ function parseFile(file, source) {
     }
     return out;
 }
+/**
+ * The classes one `@theme` key generates, each with the utility PREFIX that
+ * generated it — `--spacing-inset-control` → `{ prefix: 'px', name:
+ * 'px-inset-control' }`. The prefix cannot be recovered from the name (both
+ * `px` and `px-inset` are hyphen-splits of `px-inset-control`), and the codemod
+ * matches on it, so it is returned rather than re-derived.
+ */
+export function themeKeyClassEntries(themeKey, prefixes = THEME_CLASS_PREFIXES) {
+    const bare = themeKey.replace(/^--/, '');
+    // `--shadow: …` IS the bare `shadow` class — a namespace with no suffix.
+    if (prefixes[bare])
+        return [{ prefix: bare, name: bare }];
+    const cut = bare.indexOf('-');
+    if (cut === -1)
+        return [];
+    const namespace = bare.slice(0, cut);
+    const suffix = bare.slice(cut + 1);
+    return (prefixes[namespace] ?? []).map((p) => ({ prefix: p, name: `${p}-${suffix}` }));
+}
+/** The class names one `@theme` key generates, e.g. `--radius-control` → `rounded-control`. */
+export function themeKeyClasses(themeKey, prefixes = THEME_CLASS_PREFIXES) {
+    return themeKeyClassEntries(themeKey, prefixes).map((e) => e.name);
+}
+/**
+ * Named theme scales — the other half of the public class API.
+ *
+ * Shape parsed: a doc comment followed by a RUN of `--key: var(…)` lines inside
+ * `@theme`, exactly like the `@utility` ladder rule above. One comment governs
+ * the whole run, so the radius ladder or the spacing scale documents once.
+ */
+function parseTheme(file, source) {
+    const theme = source.match(/@theme[^{]*\{([\s\S]*?)\n\}/);
+    if (!theme)
+        return [];
+    const body = theme[1];
+    const out = [];
+    const pattern = /\/\*((?:(?!\*\/)[\s\S])*)\*\/\s*((?:\s*--[\w-]+\s*:[^;]+;\n?)+)/g;
+    for (const match of body.matchAll(pattern)) {
+        const decls = [...match[2].matchAll(/--[\w-]+\s*:[^;]+;/g)].map((m) => m[0]);
+        const names = decls.flatMap((d) => themeKeyClasses(d.slice(0, d.indexOf(':')).trim()));
+        // A comment governing only non-class keys (--default-transition-*) has
+        // nothing to document — it is internal wiring, not API.
+        if (!names.length)
+            continue;
+        const { useCase, description } = splitUseCase(cleanComment(match[1]));
+        out.push({
+            name: names[0],
+            names,
+            file,
+            useCase,
+            description,
+            css: `@theme inline {\n${decls.map((d) => `\t${d}`).join('\n')}\n}`
+        });
+    }
+    return out;
+}
 /**
  * @param sources stylesheet text keyed by path relative to src/lib/styles
  *   (e.g. `index.css`, `surfaces/glass.css`).
@@ -97,7 +211,7 @@ export function parseUtilities(sources) {
     };
     return Object.entries(sources)
         .sort(([a], [b]) => rank(a) - rank(b) || a.localeCompare(b))
-        .flatMap(([file, source]) => parseFile(file, source));
+        .flatMap(([file, source]) => [...parseFile(file, source), ...parseTheme(file, source)]);
 }
 const INTRO = [
     "era's styling API is pure class names — write `h-control rounded-control px-gutter shadow`,",
@@ -105,7 +219,7 @@ const INTRO = [
     'with the stylesheet and needs no import:',
     '',
     '```ts',
-    'import "@sig-nine/era-ui/css";',
+    'import "@signal9/era-ui/css";',
     '```',
     '',
     '```svelte',
@@ -119,7 +233,7 @@ const INTRO = [
     '',
     '| Stock-looking class | What it resolves to |',
     '|---|---|',
-    '| `rounded-icon/xxs/sm/md/lg` | the concentric radius ladder (collapses on `data-corners="square"`) |',
+    '| `rounded-icon/pill/chip/control/bar` | the concentric radius ladder (collapses on `data-corners="square"`) |',
     '| `rounded-menu-item` | menu-row radius, concentric inside a `rounded-control` panel |',
     '| `shadow` / `shadow-lg` | resting control edge / floating panel chrome, per surface |',
     '| `shadow-well` / `shadow-pressed` / `shadow-highlight` | recessed, pressed/latched, hover-material chrome |',
@@ -127,13 +241,33 @@ const INTRO = [
     '| `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 |',
+    '| `p-gutter` / `gap-gutter` / `mt-gutter` / … | the spacing scale — EVERY spacing prefix works |',
+    '',
+    'The spacing names (`gutter`, `card`, `panel`, `content`, `menu`, `field`, the',
+    '`inset-*` and concentric `*-inset-*` insets, `glyph-*`) are registered as a',
+    'Tailwind spacing scale, so every prefix derives automatically: `p-`, `px-`,',
+    '`pt-`, `mt-`, `gap-`, `gap-x-`, `inset-`, `translate-`, and the rest. The TIER',
+    'names (`icon`, `pill`, `chip`, `control`, `bar`) are heights, not spacing, so',
+    'they are registered per prefix instead — `h-`, `w-`, `min-h-`, `min-w-` and',
+    '`size-` — and the two vocabularies deliberately share no word. Putting a tier',
+    'in the spacing scale would silently make `px-control` mean 24px of padding.',
     '',
-    "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-control)` etc. remain the escape hatch.'
+    'The var form (`h-(--era-h-control)`) still works and is the escape hatch for a',
+    'token with no registered name — `--era-sp`, the press-sink offsets, anything',
+    'a component reaches for once. `scripts/check-canonical.ts` fails the build if',
+    'source uses it where a name exists.'
 ].join('\n');
-/** `h-icon` for a single class, `h-icon · h-pill · … · h-bar` for a ladder. */
-const label = (u) => u.names.join(' · ');
+/**
+ * `h-icon` for a single class, `h-icon · h-pill · … · h-bar` for a ladder.
+ *
+ * Capped, because a theme scale can govern a LOT of spellings: the colour block
+ * generates bg-/text-/border- for every token, which is ~60 names and reads as
+ * noise in a heading. The prose under each entry states the full rule.
+ */
+const LABEL_CAP = 8;
+const label = (u) => u.names.length > LABEL_CAP
+    ? `${u.names.slice(0, LABEL_CAP).join(' · ')} · … (${u.names.length} in all)`
+    : u.names.join(' · ');
 /** Renders the utilities reference — the generated `utilities.md` body. */
 export function buildUtilitiesDoc(utilities) {
     const lines = ['## Overview', '', INTRO, '', '| Utility | Use it for |', '|---|---|'];

package/dist/docs/llms-txt.js

@@ -10,8 +10,8 @@ function orientation(origin) {
         '## Using the library',
         '',
         '```ts',
-        'import { Button, Table, Select } from "@sig-nine/era-ui";',
-        'import "@sig-nine/era-ui/css";',
+        'import { Button, Table, Select } from "@signal9/era-ui";',
+        'import "@signal9/era-ui/css";',
         '```',
         '',
         'Named exports wrap a single primitive (`Button`, `Badge`, `Chip`, `Input`, …). Namespace exports compose primitives via sub-components (`Table.Root`, `Table.Row`, `Select.Trigger`, `Dialog.Content`, …). Every wrapper forwards unknown props to its underlying element or bits-ui primitive, so standard HTML attributes (`class`, `style`, event handlers, `aria-*`, `data-*`) work without ceremony.',

package/dist/docs/notes.md

@@ -1,12 +1,12 @@
 ## Usage
 
-Apps ship on their own subpath and are **not** re-exported from `@sig-nine/era-ui`.
+Apps ship on their own subpath and are **not** re-exported from `@signal9/era-ui`.
 Notes carries TipTap, and a consumer who never imports an app should never pay
 for it.
 
 ```svelte
 <script>
-	import { Notes } from '@sig-nine/era-ui/apps';
+	import { Notes } from '@signal9/era-ui/apps';
 </script>
 
 <Notes />
@@ -46,7 +46,7 @@ Persistence is one small interface, so server-backed hosting is a drop-in swap
 `load`/`save` may be sync or async:
 
 ```ts
-import { Notes, NotesStore } from '@sig-nine/era-ui/apps';
+import { Notes, NotesStore } from '@signal9/era-ui/apps';
 
 const store = new NotesStore({
 	adapter: {

package/dist/docs/quickstart.md

@@ -7,7 +7,7 @@ Use a single, pure component import from `$lib/ui` for a clean docs-friendly sta
 	import { Badge, Bar, Button, ButtonGroup, Card, Separator } from '$lib/ui';
 </script>
 
-<section class="mx-auto flex w-full max-w-4xl flex-col gap-(--era-content-p) p-(--era-content-p)">
+<section class="mx-auto flex w-full max-w-4xl flex-col gap-content p-content">
 	<Badge tone="accent">Now shipping v0.8</Badge>
 
 	<div class="space-y-(--era-gap)">
@@ -28,10 +28,10 @@ Use a single, pure component import from `$lib/ui` for a clean docs-friendly sta
 
 	<Separator />
 
-	<div class="grid gap-(--era-gap) md:grid-cols-3">
-		<Card class="p-(--era-gap)">Dense-ready</Card>
-		<Card class="p-(--era-gap)">Balanced defaults</Card>
-		<Card class="p-(--era-gap)">Spacious polish</Card>
+	<div class="grid gap-gutter md:grid-cols-3">
+		<Card class="p-gutter">Dense-ready</Card>
+		<Card class="p-gutter">Balanced defaults</Card>
+		<Card class="p-gutter">Spacious polish</Card>
 	</div>
 </section>
 ```