ooxml-ui 1.22.0 → 1.23.1

package/dist/{chunk-REJECZGV.js → chunk-6RCASLEC.js}

@@ -1,5 +1,5 @@
 import { defineSmartArt } from './chunk-QBXYGKPB.js';
-import { TEAMS_TAGS, registerTeams } from './chunk-DRBAJ5UO.js';
+import { TEAMS_TAGS, registerTeams } from './chunk-FX6CF43K.js';
 import { installOfficeUiTheme } from './chunk-T5ARELU2.js';
 import { registerControls } from './chunk-TJ245GDD.js';
 import { definePresence } from './chunk-YZH2QS7J.js';

package/dist/{chunk-DRBAJ5UO.js → chunk-FX6CF43K.js}

@@ -9,6 +9,7 @@ import { filterActivity, ACTIVITY_FILTERS, localZone, startOfDay, occurrencesBet
 import { repeat } from 'lit/directives/repeat.js';
 import { live } from 'lit/directives/live.js';
 import { keyed } from 'lit/directives/keyed.js';
+import { fileCommandDetail } from 'ooxml-core/embedding';
 
 // raw-css:/home/runner/work/ooxml/ooxml/src/ui/src/teams/reset.css?raw
 var reset_default = ":host {\n	box-sizing: border-box;\n	font: var(--office-font-size) var(--office-font);\n	color: var(--office-foreground);\n}\n*,\n*::before,\n*::after {\n	box-sizing: inherit;\n}\nbutton {\n	font: inherit;\n	color: inherit;\n	cursor: pointer;\n}\nbutton:focus-visible,\ntextarea:focus-visible,\ninput:focus-visible {\n	outline: var(--office-focus-width) solid var(--office-ring);\n	outline-offset: var(--office-focus-offset);\n}\nsvg.icon {\n	width: 1.25em;\n	height: 1.25em;\n	flex: none;\n	fill: none;\n	stroke: currentColor;\n	stroke-width: var(--office-icon-stroke);\n	stroke-linecap: round;\n	stroke-linejoin: round;\n}\n";
@@ -2022,7 +2023,7 @@ var TYPES = {
 };
 var OPEN_ACCEPT = ".xlsx,.xlsm,.xltx,.xls,.csv,.tsv,.txt";
 function announceFileCommand(host, command, fileName) {
-  return emit(host, "file-command", { command, ...fileName === void 0 ? {} : { fileName } });
+  return emit(host, "file-command", fileCommandDetail(command, fileName));
 }
 var extensionOf = (fileName) => /\.([^./\\]+)$/.exec(fileName)?.[1]?.toLowerCase() ?? "";
 function withExtension(fileName, extension) {

package/dist/chunk-HTIJ2EAA.js

@@ -0,0 +1,364 @@
+import { defineRibbonGroup, defineRibbonStack, defineButton, defineMenuItem, defineMenuButton } from './chunk-TJ245GDD.js';
+import { acceptedRibbonAddIns, findRibbonAddInCommand, RIBBON_ADD_IN_EVENT } from 'ooxml-core/ribbon';
+export { RIBBON_ADD_IN_EVENT } from 'ooxml-core/ribbon';
+import { sameRenderer, sameRegionContext, hostBackstagePageId, acceptedHostBackstagePages, placeHostBackstagePages, hostBackstageItemId, withHostMenuCommands, isHostMenuEntry, resolveHostMenuCommands, withoutHiddenEntries, hostBackstageRegionId } from 'ooxml-core/embedding';
+
+function defineRibbonAddInElements(registry) {
+  if (!registry) return;
+  for (const define of [
+    defineRibbonGroup,
+    defineRibbonStack,
+    defineButton,
+    defineMenuItem,
+    defineMenuButton
+  ])
+    define(registry);
+}
+var SMALL_ROWS = 3;
+function button(doc, spec) {
+  const menu = !!spec.items?.length;
+  const el = doc.createElement(menu ? "office-ui-menu-button" : "office-ui-button");
+  if (!menu) el.setAttribute("command", spec.id);
+  el.dataset.addInCommand = spec.id;
+  el.setAttribute("label", spec.label);
+  el.setAttribute("title", spec.title ?? spec.label);
+  if (spec.icon) el.setAttribute("icon", spec.icon);
+  const small = spec.size === "small";
+  if (!menu) el.setAttribute("size", small ? "small" : "large");
+  else if (!small) el.setAttribute("variant", "stacked");
+  else el.style.setProperty("--office-target-size", "var(--office-control-height)");
+  if (spec.disabled) el.setAttribute("disabled", "");
+  for (const item of spec.items ?? []) {
+    const entry = doc.createElement("office-ui-menu-item");
+    entry.setAttribute("command", item.id);
+    entry.dataset.addInCommand = item.id;
+    entry.setAttribute("label", item.label);
+    if (item.title) entry.setAttribute("title", item.title);
+    if (item.icon) entry.setAttribute("icon", item.icon);
+    if (item.disabled) entry.setAttribute("disabled", "");
+    el.append(entry);
+  }
+  return el;
+}
+function group(doc, spec) {
+  const el = doc.createElement("office-ui-ribbon-group");
+  el.setAttribute("label", spec.label);
+  let column;
+  for (const command of spec.commands) {
+    if (command.size !== "small") {
+      column = void 0;
+      el.append(button(doc, command));
+      continue;
+    }
+    if (!column || column.childElementCount >= SMALL_ROWS) {
+      column = doc.createElement("office-ui-ribbon-stack");
+      el.append(column);
+    }
+    column.append(button(doc, command));
+  }
+  return el;
+}
+var ownTabs = (ribbon) => new Set(
+  [...ribbon.children].flatMap(
+    (child) => child instanceof HTMLElement && child.dataset.ribbonTab && !("addIn" in child.dataset) ? [child.dataset.ribbonTab] : []
+  )
+);
+var shown = /* @__PURE__ */ new WeakMap();
+var addInPanels = (ribbon) => [...ribbon.children].filter(
+  (child) => child instanceof HTMLElement && "addIn" in child.dataset
+);
+function syncRibbonAddIns(ribbon, tabs, options = {}) {
+  const doc = ribbon.ownerDocument;
+  const accepted = acceptedRibbonAddIns(tabs, ownTabs(ribbon));
+  if (accepted.length) defineRibbonAddInElements(doc.defaultView?.customElements);
+  const ids = accepted.map((tab) => tab.id);
+  const look = JSON.stringify([options.panelClass ?? "", accepted]);
+  const current = new Map(accepted.map((tab) => [tab.id, tab]));
+  const existing = addInPanels(ribbon);
+  const before = shown.get(ribbon);
+  shown.set(ribbon, { look, tabs: current });
+  if (before?.look === look && existing.length === ids.length && existing.every((panel, index) => panel.dataset.ribbonTab === ids[index]))
+    return ids;
+  for (const panel of existing) panel.remove();
+  for (const tab of accepted) {
+    const panel = doc.createElement("div");
+    if (options.panelClass) panel.className = options.panelClass;
+    panel.id = `add-in-${tab.id}-panel`;
+    panel.dataset.addIn = "";
+    panel.dataset.ribbonTab = tab.id;
+    panel.dataset.label = tab.label;
+    if (tab.keytip) panel.dataset.tabKeytip = tab.keytip;
+    const groups = tab.groups.map((spec) => group(doc, spec));
+    panel.append(...options.wrap ? options.wrap(doc, tab, groups) : groups);
+    panel.addEventListener("office-command", (event) => {
+      event.stopPropagation();
+      const id = event.detail?.command;
+      const latest = shown.get(ribbon)?.tabs.get(tab.id);
+      const command = latest && findRibbonAddInCommand(latest, id);
+      if (!command) return;
+      command.run?.();
+      ribbon.dispatchEvent(
+        new CustomEvent(RIBBON_ADD_IN_EVENT, {
+          detail: { tab: tab.id, command: command.id },
+          bubbles: true,
+          composed: true
+        })
+      );
+    });
+    ribbon.append(panel);
+  }
+  return ids;
+}
+var HOST_REGION_ATTRIBUTE = "data-office-region";
+var HostRegionHost = class {
+  #container;
+  #callbackKeys;
+  #attribute;
+  #label;
+  #renderer;
+  #context;
+  #result;
+  #element;
+  /** The latest context as the product passed it, callbacks included. */
+  #latest;
+  constructor(container, options = {}) {
+    this.#container = container;
+    this.#callbackKeys = /* @__PURE__ */ new Set(["close", ...options.callbackKeys ?? []]);
+    this.#attribute = options.attribute ?? HOST_REGION_ATTRIBUTE;
+    this.#label = options.label ?? "[ooxml-ui]";
+  }
+  /** The container this host fills. */
+  get container() {
+    return this.#container;
+  }
+  /** True while a renderer is mounted. */
+  get mounted() {
+    return this.#renderer !== void 0;
+  }
+  /** Mount `renderer`, or deliver a changed `context` to the mounted one. */
+  render(renderer, latest) {
+    this.#latest = latest;
+    const context = this.#stable(latest);
+    this.#container.setAttribute(this.#attribute, context.region);
+    if (!sameRenderer(renderer, this.#renderer)) {
+      this.#unmount();
+      this.#renderer = renderer;
+      this.#context = context;
+      this.#mount(renderer, context);
+      return;
+    }
+    if (this.#context && sameRegionContext(this.#context, context, this.#callbackKeys)) return;
+    this.#context = context;
+    if (this.#element) this.#element.context = context;
+    else this.#guard(() => this.#result?.update?.(context));
+  }
+  /** Tear the renderer down and empty the container. */
+  destroy() {
+    this.#unmount();
+    this.#renderer = void 0;
+    this.#context = void 0;
+    this.#latest = void 0;
+  }
+  /**
+   * `context` with its callbacks swapped for stable ones that call the latest product
+   * callback, so a renderer that kept an older context never calls a stale closure.
+   */
+  #stable(context) {
+    const latest = () => this.#latest ?? context;
+    const call = (key) => (...args) => latest()[key]?.(...args);
+    const stable = { ...context };
+    for (const key of this.#callbackKeys) if (key in context) stable[key] = call(key);
+    return stable;
+  }
+  #mount(renderer, context) {
+    if (typeof renderer === "function") {
+      const result = this.#guard(() => renderer(this.#container, context));
+      this.#result = typeof result === "function" ? { destroy: result } : result ?? void 0;
+      return;
+    }
+    const spec = typeof renderer === "string" ? { element: renderer } : renderer;
+    const element = this.#guard(() => this.#container.ownerDocument.createElement(spec.element));
+    if (!element) return;
+    Object.assign(element, spec.properties);
+    this.#element = element;
+    this.#element.context = context;
+    this.#container.append(element);
+  }
+  #unmount() {
+    const result = this.#result;
+    this.#result = void 0;
+    this.#guard(() => result?.destroy?.());
+    this.#element?.remove();
+    this.#element = void 0;
+  }
+  #guard(run) {
+    try {
+      return run();
+    } catch (error) {
+      console.error(`${this.#label} A host region renderer threw:`, error);
+      return void 0;
+    }
+  }
+};
+function createHostBackstagePages(backstage, options) {
+  let pages = [];
+  const hosts = /* @__PURE__ */ new Map();
+  const container = (page) => {
+    let host = hosts.get(page.id);
+    if (host) return host;
+    const element = backstage.ownerDocument.createElement("div");
+    element.dataset.backstagePage = hostBackstageItemId(page.id);
+    if (options.pageClass) element.className = options.pageClass;
+    element.hidden = true;
+    backstage.append(element);
+    host = new HostRegionHost(element, options.label ? { label: options.label } : {});
+    hosts.set(page.id, host);
+    return host;
+  };
+  const render = (page, host) => {
+    const region = hostBackstageRegionId(page.id);
+    host.render(page.render, options.context(region, page));
+  };
+  const drop = (id) => {
+    const host = hosts.get(id);
+    if (!host) return;
+    host.destroy();
+    host.container.remove();
+    hosts.delete(id);
+  };
+  return {
+    items(builtIn) {
+      return placeHostBackstagePages(builtIn, pages, (page) => ({
+        id: hostBackstageItemId(page.id),
+        label: page.label,
+        ...page.group === "footer" ? { group: "footer" } : {}
+      }));
+    },
+    setPages(next) {
+      pages = acceptedHostBackstagePages(next);
+      const kept = new Set(pages.map((page) => page.id));
+      for (const id of [...hosts.keys()]) if (!kept.has(id)) drop(id);
+      for (const page of pages) {
+        const host = hosts.get(page.id);
+        if (host?.mounted) render(page, host);
+      }
+    },
+    show(itemId) {
+      const id = hostBackstagePageId(itemId);
+      const page = id === void 0 ? void 0 : pages.find((candidate) => candidate.id === id);
+      if (!page) return false;
+      render(page, container(page));
+      return true;
+    },
+    refresh() {
+      for (const page of pages) {
+        const host = hosts.get(page.id);
+        if (host?.mounted) render(page, host);
+      }
+    },
+    destroy() {
+      for (const id of [...hosts.keys()]) drop(id);
+    }
+  };
+}
+function withHostMenuItems(items, commands, context) {
+  const rows = withHostMenuCommands(items, commands, context);
+  const host = /* @__PURE__ */ new Map();
+  const drawn = rows.map((row) => {
+    if (!isHostMenuEntry(row)) return row;
+    host.set(row.id, row);
+    return {
+      id: row.id,
+      label: row.label,
+      ...row.separatorBefore ? { separatorBefore: true } : {},
+      ...row.disabled ? { disabled: true } : {},
+      ...row.icon ? { icon: row.icon } : {}
+    };
+  });
+  return {
+    items: drawn,
+    run(id) {
+      const entry = host.get(id);
+      if (!entry) return false;
+      entry.onSelect();
+      return true;
+    }
+  };
+}
+var HOST_CHILD = "data-host-command";
+var hostRuns = /* @__PURE__ */ new WeakMap();
+function listen(menu) {
+  const runs = /* @__PURE__ */ new Map();
+  hostRuns.set(menu, runs);
+  menu.addEventListener("office-command", (event) => {
+    const id = event.detail?.command;
+    if (id) runs.get(id)?.onSelect();
+  });
+  return runs;
+}
+function syncHostMenuChildren(menu, commands, context) {
+  for (const child of [...menu.querySelectorAll(`:scope > [${HOST_CHILD}]`)]) child.remove();
+  const doc = menu.ownerDocument;
+  const { top, bottom } = resolveHostMenuCommands(commands, context);
+  const runs = hostRuns.get(menu) ?? listen(menu);
+  runs.clear();
+  const item = (entry) => {
+    runs.set(entry.id, entry);
+    const row = doc.createElement("office-ui-menu-item");
+    row.setAttribute(HOST_CHILD, "");
+    row.setAttribute("command", entry.id);
+    row.setAttribute("label", entry.label);
+    if (entry.icon) row.setAttribute("icon", entry.icon);
+    if (entry.disabled) row.setAttribute("disabled", "");
+    return row;
+  };
+  const separator = () => {
+    const rule = doc.createElement("office-ui-menu-separator");
+    rule.setAttribute(HOST_CHILD, "");
+    return rule;
+  };
+  const builtIn = menu.children.length > 0;
+  if (top.length) menu.prepend(...top.map(item), ...builtIn ? [separator()] : []);
+  if (bottom.length)
+    menu.append(...builtIn || top.length ? [separator()] : [], ...bottom.map(item));
+}
+var TIDY_HIDDEN = "data-separator-tidy";
+function tidyMenuSeparators(menu) {
+  const isSeparator = (node) => node.localName === "office-ui-menu-separator";
+  const separators = [];
+  const rows = [];
+  let pending = [];
+  for (const child of menu.children) {
+    if (!(child instanceof HTMLElement)) continue;
+    if (isSeparator(child)) {
+      if (child.hidden && !child.hasAttribute(TIDY_HIDDEN)) continue;
+      separators.push(child);
+      pending.push(child);
+      continue;
+    }
+    rows.push({ row: child, before: pending, separatorBefore: pending.length > 0 });
+    pending = [];
+  }
+  const starts = new Map(
+    withoutHiddenEntries(rows, (entry) => entry.row.hidden !== false).map((entry) => [
+      entry.row,
+      entry.separatorBefore
+    ])
+  );
+  const shown2 = /* @__PURE__ */ new Set();
+  let carried = [];
+  for (const entry of rows) {
+    carried = [...carried, ...entry.before];
+    if (!starts.has(entry.row)) continue;
+    const separator = carried.at(-1);
+    if (starts.get(entry.row) && separator) shown2.add(separator);
+    carried = [];
+  }
+  for (const separator of separators) {
+    const hide = !shown2.has(separator);
+    separator.hidden = hide;
+    separator.toggleAttribute(TIDY_HIDDEN, hide);
+  }
+}
+
+export { HOST_REGION_ATTRIBUTE, HostRegionHost, createHostBackstagePages, defineRibbonAddInElements, syncHostMenuChildren, syncRibbonAddIns, tidyMenuSeparators, withHostMenuItems };

package/dist/docx/backstage-pages.d.ts

@@ -2,6 +2,7 @@ import { PROPERTY_FIELDS, type DocumentModel } from 'ooxml-core/docx';
 import type { DocumentStats } from 'ooxml-core/docx';
 import type { FileCommand } from './file-commands.js';
 import type { BackstageOptions, BackstageOptionKey } from './backstage-options.js';
+import type { ResolvedWordCustomization, WordRegionContext } from './customization.js';
 /** What the File view needs from the editor; every value is read when a page opens. */
 export interface BackstageHandlers {
     fileCommand(command: FileCommand, fileName?: string): void;
@@ -21,6 +22,10 @@ export interface BackstageHandlers {
     ribbon(): HTMLElement | undefined;
     hiddenActions(): readonly string[];
     setHiddenActions(ids: string[]): void;
+    /** The host customisation: hidden pages and host pages (`backstage.extraPages`). */
+    customization(): ResolvedWordCustomization;
+    /** The context of a host page's region. */
+    regionContext(region: string): WordRegionContext;
 }
 export interface PageContext {
     handlers: BackstageHandlers;

package/dist/docx/backstage.d.ts

@@ -11,6 +11,13 @@ export interface Backstage {
     readonly isOpen: boolean;
     /** Retranslates the navigation after the editor locale changed, and redraws the open page. */
     relocalize(): void;
+    /**
+     * Re-applies the host customisation: hides the pages disabled capabilities remove, places
+     * the host pages (`backstage.extraPages`) and delivers a fresh context to mounted ones.
+     */
+    refresh(): void;
+    /** Tears the host pages down. */
+    destroy(): void;
 }
 /**
  * Word's File view. Left: Back, Info, New, Open, Save and its siblings (Save As, Print, Export)

package/dist/docx/component.d.ts

@@ -42,6 +42,7 @@ export declare class DocxEditorElement extends DocxEditorApi {
     get documentModel(): DocumentModel | null;
     set documentModel(value: DocumentModel | null);
     get readOnly(): boolean;
+    /** True when the document cannot be edited: this switch, a `viewer` role or `capabilities.edit` off. */
     set readOnly(value: boolean);
     /**
      * Shares the loaded document in a room while set; `null` leaves (see

package/dist/docx/context-menu.d.ts

@@ -1,6 +1,10 @@
 import type { EditorView } from 'prosemirror-view';
+import { type MenuItem } from './context-menu-items.js';
 import { type EditorLocale } from './localization.js';
 import type { RibbonAction } from './ribbon-action.js';
+import type { ResolvedWordCustomization } from './customization.js';
+/** `items` without the `hidden` ids; a removed group start passes its separator on. */
+export declare function withoutMenuItems(items: readonly MenuItem[], hidden: ReadonlySet<string>): MenuItem[];
 export interface ContextMenuHost {
     /** Element the menu is appended to (inside the shadow root, so theme tokens apply). */
     container: HTMLElement;
@@ -13,6 +17,8 @@ export interface ContextMenuHost {
     locale(): EditorLocale;
     run(action: RibbonAction): void;
     warn(message: string): void;
+    /** The host customisation: entries capabilities remove and host commands to add. */
+    customization(): ResolvedWordCustomization;
 }
 export interface ContextMenu {
     readonly isOpen: boolean;

package/dist/docx/customization-apply.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Applies `<docx-editor>`'s `customization` property: the capabilities reach the ribbon (through
+ * `hiddenActions`), the read-only state (a lock beside the host's switch and a viewer role), the
+ * File tab, the title bar, the context menu and the shortcuts, which all read the resolved object
+ * from `core.viewOptions.customization`.
+ */
+import type { EditorCore } from './editor-core.js';
+import { type WordCustomization, type WordRegionContext } from './customization.js';
+/** Replaces the customisation (an equal object identity is a no-op) and re-applies it. */
+export declare function setWordCustomization(core: EditorCore, value: WordCustomization | null): void;
+/** The context of a host region of `<docx-editor>` (a File tab page). */
+export declare function wordRegionContext(core: EditorCore, region: string): WordRegionContext;

package/dist/docx/customization.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `<docx-editor>`'s `customization` property: the shared contract of `ooxml-core/embedding`
+ * (capabilities, host File tab pages, host context-menu commands) bound to Word. The host passes
+ * one plain object; `resolveWordCustomization` turns it into the sets every render site asks,
+ * so the ribbon, the File tab, the context menu, the shortcuts and the file commands agree.
+ */
+import { type EditorCustomization, type HostBackstagePage, type HostMenuCommand, type HostRegionContextBase, type HostRegionRenderer } from 'ooxml-core/embedding';
+import { type RibbonActionId, type WordBackstagePageId, type WordCapabilityId, type WordFileCommandId, type WordShortcutId } from 'ooxml-core/docx/ui';
+/** What a host region (a File tab page) of `<docx-editor>` receives. */
+export interface WordRegionContext extends HostRegionContextBase {
+    /** The `<docx-editor>` element: its whole public API (save, documentModel, readOnly...). */
+    readonly editor: HTMLElement;
+    /** The document's file name. */
+    readonly fileName: string;
+}
+/** What a host context-menu command of `<docx-editor>` receives: the menu's selection. */
+export interface WordMenuContext {
+    /** The selected text; empty for a caret. */
+    readonly selectedText: string;
+    /** Selection start and end, as document positions (equal for a caret). */
+    readonly from: number;
+    readonly to: number;
+    /** True when the document cannot be edited (prop, capability, protection, collaboration). */
+    readonly readOnly: boolean;
+    readonly inTable: boolean;
+    readonly onLink: boolean;
+}
+export type WordRegionRenderer = HostRegionRenderer<HTMLElement, WordRegionContext>;
+export type WordBackstagePage = HostBackstagePage<WordRegionRenderer>;
+export type WordMenuCommand = HostMenuCommand<WordMenuContext>;
+/** The whole `customization` object of `<docx-editor>`. Every field is optional. */
+export type WordCustomization = EditorCustomization<WordCapabilityId, WordRegionRenderer, WordMenuContext>;
+/** A customisation resolved into what each render site asks. */
+export interface ResolvedWordCustomization {
+    /** False when `capabilities.edit` is off: the document opens read-only. */
+    readonly canEdit: boolean;
+    /** Ribbon controls the capabilities remove, unioned with `hiddenActions` by the ribbon. */
+    readonly hiddenActions: readonly RibbonActionId[];
+    readonly fileCommands: ReadonlySet<WordFileCommandId>;
+    readonly backstagePages: ReadonlySet<WordBackstagePageId>;
+    readonly shortcuts: ReadonlySet<WordShortcutId>;
+    /** Built-in context-menu entries to remove. */
+    readonly menuItems: ReadonlySet<string>;
+    /** True when `copy` is off: the editor also refuses copy and cut from the keyboard. */
+    readonly blockCopy: boolean;
+    readonly extraPages: readonly WordBackstagePage[];
+    readonly menuCommands: readonly WordMenuCommand[];
+}
+/** Resolves a host customisation (none: everything on, nothing added). */
+export declare function resolveWordCustomization(customization?: WordCustomization | null): ResolvedWordCustomization;
+/** The resolution of "no customisation", shared so it is allocated once. */
+export declare const EMPTY_WORD_CUSTOMIZATION: ResolvedWordCustomization;

package/dist/docx/editor-chrome.d.ts

@@ -1,10 +1,12 @@
 import { type DocumentModel } from 'ooxml-core/docx';
+import { type DocumentStorage } from 'ooxml-core/embedding';
 import { type Backstage } from './backstage.js';
 import type { BackstageOptions, BackstageOptionKey } from './backstage-options.js';
 import { type FileCommand } from './file-commands.js';
 import { type EditorLocale } from './localization.js';
 import { type RibbonActions } from './ribbon-actions.js';
 import { type StatusBar } from './status-bar.js';
+import type { ResolvedWordCustomization, WordRegionContext } from './customization.js';
 import { type SaveState, type TitleBar } from './title-bar.js';
 /** What the chrome needs from the editor element; keeps component.ts free of chrome details. */
 export interface ChromeHost {
@@ -18,6 +20,8 @@ export interface ChromeHost {
     newDocument(): void;
     load(bytes: Uint8Array): Promise<void>;
     save(): Promise<Uint8Array>;
+    /** Host-owned storage for Save and Open, when the host set one. */
+    storage?(): DocumentStorage | undefined;
     print(): void;
     history(key: 'undo' | 'redo'): void;
     toggleComments(): void;
@@ -33,6 +37,10 @@ export interface ChromeHost {
     setOption(key: BackstageOptionKey, value: string): void;
     hiddenActions(): readonly string[];
     setHiddenActions(ids: string[]): void;
+    /** The resolved host customisation (`customization` property). */
+    customization(): ResolvedWordCustomization;
+    /** The context of a host region (a File tab page). */
+    regionContext(region: string): WordRegionContext;
 }
 export declare const DEFAULT_FILE_NAME = "Document1.docx";
 /**
@@ -58,9 +66,20 @@ export declare class EditorChrome {
     setSaveState(state: SaveState): void;
     setLocale(locale: EditorLocale): void;
     refresh(pageText: string, wordText: string): void;
+    /** Re-applies the host customisation to the File tab, title bar and ribbon actions. */
+    applyCustomization(): void;
     closeBackstage(): void;
     /** Runs a file command unless a host cancels the `file-command` event to handle it itself. */
     run(command: FileCommand, fileName?: string): Promise<void>;
+    /** True while a save is pending. */
+    saving: boolean;
+    /**
+     * Saves to the host's storage when there is one, else downloads a copy. An edit made while the
+     * save runs keeps the document dirty: the saved bytes do not contain it.
+     */
+    private saveDocument;
+    /** Opens from the host's storage when it can open, else shows the file picker. */
+    private open;
     private newDocument;
     private openSelectedFile;
 }

package/dist/docx/editor-core.d.ts

@@ -1,3 +1,4 @@
+import type { DocumentStorage } from 'ooxml-core/embedding';
 import type { SurfaceHostActions } from './building-blocks-actions.js';
 import type { RibbonAddInTab } from '../ribbon/add-in-tabs.js';
 import { FormatDialogs } from './format-dialogs.js';
@@ -62,11 +63,32 @@ export declare class EditorCore {
     loaded?: LoadedDocument | undefined;
     loadGeneration: number;
     loading: boolean;
-    readOnly: boolean;
+    /** The host's `readOnly` switch. A collaboration `viewer` role locks the editor on top of it. */
+    hostReadOnly: boolean;
+    /** True while `applyReadOnly` writes the `read-only` attribute. */
+    reflectingReadOnly: boolean;
+    private shownReadOnly;
+    private shownHostReadOnly;
+    /**
+     * Effective: the host's switch, a `viewer` role, or `capabilities.edit` off. Assigning sets
+     * the host's switch only, so nothing that assigns it can lift the other two.
+     */
+    get readOnly(): boolean;
+    set readOnly(value: boolean);
+    /** Applies the effective value to the view, controls and attribute. */
+    applyReadOnly(): void;
+    /** True while a collaboration `viewer` role holds the editor read-only. */
+    get roleLocked(): boolean;
+    /** Applies the effective value, then reports it when it or the host's switch changed. */
+    reportReadOnly(change?: () => void): void;
+    /** Joining or leaving a room can change the role lock: apply it and report a change. */
+    roleChanged(): void;
     /** Set before mounting to render only the document surface. */
     surfaceOnly: boolean;
     /** Host-owned workflows for surface mode (link, find and replace, picture picker). */
     surfaceActions: SurfaceHostActions;
+    /** Where File > Save and Open go instead of a download and the file picker (`storage`). */
+    storage: DocumentStorage | undefined;
     locale: EditorLocale;
     reviewAuthor: string;
     theme: EditorThemeMode;

package/dist/docx/element-api.d.ts

@@ -1,9 +1,11 @@
+import type { DocumentStorage } from 'ooxml-core/embedding';
 import type { RibbonAddInTab } from '../ribbon/add-in-tabs.js';
 import type { CollabSession } from 'ooxml-core/collab';
 import type { WordYjsOptions } from 'ooxml-core/docx/ui';
 import type { DocxCollaborationState } from './collaboration-types.js';
 import type { EditorCore } from './editor-core.js';
 import { type RibbonActionId, type RibbonActionInput } from 'ooxml-core/docx/ui';
+import type { WordCustomization } from './customization.js';
 import { type WordToolbarProps } from './building-blocks.js';
 import { type WordNavigationProps, type WordStatusProps } from './building-blocks-status.js';
 import type { SurfaceHostActions } from './building-blocks-actions.js';
@@ -27,6 +29,14 @@ export declare abstract class DocxEditorApi extends HTMLElementBase {
      */
     get surfaceActions(): SurfaceHostActions;
     set surfaceActions(value: SurfaceHostActions);
+    /**
+     * Host-owned storage. When set, File > Save and Save As hand the saved bytes to
+     * `storage.save()` instead of downloading them, and File > Open asks `storage.open()` (when it
+     * has one) instead of showing the file picker. The cancelable `file-command` event still fires
+     * first; a host that prevents it handles the command itself.
+     */
+    get storage(): DocumentStorage | undefined;
+    set storage(value: DocumentStorage | null | undefined);
     get loading(): boolean;
     /** Selection and formatting updates, including changes which do not dirty the document. */
     subscribeEditorState(listener: () => void): () => void;
@@ -64,6 +74,14 @@ export declare abstract class DocxEditorApi extends HTMLElementBase {
      */
     get hiddenActions(): readonly RibbonActionId[];
     set hiddenActions(value: readonly RibbonActionInput[]);
+    /**
+     * The host customisation (`WordCustomization`): `capabilities` (removing every UI path to
+     * what is switched off), `backstage.extraPages` (host File tab pages) and
+     * `contextMenu.extraCommands` (host context-menu commands). The object is applied when its
+     * identity changes, so keep it stable; `null` restores the defaults.
+     */
+    get customization(): WordCustomization | null;
+    set customization(value: WordCustomization | null | undefined);
     /** True after an edit until the document is saved through File > Save, `download()`, loaded or `markClean()`. */
     get dirty(): boolean;
     /** Declares the current content saved, for hosts that persist the result of `save()` themselves. */