@kahitsan/ksui 0.16.0 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "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",

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

@@ -1,7 +1,6 @@
-// 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.
+// The read-only detail view (the non-editing face of the detail modal). Renders
+// one DetailRow per declared detail row, deriving each value by its kind (raw
+// field / enum label / status / formatted datetime).
 import { For } from "solid-js";
 import DetailRow from "../../base/DetailRow";
 import type { ResourceRow, UiDetailRow, UiDetailValue } from "./spec";

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

@@ -1,7 +1,6 @@
-// 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.
+// The create/edit form: one control per declared field (text / textarea /
+// select) on the FormField + Button shell. Form state is owned by ResourcePage
+// and passed in, so one instance backs both the create and edit modals.
 import { For, Show } from "solid-js";
 import FormField from "../../base/FormField";
 import Button from "../../base/Button";

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

@@ -1,13 +1,13 @@
-// 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={...} />.
+// A config-driven CRUD page: a list (DataTable) with search, filters and paging,
+// plus create / view / edit / archive / restore modals — all described by one
+// declarative `ResourceUiSpec` (columns, fields, filters, labels, REST endpoints).
+// It talks to a REST resource exposing list / create / get / update / delete /
+// restore over `basePath`.
 //
-// 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).
+// Everything application-specific is injected via the `host` prop — the page-shell
+// layout, a permission check, per-request init (auth headers / credentials), a
+// refetch trigger, and any extra header actions — so the component carries no
+// app, transport, or auth assumptions of its own.
 import { createSignal, For, Show, type Component, type JSX } from "solid-js";
 import { createStore } from "solid-js/store";
 import Plus from "lucide-solid/icons/plus";
@@ -40,26 +40,35 @@ 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.
+ * Application-specific dependencies injected by the consumer. The component holds
+ * no transport, auth, tenancy or layout assumptions of its own — they all arrive
+ * here. Only `PageShell` is required; the rest default to permissive no-ops.
  */
 export interface ResourcePageHost {
+  /** Page-shell layout: a heading area + an actions slot wrapping the body. */
   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;
-  };
+  /** Permission check against the spec's permission keys. Defaults to allow-all. */
+  can?: (permission: string) => boolean;
+  /**
+   * `RequestInit` merged into every request the page makes — the seam for auth
+   * headers, credentials, or any per-tenant header. Called per request so it can
+   * read live context. The component adds only `method` and (on writes) the JSON
+   * `Content-Type` + body on top of what this returns.
+   */
+  requestInit?: () => RequestInit;
+  /** Reactive value; when it changes the list resets to page 1 and refetches. */
+  refetchKey?: () => unknown;
+  /**
+   * Render extra header actions before the built-in create button. A function
+   * (not a pre-created element) so it runs inside this component's render scope —
+   * a pre-created element would re-run outside it if the host object is rebuilt.
+   */
+  headerActions?: () => JSX.Element;
 }
 
 export interface ResourcePageProps<T extends ResourceRow> {
@@ -71,26 +80,54 @@ export interface ResourcePageProps<T extends ResourceRow> {
 
 type RefetchApi = { refetch: () => void; resetAndRefetch: () => void };
 
-export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>) {
+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 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);
+  // Read the host config ONCE so the component is robust against a consumer
+  // passing an inline `host={{...}}` literal (which Solid re-evaluates on each
+  // `props.host.*` access — re-instantiating headerActions outside render scope).
+  const {
+    PageShell,
+    can: hostCan,
+    requestInit: hostRequestInit,
+    refetchKey,
+    headerActions,
+  } = props.host;
+  const can = (key: string) => hostCan?.(key) ?? true;
+  const canView = () => can(spec.permissions.view);
+  const canEdit = () => spec.permissions.edit.some(can);
+  const canDelete = () => can(spec.permissions.delete);
 
-  const [filterState, setFilterState] = createStore<Record<string, string>>(initialFilterState(spec));
+  /** Merge the host's per-request init (headers/credentials) with method + body. */
+  function reqInit(extra?: RequestInit): RequestInit {
+    const base = hostRequestInit?.() ?? {};
+    return {
+      ...base,
+      ...extra,
+      headers: {
+        ...(base.headers as Record<string, string> | undefined),
+        ...(extra?.headers as Record<string, string> | undefined),
+      },
+    };
+  }
+
+  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 [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);
@@ -104,14 +141,9 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
     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() });
+      const res = await doFetch(ep.one(id), reqInit());
       if (res.ok) {
         setDetailRow(await res.json());
         setEditing(false);
@@ -128,7 +160,12 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
     setEditing(true);
   }
 
-  async function submit(method: "POST" | "PUT", url: string, fallback: string, onOk: (row: ResourceRow) => void) {
+  async function submit(
+    method: "POST" | "PUT",
+    url: string,
+    fallback: string,
+    onOk: (row: ResourceRow) => void
+  ) {
     const msg = validateForm(spec, form);
     if (msg) {
       setError(msg);
@@ -137,12 +174,14 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
     setSaving(true);
     setError("");
     try {
-      const res = await doFetch(url, {
-        method,
-        credentials: "include",
-        headers: { "Content-Type": "application/json", ...wsHeaders() },
-        body: JSON.stringify(formToBody(spec, form)),
-      });
+      const res = await doFetch(
+        url,
+        reqInit({
+          method,
+          headers: { "Content-Type": "application/json" },
+          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(() => ({}));
@@ -168,10 +207,15 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
   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);
-    });
+    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) {
@@ -185,7 +229,7 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
     )
       return;
     try {
-      await doFetch(ep.one(id), { method: "DELETE", credentials: "include", headers: wsHeaders() });
+      await doFetch(ep.one(id), reqInit({ method: "DELETE" }));
       setDetailRow(null);
       refetchFn?.refetch();
     } catch {
@@ -195,7 +239,7 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
 
   async function handleRestore(id: number) {
     try {
-      const res = await doFetch(ep.restore(id), { method: "PATCH", credentials: "include", headers: wsHeaders() });
+      const res = await doFetch(ep.restore(id), reqInit({ method: "PATCH" }));
       if (res.ok) {
         setDetailRow(await res.json());
         refetchFn?.refetch();
@@ -219,13 +263,7 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
         subtitle={spec.subtitle}
         actions={
           <>
-            <Show when={spec.share}>
-              {(s) =>
-                PageShareButton ? (
-                  <PageShareButton module={s().module} moduleLabel={s().moduleLabel} />
-                ) : null
-              }
-            </Show>
+            {headerActions?.()}
             <Show when={canEdit()}>
               <Button
                 intent="primary"
@@ -244,10 +282,12 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
         }
       >
         <DataTable<ResourceRow>
-          refetchKey={() => activeWorkspace()?.ws_id}
-          fetchFn={async (params: FetchParams): Promise<FetchResult<ResourceRow>> => {
+          refetchKey={refetchKey}
+          fetchFn={async (
+            params: FetchParams
+          ): Promise<FetchResult<ResourceRow>> => {
             const q = buildListQuery(spec, params, filterState);
-            const res = await doFetch(`${ep.list}?${q}`, { credentials: "include", headers: wsHeaders() });
+            const res = await doFetch(`${ep.list}?${q}`, reqInit());
             return res.json();
           }}
           columns={columns}
@@ -271,10 +311,14 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
                   ) : (
                     <select
                       value={filterState[f.param]}
-                      onChange={(e) => setFilterState(f.param, e.currentTarget.value)}
+                      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>
+                      <For each={f.options}>
+                        {(o) => <option value={o.value}>{o.label}</option>}
+                      </For>
                     </select>
                   )
                 }
@@ -298,7 +342,9 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
         >
           <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>
+              <h2 class="text-lg font-semibold text-zinc-100">
+                {spec.labels.createTitle}
+              </h2>
               <button
                 onClick={() => {
                   setCreateOpen(false);
@@ -340,7 +386,9 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
             <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] ?? "")}
+                  {editing()
+                    ? spec.labels.editTitle
+                    : String(row()[spec.labels.titleField] ?? "")}
                 </h2>
                 <div class="flex items-center gap-2">
                   <Show when={!editing() && canEdit()}>
@@ -387,7 +435,10 @@ export function ResourcePage<T extends ResourceRow>(props: ResourcePageProps<T>)
                 </div>
               </div>
 
-              <Show when={editing()} fallback={<ResourceDetail rows={spec.detail} row={row()} />}>
+              <Show
+                when={editing()}
+                fallback={<ResourceDetail rows={spec.detail} row={row()} />}
+              >
                 <ResourceForm
                   spec={spec}
                   values={form}

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

@@ -1,6 +1,5 @@
-// 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.
+// Column-cell rendering for the datatable. One pure function maps a column's
+// declared render hint (title / enum / status / text) to its cell markup.
 import type { JSX } from "solid-js";
 import StatusPill from "../../base/StatusPill";
 import type { ResourceRow, ResourceUiSpec, UiColumn } from "./spec";

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

@@ -1,18 +1,8 @@
-// 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).
+// The declarative contract for `ResourcePage` plus its PURE helpers (no solid-js
+// or component imports, so they unit-test under plain node). A `ResourceUiSpec`
+// describes a CRUD page's columns, form fields, filters, labels and REST endpoints
+// once; `ResourcePage` renders it. The shape is transport- and framework-agnostic
+// — it names columns and fields, never how requests are authed or sent.
 
 /** A row the runtime can render: any record with a numeric surrogate id. */
 export interface ResourceRow {
@@ -129,14 +119,12 @@ export interface UiDetailRow {
 // ---- the spec --------------------------------------------------------------
 
 export interface ResourceUiSpec {
-  /** REST base, e.g. "/api/payees". CRUD endpoints derive from it. */
+  /** REST base, e.g. "/api/things"; the 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). */
+  /** Permission keys passed to `host.can`. `edit` passes if ANY of its keys do. */
   readonly permissions: {
     readonly view: string;
     readonly edit: readonly string[];
@@ -166,7 +154,7 @@ export interface ResourceUiSpec {
     readonly archiveMessage: string;
     readonly archiveConfirm: string;
   };
-  /** data-testid prefix (e.g. "payees" → payees-add-btn, payees-row-3). */
+  /** data-testid prefix (e.g. "things" → things-add-btn, things-row-3). */
   readonly testIdPrefix: string;
 }
 
@@ -201,9 +189,9 @@ export interface ListParams {
 }
 
 /**
- * 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.
+ * Build the list-request query string: 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,
@@ -269,7 +257,7 @@ export function cleanLabel(label: string): string {
 
 /**
  * Validate the form. Returns the first required-but-empty field's error message,
- * or null when valid. Matches payees' "Name is required" exactly.
+ * or null when valid (e.g. "Name is required").
  */
 export function validateForm(
   spec: ResourceUiSpec,

package/src/index.ts

@@ -147,12 +147,12 @@ 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={...}/>.
+// Config-driven CRUD page: a list/create/view/edit/archive page over a REST
+// resource, described by one declarative ResourceUiSpec and rendered through
+// ResourcePage (DataTable + Modal + FormField). Everything app-specific — the
+// page-shell layout, a permission check, per-request init, a refetch trigger and
+// any extra header actions — is injected via the `host` prop, so the component
+// carries no app, transport or auth assumptions of its own.
 export { ResourcePage } from "./components/composite/resource/ResourcePage";
 export type {
   ResourcePageProps,