@modufolio/panel 0.1.0

package/docs/table-schema.md

@@ -0,0 +1,371 @@
+# Server-driven table schema
+
+`SchemaTable` renders a table from a description the **server** sends as an
+Inertia prop, instead of a `columns` array maintained in the page component.
+
+It wraps `Table` rather than replacing it — pages using `Table` directly are
+unaffected.
+
+```vue
+<SchemaTable
+  :schema="table"
+  :records="organizations.data"
+  :summaries="organizations.meta?.summaries ?? {}"
+  :filter-values="form"
+  :query-params="computedParams"
+  :sort-column="computedSortColumn"
+  :sort-direction="computedSortDirection"
+  @update:search="updateSearch"
+  @sort="handleSort"
+  @update:filter="setFilter"
+/>
+```
+
+The reference backend implementation is appkit-portfolio's `App\Table\TableSchema`,
+but the contract below is plain JSON — any backend can produce it.
+
+---
+
+## Props
+
+| Prop | Type | Description |
+|---|---|---|
+| `schema` | `TableSchema` | Required. The server-authored description |
+| `records` | `object[]` | Row data |
+| `summaries` | `Record<string, Summary[]>` | Column aggregates, from `meta.summaries` |
+| `filterValues` | `Record<string, unknown>` | Current filter form values |
+| `cellHandlers` | `Record<string, fn>` | Save callbacks for `editable` columns |
+| `queryParams` | `object` | Appended to record links so a drawer keeps list state |
+| `rowActionHandlers` | `Record<string, fn>` | Services `behaviour: 'handler'` row actions, by name |
+| `bulkActionHandlers` | `Record<string, fn>` | The same for bulk actions |
+| `visibleColumns` | `string[] \| null` | Which columns to render. `null` shows them all — `hiddenByDefault` is only honoured when the page seeds this, see [Column visibility](#column-visibility) |
+| `stack` | `StackItem[]` | The page's drawer stack. When given, the highlighted row follows the record the top drawer shows (arrow-key record pagination changes the stack without a click) |
+| `drawerType` | `string` | Restricts stack-driven highlighting to top items of this drawer type. Omitted = match any top item by id (safe with UUIDs) |
+| `search`, `sortColumn`, `sortDirection`, `loading`, `externalFocusedRowIndex` | | Forwarded to `Table`; an explicit `externalFocusedRowIndex ≥ 0` overrides the stack-derived row |
+
+Events: `update:search`, `sort`, `rowClick`, `update:filter (key, value)`,
+`resetFilters`.
+
+---
+
+## The schema contract
+
+```ts
+interface TableSchema {
+  columns: SchemaColumn[]
+  filters?: SchemaFilter[]
+  groups?: Array<{ value: string; label: string }>
+  constraints?: SchemaConstraint[]
+  recordUrl?: string | null      // '/panel/organizations/{id}'
+  emptyStateTitle?: string | null
+  emptyStateDescription?: string | null
+  searchable?: boolean
+  bulkActions?: boolean
+  stickyHeader?: boolean
+}
+```
+
+### Columns
+
+```ts
+interface SchemaColumn {
+  key: string
+  name: string
+  label: string
+  type: 'text' | 'select' | 'money' | 'numeric' | 'badge' | 'date'
+      | 'boolean' | 'image' | 'icon' | 'color'
+  sortable: boolean            // resolved server-side; never hand-declared
+  valueKey?: string            // dot path, e.g. 'organization.name'
+  descriptionKey?: string      // second line, read from another field
+  linksToRecord?: boolean
+  urlTemplate?: string         // dot-path placeholders: '{id}', '{organization.id}'
+  showArrow?: boolean
+  placeholder?: string         // default '—'
+  toggleable?: boolean
+  hiddenByDefault?: boolean
+  weight?: 'medium' | 'bold'
+  align?: 'left' | 'center' | 'right'
+  color?: string
+  icon?: string
+  limit?: number
+  copyable?: boolean
+  size?: string                // type: 'image': 'sm' | 'md' | 'lg' | 'xl'
+  rounded?: string             // type: 'image': 'none' | 'sm' | 'md' | 'lg' | 'full'
+  currency?: string            // type: 'money'
+  decimals?: number            // type: 'numeric'
+  format?: string              // type: 'date'
+  relative?: boolean
+  colors?: Record<string, string>
+  options?: Array<{ label: string; value: string; class?: string }>
+  editable?: boolean
+  disabledWhen?: string
+  readOnlyWhen?: string
+  summaries?: Array<{ type: string; label: string }>
+}
+```
+
+Helpers exported alongside: `getPath`, `resolveRecordUrl`, `isEmptyValue`,
+`cellClasses`, `truncate`, `formatValue`, `emptyFilterValue`, `filterDefaults`,
+`visibleColumnDefaults`.
+
+### Empty cells never link
+
+A cell whose value is empty (`null`, `undefined`, `''`) renders its
+`placeholder` — `'—'` by default — **unlinked**, whatever the column declares.
+`linksToRecord` and `urlTemplate` are both ignored for that row.
+
+This is deliberate. A `urlTemplate` such as
+`/panel/contacts/{id}/organization/{organization.id}` has nothing to resolve
+`{organization.id}` to when the contact has no organization, and a link
+labelled `—` that lands somewhere arbitrary is worse than plain text. So a
+contact *with* an organization drills into it and one *without* is inert —
+including for `type: 'image'`, where an absent picture shows the placeholder
+graphic and clicking it does nothing.
+
+The consequence to design around: the row itself is not a link, so an empty
+cell is dead space. Put the record's own link on a column that is always
+present (the name or title), which every listing here does.
+
+### Image columns
+
+`type: 'image'` reads **one URL** from the row — `size` and `rounded` control
+how it renders, and both belong in the schema rather than in a page override,
+so two listings cannot drift apart:
+
+```php
+Column::make('cover_url')->label('Cover')->type('image')
+    ->size('lg')->rounded('none')->linksToRecord()->notSortable(),
+```
+
+`rounded` defaults to `'full'` (an avatar); artwork and covers usually want
+`'none'` or `'md'`. When the row holds a media *object* rather than a URL,
+point `valueKey` at the field: `->value('cover.thumbnail_url')`. An empty value
+renders the placeholder graphic, not a dash.
+
+---
+
+## Actions
+
+`schema.actions` and `schema.bulkActionItems` are rendered by `SchemaTable`
+itself — including the confirmation dialogs — when the page passes no
+`#actions` / `#bulkActions` slot. A page slot always wins.
+
+```ts
+interface SchemaRowAction {
+  name: string
+  behaviour: 'drawer' | 'dialog' | 'visit' | 'delete' | 'handler'
+  label: string
+  icon?: string; color?: string
+  urlTemplate?: string      // dot-path placeholders, resolved per row
+  previewUrl?: string       // 'delete' only: what the deletion would cost
+  hiddenWhen?: string; visibleWhen?: string
+  confirm?: boolean; confirmMessage?: string
+}
+
+interface SchemaBulkAction {
+  name: string
+  behaviour: 'post' | 'handler'
+  label: string
+  icon?: string; color?: string; variant?: string
+  url?: string              // POST { ids: [...] }
+  confirm?: boolean
+  confirmMessage?: string   // '{count}' is replaced with the selection size
+}
+```
+
+| Behaviour | What the table does |
+|---|---|
+| `drawer` | Opens the row's `recordUrl` on the drawer stack (`visitDrawer`) |
+| `dialog` | The same navigation, to the action's own `urlTemplate` — the frame is the server's answer, so the table never learns what the dialog does |
+| `visit` | `router.visit(url)` |
+| `delete` | Confirms — with the server's plan when `previewUrl` is set — then `router.delete(url)` |
+| `post` | `router.post(url, { ids })` |
+| `handler` | Calls `rowActionHandlers[name]` / `bulkActionHandlers[name]`; nothing happens if none is registered, because a schema can outlive the page that serviced it |
+
+`drawer` and `dialog` are one code path: both are frames on the same stack, and
+the item the server returns carries `presentation` to say which renders. That
+is what keeps the behaviour list from growing per feature — a new interaction
+is a new route, not a new case here. See the
+[drawer protocol](./drawer-protocol.md#two-frames).
+
+Two delete flows exist because `useDeleteConfirmation` decides at construction
+whether it has a preview: an action with `previewUrl` asks the server what the
+deletion would cost, one without degrades to a plain confirmation. Handing the
+preview flow an empty URL would report every record as blocked.
+
+```vue
+<SchemaTable
+  :schema="table"
+  :row-action-handlers="{ restore: (record) => router.put(`/panel/x/${record.id}/restore`) }"
+/>
+```
+
+---
+
+## Column visibility
+
+Columns marked `toggleable` appear in `ColumnToggle`'s dropdown; ones marked
+`hiddenByDefault` start switched off. Neither flag does anything on its own —
+`Table` filters against the list the page hands it, so the page owns the state:
+
+```vue
+<SchemaTable :schema="table" :visible-columns="visibleColumns" …>
+  <template #headerActions>
+    <ColumnToggle v-model="visibleColumns" :columns="table.columns" />
+  </template>
+</SchemaTable>
+```
+
+```ts
+const visibleColumns = ref<string[]>(visibleColumnDefaults(props.table))
+```
+
+`visibleColumnDefaults` is what honours `hiddenByDefault`; seeding the ref with
+every key instead silently ignores the flag. Hiding a column changes nothing
+about the query — it is a client-side concern, and is not reflected in the URL.
+A column left un-`toggleable` cannot be hidden, which is how the identity
+column (name, title) stays on screen.
+
+---
+
+## Slots
+
+Everything you pass is forwarded to `Table`; anything you don't is generated.
+
+| Slot | Behaviour |
+|---|---|
+| `cell-{key}` | **Overrides** the generated cell for that column |
+| `filters` | **Replaces** the generated filter popover entirely |
+| `headerActions`, `actions`, `bulkActions`, `pagination`, `header` | Forwarded as-is |
+
+Overriding one column doesn't opt you out of the others — the component filters
+its generated columns against `useSlots()`.
+
+---
+
+## Filters
+
+When `schema.filters` is present, `SchemaTable` renders a `FilterPopover`
+containing the right control per filter type (`select`, `multiSelect`,
+`ternary`, `trashed`, `dateRange`), plus a group-by select and the query
+builder when the schema declares them.
+
+Values are **controlled** — the component never mutates `filterValues`. It
+emits `update:filter (key, value)`; the page writes it into its own form state:
+
+```js
+const { form } = useListFilters('/organizations', props.filters, {
+  defaults: filterDefaults(props.table),   // keys come from the schema
+})
+
+function setFilter(key, value) {
+  form[key] = value
+}
+```
+
+`filterDefaults(schema)` returns the key → empty-value map, including `group`
+and `constraints` when those are declared, so the page never restates filter
+keys.
+
+---
+
+## Editable cells
+
+The schema declares *that* a column is editable and *what* it offers; a save
+callback can't be JSON, so the page injects it:
+
+```js
+const cellHandlers = {
+  role: (record, _column, value) => updateField(record, 'role', value),
+  status: (record, _column, value) => updateField(record, 'account_status', value),
+}
+```
+
+Keyed by **column key** — note `status` above persists to `account_status`,
+which the schema's `valueKey` handles for display and the handler for the write.
+
+An editable cell is never wrapped in a record link; the control would navigate
+away on the first click.
+
+---
+
+## Summaries
+
+Aggregates arrive per column and render in a `<tfoot>` row via `Table`'s
+`summary` slot:
+
+```json
+{ "name": [{ "type": "count", "label": "Organizations", "value": 5 }] }
+```
+
+They belong with the data, not the schema — they change with every filter. The
+server should compute them over the **filtered set**, not the current page.
+
+---
+
+## Grouping
+
+`schema.groups` offers the user a grouping; the active key rides in
+`filterValues.group`. The **server** orders rows by the group field so they
+cluster, and `Table`'s `groupBy` prop draws a heading whenever the value
+changes. The client does not re-sort.
+
+---
+
+## Query builder
+
+`schema.constraints` drives `QueryBuilder.vue`: the user picks a field, an
+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 server must treat both the field and the operator as allowlists — the
+client is a convenience, not a guarantee.
+
+---
+
+## Why no closures
+
+The schema is JSON, so it cannot carry callbacks. Anything per-row is either
+computed server-side into a field the schema names (`descriptionKey`), or
+handled by a `#cell-{key}` slot override.
+
+## Editable text cells
+
+`Column::make('phone')->editable()` on a `text` column renders an inline input:
+Enter or blur saves through the page's handler for that column key, Escape
+reverts, and a rejected save keeps the typed value on screen with the reason
+attached rather than making the user retype it from memory.
+
+The page supplies the *how*, as it already does for editable selects and
+toggles — a save closure cannot cross the schema's JSON boundary.
+
+## Custom column types
+
+Columns have the same extension seam as blueprint fields:
+
+```ts
+import { registerColumnType } from '@modufolio/panel'
+import SparklineColumn from './Columns/SparklineColumn.vue'
+
+registerColumnType('sparkline', SparklineColumn)
+```
+
+A registered component receives `{ value, record, column, label, onUpdate }`
+and owns its cell completely, including how it renders an empty value. Unlike
+the field registry this resolves synchronously — a column renders once per
+visible cell, and an async loader would leave holes in the grid on first paint.
+Pass `defineAsyncComponent` yourself if you want that behaviour.
+
+Registering a built-in type's name replaces it everywhere the schema asks for
+it, which is how an application restyles `badge` without forking the table.
+
+## Active filter indicators
+
+`SchemaTable` renders a chip per active filter between the toolbar and the
+rows: the filter's label, its value in words (the option's label, not the raw
+query-string value), and an X that clears just that one. Filters live behind a
+popover, so without this the only sign a result set has been narrowed is a
+count badge on a closed button — and "no results" reads as "no such records".
+
+Pass a `#filterIndicators` slot to replace the strip entirely.

package/package.json

@@ -0,0 +1,150 @@
+{
+  "name": "@modufolio/panel",
+  "version": "0.1.0",
+  "description": "Schema-driven admin panel components for Inertia.js + Vue 3 — tables, blueprint forms, filters, actions, drawers, widgets.",
+  "license": "MIT",
+  "type": "module",
+  "author": "Maarten Thiebou",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist",
+    "styles",
+    "docs",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles": "./styles/index.css",
+    "./styles/*": "./styles/*"
+  },
+  "scripts": {
+    "build": "vite build",
+    "prepublishOnly": "npm run build",
+    "test": "vitest --run --config vitest.config.ts",
+    "type-check": "vue-tsc --noEmit -p tsconfig.json",
+    "lint": "eslint src"
+  },
+  "peerDependencies": {
+    "@heroicons/vue": "^2.0.0",
+    "@inertiajs/vue3": "^3.0.0",
+    "@vueuse/core": ">=10",
+    "lodash": "^4.17.0",
+    "prosemirror-commands": "^1.7.1",
+    "prosemirror-dropcursor": "^1.8.3",
+    "prosemirror-gapcursor": "^1.4.1",
+    "prosemirror-history": "^1.5.0",
+    "prosemirror-inputrules": "^1.5.1",
+    "prosemirror-keymap": "^1.2.3",
+    "prosemirror-model": "^1.25.11",
+    "prosemirror-schema-list": "^1.5.1",
+    "prosemirror-state": "^1.4.4",
+    "prosemirror-view": "^1.42.2",
+    "vue": "^3.5.0",
+    "vuedraggable": "^4.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@vueuse/core": {
+      "optional": true
+    },
+    "lodash": {
+      "optional": true
+    },
+    "prosemirror-commands": {
+      "optional": true
+    },
+    "prosemirror-dropcursor": {
+      "optional": true
+    },
+    "prosemirror-gapcursor": {
+      "optional": true
+    },
+    "prosemirror-history": {
+      "optional": true
+    },
+    "prosemirror-inputrules": {
+      "optional": true
+    },
+    "prosemirror-keymap": {
+      "optional": true
+    },
+    "prosemirror-model": {
+      "optional": true
+    },
+    "prosemirror-schema-list": {
+      "optional": true
+    },
+    "prosemirror-state": {
+      "optional": true
+    },
+    "prosemirror-view": {
+      "optional": true
+    },
+    "vuedraggable": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@heroicons/vue": "^2.2.0",
+    "@inertiajs/vue3": "3.0.0",
+    "@types/lodash": "^4.17.24",
+    "@typescript-eslint/eslint-plugin": "^8.68.0",
+    "@typescript-eslint/parser": "^8.68.0",
+    "@vitejs/plugin-vue": "^6.0.1",
+    "@vue/test-utils": "^2.4.6",
+    "@vueuse/core": "^13.0.0",
+    "eslint": "^9.39.5",
+    "eslint-plugin-vue": "^10.10.0",
+    "happy-dom": "^20.6.1",
+    "lodash": "^4.17.21",
+    "prosemirror-commands": "^1.7.1",
+    "prosemirror-dropcursor": "^1.8.3",
+    "prosemirror-gapcursor": "^1.4.1",
+    "prosemirror-history": "^1.5.0",
+    "prosemirror-inputrules": "^1.5.1",
+    "prosemirror-keymap": "^1.2.3",
+    "prosemirror-model": "^1.25.11",
+    "prosemirror-schema-list": "^1.5.1",
+    "prosemirror-state": "^1.4.4",
+    "prosemirror-view": "^1.42.2",
+    "typescript": "^5.9.3",
+    "vite": "^6.4.1",
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^4.0.18",
+    "vue": "^3.5.18",
+    "vue-eslint-parser": "^10.4.1",
+    "vue-tsc": "^3.2.4",
+    "vuedraggable": "^4.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modufolio/panel.git",
+    "directory": "ui"
+  },
+  "homepage": "https://github.com/modufolio/panel/tree/main/ui#readme",
+  "bugs": "https://github.com/modufolio/panel/issues",
+  "keywords": [
+    "vue",
+    "inertia",
+    "admin",
+    "panel",
+    "crud",
+    "table",
+    "form",
+    "blueprint",
+    "filament-alternative"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@floating-ui/vue": "^2.0.1"
+  }
+}

package/styles/buttons.css

@@ -0,0 +1,31 @@
+.btn-indigo {
+  @apply px-6 py-3 rounded-sm bg-indigo-600 text-white text-sm leading-4 font-bold whitespace-nowrap hover:bg-orange-400 focus:bg-orange-400;
+}
+
+.btn-spinner,
+.btn-spinner:after {
+  border-radius: 50%;
+  width: 1.5em;
+  height: 1.5em;
+}
+
+.btn-spinner {
+  font-size: 10px;
+  position: relative;
+  text-indent: -9999em;
+  border-top: 0.2em solid white;
+  border-right: 0.2em solid white;
+  border-bottom: 0.2em solid white;
+  border-left: 0.2em solid transparent;
+  transform: translateZ(0);
+  animation: spinning 1s infinite linear;
+}
+
+@keyframes spinning {
+  0% {
+    transform: rotate(0deg);
+  }
+  100% {
+    transform: rotate(360deg);
+  }
+}

package/styles/form.css

@@ -0,0 +1,74 @@
+.form-label {
+  @apply mb-2 block text-gray-700 select-none;
+}
+
+.form-input,
+.form-textarea,
+.form-select {
+  @apply p-2 leading-normal block w-full border text-gray-700 bg-white font-sans rounded-sm text-left appearance-none relative focus:border-indigo-400 focus:ring-3;
+
+  &::placeholder {
+    @apply text-gray-500 opacity-100;
+  }
+}
+
+.form-select {
+  @apply pr-6;
+
+  background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAQCAYAAAAMJL+VAAAABGdBTUEAALGPC/xhBQAAAQtJREFUOBG1lEEOgjAQRalbGj2OG9caOACn4ALGtfEuHACiazceR1PWOH/CNA3aMiTaBDpt/7zPdBKy7M/DCL9pGkvxxVp7KsvyJftL5rZt1865M+Ucq6pyyF3hNcI7Cuu+728QYn/JQA5yKaempxuZmQngOwEaYx55nu+1lQh8GIatMGi+01NwBcEmhxBqK4nAPZJ78K0KKFAJmR3oPp8+Iwgob0Oa6+TLoeCvRx+mTUYf/FVBGTPRwDkfLxnaSrRwcH0FWhNOmrkWYbE2XEicqgSa1J0LQ+aPCuQgZiLnwewbGuz5MGoAhcIkCQcjaTBjMgtXGURMVHC1wcQEy0J+Zlj8bKAnY1/UzDe2dbAVqfXn6wAAAABJRU5ErkJggg==');
+  background-size: 0.7rem;
+  background-repeat: no-repeat;
+  background-position: right 0.7rem center;
+
+  &::-ms-expand {
+    @apply opacity-0;
+  }
+}
+
+.form-input.error,
+.form-textarea.error,
+.form-select.error {
+  @apply border-red-500 focus:ring-3 focus:ring-red-200;
+}
+
+.form-error {
+  @apply text-red-700 mt-2 text-sm;
+}
+
+/**
+ * Standard bordered form control: inputs, selects, textareas, and any custom
+ * control that should read as a form field (contenteditable editors, tag and
+ * multi-select wrappers) — matching by role rather than by tag name, so a
+ * div-based editor cannot drift away from a plain <input>.
+ *
+ * Skin and default padding only. Layout (`w-full`, `flex-1`, explicit widths),
+ * padding overrides and behaviour (`resize-y`, `appearance-none`) stay on the
+ * element: Tailwind's utilities layer wins over this components layer, so a
+ * local utility always overrides the default.
+ */
+.ui-input {
+  /* focus-within, not focus: an <input> matches its own :focus-within, so the
+     same rule covers both plain controls and div-based wrappers. */
+  @apply border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 shadow-sm transition-colors
+    focus-within:border-primary-600 focus-within:ring-2 focus-within:ring-primary-600/20
+    disabled:cursor-not-allowed disabled:bg-gray-50 disabled:text-gray-500;
+
+  border-radius: var(--radius-input);
+  min-height: var(--input-height);
+}
+
+/* Single-line controls get an exact height so they line up regardless of
+   border and line-height; textareas and div-based wrappers only get a floor. */
+input.ui-input,
+select.ui-input {
+  height: var(--input-height);
+}
+
+/* Opt out for controls that are deliberately compact (filter bars, inline
+   editors) and size themselves from their own padding instead. */
+.ui-input-auto,
+input.ui-input-auto,
+select.ui-input-auto {
+  height: auto;
+  min-height: 0;
+}

package/styles/index.css

@@ -0,0 +1,15 @@
+/**
+ * @modufolio/panel styles entry.
+ *
+ * Import from the consumer's Tailwind CSS entry, inside the components layer:
+ *
+ *   @import '@modufolio/panel/styles' layer(components);
+ *
+ * and add the package to Tailwind's content scanning so component classes
+ * survive the build:
+ *
+ *   @source "../node_modules/@modufolio/panel";
+ */
+@import './tokens.css';
+@import './buttons.css';
+@import './form.css';