@kahitsan/ksui 0.17.1 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.17.1",
+  "version": "0.19.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/base/DataTable.test.tsx

@@ -48,4 +48,14 @@ describe("DataTable (client-side mode)", () => {
     ));
     expect(screen.getByPlaceholderText("Filter...")).toBeTruthy();
   });
+
+  it("respects pageLength: only that many rows render on page 1 (client-side)", () => {
+    render(() => (
+      <DataTable columns={COLUMNS} data={DATA} paging={true} pageLength={2} />
+    ));
+    // page size 2 over 3 rows → page 1 shows the first two, the third is on page 2.
+    expect(screen.getByText("Alpha")).toBeTruthy();
+    expect(screen.getByText("Beta")).toBeTruthy();
+    expect(screen.queryByText("Gamma")).toBeNull();
+  });
 });

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

@@ -294,6 +294,8 @@ export function ResourcePage<T extends ResourceRow>(
           searching={true}
           ordering={true}
           paging={true}
+          pageLength={spec.pageLength}
+          lengthMenu={spec.lengthMenu ? [...spec.lengthMenu] : undefined}
           searchPlaceholder={spec.labels.searchPlaceholder}
           emptyMessage={spec.labels.empty}
           noResultsMessage={spec.labels.noResults}

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

@@ -11,8 +11,10 @@ import {
   selectDefault,
   cleanLabel,
   validateForm,
+  resolveForeignValue,
   type ResourceUiSpec,
   type UiFieldSelect,
+  type UiColumn,
 } from "./spec";
 
 // A self-contained fixture exercising every helper branch (segmented + select
@@ -114,3 +116,25 @@ describe("formToBody", () => {
       .toEqual({ name: "X", kind: "customer", category: null, notes: "n" });
   });
 });
+
+describe("resolveForeignValue (U4 foreign-data contract)", () => {
+  const plain: UiColumn = { key: "name", title: "Name", render: { type: "text" } };
+  const foreign: UiColumn = {
+    key: "balance",
+    title: "Balance",
+    render: { type: "text" },
+    foreign: { source: { peer: "financial-accounts", field: "balance" }, onError: "dash" },
+  };
+  const row = { id: 1, name: "Acme", balance: "ignored-own-value" };
+
+  it("reads the own row value for a plain column", () => {
+    expect(resolveForeignValue(plain, row)).toBe("Acme");
+  });
+  it("THROWS for a foreign column with no resolver wired (throw-on-unwired guard)", () => {
+    expect(() => resolveForeignValue(foreign, row)).toThrow(/foreign source.*no ForeignResolver/);
+  });
+  it("delegates to a wired resolver for a foreign column", () => {
+    const resolver = (s: { peer: string; field: string }) => `${s.peer}:${s.field}=42`;
+    expect(resolveForeignValue(foreign, row, resolver)).toBe("financial-accounts:balance=42");
+  });
+});

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

@@ -42,6 +42,63 @@ export interface UiColumn {
   readonly title: string;
   readonly orderable?: boolean;
   readonly render: UiColumnRender;
+  /**
+   * Optional: the value is read from a PEER plugin, not this resource's own row
+   * (see UiForeignColumn). A foreign column is never sortable server-side.
+   */
+  readonly foreign?: UiForeignColumn;
+}
+
+// ---- U4: foreign data sources (declarative; resolved via the host consent model) ----
+
+/**
+ * Declares that a column's value is sourced from a PEER plugin rather than the
+ * resource's own row. The cross-plugin read is mediated by the host's consent model
+ * (kernel IP1). This is a FORWARD CONTRACT: a spec may declare a foreign source before
+ * the runtime can serve it — `resolveForeignValue` throws until a resolver is wired,
+ * so a missing consent path fails loud, never silently renders an empty cell.
+ */
+export interface UiForeignSource {
+  /** The peer plugin that owns the value (e.g. "financial-accounts"). */
+  readonly peer: string;
+  /** The field on the peer record this column reads. */
+  readonly field: string;
+  /** Opaque id on THIS row used to join to the peer (defaults to the column key). */
+  readonly joinKey?: string;
+}
+
+/** How a foreign column degrades when the peer read is unavailable/slow/denied. */
+export type UiForeignOnError = "hide" | "dash" | "warn";
+
+/** A column whose value comes from a peer plugin via the consent model. */
+export interface UiForeignColumn {
+  readonly source: UiForeignSource;
+  /** Degrade policy when the peer read fails — never breaks the row. Defaults to "dash". */
+  readonly onError?: UiForeignOnError;
+}
+
+/** The consent-gated peer-read seam the host supplies (kernel IP1). */
+export type ForeignResolver = (source: UiForeignSource, row: ResourceRow) => unknown;
+
+/**
+ * Read a column's value, honouring a declared foreign source. A plain column reads
+ * `row[key]`. A foreign column requires a wired `ForeignResolver` — without one it
+ * THROWS (the throw-on-unwired guard), because foreign reads cannot resolve until the
+ * host consent model exists. Callers that catch this apply the column's `onError`.
+ */
+export function resolveForeignValue(
+  col: UiColumn,
+  row: ResourceRow,
+  resolver?: ForeignResolver,
+): unknown {
+  if (!col.foreign) return row[col.key];
+  if (!resolver) {
+    throw new Error(
+      `ksui: column "${col.key}" declares a foreign source (peer "${col.foreign.source.peer}") ` +
+        `but no ForeignResolver is wired — foreign reads require the host consent model.`,
+    );
+  }
+  return resolver(col.foreign.source, row);
 }
 
 // ---- form fields -----------------------------------------------------------
@@ -156,6 +213,13 @@ export interface ResourceUiSpec {
   };
   /** data-testid prefix (e.g. "things" → things-add-btn, things-row-3). */
   readonly testIdPrefix: string;
+  /** Initial rows-per-page for the list (DataTable `pageLength`). When omitted,
+   * DataTable's own default (10) applies. A host can lower a resolved user/workspace
+   * preference in here (the platform's route-settings `pageSize`). */
+  readonly pageLength?: number;
+  /** The rows-per-page options offered in the list's page-size menu (DataTable
+   * `lengthMenu`). When omitted, DataTable's default ([10, 25, 50, 100]) applies. */
+  readonly lengthMenu?: readonly number[];
 }
 
 // ---- derived endpoints -----------------------------------------------------