@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/data-grid/core/rows.ts

@@ -0,0 +1,64 @@
+import type { GridOptions, GridRow, PaginationState, RowId } from "./types";
+
+export type RowIdGetter<T> = (row: T, index: number) => RowId;
+
+export function createRowIdGetter<T>(
+  getRowId: GridOptions<T>["getRowId"],
+): RowIdGetter<T> {
+  if (typeof getRowId === "function") {
+    return (row, index) => String(getRowId(row, index));
+  }
+  if (typeof getRowId === "string") {
+    return (row) => String(row[getRowId]);
+  }
+  return (row, index) => {
+    const id = (row as { id?: unknown } | null)?.id;
+    return id === null || id === undefined ? String(index) : String(id);
+  };
+}
+
+export function buildRows<T>(
+  data: readonly T[],
+  getRowId: RowIdGetter<T>,
+): GridRow<T>[] {
+  return data.map((original, index) => ({
+    id: getRowId(original, index),
+    index,
+    original,
+  }));
+}
+
+export interface PageResult<T> {
+  rows: GridRow<T>[];
+  pageIndex: number;
+  pageCount: number;
+  /** Total rows across all pages. */
+  rowCount: number;
+  /** Absolute index of the first row on the page. */
+  pageOffset: number;
+}
+
+export function paginate<T>(
+  rows: GridRow<T>[],
+  pagination: PaginationState,
+  options: { enabled: boolean; server: boolean; rowCount?: number },
+): PageResult<T> {
+  const total = options.server ? (options.rowCount ?? rows.length) : rows.length;
+
+  if (!options.enabled) {
+    return { rows, pageIndex: 0, pageCount: 1, rowCount: total, pageOffset: 0 };
+  }
+
+  const pageSize = Math.max(1, pagination.pageSize);
+  const pageCount = Math.max(1, Math.ceil(total / pageSize));
+  const pageIndex = Math.min(Math.max(0, pagination.pageIndex), pageCount - 1);
+  const pageOffset = pageIndex * pageSize;
+
+  return {
+    rows: options.server ? rows : rows.slice(pageOffset, pageOffset + pageSize),
+    pageIndex,
+    pageCount,
+    rowCount: total,
+    pageOffset,
+  };
+}

package/source/components/data-grid/core/sorting.ts

@@ -0,0 +1,133 @@
+import type { GridRow, ResolvedColumn, SortItem } from "./types";
+import { toTime } from "./values";
+
+/**
+ * One collator per locale. `undefined` means the runtime's own locale, which is
+ * what the grid used everywhere before it took a `locale` prop; passing the
+ * prop through keeps the order of the rows and the formatting of their values
+ * speaking the same language.
+ */
+const collators = new Map<string, Intl.Collator>();
+
+function collatorFor(locale?: string): Intl.Collator {
+  const key = locale ?? "";
+  let found = collators.get(key);
+  if (!found) {
+    found = new Intl.Collator(locale, { numeric: true, sensitivity: "base" });
+    collators.set(key, found);
+  }
+  return found;
+}
+
+type SortKey = number | null;
+
+/**
+ * Converts a column's values into numbers once, so the sort itself only does
+ * numeric comparisons. Strings become their collation rank.
+ */
+function buildKeys<T>(
+  rows: GridRow<T>[],
+  column: ResolvedColumn<T>,
+  locale?: string,
+): SortKey[] {
+  const values = rows.map((row) => column.getValue(row.original));
+
+  switch (column.type) {
+    case "number":
+      return values.map((v) => {
+        if (v === null || v === undefined || v === "") return null;
+        const n = Number(v);
+        return Number.isNaN(n) ? null : n;
+      });
+    case "date":
+      return values.map(toTime);
+    case "boolean":
+      return values.map((v) => (v === null || v === undefined ? null : v ? 1 : 0));
+    default: {
+      const { options } = column.def;
+      const labels = options && new Map(options.map((o) => [o.value, o.label]));
+      const strings = values.map((v) =>
+        v === null || v === undefined || v === ""
+          ? null
+          : String(labels?.get(v as string | number) ?? v),
+      );
+      const collator = collatorFor(locale);
+      const unique = Array.from(new Set(strings.filter((s) => s !== null)));
+      unique.sort(collator.compare);
+      const rank = new Map<string, number>();
+      let current = 0;
+      unique.forEach((s, i) => {
+        if (i > 0 && collator.compare(unique[i - 1], s) !== 0) current = i;
+        rank.set(s, current);
+      });
+      return strings.map((s) => (s === null ? null : rank.get(s)!));
+    }
+  }
+}
+
+/** Stable multi-column sort. Empty values always sort last. */
+export function sortRows<T>(
+  rows: GridRow<T>[],
+  columns: readonly ResolvedColumn<T>[],
+  sorting: readonly SortItem[],
+  locale?: string,
+): GridRow<T>[] {
+  const byId = new Map(columns.map((c) => [c.id, c]));
+  const active = sorting
+    .map((item) => ({ column: byId.get(item.columnId), desc: item.desc }))
+    .filter(
+      (item): item is { column: ResolvedColumn<T>; desc: boolean } =>
+        item.column !== undefined && item.column.hasValue,
+    );
+
+  if (active.length === 0 || rows.length < 2) return rows;
+
+  const comparators = active.map(({ column, desc }) => {
+    const direction = desc ? -1 : 1;
+    const { sortFn } = column.def;
+    if (sortFn) {
+      const values = rows.map((row) => column.getValue(row.original));
+      return (i: number, j: number) =>
+        direction * sortFn(values[i], values[j], rows[i].original, rows[j].original);
+    }
+    const keys = buildKeys(rows, column, locale);
+    return (i: number, j: number) => {
+      const a = keys[i];
+      const b = keys[j];
+      if (a === b) return 0;
+      if (a === null) return 1;
+      if (b === null) return -1;
+      return a < b ? -direction : direction;
+    };
+  });
+
+  const indices = rows.map((_, i) => i);
+  indices.sort((i, j) => {
+    for (const compare of comparators) {
+      const result = compare(i, j);
+      if (result !== 0) return result;
+    }
+    return i - j;
+  });
+  return indices.map((i) => rows[i]);
+}
+
+/** Click cycles asc → desc → off. With `multi`, other sorts are kept. */
+export function toggleSorting(
+  sorting: readonly SortItem[],
+  columnId: string,
+  multi: boolean,
+): SortItem[] {
+  const existing = sorting.find((s) => s.columnId === columnId);
+  const next: SortItem | null = !existing
+    ? { columnId, desc: false }
+    : !existing.desc
+      ? { columnId, desc: true }
+      : null;
+
+  if (!multi) return next ? [next] : [];
+  if (!existing) return [...sorting, next!];
+  return next
+    ? sorting.map((s) => (s.columnId === columnId ? next : s))
+    : sorting.filter((s) => s.columnId !== columnId);
+}

package/source/components/data-grid/core/state.ts

@@ -0,0 +1,82 @@
+import { getColumnId } from "./columns";
+import type { GridOptions, GridQuery, GridState } from "./types";
+
+export const DEFAULT_PAGE_SIZE = 50;
+
+export const STATE_KEYS = [
+  "sorting",
+  "filters",
+  "globalFilter",
+  "pagination",
+  "rowSelection",
+  "columnOrder",
+  "columnVisibility",
+  "columnSizing",
+  "columnPinning",
+  "density",
+] as const satisfies readonly (keyof GridState)[];
+
+const QUERY_KEYS = ["sorting", "filters", "globalFilter", "pagination"] as const;
+
+/** Initial state, seeded from `initialState` and column-level `pin` / `hidden`. */
+export function createInitialState<T>(options: GridOptions<T>): GridState {
+  const init = options.initialState ?? {};
+  const left: string[] = [];
+  const right: string[] = [];
+  const visibility: Record<string, boolean> = {};
+
+  for (const def of options.columns) {
+    const id = getColumnId(def);
+    if (def.pin === "left") left.push(id);
+    if (def.pin === "right") right.push(id);
+    if (def.hidden) visibility[id] = false;
+  }
+
+  return {
+    sorting: init.sorting ?? [],
+    filters: init.filters ?? [],
+    globalFilter: init.globalFilter ?? "",
+    pagination: { pageIndex: 0, pageSize: DEFAULT_PAGE_SIZE, ...init.pagination },
+    rowSelection: init.rowSelection ?? {},
+    columnOrder: init.columnOrder ?? [],
+    columnVisibility: init.columnVisibility ?? visibility,
+    columnSizing: init.columnSizing ?? {},
+    columnPinning: init.columnPinning ?? { left, right },
+    density: init.density ?? "standard",
+  };
+}
+
+/** Controlled keys (not undefined) win over internal state. */
+export function mergeState(
+  internal: GridState,
+  controlled: Partial<GridState> | undefined,
+): GridState {
+  if (!controlled) return internal;
+  let merged: GridState | null = null;
+  for (const key of STATE_KEYS) {
+    const value = controlled[key];
+    if (value !== undefined && value !== internal[key]) {
+      merged ??= { ...internal };
+      (merged as unknown as Record<string, unknown>)[key] = value;
+    }
+  }
+  return merged ?? internal;
+}
+
+export function pickQuery(state: GridState): GridQuery {
+  return {
+    sorting: state.sorting,
+    filters: state.filters,
+    globalFilter: state.globalFilter,
+    pagination: state.pagination,
+  };
+}
+
+export function queryChanged(a: GridState, b: GridState): boolean {
+  return QUERY_KEYS.some((key) => a[key] !== b[key]);
+}
+
+/** Filters, search and sort changes move the grid back to the first page. */
+export function resetsPage(a: GridState, b: GridState): boolean {
+  return a.filters !== b.filters || a.globalFilter !== b.globalFilter || a.sorting !== b.sorting;
+}

package/source/components/data-grid/core/store.ts

@@ -0,0 +1,52 @@
+export interface ReadableStore<S> {
+  getSnapshot(): S;
+  subscribe(listener: () => void): () => void;
+}
+
+export interface Store<S> extends ReadableStore<S> {
+  setState(updater: (prev: S) => S): void;
+  notify(): void;
+}
+
+/** Minimal external store for `useSyncExternalStore`. */
+export function createStore<S>(initial: S): Store<S> {
+  let state = initial;
+  const listeners = new Set<() => void>();
+
+  const notify = () => {
+    for (const listener of listeners) listener();
+  };
+
+  return {
+    getSnapshot: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    setState(updater) {
+      const next = updater(state);
+      if (Object.is(next, state)) return;
+      state = next;
+      notify();
+    },
+    notify,
+  };
+}
+
+export function shallowEqual<T>(a: T, b: T): boolean {
+  if (Object.is(a, b)) return true;
+  if (
+    typeof a !== "object" ||
+    typeof b !== "object" ||
+    a === null ||
+    b === null
+  ) {
+    return false;
+  }
+  const keysA = Object.keys(a) as (keyof T)[];
+  if (keysA.length !== Object.keys(b).length) return false;
+  for (const key of keysA) {
+    if (!Object.is(a[key], b[key])) return false;
+  }
+  return true;
+}

package/source/components/data-grid/core/types.ts

@@ -0,0 +1,302 @@
+import type { MouseEvent, ReactNode } from "react";
+
+export type RowId = string;
+
+export type ColumnType = "string" | "number" | "date" | "boolean";
+
+export type Density = "compact" | "standard" | "comfortable";
+
+export type PinSide = "left" | "right";
+
+export interface SortItem {
+  columnId: string;
+  desc: boolean;
+}
+
+export type FilterOperator =
+  | "contains"
+  | "notContains"
+  | "equals"
+  | "notEquals"
+  | "startsWith"
+  | "endsWith"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "between"
+  | "before"
+  | "after"
+  | "in"
+  | "isEmpty"
+  | "isNotEmpty";
+
+export type FilterValue =
+  | string
+  | number
+  | boolean
+  | ReadonlyArray<string | number>
+  | null;
+
+export interface ColumnFilter {
+  columnId: string;
+  operator: FilterOperator;
+  value?: FilterValue;
+  /** Upper bound for the `between` operator. */
+  value2?: FilterValue;
+}
+
+export interface PaginationState {
+  pageIndex: number;
+  pageSize: number;
+}
+
+export interface ColumnPinningState {
+  left: string[];
+  right: string[];
+}
+
+/** Every piece of grid state that can be controlled from the outside. */
+export interface GridState {
+  sorting: SortItem[];
+  filters: ColumnFilter[];
+  globalFilter: string;
+  pagination: PaginationState;
+  rowSelection: Record<RowId, boolean>;
+  columnOrder: string[];
+  columnVisibility: Record<string, boolean>;
+  columnSizing: Record<string, number>;
+  columnPinning: ColumnPinningState;
+  density: Density;
+}
+
+/** The subset of state a server needs to produce a page of rows. */
+export interface GridQuery {
+  sorting: SortItem[];
+  filters: ColumnFilter[];
+  globalFilter: string;
+  pagination: PaginationState;
+}
+
+export interface GridRow<T> {
+  id: RowId;
+  /** Position in the original `data` array. */
+  index: number;
+  original: T;
+}
+
+export interface CellContext<T, V = unknown> {
+  row: T;
+  rowId: RowId;
+  /** Index within the rows currently displayed (the page). */
+  rowIndex: number;
+  value: V;
+  column: ResolvedColumn<T>;
+}
+
+export interface EditorProps<T, V = unknown> {
+  value: V;
+  row: T;
+  column: ResolvedColumn<T>;
+  error: string | null;
+  onChange(value: V): void;
+  /** Commits the current draft, or `value` when given. */
+  commit(value?: V): void;
+  cancel(): void;
+}
+
+export type BuiltInEditor = "text" | "number" | "date" | "select" | "checkbox";
+
+export interface ColumnOption {
+  label: string;
+  value: string | number;
+}
+
+export type ExportCellValue = string | number | boolean | Date | null | undefined;
+
+/**
+ * Column definition. Callbacks use method syntax so a `ColumnDef<T, number>`
+ * is assignable to `ColumnDef<T>`.
+ */
+export interface ColumnDef<T, V = unknown> {
+  /** Unique id. Defaults to `field`. Required for accessor and display columns. */
+  id?: string;
+  field?: Extract<keyof T, string>;
+  accessor?(row: T): V;
+  header?: string;
+  type?: ColumnType;
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  align?: "start" | "center" | "end";
+  /** Initial pin side. */
+  pin?: PinSide;
+  /** Initially hidden. */
+  hidden?: boolean;
+  sortable?: boolean;
+  filterable?: boolean;
+  resizable?: boolean;
+  hideable?: boolean;
+  reorderable?: boolean;
+  pinnable?: boolean;
+  /** Included in the global search. Default true for data columns. */
+  searchable?: boolean;
+  /** Fixed choices: enables the `in` filter and the select editor. */
+  options?: ReadonlyArray<ColumnOption>;
+  /** Display text for the value; also used by search, CSV, PDF and copy. */
+  format?(value: V, row: T): string;
+  /** Custom cell renderer. */
+  cell?(ctx: CellContext<T, V>): ReactNode;
+  sortFn?(a: V, b: V, rowA: T, rowB: T): number;
+  filterFn?(value: V, filter: ColumnFilter, row: T): boolean;
+  editable?: boolean | ((row: T) => boolean);
+  editor?: BuiltInEditor | ((props: EditorProps<T, V>) => ReactNode);
+  /** Return an error message to reject an edit. */
+  validate?(value: V, row: T): string | null | undefined;
+  exportable?: boolean;
+  exportValue?(row: T): ExportCellValue;
+  headerClassName?: string;
+  cellClassName?: string | ((ctx: CellContext<T, V>) => string | undefined);
+}
+
+export interface ResolvedColumn<T> {
+  id: string;
+  def: ColumnDef<T>;
+  header: string;
+  type: ColumnType;
+  /** False for display-only columns (no field or accessor). */
+  hasValue: boolean;
+  getValue(row: T): unknown;
+  width: number;
+  minWidth: number;
+  maxWidth: number;
+  align: "start" | "center" | "end";
+  sortable: boolean;
+  filterable: boolean;
+  resizable: boolean;
+  hideable: boolean;
+  reorderable: boolean;
+  pinnable: boolean;
+  searchable: boolean;
+  exportable: boolean;
+  /** Internal columns (row selection) are never exported or listed in menus. */
+  internal: boolean;
+}
+
+export interface ColumnLayoutItem<T> {
+  column: ResolvedColumn<T>;
+  width: number;
+  pinned: PinSide | false;
+  /** Offset from the start of its section (left, center or right). */
+  offset: number;
+  /** Position in visual order, 0-based; also the CSS variable index. */
+  visibleIndex: number;
+  /** Last left-pinned or first right-pinned column (draws the pin shadow). */
+  pinEdge: boolean;
+  /** Stable style object for cells of this column. */
+  style: Record<string, string>;
+}
+
+export interface ColumnLayout<T> {
+  columns: ColumnLayoutItem<T>[];
+  left: ColumnLayoutItem<T>[];
+  center: ColumnLayoutItem<T>[];
+  right: ColumnLayoutItem<T>[];
+  leftWidth: number;
+  centerWidth: number;
+  rightWidth: number;
+  totalWidth: number;
+}
+
+export interface CellEditEvent<T> {
+  row: T;
+  rowId: RowId;
+  columnId: string;
+  value: unknown;
+  previousValue: unknown;
+}
+
+export type ExportScope = "filtered" | "all" | "selected" | "page";
+
+export interface ExportOptions<T> {
+  fileName?: string;
+  scope?: ExportScope;
+  /** Export these rows instead of a scope, e.g. a full result set fetched from the server. */
+  rows?: readonly T[];
+}
+
+export type PdfPaperSize = "A3" | "A4" | "A5" | "letter" | "legal";
+
+/**
+ * A repeating page band. Each slot takes plain text with `{title}`, `{page}`,
+ * `{pages}`, `{date}` and `{time}` substituted as the page is drawn.
+ */
+export interface PdfBand {
+  left?: string;
+  center?: string;
+  right?: string;
+}
+
+/** Colors for the generated PDF, as `#rgb` or `#rrggbb`. */
+export interface PdfTheme {
+  text: string;
+  /** Header and footer bands. */
+  muted: string;
+  border: string;
+  headerBg: string;
+  headerText: string;
+  /** Every other body row, or null for no striping. */
+  stripe: string | null;
+}
+
+export interface PrintExportOptions<T> extends ExportOptions<T> {
+  title?: string;
+  orientation?: "portrait" | "landscape";
+  paperSize?: PdfPaperSize;
+}
+
+export interface PdfExportOptions<T> extends PrintExportOptions<T> {
+  /** Page margin in points. 72 points to the inch; defaults to 36. */
+  margin?: number;
+  /** Body text size in points; defaults to 9. */
+  fontSize?: number;
+  /** Top of every page. Defaults to the title on the left; null removes it. */
+  header?: PdfBand | null;
+  /** Bottom of every page. Defaults to date and page numbers; null removes it. */
+  footer?: PdfBand | null;
+  theme?: Partial<PdfTheme>;
+}
+
+export interface GridOptions<T> {
+  data: readonly T[];
+  columns: readonly ColumnDef<T>[];
+  /**
+   * Stable row id: a property name (recommended) or a function.
+   * Defaults to `row.id`, falling back to the array index.
+   */
+  getRowId?: Extract<keyof T, string> | ((row: T, index: number) => RowId);
+  /** `client`: the grid sorts, filters and paginates. `server`: `data` is the current page. */
+  mode?: "client" | "server";
+  /** Total rows on the server (server mode). */
+  rowCount?: number;
+  state?: Partial<GridState>;
+  initialState?: Partial<GridState>;
+  onStateChange?(next: GridState, prev: GridState): void;
+  /** Fires when sorting, filters, search or pagination change. */
+  onQueryChange?(query: GridQuery): void;
+  enablePagination?: boolean;
+  enableSorting?: boolean;
+  enableMultiSort?: boolean;
+  enableFiltering?: boolean;
+  enableColumnResizing?: boolean;
+  enableColumnReordering?: boolean;
+  enableColumnPinning?: boolean;
+  enableColumnHiding?: boolean;
+  enableRowSelection?: boolean | ((row: T) => boolean);
+  selectionMode?: "single" | "multiple";
+  onCellEdit?(event: CellEditEvent<T>): void | Promise<void>;
+  /** Not fired for clicks on interactive content (buttons, inputs, links, checkboxes). */
+  onRowClick?(row: T, event: MouseEvent<HTMLElement>): void;
+  onRowDoubleClick?(row: T, event: MouseEvent<HTMLElement>): void;
+  exportFileName?: string;
+}