@signal9/era-ui 2.26.0 → 2.27.0

package/dist/docs/button.md

@@ -15,4 +15,5 @@
 
 - Heights, radii, paddings, and gaps come from density tokens — never hard-code px.
 - `link` variant intentionally does not change color on hover (underline only) so it reads as static prose until confirmed interactive.
+- `variant="link"` is for a _control_ that should look like a link (a button that reveals a panel, a destructive action in a row). For a link in body copy or prose, use the `era-link` CSS utility on an `<a>` instead — see [Utilities](/utilities.md).
 - For a segmented row of buttons, use `ButtonGroup`.

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

@@ -0,0 +1,21 @@
+export interface CssUtility {
+    /** Class name, e.g. `era-link`. */
+    name: 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. */
+    useCase?: string;
+    /** The rest of the doc comment — rationale, caveats, axis behaviour. */
+    description: string;
+    /** The `@utility` block verbatim, as authored. */
+    css: string;
+}
+/**
+ * @param sources stylesheet text keyed by path relative to src/lib/styles
+ *   (e.g. `index.css`, `surfaces/glass.css`).
+ */
+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. */
+export declare function buildUtilitiesIndex(utilities: CssUtility[]): string[];

package/dist/docs/css-utilities.js

@@ -0,0 +1,124 @@
+/*
+ * Extracts era's Tailwind v4 `@utility` classes — era-link, era-text-trim,
+ * era-shimmer, scrollbar-none, glass-blur, … — from the stylesheet source.
+ *
+ * These are first-class API but they have no JS export and no .svelte file, so
+ * nothing else in the doc pipeline can see them: the component barrel misses
+ * them, the registry misses them, and a consumer (or an agent) reasoning from
+ * "what does era expose for links?" never finds `era-link`. The doc comment
+ * above each `@utility` is already thorough, so it — not a hand-maintained list
+ * — is the source of truth. This parses it.
+ *
+ * The convention the parser leans on: an `@use ` line in the comment is the
+ * one-line use case (what an agent searches), and the remaining prose is the
+ * long description. A utility with no `@use` line still documents fine; it just
+ * lands in the docs without a use-case summary.
+ *
+ * Pure (takes sources, returns data) so both the runtime glob loader and the
+ * node build script can drive it — same split as component-source-scanners.ts.
+ */
+/** Files whose utilities are library API. Order fixes the doc's order. */
+const FILE_ORDER = ['index.css', 'surfaces/glass.css'];
+function cleanComment(raw) {
+    return raw
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd())
+        .join('\n')
+        .trim();
+}
+/** Split the comment into its `@use` one-liner and the surrounding prose. */
+function splitUseCase(comment) {
+    const lines = comment.split('\n');
+    const start = lines.findIndex((line) => line.startsWith('@use '));
+    if (start === -1)
+        return { description: comment.trim() };
+    let end = start + 1;
+    while (end < lines.length && lines[end].trim() !== '')
+        end++;
+    const useCase = lines
+        .slice(start, end)
+        .join(' ')
+        .replace(/^@use\s+/, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const description = [...lines.slice(0, start), ...lines.slice(end)].join('\n').trim();
+    return { useCase, description };
+}
+/** Walk from the opening brace to its match so nested rules survive intact. */
+function blockEnd(source, openBrace) {
+    let depth = 0;
+    for (let i = openBrace; i < source.length; i++) {
+        if (source[i] === '{')
+            depth++;
+        else if (source[i] === '}' && --depth === 0)
+            return i;
+    }
+    return source.length - 1;
+}
+function parseFile(file, source) {
+    const out = [];
+    // The comment body may not contain a terminator — a lazy `[\s\S]*?` would
+    // happily start at the first comment in the file and run through every `*/`
+    // 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 { useCase, description } = splitUseCase(cleanComment(match[1]));
+        out.push({
+            name: match[2],
+            file,
+            useCase,
+            description,
+            css: source.slice(source.indexOf('@utility', match.index), end + 1)
+        });
+    }
+    return out;
+}
+/**
+ * @param sources stylesheet text keyed by path relative to src/lib/styles
+ *   (e.g. `index.css`, `surfaces/glass.css`).
+ */
+export function parseUtilities(sources) {
+    const rank = (file) => {
+        const i = FILE_ORDER.indexOf(file);
+        return i === -1 ? FILE_ORDER.length : i;
+    };
+    return Object.entries(sources)
+        .sort(([a], [b]) => rank(a) - rank(b) || a.localeCompare(b))
+        .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.',
+    '',
+    '```ts',
+    'import "@sig-nine/era-ui/css";',
+    '```',
+    '',
+    '```svelte',
+    '<a class="era-link" href="/spacing">the spacing ladder</a>',
+    '```'
+].join('\n');
+/** 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('');
+    for (const u of utilities) {
+        lines.push(`## ${u.name}`, '');
+        if (u.useCase)
+            lines.push(`**Use it for:** ${u.useCase}`, '');
+        if (u.description)
+            lines.push(u.description, '');
+        lines.push(`Declared in \`${u.file}\`.`, '', '```css', u.css, '```', '');
+    }
+    return lines.join('\n');
+}
+/** One line per utility for llms.txt — name plus its searchable use case. */
+export function buildUtilitiesIndex(utilities) {
+    return utilities.map((u) => `- \`${u.name}\` — ${u.useCase ?? u.description.split('\n')[0]}`);
+}

package/dist/docs/generated-docs.d.ts

@@ -1,4 +1,6 @@
 export declare const docsBySlug: Record<string, string>;
 export declare const knownSlugs: Set<string>;
+/** Served verbatim at /utilities.json so tooling can enumerate the CSS API. */
+export declare const utilitiesJson: string;
 export declare const llmsTxtTemplate: string;
 export declare const llmsFullTxt: string;

package/dist/docs/generated-docs.js

@@ -12,6 +12,11 @@ const manifestModules = import.meta.glob('../generated-docs/manifest.json', {
     import: 'default',
     eager: true
 });
+const utilitiesModules = import.meta.glob('../generated-docs/utilities.json', {
+    query: '?raw',
+    import: 'default',
+    eager: true
+});
 function stem(path) {
     return path.replace(/^\.\.\/generated-docs\//, '').replace(/\.(md|txt)$/, '');
 }
@@ -19,5 +24,7 @@ export const docsBySlug = Object.fromEntries(Object.entries(markdownFiles).map((
 const manifest = Object.values(manifestModules)[0];
 const manifestSlugs = manifest?.entries?.map((entry) => entry.slug) ?? [];
 export const knownSlugs = new Set(manifestSlugs.length ? manifestSlugs : Object.keys(docsBySlug));
+/** Served verbatim at /utilities.json so tooling can enumerate the CSS API. */
+export const utilitiesJson = utilitiesModules['../generated-docs/utilities.json'] ?? '';
 export const llmsTxtTemplate = textFiles['../generated-docs/llms.txt'] ?? '';
 export const llmsFullTxt = textFiles['../generated-docs/llms-full.txt'] ?? '';

package/dist/docs/index.js

@@ -1,5 +1,6 @@
 import { components, guides } from '../../routes/registry.js';
 import { buildComponentDoc } from './component-docs.js';
+import { utilitiesDoc } from './utilities.js';
 const rootUiIndexSources = import.meta.glob('../ui/index.ts', {
     query: '?raw',
     import: 'default',
@@ -14,6 +15,9 @@ function slugFromPath(path) {
     return path.replace(/^\.\//, '').replace(/\.md$/, '');
 }
 const appendices = Object.fromEntries(Object.entries(markdownModules).map(([path, body]) => [slugFromPath(path), body]));
+// The utilities guide has no component source to synthesize from — its body is
+// parsed out of the `@utility` doc comments in src/lib/styles instead.
+appendices.utilities = [appendices.utilities, utilitiesDoc].filter(Boolean).join('\n\n');
 function titleFromSlug(slug) {
     return slug
         .split('-')

package/dist/docs/llms-txt.js

@@ -1,4 +1,6 @@
 import { docs, hasDoc, listEntries } from './index.js';
+import { buildUtilitiesIndex } from './css-utilities.js';
+import { utilities } from './utilities.js';
 import { modes, defaultMode, surfaces, defaultSurface, corners, defaultCorners, fonts, defaultFont, motions, defaultMotion } from '../ui/provider/index.js';
 const H1 = '# era-ui';
 const MISSION = '> A Svelte 5 + Bits UI component library. Every surface — heights, paddings, radii, gaps — derives from a single spacing atom, so density is a one-attribute override at any scope.';
@@ -49,6 +51,17 @@ function orientation(origin) {
         'Each page is generated from the component source, so props/variants/defaults stay in sync with the code automatically.'
     ].join('\n');
 }
+function utilitiesSection(origin) {
+    return [
+        '## CSS utilities',
+        '',
+        'Classes, not components — they need no import beyond the stylesheet. Reach for one of these before hand-rolling the same styling or bending a component into the role.',
+        '',
+        ...buildUtilitiesIndex(utilities),
+        '',
+        `Full reference (what each emits, when to use it): \`${origin}/utilities.md\`. Machine-readable list: \`${origin}/utilities.json\`.`
+    ].join('\n');
+}
 export function buildLlmsTxt(origin = '') {
     const entries = listEntries();
     const lines = [H1, '', MISSION, '', orientation(origin), ''];
@@ -56,6 +69,7 @@ export function buildLlmsTxt(origin = '') {
         lines.push('## Components', '');
         lines.push(entries.map((e) => e.slug).join(', '), '');
     }
+    lines.push(utilitiesSection(origin), '');
     return lines.join('\n');
 }
 // Module-init-cached: the concatenated reference has no request-dependent
@@ -73,7 +87,9 @@ export function buildLlmsFullTxt() {
         '',
         orientation(''),
         '',
-        '<!-- Full component documentation, concatenated. -->',
+        utilitiesSection(''),
+        '',
+        '<!-- Full component documentation, concatenated. The utilities page below carries the CSS each utility emits. -->',
         ''
     ];
     for (const e of entries) {

package/dist/docs/scroll-area.md

@@ -0,0 +1,7 @@
+## Notes
+
+- For a region that should scroll but show no scrollbar at all — an overflowing
+  tab strip, a chip rail, a small pane handle — you don't need ScrollArea: put
+  the `scrollbar-none` CSS utility on the overflowing element. See
+  [Utilities](/utilities.md). ScrollArea is for the case where the bar itself is
+  part of the design.

package/dist/docs/utilities.d.ts

@@ -0,0 +1,4 @@
+import { type CssUtility } from './css-utilities.js';
+export declare const utilities: CssUtility[];
+export declare const utilitiesDoc: string;
+export type { CssUtility };

package/dist/docs/utilities.js

@@ -0,0 +1,15 @@
+/*
+ * Runtime side of the CSS-utility docs: globs the shipped stylesheets and parses
+ * their `@utility` blocks. The node build script (scripts/build-llm-docs.ts)
+ * feeds the same parser from the filesystem, so the site and the generated
+ * markdown can never disagree about what era exposes.
+ */
+import { buildUtilitiesDoc, parseUtilities } from './css-utilities.js';
+const cssSources = import.meta.glob('../styles/**/*.css', {
+    query: '?raw',
+    import: 'default',
+    eager: true
+});
+const sources = Object.fromEntries(Object.entries(cssSources).map(([path, body]) => [path.replace(/^\.\.\/styles\//, ''), body]));
+export const utilities = parseUtilities(sources);
+export const utilitiesDoc = buildUtilitiesDoc(utilities);