@multiplatform.one/components 7.4.1 → 7.5.0

package/src/Meter/Meter.spec.tsx

@@ -0,0 +1,203 @@
+/**
+ * Meter — bounded-quantity display (MPO-53 AC-7 / D-meter).
+ *
+ * Progress is activity toward completion; Meter is position within bounds.
+ * Required arms: threshold intents map to theme tokens (never raw brand),
+ * a render spec at each zone in both schemes, and the rail radius resolves
+ * through resolveRadiusClass DEFAULT (not BINARY — no thumb).
+ */
+import { cleanup, screen } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset, resolveRadiusClass } from "@multiplatform.one/theme";
+import type { ReactElement } from "react";
+import { Theme } from "tamagui";
+import { afterEach, describe, expect, it } from "vitest";
+import { ListCard, ProgressCard, ShortcutCard } from "../views/Dashboard";
+import * as pkg from "../index";
+import { Meter } from "./index";
+import {
+  METER_RADIUS_CLASS,
+  METER_ZONE_PAINT,
+  formatMeterValue,
+  resolveMeterRailRadius,
+  resolveMeterZone,
+  type MeterZone,
+} from "./meter";
+
+afterEach(cleanup);
+
+const DISK = { min: 0, max: 8, low: 6.4, high: 7.6, optimum: 0 } as const;
+const BATTERY = { min: 0, max: 100, low: 10, high: 20, optimum: 100 } as const;
+
+function renderMeter(
+  ui: ReactElement,
+  scheme: "light" | "dark" = "light",
+  knobs?: { borderRadius?: "none" | "small" | "medium" | "large" | "full" },
+) {
+  return renderWithProviders(
+    <Theme name={scheme}>
+      <Preset cascade={false} overrides={knobs}>
+        {ui}
+      </Preset>
+    </Theme>,
+  );
+}
+
+function rail(container: HTMLElement): HTMLElement {
+  const el = container.querySelector("[role='meter']");
+  expect(el).toBeTruthy();
+  return el as HTMLElement;
+}
+
+describe("threshold intents map to theme intents, never raw brand", () => {
+  it("stays ok (neutral) when no thresholds are declared — LC-36, never guessed", () => {
+    expect(resolveMeterZone({ value: 0, min: 0, max: 8 })).toBe("ok");
+    expect(resolveMeterZone({ value: 7.8, min: 0, max: 8 })).toBe("ok");
+    expect(resolveMeterZone({ value: 8, min: 0, max: 8 })).toBe("ok");
+  });
+
+  it("maps disk (optimum at min) through the HTML meter regions", () => {
+    expect(resolveMeterZone({ value: 5, ...DISK })).toBe("ok");
+    expect(resolveMeterZone({ value: 6.8, ...DISK })).toBe("warn");
+    expect(resolveMeterZone({ value: 7.8, ...DISK })).toBe("critical");
+  });
+
+  it("inverts zones when optimum names the high end (battery)", () => {
+    expect(resolveMeterZone({ value: 9, ...BATTERY })).toBe("critical");
+    expect(resolveMeterZone({ value: 15, ...BATTERY })).toBe("warn");
+    expect(resolveMeterZone({ value: 80, ...BATTERY })).toBe("ok");
+  });
+
+  it("paints each zone with theme intent tokens, never hex or $accent", () => {
+    const token = /^\$(color|orange|red)\d+$/;
+    for (const zone of Object.keys(METER_ZONE_PAINT) as MeterZone[]) {
+      const paint = METER_ZONE_PAINT[zone];
+      expect(paint.fill, `${zone} fill`).toMatch(token);
+      expect(paint.value, `${zone} value`).toMatch(token);
+      expect(paint.fill).not.toMatch(/^#/);
+      expect(paint.value).not.toMatch(/^#/);
+      expect(paint.fill).not.toContain("accent");
+      expect(paint.value).not.toContain("accent");
+    }
+    expect(METER_ZONE_PAINT.ok.fill).toBe("$color11");
+    expect(METER_ZONE_PAINT.warn.fill).toBe("$orange9");
+    expect(METER_ZONE_PAINT.warn.value).toBe("$orange11");
+    expect(METER_ZONE_PAINT.critical.fill).toBe("$red9");
+    expect(METER_ZONE_PAINT.critical.value).toBe("$red11");
+  });
+});
+
+describe("rail radius resolves through resolveRadiusClass DEFAULT", () => {
+  it("is the DEFAULT class, not BINARY — a meter has no thumb", () => {
+    expect(METER_RADIUS_CLASS).toBe("DEFAULT");
+    const stops = ["none", "small", "medium", "large", "full"] as const;
+    for (const stop of stops) {
+      expect(resolveMeterRailRadius(stop)).toBe(resolveRadiusClass("DEFAULT", stop));
+    }
+    // none is 0 on every class; BINARY parts from small onward (the thumb).
+    for (const stop of ["small", "medium", "large", "full"] as const) {
+      expect(resolveMeterRailRadius(stop)).not.toBe(
+        resolveRadiusClass("BINARY", stop, { heightPx: 11 }),
+      );
+    }
+    expect(resolveMeterRailRadius("none")).toBe(0);
+    expect(resolveMeterRailRadius("small")).toBe(5);
+    expect(resolveMeterRailRadius("medium")).toBe(9);
+    expect(resolveMeterRailRadius("large")).toBe(16);
+    expect(resolveMeterRailRadius("full")).toBe(50);
+  });
+
+  it("paints the DEFAULT token on the rail, not a literal or BINARY h/2", () => {
+    const { container: none } = renderMeter(
+      <Meter label="Disk" value={5} min={0} max={8} />,
+      "light",
+      { borderRadius: "none" },
+    );
+    expect(rail(none).getAttribute("data-meter-radius-class")).toBe("DEFAULT");
+    expect(rail(none).getAttribute("data-meter-rail-radius")).toBe("0");
+
+    cleanup();
+    const { container: medium } = renderMeter(
+      <Meter label="Disk" value={5} min={0} max={8} />,
+      "light",
+      { borderRadius: "medium" },
+    );
+    expect(rail(medium).getAttribute("data-meter-rail-radius")).toBe(
+      String(resolveRadiusClass("DEFAULT", "medium")),
+    );
+    expect(rail(medium).getAttribute("data-meter-rail-radius")).not.toBe(
+      String(resolveRadiusClass("BINARY", "medium", { heightPx: 11 })),
+    );
+  });
+});
+
+describe("render spec at each intent in both schemes", () => {
+  const cases: { zone: MeterZone; value: number; bounds: typeof DISK | typeof BATTERY }[] = [
+    { zone: "ok", value: 5, bounds: DISK },
+    { zone: "warn", value: 6.8, bounds: DISK },
+    { zone: "critical", value: 7.8, bounds: DISK },
+  ];
+
+  for (const scheme of ["light", "dark"] as const) {
+    for (const { zone, value, bounds } of cases) {
+      it(`${scheme} ${zone} fill and value ink ride the theme tokens`, () => {
+        const { container } = renderMeter(
+          <Meter label="Disk usage" value={value} unit="GB" {...bounds} />,
+          scheme,
+        );
+        const node = rail(container);
+        const paint = METER_ZONE_PAINT[zone];
+        expect(node.getAttribute("data-meter-zone")).toBe(zone);
+        expect(node.getAttribute("data-meter-fill")).toBe(paint.fill);
+        const valueNode = container.querySelector("[data-meter-value]");
+        expect(valueNode?.getAttribute("data-meter-value-color")).toBe(paint.value);
+        expect(node.getAttribute("data-meter-fill")).not.toMatch(/^#/);
+      });
+    }
+  }
+});
+
+describe("Meter a11y and the Progress semantic line", () => {
+  it("uses role=meter with declared min/max and never role=progressbar", () => {
+    const { container } = renderMeter(
+      <Meter label="Disk usage" value={6.2} min={0} max={8} unit="GB" />,
+    );
+    const node = rail(container);
+    expect(node.getAttribute("role")).toBe("meter");
+    expect(container.querySelector("[role='progressbar']")).toBeNull();
+    expect(node.getAttribute("aria-valuemin")).toBe("0");
+    expect(node.getAttribute("aria-valuemax")).toBe("8");
+    expect(node.getAttribute("aria-valuenow")).toBe("6.2");
+    expect(node.getAttribute("aria-valuetext")).toMatch(/6\.2/);
+    expect(node.getAttribute("aria-label")).toBe("Disk usage");
+    expect(node.getAttribute("tabindex")).toBeNull();
+  });
+
+  it("renders the em dash for an unknown level — never an indeterminate animation", () => {
+    renderMeter(<Meter label="Quota" min={0} max={8} />);
+    expect(screen.getByText("\u2014")).toBeTruthy();
+    const node = document.querySelector("[role='meter']");
+    expect(node?.getAttribute("aria-valuenow")).toBeNull();
+    expect(node?.getAttribute("data-meter-fill")).toBeNull();
+  });
+
+  it("formats the number channel through LC-12", () => {
+    expect(formatMeterValue({ value: 6.2, min: 0, max: 8, unit: "GB", format: "number" })).toBe(
+      "6.2 of 8 GB",
+    );
+    expect(formatMeterValue({ value: 78, min: 0, max: 100, format: "percent" })).toMatch(/%$/);
+    expect(formatMeterValue({ value: undefined, min: 0, max: 8, format: "number" })).toBe("\u2014");
+  });
+});
+
+describe("barrel exports (the ProgressCard export gap)", () => {
+  it("exports Meter from the package barrel", () => {
+    expect(pkg.Meter).toBe(Meter);
+  });
+
+  it("re-exports ProgressCard, ShortcutCard, and ListCard from views/index.ts", () => {
+    expect(typeof ProgressCard).toBe("function");
+    expect(typeof ShortcutCard).toBe("function");
+    expect(typeof ListCard).toBe("function");
+  });
+});

package/src/Meter/Meter.stories.tsx

@@ -0,0 +1,119 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { YStack } from "tamagui";
+import { Meter } from "./index";
+
+const meta: Meta<typeof Meter> = {
+  title: "Components/Meter",
+  component: Meter,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Bounded-quantity display (disk, quota, seats, battery). Progress is activity toward completion; Meter is position within bounds. role=meter, DEFAULT radius class (no thumb), threshold zones only when low/high/optimum are declared.",
+      },
+    },
+  },
+  argTypes: {
+    value: { control: { type: "number", min: 0, max: 8, step: 0.1 } },
+    min: { control: "number" },
+    max: { control: "number" },
+    low: { control: "number" },
+    high: { control: "number" },
+    optimum: { control: "number" },
+    label: { control: "text" },
+    unit: { control: "text" },
+    format: { control: "radio", options: ["number", "percent"] },
+    layout: { control: "radio", options: ["adjacent", "inline", "bare"] },
+    loading: { control: "boolean" },
+    disabled: { control: "boolean" },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Meter>;
+
+export const Default: Story = {
+  name: "Main",
+  args: {
+    label: "Disk usage",
+    value: 6.2,
+    min: 0,
+    max: 8,
+    low: 6.4,
+    high: 7.6,
+    optimum: 0,
+    unit: "GB",
+    format: "number",
+    layout: "adjacent",
+  },
+};
+
+export const Thresholds: Story = {
+  render: () => (
+    <YStack gap="$4" maxWidth={360}>
+      <Meter
+        label="Disk usage"
+        value={5}
+        min={0}
+        max={8}
+        low={6.4}
+        high={7.6}
+        optimum={0}
+        unit="GB"
+      />
+      <Meter
+        label="Disk usage"
+        value={6.8}
+        min={0}
+        max={8}
+        low={6.4}
+        high={7.6}
+        optimum={0}
+        unit="GB"
+      />
+      <Meter
+        label="Disk usage"
+        value={7.8}
+        min={0}
+        max={8}
+        low={6.4}
+        high={7.6}
+        optimum={0}
+        unit="GB"
+      />
+      <Meter
+        label="Battery"
+        value={9}
+        min={0}
+        max={100}
+        low={10}
+        high={20}
+        optimum={100}
+        format="percent"
+      />
+    </YStack>
+  ),
+};
+
+export const Segmented: Story = {
+  args: {
+    label: "Seats",
+    value: 7,
+    min: 0,
+    max: 10,
+    low: 8,
+    high: 10,
+    optimum: 0,
+    segments: 10,
+  },
+};
+
+export const Unknown: Story = {
+  args: {
+    label: "Quota",
+    min: 0,
+    max: 8,
+    unit: "GB",
+  },
+};

package/src/Meter/index.tsx

@@ -0,0 +1,312 @@
+/**
+ * Meter — position within bounds (disk, quota, seats, battery, signal).
+ *
+ * Progress is activity toward completion; Meter is position within bounds.
+ * A Progress bar ends and leaves the screen; a Meter persists, and full is
+ * an incident, not an achievement. role="meter", never progressbar.
+ *
+ * Extracted from ProgressCard (`views/Dashboard.tsx`). The dashboard card
+ * keeps its chrome and composes this rail.
+ */
+import { defaultKnobs, usePresetContext, useResolvedKnobs } from "@multiplatform.one/theme";
+import type { GetProps } from "tamagui";
+import { Text, View, XStack, YStack, isWeb, styled } from "tamagui";
+import { Skeleton } from "../Skeleton";
+import {
+  METER_RADIUS_CLASS,
+  METER_TICK,
+  METER_TRACK,
+  METER_ZONE_PAINT,
+  UNKNOWN_VALUE,
+  formatMeterValue,
+  meterFillRatio,
+  meterTrackHeightPx,
+  resolveMeterRailRadius,
+  resolveMeterZone,
+  type MeterFormat,
+  type MeterLayout,
+} from "./meter";
+
+export {
+  METER_RADIUS_CLASS,
+  METER_ZONE_PAINT,
+  formatMeterValue,
+  meterTrackHeightPx,
+  resolveMeterRailRadius,
+  resolveMeterZone,
+} from "./meter";
+export type { MeterFormat, MeterLayout, MeterZone } from "./meter";
+
+const MeterRoot = styled(YStack, {
+  name: "Meter",
+});
+
+const Rail = styled(View, {
+  name: "MeterRail",
+  position: "relative",
+  overflow: "hidden",
+  width: "100%",
+  flexShrink: 0,
+});
+
+const Fill = styled(View, {
+  name: "MeterFill",
+  position: "absolute",
+  top: 0,
+  bottom: 0,
+  left: 0,
+});
+
+const Tick = styled(View, {
+  name: "MeterTick",
+  position: "absolute",
+  top: 0,
+  bottom: 0,
+  width: 1,
+});
+
+const Segment = styled(View, {
+  name: "MeterSegment",
+  flexShrink: 0,
+});
+
+export interface MeterProps extends Omit<GetProps<typeof MeterRoot>, "children"> {
+  /** Current level. Omit / null / non-finite → unknown (em dash, no fill). */
+  value?: number | null;
+  /** Inclusive lower bound. Declared, never assumed 0…100. */
+  min: number;
+  /** Inclusive upper bound. Declared, never assumed 0…100. */
+  max: number;
+  /** HTML meter `low` — first cut. With `high`/`optimum` declares zones. */
+  low?: number;
+  /** HTML meter `high` — second cut. */
+  high?: number;
+  /** Names the good end so battery inverts without new chrome (LC-36). */
+  optimum?: number;
+  /** Field label (adjacent layout). Also the default aria-label. */
+  label?: string;
+  /** Unit that never leaves the value (DG-OVF-06), e.g. `"GB"`. */
+  unit?: string;
+  /** `number` = "6.2 of 8 GB"; `percent` trails the bar when inline. */
+  format?: MeterFormat;
+  /** Override the visible value (ProgressCard keeps its own formatter). */
+  valueLabel?: string;
+  /** Override aria-valuetext (default keeps the unit). */
+  valueText?: string;
+  /** adjacent (default) · inline (percent after the bar) · bare (rail only). */
+  layout?: MeterLayout;
+  /** Discrete capacity (seats, slots). Count is data, not a knob. */
+  segments?: number;
+  /** Skeleton at the same track height (LC-20). */
+  loading?: boolean;
+  disabled?: boolean;
+}
+
+function tickLeftPercent(cut: number, min: number, max: number): number | null {
+  if (max === min) return null;
+  if (cut <= min || cut >= max) return null;
+  return ((cut - min) / (max - min)) * 100;
+}
+
+function defaultValueText(opts: {
+  value?: number | null;
+  visible: string;
+  unit?: string;
+  format?: MeterFormat;
+}): string {
+  if (opts.value == null || !Number.isFinite(opts.value)) return UNKNOWN_VALUE;
+  if (opts.format === "percent") return opts.visible;
+  if (opts.unit) return `${opts.visible} used`;
+  return opts.visible;
+}
+
+/**
+ * Bounded-quantity display. Inert — no tab stop, no focus ring. The input
+ * twin is Slider.
+ */
+export function Meter({
+  value,
+  min,
+  max,
+  low,
+  high,
+  optimum,
+  label,
+  unit,
+  format = "number",
+  valueLabel,
+  valueText,
+  layout = "adjacent",
+  segments,
+  loading = false,
+  disabled = false,
+  ...props
+}: MeterProps) {
+  const { knobProps } = useResolvedKnobs({ component: "Meter" });
+  const preset = usePresetContext();
+  const stop = preset?.preset.knobs.borderRadius ?? defaultKnobs.borderRadius;
+  const size = (preset?.preset.knobs.size ?? defaultKnobs.size) as "small" | "medium" | "large";
+  const outlined = knobProps.outlined;
+  const trackH = meterTrackHeightPx(size);
+  const railRadius = resolveMeterRailRadius(stop);
+  const known = value != null && Number.isFinite(value);
+  const zone = known
+    ? resolveMeterZone({ value: value as number, min, max, low, high, optimum })
+    : "ok";
+  const paint = METER_ZONE_PAINT[zone];
+  const ratio = meterFillRatio(value, min, max);
+  const visible = formatMeterValue({ value, min, max, unit, format, valueLabel });
+  const valuetext = valueText ?? defaultValueText({ value, visible, unit, format });
+  const discrete =
+    typeof segments === "number" && Number.isFinite(segments) && segments > 0
+      ? Math.round(segments)
+      : 0;
+  const span = max - min;
+  const filledCount =
+    known && discrete > 0 && span !== 0
+      ? Math.max(0, Math.min(discrete, Math.round(((value as number) - min) / (span / discrete))))
+      : 0;
+
+  const valueNode =
+    layout === "bare" ? null : (
+      <Text
+        {...knobProps.label}
+        fontFamily="$mono"
+        color={paint.value}
+        whiteSpace="nowrap"
+        data-meter-value=""
+        data-meter-value-color={paint.value}
+        {...(isWeb ? { style: { fontVariantNumeric: "tabular-nums" } } : null)}
+      >
+        {visible}
+      </Text>
+    );
+
+  const ticks =
+    discrete > 0
+      ? null
+      : [low, high].map((cut, i) => {
+          if (cut === undefined) return null;
+          const left = tickLeftPercent(cut, min, max);
+          if (left == null) return null;
+          return (
+            <Tick
+              key={`${cut}-${i}`}
+              left={`${left}%`}
+              backgroundColor={METER_TICK}
+              data-meter-tick=""
+            />
+          );
+        });
+
+  const railEl = loading ? (
+    <Skeleton variant="rounded" height={trackH} width="100%" />
+  ) : discrete > 0 ? (
+    <XStack gap={3} data-meter-segments={discrete} opacity={disabled ? 0.5 : 1}>
+      {Array.from({ length: discrete }, (_, i) => (
+        <Segment
+          key={i}
+          width={19}
+          height={trackH}
+          borderRadius={railRadius}
+          backgroundColor={i < filledCount ? paint.fill : outlined ? "transparent" : METER_TRACK}
+          borderWidth={outlined ? 1 : 0}
+          borderColor={outlined ? "$color6" : undefined}
+        />
+      ))}
+    </XStack>
+  ) : (
+    <Rail
+      height={trackH}
+      minHeight={trackH}
+      borderRadius={railRadius}
+      backgroundColor={outlined ? "transparent" : METER_TRACK}
+      borderWidth={outlined ? 1 : 0}
+      borderColor={outlined ? "$color6" : undefined}
+      opacity={disabled ? 0.5 : 1}
+      role="meter"
+      aria-label={label}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      aria-valuenow={known ? (value as number) : undefined}
+      aria-valuetext={valuetext}
+      data-meter-radius-class={METER_RADIUS_CLASS}
+      data-meter-rail-radius={railRadius}
+      data-meter-zone={zone}
+      data-meter-fill={known && ratio != null ? paint.fill : undefined}
+      data-meter-track-height={trackH}
+    >
+      {known && ratio != null ? (
+        <Fill
+          width={`${ratio * 100}%`}
+          backgroundColor={paint.fill}
+          {...(knobProps.transition
+            ? { transition: knobProps.transition }
+            : { transition: "none" })}
+        />
+      ) : null}
+      {ticks}
+    </Rail>
+  );
+
+  // Segmented rails still owe role=meter — park it on the segment row host.
+  const segmentedMeter =
+    !loading && discrete > 0 ? (
+      <View
+        role="meter"
+        aria-label={label}
+        aria-valuemin={min}
+        aria-valuemax={max}
+        aria-valuenow={known ? (value as number) : undefined}
+        aria-valuetext={valuetext}
+        data-meter-radius-class={METER_RADIUS_CLASS}
+        data-meter-rail-radius={railRadius}
+        data-meter-zone={zone}
+        data-meter-fill={known ? paint.fill : undefined}
+        data-meter-track-height={trackH}
+      >
+        {railEl}
+      </View>
+    ) : (
+      railEl
+    );
+
+  if (layout === "bare") {
+    return (
+      <MeterRoot width="100%" {...props}>
+        {segmentedMeter}
+      </MeterRoot>
+    );
+  }
+
+  if (layout === "inline") {
+    return (
+      <MeterRoot width="100%" {...props}>
+        <XStack alignItems="center" {...knobProps.gap}>
+          <View flex={1} minWidth={0}>
+            {segmentedMeter}
+          </View>
+          {valueNode}
+        </XStack>
+      </MeterRoot>
+    );
+  }
+
+  return (
+    <MeterRoot width="100%" {...knobProps.gap} {...props}>
+      {label || valueNode ? (
+        <XStack justifyContent="space-between" alignItems="baseline" {...knobProps.gap}>
+          {label ? (
+            <Text {...knobProps.body} flex={1} numberOfLines={1}>
+              {label}
+            </Text>
+          ) : (
+            <View flex={1} />
+          )}
+          {valueNode}
+        </XStack>
+      ) : null}
+      {segmentedMeter}
+    </MeterRoot>
+  );
+}