ooxml-ui 1.20.0 → 1.22.0

package/README.md

@@ -10,13 +10,15 @@
 
 Part of [ooxml](https://github.com/ChristopherVR/ooxml#readme): **[Office](https://github.com/ChristopherVR/ooxml#ooxml-office-the-whole-suite-in-one-app)** · [Word](https://github.com/ChristopherVR/ooxml/tree/main/viewers/docx#readme) · [Excel](https://github.com/ChristopherVR/ooxml/tree/main/viewers/xlsx#readme) · [PowerPoint](https://github.com/ChristopherVR/ooxml/tree/main/viewers/pptx#readme) · [Visio](https://github.com/ChristopherVR/ooxml/tree/main/viewers/visio#readme) · [OpenTeams](https://github.com/ChristopherVR/ooxml/tree/main/viewers/teams#readme) · [Core](https://github.com/ChristopherVR/ooxml/tree/main/src/core#readme)
 
-Shared, format-neutral web components and styles for the Office viewers (Word, PowerPoint and
-Excel). Custom elements with shadow-root controls and typed events, no framework. The runtime
+Shared, format-neutral web components and styles for the Office products (Word, Excel, PowerPoint,
+Visio and Teams), and the product editors themselves as `ooxml-ui/<product>` subpaths. Custom
+elements with shadow-root controls and typed events, no framework. The runtime
 dependencies are `ooxml-core` (types and a few pure helpers) and `lit`, which every element is built on
 (see "How the elements are built").
 
 > **You do not install this package.** It is a regular `dependency` of every published editor
-> package (`docx-*-viewer`, `pptx-*-viewer` and `xlsx-*-viewer`), so installing the editor of your framework pulls it
+> package (`docx-*-viewer`, `xlsx-*-viewer`, `pptx-*-viewer`, `visio-*-viewer` and
+> `openteams-*-viewer`), so installing the editor of your framework pulls it
 > in. It is published separately only so that the editors share one copy of the controls. Do not
 > add it to your own install instructions or `package.json`; import controls through the editor
 > package, which registers them for you. Importing `ooxml-ui` directly is for
@@ -45,7 +47,7 @@ strip, task pane, backstage, account, find bar, print preview, ruler), `comments
 - **Updates are synchronous.** Setting a property or attribute redraws the shadow DOM before the call
   returns (the contract the earlier hand-built elements had and every test relies on). The team
   elements keep Lit's batched updates (`static syncUpdates = false`).
-- **Products subclass these elements** (pptx-viewer registers `pptx-ui-*` aliases that keep their own
+- **Products subclass these elements** (`ooxml-ui/pptx` registers `pptx-ui-*` aliases that keep their own
   event names and ids), so the base class keeps what those subclasses lean on: the shadow root exists
   when the constructor returns, a connected element renders on first `shadowRoot` read or in a
   microtask even if a subclass skips `super.connectedCallback()`, and a property that a product hook
@@ -64,7 +66,7 @@ strip, task pane, backstage, account, find bar, print preview, ruler), `comments
 ## Team workspace elements (`ooxml-ui/teams`)
 
 The chat and meeting pieces of the open-source Teams-style workspace (logic in `ooxml-core/teams`,
-app in the `teams-viewer` repository): `office-ui-avatar`, `-app-rail`, `-channel-list`, `-chat-list`,
+app in `viewers/teams`, the editor element in `ooxml-ui/teams`): `office-ui-avatar`, `-app-rail`, `-channel-list`, `-chat-list`,
 `-chat-composer`, `-prejoin`, `-call-grid` and `-call-controls`. Properties in, bubbling `office-*`
 events out, no data fetching; message text is always rendered as text.
 
@@ -122,6 +124,12 @@ applies at once.
 | `ooxml-ui/controls` | button, checkbox, switch, select, ribbon group, toolbar, dialog, status bar and item, zoom slider, tab strip |
 | `ooxml-ui/presence` | `<office-ui-presence>` avatar stack for collaboration awareness                                              |
 | `ooxml-ui/smartart` | `<office-ui-smartart>`: draws a core `DiagramDrawing` as SVG                                                 |
+| `ooxml-ui/teams`    | the Teams elements and `<teams-app>`                                                                         |
+| `ooxml-ui/suite`    | browser document persistence the Office suite uses                                                           |
+| `ooxml-ui/docx`     | the Word editor and viewer elements (`<docx-editor>`)                                                        |
+| `ooxml-ui/xlsx`     | the Excel editor and viewer elements (`<xlsx-editor>`)                                                       |
+| `ooxml-ui/visio`    | the Visio editor and viewer elements (`<visio-viewer>`)                                                      |
+| `ooxml-ui/pptx`     | the PowerPoint renderer, editor and web components; also `/pptx/theme`, `/loader`, `/i18n`, `/ai`, `/dom`    |
 
 Every entry declares an `import` and a `default` export condition, so CommonJS consumers on Node 20.19+ or 22.12+ load it through `require(esm)`.
 
@@ -344,9 +352,10 @@ event detail (`approximatedGeometries`, `approximatedFills`, `flattened3d`); not
 ## Scope
 
 Only what every Office product needs lives here. Product-specific ribbon content (PowerPoint
-slides, transitions, animations; Word styles and review) stays in the viewers. See
-`docs/ooxml-ui-plan.md` in the repository for what moves when, and how the `pptx-ui-*` tags
-become aliases of `office-ui-*`.
+slides, transitions, animations; Word styles and review) lives in the product's own subpath (`src/ui/src/<product>/`), not in the shared entries. The
+`pptx-ui-*` tags are thin subclasses of the `office-ui-*` elements; `docs/ooxml-ui-plan.md` in the
+repository keeps the decisions that still apply (layout, style rules, the tag aliases and the
+token map).
 
 ## Development
 
@@ -387,7 +396,7 @@ expansion budget. Set `reading: true` on a slide stage for accessible reading
 content and native media controls without editing overlays.
 
 [Core and UI source](https://github.com/ChristopherVR/ooxml) |
-[Shared UI plan](https://github.com/ChristopherVR/ooxml/blob/main/docs/ooxml-ui-plan.md)
+[Shared UI decisions](https://github.com/ChristopherVR/ooxml/blob/main/docs/ooxml-ui-plan.md)
 
 ## License
 

package/dist/{chunk-4XPAPETH.js → chunk-DRBAJ5UO.js}

@@ -1993,7 +1993,8 @@ var XLSX_EDITOR_EVENTS = [
   "sheet-change",
   "dirty-change",
   "collaboration-change",
-  "office-ribbon-add-in"
+  "office-ribbon-add-in",
+  "validation-error"
 ];
 var CANCELABLE = /* @__PURE__ */ new Set(["file-command"]);
 function emitEvent(target, type, detail) {

package/dist/{chunk-UB36NYDT.js → chunk-REJECZGV.js}

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

package/dist/docx/building-blocks-actions.d.ts

@@ -0,0 +1,54 @@
+import type { EditorCore } from './editor-core.js';
+import { type SearchStatus } from './search-controller.js';
+/** What a host dialog gets to edit the link at the selection. The host draws the dialog. */
+export interface HyperlinkRequest {
+    /** The link target at the selection, or null when the selection is not a link. */
+    readonly href: string | null;
+    /** The selected text, which becomes the link text. */
+    readonly text: string;
+    /** Applies `href`; `text` replaces the selection (or inserts at the caret) when given. */
+    apply(href: string, text?: string): boolean;
+    remove(): boolean;
+}
+/** Find and replace over the document. Find works while read-only; replace needs edit permission. */
+export interface FindReplaceRequest {
+    readonly status: SearchStatus;
+    readonly canReplace: boolean;
+    search(query: string, caseSensitive?: boolean): SearchStatus;
+    findNext(): boolean;
+    findPrevious(): boolean;
+    replaceOne(replacement: string): boolean;
+    replaceAll(replacement: string): number;
+}
+/** A host picture picker hands the chosen file back through `insert`. */
+export interface ImagePickerRequest {
+    insert(file: File): Promise<boolean>;
+}
+/**
+ * Host-owned workflows for the surface. Each is named like the PowerPoint building blocks'
+ * `onOpen...` callbacks. A workflow without its callback reports as not enabled; the library never
+ * mounts a dialog of its own in surface mode.
+ */
+export interface SurfaceHostActions {
+    onOpenHyperlinkDialog?: ((request: HyperlinkRequest) => void) | undefined;
+    onOpenFindReplace?: ((request: FindReplaceRequest) => void) | undefined;
+    onOpenImagePicker?: ((request: ImagePickerRequest) => void) | undefined;
+}
+/** Enabled flags and openers for the host's link, find/replace and picture workflows. */
+export declare function wordHostActionProps(core: EditorCore): {
+    /** Which workflows the host supplied a callback for, whether or not they are usable now. */
+    hostWorkflows: {
+        hyperlink: boolean;
+        findReplace: boolean;
+        picture: boolean;
+    };
+    canInsertLink: boolean;
+    canFindReplace: boolean;
+    canInsertPicture: boolean;
+    /** Opens the host's link dialog for the selection. Returns false when not enabled. */
+    openHyperlinkDialog: () => boolean;
+    /** Opens the host's find and replace workflow. Returns false when not enabled. */
+    openFindReplace: () => boolean;
+    /** Opens the host's picture picker. Returns false when not enabled. */
+    openImagePicker: () => boolean;
+};

package/dist/docx/building-blocks-status.d.ts

@@ -0,0 +1,34 @@
+import type { EditorCore } from './editor-core.js';
+/**
+ * Page navigation state for custom controls. Pages exist only in Print Layout; in Draft the
+ * document is one continuous page and `pagesAvailable` is false.
+ */
+export declare function wordNavigationProps(core: EditorCore): {
+    labels: Record<string, string>;
+    viewMode: "draft" | "print";
+    /** False in Draft, where there are no pages to move between. */
+    pagesAvailable: boolean;
+    page: number;
+    pageCount: number;
+    pageText: string;
+    canGoPrevious: boolean;
+    canGoNext: boolean;
+    onGoToPage: (target: number) => boolean;
+    onPreviousPage: () => boolean;
+    onNextPage: () => boolean;
+    onViewModeChange: (mode: 'draft' | 'print') => boolean;
+};
+export type WordNavigationProps = ReturnType<typeof wordNavigationProps>;
+/** Word count and zoom state for custom status controls. */
+export declare function wordStatusProps(core: EditorCore): {
+    labels: Record<string, string>;
+    words: number;
+    wordText: string;
+    zoom: number;
+    minZoom: number;
+    maxZoom: number;
+    onZoomChange: (percent: number) => boolean;
+    onZoomIn: () => boolean;
+    onZoomOut: () => boolean;
+};
+export type WordStatusProps = ReturnType<typeof wordStatusProps>;

package/dist/docx/building-blocks.d.ts

@@ -1,11 +1,27 @@
 import type { EditorCore } from './editor-core.js';
+export type WordAlignment = 'left' | 'center' | 'right' | 'justify';
+/** The list kinds a control can apply; `remove` takes a paragraph out of its list. */
+export type WordListChoice = 'bullet' | 'number';
+/** The list the selection is in: a kind a control can apply, `other` for custom lists, or none. */
+export type WordListState = WordListChoice | 'other' | null;
 /** A snapshot of the current editor selection, with commands bound to the same editor. */
 export declare function wordToolbarProps(core: EditorCore): {
+    hostWorkflows: {
+        hyperlink: boolean;
+        findReplace: boolean;
+        picture: boolean;
+    };
+    canInsertLink: boolean;
+    canFindReplace: boolean;
+    canInsertPicture: boolean;
+    openHyperlinkDialog: () => boolean;
+    openFindReplace: () => boolean;
+    openImagePicker: () => boolean;
     labels: {
         [k: string]: string;
     };
     canEdit: boolean;
-    list: 'bullet' | 'decimal' | 'other' | null;
+    list: WordListState;
     selection: {
         from: number;
         to: number;
@@ -15,7 +31,7 @@ export declare function wordToolbarProps(core: EditorCore): {
     underline: boolean | null;
     fontFamily: string | null;
     fontSize: number | null;
-    alignment: string | null;
+    alignment: WordAlignment | null;
     canUndo: boolean;
     canRedo: boolean;
     onBold: () => boolean;
@@ -23,8 +39,8 @@ export declare function wordToolbarProps(core: EditorCore): {
     onUnderline: () => boolean;
     onFontFamilyChange: (family: string) => boolean;
     onFontSizeChange: (size: number) => boolean;
-    onAlignmentChange: (alignment: 'left' | 'center' | 'right' | 'justify') => boolean;
-    onListChange: (kind: 'bullet' | 'number' | 'remove') => boolean;
+    onAlignmentChange: (alignment: WordAlignment) => boolean;
+    onListChange: (kind: WordListChoice | 'remove') => boolean;
     onUndo: () => boolean;
     onRedo: () => boolean;
 };

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

@@ -1,3 +1,4 @@
+import type { SurfaceHostActions } from './building-blocks-actions.js';
 import type { RibbonAddInTab } from '../ribbon/add-in-tabs.js';
 import { FormatDialogs } from './format-dialogs.js';
 import type { EditorState, Transaction } from 'prosemirror-state';
@@ -42,6 +43,8 @@ export interface ShellParts {
     printNoteEditing?: () => void;
     /** Selection frame and gestures for floating pictures on the pages. */
     printFloats?: PrintFloats;
+    /** Detaches read-only selection and keyboard navigation of the surface. */
+    surfaceNavigation?: () => void;
     navigator?: PageNavigator;
     headings?: HeadingNavigator;
 }
@@ -62,6 +65,8 @@ export declare class EditorCore {
     readOnly: boolean;
     /** 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;
     locale: EditorLocale;
     reviewAuthor: string;
     theme: EditorThemeMode;

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

@@ -5,6 +5,8 @@ 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 WordToolbarProps } from './building-blocks.js';
+import { type WordNavigationProps, type WordStatusProps } from './building-blocks-status.js';
+import type { SurfaceHostActions } from './building-blocks-actions.js';
 declare const HTMLElementBase: typeof HTMLElement;
 /**
  * Save, collaboration, dirty-tracking and UI-customisation surface of `<docx-editor>`.
@@ -15,6 +17,16 @@ export declare abstract class DocxEditorApi extends HTMLElementBase {
     get surfaceOnly(): boolean;
     set surfaceOnly(value: boolean);
     getToolbarProps(): WordToolbarProps;
+    /** Page, view mode and navigation callbacks for custom page controls. */
+    getNavigationProps(): WordNavigationProps;
+    /** Word count and zoom for custom status controls. */
+    getStatusProps(): WordStatusProps;
+    /**
+     * Host-owned dialogs for surface mode: `onOpenHyperlinkDialog`, `onOpenFindReplace` and
+     * `onOpenImagePicker`. A workflow without its callback is reported as not enabled.
+     */
+    get surfaceActions(): SurfaceHostActions;
+    set surfaceActions(value: SurfaceHostActions);
     get loading(): boolean;
     /** Selection and formatting updates, including changes which do not dirty the document. */
     subscribeEditorState(listener: () => void): () => void;

package/dist/docx/index.d.ts

@@ -1,5 +1,7 @@
 export { DocxEditorElement, registerDocxEditor } from './component.js';
-export type { WordToolbarProps } from './building-blocks.js';
+export type { WordAlignment, WordListChoice, WordListState, WordToolbarProps, } from './building-blocks.js';
+export type { WordNavigationProps, WordStatusProps } from './building-blocks-status.js';
+export type { FindReplaceRequest, HyperlinkRequest, ImagePickerRequest, SurfaceHostActions, } from './building-blocks-actions.js';
 export { DOCX_EDITOR_EVENTS } from './events.js';
 export type { RibbonAction } from './ribbon.js';
 export { RIBBON_ACTION_IDS, RIBBON_ACTION_LABELS, normalizeRibbonActions, isRibbonActionId, } from 'ooxml-core/docx/ui';

package/dist/docx/insert-controller.d.ts

@@ -50,4 +50,6 @@ export declare class InsertController {
     private applyRulerChange;
     private setShowHidden;
     private insertSelectedPicture;
+    /** Stages `file` and inserts it at the selection; false when it could not be inserted. */
+    insertPictureFile(file: File): Promise<boolean>;
 }

package/dist/docx/locales/en-app.d.ts

@@ -124,6 +124,7 @@ export declare const enApp: {
     readonly 'Next page section break': 'Next page section break';
     readonly 'Continuous section break': 'Continuous section break';
     readonly 'Next page': 'Next page';
+    readonly 'Previous page': 'Previous page';
     readonly Continuous: 'Continuous';
     readonly 'Page numbers': 'Page numbers';
     readonly 'Page number format': 'Page number format';

package/dist/docx/locales/en.d.ts

@@ -287,6 +287,7 @@ export declare const en: {
     readonly 'Next page section break': 'Next page section break';
     readonly 'Continuous section break': 'Continuous section break';
     readonly 'Next page': 'Next page';
+    readonly 'Previous page': 'Previous page';
     readonly Continuous: 'Continuous';
     readonly 'Page numbers': 'Page numbers';
     readonly 'Page number format': 'Page number format';

package/dist/docx/localization-strings.d.ts

@@ -284,6 +284,7 @@ export declare const strings: {
         readonly 'Next page section break': 'Next page section break';
         readonly 'Continuous section break': 'Continuous section break';
         readonly 'Next page': 'Next page';
+        readonly 'Previous page': 'Previous page';
         readonly Continuous: 'Continuous';
         readonly 'Page numbers': 'Page numbers';
         readonly 'Page number format': 'Page number format';

package/dist/docx/surface-navigation.d.ts

@@ -0,0 +1,8 @@
+import type { EditorCore } from './editor-core.js';
+/**
+ * A read-only surface still lets the reader focus the document, select text, move a caret with the
+ * keyboard and copy. ProseMirror renders a non-editable document without a caret, so the browser's
+ * own selection is followed and mirrored into the editor state: custom controls then see it through
+ * `selection` and the formatting snapshot. Nothing here writes to the document. Returns a disposer.
+ */
+export declare function attachSurfaceNavigation(core: EditorCore): () => void;