@kahitsan/ksui 0.46.1 → 0.47.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.46.1",
+  "version": "0.47.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/TransactionForm.payee-tin.test.tsx

@@ -0,0 +1,224 @@
+// Opt-in tax-ID capture next to the payee picker: shows the picked payee's TIN
+// and address, offers inputs when they are missing, and warns when withholding
+// is on but no TIN is known.
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { render, fireEvent, waitFor } from "@solidjs/testing-library";
+import TransactionForm, { type TransactionFormProps } from "./TransactionForm";
+import { isValidTin } from "./payee-tin";
+
+function baseProps(overrides: Partial<TransactionFormProps> = {}): TransactionFormProps {
+  const noop = vi.fn();
+  return {
+    error: "",
+    saving: false,
+    category: "expense",
+    setCategory: noop,
+    subcategory: "",
+    setSubcategory: noop,
+    sourceAccount: "",
+    setSourceAccount: noop,
+    destAccount: "",
+    setDestAccount: noop,
+    amount: "",
+    setAmount: noop,
+    description: "",
+    setDescription: noop,
+    notes: "",
+    setNotes: noop,
+    date: "2026-09-10",
+    setDate: noop,
+    isPrivate: false,
+    setIsPrivate: noop,
+    sharedWith: [],
+    setSharedWith: noop,
+    sharedRoleCodes: [],
+    setSharedRoleCodes: noop,
+    backdateReason: "",
+    setBackdateReason: noop,
+    payee: "Acme Hardware",
+    setPayee: noop,
+    payeeId: 7,
+    setPayeeId: noop,
+    refNumber: "",
+    setRefNumber: noop,
+    taxType: "vat_inclusive",
+    setTaxType: noop,
+    hasEwt: false,
+    setHasEwt: noop,
+    ewtRate: "",
+    setEwtRate: noop,
+    payableKind: "",
+    setPayableKind: noop,
+    dueDate: "",
+    setDueDate: noop,
+    chequeNumber: "",
+    setChequeNumber: noop,
+    pdcStatus: "",
+    setPdcStatus: noop,
+    transferFeeEnabled: false,
+    setTransferFeeEnabled: noop,
+    transferFeeAmount: "",
+    setTransferFeeAmount: noop,
+    allowTransferFee: false,
+    pendingFiles: [],
+    setPendingFiles: noop,
+    accounts: [],
+    orgMembers: [],
+    shareableRoles: [],
+    isAdmin: true,
+    canShare: false,
+    isBackdated: false,
+    saleItems: [],
+    setSaleItems: noop,
+    saleClient: null,
+    setSaleClient: noop,
+    saleVoucher: null,
+    setSaleVoucher: noop,
+    saleManualDiscount: "",
+    setSaleManualDiscount: noop,
+    onSubmit: noop,
+    submitLabel: "Save",
+    ...overrides,
+  };
+}
+
+const tinProps = (extra: Partial<TransactionFormProps> = {}) =>
+  baseProps({
+    payeeTin: "",
+    setPayeeTin: vi.fn(),
+    payeeAddress: "",
+    setPayeeAddress: vi.fn(),
+    ...extra,
+  });
+
+function mockPayee(record: Record<string, unknown>) {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => new Response(JSON.stringify(record), { status: 200 })),
+  );
+}
+
+beforeEach(() => vi.unstubAllGlobals());
+afterEach(() => vi.unstubAllGlobals());
+
+describe("isValidTin", () => {
+  it("accepts 9 or 12 digits with or without dashes", () => {
+    expect(isValidTin("123456789")).toBe(true);
+    expect(isValidTin("123-456-789")).toBe(true);
+    expect(isValidTin("123-456-789-000")).toBe(true);
+    expect(isValidTin("123456789000")).toBe(true);
+  });
+  it("rejects other lengths and non-digits", () => {
+    expect(isValidTin("12345678")).toBe(false);
+    expect(isValidTin("1234567890")).toBe(false);
+    expect(isValidTin("12a-456-789")).toBe(false);
+  });
+  it("treats blank as valid because the field is optional", () => {
+    expect(isValidTin("")).toBe(true);
+    expect(isValidTin("   ")).toBe(true);
+  });
+});
+
+describe("TransactionForm payee tax ID", () => {
+  it("renders nothing extra when the host does not opt in", async () => {
+    mockPayee({ id: 7, name: "Acme Hardware", kind: "vendor", tin: null, address: null });
+    const { queryByTestId } = render(() => <TransactionForm {...baseProps()} />);
+    await Promise.resolve();
+    expect(queryByTestId("form-payee-tin-input")).toBeNull();
+    expect(queryByTestId("form-payee-tin-readonly")).toBeNull();
+  });
+
+  it("shows the saved TIN and address read-only and offers no input", async () => {
+    mockPayee({
+      id: 7,
+      name: "Acme Hardware",
+      kind: "vendor",
+      tin: "123-456-789-00000",
+      address: "1 Main St",
+    });
+    const { findByTestId, queryByTestId } = render(() => <TransactionForm {...tinProps()} />);
+    const line = await findByTestId("form-payee-tin-readonly");
+    expect(line.textContent).toContain("123-456-789-00000");
+    expect(line.textContent).toContain("1 Main St");
+    expect(queryByTestId("form-payee-tin-input")).toBeNull();
+    expect(queryByTestId("form-payee-address-input")).toBeNull();
+  });
+
+  it("offers TIN and address inputs when the payee has neither", async () => {
+    mockPayee({ id: 7, name: "Acme Hardware", kind: "vendor", tin: null, address: null });
+    const setPayeeTin = vi.fn();
+    const setPayeeAddress = vi.fn();
+    const { findByTestId } = render(() => (
+      <TransactionForm {...tinProps({ setPayeeTin, setPayeeAddress })} />
+    ));
+    const tin = (await findByTestId("form-payee-tin-input")) as HTMLInputElement;
+    fireEvent.input(tin, { target: { value: "123-456-789" } });
+    expect(setPayeeTin).toHaveBeenCalledWith("123-456-789");
+    const addr = (await findByTestId("form-payee-address-input")) as HTMLInputElement;
+    fireEvent.input(addr, { target: { value: "2 Side St" } });
+    expect(setPayeeAddress).toHaveBeenCalledWith("2 Side St");
+  });
+
+  it("asks only for the address when the TIN is already saved", async () => {
+    mockPayee({ id: 7, name: "Acme Hardware", kind: "vendor", tin: "123456789", address: "" });
+    const { findByTestId, queryByTestId } = render(() => <TransactionForm {...tinProps()} />);
+    await findByTestId("form-payee-address-input");
+    expect(queryByTestId("form-payee-tin-input")).toBeNull();
+  });
+
+  it("flags a malformed TIN", async () => {
+    mockPayee({ id: 7, name: "Acme Hardware", kind: "vendor", tin: null, address: null });
+    const { findByTestId, queryByTestId } = render(() => (
+      <TransactionForm {...tinProps({ payeeTin: "12-34" })} />
+    ));
+    await findByTestId("form-payee-tin-input");
+    expect(queryByTestId("form-payee-tin-error")).toBeTruthy();
+  });
+
+  it("does not flag a valid TIN", async () => {
+    mockPayee({ id: 7, name: "Acme Hardware", kind: "vendor", tin: null, address: null });
+    const { findByTestId, queryByTestId } = render(() => (
+      <TransactionForm {...tinProps({ payeeTin: "123-456-789" })} />
+    ));
+    await findByTestId("form-payee-tin-input");
+    expect(queryByTestId("form-payee-tin-error")).toBeNull();
+  });
+
+  it("warns, without blocking, when withholding is on and no TIN is known", async () => {
+    mockPayee({ id: 7, name: "Acme Hardware", kind: "vendor", tin: null, address: null });
+    const { findByTestId } = render(() => <TransactionForm {...tinProps({ hasEwt: true })} />);
+    const warn = await findByTestId("form-payee-tin-ewt-warning");
+    expect(warn.textContent).toMatch(/TIN/);
+  });
+
+  it("drops the warning once a TIN is typed or already saved", async () => {
+    mockPayee({ id: 7, name: "Acme Hardware", kind: "vendor", tin: null, address: null });
+    const typed = render(() => (
+      <TransactionForm {...tinProps({ hasEwt: true, payeeTin: "123-456-789" })} />
+    ));
+    await typed.findByTestId("form-payee-tin-input");
+    expect(typed.queryByTestId("form-payee-tin-ewt-warning")).toBeNull();
+    typed.unmount();
+
+    mockPayee({ id: 7, name: "Acme Hardware", kind: "vendor", tin: "123456789", address: "x" });
+    const saved = render(() => <TransactionForm {...tinProps({ hasEwt: true })} />);
+    await saved.findByTestId("form-payee-tin-readonly");
+    expect(saved.queryByTestId("form-payee-tin-ewt-warning")).toBeNull();
+  });
+
+  it("shows nothing before a payee is chosen", async () => {
+    mockPayee({});
+    const { queryByTestId } = render(() => (
+      <TransactionForm {...tinProps({ payee: "", payeeId: null, hasEwt: true })} />
+    ));
+    await waitFor(() => expect(queryByTestId("form-payee-tin-input")).toBeNull());
+    expect(queryByTestId("form-payee-tin-ewt-warning")).toBeNull();
+  });
+
+  it("stays out of sales", async () => {
+    mockPayee({ id: 7, name: "Acme Hardware", kind: "customer", tin: null, address: null });
+    const { queryByTestId } = render(() => <TransactionForm {...tinProps({ category: "sale" })} />);
+    await Promise.resolve();
+    expect(queryByTestId("form-payee-tin-input")).toBeNull();
+  });
+});

package/src/components/composite/TransactionForm.tsx

@@ -25,6 +25,7 @@ import TransactionAccountFields from "./TransactionAccountFields";
 import TransactionPayableFields from "./TransactionPayableFields";
 import ComboBox from "./ComboBox";
 import type { ClientOption, PayeeOption, PayeeKind } from "./picker-types";
+import { isValidTin } from "./payee-tin";
 import VoucherPicker, { type VoucherOption } from "./VoucherPicker";
 import MentionTextarea from "./MentionTextarea";
 import SearchableSelect from "./SearchableSelect";
@@ -105,6 +106,13 @@ async function createPayee(
   return (await res.json()) as PayeeOption;
 }
 
+async function loadPayee(id: number): Promise<PayeeOption | null> {
+  const r = await fetch(`/api/payees/${id}`, { credentials: "include" });
+  if (!r.ok) return null;
+  const json = (await r.json()) as PayeeOption & { data?: PayeeOption };
+  return json.data ?? json;
+}
+
 function payeeSecondary(p: PayeeOption): string | null {
   if (!p.default_subcategory && p.kind === "vendor") return null;
   return (
@@ -248,6 +256,13 @@ export interface TransactionFormProps {
   setPayee: (v: string) => void;
   payeeId: number | null;
   setPayeeId: (v: number | null) => void;
+  /** Opt in to tax-ID capture for the picked payee by supplying `setPayeeTin`.
+   *  The form shows the saved TIN/address, or inputs when they are missing, and
+   *  reports typed values here; the host decides when and how to save them. */
+  payeeTin?: string;
+  setPayeeTin?: (v: string) => void;
+  payeeAddress?: string;
+  setPayeeAddress?: (v: string) => void;
   refNumber: string;
   setRefNumber: (v: string) => void;
   taxType: string;
@@ -360,6 +375,27 @@ export default function TransactionForm(props: TransactionFormProps) {
       setSelectedPayee(null);
     }
   });
+  // A payee picked from search already carries its tax ID; one restored from a
+  // saved row does not, so load it before deciding what to show.
+  createEffect(() => {
+    const sel = selectedPayee();
+    if (!props.setPayeeTin || !sel || sel.tin !== undefined) return;
+    const id = sel.id;
+    loadPayee(id)
+      .then((rec) => {
+        const cur = selectedPayee();
+        if (!rec || !cur || cur.id !== id) return;
+        setSelectedPayee({ ...cur, tin: rec.tin ?? null, address: rec.address ?? null });
+      })
+      .catch(() => {});
+  });
+  const taxPayee = () =>
+    props.setPayeeTin && props.category !== "sale" && catConfig().showPayee
+      ? selectedPayee()
+      : null;
+  const savedTin = () => !!taxPayee()?.tin?.trim();
+  const savedAddress = () => !!taxPayee()?.address?.trim();
+  const tinKnown = () => taxPayee()?.tin !== undefined;
   let dragCounter = 0;
   let formFileInput: HTMLInputElement | undefined;
 
@@ -756,6 +792,8 @@ export default function TransactionForm(props: TransactionFormProps) {
                     setSelectedPayee(p);
                     props.setPayee(p ? p.name : "");
                     props.setPayeeId(p ? p.id : null);
+                    props.setPayeeTin?.("");
+                    props.setPayeeAddress?.("");
                   }}
                 />
               </FormField>
@@ -774,6 +812,62 @@ export default function TransactionForm(props: TransactionFormProps) {
                 </Show>
               </FormField>
             </div>
+            <Show when={taxPayee() && tinKnown()}>
+              <div class="space-y-2" data-testid="form-payee-tax-id">
+                <Show when={savedTin()}>
+                  <p
+                    data-testid="form-payee-tin-readonly"
+                    class="text-xs text-[var(--ks-fg-subtle,#71717a)]"
+                  >
+                    TIN {taxPayee()!.tin}
+                    {savedAddress() ? ` · ${taxPayee()!.address}` : ""}
+                  </p>
+                </Show>
+                <div class="grid grid-cols-2 gap-4">
+                  <Show when={!savedTin()}>
+                    <FormField label="TIN (optional)">
+                      <input
+                        type="text"
+                        inputmode="numeric"
+                        data-testid="form-payee-tin-input"
+                        value={props.payeeTin ?? ""}
+                        onInput={(e) => props.setPayeeTin!(e.currentTarget.value)}
+                        class="w-full bg-[color-mix(in_srgb,var(--ks-overlay-surface,#18181b)_60%,transparent)] border border-[color-mix(in_srgb,var(--ks-border,rgba(39,39,42,0.5))_60%,transparent)] px-3 py-3 text-sm text-[var(--ks-fg,#ffffff)] ks-hud-clip-button focus:outline-none focus:border-[color-mix(in_srgb,var(--ks-focus-ring,#c9a961)_50%,transparent)]"
+                        placeholder="000-000-000-000"
+                      />
+                      <Show when={!isValidTin(props.payeeTin ?? "")}>
+                        <p
+                          data-testid="form-payee-tin-error"
+                          class="mt-1 text-[10px] text-[var(--ks-danger,#ef4444)]"
+                        >
+                          A TIN has 9 digits, or 12 with the branch code.
+                        </p>
+                      </Show>
+                    </FormField>
+                  </Show>
+                  <Show when={!savedAddress() && props.setPayeeAddress}>
+                    <FormField label="Address (optional)">
+                      <input
+                        type="text"
+                        data-testid="form-payee-address-input"
+                        value={props.payeeAddress ?? ""}
+                        onInput={(e) => props.setPayeeAddress!(e.currentTarget.value)}
+                        class="w-full bg-[color-mix(in_srgb,var(--ks-overlay-surface,#18181b)_60%,transparent)] border border-[color-mix(in_srgb,var(--ks-border,rgba(39,39,42,0.5))_60%,transparent)] px-3 py-3 text-sm text-[var(--ks-fg,#ffffff)] ks-hud-clip-button focus:outline-none focus:border-[color-mix(in_srgb,var(--ks-focus-ring,#c9a961)_50%,transparent)]"
+                        placeholder="Printed on the invoice"
+                      />
+                    </FormField>
+                  </Show>
+                </div>
+                <Show when={props.hasEwt && !savedTin() && !(props.payeeTin ?? "").trim()}>
+                  <p
+                    data-testid="form-payee-tin-ewt-warning"
+                    class="text-[11px] text-[var(--ks-warning,#f59e0b)]"
+                  >
+                    Withholding needs the payee's TIN for the 2307 certificate. You can save without it.
+                  </p>
+                </Show>
+              </div>
+            </Show>
           </Show>
           <Show when={!catConfig().showPayee}>
             <FormField label="Reference #">

package/src/components/composite/payee-tin.ts

@@ -0,0 +1,15 @@
+// Tax-ID helpers shared by the transaction form and its hosts, so both sides
+// apply the same rule before a TIN is saved.
+
+const TIN_PATTERN = /^\d{9}(\d{3})?$/;
+
+/** Trims the input and drops dashes and spaces: "123-456-789" -> "123456789". */
+export function normalizeTin(value: string): string {
+  return value.replace(/[\s-]/g, "");
+}
+
+/** A TIN is 9 digits, or 12 with the branch code. Blank is valid (optional). */
+export function isValidTin(value: string): boolean {
+  const digits = normalizeTin(value);
+  return digits === "" || TIN_PATTERN.test(digits);
+}

package/src/components/composite/picker-types.ts

@@ -14,6 +14,9 @@ export interface PayeeOption {
   kind: PayeeKind;
   default_subcategory?: string | null;
   notes?: string | null;
+  /** Tax ID on record. `undefined` means not loaded yet; `null`/"" means none. */
+  tin?: string | null;
+  address?: string | null;
   is_active?: boolean;
 }
 

package/src/index.ts

@@ -212,6 +212,7 @@ export {
 // Shared domain option shapes for the common pickers, decoupled from any
 // component (still imported across transactions / counter / payees).
 export type { ClientOption, PayeeOption, PayeeKind } from "./components/composite/picker-types";
+export { isValidTin, normalizeTin } from "./components/composite/payee-tin";
 
 export { default as VoucherPicker, calculateDiscount } from "./components/composite/VoucherPicker";
 export type { VoucherOption } from "./components/composite/VoucherPicker";