Skip to content

Commit 9eb07fa

Browse files
koculukoculu
committed
Improve browser entry points docs.
1 parent 8e04513 commit 9eb07fa

9 files changed

Lines changed: 466 additions & 130 deletions

File tree

‎frontend/docs/componentGuide.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,16 @@ export function registerComponentGuideStyles() {
5959
const root = styleBuilder.get(theme)
6060
const neutral = palette.semanticTone.neutral
6161
const accent = palette.semanticTone.accent
62+
root.select('.runtime-code').css({
63+
whiteSpace: 'pre-wrap',
64+
overflowWrap: 'anywhere',
65+
fontSize: '0.75rem',
66+
padding: '1rem',
67+
})
68+
root.select('.runtime-code code').css({ whiteSpace: 'inherit' })
69+
root
70+
.select('app[data-review-counter]')
71+
.css({ display: 'block', minWidth: '0' })
6272
root.select('.component-guide-card > .badge').css({ alignSelf: 'start' })
6373
root.select('.layout-demo-track').css({
6474
minHeight: '7rem',

‎frontend/purestack.studio/components/runtime/index.mdx‎

Lines changed: 39 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,45 @@ nav:
1313

1414
# Browser entry points
1515

16-
Add page-specific browser behavior with colocated TypeScript entry points and independent Regor apps.
16+
<p class="component-directory-lead">Small behavior. Clear ownership. A page that stays understandable.</p>
1717

18-
[All components](/components/)
18+
Choose an independent component app or enhance the HTML already on the page. Both entry points resolve colocated TypeScript through the SSG; your browser code decides what happens next.
19+
20+
## Choose the boundary
21+
22+
<div class="component-guide-grid">
23+
<article class="component-guide-card"><div class="component-guide-card__preview"><Flex direction="column" align="start"><Badge tone="feature">Independent app</Badge><strong>Mount + template + refs</strong><span>Each instance owns its review state.</span></Flex></div><h3>RegorApp</h3><Badge tone="neutral">Component behavior</Badge><p>Register the parts you need, create fresh reactive state, and mount a focused UI. Try independent reviews, shared module loading, and explicit source ownership.</p><a href="/components/runtime/regor-app/">Explore RegorApp ↗</a></article>
24+
<article class="component-guide-card"><div class="component-guide-card__preview"><Flex direction="column" align="start"><Badge tone="info">Existing HTML</Badge><strong>Find a region + bind an event</strong><span>A scoped script adds a reading-time estimate.</span></Flex></div><h3>PageScript</h3><Badge tone="neutral">DOM enhancement</Badge><p>Keep the server-rendered content and add page-specific behavior. Inspect emitted tags, placement, source paths, and every loading or metadata option.</p><a href="/components/runtime/page-script/">Explore PageScript ↗</a></article>
25+
</div>
26+
27+
## Two working approaches
28+
29+
<ComponentExample label="An app beside a DOM enhancement" caption="Each example loads a colocated entry using its guide as the source owner. Neither entry-point component has appearance variants.">
30+
<Grid columns="1" columnsLg="2"><RegorApp id="runtime-directory-review" data-review-counter="Page readiness" src="./playground.ts" :sourceRelPath="'components/runtime/regor-app/regor-app.mdx'"/><Panel tone="info" bodyClass="p-3"><section data-reading-example aria-label="Directory reading-time enhancement"><SectionHeader title="Enhance the paragraph" subtitle="Existing content gains one focused interaction." titleTag="h3"/><p data-reading-content>Keep content readable before JavaScript runs. A scoped entry point can add calculations, event handlers, and small improvements to an existing document. Choose a separate component app when reactive state and reusable templates make the feature easier to understand.</p><label for="runtime-directory-rate">Reading speed · words per minute</label><input id="runtime-directory-rate" data-reading-rate type="range" min="10" max="300" step="10" value="200" class="w-full"/><output data-reading-result aria-live="polite">Reading-time estimate appears when the module runs.</output></section></Panel></Grid><PageScript src="./reading-time.ts" :sourceRelPath="'components/runtime/page-script/page-script.mdx'"/>
31+
</ComponentExample>
1932

20-
## Component guides
33+
## Compare responsibilities
2134

22-
<Grid columns="1" columnsSm="2" columnsXl="3">
23-
<Panel tone="neutral" bodyClass="p-3"><h3 class="mt-0">Regor<wbr/>App</h3><p>Mount an independent browser app from a TypeScript file colocated with its MDX page.</p><BtnLink href="/components/runtime/regor-app/" tone="accent" variant="link">Explore Regor<wbr/>App</BtnLink></Panel>
24-
<Panel tone="neutral" bodyClass="p-3"><h3 class="mt-0">Page<wbr/>Script</h3><p>Include a page-specific browser entry point with SSG path resolution, bundling and native script attributes.</p><BtnLink href="/components/runtime/page-script/" tone="accent" variant="link">Explore Page<wbr/>Script</BtnLink></Panel>
25-
</Grid>
35+
| Need | RegorApp | PageScript |
36+
| --- | --- | --- |
37+
| Visible root | An app mount element | A script element |
38+
| UI ownership | Browser template and registered components | Existing HTML, selected by your script |
39+
| State | Refs and computed values in each createApp context | Your chosen DOM or JavaScript state |
40+
| Initialization | Entry point explicitly calls createApp | Entry point runs its enhancement code |
41+
| Multiple instances | Create one app with fresh state per mount | Scope queries and listeners to each region |
42+
| Source resolution | src and optional sourceRelPath | src and optional sourceRelPath |
43+
| Script placement and metadata | Uses the internal default PageScript | teleport, type, loading flags, and native metadata |
44+
| Appearance | Components inside the app | Enhanced HTML and its components |
45+
46+
## From source to page
47+
48+
<ComponentExample label="Resolve → bundle → emit → initialize" caption="A repeated module URL executes once. Entry points that serve multiple mounts must initialize every matching instance.">
49+
<div class="component-appearance-grid">
50+
<div class="component-appearance-cell"><code>Resolve</code><strong>Find the source owner</strong><p class="m-0">Relative src uses the MDX directory. sourceRelPath changes that owner.</p></div>
51+
<div class="component-appearance-cell"><code>Bundle</code><strong>Record the local entry</strong><p class="m-0">The SSG bundles local TypeScript into a browser asset. External URLs stay external.</p></div>
52+
<div class="component-appearance-cell"><code>Emit</code><strong>Include the script</strong><p class="m-0">A native module tag points to the emitted asset; RegorApp also supplies an app mount.</p></div>
53+
<div class="component-appearance-cell"><code>Initialize</code><strong>Own the behavior</strong><p class="m-0">Register and mount component apps, or attach scoped listeners to the rendered document.</p></div>
54+
</div>
55+
</ComponentExample>
56+
57+
[All components](/components/)

‎frontend/purestack.studio/components/runtime/page-script/options-sample.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
// A local bundle used in inert application/json tags to inspect native metadata.
2+
export const example = 'Script attributes are forwarded without execution.'

0 commit comments

Comments
 (0)