npm - @fabric-msft/fabric-web - Versions diffs - 4.0.0 → 5.0.1 - Mend

@fabric-msft/fabric-web 4.0.0 → 5.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (435) hide show

package/dist/dts/util/direction.d.ts CHANGED Viewed

@@ -1,4 +1,87 @@
 import { Direction } from "@microsoft/fast-web-utilities";
+/**
+ * This module provides a composable system for detecting and monitoring text direction
+ * (LTR/RTL) changes in web applications. It follows a strategy/observer pattern to allow
+ * flexibility for the many ways that direction can be controlled in the document.
+ *
+ * ## Architecture
+ *
+ * The system uses two complementary interfaces:
+ *
+ * - **DirectionStrategy**: Detection - reads direction from a source (CSS, attributes, etc.)
+ * - **DirectionObserver**: Change monitoring - watches for direction changes and notifies
+ *
+ * The `DirectionDetector` class combines the detection and observer strategies to provide
+ * robust direction detection with automatic change notifications.
+ *
+ * ## Built-in Strategies
+ *
+ * - `DirAttributeStrategy`: Reads the `dir` attribute from elements
+ * - `ElementCssStrategy`: Reads computed CSS `direction` property
+ *
+ * ## Built-in Observers
+ *
+ * - `DirAttributeObserver`: Watches for `dir` attribute mutations via MutationObserver
+ *
+ * ## Global DirectionDetector
+ *
+ * A singleton detector is available via `globalDirectionDetector()`. By default, it
+ * monitors the `dir` attribute on the `<html>` element. This is the detector used by the
+ * components in this package to correctly adjust layout, keyboard navigation, etc.
+ *
+ * To customize the global detector, call `setGlobalDirectionDetector()`:
+ *
+ * ```typescript
+ * import {
+ *   setGlobalDirectionDetector,
+ *   DirectionDetector,
+ *   DirAttributeStrategy,
+ *   DirAttributeObserver
+ * } from "@fabric-msft/fabric-web";
+ *
+ * setGlobalDirectionDetector(
+ *   new DirectionDetector({
+ *     strategies: [new DirAttributeStrategy([document.documentElement])],
+ *     observers: [new DirAttributeObserver("html")],
+ *     onChange: (dir) => console.log("Global direction:", dir)
+ *   })
+ * );
+ * ```
+ *
+ * ## Defaults
+ *
+ * The default global DirectionDetector will monitor the `dir` attribute on the
+ * `html` element. You do not need to set anything if this is the strategy that your app
+ * uses to control document direction.
+ *
+ * ```html
+ * <html dir="rtl">
+ * ```
+ *
+ * ## Custom DirectionDetector
+ *
+ * ```typescript
+ * import {
+ *   DirectionDetector,
+ *   DirAttributeStrategy,
+ *   DirAttributeObserver
+ * } from "@fabric-msft/fabric-web";
+ *
+ * const detector = new DirectionDetector({
+ *   strategies: [new DirAttributeStrategy([document.documentElement])],
+ *   observers: [new DirAttributeObserver("html")],
+ *   onChange: (dir, { previous }) => {
+ *     console.log(`Direction changed: ${previous} → ${dir}`);
+ *   }
+ * });
+ *
+ * // Access current direction
+ * console.log(detector.value); // 'ltr' or 'rtl'
+ *
+ * // Clean up when done
+ * detector.stop();
+ * ```
+ */
 /**
  * Determines the current localization direction of an element.
  *
@@ -8,4 +91,114 @@ import { Direction } from "@microsoft/fast-web-utilities";
  * @public
  */
 export declare const getDirection: (rootNode: HTMLElement) => Direction;
+export declare function findClosestElementsWithDir(element: Element): Element[];
+export declare function isRtl(): boolean;
+export type DirectionOrNull = Direction | null;
+/**
+ * Interface for direction detection strategies.
+ * Strategies are pure functions that detect direction from a source.
+ * @public
+ */
+export interface DirectionStrategy {
+    /**
+     * Get the current direction value.
+     */
+    getDirection(): DirectionOrNull;
+}
+/**
+ * Interface for observing direction changes.
+ * Observers monitor a source and notify when changes may have occurred.
+ * @public
+ */
+export interface DirectionObserver {
+    /**
+     * Start observing for direction changes.
+     * @param notify - Callback to invoke when a change may have occurred.
+     */
+    start(notify: () => void): void;
+    /**
+     * Stop observing and clean up resources.
+     */
+    stop(): void;
+}
+/**
+ * Strategy that reads direction from the computed CSS style of a specific element.
+ * @public
+ */
+export declare class ElementCssStrategy implements DirectionStrategy {
+    private readonly element;
+    private readonly doc;
+    constructor(element: Element | null);
+    getDirection(): DirectionOrNull;
+}
+/**
+ * Strategy that reads direction from the dir attribute.
+ * Takes a list of elements and checks each element until it finds one with a "dir" attribute specified.
+ * @public
+ */
+export declare class DirAttributeStrategy implements DirectionStrategy {
+    private readonly elements;
+    constructor(elements: Element[]);
+    getDirection(): DirectionOrNull;
+}
+/**
+ * Observer that watches for dir attribute changes using MutationObserver.
+ * @public
+ */
+export declare class DirAttributeObserver implements DirectionObserver {
+    private readonly doc;
+    private readonly target;
+    private mo;
+    constructor(target?: Element | string, doc?: Document);
+    start(notify: () => void): void;
+    stop(): void;
+}
+export interface DirectionDetectorOptions {
+    /**
+     * Ordered list of strategies. First strategy that yields a non-null direction wins.
+     */
+    strategies: DirectionStrategy[];
+    /**
+     * Optional observers to monitor for direction changes.
+     * When any observer fires, the detector will recompute direction.
+     */
+    observers?: DirectionObserver[];
+    /**
+     * Called when the resolved direction changes.
+     */
+    onChange?: (dir: DirectionOrNull, info: {
+        previous: DirectionOrNull;
+    }) => void;
+}
+/**
+ * Detects and (optionally) observes direction using a chain of strategies.
+ * The first strategy to return a non-null direction wins.
+ * @public
+ */
+export declare class DirectionDetector {
+    private readonly strategies;
+    private readonly observers;
+    private readonly onChange?;
+    private rafId;
+    private _value;
+    private observing;
+    constructor(options: DirectionDetectorOptions);
+    get value(): Direction;
+    /**
+     * Start all observers.
+     */
+    private start;
+    /**
+     * Stop observing and cancel any scheduled refresh.
+     */
+    stop(): void;
+    stable(): boolean;
+    /**
+     * Force recomputation; invokes onChange only if the resolved direction changed.
+     */
+    refresh(): DirectionOrNull;
+    private computeDirection;
+}
+export declare function setGlobalDirectionDetector(detector: DirectionDetector): void;
+export declare function globalDirectionDetector(): DirectionDetector;
 //# sourceMappingURL=direction.d.ts.map

package/dist/dts/util/direction.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"direction.d.ts","sourceRoot":"","sources":["../../../../../../src/util/direction.ts"],"names":[],"mappings":"~~AAEA~~,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE1D;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,WAAW,KAAG,SAIpD,CAAC"}
1	+ {"version":3,"file":"direction.d.ts","sourceRoot":"","sources":["../../../../../../src/util/direction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,WAAW,KAAG,SAIpD,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,EAAE,CAYtE;AAED,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,IAAI,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,YAAY,IAAI,eAAe,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAEhC;;OAEG;IACH,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,iBAAiB;IAC1D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAW;gBAEnB,OAAO,EAAE,OAAO,GAAG,IAAI;IAKnC,YAAY,IAAI,eAAe;CAahC;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,YAAW,iBAAiB;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAY;gBAEzB,QAAQ,EAAE,OAAO,EAAE;IAI/B,YAAY,IAAI,eAAe;CAShC;AAED;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,iBAAiB;IAC5D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAW;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,EAAE,CAAiC;gBAE/B,MAAM,GAAE,OAAO,GAAG,MAAe,EAAE,GAAG,GAAE,QAAmB;IAKvE,KAAK,CAAC,MAAM,EAAE,MAAM,IAAI,GAAG,IAAI;IAc/B,IAAI,IAAI,IAAI;CAIb;AAED,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAEhC;;;OAGG;IACH,SAAS,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,EAAE,CACT,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE;QAAE,QAAQ,EAAE,eAAe,CAAA;KAAE,KAChC,IAAI,CAAC;CACX;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAGhB;IAEV,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,EAAE,wBAAwB;IAU7C,IAAI,KAAK,IAAI,SAAS,CAErB;IAED;;OAEG;IACH,OAAO,CAAC,KAAK;IA0Bb;;OAEG;IACH,IAAI,IAAI,IAAI;IAaZ,MAAM,IAAI,OAAO;IAIjB;;OAEG;IACH,OAAO,IAAI,eAAe;IAgB1B,OAAO,CAAC,gBAAgB;CAOzB;AAID,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAE5E;AAED,wBAAgB,uBAAuB,IAAI,iBAAiB,CAU3D"}

package/dist/dts/util/dom.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export declare const inputElementMethods: string[];
2	+ //# sourceMappingURL=dom.d.ts.map

package/dist/dts/util/dom.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../../../../../src/util/dom.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB,UAa/B,CAAC"}

package/dist/dts/util/element-internal-mocks.d.ts ADDED Viewed

@@ -0,0 +1,67 @@
+export declare class MockElementInternals implements ElementInternals {
+    ariaDescription: string | null;
+    ariaBrailleLabel: string | null;
+    ariaBrailleRoleDescription: string | null;
+    private _form;
+    private _labels;
+    private _element;
+    constructor(element: HTMLElement);
+    get form(): HTMLFormElement | null;
+    get labels(): NodeList;
+    get shadowRoot(): null;
+    get states(): Set<string>;
+    get validationMessage(): string;
+    get validity(): ValidityState;
+    get willValidate(): boolean;
+    role: string;
+    ariaAtomic: string;
+    ariaAutoComplete: string;
+    ariaBusy: string;
+    ariaChecked: string;
+    ariaColCount: string;
+    ariaColIndex: string;
+    ariaColIndexText: string;
+    ariaColSpan: string;
+    ariaCurrent: string;
+    ariaDisabled: string;
+    ariaExpanded: string;
+    ariaHasPopup: string;
+    ariaHidden: string;
+    ariaInvalid: string;
+    ariaKeyShortcuts: string;
+    ariaLabel: string;
+    ariaLevel: string;
+    ariaLive: string;
+    ariaModal: string;
+    ariaMultiLine: string;
+    ariaMultiSelectable: string;
+    ariaOrientation: string;
+    ariaPlaceholder: string;
+    ariaPosInSet: string;
+    ariaPressed: string;
+    ariaReadOnly: string;
+    ariaRelevant: string;
+    ariaRequired: string;
+    ariaRoleDescription: string;
+    ariaRowCount: string;
+    ariaRowIndex: string;
+    ariaRowIndexText: string;
+    ariaRowSpan: string;
+    ariaSelected: string;
+    ariaSetSize: string;
+    ariaSort: string;
+    ariaValueMax: string;
+    ariaValueMin: string;
+    ariaValueNow: string;
+    ariaValueText: string;
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    setFormValue(_value: File | string | FormData | null, _state?: File | string | FormData | null): void;
+    setValidity(_flags: ValidityStateFlags, _message?: string, _anchor?: HTMLElement): void;
+}
+/**
+ * If the HTMLElement prototype does not have the attachInternals method, add it.
+ * This is used to create a new MockElementInternals instance when the element is attached to the DOM.
+ */
+export declare function attachMockElementInternals(): void;
+//# sourceMappingURL=element-internal-mocks.d.ts.map

package/dist/dts/util/element-internal-mocks.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"element-internal-mocks.d.ts","sourceRoot":"","sources":["../../../../../../src/util/element-internal-mocks.ts"],"names":[],"mappings":"AAAA,qBAAa,oBAAqB,YAAW,gBAAgB;IAC3D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;IACtC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAQ;IACvC,0BAA0B,EAAE,MAAM,GAAG,IAAI,CAAQ;IACjD,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,OAAO,CAA0D;IACzE,OAAO,CAAC,QAAQ,CAAc;gBAElB,OAAO,EAAE,WAAW;IAMhC,IAAI,IAAI,2BAMP;IACD,IAAI,MAAM,aAET;IACD,IAAI,UAAU,SAEb;IACD,IAAI,MAAM,gBAET;IAGD,IAAI,iBAAiB,WAEpB;IACD,IAAI,QAAQ,IAaL,aAAa,CACnB;IACD,IAAI,YAAY,YAEf;IAGD,IAAI,SAAM;IACV,UAAU,SAAM;IAChB,gBAAgB,SAAM;IACtB,QAAQ,SAAM;IACd,WAAW,SAAM;IACjB,YAAY,SAAM;IAClB,YAAY,SAAM;IAClB,gBAAgB,SAAM;IACtB,WAAW,SAAM;IACjB,WAAW,SAAM;IACjB,YAAY,SAAM;IAClB,YAAY,SAAM;IAClB,YAAY,SAAM;IAClB,UAAU,SAAM;IAChB,WAAW,SAAM;IACjB,gBAAgB,SAAM;IACtB,SAAS,SAAM;IACf,SAAS,SAAM;IACf,QAAQ,SAAM;IACd,SAAS,SAAM;IACf,aAAa,SAAM;IACnB,mBAAmB,SAAM;IACzB,eAAe,SAAM;IACrB,eAAe,SAAM;IACrB,YAAY,SAAM;IAClB,WAAW,SAAM;IACjB,YAAY,SAAM;IAClB,YAAY,SAAM;IAClB,YAAY,SAAM;IAClB,mBAAmB,SAAM;IACzB,YAAY,SAAM;IAClB,YAAY,SAAM;IAClB,gBAAgB,SAAM;IACtB,WAAW,SAAM;IACjB,YAAY,SAAM;IAClB,WAAW,SAAM;IACjB,QAAQ,SAAM;IACd,YAAY,SAAM;IAClB,YAAY,SAAM;IAClB,YAAY,SAAM;IAClB,aAAa,SAAM;IAGnB,aAAa;IAGb,cAAc;IAId,YAAY,CACV,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,EACvC,MAAM,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI;IAE1C,WAAW,CACT,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,WAAW;CAExB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,SAMzC"}

package/dist/dts/util/focus-management.d.ts ADDED Viewed

@@ -0,0 +1,132 @@
+/**
+ * Options for creating a roving focus controller.
+ *
+ * @public
+ */
+export interface RovingFocusOptions {
+    /**
+     * Function that returns the current list of elements to manage.
+     * Called fresh each time to support dynamic slot changes.
+     */
+    items: () => HTMLElement[];
+    /**
+     * Filter function to determine if an element is disabled.
+     * Default: checks for `disabled`, `aria-disabled="true"`, or `inert` attributes.
+     */
+    isDisabled?: (el: HTMLElement) => boolean;
+    /**
+     * Navigation orientation.
+     * - "vertical": ArrowUp/ArrowDown (default)
+     * - "horizontal": ArrowLeft/ArrowRight
+     * - "both": All four arrow keys
+     */
+    orientation?: "vertical" | "horizontal" | "both";
+    /**
+     * Enable Home/End key support.
+     * @default true
+     */
+    enableHomeEnd?: boolean;
+    /**
+     * Enable wrapping at boundaries.
+     * @default true
+     */
+    wrap?: boolean;
+    /**
+     * Whether handleKeydown calls preventDefault for handled keys.
+     * @default true
+     */
+    preventDefault?: boolean;
+    /**
+     * Custom focus implementation for components with internal focusable elements
+     * (e.g., Prompt with internal button). If not provided, calls `el.focus()`.
+     */
+    focusItem?: (el: HTMLElement) => void;
+    /**
+     * Callback fired when the active item changes.
+     */
+    onFocusChange?: (el: HTMLElement, index: number) => void;
+    /**
+     * Function to determine if the component is in RTL mode.
+     * When true, horizontal arrow keys are swapped.
+     * @default () => false
+     */
+    isRtl: () => boolean;
+}
+/**
+ * Controller interface for managing roving tabindex focus.
+ *
+ * @remarks
+ * Invariants enforced by this controller:
+ * 1. Exactly one enabled item has `tabindex="0"` (the "active" item)
+ * 2. All other managed items have `tabindex="-1"`
+ * 3. When focus moves: new item gets tabindex=0, previous active gets -1, new item receives focus
+ *
+ * @public
+ */
+export interface RovingFocusController {
+    /**
+     * Apply roving tabindex. Preserves current active if still valid and enabled;
+     * otherwise falls back to first enabled. If no enabled items, all get tabindex=-1.
+     */
+    applyTabindex(): void;
+    /**
+     * Move focus by delta (+1 or -1).
+     * @returns true if focus moved successfully
+     */
+    move(delta: 1 | -1): boolean;
+    /**
+     * Focus first enabled item.
+     * @returns true if successful
+     */
+    focusFirst(): boolean;
+    /**
+     * Focus last enabled item.
+     * @returns true if successful
+     */
+    focusLast(): boolean;
+    /**
+     * Focus specific item.
+     * @returns false if item is not in list or is disabled
+     */
+    focus(item: HTMLElement): boolean;
+    /**
+     * Sync active tabindex to match a target element (use on focusin/click).
+     * Updates tabindex without calling focus() to avoid jumpy behavior.
+     * @returns true if target was found and made active
+     */
+    sync(target: EventTarget | null): boolean;
+    /**
+     * Handle keydown event.
+     * @returns true if handled. Calls preventDefault() when configured.
+     */
+    handleKeydown(event: KeyboardEvent): boolean;
+    /**
+     * Clean up (for lifecycle symmetry; currently a no-op).
+     */
+    destroy(): void;
+}
+/**
+ * Creates a roving focus controller for managing keyboard navigation
+ * across a list of elements using the roving tabindex pattern.
+ *
+ * @example
+ * ```typescript
+ * const controller = createRovingFocusController({
+ *   items: () => this.slottedPills ?? [],
+ *   orientation: "vertical",
+ *   enableHomeEnd: true,
+ *   wrap: true
+ * });
+ *
+ * // In connectedCallback or setup:
+ * controller.applyTabindex();
+ *
+ * // In keydown handler:
+ * if (controller.handleKeydown(event)) return;
+ * // ...handle other keys like Escape
+ * ```
+ *
+ * @public
+ */
+export declare function createRovingFocusController(options: RovingFocusOptions): RovingFocusController;
+//# sourceMappingURL=focus-management.d.ts.map

package/dist/dts/util/focus-management.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"focus-management.d.ts","sourceRoot":"","sources":["../../../../../../src/util/focus-management.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,KAAK,EAAE,MAAM,WAAW,EAAE,CAAC;IAE3B;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC;IAE1C;;;;;OAKG;IACH,WAAW,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC;IAEjD;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,CAAC;IAEtC;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAEzD;;;;OAIG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC;IAE7B;;;OAGG;IACH,UAAU,IAAI,OAAO,CAAC;IAEtB;;;OAGG;IACH,SAAS,IAAI,OAAO,CAAC;IAErB;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC;IAElC;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAAC;IAE1C;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;IAE7C;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAQD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,kBAAkB,GAC1B,qBAAqB,CAgQvB"}

package/dist/dts/util/hash-utilities.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+/**
+ * Creates a unique ID string using a prefix and counter as salt for the random hex.
+ * @param prefix - The prefix string for the ID
+ * @param counter - Optional. A counter value used as salt for additional uniqueness
+ * @returns A unique ID string in the format `{prefix}{counter}-{randomHex}`
+ */
+export declare function createUniqueId(prefix: string, counter?: number): string;
+//# sourceMappingURL=hash-utilities.d.ts.map

package/dist/dts/util/hash-utilities.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"hash-utilities.d.ts","sourceRoot":"","sources":["../../../../../../src/util/hash-utilities.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,MAAU,GAAG,MAAM,CAK1E"}

package/dist/dts/util/index.d.ts CHANGED Viewed

@@ -1,11 +1,18 @@
+export * from "./accessibility-utilities.js";
+export * from "./apply-mixins.js";
+export * from "./attribute-utilities.js";
+export * from "./debounce.js";
+export * from "./debug.js";
 export * from "./descendants.js";
 export * from "./direction.js";
-export * from "./typings.js";
-export * from "./template-helpers.js";
-export * from "./match-media-stylesheet-behaviors.js";
+export * from "./dom.js";
+export * from "./element-internal-mocks.js";
 export * from "./element-internals.js";
-export * from "./apply-mixins.js";
-export * from "./whitespace-filter.js";
+export * from "./focus-management.js";
+export * from "./hash-utilities.js";
+export * from "./match-media-stylesheet-behaviors.js";
 export * from "./support.js";
-export * from "./positioning.js";
+export * from "./template-helpers.js";
+export * from "./typings.js";
+export * from "./whitespace-filter.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/dts/util/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/util/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;~~AAC7B~~,cAAc,uBAAuB,CAAC;AACtC,cAAc,~~uCAAuC~~,CAAC;~~AACtD~~,cAAc,~~wBAAwB~~,CAAC;~~AACvC~~,cAAc,~~mBAAmB~~,CAAC;~~AAClC~~,cAAc,~~wBAAwB~~,CAAC;~~AACvC~~,cAAc,cAAc,CAAC;AAC7B,cAAc,~~kBAAkB~~,CAAC"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/util/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uCAAuC,CAAC;AACtD,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC"}

package/dist/dts/util/positioning/flexible-position-strategy.d.ts ADDED Viewed

@@ -0,0 +1,87 @@
+/**
+ * Flexible position strategy - main positioning engine.
+ * Orchestrates position calculation, fallback selection, and style application.
+ * Inspired by Angular CDK's FlexibleConnectedPositionStrategy.
+ */
+import type { ConnectedPosition, FlexiblePositionStrategyConfig, RepositionResult } from "./types.js";
+/**
+ * Flexible position strategy implementation.
+ * Main entry point for positioning overlays with fallback logic.
+ */
+export declare class FlexiblePositionStrategy {
+    private readonly origin;
+    private readonly overlay;
+    private readonly positions;
+    private readonly boundaryElement;
+    private readonly offsetParent;
+    private readonly viewportMargin;
+    private readonly resize;
+    private readonly resizeMinHeight;
+    constructor(config: FlexiblePositionStrategyConfig);
+    /**
+     * Get the effective boundary (custom boundary or viewport).
+     */
+    private getBoundary;
+    /**
+     * Returns the configured candidate positions.
+     */
+    private getCandidates;
+    /**
+     * Evaluate a single position against the current boundary.
+     * Returns the computed PositionResult without applying any styles.
+     */
+    private evaluatePosition;
+    /**
+     * Selects the best position from the candidates list.
+     *
+     * 1. First candidate that fits completely wins immediately.
+     * 2. If nothing fits and resize is enabled, picks the one with most
+     *    available space (best candidate for resize).
+     * 3. Otherwise picks the position with the most visible area.
+     */
+    private selectBestPosition;
+    /**
+     * Apply position result to the overlay element.
+     */
+    private applyPositionResult;
+    /**
+     * Get the available space for the overlay in a given position.
+     * Measures the distance from the anchor edge to the boundary edge in the
+     * relevant direction based on the position's connection points.
+     *
+     * @param position - The connected position to measure space for.
+     * @returns Available space in pixels.
+     */
+    getAvailableSpace(position: ConnectedPosition): number;
+    /**
+     * Applies a resize constraint to the overlay element if it
+     * does not fit in the available space for the given position.
+     *
+     * @param position - The connected position to measure available space for.
+     * @returns Whether a constraint was applied and the max-height value.
+     */
+    private tryResize;
+    /**
+     * High-level reposition entry point.
+     *
+     * 1. Clears any previous resize constraint so the overlay is evaluated
+     *    at its natural size.
+     * 2. Selects the best position from the positions array.
+     * 3. Applies a resize constraint if the overlay still overflows.
+     * 4. Applies the final position.
+     *
+     * The component controls flip vs auto behavior by choosing which
+     * positions to provide:
+     * - Flip: `[original, opposite]`
+     * - Auto: `[original, ...allOtherCandidates]`
+     *
+     * @returns A {@link RepositionResult} describing what happened, or `null`
+     *   if no positions or resize are provided.
+     */
+    reposition(): RepositionResult | null;
+    /**
+     * Clear any resize constraint applied to the overlay element.
+     */
+    private clearResize;
+}
+//# sourceMappingURL=flexible-position-strategy.d.ts.map

package/dist/dts/util/positioning/flexible-position-strategy.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"flexible-position-strategy.d.ts","sourceRoot":"","sources":["../../../../../../../src/util/positioning/flexible-position-strategy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAGjB,8BAA8B,EAE9B,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAWpB;;;GAGG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;gBAEzC,MAAM,EAAE,8BAA8B;IAWlD;;OAEG;IACH,OAAO,CAAC,WAAW;IAOnB;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IA4C1B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAS3B;;;;;;;OAOG;IACH,iBAAiB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM;IA+BtD;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IA2BjB;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,IAAI,gBAAgB,GAAG,IAAI;IAsCrC;;OAEG;IACH,OAAO,CAAC,WAAW;CAMpB"}

package/dist/dts/util/positioning/index.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+/**
+ * Positioning utilities - Angular CDK-inspired positioning engine.
+ * @packageDocumentation
+ */
+export type { HorizontalConnectionPos, VerticalConnectionPos, OriginConnectionPosition, OverlayConnectionPosition, ConnectedPosition, ConnectionPositionPair, Point, BoundaryBounds, OverlayFit, PositionResult, ViewportMargin, FlexiblePositionStrategyConfig, CollisionEdge, RepositionMode, RepositionResult } from "./types.js";
+export { HorizontalConnectionPositions, VerticalConnectionPositions, CollisionEdges, RepositionModes, DEFAULT_ROOT_MARGIN } from "./types.js";
+export { getViewportBounds, getBoundaryBounds, getEffectiveBoundary, getOriginPoint, getOverlayPoint, getOverlayFit, applyPositionStyles } from "./position-calculator.js";
+export { FlexiblePositionStrategy } from "./flexible-position-strategy.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/dts/util/positioning/index.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../src/util/positioning/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EACV,uBAAuB,EACvB,qBAAqB,EACrB,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,EACL,cAAc,EACd,UAAU,EACV,cAAc,EACd,cAAc,EACd,8BAA8B,EAC9B,aAAa,EACb,cAAc,EACd,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,6BAA6B,EAC7B,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,aAAa,EACb,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/dts/util/positioning/position-calculator.d.ts ADDED Viewed

@@ -0,0 +1,46 @@
+/**
+ * Position calculation utilities inspired by Angular CDK's FlexibleConnectedPositionStrategy.
+ * Provides coordinate-based positioning calculations for overlays/popovers.
+ */
+import type { Point, ConnectedPosition, BoundaryBounds, OverlayFit, ViewportMargin } from "./types.js";
+/**
+ * Get the bounding rectangle for the viewport.
+ */
+export declare function getViewportBounds(): BoundaryBounds;
+/**
+ * Get the bounding rectangle for a custom boundary element.
+ */
+export declare function getBoundaryBounds(element: HTMLElement): BoundaryBounds;
+/**
+ * Get the effective boundary, accounting for viewport margin.
+ */
+export declare function getEffectiveBoundary(boundary: BoundaryBounds, viewportMargin?: ViewportMargin): BoundaryBounds;
+/**
+ * Calculate the origin point (x, y) on the origin element based on connection position.
+ * This is the point on the anchor element where the overlay will connect.
+ */
+export declare function getOriginPoint(originRect: DOMRect, position: ConnectedPosition): Point;
+/**
+ * Calculate the overlay point (x, y) - the top-left corner of the overlay
+ * when positioned relative to the origin point.
+ */
+export declare function getOverlayPoint(originPoint: Point, overlayRect: DOMRect, position: ConnectedPosition): Point;
+/**
+ * Calculate how well the overlay fits within the boundary when positioned at the given point.
+ */
+export declare function getOverlayFit(overlayPoint: Point, overlayRect: DOMRect, boundary: BoundaryBounds): OverlayFit;
+/**
+ * Apply position styles to the overlay element.
+ *
+ * By default the overlay is pinned via `top`/`left`. When the resolved
+ * {@link ConnectedPosition} attaches the overlay's bottom or end edge
+ * (`overlayY === "bottom"` or `overlayX === "end"`), the corresponding
+ * CSS edge is used instead so that any subsequent height/width constraint
+ * causes the overlay to shrink from the *unattached* edge rather than
+ * detaching from the anchor.
+ *
+ * When an offsetParent is provided, viewport coordinates are converted to
+ * positions relative to that element (for `position: absolute` children).
+ */
+export declare function applyPositionStyles(overlayElement: HTMLElement, overlayPoint: Point, position: ConnectedPosition, offsetParent?: HTMLElement | null): void;
+//# sourceMappingURL=position-calculator.d.ts.map

package/dist/dts/util/positioning/position-calculator.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"position-calculator.d.ts","sourceRoot":"","sources":["../../../../../../../src/util/positioning/position-calculator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,iBAAiB,EACjB,cAAc,EACd,UAAU,EACV,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CASlD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CAUtE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,cAAc,EACxB,cAAc,GAAE,cAAkB,GACjC,cAAc,CA4BhB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,OAAO,EACnB,QAAQ,EAAE,iBAAiB,GAC1B,KAAK,CAyBP;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,KAAK,EAClB,WAAW,EAAE,OAAO,EACpB,QAAQ,EAAE,iBAAiB,GAC1B,KAAK,CAgCP;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,KAAK,EACnB,WAAW,EAAE,OAAO,EACpB,QAAQ,EAAE,cAAc,GACvB,UAAU,CAsCZ;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,WAAW,EAC3B,YAAY,EAAE,KAAK,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,YAAY,CAAC,EAAE,WAAW,GAAG,IAAI,GAChC,IAAI,CA8BN"}