Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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'

<DocViewer src={file} icons={{ undo: <MyUndo />, redo: <MyRedo /> }} />
// Define outside the host component so the map keeps its identity across renders.
const icons: Icons = { undo: <MyUndo />, redo: <MyRedo /> }

<DocViewer src={file} icons={icons} />
```

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 `<span class="de-icon">` whose font-size is the icon's size in pixels: draw it at `1em` (a bare `<svg>` 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
Expand Down
23 changes: 23 additions & 0 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
3 changes: 3 additions & 0 deletions docs/theming.md
Original file line number Diff line number Diff line change
Expand Up @@ -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; `<office-viewer theme="dark">` takes a mode.

## Plain CSS
Expand Down
27 changes: 17 additions & 10 deletions src/react/styles.css
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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); }
Expand Down Expand Up @@ -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;
Expand All @@ -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; }
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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; }
Expand Down Expand Up @@ -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; }
Expand Down
31 changes: 31 additions & 0 deletions test/theme.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading