feat(platform): ship a usable editor stylesheet

[henrique221]

Closes part of #516 (the packaging item).

The problem

Consumers copy stylesheets out of this repo by hand. The README says so, and it means every consumer re-copies on every visual change and has to serve the toolbar icon SVGs from its own web root, because editor.css referenced them by absolute URL.

What ships

Four stylesheets, built to dist/, one per thing you can turn off:

import "@eten-tech-foundation/platform-editor/styles.css";       // editor chrome, always
import "@eten-tech-foundation/platform-editor/context-menu.css"; // needed by everyone today
import "@eten-tech-foundation/platform-editor/toolbar.css";      // hasExternalUI: false
import "@eten-tech-foundation/platform-editor/nodes-menu.css";   // hasExternalUI: false + scrRef

The 15 toolbar icons are inlined as data URIs, so no asset copying is needed. styles.css, context-menu.css and nodes-menu.css reference no images at all.

Each one also has a root shim (platform-editor/styles.css resolving to <pkg>/styles.css) for resolvers that ignore the exports map, so those consumers reach all four rather than only the core one.

Scope, after review on #516 and #528

usj-nodes.css is not bundled. Platform generates it per project so it can respond to project stylesheets, custom.sty markers and the active view mode, and the copy in this repo is a placeholder for a formatted view. A fixed copy shipped in the package would be wrong for most consumers, so the README keeps documenting the copy for it.

editor.css is split before bundling, along the boundaries the file already labelled:

file	what	published as
editor/editor.css	core editor chrome	styles.css
editor/toolbar.css	built-in toolbar, hasExternalUI: false	toolbar.css
editor/context-menu.css	ContextMenuPlugin (see #225)	context-menu.css
shared/styles/nodes-menu.css	marker menu, hasExternalUI: false and scrRef	nodes-menu.css
editor/debug-tree-view.css	TreeView, debug: true only	nothing, source only

The marker menu started out inside the core bundle and moved out on Ira's review. Its only mount is UsjNodesMenuPlugin at Editor.tsx:927, gated on scrRef && !hasExternalUI, which is the toolbar's condition plus a scrRef requirement. It was the one optional thing left in core.

debug-tree-view.css gets no entry and no subpath on purpose. It carries two unscoped pre::-webkit-scrollbar rules that would have restyled every <pre> on a consumer's page the moment they imported styles.css, and debug is an experimental dev-only prop. It stays on the copy list.

There is no ./comments.css subpath. It would have pointed at the . entry's auto-generated dist/index.css, so the name did not describe the target, and <Marginal /> is deprecated and due for removal, so a public subpath would only buy a breaking removal later. Comment styles stay on the copy list.

Verification

• The split is rule-for-rule lossless. Splitting the marker menu out conserves the 35 rule blocks across styles.css and nodes-menu.css exactly, none added, none missing.
• Built styles.css is 2.46 kB, down from 3.63 kB; nodes-menu.css is 1.17 kB.
• All 15 url() in the built toolbar.css are data: URIs; zero external url() in any built stylesheet. That works because Vite resolves root-absolute CSS urls against config.root, and every icon is 258-720 B, under the 4096 B default assetsInlineLimit. There is a comment in toolbar.css saying so, because it looks like it should not work.
• The repo's own platform demo imports src/styles.css plus the optional files rather than re-enumerating them, so nx dev platform regresses the composition we publish. Its built stylesheet holds the same 760 rule blocks as before.
• npm pack --dry-run on a clean build is 78 files. All four exports subpaths resolve to files the build emits; the four empty CSS-entry JS chunks and their maps are negated out.
• lint, typecheck, test, build and format:check green across all affected projects. API report unchanged: this is CSS plus packaging, no public API change.

build.lib.entry stays a string on purpose: vite-plugin-dts derives its entry list from it, and an object there makes api-extractor fail on the export-less CSS entries. There is a comment at the call site.

One change outside packages/platform: libs/shared now exports ./styles/*. The marker menu's stylesheet lives there, and the entry needs to reach it through the workspace alias the way the TS in this package does. shared exported only . and ./package.json, so shared/src/styles/nodes-menu.css failed to resolve, and a relative path out of the project is an @nx/enforce-module-boundaries error. shared is private: true, so nothing public widens.

Compatibility with the separate entry-point work in #552 was checked in a combined worktree, together with #541. All four public stylesheet imports exist and survive consumer bundling. #552 keeps asset basenames at the dist root; this is needed when its JavaScript modules are preserved. When combining the Vite configs, keep the JavaScript entries in lib.entry and include both JavaScript and CSS entries in rollupOptions.input. The CSS contents are unchanged by the filename adjustment.

---

This change is

Visual evidence

These static component-shaped fixtures use the four CSS files emitted by a fresh build of head 777cf8ed. The fixture content is illustrative; the styles, optional boundaries, icon encoding and file sizes come from the exact PR build.

Editor chrome and built-in toolbar

Optional context and marker menus

[codesandbox]

Review or Edit in CodeSandbox

Open the branch in Web Editor • VS Code • Insiders

Open Preview

[henrique221]

Reworked to match your review on #516.

usj-nodes.css is out of the bundle, and editor.css is split along the boundaries it already labelled: core, built-in toolbar (hasExternalUI: false), ContextMenuPlugin, and the debug-only TreeView. Only the core plus the marker menu land in styles.css.

The one judgement call is in the PR description: I kept the toolbar and context menu shipping as their own entries rather than dropping them, since hasExternalUI defaults to false so most consumers still need them. Folding them back into the bundle is a one-line change if you prefer that.

The split is rule-for-rule lossless (88 selectors before and after) and the repo's platform demo imports the new files, so nx dev platform is unaffected.

[irahopkinson]

Looks good to me. I'll drop an AI review next.

@irahopkinson reviewed 15 files and all commit messages, and made 1 comment.
Reviewable status: complete! all files reviewed, all discussions resolved.

[irahopkinson]

Thanks for this — the packaging works, and I've verified the parts that are hard to eyeball. Building the branch: nx build, lint, typecheck and prettier --check are green; npm pack --dry-run gives the intended 59-file set (root styles.css and assets/images/icons/LICENSE.md in, src/{styles,toolbar,context-menu}.{ts,css} out — the files negations behave); all four exports subpaths resolve to files the build actually emits.

Your claims check out, with one nit:

• Split is lossless — confirmed independently: 85 rule blocks before and after, zero missing, zero added. The only reordering is the verse-selected / verse-delete-armed block moving from position 81 to 21, and no selector appears in two of the split files, so the cascade is unaffected. Thank you for keeping the post-560 verse-delete-armed rules in editor.css — that was the bit I flagged.
• Icons inline — 15/15 url() in built toolbar.css are data: URIs, zero external url() in any built stylesheet. For the record this works because Vite resolves root-absolute CSS urls against config.root = packages/platform, and every SVG is 266–956 B, under the 4096 B inline limit. Worth a comment in toolbar.css, because it looks like it shouldn't work.
• dist/index.css unchanged — I rebuilt with main's vite.config.mts and compared: 11869 bytes, cmp identical. The cssCodeSplit reasoning holds, and dist/index.js has no injected CSS import.
• "88 selectors before, 88 after" — this figure doesn't reproduce. I count 85 rule blocks, or 107 comma-separated selectors, both conserved exactly. The conclusion is right and I've verified it, but the number matches neither metric, so it can't serve as the audit trail it's offered as.

I have not verified "API report unchanged" — I confirmed no new .d.ts is emitted, but didn't run nx extract-api.

Inline comments below. Most are small. Four are decisions rather than defects and I've marked them as questions — the nodes-menu.css one (on src/styles.css) is the one I'd most like your view on.

Two more that don't anchor to a changed line:

src/editor/editor.css:1 — orphaned stylelint directive. /* stylelint-disable selector-no-qualifying-type */ stayed at the top of editor.css, but every qualifying-type selector moved out: button.toolbar-item, i.undo, .icon.pi, button.item.dropdown-item-active → toolbar.css; .typeahead-popover li.selected → context-menu.css. Dead where it sits, missing where it's needed. Nothing breaks today (we have no stylelint config), but please move it to the two files that now need it.

Adding a stylesheet takes six edits. demos/platform/src/styles.css, src/<n>.css, src/<n>.ts, vite.config.mts input, exports, files. Tolerable at four entries, not at eight. Not something to fix in this PR, but if the shims go (see the src/toolbar.css comment) it drops to four.

Leaving this as a comment rather than a change request — most of it is prose and packaging polish, and the substantive items are questions for you.

[henrique221]

The two items in your review body that had no line to anchor to:

Orphaned stylelint directive. Moved in c528e98. editor.css has no qualifying-type selectors left at all now, and the directive sits on toolbar.css and context-menu.css, which do.

Six edits per stylesheet. This did not drop to four, and I want to flag that rather than let you find it. Dropping the src/*.css shims took one edit off, but adding the three missing root shims put one back, so it is still six: demos/platform/src/styles.css, src/<n>.ts, the vite.config.mts input, exports, files, and the root <n>.css. Agreed it is not this PR's problem, but the arithmetic did not work out the way we both expected.

On your nodes-menu.css question I had no counter-argument, so it moved to its own entry. That changed the shape of what ships, so the description is updated. Numbers I re-derived rather than reused: built styles.css 3.63 kB to 2.46 kB, nodes-menu.css 1.17 kB, 35 rule blocks conserved across the two; toolbar and context-menu output byte-identical after the shims went; the demo's built stylesheet holds the same 760 rule blocks; npm pack --dry-run on a clean build is 78 files with the eight empty JS chunks gone. And you were right that my "88 selectors" figure did not reproduce, sorry, I have dropped it.

[irahopkinson]

Re-verified the whole thing at 777cf8e in a clean worktree — fresh install, fresh build, npm pack --dry-run, lint, typecheck and prettier. Since the branch has merged main in the meantime I diffed only your four commits (c8d54f00..9b81a778) so the review surface stayed the 21 files you actually touched.

Everything I could re-derive holds:

claim	result
nodes-menu.css its own entry	dist/nodes-menu.css 1168 B — your 1.17 kB exact
built styles.css shrinks	2488 B (you said 2.46 kB; mine reads 2.49 — main's merge touched editor.css after you measured)
toolbar / context-menu unchanged	11804 B and 1336 B, identical to the byte
icons still inline	15/15 data: URIs in toolbar.css; zero external url() in any built stylesheet
the 15 icons are 258–720 B	exact
empty JS chunks gone	zero in the tarball
exports subpaths	all four resolve to emitted files
lint / typecheck / prettier	green (one no-loop-func warning in verse-block.utils.ts, from main, not from you)

Two figures differ from yours and neither is a problem: 79 packed files rather than 78, and 34 conserved rule blocks rather than 35. Both are explained in the threads — the first is the main merge, the second is a counting convention around @media.

Three answers you were waiting on, all in the threads: keep src/styles.css (it has two consumers now, unlike the shims); you were right about the licensing premise and I was wrong — the artwork already ships on main via dist/index.css, so this fixes a pre-existing gap rather than opening one; and thanks for flagging the six-edits arithmetic yourself rather than letting me find it — you are right that adding the three root shims put back what dropping the src/*.css shims took off.

One nit inline below, and that is the last thing from me. I will take a final pass in Reviewable.

[irahopkinson]

@irahopkinson+AI resolved 1 discussion.
Reviewable status: 0 of 21 files reviewed, 13 unresolved discussions (waiting on henrique221 and irahopkinson).