@kahitsan/ksui 0.32.0 → 0.34.0

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";

package/src/utils/INPUT_CLASS.ts

@@ -1,7 +1,10 @@
 // Shared Tailwind class string for text inputs across plugin forms: a
-// full-width rounded input with the dark zinc surface and the amber focus
+// full-width rounded input with the themed input surface and the amber focus
 // ring. Copied verbatim from the packages remote UI atoms so the shared kit
 // owns the single source of truth. Pure string constant, no dependencies.
-
+//
+// bg reads --ks-input-bg (not --ks-border, THEME-SPEC §1.2's dedicated input
+// surface token) — the border token happens to be a plausible dark literal so
+// this silently looked right in the `dark` theme and only broke elsewhere.
 export const INPUT_CLASS =
-  "w-full rounded-lg border border-zinc-700 bg-zinc-800/50 px-3 py-2 text-sm text-zinc-200 focus:border-amber-500/50 focus:outline-none";
+  "w-full rounded-lg border border-[var(--ks-input-border,#3f3f46)] bg-[var(--ks-input-bg,#18181b)] px-3 py-2 text-sm text-[var(--ks-fg,#ffffff)] focus:border-[color-mix(in_srgb,var(--ks-focus-ring,#c9a961)_50%,transparent)] focus:outline-none";

package/src/utils/account-icons.ts

@@ -74,17 +74,39 @@ export function getAccountIcon(account: { icon?: string | null; type: string }):
   return DEFAULT_BY_TYPE[account.type] ?? Banknote;
 }
 
+// bank has no exact-hue token (blue-400/500 family isn't in §1.2), so it
+// drifts to the nearest semantic bucket (--ks-info, sky). e_wallet/capital's
+// bg (amber-500) and border (amber-400) are each an EXACT hex match to
+// --ks-warning and --ks-accent respectively, so those keep zero-regression
+// color-mix rather than sharing one base. Same for cash: bg is an exact
+// --ks-success match, border an exact --ks-success-fg match.
 const DEFAULT_TONE_BY_TYPE: Record<string, { text: string; bg: string; border: string }> = {
-  bank: { text: "text-blue-400", bg: "bg-blue-500/10", border: "border-blue-400/40" },
-  e_wallet: { text: "text-amber-400", bg: "bg-amber-500/10", border: "border-amber-400/40" },
-  cash: { text: "text-emerald-400", bg: "bg-emerald-500/10", border: "border-emerald-400/40" },
-  capital: { text: "text-amber-400", bg: "bg-amber-500/10", border: "border-amber-400/40" },
+  bank: {
+    text: "text-[var(--ks-info,#38bdf8)]",
+    bg: "bg-[color-mix(in_srgb,var(--ks-info,#38bdf8)_10%,transparent)]",
+    border: "border-[color-mix(in_srgb,var(--ks-info,#38bdf8)_40%,transparent)]",
+  },
+  e_wallet: {
+    text: "text-[var(--ks-accent,#fbbf24)]",
+    bg: "bg-[color-mix(in_srgb,var(--ks-warning,#f59e0b)_10%,transparent)]",
+    border: "border-[color-mix(in_srgb,var(--ks-accent,#fbbf24)_40%,transparent)]",
+  },
+  cash: {
+    text: "text-[var(--ks-success-fg,#34d399)]",
+    bg: "bg-[color-mix(in_srgb,var(--ks-success,#10b981)_10%,transparent)]",
+    border: "border-[color-mix(in_srgb,var(--ks-success-fg,#34d399)_40%,transparent)]",
+  },
+  capital: {
+    text: "text-[var(--ks-accent,#fbbf24)]",
+    bg: "bg-[color-mix(in_srgb,var(--ks-warning,#f59e0b)_10%,transparent)]",
+    border: "border-[color-mix(in_srgb,var(--ks-accent,#fbbf24)_40%,transparent)]",
+  },
 };
 
 const FALLBACK_TONE = {
-  text: "text-zinc-300",
-  bg: "bg-zinc-700/30",
-  border: "border-zinc-700/60",
+  text: "text-[var(--ks-fg-muted,#a1a1aa)]",
+  bg: "bg-[color-mix(in_srgb,var(--ks-border-strong,#3f3f46)_30%,transparent)]",
+  border: "border-[color-mix(in_srgb,var(--ks-border-strong,#3f3f46)_60%,transparent)]",
 };
 
 // Per-type accent tone for an account chip, or the account's own custom color.

package/src/utils/highlight.tsx

@@ -9,16 +9,15 @@
 // still pass their own `markClass` to override.
 
 import { type JSX } from "solid-js";
+import { injectCSS } from "./inject-css";
 
 const MARK_STYLE_ID = "ksui-mark-style";
 
 function ensureMarkStyle(): void {
-  if (typeof document === "undefined") return;
-  if (document.getElementById(MARK_STYLE_ID)) return;
-  const style = document.createElement("style");
-  style.id = MARK_STYLE_ID;
-  style.textContent = `.ksui-mark{background-color:rgba(245,158,11,0.3);color:inherit;border-radius:2px;}`;
-  document.head.appendChild(style);
+  injectCSS(
+    MARK_STYLE_ID,
+    `.ksui-mark{background-color:color-mix(in srgb, var(--ks-warning, #f59e0b) 30%, transparent);color:inherit;border-radius:2px;}`,
+  );
 }
 
 /** Case-insensitive substring test. Empty query matches everything. */

package/src/utils/inject-css.ts

@@ -0,0 +1,13 @@
+// Shared dedup so a component's CSS-in-JS string is appended to <head> once
+// per id, no matter how many instances mount — replaces the copy-pasted
+// createElement('style') pattern across ~14 components.
+const injected = new Set<string>();
+
+export function injectCSS(id: string, css: string): void {
+  if (injected.has(id) || typeof document === "undefined") return;
+  injected.add(id);
+  const style = document.createElement("style");
+  style.id = id;
+  style.textContent = css;
+  document.head.appendChild(style);
+}

package/tailwind.js

@@ -19,6 +19,10 @@
 /** @type {import('tailwindcss').Plugin} */
 export default function ksuiTailwindPlugin({ addUtilities, addComponents }) {
   // ─── Button intents ────────────────────────────────────────────────
+  // Amber/red/slate intent palette mirrors Button.tsx's own documented
+  // exception (component-authored tone system, not a 1:1 §1.2 surface/
+  // text/border mapping) — none of these rgba alpha values byte-match a
+  // §1.2 dark default, so left literal rather than guessed.
   // Primary (amber)
   addUtilities({
     ".ks-btn-primary": {
@@ -134,7 +138,7 @@ export default function ksuiTailwindPlugin({ addUtilities, addComponents }) {
       "align-items": "center",
       gap: "0.5rem",
       padding: "0.375rem 0.75rem",
-      "background-color": "rgb(24 24 27)",
+      "background-color": "var(--ks-input-bg, rgb(24 24 27))",
       border: "1px solid rgb(63 63 70 / 0.6)",
       "border-radius": "0.25rem",
       color: "rgb(228 228 231)",
@@ -152,7 +156,7 @@ export default function ksuiTailwindPlugin({ addUtilities, addComponents }) {
       padding: "0.5rem 1rem",
       "text-align": "left",
       "font-weight": 500,
-      color: "rgb(161 161 170)",
+      color: "var(--ks-fg-muted, rgb(161 161 170))",
       "font-size": "0.75rem",
       "text-transform": "uppercase",
       "letter-spacing": "0.05em",
@@ -168,7 +172,7 @@ export default function ksuiTailwindPlugin({ addUtilities, addComponents }) {
     ".ks-dt-empty": {
       padding: "2rem",
       "text-align": "center",
-      color: "rgb(113 113 122)",
+      color: "var(--ks-fg-subtle, rgb(113 113 122))",
     },
     ".ks-dt-pager": {
       display: "flex",
@@ -177,7 +181,7 @@ export default function ksuiTailwindPlugin({ addUtilities, addComponents }) {
       padding: "0.75rem 1rem",
       "border-top": "1px solid rgb(39 39 42 / 0.6)",
       "font-size": "0.8125rem",
-      color: "rgb(161 161 170)",
+      color: "var(--ks-fg-muted, rgb(161 161 170))",
     },
   });
 
@@ -194,7 +198,7 @@ export default function ksuiTailwindPlugin({ addUtilities, addComponents }) {
       padding: "1rem",
     },
     ".ks-modal-card": {
-      "background-color": "rgb(24 24 27)",
+      "background-color": "var(--ks-overlay-surface, rgb(24 24 27))",
       border: "1px solid rgb(63 63 70 / 0.6)",
       "max-height": "calc(100vh - 2rem)",
       overflow: "auto",
@@ -246,7 +250,7 @@ export default function ksuiTailwindPlugin({ addUtilities, addComponents }) {
       "background-color": "rgba(59 130 246 / 0.1)",
     },
     ".ks-pill-neutral": {
-      color: "rgb(161 161 170)",
+      color: "var(--ks-fg-muted, rgb(161 161 170))",
       "background-color": "rgb(63 63 70 / 0.3)",
     },
   });
@@ -259,7 +263,7 @@ export default function ksuiTailwindPlugin({ addUtilities, addComponents }) {
       gap: "0.25rem",
       padding: "0.25rem 0.5rem",
       "font-size": "0.75rem",
-      color: "rgb(161 161 170)",
+      color: "var(--ks-fg-muted, rgb(161 161 170))",
       "background-color": "transparent",
       border: "1px solid rgb(63 63 70 / 0.6)",
       "border-radius": "0.25rem",