@atelic-action/ui 0.10.0 → 0.11.0

package/README.md

@@ -41,7 +41,7 @@ The package sheets sit inside `@layer atelic-ui`, so any rule a site writes outs
 | Import | Exports |
 |---|---|
 | `@atelic-action/ui/chrome` | `SiteHeader`, `SiteMenu`, `Footer`, `CreditBar`, `StickyCTABar`, `BrandLockup`, `SkipLink`, and their prop types |
-| `@atelic-action/ui/components` | `NotFound` and the page components (`Checklist`, `DataTable`, `StatRow`, `Callout`, `Collapsible`, `StackedBar`, `ColumnChart`, `ThresholdScale`, `StarRating`), with their prop types (see [The Not Found Page](#the-not-found-page) and [Page Components](#page-components)) |
+| `@atelic-action/ui/components` | `NotFound` and the page components (`Checklist`, `DataTable`, `StatRow`, `Callout`, `Collapsible`, `StackedBar`, `ColumnChart`, `ThresholdScale`, `StarRating`, `Disclosure`), with their prop types (see [The Not Found Page](#the-not-found-page) and [Page Components](#page-components)) |
 | `@atelic-action/ui/email` | The email components, the theme provider, the plain text helpers, and their prop types (see [Email](#email)) |
 | `@atelic-action/ui/email/render` | `renderEmail` and `renderFailureEmail`, the only entry that imports `react-dom/server` |
 | `@atelic-action/ui/tokens` | `Palette`, `atelicPalette`, `Fonts`, `atelicFonts`, `toThemeCSS`, `themeTokenMap` |
@@ -256,8 +256,9 @@ The blocks a page composes, each styled in `styles/components.css` inside the `a
 |---|---|---|
 | `Checklist` | A short list of checks, each passed or failed | Two columns when there is room, one on a phone. `passLabel` and `failLabel` name the icons for a screen reader |
 | `DataTable` | A table whose first column names each row, sortable by any column marked `sortable` | A click on a heading sorts on a wide screen. On a phone each row stacks, every fact wearing its column's label, and a dropdown sorts. A cell is a node, or `{ display, sort }` when what it shows is not what it sorts by; a formatted number in a string (`"$12,047"`, `"0.24%"`) sorts as a number. It renders in `defaultSort` on the server |
-| `StatRow` | A row of large figures, each over what it counts and its `period` | `trend` draws an arrow before a figure that is itself a change. `deltas` list comparisons beneath: an arrow, how far, against what (`basis`), and the earlier figure (`was`), each in its own tone, since a spend falling and a cost falling read differently |
+| `StatRow` | A row of large figures, each over what it counts and its `period`. `variant="quiet"` is the glance row for a working page: a light figure in the text color over a small capitalized label, hairlines between; `unit` sets a figure's unit small beside it | `trend` draws an arrow before a figure that is itself a change. `deltas` list comparisons beneath: an arrow, how far, against what (`basis`), and the earlier figure (`was`), each in its own tone, since a spend falling and a cost falling read differently |
 | `Callout` | One finding: an icon in its tone beside the title, the explainer under it | `variant="box"` sets it apart on a tinted ground, for something missing or owed |
+| `Disclosure` | A section the page opens and closes: a header row that folds a body the caller controls | For an app. The caller holds `open`, so it can remember what was folded, and a closed body is not rendered. The label is the toggle; `meta` (a count, a flag) sits beside it, outside its name, and a tap on it still folds. `headingLevel` makes the label a real heading |
 | `Collapsible` | A labeled line the reader opens for the detail behind it | A native `details`, so it works before any script loads and find in page opens it. `summary` carries the point, so the detail needs no explaining once open. It prints open |
 | `StackedBar` | One bar split into the parts of a whole, with a key | A part of zero is keyed and not drawn |
 | `ColumnChart` | A bar a period, the periods in groups that carry a label and a total | Months in quarters is the case it was cut for: a quarter reads against the one before it and the same one a year earlier |
@@ -275,7 +276,7 @@ The blocks a page composes, each styled in `styles/components.css` inside the `a
 The page components also work in an app that has its own base styles (Tailwind, shadcn) and wears none of the site chrome. Three things make that so (0.10.0):
 
 1. **A second scope.** Every rule in `styles/components.css` answers to `.atelic-ui` as well as `.mkt`. `.atelic-ui` has no resets behind it, so an app puts the class on the region that holds a package component and nothing else in it restyles. Prefer a region to `body`: the components use plain class names (`.stat .num`, `.callout`, `.note`), and an app with markup of its own under those names would have a page wide scope reach it. `body` is right only for an app that has checked it has none, and it is the one way to cover a component rendered in a portal.
-2. **The app imports one sheet**, `@atelic-action/ui/styles/components.css`, and neither `base.css` nor `chrome.css`. An app's own unlayered CSS always wins over the package. With Tailwind, where the app can declare the layer order before Tailwind loads, `@layer theme, base, atelic-ui, components, utilities;` keeps utilities winning over the package too; where it cannot, the package's layer lands last and wins over utilities set on a package element, which only matters to a caller styling one with a utility class.
+2. **The app imports one sheet**, `@atelic-action/ui/styles/components.css`, and neither `base.css` nor `chrome.css`. An app's own unlayered CSS always wins over the package. With Tailwind the app **must declare the layer order before any stylesheet loads**, in a `<style>` in the `<head>` of its `index.html`: `@layer properties, theme, base, atelic-ui, components, utilities;`. A layer ranks by where it is first named, and a bundler is free to name the package's first, which ranks it below Tailwind's reset; the reset then strips the padding, margins, and borders off every component, while colors and type still look right, so it is easy to miss. Named there, the package ranks above the reset and below the app's utilities.
 3. **The app maps its tokens** onto the ones the components read, in its own stylesheet on the same scope:
 
 | Token | What it colors |
@@ -300,10 +301,14 @@ The page components also work in an app that has its own base styles (Tailwind,
 	--neutral-100: hsl(var(--muted));
 	--surface-alt: hsl(var(--muted));
 	--ui-primary: hsl(var(--brand));
+	--primary-bright: hsl(var(--brand));
+	--primary-tint: color-mix(in srgb, hsl(var(--brand)) 12%, transparent);
 	--ui-card: hsl(var(--card));
 }
 ```
 
+**Unit tests.** The package ships TSX source, and Vitest compiles it like any other module. A file under `node_modules` has no tsconfig of its own to name a JSX runtime, so a test that renders a package component fails with `React is not defined` until the test config says which to use: `esbuild: { jsx: "automatic" }` at the top level of `vitest.config.ts`. The app build needs nothing, since the React plugin sets it for Vite.
+
 `StarRating` needs none of this: its sheet is unscoped and reads no token. The chrome (`SiteHeader`, `Footer`, and the rest) and `NotFound` remain site shaped and are not meant for a signed in app.
 
 ## The Gallery

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/ui",
-	"version": "0.10.0",
+	"version": "0.11.0",
 	"description": "Shared UI for the Atelic templates: site chrome, base styles, and the component library they install",
 	"type": "module",
 	"license": "UNLICENSED",

package/src/components/Disclosure.tsx

@@ -0,0 +1,73 @@
+import { ChevronDown } from "lucide-react";
+import { type ReactNode, useId } from "react";
+
+export interface DisclosureProps {
+	/** What the section is, and the toggle's accessible name. */
+	label: ReactNode;
+	open: boolean;
+	onToggle: () => void;
+	/**
+	 * Sits beside the label and outside the toggle's name: a count, a flag, a
+	 * small chart. A tap on it still folds the section.
+	 */
+	meta?: ReactNode;
+	/** Makes the label a real heading at this level; leave it out for none. */
+	headingLevel?: 2 | 3 | 4 | 5 | 6;
+	/** The panel's id; minted when left out. */
+	panelId?: string;
+	className?: string;
+	children: ReactNode;
+}
+
+/**
+ * A section the page opens and closes: a header row that folds a body the
+ * caller controls. Where `Collapsible` is a native details element that keeps
+ * its own state and its detail in the page, this one is for an app. The
+ * caller holds `open`, so it can remember which sections were folded, and a
+ * closed body is not rendered, so a long list costs nothing until asked for.
+ *
+ * The label is the toggle, so its name reads "Produce, collapsed" and not
+ * "Produce 10 items"; `meta` is a sibling for that reason. The toggle's
+ * `::after` stretches over the whole header row, so a tap anywhere on it,
+ * meta and chevron included, folds the section.
+ */
+export function Disclosure({
+	label,
+	open,
+	onToggle,
+	meta,
+	headingLevel,
+	panelId,
+	className,
+	children,
+}: DisclosureProps) {
+	const minted = useId();
+	const id = panelId ?? minted;
+	const Root = headingLevel ? "section" : "div";
+	const Title = headingLevel ? (`h${headingLevel}` as const) : "div";
+
+	return (
+		<Root className={["disclosure", open && "is-open", className].filter(Boolean).join(" ")}>
+			<div className="disclosure-head">
+				<Title className="disclosure-title">
+					<button
+						type="button"
+						className="disclosure-toggle"
+						onClick={onToggle}
+						aria-expanded={open}
+						aria-controls={id}
+					>
+						{label}
+					</button>
+				</Title>
+				{meta != null && meta !== false && <span className="disclosure-meta">{meta}</span>}
+				<ChevronDown className="disclosure-chevron" size={16} aria-hidden="true" />
+			</div>
+			{open && (
+				<div className="disclosure-body" id={id}>
+					{children}
+				</div>
+			)}
+		</Root>
+	);
+}

package/src/components/StatRow.tsx

@@ -22,6 +22,8 @@ export interface StatDelta {
 export interface StatItem {
 	/** The big figure, e.g. "$199", "3,948", "23%"; may embed an inline glyph. */
 	value: ReactNode;
+	/** The figure's unit, set small after it on the same baseline, e.g. "mi". */
+	unit?: ReactNode;
 	/** An arrow before the figure, when the figure is itself a change. */
 	trend?: StatDirection;
 	/** What the figure counts. */
@@ -38,6 +40,13 @@ export interface StatItem {
 
 export interface StatRowProps {
 	stats: StatItem[];
+	/**
+	 * How loud the row is. `loud`, the default, is a report's headline figures:
+	 * heavy, large, in the accent. `quiet` is a glance row for a working page:
+	 * a light figure in the text color over a small capitalized label, the
+	 * stats divided by a hairline. A tone still colors a quiet figure.
+	 */
+	variant?: "loud" | "quiet";
 	className?: string;
 }
 
@@ -50,9 +59,13 @@ const spoken = { up: "Up", down: "Down", flat: "Unchanged" } as const;
  * closes the stat, with the period it covers. The row wraps to as many
  * columns as fit, and arrows are read aloud as up or down.
  */
-export function StatRow({ stats, className }: StatRowProps) {
+export function StatRow({ stats, variant = "loud", className }: StatRowProps) {
 	return (
-		<div className={["stat-row", className].filter(Boolean).join(" ")}>
+		<div
+			className={["stat-row", variant === "quiet" && "is-quiet", className]
+				.filter(Boolean)
+				.join(" ")}
+		>
 			{stats.map((stat, i) => {
 				const Trend = stat.trend ? arrow[stat.trend] : null;
 				return (
@@ -63,6 +76,7 @@ export function StatRow({ stats, className }: StatRowProps) {
 								<Trend className="stat-trend" role="img" aria-label={spoken[stat.trend]} />
 							)}
 							{stat.value}
+							{stat.unit != null && <span className="stat-unit">{stat.unit}</span>}
 						</div>
 						{stat.deltas?.map((delta) => {
 							const Icon = arrow[delta.direction];

package/src/components/index.ts

@@ -16,6 +16,7 @@ export {
 	type DataTableValueCell,
 	type SortDirection,
 } from "./DataTable";
+export { Disclosure, type DisclosureProps } from "./Disclosure";
 export { NotFound, type NotFoundProps } from "./NotFound";
 export { StackedBar, type StackedBarProps, type StackedBarSegment } from "./StackedBar";
 export { describeStarRating, StarRating, type StarRatingProps } from "./StarRating";

package/src/styles/components.css

@@ -148,6 +148,114 @@
 		margin-top: 4px;
 	}
 
+	:is(.mkt, .atelic-ui) .stat-unit {
+		margin-left: 0.2em;
+		font-size: 0.4em;
+		font-weight: 500;
+		letter-spacing: 0;
+		color: var(--neutral-500);
+	}
+
+	/* ---- StatRow, quiet: a glance row for a working page. A light figure in
+	   the text color over a small capitalized label, the stats divided by a
+	   hairline. `--stat-size` sets the figure. ---- */
+	:is(.mkt, .atelic-ui) .stat-row.is-quiet {
+		display: flex;
+		gap: 0;
+	}
+	:is(.mkt, .atelic-ui) .stat-row.is-quiet .stat {
+		flex: 1;
+		min-width: 64px;
+		padding-right: 16px;
+	}
+	:is(.mkt, .atelic-ui) .stat-row.is-quiet .stat + .stat {
+		padding-left: 16px;
+		border-left: 1px solid var(--neutral-200);
+	}
+	:is(.mkt, .atelic-ui) .stat-row.is-quiet .stat .num {
+		align-items: baseline;
+		gap: 4px;
+		font: 300 var(--stat-size, 28px) / 1 var(--font-sans);
+		/* After the shorthand, which would otherwise reset it. */
+		font-variant-numeric: tabular-nums;
+		letter-spacing: -0.02em;
+		color: var(--tone, var(--ink));
+	}
+	:is(.mkt, .atelic-ui) .stat-row.is-quiet .stat-unit {
+		margin-left: 0;
+		font: 500 12px / 1 var(--font-mono);
+	}
+	:is(.mkt, .atelic-ui) .stat-row.is-quiet .stat .lbl {
+		margin-top: 7px;
+		font: 500 10px / 1.2 var(--font-sans);
+		letter-spacing: 0.1em;
+		text-transform: uppercase;
+		color: var(--neutral-500);
+	}
+
+	/* ---- Disclosure: a section the page opens and closes. The toggle's
+	   ::after covers the whole header row, so the meta and the chevron fold
+	   it too while staying out of its name. ---- */
+	:is(.mkt, .atelic-ui) .disclosure {
+		border: 1px solid var(--neutral-200);
+		border-radius: 16px;
+		background: var(--ui-card, var(--card));
+		overflow: hidden;
+	}
+	:is(.mkt, .atelic-ui) .disclosure-head {
+		position: relative;
+		display: flex;
+		align-items: center;
+		gap: 10px;
+		padding: 14px 18px;
+	}
+	:is(.mkt, .atelic-ui) .disclosure-title {
+		display: flex;
+		min-width: 0;
+		margin: 0;
+		font: inherit;
+	}
+	:is(.mkt, .atelic-ui) .disclosure-toggle {
+		border: none;
+		background: transparent;
+		padding: 0;
+		text-align: left;
+		font: 500 17px / 1 var(--font-sans);
+		letter-spacing: -0.01em;
+		color: var(--ink);
+		cursor: pointer;
+	}
+	:is(.mkt, .atelic-ui) .disclosure-toggle::after {
+		content: "";
+		position: absolute;
+		inset: 0;
+	}
+	:is(.mkt, .atelic-ui) .disclosure-toggle:focus-visible {
+		outline: none;
+	}
+	:is(.mkt, .atelic-ui) .disclosure-toggle:focus-visible::after {
+		outline: 2px solid var(--disclosure-focus, var(--ink));
+		outline-offset: -2px;
+		border-radius: 15px;
+	}
+	:is(.mkt, .atelic-ui) .disclosure-meta {
+		display: inline-flex;
+		align-items: center;
+		color: var(--neutral-500);
+	}
+	:is(.mkt, .atelic-ui) .disclosure-chevron {
+		margin-left: auto;
+		flex-shrink: 0;
+		color: var(--neutral-500);
+		transition: transform 200ms ease;
+	}
+	:is(.mkt, .atelic-ui) .disclosure.is-open .disclosure-chevron {
+		transform: rotate(180deg);
+	}
+	:is(.mkt, .atelic-ui) .disclosure-body {
+		border-top: 1px solid var(--neutral-200);
+	}
+
 	/* ---- Collapsible: a labeled line that opens to the detail behind it ---- */
 	:is(.mkt, .atelic-ui) .collapsible > summary {
 		display: flex;