ooxml-ui 0.19.0 → 0.21.0

package/README.md

@@ -9,8 +9,9 @@
 [Try the apps](https://christophervr.github.io/ooxml/) | [npm](https://www.npmjs.com/package/ooxml-ui) | [Full docs](https://christophervr.github.io/ooxml/) | [Source](https://github.com/ChristopherVR/ooxml)
 
 Shared, format-neutral web components and styles for the Office viewers (Word, PowerPoint and
-Excel). Vanilla custom elements with shadow-root controls, typed events, no framework and no
-runtime dependency except `ooxml-core` (types and a few pure helpers).
+Excel). 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
@@ -19,6 +20,50 @@ runtime dependency except `ooxml-core` (types and a few pure helpers).
 > package, which registers them for you. Importing `ooxml-ui` directly is for
 > the viewer packages themselves and for people building their own Office-style UI.
 
+## How the elements are built
+
+Every element is a Lit class that reads like a component, in a folder named for what it is:
+`<name>.ts` holds the reactive properties and a `render()` template, `<name>.css` the styles (a real
+stylesheet imported as `?raw`, tokens only). The folders are `form/` (checkbox, switch, radio, select,
+search, zoom), `ribbon/` (button, group, stack, toolbar, tabs, section, toggle), `menu/` (menu button
+and item, separator, context menu, command search), `dialog/` (dialog, options dialog, dialog footer),
+`notices/` (toasts, read-only banner, paste options), `chrome/` (title bar, status bar and item, tab
+strip, backstage, account, find bar, print preview, ruler), `presence/`, `smartart/` and `teams/`.
+
+- **`OfficeElement`** (`base.ts`) is the base class, exported for products that build their own
+  elements. Bare `var(--office-x)` in a `.css` file gets the token's default when the sheet loads
+  (`withTokens`), so an element renders correctly with or without the installed theme.
+- **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
+  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
+  reads as an attribute (`icon`, `command`, `launcher`, `placement`) writes the attribute through.
+  A constructor must not assign a property a subclass may override with its own accessor (it would
+  run the subclass's setter before its fields exist); such state (`state`, `groups`, ...) lives in a
+  private field behind a hand-written accessor.
+- **Text is exact.** Text-bearing elements are written without whitespace between nodes, because
+  consumers compare `textContent`. `oxfmt` is set to `htmlWhitespaceSensitivity: "strict"` for
+  `packages/ui/src` (not `teams/`) so it never adds whitespace to a template; `glyph.ts` opts out of
+  the formatter with `// prettier-ignore` because it reflows `<svg>` regardless.
+- **`ribbon-section` and `keytips`** keep imperative DOM on purpose: the section patches light-DOM
+  children keyed by id (so focus and a product's tags survive), and keytips attaches a badge layer to
+  a scope it does not own.
+
+## 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`,
+`-chat-composer`, `-prejoin`, `-call-grid` and `-call-controls`. Properties in, bubbling `office-*`
+events out, no data fetching; message text is always rendered as text.
+
+```ts
+import { registerOfficeUi } from 'ooxml-ui';
+registerOfficeUi(); // defines every element, idempotent
+```
+
 ## Install
 
 Applications using a viewer receive this package as a dependency. For a custom
@@ -60,40 +105,41 @@ with an incompatible build of this package.
 
 ## Features: elements
 
-| Tag                                                   | Attributes / properties                                                                                                                                                                                                                                                                                                   | Events (all bubble, composed)                                                                                                                     |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `office-ui-button`                                    | `label`, `icon`, `command`, `disabled`, `pressed`, `expanded`, `icon-only`, `variant="stacked"`, `keyshortcuts`                                                                                                                                                                                                           | `office-command` `{ command }`                                                                                                                    |
-| `office-ui-checkbox`, `office-ui-switch`              | `checked`, `disabled`, `value`, `aria-label`; form-associated                                                                                                                                                                                                                                                             | `input`, `change`                                                                                                                                 |
-| `office-ui-select`                                    | `<option>` / `<optgroup>` children (`data-display-label`, `data-description`, font previews) or the `options` property `[{ value, label, disabled? }]`; `value`, `selectedIndex`, `disabled`, `aria-label`, `variant="ribbon-font"                                                                                        | "ribbon-icon"`, `data-font-picker`; `icon`and`custom` slots; arrows, Home, End, PageUp/PageDown, typeahead                                        | `input`, `change` |
-| `office-ui-ribbon-group`                              | `label`, `launcher` (dialog launcher command), `launcher-disabled`; default slot                                                                                                                                                                                                                                          | launcher: `office-command` `{ command }`                                                                                                          |
-| `office-ui-ribbon-stack`                              | `orientation="horizontal"`; default slot (three-row column of small commands by default)                                                                                                                                                                                                                                  | none                                                                                                                                              |
-| `office-ui-menu-button` / `-menu-item`                | button: `label`, `icon`, `command` (split button), `variant`, `disabled`, `keyshortcuts`; item: `command`, `label`, `icon`, `disabled`, `checked`                                                                                                                                                                         | item choice: `office-command` `{ command }`                                                                                                       |
-| `office-ui-toolbar`                                   | `aria-label`, `aria-orientation`; arrow-key focus movement                                                                                                                                                                                                                                                                | none                                                                                                                                              |
-| `office-ui-dialog`                                    | `open`, `heading`, `dismissible="false"`, `show()`, `close()`; slots default, `footer`                                                                                                                                                                                                                                    | `office-dialog-close` `{ reason }` (cancelable)                                                                                                   |
-| `office-ui-status-bar` / `-status-item`               | `label`, `value`, `interactive`, `id`; controlled bar: `state` `{ items?, toggles?, views?, zoom? }` with `collaboration` and `end` slots                                                                                                                                                                                 | `office-status-activate` `{ id }`                                                                                                                 |
-| `office-ui-zoom-slider`                               | `value` (percent), `min`, `max`, `step`, `disabled`, `fit` (fit button name), `label`                                                                                                                                                                                                                                     | `input`, `change`; fit: `office-command` `{ command: 'zoom-fit' }`                                                                                |
-| `office-ui-tab-strip`                                 | `tabs` `[{ id, label, title? }]`, `selected`, `label`, `previous-label`, `next-label`, `add-label`, `add-disabled`, `add-title`, `disabled`                                                                                                                                                                               | `office-tab-select` `{ id }` (cancelable); add: `office-command` `{ command: 'tab-add' }`                                                         |
-| `office-ui-context-menu` / `office-ui-menu-separator` | Children mode: `label`, `openAt(x, y)`, `close()`, `open` over `office-ui-menu-item` and separator children. Controlled mode: `state` `{ x, y, label, items: [{ id, label, separatorBefore?, heading?, danger?, disabled?, checked?, icon? }], markers?, zIndex?, autoFocus? }`; arrows, Home, End and type-ahead in both | children: item `office-command` `{ command }`; controlled: `office-menu-request` `{ id }`, `office-menu-close` `{ reason }` (never closes itself) |
-| `office-ui-command-search`                            | `commands` `[{ id, label, keywords?, description?, disabled?, title? }]`, `placeholder`, `label`, `limit` (Office's "Tell me what you want to do")                                                                                                                                                                        | choice: `office-command` `{ command }`                                                                                                            |
-| `office-ui-options-dialog`                            | `categories` `[{ id, label, description?, disabled?, sections: [{ id, title, controls }] }]` (controls: `toggle`, `select`, `number`, `text`, each optionally `disabled` with a reason), `values`, `category`, `open`, `heading`, `show()`, `close()`                                                                     | OK: `office-options-change` `{ values, changed }`                                                                                                 |
-| `office-ui-account`                                   | `profile` `{ displayName, avatarColor, initial? }`; slots `sign-in` and default (product sections)                                                                                                                                                                                                                        | `office-profile-change` `{ profile }`                                                                                                             |
-| `office-ui-ribbon`                                    | Tab row over tab panels. Panels are children with `data-ribbon-tab`, `data-label`, optional `data-tab-keytip`; slots `quick-access`, `search`, `end`; `selected`, `label`, `file-label`, `no-file`, `file-expanded`, `file-keytip`; `focusFile()`, `focusTab()`                                                           | `office-ribbon-select` `{ tab }` (cancelable), `office-ribbon-file`                                                                               |
-| `office-ui-backstage`                                 | `items` `[{ id, label, group?: 'footer', disabled?, title? }]`, `open`, `selected`, `label`, `back-label`, `show(page?)`, `close()`; pages are children with `data-backstage-page`                                                                                                                                        | `office-backstage-select` `{ id }` (cancelable), `office-backstage-close` `{ reason }` (cancelable)                                               |
-| `office-ui-find-bar`                                  | `open`, `label`, `input-label`, `placeholder`, `maxlength`, `disabled`, `navigation-disabled`, `previous-label`, `next-label`, `close-label`; `value`, `status`, `statusTitle`, `show()`, `close()`                                                                                                                       | `office-find-input` `{ query }`, `office-find-step` `{ direction }`, `office-find-close`                                                          |
-| `office-ui-ruler`                                     | `orientation="vertical"`, `origin` (px offset of zero), `scale` (px per unit, default 96), `direction="reverse"`; decorative                                                                                                                                                                                              | none                                                                                                                                              |
-| `office-ui-print-preview`                             | `pages` (rendered nodes; an inert clone of the current one is shown), `index`, `label`, `empty-label`                                                                                                                                                                                                                     | `office-print-preview-page` `{ index }`                                                                                                           |
-| `office-ui-radio`                                     | `checked`, `disabled`, `value`, `name`; radios of one tag sharing a `name` form a roving-focus group; form-associated                                                                                                                                                                                                     | `input`, `change`                                                                                                                                 |
-| `office-ui-search`                                    | `value`, `placeholder`, `disabled`, `aria-label`, `variant="titlebar"`; `focus()`, `select()`                                                                                                                                                                                                                             | `input`, `change`                                                                                                                                 |
-| `office-ui-ribbon-toggle`                             | `label`, `checked`, `disabled`, `title`, `command` (a labelled ribbon checkbox row; static `checkboxTag` picks the inner checkbox)                                                                                                                                                                                        | `office-toggle` `{ command, checked }`                                                                                                            |
-| `office-ui-dialog-footer`                             | `state` `{ actions: [{ id, label, variant?, icon?, disabled?, busy?, title?, align?, testId? }] }`, `focusAction(id)`                                                                                                                                                                                                     | `office-dialog-footer-request` `{ id }`                                                                                                           |
-| `office-ui-toasts`                                    | `state` `{ toasts: [{ id, code?, severity, message }], overflowCount?, labels? }`; hidden when empty, host positions it                                                                                                                                                                                                   | `office-toasts-request` `{ id: 'dismiss', toastId }` or `{ id: 'dismissAll' }`                                                                    |
-| `office-ui-read-only-banner`                          | `state` `{ kind, message, passwordPromptOpen?, passwordError?, checkingPassword?, labels? }`                                                                                                                                                                                                                              | `office-read-only-request` (Edit anyway, Dismiss, password submit or cancel)                                                                      |
-| `office-ui-paste-options`                             | `state` `{ left, top, options: [{ id, label }], label? }`; fixed 4px past the pasted object                                                                                                                                                                                                                               | `office-paste-options-request` `{ format }`, `office-paste-options-dismiss`                                                                       |
-| `office-ui-title-bar`                                 | `state` `{ appMark?, fileName, status?, tone?, autosave?, quickAccess?: { label, items, showLabels? }, search? }`, `placement` (`titleBar`, `belowRibbon`); slots `collaboration`, `account`; tokens `--office-title-bar-*`                                                                                               | `office-autosave-toggle`, `office-command` `{ command }`, `office-command-search` `{ query, command? }`                                           |
-| `office-ui-ribbon-section`                            | `groups` `[{ id, label, commands: [{ id, label, icon, title?, size?, badge?, disabled?, active?, compact?, hidden?, caret?, pressed?, expanded?, column? }] }]`; keyed groups and commands in the light DOM                                                                                                               | the commands' own events (`office-command`)                                                                                                       |
-| `office-ui-presence`                                  | `participants`, `max`, `label`                                                                                                                                                                                                                                                                                            | `office-presence-select` `{ id }`                                                                                                                 |
-| `office-ui-smartart`                                  | `drawing` (core `DiagramDrawing`), `schemeColors`, `label`                                                                                                                                                                                                                                                                | `office-smartart-render` (render report)                                                                                                          |
-| `office-ui-icon`                                      | `name`, `label`                                                                                                                                                                                                                                                                                                           | none                                                                                                                                              |
+| Tag                                                   | Attributes / properties                                                                                                                                                                                                                                                                                                         | Events (all bubble, composed)                                                                                                                     |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `office-ui-button`                                    | `label`, `icon`, `command`, `disabled`, `pressed`, `expanded`, `icon-only`, `variant="stacked"`, `keyshortcuts`                                                                                                                                                                                                                 | `office-command` `{ command }`                                                                                                                    |
+| `office-ui-checkbox`, `office-ui-switch`              | `checked`, `disabled`, `value`, `aria-label`; form-associated                                                                                                                                                                                                                                                                   | `input`, `change`                                                                                                                                 |
+| `office-ui-select`                                    | `<option>` / `<optgroup>` children (`data-display-label`, `data-description`, font previews) or the `options` property `[{ value, label, disabled? }]`; `value`, `selectedIndex`, `disabled`, `aria-label`, `variant="ribbon-font"                                                                                              | "ribbon-icon"`, `data-font-picker`; `icon`and`custom` slots; arrows, Home, End, PageUp/PageDown, typeahead                                        | `input`, `change` |
+| `office-ui-ribbon-group`                              | `label`, `launcher` (dialog launcher command), `launcher-disabled`; default slot                                                                                                                                                                                                                                                | launcher: `office-command` `{ command }`                                                                                                          |
+| `office-ui-ribbon-stack`                              | `orientation="horizontal"`; default slot (three-row column of small commands by default)                                                                                                                                                                                                                                        | none                                                                                                                                              |
+| `office-ui-menu-button` / `-menu-item`                | button: `label`, `icon`, `command` (split button), `variant`, `disabled`, `keyshortcuts`; item: `command`, `label`, `icon`, `disabled`, `checked`                                                                                                                                                                               | item choice: `office-command` `{ command }`                                                                                                       |
+| `office-ui-toolbar`                                   | `aria-label`, `aria-orientation`; arrow-key focus movement                                                                                                                                                                                                                                                                      | none                                                                                                                                              |
+| `office-ui-dialog`                                    | `open`, `heading`, `dismissible="false"`, `show()`, `close()`; slots default, `footer`                                                                                                                                                                                                                                          | `office-dialog-close` `{ reason }` (cancelable)                                                                                                   |
+| `office-ui-status-bar` / `-status-item`               | `label`, `value`, `interactive`, `id`; controlled bar: `state` `{ items?, toggles?, views?, zoom? }` with `collaboration` and `end` slots                                                                                                                                                                                       | `office-status-activate` `{ id }`                                                                                                                 |
+| `office-ui-zoom-slider`                               | `value` (percent), `min`, `max`, `step`, `disabled`, `fit` (fit button name), `label`                                                                                                                                                                                                                                           | `input`, `change`; fit: `office-command` `{ command: 'zoom-fit' }`                                                                                |
+| `office-ui-tab-strip`                                 | `tabs` `[{ id, label, title? }]`, `selected`, `label`, `previous-label`, `next-label`, `add-label`, `add-disabled`, `add-title`, `disabled`                                                                                                                                                                                     | `office-tab-select` `{ id }` (cancelable); add: `office-command` `{ command: 'tab-add' }`                                                         |
+| `office-ui-context-menu` / `office-ui-menu-separator` | Children mode: `label`, `openAt(x, y)`, `close()`, `open` over `office-ui-menu-item` and separator children. Controlled mode: `state` `{ x, y, label, items: [{ id, label, separatorBefore?, heading?, danger?, disabled?, checked?, icon? }], markers?, zIndex?, autoFocus? }`; arrows, Home, End and type-ahead in both       | children: item `office-command` `{ command }`; controlled: `office-menu-request` `{ id }`, `office-menu-close` `{ reason }` (never closes itself) |
+| `office-ui-command-search`                            | `commands` `[{ id, label, keywords?, description?, disabled?, title? }]`, `placeholder`, `label`, `limit` (Office's "Tell me what you want to do")                                                                                                                                                                              | choice: `office-command` `{ command }`                                                                                                            |
+| `office-ui-options-dialog`                            | `categories` `[{ id, label, description?, disabled?, sections: [{ id, title, controls }] }]` (controls: `toggle`, `select`, `number`, `text`, each optionally `disabled` with a reason), `values`, `category`, `open`, `heading`, `show()`, `close()`                                                                           | OK: `office-options-change` `{ values, changed }`                                                                                                 |
+| `office-ui-account`                                   | `profile` `{ displayName, avatarColor, initial? }`; slots `sign-in` and default (product sections)                                                                                                                                                                                                                              | `office-profile-change` `{ profile }`                                                                                                             |
+| `office-ui-ribbon`                                    | Tab row over tab panels. Panels are children with `data-ribbon-tab`, `data-label`, optional `data-tab-keytip`; slots `quick-access`, `search`, `end`; `selected`, `label`, `file-label`, `no-file`, `file-expanded`, `file-keytip`; `focusFile()`, `focusTab()`                                                                 | `office-ribbon-select` `{ tab }` (cancelable), `office-ribbon-file`                                                                               |
+| `office-ui-backstage`                                 | `items` `[{ id, label, group?: 'footer', disabled?, title? }]`, `open`, `selected`, `label`, `back-label`, `show(page?)`, `close()`; pages are children with `data-backstage-page`                                                                                                                                              | `office-backstage-select` `{ id }` (cancelable), `office-backstage-close` `{ reason }` (cancelable)                                               |
+| `office-ui-find-bar`                                  | `open`, `label`, `input-label`, `placeholder`, `maxlength`, `disabled`, `navigation-disabled`, `previous-label`, `next-label`, `close-label`; `value`, `status`, `statusTitle`, `show()`, `close()`                                                                                                                             | `office-find-input` `{ query }`, `office-find-step` `{ direction }`, `office-find-close`                                                          |
+| `office-ui-ruler`                                     | `orientation="vertical"`, `origin` (px offset of zero), `scale` (px per unit, default 96), `direction="reverse"`; decorative                                                                                                                                                                                                    | none                                                                                                                                              |
+| `office-ui-print-preview`                             | `pages` (rendered nodes; an inert clone of the current one is shown), `index`, `label`, `empty-label`                                                                                                                                                                                                                           | `office-print-preview-page` `{ index }`                                                                                                           |
+| `office-ui-radio`                                     | `checked`, `disabled`, `value`, `name`; radios of one tag sharing a `name` form a roving-focus group; form-associated                                                                                                                                                                                                           | `input`, `change`                                                                                                                                 |
+| `office-ui-search`                                    | `value`, `placeholder`, `disabled`, `aria-label`, `variant="titlebar"`; `focus()`, `select()`                                                                                                                                                                                                                                   | `input`, `change`                                                                                                                                 |
+| `office-ui-ribbon-toggle`                             | `label`, `checked`, `disabled`, `title`, `command` (a labelled ribbon checkbox row; static `checkboxTag` picks the inner checkbox)                                                                                                                                                                                              | `office-toggle` `{ command, checked }`                                                                                                            |
+| `office-ui-dialog-footer`                             | `state` `{ actions: [{ id, label, variant?, icon?, disabled?, busy?, title?, align?, testId? }] }`, `focusAction(id)`                                                                                                                                                                                                           | `office-dialog-footer-request` `{ id }`                                                                                                           |
+| `office-ui-toasts`                                    | `state` `{ toasts: [{ id, code?, severity, message }], overflowCount?, labels? }`; hidden when empty, host positions it                                                                                                                                                                                                         | `office-toasts-request` `{ id: 'dismiss', toastId }` or `{ id: 'dismissAll' }`                                                                    |
+| `office-ui-read-only-banner`                          | `state` `{ kind, message, passwordPromptOpen?, passwordError?, checkingPassword?, labels? }`                                                                                                                                                                                                                                    | `office-read-only-request` (Edit anyway, Dismiss, password submit or cancel)                                                                      |
+| `office-ui-paste-options`                             | `state` `{ left, top, options: [{ id, label }], label? }`; fixed 4px past the pasted object                                                                                                                                                                                                                                     | `office-paste-options-request` `{ format }`, `office-paste-options-dismiss`                                                                       |
+| `office-ui-title-bar`                                 | `state` `{ appMark?, fileName, status?, tone?, autosave?, quickAccess?: { label, items, showLabels? }, search? }`, `placement` (`titleBar`, `belowRibbon`); slots `collaboration`, `account`; tokens `--office-title-bar-*`                                                                                                     | `office-autosave-toggle`, `office-command` `{ command }`, `office-command-search` `{ query, command? }`                                           |
+| `office-ui-ribbon-section`                            | `groups` `[{ id, label, commands: [{ id, label, icon, title?, size?, badge?, disabled?, active?, compact?, hidden?, caret?, pressed?, expanded?, column? }] }]`; keyed groups and commands in the light DOM                                                                                                                     | the commands' own events (`office-command`)                                                                                                       |
+| `office-ui-gallery`                                   | `state` `{ id, label, moreLabel?, disabled?, command?, sections: [{ title?, columns, tileWidth, tileHeight, items: [{ id, label, applied?, preview? }] }], inline? }`, `mode` (`inline`), `chevron-only`, `icon`; `open`, `disabled`, `close()`; tiles in light DOM (`data-gallery-item`), previews parsed by `parseSvgPreview` | `office-gallery-pick` `{ gallery, itemId }`                                                                                                       |
+| `office-ui-presence`                                  | `participants`, `max`, `label`                                                                                                                                                                                                                                                                                                  | `office-presence-select` `{ id }`                                                                                                                 |
+| `office-ui-smartart`                                  | `drawing` (core `DiagramDrawing`), `schemeColors`, `label`                                                                                                                                                                                                                                                                      | `office-smartart-render` (render report)                                                                                                          |
+| `office-ui-icon`                                      | `name`, `label`                                                                                                                                                                                                                                                                                                                 | none                                                                                                                                              |
 
 The local profile behind `office-ui-account` is stored on the device only, under one suite-wide
 key (`readOfficeProfile`, `writeOfficeProfile`, `clearOfficeProfile`), so every Office viewer on

package/dist/base.d.ts

@@ -0,0 +1,118 @@
+import { LitElement, type CSSResult, type PropertyDeclaration, type PropertyDeclarations } from 'lit';
+/**
+ * Give every bare `var(--office-x)` in a stylesheet the token's default, so a control renders
+ * correctly with or without the installed theme (the same fallback `tok()` writes). Sheets stay
+ * plain CSS; unknown names and private `--_x` helpers are left alone.
+ */
+export declare function withTokens(css: string): string;
+/** An element's style list: the shared control basics plus its own `.css` files. */
+export declare const controlStyles: (...sheets: string[]) => CSSResult[];
+/**
+ * A boolean attribute that reflects. A property value of `''` counts as present (`checked=""`),
+ * so frameworks that pass attribute idioms through properties keep working.
+ */
+export declare const flag: {
+    type: BooleanConstructor;
+    reflect: true;
+    converter: {
+        fromAttribute: (value: string | null) => boolean;
+        toAttribute: (value: unknown) => string | null;
+    };
+};
+/** A boolean attribute that is read but never written back (`icon-only`, `caret`). */
+export declare const readFlag: {
+    type: BooleanConstructor;
+    converter: {
+        fromAttribute: (value: string | null) => boolean;
+    };
+};
+/** `pressed="true|false"` as a tri-state: absent is `undefined`, `""` and anything but `false` is true. */
+export declare const triState: {
+    reflect: true;
+    converter: {
+        fromAttribute: (value: string | null) => boolean | undefined;
+        toAttribute: (value: unknown) => string | null;
+    };
+};
+/** A `value` that reads `'on'` while its attribute is absent, like a native checkbox or radio. */
+export declare const valueOn: {
+    type: StringConstructor;
+    converter: {
+        fromAttribute: (value: string | null) => string;
+    };
+};
+export type OfficeProperties = PropertyDeclarations;
+/**
+ * Base class of the ooxml-ui elements. Products subclass these elements (they register an alias
+ * tag that keeps their own names), and the earlier hand-built elements always had their shadow DOM
+ * the moment the constructor returned. So, unlike a plain Lit element:
+ *
+ * - The shadow root exists as soon as the constructor returns, so a subclass can attach its own
+ *   styles there.
+ * - Reading `shadowRoot` of an element that has not rendered yet renders it first (host writes
+ *   are held back until it connects and the element re-renders), so a subclass or a host that inspects the shadow DOM right
+ *   after construction, or before connecting, finds it. A
+ *   microtask renders a connected element that nothing else rendered, for a subclass that
+ *   overrides `connectedCallback` without calling `super`.
+ * - Updates are synchronous: setting a property or attribute has redrawn the shadow DOM before
+ *   the call returns, whether or not the element is connected, the contract every consumer and
+ *   test already relies on. An element that prefers Lit's batched updates sets
+ *   `static syncUpdates = false`.
+ *
+ * A constructor must not assign a property a subclass may override with its own accessor (that
+ * would run the subclass's setter before its fields exist); elements keep such state in a private
+ * field behind a hand-written accessor instead.
+ */
+export declare class OfficeElement extends LitElement {
+    static syncUpdates: boolean;
+    private _rendering?;
+    private _ready?;
+    constructor();
+    /**
+     * Render now if the element has never rendered; a no-op afterwards or while rendering. A
+     * disconnected element may be rendered here from inside a constructor (a subclass reading
+     * `shadowRoot`), and a constructor may not add host attributes, so while it renders its host
+     * writes are queued and applied before the next write or update, or on connection.
+     */
+    ensureRendered(): void;
+    private _detachedRender?;
+    /** True while a detached first render runs (inside a constructor, maybe): no children may be added. */
+    protected get detachedFirstRender(): boolean;
+    private _queue;
+    private _deferring?;
+    /** Write to the host element: queued (and dropped) during a detached first render, else applied at once. */
+    protected hostWrite(write: () => void): void;
+    /**
+     * Forget the host writes a detached first render queued. They are stale by the time anything
+     * else happens (replaying one would fire an attribute change that overwrites a newer property),
+     * and the render that follows connecting recomputes every host write from the current state.
+     */
+    protected flushHost(): void;
+    setAttribute(name: string, value: string): void;
+    removeAttribute(name: string): void;
+    toggleAttribute(name: string, force?: boolean): boolean;
+    /**
+     * Reflecting properties write their attribute as soon as they are set, even before the element
+     * connects (Lit alone reflects during an update). A `flag` property also stores a real
+     * boolean whatever it is given, so a framework writing `''` (the attribute idiom for
+     * "present") reads back `true`.
+     */
+    static createProperty(name: PropertyKey, options?: PropertyDeclaration): void;
+    /**
+     * Attributes the element reads straight from the DOM, without a property of the same name: a
+     * product subclass reads them too, and a framework that assigns properties it finds (React 19)
+     * must write the attribute instead. Changing one redraws the element.
+     */
+    static watched: readonly string[];
+    static get observedAttributes(): string[];
+    private fromAttribute;
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    /** Write a property's value to its attribute now, unless the attribute is where it came from. */
+    protected reflectAttribute(attribute: string, value: unknown, options: PropertyDeclaration): void;
+    /** Dispatch a bubbling, composed event with `detail`. */
+    protected fire<T>(type: string, detail: T, cancelable?: boolean): boolean;
+    private get immediate();
+    connectedCallback(): void;
+    protected performUpdate(): void | Promise<unknown>;
+    requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: PropertyDeclaration): void;
+}

package/dist/{account.d.ts → chrome/account-profile.d.ts}

@@ -30,10 +30,4 @@ export declare function readOfficeProfile(storage?: StorageLike | undefined, key
 export declare function writeOfficeProfile(profile: OfficeProfile, storage?: StorageLike | undefined, key?: string): void;
 /** Forget the stored profile. */
 export declare function clearOfficeProfile(storage?: StorageLike | undefined, key?: string): void;
-/**
- * `<office-ui-account>`: User Information with avatar, display name and avatar colour. Set or read
- * `profile`; edits emit `office-profile-change`. `slot="sign-in"` hosts a product sign-in flow;
- * the default slot holds product sections (theme, product information).
- */
-export declare const defineAccount: import("./registry.js").Definer;
 export {};

package/dist/chrome/account.d.ts

@@ -0,0 +1,17 @@
+import { OfficeElement } from '../base.js';
+import { type OfficeProfile } from './account-profile.js';
+/**
+ * `<office-ui-account>`: User Information with avatar, display name and avatar colour. Set or read
+ * `profile`; edits emit `office-profile-change`. `slot="sign-in"` hosts a product sign-in flow;
+ * the default slot holds product sections (theme, product information).
+ */
+export declare class OfficeUiAccount extends OfficeElement {
+    static styles: import("lit").CSSResult[];
+    private current;
+    get profile(): OfficeProfile;
+    set profile(value: OfficeProfile);
+    private change;
+    private onSwatchKey;
+    protected render(): import("lit").TemplateResult<1>;
+}
+export declare const defineAccount: import("../registry.js").Definer;

package/dist/chrome/backstage.d.ts

@@ -0,0 +1,78 @@
+import { OfficeElement } from '../base.js';
+/**
+ * Office's File view (backstage): a navigation column and one page per item. Generalised from
+ * pptx-viewer's `BACKSTAGE_NAV` model (render/backstage.ts) and the Visio viewer's backstage.
+ */
+export interface OfficeBackstageItem {
+    id: string;
+    label: string;
+    /** Items in the footer group sit at the bottom of the column (Account, Options). */
+    group?: 'footer';
+    disabled?: boolean;
+    /** Tooltip, for example why an item is disabled. */
+    title?: string;
+}
+/** An item was chosen; cancelable (`preventDefault()` keeps the current page). */
+export type OfficeBackstageSelectEvent = CustomEvent<{
+    id: string;
+}>;
+export type OfficeBackstageCloseEvent = CustomEvent<{
+    reason: 'back' | 'escape' | 'api';
+}>;
+/**
+ * `<office-ui-backstage>`: set `items`, put one light-DOM child per page with
+ * `data-backstage-page="<id>"`, then `show(id)`. Choosing an item emits `office-backstage-select`
+ * and, unless prevented, shows its page; items without a page (Save, Close) only emit. Back and
+ * Escape emit a cancelable `office-backstage-close` and close. Attributes: `open`, `selected`,
+ * `label` (default "File"), `back-label`. Nav buttons carry `data-backstage-item`.
+ */
+export declare class OfficeUiBackstage extends OfficeElement {
+    static styles: import("lit").CSSResult[];
+    static properties: {
+        open: {
+            type: BooleanConstructor;
+            reflect: true;
+            converter: {
+                fromAttribute: (value: string | null) => boolean;
+                toAttribute: (value: unknown) => string | null;
+            };
+        };
+        items: {
+            attribute: boolean;
+        };
+        label: {
+            type: StringConstructor;
+        };
+        backLabel: {
+            attribute: string;
+            type: StringConstructor;
+        };
+        selected: {
+            type: StringConstructor;
+            noAccessor: boolean;
+        };
+    };
+    open: boolean;
+    items: readonly OfficeBackstageItem[];
+    label: string | null;
+    backLabel: string | null;
+    private picked;
+    constructor();
+    get selected(): string;
+    set selected(id: string | null);
+    /** Open on a page (default: the selected one) and focus its item. */
+    show(page?: string): void;
+    /** Close without asking (emits `office-backstage-close` with reason `api`). */
+    close(): void;
+    private page;
+    private button;
+    private choose;
+    private requestClose;
+    private onNavClick;
+    /** Exactly the selected page of the light DOM shows. */
+    private syncPages;
+    protected updated(): void;
+    private item;
+    protected render(): import("lit").TemplateResult<1>;
+}
+export declare const defineBackstage: import("../registry.js").Definer;

package/dist/chrome/find-bar.d.ts

@@ -0,0 +1,111 @@
+import { OfficeElement } from '../base.js';
+export type OfficeFindInputEvent = CustomEvent<{
+    query: string;
+}>;
+export type OfficeFindStepEvent = CustomEvent<{
+    direction: 'next' | 'previous';
+}>;
+/**
+ * `<office-ui-find-bar>`: Office's on-demand Find bar under the ribbon. Shown while `open`;
+ * `show()` opens it and selects the query. Enter steps to the next result, Shift+Enter to the
+ * previous; Escape clears a query, or closes the bar when it is already empty. Attributes:
+ * `open`, `label`, `input-label`, `placeholder`, `maxlength`, `disabled`, `navigation-disabled`,
+ * `previous-label`, `next-label`, `close-label`. Properties: `value`, `status`, `statusTitle`.
+ * Events: `office-find-input` `{ query }`, `office-find-step` `{ direction }`, `office-find-close`.
+ */
+export declare class OfficeUiFindBar extends OfficeElement {
+    static shadowRootOptions: {
+        clonable?: boolean;
+        customElementRegistry?: CustomElementRegistry | null;
+        mode: ShadowRootMode;
+        serializable?: boolean;
+        slotAssignment?: SlotAssignmentMode;
+        delegatesFocus: boolean;
+    };
+    static styles: import("lit").CSSResult[];
+    static properties: {
+        open: {
+            type: BooleanConstructor;
+            reflect: true;
+            converter: {
+                fromAttribute: (value: string | null) => boolean;
+                toAttribute: (value: unknown) => string | null;
+            };
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: true;
+            converter: {
+                fromAttribute: (value: string | null) => boolean;
+                toAttribute: (value: unknown) => string | null;
+            };
+        };
+        navigationDisabled: {
+            type: BooleanConstructor;
+            reflect: true;
+            converter: {
+                fromAttribute: (value: string | null) => boolean;
+                toAttribute: (value: unknown) => string | null;
+            };
+            attribute: string;
+        };
+        label: {
+            type: StringConstructor;
+        };
+        inputLabel: {
+            attribute: string;
+            type: StringConstructor;
+        };
+        placeholder: {
+            type: StringConstructor;
+        };
+        maxlength: {
+            type: StringConstructor;
+        };
+        previousLabel: {
+            attribute: string;
+            type: StringConstructor;
+        };
+        nextLabel: {
+            attribute: string;
+            type: StringConstructor;
+        };
+        closeLabel: {
+            attribute: string;
+            type: StringConstructor;
+        };
+        value: {
+            attribute: boolean;
+        };
+        status: {
+            attribute: boolean;
+        };
+        statusTitle: {
+            attribute: boolean;
+        };
+    };
+    open: boolean;
+    disabled: boolean;
+    navigationDisabled: boolean;
+    label: string | null;
+    inputLabel: string | null;
+    placeholder: string | null;
+    maxlength: string | null;
+    previousLabel: string | null;
+    nextLabel: string | null;
+    closeLabel: string | null;
+    value: string;
+    status: string;
+    statusTitle: string;
+    constructor();
+    private get input();
+    /** Open, focus the field and select its query. */
+    show(): void;
+    /** Close and emit `office-find-close`. */
+    close(): void;
+    private step;
+    private onInput;
+    private onKey;
+    protected render(): import("lit").TemplateResult<1>;
+}
+export declare const defineFindBar: import("../registry.js").Definer;

package/dist/chrome/print-preview.d.ts

@@ -0,0 +1,39 @@
+import { type PropertyValues } from 'lit';
+import { OfficeElement } from '../base.js';
+export type OfficePrintPreviewPageEvent = CustomEvent<{
+    index: number;
+}>;
+/**
+ * `<office-ui-print-preview>`: the Print page's paper preview with page navigation. Set `pages`
+ * to rendered nodes (for example the SVG of each page); the element shows a deep clone of the
+ * current one with `tabindex` and inline `style` removed, so the preview is inert and never
+ * parses markup. `index` selects the page; the arrows emit `office-print-preview-page`.
+ * Attributes: `label` (default "Print preview"), `empty-label`.
+ */
+export declare class OfficeUiPrintPreview extends OfficeElement {
+    static styles: import("lit").CSSResult[];
+    static properties: {
+        label: {
+            type: StringConstructor;
+        };
+        emptyLabel: {
+            attribute: string;
+            type: StringConstructor;
+        };
+    };
+    label: string | null;
+    emptyLabel: string | null;
+    private list;
+    private current;
+    private clone;
+    constructor();
+    get pages(): readonly Node[];
+    set pages(value: readonly Node[]);
+    get index(): number;
+    set index(value: number);
+    private go;
+    /** The shown page is an inert copy: no tabindex, no inline style. */
+    protected willUpdate(changed: PropertyValues<this>): void;
+    protected render(): import("lit").TemplateResult<1>;
+}
+export declare const definePrintPreview: import("../registry.js").Definer;

package/dist/chrome/ruler.d.ts

@@ -0,0 +1,43 @@
+import { OfficeElement } from '../base.js';
+/** Tick subdivisions per unit for a given unit length in CSS pixels, finer as it grows. */
+export declare function rulerDivisions(unitPixels: number): number;
+/**
+ * `<office-ui-ruler>`: a decorative Office ruler (inches by default). The product positions it
+ * and says where zero is: `origin` is the CSS-pixel offset of zero from the ruler's start edge,
+ * `scale` the CSS pixels per unit (96 at 100% for inches). `orientation="vertical"` draws a
+ * side ruler; `direction="reverse"` makes values grow toward the start edge, as Visio's
+ * vertical ruler grows upward from the page bottom. Hidden from assistive technology.
+ */
+export declare class OfficeUiRuler extends OfficeElement {
+    static styles: import("lit").CSSResult[];
+    static properties: {
+        orientation: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+        origin: {
+            type: NumberConstructor;
+        };
+        scale: {
+            type: NumberConstructor;
+        };
+        direction: {
+            type: StringConstructor;
+        };
+    };
+    orientation: string;
+    origin: number;
+    scale: number;
+    direction: string;
+    private frame;
+    private observer;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private schedule;
+    protected willUpdate(): void;
+    protected updated(): void;
+    private draw;
+    protected render(): import("lit").TemplateResult<1>;
+}
+export declare const defineRuler: import("../registry.js").Definer;