@skunkworksai/ui-kit 0.1.18 → 0.1.25-a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skunkworksai/ui-kit",
-  "version": "0.1.18",
+  "version": "0.1.25-a",
   "private": false,
   "type": "module",
   "main": "./dist/index.cjs",
@@ -48,7 +48,7 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@base-ui/react": "^1.3.0",
+    "@base-ui/react": "^1.5.0",
     "@radix-ui/react-accordion": "^1.2.0",
     "@radix-ui/react-alert-dialog": "^1.1.0",
     "@radix-ui/react-aspect-ratio": "^1.1.0",
@@ -62,7 +62,7 @@
     "@radix-ui/react-label": "^2.1.0",
     "@radix-ui/react-navigation-menu": "^1.2.0",
     "@radix-ui/react-popover": "^1.1.0",
-    "@radix-ui/react-progress": "^1.1.0",
+    "@radix-ui/react-progress": "^1.1.8",
     "@radix-ui/react-radio-group": "^1.1.0",
     "@radix-ui/react-scroll-area": "^1.1.0",
     "@radix-ui/react-select": "^2.1.0",
@@ -78,40 +78,50 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.0.0",
-    "date-fns": "^4.1.0",
+    "date-fns": "^4.4.0",
     "embla-carousel": "^8.6.0",
     "embla-carousel-react": "^8.6.0",
-    "lucide-react": "^0.577.0",
-    "motion": "^12.38.0",
+    "lucide-react": "^1.17.0",
+    "motion": "^12.40.0",
     "radix-ui": "^1.4.3",
-    "react-day-picker": "^9.4.0",
-    "react-hook-form": "^7.54.0",
+    "react-day-picker": "^10.0.1",
+    "react-hook-form": "^7.77.0",
     "recharts": "^3.8.1",
-    "shadcn": "^4.1.0",
-    "sonner": "^1.7.0",
-    "tailwind-merge": "^3.5.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.6.0",
     "tw-animate-css": "^1.4.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@storybook/addon-a11y": "^8",
     "@storybook/addon-docs": "^8",
     "@storybook/addon-onboarding": "^8",
     "@storybook/react": "^8",
     "@storybook/react-vite": "^8",
     "@tailwindcss/vite": "^4",
-    "@types/node": "^20",
+    "@types/node": "^25",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "@vitejs/plugin-react-swc": "^3",
-    "eslint": "^9",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
+    "@vitejs/plugin-react-swc": "^4",
+    "eslint": "^10",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.6.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "shadcn": "^4.10.0",
     "storybook": "^8",
     "tailwindcss": "^4",
     "tailwindcss-animate": "^1.0.7",
-    "typescript": "^5",
+    "typescript": "^6",
+    "typescript-eslint": "^8.60.1",
     "vite": "^6",
-    "vite-plugin-checker": "^0.9"
+    "vite-plugin-checker": "^0.14"
   },
-  "packageManager": "pnpm@10.32.1"
+  "packageManager": "pnpm@10.32.1",
+  "pnpm": {
+    "overrides": {
+      "ws@>=8.0.0 <8.20.1": ">=8.20.1"
+    }
+  }
 }

package/rules/button.md

@@ -61,6 +61,7 @@ import { AppButton } from "@/components/primitives/AppButton"
 - ✅ Use the `loading` prop for async actions — do not place `AppSpinner` inside manually
 - ✅ Use `iconLeft` / `iconRight` for icons — do not wrap icons in extra `<div>` or `<span>`
 - ✅ Use `variant` for color intent — do not override button color with Tailwind color classes
+- ✅ `AppButton` forwards refs to the underlying `<button>` element — safe to use as `asChild` child of Radix primitives (e.g. `PopoverTrigger`, `TooltipTrigger`)
 - ❌ Do not use `size="icon"` with text children — icon size is for icon-only buttons
 - ❌ Do not set `gap` or `flex` on the button — icon spacing is controlled by the size variant
 - ❌ If a prop you need is missing, stop and inform the design team

package/rules/dashboard.md

@@ -22,6 +22,7 @@ import { AppDashboard } from '@skunkworksai/ui-kit'
 | `background` | `ReactNode` | `<AppDashboardBackgroundWave />` | Background preset or custom component. Must render gradient. See Background presets section. |
 | `pageTitle` | `AppPageTitleProps \| false` | omitted | Page title bar below the header. Pass `false` to hide entirely. |
 | `brand` | `Omit<AppSidebarBrandProps, "className">` | `WhiteLogo` / `WhiteSymbol` | Props forwarded to `AppSidebarBrand`. Use to set a custom logo for expanded and collapsed sidebar states. |
+| `sidebarFooter` | `ReactNode` | `undefined` | Content rendered at the bottom of the sidebar inside `AppSidebarFooter`, before the rail. Omit to render no footer. |
 | `children` | `ReactNode` | required | Page content. |
 
 ## Customising the header
@@ -133,6 +134,58 @@ import { AppDashboardBackgroundWave, AppDashboardBackgroundDots } from '@skunkwo
 | `AppDashboardBackgroundWave` | Perlin noise wave grid + mouse-follow glow. Default. |
 | `AppDashboardBackgroundDots` | Uniform dot grid. Dots fade near cursor (closer = lower opacity). |
 
+### Background preset props
+
+Both presets share the following props in addition to `animated` and `interactive`:
+
+#### `AppDashboardBackgroundDots`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `string` | `--sidebar-ring` | Dot color. Any valid CSS color string: hex, oklch, hsl, or `var(--token)`. |
+
+#### `AppDashboardBackgroundWave`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `string` | `--sidebar-ring` | Wave line color. Any valid CSS color string: hex, oklch, hsl, or `var(--token)`. |
+| `glowColor` | `string` | `--sidebar-primary` / `--sidebar-accent` | Cursor glow color. Replaces both glow layers with a single color mixed at different opacities. |
+
+### Customizing background color
+
+```tsx
+import { AppDashboardBackgroundWave, AppDashboardBackgroundDots } from '@skunkworks-ai/ui-kit'
+
+// Wave with custom line + glow color (oklch, hex, hsl, or CSS variable — all valid)
+<AppDashboard background={
+  <AppDashboardBackgroundWave
+    color="oklch(0.75 0.18 150)"
+    glowColor="oklch(0.75 0.18 150)"
+  />
+}>
+  ...
+</AppDashboard>
+
+// Dots with custom dot color
+<AppDashboard background={
+  <AppDashboardBackgroundDots color="#ff6b35" />
+}>
+  ...
+</AppDashboard>
+
+// Using a design token from the consumer's theme
+<AppDashboard background={
+  <AppDashboardBackgroundWave
+    color="var(--brand-primary)"
+    glowColor="var(--brand-primary)"
+  />
+}>
+  ...
+</AppDashboard>
+```
+
+When `color` is omitted, both presets fall back to the resolved value of `--sidebar-ring`. When `glowColor` is omitted on Wave, the glow uses `--sidebar-primary` and `--sidebar-accent`.
+
 ### Custom background contract
 
 Custom backgrounds receive `animated`, `interactive`, and `themeClass` from `AppDashboardBackgroundContext`:
@@ -183,9 +236,11 @@ The canvas animation runs by default. Use `animated` to control it:
 
 **When `animated="auto"` (default):** animation runs normally unless the user's OS has `prefers-reduced-motion: reduce` set, in which case the canvas is skipped automatically. No consumer code needed for accessibility compliance.
 
-## AppThemeProvider requirement
+## AppThemeProvider
+
+`AppDashboard` includes `AppThemeProvider` internally — the theme toggle works out of the box with no extra setup required.
 
-The default header includes a theme toggle that requires `AppThemeProvider` in the tree:
+If you use `AppHeader` standalone (outside `AppDashboard`), wrap your layout with `AppThemeProvider` for the toggle to function:
 
 ```tsx
 import { AppThemeProvider } from '@skunkworksai/ui-kit'
@@ -201,8 +256,6 @@ export default function RootLayout({ children }) {
 }
 ```
 
-Without it, the toggle renders but does nothing.
-
 ## Nav types
 
 ```ts
@@ -345,6 +398,45 @@ const nav = [
 </AppDashboard>
 ```
 
+## Sidebar footer
+
+Use the `sidebarFooter` prop to render content at the bottom of the sidebar (inside `AppSidebarFooter`, before the rail). The consumer owns the markup — pass any `ReactNode`.
+
+```tsx
+// Wallet-style footer card
+<AppDashboard
+  sidebarFooter={
+    <div className="rounded-lg bg-sidebar-accent p-3 group-data-[collapsible=icon]:hidden">
+      <p className="text-xs font-medium text-sidebar-foreground">Acme Corp</p>
+      <p className="text-xs text-sidebar-foreground/60">Free plan · 3 seats</p>
+    </div>
+  }
+>
+  <PageContent />
+</AppDashboard>
+```
+
+Omitting `sidebarFooter` renders no `AppSidebarFooter` element at all — no extra whitespace.
+
+### Auto-hiding on icon collapse
+
+When the sidebar collapses to icon mode, content that doesn't make sense at 40 px wide should be hidden. Use the `group-data-[collapsible=icon]:hidden` Tailwind class on any element inside `sidebarFooter`:
+
+```tsx
+// The entire card hides when collapsed; nothing renders in icon mode
+<div className="... group-data-[collapsible=icon]:hidden">
+  ...
+</div>
+
+// Hide only the text, keep an avatar visible
+<div className="flex items-center gap-2">
+  <Avatar className="size-7 shrink-0" />
+  <span className="group-data-[collapsible=icon]:hidden text-sm">Kevin Aton</span>
+</div>
+```
+
+`group-data-[collapsible=icon]` matches the `data-collapsible="icon"` attribute set on the sidebar group element by `AppSidebarProvider` when the sidebar is collapsed to icon mode.
+
 ## Rules
 
 - **Do** use `AppDashboard` as the layout for every page — do not compose the scaffold manually.

package/rules/header.md

@@ -20,7 +20,7 @@ All right-side controls are included by default. Each can be removed or replaced
 |------|------|---------|-------------|
 | `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. |
+| `avatar` | `ReactNode` | `AppAvatar` with `UserRound` icon | 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. |
@@ -108,7 +108,7 @@ Use these only when building a layout outside `AppDashboard`:
 |-----------|---------|
 | `AppHeaderContent` | Inner flex container with padding and gap. |
 | `AppHeaderTitle` | Optional page label. `shrink-0`, never compresses. |
-| `AppHeaderSearchbar` | `flex-1` slot for search input groups. |
+| `AppHeaderSearchbar` | `flex-1 max-w-sm` slot for search input groups. Hidden on mobile (`hidden md:flex`) by default. |
 | `AppHeaderActions` | `ml-auto` right-side slot for controls. |
 | `AppHeaderNetworkCombobox` | Standalone network combobox — use inside a custom `actions` slot. |
 
@@ -163,6 +163,8 @@ Customize via the `header` prop — never import `AppHeader` directly for this:
 
 Only needed when building a custom layout that does not use `AppDashboard`:
 
+> **Note:** `AppThemeProvider` is required for the theme toggle to function. When using `AppHeader` inside `AppDashboard`, this is handled automatically. For standalone usage, wrap your layout with `AppThemeProvider`.
+
 ```tsx
 import { AppHeader, type NetworkOption } from '@skunkworks/ui'
 
@@ -197,6 +199,8 @@ With custom slots:
 
 The `searchbar` slot accepts any `ReactNode`. Always fill it with an `App*` component — never a raw `<input>`.
 
+`AppHeaderSearchbar` defaults to `hidden md:flex min-w-0 flex-1 max-w-sm`. The `max-w-sm` (384px) cap prevents searchbar content from stretching full-width when the consumer does not supply an explicit width. To widen, pass `className="max-w-md"` (or larger). Hidden on mobile — the mobile search icon + Sheet handles that path automatically.
+
 ```tsx
 // ✅ Correct
 import { AppInput } from '@skunkworksai/ui-kit'
@@ -226,6 +230,23 @@ import { AppInput } from '@skunkworksai/ui-kit'
 <AppDashboard header={{ searchbar: null }}>
 ```
 
+## Consumer Tailwind setup
+
+`AppHeader` uses `md:hidden` to hide the mobile search icon (`AppHeaderSearchbar`) at desktop widths. If the consumer's `@tailwindcss/vite` plugin injects its utilities layer **after** the ui-kit bundle, it overwrites same-named utilities and `md:hidden` stops working.
+
+**Required** — add this to the consumer's `app.css` (or equivalent global CSS entry):
+
+```css
+@layer theme, base, components, utilities;
+@import "tailwindcss/utilities" layer(utilities);
+```
+
+This explicitly names the `utilities` layer so both the ui-kit bundle and the consumer's Tailwind output merge into the same layer in document order.
+
+**Symptom of missing setup:** the mobile search icon is visible at all breakpoints instead of hiding at `md`.
+
+See `rules/tokens.md` for the full consumer setup checklist.
+
 ## Rules
 
 - **Do** provide `networks` with real data — the default 2-entry list is a demo placeholder only.

package/rules/input.md

@@ -12,10 +12,13 @@ import { AppInput } from "@/components/primitives/AppInput"
 |------|------|---------|-------------|
 | `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 |
+| `wrapperClassName` | `string` | — | Applied to the outer wrapper `<div>` when adornments are present. Use to override the default `w-full`. Silently ignored when no adornments are set. |
 | `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 |
+| `className` | `string` | — | Additional Tailwind classes applied to the inner `<input>` element |
+
+> `className` always routes to the inner `<input>`. Use `wrapperClassName` to control the outer wrapper size/layout when adornments are in use.
 
 > Accepts all standard HTML `<input>` attributes in addition to the props above.
 
@@ -43,6 +46,33 @@ import { AppInput } from "@/components/primitives/AppInput"
 />
 ```
 
+### Controlling wrapper width with adornments
+
+Without adornments `className` width classes land directly on `<input>`. With adornments you must use `wrapperClassName` — `className` targets the inner element and a width there does not constrain the wrapper.
+
+```tsx
+{/* Fixed width on desktop, full-width on mobile */}
+<AppInput
+  leftAdornment={<Search className="size-4" />}
+  placeholder="Search..."
+  wrapperClassName="w-full md:w-64"
+/>
+
+{/* Fill remaining space in a flex row */}
+<AppInput
+  leftAdornment={<Search className="size-4" />}
+  placeholder="Search..."
+  wrapperClassName="flex-1"
+/>
+
+{/* Intrinsic width */}
+<AppInput
+  leftAdornment={<Search className="size-4" />}
+  placeholder="Search..."
+  wrapperClassName="w-auto"
+/>
+```
+
 ### Disabled
 ```tsx
 <AppInput disabled placeholder="Not editable" />
@@ -59,8 +89,10 @@ import { AppInput } from "@/components/primitives/AppInput"
 ## 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
+- ✅ Use `wrapperClassName` to control width/layout when adornments are present — `className` targets the inner `<input>` only
 - ✅ 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
+- ❌ Do not add width classes via `className` when adornments are present — they land on `<input>`, not the wrapper; use `wrapperClassName` instead
+- ❌ `wrapperClassName` has no effect without adornments — without `leftAdornment` or `rightAdornment` there is no wrapper element
 - ❌ If a prop you need is missing, stop and inform the design team

package/rules/pagetitle.md

@@ -143,12 +143,44 @@ When `breadcrumbs` is omitted, the component reads `window.location.pathname` on
 </AppDashboard>
 ```
 
+## usePageTitle — ReactNode prop stability
+
+`usePageTitle` compares props by identity, not by value. Primitive props (`title`, `subtitle`, `titleColor`) are compared by value and are safe to pass inline. ReactNode props (`actions`, `breadcrumbs`, `icon`) are compared by **reference** — passing them as inline JSX causes the effect to re-run on every render.
+
+**Always memoize ReactNode props:**
+
+```tsx
+// ✅ Correct — stable reference
+const actions = React.useMemo(
+  () => <AppButton onClick={handleAdd}>+ Add Site</AppButton>,
+  [handleAdd]
+)
+usePageTitle({ title: "Sites", actions })
+
+// ✅ Also correct — module-scope constant (never changes)
+const BREADCRUMBS = [
+  { label: "Dashboard", href: "/" },
+  { label: "Sites" },
+]
+usePageTitle({ title: "Sites", breadcrumbs: BREADCRUMBS })
+
+// ❌ Wrong — new object/JSX every render, causes effect churn
+usePageTitle({
+  title: "Sites",
+  actions: <AppButton>+ Add Site</AppButton>,
+  breadcrumbs: [{ label: "Dashboard", href: "/" }, { label: "Sites" }],
+})
+```
+
+> **Note:** Earlier versions used `JSON.stringify` to compare deps, which crashed when ReactNode props contained circular references (e.g. React elements with `$$typeof`). The current implementation compares individual fields by identity — memoization is now required to avoid redundant effect re-runs rather than crashes.
+
 ## 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.
+- **Do** memoize `actions`, `breadcrumbs`, and `icon` when passing to `usePageTitle` — these are compared by identity and inline JSX re-runs the effect every render.
 - **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.

package/rules/sidebar.md

@@ -209,6 +209,27 @@ No background fill by default or on hover. The **primary brand color** backgroun
 | :--- | :--- | :--- | :--- |
 | `showIcon` | `boolean` | `false` | Show a skeleton icon placeholder. |
 
+## AppSidebarFooter
+
+Renders sticky content at the bottom of the sidebar column, below `AppSidebarContent` and above `AppSidebarRail`.
+
+**Used internally by `AppDashboard`:** when you pass the `sidebarFooter` prop to `AppDashboard`, the block wraps your content in `AppSidebarFooter` automatically. You do not need to add `AppSidebarFooter` yourself when using `AppDashboard`.
+
+**In custom layouts** (e.g. when composing `AppSidebar` directly without `AppDashboard`), place `AppSidebarFooter` as the last child of `AppSidebar` before `AppSidebarRail`:
+
+```tsx
+<AppSidebar collapsible="icon">
+  <AppSidebarHeader>...</AppSidebarHeader>
+  <AppSidebarContent>...</AppSidebarContent>
+  <AppSidebarFooter>
+    <span className="text-xs text-sidebar-foreground/50">v1.0.0</span>
+  </AppSidebarFooter>
+  <AppSidebarRail />
+</AppSidebar>
+```
+
+Use `group-data-[collapsible=icon]:hidden` on any child element to auto-hide it when the sidebar collapses to icon mode (see `rules/dashboard.md` for examples).
+
 ## useSidebar
 
 Returns `{ state, open, setOpen, openMobile, setOpenMobile, isMobile, toggleSidebar }`.

package/rules/table-manager.md

@@ -286,6 +286,44 @@ When `headerCell` is provided it fully replaces the header content (text + sort
 </TableManagerToolbarActions>
 ```
 
+## Props — TableManagerToolbar
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `layout` | `"wrap" \| "inline"` | `"wrap"` | Layout mode. See below. |
+| `className` | `string` | — | Extra classes on the toolbar wrapper. |
+
+### `layout` values
+
+| Value | Behaviour |
+|-------|-----------|
+| `"wrap"` | `flex-wrap` — children reflow to multiple rows on narrow viewports. Back-compatible default. |
+| `"inline"` | Mobile: search stacks above actions (`flex-col`). Desktop (md+): search + actions share one row with `justify-between`. Pair with `TableManagerSearch wrapperClassName="w-full md:w-64"` so the search does not stretch full-width on desktop. |
+
+### Responsive inline toolbar recipe
+
+```tsx
+<TableManagerToolbar layout="inline">
+  <TableManagerSearch wrapperClassName="w-full md:w-64" />
+  <TableManagerToolbarActions>
+    <TableManagerMultiFilter ... />
+    <TableManagerPagination />
+    <TableManagerColumnToggle />
+  </TableManagerToolbarActions>
+</TableManagerToolbar>
+```
+
+## Props — TableManagerSearch
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `placeholder` | `string` | `"Search..."` | Input placeholder. |
+| `debounceMs` | `number` | `300` | Debounce delay before `onSearchChange` fires. |
+| `wrapperClassName` | `string` | — | Forwarded to `AppInput.wrapperClassName`. Controls the outer wrapper width. Default `w-64`. |
+| `className` | `string` | — | Applied to the inner `<input>` element. |
+
+`wrapperClassName` overrides merge with the `w-64` default (later class wins via Tailwind Merge). Pass `wrapperClassName="w-full md:w-64"` for a mobile-first responsive width.
+
 ## Rules
 
 - ✅ Always wrap everything in `<TableManager>` before using any sub-component
@@ -295,12 +333,17 @@ When `headerCell` is provided it fully replaces the header content (text + sort
 - ✅ Implement OR logic in `onFilterChange` when a row can belong to multiple filter values
 - ✅ Set `type: "date"` on date columns and `type: "text"` on primary text columns so the default sort works correctly
 - ✅ Use `TableManagerToolbarActions` with `shrink-0` behavior built in — it will not compress when the search input grows
+- ✅ Use `layout="inline"` on `TableManagerToolbar` when search + actions + pagination must coexist on one row at md+
+- ✅ Pair `layout="inline"` with `wrapperClassName="w-full md:w-64"` on `TableManagerSearch` — otherwise search stretches full-width on desktop
 - ❌ Never import sub-components outside of a `<TableManager>` tree — they read from internal context and will throw
 - ❌ Never filter data internally in the block — always pass already-filtered data via the `data` prop
 - ❌ Never add `date-fns` or a date library just for this block — it uses native `Date` methods
 - ❌ Never use arbitrary CSS selectors (`:last-child`, `[&_th:last-child]`) to align column headers — use `headerAlign` / `headerCell` instead
+- ❌ Do not pass a width class via `TableManagerSearch className` to control the wrapper width — `className` targets the inner `<input>`; use `wrapperClassName` instead
 - ❌ If a prop you need is missing, stop and inform the design team
 
 ## Responsive
 
-`TableManagerToolbar` wraps with `flex-wrap` on small screens. `TableManagerToolbarActions` loses its `ml-auto` below `sm` and flows inline with other toolbar children. Wrapping is automatic — no consumer change needed.
+`TableManagerToolbar layout="wrap"` (default) wraps with `flex-wrap` on small screens. `TableManagerToolbarActions` loses its `ml-auto` below `sm` and flows inline with other toolbar children. Wrapping is automatic — no consumer change needed.
+
+`layout="inline"` gives explicit two-tier stacking: search on top on mobile, side-by-side on md+. Use this when `layout="wrap"` produces too many rows on narrow viewports.

package/rules/textarea.md

@@ -12,10 +12,21 @@ import { AppTextarea } from "@/components/primitives/AppTextarea"
 |------|------|---------|-------------|
 | `placeholder` | `string` | — | Placeholder text |
 | `disabled` | `boolean` | `false` | Disables the textarea |
-| `className` | `string` | — | Additional Tailwind classes |
+| `className` | `string` | — | Additional Tailwind classes. Merged after the built-in bg classes so your overrides always win. |
 
 > Accepts all standard HTML `<textarea>` attributes in addition to the props above.
 
+## Dark mode background
+
+`AppTextarea` applies `bg-transparent dark:bg-input/30` internally so the textarea surface is visible in dark mode, matching `AppInput`'s appearance. You do not need to add background classes for dark mode.
+
+`className` is merged last — pass a `bg-*` class to override the default for special cases.
+
+```tsx
+{/* Override background for a specific context */}
+<AppTextarea className="bg-card dark:bg-card" placeholder="Custom bg..." />
+```
+
 ## Usage
 
 ### Basic
@@ -31,8 +42,19 @@ import { AppTextarea } from "@/components/primitives/AppTextarea"
 </div>
 ```
 
+### Controlled height
+```tsx
+{/* Fixed height via rows */}
+<AppTextarea rows={6} placeholder="Detailed description..." />
+
+{/* Tailwind height class */}
+<AppTextarea className="h-40" placeholder="Notes..." />
+```
+
 ## Rules
 - ✅ Always use `AppTextarea` — never use a raw `<textarea>` element
 - ✅ Use `AppLabel` for accessibility
 - ✅ Control height via `rows` attribute or Tailwind `h-*` classes
+- ✅ Dark mode background is handled automatically — no `dark:bg-*` needed unless overriding
+- ❌ Do not add `dark:bg-transparent` to fix a dark-mode visibility issue — `AppTextarea` already applies `dark:bg-input/30` for parity with `AppInput`
 - ❌ If a prop you need is missing, stop and inform the design team