From 02037fcb89a92516821223b02860ceccb924aa54 Mon Sep 17 00:00:00 2001 From: Markus Date: Tue, 17 Nov 2026 22:04:57 +0100 Subject: [PATCH] fix: add theme color fallbacks and compatibility notes --- docs/api.md | 10 ++++++++-- docs/development.md | 23 +++++++++++++++++++++++ docs/theming.md | 3 +++ src/react/styles.css | 27 +++++++++++++++++---------- test/theme.test.ts | 31 +++++++++++++++++++++++++++++++ 5 files changed, 82 insertions(+), 12 deletions(-) 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,