@tangle-network/ui 11.2.4 → 11.3.0

package/src/primitives/metric-strip.test.tsx

@@ -0,0 +1,181 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Metric, MetricStrip } from "./metric-strip";
+
+describe("MetricStrip", () => {
+  it("pairs each label with its value as a described term", () => {
+    render(
+      <MetricStrip>
+        <Metric label="Balance" value="$248.55" />
+      </MetricStrip>,
+    );
+    // The label is wrapped for truncation, so assert the term it belongs to.
+    expect(screen.getByText("Balance").closest("dt")).not.toBeNull();
+    expect(screen.getByText("$248.55").tagName).toBe("DD");
+  });
+
+  // axe's `definition-list` rule allows only dt, dd, script, template and div
+  // as direct children of a dl. The hint is a second dd for this reason: a <p>
+  // between the terms is a violation, and it was one.
+  it("puts only permitted elements directly inside the dl", () => {
+    const { container } = render(
+      <MetricStrip>
+        <Metric label="Spend" value="$12.00" hint="This month" />
+        <Metric label="Runs" value="41" />
+      </MetricStrip>,
+    );
+    const dl = container.querySelector("dl") as HTMLElement;
+    const permitted = new Set(["DT", "DD", "SCRIPT", "TEMPLATE", "DIV"]);
+    for (const child of Array.from(dl.children)) {
+      expect(permitted).toContain(child.tagName);
+    }
+  });
+
+  it("renders the hint as a dd rather than a paragraph", () => {
+    render(
+      <MetricStrip>
+        <Metric label="Spend" value="$12.00" hint="Personal wallet" />
+      </MetricStrip>,
+    );
+    const hint = screen.getByText("Personal wallet");
+    expect(hint.tagName).toBe("DD");
+  });
+
+  it("omits the hint entirely when not given", () => {
+    const { container } = render(
+      <MetricStrip>
+        <Metric label="Runs" value="41" />
+      </MetricStrip>,
+    );
+    expect(container.querySelectorAll("dd")).toHaveLength(1);
+  });
+
+  // `attention` means a person has to do something, so it shows a pill next to
+  // the label. A zero on its own is not attention.
+  it("shows a pill beside the label only when attention is set", () => {
+    const { rerender, container } = render(
+      <MetricStrip>
+        <Metric label="Balance" value="$0.00" />
+      </MetricStrip>,
+    );
+    expect(container.querySelector("svg")).toBeNull();
+
+    rerender(
+      <MetricStrip>
+        <Metric
+          attention={{ tone: "danger", label: "Empty" }}
+          label="Balance"
+          value="$0.00"
+        />
+      </MetricStrip>,
+    );
+    expect(screen.getByText("Empty")).toBeInTheDocument();
+    expect(container.querySelector("svg")).not.toBeNull();
+  });
+
+  it("raises the value's tone only for a danger attention", () => {
+    const { container } = render(
+      <MetricStrip>
+        <Metric
+          attention={{ tone: "danger", label: "Empty" }}
+          label="Balance"
+          value="$0.00"
+        />
+      </MetricStrip>,
+    );
+    const value = screen.getByText("$0.00");
+    expect(value.className).toContain("--surface-danger-text");
+    expect(container.querySelectorAll("dd")).toHaveLength(1);
+  });
+
+  // The divider is drawn only where it belongs, never drawn and then
+  // suppressed: `border-l` alongside `border-l-0` variants puts both in one
+  // conflict group whose winner is decided by emitted-rule order, and that
+  // resolved the wrong way at every breakpoint — every item kept a left border,
+  // including the first in each row.
+  it("draws the divider without a suppressing counterpart", () => {
+    const { container } = render(
+      <MetricStrip>
+        <Metric label="Balance" value="$0.00" />
+      </MetricStrip>,
+    );
+    const item = (container.querySelector("dl") as HTMLElement)
+      .children[0] as HTMLElement;
+    expect(item.className).not.toContain("border-l-0");
+  });
+
+  // The row-start test has to name the same column count the grid does, at each
+  // breakpoint. Nothing in the type system ties them together, so changing the
+  // grid to three columns without moving the divider puts a rule mid-row. Read
+  // both out of the rendered classes and require them to agree, so the coupling
+  // is enforced rather than only described.
+  it("keeps the divider's row-start test matching the grid's column count", () => {
+    const { container } = render(
+      <MetricStrip>
+        <Metric label="Balance" value="$0.00" />
+      </MetricStrip>,
+    );
+    const dl = container.querySelector("dl") as HTMLElement;
+    const item = dl.children[0] as HTMLElement;
+
+    // `grid-cols-N` unprefixed is the base breakpoint; `<bp>:grid-cols-N` is that
+    // breakpoint. The divider spells the same breakpoints as `max-<bp>:` / `<bp>:`.
+    const columnsAt = (prefix: string) => {
+      const re = prefix
+        ? new RegExp(`(?:^| )${prefix}:grid-cols-(\\d+)(?: |$)`)
+        : /(?:^| )grid-cols-(\d+)(?: |$)/;
+      const m = dl.className.match(re);
+      return m ? Number(m[1]) : null;
+    };
+    const modulusAt = (prefix: string) => {
+      const m = item.className.match(
+        new RegExp(`(?:^| )${prefix}:\\[&:not\\(:nth-child\\((\\d+)n\\+1\\)\\)\\]:border-l(?: |$)`),
+      );
+      return m ? Number(m[1]) : null;
+    };
+
+    // base grid (below sm) is guarded by the `max-sm:` divider rule
+    expect(modulusAt("max-sm")).toBe(columnsAt(""));
+    // the `sm:` grid is guarded by the `sm:` divider rule
+    expect(modulusAt("sm")).toBe(columnsAt("sm"));
+
+    // Every grid-cols breakpoint the strip declares must have a divider rule.
+    const declared = [...dl.className.matchAll(/(?:^| )(?:([a-z]+):)?grid-cols-\d+(?= |$)/g)]
+      .map((m) => m[1] ?? "");
+    for (const bp of declared) {
+      const guard = bp === "" ? "max-sm" : bp;
+      expect(
+        modulusAt(guard),
+        `grid-cols at "${bp || "base"}" has no matching ${guard}: divider rule`,
+      ).not.toBeNull();
+    }
+  });
+
+  it("titles the hint too, so a truncated qualifier stays recoverable", () => {
+    render(
+      <MetricStrip>
+        <Metric
+          hint="Personal wallet (0x1234abcd5678efgh)"
+          label="Balance"
+          value="$248.55"
+        />
+      </MetricStrip>,
+    );
+    expect(screen.getByText("Personal wallet (0x1234abcd5678efgh)")).toHaveAttribute(
+      "title",
+      "Personal wallet (0x1234abcd5678efgh)",
+    );
+  });
+
+  it("titles a string value so a truncated figure stays readable", () => {
+    render(
+      <MetricStrip>
+        <Metric label="Balance" value="$1,284,003.10" />
+      </MetricStrip>,
+    );
+    expect(screen.getByText("$1,284,003.10")).toHaveAttribute(
+      "title",
+      "$1,284,003.10",
+    );
+  });
+});

package/src/primitives/metric-strip.tsx

@@ -0,0 +1,122 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+import { StatusPill, type StatusTone } from "./status-pill";
+
+/**
+ * The headline figures for a console page, as ONE statement rather than four.
+ *
+ * A row of separate stat cards is the default and it is usually wrong here.
+ * Each card is a box that must be tall enough for its longest member, so a row
+ * mixing "$248.55 / Personal wallet" against a bare "0" leaves the short ones
+ * mostly empty; and four bordered boxes read as four unrelated facts when they
+ * are four readings of one account. `MetricStrip` puts them on one plane
+ * divided by hairlines: same information, one object, no holes.
+ *
+ * The divider is a border on the item rather than a `divide-*` utility on the
+ * parent, because these wrap. `divide-x` draws from DOM order and leaves a
+ * stray rule at the start of every wrapped line; a per-item leading border
+ * suppressed at each row start does not.
+ */
+export interface MetricStripProps
+  extends React.HTMLAttributes<HTMLDListElement> {
+  children: React.ReactNode;
+}
+
+const MetricStrip = React.forwardRef<HTMLDListElement, MetricStripProps>(
+  ({ className, children, ...props }, ref) => (
+    <dl
+      ref={ref}
+      className={cn(
+        "grid grid-cols-2 rounded-[var(--radius-lg)] border border-border bg-card shadow-[var(--shadow-card)] sm:grid-cols-4",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </dl>
+  ),
+);
+MetricStrip.displayName = "MetricStrip";
+
+export interface MetricProps extends React.HTMLAttributes<HTMLDivElement> {
+  label: React.ReactNode;
+  value: React.ReactNode;
+  /** The qualifying line: which wallet, which window, what the limit is. */
+  hint?: React.ReactNode;
+  /** Raises the value's tone and shows a pill beside the label. A metric is
+   *  `attention` only when a person has to DO something — not merely when a
+   *  number is zero. */
+  attention?: { tone: StatusTone; label: string };
+}
+
+/**
+ * One reading inside a `MetricStrip`.
+ *
+ * `<dt>` carries the label and `<dd>` the value, so the pair is announced as a
+ * described term rather than as two loose strings — the semantic that makes a
+ * figure legible without the visual grouping.
+ *
+ * The value is `tabular-nums`: these sit in a row and change on a timer, and
+ * proportional digits make the column jitter every time a 1 becomes an 8.
+ */
+const Metric = React.forwardRef<HTMLDivElement, MetricProps>(
+  ({ className, label, value, hint, attention, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        // Leading hairline, DRAWN only where a divider belongs — never drawn
+        // and then suppressed. Stating it as `border-l` plus `border-l-0`
+        // variants puts both in one conflict group, where the winner is decided
+        // by emitted-rule order rather than by intent; that resolved the wrong
+        // way at every breakpoint and left a rule down the start of each row.
+        // `:not(:nth-child(Nn+1))` is the row-start test for the column count
+        // at that breakpoint, so no rule ever contradicts another.
+        //
+        // N is COUPLED to the grid template on `MetricStrip`: 2 columns below
+        // `sm`, 4 from `sm`. A new breakpoint there — `md:grid-cols-3`, say —
+        // needs its `md:[&:not(:nth-child(3n+1))]:border-l` here in the same
+        // change, or the dividers land mid-row at that width.
+        "border-border p-4 sm:p-5",
+        "max-sm:[&:not(:nth-child(2n+1))]:border-l",
+        "sm:[&:not(:nth-child(4n+1))]:border-l",
+        className,
+      )}
+      {...props}
+    >
+      <dt className="flex items-center gap-2 text-muted-foreground text-sm">
+        <span className="truncate">{label}</span>
+        {attention && (
+          <StatusPill tone={attention.tone}>{attention.label}</StatusPill>
+        )}
+      </dt>
+      {/* `truncate`, and a step down until the column is wide enough for the
+          longest figure this strip carries. A balance renders as "$248.55" on a
+          funded account and as "$1,284,003.10" on a busy one, and at four
+          columns the wide case has nowhere to go — it either overflows its cell
+          or pushes the whole strip past the page. */}
+      <dd
+        className={cn(
+          "mt-1 truncate font-semibold text-xl tabular-nums tracking-tight lg:text-2xl",
+          attention?.tone === "danger" && "text-[var(--surface-danger-text)]",
+        )}
+        title={typeof value === "string" ? value : undefined}
+      >
+        {value}
+      </dd>
+      {hint && (
+        // Titled for the same reason the value is: the line truncates, and a
+        // hint is where the qualifying detail lives — which wallet, which
+        // window — so a clipped one is the case most worth recovering.
+        <dd
+          className="mt-0.5 truncate text-[var(--text-dim)] text-xs"
+          title={typeof hint === "string" ? hint : undefined}
+        >
+          {hint}
+        </dd>
+      )}
+    </div>
+  ),
+);
+Metric.displayName = "Metric";
+
+export { Metric, MetricStrip };

package/src/primitives/page-header.test.tsx

@@ -0,0 +1,57 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { PageHeader } from "./page-header";
+
+describe("PageHeader", () => {
+  it("renders the title as the page's only h1", () => {
+    render(<PageHeader title="Workflows" />);
+    const headings = screen.getAllByRole("heading", { level: 1 });
+    expect(headings).toHaveLength(1);
+    expect(headings[0]).toHaveTextContent("Workflows");
+  });
+
+  it("steps the title down to h2 for a nested surface", () => {
+    render(<PageHeader level={2} title="Skills" />);
+    expect(screen.queryByRole("heading", { level: 1 })).toBeNull();
+    expect(screen.getByRole("heading", { level: 2 })).toHaveTextContent(
+      "Skills",
+    );
+  });
+
+  it("puts the id on the heading so a region can point aria-labelledby at it", () => {
+    render(<PageHeader titleId="keys-title" title="API keys" />);
+    expect(screen.getByRole("heading", { level: 1 })).toHaveAttribute(
+      "id",
+      "keys-title",
+    );
+  });
+
+  // The description is prose ABOUT the page, so it must not land in the
+  // heading — a paragraph rendered where a heading goes reads as body copy to a
+  // sighted reader and as the page's accessible name to a screen reader.
+  it("keeps the description out of the heading", () => {
+    render(<PageHeader title="Billing" description="Spend and invoices." />);
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading).toHaveTextContent("Billing");
+    expect(heading).not.toHaveTextContent("Spend and invoices.");
+    expect(screen.getByText("Spend and invoices.")).toBeInTheDocument();
+  });
+
+  it("renders the actions and meta slots when given", () => {
+    render(
+      <PageHeader
+        title="Teams"
+        actions={<button type="button">Invite</button>}
+        meta={<span>4 members</span>}
+      />,
+    );
+    expect(screen.getByRole("button", { name: "Invite" })).toBeInTheDocument();
+    expect(screen.getByText("4 members")).toBeInTheDocument();
+  });
+
+  it("omits the optional slots entirely when not given", () => {
+    const { container } = render(<PageHeader title="Alerts" />);
+    expect(container.querySelector("p")).toBeNull();
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+});

package/src/primitives/page-header.tsx

@@ -0,0 +1,86 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * The one masthead every console page opens with.
+ *
+ * A page identifies itself in three separate registers, and each gets its own
+ * slot here so they cannot compete for the same one:
+ *
+ *   - `title` — what the page IS. The `<h1>`, and the only `<h1>`.
+ *   - `description` — one line on what it is for. Prose belongs here, never in
+ *     the title slot: a paragraph rendered where a heading goes reads as body
+ *     copy to a sighted reader and as nothing at all to a screen reader, which
+ *     is how a page ends up with no accessible name.
+ *   - `actions` — what the reader can DO from here, right-aligned and wrapping
+ *     under the title on a narrow viewport rather than squeezing it.
+ *
+ * `meta` is the fourth register and the one most often missing: the small facts
+ * that qualify everything below (a count, a scope, a window). They sit on their
+ * own line under the title so a reader can tell the difference between "this
+ * page has nothing in it" and "this filter matches nothing".
+ *
+ * `titleId` is exposed so a page can point `aria-labelledby` at the heading
+ * from a region further down without minting a second copy of the string.
+ */
+export interface PageHeaderProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  actions?: React.ReactNode;
+  meta?: React.ReactNode;
+  titleId?: string;
+  /** Renders the title one step down for a nested/tab surface. */
+  level?: 1 | 2;
+}
+
+const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(
+  (
+    {
+      className,
+      title,
+      description,
+      actions,
+      meta,
+      titleId,
+      level = 1,
+      ...props
+    },
+    ref,
+  ) => {
+    const Heading = level === 1 ? "h1" : "h2";
+    return (
+      <header ref={ref} className={cn("mb-6", className)} {...props}>
+        <div className="flex flex-wrap items-start justify-between gap-x-6 gap-y-3">
+          <div className="min-w-0">
+            <Heading
+              id={titleId}
+              className={cn(
+                "text-balance font-semibold tracking-tight",
+                level === 1 ? "text-2xl" : "text-lg",
+              )}
+            >
+              {title}
+            </Heading>
+            {description && (
+              <p className="mt-1 max-w-prose text-muted-foreground text-sm">
+                {description}
+              </p>
+            )}
+          </div>
+          {actions && (
+            <div className="flex flex-wrap items-center gap-2">{actions}</div>
+          )}
+        </div>
+        {meta && (
+          <div className="mt-3 flex flex-wrap items-center gap-x-4 gap-y-2 text-[var(--text-dim)] text-xs">
+            {meta}
+          </div>
+        )}
+      </header>
+    );
+  },
+);
+PageHeader.displayName = "PageHeader";
+
+export { PageHeader };

package/src/primitives/status-pill.test.tsx

@@ -0,0 +1,104 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { StatusPill, type StatusTone } from "./status-pill";
+
+const TONES: StatusTone[] = [
+  "success",
+  "warning",
+  "danger",
+  "info",
+  "running",
+  "neutral",
+];
+
+describe("StatusPill", () => {
+  it("states the status as text, not colour alone", () => {
+    render(<StatusPill tone="danger">Failed</StatusPill>);
+    expect(screen.getByText("Failed")).toBeInTheDocument();
+  });
+
+  // The glyph is the channel that survives greyscale and colour blindness, so
+  // every tone must carry one and it must be hidden from the accessibility tree
+  // — the label beside it already says the same thing.
+  it.each(TONES)("gives %s a decorative glyph", (tone) => {
+    const { container } = render(<StatusPill tone={tone}>Status</StatusPill>);
+    const glyph = container.querySelector("svg");
+    expect(glyph).not.toBeNull();
+    expect(glyph).toHaveAttribute("aria-hidden", "true");
+  });
+
+  it.each(TONES)("brings %s's own paired background", (tone) => {
+    const { container } = render(<StatusPill tone={tone}>Status</StatusPill>);
+    const pill = container.firstElementChild as HTMLElement;
+    expect(pill.className).toContain(`bg-[var(--surface-`);
+    expect(pill.className).toContain("border");
+  });
+
+  // A tone colour is solved against its own background. `bare` drops that
+  // background, so the tone may ride on the glyph only — lifting it onto the
+  // label would put it on whatever plane the caller happens to be on.
+  it.each(TONES)("keeps %s's tone off the label in bare mode", (tone) => {
+    const { container } = render(
+      <StatusPill bare tone={tone}>
+        Status
+      </StatusPill>,
+    );
+    const pill = container.firstElementChild as HTMLElement;
+    expect(pill.className).toContain("bg-transparent");
+    expect(pill.className).not.toContain("bg-[var(--surface-");
+
+    const glyphWrapper = container.querySelector("svg")
+      ?.parentElement as HTMLElement;
+    expect(glyphWrapper.className).toContain("text-[var(--surface-");
+  });
+
+  // Guards the reason TONE_TEXT is declared rather than recovered by searching
+  // TONE_SURFACE for a `text-` class: a miss there yields undefined and removes
+  // the tone from the only channel bare mode has left.
+  it.each(TONES)("resolves a real text class for %s in bare mode", (tone) => {
+    const { container } = render(
+      <StatusPill bare tone={tone}>
+        Status
+      </StatusPill>,
+    );
+    const glyphWrapper = container.querySelector("svg")
+      ?.parentElement as HTMLElement;
+    expect(glyphWrapper.className).not.toContain("undefined");
+    expect(glyphWrapper.className).toMatch(/text-\[var\(--surface-[a-z]+-text\)\]/);
+  });
+
+  // `px-2` from the size and `px-0` from bare are the same utility group, so
+  // which one lands is decided by the class merge rather than by reading order.
+  // Asserting the resolved class list keeps that a guarantee: a bare pill has to
+  // sit flush against the text beside it, and silently keeping the size padding
+  // would space it like a chip that lost only its background.
+  it.each(["sm", "md"] as const)("drops the %s size padding in bare mode", (size) => {
+    const { container } = render(
+      <StatusPill bare size={size} tone="info">
+        Queued
+      </StatusPill>,
+    );
+    const cls = (container.firstElementChild as HTMLElement).className;
+    expect(cls).toContain("px-0");
+    expect(cls).not.toMatch(/(^| )px-2(\.5)?( |$)/);
+  });
+
+  it("gives no two tones the same silhouette", () => {
+    const shapes = TONES.map((tone) => {
+      const { container } = render(<StatusPill tone={tone}>S</StatusPill>);
+      return container.querySelector("svg")?.innerHTML ?? "";
+    });
+    expect(new Set(shapes).size).toBe(shapes.length);
+  });
+
+  it("takes a larger size", () => {
+    const { container } = render(
+      <StatusPill size="md" tone="info">
+        Queued
+      </StatusPill>,
+    );
+    expect((container.firstElementChild as HTMLElement).className).toContain(
+      "text-sm",
+    );
+  });
+});