@dowel-ui/react 0.1.0 → 0.2.0

package/dist/components/meter/meter.js

@@ -0,0 +1,144 @@
+"use client";
+import { cn } from "../../lib/utils.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+//#region src/components/meter/meter.tsx
+/**
+* A measurement against a known capacity: storage against a quota, seats
+* against a plan, spend against a budget.
+*
+* Not a Progress. Progress reports how far along a task is and is expected to
+* reach the end; a meter reports a level that has no reason to move at all, and
+* where being near the top is the thing worth noticing. They carry different
+* ARIA roles for exactly that reason, and screen readers phrase them
+* differently.
+*
+* The bar is a single `role="meter"` and the segments inside it are decoration.
+* Making each segment its own widget would put five unlabelled meters in the
+* tab order to describe one quantity; the legend carries the per-segment detail
+* as text instead, where it can actually be read.
+*/
+const TONES = {
+	primary: "bg-primary",
+	info: "bg-info",
+	success: "bg-success",
+	warning: "bg-warning",
+	destructive: "bg-destructive",
+	neutral: "bg-border-strong"
+};
+const MeterContext = createContext(null);
+function useMeterContext(component) {
+	const context = useContext(MeterContext);
+	if (!context) throw new Error(`${component} must be rendered inside <Meter>.`);
+	return context;
+}
+function defaultFormat(value) {
+	return new Intl.NumberFormat().format(value);
+}
+function Meter({ className, segments, max, label, warnAt = .9, threshold, format = defaultFormat, children, ...props }) {
+	const total = segments.reduce((sum, segment) => sum + Math.max(0, segment.value), 0);
+	const over = total > max;
+	const strained = max > 0 && total / max >= warnAt;
+	const denominator = over ? total : max;
+	const context = useMemo(() => ({
+		segments,
+		total,
+		max,
+		format,
+		over
+	}), [
+		segments,
+		total,
+		max,
+		format,
+		over
+	]);
+	return /* @__PURE__ */ jsx(MeterContext.Provider, {
+		value: context,
+		children: /* @__PURE__ */ jsxs("div", {
+			"data-slot": "meter",
+			"data-over": over || void 0,
+			"data-strained": strained || void 0,
+			className: cn("flex w-full flex-col gap-1.5", className),
+			...props,
+			children: [/* @__PURE__ */ jsxs("div", {
+				role: "meter",
+				"aria-label": label,
+				"aria-valuenow": total,
+				"aria-valuemin": 0,
+				"aria-valuemax": max,
+				"aria-valuetext": `${format(total)} of ${format(max)}${over ? ", over capacity" : ""}`,
+				"data-slot": "meter-track",
+				className: "relative h-2 w-full overflow-hidden rounded-full bg-muted",
+				children: [/* @__PURE__ */ jsx("div", {
+					className: "flex h-full w-full",
+					children: segments.map((segment) => {
+						const value = Math.max(0, segment.value);
+						if (value === 0 || denominator === 0) return null;
+						return /* @__PURE__ */ jsx("div", {
+							"data-slot": "meter-segment",
+							"data-tone": segment.tone ?? "primary",
+							className: cn("h-full first:rounded-l-full last:rounded-r-full", "transition-[width] duration-[var(--duration-slow)] ease-[var(--ease-out-quint)]", TONES[segment.tone ?? "primary"]),
+							style: { width: `${String(value / denominator * 100)}%` }
+						}, segment.id);
+					})
+				}), threshold && max > 0 && threshold.value > 0 && threshold.value < max ? /* @__PURE__ */ jsx("div", {
+					"data-slot": "meter-threshold",
+					"aria-hidden": "true",
+					className: "absolute inset-y-0 w-px bg-foreground/45",
+					style: { left: `${String(threshold.value / denominator * 100)}%` }
+				}) : null]
+			}), children]
+		})
+	});
+}
+/**
+* The per-segment breakdown, as text.
+*
+* This is where the detail lives. The bar communicates one number; anyone who
+* needs to know that images account for most of it reads it here.
+*/
+function MeterLegend({ className, ...props }) {
+	const { segments, format } = useMeterContext("MeterLegend");
+	return /* @__PURE__ */ jsx("ul", {
+		"data-slot": "meter-legend",
+		className: cn("flex flex-wrap gap-x-4 gap-y-1 text-xs", className),
+		...props,
+		children: segments.map((segment) => /* @__PURE__ */ jsxs("li", {
+			className: "flex items-center gap-1.5",
+			children: [
+				/* @__PURE__ */ jsx("span", {
+					"aria-hidden": "true",
+					className: cn("size-2 shrink-0 rounded-full", TONES[segment.tone ?? "primary"])
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: "text-muted-foreground",
+					children: segment.label
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: "tabular-nums",
+					children: format(segment.value)
+				})
+			]
+		}, segment.id))
+	});
+}
+/** The headline "4.2 GB of 10 GB" line, with an over-capacity state. */
+function MeterValue({ className, ...props }) {
+	const { total, max, format, over } = useMeterContext("MeterValue");
+	return /* @__PURE__ */ jsxs("p", {
+		"data-slot": "meter-value",
+		className: cn("text-xs tabular-nums", over ? "text-destructive" : "text-muted-foreground", className),
+		...props,
+		children: [
+			format(total),
+			" of ",
+			format(max),
+			over ? " — over capacity" : null
+		]
+	});
+}
+//#endregion
+export { Meter, MeterLegend, MeterValue };
+
+//# sourceMappingURL=meter.js.map

package/dist/components/meter/meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.js","names":[],"sources":["../../../src/components/meter/meter.tsx"],"sourcesContent":["\"use client\";\n\nimport { createContext, useContext, useMemo, type ComponentPropsWithRef } from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\n/**\n * A measurement against a known capacity: storage against a quota, seats\n * against a plan, spend against a budget.\n *\n * Not a Progress. Progress reports how far along a task is and is expected to\n * reach the end; a meter reports a level that has no reason to move at all, and\n * where being near the top is the thing worth noticing. They carry different\n * ARIA roles for exactly that reason, and screen readers phrase them\n * differently.\n *\n * The bar is a single `role=\"meter\"` and the segments inside it are decoration.\n * Making each segment its own widget would put five unlabelled meters in the\n * tab order to describe one quantity; the legend carries the per-segment detail\n * as text instead, where it can actually be read.\n */\n\nconst TONES = {\n  primary: \"bg-primary\",\n  info: \"bg-info\",\n  success: \"bg-success\",\n  warning: \"bg-warning\",\n  destructive: \"bg-destructive\",\n  neutral: \"bg-border-strong\",\n} as const;\n\nexport type MeterTone = keyof typeof TONES;\n\nexport interface MeterSegment {\n  /** Stable identity, so a re-order does not re-animate every segment. */\n  id: string;\n  /** Named in the legend and in the accessible summary. */\n  label: string;\n  value: number;\n  tone?: MeterTone;\n}\n\ninterface MeterContextValue {\n  segments: MeterSegment[];\n  total: number;\n  max: number;\n  format: (value: number) => string;\n  over: boolean;\n}\n\nconst MeterContext = createContext<MeterContextValue | null>(null);\n\nfunction useMeterContext(component: string): MeterContextValue {\n  const context = useContext(MeterContext);\n  if (!context) {\n    throw new Error(`${component} must be rendered inside <Meter>.`);\n  }\n  return context;\n}\n\nfunction defaultFormat(value: number): string {\n  return new Intl.NumberFormat().format(value);\n}\n\nexport interface MeterProps extends Omit<ComponentPropsWithRef<\"div\">, \"children\"> {\n  /** Parts making up the measurement. One segment is the ordinary case. */\n  segments: MeterSegment[];\n  /** The capacity being measured against. */\n  max: number;\n  /** Names the meter. Required — an unnamed measurement is unreadable. */\n  label: string;\n  /**\n   * Fraction of `max` past which the meter reports strain, between 0 and 1.\n   * Presentation only: it never changes the reported value.\n   */\n  warnAt?: number;\n  /** Optional marker on the track, for a soft limit or an alert threshold. */\n  threshold?: { value: number; label: string };\n  /** Formats every number that reaches the reader. */\n  format?: (value: number) => string;\n  /** Shown after the bar. Compose `MeterLegend` here, or your own summary. */\n  children?: React.ReactNode;\n}\n\nexport function Meter({\n  className,\n  segments,\n  max,\n  label,\n  warnAt = 0.9,\n  threshold,\n  format = defaultFormat,\n  children,\n  ...props\n}: MeterProps) {\n  const total = segments.reduce((sum, segment) => sum + Math.max(0, segment.value), 0);\n  const over = total > max;\n  const strained = max > 0 && total / max >= warnAt;\n\n  // Widths are a share of capacity, not of the total, so a half-full meter\n  // renders half full. Dividing by the total instead would make every meter\n  // look completely full, which is the usual bug in hand-rolled versions.\n  const denominator = over ? total : max;\n\n  const context = useMemo<MeterContextValue>(\n    () => ({ segments, total, max, format, over }),\n    [segments, total, max, format, over],\n  );\n\n  return (\n    <MeterContext.Provider value={context}>\n      <div\n        data-slot=\"meter\"\n        data-over={over || undefined}\n        data-strained={strained || undefined}\n        className={cn(\"flex w-full flex-col gap-1.5\", className)}\n        {...props}\n      >\n        <div\n          role=\"meter\"\n          aria-label={label}\n          aria-valuenow={total}\n          aria-valuemin={0}\n          aria-valuemax={max}\n          // Without this a screen reader announces a bare number with no unit\n          // and no capacity — \"4\" tells the reader nothing about 4 of what.\n          aria-valuetext={`${format(total)} of ${format(max)}${over ? \", over capacity\" : \"\"}`}\n          data-slot=\"meter-track\"\n          className=\"relative h-2 w-full overflow-hidden rounded-full bg-muted\"\n        >\n          <div className=\"flex h-full w-full\">\n            {segments.map((segment) => {\n              const value = Math.max(0, segment.value);\n              // A zero segment renders nothing at all. A one-pixel sliver reads\n              // as a small amount rather than as none.\n              if (value === 0 || denominator === 0) return null;\n\n              return (\n                <div\n                  key={segment.id}\n                  data-slot=\"meter-segment\"\n                  data-tone={segment.tone ?? \"primary\"}\n                  className={cn(\n                    \"h-full first:rounded-l-full last:rounded-r-full\",\n                    \"transition-[width] duration-[var(--duration-slow)] ease-[var(--ease-out-quint)]\",\n                    TONES[segment.tone ?? \"primary\"],\n                  )}\n                  style={{ width: `${String((value / denominator) * 100)}%` }}\n                />\n              );\n            })}\n          </div>\n\n          {threshold && max > 0 && threshold.value > 0 && threshold.value < max ? (\n            <div\n              data-slot=\"meter-threshold\"\n              // The marker repeats what the legend states in words, so it is\n              // decoration. Announcing it would interrupt the value.\n              aria-hidden=\"true\"\n              className=\"absolute inset-y-0 w-px bg-foreground/45\"\n              style={{ left: `${String((threshold.value / denominator) * 100)}%` }}\n            />\n          ) : null}\n        </div>\n\n        {children}\n      </div>\n    </MeterContext.Provider>\n  );\n}\n\n/**\n * The per-segment breakdown, as text.\n *\n * This is where the detail lives. The bar communicates one number; anyone who\n * needs to know that images account for most of it reads it here.\n */\nexport function MeterLegend({ className, ...props }: ComponentPropsWithRef<\"ul\">) {\n  const { segments, format } = useMeterContext(\"MeterLegend\");\n\n  return (\n    <ul\n      data-slot=\"meter-legend\"\n      className={cn(\"flex flex-wrap gap-x-4 gap-y-1 text-xs\", className)}\n      {...props}\n    >\n      {segments.map((segment) => (\n        <li key={segment.id} className=\"flex items-center gap-1.5\">\n          <span\n            aria-hidden=\"true\"\n            className={cn(\"size-2 shrink-0 rounded-full\", TONES[segment.tone ?? \"primary\"])}\n          />\n          <span className=\"text-muted-foreground\">{segment.label}</span>\n          <span className=\"tabular-nums\">{format(segment.value)}</span>\n        </li>\n      ))}\n    </ul>\n  );\n}\n\n/** The headline \"4.2 GB of 10 GB\" line, with an over-capacity state. */\nexport function MeterValue({ className, ...props }: ComponentPropsWithRef<\"p\">) {\n  const { total, max, format, over } = useMeterContext(\"MeterValue\");\n\n  return (\n    <p\n      data-slot=\"meter-value\"\n      className={cn(\n        \"text-xs tabular-nums\",\n        over ? \"text-destructive\" : \"text-muted-foreground\",\n        className,\n      )}\n      {...props}\n    >\n      {format(total)} of {format(max)}\n      {over ? \" — over capacity\" : null}\n    </p>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAsBA,MAAM,QAAQ;CACZ,SAAS;CACT,MAAM;CACN,SAAS;CACT,SAAS;CACT,aAAa;CACb,SAAS;AACX;AAqBA,MAAM,eAAe,cAAwC,IAAI;AAEjE,SAAS,gBAAgB,WAAsC;CAC7D,MAAM,UAAU,WAAW,YAAY;CACvC,IAAI,CAAC,SACH,MAAM,IAAI,MAAM,GAAG,UAAU,kCAAkC;CAEjE,OAAO;AACT;AAEA,SAAS,cAAc,OAAuB;CAC5C,OAAO,IAAI,KAAK,aAAa,CAAC,CAAC,OAAO,KAAK;AAC7C;AAsBA,SAAgB,MAAM,EACpB,WACA,UACA,KACA,OACA,SAAS,IACT,WACA,SAAS,eACT,UACA,GAAG,SACU;CACb,MAAM,QAAQ,SAAS,QAAQ,KAAK,YAAY,MAAM,KAAK,IAAI,GAAG,QAAQ,KAAK,GAAG,CAAC;CACnF,MAAM,OAAO,QAAQ;CACrB,MAAM,WAAW,MAAM,KAAK,QAAQ,OAAO;CAK3C,MAAM,cAAc,OAAO,QAAQ;CAEnC,MAAM,UAAU,eACP;EAAE;EAAU;EAAO;EAAK;EAAQ;CAAK,IAC5C;EAAC;EAAU;EAAO;EAAK;EAAQ;CAAI,CACrC;CAEA,OACE,oBAAC,aAAa,UAAd;EAAuB,OAAO;EAC5B,UAAA,qBAAC,OAAD;GACE,aAAU;GACV,aAAW,QAAQ,KAAA;GACnB,iBAAe,YAAY,KAAA;GAC3B,WAAW,GAAG,gCAAgC,SAAS;GACvD,GAAI;GALN,UAAA,CAOE,qBAAC,OAAD;IACE,MAAK;IACL,cAAY;IACZ,iBAAe;IACf,iBAAe;IACf,iBAAe;IAGf,kBAAgB,GAAG,OAAO,KAAK,EAAE,MAAM,OAAO,GAAG,IAAI,OAAO,oBAAoB;IAChF,aAAU;IACV,WAAU;IAVZ,UAAA,CAYE,oBAAC,OAAD;KAAK,WAAU;KACZ,UAAA,SAAS,KAAK,YAAY;MACzB,MAAM,QAAQ,KAAK,IAAI,GAAG,QAAQ,KAAK;MAGvC,IAAI,UAAU,KAAK,gBAAgB,GAAG,OAAO;MAE7C,OACE,oBAAC,OAAD;OAEE,aAAU;OACV,aAAW,QAAQ,QAAQ;OAC3B,WAAW,GACT,mDACA,mFACA,MAAM,QAAQ,QAAQ,UACxB;OACA,OAAO,EAAE,OAAO,GAAG,OAAQ,QAAQ,cAAe,GAAG,EAAE,GAAG;MAC3D,GATM,QAAQ,EASd;KAEL,CAAC;IACE,CAAA,GAEJ,aAAa,MAAM,KAAK,UAAU,QAAQ,KAAK,UAAU,QAAQ,MAChE,oBAAC,OAAD;KACE,aAAU;KAGV,eAAY;KACZ,WAAU;KACV,OAAO,EAAE,MAAM,GAAG,OAAQ,UAAU,QAAQ,cAAe,GAAG,EAAE,GAAG;IACpE,CAAA,IACC,IACD;GAEJ,CAAA,GAAA,QACE;;CACgB,CAAA;AAE3B;;;;;;;AAQA,SAAgB,YAAY,EAAE,WAAW,GAAG,SAAsC;CAChF,MAAM,EAAE,UAAU,WAAW,gBAAgB,aAAa;CAE1D,OACE,oBAAC,MAAD;EACE,aAAU;EACV,WAAW,GAAG,0CAA0C,SAAS;EACjE,GAAI;EAEH,UAAA,SAAS,KAAK,YACb,qBAAC,MAAD;GAAqB,WAAU;GAA/B,UAAA;IACE,oBAAC,QAAD;KACE,eAAY;KACZ,WAAW,GAAG,gCAAgC,MAAM,QAAQ,QAAQ,UAAU;IAC/E,CAAA;IACD,oBAAC,QAAD;KAAM,WAAU;KAAyB,UAAA,QAAQ;IAAY,CAAA;IAC7D,oBAAC,QAAD;KAAM,WAAU;KAAgB,UAAA,OAAO,QAAQ,KAAK;IAAQ,CAAA;GAC1D;EAPK,GAAA,QAAQ,EAOb,CACL;CACC,CAAA;AAER;;AAGA,SAAgB,WAAW,EAAE,WAAW,GAAG,SAAqC;CAC9E,MAAM,EAAE,OAAO,KAAK,QAAQ,SAAS,gBAAgB,YAAY;CAEjE,OACE,qBAAC,KAAD;EACE,aAAU;EACV,WAAW,GACT,wBACA,OAAO,qBAAqB,yBAC5B,SACF;EACA,GAAI;EAPN,UAAA;GASG,OAAO,KAAK;GAAE;GAAK,OAAO,GAAG;GAC7B,OAAO,qBAAqB;EAC5B;;AAEP"}

package/dist/components/metric-delta/index.d.ts

@@ -0,0 +1,2 @@
+import { MetricDelta, MetricDeltaProps, MetricPolarity, deltaVariants } from "./metric-delta.js";
+export { MetricDelta, type MetricDeltaProps, type MetricPolarity, deltaVariants };

package/dist/components/metric-delta/index.js

@@ -0,0 +1,2 @@
+import { MetricDelta, deltaVariants } from "./metric-delta.js";
+export { MetricDelta, deltaVariants };

package/dist/components/metric-delta/meta.js

@@ -0,0 +1,17 @@
+import { defineMeta } from "../../registry/schema.js";
+//#region src/components/metric-delta/meta.ts
+const meta = defineMeta({
+	name: "metric-delta",
+	title: "Metric Delta",
+	description: "A headline number with a change indicator that knows which direction is good.",
+	category: "data",
+	status: "stable",
+	dependencies: ["class-variance-authority"],
+	registryDependencies: [],
+	files: ["metric-delta.tsx"],
+	a11y: "The meaning is never carried by colour and an arrow alone, which fails WCAG 1.4.1 — the direction and the comparison are always stated in text. The tile reads as one sentence rather than three fragments: the visible number and delta are aria-hidden and a single screen-reader description carries value, direction, comparison and, where given, sample size. A zero baseline is announced as having no percentage rather than as an infinite one."
+});
+//#endregion
+export { meta };
+
+//# sourceMappingURL=meta.js.map

package/dist/components/metric-delta/meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.js","names":[],"sources":["../../../src/components/metric-delta/meta.ts"],"sourcesContent":["import { defineMeta } from \"@/registry/schema\";\n\nexport const meta = defineMeta({\n  name: \"metric-delta\",\n  title: \"Metric Delta\",\n  description: \"A headline number with a change indicator that knows which direction is good.\",\n  category: \"data\",\n  status: \"stable\",\n  dependencies: [\"class-variance-authority\"],\n  registryDependencies: [],\n  files: [\"metric-delta.tsx\"],\n  a11y:\n    \"The meaning is never carried by colour and an arrow alone, which fails WCAG 1.4.1 — the \" +\n    \"direction and the comparison are always stated in text. The tile reads as one sentence \" +\n    \"rather than three fragments: the visible number and delta are aria-hidden and a single \" +\n    \"screen-reader description carries value, direction, comparison and, where given, sample \" +\n    \"size. A zero baseline is announced as having no percentage rather than as an infinite one.\",\n});\n"],"mappings":";;AAEA,MAAa,OAAO,WAAW;CAC7B,MAAM;CACN,OAAO;CACP,aAAa;CACb,UAAU;CACV,QAAQ;CACR,cAAc,CAAC,0BAA0B;CACzC,sBAAsB,CAAC;CACvB,OAAO,CAAC,kBAAkB;CAC1B,MACE;AAKJ,CAAC"}

package/dist/components/metric-delta/metric-delta.d.ts

@@ -0,0 +1,59 @@
+import { VariantProps } from "class-variance-authority";
+import { ComponentPropsWithRef } from "react";
+//#region src/components/metric-delta/metric-delta.d.ts
+/**
+ * A headline number with an honest change indicator.
+ *
+ * The visual is a commodity; the correctness is not. Three things go wrong in
+ * almost every hand-rolled version, and all three are handled here:
+ *
+ * 1. Direction is assumed to be good news. Rising churn, rising latency and
+ *    rising cost are all bad, and painting them green is worse than showing no
+ *    colour at all. `polarity` decides.
+ * 2. A zero baseline produces `+∞%` or `NaN`. There is no percentage change
+ *    from nothing, so this says so in words instead of inventing one.
+ * 3. Meaning is carried by colour and an arrow alone, which fails WCAG 1.4.1
+ *    and is unreadable to anyone who does not already know the convention. The
+ *    direction is always stated in text.
+ *
+ * What this deliberately does NOT do is claim statistical significance. A
+ * component holding two numbers cannot know whether a change is significant —
+ * that needs the sample size and a test. `insignificantBelow` is a presentation
+ * threshold and is described as one; passing `sampleSize` only adds it to the
+ * accessible description, it does not license a stronger claim.
+ */
+type MetricPolarity = "higher-is-better" | "lower-is-better" | "neutral";
+declare const deltaVariants: (props?: ({
+  sentiment?: "good" | "bad" | "neutral" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+interface MetricDeltaProps extends Omit<ComponentPropsWithRef<"div">, "children">, VariantProps<typeof deltaVariants> {
+  /** The current value. */
+  value: number;
+  /** The value being compared against. Omit when there is nothing to compare. */
+  previous?: number;
+  /** Names the metric. */
+  label: string;
+  /**
+   * Whether a rise is good news. Churn, latency, error rate and cost are all
+   * `lower-is-better`, and getting this wrong paints bad news green.
+   */
+  polarity?: MetricPolarity;
+  /**
+   * Relative change below which the delta is shown without sentiment, as a
+   * fraction. Presentation only — this is not a significance test.
+   */
+  insignificantBelow?: number;
+  /**
+   * Included in the accessible description when given, so a reader can judge
+   * the change for themselves. Never used to compute significance.
+   */
+  sampleSize?: number;
+  /** What the previous value represents, e.g. "vs last week". */
+  comparisonLabel?: string;
+  /** Formats the headline value. */
+  format?: (value: number) => string;
+}
+declare function MetricDelta({ className, value, previous, label, polarity, insignificantBelow, sampleSize, comparisonLabel, format, ...props }: MetricDeltaProps): import("react").JSX.Element;
+//#endregion
+export { MetricDelta, MetricDeltaProps, MetricPolarity, deltaVariants };
+//# sourceMappingURL=metric-delta.d.ts.map

package/dist/components/metric-delta/metric-delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-delta.d.ts","names":[],"sources":["../../../src/components/metric-delta/metric-delta.tsx"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;KA6BY;cAEN,gBAAa;;6CASjB;UAae,yBACP,KAAK,2CAA2C,oBAAoB;;EAE5E;;EAEA;;EAEA;;;;;EAKA,WAAW;;;;;EAKX;;;;;EAKA;;EAEA;;EAEA,UAAU;;iBAaI,cACd,WACA,OACA,UACA,OACA,UACA,oBACA,YACA,iBACA,WACG,SACF,mCAAgB,IAAA"}

package/dist/components/metric-delta/metric-delta.js

@@ -0,0 +1,82 @@
+"use client";
+import { cn } from "../../lib/utils.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cva } from "class-variance-authority";
+//#region src/components/metric-delta/metric-delta.tsx
+const deltaVariants = cva("inline-flex items-center gap-1 text-xs font-medium tabular-nums", {
+	variants: { sentiment: {
+		good: "text-success",
+		bad: "text-destructive",
+		neutral: "text-muted-foreground"
+	} },
+	defaultVariants: { sentiment: "neutral" }
+});
+/** What the change means, once polarity is applied. */
+function sentimentOf(change, polarity, meaningful) {
+	if (!meaningful || change === 0 || polarity === "neutral") return "neutral";
+	return (polarity === "higher-is-better" ? change > 0 : change < 0) ? "good" : "bad";
+}
+function defaultFormat(value) {
+	return new Intl.NumberFormat().format(value);
+}
+const percentFormatter = new Intl.NumberFormat(void 0, {
+	style: "percent",
+	maximumFractionDigits: 1,
+	signDisplay: "exceptZero"
+});
+function MetricDelta({ className, value, previous, label, polarity = "higher-is-better", insignificantBelow = 0, sampleSize, comparisonLabel = "vs previous period", format = defaultFormat, ...props }) {
+	const hasComparison = previous !== void 0;
+	const absoluteChange = hasComparison ? value - previous : 0;
+	const relativeChange = hasComparison && previous !== 0 ? absoluteChange / Math.abs(previous) : null;
+	const meaningful = relativeChange === null ? absoluteChange !== 0 : Math.abs(relativeChange) >= insignificantBelow;
+	const sentiment = hasComparison ? sentimentOf(absoluteChange, polarity, meaningful) : "neutral";
+	const direction = absoluteChange > 0 ? "up" : absoluteChange < 0 ? "down" : "flat";
+	const changeText = !hasComparison ? null : relativeChange !== null ? percentFormatter.format(relativeChange) : `${absoluteChange > 0 ? "+" : ""}${format(absoluteChange)}`;
+	const description = [
+		`${label}: ${format(value)}`,
+		hasComparison ? relativeChange !== null ? `${direction === "flat" ? "unchanged" : direction} ${changeText ?? ""} ${comparisonLabel}` : `${direction === "flat" ? "unchanged" : direction} by ${format(Math.abs(absoluteChange))} ${comparisonLabel}, no percentage available from a zero baseline` : null,
+		hasComparison && !meaningful && direction !== "flat" ? "not a meaningful change" : null,
+		sampleSize !== void 0 ? `sample size ${format(sampleSize)}` : null
+	].filter(Boolean).join(", ");
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "metric-delta",
+		"data-direction": direction,
+		"data-sentiment": sentiment,
+		className: cn("flex flex-col gap-1", className),
+		...props,
+		children: [
+			/* @__PURE__ */ jsx("p", {
+				className: "text-xs text-muted-foreground",
+				children: label
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "sr-only",
+				children: description
+			}),
+			/* @__PURE__ */ jsx("p", {
+				"aria-hidden": "true",
+				className: "text-2xl leading-tight font-semibold tracking-tight tabular-nums",
+				children: format(value)
+			}),
+			hasComparison ? /* @__PURE__ */ jsxs("p", {
+				"aria-hidden": "true",
+				className: "flex flex-wrap items-center gap-x-1.5 gap-y-0.5",
+				children: [/* @__PURE__ */ jsxs("span", {
+					className: cn(deltaVariants({ sentiment })),
+					"data-slot": "metric-delta-change",
+					children: [/* @__PURE__ */ jsx("span", {
+						"aria-hidden": "true",
+						children: direction === "up" ? "↑" : direction === "down" ? "↓" : "→"
+					}), changeText]
+				}), /* @__PURE__ */ jsx("span", {
+					className: "text-xs text-muted-foreground",
+					children: comparisonLabel
+				})]
+			}) : null
+		]
+	});
+}
+//#endregion
+export { MetricDelta, deltaVariants };
+
+//# sourceMappingURL=metric-delta.js.map

package/dist/components/metric-delta/metric-delta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-delta.js","names":[],"sources":["../../../src/components/metric-delta/metric-delta.tsx"],"sourcesContent":["\"use client\";\n\nimport { cva, type VariantProps } from \"class-variance-authority\";\nimport type { ComponentPropsWithRef } from \"react\";\n\nimport { cn } from \"@/lib/utils\";\n\n/**\n * A headline number with an honest change indicator.\n *\n * The visual is a commodity; the correctness is not. Three things go wrong in\n * almost every hand-rolled version, and all three are handled here:\n *\n * 1. Direction is assumed to be good news. Rising churn, rising latency and\n *    rising cost are all bad, and painting them green is worse than showing no\n *    colour at all. `polarity` decides.\n * 2. A zero baseline produces `+∞%` or `NaN`. There is no percentage change\n *    from nothing, so this says so in words instead of inventing one.\n * 3. Meaning is carried by colour and an arrow alone, which fails WCAG 1.4.1\n *    and is unreadable to anyone who does not already know the convention. The\n *    direction is always stated in text.\n *\n * What this deliberately does NOT do is claim statistical significance. A\n * component holding two numbers cannot know whether a change is significant —\n * that needs the sample size and a test. `insignificantBelow` is a presentation\n * threshold and is described as one; passing `sampleSize` only adds it to the\n * accessible description, it does not license a stronger claim.\n */\n\nexport type MetricPolarity = \"higher-is-better\" | \"lower-is-better\" | \"neutral\";\n\nconst deltaVariants = cva(\"inline-flex items-center gap-1 text-xs font-medium tabular-nums\", {\n  variants: {\n    sentiment: {\n      good: \"text-success\",\n      bad: \"text-destructive\",\n      neutral: \"text-muted-foreground\",\n    },\n  },\n  defaultVariants: { sentiment: \"neutral\" },\n});\n\n/** What the change means, once polarity is applied. */\nfunction sentimentOf(\n  change: number,\n  polarity: MetricPolarity,\n  meaningful: boolean,\n): \"good\" | \"bad\" | \"neutral\" {\n  if (!meaningful || change === 0 || polarity === \"neutral\") return \"neutral\";\n  const improved = polarity === \"higher-is-better\" ? change > 0 : change < 0;\n  return improved ? \"good\" : \"bad\";\n}\n\nexport interface MetricDeltaProps\n  extends Omit<ComponentPropsWithRef<\"div\">, \"children\">, VariantProps<typeof deltaVariants> {\n  /** The current value. */\n  value: number;\n  /** The value being compared against. Omit when there is nothing to compare. */\n  previous?: number;\n  /** Names the metric. */\n  label: string;\n  /**\n   * Whether a rise is good news. Churn, latency, error rate and cost are all\n   * `lower-is-better`, and getting this wrong paints bad news green.\n   */\n  polarity?: MetricPolarity;\n  /**\n   * Relative change below which the delta is shown without sentiment, as a\n   * fraction. Presentation only — this is not a significance test.\n   */\n  insignificantBelow?: number;\n  /**\n   * Included in the accessible description when given, so a reader can judge\n   * the change for themselves. Never used to compute significance.\n   */\n  sampleSize?: number;\n  /** What the previous value represents, e.g. \"vs last week\". */\n  comparisonLabel?: string;\n  /** Formats the headline value. */\n  format?: (value: number) => string;\n}\n\nfunction defaultFormat(value: number): string {\n  return new Intl.NumberFormat().format(value);\n}\n\nconst percentFormatter = new Intl.NumberFormat(undefined, {\n  style: \"percent\",\n  maximumFractionDigits: 1,\n  signDisplay: \"exceptZero\",\n});\n\nexport function MetricDelta({\n  className,\n  value,\n  previous,\n  label,\n  polarity = \"higher-is-better\",\n  insignificantBelow = 0,\n  sampleSize,\n  comparisonLabel = \"vs previous period\",\n  format = defaultFormat,\n  ...props\n}: MetricDeltaProps) {\n  const hasComparison = previous !== undefined;\n  const absoluteChange = hasComparison ? value - previous : 0;\n\n  // A percentage change from zero is undefined, not infinite. Reporting it as\n  // a number at all is the lie; the component says \"no prior value\" instead.\n  const canComputeRelative = hasComparison && previous !== 0;\n  const relativeChange = canComputeRelative ? absoluteChange / Math.abs(previous) : null;\n\n  const meaningful =\n    relativeChange === null\n      ? absoluteChange !== 0\n      : Math.abs(relativeChange) >= insignificantBelow;\n\n  const sentiment = hasComparison\n    ? sentimentOf(absoluteChange, polarity, meaningful)\n    : \"neutral\";\n\n  const direction = absoluteChange > 0 ? \"up\" : absoluteChange < 0 ? \"down\" : \"flat\";\n\n  const changeText = !hasComparison\n    ? null\n    : relativeChange !== null\n      ? percentFormatter.format(relativeChange)\n      : `${absoluteChange > 0 ? \"+\" : \"\"}${format(absoluteChange)}`;\n\n  // Everything a screen reader needs, in one sentence, in the order it matters.\n  const description = [\n    `${label}: ${format(value)}`,\n    hasComparison\n      ? relativeChange !== null\n        ? `${direction === \"flat\" ? \"unchanged\" : direction} ${changeText ?? \"\"} ${comparisonLabel}`\n        : `${direction === \"flat\" ? \"unchanged\" : direction} by ${format(Math.abs(absoluteChange))} ${comparisonLabel}, no percentage available from a zero baseline`\n      : null,\n    hasComparison && !meaningful && direction !== \"flat\" ? \"not a meaningful change\" : null,\n    sampleSize !== undefined ? `sample size ${format(sampleSize)}` : null,\n  ]\n    .filter(Boolean)\n    .join(\", \");\n\n  return (\n    <div\n      data-slot=\"metric-delta\"\n      data-direction={direction}\n      data-sentiment={sentiment}\n      className={cn(\"flex flex-col gap-1\", className)}\n      {...props}\n    >\n      <p className=\"text-xs text-muted-foreground\">{label}</p>\n\n      {/* One accessible sentence for the whole tile. The parts below are hidden\n          so the reader gets the meaning once, not as three fragments. */}\n      <p className=\"sr-only\">{description}</p>\n\n      <p\n        aria-hidden=\"true\"\n        className=\"text-2xl leading-tight font-semibold tracking-tight tabular-nums\"\n      >\n        {format(value)}\n      </p>\n\n      {hasComparison ? (\n        <p aria-hidden=\"true\" className=\"flex flex-wrap items-center gap-x-1.5 gap-y-0.5\">\n          <span className={cn(deltaVariants({ sentiment }))} data-slot=\"metric-delta-change\">\n            <span aria-hidden=\"true\">\n              {direction === \"up\" ? \"↑\" : direction === \"down\" ? \"↓\" : \"→\"}\n            </span>\n            {changeText}\n          </span>\n          <span className=\"text-xs text-muted-foreground\">{comparisonLabel}</span>\n        </p>\n      ) : null}\n    </div>\n  );\n}\n\nexport { deltaVariants };\n"],"mappings":";;;;;AA+BA,MAAM,gBAAgB,IAAI,mEAAmE;CAC3F,UAAU,EACR,WAAW;EACT,MAAM;EACN,KAAK;EACL,SAAS;CACX,EACF;CACA,iBAAiB,EAAE,WAAW,UAAU;AAC1C,CAAC;;AAGD,SAAS,YACP,QACA,UACA,YAC4B;CAC5B,IAAI,CAAC,cAAc,WAAW,KAAK,aAAa,WAAW,OAAO;CAElE,QADiB,aAAa,qBAAqB,SAAS,IAAI,SAAS,KACvD,SAAS;AAC7B;AA+BA,SAAS,cAAc,OAAuB;CAC5C,OAAO,IAAI,KAAK,aAAa,CAAC,CAAC,OAAO,KAAK;AAC7C;AAEA,MAAM,mBAAmB,IAAI,KAAK,aAAa,KAAA,GAAW;CACxD,OAAO;CACP,uBAAuB;CACvB,aAAa;AACf,CAAC;AAED,SAAgB,YAAY,EAC1B,WACA,OACA,UACA,OACA,WAAW,oBACX,qBAAqB,GACrB,YACA,kBAAkB,sBAClB,SAAS,eACT,GAAG,SACgB;CACnB,MAAM,gBAAgB,aAAa,KAAA;CACnC,MAAM,iBAAiB,gBAAgB,QAAQ,WAAW;CAK1D,MAAM,iBADqB,iBAAiB,aAAa,IACb,iBAAiB,KAAK,IAAI,QAAQ,IAAI;CAElF,MAAM,aACJ,mBAAmB,OACf,mBAAmB,IACnB,KAAK,IAAI,cAAc,KAAK;CAElC,MAAM,YAAY,gBACd,YAAY,gBAAgB,UAAU,UAAU,IAChD;CAEJ,MAAM,YAAY,iBAAiB,IAAI,OAAO,iBAAiB,IAAI,SAAS;CAE5E,MAAM,aAAa,CAAC,gBAChB,OACA,mBAAmB,OACjB,iBAAiB,OAAO,cAAc,IACtC,GAAG,iBAAiB,IAAI,MAAM,KAAK,OAAO,cAAc;CAG9D,MAAM,cAAc;EAClB,GAAG,MAAM,IAAI,OAAO,KAAK;EACzB,gBACI,mBAAmB,OACjB,GAAG,cAAc,SAAS,cAAc,UAAU,GAAG,cAAc,GAAG,GAAG,oBACzE,GAAG,cAAc,SAAS,cAAc,UAAU,MAAM,OAAO,KAAK,IAAI,cAAc,CAAC,EAAE,GAAG,gBAAgB,kDAC9G;EACJ,iBAAiB,CAAC,cAAc,cAAc,SAAS,4BAA4B;EACnF,eAAe,KAAA,IAAY,eAAe,OAAO,UAAU,MAAM;CACnE,CAAC,CACE,OAAO,OAAO,CAAC,CACf,KAAK,IAAI;CAEZ,OACE,qBAAC,OAAD;EACE,aAAU;EACV,kBAAgB;EAChB,kBAAgB;EAChB,WAAW,GAAG,uBAAuB,SAAS;EAC9C,GAAI;EALN,UAAA;GAOE,oBAAC,KAAD;IAAG,WAAU;IAAiC,UAAA;GAAS,CAAA;GAIvD,oBAAC,KAAD;IAAG,WAAU;IAAW,UAAA;GAAe,CAAA;GAEvC,oBAAC,KAAD;IACE,eAAY;IACZ,WAAU;IAET,UAAA,OAAO,KAAK;GACZ,CAAA;GAEF,gBACC,qBAAC,KAAD;IAAG,eAAY;IAAO,WAAU;IAAhC,UAAA,CACE,qBAAC,QAAD;KAAM,WAAW,GAAG,cAAc,EAAE,UAAU,CAAC,CAAC;KAAG,aAAU;KAA7D,UAAA,CACE,oBAAC,QAAD;MAAM,eAAY;MACf,UAAA,cAAc,OAAO,MAAM,cAAc,SAAS,MAAM;KACrD,CAAA,GACL,UACG;IACN,CAAA,GAAA,oBAAC,QAAD;KAAM,WAAU;KAAiC,UAAA;IAAsB,CAAA,CACtE;GACD,CAAA,IAAA;EACD;;AAET"}

package/dist/components/progress/progress.d.ts

@@ -4,7 +4,7 @@ import { ComponentPropsWithRef } from "react";
 //#region src/components/progress/progress.d.ts
 declare const progressVariants: (props?: ({
   size?: "sm" | "md" | "lg" | null | undefined;
-  tone?: "destructive" | "success" | "warning" | "primary" | null | undefined;
+  tone?: "primary" | "destructive" | "success" | "warning" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 interface ProgressProps extends ComponentPropsWithRef<typeof Progress.Root>, VariantProps<typeof progressVariants> {}
 /**

package/dist/components/record-diff/index.d.ts

@@ -0,0 +1,2 @@
+import { FieldChange, RecordDiff, RecordDiffProps, RecordDiffSummary, RecordDiffTable, RecordDiffTableProps, RecordField, diffRecords } from "./record-diff.js";
+export { type FieldChange, RecordDiff, type RecordDiffProps, RecordDiffSummary, RecordDiffTable, type RecordDiffTableProps, type RecordField, diffRecords };

package/dist/components/record-diff/index.js

@@ -0,0 +1,2 @@
+import { RecordDiff, RecordDiffSummary, RecordDiffTable, diffRecords } from "./record-diff.js";
+export { RecordDiff, RecordDiffSummary, RecordDiffTable, diffRecords };

package/dist/components/record-diff/meta.js

@@ -0,0 +1,17 @@
+import { defineMeta } from "../../registry/schema.js";
+//#region src/components/record-diff/meta.ts
+const meta = defineMeta({
+	name: "record-diff",
+	title: "Record Diff",
+	description: "Field-level before and after, for audit entries, settings history and revisions.",
+	category: "data",
+	status: "stable",
+	dependencies: [],
+	registryDependencies: [],
+	files: ["record-diff.tsx"],
+	a11y: "A real table, not a grid of divs. Each field name is a th with scope=\"row\", so a value is announced with the field it belongs to rather than as a loose cell. The kind of change is never carried by row colour alone — every row states added, removed or changed in text for screen readers, satisfying WCAG 1.4.1. The unchanged-field toggle is a real button with aria-expanded. Redacted values never reach the DOM at all."
+});
+//#endregion
+export { meta };
+
+//# sourceMappingURL=meta.js.map

package/dist/components/record-diff/meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.js","names":[],"sources":["../../../src/components/record-diff/meta.ts"],"sourcesContent":["import { defineMeta } from \"@/registry/schema\";\n\nexport const meta = defineMeta({\n  name: \"record-diff\",\n  title: \"Record Diff\",\n  description:\n    \"Field-level before and after, for audit entries, settings history and revisions.\",\n  category: \"data\",\n  status: \"stable\",\n  dependencies: [],\n  registryDependencies: [],\n  files: [\"record-diff.tsx\"],\n  a11y:\n    'A real table, not a grid of divs. Each field name is a th with scope=\"row\", so a value is ' +\n    \"announced with the field it belongs to rather than as a loose cell. The kind of change is \" +\n    \"never carried by row colour alone — every row states added, removed or changed in text for \" +\n    \"screen readers, satisfying WCAG 1.4.1. The unchanged-field toggle is a real button with \" +\n    \"aria-expanded. Redacted values never reach the DOM at all.\",\n});\n"],"mappings":";;AAEA,MAAa,OAAO,WAAW;CAC7B,MAAM;CACN,OAAO;CACP,aACE;CACF,UAAU;CACV,QAAQ;CACR,cAAc,CAAC;CACf,sBAAsB,CAAC;CACvB,OAAO,CAAC,iBAAiB;CACzB,MACE;AAKJ,CAAC"}

package/dist/components/record-diff/record-diff.d.ts

@@ -0,0 +1,56 @@
+import { ComponentPropsWithRef } from "react";
+//#region src/components/record-diff/record-diff.d.ts
+/**
+ * What changed about a record, field by field.
+ *
+ * Every diff package on npm compares lines of text. That is the wrong shape for
+ * an audit entry, a settings revision or a config history, where the change is
+ * "role went from viewer to admin" and rendering it as two lines of JSON makes
+ * the reader do the comparison themselves.
+ *
+ * Scope is deliberately flat records. Nested objects and arrays are formatted as
+ * values rather than recursed into, because a recursive differ is a different
+ * and much larger component, and pretending otherwise would produce a shallow
+ * one that quietly lies about deep changes. `formatValue` is the escape hatch.
+ *
+ * Redaction is by key pattern and applied before formatting, so a secret is
+ * never handed to a formatter that might log it.
+ */
+type FieldChange = "added" | "removed" | "changed" | "unchanged";
+interface RecordField {
+  key: string;
+  label: string;
+  change: FieldChange;
+  before: unknown;
+  after: unknown;
+  redacted: boolean;
+}
+interface RecordDiffProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  before: Record<string, unknown>;
+  after: Record<string, unknown>;
+  /** Overrides the humanised key. */
+  labels?: Record<string, string>;
+  /** Keys to render as redacted. Defaults to common secret-shaped names. */
+  redact?: RegExp;
+  /** Only these keys, in this order. Anything else is ignored. */
+  fields?: string[];
+  /** Hides unchanged fields behind a toggle. */
+  collapseUnchanged?: boolean;
+  formatValue?: (value: unknown, key: string) => string;
+  children?: React.ReactNode;
+}
+declare function diffRecords(before: Record<string, unknown>, after: Record<string, unknown>, options?: {
+  labels?: Record<string, string>;
+  redact?: RegExp;
+  fields?: string[];
+}): RecordField[];
+declare function RecordDiff({ className, before, after, labels, redact, fields: fieldKeys, collapseUnchanged, formatValue, children, ...props }: RecordDiffProps): import("react").JSX.Element;
+/** "3 fields changed" — the thing a reviewer scanning a log needs first. */
+declare function RecordDiffSummary({ className, ...props }: ComponentPropsWithRef<"p">): import("react").JSX.Element;
+interface RecordDiffTableProps extends ComponentPropsWithRef<"table"> {
+  collapseUnchanged?: boolean;
+}
+declare function RecordDiffTable({ className, collapseUnchanged, ...props }: RecordDiffTableProps): import("react").JSX.Element;
+//#endregion
+export { FieldChange, RecordDiff, RecordDiffProps, RecordDiffSummary, RecordDiffTable, RecordDiffTableProps, RecordField, diffRecords };
+//# sourceMappingURL=record-diff.d.ts.map

package/dist/components/record-diff/record-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-diff.d.ts","names":[],"sources":["../../../src/components/record-diff/record-diff.tsx"],"mappings":";;;;;;;;;;;;;;;;;;KA6BY;UAEK;EACf;EACA;EACA,QAAQ;EACR;EACA;EACA;;UAiDe,wBAAwB,KAAK;EAC5C,QAAQ;EACR,OAAO;;EAEP,SAAS;;EAET,SAAS;;EAET;;EAEA;EACA,eAAe,gBAAgB;EAC/B,WAAW,MAAM;;iBA4BH,YACd,QAAQ,yBACR,OAAO,yBACP;EAAW,SAAS;EAAwB,SAAS;EAAQ;IAC5D;iBAwBa,aACd,WACA,QACA,OACA,QACA,QACA,QAAQ,WACR,mBACA,aACA,aACG,SACF,kCAAe,IAAA;;iBAiCF,oBAAoB,cAAc,SAAS,6CAA0B,IAAA;UAgBpE,6BAA6B;EAC5C;;iBAGc,kBACd,WACA,sBACG,SACF,uCAAoB,IAAA"}