@geomak/ui 7.18.5 → 7.20.0

package/.claude/commands/ui-auth-shell.md

@@ -0,0 +1,48 @@
+---
+description: Generate a complete authenticated app shell with SecureLayout, sidebar, routing, and optional Wizard tour
+---
+
+Generate an authenticated app shell for: **$ARGUMENTS**
+
+Parse the argument as `[AppName] [route1,route2,...]`. Examples:
+```
+VesOPS dashboard,vessels,settings,reports
+MyApp dashboard,users
+```
+
+AppName defaults to `App`. Routes default to `dashboard,settings`.
+
+## What this generates
+
+A single `AppRoutes.tsx` file (or updates an existing one) with:
+
+- `AppShell` with `TopBar` (brand + `ThemeSwitch`) and `sidebarSections`
+- `SecureLayout` parent route guarding all provided routes
+- Lazy-loaded placeholder pages for each route
+- `useRef` arrays + icon wrapper spans for a `Wizard` onboarding tour
+- A `Wizard` wrapping `AppShell` with `storageKey` based on the app name
+
+## Steps
+
+1. **Fetch the bootstrap code**: Call `get_app_bootstrap` with `router: true`
+   and the app name to get the reference implementation.
+
+2. **Call `get_component` for `secure-layout`** to confirm current prop names
+   (isAuthenticated, fallback, loadingFallback).
+
+3. **Generate `AppRoutes.tsx`** with:
+   - One `useRef<HTMLSpanElement>` per route for the Wizard tour
+   - `sidebarSections` array with one item per route; icon is a `<span ref={...}>` wrapping
+     an appropriate `<Icon.*>` (pick the most relevant icon per route name)
+   - `wizardSteps` array with title + description for each route
+   - `SecureLayout` wrapping all provided routes as child routes
+   - Each route uses `lazy(() => import('../pages/RouteNamePage'))` with a `Suspense` fallback
+   - `Wizard` wrapping `AppShell` with `steps={wizardSteps}` and `storageKey="{appName}-tour"`
+
+4. **Generate stub page files** for each route under `src/pages/` (e.g. `DashboardPage.tsx`)
+   if they do not already exist. Each stub is a minimal component with a heading.
+
+5. **Report** what was created and list:
+   - Which icons were guessed (developer may want to swap them)
+   - How to wire real authentication (what to replace the placeholder check with)
+   - How to add a route: duplicate an entry in `sidebarSections`, add a `useRef`, add a `wizardStep`, add a `<Route>`

package/.claude/commands/ui-bootstrap.md

@@ -0,0 +1,36 @@
+---
+description: Generate the full app bootstrap for a new project using OxygenUI
+---
+
+Bootstrap a new app using OxygenUI: **$ARGUMENTS**
+
+Parse the argument as an optional app name (e.g. `MyApp`, `VesOPS`). Defaults to `App`.
+
+## What this generates
+
+Four files that give a new project a working, production-ready shell:
+
+| File | Purpose |
+|---|---|
+| `src/main.tsx` | Entry point, mounts Bootstrap into the DOM |
+| `src/Bootstrap.tsx` | Full provider stack in the correct nesting order |
+| `src/approutes/AppRoutes.tsx` | AppShell + SecureLayout + lazy routes skeleton |
+| `src/utils/brandTokens.ts` | Token override object for custom branding |
+
+## Steps
+
+1. **Fetch the bootstrap code**: Call the `oxygen-ui` MCP tool `get_app_bootstrap`
+   with `router: true`, `reactQuery: true`, `customTheme: true`, and the app name.
+
+2. **Check what exists**: Before writing, check if any of the four target files
+   already exist. If they do, report the conflict and ask the user how to proceed
+   rather than overwriting.
+
+3. **Write the four files** with the content from the tool, substituting the app name
+   throughout (component names, display strings, localStorage keys).
+
+4. **Report** what was created and list the next steps:
+   - Add real routes to `AppRoutes.tsx`
+   - Wire real authentication (replace the `localStorage.getItem('token')` check)
+   - Populate `BRAND_TOKENS` if custom branding is needed
+   - Run `yarn add @tanstack/react-query react-router-dom` if not already installed

package/.claude/commands/ui-find.md

@@ -0,0 +1,12 @@
+---
+description: Search OxygenUI for components matching a description or use-case
+---
+
+Search OxygenUI for components that match: **$ARGUMENTS**
+
+1. Call the `oxygen-ui` MCP tool `find_component` with the argument as the query.
+2. Present the results as a concise table: **Name** · slug · category · description.
+3. For the top 1-2 results, briefly describe why they match and what the user
+   should look for in the docs (e.g. key props, integration patterns).
+4. If the search finds nothing, suggest alternative queries and offer to call
+   `list_components` to browse all available entries.

package/.claude/commands/ui-form.md

@@ -0,0 +1,38 @@
+---
+description: Generate a fully-wired OxygenUI Form from a field specification
+---
+
+Generate a wired OxygenUI form for: **$ARGUMENTS**
+
+Parse the argument as a space-separated list of `field-name:input-type` pairs.
+Append `?` to mark a field as optional (no required rule). Examples:
+
+```
+email:text name:text role:dropdown notify:switch terms:checkbox
+start:date end:date priority:slider tags:tags
+```
+
+Supported input types: `text`, `textarea`, `password`, `number`, `email`,
+`dropdown`, `switch`, `checkbox`, `radio`, `slider`, `date`, `daterange`,
+`time`, `tags`, `color`, `rating`, `autocomplete`, `treeselect`
+
+## Steps
+
+1. **Resolve binders**: For each field, call the `oxygen-ui` MCP tool
+   `get_form_binding` with the input type. This returns the correct binder
+   method, value type, and a paste-ready snippet.
+
+2. **Generate the form component**: Produce a self-contained React component:
+   - `useForm` with `defaultValues` typed to match each field
+   - One `FormField` per field with the correct binder
+   - Required rules on all non-optional (`?`) fields
+   - Email pattern rule if the type is `email`
+   - A submit `Button`
+   - `onFinish` stub with a `TODO` comment
+
+3. **Output inline**: Deliver the component as a code block. Do not write to a
+   file unless the user explicitly asks to save it.
+
+4. **Offer next steps**: After the form, suggest:
+   - Adding the form inside a Modal (`/ui-modal form-in-modal`)
+   - Making it part of a full page (`/ui-page crud EntityName`)

package/.claude/commands/ui-lookup.md

@@ -0,0 +1,13 @@
+---
+description: Look up a specific OxygenUI component, full props API and usage examples
+---
+
+Look up the OxygenUI component or hook: **$ARGUMENTS**
+
+1. Call the `oxygen-ui` MCP tool `get_component` with the appropriate slug.
+   If the slug is not obvious, call `find_component` first with the argument as
+   the query, then call `get_component` with the best-matching slug.
+2. Return the full documentation clearly formatted, props table, usage examples,
+   and any caveats or recipes that are relevant.
+3. If the component accepts children or sub-components (e.g. `Modal.Body`),
+   highlight the composition pattern.

package/.claude/commands/ui-modal.md

@@ -0,0 +1,50 @@
+---
+description: Generate the complete state + Modal setup for a named OxygenUI modal pattern
+---
+
+Generate a Modal pattern for: **$ARGUMENTS**
+
+Parse the argument as one of: `confirm-delete`, `form-in-modal`, `detail-view`, `alert`
+
+## Patterns
+
+### confirm-delete
+State + PopConfirm-style Modal for deleting a named item. Includes:
+- `open` + `target` state
+- `onDelete(item)` setter
+- `onConfirm` async handler with `useNotification` feedback
+- Full Modal JSX with cancel/confirm buttons
+
+### form-in-modal
+State + Modal containing a Form. Includes:
+- `open` + `selected` state (null = create, item = edit)
+- `openCreate` / `openEdit(item)` / `closeModal` helpers
+- `useEffect` to reset the form when `open` changes
+- Form with two example fields (developer fills in actual fields)
+- Modal with `onOk={form.submit}` wiring
+
+### detail-view
+Read-only Modal that displays a selected item's details. Includes:
+- `open` + `item` state
+- Trigger pattern
+- Modal with a descriptive layout (label/value pairs using Typography)
+
+### alert
+Simple informational Modal with a single confirm button and an optional icon.
+
+## Steps
+
+1. **Fetch component API**: Call `get_component` with slug `modal` to confirm
+   the current prop names (onClose vs onOpenChange may differ across versions).
+
+2. **Generate the pattern**: Produce the complete code block:
+   - State declarations (paste above the return statement)
+   - Helper functions
+   - The Modal JSX (paste into the render tree)
+   - Any supporting imports
+
+3. **Output inline** as a clearly labelled code block with sections:
+   `// --- STATE ---`, `// --- HANDLERS ---`, `// --- JSX ---`
+
+4. **Offer next steps**: Suggest wrapping the form-in-modal inside a full
+   CRUD page with `/ui-page crud EntityName`.

package/.claude/commands/ui-page.md

@@ -0,0 +1,36 @@
+---
+description: Scaffold a complete page component using OxygenUI patterns
+---
+
+Scaffold a complete page for: **$ARGUMENTS**
+
+Parse the argument as `<type> [EntityName]` where type is one of:
+`crud`, `dashboard`, `settings`, `detail`, `multi-step-form`
+
+EntityName is optional (e.g. `crud Vessel`, `detail Order`, `dashboard`).
+
+## Steps
+
+1. **Look up the pattern**: Call the `oxygen-ui` MCP tool `get_pattern` with the type
+   and entity name. This returns the full recipe: components needed, state to declare,
+   wiring steps, and a complete code example.
+
+2. **Resolve any unfamiliar props**: If the pattern uses a component whose API you are
+   not certain about, call `get_component` with the slug before writing code.
+
+3. **Determine the output path**
+   - Check if `src/pages/` exists; if not, check `src/views/` or `src/screens/`
+   - File name: `{EntityName}Page.tsx` (e.g. `VesselsPage.tsx`, `DashboardPage.tsx`)
+
+4. **Write the file**: Generate the complete, self-contained page component:
+   - TypeScript interface for the entity (if applicable)
+   - All imports from `@geomak/ui`
+   - All state declarations
+   - All event handlers wired up (create, edit, delete, save, etc.)
+   - Full JSX tree matching the pattern
+   - Replace all `api.*` calls with `TODO: replace with your API call`
+
+5. **Report** what was created and list:
+   - Which `api.*` calls need to be wired to real endpoints
+   - Which types/interfaces need to be expanded
+   - Any optional enhancements (e.g. "add Drawer instead of Modal for more context")

package/.claude/commands/ui-scaffold.md

@@ -0,0 +1,73 @@
+---
+description: Scaffold a new OxygenUI component, implementation + story + MDX guide
+---
+
+Scaffold a new OxygenUI component named: **$ARGUMENTS**
+
+Parse the argument as `ComponentName [category]` where category is optional
+(defaults to the most appropriate one based on the component name).
+
+## Steps
+
+1. **Plan**: Determine:
+   - Target directory: `src/components/{core|inputs|forms|layout|marketing}/`
+   - Story title: `"Category/ComponentName"`
+   - Whether the component wraps a Radix primitive or is fully custom
+
+2. **Check for overlap**, Call `find_component` to confirm no existing component
+   already covers this use case before creating anything.
+
+3. **Scaffold files**: Create the following three files:
+
+### `ComponentName.tsx`
+
+```tsx
+import React from 'react'
+
+export interface ComponentNameProps {
+  // props here
+  className?: string
+}
+
+export function ComponentName({ className, ...props }: ComponentNameProps) {
+  return (
+    <div className={className}>
+      {/* implementation */}
+    </div>
+  )
+}
+
+export default ComponentName
+```
+
+### `ComponentName.stories.tsx`
+
+```tsx
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import ComponentName from './ComponentName'
+
+const meta: Meta<typeof ComponentName> = {
+  title: 'Category/ComponentName',
+  component: ComponentName,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+}
+export default meta
+type Story = StoryObj<typeof ComponentName>
+
+export const Default: Story = {
+  args: {},
+}
+```
+
+### `src/docs/ComponentName.mdx`
+
+Use the MDX guide structure with HTML tables (not GFM markdown tables).
+Use the exported `th / td / td0 / tbl` style constants from Accordion.mdx as a template.
+
+4. **Export**, Add the new component to `src/index.ts` in the correct section
+   (Core components, Input components, etc.).
+
+5. **Report** what was created and what the developer should fill in next
+   (implementation logic, additional stories, tests).

package/.claude/commands/ui-story.md

@@ -0,0 +1,30 @@
+---
+description: Add or improve Storybook stories for an existing OxygenUI component
+---
+
+Add or improve Storybook stories for the OxygenUI component: **$ARGUMENTS**
+
+## Steps
+
+1. **Read the component**: Find and read:
+   - The component source file (`src/components/**/$ARGUMENTS.tsx` or similar)
+   - The existing story file if one exists
+   - The MDX guide if one exists in `src/docs/`
+
+2. **Identify gaps**: Look for:
+   - Props that have no story coverage
+   - State combinations (loading, error, empty, disabled)
+   - Controlled vs uncontrolled usage
+   - Composition patterns (compound components with sub-components)
+   - Responsive or theme-sensitive behaviour
+
+3. **Write stories** following the CSF3 format used throughout the codebase:
+   - `Default`: the simplest working example with sensible args
+   - One story per major variant or visual state
+   - Use `render` functions for complex compositions
+   - Use `play` functions only when testing interactions (focus, type, click)
+   - Prefer realistic content that reflects actual usage in the VesOPS portal
+
+4. **Verify** that story `title` matches the existing Storybook sidebar path.
+
+5. **Report** which stories were added and what each one demonstrates.

package/.claude/commands/ui-table.md

@@ -0,0 +1,38 @@
+---
+description: Generate a typed OxygenUI Table component with columns, actions, and optional CRUD wiring
+---
+
+Generate a typed Table for: **$ARGUMENTS**
+
+Parse the argument as `EntityName [col:type ...]`. Column type hints are optional.
+Examples:
+
+```
+Vessel name:string flag:string dwt:number status:badge actions:menu
+Order id:number customer:string total:number status:badge
+User
+```
+
+Column types: `string`, `number`, `boolean`, `badge`, `date`, `link`, `menu`
+- `badge` renders a `<Badge>` with tone based on the value
+- `menu` adds an actions column with Edit and Delete buttons + PopConfirm on delete
+- Any unlisted type defaults to a plain text renderer
+
+## Steps
+
+1. **Fetch Table API**: Call `get_component` with slug `table` to confirm the
+   exact `TableColumn<T>` shape and any props that have changed.
+
+2. **Generate the component**: Produce:
+   - TypeScript interface for the entity with all specified columns
+   - `TableColumn<Entity>[]` array with correct renderers for typed columns
+   - For `badge` columns: a `<Badge>` renderer with a sensible tone map
+   - For `menu` columns: Edit button + PopConfirm-wrapped Delete button, wired to
+     `onEdit` and `onDelete` callback props
+   - Table component with `hasSearch`, `pagination`, and `getRowKey={r => r.id}`
+
+3. **Output inline** as a complete, importable component.
+
+4. **Offer extensions**: After the output, offer to:
+   - Add a create/edit Modal + Form (`/ui-modal form-in-modal` or `/ui-page crud EntityName`)
+   - Wrap it in a full CRUD page (`/ui-page crud EntityName`)