@bluepic/embed 0.4.0-next.99 → 0.5.1

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

@@ -0,0 +1,52 @@
+import type { BluepicField } from '@bluepic/types';
+import type { HintPoint, HintQuad } from './probe';
+/**
+ * Geometry helpers over probe output. Everything here works in SERIAL
+ * coordinates — the overlay maps to screen space via zoompinch's
+ * `composePoint`, so nothing in this file needs to know about pan, zoom or
+ * viewport size.
+ */
+/** Shoelace area. Quads may be rotated or sheared, so no width×height shortcut. */
+export declare function quadArea(quad: HintQuad): number;
+export declare function quadCentroid(quad: HintQuad): HintPoint;
+export declare function quadAABB(quad: HintQuad): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Which frame a quad belongs to, in the 1-based numbering `field.frameIndex`
+ * already uses (`BxTemplateEditor` reads it as `field.frameIndex || 1` and
+ * derives `frameX = (frameIndex - 1) % frames.x`).
+ *
+ * Decided by the centroid, so an element straddling a frame boundary lands in
+ * the frame it mostly occupies rather than being duplicated or dropped.
+ */
+export declare function frameIndexOfPoint(point: HintPoint, serialWidth: number, serialHeight: number, frames: {
+    x: number;
+    y: number;
+} | undefined): number;
+/**
+ * Stacking class for overlap resolution — lower sits ON TOP.
+ *
+ * Hitboxes overlap constantly (a logo inside a full-bleed background image), so
+ * the pointer has to go somewhere defensible. Content-bearing fields win over
+ * pickers, which win over the tweak-a-value controls.
+ */
+export declare function hintPriorityClass(fieldType: BluepicField['type']): number;
+export type OrderableHitbox = {
+    fieldType: BluepicField['type'];
+    area: number;
+    /** Position of the element in the serial's depth-first order; later paints later. */
+    elementOrder: number;
+};
+/**
+ * Sorts hitboxes back-to-front, so the caller can render in array order and let
+ * DOM order do the stacking. The LAST entry is the topmost / most reachable.
+ *
+ * Smaller area on top is what keeps a logo sitting inside a full-bleed image
+ * clickable — without it the background would swallow every pointer event
+ * inside its own bounds.
+ */
+export declare function orderHitboxes<T extends OrderableHitbox>(hitboxes: T[]): T[];

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

@@ -0,0 +1,20 @@
+export { fieldHitboxProbe } from './probe';
+export type { HintPoint, HintQuad, ElementQuad, HitboxProbeResult } from './probe';
+export { collectSerialElements, expandBindingClosure, fieldBindings, referencesIdentifier, resolveFieldElements, scoreElement, CANDIDATE_SCORE_RATIO, } from './resolve';
+export type { FieldElementMatch } from './resolve';
+export { frameIndexOfPoint, hintPriorityClass, orderHitboxes, quadAABB, quadArea, quadCentroid } from './geometry';
+export type { OrderableHitbox } from './geometry';
+export { useFieldHitboxes } from './useFieldHitboxes';
+export type { FieldHitbox } from './useFieldHitboxes';
+export { useHintReveal } from './useHintReveal';
+export { useChipHighlight } from './useChipHighlight';
+export { createFieldElementRegistry, provideFieldFocus, revealFieldElement, useFieldFocus, FIELD_FOCUS_KEY, FIELD_FOCUS_FLASH_CLASS, FIELD_HOVER_CLASS, } from './fieldFocus';
+export type { FieldFocusController } from './fieldFocus';
+export { chipActionFor, fieldHasChip, 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 { useFieldActivator } from './fieldFocus';
+export type { FieldActivator } from './fieldFocus';

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

@@ -0,0 +1,84 @@
+/**
+ * The sandbox-side geometry probe.
+ *
+ * Field hints need to know where each element ACTUALLY landed on the canvas —
+ * after every ancestor transform, layout-group flow shift, mask clip and text
+ * auto-fit. That composition already happened once, inside the sandbox iframe,
+ * and the browser is holding the result. So rather than re-deriving it in the
+ * parent (which would mean linking `@bluepic/core` into this package and
+ * pinning ONE engine version against sandboxes that deliberately freeze one
+ * engine per template), we ask the frame that drew the pixels.
+ *
+ * `getBBox()` gives an element's local geometry; `getScreenCTM()` gives its
+ * full transform chain — CSS `transform` included, which is how core applies
+ * per-element matrices. Composing the element's screen CTM with the INVERSE of
+ * the root SVG's screen CTM cancels out viewport sizing and `preserveAspectRatio`
+ * letterboxing, leaving a matrix straight into viewBox units — i.e. serial
+ * coordinates. Verified against a live sandbox (0.2.65) to 0.0000px for an
+ * identity rect, a 23°-rotated text element, a rotate+scale group, and a rect
+ * nested inside that group.
+ *
+ * Nothing here needs a core release or a sandbox redeploy: it travels as source
+ * text through the existing `EmbeddedController.evaluate()` channel.
+ */
+export type HintPoint = {
+    x: number;
+    y: number;
+};
+/** Element corners in serial coordinates, clockwise from the local top-left. */
+export type HintQuad = [HintPoint, HintPoint, HintPoint, HintPoint];
+export type ElementQuad = {
+    /**
+     * The rendered instance's unique id (`data-id`). An element with an
+     * `iteration` renders once per item, so one serial element can yield several
+     * of these — `id__0`, `id__1`, … — all sharing one `data-orginal-id`.
+     */
+    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;
+    /**
+     * `no-root` — no `.serial-wrapper > svg` yet (not mounted, or a sandbox
+     * that structures its DOM differently).
+     * `no-element-identity` — rendered, but the engine predates per-element
+     * `data-id` attributes (roughly < core 0.1.400). Nothing to anchor to;
+     * hints stay off for this template forever, by design.
+     * `no-ctm` — the root SVG has no screen CTM (whole subtree hidden).
+     */
+    reason: 'no-root' | 'no-element-identity' | 'no-ctm';
+} | {
+    supported: true;
+    quads: {
+        [originalId: string]: ElementQuad[];
+    };
+};
+/**
+ * ⚠️ THIS FUNCTION IS SHIPPED AS SOURCE TEXT, NOT AS A CLOSURE.
+ *
+ * `EmbeddedController.evaluate()` does `func.toString()` here and `new Function(...)`
+ * inside the iframe, so the body executes in a scope where NOTHING from this
+ * bundle exists. Any reference to an import, a module-scope const, or a helper
+ * defined outside these braces typechecks, builds green, and then throws
+ * `ReferenceError` in the sandbox under a minified name that won't resemble the
+ * original.
+ *
+ * Rules, all enforced by `probe.test.ts`:
+ *   - one self-contained function; no free variables beyond `document`
+ *   - plain ES (`var`, `function`, no optional chaining) so no transpiler
+ *     helper can be hoisted out of the body
+ *   - arguments in as a JSON string, return value JSON-serialisable — flatten
+ *     every `DOMMatrix`/`DOMRect` before returning
+ */
+export declare function fieldHitboxProbe(originalIdsJson: string): HitboxProbeResult;

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

@@ -0,0 +1,55 @@
+import type { BluepicField, Template } from '@bluepic/types';
+/**
+ * Candidates scoring below this share of the winner are dropped. Keeps the
+ * legitimate multi-element cases — a headline plus the background bar bound to
+ * it, or one binding echoed across two frames — while cutting the long tail of
+ * weak style/visibility couplings that would otherwise blanket the canvas.
+ */
+export declare const CANDIDATE_SCORE_RATIO = 0.6;
+export type FieldElementMatch = {
+    /** Serial element id — matches the rendered `data-orginal-id`. */
+    elementId: string;
+    element: Template.Element;
+    score: number;
+    /** Property keys that produced the match, for debugging a surprising hitbox. */
+    matchedProperties: string[];
+};
+/** Depth-first walk over the serial tree, descending into group/mask slots. */
+export declare function collectSerialElements(elements: Template.Element[]): Generator<Template.Element>;
+/**
+ * Does `expression` reference `name` as a standalone identifier?
+ *
+ * Hand-rolled rather than a regex with a lookbehind: `(?<!…)` still throws at
+ * compile time on Safari below 16.4, and a template that renders fine
+ * everywhere else must not blank its hints on an older iPad. A preceding `.`
+ * is excluded so `other.headline` doesn't match `headline`.
+ */
+export declare function referencesIdentifier(expression: string, name: string): boolean;
+/**
+ * Every binding that carries this field's value, mapped to how many
+ * `computedBindings` hops away it is. A field may write `headline`, while the
+ * element actually reads `headlineUpper = UPPER(headline)`.
+ *
+ * Iterated to a fixpoint and guarded on improvement only, so a cyclic
+ * computed-binding definition terminates instead of spinning.
+ */
+export declare function expandBindingClosure(computedBindings: {
+    [k: string]: string;
+} | undefined, roots: string[]): Map<string, number>;
+/** The bindings a field writes. Group/Instruction fields have none. */
+export declare function fieldBindings(field: BluepicField): string[];
+/**
+ * Score one element against one field. Returns `null` when nothing matched.
+ * The score is the STRONGEST single property match, not a sum — an element
+ * whose text is bound to the field shouldn't outrank a sibling merely by also
+ * borrowing the same value for its opacity.
+ */
+export declare function scoreElement(field: BluepicField, element: Template.Element, hopsByBinding: Map<string, number>): {
+    score: number;
+    matchedProperties: string[];
+} | null;
+/**
+ * The elements a field drives, best first, already cut to the candidates worth
+ * drawing a hitbox for.
+ */
+export declare function resolveFieldElements(serial: Template.Serial, field: BluepicField): FieldElementMatch[];

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

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

@@ -0,0 +1,29 @@
+/**
+ * Which hint is highlighted, and which chip is on screen — two answers, because
+ * they are not the same question.
+ *
+ * The OUTLINE follows the pointer exactly: whatever it is over is the element
+ * being asked about, and nothing else may be lit.
+ *
+ * The CHIP cannot, because of where it sits. It is centred on its picture, so
+ * reaching it means travelling ACROSS that picture — and pictures nest (a logo,
+ * a portrait, a badge over a background), so the trip regularly crosses another
+ * hitbox. Handing the chip straight over to whatever the pointer touched on the
+ * way pulled it out from under a pointer already aimed at it, and the click
+ * landed on the element underneath instead: the upload dialog simply never
+ * opened. A chip that has just lost the highlight therefore stays painted (and
+ * clickable) for a moment longer.
+ *
+ * That grace period is not a lifetime: arriving on the chip re-activates it
+ * (`activate` from the chip's own `pointerenter`), so it only ever has to
+ * outlast the trip.
+ */
+export declare function useChipHighlight({ lingerMs }?: {
+    lingerMs?: number;
+}): {
+    activeKey: import("vue").Ref<string | undefined, string | undefined>;
+    chipShown: (key: string) => boolean;
+    activate: (key: string) => void;
+    release: (key: string) => boolean;
+    reset: () => void;
+};