ooxml-core 1.22.0 → 1.24.0

package/dist/embedding/index.mjs

@@ -0,0 +1,204 @@
+// embedding/storage.ts
+var FILE_COMMAND_EVENT = "file-command";
+function fileCommandDetail(command, fileName) {
+  return fileName === void 0 ? { command } : { command, fileName };
+}
+function recoveryStoreOf(storage) {
+  if (!storage?.readRecovery || !storage.writeRecovery || !storage.clearRecovery) return void 0;
+  return storage;
+}
+function isDocumentStorage(value) {
+  return typeof value === "object" && value !== null && typeof value.save === "function";
+}
+var MIME_TYPES = {
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  docm: "application/vnd.ms-word.document.macroEnabled.12",
+  dotx: "application/vnd.openxmlformats-officedocument.wordprocessingml.template",
+  doc: "application/msword",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  xlsm: "application/vnd.ms-excel.sheet.macroEnabled.12",
+  xltx: "application/vnd.openxmlformats-officedocument.spreadsheetml.template",
+  xls: "application/vnd.ms-excel",
+  csv: "text/csv",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  pptm: "application/vnd.ms-powerpoint.presentation.macroEnabled.12",
+  ppsx: "application/vnd.openxmlformats-officedocument.presentationml.slideshow",
+  potx: "application/vnd.openxmlformats-officedocument.presentationml.template",
+  ppt: "application/vnd.ms-powerpoint",
+  vsdx: "application/vnd.ms-visio.drawing",
+  vsdm: "application/vnd.ms-visio.drawing.macroEnabled.12",
+  vsd: "application/vnd.visio",
+  txt: "text/plain",
+  json: "application/json"
+};
+function documentMimeType(fileName) {
+  const extension = /\.([^./\\]+)$/.exec(fileName)?.[1]?.toLowerCase() ?? "";
+  return MIME_TYPES[extension] ?? "application/octet-stream";
+}
+function documentSaveMeta(fileName, reason = "save", mimeType = documentMimeType(fileName)) {
+  return { fileName, mimeType, reason };
+}
+async function saveToStorage(storage, bytes, meta) {
+  const result = await storage.save(bytes, meta);
+  const name = result?.fileName?.trim();
+  return name ? name : meta.fileName;
+}
+
+// embedding/backstage.ts
+function hostBackstageItemId(id) {
+  return `host.${id}`;
+}
+function hostBackstagePageId(itemId) {
+  return itemId.startsWith("host.") ? itemId.slice(5) : void 0;
+}
+function acceptedHostBackstagePages(pages) {
+  const seen = /* @__PURE__ */ new Set();
+  const accepted = [];
+  for (const page of pages ?? []) {
+    if (!page || typeof page.id !== "string" || !page.id || seen.has(page.id)) continue;
+    seen.add(page.id);
+    accepted.push({ page, index: accepted.length });
+  }
+  return accepted.sort((a, b) => (a.page.order ?? 0) - (b.page.order ?? 0) || a.index - b.index).map(({ page }) => page);
+}
+function placeHostBackstagePages(items, pages, toEntry) {
+  const entries = [...items];
+  for (const page of acceptedHostBackstagePages(pages)) {
+    const group = page.group ?? "main";
+    let at = entries.length;
+    while (at > 0 && (entries[at - 1]?.group ?? "main") !== group) at--;
+    entries.splice(at === 0 ? entries.length : at, 0, toEntry(page));
+  }
+  return entries;
+}
+
+// embedding/capabilities.ts
+var EDITOR_CAPABILITY_IDS = [
+  /** Changing the document. `false` opens it read-only, whatever the edit prop says. */
+  "edit",
+  /** Saving a copy in another format (File > Export, Save As, Download). */
+  "export",
+  /** Printing (File > Print, the Print commands and Ctrl+P). */
+  "print",
+  /** Sharing the document with other people (File > Share, Share buttons). */
+  "share",
+  /** Copying content out (Copy, Cut and their shortcuts). */
+  "copy",
+  /** Adding and editing comments. */
+  "comment",
+  /** Tracked changes: turning tracking on, accepting and rejecting. */
+  "review",
+  /** Find and Replace. */
+  "find",
+  /** File > New and File > Open. */
+  "open",
+  /** File > Save. */
+  "save",
+  /** File > Options and Customize Ribbon. */
+  "settings"
+];
+function isCapabilityEnabled(capabilities, id) {
+  return capabilities?.[id] !== false;
+}
+function disabledCapabilities(capabilities) {
+  if (!capabilities) return [];
+  return Object.keys(capabilities).filter((id) => capabilities[id] === false);
+}
+function capabilityHiddenActions(capabilities, map) {
+  const hidden = /* @__PURE__ */ new Set();
+  for (const id of disabledCapabilities(capabilities))
+    for (const action of map[id] ?? []) hidden.add(action);
+  return [...hidden];
+}
+function mergeHiddenActions(...lists) {
+  const merged = /* @__PURE__ */ new Set();
+  for (const list of lists) for (const action of list ?? []) merged.add(action);
+  return [...merged];
+}
+
+// embedding/menu-commands.ts
+function hostMenuEntryId(id) {
+  return `host:${id}`;
+}
+function isHostMenuEntry(entry) {
+  return typeof entry === "object" && entry !== null && entry.host === true;
+}
+function resolveHostMenuCommands(commands, context) {
+  const top = [];
+  const bottom = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const command of commands ?? []) {
+    if (!command?.id || seen.has(command.id)) continue;
+    seen.add(command.id);
+    if (command.when && !command.when(context)) continue;
+    const disabled = typeof command.disabled === "function" ? command.disabled(context) : command.disabled === true;
+    const entry = {
+      id: hostMenuEntryId(command.id),
+      host: true,
+      label: command.label,
+      labelKey: "",
+      disabled,
+      onSelect: () => {
+        if (!disabled) command.onSelect(context);
+      }
+    };
+    if (command.icon) entry.icon = command.icon;
+    (command.group === "bottom" ? bottom : top).push(entry);
+  }
+  return { top, bottom };
+}
+function withHostMenuCommands(entries, commands, context) {
+  const { top, bottom } = resolveHostMenuCommands(commands, context);
+  const middle = entries.map(
+    (entry, index) => index === 0 ? { ...entry, separatorBefore: top.length > 0 } : entry
+  );
+  const first = bottom[0];
+  if (first && top.length + middle.length > 0) first.separatorBefore = true;
+  return [...top, ...middle, ...bottom];
+}
+function withoutHiddenEntries(entries, hidden) {
+  const kept = [];
+  let separator = false;
+  for (const entry of entries) {
+    separator ||= entry.separatorBefore === true;
+    if (hidden(entry)) continue;
+    const starts = separator && kept.length > 0;
+    kept.push(
+      entry.separatorBefore === true === starts ? entry : { ...entry, separatorBefore: starts }
+    );
+    separator = false;
+  }
+  return kept;
+}
+
+// embedding/regions.ts
+function hostBackstageRegionId(id) {
+  return `backstage.host.${id}`;
+}
+function sameRenderer(a, b) {
+  if (a === b) return true;
+  if (!a || !b || typeof a !== "object" || typeof b !== "object" || a.element !== b.element)
+    return false;
+  const left = a.properties ?? {};
+  const right = b.properties ?? {};
+  const keys = Object.keys(left);
+  return keys.length === Object.keys(right).length && keys.every((key) => Object.is(left[key], right[key]));
+}
+function sameRegionContext(a, b, callbackKeys = /* @__PURE__ */ new Set(["close"])) {
+  const left = a;
+  const right = b;
+  for (const key of /* @__PURE__ */ new Set([...Object.keys(left), ...Object.keys(right)])) {
+    if (callbackKeys.has(key)) continue;
+    const x = left[key];
+    const y = right[key];
+    if (Array.isArray(x) && Array.isArray(y)) {
+      if (!sameItems(x, y)) return false;
+    } else if (!Object.is(x, y)) return false;
+  }
+  return true;
+}
+function sameItems(a, b) {
+  return a === b || a.length === b.length && a.every((item, index) => Object.is(item, b[index]));
+}
+
+export { EDITOR_CAPABILITY_IDS, FILE_COMMAND_EVENT, acceptedHostBackstagePages, capabilityHiddenActions, disabledCapabilities, documentMimeType, documentSaveMeta, fileCommandDetail, hostBackstageItemId, hostBackstagePageId, hostBackstageRegionId, hostMenuEntryId, isCapabilityEnabled, isDocumentStorage, isHostMenuEntry, mergeHiddenActions, placeHostBackstagePages, recoveryStoreOf, resolveHostMenuCommands, sameRegionContext, sameRenderer, saveToStorage, withHostMenuCommands, withoutHiddenEntries };

package/dist/embedding/menu-commands.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Host context-menu commands: entries a host adds to an editor's right-click menu. Each command
+ * is plain data plus callbacks, so one descriptor works in every editor and framework binding.
+ * The context `C` is a product's immutable snapshot of what the menu was opened on (the
+ * selection, the slide, the cell range); the product documents its shape.
+ */
+/** One host command. Labels are plain text the host has already localised. */
+export interface HostMenuCommand<C> {
+    /** Unique among the host commands of one menu; a repeated or empty id is ignored. */
+    id: string;
+    label: string;
+    /** A name from the shared icon set, for products whose menus show icons. */
+    icon?: string;
+    /** `top` (the default) is a group above the built-in entries; `bottom` one below them. */
+    group?: 'top' | 'bottom';
+    /** Shown only when this returns true (or is omitted). */
+    when?: (context: C) => boolean;
+    /** A disabled command is shown greyed out and never runs. */
+    disabled?: boolean | ((context: C) => boolean);
+    /** Runs after the menu closes, with the context the menu was opened on. */
+    onSelect: (context: C) => void;
+}
+/** A host command resolved for one opening of a menu. */
+export interface HostMenuEntry {
+    /** `host:<id>`, so a host id can never collide with a built-in entry. */
+    id: `host:${string}`;
+    host: true;
+    label: string;
+    /** Kept for menus that look labels up by key; always empty for a host entry. */
+    labelKey: string;
+    icon?: string;
+    separatorBefore?: boolean;
+    disabled: boolean;
+    danger?: boolean;
+    checked?: boolean;
+    /** Runs the command (a no-op when disabled). */
+    onSelect: () => void;
+}
+/** The menu id of host command `id`. */
+export declare function hostMenuEntryId(id: string): `host:${string}`;
+/** True for an entry made from a host command. */
+export declare function isHostMenuEntry(entry: unknown): entry is HostMenuEntry;
+/** The host entries for one opening of a menu, split by group, in the host's order. */
+export declare function resolveHostMenuCommands<C>(commands: readonly HostMenuCommand<C>[] | null | undefined, context: C): {
+    top: HostMenuEntry[];
+    bottom: HostMenuEntry[];
+};
+/**
+ * A menu with the host commands placed: the `top` group before the built-in entries and the
+ * `bottom` group after them, each separated from its neighbours, with no leading or trailing
+ * separator.
+ */
+export declare function withHostMenuCommands<E extends {
+    id: string;
+    separatorBefore?: boolean;
+}, C>(entries: readonly E[], commands: readonly HostMenuCommand<C>[] | null | undefined, context: C): Array<E | HostMenuEntry>;
+/**
+ * A menu without its hidden entries, with its groups intact: a hidden entry that starts a group
+ * (`separatorBefore`) passes the separator on to the next kept entry, and the first kept entry
+ * never starts with one. So hiding entries never merges two groups, never doubles a separator
+ * and never leaves one at the top. `entries` is not changed.
+ */
+export declare function withoutHiddenEntries<E extends {
+    separatorBefore?: boolean;
+}>(entries: readonly E[], hidden: (entry: E) => boolean): E[];
+//# sourceMappingURL=menu-commands.d.ts.map

package/dist/embedding/menu-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu-commands.d.ts","sourceRoot":"","sources":["../../embedding/menu-commands.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,eAAe,CAAC,CAAC;IACjC,qFAAqF;IACrF,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,KAAK,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IACzB,yDAAyD;IACzD,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC;IAC/C,2EAA2E;IAC3E,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;CAC/B;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC7B,yEAAyE;IACzE,EAAE,EAAE,QAAQ,MAAM,EAAE,CAAC;IACrB,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,wCAAwC;AACxC,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,MAAM,EAAE,CAE5D;AAED,kDAAkD;AAClD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED,uFAAuF;AACvF,wBAAgB,uBAAuB,CAAC,CAAC,EACxC,QAAQ,EAAE,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,EAC1D,OAAO,EAAE,CAAC,GACR;IAAE,GAAG,EAAE,aAAa,EAAE,CAAC;IAAC,MAAM,EAAE,aAAa,EAAE,CAAA;CAAE,CA0BnD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,CAAC,EAC1F,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,QAAQ,EAAE,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,EAC1D,OAAO,EAAE,CAAC,GACR,KAAK,CAAC,CAAC,GAAG,aAAa,CAAC,CAQ1B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,EAC3E,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,GAC3B,CAAC,EAAE,CAaL"}

package/dist/embedding/regions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Host regions: places in an editor's layout that a host fills with its own UI (a File tab
+ * page, a dialog body, a docked pane). The editor keeps the place and hands it to the host as
+ * an empty container; the host fills it in any framework, or none, through ONE of two forms:
+ *
+ *  - a mount function `(container, context) => cleanup | handle`, or
+ *  - a custom element: its tag name, or `{ element, properties }`. The editor creates it,
+ *    assigns `properties` once, and keeps its `context` property current.
+ *
+ * The contract is DOM-free: the container type is a parameter, which every product binds to
+ * `HTMLElement` in `ooxml-ui`, where the shared region host mounts it.
+ */
+/** A custom element a region creates (the host registers it). */
+export interface HostRegionElement {
+    /** The tag name, for example `acme-policies`. */
+    element: string;
+    /** Properties assigned to the element once, before it is attached. */
+    properties?: Readonly<Record<string, unknown>>;
+}
+/** What a mount function may return to receive context updates and teardown. */
+export interface HostRegionMountResult<Context> {
+    /** Called with the new context whenever it changes. */
+    update?(context: Context): void;
+    /** Called once when the region unmounts. */
+    destroy?(): void;
+}
+/** Fills `container` for one region. Returns nothing, a cleanup function or a handle. */
+export type HostRegionMount<Container, Context> = (container: Container, context: Context) => void | (() => void) | HostRegionMountResult<Context>;
+/** Any renderer form a region accepts. A string is a custom element tag name. */
+export type HostRegionRenderer<Container, Context> = HostRegionMount<Container, Context> | HostRegionElement | string;
+/** The context every product's host region receives, at least. */
+export interface HostRegionContextBase {
+    /** Which region this renderer fills (for a host File tab page, `backstage.host.<id>`). */
+    readonly region: string;
+    /** The active UI locale (BCP 47). */
+    readonly locale: string;
+    /** False when the document is read-only (prop, capability or protection). */
+    readonly canEdit: boolean;
+    /** Dismisses the region: leaves the File tab, closes a dialog. A no-op where nothing closes. */
+    readonly close: () => void;
+}
+/** Region id a host File tab page is mounted under. */
+export type HostBackstageRegionId = `backstage.host.${string}`;
+/** The region id of host File tab page `id`. */
+export declare function hostBackstageRegionId(id: string): HostBackstageRegionId;
+/**
+ * True when two renderers are the same: the same function, the same tag, or element specs with
+ * the same tag and the same property values (so an inline `{ element, properties }` passed
+ * again on every render does not remount).
+ */
+export declare function sameRenderer<Container, Context>(a: HostRegionRenderer<Container, Context> | undefined, b: HostRegionRenderer<Container, Context> | undefined): boolean;
+/**
+ * Shallow equality over two region contexts. Arrays (a selection) compare by value, and the
+ * fields named in `callbackKeys` are skipped: callbacks are recreated on every render and their
+ * identity is not a change.
+ */
+export declare function sameRegionContext(a: object, b: object, callbackKeys?: ReadonlySet<string>): boolean;
+//# sourceMappingURL=regions.d.ts.map

package/dist/embedding/regions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regions.d.ts","sourceRoot":"","sources":["../../embedding/regions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IACjC,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/C;AAED,gFAAgF;AAChF,MAAM,WAAW,qBAAqB,CAAC,OAAO;IAC7C,uDAAuD;IACvD,MAAM,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,4CAA4C;IAC5C,OAAO,CAAC,IAAI,IAAI,CAAC;CACjB;AAED,yFAAyF;AACzF,MAAM,MAAM,eAAe,CAAC,SAAS,EAAE,OAAO,IAAI,CACjD,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,OAAO,KACZ,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAE1D,iFAAiF;AACjF,MAAM,MAAM,kBAAkB,CAAC,SAAS,EAAE,OAAO,IAC9C,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC,GACnC,iBAAiB,GACjB,MAAM,CAAC;AAEV,kEAAkE;AAClE,MAAM,WAAW,qBAAqB;IACrC,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gGAAgG;IAChG,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC3B;AAED,uDAAuD;AACvD,MAAM,MAAM,qBAAqB,GAAG,kBAAkB,MAAM,EAAE,CAAC;AAE/D,gDAAgD;AAChD,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,qBAAqB,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,OAAO,EAC9C,CAAC,EAAE,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,SAAS,EACrD,CAAC,EAAE,kBAAkB,CAAC,SAAS,EAAE,OAAO,CAAC,GAAG,SAAS,GACnD,OAAO,CAWT;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAChC,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,YAAY,GAAE,WAAW,CAAC,MAAM,CAAsB,GACpD,OAAO,CAYT"}

package/dist/embedding/storage.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Host-owned storage: the contract a host application implements to take over where an embedded
+ * editor reads, saves and keeps recovery copies of its document.
+ *
+ * Every product element (`<docx-editor>`, `<xlsx-editor>`, `<visio-viewer>` and the PowerPoint
+ * viewer of each binding) accepts a {@link DocumentStorage} as its `storage` property. When it is
+ * set, File > Save hands the saved bytes to {@link DocumentStorage.save} instead of downloading
+ * them, File > Open asks {@link DocumentStorage.open} instead of showing the browser's file picker,
+ * and an editor with AutoRecover (PowerPoint, Visio) keeps its recovery copies through the
+ * recovery methods instead of the library's own IndexedDB database. The cancelable
+ * `file-command` event still fires first: a host that prevents it handles the command itself and
+ * the storage is not called.
+ *
+ * DOM-free and format-neutral: the editors only pass bytes, a file name and a reason.
+ */
+/**
+ * A command of the File backstage, title bar or a shortcut, announced as the cancelable
+ * `file-command` event before the editor runs its default. Each product raises the subset it has
+ * (see {@link WordFileCommand}, {@link ExcelFileCommand}, {@link VisioFileCommand}).
+ */
+export type FileCommand = 'new' | 'open' | 'save' | 'saveAs' | 'export' | 'exportText' | 'exportCsv' | 'print' | 'share';
+/** The File commands `<docx-editor>` announces. */
+export type WordFileCommand = Exclude<FileCommand, 'exportCsv'>;
+/** The File commands `<xlsx-editor>` announces. */
+export type ExcelFileCommand = Exclude<FileCommand, 'exportText' | 'share'>;
+/** The File commands `<visio-viewer>` announces. */
+export type VisioFileCommand = Extract<FileCommand, 'new' | 'open' | 'save'>;
+/** The detail of a `file-command` event. */
+export interface FileCommandDetail<C extends string = FileCommand> {
+    command: C;
+    /** Save As and the exports: the name the user chose, when there is one. */
+    fileName?: string;
+}
+/** The event name every editor uses for {@link FileCommandDetail}. */
+export declare const FILE_COMMAND_EVENT = "file-command";
+/** Builds a {@link FileCommandDetail}, leaving `fileName` out rather than undefined. */
+export declare function fileCommandDetail<C extends string>(command: C, fileName?: string): FileCommandDetail<C>;
+/** Why an editor is saving: File > Save (or the Quick Access button, or Ctrl+S) or Save As. */
+export type DocumentSaveReason = 'save' | 'saveAs';
+/** What an editor tells the host about the bytes it hands to {@link DocumentStorage.save}. */
+export interface DocumentSaveMeta {
+    /** The file name the editor would download as, extension included (`Report.docx`). */
+    fileName: string;
+    /** The MIME type of the bytes. */
+    mimeType: string;
+    reason: DocumentSaveReason;
+}
+/** What {@link DocumentStorage.save} may report back. */
+export interface DocumentSaveResult {
+    /** The name the document now has, when the host chose another (a Save As dialog of its own). */
+    fileName?: string;
+}
+/** A document the host opened for the editor. */
+export interface DocumentOpenResult {
+    bytes: Uint8Array;
+    fileName: string;
+}
+/** A recovery copy of a document with unsaved changes. */
+export interface DocumentRecoveryEntry {
+    /** The document id it is kept under (the editors use the file name or the host's file path). */
+    id: string;
+    /** When it was written, in milliseconds since the epoch. */
+    savedAt: number;
+    bytes: Uint8Array;
+}
+/** A recovery copy without its bytes, as {@link DocumentStorage.listRecovery} returns it. */
+export interface DocumentRecoveryInfo {
+    id: string;
+    savedAt: number;
+    /** Size of the copy in bytes. */
+    size: number;
+}
+/**
+ * Storage a host supplies to an editor. Only {@link save} is required; each optional method the
+ * host leaves out keeps the editor's own behaviour for it (the browser file picker for Open, the
+ * library's IndexedDB for recovery copies). The recovery methods are used together: a host
+ * provides `readRecovery`, `writeRecovery` and `clearRecovery`, or none of them.
+ *
+ * Every method may reject; the editor reports a failed save as an error and treats a failed
+ * recovery read or write as "no copy kept".
+ */
+export interface DocumentStorage {
+    /** Store the saved document. Resolve once it is stored; reject to report the save as failed. */
+    save(bytes: Uint8Array, meta: DocumentSaveMeta): Promise<DocumentSaveResult | void>;
+    /** File > Open: resolve with the document to open, or undefined when the user canceled. */
+    open?(): Promise<DocumentOpenResult | undefined>;
+    /** The recovery copy kept under `id`, if any. */
+    readRecovery?(id: string): Promise<DocumentRecoveryEntry | undefined>;
+    /** Keep `entry` as the recovery copy of its id, replacing an earlier one. */
+    writeRecovery?(entry: DocumentRecoveryEntry): Promise<void>;
+    /** Remove the recovery copy kept under `id` (the document was saved or the copy discarded). */
+    clearRecovery?(id: string): Promise<void>;
+    /** Every kept recovery copy, for a version-history or recovery list. Optional even then. */
+    listRecovery?(): Promise<DocumentRecoveryInfo[]>;
+}
+/** The recovery methods of a storage that provides all three of them. */
+export type DocumentRecoveryStore = Required<Pick<DocumentStorage, 'readRecovery' | 'writeRecovery' | 'clearRecovery'>> & Pick<DocumentStorage, 'listRecovery'>;
+/** The storage's recovery store, or undefined when it does not provide one (use the default). */
+export declare function recoveryStoreOf(storage: DocumentStorage | null | undefined): DocumentRecoveryStore | undefined;
+/** True when `value` has the shape of a {@link DocumentStorage} (a `save` function). */
+export declare function isDocumentStorage(value: unknown): value is DocumentStorage;
+/** The MIME type of an Office file name by its extension; `application/octet-stream` otherwise. */
+export declare function documentMimeType(fileName: string): string;
+/** The {@link DocumentSaveMeta} for saving `fileName`, its MIME type taken from the extension. */
+export declare function documentSaveMeta(fileName: string, reason?: DocumentSaveReason, mimeType?: string): DocumentSaveMeta;
+/**
+ * Hands `bytes` to the storage and returns the file name the document has afterwards: the one the
+ * host reported, else `meta.fileName`. Rejects when the storage does.
+ */
+export declare function saveToStorage(storage: DocumentStorage, bytes: Uint8Array, meta: DocumentSaveMeta): Promise<string>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/embedding/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../embedding/storage.ts"],"names":[],"mappings":"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"}