@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/data-grid/react/Toolbar.tsx

@@ -0,0 +1,267 @@
+"use client";
+
+import { useMemo, type ReactNode } from "react";
+import { isFilterActive } from "../core/filtering";
+import type { ColumnFilter, Density, FilterValue, ResolvedColumn, RowId } from "../core/types";
+import { toTime } from "../core/values";
+import { cx, useGridContext } from "./context";
+import { usePopoverState, useSelectionState } from "./hooks";
+import { ColumnsIcon, DensityIcon, DownloadIcon, SearchIcon, XIcon } from "./icons";
+import type { LocaleText } from "./locale";
+import { Popover } from "./Popover";
+
+export interface ToolbarOptions {
+  search?: boolean;
+  filterChips?: boolean;
+  columns?: boolean;
+  density?: boolean;
+  export?: boolean;
+  /** Rendered at the start of the toolbar. */
+  start?: ReactNode;
+  /** Rendered at the end of the toolbar. */
+  end?: ReactNode;
+}
+
+interface ToolbarProps<T> {
+  options: ToolbarOptions;
+  globalFilter: string;
+  filters: ColumnFilter[];
+  density: Density;
+  columns: ResolvedColumn<T>[];
+  columnVisibility: Record<string, boolean>;
+}
+
+export function Toolbar<T>({ options, globalFilter, filters, density, columns, columnVisibility }: ToolbarProps<T>) {
+  const { engine, locale, classNames, features } = useGridContext<T>();
+  const { api } = engine;
+  const activeFilters = filters.filter(isFilterActive);
+
+  const densities: [Density, string][] = [
+    ["compact", locale.densityCompact],
+    ["standard", locale.densityStandard],
+    ["comfortable", locale.densityComfortable],
+  ];
+
+  return (
+    <div className={cx("dg-toolbar", classNames.toolbar)}>
+      {options.start}
+
+      {options.search && (
+        <div className="dg-search">
+          <SearchIcon />
+          <input
+            type="search"
+            value={globalFilter}
+            placeholder={locale.searchPlaceholder}
+            aria-label={locale.search}
+            onChange={(event) => api.setGlobalFilter(event.target.value)}
+          />
+        </div>
+      )}
+
+      {options.filterChips && activeFilters.length > 0 && (
+        <div className="dg-chips">
+          {activeFilters.map((filter) => {
+            const column = columns.find((c) => c.id === filter.columnId);
+            if (!column) return null;
+            const label = describeFilter(filter, column, locale);
+            return (
+              <span key={filter.columnId} className="dg-chip">
+                {label}
+                <button
+                  type="button"
+                  className="dg-chip-remove"
+                  aria-label={locale.removeFilter(label)}
+                  onClick={() => api.setFilter(filter.columnId, null)}
+                >
+                  <XIcon width={12} height={12} />
+                </button>
+              </span>
+            );
+          })}
+          <button type="button" className="dg-link-button" onClick={() => api.clearFilters()}>
+            {locale.clearFilters}
+          </button>
+        </div>
+      )}
+
+      <SelectionSummary />
+      <div className="dg-toolbar-spacer" />
+
+      {options.density && (
+        <ToolbarMenu label={locale.density} icon={<DensityIcon />}>
+          {(close) => (
+            <div className="dg-menu-section" role="radiogroup" aria-label={locale.density}>
+              {densities.map(([value, label]) => (
+                <button
+                  key={value}
+                  type="button"
+                  role="radio"
+                  aria-checked={density === value}
+                  className="dg-menu-item"
+                  onClick={() => {
+                    api.setDensity(value);
+                    close();
+                  }}
+                >
+                  {label}
+                </button>
+              ))}
+            </div>
+          )}
+        </ToolbarMenu>
+      )}
+
+      {options.columns && features.hiding && (
+        <ToolbarMenu label={locale.columns} icon={<ColumnsIcon />}>
+          {() => <ColumnVisibilityList columns={columns} columnVisibility={columnVisibility} />}
+        </ToolbarMenu>
+      )}
+
+      {options.export && (
+        <ToolbarMenu label={locale.export} icon={<DownloadIcon />}>
+          {(close) => (
+            <div className="dg-menu-section">
+              {(
+                [
+                  [locale.exportCsv, () => api.exportCsv()],
+                  [locale.exportExcel, () => api.exportExcel()],
+                  [locale.exportPdf, () => api.exportPdf()],
+                  [locale.print, () => api.print()],
+                ] as const
+              ).map(([label, action]) => (
+                <button
+                  key={label}
+                  type="button"
+                  className="dg-menu-item"
+                  onClick={() => {
+                    close();
+                    void action();
+                  }}
+                >
+                  {label}
+                </button>
+              ))}
+            </div>
+          )}
+        </ToolbarMenu>
+      )}
+
+      {options.end}
+    </div>
+  );
+}
+
+function ToolbarMenu({
+  label,
+  icon,
+  children,
+}: {
+  label: string;
+  icon: ReactNode;
+  children: (close: () => void) => ReactNode;
+}) {
+  const menu = usePopoverState();
+  const anchor = menu.state?.anchor ?? null;
+  const close = () => menu.close(anchor);
+
+  return (
+    <>
+      <button
+        type="button"
+        className="dg-button"
+        aria-haspopup="dialog"
+        aria-expanded={anchor !== null}
+        onClick={(event) => menu.open(event.currentTarget)}
+      >
+        {icon}
+        <span className="dg-button-label">{label}</span>
+      </button>
+      {anchor && (
+        <Popover anchor={anchor} onClose={close} label={label} align="end">
+          {children(close)}
+        </Popover>
+      )}
+    </>
+  );
+}
+
+function SelectionSummary<T>() {
+  const { engine, locale, features, numberFormat } = useGridContext<T>();
+  const selection = useSelectionState<T, Record<RowId, boolean>>((s) => s);
+  const count = useMemo(() => Object.values(selection).filter(Boolean).length, [selection]);
+
+  if (!features.selection || count === 0) return null;
+  return (
+    <div className="dg-selection" role="status">
+      {locale.selected(numberFormat.format(count))}
+      <button type="button" className="dg-link-button" onClick={() => engine.api.clearSelection()}>
+        {locale.clearSelection}
+      </button>
+    </div>
+  );
+}
+
+function ColumnVisibilityList<T>({
+  columns,
+  columnVisibility,
+}: {
+  columns: ResolvedColumn<T>[];
+  columnVisibility: Record<string, boolean>;
+}) {
+  const { engine, locale } = useGridContext<T>();
+  const visibleCount = columns.filter((c) => columnVisibility[c.id] !== false).length;
+
+  return (
+    <div className="dg-menu-section">
+      <div className="dg-check-list">
+        {columns.map((column) => {
+          const visible = columnVisibility[column.id] !== false;
+          return (
+            <label key={column.id}>
+              <input
+                type="checkbox"
+                className="dg-checkbox"
+                checked={visible}
+                disabled={!column.hideable || (visible && visibleCount === 1)}
+                onChange={() => engine.api.setColumnVisibility(column.id, !visible)}
+              />
+              {column.header}
+            </label>
+          );
+        })}
+      </div>
+      <button type="button" className="dg-menu-item" onClick={() => engine.api.resetColumns()}>
+        {locale.resetColumns}
+      </button>
+    </div>
+  );
+}
+
+function describeFilter<T>(filter: ColumnFilter, column: ResolvedColumn<T>, locale: LocaleText): string {
+  const operator = locale.operators[filter.operator];
+  const format = (value: FilterValue | undefined): string => {
+    if (value === null || value === undefined || value === "") return "…";
+    if (typeof value === "boolean") return value ? locale.yes : locale.no;
+    if (Array.isArray(value)) {
+      return value
+        .map((v) => column.def.options?.find((o) => o.value === v)?.label ?? String(v))
+        .join(", ");
+    }
+    if (column.type === "date") {
+      const time = toTime(value);
+      return time === null ? String(value) : new Date(time).toLocaleDateString();
+    }
+    return String(value);
+  };
+
+  switch (filter.operator) {
+    case "isEmpty":
+    case "isNotEmpty":
+      return `${column.header} ${operator}`;
+    case "between":
+      return `${column.header} ${format(filter.value)} – ${format(filter.value2)}`;
+    default:
+      return `${column.header} ${operator} ${format(filter.value)}`;
+  }
+}

package/source/components/data-grid/react/Viewport.tsx

@@ -0,0 +1,167 @@
+"use client";
+
+import { useLayoutEffect, useMemo, useRef, type CSSProperties, type ReactNode, type UIEvent } from "react";
+import { getLayoutVars } from "../core/columns";
+import type { PageResult } from "../core/rows";
+import type { ColumnFilter, ColumnLayout, GridRow, SortItem } from "../core/types";
+import { getColumnRange, getRowRange, visibleRangeEqual, type VisibleRange } from "../core/virtual";
+import { cx, useGridContext } from "./context";
+import { HeaderRow } from "./HeaderRow";
+import { useStoreSelector } from "./hooks";
+import { handleGridKeyDown } from "./keyboard";
+import { Row } from "./Row";
+
+interface GridViewportProps<T> {
+  layout: ColumnLayout<T>;
+  page: PageResult<T>;
+  sortedRows: GridRow<T>[];
+  sorting: SortItem[];
+  filters: ColumnFilter[];
+  hasQuery: boolean;
+  rowHeight: number;
+  headerHeight: number;
+  height: number | string | undefined;
+  loading: boolean;
+  emptyState: ReactNode;
+  ariaLabel: string;
+  getRowClassName: ((row: T, rowIndex: number) => string | undefined) | undefined;
+}
+
+export function GridViewport<T>({
+  layout,
+  page,
+  sortedRows,
+  sorting,
+  filters,
+  hasQuery,
+  rowHeight,
+  headerHeight,
+  height,
+  loading,
+  emptyState,
+  ariaLabel,
+  getRowClassName,
+}: GridViewportProps<T>) {
+  const { engine, locale, classNames, features } = useGridContext<T>();
+  const ref = useRef<HTMLDivElement>(null);
+  const rows = page.rows;
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    engine.attachViewport(el);
+    const measure = () =>
+      engine.viewport.setState((v) =>
+        v.width === el.clientWidth && v.height === el.clientHeight
+          ? v
+          : { ...v, width: el.clientWidth, height: el.clientHeight },
+      );
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => {
+      observer.disconnect();
+      engine.attachViewport(null);
+    };
+  }, [engine]);
+
+  // Re-renders only when the visible window of rows or columns changes.
+  const range = useStoreSelector(
+    engine.viewport,
+    (v): VisibleRange => ({
+      rows: getRowRange(v, rows.length, rowHeight, headerHeight),
+      columns: getColumnRange(layout, v),
+    }),
+    visibleRangeEqual,
+  );
+
+  const active = useStoreSelector(engine.store, (s) => s.ui.activeCell);
+  const activeItem = active ? layout.columns[active.colIndex] : undefined;
+  const centerIndex = activeItem ? activeItem.visibleIndex - layout.left.length : -1;
+  const activeRendered =
+    !active ||
+    (activeItem !== undefined &&
+      (active.rowIndex === -1 || (active.rowIndex >= range.rows.start && active.rowIndex < range.rows.end)) &&
+      (activeItem.pinned !== false || (centerIndex >= range.columns.start && centerIndex < range.columns.end)));
+
+  const style = useMemo(
+    () => ({ ...getLayoutVars(layout), height }) as CSSProperties,
+    [layout, height],
+  );
+
+  const onScroll = (event: UIEvent<HTMLDivElement>) => {
+    const { scrollTop, scrollLeft } = event.currentTarget;
+    engine.viewport.setState((v) =>
+      v.scrollTop === scrollTop && v.scrollLeft === scrollLeft ? v : { ...v, scrollTop, scrollLeft },
+    );
+  };
+
+  const rendered: ReactNode[] = [];
+  for (let i = range.rows.start; i < Math.min(range.rows.end, rows.length); i++) {
+    const row = rows[i];
+    rendered.push(
+      <Row
+        key={row.id}
+        row={row}
+        rowIndex={i}
+        ariaRowIndex={page.pageOffset + i + 2}
+        top={i * rowHeight}
+        layout={layout}
+        colRange={range.columns}
+        className={getRowClassName?.(row.original, i)}
+      />,
+    );
+  }
+
+  return (
+    <div className="dg-viewport-wrap">
+      <div
+        ref={ref}
+        role="grid"
+        aria-label={ariaLabel}
+        aria-rowcount={page.rowCount + 1}
+        aria-colcount={layout.columns.length}
+        aria-multiselectable={features.selection && features.selectionMode === "multiple" ? true : undefined}
+        aria-busy={loading || undefined}
+        // The active cell is the tab stop; if it is scrolled out of the DOM, the grid itself is.
+        tabIndex={activeRendered ? -1 : 0}
+        className={cx("dg-viewport", classNames.viewport)}
+        style={style}
+        onScroll={onScroll}
+        onKeyDown={(event) => handleGridKeyDown(event, engine)}
+        onFocus={(event) => {
+          if (event.target === event.currentTarget && active && !activeRendered) {
+            engine.setActiveCell(active.rowIndex, active.colIndex);
+          }
+        }}
+      >
+        <HeaderRow layout={layout} colRange={range.columns} sorting={sorting} filters={filters} rows={sortedRows} />
+        <div role="rowgroup" className="dg-body" style={{ height: rows.length * rowHeight }}>
+          {rendered}
+        </div>
+      </div>
+
+      {rows.length === 0 && (
+        <div className="dg-overlay" role="status">
+          {loading
+            ? locale.loading
+            : (emptyState ?? (
+                <div className="dg-empty">
+                  <span>{hasQuery ? locale.noResults : locale.noRows}</span>
+                  {hasQuery && (
+                    <button type="button" className="dg-button" onClick={() => engine.api.clearFilters()}>
+                      {locale.clearFilters}
+                    </button>
+                  )}
+                </div>
+              ))}
+        </div>
+      )}
+      {loading && (
+        <div className="dg-loading" aria-hidden="true">
+          <div className="dg-loading-bar" />
+        </div>
+      )}
+    </div>
+  );
+}

package/source/components/data-grid/react/context.ts

@@ -0,0 +1,57 @@
+"use client";
+
+import { createContext, use } from "react";
+import type { GridEngine } from "../core/grid";
+import type { RowId } from "../core/types";
+import type { Formatters } from "../core/values";
+import type { LocaleText } from "./locale";
+
+export type GridSlot =
+  | "root"
+  | "toolbar"
+  | "viewport"
+  | "header"
+  | "headerCell"
+  | "row"
+  | "cell"
+  | "pagination";
+
+export interface GridFeatures {
+  sorting: boolean;
+  filtering: boolean;
+  resizing: boolean;
+  reordering: boolean;
+  pinning: boolean;
+  hiding: boolean;
+  selection: boolean;
+  selectionMode: "single" | "multiple";
+}
+
+export interface GridContextValue<T> {
+  engine: GridEngine<T>;
+  locale: LocaleText;
+  classNames: Partial<Record<GridSlot, string>>;
+  features: GridFeatures;
+  formatters: Formatters;
+  numberFormat: Intl.NumberFormat;
+  /** Set when the parent controls `rowSelection`. */
+  controlledSelection: Record<RowId, boolean> | undefined;
+  isRowSelectable(row: T): boolean;
+  openColumnMenu(columnId: string, anchor: HTMLElement): void;
+}
+
+export const GridContext = createContext<GridContextValue<unknown> | null>(null);
+
+export function useGridContext<T>(): GridContextValue<T> {
+  const context = use(GridContext);
+  if (!context) {
+    throw new Error("[DataGrid] Grid parts must be rendered inside <DataGrid>.");
+  }
+  return context as unknown as GridContextValue<T>;
+}
+
+/** Marks a cell without an in-flight async edit. */
+export const NO_PENDING: unique symbol = Symbol("dg.noPending");
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/data-grid/react/hooks.ts

@@ -0,0 +1,83 @@
+"use client";
+
+import { useCallback, useLayoutEffect, useRef, useState, useSyncExternalStore, type RefObject } from "react";
+import type { ReadableStore } from "../core/store";
+import type { RowId } from "../core/types";
+import { useGridContext } from "./context";
+
+/**
+ * Subscribes to a slice of an external store. The component re-renders only
+ * when the selected value changes according to `isEqual`.
+ *
+ * The cache lives in a ref rather than in the getter's closure, because callers
+ * pass the selector inline: a closure-held cache would start empty on every
+ * render, so `isEqual` would never see the previous value and a selector that
+ * builds an object would hand back a fresh identity each time, re-rendering
+ * every memoized child below it. The selector is part of the cache key, so a
+ * selector that closed over something new is always recomputed.
+ */
+export function useStoreSelector<S, R>(
+  store: ReadableStore<S>,
+  selector: (snapshot: S) => R,
+  isEqual: (a: R, b: R) => boolean = Object.is,
+): R {
+  const cache = useRef<{ snapshot: S; selector: (snapshot: S) => R; value: R } | null>(null);
+
+  const getSelection = useCallback(() => {
+    const snapshot = store.getSnapshot();
+    const previous = cache.current;
+    if (previous && Object.is(previous.snapshot, snapshot) && previous.selector === selector) {
+      return previous.value;
+    }
+    const value = selector(snapshot);
+    // Keep the previous identity while the two are equal, so `visibleRangeEqual`
+    // and friends hold across renders and not just within one.
+    const kept = previous && isEqual(previous.value, value) ? previous.value : value;
+    cache.current = { snapshot, selector, value: kept };
+    return kept;
+  }, [store, selector, isEqual]);
+
+  return useSyncExternalStore(store.subscribe, getSelection, getSelection);
+}
+
+/** Row selection, from the controlled prop when present, otherwise internal state. */
+export function useSelectionState<T, R>(
+  selector: (selection: Record<RowId, boolean>) => R,
+): R {
+  const { engine, controlledSelection } = useGridContext<T>();
+  const internal = useStoreSelector(engine.store, (s) => selector(s.state.rowSelection));
+  return controlledSelection ? selector(controlledSelection) : internal;
+}
+
+/** Moves DOM focus to a cell once it becomes active through keyboard navigation. */
+export function useFocusWhenActive(
+  ref: RefObject<HTMLElement | null>,
+  active: boolean,
+  editing = false,
+) {
+  const { engine } = useGridContext();
+  useLayoutEffect(() => {
+    if (active && !editing && engine.consumeFocusRequest()) {
+      ref.current?.focus({ preventScroll: true });
+    }
+  }, [active, editing, engine, ref]);
+}
+
+/** Open state for an anchored popover, ignoring the click that just dismissed it. */
+export function usePopoverState<P = void>() {
+  const [state, setState] = useState<{ anchor: HTMLElement; payload: P } | null>(null);
+  const lastClosed = useRef<{ anchor: HTMLElement | null; time: number }>({ anchor: null, time: 0 });
+
+  const open = useCallback((anchor: HTMLElement, payload: P) => {
+    const last = lastClosed.current;
+    if (last.anchor === anchor && performance.now() - last.time < 300) return;
+    setState({ anchor, payload });
+  }, []);
+
+  const close = useCallback((anchor: HTMLElement | null) => {
+    lastClosed.current = { anchor, time: performance.now() };
+    setState(null);
+  }, []);
+
+  return { state, open, close };
+}

package/source/components/data-grid/react/icons.tsx

@@ -0,0 +1,45 @@
+import { Svg, type IconProps } from "../../shared/react/icons";
+
+export {
+  CheckIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  SearchIcon,
+  XIcon,
+} from "../../shared/react/icons";
+
+export const ArrowUpIcon = (p: IconProps) => (
+  <Svg {...p}><path d="M12 19V5M5 12l7-7 7 7" /></Svg>
+);
+export const ArrowDownIcon = (p: IconProps) => (
+  <Svg {...p}><path d="M12 5v14M19 12l-7 7-7-7" /></Svg>
+);
+export const MoreIcon = (p: IconProps) => (
+  <Svg {...p}><path d="M12 5h.01M12 12h.01M12 19h.01" strokeWidth="3" /></Svg>
+);
+export const ChevronsLeftIcon = (p: IconProps) => (
+  <Svg {...p}><path d="m11 17-5-5 5-5M18 17l-5-5 5-5" /></Svg>
+);
+export const ChevronsRightIcon = (p: IconProps) => (
+  <Svg {...p}><path d="m13 17 5-5-5-5M6 17l5-5-5-5" /></Svg>
+);
+export const ColumnsIcon = (p: IconProps) => (
+  <Svg {...p}><rect x="3" y="4" width="18" height="16" rx="2" /><path d="M9 4v16M15 4v16" /></Svg>
+);
+export const DownloadIcon = (p: IconProps) => (
+  <Svg {...p}><path d="M12 4v11m0 0-4-4m4 4 4-4M5 20h14" /></Svg>
+);
+export const DensityIcon = (p: IconProps) => (
+  <Svg {...p}><path d="M4 6h16M4 12h16M4 18h16" /></Svg>
+);
+export const PinIcon = (p: IconProps) => (
+  <Svg {...p}><path d="M12 17v5M9 3h6l-1 6 3 4H7l3-4z" /></Svg>
+);
+export const EyeOffIcon = (p: IconProps) => (
+  <Svg {...p}>
+    <path d="m3 3 18 18M10.6 10.6a2 2 0 0 0 2.8 2.8M9.9 5.1A10 10 0 0 1 12 5c6 0 10 7 10 7a17 17 0 0 1-3 3.9M6.6 6.6C3.9 8.4 2 12 2 12s4 7 10 7a9.7 9.7 0 0 0 5.4-1.6" />
+  </Svg>
+);
+export const MoveIcon = (p: IconProps) => (
+  <Svg {...p}><path d="M5 12h14M9 8l-4 4 4 4M15 8l4 4-4 4" /></Svg>
+);