@vaam-apps/ui 0.1.0 → 0.1.1

package/src/components/status/state-mark.tsx

@@ -1,154 +0,0 @@
-import type { SVGProps } from "react";
-import { cn } from "../../lib/cn";
-import type { StatusMark, StatusMeta } from "./status-tokens";
-
-export interface StateMarkProps extends Omit<SVGProps<SVGSVGElement>, "className"> {
-  /** One state's presentation, e.g. `MY_STATUS_SYSTEM[state]`. */
-  meta: StatusMeta;
-  /** Rendered size in px. Below 12 the glyph loses its interior mark and
-   * should not be used — at that size the silhouette alone is doing all
-   * the work and a plain dot would be more honest. */
-  size?: 12 | 14 | 16;
-  className?: string | undefined;
-}
-
-// Geometry per design doc §4.3, at a 16x16 viewBox: circle r=6 centred at
-// (8,8), stroke 1.5; the progress wedge/ring inset 1.5 from that stroke
-// (r=4.5); diamond = square rotated 45deg, circumradius 7; square = 10x10
-// centred, corner radius 1. All at stroke-width 1.5.
-const CX = 8;
-const CY = 8;
-const R = 6;
-const R_INNER = 4.5;
-
-/** Clockwise pie wedge from 12 o'clock, `sweepDeg` degrees, radius `r`. */
-function pieWedgePath(sweepDeg: number, r: number): string {
-  const rad = (sweepDeg * Math.PI) / 180;
-  const x = CX + r * Math.sin(rad);
-  const y = CY - r * Math.cos(rad);
-  const largeArc = sweepDeg > 180 ? 1 : 0;
-  return `M${CX},${CY} L${CX},${CY - r} A${r},${r} 0 ${largeArc},1 ${round(x)},${round(y)} Z`;
-}
-
-function round(n: number): number {
-  return Math.round(n * 100) / 100;
-}
-
-const DIAMOND_POINTS = `${CX},${CY - 7} ${CX + 7},${CY} ${CX},${CY + 7} ${CX - 7},${CY}`;
-
-function Silhouette({ meta }: { meta: StatusMeta }) {
-  const fill = meta.filled ? "currentColor" : "none";
-  const stroke = "currentColor";
-
-  switch (meta.silhouette) {
-    case "circle":
-      return <circle cx={CX} cy={CY} r={R} fill={fill} stroke={stroke} strokeWidth={1.5} />;
-    case "diamond":
-      return <polygon points={DIAMOND_POINTS} fill={fill} stroke={stroke} strokeWidth={1.5} />;
-    case "square":
-      return (
-        <rect
-          x={3}
-          y={3}
-          width={10}
-          height={10}
-          rx={1}
-          fill={fill}
-          stroke={stroke}
-          strokeWidth={1.5}
-        />
-      );
-  }
-}
-
-/**
- * Terminal states (delivered/cancelled/expired/rejected/failed) render a
- * solid, filled silhouette (design doc §4.3: "is it over?" is readable from
- * fill alone). The interior mark then has to cut through that fill to stay
- * legible — this is the one place `StateMark` is not literally
- * single-tone: the mark strokes in `--state-mark-knockout` (default: the
- * page canvas colour) rather than `currentColor`, since a currentColor
- * stroke on a currentColor fill would be invisible. Non-terminal marks
- * (pie wedges, the submitted ring, the uncertain "?", the undelivered
- * pause bars) stay `currentColor` throughout, on an unfilled silhouette.
- */
-function InteriorMark({ mark, knockout }: { mark: StatusMark; knockout: boolean }) {
-  const stroke = knockout ? "var(--state-mark-knockout, var(--color-base-100))" : "currentColor";
-  const common = {
-    stroke,
-    strokeWidth: 1.5,
-    strokeLinecap: "round" as const,
-    fill: "none" as const,
-  };
-
-  switch (mark) {
-    case "pie-1":
-      return <path d={pieWedgePath(90, R_INNER)} fill="currentColor" />;
-    case "pie-2":
-      return <path d={pieWedgePath(180, R_INNER)} fill="currentColor" />;
-    case "pie-3":
-      return <path d={pieWedgePath(270, R_INNER)} fill="currentColor" />;
-    case "ring":
-      return (
-        <circle cx={CX} cy={CY} r={R_INNER} fill="none" stroke="currentColor" strokeWidth={1.5} />
-      );
-    case "check":
-      return <polyline points="5.4,8.3 7.2,10.2 11,5.8" strokeLinejoin="round" {...common} />;
-    case "cross":
-      return (
-        <g {...common}>
-          <line x1={5.6} y1={5.6} x2={10.4} y2={10.4} />
-          <line x1={10.4} y1={5.6} x2={5.6} y2={10.4} />
-        </g>
-      );
-    case "slash":
-      return <line x1={5.6} y1={10.4} x2={10.4} y2={5.6} {...common} />;
-    case "bar":
-      return <line x1={5} y1={8} x2={11} y2={8} {...common} />;
-    case "clock":
-      return (
-        <g {...common}>
-          <line x1={8} y1={8} x2={8} y2={5.4} />
-          <line x1={8} y1={8} x2={10.1} y2={8.9} />
-        </g>
-      );
-    case "question":
-      return (
-        <g {...common}>
-          <path d="M6.2 6.6c0-1.1 0.9-1.9 1.9-1.9s1.9 0.7 1.9 1.7c0 1.3-1.9 1.3-1.9 2.9" />
-          <circle cx={8} cy={10.7} r={0.15} fill="currentColor" stroke="none" />
-        </g>
-      );
-    case "pause":
-      return (
-        <g {...common}>
-          <line x1={6.3} y1={5.5} x2={6.3} y2={10.5} />
-          <line x1={9.7} y1={5.5} x2={9.7} y2={10.5} />
-        </g>
-      );
-  }
-}
-
-/**
- * The status-glyph SVG primitive: silhouette × interior mark × fill.
- *
- * Parameterised on a raw [`StatusMeta`] rather than on any particular
- * state enum, so every state machine's pill renders through this one
- * geometry instead of forking it. Pure, and `aria-hidden` — the
- * accessible name belongs on the wrapping pill, which has the label.
- */
-export function StateMark({ meta, size = 14, className, ...props }: StateMarkProps) {
-  return (
-    <svg
-      viewBox="0 0 16 16"
-      width={size}
-      height={size}
-      aria-hidden="true"
-      className={cn("shrink-0", className)}
-      {...props}
-    >
-      <Silhouette meta={meta} />
-      <InteriorMark mark={meta.mark} knockout={meta.filled} />
-    </svg>
-  );
-}

package/src/components/status/status-pill.tsx

@@ -1,153 +0,0 @@
-import type { ComponentType, ReactNode } from "react";
-import { cn } from "../../lib/cn";
-import { StateMark } from "./state-mark";
-import { HUE_CLASSES, type StatusMeta, type StatusSystem } from "./status-tokens";
-
-export interface StatusPillProps {
-  /** One state's presentation, e.g. `MY_STATUS_SYSTEM[state]`. */
-  meta: StatusMeta;
-  /** The raw enum literal, shown when `showLiteral` is set and used in the
-   * accessible name. Optional: a pill for a state machine whose literals
-   * are not user-facing can omit it. */
-  literal?: string | undefined;
-  /** Default `'auto'`: resolved from the state's own `attention` field. */
-  variant?: "auto" | "quiet" | "loud";
-  size?: "sm" | "md";
-  /** Render the mono enum literal beside the label. True in detail views,
-   * false in tables, where the label alone is enough and the literal is
-   * noise repeated down the column. */
-  showLiteral?: boolean;
-  /** Short mono qualifier, e.g. `failed · 4xx`. */
-  detail?: ReactNode;
-  /** Optimistic-transition case: dimmed + dashed, held until the server
-   * confirms. Never use it to mean "we think this is probably the state" —
-   * only for a transition this client has itself just requested. */
-  pending?: boolean;
-  interactive?: boolean;
-  onClick?: (() => void) | undefined;
-  className?: string | undefined;
-}
-
-/**
- * The canonical status representation: glyph + label + attention
- * treatment. Typically the single most-reused component in an operator
- * console — every screen showing a state renders through it.
- *
- * Takes a [`StatusMeta`] rather than a state literal, so one
- * implementation serves every state machine in an application.
- * [`createStatusPill`] is the ergonomic wrapper; reach for this directly
- * only when the meta comes from somewhere other than a fixed table.
- */
-export function StatusPill({
-  meta,
-  literal,
-  variant = "auto",
-  size = "sm",
-  showLiteral = false,
-  detail,
-  pending = false,
-  interactive = false,
-  onClick,
-  className,
-}: StatusPillProps) {
-  const resolvedVariant = variant === "auto" ? meta.attention : variant;
-  const loud = resolvedVariant === "loud";
-  const hue = HUE_CLASSES[meta.hue];
-  const markSize = size === "md" ? 16 : 14;
-
-  const Comp = interactive ? "button" : "span";
-
-  return (
-    <Comp
-      type={interactive ? "button" : undefined}
-      onClick={interactive ? onClick : undefined}
-      title={meta.tooltip}
-      // A non-interactive pill is an image of a state, not a label for
-      // one; without `role="img"` the `aria-label` on a `<span>` is
-      // ignored by several screen readers.
-      role={interactive ? undefined : "img"}
-      aria-label={literal === undefined ? meta.label : `${literal} — ${meta.label}`}
-      className={cn(
-        "inline-flex items-center gap-[5px] whitespace-nowrap align-middle",
-        "text-caption",
-        loud && [hue.bg, hue.border, "rounded-sm border py-0.5 pr-1.5 pl-[5px] font-medium"],
-        // A dashed outline, and NOT dimming. `pending` used to be
-        // `opacity-60`, which took its own text to 2.71:1 against the
-        // page — below AA, and unreadable at exactly the moment a reader
-        // most wants to know what is happening. Measured before changing
-        // it: the opacity that keeps this text at AA is 0.90, by which
-        // point the dimming conveys nothing. So the state says so with a
-        // border instead, at full text contrast.
-        //
-        // A quiet pill has no border to dash, so it grows the same box a
-        // loud one has — otherwise `pending` would be invisible on the
-        // majority of pills.
-        pending && "border-dashed",
-        pending && !loud && "rounded-sm border border-edge-strong py-0.5 pr-1.5 pl-[5px]",
-        interactive && "cursor-pointer",
-        className,
-      )}
-    >
-      <StateMark meta={meta} size={markSize} className={hue.fg} />
-      <span className={loud ? hue.fg : "text-muted-foreground"}>{meta.label}</span>
-      {/* `muted`, not `subtle`, once the pill is loud. A loud pill paints a
-          state tint behind this text, and `--subtle-foreground` does not
-          reach 4.5:1 on a tint over anything lighter than the page
-          background — 4.36:1 over a card, 3.85:1 over a hovered row.
-          Measured, and not fixable by nudging the token: the value that
-          would clear AA on a tint is ΔE 2 from `--muted-foreground`,
-          which collapses the three-tier text ladder into two. So the
-          tier changes with the background instead. */}
-      {showLiteral && literal !== undefined && (
-        <span
-          className={cn(
-            "font-mono text-micro",
-            loud ? "text-muted-foreground" : "text-subtle-foreground",
-          )}
-        >
-          {literal}
-        </span>
-      )}
-      {detail != null && (
-        <span
-          className={cn("font-mono", loud ? "text-muted-foreground" : "text-subtle-foreground")}
-        >
-          {detail}
-        </span>
-      )}
-    </Comp>
-  );
-}
-
-export type TypedStatusPillProps<S extends string> = Omit<StatusPillProps, "meta" | "literal"> & {
-  state: S;
-};
-
-/**
- * Binds a [`StatusSystem`] to a pill component whose `state` prop accepts
- * exactly that system's states and nothing else.
- *
- * ```tsx
- * export const OrderStatusPill = createStatusPill(ORDER_STATUS);
- * <OrderStatusPill state="refunded" showLiteral />
- * ```
- *
- * This replaced three hand-written, near-identical pill components — one
- * per state machine — that differed only in which table they indexed and
- * had already drifted apart in small ways (one set `role="img"`, one did
- * not; one supported `interactive`, two did not). Their own doc comments
- * each argued for staying separate on the grounds that the state machines
- * genuinely differ in meaning — which is true, and is preserved here:
- * each machine still has its own table and its own component identity,
- * and `state` is still typed to one machine's literals, so a `JobState`
- * cannot be passed to an order pill. What they do not need is three
- * copies of the rendering.
- */
-export function createStatusPill<S extends string>(
-  system: StatusSystem<S>,
-): ComponentType<TypedStatusPillProps<S>> {
-  function BoundStatusPill({ state, ...props }: TypedStatusPillProps<S>) {
-    return <StatusPill meta={system[state]} literal={state} {...props} />;
-  }
-  return BoundStatusPill;
-}

package/src/components/status/status-tokens.ts

@@ -1,173 +0,0 @@
-/**
- * The vocabulary of a status-glyph system — types and shared classes only,
- * no domain data.
- *
- * # What this is
- *
- * A *status system* is one state machine's presentation: a table mapping
- * every state that machine can be in to a glyph, a hue, an attention level
- * and human copy. This module owns the vocabulary and the rendering; the
- * table itself belongs to whoever owns the state machine, which is never
- * this package.
- *
- * ```tsx
- * const ORDER_STATUS = defineStatusSystem({
- *   pending:  { family: "in-flight", silhouette: "circle", mark: "pie-1",
- *               hue: "neutral", filled: false, attention: "quiet",
- *               label: "Pending", tooltip: "Awaiting payment." },
- *   paid:     { family: "terminal", silhouette: "circle", mark: "check",
- *               hue: "success", filled: true, attention: "quiet",
- *               label: "Paid", tooltip: "Settled." },
- *   refunded: { family: "terminal", silhouette: "circle", mark: "bar",
- *               hue: "neutral", filled: true, attention: "quiet",
- *               label: "Refunded", tooltip: "Returned to the payer." },
- * });
- *
- * const OrderStatusPill = createStatusPill(ORDER_STATUS);
- * <OrderStatusPill state="paid" />
- * ```
- *
- * # Every field here is PRESENTATIONAL
- *
- * Never use `family` — or anything else in a `StatusMeta` — to decide
- * whether an action is permitted. Terminality is data, and the server
- * owns it: a UI that greys out "cancel" because its own table says
- * `terminal` will be wrong the first time the state machine changes and
- * nobody remembers this table exists. Propose the action and let the
- * server refuse it.
- *
- * # Why a glyph and not just colour
- *
- * Colour alone fails for the ~8% of men with a colour-vision deficiency,
- * and fails completely in a screenshot pasted into a monochrome ticket.
- * Each state therefore differs in *silhouette* (circle / diamond /
- * square), *interior mark*, and *fill* as well as hue — three redundant
- * channels, so no single one is load-bearing.
- */
-
-/**
- * The three-way split every state machine this system has met so far
- * reduces to: still moving, stopped somewhere that needs a human, or done.
- *
- * `unresolved` is the one worth naming explicitly — it is not a failure
- * and not a success, and systems that only model two outcomes end up
- * calling it whichever is more convenient, which is how "we never learned
- * the outcome" gets reported to a user as "delivered".
- */
-export type StatusFamily = "in-flight" | "unresolved" | "terminal";
-
-export type StatusSilhouette = "circle" | "diamond" | "square";
-
-/**
- * The interior mark drawn inside the silhouette. `pie-1`..`pie-3` are the
- * quarter-fill progress wedge; `ring` is a completed stroke with a hollow
- * centre (handed off, awaiting an external answer).
- */
-export type StatusMark =
-  | "pie-1"
-  | "pie-2"
-  | "pie-3"
-  | "ring"
-  | "check"
-  | "bar"
-  | "clock"
-  | "slash"
-  | "cross"
-  | "question"
-  | "pause";
-
-/**
- * The saturated hues a status may take.
- *
- * `warning` and `uncertain` are deliberately distinct despite both reading
- * as "attention": `uncertain` means the outcome is unknown, `warning`
- * means a recoverable condition needs a human. `expired` and `parked` are
- * separated from `neutral` for the same reason — a state nobody needs to
- * act on and a state waiting for someone should not look identical.
- */
-export type StatusHue =
-  | "neutral"
-  | "success"
-  | "warning"
-  | "danger"
-  | "uncertain"
-  | "expired"
-  | "parked";
-
-/** Quiet: glyph only, no fill. Loud: tinted background + border. */
-export type StatusAttention = "quiet" | "loud";
-
-export interface StatusMeta {
-  family: StatusFamily;
-  silhouette: StatusSilhouette;
-  mark: StatusMark;
-  hue: StatusHue;
-  /** Terminal marks sit on a filled silhouette; in-flight/unresolved marks are stroked-only. */
-  filled: boolean;
-  attention: StatusAttention;
-  /** Human-facing name. Sentence case, not the raw enum literal. */
-  label: string;
-  /** One or two sentences saying what this state means and what happens next. */
-  tooltip: string;
-}
-
-/** One state machine's complete presentation table. */
-export type StatusSystem<S extends string> = Readonly<Record<S, StatusMeta>>;
-
-/**
- * Identity at runtime; exists for inference. Without it a caller must
- * write `const X: StatusSystem<"a" | "b"> = {…}` and repeat every key in
- * the type annotation; with it, `S` is inferred from the object's own keys
- * and `createStatusPill(X)` then accepts exactly those keys and no others.
- */
-export function defineStatusSystem<S extends string>(system: StatusSystem<S>): StatusSystem<S> {
-  return system;
-}
-
-/**
- * Whether a state is terminal *according to its own table* — a
- * presentational question ("should this row stop animating"), never an
- * authorisation one. See this module's own warning above.
- */
-export function isTerminalStatus<S extends string>(system: StatusSystem<S>, state: S): boolean {
-  return system[state].family === "terminal";
-}
-
-/** Hue → the token classes every status surface renders through. */
-export const HUE_CLASSES: Record<StatusHue, { fg: string; bg: string; border: string }> = {
-  neutral: {
-    fg: "text-state-neutral-fg",
-    bg: "bg-state-neutral-bg",
-    border: "border-state-neutral-border",
-  },
-  success: {
-    fg: "text-state-success-fg",
-    bg: "bg-state-success-bg",
-    border: "border-state-success-border",
-  },
-  warning: {
-    fg: "text-state-warning-fg",
-    bg: "bg-state-warning-bg",
-    border: "border-state-warning-border",
-  },
-  danger: {
-    fg: "text-state-danger-fg",
-    bg: "bg-state-danger-bg",
-    border: "border-state-danger-border",
-  },
-  uncertain: {
-    fg: "text-state-uncertain-fg",
-    bg: "bg-state-uncertain-bg",
-    border: "border-state-uncertain-border",
-  },
-  expired: {
-    fg: "text-state-expired-fg",
-    bg: "bg-state-expired-bg",
-    border: "border-state-expired-border",
-  },
-  parked: {
-    fg: "text-state-parked-fg",
-    bg: "bg-state-parked-bg",
-    border: "border-state-parked-border",
-  },
-};

package/src/index.ts

@@ -1,96 +0,0 @@
-/**
- * `@vaam-apps/ui` — a dark-first React component library for operator
- * consoles: daisyUI for styling, Headless UI for behaviour, and a
- * parameterised status-glyph system for state machines.
- *
- * Import the token layer **once**, from the app's own global stylesheet,
- * after loading Tailwind and the daisyUI plugin:
- *
- * ```css
- * @import "tailwindcss";
- * @plugin "daisyui";
- * @import "@vaam-apps/ui/styles/theme.css";
- * @source "../node_modules/@vaam-apps/ui/dist";
- * ```
- *
- * The `@source` line is not optional: Tailwind v4 only generates the
- * utilities it can see used, and it does not look inside `node_modules`
- * by default. Omit it and every component renders unstyled — a silent
- * failure that is miserable to debug.
- */
-
-// ---------------------------------------------------------------------------
-// Data display — consistency is the deliverable, so these are components
-// rather than ad hoc per-screen formatting.
-// ---------------------------------------------------------------------------
-export * from "./components/data/code";
-export * from "./components/data/copy-button";
-export * from "./components/data/detail-row";
-export * from "./components/data/id-display";
-export * from "./components/data/masked-value";
-export * from "./components/data/money";
-export * from "./components/data/phone-display";
-export * from "./components/data/stat-tile";
-export * from "./components/data/timestamp-display";
-// ---------------------------------------------------------------------------
-// Patterns — composed screen-level building blocks. Still domain-free,
-// but opinionated about layout in a way the primitives are not.
-// ---------------------------------------------------------------------------
-export * from "./components/patterns/inline-banner";
-export * from "./components/patterns/inline-empty-state";
-export * from "./components/patterns/live-row";
-export * from "./components/patterns/payload-inspector";
-export * from "./components/patterns/route-skeleton";
-export * from "./components/patterns/screen-layout";
-export * from "./components/patterns/stale-write-banner";
-export * from "./components/patterns/state-timeline";
-// ---------------------------------------------------------------------------
-// Primitives
-// ---------------------------------------------------------------------------
-export * from "./components/primitives/badge";
-export * from "./components/primitives/button";
-export * from "./components/primitives/calendar";
-export * from "./components/primitives/card";
-export * from "./components/primitives/checkbox";
-export * from "./components/primitives/chip-select";
-export * from "./components/primitives/command-menu";
-export * from "./components/primitives/confirm-dialog";
-export * from "./components/primitives/date-picker";
-export * from "./components/primitives/dialog";
-export * from "./components/primitives/drawer";
-export * from "./components/primitives/dropdown-menu";
-export * from "./components/primitives/form-field";
-export * from "./components/primitives/inline-confirm";
-export * from "./components/primitives/input";
-export * from "./components/primitives/label";
-export * from "./components/primitives/pagination";
-export * from "./components/primitives/popover";
-export * from "./components/primitives/progress";
-export * from "./components/primitives/radio-group";
-export * from "./components/primitives/select";
-export * from "./components/primitives/separator";
-export * from "./components/primitives/side-nav";
-export * from "./components/primitives/skeleton";
-export * from "./components/primitives/spinner";
-export * from "./components/primitives/switch";
-export * from "./components/primitives/table";
-export * from "./components/primitives/tabs";
-export * from "./components/primitives/textarea";
-export * from "./components/primitives/toast";
-export * from "./components/primitives/tooltip";
-// ---------------------------------------------------------------------------
-// Status — the most-reused surface in an operator console. Read
-// `status-tokens.ts` first: the tables live in the consuming application,
-// not here.
-// ---------------------------------------------------------------------------
-export * from "./components/status/state-chip";
-export * from "./components/status/state-mark";
-export * from "./components/status/status-pill";
-export * from "./components/status/status-tokens";
-
-// ---------------------------------------------------------------------------
-// Utilities
-// ---------------------------------------------------------------------------
-export { cn } from "./lib/cn";
-export * from "./lib/money";
-export { omitUndefined } from "./lib/omit-undefined";