@emuanalytics/flow-rdf-ui 4.1.27 → 4.1.28

package/dist/index.d.mts

@@ -1985,6 +1985,19 @@ declare class FlowUiAutocomplete extends FlowRdfFormControl {
     private pendingChangeEvent;
     private pendingInputEvent;
     private hasOptions;
+    /** @internal True while the user is typing to filter (input text has diverged from the committed value). */
+    private inputChanged;
+    /** @internal Stable base used to generate option DOM ids when the host has no `id` of its own. */
+    private optionIdBase;
+    /** @internal Monotonic per-host suffix for option DOM ids, so ids never collide across re-renders. */
+    private nextOptionId;
+    /**
+     * @internal True while hide()'s close animation is in flight. `open` stays true across that
+     * animation (so the popup remains visible while it fades out), which would otherwise make a
+     * concurrent show() no-op at its `!this.open` guard. show() flips this to false to cancel the
+     * close and reopen; hide() bails after its animation if it finds the close was cancelled.
+     */
+    private closing;
     private readonly formControlController;
     /** The autocomplete's size */
     size: 'small' | 'medium' | 'large';
@@ -2044,7 +2057,9 @@ declare class FlowUiAutocomplete extends FlowRdfFormControl {
     hasFocus: boolean;
     private input;
     private popup;
+    private listbox;
     connectedCallback(): void;
+    disconnectedCallback(): void;
     /** Gets the associated form, if one exists. */
     getForm(): HTMLFormElement | null;
     /** Gets the validity state object.*/
@@ -2063,10 +2078,31 @@ declare class FlowUiAutocomplete extends FlowRdfFormControl {
     private getFirstOption;
     /**
      * @internal
-     * Un-highlights currently highlighted option
-     * and highlights the given option
+     * Gives each slotted option a stable DOM `id` (`<host-id>-option-<n>`) used purely for
+     * ARIA wiring (`aria-activedescendant`). A consumer-provided `id` is preserved. This `id` is
+     * independent of the option's `value` (domain identity). See ADR-0001.
+     *
+     * The suffix comes from a monotonic per-host counter rather than the option's index: a filter
+     * re-render can retain some option elements while creating others, so an index-based suffix
+     * could hand a new element an id that a retained element already owns.
+     */
+    private assignOptionIds;
+    /**
+     * @internal
+     * Un-highlights currently highlighted option and highlights the given option.
+     *
+     * DOM focus stays on the `<input>` (per the APG editable-combobox pattern); the highlighted
+     * ("current") option is conveyed to assistive tech via the input's `aria-activedescendant`,
+     * not by moving focus. See ADR-0001.
      */
     private setCurrentOption;
+    /**
+     * @internal
+     * Sets the input's `aria-activedescendant` to the given option `id`, or clears it (to `''`,
+     * per the APG reference) when passed `null` or an empty id. Centralises the ARIA wiring so the
+     * highlight and close paths stay in sync. See ADR-0001.
+     */
+    private setActiveDescendant;
     /**
      * @internal
      * Unselects currently selected option
@@ -2108,6 +2144,17 @@ declare class FlowUiAutocomplete extends FlowRdfFormControl {
     private removeListenersForDropdown;
     /** @internal Handles changes in the default slot */
     private handleDefaultSlotChange;
+    /**
+     * @internal
+     * Establishes the highlighted ("current") option per the APG rules (ADR-0001):
+     * - while filtering (input text has changed): always the first option, so type-then-Enter
+     *   selects the narrowed-down top option.
+     * - on open with unchanged input: the selected option if one matches, else the first.
+     *
+     * Called both on slot change (list re-rendered) and on open (listbox shown without a
+     * re-render, e.g. clicking back into the input), since the latter fires no slot change.
+     */
+    private highlightCurrentOption;
     /** @internal Toggles listbox based on focus and options in the default slot. */
     toggleListbox(): void;
     /**

package/dist/index.d.ts

@@ -1985,6 +1985,19 @@ declare class FlowUiAutocomplete extends FlowRdfFormControl {
     private pendingChangeEvent;
     private pendingInputEvent;
     private hasOptions;
+    /** @internal True while the user is typing to filter (input text has diverged from the committed value). */
+    private inputChanged;
+    /** @internal Stable base used to generate option DOM ids when the host has no `id` of its own. */
+    private optionIdBase;
+    /** @internal Monotonic per-host suffix for option DOM ids, so ids never collide across re-renders. */
+    private nextOptionId;
+    /**
+     * @internal True while hide()'s close animation is in flight. `open` stays true across that
+     * animation (so the popup remains visible while it fades out), which would otherwise make a
+     * concurrent show() no-op at its `!this.open` guard. show() flips this to false to cancel the
+     * close and reopen; hide() bails after its animation if it finds the close was cancelled.
+     */
+    private closing;
     private readonly formControlController;
     /** The autocomplete's size */
     size: 'small' | 'medium' | 'large';
@@ -2044,7 +2057,9 @@ declare class FlowUiAutocomplete extends FlowRdfFormControl {
     hasFocus: boolean;
     private input;
     private popup;
+    private listbox;
     connectedCallback(): void;
+    disconnectedCallback(): void;
     /** Gets the associated form, if one exists. */
     getForm(): HTMLFormElement | null;
     /** Gets the validity state object.*/
@@ -2063,10 +2078,31 @@ declare class FlowUiAutocomplete extends FlowRdfFormControl {
     private getFirstOption;
     /**
      * @internal
-     * Un-highlights currently highlighted option
-     * and highlights the given option
+     * Gives each slotted option a stable DOM `id` (`<host-id>-option-<n>`) used purely for
+     * ARIA wiring (`aria-activedescendant`). A consumer-provided `id` is preserved. This `id` is
+     * independent of the option's `value` (domain identity). See ADR-0001.
+     *
+     * The suffix comes from a monotonic per-host counter rather than the option's index: a filter
+     * re-render can retain some option elements while creating others, so an index-based suffix
+     * could hand a new element an id that a retained element already owns.
+     */
+    private assignOptionIds;
+    /**
+     * @internal
+     * Un-highlights currently highlighted option and highlights the given option.
+     *
+     * DOM focus stays on the `<input>` (per the APG editable-combobox pattern); the highlighted
+     * ("current") option is conveyed to assistive tech via the input's `aria-activedescendant`,
+     * not by moving focus. See ADR-0001.
      */
     private setCurrentOption;
+    /**
+     * @internal
+     * Sets the input's `aria-activedescendant` to the given option `id`, or clears it (to `''`,
+     * per the APG reference) when passed `null` or an empty id. Centralises the ARIA wiring so the
+     * highlight and close paths stay in sync. See ADR-0001.
+     */
+    private setActiveDescendant;
     /**
      * @internal
      * Unselects currently selected option
@@ -2108,6 +2144,17 @@ declare class FlowUiAutocomplete extends FlowRdfFormControl {
     private removeListenersForDropdown;
     /** @internal Handles changes in the default slot */
     private handleDefaultSlotChange;
+    /**
+     * @internal
+     * Establishes the highlighted ("current") option per the APG rules (ADR-0001):
+     * - while filtering (input text has changed): always the first option, so type-then-Enter
+     *   selects the narrowed-down top option.
+     * - on open with unchanged input: the selected option if one matches, else the first.
+     *
+     * Called both on slot change (list re-rendered) and on open (listbox shown without a
+     * re-render, e.g. clicking back into the input), since the latter fires no slot change.
+     */
+    private highlightCurrentOption;
     /** @internal Toggles listbox based on focus and options in the default slot. */
     toggleListbox(): void;
     /**

package/dist/package.json.mjs

@@ -1,3 +1,3 @@
-const version = "4.1.27";
+const version = "4.1.28";
 
 export { version };

package/dist/vscode.html-custom-data.json

@@ -71,6 +71,68 @@
       ],
       "references": []
     },
+    {
+      "name": "flow-ui-animation",
+      "description": "Animate elements declaratively with over 100 animation presets. Powered by the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).\n\n\n---\n\n\n\n\n### **Events:**\n - **flow-ui-cancel** - Emitted when the animation is canceled.\n- **flow-ui-finish** - Emitted when the animation finishes.\n- **flow-ui-start** - Emitted when the animation starts or restarts.\n\n### **Methods:**\n - **cancel()** - Clears all keyframe effects caused by this animation and aborts its playback.\n- **finish()** - Sets the playback time to the end of the animation corresponding to the current playback direction.\n\n### **Slots:**\n - _default_ - The element to animate. Avoid slotting in more than one element, as subsequent ones will be ignored. To animate multiple elements, either wrap them in a single container or use multiple `<flow-ui-animation>` elements.",
+      "attributes": [
+        {
+          "name": "name",
+          "description": "The name of the built-in animation to use. For custom animations, use the `keyframes` prop.\nUse `getAnimationNames()` to retrieve a list of available animations.",
+          "values": []
+        },
+        {
+          "name": "play",
+          "description": "Plays the animation. When omitted, the animation will be paused. This attribute will be automatically removed when\nthe animation finishes or gets canceled.",
+          "values": []
+        },
+        {
+          "name": "delay",
+          "description": "The number of milliseconds to delay the start of the animation.",
+          "values": []
+        },
+        {
+          "name": "direction",
+          "description": "Determines the direction of playback as well as the behavior when reaching the end of an iteration.\n[Learn more](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-direction)",
+          "values": [{ "name": "PlaybackDirection" }]
+        },
+        {
+          "name": "duration",
+          "description": "The number of milliseconds each iteration of the animation takes to complete.",
+          "values": []
+        },
+        {
+          "name": "easing",
+          "description": "The easing function to use for the animation. This can be a Shoelace easing function or a custom easing function\nsuch as `cubic-bezier(0, 1, .76, 1.14)`.",
+          "values": []
+        },
+        {
+          "name": "end-delay",
+          "description": "The number of milliseconds to delay after the active period of an animation sequence.",
+          "values": []
+        },
+        {
+          "name": "fill",
+          "description": "Sets how the animation applies styles to its target before and after its execution.",
+          "values": [{ "name": "FillMode" }]
+        },
+        {
+          "name": "iterations",
+          "description": "The number of iterations to run before the animation completes. Defaults to `Infinity`, which loops.",
+          "values": []
+        },
+        {
+          "name": "iteration-start",
+          "description": "The offset at which to start the animation, usually between 0 (start) and 1 (end).",
+          "values": []
+        },
+        {
+          "name": "playback-rate",
+          "description": "Sets the animation's playback rate. The default is `1`, which plays the animation at a normal speed. Setting this\nto `2`, for example, will double the animation's speed. A negative value can be used to reverse the animation. This\nvalue can be changed without causing the animation to restart.",
+          "values": []
+        }
+      ],
+      "references": []
+    },
     {
       "name": "flow-ui-autocomplete",
       "description": "The Autocomplete is a Text input enhanced by a panel of suggested options.\n\n\n---\n\n\n\n\n### **Events:**\n - **flow-ui-input** - Emitted when the display value changes.\n- **flow-ui-change** - Emitted when the input value changes.\n- **flow-ui-focus** - Emitted when the input is focused.\n- **flow-ui-blur** - Emitted when the input is blurred.\n- **flow-ui-show** - Emitted when the dropdown is shown.\n- **flow-ui-after-show** - Emitted when the dropdown is shown.\n- **flow-ui-hide** - Emitted when the dropdown is hidden.\n- **flow-ui-after-hide** - Emitted when the dropdown is hidden.\n- **flow-ui-invalid** - Emitted when the input is invalid.\n- **flow-ui-valid** - Emitted when the input is valid.\n- **flow-ui-validate** - Emitted when the input is validated.\n- **flow-ui-validate-complete** - Emitted when the input is validated and the validity state is updated.\n- **flow-ui-validate-error** - Emitted when the input is validated and an error occurs.\n- **flow-ui-validate-success** - Emitted when the input is validated and no errors occur.\n\n### **Methods:**\n - **getForm(): _HTMLFormElement | null_** - Gets the associated form, if one exists.\n- **checkValidity(): _boolean_** - Checks for validity but does not show a validation message. Returns `true` when valid and `false` when invalid.\n- **reportValidity(): _boolean_** - Checks for validity and shows the browser's validation message if the control is invalid.\n- **setCustomValidity(_: _string_)** - Sets a custom validation message. Pass an empty string to restore validity.\n- **focus()** - Focuses on the control\n- **blur()** - Blurs from the control.\n- **show()** - Shows the listbox.\n- **hide()** - Hides the listbox.\n- **getInputText()** - Gets the current value of the text input\n\n### **Slots:**\n - _default_ - The listbox options. Must be `<flow-option>` elements. You can use `<flow-divider>` to group items visually.\n- **label** - The input's label. Alternatively, you can use the `label` attribute.\n- **prefix** - Used to prepend a presentational icon or similar element to the combobox.\n- **suffix** - Used to append a presentational icon or similar element to the combobox.\n- **clear-icon** - An icon to use in lieu of the default clear icon.\n- **help-text** - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.\n\n### **CSS Parts:**\n - **form-control** - The form control that wraps the label, input, and help text.\n- **form-control-label** - The label's wrapper.\n- **form-control-input** - The select's wrapper.\n- **form-control-help-text** - The help text's wrapper.\n- **combobox** - The container the wraps the prefix, suffix, combobox, clear icon, and expand button.\n- **prefix** - The container that wraps the prefix slot.\n- **suffix** - The container that wraps the suffix slot.\n- **display-input** - The element that displays the selected option's label, an `<input>` element.\n- **listbox** - The listbox container where options are slotted.\n- **clear-button** - The clear button.",
@@ -176,62 +238,12 @@
       "references": []
     },
     {
-      "name": "flow-ui-animation",
-      "description": "Animate elements declaratively with over 100 animation presets. Powered by the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).\n\n\n---\n\n\n\n\n### **Events:**\n - **flow-ui-cancel** - Emitted when the animation is canceled.\n- **flow-ui-finish** - Emitted when the animation finishes.\n- **flow-ui-start** - Emitted when the animation starts or restarts.\n\n### **Methods:**\n - **cancel()** - Clears all keyframe effects caused by this animation and aborts its playback.\n- **finish()** - Sets the playback time to the end of the animation corresponding to the current playback direction.\n\n### **Slots:**\n - _default_ - The element to animate. Avoid slotting in more than one element, as subsequent ones will be ignored. To animate multiple elements, either wrap them in a single container or use multiple `<flow-ui-animation>` elements.",
+      "name": "flow-ui-breadcrumb",
+      "description": "Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy.\n\n\n---\n\n\n\n\n### **Slots:**\n - _default_ - One or more breadcrumb items to display.\n- **separator** - The separator to use between breadcrumb items. Works best with `<flow-ui-icon>`.\n\n### **CSS Parts:**\n - **base** - The component's base wrapper.",
       "attributes": [
         {
-          "name": "name",
-          "description": "The name of the built-in animation to use. For custom animations, use the `keyframes` prop.\nUse `getAnimationNames()` to retrieve a list of available animations.",
-          "values": []
-        },
-        {
-          "name": "play",
-          "description": "Plays the animation. When omitted, the animation will be paused. This attribute will be automatically removed when\nthe animation finishes or gets canceled.",
-          "values": []
-        },
-        {
-          "name": "delay",
-          "description": "The number of milliseconds to delay the start of the animation.",
-          "values": []
-        },
-        {
-          "name": "direction",
-          "description": "Determines the direction of playback as well as the behavior when reaching the end of an iteration.\n[Learn more](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-direction)",
-          "values": [{ "name": "PlaybackDirection" }]
-        },
-        {
-          "name": "duration",
-          "description": "The number of milliseconds each iteration of the animation takes to complete.",
-          "values": []
-        },
-        {
-          "name": "easing",
-          "description": "The easing function to use for the animation. This can be a Shoelace easing function or a custom easing function\nsuch as `cubic-bezier(0, 1, .76, 1.14)`.",
-          "values": []
-        },
-        {
-          "name": "end-delay",
-          "description": "The number of milliseconds to delay after the active period of an animation sequence.",
-          "values": []
-        },
-        {
-          "name": "fill",
-          "description": "Sets how the animation applies styles to its target before and after its execution.",
-          "values": [{ "name": "FillMode" }]
-        },
-        {
-          "name": "iterations",
-          "description": "The number of iterations to run before the animation completes. Defaults to `Infinity`, which loops.",
-          "values": []
-        },
-        {
-          "name": "iteration-start",
-          "description": "The offset at which to start the animation, usually between 0 (start) and 1 (end).",
-          "values": []
-        },
-        {
-          "name": "playback-rate",
-          "description": "Sets the animation's playback rate. The default is `1`, which plays the animation at a normal speed. Setting this\nto `2`, for example, will double the animation's speed. A negative value can be used to reverse the animation. This\nvalue can be changed without causing the animation to restart.",
+          "name": "label",
+          "description": "The label to use for the breadcrumb control. This will not be shown on the screen, but it will be announced by\nscreen readers and other assistive devices to provide more context for users.",
           "values": []
         }
       ],
@@ -298,45 +310,6 @@
       ],
       "references": []
     },
-    {
-      "name": "flow-ui-breadcrumb-item",
-      "description": "Breadcrumb Items are used inside [breadcrumbs](./flow-ui-breadcrumb) to represent different links.\n\n\n---\n\n\n\n\n### **Slots:**\n - _default_ - The breadcrumb item's label.\n- **prefix** - An optional prefix, usually an icon or icon button.\n- **suffix** - An optional suffix, usually an icon or icon button.\n- **separator** - The separator to use for the breadcrumb item. This will only change the separator for this item. If you want to change it for all items in the group, set the separator on `<flow-ui-breadcrumb>` instead.\n\n### **CSS Parts:**\n - **base** - The component's base wrapper.\n- **label** - The breadcrumb item's label.\n- **prefix** - The container that wraps the prefix.\n- **suffix** - The container that wraps the suffix.\n- **separator** - The container that wraps the separator.",
-      "attributes": [
-        {
-          "name": "href",
-          "description": "Optional URL to direct the user to when the breadcrumb item is activated. When set, a link will be rendered\ninternally. When unset, a button will be rendered instead.",
-          "values": []
-        },
-        {
-          "name": "target",
-          "description": "Tells the browser where to open the link. Only used when `href` is set.",
-          "values": [
-            { "name": "_blank" },
-            { "name": "_parent" },
-            { "name": "_self" },
-            { "name": "_top" }
-          ]
-        },
-        {
-          "name": "rel",
-          "description": "The `rel` attribute to use on the link. Only used when `href` is set.",
-          "values": []
-        }
-      ],
-      "references": []
-    },
-    {
-      "name": "flow-ui-breadcrumb",
-      "description": "Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy.\n\n\n---\n\n\n\n\n### **Slots:**\n - _default_ - One or more breadcrumb items to display.\n- **separator** - The separator to use between breadcrumb items. Works best with `<flow-ui-icon>`.\n\n### **CSS Parts:**\n - **base** - The component's base wrapper.",
-      "attributes": [
-        {
-          "name": "label",
-          "description": "The label to use for the breadcrumb control. This will not be shown on the screen, but it will be announced by\nscreen readers and other assistive devices to provide more context for users.",
-          "values": []
-        }
-      ],
-      "references": []
-    },
     {
       "name": "flow-ui-badge",
       "description": "Badges are used to draw attention and display statuses or counts.\n\n\n---\n\n\n\n\n### **Slots:**\n - _default_ - The badge's content.\n\n### **CSS Parts:**\n - **base** - The component's base wrapper.",
@@ -375,6 +348,33 @@
       ],
       "references": []
     },
+    {
+      "name": "flow-ui-breadcrumb-item",
+      "description": "Breadcrumb Items are used inside [breadcrumbs](./flow-ui-breadcrumb) to represent different links.\n\n\n---\n\n\n\n\n### **Slots:**\n - _default_ - The breadcrumb item's label.\n- **prefix** - An optional prefix, usually an icon or icon button.\n- **suffix** - An optional suffix, usually an icon or icon button.\n- **separator** - The separator to use for the breadcrumb item. This will only change the separator for this item. If you want to change it for all items in the group, set the separator on `<flow-ui-breadcrumb>` instead.\n\n### **CSS Parts:**\n - **base** - The component's base wrapper.\n- **label** - The breadcrumb item's label.\n- **prefix** - The container that wraps the prefix.\n- **suffix** - The container that wraps the suffix.\n- **separator** - The container that wraps the separator.",
+      "attributes": [
+        {
+          "name": "href",
+          "description": "Optional URL to direct the user to when the breadcrumb item is activated. When set, a link will be rendered\ninternally. When unset, a button will be rendered instead.",
+          "values": []
+        },
+        {
+          "name": "target",
+          "description": "Tells the browser where to open the link. Only used when `href` is set.",
+          "values": [
+            { "name": "_blank" },
+            { "name": "_parent" },
+            { "name": "_self" },
+            { "name": "_top" }
+          ]
+        },
+        {
+          "name": "rel",
+          "description": "The `rel` attribute to use on the link. Only used when `href` is set.",
+          "values": []
+        }
+      ],
+      "references": []
+    },
     {
       "name": "flow-ui-busy-overlay",
       "description": "Busy overlay is used to indicate that a component which displays data is being currently updated.\n\n\n---\n\n\n\n\n### **Slots:**\n - _default_ - The component to overlay with when busy.\n- **busy-animation** - The indeterminate custom loading animation to display when busy.\n\n### **CSS Properties:**\n - **--transition-delay** - The delay after which the overlay is shown. _(default: undefined)_\n- **--transition-duration** - The duration of the overlay's fade-in/out transition. _(default: undefined)_\n- **--progress-ring-size** - The size of the default progress ring loading animation. _(default: undefined)_\n- **--progress-ring-track-width** - The width of the default progress ring's track. _(default: undefined)_\n- **--progress-ring-track-color** - The color of the default progress ring's track. _(default: undefined)_\n- **--overlay-background-color** - The background color of the overlay. _(default: undefined)_",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emuanalytics/flow-rdf-ui",
-  "version": "4.1.27",
+  "version": "4.1.28",
   "type": "module",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",