@delacour/react-native-ui 0.1.0-alpha.20260925055209 → 0.1.0-alpha.20260925055848

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260925055209",
+	"version": "0.1.0-alpha.20260925055848",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -43,7 +43,9 @@
 		"./icon": "./src/components/icon/index.ts",
 		"./input": "./src/components/input/index.ts",
 		"./list-group": "./src/components/list-group/index.ts",
+		"./meter": "./src/components/meter/index.ts",
 		"./pressable": "./src/components/pressable/index.ts",
+		"./progress": "./src/components/progress/index.ts",
 		"./provider": "./src/components/provider/index.ts",
 		"./radio": "./src/components/radio/index.ts",
 		"./screen": "./src/components/screen/index.ts",
@@ -82,7 +84,7 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-charts": "0.1.0-alpha.20260925055209",
+		"@delacour/react-native-charts": "0.1.0-alpha.20260925055848",
 		"@gorhom/bottom-sheet": "^5.2.8",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",

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";

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

@@ -0,0 +1,83 @@
+import { type ReactElement, useEffect } from "react";
+import { View, type ViewProps } from "react-native";
+import Animated, { useAnimatedStyle, useSharedValue, withTiming } from "react-native-reanimated";
+import { useMeterPart } from "./meter.context";
+import { METER_SEGMENT_FADE_MS, type MeterColor, type MeterSize, meterVariants } from "./meter.variants";
+
+export type MeterSegmentsProps = Omit<ViewProps, "children"> & {
+	/** Extra classes for every block. */
+	segmentClassName?: string;
+	/** Extra classes for a lit block's painted layer. */
+	fillClassName?: string;
+};
+
+type MeterSegmentProps = {
+	isLit: boolean;
+	color: MeterColor;
+	size: MeterSize;
+	className?: string;
+	fillClassName?: string;
+};
+
+/**
+ * One block: an unlit groove with its lit layer fading over it.
+ *
+ * The layer is seeded at its current state, so a meter mounting at three of
+ * four does not replay the lighting on every row that scrolls in. The timing
+ * takes Reanimated's default reduce-motion policy, so with the system setting on
+ * a block lights without a fade — nothing here needs to stay moving to be read.
+ */
+function MeterSegment({ isLit, color, size, className, fillClassName }: MeterSegmentProps): ReactElement {
+	const opacity = useSharedValue(isLit ? 1 : 0);
+
+	useEffect(() => {
+		opacity.value = withTiming(isLit ? 1 : 0, { duration: METER_SEGMENT_FADE_MS });
+	}, [isLit, opacity]);
+
+	const fillStyle = useAnimatedStyle(() => ({ opacity: opacity.value }));
+	const slots = meterVariants({ color, size });
+
+	return (
+		<View className={slots.segment({ className })}>
+			<Animated.View className={slots.segmentFill({ className: fillClassName })} style={fillStyle} />
+		</View>
+	);
+}
+MeterSegment.displayName = "DelacourUI.Meter.Segments.Segment";
+
+/**
+ * The scale drawn as discrete blocks — the segmented meter's track and fill in one.
+ *
+ * Draws the count the root was given as `segments`, lighting whole blocks only:
+ * four blocks say "three out of four" where a bar says "about seventy percent".
+ * With no count on the root it draws nothing, because there is no scale to cut.
+ */
+export function MeterSegments({
+	className,
+	segmentClassName,
+	fillClassName,
+	...props
+}: MeterSegmentsProps): ReactElement | null {
+	const { size, renderProps } = useMeterPart("Meter.Segments");
+	const { segments, litSegments, color } = renderProps;
+
+	if (segments === null) return null;
+
+	const blocks = Array.from({ length: segments }, (_, index) => index);
+
+	return (
+		<View className={meterVariants({ color, size }).segments({ className })} {...props}>
+			{blocks.map((index) => (
+				<MeterSegment
+					className={segmentClassName}
+					color={color}
+					fillClassName={fillClassName}
+					isLit={index < litSegments}
+					key={index}
+					size={size}
+				/>
+			))}
+		</View>
+	);
+}
+MeterSegments.displayName = "DelacourUI.Meter.Segments";

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

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+import { Progress, type ProgressTrackProps } from "../progress";
+import { useMeterPart } from "./meter.context";
+
+export type MeterTrackProps = ProgressTrackProps;
+
+/**
+ * The continuous groove the fill slides along — the progress bar's own track.
+ *
+ * For a segmented meter write `Meter.Segments` instead.
+ */
+export function MeterTrack(props: MeterTrackProps): ReactElement {
+	useMeterPart("Meter.Track");
+	return <Progress.Track {...props} />;
+}
+MeterTrack.displayName = "DelacourUI.Meter.Track";

package/src/components/meter/meter.context.tsx

@@ -0,0 +1,62 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { MeterRenderProps } from "./meter.types";
+import type { MeterSize } from "./meter.variants";
+
+/**
+ * What a meter's own parts read.
+ *
+ * The continuous track and fill do not read this — the root also publishes the
+ * progress bar's context, and `Meter.Track` and `Meter.Fill` are the progress
+ * bar's parts reading that. This holds only what a meter adds: the judged colour,
+ * the region and the blocks.
+ */
+export type MeterContextValue = {
+	size: MeterSize;
+	/** The settled state `Meter.Output` formats and a render function is handed. */
+	renderProps: MeterRenderProps;
+};
+
+const MeterContext = createContext<MeterContextValue | null>(null);
+
+/**
+ * Supplies one meter's state to its own parts.
+ *
+ * Its own module, importing nothing but React and types, so a part can read it
+ * without importing `./meter` and closing a cycle.
+ */
+export function MeterProvider({ value, children }: { value: MeterContextValue; children: ReactNode }): ReactElement {
+	return <MeterContext value={value}>{children}</MeterContext>;
+}
+MeterProvider.displayName = "DelacourUI.Meter.Provider";
+
+/** The enclosing meter's state, or null outside a `<Meter>`. */
+export function useMeterContext(): MeterContextValue | null {
+	return use(MeterContext);
+}
+
+/**
+ * Reads the enclosing meter's state.
+ *
+ * For a custom readout or legend that has to match the meter it sits in. Throws
+ * outside one — use {@link useMeterContext} where the meter is optional.
+ */
+export function useMeter(): MeterContextValue {
+	const context = useMeterContext();
+	if (!context) {
+		throw new Error("useMeter must be called inside a <Meter>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing meter's state, for a compound part that cannot work without one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`.
+ */
+export function useMeterPart(component: string): MeterContextValue {
+	const context = useMeterContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Meter>.`);
+	}
+	return context;
+}