@aglyn/aglyn 1.0.0-beta.143

package/src/lib/foundation/definitions/components.types.d.ts

@@ -0,0 +1,372 @@
+/**
+ * @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 type { ConditionDefinition, DataType, Validator } from '@data-driven-forms/react-form-renderer';
+import type { FieldActions, ResolvePropsFunction } from '@data-driven-forms/react-form-renderer/common-types';
+import type { SvgIconProps } from '@mui/material';
+import type { MuiStyledOptions } from '@mui/system/createStyled';
+import type { CANVAS_ROOT_ELEMENT_ID } from '../constants/canvas';
+import type { ComponentCategory } from '../constants/components';
+import type { FEATURE_FLAG, RICH_TEXT_COMMANDS } from '../constants/shared';
+import type { AGLYN_OF, SYMBOL_TYPE } from '../constants/symbol';
+export declare enum LinealDirectiveFlag {
+    LIMIT_TO = "limitedTo",
+    DISALLOW = "forbid"
+}
+export type BundleId = string;
+export type PluginId = string;
+export type ComponentId = string;
+export type PresetId = string;
+export type NodeId = string;
+export type ComponentsLinealOrder = [
+    directiveType: LinealDirectiveFlag,
+    directiveDefinition: Array<ComponentId> | {
+        plugins?: Array<PluginId>;
+        components: Array<ComponentId>;
+    } | {
+        plugins: Array<PluginId>;
+        components?: Array<ComponentId>;
+    }
+];
+export type AglynNodeItemDenormalized<P = JSX.AnyProps> = AglynNodeSchema<P> & {
+    nodes?: AglynNodeItemDenormalized[];
+};
+export type AglynNodesList = Array<AglynNodeItemDenormalized>;
+export type AglynNodeHierarchy<$ID extends NodeId = NodeId> = [
+    root: CANVAS_ROOT_ELEMENT_ID,
+    ...nodes: [...ancestors: NodeId[], element: $ID]
+];
+export interface AglynExoticComponent<PROPS = any, REF = any> extends JSX.ForwardRefExoticComponent<JSX.PropsWithoutRef<PROPS> & JSX.RefAttributes<REF>> {
+    [AGLYN_OF]?: SYMBOL_TYPE;
+    aglyn?: boolean;
+    schema?: AglynComponentSchema<PROPS>;
+}
+export interface AglynComponentSchema<P = any> {
+    $id: ComponentId;
+    pluginId?: BundleId;
+    kind?: 'element' | 'plaintext' | 'markdown';
+    displayName: string;
+    title?: string;
+    subtitle?: string;
+    description?: string;
+    /**
+     * Icon props for display around besigner
+     */
+    icon?: SvgIconProps;
+    /**
+     * Options to be passed to styled(Component, \{...styledOptions\})
+     */
+    styledOptions?: MuiStyledOptions;
+    /**
+     * Define a limitation for nodes allowed as direct descendents
+     */
+    restrictChildren?: ComponentsLinealOrder;
+    /**
+     * Define a limitation for nodes allowed to be direct ancestors
+     */
+    restrictParent?: ComponentsLinealOrder;
+    /**
+     * Filter props
+     */
+    resolveProps?: JSX.ResolveProps<AglynNodeItemDenormalized<P>>;
+    /**
+     * Attribute fields to modify the contextual properties
+     * New version
+     */
+    attributes?: AglynAttributeSchema[];
+    /**
+     * Which groups of formatting the inline rich-text toolbar offers for this
+     * component (AGL-2557). Read only where `flags.richTextEditable` is on.
+     *
+     * Omitted means every group, which is what leaves Typography exactly as it
+     * was. Naming a subset narrows the toolbar AND the commit: a surface that
+     * offers neither lists nor links is phrasing-only, and the sanitizer holds
+     * it to that whatever an author pastes in.
+     */
+    richTextCommands?: RICH_TEXT_COMMANDS[];
+    /**
+     * Feature flags
+     */
+    flags?: {
+        /**
+         * Disable the use of emotion styled
+         */
+        emotion?: FEATURE_FLAG;
+        /**
+         * Can the nodes of this component type be cloned?
+         */
+        cloning?: FEATURE_FLAG;
+        /**
+         * Allow dragging nodes of this component type
+         */
+        dragging?: FEATURE_FLAG;
+        /**
+         * Allow dropping nodes inside nodes of this component type
+         */
+        dropping?: FEATURE_FLAG;
+        /**
+         * Allow editing element attributes of this component type
+         */
+        editing?: FEATURE_FLAG;
+        /**
+         * Allow removing nodes of this component type
+         */
+        removing?: FEATURE_FLAG;
+        /**
+         * Describe nodes of this component type to be self-closing
+         */
+        selfClosing?: FEATURE_FLAG;
+        /**
+         * Component renders its `children` prop as text content the editor may
+         * edit directly (Attributes "Text" field, inline canvas editing).
+         */
+        textEditable?: FEATURE_FLAG;
+        /**
+         * Component also accepts basic rich text (AGL-54): sanitized HTML in the
+         * `html` prop with `children` as the plain-text fallback.
+         */
+        richTextEditable?: FEATURE_FLAG;
+        /**
+         * Component reads its children POSITIONALLY (AGL-1237), so the renderer
+         * must hand it one React child per node child instead of the single
+         * `<Branch>` element it normally passes.
+         *
+         * MUI's Accordion does `const [summary, ...rest] = Children.toArray(children)`,
+         * and `toArray` does not traverse into an element — so with the default
+         * wrapping the summary swallowed the whole subtree and the Collapse got
+         * nothing. Every accordion on every published site expanded to reveal an
+         * empty panel while its content rendered unconditionally inside the
+         * summary's `<h3>`.
+         *
+         * Opt in only for components with this contract; the wrapper is what
+         * keeps the Branch/Stem/Leaf seam swappable for everything else.
+         */
+        positionalChildren?: FEATURE_FLAG;
+    };
+    /**
+     * Preset items are the available items to add to the canvas
+     */
+    presets?: AglynNodePresetSchema[];
+}
+export type NodePresetData = Omit<AglynNodeSchema, '$id' | 'nodes'> & {
+    $id?: NodeId;
+    nodes?: NodePresetData[];
+};
+export type AglynNodePresetSchema = {
+    $id: PresetId;
+    label: string;
+    componentId?: ComponentId;
+    pluginId?: BundleId;
+    description?: string;
+    icon?: SvgIconProps;
+    category?: string | ComponentCategory;
+    data: NodePresetData;
+};
+export declare enum FieldComponentType {
+    /**
+     * Per-breakpoint span editor (AGL-2486): a small row of breakpoint
+     * controls (All / xs / sm / md / lg / xl), each offering a column count
+     * plus MUI's `auto` and `grow` keywords. The persisted prop is still ONE
+     * string in the syntax the Grid element already parses (`"6"`, `"auto"`,
+     * `"xs:12 md:6"`) — this is an input affordance, not a shape change, so
+     * renderers and existing documents stay untouched. A value the row cannot
+     * model (a `{{token}}`, an unknown breakpoint) falls back to free text
+     * rather than being clobbered.
+     */
+    BREAKPOINT_SPAN = "breakpoint-span",
+    BUTTON = "button",
+    BUTTON_GROUP = "button-group",
+    CHECKBOX = "checkbox",
+    COLOR_PICKER = "color-picker",
+    /**
+     * Border editor (AGL-2486): a thickness box plus a plain-English line-style
+     * picker (solid / dashed / dotted / double / no line). The persisted prop is
+     * still ONE CSS shorthand string (`"1px solid"`, `"none"`, `""`), so
+     * renderers and existing documents stay untouched. A value the pair cannot
+     * model (`thin solid`, `1px solid #f00`, a binding token) falls back to free
+     * text rather than being clobbered, and flips back the moment the text is a
+     * plain `<width> <style>` again.
+     */
+    CSS_BORDER = "css-border",
+    /**
+     * CSS length editor (AGL-1219): a number box plus a unit picker sharing
+     * the styles panel's unit list. The persisted prop is still ONE CSS
+     * string (`"920px"`, `"100%"`, `"auto"`, `""`) — this is an input
+     * affordance, not a shape change, so renderers stay untouched. Values
+     * the picker can't model (`calc(…)`, a binding token) fall back to free
+     * text rather than being clobbered.
+     */
+    CSS_DIMENSION = "css-dimension",
+    /**
+     * Background fill editor (AGL-1331): a fill-type switch (default / solid
+     * / linear / radial) over an angle box and a colour-stop list, each stop
+     * bindable to a palette token or a literal. The persisted prop is ONE CSS
+     * string under `backgroundImage` — a solid fill writes the explicit
+     * keyword `none` and leaves `backgroundColor` to do the job, while the
+     * default choice writes nothing at all (AGL-1338: the two differ on a
+     * component instance, where absence means "keep the component's fill") —
+     * so renderers stay untouched. Values
+     * the editor cannot model (`conic-gradient`, `to bottom right`, a stacked
+     * image list) fall back to free text rather than being clobbered.
+     */
+    CSS_GRADIENT = "css-gradient",
+    /**
+     * Row-and-column grid editor for the Table element (AGL-2543).
+     *
+     * The persisted prop is still ONE string — pipe-delimited rows with the
+     * markdown divider carrying per-column alignment — so the renderer and
+     * existing documents stay untouched, and a comparison table already
+     * authored inside a Markdown element pastes straight in. This is the
+     * affordance that makes the element no-code: without it an author edits
+     * pipe syntax, which is the audience the besigner exists to spare.
+     */
+    DATA_TABLE = "data-table",
+    DATE_PICKER = "date-picker",
+    DUAL_LIST_SELECT = "dual-list-select",
+    FIELD_ARRAY = "field-array",
+    ICON_PICKER = "icon-picker",
+    /**
+     * markdown-lite document editor (AGL-1616): the WYSIWYG the console
+     * already ships for blog entries and marketplace listings, rendered as the
+     * attribute's field. The persisted prop is still ONE markdown-lite string,
+     * so every renderer stays untouched — this is an input affordance, not a
+     * shape change. Declared by an attribute whose value is a whole document
+     * rather than a line of text; a plain TEXTAREA meant the Privacy Policy
+     * body was edited as a 13 KB raw paste (AGL-1594).
+     */
+    MARKDOWN = "markdown",
+    INPUT_ADDON_BUTTON_GROUP = "input-addon-button-group",
+    INPUT_ADDON_GROUP = "input-addon-group",
+    PLAIN_TEXT = "plain-text",
+    /**
+     * Named-preset picker with a raw escape hatch (AGL-2486): the theme's own
+     * answers first, then plain-English presets that PREVIEW themselves, then
+     * Custom…. The persisted prop is whatever the property already stored — a
+     * number where a bare number is a theme multiple, a CSS string otherwise —
+     * and a stored value matching no preset opens the field in its custom state
+     * holding that value rather than dropping it.
+     */
+    PRESET_CHOICE = "preset-choice",
+    RADIO = "radio",
+    /**
+     * Select listing the host's screens; the editor resolves the options from
+     * the host routing map at render time and writes the chosen screen id.
+     */
+    SCREEN_SELECT = "screen-select",
+    /**
+     * Select listing the canvas's other elements (AGL-557): the editor
+     * resolves options from the live canvas at edit time and persists the
+     * node id — e.g. the form's reveal-on-submit target.
+     */
+    NODE_SELECT = "node-select",
+    /**
+     * Id-based entity pickers (AGL-343/344): the editor resolves options
+     * from EntityPickerContext at edit time and persists the entity id —
+     * renames never break the reference.
+     */
+    /**
+     * Select listing the plugins installed for this site (AGL-1030): the editor
+     * resolves options from the install set the console publishes and persists
+     * the listing id. A picker rather than a typed document id — the same reason
+     * every other reference in the designer is one, and here it also removes the
+     * "is this installed?" question by construction.
+     */
+    PLUGIN_SELECT = "plugin-select",
+    /**
+     * A placed plugin's declared settings, rendered as real fields (AGL-1049).
+     * Reads the sibling plugin selection to know which manifest to offer.
+     */
+    PLUGIN_SETTINGS = "plugin-settings",
+    PRODUCT_SELECT = "product-select",
+    COLLECTION_SELECT = "collection-select",
+    CATEGORY_SELECT = "category-select",
+    DATASET_SELECT = "dataset-select",
+    /**
+     * Select listing the model fields of the nearest ancestor node's chosen
+     * dataset (AGL-556): the editor resolves options from
+     * EntityPickerContext.datasetFields using the ancestor's `datasetId`
+     * (or legacy `datasetName` matched by label) and persists the stable
+     * model fieldId — field renames never break the mapping.
+     */
+    DATASET_FIELD_SELECT = "dataset-field-select",
+    /**
+     * Select listing the host's form entities (`docs/specs/reusable-forms.md`
+     * §2c): the editor resolves options from EntityPickerContext.forms and
+     * persists the form id. The same id-first reasoning as every picker in this
+     * family, and here it is load-bearing rather than convenient — the string
+     * it replaces was the form's whole identity, so a rename split the
+     * submission history it named.
+     */
+    FORM_SELECT = "form-select",
+    SELECT = "select",
+    SLIDER = "slider",
+    SUB_FORM = "sub-form",
+    SWITCH = "switch",
+    TAB_ITEM = "tab-item",
+    TABS = "tabs",
+    TEXT_FIELD = "text-field",
+    TEXTAREA = "textarea",
+    /**
+     * Theme-scale combo box (AGL-2486): offers the THEME's own scale for a
+     * property — `theme.typography` for font size and weight,
+     * `theme.zIndex` for stacking — while still accepting any raw value
+     * (`18px`, `1.25rem`, `700`, `1400`), because arbitrary values are
+     * legitimate. The persisted value is a theme token PATH
+     * (`h4.fontSize`, `fontWeightBold`, `appBar`), which MUI's sx system
+     * resolves against the active theme exactly as it resolves
+     * `color: 'primary.main'` — so the element keeps following the theme
+     * instead of freezing the number it had when it was styled.
+     */
+    THEME_SCALE = "theme-scale",
+    TIME_PICKER = "time-picker",
+    TOGGLE_BUTTON = "toggle-button",
+    WIZARD = "wizard"
+}
+export declare enum FieldValidatorType {
+    EXACT_LENGTH = "exact-length",
+    MAX_LENGTH = "max-length",
+    MAX_NUMBER_VALUE = "max-number-value",
+    MIN_ITEMS = "min-items",
+    MIN_LENGTH = "min-length",
+    MIN_NUMBER_VALUE = "min-number-value",
+    PATTERN = "pattern",
+    REQUIRED = "required",
+    URL = "url"
+}
+export type FieldDataType = 'boolean' | 'float' | 'integer' | 'number' | 'string';
+export interface AglynAttributeSchema extends Dictionary<any> {
+    name: string;
+    dataType?: DataType;
+    component: string | FieldComponentType;
+    validate?: Validator[];
+    condition?: ConditionDefinition | ConditionDefinition[];
+    initializeOnMount?: boolean;
+    initialValue?: unknown;
+    clearedValue?: unknown;
+    clearOnUnmount?: boolean;
+    actions?: FieldActions;
+    resolveProps?: ResolvePropsFunction;
+    description?: string;
+}
+export interface AglynNodeSchema<P = JSX.AnyProps> {
+    $id: NodeId;
+    componentId: ComponentId;
+    pluginId?: BundleId;
+    parentId?: NodeId;
+    sx?: JSX.SxProps;
+    props?: P;
+    nodes?: NodeId[] | AglynNodeSchema[];
+}

package/src/lib/foundation/definitions/components.types.js

@@ -0,0 +1,180 @@
+/**
+ * @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.
+ */ export var LinealDirectiveFlag = /*#__PURE__*/ function(LinealDirectiveFlag) {
+    LinealDirectiveFlag["LIMIT_TO"] = "limitedTo";
+    LinealDirectiveFlag["DISALLOW"] = "forbid";
+    return LinealDirectiveFlag;
+}({});
+export var FieldComponentType = /*#__PURE__*/ function(FieldComponentType) {
+    /**
+   * Per-breakpoint span editor (AGL-2486): a small row of breakpoint
+   * controls (All / xs / sm / md / lg / xl), each offering a column count
+   * plus MUI's `auto` and `grow` keywords. The persisted prop is still ONE
+   * string in the syntax the Grid element already parses (`"6"`, `"auto"`,
+   * `"xs:12 md:6"`) — this is an input affordance, not a shape change, so
+   * renderers and existing documents stay untouched. A value the row cannot
+   * model (a `{{token}}`, an unknown breakpoint) falls back to free text
+   * rather than being clobbered.
+   */ FieldComponentType["BREAKPOINT_SPAN"] = "breakpoint-span";
+    FieldComponentType["BUTTON"] = "button";
+    FieldComponentType["BUTTON_GROUP"] = "button-group";
+    FieldComponentType["CHECKBOX"] = "checkbox";
+    FieldComponentType["COLOR_PICKER"] = "color-picker";
+    /**
+   * Border editor (AGL-2486): a thickness box plus a plain-English line-style
+   * picker (solid / dashed / dotted / double / no line). The persisted prop is
+   * still ONE CSS shorthand string (`"1px solid"`, `"none"`, `""`), so
+   * renderers and existing documents stay untouched. A value the pair cannot
+   * model (`thin solid`, `1px solid #f00`, a binding token) falls back to free
+   * text rather than being clobbered, and flips back the moment the text is a
+   * plain `<width> <style>` again.
+   */ FieldComponentType["CSS_BORDER"] = "css-border";
+    /**
+   * CSS length editor (AGL-1219): a number box plus a unit picker sharing
+   * the styles panel's unit list. The persisted prop is still ONE CSS
+   * string (`"920px"`, `"100%"`, `"auto"`, `""`) — this is an input
+   * affordance, not a shape change, so renderers stay untouched. Values
+   * the picker can't model (`calc(…)`, a binding token) fall back to free
+   * text rather than being clobbered.
+   */ FieldComponentType["CSS_DIMENSION"] = "css-dimension";
+    /**
+   * Background fill editor (AGL-1331): a fill-type switch (default / solid
+   * / linear / radial) over an angle box and a colour-stop list, each stop
+   * bindable to a palette token or a literal. The persisted prop is ONE CSS
+   * string under `backgroundImage` — a solid fill writes the explicit
+   * keyword `none` and leaves `backgroundColor` to do the job, while the
+   * default choice writes nothing at all (AGL-1338: the two differ on a
+   * component instance, where absence means "keep the component's fill") —
+   * so renderers stay untouched. Values
+   * the editor cannot model (`conic-gradient`, `to bottom right`, a stacked
+   * image list) fall back to free text rather than being clobbered.
+   */ FieldComponentType["CSS_GRADIENT"] = "css-gradient";
+    /**
+   * Row-and-column grid editor for the Table element (AGL-2543).
+   *
+   * The persisted prop is still ONE string — pipe-delimited rows with the
+   * markdown divider carrying per-column alignment — so the renderer and
+   * existing documents stay untouched, and a comparison table already
+   * authored inside a Markdown element pastes straight in. This is the
+   * affordance that makes the element no-code: without it an author edits
+   * pipe syntax, which is the audience the besigner exists to spare.
+   */ FieldComponentType["DATA_TABLE"] = "data-table";
+    FieldComponentType["DATE_PICKER"] = "date-picker";
+    FieldComponentType["DUAL_LIST_SELECT"] = "dual-list-select";
+    FieldComponentType["FIELD_ARRAY"] = "field-array";
+    FieldComponentType["ICON_PICKER"] = "icon-picker";
+    /**
+   * markdown-lite document editor (AGL-1616): the WYSIWYG the console
+   * already ships for blog entries and marketplace listings, rendered as the
+   * attribute's field. The persisted prop is still ONE markdown-lite string,
+   * so every renderer stays untouched — this is an input affordance, not a
+   * shape change. Declared by an attribute whose value is a whole document
+   * rather than a line of text; a plain TEXTAREA meant the Privacy Policy
+   * body was edited as a 13 KB raw paste (AGL-1594).
+   */ FieldComponentType["MARKDOWN"] = "markdown";
+    FieldComponentType["INPUT_ADDON_BUTTON_GROUP"] = "input-addon-button-group";
+    FieldComponentType["INPUT_ADDON_GROUP"] = "input-addon-group";
+    FieldComponentType["PLAIN_TEXT"] = "plain-text";
+    /**
+   * Named-preset picker with a raw escape hatch (AGL-2486): the theme's own
+   * answers first, then plain-English presets that PREVIEW themselves, then
+   * Custom…. The persisted prop is whatever the property already stored — a
+   * number where a bare number is a theme multiple, a CSS string otherwise —
+   * and a stored value matching no preset opens the field in its custom state
+   * holding that value rather than dropping it.
+   */ FieldComponentType["PRESET_CHOICE"] = "preset-choice";
+    FieldComponentType["RADIO"] = "radio";
+    /**
+   * Select listing the host's screens; the editor resolves the options from
+   * the host routing map at render time and writes the chosen screen id.
+   */ FieldComponentType["SCREEN_SELECT"] = "screen-select";
+    /**
+   * Select listing the canvas's other elements (AGL-557): the editor
+   * resolves options from the live canvas at edit time and persists the
+   * node id — e.g. the form's reveal-on-submit target.
+   */ FieldComponentType["NODE_SELECT"] = "node-select";
+    /**
+   * Id-based entity pickers (AGL-343/344): the editor resolves options
+   * from EntityPickerContext at edit time and persists the entity id —
+   * renames never break the reference.
+   */ /**
+   * Select listing the plugins installed for this site (AGL-1030): the editor
+   * resolves options from the install set the console publishes and persists
+   * the listing id. A picker rather than a typed document id — the same reason
+   * every other reference in the designer is one, and here it also removes the
+   * "is this installed?" question by construction.
+   */ FieldComponentType["PLUGIN_SELECT"] = "plugin-select";
+    /**
+   * A placed plugin's declared settings, rendered as real fields (AGL-1049).
+   * Reads the sibling plugin selection to know which manifest to offer.
+   */ FieldComponentType["PLUGIN_SETTINGS"] = "plugin-settings";
+    FieldComponentType["PRODUCT_SELECT"] = "product-select";
+    FieldComponentType["COLLECTION_SELECT"] = "collection-select";
+    FieldComponentType["CATEGORY_SELECT"] = "category-select";
+    FieldComponentType["DATASET_SELECT"] = "dataset-select";
+    /**
+   * Select listing the model fields of the nearest ancestor node's chosen
+   * dataset (AGL-556): the editor resolves options from
+   * EntityPickerContext.datasetFields using the ancestor's `datasetId`
+   * (or legacy `datasetName` matched by label) and persists the stable
+   * model fieldId — field renames never break the mapping.
+   */ FieldComponentType["DATASET_FIELD_SELECT"] = "dataset-field-select";
+    /**
+   * Select listing the host's form entities (`docs/specs/reusable-forms.md`
+   * §2c): the editor resolves options from EntityPickerContext.forms and
+   * persists the form id. The same id-first reasoning as every picker in this
+   * family, and here it is load-bearing rather than convenient — the string
+   * it replaces was the form's whole identity, so a rename split the
+   * submission history it named.
+   */ FieldComponentType["FORM_SELECT"] = "form-select";
+    FieldComponentType["SELECT"] = "select";
+    FieldComponentType["SLIDER"] = "slider";
+    FieldComponentType["SUB_FORM"] = "sub-form";
+    FieldComponentType["SWITCH"] = "switch";
+    FieldComponentType["TAB_ITEM"] = "tab-item";
+    FieldComponentType["TABS"] = "tabs";
+    FieldComponentType["TEXT_FIELD"] = "text-field";
+    FieldComponentType["TEXTAREA"] = "textarea";
+    /**
+   * Theme-scale combo box (AGL-2486): offers the THEME's own scale for a
+   * property — `theme.typography` for font size and weight,
+   * `theme.zIndex` for stacking — while still accepting any raw value
+   * (`18px`, `1.25rem`, `700`, `1400`), because arbitrary values are
+   * legitimate. The persisted value is a theme token PATH
+   * (`h4.fontSize`, `fontWeightBold`, `appBar`), which MUI's sx system
+   * resolves against the active theme exactly as it resolves
+   * `color: 'primary.main'` — so the element keeps following the theme
+   * instead of freezing the number it had when it was styled.
+   */ FieldComponentType["THEME_SCALE"] = "theme-scale";
+    FieldComponentType["TIME_PICKER"] = "time-picker";
+    FieldComponentType["TOGGLE_BUTTON"] = "toggle-button";
+    FieldComponentType["WIZARD"] = "wizard";
+    return FieldComponentType;
+}({});
+export var FieldValidatorType = /*#__PURE__*/ function(FieldValidatorType) {
+    FieldValidatorType["EXACT_LENGTH"] = "exact-length";
+    FieldValidatorType["MAX_LENGTH"] = "max-length";
+    FieldValidatorType["MAX_NUMBER_VALUE"] = "max-number-value";
+    FieldValidatorType["MIN_ITEMS"] = "min-items";
+    FieldValidatorType["MIN_LENGTH"] = "min-length";
+    FieldValidatorType["MIN_NUMBER_VALUE"] = "min-number-value";
+    FieldValidatorType["PATTERN"] = "pattern";
+    FieldValidatorType["REQUIRED"] = "required";
+    FieldValidatorType["URL"] = "url";
+    return FieldValidatorType;
+}({});
+
+//# sourceMappingURL=components.types.js.map

package/src/lib/foundation/definitions/components.types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/aglyn/src/lib/foundation/definitions/components.types.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n  ConditionDefinition,\n  DataType,\n  Validator,\n} from '@data-driven-forms/react-form-renderer'\nimport type {\n  FieldActions,\n  ResolvePropsFunction,\n} from '@data-driven-forms/react-form-renderer/common-types'\nimport type { SvgIconProps } from '@mui/material'\nimport type { MuiStyledOptions } from '@mui/system/createStyled'\nimport type { CANVAS_ROOT_ELEMENT_ID } from '../constants/canvas'\nimport type { ComponentCategory } from '../constants/components'\nimport type { FEATURE_FLAG, RICH_TEXT_COMMANDS } from '../constants/shared'\nimport type { AGLYN_OF, SYMBOL_TYPE } from '../constants/symbol'\n\nexport enum LinealDirectiveFlag {\n  LIMIT_TO = 'limitedTo',\n  DISALLOW = 'forbid',\n}\n\nexport type BundleId = string\nexport type PluginId = string\nexport type ComponentId = string\nexport type PresetId = string\nexport type NodeId = string\n\nexport type ComponentsLinealOrder = [\n  directiveType: LinealDirectiveFlag,\n  directiveDefinition:\n    | Array<ComponentId>\n    | { plugins?: Array<PluginId>; components: Array<ComponentId> }\n    | { plugins: Array<PluginId>; components?: Array<ComponentId> },\n]\n\nexport type AglynNodeItemDenormalized<P = JSX.AnyProps> = AglynNodeSchema<P> & {\n  nodes?: AglynNodeItemDenormalized[]\n}\n\nexport type AglynNodesList = Array<AglynNodeItemDenormalized>\n\nexport type AglynNodeHierarchy<$ID extends NodeId = NodeId> = [\n  root: CANVAS_ROOT_ELEMENT_ID,\n  ...nodes: [...ancestors: NodeId[], element: $ID],\n]\n\nexport interface AglynExoticComponent<PROPS = any, REF = any>\n  extends JSX.ForwardRefExoticComponent<\n    JSX.PropsWithoutRef<PROPS> & JSX.RefAttributes<REF>\n  > {\n  [AGLYN_OF]?: SYMBOL_TYPE\n  aglyn?: boolean\n  schema?: AglynComponentSchema<PROPS>\n}\n\nexport interface AglynComponentSchema<P = any> {\n  $id: ComponentId\n  pluginId?: BundleId\n  kind?: 'element' | 'plaintext' | 'markdown'\n\n  displayName: string\n  title?: string\n  subtitle?: string\n  description?: string\n\n  /**\n   * Icon props for display around besigner\n   */\n  icon?: SvgIconProps\n  /**\n   * Options to be passed to styled(Component, \\{...styledOptions\\})\n   */\n  styledOptions?: MuiStyledOptions\n\n  /**\n   * Define a limitation for nodes allowed as direct descendents\n   */\n  restrictChildren?: ComponentsLinealOrder\n  /**\n   * Define a limitation for nodes allowed to be direct ancestors\n   */\n  restrictParent?: ComponentsLinealOrder\n\n  /**\n   * Filter props\n   */\n  resolveProps?: JSX.ResolveProps<AglynNodeItemDenormalized<P>>\n\n  /**\n   * Attribute fields to modify the contextual properties\n   * New version\n   */\n  attributes?: AglynAttributeSchema[]\n\n  /**\n   * Which groups of formatting the inline rich-text toolbar offers for this\n   * component (AGL-2557). Read only where `flags.richTextEditable` is on.\n   *\n   * Omitted means every group, which is what leaves Typography exactly as it\n   * was. Naming a subset narrows the toolbar AND the commit: a surface that\n   * offers neither lists nor links is phrasing-only, and the sanitizer holds\n   * it to that whatever an author pastes in.\n   */\n  richTextCommands?: RICH_TEXT_COMMANDS[]\n\n  /**\n   * Feature flags\n   */\n  flags?: {\n    /**\n     * Disable the use of emotion styled\n     */\n    emotion?: FEATURE_FLAG\n    /**\n     * Can the nodes of this component type be cloned?\n     */\n    cloning?: FEATURE_FLAG\n    /**\n     * Allow dragging nodes of this component type\n     */\n    dragging?: FEATURE_FLAG\n    /**\n     * Allow dropping nodes inside nodes of this component type\n     */\n    dropping?: FEATURE_FLAG\n    /**\n     * Allow editing element attributes of this component type\n     */\n    editing?: FEATURE_FLAG\n    /**\n     * Allow removing nodes of this component type\n     */\n    removing?: FEATURE_FLAG\n    /**\n     * Describe nodes of this component type to be self-closing\n     */\n    selfClosing?: FEATURE_FLAG\n    /**\n     * Component renders its `children` prop as text content the editor may\n     * edit directly (Attributes \"Text\" field, inline canvas editing).\n     */\n    textEditable?: FEATURE_FLAG\n    /**\n     * Component also accepts basic rich text (AGL-54): sanitized HTML in the\n     * `html` prop with `children` as the plain-text fallback.\n     */\n    richTextEditable?: FEATURE_FLAG\n    /**\n     * Component reads its children POSITIONALLY (AGL-1237), so the renderer\n     * must hand it one React child per node child instead of the single\n     * `<Branch>` element it normally passes.\n     *\n     * MUI's Accordion does `const [summary, ...rest] = Children.toArray(children)`,\n     * and `toArray` does not traverse into an element — so with the default\n     * wrapping the summary swallowed the whole subtree and the Collapse got\n     * nothing. Every accordion on every published site expanded to reveal an\n     * empty panel while its content rendered unconditionally inside the\n     * summary's `<h3>`.\n     *\n     * Opt in only for components with this contract; the wrapper is what\n     * keeps the Branch/Stem/Leaf seam swappable for everything else.\n     */\n    positionalChildren?: FEATURE_FLAG\n  }\n\n  /**\n   * Preset items are the available items to add to the canvas\n   */\n  presets?: AglynNodePresetSchema[]\n}\n\nexport type NodePresetData = Omit<AglynNodeSchema, '$id' | 'nodes'> & {\n  $id?: NodeId\n  nodes?: NodePresetData[]\n}\n\nexport type AglynNodePresetSchema = {\n  $id: PresetId\n  label: string\n  componentId?: ComponentId\n  pluginId?: BundleId\n  description?: string\n  icon?: SvgIconProps\n  category?: string | ComponentCategory\n  data: NodePresetData\n}\n\nexport enum FieldComponentType {\n  /**\n   * Per-breakpoint span editor (AGL-2486): a small row of breakpoint\n   * controls (All / xs / sm / md / lg / xl), each offering a column count\n   * plus MUI's `auto` and `grow` keywords. The persisted prop is still ONE\n   * string in the syntax the Grid element already parses (`\"6\"`, `\"auto\"`,\n   * `\"xs:12 md:6\"`) — this is an input affordance, not a shape change, so\n   * renderers and existing documents stay untouched. A value the row cannot\n   * model (a `{{token}}`, an unknown breakpoint) falls back to free text\n   * rather than being clobbered.\n   */\n  BREAKPOINT_SPAN = 'breakpoint-span',\n  BUTTON = 'button',\n  BUTTON_GROUP = 'button-group',\n  CHECKBOX = 'checkbox',\n  COLOR_PICKER = 'color-picker',\n  /**\n   * Border editor (AGL-2486): a thickness box plus a plain-English line-style\n   * picker (solid / dashed / dotted / double / no line). The persisted prop is\n   * still ONE CSS shorthand string (`\"1px solid\"`, `\"none\"`, `\"\"`), so\n   * renderers and existing documents stay untouched. A value the pair cannot\n   * model (`thin solid`, `1px solid #f00`, a binding token) falls back to free\n   * text rather than being clobbered, and flips back the moment the text is a\n   * plain `<width> <style>` again.\n   */\n  CSS_BORDER = 'css-border',\n  /**\n   * CSS length editor (AGL-1219): a number box plus a unit picker sharing\n   * the styles panel's unit list. The persisted prop is still ONE CSS\n   * string (`\"920px\"`, `\"100%\"`, `\"auto\"`, `\"\"`) — this is an input\n   * affordance, not a shape change, so renderers stay untouched. Values\n   * the picker can't model (`calc(…)`, a binding token) fall back to free\n   * text rather than being clobbered.\n   */\n  CSS_DIMENSION = 'css-dimension',\n  /**\n   * Background fill editor (AGL-1331): a fill-type switch (default / solid\n   * / linear / radial) over an angle box and a colour-stop list, each stop\n   * bindable to a palette token or a literal. The persisted prop is ONE CSS\n   * string under `backgroundImage` — a solid fill writes the explicit\n   * keyword `none` and leaves `backgroundColor` to do the job, while the\n   * default choice writes nothing at all (AGL-1338: the two differ on a\n   * component instance, where absence means \"keep the component's fill\") —\n   * so renderers stay untouched. Values\n   * the editor cannot model (`conic-gradient`, `to bottom right`, a stacked\n   * image list) fall back to free text rather than being clobbered.\n   */\n  CSS_GRADIENT = 'css-gradient',\n  /**\n   * Row-and-column grid editor for the Table element (AGL-2543).\n   *\n   * The persisted prop is still ONE string — pipe-delimited rows with the\n   * markdown divider carrying per-column alignment — so the renderer and\n   * existing documents stay untouched, and a comparison table already\n   * authored inside a Markdown element pastes straight in. This is the\n   * affordance that makes the element no-code: without it an author edits\n   * pipe syntax, which is the audience the besigner exists to spare.\n   */\n  DATA_TABLE = 'data-table',\n  DATE_PICKER = 'date-picker',\n  DUAL_LIST_SELECT = 'dual-list-select',\n  FIELD_ARRAY = 'field-array',\n  ICON_PICKER = 'icon-picker',\n  /**\n   * markdown-lite document editor (AGL-1616): the WYSIWYG the console\n   * already ships for blog entries and marketplace listings, rendered as the\n   * attribute's field. The persisted prop is still ONE markdown-lite string,\n   * so every renderer stays untouched — this is an input affordance, not a\n   * shape change. Declared by an attribute whose value is a whole document\n   * rather than a line of text; a plain TEXTAREA meant the Privacy Policy\n   * body was edited as a 13 KB raw paste (AGL-1594).\n   */\n  MARKDOWN = 'markdown',\n  INPUT_ADDON_BUTTON_GROUP = 'input-addon-button-group',\n  INPUT_ADDON_GROUP = 'input-addon-group',\n  PLAIN_TEXT = 'plain-text',\n  /**\n   * Named-preset picker with a raw escape hatch (AGL-2486): the theme's own\n   * answers first, then plain-English presets that PREVIEW themselves, then\n   * Custom…. The persisted prop is whatever the property already stored — a\n   * number where a bare number is a theme multiple, a CSS string otherwise —\n   * and a stored value matching no preset opens the field in its custom state\n   * holding that value rather than dropping it.\n   */\n  PRESET_CHOICE = 'preset-choice',\n  RADIO = 'radio',\n  /**\n   * Select listing the host's screens; the editor resolves the options from\n   * the host routing map at render time and writes the chosen screen id.\n   */\n  SCREEN_SELECT = 'screen-select',\n  /**\n   * Select listing the canvas's other elements (AGL-557): the editor\n   * resolves options from the live canvas at edit time and persists the\n   * node id — e.g. the form's reveal-on-submit target.\n   */\n  NODE_SELECT = 'node-select',\n  /**\n   * Id-based entity pickers (AGL-343/344): the editor resolves options\n   * from EntityPickerContext at edit time and persists the entity id —\n   * renames never break the reference.\n   */\n  /**\n   * Select listing the plugins installed for this site (AGL-1030): the editor\n   * resolves options from the install set the console publishes and persists\n   * the listing id. A picker rather than a typed document id — the same reason\n   * every other reference in the designer is one, and here it also removes the\n   * \"is this installed?\" question by construction.\n   */\n  PLUGIN_SELECT = 'plugin-select',\n  /**\n   * A placed plugin's declared settings, rendered as real fields (AGL-1049).\n   * Reads the sibling plugin selection to know which manifest to offer.\n   */\n  PLUGIN_SETTINGS = 'plugin-settings',\n  PRODUCT_SELECT = 'product-select',\n  COLLECTION_SELECT = 'collection-select',\n  CATEGORY_SELECT = 'category-select',\n  DATASET_SELECT = 'dataset-select',\n  /**\n   * Select listing the model fields of the nearest ancestor node's chosen\n   * dataset (AGL-556): the editor resolves options from\n   * EntityPickerContext.datasetFields using the ancestor's `datasetId`\n   * (or legacy `datasetName` matched by label) and persists the stable\n   * model fieldId — field renames never break the mapping.\n   */\n  DATASET_FIELD_SELECT = 'dataset-field-select',\n  /**\n   * Select listing the host's form entities (`docs/specs/reusable-forms.md`\n   * §2c): the editor resolves options from EntityPickerContext.forms and\n   * persists the form id. The same id-first reasoning as every picker in this\n   * family, and here it is load-bearing rather than convenient — the string\n   * it replaces was the form's whole identity, so a rename split the\n   * submission history it named.\n   */\n  FORM_SELECT = 'form-select',\n  SELECT = 'select',\n  SLIDER = 'slider',\n  SUB_FORM = 'sub-form',\n  SWITCH = 'switch',\n  TAB_ITEM = 'tab-item',\n  TABS = 'tabs',\n  TEXT_FIELD = 'text-field',\n  TEXTAREA = 'textarea',\n  /**\n   * Theme-scale combo box (AGL-2486): offers the THEME's own scale for a\n   * property — `theme.typography` for font size and weight,\n   * `theme.zIndex` for stacking — while still accepting any raw value\n   * (`18px`, `1.25rem`, `700`, `1400`), because arbitrary values are\n   * legitimate. The persisted value is a theme token PATH\n   * (`h4.fontSize`, `fontWeightBold`, `appBar`), which MUI's sx system\n   * resolves against the active theme exactly as it resolves\n   * `color: 'primary.main'` — so the element keeps following the theme\n   * instead of freezing the number it had when it was styled.\n   */\n  THEME_SCALE = 'theme-scale',\n  TIME_PICKER = 'time-picker',\n  TOGGLE_BUTTON = 'toggle-button',\n  WIZARD = 'wizard',\n}\n\nexport enum FieldValidatorType {\n  EXACT_LENGTH = 'exact-length',\n  MAX_LENGTH = 'max-length',\n  MAX_NUMBER_VALUE = 'max-number-value',\n  MIN_ITEMS = 'min-items',\n  MIN_LENGTH = 'min-length',\n  MIN_NUMBER_VALUE = 'min-number-value',\n  PATTERN = 'pattern',\n  REQUIRED = 'required',\n  URL = 'url',\n}\n\nexport type FieldDataType =\n  | 'boolean'\n  | 'float'\n  | 'integer'\n  | 'number'\n  | 'string'\n\nexport interface AglynAttributeSchema extends Dictionary<any> {\n  name: string\n  dataType?: DataType\n  component: string | FieldComponentType\n  validate?: Validator[]\n  condition?: ConditionDefinition | ConditionDefinition[]\n  initializeOnMount?: boolean\n  initialValue?: unknown\n  clearedValue?: unknown\n  clearOnUnmount?: boolean\n  actions?: FieldActions\n  resolveProps?: ResolvePropsFunction\n  description?: string\n}\n\nexport interface AglynNodeSchema<P = JSX.AnyProps> {\n  $id: NodeId\n  componentId: ComponentId\n  pluginId?: BundleId\n  parentId?: NodeId\n  sx?: JSX.SxProps\n  props?: P\n  nodes?: NodeId[] | AglynNodeSchema[]\n}\n"],"names":["LinealDirectiveFlag","FieldComponentType","FieldValidatorType"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAkBD,OAAO,IAAA,AAAKA,6CAAAA;;;WAAAA;MAGX;AAwKD,OAAO,IAAA,AAAKC,4CAAAA;IACV;;;;;;;;;GASC;;;;;IAMD;;;;;;;;GAQC;IAED;;;;;;;GAOC;IAED;;;;;;;;;;;GAWC;IAED;;;;;;;;;GASC;;;;;IAMD;;;;;;;;GAQC;;;;IAKD;;;;;;;GAOC;;IAGD;;;GAGC;IAED;;;;GAIC;IAED;;;;GAIC,GACD;;;;;;GAMC;IAED;;;GAGC;;;;;IAMD;;;;;;GAMC;IAED;;;;;;;GAOC;;;;;;;;;IAUD;;;;;;;;;;GAUC;;;;WA1JSA;MA+JX;AAED,OAAO,IAAA,AAAKC,4CAAAA;;;;;;;;;;WAAAA;MAUX"}

package/src/lib/foundation/definitions/contact.types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @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.
+ */
+/**
+ * ONE postal address shape (AGL-1133).
+ *
+ * The failure this prevents is not "there is no address field" — it is a phone
+ * number stored three ways in three collections. So every place that grows an
+ * address stores this, and the Stripe mapping is a field rename in one file
+ * rather than in each caller.
+ *
+ * NOTE ON `state`: the issue specified `region`. Using it would have created a
+ * THIRD spelling — Stripe's customer address uses `state`, and the commerce
+ * plugin's `OrderAddress` already uses `state` too. A canonical type whose
+ * whole purpose is to stop variants should not open with a new variant, so
+ * this matches the two shapes it has to interoperate with.
+ */
+export interface AglynPostalAddress {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    /** State, province, prefecture or county. Stripe calls this `state`. */
+    state?: string;
+    postalCode?: string;
+    /**
+     * ISO-3166-1 alpha-2, uppercase (`US`, `GB`, `DE`).
+     *
+     * Two letters because that is what Stripe Tax and every address validator
+     * expect; a free-text country name cannot be used to compute tax.
+     */
+    country?: string;
+}
+/** Every field of a postal address, absent or blank. */
+export declare function isBlankAddress(address: AglynPostalAddress | null | undefined): boolean;
+/**
+ * Trim, drop empties, and uppercase the country code.
+ *
+ * Returns `null` for an address with nothing in it, so a cleared form stores
+ * an absent field rather than an object full of empty strings — which would
+ * read as "has an address" to every `if (address)` in the codebase.
+ */
+export declare function normalizeAddress(address: AglynPostalAddress | null | undefined): AglynPostalAddress | null;
+/**
+ * Best-effort E.164 (`+15125550123`).
+ *
+ * Measured on production 2026-07-30: the one populated profile stored a bare
+ * ten-digit US number with no country code — `5550107788` in the examples
+ * below, standing in for the value actually measured. That is unusable for SMS
+ * or for a Stripe customer, and it is what "phone already exists but is stored
+ * unnormalized" in AGL-1133 refers to.
+ *
+ * `defaultCountry` only applies to a number with NO country code of its own,
+ * and only US/CA (+1) are inferred — guessing a country for a bare national
+ * number anywhere else silently invents a different subscriber.
+ *
+ * @returns E.164, or `null` when the input cannot be normalized confidently.
+ *          Never a partially-cleaned string: a half-normalized phone is the
+ *          same bug in a new format.
+ */
+export declare function normalizePhone(input: string | null | undefined, defaultCountry?: string): string | null;