rastack 0.0.26 → 0.0.27

package/components/data-table/DataTable.tsx

@@ -0,0 +1,267 @@
+import React, { useEffect } from "react";
+import { tokens } from "../style";
+import type { TableQuery } from "../types";
+import { Table, THead, TBody, Tr, Th, Td } from "../primitives/table";
+import { Input, Button } from "../primitives/controls";
+import { Spinner } from "../primitives/misc";
+import { formatCell } from "./columns";
+import {
+  useDataTable,
+  type DataTableModel,
+  type DataTableOptions,
+} from "./use-data-table";
+
+/** Inject the row-interaction CSS once (`:hover` can't be an inline style). */
+let dtCssInjected = false;
+function useDataTableCss(): void {
+  useEffect(() => {
+    if (dtCssInjected || typeof document === "undefined") return;
+    dtCssInjected = true;
+    const el = document.createElement("style");
+    el.setAttribute("data-rastack-ui", "");
+    el.textContent =
+      ".rastack-dt tbody tr[data-clickable='true']{cursor:pointer}" +
+      ".rastack-dt tbody tr[data-clickable='true']:hover{background:var(--color-surface-alt,#f2f5fb)}";
+    document.head.appendChild(el);
+  }, []);
+}
+
+export interface DataTableProps<
+  TRow extends Record<string, unknown>,
+> extends DataTableOptions<TRow> {
+  /** The list hook result driving the table (`useListX(...)`, or any `TableQuery`). */
+  query: TableQuery<TRow>;
+  /** Row click handler; makes rows look/behave interactive. */
+  onRowClick?: (row: TRow, index: number) => void;
+  /** Show the search box when the hook supports searching. Default `true`. */
+  searchable?: boolean;
+  searchPlaceholder?: string;
+  /** Rendered when there are no rows. */
+  emptyMessage?: React.ReactNode;
+  /** Stable React key per row. Defaults to `row.id` then the index. */
+  rowKey?: (row: TRow, index: number) => React.Key;
+  /** Total-control escape hatch: receives the headless model, you render everything. */
+  children?: (model: DataTableModel<TRow>) => React.ReactNode;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/**
+ * A data table that renders itself from a list hook.
+ *
+ * ```tsx
+ * <DataTable query={useListAirports({ options: { pageSize: 20 } })} />
+ * ```
+ *
+ * Columns come from your `columns` prop, else the server `header`, else the
+ * first row's keys. Sorting, search and pagination light up automatically when
+ * the hook exposes them and stay hidden otherwise, so the same component drives
+ * both REST and local-sync entities.
+ */
+export function DataTable<TRow extends Record<string, unknown>>(
+  props: DataTableProps<TRow>,
+): React.JSX.Element {
+  const {
+    query,
+    columns: columnsOption,
+    sortable,
+    onRowClick,
+    searchable = true,
+    searchPlaceholder = "Search…",
+    emptyMessage = "No records.",
+    rowKey,
+    children,
+    style,
+    className,
+  } = props;
+
+  useDataTableCss();
+  const model = useDataTable<TRow>(query, { columns: columnsOption, sortable });
+
+  if (children) return <>{children(model)}</>;
+
+  const { columns, rows, isLoading, isEmpty, error, search, sort, pagination } =
+    model;
+  const colSpan = Math.max(columns.length, 1);
+
+  const keyOf = (row: TRow, index: number): React.Key => {
+    if (rowKey) return rowKey(row, index);
+    const id = (row as Record<string, unknown>).id;
+    return id != null ? String(id) : index;
+  };
+
+  const messageRow = (content: React.ReactNode) => (
+    <Tr>
+      <Td
+        colSpan={colSpan}
+        style={{
+          textAlign: "center",
+          color: tokens.color.textMuted,
+          padding: tokens.space.xl,
+        }}
+      >
+        {content}
+      </Td>
+    </Tr>
+  );
+
+  return (
+    <div
+      className={className}
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: tokens.space.md,
+        ...style,
+      }}
+    >
+      {search && searchable ? (
+        <div style={{ maxWidth: 320 }}>
+          <Input
+            size="sm"
+            value={search.value}
+            placeholder={searchPlaceholder}
+            onChange={(e) => search.setValue(e.target.value)}
+            aria-label="Search"
+          />
+        </div>
+      ) : null}
+
+      <div
+        style={{
+          overflowX: "auto",
+          border: `1px solid ${tokens.color.border}`,
+          borderRadius: tokens.radius.lg,
+        }}
+      >
+        <Table className="rastack-dt">
+          <THead>
+            <Tr>
+              {columns.map((col) => {
+                const direction =
+                  col.sortable && sort ? sort.directionOf(col.key) : undefined;
+                const canSort = Boolean(col.sortable && sort);
+                return (
+                  <Th
+                    key={col.key}
+                    align={col.align}
+                    sortable={canSort}
+                    sortDirection={direction}
+                    style={col.width != null ? { width: col.width } : undefined}
+                    onClick={canSort ? () => sort!.by(col.key) : undefined}
+                  >
+                    {col.header}
+                  </Th>
+                );
+              })}
+            </Tr>
+          </THead>
+          <TBody>
+            {error
+              ? messageRow(
+                  <span style={{ color: tokens.color.danger }}>
+                    {error instanceof Error
+                      ? error.message
+                      : "Something went wrong."}
+                  </span>,
+                )
+              : isLoading && rows.length === 0
+                ? messageRow(
+                    <span
+                      style={{
+                        display: "inline-flex",
+                        alignItems: "center",
+                        gap: tokens.space.sm,
+                      }}
+                    >
+                      <Spinner /> Loading…
+                    </span>,
+                  )
+                : isEmpty
+                  ? messageRow(emptyMessage)
+                  : rows.map((row, index) => (
+                      <Tr
+                        key={keyOf(row, index)}
+                        data-clickable={onRowClick ? "true" : undefined}
+                        onClick={
+                          onRowClick ? () => onRowClick(row, index) : undefined
+                        }
+                      >
+                        {columns.map((col) => {
+                          const value = (row as Record<string, unknown>)[
+                            col.key
+                          ];
+                          return (
+                            <Td key={col.key} align={col.align}>
+                              {col.render
+                                ? col.render(row, value)
+                                : formatCell(value)}
+                            </Td>
+                          );
+                        })}
+                      </Tr>
+                    ))}
+          </TBody>
+        </Table>
+      </div>
+
+      {pagination ? (
+        <div
+          style={{
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "space-between",
+            gap: tokens.space.md,
+            flexWrap: "wrap",
+          }}
+        >
+          <span
+            style={{
+              fontSize: "0.8125rem",
+              color: tokens.color.textMuted,
+              fontFamily: tokens.font.sans,
+            }}
+          >
+            {pagination.itemCount > 0
+              ? `${pagination.itemCount} record${pagination.itemCount === 1 ? "" : "s"}`
+              : ""}
+          </span>
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: tokens.space.sm,
+            }}
+          >
+            <Button
+              size="sm"
+              variant="outline"
+              disabled={!pagination.canPrev}
+              onClick={pagination.prev}
+            >
+              Previous
+            </Button>
+            <span
+              style={{
+                fontSize: "0.8125rem",
+                color: tokens.color.textMuted,
+                fontFamily: tokens.font.sans,
+              }}
+            >
+              Page {pagination.current}
+              {pagination.count ? ` of ${pagination.count}` : ""}
+            </span>
+            <Button
+              size="sm"
+              variant="outline"
+              disabled={!pagination.canNext}
+              onClick={pagination.next}
+            >
+              Next
+            </Button>
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/components/data-table/columns.ts

@@ -0,0 +1,117 @@
+/**
+ * Column resolution + cell formatting for the data table — the pure core.
+ *
+ * "Render correctly based on the data fetched" comes down to: where do the
+ * columns come from, and how is a raw value shown? Both are decided here, with
+ * no React or DOM, so they are unit tested directly.
+ *
+ * Column source, in priority order:
+ *   1. an explicit `columns` prop (author knows best);
+ *   2. the server envelope's `header` (`{ key, name }[]`) — the DRF-shaped list
+ *      response carries these, and `IListQuery` surfaces them as `.header`;
+ *   3. otherwise, the keys of the first row.
+ */
+
+import type React from "react";
+import { humanizeKey, type CellAlign } from "../util";
+
+export { humanizeKey };
+
+export interface DataTableColumn<TRow = Record<string, unknown>> {
+  /** The row property this column reads (also its React key). */
+  key: string;
+  /** The header label. Defaults to a humanised `key`. */
+  header: React.ReactNode;
+  /** Cell alignment. Defaults to `"left"`. */
+  align?: CellAlign;
+  /** Whether this column can be sorted. The table also requires the hook to expose sorting. */
+  sortable?: boolean;
+  /** Custom cell renderer. Receives the row and the resolved value (`row[key]`). */
+  render?: (row: TRow, value: unknown) => React.ReactNode;
+  /** Optional fixed column width. */
+  width?: string | number;
+}
+
+/** A caller-supplied column: everything optional but `key`. */
+export type DataTableColumnInput<TRow = Record<string, unknown>> = Partial<
+  DataTableColumn<TRow>
+> & {
+  key: string;
+};
+
+export interface ResolveColumnsInput<TRow> {
+  /** Explicit columns — highest priority. */
+  columns?: DataTableColumnInput<TRow>[];
+  /** Server-provided headers (`IListQuery.header`). */
+  header?: { key: string; name: string }[];
+  /** The rows, used only to infer columns from the first row's keys. */
+  rows?: TRow[];
+  /** Default `sortable` for inferred columns (the table sets this from hook capability). */
+  sortableByDefault?: boolean;
+}
+
+/** Fill a partial column with defaults. */
+function normalizeColumn<TRow>(
+  col: DataTableColumnInput<TRow>,
+  sortableByDefault: boolean,
+): DataTableColumn<TRow> {
+  return {
+    key: col.key,
+    header: col.header ?? humanizeKey(col.key),
+    align: col.align,
+    sortable: col.sortable ?? sortableByDefault,
+    render: col.render,
+    width: col.width,
+  };
+}
+
+/**
+ * Decide the columns to render from the (optional) explicit columns, the server
+ * header, or the first row. Returns an empty array only when nothing is known
+ * yet (no columns, no header, no rows).
+ */
+export function resolveColumns<TRow extends Record<string, unknown>>(
+  input: ResolveColumnsInput<TRow>,
+): DataTableColumn<TRow>[] {
+  const sortableByDefault = input.sortableByDefault ?? false;
+
+  if (input.columns && input.columns.length > 0) {
+    return input.columns.map((c) => normalizeColumn(c, sortableByDefault));
+  }
+
+  if (input.header && input.header.length > 0) {
+    return input.header.map((h) =>
+      normalizeColumn({ key: h.key, header: h.name }, sortableByDefault),
+    );
+  }
+
+  const first = input.rows?.find((r) => r != null && typeof r === "object");
+  if (first) {
+    return Object.keys(first).map((key) =>
+      normalizeColumn({ key }, sortableByDefault),
+    );
+  }
+
+  return [];
+}
+
+/**
+ * Default rendering for a raw cell value when a column has no custom `render`.
+ * Kept deliberately conservative: booleans read as Yes/No, nullish as an em
+ * dash, Dates localise, objects/arrays serialise compactly, everything else is
+ * stringified.
+ */
+export function formatCell(value: unknown): string {
+  if (value == null) return "—";
+  if (typeof value === "boolean") return value ? "Yes" : "No";
+  if (value instanceof Date) return value.toLocaleString();
+  if (typeof value === "object") {
+    try {
+      const json = JSON.stringify(value);
+      return json.length > 80 ? `${json.slice(0, 77)}…` : json;
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}

package/components/data-table/use-data-table.ts

@@ -0,0 +1,141 @@
+/**
+ * `useDataTable` — the headless table model.
+ *
+ * Give it any `TableQuery` (a REST `IListQuery` or a sync list result) and it
+ * returns a flat, render-ready model: resolved columns, the rows, loading/empty
+ * flags, and — only when the underlying hook supports them — normalized
+ * `search`, `sort` and `pagination` handles. `<DataTable>` renders this; you can
+ * also consume it directly to build a fully custom table (the "headless" path).
+ *
+ * The model assembly is pure (no hooks inside), so it is unit tested via
+ * {@link buildDataTableModel}.
+ */
+
+import { useMemo } from "react";
+import type { TableQuery } from "../types";
+import {
+  resolveColumns,
+  type DataTableColumn,
+  type DataTableColumnInput,
+} from "./columns";
+
+export interface DataTableSearch {
+  value: string;
+  setValue: (value: string) => void;
+}
+
+export interface DataTableSort {
+  /** Toggle the sort on a column (asc → desc → off, per the hook). */
+  by: (key: string) => void;
+  /** The current direction for a column, or `undefined` if unsorted. */
+  directionOf: (key: string) => "asc" | "desc" | undefined;
+}
+
+export interface DataTablePagination {
+  current: number;
+  count: number;
+  size: number;
+  itemCount: number;
+  next: () => void;
+  prev: () => void;
+  setSize: (size: number) => void;
+  canPrev: boolean;
+  canNext: boolean;
+}
+
+export interface DataTableModel<TRow = Record<string, unknown>> {
+  columns: DataTableColumn<TRow>[];
+  rows: TRow[];
+  isLoading: boolean;
+  isEmpty: boolean;
+  error: unknown;
+  /** Present only when the hook exposes searching. */
+  search?: DataTableSearch;
+  /** Present only when the hook exposes sorting. */
+  sort?: DataTableSort;
+  /** Present only when the hook exposes pagination. */
+  pagination?: DataTablePagination;
+}
+
+export interface DataTableOptions<TRow = Record<string, unknown>> {
+  /** Explicit columns (labels, order, alignment, custom `render`). Overrides inference. */
+  columns?: DataTableColumnInput<TRow>[];
+  /** Force sortable headers on/off. Defaults to on whenever the hook supports sorting. */
+  sortable?: boolean;
+}
+
+/** Pure model assembly — see {@link useDataTable}. */
+export function buildDataTableModel<TRow extends Record<string, unknown>>(
+  query: TableQuery<TRow>,
+  options: DataTableOptions<TRow> = {},
+): DataTableModel<TRow> {
+  const rows = query.data ?? [];
+  const hasSorting = Boolean(query.sorting);
+  const sortableByDefault = hasSorting && (options.sortable ?? true);
+
+  const columns = resolveColumns<TRow>({
+    columns: options.columns,
+    header: query.header,
+    rows,
+    sortableByDefault,
+  });
+
+  const isLoading = query.isLoading ?? query.isReady === false;
+  const isEmpty = !isLoading && rows.length === 0;
+  const error =
+    query.error ?? (query.isError ? new Error("Request failed") : undefined);
+
+  const model: DataTableModel<TRow> = {
+    columns,
+    rows,
+    isLoading,
+    isEmpty,
+    error,
+  };
+
+  if (query.searching) {
+    const s = query.searching;
+    model.search = {
+      value: s.searchText ?? "",
+      // The hook treats `undefined` as "no search"; map an empty box to that.
+      setValue: (value) => s.setSearchText(value === "" ? undefined : value),
+    };
+  }
+
+  if (query.sorting) {
+    const so = query.sorting;
+    model.sort = {
+      by: (key) => so.sortField(key as never),
+      directionOf: (key) => so.getSortingDirection(key as never),
+    };
+  }
+
+  if (query.pagination) {
+    const p = query.pagination;
+    model.pagination = {
+      current: p.currentPage,
+      count: p.pageCount,
+      size: p.pageSize,
+      itemCount: p.itemCount,
+      next: p.nextPage,
+      prev: p.previousPage,
+      setSize: p.setPageSize,
+      canPrev: p.currentPage > 1,
+      canNext: p.currentPage < p.pageCount,
+    };
+  }
+
+  return model;
+}
+
+/** React hook wrapper around {@link buildDataTableModel} (memoized on the query + options). */
+export function useDataTable<TRow extends Record<string, unknown>>(
+  query: TableQuery<TRow>,
+  options: DataTableOptions<TRow> = {},
+): DataTableModel<TRow> {
+  return useMemo(
+    () => buildDataTableModel(query, options),
+    // The query object identity changes as react-query state advances.
+    [query, options.columns, options.sortable],
+  );
+}

package/components/index.ts

@@ -0,0 +1,77 @@
+/**
+ * `rastack/components` — headless, token-styled React components for the stack.
+ *
+ * Two layers:
+ *
+ *  1. **Primitives** (`Button`, `Input`, `Select`, `Table`, `Field`, …) — the
+ *     shadcn-style building blocks. Every one is painted purely from design
+ *     tokens (`../style.ts` → `var(--…)`), so dropping them inside a
+ *     `<ThemeProvider>` (from `rastack/theme`) themes them automatically,
+ *     light/dark included, with zero hard-coded colours.
+ *
+ *  2. **Data-connected components** — the differentiator. Hand a component a
+ *     framework hook and it renders itself from the data and its datatypes:
+ *       - `<DataTable query={useListAirports(...)} />` builds columns from the
+ *         server header (or the rows), and lights up search / sortable headers /
+ *         pagination when the hook supports them.
+ *       - `<AutoForm form={useUpdateAirportForm(...)} />` renders one control per
+ *         field, chosen from the datatype the form hook derives from the write
+ *         schema (checkbox for booleans, date picker for dates, select for
+ *         enums, …).
+ *     Each also exposes a headless hook (`useDataTable`, `useAutoForm`) and a
+ *     render-prop escape hatch for full control.
+ *
+ * Web/DOM-first (the components render HTML and style via CSS variables). On
+ * React Native, drive your own views from the headless hooks + `useTokenValue`.
+ */
+
+// Styling surface (token → CSS-var helpers, the `tokens` map, variant styles).
+export * from "./style";
+export { humanizeKey } from "./util";
+
+// Structural contracts for the connected components.
+export type {
+  TableQuery,
+  AutoFormLike,
+  AutoFormField,
+  ReturnedHeader,
+} from "./types";
+
+// Primitives.
+export * from "./primitives";
+
+// Data table.
+export { DataTable, type DataTableProps } from "./data-table/DataTable";
+export {
+  useDataTable,
+  buildDataTableModel,
+  type DataTableModel,
+  type DataTableOptions,
+  type DataTableSearch,
+  type DataTableSort,
+  type DataTablePagination,
+} from "./data-table/use-data-table";
+export {
+  resolveColumns,
+  formatCell,
+  type DataTableColumn,
+  type DataTableColumnInput,
+  type ResolveColumnsInput,
+} from "./data-table/columns";
+
+// Auto form.
+export { AutoForm, type AutoFormProps } from "./auto-form/AutoForm";
+export {
+  useAutoForm,
+  buildAutoFormModel,
+  type AutoFormModel,
+  type AutoFormFieldModel,
+} from "./auto-form/use-auto-form";
+export {
+  inputKindForFieldType,
+  resolveFieldSpecs,
+  type AutoFormInputKind,
+  type AutoFormOptions,
+  type AutoFormFieldConfig,
+  type AutoFormFieldSpec,
+} from "./auto-form/fields";