diff --git a/docs-manifest.json b/docs-manifest.json index e61f12412..d9a6dc18b 100644 --- a/docs-manifest.json +++ b/docs-manifest.json @@ -404,6 +404,9 @@ "examples": "docs-src/components/data-table.docs.examples.tsx", "sources": [ "packages/core/src/components/data-table/**", + "packages/core/src/components/internals/table-core/column-types.ts", + "packages/core/src/components/internals/table-core/cell-edit-error.ts", + "packages/core/src/components/internals/table-core/editing/date.tsx", "packages/core/src/hooks/use-collection-variables.ts", "packages/core/src/lib/collection-url-state.ts", "packages/core/src/contexts/collection-control-context.tsx", @@ -476,10 +479,10 @@ "withURLCollectionState" ], "hashes": { - "typeSurface": "413c66caec0a0bf8", - "outline": "7591217822d0183b", + "typeSurface": "8ada983257d51646", + "outline": "1bcf784b4b500873", "snapshot": "a97e067c66e46ef6", - "outputMd": "36bb587b7088fb1c", + "outputMd": "f0e28c3045e5bb2d", "examples": "8adc119ac0d7152c" } }, @@ -1840,7 +1843,7 @@ "packages/core/skills/app-shell-patterns/references/components/combobox.md": "c79cd0fe175187e3", "packages/core/skills/app-shell-patterns/references/components/command-palette.md": "7e5bc675a593791a", "packages/core/skills/app-shell-patterns/references/components/csv-importer.md": "10c04c78bb846c9a", - "packages/core/skills/app-shell-patterns/references/components/data-table.md": "36bb587b7088fb1c", + "packages/core/skills/app-shell-patterns/references/components/data-table.md": "f0e28c3045e5bb2d", "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "376e7d4ad14c2934", "packages/core/skills/app-shell-patterns/references/components/default-header.md": "375e55f4b12fa2be", "packages/core/skills/app-shell-patterns/references/components/default-sidebar.md": "9b1672c71b6db3ff", diff --git a/docs-src/components/data-table.docs.outline.md b/docs-src/components/data-table.docs.outline.md index 2ccdfb808..d1142e280 100644 --- a/docs-src/components/data-table.docs.outline.md +++ b/docs-src/components/data-table.docs.outline.md @@ -5,6 +5,9 @@ title: DataTable description: Compound data table component with sortable columns, filter chips, cursor-based pagination, row actions, and multi-row selection sources: - packages/core/src/components/data-table/** + - packages/core/src/components/internals/table-core/column-types.ts + - packages/core/src/components/internals/table-core/cell-edit-error.ts + - packages/core/src/components/internals/table-core/editing/date.tsx - packages/core/src/hooks/use-collection-variables.ts - packages/core/src/lib/collection-url-state.ts - packages/core/src/contexts/collection-control-context.tsx @@ -41,8 +44,8 @@ import { type NumberCellEditOptions, type BadgeCellEditOptions, type DateCellEditOptions, - type CellEditState, type DateTimeDraft, + type CellEditState, type FooterRenderContext, } from "@tailor-platform/app-shell"; ``` diff --git a/docs/components/data-table.md b/docs/components/data-table.md index 54b7d0df7..e3d3b761d 100644 --- a/docs/components/data-table.md +++ b/docs/components/data-table.md @@ -35,8 +35,8 @@ import { type NumberCellEditOptions, type BadgeCellEditOptions, type DateCellEditOptions, - type CellEditState, type DateTimeDraft, + type CellEditState, type FooterRenderContext, } from "@tailor-platform/app-shell"; ``` diff --git a/examples/vite-app/src/App.tsx b/examples/vite-app/src/App.tsx index 035b50f91..4d33163f4 100644 --- a/examples/vite-app/src/App.tsx +++ b/examples/vite-app/src/App.tsx @@ -85,6 +85,7 @@ const AppInner = () => { + diff --git a/examples/vite-app/src/pages/showcase/line-items/page.tsx b/examples/vite-app/src/pages/showcase/line-items/page.tsx new file mode 100644 index 000000000..ca2d043c6 --- /dev/null +++ b/examples/vite-app/src/pages/showcase/line-items/page.tsx @@ -0,0 +1,204 @@ +import { + Button, + CellEditError, + Layout, + LineItems, + Tabs, + useLineItems, + type AppShellPageProps, + type LineItemsColumn, +} from "@tailor-platform/app-shell"; +import { ListIcon, XIcon } from "lucide-react"; +import { useCallback, useState } from "react"; + +type OrderLine = { + id?: string; + item: string | null; + quantity: number | null; + unitPrice: number | null; + status: string | null; + dueDate: string | null; +}; + +const validateQuantity = (_row: Readonly, value: number | null) => { + if (value === null || value <= 0) { + throw new CellEditError("Quantity must be greater than zero."); + } +}; + +const LineItemsPage = () => { + const [editable, setEditable] = useState(true); + const canEdit = useCallback(() => editable, [editable]); + const lineItems = useLineItems({ + orderer: editable, + defaultLines: [ + { + id: "line-1", + item: "Notebook", + quantity: 2, + unitPrice: 5, + status: "open", + dueDate: "2026-11-16", + }, + { + id: "line-2", + item: "Pen", + quantity: 3, + unitPrice: 1.5, + status: "closed", + dueDate: "2026-11-17", + }, + { + id: "line-3", + item: "Pencil", + quantity: 4, + unitPrice: 1, + status: "open", + dueDate: "2026-11-18", + }, + { + id: "line-4", + item: "Eraser", + quantity: 2, + unitPrice: 0.75, + status: "open", + dueDate: "2026-11-19", + }, + { + id: "line-5", + item: "Ruler", + quantity: 1, + unitPrice: 2, + status: "closed", + dueDate: "2026-11-20", + }, + ], + columns: [ + { accessorKey: "item", label: "Item", edit: { editorType: "text", canEdit } }, + { + accessorKey: "quantity", + label: "Quantity", + type: "number", + typeOptions: { maxDecimals: 2 }, + edit: { editorType: "number", canEdit, onValueCommitted: validateQuantity }, + }, + { + accessorKey: "unitPrice", + label: "Unit price", + type: "money", + edit: { editorType: "number", canEdit }, + }, + { + id: "total", + label: "Total", + type: "money", + accessor: (line) => (line.quantity ?? 0) * (line.unitPrice ?? 0), + }, + { + accessorKey: "status", + label: "Status", + edit: { + editorType: "combobox", + canEdit, + editorOptions: { + options: [ + { value: "open", label: "Open" }, + { value: "closed", label: "Closed" }, + ], + }, + }, + }, + { + accessorKey: "dueDate", + label: "Due date", + type: "date", + edit: { editorType: "date", canEdit }, + }, + ...(editable + ? [ + { + id: "actions", + label: "Actions", + width: 64, + align: "center", + headerProps: () => ({ className: "first:pl-2! last:pr-2!" }), + cellProps: () => ({ className: "py-1! first:pl-2! last:pr-2!" }), + render: (line) => ( + + ), + } satisfies LineItemsColumn, + ] + : []), + ], + }); + + return ( + + + + setEditable(value === "editable")} + > + + Editable + Readonly + + + {editable && ( +

+ Clear Quantity or enter zero or a negative number, then press Enter to see a validation + error. +

+ )} + + + + {editable && ( +
+ + +
+ )} +
+
+ ); +}; + +LineItemsPage.appShellPageProps = { + meta: { + title: "Line Items", + icon: , + }, +} satisfies AppShellPageProps; + +export default LineItemsPage; diff --git a/examples/vite-app/src/routes.generated.ts b/examples/vite-app/src/routes.generated.ts index dfc93c810..60455dd82 100644 --- a/examples/vite-app/src/routes.generated.ts +++ b/examples/vite-app/src/routes.generated.ts @@ -44,6 +44,7 @@ export type GeneratedRouteParams = { "/showcase/grid": {}; "/showcase/item-list": {}; "/showcase/layouts": {}; + "/showcase/line-items": {}; "/showcase/metric-card": {}; "/showcase/primitives": {}; "/showcase/spinner": {}; diff --git a/packages/core/src/components/data-table/cell-renderer-adapter.test.tsx b/packages/core/src/components/data-table/cell-renderer-adapter.test.tsx new file mode 100644 index 000000000..0703cbed7 --- /dev/null +++ b/packages/core/src/components/data-table/cell-renderer-adapter.test.tsx @@ -0,0 +1,108 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import * as tableCore from "@/components/internals/table-core"; +import { cleanup, render, renderHook, screen } from "@testing-library/react"; +import { createAppShellWrapper } from "../../../tests/test-utils"; +import { useEditorProps } from "./editing/cell/shared"; +import { createCellEditNavigation } from "./editing/use-navigation"; +import { MemoryRouter } from "react-router"; +import { + createTypedCellRenderer, + createTypedValueRenderer, + getCellValue, + renderTypedValue, +} from "./cell-renderers"; +import type { Column } from "./types"; + +afterEach(() => { + cleanup(); + vi.restoreAllMocks(); +}); + +describe("DataTable renderer adapter compatibility", () => { + const row = { id: "A", status: "open", name: "Raw name" }; + + it("retains accessor/id lookup precedence without treating render output as raw data", () => { + expect(getCellValue(row, { id: "name" })).toBe("Raw name"); + expect(getCellValue(row, { id: "name", accessor: (value) => value.status })).toBe("open"); + expect(getCellValue(row, { render: () => "Display only" })).toBeUndefined(); + }); + + it.each([false, true])( + "resolves an editable value once with a prepared renderer (custom display: %s)", + (custom) => { + const accessor = vi.fn((value: typeof row) => value.name); + const col = { + id: "name", + type: "text", + accessor, + render: custom ? () => "Custom" : undefined, + edit: { onValueCommitted: () => {} }, + } satisfies Column; + const valueRenderer = vi.fn(createTypedValueRenderer(col, { timeZone: "UTC" })); + const { result } = renderHook( + () => + useEditorProps({ + row, + col, + valueRenderer, + rowKey: row.id, + colKey: "name", + label: "Name", + align: "left", + navigation: createCellEditNavigation(), + cellProps: {}, + }), + { wrapper: createAppShellWrapper() }, + ); + expect(accessor).toHaveBeenCalledExactlyOnceWith(row); + expect(result.current.current).toBe("Raw name"); + expect(result.current.display).toBe(custom ? "Custom" : "Raw name"); + if (custom) expect(valueRenderer).not.toHaveBeenCalled(); + else expect(valueRenderer).toHaveBeenCalledExactlyOnceWith("Raw name", row); + }, + ); + + it("keeps edit-choice labels in legacy text rendering", () => { + const col: Column = { + id: "status", + type: "text", + edit: { + options: [{ value: "open", label: "Open label" }], + onValueCommitted: () => {}, + }, + }; + expect(createTypedCellRenderer(col, "UTC")(row)).toBe("Open label"); + }); + + it.each(["number", "money"] as const)( + "prepares a %s renderer once rather than recreating it for each row", + (type) => { + const createRenderer = vi.spyOn(tableCore, "createValueRenderer"); + const col: Column<{ value: number }> = { id: "value", type }; + const renderer = createTypedCellRenderer(col, "UTC"); + expect(createRenderer).toHaveBeenCalledExactlyOnceWith(col, { timeZone: "UTC" }); + renderer({ value: 1 }); + renderer({ value: 2 }); + renderer({ value: 3 }); + expect(createRenderer).toHaveBeenCalledOnce(); + }, + ); + + it("resolves legacy link labels and plaintext editor display outside table-core", () => { + const col: Column = { + id: "status", + type: "link", + typeOptions: { href: (value) => `/rows/${value.id}` }, + edit: { + options: [{ value: "open", label: "Open label" }], + onValueCommitted: () => {}, + }, + }; + const readonly = createTypedCellRenderer(col, "UTC"); + const editable = createTypedCellRenderer(col, "UTC", { linkAsText: true }); + expect(editable(row)).toBe("Open label"); + expect(renderTypedValue(row, col, row.status, { linkAsText: true })).toBe("Open label"); + render({readonly(row)}); + expect(screen.getByRole("link", { name: "Open label" }).getAttribute("href")).toBe("/rows/A"); + }); +}); diff --git a/packages/core/src/components/data-table/cell-renderers.tsx b/packages/core/src/components/data-table/cell-renderers.tsx index c6b91dcf5..4e0fe3268 100644 --- a/packages/core/src/components/data-table/cell-renderers.tsx +++ b/packages/core/src/components/data-table/cell-renderers.tsx @@ -1,38 +1,11 @@ import type { ReactNode } from "react"; -import { parseDate } from "@internationalized/date"; -import { Link } from "react-router"; -import { BadgeList, toValueArray } from "@/components/badge-list"; -import type { SelectOption } from "@/types/collection"; +import { + createValueRenderer, + type ValueRenderer, + type ValueRendererContext, +} from "@/components/internals/table-core"; import { optionLabel, resolveBadgeOptions } from "./cell-values"; -import { normalizeTemporalFilterValue } from "@/lib/temporal-filter-values"; -import type { - BadgeCellOptions, - Column, - DateCellOptions, - LinkCellOptions, - MoneyCellOptions, - NumberCellOptions, -} from "./types"; - -function resolveDateFormatOptions(format: string): Intl.DateTimeFormatOptions { - if (format === "long") return { month: "long", day: "numeric", year: "numeric" }; - if (format === "datetime") { - return { - month: "short", - day: "numeric", - year: "numeric", - hour: "numeric", - minute: "2-digit", - }; - } - return { month: "short", day: "numeric", year: "numeric" }; -} - -const PLACEHOLDER = ( - -); +import type { Column } from "./types"; /** * Read the raw cell value for a column. Used by the built-in `type` @@ -51,145 +24,36 @@ export function getCellValue>( return undefined; } -function isEmpty(value: unknown): boolean { - return value == null || value === ""; -} - -function renderText(value: unknown): ReactNode { - switch (true) { - case isEmpty(value): - return PLACEHOLDER; - case typeof value === "boolean": - return value ? "✓" : "✗"; - case value instanceof Date: - return value.toLocaleDateString(); - case typeof value === "object": - return JSON.stringify(value); +/** Bind DataTable's choice-label and editable-link policies before rendering rows. */ +export function createTypedValueRenderer>( + col: Column, + context: ValueRendererContext, + options?: { linkAsText?: boolean }, +): ValueRenderer { + switch (col.type) { + case "badge": { + const choices = col.edit + ? resolveBadgeOptions(col.edit.options, col.typeOptions, col.filter) + : undefined; + return createValueRenderer(col, { + ...context, + resolveBadgeLabel: choices ? (item) => String(optionLabel(choices, item)) : undefined, + }); + } + case "link": + case "text": { + const descriptor = + col.type === "link" && options?.linkAsText ? ({ type: "text" } as const) : col; + const renderValue = createValueRenderer(descriptor, context); + return (value, row) => renderValue(optionLabel(col.edit?.options, value), row); + } default: - return String(value); - } -} - -function renderNumber(value: unknown, options: NumberCellOptions | undefined): ReactNode { - if (isEmpty(value)) return PLACEHOLDER; - const num = Number(value); - if (Number.isNaN(num)) return PLACEHOLDER; - const min = options?.minDecimals ?? 0; - const formatted = new Intl.NumberFormat(options?.locale, { - minimumFractionDigits: min, - maximumFractionDigits: options?.maxDecimals ?? min, - }).format(num); - return {formatted}; -} - -function renderMoney>( - value: unknown, - row: TRow, - options: MoneyCellOptions | undefined, -): ReactNode { - if (isEmpty(value)) return PLACEHOLDER; - const num = Number(value); - if (Number.isNaN(num)) return PLACEHOLDER; - const currency = - (typeof options?.currency === "function" ? options.currency(row) : options?.currency) || "USD"; - - // `maxDecimals` raises the cap above the currency default while keeping the - // minimum at the currency default (e.g. 2 for USD). Lets a JPY column stay - // at 0 decimals while a USD price-detail column shows up to 4. - const formatOptions: Intl.NumberFormatOptions = { - style: "currency", - currency, - }; - if (options?.maxDecimals != null) { - formatOptions.maximumFractionDigits = options.maxDecimals; - } - let formatted: string; - try { - formatted = new Intl.NumberFormat(options?.locale, formatOptions).format(num); - } catch { - // Fall back to USD if the currency code is invalid — Intl throws on bad ISO codes. - formatted = new Intl.NumberFormat(options?.locale, { - style: "currency", - currency: "USD", - }).format(num); + return createValueRenderer(col, context); } - return {formatted}; -} - -function createDateRenderer( - options: DateCellOptions | undefined, - timeZone: string, -): (value: unknown) => ReactNode { - const formatOptions = resolveDateFormatOptions(options?.dateFormat ?? "short"); - let dateOnlyFormatter: Intl.DateTimeFormat | undefined; - let datetimeFormatter: Intl.DateTimeFormat | undefined; - - return (value) => { - if (isEmpty(value)) return PLACEHOLDER; - const dateOnly = typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value.trim()); - let date: Date; - if (dateOnly) { - // Calendar dates have no instant, even when a timezone skips an entire day. - try { - date = parseDate(value.trim()).toDate("UTC"); - } catch { - return PLACEHOLDER; - } - } else { - const normalized = normalizeTemporalFilterValue("datetime", value, timeZone); - if (!normalized) return PLACEHOLDER; - date = new Date(normalized); - } - const formatter = dateOnly - ? (dateOnlyFormatter ??= new Intl.DateTimeFormat(options?.locale, { - ...formatOptions, - timeZone: "UTC", - })) - : (datetimeFormatter ??= new Intl.DateTimeFormat(options?.locale, { - ...formatOptions, - timeZone, - })); - return formatter.format(date); - }; -} - -function renderBadge( - value: unknown, - options: BadgeCellOptions | undefined, - choices: readonly SelectOption[] | undefined, -): ReactNode { - const items = toValueArray(value); - const nonEmpty = items.filter((v) => v != null && v !== ""); - if (nonEmpty.length === 0) return PLACEHOLDER; - return ( - String(optionLabel(choices, v)) : undefined} - /> - ); -} - -function renderLink>( - value: unknown, - row: TRow, - options: LinkCellOptions, -): ReactNode { - if (isEmpty(value)) return PLACEHOLDER; - const label = String(value); - const href = options.href(row); - if (!href) return label; - return ( - - {label} - - ); } /** - * Create a column renderer that reuses date formatters across rows. + * Prepare a column's built-in renderer once and reuse it across rows. * Callers should prefer `col.render` when it is defined. * * @internal @@ -197,12 +61,10 @@ function renderLink>( export function createTypedCellRenderer>( col: Column, timeZone: string, + options?: { linkAsText?: boolean }, ): (row: TRow) => ReactNode { - if (col.type === "date") { - const renderDate = createDateRenderer(col.typeOptions, timeZone); - return (row) => renderDate(getCellValue(row, col)); - } - return (row) => renderTypedValue(row, col, getCellValue(row, col)); + const renderValue = createTypedValueRenderer(col, { timeZone }, options); + return (row) => renderValue(getCellValue(row, col), row); } /** @@ -218,30 +80,9 @@ export function renderTypedValue>( value: unknown, options?: { linkAsText?: boolean; timeZone?: string }, ): ReactNode { - switch (col.type) { - case "number": - return renderNumber(value, col.typeOptions); - case "money": - return renderMoney(value, row, col.typeOptions); - case "date": - return createDateRenderer( - col.typeOptions, - options?.timeZone ?? Intl.DateTimeFormat().resolvedOptions().timeZone, - )(value); - case "badge": - return renderBadge( - value, - col.typeOptions, - col.edit ? resolveBadgeOptions(col.edit.options, col.typeOptions, col.filter) : undefined, - ); - case "link": { - // A column with dropdown choices stores an option's value and shows its label. - const label = optionLabel(col.edit?.options, value); - return options?.linkAsText ? renderText(label) : renderLink(label, row, col.typeOptions); - } - case "text": - return renderText(optionLabel(col.edit?.options, value)); - default: - return renderText(value); - } + return createTypedValueRenderer( + col, + { timeZone: options?.timeZone ?? Intl.DateTimeFormat().resolvedOptions().timeZone }, + options, + )(value, row); } diff --git a/packages/core/src/components/data-table/cell-values.test.ts b/packages/core/src/components/data-table/cell-values.test.ts index e6bf9eaa0..be0983555 100644 --- a/packages/core/src/components/data-table/cell-values.test.ts +++ b/packages/core/src/components/data-table/cell-values.test.ts @@ -1,102 +1,5 @@ import { describe, expect, it } from "vitest"; -import { - isIsoDate, - optionLabel, - resolveBadgeOptions, - sameDate, - toCalendarDate, - toIsoDateTime, - toTimeText, - normalizeNumberText, - parseNumberText, - sameNumber, - toNumberEditText, - toNumberValue, - toTextValue, -} from "./cell-values"; - -describe("typed text that isn't a number", () => { - it("is reported as not a number, not silently accepted", () => { - for (const text of ["e", "1e5", "+5", "0x1f", "12a", "1,5"]) { - expect(parseNumberText(normalizeNumberText(text))).toBeUndefined(); - } - }); -}); - -describe("normalizeNumberText", () => { - it("drops strict thousands grouping", () => { - expect(normalizeNumberText("1,234.5")).toBe("1234.5"); - expect(normalizeNumberText("-1,234,567")).toBe("-1234567"); - }); - - it("leaves a decimal comma alone so it fails instead of becoming 15", () => { - expect(normalizeNumberText("1,5")).toBe("1,5"); - expect(parseNumberText(normalizeNumberText("1,5"))).toBeUndefined(); - }); - - it("converts full-width digits and signs", () => { - expect(normalizeNumberText("12.5")).toBe("12.5"); - expect(normalizeNumberText("-3")).toBe("-3"); - expect(normalizeNumberText("−3")).toBe("-3"); - }); - - it("strips whitespace and currency symbols", () => { - expect(normalizeNumberText(" $1,234.50 ")).toBe("1234.50"); - expect(normalizeNumberText("¥ 1 200")).toBe("1200"); - }); -}); - -describe("parseNumberText", () => { - it("treats an empty draft as null", () => { - expect(parseNumberText("")).toBeNull(); - expect(parseNumberText(" ")).toBeNull(); - }); - - it("parses partial but complete-enough numbers without business constraints", () => { - expect(parseNumberText("-3.5678")).toBe(-3.5678); - expect(parseNumberText("500.0001")).toBe(500.0001); - expect(parseNumberText("5.")).toBe(5); - expect(parseNumberText(".5")).toBe(0.5); - expect(parseNumberText("-0")).toBe(0); - expect(Object.is(parseNumberText("-0"), -0)).toBe(false); - }); - - it("rejects half-typed and non-numeric drafts", () => { - for (const text of ["-", ".", "-.", "abc", "1,5", String(Number.MAX_SAFE_INTEGER * 2)]) { - expect(parseNumberText(text)).toBeUndefined(); - } - }); -}); - -describe("value helpers", () => { - it("compares parsed numbers without silently rounding distinct values", () => { - expect(sameNumber(10, 10)).toBe(true); - expect(sameNumber(0.1 + 0.2, 0.3)).toBe(false); - expect(sameNumber(1234567890123456, 1234567890123457)).toBe(false); - expect(sameNumber(null, null)).toBe(true); - expect(sameNumber(0, null)).toBe(false); - expect(sameNumber(10, 10.01)).toBe(false); - }); - - it("reads raw values the way the renderers do", () => { - expect(toNumberValue("10.00")).toBe(10); - expect(toNumberValue("")).toBeNull(); - expect(toNumberValue("abc")).toBeNull(); - expect(toTextValue("")).toBeNull(); - expect(toTextValue(42)).toBe("42"); - }); - - it("formats numbers without grouping, exponents, or precision loss", () => { - expect(toNumberEditText(1234567.5)).toBe("1234567.5"); - expect(toNumberEditText(0.1 + 0.2)).toBe("0.30000000000000004"); - expect(toNumberEditText(1234567890123456)).toBe("1234567890123456"); - expect(toNumberEditText(1e21)).toBe("1000000000000000000000"); - expect(toNumberEditText(null)).toBe(""); - for (const value of [Number.MAX_SAFE_INTEGER, Number.MIN_VALUE, 1e-30, 1.2345678901234567]) { - expect(parseNumberText(toNumberEditText(value))).toBe(value); - } - }); -}); +import { optionLabel, resolveBadgeOptions } from "./cell-values"; describe("choices", () => { const choices = [ @@ -130,70 +33,3 @@ describe("choices", () => { ); }); }); - -describe("dates", () => { - it("recognises date-only strings", () => { - expect(isIsoDate("2026-10-02")).toBe(true); - expect(isIsoDate("2026-10-02T09:00:00Z")).toBe(false); - expect(isIsoDate(20261002)).toBe(false); - }); - - it("converts cell values to the calendar day and local time they show", () => { - expect(toCalendarDate("2026-10-02")?.toString()).toBe("2026-10-02"); - expect(toCalendarDate(new Date(2026, 9, 2, 23, 30))?.toString()).toBe("2026-10-02"); - expect(toCalendarDate(null)).toBeNull(); - expect(toTimeText(new Date(2026, 9, 2, 9, 5))).toBe("09:05"); - expect(toTimeText("2026-10-02")).toBe(""); - expect(toTimeText(undefined)).toBe(""); - }); - - it("builds an ISO timestamp from a day and a local time", () => { - const day = toCalendarDate("2026-10-20")!; - expect(toIsoDateTime(day, "14:30")).toBe(new Date(2026, 9, 20, 14, 30).toISOString()); - expect(toIsoDateTime(day, "")).toBeUndefined(); - }); - - it("does not fill or coerce an incomplete or invalid time", () => { - const day = toCalendarDate("2026-10-20")!; - for (const time of ["", "14:", "9:05", "24:00", "12:60", "-1:00", "abc"]) { - expect(toIsoDateTime(day, time)).toBeUndefined(); - } - expect(toIsoDateTime(day, "00:00", "Asia/Tokyo")).toBe("2026-10-19T15:00:00.000Z"); - }); - - it("initializes and commits date-times in the configured timezone", () => { - const zone = "America/New_York"; - const value = "2026-10-09T00:00:00Z"; - expect(toCalendarDate(value, zone)?.toString()).toBe("2026-10-08"); - expect(toTimeText(value, zone)).toBe("20:00"); - expect(toCalendarDate("2026-10-09", zone)?.toString()).toBe("2026-10-09"); - expect(toIsoDateTime(toCalendarDate("2026-10-08")!, "20:00", zone)).toBe( - "2026-10-09T00:00:00.000Z", - ); - expect(sameDate(value, "2026-10-08", false, zone)).toBe(true); - expect(sameDate("2026-10-08T20:00", value, true, zone)).toBe(true); - expect(toIsoDateTime(toCalendarDate("2026-12-08")!, "20:00", zone)).toBe( - "2026-12-09T01:00:00.000Z", - ); - }); - - it("distinguishes incomplete date-only data from explicit midnight in datetime comparisons", () => { - const day = "2026-10-02"; - const midnight = "2026-10-01T15:00:00.000Z"; - expect(sameDate(day, midnight, true, "Asia/Tokyo")).toBe(false); - expect(sameDate(midnight, day, true, "Asia/Tokyo")).toBe(false); - expect(sameDate(day, null, true, "Asia/Tokyo")).toBe(false); - expect(sameDate(day, day, true, "Asia/Tokyo")).toBe(true); - expect(sameDate(day, midnight, false, "Asia/Tokyo")).toBe(true); - }); - - it("compares by day for dates and by minute for date-times", () => { - expect(sameDate("2026-10-02", new Date(2026, 9, 2, 18), false)).toBe(true); - expect(sameDate("2026-10-02", "2026-10-03", false)).toBe(false); - const at = new Date(2026, 9, 2, 14, 30, 5); - expect(sameDate(at.toISOString(), new Date(2026, 9, 2, 14, 30, 50), true)).toBe(true); - expect(sameDate(at.toISOString(), new Date(2026, 9, 2, 14, 31), true)).toBe(false); - expect(sameDate(null, undefined, false)).toBe(true); - expect(sameDate(null, "2026-10-02", false)).toBe(false); - }); -}); diff --git a/packages/core/src/components/data-table/cell-values.ts b/packages/core/src/components/data-table/cell-values.ts index 086ef8975..53ee0a081 100644 --- a/packages/core/src/components/data-table/cell-values.ts +++ b/packages/core/src/components/data-table/cell-values.ts @@ -1,90 +1,13 @@ -/** - * Pure helpers behind DataTable's inline cell editing: how typed or pasted text - * becomes a value and whether a draft is a real change or a cosmetic one - * (`10` vs `10.00`). Business validation belongs to the consumer. - * - * @internal - */ - -import { - CalendarDate, - CalendarDateTime, - getLocalTimeZone, - parseDate, - toZoned, -} from "@internationalized/date"; -import { localDateTimeParts, normalizeTemporalFilterValue } from "@/lib/temporal-filter-values"; import type { SelectOption } from "@/types/collection"; import type { BadgeCellOptions, DataTableFilterConfig } from "./types"; -// Thousands grouping with commas, e.g. "1,234,567.89". -const GROUPED_NUMBER = /^-?\d{1,3}(?:,\d{3})+(?:\.\d*)?$/; - -/** - * Cleans number text before it's checked: full-width digits and signs become - * ASCII, whitespace and currency symbols are dropped, and commas are removed - * only when they form strict thousands groups — so "1,234.5" becomes "1234.5", - * while "1,5" is left alone to fail as "not a number" instead of silently - * turning into 15. - */ -export function normalizeNumberText(text: string): string { - const compact = text - .normalize("NFKC") - .replace(/[\s\p{Sc}]/gu, "") - .replace(/^−/, "-"); - return GROUPED_NUMBER.test(compact) ? compact.replace(/,/g, "") : compact; -} - -/** `""` → `null`, `"5."` → `5`; `"-"`, `"."` and anything non-numeric → `undefined`. */ -export function parseNumberText(text: string): number | null | undefined { - const trimmed = text.trim(); - if (trimmed === "") return null; - if (!/^-?(?:\d+\.?\d*|\.\d+)$/.test(trimmed)) return undefined; - const value = Number(trimmed); - if (!Number.isFinite(value) || Math.abs(value) > Number.MAX_SAFE_INTEGER) return undefined; - // `+ 0` folds -0 into 0 so "-0" doesn't read as a change from 0. - return value + 0; -} - -/** Reads a raw cell value as a number the way the `number` renderer does. */ -export function toNumberValue(raw: unknown): number | null { - if (raw == null || raw === "") return null; - const value = typeof raw === "number" ? raw : Number(raw); - return Number.isFinite(value) ? value : null; -} - -/** Reads a raw cell value as text; `null`, `undefined` and `""` are all empty. */ -export function toTextValue(raw: unknown): string | null { - if (raw == null || raw === "") return null; - return String(raw); -} - -/** Compare parsed values exactly; rounding belongs to the consumer. */ -export function sameNumber(a: number | null, b: number | null): boolean { - return a === b; -} - -/** Plain edit text preserves the value without grouping or exponent notation. */ -export function toNumberEditText(value: number | null): string { - if (value === null) return ""; - return value.toLocaleString("en-US", { - useGrouping: false, - maximumSignificantDigits: 21, - }); -} - -// ── Choices (dropdown and badge editors) ───────────────────────────────────── - /** The label a choice shows, or the raw value when it isn't one of the choices. */ export function optionLabel(options: readonly SelectOption[] | undefined, value: unknown): unknown { if (!options || value == null || value === "") return value; return options.find((option) => option.value === String(value))?.label ?? value; } -/** - * The choices a badge column offers: `edit.options`, else the entries of - * `typeOptions.badgeLabelMap`, else the column's enum filter options. - */ +/** Choices retain DataTable's edit options, badge labels, then enum-filter fallback. */ export function resolveBadgeOptions( options: readonly SelectOption[] | undefined, typeOptions: BadgeCellOptions | undefined, @@ -96,71 +19,3 @@ export function resolveBadgeOptions( if (filter?.type === "enum") return filter.options; return []; } - -// ── Dates ──────────────────────────────────────────────────────────────────── - -const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/; - -/** Whether `value` is a date-only ISO string (`"YYYY-MM-DD"`). */ -export function isIsoDate(value: unknown): value is string { - return typeof value === "string" && ISO_DATE.test(value); -} - -/** A raw date cell value as the calendar day it shows. */ -export function toCalendarDate(raw: unknown, timeZone = getLocalTimeZone()): CalendarDate | null { - const date = normalizeTemporalFilterValue("date", raw, timeZone); - if (!date) return null; - try { - return parseDate(date); - } catch { - return null; - } -} - -/** The zoned time of a raw date cell value as `"HH:mm"`; `""` when there is none. */ -export function toTimeText(raw: unknown, timeZone = getLocalTimeZone()): string { - if (isIsoDate(raw)) return ""; - const datetime = normalizeTemporalFilterValue("datetime", raw, timeZone); - return datetime ? localDateTimeParts(datetime, timeZone).time : ""; -} - -/** A calendar day plus a zoned `"HH:mm"` as an ISO 8601 timestamp. */ -export function toIsoDateTime( - day: CalendarDate, - time: string, - timeZone = getLocalTimeZone(), -): string | undefined { - if (!/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(time)) return undefined; - const [hours, minutes] = time.split(":").map(Number); - return toZoned(new CalendarDateTime(day.year, day.month, day.day, hours, minutes), timeZone) - .toDate() - .toISOString(); -} - -/** - * Whether two raw date values mean the same thing: the same day for a date - * column, the same minute for a date-time one — so `"2026-10-02"` equals a - * `Date` for that day, and string formatting differences don't count. - */ -export function sameDate( - a: unknown, - b: unknown, - withTime: boolean, - timeZone = getLocalTimeZone(), -): boolean { - if (!withTime) { - const left = toCalendarDate(a, timeZone); - const right = toCalendarDate(b, timeZone); - return left && right ? left.compare(right) === 0 : left === right; - } - // Date-only data is incomplete in a datetime editor, not implicit midnight. - if (isIsoDate(a) || isIsoDate(b)) return a === b; - const asInstant = (raw: unknown) => { - const normalized = normalizeTemporalFilterValue("datetime", raw, timeZone); - return normalized ? new Date(normalized) : null; - }; - const left = asInstant(a); - const right = asInstant(b); - if (!left || !right) return left === right; - return Math.floor(left.getTime() / 60_000) === Math.floor(right.getTime() / 60_000); -} diff --git a/packages/core/src/components/data-table/column-layout.ts b/packages/core/src/components/data-table/column-layout.ts index c1f1b8d6e..34dc41fea 100644 --- a/packages/core/src/components/data-table/column-layout.ts +++ b/packages/core/src/components/data-table/column-layout.ts @@ -1,14 +1,11 @@ import type { CSSProperties } from "react"; import { cn } from "@/lib/utils"; +import { getDisplayCellAdapter } from "@/components/internals/table-core"; import type { Column } from "./types"; -// Resolve the effective horizontal alignment for a column. Numeric `type` -// values default to `"right"` so digits line up along their decimal place; -// everything else defaults to `"left"`. Explicit `col.align` always wins. +// Explicit alignment overrides the display adapter's default, shared by header, body, and footer. function resolveAlign>(col: Column): "left" | "right" { - if (col.align) return col.align; - if (col.type === "number" || col.type === "money") return "right"; - return "left"; + return col.align ?? getDisplayCellAdapter(col.type).defaultAlign; } // Fallback widths of the built-in selection / row-actions columns, used as the diff --git a/packages/core/src/components/data-table/date-time-draft.test-d.ts b/packages/core/src/components/data-table/date-time-draft.test-d.ts new file mode 100644 index 000000000..c3f268cd3 --- /dev/null +++ b/packages/core/src/components/data-table/date-time-draft.test-d.ts @@ -0,0 +1,21 @@ +import { expectTypeOf, test } from "vitest"; +import type { DateCellEditOptions, DateTimeDraft } from "@/index"; +import type { DateTimeDraft as DataTableDateTimeDraft } from "./index"; +import type { DateTimeDraft as InternalDateTimeDraft } from "@/components/internals/table-core/editing/date"; + +type Row = { id: string; date: string | null }; + +test("DateTimeDraft remains available through the public entrypoints", () => { + expectTypeOf().toEqualTypeOf<{ + day: string | null; + time: string | null; + }>(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); +}); + +test("date change callbacks use the same public DateTimeDraft", () => { + type Draft = Parameters["onValueChange"]>>[1]; + expectTypeOf().toEqualTypeOf(); + expectTypeOf>().toEqualTypeOf(); +}); diff --git a/packages/core/src/components/data-table/editing/cell/choice.tsx b/packages/core/src/components/data-table/editing/cell/choice.tsx index 99655f1f0..a0739334b 100644 --- a/packages/core/src/components/data-table/editing/cell/choice.tsx +++ b/packages/core/src/components/data-table/editing/cell/choice.tsx @@ -1,29 +1,9 @@ -import { - useMemo, - useRef, - useState, - type ComponentProps, - type FocusEvent, - type MouseEvent, - type TouchEvent, -} from "react"; -import { Combobox as BaseCombobox } from "@base-ui/react/combobox"; -import { ChevronDown } from "lucide-react"; -import { cn } from "@/lib/utils"; -import { isComposing } from "@/lib/is-composing"; import { BadgeList } from "@/components/badge-list"; -import { ComboboxParts } from "@/components/combobox"; -import { toTextValue } from "../../cell-values"; -import { useDataTableT } from "../../i18n"; -import { useCellEditSession } from "../use-session"; +import { EditableCell } from "@/components/internals/table-core/editing/cell"; +import { choiceEditor } from "@/components/internals/table-core/editing/choice"; import { - CELL_ERROR_CLASS_NAME, - ICON_INPUT_CLASS_NAME, - INPUT_CLASS_NAME, - EditableCellFrame, columnChoices, - useCellValue, - useNavigationRef, + useEditorProps, type EditableColumn, type DataTableEditableCellProps, } from "./shared"; @@ -33,353 +13,24 @@ type ChoiceColumn> = Extract< { type: "text" | "link" | "badge" } >; -/** One dropdown choice; `value: null` is "None". */ -interface Choice { - value: string | null; - label: string; -} - -type ChoiceDraft = Choice & { notified?: boolean }; - -// Case- and width-insensitive searching: full-width letters and half-width -// katakana match their usual forms. -const searchable = (text: string) => text.normalize("NFKC").toLocaleLowerCase().trim(); - -const isChoiceEqual = (a: Choice, b: Choice) => a.value === b.value; - -const choiceLabel = (choice: Choice) => choice.label; - -export function ChoiceEditCell>({ - row, - col, - rowKey, - colKey, - label, - align, - navigation, - cellProps, - tooltipLabel, -}: DataTableEditableCellProps>) { - const t = useDataTableT(); - const session = useCellEditSession(col.edit?.error !== false); - const { state } = session; - const { current, display, change, commit, callbackError, containsErrorTarget } = useCellValue( - row, - col, - state.status === "failed" ? state : undefined, - ); - const register = useNavigationRef(navigation, rowKey, colKey); - const value = toTextValue(current); - const noneLabel = t("editNone"); - const choices = columnChoices(col); - // Keyed on content: rebuilding columns must not reset the highlight mid-search. - const choicesKey = (choices ?? []).map((c) => `${c.value}\u0000${c.label}`).join("\u0001"); - const items = useMemo( - () => [ - { value: null, label: noneLabel }, - ...(choices ?? []).map((c) => ({ value: c.value, label: String(c.label) })), - ], - // eslint-disable-next-line react-hooks/exhaustive-deps -- `choicesKey` stands for `choices`. - [choicesKey, noneLabel], - ); - - const selected = items.find((item) => item.value === value) ?? null; - const [open, setOpen] = useState(false); - const [focused, setFocused] = useState(false); - const editing = state.status !== "idle"; - const activeChoice = state.status === "idle" ? selected : state.draft; - // The displayed search text is local while editing, even if consumer data changes. - const [query, setQuery] = useState(null); - // Keep the closing list filtered until its animation completes. - const [listQuery, setListQuery] = useState(null); - const highlightedRef = useRef(undefined); - const explicitHighlightRef = useRef(undefined); - const composingRef = useRef(false); - const selectOnMouseUpRef = useRef(false); - const from = { rowKey, colKey }; - - const filtered = useMemo(() => { - const search = searchable(listQuery ?? ""); - if (!search) return items; - const rank = (item: Choice) => { - const text = searchable(item.label); - if (text === search) return 0; - return text.startsWith(search) ? 1 : 2; - }; - return ( - items - .filter((item) => item.value !== null && searchable(item.label).includes(search)) - // Sorting is stable, preserving the original order within each rank. - .toSorted((left, right) => rank(left) - rank(right)) - ); - }, [items, listQuery]); - - const startEditing = () => { - session.begin(selected ?? { value, label: value ?? noneLabel }); - setQuery(selected?.label ?? ""); - setListQuery(null); - highlightedRef.current = undefined; - explicitHighlightRef.current = undefined; - }; - - const closeEditor = () => { - setQuery(null); - explicitHighlightRef.current = undefined; - setOpen(false); - }; - - const cancelEditing = () => { - const active = session.getState(); - session.cancel( - active.status !== "idle" && active.draft.notified && active.draft.value !== value - ? () => change(value) - : undefined, - ); - closeEditor(); - }; - - const leaveEditor = () => { - const active = session.getState(); - if (active.status === "failed" || active.status === "confirming") closeEditor(); - else cancelEditing(); - }; - - const pick = (item: Choice) => { - const active = session.getState(); - if (active.status === "confirming" && active.draft.value === item.value) return; - session.change( - { ...item, notified: item.value !== value }, - item.value !== value ? () => change(item.value) : undefined, - ); - setQuery(item.label); - session.confirm(() => (item.value !== value ? commit(item.value) : undefined), closeEditor); - }; - - const explicitCandidate = () => { - const item = explicitHighlightRef.current; - return item && filtered.includes(item) ? item : undefined; - }; - - const keyboardCandidate = () => { - const highlighted = highlightedRef.current; - return ( - explicitCandidate() ?? - (highlighted && filtered.includes(highlighted) ? highlighted : filtered[0]) - ); - }; - - const handleKeyDown: NonNullable["onKeyDown"]> = ( - event, - ) => { - if (isComposing(event.nativeEvent, composingRef.current)) { - event.preventBaseUIHandler(); - return; - } - switch (event.key) { - case "Enter": { - event.preventDefault(); - event.preventBaseUIHandler(); - const active = session.getState(); - if (active.status === "confirming") return; - if (!open) { - if (active.status === "failed" && active.source === "commit") { - session.confirm( - () => (active.draft.value !== value ? commit(active.draft.value) : undefined), - closeEditor, - ); - return; - } - if (active.status === "idle") startEditing(); - setOpen(true); - return; - } - const item = keyboardCandidate(); - if (item) pick(item); - else leaveEditor(); - return; - } - case "Tab": { - event.preventBaseUIHandler(); - const item = - session.getState().status !== "idle" && open - ? (explicitCandidate() ?? - (searchable(listQuery ?? "") ? keyboardCandidate() : undefined)) - : undefined; - if (item) pick(item); - else leaveEditor(); - if (navigation.move(from, event.shiftKey ? "prev" : "next")) event.preventDefault(); - return; - } - case "Escape": - if (session.getState().status === "idle" && !open) return; - event.preventDefault(); - event.stopPropagation(); - event.preventBaseUIHandler(); - cancelEditing(); - return; - } - }; - - const handleFocus = (event: FocusEvent) => { - const withinCell = focused || containsErrorTarget(event.relatedTarget); - setFocused(true); - if (withinCell) return; - if (session.getState().status === "idle") startEditing(); - event.currentTarget.select(); - }; - - const handleBlur = () => { - setFocused(false); - leaveEditor(); - }; - - const handleMouseDown = (event: MouseEvent) => { - if (event.button === 2 && session.getState().status === "idle") { - event.preventDefault(); - return; - } - if (session.getState().status === "idle") { - startEditing(); - setOpen(true); - } - if (!focused) selectOnMouseUpRef.current = true; - }; - - const handleMouseUp = (event: MouseEvent) => { - if (!selectOnMouseUpRef.current) return; - selectOnMouseUpRef.current = false; - event.preventDefault(); - }; - - const stopWhileEditing = (event: MouseEvent | TouchEvent) => { - if (session.getState().status !== "idle") event.stopPropagation(); - }; - - const renderChoice = (item: Choice) => { - if (item.value === null) - return {item.label}; - if (col.type !== "badge") return item.label; - return ( - item.label} /> - ); - }; - +export function ChoiceEditCell>( + props: DataTableEditableCellProps>, +) { + const coreProps = useEditorProps(props); + const { col } = props; return ( - } - tooltipLabel={tooltipLabel} - editing={editing} - callbackError={callbackError} - label={label} - onEditorLeave={handleBlur} - onEditorCancel={cancelEditing} - getFailure={session.getFailure} - confirming={state.status === "confirming"} - > - - items={items} - filteredItems={filtered} - value={activeChoice} - onValueChange={(item, details) => { - if (details.reason === "item-press" && item) pick(item); - }} - inputValue={query ?? activeChoice?.label ?? ""} - onInputValueChange={(next, details) => { - if (details.reason === "input-change" || details.reason === "input-clear") { - const active = session.getState(); - session.change( - active.status === "idle" - ? (selected ?? { value, label: value ?? noneLabel }) - : active.draft, - ); - setQuery(next); - setListQuery(next); - explicitHighlightRef.current = undefined; - } - }} - open={open} - onOpenChange={(next, details) => { - if (next) { - if (session.getState().status === "idle") startEditing(); - setOpen(true); - if (details.reason !== "input-change") setListQuery(null); - return; - } - if ( - containsErrorTarget(details.event.target) || - ("relatedTarget" in details.event && - containsErrorTarget(details.event.relatedTarget as EventTarget | null)) - ) { - details.cancel(); - return; - } - // Clearing search text is not selection or cancellation. - if (details.reason === "input-clear") { - setOpen(false); - return; - } - if (details.reason === "escape-key") cancelEditing(); - else leaveEditor(); - }} - onOpenChangeComplete={(isOpen) => { - if (!isOpen) setListQuery(null); - }} - onItemHighlighted={(item, details) => { - // Hover is visual feedback, not a keyboard confirmation candidate. - if (details.reason === "pointer") return; - highlightedRef.current = item; - if (item && details.reason === "keyboard") explicitHighlightRef.current = item; - }} - autoHighlight - itemToStringLabel={choiceLabel} - isItemEqualToValue={isChoiceEqual} - > - { - composingRef.current = true; - }} - onCompositionEnd={() => { - composingRef.current = false; - }} - /> - {/* At least as wide as the cell, and wide enough that choices don't wrap. */} - - {t("editNoMatches")} - - {(item: Choice) => ( - - {renderChoice(item)} - - )} - - - - + ( + label} /> + ) + : undefined, + }} + /> ); } diff --git a/packages/core/src/components/data-table/editing/cell/date.tsx b/packages/core/src/components/data-table/editing/cell/date.tsx index 5b707f05a..4701678fb 100644 --- a/packages/core/src/components/data-table/editing/cell/date.tsx +++ b/packages/core/src/components/data-table/editing/cell/date.tsx @@ -1,246 +1,23 @@ -import { useState, type KeyboardEvent } from "react"; -import { Popover } from "@base-ui/react/popover"; -import type { CalendarDate } from "@internationalized/date"; -import { CalendarDays } from "lucide-react"; -import { cn } from "@/lib/utils"; import { useTimeZone } from "@/contexts/appshell-context"; -import { Button } from "@/components/button"; -import { Calendar } from "@/components/calendar"; -import { Input } from "@/components/input"; -import type { DateTimeDraft } from "../../types"; -import { sameDate, toCalendarDate, toIsoDateTime, toTimeText } from "../../cell-values"; -import { useDataTableT } from "../../i18n"; -import type { CellEditNavigation } from "../use-navigation"; -import { useCellEditSession } from "../use-session"; -import { - OVERLAY_CLASS_NAME, - CELL_FOCUS_CLASS_NAME, - CELL_ERROR_CLASS_NAME, - POPUP_CLASS_NAME, - EditableCellFrame, - useCellValue, - useNavigationRef, - type EditableColumn, - type DataTableEditableCellProps, -} from "./shared"; +import { EditableCell } from "@/components/internals/table-core/editing/cell"; +import { dateEditor } from "@/components/internals/table-core/editing/date"; +import { useEditorProps, type EditableColumn, type DataTableEditableCellProps } from "./shared"; type DateColumn> = Extract< EditableColumn, { type: "date" } >; -// Date cells: a transparent button over the cell's own display, with a pointer. -const TRIGGER_CLASS_NAME = cn( - OVERLAY_CLASS_NAME, - CELL_FOCUS_CLASS_NAME, - "astw:cursor-pointer", - "astw:data-popup-open:ring-2 astw:data-popup-open:ring-inset astw:data-popup-open:ring-primary", -); - -// Tab / Shift+Tab from a closed calendar moves between editable cells, the -// same way it does from a typing cell. -function tabBetweenCells( - event: KeyboardEvent, - open: boolean, - navigation: CellEditNavigation, - from: { rowKey: string; colKey: string }, +export function DateEditCell>( + props: DataTableEditableCellProps>, ) { - if (event.key !== "Tab" || open) return; - if (navigation.move(from, event.shiftKey ? "prev" : "next")) event.preventDefault(); -} - -export function DateEditCell>({ - row, - col, - rowKey, - colKey, - label, - navigation, - cellProps, - tooltipLabel, - dateRenderer, -}: DataTableEditableCellProps>) { - const t = useDataTableT(); + const coreProps = useEditorProps(props); const { value: timeZone } = useTimeZone(); - const withTime = col.typeOptions?.dateFormat === "datetime"; - const session = useCellEditSession(col.edit?.error !== false); - const { state } = session; - const { current, display, change, commit, callbackError, containsErrorTarget } = useCellValue( - row, - col, - state.status === "failed" ? state : undefined, - dateRenderer, - ); - const register = useNavigationRef(navigation, rowKey, colKey); - const baseline: DateTimeDraft = { - day: toCalendarDate(current, timeZone)?.toString() ?? null, - time: toTimeText(current, timeZone) || null, - }; - const [open, setOpen] = useState(false); - const differs = (a: DateTimeDraft, b: DateTimeDraft) => - a.day !== b.day || (withTime && a.time !== b.time); - const notifyDraft = (next: DateTimeDraft) => change(withTime ? { ...next } : next.day); - const setDraft = (next: DateTimeDraft) => { - const active = session.getState(); - const previous = active.status === "idle" ? baseline : active.draft; - if (!differs(previous, next)) { - session.begin(next); - return; - } - session.change(next, () => notifyDraft(next)); - }; - const cancelEditing = () => { - const active = session.getState(); - session.cancel( - active.status !== "idle" && differs(active.draft, baseline) - ? () => notifyDraft(baseline) - : undefined, - ); - setOpen(false); - }; - const finish = (next: string | null) => { - session.confirm( - () => (sameDate(next, current, withTime, timeZone) ? undefined : commit(next)), - () => setOpen(false), - ); - }; - const activeDraft = state.status === "idle" ? baseline : state.draft; - const pickedDay = toCalendarDate(activeDraft.day, timeZone); - const timestamp = - withTime && pickedDay && activeDraft.time - ? toIsoDateTime(pickedDay, activeDraft.time, timeZone) - : undefined; - const draftDisplay = withTime - ? `${activeDraft.day ?? "—"} ${activeDraft.time ?? "—"}` - : (activeDraft.day ?? "—"); - const visibleDisplay = state.status === "idle" ? display : draftDisplay; - // The trigger's accessible name carries the date hidden in the visual display. - const accessibleName = typeof visibleDisplay === "string" ? `${label}, ${visibleDisplay}` : label; - - const handleOpenChange = (next: boolean, details?: Popover.Root.ChangeEventDetails) => { - if ( - !next && - details && - (containsErrorTarget(details.event.target) || - ("relatedTarget" in details.event && - containsErrorTarget(details.event.relatedTarget as EventTarget | null))) - ) { - details.cancel(); - return; - } - if (next) { - session.begin(baseline); - } else { - const active = session.getState(); - if ( - details?.reason === "escape-key" || - (active.status !== "failed" && active.status !== "confirming") - ) { - cancelEditing(); - return; - } - } - setOpen(next); - }; - - const handlePick = (day: CalendarDate) => { - const active = session.getState(); - setDraft({ ...(active.status === "idle" ? baseline : active.draft), day: day.toString() }); - if (!withTime) finish(day.toString()); - }; - return ( - } - tooltipLabel={tooltipLabel} - editing={open} - callbackError={callbackError} - label={label} - onEditorCancel={cancelEditing} - getFailure={session.getFailure} - confirming={state.status === "confirming"} - > - - { - if (event.key === "Escape" && !open && session.getState().status !== "idle") { - event.preventDefault(); - event.stopPropagation(); - cancelEditing(); - return; - } - if (event.key === "ArrowDown" && !open) { - event.preventDefault(); - handleOpenChange(true); - return; - } - tabBetweenCells(event, open, navigation, { rowKey, colKey }); - }} - /> - - - event.stopPropagation()} - onTouchStart={(event) => event.stopPropagation()} - > - - {withTime && ( - - setDraft({ - ...activeDraft, - time: event.target.value || null, - }) - } - className="astw:h-8 astw:text-body-md" - /> - )} -
- - {withTime && ( - - )} -
-
-
-
-
-
+ ); } diff --git a/packages/core/src/components/data-table/editing/cell/drafts.test.tsx b/packages/core/src/components/data-table/editing/cell/drafts.test.tsx index 0348a39c5..5d2fccd34 100644 --- a/packages/core/src/components/data-table/editing/cell/drafts.test.tsx +++ b/packages/core/src/components/data-table/editing/cell/drafts.test.tsx @@ -5,10 +5,10 @@ import type { BadgeCellEditOptions, CellEditState, DateCellEditOptions, - DateTimeDraft, NumberCellEditOptions, TextCellEditOptions, } from "@/index"; +import type { DateTimeDraft } from "@/components/internals/table-core/editing/date"; import { createAppShellWrapper } from "../../../../../tests/test-utils"; import { DataTable } from "../../data-table"; import { useDataTable } from "../../use-data-table"; diff --git a/packages/core/src/components/data-table/editing/cell/errors.test.tsx b/packages/core/src/components/data-table/editing/cell/errors.test.tsx index 81b958a1d..051b4b208 100644 --- a/packages/core/src/components/data-table/editing/cell/errors.test.tsx +++ b/packages/core/src/components/data-table/editing/cell/errors.test.tsx @@ -17,6 +17,12 @@ afterEach(() => { type Row = { id: string; value: string | null }; const ROWS: Row[] = [{ id: "1", value: "Original" }]; const noop = () => {}; +const descriptionText = (input: HTMLElement) => + input + .getAttribute("aria-describedby") + ?.split(/\s+/) + .map((id) => document.getElementById(id)?.textContent) + .join(" "); function Harness({ edit, rows = ROWS }: { edit: TextCellEditOptions; rows?: Row[] }) { const columns: Column[] = [{ id: "value", label: "Value", type: "text", edit }]; @@ -129,9 +135,7 @@ describe("DataTable callback error presentation", () => { if (source === "commit") fireEvent.keyDown(input, { key: "Enter" }); expect(input.getAttribute("aria-invalid")).toBe("true"); - expect( - document.getElementById(input.getAttribute("aria-describedby")!)?.textContent, - ).toContain(failure.message); + expect(descriptionText(input)).toContain(failure.message); const popup = await screen.findByRole("dialog", { name: "Error in Value" }); expect(within(popup).getByText(failure.message)).toBeDefined(); expect(within(popup).getByRole("button", { name: "Close error details" })).toBeDefined(); @@ -355,8 +359,8 @@ describe("DataTable callback error presentation", () => { change(input); const popup = await screen.findByRole("dialog", { name: "Error in Value" }); expect(within(popup).getByText("Could not confirm this change")).toBeDefined(); - expect(document.getElementById(input.getAttribute("aria-describedby")!)?.textContent).toBe( - "Could not confirm this change. Press Alt+ArrowDown for error details", + expect(descriptionText(input)).toBe( + "Could not confirm this change Press Alt+ArrowDown for error details", ); expect(popup.textContent).toBe("Could not confirm this change"); expect(input.value).toBe("Changed"); @@ -376,8 +380,8 @@ describe("DataTable callback error presentation", () => { await rejectRequest(request, new Error("Internal server details")); const popup = await screen.findByRole("dialog", { name: "Error in Value" }); expect(popup.textContent).toBe("Could not confirm this change"); - expect(document.getElementById(input.getAttribute("aria-describedby")!)?.textContent).toBe( - "Could not confirm this change. Press Alt+ArrowDown for error details", + expect(descriptionText(input)).toBe( + "Could not confirm this change Press Alt+ArrowDown for error details", ); expect(input.value).toBe("Changed"); expect(input.getAttribute("aria-invalid")).toBe("true"); @@ -398,8 +402,8 @@ describe("DataTable callback error presentation", () => { const popup = await screen.findByRole("dialog", { name: "Error in Value" }); expect(popup.textContent).toBe("Custom feedback"); expect(renderError).toHaveBeenCalledWith({ row: ROWS[0], error: failure }); - expect(document.getElementById(input.getAttribute("aria-describedby")!)?.textContent).toBe( - "Could not confirm this change. Press Alt+ArrowDown for error details", + expect(descriptionText(input)).toBe( + "Could not confirm this change Press Alt+ArrowDown for error details", ); }); @@ -420,9 +424,7 @@ describe("DataTable callback error presentation", () => { const popup = await screen.findByRole("dialog", { name: "Valueのエラー" }); expect(within(popup).getByText(message)).toBeDefined(); expect(within(popup).getByRole("button", { name: "エラーの詳細を閉じる" })).toBeDefined(); - expect(document.getElementById(input.getAttribute("aria-describedby")!)?.textContent).toBe( - `${message}. Alt+↓キーでエラーの詳細を表示できます`, - ); + expect(descriptionText(input)).toBe(`${message} Alt+↓キーでエラーの詳細を表示できます`); }); it("clears an error on a newer successful input and ignores older rejection results", async () => { @@ -441,9 +443,7 @@ describe("DataTable callback error presentation", () => { await rejectRequest(current, new CellEditError("Current failure")); expect(input.getAttribute("aria-invalid")).toBe("true"); await rejectRequest(old, new Error("Outdated failure")); - expect(document.getElementById(input.getAttribute("aria-describedby")!)?.textContent).toContain( - "Current failure", - ); + expect(descriptionText(input)).toContain("Current failure"); fireEvent.change(input, { target: { value: "Newer" } }); expect(queryErrorTrigger()).toBeNull(); expect(input.getAttribute("aria-invalid")).toBeNull(); @@ -532,9 +532,7 @@ describe("DataTable callback error presentation", () => { await user.click(outside); expect(input.value).toBe("Changed"); expect(input.getAttribute("aria-invalid")).toBe("true"); - expect(document.getElementById(input.getAttribute("aria-describedby")!)?.textContent).toContain( - "Temporary save failure", - ); + expect(descriptionText(input)).toContain("Temporary save failure"); expect(queryErrorTrigger()).not.toBeNull(); expect(onValueCommitted).toHaveBeenCalledTimes(1); await user.click(input); @@ -583,9 +581,7 @@ describe("DataTable callback error presentation", () => { expect(input.getAttribute("aria-invalid")).toBe("true"); expect(input.closest("td")?.getAttribute("aria-busy")).toBeNull(); expect(queryErrorTrigger()).not.toBeNull(); - expect( - document.getElementById(input.getAttribute("aria-describedby")!)?.textContent, - ).toContain("Save failed"); + expect(descriptionText(input)).toContain("Save failed"); expect(screen.queryByRole("dialog")).toBeNull(); await user.click(input); @@ -709,9 +705,7 @@ describe("DataTable callback error presentation", () => { change(input); await user.keyboard("{Enter}"); expect(input.getAttribute("aria-keyshortcuts")).toBe("Alt+ArrowDown"); - expect(document.getElementById(input.getAttribute("aria-describedby")!)?.textContent).toContain( - "Press Alt+ArrowDown for error details", - ); + expect(descriptionText(input)).toContain("Press Alt+ArrowDown for error details"); await user.keyboard("{Alt>}{ArrowDown}{/Alt}"); const popup = await screen.findByRole("dialog", { name: "Error in Value" }); expect(within(popup).getByText("Not accepted")).toBeDefined(); diff --git a/packages/core/src/components/data-table/editing/cell/shared.tsx b/packages/core/src/components/data-table/editing/cell/shared.tsx index 713ed68eb..d275c85d0 100644 --- a/packages/core/src/components/data-table/editing/cell/shared.tsx +++ b/packages/core/src/components/data-table/editing/cell/shared.tsx @@ -1,39 +1,19 @@ -import { - useCallback, - useId, - useLayoutEffect, - useRef, - useState, - type ComponentProps, - type ReactNode, - type RefObject, -} from "react"; -import { Popover } from "@base-ui/react/popover"; -import { CircleAlert, X } from "lucide-react"; -import { cn } from "@/lib/utils"; +import type { ComponentProps, ReactNode } from "react"; import { useTimeZone } from "@/contexts/appshell-context"; -import { Button } from "@/components/button"; -import { Table } from "@/components/table"; -import { Tooltip } from "@/components/tooltip"; +import type { Table } from "@/components/table"; +import type { EditableCellOwnerProps } from "@/components/internals/table-core/editing/cell"; +import type { ValueRenderer } from "@/components/internals/table-core"; import type { Column } from "../../types"; import { getCellValue, renderTypedValue } from "../../cell-renderers"; -import { CellEditError } from "../../cell-edit-error"; import { resolveBadgeOptions } from "../../cell-values"; -import type { CellEditNavigation } from "../use-navigation"; import { useDataTableT } from "../../i18n"; -import type { CellEditFailure } from "../use-session"; +import type { CellEditNavigation } from "../use-navigation"; -/** - * A column whose cells can be edited in place. - * - * @internal - */ export type EditableColumn> = Extract< Column, { type: "text" | "number" | "money" | "date" | "badge" | "link" } >; -// The dropdown choices a column offers, or `undefined` when it's typed into. export function columnChoices>(col: Column) { if (col.type === "badge") return resolveBadgeOptions(col.edit?.options, col.typeOptions, col.filter); @@ -41,381 +21,54 @@ export function columnChoices>(col: Column< return undefined; } -/** - * Room for the icon a dropdown or date cell shows at its right edge (a chevron - * or a calendar; 14px plus a gap), so a value ends — or truncates — before it - * instead of running underneath. Read-only cells of the same column keep it - * too, so the column's width doesn't change as rows become editable or not. - * - * @internal - */ -export const ICON_SPACE_CLASS_NAME = "astw:pr-5"; - -// Editors cover the whole cell, end to end, instead of taking part in layout, -// so a cell becoming editable — or being edited — never changes row height or -// column width. They inherit the cell's padding (they're its direct children), -// so their text lines up exactly with the cell's own display underneath. -export const OVERLAY_CLASS_NAME = - "astw:absolute astw:inset-0 astw:h-full astw:w-full astw:p-[inherit] astw:rounded-none astw:border-0 astw:shadow-none astw:bg-transparent astw:dark:bg-transparent"; - -// Spreadsheet-style: the cell being edited outlines its edges (an inset ring, -// so it never spills onto neighbouring cells). -export const CELL_FOCUS_CLASS_NAME = cn( - "astw:outline-none astw:focus:ring-2 astw:focus:ring-inset astw:focus:ring-primary", - "astw:focus-visible:ring-2 astw:focus-visible:ring-inset astw:focus-visible:ring-primary", -); - -// Parsing and callback errors share the cell's error outline. -export const CELL_ERROR_CLASS_NAME = - "astw:ring-[1.5px] astw:ring-inset astw:ring-danger-solid astw:focus:ring-[1.5px] astw:focus:ring-danger-solid astw:focus-visible:ring-[1.5px] astw:focus-visible:ring-danger-solid"; - -// An editable cell says so at rest with a subtle tint instead of an icon. It's -// a background *image* layered over whatever colour the cell already has (the -// row's hover / selected fade, a pinned cell's opaque card), so it never -// replaces them and stays a step darker than its read-only neighbours. The -// cell being edited drops it: an untinted cell with a ring reads as "active". -// (Written out in full: Tailwind only generates classes it finds as literals.) -const EDITABLE_CELL_CLASS_NAME = cn( - "astw:[background-image:linear-gradient(color-mix(in_srgb,var(--foreground)_4%,transparent),color-mix(in_srgb,var(--foreground)_4%,transparent))]", - "astw:hover:[background-image:linear-gradient(color-mix(in_srgb,var(--foreground)_7%,transparent),color-mix(in_srgb,var(--foreground)_7%,transparent))]", - "astw:focus-within:[background-image:none]", -); - -// Text, number and dropdown cells are typed into: the whole cell shows a text -// cursor. -export const INPUT_CLASS_NAME = cn( - OVERLAY_CLASS_NAME, - CELL_FOCUS_CLASS_NAME, - "astw:text-body-md astw:cursor-text", -); - -// A dropdown's text stops before its chevron. -export const ICON_INPUT_CLASS_NAME = "astw:pr-7 astw:[td:last-child>&]:pr-11"; - -// The icon that says how a cell is edited: shown while the cell is hovered or -// being edited (the cell's tint says it's editable at rest). -// Decoration only: a click anywhere in the cell goes to the editor underneath. -const CELL_ICON_CLASS_NAME = cn( - "astw:pointer-events-none astw:absolute astw:inset-y-0 astw:right-2 astw:flex astw:items-center astw:[td:last-child>&]:right-6", - "astw:text-muted-foreground astw:opacity-0 astw:transition-opacity", - "astw:group-hover/cell:opacity-30 astw:group-focus-within/cell:opacity-30", - "astw:[&_svg]:size-3.5", -); - -export const POPUP_CLASS_NAME = cn( - "astw:bg-popover astw:text-popover-foreground astw:z-(--z-portal) astw:flex astw:flex-col astw:gap-3 astw:rounded-md astw:border astw:border-border astw:p-3 astw:shadow-md", - "astw:animate-in astw:fade-in-0 astw:zoom-in-95 astw:data-ending-style:animate-out astw:data-ending-style:fade-out-0 astw:data-ending-style:zoom-out-95", -); - -interface CellErrorUI { - failure: CellEditFailure; - id: string; - message: string; - content: ReactNode; - triggerRef: RefObject; - popupRef: RefObject; - containsTarget: (target: EventTarget | null) => boolean; -} - -// The standard popover body: the alert icon makes it read as an error rather -// than a tooltip. -function DefaultCellErrorContent({ message }: { message: string }) { - return ( -
- {/* One line-height tall, so the icon centres on the first line of text. */} - - -

{message}

-
- ); -} - -export function useCellValue>( - row: TRow, - col: EditableColumn, - failure: CellEditFailure | undefined, - dateRenderer?: (row: TRow) => ReactNode, -) { +/** Bind collection-owned values, callbacks, formatting and localization to neutral cell UI. */ +export function useEditorProps>({ + row, + col, + valueRenderer, + ...props +}: DataTableEditableCellProps): EditableCellOwnerProps { const { value: timeZone } = useTimeZone(); - const current = getCellValue(row, col); - const render = col.render ?? dateRenderer; - const display = render - ? render(row) - : renderTypedValue(row, col, current, { linkAsText: true, timeZone }); const t = useDataTableT(); - const errorId = useId(); - const triggerRef = useRef(null); - const popupRef = useRef(null); - const containsErrorTarget = (target: EventTarget | null) => - target instanceof Node && - !!(triggerRef.current?.contains(target) || popupRef.current?.contains(target)); - const change = (value: unknown) => - (col.edit?.onValueChange as ((row: TRow, value: unknown) => unknown) | undefined)?.(row, value); - const commit = (value: unknown) => - (col.edit?.onValueCommitted as ((row: TRow, value: unknown) => unknown) | undefined)?.( - row, - value, - ); - const errorConfig = col.edit?.error; - const renderError = errorConfig && errorConfig.render; - const message = - failure?.error instanceof CellEditError && failure.error.message - ? failure.error.message - : t("editCallbackError"); - const callbackError: CellErrorUI | undefined = - failure && failure.source !== "parse" - ? { - failure, - id: errorId, - message: renderError ? t("editCallbackError") : message, - content: renderError ? ( - renderError({ row, error: failure.error }) - ) : ( - - ), - triggerRef, - popupRef, - containsTarget: containsErrorTarget, - } - : undefined; - return { current, display, change, commit, callbackError, containsErrorTarget }; -} - -/** - * Registers the cell's focusable element with the table's Tab - * navigation. Unregisters on every detach instead of returning a ref cleanup: - * `Input` and `Combobox.Input` merge refs with a plain callback that calls ours - * with `null` and drops any cleanup we return. - */ -export function useNavigationRef( - navigation: CellEditNavigation, - rowKey: string, - colKey: string, -) { - const unregisterRef = useRef<(() => void) | null>(null); - return useCallback( - (element: T | null) => { - unregisterRef.current?.(); - unregisterRef.current = element ? navigation.register(rowKey, colKey, element) : null; + const current = getCellValue(row, col); + const renderError = col.edit?.error && col.edit.error.render; + let display: ReactNode; + if (col.render) display = col.render(row); + else if (valueRenderer) display = valueRenderer(current, row); + else display = renderTypedValue(row, col, current, { linkAsText: true, timeZone }); + return { + ...props, + current, + display, + change: (value) => + (col.edit?.onValueChange as ((row: TRow, value: unknown) => unknown) | undefined)?.( + row, + value, + ), + commit: (value) => + (col.edit?.onValueCommitted as ((row: TRow, value: unknown) => unknown) | undefined)?.( + row, + value, + ), + renderError: renderError ? (error) => renderError({ row, error }) : undefined, + interceptErrors: col.edit?.error !== false, + truncate: col.truncate, + slotPrefix: "data-table", + labels: { + notANumber: t("editNotANumber"), + revertHint: t("editRevertHint"), + callbackError: t("editCallbackError"), + errorHint: t("editErrorHint"), + showError: t("editShowError", { label: props.label }), + errorDialog: t("editErrorDialog", { label: props.label }), + closeError: t("editCloseError"), + none: t("editNone"), + noMatches: t("editNoMatches"), + chooseTime: t("chooseTime"), + clear: t("editClear"), + done: t("editDone"), }, - [navigation, rowKey, colKey], - ); -} - -export function EditableCellFrame({ - cellProps, - display, - truncate, - hideDisplay, - icon, - tooltipLabel, - editing, - callbackError, - label, - onEditorLeave, - onEditorCancel, - getFailure, - confirming, - children, -}: { - cellProps: ComponentProps; - display: ReactNode; - truncate?: boolean; - tooltipLabel?: string; - editing: boolean; - callbackError?: CellErrorUI; - label: string; - onEditorLeave?: () => void; - onEditorCancel: () => void; - getFailure: () => CellEditFailure | undefined; - confirming: boolean; - /** Typed-into cells hide the display while the input shows the text. */ - hideDisplay?: "focused" | "forced-colors"; - /** Shown on hover or focus; the cell's tint marks editability at rest. */ - icon?: ReactNode; - children: ReactNode; -}) { - const t = useDataTableT(); - const [tooltipOpen, setTooltipOpen] = useState(false); - const [dismissedFailure, setDismissedFailure] = useState(null); - const [manuallyOpenedFailure, setManuallyOpenedFailure] = useState(null); - const [navigationDismissedFailure, setNavigationDismissedFailure] = - useState(null); - const errorActionsRef = useRef(null); - const tabNavigationRef = useRef(false); - const errorOpen = !!callbackError && dismissedFailure !== callbackError.failure; - const showTooltip = tooltipLabel !== undefined && !editing && !callbackError; - const dismissForNavigation = () => { - const failure = getFailure(); - if (!failure || failure.source === "parse") return; - setNavigationDismissedFailure(failure); - setDismissedFailure(failure); }; - useLayoutEffect(() => { - // Remove closing focus guards before native Tab chooses its destination. - if (!errorOpen && navigationDismissedFailure === callbackError?.failure) - errorActionsRef.current?.unmount(); - }, [errorOpen, callbackError?.failure, navigationDismissedFailure]); - const cell = ( - { - if ( - event.currentTarget.contains(event.relatedTarget) || - callbackError?.containsTarget(event.relatedTarget) - ) - return; - if (tabNavigationRef.current) dismissForNavigation(); - onEditorLeave?.(); - }} - onKeyDown={(event) => { - if ( - event.key === "Tab" && - !event.defaultPrevented && - event.currentTarget.contains(event.target as Node) - ) - dismissForNavigation(); - tabNavigationRef.current = false; - }} - onKeyDownCapture={(event) => { - tabNavigationRef.current = - event.key === "Tab" && event.currentTarget.contains(event.target as Node); - if ( - callbackError && - event.key === "Escape" && - !callbackError.popupRef.current?.contains(event.target as Node) - ) { - event.preventDefault(); - event.stopPropagation(); - if (errorOpen) setDismissedFailure(callbackError.failure); - else onEditorCancel(); - return; - } - if (callbackError && event.altKey && event.key === "ArrowDown") { - event.preventDefault(); - event.stopPropagation(); - setNavigationDismissedFailure(null); - setManuallyOpenedFailure(callbackError.failure); - setDismissedFailure(null); - if (errorOpen) callbackError.popupRef.current?.focus({ preventScroll: true }); - } - }} - // Editing a cell must never fire `onClickRow`. - onClick={(event) => event.stopPropagation()} - > - - {children} - {callbackError && ( - <> - - {callbackError.message}. {t("editErrorHint")} - - { - setDismissedFailure(open ? null : callbackError.failure); - if (open) { - setNavigationDismissedFailure(null); - setManuallyOpenedFailure(callbackError.failure); - } - }} - > - event.stopPropagation()} - > - - - {/* Opens directly under the cell, not under the small icon trigger. */} - callbackError.triggerRef.current?.closest("td") ?? null} - sideOffset={2} - side="bottom" - align="start" - > - event.stopPropagation()} - onTouchStart={(event) => event.stopPropagation()} - onKeyDown={(event) => { - if (event.key === "Escape") event.stopPropagation(); - }} - > -
-
{callbackError.content}
- } - > - -
-
-
-
-
- - )} - {icon !== undefined && !callbackError && ( - - )} -
- ); - return ( - - - {tooltipLabel} - - ); } export interface DataTableEditableCellProps< @@ -431,8 +84,8 @@ export interface DataTableEditableCellProps< align: "left" | "right"; tooltipLabel?: string; navigation: CellEditNavigation; - /** Reuses the table's column-level date formatter cache. */ - dateRenderer?: (row: TRow) => ReactNode; + /** Reuses column-level preparation with the editor's already-resolved current value. */ + valueRenderer?: ValueRenderer; /** `data-slot`, style, class and context-menu handlers shared with static cells. */ cellProps: ComponentProps; } diff --git a/packages/core/src/components/data-table/editing/cell/typing.test.tsx b/packages/core/src/components/data-table/editing/cell/typing.test.tsx index de0433a12..ac6eed566 100644 --- a/packages/core/src/components/data-table/editing/cell/typing.test.tsx +++ b/packages/core/src/components/data-table/editing/cell/typing.test.tsx @@ -18,7 +18,11 @@ afterEach(() => { }); const errorText = (input: HTMLElement) => - document.getElementById(input.getAttribute("aria-describedby") ?? "")?.textContent; + input + .getAttribute("aria-describedby") + ?.split(/\s+/) + .map((id) => document.getElementById(id)?.textContent) + .join(" "); describe("DataTable inline editing", () => { describe("keyboard", () => { @@ -204,7 +208,7 @@ describe("DataTable inline editing", () => { expect(input.getAttribute("aria-invalid")).toBeNull(); await user.keyboard("{Enter}"); expect(input.getAttribute("aria-invalid")).toBe("true"); - expect(errorText(input)).toBe("Enter a number. Press Esc to undo"); + expect(errorText(input)).toBe("Enter a number Press Esc to undo"); expect(document.activeElement).toBe(input); await user.tab(); expect(document.activeElement).toBe(input); @@ -249,7 +253,7 @@ describe("DataTable inline editing", () => { ); const [input] = screen.getAllByRole("textbox", { name: "Received" }); await retype(user, input, "abc{Enter}"); - expect(errorText(input)).toBe("数値を入力してください. Escキーで元に戻せます"); + expect(errorText(input)).toBe("数値を入力してください Escキーで元に戻せます"); }); }); diff --git a/packages/core/src/components/data-table/editing/cell/typing.tsx b/packages/core/src/components/data-table/editing/cell/typing.tsx index 90e39553e..f4a87c123 100644 --- a/packages/core/src/components/data-table/editing/cell/typing.tsx +++ b/packages/core/src/components/data-table/editing/cell/typing.tsx @@ -1,261 +1,15 @@ -import { - useId, - useRef, - useState, - type ChangeEvent, - type FocusEvent, - type KeyboardEvent, - type MouseEvent, - type TouchEvent, -} from "react"; -import { cn } from "@/lib/utils"; -import { isComposing } from "@/lib/is-composing"; -import { Input } from "@/components/input"; -import { Tooltip } from "@/components/tooltip"; -import { - normalizeNumberText, - parseNumberText, - sameNumber, - toNumberEditText, - toNumberValue, - toTextValue, -} from "../../cell-values"; -import { useDataTableT } from "../../i18n"; -import { useCellEditSession } from "../use-session"; -import { - CELL_ERROR_CLASS_NAME, - ICON_INPUT_CLASS_NAME, - INPUT_CLASS_NAME, - EditableCellFrame, - useCellValue, - useNavigationRef, - type DataTableEditableCellProps, -} from "./shared"; - -export function TypingEditCell>({ - row, - col, - rowKey, - colKey, - label, - align, - navigation, - cellProps, - tooltipLabel, -}: DataTableEditableCellProps) { - const t = useDataTableT(); - const errorId = useId(); - const session = useCellEditSession(col.edit?.error !== false); - const { state } = session; - const failure = state.status === "failed" ? state : undefined; - const { current, display, change, commit, callbackError, containsErrorTarget } = useCellValue( - row, - col, - failure, - ); - const register = useNavigationRef(navigation, rowKey, colKey); - const editing = state.status !== "idle"; - const [focused, setFocused] = useState(false); - const [hovered, setHovered] = useState(false); - const composingRef = useRef(false); - const selectOnMouseUpRef = useRef(false); - - const numeric = col.type === "number" || col.type === "money"; - const baselineText = numeric - ? toNumberEditText(toNumberValue(current)) - : (toTextValue(current) ?? ""); - const text = state.status === "idle" ? baselineText : state.draft; - const message = failure?.source === "parse" ? t("editNotANumber") : undefined; - - const revert = (notify = false) => { - const previous = session.getState(); - session.cancel( - notify && previous.status !== "idle" && previous.draft !== baselineText - ? () => change(baselineText) - : undefined, - ); - }; - - const commitDraft = (): boolean => { - const active = session.getState(); - if (active.status === "idle" || active.status === "confirming") return true; - const draftText = active.draft; - const value = numeric - ? parseNumberText(normalizeNumberText(draftText)) - : toTextValue(draftText); - if (value === undefined) { - session.fail(undefined, "parse"); - return false; - } - const unchanged = - draftText === baselineText || - (numeric - ? sameNumber(value as number | null, toNumberValue(current)) - : value === toTextValue(current)); - session.confirm(() => (unchanged ? undefined : commit(value))); - return true; - }; - - const handleChange = (event: ChangeEvent) => { - const next = event.target.value; - const active = session.getState(); - const previous = active.status === "idle" ? baselineText : active.draft; - if (next !== previous) session.change(next, () => change(next)); - }; - - // Keep IME output raw until cell confirmation, just like other draft changes. - const handleCompositionEnd = () => { - composingRef.current = false; - }; - - const handleKeyDown = (event: KeyboardEvent) => { - // While an IME is composing, Enter confirms the conversion, not the cell. - if (isComposing(event.nativeEvent, composingRef.current)) return; - const from = { rowKey, colKey }; - switch (event.key) { - case "Enter": - event.preventDefault(); - if (session.getState().status === "idle") { - session.begin(baselineText); - event.currentTarget.select(); - } else { - commitDraft(); - } - return; - case "Tab": { - const active = session.getState(); - const failedCommit = active.status === "failed" && active.source === "commit"; - if (!failedCommit && !commitDraft()) { - event.preventDefault(); - return; - } - // At the first / last editable cell, native Tab leaves the table. - if (navigation.move(from, event.shiftKey ? "prev" : "next")) event.preventDefault(); - return; - } - case "Escape": - if (session.getState().status === "idle") return; - // Handled here, so an enclosing dialog doesn't also close on this Esc. - event.preventDefault(); - event.stopPropagation(); - revert(true); - return; - } - }; - - const handleFocus = (event: FocusEvent) => { - const withinCell = focused || containsErrorTarget(event.relatedTarget); - setFocused(true); - if (withinCell) return; - session.begin(baselineText); - event.currentTarget.select(); - }; - - const handleBlur = () => { - setFocused(false); - const active = session.getState(); - if (active.status === "failed") { - // Preserve callback failures; malformed numeric blur still cancels the edit. - if (active.source === "parse") revert(true); - return; - } - if (!commitDraft()) revert(true); - }; - - const handleMouseDown = (event: MouseEvent) => { - if (editing) return; - // A right-click on a resting cell opens DataTable's cell menu instead of editing. - if (event.button === 2) { - event.preventDefault(); - return; - } - session.begin(baselineText); - if (focused) event.currentTarget.select(); - selectOnMouseUpRef.current = true; - }; - - // The click that focuses the cell keeps the select-all from `handleFocus`; - // otherwise mouseup would collapse it to a caret. - const handleMouseUp = (event: MouseEvent) => { - if (!selectOnMouseUpRef.current) return; - selectOnMouseUpRef.current = false; - event.preventDefault(); - }; - - // While editing, the browser's own menu and long-press (paste, select) win - // over DataTable's cell menu. - const stopWhileEditing = (event: MouseEvent | TouchEvent) => { - if (editing) event.stopPropagation(); - }; - - const hint = t("editRevertHint"); - - return ( - revert(true)} - getFailure={session.getFailure} - confirming={state.status === "confirming"} - > - {message !== undefined && ( - - {message}. {hint} - - )} - - { - composingRef.current = true; - }} - onCompositionEnd={handleCompositionEnd} - onMouseDown={handleMouseDown} - onMouseUp={handleMouseUp} - onPointerEnter={() => setHovered(true)} - onPointerLeave={() => setHovered(false)} - onContextMenu={stopWhileEditing} - onTouchStart={stopWhileEditing} - /> - } - /> - - {message} - {hint} - - - +import { EditableCell } from "@/components/internals/table-core/editing/cell"; +import { numberEditor, textEditor } from "@/components/internals/table-core/editing/typing"; +import { useEditorProps, type DataTableEditableCellProps } from "./shared"; + +export function TypingEditCell>( + props: DataTableEditableCellProps, +) { + const coreProps = useEditorProps(props); + const numeric = props.col.type === "number" || props.col.type === "money"; + return numeric ? ( + + ) : ( + ); } diff --git a/packages/core/src/components/data-table/editing/use-session.ts b/packages/core/src/components/data-table/editing/use-session.ts deleted file mode 100644 index 0c1991406..000000000 --- a/packages/core/src/components/data-table/editing/use-session.ts +++ /dev/null @@ -1,171 +0,0 @@ -import { useEffect, useRef, useState } from "react"; - -/** @internal */ -export interface CellEditFailure { - error: unknown; - source: "parse" | "change" | "commit"; -} - -/** @internal */ -export type CellEditSessionState = - | { status: "idle" } - | { status: "editing"; draft: TDraft } - | { status: "confirming"; draft: TDraft } - | ({ status: "failed"; draft: TDraft } & CellEditFailure); - -function isPromiseLike(value: unknown): value is PromiseLike { - return typeof (value as PromiseLike | null | undefined)?.then === "function"; -} - -/** Owns the draft and its failure together; consumer data remains authoritative. @internal */ -export function useCellEditSession(enabled: boolean) { - const [state, setState] = useState>({ status: "idle" }); - const { current: session } = useRef({ - state, - revision: 0, - mounted: false, - pendingChange: null as Promise | null, - }); - const transition = (next: CellEditSessionState) => { - session.state = next; - setState(next); - }; - const isCurrent = (revision: number) => session.mounted && session.revision === revision; - - useEffect(() => { - session.mounted = true; - return () => { - session.mounted = false; - session.revision++; - session.pendingChange = null; - }; - }, [enabled, session]); - - const begin = (draft: TDraft) => { - if (session.state.status !== "idle") return; - session.revision++; - transition({ status: "editing", draft }); - }; - - const change = (draft: TDraft, callback?: () => unknown) => { - const revision = ++session.revision; - session.pendingChange = null; - transition({ status: "editing", draft }); - if (!callback) return; - if (!enabled) { - callback(); - return; - } - const reject = (error: unknown) => { - if (isCurrent(revision)) transition({ status: "failed", draft, error, source: "change" }); - }; - try { - const result = callback(); - if (isPromiseLike(result)) { - const pending = Promise.resolve(result).then( - () => { - if (isCurrent(revision) && session.pendingChange === pending) - session.pendingChange = null; - return true; - }, - (error: unknown) => { - if (isCurrent(revision) && session.pendingChange === pending) - session.pendingChange = null; - reject(error); - return false; - }, - ); - if (isCurrent(revision)) session.pendingChange = pending; - } - } catch (error) { - reject(error); - } - }; - - const discard = () => { - session.revision++; - session.pendingChange = null; - transition({ status: "idle" }); - }; - - const confirm = (callback: () => unknown, onSuccess?: () => void) => { - const current = session.state; - if ( - current.status === "idle" || - current.status === "confirming" || - (current.status === "failed" && current.source !== "commit") - ) - return; - if (!enabled) { - discard(); - onSuccess?.(); - callback(); - return; - } - const { draft } = current; - const revision = session.revision; - const pendingChange = session.pendingChange; - transition({ status: "confirming", draft }); - const isConfirming = () => isCurrent(revision) && session.state.status === "confirming"; - const complete = () => { - if (!isConfirming()) return; - transition({ status: "idle" }); - onSuccess?.(); - }; - const reject = (error: unknown) => { - if (isConfirming()) transition({ status: "failed", draft, error, source: "commit" }); - }; - const run = () => { - if (!isConfirming()) return; - try { - const result = callback(); - if (isPromiseLike(result)) { - void Promise.resolve(result).then(complete, reject); - return; - } - } catch (error) { - reject(error); - return; - } - complete(); - }; - if (pendingChange) { - void pendingChange.then((valid) => { - if (valid) run(); - }); - } else { - run(); - } - }; - - const fail = (error: unknown, source: "parse") => { - const current = session.state; - if (current.status === "idle") return; - session.revision++; - session.pendingChange = null; - transition({ status: "failed", draft: current.draft, error, source }); - }; - - const cancel = (callback?: () => unknown) => { - discard(); - if (!callback) return; - if (!enabled) { - callback(); - return; - } - // Restoration failures have no draft to attach to and must not recreate an orphan error. - try { - const result = callback(); - if (isPromiseLike(result)) void Promise.resolve(result).catch(() => {}); - } catch { - // The edit has already been cancelled. - } - }; - - const getFailure = () => { - const current = session.state; - return current.status === "failed" ? current : undefined; - }; - - return { state, getState: () => session.state, getFailure, begin, change, confirm, fail, cancel }; -} diff --git a/packages/core/src/components/data-table/index.ts b/packages/core/src/components/data-table/index.ts index de84bd250..23f847285 100644 --- a/packages/core/src/components/data-table/index.ts +++ b/packages/core/src/components/data-table/index.ts @@ -1,7 +1,7 @@ // DataTable compound component export { DataTable, type DataTablePaginationProps, type DataTableRootProps } from "./data-table"; -export { CellEditError } from "./cell-edit-error"; +export { CellEditError } from "@/components/internals/table-core/cell-edit-error"; export { useDataTable } from "./use-data-table"; export { useDataTableContext, type DataTableContextValue } from "./context"; @@ -24,8 +24,8 @@ export type { DataTableFilterConfig, DataTableTreeRow, DateCellEditOptions, - DateTimeDraft, DateCellOptions, + DateTimeDraft, LinkCellOptions, MetadataFieldOptions, MoneyCellOptions, diff --git a/packages/core/src/components/data-table/rows.tsx b/packages/core/src/components/data-table/rows.tsx index e85b80c5f..9d51d5e8d 100644 --- a/packages/core/src/components/data-table/rows.tsx +++ b/packages/core/src/components/data-table/rows.tsx @@ -9,11 +9,11 @@ import { Menu } from "@/components/menu"; import { Tooltip } from "@/components/tooltip"; import type { DataTableTreeRow, RowAction, RowExpansionOptions } from "./types"; import { SubRowsCellContent } from "./sub-rows-cell"; -import { getCellValue, createTypedCellRenderer } from "./cell-renderers"; +import { getCellValue, createTypedValueRenderer } from "./cell-renderers"; import { DataTableCellContextMenu, getCellContextValue } from "./context-menu"; import { useCellContextMenu } from "./use-cell-context-menu"; import { DataTableEditableCell, hasEditorIcon, isEditableColumn } from "./editing/cell/root"; -import { ICON_SPACE_CLASS_NAME } from "./editing/cell/shared"; +import { ICON_SPACE_CLASS_NAME } from "@/components/internals/table-core/editing/shared"; import { useCellEditNavigation } from "./editing/use-navigation"; import { RowExpandToggle, DataTableExpandedRow } from "./expanded-row"; import { useDataTableT } from "./i18n"; @@ -83,7 +83,15 @@ function DataTableRows>({ new Map( ordered .filter((col) => !col.render) - .map((col) => [col, createTypedCellRenderer(col, timeZone)]), + .map((col) => { + const context = { timeZone }; + const readonly = createTypedValueRenderer(col, context); + const editable = + col.type === "link" + ? createTypedValueRenderer(col, context, { linkAsText: true }) + : readonly; + return [col, { readonly, editable }]; + }), ), [ordered, timeZone], ); @@ -221,7 +229,10 @@ function DataTableRows>({ (col.edit?.canEdit?.(row, { selected }) ?? true); // An editable cell renders its own display; skip rendering it twice. let content: ReactNode; - if (!editable) content = col.render ? col.render(row) : cellRenderers.get(col)?.(row); + if (!editable) + content = col.render + ? col.render(row) + : cellRenderers.get(col)?.readonly(getCellValue(row, col), row); const customCellProps = col.cellProps?.(row); const { style: cellStyle, className: cellClassName } = pinCellProps( @@ -333,7 +344,7 @@ function DataTableRows>({ label={headerLabel} align={resolveAlign(col)} navigation={navigation} - dateRenderer={col.type === "date" ? cellRenderers.get(col) : undefined} + valueRenderer={cellRenderers.get(col)?.editable} tooltipLabel={tooltipLabel} cellProps={cellProps} /> diff --git a/packages/core/src/components/data-table/types.ts b/packages/core/src/components/data-table/types.ts index af0904cac..b355a4c6b 100644 --- a/packages/core/src/components/data-table/types.ts +++ b/packages/core/src/components/data-table/types.ts @@ -1,6 +1,22 @@ import type { ComponentProps, ReactNode } from "react"; import type { TreeSelectionBehaviorProps } from "@/lib/tree/types"; -import type { BadgeOptions } from "@/components/badge-list"; +import type { DateTimeDraft } from "@/components/internals/table-core/editing/date"; +export type { DateTimeDraft } from "@/components/internals/table-core/editing/date"; +import type { + BadgeCellOptions, + DateCellOptions, + LinkCellOptions, + MoneyCellOptions, + NumberCellOptions, +} from "@/components/internals/table-core/column-types"; +export type { + BadgeCellOptions, + ColumnCellType, + DateCellOptions, + LinkCellOptions, + MoneyCellOptions, + NumberCellOptions, +} from "@/components/internals/table-core/column-types"; import type { CollectionControl, Filter, @@ -16,76 +32,8 @@ import type { // Column Definitions // ============================================================================= -/** - * Built-in cell renderer types for `Column.type`. - * - * Each type produces a default render based on the value returned by - * `accessor`. Pass `render` to override the built-in renderer. - * - * - `text` — `String(value)` with `—` placeholder for null/undefined. - * - `number` — locale-formatted number with `—` for null/undefined. - * - `money` — `Intl.NumberFormat` currency. See `MoneyOptions`. - * - `date` — `Intl.DateTimeFormat`. Accepts `Date`, ISO string, or epoch ms. - * - `badge` — `` keyed off the value. See `BadgeOptions`. - * - `link` — app-shell `` with `href` from `LinkOptions`. - */ -export type ColumnCellType = "text" | "number" | "money" | "date" | "badge" | "link"; - export type { BadgeVariant } from "@/components/badge-list"; -/** Options for `type: "number"` cells. */ -export interface NumberCellOptions { - /** Minimum decimal places. Default: `0`. */ - minDecimals?: number; - /** Maximum decimal places. Default: `minDecimals` (or `0`). */ - maxDecimals?: number; - /** BCP 47 locale tag. Defaults to the runtime locale. */ - locale?: string; -} - -/** Options for `type: "money"` cells. */ -export interface MoneyCellOptions> { - /** - * ISO 4217 currency code. Pass a string for a static currency or a function - * to read it from the row. Default: `"USD"`. - */ - currency?: string | ((row: TRow) => string); - /** - * Maximum decimals. Raises the cap above the currency default while keeping - * the minimum at the currency default (e.g. USD stays at ≥2, but a price - * column can show up to 4). - */ - maxDecimals?: number; - /** BCP 47 locale tag. Defaults to the runtime locale. */ - locale?: string; -} - -/** Options for `type: "date"` cells. */ -export interface DateCellOptions { - /** - * Format style. `"short"` → `Apr 9, 2026`; `"long"` → `April 9, 2026`; - * `"datetime"` → `Apr 9, 2026, 3:45 PM`. Default: `"short"`. - */ - dateFormat?: "short" | "long" | "datetime"; - /** BCP 47 locale tag. Defaults to the runtime locale. */ - locale?: string; -} - -/** Options for `type: "badge"` cells. */ -export interface BadgeCellOptions extends BadgeOptions { - /** Maximum number of badges to display before showing a "+N" overflow indicator */ - maxVisible?: number; -} - -/** Options for `type: "link"` cells. `href` is required. */ -export interface LinkCellOptions> { - /** - * Extracts the link target. Returning `null` / `undefined` renders the cell - * value as plain text instead of a link. - */ - href: (row: TRow) => string | null | undefined; -} - // ============================================================================= // Inline editing // ============================================================================= @@ -96,12 +44,6 @@ export interface CellEditState { selected: boolean; } -/** Incomplete date-time editor state, interpreted in the AppShell timezone. */ -export interface DateTimeDraft { - day: string | null; - time: string | null; -} - interface CellEditBase, TValue, TDraft = TValue | null> { /** * Decides, per row, whether the cell can be edited. Receives the row and diff --git a/packages/core/src/components/data-table/cell-edit-error.ts b/packages/core/src/components/internals/table-core/cell-edit-error.ts similarity index 100% rename from packages/core/src/components/data-table/cell-edit-error.ts rename to packages/core/src/components/internals/table-core/cell-edit-error.ts diff --git a/packages/core/src/components/internals/table-core/cell-renderers.test-d.ts b/packages/core/src/components/internals/table-core/cell-renderers.test-d.ts new file mode 100644 index 000000000..52ed81f30 --- /dev/null +++ b/packages/core/src/components/internals/table-core/cell-renderers.test-d.ts @@ -0,0 +1,75 @@ +import type { ReactNode } from "react"; +import { expectTypeOf, test } from "vitest"; +import { createValueRenderer, type ValueRendererContext } from "./cell-renderers"; +import { displayCellAdapters } from "./display-cell-adapters"; +import type { ColumnCellType, TypedColumnDisplay } from "./column-types"; + +type Row = { id: string; currency: string }; +const context: ValueRendererContext = { timeZone: "Asia/Tokyo" }; + +test("the exhaustive display catalog shares one preparation contract", () => { + expectTypeOf().toEqualTypeOf(); + expectTypeOf(displayCellAdapters.number.defaultAlign).toEqualTypeOf<"right">(); + expectTypeOf(displayCellAdapters.text.defaultAlign).toEqualTypeOf<"left">(); + expectTypeOf(displayCellAdapters.date.createRenderer).parameters.toEqualTypeOf< + [TypedColumnDisplay, ValueRendererContext] + >(); + expectTypeOf(displayCellAdapters.money.createRenderer).parameters.toEqualTypeOf< + [TypedColumnDisplay, ValueRendererContext] + >(); + expectTypeOf(displayCellAdapters.text.createRenderer).parameters.toEqualTypeOf< + [TypedColumnDisplay, ValueRendererContext] + >(); + + createValueRenderer({ type: "date" }, context); + createValueRenderer({ type: "number" }, context); + // @ts-expect-error Every display kind requires its owner-resolved context. + createValueRenderer({ type: "number" }); + // @ts-expect-error Date preparation uses the same required context. + createValueRenderer({ type: "date" }); + // @ts-expect-error The display environment must include its timezone. + createValueRenderer({ type: "date" }, {}); + // @ts-expect-error Renderer dependencies are passed as a context object. + createValueRenderer({ type: "number" }, "UTC"); + // @ts-expect-error Adapters also require the shared preparation context. + displayCellAdapters.text.createRenderer({ type: "text" }); +}); + +test("renderer creation preserves row-dependent currency and link contracts", () => { + const money = displayCellAdapters.money.createRenderer( + { type: "money", typeOptions: { currency: (row) => row.currency } }, + context, + ); + const link = displayCellAdapters.link.createRenderer( + { type: "link", typeOptions: { href: (row) => `/rows/${row.id}` } }, + context, + ); + const dispatched = createValueRenderer( + { type: "money", typeOptions: { currency: (row) => row.currency } }, + context, + ); + expectTypeOf(money).toEqualTypeOf<(value: unknown, row: Row) => ReactNode>(); + expectTypeOf(link).toEqualTypeOf<(value: unknown, row: Row) => ReactNode>(); + expectTypeOf(dispatched).toEqualTypeOf<(value: unknown, row: Row) => ReactNode>(); + + displayCellAdapters.money.createRenderer( + { + type: "money", + typeOptions: { + // @ts-expect-error A currency callback cannot require a different row shape. + currency: (row: { other: string }) => row.other, + }, + }, + context, + ); + displayCellAdapters.link.createRenderer( + { + type: "link", + typeOptions: { + // @ts-expect-error A link callback cannot require a different row shape. + href: (row: { other: string }) => row.other, + }, + }, + context, + ); +}); diff --git a/packages/core/src/components/internals/table-core/cell-renderers.test.tsx b/packages/core/src/components/internals/table-core/cell-renderers.test.tsx new file mode 100644 index 000000000..50efd3cdd --- /dev/null +++ b/packages/core/src/components/internals/table-core/cell-renderers.test.tsx @@ -0,0 +1,55 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { createValueRenderer, getDisplayCellAdapter } from "./cell-renderers"; +import { displayCellAdapters } from "./display-cell-adapters"; +import type { ColumnCellType, ValueDisplayDescriptor } from "./column-types"; + +const context = { timeZone: "Asia/Tokyo" }; +const descriptors = { + text: { type: "text" }, + number: { type: "number", typeOptions: { minDecimals: 2 } }, + money: { type: "money", typeOptions: { currency: (row) => row.currency } }, + date: { type: "date", typeOptions: { locale: "en-US" } }, + badge: { type: "badge" }, + link: { type: "link", typeOptions: { href: (row) => `/rows/${row.id}` } }, +} satisfies Record>; + +afterEach(() => vi.restoreAllMocks()); + +describe("display renderer dispatch", () => { + it.each(Object.values(descriptors))( + "passes the descriptor and context unchanged to the $type adapter", + (descriptor) => { + const renderer = vi.fn(() => "Rendered"); + const prepare = vi + .spyOn(displayCellAdapters[descriptor.type], "createRenderer") + .mockReturnValue(renderer); + const renderValue = createValueRenderer(descriptor, context); + expect(prepare).toHaveBeenCalledExactlyOnceWith(descriptor, context); + expect(renderValue).toBe(renderer); + const row = { id: "A", currency: "EUR" }; + expect(renderValue("Raw value", row)).toBe("Rendered"); + expect(renderer).toHaveBeenCalledExactlyOnceWith("Raw value", row); + }, + ); + + it("looks up metadata without creating a renderer", () => { + const prepare = vi.spyOn(displayCellAdapters.date, "createRenderer"); + expect(getDisplayCellAdapter("date")).toBe(displayCellAdapters.date); + expect(getDisplayCellAdapter(undefined)).toBe(displayCellAdapters.text); + expect(prepare).not.toHaveBeenCalled(); + }); + + it("uses the text fallback when a display kind is omitted", () => { + expect(createValueRenderer({}, context)("Raw value", {})).toBe("Raw value"); + }); + + it.each(["custom", "constructor", "__proto__", Object("number"), { toString: () => "number" }])( + "retains the text fallback for unsupported runtime type %s", + (type: unknown) => { + // @ts-expect-error Exercise malformed JavaScript configuration outside the typed contract. + expect(getDisplayCellAdapter(type)).toBe(displayCellAdapters.text); + // @ts-expect-error Exercise malformed JavaScript configuration outside the typed contract. + expect(createValueRenderer({ type }, context)("Raw value", {})).toBe("Raw value"); + }, + ); +}); diff --git a/packages/core/src/components/internals/table-core/cell-renderers.ts b/packages/core/src/components/internals/table-core/cell-renderers.ts new file mode 100644 index 000000000..3f36ec538 --- /dev/null +++ b/packages/core/src/components/internals/table-core/cell-renderers.ts @@ -0,0 +1,51 @@ +import type { ReactNode } from "react"; +import type { ColumnCellType, TypedColumnDisplay, ValueDisplayDescriptor } from "./column-types"; +import { displayCellAdapters } from "./display-cell-adapters"; + +export type ValueRenderer> = ( + value: unknown, + row: TRow, +) => ReactNode; + +export interface ValueRendererContext { + /** Display environment resolved by the owning table, not by the shared dispatcher. */ + timeZone: string; + /** Optional, already-resolved display label policy for individual badge values. */ + resolveBadgeLabel?: (value: string) => string; +} + +export interface DisplayCellAdapter { + defaultAlign: "left" | "right"; + createRenderer>( + display: TypedColumnDisplay, + context: ValueRendererContext, + ): ValueRenderer; +} + +/** Read presentation metadata without constructing a renderer; unknown runtime kinds retain the text fallback. */ +export function getDisplayCellAdapter(type: ColumnCellType | undefined) { + return typeof type === "string" && Object.hasOwn(displayCellAdapters, type) + ? displayCellAdapters[type] + : displayCellAdapters.text; +} + +/** Keep keyed selection correlated with its descriptor and row-dependent options. */ +function createTypedValueRenderer, K extends ColumnCellType>( + type: K, + descriptor: TypedColumnDisplay, + context: ValueRendererContext, +): ValueRenderer { + const adapters: { [P in ColumnCellType]: DisplayCellAdapter

} = displayCellAdapters; + return adapters[type].createRenderer(descriptor, context); +} + +/** Prepare a built-in renderer without interpreting its settings or environment dependencies. */ +export function createValueRenderer>( + descriptor: ValueDisplayDescriptor, + context: ValueRendererContext, +): ValueRenderer { + if (typeof descriptor.type !== "string" || !Object.hasOwn(displayCellAdapters, descriptor.type)) { + return displayCellAdapters.text.createRenderer({ type: "text" }, context); + } + return createTypedValueRenderer(descriptor.type, descriptor, context); +} diff --git a/packages/core/src/components/internals/table-core/cell-session.test.ts b/packages/core/src/components/internals/table-core/cell-session.test.ts new file mode 100644 index 000000000..746d8f65f --- /dev/null +++ b/packages/core/src/components/internals/table-core/cell-session.test.ts @@ -0,0 +1,279 @@ +// @vitest-environment node +import { describe, expect, it, vi } from "vitest"; +import { createCellEditSession } from "./cell-session"; + +function deferred() { + let resolve!: () => void; + let reject!: (error: unknown) => void; + const promise = new Promise((success, failure) => { + resolve = success; + reject = failure; + }); + return { promise, resolve, reject }; +} + +async function settle(request: ReturnType, failure?: { error: unknown }) { + if (failure) request.reject(failure.error); + else request.resolve(); + await request.promise.catch(() => undefined); +} + +describe("React-independent cell edit sessions", () => { + it("separates stale-adoption revisions from explicit popup cancellation", () => { + const session = createCellEditSession(); + const cancellation = session.getCancellationRevision(); + const initial = session.getRevision(); + session.begin("Memo"); + session.change("Changed"); + expect(session.getRevision()).toBeGreaterThan(initial); + expect(session.getCancellationRevision()).toBe(cancellation); + session.cancel(); + expect(session.getCancellationRevision()).toBe(cancellation + 1); + }); + + it("caches its state and publishes adopted snapshots, not reads or no-ops", () => { + const session = createCellEditSession(); + const initial = session.getState(); + const listener = vi.fn(() => { + expect(session.getState()).toEqual({ status: "editing", draft: "Memo" }); + }); + const detach = session.subscribe(listener); + expect(session.getState()).toBe(initial); + expect(session.getFailure()).toBeUndefined(); + session.fail("No draft", "parse"); + const commit = vi.fn(); + expect(session.confirm(commit)).toBeUndefined(); + expect(commit).not.toHaveBeenCalled(); + expect(listener).not.toHaveBeenCalled(); + const begin = session.begin; + begin("Memo"); + const editing = session.getState(); + expect(editing).not.toBe(initial); + begin("Must not replace Memo"); + expect(session.getState()).toBe(editing); + expect(listener).toHaveBeenCalledTimes(1); + detach(); + detach(); + session.cancel(); + expect(listener).toHaveBeenCalledTimes(1); + }); + + it("retains a draft and its failure when a view detaches and resubscribes", () => { + const session = createCellEditSession(); + const firstView = vi.fn(); + const detach = session.subscribe(firstView); + session.change("-"); + session.fail("Not a number", "parse"); + const failed = session.getState(); + detach(); + const secondView = vi.fn(); + session.subscribe(secondView); + expect(session.getState()).toBe(failed); + expect(session.getFailure()).toBe(failed); + const commit = vi.fn(); + session.confirm(commit); + expect(commit).not.toHaveBeenCalled(); + session.change("2"); + session.confirm(commit); + expect(session.getState()).toEqual({ status: "idle" }); + expect(commit).toHaveBeenCalledTimes(1); + expect(firstView).toHaveBeenCalledTimes(2); + expect(secondView).toHaveBeenCalledTimes(3); + }); + + it("retains error dismissal without invalidating the edit and resets it for a new failure", () => { + const session = createCellEditSession(); + const error = new Error("Rejected"); + const check = () => { + throw error; + }; + session.change("Retained"); + session.confirm(check); + const failure = session.getFailure()!; + const revision = session.getRevision(); + const listener = vi.fn(); + const detach = session.subscribe(listener); + const dismissed = session.setErrorDetailsOpen(failure, false)!; + expect(dismissed.detailsDismissed).toBe(true); + expect(session.getFailure()).toBe(dismissed); + expect(session.getRevision()).toBe(revision); + expect(listener).toHaveBeenCalledTimes(1); + session.setErrorDetailsOpen(dismissed, false); + expect(listener).toHaveBeenCalledTimes(1); + detach(); + expect(session.getFailure()?.detailsDismissed).toBe(true); + const reopened = session.setErrorDetailsOpen(dismissed, true)!; + expect(reopened.detailsDismissed).toBe(false); + session.confirm(check); + const retried = session.getFailure()!; + expect(retried.error).toBe(error); + expect(retried.detailsDismissed).toBeUndefined(); + expect(session.setErrorDetailsOpen(failure, false)).toBeUndefined(); + expect(session.getFailure()).toBe(retried); + session.deactivate(); + expect(session.setErrorDetailsOpen(retried, false)).toBeUndefined(); + expect(session.getFailure()).toBe(retried); + }); + + it("uses the current listener set for each notification when subscriptions change", () => { + const session = createCellEditSession(); + const late = vi.fn(); + const second = vi.fn(); + let detachSecond!: () => void; + const first = vi.fn(() => { + detachSecond(); + session.subscribe(late); + }); + session.subscribe(first); + detachSecond = session.subscribe(second); + session.begin("Memo"); + expect(first).toHaveBeenCalledTimes(1); + expect(second).toHaveBeenCalledTimes(1); + expect(late).not.toHaveBeenCalled(); + session.change("Changed"); + expect(second).toHaveBeenCalledTimes(1); + expect(late).toHaveBeenCalledTimes(1); + }); + + it.each(["resolve", "reject"] as const)( + "does not cancel a request when its view disappears before a %s", + async (outcome) => { + const session = createCellEditSession(); + const request = deferred(); + const listener = vi.fn(); + const detach = session.subscribe(listener); + const complete = vi.fn(); + session.begin("Memo"); + session.confirm(() => request.promise, complete); + detach(); + const error = new Error("Save failed"); + await settle(request, outcome === "reject" ? { error } : undefined); + expect(session.getState()).toEqual( + outcome === "resolve" + ? { status: "idle" } + : { status: "failed", draft: "Memo", error, source: "commit" }, + ); + expect(complete).toHaveBeenCalledTimes(outcome === "resolve" ? 1 : 0); + expect(listener).toHaveBeenCalledTimes(2); + }, + ); + + it("keeps synchronous confirmation synchronous and preserves its void result", () => { + const session = createCellEditSession(); + session.begin("Memo"); + const complete = vi.fn(() => expect(session.getState()).toEqual({ status: "idle" })); + expect(session.confirm(() => false, complete)).toBeUndefined(); + expect(complete).toHaveBeenCalledTimes(1); + expect(session.getState()).toEqual({ status: "idle" }); + }); + + it("waits for a change check before committing and deduplicates confirmation", async () => { + const session = createCellEditSession(); + const check = deferred(); + const save = deferred(); + const commit = vi.fn(() => save.promise); + const duplicate = vi.fn(); + session.change("Memo", () => check.promise); + session.confirm(commit); + session.confirm(duplicate); + expect(commit).not.toHaveBeenCalled(); + await settle(check); + expect(commit).toHaveBeenCalledTimes(1); + expect(session.getState()).toEqual({ status: "confirming", draft: "Memo" }); + session.confirm(duplicate); + await settle(save); + expect(session.getState()).toEqual({ status: "idle" }); + expect(duplicate).not.toHaveBeenCalled(); + }); + + it.each(["check", "commit"] as const)( + "retains a rejected %s draft and retries only a commit failure", + async (phase) => { + const session = createCellEditSession(); + const request = deferred(); + session.change("Memo", phase === "check" ? () => request.promise : undefined); + const commit = vi.fn(() => (phase === "commit" ? request.promise : undefined)); + session.confirm(commit); + const error = new Error("Rejected"); + await settle(request, { error }); + expect(session.getState()).toEqual({ + status: "failed", + draft: "Memo", + error, + source: phase === "check" ? "change" : "commit", + }); + const retry = vi.fn(); + session.confirm(retry); + expect(retry).toHaveBeenCalledTimes(phase === "commit" ? 1 : 0); + if (phase === "check") session.change("Corrected"); + else expect(session.getState()).toEqual({ status: "idle" }); + }, + ); + + it.each(["cancel", "deactivate"] as const)( + "does not start a waiting commit after %s", + async (action) => { + const session = createCellEditSession(); + const check = deferred(); + const commit = vi.fn(); + session.change("Memo", () => check.promise); + session.confirm(commit); + session[action](); + const retained = session.getState(); + await settle(check); + expect(commit).not.toHaveBeenCalled(); + expect(session.getState()).toBe(retained); + }, + ); + + it.each(["check", "commit"] as const)( + "reactivates an invalidated %s with its draft intact for explicit retry", + async (phase) => { + const session = createCellEditSession(); + const request = deferred(); + const complete = vi.fn(); + const commit = vi.fn(() => (phase === "commit" ? request.promise : undefined)); + session.change("Memo", phase === "check" ? () => request.promise : undefined); + session.confirm(commit, complete); + session.deactivate(); + session.activate(true); + expect(session.getState()).toEqual({ status: "editing", draft: "Memo" }); + const retry = deferred(); + session.confirm(() => retry.promise); + await settle(request); + expect(session.getState()).toEqual({ status: "confirming", draft: "Memo" }); + expect(commit).toHaveBeenCalledTimes(phase === "commit" ? 1 : 0); + expect(complete).not.toHaveBeenCalled(); + await settle(retry); + expect(session.getState()).toEqual({ status: "idle" }); + }, + ); + + it("does not reset a live confirmation when an active owner activates again", async () => { + const session = createCellEditSession(); + const request = deferred(); + session.begin("Memo"); + session.confirm(() => request.promise); + const confirming = session.getState(); + session.activate(true); + expect(session.getState()).toBe(confirming); + await settle(request); + expect(session.getState()).toEqual({ status: "idle" }); + }); + + it("ignores retained commands after deactivation without notifying", () => { + const session = createCellEditSession(); + session.begin("Memo"); + const retained = session.getState(); + const listener = vi.fn(); + session.subscribe(listener); + session.deactivate(); + session.begin("Detached"); + session.change("Detached", listener); + session.fail("Detached", "parse"); + session.cancel(listener); + session.confirm(listener); + expect(session.getState()).toBe(retained); + expect(listener).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/core/src/components/internals/table-core/cell-session.ts b/packages/core/src/components/internals/table-core/cell-session.ts new file mode 100644 index 000000000..d5a88bf2d --- /dev/null +++ b/packages/core/src/components/internals/table-core/cell-session.ts @@ -0,0 +1,209 @@ +// Retain reachable session declarations in the bundle; package entrypoints do not export them. +/** A failure belongs to its draft, not to the control displaying it. */ +export interface CellEditFailure { + error: unknown; + source: "parse" | "change" | "commit"; + /** Retained owners keep dismissal with this failure, not with a mounted cell. */ + detailsDismissed?: boolean; +} + +/** The cached view of one logical edit; committed row values remain owned by the caller. */ +export type CellEditSessionState = + | { status: "idle" } + | { status: "editing"; draft: TDraft } + | { status: "confirming"; draft: TDraft } + | ({ status: "failed"; draft: TDraft } & CellEditFailure); + +function isPromiseLike(value: unknown): value is PromiseLike { + return typeof (value as PromiseLike | null | undefined)?.then === "function"; +} + +/** + * Owns one edit's draft, failure, and in-flight callback checks without React or row state. + * getState returns a cached snapshot suitable for useSyncExternalStore. A transition adopts + * that snapshot before notifying subscribers synchronously; reads do not notify. + * + * The caller owns the lifetime: detaching a subscriber leaves the edit intact, whereas + * deactivate invalidates pending callbacks and blocks commands. activate resumes the same + * draft with the caller's error-interception policy. Returned methods do not depend on this. + */ +export function createCellEditSession(interceptErrors = true) { + let state: CellEditSessionState = { status: "idle" }; + let revision = 0; + let cancellationRevision = 0; + let active = true; + let enabled = interceptErrors; + let pendingChange: Promise | null = null; + const listeners = new Set<() => void>(); + + function transition(next: CellEditSessionState) { + state = next; + // oxlint-disable-next-line unicorn/no-useless-spread -- Subscriptions can change during notification. + for (const listener of [...listeners]) listener(); + } + function invalidate() { + revision++; + pendingChange = null; + } + const isCurrent = (candidate: number) => active && revision === candidate; + + function begin(draft: TDraft) { + if (!active || state.status !== "idle") return; + invalidate(); + transition({ status: "editing", draft }); + } + + function change(draft: TDraft, callback?: () => unknown) { + if (!active) return; + invalidate(); + const candidate = revision; + transition({ status: "editing", draft }); + if (!callback) return; + if (!enabled) { + callback(); + return; + } + function reject(error: unknown) { + if (isCurrent(candidate)) transition({ status: "failed", draft, error, source: "change" }); + } + try { + const result = callback(); + if (isPromiseLike(result)) { + const pending = Promise.resolve(result).then( + () => { + if (isCurrent(candidate) && pendingChange === pending) pendingChange = null; + return true; + }, + (error: unknown) => { + if (isCurrent(candidate) && pendingChange === pending) pendingChange = null; + reject(error); + return false; + }, + ); + if (isCurrent(candidate)) pendingChange = pending; + } + } catch (error) { + reject(error); + } + } + + function discard() { + cancellationRevision++; + invalidate(); + transition({ status: "idle" }); + } + + /** Waits for an outstanding change check; repeated confirmation does not repeat callbacks. */ + function confirm(callback: () => unknown, onSuccess?: () => void) { + const current = state; + if ( + !active || + current.status === "idle" || + current.status === "confirming" || + (current.status === "failed" && current.source !== "commit") + ) + return; + if (!enabled) { + discard(); + onSuccess?.(); + callback(); + return; + } + const { draft } = current; + const candidate = revision; + const waiting = pendingChange; + transition({ status: "confirming", draft }); + const isConfirming = () => isCurrent(candidate) && state.status === "confirming"; + function complete() { + if (!isConfirming()) return; + transition({ status: "idle" }); + onSuccess?.(); + } + function reject(error: unknown) { + if (isConfirming()) transition({ status: "failed", draft, error, source: "commit" }); + } + function run() { + if (!isConfirming()) return; + try { + const result = callback(); + if (isPromiseLike(result)) { + void Promise.resolve(result).then(complete, reject); + return; + } + } catch (error) { + reject(error); + return; + } + complete(); + } + if (waiting) { + void waiting.then((valid) => { + if (valid) run(); + }); + } else run(); + } + + function fail(error: unknown, source: "parse") { + if (!active || state.status === "idle") return; + const { draft } = state; + invalidate(); + transition({ status: "failed", draft, error, source }); + } + + function cancel(callback?: () => unknown) { + if (!active) return; + discard(); + if (!callback) return; + if (!enabled) { + callback(); + return; + } + // Restoration failures cannot recreate an error for a draft that has been discarded. + try { + const result = callback(); + if (isPromiseLike(result)) void Promise.resolve(result).catch(() => {}); + } catch { + // There is no longer a draft to attach a restoration error to. + } + } + + return { + getRevision: () => revision, + /** Explicit discard also retires local popup/search state in retained editor controls. */ + getCancellationRevision: () => cancellationRevision, + getState: () => state, + getFailure: () => (state.status === "failed" ? state : undefined), + setErrorDetailsOpen(failure: CellEditFailure, open: boolean): CellEditFailure | undefined { + if (!active || state.status !== "failed" || state !== failure) return undefined; + if (!!state.detailsDismissed === !open) return state; + const next = { ...state, detailsDismissed: !open }; + transition(next); + return next; + }, + /** Registers a listener without invoking it; cleanup is idempotent and does not cancel. */ + subscribe(listener: () => void) { + listeners.add(listener); + return () => { + listeners.delete(listener); + }; + }, + begin, + change, + confirm, + fail, + cancel, + /** Resumes the retained draft; an invalidated confirmation requires an explicit retry. */ + activate(intercept: boolean) { + const resuming = !active; + enabled = intercept; + active = true; + if (resuming && state.status === "confirming") + transition({ status: "editing", draft: state.draft }); + }, + /** Invalidates async work without changing the retained draft or notifying subscribers. */ + deactivate() { + active = false; + invalidate(); + }, + }; +} diff --git a/packages/core/src/components/internals/table-core/column-types.test-d.ts b/packages/core/src/components/internals/table-core/column-types.test-d.ts new file mode 100644 index 000000000..542f0c0c0 --- /dev/null +++ b/packages/core/src/components/internals/table-core/column-types.test-d.ts @@ -0,0 +1,44 @@ +import { expectTypeOf, test } from "vitest"; +import type { Column, ColumnBase, TextCellEditOptions } from "@/components/data-table/types"; +import type { ValueDisplayDescriptor } from "./column-types"; + +type Row = { id: string; amount: number; status: string }; + +test("DataTable columns remain compatible with the neutral display descriptor", () => { + expectTypeOf>().toExtend>(); + expectTypeOf["width"]>().toEqualTypeOf(); + expectTypeOf["align"]>().toEqualTypeOf<"left" | "right" | undefined>(); + expectTypeOf["onValueCommitted"]>>().toEqualTypeOf< + (row: Row, value: string | null) => void + >(); +}); + +test("display descriptors retain the existing type/options contracts", () => { + const link: ValueDisplayDescriptor = { + type: "link", + typeOptions: { + href: (row) => { + expectTypeOf(row).toEqualTypeOf(); + return `/rows/${row.id}`; + }, + }, + }; + const money: ValueDisplayDescriptor = { + type: "money", + typeOptions: { currency: (row) => row.status }, + }; + // @ts-expect-error Links still require an href. + const missingHref: ValueDisplayDescriptor = { type: "link" }; + // @ts-expect-error Text columns do not accept typeOptions. + const textOptions: ValueDisplayDescriptor = { type: "text", typeOptions: {} }; + const numberOptions: ValueDisplayDescriptor = { + type: "number", + // @ts-expect-error Number columns do not accept currency options. + typeOptions: { currency: "USD" }, + }; + void link; + void money; + void missingHref; + void textOptions; + void numberOptions; +}); diff --git a/packages/core/src/components/internals/table-core/column-types.ts b/packages/core/src/components/internals/table-core/column-types.ts new file mode 100644 index 000000000..3d59e76a5 --- /dev/null +++ b/packages/core/src/components/internals/table-core/column-types.ts @@ -0,0 +1,91 @@ +import type { BadgeOptions } from "@/components/badge-list"; + +/** Built-in display renderers, independent of how a component obtains or edits a value. */ +export type ColumnCellType = "text" | "number" | "money" | "date" | "badge" | "link"; + +/** Options for `type: "number"` cells. */ +export interface NumberCellOptions { + /** Minimum decimal places. Default: `0`. */ + minDecimals?: number; + /** Maximum decimal places. Default: `minDecimals` (or `0`). */ + maxDecimals?: number; + /** BCP 47 locale tag. Defaults to the runtime locale. */ + locale?: string; +} + +/** Options for `type: "money"` cells. */ +export interface MoneyCellOptions> { + /** + * ISO 4217 currency code. Pass a string for a static currency or a function + * to read it from the row. Default: `"USD"`. + */ + currency?: string | ((row: TRow) => string); + /** + * Maximum decimals. Raises the cap above the currency default while keeping + * the minimum at the currency default (e.g. USD stays at ≥2, but a price + * column can show up to 4). + */ + maxDecimals?: number; + /** BCP 47 locale tag. Defaults to the runtime locale. */ + locale?: string; +} + +/** Options for `type: "date"` cells. */ +export interface DateCellOptions { + /** + * Format style. `"short"` → `Apr 9, 2026`; `"long"` → `April 9, 2026`; + * `"datetime"` → `Apr 9, 2026, 3:45 PM`. Default: `"short"`. + */ + dateFormat?: "short" | "long" | "datetime"; + /** BCP 47 locale tag. Defaults to the runtime locale. */ + locale?: string; +} + +/** Options for `type: "badge"` cells. */ +export interface BadgeCellOptions extends BadgeOptions { + /** Maximum number of badges to display before showing a "+N" overflow indicator */ + maxVisible?: number; +} + +/** Options for `type: "link"` cells. `href` is required. */ +export interface LinkCellOptions> { + /** + * Extracts the link target. Returning `null` / `undefined` renders the cell + * value as plain text instead of a link. + */ + href: (row: TRow) => string | null | undefined; +} + +/** Resolved presentation only: no accessor, edit choices, filters, or table state. */ +export type ValueDisplayDescriptor> = + | { type?: undefined; typeOptions?: never } + | { type: "text"; typeOptions?: never } + | { type: "number"; typeOptions?: NumberCellOptions } + | { type: "money"; typeOptions?: MoneyCellOptions } + | { type: "date"; typeOptions?: DateCellOptions } + | { type: "badge"; typeOptions?: BadgeCellOptions } + | { type: "link"; typeOptions: LinkCellOptions }; + +/** Values accepted by each built-in display renderer. */ +export interface ColumnDisplayValues { + text: string | number | boolean | bigint | null | undefined; + number: number | null | undefined; + money: number | null | undefined; + date: Date | string | number | null | undefined; + badge: string | string[] | number | boolean | null | undefined; + link: string | number | boolean | null | undefined; +} + +export type TypedColumnDisplay< + TRow extends Record, + K extends ColumnCellType, +> = Extract, { type: K }>; + +/** A display type must accept the value produced by its column's source. */ +export type ColumnDisplay, TValue> = + | { type?: undefined; typeOptions?: never } + | { + [K in ColumnCellType]: [TValue] extends [ColumnDisplayValues[K]] + ? TypedColumnDisplay + : never; + }[ColumnCellType]; diff --git a/packages/core/src/components/internals/table-core/display-cell-adapters.test.tsx b/packages/core/src/components/internals/table-core/display-cell-adapters.test.tsx new file mode 100644 index 000000000..ccd06acae --- /dev/null +++ b/packages/core/src/components/internals/table-core/display-cell-adapters.test.tsx @@ -0,0 +1,205 @@ +import type { ReactNode } from "react"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { cleanup, render, screen } from "@testing-library/react"; +import { MemoryRouter } from "react-router"; +import { createValueRenderer } from "./cell-renderers"; +import { displayCellAdapters } from "./display-cell-adapters"; +import type { ColumnCellType } from "./column-types"; + +const context = { timeZone: "America/New_York" }; + +afterEach(() => { + cleanup(); + vi.restoreAllMocks(); +}); + +const adapterCases: Record< + ColumnCellType, + { + adapter: { defaultAlign: "left" | "right" }; + align: "left" | "right"; + renderValue: () => ReactNode; + text: string; + href?: string; + } +> = { + text: { + adapter: displayCellAdapters.text, + align: "left", + renderValue: () => + displayCellAdapters.text.createRenderer({ type: "text" }, context)("Text", {}), + text: "Text", + }, + number: { + adapter: displayCellAdapters.number, + align: "right", + renderValue: () => + displayCellAdapters.number.createRenderer( + { type: "number", typeOptions: { locale: "en-US", minDecimals: 2, maxDecimals: 2 } }, + context, + )(12.5, {}), + text: "12.50", + }, + money: { + adapter: displayCellAdapters.money, + align: "right", + renderValue: () => + displayCellAdapters.money.createRenderer<{ currency: string }>( + { type: "money", typeOptions: { locale: "en-US", currency: (row) => row.currency } }, + context, + )(12.5, { currency: "EUR" }), + text: "€12.50", + }, + date: { + adapter: displayCellAdapters.date, + align: "left", + renderValue: () => + displayCellAdapters.date.createRenderer( + { type: "date", typeOptions: { locale: "en-US" } }, + context, + )("2026-10-09T00:00:00Z", {}), + text: "Oct 8, 2026", + }, + badge: { + adapter: displayCellAdapters.badge, + align: "left", + renderValue: () => + displayCellAdapters.badge.createRenderer( + { type: "badge", typeOptions: { badgeLabelMap: { open: "Open" } } }, + context, + )("open", {}), + text: "Open", + }, + link: { + adapter: displayCellAdapters.link, + align: "left", + renderValue: () => + displayCellAdapters.link.createRenderer<{ id: string }>( + { type: "link", typeOptions: { href: (row) => `/rows/${row.id}` } }, + context, + )("Resolved", { id: "A" }), + text: "Resolved", + href: "/rows/A", + }, +}; + +describe("display cell adapters", () => { + it.each(Object.entries(adapterCases))( + "pairs %s rendering with its default alignment", + (_kind, { adapter, align, renderValue, text, href }) => { + expect(adapter.defaultAlign).toBe(align); + render({renderValue()}); + expect(screen.getByText(text)).toBeDefined(); + if (href) expect(screen.getByRole("link").getAttribute("href")).toBe(href); + }, + ); + + it.each([undefined, { timeZone: "" }])( + "rejects date preparation without a timezone at runtime (%j)", + (invalidContext) => { + expect(() => + displayCellAdapters.date.createRenderer( + { type: "date" }, + // @ts-expect-error Exercise JavaScript configuration outside the typed contract. + invalidContext, + ), + ).toThrow("Date rendering requires a timezone."); + }, + ); +}); + +describe("neutral value rendering", () => { + it("renders the supplied value without looking up row properties or edit choices", () => { + const descriptor = { + type: "text" as const, + id: "status", + edit: { options: [{ value: "open", label: "Choice label" }] }, + }; + const renderer = createValueRenderer(descriptor, context); + expect(renderer("open", { status: "different" })).toBe("open"); + expect(renderer(false, { status: "different" })).toBe("✗"); + expect(createValueRenderer({}, context)({ count: 2 }, {})).toBe('{"count":2}'); + }); + + it("formats display precision without changing a supplied number", () => { + const value = 12.345; + const renderer = createValueRenderer( + { type: "number", typeOptions: { locale: "en-US", minDecimals: 2, maxDecimals: 2 } }, + context, + ); + render(<>{renderer(value, {})}); + expect(screen.getByText("12.35")).toBeDefined(); + expect(value).toBe(12.345); + }); + + it("resolves currency from each row and retains the invalid-currency fallback", () => { + const renderer = createValueRenderer<{ currency: string }>( + { type: "money", typeOptions: { locale: "en-US", currency: (row) => row.currency } }, + context, + ); + const view = render(<>{renderer(12.5, { currency: "EUR" })}); + expect(screen.getByText("€12.50")).toBeDefined(); + view.rerender(<>{renderer(12.5, { currency: "invalid currency" })}); + expect(screen.getByText("$12.50")).toBeDefined(); + }); + + it("applies only the explicitly supplied badge display policy", () => { + const descriptor = { type: "badge" as const, typeOptions: { badgeLabelMap: { open: "Open" } } }; + const normal = createValueRenderer(descriptor, context); + const resolved = createValueRenderer(descriptor, { + ...context, + resolveBadgeLabel: (value) => `Resolved ${value}`, + }); + const view = render(<>{normal("open", {})}); + expect(screen.getByText("Open")).toBeDefined(); + view.rerender(<>{resolved("open", {})}); + expect(screen.getByText("Resolved open")).toBeDefined(); + expect(screen.queryByText("Open")).toBeNull(); + }); + + it("renders links from the supplied label and row-dependent href, or plain text without href", () => { + const renderer = createValueRenderer<{ id?: string }>( + { type: "link", typeOptions: { href: (row) => (row.id ? `/rows/${row.id}` : null) } }, + context, + ); + const view = render({renderer("Resolved label", { id: "A" })}); + expect(screen.getByRole("link", { name: "Resolved label" }).getAttribute("href")).toBe( + "/rows/A", + ); + view.rerender({renderer("Resolved label", {})}); + expect(screen.queryByRole("link")).toBeNull(); + expect(screen.getByText("Resolved label")).toBeDefined(); + }); + + it("keeps independent date-only and zoned formatter caches across rows", () => { + const DateTimeFormat = Intl.DateTimeFormat; + const spy = vi.spyOn(Intl, "DateTimeFormat").mockImplementation(function (locale, options) { + return new DateTimeFormat(locale, options); + }); + const renderer = createValueRenderer( + { type: "date", typeOptions: { locale: "en-US" } }, + context, + ); + for (let index = 0; index < 3; index++) { + expect(renderer("2026-10-09", {})).toBe("Oct 9, 2026"); + expect(renderer("2026-10-09T00:00:00Z", {})).toBe("Oct 8, 2026"); + } + expect( + spy.mock.calls + .filter(([locale, options]) => locale === "en-US" && options?.month === "short") + .map(([, options]) => options?.timeZone), + ).toEqual(["UTC", "America/New_York"]); + }); + + it("preserves a skipped calendar date and placeholders without constructing invalid formatters", () => { + const renderer = createValueRenderer( + { type: "date", typeOptions: { locale: "en-US" } }, + { timeZone: "Pacific/Apia" }, + ); + expect(renderer("2011-12-30", {})).toBe("Dec 30, 2011"); + const view = render(<>{renderer("2026-02-30", {})}); + expect(screen.getByText("—")).toBeDefined(); + view.rerender(<>{createValueRenderer({ type: "badge" }, context)([null, ""], {})}); + expect(screen.getByText("—")).toBeDefined(); + }); +}); diff --git a/packages/core/src/components/internals/table-core/display-cell-adapters.tsx b/packages/core/src/components/internals/table-core/display-cell-adapters.tsx new file mode 100644 index 000000000..285aa1cb3 --- /dev/null +++ b/packages/core/src/components/internals/table-core/display-cell-adapters.tsx @@ -0,0 +1,224 @@ +import type { ReactNode } from "react"; +import { parseDate } from "@internationalized/date"; +import { Link } from "react-router"; +import { BadgeList, toValueArray } from "@/components/badge-list"; +import { normalizeTemporalFilterValue } from "@/lib/temporal-filter-values"; +import type { + BadgeCellOptions, + ColumnCellType, + DateCellOptions, + LinkCellOptions, + MoneyCellOptions, + NumberCellOptions, + TypedColumnDisplay, +} from "./column-types"; +import type { DisplayCellAdapter, ValueRenderer, ValueRendererContext } from "./cell-renderers"; + +const PLACEHOLDER = ( + +); + +function isEmpty(value: unknown): boolean { + return value == null || value === ""; +} + +function renderText(value: unknown): ReactNode { + switch (true) { + case isEmpty(value): + return PLACEHOLDER; + case typeof value === "boolean": + return value ? "✓" : "✗"; + case value instanceof Date: + return value.toLocaleDateString(); + case typeof value === "object": + return JSON.stringify(value); + default: + return String(value); + } +} + +function renderNumber(value: unknown, options: NumberCellOptions | undefined): ReactNode { + if (isEmpty(value)) return PLACEHOLDER; + const num = Number(value); + if (Number.isNaN(num)) return PLACEHOLDER; + const min = options?.minDecimals ?? 0; + const formatted = new Intl.NumberFormat(options?.locale, { + minimumFractionDigits: min, + maximumFractionDigits: options?.maxDecimals ?? min, + }).format(num); + return {formatted}; +} + +function renderMoney>( + value: unknown, + row: TRow, + options: MoneyCellOptions | undefined, +): ReactNode { + if (isEmpty(value)) return PLACEHOLDER; + const num = Number(value); + if (Number.isNaN(num)) return PLACEHOLDER; + const currency = + (typeof options?.currency === "function" ? options.currency(row) : options?.currency) || "USD"; + + // `maxDecimals` raises the cap above the currency default while retaining its minimum. + const formatOptions: Intl.NumberFormatOptions = { style: "currency", currency }; + if (options?.maxDecimals != null) formatOptions.maximumFractionDigits = options.maxDecimals; + let formatted: string; + try { + formatted = new Intl.NumberFormat(options?.locale, formatOptions).format(num); + } catch { + // Invalid currency codes retain the existing USD fallback. + formatted = new Intl.NumberFormat(options?.locale, { + style: "currency", + currency: "USD", + }).format(num); + } + return {formatted}; +} + +function resolveDateFormatOptions(format: string): Intl.DateTimeFormatOptions { + if (format === "long") return { month: "long", day: "numeric", year: "numeric" }; + if (format === "datetime") { + return { + month: "short", + day: "numeric", + year: "numeric", + hour: "numeric", + minute: "2-digit", + }; + } + return { month: "short", day: "numeric", year: "numeric" }; +} + +/** Bind date-only and datetime formatting to a timezone once, retaining independent formatter caches. */ +function createDateRenderer( + options: DateCellOptions | undefined, + timeZone: string, +): (value: unknown) => ReactNode { + const formatOptions = resolveDateFormatOptions(options?.dateFormat ?? "short"); + let dateOnlyFormatter: Intl.DateTimeFormat | undefined; + let datetimeFormatter: Intl.DateTimeFormat | undefined; + return (value) => { + if (isEmpty(value)) return PLACEHOLDER; + const dateOnly = typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value.trim()); + let date: Date; + if (dateOnly) { + // Calendar dates have no instant, even when a timezone skips an entire day. + try { + date = parseDate(value.trim()).toDate("UTC"); + } catch { + return PLACEHOLDER; + } + } else { + const normalized = normalizeTemporalFilterValue("datetime", value, timeZone); + if (!normalized) return PLACEHOLDER; + date = new Date(normalized); + } + const formatter = dateOnly + ? (dateOnlyFormatter ??= new Intl.DateTimeFormat(options?.locale, { + ...formatOptions, + timeZone: "UTC", + })) + : (datetimeFormatter ??= new Intl.DateTimeFormat(options?.locale, { + ...formatOptions, + timeZone, + })); + return formatter.format(date); + }; +} + +function renderBadge( + value: unknown, + options: BadgeCellOptions | undefined, + resolveLabel: ((value: string) => string) | undefined, +): ReactNode { + if (toValueArray(value).filter((item) => item != null && item !== "").length === 0) + return PLACEHOLDER; + return ( + + ); +} + +function renderLink>( + value: unknown, + row: TRow, + options: LinkCellOptions, +): ReactNode { + if (isEmpty(value)) return PLACEHOLDER; + const label = String(value); + const href = options.href(row); + if (!href) return label; + return ( + + {label} + + ); +} + +/** Each display kind owns its formatting, dependencies, and default presentation policy. */ +export const displayCellAdapters = { + text: { + defaultAlign: "left", + createRenderer: >( + _display: TypedColumnDisplay, + _context: ValueRendererContext, + ): ValueRenderer => renderText, + }, + number: { + defaultAlign: "right", + createRenderer: + >( + display: TypedColumnDisplay, + _context: ValueRendererContext, + ): ValueRenderer => + (value) => + renderNumber(value, display.typeOptions), + }, + money: { + defaultAlign: "right", + createRenderer: + >( + display: TypedColumnDisplay, + _context: ValueRendererContext, + ): ValueRenderer => + (value, row) => + renderMoney(value, row, display.typeOptions), + }, + date: { + defaultAlign: "left", + createRenderer: >( + display: TypedColumnDisplay, + context: ValueRendererContext, + ): ValueRenderer => { + if (!context?.timeZone) throw new Error("Date rendering requires a timezone."); + return createDateRenderer(display.typeOptions, context.timeZone); + }, + }, + badge: { + defaultAlign: "left", + createRenderer: + >( + display: TypedColumnDisplay, + context: ValueRendererContext, + ): ValueRenderer => + (value) => + renderBadge(value, display.typeOptions, context.resolveBadgeLabel), + }, + link: { + defaultAlign: "left", + createRenderer: + >( + display: TypedColumnDisplay, + _context: ValueRendererContext, + ): ValueRenderer => + (value, row) => + renderLink(value, row, display.typeOptions), + }, +} satisfies { [K in ColumnCellType]: DisplayCellAdapter }; diff --git a/packages/core/src/components/internals/table-core/editing/cell.test-d.ts b/packages/core/src/components/internals/table-core/editing/cell.test-d.ts new file mode 100644 index 000000000..e996ea977 --- /dev/null +++ b/packages/core/src/components/internals/table-core/editing/cell.test-d.ts @@ -0,0 +1,128 @@ +import type { ComponentProps } from "react"; +import { expectTypeOf, test } from "vitest"; +import { EditableCell, type EditableCellOwnerProps } from "./cell"; +import { choiceEditor } from "./choice"; +import { dateEditor } from "./date"; +import { numberEditor, textEditor } from "./typing"; +import type { CellEditorOptions, CellEditorOutput, CellEditorProps } from "./props"; + +declare const ownerProps: EditableCellOwnerProps; + +test("injected editors retain required options without a kind discriminator", () => { + type ChoiceOptions = CellEditorOptions; + type DateOptions = CellEditorOptions; + expectTypeOf().toEqualTypeOf< + readonly { value: string; label: string }[] + >(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf<"options" | "renderOption">(); + expectTypeOf().toEqualTypeOf< + "withTime" | "timeZone" | "minValue" | "maxValue" | "isDateUnavailable" + >(); + expectTypeOf, "timeZone">>().toEqualTypeOf(); + expectTypeOf>().toEqualTypeOf(); + + EditableCell({ + ...ownerProps, + editor: choiceEditor, + options: { + options: [{ value: "open", label: "Open" }], + renderOption: (value, label) => { + expectTypeOf(value).toEqualTypeOf(); + expectTypeOf(label).toEqualTypeOf(); + return label; + }, + }, + }); + EditableCell({ ...ownerProps, editor: dateEditor, options: { withTime: true, timeZone: "UTC" } }); + EditableCell({ ...ownerProps, editor: dateEditor, options: { timeZone: "UTC" } }); + EditableCell({ ...ownerProps, editor: textEditor, options: {} }); + EditableCell({ ...ownerProps, editor: numberEditor, options: {} }); +}); + +test("editor implementations expose their confirmed output types", () => { + expectTypeOf>().toEqualTypeOf(); + expectTypeOf>().toEqualTypeOf(); + expectTypeOf>().toEqualTypeOf(); + expectTypeOf>().toEqualTypeOf(); + expectTypeOf>().toEqualTypeOf>(); + expectTypeOf>().toEqualTypeOf(); + + const commitNumber: ComponentProps["commit"] = (value) => { + expectTypeOf(value).toEqualTypeOf(); + }; + commitNumber(12.5); + commitNumber(null); + // @ts-expect-error The numeric input cannot confirm text. + commitNumber("12.5"); + + const commitText: ComponentProps["commit"] = (value) => { + expectTypeOf(value).toEqualTypeOf(); + }; + commitText("text"); + commitText(null); + // @ts-expect-error The text input cannot confirm a numeric value. + commitText(12.5); +}); + +test("cell confirmation types are inferred only from the selected editor", () => { + EditableCell({ + ...ownerProps, + editor: numberEditor, + options: {}, + commit: (value) => { + expectTypeOf(value).toEqualTypeOf(); + }, + }); + EditableCell({ + ...ownerProps, + editor: choiceEditor, + options: { options: [] }, + commit: (value) => { + expectTypeOf(value).toEqualTypeOf(); + }, + }); + EditableCell({ + ...ownerProps, + editor: numberEditor, + options: {}, + // @ts-expect-error A callback cannot widen a number editor's output to text. + commit: (_value: string | null) => {}, + }); + EditableCell({ + ...ownerProps, + editor: numberEditor, + options: {}, + // @ts-expect-error A number editor can confirm null on clear. + commit: (_value: number) => {}, + }); + EditableCell({ + ...ownerProps, + editor: dateEditor, + options: { timeZone: "UTC" }, + // @ts-expect-error A callback cannot change the confirmed output of a date editor. + commit: (_value: number | null) => {}, + }); +}); + +test("options cannot widen or disagree with the injected editor", () => { + // @ts-expect-error Choice options remain required. + EditableCell({ ...ownerProps, editor: choiceEditor }); + // @ts-expect-error A choice editor requires its fixed choices. + EditableCell({ ...ownerProps, editor: choiceEditor, options: {} }); + // @ts-expect-error Date options cannot substitute for choice options. + EditableCell({ ...ownerProps, editor: choiceEditor, options: { withTime: true } }); + // @ts-expect-error Fixed candidates use options, not a second choices shape. + EditableCell({ ...ownerProps, editor: choiceEditor, options: { choices: [] } }); + // @ts-expect-error A date editor cannot receive choice options. + EditableCell({ ...ownerProps, editor: dateEditor, options: { timeZone: "UTC", options: [] } }); + // @ts-expect-error The date adapter must resolve its timezone before rendering. + EditableCell({ ...ownerProps, editor: dateEditor, options: { withTime: true } }); + // @ts-expect-error A timezone is not part of the generic cell contract. + EditableCell({ ...ownerProps, editor: numberEditor, options: {}, timeZone: "UTC" }); + // @ts-expect-error A number editor has no date options. + EditableCell({ ...ownerProps, editor: numberEditor, options: { withTime: true } }); + // @ts-expect-error Options describe the selected editor, not another kind. + EditableCell({ ...ownerProps, editor: textEditor, options: { type: "number" } }); +}); diff --git a/packages/core/src/components/internals/table-core/editing/cell.tsx b/packages/core/src/components/internals/table-core/editing/cell.tsx new file mode 100644 index 000000000..982f83ed7 --- /dev/null +++ b/packages/core/src/components/internals/table-core/editing/cell.tsx @@ -0,0 +1,78 @@ +import type { ComponentProps, ReactNode } from "react"; +import type { Table } from "@/components/table"; +import { EditableCellFrame } from "./shared"; +import type { CellEditor, CellEditorProps, CellEditorView } from "./props"; + +/** + * Table-owned values, callbacks, session lifetime, and cell presentation. + * Editor settings and render-time composition are supplied separately by EditableCell. + * + * @see CellEditorProps for the inherited input and confirmation contract. + */ +export type EditableCellOwnerProps = Omit< + CellEditorProps, + "children" | "options" | "valueLabel" +> & { + /** Owner-formatted adopted value, including custom content or null; an editor may supply a draft preview instead. */ + display: ReactNode; + /** Underlying table-cell props; the frame merges className and owns editing/error attributes and handlers. */ + cellProps: ComponentProps; + /** Ellipsizes the display preview without changing the value passed to the input. */ + truncate?: boolean; + /** Tooltip text for the resting display; suppressed during active editing or callback errors. */ + tooltipLabel?: string; +}; + +/** + * Shared boundary between table-owned data/presentation and an injected input editor. + * The cell composes the editor with its frame; it neither selects an editor kind nor owns row data. + * Options and confirmed output are inferred from editor alone, so settings and callbacks cannot widen its contract. + * + * @typeParam TOptions - Settings accepted by the selected editor, without a kind discriminator. + * @typeParam TOutput - Complete confirmed value type, including null when the editor can clear its value. + * @see EditableCellOwnerProps for owner-supplied values, callbacks, and presentation. + */ +export type EditableCellProps = EditableCellOwnerProps> & { + /** Concrete input implementation and its icon/preview policy; also the source of options and output types. */ + editor: CellEditor; + /** Required settings of this editor, such as fixed options or date-time mode; cannot select another editor kind. */ + options: NoInfer; +}; + +/** Owns cell presentation; the injected editor supplies input behavior without mirrored state. */ +export function EditableCell({ + editor, + options, + display, + cellProps, + truncate, + tooltipLabel, + ...props +}: EditableCellProps) { + const { labels, slotPrefix } = props; + const { Editor, icon, hideDisplay } = editor; + const renderEditor = ({ input, draftPreview, ...interaction }: CellEditorView) => ( + + {input} + + ); + return ( + + {renderEditor} + + ); +} diff --git a/packages/core/src/components/internals/table-core/editing/choice.tsx b/packages/core/src/components/internals/table-core/editing/choice.tsx new file mode 100644 index 000000000..cd631c3e5 --- /dev/null +++ b/packages/core/src/components/internals/table-core/editing/choice.tsx @@ -0,0 +1,403 @@ +import { + useMemo, + useRef, + useState, + type ComponentProps, + type FocusEvent, + type MouseEvent, + type ReactNode, + type TouchEvent, +} from "react"; +import { Combobox as BaseCombobox } from "@base-ui/react/combobox"; +import { ChevronDown } from "lucide-react"; +import { cn } from "@/lib/utils"; +import { isComposing } from "@/lib/is-composing"; +import { ComboboxParts } from "@/components/combobox"; +import { toTextValue } from "../input-values"; +import { useCellEditSession } from "./use-session"; +import { + CELL_ERROR_CLASS_NAME, + ICON_INPUT_CLASS_NAME, + INPUT_CLASS_NAME, + INPUT_DISPLAY, + useCellError, + useDraftStatus, + useNavigationRef, +} from "./shared"; +import type { CellEditor, CellEditorProps } from "./props"; + +/** One dropdown choice; `value: null` is "None". */ +interface Choice { + value: string | null; + label: string; +} + +type ChoiceDraft = Choice & { notified?: boolean }; + +// Case- and width-insensitive searching: full-width letters and half-width +// katakana match their usual forms. +const searchable = (text: string) => text.normalize("NFKC").toLocaleLowerCase().trim(); + +const isChoiceEqual = (a: Choice, b: Choice) => a.value === b.value; + +const choiceLabel = (choice: Choice) => choice.label; + +type ChoiceEditorOptions = { + options: readonly { value: string; label: string }[]; + renderOption?: (value: string, label: string) => ReactNode; +}; + +function ChoiceEditor({ + options: { options, renderOption }, + current, + allowClear = true, + change = () => undefined, + commit, + renderError, + labels, + interceptErrors = true, + session: external, + rowKey, + colKey, + label, + align, + navigation, + children, +}: CellEditorProps) { + const session = useCellEditSession(interceptErrors, external); + const { state } = session; + const { callbackError, containsErrorTarget } = useCellError( + { labels, renderError }, + state.status === "failed" ? state : undefined, + ); + const register = useNavigationRef(navigation, rowKey, colKey); + const value = toTextValue(current); + const shouldCommit = (next: string | null) => next !== value || (!!external && next === null); + const noneLabel = labels.none; + // Keyed on content: rebuilding columns must not reset the highlight mid-search. + const optionsKey = (options ?? []).map((c) => `${c.value}\u0000${c.label}`).join("\u0001"); + const items = useMemo( + () => [ + ...(allowClear ? [{ value: null, label: noneLabel }] : []), + ...(options ?? []).map((c) => ({ value: c.value, label: String(c.label) })), + ], + // eslint-disable-next-line react-hooks/exhaustive-deps -- `optionsKey` stands for `options`. + [optionsKey, noneLabel, allowClear], + ); + + const selected = items.find((item) => item.value === value) ?? null; + const [open, setOpen] = useState(false); + const [focused, setFocused] = useState(false); + const editing = state.status !== "idle"; + const activeChoice = state.status === "idle" ? selected : state.draft; + const draftStatus = useDraftStatus( + labels, + !!external, + activeChoice?.value !== value, + state.status, + ); + // The displayed search text is local while editing, even if consumer data changes. + const [query, setQuery] = useState(null); + // Keep the closing list filtered until its animation completes. + const [listQuery, setListQuery] = useState(null); + const highlightedRef = useRef(undefined); + const explicitHighlightRef = useRef(undefined); + const composingRef = useRef(false); + const selectOnMouseUpRef = useRef(false); + const from = { rowKey, colKey }; + const cancellation = session.getCancellationRevision(); + const [seenCancellation, setSeenCancellation] = useState(cancellation); + if (external && seenCancellation !== cancellation) { + setSeenCancellation(cancellation); + setOpen(false); + setQuery(null); + setListQuery(null); + highlightedRef.current = undefined; + explicitHighlightRef.current = undefined; + } + + const filtered = useMemo(() => { + const search = searchable(listQuery ?? ""); + if (!search) return items; + const rank = (item: Choice) => { + const text = searchable(item.label); + if (text === search) return 0; + return text.startsWith(search) ? 1 : 2; + }; + return ( + items + .filter((item) => item.value !== null && searchable(item.label).includes(search)) + // Sorting is stable, preserving the original order within each rank. + .toSorted((left, right) => rank(left) - rank(right)) + ); + }, [items, listQuery]); + + const startEditing = () => { + session.begin(selected ?? { value, label: value ?? noneLabel }); + setQuery(selected?.label ?? ""); + setListQuery(null); + highlightedRef.current = undefined; + explicitHighlightRef.current = undefined; + }; + + const closeEditor = () => { + setQuery(null); + explicitHighlightRef.current = undefined; + setOpen(false); + }; + + const cancelEditing = () => { + const active = session.getState(); + session.cancel( + active.status !== "idle" && active.draft.notified && active.draft.value !== value + ? () => change(value) + : undefined, + ); + closeEditor(); + }; + + const leaveEditor = () => { + const active = session.getState(); + if (active.status === "failed" || active.status === "confirming") closeEditor(); + else cancelEditing(); + }; + + const pick = (item: Choice) => { + const active = session.getState(); + if (active.status === "confirming" && active.draft.value === item.value) return; + session.change( + { ...item, notified: item.value !== value }, + item.value !== value ? () => change(item.value) : undefined, + ); + setQuery(item.label); + session.confirm(() => (shouldCommit(item.value) ? commit(item.value) : undefined), closeEditor); + }; + + const explicitCandidate = () => { + const item = explicitHighlightRef.current; + return item && filtered.includes(item) ? item : undefined; + }; + + const keyboardCandidate = () => { + const highlighted = highlightedRef.current; + return ( + explicitCandidate() ?? + (highlighted && filtered.includes(highlighted) ? highlighted : filtered[0]) + ); + }; + + const handleKeyDown: NonNullable["onKeyDown"]> = ( + event, + ) => { + if (isComposing(event.nativeEvent, composingRef.current)) { + event.preventBaseUIHandler(); + return; + } + switch (event.key) { + case "Enter": { + event.preventDefault(); + event.preventBaseUIHandler(); + const active = session.getState(); + if (active.status === "confirming") return; + if (!open) { + if (active.status === "failed" && active.source === "commit") { + session.confirm( + () => (shouldCommit(active.draft.value) ? commit(active.draft.value) : undefined), + closeEditor, + ); + return; + } + if (active.status === "idle") startEditing(); + setOpen(true); + return; + } + const item = keyboardCandidate(); + if (item) pick(item); + else leaveEditor(); + return; + } + case "Tab": { + event.preventBaseUIHandler(); + const item = + session.getState().status !== "idle" && open + ? (explicitCandidate() ?? + (searchable(listQuery ?? "") ? keyboardCandidate() : undefined)) + : undefined; + if (item) pick(item); + else leaveEditor(); + if (navigation?.move(from, event.shiftKey ? "prev" : "next")) event.preventDefault(); + return; + } + case "Escape": + if (session.getState().status === "idle" && !open) return; + event.preventDefault(); + event.stopPropagation(); + event.preventBaseUIHandler(); + cancelEditing(); + return; + } + }; + + const handleFocus = (event: FocusEvent) => { + const withinCell = focused || containsErrorTarget(event.relatedTarget); + setFocused(true); + if (withinCell) return; + if (session.getState().status === "idle") startEditing(); + event.currentTarget.select(); + }; + + const handleBlur = () => { + setFocused(false); + leaveEditor(); + }; + + const handleMouseDown = (event: MouseEvent) => { + if (event.button === 2 && session.getState().status === "idle") { + event.preventDefault(); + return; + } + if (session.getState().status === "idle") { + startEditing(); + setOpen(true); + } + if (!focused) selectOnMouseUpRef.current = true; + }; + + const handleMouseUp = (event: MouseEvent) => { + if (!selectOnMouseUpRef.current) return; + selectOnMouseUpRef.current = false; + event.preventDefault(); + }; + + const stopWhileEditing = (event: MouseEvent | TouchEvent) => { + if (session.getState().status !== "idle") event.stopPropagation(); + }; + + const renderChoice = (item: Choice) => { + if (item.value === null) + return {item.label}; + return renderOption ? renderOption(item.value, item.label) : item.label; + }; + + return children({ + editing, + callbackError, + onEditorLeave: handleBlur, + onEditorCancel: cancelEditing, + getFailure: session.getFailure, + setErrorDetailsOpen: external ? session.setErrorDetailsOpen : undefined, + draftStatus, + confirming: state.status === "confirming", + input: ( + + items={items} + filteredItems={filtered} + value={activeChoice} + onValueChange={(item, details) => { + if (details.reason === "item-press" && item) pick(item); + }} + inputValue={query ?? activeChoice?.label ?? ""} + onInputValueChange={(next, details) => { + if (details.reason === "input-change" || details.reason === "input-clear") { + const active = session.getState(); + session.change( + active.status === "idle" + ? (selected ?? { value, label: value ?? noneLabel }) + : active.draft, + ); + setQuery(next); + setListQuery(next); + explicitHighlightRef.current = undefined; + } + }} + open={open} + onOpenChange={(next, details) => { + if (next) { + if (session.getState().status === "idle") startEditing(); + setOpen(true); + if (details.reason !== "input-change") setListQuery(null); + return; + } + if ( + containsErrorTarget(details.event.target) || + ("relatedTarget" in details.event && + containsErrorTarget(details.event.relatedTarget as EventTarget | null)) + ) { + details.cancel(); + return; + } + // Clearing search text is not selection or cancellation. + if (details.reason === "input-clear") { + setOpen(false); + return; + } + if (details.reason === "escape-key") cancelEditing(); + else leaveEditor(); + }} + onOpenChangeComplete={(isOpen) => { + if (!isOpen) setListQuery(null); + }} + onItemHighlighted={(item, details) => { + // Hover is visual feedback, not a keyboard confirmation candidate. + if (details.reason === "pointer") return; + highlightedRef.current = item; + if (item && details.reason === "keyboard") explicitHighlightRef.current = item; + }} + autoHighlight + itemToStringLabel={choiceLabel} + isItemEqualToValue={isChoiceEqual} + > + { + composingRef.current = true; + }} + onCompositionEnd={() => { + composingRef.current = false; + }} + /> + {/* At least as wide as the cell, and wide enough that choices don't wrap. */} + + {labels.noMatches} + + {(item: Choice) => ( + + {renderChoice(item)} + + )} + + + + ), + }); +} + +export const choiceEditor: CellEditor = { + Editor: ChoiceEditor, + icon: , + hideDisplay: INPUT_DISPLAY, +}; diff --git a/packages/core/src/components/internals/table-core/editing/date.tsx b/packages/core/src/components/internals/table-core/editing/date.tsx new file mode 100644 index 000000000..1d29bd757 --- /dev/null +++ b/packages/core/src/components/internals/table-core/editing/date.tsx @@ -0,0 +1,287 @@ +import { useState, type KeyboardEvent } from "react"; +import { Popover } from "@base-ui/react/popover"; +import { CalendarDays } from "lucide-react"; +import type { CalendarDate } from "@internationalized/date"; +import { cn } from "@/lib/utils"; +import { Button } from "@/components/button"; +import { Calendar, type CalendarProps } from "@/components/calendar"; +import { Input } from "@/components/input"; +import { sameDate, toCalendarDate, toIsoDateTime, toTimeText } from "../input-values"; +import type { CellEditor, CellEditorNavigation, CellEditorProps } from "./props"; +import { useCellEditSession } from "./use-session"; +import { + OVERLAY_CLASS_NAME, + CELL_FOCUS_CLASS_NAME, + CELL_ERROR_CLASS_NAME, + POPUP_CLASS_NAME, + useCellError, + useDraftStatus, + useNavigationRef, +} from "./shared"; + +// Date cells: a transparent button over the cell's own display, with a pointer. +const TRIGGER_CLASS_NAME = cn( + OVERLAY_CLASS_NAME, + CELL_FOCUS_CLASS_NAME, + "astw:cursor-pointer", + "astw:data-popup-open:ring-2 astw:data-popup-open:ring-inset astw:data-popup-open:ring-primary", +); + +// Tab / Shift+Tab from a closed calendar moves between editable cells, the +// same way it does from a typing cell. +function tabBetweenCells( + event: KeyboardEvent, + open: boolean, + navigation: CellEditorNavigation | undefined, + from: { rowKey: string; colKey: string }, +) { + if (event.key !== "Tab" || open) return; + if (navigation?.move(from, event.shiftKey ? "prev" : "next")) event.preventDefault(); +} + +/** Incomplete date-time editor state, interpreted in the AppShell timezone. */ +export interface DateTimeDraft { + day: string | null; + time: string | null; +} + +type DateEditorOptions = { + withTime?: boolean; + /** Owner-resolved timezone for date/datetime conversion; not part of the common cell contract. */ + timeZone: string; +} & Pick; + +function DateEditor({ + options, + current, + allowClear = true, + valueLabel, + change = () => undefined, + commit, + renderError, + labels, + slotPrefix, + interceptErrors = true, + session: external, + rowKey, + colKey, + label, + navigation, + children, +}: CellEditorProps) { + const { withTime = false, timeZone, minValue, maxValue, isDateUnavailable } = options; + const session = useCellEditSession(interceptErrors, external); + const { state } = session; + const { callbackError, containsErrorTarget } = useCellError( + { labels, renderError }, + state.status === "failed" ? state : undefined, + ); + const register = useNavigationRef(navigation, rowKey, colKey); + const baseline: DateTimeDraft = { + day: toCalendarDate(current, timeZone)?.toString() ?? null, + time: toTimeText(current, timeZone) || null, + }; + const [open, setOpen] = useState(false); + const cancellation = session.getCancellationRevision(); + const [seenCancellation, setSeenCancellation] = useState(cancellation); + if (external && seenCancellation !== cancellation) { + setSeenCancellation(cancellation); + setOpen(false); + } + const differs = (a: DateTimeDraft, b: DateTimeDraft) => + a.day !== b.day || (withTime && a.time !== b.time); + const notifyDraft = (next: DateTimeDraft) => change(withTime ? { ...next } : next.day); + const setDraft = (next: DateTimeDraft) => { + const active = session.getState(); + const previous = active.status === "idle" ? baseline : active.draft; + if (!differs(previous, next)) { + session.begin(next); + return; + } + session.change(next, () => notifyDraft(next)); + }; + const cancelEditing = () => { + const active = session.getState(); + session.cancel( + active.status !== "idle" && differs(active.draft, baseline) + ? () => notifyDraft(baseline) + : undefined, + ); + setOpen(false); + }; + const finish = (next: string | null) => { + session.confirm( + () => { + if (sameDate(next, current, withTime, timeZone) && (!external || next !== null)) return; + return commit(next); + }, + () => setOpen(false), + ); + }; + const activeDraft = state.status === "idle" ? baseline : state.draft; + const draftStatus = useDraftStatus( + labels, + !!external, + differs(activeDraft, baseline), + state.status, + ); + const pickedDay = toCalendarDate(activeDraft.day, timeZone); + const dayAllowed = + pickedDay && + (!minValue || pickedDay.compare(minValue) >= 0) && + (!maxValue || pickedDay.compare(maxValue) <= 0) && + !isDateUnavailable?.(pickedDay); + const timestamp = + withTime && dayAllowed && activeDraft.time + ? toIsoDateTime(pickedDay, activeDraft.time, timeZone) + : undefined; + const draftDisplay = withTime + ? `${activeDraft.day ?? "—"} ${activeDraft.time ?? "—"}` + : (activeDraft.day ?? "—"); + const draftPreview = state.status === "idle" ? undefined : draftDisplay; + // The trigger names the date hidden in the cell's visual preview. + const accessibleValue = draftPreview ?? valueLabel; + const accessibleName = accessibleValue !== undefined ? `${label}, ${accessibleValue}` : label; + + const handleOpenChange = (next: boolean, details?: Popover.Root.ChangeEventDetails) => { + if ( + !next && + details && + (containsErrorTarget(details.event.target) || + ("relatedTarget" in details.event && + containsErrorTarget(details.event.relatedTarget as EventTarget | null))) + ) { + details.cancel(); + return; + } + if (next) { + session.begin(baseline); + } else { + const active = session.getState(); + if ( + details?.reason === "escape-key" || + (active.status !== "failed" && active.status !== "confirming") + ) { + cancelEditing(); + return; + } + } + setOpen(next); + }; + + const handlePick = (day: CalendarDate) => { + const active = session.getState(); + setDraft({ ...(active.status === "idle" ? baseline : active.draft), day: day.toString() }); + if (!withTime) finish(day.toString()); + }; + + return children({ + editing: open, + callbackError, + onEditorCancel: cancelEditing, + getFailure: session.getFailure, + setErrorDetailsOpen: external ? session.setErrorDetailsOpen : undefined, + draftStatus, + confirming: state.status === "confirming", + draftPreview, + input: ( + + { + if (event.key === "Escape" && !open && session.getState().status !== "idle") { + event.preventDefault(); + event.stopPropagation(); + cancelEditing(); + return; + } + if (event.key === "ArrowDown" && !open) { + event.preventDefault(); + handleOpenChange(true); + return; + } + tabBetweenCells(event, open, navigation, { rowKey, colKey }); + }} + /> + + + event.stopPropagation()} + onTouchStart={(event) => event.stopPropagation()} + > + + {withTime && ( + + setDraft({ + ...activeDraft, + time: event.target.value || null, + }) + } + className="astw:h-8 astw:text-body-md" + /> + )} + {(allowClear || withTime) && ( +

+ {allowClear && ( + + )} + {withTime && ( + + )} +
+ )} + + + + + ), + }); +} + +export const dateEditor: CellEditor = { + Editor: DateEditor, + icon: , +}; diff --git a/packages/core/src/components/internals/table-core/editing/editor.test.tsx b/packages/core/src/components/internals/table-core/editing/editor.test.tsx new file mode 100644 index 000000000..95ee276ec --- /dev/null +++ b/packages/core/src/components/internals/table-core/editing/editor.test.tsx @@ -0,0 +1,189 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { act, cleanup, fireEvent, render, screen } from "@testing-library/react"; +import { Table } from "@/components/table"; +import { createCellEditSession } from "../cell-session"; +import { EditableCell } from "./cell"; +import { numberEditor } from "./typing"; +import { choiceEditor } from "./choice"; +import { dateEditor } from "./date"; +import type { CellEditor, CellEditorLabels } from "./props"; + +afterEach(cleanup); + +const labels: CellEditorLabels = { + notANumber: "Not a number", + revertHint: "Press Escape to revert", + callbackError: "Could not confirm", + errorHint: "Check the value", + showError: "Show error", + errorDialog: "Cell error", + closeError: "Close error", + none: "None", + noMatches: "No matches", + chooseTime: "Time", + clear: "Clear", + done: "Done", +}; + +describe("editor composition", () => { + it("renders and confirms a typing control without cell display or table props", () => { + const commit = vi.fn(); + const { container } = render( + + {({ input }) =>
{input}
} +
, + ); + expect(container.querySelector("td")).toBeNull(); + expect(container.querySelector("section > input")).not.toBeNull(); + const input = screen.getByRole("textbox", { name: "Value" }); + fireEvent.focus(input); + fireEvent.change(input, { target: { value: "12.50" } }); + fireEvent.keyDown(input, { key: "Enter" }); + expect(commit).not.toHaveBeenCalled(); + fireEvent.change(input, { target: { value: "1,5" } }); + fireEvent.keyDown(input, { key: "Enter" }); + expect(input.getAttribute("aria-invalid")).toBe("true"); + expect(commit).not.toHaveBeenCalled(); + fireEvent.change(input, { target: { value: "14.5" } }); + fireEvent.keyDown(input, { key: "Enter" }); + expect(commit).toHaveBeenCalledWith(14.5); + fireEvent.change(input, { target: { value: "" } }); + fireEvent.keyDown(input, { key: "Enter" }); + expect(commit).toHaveBeenCalledWith(null); + }); + + it("uses the injected choice editor's icon and preview visibility", () => { + render( + + + + + + + , + ); + const cell = screen.getByRole("cell"); + const input = screen.getByRole("combobox", { name: "Choice" }); + const preview = cell.firstElementChild!; + expect(cell.querySelector(".lucide-chevron-down")).not.toBeNull(); + expect(preview.textContent).toBe("Formatted choice"); + expect(preview.className).toContain("astw:forced-colors:invisible"); + expect(preview.className.split(" ")).not.toContain("astw:invisible"); + fireEvent.focus(input); + expect(preview.className.split(" ")).toContain("astw:invisible"); + }); + + it("renders an injected editor without a registry entry", () => { + const commit = vi.fn(); + const editor: CellEditor<{ confirmed: string }, string> = { + Editor: ({ children, options, label, valueLabel, commit: confirm }) => + children({ + input: ( + + ), + editing: false, + confirming: false, + onEditorCancel: () => {}, + getFailure: () => undefined, + }), + }; + render( + + + + + + + , + ); + const button = screen.getByRole("button", { name: "Injected" }); + expect(button.textContent).toBe("Formatted: Changed"); + fireEvent.click(button); + expect(commit).toHaveBeenCalledWith("Changed"); + expect(screen.getByRole("cell").hasAttribute("data-editable")).toBe(true); + }); + + it.each(["confirming", "failed"] as const)( + "keeps a retained %s date preview visible with the calendar closed", + (status) => { + const session = createCellEditSession(); + render( + + + + + + + , + ); + const cell = screen.getByRole("cell"); + expect(screen.getByRole("button", { name: "Date, Formatted date" }).parentElement).toBe(cell); + act(() => { + session.begin({ day: "2026-10-20", time: null }); + session.confirm(() => { + if (status === "failed") throw new Error("Rejected"); + return new Promise(() => {}); + }); + }); + expect(cell.textContent).toContain("2026-10-20"); + expect(screen.getByRole("button", { name: "Date, 2026-10-20" }).parentElement).toBe(cell); + expect(document.querySelector('[data-slot="test-cell-calendar"]')).toBeNull(); + expect(cell.getAttribute("aria-busy")).toBe(status === "confirming" ? "true" : null); + act(() => session.cancel()); + expect(cell.textContent).toContain("Formatted date"); + expect(screen.getByRole("button", { name: "Date, Formatted date" })).toBeDefined(); + }, + ); +}); diff --git a/packages/core/src/components/internals/table-core/editing/error-description.test.tsx b/packages/core/src/components/internals/table-core/editing/error-description.test.tsx new file mode 100644 index 000000000..3c9fe4237 --- /dev/null +++ b/packages/core/src/components/internals/table-core/editing/error-description.test.tsx @@ -0,0 +1,130 @@ +import type { ReactNode } from "react"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { cleanup, fireEvent, render, screen } from "@testing-library/react"; +import { Table } from "@/components/table"; +import { CellEditError } from "../cell-edit-error"; +import { createCellEditSession } from "../cell-session"; +import { EditableCell, type EditableCellOwnerProps } from "./cell"; +import { choiceEditor } from "./choice"; +import { dateEditor } from "./date"; +import { numberEditor, textEditor } from "./typing"; +import type { CellEditorLabels } from "./props"; + +afterEach(cleanup); + +const labels: CellEditorLabels = { + notANumber: "Enter a number", + revertHint: "Esc to revert", + callbackError: "Could not confirm", + errorHint: "Alt+ArrowDown for details", + showError: "Show error", + errorDialog: "Cell error", + closeError: "Close error", + none: "None", + noMatches: "No matches", + chooseTime: "Time", + clear: "Clear", + done: "Done", +}; + +const messages = [ + { message: "Enter a quantity", hint: "Esc to revert" }, + { message: "Enter a quantity.", hint: "Esc to revert" }, + { message: "数量を入力してください", hint: "Escで元に戻す" }, + { message: "数量を入力してください。", hint: "Escで元に戻す" }, +]; + +function expectDescriptions(control: Element, message: string, hint: string) { + const ids = control.getAttribute("aria-describedby")!.split(/\s+/); + expect(ids).toHaveLength(2); + expect(new Set(ids).size).toBe(2); + const elements = ids.map((id) => document.getElementById(id)); + expect(elements.every((element) => element?.classList.contains("astw:sr-only"))).toBe(true); + expect(elements.map((element) => element?.textContent)).toEqual([message, hint]); +} + +function renderCell(cell: ReactNode) { + return render( + + + {cell} + + , + ); +} + +describe.each(["text", "number", "choice", "date"] as const)( + "%s callback error descriptions", + (kind) => { + it.each(messages)("keeps '$message' separate from its hint", ({ message, hint }) => { + const session = createCellEditSession(); + let draft: unknown = "Changed"; + if (kind === "choice") draft = { value: "changed", label: "Changed" }; + if (kind === "date") draft = { day: "2026-12-02", time: null }; + session.begin(draft); + session.confirm(() => { + throw new CellEditError(message); + }); + const props: EditableCellOwnerProps = { + current: "Initial", + display: "Initial", + cellProps: {}, + commit: vi.fn(), + labels: { ...labels, errorHint: hint }, + session, + slotPrefix: "test", + rowKey: "A", + colKey: "value", + label: "Value", + align: "left", + }; + let cell; + if (kind === "choice") + cell = ( + + ); + else if (kind === "date") + cell = ; + else if (kind === "number") + cell = ; + else cell = ; + renderCell(cell); + const control = screen.getByRole("cell").querySelector("input, button")!; + expect(control.getAttribute("aria-invalid")).toBe("true"); + expectDescriptions(control, message, hint); + expect(control.getAttribute("aria-keyshortcuts")).toBe("Alt+ArrowDown"); + }); + }, +); + +it.each(messages)( + "keeps numeric parse message '$message' separate from its hint", + ({ message, hint }) => { + renderCell( + , + ); + const control = screen.getByRole("textbox", { name: "Quantity" }); + fireEvent.focus(control); + fireEvent.change(control, { target: { value: "-" } }); + fireEvent.keyDown(control, { key: "Enter" }); + expect(control.getAttribute("aria-invalid")).toBe("true"); + expectDescriptions(control, message, hint); + }, +); diff --git a/packages/core/src/components/internals/table-core/editing/props.ts b/packages/core/src/components/internals/table-core/editing/props.ts new file mode 100644 index 000000000..091574b23 --- /dev/null +++ b/packages/core/src/components/internals/table-core/editing/props.ts @@ -0,0 +1,133 @@ +import type { ReactNode, RefObject } from "react"; +import type { CellEditFailure, createCellEditSession } from "../cell-session"; + +/** Localized by the table owner, including names scoped to the current cell. */ +export interface CellEditorLabels { + notANumber: string; + revertHint: string; + callbackError: string; + errorHint: string; + showError: string; + errorDialog: string; + closeError: string; + none: string; + noMatches: string; + chooseTime: string; + clear: string; + done: string; + /** Optional presentation for document-owned sessions; omitted by collection-owned cells. */ + unconfirmed?: string; + confirming?: string; +} + +/** Optional owner-controlled Tab navigation; omitted tables use native Tab order. */ +export interface CellEditorNavigation { + register: (rowKey: string, colKey: string, element: HTMLElement) => () => void; + move: (from: { rowKey: string; colKey: string }, direction: "next" | "prev") => boolean; +} + +export interface CellErrorUI { + failure: CellEditFailure; + id: string; + hintId: string; + message: string; + content: ReactNode; + triggerRef: RefObject; + popupRef: RefObject; + containsTarget: (target: EventTarget | null) => boolean; +} + +/** Input behavior passed to the cell's frame during the same render, without mirrored state. */ +export interface CellEditorView { + input: ReactNode; + editing: boolean; + confirming: boolean; + callbackError?: CellErrorUI; + onEditorLeave?: () => void; + onEditorCancel: () => void; + getFailure: () => CellEditFailure | undefined; + setErrorDetailsOpen?: (failure: CellEditFailure, open: boolean) => CellEditFailure | undefined; + draftStatus?: { + id: string; + message: string; + confirming: boolean; + /** Suppress status tooltips and hide the unconfirmed marker while the cell has focus. */ + quiet?: boolean; + }; + /** Date input preview; column formatting remains owned by the cell. */ + draftPreview?: string; +} + +/** Input behavior and presentation policy injected into a cell, independent of editor kinds. */ +export interface CellEditor { + Editor: (props: CellEditorProps) => ReactNode; + icon?: ReactNode; + hideDisplay?: { + idle?: "focused" | "forced-colors"; + editing?: "focused" | "forced-colors"; + }; +} + +/** Infer the contract from its implementation rather than maintaining a separate editor map. */ +export type CellEditorOptions = + TEditor extends CellEditor ? TOptions : never; +export type CellEditorOutput = + TEditor extends CellEditor ? TOutput : never; + +/** + * Input and draft behavior shared by concrete editors; cell presentation and row adoption stay with the owner. + * Draft notifications need not have the confirmed output's shape: numeric drafts, for example, remain raw text. + * + * @typeParam TOptions - Settings consumed by this input implementation. + * @typeParam TOutput - Parsed value passed to commit, including any supported clear value. + */ +export interface CellEditorProps { + /** Concrete input settings, without an editor-kind discriminator. */ + options: TOptions; + /** Latest owner-adopted value, not the local draft; normalized by the selected editor. */ + current: unknown; + /** Whether explicit Clear/None controls are available. Defaults to true. */ + allowClear?: boolean; + /** + * Optional draft/restoration notification; its editor-specific payload may be unparsed. + * This is not a request to adopt a confirmed value. Restoration errors after cancellation are ignored + * when error interception is enabled. + */ + change?: (draft: unknown) => unknown; + /** + * Confirms a changed, parsed value; the owner decides whether and how to adopt it. + * With error interception enabled, a throw or rejected promise retains the draft for retry. + * A callback's return value is not adopted as cell data. + */ + commit: (value: TOutput) => unknown; + /** Custom, user-safe callback-error content; parsing feedback remains input-owned. */ + renderError?: (error: unknown) => ReactNode; + /** + * Whether a local session retains callback failures (default true); false uses eager, caller-owned error handling. + * An external session's owner configures its error policy instead. + */ + interceptErrors?: boolean; + /** + * Optional owner-retained draft/failure session across view remounts; the owner manages activation and disposal. + * Omit for a local session that deactivates on unmount. An active draft must keep the same editor-specific shape. + */ + session?: ReturnType>; + /** Owner-localized input messages, hints, and accessible error-control labels. */ + labels: CellEditorLabels; + /** Owner namespace for generated data-slot attributes, such as data-table or line-items. */ + slotPrefix: string; + /** Stable logical row identity for optional focus navigation, rather than a row index. */ + rowKey: string; + /** Stable display-column identity for optional focus navigation; need not equal a row property key. */ + colKey: string; + /** Accessible name of the input; some controls append the formatted or draft value. */ + label: string; + /** Input text alignment; the owner supplies matching alignment for the table cell. */ + align: "left" | "center" | "right"; + /** Optional table-managed focus registration and Tab movement; omitted controls use the native Tab order. */ + navigation?: CellEditorNavigation; + /** Formatted text for accessible control names; EditableCell derives it only when display is a string. */ + valueLabel?: string; + /** Render-time composition of the input and interaction state, not a state-change notification. */ + children: (view: CellEditorView) => ReactNode; +} diff --git a/packages/core/src/components/internals/table-core/editing/shared.tsx b/packages/core/src/components/internals/table-core/editing/shared.tsx new file mode 100644 index 000000000..2f83ac2dd --- /dev/null +++ b/packages/core/src/components/internals/table-core/editing/shared.tsx @@ -0,0 +1,450 @@ +import { + useCallback, + useId, + useLayoutEffect, + useRef, + useState, + type ComponentProps, + type ReactNode, +} from "react"; +import { Popover } from "@base-ui/react/popover"; +import { CircleAlert, X } from "lucide-react"; +import { cn } from "@/lib/utils"; +import { Button } from "@/components/button"; +import { Spinner } from "@/components/spinner"; +import { Table } from "@/components/table"; +import { Tooltip } from "@/components/tooltip"; +import { CellEditError } from "../cell-edit-error"; +import type { CellEditFailure } from "../cell-session"; +import type { + CellEditorLabels, + CellEditorNavigation, + CellEditorProps, + CellEditorView, + CellErrorUI, +} from "./props"; + +/** + * Room for the icon a dropdown or date cell shows at its right edge (a chevron + * or a calendar; 14px plus a gap), so a value ends — or truncates — before it + * instead of running underneath. Read-only cells of the same column keep it + * too, so the column's width doesn't change as rows become editable or not. + * + * @internal + */ +export const ICON_SPACE_CLASS_NAME = "astw:pr-5"; + +export const INPUT_DISPLAY = { + /** Hide the preview only where forced colors make resting input text visible. */ + idle: "forced-colors", + /** Retain the preview's layout space while the input shows its draft. */ + editing: "focused", +} as const; + +// Editors cover the whole cell, end to end, instead of taking part in layout, +// so a cell becoming editable — or being edited — never changes row height or +// column width. They inherit the cell's padding (they're its direct children), +// so their text lines up exactly with the cell's own display underneath. +export const OVERLAY_CLASS_NAME = + "astw:absolute astw:inset-0 astw:h-full astw:w-full astw:p-[inherit] astw:rounded-none astw:border-0 astw:shadow-none astw:bg-transparent astw:dark:bg-transparent"; + +// Spreadsheet-style: the cell being edited outlines its edges (an inset ring, +// so it never spills onto neighbouring cells). +export const CELL_FOCUS_CLASS_NAME = cn( + "astw:outline-none astw:focus:ring-2 astw:focus:ring-inset astw:focus:ring-primary", + "astw:focus-visible:ring-2 astw:focus-visible:ring-inset astw:focus-visible:ring-primary", +); + +// Parsing and callback errors share the cell's error outline. +export const CELL_ERROR_CLASS_NAME = + "astw:ring-[1.5px] astw:ring-inset astw:ring-danger-solid astw:focus:ring-[1.5px] astw:focus:ring-danger-solid astw:focus-visible:ring-[1.5px] astw:focus-visible:ring-danger-solid"; + +// An editable cell says so at rest with a subtle tint instead of an icon. It's +// a background *image* layered over whatever colour the cell already has (the +// row's hover / selected fade, a pinned cell's opaque card), so it never +// replaces them and stays a step darker than its read-only neighbours. The +// cell being edited drops it: an untinted cell with a ring reads as "active". +// (Written out in full: Tailwind only generates classes it finds as literals.) +const EDITABLE_CELL_CLASS_NAME = cn( + "astw:[background-image:linear-gradient(color-mix(in_srgb,var(--foreground)_4%,transparent),color-mix(in_srgb,var(--foreground)_4%,transparent))]", + "astw:hover:[background-image:linear-gradient(color-mix(in_srgb,var(--foreground)_7%,transparent),color-mix(in_srgb,var(--foreground)_7%,transparent))]", + "astw:focus-within:[background-image:none]", +); + +// Text, number and dropdown cells are typed into: the whole cell shows a text +// cursor. +export const INPUT_CLASS_NAME = cn( + OVERLAY_CLASS_NAME, + CELL_FOCUS_CLASS_NAME, + "astw:text-body-md astw:cursor-text", +); + +// A dropdown's text stops before its chevron. +export const ICON_INPUT_CLASS_NAME = "astw:pr-7 astw:[td:last-child>&]:pr-11"; + +// The icon that says how a cell is edited: shown while the cell is hovered or +// being edited (the cell's tint says it's editable at rest). +// Decoration only: a click anywhere in the cell goes to the editor underneath. +const CELL_ICON_CLASS_NAME = cn( + "astw:pointer-events-none astw:absolute astw:inset-y-0 astw:right-2 astw:flex astw:items-center astw:[td:last-child>&]:right-6", + "astw:text-muted-foreground astw:opacity-0 astw:transition-opacity", + "astw:group-hover/cell:opacity-30 astw:group-focus-within/cell:opacity-30", + "astw:[&_svg]:size-3.5", +); + +export const POPUP_CLASS_NAME = cn( + "astw:bg-popover astw:text-popover-foreground astw:z-(--z-portal) astw:flex astw:flex-col astw:gap-3 astw:rounded-md astw:border astw:border-border astw:p-3 astw:shadow-md", + "astw:animate-in astw:fade-in-0 astw:zoom-in-95 astw:data-ending-style:animate-out astw:data-ending-style:fade-out-0 astw:data-ending-style:zoom-out-95", +); + +// The standard popover body: the alert icon makes it read as an error rather +// than a tooltip. +function DefaultCellErrorContent({ message }: { message: string }) { + return ( +
+ {/* One line-height tall, so the icon centres on the first line of text. */} + + +

{message}

+
+ ); +} + +export function useCellError( + { labels, renderError }: Pick, "labels" | "renderError">, + failure: CellEditFailure | undefined, +) { + const errorId = useId(); + const triggerRef = useRef(null); + const popupRef = useRef(null); + const containsErrorTarget = (target: EventTarget | null) => + target instanceof Node && + !!(triggerRef.current?.contains(target) || popupRef.current?.contains(target)); + const message = + failure?.error instanceof CellEditError && failure.error.message + ? failure.error.message + : labels.callbackError; + const callbackError: CellErrorUI | undefined = + failure && failure.source !== "parse" + ? { + failure, + id: errorId, + hintId: `${errorId}-hint`, + message: renderError ? labels.callbackError : message, + content: renderError ? ( + renderError(failure.error) + ) : ( + + ), + triggerRef, + popupRef, + containsTarget: containsErrorTarget, + } + : undefined; + return { callbackError, containsErrorTarget }; +} + +/** Describe a changed document draft without adding layout space or a focus target. */ +export function useDraftStatus( + labels: CellEditorLabels, + retained: boolean, + changed: boolean, + status: "idle" | "editing" | "confirming" | "failed", +): CellEditorView["draftStatus"] { + const id = useId(); + if ( + !retained || + status === "idle" || + status === "failed" || + (!changed && status !== "confirming") + ) + return undefined; + const confirming = status === "confirming"; + const message = confirming ? labels.confirming : labels.unconfirmed; + return message === undefined ? undefined : { id, message, confirming }; +} + +/** + * Registers the cell's focusable element with the table's Tab + * navigation. Unregisters on every detach instead of returning a ref cleanup: + * `Input` and `Combobox.Input` merge refs with a plain callback that calls ours + * with `null` and drops any cleanup we return. + */ +export function useNavigationRef( + navigation: CellEditorNavigation | undefined, + rowKey: string, + colKey: string, +) { + const unregisterRef = useRef<(() => void) | null>(null); + return useCallback( + (element: T | null) => { + unregisterRef.current?.(); + unregisterRef.current = element + ? (navigation?.register(rowKey, colKey, element) ?? null) + : null; + }, + [navigation, rowKey, colKey], + ); +} + +export function EditableCellFrame({ + labels, + slotPrefix, + cellProps, + display, + truncate, + hideDisplay, + icon, + tooltipLabel, + editing, + callbackError, + onEditorLeave, + onEditorCancel, + getFailure, + setErrorDetailsOpen, + draftStatus, + confirming, + children, +}: { + labels: CellEditorLabels; + slotPrefix: string; + cellProps: ComponentProps; + display: ReactNode; + truncate?: boolean; + tooltipLabel?: string; + editing: boolean; + callbackError?: CellErrorUI; + onEditorLeave?: () => void; + onEditorCancel: () => void; + getFailure: () => CellEditFailure | undefined; + setErrorDetailsOpen?: CellEditorView["setErrorDetailsOpen"]; + draftStatus?: CellEditorView["draftStatus"]; + confirming: boolean; + /** Typed-into cells hide the display while the input shows the text. */ + hideDisplay?: "focused" | "forced-colors"; + /** Shown on hover or focus; the cell's tint marks editability at rest. */ + icon?: ReactNode; + children: ReactNode; +}) { + const [tooltipOpen, setTooltipOpen] = useState(false); + const [focusedWithin, setFocusedWithin] = useState(false); + const [dismissedFailure, setDismissedFailure] = useState(null); + const [manuallyOpenedFailure, setManuallyOpenedFailure] = useState(null); + const [navigationDismissedFailure, setNavigationDismissedFailure] = + useState(null); + const errorActionsRef = useRef(null); + const tabNavigationRef = useRef(false); + const errorOpen = + !!callbackError && + !callbackError.failure.detailsDismissed && + dismissedFailure !== callbackError.failure; + const statusDescription = callbackError ? undefined : draftStatus; + const showTooltip = statusDescription + ? !statusDescription.quiet + : tooltipLabel !== undefined && !editing && !callbackError; + const changeErrorDetails = (failure: CellEditFailure, open: boolean) => + setErrorDetailsOpen?.(failure, open) ?? failure; + const dismissForNavigation = () => { + const failure = getFailure(); + if (!failure || failure.source === "parse") return; + const dismissed = changeErrorDetails(failure, false); + setNavigationDismissedFailure(dismissed); + setDismissedFailure(dismissed); + }; + useLayoutEffect(() => { + // Remove closing focus guards before native Tab chooses its destination. + if (!errorOpen && navigationDismissedFailure === callbackError?.failure) + errorActionsRef.current?.unmount(); + }, [errorOpen, callbackError?.failure, navigationDismissedFailure]); + const cell = ( + setFocusedWithin(true)} + onBlurCapture={(event) => { + if (!event.currentTarget.contains(event.relatedTarget)) setFocusedWithin(false); + }} + // The editor is positioned against the cell. A pinned cell is already + // positioned (sticky), which its inline style keeps. + className={cn( + cellProps.className, + "astw:relative astw:group/cell", + EDITABLE_CELL_CLASS_NAME, + callbackError && CELL_ERROR_CLASS_NAME, + )} + // The editor and its portaled error popup are one logical focus group. + onBlur={(event) => { + if ( + event.currentTarget.contains(event.relatedTarget) || + callbackError?.containsTarget(event.relatedTarget) + ) + return; + if (tabNavigationRef.current) dismissForNavigation(); + onEditorLeave?.(); + }} + onKeyDown={(event) => { + if ( + event.key === "Tab" && + !event.defaultPrevented && + event.currentTarget.contains(event.target as Node) + ) + dismissForNavigation(); + tabNavigationRef.current = false; + }} + onKeyDownCapture={(event) => { + tabNavigationRef.current = + event.key === "Tab" && event.currentTarget.contains(event.target as Node); + if ( + callbackError && + event.key === "Escape" && + !callbackError.popupRef.current?.contains(event.target as Node) + ) { + event.preventDefault(); + event.stopPropagation(); + if (errorOpen) setDismissedFailure(changeErrorDetails(callbackError.failure, false)); + else onEditorCancel(); + return; + } + if (callbackError && event.altKey && event.key === "ArrowDown") { + event.preventDefault(); + event.stopPropagation(); + setNavigationDismissedFailure(null); + setManuallyOpenedFailure(changeErrorDetails(callbackError.failure, true)); + setDismissedFailure(null); + if (errorOpen) callbackError.popupRef.current?.focus({ preventScroll: true }); + } + }} + // Editing a cell must never fire `onClickRow`. + onClick={(event) => event.stopPropagation()} + > + + {children} + {statusDescription && ( + <> + + {statusDescription.message} + + {(statusDescription.confirming || !statusDescription.quiet || !focusedWithin) && ( + + ); + return ( + + + {statusDescription?.message ?? tooltipLabel} + + ); +} diff --git a/packages/core/src/components/internals/table-core/editing/typing.tsx b/packages/core/src/components/internals/table-core/editing/typing.tsx new file mode 100644 index 000000000..c472088aa --- /dev/null +++ b/packages/core/src/components/internals/table-core/editing/typing.tsx @@ -0,0 +1,301 @@ +import { + useId, + useRef, + useState, + type ChangeEvent, + type FocusEvent, + type KeyboardEvent, + type MouseEvent, + type TouchEvent, +} from "react"; +import { cn } from "@/lib/utils"; +import { isComposing } from "@/lib/is-composing"; +import { Input } from "@/components/input"; +import { Tooltip } from "@/components/tooltip"; +import { + normalizeNumberText, + parseNumberText, + sameNumber, + toNumberEditText, + toNumberValue, + toTextValue, +} from "../input-values"; +import { useCellEditSession } from "./use-session"; +import { + CELL_ERROR_CLASS_NAME, + ICON_INPUT_CLASS_NAME, + INPUT_CLASS_NAME, + INPUT_DISPLAY, + useCellError, + useDraftStatus, + useNavigationRef, +} from "./shared"; +import type { CellEditor, CellEditorProps } from "./props"; + +function TypingEditor({ + numeric, + format, + parse, + isUnchanged, + current, + change = () => undefined, + commit, + renderError, + labels, + interceptErrors = true, + session: external, + rowKey, + colKey, + label, + align, + navigation, + children, +}: CellEditorProps, TOutput> & { + numeric: boolean; + format: (current: unknown) => string; + parse: (draft: string) => TOutput | undefined; + isUnchanged: (value: TOutput, current: unknown) => boolean; +}) { + const errorId = useId(); + const session = useCellEditSession(interceptErrors, external); + const { state } = session; + const failure = state.status === "failed" ? state : undefined; + const { callbackError, containsErrorTarget } = useCellError({ labels, renderError }, failure); + const register = useNavigationRef(navigation, rowKey, colKey); + const editing = state.status !== "idle"; + const [focused, setFocused] = useState(false); + const [hovered, setHovered] = useState(false); + const composingRef = useRef(false); + const selectOnMouseUpRef = useRef(false); + + const baselineText = format(current); + const text = state.status === "idle" ? baselineText : state.draft; + const message = failure?.source === "parse" ? labels.notANumber : undefined; + const parsedDraft = parse(text); + const draftStatus = useDraftStatus( + labels, + !!external, + text !== baselineText && (parsedDraft === undefined || !isUnchanged(parsedDraft, current)), + state.status, + ); + const descriptionIds = callbackError + ? `${callbackError.id} ${callbackError.hintId}` + : draftStatus?.id; + + const revert = (notify = false) => { + const previous = session.getState(); + session.cancel( + notify && previous.status !== "idle" && previous.draft !== baselineText + ? () => change(baselineText) + : undefined, + ); + }; + + const commitDraft = (): boolean => { + const active = session.getState(); + if (active.status === "idle" || active.status === "confirming") return true; + const draftText = active.draft; + const value = parse(draftText); + if (value === undefined) { + session.fail(undefined, "parse"); + return false; + } + const unchanged = draftText === baselineText || isUnchanged(value, current); + session.confirm(() => (unchanged ? undefined : commit(value))); + return true; + }; + + const handleChange = (event: ChangeEvent) => { + const next = event.target.value; + const active = session.getState(); + const previous = active.status === "idle" ? baselineText : active.draft; + if (next !== previous) session.change(next, () => change(next)); + }; + + // Keep IME output raw until cell confirmation, just like other draft changes. + const handleCompositionEnd = () => { + composingRef.current = false; + }; + + const handleKeyDown = (event: KeyboardEvent) => { + // While an IME is composing, Enter confirms the conversion, not the cell. + if (isComposing(event.nativeEvent, composingRef.current)) return; + const from = { rowKey, colKey }; + switch (event.key) { + case "Enter": + event.preventDefault(); + if (session.getState().status === "idle") { + session.begin(baselineText); + event.currentTarget.select(); + } else { + commitDraft(); + } + return; + case "Tab": { + const active = session.getState(); + const failedCommit = active.status === "failed" && active.source === "commit"; + if (!failedCommit && !commitDraft()) { + event.preventDefault(); + return; + } + // At the first / last editable cell, native Tab leaves the table. + if (navigation?.move(from, event.shiftKey ? "prev" : "next")) event.preventDefault(); + return; + } + case "Escape": + if (session.getState().status === "idle") return; + // Handled here, so an enclosing dialog doesn't also close on this Esc. + event.preventDefault(); + event.stopPropagation(); + revert(true); + return; + } + }; + + const handleFocus = (event: FocusEvent) => { + const withinCell = focused || containsErrorTarget(event.relatedTarget); + setFocused(true); + if (withinCell) return; + session.begin(baselineText); + event.currentTarget.select(); + }; + + const handleBlur = () => { + setFocused(false); + const active = session.getState(); + if (active.status === "failed") { + // Preserve callback failures; malformed numeric blur still cancels the edit. + if (active.source === "parse") revert(true); + return; + } + if (!commitDraft()) revert(true); + }; + + const handleMouseDown = (event: MouseEvent) => { + if (editing) return; + // A right-click on a resting cell opens DataTable's cell menu instead of editing. + if (event.button === 2) { + event.preventDefault(); + return; + } + session.begin(baselineText); + if (focused) event.currentTarget.select(); + selectOnMouseUpRef.current = true; + }; + + // The click that focuses the cell keeps the select-all from `handleFocus`; + // otherwise mouseup would collapse it to a caret. + const handleMouseUp = (event: MouseEvent) => { + if (!selectOnMouseUpRef.current) return; + selectOnMouseUpRef.current = false; + event.preventDefault(); + }; + + // While editing, the browser's own menu and long-press (paste, select) win + // over DataTable's cell menu. + const stopWhileEditing = (event: MouseEvent | TouchEvent) => { + if (editing) event.stopPropagation(); + }; + + const hint = labels.revertHint; + + return children({ + editing, + callbackError, + onEditorLeave: handleBlur, + onEditorCancel: () => revert(true), + getFailure: session.getFailure, + setErrorDetailsOpen: external ? session.setErrorDetailsOpen : undefined, + draftStatus: draftStatus && { ...draftStatus, quiet: true }, + confirming: state.status === "confirming", + input: ( + <> + {message !== undefined && ( + <> + + {message} + + + {hint} + + + )} + + { + composingRef.current = true; + }} + onCompositionEnd={handleCompositionEnd} + onMouseDown={handleMouseDown} + onMouseUp={handleMouseUp} + onPointerEnter={() => setHovered(true)} + onPointerLeave={() => setHovered(false)} + onContextMenu={stopWhileEditing} + onTouchStart={stopWhileEditing} + /> + } + /> + + {message} + {hint} + + + + ), + }); +} + +export const textEditor: CellEditor, string | null> = { + Editor: (props) => ( + toTextValue(current) ?? ""} + parse={toTextValue} + isUnchanged={(value, current) => value === toTextValue(current)} + /> + ), + hideDisplay: INPUT_DISPLAY, +}; + +export const numberEditor: CellEditor, number | null> = { + Editor: (props) => ( + toNumberEditText(toNumberValue(current))} + parse={(draft) => parseNumberText(normalizeNumberText(draft))} + isUnchanged={(value, current) => sameNumber(value, toNumberValue(current))} + /> + ), + hideDisplay: INPUT_DISPLAY, +}; diff --git a/packages/core/src/components/data-table/editing/use-session.test.tsx b/packages/core/src/components/internals/table-core/editing/use-session.test.tsx similarity index 93% rename from packages/core/src/components/data-table/editing/use-session.test.tsx rename to packages/core/src/components/internals/table-core/editing/use-session.test.tsx index 34f385f58..cbb67faa6 100644 --- a/packages/core/src/components/data-table/editing/use-session.test.tsx +++ b/packages/core/src/components/internals/table-core/editing/use-session.test.tsx @@ -1,6 +1,7 @@ import { StrictMode, type ReactNode } from "react"; import { act, cleanup, renderHook } from "@testing-library/react"; import { afterEach, describe, expect, it, vi } from "vitest"; +import { createCellEditSession } from "../cell-session"; import { useCellEditSession } from "./use-session"; afterEach(cleanup); @@ -347,4 +348,24 @@ describe("useCellEditSession", () => { }); expect(result.current.state).toEqual({ status: "idle" }); }); + + it("detaches a view without cancelling its externally owned session", () => { + const session = createCellEditSession(); + const { result, unmount } = renderHook(() => useCellEditSession(true, session)); + expect(result.current.getState).toBe(session.getState); + unmount(); + session.begin("Memo"); + const commit = vi.fn(); + session.confirm(commit); + expect(commit).toHaveBeenCalledOnce(); + expect(session.getState()).toEqual({ status: "idle" }); + }); + + it("does not activate an externally owned session whose owner has disposed it", () => { + const session = createCellEditSession(); + session.deactivate(); + const { result } = renderHook(() => useCellEditSession(true, session)); + result.current.change("Detached"); + expect(session.getState()).toEqual({ status: "idle" }); + }); }); diff --git a/packages/core/src/components/internals/table-core/editing/use-session.ts b/packages/core/src/components/internals/table-core/editing/use-session.ts new file mode 100644 index 000000000..1dd1f83c9 --- /dev/null +++ b/packages/core/src/components/internals/table-core/editing/use-session.ts @@ -0,0 +1,19 @@ +import { useEffect, useState, useSyncExternalStore } from "react"; +import { createCellEditSession } from "../cell-session"; + +/** Mounted cells own local sessions; document adapters retain external sessions across view detach. */ +export function useCellEditSession( + enabled: boolean, + external?: ReturnType>, +) { + const [local] = useState(() => external ?? createCellEditSession(enabled)); + // External sessions must retain one editor's draft shape while a draft is active. + const session = (external ?? local) as ReturnType>; + const state = useSyncExternalStore(session.subscribe, session.getState, session.getState); + useEffect(() => { + if (external) return; + session.activate(enabled); + return session.deactivate; + }, [enabled, external, session]); + return { state, ...session }; +} diff --git a/packages/core/src/components/internals/table-core/index.ts b/packages/core/src/components/internals/table-core/index.ts new file mode 100644 index 000000000..0c65f9769 --- /dev/null +++ b/packages/core/src/components/internals/table-core/index.ts @@ -0,0 +1,15 @@ +export { + createValueRenderer, + getDisplayCellAdapter, + type ValueRenderer, + type ValueRendererContext, +} from "./cell-renderers"; +export type { + BadgeCellOptions, + ColumnCellType, + DateCellOptions, + LinkCellOptions, + MoneyCellOptions, + NumberCellOptions, + ValueDisplayDescriptor, +} from "./column-types"; diff --git a/packages/core/src/components/internals/table-core/input-values.test.ts b/packages/core/src/components/internals/table-core/input-values.test.ts new file mode 100644 index 000000000..2178f1da0 --- /dev/null +++ b/packages/core/src/components/internals/table-core/input-values.test.ts @@ -0,0 +1,164 @@ +import { describe, expect, it } from "vitest"; +import { + isIsoDate, + sameDate, + toCalendarDate, + toIsoDateTime, + toTimeText, + normalizeNumberText, + parseNumberText, + sameNumber, + toNumberEditText, + toNumberValue, + toTextValue, +} from "./input-values"; + +describe("typed text that isn't a number", () => { + it("is reported as not a number, not silently accepted", () => { + for (const text of ["e", "1e5", "+5", "0x1f", "12a", "1,5"]) { + expect(parseNumberText(normalizeNumberText(text))).toBeUndefined(); + } + }); +}); + +describe("normalizeNumberText", () => { + it("drops strict thousands grouping", () => { + expect(normalizeNumberText("1,234.5")).toBe("1234.5"); + expect(normalizeNumberText("-1,234,567")).toBe("-1234567"); + }); + + it("leaves a decimal comma alone so it fails instead of becoming 15", () => { + expect(normalizeNumberText("1,5")).toBe("1,5"); + expect(parseNumberText(normalizeNumberText("1,5"))).toBeUndefined(); + }); + + it("converts full-width digits and signs", () => { + expect(normalizeNumberText("12.5")).toBe("12.5"); + expect(normalizeNumberText("-3")).toBe("-3"); + expect(normalizeNumberText("−3")).toBe("-3"); + }); + + it("strips whitespace and currency symbols", () => { + expect(normalizeNumberText(" $1,234.50 ")).toBe("1234.50"); + expect(normalizeNumberText("¥ 1 200")).toBe("1200"); + }); +}); + +describe("parseNumberText", () => { + it("treats an empty draft as null", () => { + expect(parseNumberText("")).toBeNull(); + expect(parseNumberText(" ")).toBeNull(); + }); + + it("parses partial but complete-enough numbers without business constraints", () => { + expect(parseNumberText("-3.5678")).toBe(-3.5678); + expect(parseNumberText("500.0001")).toBe(500.0001); + expect(parseNumberText("5.")).toBe(5); + expect(parseNumberText(".5")).toBe(0.5); + expect(parseNumberText("-0")).toBe(0); + expect(Object.is(parseNumberText("-0"), -0)).toBe(false); + }); + + it("rejects half-typed and non-numeric drafts", () => { + for (const text of ["-", ".", "-.", "abc", "1,5", String(Number.MAX_SAFE_INTEGER * 2)]) { + expect(parseNumberText(text)).toBeUndefined(); + } + }); +}); + +describe("value helpers", () => { + it("compares parsed numbers without silently rounding distinct values", () => { + expect(sameNumber(10, 10)).toBe(true); + expect(sameNumber(0.1 + 0.2, 0.3)).toBe(false); + expect(sameNumber(1234567890123456, 1234567890123457)).toBe(false); + expect(sameNumber(null, null)).toBe(true); + expect(sameNumber(0, null)).toBe(false); + expect(sameNumber(10, 10.01)).toBe(false); + }); + + it("reads raw values the way the renderers do", () => { + expect(toNumberValue("10.00")).toBe(10); + expect(toNumberValue("")).toBeNull(); + expect(toNumberValue("abc")).toBeNull(); + expect(toTextValue("")).toBeNull(); + expect(toTextValue(42)).toBe("42"); + }); + + it("formats numbers without grouping, exponents, or precision loss", () => { + expect(toNumberEditText(1234567.5)).toBe("1234567.5"); + expect(toNumberEditText(0.1 + 0.2)).toBe("0.30000000000000004"); + expect(toNumberEditText(1234567890123456)).toBe("1234567890123456"); + expect(toNumberEditText(1e21)).toBe("1000000000000000000000"); + expect(toNumberEditText(null)).toBe(""); + for (const value of [Number.MAX_SAFE_INTEGER, Number.MIN_VALUE, 1e-30, 1.2345678901234567]) { + expect(parseNumberText(toNumberEditText(value))).toBe(value); + } + }); +}); + +describe("dates", () => { + it("recognises date-only strings", () => { + expect(isIsoDate("2026-10-02")).toBe(true); + expect(isIsoDate("2026-10-02T09:00:00Z")).toBe(false); + expect(isIsoDate(20261002)).toBe(false); + }); + + it("converts cell values to the calendar day and local time they show", () => { + expect(toCalendarDate("2026-10-02")?.toString()).toBe("2026-10-02"); + expect(toCalendarDate(new Date(2026, 9, 2, 23, 30))?.toString()).toBe("2026-10-02"); + expect(toCalendarDate(null)).toBeNull(); + expect(toTimeText(new Date(2026, 9, 2, 9, 5))).toBe("09:05"); + expect(toTimeText("2026-10-02")).toBe(""); + expect(toTimeText(undefined)).toBe(""); + }); + + it("builds an ISO timestamp from a day and a local time", () => { + const day = toCalendarDate("2026-10-20")!; + expect(toIsoDateTime(day, "14:30")).toBe(new Date(2026, 9, 20, 14, 30).toISOString()); + expect(toIsoDateTime(day, "")).toBeUndefined(); + }); + + it("does not fill or coerce an incomplete or invalid time", () => { + const day = toCalendarDate("2026-10-20")!; + for (const time of ["", "14:", "9:05", "24:00", "12:60", "-1:00", "abc"]) { + expect(toIsoDateTime(day, time)).toBeUndefined(); + } + expect(toIsoDateTime(day, "00:00", "Asia/Tokyo")).toBe("2026-10-19T15:00:00.000Z"); + }); + + it("initializes and commits date-times in the configured timezone", () => { + const zone = "America/New_York"; + const value = "2026-10-09T00:00:00Z"; + expect(toCalendarDate(value, zone)?.toString()).toBe("2026-10-08"); + expect(toTimeText(value, zone)).toBe("20:00"); + expect(toCalendarDate("2026-10-09", zone)?.toString()).toBe("2026-10-09"); + expect(toIsoDateTime(toCalendarDate("2026-10-08")!, "20:00", zone)).toBe( + "2026-10-09T00:00:00.000Z", + ); + expect(sameDate(value, "2026-10-08", false, zone)).toBe(true); + expect(sameDate("2026-10-08T20:00", value, true, zone)).toBe(true); + expect(toIsoDateTime(toCalendarDate("2026-12-08")!, "20:00", zone)).toBe( + "2026-12-09T01:00:00.000Z", + ); + }); + + it("distinguishes incomplete date-only data from explicit midnight in datetime comparisons", () => { + const day = "2026-10-02"; + const midnight = "2026-10-01T15:00:00.000Z"; + expect(sameDate(day, midnight, true, "Asia/Tokyo")).toBe(false); + expect(sameDate(midnight, day, true, "Asia/Tokyo")).toBe(false); + expect(sameDate(day, null, true, "Asia/Tokyo")).toBe(false); + expect(sameDate(day, day, true, "Asia/Tokyo")).toBe(true); + expect(sameDate(day, midnight, false, "Asia/Tokyo")).toBe(true); + }); + + it("compares by day for dates and by minute for date-times", () => { + expect(sameDate("2026-10-02", new Date(2026, 9, 2, 18), false)).toBe(true); + expect(sameDate("2026-10-02", "2026-10-03", false)).toBe(false); + const at = new Date(2026, 9, 2, 14, 30, 5); + expect(sameDate(at.toISOString(), new Date(2026, 9, 2, 14, 30, 50), true)).toBe(true); + expect(sameDate(at.toISOString(), new Date(2026, 9, 2, 14, 31), true)).toBe(false); + expect(sameDate(null, undefined, false)).toBe(true); + expect(sameDate(null, "2026-10-02", false)).toBe(false); + }); +}); diff --git a/packages/core/src/components/internals/table-core/input-values.ts b/packages/core/src/components/internals/table-core/input-values.ts new file mode 100644 index 000000000..700efecdd --- /dev/null +++ b/packages/core/src/components/internals/table-core/input-values.ts @@ -0,0 +1,140 @@ +/** + * Pure helpers behind inline cell editing: how typed or pasted text + * becomes a value and whether a draft is a real change or a cosmetic one + * (`10` vs `10.00`). Business validation belongs to the consumer. + * + * @internal + */ + +import { + CalendarDate, + CalendarDateTime, + getLocalTimeZone, + parseDate, + toZoned, +} from "@internationalized/date"; +import { localDateTimeParts, normalizeTemporalFilterValue } from "@/lib/temporal-filter-values"; + +// Thousands grouping with commas, e.g. "1,234,567.89". +const GROUPED_NUMBER = /^-?\d{1,3}(?:,\d{3})+(?:\.\d*)?$/; + +/** + * Cleans number text before it's checked: full-width digits and signs become + * ASCII, whitespace and currency symbols are dropped, and commas are removed + * only when they form strict thousands groups — so "1,234.5" becomes "1234.5", + * while "1,5" is left alone to fail as "not a number" instead of silently + * turning into 15. + */ +export function normalizeNumberText(text: string): string { + const compact = text + .normalize("NFKC") + .replace(/[\s\p{Sc}]/gu, "") + .replace(/^−/, "-"); + return GROUPED_NUMBER.test(compact) ? compact.replace(/,/g, "") : compact; +} + +/** `""` → `null`, `"5."` → `5`; `"-"`, `"."` and anything non-numeric → `undefined`. */ +export function parseNumberText(text: string): number | null | undefined { + const trimmed = text.trim(); + if (trimmed === "") return null; + if (!/^-?(?:\d+\.?\d*|\.\d+)$/.test(trimmed)) return undefined; + const value = Number(trimmed); + if (!Number.isFinite(value) || Math.abs(value) > Number.MAX_SAFE_INTEGER) return undefined; + // `+ 0` folds -0 into 0 so "-0" doesn't read as a change from 0. + return value + 0; +} + +/** Reads a raw cell value as a number the way the `number` renderer does. */ +export function toNumberValue(raw: unknown): number | null { + if (raw == null || raw === "") return null; + const value = typeof raw === "number" ? raw : Number(raw); + return Number.isFinite(value) ? value : null; +} + +/** Reads a raw cell value as text; `null`, `undefined` and `""` are all empty. */ +export function toTextValue(raw: unknown): string | null { + if (raw == null || raw === "") return null; + return String(raw); +} + +/** Compare parsed values exactly; rounding belongs to the consumer. */ +export function sameNumber(a: number | null, b: number | null): boolean { + return a === b; +} + +/** Plain edit text preserves the value without grouping or exponent notation. */ +export function toNumberEditText(value: number | null): string { + if (value === null) return ""; + return value.toLocaleString("en-US", { + useGrouping: false, + maximumSignificantDigits: 21, + }); +} + +// ── Dates ──────────────────────────────────────────────────────────────────── + +const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/; + +/** Whether `value` is a date-only ISO string (`"YYYY-MM-DD"`). */ +export function isIsoDate(value: unknown): value is string { + return typeof value === "string" && ISO_DATE.test(value); +} + +/** A raw date cell value as the calendar day it shows. */ +export function toCalendarDate(raw: unknown, timeZone = getLocalTimeZone()): CalendarDate | null { + const date = normalizeTemporalFilterValue("date", raw, timeZone); + if (!date) return null; + try { + return parseDate(date); + } catch { + return null; + } +} + +/** The zoned time of a raw date cell value as `"HH:mm"`; `""` when there is none. */ +export function toTimeText(raw: unknown, timeZone = getLocalTimeZone()): string { + if (isIsoDate(raw)) return ""; + const datetime = normalizeTemporalFilterValue("datetime", raw, timeZone); + return datetime ? localDateTimeParts(datetime, timeZone).time : ""; +} + +/** A calendar day plus a zoned `"HH:mm"` as an ISO 8601 timestamp. */ +export function toIsoDateTime( + day: CalendarDate, + time: string, + timeZone = getLocalTimeZone(), +): string | undefined { + if (!/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(time)) return undefined; + const [hours, minutes] = time.split(":").map(Number); + return toZoned(new CalendarDateTime(day.year, day.month, day.day, hours, minutes), timeZone) + .toDate() + .toISOString(); +} + +/** + * Whether two raw date values mean the same thing: the same day for a date + * column, the same minute for a date-time one — so `"2026-10-02"` equals a + * `Date` for that day, and string formatting differences don't count. + */ +export function sameDate( + a: unknown, + b: unknown, + withTime: boolean, + timeZone = getLocalTimeZone(), +): boolean { + if (!withTime) { + const left = toCalendarDate(a, timeZone); + const right = toCalendarDate(b, timeZone); + return left && right ? left.compare(right) === 0 : left === right; + } + // Date-only data is incomplete in a datetime editor, not implicit midnight. + if (isIsoDate(a) || isIsoDate(b)) return a === b; + const asInstant = (raw: unknown) => { + const normalized = normalizeTemporalFilterValue("datetime", raw, timeZone); + return normalized ? new Date(normalized) : null; + }; + const left = asInstant(a); + const right = asInstant(b); + if (!left || !right) return left === right; + return Math.floor(left.getTime() / 60_000) === Math.floor(right.getTime() / 60_000); +} diff --git a/packages/core/src/components/line-items/adoption-refusal.test.ts b/packages/core/src/components/line-items/adoption-refusal.test.ts new file mode 100644 index 000000000..9a1c942e1 --- /dev/null +++ b/packages/core/src/components/line-items/adoption-refusal.test.ts @@ -0,0 +1,105 @@ +import { describe, expect, it, vi } from "vitest"; +import { createLineItemsDocumentStore } from "./document/store"; +import { createLineItemsEditing } from "./editing"; +import type { LineItemsColumn } from "./types"; + +type Row = { id?: string; name: string | null; quantity: number | null }; + +function setup() { + let allowed = true; + let resolve!: () => void; + const request = new Promise((success) => { + resolve = success; + }); + const check = vi.fn(() => request); + const columns: LineItemsColumn[] = [ + { + accessorKey: "name", + edit: { editorType: "text", canEdit: () => allowed, onValueCommitted: check }, + }, + { accessorKey: "quantity" }, + ]; + const store = createLineItemsDocumentStore({ + columns, + lines: [{ id: "A", name: "Initial", quantity: 1 }], + }); + const editing = createLineItemsEditing(store, columns); + const session = editing.getSession(store.getSnapshot()[0], columns[0]); + const listener = vi.fn(); + store.subscribe(listener); + session.change("Candidate"); + session.confirm(() => editing.commitField("A", "name", "Candidate")); + return { + columns, + store, + editing, + session, + check, + listener, + deny: () => { + allowed = false; + }, + async complete() { + resolve(); + await request; + await Promise.resolve(); + }, + }; +} + +describe("permission checks at adoption", () => { + it("fails a still-current confirmation when external permission changes without reconciliation", async () => { + const editor = setup(); + const initial = editor.store.getSnapshot(); + expect(editor.session.getState().status).toBe("confirming"); + editor.deny(); + await editor.complete(); + + expect(editor.session.getState()).toMatchObject({ + status: "failed", + source: "commit", + draft: "Candidate", + error: new Error("The cell is not editable"), + }); + expect(editor.store.getSnapshot()).toBe(initial); + expect(editor.store.isDirty()).toBe(false); + expect(editor.listener).not.toHaveBeenCalled(); + expect(editor.check).toHaveBeenCalledTimes(1); + }); + + it.each(["write", "revert", "remove", "dispose", "reconciled-permission"] as const)( + "does not turn a late result into an error after %s cancels the edit", + async (action) => { + const editor = setup(); + editor.deny(); + if (action === "write") editor.editing.updateField("A", "name", "Command"); + if (action === "revert") editor.editing.revert(); + if (action === "remove") editor.editing.removeLine("A"); + if (action === "dispose") editor.editing.deactivate(); + if (action === "reconciled-permission") editor.editing.reconcileColumns(editor.columns); + const snapshot = editor.store.getSnapshot(); + const notifications = editor.listener.mock.calls.length; + await editor.complete(); + + expect(editor.store.getSnapshot()).toBe(snapshot); + expect(editor.listener).toHaveBeenCalledTimes(notifications); + expect(editor.session.getFailure()).toBeUndefined(); + if (action !== "dispose" && action !== "remove") + expect(editor.session.getState()).toEqual({ status: "idle" }); + expect(editor.store.getSnapshot().map((row) => row.name)).toEqual( + action === "remove" ? [] : [action === "write" ? "Command" : "Initial"], + ); + }, + ); + + it("adopts an allowed confirmation into the current row", async () => { + const editor = setup(); + editor.editing.updateField("A", "quantity", 2); + await editor.complete(); + + expect(editor.session.getState()).toEqual({ status: "idle" }); + expect(editor.store.getSnapshot()[0]).toMatchObject({ name: "Candidate", quantity: 2 }); + expect(editor.check).toHaveBeenCalledTimes(1); + expect(editor.listener).toHaveBeenCalledTimes(2); + }); +}); diff --git a/packages/core/src/components/line-items/badge-label-ownership.test-d.ts b/packages/core/src/components/line-items/badge-label-ownership.test-d.ts new file mode 100644 index 000000000..983c97452 --- /dev/null +++ b/packages/core/src/components/line-items/badge-label-ownership.test-d.ts @@ -0,0 +1,123 @@ +import { expectTypeOf, test } from "vitest"; +import type { BadgeCellOptions } from "@/components/internals/table-core/column-types"; +import type { LineItemsColumn, LineItemsEditor } from "./types"; + +type Row = { id?: string; status: "open" | "closed" | null }; +const choices = { + editorType: "combobox" as const, + editorOptions: { options: [{ value: "open" as const, label: "Open" }] }, +}; + +test("combobox badge labels have one definition while variants remain configurable", () => { + const column: LineItemsColumn = { + accessorKey: "status", + type: "badge", + typeOptions: { + badgeVariantMap: { open: "success" }, + defaultBadgeVariant: "outline-neutral", + maxVisible: 1, + }, + edit: { + ...choices, + clearValue: () => "closed", + canEdit: (row) => { + expectTypeOf(row).toEqualTypeOf(); + return row.status !== "closed"; + }, + onValueCommitted: (row, value) => { + expectTypeOf(row).toEqualTypeOf>(); + expectTypeOf(value).toEqualTypeOf(); + }, + }, + }; + const competing = { + accessorKey: "status" as const, + type: "badge" as const, + typeOptions: { badgeLabelMap: { open: "Another label" } }, + edit: choices, + }; + // @ts-expect-error Combobox badges define labels in choices, not badgeLabelMap. + const invalid: LineItemsColumn = competing; + void column; + void invalid; +}); + +test("non-combobox badges retain their ordinary label map", () => { + type TextRow = { status: string | null }; + const columns: LineItemsColumn[] = [ + { + accessorKey: "status", + type: "badge", + typeOptions: { badgeLabelMap: { open: "Open" } }, + }, + { + accessorKey: "status", + type: "badge", + typeOptions: { badgeLabelMap: { open: "Open" } }, + edit: { + editorType: "text", + onValueCommitted: (row, value) => { + expectTypeOf(row).toEqualTypeOf>(); + expectTypeOf(value).toEqualTypeOf(); + }, + }, + }, + { + id: "computed", + type: "badge", + accessor: (row) => row.status, + typeOptions: { badgeLabelMap: { open: "Open" } }, + }, + ]; + void columns; + type MixedRow = { status: string | number | null }; + const otherEditors: LineItemsColumn[] = [ + { + accessorKey: "status", + type: "badge", + typeOptions: { badgeLabelMap: { "1": "One" } }, + edit: { editorType: "number" }, + }, + { + accessorKey: "status", + type: "badge", + typeOptions: { badgeLabelMap: { "2026-12-01": "Closing day" } }, + edit: { editorType: "date" }, + }, + ]; + void otherEditors; +}); + +test("uncertain display, editor, or map options cannot bypass label ownership", () => { + type TextRow = { status: string | null }; + const type = null as unknown as "badge" | "text"; + const edit = null as unknown as LineItemsEditor; + const typeOptions = null as unknown as BadgeCellOptions; + const displayUnion = { + accessorKey: "status" as const, + type, + typeOptions: { badgeLabelMap: { open: "Open" } }, + edit: choices, + }; + const editorUnion = { + accessorKey: "status" as const, + type: "badge" as const, + typeOptions: { badgeLabelMap: { open: "Open" } }, + edit, + }; + const optionsUnion = { + accessorKey: "status" as const, + type: "badge" as const, + typeOptions, + edit: choices, + }; + // @ts-expect-error A possibly-badge combobox cannot supply competing labels. + const invalidDisplay: LineItemsColumn = displayUnion; + // @ts-expect-error A possibly-combobox badge cannot supply competing labels. + const invalidEditor: LineItemsColumn = editorUnion; + // @ts-expect-error Broad badge options may contain a competing label map. + const invalidOptions: LineItemsColumn = optionsUnion; + void invalidDisplay; + void invalidEditor; + void invalidOptions; +}); diff --git a/packages/core/src/components/line-items/badge-label-ownership.test.tsx b/packages/core/src/components/line-items/badge-label-ownership.test.tsx new file mode 100644 index 000000000..b50d076f0 --- /dev/null +++ b/packages/core/src/components/line-items/badge-label-ownership.test.tsx @@ -0,0 +1,122 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { cleanup, render, screen } from "@testing-library/react"; +import { MemoryRouter } from "react-router"; +import { AppShellConfigContext, buildConfigurations } from "@/contexts/appshell-context"; +import { createLineItemsDocument } from "./document/model"; +import type { DocumentOptions } from "./document/types"; +import { LineItems } from "./line-items"; +import { useLineItems } from "./use-line-items"; +import type { LineItemsColumn } from "./types"; + +afterEach(cleanup); +type Row = { id?: string; status: string | null; allowed: boolean }; +const choices = { + editorType: "combobox" as const, + editorOptions: { options: [{ value: "open", label: "Open" }] }, + canEdit: (row: Row) => row.allowed, +}; +const base = { accessorKey: "status" as const, type: "badge" as const, label: "Status" }; +const rows: Row[] = [ + { id: "A", status: "open", allowed: true }, + { id: "B", status: "archived", allowed: false }, +]; +const invalid = { + ...base, + typeOptions: { badgeLabelMap: { open: "Competing label" } }, + edit: choices, +}; +const message = "Combobox badge labels must be defined in editorOptions.options only"; + +function setup(column: LineItemsColumn) { + function Owner() { + const value = useLineItems({ columns: [column], defaultLines: rows, orderer: false }); + return ( + + + + + + + + ); + } + return render(); +} + +describe("LineItems badge label ownership", () => { + it.each([undefined, () => false])( + "rejects competing labels from untyped configuration regardless of edit permission (%s)", + (canEdit) => { + const options = { + columns: [{ ...invalid, edit: { ...choices, canEdit } }], + lines: rows, + } as unknown as DocumentOptions; + expect(() => createLineItemsDocument(options)).toThrow(message); + }, + ); + + it("rejects competing labels even when a custom renderer would hide them", () => { + const options = { + columns: [{ ...invalid, render: () => null }], + lines: rows, + } as unknown as DocumentOptions; + expect(() => createLineItemsDocument(options)).toThrow(message); + }); + + it("validates later columns without changing the existing document", () => { + const document = createLineItemsDocument({ columns: [base], lines: rows }); + const snapshot = document.getRows(); + expect(() => document.assertColumns([invalid] as unknown as LineItemsColumn[])).toThrow( + message, + ); + expect(document.getRows()).toBe(snapshot); + expect(document.isDirty()).toBe(false); + }); + + it("uses choices as the sole label source, raw text for unlisted values, and raw variants", () => { + setup({ + accessorKey: "status", + type: "badge", + label: "Status", + edit: choices, + typeOptions: { + badgeVariantMap: { open: "success", archived: "neutral" }, + defaultBadgeVariant: "outline-neutral", + }, + }); + const cells = screen.getAllByRole("cell"); + expect(cells.map((cell) => cell.textContent)).toEqual(["Open", "archived"]); + expect(cells[0].querySelector('[class*="bg-success-solid"]')).not.toBeNull(); + expect(cells[1].querySelector('[class*="bg-secondary"]')).not.toBeNull(); + expect(screen.getAllByRole("combobox")).toHaveLength(1); + }); + + it("keeps badgeLabelMap for badges without a combobox", () => { + setup({ + ...base, + typeOptions: { badgeLabelMap: { open: "Open label", archived: "Archived label" } }, + }); + expect(screen.getAllByRole("cell").map((cell) => cell.textContent)).toEqual([ + "Open label", + "Archived label", + ]); + expect(screen.queryByRole("combobox")).toBeNull(); + }); + + it("keeps badgeLabelMap when a different editor is configured", () => { + setup({ + accessorKey: "status", + type: "badge", + label: "Status", + edit: { editorType: "text", canEdit: (row) => row.allowed }, + typeOptions: { badgeLabelMap: { open: "Open label", archived: "Archived label" } }, + }); + expect(screen.getAllByRole("cell").map((cell) => cell.textContent)).toEqual([ + "Open label", + "Archived label", + ]); + expect(screen.getAllByRole("textbox")).toHaveLength(1); + }); +}); diff --git a/packages/core/src/components/line-items/cell-editing.test-d.ts b/packages/core/src/components/line-items/cell-editing.test-d.ts new file mode 100644 index 000000000..72c9dada4 --- /dev/null +++ b/packages/core/src/components/line-items/cell-editing.test-d.ts @@ -0,0 +1,263 @@ +import { expectTypeOf, test } from "vitest"; +import { parseDate } from "@internationalized/date"; +import type { CalendarProps } from "@/components/calendar"; +import type { + CellEditorOptions, + CellEditorOutput, +} from "@/components/internals/table-core/editing/props"; +import type { choiceEditor } from "@/components/internals/table-core/editing/choice"; +import type { dateEditor } from "@/components/internals/table-core/editing/date"; +import type { numberEditor, textEditor } from "@/components/internals/table-core/editing/typing"; +import type { lineItemsEditors } from "./editor-factory"; +import type { LineItemsColumn, LineItemsEditor } from "./types"; + +type EditorCatalog = typeof lineItemsEditors; +type EditorAdapter = ReturnType; + +type Row = { + id?: string; + name: string | null; + quantity: number | null; + required: string; + structured: { code: string }; +}; + +test("cell editors retain property-specific nullable output and row callback types", () => { + const text: LineItemsColumn = { + accessorKey: "name", + edit: { + editorType: "text", + onValueCommitted: (row, value) => { + expectTypeOf(row).toEqualTypeOf>(); + expectTypeOf(value).toEqualTypeOf(); + }, + canEdit: (row) => { + expectTypeOf(row).toEqualTypeOf(); + return row.name !== null; + }, + }, + }; + const numeric: LineItemsColumn = { + accessorKey: "quantity", + edit: { + editorType: "number", + onValueCommitted: async (_row, value) => { + expectTypeOf(value).toEqualTypeOf(); + }, + }, + }; + const date: LineItemsColumn = { + accessorKey: "name", + type: "date", + edit: { + editorType: "date", + editorOptions: { + withTime: true, + minValue: parseDate("2026-10-05"), + maxValue: parseDate("2026-10-25"), + isDateUnavailable: (day) => { + expectTypeOf(day).toEqualTypeOf< + Parameters>[0] + >(); + return day.day === 10; + }, + }, + }, + }; + const choice: LineItemsColumn = { + accessorKey: "name", + edit: { + editorType: "combobox", + editorOptions: { options: [{ value: "open", label: "Open" }] }, + }, + }; + // @ts-expect-error Non-nullable properties require an explicit Clear policy. + const missingTextClear: LineItemsEditor = { editorType: "text" }; + // @ts-expect-error Non-nullable properties require an explicit Clear policy. + const missingNumberClear: LineItemsEditor = { editorType: "number" }; + void missingTextClear; + void missingNumberClear; + expectTypeOf>().toEqualTypeOf(); + expectTypeOf< + Extract, { accessorKey?: never }>["edit"] + >().toEqualTypeOf(); + expectTypeOf< + Extract, { editorType: "number" }> + >().toEqualTypeOf(); + const numericChoice: LineItemsEditor = { + editorType: "combobox", + editorOptions: { + // @ts-expect-error Fixed choices retain string values, not a second numeric-choice API. + options: [{ value: 1, label: "One" }], + }, + }; + // @ts-expect-error No custom editor is introduced. + const custom: LineItemsEditor = { editorType: "custom" }; + const asyncChoice: LineItemsEditor = { + editorType: "combobox", + editorOptions: { + // @ts-expect-error No asynchronous choice fetcher is introduced. + fetcher: async () => [], + }, + }; + const unhandled: LineItemsEditor = { + editorType: "text", + // @ts-expect-error Error presentation cannot disable checks or eager-adopt the value. + error: false, + }; + expectTypeOf< + ReturnType["onValueCommitted"]>> + >().toEqualTypeOf>(); + void unhandled; + void text; + void numeric; + void date; + void choice; + void numericChoice; + void custom; + void asyncChoice; +}); + +test("fixed choices and confirmation values follow nullable string enum properties", () => { + type EnumRow = { + id?: string; + status: "draft" | "confirmed" | null; + requiredStatus: "draft" | "confirmed"; + quantity: number | null; + }; + const column: LineItemsColumn = { + accessorKey: "status", + edit: { + editorType: "combobox", + // A partial choice list does not narrow the callback's property-based value type. + editorOptions: { options: [{ value: "draft", label: "Draft" }] }, + onValueCommitted: (row, value) => { + expectTypeOf(row).toEqualTypeOf>(); + expectTypeOf(value).toEqualTypeOf(); + }, + }, + }; + const invalidChoice: LineItemsEditor = { + editorType: "combobox", + editorOptions: { + // @ts-expect-error Choices must fit the target property's string enum. + options: [{ value: "invalid", label: "Invalid" }], + }, + }; + const numericChoice: LineItemsEditor = { + editorType: "combobox", + editorOptions: { + // @ts-expect-error Numeric choices are not part of the fixed-string choice API. + options: [{ value: 1, label: "One" }], + }, + }; + expectTypeOf< + Extract, { editorType: "text" }> + >().toEqualTypeOf(); + expectTypeOf< + Extract, { editorType: "combobox" }> + >().toEqualTypeOf(); + const requiredEnum: LineItemsEditor = { + editorType: "combobox", + editorOptions: { options: [{ value: "draft", label: "Draft" }] }, + clearValue: false, + }; + void requiredEnum; + void column; + void invalidChoice; + void numericChoice; +}); + +test("public editor settings and confirmation values follow the concrete editors", () => { + type DefinitionKeys = { [K in keyof EditorCatalog]: keyof EditorCatalog[K] }; + expectTypeOf().toEqualTypeOf>(); + type UIAdapters = Parameters[0]; + type AdapterKeys = { [K in keyof UIAdapters]: keyof UIAdapters[K] }; + expectTypeOf().toEqualTypeOf>(); + expectTypeOf["editorType"]>().toEqualTypeOf(); + type PublicEditor["editorType"]> = Extract< + LineItemsEditor["editor"]>>, + { editorType: K } + >; + type ConfirmedValue["editorType"]> = Parameters< + NonNullable["onValueCommitted"]> + >[1]; + + expectTypeOf>().toEqualTypeOf>(); + expectTypeOf>().toEqualTypeOf>(); + expectTypeOf>().toEqualTypeOf>(); + expectTypeOf>().toEqualTypeOf>(); + expectTypeOf["editorOptions"]>().toEqualTypeOf(); + expectTypeOf["editorOptions"]>().toEqualTypeOf(); + expectTypeOf["editorOptions"]>().toEqualTypeOf< + Omit, "timeZone"> | undefined + >(); + expectTypeOf["editorOptions"]>().toEqualTypeOf< + Pick, "options"> + >(); + type PreparedEditors = { + [K in keyof EditorCatalog]: ReturnType["prepare"]>; + }; + expectTypeOf().toEqualTypeOf< + "align" | "reserveIconSpace" | "renderCell" | "renderDisplay" + >(); + expectTypeOf().toEqualTypeOf<"left" | "center" | "right">(); + expectTypeOf().toEqualTypeOf< + Record + >(); + + const choice: PublicEditor<"combobox"> = { + editorType: "combobox", + editorOptions: { + options: [], + // @ts-expect-error Internal menu rendering is not a public editor setting. + renderOption: () => null, + }, + }; + void choice; +}); + +test("editorType discriminates nested editorOptions and rejects the flattened settings", () => { + type Editor = LineItemsEditor; + const defaults: Editor[] = [ + { editorType: "text" }, + { editorType: "number" }, + { editorType: "date" }, + { editorType: "date", editorOptions: {} }, + { editorType: "combobox", editorOptions: { options: [] } }, + ]; + const invalid: Editor[] = [ + // @ts-expect-error Fixed choices are required for combobox editors. + { editorType: "combobox" }, + // @ts-expect-error Text editors have no configurable options. + { editorType: "text", editorOptions: {} }, + // @ts-expect-error Number editors have no configurable options. + { editorType: "number", editorOptions: { withTime: true } }, + // @ts-expect-error Fixed choices belong to combobox, not date. + { editorType: "date", editorOptions: { options: [] } }, + // @ts-expect-error withTime belongs to date, not combobox. + { editorType: "combobox", editorOptions: { options: [], withTime: true } }, + // @ts-expect-error Timezone comes from AppShell, not editorOptions. + { editorType: "date", editorOptions: { timeZone: "UTC" } }, + // @ts-expect-error Date bounds use Calendar DateValue objects, not strings. + { editorType: "date", editorOptions: { minValue: "2026-10-05" } }, + // @ts-expect-error The editor owns Calendar value and callbacks. + { editorType: "date", editorOptions: { value: null } }, + // @ts-expect-error Date settings are nested under editorOptions. + { editorType: "date", withTime: true }, + // @ts-expect-error Fixed choices are nested under editorOptions. + { editorType: "combobox", options: [] }, + ]; + for (const edit of defaults) { + if (edit.editorType === "date") { + expectTypeOf(edit.editorOptions?.withTime).toEqualTypeOf(); + } else if (edit.editorType === "combobox") { + expectTypeOf(edit.editorOptions.options).toEqualTypeOf< + CellEditorOptions["options"] + >(); + } else { + expectTypeOf(edit.editorOptions).toEqualTypeOf(); + } + } + void invalid; +}); diff --git a/packages/core/src/components/line-items/cell-editing.test.tsx b/packages/core/src/components/line-items/cell-editing.test.tsx new file mode 100644 index 000000000..6a488ec01 --- /dev/null +++ b/packages/core/src/components/line-items/cell-editing.test.tsx @@ -0,0 +1,889 @@ +import { StrictMode } from "react"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { + act, + cleanup, + fireEvent, + render, + renderHook, + screen, + within, +} from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { MemoryRouter } from "react-router"; +import { parseDate, type DateValue } from "@internationalized/date"; +import { AppShellConfigContext, buildConfigurations } from "@/contexts/appshell-context"; +import { CellEditError } from "@/components/internals/table-core/cell-edit-error"; +import { LineItems } from "./line-items"; +import { useLineItemsCellRenderersByColumn } from "./line-items-cell"; +import type { lineItemsEditors } from "./editor-factory"; +import { useLineItems } from "./use-line-items"; +import type { LineItemsColumn, UseLineItemsReturn } from "./types"; + +afterEach(() => { + cleanup(); + vi.restoreAllMocks(); +}); + +type Row = { + id?: string; + name: string | null; + quantity: number | null; + status: string | null; + date: string | null; + allowed: boolean; +}; +const rows: Row[] = [ + { id: "A", name: "Widget", quantity: 2, status: "open", date: "2026-10-02", allowed: true }, +]; +const nameColumn = { + accessorKey: "name", + label: "Name", + type: "text", + edit: { editorType: "text" }, +} satisfies LineItemsColumn; +const quantityColumn = { + accessorKey: "quantity", + label: "Quantity", + type: "number", + edit: { editorType: "number" }, +} satisfies LineItemsColumn; +const statusColumn = { + accessorKey: "status", + label: "Status", + type: "text", + edit: { + editorType: "combobox", + editorOptions: { + options: [ + { value: "open", label: "Open" }, + { value: "closed", label: "Closed" }, + ], + }, + }, +} satisfies LineItemsColumn; +const dateColumn = { + accessorKey: "date", + label: "Date", + type: "date", + edit: { editorType: "date" }, +} satisfies LineItemsColumn; +const editorColumns = { + text: nameColumn, + number: quantityColumn, + combobox: statusColumn, + date: dateColumn, +} satisfies Record>; +const canEdit = (row: Row) => row.allowed; +const configurations = buildConfigurations({ modules: [], locale: "en", timeZone: "Asia/Tokyo" }); + +function setup( + initialColumns: LineItemsColumn[] = [nameColumn, quantityColumn], + initialRows = rows, + orderer = false, +) { + let value!: UseLineItemsReturn; + function Harness({ columns, show = true }: { columns: LineItemsColumn[]; show?: boolean }) { + value = useLineItems({ columns, defaultLines: initialRows, orderer }); + return ( + + + + + {show && } + + + + + + ); + } + const view = render(, { wrapper: StrictMode }); + return { + ...view, + user: userEvent.setup(), + get value() { + return value; + }, + update: (columns = initialColumns, show = true) => + view.rerender(), + }; +} +const textbox = (name = "Name") => + screen.getByRole("textbox", { name: `${name}, Row 1` }) as HTMLInputElement; +const combobox = () => screen.getByRole("combobox", { name: "Status, Row 1" }) as HTMLInputElement; +const dateTrigger = () => screen.getByRole("button", { name: /^Date, Row 1/ }); +const calendar = () => + document.querySelector('[data-slot="line-items-cell-calendar"]')!; +const dayButton = (day: string) => + within(calendar()) + .getAllByRole("button") + .find((button) => button.textContent === day && !button.dataset.outsideMonth)!; +function draft(input: HTMLInputElement, text: string) { + act(() => input.focus()); + fireEvent.change(input, { target: { value: text } }); +} +function deferred() { + let resolve!: () => void; + const promise = new Promise((success) => { + resolve = success; + }); + return { promise, resolve }; +} +async function resolveRequest(request: ReturnType) { + await act(async () => { + request.resolve(); + await request.promise; + }); +} + +describe("LineItems cell editing integration", () => { + it("keeps column keys on editable cells and their headers", () => { + setup([nameColumn]); + expect(screen.getByRole("columnheader").getAttribute("data-col-key")).toBe("name"); + expect(screen.getByRole("cell").getAttribute("data-col-key")).toBe("name"); + }); + + it("updates cell styling props without replacing an editor or discarding its draft", () => { + const column = { + ...nameColumn, + headerProps: () => ({ title: "Styled name" }), + cellProps: (row: Row) => ({ + className: "astw:py-1", + style: { backgroundColor: "red" }, + title: row.id, + }), + } satisfies LineItemsColumn; + const editor = setup([column]); + const input = textbox(); + const cell = screen.getByRole("cell"); + expect(cell.title).toBe("A"); + expect(cell.style.backgroundColor).toBe("red"); + expect(cell.className).toContain("astw:py-1"); + draft(input, "Changed"); + editor.update([{ ...column, headerProps: () => undefined, cellProps: () => undefined }]); + expect(textbox()).toBe(input); + expect(input.value).toBe("Changed"); + expect(cell.title).toBe(""); + expect(cell.style.backgroundColor).toBe(""); + expect(cell.className).toContain("astw:py-2"); + expect(screen.getByRole("columnheader").title).toBe(""); + expect(editor.value.isDirty).toBe(false); + fireEvent.keyDown(input, { key: "Enter" }); + expect(editor.value.lines[0].name).toBe("Changed"); + }); + + it("memoizes cell renderers by columns and time zone", () => { + const columns: LineItemsColumn[] = [nameColumn]; + const { result, rerender } = renderHook( + (props: { columns: LineItemsColumn[]; timeZone: string }) => + useLineItemsCellRenderersByColumn(props.columns, props.timeZone), + { initialProps: { columns, timeZone: "UTC" } }, + ); + const initial = result.current; + rerender({ columns, timeZone: "UTC" }); + expect(result.current).toBe(initial); + rerender({ columns, timeZone: "Asia/Tokyo" }); + expect(result.current).not.toBe(initial); + const timeZoneChanged = result.current; + rerender({ + columns: [{ ...nameColumn, render: () => "Custom label" }], + timeZone: "Asia/Tokyo", + }); + expect(result.current).not.toBe(timeZoneChanged); + expect(result.current[0].renderDisplay(rows[0], false)).toBe("Custom label"); + }); + + it.each([ + { name: "text", column: nameColumn, align: "left" }, + { name: "number", column: quantityColumn, align: "right" }, + { name: "choice", column: statusColumn, align: "left" }, + { + name: "money display", + column: { ...quantityColumn, type: "money" } satisfies LineItemsColumn, + align: "right", + }, + { + name: "number editor with text display", + column: { ...quantityColumn, type: "text" } satisfies LineItemsColumn, + align: "left", + }, + { + name: "explicit alignment", + column: { ...quantityColumn, align: "center" } satisfies LineItemsColumn, + align: "center", + }, + { + name: "readonly number", + column: { accessorKey: "quantity", type: "number" } satisfies LineItemsColumn, + align: "right", + }, + { + name: "computed money", + column: { + id: "computed", + type: "money", + accessor: (row: Row) => row.quantity, + } satisfies LineItemsColumn, + align: "right", + }, + ])("prepares resolved alignment for $name", ({ column, align }) => { + const { result } = renderHook(() => useLineItemsCellRenderersByColumn([column], "UTC")); + expect(result.current[0].align).toBe(align); + }); + + it("rebinds date formatting on timezone changes independently of a text editor", () => { + const columns: LineItemsColumn[] = [ + { + ...dateColumn, + typeOptions: { locale: "en-US" }, + edit: nameColumn.edit, + }, + ]; + const row = { ...rows[0], date: "2026-10-09T01:00:00Z" }; + const { result, rerender } = renderHook( + ({ timeZone }: { timeZone: string }) => useLineItemsCellRenderersByColumn(columns, timeZone), + { initialProps: { timeZone: "UTC" } }, + ); + expect(result.current[0].renderDisplay(row, false)).toBe("Oct 9, 2026"); + rerender({ timeZone: "America/Los_Angeles" }); + expect(result.current[0].renderDisplay(row, false)).toBe("Oct 8, 2026"); + }); + + it("preserves a cell draft and its row identity through keyboard reordering", () => { + const editor = setup([nameColumn], [rows[0], { ...rows[0], id: "B", name: "Second" }], true); + draft(textbox(), "Changed"); + fireEvent.keyDown(screen.getByRole("button", { name: "Reorder line 1" }), { key: "ArrowDown" }); + expect(editor.value.lines.map((row) => row.id)).toEqual(["B", "A"]); + const moved = screen.getByRole("textbox", { name: "Name, Row 2" }) as HTMLInputElement; + expect(moved.value).toBe("Changed"); + fireEvent.keyDown(moved, { key: "Enter" }); + expect(editor.value.lines.map((row) => row.name)).toEqual(["Second", "Changed"]); + }); + + it("keeps drafts out of dirty rows, adopts Enter and native Tab, and cancels Escape", async () => { + const editor = setup(); + const name = textbox(); + draft(name, "Changed"); + expect(editor.value.lines[0].name).toBe("Widget"); + expect(editor.value.isDirty).toBe(false); + fireEvent.keyDown(name, { key: "Enter" }); + expect(editor.value.lines[0].name).toBe("Changed"); + expect(editor.value.isDirty).toBe(true); + draft(name, "Canceled"); + fireEvent.keyDown(name, { key: "Escape" }); + expect(name.value).toBe("Changed"); + expect(editor.value.lines[0].name).toBe("Changed"); + draft(name, "Tabbed"); + await editor.user.tab(); + expect(editor.value.lines[0].name).toBe("Tabbed"); + expect(document.activeElement).toBe(textbox("Quantity")); + act(() => editor.value.revert()); + expect(editor.value.lines[0].name).toBe("Widget"); + expect(editor.value.isDirty).toBe(false); + }); + + it("normalizes numeric input, rejects malformed grouping, and explicitly clears to null", () => { + const editor = setup([quantityColumn]); + const input = textbox("Quantity"); + draft(input, "¥1,234.50"); + fireEvent.keyDown(input, { key: "Enter" }); + expect(editor.value.lines[0].quantity).toBe(1234.5); + draft(input, "1,5"); + fireEvent.keyDown(input, { key: "Enter" }); + expect(input.getAttribute("aria-invalid")).toBe("true"); + expect(editor.value.lines[0].quantity).toBe(1234.5); + draft(input, ""); + fireEvent.keyDown(input, { key: "Enter" }); + expect(editor.value.lines[0].quantity).toBeNull(); + }); + + it("keeps money display independent of the number editor and uses the current row's currency", () => { + const currency = vi.fn((row: Row) => (row.allowed ? "USD" : "EUR")); + const editor = setup( + [ + { + ...quantityColumn, + type: "money", + typeOptions: { currency }, + edit: { ...quantityColumn.edit, canEdit }, + }, + ], + [rows[0], { ...rows[0], id: "B", allowed: false }], + ); + const usd = new Intl.NumberFormat(undefined, { style: "currency", currency: "USD" }); + const eur = new Intl.NumberFormat(undefined, { style: "currency", currency: "EUR" }); + expect(screen.getAllByRole("cell").map((cell) => cell.textContent)).toEqual([ + usd.format(2), + eur.format(2), + ]); + const input = textbox("Quantity"); + draft(input, "3.5"); + fireEvent.keyDown(input, { key: "Enter" }); + expect(editor.value.lines[0].quantity).toBe(3.5); + expect(screen.getAllByRole("cell")[0].textContent).toBe(usd.format(3.5)); + expect(currency).toHaveBeenCalledWith(editor.value.lines[0]); + }); + + it("updates column widths without discarding an unconfirmed cell draft", () => { + const editor = setup([nameColumn]); + const input = textbox(); + draft(input, "Changed"); + editor.update([{ ...nameColumn, width: 240 }]); + expect((screen.getByRole("columnheader") as HTMLTableCellElement).style.width).toBe("240px"); + expect(textbox()).toBe(input); + expect(input.value).toBe("Changed"); + expect(editor.value.isDirty).toBe(false); + fireEvent.keyDown(input, { key: "Enter" }); + expect(editor.value.lines[0].name).toBe("Changed"); + }); + + it.each(["idle", "editing"] as const)( + "keeps a mounted %s editor usable when its column ID is rebound to another owned property", + (state) => { + const column = { ...nameColumn, id: "editable" }; + const editor = setup([column, { id: "other", accessorKey: "status" }]); + const input = textbox(); + if (state === "editing") draft(input, "Discarded"); + + editor.update([ + { ...column, accessorKey: "status" }, + { id: "other", accessorKey: "name" }, + ]); + + expect(textbox()).toBe(input); + expect(input.value).toBe("open"); + expect(editor.value.isDirty).toBe(false); + draft(input, "Canceled by command"); + expect(input.value).toBe("Canceled by command"); + act(() => editor.value.updateField("A", "status", "Command")); + expect(input.value).toBe("Command"); + draft(input, "Changed"); + expect(input.value).toBe("Changed"); + fireEvent.keyDown(input, { key: "Enter" }); + expect(editor.value.lines[0]).toMatchObject({ name: "Widget", status: "Changed" }); + }, + ); + + it("discards a pending check when a retained column is rebound and accepts the next edit", async () => { + const request = deferred(); + const check = vi.fn().mockImplementationOnce(() => request.promise); + const column = { + ...nameColumn, + id: "editable", + edit: { ...nameColumn.edit, onValueCommitted: check }, + }; + const editor = setup([column, { id: "other", accessorKey: "status" }]); + const input = textbox(); + draft(input, "Stale"); + fireEvent.keyDown(input, { key: "Enter" }); + expect(check).toHaveBeenCalledTimes(1); + expect(input.closest("td")?.getAttribute("aria-busy")).toBe("true"); + + editor.update([ + { ...column, accessorKey: "status" }, + { id: "other", accessorKey: "name" }, + ]); + + expect(textbox()).toBe(input); + expect(input.value).toBe("open"); + expect(input.closest("td")?.getAttribute("aria-busy")).not.toBe("true"); + draft(input, "Current"); + await resolveRequest(request); + expect(input.value).toBe("Current"); + expect(editor.value.lines[0]).toMatchObject({ name: "Widget", status: "open" }); + expect(editor.value.isDirty).toBe(false); + fireEvent.keyDown(input, { key: "Enter" }); + expect(check).toHaveBeenCalledTimes(2); + expect(editor.value.lines[0]).toMatchObject({ name: "Widget", status: "Current" }); + }); + + it("does not confirm an IME conversion as an editor commit", () => { + const editor = setup([nameColumn]); + const input = textbox(); + draft(input, "変換中"); + fireEvent.compositionStart(input); + fireEvent.keyDown(input, { key: "Enter", isComposing: true }); + expect(editor.value.lines[0].name).toBe("Widget"); + fireEvent.compositionEnd(input); + fireEvent.keyDown(input, { key: "Enter" }); + expect(editor.value.lines[0].name).toBe("変換中"); + }); + + it("shows fixed choice labels for readonly cells and adopts selected values, not labels", async () => { + const column: LineItemsColumn = { + ...statusColumn, + edit: { ...statusColumn.edit!, canEdit }, + }; + const editor = setup([column], [rows[0], { ...rows[0], id: "B", allowed: false }]); + expect(screen.getAllByRole("cell").map((cell) => cell.textContent)).toEqual(["Open", "Open"]); + expect(screen.getAllByRole("combobox")).toHaveLength(1); + await editor.user.click(combobox()); + await editor.user.click(screen.getByRole("option", { name: "Closed" })); + expect(editor.value.lines[0].status).toBe("closed"); + expect(editor.value.lines[1].status).toBe("open"); + expect(editor.value.isDirty).toBe(true); + }); + + it.each([ + { status: "open", text: "Open", badge: "Open" }, + { status: "unlisted", text: "unlisted", badge: "unlisted" }, + { status: null, text: "—", badge: "—" }, + { status: "", text: "—", badge: "—" }, + { status: "blank", text: "—", badge: "" }, + ])("preserves text and badge label fallbacks for $status", ({ status, text, badge }) => { + const edit = { + ...statusColumn.edit, + editorOptions: { + options: [...statusColumn.edit.editorOptions.options, { value: "blank", label: "" }], + }, + canEdit: () => false, + }; + setup( + [ + { ...statusColumn, id: "text", edit }, + { ...statusColumn, id: "badge", type: "badge", edit }, + ], + [{ ...rows[0], status }], + ); + expect(screen.getAllByRole("cell").map((cell) => cell.textContent)).toEqual([text, badge]); + }); + + it("retains link navigation and keyboard focus for readonly rows of an editable link column", async () => { + const href = vi.fn((row: Row) => `/products/${row.id}`); + const column: LineItemsColumn = { + ...nameColumn, + type: "link", + typeOptions: { href }, + edit: { ...nameColumn.edit, canEdit }, + }; + const editor = setup( + [column], + [rows[0], { ...rows[0], id: "B", name: "Second", allowed: false }], + ); + const link = screen.getByRole("link", { name: "Second" }); + expect(link.getAttribute("href")).toBe("/products/B"); + expect(screen.getAllByRole("link")).toHaveLength(1); + expect(screen.getAllByRole("textbox")).toHaveLength(1); + expect(href.mock.calls.every(([row]) => !row.allowed)).toBe(true); + + await editor.user.tab(); + expect(document.activeElement).toBe(textbox()); + await editor.user.tab(); + expect(document.activeElement).toBe(link); + }); + + it("switches between a link and an editor when row permissions change", () => { + const column: LineItemsColumn = { + ...nameColumn, + type: "link", + typeOptions: { href: (row) => `/products/${row.id}` }, + edit: { ...nameColumn.edit, canEdit }, + }; + const editor = setup([column, { accessorKey: "allowed" }]); + const input = textbox(); + draft(input, "Discarded"); + expect(screen.queryByRole("link")).toBeNull(); + act(() => editor.value.updateField("A", "allowed", false)); + expect(screen.queryByRole("textbox")).toBeNull(); + expect(screen.getByRole("link", { name: "Widget" }).getAttribute("href")).toBe("/products/A"); + act(() => editor.value.updateField("A", "allowed", true)); + expect(screen.queryByRole("link")).toBeNull(); + expect(textbox()).not.toBe(input); + expect(textbox().value).toBe("Widget"); + draft(textbox(), "Changed"); + fireEvent.keyDown(textbox(), { key: "Enter" }); + expect(editor.value.lines[0].name).toBe("Changed"); + }); + + it("retains choice labels for both editable and readonly link cells", () => { + const column: LineItemsColumn = { + ...statusColumn, + type: "link", + typeOptions: { href: (row) => `/products/${row.id}` }, + edit: { ...statusColumn.edit, canEdit }, + }; + setup([column], [rows[0], { ...rows[0], id: "B", allowed: false }]); + expect(screen.getAllByRole("cell").map((cell) => cell.textContent)).toEqual(["Open", "Open"]); + expect(screen.getAllByRole("combobox")).toHaveLength(1); + expect(screen.getByRole("link", { name: "Open" }).getAttribute("href")).toBe("/products/B"); + }); + + it.each(["content", "null"] as const)( + "preserves custom %s rendering for editable and readonly link cells", + (kind) => { + const href = vi.fn((row: Row) => `/products/${row.id}`); + const column: LineItemsColumn = { + ...nameColumn, + type: "link", + typeOptions: { href }, + render: () => (kind === "content" ? Custom label : null), + edit: { ...nameColumn.edit, canEdit }, + }; + setup([column], [rows[0], { ...rows[0], id: "B", name: "Second", allowed: false }]); + expect(screen.queryByRole("link")).toBeNull(); + expect(screen.queryByText("Widget")).toBeNull(); + expect(screen.queryByText("Second")).toBeNull(); + expect(screen.queryAllByText("Custom label")).toHaveLength(kind === "content" ? 2 : 0); + expect(href).not.toHaveBeenCalled(); + }, + ); + + it("skips choice-label lookup for custom-rendered readonly cells", () => { + const options = [...statusColumn.edit.editorOptions.options]; + const find = vi.spyOn(options, "find"); + setup([ + { + ...statusColumn, + render: () => null, + edit: { ...statusColumn.edit, editorOptions: { options }, canEdit: () => false }, + }, + ]); + expect(screen.getByRole("cell").textContent).toBe(""); + expect(find).not.toHaveBeenCalled(); + }); + + it("uses the same badges for fixed-choice display and menu labels", async () => { + const column: LineItemsColumn = { + ...statusColumn, + type: "badge", + typeOptions: { badgeVariantMap: { open: "success", closed: "neutral" } }, + }; + const editor = setup([column]); + expect(screen.getByRole("cell").textContent).toBe("Open"); + await editor.user.click(combobox()); + await editor.user.click(screen.getByRole("option", { name: "Closed" })); + expect(editor.value.lines[0].status).toBe("closed"); + expect(screen.getByRole("cell").textContent).toBe("Closed"); + }); + + it("adopts a calendar day and an explicit clear without changing the row key", async () => { + const editor = setup([dateColumn]); + await editor.user.click(dateTrigger()); + await editor.user.click(dayButton("20")); + expect(editor.value.lines[0].date).toBe("2026-10-20"); + expect(editor.value.getLineKey(editor.value.lines[0])).toBe("A"); + await editor.user.click(dateTrigger()); + await editor.user.click(screen.getByRole("button", { name: "Clear" })); + expect(editor.value.lines[0].date).toBeNull(); + }); + + it.each([false, true])( + "applies Calendar date restrictions through editorOptions (withTime: %s)", + async (withTime) => { + const commit = vi.fn(); + const column: LineItemsColumn = { + ...dateColumn, + edit: { + editorType: "date" as const, + editorOptions: { + withTime, + minValue: parseDate("2026-10-05"), + maxValue: parseDate("2026-10-25"), + isDateUnavailable: (day: DateValue) => day.day === 10, + }, + onValueCommitted: commit, + }, + }; + const editor = setup([column], [{ ...rows[0], date: "2026-10-15" }]); + await editor.user.click(dateTrigger()); + for (const day of ["4", "10", "26"]) { + const button = dayButton(day); + expect(button.getAttribute("aria-disabled")).toBe("true"); + await editor.user.click(button); + act(() => button.focus()); + await editor.user.keyboard("{Enter}"); + expect(editor.value.lines[0].date).toBe("2026-10-15"); + expect(commit).not.toHaveBeenCalled(); + } + await editor.user.click(dayButton("20")); + if (withTime) { + fireEvent.change(screen.getByLabelText("Date, Row 1 (Time)"), { + target: { value: "14:30" }, + }); + expect(commit).not.toHaveBeenCalled(); + await editor.user.click(screen.getByRole("button", { name: "Done" })); + } + expect(editor.value.lines[0].date).toBe(withTime ? "2026-10-20T05:30:00.000Z" : "2026-10-20"); + expect(commit).toHaveBeenCalledOnce(); + await editor.user.click(dateTrigger()); + await editor.user.click(screen.getByRole("button", { name: "Clear" })); + expect(editor.value.lines[0].date).toBeNull(); + }, + ); + + it.each(["before", "after", "unavailable"] as const)( + "does not confirm a time-only edit on a %s restricted day", + async (restriction) => { + const commit = vi.fn(); + const column: LineItemsColumn = { + ...dateColumn, + edit: { + editorType: "date" as const, + editorOptions: { + withTime: true, + minValue: restriction === "before" ? parseDate("2026-10-05") : undefined, + maxValue: restriction === "after" ? parseDate("2026-10-01") : undefined, + isDateUnavailable: + restriction === "unavailable" ? (day: DateValue) => day.day === 2 : undefined, + }, + onValueCommitted: commit, + }, + }; + const editor = setup([column]); + await editor.user.click(dateTrigger()); + fireEvent.change(screen.getByLabelText("Date, Row 1 (Time)"), { + target: { value: "14:30" }, + }); + const done = screen.getByRole("button", { name: "Done" }) as HTMLButtonElement; + expect(done.disabled).toBe(true); + await editor.user.click(done); + expect(commit).not.toHaveBeenCalled(); + expect(editor.value.lines[0].date).toBe("2026-10-02"); + await editor.user.click(screen.getByRole("button", { name: "Clear" })); + expect(editor.value.lines[0].date).toBeNull(); + }, + ); + + it("binds the timezone to date input independently of text display", async () => { + const editor = setup( + [{ ...dateColumn, type: "text" }], + [{ ...rows[0], date: "2026-10-08T17:00:00Z" }], + ); + expect(screen.getByRole("cell").textContent).toBe("2026-10-08T17:00:00Z"); + await editor.user.click(dateTrigger()); + expect(dayButton("9").hasAttribute("data-selected")).toBe(true); + }); + + it("holds datetime drafts until Done and converts the configured timezone to an ISO timestamp", async () => { + const column: LineItemsColumn = { + ...dateColumn, + typeOptions: { dateFormat: "datetime" as const }, + edit: { editorType: "date" as const, editorOptions: { withTime: true } }, + }; + const editor = setup([column]); + await editor.user.click(dateTrigger()); + const done = screen.getByRole("button", { name: "Done" }) as HTMLButtonElement; + expect(done.disabled).toBe(true); + await editor.user.click(dayButton("20")); + fireEvent.change(screen.getByLabelText("Date, Row 1 (Time)"), { target: { value: "14:30" } }); + expect(editor.value.lines[0].date).toBe("2026-10-02"); + expect(editor.value.isDirty).toBe(false); + await editor.user.click(done); + expect(editor.value.lines[0].date).toBe("2026-10-20T05:30:00.000Z"); + }); + + it.each(["safe", "generic", "custom"] as const)( + "retains and retries a %s callback failure without adopting it", + async (kind) => { + const error = + kind === "safe" + ? new CellEditError("Please correct this value") + : new Error("Private service detail"); + const check = vi + .fn() + .mockImplementationOnce(() => { + throw error; + }) + .mockImplementation(() => {}); + const column: LineItemsColumn = { + ...nameColumn, + edit: { + editorType: "text" as const, + onValueCommitted: check, + error: + kind === "custom" + ? { + render: ({ row }: { row: Row; error: unknown }) => ( + {row.name}: custom failure + ), + } + : undefined, + }, + }; + const editor = setup([column]); + const input = textbox(); + draft(input, "Changed"); + fireEvent.keyDown(input, { key: "Enter" }); + expect(editor.value.lines[0].name).toBe("Widget"); + expect(editor.value.isDirty).toBe(false); + expect(input.value).toBe("Changed"); + expect(input.getAttribute("aria-invalid")).toBe("true"); + const popup = await screen.findByRole("dialog", { name: "Error for Name, Row 1" }); + const expected = { + safe: "Please correct this value", + custom: "Widget: custom failure", + generic: "The value could not be confirmed.", + }[kind]; + expect(within(popup).getByText(expected)).toBeDefined(); + expect(screen.queryByText("Private service detail")).toBeNull(); + expect(document.activeElement).toBe(input); + fireEvent.keyDown(input, { key: "Enter" }); + expect(check).toHaveBeenCalledTimes(2); + expect(editor.value.lines[0].name).toBe("Changed"); + }, + ); + + it.each(["write", "revert", "remove", "dispose"] as const)( + "ignores late async adoption after %s", + async (action) => { + const request = deferred(); + const check = vi.fn(() => request.promise); + const column: LineItemsColumn = { + ...nameColumn, + edit: { editorType: "text" as const, onValueCommitted: check }, + }; + const editor = setup([column]); + const input = textbox(); + draft(input, "Stale"); + fireEvent.keyDown(input, { key: "Enter" }); + expect(input.closest("td")?.getAttribute("aria-busy")).toBe("true"); + expect(editor.value.isDirty).toBe(false); + if (action === "write") act(() => editor.value.updateField("A", "name", "Command")); + if (action === "revert") act(() => editor.value.revert()); + if (action === "remove") act(() => editor.value.removeLine("A")); + if (action === "dispose") editor.unmount(); + await resolveRequest(request); + expect(editor.value.lines.map((row) => row.name)).toEqual( + action === "remove" ? [] : [action === "write" ? "Command" : "Widget"], + ); + }, + ); + + it("retains drafts across table view remounts and allows a detached pending cell to adopt", async () => { + const request = deferred(); + const column: LineItemsColumn = { + ...nameColumn, + edit: { editorType: "text" as const, onValueCommitted: () => request.promise }, + }; + const editor = setup([column]); + draft(textbox(), "Retained"); + editor.update([column], false); + expect(editor.value.isDirty).toBe(false); + editor.update([column]); + expect(textbox().value).toBe("Retained"); + fireEvent.keyDown(textbox(), { key: "Enter" }); + editor.update([column], false); + await resolveRequest(request); + expect(editor.value.lines[0].name).toBe("Retained"); + expect(editor.value.isDirty).toBe(true); + }); + + it.each(Object.entries(editorColumns))( + "keeps the %s input and local state when column preparation is recreated", + async (kind, column) => { + const editor = setup([column]); + const getControl = () => { + if (kind === "date") return dateTrigger(); + if (kind === "combobox") return combobox(); + return textbox(kind === "number" ? "Quantity" : "Name"); + }; + const control = getControl(); + if (kind === "date" || kind === "combobox") await editor.user.click(control); + if (kind === "combobox") await editor.user.type(control, "Clos"); + if (control instanceof HTMLInputElement && kind !== "combobox") + draft(control, kind === "number" ? "3." : "Retained"); + const focused = document.activeElement; + const popup = kind === "date" ? calendar() : null; + const inputValue = control instanceof HTMLInputElement ? control.value : undefined; + + editor.update([{ ...column }]); + + expect(getControl()).toBe(control); + expect(document.activeElement).toBe(focused); + if (kind === "date") expect(calendar()).toBe(popup); + if (control instanceof HTMLInputElement) expect(control.value).toBe(inputValue); + if (kind === "combobox") expect(combobox().getAttribute("aria-expanded")).toBe("true"); + expect(editor.value.isDirty).toBe(false); + }, + ); + + it("preserves a focused draft when editor callbacks are recreated and uses the latest callback", () => { + const before = vi.fn(); + const after = vi.fn(); + const column = (onValueCommitted: () => void): LineItemsColumn => ({ + ...nameColumn, + edit: { + ...nameColumn.edit, + onValueCommitted, + canEdit: (row: Row) => row.allowed, + error: { render: () => null }, + }, + }); + const editor = setup([column(before)]); + const input = textbox(); + draft(input, "Retained"); + editor.update([column(after)]); + expect(textbox()).toBe(input); + expect(document.activeElement).toBe(input); + expect(input.value).toBe("Retained"); + expect(editor.value.isDirty).toBe(false); + fireEvent.keyDown(input, { key: "Enter" }); + expect(editor.value.lines[0].name).toBe("Retained"); + expect(before).not.toHaveBeenCalled(); + expect(after).toHaveBeenCalledWith(expect.objectContaining({ id: "A" }), "Retained"); + }); + + it("applies changed row permissions without losing document state or adopting a pending edit", async () => { + const request = deferred(); + const column: LineItemsColumn = { + ...nameColumn, + edit: { + editorType: "text" as const, + canEdit: (row: Row) => row.allowed, + onValueCommitted: () => request.promise, + }, + }; + const editor = setup([column, { accessorKey: "allowed" }]); + draft(textbox(), "Stale"); + fireEvent.keyDown(textbox(), { key: "Enter" }); + act(() => editor.value.updateField("A", "allowed", false)); + expect(screen.queryByRole("textbox")).toBeNull(); + await resolveRequest(request); + expect(editor.value.lines[0]).toMatchObject({ name: "Widget", allowed: false }); + act(() => editor.value.updateField("A", "allowed", true)); + expect(textbox().value).toBe("Widget"); + }); + + it("retires pending edits when a stable predicate reads changed external permissions", async () => { + const request = deferred(); + let allowed = true; + const column: LineItemsColumn = { + ...nameColumn, + edit: { + editorType: "text" as const, + canEdit: () => allowed, + onValueCommitted: () => request.promise, + }, + }; + const editor = setup([column]); + draft(textbox(), "Stale"); + fireEvent.keyDown(textbox(), { key: "Enter" }); + allowed = false; + editor.update(); + expect(screen.queryByRole("textbox")).toBeNull(); + allowed = true; + editor.update(); + await resolveRequest(request); + expect(editor.value.lines[0].name).toBe("Widget"); + expect(textbox().value).toBe("Widget"); + }); + + it.each(["choice", "date"] as const)( + "closes an open %s popup when a direct command cancels its session", + async (kind) => { + const editor = setup([kind === "choice" ? statusColumn : dateColumn]); + await editor.user.click(kind === "choice" ? combobox() : dateTrigger()); + if (kind === "choice") expect(combobox().getAttribute("aria-expanded")).toBe("true"); + else expect(calendar()).not.toBeNull(); + act(() => { + if (kind === "choice") editor.value.updateField("A", "status", "closed"); + else editor.value.updateField("A", "date", "2026-10-25"); + }); + if (kind === "choice") { + expect(combobox().getAttribute("aria-expanded")).toBe("false"); + expect(combobox().value).toBe("Closed"); + } else expect(dateTrigger().getAttribute("aria-expanded")).toBe("false"); + }, + ); +}); diff --git a/packages/core/src/components/line-items/choice-display.test.tsx b/packages/core/src/components/line-items/choice-display.test.tsx new file mode 100644 index 000000000..1392f3a6b --- /dev/null +++ b/packages/core/src/components/line-items/choice-display.test.tsx @@ -0,0 +1,113 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { cleanup, render, screen, within } from "@testing-library/react"; +import { MemoryRouter } from "react-router"; +import { AppShellConfigContext, buildConfigurations } from "@/contexts/appshell-context"; +import { LineItems } from "./line-items"; +import { useLineItems } from "./use-line-items"; +import type { LineItemsColumn } from "./types"; + +afterEach(cleanup); +type Row = { id?: string; value: string | null; allowed: boolean }; +const rawValue = "2026-12-01"; +const choiceLabel = "First closing day"; +const edit = { + editorType: "combobox" as const, + canEdit: (row: Row) => row.allowed, + editorOptions: { options: [{ value: rawValue, label: choiceLabel }] }, +}; +const base = { accessorKey: "value" as const, label: "Value", edit }; +const configurations = buildConfigurations({ modules: [], locale: "en", timeZone: "UTC" }); + +function setup(column: LineItemsColumn) { + function Owner() { + const value = useLineItems({ + columns: [column], + defaultLines: [ + { id: "A", value: rawValue, allowed: true }, + { id: "B", value: rawValue, allowed: false }, + ], + orderer: false, + }); + return ( + + + + + + + + ); + } + return render(); +} + +describe("LineItems choice display policy", () => { + it("formats the raw date in both editable and readonly rows, not its choice label", () => { + setup({ + ...base, + type: "date", + typeOptions: { locale: "en-US", dateFormat: "short" }, + }); + expect(screen.getAllByRole("cell").map((cell) => cell.textContent)).toEqual([ + "Dec 1, 2026", + "Dec 1, 2026", + ]); + expect(screen.getByRole("combobox").value).toBe(choiceLabel); + }); + + it.each([undefined, "text", "link", "badge"] as const)( + "retains choice labels for %s display in editable and readonly rows", + (type) => { + const href = vi.fn((row: Row) => `/lines/${row.id}?date=${row.value}`); + let column: LineItemsColumn; + if (type === "link") column = { ...base, type, typeOptions: { href } }; + else if (type === "badge") + column = { + ...base, + type, + typeOptions: { badgeVariantMap: { [rawValue]: "success" } }, + }; + else column = { ...base, type }; + setup(column); + const cells = screen.getAllByRole("cell"); + expect(cells.map((cell) => cell.textContent)).toEqual([choiceLabel, choiceLabel]); + expect(screen.getAllByRole("combobox")).toHaveLength(1); + if (type === "link") { + expect(within(cells[0]).queryByRole("link")).toBeNull(); + expect(within(cells[1]).getByRole("link").getAttribute("href")).toBe( + `/lines/B?date=${rawValue}`, + ); + expect(href).toHaveBeenCalledWith(expect.objectContaining({ id: "B", value: rawValue })); + } + if (type === "badge") + for (const cell of cells) + expect(cell.querySelector('[class*="bg-success-solid"]')).not.toBeNull(); + }, + ); + + it.each(["text", "combobox"] as const)( + "passes only the public row argument to custom render with %s editing", + (editorType) => { + const custom = vi.fn((_row: Row) => null); + setup({ + ...base, + edit: editorType === "combobox" ? edit : { editorType, canEdit: edit.canEdit }, + render: custom, + }); + expect(custom.mock.calls.map((args) => args.length)).toEqual([1, 1]); + expect(custom.mock.calls.map(([row]) => row.id)).toEqual(["A", "B"]); + expect(screen.getAllByRole("cell").map((cell) => cell.textContent)).toEqual(["", ""]); + }, + ); + + it.each([null, "Custom date"])( + "keeps custom date output %s ahead of built-in formatting", + (output) => { + setup({ ...base, type: "date", render: () => output }); + expect(screen.getAllByRole("cell").map((cell) => cell.textContent)).toEqual([ + output ?? "", + output ?? "", + ]); + }, + ); +}); diff --git a/packages/core/src/components/line-items/choice-normalization.test.tsx b/packages/core/src/components/line-items/choice-normalization.test.tsx new file mode 100644 index 000000000..ccd23b7b6 --- /dev/null +++ b/packages/core/src/components/line-items/choice-normalization.test.tsx @@ -0,0 +1,76 @@ +import { afterEach, expect, it } from "vitest"; +import { cleanup, render, screen } from "@testing-library/react"; +import { MemoryRouter } from "react-router"; +import { LineItems } from "./line-items"; +import { useLineItems } from "./use-line-items"; +import type { LineItemsColumn, UseLineItemsReturn } from "./types"; + +afterEach(cleanup); +type Row = { id?: string; value: string | number | null | undefined; editable: boolean }; +const cases = [ + { raw: 1, expected: "One" }, + { raw: "1", expected: "One" }, + { raw: 0, expected: "Zero" }, + { raw: "0", expected: "Zero" }, + { raw: null, expected: "—" }, + { raw: undefined, expected: "—" }, + { raw: "", expected: "—" }, + { raw: "unlisted", expected: "unlisted" }, +]; + +it.each(["text", "link", "badge"] as const)( + "normalizes choice-label lookup for %s without changing adopted values", + (type) => { + const source = { + accessorKey: "value" as const, + label: "Value", + edit: { + editorType: "combobox" as const, + canEdit: (row: Row) => row.editable, + editorOptions: { + options: [ + { value: "1", label: "One" }, + { value: "0", label: "Zero" }, + { value: "null", label: "Not null" }, + { value: "undefined", label: "Not undefined" }, + { value: "", label: "Not empty" }, + ], + }, + }, + }; + const column: LineItemsColumn = + type === "link" + ? { ...source, type, typeOptions: { href: (row) => `/lines/${row.id}` } } + : { ...source, type }; + let value!: UseLineItemsReturn; + function Owner() { + value = useLineItems({ + columns: [column], + orderer: false, + defaultLines: cases.flatMap(({ raw }, index) => [ + { id: `${index}-editable`, value: raw, editable: true }, + { id: `${index}-readonly`, value: raw, editable: false }, + ]), + }); + return ( + + + + + + ); + } + render(); + expect(screen.getAllByRole("cell").map((cell) => cell.textContent)).toEqual( + cases.flatMap(({ expected }) => [expected, expected]), + ); + expect( + screen + .getAllByRole("combobox") + .slice(0, 4) + .map((input) => input.value), + ).toEqual(["One", "One", "Zero", "Zero"]); + expect(value.lines.map((row) => row.value)).toEqual(cases.flatMap(({ raw }) => [raw, raw])); + expect(value.isDirty).toBe(false); + }, +); diff --git a/packages/core/src/components/line-items/clear-value.test-d.ts b/packages/core/src/components/line-items/clear-value.test-d.ts new file mode 100644 index 000000000..035aba88a --- /dev/null +++ b/packages/core/src/components/line-items/clear-value.test-d.ts @@ -0,0 +1,115 @@ +import { expectTypeOf, test } from "vitest"; +import type { LineItemsColumn, LineItemsEditor } from "./types"; + +type Row = { + id?: string; + name: string; + quantity: number; + optional?: number; + nullable: number | null; + mixed: string | number | null; + status: "draft" | "confirmed"; +}; + +test("Clear policy is explicit when null does not fit the property", () => { + const columns: LineItemsColumn[] = [ + { + accessorKey: "name", + edit: { + editorType: "text", + clearValue: false, + onValueCommitted: (row, value) => { + expectTypeOf(row).toEqualTypeOf>(); + expectTypeOf(value).toEqualTypeOf(); + }, + }, + }, + { accessorKey: "name", edit: { editorType: "text", clearValue: () => "" } }, + { accessorKey: "quantity", edit: { editorType: "number", clearValue: () => 0 } }, + { + accessorKey: "optional", + edit: { + editorType: "number", + clearValue: () => undefined, + onValueCommitted: (_row, value) => { + expectTypeOf(value).toEqualTypeOf(); + }, + }, + }, + { + accessorKey: "nullable", + edit: { + editorType: "number", + onValueCommitted: (_row, value) => { + expectTypeOf(value).toEqualTypeOf(); + }, + }, + }, + { + accessorKey: "status", + edit: { + editorType: "combobox", + editorOptions: { options: [{ value: "draft", label: "Draft" }] }, + clearValue: () => "confirmed", + onValueCommitted: (_row, value) => { + expectTypeOf(value).toEqualTypeOf<"draft" | "confirmed">(); + }, + }, + }, + { + accessorKey: "mixed", + edit: { + editorType: "number", + clearValue: () => "not set", + onValueCommitted: (_row, value) => { + // Clear can return any synchronous property value, not just a number. + expectTypeOf(value).toEqualTypeOf(); + }, + }, + }, + ]; + void columns; + + // @ts-expect-error Required numbers cannot inherit the null Clear default. + const required: LineItemsEditor = { editorType: "number" }; + // @ts-expect-error Optional numbers also cannot inherit the null Clear default. + const optional: LineItemsEditor = { editorType: "number" }; + // @ts-expect-error A number property cannot accept a string Clear result. + const wrong: LineItemsEditor = { editorType: "number", clearValue: () => "" }; + const wrongEmpty: LineItemsEditor = { + editorType: "number", + // @ts-expect-error undefined is not part of this required property. + clearValue: () => undefined, + }; + // @ts-expect-error Clear resolution is synchronous, unlike the confirmation check. + const async: LineItemsEditor = { editorType: "number", clearValue: async () => 0 }; + const asyncUnknown: LineItemsEditor = { + editorType: "number", + // @ts-expect-error An unconstrained property does not permit asynchronous Clear resolution either. + clearValue: async () => 0, + }; + const outOfEnum: LineItemsEditor = { + editorType: "combobox", + editorOptions: { options: [{ value: "draft", label: "Draft" }] }, + // @ts-expect-error Clear must fit the enum just like the normal choices. + clearValue: () => "invalid", + }; + void required; + void optional; + void wrong; + void wrongEmpty; + void async; + void asyncUnknown; + void outOfEnum; +}); + +test("callbacks cover the property domain after Clear and keep the intentional void contract", () => { + type Editor = Extract, { editorType: "text" }>; + expectTypeOf>[1]>().toEqualTypeOf(); + const editor: LineItemsEditor = { + editorType: "number", + // @ts-expect-error Successful response values still need to be discarded by the caller. + onValueCommitted: () => Promise.resolve(new Response()), + }; + void editor; +}); diff --git a/packages/core/src/components/line-items/clear-value.test.tsx b/packages/core/src/components/line-items/clear-value.test.tsx new file mode 100644 index 000000000..3e041008e --- /dev/null +++ b/packages/core/src/components/line-items/clear-value.test.tsx @@ -0,0 +1,310 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { act, cleanup, fireEvent, render, screen } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { MemoryRouter } from "react-router"; +import { AppShellConfigContext, buildConfigurations } from "@/contexts/appshell-context"; +import { LineItems } from "./line-items"; +import { useLineItems } from "./use-line-items"; +import { createLineItemsDocumentStore } from "./document/store"; +import { createLineItemsEditing } from "./editing"; +import type { LineItemsColumn, LineItemsEditor, UseLineItemsReturn } from "./types"; + +afterEach(cleanup); +type Row = { id?: string; value?: string | number | null }; +type Kind = "text" | "number" | "combobox" | "date"; +const initialValue = (kind: Kind) => (kind === "number" ? 2 : "2026-12-01"); +function editor( + kind: Kind, + clearValue?: false | (() => Row["value"]), +): LineItemsEditor { + if (kind === "combobox") + return { + editorType: kind, + editorOptions: { options: [{ value: "2026-12-01", label: "First day" }] }, + clearValue, + }; + return { editorType: kind, clearValue }; +} +function setup( + edit: LineItemsEditor, + initial: Row["value"], + locale: "en" | "ja" = "en", +) { + let value!: UseLineItemsReturn; + const columns: LineItemsColumn[] = [{ accessorKey: "value", label: "Value", edit }]; + const configurations = buildConfigurations({ modules: [], locale, timeZone: "UTC" }); + function Owner({ show = true }: { show?: boolean }) { + value = useLineItems({ + columns, + defaultLines: [{ id: "A", value: initial }], + orderer: false, + }); + return ( + + + {show && } + + + ); + } + const view = render(); + return { + ...view, + get value() { + return value; + }, + user: userEvent.setup(), + rerender: () => view.rerender(), + }; +} +const textbox = () => screen.getByRole("textbox", { name: /^Value,/ }); +const dateTrigger = () => screen.getByRole("button", { name: /^Value,/ }); +async function clear(kind: Kind, user: ReturnType) { + if (kind === "date") { + await user.click(dateTrigger()); + await user.click(screen.getByRole("button", { name: "Clear" })); + } else if (kind === "combobox") { + await user.click(screen.getByRole("combobox")); + await user.click(screen.getByRole("option", { name: "None" })); + } else { + act(() => textbox().focus()); + fireEvent.change(textbox(), { target: { value: "" } }); + fireEvent.keyDown(textbox(), { key: "Enter" }); + } +} + +describe("LineItems Clear policy", () => { + it.each(["text", "number", "combobox", "date"])( + "resolves %s Clear to undefined before checking and adopting", + async (kind) => { + const resolve = vi.fn(() => undefined); + const check = vi.fn(); + const view = setup({ ...editor(kind, resolve), onValueCommitted: check }, initialValue(kind)); + view.rerender(); + expect(resolve).not.toHaveBeenCalled(); + await clear(kind, view.user); + expect(resolve).toHaveBeenCalledTimes(1); + expect(check).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ value: initialValue(kind) }), + undefined, + ); + expect(view.value.lines[0].value).toBeUndefined(); + expect(Object.hasOwn(view.value.lines[0], "value")).toBe(true); + expect(view.value.isDirty).toBe(true); + }, + ); + + it.each(["text", "number", "combobox", "date"])( + "keeps the existing null default for %s", + async (kind) => { + const check = vi.fn(); + const view = setup({ ...editor(kind), onValueCommitted: check }, initialValue(kind)); + await clear(kind, view.user); + expect(check).toHaveBeenCalledExactlyOnceWith(expect.anything(), null); + expect(view.value.lines[0].value).toBeNull(); + }, + ); + + it.each(["text", "number", "combobox", "date"])( + "does not resolve %s Clear merely by focusing/opening and leaving an empty value", + async (kind) => { + const resolve = vi.fn(() => null); + const check = vi.fn(); + const view = setup({ ...editor(kind, resolve), onValueCommitted: check }, undefined); + if (kind === "date") { + await view.user.click(dateTrigger()); + await view.user.keyboard("{Escape}"); + } else if (kind === "combobox") { + await view.user.click(screen.getByRole("combobox")); + await view.user.keyboard("{Escape}"); + } else { + await view.user.click(textbox()); + await view.user.tab(); + } + view.rerender(); + expect(resolve).not.toHaveBeenCalled(); + expect(check).not.toHaveBeenCalled(); + expect(view.value.lines[0].value).toBeUndefined(); + expect(view.value.isDirty).toBe(false); + }, + ); + + it.each( + (["text", "number"] as const).flatMap((kind) => + (["Enter", "Tab", "blur"] as const).map((action) => ({ kind, action })), + ), + )( + "rejects forbidden empty $kind input on $action without losing its draft", + ({ kind, action }) => { + const check = vi.fn(); + const view = setup({ ...editor(kind, false), onValueCommitted: check }, initialValue(kind)); + const input = textbox(); + act(() => input.focus()); + fireEvent.change(input, { target: { value: "" } }); + if (action === "blur") fireEvent.blur(input); + else fireEvent.keyDown(input, { key: action }); + expect(input.value).toBe(""); + expect(input.getAttribute("aria-invalid")).toBe("true"); + const description = input + .getAttribute("aria-describedby")! + .split(/\s+/) + .map((id) => document.getElementById(id)?.textContent) + .join(" "); + expect(description).toContain("This field cannot be cleared."); + fireEvent.keyDown(input, { key: "Tab" }); + fireEvent.blur(input); + view.rerender(); + expect(textbox().value).toBe(""); + expect(view.value.lines[0].value).toBe(initialValue(kind)); + expect(view.value.isDirty).toBe(false); + expect(check).not.toHaveBeenCalled(); + }, + ); + + it("retains and explains a forbidden Clear first attempted on blur", () => { + const check = vi.fn(); + const view = setup({ ...editor("number", false), onValueCommitted: check }, 2, "ja"); + const input = textbox(); + act(() => input.focus()); + fireEvent.change(input, { target: { value: "" } }); + fireEvent.blur(input); + expect(textbox().value).toBe(""); + expect(input.getAttribute("aria-invalid")).toBe("true"); + expect(screen.getByText("この項目は空にできません。", { selector: "p" })).toBeDefined(); + expect(view.value.lines[0].value).toBe(2); + expect(check).not.toHaveBeenCalled(); + }); + + it("omits None from a combobox that cannot be cleared", async () => { + const view = setup(editor("combobox", false), "2026-12-01"); + await view.user.click(screen.getByRole("combobox")); + expect(screen.queryByRole("option", { name: "None" })).toBeNull(); + expect(screen.getByRole("option", { name: "First day" })).toBeDefined(); + }); + + it.each([false, true])( + "omits date Clear while preserving calendar and datetime Done (withTime %s)", + async (withTime) => { + const view = setup( + { editorType: "date", editorOptions: { withTime }, clearValue: false }, + "2026-12-01", + ); + await view.user.click(dateTrigger()); + expect(screen.queryByRole("button", { name: "Clear" })).toBeNull(); + if (withTime) expect(screen.getByRole("button", { name: "Done" })).toBeDefined(); + expect(document.querySelector('[data-slot="line-items-cell-calendar"]')).not.toBeNull(); + }, + ); + + it.each([ + { kind: "text" as const, empty: "" }, + { kind: "number" as const, empty: 0 }, + ])("uses an explicitly chosen $empty for $kind", async ({ kind, empty }) => { + const check = vi.fn(); + const view = setup( + { ...editor(kind, () => empty), onValueCommitted: check }, + initialValue(kind), + ); + await clear(kind, view.user); + expect(check).toHaveBeenCalledExactlyOnceWith(expect.anything(), empty); + expect(view.value.lines[0].value).toBe(empty); + }); + + it("evaluates Clear once per pending confirmation and never adopts its unresolved output", async () => { + let finish!: () => void; + const pending = new Promise((resolve) => { + finish = resolve; + }); + const resolve = vi.fn(() => undefined); + const check = vi.fn(() => pending); + const view = setup({ ...editor("number", resolve), onValueCommitted: check }, 2); + const input = textbox(); + act(() => input.focus()); + fireEvent.change(input, { target: { value: "" } }); + expect(resolve).not.toHaveBeenCalled(); + fireEvent.keyDown(input, { key: "Enter" }); + fireEvent.keyDown(input, { key: "Enter" }); + view.rerender(); + expect(resolve).toHaveBeenCalledTimes(1); + expect(check).toHaveBeenCalledExactlyOnceWith(expect.anything(), undefined); + expect(view.value.lines[0].value).toBe(2); + expect(view.value.isDirty).toBe(false); + await act(async () => { + finish(); + await pending; + }); + expect(view.value.lines[0].value).toBeUndefined(); + expect(resolve).toHaveBeenCalledTimes(1); + }); + + it.each(["combobox", "date"] as const)( + "resolves explicit %s Clear from an empty value without treating open/close as Clear", + async (kind) => { + let finish!: () => void; + const pending = new Promise((resolve) => { + finish = resolve; + }); + const resolve = vi.fn(() => "2026-12-01"); + const check = vi.fn(() => pending); + const view = setup({ ...editor(kind, resolve), onValueCommitted: check }, undefined); + expect(resolve).not.toHaveBeenCalled(); + await clear(kind, view.user); + expect(resolve).toHaveBeenCalledTimes(1); + expect(check).toHaveBeenCalledExactlyOnceWith(expect.anything(), "2026-12-01"); + expect(view.value.lines[0].value).toBeUndefined(); + expect(document.querySelector('[data-slot="line-items-cell-confirming"]')).not.toBeNull(); + await act(async () => { + finish(); + await pending; + }); + expect(view.value.lines[0].value).toBe("2026-12-01"); + expect(resolve).toHaveBeenCalledTimes(1); + }, + ); + + it("does not run a check when the resolved Clear value is already adopted", async () => { + const resolve = vi.fn(() => 0); + const check = vi.fn(); + const view = setup({ ...editor("number", resolve), onValueCommitted: check }, 0); + await clear("number", view.user); + expect(resolve).toHaveBeenCalledTimes(1); + expect(check).not.toHaveBeenCalled(); + expect(view.value.lines[0].value).toBe(0); + expect(view.value.isDirty).toBe(false); + }); + + it("rejects asynchronous Clear results supplied by untyped callers", async () => { + const check = vi.fn(); + const invalid = { + editorType: "number", + clearValue: () => Promise.reject(new Error("Async Clear")), + onValueCommitted: check, + } as unknown as LineItemsEditor; + const view = setup(invalid, 2); + await clear("number", view.user); + expect(view.value.lines[0].value).toBe(2); + expect(view.value.isDirty).toBe(false); + expect(textbox().getAttribute("aria-invalid")).toBe("true"); + expect(check).not.toHaveBeenCalled(); + }); + + it("validates malformed Clear configuration and leaves direct document commands independent", () => { + const invalid = { editorType: "number", clearValue: 0 } as unknown as LineItemsEditor< + Row, + Row["value"] + >; + expect(() => setup(invalid, 2)).toThrow( + "LineItems clearValue must be false or a synchronous function", + ); + const columns: LineItemsColumn[] = [ + { accessorKey: "value", edit: editor("number", false) }, + ]; + const store = createLineItemsDocumentStore({ columns, lines: [{ id: "A", value: 2 }] }); + const editing = createLineItemsEditing(store, columns); + const session = editing.getSession(store.getSnapshot()[0], columns[0]); + session.change(""); + editing.updateField("A", "value", undefined); + expect(store.getSnapshot()[0].value).toBeUndefined(); + expect(session.getState()).toEqual({ status: "idle" }); + }); +}); diff --git a/packages/core/src/components/line-items/copied-value.test.tsx b/packages/core/src/components/line-items/copied-value.test.tsx new file mode 100644 index 000000000..9fd0b2119 --- /dev/null +++ b/packages/core/src/components/line-items/copied-value.test.tsx @@ -0,0 +1,92 @@ +import { StrictMode } from "react"; +import { afterEach, expect, it, vi } from "vitest"; +import { act, cleanup, fireEvent, render, renderHook, screen } from "@testing-library/react"; +import { MemoryRouter } from "react-router"; +import { AppShellConfigContext, buildConfigurations } from "@/contexts/appshell-context"; +import { getLineItemsEditing, LINE_ITEMS_EDITING } from "./editing"; +import { LineItems } from "./line-items"; +import { useLineItems } from "./use-line-items"; +import type { LineItemsColumn, UseLineItemsReturn } from "./types"; + +afterEach(cleanup); + +type Row = { id?: string; name: string | null }; +const configurations = buildConfigurations({ modules: [], locale: "en" }); + +it.each(["spread", "assign"] as const)( + "edits through a %s copy and retains the document draft across fresh copies and view remounts", + (copy) => { + const check = vi.fn(); + const columns: LineItemsColumn[] = [ + { accessorKey: "name", label: "Name", edit: { editorType: "text", onValueCommitted: check } }, + ]; + let value!: UseLineItemsReturn; + function Harness({ show = true }: { show?: boolean }) { + value = useLineItems({ + columns, + defaultLines: [{ id: "A", name: "Initial" }], + orderer: false, + }); + const copied = copy === "spread" ? { ...value } : Object.assign({}, value); + return ( + + + {show && } + + + ); + } + const view = render(, { wrapper: StrictMode }); + const original = value; + const input = screen.getByRole("textbox", { name: "Name, Row 1" }); + act(() => input.focus()); + fireEvent.change(input, { target: { value: "Retained" } }); + + view.rerender(); + expect(value).not.toBe(original); + expect(value[LINE_ITEMS_EDITING]).toBe(original[LINE_ITEMS_EDITING]); + expect(screen.getByRole("textbox")).toBe(input); + expect(input.value).toBe("Retained"); + expect(document.activeElement).toBe(input); + + view.rerender(); + expect(check).not.toHaveBeenCalled(); + expect(value.lines[0].name).toBe("Initial"); + expect(value.isDirty).toBe(false); + view.rerender(); + const restored = screen.getByRole("textbox", { name: "Name, Row 1" }); + expect(restored.value).toBe("Retained"); + fireEvent.keyDown(restored, { key: "Enter" }); + expect(check).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ name: "Initial" }), + "Retained", + ); + expect(value.lines[0].name).toBe("Retained"); + expect(value.isDirty).toBe(true); + }, +); + +it("keeps copied document handles isolated", () => { + const columns: LineItemsColumn[] = [{ accessorKey: "name", edit: { editorType: "text" } }]; + const { result } = renderHook(() => ({ + first: useLineItems({ columns, defaultLines: [{ id: "A", name: "First" }] }), + second: useLineItems({ columns, defaultLines: [{ id: "A", name: "Second" }] }), + })); + const first = getLineItemsEditing({ ...result.current.first }); + const second = getLineItemsEditing({ ...result.current.second }); + expect(first).not.toBe(second); + const firstSession = first.getSession(result.current.first.lines[0], columns[0]); + const secondSession = second.getSession(result.current.second.lines[0], columns[0]); + firstSession.begin("First draft"); + secondSession.begin("Second draft"); + act(() => result.current.first.updateField("A", "name", "Updated")); + expect(firstSession.getState()).toEqual({ status: "idle" }); + expect(secondSession.getState()).toEqual({ status: "editing", draft: "Second draft" }); + expect(result.current.second.lines[0].name).toBe("Second"); +}); + +it("rejects values without a document editing handle", () => { + expect(() => getLineItemsEditing({})).toThrow( + "Editable LineItems requires the value returned by useLineItems", + ); +}); diff --git a/packages/core/src/components/line-items/document/identity.test.ts b/packages/core/src/components/line-items/document/identity.test.ts new file mode 100644 index 000000000..935bb1a91 --- /dev/null +++ b/packages/core/src/components/line-items/document/identity.test.ts @@ -0,0 +1,81 @@ +import { describe, expect, it } from "vitest"; +import { clientKeyOf, createLineItemsIdentity, persistedId } from "./identity"; + +type Row = { id?: string | number; value: string }; + +describe("document-scoped line identity", () => { + it("normalizes valid persisted IDs and rejects invalid identities", () => { + expect(persistedId(undefined)).toBeUndefined(); + expect(persistedId(null)).toBeUndefined(); + expect(persistedId(0)).toBe("0"); + expect(persistedId(1)).toBe(persistedId("1")); + expect(persistedId(" A ")).toBe(" A "); + for (const value of ["", Number.NaN, Number.POSITIVE_INFINITY, true, {}]) { + expect(() => persistedId(value)).toThrow("non-empty strings or finite numbers"); + } + }); + + it("tags immutable copies with fresh client keys without registering persisted IDs", () => { + const identity = createLineItemsIdentity("id"); + const source = Object.freeze({ id: 0, value: "Initial" }); + const clientKey = identity.newClientKey(); + const tagged = identity.tag(source, clientKey); + expect(tagged).not.toBe(source); + expect(Object.isFrozen(tagged)).toBe(true); + expect(Object.getOwnPropertySymbols(source)).toHaveLength(0); + expect(identity.newClientKey()).not.toBe(clientKey); + expect(identity.getLineKey(tagged)).toBe(clientKey); + expect(clientKeyOf(tagged)).toBe(clientKey); + identity.remember([tagged]); + expect(identity.getLineKey({ ...tagged })).toBe("0"); + const updated = identity.tag({ ...tagged, value: "Updated" }, clientKey); + expect(identity.clientKeyOf(updated)).toBe(identity.clientKeyOf(tagged)); + expect(clientKeyOf({ ...updated })).toBe(clientKey); + expect(identity.getLineKey(updated)).toBe("0"); + expect(source.value).toBe("Initial"); + }); + + it("rejects untagged rows and rows owned by another factory", () => { + const identity = createLineItemsIdentity("id"); + const other = createLineItemsIdentity("id"); + const source: Row = { id: "A", value: "Initial" }; + expect(() => identity.clientKeyOf(source)).toThrow("does not belong"); + expect(() => clientKeyOf(source)).toThrow("does not belong"); + const foreign = other.tag(source, other.newClientKey()); + expect(() => identity.getLineKey(foreign)).toThrow("does not belong"); + }); + + it("resolves line keys only within the supplied current client keys", () => { + const identity = createLineItemsIdentity("id"); + const persistedClientKey = identity.newClientKey(); + const creationClientKey = identity.newClientKey(); + const persisted = identity.tag({ id: 0, value: "Persisted" }, persistedClientKey); + const creation = identity.tag({ value: "Creation" }, creationClientKey); + identity.remember([persisted, creation]); + const currentClientKeys = Object.freeze([persistedClientKey, creationClientKey]); + expect(identity.resolveClientKey("0", currentClientKeys)).toBe(persistedClientKey); + expect(identity.resolveClientKey(creationClientKey, currentClientKeys)).toBe(creationClientKey); + expect(() => identity.resolveClientKey("missing", currentClientKeys)).toThrow( + 'Unknown line "missing"', + ); + expect(() => identity.resolveClientKey("0", [creationClientKey])).toThrow('Unknown line "0"'); + expect(() => identity.resolveClientKey(creationClientKey, [])).toThrow("Unknown line"); + expect(() => identity.resolveClientKey(persistedClientKey, currentClientKeys)).toThrow( + "Unknown line", + ); + expect(identity.getLineKey(persisted)).toBe("0"); + expect(currentClientKeys).toEqual([persistedClientKey, creationClientKey]); + }); + + it("retains registered IDs until adoption, including identities for retired rows", () => { + const identity = createLineItemsIdentity("id"); + const clientKey = identity.newClientKey(); + const adopted = identity.tag({ id: "A", value: "Initial" }, clientKey); + identity.remember([adopted]); + const unadopted = identity.tag({ id: "Changed", value: "Candidate" }, clientKey); + expect(identity.getLineKey(unadopted)).toBe("A"); + identity.remember([]); + expect(identity.getLineKey(adopted)).toBe("A"); + expect(identity.getLineKey(unadopted)).toBe("A"); + }); +}); diff --git a/packages/core/src/components/line-items/document/identity.ts b/packages/core/src/components/line-items/document/identity.ts new file mode 100644 index 000000000..110ef761f --- /dev/null +++ b/packages/core/src/components/line-items/document/identity.ts @@ -0,0 +1,74 @@ +const IDENTITY = Symbol("LineItems.identity"); +type Identity = { owner: object; clientKey: string }; +type Tagged = { [IDENTITY]?: Identity }; + +/** Reads stable UI identity without exposing it through the public command API. */ +export function clientKeyOf(row: Record): string { + const identity = (row as Tagged)[IDENTITY]; + if (!identity) throw new Error("The line does not belong to a document"); + return identity.clientKey; +} + +/** Normalize a persisted ID without trimming strings or conflating zero with absence. */ +export function persistedId(value: unknown): string | undefined { + if (value === undefined || value === null) return undefined; + if ( + (typeof value !== "string" && typeof value !== "number") || + value === "" || + (typeof value === "number" && !Number.isFinite(value)) + ) + throw new Error("Line IDs must be non-empty strings or finite numbers"); + return String(value); +} + +/** + * Owns client keys and registered persisted IDs for one document lifetime. + * Candidate tags do not register persisted IDs. The document validates a complete + * snapshot first, then calls remember during adoption. Retired identities remain + * resolvable; current membership and duplicate-ID checks belong to the document. + * + * @internal + */ +export function createLineItemsIdentity>( + idKey: keyof T & string, +) { + const owner = {}; + const prefix = crypto.randomUUID(); + let serial = 0; + const persistedIds = new Map(); + const ownedClientKeyOf = (row: T): string => { + const identity = (row as Tagged)[IDENTITY]; + if (identity?.owner !== owner) throw new Error("The line does not belong to this document"); + return identity.clientKey; + }; + const toLineKey = (clientKey: string): string => persistedIds.get(clientKey) ?? clientKey; + + return { + /** Reads the client key, rejecting rows from outside this document owner. */ + clientKeyOf: ownedClientKeyOf, + /** Copies and shallow-freezes a row with its client key; spreads retain the tag. */ + tag: (row: T, clientKey: string): T => + Object.freeze({ ...row, [IDENTITY]: Object.freeze({ owner, clientKey }) }) as T, + /** Allocates a fresh client key without registering a row or persisted ID. */ + newClientKey: () => `line:${prefix}:${++serial}`, + /** Resolves a line key through the client tag, not potentially replaced row fields. */ + getLineKey: (row: T): string => toLineKey(ownedClientKeyOf(row)), + /** + * Resolves a line key within the caller's current client keys only. + * The registry may retain retired identities, but candidates define allowed membership. + * @throws If no candidate resolves to the requested line key. + */ + resolveClientKey(lineKey: string, currentClientKeys: readonly string[]): string { + const clientKey = currentClientKeys.find((candidate) => toLineKey(candidate) === lineKey); + if (clientKey === undefined) throw new Error(`Unknown line "${lineKey}"`); + return clientKey; + }, + /** + * Registers IDs for already-validated, adopted rows. Does not forget retired rows. + * The caller owns snapshot validation and decides when adoption is allowed. + */ + remember(rows: readonly T[]) { + for (const row of rows) persistedIds.set(ownedClientKeyOf(row), persistedId(row[idKey])); + }, + }; +} diff --git a/packages/core/src/components/line-items/document/index.ts b/packages/core/src/components/line-items/document/index.ts new file mode 100644 index 000000000..92c30b78a --- /dev/null +++ b/packages/core/src/components/line-items/document/index.ts @@ -0,0 +1 @@ +export type { LineItemsColumn } from "./types"; diff --git a/packages/core/src/components/line-items/document/model.test.ts b/packages/core/src/components/line-items/document/model.test.ts new file mode 100644 index 000000000..98c24ed77 --- /dev/null +++ b/packages/core/src/components/line-items/document/model.test.ts @@ -0,0 +1,188 @@ +import { describe, expect, it } from "vitest"; +import { createLineItemsDocument } from "./model"; +import type { LineItemsColumn } from "./types"; + +type Row = { + id?: string | number; + name: string; + quantity: number; + detail?: { count: number }; + hidden?: string; +}; +const columns: LineItemsColumn[] = [ + { accessorKey: "name", type: "text" }, + { accessorKey: "quantity", type: "number" }, + { accessorKey: "detail" }, +]; +const row = (id?: string | number, quantity = 1): Row => ({ id, name: "Item", quantity }); +const document = (lines: readonly Row[] = [row("A"), row("B")]) => + createLineItemsDocument({ columns, lines }); + +describe("LineItems document rows and identity", () => { + it("starts clean for persisted rows and retains immutable object-valued leaves", () => { + const detail = Object.freeze({ count: 1 }); + const source = Object.freeze({ ...row(0), detail }); + const doc = document([source]); + expect(doc.isDirty()).toBe(false); + expect(doc.getRows()[0]).not.toBe(source); + expect(doc.getRows()[0].detail).toBe(detail); + expect(Object.isFrozen(doc.getRows())).toBe(true); + expect(Object.isFrozen(doc.getRows()[0])).toBe(true); + expect(Object.getOwnPropertySymbols(source)).toHaveLength(0); + expect(doc.getLineKey(doc.getRows()[0])).toBe("0"); + }); + + it("uses the configured identity property for creation, updates and revert", () => { + type Custom = { code?: number; quantity: number }; + const doc = createLineItemsDocument({ + columns: [{ accessorKey: "quantity" }], + idKey: "code", + lines: [{ code: 0, quantity: 1 }], + }); + const source = Object.freeze({ code: 99, quantity: 2 }); + const key = doc.addLine(source); + expect(doc.getRows().map(doc.getLineKey)).toEqual(["0", key]); + expect(doc.getRows()[1].code).toBeUndefined(); + expect(source.code).toBe(99); + expect(() => doc.updateField("0", "code", 1)).toThrow("save acknowledgment"); + doc.updateField(key, "quantity", 3); + doc.revert(); + expect(doc.getRows()).toMatchObject([{ code: 0, quantity: 1 }]); + expect(doc.isDirty()).toBe(false); + }); + + it("treats ID-less initial rows as unsaved creations and discards them on revert", () => { + const doc = document([row("A"), row(), row()]); + const initial = doc.getRows(); + const keys = initial.map(doc.getLineKey); + expect(new Set(keys).size).toBe(3); + expect(doc.isDirty()).toBe(true); + doc.updateField(keys[1], "quantity", 2); + expect(doc.getLineKey(doc.getRows()[1])).toBe(keys[1]); + doc.removeLine("A"); + doc.revert(); + expect(doc.getRows()).toEqual([initial[0]]); + expect(doc.getLineKey(doc.getRows()[0])).toBe("A"); + expect(doc.isDirty()).toBe(false); + expect(() => doc.updateField(keys[1], "quantity", 3)).toThrow("Unknown line"); + }); + + it("retains line keys across row copies and sequential updates", () => { + const doc = document([row("A"), row()]); + const [oldPersisted, oldCreation] = doc.getRows(); + const lineKey = doc.getLineKey(oldCreation); + const update = doc.updateField; + update("A", "name", "Updated"); + update("A", "quantity", 2); + update(lineKey, "quantity", 3); + expect(doc.getRows()[0]).toMatchObject({ id: "A", name: "Updated", quantity: 2 }); + expect(doc.getRows()[0]).not.toBe(oldPersisted); + expect(doc.getLineKey(oldPersisted)).toBe("A"); + expect(doc.getLineKey(doc.getRows()[1])).toBe(lineKey); + expect(doc.getLineKey({ ...doc.getRows()[1] })).toBe(lineKey); + expect(oldPersisted.quantity).toBe(1); + expect(oldCreation.quantity).toBe(1); + const foreign = document([row("A")]); + expect(() => doc.getLineKey(foreign.getRows()[0])).toThrow("does not belong"); + expect(() => doc.getLineKey(row("A"))).toThrow("does not belong"); + }); + + it("tracks exact field values rather than row reference changes or display precision", () => { + const doc = document([row("A", 0.3)]); + const initial = doc.getRows(); + doc.updateField("A", "quantity", 0.3); + expect(doc.getRows()).toBe(initial); + doc.updateField("A", "quantity", 0.1 + 0.2); + expect(doc.isDirty()).toBe(true); + doc.updateField("A", "quantity", 0.3); + expect(doc.getRows()).not.toBe(initial); + expect(doc.isDirty()).toBe(false); + doc.updateField("A", "detail", { count: 1 }); + expect(doc.isDirty()).toBe(true); + doc.updateField("A", "detail", undefined); + expect(doc.isDirty()).toBe(false); + }); + + it("appends fresh creations without copied persisted IDs and cancels add/remove pairs", () => { + const source = Object.freeze(row("A")); + const doc = document([source]); + const added = doc.addLine(source); + expect(added).not.toBe("A"); + expect(doc.getRows()[1].id).toBeUndefined(); + expect(JSON.stringify(doc.getRows()[1])).not.toContain(added); + expect(source.id).toBe("A"); + expect(doc.isDirty()).toBe(true); + doc.removeLine(added); + expect(doc.isDirty()).toBe(false); + expect(doc.addLine(source)).not.toBe(added); + }); + + it("moves lines after an anchor or to the front without changing row identity", () => { + const doc = document([row("A"), row("B"), row("C")]); + const initial = doc.getRows(); + doc.reorderLine("A", "C"); + expect(doc.getRows()).toEqual([initial[1], initial[2], initial[0]]); + expect(doc.getRows()[2]).toBe(initial[0]); + expect(doc.isDirty()).toBe(true); + doc.reorderLine("A", null); + expect(doc.getRows()).toEqual(initial); + expect(doc.isDirty()).toBe(false); + doc.reorderLine("C", null); + expect(doc.getRows().map(doc.getLineKey)).toEqual(["C", "A", "B"]); + doc.revert(); + expect(doc.getRows()).toEqual(initial); + expect(doc.isDirty()).toBe(false); + }); + + it("rejects invalid moves and preserves the row view for no-op moves", () => { + const doc = document(); + const initial = doc.getRows(); + doc.reorderLine("A", "A"); + doc.reorderLine("A", null); + doc.reorderLine("B", "A"); + expect(() => doc.reorderLine("missing", "A")).toThrow("Unknown line"); + expect(() => doc.reorderLine("A", "missing")).toThrow("Unknown line"); + expect(doc.getRows()).toBe(initial); + expect(doc.isDirty()).toBe(false); + }); + + it("restores persisted values, membership and order on revert", () => { + const doc = document(); + const initial = doc.getRows(); + doc.updateField("A", "name", "Changed"); + doc.removeLine("A"); + const added = doc.addLine(row("C")); + expect(doc.getRows().map(doc.getLineKey)).toEqual(["B", added]); + doc.revert(); + expect(doc.getRows()).toEqual(initial); + expect(doc.getRows().map(doc.getLineKey)).toEqual(["A", "B"]); + expect(doc.isDirty()).toBe(false); + }); + + it("rejects unknown rows, unowned properties and identity changes before adoption", () => { + const doc = document(); + const initial = doc.getRows(); + expect(() => doc.updateField("A", "id", "C")).toThrow("save acknowledgment"); + expect(() => doc.updateField("A", "hidden", "hidden change")).toThrow("no document owner"); + expect(() => doc.updateField("missing", "quantity", 2)).toThrow("Unknown line"); + expect(() => doc.removeLine("missing")).toThrow("Unknown line"); + doc.updateField("A", "id", "A"); + expect(doc.getRows()).toBe(initial); + expect(doc.isDirty()).toBe(false); + }); + + it("accepts display-only reconfiguration but rejects changing property ownership", () => { + const doc = document(); + doc.assertColumns([ + ...columns.toReversed(), + { accessorKey: "quantity", id: "duplicate-display", label: "Also quantity" }, + { id: "computed", accessor: (line) => line.quantity * 2 }, + ]); + expect(() => doc.assertColumns([{ accessorKey: "name" }])).toThrow( + "change document property ownership", + ); + doc.updateField("A", "quantity", 2); + expect(doc.getRows()[0].quantity).toBe(2); + expect(doc.isDirty()).toBe(true); + }); +}); diff --git a/packages/core/src/components/line-items/document/model.ts b/packages/core/src/components/line-items/document/model.ts new file mode 100644 index 000000000..b6ba6462e --- /dev/null +++ b/packages/core/src/components/line-items/document/model.ts @@ -0,0 +1,190 @@ +import { assertLineItemsEditor } from "../editor-factory"; +import { createLineItemsIdentity, persistedId } from "./identity"; +import { createLineItemsSnapshots } from "./snapshot"; +import type { DocumentOptions, LineItemsColumn } from "./types"; + +/** Resolve document property ownership independently of display column identities. */ +function compileLineItemsColumns>( + columns: readonly LineItemsColumn[], +): ReadonlySet { + const ids = new Set(); + const properties = new Set(); + for (const column of columns) { + const id = column.id ?? column.accessorKey; + if (typeof id !== "string" || id === "" || ids.has(id)) + throw new Error("LineItems column IDs must be non-empty and unique"); + if (column.edit !== undefined) { + if (column.accessorKey === undefined) + throw new Error("Cell editors require an accessorKey property"); + assertLineItemsEditor(column.edit); + if ( + column.type === "badge" && + column.edit.editorType === "combobox" && + column.typeOptions?.badgeLabelMap !== undefined + ) + throw new Error("Combobox badge labels must be defined in editorOptions.options only"); + } + ids.add(id); + if (column.accessorKey !== undefined) properties.add(column.accessorKey); + } + return properties; +} + +/** + * Creates the domain model for one document's rows, identities, baseline, and adopted order. + * It has no subscriptions or framework integration; createLineItemsDocumentStore wraps + * its commands when callers need observable snapshots. + * + * Initial rows and subsequent row copies are shallow-frozen. Nested values are not + * cloned and must also be treated as immutable. Only initial rows with persisted IDs form + * the persisted baseline; ID-less initial rows are unsaved creations, start dirty, + * and are discarded by revert. This model does not advance the baseline or implement + * draft editing, business validation, normalization, or persistence. + * + * Inspection and configuration checks do not mutate state. Commands validate keys and + * ownership before adopting a new row view. Returned functions are stable and do not + * depend on this. Movement permissions belong to the caller, not the ordering primitive. + * + * @internal + */ +export function createLineItemsDocument>( + options: DocumentOptions, +) { + const { columns, lines = [] } = options; + const idKey = (options.idKey ?? "id") as keyof T & string; + const properties = compileLineItemsColumns(columns); + const identity = createLineItemsIdentity(idKey); + const snapshots = createLineItemsSnapshots(identity, idKey); + let current = snapshots.adopt(lines.map((row) => identity.tag(row, identity.newClientKey()))); + // ID-less initial rows are unsaved creations, not part of the persisted baseline. + const baseline = snapshots.create( + current.lines.filter((row) => persistedId(row[idKey]) !== undefined), + ); + + return { + /** Identity property captured at creation; a different idKey requires a new model. */ + idKey, + /** + * Returns the current shallow-frozen row view in adopted document order. + * Repeated reads are referentially equal until a command adopts a new array. + */ + getRows: () => current.lines, + /** + * Resolves a row's line key: its persisted ID, or its client key for an unsaved creation. + * Accepts owned rows, previously returned rows, and spreads retaining the client tag; + * rejects untagged or foreign rows. This is not a current-membership check: a removed + * row still resolves, but its line key cannot be used by commands until it is restored. + */ + getLineKey: identity.getLineKey, + /** + * Validates display definitions against the original property ownership without + * storing configuration or mutating rows. + * Reordering/renaming columns and adding duplicate displays of an owned property are + * allowed; changing the accessorKey property set requires a new document instance. + * @throws If column definitions are invalid or document property ownership changes. + */ + assertColumns(nextColumns: readonly LineItemsColumn[]) { + const next = compileLineItemsColumns(nextColumns); + if (next.size !== properties.size || [...next].some((key) => !properties.has(key))) + throw new Error("Remount LineItems to change document property ownership"); + }, + /** + * Inspects differences from the persisted initial baseline without modifying the model. + * Membership or adopted order changes are dirty, including ID-less initial creations. + * Owned field values use Object.is, not deep equality or formatted display precision; + * replacing a row object alone does not make it dirty. Drafts are not tracked here. + */ + isDirty() { + if ( + current.clientKeys.length !== baseline.clientKeys.length || + current.clientKeys.some((clientKey, index) => clientKey !== baseline.clientKeys[index]) + ) + return true; + for (const clientKey of current.clientKeys) { + const row = current.byClientKey.get(clientKey)!; + const base = baseline.byClientKey.get(clientKey)!; + for (const property of properties) { + if (property !== idKey && !Object.is(row[property], base[property])) return true; + } + } + return false; + }, + /** + * Replaces one current row with a copy containing an updated accessorKey-owned property, + * preserving its client key and reusing all other rows. Values are adopted as-is, + * without normalization or business validation. A valid Object.is-equal write is a no-op. + * @throws If the line key is not current, the property is unowned, or the persisted ID changes. + */ + updateField(lineKey: string, property: K, value: T[K]) { + const clientKey = identity.resolveClientKey(lineKey, current.clientKeys); + const row = current.byClientKey.get(clientKey)!; + if (property === idKey && !Object.is(row[property], value)) + throw new Error("Line IDs may only change through save acknowledgment"); + if (property !== idKey && !properties.has(property)) + throw new Error(`Property "${property}" has no document owner`); + if (Object.is(row[property], value)) return; + const updated = identity.tag({ ...row, [property]: value }, clientKey); + current = snapshots.adopt( + current.lines.map((line) => (identity.clientKeyOf(line) === clientKey ? updated : line)), + ); + }, + /** + * Appends an unsaved creation from a shallow copy of input. + * Drops the configured persisted ID and assigns a fresh client key even for an owned + * row. The input is not mutated, nested values are reused, and the baseline is unchanged. + * Returns the line key accepted by the row commands; the creation makes the + * document dirty until it is removed or discarded by revert. + */ + addLine(input: T): string { + const raw = { ...input }; + delete raw[idKey]; + const added = identity.tag(raw, identity.newClientKey()); + current = snapshots.adopt([...current.lines, added]); + return identity.getLineKey(added); + }, + /** + * Removes one current row without changing the baseline. + * Removing an unsaved creation can cancel its dirty contribution; removing a persisted + * row stays dirty until restored by revert. Remaining rows retain their objects and keys. + * @throws If the line key does not identify a current row. + */ + removeLine(lineKey: string) { + const clientKey = identity.resolveClientKey(lineKey, current.clientKeys); + current = snapshots.adopt( + current.lines.filter((row) => identity.clientKeyOf(row) !== clientKey), + ); + }, + /** + * Moves a current row immediately after another current row; null moves it to the front. + * Adopts a new view only when order changes, preserving row objects, identities, and + * membership. A self-anchor or unchanged position is a no-op. Movement permission is + * checked by the caller; this primitive does not enforce orderer. + * @throws If the moved row or a non-null anchor is not in the current document. + */ + reorderLine(lineKey: string, afterLineKey: string | null) { + const clientKey = identity.resolveClientKey(lineKey, current.clientKeys); + const afterClientKey = + afterLineKey === null ? null : identity.resolveClientKey(afterLineKey, current.clientKeys); + if (clientKey === afterClientKey) return; + const clientKeys = current.clientKeys.filter((candidate) => candidate !== clientKey); + clientKeys.splice( + afterClientKey === null ? 0 : clientKeys.indexOf(afterClientKey) + 1, + 0, + clientKey, + ); + if (clientKeys.some((candidate, index) => candidate !== current.clientKeys[index])) + current = snapshots.adopt( + clientKeys.map((candidate) => current.byClientKey.get(candidate)!), + ); + }, + /** + * Restores the persisted initial rows, values, and order without advancing the baseline. + * Discards every unsaved creation, including ID-less rows supplied at initialization. + * Restored rows retain their initial frozen objects and identities. Always adopts a new + * row array, even when already clean; this is restoration, not manual movement. + */ + revert() { + current = snapshots.adopt(baseline.lines); + }, + }; +} diff --git a/packages/core/src/components/line-items/document/snapshot.test.ts b/packages/core/src/components/line-items/document/snapshot.test.ts new file mode 100644 index 000000000..a242b96bb --- /dev/null +++ b/packages/core/src/components/line-items/document/snapshot.test.ts @@ -0,0 +1,67 @@ +import { describe, expect, it } from "vitest"; +import { createLineItemsIdentity } from "./identity"; +import { createLineItemsSnapshots } from "./snapshot"; + +type Row = { id?: string | number; value: string }; + +describe("document-bound snapshot factory", () => { + it("constructs an immutable row view and client-key indexes without registering candidates", () => { + const identity = createLineItemsIdentity("id"); + const snapshots = createLineItemsSnapshots(identity, "id"); + const firstClientKey = identity.newClientKey(); + const secondClientKey = identity.newClientKey(); + const first = identity.tag({ id: 0, value: "First" }, firstClientKey); + const second = identity.tag({ value: "Second" }, secondClientKey); + const input = [first, second]; + const candidate = snapshots.create(input); + expect(Object.isFrozen(candidate)).toBe(true); + expect(Object.isFrozen(candidate.lines)).toBe(true); + expect(Object.isFrozen(candidate.clientKeys)).toBe(true); + expect(candidate.lines).not.toBe(input); + expect(candidate.clientKeys).toEqual([firstClientKey, secondClientKey]); + expect(candidate.byClientKey.get(firstClientKey)).toBe(candidate.lines[0]); + expect(candidate.byClientKey.get(secondClientKey)).toBe(candidate.lines[1]); + input.reverse(); + expect(candidate.lines).toEqual([first, second]); + expect(identity.getLineKey(first)).toBe(firstClientKey); + }); + + it("registers adopted identities and returns fresh snapshots without owning current state", () => { + const identity = createLineItemsIdentity("id"); + const snapshots = createLineItemsSnapshots(identity, "id"); + const clientKey = identity.newClientKey(); + const row = identity.tag({ id: "A", value: "Initial" }, clientKey); + const first = snapshots.adopt([row]); + expect(identity.getLineKey(first.lines[0])).toBe("A"); + const second = snapshots.adopt(first.lines); + expect(second.lines).not.toBe(first.lines); + expect(second.lines[0]).toBe(first.lines[0]); + expect(first.clientKeys).toEqual([clientKey]); + expect(second.clientKeys).toEqual(first.clientKeys); + }); + + it("finishes duplicate and ownership validation before registering any identities", () => { + const identity = createLineItemsIdentity("id"); + const snapshots = createLineItemsSnapshots(identity, "id"); + const firstClientKey = identity.newClientKey(); + const first = identity.tag({ id: 1, value: "First" }, firstClientKey); + const alias = identity.tag({ id: "1", value: "Alias" }, identity.newClientKey()); + expect(() => snapshots.adopt([first, alias])).toThrow("Line IDs must be unique"); + expect(() => snapshots.adopt([first, first])).toThrow("Line IDs must be unique"); + const other = createLineItemsIdentity("id"); + const foreign = other.tag({ id: "B", value: "Foreign" }, other.newClientKey()); + expect(() => snapshots.adopt([first, foreign])).toThrow("does not belong"); + expect(identity.getLineKey(first)).toBe(firstClientKey); + }); + + it("uses the persisted-ID property bound at construction", () => { + type Custom = { code?: number; value: string }; + const identity = createLineItemsIdentity("code"); + const snapshots = createLineItemsSnapshots(identity, "code"); + const first = identity.tag({ code: 0, value: "First" }, identity.newClientKey()); + const alias = identity.tag({ code: 0, value: "Alias" }, identity.newClientKey()); + expect(() => snapshots.adopt([first, alias])).toThrow("Line IDs must be unique"); + const adopted = snapshots.adopt([first]); + expect(identity.getLineKey(adopted.lines[0])).toBe("0"); + }); +}); diff --git a/packages/core/src/components/line-items/document/snapshot.ts b/packages/core/src/components/line-items/document/snapshot.ts new file mode 100644 index 000000000..0045ff58d --- /dev/null +++ b/packages/core/src/components/line-items/document/snapshot.ts @@ -0,0 +1,50 @@ +import { persistedId } from "./identity"; +import type { LineItemsIdentity, LineItemsSnapshot } from "./types"; + +/** + * Binds one document's identity registry and persisted-ID property to snapshot construction. + * create validates and freezes a candidate without registering IDs; adopt additionally + * registers the validated rows and returns the snapshot for the document to assign. + * The factory owns no current state, baseline, subscriptions, or movement permissions. + * + * @internal + */ +export function createLineItemsSnapshots>( + identity: LineItemsIdentity, + idKey: keyof T & string, +) { + /** Validate row ownership and unique client/line keys before producing a fresh row view. */ + function create(input: readonly T[]): LineItemsSnapshot { + const byClientKey = new Map(); + const lineKeys = new Set(); + const clientKeys: string[] = []; + for (const row of input) { + const clientKey = identity.clientKeyOf(row); + const lineKey = persistedId(row[idKey]) ?? clientKey; + if (byClientKey.has(clientKey) || lineKeys.has(lineKey)) + throw new Error("Line IDs must be unique"); + byClientKey.set(clientKey, row); + lineKeys.add(lineKey); + clientKeys.push(clientKey); + } + return Object.freeze({ + lines: Object.freeze([...input]), + clientKeys: Object.freeze(clientKeys), + byClientKey, + }); + } + + return { + create, + /** + * Construct and register a validated snapshot; the caller remains responsible for + * replacing current state. Each call returns a fresh row view, including for revert. + * Validation completes before any identity registration occurs. + */ + adopt(input: readonly T[]): LineItemsSnapshot { + const next = create(input); + identity.remember(next.lines); + return next; + }, + }; +} diff --git a/packages/core/src/components/line-items/document/store.test.ts b/packages/core/src/components/line-items/document/store.test.ts new file mode 100644 index 000000000..8038bab86 --- /dev/null +++ b/packages/core/src/components/line-items/document/store.test.ts @@ -0,0 +1,96 @@ +import { describe, expect, it, vi } from "vitest"; +import { createLineItemsDocumentStore } from "./store"; +import type { LineItemsColumn } from "./types"; + +type Row = { id?: string; name: string; quantity: number; hidden?: string }; +const columns: LineItemsColumn[] = [ + { accessorKey: "name", type: "text" }, + { accessorKey: "quantity", type: "number" }, +]; +const store = () => + createLineItemsDocumentStore({ + columns, + lines: [ + { id: "A", name: "First", quantity: 1 }, + { id: "B", name: "Second", quantity: 1 }, + ], + }); + +describe("LineItems document store notifications", () => { + it("returns a cached snapshot without publishing reads or configuration checks", () => { + const value = store(); + const initial = value.getSnapshot(); + const listener = vi.fn(); + value.subscribe(listener); + expect(value.getSnapshot()).toBe(initial); + expect(Object.isFrozen(initial)).toBe(true); + expect(initial.every(Object.isFrozen)).toBe(true); + expect(value.getLineKey(initial[0])).toBe("A"); + expect(value.isDirty()).toBe(false); + value.assertColumns(columns.toReversed()); + expect(value.getSnapshot()).toBe(initial); + expect(listener).not.toHaveBeenCalled(); + }); + + it("notifies after adoption for every row command and preserves their return values", () => { + const value = store(); + const observed: { rows: readonly Row[]; dirty: boolean }[] = []; + const listener = vi.fn(() => + observed.push({ rows: value.getSnapshot(), dirty: value.isDirty() }), + ); + value.subscribe(listener); + const key = value.addLine({ name: "Added", quantity: 3 }); + expect(value.getLineKey(observed[0].rows[2])).toBe(key); + expect(observed[0].dirty).toBe(true); + value.updateField("A", "quantity", 2); + expect(observed[1].rows[0].quantity).toBe(2); + value.reorderLine(key, null); + expect(value.getLineKey(observed[2].rows[0])).toBe(key); + value.removeLine(key); + expect(observed[3].rows.map(value.getLineKey)).toEqual(["A", "B"]); + value.revert(); + expect(observed[4].rows).toBe(value.getSnapshot()); + expect(observed[4].rows[0].quantity).toBe(1); + expect(observed[4].dirty).toBe(false); + expect(listener).toHaveBeenCalledTimes(5); + }); + + it("does not notify or change the snapshot for invalid writes and no-ops", () => { + const value = store(); + const initial = value.getSnapshot(); + const listener = vi.fn(); + value.subscribe(listener); + value.updateField("A", "quantity", 1); + value.reorderLine("A", "A"); + value.reorderLine("A", null); + value.reorderLine("B", "A"); + expect(() => value.updateField("A", "id", "C")).toThrow("save acknowledgment"); + expect(() => value.updateField("A", "hidden", "hidden change")).toThrow("no document owner"); + expect(() => value.removeLine("missing")).toThrow("Unknown line"); + expect(() => value.reorderLine("A", "missing")).toThrow("Unknown line"); + expect(() => value.assertColumns([])).toThrow("change document property ownership"); + expect(value.getSnapshot()).toBe(initial); + expect(value.isDirty()).toBe(false); + expect(listener).not.toHaveBeenCalled(); + }); + + it("publishes revert even when already clean and supports idempotent unsubscribe", () => { + const value = store(); + const initial = value.getSnapshot(); + const listener = vi.fn(); + const detach = value.subscribe(listener); + value.revert(); + const restored = value.getSnapshot(); + expect(restored).not.toBe(initial); + expect(restored[0]).toBe(initial[0]); + value.revert(); + expect(value.getSnapshot()).not.toBe(restored); + expect(value.getSnapshot()[0]).toBe(initial[0]); + expect(value.isDirty()).toBe(false); + expect(listener).toHaveBeenCalledTimes(2); + detach(); + detach(); + value.updateField("A", "quantity", 2); + expect(listener).toHaveBeenCalledTimes(2); + }); +}); diff --git a/packages/core/src/components/line-items/document/store.ts b/packages/core/src/components/line-items/document/store.ts new file mode 100644 index 000000000..ec1e32974 --- /dev/null +++ b/packages/core/src/components/line-items/document/store.ts @@ -0,0 +1,75 @@ +import { createLineItemsDocument } from "./model"; +import type { DocumentOptions } from "./types"; + +/** + * Makes one document model observable without duplicating its row state or domain rules. + * The model stays private so all writes pass through the notifying command boundary. + * + * React adapters retain one store per mounted document with a lazy useState initializer, + * then pass the stable subscribe/getSnapshot functions to useSyncExternalStore. The model's + * cached row view is the snapshot: adoption changes its reference before listeners run + * synchronously. Invalid writes and no-ops do not notify; revert always adopts and notifies. + * Returned methods do not depend on this and may be retained across renders. + * + * @example + * const [store] = useState(() => createLineItemsDocumentStore({ columns, lines })); + * const rows = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot); + * + * @internal + */ +export function createLineItemsDocumentStore>( + options: DocumentOptions, +) { + const document = createLineItemsDocument(options); + const listeners = new Set<() => void>(); + + function mutate(operation: () => Result): Result { + const before = document.getRows(); + const result = operation(); + if (document.getRows() !== before) { + // oxlint-disable-next-line unicorn/no-useless-spread -- Subscriptions can change during notification. + for (const listener of [...listeners]) listener(); + } + return result; + } + + return { + idKey: document.idKey, + /** Cached immutable row view, suitable for both getSnapshot and getServerSnapshot. */ + getSnapshot: document.getRows, + getLineKey: document.getLineKey, + assertColumns: document.assertColumns, + isDirty: document.isDirty, + /** + * Registers a payload-free listener without invoking it immediately. Notifications run + * after model adoption; listeners reread getSnapshot/isDirty, not veto the write. + * Returns idempotent cleanup that removes the listener from future notifications. + */ + subscribe(listener: () => void) { + listeners.add(listener); + return () => { + listeners.delete(listener); + }; + }, + /** Delegates the typed field update to the model, then notifies if a row view was adopted. */ + updateField(lineKey: string, property: K, value: T[K]) { + mutate(() => document.updateField(lineKey, property, value)); + }, + /** Appends a model-owned creation and returns its key after notifying subscribers. */ + addLine(input: T): string { + return mutate(() => document.addLine(input)); + }, + /** Removes a current line through the model and publishes the resulting snapshot. */ + removeLine(lineKey: string) { + mutate(() => document.removeLine(lineKey)); + }, + /** Publishes a valid model move; movement permission remains the caller's responsibility. */ + reorderLine(lineKey: string, afterLineKey: string | null) { + mutate(() => document.reorderLine(lineKey, afterLineKey)); + }, + /** Restores the model baseline and notifies even if the document was already clean. */ + revert() { + mutate(() => document.revert()); + }, + }; +} diff --git a/packages/core/src/components/line-items/document/types.ts b/packages/core/src/components/line-items/document/types.ts new file mode 100644 index 000000000..d831667a7 --- /dev/null +++ b/packages/core/src/components/line-items/document/types.ts @@ -0,0 +1,174 @@ +import type { ComponentProps, ReactNode } from "react"; +import type { CellEditorOutput } from "@/components/internals/table-core/editing/props"; +import type { lineItemsEditors } from "../editor-factory"; +import type { + BadgeCellOptions, + ColumnCellType, + ColumnDisplay, + ColumnDisplayValues, + TypedColumnDisplay, +} from "@/components/internals/table-core/column-types"; +import type { createLineItemsIdentity } from "./identity"; + +type EditorBase, TValue> = { + /** Checks the resolved value before adoption, including Clear results; throw/rejection retains the draft. Not persistence. */ + onValueCommitted?: (row: Readonly, value: TValue) => void | Promise; + /** UI policy only; direct row commands remain available. */ + canEdit?: (row: TRow) => boolean; + /** Replaces error content only; checks always finish before adoption and failures retain the draft. */ + error?: { render: (ctx: { row: TRow; error: unknown }) => ReactNode }; +}; + +/** A resolver cannot introduce asynchronous work into Clear value selection. */ +type SynchronousValue = + | string + | number + | boolean + | bigint + | symbol + | null + | undefined + | (object & { then?: never }); +/** Null is the default only when accepted; otherwise the property needs an explicit Clear policy. */ +type ClearOptions = null extends TValue + ? { clearValue?: false | (() => TValue & SynchronousValue) } + : { clearValue: false | (() => TValue & SynchronousValue) }; + +type EditorCatalog = typeof lineItemsEditors; +type EditorAdapter = ReturnType; +type EditorOutput = CellEditorOutput["editor"]>; +type EditorSettings = Parameters["prepare"]>[0]; +type ChoiceOptions = EditorSettings<"combobox">["editorOptions"]; +type ChoiceOption = ChoiceOptions["options"][number]; +type ChoiceValue = Exclude, null>; +type PropertyChoiceValue = ChoiceValue extends TValue + ? ChoiceValue + : Extract; +type PropertyChoiceOption = { + [K in keyof ChoiceOption]: K extends "value" ? PropertyChoiceValue : ChoiceOption[K]; +}; +type PropertyChoiceOptions = { + [K in keyof ChoiceOptions]: K extends "options" + ? readonly PropertyChoiceOption[] + : ChoiceOptions[K]; +}; +type PropertyEditorOutput = K extends "combobox" + ? PropertyChoiceValue | Extract, null> + : EditorOutput; +type PropertyEditorSettings = K extends "combobox" + ? { editorOptions: PropertyChoiceOptions } + : EditorSettings; + +/** Derive editor contracts from the adapters; fixed choices additionally follow the property. */ +export type LineItemsEditor, TValue> = { + [K in keyof EditorCatalog]: [Exclude, null>] extends [never] + ? never + : [Exclude, null>] extends [TValue] + ? EditorBase & + ClearOptions & { + editorType: K; + } & PropertyEditorSettings + : never; +}[keyof EditorCatalog]; + +type DisplayProps> = { + label?: string; + /** Overrides the built-in renderer, including when it returns null. */ + render?: (row: TRow) => ReactNode; + align?: "left" | "center" | "right"; + /** Preferred column width in pixels; omitted widths are automatic and content may require more space. */ + width?: number; + /** Header styling; return undefined to retain defaults. Column width takes precedence over style.width. */ + headerProps?: () => Pick, "className" | "style" | "title"> | undefined; + /** Row-specific styling for readonly and editable cells; content and editing behavior remain owned by the table. */ + cellProps?: ( + row: TRow, + ) => Pick, "className" | "style" | "title"> | undefined; +}; + +/** Combobox labels come from its choices, never a competing badge label map. */ +type PropertyDisplay< + TRow extends Record, + TValue, + TDisplay = ColumnDisplay, +> = TDisplay extends { type: "badge" } + ? TDisplay & + ( + | { + typeOptions?: Omit & { badgeLabelMap?: never }; + edit: Extract, { editorType: "combobox" }>; + } + | { edit?: Exclude, { editorType: "combobox" }> } + ) + : TDisplay & { edit?: LineItemsEditor }; + +type PropertyColumn> = { + [K in keyof TRow & string]: DisplayProps & + PropertyDisplay & { + accessorKey: K; + accessor?: never; + id?: string; + }; +}[keyof TRow & string]; + +type ComputedColumn> = DisplayProps & { + id: string; + accessorKey?: never; + edit?: never; +} & ( + | { type?: undefined; typeOptions?: never; accessor: (row: TRow) => unknown } + | { + [K in ColumnCellType]: TypedColumnDisplay & { + accessor: (row: TRow) => ColumnDisplayValues[K]; + }; + }[ColumnCellType] + ); + +type SourceLessColumn> = DisplayProps & + ColumnDisplay & { + id: string; + accessorKey?: never; + accessor?: never; + edit?: never; + }; + +/** A property, computed value, or explicitly value-less display column. */ +export type LineItemsColumn> = + | PropertyColumn + | ComputedColumn + | SourceLessColumn; + +type UnsafeIdentityKey = T extends unknown + ? string extends keyof T + ? string // Index signatures cannot prove that a named identity property is optional. + : { + [K in keyof T]-?: {} extends Pick ? never : K; + }[keyof T] & + string + : never; + +type OptionalStringKey = Exclude>; + +/** Persisted identity property, defaulting to id; it must be optional in every row variant. */ +export type LineItemsIdentityOptions> = + Extract extends never + ? { idKey?: OptionalStringKey } + : { idKey: OptionalStringKey }; + +export type DocumentOptions> = { + /** Initial definitions whose accessorKey fields establish document property ownership. */ + columns: readonly LineItemsColumn[]; + /** Initial rows, read once; only rows with persisted IDs establish the baseline. */ + lines?: readonly T[]; +} & LineItemsIdentityOptions; + +export type LineItemsIdentity> = ReturnType< + typeof createLineItemsIdentity +>; + +/** A validated row view, ordered client keys, and client-key index constructed together. */ +export type LineItemsSnapshot = { + readonly lines: readonly T[]; + readonly clientKeys: readonly string[]; + readonly byClientKey: ReadonlyMap; +}; diff --git a/packages/core/src/components/line-items/editing.test.ts b/packages/core/src/components/line-items/editing.test.ts new file mode 100644 index 000000000..7f95c2ed4 --- /dev/null +++ b/packages/core/src/components/line-items/editing.test.ts @@ -0,0 +1,358 @@ +import { describe, expect, it, vi } from "vitest"; +import { createLineItemsDocumentStore } from "./document/store"; +import { createLineItemsEditing } from "./editing"; +import type { LineItemsColumn } from "./types"; + +type Row = { id?: string; name: string | null; quantity: number | null }; +function deferred() { + let resolve!: () => void; + let reject!: (error: unknown) => void; + const promise = new Promise((success, failure) => { + resolve = success; + reject = failure; + }); + return { promise, resolve, reject }; +} +function setup( + check?: (row: Readonly, value: string | null) => void | Promise, + error?: NonNullable["edit"]>["error"], +) { + const columns: LineItemsColumn[] = [ + { + accessorKey: "name", + label: "Name", + edit: { editorType: "text", onValueCommitted: check, error }, + }, + { accessorKey: "quantity" }, + ]; + const store = createLineItemsDocumentStore({ + columns, + lines: [{ id: "A", name: "First", quantity: 1 }], + }); + const editing = createLineItemsEditing(store, columns); + const session = editing.getSession(store.getSnapshot()[0], columns[0]); + const confirm = (value: string) => { + session.change(value); + session.confirm(() => editing.commitField("A", "name", value)); + }; + return { columns, store, editing, session, confirm }; +} + +describe("document-owned cell editing", () => { + it("indexes each snapshot once when reconciling retained cells and purging removed rows", () => { + const columns: LineItemsColumn[] = Array.from({ length: 5 }, (_, index) => ({ + id: `name-${index}`, + accessorKey: "name", + edit: { editorType: "text" }, + })); + const store = createLineItemsDocumentStore({ + columns, + lines: Array.from({ length: 1_000 }, (_, index) => ({ + id: String(index), + name: "Item", + quantity: 1, + })), + }); + const getLineKey = vi.spyOn(store, "getLineKey"); + const editing = createLineItemsEditing(store, columns); + for (const row of store.getSnapshot()) + for (const column of columns) editing.getSession(row, column); + getLineKey.mockClear(); + + editing.reconcileColumns(columns); + expect(getLineKey).toHaveBeenCalledTimes(1_000); + getLineKey.mockClear(); + editing.reconcileColumns(columns); + expect(getLineKey).not.toHaveBeenCalled(); + + editing.removeLine("999"); + expect(getLineKey).toHaveBeenCalledTimes(999); + getLineKey.mockClear(); + editing.reconcileColumns(columns); + expect(getLineKey).not.toHaveBeenCalled(); + }); + + it.each(["update", "add", "reorder", "remove", "revert"] as const)( + "reads current rows after a document %s changes the snapshot", + (action) => { + const { columns, store, editing } = setup(); + const canEdit = vi.fn((_row: Row) => true); + const editable: LineItemsColumn[] = [ + { accessorKey: "name", edit: { editorType: "text", canEdit } }, + columns[1], + ]; + const addedKey = store.addLine({ name: "Added", quantity: 2 }); + editing.getSession(store.getSnapshot()[1], editable[0]); + editing.reconcileColumns(editable); + canEdit.mockClear(); + + if (action === "update") store.updateField("A", "quantity", 3); + if (action === "add") { + store.addLine({ name: "Another", quantity: 4 }); + editing.getSession(store.getSnapshot()[2], editable[0]); + } + if (action === "reorder") store.reorderLine(addedKey, null); + if (action === "remove") editing.removeLine(addedKey); + if (action === "revert") editing.revert(); + editing.reconcileColumns(editable); + + expect(canEdit).toHaveBeenCalledTimes(store.getSnapshot().length); + for (const row of store.getSnapshot()) { + const checked = canEdit.mock.calls.find( + ([candidate]) => store.getLineKey(candidate) === store.getLineKey(row), + ); + expect(checked?.[0]).toBe(row); + } + }, + ); + + it("adopts a successful check into the current row without overwriting unrelated changes", async () => { + const request = deferred(); + const check = vi.fn(() => request.promise); + const { editing, store, session, confirm } = setup(check); + const listener = vi.fn(); + store.subscribe(listener); + confirm("Confirmed"); + expect(store.getSnapshot()[0].name).toBe("First"); + editing.updateField("A", "quantity", 2); + request.resolve(); + await request.promise; + await Promise.resolve(); + expect(session.getState()).toEqual({ status: "idle" }); + expect(store.getSnapshot()[0]).toMatchObject({ name: "Confirmed", quantity: 2 }); + expect(check).toHaveBeenCalledWith( + expect.objectContaining({ name: "First", quantity: 1 }), + "Confirmed", + ); + expect(listener).toHaveBeenCalledTimes(2); + }); + + it.each([ + "update", + "noop-update", + "remove", + "revert", + "dispose", + "permission", + "editor-removed", + ] as const)("prevents late adoption after %s invalidates the logical edit", async (action) => { + const request = deferred(); + const check = () => request.promise; + const { columns, editing, store, session, confirm } = setup(check); + confirm("Stale"); + if (action === "update") editing.updateField("A", "name", "Command"); + if (action === "noop-update") editing.updateField("A", "name", "First"); + if (action === "remove") editing.removeLine("A"); + if (action === "revert") editing.revert(); + if (action === "dispose") editing.deactivate(); + if (action === "permission" || action === "editor-removed") { + editing.reconcileColumns([ + { + accessorKey: "name", + edit: + action === "editor-removed" + ? undefined + : { editorType: "text", onValueCommitted: check, canEdit: () => false }, + }, + columns[1], + ]); + } + const snapshot = store.getSnapshot(); + request.resolve(); + await request.promise; + await Promise.resolve(); + expect(store.getSnapshot()).toBe(snapshot); + if (action !== "dispose" && action !== "remove") + expect(session.getState()).toEqual({ status: "idle" }); + expect(store.getSnapshot().map((row) => row.name)).toEqual( + action === "remove" ? [] : [action === "update" ? "Command" : "First"], + ); + }); + + it("retains an in-flight check when callbacks are recreated and uses the latest callback next time", async () => { + const request = deferred(); + const before = vi.fn(() => request.promise); + const after = vi.fn(); + const { columns, editing, store, session, confirm } = setup(before); + confirm("Pending"); + const pending = session.getState(); + editing.reconcileColumns([ + { accessorKey: "name", edit: { editorType: "text", onValueCommitted: after } }, + columns[1], + ]); + expect(session.getState()).toBe(pending); + request.resolve(); + await request.promise; + await Promise.resolve(); + expect(store.getSnapshot()[0].name).toBe("Pending"); + expect(before).toHaveBeenCalledTimes(1); + expect(after).not.toHaveBeenCalled(); + confirm("Next"); + expect(store.getSnapshot()[0].name).toBe("Next"); + expect(after).toHaveBeenCalledWith(expect.objectContaining({ name: "Pending" }), "Next"); + }); + + it("retains a rejected callback draft without adopting data or publishing a row snapshot", async () => { + const request = deferred(); + const { confirm, store, session } = setup(() => request.promise); + const initial = store.getSnapshot(); + const listener = vi.fn(); + store.subscribe(listener); + confirm("Rejected"); + const error = new Error("Rejected"); + request.reject(error); + await request.promise.catch(() => {}); + await Promise.resolve(); + expect(session.getFailure()).toMatchObject({ error, source: "commit", draft: "Rejected" }); + expect(store.getSnapshot()).toBe(initial); + expect(listener).not.toHaveBeenCalled(); + }); + + it("does not discard a draft for an invalid programmatic write", () => { + const { editing, session } = setup(); + session.begin("Retained"); + const draft = session.getState(); + expect(() => editing.updateField("A", "id", "Changed")).toThrow("save acknowledgment"); + expect(session.getState()).toBe(draft); + }); + + it("validates proposed columns without changing drafts or committed callbacks", () => { + const before = vi.fn(); + const after = vi.fn(); + const { columns, editing, store, session, confirm } = setup(before); + session.begin("Retained"); + const draft = session.getState(); + const snapshot = store.getSnapshot(); + editing.assertColumns([{ accessorKey: "name" }, columns[1]]); + editing.assertColumns([ + { accessorKey: "name", edit: { editorType: "text", onValueCommitted: after } }, + columns[1], + ]); + expect(() => editing.assertColumns([])).toThrow("change document property ownership"); + expect(session.getState()).toBe(draft); + expect(store.getSnapshot()).toBe(snapshot); + confirm("Confirmed"); + expect(before).toHaveBeenCalledWith(snapshot[0], "Confirmed"); + expect(after).not.toHaveBeenCalled(); + }); + + it("rejects invalid reconciliation without changing drafts or committed callbacks", () => { + const check = vi.fn(); + const { editing, store, session, confirm } = setup(check); + session.begin("Retained"); + const draft = session.getState(); + const snapshot = store.getSnapshot(); + expect(() => editing.reconcileColumns([])).toThrow("change document property ownership"); + expect(session.getState()).toBe(draft); + expect(store.getSnapshot()).toBe(snapshot); + confirm("Confirmed"); + expect(check).toHaveBeenCalledWith(snapshot[0], "Confirmed"); + }); + + it("preserves a draft on display-only configuration changes", () => { + const { columns, editing, session } = setup(); + session.begin("Retained"); + const draft = session.getState(); + editing.reconcileColumns([ + { ...columns[0], label: "Renamed", render: (row) => row.name }, + columns[1], + ]); + expect(session.getState()).toBe(draft); + }); + + it("clears sibling drafts for duplicate columns owning the same property", () => { + const { columns, editing, store, confirm } = setup(); + const duplicate = { ...columns[0], id: "duplicate" }; + editing.reconcileColumns([...columns, duplicate]); + const sibling = editing.getSession(store.getSnapshot()[0], duplicate); + sibling.begin("Other draft"); + confirm("Confirmed"); + expect(sibling.getState()).toEqual({ status: "idle" }); + expect(store.getSnapshot()[0].name).toBe("Confirmed"); + }); + + describe.each(["default", "custom"] as const)("%s error presentation", (presentation) => { + const errorOptions = presentation === "custom" ? { render: () => null } : undefined; + + it("retains synchronous rejection without adopting or publishing a snapshot", () => { + const error = new Error("Rejected"); + const check = vi.fn(() => { + throw error; + }); + const { confirm, store, session } = setup(check, errorOptions); + const initial = store.getSnapshot(); + const listener = vi.fn(); + store.subscribe(listener); + + expect(() => confirm("Rejected")).not.toThrow(); + + expect(session.getFailure()).toMatchObject({ error, source: "commit", draft: "Rejected" }); + expect(store.getSnapshot()).toBe(initial); + expect(store.isDirty()).toBe(false); + expect(listener).not.toHaveBeenCalled(); + expect(check).toHaveBeenCalledTimes(1); + }); + + it.each(["resolve", "reject"] as const)( + "waits before adoption when a pending check will %s and does not repeat it", + async (outcome) => { + const request = deferred(); + const check = vi.fn(() => request.promise); + const { confirm, editing, store, session } = setup(check, errorOptions); + const initial = store.getSnapshot(); + const listener = vi.fn(); + store.subscribe(listener); + confirm("Candidate"); + session.confirm(() => editing.commitField("A", "name", "Candidate")); + + expect(session.getState()).toEqual({ status: "confirming", draft: "Candidate" }); + expect(store.getSnapshot()).toBe(initial); + expect(store.isDirty()).toBe(false); + expect(listener).not.toHaveBeenCalled(); + expect(check).toHaveBeenCalledExactlyOnceWith(initial[0], "Candidate"); + + const error = new Error("Rejected"); + if (outcome === "resolve") request.resolve(); + else request.reject(error); + await request.promise.catch(() => {}); + await Promise.resolve(); + + if (outcome === "resolve") { + expect(session.getState()).toEqual({ status: "idle" }); + expect(store.getSnapshot()[0].name).toBe("Candidate"); + expect(store.isDirty()).toBe(true); + expect(listener).toHaveBeenCalledTimes(1); + } else { + expect(session.getFailure()).toMatchObject({ + error, + source: "commit", + draft: "Candidate", + }); + expect(store.getSnapshot()).toBe(initial); + expect(store.isDirty()).toBe(false); + expect(listener).not.toHaveBeenCalled(); + } + expect(check).toHaveBeenCalledTimes(1); + }, + ); + }); + + it("rejects disabled error handling from untyped configuration", () => { + const columns = [ + { accessorKey: "name", edit: { editorType: "text", error: false } }, + ] as unknown as LineItemsColumn[]; + expect(() => createLineItemsDocumentStore({ columns })).toThrow( + "LineItems error handling cannot be disabled", + ); + }); + + it("rejects editors on the server identity property", () => { + const columns: LineItemsColumn<{ id?: string | null }>[] = [ + { accessorKey: "id", edit: { editorType: "text" } }, + ]; + const store = createLineItemsDocumentStore({ columns }); + expect(() => createLineItemsEditing(store, columns)).toThrow( + "Line IDs cannot have cell editors", + ); + }); +}); diff --git a/packages/core/src/components/line-items/editing.ts b/packages/core/src/components/line-items/editing.ts new file mode 100644 index 000000000..e7144c872 --- /dev/null +++ b/packages/core/src/components/line-items/editing.ts @@ -0,0 +1,188 @@ +import { createCellEditSession } from "@/components/internals/table-core/cell-session"; +import type { createLineItemsDocumentStore } from "./document/store"; +import type { LineItemsColumn } from "./types"; + +type Store> = ReturnType>; +type Session = ReturnType>; +type Cell = { property: string; session: Session }; +const columnId = >(column: LineItemsColumn) => + (column.id ?? column.accessorKey)!; + +/** Internal refusal translated by the cell owner before entering error presentation. */ +export class LineItemsClearError extends Error {} + +/** Binds logical cell drafts to a document, without owning another copy of its rows. @internal */ +export function createLineItemsEditing>( + store: Store, + initialColumns: readonly LineItemsColumn[], +) { + let columns = initialColumns; + let active = true; + const cells = new Map>(); + const columnFor = (id: string) => columns.find((column) => columnId(column) === id); + let indexedSnapshot: readonly T[] | undefined; + let rowsByKey = new Map(); + function getCurrentRow(key: string) { + const snapshot = store.getSnapshot(); + if (snapshot !== indexedSnapshot) { + rowsByKey = new Map(snapshot.map((row) => [store.getLineKey(row), row])); + indexedSnapshot = snapshot; + } + return rowsByKey.get(key); + } + + function cancelProperty(key: string, property: string, source?: Session) { + for (const cell of cells.get(key)?.values() ?? []) + if (cell.property === property && cell.session !== source) cell.session.cancel(); + } + function purgeRemoved() { + for (const [key, rowCells] of cells) { + if (getCurrentRow(key)) continue; + for (const cell of rowCells.values()) cell.session.deactivate(); + cells.delete(key); + } + } + function assertColumns(next: readonly LineItemsColumn[]) { + store.assertColumns(next); + if (next.some((column) => column.edit && column.accessorKey === store.idKey)) + throw new Error("Line IDs cannot have cell editors"); + } + assertColumns(initialColumns); + + return { + /** Validates proposed columns without changing committed configuration or drafts. */ + assertColumns, + getLineKey: store.getLineKey, + /** + * A cell deliberately reuses its session across rerenders and view remounts. + * On-the-fly editor replacement (type or options) during an active draft is not + * a targeted LineItems use case, so we do not compare editor contracts or migrate + * drafts between editor-specific shapes. Keep that configuration stable mid-draft; + * ordinary callback recreation and canEdit changes are supported independently. + * + * shortcut: Live editor replacement is unsupported, add session versioning if a concrete use case requires it. + */ + getSession(row: T, column: LineItemsColumn): Session { + const key = store.getLineKey(row); + let rowCells = cells.get(key); + if (!rowCells) { + rowCells = new Map(); + cells.set(key, rowCells); + } + let cell = rowCells.get(columnId(column)); + if (!cell) { + const session = createCellEditSession(); + if (!active) session.deactivate(); + cell = { property: column.accessorKey!, session }; + rowCells.set(columnId(column), cell); + } + return cell.session; + }, + /** Only a still-current successful cell check can write to the current row. */ + commitField(key: string, id: string, value: unknown) { + const row = getCurrentRow(key); + const column = columnFor(id); + const source = cells.get(key)?.get(id)?.session; + if (!active || !row || !column?.edit || column.accessorKey === undefined || !source) + throw new Error("The edited cell no longer exists"); + if (!(column.edit.canEdit?.(row) ?? true)) throw new Error("The cell is not editable"); + const revision = source.getRevision(); + if (value === null) { + if (column.edit.clearValue === false) + throw new LineItemsClearError("The cell cannot be cleared"); + value = column.edit.clearValue ? column.edit.clearValue() : null; + if (typeof (value as PromiseLike | null | undefined)?.then === "function") { + void Promise.resolve(value).catch(() => {}); + throw new Error("LineItems clearValue must return a synchronous value"); + } + if (Object.is(value, row[column.accessorKey])) return; + } + // The correlated property contract is checked before this heterogeneous cell boundary. + const check = column.edit.onValueCommitted as + | ((row: Readonly, value: unknown) => void | Promise) + | undefined; + const adopt = () => { + const current = getCurrentRow(key); + const currentColumn = columnFor(id); + if ( + !active || + !current || + source.getRevision() !== revision || + !currentColumn?.edit || + currentColumn.accessorKey !== column.accessorKey + ) + return; + if (!(currentColumn.edit.canEdit?.(current) ?? true)) + throw new Error("The cell is not editable"); + store.updateField(key, column.accessorKey!, value as T[keyof T & string]); + cancelProperty(key, column.accessorKey!, source); + }; + const result = check?.(row, value); + if (result && typeof result.then === "function") return Promise.resolve(result).then(adopt); + return adopt(); + }, + updateField(key: string, property: K, value: T[K]) { + store.updateField(key, property, value); + // Even a no-op direct write supersedes the editor's intent. + cancelProperty(key, property); + }, + removeLine(key: string) { + store.removeLine(key); + purgeRemoved(); + }, + revert() { + store.revert(); + for (const rowCells of cells.values()) + for (const cell of rowCells.values()) cell.session.cancel(); + purgeRemoved(); + }, + /** Adopts committed columns and retires removed cells or denied drafts. */ + reconcileColumns(next: readonly LineItemsColumn[]) { + assertColumns(next); + columns = next; + for (const [key, rowCells] of cells) { + for (const [id, cell] of rowCells) { + const after = columnFor(id); + if (!after?.edit) { + cell.session.cancel(); + cell.session.deactivate(); + rowCells.delete(id); + continue; + } + if (after.accessorKey !== cell.property) { + cell.property = after.accessorKey!; + cell.session.cancel(); + } + const row = getCurrentRow(key); + if (row && !(after.edit.canEdit?.(row) ?? true)) cell.session.cancel(); + if (active) cell.session.activate(true); + } + if (rowCells.size === 0) cells.delete(key); + } + }, + deactivate() { + active = false; + for (const rowCells of cells.values()) + for (const cell of rowCells.values()) cell.session.deactivate(); + }, + activate() { + active = true; + for (const rowCells of cells.values()) + for (const cell of rowCells.values()) cell.session.activate(true); + }, + }; +} + +export type LineItemsEditing> = ReturnType< + typeof createLineItemsEditing +>; +/** Internal document handle; enumerable symbol properties survive shallow copies. */ +export const LINE_ITEMS_EDITING = Symbol("LineItems.editing"); + +export function getLineItemsEditing>( + value: object, +): LineItemsEditing { + const editing = (value as { [LINE_ITEMS_EDITING]?: LineItemsEditing })[LINE_ITEMS_EDITING]; + if (!editing) throw new Error("Editable LineItems requires the value returned by useLineItems"); + return editing; +} diff --git a/packages/core/src/components/line-items/editor-factory.test.ts b/packages/core/src/components/line-items/editor-factory.test.ts new file mode 100644 index 000000000..1449e0a07 --- /dev/null +++ b/packages/core/src/components/line-items/editor-factory.test.ts @@ -0,0 +1,98 @@ +// @vitest-environment node +import { describe, expect, it, vi } from "vitest"; +import { createLineItemsDocument } from "./document/model"; +import { assertLineItemsEditor, lineItemsEditors } from "./editor-factory"; +import type { LineItemsColumn, LineItemsEditor } from "./types"; + +vi.mock("react", () => { + throw new Error("Document validation must not load React or editor UI"); +}); +vi.mock("./line-items-cell", () => { + throw new Error("Document validation must not load the UI adapters"); +}); + +type Row = { id?: string; value: string | number | null }; +const settings = { + text: { editorType: "text" }, + number: { editorType: "number" }, + date: { editorType: "date", editorOptions: { withTime: true } }, + combobox: { + editorType: "combobox", + editorOptions: { options: Object.freeze([{ value: "open", label: "Open" }]) }, + }, +} satisfies { + [K in keyof typeof lineItemsEditors]: Extract, { editorType: K }>; +}; + +const columns = (edit: unknown) => + [{ accessorKey: "value", edit }] as unknown as LineItemsColumn[]; + +const document = () => + createLineItemsDocument({ + columns: columns(settings.text), + lines: [{ id: "A", value: "Initial" }], + }); + +describe("headless editor definitions", () => { + it.each(Object.keys(settings) as (keyof typeof settings)[])( + "validates %s at document creation and reconfiguration without UI bindings", + (kind) => { + const config = columns(settings[kind]); + const doc = createLineItemsDocument({ columns: config }); + expect(() => doc.assertColumns(config)).not.toThrow(); + expect(Object.keys(lineItemsEditors)).toContain(kind); + }, + ); + + it.each(["custom", "constructor", "__proto__", { toString: () => "text" }, Object("date")])( + "rejects an unsupported kind %s without changing the document", + (editorType) => { + const doc = document(); + const before = doc.getRows(); + const config = columns({ editorType }); + expect(() => createLineItemsDocument({ columns: config })).toThrow( + "Unsupported LineItems editor type", + ); + expect(() => doc.assertColumns(config)).toThrow("Unsupported LineItems editor type"); + expect(doc.getRows()).toBe(before); + expect(doc.isDirty()).toBe(false); + }, + ); + + it.each([ + undefined, + null, + {}, + () => [], + [], + { options: undefined }, + { options: null }, + { options: {} }, + { options: () => [] }, + { options: [null] }, + { options: [{ value: 1, label: "One" }] }, + { options: [{ value: "one", label: 1 }] }, + ])("rejects malformed editorOptions %s without UI preparation", (editorOptions) => { + const edit = { editorType: "combobox", editorOptions }; + expect(() => assertLineItemsEditor(edit)).toThrow( + "Combobox editors require fixed string options", + ); + expect(() => createLineItemsDocument({ columns: columns(edit) })).toThrow( + "Combobox editors require fixed string options", + ); + const doc = document(); + const before = doc.getRows(); + expect(() => doc.assertColumns(columns(edit))).toThrow( + "Combobox editors require fixed string options", + ); + expect(doc.getRows()).toBe(before); + expect(doc.isDirty()).toBe(false); + }); + + it("does not accept legacy flattened combobox options", () => { + const edit = { editorType: "combobox", options: [{ value: "open", label: "Open" }] }; + expect(() => assertLineItemsEditor(edit)).toThrow( + "Combobox editors require fixed string options", + ); + }); +}); diff --git a/packages/core/src/components/line-items/editor-factory.ts b/packages/core/src/components/line-items/editor-factory.ts new file mode 100644 index 000000000..b11ac1e9c --- /dev/null +++ b/packages/core/src/components/line-items/editor-factory.ts @@ -0,0 +1,66 @@ +import type { createLineItemsCellPreparers } from "./line-items-cell"; + +type UIAdapters = ReturnType["bindings"]; + +/** Headless registration: validate settings without UI, then select an adapter for rendering. */ +interface LineItemsEditorDefinition { + validate: (settings: unknown) => void; + bind: (ui: UIAdapters) => TAdapter; +} + +/** The single registration point for editor kinds, settings validation, and UI adapter selection. */ +export const lineItemsEditors = { + text: { + validate: () => {}, + bind: (ui) => ui.text, + }, + number: { + validate: () => {}, + bind: (ui) => ui.number, + }, + date: { + validate: () => {}, + bind: (ui) => ui.date, + }, + combobox: { + validate: (settings) => { + if ( + typeof settings !== "object" || + settings === null || + !("options" in settings) || + !Array.isArray(settings.options) || + settings.options.some( + (option: unknown) => + typeof option !== "object" || + option === null || + !("value" in option) || + typeof option.value !== "string" || + !("label" in option) || + typeof option.label !== "string", + ) + ) + throw new Error("Combobox editors require fixed string options"); + }, + bind: (ui) => ui.choice, + }, +} satisfies Record>; + +/** Validate settings through the same definitions used for rendering, without loading UI modules. */ +export function assertLineItemsEditor(edit: { + editorType: unknown; + editorOptions?: unknown; + clearValue?: unknown; + error?: unknown; +}) { + if (edit.error === false) throw new Error("LineItems error handling cannot be disabled"); + if ( + edit.clearValue !== undefined && + edit.clearValue !== false && + typeof edit.clearValue !== "function" + ) + throw new Error("LineItems clearValue must be false or a synchronous function"); + const kind = edit.editorType; + if (typeof kind !== "string" || !Object.hasOwn(lineItemsEditors, kind)) + throw new Error("Unsupported LineItems editor type"); + lineItemsEditors[kind as keyof typeof lineItemsEditors].validate(edit.editorOptions); +} diff --git a/packages/core/src/components/line-items/enum-editing.test.tsx b/packages/core/src/components/line-items/enum-editing.test.tsx new file mode 100644 index 000000000..0827557f8 --- /dev/null +++ b/packages/core/src/components/line-items/enum-editing.test.tsx @@ -0,0 +1,63 @@ +import { afterEach, expect, it, vi } from "vitest"; +import { cleanup, render, screen } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { MemoryRouter } from "react-router"; +import { AppShellConfigContext, buildConfigurations } from "@/contexts/appshell-context"; +import { LineItems } from "./line-items"; +import { useLineItems } from "./use-line-items"; +import type { LineItemsColumn, UseLineItemsReturn } from "./types"; + +afterEach(cleanup); + +it("adopts selected nullable enum values rather than their labels", async () => { + type Row = { id?: string; status: "draft" | "confirmed" | null }; + const checked = vi.fn((_row: Readonly, _value: Row["status"]) => {}); + const columns: LineItemsColumn[] = [ + { + accessorKey: "status", + label: "Status", + edit: { + editorType: "combobox", + editorOptions: { + options: [ + { value: "draft", label: "Draft" }, + { value: "confirmed", label: "Confirmed" }, + ], + }, + onValueCommitted: checked, + }, + }, + ]; + let value!: UseLineItemsReturn; + function Owner() { + value = useLineItems({ + columns, + defaultLines: [{ id: "A", status: "draft" }], + orderer: false, + }); + return ( + + + + ); + } + render( + + + + + , + ); + const user = userEvent.setup(); + await user.click(screen.getByRole("combobox", { name: "Status, Row 1" })); + await user.click(screen.getByRole("option", { name: "Confirmed" })); + expect(checked).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ status: "draft" }), + "confirmed", + ); + expect(value.lines[0].status).toBe("confirmed"); + expect(value.isDirty).toBe(true); + expect(screen.getByRole("cell").textContent).toBe("Confirmed"); +}); diff --git a/packages/core/src/components/line-items/i18n.ts b/packages/core/src/components/line-items/i18n.ts new file mode 100644 index 000000000..bfade85e7 --- /dev/null +++ b/packages/core/src/components/line-items/i18n.ts @@ -0,0 +1,52 @@ +import { defineI18nLabels } from "@/hooks/i18n"; + +const labels = defineI18nLabels({ + en: { + title: "Line items", + empty: "No lines yet.", + order: "Order", + reorder: ({ line }: { line: number }) => `Reorder line ${line}`, + dragToReorder: "Drag to reorder, or use the Up and Down arrow keys", + row: ({ index }: { index: number }) => `Row ${index}`, + notANumber: "Not a number", + revertHint: "Esc to revert", + callbackError: "The value could not be confirmed.", + errorHint: "Alt+↓ to show details", + showError: ({ label }: { label: string }) => `Show error for ${label}`, + errorDialog: ({ label }: { label: string }) => `Error for ${label}`, + closeError: "Close error details", + none: "None", + noMatches: "No matches", + chooseTime: "Time", + clear: "Clear", + clearNotAllowed: "This field cannot be cleared.", + done: "Done", + unconfirmed: "Unconfirmed input. It has not been applied to the line.", + confirming: "Confirming input.", + }, + ja: { + title: "明細", + empty: "明細がありません。", + order: "並び順", + reorder: ({ line }) => `${line}行目の並び替え`, + dragToReorder: "ドラッグ、または上下の矢印キーで並び替え", + row: ({ index }) => `${index}行目`, + notANumber: "数値ではありません", + revertHint: "Escで元に戻す", + callbackError: "値を確定できませんでした。", + errorHint: "Alt+↓で詳細を表示", + showError: ({ label }) => `${label}のエラーを表示`, + errorDialog: ({ label }) => `${label}のエラー`, + closeError: "エラー詳細を閉じる", + none: "なし", + noMatches: "一致する項目がありません", + chooseTime: "時刻", + clear: "クリア", + clearNotAllowed: "この項目は空にできません。", + done: "完了", + unconfirmed: "未確定の入力です。まだ明細に反映されていません。", + confirming: "入力を確認中です。", + }, +}); + +export const useLineItemsT = labels.useT; diff --git a/packages/core/src/components/line-items/icon-spacing.test.tsx b/packages/core/src/components/line-items/icon-spacing.test.tsx new file mode 100644 index 000000000..4eebe3554 --- /dev/null +++ b/packages/core/src/components/line-items/icon-spacing.test.tsx @@ -0,0 +1,97 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { cleanup, render, screen, within } from "@testing-library/react"; +import { MemoryRouter } from "react-router"; +import { AppShellConfigContext, buildConfigurations } from "@/contexts/appshell-context"; +import { ICON_SPACE_CLASS_NAME } from "@/components/internals/table-core/editing/shared"; +import { LineItems } from "./line-items"; +import { useLineItems } from "./use-line-items"; +import type { LineItemsColumn } from "./types"; + +afterEach(cleanup); +type Row = { id?: string; value: string | null; amount: number | null; allowed: boolean }; +const canEdit = (row: Row) => row.allowed; +const configurations = buildConfigurations({ modules: [], locale: "en", timeZone: "UTC" }); + +function setup(kind: "combobox" | "date" | "text" | "number", align: "left" | "center" | "right") { + const presentation = { + label: "Value", + align, + cellProps: () => ({ style: { backgroundColor: "lavender" }, title: "Cell presentation" }), + }; + let column: LineItemsColumn; + if (kind === "number") { + column = { + ...presentation, + accessorKey: "amount", + type: "number", + edit: { editorType: "number", canEdit }, + }; + } else if (kind === "combobox") { + column = { + ...presentation, + accessorKey: "value", + edit: { + editorType: "combobox", + canEdit, + editorOptions: { options: [{ value: "2026-12-01", label: "Closing day" }] }, + }, + }; + } else { + column = { + ...presentation, + accessorKey: "value", + type: kind, + edit: { editorType: kind, canEdit }, + }; + } + function Owner() { + const value = useLineItems({ + columns: [column], + defaultLines: [ + { id: "A", value: "2026-12-01", amount: 12, allowed: true }, + { id: "B", value: "2026-12-01", amount: 12, allowed: false }, + ], + orderer: false, + }); + return ( + + + + + + + + ); + } + render(); +} + +describe("LineItems mixed-permission icon spacing", () => { + it.each(["left", "center", "right"] as const)( + "reserves the same icon space in editable and readonly rows with %s alignment", + (align) => { + for (const kind of ["combobox", "date", "text", "number"] as const) { + setup(kind, align); + const [editable, readonly] = screen.getAllByRole("cell"); + const hasIcon = kind === "combobox" || kind === "date"; + for (const cell of [editable, readonly]) { + const preview = Array.from(cell.children).find((child) => + child.classList.contains("astw:block"), + ); + expect(preview?.classList.contains(ICON_SPACE_CLASS_NAME) ?? false).toBe(hasIcon); + expect(cell.classList.contains(`astw:text-${align}`)).toBe(true); + expect(cell.style.backgroundColor).toBe("lavender"); + expect(cell.title).toBe("Cell presentation"); + } + expect(editable.hasAttribute("data-editable")).toBe(true); + expect(readonly.hasAttribute("data-editable")).toBe(false); + expect(within(readonly).queryByRole("combobox")).toBeNull(); + expect(within(readonly).queryByRole("textbox")).toBeNull(); + expect(within(readonly).queryByRole("button")).toBeNull(); + expect(readonly.querySelector("svg")).toBeNull(); + expect(readonly.textContent).toBe(editable.firstElementChild?.textContent); + cleanup(); + } + }, + ); +}); diff --git a/packages/core/src/components/line-items/index.ts b/packages/core/src/components/line-items/index.ts new file mode 100644 index 000000000..ff69cc96b --- /dev/null +++ b/packages/core/src/components/line-items/index.ts @@ -0,0 +1,3 @@ +export { LineItems, type LineItemsRootProps, type LineItemsTableProps } from "./line-items"; +export { useLineItems } from "./use-line-items"; +export type { UseLineItemsOptions, UseLineItemsReturn } from "./types"; diff --git a/packages/core/src/components/line-items/line-items-cell.tsx b/packages/core/src/components/line-items/line-items-cell.tsx new file mode 100644 index 000000000..eb8a012d3 --- /dev/null +++ b/packages/core/src/components/line-items/line-items-cell.tsx @@ -0,0 +1,330 @@ +import { useMemo, type ComponentProps, type ReactNode } from "react"; +import { BadgeList } from "@/components/badge-list"; +import { Table } from "@/components/table"; +import { cn } from "@/lib/utils"; +import { ICON_SPACE_CLASS_NAME } from "@/components/internals/table-core/editing/shared"; +import { + createValueRenderer, + getDisplayCellAdapter, + type ValueRenderer, +} from "@/components/internals/table-core"; +import type { + CellEditor, + CellEditorOptions, +} from "@/components/internals/table-core/editing/props"; +import { + EditableCell, + type EditableCellOwnerProps, +} from "@/components/internals/table-core/editing/cell"; +import { choiceEditor } from "@/components/internals/table-core/editing/choice"; +import { toTextValue } from "@/components/internals/table-core/input-values"; +import { dateEditor } from "@/components/internals/table-core/editing/date"; +import { numberEditor, textEditor } from "@/components/internals/table-core/editing/typing"; +import { LineItemsClearError, type LineItemsEditing } from "./editing"; +import { CellEditError } from "@/components/internals/table-core/cell-edit-error"; +import { lineItemsEditors } from "./editor-factory"; +import { useLineItemsT } from "./i18n"; +import type { LineItemsColumn } from "./types"; + +/** + * Resolved cell alignment and rendering operations prepared for one column and reused across rows. + * Consumers select a row's display mode without inspecting editor kinds, settings, or choice metadata. + * + * @typeParam T - Row type preserved for accessors and row-dependent display options. + */ +interface LineItemsCellRenderers> { + /** Explicit column alignment, or the display type's default; shared by the header, preview, and input. */ + align: EditableCellOwnerProps["align"]; + /** Reserve the concrete editor's icon space even in rows that cannot edit. */ + reserveIconSpace?: boolean; + /** Invoke directly with owner-bound values, callbacks, and session; do not mount this callback as a component. */ + renderCell: (props: EditableCellOwnerProps) => ReactNode; + /** Render row data or custom content; editable selects the input-compatible preview, not permission or draft state. */ + renderDisplay: (row: T, editable: boolean) => ReactNode; +} + +/** UI-owned preparation, retaining the editor actually rendered as the source of its output contract. */ +export interface LineItemsEditorAdapter { + /** Concrete input used for both rendering and output-type derivation. */ + editor: CellEditor; + /** Resolve settings, display policy, and environment dependencies before rendering rows. */ + prepare>( + settings: TSettings, + column: LineItemsColumn, + ): LineItemsCellRenderers; +} + +/** + * Bind a row's value source to already-prepared readonly and editable value renderers. + * This common step knows no display kinds, editor settings, labels, or timezone dependencies. + * + * @param source - Property or computed accessor supplying the raw value. + * @param renderReadonly - Prepared value renderer for readonly cells. + * @param renderEditable - Input-compatible preview renderer; defaults to the readonly renderer. + * @returns Row renderer whose mode is selected by the caller after evaluating the row's edit policy. + */ +function bindDisplay>( + source: { accessorKey?: keyof T & string; accessor?: (row: T) => unknown }, + renderReadonly: ValueRenderer, + renderEditable: ValueRenderer = renderReadonly, +): LineItemsCellRenderers["renderDisplay"] { + return (row, editable) => { + const current = + source.accessorKey !== undefined ? row[source.accessorKey] : source.accessor?.(row); + return (editable ? renderEditable : renderReadonly)(current, row); + }; +} + +/** Bind the implementation used for type derivation to the same input used for rendering. */ +function bindEditor( + editor: CellEditor, + prepare: >( + settings: TSettings, + column: LineItemsColumn, + ) => { options: NoInfer } & Omit, "renderCell">, +): LineItemsEditorAdapter { + return { + editor, + prepare(settings, column) { + const { options, align, renderDisplay } = prepare(settings, column); + return { + align, + reserveIconSpace: editor.icon !== undefined, + renderCell: (props) => , + renderDisplay, + }; + }, + }; +} + +/** Assemble UI adapters and readonly presentation, binding date dependencies before rendering. */ +export function createLineItemsCellPreparers(timeZone: string) { + /** Custom output wins before any built-in value renderer is prepared. */ + function prepareDisplay>( + column: LineItemsColumn, + ): Omit, "renderCell"> { + const align = column.align ?? getDisplayCellAdapter(column.type).defaultAlign; + const render = column.render; + if (render) return { align, renderDisplay: (row) => render(row) }; + const renderReadonly = createValueRenderer(column, { timeZone }); + const renderEditable = + column.type === "link" ? createValueRenderer({ type: "text" }, { timeZone }) : renderReadonly; + return { align, renderDisplay: bindDisplay(column, renderReadonly, renderEditable) }; + } + + function prepareChoiceDisplay>( + column: LineItemsColumn, + options: CellEditorOptions["options"], + ): Omit, "renderCell"> { + const align = column.align ?? getDisplayCellAdapter(column.type).defaultAlign; + const render = column.render; + if (render) return { align, renderDisplay: (row) => render(row) }; + const resolveLabel = (value: unknown) => { + const normalized = toTextValue(value); + return normalized === null + ? undefined + : options.find((option) => option.value === normalized)?.label; + }; + if (column.type === "badge") { + const renderBadge = createValueRenderer(column, { + timeZone, + resolveBadgeLabel: (value) => resolveLabel(value) ?? value, + }); + return { align, renderDisplay: bindDisplay(column, renderBadge) }; + } + if (column.type !== undefined && column.type !== "text" && column.type !== "link") + return prepareDisplay(column); + const renderReadonly = createValueRenderer(column, { timeZone }); + const renderEditable = + column.type === "link" ? createValueRenderer({ type: "text" }, { timeZone }) : renderReadonly; + return { + align, + renderDisplay: bindDisplay( + column, + (value, row) => renderReadonly(resolveLabel(value) ?? value, row), + (value, row) => renderEditable(resolveLabel(value) ?? value, row), + ), + }; + } + + const bindings = { + text: bindEditor(textEditor, (_settings: { editorOptions?: never }, column) => ({ + options: {}, + ...prepareDisplay(column), + })), + number: bindEditor(numberEditor, (_settings: { editorOptions?: never }, column) => ({ + options: {}, + ...prepareDisplay(column), + })), + date: bindEditor( + dateEditor, + ( + { + editorOptions, + }: { editorOptions?: Omit, "timeZone"> }, + column, + ) => ({ + options: { ...editorOptions, timeZone }, + ...prepareDisplay(column), + }), + ), + choice: bindEditor( + choiceEditor, + ( + { + editorOptions: { options }, + }: { + editorOptions: Pick, "options">; + }, + column, + ) => ({ + options: { + options, + renderOption: + column.type === "badge" + ? (value, label) => ( + label} + /> + ) + : undefined, + }, + ...prepareChoiceDisplay(column, options), + }), + ), + }; + return { bindings, prepareDisplay }; +} + +type EditorCatalog = typeof lineItemsEditors; +type UIAdapters = ReturnType["bindings"]; +type EditorSettingsByKind = { + [K in keyof EditorCatalog]: Parameters["prepare"]>[0]; +}; +type EditorDefinitions = { + [K in keyof EditorSettingsByKind]: { + bind: (ui: UIAdapters) => { + prepare: >( + settings: EditorSettingsByKind[K], + column: LineItemsColumn, + ) => LineItemsCellRenderers; + }; + }; +}; + +/** Keep keyed selection correlated with its settings without another editor-kind switch. */ +function resolveEditor>( + edit: (EditorSettingsByKind[K] & { editorType: K }) | undefined, + column: LineItemsColumn, + bindings: UIAdapters, +): LineItemsCellRenderers | undefined { + if (!edit) return undefined; + const definition: EditorDefinitions[K] = lineItemsEditors[edit.editorType]; + return definition.bind(bindings).prepare(edit, column); +} + +/** Prepare and memoize cell renderers per column; row permissions choose the display mode later. */ +export function useLineItemsCellRenderersByColumn>( + columns: readonly LineItemsColumn[], + timeZone: string, +) { + return useMemo(() => { + const { bindings, prepareDisplay } = createLineItemsCellPreparers(timeZone); + return columns.map((column) => { + const renderers = resolveEditor(column.edit, column, bindings); + const presentation = renderers ?? prepareDisplay(column); + return { + column, + id: column.id ?? column.accessorKey!, + align: presentation.align, + reserveIconSpace: renderers?.reserveIconSpace ?? false, + renderCell: renderers?.renderCell, + renderDisplay: presentation.renderDisplay, + }; + }); + }, [columns, timeZone]); +} + +/** Adapts property-owned confirmation to the same cell controls used by DataTable. */ +export function LineItemsEditableCell>({ + row, + column, + edit, + renderCell, + index, + editing, + display, + cellProps, +}: { + row: T; + column: LineItemsColumn; + edit: NonNullable["edit"]>; + renderCell: LineItemsCellRenderers["renderCell"]; + index: number; + editing: LineItemsEditing; + display: ReactNode; + cellProps: ComponentProps & { align: EditableCellOwnerProps["align"] }; +}) { + const t = useLineItemsT(); + const session = editing.getSession(row, column); + const id = (column.id ?? column.accessorKey)!; + const key = editing.getLineKey(row); + const label = `${column.label ?? id}, ${t("row", { index: index + 1 })}`; + const renderError = edit.error?.render; + const props: EditableCellOwnerProps = { + current: row[column.accessorKey!], + display, + cellProps, + session, + allowClear: edit.clearValue !== false, + commit: (value) => { + try { + return editing.commitField(key, id, value); + } catch (error) { + if (error instanceof LineItemsClearError) throw new CellEditError(t("clearNotAllowed")); + throw error; + } + }, + renderError: renderError ? (error) => renderError({ row, error }) : undefined, + label, + rowKey: key, + colKey: id, + align: cellProps.align, + slotPrefix: "line-items", + labels: { + notANumber: t("notANumber"), + revertHint: t("revertHint"), + callbackError: t("callbackError"), + errorHint: t("errorHint"), + showError: t("showError", { label }), + errorDialog: t("errorDialog", { label }), + closeError: t("closeError"), + none: t("none"), + noMatches: t("noMatches"), + chooseTime: t("chooseTime"), + clear: t("clear"), + done: t("done"), + unconfirmed: t("unconfirmed"), + confirming: t("confirming"), + }, + }; + return renderCell(props); +} + +export function LineItemsDisplayCell({ + reserveIconSpace, + children, + ...props +}: ComponentProps & { reserveIconSpace: boolean }) { + return ( + + {reserveIconSpace ? ( + {children} + ) : ( + children + )} + + ); +} diff --git a/packages/core/src/components/line-items/line-items-context.ts b/packages/core/src/components/line-items/line-items-context.ts new file mode 100644 index 000000000..c12605e3c --- /dev/null +++ b/packages/core/src/components/line-items/line-items-context.ts @@ -0,0 +1,12 @@ +import { createContext, useContext } from "react"; +import type { UseLineItemsReturn } from "./types"; + +export const LineItemsContext = createContext(null); + +export function useLineItemsContext>( + part: string, +): UseLineItemsReturn { + const value = useContext(LineItemsContext) as UseLineItemsReturn | null; + if (!value) throw new Error(`${part} must be rendered inside LineItems.Root`); + return value; +} diff --git a/packages/core/src/components/line-items/line-items.test-d.ts b/packages/core/src/components/line-items/line-items.test-d.ts new file mode 100644 index 000000000..8293d3533 --- /dev/null +++ b/packages/core/src/components/line-items/line-items.test-d.ts @@ -0,0 +1,218 @@ +import { expectTypeOf, test } from "vitest"; +import type { ComponentProps } from "react"; +import { + LineItems, + useLineItems, + type LineItemsColumn, + type UseLineItemsOptions, + type UseLineItemsReturn, + type LineItemsRootProps, + type LineItemsTableProps, +} from "@/index"; +import { createLineItemsDocumentStore } from "./document/store"; +import type { LINE_ITEMS_EDITING } from "./editing"; + +type Row = { id?: string; name: string; quantity: number; detail: { nested: string } }; + +test("column styling hooks retain row types without exposing content or events", () => { + expectTypeOf["headerProps"]>>().toEqualTypeOf< + () => Pick, "className" | "style" | "title"> | undefined + >(); + expectTypeOf["cellProps"]>>().toEqualTypeOf< + (row: Row) => Pick, "className" | "style" | "title"> | undefined + >(); + expectTypeOf, "role">>().toEqualTypeOf(); + const column: LineItemsColumn = { + id: "operations", + render: (row) => row.name, + headerProps: () => ({ className: "astw:text-center" }), + cellProps: (row) => { + expectTypeOf(row).toEqualTypeOf(); + return { title: row.name, style: { color: "red" } }; + }, + }; + void column; +}); + +test("row commands retain row types without exposing unfinished save APIs", () => { + function Contract() { + const value = useLineItems({ + columns: [{ accessorKey: "quantity", type: "number" }], + defaultLines: [], + }); + expectTypeOf(value).toEqualTypeOf>(); + expectTypeOf[typeof LINE_ITEMS_EDITING]>().toEqualTypeOf(); + expectTypeOf(value.lines).toEqualTypeOf(); + expectTypeOf(value.getLineKey).toEqualTypeOf<(row: Row) => string>(); + expectTypeOf["value"]>().toEqualTypeOf>(); + expectTypeOf(value.isDirty).toEqualTypeOf(); + expectTypeOf(value.orderer).toEqualTypeOf(); + expectTypeOf["orderer"]>().toEqualTypeOf(); + value.reorderLine("A", "B"); + value.reorderLine("A", null); + const ordering: UseLineItemsOptions = { columns: [], orderer: true }; + ordering.orderer = false; + // @ts-expect-error The orderer option accepts booleans, not named policies. + ordering.orderer = "manual"; + // @ts-expect-error A movement anchor must be a current key or null. + value.reorderLine("A", 1); + value.updateField("A", "quantity", 2); + expectTypeOf( + value.addLine({ name: "New", quantity: 1, detail: { nested: "value" } }), + ).toEqualTypeOf(); + value.removeLine("A"); + value.revert(); + // @ts-expect-error A numeric property cannot receive text. + value.updateField("A", "quantity", "2"); + // @ts-expect-error A field must exist on the row. + value.updateField("A", "missing", 2); + // @ts-expect-error A new line must supply the complete editing model. + value.addLine({ name: "Incomplete" }); + // @ts-expect-error This slice does not implement document-wide confirmation or persistence. + value.commitEdits(); + // @ts-expect-error Controlled rows are not supported. + const controlled: UseLineItemsOptions = { columns: [], lines: [] }; + void controlled; + } + void Contract; + expectTypeOf[0]>().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf< + "className" | "emptyMessage" | "aria-label" + >(); +}); + +test("identity properties must be optional while other row fields stay required", () => { + type Custom = { code?: number; name: string }; + type RequiredCustom = { code: number; name: string }; + type RequiredDefault = { id: string; name: string }; + type Alternative = RequiredDefault & { code?: number }; + + function Contract() { + const value = useLineItems({ + idKey: "code", + columns: [ + { + accessorKey: "code", + render: (row) => { + expectTypeOf(row.code).toEqualTypeOf(); + // @ts-expect-error A creation has no persisted ID until it is saved. + row.code.toFixed(); + return row.code?.toFixed() ?? "New"; + }, + }, + ], + }); + expectTypeOf(value.lines).toEqualTypeOf(); + expectTypeOf(value.addLine({ name: "New" })).toEqualTypeOf(); + // @ts-expect-error Non-identity properties remain required. + value.addLine({}); + // @ts-expect-error Removing a required identity would violate the declared row type. + useLineItems({ columns: [], idKey: "code" }); + // @ts-expect-error A required default ID cannot be removed from a creation. + useLineItems({ columns: [] }); + // @ts-expect-error Explicitly selecting a required default ID is also unsafe. + useLineItems({ columns: [], idKey: "id" }); + // @ts-expect-error Explicit undefined must not bypass the required-default-ID guard. + useLineItems({ columns: [], idKey: undefined }); + + const alternative = useLineItems({ columns: [], idKey: "code" }); + alternative.addLine({ id: "Required non-identity value", name: "New" }); + // @ts-expect-error The required id is not the selected identity and must remain present. + alternative.addLine({ name: "Missing required field" }); + + const withoutId = useLineItems<{ name: string }>({ columns: [] }); + withoutId.addLine({ name: "No identity property" }); + } + void Contract; +}); + +test("the document store enforces the same optional identity contract", () => { + type Custom = { code?: number; name: string }; + type RequiredDefault = { id: string; name: string }; + const store = createLineItemsDocumentStore({ columns: [], idKey: "code" }); + expectTypeOf(store.addLine({ name: "New" })).toEqualTypeOf(); + // @ts-expect-error Direct store callers cannot select a required identity property. + createLineItemsDocumentStore<{ code: number; name: string }>({ columns: [], idKey: "code" }); + // @ts-expect-error Direct store callers cannot use a required default identity either. + createLineItemsDocumentStore({ columns: [] }); +}); + +test("identity optionality must hold across row variants and indexed records", () => { + type Variant = + | { kind: "persisted"; id: string; code: number; name: string; reference?: number } + | { kind: "draft"; id?: string; code?: number; name: string; reference?: number }; + // @ts-expect-error The default identity is required by one row variant. + createLineItemsDocumentStore({ columns: [] }); + // @ts-expect-error Explicit selection must also be optional in every variant. + createLineItemsDocumentStore({ columns: [], idKey: "id" }); + // @ts-expect-error A custom identity cannot be required by even one variant. + createLineItemsDocumentStore({ columns: [], idKey: "code" }); + createLineItemsDocumentStore({ columns: [], idKey: "reference" }); + + type Indexed = Record & { code: number; name: string }; + // @ts-expect-error An index signature must not hide a required named identity. + createLineItemsDocumentStore({ columns: [], idKey: "code" }); + type IndexedVariant = Indexed | { code?: number; name: string }; + // @ts-expect-error Indexed members cannot hide required identities in a row union either. + createLineItemsDocumentStore({ columns: [], idKey: "code" }); +}); + +test("the store adapter preserves property-specific command typing", () => { + const store = createLineItemsDocumentStore({ columns: [{ accessorKey: "quantity" }] }); + store.updateField("A", "quantity", 2); + // @ts-expect-error Notification wrappers must not widen the field's value type. + store.updateField("A", "quantity", "2"); +}); + +test("property, computed and value-less columns keep source and display contracts", () => { + expectTypeOf["width"]>().toEqualTypeOf(); + const property: LineItemsColumn = { accessorKey: "quantity", type: "number", width: 120 }; + const computed: LineItemsColumn = { + id: "double", + width: 160, + type: "number", + accessor: (row) => row.quantity * 2, + }; + const custom: LineItemsColumn = { + id: "custom", + width: 96, + render: (row) => row.detail.nested, + }; + // @ts-expect-error Widths are pixel numbers, not CSS strings. + const cssWidth: LineItemsColumn = { id: "custom", width: "96px" }; + // @ts-expect-error Property sources must exist on the row. + const missing: LineItemsColumn = { accessorKey: "missing" }; + // @ts-expect-error A string property cannot use a number renderer. + const wrongProperty: LineItemsColumn = { accessorKey: "name", type: "number" }; + // @ts-expect-error Structured values require custom rendering. + const structured: LineItemsColumn = { accessorKey: "detail", type: "text" }; + // @ts-expect-error Computed sources need a stable column ID. + const noId: LineItemsColumn = { accessor: (row) => row.quantity }; + // @ts-expect-error A typed numeric accessor cannot return text. + const wrongComputed: LineItemsColumn = { + id: "wrong", + type: "number", + accessor: (row) => row.name, + }; + // @ts-expect-error A column cannot declare both sources. + const twoSources: LineItemsColumn = { + accessorKey: "quantity", + accessor: (row: Row) => row.quantity, + }; + // @ts-expect-error A link still requires href options. + const link: LineItemsColumn = { accessorKey: "name", type: "link" }; + // @ts-expect-error Clearing a text editor emits null, which this required field cannot adopt. + const editing: LineItemsColumn = { accessorKey: "name", edit: { editorType: "text" } }; + void property; + void computed; + void custom; + void cssWidth; + void missing; + void wrongProperty; + void structured; + void noId; + void wrongComputed; + void twoSources; + void link; + void editing; +}); diff --git a/packages/core/src/components/line-items/line-items.test.tsx b/packages/core/src/components/line-items/line-items.test.tsx new file mode 100644 index 000000000..8cffe5a48 --- /dev/null +++ b/packages/core/src/components/line-items/line-items.test.tsx @@ -0,0 +1,671 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { + act, + cleanup, + fireEvent, + render, + renderHook, + screen, + within, +} from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { useState, type FormEvent } from "react"; +import { MemoryRouter } from "react-router"; +import { AppShellConfigContext, buildConfigurations } from "@/contexts/appshell-context"; +import { LineItems } from "./line-items"; +import { useLineItems } from "./use-line-items"; +import { createLineItemsIdentity } from "./document/identity"; +import type { LineItemsColumn } from "./document"; +import type { UseLineItemsReturn } from "./types"; + +afterEach(() => { + cleanup(); + vi.restoreAllMocks(); +}); + +type Row = { + id?: string; + name: string; + quantity: number; + price: number; + status: string; + date: string; +}; +const rows: Row[] = [ + { + id: "A", + name: "Widget", + quantity: 2, + price: 12.5, + status: "open", + date: "2026-10-09T00:00:00Z", + }, +]; +const columns: LineItemsColumn[] = [ + { accessorKey: "name", id: "product", label: "Product", type: "text" }, + { accessorKey: "quantity", label: "Quantity", type: "number", typeOptions: { locale: "en-US" } }, + { + accessorKey: "price", + label: "Price", + type: "money", + typeOptions: { locale: "en-US", currency: "USD" }, + }, + { + accessorKey: "status", + label: "Status", + type: "badge", + typeOptions: { badgeLabelMap: { open: "Open" } }, + }, + { accessorKey: "date", label: "Date", type: "date", typeOptions: { locale: "en-US" } }, + { + id: "total", + label: "Total", + accessor: (row) => row.quantity * row.price, + type: "money", + typeOptions: { locale: "en-US" }, + }, + { + id: "link", + label: "Link", + accessor: (row) => row.name, + type: "link", + typeOptions: { href: (row) => `/products/${row.id}` }, + }, + { + id: "custom", + label: "Custom", + render: (row) => {row.name} details, + align: "center", + }, +]; + +// Happy DOM lacks DragEvent. +function dispatchDrag(type: string, target: Element, init: MouseEventInit = {}) { + const event = Object.assign(new MouseEvent(type, { bubbles: true, cancelable: true, ...init }), { + dataTransfer: { effectAllowed: "", dropEffect: "", setData: vi.fn() }, + }); + fireEvent(target, event); + return event; +} + +function Harness({ + data = rows, + cols = columns, + timeZone = "America/New_York", + locale = "en", + emptyMessage, + orderer, +}: { + data?: Row[]; + cols?: LineItemsColumn[]; + timeZone?: string; + locale?: string; + emptyMessage?: string; + orderer?: boolean; +}) { + const value = useLineItems({ columns: cols, defaultLines: data, orderer }); + return ( + + + + + + + + ); +} + +describe("LineItems table", () => { + it("renders property, computed and custom cells through a semantic, non-editable table", () => { + const { container } = render(); + const table = screen.getByRole("table", { name: "Order lines" }); + const cells = within(table).getAllByRole("cell"); + expect(cells.map((cell) => cell.textContent)).toEqual([ + "Widget", + "2", + "$12.50", + "Open", + "Oct 8, 2026", + "$25.00", + "Widget", + "Widget details", + ]); + expect(screen.getByRole("link", { name: "Widget" }).getAttribute("href")).toBe("/products/A"); + expect( + within(table) + .getAllByRole("columnheader") + .every((header) => header.getAttribute("scope") === "col"), + ).toBe(true); + const keys = columns.map((column) => column.id ?? column.accessorKey); + expect( + within(table) + .getAllByRole("columnheader") + .map((header) => header.getAttribute("data-col-key")), + ).toEqual(keys); + expect(cells.map((cell) => cell.getAttribute("data-col-key"))).toEqual(keys); + expect(cells[1].className).toContain("astw:text-right"); + expect(cells[7].className).toContain("astw:text-center"); + expect(cells[7].className).toContain("astw:last:pr-6"); + expect(within(table).getAllByRole("columnheader")[7].className).toContain("astw:last:pr-6"); + expect(cells[0].className).toContain("astw:first:pl-6"); + expect(table.className).toContain("custom-table"); + expect(container.querySelector('[data-slot="line-items"]')?.className).toContain( + "custom-frame", + ); + expect(screen.queryByRole("textbox")).toBeNull(); + expect(screen.queryByRole("checkbox")).toBeNull(); + expect(screen.queryByRole("button")).toBeNull(); + }); + + it.each([columns[0], columns[5], columns[7]])( + "applies column styling props to property, computed, and custom columns ($id)", + (column) => { + let styled = true; + const headerProps = vi.fn(() => + styled + ? { + className: "astw:text-right astw:last:pr-2", + style: { backgroundColor: "red", width: 180 }, + title: "Custom header", + } + : undefined, + ); + const cellProps = vi.fn((row: Row) => + styled + ? { + className: "astw:text-left astw:py-1 astw:last:pr-2", + style: { color: row.id === "A" ? "red" : "blue" }, + title: row.name, + } + : undefined, + ); + const data = [rows[0], { ...rows[0], id: "B", name: "Second" }]; + const { rerender } = render( + , + ); + const header = screen.getByRole("columnheader"); + const cells = screen.getAllByRole("cell"); + const content = cells.map((cell) => cell.textContent); + expect(headerProps).toHaveBeenCalledWith(); + expect(header.title).toBe("Custom header"); + expect(header.style.width).toBe("0px"); + expect(header.style.backgroundColor).toBe("red"); + expect(header.className).toContain("astw:text-right"); + expect(header.className).toContain("astw:last:pr-2"); + expect(cells.map((cell) => cell.title)).toEqual(["Widget", "Second"]); + expect(cells.map((cell) => cell.style.color)).toEqual(["red", "blue"]); + expect(cells[0].className).toContain("astw:py-1"); + expect(cells[0].className).toContain("astw:text-left"); + rerender( + , + ); + expect(header.style.width).toBe("180px"); + styled = false; + rerender( + , + ); + expect(header.title).toBe(""); + expect(header.style.width).toBe(""); + expect(header.style.backgroundColor).toBe(""); + expect(header.className).toContain("astw:last:pr-6"); + expect(cells.map((cell) => cell.style.color)).toEqual(["", ""]); + expect(cells.map((cell) => cell.title)).toEqual(["", ""]); + expect(cells[0].className).toContain("astw:py-2"); + expect(cells.map((cell) => cell.textContent)).toEqual(content); + }, + ); + + it("does not call cellProps for an empty table", () => { + const cellProps = vi.fn(() => ({ title: "Unused" })); + render(); + expect(cellProps).not.toHaveBeenCalled(); + }); + + it("applies pixel widths to all column kinds and restores automatic sizing when omitted", () => { + const cols = [columns[0], columns[5], columns[7]].map((column, index) => ({ + ...column, + width: [200, 120, 0][index], + })); + const { rerender } = render(); + const headers = screen.getAllByRole("columnheader") as HTMLTableCellElement[]; + const row = screen.getAllByRole("row")[1]; + expect(headers.slice(1).map((header) => header.style.width)).toEqual(["200px", "120px", "0px"]); + expect(screen.getByRole("table").style.tableLayout).toBe(""); + rerender(); + expect(headers.slice(1).map((header) => header.style.width)).toEqual(["", "", "96px"]); + expect(screen.getAllByRole("row")[1]).toBe(row); + }); + + it("does not infer a value from a source-less column's ID", () => { + render(); + expect(screen.getByRole("cell").textContent).toBe("—"); + }); + + it("keeps custom rendering authoritative, including null output", () => { + const accessor = vi.fn(() => "2026-10-09"); + render( + null, + }, + ]} + />, + ); + expect(screen.getByRole("cell").textContent).toBe(""); + expect(accessor).not.toHaveBeenCalled(); + }); + + it("retains initial rows while accepting new columns and timezone configuration", () => { + const { rerender } = render(); + const firstRow = screen.getAllByRole("row")[1]; + rerender( + , + ); + expect(screen.getByText("Widget")).toBeDefined(); + expect(screen.queryByText("Replacement")).toBeNull(); + expect(screen.getByText("Oct 9, 2026")).toBeDefined(); + expect(screen.getAllByRole("row")[1]).toBe(firstRow); + expect(screen.getAllByRole("columnheader")).toHaveLength(5); + }); + + it("shares date formatters across rows and repeated rendering", () => { + const DateTimeFormat = Intl.DateTimeFormat; + const spy = vi.spyOn(Intl, "DateTimeFormat").mockImplementation(function (locale, options) { + return new DateTimeFormat(locale, options); + }); + const data = [rows[0], { ...rows[0], id: "B", date: "2026-10-09" }]; + const cols = [columns[4]]; + const { rerender } = render(); + rerender(); + expect( + spy.mock.calls + .filter(([locale, options]) => locale === "en-US" && options?.month === "short") + .map(([, options]) => options?.timeZone), + ).toEqual(["America/New_York", "UTC"]); + }); + + it.each([ + { count: 2, message: "No order lines", orderer: true }, + { count: 0, message: undefined, orderer: true }, + { count: 2, message: "No order lines", orderer: false }, + { count: 0, message: undefined, orderer: false }, + ])("spans all columns when empty ($count, orderer: $orderer)", ({ count, message, orderer }) => { + render( + , + ); + expect(screen.getByRole("cell").getAttribute("colspan")).toBe( + String(Math.max(1, count + (orderer ? 1 : 0))), + ); + expect(screen.getByText(message ?? "No lines yet.")).toBeDefined(); + expect(screen.queryByRole("button")).toBeNull(); + }); + + it("moves persisted and unsaved rows by default with keyboard focus and boundary guards", async () => { + const user = userEvent.setup(); + const submit = vi.fn((event: FormEvent) => event.preventDefault()); + const data = [ + rows[0], + { ...rows[0], id: "B", name: "Second" }, + { ...rows[0], id: undefined, name: "Unsaved" }, + { ...rows[0], id: "D", name: "Fourth" }, + { ...rows[0], id: "E", name: "Fifth" }, + ]; + render( +
+ + , + ); + const table = screen.getByRole("table", { name: "Order lines" }); + const originalRows = within(table).getAllByRole("row").slice(1); + const names = () => + within(table) + .getAllByRole("row") + .slice(1) + .map((row) => within(row).getAllByRole("cell")[1].textContent); + const handle = screen.getByRole("button", { name: "Reorder line 3" }); + const handleCell = within(originalRows[2]).getAllByRole("cell")[0]; + expect(handleCell.contains(handle)).toBe(true); + expect(handleCell.className).toContain("astw:first:pl-0"); + expect(handleCell.className).not.toContain("astw:first:pl-6"); + const handleHead = within(table).getAllByRole("columnheader")[0]; + expect(handleHead.className).toContain("astw:first:pl-0"); + expect(handleHead.className).not.toContain("astw:first:pl-6"); + expect(handle.getAttribute("draggable")).toBe("true"); + expect(screen.getAllByRole("button")).toHaveLength(5); + + await user.click(handle); + await user.keyboard("{ArrowUp}"); + expect(names()).toEqual(["Widget", "Unsaved", "Second", "Fourth", "Fifth"]); + expect(document.activeElement).toBe(handle); + await user.keyboard("{ArrowUp}"); + expect(names()).toEqual(["Unsaved", "Widget", "Second", "Fourth", "Fifth"]); + await user.keyboard("{ArrowUp}"); + expect(names()).toEqual(["Unsaved", "Widget", "Second", "Fourth", "Fifth"]); + expect(document.activeElement).toBe(handle); + + await user.keyboard("{ArrowDown}{ArrowDown}"); + expect(names()).toEqual(["Widget", "Second", "Unsaved", "Fourth", "Fifth"]); + await user.keyboard("{ArrowDown}{ArrowDown}"); + expect(names()).toEqual(["Widget", "Second", "Fourth", "Fifth", "Unsaved"]); + await user.keyboard("{ArrowDown}{Enter}"); + expect(names()).toEqual(["Widget", "Second", "Fourth", "Fifth", "Unsaved"]); + expect(document.activeElement).toBe(handle); + expect(within(table).getAllByRole("row").slice(1)).toEqual([ + originalRows[0], + originalRows[1], + originalRows[3], + originalRows[4], + originalRows[2], + ]); + expect(submit).not.toHaveBeenCalled(); + }); + + it.each([ + { + from: 0, + target: 4, + after: true, + expected: ["Second", "Unsaved", "Fourth", "Fifth", "Widget"], + }, + { + from: 4, + target: 0, + after: false, + expected: ["Fifth", "Widget", "Second", "Unsaved", "Fourth"], + }, + { + from: 2, + target: 3, + after: true, + expected: ["Widget", "Second", "Fourth", "Unsaved", "Fifth"], + }, + { + from: 4, + target: 1, + after: false, + expected: ["Widget", "Fifth", "Second", "Unsaved", "Fourth"], + }, + { + from: 2, + target: 2, + after: true, + expected: ["Widget", "Second", "Unsaved", "Fourth", "Fifth"], + }, + { + from: 2, + target: 2, + after: false, + expected: ["Widget", "Second", "Unsaved", "Fourth", "Fifth"], + }, + { + from: 2, + target: 1, + after: true, + expected: ["Widget", "Second", "Unsaved", "Fourth", "Fifth"], + }, + { + from: 2, + target: 3, + after: false, + expected: ["Widget", "Second", "Unsaved", "Fourth", "Fifth"], + }, + ])("drops row $from at row $target (after: $after)", ({ from, target, after, expected }) => { + const data = [ + rows[0], + { ...rows[0], id: "B", name: "Second" }, + { ...rows[0], id: undefined, name: "Unsaved" }, + { ...rows[0], id: "D", name: "Fourth" }, + { ...rows[0], id: "E", name: "Fifth" }, + ]; + render(); + const bodyRows = screen.getAllByRole("row").slice(1); + const handle = within(bodyRows[from]).getByRole("button"); + expect(within(bodyRows[from]).getAllByRole("cell")[0].contains(handle)).toBe(true); + vi.spyOn(bodyRows[target], "getBoundingClientRect").mockReturnValue( + new DOMRect(0, 100, 400, 40), + ); + const drop = { clientY: after ? 130 : 110 }; + handle.focus(); + const start = dispatchDrag("dragstart", handle); + expect(bodyRows[from].getAttribute("data-dragging")).toBe(""); + expect(start.dataTransfer.effectAllowed).toBe("move"); + const hover = dispatchDrag("dragover", bodyRows[target], drop); + expect(bodyRows[target].getAttribute("data-drop-position")).toBe(after ? "after" : "before"); + expect(hover.dataTransfer.dropEffect).toBe("move"); + dispatchDrag("drop", bodyRows[target], drop); + expect( + screen + .getAllByRole("row") + .slice(1) + .map((row) => within(row).getAllByRole("cell")[1].textContent), + ).toEqual(expected); + expect(document.activeElement).toBe(handle); + expect( + bodyRows.every( + (row) => !row.hasAttribute("data-drop-position") && !row.hasAttribute("data-dragging"), + ), + ).toBe(true); + }); + + it("ignores foreign drops and clears indicators when dragging is cancelled or leaves the table", () => { + const data = [rows[0], { ...rows[0], id: "B", name: "Second" }]; + render( + <> + + + , + ); + const tables = screen.getAllByRole("table", { name: "Order lines" }); + const source = within(tables[0]).getAllByRole("row")[1]; + const target = within(tables[0]).getAllByRole("row")[2]; + const foreign = within(tables[1]).getAllByRole("row")[2]; + const handle = within(source).getByRole("button"); + dispatchDrag("dragstart", handle); + dispatchDrag("dragover", foreign, { clientY: 1 }); + dispatchDrag("drop", foreign, { clientY: 1 }); + expect(foreign.hasAttribute("data-drop-position")).toBe(false); + dispatchDrag("dragover", target, { clientY: 1 }); + expect(target.hasAttribute("data-drop-position")).toBe(true); + dispatchDrag("dragleave", target.parentElement!, { + relatedTarget: within(target).getAllByRole("cell")[0], + }); + expect(target.hasAttribute("data-drop-position")).toBe(true); + dispatchDrag("dragleave", target.parentElement!, { relatedTarget: null }); + expect(target.hasAttribute("data-drop-position")).toBe(false); + dispatchDrag("dragover", target, { clientY: 1 }); + dispatchDrag("dragend", handle); + expect(source.hasAttribute("data-dragging")).toBe(false); + expect(target.hasAttribute("data-drop-position")).toBe(false); + dispatchDrag("drop", target, { clientY: 1 }); + for (const table of tables) { + expect( + within(table) + .getAllByRole("row") + .slice(1) + .map((row) => within(row).getAllByRole("cell")[1].textContent), + ).toEqual(["Widget", "Second"]); + } + }); + + it("hides ordering controls when disabled and preserves rows across policy changes", async () => { + const user = userEvent.setup(); + const data = [rows[0], { ...rows[0], id: "B", name: "Second" }]; + const { rerender } = render(); + expect(screen.queryByRole("button")).toBeNull(); + expect(screen.queryByRole("columnheader", { name: "Order" })).toBeNull(); + rerender(); + dispatchDrag("dragstart", screen.getByRole("button", { name: "Reorder line 1" })); + dispatchDrag("dragover", screen.getAllByRole("row")[2], { clientY: 1 }); + rerender(); + dispatchDrag("drop", screen.getAllByRole("row")[2], { clientY: 1 }); + rerender(); + dispatchDrag("drop", screen.getAllByRole("row")[2], { clientY: 1 }); + expect(within(screen.getAllByRole("row")[1]).getAllByRole("cell")[1].textContent).toBe( + "Widget", + ); + await user.click(screen.getByRole("button", { name: "Reorder line 1" })); + await user.keyboard("{ArrowDown}"); + const movedRows = screen.getAllByRole("row").slice(1); + rerender(); + expect(screen.queryByRole("button")).toBeNull(); + expect(screen.queryByRole("columnheader", { name: "Order" })).toBeNull(); + expect(screen.getAllByRole("row").slice(1)).toEqual(movedRows); + expect(within(movedRows[0]).getAllByRole("cell")[0].textContent).toBe("Second"); + }); + + it("disables reordering for a single row and localizes ordering labels", async () => { + const user = userEvent.setup(); + render(); + expect(screen.getByRole("columnheader", { name: "並び順" })).toBeDefined(); + const handle = screen.getByRole("button", { name: "1行目の並び替え" }); + expect(handle.getAttribute("aria-disabled")).toBe("true"); + expect(handle.getAttribute("draggable")).toBe("false"); + await user.click(handle); + await user.keyboard("{ArrowUp}{ArrowDown}"); + expect(screen.getAllByRole("row")).toHaveLength(2); + }); + + it("reflects row commands without remounting existing rows or adding editor UI", () => { + let value!: UseLineItemsReturn; + function DocumentTable() { + value = useLineItems({ columns, defaultLines: rows }); + return ( + + + + + + ); + } + render(); + const firstRow = screen.getAllByRole("row")[1]; + act(() => value.updateField("A", "quantity", 3)); + expect(screen.getByText("$37.50")).toBeDefined(); + expect(screen.getAllByRole("row")[1]).toBe(firstRow); + let key = ""; + act(() => { + key = value.addLine({ ...rows[0], name: "New line" }); + }); + const creationRow = screen.getAllByRole("row")[2]; + act(() => value.updateField(key, "quantity", 4)); + expect(screen.getAllByRole("row")[2]).toBe(creationRow); + act(() => value.reorderLine("A", key)); + expect(screen.getAllByRole("row")[1]).toBe(creationRow); + expect(screen.getAllByRole("row")[2]).toBe(firstRow); + expect(value.isDirty).toBe(true); + act(() => { + value.removeLine("A"); + value.revert(); + }); + expect(screen.getAllByRole("row")).toHaveLength(2); + expect(screen.getByText("$25.00")).toBeDefined(); + expect(value.isDirty).toBe(false); + expect(screen.queryByRole("textbox")).toBeNull(); + }); + + it("preserves the row, focus and cell draft when a creation receives a persisted ID", () => { + function DraftCell() { + const [draft, setDraft] = useState(""); + return ( + setDraft(event.currentTarget.value)} + /> + ); + } + const identity = createLineItemsIdentity("id"); + const clientKey = identity.newClientKey(); + const creation = identity.tag({ ...rows[0], id: undefined }, clientKey); + identity.remember([creation]); + const { result: owner } = renderHook(() => useLineItems({ columns: [] })); + const value: UseLineItemsReturn = { + ...owner.current, + columns: [{ id: "draft", render: () => }], + lines: [creation], + orderer: true, + isDirty: true, + getLineKey: identity.getLineKey, + updateField: vi.fn(), + addLine: vi.fn(() => ""), + removeLine: vi.fn(), + reorderLine: vi.fn(), + revert: vi.fn(), + }; + const { rerender } = render( + + + + + , + ); + const row = screen.getAllByRole("row")[1]; + const editor = screen.getByRole("textbox", { name: "Draft name" }); + fireEvent.change(editor, { target: { value: "Unsaved draft" } }); + editor.focus(); + expect(value.getLineKey(creation)).toBe(clientKey); + + const persisted = identity.tag({ ...creation, id: "A" }, clientKey); + identity.remember([persisted]); + rerender( + + + + + , + ); + + expect(value.getLineKey(persisted)).toBe("A"); + expect(screen.getAllByRole("row")[1]).toBe(row); + expect(screen.getByRole("textbox", { name: "Draft name" })).toBe(editor); + expect(document.activeElement).toBe(editor); + expect(editor.value).toBe("Unsaved draft"); + }); + + it("localizes the default table name and empty state", () => { + function Japanese() { + const value = useLineItems({ columns, defaultLines: [] }); + return ( + + + + ); + } + render( + + + , + ); + expect(screen.getByRole("table", { name: "明細" })).toBeDefined(); + expect(screen.getByText("明細がありません。")).toBeDefined(); + }); + + it("requires Root context", () => { + expect(() => render()).toThrow( + "LineItems.Table must be rendered inside LineItems.Root", + ); + }); +}); diff --git a/packages/core/src/components/line-items/line-items.tsx b/packages/core/src/components/line-items/line-items.tsx new file mode 100644 index 000000000..303129c98 --- /dev/null +++ b/packages/core/src/components/line-items/line-items.tsx @@ -0,0 +1,167 @@ +import type { ReactNode } from "react"; +import { GripVerticalIcon } from "lucide-react"; +import { Table } from "@/components/table"; +import { Text } from "@/components/text"; +import { useTimeZone } from "@/contexts/appshell-context"; +import { cn } from "@/lib/utils"; +import { LineItemsContext, useLineItemsContext } from "./line-items-context"; +import { useLineItemsT } from "./i18n"; +import { useLineItemsReorder } from "./use-line-items-reorder"; +import { clientKeyOf } from "./document/identity"; +import { getLineItemsEditing } from "./editing"; +import { + LineItemsDisplayCell, + LineItemsEditableCell, + useLineItemsCellRenderersByColumn, +} from "./line-items-cell"; +import type { UseLineItemsReturn } from "./types"; + +export type LineItemsRootProps> = { + value: UseLineItemsReturn; + children: ReactNode; + className?: string; +}; + +function Root>({ + value, + children, + className, +}: LineItemsRootProps) { + return ( + +
+ {children} +
+
+ ); +} + +export type LineItemsTableProps = { + className?: string; + emptyMessage?: ReactNode; + "aria-label"?: string; +}; + +function LineItemsTable({ className, emptyMessage, "aria-label": label }: LineItemsTableProps) { + const value = useLineItemsContext>("LineItems.Table"); + const { value: timeZone } = useTimeZone(); + const t = useLineItemsT(); + const reorder = useLineItemsReorder(value); + const cellsByColumn = useLineItemsCellRenderersByColumn(value.columns, timeZone); + return ( + + {label ?? t("title")} + + + {value.orderer && ( + + {t("order")} + + )} + {cellsByColumn.map(({ column, id, align }) => { + const headerProps = column.headerProps?.(); + return ( + + {column.label} + + ); + })} + + + + {value.lines.map((row, index) => ( + + {value.orderer && ( + + {/* shortcut: native dragging is desktop-only, add pointer dragging if touch dragging is required. */} + + + )} + {cellsByColumn.map( + ({ column, renderCell, id, align, renderDisplay, reserveIconSpace }) => { + const edit = column.edit; + const customCellProps = column.cellProps?.(row); + const cellProps = { + align, + "data-col-key": id, + className: customCellProps?.className, + style: customCellProps?.style, + title: customCellProps?.title, + }; + if (!edit || !renderCell || !(edit.canEdit?.(row) ?? true)) + return ( + + {renderDisplay(row, false)} + + ); + return ( + + ); + }, + )} + + ))} + {value.lines.length === 0 && ( + + + + {emptyMessage ?? t("empty")} + + + + )} + + + ); +} + +Root.displayName = "LineItems.Root"; +LineItemsTable.displayName = "LineItems.Table"; +export const LineItems = { Root, Table: LineItemsTable }; diff --git a/packages/core/src/components/line-items/restored-presentation.test.tsx b/packages/core/src/components/line-items/restored-presentation.test.tsx new file mode 100644 index 000000000..3cf59d5b2 --- /dev/null +++ b/packages/core/src/components/line-items/restored-presentation.test.tsx @@ -0,0 +1,310 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { act, cleanup, fireEvent, render, screen } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { MemoryRouter } from "react-router"; +import { AppShellConfigContext, buildConfigurations } from "@/contexts/appshell-context"; +import { LineItems } from "./line-items"; +import { useLineItems } from "./use-line-items"; +import type { UseLineItemsReturn } from "./types"; +import { Table } from "@/components/table"; +import { Tooltip } from "@/components/tooltip"; +import { createCellEditSession } from "@/components/internals/table-core/cell-session"; +import { EditableCell } from "@/components/internals/table-core/editing/cell"; +import { textEditor, numberEditor } from "@/components/internals/table-core/editing/typing"; +import { choiceEditor } from "@/components/internals/table-core/editing/choice"; +import { dateEditor } from "@/components/internals/table-core/editing/date"; +import type { CellEditorLabels } from "@/components/internals/table-core/editing/props"; + +// Exercise the shared presentation with the document-retained sessions used by LineItems. +afterEach(cleanup); +const labels: CellEditorLabels = { + notANumber: "Not a number", + revertHint: "Esc to revert", + callbackError: "Could not confirm", + errorHint: "Check the value", + showError: "Show error", + errorDialog: "Cell error", + closeError: "Close error", + none: "None", + noMatches: "No matches", + chooseTime: "Time", + clear: "Clear", + done: "Done", + unconfirmed: "Unconfirmed input", + confirming: "Confirming input", +}; + +function setup({ numeric = false, retained = true, commit = vi.fn() } = {}) { + const session = createCellEditSession(); + function View({ show = true }: { show?: boolean }) { + return show ? ( + + + + + , string | number | null> + editor={numeric ? numberEditor : textEditor} + options={{}} + current={numeric ? 2 : "Initial"} + display={numeric ? "2" : "Initial"} + cellProps={{}} + session={retained ? session : undefined} + commit={commit} + labels={labels} + slotPrefix="line-items" + rowKey="A" + colKey="value" + label="Value" + align="left" + /> + + + + + ) : null; + } + const view = render(); + return { + ...view, + session, + commit, + user: userEvent.setup(), + show: (show: boolean) => view.rerender(), + }; +} +const input = () => screen.getByRole("textbox", { name: "Value" }) as HTMLInputElement; +const marker = () => document.querySelector('[data-slot="line-items-cell-unconfirmed"]'); +function draft(value: string) { + act(() => input().focus()); + fireEvent.change(input(), { target: { value } }); +} + +describe("document-owned draft presentation", () => { + it("keeps a dismissed LineItems error and unadopted draft when its table remounts", async () => { + type Row = { id?: string; name: string | null }; + const commit = vi.fn(() => { + throw new Error("Rejected"); + }); + let value!: UseLineItemsReturn; + const configurations = buildConfigurations({ modules: [], locale: "en", timeZone: "UTC" }); + function Owner({ show = true }: { show?: boolean }) { + value = useLineItems({ + columns: [ + { + accessorKey: "name", + label: "Name", + edit: { editorType: "text", onValueCommitted: commit }, + }, + ], + defaultLines: [{ id: "A", name: "Initial" }], + orderer: false, + }); + return ( + + + {show && } + + + ); + } + const view = render(); + const field = () => screen.getByRole("textbox", { name: "Name, Row 1" }) as HTMLInputElement; + act(() => field().focus()); + expect(marker()).toBeNull(); + fireEvent.change(field(), { target: { value: "Retained" } }); + expect(marker()).toBeNull(); + view.rerender(); + expect(commit).not.toHaveBeenCalled(); + view.rerender(); + expect(field().value).toBe("Retained"); + expect(marker()).not.toBeNull(); + expect(document.activeElement).not.toBe(field()); + fireEvent.keyDown(field(), { key: "Enter" }); + const user = userEvent.setup(); + await user.click(await screen.findByRole("button", { name: "Close error details" })); + view.rerender(); + view.rerender(); + expect(field().value).toBe("Retained"); + expect(field().getAttribute("aria-invalid")).toBe("true"); + expect(screen.queryByRole("dialog", { name: "Error for Name, Row 1" })).toBeNull(); + expect(value.lines[0].name).toBe("Initial"); + expect(value.isDirty).toBe(false); + expect(commit).toHaveBeenCalledTimes(1); + await user.click(screen.getByRole("button", { name: "Show error for Name, Row 1" })); + expect(await screen.findByRole("dialog", { name: "Error for Name, Row 1" })).toBeDefined(); + }); + + it.each([ + { numeric: false, cosmetic: "Initial", changed: "Changed" }, + { numeric: true, cosmetic: "2.00", changed: "2.5" }, + ])( + "keeps focused typing quiet but accessible (numeric: $numeric)", + async ({ numeric, cosmetic, changed }) => { + const editor = setup({ numeric }); + act(() => input().focus()); + expect(marker()).toBeNull(); + fireEvent.change(input(), { target: { value: cosmetic } }); + expect(input().hasAttribute("aria-describedby")).toBe(false); + fireEvent.change(input(), { target: { value: changed } }); + expect(marker()).toBeNull(); + const description = document.getElementById(input().getAttribute("aria-describedby")!); + expect(description?.textContent).toBe("Unconfirmed input"); + expect(document.querySelector('[data-slot="tooltip-content"]')).toBeNull(); + await editor.user.hover(screen.getByRole("cell")); + expect(document.querySelector('[data-slot="tooltip-content"]')).toBeNull(); + expect(editor.commit).not.toHaveBeenCalled(); + act(() => editor.session.cancel()); + expect(marker()).toBeNull(); + expect(input().hasAttribute("aria-describedby")).toBe(false); + }, + ); + + it.each([false, true])( + "restores a quiet marked draft without committing (numeric: %s)", + async (numeric) => { + const editor = setup({ numeric }); + const value = numeric ? "2.5" : "Retained"; + draft(value); + editor.show(false); + expect(editor.commit).not.toHaveBeenCalled(); + editor.show(true); + expect(input().value).toBe(value); + expect(marker()).not.toBeNull(); + expect(marker()?.getAttribute("aria-hidden")).toBe("true"); + expect(marker()?.hasAttribute("tabindex")).toBe(false); + expect(document.activeElement).not.toBe(input()); + expect(document.querySelector('[data-slot="tooltip-content"]')).toBeNull(); + expect(editor.commit).not.toHaveBeenCalled(); + await editor.user.hover(screen.getByRole("cell")); + expect(document.querySelector('[data-slot="tooltip-content"]')).toBeNull(); + await editor.user.click(input()); + expect(marker()).toBeNull(); + expect(document.querySelector('[data-slot="tooltip-content"]')).toBeNull(); + expect(editor.commit).not.toHaveBeenCalled(); + fireEvent.keyDown(input(), { key: "Escape" }); + expect(input().value).toBe(numeric ? "2" : "Initial"); + expect(marker()).toBeNull(); + }, + ); + + it.each([false, true])("uses only a spinner while confirming (numeric: %s)", async (numeric) => { + let resolve!: () => void; + const request = new Promise((success) => { + resolve = success; + }); + const editor = setup({ numeric, commit: vi.fn(() => request) }); + draft(numeric ? "2.5" : "Pending"); + fireEvent.keyDown(input(), { key: "Enter" }); + expect(marker()).toBeNull(); + const status = document.querySelector('[data-slot="line-items-cell-confirming"]'); + expect(status?.querySelector('[data-slot="spinner"]')).not.toBeNull(); + expect(screen.getByRole("cell").getAttribute("aria-busy")).toBe("true"); + expect(document.getElementById(input().getAttribute("aria-describedby")!)?.textContent).toBe( + "Confirming input", + ); + expect(document.querySelector('[data-slot="tooltip-content"]')).toBeNull(); + await editor.user.hover(screen.getByRole("cell")); + expect(document.querySelector('[data-slot="tooltip-content"]')).toBeNull(); + editor.show(false); + editor.show(true); + expect(document.querySelector('[data-slot="line-items-cell-confirming"]')).not.toBeNull(); + expect(editor.commit).toHaveBeenCalledTimes(1); + await act(async () => { + resolve(); + await request; + }); + expect(document.querySelector('[data-slot="line-items-cell-confirming"]')).toBeNull(); + expect(screen.getByRole("cell").getAttribute("aria-busy")).toBeNull(); + }); + + it("retains dismissal through remount, allows reopening and opens a new retry failure", async () => { + const error = new Error("Rejected"); + const editor = setup({ + commit: vi.fn(() => { + throw error; + }), + }); + draft("Rejected draft"); + fireEvent.keyDown(input(), { key: "Enter" }); + expect(marker()).toBeNull(); + expect(await screen.findByRole("dialog", { name: "Cell error" })).toBeDefined(); + await editor.user.click(screen.getByRole("button", { name: "Close error" })); + expect(screen.queryByRole("dialog", { name: "Cell error" })).toBeNull(); + editor.show(false); + editor.show(true); + expect(input().value).toBe("Rejected draft"); + expect(input().getAttribute("aria-invalid")).toBe("true"); + expect(screen.queryByRole("dialog", { name: "Cell error" })).toBeNull(); + fireEvent.keyDown(input(), { key: "ArrowDown", altKey: true }); + expect(await screen.findByRole("dialog", { name: "Cell error" })).toBeDefined(); + await editor.user.click(screen.getByRole("button", { name: "Close error" })); + fireEvent.keyDown(input(), { key: "Enter" }); + expect(editor.commit).toHaveBeenCalledTimes(2); + expect(await screen.findByRole("dialog", { name: "Cell error" })).toBeDefined(); + }); + + it("does not add draft markers to local DataTable-style sessions", () => { + setup({ retained: false }); + draft("Changed"); + expect(marker()).toBeNull(); + expect(input().hasAttribute("aria-describedby")).toBe(false); + }); + + it.each(["choice", "date"] as const)( + "restores a marked %s draft without opening its popup", + (kind) => { + const session = createCellEditSession(); + session.change( + kind === "choice" + ? { value: "closed", label: "Closed" } + : { day: "2026-10-20", time: null }, + ); + const common = { + session, + display: "Initial", + cellProps: {}, + commit: vi.fn(), + labels, + slotPrefix: "line-items", + rowKey: "A", + colKey: "value", + label: "Value", + align: "left" as const, + }; + render( + + + + {kind === "choice" ? ( + + ) : ( + + )} + + + , + ); + expect(marker()).not.toBeNull(); + expect(screen.queryByRole("listbox")).toBeNull(); + expect(document.querySelector('[data-slot="line-items-cell-calendar"]')).toBeNull(); + expect(common.commit).not.toHaveBeenCalled(); + act(() => + screen.getByRole(kind === "choice" ? "combobox" : "button", { name: /^Value/ }).focus(), + ); + expect(marker()).not.toBeNull(); + expect(document.querySelector('[data-slot="tooltip-content"]')?.textContent).toBe( + "Unconfirmed input", + ); + }, + ); +}); diff --git a/packages/core/src/components/line-items/types.ts b/packages/core/src/components/line-items/types.ts new file mode 100644 index 000000000..4c8323d05 --- /dev/null +++ b/packages/core/src/components/line-items/types.ts @@ -0,0 +1,34 @@ +import type { LineItemsColumn } from "./document"; +import type { LineItemsIdentityOptions } from "./document/types"; +import type { LINE_ITEMS_EDITING } from "./editing"; + +export type { LineItemsColumn, LineItemsEditor } from "./document/types"; + +/** Initial document ownership, cell editing and row commands; persistence is not yet supported. */ +export type UseLineItemsOptions> = { + columns: readonly LineItemsColumn[]; + /** Read once. ID-less rows are unsaved creations and are removed by revert. Remount the hook's owner to display another document. */ + defaultLines?: readonly TRow[]; + /** Enables manual row movement. Defaults to true; false does not restrict other row commands. */ + orderer?: boolean; +} & LineItemsIdentityOptions; + +export type UseLineItemsReturn> = { + /** Internal handle retained by object spread; not a second owner of row data. */ + readonly [LINE_ITEMS_EDITING]: object; + readonly columns: readonly LineItemsColumn[]; + readonly lines: readonly TRow[]; + readonly orderer: boolean; + /** Adopted changes or unsaved creations; unconfirmed cell drafts are not included. */ + readonly isDirty: boolean; + getLineKey: (row: TRow) => string; + /** Updates an accessorKey-owned property and discards its drafts; persisted identity cannot change. */ + updateField: (lineKey: string, key: K, value: TRow[K]) => void; + /** Appends a new creation without requiring an ID; removes any supplied persisted ID. */ + addLine: (line: TRow) => string; + removeLine: (lineKey: string) => void; + /** Moves a line after another current line; null moves it to the front. Requires orderer: true. */ + reorderLine: (lineKey: string, afterLineKey: string | null) => void; + /** Restores persisted initial rows and discards all unsaved creations and cell drafts. */ + revert: () => void; +}; diff --git a/packages/core/src/components/line-items/use-line-items-reorder.test.tsx b/packages/core/src/components/line-items/use-line-items-reorder.test.tsx new file mode 100644 index 000000000..43bc740a0 --- /dev/null +++ b/packages/core/src/components/line-items/use-line-items-reorder.test.tsx @@ -0,0 +1,255 @@ +import type { DragEvent, KeyboardEvent, ReactNode } from "react"; +import { act, cleanup, renderHook } from "@testing-library/react"; +import { afterEach, expect, it, vi } from "vitest"; +import { AppShellConfigContext, buildConfigurations } from "@/contexts/appshell-context"; +import { useLineItems } from "./use-line-items"; +import { useLineItemsReorder } from "./use-line-items-reorder"; +import { createLineItemsIdentity } from "./document/identity"; +import type { UseLineItemsReturn } from "./types"; + +type Row = { id?: string; name: string }; +const handles = new Set(); +afterEach(() => { + cleanup(); + handles.forEach((handle) => handle.remove()); + handles.clear(); + vi.restoreAllMocks(); +}); + +function Wrapper({ children }: { children: ReactNode }) { + return ( + + {children} + + ); +} + +function setup(initialOrderer?: boolean) { + const hook = renderHook( + ({ orderer }: { orderer?: boolean }) => { + const value = useLineItems({ + columns: [{ accessorKey: "name" }], + defaultLines: [ + { id: "A", name: "First" }, + { id: "B", name: "Second" }, + { id: "C", name: "Third" }, + ], + orderer, + }); + return { value, reorder: useLineItemsReorder(value) }; + }, + { initialProps: { orderer: initialOrderer }, wrapper: Wrapper }, + ); + return { + ...hook, + keys: () => hook.result.current.value.lines.map(hook.result.current.value.getLineKey), + }; +} + +function mountedHandle() { + const handle = document.createElement("button"); + handle.type = "button"; + document.body.append(handle); + handles.add(handle); + return handle; +} + +function targetRow() { + const row = document.createElement("tr"); + vi.spyOn(row, "getBoundingClientRect").mockReturnValue(new DOMRect(0, 100, 400, 40)); + return row; +} + +function dragEvent( + currentTarget: T, + clientY = 0, + relatedTarget: Node | null = null, +) { + return { + currentTarget, + clientY, + relatedTarget, + dataTransfer: { effectAllowed: "", dropEffect: "", setData: vi.fn() }, + preventDefault: vi.fn(), + stopPropagation: vi.fn(), + } as unknown as DragEvent; +} + +function keyEvent(currentTarget: HTMLButtonElement, key: string) { + return { + currentTarget, + key, + preventDefault: vi.fn(), + } as unknown as KeyboardEvent; +} + +it.each([ + { from: 0, target: 2, after: true, expected: ["B", "C", "A"] }, + { from: 2, target: 0, after: false, expected: ["C", "A", "B"] }, + { from: 0, target: 2, after: false, expected: ["B", "A", "C"] }, + { from: 2, target: 0, after: true, expected: ["A", "C", "B"] }, + { from: 2, target: 1, after: true, expected: ["A", "B", "C"] }, +])( + "inserts row $from at row $target (after: $after), including no-op gaps", + ({ from, target, after, expected }) => { + const { result, keys } = setup(); + const handle = mountedHandle(); + const start = dragEvent(handle); + const drop = dragEvent(targetRow(), after ? 130 : 110); + handle.focus(); + act(() => result.current.reorder.getHandleProps(from).onDragStart(start)); + expect(start.dataTransfer.effectAllowed).toBe("move"); + expect(start.dataTransfer.setData).toHaveBeenCalledWith("text/plain", ""); + expect(result.current.reorder.getRowProps(from)["data-dragging"]).toBe(""); + act(() => result.current.reorder.getRowProps(target).onDragOver(drop)); + expect(drop.dataTransfer.dropEffect).toBe("move"); + expect(result.current.reorder.getRowProps(target)["data-drop-position"]).toBe( + after ? "after" : "before", + ); + expect(keys()).toEqual(["A", "B", "C"]); + act(() => result.current.reorder.getRowProps(target).onDrop(drop)); + expect(keys()).toEqual(expected); + expect(result.current.value.isDirty).toBe(expected.join(",") !== "A,B,C"); + expect(document.activeElement).toBe(handle); + expect(result.current.reorder.getRowProps(0)["data-dragging"]).toBeUndefined(); + expect(result.current.reorder.getRowProps(target)["data-drop-position"]).toBeUndefined(); + }, +); + +it("retains drag identities across persisted ID assignment and dispatches current line keys", () => { + const identity = createLineItemsIdentity("id"); + const lines = ["First", "Second"].map((name) => identity.tag({ name }, identity.newClientKey())); + identity.remember(lines); + const { result: owner } = renderHook(() => useLineItems({ columns: [] })); + const value: UseLineItemsReturn = { + ...owner.current, + columns: [{ accessorKey: "name" }], + lines, + orderer: true, + isDirty: true, + getLineKey: identity.getLineKey, + updateField: vi.fn(), + addLine: vi.fn(() => ""), + removeLine: vi.fn(), + reorderLine: vi.fn(), + revert: vi.fn(), + }; + const { result, rerender } = renderHook( + (current: UseLineItemsReturn) => useLineItemsReorder(current), + { initialProps: value }, + ); + const handle = mountedHandle(); + const drop = dragEvent(targetRow(), 130); + act(() => result.current.getHandleProps(0).onDragStart(dragEvent(handle))); + act(() => result.current.getRowProps(1).onDragOver(drop)); + + const persisted = lines.map((line, index) => + identity.tag({ ...line, id: index === 0 ? "A" : "B" }, identity.clientKeyOf(line)), + ); + identity.remember(persisted); + rerender({ ...value, lines: persisted, isDirty: false }); + + expect(result.current.getRowProps(0)["data-dragging"]).toBe(""); + expect(result.current.getRowProps(1)["data-drop-position"]).toBe("after"); + act(() => result.current.getRowProps(1).onDrop(drop)); + expect(value.reorderLine).toHaveBeenCalledExactlyOnceWith("A", "B"); + expect(result.current.getRowProps(0)["data-dragging"]).toBeUndefined(); + expect(result.current.getRowProps(1)["data-drop-position"]).toBeUndefined(); +}); + +it("moves by arrow keys by default, retaining focus and dirty state without crossing boundaries", () => { + const { result, keys } = setup(); + const handle = mountedHandle(); + const up = keyEvent(handle, "ArrowUp"); + const down = keyEvent(handle, "ArrowDown"); + expect(result.current.reorder.getHandleProps(0).draggable).toBe(true); + act(() => result.current.reorder.getHandleProps(0).onKeyDown(up)); + expect(keys()).toEqual(["A", "B", "C"]); + expect(result.current.value.isDirty).toBe(false); + act(() => result.current.reorder.getHandleProps(0).onKeyDown(down)); + expect(keys()).toEqual(["B", "A", "C"]); + expect(document.activeElement).toBe(handle); + expect(result.current.value.isDirty).toBe(true); + act(() => result.current.reorder.getHandleProps(1).onKeyDown(down)); + act(() => result.current.reorder.getHandleProps(2).onKeyDown(down)); + expect(keys()).toEqual(["B", "C", "A"]); + expect(document.activeElement).toBe(handle); + const enter = keyEvent(handle, "Enter"); + act(() => result.current.reorder.getHandleProps(2).onKeyDown(enter)); + expect(enter.preventDefault).not.toHaveBeenCalled(); + act(() => result.current.value.revert()); + expect(result.current.value.isDirty).toBe(false); +}); + +it("ignores foreign drops and clears the guide on table leave or cancelled dragging", () => { + const first = setup(); + const second = setup(); + const handle = mountedHandle(); + const row = targetRow(); + const drop = dragEvent(row, 130); + act(() => first.result.current.reorder.getRowProps(2).onDrop(drop)); + expect(drop.preventDefault).not.toHaveBeenCalled(); + act(() => first.result.current.reorder.getHandleProps(0).onDragStart(dragEvent(handle))); + act(() => second.result.current.reorder.getRowProps(2).onDragOver(drop)); + act(() => second.result.current.reorder.getRowProps(2).onDrop(drop)); + expect(second.keys()).toEqual(["A", "B", "C"]); + expect(second.result.current.reorder.getRowProps(2)["data-drop-position"]).toBeUndefined(); + act(() => first.result.current.reorder.getRowProps(2).onDragOver(drop)); + const body = document.createElement("tbody"); + body.append(row); + act(() => first.result.current.reorder.bodyProps.onDragLeave(dragEvent(body, 0, row))); + expect(first.result.current.reorder.getRowProps(2)["data-drop-position"]).toBe("after"); + act(() => first.result.current.reorder.bodyProps.onDragLeave(dragEvent(body))); + expect(first.result.current.reorder.getRowProps(2)["data-drop-position"]).toBeUndefined(); + act(() => first.result.current.reorder.getHandleProps(0).onDragEnd()); + expect(first.result.current.reorder.getRowProps(0)["data-dragging"]).toBeUndefined(); + act(() => first.result.current.reorder.getRowProps(2).onDrop(drop)); + expect(first.keys()).toEqual(["A", "B", "C"]); +}); + +it("rejects disabled reordering and cancels an active drag across policy changes", () => { + const { result, rerender, keys } = setup(false); + const handle = mountedHandle(); + const start = dragEvent(handle); + const drop = dragEvent(targetRow(), 130); + expect(result.current.reorder.getHandleProps(0).draggable).toBe(false); + expect(result.current.reorder.getHandleProps(0)["aria-disabled"]).toBe(true); + act(() => result.current.reorder.getHandleProps(0).onDragStart(start)); + expect(start.preventDefault).toHaveBeenCalled(); + act(() => result.current.reorder.getHandleProps(0).onKeyDown(keyEvent(handle, "ArrowDown"))); + expect(keys()).toEqual(["A", "B", "C"]); + rerender({ orderer: true }); + act(() => result.current.reorder.getHandleProps(0).onDragStart(dragEvent(handle))); + act(() => result.current.reorder.getRowProps(2).onDragOver(drop)); + rerender({ orderer: false }); + rerender({ orderer: true }); + expect(result.current.reorder.getRowProps(0)["data-dragging"]).toBeUndefined(); + expect(result.current.reorder.getRowProps(2)["data-drop-position"]).toBeUndefined(); + act(() => result.current.reorder.getRowProps(2).onDrop(drop)); + expect(keys()).toEqual(["A", "B", "C"]); +}); + +it.each(["source row", "detached handle"])( + "does not revive a cancelled drag after restoring a %s", + (removed) => { + const { result, keys } = setup(); + const handle = mountedHandle(); + act(() => result.current.reorder.getHandleProps(0).onDragStart(dragEvent(handle))); + act(() => result.current.reorder.getRowProps(2).onDragOver(dragEvent(targetRow(), 130))); + if (removed === "source row") { + act(() => result.current.value.removeLine("A")); + } else { + handle.remove(); + act(() => result.current.value.updateField("B", "name", "Updated")); + document.body.append(handle); + } + act(() => result.current.value.revert()); + expect(result.current.reorder.getRowProps(0)["data-dragging"]).toBeUndefined(); + expect(result.current.reorder.getRowProps(2)["data-drop-position"]).toBeUndefined(); + act(() => result.current.reorder.getRowProps(2).onDrop(dragEvent(targetRow(), 130))); + expect(keys()).toEqual(["A", "B", "C"]); + expect(result.current.value.isDirty).toBe(false); + }, +); diff --git a/packages/core/src/components/line-items/use-line-items-reorder.ts b/packages/core/src/components/line-items/use-line-items-reorder.ts new file mode 100644 index 000000000..d98b8f42d --- /dev/null +++ b/packages/core/src/components/line-items/use-line-items-reorder.ts @@ -0,0 +1,117 @@ +import { useLayoutEffect, useRef, useState, type DragEvent, type KeyboardEvent } from "react"; +import type { UseLineItemsReturn } from "./types"; +import { clientKeyOf } from "./document/identity"; + +function isAfter(event: DragEvent) { + const rect = event.currentTarget.getBoundingClientRect(); + return event.clientY > rect.top + rect.height / 2; +} + +/** @internal Drag and keyboard reordering for the current line-items document. */ +export function useLineItemsReorder>( + value: UseLineItemsReturn, +) { + const { orderer, lines } = value; + const [drag, setDrag] = useState<{ clientKey: string; handle: HTMLButtonElement } | null>(null); + const [dropTarget, setDropTarget] = useState<{ clientKey: string; after: boolean } | null>(null); + const movedHandle = useRef(null); + const resetDrag = () => { + setDrag(null); + setDropTarget(null); + }; + useLayoutEffect(() => { + if ( + !orderer || + (drag && + (!drag.handle.isConnected || !lines.some((line) => clientKeyOf(line) === drag.clientKey))) + ) { + setDrag(null); + setDropTarget(null); + } + }, [orderer, lines, drag]); + useLayoutEffect(() => { + // Moving a keyed table row can blur its handle in the browser. + movedHandle.current?.focus({ preventScroll: true }); + movedHandle.current = null; + }, [value.lines]); + + const moveLine = (index: number, destination: number, handle: HTMLButtonElement) => { + if ( + !value.orderer || + index < 0 || + destination < 0 || + destination >= value.lines.length || + index === destination + ) + return; + const anchor = value.lines[destination > index ? destination : destination - 1]; + movedHandle.current = handle; + value.reorderLine( + value.getLineKey(value.lines[index]), + anchor ? value.getLineKey(anchor) : null, + ); + }; + const dropPosition = dropTarget?.after ? "after" : "before"; + + return { + bodyProps: { + onDragLeave: (event: DragEvent) => { + if (!event.currentTarget.contains(event.relatedTarget as Node | null)) setDropTarget(null); + }, + }, + getRowProps(index: number) { + const clientKey = clientKeyOf(value.lines[index]); + return { + "data-dragging": value.orderer && drag?.clientKey === clientKey ? "" : undefined, + "data-drop-position": + value.orderer && drag && dropTarget?.clientKey === clientKey ? dropPosition : undefined, + onDragOver: (event: DragEvent) => { + if (!value.orderer || !drag) return; + event.preventDefault(); + event.stopPropagation(); + event.dataTransfer.dropEffect = "move"; + const after = isAfter(event); + setDropTarget((previous) => + previous?.clientKey === clientKey && previous.after === after + ? previous + : { clientKey, after }, + ); + }, + onDrop: (event: DragEvent) => { + if (!value.orderer || !drag) return; + event.preventDefault(); + event.stopPropagation(); + const from = value.lines.findIndex((line) => clientKeyOf(line) === drag.clientKey); + const gap = index + (isAfter(event) ? 1 : 0); + moveLine(from, gap > from ? gap - 1 : gap, drag.handle); + resetDrag(); + }, + }; + }, + getHandleProps(index: number) { + const clientKey = clientKeyOf(value.lines[index]); + return { + "aria-disabled": !value.orderer || value.lines.length < 2, + draggable: value.orderer && value.lines.length > 1, + onDragStart: (event: DragEvent) => { + event.stopPropagation(); + if (!value.orderer || value.lines.length < 2) { + event.preventDefault(); + return; + } + event.dataTransfer.effectAllowed = "move"; + event.dataTransfer.setData("text/plain", ""); + setDropTarget(null); + setDrag({ clientKey, handle: event.currentTarget }); + }, + onDragEnd: resetDrag, + onKeyDown: (event: KeyboardEvent) => { + if (event.key === "ArrowUp" || event.key === "ArrowDown") { + event.preventDefault(); + moveLine(index, index + (event.key === "ArrowUp" ? -1 : 1), event.currentTarget); + } + }, + }; + }, + }; +} diff --git a/packages/core/src/components/line-items/use-line-items.test.tsx b/packages/core/src/components/line-items/use-line-items.test.tsx new file mode 100644 index 000000000..2f5f8c847 --- /dev/null +++ b/packages/core/src/components/line-items/use-line-items.test.tsx @@ -0,0 +1,250 @@ +import { StrictMode, Suspense, type ReactNode } from "react"; +import { afterEach, expect, it } from "vitest"; +import { act, cleanup, render, renderHook } from "@testing-library/react"; +import { useLineItems } from "./use-line-items"; +import type { LineItemsColumn } from "./document"; +import type { UseLineItemsOptions, UseLineItemsReturn } from "./types"; + +afterEach(cleanup); +type Row = { id?: string | number; name: string }; +const columns: LineItemsColumn[] = [{ accessorKey: "name", type: "text" }]; +function Wrapper({ children }: { children: ReactNode }) { + return {children}; +} + +it("owns a shallow-frozen initial snapshot with stable line keys", () => { + const input: Row[] = [{ id: 1, name: "Existing" }, { name: "New" }, { name: "New" }]; + const { result, rerender } = renderHook( + (props: UseLineItemsOptions) => useLineItems(props), + { initialProps: { columns, defaultLines: input }, wrapper: Wrapper }, + ); + const initial = result.current; + const keys = initial.lines.map(initial.getLineKey); + expect(keys[0]).toBe("1"); + expect(new Set(keys).size).toBe(3); + expect(Object.isFrozen(initial.lines)).toBe(true); + expect(initial.lines.every(Object.isFrozen)).toBe(true); + expect(initial.lines[0]).not.toBe(input[0]); + input[0].name = "Mutated input"; + rerender({ columns, defaultLines: [{ name: "Replacement" }] }); + expect(result.current.lines).toBe(initial.lines); + expect(result.current.lines[0].name).toBe("Existing"); + expect(result.current.lines.map(result.current.getLineKey)).toEqual(keys); + expect(() => result.current.getLineKey(input[0])).toThrow("does not belong"); +}); + +it("supports an alternative identity property", () => { + type Alternative = { code?: number; name: string }; + const { result } = renderHook(() => + useLineItems({ + columns: [{ accessorKey: "name" }], + defaultLines: [{ code: 42, name: "Line" }], + idKey: "code", + }), + ); + expect(result.current.getLineKey(result.current.lines[0])).toBe("42"); + act(() => result.current.addLine({ name: "New" })); + expect(result.current.lines[1].code).toBeUndefined(); + expect(result.current.getLineKey(result.current.lines[1])).toMatch(/^line:/); +}); + +it.each(["", Number.NaN, Number.POSITIVE_INFINITY, true, {}])( + "rejects an invalid persisted ID %s", + (id) => { + expect(() => + renderHook(() => useLineItems({ columns, defaultLines: [{ id, name: "Invalid" }] as Row[] })), + ).toThrow("Line IDs must be non-empty strings or finite numbers"); + }, +); + +it("rejects duplicate identities after string normalization", () => { + expect(() => + renderHook(() => + useLineItems({ + columns, + defaultLines: [ + { id: 1, name: "One" }, + { id: "1", name: "Another" }, + ], + }), + ), + ).toThrow("Line IDs must be unique"); +}); + +it("rejects duplicate and empty column identities", () => { + expect(() => renderHook(() => useLineItems({ columns: [columns[0], columns[0]] }))).toThrow( + "column IDs must be non-empty and unique", + ); + expect(() => + renderHook(() => useLineItems({ columns: [{ id: "", render: () => null }] })), + ).toThrow("column IDs must be non-empty and unique"); +}); + +it.each(["custom", "constructor", "__proto__", { toString: () => "text" }, Object("number")])( + "rejects unsupported editor %s instead of silently ignoring it", + (editorType) => { + const unsupported = [{ accessorKey: "name", edit: { editorType } }]; + expect(() => + renderHook(() => + useLineItems({ columns: unsupported } as unknown as UseLineItemsOptions), + ), + ).toThrow("Unsupported LineItems editor type"); + }, +); + +it.each([ + { options: undefined }, + { options: null }, + { options: {} }, + { options: () => [] }, + { options: [null] }, + { options: [{ value: 1, label: "One" }] }, + { options: [{ value: "one", label: 1 }] }, +])("rejects malformed combobox options $options", ({ options }) => { + const invalid = [ + { accessorKey: "name", edit: { editorType: "combobox", editorOptions: { options } } }, + ]; + expect(() => + renderHook(() => useLineItems({ columns: invalid } as unknown as UseLineItemsOptions)), + ).toThrow("Combobox editors require fixed string options"); +}); + +it("reflects sequential commands and dirty state under StrictMode", () => { + const { result } = renderHook( + () => useLineItems({ columns, defaultLines: [{ id: "A", name: "Existing" }] }), + { wrapper: Wrapper }, + ); + const commands = result.current; + expect(result.current.isDirty).toBe(false); + let key = ""; + act(() => { + commands.updateField("A", "name", "Changed"); + key = commands.addLine({ name: "Added" }); + commands.updateField(key, "name", "Updated creation"); + }); + expect(result.current.lines.map((row) => row.name)).toEqual(["Changed", "Updated creation"]); + expect(result.current.isDirty).toBe(true); + act(() => { + commands.removeLine(key); + commands.revert(); + }); + expect(result.current.lines.map((row) => row.name)).toEqual(["Existing"]); + expect(result.current.isDirty).toBe(false); +}); + +it("discards ID-less initial rows without accepting replacement defaultLines", () => { + const initialProps: UseLineItemsOptions = { columns, defaultLines: [{ name: "Unsaved" }] }; + const { result, rerender } = renderHook( + (options: UseLineItemsOptions) => useLineItems(options), + { initialProps, wrapper: Wrapper }, + ); + expect(result.current.isDirty).toBe(true); + act(() => result.current.revert()); + rerender({ columns, defaultLines: [{ id: "B", name: "Replacement" }] }); + expect(result.current.lines).toEqual([]); + expect(result.current.isDirty).toBe(false); +}); + +it("requires remounting to change idKey or document property ownership", () => { + const initialProps: UseLineItemsOptions = { + columns, + defaultLines: [{ id: "A", name: "Existing" }], + }; + const first = renderHook( + (options: UseLineItemsOptions) => useLineItems(options), + { initialProps }, + ); + expect(() => first.rerender({ columns, idKey: "code" })).toThrow( + "Remount LineItems to change idKey", + ); + const second = renderHook((options: UseLineItemsOptions) => useLineItems(options), { + initialProps: { columns }, + }); + expect(() => second.rerender({ columns: [] })).toThrow("change document property ownership"); +}); + +it("defaults to manual ordering and applies boolean changes to retained commands", () => { + const initialProps: UseLineItemsOptions = { + columns, + defaultLines: [ + { id: "A", name: "First" }, + { id: "B", name: "Second" }, + ], + }; + const { result, rerender } = renderHook( + (options: UseLineItemsOptions) => useLineItems(options), + { initialProps, wrapper: Wrapper }, + ); + const reorder = result.current.reorderLine; + expect(result.current.orderer).toBe(true); + act(() => reorder("A", "B")); + expect(result.current.lines.map(result.current.getLineKey)).toEqual(["B", "A"]); + expect(result.current.isDirty).toBe(true); + rerender({ ...initialProps, orderer: false }); + const moved = result.current.lines; + expect(result.current.orderer).toBe(false); + expect(() => reorder("A", null)).toThrow("Manual reordering is disabled"); + expect(result.current.lines).toBe(moved); + expect(result.current.isDirty).toBe(true); + act(() => { + result.current.updateField("B", "name", "Updated"); + const key = result.current.addLine({ name: "Added" }); + result.current.removeLine(key); + }); + expect(result.current.lines[0].name).toBe("Updated"); + act(() => result.current.revert()); + expect(result.current.lines.map(result.current.getLineKey)).toEqual(["A", "B"]); + expect(result.current.isDirty).toBe(false); + rerender({ ...initialProps, orderer: true }); + act(() => reorder("B", null)); + expect(result.current.lines.map(result.current.getLineKey)).toEqual(["B", "A"]); +}); + +it("does not adopt an orderer policy from a suspended render", () => { + const pending = new Promise(() => {}); + let value!: UseLineItemsReturn; + function Owner({ orderer, suspend }: { orderer: boolean; suspend: boolean }) { + value = useLineItems({ + columns, + defaultLines: [ + { id: "A", name: "First" }, + { id: "B", name: "Second" }, + ], + orderer, + }); + if (suspend) throw pending; + return null; + } + const { rerender } = render( + + + , + ); + const reorder = value.reorderLine; + rerender( + + + , + ); + act(() => reorder("B", null)); + rerender( + + + , + ); + expect(value.lines.map(value.getLineKey)).toEqual(["B", "A"]); + expect(() => reorder("A", null)).toThrow("Manual reordering is disabled"); +}); + +it("rejects non-boolean orderer configuration", () => { + const options: UseLineItemsOptions = { columns }; + Object.assign(options, { orderer: "manual" }); + expect(() => renderHook(() => useLineItems(options))).toThrow("orderer must be a boolean"); +}); + +it("rejects controlled rows instead of silently ignoring them", () => { + const options = { columns, lines: [] }; + expect(() => renderHook(() => useLineItems(options))).toThrow( + "use defaultLines, not controlled lines", + ); +}); diff --git a/packages/core/src/components/line-items/use-line-items.ts b/packages/core/src/components/line-items/use-line-items.ts new file mode 100644 index 000000000..142f6dd4e --- /dev/null +++ b/packages/core/src/components/line-items/use-line-items.ts @@ -0,0 +1,56 @@ +import { useCallback, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react"; +import { createLineItemsDocumentStore } from "./document/store"; +import { createLineItemsEditing, LINE_ITEMS_EDITING } from "./editing"; +import type { UseLineItemsOptions, UseLineItemsReturn } from "./types"; + +/** Owns one document; changing the document identity requires remounting the hook's owner. */ +export function useLineItems>( + options: UseLineItemsOptions, +): UseLineItemsReturn { + if ("lines" in options || "onLinesChange" in options) + throw new Error("useLineItems owns its rows; use defaultLines, not controlled lines"); + if (options.orderer !== undefined && typeof options.orderer !== "boolean") + throw new Error("LineItems orderer must be a boolean"); + const orderer = options.orderer ?? true; + const committedOrderer = useRef(orderer); + const [store] = useState(() => + createLineItemsDocumentStore({ ...options, lines: options.defaultLines }), + ); + const [editing] = useState(() => createLineItemsEditing(store, options.columns)); + if ((options.idKey ?? "id") !== store.idKey) throw new Error("Remount LineItems to change idKey"); + // Validate without changing configuration or drafts from an abandoned render. + editing.assertColumns(options.columns); + const lines = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot); + // Retained commands must not observe a movement policy from an abandoned render. + useLayoutEffect(() => { + committedOrderer.current = orderer; + }, [orderer]); + useLayoutEffect(() => { + editing.activate(); + return editing.deactivate; + }, [editing]); + // Stable permission predicates may read external state; check each committed render. + useLayoutEffect(() => { + editing.reconcileColumns(options.columns); + }); + const reorderLine = useCallback( + (lineKey: string, afterLineKey: string | null) => { + if (!committedOrderer.current) throw new Error("Manual reordering is disabled"); + store.reorderLine(lineKey, afterLineKey); + }, + [store], + ); + return { + [LINE_ITEMS_EDITING]: editing, + columns: options.columns, + lines, + orderer, + isDirty: store.isDirty(), + getLineKey: store.getLineKey, + updateField: editing.updateField, + addLine: store.addLine, + removeLine: editing.removeLine, + reorderLine, + revert: editing.revert, + }; +} diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index fa3476839..a3c1c2706 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -219,6 +219,15 @@ export { Input, type InputProps } from "./components/input"; export { Textarea, type TextareaProps } from "./components/textarea"; export { Checkbox, type CheckboxProps } from "./components/checkbox"; export { Table } from "./components/table"; +export { + LineItems, + useLineItems, + type LineItemsRootProps, + type LineItemsTableProps, + type UseLineItemsOptions, + type UseLineItemsReturn, +} from "./components/line-items"; +export type { LineItemsColumn } from "./components/line-items/document"; export { Card } from "./components/card"; export { Dialog } from "./components/dialog"; export { Field } from "./components/field"; @@ -352,8 +361,8 @@ export { type NumberCellEditOptions, type BadgeCellEditOptions, type DateCellEditOptions, - type CellEditState, type DateTimeDraft, + type CellEditState, } from "./components/data-table"; export { useCollectionVariables } from "./hooks/use-collection-variables"; export { useURLCollectionVariables, withURLCollectionState } from "./lib/collection-url-state"; diff --git a/packages/core/tests/browser/line-items-icon-spacing.test.tsx b/packages/core/tests/browser/line-items-icon-spacing.test.tsx new file mode 100644 index 000000000..c6df36f0e --- /dev/null +++ b/packages/core/tests/browser/line-items-icon-spacing.test.tsx @@ -0,0 +1,129 @@ +import { render, screen, within } from "@testing-library/react"; +import { + LineItems, + SidebarLayout, + defineModule, + useLineItems, + type LineItemsColumn, +} from "@tailor-platform/app-shell"; +import { AppShell } from "@tailor-platform/app-shell/testing"; +import { describe, expect, it } from "vitest"; + +type Line = { id?: string; value: string | null; allowed: boolean }; +type Kind = "combobox" | "date"; +type Align = "left" | "center" | "right"; +const longLabel = "A deliberately long closing-day description that does not fit in the cell"; + +function SpacingTable({ + kind, + align, + clipped = false, +}: { + kind: Kind; + align: Align; + clipped?: boolean; +}) { + const column: LineItemsColumn = { + accessorKey: "value", + label: "Value", + type: kind === "date" ? "date" : "text", + align, + render: clipped + ? () => {longLabel} + : undefined, + edit: + kind === "date" + ? { editorType: "date", canEdit: (row) => row.allowed } + : { + editorType: "combobox", + canEdit: (row) => row.allowed, + editorOptions: { options: [{ value: "2026-12-01", label: "Closing day" }] }, + }, + }; + const value = useLineItems({ + columns: [column], + defaultLines: [ + { id: "A", value: "2026-12-01", allowed: true }, + { id: "B", value: "2026-12-01", allowed: false }, + ], + orderer: false, + }); + return ( +
+ + + +
+ ); +} + +const cases = (["combobox", "date"] as const).flatMap((kind) => + (["left", "center", "right"] as const).map((align) => ({ kind, align })), +); + +describe("LineItems mixed-permission value geometry", () => { + it.each(cases)( + "aligns $kind values and clipping bounds with $align alignment", + async ({ kind, align }) => { + render( + ( + <> + + + + ), + resources: [], + }), + ]} + > + + , + ); + const aligned = await screen.findByRole("table", { name: "Aligned" }); + const clipped = screen.getByRole("table", { name: "Clipped" }); + for (const table of [aligned, clipped]) { + const [editable, readonly] = within(table).getAllByRole("cell"); + const editablePreview = editable.firstElementChild as HTMLElement; + const readonlyPreview = readonly.firstElementChild as HTMLElement; + expect(getComputedStyle(editablePreview).paddingRight).toBe("20px"); + expect(getComputedStyle(readonlyPreview).paddingRight).toBe("20px"); + expect(getComputedStyle(readonly).textAlign).toBe(align); + expect(readonly.querySelector("input, button, svg")).toBeNull(); + const previews = [editablePreview, readonlyPreview]; + const textBounds = previews.map((preview) => { + const range = document.createRange(); + range.selectNodeContents(preview); + return range.getBoundingClientRect(); + }); + expect(textBounds[0].left).toBeCloseTo(textBounds[1].left, 1); + expect(textBounds[0].right).toBeCloseTo(textBounds[1].right, 1); + if (table === clipped) { + const [editableClip, readonlyClip] = previews.map( + (preview) => preview.firstElementChild as HTMLElement, + ); + expect(editableClip.scrollWidth).toBeGreaterThan(editableClip.clientWidth); + expect(readonlyClip.scrollWidth).toBeGreaterThan(readonlyClip.clientWidth); + expect(editableClip.getBoundingClientRect().left).toBeCloseTo( + readonlyClip.getBoundingClientRect().left, + 1, + ); + expect(editableClip.getBoundingClientRect().right).toBeCloseTo( + readonlyClip.getBoundingClientRect().right, + 1, + ); + } + } + }, + ); +}); diff --git a/packages/core/tests/browser/line-items.test.tsx b/packages/core/tests/browser/line-items.test.tsx new file mode 100644 index 000000000..42a4605bd --- /dev/null +++ b/packages/core/tests/browser/line-items.test.tsx @@ -0,0 +1,189 @@ +import { render, screen, waitFor } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import { XIcon } from "lucide-react"; +import { + Button, + DataTable, + LineItems, + SidebarLayout, + defineModule, + useDataTable, + useLineItems, + type LineItemsColumn, +} from "@tailor-platform/app-shell"; +import { AppShell } from "@tailor-platform/app-shell/testing"; +import { describe, expect, it } from "vitest"; + +type Line = { id?: string; item: string | null }; +const items = ["Notebook", "Pen", "Pencil", "Eraser", "Ruler"]; +function Page({ + editable, + align, + normalButtons = false, +}: { + editable: boolean; + align: "left" | "center" | "right"; + normalButtons?: boolean; +}) { + const renderItem = normalButtons + ? (line: { item: string | null }) => ( + + ) + : undefined; + const table = useDataTable<{ id: string; item: string }>({ + columns: [ + { + id: "item", + label: "Item", + type: "text", + render: renderItem, + align: align === "right" ? "right" : "left", + }, + ], + data: { rows: items.map((item, index) => ({ id: String(index), item })) }, + }); + const lineItems = useLineItems({ + orderer: editable, + defaultLines: items.map((item, index) => ({ id: String(index), item })), + columns: [ + { + accessorKey: "item", + label: "Item", + render: renderItem, + align: normalButtons ? align : undefined, + edit: editable ? { editorType: "text" } : undefined, + }, + ...(editable + ? [ + { + id: "operations", + label: "Actions", + width: 64, + align, + headerProps: () => ({ className: "text-center! first:pl-2! last:pr-2!" }), + cellProps: () => ({ className: "py-1! first:pl-2! last:pr-2!" }), + render: (line) => ( + + ), + } satisfies LineItemsColumn, + ] + : []), + ], + }); + return ( + <> +
+ + + +
+ + + + + ); +} + +const lineItemsRows = () => [ + ...document.querySelectorAll('[data-slot="line-items-table"] tbody tr'), +]; + +describe("LineItems compact action cells", () => { + it.each([ + { editable: true, align: "left", normalButtons: false }, + { editable: true, align: "center", normalButtons: false }, + { editable: true, align: "right", normalButtons: false }, + { editable: false, align: "left", normalButtons: false }, + { editable: false, align: "left", normalButtons: true }, + { editable: false, align: "right", normalButtons: true }, + ] as const)( + "matches DataTable rows (editable: $editable, align: $align, normal buttons: $normalButtons)", + async ({ editable, align, normalButtons }) => { + const user = userEvent.setup(); + render( + ( + + ), + resources: [], + }), + ]} + > + + , + ); + await screen.findByRole("table", { name: "Order lines" }); + const referenceRows = screen.getByTestId("reference-table").querySelectorAll("tbody tr"); + expect(lineItemsRows()).toHaveLength(referenceRows.length); + lineItemsRows().forEach((row, index) => { + expect(row.getBoundingClientRect().height).toBeCloseTo( + referenceRows[index].getBoundingClientRect().height, + 1, + ); + }); + if (!editable) { + expect(screen.queryByRole("button", { name: "Delete Notebook" })).toBeNull(); + const cell = lineItemsRows()[0].querySelector("td")!; + expect(getComputedStyle(cell).paddingTop).toBe("8px"); + expect(getComputedStyle(cell).paddingBottom).toBe("8px"); + if (normalButtons) expect(getComputedStyle(cell).textAlign).toBe(align); + return; + } + const remove = screen.getByRole("button", { name: "Delete Notebook" }); + const bounds = remove.getBoundingClientRect(); + expect(bounds.width).toBe(28); + expect(bounds.height).toBe(28); + const header = document.querySelector( + '[data-slot="line-items-table"] th[data-col-key="operations"]', + )!; + const headerStyle = getComputedStyle(header); + expect(headerStyle.textAlign).toBe("center"); + expect(headerStyle.paddingLeft).toBe("8px"); + expect(headerStyle.paddingRight).toBe("8px"); + const headerBounds = header.getBoundingClientRect(); + const cell = remove.closest("td")!; + const cellStyle = getComputedStyle(cell); + const cellBounds = cell.getBoundingClientRect(); + expect(cellStyle.textAlign).toBe(align); + expect(cellStyle.paddingLeft).toBe("8px"); + expect(cellStyle.paddingRight).toBe("8px"); + if (align === "center") { + expect(headerBounds.left + headerBounds.width / 2).toBeCloseTo( + bounds.left + bounds.width / 2, + 1, + ); + } else if (align === "left") { + expect(bounds.left).toBeCloseTo(cellBounds.left + parseFloat(cellStyle.paddingLeft), 1); + } else { + expect(bounds.right).toBeCloseTo(cellBounds.right - parseFloat(cellStyle.paddingRight), 1); + } + expect(cellStyle.paddingTop).toBe("4px"); + expect(cellStyle.paddingBottom).toBe("4px"); + remove.focus(); + await user.keyboard("{ArrowLeft}"); + expect(document.activeElement).toBe(remove); + expect(getComputedStyle(remove).boxShadow).not.toBe("none"); + await user.click(remove); + await waitFor(() => expect(lineItemsRows()).toHaveLength(4)); + expect(screen.queryByRole("button", { name: "Delete Notebook" })).toBeNull(); + }, + ); +});