@aglyn/besigner-ui 1.0.0-beta.143

package/src/lib/components/element-props-form.component.d.ts

@@ -0,0 +1,565 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import PluginSettingsField from './plugin-settings-field.component';
+import type * as Aglyn from '@aglyn/aglyn';
+import { type RepeatSource } from '@aglyn/aglyn/app-utils/repeat-sources';
+import { type FormRendererProps, type FormTemplateRenderProps } from '@aglyn/shared-ui-jsx-forms';
+import { MarkdownAttributeField } from './markdown-attribute-field.component';
+import { ScreenLinkField, ScreenTargetField } from './screen-link-field.component';
+import { PropertyBindingField } from './property-binding-field.component';
+export { ATTRIBUTE_COMMIT_DEBOUNCE_MS, useDebouncedCommit, } from '../hooks/use-debounced-commit';
+export { readAttributeFieldValue } from '../utils/attribute-field-value';
+/**
+ * @TODO ⚠️ remove and reimplement following PR merge
+ *   https://github.com/data-driven-forms/react-forms/pull/1218
+ */
+/**
+ * Whether a node's text is FORMATTED — it carries a `html` prop the renderer
+ * draws in preference to `children` (AGL-2486).
+ *
+ * An instance is excluded: its text rides `propValues`, not a `html` prop of
+ * its own, so the question does not arise there.
+ */
+export declare function isFormattedText(node: Aglyn.NodeSchema<any> | undefined | null): boolean;
+/**
+ * The same props with the formatting dropped and the words kept
+ * (AGL-2486).
+ *
+ * `children` is deliberately untouched. It already holds the plain reading
+ * of the markup — and since `richTextToPlain` keeps line breaks, that
+ * reading has the author's breaks in it — so the element goes on saying the
+ * same thing in the same shape, in a form this panel can edit.
+ */
+export declare function withoutFormatting(props: Record<string, unknown> | undefined): Record<string, unknown>;
+export declare const ElementPropsFormTemplate: import("react").ForwardRefExoticComponent<Omit<FormTemplateRenderProps, "ref"> & import("react").RefAttributes<any>>;
+export interface ElementPropsFormProps extends Omit<FormRendererProps, 'schema' | 'componentMapper'> {
+    node?: Aglyn.NodeSchema<any>;
+    /**
+     * Supplied by the component, not the caller: `ElementPropsFormRaw` reads
+     * `node.componentSchema` and ignores anything passed in, and the production
+     * mount (`withLastSelectedNode(withTabPanelInner(...))`) passes neither. They
+     * stayed required only because the interface extended `FormRendererProps`
+     * wholesale, so any direct render was a type error for props the component
+     * discards.
+     */
+    schema?: FormRendererProps['schema'];
+    componentMapper?: FormRendererProps['componentMapper'];
+}
+export declare const elementPropsComponentMapper: {
+    "icon-picker": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    checkbox: import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "color-picker": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "css-dimension": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "css-gradient": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "data-table": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "breakpoint-span": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "css-border": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "preset-choice": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "theme-scale": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    radio: import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    slider: import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "toggle-button": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "dual-list-select": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "aglyn-token-text-field": {
+        (props: import("./token-text-field.component").TokenTextFieldProps): import("react").JSX.Element;
+        displayName: string;
+    };
+    "aglyn-screen-link-field": typeof ScreenLinkField;
+    "aglyn-screen-target-field": typeof ScreenTargetField;
+    markdown: typeof MarkdownAttributeField;
+    "aglyn-markdown-attribute-field": typeof MarkdownAttributeField;
+    "aglyn-plugin-settings-field": typeof PluginSettingsField;
+    "aglyn-property-binding-field": typeof PropertyBindingField;
+    select: import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "sub-form": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    switch: import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    "text-field": import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+    textarea: import("@aglyn/shared-ui-jsx-forms").ExtendedMapperComponent;
+};
+/**
+ * A number-typed field persists a NUMBER, not the text that was typed.
+ *
+ * Every control in this panel can only hand back a string, and for a prop
+ * the renderer reads as a number that changes what the value DOES: MUI
+ * renders `size: 24` as 24px and passes the string `'24'` through verbatim,
+ * where it is not CSS and the declaration is dropped — the icon silently
+ * goes back to its default size. Clearing the box to retype the same number
+ * is enough to do it.
+ *
+ * Gated on the field's declared `type: 'number'` rather than on the value's
+ * shape, which is how the styles panel decides ({@link numericTextValue}):
+ * every value there is CSS, while an attribute holds arbitrary authored
+ * content, and a Text element reading `2026` is text that must stay text.
+ *
+ * Implemented as final-form's `parse` rather than data-driven-forms'
+ * `dataType`, which converts the same way but ALSO attaches a pattern
+ * validator. These fields are token-capable, so a `{{var:id}}` binding —
+ * legitimate in a numeric prop — would make the form invalid, and this
+ * panel's autosave only commits while it is valid: every attribute on the
+ * element would stop saving, with nothing on screen to say so.
+ */
+export declare function withNumericValueParse<T extends Record<string, unknown>>(field: T): T;
+/**
+ * The field, with its `resolveProps` handed the element it edits as a fourth
+ * argument (see {@link Aglyn.AttributeFieldContext}).
+ *
+ * data-driven-forms calls `resolveProps` with the field's value and the form's
+ * values, which are the element's own props. A warning about the element as a
+ * whole also needs what is inside it — a Link Container holding only an icon
+ * renders an unnamed link (AGL-2886) — and nothing else tells a field which
+ * element on the canvas it belongs to.
+ *
+ * The context is read when the field renders, not when this runs, so the
+ * lookup answers from the live canvas rather than from a copy taken when the
+ * element was selected. A field that declares no `resolveProps` is returned
+ * untouched.
+ */
+export declare function withAttributeFieldContext<T extends Record<string, unknown>>(field: T, context: Aglyn.AttributeFieldContext | undefined): T;
+/**
+ * The switch's position as the page stores it: a real boolean, read with the
+ * spellings every Yes / no reader accepts, so a value stored as the text
+ * `'false'` or `'off'` shows off rather than on.
+ *
+ * Unset is not a position a switch has, and it is the one a page needs to hand
+ * the choice back to the default — so the field's clear button is the way
+ * there, and it removes the value rather than storing either answer.
+ */
+export declare function parseYesNoPropValue(value: unknown): boolean | undefined;
+/**
+ * The path each icon picker's companion prop should hold once these values
+ * are saved: `iconId` → `iconPath`, `startIconId` → `startIconPath`
+ * (AGL-1212).
+ *
+ * The id stays the source of truth and the path travels with the document,
+ * because the catalog is ~2.9 MB, only picker surfaces load it, and a
+ * published page has to draw the icon without it.
+ *
+ * The lookup runs on every save of the panel, and the panel saves edits to
+ * every other attribute too — from the moment it opens, before the picker has
+ * finished loading the catalog (AGL-2879). So a miss is not evidence the icon
+ * has no path: for an id that did NOT change it keeps the path already
+ * stored. For a changed id the lookup decides, and a miss clears the path,
+ * because the old icon's path is never the new icon's.
+ */
+export declare function iconPathsForSave(attributes: readonly Aglyn.AglynAttributeSchema[] | undefined | null, values: Record<string, unknown>, stored: Record<string, unknown> | undefined | null): Record<string, string | undefined>;
+/**
+ * An icon property's stored pick as the icon picker shows it: the icon's id,
+ * or `''` for nothing picked.
+ */
+export declare function formatIconPropValue(value: unknown): string;
+/**
+ * The icon picker's choice as the instance stores it: the id AND its SVG path,
+ * or unset.
+ *
+ * The path is looked up here, at the moment of the pick, for the reason
+ * `handleElementSave` stores `iconPath` beside an Icon element's `iconId`
+ * (AGL-1212): a published page never loads the icon catalog, so an id alone
+ * draws the empty Icon placeholder. This is the one moment the catalog is
+ * certainly loaded — the picker needed it to offer the icon — and an
+ * untouched field is never parsed again, so no later edit can look the id up
+ * against a catalog that has not arrived.
+ */
+export declare function parseIconPropValue(value: unknown): Aglyn.ReusableComponentIcon | undefined;
+/** Who a property belongs to, in the words its fields speak. */
+export type PropertyOwnerNoun = 'component' | 'layout';
+/** How {@link buildPropertyField} draws one property. */
+export interface PropertyFieldOptions {
+    /** The form path the field saves to, e.g. `propValues.headline`. */
+    name: string;
+    /**
+     * `value` for a page setting the property, where an empty field means "use
+     * the default" and says so; `default` for the Properties dialog declaring
+     * that default, where it means "no default".
+     */
+    role: 'value' | 'default';
+    /** Every property the owner declares, so a condition can read the others. */
+    declared?: readonly Aglyn.ReusableComponentProp[];
+    /** The form path a declared property's value sits at, by name. */
+    valuePath?: (propName: string) => string;
+    noun?: PropertyOwnerNoun;
+    /** Token-capable fields offer these in their `{}` menu. */
+    tokenOptions?: unknown;
+    tokenLabelContext?: unknown;
+    /** The site theme's scales, for the Theme scale and Theme preset kinds. */
+    themeScales?: Partial<Record<string, unknown>>;
+}
+/**
+ * A property's condition as the form renderer evaluates one (AGL-2893): each
+ * rule reads the named property's field, and compares what that property is
+ * worth on the page — its own value, else its default — the way the published
+ * page compares it, so the field shows exactly where the value applies.
+ *
+ * The operators are data-driven-forms' own; each rule becomes a function `is`
+ * only so an unset field can be read as its default first.
+ */
+export declare function propertyFieldCondition(condition: Aglyn.ReusableComponentProp['condition'], declared: readonly Aglyn.ReusableComponentProp[], valuePath: (propName: string) => string): unknown;
+/**
+ * One component or layout property as an Attributes field (AGL-1247,
+ * AGL-2893): the attribute schema field its kind names — a switch for a
+ * Yes / no, the icon picker for an Icon, the color picker for a Color — with
+ * the kind's options and settings, and the property's condition.
+ *
+ * The result is an attribute field like any coded component's, so it is
+ * finished by {@link resolveAttributeField} and drawn by
+ * `elementPropsComponentMapper`: the Properties dialog's Default, an
+ * instance's Attributes and a screen's layout values all edit a property with
+ * the control a coded component's attribute of that kind gets.
+ */
+export declare function buildPropertyField(prop: Aglyn.ReusableComponentProp, options: PropertyFieldOptions): Record<string, unknown>;
+/**
+ * One Attributes field per prop a reusable component declares (AGL-1247),
+ * so the same hero can carry different copy on eleven pages instead of
+ * being copied onto each — each drawn by {@link buildPropertyField} and
+ * finished by {@link resolveAttributeField}, like the component's own
+ * attributes.
+ *
+ * Fields are named for the `propValues.<name>` path the graft reads, so the
+ * form round-trips them through final-form's nested-path handling with no
+ * flatten/unflatten step. A name that is not an identifier is skipped
+ * rather than rendered as a field that could not save.
+ */
+export declare function buildInstancePropFields(declared: Aglyn.ReusableComponentProp[] | undefined, tokenOptions?: unknown, tokenLabelContext?: unknown, context?: AttributeFieldResolveContext & {
+    themeScales?: Partial<Record<string, unknown>>;
+}): Array<Record<string, unknown>>;
+/**
+ * One field per declared property for a page setting their values, at the
+ * paths `pathOf` names — an instance's `propValues`, or a screen's values for
+ * its layout.
+ */
+export declare function buildPropertyValueFields(declared: readonly Aglyn.ReusableComponentProp[] | undefined, options: {
+    pathOf: (propName: string) => string;
+    noun: PropertyOwnerNoun;
+    context?: AttributeFieldResolveContext;
+    themeScales?: Partial<Record<string, unknown>>;
+}): Array<Record<string, unknown>>;
+/** What {@link resolveAttributeField} reads beyond the field itself. */
+export interface AttributeFieldResolveContext {
+    /** The routing map and screen names, for Screen pickers. */
+    screens?: Aglyn.ScreenLinkContextValue['screens'];
+    labels?: Aglyn.ScreenLinkContextValue['labels'];
+    /** The values the form holds, so a picker can name what is stored. */
+    values?: Record<string, unknown> | null;
+    entityOptions?: Aglyn.EntityPickerContextValue;
+    /** The canvas's other elements, for element pickers. */
+    nodeOptions?: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    /** The dataset of the nearest ancestor that chose one. */
+    ancestorDatasetId?: string;
+    /** Whether the edited element's text is formatted markup. */
+    hasFormattedText?: boolean;
+    insertOptions?: unknown;
+    tokenLabelContext?: unknown;
+    /**
+     * Bumped when the installed-plugin set changes, so a memo holding this
+     * context re-resolves the Plugin picker (AGL-1030).
+     */
+    pluginInstallsVersion?: number;
+}
+/**
+ * An attribute field as the panel draws it: a declared kind that needs the
+ * site's data resolved into a dropdown the form renderer knows, a free-text
+ * field upgraded to the token editor, and every other field as declared.
+ *
+ * Pure, and the one place this happens — the element's own attributes, a
+ * component instance's properties and a screen's layout values all pass
+ * through it, so a kind cannot draw one way as an attribute and another as a
+ * property.
+ */
+export declare function resolveAttributeField<T extends Record<string, any>>(field: T, context?: AttributeFieldResolveContext): Record<string, any>;
+/**
+ * What a "Browse media" pick should ALSO write for `alt` (AGL-1896).
+ *
+ * The DAM has stored per-asset alt text since AGL-173 and nothing ever read
+ * it back, so an author placing the same logo on eight pages typed its alt
+ * eight times — and a field that must be retyped per placement is a field
+ * that ships blank, on the customer's published site.
+ *
+ * Exported and pure so the decision is testable on real inputs; the handler
+ * that calls it is inside a component wired to the live canvas.
+ *
+ * Two narrowings, both deliberate:
+ *
+ * * **`src` only.** The Browse button is offered on every media-ish
+ *   attribute — `poster`, `background`, `thumbnail`, `logo`. A poster
+ *   frame's description is not the element's alt text, and no attribute
+ *   pairing anywhere says which of those an `alt` belongs to. Guessing would
+ *   put the wrong sentence on the element and look like a bug.
+ * * **Only where the SCHEMA declares an `alt`.** Read off the element's own
+ *   attributes rather than assumed, so a component without one is never
+ *   handed a prop its renderer would drop on the floor.
+ *
+ * Returns `{}` — not `{ alt: undefined }` — whenever nothing should change,
+ * because the caller spreads the result into a props object that
+ * `updateNodeProps` REPLACES wholesale. An `alt` key present with an
+ * undefined value is indistinguishable from an authored empty alt to
+ * everything downstream, and would silently clear one.
+ */
+export declare function inheritedAltPatch(options: {
+    /** The attribute the Browse button was pressed for. */
+    propName: string;
+    /** Whether this element's schema declares an `alt` attribute at all. */
+    declaresAlt: boolean;
+    /** The node's CURRENT props, snapshotted from the canvas. */
+    props?: Record<string, unknown> | null;
+    /** The chosen DAM asset's own stored alt. */
+    assetAlt?: unknown;
+}): {
+    alt?: string;
+};
+/**
+ * The one kind of file a "Browse media" pick can place in an attribute, or
+ * `undefined` where the picker stays unnarrowed (AGL-2953).
+ *
+ * The Video element's `src` plays a film and its `poster` is the still shown
+ * before anyone presses play, so each opens a picker that lists only what it
+ * can use and uploads nothing else. Every other media attribute is left as it
+ * was, because nothing on it says what the element's renderer accepts.
+ *
+ * Exported and pure for the reason {@link inheritedAltPatch} is; keyed on the
+ * persisted component id, which is never renamed.
+ */
+export declare function browseMediaKind(options: {
+    /** The element being written to. */
+    componentId?: unknown;
+    /** The attribute the Browse button was pressed for. */
+    propName: string;
+}): Aglyn.MediaPickerKind | undefined;
+/**
+ * The two visibility fields every node inside a component definition gets
+ * (AGL-1314), so "this part is optional" is something an author declares by
+ * clicking rather than something the component hard-codes.
+ *
+ * Token-capable, because the value that decides is almost always the
+ * definition's own `{{prop.*}}`: `hideIf` takes a `boolean` prop ("Hide the
+ * mockup"), `hideUnless` takes the prop that would have supplied the
+ * content ("no link, no button" — AGL-1348).
+ *
+ * Offered ONLY where `{{prop.*}}` exists — inside a component editor,
+ * signalled by `BindingPickerContext.componentProps` exactly as the insert
+ * picker uses it. On an ordinary screen the directive is inert (the graft
+ * is the only thing that evaluates it), and a field that silently does
+ * nothing is worse than no field.
+ */
+export declare function buildVisibilityFields(tokenOptions?: unknown, tokenLabelContext?: unknown): Array<Record<string, unknown>>;
+/**
+ * The animation fields every element gets (AGL-2486).
+ *
+ * Presets rather than a keyframes box, because the audience includes people
+ * who have never written CSS: an author picks "Slide up", "on scroll into
+ * view", and adjusts a few obvious knobs. The knobs named — duration,
+ * delay, easing — plus stagger, and this is that list and nothing more. There
+ * is deliberately no keyframe editor and no general trigger picker; the
+ * things that are NOT offered (the distance a slide travels, the difference
+ * between a transition and a keyframe run, arbitrary curves) are decided for
+ * the author, and an author who needs them has the sx tab.
+ *
+ * Easing is a named list, never a `cubic-bezier()` text box. That keeps the
+ * curve out of author free-text — the id becomes a class and the curve is
+ * looked up in the tenant's own stylesheet — so there is nothing here for the
+ * sx sanitizer to have to catch.
+ *
+ * "Stagger children" is the one control that changes WHAT animates rather
+ * than how: the element stops animating and its children animate in
+ * sequence instead. It reads as a switch rather than a separate "Stagger"
+ * preset because stagger is orthogonal to fade/slide/zoom — a "Stagger"
+ * preset would have had to answer "stagger which animation?".
+ *
+ * Offered on every element, unlike the visibility directives above, because an
+ * animation is meaningful on any node on any screen — there is no context in
+ * which the field would be inert.
+ *
+ * The "None" option carries a real value, never `''` (AGL-1451/AGL-1191): an
+ * empty value cannot persist, so an author who picked a preset could never
+ * turn it back off.
+ *
+ * The dependent fields are gated on the PRESET rather than on "not none", so
+ * an element that has never been animated shows one dropdown and nothing else.
+ * `is` takes the explicit list; a `notMatch` against `'none'` would be true for
+ * the undefined case too and would show all five fields on every element.
+ */
+export declare function buildAnimationFields(): Array<Record<string, unknown>>;
+/**
+ * The Repeat fields every element gets (AGL-3111).
+ *
+ * Repeating used to be one component's feature: only the MUI Stack declared
+ * `repeatDataset`, so a card, an image or a placed component could not be
+ * data-driven at all. It is a node capability now, offered here the way
+ * visibility and animation are — and on a component instance too, which is the
+ * shape most authors reach for first.
+ *
+ * WHAT an element repeats over is not decided here. Each registered
+ * {@link RepeatSource} contributes its own key field under its own prop name,
+ * and the plugin that owns the rows registers it; this list names no kind of
+ * data. With nothing registered there is no Repeat section at all, which is
+ * correct rather than degraded: an editor with no source has nothing to repeat
+ * over.
+ *
+ * The bounds are shared by every source, because they are properties of the
+ * REPEAT and not of the rows: the composition applies the same filter, sort
+ * and limit whatever answered with the records. They are declared once, in
+ * core, as {@link REPEAT_NODE_CAPABILITY} — this panel draws them, and
+ * anything that has to describe what an author can build reads the same list.
+ * While the list lived here it was invisible to every other reader, and a
+ * reader that walked component schemas to find repeat found nothing at all.
+ *
+ * `hasChildren` decides whether the scope field is offered at all. An element
+ * with nothing inside it has only one possible reading — it repeats itself —
+ * and a control whose two options do the same thing is worse than no control.
+ */
+export declare function buildRepeatFields(options: {
+    sources: readonly RepeatSource[];
+    /** Whether the edited node holds a child list, which the scope field needs. */
+    hasChildren: boolean;
+    /** Finishes a key field that names an entity picker, as an attribute is. */
+    resolveKeyField: (field: Record<string, unknown>) => Record<string, unknown>;
+}): Array<Record<string, unknown>>;
+/**
+ * The list each entity picker DISPLAYS, keyed by the attribute type a
+ * component schema declares.
+ *
+ * One table rather than two switches, because the demand signal and the
+ * option list have to agree about which list a picker means. When they
+ * disagreed the failure was silent and total: the panel would open a
+ * listener on one collection and read its options out of another, and the
+ * dropdown stayed empty on a site full of data.
+ *
+ * `DATASET_FIELD_SELECT` is deliberately absent. Its options are the model
+ * fields of the dataset an ANCESTOR chose, so it needs the dataset list to
+ * resolve against but is not itself a picker OF datasets — it asks for the
+ * list below and renders its own options.
+ */
+export declare const ENTITY_PICKER_KINDS: Readonly<Partial<Record<Aglyn.FieldComponentType, Aglyn.EntityPickerKind>>>;
+/**
+ * The label on an entity picker's empty first option.
+ *
+ * An empty dropdown and a broken dropdown look identical, and an author who
+ * cannot tell them apart goes looking for a form they already made. So the
+ * four reasons a picker has nothing say four different things, and only the
+ * settled one claims anything about the site.
+ */
+export declare function entityPickerPlaceholder(kind: Aglyn.EntityPickerKind, state: Aglyn.EntityListState, count: number): string;
+/**
+ * What a picker owes the reader about the list it is showing.
+ *
+ * A browse window is a PAGE of the site's catalog, and a page that does not
+ * say so is the silent-truncation defect: "not in the picker" and "does not
+ * exist" are the same absence to look at, and only one of them is a fact
+ * about their site. The inbox's form filter carries the same sentence for the
+ * same reason.
+ *
+ * Two sentences, because the second half is only true for a kind whose
+ * documents carry the name-search keys. A picker that promised to search the
+ * whole catalog and then searched 25 rows would be a worse lie than saying
+ * nothing.
+ */
+export declare function entityPickerBrowseNotice(kind: Aglyn.EntityPickerKind, context: Aglyn.EntityPickerContextValue | undefined): string | undefined;
+/**
+ * What the dropdown says when the reader's typing matches nothing it holds.
+ *
+ * On a truncated list that cannot be searched on the server, "no match" is a
+ * statement about the WINDOW and must not be read as one about the site —
+ * this is where an author concludes a form they already made does not exist
+ * and makes a second one.
+ */
+export declare function entityPickerNoMatchText(kind: Aglyn.EntityPickerKind, context: Aglyn.EntityPickerContextValue | undefined): string;
+/**
+ * The extra option a picker needs when its stored value is not in the window.
+ *
+ * The counterpart to {@link Aglyn.unresolvedScreenOption}, and it exists for
+ * the same reason: a picker whose value matches no option renders BLANK, which
+ * reads as "nothing chosen" on an element that is bound. An author repairs
+ * that by choosing again — which is how a correct reference gets replaced with
+ * a different one.
+ *
+ * Returns the stored value UNCHANGED as the option's value. Naming a
+ * selection must never rewrite it.
+ *
+ * A value nothing has answered for yet shows as the raw id, NOT as a warning.
+ * Flashing "unavailable" over every live reference for the beat before the
+ * keyed read lands would teach authors to ignore the one warning that means
+ * something — the same call `unavailableScreenLabel` makes.
+ *
+ * The exception is a picker that has settled and has no way to look anything
+ * up. There is no answer coming, so the raw value is all there will ever be,
+ * and left unmarked it would read as a resolved name — which is exactly what
+ * a free-text caption stored where an id belongs looks like.
+ */
+export declare function entitySelectionOption(context: Aglyn.EntityPickerContextValue | undefined, kind: Aglyn.EntityPickerKind, value: unknown): {
+    value: string;
+    label: string;
+} | undefined;
+/**
+ * An entity picker rendered as the SELECT the form renderer knows how to
+ * draw, resolved against whatever the surface's picker context can offer.
+ *
+ * Three things this must not do, each of which renders as something other
+ * than a broken picker.
+ *
+ * Every option carries the entity's ID, never its label. The label is
+ * resolved fresh at edit time and a rename moves it; the id is the whole
+ * reference, and for a form it is the difference between one submission list
+ * and two (`docs/specs/reusable-forms.md` §2c).
+ *
+ * The field is decided by the attribute's own TYPE, not by whether a list
+ * happens to have arrived. Keying off the list meant a surface with no picker
+ * context dropped the attribute from the panel entirely — no control, no
+ * explanation, indistinguishable from a component that simply has no such
+ * setting. A picker with nothing to offer must still be a picker, and must
+ * say what is wrong.
+ *
+ * And the STORED VALUE is offered whether or not the browse window contains
+ * it, which is what lets that window be a console page rather than hundreds
+ * of documents. A picker that took its options and its current selection from
+ * one list needs the list wide enough to hold whatever an author picked last
+ * month, and past that width renders a bound element as unbound anyway. The
+ * selection is a keyed read; this is where its answer is offered.
+ */
+export declare function buildEntityPickerField<T extends Aglyn.AglynAttributeSchema>(field: T, kind: Aglyn.EntityPickerKind, context: Aglyn.EntityPickerContextValue | undefined, value?: unknown): T & {
+    noOptionsText: () => string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    helperText?: string;
+    onSearchInput?: (text: string, reason?: string) => void;
+    isSearchable: boolean;
+    onOpen?: () => void;
+    component: Aglyn.FieldComponentType;
+};
+/**
+ * Which entity lists a node's attributes will need (AGL-703).
+ *
+ * The provider that owns those lists reads them from Firestore, and it used
+ * to read all four the moment the besigner opened — up to 300 products, 200
+ * catalog collections, 200 categories and 200 datasets — for pickers most
+ * editing sessions never open. This is the demand signal that replaced that:
+ * a node whose schema declares the picker.
+ *
+ * `DATASET_FIELD_SELECT` asks for `datasets` and not for some list of its
+ * own, which is the one mapping worth stating: its options are the model
+ * fields of the dataset an ANCESTOR chose, so it cannot resolve one without
+ * the dataset list to resolve it against.
+ *
+ * Exported for the test that pins the mapping — a picker silently missing
+ * from {@link ENTITY_PICKER_KINDS} renders as a permanently empty dropdown,
+ * which looks exactly like a site with no products.
+ */
+export declare function entityKindsForAttributes(attributes: readonly Aglyn.AglynAttributeSchema[] | undefined): Aglyn.EntityPickerKind[];
+export declare const ElementPropsForm: import("react").FunctionComponent<ElementPropsFormProps & import("react").RefAttributes<any>>;
+export default ElementPropsForm;