@modufolio/panel 0.1.0 → 0.2.0

package/docs/custom-fields.md

@@ -2,8 +2,9 @@
 
 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:
+`checkbox`, `range`, `date`, `datetime`, `time`, `date-range`, `file`, `color`,
+`tags`, `belongs-to`, `repeater`, `toggle-buttons`, `set`, `embed`, `data`,
+`hidden`). Anything app-specific is registered at boot:
 
 ```js
 createPanel({
@@ -51,6 +52,57 @@ A field component receives (via `useBlueprint`'s `fieldProps`):
 plus anything passed through the FieldDef's `props` object. Emit
 `update:modelValue` with the new value.
 
+### Render it inside `FieldPrimitive`
+
+Do not hand-roll the label, the help text or the error message. `FieldPrimitive`
+is the frame every built-in field renders inside — it owns the grid width, the
+label, the description, the message, and the ARIA relationships between them —
+and it hands the control what it needs through slot props:
+
+```vue
+<template>
+  <FieldPrimitive
+    v-bind="{ width, id, label, help, error, required }"
+    wrapper-class="ui-field-signature"
+    v-slot="{ describedBy, invalid }"
+  >
+    <canvas :id="id" :aria-describedby="describedBy" :aria-invalid="invalid" />
+  </FieldPrimitive>
+</template>
+
+<script setup lang="ts">
+import { FieldPrimitive, fieldWidthProp } from '@modufolio/panel'
+
+const props = defineProps({ ...fieldWidthProp, /* … */ })
+</script>
+```
+
+| Slot prop | Use |
+|---|---|
+| `describedBy` | `aria-describedby` — the help and error ids, or `undefined` |
+| `invalid` | `aria-invalid` — `true` while there is an error, else `undefined` |
+| `descriptionId` / `errorId` | The individual ids, when the control wires them itself |
+
+Pass the same `id` to the frame and to the control: the help and error ids
+derive from it, and that is what connects the three.
+
+A field wrapping **several** controls passes `as="fieldset"`, which renders the
+caption as a `<legend>` — `<label for>` may only point at one control, so a
+group's label would otherwise label nothing.
+
+A layout the stacked frame cannot express — a checkbox whose label sits beside
+the box — composes the parts instead:
+
+```vue
+import { FieldLabel, FieldDescription, FieldMessage } from '@modufolio/panel'
+```
+
+That split is what the built-ins do, and it exists because twenty-two of them
+used to render this scaffolding themselves: three different spacings for the
+gap under a label, `role="alert"` on some error paragraphs and not others, and
+`aria-describedby` missing from most of them, so their help text was visible to
+sighted users only.
+
 ### Container fields
 
 A field holding a list of rows (a repeater, a matrix) also receives:

package/docs/drawer-protocol.md

@@ -71,7 +71,7 @@ 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. See [table-schema.md](../../docs/table-schema.md#actions).
 
 ## Client components
 
@@ -88,6 +88,32 @@ client. See [table-schema.md](../../../docs/table-schema.md#actions).
   given a `stack` prop, so the highlighted row follows record pagination;
   reach for the composable directly only outside `SchemaTable`.
 
+## Unsaved changes
+
+Closing a frame with edits in it must ask first, and there are five ways to
+close one: the X, the back arrow, the backdrop, Escape, and clicking a frame
+further down the pile. Each used to decide for itself, so a form was protected
+on some paths and not others.
+
+They now all route through **one** discard dialog, raised whenever any frame
+the action would remove reports unsaved changes. A form opts in by reporting
+its own dirtiness:
+
+```ts
+import { useDrawerDirtyGuard } from '@modufolio/panel'
+
+const isDirty = computed(() => form.isDirty)
+useDrawerDirtyGuard(isDirty)
+```
+
+Nothing is guarded by default — a frame that never calls this closes without a
+prompt, which is right for a read-only drawer. `NestedDrawerForm` is a real
+`<form>` (so Enter submits), and its composable exposes `getChangedData()` for
+sending only the delta on edit.
+
+Background frames scale down as they recede, so a stack reads as depth rather
+than as overlapping panels.
+
 ## Never hand-write the visit
 
 The request side is three things at once — the header, `only: ['stack']`, and

package/docs/table-schema.md

@@ -319,6 +319,11 @@ operator from that field's type, and value(s). Each operator carries its
 arity (`0`, `1` or `2`), so the UI knows how many inputs to draw. Conditions
 are ANDed and sent as `constraints[]`.
 
+The value input follows the constraint's `type`: a number spinner, a date
+picker, a Yes/No select for a boolean (whose single `is` operator takes a
+value, rather than the pair of valueless operators it used to have), and a text
+box otherwise.
+
 The server must treat both the field and the operator as allowlists — the
 client is a convenience, not a guarantee.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modufolio/panel",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Schema-driven admin panel components for Inertia.js + Vue 3 — tables, blueprint forms, filters, actions, drawers, widgets.",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "prepublishOnly": "npm run build",
     "test": "vitest --run --config vitest.config.ts",
     "type-check": "vue-tsc --noEmit -p tsconfig.json",
-    "lint": "eslint src"
+    "lint": "eslint src --max-warnings 0"
   },
   "peerDependencies": {
     "@heroicons/vue": "^2.0.0",