@agorapulse/ui-components 22.0.30 → 22.0.32

package/types/agorapulse-ui-components-floating.d.ts

@@ -0,0 +1,167 @@
+import { Side, Placement, Middleware } from '@floating-ui/dom';
+import * as _angular_core from '@angular/core';
+import { TemplateRef, Type, ComponentRef } from '@angular/core';
+import { OverlayRef } from '@angular/cdk/overlay';
+
+/**
+ * The twelve placements, aliased from Floating UI rather than redeclared. The trade-off: this puts
+ * `@floating-ui/dom` in our **public** type surface, so its next major would move our types too.
+ *
+ * There is no `'auto'`; an unset placement is derived by `defaultPlacementFor`.
+ */
+type FloatingPlacement = Placement;
+/** The four opening sides. Floating UI's `Side`, for the same reason. */
+type FloatingSide = Side;
+declare function sideOf(placement: FloatingPlacement): FloatingSide;
+declare function isVertical(placement: FloatingPlacement): boolean;
+
+/** A minimal rect — neither `DOMRect` nor any DOM dependency, so the pure units stay pure. */
+interface FloatingRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+/** What the panel connects to. */
+type FloatingAnchorMode = 'trigger' | 'pointer' | 'pointer-free';
+/**
+ * The placement derived when `placement` is unset. Reads the **configured** anchor mode, not the
+ * resolved one: a keyboard opening falls back to the trigger, and if the alignment followed, the
+ * component would change shape between mouse and keyboard.
+ */
+declare function defaultPlacementFor(anchor: FloatingAnchorMode): FloatingPlacement;
+/**
+ * `'pointer'` is a hybrid whose zero dimension is the **cross-axis** one; a lateral panel built
+ * from a fully point-like anchor would sit inside its own trigger. `'pointer-free'` is the point
+ * itself. Both fall back to the trigger when there is no click.
+ *
+ * @param vertical The opening axis. Invariant under the flip, which only swaps the main axis.
+ */
+declare function resolveAnchorRect(anchor: FloatingAnchorMode, triggerRect: FloatingRect, vertical: boolean, clickPoint?: {
+    x: number;
+    y: number;
+}): FloatingRect;
+/** A point expressed as a proportion of the trigger, on each axis. */
+interface ClickRatio {
+    x: number;
+    y: number;
+}
+
+interface ApArrowOptions {
+    /** What the tip aims at — see {@link resolveArrowOffset}. */
+    targetMode: 'anchor' | 'pointer';
+    /** The configured anchor mode. Decides how the click is recovered from the reference rect. */
+    anchorMode: FloatingAnchorMode;
+    /** The clicked point as a proportion of the trigger. Absent on a keyboard opening. */
+    clickRatio?: ClickRatio;
+}
+/** What the middleware leaves in `middlewareData.apArrow`. */
+interface ApArrowData {
+    /** The arrow's offset from the panel's start edge, along the cross axis. */
+    offset: number;
+    /** The side of the panel the arrow sits on — read from the **resolved** placement. */
+    side: FloatingSide;
+    /** The panel covers its **anchor** — in the POI mode the trigger may be covered on purpose. */
+    hidden: boolean;
+}
+/**
+ * Replaces Floating UI's `arrow`, which aims at the centre of the *reference*: on a 280px trigger
+ * with a 100px panel that centre is out of reach and the tip clamps to a corner at 80, where the
+ * intersection's centre is 42 (plate 22). {@link resolveArrowOffset} holds the rule.
+ *
+ * Must run last, after `shift`, since it reads the panel's final position.
+ */
+declare function apArrow(options: ApArrowOptions): Middleware;
+
+interface ArrowOffsetInput {
+    /** The side of the panel the arrow sits on — the **resolved** side, not the wanted one. */
+    side: FloatingSide;
+    anchorRect: FloatingRect;
+    floatingRect: FloatingRect;
+    /** `'anchor'` aims at the anchor ∩ panel intersection's centre, `'pointer'` at the click. */
+    targetMode: 'anchor' | 'pointer';
+    clickPoint?: {
+        x: number;
+        y: number;
+    };
+}
+interface ArrowOffsetResult {
+    /** The arrow's offset from the panel's start edge, along the cross axis. */
+    offset: number;
+    clamped: boolean;
+    /** The click fell outside the panel, so the intersection centre was used instead. */
+    fellBack: boolean;
+    /** The panel is too narrow: the clamp range inverts and the arrow is centred outright. */
+    centered: boolean;
+}
+/**
+ * Three rules, in order:
+ *
+ * 1. Aim at the centre of the **anchor ∩ panel intersection**, never the anchor's own centre —
+ *    `apArrow` documents why this diverges from Floating UI.
+ * 2. In `'pointer'` mode, aim at the click, falling back to rule 1 — discontinuously, as the
+ *    plates specify — when the click lands outside the panel.
+ * 3. Clamp to leave the corner radius clear. Below `arrow + 2 × radius` = 24px the range inverts,
+ *    and the arrow is centred outright.
+ *
+ * The flags say which rule applied, so the generated plate cases can assert the path taken.
+ */
+declare function resolveArrowOffset(input: ArrowOffsetInput): ArrowOffsetResult;
+
+/**
+ * The panel edge an arrow sits on: a panel placed `bottom` hangs below its anchor, so its tip is on
+ * its top edge. Give it the **resolved** placement, or a flipped panel grows its arrow away.
+ */
+declare function arrowSideFor(placement: FloatingPlacement): FloatingSide;
+/** Ready-to-use CSS values, `'auto'` for the sides that do not apply. */
+interface ArrowPlacement {
+    top: string;
+    right: string;
+    bottom: string;
+    left: string;
+    rotate: string;
+}
+/**
+ * The insets and rotation `_floating-arrow.scss` reads off the pane. The rotation-centre
+ * compensation lives here rather than in the stylesheet, where it could not be tested.
+ *
+ * @param side The panel edge the arrow sits on — the **resolved** side, not the wanted one.
+ * @param offset The offset from the panel's start edge, along the cross axis.
+ */
+declare function resolveArrowPlacement(side: FloatingSide, offset: number): ArrowPlacement;
+
+interface FloatingOverlayConfig {
+    /** Unset means derived from `anchor`. There is no `'auto'` value. */
+    placement?: FloatingPlacement;
+    anchor?: FloatingAnchorMode;
+    arrow?: boolean;
+    arrowTarget?: 'anchor' | 'pointer';
+    showBackdrop?: boolean;
+    panelClass?: string | string[];
+    /** Fallback for the two handlers below. */
+    onClose?: () => void;
+    /** Escape, which always closes. Unset means `onClose`. */
+    onEscape?: () => void;
+    /** Outside click. Unset means `onClose`. */
+    onOutsideClick?: () => void;
+    /**
+     * Elements that carry their own toggle, so a click on them is not "the outside". Read on every
+     * event, since the list may change while the floating is open.
+     *
+     * Without this, the CDK's capture-phase dispatcher closes before a secondary trigger sees the
+     * click, that trigger reopens, and the toggle never closes again.
+     */
+    additionalTriggers?: () => readonly HTMLElement[];
+}
+declare function createFloatingOverlay(): {
+    readonly overlayRef: OverlayRef | null;
+    isOpen: _angular_core.Signal<boolean>;
+    open: <T = unknown>(content: TemplateRef<unknown> | Type<T>, triggerElement?: HTMLElement, config?: FloatingOverlayConfig, event?: MouseEvent) => ComponentRef<T> | null;
+    close: () => void;
+    updatePosition: () => void;
+};
+type FloatingOverlayInstance = ReturnType<typeof createFloatingOverlay>;
+
+export { apArrow, arrowSideFor, createFloatingOverlay, defaultPlacementFor, isVertical, resolveAnchorRect, resolveArrowOffset, resolveArrowPlacement, sideOf };
+export type { ApArrowData, ApArrowOptions, ArrowOffsetInput, ArrowOffsetResult, ArrowPlacement, FloatingAnchorMode, FloatingOverlayConfig, FloatingOverlayInstance, FloatingPlacement, FloatingRect, FloatingSide };