@skunkworksai/ui-kit 0.1.18

package/rules/pagination.md

@@ -0,0 +1,71 @@
+# AppPagination
+
+> Docs: https://ui-kit.vercel.app/docs/components/pagination
+
+```tsx
+import {
+  AppPagination,
+  AppPaginationContent,
+  AppPaginationItem,
+  AppPaginationLink,
+  AppPaginationPrevious,
+  AppPaginationNext,
+  AppPaginationEllipsis,
+} from "@/components/primitives/AppPagination"
+```
+
+## AppPaginationLink
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `isActive` | `boolean` | `false` | Whether the link represents the current page. |
+| `size` | `"default" \| "sm" \| "lg" \| "icon"` | `"icon"` | The size of the link. |
+
+## Usage
+
+### Default Pagination
+```tsx
+<AppPagination>
+  <AppPaginationContent>
+    <AppPaginationItem>
+      <AppPaginationPrevious href="#" />
+    </AppPaginationItem>
+    <AppPaginationItem>
+      <AppPaginationLink href="#">1</AppPaginationLink>
+    </AppPaginationItem>
+    <AppPaginationItem>
+      <AppPaginationLink href="#" isActive>2</AppPaginationLink>
+    </AppPaginationItem>
+    <AppPaginationItem>
+      <AppPaginationEllipsis />
+    </AppPaginationItem>
+    <AppPaginationItem>
+      <AppPaginationNext href="#" />
+    </AppPaginationItem>
+  </AppPaginationContent>
+</AppPagination>
+```
+
+## Rules
+
+- **Do** use `AppPagination` for navigating through paginated lists.
+- **Do** mark the current page with `isActive`.
+- **Don't** show too many page links; use `AppPaginationEllipsis` for collapsed ranges.
+- If a prop you need is missing, stop and inform the design team.
+
+## Responsive
+
+`AppPaginationLink` (page numbers) and `AppPaginationEllipsis` are hidden below `sm` (640px) via `hidden sm:inline-flex` and `hidden sm:flex` respectively. Previous and next buttons are always visible. On mobile, show a "Page X of Y" label alongside prev/next if page context is needed.
+
+```tsx
+// Mobile-friendly pagination with page label
+<div className="flex items-center gap-2">
+  <AppPagination>
+    <AppPaginationContent>
+      <AppPaginationItem><AppPaginationPrevious href="#" /></AppPaginationItem>
+      <AppPaginationItem className="sm:hidden"><span className="text-sm">Page 2 of 10</span></AppPaginationItem>
+      <AppPaginationItem><AppPaginationNext href="#" /></AppPaginationItem>
+    </AppPaginationContent>
+  </AppPagination>
+</div>
+```

package/rules/popover.md

@@ -0,0 +1,48 @@
+# AppPopover
+
+> Docs: https://ui-kit.vercel.app/docs/components/popover
+
+```tsx
+import { AppPopover, AppPopoverTrigger, AppPopoverContent } from "@/components/primitives/AppPopover"
+```
+
+## AppPopoverContent
+
+| 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. |
+| `sideOffset` | `number` | `4` | The distance in pixels from the trigger. |
+
+## Usage
+
+### Basic Popover
+```tsx
+<AppPopover>
+  <AppPopoverTrigger asChild>
+    <AppButton variant="outline">Open Popover</AppButton>
+  </AppPopoverTrigger>
+  <AppPopoverContent className="w-80">
+    <div className="grid gap-4">
+      <div className="space-y-2">
+        <h4 className="font-medium leading-none">Dimensions</h4>
+        <p className="text-sm text-muted-foreground">Set the dimensions for the layer.</p>
+      </div>
+    </div>
+  </AppPopoverContent>
+</AppPopover>
+```
+
+## Rules
+
+- **Do** use `AppPopover` for rich content that should appear upon click.
+- **Do** use `asChild` on `AppPopoverTrigger` to use an `AppButton`.
+- **Do** always set width via `className` on `AppPopoverContent` (e.g. `className="w-64"`) — no default width.
+- **Don't** use `AppPopover` if the content is just a simple text label; use `AppTooltip` instead.
+- If a prop you need is missing, stop and inform the design team.
+
+## Responsive
+
+On mobile (<768px) `AppPopover` renders as a bottom `Drawer`; `AppPopoverTrigger` becomes a `DrawerTrigger` and `AppPopoverContent` becomes `DrawerContent`. The consumer API is unchanged across all viewport sizes.
+
+> **Implementation note:** On mobile, `AppPopoverContent` wraps `{children}` in an inner `div` inside `DrawerContent`. Consumer `className` (e.g. `p-0`) applies to that inner div, preserving `DrawerContent`'s own padding. `AppNotificationsMenu` and `AppProfile` do not use `AppPopover` on mobile — they branch directly to `AppDrawer` for a purpose-built drawer header.

package/rules/profile.md

@@ -0,0 +1,125 @@
+# AppProfile
+
+Avatar trigger that opens a user profile popover with name, role, and action items (Settings, Administrator, Log Out by default).
+
+## Exports
+
+```ts
+import {
+  AppProfile,
+  type AppProfileUser,
+  type AppProfileItem,
+  type AppProfileProps,
+} from '@skunkworksai/ui-kit'
+```
+
+## Props
+
+### `AppProfile`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `user` | `AppProfileUser` | — | Required. User data for the header row and avatar. |
+| `items` | `AppProfileItem[]` | Settings + Administrator + Log Out | Override the full menu item list. |
+| `onSettings` | `() => void` | — | Called when Settings is clicked. |
+| `onAdministrator` | `() => void` | — | Called when Administrator is clicked. |
+| `onLogout` | `() => void` | — | Called when Log Out is clicked. |
+| `open` | `boolean` | — | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | — | Open state change handler. |
+| `trigger` | `ReactNode` | avatar button | Replace the default avatar trigger. |
+| `className` | `string` | — | Extra classes added to the popover content. |
+
+### `AppProfileUser`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | ✓ | Full display name shown in the popover header. |
+| `role` | `string` | — | Subtitle shown below the name. |
+| `avatarSrc` | `string` | — | Image URL for the avatar. |
+| `avatarFallback` | `string` | — | Initials override. Derived from `name` when omitted. |
+
+### `AppProfileItem`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `label` | `string` | ✓ | Display text. |
+| `icon` | `ComponentType` | — | Lucide icon component. |
+| `onClick` | `() => void` | — | Click handler. |
+| `href` | `string` | — | Renders the item as an `<a>` tag. |
+| `destructive` | `boolean` | — | Applies destructive color. |
+
+## Usage
+
+### Via AppDashboard (standard)
+
+```tsx
+<AppDashboard
+  nav={nav}
+  header={{
+    profile: { name: "Joshua Intern", role: "Admin" },
+    onSettings: handleSettings,
+    onAdministrator: handleAdministrator,
+    onLogout: handleLogout,
+  }}
+>
+  <PageContent />
+</AppDashboard>
+```
+
+### Standalone
+
+```tsx
+<AppProfile
+  user={{ name: "Joshua Intern", role: "Admin" }}
+  onSettings={handleSettings}
+  onAdministrator={handleAdministrator}
+  onLogout={handleLogout}
+/>
+```
+
+### With avatar image
+
+```tsx
+<AppProfile
+  user={{ name: "Joshua Intern", role: "Admin", avatarSrc: "https://..." }}
+  onLogout={handleLogout}
+/>
+```
+
+### Custom items
+
+```tsx
+import { User, HelpCircle, LogOut } from "lucide-react"
+
+<AppProfile
+  user={{ name: "Joshua Intern", role: "Admin" }}
+  items={[
+    { label: "My Account", icon: User, onClick: handleAccount },
+    { label: "Help", icon: HelpCircle, href: "/help" },
+    { label: "Log Out", icon: LogOut, onClick: handleLogout, destructive: true },
+  ]}
+/>
+```
+
+### Controlled open state
+
+```tsx
+const [open, setOpen] = React.useState(false)
+
+<AppProfile
+  user={{ name: "Joshua Intern", role: "Admin" }}
+  open={open}
+  onOpenChange={setOpen}
+  onLogout={() => setOpen(false)}
+/>
+```
+
+## Rules
+
+- Use `profile` + handler props on `AppDashboard`/`AppHeader` rather than dropping `AppProfile` directly into slots.
+- The `avatar` prop on `AppHeader` takes precedence over `profile` — do not set both.
+- The `actions` prop on `AppHeader` overrides everything; profile props are ignored when `actions` is set.
+- Default initials are derived from `name` (first letter of each word, max 2). Supply `avatarFallback` to override.
+- Each item closes the popover on click; `href` items also close on click.
+- Mobile: `AppProfile` renders as a side `AppDrawer` on viewports below 768px, with user avatar, name, role, and a close button in the drawer header. Desktop uses `AppPopover`. The public API is unchanged across viewport sizes.
+- If a prop you need is missing, stop and inform the design team.

package/rules/progress.md

@@ -0,0 +1,41 @@
+# AppProgress
+
+> Docs: https://ui-kit.vercel.app/docs/components/progress
+
+```tsx
+import { AppProgress } from "@/components/primitives/AppProgress"
+```
+
+## AppProgress
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `value` | `number \| null` | - | The progress value. |
+| `max` | `number` | `100` | The maximum progress value. |
+
+## Usage
+
+> `AppProgress` has no default width. Set width on a parent wrapper or via `className` (e.g. `className="w-full"` or `className="w-64"`).
+
+### Simple Progress Bar
+```tsx
+<AppProgress value={33} className="w-full" />
+```
+
+### Progress with Label
+```tsx
+<div className="w-full space-y-1.5">
+  <div className="flex justify-between text-sm">
+    <span>Uploading…</span>
+    <span>66%</span>
+  </div>
+  <AppProgress value={66} />
+</div>
+```
+
+## Rules
+
+- **Do** use `AppProgress` to show completion status of a task.
+- **Do** provide additional context (like percentages) for better clarity when needed.
+- **Don't** use `AppProgress` for indeterminate loading states where time is unknown; use `AppSpinner` or a skeleton instead if appropriate.
+- If a prop you need is missing, stop and inform the design team.

package/rules/radio-group.md

@@ -0,0 +1,44 @@
+# AppRadioGroup
+
+> Docs: https://ui-kit.vercel.app/docs/components/radio-group
+
+```tsx
+import { AppRadioGroup, AppRadioGroupItem } from "@/components/primitives/AppRadioGroup"
+```
+
+## AppRadioGroup
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `defaultValue` | `string` | - | The value of the radio item that should be checked by default. |
+| `onValueChange` | `(value: string) => void` | - | Event handler called when the value changes. |
+
+## AppRadioGroupItem
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `value` | `string` | - | The value given as data to the radio item when submitted in a form. |
+| `id` | `string` | - | A unique ID for the radio item, used to link with a label. |
+
+## Usage
+
+### Default Radio Group
+```tsx
+<AppRadioGroup defaultValue="option-one">
+  <div className="flex items-center gap-2">
+    <AppRadioGroupItem value="option-one" id="option-one" />
+    <AppLabel htmlFor="option-one">Option One</AppLabel>
+  </div>
+  <div className="flex items-center gap-2">
+    <AppRadioGroupItem value="option-two" id="option-two" />
+    <AppLabel htmlFor="option-two">Option Two</AppLabel>
+  </div>
+</AppRadioGroup>
+```
+
+## Rules
+
+- **Do** use `AppRadioGroup` when only one option can be selected from a set.
+- **Do** always provide a label for each `AppRadioGroupItem`.
+- **Don't** use `AppRadioGroup` for multi-select; use `AppCheckbox` instead.
+- If a prop you need is missing, stop and inform the design team.

package/rules/scroll-area.md

@@ -0,0 +1,32 @@
+# AppScrollArea
+
+> Docs: https://ui-kit.vercel.app/docs/components/scroll-area
+
+```tsx
+import { AppScrollArea, AppScrollBar } from "@/components/primitives/AppScrollArea"
+```
+
+## AppScrollArea
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `type` | `"auto" \| "always" \| "scroll" \| "hover"` | `"hover"` | Describes the nature of scrollbar visibility. |
+
+## Usage
+
+### Simple Scroll Area
+```tsx
+<AppScrollArea className="h-[200px] w-[350px] rounded-md border p-4">
+  Jokester began sneaking into the castle in the middle of the night and leaving
+  jokes all over the place: under the king's pillow, in his soup, even in the
+  royal toilet. The king was furious, but he couldn't help but laugh at the
+  jokes.
+</AppScrollArea>
+```
+
+## Rules
+
+- **Do** use `AppScrollArea` for custom-styled scrollbars that work across browsers.
+- **Do** specify a height for the `AppScrollArea` container.
+- **Don't** use `AppScrollArea` for the entire page; use native browser scrolling for better performance.
+- If a prop you need is missing, stop and inform the design team.

package/rules/scroll-text.md

@@ -0,0 +1,40 @@
+# AppScrollText
+
+> Docs: https://ui-kit.vercel.app/docs/components/scroll-text
+
+```tsx
+import { AppScrollText } from "@/components/primitives/AppScrollText"
+```
+
+## AppScrollText
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `direction` | `"left" \| "right"` | `"left"` | The direction of the scrolling text. |
+| `speed` | `number` | `50` | The speed of the scrolling animation. |
+| `pauseOnHover` | `boolean` | `false` | Whether to pause the animation when hovered. |
+
+## Usage
+
+### Left Scrolling Text
+```tsx
+<AppScrollText direction="left" className="text-2xl font-bold">
+  <span>Special Offer!</span>
+  <span>50% Off all items</span>
+  <span>Ends tonight!</span>
+</AppScrollText>
+```
+
+### Fast Right Scrolling Text
+```tsx
+<AppScrollText direction="right" speed={100} className="text-lg">
+  <span>Breaking News: New components released!</span>
+</AppScrollText>
+```
+
+## Rules
+
+- **Do** use `AppScrollText` for marquee-like announcements.
+- **Do** ensure the text remains readable at the chosen `speed`.
+- **Don't** use `AppScrollText` for critical information that the user might miss.
+- If a prop you need is missing, stop and inform the design team.

package/rules/select.md

@@ -0,0 +1,86 @@
+# AppSelect
+
+> Docs: https://ui-kit.vercel.app/docs/components/select
+
+```tsx
+import {
+  AppSelect,
+  AppSelectTrigger,
+  AppSelectValue,
+  AppSelectContent,
+  AppSelectGroup,
+  AppSelectItem,
+  AppSelectLabel,
+} from "@/components/primitives/AppSelect"
+```
+
+## AppSelect
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `defaultValue` | `string` | - | The value of the select that should be open by default. |
+| `onValueChange` | `(value: string) => void` | - | Event handler called when the value changes. |
+
+## AppSelectTrigger
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `loading` | `boolean` | `false` | If true, shows a spinner and disables the trigger. |
+
+## Usage
+
+### Basic Select
+```tsx
+<AppSelect>
+  <AppSelectTrigger className="w-48">
+    <AppSelectValue placeholder="Select a fruit" />
+  </AppSelectTrigger>
+  <AppSelectContent>
+    <AppSelectItem value="apple">Apple</AppSelectItem>
+    <AppSelectItem value="banana">Banana</AppSelectItem>
+    <AppSelectItem value="blueberry">Blueberry</AppSelectItem>
+  </AppSelectContent>
+</AppSelect>
+```
+
+### Grouped options
+```tsx
+<AppSelect>
+  <AppSelectTrigger className="w-48">
+    <AppSelectValue placeholder="Select a fruit" />
+  </AppSelectTrigger>
+  <AppSelectContent>
+    <AppSelectGroup>
+      <AppSelectLabel>Fruits</AppSelectLabel>
+      <AppSelectItem value="apple">Apple</AppSelectItem>
+      <AppSelectItem value="banana">Banana</AppSelectItem>
+    </AppSelectGroup>
+    <AppSelectGroup>
+      <AppSelectLabel>Vegetables</AppSelectLabel>
+      <AppSelectItem value="carrot">Carrot</AppSelectItem>
+      <AppSelectItem value="broccoli">Broccoli</AppSelectItem>
+    </AppSelectGroup>
+  </AppSelectContent>
+</AppSelect>
+```
+
+### Loading State
+```tsx
+<AppSelect>
+  <AppSelectTrigger loading className="w-48">
+    <AppSelectValue placeholder="Loading options..." />
+  </AppSelectTrigger>
+  <AppSelectContent>
+    {/* Items would be here after loading */}
+  </AppSelectContent>
+</AppSelect>
+```
+
+## Rules
+
+- **Do** use `AppSelect` for picking a single value from a list of options.
+- **Do** use the `loading` prop on `AppSelectTrigger` when fetching data.
+- **Do** use `AppSelectGroup` + `AppSelectLabel` to group related options.
+- **Do** set trigger width explicitly via `className` (e.g. `className="w-48"`) — no default width.
+- **Don't** use raw `<select>` elements.
+- If a prop you need is missing, stop and inform the design team.

package/rules/separator.md

@@ -0,0 +1,43 @@
+# AppSeparator
+
+> Docs: https://ui-kit.vercel.app/docs/components/separator
+
+```tsx
+import { AppSeparator } from "@/components/primitives/AppSeparator"
+```
+
+## AppSeparator
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the separator. |
+| `decorative` | `boolean` | `true` | Whether the separator is purely decorative. If `false`, it's accessible to screen readers as a separator. |
+
+## Usage
+
+### Horizontal Separator
+```tsx
+<div className="space-y-4">
+  <p>Top section</p>
+  <AppSeparator />
+  <p>Bottom section</p>
+</div>
+```
+
+### Vertical Separator
+```tsx
+<div className="flex h-5 items-center space-x-4">
+  <div>Item 1</div>
+  <AppSeparator orientation="vertical" />
+  <div>Item 2</div>
+</div>
+```
+
+## Rules
+
+- **Do** use `AppSeparator` to visually divide content.
+- **Do** set `orientation="vertical"` when used within flex containers for side-by-side items.
+- **Don't** use raw `<hr />` tags for separation.
+- **Don't** use `AppSeparator` for purely layout purposes if a border on a container is more appropriate.
+
+If a prop you need is missing, stop and inform the design team.

package/rules/sheet.md

@@ -0,0 +1,76 @@
+# AppSheet
+
+> Docs: https://ui-kit.vercel.app/docs/components/sheet
+
+```tsx
+import {
+  AppSheet,
+  AppSheetTrigger,
+  AppSheetContent,
+  AppSheetHeader,
+  AppSheetTitle,
+  AppSheetDescription
+} from "@/components/primitives/AppSheet"
+```
+
+## AppSheet
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | - | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | - | Callback for open state changes. |
+| `defaultOpen` | `boolean` | - | Initial open state. |
+
+## AppSheetTrigger
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `asChild` | `boolean` | `false` | Change the rendered element to the child. |
+
+## AppSheetContent
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `side` | `"top" \| "bottom" \| "left" \| "right"` | `"right"` | The side the sheet slides from. |
+
+## Usage
+
+### Default Sheet
+```tsx
+<AppSheet>
+  <AppSheetTrigger asChild>
+    <AppButton variant="outline">Open Sheet</AppButton>
+  </AppSheetTrigger>
+  <AppSheetContent>
+    <AppSheetHeader>
+      <AppSheetTitle>Edit Profile</AppSheetTitle>
+      <AppSheetDescription>Make changes to your profile here.</AppSheetDescription>
+    </AppSheetHeader>
+    <div className="py-4">Profile edit form...</div>
+  </AppSheetContent>
+</AppSheet>
+```
+
+### Left Side Sheet
+```tsx
+<AppSheet>
+  <AppSheetTrigger asChild>
+    <AppButton variant="ghost">Menu</AppButton>
+  </AppSheetTrigger>
+  <AppSheetContent side="left">
+    <AppSheetHeader>
+      <AppSheetTitle>Navigation</AppSheetTitle>
+    </AppSheetHeader>
+    <nav>Links...</nav>
+  </AppSheetContent>
+</AppSheet>
+```
+
+## Rules
+
+- **Do** use `AppSheet` for secondary information or forms that don't fit in a standard dialog.
+- **Do** provide a clear `AppSheetTitle` and `AppSheetDescription` for accessibility.
+- **Don't** overfill the sheet with complex multi-step workflows.
+- **Don't** use `AppSheet` for small confirmation tasks; use `AppAlertDialog` instead.
+
+If a prop you need is missing, stop and inform the design team.