@modufolio/panel 0.1.0

package/dist/injectionKeys.d.ts

@@ -0,0 +1,10 @@
+import { InjectionKey, Ref } from 'vue';
+/**
+ * Typed provide/inject keys — the analog of Solid's typed createContext.
+ *
+ * Using a typed Symbol key instead of a bare string gives inject() the right
+ * type automatically and makes the provider/consumer contract greppable and
+ * collision-proof.
+ */
+/** Whether the app sidebar is collapsed. Provided by AppLayout, read by sidebars. */
+export declare const SidebarCollapsedKey: InjectionKey<Ref<boolean>>;

package/dist/plugin.d.ts

@@ -0,0 +1,36 @@
+import { App, Component } from 'vue';
+import { MediaEndpoints } from './Components/Media/mediaEndpoints';
+export interface CreatePanelOptions {
+    /** Mount path of the panel backend, e.g. '/panel' or '/admin'. */
+    baseUrl?: string;
+    /** Extra icons for <Icon>, name → component. Override built-ins by name. */
+    icons?: Record<string, Component>;
+    /** App-specific blueprint field types, type → async component loader. */
+    fields?: Record<string, () => Promise<Component | {
+        default: Component;
+    }>>;
+    /**
+     * Where overlays (dialogs, drawers, dropdowns) are teleported.
+     * Defaults to 'body'; set it when overlays must live inside a themed or
+     * transformed subtree instead.
+     */
+    teleportTarget?: string | HTMLElement;
+    /**
+     * Backend paths the media picker calls, relative to `baseUrl`. Defaults to
+     * `/api/media/picker` and `/api/media/picker/albums`; override them when the
+     * app serves media under different routes.
+     */
+    media?: Partial<MediaEndpoints>;
+}
+/**
+ * Vue plugin — the single required setup call for panel consumers:
+ *
+ *   app.use(createPanel({
+ *     baseUrl: '/panel',
+ *     icons: { camera: CameraIcon },
+ *     fields: { 'block-editor': () => import('./Fields/BlockEditorField.vue') },
+ *   }))
+ */
+export declare function createPanel(options?: CreatePanelOptions): {
+    install(_app: App): void;
+};

package/dist/types/menu.d.ts

@@ -0,0 +1,11 @@
+/** User-menu item rendered by TopNavigation's dropdown. */
+export interface MenuItem {
+    label: string;
+    href?: string;
+    icon?: string;
+    divider?: boolean;
+    method?: 'get' | 'post' | 'put' | 'patch' | 'delete';
+    action?: () => void;
+    badge?: string | number;
+    badgeColor?: 'primary' | 'success' | 'danger' | 'warning';
+}

package/docs/async-writes.md

@@ -0,0 +1,159 @@
+# Async writes: ordering, staleness and in-flight state
+
+Admin panels do a lot of small writes — a toggle in a row, a debounced text
+field, an optimistic star. Two of them overlapping is normal, and the
+failure modes are quiet: no error, just the wrong value left on screen.
+
+These primitives exist for that. All are exported from the package root.
+
+## The rule they share
+
+> The order that matters is the order requests were **dispatched** in, not
+> the order responses **settled** in.
+
+A slow first request must never overwrite what a faster second one already
+applied. Nothing here retries or queues; they only decide which result is
+allowed to land.
+
+## `writeGate` — deciding which write wins
+
+```ts
+import { writeGate, writeKey, LOCAL_WRITE } from '@modufolio/panel'
+
+const key = writeKey('users', user.id, 'is_active')   // "users/42/is_active"
+
+const stamp = writeGate.next(true)                    // take a sequence number
+// … dispatch the request …
+if (writeGate.admit(key, stamp)) {
+  // still the newest write for this key — safe to apply
+}
+```
+
+| Member | Purpose |
+|---|---|
+| `next(record: boolean)` | Take the next sequence number. Call at **dispatch**, not on settle. |
+| `admit(key, stamp)` | May this write land? Recording stamps also book the key. |
+| `seal(key)` | The record is gone server-side — reject every write still in flight for it. |
+| `clear()` | Drop all bookkeeping. Intended for tests. |
+| `writeKey(resource, id, field?)` | One spelling for keys, so call sites agree on identity. |
+| `LOCAL_WRITE` | A write with no dispatch order — seeding state, a value that never went over the wire. Always admitted, records nothing. |
+
+Three details that are load-bearing:
+
+- **Only mutating requests should record** (`next(true)`). A read that
+  recorded its number would gate out a save dispatched before it. Pass
+  `next(false)` for reads, or to *ask* whether your write is still newest
+  without moving the gate.
+- **`LOCAL_WRITE` is a value you name, not a parameter you omit.** The
+  un-ordered case should be a decision at the call site.
+- **`seal()` takes a fresh number**, not the delete's own. A delete becomes
+  true when it *settles*; anything still in flight at that moment is dead
+  data and must not re-create the record.
+
+The counter is global and monotonic; comparison is per key. A per-key
+counter restarting at zero would let a number minted for one key match a
+later slot's — which is how a deleted record comes back to life.
+
+## `optimistic()` — apply now, roll back if refused
+
+```ts
+import { optimistic, writeKey } from '@modufolio/panel'
+
+const ok = await optimistic(
+  () => {                                    // apply, returning a rollback
+    const previous = item.starred
+    item.starred = !previous
+    return () => { item.starred = previous }
+  },
+  () => apiFetch(url, { method: 'PATCH', body: { starred: item.starred } }),
+  writeKey('items', item.id, 'starred'),     // optional, but see below
+)
+```
+
+Resolves `true` on success, `false` if the request failed (already rolled
+back).
+
+**Pass a key whenever the same state can be mutated twice concurrently.**
+Without one, two quick toggles interleave so that the *first* failing rolls
+state back to before either ran — silently erasing the second toggle, whose
+request succeeded. With a key, a failure only rolls back while its own write
+is still the newest.
+
+Bulk actions that span many records are the honest exception: one key cannot
+represent them, so leave it off.
+
+## `useFieldSaver()` — debounced saves with status
+
+```ts
+const { saveStatus, save, debouncedSave } = useFieldSaver(
+  (value: string) => apiFetch(url, { method: 'PATCH', body: { title: value } }),
+)
+```
+
+`saveStatus` is `null | 'saving' | 'saved' | 'error'`. Ordering is built in:
+a slow save settling after a faster later one cannot report its stale
+outcome in either direction — no stale `error` over a newer success, no
+stale `saved` hiding a newer failure. Timers are cleared on scope dispose.
+
+## `usePendingKeys()` — which row is busy
+
+```ts
+const { isPending, anyPending, run } = usePendingKeys()
+
+const toggle = (row) => run(row.id, () => apiFetch(/* … */))
+```
+
+```vue
+<Spinner v-if="isPending(row.id)" />
+```
+
+One boolean per component answers "is anything saving"; a list needs "is
+*this row* saving", or every row spins together. `run` also guards
+re-entry — a key already in flight refuses a second call and resolves
+`undefined`, which is what a double-click should mean.
+
+## `useUnsavedChangesWarning()` — don't discard edits silently
+
+```ts
+const { allowNextNavigation } = useUnsavedChangesWarning(form)
+
+function submit() {
+  allowNextNavigation()   // this navigation *is* the save
+  form.post(url)
+}
+```
+
+Hooks Inertia's `before` event, so it covers every ordinary visit —
+including logout, which is a POST visit like any other — plus `beforeunload`
+for tab closes.
+
+Takes Inertia's form object, or **a getter** for anything else that knows
+whether it is dirty:
+
+```ts
+useUnsavedChangesWarning(() => draft.isDirty.value || other.isDirty.value)
+```
+
+The getter is read at event time, never captured, so state that flips after
+setup is still seen. `allowNextNavigation()` skips exactly one prompt and
+re-arms, so a save that leaves the form dirty does not open a hole.
+
+## `moduleSingleton()` — state that survives a duplicated module
+
+```ts
+const state = moduleSingleton('toast-store', () => ({
+  items: ref([]),
+  nextId: 0,
+}))
+```
+
+A bundler can instantiate the same module twice — Vite's dep pre-bundler,
+for example, inlines a package's TS while leaving its `.vue` SFCs as
+external raw-source imports. A store imported from both sides of that
+boundary splits: one copy is written, the other is rendered, and nothing
+appears. It fails silently, which is what makes it expensive to find.
+
+Keying the state off `globalThis` with `Symbol.for` hands every copy the
+same object. Use it **only** for process-wide state. Anything scoped to a
+component or an app instance belongs in provide/inject — a global would leak
+across SSR requests.

package/docs/custom-fields.md

@@ -0,0 +1,71 @@
+# Custom field types
+
+Blueprint forms resolve field components through a registry. Built-ins cover
+the standard inputs (`text`, `textarea`, `select`, `multiselect`, `toggle`,
+`checkbox`, `date`, `date-range`, `file`, `color`, `belongs-to`, `repeater`,
+`toggle-buttons`). Anything app-specific is registered at boot:
+
+```js
+createPanel({
+  fields: {
+    'writer':       () => import('@/Fields/WriterField.vue'),
+    'block-editor': () => import('@/Fields/BlockEditorField.vue'),
+  },
+})
+```
+
+or imperatively:
+
+```js
+import { registerFieldType } from '@modufolio/panel'
+registerFieldType('signature', () => import('./SignatureField.vue'))
+```
+
+A field component that needs the resolver itself (a container type
+rendering its own sub-fields) should import it from `fieldRegistry`, not
+from `useBlueprint` — the composable imports the registry too, and going
+back the other way re-creates a cycle between a composable and a component.
+
+Then use the type in any blueprint:
+
+```js
+const fields = [
+  { type: 'signature', key: 'signature', label: 'Sign here' },
+]
+```
+
+## Field component contract
+
+A field component receives (via `useBlueprint`'s `fieldProps`):
+
+| Prop | Type | Notes |
+|---|---|---|
+| `modelValue` | any | v-model value for the field's key |
+| `label` | string | |
+| `width` | string | grid width (`full`, `1/2`, ...) — use `useFieldWidth` |
+| `required` | boolean | |
+| `error` | string | validation message ('' when valid) |
+| `help`, `placeholder` | string? | only when set in the FieldDef |
+| `options` | OptionItem[]? | for choice-style fields |
+
+plus anything passed through the FieldDef's `props` object. Emit
+`update:modelValue` with the new value.
+
+### Container fields
+
+A field holding a list of rows (a repeater, a matrix) also receives:
+
+| Prop | Type | Notes |
+|---|---|---|
+| `fields` | FieldDef[] | the child's own field declarations |
+| `nestedErrors` | Record<string, string> | row-scoped messages keyed `{index}.{subKey}`, the container's own prefix already stripped |
+
+Render sub-fields through `resolveFieldComponent` so custom types work
+inside containers too. See [relation-fields.md](relation-fields.md) for the
+server side of that contract.
+
+Registering an existing name (e.g. `'file'`) **overrides** the built-in —
+that's the supported way to swap in, say, a resumable-upload field.
+
+Unknown types throw at resolve time with the list of known types, so typos
+fail loudly rather than rendering nothing.

package/docs/drawer-protocol.md

@@ -0,0 +1,130 @@
+# Drawer Stack — server/client protocol
+
+The Drawer components render a stack of overlay panels driven by ordinary
+Inertia visits ("URL = state"). Any backend can drive them by honoring this
+contract; the reference implementation is appkit-portfolio's
+`src/Inertia/DrawerStack.php`.
+
+## Request side
+
+Every visit initiated from inside a drawer (DrawerLink, useDrawerStack
+navigation, Drawer record-pagination) carries the header:
+
+```
+X-Inertia-Drawer-Stack: 1
+```
+
+The server uses its presence to decide to render the *underlying page* with a
+drawer stack on top, instead of a full page swap.
+
+## Response side
+
+The page component receives a **`stack`** prop: an ordered array of stack
+items, bottom-most first. Each item:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `type` | string | Which drawer content to render — the client maps types to components (consumer-defined) |
+| `data` | object | Payload for that drawer (the record, options, ...) |
+| `title` | string | Header title |
+| `description` | string | Optional header subtitle |
+| `width` | string | `sm` \| `md` \| `lg` \| ... (Drawer width presets) |
+| `href` | string | Canonical URL of this drawer (used when re-opening / deep-linking) |
+| `nextRecordUrl` | string\|null | Optional record-pagination target (renders next/prev arrows) |
+| `previousRecordUrl` | string\|null | Optional record-pagination target |
+| `tabs` | array\|null | Optional sections for the drawer body — key, label, count, and per-type extras (`fields`, `sections`, `primary`, `empty`, …) |
+| `presentation` | `'drawer'` \| `'dialog'` | Which frame renders this item. Absent means `drawer` — see [Two frames](#two-frames) |
+
+An empty array (or absent prop) means no drawers are open.
+
+## Two frames
+
+A drawer is a side panel you read a record in and can page through. A dialog is
+a centred modal for one decision or one short form. They are the **same stack**:
+same header, same URL-is-state contract, same per-type slots — a frame declares
+which one it wants and nothing else changes.
+
+```php
+DrawerStack::create()->push(
+    type: 'publish',
+    data: [...],
+    title: 'Publish post',
+    href: '/panel/posts/{uuid}/publish',
+    width: 'sm',
+    presentation: DrawerStack::AS_DIALOG,
+);
+```
+
+```vue
+<DrawerStack :stack="stack" base-url="/panel/posts">
+  <template #publish="{ item }">…the dialog body…</template>
+  <template #footer-publish="{ item }">…its buttons…</template>
+</DrawerStack>
+```
+
+A second protocol for dialogs would have been a second set of things to get
+subtly wrong, and it would have bought nothing: because a dialog is a stack
+item, it is addressable, deep-linkable and closed by navigating away — which a
+dialog held in page state is not. `Dialog` draws its own overlay, so the
+stack's shared overlay stands down when no item in the stack is a drawer.
+
+**Frames are pointers, which is the point.** A row action can carry a dialog
+URL (`RowAction::dialog()`) instead of naming a behaviour the table has to
+implement, so a new interaction is a new route rather than a new case in the
+client. See [table-schema.md](../../../docs/table-schema.md#actions).
+
+## Client components
+
+- `<DrawerStack :stack="stack" :base-url="...">` — renders the items;
+  `baseUrl` is where closing the whole stack navigates (Inertia visit).
+  Provides push/pop/close via `provide/inject` (`useDrawerStackContext`).
+- `<DrawerLink href="...">` — opens a URL as a new drawer on the stack
+  (adds the header, keeps the underlying page).
+- `useDrawerPage()` — inside drawer content: access the current item's
+  `data` with page-like ergonomics.
+- `useIsDrawer()` — is this component rendering inside a drawer?
+- `useFocusedStackRow(props, type, records)` — index of the listing row the
+  top stack item is showing, or -1. `SchemaTable` uses this internally when
+  given a `stack` prop, so the highlighted row follows record pagination;
+  reach for the composable directly only outside `SchemaTable`.
+
+## Never hand-write the visit
+
+The request side is three things at once — the header, `only: ['stack']`, and
+the preserve flags that keep the page underneath mounted. Get one third wrong
+and it still *looks* right: fetching only the stack renders a drawer even when
+the server never took the drawer path. A hand-written `X-Drawer` header did
+exactly that, and survived a manual check.
+
+So there is one way to navigate the stack, and every caller uses it:
+
+```ts
+import { visitDrawer } from '@modufolio/panel'
+
+visitDrawer('/panel/movies/42', { queryParams: { sort: 'title' } })
+```
+
+`DrawerLink`, `Drawer`'s record pagination, `useDrawerStack` and `SchemaTable`'s
+declared `drawer` action all route through it; `visit-drawer.spec.ts` asserts
+the trio so a fifth caller cannot quietly drop a third of it. Reach for
+`drawerVisitOptions()` only when Inertia needs the options themselves (a form
+submission rather than a navigation).
+
+`queryParams` keeps empty strings — the server distinguishes "this filter is
+set to nothing" from "this filter was not sent", and dropping them silently
+reset filters whenever a drawer opened.
+
+## Server responsibilities (checklist for a new backend)
+
+1. Detect the `X-Inertia-Drawer-Stack` header.
+2. For drawer requests, resolve the *base* page (the URL under the drawer)
+   and its props as usual.
+3. Build the stack array (deep-linkable: a fresh GET with a drawer URL should
+   reconstruct the same stack) and pass it as the `stack` prop.
+4. Set `presentation` on any item that should render as a dialog; omit it for
+   drawers.
+5. Closing is plain navigation — no special endpoint needed.
+
+A dialog route is an ordinary route: it renders the *listing* underneath with
+one extra frame on top. `PostController::publishDialog()` is the reference —
+it differs from `show()` by one argument.

package/docs/overlays.md

@@ -0,0 +1,106 @@
+# Overlay primitives
+
+Dialogs, drawers, dropdowns and popovers in this package share a small set of
+primitives in `src/Primitives/` rather than each carrying its own copy of the
+behaviour. They are exported, so an application can build its own overlays on
+the same foundations.
+
+## The layer stack — `useDismissableLayer`
+
+Every open overlay registers itself while it is open. Escape and outside
+presses go to the **top of the stack only**.
+
+```ts
+useDismissableLayer(isOpen, {
+  // Everything that counts as "inside": a teleported panel and the trigger
+  // that opened it live in different parts of the DOM.
+  elements: () => [triggerRef.value, panelRef.value],
+  onDismiss: (reason) => { isOpen.value = false },
+  dismissOnOutsidePointer: true,
+  // Supplying this marks the layer modal: the rest of the page is hidden from
+  // assistive technology while it is on top.
+  modalElement: () => panelRef.value,
+})
+```
+
+The layer decides what to do with a dismissal, so a non-closable dialog can
+ignore Escape without the press falling through to the drawer beneath it.
+
+`modalElement` exists because `aria-modal="true"` is not reliably honoured: a
+screen reader can otherwise walk out of an open dialog and read a page the user
+cannot reach. The page behind is marked `inert` rather than `aria-hidden` —
+the browser refuses the latter over the focused element ("Blocked aria-hidden
+on an element because its descendant retained focus"), while `inert` moves
+focus out on its own and takes the page out of the tab order too. Only the
+highest modal layer applies, and the other registered layers are exempt — so a
+dropdown opened inside a dialog is not silenced by the dialog containing it,
+and a toast region keeps announcing.
+
+**An overlay the host app renders itself must register too.** A raw
+`<Teleport to="body">` panel is invisible to the stack: Escape closes the
+drawer beneath it instead of the panel, and that drawer's focus trap reaches
+into it — which shows up as a combobox inside the panel closing the instant it
+opens. Registering it is the whole fix:
+
+```ts
+const panelRef = ref<HTMLElement | null>(null)
+
+useDismissableLayer(() => isVisible.value, {
+  elements: () => [panelRef.value],
+  onDismiss: (reason) => { if (reason === 'escape') close() },
+  dismissOnOutsidePointer: false,   // the panel draws its own scrim
+  modalElement: () => panelRef.value,
+})
+```
+
+## Scroll lock — `useBodyScrollLock`
+
+Reference counted across every overlay. The page scrolls again only once the
+last holder releases, so a dialog opened from inside a drawer cannot unlock the
+page while the drawer is still covering it. It also compensates for the
+scrollbar's width, so the page behind does not jump sideways, and exposes that
+width as `--panel-scrollbar-width`.
+
+```ts
+const locked = useBodyScrollLock(props.isOpen)
+watch(() => props.isOpen, (open) => { locked.value = open })
+```
+
+## Positioning — `useAnchoredPosition`
+
+A thin wrapper over `@floating-ui/vue`: flipping, viewport clamping, optional
+width matching and height capping, and — through `autoUpdate` — following the
+anchor through scrolls and resizes without per-component listeners.
+
+```ts
+const { floatingStyles } = useAnchoredPosition(triggerRef, panelRef, isOpen, {
+  placement: 'bottom-end',
+  matchWidth: true,
+})
+```
+
+The available height is applied as `max-height` and published as
+`--panel-available-height` for panels that scroll an inner region instead.
+
+## Keyboard — `useArrowNavigation`, `useTypeahead`
+
+`useArrowNavigation(container)` gives a menu the WAI-ARIA keyboard model:
+arrows move focus between items, Home/End jump to the ends, and typing jumps to
+an item by name. `resolveNavigationIndex()` is the same key model as a pure
+function, for lists driven by a highlighted index — a combobox, where focus
+stays in the text field and `aria-activedescendant` points at the row.
+
+## Ids — `useId`
+
+Wraps Vue's own `useId()`, which is stable across a server render and its
+hydration. Ids count per application, so two components in the same app always
+differ; two independently created apps restart the sequence.
+
+## Where overlays render — `teleportTarget`
+
+Overlays teleport to `body` by default. An application whose overlays must live
+inside a themed or transformed subtree sets it once:
+
+```ts
+app.use(createPanel({ teleportTarget: '#panel-overlays' }))
+```

package/docs/relation-fields.md

@@ -0,0 +1,112 @@
+# Relation fields: lookups and repeaters
+
+Two field types talk to the server while the form is open: `belongs-to`
+(pick one related record) and `repeater` (edit a list of child rows). Both
+work from props the backend sends, so a page declares nothing.
+
+## `belongs-to` — a lookup
+
+Small relations ship their whole option list and behave like a select.
+Larger ones ship no options and a `searchUrl` instead:
+
+```js
+{
+  type: 'belongs-to',
+  key: 'author_id',
+  label: 'Author',
+  props: {
+    searchUrl: '/panel/posts/relations/author_id',
+    valueKey: 'value',
+    labelKey: 'label',
+    clearable: true,      // offer a way back to "no selection"
+    allowCreate: true,    // offer "Create …" for an unmatched name
+  },
+}
+```
+
+### Endpoint contract
+
+One path answers three things:
+
+| Request | Returns |
+|---|---|
+| `GET ?q=term` | `{ data: [{ value, label }], meta: { total, limit, truncated } }` |
+| `GET ?values=id[,id]` | `{ data: [...] }` — labels for identifiers the field already holds |
+| `POST { label }` | `{ data: { value, label } }` — create from a typed name |
+
+`?values=` exists because a searchable field arrives with an identifier but
+no label: the list it came from was never sent, so the control asks what to
+call its current value before rendering.
+
+`meta.truncated` is rendered as a visible notice. A silently capped list
+reads as "that is everything", which is how someone concludes a record does
+not exist.
+
+### Behaviour worth knowing
+
+**The input always names what is actually held.** Typing filters the list,
+but typed-and-never-chosen text is not a selection: dismissing the dropdown
+(Escape, blur, clicking away) reverts the input to the held value's label.
+Without that, the display and the value disagree and the next submit proves
+it. Emptying the input still means deselect.
+
+**`allowCreate` is an offer, not a permission.** The row is hidden when the
+exact name is already listed, and the `POST` must re-check server-side that
+the target really can be created from a label alone — a forged offer buys
+nothing. A refusal is shown verbatim under the field. Without a `searchUrl`,
+the field emits a `create` event instead for the page to handle.
+
+## `repeater` — child rows
+
+```js
+{
+  type: 'repeater',
+  key: 'lines',
+  label: 'Lines',
+  fields: [                        // the child's own fields
+    { key: 'item_id', type: 'belongs-to', label: 'Item', width: '1/2' },
+    { key: 'quantity', type: 'text', label: 'Quantity', width: '1/2',
+      props: { type: 'number', step: '0.001' } },
+  ],
+}
+```
+
+Rows are plain objects keyed by the sub-field keys, plus an `id` for rows
+that already exist. **A row with no `id` is new** — that is how the server
+tells create from update, and how it knows which rows were removed.
+
+Sub-fields render through the same registry as top-level fields, so a
+`belongs-to` inside a row behaves exactly like one outside it (including
+its own `searchUrl`, usually addressed with a dotted path such as
+`lines.item_id`).
+
+## Row-addressed errors
+
+Server validation for a child row comes back under a dotted key:
+
+```json
+{ "errors": { "lines.1.quantity": "Another row already uses this." } }
+```
+
+`BlueprintForm` fans those out to the container field as `nestedErrors`,
+keyed relative to it (`1.quantity`), and the repeater pins each message to
+its row. A container field type that wants this only has to accept a
+`nestedErrors` prop — see [custom-fields.md](custom-fields.md).
+
+Two lifetime rules, both deliberate:
+
+- **Editing the container clears its row messages.** Any edit may have been
+  the fix, and a stale message pinned to a reordered list points at the
+  wrong row.
+- **A fresh batch of server errors resets what counts as "already edited".**
+  Server errors only show on untouched fields — but every field the user
+  filled in before submitting is touched, so without this reset the server's
+  answer *about that edit* would be suppressed on arrival. After the message
+  appears, editing again hides it: that edit is a response to it.
+
+## Field widths
+
+Sub-fields honour the same `width` values as top-level fields (`1/4`,
+`1/3`, `1/2`, `2/3`, `3/4`, `full`) against a twelve-column grid, so a
+two-field row reads as halves and a three-field row as thirds. Past three,
+columns get too narrow for a label and each field takes its own row.

package/docs/roadmap.md

@@ -0,0 +1,38 @@
+
+### Correction: the panel package always had tests (2026-08-25)
+
+Several entries above claim the panel package had "zero tests" and count a
+package suite growing from nothing. **That was wrong.** The package has its
+own `tests/` directory and its own `vitest.config.ts`, and has carried 32
+spec files / 479 tests throughout — including `useQuery.spec.ts`,
+`useAsyncData.spec.ts`, `reconcile.spec.ts` and `optimistic.spec.ts`, the
+very modules described here as untested.
+
+Two scoped-wrong checks produced the error and agreed with each other: a
+`find src -name "*.test.ts"` that never looked outside `src/`, and a root
+`vitest run` whose `include` only covered `assets/**`. Neither would have
+caught it; running the package's own suite would have.
+
+Consequences cleaned up:
+
+- The duplicate specs written on that premise (`useQuery`, `useAsyncData`,
+  `reconcile`) are deleted — the existing ones cover the same ground, down
+  to the invalidation-coalescing case.
+- Genuinely new specs (writeGate, moduleSingleton, usePendingKeys,
+  useFieldSaver ordering, optimistic ordering, unsaved-changes, belongs-to
+  revert and create, blueprint row errors) moved from `src/` into `tests/`
+  where the package's own runner sees them: 42 files, 530 tests.
+- The root `vitest.config.ts` include added for the misplaced files is
+  reverted.
+
+**And the consolidation found a real bug.** Adding files changed timing
+enough to expose an intermittently failing pre-existing spec: `useQuery`
+skipped a revalidation when a subscriber arrived in the *same millisecond*
+as the previous fetch, because `Date.now() - updatedAt > staleTime` reads as
+"still fresh" at zero elapsed — so the default `staleTime: 0` did not
+reliably mean "always revalidate". Now `>=`. Three consecutive full runs
+green.
+
+The claim to keep from those entries is narrower but still true: the package
+had **no component (`.vue`) mounting tests** before this work, and now has
+them for BlueprintForm and BelongsToSelect.