@pilotiq/pilotiq 0.24.2 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @pilotiq/pilotiq
 
+## 0.25.0
+
+### Minor Changes
+
+- a7c0ffd: feat(pilotiq): align form controls to the shadcn input/button spec + tighter default spacing
+
+  Brings every text/control surface onto the shadcn component look for a more consistent, denser admin UI:
+
+  - **Inputs / Select / Textarea / field inputs** (`Input`, `SelectTrigger`, `Textarea`, plus the `DateField` trigger, `ColorPicker` swatch, `TagsInput`, and the Tiptap text chrome) → `h-8`, `rounded-lg`, `px-2.5`, `ring-3` focus, no drop shadow — matching the shadcn.com control set. The standalone `<Input>` was previously `h-9`.
+  - **Filters & Actions buttons** now use the shared shadcn button styling: the table toolbar's Filters triggers render via `buttonVariants({ variant: 'outline' })` (wrapped in `cn()` so `tailwind-merge` keeps the outline border), and `actionButtonClass` emits the `<Button>` chrome (`rounded-lg`, focus ring, `active:translate-y-px`, `h-8`/`h-7`/`h-9` sizes) while keeping the richer Action color palette (primary/destructive/success/warning/info + outlined).
+  - **Toolbar consistency**: the group-by / sort pickers drop `size="sm"` so they render at the default `h-8`, matching the search input.
+  - **Default spacing** density tightened — the default `vega` preset now resolves `--spacing` to `0.25rem` (Tailwind's stock unit) instead of `0.3rem`, so every `p-*`/`gap-*`/`m-*` tightens uniformly. Matches the theme-editor preview, which already used `0.25rem`.
+
+  No public API changes.
+
+- e9e7dbb: feat(pilotiq): sidebar layout options + palette-driven stat sparklines
+
+  - `Pilotiq.layout('sidebar', opts?)` is now overloaded so the sidebar chrome options bind to the `'sidebar'` mode: `variant: 'sidebar' | 'floating' | 'inset'`, `collapsible: 'offcanvas' | 'icon' | 'none'`, `side: 'left' | 'right'` (defaults `inset` / `icon` / `left`). `.layout('topbar', {...})` is a compile error so sidebar-only config can't silently no-op under topbar. The sticky page header gains `border-b bg-background/95 backdrop-blur`; the `md:rounded-t-xl` float applies only to `variant: 'inset'`.
+  - `StatsOverview` sparklines render as soft area-fills and default to the theme chart palette.
+
+- 8e4dc9f: feat(pilotiq): simplify the panel topbar — search right, breadcrumb in the header, theme + notifications in the user menu
+
+  The sticky header chrome is consolidated:
+
+  - **Search** moves to the right cluster (sidebar layout); the left now holds just the sidebar toggle.
+  - **Breadcrumb** is hoisted into the header next to the toggle (sidebar layout) and removed from the page body. Wired SSR-correctly — the auto-gen `+Layout` extracts the `breadcrumbs` element from `schemaData` and passes it to the header, so it paints on first load and updates on SPA nav. The topbar layout (and any custom header slot) keeps the breadcrumb in the body.
+  - **Theme toggle** moves into the user dropdown as a row (stays open on click).
+  - **Database notifications** fold into the user dropdown as a "Notifications" submenu carrying the full inbox list; an unread dot shows on the avatar. The standalone `<NotificationBell>` is retained for the `databaseNotificationsPosition('sidebar')` placement.
+
+  New: `DropdownMenuSub` / `DropdownMenuSubTrigger` / `DropdownMenuSubContent` primitives, a shared `useNotifications()` hook + `NotificationList` component (extracted from `NotificationBell`), an exported `BreadcrumbsView`, and a `breadcrumb` prop on `AppShell` / `UserMenu`'s new optional `notifications` prop. No breaking public API.
+
+### Patch Changes
+
+- 184951e: refactor(pilotiq): route dialog / action-group / inline-create buttons through the shadcn `<Button>`
+
+  The remaining hand-rolled `h-9` buttons that bypassed the shared component now use `<Button>`, so they pick up the shadcn chrome (`h-8`, `rounded-lg`, focus ring, active-press) and stay consistent with the rest of the panel: the confirm/cancel buttons in `ActionModalDialog` and `ConfirmActionDialog`, the confirm dialog inside `ActionGroup`, and the `SelectField` inline-create trigger/cancel/submit. Modal confirm CTAs keep their intentional **solid-red** styling (a className override on the default variant) rather than the soft inline `destructive` variant.
+
+- ac7a567: fix(pilotiq): resolve the live panel in the reactive form POST endpoints too — dev edits reflect without a restart
+
+  Follow-up to the SSR/render-data `livePanel()` fix. The four interactive form builders (`formStateData`, `formWizardData`, `formCreateOptionData`, `mentionResolveData`) still passed their registration-time `Pilotiq` closure straight through, so editing a `live()` field's `options(fn)`, an `afterStateUpdated` hook, a wizard step's validators, an inline-create form, or a mention resolver reflected on the initial SSR render but not on the subsequent partial-resolve / step-validate / create-option / mention roundtrip until a server restart. Each now re-resolves via `livePanel()` at request time, matching the chrome and render-data builders.
+
+## 0.24.3
+
+### Patch Changes
+
+- 02d5793: fix(pilotiq): panel routes resolve the live panel at request time — dev edits reflect without a server restart
+
+  Panel route handlers closed over the `Pilotiq` instance captured when their routes were registered. In dev, editing the panel module (or a resource/page schema it imports) re-registers a fresh panel in `PilotiqRegistry`, but those already-registered handler closures kept pointing at the stale instance — so SSR-rendered chrome and schema lagged a reload behind (the panel only updated after editing some _other_ watched file, or a restart).
+
+  The render-data layer now re-resolves the panel from `PilotiqRegistry` by name at request time, via a new `livePanel()` helper, applied at the top of `panelInfo` (chrome) and every render-data builder (`resourcePages`, `misc`, `relationPages`). This mirrors what `dispatchPageData()` already did for the client-nav path; the SSR route path was the only outlier. `livePanel()` falls back to the passed instance when the registry has no entry (tests, teardown), so non-dev behavior is unchanged.
+
+- 539c87a: feat(pilotiq): ship `pilotiq-actions` boost skill — Phase B residual #1
+
+  First of the four still-open Phase B skill candidates. `SKILL.md` declares `appliesTo: ['@pilotiq/pilotiq']` so `@rudderjs/boost`'s `boost:install` writes it under `.ai/skills/` only when the consumer has `@pilotiq/pilotiq` installed. Trigger scopes to specific action-authoring contexts — adding header/row/bulk buttons, wiring a modal-form action, customizing per-row visibility, reaching for a built-in factory.
+
+  Three rule files under `boost/skills/pilotiq-actions/rules/`:
+
+  - **`dispatch-modes.md`** — 4 mutually-exclusive modes (`href` / `method` / `handler` / `submit`), modal-form as a flavor of handler, return shape, `ctx` shape, 12 modal chrome setters, `.confirm()` + `.formField()` interactions.
+  - **`visibility-and-authorization.md`** — 4 conditional setters (`visible / hidden / disabled / authorize`), `ActionVisibilityContext`, fail-closed semantics (opposite of layout-visible), per-row gating cost model, composing with Resource policies.
+  - **`factories.md`** — 25 pre-built factories (`create / edit / view / delete / replicate / restore / forceDelete / markAsRead`, bulk variants, `import / export`, relation\* variants including M2M `attach / detach`), `ReplicateOptions` with `getCreatedNotificationTitle / getRedirectUrl` callbacks, when to skip factories for compound flows.
+
+  Mirrors the shape established by `pilotiq-resource` / `pilotiq-fields` / `pilotiq-relations` / `pilotiq-tiptap-blocks`.
+
+  Remaining Phase B residuals (lower priority — `guidelines.md` already covers most of what they'd add): `pilotiq-widgets`, `pilotiq-theme`, `pilotiq-vite-plugin`.
+
 ## 0.24.2
 
 ### Patch Changes

package/boost/guidelines.md

@@ -442,12 +442,17 @@ Client-only reactivity (no server round-trip): `afterStateUpdatedJs(`$set('slug'
 Pilotiq.make('Admin')
   .branding({ name: 'Acme', logo: '/logo.svg', primaryColor: '#3b82f6' })
   .theme('nova')                                                // built-in preset
-  .layout('sidebar')                                            // 'sidebar' | 'topbar'
+  .layout('sidebar', { variant: 'inset', collapsible: 'icon', side: 'left' }) // see below
   .use(themeEditor())                                           // exposes /admin/theme runtime editor
 ```
 
 Presets: `default`, `nova`, `maia`, `lyra`. Custom themes pass a `Theme` object to `.theme()`.
 
+**`.layout(mode, opts?)`** — `mode` is `'sidebar' | 'topbar'`. The optional second arg configures the sidebar's chrome and is **bound to the `'sidebar'` mode**: `.layout('topbar', {...})` is a compile error (so sidebar-only config can't silently no-op under topbar). Sidebar keys (all optional):
+- `variant`: `'inset'` (default — content floats in a rounded card) · `'floating'` (sidebar itself floats) · `'sidebar'` (classic full-height flush rail)
+- `collapsible`: `'icon'` (default — collapses to an icon rail) · `'offcanvas'` (slides fully off-screen) · `'none'` (always expanded)
+- `side`: `'left'` (default, RTL-aware) · `'right'`
+
 Plugin-shaped extensions: `.plugins([tiptap(), codeEditor(), recharts()])` — register adapter packages in one call.
 
 ## Common Pitfalls

package/boost/skills/pilotiq-actions/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: pilotiq-actions
+description: Buttons, modal-form actions, and built-in CRUD/import/export/relation factories in pilotiq — the 4 dispatch modes, visibility/authorize layers, and per-row gating
+license: MIT
+appliesTo:
+  - '@pilotiq/pilotiq'
+trigger: adding header / row / bulk action buttons to a `Resource.table()` / page, wiring a modal-form action, customizing per-row visibility via `visible()` / `authorize()`, or using one of the `Action.*` factories (`create` / `edit` / `delete` / `replicate` / `import` / `export` / `relation*` / `bulk*`)
+skip: customizing the form schema itself (use `pilotiq-fields`) or wiring a relation tab as a whole (use `pilotiq-relations`)
+metadata:
+  author: pilotiq
+---
+
+# Pilotiq Actions
+
+## When to use this skill
+
+Load when you're:
+
+- Adding action buttons to a page — header actions, row actions, bulk actions, inline actions
+- Wiring a modal-form action (`Action.make('foo').schema([Field…]).handler(ctx => …)`)
+- Customizing chrome (colors, sizes, icons, tooltips, outlined / icon-only / destructive)
+- Setting visibility / disabled / authorize rules — including per-row gating that re-evaluates on every list row
+- Reaching for a built-in factory: `Action.create / edit / view / delete / replicate / import / export / restore / forceDelete / markAsRead / bulkDelete / bulkRestore / bulkForceDelete / bulkReplicate / bulkExport / relation*`
+
+For the form schema *inside* an action's modal, that's `pilotiq-fields`. For the resource-side `Resource.table().recordActions([…])` wiring, this skill covers the action surface itself; `pilotiq-resource` covers when to subclass `ListPage` to override `getHeaderActions()` etc.
+
+## Quick Reference
+
+| Task | Open |
+|---|---|
+| 4 dispatch modes — `href` / `method` / `handler` / `submit`; modal-form via `.schema([…]).handler()`; `formField` for submit-button pairs | `rules/dispatch-modes.md` |
+| Visibility, disabled, authorize — `ActionVisibilityContext`, per-row gating, fail-closed semantics, async predicates | `rules/visibility-and-authorization.md` |
+| Built-in factories — `Action.create / .edit / .delete / .replicate / .import / .export / .relation*` plus bulk variants; chrome + visibility defaults | `rules/factories.md` |
+
+## Key concepts (load once)
+
+- **Every action is `Action.make(name).<setters>`.** No subclassing. The `name` is the discriminator for visibility lookups + the dispatch URL slug.
+- **Four dispatch modes are mutually exclusive.** `.href(url)` = link. `.method('POST').action(url)` = form-post. `.handler(ctx => …)` = JSON dispatch via the framework's `_action/:name` route. `.submit()` = trigger the enclosing form's submit.
+- **Modal-form is a flavor of handler.** Calling `.schema([Field, …])` flips an action into modal-form mode: clicking the trigger opens a Dialog with the schema as a real pilotiq form; submit fetches the action's dispatch URL with the form body.
+- **Placement determines where the button mounts.** `inline` (default, in-page) / `bulk` (toolbar when rows selected) / `row` (per-row) / `header` (page header). Placement is implicit from how you pass the action — `Resource.table().recordActions([…])` are row, `.bulkActions([…])` are bulk, etc.
+- **Visibility is fail-closed.** `.visible(rule)` / `.hidden(rule)` / `.disabled(rule)` / `.authorize(rule)` accept `boolean | (ctx) => boolean | Promise<boolean>`. Throwing → visibility false. `ActionVisibilityContext` carries `{ record?, records?, user? }` depending on placement.
+- **Row-placement actions evaluate per row.** The framework calls each row's predicates in `loadTableRecords` and stamps `row._visibleActions: name[]` / `row._disabledActions: name[]`. The renderer filters its action strip against that stamp.
+- **All non-modal handler dispatches SPA-update.** Fetch with `Accept: application/json`, drain notifications via `useToast()`, then `useNavigate(redirect)`. No page reload. Only form-post `method` actions (e.g. `Action.delete`) still use the 303-redirect path for back-compat.
+
+## Examples
+
+- `playground/app/Pilotiq/Articles/ArticleResource.ts` — header/row actions with built-in factories.
+- `playground/app/Pilotiq/Posts/PostResource.ts` — modal-form action (`Action.make('publish').schema([…]).handler(…)`).
+- `playground/app/Pilotiq/Users/UserResource.ts` — `Action.replicate` with `beforeReplicaSaved` mutator.

package/boost/skills/pilotiq-actions/rules/dispatch-modes.md

@@ -0,0 +1,177 @@
+# Dispatch Modes
+
+Every `Action` has exactly one of four dispatch modes. They're mutually exclusive — calling a setter from a different mode replaces the prior choice. Pick the mode by what the action does, not where it appears.
+
+## 1. `href(url)` — link
+
+```ts
+Action.make('docs')
+  .label('Documentation')
+  .icon('book')
+  .href('https://docs.example.com')
+```
+
+Renders as `<a href>`. No server round-trip. Cmd+click / right-click "open in new tab" works because it's a real anchor.
+
+`.openInNewTab()` adds `target="_blank" rel="noopener"`. `.tooltip(text)` adds a hover hint.
+
+Use for: external doc links, marketing CTAs, sibling-app deep links.
+
+## 2. `method(verb).action(url)` — form-post
+
+```ts
+Action.make('archive')
+  .label('Archive')
+  .color('warning')
+  .method('POST')
+  .action(`${base}/articles/${row.id}/archive`)
+  .confirm('Archive this article? You can restore it later.')
+```
+
+Renders as a hidden `<form>` with a submit button. The form body is empty (or carries `Action.formField(name, value)` pairs — see below). Server responds 303 → browser follows → page re-renders.
+
+This is the **only mode that survives no-JavaScript clients** — useful for back-compat with progressively-enhanced flows or for actions that must remain accessible from raw HTML email links. The framework's `Action.delete` factory ships in this mode for that reason.
+
+`.confirm(message)` wraps the submit in a confirmation Dialog. The submit doesn't fire until the user OKs.
+
+## 3. `handler(ctx => …)` — JSON dispatch
+
+```ts
+Action.make('publish')
+  .label('Publish')
+  .color('primary')
+  .icon('send')
+  .handler(async (ctx) => {
+    const article = await ArticleModel.find(ctx.record.id)
+    article.publishedAt = new Date()
+    await article.save()
+    return {
+      notify: { title: 'Published', body: article.title, kind: 'success' },
+      redirect: `${ctx.basePath}/articles/${article.id}/edit`,
+    }
+  })
+```
+
+Clicking POSTs `Accept: application/json` to `{basePath}/{slug}/_action/{name}`. The framework routes through `dispatchAction(action, body, ctx)`, calls the handler, normalizes the return shape, ships it back.
+
+**Return shape** (all keys optional):
+
+```ts
+{
+  notify?:        NotificationLike | NotificationLike[],
+  redirect?:      string,                    // URL to navigate to after success
+  download?:      { filename, contentType, body },  // triggers <a download> on the client
+  ok?:            boolean,                   // false short-circuits to error toast
+  error?:         string,                    // surfaced as toast when ok:false
+  // ...any extras get round-tripped via additional ActionResult slots
+}
+```
+
+Client-side: drains notifications via `useToast()`, then `useNavigate(redirect)`. **No page reload** — SPA-only flow. If the response carries a `download` payload, the framework synthesizes a temporary `<a download>` blob and clicks it.
+
+**`ctx` shape:**
+
+```ts
+{
+  user:       OpaqueUser | null,         // from Pilotiq.user() resolver
+  record?:    Record,                    // row placement — current row
+  records?:   Record[],                  // bulk placement — selected rows
+  basePath:   string,                    // panel base ("/admin")
+  resource?:  ResourceLike,              // when in a resource scope
+  relation?:  { parent, parentId, relationship },  // when inside a relation manager
+  body?:      unknown,                   // raw POST body (FormData-parsed) — modal-form values land here
+}
+```
+
+Use for: anything that needs server work but is conceptually a one-shot operation, not a page navigation.
+
+## 4. `submit()` — trigger an enclosing form
+
+```ts
+// inside CreatePage.getFormActions(R)
+Action.make('createAnother')
+  .label('Create & create another')
+  .outlined()
+  .submit()
+  .formField('_continueCreate', '1')      // rides the form body so the handler can branch
+```
+
+Renders as `<button type="submit">`. No dispatch URL — it submits the enclosing `<form>`. Used in page headers / form footers where the form already wires its own POST.
+
+`.form(formId)` targets a form outside the natural enclosing `<form>` (HTML `form=` attribute). Useful when the submit button lives in the page header but the form lives further down the tree.
+
+`.formField(name, value='1')` attaches a hidden `name`/`value` pair to the form body — the click sets `event.submitter` so `new FormData(form, submitter)` picks it up. Confirm-gated submits intentionally **don't** honor `formField` (programmatic `requestSubmit()` has no submitter).
+
+## Modal-form actions (flavor of handler)
+
+Add `.schema([Field, …])` to a handler action and it switches to modal-form mode:
+
+```ts
+Action.make('addNote')
+  .label('Add note')
+  .icon('plus')
+  .schema([
+    TextField.make('subject').required(),
+    TextareaField.make('body').required(),
+    SelectField.make('priority').options({ low: 'Low', med: 'Med', high: 'High' }).default('med'),
+  ])
+  .handler(async (ctx) => {
+    // ctx.body has the parsed + validated form values
+    await Note.create({ ...ctx.body, articleId: ctx.record.id })
+    return { notify: { title: 'Note added', kind: 'success' } }
+  })
+```
+
+Clicking the trigger opens a Dialog with the schema mounted as a real pilotiq form. Submit fetches `Accept: application/json`. Server responses:
+
+- **200 `{ ok: true, redirect, notifications }`** — drain notifications, SPA-navigate.
+- **422 `{ ok: false, errors: { field: [msg, …] } }`** — stamp inline field errors.
+- **5xx `{ ok: false, error }`** — error toast.
+
+The form runs every `pilotiq-fields`-style validator (required / email / unique / distinct) before reaching the handler. Field-level `live()` works inside the modal.
+
+### Modal chrome
+
+12 setters customize the modal:
+
+```ts
+Action.make('addNote')
+  .modalHeading('Add a note')
+  .modalDescription('Notes are visible to all editors.')
+  .modalIcon('sticky-note')
+  .modalIconColor('warning')
+  .modalWidth('lg')                       // 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | 'screen'
+  .modalSubmitActionLabel('Save note')
+  .modalCancelActionLabel('Discard')
+  .modalCloseable(false)                  // user can't close via Esc / outside-click
+  .modalContentFooter([                    // Element[] rendered below the form body
+    Text.make('Notes auto-archive after 90 days.').size('xs').color('muted'),
+  ])
+  // …
+```
+
+Setters with no special chrome you want, just omit — sensible defaults ship.
+
+## Confirm
+
+Both handler and method modes accept `.confirm(message)`:
+
+```ts
+Action.make('publish')
+  .handler(/* … */)
+  .confirm('Publish this article? It will be visible to everyone.')
+```
+
+`.modalConfirmIcon` / `.modalConfirmIconColor` customize the chrome. Confirm dialogs share the same `<ActionModalDialog>` primitive as modal-form — the difference is content: confirm shows a message + Cancel/OK; modal-form mounts a `<FormFields>`.
+
+## Pitfalls
+
+- **`.handler()` on a method action.** Calling `.method('POST').action(...)` then `.handler(...)` will override the method, NOT compose — handler wins. Pick one mode.
+- **`.submit().formField(...)` with `.confirm(...)`.** Confirm-gated submits use `form.requestSubmit()` programmatically, which doesn't carry a `submitter`. The `formField` pair will silently drop. If you need both, use `.handler()` + `.confirm()` instead.
+- **Modal-form fields inside the modal can't access the outer page's form state.** The modal is a fresh form scope; `$get('outerFieldName')` won't see the page's form. If you need cross-form data, pass it via `ctx.record` instead.
+- **Handler returns are async-aware but not stream-aware.** Don't expect to ship progressive output from a long-running handler. For batch operations that take >5s, return immediately with `{ notify: 'Queued', redirect }` and process out-of-band.
+
+## See also
+
+- `visibility-and-authorization.md` — gating which dispatch modes fire for which user / record.
+- `factories.md` — pre-built factories you usually want instead of writing dispatch from scratch.

package/boost/skills/pilotiq-actions/rules/factories.md

@@ -0,0 +1,130 @@
+# Built-in Action Factories
+
+Pilotiq ships ~25 pre-built `Action.*` factories for the operations every admin panel needs. They handle dispatch wiring, visibility gating, chrome, and notification copy — most of the time you reach for one of these instead of `Action.make(...)`.
+
+## CRUD basics (single row)
+
+```ts
+import { Action } from '@pilotiq/pilotiq'
+
+Action.create(R, base)              // header — "Create <Label>"; href = `${base}/${slug}/create`
+Action.edit(R, base, recordId)      // row — pencil icon; href = `${base}/${slug}/:id/edit`
+Action.view(R, base, recordId)      // row — eye icon; href = `${base}/${slug}/:id`
+Action.delete(R, base, recordId)    // row — trash icon; method POST → `${base}/${slug}/:id/delete` with .confirm()
+```
+
+Each delegates visibility to the matching Resource policy (`canCreate` / `canEdit` / `canView` / `canDelete`) automatically — see `visibility-and-authorization.md` § Composing with Resource policies.
+
+## Replicate
+
+```ts
+Action.replicate(R, base, recordId, {
+  excludeAttributes:    ['name', 'slug'],     // strip these in addition to PK + soft-delete column
+  beforeReplicaSaved:   async (replica, source) => {
+    replica.name = `Copy of ${source.name}`
+    replica.slug = await generateSlug(replica.name)
+  },
+  getCreatedNotificationTitle: ({ replica, source }) => `Cloned "${source.title}"`,
+  getRedirectUrl:       ({ replica }) => `${base}/articles/${replica.id}/edit`,
+})
+```
+
+Clones the source row via `R.model.create(...)`. Strips PK + soft-delete column + `opts.excludeAttributes`, runs `beforeReplicaSaved` to mutate, persists, redirects to the new record's edit page. Visibility delegates to `R.canCreate`.
+
+`Action.bulkReplicate(R, base, opts?)` is the bulk variant — iterates `ctx.records`, applies the same strip-mutate-create pipeline per row, skips rows that throw or fail per-row `canCreate`, notifies with the count.
+
+`opts.getCreatedNotificationTitle` and `opts.getRedirectUrl` are both sync-or-async; receive `{ replica, source }` (single) or `{ count, records }` (bulk). Returning `undefined` falls back to the default copy. Empty string is honored — won't be swallowed by `??`.
+
+## Soft delete (when `Resource.softDeletes = true`)
+
+```ts
+Action.restore(R, base, recordId)            // row — only visible on trashed rows
+Action.forceDelete(R, base, recordId)        // row — only visible on trashed rows; method POST with .confirm()
+
+Action.bulkRestore(R, base)                  // bulk — restores selected trashed rows
+Action.bulkForceDelete(R, base)              // bulk
+```
+
+`Action.delete` auto-hides on already-trashed rows (per Plan #13 soft-delete wiring); restore / forceDelete auto-hide on non-trashed rows. The toggling is structural, not optional — opt out by overriding `.visible()` after the factory.
+
+## Import / Export
+
+```ts
+Action.export(R, base, {
+  format:    'csv',                                  // 'csv' | 'json'
+  columns:   ['id', 'title', 'publishedAt'],         // omit → all columns from R.table()
+  filename:  () => `articles-${new Date().toISOString().slice(0, 10)}.csv`,
+})
+
+Action.bulkExport(R, base, opts?)                    // bulk — exports only selected rows
+
+Action.import(R, base, {
+  format:     'csv',                                 // omit → auto-detect from filename
+  upsertBy:   ['email'],                             // turns it into an upsert action; mode-select appears in the modal
+  maxRows:    10_000,                                // default cap
+})
+```
+
+`Action.export` reads from the resource's `Table.records(ctx)` (so filters / search / sort flow through); writes the body to a `download` envelope that the client synthesizes as `<a download>`. CSV via the in-tree `src/io/csv.ts` (RFC 4180, in-memory only).
+
+`Action.import` auto-builds a modal-form schema with a `FileUpload` field (and a `Mode` select when `upsertBy` is set). Handler reads `ctx.values.file`, fetches the URL the upload stamped, parses CSV/JSON, walks rows through `R.model.create` (or `R.model.update` for matched upserts). Per-row `validate / beforeCreate / beforeUpdate` lifecycle hooks fire from the resource's form config. Partial-failure-soft: rows that throw / fail validate accumulate in `summary.errors` and the import keeps going. v1 has **no transaction wrapper** — partial imports leave the DB in a partially-applied state.
+
+## Relation factories (inside RelationManagers)
+
+```ts
+// inside a RelationManager static table(table, ctx)
+Action.relationCreate(M, ctx)                        // header — "Create <Label>"; opens create form in tab
+Action.relationEdit(M, ctx, recordId)                // row — pencil
+Action.relationDelete(M, ctx, recordId)              // row — trash
+Action.relationRestore(M, ctx, recordId)             // row — soft-delete trash only
+Action.relationForceDelete(M, ctx, recordId)         // row — soft-delete trash only
+
+Action.relationReplicate(M, ctx, recordId, opts?)
+Action.relationBulkReplicate(M, ctx, opts?)
+
+// M2M only (auto-hide outside `belongsToMany / morphToMany / morphedByMany`)
+Action.relationAttach(M, ctx)                        // header — modal-form picker
+Action.relationDetach(M, ctx, recordId)              // row
+Action.relationBulkDetach(M, ctx)                    // bulk
+```
+
+`ctx` is the `RelationManagerContext` injected into `M.table(table, ctx)` — it carries `basePath / parentSlug / parentId / relationship / parentRecord / related? / mode`. The factories thread URLs + parent attachment automatically.
+
+`relationReplicate` force-pins the parent FK back onto the replica AFTER strip + BEFORE `beforeReplicaSaved`, so a tampered source row can't slip a different parent in by riding its own FK column. Auto-hides on M2M (replicate doesn't fit pivot semantics) and on `morphTo` (no single owner to pin to).
+
+For the broader RelationManager surface (when to override `canDelete` vs `canDetach`, how `ctx.mode` derives), see [[pilotiq-relations]].
+
+## Common chrome customizations
+
+The factory result is just an `Action` instance — every chain method composes after the factory call:
+
+```ts
+Action.delete(R, base, row.id)
+  .label('Move to trash')                   // override default copy
+  .color('warning')                          // override 'destructive'
+  .tooltip('Trashed items auto-purge after 30 days')
+  .confirm('Move this article to trash?')   // override default confirm copy
+  .visible(({ user }) => user?.role === 'admin')
+```
+
+The `.visible()` you set wins over the factory's auto-attached policy gate.
+
+## When NOT to use a factory
+
+- **Custom modal-form** — the import factory's modal schema is fixed (FileUpload + maybe Mode). For richer modals (multi-field policy decisions, conditional reactivity), use `Action.make('foo').schema([…]).handler(…)` directly.
+- **Cross-record orchestration** — bulk factories iterate row-by-row. For "select 50 rows, run one SQL UPDATE" semantics, write a handler that consumes `ctx.records` and dispatches a single ORM call.
+- **Compound flows** — anything that needs multi-step UX (confirm → modal-form → second confirm) doesn't compose from factories. Build it from `Action.make()` primitives.
+
+## Pitfalls
+
+- **`opts.beforeReplicaSaved` mutates a plain object, not a model instance.** It's `Record<string, unknown>`, pre-create. Don't expect `replica.save()` / lifecycle hooks — those are framework-internal post-mutation.
+- **Bulk factories don't wrap in a transaction.** Partial failures leave the DB partially updated. The notification shows the count succeeded; the rest accumulate in `summary.errors`. If you need atomicity, write a handler that opens a transaction explicitly via your ORM.
+- **`Action.import`'s `upsertBy` requires `R.model.update` to exist.** Without it, the import will throw on the first matching row. Boot-time guard catches the missing method.
+- **Relation factories' `ctx.mode` lies about `morphOne` / `hasOne`.** Both collapse into `'hasMany'` for action dispatch — `morphOne / hasOne` semantically still allow one child, but the factory shape is the same.
+
+## See also
+
+- `dispatch-modes.md` — what each factory does under the hood.
+- `visibility-and-authorization.md` — how factory auto-visibility composes with manual `.visible()`.
+- [[pilotiq-relations]] — broader RelationManager + `Repeater.relationship` patterns.
+- [[pilotiq-resource]] — the `Resource.softDeletes` + `can*` static surface that factories key off.

package/boost/skills/pilotiq-actions/rules/visibility-and-authorization.md

@@ -0,0 +1,125 @@
+# Visibility & Authorization
+
+Every action exposes four conditional setters. They differ in *intent*; all use the same predicate shape.
+
+```ts
+type VisibilityRule =
+  | boolean
+  | ((ctx: ActionVisibilityContext) => boolean | Promise<boolean>)
+
+type ActionVisibilityContext = {
+  record?:  Record               // present on row-placement
+  records?: Record[]             // present on bulk-placement
+  user?:    OpaqueUser | null    // from Pilotiq.user()
+}
+```
+
+## The four setters
+
+```ts
+Action.make('publish')
+  .visible(({ record, user }) => !record.publishedAt && user?.role === 'editor')
+  .hidden(({ record }) => record.archived)
+  .disabled(({ record }) => record.locked)
+  .authorize(async ({ user, record }) => await canPublish(user, record))
+```
+
+- **`.visible(rule)`** — mounts the button only when rule resolves truthy. Default: visible.
+- **`.hidden(rule)`** — sugar inverse of `visible`. Last write wins; if you set both, the more recent setter is the active one.
+- **`.disabled(rule)`** — renders the button but as a non-interactive (greyed) chip. The user sees it exists but can't fire it.
+- **`.authorize(rule)`** — semantically equivalent to `.visible()` but reads as a permission gate at call sites. Use when the predicate is policy-shaped (`canEdit`, `canDelete`).
+
+`visible` + `authorize` both gate *presence*. Composing them is fine; both must resolve truthy. Default is `true` for both, so omitting them leaves the action always-visible.
+
+## Fail-closed semantics
+
+Predicates that throw or reject → button hides (or for `.disabled`, treats as disabled-true). This is the **opposite** of the layout `visible()` posture in `pilotiq-fields`, which fails *open* for in-progress data safety. Actions are operations, not data — silently hiding a bad button is safer than rendering one with broken logic.
+
+```ts
+Action.make('publish')
+  .visible(async ({ record }) => {
+    if (!record) throw new Error('record missing')   // silently hides; no toast, no log
+    return record.status === 'draft'
+  })
+```
+
+If you want errors loud, log inside the predicate yourself. Don't expect a framework-level toast.
+
+## Per-row gating on tables
+
+Row-placement actions evaluate predicates **per row** during `loadTableRecords`. The framework:
+
+1. Walks the registered row actions (from `Resource.table().recordActions([…])` or page-override `getRowActions()`).
+2. Filters to actions with at least one conditional rule (`visible` / `hidden` / `disabled` / `authorize`).
+3. Calls each rule in parallel via `Promise.all` for each row.
+4. Stamps the row with `_visibleActions: name[]` (names that resolved truthy on visible/authorize) and `_disabledActions: name[]` (names that resolved truthy on disabled).
+5. The renderer's `renderRowActions` filters its strip against `_visibleActions` and applies disabled styling per `_disabledActions`.
+
+**Performance** — every conditional rule × every row × every page load. Heavy predicates (DB queries, network calls) inside `visible()` will dominate list-page latency. Prefer reading from the row record itself when possible:
+
+```ts
+// Cheap — reads from the record server-side stamped fields
+.visible(({ record }) => record.status === 'draft')
+
+// Expensive — DB query per row
+.visible(async ({ record }) => await UserPolicy.canEdit(user, record))
+```
+
+If you need expensive checks, stamp the result on the row via `Column.formatStateUsing` upstream and read from `record._formatted[col]` instead.
+
+## Bulk-placement gating
+
+Bulk-action predicates receive `records: Record[]` instead of `record`. They evaluate ONCE per page render (against the rendered row set), not per row:
+
+```ts
+Action.make('bulkDelete')
+  .label('Delete selected')
+  .color('destructive')
+  .handler(async ({ records, user }) => {
+    for (const r of records) {
+      if (!await canDelete(user, r)) continue
+      await Article.delete(r.id)
+    }
+    return { notify: { title: `Deleted ${records.length}`, kind: 'success' } }
+  })
+  .visible(({ user }) => user?.role === 'editor')      // gates the bulk button
+```
+
+For *per-row* exclusion inside a bulk handler, the convention is: iterate `records` in the handler, run the per-row predicate yourself, skip / accumulate errors. The framework doesn't pre-filter `records` against row-side predicates — the bulk button either shows or doesn't, and the handler owns row-level safety.
+
+## Composing with Resource policies
+
+Resource statics (`canView` / `canEdit` / `canDelete` / `canCreate` etc.) return `boolean | Promise<boolean>` against `(user, record?)`. Built-in factories (`Action.delete`, `Action.edit`, `Action.replicate`) auto-attach a `.visible()` rule that consults the matching policy:
+
+```ts
+// Resource
+class ArticleResource extends Resource {
+  static async canDelete(user, record) {
+    return user?.role === 'editor' && !record.locked
+  }
+}
+
+// page-override row actions
+Action.delete(ArticleResource, base, row.id)
+// equivalent to: Action.make('delete').method('POST').action(...).visible(({ record, user }) => ArticleResource.canDelete(user, record))
+```
+
+Override the auto-attach by setting `.visible(...)` explicitly — your setter wins.
+
+## Async + parallel
+
+All four predicates may be `async`. Per-row eval runs every row's predicates in parallel via `Promise.all`. Don't fan-out further inside a predicate — each row already pays one round-trip if you go async. Batch reads upstream if you need them.
+
+## Pitfalls
+
+- **`hidden(true)` does NOT permanently hide.** It's just the inverse of `visible(true)`. To permanently disable an action conditionally on config rather than data, hide it at the schema-builder level (don't include it in `recordActions([…])` at all).
+- **`disabled(true)` still POSTS if you mount it elsewhere.** The disabled flag is purely chrome. The action's dispatch URL is still live server-side — if a user crafts the POST manually, the handler still fires. Always gate inside the handler too for security.
+- **Predicates can see `record` as `undefined`** when an action is placed in a context that doesn't have a record (e.g. inline placement on a non-row page). Guard with `if (!record) return false` or use `?.` chaining.
+- **`user` may be `null`** when no user resolver runs or the resolver returns null. Predicates that need a user must guard.
+- **Don't read mutable state in predicates** (counter increments, request-scoped caches). They run multiple times per render in parallel — the same predicate may fire 5× concurrently for 5 rows.
+
+## See also
+
+- `dispatch-modes.md` — what the button does when allowed to fire.
+- `factories.md` — built-in factories auto-attach visibility rules; this rule covers the manual setter form.
+- `pilotiq-resource/rules/authorization.md` — Resource-level `can*` policies that feed factory auto-visibility.

package/dist/Pilotiq.d.ts

@@ -15,6 +15,23 @@ import type { NotificationActionHandler } from './notifications/types.js';
 import { type RightPanelContribution } from './RightPanel.js';
 import type { NavComponentProps, HeaderComponentProps, FooterComponentProps } from './react/component-slots.js';
 export type PilotiqLayout = 'sidebar' | 'topbar';
+/**
+ * Sidebar chrome options for the `'sidebar'` layout. Maps 1:1 onto the
+ * underlying shadcn `<Sidebar>` primitive; ignored under the `'topbar'`
+ * layout. All keys are optional — unset falls back to the panel default
+ * (`inset` / `icon` / `left`).
+ */
+export interface PilotiqSidebarOptions {
+    /** Surface treatment. `inset` floats the content in a rounded card
+     *  (the default); `floating` floats the sidebar itself; `sidebar` is
+     *  the classic full-height flush rail. */
+    variant?: 'sidebar' | 'floating' | 'inset';
+    /** Collapse behavior. `icon` collapses to an icon rail (default);
+     *  `offcanvas` slides fully off-screen; `none` disables collapsing. */
+    collapsible?: 'offcanvas' | 'icon' | 'none';
+    /** Which edge the rail docks to. `left` (default) is RTL-aware. */
+    side?: 'left' | 'right';
+}
 /** Plugin interface for extending Pilotiq panels. */
 export interface PilotiqPlugin {
     name: string;
@@ -181,6 +198,9 @@ export interface PilotiqConfig {
     name: string;
     path: string;
     layout: PilotiqLayout;
+    /** Sidebar chrome options — honored only under the `'sidebar'` layout.
+     *  Absent → primitive defaults (`inset` / `icon` / `left`). */
+    sidebar?: PilotiqSidebarOptions;
     resources: ResourceClass[];
     globals: GlobalClass[];
     pages: (typeof Page)[];
@@ -439,6 +459,17 @@ export declare class Pilotiq {
      *   panel.profile(ProfilePage)
      */
     profile(P: typeof Page): this;
+    /**
+     * Pick the panel layout, and (for `'sidebar'`) its chrome options.
+     * The options are bound to the layout that uses them: passing a second
+     * argument with `'topbar'` is a compile error, so sidebar-only config
+     * can't silently no-op under a topbar panel.
+     *
+     * @example
+     *   Pilotiq.make('Admin').layout('sidebar', { variant: 'floating', side: 'right' })
+     *   Pilotiq.make('Admin').layout('topbar')
+     */
+    layout(l: 'sidebar', opts?: PilotiqSidebarOptions): this;
     layout(l: PilotiqLayout): this;
     theme(config: ThemeConfig): this;
     guard(fn: (req: unknown) => boolean | Promise<boolean>): this;