fluid-primitives 0.19.1 → 1.0.0-beta.1

package/dist/index-B06gIN_k.d.ts

@@ -0,0 +1,1358 @@
+import * as asyncList from "@zag-js/async-list";
+import { Attrs, VanillaMachine, mergeProps, normalizeProps as normalizeProps$1, spreadProps } from "@zag-js/vanilla";
+import { CollectionItem, ListCollection } from "@zag-js/collection";
+import { EventObject, InputProps, Machine, MachineSchema } from "@zag-js/core";
+import { CommonProperties, DirectionProperty, JSX, PropTypes } from "@zag-js/types";
+
+//#region Resources/Private/Client/src/lib/async-list.d.ts
+/** The options of an {@link AsyncList}: the props of the `@zag-js/async-list` machine. */
+type AsyncListOptions<T, Filter = string, Sorting = asyncList.SortDescriptor<T>, Cursor = string> = asyncList.Props<T, Filter, Sorting, Cursor>;
+/**
+ * Wraps the machine of `@zag-js/async-list` for use without any DOM or hydration: construct it, call
+ * `init()`, `subscribe()` to state changes and `destroy()` when done. Rendering is yours, do it from
+ * inside `subscribe()`.
+ *
+ * Debouncing or throttling `setFilter()` is left to the caller, wrap the call site with the
+ * `debounce` or `throttle` of `@zag-js/utils`, which this library already depends on.
+ */
+declare class AsyncList<T, Filter = string, Sorting = asyncList.SortDescriptor<T>, Cursor = string> {
+  private machine;
+  constructor(options: AsyncListOptions<T, Filter, Sorting, Cursor>);
+  /** The api of the current state of the list. It is read fresh on every access, don't hold on to it. */
+  get api(): asyncList.Api<T, Filter, Sorting, Cursor>;
+  /**
+   * Calls `fn` with the api on every future state change. It does not fire for the current state,
+   * read `api` first if you need it.
+   *
+   * @param fn - The listener.
+   * @returns A function that removes the listener.
+   */
+  subscribe(fn: (api: asyncList.Api<T, Filter, Sorting, Cursor>) => void): () => void;
+  /** Sets the filter and reloads the list with it. */
+  setFilter(filter: Filter): void;
+  /**
+   * Changes options at runtime, e.g. `dependencies` to trigger an `autoReload`. `load` is fixed
+   * when the list is constructed and can't be swapped here.
+   */
+  updateProps(newProps: Partial<Omit<asyncList.Props<T, Filter, Sorting, Cursor>, 'load'>>): void;
+  /** Starts the machine, which loads the list for the first time. Call it once, after constructing. */
+  init(): void;
+  /** Stops the machine and cancels a load that is in flight. */
+  destroy(): void;
+}
+//#endregion
+//#region Resources/Private/Client/src/lib/client-prop-converters.d.ts
+/**
+ * Converts a prop from the shape it has on the wire (JSON) to the one the component needs. It gets
+ * the wire value and all props of the component.
+ */
+type ClientPropConverter<TWire = unknown, TMachine = unknown> = (wireValue: TWire, props: Record<string, unknown>) => TMachine;
+/** The converters of one component, by prop name. */
+type ClientPropConverterMap = Record<string, ClientPropConverter<any, any>>;
+/**
+ * The shape each prop of a converters object has after conversion. Use it for the
+ * `HydrationPropsOverrides` of a component, derived from the converters with `typeof` instead of
+ * typed a second time.
+ */
+type ConverterMachineProps<T extends ClientPropConverterMap> = { [K in keyof T]: T[K] extends ClientPropConverter<any, infer TMachine> ? TMachine : never };
+/**
+ * Registers which props of a component need converting before a `mountAll()` or `mount()` callback
+ * receives them, e.g. the `collection` of a Select: JSON on the wire, a `ListCollection` once
+ * converted.
+ *
+ * @param componentName - The component, e.g. `select`.
+ * @param propConverters - The converters, by prop name.
+ */
+declare function registerClientPropConverters<T extends ClientPropConverterMap>(componentName: string, propConverters: T): void;
+/**
+ * @internal
+ *
+ * Runs every registered converter for `componentName` against `props`, called for every
+ * registered key regardless of whether it's actually present on `props` - a converter is
+ * registered per prop *name*, not per wire value, so it can supply a default for a prop the wire
+ * data omitted entirely (e.g. Combobox's `collection` when a purely async, searchUrl-only combobox
+ * sends none).
+ */
+declare function applyClientPropConverters(componentName: string, props: Record<string, unknown>): Record<string, unknown>;
+//#endregion
+//#region Resources/Private/Client/src/types.d.ts
+declare global {
+  interface Window {
+    FluidPrimitives: {
+      /**
+       * Nested by Fluid namespace identifier first (e.g. "ui"/"primitives" - the same prefix
+       * a `mountAll`/`mount` call must use, see `parseNamespacedComponentName`), then by the
+       * bare component name, then by rootId - never a flat `"ui:select"`-string-keyed map.
+       * Two collections can legitimately register a same-named component with a different
+       * shape (a styled wrapper around a primitive it doesn't expose every prop of), and
+       * nesting by namespace first keeps those genuinely separate.
+       */
+      hydrationData: {
+        [namespace: string]: {
+          [componentName: string]: {
+            [id: string]: ComponentHydrationData;
+          };
+        };
+      };
+      globals?: FluidPrimitivesGlobals;
+      /**
+       * Every component instance `mountAll`/`mount` has created, nested the same way as
+       * `hydrationData` above - populated by both, so `getComponentInstance` can find a
+       * component that was mounted by hand with `mount` too.
+       */
+      componentInstances: {
+        [namespace: string]: {
+          [componentName: string]: {
+            [id: string]: Component<unknown, unknown>;
+          };
+        };
+      };
+      /**
+       * Root components PHP found nested inside a tracked scope - a `ui:template` stencil, or
+       * a FieldArray row - keyed by that scope's own id (see
+       * `HydrationRegistry::recordNestedComponent()`'s own docblock for why this exists rather
+       * than inferring nesting from rendered DOM shape). Read via
+       * {@see getNestedComponents}, not indexed directly.
+       */
+      nestedComponents?: {
+        [scopeId: string]: NestedComponentEntry[];
+      };
+    };
+  }
+}
+/** @internal */
+interface NestedComponentEntry {
+  /**
+   * The nested component's own hydration registry key, "namespace:clientBaseName" (e.g.
+   * "primitives:field") - a single opaque, round-tripped string, never parsed/indexed as an
+   * object path the way `hydrationData`/`componentInstances` are.
+   */
+  name: string;
+  /** Its bare rootId - the same form `ComponentHydrator`'s own `rootId` uses, no namespace prefix. */
+  id: string;
+}
+/** @internal */
+interface ComponentInterface<Api> {
+  document: Document;
+  machine: VanillaMachine<any>;
+  api: Api;
+  hydrator: ComponentHydrator;
+  init(): void;
+  destroy(): void;
+  render(): void;
+}
+/** The hydration entry of one component instance, as PHP renders it for `mountAll()` and `mount()`. */
+interface ComponentHydrationData {
+  /** Whether the instance mounts on its own: `false` when it was rendered with `autoMount="{false}"`. */
+  autoMount: boolean;
+  /** The props of the instance. Typed per component by `HydrationPropsRegistry`. */
+  props: {
+    id: string;
+    ids: {
+      [key: string]: string;
+    };
+    [key: string]: unknown;
+  };
+}
+/**
+ * Types the `props` of `mountAll()` and `mount()` per component. It is empty on purpose: a project
+ * fills it with its own generated types, keyed by the namespaced name used at the call site.
+ * A component that is not in it gets the untyped `props` of `ComponentHydrationData`.
+ *
+ * @example
+ * ```typescript
+ * declare module 'fluid-primitives' {
+ *     interface HydrationPropsRegistry {
+ *         'ui:select': SelectHydrationProps;
+ *     }
+ * }
+ * ```
+ */
+interface HydrationPropsRegistry {}
+/**
+ * Overrides the type of the props whose shape changes through a registered client prop converter,
+ * for example the `collection` of a Select: JSON on the wire, a `ListCollection` once converted.
+ * It is keyed by the bare component name. Derive each entry from the converters with
+ * `ConverterMachineProps` instead of typing it by hand.
+ */
+interface HydrationPropsOverrides {}
+/** @internal */
+type KnownComponentName = Extract<keyof HydrationPropsRegistry, string>;
+/**
+ * `K` with any `"namespace:"` prefix stripped (e.g. `"ui:select"` -> `"select"`) - converters (see
+ * `client-prop-converters.ts`) are registered once per TS class under its own bare name,
+ * independent of which namespace ends up mounting it, so {@see HydrationPropsOverrides} stays
+ * bare-keyed even though {@see HydrationPropsRegistry} itself is namespaced.
+ */
+type BareComponentName<K extends string> = K extends `${string}:${infer BaseName}` ? BaseName : K;
+type PickOverride<K extends string> = BareComponentName<K> extends keyof HydrationPropsOverrides ? HydrationPropsOverrides[BareComponentName<K>] : object;
+/**
+ * The `props` type of the callback of `mountAll()` and `mount()` for the component name `K`: its
+ * entry in `HydrationPropsRegistry`, with the props that have a converter replaced by their
+ * `HydrationPropsOverrides`. A name that is not in the registry gets the untyped props.
+ */
+type HydrationPropsFor<K extends string> = K extends keyof HydrationPropsRegistry ? Omit<HydrationPropsRegistry[K], keyof PickOverride<K>> & PickOverride<K> : ComponentHydrationData['props'];
+/** @internal */
+interface FluidPrimitivesGlobals {
+  locale?: string;
+  /**
+   * Enables dev-only checks. Set automatically to whether
+   * TYPO3's own Application Context is development (see `HydrationRegistry::resolveGlobals()`),
+   * nothing for a consumer to configure. These checks aren't gated by a bundler env variable, so
+   * nothing is stripped from the production bundle either way - they simply never run unless
+   * this is true.
+   */
+  debug?: boolean;
+  [key: string]: unknown;
+}
+//#endregion
+//#region Resources/Private/Client/src/lib/component.d.ts
+/**
+ * Base class of every primitive. A subclass builds its machine in `initMachine()`, connects it in
+ * `initApi()` and spreads the props of its parts onto the DOM in `render()`. Call `init()` once to
+ * start it.
+ *
+ * @example
+ * ```typescript
+ * class Counter extends Component<CounterProps, CounterApi> {
+ *     static componentName = 'counter';
+ *
+ *     initMachine(props: CounterProps) {
+ *         return new Machine(counter.machine, props);
+ *     }
+ *
+ *     initApi() {
+ *         return counter.connect(this.machine.service, normalizeProps);
+ *     }
+ *
+ *     render() {
+ *         const rootEl = this.hydrator.query('root');
+ *         if (rootEl) this.spreadProps(rootEl, this.api.getRootProps());
+ *     }
+ * }
+ * ```
+ */
+declare abstract class Component<Props, Api> implements ComponentInterface<Api> {
+  #private;
+  private readonly initialProps;
+  /** The document the component renders into. */
+  document: Document;
+  /**
+   * The Fluid namespace identifier (e.g. "ui") this instance was mounted under - assigned by
+   * `mountAll`/`mount` right after their callback returns, so not yet available while it runs
+   * (`init()` included).
+   */
+  namespace?: string;
+  /** The name of the component, in camelCase. Every subclass has to set it. */
+  static componentName: string;
+  /** Alias of `document`. */
+  get doc(): Document;
+  constructor(initialProps: Props, userDocument?: Document);
+  /** Created by {@see init} - reading it earlier throws. */
+  get machine(): Machine$1<any>;
+  /** Created by {@see init} - reading it earlier throws. */
+  get api(): Api;
+  protected set api(api: Api);
+  /**
+   * Finds the component's parts by name, see {@see ComponentHydrator.query}. Created by
+   * {@see init} - reading it earlier throws.
+   */
+  get hydrator(): ComponentHydrator;
+  /**
+   * The props the instance runs on - what {@see transformProps} made of the ones it was created
+   * with. Created by {@see init} - reading it earlier throws.
+   */
+  get userProps(): Props;
+  /** Creates the machine from the props. Called once by `init()`. */
+  abstract initMachine(props: Props): Machine$1<any>;
+  /** Connects the machine to its api. Called by `init()` and again after every state change. */
+  abstract initApi(): Api;
+  /** Creates the hydrator that finds the parts of the component. It needs the `id` prop. */
+  initHydrator(props: Props): ComponentHydrator;
+  /**
+   * Builds everything the instance runs on - `userProps`, hydrator, machine and api - then renders
+   * once and starts the machine. Call it once after constructing.
+   */
+  init(): void;
+  /**
+   * Renders again with no prop change behind it. Use it after changing the DOM directly, e.g.
+   * after inserting a new `Template` instance, for a primitive with no prop that causes a render on
+   * its own. Combobox and Select don't need it: `updateProps({ collection })` already renders.
+   */
+  refresh(): void;
+  /** The `componentName` of the class. */
+  getName(): string;
+  /**
+   * Kebab form of {@see getName} - what actually appears in DOM-facing identifiers (part attribute
+   * names, hydration keys). See {@see ComponentHydrator.clientComponentName}.
+   */
+  getClientName(): string;
+  /**
+   * Override to adjust the props before anything else sees them, e.g. to wrap a callback prop.
+   * Runs once, first in {@see init}: the result becomes `userProps`, which `initHydrator()` and
+   * `initMachine()` receive.
+   */
+  transformProps(props: Props): Props;
+  /**
+   * Another already-mounted instance of this same component, by root id - for a primitive that
+   * composes two independent instances of itself (Menu submenus). Only resolves once
+   * `mountAll`/`mount` assigned {@see namespace}.
+   */
+  protected getPeerInstance<T extends Component<any, any>>(rootId: string): T | undefined;
+  /** Changes props at runtime. Only the ones you pass change, the others stay. */
+  updateProps(newProps: Partial<Props>): void;
+  /** Stops the machine and releases the hydrator. */
+  destroy(): void;
+  /** Applies the attributes and event handlers of a part's props to its element. */
+  spreadProps(node: HTMLElement, attrs: Attrs): void;
+  /** {@see spreadTextControlProps}: for a text control that mirrors what the user typed. */
+  spreadTextControlProps(node: HTMLInputElement | HTMLTextAreaElement, attrs: Attrs): void;
+  /**
+   * For every element matching `part`, reads its own `data-value` and hands `{el, value}` to
+   * `getProps`; if it returns a props object, spreads it onto that element via `spreadProps`.
+   * Returning `null`/`undefined` skips the element (e.g. a value that no longer resolves
+   * against a collection). Deliberately does not read any other attribute
+   * (disabled/invalid/current/...) or resolve a collection itself - callers read whatever flags
+   * they need off `el` and do their own value resolution, since both vary per primitive.
+   */
+  protected spreadPropsByValue(part: string, getProps: (ctx: {
+    el: HTMLElement;
+    value: string;
+  }) => Attrs | null | undefined, options?: {
+    parent?: HTMLElement | Document;
+  }): void;
+  protected spreadPropsByOptionalValue(part: string, getProps: (ctx: {
+    el: HTMLElement;
+    value?: string;
+  }) => Attrs | null | undefined, options?: {
+    parent?: HTMLElement | Document;
+  }): void;
+  /** Spreads the props of every part onto its element. Called after every state change. */
+  abstract render(): void;
+}
+//#endregion
+//#region Resources/Private/Client/src/lib/delayed-indicator.d.ts
+/** The options of a {@link DelayedIndicator}. */
+interface DelayedIndicatorOptions<T> {
+  /**
+   * How long a transient value must persist before it is shown at all. Must be finite and >= 0.
+   * @default 150
+   */
+  showDelayMs?: number;
+  /**
+   * Once shown, how long a transient value stays current before a settled value can replace it.
+   * Must be finite and >= 0.
+   * @default 300
+   */
+  minVisibleMs?: number;
+  /**
+   * Marks which values are transient, e.g. a loading state. Every other value is treated as settled
+   * and passes through immediately once no transient value is held.
+   */
+  isTransient: (value: T) => boolean;
+  /** Called with each value once it is ready to be shown. */
+  onChange: (value: T) => void;
+}
+/**
+ * Delays showing a transient value long enough to avoid flicker, and keeps it visible for a minimum
+ * duration once shown. Feed it every new value through `set()`, typically straight from a subscribe
+ * callback, and it forwards them to `onChange`. The values `isTransient` marks are held back for
+ * `showDelayMs`, so a fast operation never flashes them. Once shown they stay for at least
+ * `minVisibleMs`, so they can't vanish the instant they appeared.
+ *
+ * It works on any value, not only a boolean: one instance can drive a spinner and a status text
+ * from the same source, so they never disagree.
+ */
+declare class DelayedIndicator<T> {
+  private readonly showDelayMs;
+  private readonly minVisibleMs;
+  private readonly isTransient;
+  private readonly onChange;
+  private phase;
+  private latestValue;
+  private timer;
+  private shownAt;
+  constructor(options: DelayedIndicatorOptions<T>);
+  /**
+   * Passes a new value on, delayed as described above. It does not deduplicate: the same value
+   * again can still call `onChange` again, as this filters state over time, it is not a
+   * `distinctUntilChanged()`.
+   *
+   * @param value - The new value.
+   */
+  set(value: T): void;
+  /**
+   * Cancels any timer that is running. Call it when the indicator is no longer needed, e.g. on
+   * teardown: otherwise a scheduled value can still reach `onChange` afterwards. It is safe to call
+   * when nothing is transient or shown.
+   */
+  destroy(): void;
+}
+//#endregion
+//#region Resources/Private/Client/src/lib/extbase.d.ts
+/**
+ * Reads the Extbase argument namespace (`tx_docs_docs`) of a frontend action URL, from its
+ * `[controller]` or `[action]` query key. `UriBuilder::uriFor()` nests those under it, also for a
+ * custom `pluginNamespace`.
+ *
+ * @param url - The URL of the action.
+ * @returns The namespace, or `null` for a URL without such a key.
+ */
+declare function getArgumentPrefix(url: string): string | null;
+/**
+ * Sends GET and POST requests to an Extbase controller action from your own code, e.g. from the
+ * `load` callback of an async search. The data is nested under the Extbase argument namespace of the
+ * URL, the way `f:uri.action` builds it.
+ */
+declare const extbase: {
+  /**
+   * GETs `url` with `data` appended as query parameters under its Extbase argument namespace. The
+   * URL's own query, `cHash` included, is kept - so the new parameters have to be listed in
+   * `FE.cacheHash.excludedParameters`, or TYPO3 rejects the request.
+   *
+   * @param url - The URL of the action, absolute or relative.
+   * @param data - The arguments. Nested objects and arrays are flattened into bracket notation.
+   * @param init - More options for `fetch`, e.g. `{ signal }`.
+   * @returns The native `Response`. A non-2xx status resolves normally, check `response.ok`.
+   */
+  get(url: string, data?: Record<string, unknown>, init?: RequestInit): Promise<Response>;
+  /**
+   * POSTs `data` as `multipart/form-data`, nested under the URL's Extbase argument namespace. A
+   * URL without one gets `data` unprefixed.
+   *
+   * @param url - The URL of the action.
+   * @param data - The arguments. Nested objects and arrays are flattened into bracket notation, `null`
+   * and `undefined` are skipped, a `File` or `Blob` is sent as it is.
+   * @param init - More options for `fetch`, e.g. `{ signal }`.
+   * @returns The native `Response`. A non-2xx status resolves normally, check `response.ok`.
+   */
+  post(url: string, data?: Record<string, unknown>, init?: RequestInit): Promise<Response>;
+  getArgumentPrefix: typeof getArgumentPrefix;
+};
+//#endregion
+//#region Resources/Private/Primitives/Field/src/field.types.d.ts
+/**
+ * A plain-object snapshot of the control's native `ValidityState`.
+ * The live DOM object is never exposed — its getters change under the framework's feet.
+ */
+interface ValiditySnapshot {
+  badInput: boolean;
+  customError: boolean;
+  patternMismatch: boolean;
+  rangeOverflow: boolean;
+  rangeUnderflow: boolean;
+  stepMismatch: boolean;
+  tooLong: boolean;
+  tooShort: boolean;
+  typeMismatch: boolean;
+  valueMissing: boolean;
+  valid: boolean;
+}
+type ValidityMatch = Exclude<keyof ValiditySnapshot, 'valid'>;
+interface ValidateDetails {
+  /**
+   * The current value of the control.
+   */
+  value: string;
+  /**
+   * Snapshot of the control's native validity, taken before custom validation runs.
+   */
+  validity: ValiditySnapshot;
+}
+/**
+ * Return a string or list of strings to mark the field invalid; anything else means valid.
+ */
+type ValidateResult = string | string[] | null | undefined | void;
+interface ValidityChangeDetails {
+  valid: boolean;
+  errors: string[];
+  validity: ValiditySnapshot;
+  value: string;
+}
+/**
+ * When validation is committed (made visible):
+ * - `onSubmit`: on form submission — behaves like `onChange` after the first submit attempt
+ * - `onBlur`: when the control loses focus
+ * - `onChange`: on every change
+ */
+type ValidationMode = 'onSubmit' | 'onBlur' | 'onChange';
+type ElementIds = Partial<{
+  root: string;
+  control: string;
+  label: string;
+  errorText: string;
+  helperText: string;
+}>;
+interface FieldProps extends DirectionProperty, CommonProperties {
+  /**
+   * The name of the field. It keys the field in its form and is what the field's value is read by.
+   */
+  name: string;
+  /**
+   * The initial value, used while the DOM holds no control for this name yet.
+   */
+  defaultValue?: unknown;
+  /**
+   * Names of sibling fields in the same form whose value changes this field reacts to.
+   */
+  listenTo?: string[] | undefined;
+  /**
+   * The ids of the elements. Useful for composition.
+   */
+  ids?: ElementIds | undefined;
+  /**
+   * Whether the field is disabled. Also inherited from a surrounding native `<fieldset disabled>`.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+  /**
+   * Whether the field is invalid, regardless of computed validity.
+   * Use for app-level errors (e.g. server errors) the machine cannot compute itself.
+   */
+  invalid?: boolean | undefined;
+  /**
+   * Whether the field's value has been changed from its initial value.
+   * Useful when the field state is controlled by an external library.
+   */
+  dirty?: boolean | undefined;
+  /**
+   * Whether the field has been touched.
+   * Useful when the field state is controlled by an external library.
+   */
+  touched?: boolean | undefined;
+  /**
+   * Whether the field is read-only.
+   * @default false
+   */
+  readOnly?: boolean | undefined;
+  /**
+   * Whether the field is required.
+   * @default false
+   */
+  required?: boolean | undefined;
+  /**
+   * Custom validation, run against the value and the native validity snapshot.
+   * May return a promise; a newer validation run supersedes an in-flight one.
+   */
+  validate?: ((details: ValidateDetails) => ValidateResult | Promise<ValidateResult>) | undefined;
+  /**
+   * When validation results become visible.
+   * @default "onBlur"
+   */
+  validationMode?: ValidationMode | undefined;
+  /**
+   * Called when the committed validity changes.
+   */
+  onValidityChange?: ((details: ValidityChangeDetails) => void) | undefined;
+}
+type PropsWithDefault = 'disabled' | 'readOnly' | 'required' | 'validationMode';
+interface FieldSchema {
+  state: 'idle';
+  props: FieldProps;
+  defaultPropKey: PropsWithDefault;
+  context: {
+    touched: boolean;
+    dirty: boolean;
+    filled: boolean;
+    focused: boolean;
+    validating: boolean;
+    errors: string[];
+    validity: ValiditySnapshot | null;
+    errorTextIds: string[];
+    hasHelperText: boolean;
+    fieldsetDisabled: boolean;
+    submitAttempted: boolean;
+  };
+  computed: {
+    disabled: boolean;
+    /**
+     * `null` until validation has run — the field is neither valid nor invalid.
+     */
+    valid: boolean | null;
+    invalid: boolean;
+  };
+  refs: {
+    /**
+     * Latches to `true` the first time the field is dirtied. Gates `valueMissing`
+     * so a pristine empty required field is not flagged before interaction or submit.
+     */
+    markedDirty: boolean;
+    /**
+     * The control value at first tracking, the baseline for `dirty`.
+     */
+    initialValue: string | null;
+    /**
+     * Async validation sequence — stale resolutions are discarded.
+     */
+    seq: number;
+    /**
+     * The field root, resolved once when the machine starts.
+     */
+    rootEl: HTMLElement | null;
+  };
+  event: EventObject;
+  action: string;
+  effect: string;
+  guard: string;
+}
+interface ErrorTextProps {
+  /**
+   * Narrows when the error text shows:
+   * - a `ValidityState` key shows it only for that native failure
+   * - `true` forces it visible (e.g. driven by an external form library)
+   * - omitted shows it whenever the field is invalid
+   */
+  match?: ValidityMatch | boolean | undefined;
+  /**
+   * Overrides the generated id. Use when two error texts share the same `match`.
+   */
+  id?: string | undefined;
+}
+type IndicatorType = 'required' | 'invalid' | 'valid' | 'validating';
+interface IndicatorProps {
+  /**
+   * The state the indicator reflects. Hidden (not unmounted) unless the state
+   * matches, so CSS transitions survive:
+   * - `required`: the field is required (e.g. an asterisk)
+   * - `invalid`: committed validity is invalid
+   * - `valid`: committed validity is valid — a pristine field shows neither
+   * - `validating`: an async validation is in flight (e.g. a spinner)
+   */
+  type: IndicatorType;
+}
+interface ResolvedElementIds {
+  root: string;
+  control: string;
+  label: string;
+  errorText: string;
+  helperText: string;
+}
+/**
+ * Shared interaction and validity state, mirrored onto every field part.
+ */
+interface FieldState {
+  /**
+   * Whether the field is disabled (including inherited fieldset disabled state).
+   */
+  disabled: boolean;
+  /**
+   * Whether the field is invalid.
+   */
+  invalid: boolean;
+  /**
+   * Committed validity: `null` until validation has run.
+   */
+  valid: boolean | null;
+  /**
+   * Whether the field is required.
+   */
+  required: boolean;
+  /**
+   * Whether the field is read-only.
+   */
+  readOnly: boolean;
+  /**
+   * Whether the control has been blurred at least once.
+   */
+  touched: boolean;
+  /**
+   * Whether the value differs from the initial value.
+   */
+  dirty: boolean;
+  /**
+   * Whether the control has a non-empty value.
+   */
+  filled: boolean;
+  /**
+   * Whether the control is focused.
+   */
+  focused: boolean;
+  /**
+   * Whether an async validation is in flight.
+   */
+  validating: boolean;
+}
+interface RootState extends FieldState {}
+interface LabelState extends FieldState {}
+interface ControlState extends FieldState {}
+interface HelperTextState extends FieldState {}
+interface ErrorTextState extends FieldState {
+  /**
+   * Whether the error text is hidden.
+   */
+  hidden: boolean;
+}
+interface IndicatorState extends FieldState {
+  /**
+   * The state this indicator reflects.
+   */
+  type: IndicatorType;
+  /**
+   * Whether the indicator is hidden.
+   */
+  hidden: boolean;
+}
+interface FieldApi<T extends PropTypes = PropTypes> {
+  /**
+   * The resolved element ids, for composition with other components.
+   */
+  ids: ResolvedElementIds;
+  /**
+   * Whether the field is disabled (including inherited fieldset disabled state).
+   */
+  disabled: boolean;
+  /**
+   * Whether the field is invalid.
+   */
+  invalid: boolean;
+  /**
+   * Committed validity: `null` until validation has run.
+   */
+  valid: boolean | null;
+  /**
+   * Whether the field is required.
+   */
+  required: boolean;
+  /**
+   * Whether the field is read-only.
+   */
+  readOnly: boolean;
+  /**
+   * Whether the control is focused.
+   */
+  focused: boolean;
+  /**
+   * Whether the control has been blurred at least once.
+   */
+  touched: boolean;
+  /**
+   * Whether the value differs from the initial value.
+   */
+  dirty: boolean;
+  /**
+   * Whether the control has a non-empty value.
+   */
+  filled: boolean;
+  /**
+   * Whether an async validation is in flight.
+   */
+  validating: boolean;
+  /**
+   * The committed error messages.
+   */
+  errors: string[];
+  /**
+   * The committed validity snapshot, `null` until validation has run.
+   */
+  validity: ValiditySnapshot | null;
+  /**
+   * The composed `aria-describedby`, for wiring custom controls.
+   */
+  ariaDescribedby: string | undefined;
+  /**
+   * Runs validation now, surfacing `valueMissing` even on a pristine field.
+   */
+  validate: VoidFunction;
+  /**
+   * Clears committed errors and returns validity to the pristine (unvalidated) state.
+   */
+  clearErrors: VoidFunction;
+  /**
+   * Resets interaction state and validity to pristine.
+   */
+  reset: VoidFunction;
+  /**
+   * Returns the state of the root.
+   */
+  getRootState: () => RootState;
+  getRootProps: () => T['element'];
+  /**
+   * Returns the state of the label.
+   */
+  getLabelState: () => LabelState;
+  getLabelProps: () => T['label'];
+  /**
+   * Returns the state of the control (input, textarea, select, or a custom host).
+   */
+  getControlState: () => ControlState;
+  getControlProps: () => T['element'];
+  getInputProps: () => T['input'];
+  getTextareaProps: () => T['textarea'];
+  getSelectProps: () => T['select'];
+  /**
+   * Returns the state of the helper text.
+   */
+  getHelperTextState: () => HelperTextState;
+  getHelperTextProps: () => T['element'];
+  /**
+   * Returns the state of the error text.
+   */
+  getErrorTextState: (props?: ErrorTextProps) => ErrorTextState;
+  getErrorTextProps: (props?: ErrorTextProps) => T['element'];
+  /**
+   * Returns the state of the indicator.
+   */
+  getIndicatorState: (props: IndicatorProps) => IndicatorState;
+  getIndicatorProps: (props: IndicatorProps) => T['element'];
+}
+//#endregion
+//#region Resources/Private/Primitives/Field/src/field.registry.d.ts
+type FieldMachine = Machine$1<FieldSchema>;
+//#endregion
+//#region Resources/Private/Primitives/Form/src/form.registry.d.ts
+type FormMachine = Machine$1<any>;
+//#endregion
+//#region Resources/Private/Primitives/Form/Form.d.ts
+declare class Form extends Component<FormProps, FormApi> {
+  static componentName: string;
+  private fieldSubscriptions;
+  initMachine(props: FormProps): Machine$1<FormSchema>;
+  initApi(): FormApi;
+  private subscribeToFieldMachines;
+  render(): void;
+  destroy(): void;
+}
+//#endregion
+//#region Resources/Private/Primitives/Form/src/form.types.d.ts
+interface FieldError {
+  messages: string[];
+  value?: FormDataEntryValue | FormDataEntryValue[] | null;
+}
+type FormErrors = Record<string, FieldError>;
+type FormDirty = Record<string, boolean>;
+type FormTouched = Record<string, boolean>;
+type FormValueLeaf = string | File;
+interface FormValuesObject {
+  [key: string]: FormValueTree;
+}
+interface FormValuesArray extends Array<FormValueTree> {}
+type FormValueTree = FormValueLeaf | FormValuesObject | FormValuesArray;
+interface FormValues {
+  get(path: string): FormValueLeaf | null;
+  getAll(path: string): FormValueLeaf[];
+  has(path: string): boolean;
+  pick(path: string): FormValueTree | null;
+  toObject(): FormValuesObject;
+}
+interface StandardSchemaPathSegment {
+  readonly key: PropertyKey;
+}
+interface StandardSchemaIssue {
+  readonly message: string;
+  readonly path?: readonly (PropertyKey | StandardSchemaPathSegment)[];
+}
+interface StandardSchemaSuccessResult<Output = unknown> {
+  readonly value: Output;
+  readonly issues?: undefined;
+}
+interface StandardSchemaFailureResult {
+  readonly issues: readonly StandardSchemaIssue[];
+}
+type StandardSchemaResult<Output = unknown> = StandardSchemaSuccessResult<Output> | StandardSchemaFailureResult;
+interface StandardSchemaV1<Output = unknown> {
+  readonly '~standard': {
+    readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+  };
+}
+interface FormValidationContext {
+  values: FormValues;
+  fieldName?: string;
+  validateWithStandardSchema: <Output = unknown>(schema: StandardSchemaV1<Output>) => FormErrors;
+}
+type FormState = 'invalid' | 'ready' | 'submitting' | 'success' | 'error';
+type FormValidation = StandardSchemaV1 | ((context: FormValidationContext) => FormErrors | null | void);
+type FormSubmitResult = true | false | FormErrors;
+interface FormProps {
+  /** The unique identifier of the form. */
+  id: string;
+  /**
+   * Validates the values of the form on the client: a Standard Schema validator such as Zod, or a
+   * synchronous callback that gets the `values` and returns the errors by field name. It cannot be
+   * set from a Fluid template, only by constructing `Form` in your own entry file.
+   */
+  validation?: FormValidation;
+  /** The object name that prefixes the names of nested form fields. */
+  objectName?: string;
+  /**
+   * How long the fields wait after the last change before they read their value, never less than
+   * 50. A `validate` that sends a request should not fire on every keystroke.
+   * @default 100
+   */
+  inputDebounceMs?: number;
+  /**
+   * Called with the values once the form is valid and submitted. Return `true` for success,
+   * `false` for an error, or field errors to mark the form invalid. `post(url)` submits the form
+   * as `FormData` and maps a 422 JSON response to field errors for you.
+   */
+  onSubmit?: ({
+    values,
+    api,
+    event,
+    post
+  }: {
+    values: FormValues;
+    api: FormApi;
+    event: JSX.FormEvent<HTMLElement>;
+    post: (url: string) => Promise<Response>;
+  }) => Promise<FormSubmitResult> | FormSubmitResult;
+  /** Called every time the form state changes. Use it to update UI the form does not wire itself. */
+  render?: (form: Form) => void;
+}
+interface FormSchema {
+  props: FormProps;
+  context: {
+    errorText: string | null;
+    successText: string | null;
+  };
+  refs: {
+    serverErrors: FormErrors;
+  };
+  state: FormState;
+  event: EventObject;
+  action: string;
+  effect: string;
+}
+interface FormApi {
+  /** Whether the form is being submitted. */
+  isSubmitting: boolean;
+  /** Whether the value of any field differs from the one it started with. */
+  isDirty: boolean;
+  /** Whether any field is invalid. */
+  isInvalid: boolean;
+  /** Whether the last submit succeeded. */
+  isSuccessful: boolean;
+  /** Whether the last submit ended in an error. */
+  isError: boolean;
+  getFormProps(): PropTypes['element'];
+  getContentProps(): PropTypes['element'];
+  getIndicatorProps(state: FormState): PropTypes['element'];
+  getErrorTextProps(): PropTypes['element'];
+  getSuccessTextProps(): PropTypes['element'];
+  /** The current values of the form. */
+  getValues(): FormValues;
+  /** The errors of the invalid fields, by field name. */
+  getErrors(): FormErrors;
+  /** The dirty fields, by field name. */
+  getDirty(): FormDirty;
+  /** The touched fields, by field name. */
+  getTouched(): FormTouched;
+  /** The text of the error status of the form, `null` if there is none. */
+  getErrorText(): string | null;
+  /** Sets the text of the error status. Pass `null` to remove it. */
+  setErrorText(text: string | null): void;
+  /** The text of the success status of the form, `null` if there is none. */
+  getSuccessText(): string | null;
+  /** Sets the text of the success status. Pass `null` to remove it. */
+  setSuccessText(text: string | null): void;
+  /** Removes the error and the success text. */
+  clearStatusText(): void;
+  /** @internal */
+  _userRenderFn: FormProps['render'];
+  /** Every field of the form, by name. */
+  getAllFields(): Map<string, FieldHandle>;
+  /** The field with this name, `undefined` if the form has none. */
+  getField(name: string): FieldHandle | undefined;
+  /** The `<form>` element. */
+  getFormEl(): HTMLFormElement | null;
+  /** The `action` of the form, an empty string if it has none. */
+  getAction(): string;
+  /** Resets the form to its initial state. */
+  reset(): void;
+  /** Picks up fields that were added or removed after the form was hydrated. */
+  syncFields(): void;
+  /**
+   * Renames a field, keeping its value, touched, dirty and error state. Useful to keep the rows of
+   * a FieldArray contiguously indexed after one in the middle was removed.
+   */
+  renameField(oldName: string, newName: string): void;
+}
+//#endregion
+//#region Resources/Private/Primitives/Field/src/field.value.d.ts
+type FieldValue = FormDataEntryValue | FormDataEntryValue[] | null;
+//#endregion
+//#region Resources/Private/Primitives/Field/src/field.handle.d.ts
+interface FieldDependencyChangeDetail {
+  name: string;
+  dependencies: Record<string, FieldValue>;
+  values: FormValues;
+}
+/** What a field offers on top of Zag's api: its name, its value, its form and its `listenTo` event. */
+interface FieldHandleExtras {
+  /** The name of the field. */
+  name: string;
+  /** The current value of the field. */
+  getValue(): FieldValue;
+  /** The first error message of the field, `null` if there is none. */
+  getErrorText(): string | null;
+  /** The root element of the field. */
+  getRootEl(): HTMLElement | null;
+  /** The machine of the form the field sits in, `undefined` outside of a form. */
+  getFormMachine(): FormMachine | undefined;
+  /** Disables or enables the field. */
+  setDisabled(disabled: boolean): void;
+  /** Marks the field as required or optional. */
+  setRequired(required: boolean): void;
+  /** Makes the field read-only or editable. */
+  setReadOnly(readOnly: boolean): void;
+  /**
+   * Calls `callback` whenever the value of a field named in the `listenTo` prop of this field
+   * changes. Returns a function that removes the listener again. For a field without `listenTo` it
+   * never fires, but the returned function is still safe to call.
+   */
+  addDependencyChangeListener(callback: (detail: FieldDependencyChangeDetail) => void): () => void;
+}
+/** Zag's api plus the handle extras: what a `Field` instance exposes as `.api`. */
+type FieldClientApi = FieldApi & FieldHandleExtras;
+/** What `form.api.getField(name)` returns: the field's state and actions, flat. */
+type FieldHandle = Pick<FieldApi, 'disabled' | 'required' | 'readOnly' | 'invalid' | 'valid' | 'touched' | 'dirty' | 'filled' | 'focused' | 'validating' | 'errors' | 'validate' | 'clearErrors' | 'reset'> & FieldHandleExtras;
+//#endregion
+//#region Resources/Private/Client/src/lib/field-aware-component.d.ts
+/**
+ * Base class of a primitive that can sit inside a Field. It takes `name`, `disabled`, `readOnly`,
+ * `required` and `invalid` from the closest Field and follows its changes, and it tells the field
+ * once it has hydrated.
+ */
+declare abstract class FieldAwareComponent<Props, Api> extends Component<Props, Api> {
+  protected subscribedToField: boolean;
+  protected fieldMachine: FieldMachine | undefined;
+  protected closestField: HTMLElement | null;
+  protected abstract propsWithField(props: Partial<Props>, field: FieldClientApi): Props;
+  /** The field's current api, for what a primitive merges into its own props when it renders. */
+  protected get field(): FieldClientApi | undefined;
+  protected getClosestField(): HTMLElement | null;
+  /** Builds the component like `Component.init()`, then tells the field that it is hydrated. */
+  init(): void;
+  protected withFieldProps(props: Props): Props;
+  /**
+   * Applies every later change of the field to the machine props. It waits for the field if that
+   * has not registered yet, and does nothing when there is no field around.
+   */
+  subscribeToFieldService(): void;
+  /**
+   * The field measured its starting value from the server HTML; a primitive may hydrate to a
+   * different state (a defaultChecked checkbox, a Select's selected option).
+   */
+  private notifyFieldHydrated;
+}
+//#endregion
+//#region Resources/Private/Client/src/lib/hydration.d.ts
+/**
+ * @internal
+ *
+ * A part's own name is lowerCamelCase (mirroring zag-js's own `ids` prop keys), but its attribute
+ * always renders lower-kebab. Keep in sync with: Classes/Utility/ComponentNameUtility.php's
+ * camelCaseToLowerCaseDashed().
+ */
+declare function toKebabCase(part: string): string;
+/** @internal */
+declare function getHydrationData(component: string): Record<string, ComponentHydrationData> | null;
+declare function getHydrationData(component: string, id: string): ComponentHydrationData | null;
+/**
+ * Finds a component instance that is already mounted, by the namespaced name it was mounted with and
+ * its hydration id (the `id` prop it was rendered with). Works for instances from `mountAll()` and
+ * `mount()` alike. It is for primitives that compose two independent instances of themselves at
+ * runtime, e.g. the submenus of a Menu.
+ *
+ * @param componentName - The namespaced name, e.g. `ui:menu`.
+ * @param id - The hydration id of the instance.
+ * @returns The instance, or `undefined` if none is mounted under that id.
+ */
+declare function getComponentInstance<T extends Component<unknown, unknown> = Component<unknown, unknown>>(componentName: string, id: string): T | undefined;
+/** @internal */
+declare function getGlobals(): FluidPrimitivesGlobals | null;
+/** @internal */
+declare function getGlobal<T = unknown>(key: string): T | undefined;
+/**
+ * Mounts every instance of a component that is not mounted yet and was not rendered with
+ * `autoMount="{false}"`. It is safe to call more than once, e.g. after lazily inserted DOM adds new
+ * instances: mounted ones are skipped.
+ *
+ * The `props` in the callback are typed from `componentName` via `HydrationPropsFor`. A component
+ * without generated types gets an untyped bag.
+ *
+ * @param componentName - The namespaced name, e.g. `ui:select`.
+ * @param callback - Creates the instance of one hydration entry and returns it.
+ *
+ * @example
+ * ```typescript
+ * mountAll('ui:accordion', ({ props }) => {
+ *     const accordion = new Accordion(props);
+ *     accordion.init();
+ *     return accordion;
+ * });
+ * ```
+ */
+declare function mountAll<K extends KnownComponentName | (string & {})>(componentName: K, callback: (data: {
+  autoMount: boolean;
+  props: HydrationPropsFor<Extract<K, string>>;
+  createHydrator: () => ComponentHydrator;
+}) => Component<unknown, unknown> | void): void;
+/**
+ * Destroys every mounted instance whose root element is `root` or inside it, and forgets it. Call it
+ * before you remove a subtree from the DOM, e.g. a row of a FieldArray.
+ *
+ * Only the `root` part of an instance counts. A component without one, such as Dialog, is never
+ * matched.
+ *
+ * @param root - The element that is about to be removed.
+ */
+declare function destroyComponentsWithin(root: Element | Document): void;
+/**
+ * Mounts one instance by its `rootId`, also one that was rendered with `autoMount="{false}"`. Unlike
+ * `mountAll()`, it creates a new instance on every call, which then replaces the one tracked before.
+ * `getComponentInstance()` and `destroyComponentsWithin()` find it like any other.
+ *
+ * The `props` in the callback are typed like those of `mountAll()`.
+ *
+ * @param componentName - The namespaced name, e.g. `ui:dialog`.
+ * @param rootId - The `rootId` the component was rendered with.
+ * @param callback - Creates the instance and returns it.
+ * @returns The instance, or `undefined` if there is no hydration entry for `rootId`.
+ */
+declare function mount<K extends KnownComponentName | (string & {}), T extends Component<unknown, unknown>>(componentName: K, rootId: string, callback: (data: {
+  autoMount: boolean;
+  props: HydrationPropsFor<Extract<K, string>>;
+  createHydrator: () => ComponentHydrator;
+}) => T | void): T | undefined;
+/**
+ * Finds the parts of one component instance. Every part that `ui:ref` renders carries a
+ * `data-<component>-<part>="<rootId>"` attribute, so a lookup needs no id and searches the whole
+ * document by default. That is also what finds content that was portaled away from the root.
+ */
+declare class ComponentHydrator {
+  /** The name of the component, in camelCase. */
+  componentName: string;
+  /** The kebab-case form of `componentName`, as it appears in attribute names. */
+  clientComponentName: string;
+  /** The document the parts are searched in. */
+  doc: Document;
+  /** The `rootId` the component was rendered with. */
+  rootId: string;
+  /**
+   * @param componentName - The name of the component, in camelCase.
+   * @param rootId - The `rootId` the component was rendered with. Throws if it is missing.
+   * @param doc - The document the parts are searched in.
+   */
+  constructor(componentName: string, rootId: string | undefined, doc?: Document);
+  private get attrPrefix();
+  /** The name of the attribute that marks `part`, e.g. `data-accordion-item-trigger`. */
+  attr(part: string): string;
+  /** The CSS selector of every element of `part` that belongs to this instance. */
+  selector(part: string): string;
+  /** The key that identifies `part`, and optionally one `value` of it, across this instance. */
+  scopeKey(part: string, value?: string): string;
+  /**
+   * Finds the first element of `part`.
+   *
+   * @param part - The name of the part, in camelCase.
+   * @param parent - Where to search, the whole document by default.
+   * @returns The element, or `null` if there is none.
+   */
+  query<T extends Element = HTMLElement>(part: string, parent?: Element | Document): T | null;
+  /**
+   * Finds every element of `part`.
+   *
+   * @param part - The name of the part, in camelCase.
+   * @param parent - Where to search, the whole document by default.
+   */
+  queryAll<T extends Element = HTMLElement>(part: string, parent?: Element | Document): T[];
+  /**
+   * Marks an element as `part` of this instance, like `ui:ref` does on the server. For elements
+   * you create after hydration.
+   *
+   * @param element - The element to mark.
+   * @param part - The name of the part, in camelCase.
+   * @param value - Sets `data-value`, for a part that exists once per item.
+   */
+  stamp(element: Element, part: string, value?: string): void;
+  /** The part this component's own scope marks `el` as (kebab-case), if any. */
+  private getOwnPart;
+  /**
+   * Sets `data-value` on every element within `root` (root included) that is a part of *this*
+   * component's own scope, for a new, real `value` - the shared half of
+   * {@see restampValue}/{@see renameValue}, which differ only in what they each then do about any
+   * nested, independent root component `root` happens to compose (a fresh copy vs. an in-place
+   * rename - see `restampValue`'s own docblock for why the two are never auto-detected from one
+   * another).
+   *
+   * `attributes`, if given, are additionally set on the same elements `value` is applied to - for
+   * primitives whose `render()` reads plain per-element data attributes rather than resolving a
+   * collection item (e.g. RadioGroup's `disabled`/`invalid`, NavigationMenu's `Link` `current`).
+   * A boolean value toggles a bare `data-x` attribute (e.g. `{ disabled: true }` -> `data-disabled`,
+   * present only when true); a string value sets `data-x="value"` directly.
+   */
+  private restampOwnScope;
+  /**
+   * @internal
+   *
+   * Re-stamps `root` for a new, real `value` (via {@see restampOwnScope}) and prepares any
+   * nested, *independent* root component found inside it (e.g. a `Field`+`Input` composed inside
+   * a `FieldArray` row, or any other primitive that composes another one inside its own per-item
+   * markup) as a brand-new instance copied from its own pristine stencil data, via
+   * {@see prepareNestedRootComponents}. Use after cloning a `<template>` (see `Template`) to make
+   * the clone represent one real item/row in a single call, instead of manually setting
+   * `data-value` on the root and separately on every nested value-scoped part (e.g. a combobox
+   * item's own `item-text`/`item-indicator`) *and* separately preparing whatever independent
+   * components that item happens to compose. Fully generic - not
+   * tied to any one primitive - so a `<template>` item "just works" regardless of what it
+   * contains, without the calling primitive needing to know or handle that itself.
+   *
+   * Only for a *freshly cloned* item - one that has never been through this or
+   * {@see renameValue} before (a `<template>`'s content is never mutated by a previous clone, so
+   * this is always true right after `content.cloneNode(true)`). For an *existing* item pulled
+   * from the live DOM whose value is merely changing (e.g. `FieldArray` reindexing a later row
+   * down by one after an earlier row was removed), call {@see renameValue} instead.
+   *
+   * The two used to be auto-detected from a nested component's own *current* id shape (no
+   * `:value` suffix yet vs. already has one) rather than asked for explicitly - but that shape
+   * can't actually tell a never-touched, already-live server-rendered row apart from a
+   * never-touched template clone; both look identical. That silently mis-classified an
+   * already-mounted row as "fresh" the first time an earlier row's removal caused it to be
+   * reindexed: its DOM references moved out from under it (via `restampIdReferences`, which both
+   * paths run) without its `ComponentHydrator.rootId`/`componentInstances` entry following along -
+   * only {@see renameValue}'s path updates those - leaving its already-mounted `Field`/`Input`
+   * instances silently unable to find their own elements again. The caller already knows
+   * unambiguously which case it's in (a fresh `Template` clone vs. an element already in the
+   * document), so it now says so by calling the matching method instead of leaving it to a guess.
+   *
+   * `stencilKey` is the stencil's own {@see scopeKey} (see `Template`'s constructor, its only
+   * caller) - what nested root components `root` composes is looked up from
+   * `window.FluidPrimitives.nestedComponents[stencilKey]` (PHP-recorded, see
+   * `HydrationRegistry::recordNestedComponent()`), not found by scanning `root` itself. That's
+   * what lets this find a nested component regardless of what DOM shape it renders - including
+   * one that renders no identifiable wrapper of its own at all (e.g. `Dialog`'s `Root`, which is
+   * just `<f:slot />` - see `ui:portal`'s own `isRenderStencil` handling for the other half of
+   * making a portalled nested component work inside a stencil).
+   *
+   * Returns the distinct client component names of any nested root components found and
+   * prepared (empty when `root` contains none, the common case - e.g. `FileUpload`'s own item
+   * previews) - call the matching `mountAll()`s for each of these after inserting a freshly
+   * cloned item into the document, per `mountAll`'s own docblock ("after lazily-inserted DOM
+   * adds new instances").
+   */
+  restampValue(root: Element, value: string, stencilKey: string, attributes?: Record<string, boolean | string>): string[];
+  /**
+   * @internal
+   *
+   * Re-stamps `root` for a new, real `value` (via {@see restampOwnScope}) and re-keys every
+   * nested, independent root component found inside it (e.g. a `FieldArray` row's own
+   * `Field`+`Input`) to reference `value` instead of whatever position it previously held - both
+   * their DOM references (via {@see restampIdReferences}) and, for ones that are already live/mounted,
+   * their own `ComponentHydrator.rootId` and their entry in
+   * `window.FluidPrimitives.componentInstances`/`hydrationData` (via
+   * {@see renameNestedComponentEntry}), so their future re-renders keep resolving their own
+   * elements and later lookups (`getComponentInstance`, `destroyComponentsWithin`) keep finding
+   * them under their new id.
+   *
+   * For an *existing* item pulled from the live DOM whose position is merely shifting - never for
+   * a freshly cloned `<template>` item, which has no existing instance/hydration-data entry to
+   * re-key in the first place; use {@see restampValue} for that. See that method's own docblock
+   * for why the two are never auto-detected from one another.
+   *
+   * Looks up what `root` composes from `window.FluidPrimitives.nestedComponents[<scopeKey>]`,
+   * keyed by `root`'s own part and `data-value` *before* this call restamps it, which is why
+   * that's read first, before {@see restampOwnScope} changes it. That's a correct lookup key both
+   * for a row rendered for real (PHP records it there too - see `ComponentHydrationCollector`'s
+   * FieldArray-ambient-context check) and for one `restampValue` prepared earlier (which migrates
+   * the same entry to the row's new key as its own last step, for exactly this reason).
+   *
+   * Restamps id *references* (via {@see restampIdReferences}) across the whole document, not just
+   * `root`'s own subtree - unlike {@see restampValue}, where a fresh clone can't yet have anything
+   * portaled out of it (nothing composed by it has mounted/opened yet), `root` here is an existing,
+   * already-live item, so a nested component it composes may already have portaled its own content
+   * elsewhere in the document (e.g. an open `Popover`'s positioner, rendered via `ui:portal` into
+   * the page footer) by the time this runs. Scoping to `root` alone would restamp that component's
+   * trigger in place but silently miss its portaled content, leaving it referencing a now-stale id.
+   */
+  renameValue(root: Element, value: string): void;
+  /** Nothing to release yet, it exists so every instance can be destroyed alike. */
+  destroy(): void;
+}
+declare function getListCollectionFromHydrationData<T extends CollectionItem>(hydrationCollection: {
+  items: T[];
+  itemToValueKey?: string | null;
+  itemToStringKey?: string | null;
+  isItemDisabledKey?: string | null;
+  groupByKey?: string | null;
+  groupSort?: 'asc' | 'desc' | Array<string> | null;
+}): ListCollection<T>;
+//#endregion
+//#region Resources/Private/Client/src/lib/machine.d.ts
+/**
+ * The Zag machine runtime that components run on. It takes `Partial` props: the `id` that Zag
+ * requires is guaranteed at runtime by `Component.initHydrator()`.
+ */
+declare class Machine$1<T extends MachineSchema> extends VanillaMachine<T> {
+  constructor(machine: Machine<T>, userProps?: Partial<NonNullable<T['props']>>);
+  /** Changes props at runtime. Only the ones you pass change, the others stay. */
+  updateProps(newProps: Partial<NonNullable<T['props']>> | InputProps<T> | (() => InputProps<T>)): void;
+}
+//#endregion
+//#region Resources/Private/Client/src/lib/spread-props.d.ts
+/**
+ * Like `spreadProps` for a text control, but it does not assign a `value` the control already
+ * shows. Any assignment, even of the same text, makes the browser treat the value as set by a
+ * script, and it stops reporting `tooShort` (`minlength`) for such a value. These controls mirror
+ * what the user typed into their machine, so that assignment would happen on every keystroke.
+ *
+ * As in `spreadProps`, a value is only considered when it changed since the last call: the control
+ * can be one event ahead of the machine, and must not be reset to the machine's older value.
+ */
+declare function spreadTextControlProps(node: HTMLInputElement | HTMLTextAreaElement, attrs: Attrs, scopeKey?: string): () => void;
+//#endregion
+//#region Resources/Private/Client/src/lib/template.d.ts
+/** The options of a {@link Template}. */
+interface TemplateOptions {
+  /**
+   * Makes the clone represent one real item: sets `data-value` on its root and on every part
+   * inside it that exists once per item, and prepares independent root components inside it, such
+   * as a `Field` with an `Input`, so `mountAll()` can mount them. Leave it out for a template
+   * without a per-item value.
+   */
+  value?: string;
+  /**
+   * Data attributes to set next to `value`, on the same elements. A boolean toggles a bare
+   * `data-x` attribute, `{ disabled: true }` sets `data-disabled` and `false` removes it. A string
+   * sets `data-x="value"`. Only has an effect together with `value`.
+   */
+  attributes?: Record<string, boolean | string>;
+}
+/**
+ * Clones the content of a `<template>` part, which must have exactly one root element, and throws
+ * otherwise. It is a `DocumentFragment`, so you can append it directly: `root` stays a valid
+ * reference to the element after the fragment has been emptied by the insertion.
+ *
+ * It works for any "clone a `<template>` and fill it with data that doesn't exist at server render
+ * time" case, such as async search results, file upload previews or the rows of a FieldArray.
+ */
+declare class Template extends DocumentFragment {
+  private readonly hydrator;
+  /** The one root element of the clone. */
+  readonly root: HTMLElement;
+  /**
+   * The client names of the independent root components found inside the clone, empty without
+   * `options.value` or when there are none. Call their `mountAll()` after you insert the clone into
+   * the document.
+   */
+  readonly componentNames: string[];
+  /**
+   * @param hydrator - The hydrator of the component that owns the `<template>`.
+   * @param part - The name of the `<template>` part.
+   * @param options - See `TemplateOptions`.
+   */
+  constructor(hydrator: ComponentHydrator, part: string, options?: TemplateOptions);
+  /** Finds the first element of `part` inside the clone. */
+  query<T extends Element = HTMLElement>(part: string): T | null;
+  /** Finds every element of `part` inside the clone. */
+  queryAll<T extends Element = HTMLElement>(part: string): T[];
+}
+//#endregion
+//#region Resources/Private/Client/src/lib/uid.d.ts
+/**
+ * Creates an id that is unique within the page, e.g. for a part that needs an `id` to reference.
+ *
+ * @param prefix - Starts the id.
+ */
+declare function uid(prefix?: string): string;
+//#endregion
+export { AsyncList as $, FormValueTree as A, ComponentHydrationData as B, FieldValue as C, FormSubmitResult as D, FormProps as E, FieldSchema as F, HydrationPropsRegistry as G, FluidPrimitivesGlobals as H, extbase as I, ClientPropConverter as J, KnownComponentName as K, DelayedIndicator as L, FormValuesObject as M, Form as N, FormValidation as O, FieldProps as P, registerClientPropConverters as Q, DelayedIndicatorOptions as R, FieldHandle as S, FormErrors as T, HydrationPropsFor as U, ComponentInterface as V, HydrationPropsOverrides as W, ConverterMachineProps as X, ClientPropConverterMap as Y, applyClientPropConverters as Z, mountAll as _, spreadTextControlProps as a, FieldClientApi as b, Machine$1 as c, getComponentInstance as d, AsyncListOptions as et, getGlobal as f, mount as g, getListCollectionFromHydrationData as h, spreadProps as i, FormValues as j, FormValueLeaf as k, ComponentHydrator as l, getHydrationData as m, Template as n, normalizeProps$1 as o, getGlobals as p, NestedComponentEntry as q, TemplateOptions as r, mergeProps as s, uid as t, destroyComponentsWithin as u, toKebabCase as v, FormApi as w, FieldDependencyChangeDetail as x, FieldAwareComponent as y, Component as z };