rastack 0.0.25 → 0.0.27

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.27](https://github.com/theserverkid/reactapistack/compare/v0.0.26...v0.0.27) (2026-07-10)
+
+### [0.0.26](https://github.com/theserverkid/reactapistack/compare/v0.0.25...v0.0.26) (2026-07-10)
+
 ### [0.0.25](https://github.com/theserverkid/reactapistack/compare/v0.0.24...v0.0.25) (2026-07-10)
 
 ### [0.0.24](https://github.com/theserverkid/reactapistack/compare/v0.0.23...v0.0.24) (2026-07-09)

package/components/auto-form/AutoForm.tsx

@@ -0,0 +1,254 @@
+import React, { useState } from "react";
+import { tokens } from "../style";
+import type { AutoFormLike } from "../types";
+import { Field } from "../primitives/field";
+import {
+  Input,
+  Textarea,
+  Select,
+  Checkbox,
+  Button,
+} from "../primitives/controls";
+import {
+  useAutoForm,
+  type AutoFormFieldModel,
+  type AutoFormModel,
+} from "./use-auto-form";
+import type { AutoFormInputKind, AutoFormOptions } from "./fields";
+
+export interface AutoFormProps extends AutoFormOptions {
+  /** The form hook result (`useUpdateXForm(...)`) driving the form. */
+  form: AutoFormLike;
+  submitLabel?: React.ReactNode;
+  /** Renders a secondary button that calls this. */
+  onCancel?: () => void;
+  cancelLabel?: React.ReactNode;
+  /** Called after the form's own submit fires (e.g. to close a modal). */
+  onSubmit?: () => void;
+  /** Hide the built-in actions row (render your own submit control). */
+  hideActions?: boolean;
+  /** Field-grid column count. Default 1. */
+  columns?: number;
+  /** Total-control escape hatch: receives the headless model. */
+  children?: (model: AutoFormModel) => React.ReactNode;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/** Format a stored value for a native date / datetime-local input. */
+function toInputValue(kind: AutoFormInputKind, value: unknown): string {
+  if (value == null) return "";
+  const s = String(value);
+  if (kind === "date") return s.slice(0, 10);
+  if (kind === "datetime-local") return s.slice(0, 16);
+  return s;
+}
+
+/**
+ * A form that builds itself from a form hook.
+ *
+ * ```tsx
+ * <AutoForm form={useUpdateAirportForm({ formValues: { code: "", name: "" } })} />
+ * ```
+ *
+ * Each field's control is chosen from the datatype the form hook derives from
+ * the write schema — booleans become checkboxes, `date-time` fields date
+ * pickers, enums dropdowns, and so on. Override any field (label, control,
+ * options for an FK picker, custom render) via the `fields` option.
+ */
+export function AutoForm(props: AutoFormProps): React.JSX.Element {
+  const {
+    form,
+    fields,
+    exclude,
+    submitLabel = "Save",
+    onCancel,
+    cancelLabel = "Cancel",
+    onSubmit,
+    hideActions = false,
+    columns = 1,
+    children,
+    style,
+    className,
+  } = props;
+
+  const model = useAutoForm(form, { fields, exclude });
+  const [touched, setTouched] = useState<Set<string>>(() => new Set());
+  const [submitted, setSubmitted] = useState(false);
+
+  const markTouched = (name: string) => {
+    setTouched((prev) => {
+      if (prev.has(name)) return prev;
+      const next = new Set(prev);
+      next.add(name);
+      return next;
+    });
+  };
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    setSubmitted(true);
+    model.submit();
+    onSubmit?.();
+  };
+
+  const renderControl = (f: AutoFormFieldModel): React.ReactNode => {
+    const { field, input, id } = f;
+    const blur = () => {
+      markTouched(f.name);
+      field.setTouched(true);
+    };
+    const invalid = (touched.has(f.name) || submitted) && field.isError;
+
+    if (f.render) return f.render(field, { name: f.name, id });
+
+    switch (input) {
+      case "checkbox":
+        return (
+          <Checkbox
+            id={id}
+            label={f.label}
+            checked={Boolean(field.value)}
+            onChange={(e) => field.setValue(e.target.checked)}
+            onBlur={blur}
+          />
+        );
+      case "select": {
+        const options = f.options ?? [];
+        return (
+          <Select
+            id={id}
+            invalid={invalid}
+            value={field.value == null ? "" : String(field.value)}
+            placeholder={field.isRequired ? undefined : (f.placeholder ?? "—")}
+            options={options}
+            onChange={(e) => {
+              const match = options.find(
+                (o) => String(o.value) === e.target.value,
+              );
+              field.setValue(match ? match.value : e.target.value);
+            }}
+            onBlur={blur}
+          />
+        );
+      }
+      case "textarea":
+        return (
+          <Textarea
+            id={id}
+            invalid={invalid}
+            value={field.value == null ? "" : String(field.value)}
+            placeholder={f.placeholder}
+            onChange={(e) => field.setValue(e.target.value)}
+            onBlur={blur}
+          />
+        );
+      default: {
+        const htmlType =
+          input === "number"
+            ? "number"
+            : input === "date"
+              ? "date"
+              : input === "datetime-local"
+                ? "datetime-local"
+                : input === "email"
+                  ? "email"
+                  : input === "url"
+                    ? "url"
+                    : "text";
+        return (
+          <Input
+            id={id}
+            type={htmlType}
+            invalid={invalid}
+            maxLength={
+              input === "text" || input === "email" || input === "url"
+                ? field.maxLength
+                : undefined
+            }
+            value={toInputValue(input, field.value)}
+            placeholder={f.placeholder}
+            onChange={(e) => field.setValue(e.target.value)}
+            onBlur={blur}
+          />
+        );
+      }
+    }
+  };
+
+  const renderField = (f: AutoFormFieldModel): React.ReactNode => {
+    const invalid = (touched.has(f.name) || submitted) && f.field.isError;
+    const errorText = invalid ? f.field.error : undefined;
+    // Checkboxes carry their own inline label; don't repeat it above.
+    const label = f.input === "checkbox" ? undefined : f.label;
+    return (
+      <Field
+        key={f.name}
+        label={label}
+        htmlFor={f.id}
+        required={f.field.isRequired}
+        error={errorText}
+        hint={f.hint}
+      >
+        {renderControl(f)}
+      </Field>
+    );
+  };
+
+  return (
+    <form
+      onSubmit={handleSubmit}
+      className={className}
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: tokens.space.lg,
+        ...style,
+      }}
+      noValidate
+    >
+      {children ? (
+        children(model)
+      ) : (
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: `repeat(${Math.max(1, columns)}, minmax(0, 1fr))`,
+            gap: tokens.space.lg,
+          }}
+        >
+          {model.fields.map(renderField)}
+        </div>
+      )}
+
+      {!hideActions && !children ? (
+        <div
+          style={{
+            display: "flex",
+            gap: tokens.space.sm,
+            justifyContent: "flex-end",
+          }}
+        >
+          {onCancel ? (
+            <Button
+              type="button"
+              variant="outline"
+              onClick={onCancel}
+              disabled={model.isSubmitting}
+            >
+              {cancelLabel}
+            </Button>
+          ) : null}
+          <Button
+            type="submit"
+            variant="primary"
+            loading={model.isSubmitting}
+            disabled={!model.canSubmit}
+          >
+            {submitLabel}
+          </Button>
+        </div>
+      ) : null}
+    </form>
+  );
+}

package/components/auto-form/fields.ts

@@ -0,0 +1,108 @@
+/**
+ * Auto-form field resolution — the pure core.
+ *
+ * Two decisions live here, both React-free and unit tested:
+ *   1. **Which fields, in what order** — from an explicit `fields` list, else the
+ *      keys of the form's current values — minus any `exclude`d.
+ *   2. **Which control each field gets** — mapped from the enriched
+ *      {@link FormType} the form hook now derives from the write JSON Schema
+ *      (`boolean → checkbox`, `date → date picker`, `select → dropdown`, …).
+ * `<AutoForm>` turns these specs into live fields; you can also call
+ * {@link inputKindForFieldType} yourself to drive a custom form.
+ */
+
+import type React from "react";
+import type { FieldOption, FormType } from "../../hooks/form/interfaces";
+import type { AutoFormField } from "../types";
+import { humanizeKey } from "../util";
+
+/** The concrete control an auto-form field renders as. */
+export type AutoFormInputKind =
+  | "text"
+  | "textarea"
+  | "number"
+  | "checkbox"
+  | "date"
+  | "datetime-local"
+  | "select"
+  | "email"
+  | "url";
+
+/** Per-field overrides. */
+export interface AutoFormFieldConfig {
+  label?: React.ReactNode;
+  /** Force the control kind (e.g. render an FK `relation` as a `select`). */
+  input?: AutoFormInputKind;
+  /** Options for a `select` — e.g. records loaded for a foreign key. */
+  options?: FieldOption[];
+  hint?: React.ReactNode;
+  placeholder?: string;
+  /** Fully custom render for this field, given its live structure. */
+  render?: (
+    field: AutoFormField,
+    ctx: { name: string; id: string },
+  ) => React.ReactNode;
+}
+
+/** A field entry with its name, usable in the `fields` option. */
+export interface AutoFormFieldSpec extends AutoFormFieldConfig {
+  name: string;
+}
+
+export interface AutoFormOptions {
+  /**
+   * Explicit fields — sets the order and, optionally, per-field config. A bare
+   * string includes a field with defaults; an object configures it. When
+   * omitted, every key of the form's values is used.
+   */
+  fields?: Array<string | AutoFormFieldSpec>;
+  /** Names to drop (applied whether fields are explicit or inferred). */
+  exclude?: string[];
+}
+
+/** Map an enriched {@link FormType} to the control the auto-form renders. */
+export function inputKindForFieldType(type: FormType): AutoFormInputKind {
+  switch (type) {
+    case "boolean":
+      return "checkbox";
+    case "number":
+      return "number";
+    case "date":
+      return "date";
+    case "datetime":
+      return "datetime-local";
+    case "select":
+      return "select";
+    case "email":
+      return "email";
+    case "url":
+      return "url";
+    case "array":
+      return "textarea";
+    case "text":
+    default:
+      return "text";
+  }
+}
+
+/**
+ * Decide the ordered, configured field specs for a form. Pure: it reads only the
+ * field-name list (the caller passes `Object.keys(formValues)`) and the options.
+ */
+export function resolveFieldSpecs(
+  fieldNames: string[],
+  options: AutoFormOptions = {},
+): AutoFormFieldSpec[] {
+  const exclude = new Set(options.exclude ?? []);
+
+  let specs: AutoFormFieldSpec[];
+  if (options.fields && options.fields.length > 0) {
+    specs = options.fields.map((f) =>
+      typeof f === "string" ? { name: f } : { ...f },
+    );
+  } else {
+    specs = fieldNames.map((name) => ({ name }));
+  }
+
+  return specs.filter((s) => !exclude.has(s.name));
+}

package/components/auto-form/use-auto-form.ts

@@ -0,0 +1,89 @@
+/**
+ * `useAutoForm` — the headless form model.
+ *
+ * Give it a `useForm()` result and it returns one descriptor per field —
+ * resolved label, the control kind picked from the field's datatype, and the
+ * live field structure (value, setter, error, options) — plus `submit`/`reset`
+ * and submit-state flags. `<AutoForm>` renders these; consume it directly to lay
+ * out a bespoke form while keeping the datatype-driven wiring.
+ */
+
+import type React from "react";
+import type { FieldOption } from "../../hooks/form/interfaces";
+import type { AutoFormField, AutoFormLike } from "../types";
+import { humanizeKey } from "../util";
+import {
+  inputKindForFieldType,
+  resolveFieldSpecs,
+  type AutoFormInputKind,
+  type AutoFormOptions,
+} from "./fields";
+
+export interface AutoFormFieldModel {
+  name: string;
+  /** DOM id linking label ↔ control. */
+  id: string;
+  label: React.ReactNode;
+  input: AutoFormInputKind;
+  /** The live field: `value`, `setValue`, `error`, `isError`, `isRequired`, `maxLength`, … */
+  field: AutoFormField;
+  /** Resolved choices for a `select` (config options, else the field's enum). */
+  options?: FieldOption[];
+  hint?: React.ReactNode;
+  placeholder?: string;
+  render?: (
+    field: AutoFormField,
+    ctx: { name: string; id: string },
+  ) => React.ReactNode;
+}
+
+export interface AutoFormModel {
+  fields: AutoFormFieldModel[];
+  submit: () => void;
+  reset: () => void;
+  isSubmitting: boolean;
+  /** `true` when the form is valid and not mid-submit. */
+  canSubmit: boolean;
+  errors: Record<string, unknown>;
+}
+
+/** Pure model assembly — see {@link useAutoForm}. Testable with a mock form. */
+export function buildAutoFormModel(
+  form: AutoFormLike,
+  options: AutoFormOptions = {},
+): AutoFormModel {
+  const fieldNames = Object.keys(form.formValues ?? {});
+  const specs = resolveFieldSpecs(fieldNames, options);
+
+  const fields: AutoFormFieldModel[] = specs.map((spec) => {
+    const field = form.getFormField(spec.name);
+    return {
+      name: spec.name,
+      id: `af-${spec.name}`,
+      label: spec.label ?? humanizeKey(spec.name),
+      input: spec.input ?? inputKindForFieldType(field.type),
+      field,
+      options: spec.options ?? field.options,
+      hint: spec.hint,
+      placeholder: spec.placeholder,
+      render: spec.render,
+    };
+  });
+
+  return {
+    fields,
+    submit: () => form.onSubmit(),
+    reset: () => form.resetForm(),
+    isSubmitting: form.isSubmitting,
+    canSubmit: !form.isSubmitDisabled && !form.isSubmitting,
+    errors: (form.errors as Record<string, unknown>) ?? {},
+  };
+}
+
+/** React hook wrapper around {@link buildAutoFormModel}. */
+export function useAutoForm(
+  form: AutoFormLike,
+  options: AutoFormOptions = {},
+): AutoFormModel {
+  return buildAutoFormModel(form, options);
+}