@delacour/react-native-ui 0.1.0-alpha.4 → 0.1.0

package/src/components/menu/menu.variants.ts

@@ -0,0 +1,353 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+export const MENU_PLACEMENTS = ["top", "bottom"] as const;
+export const MENU_ALIGNS = ["start", "center", "end"] as const;
+export const MENU_ITEM_VARIANTS = ["default", "destructive"] as const;
+export const MENU_RADIO_INDICATORS = ["check", "dot"] as const;
+
+export type MenuPlacement = (typeof MENU_PLACEMENTS)[number];
+export type MenuAlign = (typeof MENU_ALIGNS)[number];
+export type MenuItemVariant = (typeof MENU_ITEM_VARIANTS)[number];
+export type MenuRadioIndicator = (typeof MENU_RADIO_INDICATORS)[number];
+
+/** Where the panel is anchored, in window coordinates. A zero-size rect is a point. */
+export type MenuAnchorRect = { x: number; y: number; width: number; height: number };
+
+/** A screen edge's safe-area inset, in points. */
+export type MenuInsets = { top: number; right: number; bottom: number; left: number };
+
+/** `align` with RTL already applied — the edge the panel lines up with on screen. */
+export type MenuPhysicalAlign = "left" | "center" | "right";
+
+/** Gap between the anchor and the panel, in points. */
+export const MENU_DEFAULT_OFFSET = 6;
+
+/** What the panel keeps clear of the safe area on every side, in points. */
+export const MENU_EDGE_MARGIN = 8;
+
+/** The narrowest a panel resolves to when nothing names a width. */
+export const MENU_DEFAULT_MIN_WIDTH = 200;
+
+/** The scale the panel grows from on enter and shrinks to on exit. */
+export const MENU_ENTER_SCALE = 0.96;
+
+/** How long the panel takes to appear and to leave, in milliseconds. */
+export const MENU_MOTION = { enterMs: 160, exitMs: 120 } as const;
+
+/**
+ * A row's press: the fill fades in fast and out slower, and the row dips to
+ * `scale`. Both read one shared value.
+ */
+export const MENU_PRESS = { inMs: 90, outMs: 160, scale: 0.98 } as const;
+
+/** How far a tap may travel before it stops being a tap — a scroll, in a long menu. */
+export const MENU_TAP_MAX_DISTANCE = 10;
+
+/** Where the sub-trigger's chevron points at each end of the travel, in degrees. */
+export const MENU_SUB_ROTATION = { collapsed: 0, expanded: 90 } as const;
+
+/**
+ * The submenu's spring — `Collapsible`'s, restated rather than imported so
+ * `delacour add menu` copies one folder. Critically damped, because an
+ * overshoot in height flashes the panel behind the rows.
+ */
+export const MENU_SUB_SPRING = { damping: 26, mass: 0.4, stiffness: 400 } as const;
+
+/** Theme token a row's icon is drawn in, per variant. */
+export const MENU_ICON_TOKEN: Record<MenuItemVariant, string> = {
+	default: "popover-foreground",
+	destructive: "destructive",
+};
+
+/** Theme token an indicator (check, chevron) is drawn in. */
+export const MENU_INDICATOR_TOKEN = "popover-foreground";
+
+/** The accessibility hint a trigger carries. */
+export const MENU_TRIGGER_HINT = "Opens a menu";
+
+/** `align` as a screen edge: start and end swap under RTL, center does not. */
+export function resolveMenuPhysicalAlign(align: MenuAlign, isRTL: boolean): MenuPhysicalAlign {
+	if (align === "center") return "center";
+	const isStart = align === "start";
+	return isStart !== isRTL ? "left" : "right";
+}
+
+export type MenuPlacementInput = {
+	anchor: MenuAnchorRect;
+	/** The panel's size — its resolved width and its measured (or estimated) height. */
+	content: { width: number; height: number };
+	window: { width: number; height: number };
+	insets: MenuInsets;
+	placement: MenuPlacement;
+	align: MenuAlign;
+	offset: number;
+	isRTL: boolean;
+};
+
+export type MenuPlacementResult = {
+	/** The panel's top edge, for a panel below the anchor. */
+	top: number;
+	/**
+	 * The distance from the window's bottom to the panel's bottom edge — what a
+	 * panel above the anchor is positioned by, so it grows away from the anchor
+	 * when its content does.
+	 */
+	bottom: number;
+	left: number;
+	/** The side it actually opened on, after any flip. */
+	placement: MenuPlacement;
+	/** The room on that side, inside the safe area and the margin. Never negative. */
+	maxHeight: number;
+};
+
+/**
+ * Where the panel goes.
+ *
+ * **Vertical.** The requested side wins when the content fits there; otherwise it
+ * flips to the other side if the content fits there; otherwise it takes the
+ * larger side and `maxHeight` caps it, so the rows scroll. Room is measured
+ * inside the safe area plus {@link MENU_EDGE_MARGIN}.
+ *
+ * **Horizontal.** `align` lines an edge (or the centre) up with the anchor's —
+ * start and end swap under RTL — and the result is clamped inside the safe area
+ * plus the margin. A panel wider than the room pins to the left edge.
+ *
+ * A zero-size anchor (a long-press point) runs through the same arithmetic with
+ * no special case: its edges coincide.
+ *
+ * Pure, and the one place the geometry lives — when Popover lands, Menu.Content
+ * moves onto it and this resolver moves with it.
+ */
+export function resolveMenuPlacement({
+	anchor,
+	content,
+	window,
+	insets,
+	placement,
+	align,
+	offset,
+	isRTL,
+}: MenuPlacementInput): MenuPlacementResult {
+	const topBound = insets.top + MENU_EDGE_MARGIN;
+	const bottomBound = window.height - insets.bottom - MENU_EDGE_MARGIN;
+	const belowStart = anchor.y + anchor.height + offset;
+	const aboveEnd = anchor.y - offset;
+
+	const room: Record<MenuPlacement, number> = {
+		bottom: Math.max(0, bottomBound - belowStart),
+		top: Math.max(0, aboveEnd - topBound),
+	};
+	const other: MenuPlacement = placement === "bottom" ? "top" : "bottom";
+
+	let side: MenuPlacement;
+	if (content.height <= room[placement]) side = placement;
+	else if (content.height <= room[other]) side = other;
+	else side = room[placement] >= room[other] ? placement : other;
+
+	const maxHeight = room[side];
+	const height = Math.min(content.height, maxHeight);
+	const top = side === "bottom" ? belowStart : aboveEnd - height;
+	const bottom = window.height - (top + height);
+
+	const physical = resolveMenuPhysicalAlign(align, isRTL);
+	let left: number;
+	if (physical === "left") left = anchor.x;
+	else if (physical === "right") left = anchor.x + anchor.width - content.width;
+	else left = anchor.x + anchor.width / 2 - content.width / 2;
+
+	const minLeft = insets.left + MENU_EDGE_MARGIN;
+	const maxLeft = window.width - insets.right - MENU_EDGE_MARGIN - content.width;
+	left = maxLeft < minLeft ? minLeft : Math.min(Math.max(left, minLeft), maxLeft);
+
+	return { bottom, left, maxHeight, placement: side, top };
+}
+
+/**
+ * The translate that makes a centre-origin scale look like it grows out of the
+ * anchor's side, at the panel's smallest. The worklet multiplies it by
+ * `1 - progress`, so it is zero once the panel has arrived.
+ *
+ * React Native has no `transformOrigin` that Reanimated animates reliably on
+ * both platforms, so the origin is approximated: a panel below grows from its
+ * top edge, a panel above from its bottom, and a start-aligned one from its
+ * leading edge.
+ */
+export function resolveMenuOrigin({
+	placement,
+	align,
+	width,
+	height,
+}: {
+	placement: MenuPlacement;
+	align: MenuPhysicalAlign;
+	width: number;
+	height: number;
+}): { x: number; y: number } {
+	const shrink = 1 - MENU_ENTER_SCALE;
+	const y = ((placement === "bottom" ? -1 : 1) * shrink * height) / 2;
+	const x = align === "center" ? 0 : ((align === "left" ? -1 : 1) * shrink * width) / 2;
+	return { x, y };
+}
+
+/**
+ * The panel's width: the caller's `width`, or the trigger's floored at
+ * {@link MENU_DEFAULT_MIN_WIDTH}; then floored by `minWidth`; then capped by
+ * `maxWidth` — the room between the safe-area edges — so it never runs off screen.
+ */
+export function resolveMenuWidth({
+	width,
+	minWidth,
+	maxWidth,
+	triggerWidth,
+}: {
+	width?: number;
+	minWidth?: number;
+	maxWidth?: number;
+	triggerWidth: number;
+}): number {
+	const base = width ?? Math.max(triggerWidth, MENU_DEFAULT_MIN_WIDTH);
+	const floored = Math.max(base, minWidth ?? 0);
+	return maxWidth === undefined ? floored : Math.min(floored, maxWidth);
+}
+
+/** The group's next value when a radio row is chosen. A radio never clears, so re-choosing keeps it. */
+export function resolveRadioNext(_current: string | undefined, value: string): string {
+	return value;
+}
+
+/** The kinds of row a menu has. */
+export type MenuRowKind = "item" | "checkbox" | "radio" | "sub-trigger";
+
+const CLOSE_ON_SELECT: Record<MenuRowKind, boolean> = {
+	checkbox: false,
+	item: true,
+	radio: true,
+	"sub-trigger": false,
+};
+
+/**
+ * Whether choosing a row closes the menu: an item and a radio do, a checkbox does
+ * not (several are usually toggled in one visit), and a sub-trigger only expands.
+ * An explicit `isClosedOnSelect` wins.
+ */
+export function resolveCloseOnSelect(kind: MenuRowKind, explicit?: boolean): boolean {
+	return explicit ?? CLOSE_ON_SELECT[kind];
+}
+
+export type MenuItemAccessibilityInput =
+	| { kind: "item"; isDisabled: boolean }
+	| { kind: "checkbox"; isDisabled: boolean; isChecked: boolean }
+	| { kind: "radio"; isDisabled: boolean; isSelected: boolean }
+	| { kind: "sub-trigger"; isDisabled: boolean; isExpanded: boolean };
+
+export type MenuItemAccessibilityState = {
+	disabled: boolean;
+	checked?: boolean;
+	selected?: boolean;
+	expanded?: boolean;
+};
+
+/** The `accessibilityState` a row announces — one source, so the matrix is testable. */
+export function resolveMenuItemAccessibility(input: MenuItemAccessibilityInput): MenuItemAccessibilityState {
+	switch (input.kind) {
+		case "item":
+			return { disabled: input.isDisabled };
+		case "checkbox":
+			return { checked: input.isChecked, disabled: input.isDisabled };
+		case "radio":
+			return { disabled: input.isDisabled, selected: input.isSelected };
+		case "sub-trigger":
+			return { disabled: input.isDisabled, expanded: input.isExpanded };
+		default:
+			return { disabled: false };
+	}
+}
+
+/**
+ * Styling for every part of a menu.
+ *
+ * One slotted `tv()`, because the parts cannot import each other without closing
+ * a cycle (AGENTS.md rule 3) and all of them read the same row axes.
+ *
+ * **`background` is `bg-popover`, never `bg-overlay`.** `overlay` is the
+ * translucent scrim colour, and a panel painted in it is a see-through card.
+ * The scrim slot wears it instead.
+ *
+ * **`itemFill` is the row's pressed background**, an absolute layer whose
+ * opacity the press drives. There is no wash on top: the fill is the feedback.
+ *
+ * **The disabled fade lands on `item`**, a plain `Animated.View` that owns only
+ * `transform`, so a class opacity there is not overwritten.
+ *
+ * No slot worn by a `View` carries `text-*` (rule 1). Free of React Native
+ * imports so it stays reachable from `bun test`.
+ */
+export const menuVariants = tv({
+	slots: {
+		/**
+		 * The positioned, animated layer. Casts the panel's shadow, so it carries no
+		 * `overflow-hidden` — iOS clips a shadow to a clipping view's own bounds.
+		 */
+		panel: "absolute shadow-lg",
+		/** The panel's frame: corner, hairline and clip. Its surface is `background`. */
+		content: "overflow-hidden rounded-lg border border-border",
+		/** The panel's surface, drawn behind the scroller. */
+		background: "absolute inset-0 bg-popover",
+		/** The full-screen tint behind the panel, when `hasScrim`. */
+		scrim: "absolute inset-0 bg-overlay",
+		/** What `backdrop` is drawn in — full-screen, over the scrim, behind the panel. */
+		backdrop: "absolute inset-0",
+		/** The scroller's padding, around the rows. */
+		scroll: "p-1",
+		/** One row. */
+		item: "min-h-11 flex-row items-center gap-3 rounded-md px-3 py-2",
+		/** The row's pressed fill. Its opacity is an animated style. */
+		itemFill: "absolute inset-0 rounded-md bg-accent",
+		/** The label-and-description column. */
+		itemContent: "min-w-0 flex-1 justify-center gap-0.5",
+		itemLabel: "text-popover-foreground text-sm",
+		itemDescription: "text-muted-foreground text-xs",
+		itemShortcut: "ms-auto text-muted-foreground text-xs",
+		/** Edge length of a row's glyph — 18pt, the reserved icon column. */
+		itemIcon: "size-icon-md",
+		/** The section heading. */
+		label: "px-3 pt-2 pb-1 font-medium text-muted-foreground text-xs",
+		/** The box an indicator (check, dot, chevron) sits in — the icon column's footprint. */
+		indicator: "size-icon-md items-center justify-center",
+		/** The radio `dot` indicator. */
+		indicatorDot: "size-1.5 rounded-full bg-popover-foreground",
+		/** The rows a submenu discloses, stepped in from the trigger. */
+		subContent: "ps-3",
+		/** The submenu's measured clip. Its height is an animated style. */
+		subClip: "overflow-hidden",
+		/** The submenu's measured inner layer — out of flow so it measures its content alone. */
+		subInner: "absolute top-0 right-0 left-0",
+		/** The separator's spacing. */
+		separator: "my-1",
+	},
+	variants: {
+		variant: {
+			default: {},
+			destructive: {
+				itemFill: "bg-destructive-soft",
+				itemLabel: "text-destructive",
+			},
+		},
+		isInset: {
+			true: { label: "ps-[42px]" },
+			false: {},
+		},
+		isDisabled: {
+			true: { item: "opacity-50" },
+			false: {},
+		},
+	},
+	defaultVariants: {
+		variant: "default",
+		isInset: false,
+		isDisabled: false,
+	},
+});
+
+export type MenuVariantProps = VariantProps<typeof menuVariants>;

package/src/components/meter/AGENTS.md

@@ -0,0 +1,135 @@
+# Meter
+
+A measurement on a fixed scale, coloured by where it falls — storage used, a
+battery's charge, a password's strength. Built on `Progress`: the same track, fill,
+header and label, with a root that clamps the reading, judges it, and paints the
+fill that judgement's colour. Adds `Meter.Segments` for a scale drawn as whole
+blocks.
+
+`import { Meter } from "@delacour/react-native-ui/meter";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/meter` |
+| `meter.tsx` | Root + the `Object.assign` compound surface; publishes both contexts |
+| `meter-header.tsx` | `Meter.Header` — `Progress.Header`, named for the meter |
+| `meter-label.tsx` | `Meter.Label` — `Progress.Label`, named for the meter |
+| `meter-output.tsx` | `Meter.Output`, the readout, whose function child is handed the region |
+| `meter-track.tsx` | `Meter.Track` — `Progress.Track`, named for the meter |
+| `meter-fill.tsx` | `Meter.Fill` — `Progress.Fill`, named for the meter |
+| `meter-segments.tsx` | `Meter.Segments`, the blocks, and the internal `Meter.Segments.Segment` |
+| `meter.context.tsx` | `MeterContext`, `useMeter()`, `useMeterContext()`, `useMeterPart()` |
+| `meter.types.ts` | `MeterRenderProps`, shared by the context and the readout |
+| `meter.variants.ts` | The blocks' `tv()` slots + the scale, region, threshold and segment resolvers |
+| `meter.variants.test.ts` | |
+
+## Built on Progress
+
+- **The root publishes `ProgressContextValue` as well as its own context.**
+  `Progress.Track` and `Progress.Fill` read only `ratio`, `isIndeterminate`,
+  `color`, `size` and `trackSize` — the progress bar was written to be reused
+  this way — so `Meter.Track` and `Meter.Fill` *are* those parts, and the fill's
+  UI-thread transform, its seeded first frame and its hide-until-measured come
+  along without a line restated. `isIndeterminate` is always `false`.
+- **Each reused part is a thin wrapper, not the progress part assigned
+  directly.** The wrapper calls `useMeterPart` first, so a `Meter.Fill` outside
+  a meter throws naming `Meter.Fill` rather than `Progress.Fill`, and DevTools
+  shows `DelacourUI.Meter.Fill` (rule 12).
+- **The parts come through `../progress`, the index; the resolvers through
+  `../progress/progress.variants`, the leaf** (rule 3). Progress imports nothing
+  from here, so there is no cycle, and the registry records `progress` as a
+  dependency of `meter`.
+- **Colours and sizes are the progress bar's tuples, re-exported, not
+  restated.** A test pins them equal, and another pins a block's height and
+  paint to the progress track's and fill's, so a segmented meter and a
+  continuous one in one card read as one instrument.
+
+## Judging the reading
+
+- **Two ways, never both, and the prop type says so.** `MeterProps` is a union:
+  `low` / `high` / `optimum` *or* `thresholds`. Passing both is a type error
+  rather than a precedence rule. `resolveMeterScale` turns the props into a
+  `MeterScale` — `plain`, `regions` or `thresholds` — and `resolveMeterColor`
+  switches on its `kind`.
+- **Regions follow a gauge's three-part model.** `low` and `high` default to the
+  scale's ends and `optimum` to its middle; each is clamped into the scale and
+  `high` is never below `low`, so a boundary written the wrong way round is
+  pulled into order rather than inverting every region. `optimum` below `low`
+  makes the bottom good (a disk), above `high` the top (a battery), between them
+  the band (a temperature). The regions paint `success`, `warning`,
+  `destructive` — `METER_REGION_COLORS`, fixed, so a region reads the same in
+  every meter in an app — and `color` is ignored.
+- **Thresholds: the highest `from` reached wins, in any listed order.** `from`
+  is in the reading's units, not a percentage — a threshold on a 0–256 GB meter
+  is written in gigabytes. A non-finite `from` is ignored. Below every threshold
+  `color` applies.
+- **The clamped reading is what is judged.** A disk over its capacity is
+  `critical`, not off the scale.
+- **Colour is never the only signal, and `valueLabel` takes a function for it.**
+  Nothing speaks the region on its own — the words are domain-specific ("Almost
+  full", "Weak") — so `valueLabel` may be a function handed the judged
+  `MeterReading`, and `resolveMeterValueLabel` calls it. A `Meter.Output`
+  function reading `region` is **not** enough: the output is hidden from
+  assistive technology, so its words are seen and never heard. The simulator
+  pass caught exactly that — the regions demo drew "Filling up · 82%" while
+  VoiceOver's value was "82%".
+
+## The scale
+
+- **`meterRange` makes the scale finite and ordered.** A non-finite bound takes
+  0 or 100; an inverted or empty scale collapses at its floor and reads empty.
+  `progressRatio` would already return 0 for it, but the accessibility value
+  needs `min ≤ now ≤ max` too.
+- **`meterValue` clamps to the ends; `NaN` reads at the floor and an infinity at
+  the end it points to.** `progressRatio` alone returns 0 for `+Infinity`,
+  which would draw a full disk as empty.
+- **The formatted readout uses the clamped reading**, so a non-percent format
+  never prints `300 GB` on a 256 GB scale.
+
+## Segments
+
+- **Whole blocks only.** `litSegments` floors, so four blocks say "three out of
+  four" where a bar says "about seventy percent" — a password is not seventy
+  percent strong. A small epsilon absorbs floating-point error, so `0.7 × 10`
+  lights seven.
+- **Any reading above the floor lights at least one block.** Rounding down would
+  leave the first quarter of a four-block meter dark, and "a little" looking like
+  "none" is the reading a meter can least afford to get wrong.
+- **`meterSegmentCount` rounds a fractional count down, clamps above
+  `METER_MAX_SEGMENTS` (100), and falls back to the continuous bar** for a count
+  under one or not finite, rather than drawing nothing.
+- **A block's lit colour is a layer that fades its opacity**, not the block's own
+  background: an opacity animates on the UI thread, where a background would need
+  two token values interpolated in JavaScript. Each layer is seeded at its
+  current state, so a list of meters does not replay the lighting as rows mount,
+  and the timing keeps Reanimated's default reduce-motion policy — with the system
+  setting on, a block lights without a fade. Unlike the progress bar's loop,
+  nothing here has to keep moving to be read.
+- **`segments` lives on the root, not on `Meter.Segments`.** The lit count is
+  part of the render props a readout reads, so the root has to know it.
+  `Meter.Segments` without a count renders nothing; `Meter.Track` with one still
+  draws the continuous bar.
+
+## What it refuses
+
+- **No `isDisabled`, `isInvalid`, `Field` or indeterminate state.** A meter
+  reports a reading and accepts no input; `resolveMeterAxes` takes one argument
+  and a test pins that. A reading that is not known yet is `Progress`'s
+  indeterminate loop, not a meter.
+- **No `label` / `showValueLabel` props.** The anatomy is written out, as
+  `Progress`'s is — `Meter.Header` with a `Meter.Label` and a `Meter.Output` — and
+  a bare `<Meter value={68} />` still draws the scale, because a compound root
+  with no default children renders an empty `View` with no error.
+
+## Accessibility
+
+- **The root is the one accessible element**, `accessibilityRole="progressbar"`
+  — React Native has no meter role, and this is the one that publishes a range
+  and a value on both platforms. `resolveProgressAccessibility` decides the
+  spoken text: the percentage over 0–100, `168 of 256` otherwise, or
+  `valueLabel`. Thresholds, regions and segments never change it.
+- **`Meter.Label` is the name, `Meter.Output` is hidden** — the root already
+  speaks the value, so a visible readout would be read twice. A meter with no
+  label needs an `accessibilityLabel`.

package/src/components/meter/index.ts

@@ -0,0 +1,43 @@
+export { Meter, type MeterProps } from "./meter";
+export { type MeterContextValue, MeterProvider, useMeter, useMeterContext } from "./meter.context";
+export type { MeterRenderChildren, MeterRenderProps } from "./meter.types";
+export {
+	litSegments,
+	METER_COLORS,
+	METER_DEFAULT_COLOR,
+	METER_DEFAULT_SIZE,
+	METER_MAX_SEGMENTS,
+	METER_MAX_VALUE,
+	METER_MIN_VALUE,
+	METER_REGION_COLORS,
+	METER_REGIONS,
+	METER_SEGMENT_FADE_MS,
+	METER_SIZES,
+	type MeterAxes,
+	type MeterColor,
+	type MeterOwnAxes,
+	type MeterReading,
+	type MeterRegion,
+	type MeterScale,
+	type MeterScaleInput,
+	type MeterSize,
+	type MeterThreshold,
+	type MeterValueLabel,
+	type MeterVariantProps,
+	meterRange,
+	meterSegmentCount,
+	meterValue,
+	meterVariants,
+	resolveMeterAxes,
+	resolveMeterColor,
+	resolveMeterRegion,
+	resolveMeterScale,
+	resolveMeterValueLabel,
+	thresholdColor,
+} from "./meter.variants";
+export type { MeterFillProps } from "./meter-fill";
+export type { MeterHeaderProps } from "./meter-header";
+export type { MeterLabelProps } from "./meter-label";
+export type { MeterOutputProps } from "./meter-output";
+export type { MeterSegmentsProps } from "./meter-segments";
+export type { MeterTrackProps } from "./meter-track";

package/src/components/meter/meter-fill.tsx

@@ -0,0 +1,19 @@
+import type { ReactElement } from "react";
+import { Progress, type ProgressFillProps } from "../progress";
+import { useMeterPart } from "./meter.context";
+
+export type MeterFillProps = ProgressFillProps;
+
+/**
+ * The painted bar, in the colour the reading was judged to be.
+ *
+ * The progress bar's own fill: a transform on the UI thread, one timing per new
+ * reading, landing on the value without travel under the system's reduce-motion
+ * setting. A change of colour is a class, so it lands on the render that judged
+ * it.
+ */
+export function MeterFill(props: MeterFillProps): ReactElement {
+	useMeterPart("Meter.Fill");
+	return <Progress.Fill {...props} />;
+}
+MeterFill.displayName = "DelacourUI.Meter.Fill";

package/src/components/meter/meter-header.tsx

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import { Progress, type ProgressHeaderProps } from "../progress";
+import { useMeterPart } from "./meter.context";
+
+export type MeterHeaderProps = ProgressHeaderProps;
+
+/**
+ * The row above the track: a label at the start, a readout at the end.
+ *
+ * The progress bar's own header — the meter publishes that bar's context, so the
+ * row, its gap and its type step are shared rather than restated.
+ */
+export function MeterHeader(props: MeterHeaderProps): ReactElement {
+	useMeterPart("Meter.Header");
+	return <Progress.Header {...props} />;
+}
+MeterHeader.displayName = "DelacourUI.Meter.Header";

package/src/components/meter/meter-label.tsx

@@ -0,0 +1,18 @@
+import type { ReactElement } from "react";
+import { Progress, type ProgressLabelProps } from "../progress";
+import { useMeterPart } from "./meter.context";
+
+export type MeterLabelProps = ProgressLabelProps;
+
+/**
+ * What is being measured — "Storage", "Battery".
+ *
+ * Left visible to assistive technology: the root is one accessible element, and
+ * a label inside it is what VoiceOver and TalkBack read as that element's name.
+ * A meter without one announces a number with nothing attached to it.
+ */
+export function MeterLabel(props: MeterLabelProps): ReactElement {
+	useMeterPart("Meter.Label");
+	return <Progress.Label {...props} />;
+}
+MeterLabel.displayName = "DelacourUI.Meter.Label";

package/src/components/meter/meter-output.tsx

@@ -0,0 +1,42 @@
+import type { ReactElement } from "react";
+import { PROGRESS_OUTPUT_TEXT_SIZE, progressVariants } from "../progress/progress.variants";
+import { Text, type TextPresetProps } from "../text";
+import { useMeterPart } from "./meter.context";
+import type { MeterRenderChildren } from "./meter.types";
+
+export type MeterOutputProps = Omit<TextPresetProps, "children"> & {
+	/** Custom content, or a function called with the meter's settled state. */
+	children?: MeterRenderChildren;
+};
+
+/**
+ * The reading, formatted — `68%` by default, or `valueLabel` when one is given.
+ *
+ * A function child is handed the meter's state, including the `region` it was
+ * judged to be in. Words it draws are seen but not heard — see below — so a
+ * judgement a screen reader must hear belongs in a `valueLabel` function.
+ *
+ * **Hidden from assistive technology on purpose.** The root already publishes
+ * the reading as `accessibilityValue`, so a readout left visible inside it would
+ * be read twice.
+ */
+export function MeterOutput({ children, className, size, ...props }: MeterOutputProps): ReactElement | null {
+	const { size: meterSize, renderProps } = useMeterPart("Meter.Output");
+
+	const content = typeof children === "function" ? children(renderProps) : (children ?? renderProps.formatted);
+
+	if (content === null || content === undefined) return null;
+
+	return (
+		<Text.Label
+			accessibilityElementsHidden
+			className={progressVariants({ size: meterSize }).output({ className })}
+			importantForAccessibility="no-hide-descendants"
+			size={size ?? PROGRESS_OUTPUT_TEXT_SIZE[meterSize]}
+			{...props}
+		>
+			{content}
+		</Text.Label>
+	);
+}
+MeterOutput.displayName = "DelacourUI.Meter.Output";