@dxos/react-ui-form 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/hooks/useAsyncFieldEffect.ts

@@ -0,0 +1,81 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import { useEffect, useRef, useState } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+
+/** Picks the declared dependency fields from the form values — the subset a dynamic field subscribes to. */
+export const pickValues = (values: AnyProperties | undefined, deps: readonly string[]): Record<string, unknown> => {
+  const subset: Record<string, unknown> = {};
+  for (const dep of deps) {
+    subset[dep] = values?.[dep];
+  }
+  return subset;
+};
+
+export type AsyncFieldEffectState<A> = {
+  loading: boolean;
+  error: unknown;
+  data: A | undefined;
+};
+
+export type UseAsyncFieldEffectOptions = {
+  /** Debounce applied before running, so per-keystroke value changes coalesce into one run. */
+  debounceMs?: number;
+  /** When false, the effect is not run and prior data/error is cleared. */
+  enabled?: boolean;
+};
+
+/**
+ * Runs a self-contained Effect (`R = never`) whenever `key` changes, debounced and abortable. Used by
+ * dynamic form fields to load select options, derive values, or validate against an external source from
+ * the current form values. The latest `factory` is always used, but a run is only (re)triggered when
+ * `key` changes — derive `key` from the inputs the factory actually reads. Re-running interrupts the
+ * prior run (cancelling any in-flight request).
+ */
+export const useAsyncFieldEffect = <A>(
+  factory: () => Effect.Effect<A, unknown>,
+  key: string,
+  { debounceMs = 400, enabled = true }: UseAsyncFieldEffectOptions = {},
+): AsyncFieldEffectState<A> => {
+  const factoryRef = useRef(factory);
+  factoryRef.current = factory;
+  const [state, setState] = useState<AsyncFieldEffectState<A>>({ loading: false, error: undefined, data: undefined });
+
+  useEffect(() => {
+    if (!enabled) {
+      setState({ loading: false, error: undefined, data: undefined });
+      return;
+    }
+
+    let cancel: (() => void) | undefined;
+    const timer = setTimeout(() => {
+      setState((prev) => ({ ...prev, loading: true, error: undefined }));
+      cancel = Effect.runCallback(factoryRef.current(), {
+        onExit: (exit: Exit.Exit<A, unknown>) => {
+          Exit.match(exit, {
+            onSuccess: (data) => setState({ loading: false, error: undefined, data }),
+            onFailure: (cause) => {
+              // A superseding run interrupts this one; ignore the resulting interruption.
+              if (!Cause.isInterruptedOnly(cause)) {
+                setState((prev) => ({ loading: false, error: Cause.squash(cause), data: prev.data }));
+              }
+            },
+          });
+        },
+      });
+    }, debounceMs);
+
+    return () => {
+      clearTimeout(timer);
+      cancel?.();
+    };
+  }, [key, enabled, debounceMs]);
+
+  return state;
+};

package/src/hooks/useFormContext.ts

@@ -0,0 +1,89 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import * as SchemaAST from 'effect/SchemaAST';
+import { useEffect, useMemo, useRef } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+import { SchemaEx } from '@dxos/effect';
+
+import { type FieldContext, type FormFieldStateProps } from '#types';
+
+import { type FormVariant } from '../components/Form/Form.theme';
+import { type FormHandler } from './useFormHandler';
+
+//
+// Context
+//
+
+export type FormContextValue<T extends AnyProperties = any> = {
+  /**
+   * Form handler.
+   */
+  form: FormHandler<T>;
+
+  /**
+   * Testing.
+   */
+  testId?: string;
+
+  /** Visual variant applied across the form's parts (see Form.theme). */
+  variant?: FormVariant;
+} & FieldContext;
+
+export const [FormContextProvider, useFormContext] = createContext<FormContextValue>('Form');
+
+/**
+ * Get the current form values.
+ */
+export const useFormValues: {
+  <T extends AnyProperties>(componentName: string, path?: (string | number)[]): T;
+  <T extends AnyProperties>(
+    componentName: string,
+    path: (string | number)[] | undefined,
+    defaultValue: () => T,
+  ): T | undefined;
+} = (componentName: string, path?: (string | number)[], defaultValue?: () => any) => {
+  const stablePath = useMemo(() => path ?? [], [path ? path.join('.') : undefined]);
+  const jsonPath = SchemaEx.createJsonPath(stablePath);
+  const {
+    form: { values, onValueChange },
+  } = useFormContext(componentName);
+
+  const value = SchemaEx.getValue(values, jsonPath);
+
+  // Apply default value once when the field has no value. lastAppliedPathRef prevents
+  // re-applying on every render (e.g. when defaultValue() returns null) and ensures
+  // we apply per path when the hook is used for different fields.
+  const lastAppliedPathRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (value == null && defaultValue && lastAppliedPathRef.current !== jsonPath) {
+      lastAppliedPathRef.current = jsonPath;
+      onValueChange(stablePath, SchemaAST.stringKeyword, defaultValue());
+    }
+  }, [value, defaultValue, onValueChange, stablePath, jsonPath]);
+
+  return value;
+};
+
+/**
+ * Get the state props for the given field.
+ */
+export const useFormFieldState = (componentName: string, path: (string | number)[] = []): FormFieldStateProps => {
+  const stablePath = useMemo(() => path, [Array.isArray(path) ? path.join('.') : path]);
+  const {
+    form: { getStatus, getValue, onBlur, onValueChange },
+  } = useFormContext(componentName);
+
+  return useMemo(
+    () => ({
+      getStatus: () => getStatus(stablePath),
+      getValue: () => getValue(stablePath),
+      onBlur: () => onBlur(stablePath),
+      onValueChange: (ast: SchemaAST.AST, value: any) => onValueChange(stablePath, ast, value),
+    }),
+    [getStatus, getValue, onBlur, onValueChange, stablePath],
+  );
+};

package/src/hooks/useFormHandler.ts

@@ -14,10 +14,7 @@ import { useDefaultValue } from '@dxos/react-ui';
 import { type ValidationError, validateSchema } from '@dxos/schema';
 import { type MaybePromise } from '@dxos/util';
 
-export type FormFieldStatus = {
-  status?: 'error';
-  error?: string;
-};
+import { type FormFieldStatus } from '#types';
 
 /**
  * Form properties.
@@ -80,17 +77,21 @@ export type FormHandler<T extends AnyProperties> = Pick<FormHandlerProps<T>, 'sc
   /** Initial values (which may not pass validation). */
   values: Partial<T>;
 
-  /** Map of changed fields. */
+  /** Fields whose value has been edited (set by `onValueChange`). Gates autosave-on-blur. */
   changed: Record<SchemaEx.JsonPath, boolean>;
-  // TODO(burdon): How is this different from above?
+  /** Fields the user has interacted with (set by `onBlur`). Gates error *visibility* — errors only surface once touched. */
   touched: Record<SchemaEx.JsonPath, boolean>;
 
   /** Map of error strings. */
   errors: Record<SchemaEx.JsonPath, string>;
 
-  /** Whether the form can be saved (i.e., data is valid). */
+  /** Whether the values pass validation (no errors at all). */
   isValid: boolean;
-  // TODO(burdon): Why is this needed separately from isValid?
+  /**
+   * Whether the submit affordance should be enabled. Stricter than `isValid`: it also requires no save
+   * in flight (`saving`) and only blocks on errors for *touched* fields, so a pristine form with
+   * not-yet-touched required fields can still show an enabled control.
+   */
   canSave: boolean;
 
   onSave: () => void;
@@ -328,6 +329,7 @@ export const useFormHandler = <T extends AnyProperties>({
     }),
     [
       schema,
+      autoSave,
       values,
       errors,
       touched,
@@ -338,8 +340,8 @@ export const useFormHandler = <T extends AnyProperties>({
       getValue,
       onBlur,
       onValueChange,
-      onSave,
-      onCancel,
+      handleSave,
+      handleCancel,
     ],
   );
 };

package/src/index.ts

@@ -2,6 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './annotations';
 export * from './components';
 export * from './hooks';
+export * from './types';
 export * from './util';

package/src/{components/testing.tsx → testing/TestLayout.tsx}

@@ -7,23 +7,26 @@ import React, { type PropsWithChildren } from 'react';
 import { type ThemedClassName } from '@dxos/react-ui';
 import { composableProps, slottable } from '@dxos/react-ui';
 import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { mx } from '@dxos/ui-theme';
 
-type TestLayoutProps = PropsWithChildren<{ json?: any }>;
+type TestLayoutProps = PropsWithChildren<{ json?: unknown }>;
 
 export const TestLayout = ({ children, json }: TestLayoutProps) => {
   return (
-    <div className='dx-container grid grid-cols-[1fr_1fr] p-4 gap-4'>
+    <div className={mx('dx-container grid grid-cols-1 p-4 gap-4', !!json && 'grid-cols-[1fr_1fr]')}>
       <TestPanel>{children}</TestPanel>
-      <TestPanel>
-        <Syntax.Root data={json}>
-          <Syntax.Content>
-            <Syntax.Filter />
-            <Syntax.Viewport>
-              <Syntax.Code testId='debug' classNames='text-sm' />
-            </Syntax.Viewport>
-          </Syntax.Content>
-        </Syntax.Root>
-      </TestPanel>
+      {!!json && (
+        <TestPanel>
+          <Syntax.Root data={json}>
+            <Syntax.Content>
+              <Syntax.Filter />
+              <Syntax.Viewport>
+                <Syntax.Code testId='debug' classNames='text-sm' />
+              </Syntax.Viewport>
+            </Syntax.Content>
+          </Syntax.Root>
+        </TestPanel>
+      )}
     </div>
   );
 };
@@ -32,7 +35,7 @@ type TestPanelProps = ThemedClassName<PropsWithChildren>;
 
 export const TestPanel = slottable<HTMLDivElement, TestPanelProps>(({ children }, forwardedRef) => {
   return (
-    <div {...composableProps({ classNames: 'dx-container bg-card-surface rounded-md' })} ref={forwardedRef}>
+    <div {...composableProps({ classNames: 'dx-container dx-card-surface rounded-sm' })} ref={forwardedRef}>
       {children}
     </div>
   );

package/src/testing/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './schema';
+
+export * from './TestLayout';

package/src/testing/schema.ts

@@ -0,0 +1,59 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, DXN, Format, Ref, Tag, Type } from '@dxos/echo';
+
+/**
+ * Shared test schemas for form stories. Intentionally small, hand-written types
+ * (not `@dxos/types`) exercising the range of field renderers: scalars, nested
+ * structs, refs, ref arrays, enums, and the various formats.
+ */
+
+export class Organization extends Type.makeObject<Organization>(DXN.make('com.example.type.organization', '0.1.0'))(
+  Schema.Struct({
+    name: Schema.String.pipe(Schema.minLength(1)).annotations({ title: 'Full name' }),
+  }),
+) {}
+
+export class Person extends Type.makeObject<Person>(DXN.make('org.dxos.type.person', '0.1.0'))(
+  Schema.Struct({
+    name: Schema.String.pipe(Schema.minLength(1)).annotations({ title: 'Full name' }),
+    ignore: Schema.String.pipe(Annotation.FormInputAnnotation.set(false), Schema.optional),
+    active: Schema.optional(Schema.Boolean.annotations({ title: 'Active' })),
+    address: Schema.optional(
+      Schema.Struct({
+        street: Schema.String,
+        city: Schema.String,
+        // TODO(burdon): Constrain input control.
+        state: Schema.String.pipe(Schema.minLength(2), Schema.maxLength(2)).annotations({
+          title: 'State',
+          description: 'State code',
+        }),
+        zip: Schema.Number.annotations({ title: 'ZIP Code' }),
+      }).annotations({ title: 'Address' }),
+    ),
+    employer: Schema.optional(Ref.Ref(Organization).annotations({ title: 'Employer' })),
+    tags: Schema.optional(Schema.Array(Ref.Ref(Tag.Tag)).annotations({ title: 'Tags' })),
+    status: Schema.optional(Schema.Literal('active', 'inactive').annotations({ title: 'Status' })),
+    notes: Schema.optional(Format.Text.annotations({ title: 'Notes' })),
+    location: Schema.optional(Format.GeoPoint.annotations({ title: 'Location' })),
+    birthday: Schema.optional(Format.DateOnly.annotations({ title: 'Birthday' })),
+    meetingAt: Schema.optional(Format.DateTime.annotations({ title: 'Next meeting' })),
+    reminderAt: Schema.optional(Format.TimeOnly.annotations({ title: 'Reminder time' })),
+    tasks: Schema.optional(Schema.Array(Schema.String).annotations({ title: 'Tasks' })),
+    locations: Schema.optional(Schema.Array(Format.GeoPoint).annotations({ title: 'Locations' })),
+    identities: Schema.optional(
+      Schema.Array(
+        Schema.Struct({
+          type: Schema.String.annotations({ title: 'Type' }),
+          value: Schema.String.annotations({ title: 'Value' }),
+        }).annotations({ title: 'Identities' }),
+      ).annotations({
+        title: 'Identities',
+      }),
+    ),
+  }),
+) {}

package/src/types.ts

@@ -0,0 +1,186 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+import type * as SchemaAST from 'effect/SchemaAST';
+import { type FC, type FocusEvent, type ReactElement } from 'react';
+
+import { type Database, type Entity, type Format, type Obj, type Type } from '@dxos/echo';
+import { type URI } from '@dxos/keys';
+import { type Palette } from '@dxos/react-ui';
+import { type ProjectionModel } from '@dxos/schema';
+
+//
+// Field component contracts.
+//
+
+/**
+ * Validation status of a field.
+ */
+export type FormFieldStatus = {
+  status?: 'error';
+  error?: string;
+};
+
+/**
+ * FormPresentation mode.
+ * - full: Show label, control, and status.
+ * - compact: Show label and control.
+ * - inline: Control only.
+ * - static: Plain DOM; omit all undefined values.
+ */
+export type FormPresentation = 'full' | 'compact' | 'inline' | 'static';
+
+/**
+ * Dynamic props passed to input components.
+ */
+export type FormFieldStateProps<T = any> = {
+  getStatus: () => FormFieldStatus;
+  getValue: () => T | undefined;
+  onBlur: (event: FocusEvent<HTMLElement>) => void;
+  onValueChange: (type: SchemaAST.AST, value: T) => void;
+};
+
+/**
+ * Props passed to input components.
+ */
+export type FormFieldRendererProps<T = any> = {
+  /** Database the form is editing against; populated for fields whose value is an ECHO object/Ref. */
+  db?: Database.Database;
+  type: SchemaAST.AST;
+  format?: Format.TypeFormat;
+  readonly?: boolean;
+  label: string;
+  /**
+   * Human-readable description (from the schema's description annotation). Rendered as visible text
+   * only when the resolved presentation opts in; otherwise it falls back to the input placeholder.
+   */
+  description?: string;
+  /**
+   * Dotted JSON path of this field within the form values (e.g. `runtime.client.storage.persistent`).
+   */
+  jsonPath?: string;
+  placeholder?: string;
+  autoFocus?: boolean;
+  /** Presentation mode for the field (full/compact/inline/static); see {@link FormPresentation}. */
+  presentation?: FormPresentation;
+  /** Whether the field is required (non-optional in the schema); surfaces a trailing asterisk on the label. */
+  required?: boolean;
+} & FormFieldStateProps<T>;
+
+export type FormFieldRenderer = FC<FormFieldRendererProps>;
+
+export type FormFieldMap = Record<string, FormFieldRenderer>;
+
+export type FormFieldProvider = (props: {
+  prop: string;
+  schema: Schema.Schema<any>;
+  fieldProps: FormFieldRendererProps;
+}) => ReactElement | null | undefined;
+
+//
+// Ref / create contracts.
+//
+
+/**
+ * Per-typename override for the ref-field inline create form and its submission handler.
+ * The type parameter S links the form schema's decoded type to the createObject values argument,
+ * ensuring the schema and the handler agree on the shape of the form data.
+ */
+export type CreateEntryOverride<S extends Schema.Schema.AnyNoContext = Schema.Schema.AnyNoContext> = {
+  /** Replaces the raw ECHO type schema for the inline create form. */
+  inputSchema?: S;
+  /** Runs instead of the default onCreate(schema, values) path; values are typed from inputSchema. */
+  createObject?: (values: Schema.Schema.Type<S>, db: Database.Database) => Promise<Obj.Unknown>;
+};
+
+/**
+ * Configuration for the inline "create a new referenced object" affordance, shared by every
+ * surface that can spawn a ref target (the picker, `RefField`, and the `Form*` props that forward
+ * to them). `onCreate` is intentionally NOT part of this group: its signature differs per consumer
+ * (the picker takes `(values)`, `RefField` takes `(schema, values)`).
+ */
+export type CreateOptions = {
+  createOptionLabel?: [string, { ns: string | readonly string[] }];
+  createOptionIcon?: string;
+  createInitialValuePath?: string;
+  createFieldMap?: FormFieldMap;
+};
+
+export type RefOption = {
+  id: string;
+  label: string;
+  /** Optional secondary line shown beneath the label in the picker list. */
+  description?: string;
+  hue?: Palette;
+};
+
+/**
+ * Data plumbing for resolving and creating ref targets: how to look up the ref type, query
+ * candidate objects, map them to options, and persist a newly-created one.
+ */
+export type RefFieldDataProps = {
+  // TODO(burdon): Replace hooks with callbacks?
+  useType?: (db?: Database.Database, typeUri?: URI.URI) => Type.AnyEntity;
+  useResults?: (db?: Database.Database, typename?: string) => Entity.Any[];
+  getOptions?: (
+    objects: Entity.Any[],
+    options?: { parentLabel?: boolean; getTypePlaceholder?: (typename: string) => string },
+  ) => RefOption[];
+  /**
+   * Persist a newly-created object. Called after the user fills out the inline create form and
+   * clicks Save. Should add the object to the database and return it (sync or async). The returned
+   * object is then wired into this slot's form value as a Ref.
+   */
+  onCreate?: (schema: Type.AnyEntity, values: any) => Obj.Unknown | Promise<Obj.Unknown> | undefined | void;
+  /**
+   * Supply default values for a newly-created owned object when the user clicks "add" on an owned-ref
+   * array field (see `FormCreateAnnotation`). Keyed by the field's json path so a container can pre-populate
+   * the new object (e.g. a back-reference to the parent). The returned values are passed to
+   * `onCreate(schema, values)` before the object is persisted.
+   */
+  getCreateDefaults?: (props: { jsonPath: string; schema: Type.AnyEntity }) => Record<string, unknown> | undefined;
+  /**
+   * Optional resolver that maps a ref's typename to a {@link CreateEntryOverride}, replacing the
+   * raw ECHO type schema and/or the default `onCreate` path with plugin-registered create logic
+   * (e.g. `SpaceCapabilities.CreateObjectEntry`). When absent or returning `undefined` for a given
+   * typename the existing fallback behaviour is preserved.
+   */
+  resolveCreateEntry?: (typename: string) => CreateEntryOverride | undefined;
+};
+
+/**
+ * Form-wide field options carried by the form context and threaded down to every field. The
+ * canonical source for the config that `FormContextValue`, `FormFieldProps`, and `FormFieldSetProps`
+ * all share — so none of them has to reach "up" into another's props to express it.
+ */
+export type FormFieldOptions = {
+  db?: Database.Database;
+  readonly?: boolean;
+  layout?: FormPresentation;
+  projection?: ProjectionModel;
+  fieldMap?: FormFieldMap;
+  fieldProvider?: FormFieldProvider;
+  /**
+   * Typename of the ref type that the create props apply to.
+   * When set, the create affordance is only offered to ref fields whose typename matches.
+   */
+  createTypename?: string;
+};
+
+/**
+ * The subset of {@link RefFieldDataProps} that is forwarded down the field recursion. `useResults`
+ * is consumed only by `RefField` itself (it defaults internally), so it is not threaded.
+ */
+export type RefThreadedProps = Pick<
+  RefFieldDataProps,
+  'useType' | 'getOptions' | 'onCreate' | 'getCreateDefaults' | 'resolveCreateEntry'
+>;
+
+/**
+ * Form-wide configuration threaded unchanged down the entire field recursion. This is the single
+ * canonical source for the bag that `FormContextValue`, `FormFieldProps`, and `FormFieldSetProps`
+ * all carry — so none of them re-Picks fragments of the others.
+ */
+export type FieldContext = FormFieldOptions & CreateOptions & RefThreadedProps;

package/src/util/index.ts

@@ -3,7 +3,7 @@
 //
 
 export * from './field';
-export * from './field-type';
 export * from './formatting';
+export * from './omit';
 export * from './properties';
 export * from './refs';

package/src/util/omit.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { Annotation, Type } from '@dxos/echo';
+
+// TODO(burdon): Reconcile with @dxos/echo.
+// Distributive: applied per union member so `ExcludeId<A | B>` → `ExcludeId<A> | ExcludeId<B>` rather
+// than `Omit<InstanceType<A> | InstanceType<B>, 'id'>` (which would intersect away per-member narrowing).
+export type ExcludeId<S extends Schema.Schema.AnyNoContext | Type.AnyEntity> = S extends Type.AnyEntity
+  ? Omit<Type.InstanceType<S>, 'id'>
+  : S extends Schema.Schema.AnyNoContext
+    ? Omit<Schema.Schema.Type<S>, 'id'>
+    : never;
+
+// TODO(burdon): Move to @dxos/schema (re-export here).
+export const omitId = <S extends Schema.Schema.AnyNoContext | Type.AnyEntity>(
+  schemaOrType: S,
+): Schema.Schema<ExcludeId<S>, ExcludeId<S>> => {
+  const schema = Type.isType(schemaOrType)
+    ? Type.getSchema(schemaOrType)
+    : (schemaOrType as Schema.Schema.AnyNoContext);
+  // Cast: `Schema.omit` cannot statically express the `ExcludeId<S>` result type, so the result is a
+  // widened schema; the runtime shape matches the declared return type.
+  return omitIdFromSchema(schema) as any;
+};
+
+/**
+ * Removes the `id` field where present, preserving the schema's shape. Recurses into unions so a
+ * discriminated (create) schema keeps its discriminant — `Schema.omit('id')` is a struct operation and
+ * would otherwise flatten the union, breaking variant rendering. A no-op when there is no `id` (plain
+ * create structs that never carried one).
+ */
+const omitIdFromSchema = (schema: Schema.Schema.AnyNoContext): Schema.Schema.AnyNoContext => {
+  const ast = schema.ast;
+  if (SchemaAST.isUnion(ast)) {
+    return Schema.Union(...ast.types.map((type) => omitIdFromSchema(Schema.make(type))));
+  }
+  const hasId = SchemaAST.getPropertySignatures(ast).some((prop) => prop.name === 'id');
+  return hasId ? schema.pipe(Schema.omit('id')) : schema;
+};
+
+/**
+ * Drop fields annotated with `FormInputAnnotation.set(false)` from a schema so
+ * the form's validator doesn't trip on required-but-hidden fields. Used by
+ * the picker's inline create form, where a `FactoryAnnotation` typically
+ * supplies the hidden values (e.g. a backing-object Ref) outside the form.
+ */
+export const omitHiddenFormFields = <S extends Schema.Schema.AnyNoContext>(schema: S): S => {
+  const properties = SchemaAST.getPropertySignatures(schema.ast);
+  const hidden = properties
+    .filter((prop) => Option.getOrElse(Annotation.FormInputAnnotation.getFromAst(prop.type), () => true) === false)
+    .map((prop) => prop.name as string);
+  // Cast: omitting a dynamically-computed set of keys can't be expressed as the original `S`, but
+  // the result is structurally a subset of `S` and callers treat it as `S`.
+  return hidden.length === 0 ? schema : (schema.pipe(Schema.omit(...(hidden as [string, ...string[]]))) as any);
+};