rastack 0.0.26 → 0.0.28

package/components/primitives/table.tsx

@@ -0,0 +1,147 @@
+import React from "react";
+import { tokens, mergeStyles } from "../style";
+import type { CellAlign } from "../util";
+
+export type { CellAlign };
+
+export interface TableProps extends React.TableHTMLAttributes<HTMLTableElement> {}
+
+/** A token-styled `<table>`. Compose with the head/body/row/cell primitives, or drive it with `<DataTable>`. */
+export function Table({
+  style,
+  children,
+  ...rest
+}: TableProps): React.JSX.Element {
+  const base: React.CSSProperties = {
+    width: "100%",
+    borderCollapse: "collapse",
+    fontFamily: tokens.font.sans,
+    fontSize: "0.875rem",
+    color: tokens.color.text,
+    textAlign: "left",
+  };
+  return (
+    <table style={mergeStyles(base, style)} {...rest}>
+      {children}
+    </table>
+  );
+}
+
+export function THead({
+  style,
+  children,
+  ...rest
+}: React.HTMLAttributes<HTMLTableSectionElement>): React.JSX.Element {
+  return (
+    <thead style={style} {...rest}>
+      {children}
+    </thead>
+  );
+}
+
+export function TBody({
+  style,
+  children,
+  ...rest
+}: React.HTMLAttributes<HTMLTableSectionElement>): React.JSX.Element {
+  return (
+    <tbody style={style} {...rest}>
+      {children}
+    </tbody>
+  );
+}
+
+export interface TrProps extends React.HTMLAttributes<HTMLTableRowElement> {}
+
+export function Tr({ style, children, ...rest }: TrProps): React.JSX.Element {
+  return (
+    <tr style={style} {...rest}>
+      {children}
+    </tr>
+  );
+}
+
+export interface ThProps extends React.ThHTMLAttributes<HTMLTableCellElement> {
+  align?: CellAlign;
+  sortable?: boolean;
+  /** The current sort on this column, for the indicator. */
+  sortDirection?: "asc" | "desc";
+}
+
+/** A header cell. When `sortable`, shows a direction indicator and a pointer cursor. */
+export function Th({
+  align = "left",
+  sortable = false,
+  sortDirection,
+  style,
+  children,
+  ...rest
+}: ThProps): React.JSX.Element {
+  const base: React.CSSProperties = {
+    padding: `${tokens.space.sm} ${tokens.space.md}`,
+    textAlign: align,
+    fontSize: "0.75rem",
+    fontWeight: tokens.font.weightMedium as unknown as number,
+    letterSpacing: "0.02em",
+    textTransform: "uppercase",
+    color: tokens.color.textMuted,
+    borderBottom: `1px solid ${tokens.color.border}`,
+    background: tokens.color.surfaceAlt,
+    whiteSpace: "nowrap",
+    cursor: sortable ? "pointer" : undefined,
+    userSelect: sortable ? "none" : undefined,
+  };
+  const indicator = sortable
+    ? sortDirection === "asc"
+      ? " ▲"
+      : sortDirection === "desc"
+        ? " ▼"
+        : " ↕"
+    : null;
+  return (
+    <th
+      style={mergeStyles(base, style)}
+      aria-sort={
+        sortDirection === "asc"
+          ? "ascending"
+          : sortDirection === "desc"
+            ? "descending"
+            : undefined
+      }
+      {...rest}
+    >
+      {children}
+      {indicator ? (
+        <span
+          style={{ opacity: sortDirection ? 0.9 : 0.35, fontSize: "0.7em" }}
+        >
+          {indicator}
+        </span>
+      ) : null}
+    </th>
+  );
+}
+
+export interface TdProps extends React.TdHTMLAttributes<HTMLTableCellElement> {
+  align?: CellAlign;
+}
+
+export function Td({
+  align = "left",
+  style,
+  children,
+  ...rest
+}: TdProps): React.JSX.Element {
+  const base: React.CSSProperties = {
+    padding: `${tokens.space.sm} ${tokens.space.md}`,
+    textAlign: align,
+    borderBottom: `1px solid ${tokens.color.border}`,
+    color: tokens.color.text,
+    verticalAlign: "middle",
+  };
+  return (
+    <td style={mergeStyles(base, style)} {...rest}>
+      {children}
+    </td>
+  );
+}

package/components/style.ts

@@ -0,0 +1,195 @@
+/**
+ * `rastack/components` — the styling primitives.
+ *
+ * Every component in this package is painted **entirely from design tokens**:
+ * there is not a single hard-coded colour or dimension in the render tree, only
+ * `var(--…)` references produced here. That is what makes the kit "use the
+ * design system tokens as inputs" — drop the components inside a
+ * `<ThemeProvider>` (or link a `rastack tokens`-generated `tokens.css`) and they
+ * inherit the app's brand, spacing, radius and light/dark modes for free, with
+ * mode switches recascading through CSS with no re-render (exactly like
+ * `rastack/theme`).
+ *
+ * This module is pure (no React, no DOM), so the token-name mapping is unit
+ * tested the same way the token engine is.
+ */
+
+import type React from "react";
+import { cssVarName } from "rastack/tokens";
+
+/**
+ * A design-token path (`"color.surface"`, `"space.md"`, `"radius.lg"`) rendered
+ * as a CSS custom-property reference. Reuses the token engine's `cssVarName`, so
+ * the variable names are guaranteed identical to what `rastack tokens` emits and
+ * `<ThemeProvider>` injects.
+ *
+ * An optional `fallback` becomes the second argument of `var()`, so a component
+ * still renders sensibly when a token set omits an optional token (e.g. a
+ * hand-authored theme without `color.danger`) or before any theme is wired up.
+ *
+ * ```ts
+ * cssVar("color.surface")               // "var(--color-surface)"
+ * cssVar("color.danger", "#E5484D")     // "var(--color-danger, #E5484D)"
+ * ```
+ */
+export function cssVar(path: string, fallback?: string): string {
+  const name = cssVarName(path);
+  return fallback ? `var(${name}, ${fallback})` : `var(${name})`;
+}
+
+/**
+ * The semantic tokens the kit paints from, each already a `var(--…)` string.
+ * Colours carry a literal fallback that mirrors `defineTheme`'s defaults, so the
+ * components degrade gracefully with partial token sets and are legible even
+ * with no `<ThemeProvider>` at all — while a real theme still wins.
+ */
+export const tokens = {
+  color: {
+    bg: cssVar("color.bg", "#ffffff"),
+    surface: cssVar("color.surface", "#ffffff"),
+    surfaceAlt: cssVar("color.surface-alt", "#f2f5fb"),
+    border: cssVar("color.border", "#e6eaf2"),
+    text: cssVar("color.text", "#0b1020"),
+    textMuted: cssVar("color.text-muted", "#4b5670"),
+    accent: cssVar("color.accent", "#4f6bff"),
+    accentStrong: cssVar("color.accent-strong", "#3b54e8"),
+    onAccent: cssVar("color.on-accent", "#ffffff"),
+    success: cssVar("color.success", "#1fa971"),
+    danger: cssVar("color.danger", "#e5484d"),
+    warning: cssVar("color.warning", "#f5a623"),
+  },
+  space: {
+    xs: cssVar("space.xs", "4px"),
+    sm: cssVar("space.sm", "8px"),
+    md: cssVar("space.md", "16px"),
+    lg: cssVar("space.lg", "24px"),
+    xl: cssVar("space.xl", "40px"),
+  },
+  radius: {
+    sm: cssVar("radius.sm", "6px"),
+    md: cssVar("radius.md", "10px"),
+    lg: cssVar("radius.lg", "16px"),
+    xl: cssVar("radius.xl", "24px"),
+    pill: cssVar("radius.pill", "999px"),
+  },
+  font: {
+    sans: cssVar("font.family.sans", "system-ui, sans-serif"),
+    mono: cssVar("font.family.mono", "ui-monospace, monospace"),
+    weightRegular: cssVar("font.weight.regular", "400"),
+    weightMedium: cssVar("font.weight.medium", "500"),
+    weightBold: cssVar("font.weight.bold", "700"),
+  },
+  shadow: {
+    sm: cssVar("shadow.sm", "0 1px 2px rgba(11,16,32,0.08)"),
+    md: cssVar(
+      "shadow.md",
+      "0 2px 4px rgba(11,16,32,0.12), 0 8px 24px rgba(11,16,32,0.10)",
+    ),
+  },
+  duration: {
+    fast: cssVar("duration.fast", "150ms"),
+    base: cssVar("duration.base", "200ms"),
+  },
+} as const;
+
+/** Shallow-merge a base style with a caller override (override wins, `undefined` ignored). */
+export function mergeStyles(
+  base: React.CSSProperties,
+  override?: React.CSSProperties,
+): React.CSSProperties {
+  return override ? { ...base, ...override } : base;
+}
+
+// --- shared control tokens (kept in one place so inputs/selects/buttons align) --
+
+/** Sizes shared by the interactive controls. */
+export type ControlSize = "sm" | "md" | "lg";
+
+/** Per-size padding / font-size / height, in token units. */
+export const controlSizing: Record<
+  ControlSize,
+  { paddingY: string; paddingX: string; fontSize: string; height: string }
+> = {
+  sm: {
+    paddingY: tokens.space.xs,
+    paddingX: tokens.space.sm,
+    fontSize: "0.8125rem",
+    height: "2rem",
+  },
+  md: {
+    paddingY: tokens.space.sm,
+    paddingX: tokens.space.md,
+    fontSize: "0.875rem",
+    height: "2.5rem",
+  },
+  lg: {
+    paddingY: tokens.space.sm,
+    paddingX: tokens.space.lg,
+    fontSize: "1rem",
+    height: "3rem",
+  },
+};
+
+/** The base look every text-like control shares (input, textarea, select). */
+export function controlBaseStyle(size: ControlSize): React.CSSProperties {
+  const s = controlSizing[size];
+  return {
+    display: "block",
+    width: "100%",
+    boxSizing: "border-box",
+    padding: `${s.paddingY} ${s.paddingX}`,
+    fontFamily: tokens.font.sans,
+    fontSize: s.fontSize,
+    color: tokens.color.text,
+    background: tokens.color.surface,
+    border: `1px solid ${tokens.color.border}`,
+    borderRadius: tokens.radius.md,
+    outline: "none",
+    transition: `border-color ${tokens.duration.fast} ease, box-shadow ${tokens.duration.fast} ease`,
+  };
+}
+
+/** The focus ring shared by controls, as inline style to spread on focus. */
+export const focusRingStyle: React.CSSProperties = {
+  borderColor: tokens.color.accent,
+  boxShadow: `0 0 0 3px ${cssVar("color.accent", "#4f6bff")}33`,
+};
+
+/** Style applied to a control flagged invalid. */
+export const invalidControlStyle: React.CSSProperties = {
+  borderColor: tokens.color.danger,
+};
+
+// --- button variants ----------------------------------------------------------
+
+export type ButtonVariant =
+  "primary" | "secondary" | "outline" | "ghost" | "danger";
+
+/** Colour treatment per button variant (structure/sizing handled by the component). */
+export const buttonVariantStyle: Record<ButtonVariant, React.CSSProperties> = {
+  primary: {
+    background: tokens.color.accent,
+    color: tokens.color.onAccent,
+    border: "1px solid transparent",
+  },
+  secondary: {
+    background: tokens.color.surfaceAlt,
+    color: tokens.color.text,
+    border: `1px solid ${tokens.color.border}`,
+  },
+  outline: {
+    background: "transparent",
+    color: tokens.color.text,
+    border: `1px solid ${tokens.color.border}`,
+  },
+  ghost: {
+    background: "transparent",
+    color: tokens.color.text,
+    border: "1px solid transparent",
+  },
+  danger: {
+    background: tokens.color.danger,
+    color: "#ffffff",
+    border: "1px solid transparent",
+  },
+};

package/components/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Structural contracts the data-connected components accept.
+ *
+ * The framework has **two** hook families (see `docs/local-sync-engine.md`):
+ * the REST list hook returns a rich `IListQuery` (`data` + `header` +
+ * `pagination`/`sorting`/`searching`/`filtering` + the react-query flags), while
+ * a `sync: { mode: "local" }` entity returns only `{ data, isLoading, isReady }`.
+ * Rather than couple to either, the components accept the **structural
+ * lowest-common-denominator** below and *feature-detect* the richer parts — a
+ * `<DataTable>` renders a pager only when `pagination` is present, sortable
+ * headers only when `sorting` is present, and so on. Both hook families satisfy
+ * `TableQuery`, so the same `<DataTable query={…} />` works with either.
+ *
+ * These are `import type`-only re-exports of the real hook interfaces, so this
+ * file adds no runtime dependency and the shapes never drift from the hooks.
+ */
+
+import type {
+  IPaginationActions,
+  ISearchingActions,
+  ISortingActions,
+  IFilterActions,
+  ReturnedHeader,
+} from "../hooks/query/interfaces";
+import type { FormFieldStructure } from "../hooks/form/interfaces";
+
+export type { ReturnedHeader } from "../hooks/query/interfaces";
+
+/**
+ * Anything a `<DataTable>` / `useDataTable` can drive. The only required members
+ * are `data` (the rows) and, in practice, a loading flag; everything else is
+ * optional and lit up when present.
+ */
+export interface TableQuery<TRow = Record<string, unknown>> {
+  /** The rows. `IListQuery.data` (`.results`) or a sync list's `data`. */
+  data: TRow[] | undefined;
+  /** react-query's flag (REST) — absent on sync hooks, treated as `false`. */
+  isLoading?: boolean;
+  /** react-query's flag (REST). */
+  isError?: boolean;
+  /** react-query's error (REST). */
+  error?: unknown;
+  /** Column descriptors from the server envelope, when the API supplies them. */
+  header?: ReturnedHeader[];
+  /** Present on REST list hooks — enables the pager. */
+  pagination?: IPaginationActions;
+  /** Present on REST list hooks — enables the search box. */
+  searching?: ISearchingActions<Record<string, unknown>>;
+  /** Present on REST list hooks — enables sortable headers. */
+  sorting?: ISortingActions<Record<string, unknown>>;
+  /** Present on REST list hooks. */
+  filtering?: IFilterActions<Record<string, unknown>>;
+  /** Sync hooks expose readiness instead of react-query's `isLoading`. */
+  isReady?: boolean;
+}
+
+/**
+ * A single field as `useForm().getFormField(name)` returns it, with `value`
+ * widened to `unknown` and `setValue` to `(value: any)`. `FormFieldStructure<T>`
+ * is invariant in `T` (it both reads `value: T` and writes `setValue(v: T)`), so
+ * these two overrides are what let a `FormFieldStructure<SomeField>` assign here
+ * regardless of the field's concrete type.
+ */
+export type AutoFormField = Omit<
+  FormFieldStructure<unknown>,
+  "value" | "setValue"
+> & {
+  value: unknown;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  setValue: (value: any) => void;
+};
+
+/**
+ * Anything an `<AutoForm>` / `useAutoForm` can drive — the subset of
+ * `useForm()`'s `FormStructure` the auto-form reads. `getFormField`/`onSubmit`/
+ * `resetForm` are declared as **methods** (bivariant params) so the generic
+ * `FormStructure` assigns without a cast.
+ */
+export interface AutoFormLike {
+  /**
+   * Current values; their keys are the default field list/order. Typed as
+   * `object` (not `Record<string, unknown>`) so a `useForm<Interface>()` result —
+   * whose values are a plain interface with no index signature — assigns cleanly.
+   */
+  formValues: object | undefined;
+  /** Per-field structure, including the (enriched) datatype used to pick a control. */
+  getFormField(name: string): AutoFormField;
+  /** Validate + fire the wired mutation. */
+  onSubmit(): void;
+  /** Reset back to the initial values. */
+  resetForm(): void;
+  /** Whether submission is currently blocked (invalid). */
+  isSubmitDisabled: boolean;
+  /** Whether a submit mutation is in flight. */
+  isSubmitting: boolean;
+  /** Formik's error bag, keyed by field name. */
+  errors?: Record<string, unknown> | unknown;
+}

package/components/util.ts

@@ -0,0 +1,14 @@
+/** Small pure helpers + shared types across the components. React- and DOM-free. */
+
+/** Text alignment shared by table cells and (potentially) other layout. */
+export type CellAlign = "left" | "center" | "right";
+
+/** `"first_name"` / `"firstName"` / `"created-at"` → `"First name"`. */
+export function humanizeKey(key: string): string {
+  const spaced = key
+    .replace(/[_\-.]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .trim();
+  if (!spaced) return key;
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1).toLowerCase();
+}

package/hooks/form/form.ts

@@ -160,10 +160,11 @@ export function useForm<
     const { setValue: setFormValue, setTouched } =
       formik.getFieldHelpers(fieldName);
 
-    let { type, isRequired } = getFieldStructure(
-      mutations ? mutations[updateMethod]?.validation : undefined,
-      fieldName,
-    );
+    const { type, isRequired, maxLength, options, relation, nullable, format } =
+      getFieldStructure(
+        mutations ? mutations[updateMethod]?.validation : undefined,
+        fieldName,
+      );
 
     const error = errorMessage ?? "";
     const isError = errorMessage !== undefined;
@@ -189,6 +190,11 @@ export function useForm<
       isRequired,
       setValue,
       setTouched,
+      maxLength,
+      options,
+      relation,
+      nullable,
+      format,
     };
   };
 

package/hooks/form/interfaces.ts

@@ -3,6 +3,18 @@ import { SchemaObject } from "ajv";
 import { IUpdateQueryResult } from "../../hooks";
 import { FormikValues } from "formik";
 
+/** A choice for an `enum`-backed (`select`) field. */
+export interface FieldOption {
+  label: string;
+  value: string | number;
+}
+
+/** The `{ app, model }` a foreign-key field points at (`x-rastack-relation`). */
+export interface RelationTarget {
+  app: string;
+  model: string;
+}
+
 export interface FormFieldStructure<TValue> {
   value: TValue;
   error: string;
@@ -13,6 +25,16 @@ export interface FormFieldStructure<TValue> {
   isRequired: boolean;
   setValue: (value: TValue) => void;
   setTouched: (isTouched: boolean) => void;
+  /** Max string length, when the schema constrains it. Drives a character counter. */
+  maxLength?: number;
+  /** Choices for a `select` field, derived from the schema's `enum`. */
+  options?: FieldOption[];
+  /** The FK target, when this field is a foreign key. Lets a caller render a relation picker. */
+  relation?: RelationTarget;
+  /** Whether the schema allows `null`. */
+  nullable?: boolean;
+  /** The schema `format` (`date-time`, `email`, `uuid`, …), for finer control choices. */
+  format?: string;
 }
 
 interface FormMutation<
@@ -118,7 +140,24 @@ export interface FormStructure<TFormValues, TResponse> {
   ) => FormFieldStructure<FlattenedRecord<TFormValues>[TFieldName]>;
 }
 
-export type FormType = "number" | "text" | "array";
+/**
+ * The control kind a field maps to. Derived from the write JSON Schema by
+ * {@link getFieldStructure}: the base scalar types (`text`/`number`/`array`)
+ * plus the richer distinctions a form UI needs — `boolean` (checkbox), `date`
+ * / `datetime` (date pickers), `select` (an `enum`), and the typed-text formats
+ * `email` / `url`. The list is a superset of the original three, so existing
+ * `type === "number"` / `"text"` / `"array"` checks keep working.
+ */
+export type FormType =
+  | "text"
+  | "number"
+  | "array"
+  | "boolean"
+  | "date"
+  | "datetime"
+  | "select"
+  | "email"
+  | "url";
 
 export interface SetupUpdateEndpointReturn<TParams, TPayload, TResult> {
   mutation: IUpdateQueryResult<TParams, TPayload, TResult>;

package/hooks/form/structure.ts

@@ -1,39 +1,96 @@
-import { SchemaObject } from "ajv";
-import { FormType } from "./interfaces";
+import type { SchemaObject } from "ajv";
+import type { FieldOption, FormType, RelationTarget } from "./interfaces";
 
-interface GetFieldStructureResponse {
+export interface GetFieldStructureResponse {
   isRequired: boolean;
   type: FormType;
+  maxLength?: number;
+  options?: FieldOption[];
+  relation?: RelationTarget;
+  nullable?: boolean;
+  format?: string;
 }
 
+/**
+ * Read one field's UI shape out of a write JSON Schema (the dereferenced
+ * `Deref{Name}` the form hook validates against).
+ *
+ * The schema is the only runtime artifact that still carries a field's real
+ * datatype — `type`, `format` (`date-time`/`email`/`uuid`), `enum`, `maxLength`,
+ * `nullable`, and the `x-rastack-relation` FK target the compiler stamps on
+ * foreign keys. This maps that to a {@link FormType} control kind plus the extra
+ * metadata a form UI needs, so `<AutoForm>` (and any hand-rolled form reading
+ * `getFormField`) can render the correct input per datatype instead of a text
+ * box for everything.
+ */
 export function getFieldStructure<TFieldName>(
   validationSchema: SchemaObject | undefined,
   fieldName: TFieldName,
 ): GetFieldStructureResponse {
-  let type: FormType = "text";
-  if (validationSchema?.properties) {
-    const schemaJson = validationSchema.properties[fieldName];
-    if (!schemaJson) {
-      return { isRequired: false, type };
-    }
-    let schemaJsonType = schemaJson.type;
-
-    if (typeof schemaJsonType === "string") {
-      schemaJsonType = [schemaJsonType];
-    }
-    if (schemaJsonType) {
-      if (schemaJsonType.includes("integer")) {
-        type = "number";
-      }
-      if (schemaJsonType.includes("array")) {
-        type = "array";
-      }
-    }
+  const result: GetFieldStructureResponse = { isRequired: false, type: "text" };
+
+  // JSON Schema shapes vary across ajv typings; access untyped.
+  const schema = validationSchema as
+    { properties?: Record<string, any>; required?: unknown } | undefined;
+  const property: any = schema?.properties?.[fieldName as string];
+  if (!property) return result;
+
+  // JSON Schema `type` can be a string or an array (nullable unions like
+  // `["string", "null"]`); normalise to a list.
+  const rawType = property.type;
+  const typeList: string[] =
+    typeof rawType === "string"
+      ? [rawType]
+      : Array.isArray(rawType)
+        ? rawType
+        : [];
+  if (typeList.includes("null") || property.nullable === true) {
+    result.nullable = true;
+  }
+
+  const format: unknown = property.format;
+  if (typeof format === "string") result.format = format;
+
+  if (typeof property.maxLength === "number")
+    result.maxLength = property.maxLength;
+
+  const relation = property["x-rastack-relation"];
+  if (relation && typeof relation === "object") {
+    result.relation = relation as RelationTarget;
   }
 
-  let isRequired = false;
-  if (validationSchema?.required) {
-    isRequired = validationSchema.required?.includes(fieldName);
+  const enumValues: unknown = property.enum;
+
+  // Choose the control kind. Enum wins over the raw scalar type (a constrained
+  // string is a picker, not a free text box); FK metadata is advisory and does
+  // not change the underlying scalar control.
+  if (Array.isArray(enumValues) && enumValues.length > 0) {
+    result.type = "select";
+    result.options = enumValues
+      .filter((v): v is string | number => v !== null && v !== undefined)
+      .map((v) => ({ label: String(v), value: v }));
+  } else if (typeList.includes("boolean")) {
+    result.type = "boolean";
+  } else if (typeList.includes("integer") || typeList.includes("number")) {
+    result.type = "number";
+  } else if (typeList.includes("array")) {
+    result.type = "array";
+  } else if (result.format === "date-time") {
+    result.type = "datetime";
+  } else if (result.format === "date") {
+    result.type = "date";
+  } else if (result.format === "email") {
+    result.type = "email";
+  } else if (result.format === "uri" || result.format === "url") {
+    result.type = "url";
+  } else {
+    result.type = "text";
   }
-  return { isRequired, type };
+
+  const required: unknown = schema?.required;
+  if (Array.isArray(required)) {
+    result.isRequired = required.includes(fieldName);
+  }
+
+  return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rastack",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",