@stackframe/dashboard-ui-components 2.8.89 → 2.8.92

package/dist/components/chart-legend.d.ts

@@ -2,7 +2,7 @@ import * as React$1 from "react";
 import * as RechartsPrimitive from "recharts";
 
 //#region src/components/chart-legend.d.ts
-declare const DesignChartLegendContent: React$1.ForwardRefExoticComponent<Omit<React$1.ClassAttributes<HTMLDivElement> & React$1.HTMLAttributes<HTMLDivElement> & Pick<RechartsPrimitive.LegendProps, "verticalAlign" | "payload"> & {
+declare const DesignChartLegendContent: React$1.ForwardRefExoticComponent<Omit<React$1.ClassAttributes<HTMLDivElement> & React$1.HTMLAttributes<HTMLDivElement> & Pick<RechartsPrimitive.LegendProps, "payload" | "verticalAlign"> & {
   hideIcon?: boolean;
   nameKey?: string;
 }, "ref"> & React$1.RefAttributes<HTMLDivElement>>;

package/dist/components/data-grid/data-grid-sizing.d.ts

@@ -1,12 +1,13 @@
 import { DataGridColumnDef } from "./types.js";
-import { CSSProperties } from "react";
 
 //#region src/components/data-grid/data-grid-sizing.d.ts
+declare const DEFAULT_MAX_COL_WIDTH = 800;
+declare const DEFAULT_COL_WIDTH = 150;
+/** Effective minimum column width. When `col.minWidth` is unset, derive
+ * one from the header label so it never gets clipped during resize. */
 declare function getEffectiveMinWidth<TRow>(col: DataGridColumnDef<TRow>): number;
-declare function getColumnSizingStyle<TRow>(col: DataGridColumnDef<TRow>): CSSProperties;
-declare function createGridSizingStyle(widths: ReadonlyMap<string, number>, totalWidth: number): Record<string, string>;
-declare function applyDraggedColumnWidth(el: HTMLElement, columnId: string, width: number, totalWidth: number): void;
+declare function getEffectiveMaxWidth<TRow>(col: DataGridColumnDef<TRow>): number;
 declare function clampColumnWidth<TRow>(col: DataGridColumnDef<TRow>, width: number): number;
 //#endregion
-export { applyDraggedColumnWidth, clampColumnWidth, createGridSizingStyle, getColumnSizingStyle, getEffectiveMinWidth };
+export { DEFAULT_COL_WIDTH, DEFAULT_MAX_COL_WIDTH, clampColumnWidth, getEffectiveMaxWidth, getEffectiveMinWidth };
 //# sourceMappingURL=data-grid-sizing.d.ts.map

package/dist/components/data-grid/data-grid-sizing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-grid-sizing.d.ts","names":[],"sources":["../../../src/components/data-grid/data-grid-sizing.ts"],"mappings":";;;;iBAgEgB,oBAAA,MAAA,CAA2B,GAAA,EAAK,iBAAA,CAAkB,IAAA;AAAA,iBAWlD,oBAAA,MAAA,CAA2B,GAAA,EAAK,iBAAA,CAAkB,IAAA,IAAQ,aAAA;AAAA,iBAW1D,qBAAA,CACd,MAAA,EAAQ,WAAA,kBACR,UAAA,WACC,MAAA;AAAA,iBAQa,uBAAA,CACd,EAAA,EAAI,WAAA,EACJ,QAAA,UACA,KAAA,UACA,UAAA;AAAA,iBAMc,gBAAA,MAAA,CAAuB,GAAA,EAAK,iBAAA,CAAkB,IAAA,GAAO,KAAA"}
+{"version":3,"file":"data-grid-sizing.d.ts","names":[],"sources":["../../../src/components/data-grid/data-grid-sizing.ts"],"mappings":";;;cAIa,qBAAA;AAAA,cACA,iBAAA;AADb;;AAAA,iBA+BgB,oBAAA,MAAA,CAA2B,GAAA,EAAK,iBAAA,CAAkB,IAAA;AAAA,iBASlD,oBAAA,MAAA,CAA2B,GAAA,EAAK,iBAAA,CAAkB,IAAA;AAAA,iBAIlD,gBAAA,MAAA,CAAuB,GAAA,EAAK,iBAAA,CAAkB,IAAA,GAAO,KAAA"}

package/dist/components/data-grid/data-grid-sizing.js

@@ -1,13 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 //#region src/components/data-grid/data-grid-sizing.ts
-function colVar(id) {
-	if (process.env.NODE_ENV !== "production" && !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(id)) console.warn(`[DataGrid] column id ${JSON.stringify(id)} contains characters that are not safe in a CSS custom property name. Prefer ascii identifiers.`);
-	return `--col-${id}`;
-}
 const MIN_COL_WIDTH = 20;
 const MIN_CUSTOM_HEADER_WIDTH = 50;
 const DEFAULT_MAX_COL_WIDTH = 800;
+const DEFAULT_COL_WIDTH = 150;
 const HEADER_CHROME_PX = 44;
 let measureContext = null;
 const headerWidthCache = /* @__PURE__ */ new Map();
@@ -23,41 +20,25 @@ function measureHeaderLabelWidth(label) {
 	headerWidthCache.set(label, width);
 	return width;
 }
+/** Effective minimum column width. When `col.minWidth` is unset, derive
+* one from the header label so it never gets clipped during resize. */
 function getEffectiveMinWidth(col) {
 	if (col.minWidth != null) return col.minWidth;
 	const label = typeof col.header === "string" ? col.header : null;
 	if (label == null) return typeof col.header === "function" ? MIN_CUSTOM_HEADER_WIDTH : MIN_COL_WIDTH;
 	return Math.max(MIN_COL_WIDTH, measureHeaderLabelWidth(label) + HEADER_CHROME_PX);
 }
-function getColumnSizingStyle(col) {
-	const w = `var(${colVar(col.id)})`;
-	const grow = col.flex ?? 0;
-	return {
-		flex: `${grow} 0 ${w}`,
-		width: w,
-		minWidth: getEffectiveMinWidth(col),
-		maxWidth: grow > 0 ? void 0 : col.maxWidth ?? DEFAULT_MAX_COL_WIDTH
-	};
-}
-function createGridSizingStyle(widths, totalWidth) {
-	const style = { "--grid-total-w": `${totalWidth}px` };
-	for (const [id, w] of widths) style[colVar(id)] = `${w}px`;
-	return style;
-}
-function applyDraggedColumnWidth(el, columnId, width, totalWidth) {
-	el.style.setProperty(colVar(columnId), `${width}px`);
-	el.style.setProperty("--grid-total-w", `${totalWidth}px`);
+function getEffectiveMaxWidth(col) {
+	return col.maxWidth ?? DEFAULT_MAX_COL_WIDTH;
 }
 function clampColumnWidth(col, width) {
-	const minWidth = getEffectiveMinWidth(col);
-	const maxWidth = col.maxWidth ?? DEFAULT_MAX_COL_WIDTH;
-	return Math.max(minWidth, Math.min(maxWidth, width));
+	return Math.max(getEffectiveMinWidth(col), Math.min(getEffectiveMaxWidth(col), width));
 }
 
 //#endregion
-exports.applyDraggedColumnWidth = applyDraggedColumnWidth;
+exports.DEFAULT_COL_WIDTH = DEFAULT_COL_WIDTH;
+exports.DEFAULT_MAX_COL_WIDTH = DEFAULT_MAX_COL_WIDTH;
 exports.clampColumnWidth = clampColumnWidth;
-exports.createGridSizingStyle = createGridSizingStyle;
-exports.getColumnSizingStyle = getColumnSizingStyle;
+exports.getEffectiveMaxWidth = getEffectiveMaxWidth;
 exports.getEffectiveMinWidth = getEffectiveMinWidth;
 //# sourceMappingURL=data-grid-sizing.js.map

package/dist/components/data-grid/data-grid-sizing.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-grid-sizing.js","names":[],"sources":["../../../src/components/data-grid/data-grid-sizing.ts"],"sourcesContent":["import type { CSSProperties } from \"react\";\nimport type { DataGridColumnDef } from \"./types\";\n\n// CSS variable names for column widths set on the grid container.\n// Cells read these via var(...) so a single setProperty during drag\n// resizes every cell in a column with zero React re-renders.\n\nfunction colVar(id: string): `--col-${string}` {\n  // Column ids flow into CSS custom-property names. Non-ident chars would\n  // break the cascade silently, so fail loud in dev. Consumers should stick\n  // to stable ascii-ident ids for every column.\n  if (process.env.NODE_ENV !== \"production\" && !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(id)) {\n    // eslint-disable-next-line no-console\n    console.warn(\n      `[DataGrid] column id ${JSON.stringify(id)} contains characters that are not safe in a CSS custom property name. Prefer ascii identifiers.`\n    );\n  }\n  return `--col-${id}`;\n}\n\n// When col.minWidth is not set, the effective minimum is derived from\n// the header label text width so the label is never clipped on resize.\n// Uses an offscreen canvas for zero-layout measurement; results are\n// cached per unique label string.\n\nconst MIN_COL_WIDTH = 20;\nconst MIN_CUSTOM_HEADER_WIDTH = 50;\n// Default upper bound on column width (both initial sizing + resize clamp).\n// Kept generous because consumers can override per-column via `col.maxWidth`.\nconst DEFAULT_MAX_COL_WIDTH = 800;\n// px-3 both sides + gap-1.5 + sort icon (h-3 w-3) + 2px rounding buffer\nconst HEADER_CHROME_PX = 12 + 12 + 6 + 12 + 2;\n\nlet measureContext: CanvasRenderingContext2D | null = null;\nconst headerWidthCache = new Map<string, number>();\n\nfunction measureHeaderLabelWidth(label: string): number {\n  const cached = headerWidthCache.get(label);\n  if (cached != null) {\n    return cached;\n  }\n\n  if (typeof document === \"undefined\") {\n    return 0;\n  }\n  if (measureContext == null) {\n    measureContext = document.createElement(\"canvas\").getContext(\"2d\");\n  }\n  if (measureContext == null) {\n    return 0;\n  }\n\n  // Match header cell: text-xs (12px) font-semibold (600) uppercase tracking-wider (0.05em)\n  measureContext.font = \"600 12px system-ui, -apple-system, sans-serif\";\n  const text = label.toUpperCase();\n  const letterSpacingPx = 0.05 * 12;\n  const width = Math.ceil(\n    measureContext.measureText(text).width + letterSpacingPx * text.length,\n  );\n\n  headerWidthCache.set(label, width);\n  return width;\n}\n\nexport function getEffectiveMinWidth<TRow>(col: DataGridColumnDef<TRow>): number {\n  if (col.minWidth != null) {\n    return col.minWidth;\n  }\n  const label = typeof col.header === \"string\" ? col.header : null;\n  if (label == null) {\n    return typeof col.header === \"function\" ? MIN_CUSTOM_HEADER_WIDTH : MIN_COL_WIDTH;\n  }\n  return Math.max(MIN_COL_WIDTH, measureHeaderLabelWidth(label) + HEADER_CHROME_PX);\n}\n\nexport function getColumnSizingStyle<TRow>(col: DataGridColumnDef<TRow>): CSSProperties {\n  const w = `var(${colVar(col.id)})`;\n  const grow = col.flex ?? 0;\n  return {\n    flex: `${grow} 0 ${w}`,\n    width: w,\n    minWidth: getEffectiveMinWidth(col),\n    maxWidth: grow > 0 ? undefined : (col.maxWidth ?? DEFAULT_MAX_COL_WIDTH),\n  };\n}\n\nexport function createGridSizingStyle(\n  widths: ReadonlyMap<string, number>,\n  totalWidth: number,\n): Record<string, string> {\n  const style: Record<string, string> = { \"--grid-total-w\": `${totalWidth}px` };\n  for (const [id, w] of widths) {\n    style[colVar(id)] = `${w}px`;\n  }\n  return style;\n}\n\nexport function applyDraggedColumnWidth(\n  el: HTMLElement,\n  columnId: string,\n  width: number,\n  totalWidth: number,\n) {\n  el.style.setProperty(colVar(columnId), `${width}px`);\n  el.style.setProperty(\"--grid-total-w\", `${totalWidth}px`);\n}\n\nexport function clampColumnWidth<TRow>(col: DataGridColumnDef<TRow>, width: number): number {\n  const minWidth = getEffectiveMinWidth(col);\n  const maxWidth = col.maxWidth ?? DEFAULT_MAX_COL_WIDTH;\n  return Math.max(minWidth, Math.min(maxWidth, width));\n}\n"],"mappings":";;;AAOA,SAAS,OAAO,IAA+B;AAI7C,KAAI,QAAQ,IAAI,aAAa,gBAAgB,CAAC,4BAA4B,KAAK,GAAG,CAEhF,SAAQ,KACN,wBAAwB,KAAK,UAAU,GAAG,CAAC,iGAC5C;AAEH,QAAO,SAAS;;AAQlB,MAAM,gBAAgB;AACtB,MAAM,0BAA0B;AAGhC,MAAM,wBAAwB;AAE9B,MAAM,mBAAmB;AAEzB,IAAI,iBAAkD;AACtD,MAAM,mCAAmB,IAAI,KAAqB;AAElD,SAAS,wBAAwB,OAAuB;CACtD,MAAM,SAAS,iBAAiB,IAAI,MAAM;AAC1C,KAAI,UAAU,KACZ,QAAO;AAGT,KAAI,OAAO,aAAa,YACtB,QAAO;AAET,KAAI,kBAAkB,KACpB,kBAAiB,SAAS,cAAc,SAAS,CAAC,WAAW,KAAK;AAEpE,KAAI,kBAAkB,KACpB,QAAO;AAIT,gBAAe,OAAO;CACtB,MAAM,OAAO,MAAM,aAAa;CAEhC,MAAM,QAAQ,KAAK,KACjB,eAAe,YAAY,KAAK,CAAC,QAFX,MAAO,KAE8B,KAAK,OACjE;AAED,kBAAiB,IAAI,OAAO,MAAM;AAClC,QAAO;;AAGT,SAAgB,qBAA2B,KAAsC;AAC/E,KAAI,IAAI,YAAY,KAClB,QAAO,IAAI;CAEb,MAAM,QAAQ,OAAO,IAAI,WAAW,WAAW,IAAI,SAAS;AAC5D,KAAI,SAAS,KACX,QAAO,OAAO,IAAI,WAAW,aAAa,0BAA0B;AAEtE,QAAO,KAAK,IAAI,eAAe,wBAAwB,MAAM,GAAG,iBAAiB;;AAGnF,SAAgB,qBAA2B,KAA6C;CACtF,MAAM,IAAI,OAAO,OAAO,IAAI,GAAG,CAAC;CAChC,MAAM,OAAO,IAAI,QAAQ;AACzB,QAAO;EACL,MAAM,GAAG,KAAK,KAAK;EACnB,OAAO;EACP,UAAU,qBAAqB,IAAI;EACnC,UAAU,OAAO,IAAI,SAAa,IAAI,YAAY;EACnD;;AAGH,SAAgB,sBACd,QACA,YACwB;CACxB,MAAM,QAAgC,EAAE,kBAAkB,GAAG,WAAW,KAAK;AAC7E,MAAK,MAAM,CAAC,IAAI,MAAM,OACpB,OAAM,OAAO,GAAG,IAAI,GAAG,EAAE;AAE3B,QAAO;;AAGT,SAAgB,wBACd,IACA,UACA,OACA,YACA;AACA,IAAG,MAAM,YAAY,OAAO,SAAS,EAAE,GAAG,MAAM,IAAI;AACpD,IAAG,MAAM,YAAY,kBAAkB,GAAG,WAAW,IAAI;;AAG3D,SAAgB,iBAAuB,KAA8B,OAAuB;CAC1F,MAAM,WAAW,qBAAqB,IAAI;CAC1C,MAAM,WAAW,IAAI,YAAY;AACjC,QAAO,KAAK,IAAI,UAAU,KAAK,IAAI,UAAU,MAAM,CAAC"}
+{"version":3,"file":"data-grid-sizing.js","names":[],"sources":["../../../src/components/data-grid/data-grid-sizing.ts"],"sourcesContent":["import type { DataGridColumnDef } from \"./types\";\n\nconst MIN_COL_WIDTH = 20;\nconst MIN_CUSTOM_HEADER_WIDTH = 50;\nexport const DEFAULT_MAX_COL_WIDTH = 800;\nexport const DEFAULT_COL_WIDTH = 150;\n\n// px-3 both sides + gap-1.5 + sort icon (h-3 w-3) + 2px rounding buffer\nconst HEADER_CHROME_PX = 12 + 12 + 6 + 12 + 2;\n\nlet measureContext: CanvasRenderingContext2D | null = null;\nconst headerWidthCache = new Map<string, number>();\n\nfunction measureHeaderLabelWidth(label: string): number {\n  const cached = headerWidthCache.get(label);\n  if (cached != null) return cached;\n  if (typeof document === \"undefined\") return 0;\n  if (measureContext == null) {\n    measureContext = document.createElement(\"canvas\").getContext(\"2d\");\n  }\n  if (measureContext == null) return 0;\n\n  // Match header cell: text-xs (12px) font-semibold uppercase tracking-wider (0.05em)\n  measureContext.font = \"600 12px system-ui, -apple-system, sans-serif\";\n  const text = label.toUpperCase();\n  const letterSpacingPx = 0.05 * 12;\n  const width = Math.ceil(\n    measureContext.measureText(text).width + letterSpacingPx * text.length,\n  );\n  headerWidthCache.set(label, width);\n  return width;\n}\n\n/** Effective minimum column width. When `col.minWidth` is unset, derive\n * one from the header label so it never gets clipped during resize. */\nexport function getEffectiveMinWidth<TRow>(col: DataGridColumnDef<TRow>): number {\n  if (col.minWidth != null) return col.minWidth;\n  const label = typeof col.header === \"string\" ? col.header : null;\n  if (label == null) {\n    return typeof col.header === \"function\" ? MIN_CUSTOM_HEADER_WIDTH : MIN_COL_WIDTH;\n  }\n  return Math.max(MIN_COL_WIDTH, measureHeaderLabelWidth(label) + HEADER_CHROME_PX);\n}\n\nexport function getEffectiveMaxWidth<TRow>(col: DataGridColumnDef<TRow>): number {\n  return col.maxWidth ?? DEFAULT_MAX_COL_WIDTH;\n}\n\nexport function clampColumnWidth<TRow>(col: DataGridColumnDef<TRow>, width: number): number {\n  return Math.max(getEffectiveMinWidth(col), Math.min(getEffectiveMaxWidth(col), width));\n}\n"],"mappings":";;;AAEA,MAAM,gBAAgB;AACtB,MAAM,0BAA0B;AAChC,MAAa,wBAAwB;AACrC,MAAa,oBAAoB;AAGjC,MAAM,mBAAmB;AAEzB,IAAI,iBAAkD;AACtD,MAAM,mCAAmB,IAAI,KAAqB;AAElD,SAAS,wBAAwB,OAAuB;CACtD,MAAM,SAAS,iBAAiB,IAAI,MAAM;AAC1C,KAAI,UAAU,KAAM,QAAO;AAC3B,KAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,KAAI,kBAAkB,KACpB,kBAAiB,SAAS,cAAc,SAAS,CAAC,WAAW,KAAK;AAEpE,KAAI,kBAAkB,KAAM,QAAO;AAGnC,gBAAe,OAAO;CACtB,MAAM,OAAO,MAAM,aAAa;CAEhC,MAAM,QAAQ,KAAK,KACjB,eAAe,YAAY,KAAK,CAAC,QAFX,MAAO,KAE8B,KAAK,OACjE;AACD,kBAAiB,IAAI,OAAO,MAAM;AAClC,QAAO;;;;AAKT,SAAgB,qBAA2B,KAAsC;AAC/E,KAAI,IAAI,YAAY,KAAM,QAAO,IAAI;CACrC,MAAM,QAAQ,OAAO,IAAI,WAAW,WAAW,IAAI,SAAS;AAC5D,KAAI,SAAS,KACX,QAAO,OAAO,IAAI,WAAW,aAAa,0BAA0B;AAEtE,QAAO,KAAK,IAAI,eAAe,wBAAwB,MAAM,GAAG,iBAAiB;;AAGnF,SAAgB,qBAA2B,KAAsC;AAC/E,QAAO,IAAI,YAAY;;AAGzB,SAAgB,iBAAuB,KAA8B,OAAuB;AAC1F,QAAO,KAAK,IAAI,qBAAqB,IAAI,EAAE,KAAK,IAAI,qBAAqB,IAAI,EAAE,MAAM,CAAC"}

package/dist/components/data-grid/data-grid.d.ts

@@ -4,262 +4,42 @@ import * as react_jsx_runtime0 from "react/jsx-runtime";
 //#region src/components/data-grid/data-grid.d.ts
 declare function isDataGridInteractiveRowClickTarget(target: EventTarget | null): boolean;
 /**
- * Interactive table with sorting, quick search, pagination, selection,
- * and virtualization. Handles 10k+ rows smoothly. Pair with
- * `useDataSource` for client-side data; use an async `dataSource`
- * generator for server or infinite-scroll modes.
+ * Interactive table built on TanStack Table v8. Sorting, column sizing,
+ * visibility, ordering, and pinning are owned by the table instance; we
+ * layer virtualization, sticky toolbar/header/footer, infinite scroll,
+ * quick search, CSV export, and date-format toggling on top.
  *
- * ## Mental model (read this first — everything else depends on it)
- *
- * DataGrid is a **display** component. It does NOT sort, search, or
- * paginate your data directly — you own that, but `useDataSource` does
- * it for you. The `rows` prop is always the already-processed slice to
- * show. The grid tracks user intent in `state` (sort model, quick
- * search text, page index). You feed that state into `useDataSource`,
- * and its output goes back in as `rows`.
- *
- * `useDataSource` IS the processor. Given your full dataset and the
- * grid's state, it returns the searched + sorted + paginated rows
- * ready to pass to DataGrid. This is the ONLY correct pattern for
- * client-side data — do NOT pass a raw array to `rows`.
- *
- * ## Search (client vs async)
- *
- * - **Client mode** (`useDataSource` with `data`): a case-insensitive
- *   substring match across every column is applied automatically.
- *   Override the matcher with `matchRow` for fuzzy / weighted search,
- *   or disable by passing `matchRow: () => true`.
- * - **Async mode** (`useDataSource` with `dataSource`): `state.quickSearch`
- *   is forwarded to the generator as `params.quickSearch`. Same
- *   mechanism as `params.sorting` — a change triggers a refetch, and
- *   the generator is the "matching logic" (typically a WHERE / ILIKE
- *   clause in the backend query). The grid does NO client-side
- *   filtering in async mode.
- *
- * ## The canonical pattern
+ * The grid is display-only — it does not fetch or page data itself. Pair
+ * with `useDataSource` for client- or server-side data and pass the
+ * already-processed slice through `rows`.
  *
  * ```tsx
- * // 1. Columns — define OUTSIDE the component or inside a useMemo. Must be stable.
- * const columns = React.useMemo(() => [
- *   { id: "name", header: "Name", accessor: "name", width: 180, type: "string" },
- *   { id: "email", header: "Email", accessor: "email", width: 240, type: "string" },
- *   { id: "role", header: "Role", accessor: "role", width: 120, type: "singleSelect",
- *     valueOptions: [{ value: "admin", label: "Admin" }, { value: "member", label: "Member" }] },
- *   { id: "signUps", header: "Sign-ups", accessor: "signUps", width: 120, type: "number", align: "right",
- *     renderCell: ({ value }) => <span className="tabular-nums">{Number(value).toLocaleString()}</span> },
- * ], []);
- *
- * // 2. Grid state — one hook, initialized from the columns. NEVER build the state object by hand.
- * const [gridState, setGridState] = React.useState(() => createDefaultDataGridState(columns));
- *
- * // 3. Data source — wires your raw array through the grid state. ALWAYS call this
- * //    hook unconditionally at the top level (no if/return before it).
+ * const columns = useMemo(() => [...], []);
+ * const [gridState, setGridState] = useState(() => createDefaultDataGridState(columns));
  * const gridData = useDataSource({
- *   data: users,                   // your raw array (can be [] while loading)
- *   columns,
- *   getRowId: (row) => row.id,
+ *   data: users, columns, getRowId: (r) => r.id,
  *   sorting: gridState.sorting,
  *   quickSearch: gridState.quickSearch,
  *   pagination: gridState.pagination,
- *   paginationMode: "client",       // "client" | "server" | "infinite"
+ *   paginationMode: "client",
  * });
  *
- * // 4. Render — `rows` comes from gridData.rows, NOT from your raw array.
  * <DataGrid
  *   columns={columns}
  *   rows={gridData.rows}
- *   getRowId={(row) => row.id}
+ *   getRowId={(r) => r.id}
  *   totalRowCount={gridData.totalRowCount}
  *   isLoading={gridData.isLoading}
  *   state={gridState}
  *   onChange={setGridState}
- *   selectionMode="none"            // "none" | "single" | "multiple"
- *   maxHeight={480}
  * />
  * ```
  *
- * ## Iron rules (violating any of these breaks the grid)
- *
- * 1. The prop is `rows`, NOT `data`. There is no `data` prop on DataGrid.
- *    `data` belongs on `useDataSource`.
- * 2. `rows` is ALWAYS `gridData.rows`. Never pass your raw array to
- *    `rows` — the grid won't search, sort, or paginate it.
- * 3. Columns must be stable across renders. Define them outside the
- *    component or wrap in `React.useMemo`. A fresh columns array every
- *    render will reset sorting state.
- * 4. Initialize grid state with `createDefaultDataGridState(columns)`.
- *    Do NOT spell out the state object manually — you will miss fields
- *    and crash.
- * 5. `onChange` takes a `SetStateAction` (the setter you got from
- *    `useState`). Pass `setGridState` directly. Do NOT wrap it unless
- *    you know exactly what you're doing.
- * 6. Call `useDataSource` ONCE per grid, at the top level, before any
- *    early return. It contains hooks.
- * 7. `renderCell` is a PURE function of its context. NEVER call React
- *    hooks inside it (no `useState`, `useMemo`, `useEffect`, nothing).
- *    If you need derived data per row, compute it BEFORE the render —
- *    e.g. build a `Map<rowId, sparklineData>` in a `useMemo` and look
- *    it up in `renderCell`.
- * 8. `toolbar` accepts `false` (hide it) or a render function
- *    `(ctx) => ReactNode`. Anything else — `true`, `undefined`, a state
- *    variable — will either show the default toolbar or crash. If you
- *    just want the default toolbar, omit the prop entirely.
- * 9. The toolbar's search input writes to `state.quickSearch`. That
- *    value is consumed by `useDataSource` — client mode filters
- *    client-side, async mode forwards to the generator. Do NOT wire
- *    a separate "controlled" search prop, everything flows through
- *    grid state.
- *
- * ## renderCell — what you can and cannot do inside it
- *
- * ```tsx
- * // OK — pure rendering from ctx:
- * renderCell: ({ value }) => <span className="tabular-nums">{Number(value).toLocaleString()}</span>
- * renderCell: ({ row }) => <Badge variant={row.active ? "default" : "outline"}>{row.status}</Badge>
- *
- * // OK — looking up pre-computed data by row id:
- * // BEFORE the return, in the component body:
- * const sparklinesById = React.useMemo(() => {
- *   const m = new Map();
- *   for (const u of users) {
- *     m.set(u.id, u.recentActivity.map((n, i) => ({ ts: i, values: { primary: n } })));
- *   }
- *   return m;
- * }, [users]);
- * // Then inside the column def:
- * renderCell: ({ rowId }) => <MiniSparkline data={sparklinesById.get(rowId) ?? []} />
- *
- * // NOT OK — hooks inside renderCell:
- * renderCell: ({ row }) => {
- *   const [hovered, setHovered] = React.useState(false);  // ← crashes the grid
- *   const data = React.useMemo(() => ..., []);             // ← crashes the grid
- *   return ...;
- * }
- *
- * // NOT OK — embedding AnalyticsChart (or any other controlled, stateful chart) per row:
- * // AnalyticsChart owns its own state, tooltips, zoom, and virtualized data
- * // pipeline. Instantiating one per row is expensive and fights the grid's
- * // virtualizer. Don't do it.
- * ```
- *
- * ## Sparklines and mini-charts in cells — use raw Recharts
- *
- * If you want a tiny chart (sparkline, micro bar chart, trend line) inside
- * a cell, drop down to raw `Recharts.*` components — they are lightweight
- * and stateless, so they render cleanly per row without owning any state.
- * Read pre-computed points off the row (or off a `Map<rowId, points>` you
- * built in a `useMemo` above) and pass them directly to the Recharts
- * primitive. Do NOT wrap them in `DesignChartContainer` or
- * `DesignChartCard` inside a cell — those add chrome meant for full-size
- * charts.
- *
- * ```tsx
- * // OK — raw Recharts sparkline per row:
- * renderCell: ({ rowId }) => {
- *   const points = sparklinesById.get(rowId) ?? [];
- *   return (
- *     <Recharts.ResponsiveContainer width="100%" height={28}>
- *       <Recharts.LineChart data={points} margin={{ top: 2, right: 2, bottom: 2, left: 2 }}>
- *         <Recharts.Line type="monotone" dataKey="v" stroke="currentColor" strokeWidth={1.5} dot={false} isAnimationActive={false} />
- *       </Recharts.LineChart>
- *     </Recharts.ResponsiveContainer>
- *   );
- * }
- * ```
- *
- * Keep in-cell Recharts configs minimal: no axes, no tooltips, no animation
- * (`isAnimationActive={false}`), tight margins, fixed height. The goal is a
- * visual summary, not an interactive chart.
- *
- * ## State shape (from `createDefaultDataGridState`)
- *
- * ```ts
- * {
- *   sorting: [],                                        // { columnId, direction: "asc" | "desc" }[]
- *   quickSearch: "",                                    // search input text
- *   dateDisplay: "relative",                            // "relative" | "absolute"
- *   columnVisibility: {}, columnWidths: {...},
- *   columnPinning: { left: [], right: [] }, columnOrder: [...],
- *   pagination: { pageIndex: 0, pageSize: 50 },
- *   selection: { selectedIds: new Set(), anchorId: null },
- * }
- * ```
- *
- * Everything is updated through `setGridState` — the toolbar, header,
- * and footer all call it for you. You do not need to wire any of this
- * manually.
- *
- * ## Cell overflow and dynamic row heights
- *
- * By default every cell truncates its content with an ellipsis
- * (`cellOverflow: "truncate"`). For columns whose content should wrap
- * — badge lists, multi-line text, permission chips — set
- * `cellOverflow: "wrap"` on the column definition.
- *
- * To let rows grow to fit their tallest cell, set `rowHeight="auto"`
- * on the grid. The virtualizer will measure each row after render and
- * adjust scroll positions accordingly. Pair with `estimatedRowHeight`
- * (default 44) for better scroll-position estimates before measurement.
- *
- * ```tsx
- * // Columns: UUIDs truncate, auth-method badges wrap
- * const columns = [
- *   { id: "userId", header: "User ID", width: 130 },                      // default truncate
- *   { id: "auth", header: "Auth methods", width: 150, cellOverflow: "wrap",
- *     renderCell: ({ row }) => (
- *       <div className="flex flex-wrap gap-1">
- *         {row.authTypes.map((t) => <Badge key={t}>{t}</Badge>)}
- *       </div>
- *     ),
- *   },
- * ];
- *
- * <DataGrid columns={columns} rowHeight="auto" estimatedRowHeight={48} ... />
- * ```
- *
- * With a fixed numeric `rowHeight` (the default), `cellOverflow: "wrap"`
- * still lets content wrap within the row, but anything exceeding the
- * fixed height is clipped. This is useful when you want controlled
- * wrapping without variable row heights.
- *
- * ## Height and scrolling
- *
- * DataGrid is NOT a card. It has no border, rounded corners, or shadow of
- * its own. Wrap it in whatever chrome you want — a `DesignCard`, a section,
- * or just raw layout. The grid itself fills its parent's height via
- * `h-full`.
- *
- * How the grid gets its height (pick ONE):
- * 1. Bounded parent — put the grid inside a flex/grid container with a
- *    definite height (e.g. `flex-1 min-h-0` inside a page-filling flex
- *    column). The grid stretches to that height and scrolls its body.
- * 2. `maxHeight` prop — pass a number (pixels) or CSS string
- *    (`"480px"`, `"60vh"`, `"100%"`). The grid caps at that size and
- *    scrolls its body.
- * 3. Unbounded — omit `maxHeight` and let the parent grow freely. The
- *    grid renders at its full content height and the page scrolls. Fine
- *    for small lists; bad UX for thousands of rows.
- *
- * The toolbar, header, and footer are always `shrink-0`; only the body
- * scrolls. You do NOT need to subtract toolbar/footer heights from
- * `maxHeight` — the grid's internal flex layout handles that.
- *
- * ## When to use what
- *
- * - Simple static list, < 20 rows, no interaction → use a plain table component instead.
- * - Interactive table, sortable + searchable, any size → `DataGrid` +
- *   `useDataSource` with `paginationMode: "client"`.
- * - Infinite scroll over a huge dataset you fetch in pages → `dataSource` async
- *   generator + `paginationMode: "infinite"`. Only reach for this if you actually
- *   need pagination over a remote source. For anything that fits in memory,
- *   `"client"` is simpler and faster.
- *
- * ## Features you get for free
- *
- * Quick search, sortable columns (shift-click for multi-sort), column
- * visibility toggle, column resize, CSV export, virtualized rendering
- * for 10k+ rows, keyboard navigation, and a relative/absolute date
- * toggle for `date` / `dateTime` columns.
+ * Iron rules:
+ * - `rows` is always `gridData.rows`, never your raw array.
+ * - Columns must be stable (define outside the component or wrap in `useMemo`).
+ * - Initialize state with `createDefaultDataGridState(columns)`.
+ * - `renderCell` must be a pure function — no React hooks inside.
  */
 declare function DataGrid<TRow>(props: DataGridProps<TRow>): react_jsx_runtime0.JSX.Element;
 //#endregion

package/dist/components/data-grid/data-grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-grid.d.ts","names":[],"sources":["../../../src/components/data-grid/data-grid.tsx"],"mappings":";;;;iBAsKgB,mCAAA,CAAoC,MAAA,EAAQ,WAAA;;;AAA5D;;;;;AA+sBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,QAAA,MAAA,CAAe,KAAA,EAAO,aAAA,CAAc,IAAA,IAAK,kBAAA,CAAA,GAAA,CAAA,OAAA"}
+{"version":3,"file":"data-grid.d.ts","names":[],"sources":["../../../src/components/data-grid/data-grid.tsx"],"mappings":";;;;iBAmEgB,mCAAA,CAAoC,MAAA,EAAQ,WAAA;;;AAA5D;;;;;AAohBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,QAAA,MAAA,CAAe,KAAA,EAAO,aAAA,CAAc,IAAA,IAAK,kBAAA,CAAA,GAAA,CAAA,OAAA"}