@bluepic/embed 0.4.0-next.142 → 0.4.0-next.144

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

@@ -0,0 +1,70 @@
+import { type InjectionKey } from 'vue';
+import type { BluepicField } from '@bluepic/types';
+/**
+ * Opens a field's own primary editing flow — for an image field, the "Select
+ * image" popup (or the device file picker, when that's all it offers).
+ *
+ * Registered BY the field component, because only it knows that flow. An
+ * `interact` hint reproducing it would mean duplicating image libraries,
+ * cropping, background removal and auto-crop on the overlay, and then watching
+ * the two copies drift.
+ */
+export type FieldActivator = () => void;
+/**
+ * Connects a hint on the preview to the field control that drives it.
+ *
+ * The two halves live far apart — the hint renders inside zoompinch's matrix
+ * slot, the control somewhere down a recursive `FieldsList` — so this is
+ * provided by `BxTemplateEditor` and injected at both ends rather than threaded
+ * through props.
+ *
+ * DESKTOP registers elements here and focuses them directly. MOBILE does not:
+ * one field slide is on screen at a time, so "focus" there means swiping the
+ * swiper to the right slide, which only `BxTemplateEditor` can do. That
+ * asymmetry is why `focus()` is a controller method and not just a lookup.
+ */
+export type FieldFocusController = {
+    /** Desktop only; mobile slides are addressed by index, not by element. */
+    register(field: BluepicField, el: HTMLElement | null): void;
+    focus(field: BluepicField): void;
+    /** Field components self-register; pass `null` on unmount. */
+    registerActivator(field: BluepicField, activate: FieldActivator | null): void;
+    /**
+     * Runs the field's own flow. Returns false when the field never registered
+     * one, so the caller can fall back to plain focus instead of doing nothing.
+     */
+    activate(field: BluepicField): boolean;
+};
+export declare const FIELD_FOCUS_KEY: InjectionKey<FieldFocusController>;
+export declare function provideFieldFocus(controller: FieldFocusController): void;
+/** Absent whenever the fields tree is rendered outside `BxTemplateEditor`. */
+export declare function useFieldFocus(): FieldFocusController | undefined;
+/** Marks the focused field for a moment so the eye can follow the jump. */
+export declare const FIELD_FOCUS_FLASH_CLASS = "bx-field-hint-target";
+/**
+ * Scroll a field's control into view, flash it, and focus the first thing in it
+ * that can take focus.
+ *
+ * `block: 'nearest'` rather than 'center': the fields panel is a scroll
+ * container, and centering yanks the whole list even when the target was
+ * already comfortably visible.
+ */
+export declare function revealFieldElement(el: HTMLElement | null | undefined): void;
+/**
+ * Creates the desktop half: a registry keyed by the field object itself.
+ *
+ * A WeakMap (not a Map) because fields are plain objects off the serial — when
+ * the serial is swapped the old field objects should simply be collectable,
+ * with no unregister bookkeeping to get wrong.
+ */
+export declare function createFieldElementRegistry(): {
+    register(field: BluepicField, el: HTMLElement | null): void;
+    get(field: BluepicField): HTMLElement | undefined;
+    registerActivator(field: BluepicField, activate: FieldActivator | null): void;
+    activate(field: BluepicField): boolean;
+};
+/**
+ * Registers a field component's own editing flow for the lifetime of that
+ * component. A no-op outside `BxTemplateEditor`, where no controller is provided.
+ */
+export declare function useFieldActivator(field: () => BluepicField | undefined, activate: FieldActivator): void;

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

@@ -6,3 +6,10 @@ export { frameIndexOfPoint, hintPriorityClass, orderHitboxes, quadAABB, quadArea
 export type { OrderableHitbox } from './geometry';
 export { useFieldHitboxes } from './useFieldHitboxes';
 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 { useFieldActivator } from './fieldFocus';
+export type { FieldActivator } from './fieldFocus';

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

@@ -0,0 +1,21 @@
+import type { BluepicField } from '@bluepic/types';
+/**
+ * What an `interact` hint does when clicked.
+ *
+ * - `inline-text` — expand into a text input on the overlay, editing the value
+ *   in place. Only for plain-text fields: a richtext field's value is a run
+ *   array with its own toolbar, and a bare input would silently flatten it.
+ * - `activate`    — run the field's own flow (image picker / upload dialog),
+ *   via the activator the field component registered.
+ * - `focus`       — nothing better available; jump to the control in the panel.
+ */
+export type InteractMode = 'inline-text' | 'activate' | '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 interactModeFor(field: BluepicField, evaluate?: (fn: Function) => unknown): InteractMode;
+/** The binding an inline text editor reads and writes. */
+export declare function inlineTextBinding(field: BluepicField): string | undefined;

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

@@ -0,0 +1,9 @@
+import { type Ref } from 'vue';
+export declare function useHintReveal(enabled: Ref<boolean>): {
+    revealed: Ref<boolean, boolean>;
+    hide: () => void;
+    onPointerEnter: (event: PointerEvent) => void;
+    onPointerLeave: (event: PointerEvent) => void;
+    onPointerDown: (event: PointerEvent) => void;
+    onPointerUp: (event: PointerEvent) => void;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluepic/embed",
-  "version": "0.4.0-next.142",
+  "version": "0.4.0-next.144",
   "description": "Bluepic embed sdk",
   "type": "module",
   "sideEffects": false,
@@ -45,7 +45,7 @@
   },
   "devDependencies": {
     "@auth0/auth0-vue": "^2.4.0",
-    "@bluepic/types": "^0.6.494",
+    "@bluepic/types": "^0.6.497",
     "@hono/zod-openapi": "^1.1.4",
     "@types/css": "^0.0.38",
     "@types/downloadjs": "^1.4.6",