@skunkworksai/ui-kit 0.1.18

package/rules/calendar.md

@@ -0,0 +1,97 @@
+# AppCalendar
+
+> Docs: https://ui-kit.vercel.app/docs/components/calendar
+
+```tsx
+import { AppCalendar } from "@/components/primitives/AppCalendar"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `"single" \| "range"` | `"single"` | Selection mode |
+| `value` | `Date \| DateRange` | — | Controlled selected date(s) |
+| `onChange` | `(date) => void` | — | Change handler |
+| `popover` | `boolean` | `false` | Render as a popover trigger instead of inline |
+| `presets` | `{ label: string; days: number }[]` | `[]` | Quick-select preset buttons (popover only) |
+| `placeholder` | `string` | — | Trigger button label when no date selected (popover only) |
+| `numberOfMonths` | `number` | `1` | Months to display side by side |
+| `showWeekNumber` | `boolean` | `false` | Show ISO week numbers |
+| `disabled` | `boolean` | `false` | Disable the trigger button (popover only) |
+| `disabledDates` | `Matcher \| Matcher[]` | — | Disable specific dates in the calendar |
+
+## Usage
+
+### Inline (basic)
+```tsx
+<AppCalendar
+  mode="single"
+  value={date}
+  onChange={setDate}
+/>
+```
+
+### Inline range
+```tsx
+<AppCalendar
+  mode="range"
+  value={range}
+  onChange={setRange}
+  numberOfMonths={2}
+/>
+```
+
+### Popover date picker (built-in)
+```tsx
+<AppCalendar
+  mode="single"
+  popover
+  value={date}
+  onChange={setDate}
+  placeholder="Pick a date"
+  className="w-64"
+/>
+```
+
+### Popover with presets
+```tsx
+<AppCalendar
+  mode="single"
+  popover
+  value={date}
+  onChange={setDate}
+  presets={[
+    { label: "Today", days: 0 },
+    { label: "Tomorrow", days: 1 },
+    { label: "In a week", days: 7 },
+  ]}
+  className="w-64"
+/>
+```
+
+### Popover range picker
+```tsx
+<AppCalendar
+  mode="range"
+  popover
+  value={range}
+  onChange={setRange}
+  numberOfMonths={2}
+  className="w-64"
+/>
+```
+
+## Rules
+- ✅ Always use `mode` to specify the selection behavior
+- ✅ Use `popover` prop for a built-in dropdown date picker — no need to manually wrap in `AppPopover`
+- ✅ Use `presets` for quick-select shortcuts (popover mode only)
+- ✅ Use `numberOfMonths={2}` for range selection to improve usability
+- ✅ Set trigger width via `className` when using `popover` (e.g. `className="w-64"`) — no default width
+- ❌ Do not wrap `AppCalendar` in `AppPopover` manually — use the `popover` prop instead
+- ❌ Do not use `AppCalendar` for simple month/year selection — it is optimized for date selection
+- ❌ If a prop you need is missing, stop and inform the design team
+
+## Responsive
+
+On mobile (<768px) `numberOfMonths` is forced to `1` regardless of the prop value; on desktop the prop value is used (default `2` for range mode). Pass `numberOfMonths={1}` explicitly to opt out of the 2-month default on desktop without affecting mobile behavior.

package/rules/card.md

@@ -0,0 +1,84 @@
+# AppCard
+
+> Docs: https://ui-kit.vercel.app/docs/components/card
+
+```tsx
+import {
+  AppCard,
+  AppCardHeader,
+  AppCardTitle,
+  AppCardDescription,
+  AppCardAction,
+  AppCardContent,
+  AppCardFooter,
+} from "@/components/primitives/AppCard"
+```
+
+## AppCard
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `"default" \| "sm"` | `"default"` | Padding and spacing size (shadcn base prop) |
+| `padding` | `"default" \| "none" \| "sm" \| "md" \| "lg"` | `"default"` | Override internal padding for dense/media layouts |
+
+## Usage
+
+### Basic
+```tsx
+<AppCard>
+  <AppCardHeader>
+    <AppCardTitle>Project Update</AppCardTitle>
+    <AppCardDescription>Deploying to production tomorrow.</AppCardDescription>
+  </AppCardHeader>
+  <AppCardContent>
+    <p>Everything is looking good. All tests passed.</p>
+  </AppCardContent>
+  <AppCardFooter>
+    <AppButton>Dismiss</AppButton>
+  </AppCardFooter>
+</AppCard>
+```
+
+### With Action
+```tsx
+<AppCardHeader>
+  <AppCardTitle>Settings</AppCardTitle>
+  <AppCardDescription>Manage your account settings.</AppCardDescription>
+  <AppCardAction>
+    <AppButton variant="outline" size="sm">Edit</AppButton>
+  </AppCardAction>
+</AppCardHeader>
+```
+
+### Small Size
+```tsx
+<AppCard size="sm">
+  <AppCardHeader>
+    <AppCardTitle>Summary</AppCardTitle>
+  </AppCardHeader>
+  <AppCardContent>
+    <p>Compact card content.</p>
+  </AppCardContent>
+</AppCard>
+```
+
+### Dense / media layout
+```tsx
+<AppCard padding="none">
+  <img src="/feed.jpg" alt="Camera feed" className="h-40 w-full object-cover" />
+  <AppCardHeader>
+    <AppCardTitle>Camera 01</AppCardTitle>
+  </AppCardHeader>
+</AppCard>
+```
+
+`padding` values: `"default"` (24px), `"none"` (0), `"sm"` (12px), `"md"` (16px), `"lg"` (32px).
+
+## Rules
+- ✅ Use `AppCardAction` for actions that should live in the header (aligned top-right)
+- ✅ Use `AppCardHeader` to group Title, Description, and Action together
+- ✅ Use `AppCard` as the standard container for grouped information
+- ✅ Use `padding="none"` for flush media cards (camera feeds, image-first layouts)
+- ❌ Do not nest multiple `AppCard` components unless visually distinct
+- ❌ Do not use `!important` overrides on Card children — use the `padding` prop instead
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/carousel.md

@@ -0,0 +1,113 @@
+# AppCarousel
+
+> Docs: https://ui-kit.vercel.app/docs/components/carousel
+
+```tsx
+import {
+  AppCarousel,
+  AppCarouselContent,
+  AppCarouselItem,
+  AppCarouselPrevious,
+  AppCarouselNext,
+  type AppCarouselApi,
+  useAppCarousel,
+} from "@skunkworksai/ui-kit"
+```
+
+## AppCarousel
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Scroll axis. |
+| `opts` | `EmblaOptionsType` | — | Embla configuration object (align, loop, etc.). |
+| `setApi` | `(api: AppCarouselApi) => void` | — | Callback to receive the Embla API instance for programmatic control. |
+| `plugins` | `EmblaPluginType[]` | — | Embla plugins (e.g. autoplay). |
+
+## AppCarouselContent
+
+Accepts all `div` props. The scrollable slide container — wrap `AppCarouselItem` children inside.
+
+## AppCarouselItem
+
+Accepts all `div` props. Use `className="basis-1/2"` (or `basis-1/3`, etc.) to show multiple slides at once.
+
+## AppCarouselPrevious / AppCarouselNext
+
+Accepts all `button` props. Positioned absolutely — ensure the parent (`AppCarousel`) has enough horizontal padding (e.g. `px-14`) so buttons don't overlap slide content.
+
+## Usage
+
+### Basic
+```tsx
+<div className="px-14 max-w-sm">
+  <AppCarousel>
+    <AppCarouselContent>
+      {items.map((item, i) => (
+        <AppCarouselItem key={i}>
+          <AppCard>
+            <AppCardContent className="flex aspect-square items-center justify-center p-6">
+              {item}
+            </AppCardContent>
+          </AppCard>
+        </AppCarouselItem>
+      ))}
+    </AppCarouselContent>
+    <AppCarouselPrevious />
+    <AppCarouselNext />
+  </AppCarousel>
+</div>
+```
+
+### Multiple slides visible
+```tsx
+<AppCarousel opts={{ align: "start" }}>
+  <AppCarouselContent>
+    {items.map((item, i) => (
+      <AppCarouselItem key={i} className="basis-1/3">
+        ...
+      </AppCarouselItem>
+    ))}
+  </AppCarouselContent>
+  <AppCarouselPrevious />
+  <AppCarouselNext />
+</AppCarousel>
+```
+
+### Vertical orientation
+```tsx
+<AppCarousel orientation="vertical" className="max-h-64">
+  <AppCarouselContent className="-mt-1 h-64">
+    {items.map((item, i) => (
+      <AppCarouselItem key={i} className="pt-1 basis-1/3">
+        ...
+      </AppCarouselItem>
+    ))}
+  </AppCarouselContent>
+  <AppCarouselPrevious />
+  <AppCarouselNext />
+</AppCarousel>
+```
+
+### Programmatic API access
+```tsx
+const [api, setApi] = React.useState<AppCarouselApi>()
+const [current, setCurrent] = React.useState(0)
+
+React.useEffect(() => {
+  if (!api) return
+  setCurrent(api.selectedScrollSnap() + 1)
+  api.on("select", () => setCurrent(api.selectedScrollSnap() + 1))
+}, [api])
+
+<AppCarousel setApi={setApi}>...</AppCarousel>
+<p>Slide {current} of {api?.scrollSnapList().length}</p>
+```
+
+## Rules
+- ✅ Always wrap `AppCarouselPrevious` / `AppCarouselNext` inside `AppCarousel` — they use carousel context
+- ✅ Add horizontal padding (e.g. `px-14`) to the container when using nav buttons in horizontal mode
+- ✅ Add vertical padding (e.g. `py-14`) when using nav buttons in vertical mode
+- ✅ Use `opts={{ loop: true }}` for infinite looping
+- ✅ Use `setApi` to get the Embla instance for programmatic scroll, event listeners, or slide counters
+- ❌ Do not use `AppCarouselPrevious` / `AppCarouselNext` outside an `AppCarousel` — they require its context
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/chart.md

@@ -0,0 +1,125 @@
+# AppChart
+
+> Docs: https://ui-kit.vercel.app/docs/components/chart
+
+```tsx
+import {
+  AppChartContainer,
+  AppChartTooltip,
+  AppChartTooltipContent,
+  AppChartLegend,
+  AppChartLegendContent,
+  AppChartStyle,
+  type AppChartConfig,
+  // Recharts chart + shape components re-exported:
+  BarChart, Bar, LineChart, Line, AreaChart, Area,
+  PieChart, Pie, Cell, CartesianGrid, XAxis, YAxis,
+} from "@skunkworksai/ui-kit"
+```
+
+## AppChartContainer
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `AppChartConfig` | required | Color and label mappings for each data key. |
+| `className` | `string` | — | Must include a height constraint (`min-h-*` or `aspect-*`). |
+| `children` | `ReactElement` | required | A single Recharts chart component (BarChart, LineChart, etc.). |
+
+## AppChartTooltipContent
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `indicator` | `"dot" \| "line" \| "dashed"` | `"dot"` | Color swatch shape. |
+| `nameKey` | `string` | — | Config key to look up labels. Set when `dataKey` ≠ config key (e.g. Pie charts). |
+| `hideLabel` | `boolean` | `false` | Hides the series label row. |
+
+## AppChartLegendContent
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `nameKey` | `string` | — | Config key for label lookup. Set when `dataKey` ≠ config key (e.g. Pie charts). |
+
+## AppChartConfig
+
+```ts
+type AppChartConfig = {
+  [key: string]: {
+    label: string
+    color?: string          // CSS variable: "var(--chart-1)"
+    theme?: {               // or per-theme colors
+      light: string
+      dark: string
+    }
+    icon?: React.ComponentType
+  }
+}
+```
+
+Inside Recharts, reference colors as `var(--color-{key})` — e.g. `var(--color-desktop)`.
+
+## Usage
+
+### Bar chart
+```tsx
+const chartConfig = {
+  desktop: { label: "Desktop", color: "var(--chart-1)" },
+  mobile: { label: "Mobile", color: "var(--chart-2)" },
+} satisfies AppChartConfig
+
+<AppChartContainer config={chartConfig} className="min-h-[250px] w-full">
+  <BarChart data={data} accessibilityLayer>
+    <CartesianGrid vertical={false} />
+    <XAxis dataKey="month" tickLine={false} axisLine={false} tickMargin={8} />
+    <AppChartTooltip content={<AppChartTooltipContent />} />
+    <AppChartLegend content={<AppChartLegendContent />} />
+    <Bar dataKey="desktop" fill="var(--color-desktop)" radius={4} />
+    <Bar dataKey="mobile" fill="var(--color-mobile)" radius={4} />
+  </BarChart>
+</AppChartContainer>
+```
+
+### Line chart
+```tsx
+<AppChartContainer config={chartConfig} className="min-h-[250px] w-full">
+  <LineChart data={data} accessibilityLayer>
+    <CartesianGrid vertical={false} />
+    <XAxis dataKey="month" tickLine={false} axisLine={false} tickMargin={8} />
+    <YAxis tickLine={false} axisLine={false} tickMargin={8} />
+    <AppChartTooltip content={<AppChartTooltipContent />} />
+    <AppChartLegend content={<AppChartLegendContent />} />
+    <Line dataKey="desktop" stroke="var(--color-desktop)" strokeWidth={2} dot={false} />
+    <Line dataKey="mobile" stroke="var(--color-mobile)" strokeWidth={2} dot={false} />
+  </LineChart>
+</AppChartContainer>
+```
+
+### Pie chart
+```tsx
+const pieConfig = {
+  Chrome: { label: "Chrome", color: "var(--chart-1)" },
+  Firefox: { label: "Firefox", color: "var(--chart-2)" },
+} satisfies AppChartConfig
+
+<AppChartContainer config={pieConfig} className="min-h-[250px] w-full">
+  <PieChart accessibilityLayer>
+    <AppChartTooltip content={<AppChartTooltipContent nameKey="name" />} />
+    <AppChartLegend content={<AppChartLegendContent nameKey="name" />} />
+    <Pie data={pieData} dataKey="value" nameKey="name" outerRadius={80}>
+      {pieData.map((entry) => (
+        <Cell key={entry.name} fill={pieConfig[entry.name as keyof typeof pieConfig]?.color} />
+      ))}
+    </Pie>
+  </PieChart>
+</AppChartContainer>
+```
+
+## Rules
+- ✅ Always set a height constraint on `AppChartContainer` (`min-h-[250px]`, `aspect-video`, etc.)
+- ✅ Add `accessibilityLayer` to every Recharts chart component
+- ✅ Use `var(--chart-1)` through `var(--chart-5)` as color values in config — never hardcode colors
+- ✅ Reference colors inside the chart as `var(--color-{key})` (e.g. `var(--color-desktop)`)
+- ✅ For Pie charts, set `nameKey` on both `AppChartTooltipContent` and `AppChartLegendContent` so labels resolve correctly
+- ✅ Use `satisfies AppChartConfig` on your config object for type safety
+- ❌ Do not import from `recharts` directly — import Recharts components from `@skunkworksai/ui-kit`
+- ❌ Do not hardcode color values in `fill` or `stroke` — always use `var(--color-{key})`
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/checkbox.md

@@ -0,0 +1,49 @@
+# AppCheckbox
+
+> Docs: https://ui-kit.vercel.app/docs/components/checkbox
+
+```tsx
+import { AppCheckbox } from "@/components/primitives/AppCheckbox"
+```
+
+## AppCheckbox
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `checked` | `boolean \| "indeterminate"` | - | The controlled checked state of the checkbox. |
+| `defaultChecked` | `boolean` | - | The checked state of the checkbox when it is initially rendered. |
+| `onCheckedChange` | `(checked: boolean \| "indeterminate") => void` | - | Event handler called when the checked state of the checkbox changes. |
+| `disabled` | `boolean` | - | When true, prevents the user from interacting with the checkbox. |
+| `required` | `boolean` | - | When true, indicates that the user must check the checkbox before the owning form can be submitted. |
+| `name` | `string` | - | The name of the checkbox. Submitted with its owning form as part of a name/value pair. |
+| `value` | `string` | `"on"` | The value given as data to the checkbox when submitted in a form. |
+
+## Usage
+
+### Default Checkbox
+```tsx
+<div className="flex items-center gap-2">
+  <AppCheckbox id="terms" />
+  <label htmlFor="terms" className="text-sm font-medium">
+    Accept terms and conditions
+  </label>
+</div>
+```
+
+### Disabled State
+```tsx
+<div className="flex items-center gap-2">
+  <AppCheckbox id="disabled-terms" disabled />
+  <label htmlFor="disabled-terms" className="text-sm font-medium opacity-50">
+    Disabled checkbox
+  </label>
+</div>
+```
+
+## Rules
+
+- **Do** use `AppCheckbox` for all checkbox needs.
+- **Do** always provide a corresponding label for accessibility.
+- **Don't** use the raw HTML `<input type="checkbox">`.
+- **Don't** manually style the checkbox unless absolutely necessary.
+- If a prop you need is missing, stop and inform the design team.

package/rules/collapsible.md

@@ -0,0 +1,57 @@
+# AppCollapsible
+
+> Docs: https://ui-kit.vercel.app/docs/components/collapsible
+
+```tsx
+import { 
+  AppCollapsible, 
+  AppCollapsibleTrigger, 
+  AppCollapsibleContent 
+} from "@/components/primitives/AppCollapsible"
+```
+
+## AppCollapsible
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `open` | `boolean` | - | The controlled open state of the collapsible. |
+| `defaultOpen` | `boolean` | - | The open state of the collapsible when it is initially rendered. |
+| `onOpenChange` | `(open: boolean) => void` | - | Event handler called when the open state of the collapsible changes. |
+| `disabled` | `boolean` | - | When true, prevents the user from interacting with the collapsible. |
+
+## AppCollapsibleTrigger
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `asChild` | `boolean` | `false` | Change the default rendered element for the one passed as a child, merging their props and behavior. |
+
+## AppCollapsibleContent
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `forceMount` | `boolean` | - | Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries. |
+
+## Usage
+
+### Simple Collapsible
+```tsx
+const [isOpen, setIsOpen] = React.useState(false)
+
+<AppCollapsible open={isOpen} onOpenChange={setIsOpen}>
+  <AppCollapsibleTrigger asChild>
+    <AppButton variant="ghost">Toggle Content</AppButton>
+  </AppCollapsibleTrigger>
+  <AppCollapsibleContent>
+    <div className="p-4 border rounded-md">
+      Hidden information revealed!
+    </div>
+  </AppCollapsibleContent>
+</AppCollapsible>
+```
+
+## Rules
+
+- **Do** use `AppCollapsible` for showing/hiding additional content.
+- **Do** use `asChild` on the trigger if you want to use a custom component like `AppButton`.
+- **Don't** use `AppCollapsible` for complex menus; use `AppAccordion` or `AppNavigationMenu` instead.
+- If a prop you need is missing, stop and inform the design team.

package/rules/combobox.md

@@ -0,0 +1,133 @@
+# AppCombobox
+
+> Docs: https://ui-kit.vercel.app/docs/components/combobox
+
+```tsx
+import {
+  AppCombobox,
+  AppComboboxInput,
+  AppComboboxContent,
+  AppComboboxList,
+  AppComboboxItem,
+  AppComboboxEmpty,
+  AppComboboxSeparator,
+} from "@skunkworksai/ui-kit"
+```
+
+## AppCombobox
+
+Root provider. Manages open state, search state, selection, and filtering.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `readonly string[]` | — | **Required.** Flat list of option values. |
+| `value` | `string` \| `string[]` | — | Controlled selected value(s). |
+| `onValueChange` | `(value: string) => void` \| `(value: string[]) => void` | — | Selection change handler. |
+| `multiple` | `boolean` | `false` | Enables multi-select. `value` becomes `string[]`. |
+| `filter` | `(item: string, search: string) => boolean` | case-insensitive substring | Custom filter function. |
+| `getDisplayValue` | `(value: string \| string[]) => string \| null` | — | Maps selected value(s) to display text in the trigger. |
+| `disabled` | `boolean` | `false` | Disables the entire combobox. |
+
+## AppComboboxInput
+
+Trigger button. Shows current selection or placeholder.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placeholder` | `string` | `"Select..."` | Shown when nothing is selected. |
+| `className` | `string` | — | Additional Tailwind classes. |
+
+## AppComboboxContent
+
+Popover panel. Contains search input and item list.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `searchPlaceholder` | `string` | `"Search..."` | Placeholder inside the search input. |
+| `align` | `"start"` \| `"center"` \| `"end"` | `"start"` | Popover alignment relative to trigger. |
+| `sideOffset` | `number` | `4` | Vertical gap between trigger and popover (px). |
+
+## AppComboboxList
+
+Renders filtered items via a render-prop function.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `(item: string) => ReactNode` | — | **Required.** Render function per item value. |
+
+## AppComboboxItem
+
+Single selectable option. Shows a checkmark when selected.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | **Required.** Must match a value in `items`. |
+
+## AppComboboxEmpty
+
+Shown when no items match the current search.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | `"No results found."` | Empty-state message. |
+
+## AppComboboxSeparator
+
+Visual divider between groups of items.
+
+## Usage
+
+### Single select with label mapping
+```tsx
+const options = [
+  { value: "next", label: "Next.js" },
+  { value: "remix", label: "Remix" },
+]
+const values = options.map((o) => o.value)
+const labelOf = (v: string) => options.find((o) => o.value === v)?.label ?? v
+
+<AppCombobox
+  items={values}
+  value={selected}
+  onValueChange={setSelected}
+  getDisplayValue={(v) => (v ? labelOf(v as string) : null)}
+  filter={(item, search) => labelOf(item).toLowerCase().includes(search.toLowerCase())}
+>
+  <AppComboboxInput placeholder="Select framework..." />
+  <AppComboboxContent searchPlaceholder="Search...">
+    <AppComboboxEmpty>No framework found.</AppComboboxEmpty>
+    <AppComboboxList>
+      {(item) => <AppComboboxItem value={item}>{labelOf(item)}</AppComboboxItem>}
+    </AppComboboxList>
+  </AppComboboxContent>
+</AppCombobox>
+```
+
+### Multi-select
+```tsx
+<AppCombobox
+  multiple
+  items={values}
+  value={selected}
+  onValueChange={setSelected}
+  getDisplayValue={(v) => {
+    const arr = (v as string[]) ?? []
+    return arr.length ? arr.map(labelOf).join(", ") : null
+  }}
+>
+  <AppComboboxInput placeholder="Select frameworks..." />
+  <AppComboboxContent>
+    <AppComboboxEmpty>No results.</AppComboboxEmpty>
+    <AppComboboxList>
+      {(item) => <AppComboboxItem value={item}>{labelOf(item)}</AppComboboxItem>}
+    </AppComboboxList>
+  </AppComboboxContent>
+</AppCombobox>
+```
+
+## Rules
+- ✅ Always pass `items` as `string[]` — use `getDisplayValue` + `filter` for label mapping
+- ✅ Always render `AppComboboxEmpty` inside `AppComboboxContent`
+- ✅ Always use `AppComboboxList` render-prop to map items to `AppComboboxItem`
+- ❌ Never use a raw `<select>` or custom dropdown — use `AppCombobox`
+- ❌ If a prop you need is missing, stop and inform the design team