@twip/web 0.0.0-canary-abcb2d5 → 0.0.0-canary-6f0bf0b

package/dist/commands.d.ts

@@ -1,5 +1,5 @@
 import type { RichText } from './review.js';
-import type { ControlKind, ControlOptions, DataBinding, ReferenceRule } from './services/elements.js';
+import type { ControlKind, ControlOptions, DataBinding, ReferenceRule, SubTemplateVersion } from './services/elements.js';
 import type { TabAlignment, TabLeader, TabSelector } from './services/ruler.js';
 import type { ViewOptions } from './services/view.js';
 import type { AutoCorrectChange, HighlightColor, HorizontalPosition, LineSpacing, MarkupView, ObjectWrap, RowHeight, TablePosition, TableWidth, UnderlineStyle, VerticalPosition, WrapSide } from './state.js';
@@ -19,7 +19,10 @@ export interface PlaceholderLook {
     } | {
         prefix: string;
     } | 'default';
-    /** A fill, label and icon, or an image. */
+    /**
+     * A fill, label and icon, or an image. With `placeholderUi` on, `fill` is the input block's base colour: its tint,
+     * outlines and primary button are derived from it.
+     */
     look: {
         fill?: Color;
         label?: string;
@@ -28,6 +31,19 @@ export interface PlaceholderLook {
         image: Uint8Array;
         mime: string;
     };
+    /** The hint an input block shows while hovered. Default: "Click to add". */
+    hint?: string;
+    /** The buttons a selected input block shows, in order; none: a press on the block activates it. */
+    actions?: PlaceholderAction[];
+}
+/** A button on a selected input block: a press raises `placeholderActivated` with its `id` as `action`. */
+export interface PlaceholderAction {
+    /** What `placeholderActivated` names as `action`. */
+    id: string;
+    /** Its text. */
+    label: string;
+    /** Filled in the block's colour (the others are outlined); Enter presses it. Default: false. */
+    primary?: boolean;
 }
 /**
  * Every edit, one method per command. Each resolves after its change commits, with `getState()` already at that
@@ -476,6 +492,18 @@ export interface Commands {
         labels: Record<string, string>;
         merge?: boolean;
     }): Promise<void>;
+    /** The type text a field's caption shows, by field code (default: the field type, `MERGEFIELD`). View. */
+    setFieldTypes(options: {
+        types: Record<string, string>;
+        merge?: boolean;
+    }): Promise<void>;
+    /**
+     * The merge fields (by name, their first argument) the data source lacks: drawn neutral, struck through. Replaces
+     * the list, and `[]` clears it. View.
+     */
+    setUnmappedFields(options: {
+        names: string[];
+    }): Promise<void>;
     /** Which fields are sub-template references: replaces the rules; an empty list turns sub-templates off. View. */
     setSubTemplateRules(options: {
         rules: ReferenceRule[];
@@ -510,6 +538,10 @@ export interface Commands {
         name: string;
         category?: string;
     }): Promise<void>;
+    /** The version text sub-templates' cards and tabs show, and their newer versions; replaces the list. View. */
+    setSubTemplateVersions(options: {
+        versions: SubTemplateVersion[];
+    }): Promise<void>;
     /** Inserts a content control, optionally around the selection. */
     insertControl(options: {
         kind: ControlKind;
@@ -583,6 +615,14 @@ export interface Commands {
         looks: PlaceholderLook[];
         merge?: boolean;
     }): Promise<void>;
+    /** Draws a placeholder hovered until cleared (`null`), as when the application's field list hovers it. View. */
+    highlightElement(options: {
+        id: ElementId | null;
+    }): Promise<void>;
+    /** Selects the next placeholder in document order, wrapping; Tab while one is selected. View. */
+    selectNextPlaceholder(): Promise<void>;
+    /** Selects the previous placeholder in document order, wrapping; Shift+Tab while one is selected. View. */
+    selectPreviousPlaceholder(): Promise<void>;
     /** Fills the selected placeholder, or every unfilled one with `key`. */
     fillPlaceholder(options: {
         key?: string;
@@ -659,7 +699,7 @@ export interface Commands {
     setZoom(zoom: number | 'pageWidth' | 'wholePage'): Promise<void>;
     /**
      * Sets view options: formatting marks (Ctrl+Shift+8), gridlines, text boundaries, live layout, the chrome's theme
-     * and accent, the page's appearance, the measuring detail and the object grid.
+     * and accent, the page's appearance, the measuring detail, the object grid and the placeholder UI.
      */
     setViewOptions(options: ViewOptions): Promise<void>;
     /** Switches between editing and design mode. */

package/dist/commands.js

@@ -143,6 +143,8 @@ const encodings = {
     unlinkFields: 'spread',
     showFieldCodes: 'spread',
     setFieldLabels: 'spread',
+    setFieldTypes: 'spread',
+    setUnmappedFields: 'spread',
     setSubTemplateRules: 'spread',
     setSubTemplateView: 'spread',
     editSubTemplate: 'spread',
@@ -150,6 +152,7 @@ const encodings = {
     createSubTemplate: 'spread',
     renameSubTemplate: 'spread',
     removeSubTemplate: 'spread',
+    setSubTemplateVersions: 'spread',
     insertControl: 'spread',
     setControl: 'spread',
     removeControl: 'spread',
@@ -160,6 +163,9 @@ const encodings = {
     replaceInElements: 'spread',
     markElements: 'spread',
     setPlaceholderLooks: 'spread',
+    highlightElement: 'spread',
+    selectNextPlaceholder: 'none',
+    selectPreviousPlaceholder: 'none',
     fillPlaceholder: 'spread',
     writeDataPart: 'spread',
     removeDataPart: 'spread',

package/dist/events.d.ts

@@ -2,7 +2,7 @@ import type { EditorError } from './errors.js';
 import type { BalloonPlacement, CommentAnchor } from './review.js';
 import type { AnnouncementKind } from './services/accessibility.js';
 import type { DialogKind } from './services/dialogs.js';
-import type { ElementInfo } from './services/elements.js';
+import type { ElementInfo, SubTemplateReference } from './services/elements.js';
 import type { ContextMenuEvent } from './services/menus.js';
 import type { RulerView } from './services/ruler.js';
 import type { GestureEvent, Popover } from './services/view.js';
@@ -21,10 +21,29 @@ export interface TwipEvents {
         address: string;
         via: 'ctrlClick' | 'click';
     };
-    /** An unfilled picture placeholder was clicked. */
+    /**
+     * An unfilled picture placeholder was clicked, or one of its buttons (`action`: the button's id, or `replace` from a
+     * filled block's tab).
+     */
     placeholderActivated: {
         key: string;
         element: ElementId | null;
+        action?: string;
+    };
+    /**
+     * With `placeholderUi` on, the pointer starts or stops being over a placeholder, or the hovered one's anchor moves;
+     * `null` when it leaves.
+     */
+    placeholderHovered: PlaceholderTarget | null;
+    /**
+     * With `placeholderUi` on, the selection starts or stops covering exactly one placeholder, or the selected one's
+     * anchor moves (scroll, zoom, layout); `null` when it's no longer selected.
+     */
+    placeholderSelected: PlaceholderTarget | null;
+    /** A shown sub-template's newer-version notice (`setSubTemplateVersions`) was pressed: the application updates it. */
+    subTemplateUpdateRequested: {
+        name: string;
+        category: string;
     };
     /**
      * Typing, pasting or dropping was refused: into a sub-template's body shown in place of its reference (edit the
@@ -148,3 +167,26 @@ export interface Tooltip {
     /** The hovered thing's box. */
     rect: ClientRect;
 }
+/** What kind of placeholder a {@link PlaceholderTarget} is. */
+export type PlaceholderKind = 'field' | 'control' | 'repeatingSection' | 'subTemplate' | 'inputBlock' | 'ifField';
+/** A placeholder the pointer is over or the selection covers, with `placeholderUi` on. */
+export interface PlaceholderTarget {
+    /** The field or control; absent for an input block outside a content control. */
+    element?: ElementId;
+    /** What it is. */
+    kind: PlaceholderKind;
+    /** What it shows, in full: a field's label or result, a control's title. */
+    label: string;
+    /** A field's name (its first argument), a control's tag, or a picture placeholder's key. */
+    key?: string;
+    /** A field's code. */
+    code?: string;
+    /** The caption's type text: `setFieldTypes`' text for the code, else the field type (`MERGEFIELD`), or a control's kind. */
+    typeText: string;
+    /** The data source lacks the field (`setUnmappedFields`). */
+    unmapped: boolean;
+    /** For a sub-template reference: what it names and whether its body shows. */
+    reference?: SubTemplateReference;
+    /** Where it is, in the same space as a popover's anchor: a field's last line, else its box. */
+    anchor: ClientRect;
+}

package/dist/host/chrome.js

@@ -112,6 +112,7 @@ export function startChrome(s, dom, ledger, frames, report, toViewport) {
         setThemeColors: (themeColors) => setLook({ themeColors }),
         setAppearance: (appearance) => setLook({ appearance }),
         setDetail: (detail) => setLook({ detail }),
+        setPlaceholderUi: (placeholderUi) => setLook({ placeholderUi }),
         visiblePages: () => {
             const r = dom.canvas.getBoundingClientRect();
             return pages.map(({ page, rect }) => ({ page, rect: { ...rect, left: rect.left + r.left, top: rect.top + r.top } }));

package/dist/host/mount.js

@@ -34,6 +34,10 @@ export async function mountHost(container, s, options, claims) {
             const t = event;
             return { ...t, at: client(t.at), rect: { ...t.rect, left: t.rect.left + r.left, top: t.rect.top + r.top } };
         }
+        if ((type === 'placeholderHovered' || type === 'placeholderSelected') && event) {
+            const t = event;
+            return { ...t, anchor: { ...t.anchor, left: t.anchor.left + r.left, top: t.anchor.top + r.top } };
+        }
         if (type === 'popoverRequested') {
             const p = event;
             return { ...p, anchor: { ...p.anchor, left: p.anchor.left + r.left, top: p.anchor.top + r.top } };

package/dist/index.d.ts

@@ -6,9 +6,9 @@
  */
 export { Editor, HeadlessEditor } from './editor.js';
 export type { ExportResult, MountOptions, SessionOptions } from './editor.js';
-export type { CommandEntry, CommandId, CommandInfo, Commands, FieldTargets, NoArgumentCommandId, Op, OpArgs, PlaceholderLook, } from './commands.js';
+export type { CommandEntry, CommandId, CommandInfo, Commands, FieldTargets, NoArgumentCommandId, Op, OpArgs, PlaceholderAction, PlaceholderLook, } from './commands.js';
 export type { AutoCorrectChange, AutoCorrectEntry, AutoCorrectOptions, CharacterFormatting, CommandState, CommandValues, EditingTarget, EditorState, ElementContext, HighlightColor, HorizontalPosition, HorizontalReference, LineSpacing, MarkupView, Mixed, ObjectHorizontalAlignment, ObjectPlacement, ObjectSelection, ObjectVerticalAlignment, ObjectWrap, PageFormatting, ParagraphFormatting, ReviewState, RowHeight, SelectionSummary, TablePosition, TableSelection, TableStyleOptions, TableWidth, TextDistance, Tri, UnderlineStyle, VerticalPosition, VerticalReference, ViewState, WrapSide, } from './state.js';
-export type { HostCommand, Tooltip, TransactionRecord, TwipEvents } from './events.js';
+export type { HostCommand, PlaceholderKind, PlaceholderTarget, Tooltip, TransactionRecord, TwipEvents } from './events.js';
 export { EditorError } from './errors.js';
 export type { ErrorCode } from './errors.js';
 export { FontLibrary } from './fonts/library.js';
@@ -18,7 +18,7 @@ export type { ContextMenu, ContextMenuEvent, MenuAction, MenuItem, MenuTarget, M
 export type { AccessibilityDialogSession, DialogKind, DialogSession, DialogSessionOf, DialogValues, Dialogs, FieldInfo, } from './services/dialogs.js';
 export type { Find, FindMatch, FindQuery, FindResult } from './services/find.js';
 export type { Dictionary, Spelling } from './services/spelling.js';
-export type { Block, ControlKind, ControlOptions, DataBinding, DataParts, ElementDetail, ElementInfo, Elements, MountedElements, PlaceholderInfo, ReferenceResolution, ReferenceRule, SubTemplateInfo, SubTemplateReference, SubTemplates, } from './services/elements.js';
+export type { Block, ControlKind, ControlOptions, DataBinding, DataParts, ElementDetail, ElementInfo, Elements, MountedElements, PlaceholderInfo, ReferenceResolution, ReferenceRule, SubTemplateInfo, SubTemplateReference, SubTemplates, SubTemplateVersion, } from './services/elements.js';
 export type { Accessibility, AccessibleId, AccessibleNode, AnnouncementKind, CellPlace, ListPosition, Shortcuts } from './services/accessibility.js';
 export type { Heading, Navigation, StyleInfo, Styles } from './services/navigation.js';
 export type { Ruler, RulerModel, RulerModelSource, RulerUnit, RulerView, TabAlignment, TabLeader, TabSelector, } from './services/ruler.js';

package/dist/services/elements.d.ts

@@ -37,6 +37,8 @@ export interface PlaceholderInfo {
     key: string;
     /** The control it is in. */
     element: ElementId | null;
+    /** The input block's button pressed (its id), or `replace` from a filled block's tab; absent: the block itself. */
+    action?: string;
 }
 /** {@link Elements} on a mounted editor: adds drop targets and hit testing. */
 export interface MountedElements extends Elements {
@@ -91,6 +93,17 @@ export interface ReferenceRule {
     /** The building block gallery (`custom1`), when it matters. */
     gallery?: string;
 }
+/** A sub-template's version, as its card and its shown body's tab show it (`setSubTemplateVersions`). */
+export interface SubTemplateVersion {
+    /** The sub-template's name. */
+    name: string;
+    /** Its category. Default: the first reference rule's. */
+    category?: string;
+    /** The version text (`v4`). */
+    version: string;
+    /** A newer version's notice (`v5 available`); a press on it raises `subTemplateUpdateRequested`. */
+    newer?: string;
+}
 /** Whether a reference's sub-template resolves, or why its body can't show. */
 export type ReferenceResolution = 'resolved' | 'missing' | 'nearMatch' | 'cycle' | 'tooDeep' | 'notAlone' | 'notInBody';
 /** What a sub-template reference field names and whether its body shows. */

package/dist/services/view.d.ts

@@ -31,6 +31,12 @@ export interface View {
     setAppearance(appearance: DocumentAppearance): Promise<void>;
     /** How much the editor measures while you drag and hover. `setViewOptions` with `detail`. */
     setDetail(detail: MeasureDetail): Promise<void>;
+    /**
+     * Draws placeholders as editor UI (field marks, repeating sections, sub-template cards and input blocks), with the
+     * `placeholderHovered` and `placeholderSelected` events; never changes the output. `setViewOptions` with
+     * `placeholderUi`.
+     */
+    setPlaceholderUi(on: boolean): Promise<void>;
     /** The pages on screen, for a page navigator or a thumbnails strip. */
     visiblePages(): {
         page: number;
@@ -71,6 +77,8 @@ export interface ViewOptions {
     detail?: MeasureDetail;
     /** When the dot grid objects snap to shows (unrelated to `gridlines`, the table gridlines). */
     objectGrid?: ObjectGrid;
+    /** Draws placeholders as editor UI: field marks, repeating sections, sub-template cards and input blocks. Default: off. */
+    placeholderUi?: boolean;
 }
 /**
  * The editor chrome's colour scheme: the desk, rulers, handles, guides and readouts. `highContrast` takes the

package/dist/state.d.ts

@@ -570,6 +570,8 @@ export interface ViewState {
     detail: MeasureDetail;
     /** When the objects' dot grid shows. */
     objectGrid: ObjectGrid;
+    /** Placeholders are drawn as editor UI (`placeholderUi`). */
+    placeholderUi: boolean;
     /** Which fields are sub-template references (`setSubTemplateRules`); absent when none are. */
     subTemplateRules?: ReferenceRule[];
 }

package/dist/transport/protocol.js

@@ -127,7 +127,7 @@ export function decodeEvent(wire) {
     return { type, event: 'value' in fields ? fields.value : fields };
 }
 /** The events whose payload always travels as `value`, an object or not: the engine's optional payloads. */
-const valueEvents = new Set(['tooltip']);
+const valueEvents = new Set(['tooltip', 'placeholderHovered', 'placeholderSelected']);
 /** The inverse of {@link decodeEvent}. */
 export function encodeEvent(type, event) {
     if (event instanceof EditorError)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twip/web",
-  "version": "0.0.0-canary-abcb2d5",
+  "version": "0.0.0-canary-6f0bf0b",
   "description": "The Twip DOCX editor for the browser and Node: a managed, framework-independent editor over the WebAssembly engine.",
   "type": "module",
   "license": "Apache-2.0",