@stackframe/dashboard-ui-components 2.8.84 → 2.8.85

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

@@ -0,0 +1,233 @@
+import { DataGridProps } from "./types.js";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/components/data-grid/data-grid.d.ts
+/**
+ * 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.
+ *
+ * ## 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
+ *
+ * ```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 gridData = useDataSource({
+ *   data: users,                   // your raw array (can be [] while loading)
+ *   columns,
+ *   getRowId: (row) => row.id,
+ *   sorting: gridState.sorting,
+ *   quickSearch: gridState.quickSearch,
+ *   pagination: gridState.pagination,
+ *   paginationMode: "client",       // "client" | "server" | "infinite"
+ * });
+ *
+ * // 4. Render — `rows` comes from gridData.rows, NOT from your raw array.
+ * <DataGrid
+ *   columns={columns}
+ *   rows={gridData.rows}
+ *   getRowId={(row) => row.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.
+ *
+ * ## 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.
+ */
+declare function DataGrid<TRow>(props: DataGridProps<TRow>): react_jsx_runtime0.JSX.Element;
+//#endregion
+export { DataGrid };
+//# sourceMappingURL=data-grid.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"data-grid.d.ts","names":[],"sources":["../../../src/components/data-grid/data-grid.tsx"],"mappings":";;;;;;;AA2wBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,QAAA,MAAA,CAAe,KAAA,EAAO,aAAA,CAAc,IAAA,IAAK,kBAAA,CAAA,GAAA,CAAA,OAAA"}