@kahitsan/ksui 0.32.0 → 0.33.0

package/package.json

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

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

@@ -0,0 +1,141 @@
+// Pure builder for a declarative form descriptor. field.* helpers compile DOWN
+// to the EXISTING UiField union, so ResourceForm renders them with zero new
+// path. defineForm(...).fields plugs straight into the route adapter as
+// spec.fields. No solid-js — data only.
+import type { FieldTransform, UiField, UiFieldSelectOption } from "./spec.js";
+
+// ---- field defs ------------------------------------------------------------
+
+// FieldDef carries the lowered UiField body minus the key (supplied at the
+// fields-record key) and label (supplied per builder). `kind` is the discriminant.
+export interface FieldDefText {
+  readonly kind: "text";
+  readonly label: string;
+  readonly required?: boolean;
+  readonly transform: FieldTransform;
+  readonly placeholder?: string;
+}
+export interface FieldDefTextarea {
+  readonly kind: "textarea";
+  readonly label: string;
+  readonly required?: boolean;
+  readonly transform: FieldTransform;
+  readonly placeholder?: string;
+  readonly rows?: number;
+}
+export interface FieldDefSelect {
+  readonly kind: "select";
+  readonly label: string;
+  readonly required?: boolean;
+  readonly default?: string;
+  readonly options: readonly UiFieldSelectOption[];
+}
+// Declared-but-unwired kinds: present in the union so the contract is whole,
+// but no field.* builder produces them — an unwired kind is a tsc error at the
+// call site, never a silent runtime hole (the adapter also throws on it).
+export interface FieldDefUnwired {
+  readonly kind: "currency" | "date" | "relation" | "file";
+  readonly label: string;
+}
+export type FieldDef = FieldDefText | FieldDefTextarea | FieldDefSelect | FieldDefUnwired;
+
+export const field = {
+  text: (opts: {
+    label: string;
+    required?: boolean;
+    transform: FieldTransform;
+    placeholder?: string;
+  }): FieldDefText =>
+    Object.freeze({
+      kind: "text",
+      label: opts.label,
+      transform: opts.transform,
+      ...(opts.required ? { required: opts.required } : {}),
+      ...(opts.placeholder !== undefined ? { placeholder: opts.placeholder } : {}),
+    }),
+  textarea: (opts: {
+    label: string;
+    required?: boolean;
+    transform: FieldTransform;
+    placeholder?: string;
+    rows?: number;
+  }): FieldDefTextarea =>
+    Object.freeze({
+      kind: "textarea",
+      label: opts.label,
+      transform: opts.transform,
+      ...(opts.required ? { required: opts.required } : {}),
+      ...(opts.rows !== undefined ? { rows: opts.rows } : {}),
+      ...(opts.placeholder !== undefined ? { placeholder: opts.placeholder } : {}),
+    }),
+  select: (opts: {
+    label: string;
+    required?: boolean;
+    default?: string;
+    options: readonly UiFieldSelectOption[];
+  }): FieldDefSelect =>
+    Object.freeze({
+      kind: "select",
+      label: opts.label,
+      options: opts.options,
+      ...(opts.default !== undefined ? { default: opts.default } : {}),
+      ...(opts.required ? { required: opts.required } : {}),
+    }),
+} as const;
+
+// ---- the form spec ---------------------------------------------------------
+
+export interface FormSpec {
+  readonly name?: string;
+  readonly title?: string;
+  readonly fields: Readonly<Record<string, FieldDef>>;
+  // Binding seam: STRING command ids, not hardcoded verbs, so a flow runtime
+  // can slot in without recontracting the form.
+  readonly submit: { readonly create?: string; readonly update?: string; readonly label?: string };
+  readonly layout?: unknown;
+}
+
+export function defineForm(cfg: FormSpec): FormSpec {
+  return Object.freeze(cfg);
+}
+
+// ---- lowering (consumed by ./route-adapter) ---------------------------------
+
+/** Fold one FieldDef + its key into the existing UiField. THROWS on an
+ *  unwired kind so the wired subset fails loudly at build/test. */
+export function fieldToUiField(key: string, def: FieldDef): UiField {
+  switch (def.kind) {
+    case "text":
+      return {
+        key,
+        label: def.label,
+        type: "text",
+        ...(def.required ? { required: def.required } : {}),
+        transform: def.transform,
+        ...(def.placeholder !== undefined ? { placeholder: def.placeholder } : {}),
+      };
+    case "textarea":
+      return {
+        key,
+        label: def.label,
+        type: "textarea",
+        ...(def.required ? { required: def.required } : {}),
+        transform: def.transform,
+        ...(def.rows !== undefined ? { rows: def.rows } : {}),
+        ...(def.placeholder !== undefined ? { placeholder: def.placeholder } : {}),
+      };
+    case "select":
+      return {
+        key,
+        label: def.label,
+        type: "select",
+        ...(def.default !== undefined ? { default: def.default } : {}),
+        options: def.options,
+        ...(def.required ? { required: def.required } : {}),
+      };
+    default:
+      throw new Error(
+        `form-spec: field "${key}" uses unwired kind "${(def as { kind: string }).kind}" (only text/textarea/select are wired)`,
+      );
+  }
+}

package/src/components/composite/resource/route-adapter.ts

@@ -0,0 +1,63 @@
+// The compile-down core: routeToResourceSpec folds a RouteSpec DOWN to the
+// EXISTING ResourceUiSpec byte-identically, so ResourcePage (untouched) is
+// the single render engine. THROWS on unrepresentable config (a 2nd view mode,
+// a cards body, an unwired field kind) so the table-only subset is enforced at
+// author/build time, never silently dropped. Pure — no solid-js.
+import type { ResourceUiSpec, UiColumn, UiField } from "./spec.js";
+import type { BodyView, RouteSpec } from "./route-spec.js";
+import { fieldToUiField } from "./form-spec.js";
+
+/** Resolve the single body view, rejecting the multi-view / cards cases the
+ *  table-only subset does not render yet. */
+function resolveTableView(view: RouteSpec["view"]): BodyView {
+  if ("views" in view) {
+    throw new Error(
+      "route-adapter: multi-view routes are not supported (a second view mode is deferred)",
+    );
+  }
+  if (view.kind !== "table") {
+    throw new Error(
+      `route-adapter: body view "${view.kind}" is not wired (only "table" lowers to ResourcePage)`,
+    );
+  }
+  return view;
+}
+
+function routeColumns(view: BodyView): UiColumn[] {
+  if (view.kind !== "table") {
+    throw new Error(`route-adapter: cannot lower a "${view.kind}" body to columns`);
+  }
+  return view.columns.map((c) =>
+    c.orderable === undefined
+      ? { key: c.key, title: c.title, render: c.render }
+      : { key: c.key, title: c.title, orderable: c.orderable, render: c.render },
+  );
+}
+
+function routeFields(route: RouteSpec): UiField[] {
+  if (!route.form) return [];
+  return Object.entries(route.form.fields).map(([key, def]) => fieldToUiField(key, def));
+}
+
+export function routeToResourceSpec(route: RouteSpec): ResourceUiSpec {
+  const view = resolveTableView(route.view);
+
+  const spec: ResourceUiSpec = {
+    basePath: route.basePath,
+    title: route.title,
+    ...(route.subtitle !== undefined ? { subtitle: route.subtitle } : {}),
+    permissions: {
+      view: route.permissions.view,
+      edit: route.permissions.edit,
+      delete: route.permissions.delete,
+    },
+    softDeleteField: route.softDeleteField,
+    testIdPrefix: route.testIdPrefix,
+    columns: routeColumns(view),
+    fields: routeFields(route),
+    ...(route.toolbar?.filters !== undefined ? { filters: route.toolbar.filters } : {}),
+    detail: route.detail,
+    labels: route.labels,
+  };
+  return spec;
+}

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

@@ -0,0 +1,125 @@
+// Unit tests for the RouteSpec builder layer + its lowering. They pin the
+// contract that a built RouteSpec lowers to the EXACT ResourceUiSpec a
+// hand-authored spec would produce, and that unrepresentable config fails
+// loudly instead of being silently dropped.
+import { describe, it, expect } from "vitest";
+import { Cell, action, col, defineRoute, setting, table } from "./route-spec";
+import { defineForm, field, fieldToUiField } from "./form-spec";
+import { routeToResourceSpec } from "./route-adapter";
+import type { ResourceUiSpec } from "./spec";
+
+const LABELS = {
+  add: "Add Vendor",
+  createTitle: "New Vendor",
+  createSubmit: "Create",
+  editTitle: "Edit Vendor",
+  editSubmit: "Save",
+  titleField: "name",
+  searchPlaceholder: "Search vendors",
+  empty: "No vendors yet.",
+  noResults: "No vendors match.",
+  createErrorFallback: "Could not create the vendor.",
+  updateErrorFallback: "Could not update the vendor.",
+  networkError: "Network error — try again.",
+  archiveTitle: "Archive vendor?",
+  archiveMessage: "It can be restored later.",
+  archiveConfirm: "Archive",
+} as const;
+
+function vendorRoute() {
+  return defineRoute({
+    title: "Vendors",
+    basePath: "/api/vendors",
+    softDeleteField: "is_active",
+    testIdPrefix: "vendor",
+    permissions: { view: "vendors.view", edit: ["vendors.edit"], delete: "vendors.delete" },
+    header: {
+      actions: [action("add", { label: "Add Vendor", flow: "vendors.create" })],
+    },
+    view: table({
+      columns: [
+        col("name", { title: "Name", orderable: true, render: Cell.Title }),
+        col("kind", { title: "Kind", render: Cell.Enum({ a: "A", b: "B" }) }),
+        col("notes", { title: "Notes", render: Cell.Text({ muted: true }) }),
+      ],
+    }),
+    form: defineForm({
+      fields: {
+        name: field.text({ label: "Name", required: true, transform: "trim" }),
+        notes: field.textarea({ label: "Notes", transform: "trimOrNull", rows: 3 }),
+        kind: field.select({
+          label: "Kind",
+          default: "a",
+          options: [
+            { value: "a", label: "A" },
+            { value: "b", label: "B" },
+          ],
+        }),
+      },
+      submit: { create: "vendors.create", update: "vendors.update" },
+    }),
+    detail: [{ label: "Name", value: { type: "field", key: "name" } }],
+    settings: { pageSize: setting.number({ default: 25 }) },
+    labels: LABELS,
+  });
+}
+
+describe("routeToResourceSpec lowering", () => {
+  it("lowers a built route to the hand-authored ResourceUiSpec shape", () => {
+    const lowered = routeToResourceSpec(vendorRoute());
+    const hand: ResourceUiSpec = {
+      basePath: "/api/vendors",
+      title: "Vendors",
+      permissions: { view: "vendors.view", edit: ["vendors.edit"], delete: "vendors.delete" },
+      softDeleteField: "is_active",
+      testIdPrefix: "vendor",
+      columns: [
+        { key: "name", title: "Name", orderable: true, render: { type: "title" } },
+        { key: "kind", title: "Kind", render: { type: "enum", labels: { a: "A", b: "B" } } },
+        { key: "notes", title: "Notes", render: { type: "text", muted: true } },
+      ],
+      fields: [
+        { key: "name", label: "Name", type: "text", required: true, transform: "trim" },
+        { key: "notes", label: "Notes", type: "textarea", transform: "trimOrNull", rows: 3 },
+        {
+          key: "kind",
+          label: "Kind",
+          type: "select",
+          default: "a",
+          options: [
+            { value: "a", label: "A" },
+            { value: "b", label: "B" },
+          ],
+        },
+      ],
+      detail: [{ label: "Name", value: { type: "field", key: "name" } }],
+      labels: LABELS,
+    };
+    expect(lowered).toEqual(hand);
+  });
+
+  it("omits `orderable` (does not emit false) when col() left it out", () => {
+    const lowered = routeToResourceSpec(vendorRoute());
+    expect("orderable" in lowered.columns[1]).toBe(false);
+  });
+
+  it("throws on a cards body (unwired view)", () => {
+    const route = defineRoute({
+      ...vendorRoute(),
+      view: { kind: "cards", item: {} },
+    });
+    expect(() => routeToResourceSpec(route)).toThrow(/not wired/);
+  });
+
+  it("throws on a multi-view route", () => {
+    const route = defineRoute({
+      ...vendorRoute(),
+      view: { views: { t: table({ columns: [] }) }, default: "t" },
+    });
+    expect(() => routeToResourceSpec(route)).toThrow(/multi-view/);
+  });
+
+  it("throws on an unwired field kind", () => {
+    expect(() => fieldToUiField("due", { kind: "date", label: "Due" })).toThrow(/unwired kind/);
+  });
+});

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

@@ -0,0 +1,158 @@
+// Pure builder layer for declarative resource routes. defineRoute() composes a
+// frozen RouteSpec out of small helpers; the adapter (./route-adapter) folds it
+// DOWN to the existing ResourceUiSpec, so ResourcePage stays the one render
+// engine. No solid-js — this module is data only, like ./spec.ts.
+import type { ColumnTone, UiColumnRender, UiFilter, UiDetailRow } from "./spec.js";
+import type { FormSpec } from "./form-spec.js";
+
+// ---- columns ---------------------------------------------------------------
+
+/** A column descriptor; `render` is the EXISTING UiColumnRender union, so
+ *  no new cell-rendering path is introduced. */
+export interface RouteColumn {
+  readonly key: string;
+  readonly title: string;
+  readonly orderable?: boolean;
+  readonly render: UiColumnRender;
+}
+
+// Cell.* helpers emit the existing UiColumnRender union — the title field is the
+// column key, supplied at col() time, so these only carry the render shape.
+export const Cell = {
+  Title: { type: "title" } as const satisfies UiColumnRender,
+  Enum: (labels: Readonly<Record<string, string>>): UiColumnRender => ({ type: "enum", labels }),
+  Status: (opts: {
+    active: { label: string; tone: ColumnTone };
+    inactive: { label: string; tone: ColumnTone };
+  }): UiColumnRender => ({ type: "status", active: opts.active, inactive: opts.inactive }),
+  Text: (opts?: { muted?: boolean }): UiColumnRender =>
+    opts?.muted === undefined ? { type: "text" } : { type: "text", muted: opts.muted },
+} as const;
+
+/** Build a column. `orderable` is omitted (not set false) when not requested so
+ *  the lowered spec matches a hand-authored one that left it out. */
+export function col(
+  key: string,
+  opts: { title: string; orderable?: boolean; render: UiColumnRender },
+): RouteColumn {
+  const c: RouteColumn =
+    opts.orderable === undefined
+      ? { key, title: opts.title, render: opts.render }
+      : { key, title: opts.title, orderable: opts.orderable, render: opts.render };
+  return Object.freeze(c);
+}
+
+// ---- body views ------------------------------------------------------------
+
+/** A `table` body. `kind` keys a future body-renderer registry; today only
+ *  `table` is wired (the adapter THROWS on anything else). `cards` is reserved
+ *  in the union but the builder for it is intentionally absent so an unwired
+ *  view is a tsc error at the call site, not a runtime hole. */
+export interface TableView {
+  readonly kind: "table";
+  readonly columns: readonly RouteColumn[];
+}
+export interface CardsView {
+  readonly kind: "cards";
+  readonly item: unknown;
+}
+export type BodyView = TableView | CardsView;
+
+/** The only wired body builder. */
+export function table(opts: { columns: readonly RouteColumn[] }): TableView {
+  return Object.freeze({ kind: "table", columns: opts.columns });
+}
+
+// ---- header actions ---------------------------------------------------------
+
+/** A header action. `flow` is a STRING id (never an inline fn) so a flow
+ *  runtime can slot in behind a host-provided runner without recontracting. */
+export interface RouteAction {
+  readonly id: string;
+  readonly label: string;
+  readonly icon?: string;
+  readonly variant?: string;
+  readonly flow: string;
+}
+export function action(
+  id: string,
+  opts: { label: string; icon?: string; variant?: string; flow: string },
+): RouteAction {
+  return Object.freeze({
+    id,
+    label: opts.label,
+    flow: opts.flow,
+    ...(opts.icon ? { icon: opts.icon } : {}),
+    ...(opts.variant ? { variant: opts.variant } : {}),
+  });
+}
+
+// ---- the route spec ---------------------------------------------------------
+
+export interface RoutePermissions {
+  readonly view: string;
+  readonly edit: readonly string[];
+  readonly delete: string;
+}
+
+/** Labels carried straight onto the lowered ResourceUiSpec.labels. */
+export type RouteLabels = {
+  readonly add: string;
+  readonly createTitle: string;
+  readonly createSubmit: string;
+  readonly editTitle: string;
+  readonly editSubmit: string;
+  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;
+};
+
+/** A route-load setting. Reserved for a host settings store; the adapter does
+ *  not lower it (it is host-resolved later), so it is presentation metadata
+ *  only for now. */
+export interface SettingDecl {
+  readonly kind: "number";
+  readonly default: number;
+}
+export const setting = {
+  number: (opts: { default: number }): SettingDecl =>
+    Object.freeze({ kind: "number", default: opts.default }),
+} as const;
+
+export interface RouteSpec {
+  readonly path?: string;
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly icon?: string;
+  readonly basePath: string;
+  readonly softDeleteField: string;
+  readonly testIdPrefix: string;
+  readonly permissions: RoutePermissions;
+  readonly header?: { readonly actions: readonly RouteAction[] };
+  readonly toolbar?: {
+    readonly search?: { readonly placeholder: string; readonly fields: readonly string[] };
+    readonly filters?: readonly UiFilter[];
+  };
+  readonly view:
+    | BodyView
+    | { readonly views: Readonly<Record<string, BodyView>>; readonly default: string };
+  readonly form?: FormSpec;
+  readonly detail: readonly UiDetailRow[];
+  readonly settings?: Readonly<Record<string, SettingDecl>>;
+  // Sticky-footer slot — reserved in the contract, not rendered yet (needs an
+  // additive page-shell `footer?` prop on the consumer side).
+  readonly footer?: unknown;
+  readonly labels: RouteLabels;
+}
+
+/** defineRoute composes a frozen RouteSpec. Pure — no rendering, no side effects. */
+export function defineRoute(cfg: RouteSpec): RouteSpec {
+  return Object.freeze(cfg);
+}

package/src/index.ts

@@ -191,6 +191,14 @@ export type {
 } from "./components/composite/resource/ResourcePage";
 export * from "./components/composite/resource/spec";
 
+// Builder layer over ResourceUiSpec: defineRoute/defineForm compose a frozen
+// RouteSpec/FormSpec out of small helpers (col, Cell.*, table, action, field.*,
+// setting.*), and routeToResourceSpec lowers it to the exact ResourceUiSpec a
+// hand-authored spec would produce — ResourcePage stays the one render engine.
+export * from "./components/composite/resource/route-spec";
+export * from "./components/composite/resource/form-spec";
+export { routeToResourceSpec } from "./components/composite/resource/route-adapter";
+
 // U6 — declarative file/media field for the spec-driven form runtime. Value is an
 // opaque asset handle; host injects onUpload + presignUrl (storage-agnostic).
 export { default as FileField, type FileFieldProps, type AssetHandle, type FileFieldStatus } from "./components/composite/FileField";