strata-react 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jonathan Burnhams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# strata-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An opinionated React + Tailwind v4 framework for building product frontends: components,
+UX patterns and styles, with the testing and review tooling that keeps them honest. Built
+from the research in [jburnhams/ux-research](https://github.com/jburnhams/ux-research)
+(`ui-library/`), which explains every decision.
+
+It is opinionated about **structure, behaviour, states, accessibility and the stack**, and
+deliberately silent about **the look**: there is no default theme. Each product generates its
+own palette from its subject, and Tailwind's stock colours, sizes, radii and shadows are
+removed so they cannot be typed by accident.
+
+Rules for working in this repo, for people and coding agents: [`CLAUDE.md`](./CLAUDE.md).
+
+## The stack
+
+Node 26 · React 19 · TypeScript · Vite 8 · Tailwind v4 · class-variance-authority · lucide-react ·
+TanStack Query, Table and Virtual · React Router · Vitest + Testing Library + MSW ·
+Storybook 10 · Playwright Chromium + pixelmatch visual regression · GitHub Actions.
+
+## Install
+
+Not on npm yet. Install from GitHub (the `prepare` script builds it):
+
+```bash
+npm install github:jburnhams/strata-react react react-dom react-router @tanstack/react-query tailwindcss @tailwindcss/vite
+```
+
+## Set up an app
+
+```css
+/* src/app.css */
+@import "tailwindcss";
+@import "strata-react/strata.css";   /* token contract, namespace reset, type steps, base layer */
+@import "./theme.generated.css";     /* your palette: ux-research ux-design/skill/scripts/palette.mjs */
+@import "./theme.css";               /* your status roles, faces and subject colours, with reasons */
+```
+
+`theme.css` supplies what Strata names but does not choose: `--success`, `--success-subtle`,
+`--warning…`, `--danger…`, `--info…` (pale tint + dark ink of one hue, ink at least 6:1),
+`--font-sans` / `--font-display` in an `@theme` block, and optionally `--title-weight`,
+`--title-stretch`, `--title-tracking`. See `.storybook/theme.css` for a complete example (the
+kiln-room fixture).
+
+```tsx
+import { createBrowserRouter, RouterProvider } from "react-router";
+import { StrataQueryProvider } from "strata-react";
+import "./app.css";
+
+const router = createBrowserRouter([{ path: "/", element: <KilnRoom /> }]);
+
+createRoot(document.getElementById("root")!).render(
+  <StrataQueryProvider>
+    <RouterProvider router={router} />
+  </StrataQueryProvider>,
+);
+```
+
+```tsx
+// One question: "Is my work out of the kiln yet?"
+function KilnRoom() {
+  const load = useLoad({ queryKey: ["bookings"], queryFn: () => fetchJson<Booking[]>("/api/bookings") });
+  return (
+    <AppShell product="Back Lane Clay" nav={nav}>
+      <PageHeader title="Kiln room" finding={{ text: "Kiln 2 is safe to open at about 14:50." }} />
+      <DataView
+        state={load}
+        isEmpty={(rows) => rows.length === 0}
+        skeleton={<TableSkeleton />}
+        empty={<EmptyState title="All three kilns are cold" />}
+      >
+        {(rows) => <DataTable caption="Work in the kilns" columns={columns} rows={rows} rowKey={(b) => b.id} sortParam="sort" />}
+      </DataView>
+    </AppShell>
+  );
+}
+```
+
+## Components
+
+| Group | Exports | Notes |
+|---|---|---|
+| Actions | `Button`, `IconButton`, `AsyncButton`, `useAsyncAction` | Default is `outline`; one filled button per view; `IconButton` requires `label`; `AsyncButton` keeps one width through idle, pending, done and error |
+| Form | `Field`, `Input`, `Textarea`, `NativeSelect`, `ChoiceGroup` | `Field` wires label, hint, error, `aria-describedby`, `aria-invalid` |
+| Status and figures | `Status`, `Metric`, `MetricStrip` | A status is always a word; figures have no icons or sparklines |
+| Data | `DataView`, `Load<T>`, `EmptyState`, `Skeleton`, `DataTable`, `TableSkeleton`, `VirtualList`, `LineChart` | `DataView` requires skeleton and empty; tables and lists virtualise from 100 rows; charts label values directly |
+| Data loading | `StrataQueryProvider`, `createQueryClient`, `useLoad`, `toLoad`, `fetchJson`, `HttpError` | TanStack Query in, `Load<T>` out |
+| Page and navigation | `AppShell`, `SideNav`, `Breadcrumb`, `Tabs`, `PageHeader` | React Router; tab and sort state in the URL |
+| Feedback | `UndoBar`, `useUndoable`, `Done` | Undo before confirm; `Done` is the one celebration, and it must say what happens next |
+| Helpers | `cn`, `format`, `createFormat` | `cn` knows `type-*`; all numbers and dates through `Intl` |
+| Testing | `strata-react/testing`: `renderWithStrata`, `createTestQueryClient` | Router + query client around Testing Library's `render` |
+
+Specs for the components not built yet (dialogs, sheets, menus, toasts, command menu, prose)
+are in ux-research `ui-library/components.md`.
+
+## Develop
+
+```bash
+npm install
+npm run storybook           # http://localhost:6006
+npm test                    # typecheck + unit tests
+npm run test:integration    # build, then check the package and its CSS as an app sees them
+npm run test:visual         # screenshot every story (light, dark) and compare with baselines
+npm run test:visual:update  # accept the current screenshots as baselines
+npm run site                # build the docs site into site/
+```
+
+## Docs site
+
+GitHub Pages serves one site, built by `.github/workflows/pages.yml` on every push to main:
+Storybook at the root, the TypeDoc API reference at `/api/`, and a gallery of every visual
+baseline (light and dark, linked to its story) at `/visuals/`. One-time setup: Settings → Pages →
+Source: GitHub Actions.
+
+## Licence
+
+MIT

package/dist/components/app-shell.d.ts

@@ -0,0 +1,32 @@
+import { IconComponent } from '../lib/icon';
+import * as React from "react";
+export type NavItem = {
+    to: string;
+    label: string;
+    icon?: IconComponent;
+    /** Match only this exact path, for an index route such as "/". */
+    end?: boolean;
+};
+/** The app frame: product name, side nav on the page ground (a scrollable row on phones), optional top bar, and the main region. */
+export declare function AppShell({ product, nav, navLabel, topBar, children, className, }: {
+    /** The product's name or mark, linking home. */
+    product: React.ReactNode;
+    nav: NavItem[];
+    navLabel?: string;
+    topBar?: React.ReactNode;
+    children: React.ReactNode;
+    className?: string;
+}): React.JSX.Element;
+/** Navigation links (React Router `NavLink`); the current route is a neutral pill with `aria-current`. */
+export declare function SideNav({ items, label, className }: {
+    items: NavItem[];
+    label: string;
+    className?: string;
+}): React.JSX.Element;
+/** Plain links separated by `/`; the last crumb is the current page. */
+export declare function Breadcrumb({ items }: {
+    items: {
+        label: string;
+        to?: string;
+    }[];
+}): React.JSX.Element;

package/dist/components/async-button.d.ts

@@ -0,0 +1,18 @@
+import { ButtonProps } from './button';
+import * as React from "react";
+export type Phase = "idle" | "pending" | "done" | "error";
+export type AsyncLabels = {
+    idle: string;
+    /** Ends in an ellipsis: "Saving…", "Booking…". */
+    pending: string;
+    /** The same verb, finished: "Saved", "Booked". */
+    done: string;
+    error?: string;
+};
+/** One button through idle, pending, done and error, with the label changing in place and its width fixed by the longest label. The outcome is announced politely. */
+export declare function AsyncButton({ phase, labels, disabled, ...props }: Omit<ButtonProps, "children"> & {
+    phase: Phase;
+    labels: AsyncLabels;
+}): React.JSX.Element;
+/** Runs an async action and reports its phase. `done` returns to `idle` after `settleMs`. */
+export declare function useAsyncAction<A extends unknown[]>(action: (...args: A) => Promise<void>, settleMs?: number): readonly [Phase, (...args: A) => Promise<void>];

package/dist/components/button.d.ts

@@ -0,0 +1,18 @@
+import { VariantProps } from 'class-variance-authority';
+import { IconComponent } from '../lib/icon';
+import * as React from "react";
+export declare const buttonVariants: (props?: ({
+    variant?: "link" | "default" | "outline" | "secondary" | "ghost" | "destructive" | null | undefined;
+    size?: "default" | "sm" | "icon" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export type ButtonProps = React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+};
+/** A button with shadcn's variant names. The default variant is `outline`; ask for the filled accent (`variant="default"`) once per view. `type` defaults to `button`. */
+export declare function Button({ className, variant, size, asChild, type, ...props }: ButtonProps): React.JSX.Element;
+export type IconButtonProps = Omit<ButtonProps, "size" | "children" | "aria-label"> & {
+    icon: IconComponent;
+    label: string;
+};
+/** An icon-only button. `label` is required and becomes the accessible name and tooltip. */
+export declare function IconButton({ icon: Icon, label, variant, ...props }: IconButtonProps): React.JSX.Element;

package/dist/components/data-table.d.ts

@@ -0,0 +1,42 @@
+import * as React from "react";
+export type Column<T> = {
+    key: string;
+    header: string;
+    cell: (row: T) => React.ReactNode;
+    /** Right-aligns and sets tabular figures. Use for every quantity. */
+    numeric?: boolean;
+    sort?: (a: T, b: T) => number;
+    /** Cells that may hold long text get truncated rather than stretching the table. */
+    truncate?: boolean;
+    className?: string;
+};
+export type Sort = {
+    key: string;
+    dir: "ascending" | "descending";
+};
+export type DataTableProps<T> = {
+    /** Names the table for screen readers and labels the scroll region. */
+    caption: string;
+    columns: Column<T>[];
+    rows: T[];
+    rowKey: (row: T) => string;
+    initialSort?: Sort;
+    /** Keep the sort in this URL search parameter. Needs a React Router context. */
+    sortParam?: string;
+    /** Row count from which only the visible rows render. Default 100. */
+    virtualizeFrom?: number;
+    /** Height of the scroll region once virtualised, in px. Default 480. */
+    maxHeight?: number;
+    className?: string;
+};
+/** Reads a sort from its URL form (`pieces.desc`). */
+export declare function parseSort(value: string | null): Sort | undefined;
+/** Writes a sort in its URL form (`pieces.desc`). */
+export declare function serialiseSort(sort: Sort): string;
+/** A table on TanStack Table: muted headers, row rules, right-aligned tabular numbers, sortable headers with `aria-sort`, virtualised from `virtualizeFrom` rows, sort optionally kept in the URL (`sortParam`). */
+export declare function DataTable<T>(props: DataTableProps<T>): React.JSX.Element;
+/** The loading placeholder for a `DataTable`, shaped like its rows. */
+export declare function TableSkeleton({ rows, columns }: {
+    rows?: number;
+    columns?: number;
+}): React.JSX.Element;

package/dist/components/data-view.d.ts

@@ -0,0 +1,33 @@
+import * as React from "react";
+export type Load<T> = {
+    status: "loading";
+} | {
+    status: "error";
+    message: string;
+    retry: () => void;
+} | {
+    status: "ready";
+    data: T;
+};
+/** Every view of remote data: renders `skeleton` while loading, an alert with Try again on error, `empty` when `isEmpty`, else `children(data)`. The skeleton and empty state are required. */
+export declare function DataView<T>({ state, isEmpty, skeleton, empty, children, className, }: {
+    state: Load<T>;
+    /** When the loaded data counts as empty. For arrays, `(rows) => rows.length === 0`. */
+    isEmpty: (data: T) => boolean;
+    /** Mirrors the final layout, so nothing jumps when data arrives. Not a centred spinner. */
+    skeleton: React.ReactNode;
+    /** What goes here and how to add it. An `EmptyState`, not an illustration. */
+    empty: React.ReactNode;
+    children: (data: T) => React.ReactNode;
+    className?: string;
+}): React.JSX.Element;
+/** An empty state that teaches the next action: a title, a sentence and an action. No illustration slot, on purpose. */
+export declare function EmptyState({ title, children, action }: {
+    title: string;
+    children?: React.ReactNode;
+    action?: React.ReactNode;
+}): React.JSX.Element;
+/** A placeholder block for a loading layout. Size it with layout classes so it mirrors the final content. */
+export declare function Skeleton({ className }: {
+    className?: string;
+}): React.JSX.Element;

package/dist/components/done.d.ts

@@ -0,0 +1,14 @@
+import * as React from "react";
+/** The completion moment for a rare, earned finish: what happened (past tense, with its object), what happens next, and optionally a figure drawn from the person's own data. Focus moves to the heading. */
+export declare function Done({ title, next, figure, actions, focusOnMount, className, }: {
+    /** What happened, past tense, with its object. */
+    title: string;
+    /** What the person does now, or what happens next and when. */
+    next: React.ReactNode;
+    /** A drawing of the result made from the person's data in the subject's own terms. */
+    figure?: React.ReactNode;
+    actions?: React.ReactNode;
+    /** Off only where the result is not the page's subject (the state-matrix page). */
+    focusOnMount?: boolean;
+    className?: string;
+}): React.JSX.Element;

package/dist/components/field.d.ts

@@ -0,0 +1,34 @@
+import * as React from "react";
+export type FieldProps = {
+    label: string;
+    /** The control's id, when the page needs a known one (an anchor, a test). Generated otherwise. */
+    id?: string;
+    /** What the person needs to know before typing, such as limits or units. */
+    hint?: React.ReactNode;
+    /** What went wrong and how to fix it, in one sentence. Shown under the control, never in a toast. */
+    error?: string;
+    children: React.ReactNode;
+    className?: string;
+};
+/** A labelled form field: wires the label, hint, error, `aria-describedby` and `aria-invalid` into the one control it wraps. */
+export declare function Field({ label, id: idProp, hint, error, children, className }: FieldProps): React.JSX.Element;
+/** A text input that picks up its id and descriptions from the surrounding `Field`. */
+export declare function Input({ className, id, ...props }: React.ComponentProps<"input">): React.JSX.Element;
+/** A multi-line input that picks up its id and descriptions from the surrounding `Field`. */
+export declare function Textarea({ className, id, ...props }: React.ComponentProps<"textarea">): React.JSX.Element;
+/** The platform select, styled. The default for short lists, especially on touch screens. */
+export declare function NativeSelect({ className, id, ...props }: React.ComponentProps<"select">): React.JSX.Element;
+export type Choice = {
+    value: string;
+    label: string;
+    detail?: string;
+};
+/** Radio choices in a fieldset with a legend; each whole row is the hit target. For 2 to 5 options that each need a sentence. */
+export declare function ChoiceGroup({ legend, name, choices, value, onChange, error, }: {
+    legend: string;
+    name: string;
+    choices: Choice[];
+    value: string;
+    onChange: (value: string) => void;
+    error?: string;
+}): React.JSX.Element;

package/dist/components/line-chart.d.ts

@@ -0,0 +1,36 @@
+import * as React from "react";
+export type Point = {
+    x: number;
+    y: number;
+};
+export type LineChartProps = {
+    /** What the chart shows, as a sentence. Used as the accessible name and the table caption. */
+    label: string;
+    series: Point[];
+    seriesLabel: string;
+    planned?: Point[];
+    plannedLabel?: string;
+    band?: {
+        below: number;
+        label: string;
+    };
+    formatX: (x: number) => string;
+    formatY: (y: number) => string;
+    xTicks: number[];
+    /** CSS colour for the measured series. Defaults to the first chart token. */
+    colour?: string;
+    /** Colour the measured series by value: each stop applies from `at` upwards, blending to the
+     *  next. Only where the colour means something in the subject; record the reason in DESIGN.md. */
+    colourScale?: {
+        at: number;
+        colour: string;
+    }[];
+    /** Says what the colours mean, shown beside the legend swatch when `colourScale` is set. */
+    colourScaleLabel?: string;
+    height?: number;
+    className?: string;
+};
+/** Four gridline steps of a size people write on a scale (1, 2, 2.5, 4 or 5 × 10ⁿ), ending above the max. */
+export declare function niceMax(max: number): number;
+/** One measured series, drawn in real pixels, with the peak and current readings labelled on the chart and every reading in a screen-reader table. Optional plan, threshold band and `colourScale`. */
+export declare function LineChart({ label, series, seriesLabel, planned, plannedLabel, band, formatX, formatY, xTicks, colour, colourScale, colourScaleLabel, height, className, }: LineChartProps): React.JSX.Element;

package/dist/components/metric.d.ts

@@ -0,0 +1,17 @@
+import * as React from "react";
+/** Headline figures as one description list split by hairlines. Holds `Metric`s. */
+export declare function MetricStrip({ label, children, className }: {
+    label: string;
+    children: React.ReactNode;
+    className?: string;
+}): React.JSX.Element;
+export type MetricProps = {
+    label: string;
+    /** Already formatted. Ink colour, 28px, tabular figures: never the brand colour, never 48px. */
+    value: string;
+    unit?: string;
+    /** One sentence: the change in words with its window, or what the figure means right now. */
+    note?: React.ReactNode;
+};
+/** One figure: label over value, an optional muted unit and a note that states any change in words with its window. */
+export declare function Metric({ label, value, unit, note }: MetricProps): React.JSX.Element;

package/dist/components/page-header.d.ts

@@ -0,0 +1,14 @@
+import * as React from "react";
+/** The top of an Operate screen: a noun title, its scope, the main action, and the finding (the one fact in today's data that most needs attention). */
+export declare function PageHeader({ title, scope, actions, finding, as: Heading, }: {
+    title: string;
+    /** The title's element: h1 on a screen, h2 where the header is shown inside another page. */
+    as?: "h1" | "h2";
+    /** What the screen covers: a date, a range, a filter. */
+    scope?: React.ReactNode;
+    actions?: React.ReactNode;
+    finding?: {
+        text: React.ReactNode;
+        action?: React.ReactNode;
+    };
+}): React.JSX.Element;

package/dist/components/status.d.ts

@@ -0,0 +1,9 @@
+import { IconComponent } from '../lib/icon';
+export type Tone = "neutral" | "info" | "success" | "warning" | "danger";
+/** A status as a word on a pale tint of its tone, with an optional icon. Never colour alone. */
+export declare function Status({ tone, icon: Icon, children, className, }: {
+    tone: Tone;
+    icon?: IconComponent;
+    children: string;
+    className?: string;
+}): import('react').JSX.Element;

package/dist/components/tabs.d.ts

@@ -0,0 +1,16 @@
+import * as React from "react";
+export type TabItem = {
+    value: string;
+    label: string;
+};
+/** Tabs whose selection lives in a URL search parameter (React Router), with the ARIA tabs keyboard model. */
+export declare function Tabs({ param, items, label, children, className, }: {
+    /** The search parameter that holds the selected tab. */
+    param: string;
+    items: TabItem[];
+    /** Names the tab list for screen readers. */
+    label: string;
+    /** Renders the selected panel. */
+    children: (value: string) => React.ReactNode;
+    className?: string;
+}): React.JSX.Element;

package/dist/components/undo.d.ts

@@ -0,0 +1,20 @@
+import * as React from "react";
+/** A removal waiting out its undo window: what to say, and what to do when the window closes. */
+export type PendingRemoval = {
+    id: string;
+    message: string;
+    commit: () => void;
+};
+/** Schedules a reversible removal to commit after `windowMs` unless undone. A second removal, or unmounting, commits the pending one. */
+export declare function useUndoable(windowMs?: number): {
+    pending: PendingRemoval | null;
+    schedule: (next: PendingRemoval) => void;
+    undo: () => void;
+};
+/** The polite live region that shows a pending removal with an Undo button. */
+export declare function UndoBar({ pending, onUndo, inline, }: {
+    pending: PendingRemoval | null;
+    onUndo: () => void;
+    /** Render in the flow instead of fixed to the viewport; for the state-matrix page. */
+    inline?: boolean;
+}): React.JSX.Element;

package/dist/components/virtual-list.d.ts

@@ -0,0 +1,12 @@
+import * as React from "react";
+/** A list that renders only its visible rows (TanStack Virtual) from `virtualizeFrom` items, keeping list semantics for screen readers. */
+export declare function VirtualList<T>({ label, items, itemKey, children, estimateSize, height, virtualizeFrom, className, }: {
+    label: string;
+    items: T[];
+    itemKey: (item: T) => string;
+    children: (item: T, index: number) => React.ReactNode;
+    estimateSize?: number;
+    height?: number;
+    virtualizeFrom?: number;
+    className?: string;
+}): React.JSX.Element;

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * strata-react: an opinionated React + Tailwind v4 framework for building product frontends.
+ * Components ship structure, behaviour, states and accessibility; the look comes from the
+ * product's own theme. Every component has a Storybook story for each of its states.
+ *
+ * @module strata-react
+ */
+export { cn, typeSteps } from './lib/utils';
+export { createFormat, format, NBSP, type Format } from './lib/format';
+export type { IconComponent } from './lib/icon';
+export { Button, IconButton, buttonVariants, type ButtonProps, type IconButtonProps } from './components/button';
+export { AsyncButton, useAsyncAction, type Phase, type AsyncLabels } from './components/async-button';
+export { Field, Input, Textarea, NativeSelect, ChoiceGroup, type FieldProps, type Choice } from './components/field';
+export { Status, type Tone } from './components/status';
+export { Metric, MetricStrip, type MetricProps } from './components/metric';
+export { DataView, EmptyState, Skeleton, type Load } from './components/data-view';
+export { DataTable, TableSkeleton, parseSort, serialiseSort, type Column, type Sort, type DataTableProps } from './components/data-table';
+export { VirtualList } from './components/virtual-list';
+export { LineChart, type LineChartProps, type Point } from './components/line-chart';
+export { PageHeader } from './components/page-header';
+export { UndoBar, useUndoable, type PendingRemoval } from './components/undo';
+export { Done } from './components/done';
+export { AppShell, SideNav, Breadcrumb, type NavItem } from './components/app-shell';
+export { Tabs, type TabItem } from './components/tabs';
+export { StrataQueryProvider, createQueryClient, toLoad, useLoad, fetchJson, HttpError, describeHttpError, type DescribeError, } from './query';