@signal9/era-ui 30.4.0 → 30.5.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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/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.0",
 	"scripts": {
 		"dev": "vite dev --host",
 		"build": "vite build && npm run prepack",