@signal9/era-ui 2.21.0 → 2.23.0

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

@@ -0,0 +1,52 @@
+/*
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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.',
+    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')
+            return null;
+        // Is it clipping?
+        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;
+        const fontSize = parseFloat(s.fontSize) || 14;
+        // A healthy fixed-height control is at least as tall as its own type; a
+        // collapsed trim band lands near the x-height, roughly half of it.
+        if (h >= fontSize)
+            return null;
+        const issue = {
+            auditId: 'typography/collapsed-text-trim',
+            element: el,
+            message: `text box collapsed to ${h.toFixed(1)}px (font-size ${fontSize}px) while clipping — era-text-trim on an auto-height clipping element chops the glyphs; move the trim to the fixed-height row`,
+            details: { height: h, fontSize, trim, overflow: s.overflowX + '/' + s.overflowY }
+        };
+        return issue;
+    }
+};

package/dist/dev/audit/audits/flat-chrome.d.ts

@@ -0,0 +1,2 @@
+import type { Audit } from '../types.js';
+export declare const flatChrome: Audit;

package/dist/dev/audit/audits/flat-chrome.js

@@ -0,0 +1,46 @@
+/*
+ * Chrome that forgot to reference a surface shadow token.
+ *
+ * The surface system is entirely token-driven: --era-shadow and its siblings are
+ * what expand into bevel's chisel, glass's frosted rim, cartoon's ink-and-offset,
+ * and `none` on flat. So an element that paints a raised or floating surface with
+ * a bare `bg-*` and NO shadow token looks perfectly correct on flat — and renders
+ * as an undifferentiated grey rectangle on the other three.
+ *
+ * No token-usage check can catch this, because `bg-2` is a perfectly legal token.
+ * The bug is the ABSENCE of a second one, and absence is only visible once you
+ * render the thing on a surface that has depth. That is what happened to the
+ * command-bar dropdown: it used bg-2 with no shadow, correct on flat, borderless
+ * on bevel/glass/cartoon.
+ *
+ * Run this on a NON-FLAT surface (bevel is the harshest): the surface promises a
+ * shadow, so a floating panel that resolves to `box-shadow: none` is broken.
+ */
+export const flatChrome = {
+    id: 'surface/flat-chrome',
+    name: 'Floating chrome carries a surface shadow',
+    description: 'A floating panel (dropdown, popover, menu, dialog) must reference a surface shadow token, or it renders as a flat rectangle on every surface except flat.',
+    category: 'tokens',
+    severity: 'warn',
+    selector: '[role="menu"], [role="listbox"], [role="dialog"], [data-dialog-content], [data-popover-content], [data-select-content], [data-dropdown-menu-content], [data-combobox-content], [data-menubar-content], [data-context-menu-content]',
+    check(el) {
+        const surface = el.closest('[data-surface]')?.getAttribute('data-surface') ?? 'flat';
+        // On flat the tokens legitimately resolve to `none` — there is nothing to
+        // assert. The whole point of the rule only exists on a surface with depth.
+        if (surface === 'flat')
+            return null;
+        const s = getComputedStyle(el);
+        if (s.boxShadow !== 'none')
+            return null;
+        // A panel with no fill isn't chrome — it's a positioning wrapper.
+        if (s.backgroundColor === 'transparent' || /,\s*0\)$/.test(s.backgroundColor))
+            return null;
+        const issue = {
+            auditId: 'surface/flat-chrome',
+            element: el,
+            message: `floating panel has box-shadow: none on the "${surface}" surface — it references no --era-shadow token and will render flat everywhere but flat`,
+            details: { surface, background: s.backgroundColor }
+        };
+        return issue;
+    }
+};

package/dist/dev/audit/audits/icon-flush.d.ts

@@ -0,0 +1,2 @@
+import type { Audit } from '../types.js';
+export declare const iconFlush: Audit;

package/dist/dev/audit/audits/icon-flush.js

@@ -0,0 +1,51 @@
+import { TOL } from './_helpers.js';
+import { BOUNDED_TIER_MAX, getGaps } from '../../measure.js';
+/*
+ * The zero-gap bug, caught at the source.
+ *
+ * This is the copy button's original defect made mechanical: it shipped as
+ * `size="icon"` (an h-xs button) holding an `size-(--era-h-xs)` glyph, so
+ * (14 − 14) / 2 = 0 — the icon filled its own button edge to edge and read as a
+ * glyph jammed against its border. Every individual class was legal; the tier was
+ * legal; only the NESTING was wrong, which is why nothing but a rendered
+ * measurement could see it.
+ *
+ * The same shape recurs whenever an icon is sized at the tier of the control that
+ * holds it, so the check is simply: an icon inside a bounded control must have
+ * some breathing room.
+ */
+export const iconFlush = {
+    id: 'layout/icon-flush',
+    name: 'Icon flush against its control',
+    description: 'An icon inside a bounded control must leave a gap on every side. A zero gap means the glyph was sized at its container’s own tier and fills it edge to edge.',
+    category: 'layout',
+    severity: 'error',
+    selector: 'svg',
+    check(icon) {
+        const container = icon.parentElement;
+        if (!container)
+            return null;
+        const box = container.getBoundingClientRect();
+        // Bounded controls only — an icon sitting flush in an unbounded content
+        // area is a layout choice, not a tier error.
+        if (box.height === 0 || box.height > BOUNDED_TIER_MAX)
+            return null;
+        // The control has to actually be a control: a bare <span> wrapper around an
+        // icon legitimately hugs it (that is how an icon gets centred inside a
+        // button in the first place), so require chrome — a radius.
+        if (parseFloat(getComputedStyle(container).borderTopLeftRadius) <= 0)
+            return null;
+        const g = getGaps(icon, container);
+        const flushY = Math.abs(g.top) <= TOL && Math.abs(g.bottom) <= TOL;
+        const flushX = Math.abs(g.left) <= TOL && Math.abs(g.right) <= TOL;
+        if (!flushY && !flushX)
+            return null;
+        const issue = {
+            auditId: 'layout/icon-flush',
+            element: icon,
+            message: `icon fills its control (gaps T${g.top.toFixed(1)} R${g.right.toFixed(1)} B${g.bottom.toFixed(1)} L${g.left.toFixed(1)}) — size it a tier below its container`,
+            details: { ...g, containerHeight: box.height }
+        };
+        return issue;
+    }
+};

package/dist/dev/audit/audits/index.d.ts

@@ -1,5 +1,11 @@
+import { collapsedTextTrim } from './collapsed-text-trim.js';
 import { concentricInset } from './concentric-inset.js';
+import { flatChrome } from './flat-chrome.js';
+import { iconFlush } from './icon-flush.js';
+import { offAxisMotion } from './off-axis-motion.js';
+import { offTierHeight } from './off-tier-height.js';
 import { radiusConcentricity } from './radius-concentricity.js';
+import { singleGlyphSquare } from './single-glyph-square.js';
 import { uniformSiblingGaps } from './uniform-sibling-gaps.js';
 import { wallMatchesGap } from './wall-matches-gap.js';
-export { concentricInset, radiusConcentricity, uniformSiblingGaps, wallMatchesGap };
+export { collapsedTextTrim, concentricInset, flatChrome, iconFlush, offAxisMotion, offTierHeight, radiusConcentricity, singleGlyphSquare, uniformSiblingGaps, wallMatchesGap };

package/dist/dev/audit/audits/index.js

@@ -1,11 +1,30 @@
 import { registry } from '../registry.js';
+import { collapsedTextTrim } from './collapsed-text-trim.js';
 import { concentricInset } from './concentric-inset.js';
+import { flatChrome } from './flat-chrome.js';
+import { iconFlush } from './icon-flush.js';
+import { offAxisMotion } from './off-axis-motion.js';
+import { offTierHeight } from './off-tier-height.js';
 import { radiusConcentricity } from './radius-concentricity.js';
+import { singleGlyphSquare } from './single-glyph-square.js';
 import { uniformSiblingGaps } from './uniform-sibling-gaps.js';
 import { wallMatchesGap } from './wall-matches-gap.js';
-export { concentricInset, radiusConcentricity, uniformSiblingGaps, wallMatchesGap };
+export { collapsedTextTrim, concentricInset, flatChrome, iconFlush, offAxisMotion, offTierHeight, radiusConcentricity, singleGlyphSquare, uniformSiblingGaps, wallMatchesGap };
 // Auto-register built-ins. Consumers can still unregister or add their own.
+//
+// Two of these only tell the truth on a particular axis setting, because the bug
+// they hunt is invisible on the default one:
+//   - motion/off-axis-timing → run at data-motion="instant" (at "normal" a
+//     hardcoded duration-150 coincidentally matches the token and hides).
+//   - surface/flat-chrome    → run on a non-flat surface (on flat the shadow
+//     tokens legitimately resolve to `none`, so there is nothing to assert).
+registry.register(collapsedTextTrim);
 registry.register(concentricInset);
+registry.register(flatChrome);
+registry.register(iconFlush);
+registry.register(offAxisMotion);
+registry.register(offTierHeight);
 registry.register(radiusConcentricity);
+registry.register(singleGlyphSquare);
 registry.register(uniformSiblingGaps);
 registry.register(wallMatchesGap);

package/dist/dev/audit/audits/off-axis-motion.d.ts

@@ -0,0 +1,2 @@
+import type { Audit } from '../types.js';
+export declare const offAxisMotion: Audit;

package/dist/dev/audit/audits/off-axis-motion.js

@@ -0,0 +1,60 @@
+import { eraDurationMs, timesMs } from './_helpers.js';
+/*
+ * Motion must come off the motion axis, not out of thin air.
+ *
+ * --era-duration is the single knob behind data-motion (instant 0s / normal 150ms
+ * / extra 260ms). A component that hardcodes its timing — `duration-150`, a raw
+ * `transition: … 200ms`, or a Tailwind built-in like animate-pulse (which expands
+ * to a fixed 2s cubic-bezier that never reads the token) — looks fine at `normal`
+ * and is WRONG everywhere else: it keeps moving at `instant`, where the user (or
+ * prefers-reduced-motion) has asked for no motion at all.
+ *
+ * That last case is the point of running this audit at data-motion="instant": with
+ * the axis at 0s, ANY surviving duration is by definition off-axis. At `normal` a
+ * hardcoded `duration-150` coincidentally equals the token and hides. So:
+ *
+ *     set data-motion="instant" → run this audit → every hit is a real violation.
+ *
+ * The one sanctioned exception is a spinner: an indeterminate progress indicator
+ * is allowed to keep spinning at every motion level, because a frozen spinner
+ * reads as a hung app.
+ */
+const SPINNER = /spin/i;
+export const offAxisMotion = {
+    id: 'motion/off-axis-timing',
+    name: 'Timing comes from the motion axis',
+    description: 'Transitions and animations must derive their duration from --era-duration. Run with data-motion="instant": anything still animating there is hardcoded and cannot be turned off.',
+    category: 'tokens',
+    severity: 'warn',
+    selector: '*',
+    check(el) {
+        const s = getComputedStyle(el);
+        const expected = eraDurationMs(el);
+        const animating = timesMs(s.animationDuration).filter((d) => d > 0);
+        const transitioning = timesMs(s.transitionDuration).filter((d) => d > 0);
+        if (animating.length === 0 && transitioning.length === 0)
+            return null;
+        // A spinner is allowed to run at every motion level.
+        if (animating.length > 0 && SPINNER.test(s.animationName))
+            return null;
+        const offAxis = (d) => {
+            if (expected === 0)
+                return true; // instant: any motion at all is off-axis
+            // Components legitimately scale the token — calc(var(--era-duration) * N).
+            const ratio = d / expected;
+            return Math.abs(ratio - Math.round(ratio)) > 0.02 || ratio < 0.98;
+        };
+        const bad = [...animating, ...transitioning].filter(offAxis);
+        if (bad.length === 0)
+            return null;
+        const issue = {
+            auditId: 'motion/off-axis-timing',
+            element: el,
+            message: expected === 0
+                ? `still animating at motion="instant" (${bad.map((d) => `${d}ms`).join(', ')}) — hardcoded timing, ignores --era-duration`
+                : `timing ${bad.map((d) => `${d}ms`).join(', ')} is not derived from --era-duration (${expected}ms)`,
+            details: { expected, animating, transitioning, animationName: s.animationName }
+        };
+        return issue;
+    }
+};

package/dist/dev/audit/audits/off-tier-height.d.ts

@@ -0,0 +1,2 @@
+import type { Audit } from '../types.js';
+export declare const offTierHeight: Audit;

package/dist/dev/audit/audits/off-tier-height.js

@@ -0,0 +1,47 @@
+import { TOL, tiers } from './_helpers.js';
+/*
+ * Every chrome-bearing control must land on a tier.
+ *
+ * The tier ladder (xs / xxs / sm / md / lg) is the whole basis of the even-gap and
+ * concentricity laws: those laws are stated in terms of (h_outer − h_inner)/2, so
+ * a control that sits BETWEEN tiers can never nest concentrically in anything —
+ * it silently poisons every gap around it. That is exactly how the date segments
+ * broke: 21px tall, which is no tier at all, so their 1.5px gap could not match any
+ * radius step. Putting them on the sm tier (22px) is what let the identity close.
+ *
+ * A grep cannot see this. `h-[21px]` would be caught by the hardcoded-px rule, but
+ * these segments had NO height class at all — 21px was whatever the line box
+ * happened to produce. Only the rendered box tells you.
+ */
+export const offTierHeight = {
+    id: 'layout/off-tier-height',
+    name: 'Control lands on a tier',
+    description: 'A control that paints chrome must be exactly one of the five tier heights. A between-tier control cannot nest concentrically in anything.',
+    category: 'layout',
+    severity: 'warn',
+    selector: 'button, input, [role="switch"], [role="checkbox"], [role="radio"], [data-segment]',
+    check(el) {
+        const s = getComputedStyle(el);
+        // Chromeless controls (Button's `link` variant is tinted text, no box) have
+        // no tier to be on — their height is their line box, by design.
+        if (parseFloat(s.borderTopLeftRadius) <= 0)
+            return null;
+        // Multi-line controls (a grown textarea) aren't tier objects either.
+        if (s.whiteSpace === 'pre-wrap' || el.tagName === 'TEXTAREA')
+            return null;
+        const h = el.getBoundingClientRect().height;
+        if (h === 0)
+            return null;
+        const ladder = tiers(el);
+        const nearest = ladder.reduce((a, b) => (Math.abs(b.px - h) < Math.abs(a.px - h) ? b : a));
+        if (Math.abs(nearest.px - h) <= TOL)
+            return null;
+        const issue = {
+            auditId: 'layout/off-tier-height',
+            element: el,
+            message: `height ${h.toFixed(1)}px is between tiers (nearest ${nearest.name} = ${nearest.px}px) — give it an h-(…) tier`,
+            details: { height: h, nearest: nearest.name, nearestPx: nearest.px, ladder }
+        };
+        return issue;
+    }
+};

package/dist/dev/audit/audits/single-glyph-square.d.ts

@@ -0,0 +1,2 @@
+import type { Audit } from '../types.js';
+export declare const singleGlyphSquare: Audit;

package/dist/dev/audit/audits/single-glyph-square.js

@@ -0,0 +1,50 @@
+import { TOL, paintsChrome } from './_helpers.js';
+import { BOUNDED_TIER_MAX } from '../../measure.js';
+/*
+ * A one-character pill must be a square, not a sliver.
+ *
+ * Rule 5: every element that can hold a single glyph carries a min-width equal to
+ * its tier height, so one character renders as a perfect square (or circle, once
+ * rounded) instead of a skinny vertical pill. Icon buttons take min-w-(--era-h-md);
+ * Badge, Chip and the KV value cell take min-w-(--era-h-xxs).
+ *
+ * Drop the min-width and nothing looks wrong until content happens to BE one
+ * character — a badge showing "1", a count that ticks from 10 down to 9 — and the
+ * pill visibly pinches. That makes it a data-dependent bug: the class string is
+ * identical in both cases, so only the rendered box can tell you, and only when
+ * the short content is actually on screen.
+ *
+ * Chrome-bearing elements only: a bare one-character text span (the "/" literal in
+ * a date field) has no pill to pinch.
+ */
+export const singleGlyphSquare = {
+    id: 'layout/single-glyph-square',
+    name: 'Single-glyph pill stays square',
+    description: 'An element holding one character must be at least as wide as it is tall (min-w = its tier height), or it renders as a skinny pill instead of a square.',
+    category: 'layout',
+    severity: 'warn',
+    selector: '*',
+    check(el) {
+        const text = el.textContent?.trim() ?? '';
+        if (text.length !== 1)
+            return null;
+        // Only leaf-ish elements — a wrapper whose single child holds the glyph is
+        // not the thing that needs the min-width.
+        if (el.childElementCount > 0)
+            return null;
+        if (!paintsChrome(el))
+            return null;
+        const r = el.getBoundingClientRect();
+        if (r.height === 0 || r.height > BOUNDED_TIER_MAX)
+            return null;
+        if (r.width >= r.height - TOL)
+            return null;
+        const issue = {
+            auditId: 'layout/single-glyph-square',
+            element: el,
+            message: `one-glyph pill is ${r.width.toFixed(1)}×${r.height.toFixed(1)} — add min-w-(--era-h-…) matching its tier so it squares up`,
+            details: { width: r.width, height: r.height, text }
+        };
+        return issue;
+    }
+};

package/dist/dev/axis-signature.d.ts

@@ -0,0 +1,17 @@
+/** What one component looks like, on the axes, at one setting. */
+export interface AxisSignature {
+    slug: string;
+    /** Unique non-zero transition/animation durations in the subtree, in ms. */
+    durations: number[];
+    /** Names of running keyframe animations (a spinner is allowed to keep spinning). */
+    animations: string[];
+    /** Unique painted box-shadows — the surface system's whole output. */
+    shadows: string[];
+    /** The font actually resolved for the component's text. */
+    fontFamily: string;
+    /** Elements whose text is being cut off — the font-swap failure mode. */
+    clipped: string[];
+    /** Interactive controls, for the hover-state sweep the harness drives. */
+    controls: number;
+}
+export declare function captureSignatures(root?: ParentNode): AxisSignature[];

package/dist/dev/axis-signature.js

@@ -0,0 +1,87 @@
+/*
+ * Axis signatures — the fingerprint a component leaves at one axis setting.
+ *
+ * Every audit in ./audit answers a question about a SINGLE render: is this gap
+ * even, is this radius concentric, does this panel have a shadow. But the most
+ * important promises era makes are about the axes themselves, and they are
+ * comparative:
+ *
+ *   MOTION   does this component actually respond to instant / normal / extra —
+ *            freezing at one, moving at the next, and moving MORE at the third?
+ *   SURFACE  does its chrome actually change between flat / glass / bevel /
+ *            cartoon, or does it render the same rectangle on all four?
+ *   FONT     does it survive mono / sans / serif without clipping its own text?
+ *
+ * None of those can be answered by looking at one DOM. A component that hardcodes
+ * `duration-150` looks perfectly correct at data-motion="normal" — it is only
+ * wrong RELATIVE to the other two levels, where it fails to change. So the check
+ * has to be: render at each level, fingerprint what should have moved, and diff.
+ *
+ * This module captures the fingerprint. The comparison lives in the harness that
+ * drives the renders (tests/visual/axis-conformance.spec.ts), because only it can
+ * visit more than one axis at a time.
+ */
+const num = (v) => v
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => (s.endsWith('ms') ? parseFloat(s) : parseFloat(s) * 1000))
+    .filter((n) => !Number.isNaN(n) && n > 0);
+const uniq = (xs) => [...new Set(xs)];
+/**
+ * Is this element's text being cut off by its own box?
+ *
+ * The font axis is the one that breaks silently: a serif or sans face is WIDER
+ * than the mono default at the same size, so a label that fits in mono can
+ * overflow its control in serif — and because the control clips, the text simply
+ * disappears rather than reflowing. Nothing in a single-font render can predict
+ * that; you have to swap the font and look.
+ */
+function isClipped(el) {
+    const s = getComputedStyle(el);
+    if (!/hidden|clip/.test(s.overflowX))
+        return false;
+    if (!el.textContent?.trim())
+        return false;
+    // A visually-hidden element (sr-only) is a 1px box with its overflow clipped —
+    // that IS the technique, not a defect. It reports a wildly overflowing
+    // scrollWidth by construction (the calendar's screen-reader heading measured
+    // 144px of text in a 1px box), so exclude the degenerate boxes.
+    if (el.clientWidth <= 1 || el.clientHeight <= 1)
+        return false;
+    // 1px of slack: sub-pixel text metrics routinely round a hair over.
+    return el.scrollWidth > el.clientWidth + 1;
+}
+export function captureSignatures(root = document) {
+    const out = [];
+    for (const host of root.querySelectorAll('[data-specimen]')) {
+        const slug = host.getAttribute('data-specimen') ?? '';
+        const durations = [];
+        const animations = [];
+        const shadows = [];
+        const clipped = [];
+        let controls = 0;
+        for (const el of host.querySelectorAll('*')) {
+            const s = getComputedStyle(el);
+            durations.push(...num(s.transitionDuration), ...num(s.animationDuration));
+            if (s.animationName && s.animationName !== 'none')
+                animations.push(s.animationName);
+            if (s.boxShadow && s.boxShadow !== 'none')
+                shadows.push(s.boxShadow);
+            if (isClipped(el))
+                clipped.push(`${el.tagName.toLowerCase()}"${el.textContent?.trim().slice(0, 24)}"`);
+            if (el.matches('button, input, [role="switch"], [role="checkbox"], a[href]'))
+                controls++;
+        }
+        out.push({
+            slug,
+            durations: uniq(durations).sort((a, b) => a - b),
+            animations: uniq(animations).sort(),
+            shadows: uniq(shadows).sort(),
+            fontFamily: getComputedStyle(host).fontFamily,
+            clipped: uniq(clipped),
+            controls
+        });
+    }
+    return out;
+}

package/dist/dev/index.d.ts

@@ -1,3 +1,4 @@
 export * from './audit/index.js';
 export * from './measure.js';
+export * from './axis-signature.js';
 export { default as AuditOverlay } from './audit-overlay.svelte';

package/dist/dev/index.js

@@ -1,3 +1,4 @@
 export * from './audit/index.js';
 export * from './measure.js';
+export * from './axis-signature.js';
 export { default as AuditOverlay } from './audit-overlay.svelte';