@signal9/era-ui 2.26.0 → 2.27.1

package/dist/dev/audit/audits/collapsed-text-trim.js

@@ -2,37 +2,65 @@
  * The chopped-text bug.
  *
  * `era-text-trim` centres the ink by trimming the line box down to the x-height
- * band (text-box: trim-both ex alphabetic). That is exactly right on a control
- * with a FIXED height — the tier holds the box open and the trim only re-centres
- * what is inside it.
+ * band (text-box: trim-both ex alphabetic). It has two failure modes, and they
+ * are NOT the same check — the first one is why the Input shipped with every
+ * ascender sliced off the text you typed while this audit sat here reporting
+ * nothing.
  *
- * Put the same utility on an AUTO-height element that also clips its overflow
- * (`truncate`, `overflow-hidden`, an <input>) and the box collapses to the
- * ~7.5px x-height band. The clip then slices every ascender, cap and descender
- * off the glyphs, and the text renders as a chopped middle stripe.
+ * 1. NATIVE EDITABLES (<input>, <textarea>, <select>).
+ *    A fixed height does NOT make these safe. The UA lays out an inner editor
+ *    box and clips to IT, and that inner box is the trimmed line box — so the
+ *    trim collapses it to the x-height band no matter how tall the control is,
+ *    and the glyphs lose their tops and tails ("d" renders as "o"). The
+ *    element's own height therefore says nothing about whether it is broken:
+ *    the trim being ACTIVE is the whole defect. These elements also hold their
+ *    text in `value`, not in textContent, which is the other reason the old
+ *    height-and-textContent check could never fire on them.
  *
- * The tell is unmistakable in the geometry: a box shorter than its own font-size
- * that is still clipping. No static check can see it — whether the box collapses
- * depends on whether some OTHER class set a height.
+ * 2. AUTO-HEIGHT CLIPPING ELEMENTS (a `truncate` child, overflow-hidden with no
+ *    height). Nothing holds the box open, so it collapses to the ~7.5px band and
+ *    the clip chops the glyphs into a middle stripe. Here the tell IS geometric:
+ *    a box shorter than its own font-size that is still clipping. A FIXED-height
+ *    non-editable box is fine — the ink overflows the trimmed LINE box but stays
+ *    inside the padding box, which is what clips.
  */
+const EDITABLE = 'input, textarea, select';
+/** The trim, as the browser actually resolved it. Chromium exposes the longhand. */
+function activeTrim(s) {
+    const trim = s.getPropertyValue('text-box-trim').trim() || s.getPropertyValue('text-box').trim();
+    if (!trim || trim === 'none' || trim === 'normal')
+        return null;
+    return trim;
+}
 export const collapsedTextTrim = {
     id: 'typography/collapsed-text-trim',
     name: 'Trimmed text box has not collapsed',
-    description: 'era-text-trim on an auto-height element that clips overflow collapses the box to the x-height band, slicing the tops and tails off the glyphs.',
+    description: 'era-text-trim clips the glyphs when it lands on a native editable (any height) or on an auto-height element that clips its overflow.',
     category: 'layout',
     severity: 'error',
     selector: '*',
     check(el) {
         const s = getComputedStyle(el);
-        // Is the trim active on this element? Chromium exposes the longhand.
-        const trim = s.getPropertyValue('text-box-trim').trim() || s.getPropertyValue('text-box').trim();
-        if (!trim || trim === 'none' || trim === 'normal')
+        const trim = activeTrim(s);
+        if (!trim)
             return null;
-        // Is it clipping?
+        // (1) A native editable is broken by the trim at ANY height — it clips to the
+        // trimmed inner editor box. No geometry test, and no textContent test: an
+        // input's text lives in `value`, and an EMPTY input is just as broken, it
+        // simply has nothing to chop yet.
+        if (el.matches(EDITABLE)) {
+            const issue = {
+                auditId: 'typography/collapsed-text-trim',
+                element: el,
+                message: `text-box trim (${trim}) on a <${el.tagName.toLowerCase()}> — a native editable clips to the trimmed inner editor box, so the text you type loses its ascenders and descenders ("d" renders as "o"). Drop the trim; the tier height centres it.`,
+                details: { trim, tag: el.tagName.toLowerCase() }
+            };
+            return issue;
+        }
+        // (2) Everything else: only a collapsed, clipping box is a defect.
         const clips = /hidden|clip|auto|scroll/.test(s.overflowX + s.overflowY);
         if (!clips)
             return null;
-        // Does it hold any text of its own?
         if (!el.textContent?.trim())
             return null;
         const h = el.getBoundingClientRect().height;

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);