@kahitsan/ksui 0.15.1 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "ksui is a standalone set of SolidJS UI components for KahitSan/Hilinga and any SolidJS app. Published to the public npm registry and consumed as a normal dependency. Ships source under a `solid` export condition so the consumer's vite-plugin-solid compiles it with only solid-js externalized; it depends on nothing but solid-js + lucide-solid and injects its own CSS.",
   "type": "module",
   "main": "./src/index.ts",
@@ -32,6 +32,11 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "dev:e2e": "vite --config e2e/vite.config.ts",
     "changeset": "changeset",
     "version": "changeset version",
     "release": "changeset publish"
@@ -50,8 +55,14 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
+    "@playwright/test": "^1.50.0",
+    "@solidjs/testing-library": "^0.8.0",
+    "jsdom": "^26.0.0",
     "solid-js": "^1.9.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0",
+    "vite-plugin-solid": "^2.11.0",
+    "vitest": "^4.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/components/base/Avatar.tsx

@@ -20,11 +20,18 @@ const sizeMap: Record<string, number> = {
  * people; use AccountAvatar directly for financial accounts.
  */
 export default function Avatar(props: AvatarProps) {
+  // Getter-backed so name/image stay reactive: a parent rebinding them on a live
+  // Avatar (e.g. an in-session profile update) re-renders, rather than snapshotting
+  // the values once at component init.
   const account: AvatarAccount = {
     id: 0,
     type: "user",
-    name: props.name,
-    image: props.image,
+    get name() {
+      return props.name;
+    },
+    get image() {
+      return props.image;
+    },
   };
 
   return <AccountAvatar account={account} size={sizeMap[props.size ?? "md"]} class={props.class} />;

package/src/components/base/DataTable.test.tsx

@@ -0,0 +1,51 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, fireEvent } from "@solidjs/testing-library";
+import { DataTable, type DataTableColumn } from "./DataTable";
+
+// DataTable is the most reused widget in every plugin's list view. This suite
+// covers the CLIENT-SIDE mode (static data prop) only — server-side mode
+// (fetchFn) requires async mocks and is covered by the transactions integration
+// test. The dedup rule: a plugin UI test must NOT re-assert "columns render
+// headers" or "pagination shows page 2" — those are owned here.
+
+type Row = { id: number; name: string; amount: number };
+
+const COLUMNS: DataTableColumn<Row>[] = [
+  { data: "name" },
+  { data: "amount", orderable: true },
+];
+
+const DATA: Row[] = [
+  { id: 1, name: "Alpha", amount: 100 },
+  { id: 2, name: "Beta", amount: 200 },
+  { id: 3, name: "Gamma", amount: 300 },
+];
+
+describe("DataTable (client-side mode)", () => {
+  it("renders column headers", () => {
+    render(() => <DataTable columns={COLUMNS} data={DATA} />);
+    expect(screen.getByText("Name")).toBeTruthy();
+    expect(screen.getByText("Amount")).toBeTruthy();
+  });
+
+  it("renders all rows", () => {
+    render(() => <DataTable columns={COLUMNS} data={DATA} />);
+    expect(screen.getByText("Alpha")).toBeTruthy();
+    expect(screen.getByText("Beta")).toBeTruthy();
+    expect(screen.getByText("Gamma")).toBeTruthy();
+  });
+
+  it("shows empty state when data is empty", () => {
+    render(() => (
+      <DataTable columns={COLUMNS} data={[]} emptyMessage="No records" />
+    ));
+    expect(screen.getByText("No records")).toBeTruthy();
+  });
+
+  it("respects default search input placeholder", () => {
+    render(() => (
+      <DataTable columns={COLUMNS} data={DATA} searchPlaceholder="Filter..." />
+    ));
+    expect(screen.getByPlaceholderText("Filter...")).toBeTruthy();
+  });
+});

package/src/components/base/DatePicker.test.tsx

@@ -0,0 +1,51 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, fireEvent } from "@solidjs/testing-library";
+import { createSignal } from "solid-js";
+import DatePicker from "./DatePicker";
+
+// DatePicker is the shared calendar popover used by every plugin's date input
+// and by DataTable's date filter. The key behaviors: renders a trigger button
+// labeled with the selected date (or placeholder), opens a calendar popover on
+// click, and calls onChange when a day is selected. The dedup rule: plugin UI
+// tests must NOT re-assert "calendar opens on click" or "selecting a day calls
+// onChange" — those are owned here.
+
+describe("DatePicker", () => {
+  it("renders trigger with placeholder when no value is selected", () => {
+    render(() => <DatePicker value={null} onChange={() => {}} />);
+    expect(screen.getByText("Pick date")).toBeTruthy();
+  });
+
+  it("renders trigger with the selected date", () => {
+    // Use a date far from today so formatDateDisplay renders "Jun 15" (not "Today")
+    render(() => <DatePicker value="2026-06-15" onChange={() => {}} />);
+    expect(screen.getByText("Jun 15")).toBeTruthy();
+  });
+
+  it("opens calendar popover on trigger click", async () => {
+    render(() => <DatePicker value={null} onChange={() => {}} />);
+    const trigger = screen.getByText("Pick date");
+    await fireEvent.click(trigger);
+    // Calendar grid should appear with day-of-week headers
+    expect(screen.getByText("Su")).toBeTruthy();
+    expect(screen.getByText("Mo")).toBeTruthy();
+  });
+
+  it("calls onChange when a day is clicked", async () => {
+    const onChange = vi.fn();
+    render(() => <DatePicker value="2026-06-15" onChange={onChange} />);
+    // Open the popover
+    await fireEvent.click(screen.getByText("Jun 15"));
+    // Find and click a day (20 is visible in the June 2026 grid)
+    const day20 = screen.getByText("20", { exact: true });
+    await fireEvent.click(day20);
+    expect(onChange).toHaveBeenCalledOnce();
+    expect(onChange).toHaveBeenCalledWith("2026-06-20");
+  });
+
+  it("renders disabled trigger when disabled prop is true", () => {
+    render(() => <DatePicker value={null} onChange={() => {}} disabled />);
+    const trigger = screen.getByText("Pick date").closest("button")!;
+    expect(trigger.disabled).toBe(true);
+  });
+});

package/src/components/base/Modal.test.tsx

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from "vitest";
+import { render } from "@solidjs/testing-library";
+import { Show, createSignal } from "solid-js";
+import Modal from "./Modal";
+
+// Modal is the most critical shared widget — it wraps a native <dialog> with
+// focus trap, Escape handling, and backdrop-click dismissal. Every plugin's
+// create/edit/void flow opens a Modal, so its behavior is the canonical
+// dedup source: a plugin UI test must NOT re-assert that "Escape closes the
+// modal" or "clicking the backdrop calls onClose".
+//
+// Modal has no `open` prop — mount === open, unmount === closed. Wrap in
+// `<Show when={...}>` to control visibility (same pattern the plugins use).
+
+describe("Modal", () => {
+  it("renders children inside a dialog", () => {
+    const { container } = render(() => (
+      <Modal onClose={() => {}}>
+        <p>modal content</p>
+      </Modal>
+    ));
+    const dialog = container.querySelector("dialog");
+    expect(dialog).not.toBeNull();
+    expect(dialog!.getAttribute("aria-modal")).toBe("true");
+    expect(dialog!.textContent).toContain("modal content");
+  });
+
+  it("calls onClose when Escape is pressed (dismissable by default)", () => {
+    const onClose = vi.fn();
+    const { container } = render(() => (
+      <Modal onClose={onClose}>
+        <p>content</p>
+      </Modal>
+    ));
+    const dialog = container.querySelector("dialog")!;
+    dialog.dispatchEvent(new KeyboardEvent("cancel", { bubbles: true }));
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it("does NOT call onClose when dismissable=false", () => {
+    const onClose = vi.fn();
+    const { container } = render(() => (
+      <Modal onClose={onClose} dismissable={false}>
+        <p>content</p>
+      </Modal>
+    ));
+    const dialog = container.querySelector("dialog")!;
+    dialog.dispatchEvent(new KeyboardEvent("cancel", { bubbles: true }));
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("sets the requested size as max-width on the card", () => {
+    const { container } = render(() => (
+      <Modal onClose={() => {}} size="sm">
+        <p>sized</p>
+      </Modal>
+    ));
+    const card = container.querySelector(".ksui-modal-card")!;
+    expect(card.getAttribute("style")).toContain("max-width");
+  });
+
+  it("applies danger tone class when tone='danger'", () => {
+    const { container } = render(() => (
+      <Modal onClose={() => {}} tone="danger">
+        <p>danger</p>
+      </Modal>
+    ));
+    const card = container.querySelector(".ksui-modal-card")!;
+    expect(card.className).toContain("danger");
+  });
+});

package/src/components/composite/resource/ResourceDetail.tsx

@@ -0,0 +1,34 @@
+// The spec-driven read-only detail view (the non-editing face of the detail
+// modal). Renders one ksui DetailRow per declared detail row, deriving each
+// value by its kind (raw field / enum label / status / formatted datetime),
+// reproducing hand-written payees' PayeeDetail.
+import { For } from "solid-js";
+import DetailRow from "../../base/DetailRow";
+import type { ResourceRow, UiDetailRow, UiDetailValue } from "./spec";
+
+function detailValue(row: ResourceRow, value: UiDetailValue): string | null {
+  const raw = row[value.key];
+  switch (value.type) {
+    case "enum": {
+      const key = String(raw ?? "");
+      return value.labels[key] || key;
+    }
+    case "status":
+      return raw ? value.active : value.inactive;
+    case "datetime":
+      return raw ? new Date(String(raw)).toLocaleString() : null;
+    case "field":
+    default:
+      return raw === null || raw === undefined ? null : String(raw);
+  }
+}
+
+export function ResourceDetail(props: { rows: readonly UiDetailRow[]; row: ResourceRow }) {
+  return (
+    <div class="space-y-4">
+      <For each={props.rows}>
+        {(r) => <DetailRow label={r.label} value={detailValue(props.row, r.value)} />}
+      </For>
+    </div>
+  );
+}

package/src/components/composite/resource/ResourceForm.tsx

@@ -0,0 +1,114 @@
+// The spec-driven create/edit form. Renders one control per declared field
+// (text / textarea / select), reproducing hand-written payees' markup, testids,
+// and the ksui FormField + Button shell. Form state is owned by ResourcePage and
+// passed in, so a single instance backs both the create and edit modals.
+import { For, Show } from "solid-js";
+import FormField from "../../base/FormField";
+import Button from "../../base/Button";
+import { INPUT_CLASS } from "../../../utils/INPUT_CLASS";
+import type { ResourceUiSpec, UiField } from "./spec";
+
+
+export interface ResourceFormProps {
+  spec: ResourceUiSpec;
+  values: Record<string, string>;
+  setValue: (key: string, value: string) => void;
+  error: string;
+  saving: boolean;
+  submitLabel: string;
+  onSubmit: () => void;
+  onCancel: () => void;
+}
+
+function Field(props: { spec: ResourceUiSpec; field: UiField; value: string; setValue: (v: string) => void }) {
+  const f = props.field;
+  const testId =
+    f.type === "text" && (f as { required?: boolean }).required
+      ? `${props.spec.testIdPrefix}-form-${f.key}`
+      : undefined;
+  return (
+    <FormField label={f.label}>
+      <Show when={f.type === "select"}>
+        <select
+          data-testid={`${props.spec.testIdPrefix}-form-${f.key}`}
+          value={props.value}
+          onChange={(e) => props.setValue(e.currentTarget.value)}
+          class={`${INPUT_CLASS} cursor-pointer`}
+          required={f.type === "select" ? f.required : undefined}
+        >
+          <For each={f.type === "select" ? f.options : []}>
+            {(o) => <option value={o.value}>{o.label}</option>}
+          </For>
+        </select>
+      </Show>
+      <Show when={f.type === "textarea"}>
+        <textarea
+          value={props.value}
+          onInput={(e) => props.setValue(e.currentTarget.value)}
+          class={`${INPUT_CLASS} resize-none`}
+          rows={f.type === "textarea" ? (f.rows ?? 3) : 3}
+          placeholder={f.type === "textarea" ? f.placeholder : undefined}
+        />
+      </Show>
+      <Show when={f.type === "text"}>
+        <input
+          type="text"
+          data-testid={testId}
+          value={props.value}
+          onInput={(e) => props.setValue(e.currentTarget.value)}
+          class={INPUT_CLASS}
+          placeholder={f.type === "text" ? f.placeholder : undefined}
+          required={f.type === "text" ? f.required : undefined}
+        />
+      </Show>
+    </FormField>
+  );
+}
+
+export function ResourceForm(props: ResourceFormProps) {
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        props.onSubmit();
+      }}
+      class="space-y-4"
+    >
+      <Show when={props.error}>
+        <div
+          data-testid={`${props.spec.testIdPrefix}-form-error`}
+          class="rounded-lg border border-red-500/30 bg-red-500/10 px-3 py-2 text-sm text-red-400"
+        >
+          {props.error}
+        </div>
+      </Show>
+
+      <For each={props.spec.fields}>
+        {(field) => (
+          <Field
+            spec={props.spec}
+            field={field}
+            value={props.values[field.key] ?? ""}
+            setValue={(v) => props.setValue(field.key, v)}
+          />
+        )}
+      </For>
+
+      <div class="flex flex-col-reverse sm:flex-row gap-2 sm:justify-end">
+        <Button type="button" onClick={props.onCancel} intent="secondary" class="w-full sm:w-auto">
+          Cancel
+        </Button>
+        <Button
+          type="button"
+          onClick={props.onSubmit}
+          disabled={props.saving}
+          intent="primary"
+          class="gap-2 w-full sm:w-auto"
+          data-testid={`${props.spec.testIdPrefix}-form-submit`}
+        >
+          {props.submitLabel}
+        </Button>
+      </div>
+    </form>
+  );
+}

package/src/components/composite/resource/ResourcePage.tsx

@@ -0,0 +1,408 @@
+// The spec-driven default-datatable page: list + create + detail/edit + archive,
+// composed from a ResourceUiSpec onto the ksui DataTable/Modal/FormField shell.
+// This is the generic runtime that reproduces a hand-written base plugin's UI
+// (proved byte-for-behavior against payees). A base plugin's `ui/remote/index.tsx`
+// shrinks to: build a spec, render <ResourcePage spec={...} host={...} />.
+//
+// ksui stays standalone — it never imports `@kserp/host-ui`. The host primitives
+// (PageShell, PageShareButton, and the workspace/permission hooks) are INJECTED
+// via the `host` prop; the plugin passes them from its host UI kit, where the
+// hooks run inside the plugin's own component tree (correct reactive context).
+import { createSignal, For, Show, type Component, type JSX } from "solid-js";
+import { createStore } from "solid-js/store";
+import Plus from "lucide-solid/icons/plus";
+import X from "lucide-solid/icons/x";
+import Archive from "lucide-solid/icons/archive";
+import ArchiveRestore from "lucide-solid/icons/archive-restore";
+import Pencil from "lucide-solid/icons/pencil";
+import SegmentedFilter from "../../base/SegmentedFilter";
+import Button from "../../base/Button";
+import Modal from "../../base/Modal";
+import DataTable, {
+  type DataTableColumn,
+  type FetchParams,
+  type FetchResult,
+} from "../../base/DataTable";
+import { confirm } from "../../../utils/confirm";
+import {
+  buildListQuery,
+  emptyFormValues,
+  endpoints,
+  formToBody,
+  initialFilterState,
+  rowToFormValues,
+  validateForm,
+  type ResourceRow,
+  type ResourceUiSpec,
+} from "./spec";
+import { renderCell } from "./cells";
+import { ResourceForm } from "./ResourceForm";
+import { ResourceDetail } from "./ResourceDetail";
+
+/**
+ * Host primitives injected by the plugin so ksui never imports `@kserp/host-ui`.
+ * The plugin's remote entry passes these from the host UI kit; the hooks are
+ * invoked at the top of ResourcePage's render, inside the plugin's component
+ * tree, so their reactive context resolves correctly.
+ */
+export interface ResourcePageHost {
+  PageShell: Component<{
+    title: string;
+    subtitle?: string;
+    actions?: JSX.Element;
+    children: JSX.Element;
+  }>;
+  PageShareButton?: Component<{ module: string; moduleLabel: string }>;
+  useActiveWorkspace: () => {
+    activeWorkspace: () => { ws_id: number | string } | null | undefined;
+  };
+  usePermissions: () => {
+    has: (code: string) => boolean;
+    hasAny: (...codes: string[]) => boolean;
+  };
+}
+
+export interface ResourcePageProps<T extends ResourceRow> {
+  spec: ResourceUiSpec;
+  host: ResourcePageHost;
+  /** Test seam: override the fetch implementation (defaults to window.fetch). */
+  fetchImpl?: typeof fetch;
+}
+
+type RefetchApi = { refetch: () => void; resetAndRefetch: () => void };
+
+export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>) {
+  const spec = props.spec;
+  const ep = endpoints(spec);
+  const doFetch = props.fetchImpl ?? ((...a: Parameters<typeof fetch>) => fetch(...a));
+
+  const { PageShell, PageShareButton } = props.host;
+  const { activeWorkspace } = props.host.useActiveWorkspace();
+  const perms = props.host.usePermissions();
+  const canView = () => perms.has(spec.permissions.view);
+  const canEdit = () => perms.hasAny(...spec.permissions.edit);
+  const canDelete = () => perms.has(spec.permissions.delete);
+
+  const [filterState, setFilterState] = createStore<Record<string, string>>(initialFilterState(spec));
+  let refetchFn: RefetchApi | undefined;
+
+  const [detailRow, setDetailRow] = createSignal<ResourceRow | null>(null);
+  const [editing, setEditing] = createSignal(false);
+  const [createOpen, setCreateOpen] = createSignal(false);
+
+  const [form, setForm] = createStore<Record<string, string>>(emptyFormValues(spec));
+  const [saving, setSaving] = createSignal(false);
+  const [error, setError] = createSignal("");
+  const setValue = (key: string, value: string) => setForm(key, value);
+
+  function resetForm() {
+    setForm(emptyFormValues(spec));
+    setError("");
+  }
+  function populateForm(row: ResourceRow) {
+    setForm(rowToFormValues(spec, row));
+    setError("");
+  }
+
+  function wsHeaders(): Record<string, string> {
+    const ws = activeWorkspace();
+    return ws ? { "X-Workspace-Id": String(ws.ws_id) } : {};
+  }
+
+  async function openDetail(id: number) {
+    try {
+      const res = await doFetch(ep.one(id), { credentials: "include", headers: wsHeaders() });
+      if (res.ok) {
+        setDetailRow(await res.json());
+        setEditing(false);
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  function startEdit() {
+    const row = detailRow();
+    if (!row) return;
+    populateForm(row);
+    setEditing(true);
+  }
+
+  async function submit(method: "POST" | "PUT", url: string, fallback: string, onOk: (row: ResourceRow) => void) {
+    const msg = validateForm(spec, form);
+    if (msg) {
+      setError(msg);
+      return;
+    }
+    setSaving(true);
+    setError("");
+    try {
+      const res = await doFetch(url, {
+        method,
+        credentials: "include",
+        headers: { "Content-Type": "application/json", ...wsHeaders() },
+        body: JSON.stringify(formToBody(spec, form)),
+      });
+      // create allows the idempotent-200 path; both treat non-ok as an error
+      if (!res.ok && !(method === "POST" && res.status === 200)) {
+        const err = await res.json().catch(() => ({}));
+        setError(err.error || fallback);
+        return;
+      }
+      onOk(await res.json().catch(() => ({})));
+      refetchFn?.refetch();
+    } catch {
+      setError(spec.labels.networkError);
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  async function handleCreate() {
+    await submit("POST", ep.create, spec.labels.createErrorFallback, () => {
+      setCreateOpen(false);
+      resetForm();
+    });
+  }
+
+  async function handleUpdate() {
+    const row = detailRow();
+    if (!row) return;
+    await submit("PUT", ep.one(row.id), spec.labels.updateErrorFallback, (updated) => {
+      if (updated && typeof updated.id === "number") setDetailRow(updated);
+      setEditing(false);
+    });
+  }
+
+  async function handleArchive(id: number) {
+    if (
+      !(await confirm({
+        title: spec.labels.archiveTitle,
+        message: spec.labels.archiveMessage,
+        confirmLabel: spec.labels.archiveConfirm,
+        danger: true,
+      }))
+    )
+      return;
+    try {
+      await doFetch(ep.one(id), { method: "DELETE", credentials: "include", headers: wsHeaders() });
+      setDetailRow(null);
+      refetchFn?.refetch();
+    } catch {
+      /* ignore */
+    }
+  }
+
+  async function handleRestore(id: number) {
+    try {
+      const res = await doFetch(ep.restore(id), { method: "PATCH", credentials: "include", headers: wsHeaders() });
+      if (res.ok) {
+        setDetailRow(await res.json());
+        refetchFn?.refetch();
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  const columns: DataTableColumn<ResourceRow>[] = spec.columns.map((c) => ({
+    data: c.key,
+    title: c.title,
+    orderable: c.orderable ?? false,
+    render: (_v, _t, row) => renderCell(spec, c, row, openDetail),
+  }));
+
+  return (
+    <Show when={canView()}>
+      <PageShell
+        title={spec.title}
+        subtitle={spec.subtitle}
+        actions={
+          <>
+            <Show when={spec.share}>
+              {(s) =>
+                PageShareButton ? (
+                  <PageShareButton module={s().module} moduleLabel={s().moduleLabel} />
+                ) : null
+              }
+            </Show>
+            <Show when={canEdit()}>
+              <Button
+                intent="primary"
+                variant="clip1"
+                icon={Plus}
+                data-testid={`${spec.testIdPrefix}-add-btn`}
+                onClick={() => {
+                  resetForm();
+                  setCreateOpen(true);
+                }}
+              >
+                {spec.labels.add}
+              </Button>
+            </Show>
+          </>
+        }
+      >
+        <DataTable<ResourceRow>
+          refetchKey={() => activeWorkspace()?.ws_id}
+          fetchFn={async (params: FetchParams): Promise<FetchResult<ResourceRow>> => {
+            const q = buildListQuery(spec, params, filterState);
+            const res = await doFetch(`${ep.list}?${q}`, { credentials: "include", headers: wsHeaders() });
+            return res.json();
+          }}
+          columns={columns}
+          searching={true}
+          ordering={true}
+          paging={true}
+          searchPlaceholder={spec.labels.searchPlaceholder}
+          emptyMessage={spec.labels.empty}
+          noResultsMessage={spec.labels.noResults}
+          filters={
+            <div class="flex items-center gap-2 flex-wrap">
+              <For each={spec.filters ?? []}>
+                {(f) =>
+                  f.type === "segmented" ? (
+                    <SegmentedFilter
+                      options={[...f.options]}
+                      value={filterState[f.param]}
+                      onChange={(v: string) => setFilterState(f.param, v)}
+                      testIdPrefix={f.testIdPrefix}
+                    />
+                  ) : (
+                    <select
+                      value={filterState[f.param]}
+                      onChange={(e) => setFilterState(f.param, e.currentTarget.value)}
+                      class="rounded-lg border border-zinc-800/50 bg-zinc-900 px-3 py-1.5 text-xs text-zinc-400 cursor-pointer"
+                    >
+                      <For each={f.options}>{(o) => <option value={o.value}>{o.label}</option>}</For>
+                    </select>
+                  )
+                }
+              </For>
+            </div>
+          }
+          onRefetch={(api) => {
+            refetchFn = api;
+          }}
+        />
+      </PageShell>
+
+      {/* Create modal */}
+      <Show when={createOpen()}>
+        <Modal
+          onClose={() => {
+            setCreateOpen(false);
+            resetForm();
+          }}
+          size="lg"
+        >
+          <div data-testid={`${spec.testIdPrefix}-create-modal`}>
+            <div class="flex items-center justify-between mb-6">
+              <h2 class="text-lg font-semibold text-zinc-100">{spec.labels.createTitle}</h2>
+              <button
+                onClick={() => {
+                  setCreateOpen(false);
+                  resetForm();
+                }}
+                class="text-zinc-500 hover:text-zinc-300 cursor-pointer"
+                aria-label="Close"
+              >
+                <X size={20} />
+              </button>
+            </div>
+            <ResourceForm
+              spec={spec}
+              values={form}
+              setValue={setValue}
+              error={error()}
+              saving={saving()}
+              submitLabel={spec.labels.createSubmit}
+              onSubmit={handleCreate}
+              onCancel={() => {
+                setCreateOpen(false);
+                resetForm();
+              }}
+            />
+          </div>
+        </Modal>
+      </Show>
+
+      {/* Detail / edit modal */}
+      <Show when={detailRow()}>
+        {(row) => (
+          <Modal
+            onClose={() => {
+              setDetailRow(null);
+              setEditing(false);
+            }}
+            size="lg"
+          >
+            <div data-testid={`${spec.testIdPrefix}-detail-modal`}>
+              <div class="flex items-center justify-between mb-6">
+                <h2 class="text-lg font-semibold text-zinc-100">
+                  {editing() ? spec.labels.editTitle : String(row()[spec.labels.titleField] ?? "")}
+                </h2>
+                <div class="flex items-center gap-2">
+                  <Show when={!editing() && canEdit()}>
+                    <button
+                      onClick={startEdit}
+                      class="text-zinc-500 hover:text-amber-400 cursor-pointer p-1"
+                      title="Edit"
+                      aria-label="Edit"
+                    >
+                      <Pencil size={16} />
+                    </button>
+                  </Show>
+                  <Show when={!editing() && canDelete()}>
+                    {row()[spec.softDeleteField] ? (
+                      <button
+                        onClick={() => handleArchive(row().id)}
+                        class="text-zinc-500 hover:text-red-400 cursor-pointer p-1"
+                        title="Archive"
+                        aria-label="Archive"
+                      >
+                        <Archive size={16} />
+                      </button>
+                    ) : (
+                      <button
+                        onClick={() => handleRestore(row().id)}
+                        class="text-zinc-500 hover:text-emerald-400 cursor-pointer p-1"
+                        title="Restore"
+                        aria-label="Restore"
+                      >
+                        <ArchiveRestore size={16} />
+                      </button>
+                    )}
+                  </Show>
+                  <button
+                    onClick={() => {
+                      setDetailRow(null);
+                      setEditing(false);
+                    }}
+                    class="text-zinc-500 hover:text-zinc-300 cursor-pointer p-1"
+                    aria-label="Close"
+                  >
+                    <X size={20} />
+                  </button>
+                </div>
+              </div>
+
+              <Show when={editing()} fallback={<ResourceDetail rows={spec.detail} row={row()} />}>
+                <ResourceForm
+                  spec={spec}
+                  values={form}
+                  setValue={setValue}
+                  error={error()}
+                  saving={saving()}
+                  submitLabel={spec.labels.editSubmit}
+                  onSubmit={handleUpdate}
+                  onCancel={() => setEditing(false)}
+                />
+              </Show>
+            </div>
+          </Modal>
+        )}
+      </Show>
+    </Show>
+  );
+}

package/src/components/composite/resource/cells.tsx

@@ -0,0 +1,44 @@
+// Column-cell rendering for the spec-driven datatable. One pure function maps a
+// UiColumn's declared render hint to the exact JSX hand-written payees ships, so
+// the generated table is byte-for-behavior identical.
+import type { JSX } from "solid-js";
+import StatusPill from "../../base/StatusPill";
+import type { ResourceRow, ResourceUiSpec, UiColumn } from "./spec";
+
+/** Render a single cell for `column` from `row`. `onTitleClick` opens detail. */
+export function renderCell(
+  spec: ResourceUiSpec,
+  column: UiColumn,
+  row: ResourceRow,
+  onTitleClick: (id: number) => void,
+): JSX.Element | string {
+  const r = column.render;
+  const raw = row[column.key];
+  switch (r.type) {
+    case "title":
+      return (
+        <button
+          data-testid={`${spec.testIdPrefix}-row-${row.id}`}
+          class="text-left text-zinc-200 hover:text-amber-400 transition-colors cursor-pointer"
+          onClick={() => onTitleClick(row.id)}
+        >
+          {String(raw ?? "")}
+        </button>
+      );
+    case "enum": {
+      const key = String(raw ?? "");
+      return <span class="text-zinc-400 text-sm capitalize">{r.labels[key] || key}</span>;
+    }
+    case "status": {
+      const active = Boolean(raw);
+      const arm = active ? r.active : r.inactive;
+      return <StatusPill label={arm.label} tone={arm.tone} dot solid />;
+    }
+    case "text":
+    default: {
+      const cls = (r.type === "text" && r.muted) ? "text-zinc-500 text-sm" : "text-zinc-400 text-sm";
+      const text = raw === null || raw === undefined || raw === "" ? "—" : String(raw);
+      return <span class={cls}>{text}</span>;
+    }
+  }
+}

package/src/components/composite/resource/spec.test.ts

@@ -0,0 +1,116 @@
+// Unit tests for the spec-driven UI runtime's PURE helpers (no DOM). They pin
+// the request/validation/form behavior that ResourcePage relies on.
+import { describe, it, expect } from "vitest";
+import {
+  buildListQuery,
+  emptyFormValues,
+  endpoints,
+  formToBody,
+  initialFilterState,
+  rowToFormValues,
+  selectDefault,
+  cleanLabel,
+  validateForm,
+  type ResourceUiSpec,
+  type UiFieldSelect,
+} from "./spec";
+
+// A self-contained fixture exercising every helper branch (segmented + select
+// filters, text/textarea/select fields, trim/trimOrNull transforms).
+const spec: ResourceUiSpec = {
+  basePath: "/api/things",
+  title: "Things",
+  permissions: { view: "things.view", edit: ["things.create", "things.edit"], delete: "things.delete" },
+  softDeleteField: "is_active",
+  testIdPrefix: "things",
+  columns: [{ key: "name", title: "Name", render: { type: "title" } }],
+  fields: [
+    { key: "name", label: "Name *", type: "text", required: true, transform: "trim" },
+    { key: "kind", label: "Kind", type: "select", default: "vendor", options: [
+      { value: "vendor", label: "Vendor" },
+      { value: "customer", label: "Customer" },
+    ] },
+    { key: "category", label: "Category", type: "text", transform: "trimOrNull" },
+    { key: "notes", label: "Notes", type: "textarea", transform: "trimOrNull" },
+  ],
+  filters: [
+    { type: "segmented", param: "status", options: ["active", "archived", "all"], default: "active", testIdPrefix: "things-status" },
+    { type: "select", param: "kind", default: "", options: [
+      { value: "", label: "All kinds" },
+      { value: "vendor", label: "Vendors" },
+    ] },
+  ],
+  detail: [{ label: "Name", value: { type: "field", key: "name" } }],
+  labels: {
+    add: "Add Thing", createTitle: "New Thing", createSubmit: "Create", editTitle: "Edit Thing",
+    editSubmit: "Save", titleField: "name", searchPlaceholder: "Search…", empty: "None yet",
+    noResults: "No matches", createErrorFallback: "Failed to create", updateErrorFallback: "Failed to update",
+    networkError: "Network error", archiveTitle: "Archive?", archiveMessage: "Hidden.", archiveConfirm: "Archive",
+  },
+};
+
+const baseParams = { page: 1, limit: 25, search: "", sortBy: null, sortDir: "asc" };
+
+describe("endpoints", () => {
+  it("derives CRUD paths from basePath", () => {
+    const ep = endpoints(spec);
+    expect(ep.list).toBe("/api/things");
+    expect(ep.one(7)).toBe("/api/things/7");
+    expect(ep.restore(7)).toBe("/api/things/7/restore");
+  });
+});
+
+describe("buildListQuery", () => {
+  it("always carries paging/search/sort + segmented filter; omits empty select", () => {
+    const q = buildListQuery(spec, baseParams, initialFilterState(spec));
+    expect(q.get("page")).toBe("1");
+    expect(q.get("sortBy")).toBe("");
+    expect(q.get("status")).toBe("active");
+    expect(q.has("kind")).toBe(false);
+  });
+  it("sends a select filter once it has a value", () => {
+    const q = buildListQuery(spec, baseParams, { status: "archived", kind: "vendor" });
+    expect(q.get("status")).toBe("archived");
+    expect(q.get("kind")).toBe("vendor");
+  });
+});
+
+describe("form values", () => {
+  it("empty form: '' for text/textarea, default option for select", () => {
+    expect(emptyFormValues(spec)).toEqual({ name: "", kind: "vendor", category: "", notes: "" });
+  });
+  it("selectDefault falls back to the first option", () => {
+    const f: UiFieldSelect = { type: "select", options: [{ value: "a", label: "A" }, { value: "b", label: "B" }] };
+    expect(selectDefault(f)).toBe("a");
+  });
+  it("rowToFormValues prefills from a row, null → ''", () => {
+    expect(rowToFormValues(spec, { id: 3, name: "X", kind: "vendor", category: null, notes: "hi" }))
+      .toEqual({ name: "X", kind: "vendor", category: "", notes: "hi" });
+  });
+});
+
+describe("validateForm", () => {
+  it("flags the first required-but-empty field with a clean label", () => {
+    expect(validateForm(spec, { name: " ", kind: "vendor", category: "", notes: "" })).toBe("Name is required");
+  });
+  it("passes when required fields are filled", () => {
+    expect(validateForm(spec, { name: "X", kind: "vendor", category: "", notes: "" })).toBeNull();
+  });
+  it("flags a required select left on an empty placeholder option", () => {
+    const s = { fields: [{ key: "kind", label: "Kind *", type: "select", required: true,
+      options: [{ value: "", label: "Choose…" }, { value: "a", label: "A" }] }] } as unknown as ResourceUiSpec;
+    expect(validateForm(s, { kind: "" })).toBe("Kind is required");
+    expect(validateForm(s, { kind: "a" })).toBeNull();
+  });
+  it("cleanLabel strips a trailing required marker", () => {
+    expect(cleanLabel("Name *")).toBe("Name");
+    expect(cleanLabel("Notes")).toBe("Notes");
+  });
+});
+
+describe("formToBody", () => {
+  it("trims required text, nulls empty optional, passes select raw", () => {
+    expect(formToBody(spec, { name: "  X  ", kind: "customer", category: "   ", notes: "  n  " }))
+      .toEqual({ name: "X", kind: "customer", category: null, notes: "n" });
+  });
+});

package/src/components/composite/resource/spec.ts

@@ -0,0 +1,305 @@
+// Spec-driven default-datatable UI runtime — the declarative contract + its PURE
+// helpers (no solid-js / ksui imports, so it unit-tests under plain node).
+//
+// Phase 2 P1 (UI half): a base plugin's list/create/edit/archive page is the
+// data-shaped projection of its resource. This module is the UI mirror of the
+// server-side `defineResource(spec)` runtime (kernel-base/resource/*): the SAME
+// field/column declarations that drive the table + migration + CRUD routes also
+// drive the page. Authored once as a `ResourceUiSpec`, rendered by `ResourcePage`
+// (ResourcePage.tsx) into the exact ksui DataTable + Modal + FormField shell a
+// hand-written base plugin ships.
+//
+// Built inside kplugin_payees as the make-or-break proof (byte-for-behavior ==
+// hand-written payees). It imports only ksui + @kserp/host-ui + solid-js, so it
+// lifts into the shared SDK / UI-kit later (that lift needs the plugin UI build
+// to resolve the SDK — a vite alias + tsconfig.ui paths entry — out of scope here).
+
+/** A row the runtime can render: any record with a numeric surrogate id. */
+export interface ResourceRow {
+  id: number;
+  [key: string]: unknown;
+}
+
+// ---- columns ---------------------------------------------------------------
+
+export type ColumnTone = "success" | "warning" | "danger" | "neutral";
+
+/** Plain text cell; renders `—` when the value is null/empty. `muted` dims it. */
+export interface UiColumnText {
+  readonly type: "text";
+  readonly muted?: boolean;
+}
+/** The clickable title cell that opens the detail modal. */
+export interface UiColumnTitle {
+  readonly type: "title";
+}
+/** Enum value rendered through a label map (e.g. vendor → "Vendor"). */
+export interface UiColumnEnum {
+  readonly type: "enum";
+  readonly labels: Readonly<Record<string, string>>;
+}
+/** A boolean column rendered as a ksui StatusPill (e.g. is_active → Active/Archived). */
+export interface UiColumnStatus {
+  readonly type: "status";
+  readonly active: { readonly label: string; readonly tone: ColumnTone };
+  readonly inactive: { readonly label: string; readonly tone: ColumnTone };
+}
+export type UiColumnRender = UiColumnText | UiColumnTitle | UiColumnEnum | UiColumnStatus;
+
+export interface UiColumn {
+  /** Row property this column reads (also the `data` key + sort field). */
+  readonly key: string;
+  readonly title: string;
+  readonly orderable?: boolean;
+  readonly render: UiColumnRender;
+}
+
+// ---- form fields -----------------------------------------------------------
+
+/** How a submitted string field is coerced into the request body. */
+export type FieldTransform = "trim" | "trimOrNull";
+
+export interface UiFieldText {
+  readonly type: "text";
+  readonly placeholder?: string;
+  readonly required?: boolean;
+  readonly transform: FieldTransform;
+}
+export interface UiFieldTextarea {
+  readonly type: "textarea";
+  readonly placeholder?: string;
+  readonly rows?: number;
+  readonly required?: boolean;
+  readonly transform: FieldTransform;
+}
+export interface UiFieldSelectOption {
+  readonly value: string;
+  readonly label: string;
+}
+export interface UiFieldSelect {
+  readonly type: "select";
+  readonly options: readonly UiFieldSelectOption[];
+  /** Default option value for a fresh create (defaults to the first option). */
+  readonly default?: string;
+  /**
+   * Reject an empty selection (a select that opens on an empty placeholder
+   * option). A select with a non-empty default never trips this; it matters
+   * for a future spec whose first option is a `""` "Choose…" placeholder.
+   */
+  readonly required?: boolean;
+}
+export type UiField = { readonly key: string; readonly label: string } & (
+  | UiFieldText
+  | UiFieldTextarea
+  | UiFieldSelect
+);
+
+// ---- filters ---------------------------------------------------------------
+
+/** A segmented control whose value is ALWAYS sent as a query param. */
+export interface UiFilterSegmented {
+  readonly type: "segmented";
+  readonly param: string;
+  readonly options: readonly string[];
+  readonly default: string;
+  readonly testIdPrefix: string;
+}
+/** A native select whose value is sent only when non-empty (`""` = no filter). */
+export interface UiFilterSelect {
+  readonly type: "select";
+  readonly param: string;
+  readonly default: string;
+  readonly options: readonly UiFieldSelectOption[];
+}
+export type UiFilter = UiFilterSegmented | UiFilterSelect;
+
+// ---- detail view -----------------------------------------------------------
+
+export type UiDetailValue =
+  | { readonly type: "field"; readonly key: string }
+  | { readonly type: "enum"; readonly key: string; readonly labels: Readonly<Record<string, string>> }
+  | { readonly type: "status"; readonly key: string; readonly active: string; readonly inactive: string }
+  | { readonly type: "datetime"; readonly key: string };
+
+export interface UiDetailRow {
+  readonly label: string;
+  readonly value: UiDetailValue;
+}
+
+// ---- the spec --------------------------------------------------------------
+
+export interface ResourceUiSpec {
+  /** REST base, e.g. "/api/payees". CRUD endpoints derive from it. */
+  readonly basePath: string;
+  /** Page title + framing. */
+  readonly title: string;
+  readonly subtitle?: string;
+  /** PageShareButton wiring. */
+  readonly share?: { readonly module: string; readonly moduleLabel: string };
+  /** Capability codes. `edit` is satisfied by hasAny(...edit). */
+  readonly permissions: {
+    readonly view: string;
+    readonly edit: readonly string[];
+    readonly delete: string;
+  };
+  /** Soft-delete boolean field; drives the archive/restore affordance + status. */
+  readonly softDeleteField: string;
+  readonly columns: readonly UiColumn[];
+  readonly fields: readonly UiField[];
+  readonly filters?: readonly UiFilter[];
+  readonly detail: readonly UiDetailRow[];
+  readonly labels: {
+    readonly add: string;
+    readonly createTitle: string;
+    readonly createSubmit: string;
+    readonly editTitle: string;
+    readonly editSubmit: string;
+    /** The detail-modal title falls back to this row field when not editing. */
+    readonly titleField: string;
+    readonly searchPlaceholder: string;
+    readonly empty: string;
+    readonly noResults: string;
+    readonly createErrorFallback: string;
+    readonly updateErrorFallback: string;
+    readonly networkError: string;
+    readonly archiveTitle: string;
+    readonly archiveMessage: string;
+    readonly archiveConfirm: string;
+  };
+  /** data-testid prefix (e.g. "payees" → payees-add-btn, payees-row-3). */
+  readonly testIdPrefix: string;
+}
+
+// ---- derived endpoints -----------------------------------------------------
+
+export interface ResourceEndpoints {
+  readonly list: string;
+  readonly create: string;
+  readonly one: (id: number) => string;
+  readonly restore: (id: number) => string;
+}
+
+export function endpoints(spec: ResourceUiSpec): ResourceEndpoints {
+  const base = spec.basePath;
+  return {
+    list: base,
+    create: base,
+    one: (id) => `${base}/${id}`,
+    restore: (id) => `${base}/${id}/restore`,
+  };
+}
+
+// ---- pure helpers (unit-tested) --------------------------------------------
+
+/** The fixed columns the list request always carries. */
+export interface ListParams {
+  readonly page: number;
+  readonly limit: number;
+  readonly search: string;
+  readonly sortBy: string | null;
+  readonly sortDir: string;
+}
+
+/**
+ * Build the list-request query string. Mirrors hand-written payees exactly:
+ * page/limit/search/sortBy/sortDir are always present; a segmented filter is
+ * always sent; a select filter is sent only when its value is non-empty.
+ */
+export function buildListQuery(
+  spec: ResourceUiSpec,
+  params: ListParams,
+  filterState: Readonly<Record<string, string>>,
+): URLSearchParams {
+  const q = new URLSearchParams({
+    page: String(params.page),
+    limit: String(params.limit),
+    search: params.search,
+    sortBy: params.sortBy || "",
+    sortDir: params.sortDir,
+  });
+  for (const f of spec.filters ?? []) {
+    const value = filterState[f.param] ?? f.default;
+    // Segmented filters are always sent; a select filter only when non-empty.
+    if (f.type === "segmented" || value) {
+      q.set(f.param, value);
+    }
+  }
+  return q;
+}
+
+/** The default filter state (each filter at its declared default). */
+export function initialFilterState(spec: ResourceUiSpec): Record<string, string> {
+  const state: Record<string, string> = {};
+  for (const f of spec.filters ?? []) state[f.param] = f.default;
+  return state;
+}
+
+/** The default option value for a select field (explicit default ?? first option). */
+export function selectDefault(field: UiFieldSelect): string {
+  return field.default ?? field.options[0]?.value ?? "";
+}
+
+/** A fresh, empty form: "" for text/textarea, the default option for a select. */
+export function emptyFormValues(spec: ResourceUiSpec): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const f of spec.fields) {
+    values[f.key] = f.type === "select" ? selectDefault(f) : "";
+  }
+  return values;
+}
+
+/** Prefill the form from an existing row (edit mode). */
+export function rowToFormValues(
+  spec: ResourceUiSpec,
+  row: Readonly<Record<string, unknown>>,
+): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const f of spec.fields) {
+    const v = row[f.key];
+    values[f.key] = v === null || v === undefined ? "" : String(v);
+  }
+  return values;
+}
+
+/** Strip a trailing required-marker (" *") from a field label. */
+export function cleanLabel(label: string): string {
+  const trimmed = label.trimEnd();
+  return (trimmed.endsWith("*") ? trimmed.slice(0, -1) : trimmed).trimEnd();
+}
+
+/**
+ * Validate the form. Returns the first required-but-empty field's error message,
+ * or null when valid. Matches payees' "Name is required" exactly.
+ */
+export function validateForm(
+  spec: ResourceUiSpec,
+  values: Readonly<Record<string, string>>,
+): string | null {
+  for (const f of spec.fields) {
+    // text/textarea/select all carry an optional `required`; a select with a
+    // non-empty default never trips this, but a placeholder-first select can.
+    if (f.required && !(values[f.key] ?? "").trim()) {
+      return `${cleanLabel(f.label)} is required`;
+    }
+  }
+  return null;
+}
+
+/** Coerce form values into the request body per each field's transform. */
+export function formToBody(
+  spec: ResourceUiSpec,
+  values: Readonly<Record<string, string>>,
+): Record<string, string | null> {
+  const body: Record<string, string | null> = {};
+  for (const f of spec.fields) {
+    const raw = values[f.key] ?? "";
+    if (f.type === "select") {
+      body[f.key] = raw;
+    } else if (f.transform === "trim") {
+      body[f.key] = raw.trim();
+    } else {
+      body[f.key] = raw.trim() || null;
+    }
+  }
+  return body;
+}

package/src/index.ts

@@ -147,6 +147,19 @@ export type { VoucherOption } from "./components/composite/VoucherPicker";
 
 export { default as NotFound, type NotFoundProps } from "./components/composite/NotFound";
 
+// Spec-driven default-datatable runtime: a base plugin's list/create/edit/archive
+// page expressed as a declarative ResourceUiSpec and rendered through ResourcePage
+// (DataTable + Modal + FormField + the host shell). Host primitives (PageShell,
+// PageShareButton, and the workspace/permission hooks) are INJECTED via the `host`
+// prop, so ksui stays standalone — it never imports `@kserp/host-ui`. The plugin's
+// remote entry shrinks to: build a ResourceUiSpec, render <ResourcePage host={...}/>.
+export { ResourcePage } from "./components/composite/resource/ResourcePage";
+export type {
+  ResourcePageProps,
+  ResourcePageHost,
+} from "./components/composite/resource/ResourcePage";
+export * from "./components/composite/resource/spec";
+
 // ---------------------------------------------------------------------------
 // Utils (not components)
 // ---------------------------------------------------------------------------

package/src/test/setup.ts

@@ -0,0 +1,18 @@
+// ksui component test setup.
+//
+// Every component injects a <style id="STYLE_ID"> once per page via
+// ensureStyle(). In jsdom each test gets a fresh document, so injection is
+// idempotent — but we still strip any leftover <style> tags between tests
+// as a safety net (e.g. shared-document jsdom mode if ever enabled).
+//
+// Portal content is portaled to document.body; cleanup between tests so a
+// previous test's portal DOM doesn't leak into the next one's queries.
+
+import { afterEach } from "vitest";
+
+afterEach(() => {
+  // Strip injected style tags
+  document.querySelectorAll("style").forEach((s) => s.remove());
+  // Strip portal content (solid-js portals append to document.body)
+  document.body.innerHTML = "";
+});