@bluepic/embed 0.4.0-next.145 → 0.4.0-next.148

package/dist/util/fieldHints/chipAction.d.ts

@@ -0,0 +1,23 @@
+import type { BluepicField } from '@bluepic/types';
+/**
+ * What clicking a hint chip does.
+ *
+ * There is no per-field hint MODE any more — hints are simply on or off for the
+ * whole campaign (`config.hints.enabled`). What a chip does is inferred from the
+ * field itself:
+ *
+ * - `upload` — an image field that accepts a device upload. Clicking goes
+ *   straight to its own upload flow, which is the only thing anyone wants from
+ *   an image chip.
+ * - `focus`  — everything else, including image fields restricted to libraries.
+ *   The chip scrolls the field into view and focuses its control, so the next
+ *   keystroke already types into it.
+ */
+export type ChipAction = 'upload' | 'focus';
+/**
+ * `field.props` entries may be author expressions (functions) rather than
+ * literals, so a prop can only be read through the host's evaluator — the same
+ * `wrapFieldProps` treatment `FieldsList` gives every field component.
+ */
+export declare function readFieldProp<T>(value: T | (() => T), evaluate?: (fn: Function) => unknown): T | undefined;
+export declare function chipActionFor(field: BluepicField, evaluate?: (fn: Function) => unknown): ChipAction;

package/dist/util/fieldHints/fieldFocus.d.ts

@@ -49,7 +49,7 @@ export declare const FIELD_FOCUS_FLASH_CLASS = "bx-field-hint-target";
  * container, and centering yanks the whole list even when the target was
  * already comfortably visible.
  */
-export declare function revealFieldElement(el: HTMLElement | null | undefined): void;
+export declare function revealFieldElement(el: HTMLElement | null | undefined): HTMLElement | undefined;
 /**
  * Creates the desktop half: a registry keyed by the field object itself.
  *

package/dist/util/fieldHints/index.d.ts

@@ -9,7 +9,13 @@ export type { FieldHitbox } from './useFieldHitboxes';
 export { useHintReveal } from './useHintReveal';
 export { createFieldElementRegistry, provideFieldFocus, revealFieldElement, useFieldFocus, FIELD_FOCUS_KEY, FIELD_FOCUS_FLASH_CLASS, } from './fieldFocus';
 export type { FieldFocusController } from './fieldFocus';
-export { interactModeFor, inlineTextBinding, readFieldProp } from './interact';
-export type { InteractMode } from './interact';
+export { chipActionFor, readFieldProp } from './chipAction';
+export type { ChipAction } from './chipAction';
+export { textGeometryProbe } from './textProbe';
+export type { CaretGeometry, SelectionQuad, TextGeometryResult, TextIndexResult } from './textProbe';
+export { useCanvasTextEditing } from './useCanvasTextEditing';
+export type { CanvasTextState, SelectionHandle } from './useCanvasTextEditing';
+export { chooseChipPlacement, chipIsCentered, estimateChipWidth, arrowRotationForSide } from './placement';
+export type { ChipSide, PlacementResult } from './placement';
 export { useFieldActivator } from './fieldFocus';
 export type { FieldActivator } from './fieldFocus';

package/dist/util/fieldHints/placement.d.ts

@@ -0,0 +1,72 @@
+import type { BluepicField } from '@bluepic/types';
+/**
+ * Where a hint chip sits relative to its hitbox.
+ *
+ * Deliberately a small synchronous solver rather than `@floating-ui`, which
+ * this package already depends on: hints re-project on EVERY pan/zoom frame,
+ * and floating-ui's `computePosition` is async and DOM-measuring. Running one
+ * per hint per frame would lag the overlay behind the canvas it is annotating.
+ * A pure function over numbers also means the placement rules can be tested
+ * without a DOM.
+ */
+export type ChipSide = 'top' | 'bottom' | 'left' | 'right';
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type PlacementInput = {
+    /** Hitbox AABB in overlay pixels. */
+    box: Rect;
+    /** Measured (or estimated) chip size. */
+    chip: {
+        width: number;
+        height: number;
+    };
+    /** Visible overlay area. */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Distance from the hitbox edge to the chip edge — room for the arrow. */
+    gap: number;
+    /** Keep-inside-the-viewport padding. */
+    margin: number;
+};
+export type PlacementResult = {
+    side: ChipSide;
+    /** Chip top-left in overlay pixels. */
+    x: number;
+    y: number;
+    /**
+     * Arrow tip anchor, RELATIVE to the chip's top-left. Tracks the hitbox centre
+     * even after the chip has been shifted to stay on screen — otherwise a
+     * clamped chip would point at empty space.
+     */
+    arrowX: number;
+    arrowY: number;
+};
+export declare function chipIsCentered(fieldType: BluepicField['type']): boolean;
+export declare function chooseChipPlacement(input: PlacementInput): PlacementResult;
+/**
+ * Chip width before the real element has been measured. Only used for the very
+ * first frame — the layer measures the rendered chip and re-solves — but a wild
+ * guess here would place the first paint visibly wrong.
+ */
+export declare function estimateChipWidth(label: string, max?: number): number;
+/**
+ * The arrow artwork points RIGHT at rest — the path's tip is authored on the
+ * left, but `popoverArrow`'s outer `matrix(-1,0,-0,-1,...)` flips it. Verified
+ * by rasterising the mask: the left edge is ~97% covered (the flat base) and
+ * the right edge ~4% (the point).
+ */
+export declare const ARROW_NATIVE_DIRECTION: {
+    x: number;
+    y: number;
+};
+/**
+ * Degrees to rotate the arrow so it points from the chip back at its hitbox.
+ * CSS rotation is clockwise with y pointing down.
+ */
+export declare function arrowRotationForSide(side: ChipSide): number;

package/dist/util/fieldHints/probe.d.ts

@@ -35,6 +35,17 @@ export type ElementQuad = {
      */
     dataId: string;
     quad: HintQuad;
+    /**
+     * Tighter box to POINT AT, when the element has one. Present only for text
+     * elements whose painted box is larger than the glyphs — i.e. text carrying a
+     * surface/background bar, where `quad` balloons out to the whole text frame.
+     *
+     * The hover region stays `quad` (generous, easy to hit); only the tooltip's
+     * anchor moves here, so a bubble describing a headline points at the words
+     * rather than at the far corner of the bar behind them. Absent whenever the
+     * two coincide, which is the common case.
+     */
+    anchor?: HintQuad;
 };
 export type HitboxProbeResult = {
     supported: false;

package/dist/util/fieldHints/textProbe.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Text geometry on the canvas: where the caret is, what the selection covers,
+ * and which character a point lands on.
+ *
+ * All three answers come from the glyphs the engine actually laid out, via
+ * `SVGTextContentElement`:
+ *   `getStartPositionOfChar` / `getEndPositionOfChar` — caret and range edges
+ *   `getExtentOfChar`                                — line height / em box
+ *   `getCharNumAtPosition`                           — point → character
+ * plus the tspan's computed `fill` for colour. Verified against a live 0.2.65
+ * sandbox: hit-testing along a line returned the exact character at each
+ * position and −1 outside.
+ *
+ * ONE probe with an `op` rather than three: it ships as SOURCE TEXT (see the
+ * warning on `fieldHitboxProbe`), so helpers cannot be shared between separate
+ * probe functions — they would have to be duplicated inside each one. The line
+ * mapping below is subtle enough that having two copies drift apart is a real
+ * risk, so the ops share one body.
+ */
+/**
+ * A caret as a SEGMENT rather than a point plus a height.
+ *
+ * Both ends are computed in the line's local space and mapped out, so the
+ * segment carries the text's rotation, skew and scale intrinsically. Returning
+ * `{x, y, height}` instead forced the consumer to subtract the ascent in SERIAL
+ * y — which is only "up" for unrotated text, and left carets and handle stems
+ * standing vertically through slanted text.
+ */
+export type CaretGeometry = {
+    /** Top of the em box, in serial coordinates. */
+    top: {
+        x: number;
+        y: number;
+    };
+    /** Bottom of the em box, in serial coordinates. */
+    bottom: {
+        x: number;
+        y: number;
+    };
+    /** Resolved text colour, so the caret matches the words it sits in. */
+    color: string;
+    lineIndex: number;
+};
+/** One selected run on one line, as a quad so rotated text still works. */
+export type SelectionQuad = {
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+    lineIndex: number;
+};
+export type TextGeometryResult = {
+    found: false;
+} | {
+    found: true;
+    /** Present only when the selection is collapsed — a caret, not a range. */
+    caret?: CaretGeometry;
+    selection: SelectionQuad[];
+    /** Range ends, for the mobile drag handles. Present when a range exists. */
+    startAnchor?: CaretGeometry;
+    endAnchor?: CaretGeometry;
+};
+export type TextIndexResult = {
+    index: number | null;
+};
+/**
+ * ⚠️ SHIPPED AS SOURCE TEXT — no imports, no module-scope references, plain ES.
+ *
+ * @param argsJson `{ op, elementId, value, selectionStart, selectionEnd, x, y }`
+ */
+export declare function textGeometryProbe(argsJson: string): TextGeometryResult | TextIndexResult;

package/dist/util/fieldHints/useCanvasTextEditing.d.ts

@@ -0,0 +1,125 @@
+import { type Ref } from 'vue';
+import type { BluepicField } from '@bluepic/types';
+import { type CaretGeometry, type SelectionQuad } from './textProbe';
+type EvaluateFn = (func: Function, ...args: string[]) => Promise<unknown>;
+export type CanvasTextState = {
+    caret?: CaretGeometry;
+    selection: SelectionQuad[];
+    startAnchor?: CaretGeometry;
+    endAnchor?: CaretGeometry;
+};
+export type SelectionHandle = 'start' | 'end';
+export declare function useCanvasTextEditing(options: {
+    evaluate: () => EvaluateFn | undefined;
+    data: Ref<{
+        [k: string]: unknown;
+    }>;
+}): {
+    state: Ref<{
+        caret?: {
+            top: {
+                x: number;
+                y: number;
+            };
+            bottom: {
+                x: number;
+                y: number;
+            };
+            color: string;
+            lineIndex: number;
+        } | undefined;
+        selection: {
+            points: {
+                x: number;
+                y: number;
+            }[];
+            lineIndex: number;
+        }[];
+        startAnchor?: {
+            top: {
+                x: number;
+                y: number;
+            };
+            bottom: {
+                x: number;
+                y: number;
+            };
+            color: string;
+            lineIndex: number;
+        } | undefined;
+        endAnchor?: {
+            top: {
+                x: number;
+                y: number;
+            };
+            bottom: {
+                x: number;
+                y: number;
+            };
+            color: string;
+            lineIndex: number;
+        } | undefined;
+    } | undefined, CanvasTextState | {
+        caret?: {
+            top: {
+                x: number;
+                y: number;
+            };
+            bottom: {
+                x: number;
+                y: number;
+            };
+            color: string;
+            lineIndex: number;
+        } | undefined;
+        selection: {
+            points: {
+                x: number;
+                y: number;
+            }[];
+            lineIndex: number;
+        }[];
+        startAnchor?: {
+            top: {
+                x: number;
+                y: number;
+            };
+            bottom: {
+                x: number;
+                y: number;
+            };
+            color: string;
+            lineIndex: number;
+        } | undefined;
+        endAnchor?: {
+            top: {
+                x: number;
+                y: number;
+            };
+            bottom: {
+                x: number;
+                y: number;
+            };
+            color: string;
+            lineIndex: number;
+        } | undefined;
+    } | undefined>;
+    activeElementId: Ref<string | undefined, string | undefined>;
+    isActive: import("vue").ComputedRef<boolean>;
+    begin: (next: {
+        field: BluepicField;
+        elementId: string;
+        binding: string;
+        input: HTMLInputElement | HTMLTextAreaElement;
+    }) => void;
+    end: () => void;
+    beginSelectionAt: (x: number, y: number) => Promise<void>;
+    beginHandleDrag: (handle: SelectionHandle, point: {
+        x: number;
+        y: number;
+    }) => void;
+    extendSelectionTo: (x: number, y: number) => Promise<void>;
+    endSelectionDrag: () => void;
+    selectWordAt: (x: number, y: number) => Promise<void>;
+};
+export {};