@djangocfg/widget-data 0.1.1

package/src/DataGrid/index.ts

@@ -0,0 +1,34 @@
+'use client';
+
+export {
+  DataGridProvider,
+  useDataGridContext,
+} from './context/DataGridContext';
+export type {
+  DataGridContextValue,
+  DataGridProviderProps,
+} from './context/DataGridContext';
+
+export {
+  DataGrid,
+  DataGridHeader,
+  DataGridRow,
+  DataGridCell,
+  DataGridPagination,
+} from './parts';
+
+export type {
+  DataGridProps,
+  DataGridColumn,
+  DataGridSortState,
+  DataGridFilterState,
+  DataGridPaginationState,
+  DataGridSelectionMode,
+  DataGridRowId,
+  SortDirection,
+} from './types';
+
+// The dynamic-import wrapper. Exported here because the subpath resolves to
+// this barrel: in the retired ui-tools `lazy.tsx` was reachable from no declared export,
+// so `LazyDataGrid` was dead code for every tool but `JsonTree`.
+export { LazyDataGrid } from './lazy';

package/src/DataGrid/lazy.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { createLazyComponent, LoadingFallback } from '@djangocfg/widget-kit/lazy';
+import type { DataGridProps } from './types';
+
+export const LazyDataGrid = createLazyComponent<DataGridProps<unknown>>(
+  () => import('./parts/DataGrid').then((m) => ({ default: m.DataGrid })),
+  {
+    displayName: 'LazyDataGrid',
+    fallback: <LoadingFallback minHeight={300} text="Loading data grid…" />,
+  },
+);
+
+// Re-export light surface synchronously
+export * from './types';
+export {
+  DataGridProvider,
+  useDataGridContext,
+} from './context/DataGridContext';
+export type {
+  DataGridContextValue,
+  DataGridProviderProps,
+} from './context/DataGridContext';

package/src/DataGrid/parts/DataGrid.tsx

@@ -0,0 +1,125 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { ScrollArea } from '@djangocfg/ui-core/components';
+
+import type { DataGridProps } from '../types';
+import { DataGridProvider } from '../context/DataGridContext';
+import { DataGridHeader } from './DataGridHeader';
+import { DataGridRow } from './DataGridRow';
+import { DataGridPagination } from './DataGridPagination';
+
+export function DataGrid<T>(props: DataGridProps<T>) {
+  const {
+    data,
+    columns,
+    getRowId,
+    selectionMode,
+    initialSelectedIds,
+    onSelectionChange,
+    sort,
+    onSortChange,
+    initialSort,
+    filters,
+    onFilterChange,
+    initialFilters,
+    pagination,
+    onPaginationChange,
+    initialPagination,
+    pageSizeOptions,
+    loading,
+    emptyMessage,
+    getRowClassName,
+    onRowClick,
+    onRowDoubleClick,
+    stickyHeader = true,
+    className,
+    style,
+  } = props;
+
+  return (
+    <DataGridProvider<T>
+      data={data}
+      columns={columns}
+      getRowId={getRowId}
+      selectionMode={selectionMode}
+      initialSelectedIds={initialSelectedIds}
+      onSelectionChange={onSelectionChange}
+      sort={sort}
+      onSortChange={onSortChange}
+      initialSort={initialSort}
+      filters={filters}
+      onFilterChange={onFilterChange}
+      initialFilters={initialFilters}
+      pagination={pagination}
+      onPaginationChange={onPaginationChange}
+      initialPagination={initialPagination}
+      pageSizeOptions={pageSizeOptions}
+      loading={loading}
+      emptyMessage={emptyMessage}
+      getRowClassName={getRowClassName}
+      onRowClick={onRowClick}
+      onRowDoubleClick={onRowDoubleClick}
+      stickyHeader={stickyHeader}
+    >
+      <DataGridShell className={className} style={style} />
+    </DataGridProvider>
+  );
+}
+DataGrid.displayName = 'DataGrid';
+
+function DataGridShell({ className, style }: { className?: string; style?: React.CSSProperties }) {
+  return (
+    <div
+      data-slot="data-grid"
+      className={cn('flex flex-col gap-2 rounded-sm border border-border bg-background', className)}
+      style={style}
+    >
+      <ScrollArea className="w-full" viewportClassName="max-h-[60vh]">
+        <table className="w-full caption-bottom text-sm">
+          <DataGridHeader />
+          <tbody className="[&_tr:last-child]:border-0">
+            <DataGridRows />
+          </tbody>
+        </table>
+      </ScrollArea>
+      <DataGridPagination />
+    </div>
+  );
+}
+
+function DataGridRows() {
+  const { rows, getRowId, loading, emptyMessage } = useDataGridContext();
+
+  if (loading) {
+    return (
+      <tr>
+        <td colSpan={999} className="p-8 text-center text-muted-foreground">
+          Loading…
+        </td>
+      </tr>
+    );
+  }
+
+  if (rows.length === 0) {
+    return (
+      <tr>
+        <td colSpan={999} className="p-8 text-center text-muted-foreground">
+          {emptyMessage}
+        </td>
+      </tr>
+    );
+  }
+
+  return (
+    <>
+      {rows.map((row, index) => (
+        <DataGridRow key={String(getRowId(row))} row={row} index={index} />
+      ))}
+    </>
+  );
+}
+
+// Ambient import for JSX usage
+import { useDataGridContext } from '../context/DataGridContext';

package/src/DataGrid/parts/DataGridCell.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { DataGridColumn } from '../types';
+
+interface DataGridCellProps<T> {
+  column: DataGridColumn<T>;
+  row: T;
+}
+
+export function DataGridCell<T>({ column, row }: DataGridCellProps<T>) {
+  const value = (row as Record<string, unknown>)[column.key];
+
+  const content = column.cell ? column.cell(row) : value != null ? String(value) : null;
+
+  return (
+    <td
+      className={cn(
+        'p-2 align-middle',
+        column.align === 'center' && 'text-center',
+        column.align === 'right' && 'text-right'
+      )}
+    >
+      {content}
+    </td>
+  );
+}
+DataGridCell.displayName = 'DataGridCell';

package/src/DataGrid/parts/DataGridHeader.tsx

@@ -0,0 +1,111 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { ArrowUp, ArrowDown, ArrowUpDown } from 'lucide-react';
+
+import { useDataGridContext } from '../context/DataGridContext';
+import { DataGridCell } from './DataGridCell';
+
+export function DataGridHeader() {
+  const { columns, selectionMode, selectAllVisible, isSelected, rows, getRowId, stickyHeader } =
+    useDataGridContext();
+
+  const allVisibleSelected = rows.length > 0 && rows.every((r) => isSelected(getRowId(r)));
+
+  return (
+    <thead
+      className={cn(
+        '[&_tr]:border-b',
+        stickyHeader && 'sticky top-0 z-10 bg-background'
+      )}
+    >
+      <tr className="border-b transition-colors hover:bg-muted/50">
+        {selectionMode === 'multiple' && (
+          <th className="h-10 px-2 text-left align-middle font-medium text-muted-foreground w-10">
+            <input
+              type="checkbox"
+              checked={allVisibleSelected}
+              onChange={selectAllVisible}
+              className="h-4 w-4 rounded border-border accent-primary"
+              aria-label="Select all visible rows"
+            />
+          </th>
+        )}
+        {selectionMode === 'single' && <th className="w-10" />}
+        {columns.map((col) => (
+          <DataGridHeaderCell key={col.key} column={col} />
+        ))}
+      </tr>
+      <DataGridFilterRow />
+    </thead>
+  );
+}
+DataGridHeader.displayName = 'DataGridHeader';
+
+function DataGridHeaderCell({ column }: { column: { key: string; header: React.ReactNode; sortable?: boolean; align?: 'left' | 'center' | 'right'; width?: string | number; minWidth?: string | number; maxWidth?: string | number } }) {
+  const { sort, setSort } = useDataGridContext();
+  const isSorted = sort.key === column.key;
+
+  const style: React.CSSProperties = {};
+  if (column.width) style.width = column.width;
+  if (column.minWidth) style.minWidth = column.minWidth;
+  if (column.maxWidth) style.maxWidth = column.maxWidth;
+
+  return (
+    <th
+      className={cn(
+        'h-10 px-2 text-left align-middle font-medium text-muted-foreground',
+        column.align === 'center' && 'text-center',
+        column.align === 'right' && 'text-right',
+        column.sortable && 'cursor-pointer select-none'
+      )}
+      style={style}
+      onClick={() => column.sortable && setSort(column.key)}
+      data-sort={isSorted ? sort.direction : undefined}
+    >
+      <span className="inline-flex items-center gap-1">
+        {column.header}
+        {column.sortable && (
+          <span className="inline-flex text-muted-foreground/60">
+            {isSorted && sort.direction === 'asc' && <ArrowUp className="h-3.5 w-3.5" />}
+            {isSorted && sort.direction === 'desc' && <ArrowDown className="h-3.5 w-3.5" />}
+            {!isSorted && <ArrowUpDown className="h-3.5 w-3.5" />}
+          </span>
+        )}
+      </span>
+    </th>
+  );
+}
+
+function DataGridFilterRow() {
+  const { columns, filters, setFilter, selectionMode } = useDataGridContext();
+  const hasFilterable = columns.some((c) => c.filterable);
+
+  if (!hasFilterable) return null;
+
+  return (
+    <tr className="border-b transition-colors">
+      {selectionMode !== 'none' && <td className="p-2" />}
+      {columns.map((col) => (
+        <td key={col.key} className="p-2">
+          {col.filterable ? (
+            <input
+              type="text"
+              value={filters[col.key] ?? ''}
+              onChange={(e) => setFilter(col.key, e.target.value)}
+              placeholder="Filter…"
+              className={cn(
+                'w-full rounded-sm border border-input bg-background px-2 py-1 text-xs',
+                'placeholder:text-muted-foreground',
+                'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring'
+              )}
+            />
+          ) : (
+            <span />
+          )}
+        </td>
+      ))}
+    </tr>
+  );
+}

package/src/DataGrid/parts/DataGridPagination.tsx

@@ -0,0 +1,105 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight } from 'lucide-react';
+
+import { useDataGridContext } from '../context/DataGridContext';
+
+export function DataGridPagination() {
+  const { pagination, setPage, setPageSize, totalRows, pageCount, pageSizeOptions } =
+    useDataGridContext();
+
+  const start = totalRows === 0 ? 0 : (pagination.page - 1) * pagination.pageSize + 1;
+  const end = Math.min(pagination.page * pagination.pageSize, totalRows);
+
+  return (
+    <div
+      data-slot="data-grid-pagination"
+      className="flex flex-col items-center justify-between gap-2 px-4 py-2 sm:flex-row"
+    >
+      <span className="text-sm text-muted-foreground">
+        {start}-{end} of {totalRows}
+      </span>
+
+      <div className="flex items-center gap-2">
+        <select
+          value={pagination.pageSize}
+          onChange={(e) => setPageSize(Number(e.target.value))}
+          className={cn(
+            'h-8 rounded-sm border border-input bg-background px-2 text-sm',
+            'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring'
+          )}
+          aria-label="Rows per page"
+        >
+          {pageSizeOptions.map((size) => (
+            <option key={size} value={size}>
+              {size} / page
+            </option>
+          ))}
+        </select>
+
+        <div className="flex items-center gap-1">
+          <PaginationButton
+            onClick={() => setPage(1)}
+            disabled={pagination.page <= 1}
+            aria-label="First page"
+          >
+            <ChevronsLeft className="h-4 w-4" />
+          </PaginationButton>
+          <PaginationButton
+            onClick={() => setPage(pagination.page - 1)}
+            disabled={pagination.page <= 1}
+            aria-label="Previous page"
+          >
+            <ChevronLeft className="h-4 w-4" />
+          </PaginationButton>
+
+          <span className="px-2 text-sm tabular-nums">
+            {pagination.page} / {pageCount}
+          </span>
+
+          <PaginationButton
+            onClick={() => setPage(pagination.page + 1)}
+            disabled={pagination.page >= pageCount}
+            aria-label="Next page"
+          >
+            <ChevronRight className="h-4 w-4" />
+          </PaginationButton>
+          <PaginationButton
+            onClick={() => setPage(pageCount)}
+            disabled={pagination.page >= pageCount}
+            aria-label="Last page"
+          >
+            <ChevronsRight className="h-4 w-4" />
+          </PaginationButton>
+        </div>
+      </div>
+    </div>
+  );
+}
+DataGridPagination.displayName = 'DataGridPagination';
+
+function PaginationButton({
+  children,
+  onClick,
+  disabled,
+  ...props
+}: React.ButtonHTMLAttributes<HTMLButtonElement>) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      className={cn(
+        'inline-flex h-8 w-8 items-center justify-center rounded-sm border border-input bg-background text-sm',
+        'hover:bg-accent hover:text-accent-foreground',
+        'disabled:pointer-events-none disabled:opacity-50',
+        'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring'
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}

package/src/DataGrid/parts/DataGridRow.tsx

@@ -0,0 +1,84 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useDataGridContext } from '../context/DataGridContext';
+import { DataGridCell } from './DataGridCell';
+
+interface DataGridRowProps<T> {
+  row: T;
+  index: number;
+}
+
+export function DataGridRow<T>({ row, index }: DataGridRowProps<T>) {
+  const {
+    columns,
+    getRowId,
+    selectionMode,
+    select,
+    isSelected,
+    getRowClassName,
+    onRowClick,
+    onRowDoubleClick,
+  } = useDataGridContext<T>();
+
+  const id = getRowId(row);
+  const selected = isSelected(id);
+
+  const handleClick = React.useCallback(() => {
+    if (selectionMode !== 'none') {
+      select(id);
+    }
+    onRowClick?.(row);
+  }, [id, selectionMode, select, onRowClick, row]);
+
+  const handleDoubleClick = React.useCallback(() => {
+    onRowDoubleClick?.(row);
+  }, [onRowDoubleClick, row]);
+
+  return (
+    <tr
+      data-slot="data-grid-row"
+      data-id={String(id)}
+      data-selected={selected ? '' : undefined}
+      data-state={selected ? 'selected' : undefined}
+      className={cn(
+        'border-b transition-colors hover:bg-muted/50',
+        selected && 'bg-muted',
+        getRowClassName?.(row, index)
+      )}
+      onClick={handleClick}
+      onDoubleClick={handleDoubleClick}
+    >
+      {selectionMode === 'multiple' && (
+        <td className="p-2 align-middle">
+          <input
+            type="checkbox"
+            checked={selected}
+            onChange={() => select(id)}
+            className="h-4 w-4 rounded border-border accent-primary"
+            aria-label={`Select row ${String(id)}`}
+            onClick={(e) => e.stopPropagation()}
+          />
+        </td>
+      )}
+      {selectionMode === 'single' && (
+        <td className="p-2 align-middle">
+          <input
+            type="radio"
+            checked={selected}
+            onChange={() => select(id)}
+            className="h-4 w-4 border-border accent-primary"
+            aria-label={`Select row ${String(id)}`}
+            onClick={(e) => e.stopPropagation()}
+          />
+        </td>
+      )}
+      {columns.map((col) => (
+        <DataGridCell key={col.key} column={col} row={row} />
+      ))}
+    </tr>
+  );
+}
+DataGridRow.displayName = 'DataGridRow';

package/src/DataGrid/parts/index.ts

@@ -0,0 +1,7 @@
+'use client';
+
+export { DataGrid } from './DataGrid';
+export { DataGridHeader } from './DataGridHeader';
+export { DataGridRow } from './DataGridRow';
+export { DataGridCell } from './DataGridCell';
+export { DataGridPagination } from './DataGridPagination';

package/src/DataGrid/types.ts

@@ -0,0 +1,95 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+export type DataGridRowId = string | number;
+
+export type SortDirection = 'asc' | 'desc' | null;
+
+export interface DataGridColumn<T = unknown> {
+  key: string;
+  header: ReactNode;
+  width?: string | number;
+  minWidth?: string | number;
+  maxWidth?: string | number;
+  sortable?: boolean;
+  filterable?: boolean;
+  align?: 'left' | 'center' | 'right';
+  /** Custom cell renderer. Receives the row data. */
+  cell?: (row: T) => ReactNode;
+  /** Custom filter predicate for this column. */
+  filterFn?: (row: T, filterValue: string) => boolean;
+}
+
+export interface DataGridSortState {
+  key: string | null;
+  direction: SortDirection;
+}
+
+export interface DataGridFilterState {
+  [columnKey: string]: string;
+}
+
+export interface DataGridPaginationState {
+  page: number;
+  pageSize: number;
+}
+
+export type DataGridSelectionMode = 'none' | 'single' | 'multiple';
+
+export interface DataGridProps<T = unknown> {
+  /** Row data */
+  data: T[];
+  /** Column definitions */
+  columns: DataGridColumn<T>[];
+  /** Unique row id getter */
+  getRowId: (row: T) => DataGridRowId;
+
+  /** Selection behaviour. Default: 'none' */
+  selectionMode?: DataGridSelectionMode;
+  /** Initially selected row ids */
+  initialSelectedIds?: DataGridRowId[];
+  /** Triggered when selection changes */
+  onSelectionChange?: (selectedIds: DataGridRowId[]) => void;
+
+  /** Controlled sort state */
+  sort?: DataGridSortState;
+  /** Called when sort changes */
+  onSortChange?: (sort: DataGridSortState) => void;
+  /** Default sort */
+  initialSort?: DataGridSortState;
+
+  /** Controlled filter state */
+  filters?: DataGridFilterState;
+  /** Called when filters change */
+  onFilterChange?: (filters: DataGridFilterState) => void;
+  /** Default filters */
+  initialFilters?: DataGridFilterState;
+
+  /** Controlled pagination */
+  pagination?: DataGridPaginationState;
+  /** Called when pagination changes */
+  onPaginationChange?: (pagination: DataGridPaginationState) => void;
+  /** Default pagination */
+  initialPagination?: DataGridPaginationState;
+  /** Available page sizes. Default: [10, 25, 50, 100] */
+  pageSizeOptions?: number[];
+
+  /** Enable column resizing. Default: false */
+  resizable?: boolean;
+  /** Sticky header. Default: true */
+  stickyHeader?: boolean;
+  /** Loading state */
+  loading?: boolean;
+  /** Empty state message */
+  emptyMessage?: ReactNode;
+  /** Row className getter */
+  getRowClassName?: (row: T, index: number) => string;
+  /** Called when a row is clicked */
+  onRowClick?: (row: T) => void;
+  /** Called when a row is double-clicked */
+  onRowDoubleClick?: (row: T) => void;
+
+  className?: string;
+  style?: React.CSSProperties;
+}

package/src/DataTable/README.md

@@ -0,0 +1,42 @@
+# DataTable
+
+Lighter sibling of `DataGrid`. Same sort / filter / pagination / selection model, but no column resizing, no sticky header, no `width`/`minWidth`/`maxWidth` per column — use when you want a plain semantic `<table>` for read-heavy lists. For resizable / sticky-header grids reach for `DataGrid` instead.
+
+```tsx
+import { DataTable } from '@djangocfg/ui-tools/data-table';
+
+<DataTable
+  data={invoices}
+  columns={[
+    { key: 'number', header: '#',      sortable: true },
+    { key: 'client', header: 'Client', filterable: true },
+    { key: 'total',  header: 'Total',  align: 'right' },
+  ]}
+  getRowId={(inv) => inv.id}
+  onRowClick={openInvoice}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `T[]` | — | Row data. |
+| `columns` | `DataTableColumn<T>[]` | — | Column defs (`key`, `header`, `cell?`, `sortable?`, `filterable?`, `align?`, `filterFn?`). |
+| `getRowId` | `(row: T) => string \| number` | — | Stable row id. |
+| `selectionMode` | `'none' \| 'single' \| 'multiple'` | `'none'` | Selection behaviour. |
+| `initialSelectedIds` / `onSelectionChange` | `RowId[]` / `(ids) => void` | — | Uncontrolled selection. |
+| `sort` / `onSortChange` / `initialSort` | `DataTableSortState` | — | Controlled or uncontrolled sort. |
+| `filters` / `onFilterChange` / `initialFilters` | `DataTableFilterState` | — | Per-column text filters. |
+| `pagination` / `onPaginationChange` / `initialPagination` | `DataTablePaginationState` | — | Controlled or uncontrolled pagination. |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Page-size choices. |
+| `loading` | `boolean` | `false` | Loading state. |
+| `emptyMessage` | `ReactNode` | — | Rendered when `data` is empty. |
+| `getRowClassName` | `(row, i) => string` | — | Per-row class hook. |
+| `onRowClick` / `onRowDoubleClick` | `(row) => void` | — | Row event handlers. |
+
+Composable parts (`DataTableProvider`, `DataTableHeader`, `DataTableRow`, `DataTablePagination`) are exported for custom compositions.
+
+---
+
+Adapted from jalcoui (MIT).