@geomak/ui 7.18.5 → 7.20.0

package/.claude/skills/oxygen-ui/SKILL.md

@@ -0,0 +1,402 @@
+---
+name: oxygen-ui
+description: >
+  Context skill for working with the OxygenUI (@geomak/ui) design system.
+  Equips Claude Code with knowledge about available components, tokens, import
+  patterns, and how to use the MCP server for real-time docs lookup.
+---
+
+# OxygenUI Design System
+
+You are working inside the `@geomak/ui` repository, a React component library
+built with Radix UI primitives, Tailwind CSS utilities, and a three-layer token
+system. Everything ships as tree-shakeable ESM.
+
+---
+
+## MCP server
+
+An `oxygen-ui` MCP server is configured in `.mcp.json`. Use its tools whenever
+you need to look up component APIs, prop tables, or design tokens.
+
+| Tool | When to call |
+|---|---|
+| `find_component` | Before writing any UI, check what the design system already has |
+| `get_component` | Get full props + examples for a specific component (use the slug) |
+| `list_components` | Browse all 100+ entries when unsure what exists |
+| `get_token` | Look up CSS custom properties by name or category prefix |
+| `get_pattern` | Get a full wired recipe for a page-level pattern (crud-list, dashboard, etc.) |
+| `get_form_binding` | Look up the correct `useForm` binder for any input component |
+| `compare_components` | Get a decision guide when choosing between similar components |
+| `get_app_bootstrap` | Get the full provider stack + app shell bootstrap code |
+
+**Always call `find_component` first.** OxygenUI ships 100+ components. Writing
+from scratch without checking is almost always redundant.
+
+---
+
+## Import pattern
+
+```tsx
+// Named imports from the main entry (tree-shakeable)
+import { Button, Modal, DataGrid, useExcel } from '@geomak/ui'
+
+// Styles: include once at app root
+import '@geomak/ui/styles'
+
+// Token values for JS/TS code
+import { vars, semanticTokens, palette } from '@geomak/ui/tokens'
+
+// Icons
+import { Icon } from '@geomak/ui'
+<Icon.Search size={20} />
+```
+
+---
+
+## Token system
+
+Three layers:
+
+| Layer | Use case |
+|---|---|
+| `palette` | Raw brand hex values |
+| `semanticTokens` | Resolved hex/px values in `{ light, dark, shared }` objects |
+| `vars` | CSS custom-property strings: `vars.color.accent`, `vars.radius.md` |
+
+### CSS custom properties (use in inline styles or SCSS)
+
+```tsx
+<div style={{
+  background: 'var(--color-surface)',
+  border: '1px solid var(--color-border)',
+  borderRadius: 'var(--radius-md)',
+  color: 'var(--color-foreground)',
+}}>
+```
+
+### Tailwind utilities
+
+| Utility | Token |
+|---|---|
+| `bg-surface` | `--color-surface` |
+| `bg-surface-raised` | `--color-surface-raised` |
+| `border-border` | `--color-border` |
+| `text-foreground` | `--color-foreground` |
+| `text-foreground-muted` | `--color-foreground-muted` |
+| `bg-accent` | `--color-accent` |
+| `text-accent-fg` | `--color-accent-foreground` |
+
+---
+
+## Form binder cheat sheet
+
+**This is the most common source of silent bugs.** Every `useForm` field must use
+the correct binder for its input type or values will not update.
+
+| Input component | Binder method | Value type stored |
+|---|---|---|
+| `TextInput`, `TextArea`, `Password`, `SearchInput` | `fieldNative` | `string` |
+| `NumberInput` | `fieldNative` | `number` |
+| `Switch`, `Checkbox` | `fieldChecked` | `boolean` |
+| `Dropdown`, `TreeSelect`, `AutoComplete` | `fieldTarget` | `key` or `key[]` |
+| `RadioGroup` | `field` | option value |
+| `Slider` | `field` | `number` or `[number, number]` |
+| `DatePicker`, `TimePicker` | `field` | `Date \| null` |
+| `DateRangePicker` | `field` | `{ from: Date; to: Date } \| null` |
+| `TagsInput` | `field` | `string[]` |
+| `ColorPicker` | `field` | `string` (hex) |
+| `Rating` | `field` | `number` |
+
+```tsx
+// Example: mixed form with correct binders
+const form = useForm({ defaultValues: { name: '', role: '', active: false, joined: null } })
+
+<Form form={form} onFinish={handleSubmit}>
+  <FormField name="name"><TextInput label="Name" {...form.fieldNative('name')} /></FormField>
+  <FormField name="role"><Dropdown label="Role" items={roles} {...form.fieldTarget('role')} /></FormField>
+  <FormField name="active"><Switch label="Active" {...form.fieldChecked('active')} /></FormField>
+  <FormField name="joined"><DatePicker label="Joined" {...form.field('joined')} /></FormField>
+</Form>
+```
+
+Call `get_form_binding` MCP tool when unsure which binder to use for a specific input.
+
+---
+
+## Component decision guide
+
+### Modal vs Drawer vs PopConfirm
+
+| Component | Use when |
+|---|---|
+| `Modal` | The action needs full attention; no background context helps (confirm, form submit) |
+| `Drawer` | User benefits from seeing the page behind (filter panel, row inspector, quick edit) |
+| `PopConfirm` | Inline destructive confirmation on a specific row/button; no overlay needed |
+
+Both Modal and Drawer share the same controlled API: `open` + `onClose` + `hasFooter` + `onOk` + `onCancel`.
+
+### Table vs DataGrid vs VirtualList vs List
+
+| Component | Use when |
+|---|---|
+| `Table` | Standard paginated, sortable, searchable data; editable cells optional |
+| `DataGrid` | Excel-like: column reorder/resize, bulk edits, copy-paste cell behaviour |
+| `VirtualList` | 10k+ rows where DOM count is the bottleneck; no built-in sort/filter |
+| List (custom) | Single-column items, icon + label, no comparison between columns |
+
+### Tabs vs SegmentedControl
+
+| Component | Use when |
+|---|---|
+| `Tabs` | Three or more sibling content panes; content is substantial |
+| `SegmentedControl` | Two to four compact mutually exclusive filter-style options |
+
+---
+
+## App bootstrap (provider nesting order)
+
+This order is required. Getting it wrong causes token overrides, notification
+portals, or dark mode to break silently.
+
+```tsx
+// main.tsx or Bootstrap.tsx
+import { ThemeProvider, NotificationProvider } from '@geomak/ui'
+import { QueryClientProvider, QueryClient } from '@tanstack/react-query'
+import { BrowserRouter } from 'react-router-dom'
+
+const queryClient = new QueryClient()
+
+export function Bootstrap() {
+  return (
+    <ThemeProvider colorScheme={colorScheme}>        {/* always outermost */}
+      <BrowserRouter>
+        <QueryClientProvider client={queryClient}>
+          <NotificationProvider>                     {/* must be inside ThemeProvider */}
+            <AppRoutes />
+          </NotificationProvider>
+        </QueryClientProvider>
+      </BrowserRouter>
+    </ThemeProvider>
+  )
+}
+```
+
+Dark mode toggle: maintain `colorScheme` state in Bootstrap, pass it to `ThemeProvider`,
+and also toggle `document.documentElement.classList.toggle('dark', isDark)` so that
+Tailwind dark utilities work inside portals that render outside the ThemeProvider div.
+
+Custom brand tokens (optional):
+
+```tsx
+const BRAND_TOKENS = {
+  '--color-accent': '#1A56DB',
+  '--color-accent-hover': '#1e429f',
+}
+
+<ThemeProvider colorScheme={colorScheme} theme={BRAND_TOKENS} darkTheme={BRAND_TOKENS}>
+```
+
+---
+
+## useNotification
+
+Must be used inside a component that is a descendant of `NotificationProvider`.
+
+```tsx
+import { useNotification } from '@geomak/ui'
+
+function MyPage() {
+  const notification = useNotification()
+
+  const onSave = async () => {
+    try {
+      await api.save(data)
+      notification.success({ title: 'Saved', description: 'Changes applied.', duration: 3000 })
+    } catch (err) {
+      notification.error({ title: 'Save failed', description: err.message, duration: 5000 })
+    }
+  }
+}
+```
+
+Methods: `notification.success`, `notification.info`, `notification.warning`, `notification.error`.
+All accept `{ title, description?, duration? }`.
+
+---
+
+## React Query integration
+
+Map React Query state to OxygenUI component props:
+
+```tsx
+const { data, isPending, isFetching, isError, refetch } = useQuery({ queryKey, queryFn })
+
+// First load: full skeleton
+if (isPending) return <SkeletonBox className="h-96 w-full" />
+
+// Error state
+if (isError) return <ErrorState onRetry={refetch} />
+
+// Background refetch: show spinner overlay on existing content (not a full skeleton)
+// isPending=false, isFetching=true means data is already on screen
+return (
+  <Table
+    data={data}
+    loading={isFetching && !isPending}  // subtle refetch indicator
+    columns={columns}
+  />
+)
+```
+
+For mutations:
+
+```tsx
+const mutation = useMutation({
+  mutationFn: api.create,
+  onSuccess: () => {
+    notification.success({ title: 'Created' })
+    queryClient.invalidateQueries({ queryKey })
+  },
+  onError: (err) => notification.error({ title: 'Failed', description: err.message }),
+})
+
+<Button loading={mutation.isPending} onClick={() => mutation.mutate(formData)}>
+  Save
+</Button>
+```
+
+---
+
+## SecureLayout + route guard pattern
+
+```tsx
+// AppRoutes.tsx
+import { AppShell, SecureLayout } from '@geomak/ui'
+import { Routes, Route, Navigate } from 'react-router-dom'
+
+function AppRoutes() {
+  return (
+    <AppShell topBar={<TopBar />} sidebarSections={sidebarSections}>
+      <Routes>
+        {/* Auth-gated routes: wrap parent Route with SecureLayout */}
+        <Route
+          element={
+            <SecureLayout
+              isAuthenticated={isAuthenticated}
+              fallback={<Navigate to="/login" replace />}
+              loadingFallback={null}
+            />
+          }
+        >
+          <Route path="/dashboard" element={<DashboardPage />} />
+          <Route path="/settings" element={<SettingsPage />} />
+        </Route>
+
+        <Route path="/login" element={<LoginPage />} />
+        <Route path="/" element={<Navigate to="/dashboard" replace />} />
+      </Routes>
+    </AppShell>
+  )
+}
+```
+
+---
+
+## Wizard + AppShell onboarding tour
+
+Wizard must WRAP AppShell (not be inside it) so it can overlay the full viewport.
+Refs for Wizard steps go on wrapper `<span>` elements inside the `icon` prop of each
+`SidebarItem`, because `SidebarItem` has no `ref` prop.
+
+```tsx
+const dashboardRef = useRef<HTMLSpanElement>(null)
+const settingsRef  = useRef<HTMLSpanElement>(null)
+
+const sidebarSections = [{
+  items: [
+    {
+      label: 'Dashboard',
+      href: '/dashboard',
+      icon: <span ref={dashboardRef}><Icon.Home size={18} /></span>,
+    },
+    {
+      label: 'Settings',
+      href: '/settings',
+      icon: <span ref={settingsRef}><Icon.Settings size={18} /></span>,
+    },
+  ],
+}]
+
+const wizardSteps = [
+  { target: dashboardRef, title: 'Dashboard', description: 'Your overview at a glance.' },
+  { target: settingsRef,  title: 'Settings',  description: 'Configure your preferences.' },
+]
+
+<Wizard steps={wizardSteps} storageKey="my-app-tour">
+  <AppShell topBar={...} sidebarSections={sidebarSections}>
+    <Routes>...</Routes>
+  </AppShell>
+</Wizard>
+```
+
+---
+
+## Page patterns reference
+
+| Pattern | Key components |
+|---|---|
+| **CRUD list** | Table + Modal (create/edit) + Form + useForm + PopConfirm + useNotification |
+| **Dashboard overview** | Statistic cards + Skeleton + Dropdown (filter) + optional chart cards |
+| **Settings / admin tabs** | Tabs + Form per panel + Switch/Dropdown + useNotification on save |
+| **Multi-step wizard form** | Stepper + Form (per step or sectioned) + validation before advancing |
+| **Detail / inspection page** | Tabs + Statistic + Timeline + Drawer (row inspector) + Badge |
+| **Authenticated app shell** | ThemeProvider + NotificationProvider + AppShell + SecureLayout + Wizard tour |
+
+Use `get_pattern` MCP tool for the full wired recipe (components + state + wiring steps + code example) for any of these.
+
+---
+
+## Key component patterns
+
+### ThemeProvider (required at app root)
+
+```tsx
+import { ThemeProvider } from '@geomak/ui'
+
+<ThemeProvider defaultTheme="system">
+  <App />
+</ThemeProvider>
+```
+
+### Modal
+
+```tsx
+import { Modal } from '@geomak/ui'
+
+const [open, setOpen] = useState(false)
+
+<Modal open={open} onClose={() => setOpen(false)} title="Confirm" onOk={handleOk}>
+  <p>Are you sure?</p>
+</Modal>
+```
+
+---
+
+## Storybook
+
+Stories live in `src/**/*.stories.tsx` (CSF3 format). The Storybook dev server
+is in `.claude/launch.json` as `"storybook"` (port 6006).
+
+Guide MDX files live in `src/docs/` (one per component).
+
+---
+
+## Repository conventions
+
+- Component source: `src/components/{core,inputs,forms,layout,marketing}/`
+- Hooks: `src/hooks/`
+- Story title format: `"Category/ComponentName"` or `"Category/ComponentName/Guide"`
+- All MDX guides use HTML tables (not GFM) with exported `th/td/td0/tbl` style constants
+- Commit convention: `fix:` (patch), `feat:` (minor), `docs:` (no bump); semantic-release runs in CI
+- Never bump `version` in `package.json` manually

package/README.md

@@ -4,7 +4,7 @@
 
 # @geomak/ui · Oxygen Design System
 
-**100+ production-grade React components for enterprise apps** — dashboards, CRMs, internal tools, and landing pages. Token-driven, accessible, light/dark first-class, and properly tree-shakeable.
+**100+ production-grade React components for enterprise apps**, dashboards, CRMs, internal tools, and landing pages. Token-driven, accessible, light/dark first-class, and properly tree-shakeable.
 
 [![npm version](https://img.shields.io/npm/v/@geomak/ui?color=0466c8&label=npm)](https://www.npmjs.com/package/@geomak/ui)
 [![types](https://img.shields.io/npm/types/@geomak/ui?color=0466c8)](https://www.npmjs.com/package/@geomak/ui)
@@ -14,7 +14,7 @@
 
 ### ▶ [Browse the live, interactive demo →](https://oxygenui.com)
 
-<!-- Tip: drop a Storybook screen-recording here for the launch — docs/assets/preview.gif -->
+<!-- Tip: drop a Storybook screen-recording here for the launch, docs/assets/preview.gif -->
 
 </div>
 
@@ -24,11 +24,11 @@ Built on **React 19**, **Radix UI** (accessibility + behaviour), **Tailwind CSS*
 
 ## Why oxygen-ui
 
-- **Token-driven, dark mode first-class.** Every colour, radius, shadow, and motion value is a CSS variable. Light and dark aren't an afterthought — both are designed. Re-theme the whole system with one override.
+- **Token-driven, dark mode first-class.** Every colour, radius, shadow, and motion value is a CSS variable. Light and dark aren't an afterthought, both are designed. Re-theme the whole system with one override.
 - **Accessible by default.** Behaviour comes from Radix (focus traps, keyboard nav, ARIA); icons are `aria-hidden`, controls are labelled.
-- **Genuinely tree-shakeable.** Import one icon and ship **0.45 KB** (not the whole set). The entire library is **~76 KB gzipped** with deps external — and a CI guard keeps it from regressing.
+- **Genuinely tree-shakeable.** Import one icon and ship **0.45 KB** (not the whole set). The entire library is **~76 KB gzipped** with deps external, and a CI guard keeps it from regressing.
 - **Strict and tested.** `strict` TypeScript, ESLint at zero warnings, 360+ unit tests, per-export bundle budgets in CI.
-- **Batteries included.** Not just buttons — a `Scheduler`, a real-time `Chat` (WebSocket-ready), `Table` with pagination, a `Form` engine, an e-commerce `Cart`, and a full **Marketing** kit (hero, pricing, testimonials, lead capture) to build the landing page too.
+- **Batteries included.** Not just buttons, a `Scheduler`, a real-time `Chat` (WebSocket-ready), `Table` with pagination, a `Form` engine, an e-commerce `Cart`, and a full **Marketing** kit (hero, pricing, testimonials, lead capture) to build the landing page too.
 
 ---
 
@@ -64,7 +64,7 @@ import { ChevronDown, Search, createIcon } from '@geomak/ui/icons'
 
 ## Components
 
-100+ components across these groups — all with **live controls and a written guide** in [Storybook](https://oxygenui.com).
+100+ components across these groups, all with **live controls and a written guide** in [Storybook](https://oxygenui.com).
 
 | Group | Components |
 |---|---|
@@ -137,53 +137,93 @@ The standard **gray / slate / zinc** ramps and **black** stay available alongsid
 
 ## AI toolchain (Claude Code)
 
-OxygenUI ships a built-in MCP server and a set of Claude Code skills and commands that let AI assistants look up component APIs, search by use-case, and scaffold new components — all grounded in the real MDX documentation.
+OxygenUI ships a built-in MCP server and a set of Claude Code skills and commands that let AI assistants look up component APIs, search by use-case, generate complete page components, and bootstrap entire apps, all grounded in the real MDX documentation.
+
+### Setup
+
+The toolchain has two parts: the **MCP server** (does the work) and the **commands + skill** (how you call it from Claude Code). Both can be installed at user scope (available in every project on your machine) or project scope (committed to the repo, shared with the whole team).
+
+#### Option A — User scope (recommended for individuals)
+
+Installs everything into `~/.claude/`. Available in every Claude Code session from that point on.
+
+```bash
+# 1. Install commands + skill + MCP server config in one shot
+npx --package=@geomak/ui@latest setup-claude
+
+# If you already have @geomak/ui installed locally:
+node node_modules/@geomak/ui/scripts/setup-claude.mjs
+```
+
+#### Option B — Project scope (recommended for teams)
+
+Commits the toolchain into the repo so every developer who clones it gets it automatically.
+
+```bash
+# 1. Install commands + skill + .mcp.json into the project directory
+npx --package=@geomak/ui@latest setup-claude --scope project
+
+# If you already have @geomak/ui installed locally:
+node node_modules/@geomak/ui/scripts/setup-claude.mjs --scope project
+
+# 2. Commit the generated files so your team gets them on clone
+git add .claude/ .mcp.json
+git commit -m "chore: add OxygenUI Claude Code toolchain"
+```
+
+Both options write a `.mcp.json` / `~/.claude/mcp.json` entry pointing to `https://oxygenui.com/mcp` alongside the commands and skill, so no manual config is needed. Restart Claude Code (or reload the MCP server list) after running.
+
+---
 
 ### MCP server
 
-The server is deployed alongside Storybook on Netlify as a Netlify Function at `/mcp`. It exposes four tools:
+The server is deployed alongside Storybook at `https://oxygenui.com/mcp` (Netlify Function). It exposes eight tools in two tiers.
+
+**Lookup tier** (docs + tokens):
 
 | Tool | What it does |
 |---|---|
 | `list_components` | Browse all 100+ components with slug, category, and description |
-| `get_component` | Fetch the full props API and usage examples for one component by slug |
+| `get_component` | Full props API and usage examples for one component by slug |
 | `find_component` | Keyword search across names, categories, and descriptions |
 | `get_token` | Look up CSS custom properties by name or category prefix |
 
-**Connect it:**
-
-```jsonc
-// .mcp.json (already in the repo — update the URL after first deploy)
-{
-  "mcpServers": {
-    "oxygen-ui": {
-      "type": "http",
-      "url": "https://your-site.netlify.app/mcp"
-    },
-    "oxygen-ui-local": {
-      "type": "http",
-      "url": "http://localhost:8888/mcp"
-    }
-  }
-}
-```
+**Generation tier** (patterns + code):
 
-Or add it from the CLI: `claude mcp add oxygen-ui --transport http https://your-site.netlify.app/mcp`
+| Tool | What it does |
+|---|---|
+| `get_pattern` | Full wired recipe for a page type: components, state, wiring steps, and a complete code example. Patterns: `crud-list`, `dashboard`, `settings-tabs`, `multi-step-form`, `detail-page`, `app-bootstrap` |
+| `get_form_binding` | Correct `useForm` binder for any input (`fieldNative` / `fieldChecked` / `fieldTarget` / `field`), with paste-ready snippet |
+| `compare_components` | Decision guide for similar components: Modal vs Drawer, Table vs DataGrid, Tabs vs SegmentedControl |
+| `get_app_bootstrap` | Full Bootstrap.tsx + AppRoutes.tsx + brandTokens.ts template for a new project |
 
 ### Claude Code commands
 
-Four slash commands are registered in `.claude/commands/`:
+Eight slash commands are available after setup:
+
+**Lookup commands:**
 
 | Command | Usage |
 |---|---|
-| `/ui-lookup <name>` | Fetch the full docs for a component — e.g. `/ui-lookup wizard` |
-| `/ui-find <query>` | Search by use-case — e.g. `/ui-find virtualized table` |
-| `/ui-scaffold <name>` | Scaffold a new component with source + story + MDX guide |
-| `/ui-story <name>` | Add story coverage for an existing component |
+| `/ui-find <query>` | Search by use-case, e.g. `/ui-find virtualized table` |
+| `/ui-lookup <name>` | Full docs for a component, e.g. `/ui-lookup wizard` |
+
+**Generation commands** (write real files into your project):
+
+| Command | Usage |
+|---|---|
+| `/ui-page <type> [entity]` | Scaffold a complete page file. Types: `crud`, `dashboard`, `settings`, `detail`, `multi-step-form`. Example: `/ui-page crud Vessel` |
+| `/ui-bootstrap [name]` | Generate the four-file app bootstrap (Bootstrap.tsx, AppRoutes.tsx, brandTokens.ts, main.tsx) |
+| `/ui-form <field:type ...>` | Generate a fully-wired Form from a field spec, e.g. `/ui-form name:text role:dropdown active:switch` |
+| `/ui-table <entity> [col:type]` | Typed Table with column renderers + actions, e.g. `/ui-table Vessel name:string flag:string status:badge actions:menu` |
+| `/ui-modal <type>` | Complete state + Modal JSX. Types: `confirm-delete`, `form-in-modal`, `detail-view`, `alert` |
+| `/ui-auth-shell [name] [routes]` | Full SecureLayout + AppShell + Wizard tour shell, e.g. `/ui-auth-shell VesOPS dashboard,vessels,settings` |
+
+Two additional library commands (`/ui-scaffold`, `/ui-story`) are available inside the `oxygen-ui` repository itself for contributors.
 
 ### Context skill
 
-The `/oxygen-ui` skill loads the full design system context into any Claude Code session — import patterns, token usage, Tailwind utilities, form API, and repository conventions. Invoke it at the start of any session where you plan to build against `@geomak/ui`.
+The `/oxygen-ui` skill (installed by the setup script) loads the full design system context into any Claude Code session: import patterns, form binder cheat sheet, component decision guide, provider nesting order, React Query integration, and page pattern reference. Invoke it at the start of any session where you plan to build against `@geomak/ui`.
 
 ### Local development with the MCP server
 
@@ -196,7 +236,7 @@ The function is then available at `http://localhost:8888/mcp`. Claude Code picks
 
 ### How the manifest is built
 
-At build time, `scripts/generate-ai-manifest.mjs` scans all 101 MDX guide files in `src/docs/` and the co-located MDX files in `src/components/`, strips Storybook boilerplate, and emits `netlify/functions/ai-manifest.json`. The Netlify Function bundles this JSON via esbuild — no database, no runtime file I/O, no cold-start penalty.
+At build time, `scripts/generate-ai-manifest.mjs` scans all MDX guide files in `src/docs/` and co-located MDX files in `src/components/`, strips Storybook boilerplate, and emits `netlify/_data/ai-manifest.js`. The Netlify Function bundles this via esbuild at deploy time. No database, no runtime file I/O, no cold-start penalty.
 
 ---
 

package/dist/{chunk-4V4U2W7K.cjs → chunk-4WD27VQX.cjs}

@@ -385,5 +385,5 @@ exports.X = X;
 exports.XCircle = XCircle;
 exports.createIcon = createIcon;
 exports.icons_default = icons_default;
-//# sourceMappingURL=chunk-4V4U2W7K.cjs.map
-//# sourceMappingURL=chunk-4V4U2W7K.cjs.map
+//# sourceMappingURL=chunk-4WD27VQX.cjs.map
+//# sourceMappingURL=chunk-4WD27VQX.cjs.map