@xenide-io/the-old-ui-theme 0.7.0 → 0.9.0

package/docs/component-reference.md

@@ -0,0 +1,81 @@
+# Component Reference
+
+The published package is `@xenide-io/the-old-ui-theme`. Import the supported
+product surface from the package root:
+
+```tsx
+import { Button, Card, H1, P } from "@xenide-io/the-old-ui-theme";
+```
+
+The `/ui` entry additionally exposes `Range`, `Kbd`, `SearchGroup`,
+`FilterControls`, `ThemeDomSync`, `ThemeSwitcher`, and catalogue helpers.
+The `/suite` entry exposes ShellStack-specific application chrome and workflow
+components; it is not a generic primitive library.
+
+## Actions And Feedback
+
+| Component | Primary API |
+|---|---|
+| `Button` | `variant`, `size`, `shape`, `loading`, `icon`, `sideIcon`, `split`, `outline` |
+| `ButtonChrome` | Shared visual button chrome for product-specific actions. |
+| `Alert` | `status`, `title`, `description`, `icon`, `onDismiss`, `live` |
+| `Badge` | `variant`, `size` |
+| `Loader` | `variant`, `size`, `label` |
+| `LoadingState` | `label`, `title`, `description`, `variant`, `size` |
+| `Skeleton` | `shape` |
+| `Progress` | `value`, `max`, `label`, `showPercentage`, `size` |
+| `EmptyState` | `icon`, `title`, `description`, `action` |
+
+## Forms
+
+| Component | Primary API |
+|---|---|
+| `FormField` | `controlId`, `label`, `hideLabel`, `helperText`, `error`, `required` |
+| `Input` | Native input props plus `label`, `hideLabel`, `error`, `helperText`, `size`, `variant` |
+| `Select` | Native select props plus `label`, `hideLabel`, `error`, `helperText`, `size` |
+| `Textarea` | Native textarea props plus `label`, `hideLabel`, `error`, `helperText`, `size` |
+| `Checkbox`, `Radio`, `Toggle` | Native control props plus label and field feedback props. |
+| `FileUpload` | File-input wrapper with label and prompt. |
+| `SearchInput` | Search field with optional shortcut and density. |
+| `Range` (`/ui`) | Native range wrapper with labels and value display. |
+
+## Overlays And Selection
+
+| Component | Primary API |
+|---|---|
+| `Modal` | `open`, `onClose`, `title`, `description`, `footer`, `size`, dismissal controls |
+| `DropdownMenu` | Radix-backed `trigger`, `align`, `side`, menu content. |
+| `DropdownItem`, `DropdownRadioGroup`, `DropdownRadioItem` | Canonical menu item composition. |
+| `Tooltip` | `content`, `side`, `align`, `open`, `defaultOpen`, `onOpenChange` |
+| `Accordion` | `items`, `allowMultiple`, `defaultOpen` |
+| `SegmentedControl` | `options`, `value`, `onChange` |
+| `Calendar` | `value`, `onChange` |
+| `CommandPalette` | `items`, `isOpen`, `onClose` |
+| `FilterBar`, `FilterMenu`, `SortMenu`, `FilterChips` | Stateless filtering composition. |
+
+## Content And Layout
+
+| Component | Primary API |
+|---|---|
+| `Card` | `title`, `description`, `media`, `actions`, `footer`, `variant` |
+| `Panel` | `title`, `description`, native div props. |
+| `Table` | `data`, `columns`, `getRowKey`, `caption`, density and ribbon props. |
+| `Stat` | `label`, `value`, `tone`, `icon`, `footer` |
+| `Avatar`, `AvatarGroup` | `size`, `status`, label/icon and grouping props. |
+| `AuthLayout`, `AuthCard`, `AuthDivider` | Authentication page composition. |
+| `SettingsLayout`, `SettingsNav` | Settings page composition and navigation. |
+
+## Typography And Utilities
+
+`Display`, `SectionTitle`, `H1` through `H5`, `P`, `Small`, `Caption`,
+`Overline`, `Lead`, `Mono`, `Label`, `Link`, `Chip`, `Dot`, `Spinner`,
+`Icon`, and `IconByName` are exported from the root package.
+
+Themes are provided through `THEMES`, `THEME_GROUPS`, `getTheme`,
+`persistTheme`, `readStoredTheme`, `THEME_INIT_SCRIPT`, `ThemeDomSync`, and
+`ThemeSwitcher`.
+
+Use the generated TypeScript declarations as the authoritative detailed prop
+reference until per-component API pages are added. Named props interfaces are
+available for the major primitives and are being standardised across the
+remaining public components.

package/docs/components.md

@@ -0,0 +1,48 @@
+# Component Usage
+
+Import supported components from `@xenide-io/the-old-ui-theme`. The complete
+supported surface is listed in the [component reference](./component-reference.md).
+
+```tsx
+import {
+  Alert,
+  Button,
+  Card,
+  Input,
+  Modal,
+  Table,
+  type TableColumn,
+} from "@xenide-io/the-old-ui-theme";
+```
+
+Use `className` for layout and small local adjustments. Prefer a component's
+typed props and semantic token classes over literal colours or bespoke control
+implementations.
+
+```tsx
+<Card title="Workspace settings" description="Manage member access.">
+  <Input label="Workspace name" defaultValue="Research" />
+  <Button variant="primary">Save changes</Button>
+</Card>
+
+<Alert status="warning" title="Approaching quota" />
+
+<Modal open={open} onClose={() => setOpen(false)} title="Create project">
+  <Input label="Project name" autoFocus />
+</Modal>
+```
+
+Tables need stable row identity whenever rows can change order or contain
+stateful content:
+
+```tsx
+const columns: TableColumn<User>[] = [
+  { key: "name", header: "Name", cell: (user) => user.name },
+];
+
+<Table data={users} columns={columns} getRowKey={(user) => user.id} />;
+```
+
+For the additional `/ui` surface, import from
+`@xenide-io/the-old-ui-theme/ui`. Use `/suite` only for ShellStack product
+chrome and suite workflow components.

package/docs/demos.md

@@ -0,0 +1,19 @@
+# Demo Routes
+
+The catalogue is intentionally split into focused routes. The root `/` route
+redirects to `/demo` instead of mounting every showcase at once.
+
+| Route               | Focus                                                      |
+| ------------------- | ---------------------------------------------------------- |
+| `/demo`             | Demo index and route picker                                |
+| `/demo/foundations` | Type scale, tokens, themes, icons, setup, and shortcuts     |
+| `/demo/components`  | Primitive components and everyday controls                 |
+| `/demo/patterns`    | Auth, settings, overlays, filters, and loading flows       |
+| `/demo/suite`       | Suite shell, sidebar, mobile chrome, and settings patterns |
+
+Every showcase maps to a component the ShellStack apps ship. If a component is
+not used by an app, it does not belong in the package or the demo.
+
+Every demo route uses the shared `SuiteAppLayout`. The sidebar selection is
+route-aware, the desktop rail is resizable, and the width is persisted per
+browser.

package/docs/installation.md

@@ -0,0 +1,117 @@
+# Installation
+
+## Build The Library
+
+Run this in the UI library repo:
+
+```bash
+bun install
+bun run build:lib
+```
+
+The library build outputs:
+
+```txt
+dist/index.mjs
+dist/index.js
+dist/index.d.ts
+```
+
+## Local Install In Another App
+
+Use this while developing locally:
+
+```json
+{
+  "dependencies": {
+    "@xenide-io/the-old-ui-theme": "file:../path-to/the-old-ui"
+  }
+}
+```
+
+Then install in the consuming app:
+
+```bash
+bun install
+```
+
+## Published Install
+
+After publishing:
+
+```bash
+bun add @xenide-io/the-old-ui-theme
+```
+
+or:
+
+```bash
+npm install @xenide-io/the-old-ui-theme
+```
+
+## Import Styles Once
+
+In a Next.js app:
+
+```tsx
+// app/layout.tsx
+import "@xenide-io/the-old-ui-theme/styles.css";
+```
+
+## Tailwind Setup
+
+Add the package preset and include the built package files in `content`.
+
+```ts
+// tailwind.config.ts
+import theOldUiPreset from "@xenide-io/the-old-ui-theme/tailwind-preset";
+
+export default {
+  presets: [theOldUiPreset],
+  content: [
+    "./src/**/*.{ts,tsx}",
+    "./app/**/*.{ts,tsx}",
+    "./node_modules/@xenide-io/the-old-ui-theme/dist/**/*.{js,mjs}",
+  ],
+};
+```
+
+## Next.js Theme Setup
+
+Use `THEME_INIT_SCRIPT` to avoid a theme flash and `ThemeDomSync` to sync the stored theme after hydration.
+
+```tsx
+// app/layout.tsx
+import "@xenide-io/the-old-ui-theme/styles.css";
+import { THEME_INIT_SCRIPT, ThemeDomSync } from "@xenide-io/the-old-ui-theme";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" data-theme="hedgehog-light" suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }} />
+      </head>
+      <body>
+        <ThemeDomSync />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+## Basic Usage
+
+```tsx
+import { Button, Card, H1, P } from "@xenide-io/the-old-ui-theme";
+
+export function Example() {
+  return (
+    <Card
+      title={<H1>Dashboard</H1>}
+      description={<P tone="subtle">Your workspace overview.</P>}
+      actions={<Button variant="primary">Create insight</Button>}
+    />
+  );
+}
+```

package/docs/suite-audit.md

@@ -0,0 +1,34 @@
+# Suite UI Audit
+
+The suite apps are separate consumers of this package. The shared package now
+owns the visual language; app code should keep product-specific workflows and
+illustrations.
+
+## Move Into The Shared Package
+
+| Pattern                                                      | Current consumers                     | Shared home                                                             |
+| ------------------------------------------------------------ | ------------------------------------- | ----------------------------------------------------------------------- |
+| Desktop rail, mobile header, bottom navigation               | Tides, TurtleTime, ShellStack, Kraken | `SuiteAppLayout`, `SuiteSidebar`, `SuiteMobileHeader`, `SuiteBottomNav` |
+| App switching, notifications, command handoff                | All suite apps                        | `/suite` exports                                                        |
+| Cards, alerts, empty/loading states, dialogs, inputs, tables | All suite apps                        | `/ui` exports and `--ph-*` tokens                                       |
+| Auth and settings chrome                                     | Tides, TurtleTime, ShellStack, Kraken | `AuthLayout`, `AuthCard`, `SettingsLayout`                              |
+| Theme pairing, semantic status colours, focus rings          | All suite apps                        | `themes.css` and `themes/registry.ts`                                   |
+
+## Keep In The Apps
+
+- Tides kanban, task detail, BlockNote editor, project and crew controls.
+- TurtleTime tracker, timer state, report charts, and time-entry workflows.
+- ShellStack terminal scene, workspace/billing domain, and API documentation.
+- Kraken document editor, React Flow diagrams, deep research, and citations.
+- Product marks and illustrations that carry product meaning.
+
+## Adoption Contract
+
+Keep app canvases token-driven and quiet by default:
+
+```tsx
+<SuiteAppLayout {...props} />
+```
+
+Decorative hero treatments should remain app-owned and opt-in. Do not add
+continuous animated backgrounds to dense product workspaces.

package/docs/theme-token-reference.md

@@ -0,0 +1,67 @@
+# Theme Token Reference
+
+The built-in palettes are defined in `src/styles/themes.css`; the registry in
+`src/themes/registry.ts` is the source of truth for IDs, names, and modes.
+
+## Theme IDs
+
+```ts
+"hedgehog-light";
+"hedgehog-dark";
+"note";
+"note-dark";
+"turtletime";
+"turtletime-dark";
+"rosepine-light";
+"rosepine-dark";
+"kraken-light";
+"kraken-dark";
+"deepsea-light";
+"deepsea-dark";
+"malibu-light";
+"malibu-dark";
+```
+
+## Theme Pairs
+
+| Pair        | Light            | Dark              |
+| ----------- | ---------------- | ----------------- |
+| HedgeHog    | `hedgehog-light` | `hedgehog-dark`   |
+| Note        | `note`           | `note-dark`       |
+| TurtleTime  | `turtletime`     | `turtletime-dark` |
+| Rosé Pine   | `rosepine-light` | `rosepine-dark`   |
+| Kraken      | `kraken-light`   | `kraken-dark`     |
+| Tokyo Night | `deepsea-light`  | `deepsea-dark`    |
+| Malibu      | `malibu-light`   | `malibu-dark`     |
+
+## Core Tokens
+
+Every built-in theme defines these semantic values:
+
+```css
+--ph-canvas
+--ph-surface
+--ph-muted
+--ph-toolbar
+--ph-border
+--ph-border-strong
+--ph-text-primary
+--ph-text-secondary
+--ph-text-tertiary
+--ph-accent
+--ph-accent-hover
+--ph-blue
+--ph-violet
+--ph-purple
+--ph-success
+--ph-warning
+--ph-danger
+--ph-info
+--ph-data-1 through --ph-data-7
+```
+
+Malibu uses a sun-bleached GTA San Andreas palette in light mode and Shelly's
+deep plum command deck in dark mode, with hot pink, lime, cyan, amber, and
+emerald signals.
+
+For the complete token values, read `src/styles/themes.css` directly.

package/docs/themes.md

@@ -0,0 +1,164 @@
+# Themes
+
+Themes are CSS-variable based. Components read semantic `--ph-*` tokens, so changing `html[data-theme]` changes the whole UI without editing components.
+
+## Default Theme
+
+```txt
+hedgehog-light
+```
+
+Dark pair:
+
+```txt
+hedgehog-dark
+```
+
+## Built-In Theme Pairs
+
+```ts
+export const themePairs = [
+  { name: "HedgeHog", light: "hedgehog-light", dark: "hedgehog-dark" },
+  { name: "Note", light: "note", dark: "note-dark" },
+  { name: "TurtleTime", light: "turtletime", dark: "turtletime-dark" },
+  { name: "Rose Pine", light: "rosepine-light", dark: "rosepine-dark" },
+  { name: "Kraken", light: "kraken-light", dark: "kraken-dark" },
+  { name: "Tokyo Night", light: "deepsea-light", dark: "deepsea-dark" },
+  { name: "Malibu", light: "malibu-light", dark: "malibu-dark" },
+] as const;
+```
+
+## Theme Switching
+
+Use the built-in switcher:
+
+```tsx
+import { ThemeSwitcher } from "@xenide-io/the-old-ui-theme";
+
+<ThemeSwitcher />;
+```
+
+Switch manually and persist to `localStorage`:
+
+```tsx
+import { persistTheme } from "@xenide-io/the-old-ui-theme";
+
+persistTheme("malibu-dark");
+```
+
+Set directly without persistence:
+
+```tsx
+document.documentElement.setAttribute("data-theme", "malibu-dark");
+```
+
+## Master Color List
+
+The source of truth for all theme colors is:
+
+```txt
+src/styles/themes.css
+```
+
+The source of truth for theme IDs, names, groups, and light/dark mode metadata is:
+
+```txt
+src/themes/registry.ts
+```
+
+The rendered demo has a visual swatch guide under **Setup & Theme**.
+
+For the complete AI-readable list of every built-in theme and token value, see [Theme Token Reference](./theme-token-reference.md).
+
+## Core Theme Tokens
+
+Every theme should define these semantic tokens:
+
+```css
+--ph-canvas
+--ph-surface
+--ph-muted
+--ph-toolbar
+--ph-border
+--ph-border-strong
+
+--ph-text-primary
+--ph-text-secondary
+--ph-text-tertiary
+
+--ph-accent
+--ph-accent-hover
+--ph-blue
+--ph-purple
+
+--ph-success
+--ph-warning
+--ph-danger
+--ph-info
+
+--ph-data-1
+--ph-data-2
+--ph-data-3
+--ph-data-4
+--ph-data-5
+--ph-data-6
+--ph-data-7
+```
+
+## Custom Light And Dark Theme
+
+Custom themes work like DaisyUI themes: define a light block and a dark block.
+
+```css
+@import "@xenide-io/the-old-ui-theme/styles.css";
+
+[data-theme="my-theme-light"] {
+  color-scheme: light;
+
+  --ph-canvas: #f8f5ef;
+  --ph-surface: #ffffff;
+  --ph-muted: #eee8dd;
+  --ph-toolbar: #e5dccd;
+  --ph-border: #d7cbb8;
+  --ph-border-strong: #a99b87;
+
+  --ph-text-primary: #15110c;
+  --ph-text-secondary: #4d4337;
+  --ph-text-tertiary: #796f63;
+
+  --ph-accent: #f97316;
+  --ph-accent-hover: #ea580c;
+  --ph-blue: #2563eb;
+  --ph-purple: #7c3aed;
+  --ph-success: #15803d;
+  --ph-warning: #b45309;
+  --ph-danger: #dc2626;
+  --ph-info: #2563eb;
+}
+
+[data-theme="my-theme-dark"] {
+  color-scheme: dark;
+
+  --ph-canvas: #11100e;
+  --ph-surface: #191713;
+  --ph-muted: #242018;
+  --ph-toolbar: #2e281f;
+  --ph-border: #443a2b;
+  --ph-border-strong: #7a6a54;
+
+  --ph-text-primary: #fff7ed;
+  --ph-text-secondary: #d8c8b6;
+  --ph-text-tertiary: #a89985;
+
+  --ph-accent: #fb923c;
+  --ph-accent-hover: #fdba74;
+  --ph-blue: #60a5fa;
+  --ph-purple: #a78bfa;
+  --ph-success: #4ade80;
+  --ph-warning: #facc15;
+  --ph-danger: #f87171;
+  --ph-info: #60a5fa;
+}
+```
+
+If the custom theme should appear in the built-in `ThemeSwitcher`, add both IDs to `src/themes/registry.ts` before building the package.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xenide-io/the-old-ui-theme",
-  "version": "0.7.0",
-  "description": "Props-driven React components and theme tokens inspired by classic interface design \u2014 optimized for Next.js apps and internal tools.",
+  "version": "0.9.0",
+  "description": "Props-driven React components and theme tokens inspired by classic interface design — optimized for Next.js apps and internal tools.",
   "author": "Xenide",
   "license": "MIT",
   "homepage": "https://github.com/xenide-io/the-old-ui-theme",
@@ -19,7 +19,7 @@
   ],
   "packageManager": "bun@1.3.5",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.9.0"
   },
   "sideEffects": [
     "*.css"
@@ -48,6 +48,12 @@
       "require": "./dist/suite.js",
       "default": "./dist/suite.mjs"
     },
+    "./theme-boot": {
+      "types": "./dist/theme-boot.d.ts",
+      "import": "./dist/theme-boot.mjs",
+      "require": "./dist/theme-boot.js",
+      "default": "./dist/theme-boot.mjs"
+    },
     "./tailwind-preset": {
       "types": "./dist/tailwind-preset.d.ts",
       "import": "./dist/tailwind-preset.mjs",
@@ -56,7 +62,9 @@
     }
   },
   "files": [
+    "docs",
     "dist",
+    "public/fonts",
     "scripts",
     "src/app/globals.css",
     "src/components/ui",
@@ -70,17 +78,18 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
-    "build:lib": "tsup --entry.index src/index.ts --entry.ui src/components/ui/index.ts --entry.suite src/suite/index.ts --entry.tailwind-preset tailwind-preset.ts --format cjs,esm --dts --external react,react-dom,next,iconoir-react,motion --clean --tsconfig ./tsconfig.lib.json",
+    "build:lib": "tsup --entry.index src/index.ts --entry.ui src/components/ui/index.ts --entry.suite src/suite/index.ts --entry.theme-boot src/suite/lib/theme-boot.ts --entry.tailwind-preset tailwind-preset.ts --format cjs,esm --dts --external react,react-dom,next,iconoir-react,motion --clean --tsconfig ./tsconfig.lib.json",
     "start": "next start",
-    "lint": "next lint",
+    "lint": "eslint .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:visual": "playwright test --project=desktop-chromium --workers=1 && playwright test --project=mobile-chromium --workers=1",
-    "check": "bun run typecheck && bun run test",
+    "check": "bun run typecheck && bun run lint && bun run test",
     "clean": "rm -rf .next out *.tsbuildinfo dist",
     "icons:check": "node scripts/sync-posthog-icons.mjs",
-    "prepublishOnly": "bun run build:lib",
-    "release": "bun run check && npm publish"
+    "package:smoke": "node scripts/package-smoke.mjs",
+    "prepublishOnly": "bun run build:lib && bun run package:smoke",
+    "release": "bun run check && bun run build && bun run build:lib && bun run package:smoke && npm publish"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -90,29 +99,21 @@
     "iconoir-react": ">=7.11.1",
     "motion": ">=12"
   },
-  "peerDependenciesMeta": {
-    "iconoir-react": {
-      "optional": true
-    },
-    "motion": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@playwright/test": "1.54.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.10.0",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.3",
-    "@types/d3-scale": "^4.0.9",
     "@types/node": "^20.19.43",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
     "autoprefixer": "^10.5.4",
+    "eslint": "^9.0.0",
+    "eslint-config-next": "^16.3.4",
     "iconoir-react": "^7.11.1",
-    "motion": "^12.43.0",
-    "d3-scale": "^4.0.2",
     "jsdom": "^26.1.0",
+    "motion": "^12.43.0",
     "next": "^16.3.0",
     "postcss": "^8.5.25",
     "react": "^18.3.1",
@@ -120,8 +121,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^3.2.7",
-    "typescript7": "npm:typescript@^7.0.2"
+    "typescript7": "npm:typescript@^7.0.2",
+    "vitest": "^3.2.7"
   },
   "publishConfig": {
     "access": "public"