Documents the host asset pipeline and theming - #84
Merged
Conversation
Exercises the ADR-0009 embedding story end to end in a throwaway Phoenix-shaped host: the hex tarball this branch builds, unpacked to deps/, pulled in as "statifier_ui": "file:../deps/statifier_ui/assets", bundled by the host's own esbuild, and served with the components' real rendered markup. The hook attaches and the completion popup opens over it, which is the first time this package's JavaScript has been run outside a test. Three things the guide could not say before: - how the JavaScript reaches a host's bundler, what the tarball ships, and what a Node-free host still gets - what a stylesheet can reach. No component reads a CSS custom property, a data-theme, or a prefers-color-scheme, so the class and data-attribute contract is the whole theming surface; every class the package renders or the hook builds is now listed, including the popup selectors no template renders - the fallback contract: a host renders its own surfaces off trace wire format v1 and is never locked into the shipped components, with the two obligations that come with doing so Also corrects a claim the guide made about shipping no JavaScript, true until assets/ landed, and records that the diagram's Mermaid classDef carries literal colours no host stylesheet can reach. Refs: sui-191
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the ADR-0009 embedding story's verification gap: until now nothing had
compiled this package's JavaScript in a bundler, and the guide described a
theming surface nobody had styled against.
What was exercised
A throwaway host, removed after the run. Nothing outside this repo was written.
mix hex.build --unpackfrom this branch. The tarball does shipassets/package.json,assets/js/index.js,assets/js/expression_input.js<host>/deps/statifier_ui, and the host'sown
assets/package.jsondeclaring"statifier_ui": "file:../deps/statifier_ui/assets".npm installlinkednode_modules/statifier_ui -> ../../deps/statifier_ui/assets.../deps/statifier_ui/assets/js/index.jsand../deps/statifier_ui/assets/js/expression_input.js; the output ispriv/static/assets/app.js, 6.6kb.rendered markup -
ops_view/1andexpression_input/1rendered throughPhoenix.LiveViewTest, not hand-typed HTML - plus a host stylesheet writtenonly against the documented classes. The hook mounted, stamped
data-hook="attached", and built the completion popup, which the hoststylesheet then themed. First time this package's JavaScript has run outside
a test.
What the guide gained
tarball ships, that
npm installlinks rather than copies, and what aNode-free host still gets (working, unenhanced markup - every component has a
no-JavaScript affordance).
property, a
var(), adata-theme, or aprefers-color-scheme. That is thecontract, not a gap in it - the host owns the palette outright. All 38 classes
lib/andassets/render or build are now enumerated, including the popupselectors the hook creates at runtime that appear in no template.
wire format v1 at three levels - recompose the panes, keep the read model and
drop the markup, or take the messages - and is never locked into the shipped
components. The two obligations that travel with the third level (never
present a partial stream as whole, never present a carried configuration as a
measured one) are stated, because they are properties of the data rather than
of these components.
Corrections
pane. True until
assets/landed; now scoped to the Mermaid client.StatifierUI.Diagram'sclassDef activebakes literal Mermaid colours intothe diagram source, so the active-configuration highlight is unreachable from
a host stylesheet and stays light under a dark theme. Recorded as a known gap
rather than fixed - it is a
lib/change and outside this bead.Notes
Docs only. No path under
lib/,test/,config/,mix.exs,mix.lock,assets/, ordocs/wire-format.mdchanged, so the local gate carve-out appliesand no
mix qualityran; CI replays the full gate on this request. No changelogfragment: documentation is on
changelog.d/README.md's do-not-write list.Rebased onto
mainafter sui-pb2's trace-capture landed; no conflict, and theclass enumeration re-verified against
grepon the rebased HEAD.