@vaam-apps/ui 0.1.0 → 0.1.1

package/src/components/data/masked-value.tsx

@@ -1,96 +0,0 @@
-"use client";
-
-import { Eye, EyeOff } from "lucide-react";
-import { useState } from "react";
-import { cn } from "../../lib/cn";
-import { CopyButton } from "./copy-button";
-
-export interface MaskedValueProps {
-  /** The full value. Present in the DOM only while revealed. */
-  value: string;
-  /** Trailing characters left visible while masked, so the value stays
-   * recognisable without being readable. `0` masks everything. */
-  reveal?: number;
-  /** Leading characters left visible — for a prefixed credential like
-   * `whsec_…` or `sk_live_…`, where the prefix says what kind of thing it
-   * is and is not itself secret. */
-  prefix?: number;
-  /** Allow revealing at all. `false` gives a permanently masked value with
-   * no toggle — for something displayed for recognition only. */
-  revealable?: boolean;
-  /** Offer a copy button. Copies the full value whether or not it is
-   * currently revealed — the point of masking is the screen, not the
-   * clipboard. */
-  copyable?: boolean;
-  /** Names the value in the toggle's and copy button's accessible names,
-   * e.g. `"signing secret"`. */
-  label?: string;
-  className?: string | undefined;
-}
-
-const DOT = "•";
-
-function mask(value: string, prefix: number, reveal: number): string {
-  const head = value.slice(0, prefix);
-  const tail = reveal > 0 ? value.slice(-reveal) : "";
-  const hiddenCount = Math.max(value.length - head.length - tail.length, 0);
-  // A fixed run of dots, not one per character: the exact length of a
-  // secret is information, and padding it out to the real length leaks it
-  // to anyone looking over a shoulder.
-  const dots = DOT.repeat(hiddenCount === 0 ? 0 : Math.min(Math.max(hiddenCount, 6), 12));
-  return `${head}${dots}${tail}`;
-}
-
-/**
- * A secret or sensitive value, masked by default with an explicit reveal.
- *
- * # What this is and is not
- *
- * It is a **shoulder-surfing and screen-share control**, not a security
- * boundary. Whoever renders this already received the value over the
- * wire; anyone with the session and dev tools can read it regardless.
- * Withholding data that has already crossed the wire to an authorised,
- * authenticated session would be theatre. What masking buys is real but
- * narrow: the value does not end up in a screenshot, a recording, or the
- * eyeline of the person sitting behind the operator.
- *
- * If a value must genuinely never reach the client, that is an API
- * decision — do not send it — and no component can substitute for it.
- *
- * # Why it is shared
- *
- * Both applications this package serves had hand-rolled one: a console
- * masking a webhook signing secret as `whsec_••••••••••<last 4>`, and a
- * payments dashboard rendering a masked payer reference and a TOTP
- * enrolment secret as plain text because no such component existed.
- */
-export function MaskedValue({
-  value,
-  reveal = 4,
-  prefix = 0,
-  revealable = true,
-  copyable = true,
-  label = "value",
-  className,
-}: MaskedValueProps) {
-  const [revealed, setRevealed] = useState(false);
-  const shown = revealed ? value : mask(value, prefix, reveal);
-
-  return (
-    <span className={cn("group inline-flex items-center gap-1.5", className)}>
-      <span className={cn("font-mono", revealed && "select-all break-all")}>{shown}</span>
-      {revealable && (
-        <button
-          type="button"
-          onClick={() => setRevealed((previous) => !previous)}
-          aria-label={revealed ? `Hide ${label}` : `Reveal ${label}`}
-          aria-pressed={revealed}
-          className="shrink-0 text-subtle-foreground transition-colors hover:text-foreground"
-        >
-          {revealed ? <EyeOff size={12} strokeWidth={1.5} /> : <Eye size={12} strokeWidth={1.5} />}
-        </button>
-      )}
-      {copyable && <CopyButton value={value} label={`Copy ${label}`} />}
-    </span>
-  );
-}

package/src/components/data/money.tsx

@@ -1,46 +0,0 @@
-import { cn } from "../../lib/cn";
-import { type FormatMoneyOptions, formatMoney, type MinorUnits } from "../../lib/money";
-
-export interface MoneyProps extends FormatMoneyOptions {
-  /** An integer count of the currency's smallest unit. */
-  amount: MinorUnits;
-  /** ISO 4217 code, e.g. `"XAF"`. */
-  currency: string;
-  /** Tint by sign: credits green, debits red. Off by default — in a
-   * ledger where most rows are one direction, colouring every row is
-   * noise, and colour alone is not an accessible way to convey sign. The
-   * minus sign is always rendered regardless. */
-  tone?: "none" | "signed";
-  className?: string | undefined;
-}
-
-/**
- * An amount of money, right-alignable and vertically comparable.
- *
- * `tabular-nums` is the whole reason this is a component and not a call to
- * [`formatMoney`] in a `<span>`: without fixed-width digits, a column of
- * amounts does not line up at the decimal point, and scanning it for an
- * outlier — the actual job — stops working.
- *
- * `<data value>` rather than `<span>`: the machine-readable amount stays
- * in the DOM in minor units, so a copy-paste or a scraper gets the exact
- * integer rather than a locale-formatted string it would have to parse
- * back.
- */
-export function Money({ amount, currency, tone = "none", className, ...options }: MoneyProps) {
-  const formatted = formatMoney(amount, currency, options);
-  const negative = String(amount).trim().startsWith("-");
-
-  return (
-    <data
-      value={`${String(amount)} ${currency}`}
-      className={cn(
-        "font-mono tabular-nums whitespace-nowrap",
-        tone === "signed" && (negative ? "text-state-danger-fg" : "text-state-success-fg"),
-        className,
-      )}
-    >
-      {formatted}
-    </data>
-  );
-}

package/src/components/data/phone-display.tsx

@@ -1,60 +0,0 @@
-import { cn } from "../../lib/cn";
-import { CopyButton } from "./copy-button";
-
-export interface PhoneDisplayProps {
-  /** E.164, e.g. `+237677123456`. Stored form, and what gets copied. */
-  value: string;
-  /**
-   * Regroups the E.164 digits for reading. Return `null` — or omit the
-   * prop — to render the value verbatim.
-   *
-   * Grouping is a per-country convention (`+237 6 77 12 34 56` in
-   * Cameroon, `+1 (415) 555-0132` in the NANP) and getting it wrong is
-   * worse than not grouping at all, because a mis-grouped number reads as
-   * a different number. This component therefore ships no default
-   * grouping and no built-in country table: a caller that knows its
-   * market passes a formatter, and everyone else gets the raw E.164,
-   * which is always correct if less pretty.
-   */
-  format?: ((e164: string) => string | null) | undefined;
-  /**
-   * A short mono tag after the number — a carrier, a line type, a region.
-   * Renders an em dash when absent, so a column of numbers stays aligned
-   * whether or not each row could be classified.
-   */
-  tag?: string | undefined;
-  /** Hover text for the tag. Say where it came from and how much to trust
-   * it: a carrier inferred from a number prefix is a guess, and number
-   * portability means it is wrong for a real fraction of subscribers. */
-  tagTitle?: string | undefined;
-  className?: string | undefined;
-}
-
-/**
- * A phone number, never truncated.
- *
- * Truncation is banned rather than discouraged: a half-shown phone number
- * is worse than useless in an investigation, and unlike an opaque id
- * (where a prefix is enough to match rows by eye) there is no prefix of a
- * phone number that identifies it.
- *
- * Copy always copies the raw E.164 — the form that pastes into a query —
- * not the grouped form on screen.
- *
- * Previously this was `MsisdnDisplay`, with Cameroon's `+237` grouping and
- * a four-entry Cameroonian carrier table compiled in. Both are now the
- * caller's: an application knows its market, a component library does not.
- */
-export function PhoneDisplay({ value, format, tag, tagTitle, className }: PhoneDisplayProps) {
-  const formatted = format?.(value) ?? value;
-
-  return (
-    <span className={cn("group inline-flex items-center gap-1.5 whitespace-nowrap", className)}>
-      <span className="font-mono tabular-nums">{formatted}</span>
-      <span className="font-mono text-micro text-subtle-foreground" title={tagTitle}>
-        {tag ?? "—"}
-      </span>
-      <CopyButton value={value} revealOnGroupHover />
-    </span>
-  );
-}

package/src/components/data/stat-tile.tsx

@@ -1,68 +0,0 @@
-import type { ReactNode } from "react";
-import { cn } from "../../lib/cn";
-import type { StatusHue } from "../status/status-tokens";
-import { HUE_CLASSES } from "../status/status-tokens";
-
-export interface StatTileProps {
-  label: ReactNode;
-  /** The number itself. Pass a `Money` or a formatted string — this
-   * component does no formatting, because a tile has no way to know
-   * whether it is showing a count, a currency or a rate. */
-  value: ReactNode;
-  /** One line under the value: the comparison, the window, the caveat.
-   * A bare number with no denominator is the most common way a dashboard
-   * misleads, so this slot exists to make the denominator easy. */
-  caption?: ReactNode;
-  /** Tints the value. Leave unset unless the number's own colour carries
-   * meaning — a wall of coloured tiles makes the one that matters harder
-   * to find, which is the opposite of the point. */
-  tone?: StatusHue | undefined;
-  /** Top-right slot — a sparkline, a `StateChip`, a refresh button. */
-  action?: ReactNode;
-  className?: string | undefined;
-}
-
-/**
- * One headline number with its label and context.
- *
- * Borders, not shadows, and no card chrome of its own beyond a hairline:
- * tiles appear in rows of three to six, and six shadowed boxes is visual
- * noise where six outlined ones read as one instrument panel.
- *
- * `<dl>`/`<dt>`/`<dd>` rather than divs — a tile *is* a term and its
- * definition, and the semantics make a row of them navigable rather than
- * an undifferentiated wall of text to a screen reader.
- */
-export function StatTile({ label, value, caption, tone, action, className }: StatTileProps) {
-  return (
-    <div
-      className={cn(
-        "relative flex flex-col rounded-box border border-edge bg-base-300 p-4",
-        className,
-      )}
-    >
-      {/* Outside the `<dl>`, and absolutely positioned rather than a flex
-          sibling of the `<dt>`. A `<dl>` may contain only `<dt>`, `<dd>`
-          and `<div>`s that wrap dt/dd groups — an action button among
-          them is invalid markup, which axe reports as a serious
-          `definition-list` violation. Found by the a11y addon, after an
-          earlier version nested the action in a header row inside the
-          list. */}
-      {action != null && <div className="absolute top-4 right-4">{action}</div>}
-      <dl className="flex flex-col gap-1">
-        <dt className={cn("text-caption text-muted-foreground", action != null && "pr-20")}>
-          {label}
-        </dt>
-        <dd
-          className={cn(
-            "font-mono text-metric tabular-nums",
-            tone === undefined ? "text-foreground" : HUE_CLASSES[tone].fg,
-          )}
-        >
-          {value}
-        </dd>
-        {caption != null && <dd className="text-caption text-subtle-foreground">{caption}</dd>}
-      </dl>
-    </div>
-  );
-}

package/src/components/data/timestamp-display.tsx

@@ -1,106 +0,0 @@
-"use client";
-
-import { useEffect, useState, useSyncExternalStore } from "react";
-import { cn } from "../../lib/cn";
-
-// A single shared 30s interval drives every `TimestampDisplay` instance's
-// relative-time re-render (design doc §7.2: "a table of 200 rows must not
-// run 200 timers"). Lazily started on the first mounted instance, torn
-// down when the last one unmounts.
-
-let tick = 0;
-const listeners = new Set<() => void>();
-let timer: ReturnType<typeof setInterval> | null = null;
-
-function subscribe(listener: () => void): () => void {
-  listeners.add(listener);
-  timer ??= setInterval(() => {
-    tick += 1;
-    for (const l of listeners) l();
-  }, 30_000);
-  return () => {
-    listeners.delete(listener);
-    if (listeners.size === 0 && timer !== null) {
-      clearInterval(timer);
-      timer = null;
-    }
-  };
-}
-
-function useSharedTick(): number {
-  return useSyncExternalStore(
-    subscribe,
-    () => tick,
-    () => 0,
-  );
-}
-
-function pad(n: number): string {
-  return String(n).padStart(2, "0");
-}
-
-/** `2026-08-08 14:03:07` + a zone suffix — ISO-ordered so it sorts and
- * compares visually (design doc §7.2). Only UTC is implemented (`Z`
- * suffix, always): the Africa/Douala toggle lives on the top bar, which
- * this screen doesn't build. "A bare local time with no zone label never
- * appears anywhere in this product" still holds — the suffix is always
- * present, just not yet switchable. */
-function formatAbsolute(date: Date): string {
-  const y = date.getUTCFullYear();
-  const mo = pad(date.getUTCMonth() + 1);
-  const d = pad(date.getUTCDate());
-  const h = pad(date.getUTCHours());
-  const mi = pad(date.getUTCMinutes());
-  const s = pad(date.getUTCSeconds());
-  return `${y}-${mo}-${d} ${h}:${mi}:${s}Z`;
-}
-
-function formatRelative(diffMs: number): string {
-  const minutes = Math.floor(diffMs / 60_000);
-  if (minutes < 1) return "just now";
-  if (minutes < 60) return `${minutes}m`;
-  const hours = Math.floor(minutes / 60);
-  return `${hours}h`;
-}
-
-export interface TimestampDisplayProps {
-  /** ISO-8601. */
-  value: string;
-  className?: string;
-}
-
-/**
- * Relative for anything under 24h (`2m`, `47m`, `6h`), absolute otherwise
- * — design doc §7.2. Renders the absolute value on the server and on
- * first client render (so server/client markup matches and Next doesn't
- * warn/flash), then upgrades to relative once mounted, driven by the
- * shared interval above rather than its own timer.
- */
-export function TimestampDisplay({ value, className }: TimestampDisplayProps) {
-  useSharedTick();
-  const [hydrated, setHydrated] = useState(false);
-  useEffect(() => setHydrated(true), []);
-
-  const date = new Date(value);
-  const absolute = formatAbsolute(date);
-
-  if (!hydrated) {
-    return (
-      <span className={cn("font-mono text-subtle-foreground tabular-nums", className)}>
-        {absolute}
-      </span>
-    );
-  }
-
-  const diffMs = Date.now() - date.getTime();
-  const display = diffMs >= 0 && diffMs < 24 * 3600 * 1000 ? formatRelative(diffMs) : absolute;
-
-  return (
-    <span
-      title={absolute}
-      className={cn("font-mono text-subtle-foreground tabular-nums", className)}
-    >
-      {display}
-    </span>
-  );
-}

package/src/components/patterns/inline-banner.tsx

@@ -1,60 +0,0 @@
-import type { ReactNode } from "react";
-import { cn } from "../../lib/cn";
-
-// R6 (AGENTS.md): the same three banner treatments — a neutral scope/notice
-// box, a danger error box, and a plain caption-only note — were hand-rolled
-// inline in every screen that needed one (`rounded-sm border border-edge
-// bg-surface-2 px-3 py-2 text-caption text-muted-foreground` for "neutral",
-// `border-state-danger-border bg-state-danger-bg ... text-state-danger-fg`
-// for "danger"). Classes moved here verbatim, parameterised by variant, not
-// redesigned. `InlineEmptyState` already set the precedent for this shape
-// of extraction (a status treatment repeated per-screen, given one home) —
-// this is the same move applied to a different repeated block.
-//
-// Not to be confused with `InlineEmptyState`: that one is for "there is
-// nothing to show here" inside a list; this one is for a standing notice or
-// an error above/around content that *is* showing.
-
-export interface InlineBannerProps {
-  /** `'neutral'` — a standing notice (scope, caveat). `'danger'` — an
-   * error. `'warning'` — recoverable, needs attention (a stale write).
-   * `'success'` — a positive confirmation (a verified audit chain).
-   * `'uncertain'` — degraded or unknown, neither failure nor success (a
-   * stalled live feed, a UCS-2 volume spike). `'plain'` — a caption-only
-   * note with no border or fill, for something that doesn't need the
-   * weight of a bordered box.
-   *
-   * The last three were added after the R6 factorization, not with it:
-   * four route groups had hand-rolled boxes in exactly these tones because
-   * the variant they needed did not exist, and the agents doing the
-   * factorization were deliberately barred from editing this package. Two
-   * of them flagged the gap rather than inventing a competing component,
-   * which is the behaviour the constraint was for. */
-  variant?: "neutral" | "danger" | "warning" | "success" | "uncertain" | "plain";
-  children: ReactNode;
-  className?: string;
-}
-
-export function InlineBanner({ variant = "neutral", children, className }: InlineBannerProps) {
-  return (
-    <div
-      className={cn(
-        "text-caption",
-        variant === "neutral" &&
-          "rounded-sm border border-edge bg-surface-2 px-3 py-2 text-muted-foreground",
-        variant === "danger" &&
-          "rounded-sm border border-state-danger-border bg-state-danger-bg px-3 py-2 text-state-danger-fg",
-        variant === "warning" &&
-          "rounded-sm border border-state-warning-border bg-state-warning-bg px-3 py-2 text-state-warning-fg",
-        variant === "success" &&
-          "rounded-sm border border-state-success-border bg-state-success-bg px-3 py-2 text-state-success-fg",
-        variant === "uncertain" &&
-          "rounded-sm border border-state-uncertain-border bg-state-uncertain-bg px-3 py-2 text-state-uncertain-fg",
-        variant === "plain" && "text-subtle-foreground",
-        className,
-      )}
-    >
-      {children}
-    </div>
-  );
-}

package/src/components/patterns/inline-empty-state.tsx

@@ -1,45 +0,0 @@
-import type { ReactNode } from "react";
-import { cn } from "../../lib/cn";
-
-export interface InlineEmptyStateProps {
-  message: ReactNode;
-  action?: { label: string; onClick: () => void };
-  /** `'standalone'` is the one exception (§5.3): a screen with nothing else
-   * to do may centre a single line plus one primary action. Still no
-   * illustration, still no card. */
-  variant?: "inline" | "standalone";
-  className?: string;
-}
-
-/**
- * Enforces the binding rule: empty states are inline status lines, not
- * centred placards. Use inside a table body (spanning all columns) or in
- * the panel where the missing list would be.
- */
-export function InlineEmptyState({
-  message,
-  action,
-  variant = "inline",
-  className,
-}: InlineEmptyStateProps) {
-  return (
-    <div
-      className={cn(
-        "flex items-center gap-3 text-body text-muted-foreground",
-        variant === "standalone" ? "justify-center py-16 text-center" : "py-3 text-left",
-        className,
-      )}
-    >
-      <span>{message}</span>
-      {action != null && (
-        <button
-          type="button"
-          onClick={action.onClick}
-          className="text-foreground underline decoration-edge-strong underline-offset-2 hover:decoration-foreground"
-        >
-          {action.label}
-        </button>
-      )}
-    </div>
-  );
-}

package/src/components/patterns/live-row.tsx

@@ -1,75 +0,0 @@
-"use client";
-
-import { useEffect, useRef, useState } from "react";
-import { cn } from "../../lib/cn";
-import { TableRow, type TableRowProps } from "../primitives/table";
-import type { StatusHue } from "../status/status-tokens";
-
-export interface LiveRowProps extends TableRowProps {
-  /** Any value that changes to trigger a wash — pass the row's `@version`, an exact change key immune to clock skew. */
-  washTrigger: string | number;
-  /** The destination state's hue, so the wash tints toward where the row landed. */
-  washHue?: StatusHue;
-}
-
-const WASH_BG_CLASS: Record<StatusHue, string> = {
-  neutral: "bg-state-neutral-fg/10",
-  success: "bg-state-success-fg/10",
-  warning: "bg-state-warning-fg/10",
-  danger: "bg-state-danger-fg/10",
-  uncertain: "bg-state-uncertain-fg/10",
-  expired: "bg-state-expired-fg/10",
-  parked: "bg-state-parked-fg/10",
-};
-
-/**
- * The row-level half of the design doc's `LiveTable`/`LiveRow` contract
- * (§5.3, §6.5 rule 4): "in-place status change never moves a row" — this
- * wraps `TableRow` with the 240ms wash-then-decay on a status change,
- * nothing else moves or resizes. The full `LiveTable` (scroll-position-
- * dependent buffered insertion, the sticky "N new" pill, sort-mode
- * switching) is a later, screen-level task — this is the reusable unit it
- * will be built on, shipped now so the wash behaviour isn't retrofitted
- * per-screen later.
- *
- * Reduced motion (§3.8 rule 3): the wash becomes a static hold instead of
- * a timed decay — the signal must survive, only the animation may not.
- */
-export function LiveRow({
-  washTrigger,
-  washHue = "neutral",
-  className,
-  children,
-  ...props
-}: LiveRowProps) {
-  const [washing, setWashing] = useState(false);
-  const previousTrigger = useRef(washTrigger);
-  const reducedMotion =
-    typeof window !== "undefined" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-
-  useEffect(() => {
-    if (previousTrigger.current === washTrigger) return;
-    previousTrigger.current = washTrigger;
-    setWashing(true);
-    const holdMs = reducedMotion ? 1200 : 400 + 240 + 600;
-    const timeout = setTimeout(() => setWashing(false), holdMs);
-    return () => clearTimeout(timeout);
-  }, [washTrigger, reducedMotion]);
-
-  return (
-    <TableRow
-      className={cn(
-        washing && [
-          WASH_BG_CLASS[washHue],
-          reducedMotion
-            ? "transition-none"
-            : "transition-colors duration-[var(--dur-state)] ease-out",
-        ],
-        className,
-      )}
-      {...props}
-    >
-      {children}
-    </TableRow>
-  );
-}