@skunkworksai/ui-kit 0.1.18

package/rules/location-tree-filter.md

@@ -0,0 +1,165 @@
+# AppLocationTreeFilter
+
+> Docs: https://ui-kit.vercel.app/docs/blocks/location-tree-filter
+
+**This is a block — import from `blocks/`, not `primitives/`.**
+
+```tsx
+import { AppLocationTreeFilter } from "@/components/blocks/AppLocationTreeFilter"
+```
+
+Also available from the barrel:
+
+```tsx
+import { AppLocationTreeFilter } from "@/components/blocks"
+```
+
+## Hard stop
+
+> ❌ **Never compose a location tree filter manually using `AppCollapsible`, raw `<details>`, or any other approach.**
+>
+> `AppLocationTreeFilter` handles the full tree rendering, recursive collapsible structure, search/filter, depth indentation, selection state, and unallocated row. Building this from scratch will produce inconsistent behaviour and visual drift. Use this block.
+
+## Types
+
+```tsx
+type TreeNode = {
+  label: string         // Display label and the value emitted when this node is selected
+  count: number         // Badge count shown alongside the label
+  children?: TreeNode[] // If present, renders as a collapsible branch
+}
+
+type UnallocatedConfig = {
+  label?: string  // Row label. Defaults to "Unallocated"
+  count: number   // Badge count
+  value?: string  // Sentinel value emitted on click. Defaults to "__unallocated__"
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `TreeNode[]` | required | Tree data. Top-level nodes with optional nested children. |
+| `selected` | `string \| null` | required | Current selection value. `null` = root/all state. |
+| `onSelect` | `(value: string \| null) => void` | required | Fired when user clicks a node or the unallocated row. |
+| `title` | `string` | `"Filter by Location"` | Label shown above the search input. |
+| `showHelp` | `boolean` | `false` | Shows a help icon next to the title. |
+| `searchPlaceholder` | `string` | `"Search locations..."` | Placeholder for the search input. |
+| `unallocated` | `UnallocatedConfig` | `undefined` | Pinned row above the tree for unallocated records. Omit to hide. |
+| `className` | `string` | `—` | Extra classes on the root container (default width: `w-56`). |
+
+## Selection model
+
+The block is **uncontrolled for tree state** (collapse/expand), but **controlled for selection** — your component owns `selected`.
+
+| `onSelect` emits | Meaning |
+|-----------------|---------|
+| `null` | Top-level branch node clicked — "show all" / root state |
+| `node.label` | A mid-level or leaf node was clicked — filter by that label |
+| `unallocated.value` (default: `"__unallocated__"`) | The unallocated row was clicked |
+
+```tsx
+const [selected, setSelected] = React.useState<string | null>(null)
+
+<AppLocationTreeFilter
+  data={tree}
+  selected={selected}
+  onSelect={setSelected}
+/>
+```
+
+## Search behavior
+
+Typing in the search input filters visible tree nodes by label. Branches that contain a matching descendant are automatically expanded. Clearing the search restores the original collapsed state.
+
+## Usage
+
+### Basic
+
+```tsx
+const tree: TreeNode[] = [
+  {
+    label: "All",
+    count: 65,
+    children: [
+      {
+        label: "Philippines",
+        count: 65,
+        children: [
+          { label: "Davao City", count: 1 },
+          { label: "Cagayan de Oro", count: 64 },
+        ],
+      },
+    ],
+  },
+]
+
+export default function Page() {
+  const [selected, setSelected] = React.useState<string | null>(null)
+
+  return (
+    <AppLocationTreeFilter
+      data={tree}
+      selected={selected}
+      onSelect={setSelected}
+    />
+  )
+}
+```
+
+### With unallocated row
+
+```tsx
+<AppLocationTreeFilter
+  data={tree}
+  title="Filter by Location"
+  showHelp
+  unallocated={{ label: "Unallocated Devices", count: 135 }}
+  selected={selected}
+  onSelect={setSelected}
+/>
+```
+
+### URL search params
+
+The `unallocated.value` sentinel (default `"__unallocated__"`) must be encoded when storing in URL params:
+
+```tsx
+// Writing to URL
+const params = new URLSearchParams()
+if (selected !== null) params.set("location", encodeURIComponent(selected))
+
+// Reading from URL
+const raw = params.get("location")
+const selected = raw ? decodeURIComponent(raw) : null
+```
+
+### Custom width
+
+Override the default `w-56` via `className`:
+
+```tsx
+<AppLocationTreeFilter
+  data={tree}
+  selected={selected}
+  onSelect={setSelected}
+  className="w-64"
+/>
+```
+
+## Rules
+
+- ✅ Always use `AppLocationTreeFilter` for hierarchical location filtering — never compose manually
+- ✅ Provide a top-level node (e.g. "All") as the root branch — it emits `null` on click and represents the "show all" state
+- ✅ Own the `selected` state in your page or parent component — the block does not manage selection internally
+- ✅ Use `unallocated` whenever records can exist without an assigned location
+- ✅ Set a custom `unallocated.value` if `"__unallocated__"` conflicts with any real location label in your dataset
+- ❌ Never import `AppCollapsible` to build a tree structure — use this block
+- ❌ Never manage tree expand/collapse state externally — the block handles it internally
+- ❌ Never pass a flat list as `data` — the tree structure must be nested via `children`
+- ❌ If a prop you need is missing, stop and inform the design team
+
+## Responsive
+
+The root container uses `w-full sm:w-56 sm:shrink-0` — on mobile it expands to full width and stacks vertically with surrounding content; on desktop it returns to its fixed `14rem` width and does not shrink. A drawer-based mobile trigger is not implemented — wrap in `AppSheet` at the page level if a collapsible filter panel is needed.

package/rules/logo.md

@@ -0,0 +1,58 @@
+# Logo Assets
+
+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:
+
+```tsx
+import { PrimaryLogo, DarkLogo, WhiteLogo } from "./assets/logos"
+import { PrimarySymbol, DarkSymbol, WhiteSymbol } from "./assets/logos"
+```
+
+## Variants
+
+| Component | Fill color | Use on |
+|-----------|-----------|--------|
+| `PrimaryLogo` | Brand blue | Light backgrounds, white surfaces |
+| `DarkLogo` | Dark | Light backgrounds when primary blue is too prominent |
+| `WhiteLogo` | White | Dark backgrounds, colored sidebars, dark-mode |
+| `PrimarySymbol` | Brand blue | Icon-only contexts on light backgrounds |
+| `DarkSymbol` | Dark | Icon-only on light |
+| `WhiteSymbol` | White | Icon-only on dark backgrounds or colored fills |
+
+## Default dimensions
+
+All logos share the same `265 × 83` viewBox. Pass `width` and `height` to scale proportionally:
+
+```tsx
+<PrimaryLogo width={120} height={38} />   {/* standard header size */}
+<WhiteLogo width={160} height={50} />     {/* larger marketing use */}
+<WhiteSymbol width={32} height={32} />    {/* icon-only mark */}
+```
+
+## Usage
+
+### Light + dark mode pair
+
+```tsx
+<PrimaryLogo className="block dark:hidden" width={120} height={38} />
+<WhiteLogo className="hidden dark:block" width={120} height={38} />
+```
+
+### Symbol only
+
+```tsx
+<WhiteSymbol width={28} height={28} />
+```
+
+## Rules
+
+- ✅ Import from `./assets/logos` — never from `@skunkworksai/ui-kit`
+- ✅ Use `PrimaryLogo` on light backgrounds (docs, marketing pages, cards)
+- ✅ Use `WhiteLogo` or `WhiteSymbol` on dark backgrounds
+- ✅ Support dark mode with `block dark:hidden` / `hidden dark:block` pair
+- ❌ Do not hardcode logo colors with Tailwind color classes — use the correct variant instead
+- ❌ Do not distort the logo — always scale both `width` and `height` proportionally from the `265 × 83` viewBox ratio
+- ❌ If you need a logo variant that doesn't exist, inform the design team — do not create ad-hoc SVGs
+
+## On package upgrade
+
+Re-run the asset scaffold step and diff `src/assets/logos/` against the new `dist/assets/logos/` if logos changed.

package/rules/menubar.md

@@ -0,0 +1,75 @@
+# AppMenubar
+
+> Docs: https://ui-kit.vercel.app/docs/components/menubar
+
+```tsx
+import {
+  AppMenubar,
+  AppMenubarMenu,
+  AppMenubarTrigger,
+  AppMenubarContent,
+  AppMenubarItem,
+  AppMenubarSeparator,
+  AppMenubarLabel,
+  AppMenubarCheckboxItem,
+  AppMenubarRadioGroup,
+  AppMenubarRadioItem,
+  AppMenubarPortal,
+  AppMenubarGroup,
+  AppMenubarSub,
+  AppMenubarSubContent,
+  AppMenubarSubTrigger,
+  AppMenubarShortcut,
+} from "@/components/primitives/AppMenubar"
+```
+
+## AppMenubar
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `defaultValue` | `string` | - | The value of the menu that should be open by default. |
+
+## AppMenubarTrigger
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `asChild` | `boolean` | `false` | Change the default rendered element for the one passed as a child. |
+
+## Usage
+
+### Desktop-style Menubar
+```tsx
+<AppMenubar>
+  <AppMenubarMenu>
+    <AppMenubarTrigger>File</AppMenubarTrigger>
+    <AppMenubarContent>
+      <AppMenubarItem>
+        New Tab <AppMenubarShortcut>⌘T</AppMenubarShortcut>
+      </AppMenubarItem>
+      <AppMenubarItem>
+        New Window <AppMenubarShortcut>⌘N</AppMenubarShortcut>
+      </AppMenubarItem>
+      <AppMenubarSeparator />
+      <AppMenubarItem>Print</AppMenubarItem>
+    </AppMenubarContent>
+  </AppMenubarMenu>
+  <AppMenubarMenu>
+    <AppMenubarTrigger>Edit</AppMenubarTrigger>
+    <AppMenubarContent>
+      <AppMenubarItem>Undo</AppMenubarItem>
+      <AppMenubarItem>Redo</AppMenubarItem>
+    </AppMenubarContent>
+  </AppMenubarMenu>
+</AppMenubar>
+```
+
+## Rules
+
+- **Do** use `AppMenubar` for application-wide persistent menus.
+- **Do** use `AppMenubarShortcut` to display keyboard shortcuts.
+- **Don't** use `AppMenubar` for simple navigation; use `AppNavigationMenu` for website headers.
+- If a prop you need is missing, stop and inform the design team.
+
+## Responsive
+
+`AppMenubar` scrolls horizontally on mobile via an `overflow-x-auto` wrapper with `min-w-max` on the inner bar. A Sheet-based mobile menu is not implemented — compose one at the page level using `AppSheet` if a collapsing menu is required.

package/rules/navigation-menu.md

@@ -0,0 +1,68 @@
+# AppNavigationMenu
+
+> Docs: https://ui-kit.vercel.app/docs/components/navigation-menu
+
+```tsx
+import {
+  AppNavigationMenu,
+  AppNavigationMenuList,
+  AppNavigationMenuItem,
+  AppNavigationMenuTrigger,
+  AppNavigationMenuContent,
+  AppNavigationMenuLink,
+  AppNavigationMenuIndicator,
+  AppNavigationMenuViewport,
+  navigationMenuTriggerStyle,
+} from "@/components/primitives/AppNavigationMenu"
+```
+
+## AppNavigationMenu
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the menu. |
+
+## AppNavigationMenuLink
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `active` | `boolean` | - | Whether the link is currently active. |
+| `asChild` | `boolean` | `false` | Change the default rendered element for the one passed as a child. |
+
+## Usage
+
+### Standard Navigation Menu
+```tsx
+<AppNavigationMenu>
+  <AppNavigationMenuList>
+    <AppNavigationMenuItem>
+      <AppNavigationMenuTrigger>Components</AppNavigationMenuTrigger>
+      <AppNavigationMenuContent>
+        <ul className="grid w-[400px] gap-3 p-4">
+          <li>
+            <AppNavigationMenuLink asChild>
+              <a href="/docs/alert">Alert</a>
+            </AppNavigationMenuLink>
+          </li>
+        </ul>
+      </AppNavigationMenuContent>
+    </AppNavigationMenuItem>
+    <AppNavigationMenuItem>
+      <AppNavigationMenuLink className={navigationMenuTriggerStyle()} href="/docs">
+        Documentation
+      </AppNavigationMenuLink>
+    </AppNavigationMenuItem>
+  </AppNavigationMenuList>
+</AppNavigationMenu>
+```
+
+## Rules
+
+- **Do** use `AppNavigationMenu` for primary website navigation.
+- **Do** use `navigationMenuTriggerStyle()` for consistent styling on top-level links.
+- **Don't** nest `AppNavigationMenu` components.
+- If a prop you need is missing, stop and inform the design team.
+
+## Responsive
+
+`AppNavigationMenuList` scrolls horizontally on mobile via an `overflow-x-auto` wrapper with `min-w-max` on items so they never wrap. A hamburger-to-Sheet pattern is not implemented — if a collapsing nav is needed at mobile widths, build it at the page level using `AppSheet`.

package/rules/notifications-menu.md

@@ -0,0 +1,137 @@
+# AppNotificationsMenu
+
+## When to use
+
+`AppNotificationsMenu` is a bell-icon trigger that opens a popover panel listing notifications. It is rendered automatically inside `AppHeader` — you do not need to import it directly unless building a layout outside `AppDashboard`.
+
+To show notifications inside `AppDashboard`, pass notification props via the `header` prop on `AppDashboard`:
+
+```tsx
+<AppDashboard
+  header={{
+    notifications: myNotifications,
+    notificationsTotal: 1433,
+    onShowMoreNotifications: handleShowMore,
+    onMarkAllNotificationsRead: handleMarkAll,
+  }}
+>
+  ...
+</AppDashboard>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `notifications` | `AppNotification[]` | `[]` | Notification items to display. Component is data-dumb — caller owns the array. |
+| `totalCount` | `number` | `notifications.length` | Total count on the server. Used for "Show More (N of TOTAL)" footer label. |
+| `pageSize` | `number` | `10` | Initial number of visible items. |
+| `onShowMore` | `() => void` | — | Called when "Show More" is clicked. Append more items to `notifications` in the caller. |
+| `onMarkAllAsRead` | `() => void` | — | Called when "Mark all as read" is selected from the meatball menu. |
+| `open` | `boolean` | — | Controlled open state for the popover. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when the panel open state changes. |
+| `trigger` | `ReactNode` | Bell icon button | Replaces the default bell trigger entirely. |
+| `className` | `string` | — | Extra classes applied to the popover content panel. |
+
+## AppNotification type
+
+```ts
+type AppNotification = {
+  id: string
+  title: string
+  description?: string
+  /** ISO string or Date. Rendered as relative time ("20d ago"). */
+  timestamp: string | Date
+  variant?: "info" | "success" | "warning" | "destructive"  // default "info"
+  /** When false, renders an unread dot before the title. */
+  read?: boolean
+  /** Override the default variant icon. */
+  icon?: React.ComponentType<React.SVGProps<SVGSVGElement>>
+  href?: string
+  onClick?: () => void
+}
+```
+
+## Variant → icon map
+
+| Variant | Icon | Container colors |
+|---------|------|-----------------|
+| `info` | `Info` | `bg-info text-info-foreground` |
+| `success` | `CheckCircle2` | `bg-success text-success-foreground` |
+| `warning` | `AlertTriangle` | `bg-warning text-warning-foreground` |
+| `destructive` | `AlertCircle` | `bg-destructive text-destructive-foreground` |
+
+## Usage
+
+### Inside AppDashboard (standard)
+
+```tsx
+<AppDashboard
+  nav={nav}
+  header={{
+    notifications: items,
+    notificationsTotal: 1433,
+    onShowMoreNotifications: () => fetchMore().then(more => setItems(prev => [...prev, ...more])),
+    onMarkAllNotificationsRead: () => setItems(prev => prev.map(n => ({ ...n, read: true }))),
+  }}
+>
+  <PageContent />
+</AppDashboard>
+```
+
+### Hide the bell
+
+```tsx
+<AppDashboard header={{ showNotifications: false }}>...</AppDashboard>
+```
+
+### Custom bell trigger
+
+```tsx
+<AppNotificationsMenu
+  notifications={items}
+  trigger={<AppButton variant="outline" size="sm">Alerts</AppButton>}
+/>
+```
+
+### Server-paged Show More
+
+The component is intentionally dumb about data. "Show More" fires `onShowMore` — caller fetches the next page and appends to `notifications`. The footer auto-hides when `notifications.length >= totalCount`.
+
+```tsx
+const [items, setItems] = useState<AppNotification[]>(initialPage)
+
+<AppNotificationsMenu
+  notifications={items}
+  totalCount={serverTotal}
+  pageSize={10}
+  onShowMore={async () => {
+    const next = await fetchPage(items.length)
+    setItems(prev => [...prev, ...next])
+  }}
+/>
+```
+
+## Default header action order
+
+```
+network combobox → bell → bento → theme toggle → avatar
+```
+
+The bell is positioned between the network combobox and the bento icon. This order is fixed in `AppHeader` default actions and cannot be changed via props (use the `actions` slot override on `AppHeader` to reorder).
+
+## Rules
+
+- **Do** keep the component data-dumb — never mutate `notifications` inside the component. Caller owns the array.
+- **Do** pass `totalCount` when data is server-paged so the footer shows the correct "N of TOTAL" label.
+- **Do** set `read: false` on new items to render the unread blue dot before the title.
+- **Do** provide an `href` or `onClick` on each row that should be navigable.
+- **Don't** add an unread badge count to the bell trigger — deferred to a future `unreadCount` prop.
+- **Don't** sort or filter notifications inside this component — do it in the caller before passing the array.
+- **Don't** use `AppScrollArea` inside this component — the list uses a plain overflow div; Radix ScrollArea requires a fixed height which conflicts with dynamic list heights.
+
+If a prop you need is missing, stop and inform the design team.
+
+## Responsive
+
+On mobile (<768px) the panel renders as a side `AppDrawer` with the header row showing title, meatball menu, and close button together. On desktop (≥768px) it renders as a floating `AppPopover`. The component uses `useIsMobile` to branch between these two paths internally — the public API is unchanged across all viewport sizes. The bell trigger remains visible at all viewport widths.

package/rules/pagetitle.md

@@ -0,0 +1,160 @@
+# AppPageTitle
+
+> **Default page header block** — present on most pages. Suppress it explicitly with `pageTitle={false}`.
+
+## Import
+
+```tsx
+import { AppPageTitle } from "@/components/blocks/AppPageTitle"
+```
+
+Or via `AppDashboard` (recommended):
+
+```tsx
+import { AppDashboard } from "@/components/blocks/AppDashboard"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | auto | Page heading, rendered as an `<h1>`. Auto-derived from the last pathname segment when omitted. |
+| `subtitle` | `string` | — | Optional description rendered below the heading. |
+| `breadcrumbs` | `AppPageTitleBreadcrumb[]` | auto | Explicit breadcrumb trail. Auto-generated from `window.location.pathname` when omitted. |
+| `actions` | `ReactNode` | — | Right-side action slot. Accepts any elements — buttons, selects, text, etc. Empty by default. |
+| `icon` | `ReactNode` | — | Optional icon rendered to the left of the title stack. Accepts `<img>`, SVG, or Lucide icons. Omit to hide. |
+| `titleColor` | `"default" \| "primary"` | `"default"` | Controls the h1 color. `"default"` uses `text-foreground`; `"primary"` uses the brand blue. |
+| `hidden` | `boolean` | `false` | Hides the entire block. |
+| `className` | `string` | — | Extra classes on the root element. |
+
+### AppPageTitleBreadcrumb
+
+```ts
+type AppPageTitleBreadcrumb = {
+  label: string
+  href?: string  // Omit for the last (current-page) segment
+}
+```
+
+## Usage via AppDashboard
+
+### Default (title + breadcrumbs auto-derived from pathname)
+
+```tsx
+<AppDashboard nav={nav}>
+  <PageContent />
+</AppDashboard>
+```
+
+### With explicit title and subtitle
+
+```tsx
+<AppDashboard
+  nav={nav}
+  pageTitle={{ title: "Site", subtitle: "Stay up to date to everything in your network" }}
+>
+  <PageContent />
+</AppDashboard>
+```
+
+### With actions
+
+```tsx
+<AppDashboard
+  nav={nav}
+  pageTitle={{
+    title: "Site",
+    subtitle: "Stay up to date to everything in your network",
+    actions: <AppButton>+ Add Site</AppButton>,
+  }}
+>
+  <PageContent />
+</AppDashboard>
+```
+
+### Hidden
+
+```tsx
+<AppDashboard nav={nav} pageTitle={false}>
+  <PageContent />
+</AppDashboard>
+```
+
+### Manual breadcrumbs
+
+```tsx
+<AppDashboard
+  nav={nav}
+  pageTitle={{
+    title: "Site Details",
+    breadcrumbs: [
+      { label: "Manage", href: "/manage" },
+      { label: "Site", href: "/manage/site" },
+      { label: "Site Details" },
+    ],
+  }}
+>
+  <PageContent />
+</AppDashboard>
+```
+
+## Breadcrumb auto-generation
+
+When `breadcrumbs` is omitted, the component reads `window.location.pathname` on mount and converts each path segment into a readable label:
+
+- Segments are split on `-` and `_`, then title-cased (`site-settings` → `Site Settings`)
+- The final segment has no `href` (current page, non-linked)
+- All preceding segments get `href` values pointing to their cumulative path
+
+## With icon
+
+```tsx
+<AppDashboard
+  nav={nav}
+  pageTitle={{
+    title: "Hi Kevin! Welcome to Skunkworks",
+    subtitle: "Stay up to date to everything in your network",
+    breadcrumbs: [{ label: "Dashboard" }],
+    titleColor: "primary",
+    icon: (
+      <img
+        src="/persistent-icon.png"
+        alt="Dashboard"
+        className="size-16 rounded-xl"
+      />
+    ),
+  }}
+>
+  <PageContent />
+</AppDashboard>
+```
+
+## With primary title color
+
+```tsx
+<AppDashboard
+  nav={nav}
+  pageTitle={{
+    title: "Dashboard",
+    titleColor: "primary",
+  }}
+>
+  <PageContent />
+</AppDashboard>
+```
+
+## Rules
+
+- **Do** use `pageTitle` on `AppDashboard` rather than placing `AppPageTitle` manually inside the page content.
+- **Do** pass `pageTitle={false}` to explicitly suppress the block — do not conditionally omit it based on state.
+- **Do** put action buttons in the `actions` slot — do not place them above the title.
+- **Do** size and style the `icon` yourself — pass `className="size-16 rounded-xl"` on the `<img>` or wrapper. The component does not enforce icon dimensions.
+- **Don't** hardcode breadcrumbs when auto-generation is correct — only override when the URL structure doesn't match the desired labels.
+- **Don't** add additional margin-top to page content — `AppPageTitle` already provides `mb-6` spacing.
+- **Don't** use raw color values for `titleColor` overrides — use the `titleColor` prop, not a `className` on the heading.
+
+If a prop you need is missing, stop and inform the design team.
+
+## Responsive
+
+On mobile (<768px) the title row stacks vertically (`flex-col`) with actions rendering below the title. On desktop (≥768px) title and actions are inline (`flex-row justify-between`). When a breadcrumb trail has more than 2 segments, middle items are automatically hidden on mobile using `hideOnMobile` — no manual configuration required.