@classytic/fluid 0.3.6 → 0.4.1

package/dist/client/spreadsheet.d.mts

@@ -0,0 +1,207 @@
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import * as react from "react";
+import { ComponentType, ReactNode } from "react";
+
+//#region src/components/spreadsheet/types.d.ts
+interface SpreadsheetColumn<TData = unknown> {
+  /** Unique column identifier — also used as the field key unless `field` is set */
+  id: string;
+  /** Optional field key on the data object (defaults to `id`) */
+  field?: string;
+  /** Column header label */
+  header: string | ReactNode;
+  /** CSS width: '20%', '120px', 'minmax(100px, 1fr)', etc. */
+  width: string;
+  /** Text alignment */
+  align?: "left" | "right" | "center";
+  /** Component that renders the cell content */
+  cell: ComponentType<CellRenderProps<TData>>;
+  /** Label shown above the field in mobile card layout */
+  mobileLabel?: string;
+  /** grid-cols-12 span for mobile card layout (default 12 = full width) */
+  mobileSpan?: number;
+  /** Hide column conditionally (e.g., hide actions when read-only) */
+  hiddenWhen?: (ctx: {
+    isReadOnly: boolean;
+  }) => boolean;
+  /** Data type hint for clipboard paste coercion. "number" coerces pasted strings to numbers. */
+  dataType?: "string" | "number";
+}
+interface CellRenderProps<TData = unknown> {
+  /** Current field value */
+  value: unknown;
+  /** Full row data object */
+  row: TData;
+  /** Stable row ID (UUID) */
+  rowId: string;
+  /** Visual row index (0-based, accounts for filtering) */
+  rowIndex: number;
+  /** Column definition */
+  column: SpreadsheetColumn<TData>;
+  /**
+   * Commit a value change.
+   * - Single field: `onChange("debit", 100)`
+   * - Multi-field batch: `onChange({ debit: 100, credit: 0 })`
+   */
+  onChange: (fieldOrPatch: string | Record<string, unknown>, value?: unknown) => void;
+  /** Whether the spreadsheet is in read-only mode */
+  isReadOnly: boolean;
+  /** Data attributes for keyboard navigation */
+  cellRef?: string;
+}
+interface SpreadsheetTableProps<TData = unknown> {
+  /** Column definitions */
+  columns: SpreadsheetColumn<TData>[];
+  /** Items state from useSpreadsheetStore */
+  items: Map<string, TData>;
+  /** Ordered row IDs (can be pre-filtered for search) */
+  orderedIds: string[];
+  /** Dispatch function from useSpreadsheetStore */
+  dispatch: (action: SpreadsheetAction<TData>) => void;
+  /** Read-only mode (e.g., posted journal entries) */
+  isReadOnly?: boolean;
+  /** Enable row virtualization (recommended when > 30 rows) */
+  virtualize?: boolean;
+  /** Estimated row height for virtualization (default: 48) */
+  estimateRowHeight?: number;
+  /** Render a footer row (e.g., totals) — used inside <tfoot> on desktop */
+  footer?: ReactNode;
+  /** Separate footer for mobile card layout (avoids <tr> inside <div>) */
+  mobileFooter?: ReactNode;
+  /** Render row action buttons (add/remove) */
+  rowActions?: (props: {
+    rowId: string;
+    rowIndex: number;
+    isReadOnly: boolean;
+  }) => ReactNode;
+  /** CSS class for the table container */
+  className?: string;
+  /** Accessible label for the table */
+  ariaLabel?: string;
+  /** Called when a row is added (receives the ID of the row to insert after) */
+  onAddRow?: (afterRowId: string) => void;
+  /** Called when a row is removed */
+  onRemoveRow?: (rowId: string) => void;
+}
+interface SpreadsheetState<TData> {
+  items: Map<string, TData>;
+  orderedIds: string[];
+}
+type SpreadsheetAction<TData = unknown> = {
+  type: "SET_ALL";
+  items: TData[];
+  getId?: (item: TData) => string;
+} | {
+  type: "UPDATE_CELL";
+  rowId: string;
+  field: string;
+  value: unknown;
+} | {
+  type: "UPDATE_ROW";
+  rowId: string;
+  patch: Partial<TData>;
+} | {
+  type: "ADD_ROW";
+  afterRowId: string;
+  item: TData;
+  newId?: string;
+} | {
+  type: "REMOVE_ROW";
+  rowId: string;
+} | {
+  type: "BATCH";
+  actions: SpreadsheetAction<TData>[];
+};
+//#endregion
+//#region src/components/spreadsheet/spreadsheet-table.d.ts
+declare function SpreadsheetTable<TData = unknown>({
+  columns,
+  items,
+  orderedIds,
+  dispatch,
+  isReadOnly,
+  footer,
+  mobileFooter,
+  rowActions,
+  className,
+  ariaLabel,
+  onAddRow,
+  virtualize,
+  estimateRowHeight
+}: SpreadsheetTableProps<TData>): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/components/spreadsheet/spreadsheet-row.d.ts
+interface SpreadsheetRowProps<TData = unknown> {
+  rowId: string;
+  rowIndex: number;
+  item: TData;
+  visibleColumns: SpreadsheetColumn<TData>[];
+  dispatch: (action: SpreadsheetAction<TData>) => void;
+  isReadOnly: boolean;
+  rowActions?: (props: {
+    rowId: string;
+    rowIndex: number;
+    isReadOnly: boolean;
+  }) => ReactNode;
+  onCellKeyDown?: (e: React.KeyboardEvent, rowId: string, colId: string) => void;
+  cellAttr?: string;
+  isMobile?: boolean;
+  style?: React.CSSProperties;
+  /** Ref callback from virtualizer for dynamic row measurement */
+  measureRef?: (node: HTMLElement | null) => void;
+}
+declare function SpreadsheetRowInner<TData>({
+  rowId,
+  rowIndex,
+  item,
+  visibleColumns,
+  dispatch,
+  isReadOnly,
+  rowActions,
+  onCellKeyDown,
+  cellAttr,
+  isMobile,
+  style,
+  measureRef
+}: SpreadsheetRowProps<TData>): react_jsx_runtime0.JSX.Element;
+declare const SpreadsheetRow: typeof SpreadsheetRowInner;
+//#endregion
+//#region src/components/spreadsheet/use-spreadsheet-store.d.ts
+declare function useSpreadsheetStore<TData>(initialItems?: TData[], getId?: (item: TData) => string): {
+  items: Map<string, TData>;
+  orderedIds: string[];
+  dispatch: react.ActionDispatch<[action: SpreadsheetAction<TData>]>;
+  getOrderedItems: () => TData[];
+  rowCount: number;
+};
+type SpreadsheetStore<TData> = ReturnType<typeof useSpreadsheetStore<TData>>;
+//#endregion
+//#region src/components/spreadsheet/use-spreadsheet-keyboard.d.ts
+interface UseSpreadsheetKeyboardOptions {
+  /** Ordered row IDs (visible/filtered) */
+  orderedIds: string[];
+  /** Column IDs in display order */
+  columnIds: string[];
+  /** Ref to the table container element */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Add a row when navigating past the end */
+  onAddRow?: (afterRowId: string) => void;
+}
+/**
+ * Keyboard navigation for spreadsheet cells.
+ *
+ * Tab → next cell → wrap to next row
+ * Shift+Tab → previous cell → wrap to previous row
+ * Enter → commit + move down (same column, next row)
+ */
+declare function useSpreadsheetKeyboard({
+  orderedIds,
+  columnIds,
+  containerRef,
+  onAddRow
+}: UseSpreadsheetKeyboardOptions): {
+  handleCellKeyDown: (e: React.KeyboardEvent, rowId: string, colId: string) => void;
+  CELL_ATTR: string;
+};
+//#endregion
+export { type CellRenderProps, type SpreadsheetAction, type SpreadsheetColumn, SpreadsheetRow, type SpreadsheetState, type SpreadsheetStore, SpreadsheetTable, type SpreadsheetTableProps, useSpreadsheetKeyboard, useSpreadsheetStore };