@kahitsan/ksui 0.31.1 → 0.33.0

package/src/components/composite/TransferAccountsPicker.tsx

@@ -0,0 +1,291 @@
+import { Show, type JSX } from "solid-js";
+import ArrowRightLeft from "lucide-solid/icons/arrow-right-left";
+import Plus from "lucide-solid/icons/plus";
+import AccountAvatar from "../base/AccountAvatar";
+import FormField from "../base/FormField";
+import AccountRadioPicker from "./AccountRadioPicker";
+import type { TransactionAccount } from "./TransactionForm";
+import { formatPHP } from "../../utils/formatPHP";
+
+export interface TransferAccountsPickerProps {
+  accounts: TransactionAccount[];
+  sourceAccount: string;
+  setSourceAccount: (v: string) => void;
+  destAccount: string;
+  setDestAccount: (v: string) => void;
+  sourceLabel: string;
+  destLabel: string;
+  amount: string;
+  feeAmount: string;
+  feeEnabled: boolean;
+}
+
+interface AccountTileProps {
+  role: "from" | "to";
+  account: TransactionAccount | undefined;
+  emptyHint: string;
+  delta: number;
+  onEditRequest: () => void;
+  tileTestId: string;
+  clipClass: string;
+}
+
+function AccountTile(p: AccountTileProps): JSX.Element {
+  const isFilled = () => !!p.account;
+  const isFrom = () => p.role === "from";
+  return (
+    <button
+      type="button"
+      data-testid={p.tileTestId}
+      onClick={p.onEditRequest}
+      class={`group flex flex-1 min-w-0 items-center gap-3 border px-4 py-3 text-left transition-colors cursor-pointer ${p.clipClass}`}
+      classList={{
+        "border-blue-500/40 bg-blue-500/5 hover:bg-blue-500/10":
+          isFilled() && isFrom(),
+        "border-amber-500/40 bg-amber-500/5 hover:bg-amber-500/10":
+          isFilled() && !isFrom(),
+        "border-dashed border-zinc-700 bg-zinc-900/40 hover:border-amber-500/50 hover:bg-zinc-900/60":
+          !isFilled(),
+      }}
+      aria-label={
+        isFilled()
+          ? `${isFrom() ? "Source" : "Destination"}: ${p.account!.name} — tap to change`
+          : `Select ${isFrom() ? "source" : "destination"} account`
+      }
+    >
+      <Show
+        when={p.account}
+        keyed
+        fallback={
+          <span class="flex h-8 w-8 items-center justify-center text-zinc-500">
+            <Plus size={18} />
+          </span>
+        }
+      >
+        {(a) => (
+          <AccountAvatar
+            account={a}
+            size={28}
+            iconClass={isFrom() ? "text-blue-300" : "text-amber-300"}
+          />
+        )}
+      </Show>
+      <div class="flex min-w-0 flex-col">
+        <span
+          class="text-[10px] font-semibold uppercase tracking-widest"
+          classList={{
+            "text-blue-300": isFilled() && isFrom(),
+            "text-amber-300": isFilled() && !isFrom(),
+            "text-zinc-500": !isFilled(),
+          }}
+        >
+          {isFrom() ? "From" : "To"}
+        </span>
+        <Show
+          when={p.account}
+          keyed
+          fallback={
+            <span class="text-sm text-zinc-500">{p.emptyHint}</span>
+          }
+        >
+          {(a) => (
+            <>
+              <span class="truncate text-sm font-semibold text-zinc-100">
+                {a.name}
+              </span>
+              <Show when={a.balance != null}>
+                <span class="flex items-baseline gap-1 text-[11px] tabular-nums text-zinc-400">
+                  <span class="truncate">{formatPHP(a.balance!)}</span>
+                  <Show when={p.delta !== 0}>
+                    <span
+                      class="whitespace-nowrap font-semibold"
+                      classList={{
+                        "text-red-400": p.delta < 0,
+                        "text-emerald-400": p.delta > 0,
+                      }}
+                      data-testid={`transactions-form-transfer-delta-${p.role}`}
+                    >
+                      ({p.delta > 0 ? "+" : ""}
+                      {formatPHP(p.delta)})
+                    </span>
+                  </Show>
+                </span>
+              </Show>
+            </>
+          )}
+        </Show>
+      </div>
+    </button>
+  );
+}
+
+export default function TransferAccountsPicker(
+  props: TransferAccountsPickerProps
+) {
+  const sourceMeta = () =>
+    props.accounts.find((a) => a.id.toString() === props.sourceAccount);
+  const destMeta = () =>
+    props.accounts.find((a) => a.id.toString() === props.destAccount);
+
+  const swap = () => {
+    const s = props.sourceAccount;
+    const d = props.destAccount;
+    props.setSourceAccount(d);
+    props.setDestAccount(s);
+  };
+
+  const bothFilled = () => !!props.sourceAccount && !!props.destAccount;
+
+  const amountNum = () => {
+    const n = parseFloat(props.amount);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+  };
+  const feeNum = () => {
+    if (!props.feeEnabled) return 0;
+    const n = parseFloat(props.feeAmount);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+  };
+  const sourceDelta = () => -(amountNum() + feeNum());
+  const destDelta = () => amountNum();
+
+  return (
+    <div class="space-y-3">
+      <div class="flex items-stretch gap-2 max-sm:flex-col sm:flex-row">
+        <AccountTile
+          role="from"
+          account={sourceMeta()}
+          emptyHint="Select source"
+          delta={sourceDelta()}
+          onEditRequest={() => props.setSourceAccount("")}
+          tileTestId="transactions-form-transfer-tile-from"
+          clipClass="ks-hud-clip-top-right-bottom-left"
+        />
+
+        <Show
+          when={!bothFilled()}
+          fallback={
+            <button
+              type="button"
+              data-testid="transactions-form-transfer-swap"
+              onClick={swap}
+              class="flex h-9 w-9 shrink-0 items-center justify-center self-center border border-zinc-700 bg-zinc-900 text-zinc-300 transition-colors hover:border-amber-500/60 hover:text-amber-300 cursor-pointer ks-hud-clip-button max-sm:rotate-90"
+              aria-label="Swap source and destination"
+              title="Swap source and destination"
+            >
+              <ArrowRightLeft size={14} />
+            </button>
+          }
+        >
+          <div
+            class="shrink-0 self-center max-sm:py-1 sm:px-1"
+            aria-hidden="true"
+          >
+            <svg
+              viewBox="0 0 56 14"
+              class="max-sm:hidden sm:block h-3.5 w-14"
+            >
+              <defs>
+                <linearGradient
+                  id="fin-flow-h"
+                  gradientUnits="userSpaceOnUse"
+                  x1="0"
+                  y1="7"
+                  x2="56"
+                  y2="7"
+                >
+                  <stop offset="0" stop-color="#3b82f6" />
+                  <stop offset="1" stop-color="#f59e0b" />
+                </linearGradient>
+              </defs>
+              <line
+                x1="0"
+                y1="7"
+                x2="44"
+                y2="7"
+                stroke="url(#fin-flow-h)"
+                stroke-width="2"
+                class="fin-flow-dash"
+              />
+              <path d="M44 1 L56 7 L44 13 Z" fill="#f59e0b" />
+            </svg>
+            <svg
+              viewBox="0 0 14 40"
+              class="max-sm:block sm:hidden h-10 w-3.5"
+            >
+              <defs>
+                <linearGradient
+                  id="fin-flow-v"
+                  gradientUnits="userSpaceOnUse"
+                  x1="7"
+                  y1="0"
+                  x2="7"
+                  y2="40"
+                >
+                  <stop offset="0" stop-color="#3b82f6" />
+                  <stop offset="1" stop-color="#f59e0b" />
+                </linearGradient>
+              </defs>
+              <line
+                x1="7"
+                y1="0"
+                x2="7"
+                y2="30"
+                stroke="url(#fin-flow-v)"
+                stroke-width="2"
+                class="fin-flow-dash"
+              />
+              <path d="M1 30 L13 30 L7 40 Z" fill="#f59e0b" />
+            </svg>
+          </div>
+        </Show>
+
+        <AccountTile
+          role="to"
+          account={destMeta()}
+          emptyHint={
+            props.sourceAccount ? "Select destination" : "Destination"
+          }
+          delta={destDelta()}
+          onEditRequest={() => props.setDestAccount("")}
+          tileTestId="transactions-form-transfer-tile-to"
+          clipClass="ks-hud-clip-top-left-bottom-right"
+        />
+      </div>
+
+      <Show when={!props.sourceAccount}>
+        <div
+          class="animate-[fin-slide-fade-down_0.28s_ease-out]"
+          data-testid="transactions-form-transfer-source-picker"
+        >
+          <FormField label={props.sourceLabel}>
+            <AccountRadioPicker
+              accounts={props.accounts}
+              ariaLabel={props.sourceLabel}
+              value={props.sourceAccount}
+              onChange={props.setSourceAccount}
+              excludeId={props.destAccount}
+              autoDefault={false}
+            />
+          </FormField>
+        </div>
+      </Show>
+      <Show when={props.sourceAccount && !props.destAccount}>
+        <div
+          class="animate-[fin-slide-fade-down_0.28s_ease-out]"
+          data-testid="transactions-form-transfer-dest-picker"
+        >
+          <FormField label={props.destLabel}>
+            <AccountRadioPicker
+              accounts={props.accounts}
+              ariaLabel={props.destLabel}
+              value={props.destAccount}
+              onChange={props.setDestAccount}
+              excludeId={props.sourceAccount}
+              autoDefault={false}
+            />
+          </FormField>
+        </div>
+      </Show>
+    </div>
+  );
+}

package/src/components/composite/TransferFeeChip.tsx

@@ -0,0 +1,34 @@
+import X from "lucide-solid/icons/x";
+
+export interface TransferFeeChipProps {
+  enabled: boolean;
+  onToggle: () => void;
+}
+
+export default function TransferFeeChip(props: TransferFeeChipProps) {
+  return (
+    <button
+      type="button"
+      data-testid="transactions-form-transfer-fee-toggle"
+      onClick={props.onToggle}
+      class="flex items-center gap-1.5 self-center rounded-md border px-2.5 py-1 text-[11px] font-semibold uppercase tracking-wider transition-colors cursor-pointer"
+      classList={{
+        "border-blue-500/50 bg-blue-500/15 text-blue-300 hover:bg-blue-500/25":
+          props.enabled,
+        "border-zinc-700 bg-zinc-950/60 text-zinc-400 hover:border-blue-500/40 hover:text-blue-300":
+          !props.enabled,
+      }}
+      aria-pressed={props.enabled}
+      aria-label={props.enabled ? "Remove transfer fee" : "Add transfer fee"}
+    >
+      <span>Fees</span>
+      <span
+        class="inline-flex items-center justify-center"
+        classList={{ hidden: !props.enabled }}
+        aria-hidden="true"
+      >
+        <X size={11} />
+      </span>
+    </button>
+  );
+}

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/);
+  });
+});