@bluepic/embed 0.4.0-next.99 → 0.5.1

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

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

package/dist/util/fieldTree.d.ts

@@ -0,0 +1,20 @@
+import type { BluepicField } from '@bluepic/types';
+/**
+ * Pure field-tree walks, deliberately kept OUT of `./fields.ts`.
+ *
+ * `fields.ts` imports the per-type icon components, so importing anything from
+ * it drags a dozen Vue SFCs along — fine in the browser bundle, fatal for any
+ * consumer that runs outside Vite (Node tests, headless tooling). These
+ * functions are plain logic over the field tree and have no such need.
+ *
+ * `fields.ts` re-exports `flattenFieldTable` so existing imports keep working.
+ */
+/**
+ * Every LEAF field, in document order. `Group` is pure presentation — it holds
+ * no binding of its own — so it is flattened away rather than returned.
+ *
+ * `Collection` is NOT descended into: its nested `props.fields` are the
+ * per-item template, not fields with live bindings, while the Collection field
+ * itself does carry a `modelValue`. So it is returned as the leaf it behaves as.
+ */
+export declare function flattenFieldTable(fields: BluepicField[]): BluepicField[];

package/dist/util/fields.d.ts

@@ -10,7 +10,7 @@ export declare function modelField(model: BluepicField['model'], data: Ref<{
     [x: string]: unknown;
 };
 export declare function flattenFields(fields: BluepicField[]): MobileFieldsSlide[];
-export declare function flattenFieldTable(fields: BluepicField[]): BluepicField[];
+export { flattenFieldTable } from './fieldTree';
 export declare function useMobileFields(fields: Ref<BluepicField[]>): {
     mobileFields: import("vue").ComputedRef<{
         originalField: BluepicFieldGroup | undefined;

package/dist/util/gallery.d.ts

@@ -1,47 +1,95 @@
 import { Studio } from '@bluepic/types';
 import { z } from '@hono/zod-openapi';
+/**
+ * A multi-canvas template (canvases v2) is ATOMIC in the gallery: its canvases
+ * ARE its format variants, so it never merges with same-named templates — and
+ * two multi-canvas templates sharing a name stay two cards. Single-format
+ * templates keep merging by name exactly as before.
+ */
+export declare function isMultiCanvasTemplateDescriptor(td: Pick<z.infer<typeof Studio.publicTemplateDescriptor>, 'canvases'>): boolean;
 export declare function groupTemplatesByName(templates: {
     [k: string]: z.infer<typeof Studio.publicTemplateDescriptor>;
 }): {
     [k: string]: {
-        [k: string]: z.infer<z.ZodObject<{
-            serial: z.ZodNullable<z.ZodAny>;
-            preview: z.ZodNullable<z.ZodString>;
-            name: z.ZodString;
-            width: z.ZodNumber;
-            height: z.ZodNumber;
-            category: z.ZodNullable<z.ZodString>;
-            dpi: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strip>>;
+        [k: string]: {
+            serial: any;
+            preview: string | null;
+            name: string;
+            width: number;
+            height: number;
+            dpi?: number | undefined;
+            canvases?: {
+                id: string;
+                width: number;
+                height: number;
+                label?: string | undefined;
+                preview?: string | null | undefined;
+            }[] | undefined;
+        };
     };
 };
+export declare const OTHER_CATEGORY = "Other";
+export type PortalAsset = z.infer<typeof Studio.publicCampaignAssetDescriptor>;
+export type CampaignCategory = Studio.CampaignCategory;
 /**
- * A campaign-level template→category override map (`config.categories`), keyed
- * by TEMPLATE ID. When an entry exists for a template it wins over the
- * template's own `category`; templates with no entry fall back to their
- * descriptor category. `undefined`/empty categories collapse into "Other".
+ * The one ordering for portal assets — alphabetical by title, same as the
+ * campaign editor. Used both within a category bucket and for the flat,
+ * uncategorised list, so toggling "sort by categories" only changes GROUPING,
+ * never the relative order of two given assets.
  */
-export type CampaignCategories = {
-    [templateId: string]: string;
-} | undefined;
-export declare function collectTemplatesCategories(templates: {
-    [k: string]: z.infer<typeof Studio.publicTemplateDescriptor>;
-}, overrides?: CampaignCategories): string[];
-export declare function groupTemplatesByCategory(templates: {
+export declare function sortPortalAssetsByTitle(assets: PortalAsset[]): PortalAsset[];
+/**
+ * Group templates AND assets by the campaign's categories.
+ *
+ * Takes the CONVERTED category array — `Studio.convertCampaign` has already run
+ * at the boundary — so there is no shape-guessing here, no legacy record, and
+ * no separate order field: array position IS the order.
+ *
+ * Anything no category claims falls into "Other", which always renders last.
+ * Categories that end up empty are dropped: an empty category is legitimate
+ * while editing, but not something to render a tab for.
+ */
+export declare function groupPortalItemsByCategory(templates: {
     [k: string]: z.infer<typeof Studio.publicTemplateDescriptor>;
-}, overrides?: CampaignCategories): {
+}, assets: PortalAsset[] | undefined, categories: CampaignCategory[] | undefined): {
     category: string;
     templatesByName: {
         [k: string]: {
-            [k: string]: z.infer<z.ZodObject<{
-                serial: z.ZodNullable<z.ZodAny>;
-                preview: z.ZodNullable<z.ZodString>;
-                name: z.ZodString;
-                width: z.ZodNumber;
-                height: z.ZodNumber;
-                category: z.ZodNullable<z.ZodString>;
-                dpi: z.ZodOptional<z.ZodNumber>;
-            }, z.core.$strip>>;
+            [k: string]: {
+                serial: any;
+                preview: string | null;
+                name: string;
+                width: number;
+                height: number;
+                dpi?: number | undefined;
+                canvases?: {
+                    id: string;
+                    width: number;
+                    height: number;
+                    label?: string | undefined;
+                    preview?: string | null | undefined;
+                }[] | undefined;
+            };
         };
     };
+    assets: {
+        id: string;
+        kind: "image" | "file";
+        title: string;
+        description: string | null;
+        category: string | null;
+        mime: string;
+        size: number;
+        filename: string;
+        previewUrl: string | null;
+        downloadUrl: string;
+        width?: number | undefined;
+        height?: number | undefined;
+        pageCount?: number | undefined;
+        documentUrl?: string | undefined;
+    }[];
 }[];
+/** The category strip: only labels that actually have something in them. */
+export declare function collectPortalCategories(templates: {
+    [k: string]: z.infer<typeof Studio.publicTemplateDescriptor>;
+}, assets: PortalAsset[] | undefined, categories: CampaignCategory[] | undefined): string[];

package/dist/util/popoverArrow.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The popover/tooltip arrow artwork, shared by everything that needs to point
+ * at something.
+ *
+ * The arrow isn't a CSS triangle: it has a rounded tip and flared sides, drawn
+ * as an SVG path, and it renders as TWO masked layers — a fill layer tinted
+ * with the surface colour, and a border layer tinted with the border colour,
+ * built from an outline-only mask so the arrow's outline continues the
+ * bubble's. That's what makes it read as part of the bubble rather than a
+ * triangle stuck to it.
+ *
+ * The shape is authored pointing LEFT. Every other direction is a CSS rotation
+ * of the same mask at the call site, so there is one source of truth for the
+ * geometry and callers only own their placement.
+ *
+ * Extracted from `PopoverElement.vue` so the field-hint overlay can reuse the
+ * same arrow instead of growing a second, subtly different one.
+ */
+declare const ARROW_VIEWBOX: readonly [0, 0, 540, 810];
+/** Outer silhouette — the arrow as the reader sees it. */
+declare const ARROW_SHAPE = "\n<g transform=\"matrix(-1,0,-0,-1,539.059,810)\">\n  <path d=\"M11.046,422.072C-6.191,410.25 -0.941,397.5 11.046,387.928L539.059,0L539.059,810L11.046,422.072Z\"/>\n</g>\n";
+/**
+ * Slightly inset copy of the silhouette. Subtracting it from the outer shape
+ * leaves a constant-width outline — the border layer. A plain stroke would
+ * thicken unevenly around the curved tip.
+ */
+declare const ARROW_INNER_SHAPE = "\n<g transform=\"matrix(-0.926069,0,-0,-0.926069,499.205868,780.057974)\">\n  <path d=\"M0.498,414.688C-13.575,404.976 -4.105,398.555 4.717,392.147L539.059,0L539.059,810L0.498,414.688Z\"/>\n</g>\n";
+declare const ARROW_STROKE_WIDTH = 100;
+/** `mask-image` value for the arrow's filled body. */
+export declare function popoverArrowMaskImage(): string;
+/** `mask-image` value for the arrow's outline. */
+export declare function popoverArrowBorderMaskImage(): string;
+export { ARROW_VIEWBOX, ARROW_SHAPE, ARROW_INNER_SHAPE, ARROW_STROKE_WIDTH };

package/dist/util/popupHeaderTools.d.ts

@@ -0,0 +1,26 @@
+import { type InjectionKey, type Ref } from 'vue';
+/**
+ * A channel for putting controls INTO the popup's own header.
+ *
+ * A popup owns its header — title, actions, close button — while the thing
+ * rendered inside it owns the state those actions act on. The asset viewer's
+ * Preview/Source switch is the case in point: it belongs visually beside the
+ * Download button, but the text it copies and the view it toggles live in the
+ * viewer, three levels down.
+ *
+ * Rather than lift that state into every host that opens a popup, the popup
+ * publishes the header's action container as an element ref and descendants
+ * TELEPORT into it. The control renders where it belongs while its state stays
+ * where it belongs.
+ *
+ * Null when there is no popup ancestor — a component using this must keep
+ * working standalone, so treat it as "no header available" and render inline.
+ */
+export declare const popupHeaderToolsKey: InjectionKey<Ref<HTMLElement | null>>;
+/** Called by the popup itself. Returns the ref to bind to the tools container. */
+export declare function providePopupHeaderTools(): Ref<HTMLElement | null>;
+/**
+ * Called by content inside a popup. The returned ref resolves after mount, so
+ * teleport with `v-if` on it rather than reading it during setup.
+ */
+export declare function usePopupHeaderTools(): Ref<HTMLElement | null>;

package/dist/util/scrollPassthrough.d.ts

@@ -0,0 +1,9 @@
+import { type Ref } from 'vue';
+/**
+ * Forward wheel/touch gestures that land on `wrapperRef`'s own backdrop to the
+ * app behind it. Gestures over the popover's content are left alone.
+ *
+ * @param wrapperRef the full-viewport popover wrapper
+ * @param enabled    re-evaluated on every gesture, so a popover can flip modes
+ */
+export declare function useScrollPassthrough(wrapperRef: Ref<HTMLElement | undefined>, enabled: () => boolean): void;

package/dist/util/useTheme.d.ts

@@ -1,5 +1,40 @@
 import { z } from '@hono/zod-openapi';
 import { EmbedV2 } from '@bluepic/types';
+import { Ref, type MaybeRefOrGetter } from 'vue';
+import { type ResolvedTheme, type ThemeInput } from '../theme';
+/**
+ * @deprecated Legacy engine. Parses a preset SCSS dump into a flat variable map. Kept only so
+ * campaigns without `config.theme` keep rendering exactly as before; new code should use
+ * `resolveTheme()` / `useThemeV2()` (theme system v2). Will be removed once no legacy campaigns remain.
+ */
 export declare function getThemeStyle(rawCSS: string): Record<string, string>;
+/** @deprecated Legacy engine — see `getThemeStyle`. Use `resolveTheme({ version: 2, preset })` + `themeToCssText()` instead. */
 export declare function resolveThemeStyle(theme: 'light' | 'dark' | 'auto'): Record<string, string>;
-export declare function useTheme(bluepicAppWrapperSelector?: string, theme?: 'light' | 'dark' | 'auto', customThemeVars?: Partial<z.infer<typeof EmbedV2.customStyleSchema>>, interFontUrl?: string): any;
+export type UseThemeV2Options = {
+    /** Selector of the app wrapper (default: GLOBAL_APP_WRAPPER_SELECTOR). */
+    wrapperSelector?: string;
+    /** Optional @import for the UI font (e.g. Inter). */
+    fontUrl?: string;
+    /**
+     * Legacy `customStyle` snapshot to fall back to when the input is empty — only its
+     * surface/primary/contrast are used (see themeInputFromLegacyCustomStyle).
+     */
+    legacyCustomStyle?: MaybeRefOrGetter<Record<string, string> | null | undefined>;
+};
+/**
+ * Reactive v2 theme binding. Re-resolves whenever the input changes and rewrites the SAME
+ * style element. Returns the resolved theme (tokens + contrast report) for hosts that want to
+ * show it (e.g. the Studio theme step).
+ */
+export declare function useThemeV2(input: MaybeRefOrGetter<ThemeInput | null | undefined>, options?: UseThemeV2Options): {
+    theme: import("vue").ComputedRef<ResolvedTheme>;
+    uid: string;
+};
+/** Imperative one-shot application (no reactivity). */
+export declare function applyTheme(theme: ResolvedTheme, options?: Omit<UseThemeV2Options, 'legacyCustomStyle'>): string;
+/**
+ * Legacy API. `customThemeVars` may be a legacy customStyle record (preset snapshot + overrides)
+ * or, as of v2, a `ThemeInput` (`{ version: 2, surface, primary, … }`), in which case the new
+ * engine is used. The returned ref holds the emitted CSS variables.
+ */
+export declare function useTheme(bluepicAppWrapperSelector?: string, theme?: 'light' | 'dark' | 'auto', customThemeVars?: Partial<z.infer<typeof EmbedV2.customStyleSchema>> | ThemeInput, interFontUrl?: string): Ref<Record<string, string>, Record<string, string>>;

package/dist/util/visualViewport.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The on-screen keyboard, as iOS actually reports it.
+ *
+ * iOS Safari does NOT shrink the layout viewport when the keyboard opens:
+ * `window.innerHeight`, `100vh` and even `100dvh` stay exactly as they were
+ * (`dvh` tracks the URL bar collapsing, not the keyboard). The only thing that
+ * reports the covered space is `visualViewport` — so any layout that has to
+ * react to the keyboard has to be driven from JS. There is no CSS-only
+ * equivalent on iOS.
+ *
+ * Android Chrome behaves differently by default (it resizes the layout
+ * viewport), which this handles for free: the inset simply computes to ~0
+ * because `innerHeight` shrank along with the visual viewport.
+ */
+export declare function useVisualViewport(): {
+    supported: boolean;
+    height: import("vue").Ref<number, number>;
+    offsetTop: import("vue").Ref<number, number>;
+    keyboardInset: import("vue").Ref<number, number>;
+    keyboardOpen: import("vue").Ref<boolean, boolean>;
+};
+/**
+ * Scroll the PAGE so `el`'s top edge meets the top of the visible band.
+ *
+ * Used on an element that has already been sized to FIT the band, so aligning
+ * its top is the whole job — there is no "scroll to the field" here. Scrolling
+ * to a target inside a box that is about to get shorter is what produced the
+ * drift: the scroll landed first and the content then shrank out from under it.
+ *
+ * Why not `scrollIntoView`: it scrolls every scrollable ancestor, and on the
+ * mobile layout one of those is swiper's track — which positions its slides by
+ * transform. Scrolling it leaves swiper's own offset wrong and the panel
+ * misaligned. Moving the page and nothing else is the whole job.
+ *
+ * Why not just `focus()` without `preventScroll`: same reason, plus iOS ignores
+ * it for a programmatic focus often enough to be useless — which is why the
+ * field only jumped into view once the user typed.
+ *
+ * The keyboard animates over ~250–400ms and fires several `resize` events on
+ * the way; we wait for a quiet moment rather than guessing a delay, with a hard
+ * stop for the case where no keyboard is coming at all (a hardware keyboard, a
+ * desktop browser, a field that opened no keyboard).
+ */
+export declare function revealAboveKeyboard(el: HTMLElement | undefined, { margin, hardStopMs }?: {
+    margin?: number | undefined;
+    hardStopMs?: number | undefined;
+}): void;