@kyzarky/ui 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,9 @@
 # @kyzarky/ui
 
-Design tokens for Ky Merritt's apps: a Tailwind CSS 4 theme with light and dark values.
-React components arrive in 0.2.0 ([ADR 0002](docs/decisions/0002-first-scope.md)). First
-consumer: Fluent Prior. Next: Merritt's Mini Mind.
+Design tokens and React components for Ky Merritt's apps: a Tailwind CSS 4 theme with
+light and dark values, and the components built on it
+([ADR 0002](docs/decisions/0002-first-scope.md)). First consumer: Fluent Prior. Next:
+Merritt's Mini Mind.
 
 ## Use
 
@@ -17,7 +18,9 @@ Then import the theme after Tailwind in the app's CSS:
 @import "@kyzarky/ui/theme.css";
 ```
 
-It needs Tailwind CSS 4. **Pin an exact version and upgrade on purpose,** so work in
+It needs Tailwind CSS 4, and React 19 for the components. The import also has the app's
+Tailwind scan the package's components, so their classes are generated with the app's own.
+**Pin an exact version and upgrade on purpose,** so work in
 progress here never changes an app under it. The [changelog](CHANGELOG.md) says what each
 version changes and how to upgrade.
 
@@ -78,6 +81,56 @@ own rule wins wherever it is. For example, a green brand color:
 `ring` follows `primary` unless you set it too. Keep the contrast of every pair in the
 table above.
 
+## Components
+
+```tsx
+import { List, ListRow, Meter } from "@kyzarky/ui";
+
+<List heading={<h3>Grammar</h3>} description="Optional help text.">
+  <ListRow label="Question word order" detail="99% · 9 answers">
+    <Meter value={0.99} />
+  </ListRow>
+</List>
+```
+
+- **`List`** is a group of rows with a divider between them. Pass the `heading` as an
+  element, at whatever level the page needs; `List` sets its look. A `List` that follows
+  something sits 32px below it.
+- **`ListRow`** is one row: a `label`, a `detail` on the right, and optional children
+  below for a graphic.
+- **`Meter`** is a bar for a `value` from 0 to 1. It's hidden from screen readers, so
+  state the value in the row's `detail`.
+
+```tsx
+import { Button, Card, SegmentedControl } from "@kyzarky/ui";
+
+<Card aria-labelledby="progress-heading" className="flex flex-col gap-4">
+  <SegmentedControl
+    label="Show"
+    value={view}
+    onChange={setView}
+    options={[
+      { value: "now", label: "Now" },
+      { value: "over-time", label: "Over time" },
+    ]}
+  />
+  <Button type="submit">Check my answer</Button>
+  <Button variant="outline" onClick={next}>Next situation</Button>
+</Card>
+```
+
+- **`Card`** is a raised surface, rendered as a `<section>`. Name it with
+  `aria-labelledby` or `aria-label`.
+- **`Button`** takes shadcn/ui's props: `variant` is `default` (filled), `outline`, or
+  `ghost`, and `size` is `default` or `icon`. Unlike a bare `<button>`, its `type` is
+  `button` unless you pass `submit`. It also takes every native button prop.
+- **`SegmentedControl`** picks one option from a few. It's a group of radio buttons
+  underneath, so arrow keys move between options. `label` names the group for screen
+  readers and isn't shown.
+
+`Card` and `Button` take a `className` for layout only (`flex-1`, `w-full`, a `gap`). It's
+added after the component's own classes, not merged with them, so don't use it to restyle.
+
 ## Rules
 
 - **Less space inside a group than between groups,** at least 1:2.
@@ -111,8 +164,9 @@ table above.
 
 | Command | What it does |
 |---|---|
-| `npm run verify` | Typecheck, lint, and test |
-| `npm test` | The contrast and fallback tests, and a Tailwind build of the theme |
+| `npm run verify` | Typecheck, lint, test, and build |
+| `npm run build` | Compiles `src` to `dist` with `tsc`. `npm pack` and `npm publish` run it first |
+| `npm test` | The contrast, fallback, and component tests, and a Tailwind build of the theme |
 | `npm run test:browsers` | Opens `browser-check.html` in Chromium, Firefox, and WebKit, in light and dark. Needs `npx playwright install` once. Add engine names to run only those: `npm run test:browsers -- webkit` |
 | `npm run format` | Biome: format and apply safe lint fixes |
 

package/dist/Button.d.ts

@@ -0,0 +1,20 @@
+import type { ComponentProps } from "react";
+declare const VARIANTS: {
+    /** Filled with the brand color: the main action. */
+    default: string;
+    /** An edge and the card color: a second action beside a filled one. */
+    outline: string;
+    /** Nothing until hovered: a quiet action, such as an icon in a toolbar. */
+    ghost: string;
+};
+declare const SIZES: {
+    default: string;
+    /** Square, for a single icon. Give the button an aria-label. */
+    icon: string;
+};
+interface ButtonProps extends ComponentProps<"button"> {
+    variant?: keyof typeof VARIANTS;
+    size?: keyof typeof SIZES;
+}
+export declare function Button({ variant, size, type, className, ...props }: ButtonProps): import("react").JSX.Element;
+export {};

package/dist/Button.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { joinClasses } from "./joinClasses.js";
+const VARIANTS = {
+    /** Filled with the brand color: the main action. */
+    default: "bg-primary text-primary-foreground hover:bg-primary/90 active:bg-primary/80",
+    /** An edge and the card color: a second action beside a filled one. */
+    outline: "border border-input bg-card hover:bg-muted active:bg-muted",
+    /** Nothing until hovered: a quiet action, such as an icon in a toolbar. */
+    ghost: "hover:bg-muted active:bg-muted",
+};
+const SIZES = {
+    default: "px-5",
+    /** Square, for a single icon. Give the button an aria-label. */
+    icon: "w-11",
+};
+export function Button({ variant = "default", size = "default", 
+// A bare <button> inside a form submits it. Submitting should be asked for.
+type = "button", className, ...props }) {
+    return (_jsx("button", { type: type, className: joinClasses("inline-flex min-h-11 items-center justify-center gap-2 rounded-xl font-semibold transition-colors focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-2 disabled:pointer-events-none disabled:opacity-50", VARIANTS[variant], SIZES[size], className), ...props }));
+}

package/dist/Card.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentProps } from "react";
+export declare function Card({ className, ...props }: ComponentProps<"section">): import("react").JSX.Element;

package/dist/Card.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { joinClasses } from "./joinClasses.js";
+export function Card({ className, ...props }) {
+    return (_jsx("section", { className: joinClasses("rounded-2xl border border-border bg-card p-5 text-card-foreground shadow-sm", className), ...props }));
+}

package/dist/List.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+interface ListProps {
+    /**
+     * The heading element, at whatever level the page needs: `<h3>Grammar</h3>`. The level
+     * is the page's to choose; the look is set here. Tailwind's preflight makes headings
+     * inherit size and weight, so the wrapper's classes apply to it.
+     */
+    heading?: ReactNode;
+    /** A line of help text between the heading and the rows. */
+    description?: ReactNode;
+    /** `ListRow`s. */
+    children: ReactNode;
+}
+export declare function List({ heading, description, children }: ListProps): import("react").JSX.Element;
+export {};

package/dist/List.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function List({ heading, description, children }) {
+    return (_jsxs("div", { className: "mt-8 first:mt-0", children: [heading && _jsx("div", { className: "font-semibold text-base", children: heading }), description && _jsx("p", { className: "mt-1 text-muted-foreground text-sm", children: description }), _jsx("ul", { className: "mt-2 divide-y divide-border", children: children })] }));
+}

package/dist/ListRow.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+interface ListRowProps {
+    label: ReactNode;
+    /** Secondary text on the right. If the row has a graphic, this states its value. */
+    detail?: ReactNode;
+    /** A graphic for the row, such as a `Meter`. */
+    children?: ReactNode;
+}
+export declare function ListRow({ label, detail, children }: ListRowProps): import("react").JSX.Element;
+export {};

package/dist/ListRow.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function ListRow({ label, detail, children }) {
+    return (_jsxs("li", { className: "py-3", children: [_jsxs("div", { className: "flex items-baseline justify-between gap-3 text-sm", children: [_jsx("span", { children: label }), detail && _jsx("span", { className: "shrink-0 text-muted-foreground tabular-nums", children: detail })] }), children && _jsx("div", { className: "mt-2", children: children })] }));
+}

package/dist/Meter.d.ts

@@ -0,0 +1,6 @@
+interface MeterProps {
+    /** From 0 to 1. Values outside that are clamped, and NaN draws an empty bar. */
+    value: number;
+}
+export declare function Meter({ value }: MeterProps): import("react").JSX.Element;
+export {};

package/dist/Meter.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function Meter({ value }) {
+    // `|| 0` turns NaN into 0. An invalid width would be ignored, leaving the bar full.
+    const percent = Math.min(1, Math.max(0, value || 0)) * 100;
+    return (_jsx("div", { "aria-hidden": "true", className: "h-2 overflow-hidden rounded-full bg-muted", children: _jsx("div", { className: "h-full rounded-full bg-primary", style: { width: `${percent}%` } }) }));
+}

package/dist/SegmentedControl.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from "react";
+interface SegmentedControlProps<Value extends string> {
+    /** What the choice is, for screen readers: "Show", "Sort by". Not displayed. */
+    label: string;
+    options: readonly {
+        value: Value;
+        label: ReactNode;
+    }[];
+    value: Value;
+    onChange: (value: Value) => void;
+}
+export declare function SegmentedControl<Value extends string>({ label, options, value, onChange, }: SegmentedControlProps<Value>): import("react").JSX.Element;
+export {};

package/dist/SegmentedControl.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A choice of one option from a few, shown side by side. Underneath it's a group of radio
+// buttons, so arrow keys move between options and a screen reader says how many there
+// are, with no key handling written here. The selected look comes from CSS :has(:checked).
+import { useId } from "react";
+export function SegmentedControl({ label, options, value, onChange, }) {
+    // Radio buttons form one group by sharing a name.
+    const name = useId();
+    return (_jsxs("fieldset", { className: "flex rounded-full bg-muted p-1 text-sm", children: [_jsx("legend", { className: "sr-only", children: label }), options.map((option) => (_jsxs("label", { className: "flex min-h-11 cursor-pointer items-center rounded-full px-4 text-muted-foreground has-checked:bg-card has-checked:font-medium has-checked:text-foreground has-checked:shadow-sm has-focus-visible:outline-2 has-focus-visible:outline-ring has-focus-visible:outline-offset-2", children: [_jsx("input", { type: "radio", className: "sr-only", name: name, value: option.value, checked: option.value === value, onChange: () => onChange(option.value) }), option.label] }, option.value)))] }));
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Button } from "./Button.js";
+export { Card } from "./Card.js";
+export { List } from "./List.js";
+export { ListRow } from "./ListRow.js";
+export { Meter } from "./Meter.js";
+export { SegmentedControl } from "./SegmentedControl.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+// The package's components. The tokens they use come from theme.css.
+export { Button } from "./Button.js";
+export { Card } from "./Card.js";
+export { List } from "./List.js";
+export { ListRow } from "./ListRow.js";
+export { Meter } from "./Meter.js";
+export { SegmentedControl } from "./SegmentedControl.js";

package/dist/joinClasses.d.ts

@@ -0,0 +1 @@
+export declare function joinClasses(...names: (string | undefined)[]): string;

package/dist/joinClasses.js

@@ -0,0 +1,6 @@
+// Joins class names, skipping any that aren't set. It doesn't resolve conflicts: a
+// component's `className` prop is for layout (flex-1, w-full, a margin), which the
+// component's own classes never set.
+export function joinClasses(...names) {
+    return names.filter(Boolean).join(" ");
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kyzarky/ui",
-  "version": "0.1.0",
-  "description": "Design tokens for Ky Merritt's apps, as a Tailwind CSS 4 theme with light and dark values",
+  "version": "0.3.0",
+  "description": "Design tokens and React components for Ky Merritt's apps, built on Tailwind CSS 4",
   "license": "MIT",
   "author": "Ky Merritt",
   "repository": {
@@ -10,30 +10,42 @@
   },
   "type": "module",
   "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
     "./theme.css": "./theme.css"
   },
   "files": [
-    "theme.css"
+    "theme.css",
+    "dist"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "format": "biome check --write .",
     "test": "vitest run",
-    "verify": "npm run typecheck && npm run lint && npm run test",
-    "test:browsers": "node browser-check.ts"
+    "test:browsers": "node browser-check.ts",
+    "verify": "npm run typecheck && npm run lint && npm run test && npm run build"
   },
   "peerDependencies": {
+    "react": "^19.0.0",
     "tailwindcss": "^4.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
     "@tailwindcss/node": "^4.3.3",
     "@types/node": "^26.6.4",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "playwright": "^1.64.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "tailwindcss": "^4.3.3",
     "typescript": "~6.0.3",
     "vitest": "^5.0.3"

package/theme.css

@@ -9,6 +9,10 @@
    color-scheme itself. Components use the utilities (bg-card, text-muted-foreground) and
    never Tailwind's dark: variant. */
 
+/* The components are published as compiled files full of Tailwind class names. This has
+   the app's Tailwind scan them, so it generates those classes along with the app's own. */
+@source "./dist";
+
 /* In the base layer, so an app's own unlayered rules win wherever it puts them. That's
    how an app themes the package: by redefining a token. */
 @layer base {