diff --git a/docs/api.md b/docs/api.md
index 44b5ba6..99b529c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -135,13 +135,19 @@ The views style themselves from design tokens on their root: `useThemeRoot(theme
Every icon the viewer draws, toolbars, menus, zoom, outline, Present and the add-sheet tab included, has a name (`IconName`, all of them in `ICON_NAMES`). `icons` replaces any of them, either as a map or as a resolver that is called for every icon:
```tsx
-import { DocViewer, type IconName } from '@p10node/office-engine'
+import { DocViewer, type IconName, type Icons } from '@p10node/office-engine'
- , redo: }} />
+// Define outside the host component so the map keeps its identity across renders.
+const icons: Icons = { undo: , redo: }
+
+
```
A name the map leaves out, or a resolver returning `undefined` / `null`, keeps the built-in icon, so a set can cover just part of the names. Your icon is rendered inside `` whose font-size is the icon's size in pixels: draw it at `1em` (a bare `` child is sized to `1em` for you) and with `currentColor`, so it follows the theme. The resolver also gets `{ size }` in pixels.
+The names exported in `ICON_NAMES` are stable public keys, including names originally used only inside the viewer.
+New names may be added; existing keys must not be renamed as an internal refactor.
+
With [Lucide](https://lucide.dev) (`lucide-react`):
```tsx
diff --git a/docs/development.md b/docs/development.md
index f043ead..9faf2fc 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -70,6 +70,29 @@ One-time setup: **Settings → Pages → Source: GitHub Actions**. Build locally
## Release
+### Pending compatibility notes: themes and icons
+
+Carry these notes into the next release's versioned notes when its version is chosen; leave already released notes unchanged.
+
+- `Theme` now means `ThemeMode | ThemeOptions`. Hosts that need only the mode union (`'light' | 'dark' | 'auto'`)
+ should use `ThemeMode` instead of `Theme` for their own state, parameters and records.
+- `FileMenuItem.icon` now accepts `IconName` rather than any string. Annotate variables holding icon names as
+ `IconName` to prevent widening to `string`; keep using the existing icon rendering API.
+- `ICON_NAMES` exposes the supported icon names as stable public keys. New keys may be added; existing keys must
+ not be renamed as an internal cleanup.
+- CSS declarations using `color-mix()` have token-based fallbacks for visible selection, hover and connection states.
+ This does not imply full support for older browsers.
+
+```ts
+import type { FileMenuItem, IconName, ThemeMode } from '@p10node/office-engine'
+
+const mode: ThemeMode = 'auto'
+const icon: IconName = 'save'
+const item: FileMenuItem = { label: 'Save a copy', icon, onClick: saveCopy }
+```
+
+### Release process
+
CI (`.github/workflows/ci.yml`) runs typecheck, tests, the library and SDK package builds and `npm pack --dry-run` of each package, and the browser tests, on every push to `main` and every PR.
To release, push a branch named after the version:
diff --git a/docs/theming.md b/docs/theming.md
index 648b0ed..ef89f4b 100644
--- a/docs/theming.md
+++ b/docs/theming.md
@@ -25,6 +25,9 @@ value of that mode. Names are camelCase (`accentHover` sets `--de-accent-hover`)
point at the host's own variables: `{ accent: 'var(--brand-500)' }`. `createTheme()` types a theme object written apart
from the prop, and `THEME_TOKENS` lists every token.
+Treat token values as trusted application configuration: they are passed through as CSS without validation. Validate
+externally supplied values before passing them to the viewer, including when rendering on the server (SSR).
+
`mount()` takes the same `theme` option; `` takes a mode.
## Plain CSS
diff --git a/src/react/styles.css b/src/react/styles.css
index 988dd4a..edbc889 100644
--- a/src/react/styles.css
+++ b/src/react/styles.css
@@ -97,7 +97,7 @@
/* source editor (Markdown, HTML, diagrams) */
--de-src-bg: #ffffff;
--de-src-gutter: #f6f7f8;
- --de-src-sel: color-mix(in srgb, var(--de-accent) 25%, transparent);
+ --de-src-sel: var(--de-accent-soft);
--de-src-font: ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace;
--de-src-comment: #6a737d;
--de-src-keyword: #8e3bc7;
@@ -178,7 +178,6 @@
--de-cm-quote: #fdd663;
--de-src-bg: #1b1d20;
--de-src-gutter: #202327;
- --de-src-sel: color-mix(in srgb, var(--de-accent) 35%, transparent);
--de-src-comment: #8b949e;
--de-src-keyword: #d2a8ff;
--de-src-string: #7ee787;
@@ -191,6 +190,12 @@
color-scheme: dark;
}
+/* Custom properties accept unsupported functions as raw tokens, so gate the mixed selection colors. */
+@supports (background: color-mix(in srgb, red, transparent)) {
+ .de-root { --de-src-sel: color-mix(in srgb, var(--de-accent) 25%, transparent); }
+ .de-root.de-dark { --de-src-sel: color-mix(in srgb, var(--de-accent) 35%, transparent); }
+}
+
/* ---------------------------------------------------------------- chrome */
.de-bar {
display: flex;
@@ -391,8 +396,8 @@
.de-tbl-wrap { position: relative; }
.de-tbl-wrap > .de-tbl { margin: 0 !important; }
.de-col-resize { position: absolute; top: 0; bottom: 0; width: 6px; cursor: col-resize; z-index: 2; touch-action: none; }
-.de-col-resize:hover { background: color-mix(in srgb, var(--de-accent) 35%, transparent); }
-.de-tbl td.de-cell-sel { box-shadow: inset 0 0 0 9999px color-mix(in srgb, var(--de-accent) 16%, transparent); }
+.de-col-resize:hover { background: var(--de-accent-soft); background: color-mix(in srgb, var(--de-accent) 35%, transparent); }
+.de-tbl td.de-cell-sel { box-shadow: inset 0 0 0 9999px var(--de-accent-soft); box-shadow: inset 0 0 0 9999px color-mix(in srgb, var(--de-accent) 16%, transparent); }
.de-tbl td {
vertical-align: top;
overflow-wrap: break-word;
@@ -476,7 +481,7 @@
.de-xl-pic { position: absolute; z-index: 2; object-fit: fill; pointer-events: none; user-select: none; }
.de-xl-drawing {
position: absolute; z-index: 2; box-sizing: border-box; display: flex; flex-direction: column; align-items: center; justify-content: center;
- gap: 3px; padding: 6px; overflow: hidden; border: 1px dashed var(--de-border); border-radius: 4px; background: color-mix(in srgb, var(--de-chrome) 94%, transparent);
+ gap: 3px; padding: 6px; overflow: hidden; border: 1px dashed var(--de-border); border-radius: 4px; background: var(--de-chrome); background: color-mix(in srgb, var(--de-chrome) 94%, transparent);
color: var(--de-muted); font: 12px/1.3 system-ui, sans-serif; text-align: center; pointer-events: none;
}
.de-xl-drawing svg { color: var(--de-accent); }
@@ -924,7 +929,9 @@
::highlight(de-cm-draft) { background-color: var(--de-cm-on); }
.de-range {
position: absolute;
+ background: var(--de-accent-soft);
background: color-mix(in srgb, var(--de-accent) 10%, transparent);
+ border: 1px solid var(--de-accent);
border: 1px solid color-mix(in srgb, var(--de-accent) 60%, transparent);
pointer-events: none;
z-index: 2;
@@ -947,7 +954,7 @@
.de-fx-input:focus { background: var(--de-input-bg); box-shadow: inset 0 -2px 0 var(--de-accent); }
.de-tb-hint { margin-left: 8px; color: var(--de-muted); font-size: 12px; }
.de-slide-editable [data-sid] { cursor: text; }
-.de-slide-editable [data-sid]:hover { outline: 1px dashed color-mix(in srgb, var(--de-accent) 60%, transparent); }
+.de-slide-editable [data-sid]:hover { outline: 1px dashed var(--de-accent); outline: 1px dashed color-mix(in srgb, var(--de-accent) 60%, transparent); }
.de-txt-edit { outline: 2px solid var(--de-accent); outline-offset: 0; caret-color: var(--de-page-ink); cursor: text; z-index: 2; }
.de-gridpick { display: grid; grid-template-columns: repeat(8, 16px); gap: 3px; }
.de-gridpick button { width: 16px; height: 16px; padding: 0; border: 1px solid var(--de-border); border-radius: 2px; background: var(--de-pop); cursor: pointer; }
@@ -986,7 +993,7 @@
}
.de-grip-c { position: absolute; top: 0; width: 6px; cursor: col-resize; z-index: 3; }
.de-grip-r { position: absolute; left: 0; height: 6px; cursor: row-resize; z-index: 3; }
-.de-grip-c:hover, .de-grip-r:hover { background: color-mix(in srgb, var(--de-accent) 35%, transparent); }
+.de-grip-c:hover, .de-grip-r:hover { background: var(--de-accent-soft); background: color-mix(in srgb, var(--de-accent) 35%, transparent); }
.de-ctx {
position: fixed;
z-index: 50;
@@ -1034,7 +1041,7 @@
.de-cell-hl { z-index: 4; pointer-events: none; color: var(--de-sheet-ink); overflow: hidden; overflow-wrap: break-word; }
.de-cell-edit { overflow-wrap: break-word; }
.de-cell-edit-fx { background: transparent; color: transparent; caret-color: var(--de-sheet-ink); box-shadow: none; }
-.de-cell-edit-fx::selection { color: transparent; background: color-mix(in srgb, var(--de-accent) 25%, transparent); }
+.de-cell-edit-fx::selection { color: transparent; background: var(--de-accent-soft); background: color-mix(in srgb, var(--de-accent) 25%, transparent); }
.de-fassist-at { position: absolute; z-index: 30; }
.de-fassist {
min-width: 240px;
@@ -1195,7 +1202,7 @@
}
.de-dialog input:focus, .de-dialog textarea:focus { border-color: var(--de-accent); box-shadow: inset 0 0 0 1px var(--de-accent); }
.de-hf-zone { position: absolute; left: 0; right: 0; z-index: 1; cursor: default; }
-.de-hf-zone:hover { background: color-mix(in srgb, var(--de-accent) 5%, transparent); }
+.de-hf-zone:hover { background: var(--de-accent-soft); background: color-mix(in srgb, var(--de-accent) 5%, transparent); }
.de-hfd { width: 460px; }
.de-hfd textarea { min-height: 70px; }
.de-hfd-tabs { display: flex; gap: 4px; flex-wrap: wrap; }
@@ -1258,7 +1265,7 @@
.de-collab { display: inline-flex; align-items: center; gap: 8px; flex: none; }
.de-collab-status { display: inline-flex; align-items: center; gap: 6px; height: 24px; padding: 0 9px; border-radius: var(--de-radius-xl); font-size: 12px; color: var(--de-muted); background: var(--de-head); white-space: nowrap; }
.de-collab-dot { width: 7px; height: 7px; border-radius: 50%; background: var(--de-status-idle); flex: none; }
-.de-collab-live .de-collab-dot { background: var(--de-status-live); box-shadow: 0 0 0 3px color-mix(in srgb, var(--de-status-live) 18%, transparent); }
+.de-collab-live .de-collab-dot { background: var(--de-status-live); box-shadow: 0 0 0 3px var(--de-status-live); box-shadow: 0 0 0 3px color-mix(in srgb, var(--de-status-live) 18%, transparent); }
.de-collab-live { color: var(--de-ok); }
.de-collab-connecting .de-collab-dot,
.de-collab-syncing .de-collab-dot { background: var(--de-status-busy); animation: de-collab-pulse 1s ease-in-out infinite alternate; }
diff --git a/test/theme.test.ts b/test/theme.test.ts
index 86482ad..86c7298 100644
--- a/test/theme.test.ts
+++ b/test/theme.test.ts
@@ -36,6 +36,37 @@ describe('theme tokens', () => {
})
})
+describe('color-mix compatibility', () => {
+ test('mixed source selection tokens are gated by feature support', () => {
+ const gated = css.match(/@supports \(background: color-mix\(in srgb, red, transparent\)\) \{\n([\s\S]*?)\n\}/)
+ expect(gated).not.toBeNull()
+ expect(gated![1]).toContain('.de-root { --de-src-sel: color-mix(in srgb, var(--de-accent) 25%, transparent); }')
+ expect(gated![1]).toContain('.de-root.de-dark { --de-src-sel: color-mix(in srgb, var(--de-accent) 35%, transparent); }')
+ const withoutSupport = css.replace(gated![0], '')
+ // Duplicate custom properties alone would still accept the unsupported function as raw tokens.
+ expect(withoutSupport).not.toMatch(/--de-[\w-]+:\s*color-mix\(/)
+ expect(block('.de-root')).toContain('--de-src-sel: var(--de-accent-soft);')
+ expect(css).toContain('.de-src-input::selection { background: var(--de-src-sel); }')
+ })
+
+ test('each mixed property has an immediately preceding non-mixed fallback', () => {
+ let checked = 0
+ for (const body of css.split(/[{}]/)) {
+ const declarations = body.split(';').map((s) => s.trim()).filter(Boolean)
+ for (const [i, declaration] of declarations.entries()) {
+ const mixed = declaration.match(/^([a-z-]+):\s*.*color-mix\(/)
+ if (!mixed || mixed[1].startsWith('--')) continue
+ const fallback = declarations[i - 1] ?? ''
+ expect(fallback.startsWith(`${mixed[1]}:`)).toBe(true)
+ expect(fallback).not.toContain('color-mix(')
+ expect(fallback).toContain('var(--de-')
+ checked++
+ }
+ }
+ expect(checked).toBeGreaterThan(0)
+ })
+})
+
describe('themeStyle', () => {
const theme = {
mode: 'auto' as const,