gbs-add-block 1.2.7 → 1.2.8

package/source/components/datagridbeta/core/sorting.ts

@@ -0,0 +1,111 @@
+import type { GridRow, ResolvedColumn, SortItem } from "./types";
+import { toTime } from "./values";
+
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" });
+
+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>): 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 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[],
+): 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);
+    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/datagridbeta/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/datagridbeta/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/datagridbeta/core/types.ts

@@ -0,0 +1,266 @@
+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 interface PdfExportOptions<T> extends ExportOptions<T> {
+  title?: string;
+  orientation?: "portrait" | "landscape";
+  paperSize?: "A3" | "A4" | "A5" | "letter" | "legal";
+}
+
+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;
+}

package/source/components/datagridbeta/core/values.ts

@@ -0,0 +1,98 @@
+import type { ResolvedColumn } from "./types";
+
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+export interface Formatters {
+  date: Intl.DateTimeFormat;
+  yes: string;
+  no: string;
+}
+
+export function createFormatters(
+  locale?: string,
+  labels: { yes: string; no: string } = { yes: "Yes", no: "No" },
+): Formatters {
+  return {
+    date: new Intl.DateTimeFormat(locale, { dateStyle: "medium" }),
+    ...labels,
+  };
+}
+
+/** Milliseconds since epoch, or null. Date-only strings are read as local dates. */
+export function toTime(value: unknown): number | null {
+  if (value instanceof Date) {
+    const time = value.getTime();
+    return Number.isNaN(time) ? null : time;
+  }
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "string" && value !== "") {
+    const match = DATE_ONLY.exec(value);
+    const time = match
+      ? new Date(+match[1], +match[2] - 1, +match[3]).getTime()
+      : Date.parse(value);
+    return Number.isNaN(time) ? null : time;
+  }
+  return null;
+}
+
+export function startOfNextDay(time: number): number {
+  const date = new Date(time);
+  date.setHours(0, 0, 0, 0);
+  date.setDate(date.getDate() + 1);
+  return date.getTime();
+}
+
+export function startOfDay(time: number): number {
+  const date = new Date(time);
+  date.setHours(0, 0, 0, 0);
+  return date.getTime();
+}
+
+export function isEmptyValue(value: unknown): boolean {
+  return (
+    value === null ||
+    value === undefined ||
+    (typeof value === "string" && value.trim() === "") ||
+    (typeof value === "number" && Number.isNaN(value)) ||
+    (Array.isArray(value) && value.length === 0)
+  );
+}
+
+/** `YYYY-MM-DD` in local time, for `<input type="date">`. */
+export function toDateInputValue(value: unknown): string {
+  const time = toTime(value);
+  if (time === null) return "";
+  const date = new Date(time);
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+/** Display text for a cell; also used by search, CSV, PDF and clipboard copy. */
+export function formatCellValue<T>(
+  column: ResolvedColumn<T>,
+  value: unknown,
+  row: T,
+  formatters: Formatters,
+): string {
+  if (column.def.format) return column.def.format(value, row);
+  if (value === null || value === undefined) return "";
+
+  const { options } = column.def;
+  if (options) {
+    const option = options.find((o) => o.value === value);
+    if (option) return option.label;
+  }
+
+  switch (column.type) {
+    case "date": {
+      const time = toTime(value);
+      return time === null ? String(value) : formatters.date.format(time);
+    }
+    case "boolean":
+      return value ? formatters.yes : formatters.no;
+    default:
+      if (Array.isArray(value)) return value.join(", ");
+      if (value instanceof Date) return formatters.date.format(value);
+      return String(value);
+  }
+}

package/source/components/datagridbeta/core/virtual.ts

@@ -0,0 +1,85 @@
+import type { ColumnLayout } from "./types";
+
+export interface Viewport {
+  scrollTop: number;
+  scrollLeft: number;
+  width: number;
+  height: number;
+}
+
+/** Half-open range: `start` inclusive, `end` exclusive. */
+export interface Range {
+  start: number;
+  end: number;
+}
+
+export interface VisibleRange {
+  rows: Range;
+  columns: Range;
+}
+
+export function getRowRange(
+  viewport: Viewport,
+  rowCount: number,
+  rowHeight: number,
+  headerHeight: number,
+  overscan = 6,
+): Range {
+  if (rowCount === 0) return { start: 0, end: 0 };
+  const bodyHeight = Math.max(0, viewport.height - headerHeight);
+  const first = Math.floor(viewport.scrollTop / rowHeight);
+  const last = Math.ceil((viewport.scrollTop + bodyHeight) / rowHeight);
+  return {
+    start: Math.max(0, Math.min(rowCount, first) - overscan),
+    end: Math.min(rowCount, last + overscan),
+  };
+}
+
+/** Range of center (unpinned) columns intersecting the viewport. */
+export function getColumnRange<T>(
+  layout: ColumnLayout<T>,
+  viewport: Viewport,
+  overscan = 2,
+): Range {
+  const { center } = layout;
+  const count = center.length;
+  // Width is unknown before the first measurement (and during SSR): render everything.
+  if (count === 0 || viewport.width === 0) return { start: 0, end: count };
+
+  // Browsers report negative scrollLeft in RTL.
+  const windowStart = Math.abs(viewport.scrollLeft);
+  const windowEnd =
+    windowStart + Math.max(0, viewport.width - layout.leftWidth - layout.rightWidth);
+
+  // First column whose right edge is past windowStart.
+  let lo = 0;
+  let hi = count;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (center[mid].offset + center[mid].width <= windowStart) lo = mid + 1;
+    else hi = mid;
+  }
+  const start = lo;
+
+  // First column starting at or past windowEnd.
+  hi = count;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (center[mid].offset < windowEnd) lo = mid + 1;
+    else hi = mid;
+  }
+
+  return {
+    start: Math.max(0, start - overscan),
+    end: Math.min(count, Math.max(lo, start + 1) + overscan),
+  };
+}
+
+export function visibleRangeEqual(a: VisibleRange, b: VisibleRange): boolean {
+  return (
+    a.rows.start === b.rows.start &&
+    a.rows.end === b.rows.end &&
+    a.columns.start === b.columns.start &&
+    a.columns.end === b.columns.end
+  );
+}