forty-cdk 0.2.0 → 0.3.0

package/types/forty-cdk-context-menu.d.ts

@@ -0,0 +1,313 @@
+import * as forty_cdk_core from 'forty-cdk/core';
+import { MenuActivationModality, MenuOverlayHost, ForMenuContext, FloatingSide, FloatingAlign, WritingDirection, VetoableNativeEvent, VetoableEvent } from 'forty-cdk/core';
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Signal, Provider } from '@angular/core';
+import { ReferenceElement } from '@floating-ui/dom';
+
+/**
+ * Coordination contract `[forContextMenuTrigger]` resolves from its enclosing
+ * `[forContextMenu]` root. It exposes exactly the slice of the root the
+ * trigger consumes: open / disabled state, trigger registration (for
+ * return-focus on close), the pointer / keyboard virtual-anchor setters, and
+ * the open entry point.
+ *
+ * `ForContextMenu` provides it via `useExisting`, so a subclassed root (the
+ * standard design-system wrapping pattern) only has to re-provide tokens —
+ * `FOR_MENU_CONTEXT` for items / content and `FOR_CONTEXT_MENU_CONTEXT` for
+ * the trigger — never a concrete-class alias.
+ */
+interface ForContextMenuContext {
+    /**
+     * Whether the menu is currently shown. Read-only at the contract level —
+     * the root backs it with its own `model<boolean>` and writes through its
+     * `openMenu` / `closeMenu` plumbing; the trigger only ever reads.
+     */
+    readonly open: Signal<boolean>;
+    /**
+     * When `true`, trigger activations are no-ops and the `contextmenu` event
+     * falls through to the native browser menu.
+     */
+    readonly disabled: Signal<boolean>;
+    /** Registers the trigger element so it receives return-focus on close. */
+    registerTrigger(el: HTMLElement): void;
+    /** Unregisters a previously registered trigger element. */
+    unregisterTrigger(el: HTMLElement): void;
+    /** Updates the virtual anchor to a 0×0 rect at (`x`, `y`) in viewport coordinates. */
+    setVirtualAnchor(x: number, y: number): void;
+    /**
+     * Updates the virtual anchor to a by-value snapshot of `rect`. Used by the
+     * keyboard activators (`Shift+F10`, the `ContextMenu` key) so the menu
+     * floats off the focused element instead of the pointer position.
+     */
+    setVirtualAnchorFromRect(rect: DOMRect): void;
+    /**
+     * Opens the menu and sends focus to its first or last enabled item
+     * (default `'first'`). Honours `disabled`. `modality` (default
+     * `'keyboard'`) records how the open was activated: a `'pointer'` open
+     * (right-click / long-press) keeps the programmatic initial focus from
+     * reflecting `data-highlighted`, while a `'keyboard'` open (`Shift+F10`,
+     * the `ContextMenu` key) highlights the focused item.
+     */
+    openMenu(initialFocus?: 'first' | 'last', modality?: MenuActivationModality): void;
+}
+/**
+ * Token under which `[forContextMenu]` exposes the {@link ForContextMenuContext}
+ * surface to its `[forContextMenuTrigger]`. Subclassed roots re-provide it with
+ * `{ provide: FOR_CONTEXT_MENU_CONTEXT, useExisting: MySubclass }`.
+ */
+declare const FOR_CONTEXT_MENU_CONTEXT: InjectionToken<ForContextMenuContext>;
+
+/**
+ * Headless implementation of a right-click / `Shift+F10` menu (variant of
+ * the [WAI-ARIA Menu pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/)).
+ * Apply on a wrapper that contains a `[forContextMenuTrigger]` and an
+ * `@if`-mounted `[forMenuContent]`.
+ *
+ * The menu is positioned at the pointer location at the time of the
+ * `contextmenu` event — implemented via floating-ui's virtual element so
+ * placement / flip / shift middleware still apply normally. Selecting an
+ * item, Escape, or any outside interaction closes.
+ *
+ * ```html
+ * <div forContextMenu [(open)]="open">
+ *   <div forContextMenuTrigger class="region">Right-click here</div>
+ *   @if (open()) {
+ *     <div forMenuContent>…</div>
+ *   }
+ * </div>
+ * ```
+ *
+ * Most of the directive's body (id generation, item collection, typeahead,
+ * navigate / focus helpers, escape / outside-click veto plumbing) is owned
+ * by the shared `_internal/menu-overlay` helper. The directive contributes
+ * the inputs / outputs / model that make up the public surface, the
+ * pointer-driven `VirtualElement` anchor (`setVirtualAnchor` /
+ * `setVirtualAnchorFromRect`), and the contextmenu-specific dismissable
+ * semantics (no exemption — a left-click on the right-click region while
+ * the menu is open should close it).
+ */
+declare class ForContextMenu extends MenuOverlayHost implements ForMenuContext, ForContextMenuContext {
+    #private;
+    readonly open: _angular_core.ModelSignal<boolean>;
+    /**
+     * Side the menu is anchored to relative to the pointer. Defaults to
+     * `'bottom'`. Pair with `align` for the full positioning API.
+     *
+     * One of the floating-ui positioning inputs shared verbatim across the
+     * three menu roots — their non-seed defaults come from the single
+     * `MENU_POSITIONING_DEFAULTS` source and `menu-positioning-inputs.spec.ts`
+     * guards the three roots against drift.
+     */
+    readonly side: _angular_core.InputSignal<FloatingSide | undefined>;
+    /** Alignment along the chosen `side`. Defaults to `'start'`. */
+    readonly align: _angular_core.InputSignal<FloatingAlign | undefined>;
+    /**
+     * Gap (px) along the main axis. Default `0`. The default is read from
+     * `provideForContextMenuDefaults` for the surrounding scope.
+     */
+    readonly sideOffset: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Gap (px) along the cross axis. Default `0`. */
+    readonly alignOffset: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** When `true` (default), `flip` and `shift` keep the menu inside the viewport. */
+    readonly avoidCollisions: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Padding (px) applied uniformly to flip / shift / size. Default `8`.
+     * The default is read from `provideForContextMenuDefaults` for the
+     * surrounding scope.
+     */
+    readonly collisionPadding: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Padding (px) for the `arrow` middleware. Default `0`. */
+    readonly arrowPadding: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Stickiness behaviour for `shift`. Default `'partial'`. */
+    readonly sticky: _angular_core.InputSignal<false | "partial" | "always">;
+    /** When `true`, sets `data-detached=""` while the virtual anchor is off-screen. */
+    readonly hideWhenDetached: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When `true` (default), the menu is clipped until floating-ui resolves
+     * its first position, preventing a flash at the viewport corner. Set to
+     * `false` so a dramatic `animate.enter` plays from its first frame.
+     */
+    readonly clipUntilPositioned: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When `true` (default), arrow-key navigation wraps from the last enabled
+     * item back to the first (and vice versa). When `false`, navigation stops
+     * at the ends.
+     */
+    readonly loop: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Writing direction. Drives ArrowLeft / ArrowRight semantics on submenu
+     * triggers and items underneath this menu (in RTL, ArrowLeft opens a submenu
+     * and ArrowRight closes it back). When unset (default `null`), the inherited
+     * ambient direction is resolved from the nearest ancestor carrying a `dir`
+     * attribute (or `<html dir>`), defaulting to `'ltr'`. An explicit `[dir]`
+     * always wins, the resolved value is reflected to the host `dir` attribute,
+     * and it is inherited by descendant submenus.
+     */
+    readonly _dirInput: _angular_core.InputSignal<WritingDirection | null>;
+    readonly dir: _angular_core.Signal<WritingDirection>;
+    /**
+     * When true, the contextmenu event is allowed to fall through to the
+     * native browser menu. Useful for letting the OS-provided context menu
+     * appear on certain regions while keeping the directive mounted.
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** When true (default), Escape, pointer-down outside, and focus outside close the menu. */
+    readonly dismissible: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** When true (default), focus returns to the right-click target on close. */
+    readonly returnFocus: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Manual `aria-label` on `[forMenuContent]`. Use when there is no meaningful labelling element. */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * Fires when Escape is pressed while the menu is open, just before it
+     * closes. Call `preventDefault()` on the emitted veto to keep the menu
+     * open and suppress the Escape-driven close.
+     */
+    readonly escapeKeyDown: _angular_core.OutputEmitterRef<VetoableNativeEvent<KeyboardEvent>>;
+    /**
+     * Fires on a pointer-down outside the menu, just before it closes. Call
+     * `preventDefault()` on the veto to keep the menu open.
+     */
+    readonly pointerDownOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<PointerEvent>>;
+    /**
+     * Fires when focus moves outside the menu, just before it closes. Call
+     * `preventDefault()` on the veto to keep the menu open.
+     */
+    readonly focusOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<FocusEvent>>;
+    /**
+     * Composite outside-interaction channel: fires for either a
+     * pointer-down-outside or a focus-outside, just before the menu closes.
+     * Call `preventDefault()` on the veto to keep the menu open regardless of
+     * which interaction triggered it.
+     */
+    readonly interactOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<PointerEvent | FocusEvent>>;
+    /**
+     * Fires just before the menu sends focus to its first / last enabled
+     * item on mount. Call `preventDefault()` on the emitted veto to skip
+     * the imperative focus move.
+     */
+    readonly autoFocusOnOpen: _angular_core.OutputEmitterRef<VetoableEvent>;
+    /**
+     * Fires just before focus returns to the trigger on unmount. Call
+     * `preventDefault()` on the veto to suppress the return-focus.
+     */
+    readonly autoFocusOnClose: _angular_core.OutputEmitterRef<VetoableEvent>;
+    protected readonly _overlay: forty_cdk_core.MenuOverlay<forty_cdk_core.MenuItemHandle>;
+    readonly anchor: _angular_core.Signal<ReferenceElement | null>;
+    /**
+     * ContextMenu exempts nothing — a left-click on the right-click region
+     * while the menu is open should close it like any other outside click.
+     */
+    readonly dismissableExemptions: _angular_core.Signal<readonly HTMLElement[]>;
+    /** Top-level: no parent menu. */
+    readonly parentMenu: null;
+    /** Updates the virtual anchor to a 0×0 rect at (`x`, `y`) in viewport coordinates. */
+    setVirtualAnchor(x: number, y: number): void;
+    /**
+     * Updates the virtual anchor to a snapshot of `rect`. Used by the keyboard
+     * activators (`Shift+F10`, `ContextMenu` key) so the menu floats off the
+     * focused element instead of the pointer position. The rect is captured
+     * by value, so subsequent layout changes don't shift the anchor.
+     */
+    setVirtualAnchorFromRect(rect: DOMRect): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForContextMenu, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForContextMenu, "[forContextMenu]", ["forContextMenu"], { "open": { "alias": "open"; "required": false; "isSignal": true; }; "side": { "alias": "side"; "required": false; "isSignal": true; }; "align": { "alias": "align"; "required": false; "isSignal": true; }; "sideOffset": { "alias": "sideOffset"; "required": false; "isSignal": true; }; "alignOffset": { "alias": "alignOffset"; "required": false; "isSignal": true; }; "avoidCollisions": { "alias": "avoidCollisions"; "required": false; "isSignal": true; }; "collisionPadding": { "alias": "collisionPadding"; "required": false; "isSignal": true; }; "arrowPadding": { "alias": "arrowPadding"; "required": false; "isSignal": true; }; "sticky": { "alias": "sticky"; "required": false; "isSignal": true; }; "hideWhenDetached": { "alias": "hideWhenDetached"; "required": false; "isSignal": true; }; "clipUntilPositioned": { "alias": "clipUntilPositioned"; "required": false; "isSignal": true; }; "loop": { "alias": "loop"; "required": false; "isSignal": true; }; "_dirInput": { "alias": "dir"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "dismissible": { "alias": "dismissible"; "required": false; "isSignal": true; }; "returnFocus": { "alias": "returnFocus"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "open": "openChange"; "escapeKeyDown": "escapeKeyDown"; "pointerDownOutside": "pointerDownOutside"; "focusOutside": "focusOutside"; "interactOutside": "interactOutside"; "autoFocusOnOpen": "autoFocusOnOpen"; "autoFocusOnClose": "autoFocusOnClose"; }, never, never, true, never>;
+}
+
+/**
+ * Region that opens its parent `[forContextMenu]` on the `contextmenu` event
+ * (right-click / long-press on touch) and on the keyboard equivalents
+ * `Shift+F10` and the dedicated `ContextMenu` key. Pointer activations are
+ * anchored at the cursor; keyboard activations are anchored at the bounding
+ * rect of the focused element, so screen-reader / keyboard-only users get
+ * the menu next to whatever they're working on. The native context menu is
+ * suppressed via `event.preventDefault()`.
+ *
+ * Modality is detected by whether a `pointerdown` preceded the `contextmenu`
+ * event: a genuine right-click / long-press always has one, while the
+ * `contextmenu` some browsers synthesize for `Shift+F10` / the `ContextMenu`
+ * key does not. A pointer activation anchors at the cursor and skips
+ * `data-highlighted` on the initially focused item; a keyboard activation
+ * anchors at the focused element's rect and highlights it. The synthesized
+ * `contextmenu` that trails an already-handled keydown is swallowed so it
+ * cannot demote the rect anchor to a 0x0 point at the keyboard coordinates.
+ *
+ * Apply on any element. A default `tabindex="-1"` is host-bound so the
+ * trigger can receive programmatic focus and return-focus works out of the
+ * box on close — no consumer setup required. The default is overridable:
+ * set your own `tabindex` (e.g. `tabindex="0"` to put the trigger in the
+ * Tab order) and it wins. The keyboard activators (`Shift+F10`, the
+ * `ContextMenu` key) need the trigger — or something inside it — focusable,
+ * which the default guarantees.
+ *
+ * The root is normally resolved via DI from the enclosing `[forContextMenu]`.
+ * When the trigger is declared inside an `ng-template` stamped into the root
+ * (e.g. via `ngTemplateOutlet`), DI resolves at the template's declaration
+ * site and misses the root — pass it explicitly through the selector input,
+ * `routerLink`-style: `[forContextMenuTrigger]="root"` with
+ * `#root="forContextMenu"`.
+ *
+ * Disabling merges the trigger's own `disabled` input OR the root's
+ * `disabled`. When disabled, only `data-disabled` is reflected as a styling /
+ * state hook. The trigger is a generic region with no interactive ARIA role,
+ * so it emits neither the native `disabled` attribute (which applies only to
+ * form controls) nor `aria-disabled` (which is meaningful only on an
+ * interactive role); the disabled behaviour is enforced by the in-handler
+ * guards, which let the native browser menu show through instead.
+ */
+declare class ForContextMenuTrigger {
+    #private;
+    /**
+     * Optional explicit reference to the `[forContextMenu]` root, named after
+     * the selector `routerLink`-style. The bare valueless attribute keeps
+     * resolving the enclosing root via DI; pass the root explicitly
+     * (`[forContextMenuTrigger]="root"`, with `#root="forContextMenu"`) when
+     * the trigger is declared in an `ng-template` stamped inside the root —
+     * DI resolves at the template's declaration site, so the enclosing root
+     * is invisible there. The empty string (what the valueless attribute
+     * yields) is treated as unset.
+     */
+    readonly forContextMenuTrigger: _angular_core.InputSignal<"" | ForContextMenuContext>;
+    protected readonly ctx: _angular_core.Signal<ForContextMenuContext>;
+    /** Disables this trigger only, in addition to the root's `disabled`. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether the trigger is disabled — its own `disabled` input OR the root's. */
+    readonly effectiveDisabled: _angular_core.Signal<boolean>;
+    constructor();
+    protected onPointerDown(): void;
+    protected onContextMenu(event: MouseEvent): void;
+    protected onKeyDown(event: KeyboardEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForContextMenuTrigger, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForContextMenuTrigger, "[forContextMenuTrigger]", ["forContextMenuTrigger"], { "forContextMenuTrigger": { "alias": "forContextMenuTrigger"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant context menus in the surrounding
+ * injector scope. Configure with `provideForContextMenuDefaults` either
+ * at the application root or in any component's `providers` array; partial
+ * overrides merge with the parent scope.
+ */
+interface ForContextMenuDefaults {
+    /**
+     * Distance (px) between the virtual anchor (pointer position) and the
+     * floating content along the resolved `side` axis. Defaults to `0`
+     * since context menus open at the cursor.
+     */
+    sideOffset: number;
+    /**
+     * Padding (px) added to the viewport edges for collision-aware
+     * positioning. Higher values keep the floating content further from
+     * the edge when `flip` / `shift` runs.
+     */
+    collisionPadding: number;
+}
+/** Token holding the resolved context-menu defaults for the current scope. */
+declare const FOR_CONTEXT_MENU_DEFAULTS: _angular_core.InjectionToken<ForContextMenuDefaults>;
+/**
+ * Configures forty-cdk context-menu defaults for this injector scope.
+ * Partial overrides inherit unspecified keys from the parent scope (or
+ * library defaults at the root).
+ */
+declare function provideForContextMenuDefaults(defaults?: Partial<ForContextMenuDefaults>): Provider[];
+
+export { FOR_CONTEXT_MENU_CONTEXT, FOR_CONTEXT_MENU_DEFAULTS, ForContextMenu, ForContextMenuTrigger, provideForContextMenuDefaults };
+export type { ForContextMenuContext, ForContextMenuDefaults };