@stapel/forms-react 0.1.0

package/src/default/fields.tsx

@@ -0,0 +1,454 @@
+/**
+ * The antd BUILTIN field widgets — one per attribute kind stapel-forms allows
+ * (`STAPEL_FORMS["FIELD_KINDS"]`, ten of them).
+ *
+ * ── Where these sit in the resolution ladder ───────────────────────────────
+ *
+ *   explicit `registerFormFieldWidget(kind, …)`  ← a host's, always wins
+ *   → this table                                  ← the skin's default
+ *   → the unsupported-field notice                ← loud, never silent
+ *
+ * The host's registration outranks the skin's builtin, mirroring docs-react's
+ * `DocSurface`, so "override without fork" is real and not a slogan: a host
+ * that dislikes this `select` replaces it in one line and keeps every other
+ * widget.
+ *
+ * ── Two deliberate departures from the spec's widget sketch ────────────────
+ *
+ * 1. **`date` uses a native `<input type=…>`, not antd's `DatePicker`.**
+ *    `DatePicker` speaks Dayjs objects, which would make `dayjs` a runtime
+ *    dependency of this pair for exactly one widget — and would put a
+ *    format-guessing step between the person and the wire, where today the
+ *    native control hands over the ISO string
+ *    (`YYYY-MM-DD` / `YYYY-MM` / `YYYY-MM-DDTHH:mm`) that the attributes date
+ *    type already parses. The `precision` config selects the input type, so
+ *    "year only" is a number and "datetime" is a datetime-local. A host that
+ *    wants the antd picker registers it — that is what the seam is for.
+ *
+ * 2. **`select` renders `Segmented` at ≤4 single-choice options, else
+ *    `Select`** — the profiles-react `FieldRow` threshold, kept identical so
+ *    the fleet's forms and its settings screens read the same way.
+ *
+ * Values are BARE SCALARS. The server normalizes a single `select` answer to
+ * a list, so no widget wraps its own value; the one exception is
+ * `convertible_unit`, whose wire DTO genuinely is an object
+ * (`{type, value, unit}` — `stapel_attributes.types.convertible_unit.dto`).
+ */
+import { useMemo } from "react";
+import type { ReactElement } from "react";
+import {
+  Cascader,
+  ColorPicker,
+  Flex,
+  Input,
+  InputNumber,
+  Segmented,
+  Select,
+  Switch,
+  Typography,
+} from "antd";
+import { useT } from "@stapel/core";
+import type { FormFieldDef } from "../api/types.js";
+import type { FormFieldWidget, FormFieldWidgetProps } from "../widgets/registry.js";
+import { optionValues } from "../widgets/validate.js";
+import { FORMS_I18N_KEYS } from "../i18n/keys.js";
+
+/** At or below this many choices a single-select renders as a `Segmented`
+ * (the profiles-react threshold — kept identical on purpose). */
+const SEGMENTED_MAX_OPTIONS = 4;
+
+/**
+ * antd's `status` prop under `exactOptionalPropertyTypes` does not accept
+ * `undefined` — it wants the key ABSENT. Spread this instead of passing
+ * `status={error ? "error" : undefined}`, which every control in this file
+ * would otherwise have to spell out.
+ */
+function errorStatus(
+  error: unknown
+): { status: "error" } | Record<string, never> {
+  return error ? { status: "error" } : {};
+}
+
+function config(field: FormFieldDef): Readonly<Record<string, unknown>> {
+  return field.config ?? {};
+}
+
+function numberish(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+function str(value: unknown): string {
+  return typeof value === "string" ? value : value == null ? "" : String(value);
+}
+
+/** `{value, label}` choices for antd, from either option shape the attributes
+ * types allow (bare scalars, or `{value, label}` objects). */
+function choiceList(
+  field: FormFieldDef
+): readonly { value: string; label: string }[] {
+  const raw = config(field)["options"];
+  if (!Array.isArray(raw)) return [];
+  return raw.map((option) => {
+    if (option !== null && typeof option === "object") {
+      const entry = option as { value?: unknown; label?: unknown };
+      const value = str(entry.value);
+      return { value, label: entry.label == null ? value : str(entry.label) };
+    }
+    return { value: str(option), label: str(option) };
+  });
+}
+
+// ── string ───────────────────────────────────────────────────────────────────
+
+/**
+ * `string` → `Input`, or `Input.TextArea` when `config.multiline` is set
+ * (stapel-attributes 0.4.6). Absent means single-line, which is what every
+ * schema published before that release carries — so nothing stored needs a
+ * migration and the widget needs no fallback heuristic.
+ */
+const StringWidget: FormFieldWidget = (props: FormFieldWidgetProps) => {
+  const cfg = config(props.field);
+  const maxLength = numberish(cfg["maxLength"]);
+  const placeholder = str(cfg["placeholder"]);
+  const common = {
+    id: props.id,
+    value: str(props.value),
+    disabled: props.disabled,
+    ...errorStatus(props.error),
+    ...(maxLength !== undefined ? { maxLength } : {}),
+    ...(placeholder.length > 0 ? { placeholder } : {}),
+  };
+  return cfg["multiline"] === true ? (
+    <Input.TextArea
+      {...common}
+      autoSize={{ minRows: 3, maxRows: 8 }}
+      onChange={(event) => props.onChange(event.target.value)}
+    />
+  ) : (
+    <Input {...common} onChange={(event) => props.onChange(event.target.value)} />
+  );
+};
+
+// ── int / float ──────────────────────────────────────────────────────────────
+
+function makeNumberWidget(isInt: boolean): FormFieldWidget {
+  const Widget = (props: FormFieldWidgetProps): ReactElement => {
+    const cfg = config(props.field);
+    const min = numberish(cfg["min"]);
+    const max = numberish(cfg["max"]);
+    const precision = isInt ? 0 : numberish(cfg["precision"]);
+    const placeholder = str(cfg["placeholder"]);
+    return (
+      <InputNumber
+        id={props.id}
+        style={{ width: "100%" }}
+        value={numberish(props.value) ?? null}
+        disabled={props.disabled}
+        {...errorStatus(props.error)}
+                {...(min !== undefined ? { min } : {})}
+        {...(max !== undefined ? { max } : {})}
+        {...(precision !== undefined ? { precision } : {})}
+        {...(isInt ? { step: 1 } : {})}
+        {...(placeholder.length > 0 ? { placeholder } : {})}
+        {...(str(cfg["prefix"]).length > 0 ? { prefix: str(cfg["prefix"]) } : {})}
+        {...(str(cfg["postfix"]).length > 0 ? { suffix: str(cfg["postfix"]) } : {})}
+        onChange={(next) => props.onChange(next ?? undefined)}
+      />
+    );
+  };
+  Widget.displayName = isInt ? "IntWidget" : "FloatWidget";
+  return Widget;
+}
+
+// ── bool ─────────────────────────────────────────────────────────────────────
+
+/** `bool` → `Switch`, labelled with the config's own `trueLabel`/`falseLabel`
+ * when the admin supplied them. */
+const BoolWidget: FormFieldWidget = (props: FormFieldWidgetProps) => {
+  const t = useT();
+  const cfg = config(props.field);
+  const on = props.value === true;
+  const trueLabel = str(cfg["trueLabel"]) || t(FORMS_I18N_KEYS.fillBoolYes);
+  const falseLabel = str(cfg["falseLabel"]) || t(FORMS_I18N_KEYS.fillBoolNo);
+  return (
+    <Flex align="center" gap={8}>
+      <Switch
+        id={props.id}
+        checked={on}
+        disabled={props.disabled}
+        onChange={(checked) => props.onChange(checked)}
+      />
+      <Typography.Text type="secondary">
+        {on ? trueLabel : falseLabel}
+      </Typography.Text>
+    </Flex>
+  );
+};
+
+// ── select ───────────────────────────────────────────────────────────────────
+
+/**
+ * `select` → `Segmented` for a small single choice, `Select` otherwise
+ * (multiple when the config allows more than one).
+ *
+ * `maxSelected` absent means UNLIMITED — that is the engine's own
+ * `SelectConfig` default, and reading an absent key as 1 would silently turn
+ * every unconfigured select into a single-choice control.
+ */
+const SelectWidget: FormFieldWidget = (props: FormFieldWidgetProps) => {
+  const t = useT();
+  const cfg = config(props.field);
+  const choices = choiceList(props.field);
+  const maxSelected = numberish(cfg["maxSelected"]);
+  const multiple = maxSelected === undefined || maxSelected > 1;
+
+  if (!multiple && choices.length > 0 && choices.length <= SEGMENTED_MAX_OPTIONS) {
+    const current = str(Array.isArray(props.value) ? props.value[0] : props.value);
+    return (
+      <Segmented<string>
+        id={props.id}
+        options={[...choices]}
+        value={current}
+        disabled={props.disabled}
+        {...errorStatus(props.error)}
+        onChange={(next) => props.onChange(next)}
+      />
+    );
+  }
+
+  const value = multiple
+    ? (Array.isArray(props.value) ? props.value : props.value == null ? [] : [props.value]).map(
+        str
+      )
+    : str(Array.isArray(props.value) ? props.value[0] : props.value) || undefined;
+
+  return (
+    <Select
+      id={props.id}
+      style={{ width: "100%" }}
+      options={[...choices]}
+      disabled={props.disabled}
+      {...errorStatus(props.error)}
+            placeholder={t(FORMS_I18N_KEYS.fillSelectPlaceholder)}
+      {...(multiple ? { mode: "multiple" as const } : {})}
+      {...(multiple && maxSelected !== undefined ? { maxCount: maxSelected } : {})}
+      // `allowCustom` is the engine's word for "a value outside options is
+      // acceptable"; antd's word for the same affordance is a tags mode.
+      {...(cfg["allowCustom"] === true && multiple
+        ? { mode: "tags" as const }
+        : {})}
+      value={value}
+      onChange={(next: unknown) => props.onChange(next)}
+    />
+  );
+};
+
+// ── date ─────────────────────────────────────────────────────────────────────
+
+/** `precision` → the native input type that produces exactly the ISO string
+ * the attributes date type parses. */
+const DATE_INPUT_TYPE: Readonly<Record<string, string>> = {
+  month: "month",
+  date: "date",
+  datetime: "datetime-local",
+};
+
+const DateWidget: FormFieldWidget = (props: FormFieldWidgetProps) => {
+  const cfg = config(props.field);
+  const precision = str(cfg["precision"]) || "date";
+
+  // "Year only" is a number, not a date: a date input would force a month and
+  // a day the admin explicitly said they do not want.
+  if (precision === "year") {
+    return (
+      <InputNumber
+        style={{ width: "100%" }}
+        value={numberish(props.value) ?? null}
+        disabled={props.disabled}
+        {...errorStatus(props.error)}
+                step={1}
+        precision={0}
+        onChange={(next) => props.onChange(next ?? undefined)}
+      />
+    );
+  }
+
+  return (
+    <Input
+      id={props.id}
+      type={DATE_INPUT_TYPE[precision] ?? "date"}
+      value={str(props.value)}
+      disabled={props.disabled}
+      {...errorStatus(props.error)}
+            {...(str(cfg["minDate"]).length > 0 ? { min: str(cfg["minDate"]) } : {})}
+      {...(str(cfg["maxDate"]).length > 0 ? { max: str(cfg["maxDate"]) } : {})}
+      onChange={(event) => props.onChange(event.target.value || undefined)}
+    />
+  );
+};
+
+// ── header ───────────────────────────────────────────────────────────────────
+
+/**
+ * `header` → a caption, and NOT a control.
+ *
+ * It never calls `onChange`: the engine regenerates a header's DAO from its
+ * config and stapel-forms rejects an answer to one outright (backend delta
+ * note 1), so a header that could hold a value would only ever produce a
+ * refused submit. `config.style` is `l` (H1) or `m` (H2) — with the upstream
+ * default `"h2"` matching NEITHER (LN-B01, preserved), which is why anything
+ * that is not `l` reads as H2 rather than being looked up.
+ */
+const HeaderWidget: FormFieldWidget = (props: FormFieldWidgetProps) => {
+  const level = str(config(props.field)["style"]) === "l" ? 3 : 4;
+  return (
+    <Typography.Title level={level} style={{ marginBottom: 0 }}>
+      {props.field.name ?? ""}
+    </Typography.Title>
+  );
+};
+
+// ── hex_color ────────────────────────────────────────────────────────────────
+
+const HexColorWidget: FormFieldWidget = (props: FormFieldWidgetProps) => {
+  const presets = useMemo(() => {
+    const values = optionValues(props.field) ?? [];
+    return values.length > 0
+      ? [{ label: props.field.name ?? "", colors: values.map(str) }]
+      : undefined;
+  }, [props.field]);
+  const current = str(props.value);
+  return (
+    // antd's ColorPicker renders no labelable form control and accepts no
+    // `id`, so the field row's `<label for>` cannot reach it. The accessible
+    // name therefore comes from the trigger's own text (`showText`), and the
+    // wrapper carries the id so the label at least resolves to this region.
+    <span id={props.id}>
+    <ColorPicker
+      disabled={props.disabled}
+      format="hex"
+      {...(presets ? { presets } : {})}
+      {...(current.length > 0 ? { value: current } : {})}
+      onChange={(color) => props.onChange(color.toHexString())}
+      showText
+    />
+    </span>
+  );
+};
+
+// ── hierarchical_select ──────────────────────────────────────────────────────
+
+/** `hierarchical_select` → `Cascader`. The config's nested
+ * `{value, label, children}` options are already the shape antd wants, and
+ * the answer is the path array the engine stores. */
+const HierarchicalSelectWidget: FormFieldWidget = (props: FormFieldWidgetProps) => {
+  const t = useT();
+  const raw = config(props.field)["options"];
+  const options = Array.isArray(raw) ? raw : [];
+  const value = Array.isArray(props.value) ? props.value.map(str) : undefined;
+  return (
+    <Cascader
+      id={props.id}
+      style={{ width: "100%" }}
+      options={options as never}
+      disabled={props.disabled}
+      {...errorStatus(props.error)}
+            placeholder={t(FORMS_I18N_KEYS.fillSelectPlaceholder)}
+      {...(value ? { value } : {})}
+      onChange={(next: unknown) => props.onChange(next ?? undefined)}
+    />
+  );
+};
+
+// ── convertible_unit ─────────────────────────────────────────────────────────
+
+/**
+ * `convertible_unit` → a number beside the unit it is expressed in.
+ *
+ * The one widget whose value is an OBJECT, because its wire DTO is:
+ * `{type: "convertible_unit", value, unit}` — the number as typed, tagged
+ * with which of the config's `unit_m` (metric) / `unit_i` (imperial) codes it
+ * is in. The server converts to the family's base unit before validating, so
+ * the widget must send the unit and must NOT convert anything itself.
+ *
+ * This kind has no upstream `config_form()` declaration, so it ships
+ * BUILDER-LESS (spec §12 risk 5) — it renders and submits correctly, it just
+ * cannot be configured in `<FormBuilderPane>`.
+ */
+const ConvertibleUnitWidget: FormFieldWidget = (props: FormFieldWidgetProps) => {
+  const cfg = config(props.field);
+  const units = [str(cfg["unit_m"]), str(cfg["unit_i"])].filter(
+    (code) => code.length > 0
+  );
+  const current =
+    props.value !== null && typeof props.value === "object"
+      ? (props.value as { value?: unknown; unit?: unknown })
+      : {};
+  const unit = str(current.unit) || units[0] || "";
+  const amount = numberish(current.value);
+  const precision = numberish(cfg["precision"]);
+
+  const emit = (nextAmount: number | undefined, nextUnit: string): void => {
+    if (nextAmount === undefined) {
+      props.onChange(undefined);
+      return;
+    }
+    props.onChange({
+      type: "convertible_unit",
+      value: nextAmount,
+      ...(nextUnit.length > 0 ? { unit: nextUnit } : {}),
+    });
+  };
+
+  return (
+    <Flex gap={8}>
+      <InputNumber
+        id={props.id}
+        style={{ flex: 1 }}
+        value={amount ?? null}
+        disabled={props.disabled}
+        {...errorStatus(props.error)}
+                {...(precision !== undefined ? { precision } : {})}
+        onChange={(next) => emit(next ?? undefined, unit)}
+      />
+      {units.length > 0 && (
+        <Select
+          style={{ width: 96 }}
+          disabled={props.disabled}
+          {...errorStatus(props.error)}
+          value={unit}
+          options={units.map((code) => ({ value: code, label: code }))}
+          onChange={(next) => emit(amount, next)}
+        />
+      )}
+    </Flex>
+  );
+};
+
+/**
+ * The skin's builtin widget per kind — the second rung of the ladder. A kind
+ * absent from this table has no default drawing and reaches the
+ * unsupported-field notice.
+ */
+export const BUILTIN_FIELD_WIDGETS: Readonly<Record<string, FormFieldWidget>> = {
+  string: StringWidget,
+  int: makeNumberWidget(true),
+  float: makeNumberWidget(false),
+  bool: BoolWidget,
+  select: SelectWidget,
+  date: DateWidget,
+  header: HeaderWidget,
+  hex_color: HexColorWidget,
+  hierarchical_select: HierarchicalSelectWidget,
+  convertible_unit: ConvertibleUnitWidget,
+};
+
+/** The kinds this skin can draw — handed to `<FormFill>` so the headless
+ * layer can judge `unsupportedKinds` without importing the skin. */
+export const BUILTIN_FIELD_KINDS: readonly string[] =
+  Object.keys(BUILTIN_FIELD_WIDGETS).sort();

package/src/default/index.ts

@@ -0,0 +1,71 @@
+/**
+ * `@stapel/forms-react/default` — the antd default skin.
+ *
+ * A SEPARATE entry point on purpose: the main entry is headless and carries
+ * no antd, so a host that renders its own visuals over `<FormFill>` never
+ * pays for this bundle (enforced by size-limit and the bundle-purity test).
+ *
+ * Three override levers, in increasing order of reach — none of which
+ * requires forking anything:
+ *
+ *  1. **props** (`mode`, `showTitle`, `submitLabel`);
+ *  2. **`registerFormFieldWidget(kind, …)`** — replace how one field kind
+ *     draws; a host registration outranks every builtin here;
+ *  3. **`registerFormsSkinComponent(slot, …)`** — replace a piece of the
+ *     skin itself (a field row, the submit bar, a response cell).
+ *
+ * And beneath all three: retheming through the §68 token JSON, which reaches
+ * this skin with zero code because every surface wraps itself in
+ * `<FormsSkinTheme>`.
+ */
+
+// ── surfaces ────────────────────────────────────────────────────────────────
+export { StapelForm } from "./StapelForm.js";
+export type {
+  StapelFormProps,
+  FieldRowSlotProps,
+  SubmitBarSlotProps,
+  ConfirmationSlotProps,
+  UnsupportedFieldSlotProps,
+} from "./StapelForm.js";
+
+export { FormBuilderPane } from "./FormBuilderPane.js";
+export type {
+  FormBuilderPaneProps,
+  BuilderToolbarSlotProps,
+  BuilderFieldRowSlotProps,
+} from "./FormBuilderPane.js";
+
+export { ResponsesPane } from "./ResponsesPane.js";
+export type {
+  ResponsesPaneProps,
+  ResponseCellSlotProps,
+  ResponsesToolbarSlotProps,
+} from "./ResponsesPane.js";
+
+export { FormsListPane } from "./FormsListPane.js";
+export type { FormsListPaneProps } from "./FormsListPane.js";
+
+// ── theming ─────────────────────────────────────────────────────────────────
+export { FormsSkinTheme } from "./theme.js";
+export type { FormsSkinThemeProps } from "./theme.js";
+export { ErrorAlert } from "./ErrorAlert.js";
+export type { ThemeModeProp } from "./types.js";
+
+// ── the two override registries ─────────────────────────────────────────────
+export {
+  registerFormsSkinComponent,
+  unregisterFormsSkinComponent,
+  resolveFormsSkinComponent,
+  registeredFormsSkinSlots,
+} from "./slots.js";
+export type { FormsSkinSlot } from "./slots.js";
+
+/** The skin's builtin widgets, exported so a host can WRAP one instead of
+ * replacing it outright (decorate the default rather than reimplement it). */
+export { BUILTIN_FIELD_WIDGETS, BUILTIN_FIELD_KINDS } from "./fields.js";
+
+/** The data-driven config-form row — exported for a host building its own
+ * builder over the same declarations. */
+export { ConfigField } from "./ConfigField.js";
+export type { ConfigFieldProps } from "./ConfigField.js";

package/src/default/slots.ts

@@ -0,0 +1,78 @@
+/**
+ * The skin-slot registry — the SECOND override lever of `/default`, beside
+ * the field-widget registry (`widgets/registry.ts`) and plain props.
+ *
+ * "A default the customer cannot swap is a decision, not a default"
+ * (spec §7.3). The widget registry lets a host replace how one FIELD KIND
+ * draws; this lets a host replace a piece of the SKIN — the row that wraps a
+ * field, the submit bar, the confirmation panel, a response cell — without
+ * forking the skin to get at it.
+ *
+ * ```tsx
+ * registerFormsSkinComponent("fill.submitBar", MySubmitBar);
+ * ```
+ *
+ * Slot names are a closed union on purpose: a typo in a string key would
+ * register a component that silently never renders, and "my override did
+ * nothing and nothing said so" is the exact failure this fleet keeps closing.
+ */
+import type { ComponentType } from "react";
+
+/**
+ * The slots `/default` renders through. Each name is `<surface>.<part>`.
+ *
+ * Adding a slot is additive; REMOVING one is a breaking change for any host
+ * that registered it, so a slot is only added where the default is genuinely
+ * a judgement call somebody might reasonably disagree with.
+ */
+export type FormsSkinSlot =
+  /** Wraps one field: label, control, error, required marker. */
+  | "fill.fieldRow"
+  /** The submit button and everything beside it (captcha, blocked reason). */
+  | "fill.submitBar"
+  /** What replaces the form once the server accepts it. */
+  | "fill.confirmation"
+  /** The notice shown in place of a field whose kind nothing can draw. */
+  | "fill.unsupportedField"
+  /** One cell of the responses grid. */
+  | "responses.cell"
+  /** The responses toolbar: version filter, export, paging. */
+  | "responses.toolbar"
+  /** One row of the builder's field list. */
+  | "builder.fieldRow"
+  /** The builder's save/publish/state controls. */
+  | "builder.toolbar";
+
+const slots = new Map<FormsSkinSlot, ComponentType<never>>();
+
+/**
+ * Replace a slot's component. Call at startup, before the first render.
+ *
+ * The props a slot receives are the ones the skin passes it — each slot's
+ * prop type is exported beside the component that renders it, so an override
+ * is written against a real type rather than by reading the skin's source.
+ */
+export function registerFormsSkinComponent<P>(
+  slot: FormsSkinSlot,
+  component: ComponentType<P>
+): void {
+  slots.set(slot, component as ComponentType<never>);
+}
+
+/** Remove an override, restoring the skin's own component. */
+export function unregisterFormsSkinComponent(slot: FormsSkinSlot): void {
+  slots.delete(slot);
+}
+
+/** The host's override for a slot, or `null` — the skin falls back to its
+ * own component. */
+export function resolveFormsSkinComponent<P>(
+  slot: FormsSkinSlot
+): ComponentType<P> | null {
+  return (slots.get(slot) as ComponentType<P> | undefined) ?? null;
+}
+
+/** Every slot with an override, sorted. */
+export function registeredFormsSkinSlots(): readonly FormsSkinSlot[] {
+  return [...slots.keys()].sort();
+}

package/src/default/theme.tsx

@@ -0,0 +1,65 @@
+/**
+ * The default skin's INTERNAL theme provider — every `/default` surface wraps
+ * itself in this, so the skin is readable no matter what the host supplies
+ * (tracker #26: a skin set with no internal provider once inherited a theme
+ * bridge serving light-mode values inside a dark document — text on
+ * background at 1.00:1). The theme derives from `@stapel/tokens` via
+ * `@stapel/tokens-antd`'s `toAntdThemeConfig(mode)`; `mode` defaults to what
+ * the HOST's document declares (`resolveThemeMode()` — the `data-theme`
+ * attribute `tokens.css` keys its dark block on), never to a hardcoded side.
+ *
+ * This is also what "override styles" means for this pair (spec §7.3): a host
+ * retheming through the §68 token JSON regenerates its `--stapel-*` custom
+ * properties, and the form follows with zero code — which is a far better
+ * deal than a prop-per-colour API, and the reason the skin has none.
+ */
+import { useMemo } from "react";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
+import { ConfigProvider } from "antd";
+import {
+  resolveThemeMode,
+  toAntdTheme,
+  toAntdThemeConfig,
+} from "@stapel/tokens-antd";
+import type { ThemeMode } from "@stapel/tokens-antd";
+
+export interface FormsSkinThemeProps {
+  /**
+   * Light or dark. Defaults to the mode the host's document declares
+   * (`resolveThemeMode()`). Pass explicitly to pin a side.
+   */
+  readonly mode?: ThemeMode;
+  /** Extra styles merged onto the themed root element (layout only — colors
+   * come from the mode). */
+  readonly style?: CSSProperties;
+  readonly children: ReactNode;
+}
+
+/**
+ * `<FormsSkinTheme/>` — the self-theming wrapper of
+ * `@stapel/forms-react/default`. Standalone use is supported (wrap any
+ * composition of the skin's parts once); the shipped surfaces
+ * (`StapelForm`, `FormBuilderPane`, `ResponsesPane`, `FormsListPane`) each
+ * already wrap themselves, and nested antd `ConfigProvider`s merge, so
+ * composing them under one `FormsSkinTheme` stays correct.
+ */
+export function FormsSkinTheme(props: FormsSkinThemeProps): ReactElement {
+  const mode = props.mode ?? resolveThemeMode();
+  const theme = useMemo(() => toAntdThemeConfig(mode), [mode]);
+  const token = useMemo(() => toAntdTheme(mode), [mode]);
+  return (
+    <ConfigProvider theme={theme}>
+      <div
+        data-forms-skin-root
+        data-forms-skin-mode={mode}
+        style={{
+          color: token.colorText,
+          backgroundColor: token.colorBgContainer,
+          ...props.style,
+        }}
+      >
+        {props.children}
+      </div>
+    </ConfigProvider>
+  );
+}

package/src/default/types.ts

@@ -0,0 +1,12 @@
+/**
+ * Small shared types for the `/default` skin — kept in one place so every
+ * surface takes the same `mode` prop and re-exports the same error dialect.
+ */
+export type { FlowError } from "@stapel/core";
+import type { ThemeMode } from "@stapel/tokens-antd";
+
+/** Every `/default` surface accepts a theme mode; absent means "whatever the
+ * host document declares" (`resolveThemeMode()`), never a hardcoded side. */
+export interface ThemeModeProp {
+  readonly mode?: ThemeMode;
+}