@zeyos/zx 4.3.4 → 5.0.0

package/dist/types/components/dialog/dialog.d.ts

@@ -17,6 +17,14 @@ export type DialogButton = {
      * Whether this button receives initial focus.
      */
     autofocus?: boolean;
+    /**
+     * Whether the footer button is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Visible shortcut hint; the host binds the action.
+     */
+    shortcut?: import('../button/button.js').ButtonShortcut;
 };
 export type DialogOptions = {
     /**
@@ -42,7 +50,7 @@ export type DialogOptions = {
         toElement: () => Node | null;
     } | null;
     /**
-     * Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+     * Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
      */
     scope?: Element | string | null;
     /**
@@ -129,6 +137,14 @@ export type ConfirmOptions = {
      * Whether the confirmation action is dangerous.
      */
     danger?: boolean;
+    /**
+     * Text the reader must type before the confirm button
+     * enables — the name of what is about to be deleted, say. The dialog adds an input labelled
+     * "Type <confirmText> to confirm" (message `dialog.typeToConfirm`, `%1` standing for the text),
+     * focuses it, and enables the confirm button, and Enter, only while its value matches exactly,
+     * ignoring surrounding spaces.
+     */
+    confirmText?: string | null;
 };
 export type PromptOptions = {
     /**
@@ -147,6 +163,14 @@ export type PromptOptions = {
      * Input placeholder.
      */
     placeholder?: string;
+    /**
+     * Confirmation label.
+     */
+    okLabel?: string;
+    /**
+     * Cancellation label.
+     */
+    cancelLabel?: string;
 };
 /** @typedef {'default'|'primary'|'danger'|'ghost'} DialogButtonKind */
 /**
@@ -155,6 +179,8 @@ export type PromptOptions = {
  * @property {DialogButtonKind} [kind='default'] Visual button kind.
  * @property {'close'|'cancel'|((dialog: Dialog) => void)} [action='close'] Button action.
  * @property {boolean} [autofocus=false] Whether this button receives initial focus.
+ * @property {boolean} [disabled=false] Whether the footer button is disabled.
+ * @property {import('../button/button.js').ButtonShortcut} [shortcut] Visible shortcut hint; the host binds the action.
  */
 /**
  * @typedef {Object} DialogOptions
@@ -163,7 +189,7 @@ export type PromptOptions = {
  * @property {DialogButton[]} [buttons=[]] Footer buttons.
  * @property {boolean} [closable=true] Whether Escape and the header button may close the dialog.
  * @property {Node|string|number|{toElement: () => Node|null}|null} [content=null] Body content.
- * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the overlay; defaults to the opener. Resolved on every open, so a scope connected after construction still owns it.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<{result: unknown}>) => void} [onclose] Close event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [oncancel] Cancel event listener.
@@ -194,6 +220,11 @@ export type PromptOptions = {
  * @property {string} [okLabel='OK'] Confirmation label.
  * @property {string} [cancelLabel='Cancel'] Cancellation label.
  * @property {boolean} [danger=false] Whether the confirmation action is dangerous.
+ * @property {string|null} [confirmText=null] Text the reader must type before the confirm button
+ *   enables — the name of what is about to be deleted, say. The dialog adds an input labelled
+ *   "Type <confirmText> to confirm" (message `dialog.typeToConfirm`, `%1` standing for the text),
+ *   focuses it, and enables the confirm button, and Enter, only while its value matches exactly,
+ *   ignoring surrounding spaces.
  */
 /**
  * @typedef {Object} PromptOptions
@@ -201,6 +232,8 @@ export type PromptOptions = {
  * @property {Node|string|number|null} [message=''] Prompt message.
  * @property {string} [value=''] Initial input value.
  * @property {string} [placeholder=''] Input placeholder.
+ * @property {string} [okLabel='OK'] Confirmation label.
+ * @property {string} [cancelLabel='Cancel'] Cancellation label.
  */
 /**
  * Structured modal with a title, body, footer actions, and switchable views.
@@ -275,17 +308,18 @@ export declare class Dialog extends Modal {
      */
     static alert({ title, message, okLabel }?: AlertOptions): Promise<void>;
     /**
-     * Opens a confirmation dialog.
+     * Opens a confirmation dialog. With `confirmText` it becomes a type-to-confirm dialog: the
+     * confirm button stays disabled until the reader has typed that text.
      * @param {ConfirmOptions} [options={}] Confirmation options.
-     * @returns {Promise<boolean>}
+     * @returns {Promise<boolean>} True when confirmed; false on Cancel, Escape, or the close button.
      */
-    static confirm({ title, message, okLabel, cancelLabel, danger }?: ConfirmOptions): Promise<boolean>;
+    static confirm({ title, message, okLabel, cancelLabel, danger, confirmText }?: ConfirmOptions): Promise<boolean>;
     /**
      * Opens a single-line text prompt.
      * @param {PromptOptions} [options={}] Prompt options.
      * @returns {Promise<string|null>}
      */
-    static prompt({ title, message, value, placeholder }?: PromptOptions): Promise<string | null>;
+    static prompt({ title, message, value, placeholder, okLabel, cancelLabel }?: PromptOptions): Promise<string | null>;
     /**
      * Applies the dialog width. Subclasses that size themselves on a different axis override this.
      *
@@ -295,4 +329,39 @@ export declare class Dialog extends Modal {
      * @returns {void}
      */
     _applySize(size: 'sm' | 'md' | 'lg' | number): void;
+    /**
+     * Resolves a component message, falling back to the built-in English text.
+     * @param {string} key Message key.
+     * @param {string} fallback English default.
+     * @returns {string}
+     */
+    _message(key: string, fallback: string): string;
 }
+/**
+ * Reports whether what the reader typed confirms a type-to-confirm dialog: the same text, exactly
+ * — case and inner spacing included — once surrounding spaces are ignored on both sides.
+ * @param {unknown} typed Input value.
+ * @param {unknown} expected Text the dialog asks for.
+ * @returns {boolean}
+ */
+export declare function typedConfirmation(typed: unknown, expected: unknown): boolean;
+/**
+ * Splits the type-to-confirm message around `%1`, where the text to type goes. A translation that
+ * leaves `%1` out gets the text after it, following a space; a second `%1` is filled in as text.
+ * @param {string} template Message such as "Type %1 to confirm".
+ * @param {string} expected Text to type.
+ * @returns {[string, string]} The text before and after the text to type.
+ */
+export declare function typeToConfirmParts(template: string, expected: string): [string, string];
+/**
+ * Copies footer-button descriptors without mutating the caller's array or objects, and settles
+ * the two booleans the footer renders from.
+ *
+ * `autofocus` and `disabled` are resolved together because they contradict each other: a control
+ * that refuses activation must not be the one initial focus lands on, and a host that writes both
+ * has said what it wants twice. Deciding it here rather than at render time keeps `Sheet` — which
+ * takes the same descriptors through the same footer — on one answer.
+ * @param {DialogButton[]|null|undefined} list Button descriptors.
+ * @returns {DialogButton[]} Normalized copies.
+ */
+export declare function normalizeDialogButtons(list: DialogButton[] | null | undefined): DialogButton[];

package/dist/types/components/dropdown/dropdown.d.ts

@@ -29,7 +29,7 @@ export type DropdownOptions = {
      */
     closeOnSelect?: boolean;
     /**
-     * Element whose nearest Zx theme scope owns the panel; defaults to the anchor.
+     * Element whose nearest Zx theme scope owns the panel; defaults to the anchor. Resolved on every open, so an anchor connected after construction still gets its scope.
      */
     scope?: Element | string | null;
     /**
@@ -49,7 +49,7 @@ export type DropdownOptions = {
  * @property {boolean} [matchWidth=false] Whether the panel matches the anchor width.
  * @property {'click'|'manual'} [openOn='click'] Trigger behavior.
  * @property {boolean} [closeOnSelect=false] Whether a click within the panel closes it.
- * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the panel; defaults to the anchor.
+ * @property {Element|string|null} [scope=null] Element whose nearest Zx theme scope owns the panel; defaults to the anchor. Resolved on every open, so an anchor connected after construction still gets its scope.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onopen] Open event listener.
  * @property {(event: CustomEvent<Record<string, never>>) => void} [onclose] Close event listener.
  */

package/dist/types/components/entity-ref/entity-ref.d.ts

@@ -0,0 +1,331 @@
+import { Component } from '../../core/component.js';
+export type EntityRefContent = string | number | Node | Component | null;
+export type EntityRefIcon = string | Node | Component | (() => string | Node | Component | null) | null;
+export type EntityRefLink = {
+    /**
+     * Native primary-link destination.
+     */
+    href: string;
+    /**
+     * Native browsing context.
+     */
+    target?: string;
+    /**
+     * Native link relationship.
+     */
+    rel?: string;
+    /**
+     * Native download hint; a string supplies the filename.
+     */
+    download?: boolean | string;
+    /**
+     * Optional callback after an uncanceled activation; navigation remains native.
+     */
+    onclick?: (event: MouseEvent, entity: Readonly<EntityRefState>, component: EntityRef) => void;
+};
+export type EntityRefMetadata = {
+    /**
+     * Metadata label.
+     */
+    label: string;
+    /**
+     * Metadata value.
+     */
+    value: EntityRefContent;
+    /**
+     * Optional Zx icon before the value.
+     */
+    icon?: string | null;
+    /**
+     * Whether the label is visible instead of visually hidden.
+     */
+    showLabel?: boolean;
+};
+export type EntityRefAction = {
+    /**
+     * Stable action identifier.
+     */
+    id: string;
+    /**
+     * Visible label.
+     */
+    label?: string;
+    /**
+     * Optional Zx icon.
+     */
+    icon?: string | null;
+    /**
+     * Accessible/native title, required when the label is empty.
+     */
+    title?: string;
+    /**
+     * Optional safe native link destination; otherwise a button is rendered.
+     */
+    href?: string;
+    /**
+     * Native link browsing context.
+     */
+    target?: string;
+    /**
+     * Native link relationship.
+     */
+    rel?: string;
+    /**
+     * Visual intent.
+     */
+    kind?: 'default' | 'primary' | 'danger' | 'ghost';
+    /**
+     * Whether activation is unavailable.
+     */
+    disabled?: boolean;
+    /**
+     * Callback after an uncanceled activation.
+     */
+    onselect?: (id: string, action: Readonly<EntityRefAction>, entity: Readonly<EntityRefState>, component: EntityRef) => void;
+};
+export type EntityRefActionEntry = Element | EntityRefAction;
+export type EntityRefLinkValue = string | EntityRefLink | null;
+export type EntityRefOptions = {
+    /**
+     * Application-owned entity identifier included in events.
+     */
+    id?: unknown;
+    /**
+     * Primary identity text.
+     */
+    title?: string;
+    /**
+     * Secondary identity text or safe caller-supplied content.
+     */
+    subtitle?: EntityRefContent;
+    /**
+     * Icon name, node, component, or lazy renderer.
+     */
+    icon?: EntityRefIcon;
+    /**
+     * Labelled dense metadata.
+     */
+    metadata?: EntityRefMetadata[];
+    /**
+     * Optional native primary link.
+     */
+    link?: EntityRefLinkValue;
+    /**
+     * Secondary controls; element actions keep their own behavior.
+     */
+    actions?: EntityRefActionEntry[];
+    /**
+     * Size of the icon and the identity text.
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * Whether long identity text may wrap instead of truncating.
+     */
+    wrap?: boolean;
+    /**
+     * Accessible name for secondary actions.
+     */
+    actionsLabel?: string;
+    /**
+     * Preventable primary-link listener.
+     */
+    onactivate?: (event: CustomEvent<{
+        id: unknown;
+        entity: Readonly<EntityRefState>;
+        href: string;
+        event: MouseEvent;
+    }>) => void;
+    /**
+     * Preventable delegated-action listener.
+     */
+    onaction?: (event: CustomEvent<{
+        id: string;
+        action: Readonly<EntityRefAction>;
+        entity: Readonly<EntityRefState>;
+        event: MouseEvent;
+    }>) => void;
+};
+export type EntityRefState = {
+    /**
+     * Entity identifier.
+     */
+    id: unknown;
+    /**
+     * Primary identity.
+     */
+    title: string;
+    /**
+     * Secondary identity.
+     */
+    subtitle: EntityRefContent;
+    /**
+     * Identity icon.
+     */
+    icon: EntityRefIcon;
+    /**
+     * Normalized metadata copies.
+     */
+    metadata: EntityRefMetadata[];
+    /**
+     * Safe native link.
+     */
+    link: EntityRefLink | null;
+    /**
+     * Normalized action copies or elements.
+     */
+    actions: EntityRefActionEntry[];
+    /**
+     * Presentation size.
+     */
+    size: 'sm' | 'md' | 'lg';
+    /**
+     * Wrapping state.
+     */
+    wrap: boolean;
+    /**
+     * Action-group label.
+     */
+    actionsLabel: string;
+};
+/** @typedef {string|number|Node|Component|null} EntityRefContent */
+/** @typedef {string|Node|Component|(()=>string|Node|Component|null)|null} EntityRefIcon */
+/**
+ * @typedef {Object} EntityRefLink
+ * @property {string} href Native primary-link destination.
+ * @property {string} [target] Native browsing context.
+ * @property {string} [rel] Native link relationship.
+ * @property {boolean|string} [download] Native download hint; a string supplies the filename.
+ * @property {(event: MouseEvent, entity: Readonly<EntityRefState>, component: EntityRef) => void} [onclick]
+ *   Optional callback after an uncanceled activation; navigation remains native.
+ */
+/**
+ * @typedef {Object} EntityRefMetadata
+ * @property {string} label Metadata label.
+ * @property {EntityRefContent} value Metadata value.
+ * @property {string|null} [icon=null] Optional Zx icon before the value.
+ * @property {boolean} [showLabel=true] Whether the label is visible instead of visually hidden.
+ */
+/**
+ * @typedef {Object} EntityRefAction
+ * @property {string} id Stable action identifier.
+ * @property {string} [label=''] Visible label.
+ * @property {string|null} [icon=null] Optional Zx icon.
+ * @property {string} [title] Accessible/native title, required when the label is empty.
+ * @property {string} [href] Optional safe native link destination; otherwise a button is rendered.
+ * @property {string} [target] Native link browsing context.
+ * @property {string} [rel] Native link relationship.
+ * @property {'default'|'primary'|'danger'|'ghost'} [kind='ghost'] Visual intent.
+ * @property {boolean} [disabled=false] Whether activation is unavailable.
+ * @property {(id: string, action: Readonly<EntityRefAction>, entity: Readonly<EntityRefState>, component: EntityRef) => void} [onselect]
+ *   Callback after an uncanceled activation.
+ */
+/** @typedef {Element|EntityRefAction} EntityRefActionEntry */
+/** @typedef {string|EntityRefLink|null} EntityRefLinkValue */
+/**
+ * @typedef {Object} EntityRefOptions
+ * @property {unknown} [id=null] Application-owned entity identifier included in events.
+ * @property {string} [title=''] Primary identity text.
+ * @property {EntityRefContent} [subtitle=null] Secondary identity text or safe caller-supplied content.
+ * @property {EntityRefIcon} [icon=null] Icon name, node, component, or lazy renderer.
+ * @property {EntityRefMetadata[]} [metadata=[]] Labelled dense metadata.
+ * @property {EntityRefLinkValue} [link=null] Optional native primary link.
+ * @property {EntityRefActionEntry[]} [actions=[]] Secondary controls; element actions keep their own behavior.
+ * @property {'sm'|'md'|'lg'} [size='md'] Size of the icon and the identity text.
+ * @property {boolean} [wrap=false] Whether long identity text may wrap instead of truncating.
+ * @property {string} [actionsLabel='Entity actions'] Accessible name for secondary actions.
+ * @property {(event: CustomEvent<{id: unknown, entity: Readonly<EntityRefState>, href: string, event: MouseEvent}>) => void} [onactivate]
+ *   Preventable primary-link listener.
+ * @property {(event: CustomEvent<{id: string, action: Readonly<EntityRefAction>, entity: Readonly<EntityRefState>, event: MouseEvent}>) => void} [onaction]
+ *   Preventable delegated-action listener.
+ */
+/**
+ * @typedef {Object} EntityRefState
+ * @property {unknown} id Entity identifier.
+ * @property {string} title Primary identity.
+ * @property {EntityRefContent} subtitle Secondary identity.
+ * @property {EntityRefIcon} icon Identity icon.
+ * @property {EntityRefMetadata[]} metadata Normalized metadata copies.
+ * @property {EntityRefLink|null} link Safe native link.
+ * @property {EntityRefActionEntry[]} actions Normalized action copies or elements.
+ * @property {'sm'|'md'|'lg'} size Presentation size.
+ * @property {boolean} wrap Wrapping state.
+ * @property {string} actionsLabel Action-group label.
+ */
+/**
+ * Dense entity identity for tables, feeds, selectors, and detail metadata. It owns presentation and
+ * safe native-link/action semantics; routing, permissions, context menus, and persistence remain
+ * application-owned.
+ * @fires EntityRef#activate
+ * @fires EntityRef#action
+ * @extends {Component<EntityRefOptions>}
+ */
+export declare class EntityRef extends Component<EntityRefOptions> {
+    _createdRoot: boolean;
+    _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _destroyed: boolean;
+    _state: EntityRefState;
+    _renderedActions: any[] | EntityRefActionEntry[];
+    static cssName: string;
+    /** @type {Readonly<EntityRefOptions>} */
+    static defaults: Readonly<EntityRefOptions>;
+    /**
+     * Creates or enhances a dense entity reference.
+     * @param {Element|string|null} [target=null] Existing host, selector, or null.
+     * @param {EntityRefOptions} [options={}] Entity presentation.
+     */
+    constructor(target?: Element | string | null, options?: EntityRefOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /**
+     * Updates any subset of the identity without replacing the root.
+     * @param {Partial<EntityRefOptions>} values Next values.
+     * @returns {this}
+     */
+    set(values?: Partial<EntityRefOptions>): this;
+    /** Replaces the metadata collection. @param {EntityRefMetadata[]} metadata Metadata. @returns {this} */
+    setMetadata(metadata: EntityRefMetadata[]): this;
+    /** Replaces the secondary action controls. @param {EntityRefActionEntry[]} actions Actions. @returns {this} */
+    setActions(actions: EntityRefActionEntry[]): this;
+    /** Sets or clears the primary link. @param {EntityRefLinkValue} link Link. @returns {this} */
+    setLink(link: EntityRefLinkValue): this;
+    /**
+     * Returns a defensive presentation snapshot. Caller-supplied Nodes and Components retain their
+     * identity; arrays and descriptors are copied.
+     * @returns {Readonly<EntityRefState>}
+     */
+    getEntity(): Readonly<EntityRefState>;
+    /** Focuses the primary link or the first enabled action. @returns {this} */
+    focus(): this;
+    /** Restores an enhanced target exactly, or removes an owned reference. @returns {void} */
+    destroy(): void;
+    /** @returns {void} */
+    _sync(): void;
+    /** @param {MouseEvent} event @returns {void} */
+    _handleClick(event: MouseEvent): void;
+}
+/**
+ * Normalizes an entity-reference contract without touching the DOM.
+ * @param {Partial<EntityRefOptions>|null|undefined} values Candidate values.
+ * @returns {EntityRefState}
+ */
+export declare function normalizeEntityRef(values?: Partial<EntityRefOptions> | null | undefined): EntityRefState;
+/**
+ * Normalizes and secures a primary native link.
+ * @param {EntityRefLinkValue|unknown} value Candidate link.
+ * @returns {EntityRefLink|null}
+ */
+export declare function normalizeEntityRefLink(value: EntityRefLinkValue | unknown): EntityRefLink | null;
+/**
+ * Normalizes labelled metadata, omitting entries without a label or displayable value.
+ * @param {unknown} values Candidate metadata.
+ * @returns {EntityRefMetadata[]}
+ */
+export declare function normalizeEntityRefMetadata(values: unknown): EntityRefMetadata[];
+/**
+ * Normalizes delegated actions while preserving caller-supplied Elements.
+ * @param {unknown} values Candidate actions.
+ * @returns {EntityRefActionEntry[]}
+ */
+export declare function normalizeEntityRefActions(values: unknown): EntityRefActionEntry[];
+/** Fired when the native primary link is activated. @event EntityRef#activate @type {CustomEvent<{id: unknown, entity: Readonly<EntityRefState>, href: string, event: MouseEvent}>} */
+/** Fired when a delegated secondary action is activated. @event EntityRef#action @type {CustomEvent<{id: string, action: Readonly<EntityRefAction>, entity: Readonly<EntityRefState>, event: MouseEvent}>} */

package/dist/types/components/field/field.d.ts

@@ -1,9 +1,15 @@
 import { Component } from '../../core/component.js';
 export type FieldOptions = {
     /**
-     * Control ID and logical field identifier.
+     * DOM id of the control. Generated when omitted; a Fieldset
+     * derives it from its `idPrefix` and the field key, so a key never becomes a DOM id by itself.
      */
     id?: string | null;
+    /**
+     * Field name: the `name` of a native control and the key the
+     * field is filed under. A Fieldset sets it to the field key; a standalone field falls back to `id`.
+     */
+    name?: string | null;
     /**
      * Registered field type.
      */
@@ -88,6 +94,12 @@ export type FieldAdapter = {
      * Release adapter-owned resources.
      */
     destroy?: () => void;
+    /**
+     * The element the field's label, description, and validity
+     * belong to when it is not `el` — the text input inside a composite control. Left out, a
+     * wrapper that cannot be labelled hands them to the first unnamed form control inside it.
+     */
+    labelTarget?: Element;
 };
 export type FieldAdapterFactory = (field: Field, options: Readonly<FieldOptions>) => FieldAdapter;
 export type NumericCoercion = {
@@ -96,7 +108,10 @@ export type NumericCoercion = {
 };
 /**
  * @typedef {Object} FieldOptions
- * @property {string|null} [id=null] Control ID and logical field identifier.
+ * @property {string|null} [id=null] DOM id of the control. Generated when omitted; a Fieldset
+ *   derives it from its `idPrefix` and the field key, so a key never becomes a DOM id by itself.
+ * @property {string|null} [name=null] Field name: the `name` of a native control and the key the
+ *   field is filed under. A Fieldset sets it to the field key; a standalone field falls back to `id`.
  * @property {string} [type='text'] Registered field type.
  * @property {string} [label=''] Visible label.
  * @property {string} [description=''] Supporting description.
@@ -119,6 +134,9 @@ export type NumericCoercion = {
  * @property {() => void} focus Focus the control.
  * @property {(disabled: boolean) => void} setDisabled Set disabled state.
  * @property {() => void} [destroy] Release adapter-owned resources.
+ * @property {Element} [labelTarget] The element the field's label, description, and validity
+ *   belong to when it is not `el` — the text input inside a composite control. Left out, a
+ *   wrapper that cannot be labelled hands them to the first unnamed form control inside it.
  */
 /** @typedef {(field: Field, options: Readonly<FieldOptions>) => FieldAdapter} FieldAdapterFactory */
 /** @typedef {{valid: boolean, value: number|string}} NumericCoercion */
@@ -133,8 +151,12 @@ export declare class Field extends Component<FieldOptions> {
     _ownedComponents: Set<any>;
     _ownedNodes: any[];
     _rootAttributes: Map<string, string>;
+    /** @type {string} The control's DOM id: `options.id`, or a generated one. */
     controlId: string;
+    /** @type {string} The field name (`options.name`, else `options.id`), '' when there is none. */
+    name: string;
     adapter: FieldAdapter;
+    _labelled: Element;
     _baseDescribedBy: string;
     _descriptionId: string;
     _highlightId: string;

package/dist/types/components/fieldset/fieldset.d.ts

@@ -13,6 +13,12 @@ export type FieldsetOptions = {
      * Initial fields.
      */
     fields?: Record<string, FieldOptions | Field | Element | Component>;
+    /**
+     * Prefix of the DOM ids generated for the fields, as
+     * `<idPrefix>-<key>`. Null generates one per instance, so the same fieldset mounted twice
+     * never repeats an id and a field key never collides with an element id elsewhere on the page.
+     */
+    idPrefix?: string | null;
 };
 export type FieldOptions = import('../field/field.js').FieldOptions;
 /**
@@ -20,6 +26,9 @@ export type FieldOptions = import('../field/field.js').FieldOptions;
  * @property {string} [title=''] Legend text.
  * @property {1|2|3} [columns=1] Grid column count.
  * @property {Record<string, FieldOptions|Field|Element|Component>} [fields={}] Initial fields.
+ * @property {string|null} [idPrefix=null] Prefix of the DOM ids generated for the fields, as
+ *   `<idPrefix>-<key>`. Null generates one per instance, so the same fieldset mounted twice
+ *   never repeats an id and a field key never collides with an element id elsewhere on the page.
  */
 /** @typedef {import('../field/field.js').FieldOptions} FieldOptions */
 /**
@@ -32,6 +41,7 @@ export declare class Fieldset extends Component<FieldsetOptions> {
     _origins: Map<any, any>;
     _fieldIdAttributes: Map<any, any>;
     _ownedNodes: any[];
+    _idPrefix: string;
     _columnAttribute: string;
     _grid: HTMLElement;
     static cssName: string;
@@ -40,7 +50,9 @@ export declare class Fieldset extends Component<FieldsetOptions> {
     /** @returns {HTMLElement} */
     render(): HTMLElement;
     /**
-     * Adds a field from options, an existing field, an element, or a component.
+     * Adds a field from options, an existing field, an element, or a component. The key becomes the
+     * field's `name` and its `data-field-id`; the control's DOM id is `<idPrefix>-<key>`, unless the
+     * field options give an `id` of their own that differs from the key.
      * @param {string} id Logical field identifier.
      * @param {FieldOptions|Field|Element|Component} field Field source.
      * @returns {Field}
@@ -118,6 +130,12 @@ export declare class Fieldset extends Component<FieldsetOptions> {
      * @returns {this}
      */
     clearHighlights(): this;
+    /**
+     * The DOM id generated for a field key: unique per instance unless `idPrefix` was given.
+     * @param {string} key Field key.
+     * @returns {string}
+     */
+    _controlId(key: string): string;
     /** @param {Field} field @returns {void} */
     _releaseField(field: Field): void;
     /** @returns {void} */