@signal9/era-ui 2.26.0 → 2.27.1

package/dist/styles/index.css

@@ -36,7 +36,10 @@
 }
 
 /* Shared interactive-state recipe: quiet focus, disabled affordance.
- * Equivalent to `focus:outline-none disabled:cursor-not-allowed disabled:opacity-50`. */
+ * Equivalent to `focus:outline-none disabled:cursor-not-allowed disabled:opacity-50`.
+ *
+ * @use the focus/disabled recipe every era control carries — put it on a custom
+ * interactive element instead of hand-writing focus/disabled variants. */
 @utility era-interactive {
 	&:focus {
 		outline: none;
@@ -54,7 +57,11 @@
  * "extra" — matching every other era transition. Font-agnostic: it styles
  * decoration + colour only, so it reads correctly in mono, sans, or serif, and
  * the 0.2em offset scales with the type size. Keyboard focus mirrors hover so
- * the affordance is reachable without a pointer. */
+ * the affordance is reachable without a pointer.
+ *
+ * @use understated, motion-aware inline text link — the canonical style for a
+ * link in body copy or prose; prefer it over a hand-rolled underline or
+ * `Button variant="link"` (which is a control, not running text). */
 @utility era-link {
 	/* The text is bright at rest and never changes — the link reads as a link
 	 * before you touch it. Only the UNDERLINE reacts: a faint half-strength-muted
@@ -71,7 +78,10 @@
 }
 
 /* Scrollable but chromeless — hides the scrollbar while keeping wheel / touch /
- * drag scrolling (e.g. an overflowing tab strip in a small pane handle). */
+ * drag scrolling (e.g. an overflowing tab strip in a small pane handle).
+ *
+ * @use hide the scrollbar on an overflowing strip or rail while keeping it
+ * scrollable — for a scroll region that should show its bar, use ScrollArea. */
 @utility scrollbar-none {
 	scrollbar-width: none;
 	&::-webkit-scrollbar {
@@ -91,16 +101,29 @@
  * Where text-box is supported it fully determines the box, so the two
  * declarations never fight. Worst-case residual: 0.44px.
  *
- * The one hard rule concerns overflow clipping, and it is HEIGHT-conditional.
- * On an AUTO-height element that also clips — a `truncate` child, a
- * <textarea>, an auto-height <input> — trim-both collapses the box to the
- * x-height band (~7.5px at 14px) and the clip slices off every ascender, cap,
- * and descender (text renders as a chopped middle stripe): NEVER do that.
- * A FIXED-height control is the intended home, and is safe: the explicit
- * `h-(--era-*)` overrides the collapse, so a single-line <input> (Input,
- * command-input) and clipping display tokens (KV) correctly carry it. For
- * truncating text, put the trim on the fixed-height ROW and let the child
- * center via the row's items-center.
+ * The hard rules concern overflow clipping, and there are TWO of them.
+ *
+ * 1. NEVER on a NATIVE EDITABLE — <input>, <textarea>, <select>. These clip to
+ *    a UA-owned inner editor box that IS the trimmed line box, so a fixed
+ *    height does NOT hold it open: whatever you type gets its ascenders and
+ *    descenders sliced off (a "d" renders as an "o"). This rule used to read
+ *    the other way round — it claimed a fixed-height <input> was the trim's
+ *    intended home — and the Input component shipped chopped text as a result.
+ *    A tier-height input centres its own text; it needs no trim.
+ *
+ * 2. NEVER on an AUTO-height element that clips — a `truncate` child, an
+ *    auto-height box with overflow-hidden. With no height to hold it open the
+ *    box collapses to the x-height band (~7.5px at 14px) and the clip chops the
+ *    glyphs into a middle stripe. Put the trim on the fixed-height ROW instead
+ *    and let the child centre via the row's items-center.
+ *
+ * A fixed-height NON-editable element is the safe home: the ink overflows the
+ * trimmed LINE box but stays inside the padding box, which is what actually
+ * clips. Both rules are enforced at runtime by typography/collapsed-text-trim.
+ *
+ * @use vertically center single-line control text (a label beside an icon, a
+ * button's own text) without a translateY nudge — fixed-height, non-editable
+ * elements only; see era-text-trim-caps for ALL-CAPS strings.
  */
 @utility era-text-trim {
 	line-height: 1;
@@ -108,7 +131,10 @@
 }
 
 /* ALL-CAPS single-line text (kbd hints, acronym badges): the x-height band
- * misjudges caps-only strings — cap/alphabetic edges are the right box. */
+ * misjudges caps-only strings — cap/alphabetic edges are the right box.
+ *
+ * @use the era-text-trim variant for ALL-CAPS single-line strings (kbd hints,
+ * acronym badges) — never use it for mixed-case text. */
 @utility era-text-trim-caps {
 	line-height: 1;
 	text-box: trim-both cap alphabetic;
@@ -118,7 +144,10 @@
  * "working…" label treatment in streaming UIs). Timing derives from the motion
  * axis (10× --era-duration ≈ 1.5s at normal, 2.6s at extra); at instant the
  * duration is 0s and the sweep freezes on its base frame — plain muted text —
- * so reduced-motion and data-motion="instant" both kill it for free. */
+ * so reduced-motion and data-motion="instant" both kill it for free.
+ *
+ * @use the in-progress text treatment — put it on a "working…" / "thinking…"
+ * label while a task streams, instead of a spinner beside the text. */
 @utility era-shimmer {
 	background: linear-gradient(
 		110deg,

package/dist/styles/surfaces/glass.css

@@ -118,7 +118,11 @@
 }
 
 /* Tailwind v4 cannot resolve var() inside backdrop-blur-[], so the filter
- * is a registered utility, gated to glass subtrees. */
+ * is a registered utility, gated to glass subtrees.
+ *
+ * @use the backdrop blur for a floating panel (popover, dialog, taskbar) — it
+ * applies only inside a data-surface="glass" subtree and is inert elsewhere,
+ * so it is safe to leave on a panel that renders under every surface. */
 @utility glass-blur {
 	[data-surface='glass'] & {
 		backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));

package/dist/ui/input/input.svelte

@@ -16,7 +16,11 @@
 	bind:this={ref}
 	bind:value
 	class={cn(
-		'flex h-(--era-h-md) w-full era-interactive rounded-(--era-rd-md) bg-(--era-surface-bg-elevated) px-(--era-inset-md) text-body era-text-trim text-fg shadow-(--era-shadow-well) placeholder:text-muted hover:bg-(--era-highlight) focus:bg-(--era-highlight)',
+		// No era-text-trim here: an <input> clips to a UA-owned inner editor box that
+		// IS the trimmed line box, so the trim slices the ascenders and descenders off
+		// what you type (a "d" renders as an "o"). The fixed tier height centres the
+		// text on its own. See the utility's note in styles/index.css.
+		'flex h-(--era-h-md) w-full era-interactive rounded-(--era-rd-md) bg-(--era-surface-bg-elevated) px-(--era-inset-md) text-body text-fg shadow-(--era-shadow-well) placeholder:text-muted hover:bg-(--era-highlight) focus:bg-(--era-highlight)',
 		className
 	)}
 	{...restProps}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@signal9/era-ui",
-	"version": "2.26.0",
+	"version": "2.27.1",
 	"scripts": {
 		"dev": "vite dev --host",
 		"build": "vite build && npm run prepack",
@@ -65,7 +65,8 @@
 		},
 		"./css": "./dist/era-ui.css",
 		"./styles/raw": "./dist/styles/index.css",
-		"./styles/themes": "./dist/styles/themes.css"
+		"./styles/themes": "./dist/styles/themes.css",
+		"./utilities.json": "./dist/generated-docs/utilities.json"
 	},
 	"peerDependencies": {
 		"svelte": "^5.0.0",

package/skill/SKILL.md

@@ -115,6 +115,23 @@ motion-axis-aware for free.
 - Headings balance and prose wraps pretty automatically — don't re-add
   `text-balance`/`text-pretty` except on non-semantic prose elements.
 
+## CSS utilities (classes, not components)
+
+Not everything era exposes is a component — these ride along with the stylesheet
+and need no import. Reach for one before hand-rolling the same styling or bending
+a component into the role. Full reference: `/utilities.md`; machine-readable list:
+`/utilities.json` (or `@sig-nine/era-ui/utilities.json`).
+
+| Class                | Use it for                                                                                                             |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `era-link`           | inline text link in body copy/prose — NOT `Button variant="link"` (that's a control) and never a hand-rolled underline |
+| `era-interactive`    | the focus/disabled recipe on a custom control (every era wrapper carries it)                                           |
+| `era-text-trim`      | ink-centering single-line control text beside an icon; fixed-height elements only                                      |
+| `era-text-trim-caps` | the same for ALL-CAPS strings (kbd hints, acronym badges)                                                              |
+| `era-shimmer`        | a "working…" / streaming label — motion-aware, dies at `instant` and under reduced-motion                              |
+| `scrollbar-none`     | an overflowing strip that scrolls with no visible bar (ScrollArea is for when the bar IS the design)                   |
+| `glass-blur`         | backdrop blur on a floating panel; inert outside a `data-surface="glass"` subtree                                      |
+
 ## Composing the library
 
 ```svelte