@handamade/psi-react 0.3.0

package/docs/Input.md

@@ -0,0 +1,36 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# Input
+
+
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `size` | `24 \| 32 \| 40 \| 48` | 32 | no | Height in px (24 \| 32 \| 40 \| 48). |
+| `error` | `boolean` | false | no | Show error styling. |
+| `ref` | `Ref<HTMLInputElement>` | — | no | Forwarded ref to the underlying `<input>` element. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Tab | Focuses the native <input>; focus ring on the field. |
+
+error sets a red border only — pair with aria-invalid and aria-describedby pointing at your error text.
+
+## Theming
+
+Override `--psi-input-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).

package/docs/NavBar.md

@@ -0,0 +1,29 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# NavBar
+
+
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `brand` | `ReactNode` | — | no | Brand slot (wordmark / logo link), leading edge. |
+| `actions` | `ReactNode` | — | no | Trailing actions slot (theme switch, CTA). |
+| `children` | `ReactNode` | — | no | Nav links. |
+| `ref` | `Ref<HTMLElement>` | — | no | Forwarded ref to the header element. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+
+## Theming
+
+Override `--psi-navbar-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).

package/docs/Select.md

@@ -0,0 +1,37 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# Select
+
+
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `size` | `24 \| 32 \| 40 \| 48` | 32 | no | Height in px (24 \| 32 \| 40 \| 48). Replaces the native `size` attribute (which sets the visible option-row count on a listbox-style `<select>`) with the design system's control height in pixels. |
+| `error` | `boolean` | false | no | Show error styling. |
+| `ref` | `Ref<HTMLSelectElement>` | — | no | Forwarded ref to the underlying `<select>` element. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Tab | Focuses the native <select>. |
+| Arrow keys / typeahead | Native option navigation. |
+
+error: same contract as Input.
+
+## Theming
+
+Override `--psi-select-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).

package/docs/Switch.md

@@ -0,0 +1,34 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# Switch
+
+
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `children` | `ReactNode` | — | no | Label text. |
+| `ref` | `Ref<HTMLInputElement>` | — | no | Forwarded ref to the underlying `<input type="checkbox" role="switch">` element. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Space | Toggles. Native checkbox input with role="switch"; announced as a switch, not a checkbox. |
+
+
+## Theming
+
+Override `--psi-switch-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).

package/docs/Tag.md

@@ -0,0 +1,47 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# Tag
+
+
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `variant` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger"` | neutral | no | Semantic color variant. |
+| `subtle` | `boolean` | false | no | Use tinted background with semantic foreground. |
+| `onDismiss` | `(() => void)` | — | no | When provided, renders a dismiss button that calls this handler. |
+| `ref` | `Ref<HTMLSpanElement>` | — | no | Forwarded ref to the underlying `<span>` element. |
+| `className` | `string` | — | no | Additional CSS class name(s) merged onto the component's root element. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Enter / Space (dismiss button) | onDismiss renders a real <button>; keyboard-dismissible. |
+
+Passive label otherwise; not in the tab order without onDismiss.
+
+## Theming
+
+Override `--psi-tag-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+## Variant guidance
+
+- **accent** — Primary action, draws attention. Submit, CTA, main action in a group.
+- **accent-subtle** — Accent tone, lower visual weight. Selected state, active filter, soft CTA.
+- **neutral** — Default, structurally present. Secondary actions, toolbar buttons.
+- **neutral-subtle** — Minimal chrome. Inline actions, table row actions.
+- **ghost** — No visible container until hover. Icon-only triggers, compact toolbars.
+- **outline** — Bordered ghost — visible structure, no fill until hover. Marketing CTA, download button; hover fills accent.
+- **danger** — Destructive action. Delete, remove, disconnect.
+- **danger-subtle** — Destructive context, low urgency. Warning badges, soft destructive hints.
+- **success | warning** — Status communication (Tag only). Status badges, labels.
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).

package/docs/Tooltip.md

@@ -0,0 +1,36 @@
+<!-- Generated by emit-docs.ts — do not edit. -->
+# Tooltip
+
+
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `content` | `ReactNode` | — | yes | Tooltip content. |
+| `children` | `ReactElement<Record<string, unknown>, string \| JSXElementConstructor<any>>` | — | yes | The trigger element (must accept ref, onMouseEnter/Leave, onFocus/Blur). |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` | top | no | Preferred placement. |
+
+## Keyboard & assistive tech
+
+| Keys | Behavior |
+|---|---|
+| Tab (focus trigger) | Shows immediately on focus (no delay). |
+| Escape | Dismisses while visible (WCAG 1.4.13). |
+
+Hover opens after a short delay; content is linked via aria-describedby while visible. Trigger must accept onMouseEnter/Leave and onFocus/Blur props (cloned in automatically) — no ref forwarding required.
+
+## Theming
+
+Override `--psi-tooltip-*` custom properties at any scope; interactive states derive automatically (L - 0.04 hover, L - 0.08 active).
+
+
+
+## Rules
+
+- One accent per visual group; everything else neutral or ghost.
+- danger only for actions with real consequences.
+- Sizes are px numbers (24|32|40|48), never S/M/L.
+- Typography tokens are --psi-text-{size}-{lineHeight}-{weight}.
+- Override component tokens (--psi-{component}-*), not semantic tokens, for one-off theming.
+- --psi-button-font overrides button typography across all sizes (documented D34 override; ember → mono).

package/llms.txt

@@ -0,0 +1,43 @@
+# @handamade/psi-react
+
+11 React 19 components consuming @handamade/psi-tokens. Zero runtime deps, CSS Modules, ref-as-prop.
+
+## Machine-readable artifacts
+- dist/manifest.json: full component/prop inventory with types and defaults
+- docs/{Component}.md: per-component docs (props, theming, variant guidance)
+
+## Rules for generated code
+- import { Button } from "@handamade/psi-react"; import "@handamade/psi-react/styles";
+- Also import from @handamade/psi-tokens: base.css, a theme css, components.css, utilities.css.
+- size is a px number (24|32|40|48), never "sm"/"md"/"lg".
+- variant vocabulary: accent | accent-subtle | neutral | neutral-subtle | ghost | danger | danger-subtle | outline.
+- One accent per visual group. danger only for destructive actions.
+
+## Button: href + outline (D33/D34)
+- Button renders as an <a> when given `href` (plus optional `target`/`rel`); disabled anchors get aria-disabled, no href attribute, and pointer-events: none instead of the disabled attribute.
+- `outline` is a bordered-ghost variant: visible structure, no fill until hover — good for marketing CTAs and download buttons.
+- --psi-button-font overrides button typography across all sizes in one declaration; brands can set it via componentOverrides (ember → mono).
+
+## Card
+- <Card variant="stacked" | "featured" media={...} hoverLift>: stacked places media above the body, featured places media beside it (~1.6fr/1fr, stacks under the md breakpoint). hoverLift lifts the card translateY(-6px) over --psi-duration-350. Border uses --psi-border-faint.
+
+## NavBar
+- <NavBar brand={...} actions={...}>{links}</NavBar>: brand slot leading, nav links centered/inline, actions slot trailing (theme switch, CTA). Renders inside .psi-container. Background defaults to --psi-scrim-heavy so content can scroll underneath; border uses --psi-border-faint.
+
+## AspectRatio
+- <AspectRatio ratio={16/10}>{children}</AspectRatio>: a frame div with CSS aspect-ratio set from the numeric ratio prop — wrap images/media to reserve layout space before load. Combine with the .psi-media-tint utility for the brand media-tint treatment.
+
+## Icons (22)
+- Full icon set: IconPlus, IconMinus, IconCheck, IconClose, IconChevronDown, IconChevronRight, IconSearch, IconSettings, IconUser, IconEye, IconEyeOff, IconEdit, IconCopy, IconTrash, IconLoader, IconExternalLink, plus D36 additions — arrows IconArrowDown and IconArrowUpRight, and social glyphs IconLinkedIn, IconGitHub, IconX, IconInstagram.
+
+## Compositions (recipes for what has no component yet)
+
+- Form field: there is no Field/Label component. Compose: `<label htmlFor>` styled with `.psi-text-14-20-medium`; the control (Input/Select); error text in `.psi-text-12-16-regular` with `color: var(--psi-fg-danger)`, linked via `aria-describedby` on the control plus `aria-invalid` and `error` when invalid. Spacing: `ds-gap-6` label→control, `ds-gap-24` between fields, `ds-gap-12` for toggle groups, `ds-gap-8` for button rows and label+Tag rows.
+- Stacks/rows: `.psi-gap-*` utilities set only the gap — they do not create a flex/grid container. Pair them with `display: flex` (column for stacks, row for button groups).
+- Native pass-through: components spread unlisted props onto their underlying element (Input → `<input>`, Select → `<select>`, Button → `<button>`/`<a>`), so `value`, `onChange`, `type`, `id`, `autoComplete`, `checked` etc. all work even though manifest.json lists only the component-specific props. Exception: Tooltip takes no host props — put handlers/attributes on its trigger child.
+- Theming, programmatic: the standard setup is `data-psi-theme` on `<html>`. From JS, set it once at app init: `document.documentElement.dataset.dsTheme = "dark"` (React: in a root-level effect). Theme CSS does NOT paint the page background — paint `background: var(--psi-bg-primary)` at your app root yourself. For a themed subtree, set `data-psi-theme` on a wrapper and paint its background the same way; brand font combos do not reach nested subtrees (see guidance.fonts.scope).
+- Size selection: 32 is the default (compact UI); 40 for comfortable forms and marketing pages; 24 for inline/table-row actions; 48 for hero CTAs.
+- Tags & the accent rule (D40): Tags are passive labels — they do NOT count against "one accent per visual group" (that rule governs buttons/CTAs). Badge mapping: highlight (e.g. a plan badge) → `accent-subtle`; meta → `neutral-subtle`; status → `success`/`warning`/`danger`.
+- CSS import order: all DS stylesheets are order-independent — base.css opens with an explicit `@layer psi.base, psi.theme, psi.components, psi.utilities;` statement. Recommended listing for readability: base → theme → components → utilities → @handamade/psi-react/styles.
+- Widths: content widths are app-level; the system tokenizes the page container only (`--psi-container-max`). Component width tokens arrive with Field/Dialog (next cycle).
+- Full semantic token roster: `@handamade/psi-tokens/resolved/<theme>.json` has every token with resolved values — this file lists only the patterns.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@handamade/psi-react",
+  "version": "0.3.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./styles": "./dist/styles.css",
+    "./manifest.json": "./dist/manifest.json"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "llms.txt"
+  ],
+  "peerDependencies": {
+    "@handamade/psi-tokens": ">=0.2.0 <1.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^4.3.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.0",
+    "react-docgen-typescript": "^2.4.0",
+    "react-dom": "^19.2.0",
+    "tsx": "^4.22.4",
+    "vite": "^6.0.0",
+    "vitest": "^3.2.6",
+    "@handamade/psi-tokens": "0.3.0"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json && tsx scripts/emit-manifest.ts && tsx scripts/emit-docs.ts",
+    "dev": "vite build --watch"
+  }
+}