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

package/types/radix-ng-primitives-drawer.d.ts

@@ -13,6 +13,8 @@ interface RdxDrawerRegistration {
     id: string;
     /** The drawer popup's measured size (px) along its dismiss axis. */
     height: Signal<number>;
+    /** 0..1 live dismiss progress of this drawer. */
+    swipeProgress: Signal<number>;
 }
 /**
  * App-level coordinator that tracks every open drawer so background content can react to them
@@ -30,6 +32,8 @@ declare class RdxDrawerProvider {
     readonly frontmost: Signal<RdxDrawerRegistration | null>;
     /** The frontmost drawer's measured size (px), or `0` when none is open. */
     readonly frontmostHeight: Signal<number>;
+    /** The frontmost drawer's live dismiss progress, or `0` when none is open. */
+    readonly swipeProgress: Signal<number>;
     /** Register an open drawer; returns a disposer that removes it. */
     register(registration: RdxDrawerRegistration): () => void;
     static ɵfac: i0.ɵɵFactoryDeclaration<RdxDrawerProvider, never>;
@@ -62,6 +66,10 @@ type RdxDrawerRelease = {
 interface RdxDrawerSwipeConfig {
     /** The popup element the gesture lives on (CSS variables + data attributes are written here). */
     element: () => HTMLElement;
+    /** Gesture boundary used to discover scrollable ancestors around the popup. */
+    boundary?: () => HTMLElement;
+    /** Visible size along the dismiss axis, used to normalize live swipe progress. */
+    size?: () => number;
     /** Active swipe direction. */
     direction: Signal<RdxDrawerSwipeDirection>;
     /** Whether the gesture is currently armed (typically `open`). */
@@ -109,8 +117,8 @@ declare function useDrawerSwipe(config: RdxDrawerSwipeConfig): void;
  * - a string — `'148px'` (pixels), `'30rem'` (root-em), `'40%'` (fraction of size), or a bare number
  *   as above.
  *
- * Order the `snapPoints` array ascending by openness; the last entry is treated as "most open" and
- * is the default the drawer opens to when `defaultSnapPoint` is not set.
+ * Order the `snapPoints` array ascending by openness; the first entry is the default the drawer opens
+ * to when `defaultSnapPoint` is not set.
  */
 type RdxDrawerSnapPoint = number | string;
 /**
@@ -166,6 +174,12 @@ interface RdxDrawerRootContext {
     swipeProgress: Signal<number>;
     /** Reports gesture progress from the popup's swipe engine. */
     setSwipeProgress: (value: number) => void;
+    /** Whether the drawer is currently being revealed from a SwipeArea. */
+    openingSwipeActive: Signal<boolean>;
+    /** Pointer travel (px) inward from the SwipeArea while revealing the drawer. */
+    openingSwipeDistance: Signal<number>;
+    /** Starts or updates the SwipeArea reveal gesture. */
+    setOpeningSwipe: (active: boolean, distance: number) => void;
     /** Configured snap points (empty when the drawer has none). */
     snapPoints: Signal<readonly RdxDrawerSnapPoint[]>;
     /** Whether the drawer rests at discrete snap points. */
@@ -208,12 +222,12 @@ declare class RdxDrawerRoot {
     readonly swipeDirection: i0.InputSignal<RdxDrawerSwipeDirection>;
     /**
      * Resting positions the drawer snaps to along the dismiss axis. Order ascending by openness; the
-     * last entry is the default the drawer opens to. Omit for a plain open/closed drawer.
+     * first entry is the default the drawer opens to. Omit for a plain open/closed drawer.
      */
     readonly snapPoints: i0.InputSignal<readonly RdxDrawerSnapPoint[] | undefined>;
     /** The active snap point (controlled / uncontrolled with `[(snapPoint)]`). */
     readonly snapPoint: i0.ModelSignal<RdxDrawerSnapPoint | null>;
-    /** The snap point the drawer opens to when uncontrolled; defaults to the most open point. */
+    /** The snap point the drawer opens to when uncontrolled; defaults to the first point. */
     readonly defaultSnapPoint: i0.InputSignal<RdxDrawerSnapPoint | undefined>;
     /** Step at most one snap point per release instead of letting velocity skip points. */
     readonly snapToSequentialPoints: i0.InputSignalWithTransform<boolean, BooleanInput>;
@@ -221,6 +235,9 @@ declare class RdxDrawerRoot {
     readonly onSnapPointChange: i0.OutputEmitterRef<RdxDrawerSnapPoint>;
     /** 0..1 progress of the active dismiss gesture, written by the popup's swipe engine. */
     readonly swipeProgress: i0.WritableSignal<number>;
+    /** Live SwipeArea reveal state; the popup converts distance into its measured-axis movement. */
+    readonly openingSwipeActive: i0.WritableSignal<boolean>;
+    readonly openingSwipeDistance: i0.WritableSignal<number>;
     readonly normalizedSnapPoints: Signal<readonly RdxDrawerSnapPoint[]>;
     readonly hasSnapPoints: Signal<boolean>;
     /** Whether a drawer nested inside this one is open (reuses the dialog's nesting detection). */
@@ -252,41 +269,47 @@ declare class RdxDrawerTrigger {
 /**
  * An off-canvas region (typically pinned to a screen edge) that opens the drawer when swiped inward.
  *
- * Phase 1 opens on a threshold crossing rather than following the pointer live (the popup is not
- * mounted while closed); the live-follow open will land with snap points. Shares the drawer's
- * pointer-drag lifecycle so capture/cancel handling stays consistent with the popup gesture.
+ * Opens the drawer at the start of a drag so its popup can follow the pointer live. Releasing past
+ * the threshold settles open; releasing before it or cancelling animates the drawer back out.
  */
 declare class RdxDrawerSwipeArea {
     private readonly drawerContext;
     private readonly dialogContext;
-    /** Direction the swipe area opens from; defaults to the root's `swipeDirection`. */
+    /** Direction the opening gesture travels; defaults to the opposite of the root's dismiss direction. */
     readonly swipeDirection: i0.InputSignal<RdxDrawerSwipeDirection | undefined>;
     /** Whether the swipe area should ignore user interaction. */
     readonly disabled: i0.InputSignalWithTransform<boolean, BooleanInput>;
     protected readonly isOpen: i0.Signal<boolean>;
     protected readonly direction: i0.Signal<RdxDrawerSwipeDirection>;
+    protected readonly resolvedTouchAction: i0.Signal<"pan-y" | "pan-x">;
     protected readonly swiping: i0.WritableSignal<boolean>;
     private startX;
     private startY;
+    private distance;
     constructor();
     static ɵfac: i0.ɵɵFactoryDeclaration<RdxDrawerSwipeArea, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<RdxDrawerSwipeArea, "[rdxDrawerSwipeArea]", ["rdxDrawerSwipeArea"], { "swipeDirection": { "alias": "swipeDirection"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
- * Mounts the portal while the drawer is open and waits for CSS exit keyframes before unmounting.
+ * Structural directive that teleports the drawer content (backdrop + popup) into a container (default
+ * `document.body`) while the drawer is open, keeping it mounted until its CSS exit `@keyframes`
+ * finish. It composes the structural {@link RdxDialogPortal}, inheriting the dialog presence context.
+ *
+ * Use the explicit `<ng-template rdxDrawerPortal>` form; pass `[container]` for a custom target.
  */
-declare class RdxDrawerPortalPresence {
-    static ɵfac: i0.ɵɵFactoryDeclaration<RdxDrawerPortalPresence, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<RdxDrawerPortalPresence, "ng-template[rdxDrawerPortalPresence]", never, {}, {}, never, never, true, [{ directive: typeof i1.RdxDialogPortalPresence; inputs: {}; outputs: {}; }]>;
+declare class RdxDrawerPortal {
+    static ɵfac: i0.ɵɵFactoryDeclaration<RdxDrawerPortal, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RdxDrawerPortal, "ng-template[rdxDrawerPortal]", ["rdxDrawerPortal"], {}, {}, never, never, true, [{ directive: typeof i1.RdxDialogPortal; inputs: { "container": "container"; }; outputs: {}; }]>;
 }
-
 /**
- * Moves the drawer to a different part of the DOM. Defaults to `document.body`.
+ * Dev-mode guard: `rdxDrawerPortal` is now structural, so the old `<div rdxDrawerPortal>` markup would
+ * silently stop portaling — fail loudly instead.
  */
-declare class RdxDrawerPortal {
-    static ɵfac: i0.ɵɵFactoryDeclaration<RdxDrawerPortal, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<RdxDrawerPortal, "[rdxDrawerPortal]", ["rdxDrawerPortal"], {}, {}, never, never, true, [{ directive: typeof i1.RdxDialogPortal; inputs: { "container": "container"; }; outputs: {}; }]>;
+declare class RdxDrawerPortalMisuseGuard {
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<RdxDrawerPortalMisuseGuard, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<RdxDrawerPortalMisuseGuard, "[rdxDrawerPortal]:not(ng-template)", never, {}, {}, never, never, true, never>;
 }
 
 /**
@@ -336,6 +359,9 @@ declare class RdxDrawerPopup {
     protected readonly frontmostHeightPx: i0.Signal<string | null>;
     constructor();
     private axisSize;
+    private axisElementSize;
+    private swipeBoundary;
+    private visibleAxisSize;
     private resolveRelease;
     static ɵfac: i0.ɵɵFactoryDeclaration<RdxDrawerPopup, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<RdxDrawerPopup, "[rdxDrawerPopup]", ["rdxDrawerPopup"], {}, {}, never, never, true, [{ directive: typeof i1.RdxDialogPopup; inputs: {}; outputs: { "escapeKeyDown": "escapeKeyDown"; "pointerDownOutside": "pointerDownOutside"; "focusOutside": "focusOutside"; "interactOutside": "interactOutside"; "openAutoFocus": "openAutoFocus"; "closeAutoFocus": "closeAutoFocus"; }; }]>;
@@ -384,6 +410,7 @@ declare class RdxDrawerClose {
  * Reads the nearest {@link RdxDrawerProvider} and exposes styling hooks; the visual transform is
  * consumer CSS (headless):
  * - `[data-active]` — present while at least one drawer is open.
+ * - `--drawer-swipe-progress` — 0..1 live dismiss progress of the frontmost drawer.
  * - `--nested-drawers` — the number of open drawers.
  * - `--drawer-frontmost-height` — the frontmost drawer's measured size, in pixels.
  */
@@ -396,9 +423,9 @@ declare class RdxDrawerIndent {
 /**
  * The page background layer that scales/indents while any drawer is open.
  *
- * Behaves like {@link RdxDrawerIndent} (same `[data-active]` / `--nested-drawers` /
- * `--drawer-frontmost-height` contract); kept as a distinct part so the page backdrop and the
- * indented content can be styled independently, mirroring Base UI.
+ * Behaves like {@link RdxDrawerIndent} (same `[data-active]` / `--drawer-swipe-progress` /
+ * `--nested-drawers` / `--drawer-frontmost-height` contract); kept as a distinct part so the page
+ * backdrop and the indented content can be styled independently, mirroring Base UI.
  */
 declare class RdxDrawerIndentBackground {
     protected readonly provider: RdxDrawerProvider | null;
@@ -418,9 +445,9 @@ declare function createRdxDrawerHandle<Payload = unknown>(): RdxDrawerHandle<Pay
 declare const drawerImports: (typeof RdxDrawerProviderDirective)[];
 declare class RdxDrawerModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<RdxDrawerModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<RdxDrawerModule, never, [typeof RdxDrawerProviderDirective, typeof RdxDrawerRoot, typeof RdxDrawerTrigger, typeof RdxDrawerSwipeArea, typeof RdxDrawerPortalPresence, typeof RdxDrawerPortal, typeof RdxDrawerBackdrop, typeof RdxDrawerViewport, typeof RdxDrawerPopup, typeof RdxDrawerContent, typeof RdxDrawerTitle, typeof RdxDrawerDescription, typeof RdxDrawerClose, typeof RdxDrawerIndent, typeof RdxDrawerIndentBackground], [typeof RdxDrawerProviderDirective, typeof RdxDrawerRoot, typeof RdxDrawerTrigger, typeof RdxDrawerSwipeArea, typeof RdxDrawerPortalPresence, typeof RdxDrawerPortal, typeof RdxDrawerBackdrop, typeof RdxDrawerViewport, typeof RdxDrawerPopup, typeof RdxDrawerContent, typeof RdxDrawerTitle, typeof RdxDrawerDescription, typeof RdxDrawerClose, typeof RdxDrawerIndent, typeof RdxDrawerIndentBackground]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<RdxDrawerModule, never, [typeof RdxDrawerProviderDirective, typeof RdxDrawerRoot, typeof RdxDrawerTrigger, typeof RdxDrawerSwipeArea, typeof RdxDrawerPortal, typeof RdxDrawerPortalMisuseGuard, typeof RdxDrawerBackdrop, typeof RdxDrawerViewport, typeof RdxDrawerPopup, typeof RdxDrawerContent, typeof RdxDrawerTitle, typeof RdxDrawerDescription, typeof RdxDrawerClose, typeof RdxDrawerIndent, typeof RdxDrawerIndentBackground], [typeof RdxDrawerProviderDirective, typeof RdxDrawerRoot, typeof RdxDrawerTrigger, typeof RdxDrawerSwipeArea, typeof RdxDrawerPortal, typeof RdxDrawerPortalMisuseGuard, typeof RdxDrawerBackdrop, typeof RdxDrawerViewport, typeof RdxDrawerPopup, typeof RdxDrawerContent, typeof RdxDrawerTitle, typeof RdxDrawerDescription, typeof RdxDrawerClose, typeof RdxDrawerIndent, typeof RdxDrawerIndentBackground]>;
     static ɵinj: i0.ɵɵInjectorDeclaration<RdxDrawerModule>;
 }
 
-export { RdxDrawerBackdrop, RdxDrawerClose, RdxDrawerContent, RdxDrawerDescription, RdxDrawerHandle, RdxDrawerIndent, RdxDrawerIndentBackground, RdxDrawerModule, RdxDrawerPopup, RdxDrawerPortal, RdxDrawerPortalPresence, RdxDrawerProvider, RdxDrawerProviderDirective, RdxDrawerRoot, RdxDrawerSwipeArea, RdxDrawerTitle, RdxDrawerTrigger, RdxDrawerViewport, buildSnapEntries, createRdxDrawerHandle, dismissUnitVector, drawerImports, injectRdxDrawerRootContext, provideRdxDrawerProvider, provideRdxDrawerRootContext, resolveSnapTarget, snapPointReveal, useDrawerSwipe };
+export { RdxDrawerBackdrop, RdxDrawerClose, RdxDrawerContent, RdxDrawerDescription, RdxDrawerHandle, RdxDrawerIndent, RdxDrawerIndentBackground, RdxDrawerModule, RdxDrawerPopup, RdxDrawerPortal, RdxDrawerPortalMisuseGuard, RdxDrawerProvider, RdxDrawerProviderDirective, RdxDrawerRoot, RdxDrawerSwipeArea, RdxDrawerTitle, RdxDrawerTrigger, RdxDrawerViewport, buildSnapEntries, createRdxDrawerHandle, dismissUnitVector, drawerImports, injectRdxDrawerRootContext, provideRdxDrawerProvider, provideRdxDrawerRootContext, resolveSnapTarget, snapPointReveal, useDrawerSwipe };
 export type { RdxDrawerRegistration, RdxDrawerRelease, RdxDrawerRootContext, RdxDrawerSnapEntry, RdxDrawerSnapPoint, RdxDrawerSnapResolveOptions, RdxDrawerSnapTarget, RdxDrawerSwipeConfig, RdxDrawerSwipeDirection };

package/types/radix-ng-primitives-field.d.ts

@@ -188,6 +188,7 @@ declare class RdxFieldLabel {
      */
     readonly id: _angular_core.InputSignal<string>;
     readonly htmlFor: () => string;
+    constructor();
     protected readonly dataAttr: (value: boolean) => "" | undefined;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<RdxFieldLabel, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<RdxFieldLabel, "[rdxFieldLabel]", ["rdxFieldLabel"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;

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 };