uhuu-components 0.4.0 → 0.4.2

package/index.d.ts

@@ -414,6 +414,246 @@ export interface ImageUrlOptions {
  */
 export function imageUrl(src: ImageSource, options?: ImageUrlOptions): string | undefined;
 
+// --- Image frames (src/uhuu/frame/). See docs/frame-block.md. ---
+// The read helpers are the vendored `uhuu.frame.v1` module (src/uhuu/frame/vendor, generated from
+// uhuu-editor-dialogs). dist ships this file alone, so the module's types are mirrored here;
+// test/frame-vendor.test.mjs checks the mirror against the vendored source.
+
+/** `value.uhuuFrame.schema` of a frame. */
+export const FRAME_SCHEMA: "uhuu.frame.v1";
+/** Key of the frame record inside a frame value. Namespaced so it cannot collide with template keys. */
+export const FRAME_KEY: "uhuuFrame";
+
+/** Which legacy image wins when an old value carries both a generated image and a pick. */
+export type FrameLegacyPrecedence = "generated" | "pick";
+
+/** A transform applied to a source's image (crop, AI enhance, …). Its base is the previous step. */
+export interface FrameStep {
+  type: string;
+  url: string;
+  width?: number;
+  height?: number;
+  mimeType?: string;
+  /** Replayable parameters or result metadata (crop box, AI asset id, …). */
+  state?: Record<string, unknown>;
+}
+
+/** An overlay drawn over a source's image by the page (annotation). Never composited into the image. */
+export interface FrameLayer {
+  state: unknown;
+  /** The image the overlay was drawn on. */
+  baseUrl?: string;
+  /** The image under the overlay changed after it was drawn. */
+  stale?: boolean;
+}
+
+/** One dialog's own entry: its last image, the state it reopens with, its steps and layers. */
+export interface FrameSource {
+  /** Absent for state-only saves (a map saved without a design image). */
+  url?: string;
+  /** Key the dialog used for its URL (`image` for generated dialogs); reproduced when it reopens. */
+  urlKey?: string;
+  width?: number;
+  height?: number;
+  mimeType?: string;
+  /** Everything else the dialog saved, URL keys removed. */
+  state?: Record<string, unknown>;
+  steps?: FrameStep[];
+  layers?: Record<string, FrameLayer>;
+}
+
+/** One-level undo: the active source before the last action and the entry it changed. */
+export interface FrameUndo {
+  active: string | null;
+  /** Source entry the action changed; absent when only `active` moved. */
+  type?: string;
+  /** That entry before the action; `null` when the action created it. */
+  before?: FrameSource | null;
+}
+
+/** `value.uhuuFrame`: every source the slot holds and the one it shows. */
+export interface FrameRecord {
+  schema: "uhuu.frame.v1";
+  active: string | null;
+  sources: Record<string, FrameSource>;
+  previous?: FrameUndo;
+}
+
+/**
+ * A frame value as stored in the payload. Its top level mirrors the active source in the shape it
+ * saved before frames — a map's image under `image`, a pick's under `contentUrl`, both also under
+ * `url` — so `imageUrl(value)` and the readers templates already have keep working.
+ */
+export type FrameValue = Record<string, unknown> & { uhuuFrame: FrameRecord };
+
+export interface FrameOptions {
+  /** Source types the field declares, in order. Resolves a legacy generated shape with no identifying key (a bare `{ image }`). */
+  sources?: readonly string[];
+  /** Default `'generated'`. Implenia IM passes `'pick'`. */
+  legacyPrecedence?: FrameLegacyPrecedence;
+  /**
+   * A legacy generated value whose upload failed keeps its render as a `data:` URL
+   * (`dataImage`). `'show'` (default) shows it, as Implenia IM, implenia-teaser and jbre's
+   * cadastral do; `'ignore'` treats the source as having no image, as wuw, evernest, go and
+   * jbre's map do (their placeholder shows). New saves never carry one.
+   */
+  legacyDataImage?: 'show' | 'ignore';
+  /**
+   * Also draw the overlay a source dialog keeps in its own state (cadastral's
+   * `annotationSvg`). Off by default: the cadastral dialog bakes that outline into its image.
+   */
+  intrinsicOverlays?: boolean;
+  /** A legacy overlay saved at a separate path (`annotationPath`); folded into the active source. */
+  legacyLayer?: unknown;
+  /** Layer type the legacy overlay becomes. Default `'annotation'`. */
+  legacyLayerType?: string;
+}
+
+export interface FrameDisplay {
+  /** The image to show; `''` when there is none. */
+  url: string;
+  width?: number;
+  height?: number;
+  mimeType?: string;
+  /** Active source type. */
+  source: string | null;
+  /** Number of transforms applied on top of the source image. */
+  steps: number;
+}
+
+export interface FrameOverlay {
+  /** Layer type, or the source type for an overlay the source dialog drew itself (cadastral). */
+  key: string;
+  svg: string;
+  stale: boolean;
+  /** Drawn by the source dialog as part of its own output. */
+  intrinsic: boolean;
+}
+
+/** The image an image-accepting dialog opens with (`eventData.input`). */
+export interface FrameImageInput {
+  url: string;
+  width?: number;
+  height?: number;
+  mimeType?: string;
+  /** Frame source the image comes from. */
+  source?: string;
+}
+
+/** True when `value` carries a `uhuu.frame.v1` record. */
+export function isFrameValue(value: unknown): value is FrameValue;
+
+/**
+ * The frame record of any value: a frame (validated), or a value saved before frames (URL string,
+ * ImageObject, a generated dialog's output) read into one in memory. Never writes. `null` for an
+ * empty slot. A frame whose mirrored `contentUrl` was patched by a writer that does not know frames
+ * reads that patch as the newest pick.
+ */
+export function normalizeFrame(value: unknown, options?: FrameOptions): FrameRecord | null;
+
+/** What the page should show for this value: URL, size and the source it comes from. */
+export function frameDisplay(value: unknown, options?: FrameOptions): FrameDisplay;
+
+/** The image URL to show for a frame or legacy value; `''` when there is none. */
+export function frameImage(value: unknown, options?: FrameOptions): string;
+
+/** The active source type, or `null`. */
+export function frameActive(value: unknown, options?: FrameOptions): string | null;
+
+/** The input an image-accepting dialog opens with; `null` when nothing is shown. */
+export function frameInput(value: unknown, options?: FrameOptions): FrameImageInput | null;
+
+/**
+ * The overlays to draw over the shown image, bottom to top: the source dialog's own overlay
+ * (cadastral's `annotationSvg`), then the active source's layers. Stale layers are included.
+ */
+export function frameOverlays(value: unknown, options?: FrameOptions): FrameOverlay[];
+
+/**
+ * The value a source dialog reopens with, in the shape it saved (`{ list, home, mapbox, image }` for
+ * the map). `undefined` when the source has never been saved.
+ */
+export function frameSourceView(value: unknown, type: string, options?: FrameOptions): Record<string, unknown> | undefined;
+
+/** Any value as a stored frame, showing what it showed before. `null` for an empty slot. */
+export function toFrameValue(value: unknown, options?: FrameOptions): FrameValue | null;
+
+/**
+ * The options every reader of a slot passes, from its declaration: its sources, legacy
+ * precedence, failed-upload rule, and the overlay saved at `annotationPath` (read from `payload`).
+ */
+export function frameOptionsOf(declaration: Partial<FrameDeclaration>, payload?: unknown): FrameOptions;
+
+/** The image shown now and the overlay saved at `annotationPath`: what an editor without frames annotates. */
+export interface FrameLegacyCurrent {
+  image?: string;
+  annotation?: unknown;
+}
+
+/**
+ * `{ path, frame, types }`: the message `$uhuu.editFrame` sends, for an `ImageBlock` `dialog` or an
+ * SDK without `editFrame`. `types` is the chooser an editor without frames shows. `null` without a
+ * `path` or a source with a `type`.
+ */
+export function frameEditDialog(
+  declaration: FrameDeclaration,
+  current?: FrameLegacyCurrent | null,
+): { path: string; frame: Omit<FrameDeclaration, "path">; types: Record<string, unknown>[] } | null;
+
+/** Opens a frame from a template's own click handler: `$uhuu.editFrame` when the SDK has it, else `editDialog` with `frameEditDialog`'s message. No host, no call. */
+export function openFrame(declaration: FrameDeclaration, current?: FrameLegacyCurrent | null): void;
+
+/** One dialog a frame offers: its type, its title in the chooser, and that dialog's own options. */
+export interface FrameDialogEntry {
+  type: string;
+  title?: string;
+  /** The dialog's configuration (coordinates, styles, zoom, `visualGallery`, …). */
+  config?: Record<string, unknown>;
+  /** Other options for that dialog (`imageGalleryPath`, `galleryUpload`, …). */
+  [key: string]: unknown;
+}
+
+/** What `$uhuu.editFrame` takes (uhuu-sdk): the slot and the dialogs it offers. */
+export interface FrameDeclaration {
+  /** Where the frame is saved. */
+  path: string;
+  /** The dialogs that create the image (`map`, `satellite`, `cadastral`, `image`, …), in chooser order. */
+  sources: FrameDialogEntry[];
+  /** Overlays drawn over the shown image (`annotation`). */
+  layers?: FrameDialogEntry[];
+  /** Transforms offered on the shown image (`image-editor`, `ai-marketing-studio`). Default: all the editor offers; `false` for none. */
+  transforms?: string[] | false;
+  /** Crop aspect ratio, width / height. */
+  ratio?: number;
+  /** Which image an old document shows when it holds both a generated image and a pick. Default `'generated'`. */
+  legacyPrecedence?: FrameLegacyPrecedence;
+  /** Whether an old map whose upload failed shows its unsaved render (`'show'`, default) or the placeholder (`'ignore'`). */
+  legacyDataImage?: 'show' | 'ignore';
+  /** An overlay saved at its own path before frames. Pass its value as FrameBlock's `annotation`. */
+  annotationPath?: string;
+}
+
+export interface FrameBlockProps extends FrameDeclaration, Omit<ImageBlockProps, "src" | "dialog" | "annotation"> {
+  /** The value at `path`: a frame, or anything saved there before frames. */
+  value?: unknown;
+  /** Also draw a source's own outline (cadastral `annotationSvg`); off because the cadastral image has it baked in. */
+  intrinsicOverlays?: boolean;
+  /** The overlay value saved at `annotationPath`; read as the active source's layer until the frame holds its own. */
+  annotation?: ImageBlockAnnotationValue | null;
+  /** Rendered instead of the frame's image: a template adapter's own URL. */
+  src?: string;
+  /** `imageUrl` options for the shown image (`print`, `size`, `printSize`, `format`). */
+  imageUrlOptions?: ImageUrlOptions;
+}
+
+/**
+ * An image slot several dialogs write (map, satellite, cadastral, gallery pick, crop, annotation),
+ * stored as a `uhuu.frame.v1` value. Renders the shown image through `imageUrl` with every overlay
+ * of the active source over it, and opens `$uhuu.editFrame` on click in the editor (`editDialog`
+ * with the legacy `types` on an older SDK; nothing in renderer mode). Layout props are ImageBlock's.
+ */
+export const FrameBlock: ComponentType<FrameBlockProps>;
+
 // --- Brand-kit runtime (src/uhuu/brand-kit/). See docs/brand-kit-runtime.md. ---
 
 export interface BrandKitFontFile {
@@ -852,7 +1092,8 @@ export interface PageEditorTemplateConfig {
 
 export interface PageOptionSelectValue {
   label: LocalizedText;
-  value: string;
+  /** Matched to the stored value as a string (`2` is `"2"`); a payload option writes it typed by `valueType`. */
+  value: string | number | boolean;
   hex?: string;
 }
 
@@ -883,12 +1124,27 @@ export type ColorSeriesPageOption = BasePageOption & {
 };
 export type PageOption = SelectPageOption | TogglePageOption | SliderPageOption | CounterPageOption | ColorSeriesPageOption;
 
+/** How a payload option writes a choice: default `boolean` for a toggle, `number` for a slider or counter, else `string`. */
+export type OptionValueType = "string" | "number" | "boolean";
+
+/** What a payload option (a page option without callbacks, or a document option) adds to its control. */
+interface PayloadOptionStorage {
+  /** Shown while the payload holds no value (`stored ?? defaultValue`). */
+  defaultValue?: any;
+  /** The stored key. Default: `id`. */
+  field?: string;
+  valueType?: OptionValueType;
+}
+
 type PayloadOptionFor<Option> = Option extends PageOption
-  ? Omit<Option, "getValue" | "onChange" | "applyPatch"> & { defaultValue?: any; field?: string }
+  ? Omit<Option, "getValue" | "onChange" | "applyPatch"> & PayloadOptionStorage
   : never;
-/** A page option stored automatically in `payload.pages`, without custom callbacks. */
+/** A page option stored automatically in `payload.pages[pageId]`, without custom callbacks. */
 export type PayloadOptionDefinition = PayloadOptionFor<PageOption>;
 
+/** The corner of PageEditor's floating toolbar. */
+export type ToolbarPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+
 export interface PageEditorProps {
   /** Pages, groups and initial items; `pageManagement` sets the page-management controls. */
   templateConfig: PageEditorTemplateConfig;
@@ -907,6 +1163,12 @@ export interface PageEditorProps {
   pageFilter?: PageFilterConfig;
   printConfigs?: PrintConfigMap;
   defaultZoomMode?: PageEditorDefaultZoomMode;
+  /**
+   * The corner the floating toolbar (page count, Add, Reorder, document options, zoom) starts in.
+   * Default `bottom-right`. A user moves it from the zoom menu; their corner is remembered in the
+   * browser and wins over this one.
+   */
+  toolbarPosition?: ToolbarPosition;
   onItemsChange?: (items: PageItem[], state: PageEditorState) => void;
   onStateChange?: (state: PageEditorState) => void;
   /**
@@ -963,26 +1225,32 @@ export interface IntegrationAdapter {
   [key: string]: unknown;
 }
 
+type DocumentOptionFor<Option> = Option extends PageOption
+  ? Omit<Option, "getValue" | "onChange" | "applyPatch" | "appliesTo"> & PayloadOptionStorage
+  : never;
+
 /**
- * One document-level option: a top-level payload key the template reads (`payload.language`).
- * The shape `uhuu templates theme inspect <templateId> --snippet` prints from a legacy template
- * theme. See docs/document-options.md.
+ * The 0.4 shape, as `uhuu templates theme inspect <templateId> --snippet` prints a legacy theme:
+ * `key` names the payload key, and a select may leave out `type`.
+ * @deprecated Define document options as payload page options are, with `id`.
  */
-export interface DocumentOptionDefinition {
-  /** The top-level payload key, the same one the platform's theme option wrote. */
+export interface LegacyDocumentOptionDefinition {
   key: string;
-  /** Default `select`. */
   type?: "select" | "toggle";
   label: LocalizedText;
   description?: LocalizedText;
-  /** A select's choices. A stored value matches a choice as a string: `2` matches `"2"`. */
   options?: Array<{ value: string | number | boolean; label: LocalizedText }>;
-  /** Shown while the payload has no value for the key (`payload[key] ?? defaultValue`). */
   defaultValue?: unknown;
-  /** Local onChange previews: default `string` for a select, `boolean` for a toggle. Editor selects save strings. */
-  valueType?: "string" | "number" | "boolean";
+  valueType?: OptionValueType;
 }
 
+/**
+ * One document-level option: a top-level payload key the template reads (`payload.language`),
+ * defined, valued and drawn as a payload page option is (`id` names the key, `field` overrides
+ * it). See docs/document-options.md.
+ */
+export type DocumentOptionDefinition = DocumentOptionFor<PageOption> | LegacyDocumentOptionDefinition;
+
 export interface DocumentOptionsProps {
   /**
    * The payload the template renders. Required outside a TemplateDataProvider; inside one, the
@@ -993,14 +1261,13 @@ export interface DocumentOptionsProps {
   /** Heading of the control. Default: "Document options" in the shell's interface language. */
   title?: LocalizedText;
   /**
-   * Called for local choices when no supported $uhuu.editDialog is available. The editor field
-   * saves through the next payload update and does not call onChange.
+   * Called for local choices, when there is no uhuu document editor on the page. In the editor a
+   * choice arrives through the next payload update.
    */
   onChange?: (key: string, value: unknown) => void;
-  /**
-   * Inside PageEditor's floating toolbar: the entry's wrapper. Otherwise the control's own
-   * floating bar, bottom right by default (move it with `style`, e.g. `{ top: 16, bottom: "auto" }`).
-   */
+  /** The corner of the control's own floating bar, drawn when no PageEditor toolbar is on screen. Default `bottom-right`. */
+  toolbarPosition?: ToolbarPosition;
+  /** Inside PageEditor's floating toolbar: the entry's wrapper. Otherwise the control's own floating bar. */
   className?: string;
   style?: CSSProperties;
 }
@@ -1012,9 +1279,10 @@ export const EditorShell: {
   useInteractive: () => InteractiveModeContextValue;
   useIntegrationAdapter: (config: IntegrationAdapterConfig) => IntegrationAdapter;
   /**
-   * Document-level switches for top-level payload keys, edited through the released editor's
-   * `$uhuu.editDialog` field. Joins the nearest InteractiveModeProvider's PageEditor toolbar, else floats bottom right.
-   * Hidden outside edit mode, in the PDF renderer and in print. See docs/document-options.md.
+   * Document-level options for top-level payload keys, defined and drawn as page options are. A
+   * choice is an edit in the uhuu document editor. Joins the nearest InteractiveModeProvider's
+   * PageEditor toolbar, else floats in a corner. Hidden outside edit mode, in the PDF renderer and
+   * in print. See docs/document-options.md.
    */
   DocumentOptions: ComponentType<DocumentOptionsProps>;
 };

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.0",
+  "version": "0.4.2",
   "name": "uhuu-components",
   "main": "uhuu-components.umd.cjs",
   "module": "uhuu-components.es.js",