@signal9/era-ui 30.4.0 → 30.5.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [30.5.1](https://github.com/sig-nine/era-ui/compare/v30.5.0...v30.5.1) (2026-08-16)
+
+### Bug Fixes
+
+* **card:** a pressable card depresses, and the tones say what they paint ([7890b96](https://github.com/sig-nine/era-ui/commit/7890b969b5064df8a6716d530e21a82f23e68601))
+
+## [30.5.0](https://github.com/sig-nine/era-ui/compare/v30.4.0...v30.5.0) (2026-08-16)
+
+### Features
+
+* **meter:** start and end snippets caption what the range means ([1a6bf54](https://github.com/sig-nine/era-ui/commit/1a6bf544b5b3992649f66c5e9a05f24057f495cd))
+
 ## [30.4.0](https://github.com/sig-nine/era-ui/compare/v30.3.0...v30.4.0) (2026-08-16)
 
 ### Features

package/dist/ui/card/card.svelte

@@ -32,8 +32,17 @@
 			// was: the even-gap law, broken by default, in the component that
 			// bounds more consumer content than any other.
 			sectioned: { true: 'p-0', false: 'p-card' },
+			// A CARD YOU CAN PRESS DEPRESSES. `active:shadow-pressed` is on every
+			// other era control and was missing here, so a pressable card was the
+			// one thing in the library that lit up on hover and then did nothing
+			// under the finger — on bevel, where the pressed face is an inverted
+			// chisel, that is the difference between a control and a picture of
+			// one. Inert on flat (the token is `none`) and on glass (it resolves
+			// to the resting shadow), so only the surface that has a pressed face
+			// shows it. No content sink to go with it: the sink moves a control's
+			// single content wrapper, and a card's children are the consumer's.
 			interactive: {
-				true: 'cursor-pointer hover:bg-highlight hover:shadow-highlight focus-visible:bg-highlight era-interactive aria-disabled:cursor-not-allowed aria-disabled:opacity-50'
+				true: 'cursor-pointer hover:bg-highlight hover:shadow-highlight focus-visible:bg-highlight active:shadow-pressed era-interactive aria-disabled:cursor-not-allowed aria-disabled:opacity-50'
 			}
 		},
 		defaultVariants: { tone: 'elevated', sectioned: false, interactive: false }
@@ -93,11 +102,32 @@
 			ref?: CardElement | null;
 			/**
 			 * Surface tier the card paints on.
-			 * - `elevated` (default): the lifted surface. Use on the page background.
-			 * - `surface`: the base surface tier. Use when nesting cards inside another elevated container.
-			 * - `well`: recessed. For content the surrounding UI puts INTO the card — a tool's
-			 *   output pane, a transcript body — the container twin of a text field's fill.
-			 * - `flat`: no background; only the rounded/padded shell. For grouping content visually without adding contrast.
+			 * - `elevated` (default): the lifted surface, with a resting shadow. Use
+			 *   on the page background.
+			 * - `surface`: the base surface tier, no shadow. Use when nesting cards
+			 *   inside another elevated container.
+			 * - `well`: recessed. For content the surrounding UI puts INTO the card —
+			 *   a tool's output pane, a transcript body — the container twin of a
+			 *   text field's fill.
+			 * - `flat`: no background; only the rounded/padded shell. For grouping
+			 *   content visually without adding contrast.
+			 *
+			 * READ THE CLASSES AND THEY LOOK SWAPPED. They are not, and this is
+			 * worth a sentence because a consumer read them, believed it, and
+			 * shipped flat cards for months. `surface` paints `bg-well` and `well`
+			 * paints `bg-field`, because era's utility names describe FILLS rather
+			 * than tiers: `bg-well` is the surface's own resting fill (it is what a
+			 * panel is painted with, and it pairs with `shadow-well` when you want
+			 * recessed chrome), and `bg-field` is the recessed fill a text input
+			 * sits in. The tone names are the tiers; the class names are the paints.
+			 *
+			 * A CARD THAT IS PRESSABLE SHOULD USUALLY BE `elevated`. Passing `href`
+			 * or `onclick` turns on the interactive face — hover, focus, press — but
+			 * it deliberately does NOT override the tier you asked for, so a
+			 * `surface` link card has no resting lift and reads flatter than the
+			 * static cards around it. That combination was reported as a bug and it
+			 * is a choice: a tone that silently changed under an event handler would
+			 * be a worse one.
 			 */
 			tone?: 'elevated' | 'surface' | 'well' | 'flat';
 			/** Rendered above the body with a subtle divider. */

package/dist/ui/card/card.svelte.d.ts

@@ -10,7 +10,7 @@ export declare const cardVariants: import("tailwind-variants").TVReturnType<{
         false: "p-card";
     };
     interactive: {
-        true: "cursor-pointer hover:bg-highlight hover:shadow-highlight focus-visible:bg-highlight era-interactive aria-disabled:cursor-not-allowed aria-disabled:opacity-50";
+        true: "cursor-pointer hover:bg-highlight hover:shadow-highlight focus-visible:bg-highlight active:shadow-pressed era-interactive aria-disabled:cursor-not-allowed aria-disabled:opacity-50";
     };
 }, undefined, "block w-full rounded-bar text-left text-fg", {
     tone: {
@@ -24,7 +24,7 @@ export declare const cardVariants: import("tailwind-variants").TVReturnType<{
         false: "p-card";
     };
     interactive: {
-        true: "cursor-pointer hover:bg-highlight hover:shadow-highlight focus-visible:bg-highlight era-interactive aria-disabled:cursor-not-allowed aria-disabled:opacity-50";
+        true: "cursor-pointer hover:bg-highlight hover:shadow-highlight focus-visible:bg-highlight active:shadow-pressed era-interactive aria-disabled:cursor-not-allowed aria-disabled:opacity-50";
     };
 }, undefined, import("tailwind-variants").TVReturnTypeLike<{
     tone: {
@@ -38,7 +38,7 @@ export declare const cardVariants: import("tailwind-variants").TVReturnType<{
         false: "p-card";
     };
     interactive: {
-        true: "cursor-pointer hover:bg-highlight hover:shadow-highlight focus-visible:bg-highlight era-interactive aria-disabled:cursor-not-allowed aria-disabled:opacity-50";
+        true: "cursor-pointer hover:bg-highlight hover:shadow-highlight focus-visible:bg-highlight active:shadow-pressed era-interactive aria-disabled:cursor-not-allowed aria-disabled:opacity-50";
     };
 }, undefined>>;
 import type { Snippet } from 'svelte';
@@ -50,11 +50,32 @@ type $$ComponentProps = HTMLAttributes<HTMLElement> & AnchorBits & ButtonBits &
     ref?: CardElement | null;
     /**
      * Surface tier the card paints on.
-     * - `elevated` (default): the lifted surface. Use on the page background.
-     * - `surface`: the base surface tier. Use when nesting cards inside another elevated container.
-     * - `well`: recessed. For content the surrounding UI puts INTO the card — a tool's
-     *   output pane, a transcript body — the container twin of a text field's fill.
-     * - `flat`: no background; only the rounded/padded shell. For grouping content visually without adding contrast.
+     * - `elevated` (default): the lifted surface, with a resting shadow. Use
+     *   on the page background.
+     * - `surface`: the base surface tier, no shadow. Use when nesting cards
+     *   inside another elevated container.
+     * - `well`: recessed. For content the surrounding UI puts INTO the card —
+     *   a tool's output pane, a transcript body — the container twin of a
+     *   text field's fill.
+     * - `flat`: no background; only the rounded/padded shell. For grouping
+     *   content visually without adding contrast.
+     *
+     * READ THE CLASSES AND THEY LOOK SWAPPED. They are not, and this is
+     * worth a sentence because a consumer read them, believed it, and
+     * shipped flat cards for months. `surface` paints `bg-well` and `well`
+     * paints `bg-field`, because era's utility names describe FILLS rather
+     * than tiers: `bg-well` is the surface's own resting fill (it is what a
+     * panel is painted with, and it pairs with `shadow-well` when you want
+     * recessed chrome), and `bg-field` is the recessed fill a text input
+     * sits in. The tone names are the tiers; the class names are the paints.
+     *
+     * A CARD THAT IS PRESSABLE SHOULD USUALLY BE `elevated`. Passing `href`
+     * or `onclick` turns on the interactive face — hover, focus, press — but
+     * it deliberately does NOT override the tier you asked for, so a
+     * `surface` link card has no resting lift and reads flatter than the
+     * static cards around it. That combination was reported as a bug and it
+     * is a choice: a tone that silently changed under an event handler would
+     * be a worse one.
      */
     tone?: 'elevated' | 'surface' | 'well' | 'flat';
     /** Rendered above the body with a subtle divider. */

package/dist/ui/meter/meter.svelte

@@ -35,6 +35,7 @@
 </script>
 
 <script lang="ts">
+	import type { Snippet } from 'svelte';
 	import { Meter } from 'bits-ui';
 	import { cn } from '../../utils/index.js';
 
@@ -44,6 +45,8 @@
 		min = 0,
 		max = 100,
 		tone = 'default',
+		start,
+		end,
 		class: className,
 		...restProps
 	}: Meter.RootProps & {
@@ -57,30 +60,73 @@
 		 * `aria-label` / a visible label, never rely on the hue alone.
 		 */
 		tone?: 'default' | 'accent' | 'destructive' | 'success' | 'warning' | 'info';
+		/**
+		 * Captions under the two ends of the bar — what the range MEANS.
+		 *
+		 * A meter states a proportion and leaves the reader to work out what of.
+		 * "0m used" on the left and "50h before approval" on the right is not
+		 * decoration, it is the reading; every consumer of a bare meter ends up
+		 * hand-rolling the same flex row underneath it, which is where this came
+		 * from. `start` is left, `end` is right, either may stand alone.
+		 *
+		 * NOT ANNOUNCED. They are captions, so a screen reader gets the meter's
+		 * value and its own `aria-label`, not these. If the range needs saying
+		 * out loud, say it in the label too — the same rule `tone` carries.
+		 *
+		 * THE DOM IS UNCHANGED WITHOUT THEM. With neither snippet this renders
+		 * exactly the element it always did, so `class` still lands on the track
+		 * and the geometry audits still walk the same box. Passing one wraps the
+		 * track in a column, and `class` still lands on the track.
+		 */
+		start?: Snippet;
+		end?: Snippet;
 	} = $props();
 
 	let percentage = $derived(((value - min) / (max - min)) * 100);
 </script>
 
-<Meter.Root
-	bind:ref
-	{value}
-	{min}
-	{max}
-	data-tone={tone}
-	class={cn(
-		// bg-field, not bg-elevated: the track is recessed (era-track-well), so it
-		// wears the recessed tier. See Checkbox for the full version of this note.
-		// era-track-well, not shadow-well: the fill below covers the whole box,
-		// and an inset shadow paints under its own descendants — so the plain
-		// well survived only on the empty side of the value.
-		'era-track-well h-(--era-sp) w-full overflow-hidden rounded-control bg-field',
-		className
-	)}
-	{...restProps}
->
-	<div
-		class={meterFillVariants({ tone })}
-		style="transform: translateX(-{100 - percentage}%)"
-	></div>
-</Meter.Root>
+{#snippet track()}
+	<Meter.Root
+		bind:ref
+		{value}
+		{min}
+		{max}
+		data-tone={tone}
+		class={cn(
+			// bg-field, not bg-elevated: the track is recessed (era-track-well), so it
+			// wears the recessed tier. See Checkbox for the full version of this note.
+			// era-track-well, not shadow-well: the fill below covers the whole box,
+			// and an inset shadow paints under its own descendants — so the plain
+			// well survived only on the empty side of the value.
+			'era-track-well h-(--era-sp) w-full overflow-hidden rounded-control bg-field',
+			className
+		)}
+		{...restProps}
+	>
+		<div
+			class={meterFillVariants({ tone })}
+			style="transform: translateX(-{100 - percentage}%)"
+		></div>
+	</Meter.Root>
+{/snippet}
+
+<!--
+	The wrapper exists ONLY when a caption does. Rendering it always would change
+	the element every existing consumer measures and styles — the same opt-in the
+	Button and Chip label boxes are built on, for the same reason.
+
+	`justify-between` rather than a grid: with one caption it pins to its own end,
+	which is what a lone "0 used" or a lone "quota" should do. min-w-0 + truncate
+	because a caption is prose and the bar's width is not negotiable.
+-->
+{#if start || end}
+	<div class="flex flex-col gap-gutter">
+		{@render track()}
+		<div class="flex items-baseline justify-between gap-gutter text-body text-muted">
+			<span class="min-w-0 truncate">{@render start?.()}</span>
+			<span class="min-w-0 truncate text-right">{@render end?.()}</span>
+		</div>
+	</div>
+{:else}
+	{@render track()}
+{/if}

package/dist/ui/meter/meter.svelte.d.ts

@@ -26,6 +26,7 @@ export declare const meterFillVariants: import("tailwind-variants").TVReturnType
         info: "bg-info";
     };
 }, undefined>>;
+import type { Snippet } from 'svelte';
 import { Meter } from 'bits-ui';
 type $$ComponentProps = Meter.RootProps & {
     /**
@@ -38,6 +39,26 @@ type $$ComponentProps = Meter.RootProps & {
      * `aria-label` / a visible label, never rely on the hue alone.
      */
     tone?: 'default' | 'accent' | 'destructive' | 'success' | 'warning' | 'info';
+    /**
+     * Captions under the two ends of the bar — what the range MEANS.
+     *
+     * A meter states a proportion and leaves the reader to work out what of.
+     * "0m used" on the left and "50h before approval" on the right is not
+     * decoration, it is the reading; every consumer of a bare meter ends up
+     * hand-rolling the same flex row underneath it, which is where this came
+     * from. `start` is left, `end` is right, either may stand alone.
+     *
+     * NOT ANNOUNCED. They are captions, so a screen reader gets the meter's
+     * value and its own `aria-label`, not these. If the range needs saying
+     * out loud, say it in the label too — the same rule `tone` carries.
+     *
+     * THE DOM IS UNCHANGED WITHOUT THEM. With neither snippet this renders
+     * exactly the element it always did, so `class` still lands on the track
+     * and the geometry audits still walk the same box. Passing one wraps the
+     * track in a column, and `class` still lands on the track.
+     */
+    start?: Snippet;
+    end?: Snippet;
 };
 declare const Meter: import("svelte").Component<$$ComponentProps, {}, "ref">;
 type Meter = ReturnType<typeof Meter>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@signal9/era-ui",
-	"version": "30.4.0",
+	"version": "30.5.1",
 	"scripts": {
 		"dev": "vite dev --host",
 		"build": "vite build && npm run prepack",