@radix-ng/primitives 1.0.0-beta.3 → 1.0.0-beta.4

package/types/radix-ng-primitives-floating-focus-manager.d.ts

@@ -0,0 +1,175 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Provider } from '@angular/core';
+import { BooleanInput } from '@radix-ng/primitives/core';
+import * as i1 from '@radix-ng/primitives/focus-scope';
+
+/**
+ * How a popup was opened / closed (Base UI `InteractionType`). `null` = a **programmatic** open (prefer
+ * the previously-focused element); `''` = an **unknown** interaction. The two are deliberately distinct
+ * (Base UI keys `preferPreviousFocus = openInteractionType == null` off exactly this).
+ */
+type RdxInteractionType = 'mouse' | 'touch' | 'pen' | 'keyboard' | '' | null;
+/** A focus target: an element, a getter, or `null`. */
+type RdxFocusTarget = HTMLElement | (() => HTMLElement | null) | null;
+/** `initialFocus` policy (ADR 0017 §2) — a target, `false`, or an open-interaction callback. */
+type RdxInitialFocus = RdxFocusTarget | false | ((openInteractionType: RdxInteractionType) => RdxFocusTarget | false);
+/** `returnFocus` policy (ADR 0017 §2) — a target/boolean or a callback receiving the **close** interaction type. */
+type RdxReturnFocus = RdxFocusTarget | boolean | ((closeInteractionType: RdxInteractionType) => RdxFocusTarget | boolean);
+/** Normalizes a DOM event into Base UI-like interaction intent for focus policy decisions. */
+declare function getInteractionTypeFromEvent(event?: Event): RdxInteractionType;
+/** Resolves an {@link RdxFocusTarget} (element | getter | null) to a concrete element. */
+declare function resolveFocusTarget(target: RdxFocusTarget): HTMLElement | null;
+/**
+ * Resolves an {@link RdxInitialFocus} policy against how the popup opened.
+ */
+declare function resolveInitialFocus(policy: RdxInitialFocus, openInteractionType: RdxInteractionType): HTMLElement | null | false;
+/**
+ * Resolves an {@link RdxReturnFocus} policy against how the popup closed. `false` = do not return focus;
+ * `true` = the default (return to the previously-focused element); an element = return there.
+ */
+declare function resolveReturnFocus(policy: RdxReturnFocus, closeInteractionType: RdxInteractionType): HTMLElement | boolean | null;
+/**
+ * DI seam for a **composing primitive** (Dialog / Popover / Menu) to drive the manager's gates from its
+ * own root context instead of template-bound inputs (which a primitive cannot set). Each field falls
+ * back to the manager's input, then to the documented default. Mirrors {@link RdxFocusScopeConfig}.
+ */
+interface RdxFloatingFocusManagerConfig {
+    modal?: () => boolean;
+    inert?: () => boolean;
+    enabled?: () => boolean;
+    closeOnFocusOut?: () => boolean;
+    initialFocus?: () => RdxInitialFocus;
+    returnFocus?: () => RdxReturnFocus;
+    openInteractionType?: () => RdxInteractionType;
+    closeInteractionType?: () => RdxInteractionType;
+}
+declare const RDX_FLOATING_FOCUS_MANAGER_CONFIG: InjectionToken<RdxFloatingFocusManagerConfig>;
+/** Provides a {@link RdxFloatingFocusManagerConfig} for an enclosing primitive's focus manager. */
+declare function provideFloatingFocusManagerConfig(factory: () => RdxFloatingFocusManagerConfig): Provider;
+/**
+ * `RdxFloatingFocusManager` (ADR 0017 Phase 1b skeleton) — the Angular counterpart of Base UI's
+ * `FloatingFocusManager`. It is a **coordinator** that composes three low-level focus parts (it never
+ * inherits them, which would re-fuse trap + popup policy): the **reworked {@link RdxFocusScope}** (the
+ * trap, via `hostDirectives`), the portal-focus bridge, and owner-`Document` guards. Per ADR 0017 §1/§2
+ * its policies are **independent**, none derived from `modal`.
+ *
+ * **This skeleton wires the composition + lifecycle gates:**
+ * - `enabled` — the manager's active-ness (`mounted && !hover-open`). When off, **no trap** (and, later,
+ *   no aria-hidden / no marker — Phase 2).
+ * - `modal` → `RdxFocusScope.trapped`: the effective trap is `enabled() && modal()`, pushed into the
+ *   composed focus scope through its config token (the composition seam).
+ * - `loop` is forwarded to `RdxFocusScope`.
+ * - `initialFocus` / `returnFocus` are **orchestrated** here (the §2 policy contract, incl. the
+ *   interaction-type callback forms): `initialFocus` via the scope's `mountAutoFocus` hook, `returnFocus`
+ *   via the scope's `returnFocus` config seam (resolved at the scope's queued post-unmount frame). The
+ *   portal-focus bridge remains a later-phase dependency.
+ */
+declare class RdxFloatingFocusManager {
+    /** Manager active-ness (ADR 0017 §2): the popup is mounted **and** not hover-opened. */
+    readonly enabled: _angular_core.InputSignalWithTransform<boolean | undefined, BooleanInput>;
+    /** Modal popup → focus trap. Combined with `enabled` to drive the composed `RdxFocusScope`. */
+    readonly modal: _angular_core.InputSignalWithTransform<boolean | undefined, BooleanInput>;
+    /**
+     * Whether outside elements receive the real `inert` attribute. Defaults to the effective `modal` value,
+     * but primitives can split focus trapping from pointer/AT isolation (Base UI `modal="trap-focus"`).
+     */
+    readonly inert: _angular_core.InputSignalWithTransform<boolean | undefined, BooleanInput>;
+    /** Where focus goes when the popup opens (ADR 0017 §2). */
+    readonly initialFocus: _angular_core.InputSignal<RdxInitialFocus | undefined>;
+    /** Where focus returns when the popup closes (ADR 0017 §2). */
+    readonly returnFocus: _angular_core.InputSignal<RdxReturnFocus | undefined>;
+    /**
+     * Whether a **non-modal** popup closes when focus leaves to an unrelated node (Base UI
+     * `closeOnFocusOut`, default `true`; Dialog sets it to `!disablePointerDismissal`). Modal popups
+     * never close on focus-out (the trap keeps focus in).
+     */
+    readonly closeOnFocusOut: _angular_core.InputSignalWithTransform<boolean | undefined, BooleanInput>;
+    /**
+     * Emitted when focus leaves a non-modal popup to a node **unrelated** to the floating tree (ADR 0017
+     * §3) — the consumer should close the popup. This is the focus-manager's focus-out close (it reads
+     * the shared tree), replacing the dismissal capability's focus-out at the ADR 0015 Phase-4 cutover.
+     */
+    readonly focusOut: _angular_core.OutputEmitterRef<FocusEvent>;
+    /** Optional DI config a composing primitive provides to drive the gates (input wins over config). */
+    private readonly config;
+    /** Effective gates: `input ?? config ?? default`. */
+    readonly effectiveEnabled: _angular_core.Signal<boolean>;
+    readonly effectiveModal: _angular_core.Signal<boolean>;
+    readonly effectiveInert: _angular_core.Signal<boolean>;
+    readonly effectiveCloseOnFocusOut: _angular_core.Signal<boolean>;
+    readonly effectiveInitialFocus: _angular_core.Signal<false | HTMLElement | ((openInteractionType: RdxInteractionType) => RdxFocusTarget | false) | null>;
+    readonly effectiveReturnFocus: _angular_core.Signal<boolean | HTMLElement | ((closeInteractionType: RdxInteractionType) => RdxFocusTarget | boolean)>;
+    readonly effectiveOpenInteractionType: _angular_core.Signal<RdxInteractionType>;
+    readonly effectiveCloseInteractionType: _angular_core.Signal<RdxInteractionType>;
+    /** The effective trap state the composed `RdxFocusScope` reads via its config token. */
+    readonly trapped: _angular_core.Signal<boolean>;
+    private readonly focusScopeConfig;
+    private readonly host;
+    private readonly isBrowser;
+    /** The shared per-popup context (open / triggers / elements), if a primitive root provides one. */
+    private readonly rootContext;
+    /** The registration handle for this node, used to read the shared tree (ancestors / descendants). */
+    private readonly registration;
+    private readonly _interactionType;
+    /** How the popup was most recently interacted with — fed to the initial/return focus policy callbacks. */
+    readonly interactionType: _angular_core.Signal<RdxInteractionType>;
+    constructor();
+    /** Records the most recent open/close interaction (pointer type or keyboard) for the focus policies. */
+    private trackInteractionType;
+    /**
+     * Initial-focus orchestration (ADR 0017 §2). The manager owns the focus *policy*; it intercepts the
+     * composed {@link RdxFocusScope}'s preventable `mountAutoFocus` (its designed extension point) and
+     * applies the `initialFocus` policy, falling back to the scope's first-tabbable default when the
+     * policy is `null`. (`returnFocus` is orchestrated separately via the config seam — see
+     * {@link resolveReturnFocusTarget} — because it must run during the scope's queued *post-unmount* frame.)
+     */
+    private wireFocusOrchestration;
+    /**
+     * Resolves the {@link returnFocus} policy against the **close** interaction type for the composed
+     * focus scope to apply at unmount (ADR 0017 §2). Mirrors Base UI's `getReturnElement`:
+     * - `false` → `false` (the scope suppresses return-focus);
+     * - `true` / `null` → `undefined` (the scope's default — return to the element focused before mount);
+     * - an element (direct or from a callback) → that element (returned **explicitly**, bypassing the
+     *   "focus moved elsewhere" guard).
+     */
+    private resolveReturnFocusTarget;
+    /**
+     * Base UI's `defaultInitialFocus`: on a **touch** open, focus the popup itself instead of its first
+     * tabbable control, so a soft keyboard (Android) does not pop up over the popup. Any other interaction
+     * returns `null`, keeping the focus scope's first-tabbable default. The popup is made programmatically
+     * focusable (`tabindex="-1"`) if it isn't already.
+     */
+    private defaultInitialFocus;
+    /**
+     * Manager-owned post-open fallback. Some popup types open from a trigger event that fired before the
+     * manager existed, and some policies resolve their final target only after a couple of renders. Re-run
+     * the initial-focus policy for a few animation frames while the popup is open so the target can settle.
+     */
+    private wireInitialFocusFallback;
+    private scheduleInitialFocusFallback;
+    private applyInitialFocusFallback;
+    /**
+     * Close-on-focus-out (ADR 0017 §3): a **non-modal** active popup closes when focus moves to a node
+     * unrelated to the floating tree — not the popup, its trigger(s), a focus guard, or an ancestor /
+     * descendant popup — and not during a pointer press (a drag must not close it). Mirrors Base UI's
+     * `FloatingFocusManager` `!modal` branch (`movedToUnrelatedNode`).
+     */
+    private wireCloseOnFocusOut;
+    /**
+     * The marker keep-set is intentionally narrow: the popup/focus host only. Own sibling roots such as a
+     * user backdrop are DOM-footprint bookkeeping, not marker keep-set members.
+     */
+    private avoidElements;
+    private isFloatingOpen;
+    /** Whether `relatedTarget` is inside the popup, its trigger(s), or an ancestor / descendant popup. */
+    private isRelatedTargetInside;
+    private contextContains;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFloatingFocusManager, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFloatingFocusManager, "[rdxFloatingFocusManager]", ["rdxFloatingFocusManager"], { "enabled": { "alias": "enabled"; "required": false; "isSignal": true; }; "modal": { "alias": "modal"; "required": false; "isSignal": true; }; "inert": { "alias": "inert"; "required": false; "isSignal": true; }; "initialFocus": { "alias": "initialFocus"; "required": false; "isSignal": true; }; "returnFocus": { "alias": "returnFocus"; "required": false; "isSignal": true; }; "closeOnFocusOut": { "alias": "closeOnFocusOut"; "required": false; "isSignal": true; }; }, { "focusOut": "focusOut"; }, never, never, true, [{ directive: typeof i1.RdxFocusScope; inputs: { "loop": "loop"; }; outputs: {}; }]>;
+}
+
+/** The neutral "outside the active floating layer" marker (Base UI `data-base-ui-inert`). */
+declare const RDX_FLOATING_MARKER = "data-rdx-floating-inert";
+
+export { RDX_FLOATING_FOCUS_MANAGER_CONFIG, RDX_FLOATING_MARKER, RdxFloatingFocusManager, getInteractionTypeFromEvent, provideFloatingFocusManagerConfig, resolveFocusTarget, resolveInitialFocus, resolveReturnFocus };
+export type { RdxFloatingFocusManagerConfig, RdxFocusTarget, RdxInitialFocus, RdxInteractionType, RdxReturnFocus };

package/types/radix-ng-primitives-focus-scope.d.ts

@@ -3,6 +3,49 @@ import { WritableSignal, Signal, InjectionToken, Provider } from '@angular/core'
 import * as _radix_ng_primitives_core from '@radix-ng/primitives/core';
 import { BooleanInput } from '@radix-ng/primitives/core';
 
+/** Marks the leading / trailing focus-guard spans (Base UI `data-base-ui-focus-guard`). */
+declare const FOCUS_GUARD_ATTR = "data-rdx-focus-guard";
+/** Visually-hidden, off-flow style for a focus guard / `aria-owns` anchor (Base UI `visuallyHidden`). */
+declare const FOCUS_GUARD_STYLE: Partial<CSSStyleDeclaration>;
+/**
+ * Creates a visually-hidden, **tabbable** focus-guard `<span>` — the Angular counterpart of Base UI's
+ * `FocusGuard`. The portal-focus bridge places one before and one after the portal content so a Tab into
+ * (or out of) the portal lands on a guard, which then redirects focus to the right boundary.
+ */
+declare function createFocusGuard(ownerDocument: Document): HTMLSpanElement;
+/**
+ * Creates a visually-hidden `<span aria-owns="…">` that links the portal node into the trigger's tab /
+ * AT order (Base UI's single `aria-owns` anchor). The manager places it next to the trigger.
+ */
+declare function createAriaOwnsAnchor(ownerDocument: Document, portalId: string): HTMLSpanElement;
+/**
+ * Makes every tabbable descendant of `container` **non-tabbable** (`tabindex="-1"`), saving each one's
+ * original tabindex so {@link enableFocusInside} can restore it. Base UI `disableFocusInside`: a
+ * non-modal portal keeps its content untabbable until focus is actually inside it, so a Tab from the
+ * trigger steps onto the guard instead of jumping into the content.
+ */
+declare function disableFocusInside(container: HTMLElement): void;
+/** Restores the tabbability that {@link disableFocusInside} suspended. Base UI `enableFocusInside`. */
+declare function enableFocusInside(container: HTMLElement): void;
+/**
+ * Whether a focus event crossed the `container` boundary — its `relatedTarget` (the other side of the
+ * focus move) is `null` or outside `container` (Base UI `isOutsideEvent`). Shadow-DOM-aware via
+ * {@link composedContains}.
+ */
+declare function isOutsideEvent(event: FocusEvent, container: Element): boolean;
+/**
+ * The portal-focus bridge's **tabbability toggle** (Base UI `FloatingPortal` capture-phase `onFocus`).
+ * While `portalNode` is mounted (and `enabled`), it makes the portal content tabbable **only when focus
+ * is inside it**: focus entering from outside re-enables tabbability, focus leaving to outside disables
+ * it again. Listens on the **capture** phase so it settles before the focus manager's guards react.
+ *
+ * Must be called in an injection context. The initial disable-on-mount and the guard-span placement are
+ * the manager's responsibility (Phase 1b); this owns only the dynamic in/out toggle.
+ */
+declare function useFocusGuardsTabbability(portalNode: () => HTMLElement | null, options?: {
+    enabled?: () => boolean;
+}): void;
+
 interface FocusScopeAPI {
     paused: WritableSignal<boolean>;
     pause(): void;
@@ -23,6 +66,8 @@ declare class RdxFocusScope {
     private readonly destroyRef;
     private readonly elementRef;
     private readonly config;
+    /** The host's owner `Document` — all focus listeners / reads are scoped here, never global `document`. */
+    private readonly ownerDocument;
     /**
      * When `true`, tabbing from last item will focus first tabbable
      * and shift+tab from first item will focus last tababble.
@@ -59,6 +104,15 @@ declare class RdxFocusScope {
     readonly focusScope: FocusScopeAPI;
     private alive;
     constructor();
+    /**
+     * Whether the interaction that unmounted this scope already moved focus to a legitimate element
+     * **outside** it — e.g. an outside press onto an interactive control in a non-modal layer (ADR 0017
+     * §2, finding #3). Returning focus to the previously-focused element would then *steal* it back from
+     * what the user just acted on. Focus that fell to `<body>` / `null` (a backdrop press, Escape, or the
+     * focused element being removed) is **not** "moved" — return focus normally so keyboard users land
+     * back on the trigger. The page never scroll-jumps either way: {@link focus} uses `preventScroll`.
+     */
+    private shouldPreserveMovedFocus;
     handleKeyDown(event: KeyboardEvent): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFocusScope, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFocusScope, "[rdxFocusScope]", never, { "loop": { "alias": "loop"; "required": false; "isSignal": true; }; "trapped": { "alias": "trapped"; "required": false; "isSignal": true; }; }, { "mountAutoFocus": "mountAutoFocus"; "unmountAutoFocus": "unmountAutoFocus"; }, never, never, true, never>;
@@ -66,9 +120,86 @@ declare class RdxFocusScope {
 
 type RdxFocusScopeConfig = {
     trapped: Signal<boolean>;
+    /**
+     * Optional return-focus policy override (ADR 0017 `returnFocus`), resolved by an enclosing
+     * {@link RdxFloatingFocusManager} at **unmount time**. The focus scope owns the *timing* (its queued
+     * post-unmount focus); this lets the manager own the *target*:
+     * - `false` → do **not** return focus;
+     * - an `HTMLElement` → return focus there **explicitly** (bypasses the moved-focus guard, matching
+     *   Base UI's `hasExplicitReturnFocus`);
+     * - `undefined` → default behavior (return to the element focused before mount, with the guard).
+     */
+    returnFocus?: () => HTMLElement | false | undefined;
 };
 declare const RdxFocusScopeConfigToken: InjectionToken<RdxFocusScopeConfig>;
 declare function provideRdxFocusScopeConfig(factory: () => RdxFocusScopeConfig): Provider;
 
-export { RdxFocusScope, RdxFocusScopeConfigToken, injectFocusScopeContext, provideFocusScopeContext, provideRdxFocusScopeConfig };
+declare const AUTOFOCUS_ON_MOUNT = "focusScope.autoFocusOnMount";
+declare const AUTOFOCUS_ON_UNMOUNT = "focusScope.autoFocusOnUnmount";
+declare const EVENT_OPTIONS: {
+    bubbles: boolean;
+    cancelable: boolean;
+};
+type FocusableTarget = HTMLElement | {
+    focus: () => void;
+};
+/**
+ * The real target of a (possibly retargeted) event, piercing shadow boundaries via `composedPath()`.
+ * Falls back to `event.target` when `composedPath` is unavailable.
+ */
+declare function getEventTarget(event: Event): EventTarget | null;
+/**
+ * Shadow-DOM-aware containment: whether `node` is `container` or lives inside it, crossing shadow roots
+ * via their `host` (unlike `Node.contains`, which stops at a shadow boundary).
+ */
+declare function composedContains(container: Node, node: Node | null): boolean;
+/**
+ * Attempts focusing the first element in a list of candidates.
+ * Stops when focus has actually moved.
+ */
+declare function focusFirst(candidates: HTMLElement[], { select }?: {
+    select?: boolean | undefined;
+}): true | undefined;
+/**
+ * Returns a list of potential tabbable candidates.
+ *
+ * NOTE: This is only a close approximation. For example it doesn't take into account cases like when
+ * elements are not visible. This cannot be worked out easily by just reading a property, but rather
+ * necessitate runtime knowledge (computed styles, etc). We deal with these cases separately.
+ *
+ * See: https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker
+ * Credit: https://github.com/discord/focus-layers/blob/master/src/util/wrapFocus.tsx#L1
+ */
+declare function getTabbableCandidates(container: HTMLElement): HTMLElement[];
+declare function isHidden(node: HTMLElement, { upTo }: {
+    upTo?: HTMLElement;
+}): boolean;
+/**
+ * Returns the first visible element in a list.
+ * NOTE: Only checks visibility up to the `container`.
+ */
+declare function findVisible(elements: HTMLElement[], container: HTMLElement): HTMLElement | undefined;
+/**
+ * Returns the first and last tabbable elements inside a container.
+ */
+declare function getTabbableEdges(container: HTMLElement): readonly [HTMLElement | undefined, HTMLElement | undefined];
+/**
+ * The next tabbable in the document after the current focus (Base UI `getNextTabbable`) — used by the
+ * portal-focus bridge's trailing guard to step focus past the popup. Falls back to `reference`.
+ */
+declare function getNextTabbable(reference: Element | null): HTMLElement | null;
+/** The previous tabbable in the document before the current focus (Base UI `getPreviousTabbable`). */
+declare function getPreviousTabbable(reference: Element | null): HTMLElement | null;
+/** The tabbable immediately after `reference` in the document, wrapping (Base UI `getTabbableAfterElement`). */
+declare function getTabbableAfterElement(reference: Element | null): HTMLElement | null;
+/** The tabbable immediately before `reference` in the document, wrapping (Base UI `getTabbableBeforeElement`). */
+declare function getTabbableBeforeElement(reference: Element | null): HTMLElement | null;
+declare function isSelectableInput(element: any): element is FocusableTarget & {
+    select: () => void;
+};
+declare function focus(element?: FocusableTarget | null, { select }?: {
+    select?: boolean | undefined;
+}): void;
+
+export { AUTOFOCUS_ON_MOUNT, AUTOFOCUS_ON_UNMOUNT, EVENT_OPTIONS, FOCUS_GUARD_ATTR, FOCUS_GUARD_STYLE, RdxFocusScope, RdxFocusScopeConfigToken, composedContains, createAriaOwnsAnchor, createFocusGuard, disableFocusInside, enableFocusInside, findVisible, focus, focusFirst, getEventTarget, getNextTabbable, getPreviousTabbable, getTabbableAfterElement, getTabbableBeforeElement, getTabbableCandidates, getTabbableEdges, injectFocusScopeContext, isHidden, isOutsideEvent, isSelectableInput, provideFocusScopeContext, provideRdxFocusScopeConfig, useFocusGuardsTabbability };
 export type { FocusScopeContext, RdxFocusScopeConfig };