@qalma/kit 0.1.0-beta.0 → 0.4.0

package/types/qalma-kit-headless.d.ts

@@ -0,0 +1,303 @@
+import * as _angular_core from '@angular/core';
+import { DestroyRef, ElementRef, Signal } from '@angular/core';
+import { DragHandleMoveCommandValue, DragHandleCommandValue, QalmaEditorController } from '@qalma/editor';
+import * as _qalma_kit_headless from '@qalma/kit/headless';
+
+interface AnchorRect {
+    readonly top: number;
+    readonly bottom: number;
+    readonly left: number;
+    readonly right: number;
+}
+interface AnchorSize {
+    readonly width: number;
+    readonly height: number;
+}
+type AnchorPlacement = 'top' | 'bottom' | 'left' | 'right';
+type AnchorAlign = 'start' | 'center' | 'end';
+interface AnchorToRectOptions {
+    /** Which side of the anchor rect the floating element renders on. */
+    readonly placement: AnchorPlacement;
+    /** Rect (viewport or scroll surface) the result is clamped within. */
+    readonly boundary: AnchorRect;
+    /** Size of the floating element being positioned. */
+    readonly size: AnchorSize;
+    /** Distance between the anchor rect and the floating element. Default 8. */
+    readonly gap?: number;
+    /** Minimum distance kept from the boundary edges. Default 8. */
+    readonly edgeMargin?: number;
+    /**
+     * Cross-axis alignment relative to the anchor rect. `start` | `center` |
+     * `end` align to the anchor rect itself; a number instead pins the
+     * floating element's center to that viewport coordinate (clamped within
+     * the anchor rect), e.g. to follow a pointer's Y while hovering a tall
+     * block. Defaults to `start`.
+     */
+    readonly align?: AnchorAlign | number;
+}
+interface AnchorPosition {
+    readonly top: number;
+    readonly left: number;
+}
+declare function anchorToRect(anchor: AnchorRect, options: AnchorToRectOptions): AnchorPosition;
+
+/**
+ * Fixed-position coordinates for a suggestion menu anchored to a caret/range
+ * rect. Exactly one of `top`/`bottom` is a number (the other is `null`): the
+ * menu is pinned below the anchor by `top`, or above it by `bottom`.
+ */
+interface SuggestionMenuPlacement {
+    readonly left: number;
+    readonly top: number | null;
+    readonly bottom: number | null;
+    readonly maxHeight: number;
+}
+interface FlipAbovePlacementOptions {
+    /** Menu width, used to clamp `left` within the viewport. */
+    readonly width: number;
+    /** Ideal menu height for the current option count. */
+    readonly desiredHeight: number;
+    /** Floor for the computed `maxHeight` (e.g. one option / a loading row). */
+    readonly minHeight: number;
+    /** Viewport edge margin (default 12). */
+    readonly margin?: number;
+    /** Gap between the anchor and the menu (default 8). */
+    readonly gap?: number;
+}
+/**
+ * Positions a floating list under an anchor rect, flipping it above when there
+ * is not enough room below, and clamping its height and horizontal position to
+ * the viewport. Shared by the mention and slash-command menus, whose flip
+ * behavior `anchorToRect` does not cover (it has no flip / dynamic max-height).
+ */
+declare function flipAbovePlacement(rect: {
+    readonly top: number;
+    readonly bottom: number;
+    readonly left: number;
+}, options: FlipAbovePlacementOptions): SuggestionMenuPlacement;
+
+interface DismissibleOverlayOptions {
+    /** Returns true when the event target is part of the overlay/trigger and should not dismiss it. */
+    isInside: (target: EventTarget | null) => boolean;
+    onDismiss: () => void;
+}
+/**
+ * Shared outside-click / Escape dismiss behavior for floating overlays
+ * (popovers, contextual menus, autocomplete lists). Generalizes the
+ * ad-hoc click-outside/Escape handling that used to be reimplemented
+ * separately per feature.
+ */
+declare class DismissibleOverlay {
+    private readonly options;
+    private readonly pointerDown;
+    private readonly keydown;
+    constructor(options: DismissibleOverlayOptions);
+    connect(destroyRef: DestroyRef): void;
+}
+
+interface KeyboardNavigableListOptions<T> {
+    items: () => readonly T[];
+    activeIndex: () => number;
+    setActiveIndex: (index: number) => void;
+    onSelect: (item: T, index: number) => void;
+}
+/**
+ * Circular index step: move `index` by `delta` within `[0, length)`, wrapping
+ * around both ends; returns `index` unchanged for an empty list. This is the
+ * single source of truth for wrap-around list navigation — both
+ * `KeyboardNavigableList` (BYO-markup lists) and `QalmaSuggestionMenu` (the
+ * shipped mention/slash menus) delegate their arrow-key math to it.
+ */
+declare function wrapIndex(index: number, delta: number, length: number): number;
+/**
+ * Arrow-key navigation + Enter-to-select for autocomplete-style popovers
+ * (mention menu, slash command menu). Shared so both features stop
+ * reimplementing the same wrap-around index math.
+ *
+ * Takes a plain key string rather than a `KeyboardEvent` — some callers
+ * relay keys through a `CustomEvent` (no real `KeyboardEvent` to read),
+ * so preventing the default action is left to the caller.
+ */
+declare class KeyboardNavigableList<T> {
+    private readonly options;
+    constructor(options: KeyboardNavigableListOptions<T>);
+    /** Returns true when the key was handled (caller should stop further propagation / preventDefault). */
+    handleKey(key: string): boolean;
+}
+
+/** Option buttons carry this attribute so the base can focus/scroll to one by index. */
+declare const SUGGESTION_OPTION_INDEX_ATTR = "data-suggestion-index";
+/** The scrollable options container carries this attribute (optional). */
+declare const SUGGESTION_OPTIONS_SCROLLER_ATTR = "data-suggestion-options";
+/**
+ * Shared behavior for caret-anchored suggestion menus (mention, slash command):
+ * flip-above placement input, active-option highlighting, and in-menu keyboard
+ * handling (Escape dismisses, Arrow moves + focuses, Enter/Space picks) with
+ * wrap-around and optional scroll-into-view. Concrete menus only supply their
+ * own item markup and expose their option list via `optionList`.
+ */
+declare abstract class QalmaSuggestionMenu<TOption extends {
+    readonly id: string;
+}> {
+    protected readonly elementRef: ElementRef<HTMLElement>;
+    readonly placement: _angular_core.InputSignal<SuggestionMenuPlacement | null>;
+    readonly activeIndex: _angular_core.InputSignal<number>;
+    readonly activate: _angular_core.OutputEmitterRef<number>;
+    readonly pick: _angular_core.OutputEmitterRef<TOption>;
+    readonly dismiss: _angular_core.OutputEmitterRef<void>;
+    /** The rendered options, bound by the concrete menu (`options`/`suggestions`). */
+    protected abstract readonly optionList: Signal<readonly TOption[]>;
+    protected preserveSelection(event: MouseEvent): void;
+    protected handleOptionKeydown(event: KeyboardEvent, option: TOption, index: number): void;
+    protected focusOption(index: number): void;
+    protected scrollOptionIntoView(index: number): void;
+    private getNextIndex;
+    private optionElement;
+    private optionsScroller;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<QalmaSuggestionMenu<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<QalmaSuggestionMenu<any>, never, never, { "placement": { "alias": "placement"; "required": false; "isSignal": true; }; "activeIndex": { "alias": "activeIndex"; "required": false; "isSignal": true; }; }, { "activate": "activate"; "pick": "pick"; "dismiss": "dismiss"; }, never, never, true, never>;
+}
+
+interface QalmaDragHandleView {
+    target: DragHandleCommandValue;
+    transform: string;
+    blockType: string;
+    canMoveUp: boolean;
+    canMoveDown: boolean;
+}
+interface QalmaDragDropIndicator {
+    target: DragHandleMoveCommandValue;
+    transform: string;
+    width: number;
+}
+interface QalmaDragBlockHighlight {
+    transform: string;
+    width: number;
+    height: number;
+}
+declare class QalmaDragHandleController {
+    private readonly editor;
+    private readonly handleState;
+    private readonly dropIndicatorState;
+    private readonly draggedBlockHighlightState;
+    readonly handle: _angular_core.Signal<QalmaDragHandleView | null>;
+    readonly dropIndicator: _angular_core.Signal<QalmaDragDropIndicator | null>;
+    readonly draggedBlockHighlight: _angular_core.Signal<QalmaDragBlockHighlight | null>;
+    private surface;
+    private currentBlock;
+    private pendingBlock;
+    private lastPointerClientY;
+    private refreshFrame;
+    private handleKey;
+    private dragSession;
+    constructor(editor: () => QalmaEditorController);
+    connect(surface: HTMLElement, destroyRef: DestroyRef): void;
+    hide(): void;
+    startDrag(event: PointerEvent, handle: QalmaDragHandleView): void;
+    private handlePointerMove;
+    private handlePointerLeave;
+    private handleDragPointerMove;
+    private handleDragPointerUp;
+    private activateDragSession;
+    private updateDropIndicator;
+    private updateDraggedBlockHighlight;
+    private finishDrag;
+    private scheduleRefresh;
+    private refresh;
+    private updateFromBlock;
+    private cancelScheduledRefresh;
+    private setHandle;
+    private setDropIndicator;
+}
+
+declare class QalmaDragHandleDirective {
+    readonly editor: _angular_core.InputSignal<QalmaEditorController>;
+    private readonly destroyRef;
+    private readonly host;
+    private readonly controller;
+    readonly handle: _angular_core.Signal<QalmaDragHandleView | null>;
+    readonly dropIndicator: _angular_core.Signal<_qalma_kit_headless.QalmaDragDropIndicator | null>;
+    readonly draggedBlockHighlight: _angular_core.Signal<_qalma_kit_headless.QalmaDragBlockHighlight | null>;
+    constructor();
+    hide(): void;
+    startDrag(event: PointerEvent, handle: QalmaDragHandleView): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<QalmaDragHandleDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<QalmaDragHandleDirective, "[qalmaDragHandle]", ["qalmaDragHandle"], { "editor": { "alias": "qalmaDragHandle"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Fixed-position placement for a selection/contextual toolbar: a ready-to-apply
+ * CSS `transform` that pins the toolbar above the current selection rect.
+ * Produced by {@link QalmaSelectionToolbarController}; consumed by the styled
+ * `QalmaContextualToolbar` (or any custom bubble toolbar).
+ */
+interface QalmaContextualToolbarPlacement {
+    transform: string;
+}
+declare class QalmaSelectionToolbarController {
+    private readonly editor;
+    private readonly placementState;
+    readonly placement: _angular_core.Signal<QalmaContextualToolbarPlacement | null>;
+    private surface;
+    private refreshFrame;
+    private placementKey;
+    constructor(editor: () => QalmaEditorController);
+    connect(surface: HTMLElement, destroyRef: DestroyRef): void;
+    refresh(): void;
+    hide(): void;
+    handleKeydown(event: Event): void;
+    private scheduleRefresh;
+    private cancelScheduledRefresh;
+    private setPlacement;
+}
+
+declare class QalmaSelectionToolbarDirective {
+    readonly editor: _angular_core.InputSignal<QalmaEditorController>;
+    private readonly destroyRef;
+    private readonly host;
+    private readonly controller;
+    readonly placement: _angular_core.Signal<_qalma_kit_headless.QalmaContextualToolbarPlacement | null>;
+    constructor();
+    refresh(): void;
+    hide(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<QalmaSelectionToolbarDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<QalmaSelectionToolbarDirective, "[qalmaSelectionToolbar]", ["qalmaSelectionToolbar"], { "editor": { "alias": "qalmaSelectionToolbar"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+interface LinkPopover extends LinkPopoverPlacement {
+    editing: boolean;
+    element: HTMLAnchorElement | null;
+    href: string;
+    rel: string | null;
+    target: '_blank' | null;
+    text: string;
+}
+interface LinkPopoverPlacement {
+    left: number;
+    top: number;
+}
+declare function createLinkPopoverPlacement(element: HTMLElement): LinkPopoverPlacement;
+declare function findEditorLinkElement(target: EventTarget | null): HTMLAnchorElement | null;
+
+declare class LinkPopoverController {
+    private readonly editor;
+    readonly popover: _angular_core.WritableSignal<LinkPopover | null>;
+    readonly href: _angular_core.WritableSignal<string>;
+    private hideTimeout;
+    constructor(editor: QalmaEditorController);
+    showToolbarEditor(event: MouseEvent): void;
+    showPreview(event: Event): void;
+    scheduleHideFromEvent(event: MouseEvent | FocusEvent): void;
+    edit(popover: LinkPopover): void;
+    save(popover: LinkPopover): void;
+    remove(popover: LinkPopover): void;
+    hide(): void;
+    keepOpen(): void;
+    scheduleHide(): void;
+    private selectLink;
+    private clearHideTimeout;
+}
+
+export { DismissibleOverlay, KeyboardNavigableList, LinkPopoverController, QalmaDragHandleController, QalmaDragHandleDirective, QalmaSelectionToolbarController, QalmaSelectionToolbarDirective, QalmaSuggestionMenu, SUGGESTION_OPTIONS_SCROLLER_ATTR, SUGGESTION_OPTION_INDEX_ATTR, anchorToRect, createLinkPopoverPlacement, findEditorLinkElement, flipAbovePlacement, wrapIndex };
+export type { AnchorAlign, AnchorPlacement, AnchorPosition, AnchorRect, AnchorSize, AnchorToRectOptions, DismissibleOverlayOptions, FlipAbovePlacementOptions, KeyboardNavigableListOptions, LinkPopover, LinkPopoverPlacement, QalmaContextualToolbarPlacement, QalmaDragBlockHighlight, QalmaDragDropIndicator, QalmaDragHandleView, SuggestionMenuPlacement };
+//# sourceMappingURL=qalma-kit-headless.d.ts.map

package/types/qalma-kit-headless.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qalma-kit-headless.d.ts","sources":["../../../../libs/ui-kit/headless/src/lib/anchor-to-rect.ts","../../../../libs/ui-kit/headless/src/lib/flip-above-placement.ts","../../../../libs/ui-kit/headless/src/lib/dismissible-overlay.ts","../../../../libs/ui-kit/headless/src/lib/keyboard-navigable-list.ts","../../../../libs/ui-kit/headless/src/lib/suggestion-menu-base.ts","../../../../libs/ui-kit/headless/src/lib/drag-handle-controller.ts","../../../../libs/ui-kit/headless/src/lib/drag-handle-directive.ts","../../../../libs/ui-kit/headless/src/lib/selection-toolbar-controller.ts","../../../../libs/ui-kit/headless/src/lib/selection-toolbar-directive.ts","../../../../libs/ui-kit/headless/src/lib/link-popover.model.ts","../../../../libs/ui-kit/headless/src/lib/link-popover-controller.ts"],"mappings":"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","names":[]}