entasis 0.11.0 → 0.12.0

package/dist/components/Meter/Meter.svelte

@@ -1,8 +1,15 @@
-<script lang="ts" generics="T = unknown, S = unknown">
+<script lang="ts" generics="T = unknown">
 	import type { MeterProps, MeterStep } from './meter.props.js';
 	import { useMeterTheme } from './meter.theme.js';
 	import Slot from '../Slot/Slot.svelte';
 	import { useSpringState } from '../../utils/spring.svelte.js';
+	import { useI18n } from '../../i18n/context.svelte.js';
+	import {
+		clampRange,
+		formatRangeValue,
+		rangeAriaAttributes,
+		toPercent
+	} from '../../utils/range.js';
 	import { untrack } from 'svelte';
 
 	let {
@@ -17,13 +24,24 @@
 		damping = 1,
 		precision = 0.001,
 		soft = 0.1,
+		min = 0,
 		max = 100,
+		format,
+		getAriaValueText,
+		locale: localeProp,
 		header,
 		label,
 		helper,
 		description,
 		theme
-	}: MeterProps<T, S> = $props();
+	}: MeterProps<T> = $props();
+	const t = $derived(useI18n());
+	const locale = $derived(localeProp ?? t.locale);
+
+	const id = $props.id();
+	const labelId = `${id}-label`;
+	const helperId = `${id}-helper`;
+	const descriptionId = `${id}-description`;
 
 	const spring = useSpringState({
 		get stiffness() {
@@ -45,15 +63,14 @@
 				: [value]
 	);
 
+	// One source of truth for the fill, the visible text and the ARIA values: the segment value is
+	// clamped into [min, max] and measured as (clamped - min) / (max - min). A non-finite value
+	// reads as `min`.
+	const finiteValue = (stepValue: number) => (Number.isFinite(stepValue) ? stepValue : min);
+	const percentOf = (stepValue: number) => toPercent(finiteValue(stepValue), min, max);
+
 	const createMeterSprings = (steps: MeterStep<T>[]) =>
-		steps.map((step) => {
-			const percentage = (step.value / max) * 100;
-			return {
-				percentage,
-				value: spring(step.value),
-				width: spring(percentage)
-			};
-		});
+		steps.map((step) => ({ width: spring(percentOf(step.value)) }));
 
 	let springs = $state(untrack(() => createMeterSprings(meterSteps)));
 
@@ -64,14 +81,56 @@
 			return;
 		}
 		for (const [index, step] of currentSteps.entries()) {
-			springs[index].percentage = (step.value / max) * 100;
-			springs[index].value.set(step.value || 0, { soft });
-			springs[index].width!.set((step.value / max) * 100, { soft });
+			springs[index].width.set(percentOf(step.value), { soft });
 		}
 	});
 
 	const classes = $derived(useMeterTheme(theme));
 
+	// Accessibility. One segment makes the root a `meter`; several make it a `group` of meters,
+	// one per segment. Either root is described by the helper and description. The value text is the indicator text, so what is announced matches what is
+	// drawn, and aria-valuenow is clamped to the scale.
+	const stacked = $derived(meterSteps.length !== 1);
+	const labelRendered = $derived(!header && !!label);
+	// `format` shapes the value text in value mode; the percentage text is the share of the scale.
+	const rangeOptions = (stepValue: number) => ({
+		value: finiteValue(stepValue),
+		min,
+		max,
+		locale,
+		format: showIndicatorAs === 'value' ? (format ?? {}) : undefined
+	});
+	const valueText = (step: MeterStep<T>) => formatRangeValue(rangeOptions(step.value));
+	const ariaValues = (step: MeterStep<T>) =>
+		rangeAriaAttributes({
+			...rangeOptions(step.value),
+			getAriaValueText:
+				getAriaValueText &&
+				((formattedValue, rawValue) =>
+					getAriaValueText({
+						value: clampRange(rawValue ?? min, min, max),
+						formattedValue,
+						min,
+						max
+					}))
+		});
+	const rootAria = $derived(stacked ? undefined : ariaValues(meterSteps[0]));
+	// A custom `header` replaces the rendered label, so a string label still names the meter
+	// directly. A single segment object can name it with its own label; the catalog name is the
+	// last resort so every meter is announced with a name.
+	const rootName = $derived.by(() => {
+		if (labelRendered) return undefined;
+		if (typeof label === 'string' && label) return label;
+		if (stacked) return undefined;
+		if (typeof value !== 'number' && meterSteps[0]?.label) return meterSteps[0].label;
+		return t.meter;
+	});
+	const describedBy = $derived(
+		[!header && helper ? helperId : undefined, description ? descriptionId : undefined]
+			.filter(Boolean)
+			.join(' ') || undefined
+	);
+
 	const labelsPositions = $derived(meterSteps.map((step) => step.position || 'top'));
 	const labelsPosition: 'top' | 'bottom' | 'both' | undefined = $derived(
 		labelsPositions.includes('top') && labelsPositions.includes('bottom')
@@ -84,19 +143,22 @@
 
 {#snippet meter(index: number, meter: MeterStep<T>)}
 	{@const spring = springs[index]}
+	{@const aria = stacked ? ariaValues(meter) : undefined}
 	<div
 		data-first={index === 0}
 		data-last={index === springs.length - 1}
 		data-color={meter.color ?? color}
+		role={stacked ? 'meter' : undefined}
+		aria-label={stacked ? meter.label || t.meterSegment(index + 1, meterSteps.length) : undefined}
+		aria-valuemin={aria?.['aria-valuemin']}
+		aria-valuemax={aria?.['aria-valuemax']}
+		aria-valuenow={aria?.['aria-valuenow']}
+		aria-valuetext={aria?.['aria-valuetext']}
 		style:width="{spring.width.current}%"
 		class={classes.container({ first: index === 0, last: index === springs.length - 1 })}
 	>
 		{#snippet indicatorContent()}
-			{showIndicatorAs === 'value'
-				? meter.value.toFixed(0)
-				: showIndicatorAs === 'percentage'
-					? `${spring.percentage.toFixed(0)}%`
-					: ''}
+			{showIndicatorAs ? valueText(meter) : ''}
 		{/snippet}
 		<Slot
 			as="span"
@@ -109,14 +171,35 @@
 		/>
 
 		<div class={classes.progress({ size })}></div>
+		{#if stacked}
+			<!-- Forces NVDA to read the meter's name (mui/base-ui#4184). -->
+			<span role="presentation" class="sr-only">x</span>
+		{/if}
 	</div>
 {/snippet}
 
 {#snippet headerSnippet()}
-	<Slot class={classes.label({ size })} render={label} />
-	<Slot class={classes.helper({ size })} render={helper} />
+	{#if label}
+		<!-- role="presentation" completes the NVDA workaround (mui/base-ui#4200): NVDA skips a name
+		     that comes from a label inside the meter (nvaccess/nvda#16204). aria-labelledby still
+		     resolves through a presentational element. -->
+		<div id={labelId} role="presentation" class={classes.label({ size })}>
+			{#if typeof label === 'string'}{label}{:else}{@render label()}{/if}
+		</div>
+	{/if}
+	<Slot class={classes.helper({ size })} render={helper} attrs={{ id: helperId }} />
 {/snippet}
-<div class={classes.root({ size, className })}>
+<div
+	class={classes.root({ size, className })}
+	role={stacked ? 'group' : 'meter'}
+	aria-labelledby={labelRendered ? labelId : undefined}
+	aria-label={rootName}
+	aria-describedby={describedBy}
+	aria-valuemin={rootAria?.['aria-valuemin']}
+	aria-valuemax={rootAria?.['aria-valuemax']}
+	aria-valuenow={rootAria?.['aria-valuenow']}
+	aria-valuetext={rootAria?.['aria-valuetext']}
+>
 	<Slot
 		class={classes.header({ size })}
 		renderIf={!!(header || label || helper)}
@@ -130,7 +213,6 @@
 	{#if showLegend}
 		<div class={classes.legend({ size })}>
 			{#each meterSteps as meterItem, i (i)}
-				{@const percentage = (meterItem.value / max) * 100}
 				<div data-color={meterItem.color ?? color} class={classes.legendItem({ size })}>
 					{#if meterItem.icon}
 						<div class={classes.legendIcon({ size })}>
@@ -141,11 +223,15 @@
 						<span class={classes.legendLabel({ size })}>{meterItem.label}</span>
 					{/if}
 					<span class={classes.legendPercentage({ size })}>
-						{percentage.toFixed(0)}%
+						{formatRangeValue({ value: finiteValue(meterItem.value), min, max, locale })}
 					</span>
 				</div>
 			{/each}
 		</div>
 	{/if}
-	<Slot class={classes.description({ size })} render={description} />
+	<Slot class={classes.description({ size })} render={description} attrs={{ id: descriptionId }} />
+	{#if !stacked}
+		<!-- Forces NVDA to read the meter's name (mui/base-ui#4184). -->
+		<span role="presentation" class="sr-only">x</span>
+	{/if}
 </div>

package/dist/components/Meter/Meter.svelte.d.ts

@@ -1,25 +1,25 @@
 import type { MeterProps } from './meter.props.js';
-declare function $$render<T = unknown, S = unknown>(): {
-    props: MeterProps<T, S>;
+declare function $$render<T = unknown>(): {
+    props: MeterProps<T>;
     exports: {};
     bindings: "";
     slots: {};
     events: {};
 };
-declare class __sveltets_Render<T = unknown, S = unknown> {
-    props(): ReturnType<typeof $$render<T, S>>['props'];
-    events(): ReturnType<typeof $$render<T, S>>['events'];
-    slots(): ReturnType<typeof $$render<T, S>>['slots'];
+declare class __sveltets_Render<T = unknown> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
     bindings(): "";
     exports(): {};
 }
 interface $$IsomorphicComponent {
-    new <T = unknown, S = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T, S>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T, S>['props']>, ReturnType<__sveltets_Render<T, S>['events']>, ReturnType<__sveltets_Render<T, S>['slots']>> & {
-        $$bindings?: ReturnType<__sveltets_Render<T, S>['bindings']>;
-    } & ReturnType<__sveltets_Render<T, S>['exports']>;
-    <T = unknown, S = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<T, S>['props']> & {}): ReturnType<__sveltets_Render<T, S>['exports']>;
-    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
+    new <T = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
 declare const Meter: $$IsomorphicComponent;
-type Meter<T = unknown, S = unknown> = InstanceType<typeof Meter<T, S>>;
+type Meter<T = unknown> = InstanceType<typeof Meter<T>>;
 export default Meter;

package/dist/components/Meter/meter.mcp.d.ts

@@ -1 +1 @@
-export declare const meterDescription = "\n# Meter Component\n\nThe Meter component visualizes a measurement or progress along a known scale, with support for multiple values, steps, labels, and animations.\n\n## Basic Usage\n\n```svelte\n<Meter value={75} label=\"Progress\" />\n```\n\n## Props\n\n### Core Props\n- **value**: number | MeterStep<T> | Array<MeterStep<T>> (required) - A plain number, one segment, or a stacked set of segments\n  - A number renders a single segment coloured by `color`; its legend label defaults to the number itself\n  - Each segment object: { value: number, label?: string, color?: Colors, icon?: Snippet, position?: 'top' | 'bottom', data?: T }\n- **color**: Colors (default: 'primary') - Color used for a numeric value and as the fallback for segments with no color of their own\n\n- **min**: number (default: 0) - Minimum value\n- **max**: number (default: 100) - Maximum value\n- **size**: 'small' | 'normal' | 'large' - Visual size of the meter\n\n### Display Props\n- **showIndicatorAs**: 'value' | 'percentage' - How to display the indicator label\n\n### Steps\n- **steps**: Array<Step<S>> - Predefined steps/milestones on the meter\n  - Each step: { start: number, end?: number, label: Slot, color: Colors, position?: 'top' | 'bottom', class?: string, labelClass?: string, data?: S }\n\n### Content Slots\n- **label**: Snippet - Custom label\n- **description**: Snippet - Description text\n- **helper**: Snippet - Helper text\n- **header**: Snippet - Custom header\n- **indicator**: string | Snippet - Custom indicator content (no payload); combine with `showIndicatorAs` for the built-in value/percentage text\n\n### Animation Props\n- **stiffness**: number - Spring animation stiffness\n- **damping**: number - Spring animation damping\n- **soft**: number - Softness of animation\n- **precision**: number - Precision of animated values\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Structure\n\n```\n<Meter>\n\t<Header>\n\t\t<Label />\n\t\t<Description />\n\t</Header>\n\t<Track>\n\t\t<Progress />\n\t\t<Indicator />\n\t\t<Steps />\n\t</Track>\n\t<Helper />\n</Meter>\n```\n\n## Examples\n\n### Simple Progress Bar\n```svelte\n<Meter value={65} />\n```\n\n### Basic Meter\n```svelte\n<Meter value={60} label=\"Completion\" />\n```\n\n### With Label and Description\n```svelte\n<Meter \n\tvalue={75}\n>\n\t{#snippet label()}\n\t\t<span>Progress</span>\n\t{/snippet}\n\t{#snippet description()}\n\t\t<span>75% complete</span>\n\t{/snippet}\n</Meter>\n```\n\n### Different Colors\n```svelte\n<Meter value={30} color=\"danger\" label=\"Low\" />\n<Meter value={60} color=\"warning\" label=\"Medium\" />\n<Meter value={90} color=\"success\" label=\"High\" />\n```\n\n### Multiple Values (Stacked)\n```svelte\n<Meter \n\tvalue={[\n\t\t{ value: 40, color: 'primary', label: 'Used' },\n\t\t{ value: 30, color: 'secondary', label: 'Reserved' }\n\t]}\n\tmax={100}\n/>\n```\n\n### With Steps\n```svelte\n<Meter \n\tvalue={65}\n\tsteps={[\n\t\t{ start: 0, end: 25, label: 'Low', color: 'danger' },\n\t\t{ start: 25, end: 75, label: 'Medium', color: 'warning' },\n\t\t{ start: 75, end: 100, label: 'High', color: 'success' }\n\t]}\n/>\n```\n\n### Show as Percentage\n```svelte\n<Meter \n\tvalue={45}\n\tshowIndicatorAs=\"percentage\"\n/>\n```\n\n### Different Sizes\n```svelte\n<Meter size=\"small\" value={50} />\n<Meter size=\"normal\" value={50} />\n<Meter size=\"large\" value={50} />\n```\n\n### Custom Range\n```svelte\n<Meter \n\tmin={0}\n\tmax={1000}\n\tvalue={350}\n\tlabel=\"Score\"\n/>\n```\n\n### Storage Usage Example\n```svelte\n<script>\n\tlet storage = {\n\t\tused: 45,\n\t\tcached: 20,\n\t\tavailable: 35\n\t};\n</script>\n\n<Meter \n\tvalue={[\n\t\t{ value: storage.used, color: 'primary', label: 'Used' },\n\t\t{ value: storage.cached, color: 'info', label: 'Cached' }\n\t]}\n\tmax={100}\n>\n\t{#snippet header()}\n\t\t<div class=\"flex justify-between\">\n\t\t\t<span>Storage</span>\n\t\t\t<span>{storage.used + storage.cached}GB / 100GB</span>\n\t\t</div>\n\t{/snippet}\n\t{#snippet helper()}\n\t\t{storage.available}GB available\n\t{/snippet}\n</Meter>\n```\n\n### Task Progress\n```svelte\n<script>\n\tlet tasks = {\n\t\tcompleted: 12,\n\t\ttotal: 20\n\t};\n\tlet progress = (tasks.completed / tasks.total) * 100;\n</script>\n\n<Meter \n\tvalue={progress}\n\tcolor=\"success\"\n>\n\t{#snippet label()}\n\t\tTask Progress\n\t{/snippet}\n\t{#snippet description()}\n\t\t{tasks.completed} of {tasks.total} tasks completed\n\t{/snippet}\n</Meter>\n```\n\n### With Custom Indicator\n```svelte\n<!-- indicator is a payload-less slot; use showIndicatorAs for the built-in value/percentage text -->\n<Meter value={75}>\n\t{#snippet indicator()}\n\t\t<div class=\"custom-indicator\">75 / 100</div>\n\t{/snippet}\n</Meter>\n```\n\n### Skill Level Meter\n```svelte\n<Meter \n\tvalue={85}\n\tcolor=\"info\"\n\tsteps={[\n\t\t{ start: 0, end: 30, label: 'Beginner', color: 'danger', position: 'bottom' },\n\t\t{ start: 30, end: 70, label: 'Intermediate', color: 'warning', position: 'bottom' },\n\t\t{ start: 70, end: 100, label: 'Expert', color: 'success', position: 'bottom' }\n\t]}\n>\n\t{#snippet label()}\n\t\tJavaScript Proficiency\n\t{/snippet}\n</Meter>\n```\n\n## Accessibility\n\n- Uses semantic HTML meter/progress elements\n- Labels provide context for screen readers\n- ARIA attributes for current value and range\n- Visual indicators have text alternatives\n\n## Notes\n\n- Values are animated with spring physics for smooth transitions\n- Multiple values stack horizontally\n- Steps provide visual milestones and labels\n- Indicator position can be top or bottom\n- Progress bar fills from left to right\n- The root `color` prop colors the whole meter; a segment's own `color` overrides it\n\n## Theme Customization\n\nThe Meter component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main meter container styles\n- **header**: Header section styles\n- **container**: Progress container styles\n- **label**: Label text styles\n- **helper**: Helper text styles\n- **description**: Description text styles\n- **progress**: Progress bar element styles\n- **track**: Track/background styles\n- **indicator**: Value indicator styles\n- **legend**: Legend container styles\n- **legendItem**: Legend item styles\n- **legendIcon**: Legend icon styles\n- **legendLabel**: Legend label text styles\n- **legendPercentage**: Legend percentage text styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for main container\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Container gap size\n\n**header**:\n- base: Base classes for header section\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Gap between elements\n\n**container**:\n- base: Base classes for progress container\n- Variants:\n  - first: boolean - First segment styling (rounded left)\n  - last: boolean - Last segment styling (rounded right)\n\n**label**:\n- base: Base classes for label text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n\n**helper**:\n- base: Base classes for helper text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n\n**description**:\n- base: Base classes for description text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n\n**progress**:\n- base: Base classes for progress bar\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Bar height\n\n**track**:\n- base: Base classes for track/background\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Track height\n  - labelsPosition: 'top' | 'bottom' | 'both' - Margin based on label position\n\n**indicator**:\n- base: Base classes for value indicator\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - position: 'top' | 'bottom' - Indicator position\n\n**legend**:\n- base: Base classes for legend container\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Legend size\n\n**legendItem**:\n- base: Base classes for legend items\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Gap between elements\n\n**legendIcon**:\n- base: Base classes for legend icons\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n\n**legendLabel**:\n- base: Base classes for legend labels\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n\n**legendPercentage**:\n- base: Base classes for legend percentages\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Meter \n  value={75}\n  theme={{\n    root: {\n      base: 'flex flex-col',\n      size: {\n        normal: 'gap-2'\n      }\n    },\n    track: {\n      base: 'rounded-full bg-gray-200',\n      size: {\n        normal: 'h-2'\n      }\n    }\n  }}\n/>\n```\n\n**Custom Progress Bar**:\n```svelte\n<Meter \n  value={60}\n  theme={{\n    progress: {\n      base: 'bg-gradient-to-r from-primary to-secondary',\n      size: {\n        large: 'h-4'\n      }\n    },\n    track: {\n      base: 'bg-gray-100 rounded-full',\n      size: {\n        large: 'h-4'\n      }\n    },\n    indicator: {\n      base: 'text-sm font-semibold',\n      position: {\n        top: 'bottom-full mb-2'\n      }\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setMeterTheme } from './index.ts';\n  \n  setMeterTheme({\n    root: {\n      base: 'flex flex-col',\n      size: {\n        normal: 'gap-2'\n      }\n    },\n    track: {\n      base: 'rounded-full bg-gray-200',\n      size: {\n        normal: 'h-2'\n      }\n    },\n    progress: {\n      base: 'bg-primary rounded-full'\n    }\n  });\n</script>\n```\n";
+export declare const meterDescription = "\n# Meter Component\n\nThe Meter component visualizes a measurement or progress along a known scale, with support for stacked segments, labels, and animations.\n\n## Basic Usage\n\n```svelte\n<Meter value={75} label=\"Progress\" />\n```\n\n## Props\n\n### Core Props\n- **value**: number | MeterStep<T> | Array<MeterStep<T>> (required) - A plain number, one segment, or a stacked set of segments\n  - A number renders a single segment coloured by `color`; its legend label defaults to the number itself\n  - Each segment object: { value: number, label?: string, color?: Colors, icon?: Snippet, position?: 'top' | 'bottom', data?: T }\n- **color**: Colors (default: 'primary') - Color used for a numeric value and as the fallback for segments with no color of their own\n\n- **min**: number (default: 0) - Minimum value of the scale; a segment fills (value - min) / (max - min) of the track\n- **max**: number (default: 100) - Maximum value of the scale; values are clamped into [min, max], so a bar never passes the track\n- **size**: 'small' | 'normal' | 'large' - Visual size of the meter\n\n### Display Props\n- **showIndicatorAs**: 'value' | 'percentage' - How to display the indicator label\n- **format**: Intl.NumberFormatOptions - Formats the clamped value in value mode (for example { style: 'unit', unit: 'megabyte' }); the percentage text is always the share of the scale\n- **getAriaValueText**: (payload: { value, formattedValue, min, max }) => string - Overrides aria-valuetext, which otherwise mirrors the indicator text\n- **locale**: Intl.LocalesArgument - Locale of the value and percentage text (default: the I18n locale, so French reads \"50 %\")\n\n### Content Slots\n- **label**: string | Snippet - Label rendered in the header; it names the meter (or the group of stacked meters)\n- **description**: string | Snippet - Description text; describes the meter\n- **helper**: string | Snippet - Helper text shown beside the label; describes the meter\n- **header**: Snippet - Custom header\n- **indicator**: string | Snippet - Custom indicator content (no payload); combine with `showIndicatorAs` for the built-in value/percentage text\n\n### Animation Props\n- **stiffness**: number - Spring animation stiffness\n- **damping**: number - Spring animation damping\n- **soft**: number - Softness of animation\n- **precision**: number - Precision of animated values\n\n### Styling Props\n- **class**: string - Additional CSS classes\n- **theme**: ComponentTheme - Custom theme overrides\n\n## Structure\n\n```\n<Meter>\n\t<Header>\n\t\t<Label />\n\t\t<Description />\n\t</Header>\n\t<Track>\n\t\t<Progress />\n\t\t<Indicator />\n\t</Track>\n\t<Helper />\n</Meter>\n```\n\n## Examples\n\n### Simple Progress Bar\n```svelte\n<Meter value={65} />\n```\n\n### Basic Meter\n```svelte\n<Meter value={60} label=\"Completion\" />\n```\n\n### With Label and Description\n```svelte\n<Meter \n\tvalue={75}\n>\n\t{#snippet label()}\n\t\t<span>Progress</span>\n\t{/snippet}\n\t{#snippet description()}\n\t\t<span>75% complete</span>\n\t{/snippet}\n</Meter>\n```\n\n### Different Colors\n```svelte\n<Meter value={30} color=\"danger\" label=\"Low\" />\n<Meter value={60} color=\"warning\" label=\"Medium\" />\n<Meter value={90} color=\"success\" label=\"High\" />\n```\n\n### Multiple Values (Stacked)\n```svelte\n<Meter \n\tvalue={[\n\t\t{ value: 40, color: 'primary', label: 'Used' },\n\t\t{ value: 30, color: 'secondary', label: 'Reserved' }\n\t]}\n\tmax={100}\n/>\n```\n\n### Formatted Value\n```svelte\n<Meter\n\tvalue={1536}\n\tmax={4096}\n\tshowIndicatorAs=\"value\"\n\tformat={{ style: 'unit', unit: 'megabyte', unitDisplay: 'short' }}\n\tgetAriaValueText={({ formattedValue, max }) => `${formattedValue} of ${max} megabytes used`}\n\tlabel=\"Memory\"\n/>\n```\n\n### Show as Percentage\n```svelte\n<Meter \n\tvalue={45}\n\tshowIndicatorAs=\"percentage\"\n/>\n```\n\n### Different Sizes\n```svelte\n<Meter size=\"small\" value={50} />\n<Meter size=\"normal\" value={50} />\n<Meter size=\"large\" value={50} />\n```\n\n### Custom Range\n```svelte\n<Meter \n\tmin={0}\n\tmax={1000}\n\tvalue={350}\n\tlabel=\"Score\"\n/>\n```\n\n### Storage Usage Example\n```svelte\n<script>\n\tlet storage = {\n\t\tused: 45,\n\t\tcached: 20,\n\t\tavailable: 35\n\t};\n</script>\n\n<Meter \n\tvalue={[\n\t\t{ value: storage.used, color: 'primary', label: 'Used' },\n\t\t{ value: storage.cached, color: 'info', label: 'Cached' }\n\t]}\n\tmax={100}\n>\n\t{#snippet header()}\n\t\t<div class=\"flex justify-between\">\n\t\t\t<span>Storage</span>\n\t\t\t<span>{storage.used + storage.cached}GB / 100GB</span>\n\t\t</div>\n\t{/snippet}\n\t{#snippet helper()}\n\t\t{storage.available}GB available\n\t{/snippet}\n</Meter>\n```\n\n### Task Progress\n```svelte\n<script>\n\tlet tasks = {\n\t\tcompleted: 12,\n\t\ttotal: 20\n\t};\n\tlet progress = (tasks.completed / tasks.total) * 100;\n</script>\n\n<Meter \n\tvalue={progress}\n\tcolor=\"success\"\n>\n\t{#snippet label()}\n\t\tTask Progress\n\t{/snippet}\n\t{#snippet description()}\n\t\t{tasks.completed} of {tasks.total} tasks completed\n\t{/snippet}\n</Meter>\n```\n\n### With Custom Indicator\n```svelte\n<!-- indicator is a payload-less slot; use showIndicatorAs for the built-in value/percentage text -->\n<Meter value={75}>\n\t{#snippet indicator()}\n\t\t<div class=\"custom-indicator\">75 / 100</div>\n\t{/snippet}\n</Meter>\n```\n\n### Skill Level Meter\n```svelte\n<Meter value={85} color=\"success\" label=\"JavaScript Proficiency\" />\n```\n\n## Accessibility\n\n- A single value makes the root `role=\"meter\"` with `aria-valuemin` (`min`), `aria-valuemax` (`max`), `aria-valuenow` (the value clamped to the scale) and `aria-valuetext` (the indicator text computed from the clamped value over the scale, e.g. \"65%\" or \"50 %\" in French, or the formatted raw value with `showIndicatorAs=\"value\"`; `getAriaValueText` overrides it)\n- The meter is named by the rendered `label` (`aria-labelledby`). With a custom `header`, a string `label` names it through `aria-label`; without any label it falls back to a single segment's own `label`, then to the i18n `meter` text\n- `helper` and `description` describe the root (the meter, or the group of stacked meters) through `aria-describedby`\n- Several segments make the root a `role=\"group\"` named by `label`, containing one `role=\"meter\"` per segment named by the segment's `label` (or \"Segment 1 of 3\", i18n `meterSegment`)\n- Each meter contains a visually hidden presentational text node, and the rendered label element is `role=\"presentation\"`, so NVDA reads its name\n\n## Notes\n\n- Values are animated with spring physics for smooth transitions\n- Multiple values stack horizontally\n- Indicator position can be top or bottom\n- Progress bar fills from left to right\n- The root `color` prop colors the whole meter; a segment's own `color` overrides it\n\n## Theme Customization\n\nThe Meter component uses a theme object that can be customized using the `theme` prop or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **root**: Main meter container styles\n- **header**: Header section styles\n- **container**: Progress container styles\n- **label**: Label text styles\n- **helper**: Helper text styles\n- **description**: Description text styles\n- **progress**: Progress bar element styles\n- **track**: Track/background styles\n- **indicator**: Value indicator styles\n- **legend**: Legend container styles\n- **legendItem**: Legend item styles\n- **legendIcon**: Legend icon styles\n- **legendLabel**: Legend label text styles\n- **legendPercentage**: Legend percentage text styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for main container\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Container gap size\n\n**header**:\n- base: Base classes for header section\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Gap between elements\n\n**container**:\n- base: Base classes for progress container\n- Variants:\n  - first: boolean - First segment styling (rounded left)\n  - last: boolean - Last segment styling (rounded right)\n\n**label**:\n- base: Base classes for label text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n\n**helper**:\n- base: Base classes for helper text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n\n**description**:\n- base: Base classes for description text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n\n**progress**:\n- base: Base classes for progress bar\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Bar height\n\n**track**:\n- base: Base classes for track/background\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Track height\n  - labelsPosition: 'top' | 'bottom' | 'both' - Margin based on label position\n\n**indicator**:\n- base: Base classes for value indicator\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - position: 'top' | 'bottom' - Indicator position\n\n**legend**:\n- base: Base classes for legend container\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Legend size\n\n**legendItem**:\n- base: Base classes for legend items\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Gap between elements\n\n**legendIcon**:\n- base: Base classes for legend icons\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n\n**legendLabel**:\n- base: Base classes for legend labels\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n\n**legendPercentage**:\n- base: Base classes for legend percentages\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n\n### Usage Examples\n\n**Basic Theme Override**:\n```svelte\n<Meter \n  value={75}\n  theme={{\n    root: {\n      base: 'flex flex-col',\n      size: {\n        normal: 'gap-2'\n      }\n    },\n    track: {\n      base: 'rounded-full bg-gray-200',\n      size: {\n        normal: 'h-2'\n      }\n    }\n  }}\n/>\n```\n\n**Custom Progress Bar**:\n```svelte\n<Meter \n  value={60}\n  theme={{\n    progress: {\n      base: 'bg-gradient-to-r from-primary to-secondary',\n      size: {\n        large: 'h-4'\n      }\n    },\n    track: {\n      base: 'bg-gray-100 rounded-full',\n      size: {\n        large: 'h-4'\n      }\n    },\n    indicator: {\n      base: 'text-sm font-semibold',\n      position: {\n        top: 'bottom-full mb-2'\n      }\n    }\n  }}\n/>\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setMeterTheme } from './index.ts';\n  \n  setMeterTheme({\n    root: {\n      base: 'flex flex-col',\n      size: {\n        normal: 'gap-2'\n      }\n    },\n    track: {\n      base: 'rounded-full bg-gray-200',\n      size: {\n        normal: 'h-2'\n      }\n    },\n    progress: {\n      base: 'bg-primary rounded-full'\n    }\n  });\n</script>\n```\n";

package/dist/components/Meter/meter.mcp.js

@@ -1,7 +1,7 @@
 export const meterDescription = `
 # Meter Component
 
-The Meter component visualizes a measurement or progress along a known scale, with support for multiple values, steps, labels, and animations.
+The Meter component visualizes a measurement or progress along a known scale, with support for stacked segments, labels, and animations.
 
 ## Basic Usage
 
@@ -17,21 +17,20 @@ The Meter component visualizes a measurement or progress along a known scale, wi
   - Each segment object: { value: number, label?: string, color?: Colors, icon?: Snippet, position?: 'top' | 'bottom', data?: T }
 - **color**: Colors (default: 'primary') - Color used for a numeric value and as the fallback for segments with no color of their own
 
-- **min**: number (default: 0) - Minimum value
-- **max**: number (default: 100) - Maximum value
+- **min**: number (default: 0) - Minimum value of the scale; a segment fills (value - min) / (max - min) of the track
+- **max**: number (default: 100) - Maximum value of the scale; values are clamped into [min, max], so a bar never passes the track
 - **size**: 'small' | 'normal' | 'large' - Visual size of the meter
 
 ### Display Props
 - **showIndicatorAs**: 'value' | 'percentage' - How to display the indicator label
-
-### Steps
-- **steps**: Array<Step<S>> - Predefined steps/milestones on the meter
-  - Each step: { start: number, end?: number, label: Slot, color: Colors, position?: 'top' | 'bottom', class?: string, labelClass?: string, data?: S }
+- **format**: Intl.NumberFormatOptions - Formats the clamped value in value mode (for example { style: 'unit', unit: 'megabyte' }); the percentage text is always the share of the scale
+- **getAriaValueText**: (payload: { value, formattedValue, min, max }) => string - Overrides aria-valuetext, which otherwise mirrors the indicator text
+- **locale**: Intl.LocalesArgument - Locale of the value and percentage text (default: the I18n locale, so French reads "50 %")
 
 ### Content Slots
-- **label**: Snippet - Custom label
-- **description**: Snippet - Description text
-- **helper**: Snippet - Helper text
+- **label**: string | Snippet - Label rendered in the header; it names the meter (or the group of stacked meters)
+- **description**: string | Snippet - Description text; describes the meter
+- **helper**: string | Snippet - Helper text shown beside the label; describes the meter
 - **header**: Snippet - Custom header
 - **indicator**: string | Snippet - Custom indicator content (no payload); combine with \`showIndicatorAs\` for the built-in value/percentage text
 
@@ -56,7 +55,6 @@ The Meter component visualizes a measurement or progress along a known scale, wi
 	<Track>
 		<Progress />
 		<Indicator />
-		<Steps />
 	</Track>
 	<Helper />
 </Meter>
@@ -106,15 +104,15 @@ The Meter component visualizes a measurement or progress along a known scale, wi
 />
 \`\`\`
 
-### With Steps
+### Formatted Value
 \`\`\`svelte
-<Meter 
-	value={65}
-	steps={[
-		{ start: 0, end: 25, label: 'Low', color: 'danger' },
-		{ start: 25, end: 75, label: 'Medium', color: 'warning' },
-		{ start: 75, end: 100, label: 'High', color: 'success' }
-	]}
+<Meter
+	value={1536}
+	max={4096}
+	showIndicatorAs="value"
+	format={{ style: 'unit', unit: 'megabyte', unitDisplay: 'short' }}
+	getAriaValueText={({ formattedValue, max }) => \`\${formattedValue} of \${max} megabytes used\`}
+	label="Memory"
 />
 \`\`\`
 
@@ -207,33 +205,21 @@ The Meter component visualizes a measurement or progress along a known scale, wi
 
 ### Skill Level Meter
 \`\`\`svelte
-<Meter 
-	value={85}
-	color="info"
-	steps={[
-		{ start: 0, end: 30, label: 'Beginner', color: 'danger', position: 'bottom' },
-		{ start: 30, end: 70, label: 'Intermediate', color: 'warning', position: 'bottom' },
-		{ start: 70, end: 100, label: 'Expert', color: 'success', position: 'bottom' }
-	]}
->
-	{#snippet label()}
-		JavaScript Proficiency
-	{/snippet}
-</Meter>
+<Meter value={85} color="success" label="JavaScript Proficiency" />
 \`\`\`
 
 ## Accessibility
 
-- Uses semantic HTML meter/progress elements
-- Labels provide context for screen readers
-- ARIA attributes for current value and range
-- Visual indicators have text alternatives
+- A single value makes the root \`role="meter"\` with \`aria-valuemin\` (\`min\`), \`aria-valuemax\` (\`max\`), \`aria-valuenow\` (the value clamped to the scale) and \`aria-valuetext\` (the indicator text computed from the clamped value over the scale, e.g. "65%" or "50 %" in French, or the formatted raw value with \`showIndicatorAs="value"\`; \`getAriaValueText\` overrides it)
+- The meter is named by the rendered \`label\` (\`aria-labelledby\`). With a custom \`header\`, a string \`label\` names it through \`aria-label\`; without any label it falls back to a single segment's own \`label\`, then to the i18n \`meter\` text
+- \`helper\` and \`description\` describe the root (the meter, or the group of stacked meters) through \`aria-describedby\`
+- Several segments make the root a \`role="group"\` named by \`label\`, containing one \`role="meter"\` per segment named by the segment's \`label\` (or "Segment 1 of 3", i18n \`meterSegment\`)
+- Each meter contains a visually hidden presentational text node, and the rendered label element is \`role="presentation"\`, so NVDA reads its name
 
 ## Notes
 
 - Values are animated with spring physics for smooth transitions
 - Multiple values stack horizontally
-- Steps provide visual milestones and labels
 - Indicator position can be top or bottom
 - Progress bar fills from left to right
 - The root \`color\` prop colors the whole meter; a segment's own \`color\` overrides it

package/dist/components/Meter/meter.props.d.ts

@@ -1,10 +1,12 @@
 import type { Snippet } from 'svelte';
 import type { Colors, Sizes } from '../../types/theme.js';
-import type { Slot, WithSlot } from '../Slot/slot.js';
+import type { WithSlot } from '../Slot/slot.js';
 import type { MeterThemeProps } from './meter.theme.js';
 export type MeterStep<T = unknown> = {
     /**
-     * Label shown for this segment in the legend when `showLegend` is enabled.
+     * Label shown for this segment in the legend when `showLegend` is enabled. In a stacked meter
+     * it is also the accessible name of the segment's `meter`; an unlabelled segment is announced
+     * as "Segment 1 of 3" from the i18n catalog.
      */
     label?: string;
     /**
@@ -28,41 +30,7 @@ export type MeterStep<T = unknown> = {
      */
     data?: T;
 };
-type Step<T = unknown> = {
-    /**
-     * Scale value where this background step segment begins.
-     */
-    start: number;
-    /**
-     * Scale value where this background step segment ends.
-     */
-    end?: number;
-    /**
-     * Vertical placement of the step label relative to the track.
-     */
-    position?: 'top' | 'bottom';
-    /**
-     * Additional CSS classes for the step segment element.
-     */
-    class?: string;
-    /**
-     * Additional CSS classes for the step label element.
-     */
-    labelClass?: string;
-    /**
-     * Theme color of the step segment.
-     */
-    color: Colors;
-    /**
-     * Slot content rendered as the step label.
-     */
-    label: Slot;
-    /**
-     * Arbitrary metadata attached to this step definition.
-     */
-    data?: T;
-};
-export type MeterProps<T = unknown, S = unknown> = WithSlot<WithSlot<{
+export type MeterProps<T = unknown> = WithSlot<WithSlot<{
     /**
      * Additional CSS classes for the root meter container.
      */
@@ -76,6 +44,11 @@ export type MeterProps<T = unknown, S = unknown> = WithSlot<WithSlot<{
      * on the track. A number renders a single segment coloured by `color` whose
      * legend label defaults to the number itself.
      *
+     * One segment makes the root a `role="meter"` named by `label`; several segments make
+     * it a `role="group"` named by `label` with one `meter` per segment. Each meter reports
+     * `aria-valuemin`, `aria-valuemax`, the value clamped to the scale as `aria-valuenow`,
+     * and the indicator text as `aria-valuetext`.
+     *
      * @readonly-value Meter draws a measurement it never edits.
      */
     value: number | MeterStep<T> | MeterStep<T>[];
@@ -84,10 +57,6 @@ export type MeterProps<T = unknown, S = unknown> = WithSlot<WithSlot<{
      * for segments that declare no color of their own.
      */
     color?: Colors;
-    /**
-     * Colored range segments overlaid along the meter scale.
-     */
-    steps?: Step<S>[];
     /**
      * When true, renders a legend listing each segment's label and percentage.
      */
@@ -109,13 +78,37 @@ export type MeterProps<T = unknown, S = unknown> = WithSlot<WithSlot<{
      */
     precision?: number;
     /**
-     * Minimum value of the meter scale.
+     * Minimum value of the meter scale, reported as `aria-valuemin`. A segment fills
+     * `(value - min) / (max - min)` of the track.
+     * @default 0
      */
     min?: number;
     /**
-     * Maximum value of the meter scale used for percentage calculations.
+     * Maximum value of the meter scale, reported as `aria-valuemax`. Values are clamped into
+     * `[min, max]`, so a segment never draws past the track and `aria-valuenow` stays in range.
+     * @default 100
      */
     max?: number;
+    /**
+     * `Intl.NumberFormat` options for the value text when `showIndicatorAs` is `'value'`
+     * (`{ style: 'unit', unit: 'megabyte' }`). The clamped value is formatted in the active
+     * I18n locale. The percentage text is always the share of the scale.
+     */
+    format?: Intl.NumberFormatOptions;
+    /**
+     * Overrides the `aria-valuetext` of a meter, which otherwise mirrors the indicator text.
+     * Receives the clamped value, its formatted text and the scale bounds.
+     */
+    getAriaValueText?: (payload: {
+        value: number;
+        formattedValue: string;
+        min: number;
+        max: number;
+    }) => string;
+    /**
+     * Locale used to format the value and percentage text. Defaults to the I18n locale.
+     */
+    locale?: Intl.LocalesArgument;
     /**
      * Visual size variant of the meter track, labels, and legend.
      */
@@ -125,4 +118,3 @@ export type MeterProps<T = unknown, S = unknown> = WithSlot<WithSlot<{
      */
     theme?: MeterThemeProps;
 }, 'label' | 'description' | 'helper' | 'header'>, 'indicator'>;
-export {};