@kyzarky/ui 0.1.0 → 0.2.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,26 @@ 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`.
+
 ## Rules
 
 - **Less space inside a group than between groups,** at least 1:2.
@@ -111,8 +134,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/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/index.d.ts

@@ -0,0 +1,3 @@
+export { List } from "./List.js";
+export { ListRow } from "./ListRow.js";
+export { Meter } from "./Meter.js";

package/dist/index.js

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

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.2.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 {