@skunkworksai/ui-kit 0.1.18

package/rules/header.md

@@ -0,0 +1,245 @@
+# AppHeader
+
+## When to use
+
+`AppHeader` is the top-of-page bar. It is rendered automatically inside `AppDashboard` — you do not need to import or use it directly unless you are building a layout outside `AppDashboard`.
+
+To customise the header inside `AppDashboard`, pass props via the `header` prop on `AppDashboard`. See `rules/dashboard.md`.
+
+## Default layout
+
+```
+AppSidebarTrigger → separator → searchbar → [network combobox] [bell] [bento] [theme toggle] [avatar]
+```
+
+All right-side controls are included by default. Each can be removed or replaced via props.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `searchbar` | `ReactNode` | standard search input | Searchbar slot. Pass `<AppInput />` to customise. `null` removes it entirely. |
+| `actions` | `ReactNode` | network combobox + bento + theme toggle + avatar | Entire right-side slot. `null` removes all actions. Overrides all other action props. |
+| `avatar` | `ReactNode` | `AppAvatar` with fallback `"KA"` | Avatar inside default actions. `null` hides it. Ignored when `actions` is provided. |
+| `networkSelect` | `ReactNode` | `AppHeaderNetworkCombobox` | Network picker inside default actions. `null` hides it. Pass a custom node to override. Ignored when `actions` is provided. |
+| `networks` | `NetworkOption[]` | 2 demo entries | List of networks for the built-in combobox. Ignored when `networkSelect` or `actions` is provided. |
+| `currentNetwork` | `string` | first network in list | Controlled selected network. Omit for uncontrolled. Ignored when `networkSelect` or `actions` is provided. |
+| `onNetworkChange` | `(value: string) => void` | — | Called when user selects a network. Ignored when `networkSelect` or `actions` is provided. |
+| `showThemeToggle` | `boolean` | `true` | Show/hide theme toggle in default actions. Ignored when `actions` is provided. |
+| `showBento` | `boolean` | `true` | Show/hide bento icon button in default actions. Ignored when `actions` is provided. |
+| `bentoApps` | `BentoApp[]` | MeldCX apps | Apps shown in bento dropdown. Ignored when `actions` is provided or `showBento` is false. |
+| `bentoCols` | `number` | `2` | Grid column count inside the bento dropdown. Use `3` for 5+ apps to avoid asymmetric rows. Ignored when `actions` is provided or `showBento` is false. |
+| `showNotifications` | `boolean` | `true` | Show/hide the notifications bell in default actions. Ignored when `actions` is provided. |
+| `notifications` | `AppNotification[]` | `[]` | Notification items for the bell panel. Ignored when `actions` or `notificationsMenu` is provided. |
+| `notificationsTotal` | `number` | — | Total server count for the Show More footer. |
+| `onShowMoreNotifications` | `() => void` | — | Called when Show More is clicked in the notifications panel. |
+| `onMarkAllNotificationsRead` | `() => void` | — | Called when Mark all as read is selected. |
+| `notificationsMenu` | `ReactNode` | — | Replace the entire bell+panel with a custom node. Pass `null` to hide. |
+| `profile` | `AppProfileUser` | — | User data for the avatar profile popover (name, role, initials, optional image). When set, replaces the plain avatar with an interactive `AppProfile`. Ignored when `avatar` or `actions` is provided. |
+| `onSettings` | `() => void` | — | Called when Settings is clicked in the profile menu. |
+| `onAdministrator` | `() => void` | — | Called when Administrator is clicked in the profile menu. |
+| `onLogout` | `() => void` | — | Called when Log Out is clicked in the profile menu. |
+| `profileMenu` | `ReactNode` | — | Replace the entire profile popover with a custom node. Ignored when `avatar` or `actions` is provided. |
+
+**Slot resolution rule:** `undefined` = use default content. `null` = remove entirely. Any other node = override.
+
+### AppProfileUser type
+
+```ts
+type AppProfileUser = {
+  name: string          // required — full display name
+  role?: string         // subtitle below name
+  avatarSrc?: string    // image URL
+  avatarFallback?: string // initials override; derived from name when omitted
+}
+```
+
+## Network combobox
+
+The built-in network picker (`AppHeaderNetworkCombobox`) is a searchable combobox:
+
+- Current network pinned at the top of the list
+- Remaining networks sorted A–Z by label
+- Shows **5** networks initially; "See N more..." button expands to the full scrollable list
+- Search filters all networks (not just the initial 5); bypasses the initial limit
+- Closing the popover resets to the collapsed 5-item view
+
+### NetworkOption type
+
+```ts
+type NetworkOption = { value: string; label: string }
+```
+
+### Controlled usage
+
+```tsx
+const [network, setNetwork] = React.useState("meldcx")
+
+<AppHeader
+  networks={networks}
+  currentNetwork={network}
+  onNetworkChange={setNetwork}
+/>
+```
+
+### Uncontrolled usage (no onChange needed)
+
+```tsx
+<AppHeader networks={networks} />
+```
+
+### Custom network picker (override slot)
+
+```tsx
+<AppHeader networkSelect={<MyCustomPicker />} />
+```
+
+### Hide network picker
+
+```tsx
+<AppHeader networkSelect={null} />
+```
+
+## Sub-components (advanced layouts only)
+
+Use these only when building a layout outside `AppDashboard`:
+
+| Component | Purpose |
+|-----------|---------|
+| `AppHeaderContent` | Inner flex container with padding and gap. |
+| `AppHeaderTitle` | Optional page label. `shrink-0`, never compresses. |
+| `AppHeaderSearchbar` | `flex-1` slot for search input groups. |
+| `AppHeaderActions` | `ml-auto` right-side slot for controls. |
+| `AppHeaderNetworkCombobox` | Standalone network combobox — use inside a custom `actions` slot. |
+
+## Usage inside AppDashboard (standard)
+
+Customize via the `header` prop — never import `AppHeader` directly for this:
+
+```tsx
+// Default (no header prop needed)
+<AppDashboard>...</AppDashboard>
+
+// With network list
+<AppDashboard header={{ networks: myNetworks, currentNetwork: selected, onNetworkChange: setSelected }}>
+  ...
+</AppDashboard>
+
+// Remove searchbar
+<AppDashboard header={{ searchbar: null }}>...</AppDashboard>
+
+// Remove avatar
+<AppDashboard header={{ avatar: null }}>...</AppDashboard>
+
+// Remove network select
+<AppDashboard header={{ networkSelect: null }}>...</AppDashboard>
+
+// Hide theme toggle and bento
+<AppDashboard header={{ showThemeToggle: false, showBento: false }}>...</AppDashboard>
+
+// Custom right-side actions
+<AppDashboard header={{ actions: <AppButton>Save</AppButton> }}>...</AppDashboard>
+
+// Profile popover (avatar becomes interactive)
+<AppDashboard
+  header={{
+    profile: { name: "Joshua Intern", role: "Admin" },
+    onSettings: handleSettings,
+    onAdministrator: handleAdministrator,
+    onLogout: handleLogout,
+  }}
+>...</AppDashboard>
+
+// Profile with avatar image
+<AppDashboard
+  header={{
+    profile: { name: "Joshua Intern", role: "Admin", avatarSrc: "https://..." },
+    onLogout: handleLogout,
+  }}
+>...</AppDashboard>
+```
+
+## Usage standalone (layout outside AppDashboard)
+
+Only needed when building a custom layout that does not use `AppDashboard`:
+
+```tsx
+import { AppHeader, type NetworkOption } from '@skunkworks/ui'
+
+const networks: NetworkOption[] = [
+  { value: "meldcx", label: "MeldCX Network" },
+  { value: "acme", label: "Acme Corp" },
+  // ...
+]
+
+<AppSidebarProvider
+  style={{ "--sidebar-width": "14rem", "--header-height": "3.5rem" } as React.CSSProperties}
+>
+  <AppSidebar>...</AppSidebar>
+  <AppSidebarInset>
+    <AppHeader networks={networks} currentNetwork={selected} onNetworkChange={setSelected} />
+    <main>Page content</main>
+  </AppSidebarInset>
+</AppSidebarProvider>
+```
+
+With custom slots:
+
+```tsx
+<AppHeader
+  searchbar={<AppInput placeholder="Find sites..." className="w-64" />}
+  avatar={<AppAvatar className="size-8"><AppAvatarFallback>JD</AppAvatarFallback></AppAvatar>}
+  networkSelect={null}
+/>
+```
+
+## Searchbar slot
+
+The `searchbar` slot accepts any `ReactNode`. Always fill it with an `App*` component — never a raw `<input>`.
+
+```tsx
+// ✅ Correct
+import { AppInput } from '@skunkworksai/ui-kit'
+
+<AppDashboard header={{
+  searchbar: (
+    <AppInput
+      placeholder="Search sites, users..."
+      value={query}
+      onChange={(e) => setQuery(e.target.value)}
+      className="w-64"
+    />
+  )
+}}>
+
+// ✅ Also correct — controlled with state
+<AppDashboard header={{
+  searchbar: <AppInput placeholder="Search..." value={q} onChange={e => setQ(e.target.value)} />
+}}>
+
+// ❌ Wrong — raw <input> with inline classes
+<AppDashboard header={{
+  searchbar: <input className="flex h-9 rounded-md border border-input bg-transparent px-3 ..." />
+}}>
+
+// ✅ Remove searchbar entirely
+<AppDashboard header={{ searchbar: null }}>
+```
+
+## Rules
+
+- **Do** provide `networks` with real data — the default 2-entry list is a demo placeholder only.
+- **Do** use controlled `currentNetwork` + `onNetworkChange` when the selected network needs to drive other state.
+- **Do** customize the header via `AppDashboard`'s `header` prop — not by importing `AppHeader` directly.
+- **Do** use `null` to remove a slot, not an empty fragment.
+- **Do** use `actions` prop to replace the entire right-side area; use `avatar`/`networkSelect`/`showThemeToggle`/`showBento` for targeted control.
+- **Do** use `AppInput` for the searchbar slot — never a raw `<input>` with className.
+- **Don't** add `bg-*` or theme classes to `AppHeader` inside the dashboard — it uses transparent background by design.
+- **Don't** use raw `<input>`, `<button>`, or `<select>` inside any slot — always use `AppInput`, `AppButton`, `AppSelect`.
+- **Don't** use `AppSelect` for the network picker — use `AppHeaderNetworkCombobox` or the `networks` prop.
+
+If a prop you need is missing, stop and inform the design team.
+
+## Responsive
+
+On mobile (<768px) the searchbar collapses to an icon button that opens a top Sheet, the network combobox is hidden below `sm` (640px), and the actions gap tightens to `gap-1`. On desktop (≥768px) all slots — searchbar, network combobox, and actions — are visible inline with no consumer intervention required.

package/rules/hover-card.md

@@ -0,0 +1,53 @@
+# AppHoverCard
+
+> Docs: https://ui-kit.vercel.app/docs/components/hover-card
+
+```tsx
+import { AppHoverCard, AppHoverCardTrigger, AppHoverCardContent } from "@/components/primitives/AppHoverCard"
+```
+
+## AppHoverCard
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `openDelay` | `number` | `700` | The duration from when the mouse enters the trigger until the hover card opens. |
+| `closeDelay` | `number` | `300` | The duration from when the mouse leaves the trigger or content until the hover card closes. |
+
+## AppHoverCardContent
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | The preferred side of the trigger to render against when open. |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | The preferred alignment against the trigger. |
+
+## Usage
+
+### Simple Hover Card
+```tsx
+<AppHoverCard>
+  <AppHoverCardTrigger>
+    <a href="https://twitter.com/nextjs" className="underline">@nextjs</a>
+  </AppHoverCardTrigger>
+  <AppHoverCardContent className="w-80">
+    <div className="flex justify-between space-x-4">
+      <div className="space-y-1">
+        <h4 className="text-sm font-semibold">@nextjs</h4>
+        <p className="text-sm text-muted-foreground">
+          The React Framework – created and maintained by @vercel.
+        </p>
+      </div>
+    </div>
+  </AppHoverCardContent>
+</AppHoverCard>
+```
+
+## Rules
+
+- **Do** use `AppHoverCard` to provide a preview of content behind a link.
+- **Do** use `AppHoverCard` for sighted users on desktop; ensure information is accessible via other means for mobile/screen readers.
+- **Don't** use `AppHoverCard` for critical actions; it is for informational previews.
+- If a prop you need is missing, stop and inform the design team.
+
+## Responsive
+
+`AppHoverCardContent` renders `null` on mobile (<768px) — hover previews are not available on touch. Use a tap-triggered `AppPopover` or `AppDrawer` if the content must be accessible on mobile.

package/rules/icons.md

@@ -0,0 +1,141 @@
+# Icons
+
+UI Kit uses two icon systems: custom SVG nav icons for the sidebar, and **lucide-react** for all general-purpose UI icons.
+
+---
+
+## Custom Nav Icons
+
+Seven navigation icon pairs ship with UI Kit. Each has a default and an active state. They are used exclusively inside `AppDashboard` nav items — the active/default swap is handled automatically when `isActive` is set on the nav item.
+
+Assets ship as raw files in `dist/assets/` (requires `@skunkworksai/ui-kit@>=0.1.5`). They are scaffolded into your project during setup — import from your own files, never from the package directly:
+
+### Available pairs
+
+| Name | Default | Active |
+|------|---------|--------|
+| Dashboard | `DashboardIcon` | `DashboardActiveIcon` |
+| Site | `SiteIcon` | `SiteActiveIcon` |
+| Devices | `DevicesIcon` | `DevicesActiveIcon` |
+| Sensor | `SensorIcon` | `SensorActiveIcon` |
+| X-ray | `XrayIcon` | `XrayActiveIcon` |
+| Manifest | `ManifestIcon` | `ManifestActiveIcon` |
+| Installer | `InstallerIcon` | `InstallerActiveIcon` |
+
+### Import
+
+```tsx
+import {
+  DashboardIcon, DashboardActiveIcon,
+  SiteIcon, SiteActiveIcon,
+  // … other pairs
+} from "./assets/icons"
+```
+
+These components accept all standard `SVGProps<SVGSVGElement>`. Default size is 24×24 — override with `width` / `height` props.
+
+### Usage in AppDashboard nav
+
+Pass the icon component (not `<Icon />`) as the `icon` field. Do not pass the active icon — the sidebar handles the swap internally.
+
+```tsx
+import { DashboardIcon, DashboardActiveIcon } from "./assets/icons"
+
+function DashboardNavIcon() {
+  return <AppSidebarNavIcon icon={<DashboardIcon />} activeIcon={<DashboardActiveIcon />} />
+}
+
+const nav = [
+  {
+    items: [
+      { title: "Dashboard", icon: DashboardNavIcon, isActive: true },
+    ],
+  },
+]
+```
+
+---
+
+## Lucide React
+
+All general-purpose icons come from **lucide-react**. It is already installed — do not add a second icon library.
+
+### Usage
+
+```tsx
+import { Search, Moon, Sun, LayoutGrid } from "lucide-react"
+
+<Search className="size-4" />   // 16px — inline / button icons
+<Search className="size-5" />   // 20px — sidebar nav icons
+<Search className="size-6" />   // 24px — hero / standalone
+```
+
+### Size conventions
+
+| Class | Size | When to use |
+|-------|------|-------------|
+| `size-3` | 12px | Badges, labels |
+| `size-4` | 16px | Buttons, inputs, inline |
+| `size-5` | 20px | Sidebar nav, list items |
+| `size-6` | 24px | Hero, standalone callouts |
+
+### Color
+
+Icons inherit `currentColor` via their `stroke`. Set color with a Tailwind text class — never hardcode a fill or stroke color.
+
+```tsx
+<Search className="size-4 text-muted-foreground" />
+<Search className="size-4 text-primary" />
+<Search className="size-4 text-destructive" />
+```
+
+---
+
+## Service Applets & Apps
+
+Branded app imagery for each Skunkworks product. Import from your own scaffolded files:
+
+```tsx
+import { AudienceMeasurementImg } from "./assets/Service-applets-apps"
+
+<img src={AudienceMeasurementImg} alt="Audience Measurement" />
+```
+
+### Service Applets
+
+| Export | File |
+|--------|------|
+| `AudienceMeasurementImg` | `audience-measurement.png` |
+| `ContentEffectivenessImg` | `content-effectiveness.png` |
+| `HopTrackingImg` | `hop-tracking.png` |
+| `PeopleCountingImg` | `people-counting.png` |
+| `PetraImg` | `petra.png` |
+| `SamGenericImg` | `sam-generic.png` |
+| `SamiForEnvironmentImg` | `sami-for-environment.png` |
+| `ShelfEngagementImg` | `shelf-engagement.png` |
+| `TrafficManagementImg` | `traffic-management.png` |
+| `ZoneEngagementImg` | `zone-engagement.png` |
+
+### Apps
+
+| Export | File |
+|--------|------|
+| `CoatroAppImg` | `coatro-app.png` |
+| `JourneysAppImg` | `journeys-app.png` |
+
+---
+
+## Rules
+
+- ✅ Import custom nav icons from `./assets/icons` — never from `@skunkworksai/ui-kit`
+- ✅ Import service applet images from `./assets/Service-applets-apps` — never from the package
+- ✅ Always set a `size-*` class on Lucide icons — never rely on the default 24px
+- ✅ Use `text-*` classes for Lucide icon color — icons inherit `currentColor`
+- ❌ Do not import from `lucide-react/dist` — import from the root package
+- ❌ Do not add a second icon library (heroicons, phosphor, etc.) — use lucide-react exclusively
+- ❌ Do not wrap Lucide icons in custom components — use them directly
+- ❌ Do not pass `<Icon />` to the `icon` field in AppDashboard nav — pass the component reference
+
+## On package upgrade
+
+Re-run the asset scaffold step and diff `src/assets/icons/` against the new `dist/assets/icons/` if icons changed.

package/rules/input.md

@@ -0,0 +1,66 @@
+# AppInput
+
+> Docs: https://ui-kit.vercel.app/docs/components/input
+
+```tsx
+import { AppInput } from "@/components/primitives/AppInput"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `leftAdornment` | `ReactNode` | — | Icon or element rendered inside the left edge of the input |
+| `rightAdornment` | `ReactNode` | — | Icon or element rendered inside the right edge of the input |
+| `type` | `string` | `"text"` | HTML input type (text, email, password, number, etc.) |
+| `placeholder` | `string` | — | Placeholder text |
+| `disabled` | `boolean` | `false` | Disables the input |
+| `className` | `string` | — | Additional Tailwind classes applied to the input element |
+
+> Accepts all standard HTML `<input>` attributes in addition to the props above.
+
+## Usage
+
+### Basic
+```tsx
+<AppInput type="email" placeholder="you@example.com" />
+<AppInput type="password" placeholder="••••••••" />
+```
+
+### With adornments
+```tsx
+<AppInput
+  type="search"
+  placeholder="Search..."
+  leftAdornment={<SearchIcon className="size-4" />}
+/>
+
+<AppInput
+  type="text"
+  placeholder="Enter amount"
+  leftAdornment={<span className="text-sm text-muted-foreground">$</span>}
+  rightAdornment={<span className="text-sm text-muted-foreground">USD</span>}
+/>
+```
+
+### Disabled
+```tsx
+<AppInput disabled placeholder="Not editable" />
+```
+
+### With label (use AppLabel)
+```tsx
+<div className="space-y-1.5">
+  <AppLabel htmlFor="email">Email</AppLabel>
+  <AppInput id="email" type="email" placeholder="you@example.com" />
+</div>
+```
+
+## Rules
+- ✅ Always use `AppInput` — never use a raw `<input>` element
+- ✅ Use `leftAdornment` / `rightAdornment` for icons inside the input — do not wrap `AppInput` in a relative `<div>` to position them manually
+- ✅ Pair with `AppLabel` using matching `id` and `htmlFor` — never use a raw `<label>`
+- ✅ Pair with `AppField` or `AppForm` for full form field layout with error states
+- ❌ Do not add `pl-*` or `pr-*` padding when using adornments — padding is adjusted automatically
+- ❌ Do not set `width` directly on `AppInput` — control width from the parent container
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/kbd.md

@@ -0,0 +1,58 @@
+# AppKbd
+
+> Docs: https://ui-kit.vercel.app/docs/components/kbd
+
+```tsx
+import { AppKbd, AppKbdGroup } from "@skunkworksai/ui-kit"
+```
+
+## AppKbd
+
+Keyboard key badge. Renders a `<kbd>` element styled as a bordered monospace pill.
+
+Accepts all HTML `<kbd>` attributes.
+
+## AppKbdGroup
+
+Inline row of `AppKbd` keys with consistent `gap-1`.
+
+Accepts all `<span>` HTML attributes.
+
+## Usage
+
+### Single key
+```tsx
+<AppKbd>K</AppKbd>
+<AppKbd>Enter</AppKbd>
+<AppKbd>⌘</AppKbd>
+```
+
+### Key combination
+```tsx
+<AppKbdGroup>
+  <AppKbd>⌘</AppKbd>
+  <AppKbd>K</AppKbd>
+</AppKbdGroup>
+```
+
+### Multi-key shortcut
+```tsx
+<AppKbdGroup>
+  <AppKbd>Ctrl</AppKbd>
+  <AppKbd>Shift</AppKbd>
+  <AppKbd>P</AppKbd>
+</AppKbdGroup>
+```
+
+### Inside a label or description
+```tsx
+<p className="text-sm text-muted-foreground">
+  Press <AppKbdGroup><AppKbd>⌘</AppKbd><AppKbd>K</AppKbd></AppKbdGroup> to open the command palette.
+</p>
+```
+
+## Rules
+- ✅ Use `AppKbdGroup` whenever showing two or more keys together
+- ✅ Use platform symbols (⌘, ⌥, ⇧) for Mac shortcuts; use "Ctrl", "Alt", "Shift" for cross-platform
+- ❌ Do not wrap `AppKbd` in extra `<span>` elements for spacing — use `AppKbdGroup`
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/label.md

@@ -0,0 +1,30 @@
+# AppLabel
+
+> Docs: https://ui-kit.vercel.app/docs/components/label
+
+```tsx
+import { AppLabel } from "@/components/primitives/AppLabel"
+```
+
+## AppLabel
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `htmlFor` | `string` | - | The ID of the form element the label is associated with. |
+
+## Usage
+
+### Basic Label
+```tsx
+<div className="flex items-center space-x-2">
+  <AppCheckbox id="terms" />
+  <AppLabel htmlFor="terms">Accept terms and conditions</AppLabel>
+</div>
+```
+
+## Rules
+
+- **Do** use `AppLabel` for all form control labels to ensure accessibility.
+- **Do** use the `htmlFor` prop to link the label to its corresponding input.
+- **Don't** use raw `<label>` elements.
+- If a prop you need is missing, stop and inform the design team.