@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/combobox/styles.css

@@ -0,0 +1,419 @@
+/*
+ * Combobox styles (Select and MultiSelect).
+ *
+ * Tokens read the shared --gbs-* variables when they are set on an ancestor
+ * (set them on :root to theme every component at once) and fall back to the
+ * same default palette otherwise. Rules are unlayered: they beat a framework
+ * reset on specificity, and lose to anything you pass through `className`.
+ * With Tailwind v4, import this file after the framework and inside its
+ * components layer - see the README.
+ */
+
+.cb-root {
+  --cb-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+  --cb-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --cb-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --cb-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --cb-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+  --cb-input-bg: var(--gbs-input-bg, var(--dg-input-bg, light-dark(#ffffff, #121216)));
+  --cb-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+  --cb-accent-fg: var(--gbs-accent-fg, var(--dg-accent-fg, light-dark(#ffffff, #0b1220)));
+  --cb-accent-soft: var(--gbs-accent-soft, var(--dg-accent-soft, light-dark(#eff6ff, #172554)));
+  --cb-accent-strong: var(--gbs-accent-strong, var(--dg-accent-strong, light-dark(#1d4ed8, #bfdbfe)));
+  --cb-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --cb-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+  --cb-shadow: var(--gbs-shadow, var(--dg-shadow, 0 10px 30px -8px light-dark(rgb(0 0 0 / 0.18), rgb(0 0 0 / 0.6))));
+  --cb-radius: var(--gbs-radius, var(--dg-radius, 8px));
+  --cb-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --cb-height: 36px;
+  --cb-px: 10px;
+
+  color-scheme: inherit;
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  width: 100%;
+  min-width: 0;
+  font-size: var(--cb-font-size);
+  line-height: 1.4;
+  color: var(--cb-fg);
+}
+
+:where(.dark, [data-theme="dark"]) .cb-root {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) .cb-root {
+  color-scheme: light;
+}
+
+:where(.cb-root, .cb-popover) *,
+:where(.cb-root, .cb-popover) *::before,
+:where(.cb-root, .cb-popover) *::after {
+  box-sizing: border-box;
+}
+
+.cb-root[data-size="sm"] {
+  --cb-height: 30px;
+  --cb-font-size: 12px;
+  --cb-px: 8px;
+}
+.cb-root[data-size="lg"] {
+  --cb-height: 44px;
+  --cb-font-size: 14px;
+  --cb-px: 12px;
+}
+
+.cb-label {
+  font-weight: 500;
+}
+.cb-label[data-required]::after {
+  content: " *";
+  color: var(--cb-danger);
+}
+.cb-description {
+  color: var(--cb-muted);
+  font-size: 0.92em;
+}
+.cb-error {
+  color: var(--cb-danger);
+  font-size: 0.92em;
+}
+
+/* -------------------------------------------------------------- trigger */
+
+.cb-control {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  min-height: var(--cb-height);
+  padding: 3px var(--cb-px);
+  border: 1px solid var(--cb-border);
+  border-radius: var(--cb-radius);
+  background: var(--cb-input-bg);
+  color: inherit;
+  font: inherit;
+  text-align: start;
+  cursor: pointer;
+}
+.cb-control:hover:not([data-disabled]) {
+  border-color: color-mix(in oklab, var(--cb-border), var(--cb-fg) 25%);
+}
+.cb-control:focus-visible,
+.cb-root[data-state="open"] .cb-control {
+  outline: 2px solid var(--cb-focus);
+  outline-offset: -1px;
+}
+.cb-control[data-invalid] {
+  border-color: var(--cb-danger);
+}
+.cb-control[data-invalid]:focus-visible,
+.cb-root[data-invalid][data-state="open"] .cb-control {
+  outline-color: var(--cb-danger);
+}
+.cb-control[data-disabled] {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.cb-value {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.cb-placeholder {
+  color: var(--cb-muted);
+}
+.cb-value-icon {
+  display: inline-flex;
+  margin-inline-end: 6px;
+  vertical-align: -2px;
+  color: var(--cb-muted);
+}
+
+.cb-tags {
+  display: flex;
+  flex: 1 1 auto;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+}
+.cb-tag {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  max-width: 100%;
+  padding-inline: 8px 3px;
+  border-radius: 999px;
+  background: var(--cb-accent-soft);
+  color: var(--cb-accent-strong);
+  font-size: 0.92em;
+  line-height: 20px;
+}
+.cb-tag-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.cb-tag-remove {
+  display: inline-grid;
+  place-items: center;
+  width: 16px;
+  height: 16px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+.cb-tag-remove:hover {
+  background: color-mix(in oklab, var(--cb-accent-strong), transparent 85%);
+}
+.cb-tag-overflow {
+  color: var(--cb-muted);
+  font-size: 0.92em;
+  white-space: nowrap;
+}
+
+.cb-actions {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 2px;
+  color: var(--cb-muted);
+}
+.cb-icon-button {
+  display: inline-grid;
+  place-items: center;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+.cb-icon-button:hover {
+  background: var(--cb-hover);
+  color: var(--cb-fg);
+}
+.cb-icon-button:focus-visible {
+  outline: 2px solid var(--cb-focus);
+  outline-offset: 1px;
+}
+.cb-chevron {
+  transition: transform 120ms ease;
+}
+.cb-root[data-state="open"] .cb-chevron {
+  transform: rotate(180deg);
+}
+@media (prefers-reduced-motion: reduce) {
+  .cb-chevron {
+    transition: none;
+  }
+}
+
+/* -------------------------------------------------------------- popover */
+
+.cb-popover {
+  position: fixed;
+  inset: auto;
+  margin: 0;
+  padding: 0;
+  overflow: hidden;
+  border: 1px solid var(--cb-border);
+  border-radius: var(--cb-radius);
+  background: var(--cb-bg);
+  color: var(--cb-fg);
+  box-shadow: var(--cb-shadow);
+  font-size: var(--cb-font-size);
+}
+.cb-search {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 10px;
+  border-bottom: 1px solid var(--cb-border);
+  color: var(--cb-muted);
+}
+.cb-search input {
+  width: 100%;
+  min-width: 0;
+  border: 0;
+  outline: 0;
+  background: transparent;
+  color: var(--cb-fg);
+  font: inherit;
+}
+
+.cb-list {
+  position: relative;
+  overflow: auto;
+  overscroll-behavior: contain;
+  padding: 4px;
+  outline: none;
+  scrollbar-width: var(--gbs-scrollbar-width, thin);
+  scrollbar-color: var(--gbs-scrollbar-thumb, light-dark(#c4c4ca, #3f3f46))
+    var(--gbs-scrollbar-track, transparent);
+}
+.cb-list:focus-visible {
+  outline: 2px solid var(--cb-focus);
+  outline-offset: -2px;
+}
+.cb-list[data-virtual] .cb-item,
+.cb-list[data-virtual] .cb-group {
+  position: absolute;
+  inset-inline: 4px;
+}
+
+.cb-group {
+  display: flex;
+  align-items: center;
+  padding: 6px 8px 2px;
+  color: var(--cb-muted);
+  font-size: 0.85em;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.cb-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  padding: 6px 8px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: start;
+  cursor: pointer;
+}
+.cb-item[data-active] {
+  background: var(--cb-hover);
+}
+.cb-item[data-selected] {
+  color: var(--cb-accent-strong);
+  font-weight: 500;
+}
+.cb-item[data-disabled] {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+.cb-item-check {
+  flex: none;
+  width: 16px;
+  color: var(--cb-accent);
+  opacity: 0;
+}
+.cb-item[data-selected] .cb-item-check {
+  opacity: 1;
+}
+.cb-item-icon {
+  flex: none;
+  display: inline-flex;
+  color: var(--cb-muted);
+}
+.cb-item-body {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+.cb-item-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.cb-item-description {
+  overflow: hidden;
+  color: var(--cb-muted);
+  font-size: 0.9em;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.cb-mark {
+  background: color-mix(in oklab, var(--cb-accent), transparent 82%);
+  border-radius: 2px;
+  color: inherit;
+  font-weight: 600;
+}
+
+.cb-empty,
+.cb-status {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  padding: 16px 8px;
+  color: var(--cb-muted);
+}
+.cb-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 4px 6px;
+  border-top: 1px solid var(--cb-border);
+}
+.cb-link-button {
+  padding: 4px 6px;
+  border: 0;
+  border-radius: 4px;
+  background: none;
+  color: var(--cb-accent);
+  font: inherit;
+  cursor: pointer;
+}
+.cb-link-button:hover {
+  background: var(--cb-hover);
+}
+.cb-link-button:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+.cb-footer-count {
+  color: var(--cb-muted);
+}
+
+.cb-spinner {
+  animation: cb-spin 0.7s linear infinite;
+}
+@keyframes cb-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .cb-spinner {
+    animation-duration: 2s;
+  }
+}
+
+.cb-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+@media (forced-colors: active) {
+  .cb-item[data-active] {
+    outline: 1px solid Highlight;
+  }
+  .cb-mark {
+    background: Highlight;
+    color: HighlightText;
+  }
+}

package/source/components/data-grid/README.md

@@ -0,0 +1,233 @@
+# DataGrid
+
+A virtualized data grid for React 19 with no runtime dependencies besides React.
+Works in Vite/SPA apps and in the Next.js App Router.
+
+- **Fast by design:** rows and columns are virtualized; state lives in an
+  external store with per-row subscriptions, so selecting a row or moving focus
+  re-renders only the rows involved; column resizing rewrites CSS variables
+  without rendering; filtering and sorting run at low priority via
+  `useDeferredValue`.
+- **Features:** typed columns, multi-column sort, typed column filters, global
+  search, pagination, row selection (single, multiple, shift-range), column
+  resize / reorder (drag or menu) / pin / hide, inline editing with validation and
+  async saves, CSV / Excel / PDF export, clipboard copy, density, i18n, RTL, dark
+  mode, WAI-ARIA grid keyboard navigation.
+- **Client or server mode:** let the grid sort/filter/paginate, or receive a
+  query and fetch pages yourself.
+
+## Setup
+
+Import the stylesheet once (e.g. in your root CSS or layout):
+
+```css
+@import "../component-lib/data-grid/styles.css";
+```
+
+or from JS: `import "component-lib/data-grid/styles.css";`
+
+## Basic usage
+
+```tsx
+import { createColumnHelper, DataGrid } from "component-lib/data-grid";
+
+interface Employee { id: number; name: string; salary: number; startDate: string; active: boolean }
+
+const col = createColumnHelper<Employee>();
+
+// Define columns outside the component (or memoize them).
+const columns = [
+  col.field("id", { header: "ID", type: "number", width: 80, pin: "left" }),
+  col.field("name", { width: 200 }),
+  col.field("salary", { type: "number", format: (v) => `$${v.toLocaleString()}` }),
+  col.field("startDate", { type: "date" }),
+  col.field("active", { type: "boolean" }),
+];
+
+export function Employees({ data }: { data: Employee[] }) {
+  return <DataGrid data={data} columns={columns} getRowId="id" enableRowSelection height={600} />;
+}
+```
+
+`createColumnHelper` infers the value type for `cell`, `format`, `validate` and
+`sortFn`. Plain `ColumnDef<T>[]` objects work too.
+
+### Stable inputs
+
+The grid memoizes on the identity of `data`, `columns` and `getRowId`. Keep
+them stable: define columns at module level or with `useMemo`, and pass
+`getRowId` as a property name (`getRowId="id"`). With React Compiler enabled,
+inline values are memoized for you.
+
+## Columns
+
+| Option | Purpose |
+| --- | --- |
+| `field` / `accessor` / `id` | Where the value comes from. Display-only columns need just `id` and `cell`. |
+| `header`, `width`, `minWidth`, `maxWidth`, `align` | Presentation. |
+| `type` | `string` (default), `number`, `date`, `boolean`. Drives filter operators, sorting, alignment, editors and Excel cell types. |
+| `options` | `{ label, value }[]` for enum columns: "is any of" filter, select editor, label display. |
+| `format(value, row)` | Display text. Also used by search, CSV, PDF and copy. |
+| `cell(ctx)` | Custom renderer. Clicks on buttons/inputs inside cells don't trigger `onRowClick`. |
+| `pin`, `hidden` | Initial pin side / visibility. |
+| `sortable`, `filterable`, `resizable`, `reorderable`, `pinnable`, `hideable`, `searchable` | Per-column feature switches (default `true`). |
+| `sortFn`, `filterFn` | Custom comparison / matching. |
+| `editable`, `editor`, `validate` | Inline editing (below). |
+| `exportable`, `exportValue(row)` | Export control. |
+| `headerClassName`, `cellClassName` | Styling hooks. |
+
+## Server mode
+
+```tsx
+const [query, setQuery] = useState<GridQuery>(initialQuery);
+const { data, isFetching } = useQuery({ queryKey: ["orders", query], queryFn: () => fetchOrders(query) });
+
+<DataGrid
+  mode="server"
+  data={data?.rows ?? []}
+  rowCount={data?.total ?? 0}
+  loading={isFetching}
+  columns={columns}
+  initialState={initialQuery}
+  onQueryChange={setQuery}
+/>
+```
+
+`onQueryChange` receives `{ sorting, filters, globalFilter, pagination }`
+whenever one of them changes. Changing filters, search or sorting resets to the
+first page. The previous rows stay visible while `loading`.
+
+The framework-free core (`component-lib/data-grid/core`) exports `filterRows`,
+`sortRows` and `paginate`, so a Node or Next.js route handler can apply exactly
+the same semantics on the server.
+
+## State
+
+All grid state can be controlled or left internal:
+
+```ts
+interface GridState {
+  sorting; filters; globalFilter; pagination; rowSelection;
+  columnOrder; columnVisibility; columnSizing; columnPinning; density;
+}
+```
+
+- `initialState` seeds internal state.
+- `state` controls any subset of keys; the grid then calls `onStateChange(next, prev)`
+  instead of updating those keys itself.
+- Example: persist column layout with
+  `onStateChange={(s) => save(pick(s, ["columnOrder", "columnSizing", "columnPinning", "columnVisibility"]))}`.
+
+## Editing
+
+```ts
+col.field("salary", {
+  type: "number",
+  editable: (row) => !row.locked,
+  validate: (v) => (v < 0 ? "Must be positive" : null),
+});
+
+<DataGrid onCellEdit={async ({ rowId, columnId, value }) => { await save(rowId, columnId, value); }} />
+```
+
+Start editing with double-click, Enter or F2. Enter commits and moves down,
+Tab commits and moves right, and Escape cancels. The grid never mutates `data`:
+update it in `onCellEdit`. If `onCellEdit` returns a promise, the cell shows the
+pending value until it settles, and a rejection marks the cell invalid.
+Custom editors: `editor: (props) => <MyInput value={props.value} onChange={props.onChange} onBlur={() => props.commit()} />`.
+
+## Imperative API
+
+```tsx
+const api = useRef<GridApi<Employee>>(null);
+<DataGrid ref={api} ... />
+
+api.current?.setFilter("status", { operator: "in", value: ["active"] });
+api.current?.exportExcel({ scope: "selected", fileName: "people" });
+api.current?.focusCell(0, "name");
+```
+
+Methods include `toggleSort`, `setSorting`, `setFilter`, `clearFilters`,
+`setGlobalFilter`, `setPageIndex`, `setPageSize`, `toggleRowSelected`,
+`toggleAllRowsSelected`, `getSelectedRows`, `setColumnVisibility`,
+`setColumnWidth`, `pinColumn`, `moveColumn`, `resetColumns`, `scrollToRow`,
+`focusCell`, `startEditing`, `getRows`, `exportCsv`, `exportExcel`, `exportPdf`,
+`print` and `copyToClipboard`.
+
+## Export
+
+Export code is split into chunks loaded on first use.
+
+| Format | Notes |
+| --- | --- |
+| CSV | UTF-8 with BOM (opens correctly in Excel). Cells starting with `= + - @` are prefixed with `'` to prevent formula injection. |
+| Excel | Real `.xlsx`: typed numbers, booleans and dates, bold frozen header, auto-filter, column widths. Written without a library. |
+| PDF | Writes a real `.pdf` and downloads it: chosen paper size and orientation, a repeated header row, page numbers and your own header/footer bands. Uses the standard PDF fonts, so text must be Latin-1. |
+| Print | `api.print()` opens the browser's print dialog instead, for paper or for text the standard fonts cannot encode. |
+
+Scopes: `filtered` (default), `all`, `selected`, `page`, or pass `rows`, e.g. a
+full result set fetched from the server.
+
+## Keyboard
+
+| Keys | Action |
+| --- | --- |
+| Arrows, Home/End, Ctrl+Home/End, PageUp/PageDown | Move between cells (header row included). |
+| Enter (header) | Sort; Shift+Enter adds to the sort. |
+| Alt+↓ or the Menu key (header) | Open the column menu. |
+| Enter / F2 | Edit the cell, or focus the widget inside a custom cell. |
+| Space | Toggle row selection (Shift for a range). |
+| Ctrl/Cmd+A | Select all rows. |
+| Ctrl/Cmd+C | Copy selected rows (TSV) or the active cell. |
+| Escape | Cancel editing / leave a widget inside a cell. |
+
+## Theming
+
+Styles live in `@layer components`, so Tailwind utilities passed via
+`classNames` / `className` win. Override the `--dg-*` variables for a theme:
+
+```css
+.dg-root { --dg-accent: #7c3aed; --dg-radius: 12px; --dg-font-size: 14px; }
+```
+
+Colors follow the page's `color-scheme`. A `.dark` or `[data-theme="dark"]`
+ancestor forces a scheme. State is exposed as attributes for styling:
+`data-selected`, `data-active`, `data-editing`, `data-pinned`, `data-density`,
+and `aria-sort` on header cells.
+
+Slots for `classNames`: `root`, `toolbar`, `viewport`, `header`, `headerCell`,
+`row`, `cell`, `pagination`.
+
+## Next.js
+
+Components carry `"use client"`; import `DataGrid` from a Server Component and
+pass serializable props (`data`, `initialState`). Column definitions contain
+functions, so define them in a client module. For server mode, fetch in a
+Server Component or Route Handler using `core` functions, and sync the query to
+the URL (e.g. with `nuqs`) through `state` + `onQueryChange`.
+
+## Known limits
+
+- Rows have a fixed height (per density or `rowHeight`); variable-height rows are not supported.
+- Updates from the grid's store render synchronously; heavy client-side filtering is
+  deferred with `useDeferredValue`, but a single filter pass over very large data
+  (1M+ rows) still runs on the main thread. For that scale, use server mode or a worker.
+- Row grouping, tree data and pivoting are not implemented.
+
+## Migrating from `component-lib/datagrid`
+
+| Old prop | New |
+| --- | --- |
+| `dataSource` (array) | `data` |
+| `dataSource` (URL string) | Fetch in your app; pass `data` (the grid no longer fetches). |
+| `lazy` + `pageSettings.totalCount` | `mode="server"` + `rowCount` |
+| `pageSettings.pageNumber` / `pageSize` | `initialState={{ pagination: { pageIndex: 0, pageSize } }}` |
+| `enableSearch`, `enableExcelExport`, `enablePdfExport` | `toolbar={{ search, export }}` |
+| `selectAll`, `onSelectRow` | `enableRowSelection`, `onStateChange` / `api.getSelectedRows()` |
+| `rowChange` / `onRowClick` | `onRowClick` |
+| `pageStatus` / `onPageChange`, `onFilterChange`, `onSearchChange` | `onQueryChange` |
+| `initialFilters`, `initialSearchParam` | `initialState={{ filters, globalFilter }}` |
+| `isFetching` | `loading` |
+| `column.headerText`, `column.template` | `header`, `cell` |
+| `grid*Class` props | `classNames` slots |
+| `ref.goToPage(n)` etc. | `ref.setPageIndex(n)` and the API above |