@oddkin/workbench 1.0.0-beta.0 → 1.0.0-beta.1

package/dist/panels/component-detail.js

@@ -8,9 +8,11 @@ import { OddkinElement, prop } from '@oddkin/core/element';
 import { signal, untracked } from '@oddkin/core/reactive';
 import { createScope } from '@oddkin/core/scope';
 import { html, nothing, repeat } from '@oddkin/core/template';
-import { createIsolatedPreview } from '../preview/frame.js';
-import { authoredValues, componentFacts, decodeShare, defaultWriteMode, encodeShare, initialState, intendedUse, pageCoverage, presets, usagePairs, MAX_SHARE_WIDTH, MIN_SHARE_WIDTH, SHARE_PARAM, sharePayload, snippet, } from './model.js';
+import { createIsolatedPreview, PreviewFrameError, } from '../preview/frame.js';
+import { isCustomPropertyName, } from '../protocol/index.js';
+import { authoredValues, componentFacts, decodeShare, defaultWriteMode, encodeShare, initialState, intendedUse, pageCoverage, presets, registrationOf, usagePairs, MAX_SHARE_WIDTH, MIN_SHARE_WIDTH, SHARE_PARAM, sharePayload, snippet, } from './model.js';
 import { contentStyles, panelHostStyles } from './styles.js';
+import { exampleStyles } from './example-styles.js';
 const LOG_LIMIT = 50;
 const WIDTHS = {
     narrow: 320,
@@ -40,11 +42,27 @@ const notDocumented = (key, subject) => {
 const bullets = (items) => html `<ul class="wb-list">
     ${items.map((item) => html `<li>${inline(item)}</li>`)}
   </ul>`;
-function covered(coverage) {
+/** The reference layout's links to its sections (Figma 19:874), by section id. */
+const PAGE_LINKS = [
+    ['overview', 'Overview'],
+    ['interactive-example', 'Controls'],
+    ['examples', 'Examples'],
+    ['behavior-and-accessibility', 'Accessibility'],
+];
+/** `'secondary'` reads as `secondary`; an empty literal stays as written. */
+const unquote = (value) => (/^(['"`]).+\1$/.test(value) ? value.slice(1, -1) : value);
+/** A row's name cell: the name, and its description or "Not documented". */
+const named = (name, description) => html `<th scope="row" data-label="Name">
+    <code>${name}</code>
+    <small
+      >${description ? inline(description) : html `<span class="wb-not-documented">Not documented</span>`}</small
+    >
+  </th>`;
+function covered(coverage, quiet) {
     const byId = new Map(coverage.map((item) => [item.id, item]));
     return (id, content) => {
         const item = byId.get(id);
-        if (!item)
+        if (!item || (quiet && item.state !== 'documented'))
             return nothing;
         return html `<div data-coverage=${id} data-state=${item.state}>
       ${item.state === 'documented'
@@ -70,8 +88,31 @@ export class ComponentDetailElement extends OddkinElement.with({
         attribute: false,
         description: 'URL of the preview frame document.',
     }),
+    layout: prop.enum(['workbench', 'reference'], {
+        default: 'workbench',
+        description: "'reference' is the documentation page (Figma 20:2190): links to the page's sections, no preview tools (presets, settings, example link, event log), and absent items left out instead of labelled.",
+    }),
+    examplePreview: prop.custom({
+        default: () => undefined,
+        coerce: (value) => value === undefined || typeof value === 'function'
+            ? {
+                ok: true,
+                value: value,
+            }
+            : { ok: false, reason: 'expected a function' },
+        description: 'Returns a live element for an example card (the example id, `example:<tag>/<name>`). Only a host that loads the library supplies one; the same example should get the same node.',
+    }),
+    sections: prop.custom({
+        default: () => null,
+        coerce: (value) => value === null || value === undefined
+            ? { ok: true, value: null }
+            : Array.isArray(value) && value.every((id) => typeof id === 'string')
+                ? { ok: true, value: Object.freeze([...value]) }
+                : { ok: false, reason: 'expected an array of section ids, or null' },
+        description: "The section ids to show, for a host's tabs (overview, interactive-example, api, examples, tokens, behavior-and-accessibility, guidance, source, known-limitations); null shows every section. The others stay rendered but hidden, so the example's preview and controls survive a switch, and the panel leaves out its own section links.",
+    }),
 }) {
-    static styles = [panelHostStyles, contentStyles];
+    static styles = [panelHostStyles, contentStyles, exampleStyles];
     #state = signal({
         preset: 'default',
         attributes: {},
@@ -87,6 +128,12 @@ export class ComponentDetailElement extends OddkinElement.with({
         alert: false,
     });
     #link = signal('');
+    /** The generated code is shown under the example. */
+    #code = signal(false);
+    /** The section the reference layout's links mark as current. */
+    #current = signal('');
+    /** The reference layout shows every example card, not the first four. */
+    #allExamples = signal(false);
     #hosts;
     #previews = [];
     #previewScope;
@@ -114,10 +161,41 @@ export class ComponentDetailElement extends OddkinElement.with({
             this.#key = '';
             this.#stop();
         });
+        let frame = 0;
+        scope.listen(this.ownerDocument, 'scroll', () => {
+            if (this.layout === 'reference' && !frame)
+                frame = requestAnimationFrame(() => {
+                    frame = 0;
+                    this.#spy();
+                });
+        }, { capture: true, passive: true });
+        scope.add(() => cancelAnimationFrame(frame));
+    }
+    /** The current section is the last linked one whose top has passed a third of the view. */
+    #spy() {
+        const view = this.ownerDocument.defaultView;
+        const page = this.ownerDocument.scrollingElement;
+        if (!view || !page)
+            return;
+        const linked = PAGE_LINKS.flatMap(([id]) => this.shadowRoot?.getElementById(id) ?? []);
+        const atEnd = page.scrollTop + view.innerHeight >= page.scrollHeight - 2;
+        let current = linked[0]?.id ?? '';
+        for (const section of linked)
+            if (atEnd || section.getBoundingClientRect().top <= view.innerHeight / 3)
+                current = section.id;
+        this.#current.value = current;
+    }
+    /** Scroll a section into view and move focus to its heading. */
+    #jump(event, id) {
+        event.preventDefault();
+        const section = this.shadowRoot?.getElementById(id);
+        section?.scrollIntoView({ block: 'start' });
+        section?.querySelector('h2')?.focus({ preventScroll: true });
+        this.#current.value = id;
     }
     /** Restart the preview only when the component, registration, or frame document changes. */
     #sync(page, frameUrl) {
-        const registration = page?.enrichment?.['registration'];
+        const registration = page && registrationOf(page);
         const key = page ? `${page.tag}\n${String(registration)}\n${frameUrl}` : '';
         if (key === this.#key)
             return;
@@ -192,6 +270,7 @@ export class ComponentDetailElement extends OddkinElement.with({
     #mountPayload(page, registration, index) {
         const state = this.#state.peek();
         const facts = componentFacts(page);
+        const fixture = presets(page).some((p) => p.name === state.preset && p.fixture);
         return {
             tag: page.tag,
             registration,
@@ -199,6 +278,8 @@ export class ComponentDetailElement extends OddkinElement.with({
             properties: state.properties,
             attributes: state.attributes,
             slots: state.slots,
+            styles: state.styles ?? {},
+            ...(fixture && page.exampleModule ? { fixture: page.exampleModule } : {}),
             events: facts.events.map((event) => event.name),
             sync: facts.syncPairs,
             settings: this.#frameSettings(index),
@@ -210,9 +291,9 @@ export class ComponentDetailElement extends OddkinElement.with({
         const page = this.page;
         if (!page || !this.isConnected)
             return;
-        const registration = page.enrichment?.['registration'];
+        const registration = registrationOf(page);
         // Without a registration entry the preview item itself says what is missing.
-        if (typeof registration !== 'string') {
+        if (registration === undefined) {
             if (!this.#status.peek().keep)
                 this.#status.value = { text: '', alert: false };
             return;
@@ -248,8 +329,8 @@ export class ComponentDetailElement extends OddkinElement.with({
         this.#mountAll(scope, page, registration);
     }
     #mountAll(scope, page, registration) {
-        const previews = [...this.#previews];
-        void Promise.all(previews.map((preview, i) => preview.ready.then(() => preview.request('mount', this.#mountPayload(page, registration, i))))).then(() => {
+        // Each preview handles requests in order, so changes made from now on follow this mount.
+        void Promise.all(this.#previews.map((preview, i) => preview.request('mount', this.#mountPayload(page, registration, i)))).then(() => {
             if (!scope.disposed && !this.#status.peek().alert && !this.#status.peek().keep)
                 this.#status.value = { text: '', alert: false };
         }, (error) => {
@@ -258,6 +339,10 @@ export class ComponentDetailElement extends OddkinElement.with({
         });
     }
     #fail(error) {
+        // A request for a frame that was replaced (Reset) or removed has nothing left to report.
+        if (error instanceof PreviewFrameError &&
+            (error.code === 'frame.generation.superseded' || error.code === 'frame.disposed'))
+            return;
         this.#status.value = { text: `Preview unavailable: ${message(error)}`, alert: true };
     }
     #onMessage(notification, index) {
@@ -274,6 +359,15 @@ export class ComponentDetailElement extends OddkinElement.with({
             };
             this.#log.value = [entry, ...this.#log.peek()].slice(0, LOG_LIMIT);
         }
+        else if (notification.kind === 'error' &&
+            isRecord(payload) &&
+            payload['phase'] === 'fixture') {
+            this.#status.value = {
+                text: `The example's setup did not run (${String(payload['message'])}), so the preview shows the element without it.`,
+                alert: false,
+                keep: true,
+            };
+        }
         else if (notification.kind === 'error' && isRecord(payload)) {
             this.#status.value = {
                 text: `Preview ${String(payload['phase'])} failed: ${String(payload['message'])}. Use Reset to start a fresh preview.`,
@@ -304,6 +398,18 @@ export class ComponentDetailElement extends OddkinElement.with({
             delete errors[id];
         this.#errors.value = errors;
     }
+    /** Why a typed value is not written (a number field's text that is not a number yet). */
+    #textProblem(number, mode, text) {
+        if (!number)
+            return undefined;
+        if (mode === 'attribute')
+            return text !== '' && !Number.isFinite(Number(text))
+                ? 'Not written: not a number.'
+                : undefined;
+        return text.trim() === '' || !Number.isFinite(Number(text))
+            ? 'Not written: enter a number, or use Unset.'
+            : undefined;
+    }
     #writeAttribute(row, value) {
         const name = row.attribute;
         const state = this.#state.peek();
@@ -340,12 +446,23 @@ export class ComponentDetailElement extends OddkinElement.with({
         this.#state.value = { ...state, slots: { ...state.slots, [name]: text } };
         this.#send('slot', { name, text });
     }
+    /** A CSS custom property on the element's style; `null` removes it. */
+    #writeStyle(name, value) {
+        const state = this.#state.peek();
+        const styles = { ...state.styles };
+        if (value === null)
+            delete styles[name];
+        else
+            styles[name] = value;
+        this.#state.value = { ...state, styles };
+        this.#send('set', { cssProperty: name, cssValue: value });
+    }
     /** Mount the current state again in the existing frames (a clean instance, same realm). */
     #remount(note) {
         const page = this.page;
-        const registration = page?.enrichment?.['registration'];
+        const registration = page && registrationOf(page);
         const scope = this.#previewScope;
-        if (!page || typeof registration !== 'string' || !scope)
+        if (!page || registration === undefined || !scope)
             return;
         this.#status.value = { text: note ?? '', alert: false, ...(note ? { keep: true } : {}) };
         this.#mountAll(scope, page, registration);
@@ -379,9 +496,9 @@ export class ComponentDetailElement extends OddkinElement.with({
     }
     #replace() {
         const page = this.page;
-        const registration = page?.enrichment?.['registration'];
+        const registration = page && registrationOf(page);
         const scope = this.#previewScope;
-        if (!page || typeof registration !== 'string' || !scope) {
+        if (!page || registration === undefined || !scope) {
             this.#restart();
             return Promise.resolve();
         }
@@ -442,6 +559,10 @@ export class ComponentDetailElement extends OddkinElement.with({
             return;
         clipboard.writeText(link).then(() => (this.#status.value = { text: 'Example link copied.', alert: false, keep: true }), () => undefined);
     }
+    #copyCode() {
+        const code = this.shadowRoot?.querySelector('.wb-snippet')?.textContent ?? '';
+        this.ownerDocument.defaultView?.navigator.clipboard?.writeText(code).then(() => (this.#status.value = { text: 'Code copied.', alert: false, keep: true }), () => undefined);
+    }
     // ---- Rendering ----
     render() {
         const page = this.page;
@@ -449,62 +570,73 @@ export class ComponentDetailElement extends OddkinElement.with({
         if (!page || !index)
             return html `<div class="wb-content"></div>`;
         const entry = index.registry.pages.find((p) => p.id === page.id);
-        const sections = (entry?.sections ?? []).filter((s) => s.visible);
+        const reference = this.layout === 'reference';
         const facts = componentFacts(page);
-        const at = covered(pageCoverage(page));
+        const coverage = pageCoverage(page);
+        const at = covered(coverage, reference);
+        // The reference layout leaves out a section with nothing to show; Workbench labels it.
+        const sections = (entry?.sections ?? []).filter((s) => s.visible &&
+            (!reference ||
+                coverage.some((item) => item.section === s.id && item.state === 'documented') ||
+                (s.id === 'api' && facts.cssProperties.length > 0)));
+        const links = reference && !this.sections
+            ? PAGE_LINKS.filter(([id]) => sections.some((s) => s.id === id))
+            : [];
+        const current = this.#current.value || links[0]?.[0];
+        const shown = this.sections;
         // Sections are built eagerly (not with repeat()), so the signals they read are tracked.
         return html `<div class="wb-content">
-      ${sections.map((section) => html `<section id=${section.id} aria-labelledby=${`${section.id}-title`}>
-            <h2 id=${`${section.id}-title`}>${section.title}</h2>
-            ${this.#section(section.id, page, facts, at)}
+      ${links.length
+            ? html `<nav class="wb-page-nav" aria-label="Page sections">
+              ${links.map(([id, label]) => html `<a
+                    href=${`#${id}`}
+                    aria-current=${current === id ? 'true' : null}
+                    @click=${(event) => this.#jump(event, id)}
+                    >${label}</a
+                  >`)}
+            </nav>`
+            : nothing}
+      ${sections.map((section) => html `<section
+            id=${section.id}
+            aria-labelledby=${`${section.id}-title`}
+            ?hidden=${!!shown && !shown.includes(section.id)}
+          >
+            <h2 id=${`${section.id}-title`} tabindex="-1">${section.title}</h2>
+            ${this.#section(section.id, page, facts, at, sections)}
           </section>`)}
     </div>`;
     }
-    #section(id, page, facts, at) {
+    #section(id, page, facts, at, sections) {
         switch (id) {
             case 'overview':
                 return this.#overview(page, at);
             case 'interactive-example':
                 return this.#interactive(page, facts, at);
             case 'api':
-                return this.#api(facts, at);
+                return this.#reference(facts, at, sections.some((s) => s.id === 'interactive-example'));
             case 'examples':
                 return at('examples/examples', () => this.#examples(page));
             case 'tokens':
                 return this.#tokens(page, at);
             case 'behavior-and-accessibility':
-                return this.#behavior(page, facts, at);
+                return this.#behavior(page, at);
             case 'guidance':
                 return this.#guidance(page, at);
             case 'source':
-                return at('source/module', () => this.#source(page));
+                return this.#source(page, at);
             case 'known-limitations':
-                return at('known-limitations/limitations', () => bullets(authoredValues(page.enrichment?.['limitations'])));
+                return at('known-limitations/limitations', () => html `<div class="wb-callout">
+              ${bullets(authoredValues(page.enrichment?.['limitations']))}
+            </div>`);
             default:
                 return notDocumented(`pages["${page.id}"].sections["${id}"] in oddkin.docs.ts`);
         }
     }
     #overview(page, at) {
         const description = typeof page.declaration['description'] === 'string' ? page.declaration['description'] : '';
-        const registration = page.enrichment?.['registration'];
-        const related = Array.isArray(page.enrichment?.['related'])
-            ? page.enrichment['related'].filter((r) => typeof r === 'string')
-            : [];
-        return html `${at('overview/description', () => description
+        return at('overview/description', () => description
             .split(/\n\s*\n/)
-            .map((paragraph) => html `<p>${inline(paragraph.replace(/\s*\n\s*/g, ' '))}</p>`))}
-      <h3>Imports</h3>
-      ${at('overview/imports', () => html `<p>Register the element with its define entry:</p>
-            <pre class="wb-code" tabindex="0"><code>import '${String(registration)}';</code></pre>`)}
-      ${related.length
-            ? html `<h3>Related components</h3>
-              <ul class="wb-list">
-                ${related.map((tag) => {
-                const name = tag.replace(/^component:/, '');
-                return html `<li><a href=${this.href(`/components/${name}`)}>${name}</a></li>`;
-            })}
-              </ul>`
-            : nothing}`;
+            .map((paragraph) => html `<p>${inline(paragraph.replace(/\s*\n\s*/g, ' '))}</p>`));
     }
     /** Intended use and explained mistakes, each paired with the example to use instead. */
     #guidance(page, at) {
@@ -544,23 +676,96 @@ export class ComponentDetailElement extends OddkinElement.with({
         const link = this.#link.value;
         const frameSettings = settings.pair ? {} : this.#frameSettings(0);
         const update = (patch) => this.#applySettings({ ...settings, ...patch });
-        return html `<div class="wb-toolbar">
-        ${at('interactive-example/presets', () => html `<label
-              >Preset
-              <select
-                .value=${state.preset}
-                @change=${(event) => {
-            const name = event.target.value;
-            const entry = entries.find((p) => p.name === name);
-            if (entry)
-                this.#applyPreset(entry);
-        }}
-              >
-                ${entries.map((p) => html `<option value=${p.name} ?selected=${p.name === state.preset}>
-                      ${p.label}${p.incorrect ? ' (incorrect usage)' : ''}
-                    </option>`)}
-              </select></label
-            >`)}
+        const code = this.#code.value;
+        const tools = this.layout === 'workbench';
+        return html `<div class="wb-example">
+        <div class="wb-example-bar">
+          <p class="wb-example-title">Interactive example · ${page.tag}</p>
+          ${tools
+            ? at('interactive-example/presets', () => html `<label
+                      >Preset
+                      <select
+                        .value=${state.preset}
+                        @change=${(event) => {
+                const name = event.target.value;
+                const entry = entries.find((p) => p.name === name);
+                if (entry)
+                    this.#applyPreset(entry);
+            }}
+                      >
+                        ${entries.map((p) => html `<option value=${p.name} ?selected=${p.name === state.preset}>
+                              ${p.label}${p.incorrect ? ' (incorrect usage)' : ''}
+                            </option>`)}
+                      </select></label
+                    >`)
+            : nothing}
+          <button
+            type="button"
+            aria-expanded=${code ? 'true' : 'false'}
+            aria-controls="wb-example-code"
+            @click=${() => (this.#code.value = !code)}
+          >
+            ${code ? 'Hide code' : 'See code'}
+          </button>
+          ${tools
+            ? html `<button type="button" @click=${() => this.#copyLink(page)}>
+                  Copy example link
+                </button>`
+            : nothing}
+          <button type="button" class="wb-quiet" @click=${() => this.#reset()}>Reset</button>
+        </div>
+        ${link
+            ? html `<label class="wb-share"
+                >Example link <input type="url" readonly .value=${link} size="40"
+              /></label>`
+            : nothing}
+        <div class="wb-example-stage">
+          ${at('interactive-example/preview', () => html `<div class=${settings.pair ? 'wb-previews wb-pair' : 'wb-previews'}>
+                  <div class="wb-preview">
+                    ${settings.pair ? html `<p>Light</p>` : nothing}${this.#hosts[0]}
+                  </div>
+                  ${settings.pair
+            ? html `<div class="wb-preview">
+                          <p>Dark</p>
+                          ${this.#hosts[1]}
+                        </div>`
+            : nothing}
+                </div>
+                <p class="wb-muted wb-example-caption">Changes appear here as you edit.</p>`)}
+          <p class="wb-status" role=${status.alert ? 'alert' : 'status'}>${status.text}</p>
+        </div>
+        ${tools ? this.#settingsBar(settings, update) : nothing}
+        <div class="wb-example-controls">
+          <div class="wb-controls-head">
+            <h3>Controls and API</h3>
+            <p class="wb-muted">Scroll the table; the preview stays in view.</p>
+          </div>
+          <div class="wb-controls-scroll" role="region" aria-label="Controls and API" tabindex="0">
+            ${at('api/properties', () => this.#apiTable(facts))}
+            ${at('api/slots', () => this.#slots(facts))}
+            ${at('api/css-properties', () => this.#cssTable(facts))}
+          </div>
+        </div>
+        <div class="wb-example-code" id="wb-example-code" ?hidden=${!code}>
+          <div class="wb-code-head">
+            <p class="wb-example-title">Generated HTML · follows the current controls</p>
+            <button type="button" @click=${() => this.#copyCode()}>Copy code</button>
+          </div>
+          <pre
+            class="wb-code wb-snippet"
+            tabindex="0"
+          ><code>${snippet(page, state, { settings: frameSettings })}</code></pre>
+        </div>
+      </div>
+      ${tools
+            ? html `<h3>Event log</h3>
+              ${this.#eventLog(facts)}`
+            : nothing}`;
+    }
+    /** Workbench's preview settings: mode, light and dark together, direction, and width. */
+    #settingsBar(settings, update) {
+        return html `<div class="wb-example-settings">
+      <div class="wb-toolbar">
         <label
           >Mode
           <select
@@ -623,8 +828,6 @@ export class ComponentDetailElement extends OddkinElement.with({
             }}
               /></label>`
             : nothing}
-        <button type="button" @click=${() => this.#reset()}>Reset</button>
-        <button type="button" @click=${() => this.#copyLink(page)}>Copy example link</button>
       </div>
       <p class="wb-muted wb-settings-summary">
         Preview only:
@@ -634,31 +837,7 @@ export class ComponentDetailElement extends OddkinElement.with({
             ? 'fills the column'
             : `${settings.width === 'custom' ? settings.customWidth : WIDTHS[settings.width]}px container`}
       </p>
-      ${link
-            ? html `<label class="wb-share"
-              >Example link <input type="url" readonly .value=${link} size="40"
-            /></label>`
-            : nothing}
-      ${at('interactive-example/preview', () => html `<div class=${settings.pair ? 'wb-previews wb-pair' : 'wb-previews'}>
-            <div class="wb-preview">
-              ${settings.pair ? html `<p>Light</p>` : nothing}${this.#hosts[0]}
-            </div>
-            ${settings.pair
-            ? html `<div class="wb-preview">
-                    <p>Dark</p>
-                    ${this.#hosts[1]}
-                  </div>`
-            : nothing}
-          </div>`)}
-      <p class="wb-status" role=${status.alert ? 'alert' : 'status'}>${status.text}</p>
-      <h3>Event log</h3>
-      ${this.#eventLog(facts)}
-      <h3>Code</h3>
-      <p class="wb-muted">Plain HTML and JavaScript for the current configuration.</p>
-      <pre
-        class="wb-code wb-snippet"
-        tabindex="0"
-      ><code>${snippet(page, state, { settings: frameSettings })}</code></pre>`;
+    </div>`;
     }
     #eventLog(facts) {
         if (!facts.events.length)
@@ -684,88 +863,58 @@ export class ComponentDetailElement extends OddkinElement.with({
             : html `<p class="wb-muted">No events yet.</p>`}
     </div>`;
     }
-    #api(facts, at) {
-        return html `${at('api/properties', () => this.#apiTable(facts))}
-      <h3>Slots</h3>
-      ${at('api/slots', () => this.#slots(facts))}
-      <h3>Events</h3>
-      ${at('api/events', () => this.#namedTable(facts.events, 'events', 'Event', true))}
-      <h3>Methods</h3>
-      ${at('api/methods', () => html `<p class="wb-muted">
-              Methods are documented here and never invoked by the Workbench.
-            </p>
-            ${this.#namedTable(facts.methods, 'methods', 'Method', false)}`)}
-      <h3>CSS parts</h3>
-      ${at('api/parts', () => this.#namedTable(facts.parts, 'parts', 'Part', false))}
-      <h3>CSS custom properties</h3>
-      ${at('api/css-properties', () => this.#namedTable(facts.cssProperties, 'css-properties', 'Property', false))}
-      <h3>Custom states</h3>
-      ${at('api/css-states', () => this.#namedTable(facts.cssStates, 'states', 'State', false))}`;
-    }
-    #namedTable(entries, id, label, withType) {
-        return html `<div class="wb-table-wrap">
-      <table class="wb-stack" data-table=${id}>
-        <thead>
-          <tr>
-            <th scope="col">${label}</th>
-            ${withType ? html `<th scope="col">Type</th>` : nothing}
-            <th scope="col">Description</th>
-          </tr>
-        </thead>
-        <tbody>
-          ${entries.map((entry) => html `<tr>
-                <td data-label=${label}><code>${entry.name || '(default)'}</code></td>
-                ${withType ? html `<td data-label="Type"><code>${entry.type ?? 'Unknown'}</code></td>` : nothing}
-                <td data-label="Description">
-                  ${entry.description ? inline(entry.description) : html `<span class="wb-not-documented">Not documented</span>`}
-                </td>
-              </tr>`)}
-        </tbody>
-      </table>
-    </div>`;
+    /** Contracts beside the controls (Figma 232:9895): events, parts, methods, states, and styling hooks. */
+    #reference(facts, at, inExample) {
+        const reference = this.layout === 'reference';
+        const card = (id, title, entries, name = (n) => n) => reference && !entries.length
+            ? nothing
+            : html `<div class="wb-box" data-card=${id}>
+            <h3>${title}</h3>
+            ${at(`api/${id}`, () => html `<ul class="wb-plain">
+                  ${entries.map((entry) => html `<li>
+                        <code>${name(entry.name)}</code
+                        >${entry.description ? html ` — ${inline(entry.description)}` : nothing}
+                      </li>`)}
+                </ul>`)}
+          </div>`;
+        return html `${inExample
+            ? html `<p class="wb-lede">
+              Contracts that complement the properties and slots table above.
+            </p>`
+            : html `${at('api/properties', () => this.#apiTable(facts))}
+            ${at('api/slots', () => this.#slots(facts))}
+            ${at('api/css-properties', () => this.#cssTable(facts))}`}
+      <div class="wb-boxes">
+        ${card('events', 'Events', facts.events)} ${card('parts', 'CSS parts', facts.parts)}
+        ${card('methods', 'Methods', facts.methods)}
+        ${card('css-states', 'Custom states', facts.cssStates, (n) => `:state(${n})`)}
+      </div>
+      ${facts.cssProperties.length
+            ? html `<div class="wb-box wb-sunken" data-card="css-properties">
+              <h3>CSS custom properties</h3>
+              <ul class="wb-plain wb-names">
+                ${facts.cssProperties.map((entry) => html `<li><code>${entry.name}</code></li>`)}
+              </ul>
+            </div>`
+            : nothing}`;
     }
     #apiTable(facts) {
-        return html `<div class="wb-table-wrap">
-      <table class="wb-stack wb-api" data-table="api">
-        <caption>
-          Editing a value updates the preview: one write per change, as a property or as an
-          attribute. Reflected attributes are not written back.
-        </caption>
-        <thead>
-          <tr>
-            <th scope="col">Name</th>
-            <th scope="col">Type</th>
-            <th scope="col">Default</th>
-            <th scope="col">Current value</th>
-            <th scope="col">Description</th>
-          </tr>
-        </thead>
-        <tbody>
-          ${facts.rows.map((row) => this.#apiRow(row))}
-        </tbody>
-      </table>
-    </div>`;
+        return this.#group('api', 'Editing a value updates the preview: one write per change, as a property or as an attribute. Reflected attributes are not written back.', ['Properties', 'Types', 'Default', 'Attribute', 'Reflected', 'Control / current value'], facts.rows.map((row) => this.#apiRow(row)));
     }
     #apiRow(row) {
-        const name = row.property ?? row.attribute ?? '';
-        const notes = [];
-        if (row.property && row.attribute)
-            notes.push(`attr ${row.attribute}${row.reflects ? ', reflects' : ''}`);
-        else if (!row.property)
-            notes.push('attribute only');
-        else
-            notes.push(row.propertyOnly ? 'property only' : 'no attribute');
         return html `<tr data-row=${row.id}>
-      <th scope="row" data-label="Name"><code>${name}</code><small>${notes.join(' · ')}</small></th>
-      <td data-label="Type">
-        <code>${row.values ? row.values.map((v) => JSON.stringify(v)).join(' | ') : row.type}</code>
-        ${row.nullable ? html `<small>nullable</small>` : nothing}
+      ${named(row.property ?? row.attribute ?? '', row.description)}
+      <td data-label="Types">
+        ${row.values ? row.values.join(', ') : row.type}${row.values && row.nullable ? ' · nullable' : ''}
       </td>
-      <td data-label="Default">${row.default ? html `<code>${row.default}</code>` : 'Unknown'}</td>
-      <td data-label="Current value">${this.#control(row)}</td>
-      <td data-label="Description">
-        ${row.description ? inline(row.description) : html `<span class="wb-not-documented">Not documented</span>`}
+      <td data-label="Default">${row.default ? unquote(row.default) : 'Unknown'}</td>
+      <td data-label="Attribute">
+        ${row.attribute ? (row.property ? row.attribute : `${row.attribute} (attribute only)`) : row.propertyOnly ? 'Property only' : 'None'}
       </td>
+      <td data-label="Reflected">
+        ${row.property && row.attribute ? (row.reflects ? 'Yes' : 'No') : '—'}
+      </td>
+      <td data-label="Control">${this.#control(row)}</td>
     </tr>`;
     }
     #control(row) {
@@ -786,7 +935,11 @@ export class ComponentDetailElement extends OddkinElement.with({
         const attrValue = attr ? state.attributes[attr] : undefined;
         const propSet = prop !== undefined && prop in state.properties;
         const propValue = prop !== undefined ? state.properties[prop] : undefined;
-        const modeSwitch = row.property && row.attribute && !row.propertyOnly && row.control !== 'json'
+        const modeSwitch = this.layout === 'workbench' &&
+            row.property &&
+            row.attribute &&
+            !row.propertyOnly &&
+            row.control !== 'json'
             ? html `<select
             aria-label=${`Write ${name} as`}
             .value=${mode}
@@ -806,6 +959,8 @@ export class ComponentDetailElement extends OddkinElement.with({
             const checked = mode === 'attribute' ? attrValue !== undefined : propValue === true;
             control = html `<input
           type="checkbox"
+          role="switch"
+          class="wb-switch"
           aria-label=${label}
           .checked=${checked}
           @change=${(event) => {
@@ -834,21 +989,22 @@ export class ComponentDetailElement extends OddkinElement.with({
                         ? '\u0000null'
                         : String(propValue)
                     : '';
-            control = html `<select
-        aria-label=${label}
-        .value=${current}
-        @change=${(event) => {
-                const value = event.target.value;
+            const write = (value) => {
                 if (mode === 'attribute')
                     this.#writeAttribute(row, value === '' ? null : value);
                 else if (value === '')
                     this.#unsetProperty(row);
                 else
                     this.#writeProperty(row, value === '\u0000null' ? null : value);
-            }}
+            };
+            const values = row.values ?? [];
+            control = html `<select
+        aria-label=${label}
+        .value=${current}
+        @change=${(event) => write(event.target.value)}
       >
         <option value="" ?selected=${current === ''}>(unset)</option>
-        ${(row.values ?? []).map((value) => html `<option value=${value} ?selected=${current === value}>${value}</option>`)}
+        ${values.map((value) => html `<option value=${value} ?selected=${current === value}>${value}</option>`)}
         ${mode === 'property' && row.nullable
                 ? html `<option value=${'\u0000null'} ?selected=${current === '\u0000null'}>
                 null
@@ -893,25 +1049,20 @@ export class ComponentDetailElement extends OddkinElement.with({
           aria-label=${label}
           placeholder=${isSet ? '' : 'unset'}
           .value=${shown}
-          @change=${(event) => {
+          @input=${(event) => {
+                // The preview follows the field as the reader types; an unfinished number waits.
                 const text = event.target.value;
-                if (mode === 'attribute') {
-                    if (number && text !== '' && !Number.isFinite(Number(text))) {
-                        this.#setError(row.id, 'Not written: not a number.');
-                        return;
-                    }
-                    this.#writeAttribute(row, text);
+                if (this.#textProblem(number, mode, text))
                     return;
-                }
-                if (number) {
-                    if (text.trim() === '' || !Number.isFinite(Number(text))) {
-                        this.#setError(row.id, 'Not written: enter a number, or use Unset.');
-                        return;
-                    }
-                    this.#writeProperty(row, Number(text));
-                }
+                if (mode === 'attribute')
+                    this.#writeAttribute(row, text);
                 else
-                    this.#writeProperty(row, text);
+                    this.#writeProperty(row, number ? Number(text) : text);
+            }}
+          @change=${(event) => {
+                const problem = this.#textProblem(number, mode, event.target.value);
+                if (problem)
+                    this.#setError(row.id, problem);
             }}
         />
         <button
@@ -948,61 +1099,133 @@ export class ComponentDetailElement extends OddkinElement.with({
         return html `<div class="wb-cell-controls">${control} ${modeSwitch}</div>
       ${error ? html `<p class="wb-error" role="alert">${error}</p>` : nothing}`;
     }
-    #slots(facts) {
-        const state = this.#state.value;
+    /** One group of the controls: its header row names the group and its columns, and stays in view. */
+    #group(id, caption, heads, rows) {
         return html `<div class="wb-table-wrap">
-      <table class="wb-stack" data-table="slots">
+      <table class="wb-stack wb-api" data-table=${id}>
+        <caption class="wb-visually-hidden">
+          ${caption}
+        </caption>
+        <colgroup>
+          ${[0, 1, 2, 3, 4, 5].map(() => html `<col />`)}
+        </colgroup>
         <thead>
           <tr>
-            <th scope="col">Slot</th>
-            <th scope="col">Description</th>
-            <th scope="col">Text content</th>
+            ${heads.map((head, i) => html `<th scope="col" colspan=${heads.length === 5 && i === 3 ? '2' : null}>
+                  ${head}
+                </th>`)}
           </tr>
         </thead>
         <tbody>
-          ${facts.slots.map((slot) => {
-            const label = slot.name || '(default)';
-            return html `<tr data-slot=${slot.name}>
-              <th scope="row" data-label="Slot"><code>${label}</code></th>
-              <td data-label="Description">
-                ${slot.description ? inline(slot.description) : html `<span class="wb-not-documented">Not documented</span>`}
-              </td>
-              <td data-label="Text content">
-                <input
-                  type="text"
-                  aria-label=${`${label} slot text`}
-                  .value=${state.slots[slot.name] ?? ''}
-                  @change=${(event) => this.#writeSlot(slot.name, event.target.value)}
-                />
-                <small>Text only; richer compositions need a fixture from defineExamples.</small>
-              </td>
-            </tr>`;
-        })}
+          ${rows}
         </tbody>
       </table>
     </div>`;
     }
+    #slots(facts) {
+        const state = this.#state.value;
+        return this.#group('slots', 'Slots: text content written into the preview.', ['Slots', 'Content type', 'Default', 'Name', 'Position', 'Control / current content'], facts.slots.map((slot) => {
+            const label = slot.name || 'default';
+            return html `<tr data-slot=${slot.name}>
+          ${named(label, undefined)}
+          <td data-label="Content type">Text</td>
+          <td data-label="Default">Empty</td>
+          <td data-label="Name">${slot.name || '(none)'}</td>
+          <td data-label="Position">
+            ${slot.description ? inline(slot.description) : html `<span class="wb-not-documented">Not documented</span>`}
+          </td>
+          <td data-label="Control">
+            <input
+              type="text"
+              aria-label=${`${label} slot text`}
+              .value=${state.slots[slot.name] ?? ''}
+              @input=${(event) => this.#writeSlot(slot.name, event.target.value)}
+            />
+          </td>
+        </tr>`;
+        }));
+    }
+    #cssTable(facts) {
+        const styles = this.#state.value.styles ?? {};
+        return this.#group('css-properties', "CSS custom properties: values set on the preview element's style.", ['CSS custom properties', 'Syntax', 'Default', 'Description', 'Control / current value'], facts.cssProperties.map((entry) => {
+            const value = styles[entry.name];
+            return html `<tr data-css=${entry.name}>
+          ${named(entry.name, undefined)}
+          <td data-label="Syntax">${entry.type ?? 'Unknown'}</td>
+          <td data-label="Default">${entry.default ?? 'Unknown'}</td>
+          <td data-label="Description" colspan="2">
+            ${entry.description ? inline(entry.description) : html `<span class="wb-not-documented">Not documented</span>`}
+          </td>
+          <td data-label="Control">
+            ${isCustomPropertyName(entry.name)
+                ? html `<div class="wb-cell-controls">
+                    <input
+                      type="text"
+                      aria-label=${`${entry.name} value`}
+                      placeholder="unset"
+                      .value=${value ?? ''}
+                      @input=${(event) => {
+                    const text = event.target.value;
+                    this.#writeStyle(entry.name, text === '' ? null : text);
+                }}
+                    />
+                    <button
+                      type="button"
+                      ?disabled=${value === undefined}
+                      @click=${() => this.#writeStyle(entry.name, null)}
+                    >
+                      Unset
+                    </button>
+                  </div>`
+                : html `<span class="wb-muted">Not editable: not a custom property name.</span>`}
+          </td>
+        </tr>`;
+        }));
+    }
+    /** The published examples as cards (Figma 20:2266), each with a live specimen when the host gives one. */
     #examples(page) {
-        const entries = presets(page);
-        return html `<ul class="wb-list wb-examples">
-      ${entries.map((entry) => html `<li data-example=${entry.id}>
-            <strong>${entry.label}</strong> <code>${entry.id}</code>
-            ${entry.incorrect ? html `<small>Incorrect usage</small>` : nothing}
-            ${entry.guidance ? html `<p>${inline(entry.guidance)}</p>` : nothing}
-            ${entry.incorrect?.explanation ? html `<p>${inline(entry.incorrect.explanation)}</p>` : nothing}
-            ${entry.requiresFixture
-            ? html `<p class="wb-muted">
-                    Requires fixture: rendered by its example module only.
-                  </p>`
-            : entry.state
-                ? html `<button type="button" @click=${() => this.#applyPreset(entry)}>
-                      Show in preview
-                    </button>`
-                : html `<p class="wb-muted">
-                      Values not published (the example module was not loaded).
-                    </p>`}
-          </li>`)}
-    </ul>`;
+        const preview = this.examplePreview;
+        const tools = this.layout === 'workbench';
+        const shown = presets(page).filter((e) => !e.incorrect && (tools || !e.requiresFixture));
+        // Presets lead; the reference layout shows four and keeps the rest one action away.
+        const ordered = [...shown.filter((e) => e.preset), ...shown.filter((e) => !e.preset)];
+        const all = tools || this.#allExamples.value;
+        return html `<p class="wb-lede">Compare the published examples without leaving the page.</p>
+      <ul class="wb-boxes wb-examples" role="list">
+        ${(all ? ordered : ordered.slice(0, 4)).map((entry) => {
+            const node = preview?.(page, entry.id);
+            return html `<li class="wb-box" data-example=${entry.id}>
+            ${node ? html `<div class="wb-specimen">${node}</div>` : nothing}
+            <div class="wb-box-body">
+              <h3>${entry.label}</h3>
+              ${entry.guidance ? html `<p>${inline(entry.guidance)}</p>` : nothing}
+              ${entry.requiresFixture
+                ? html `<p class="wb-muted">
+                      Requires fixture: rendered by its example module only.
+                    </p>`
+                : !tools
+                    ? nothing
+                    : entry.state
+                        ? html `<button type="button" @click=${() => this.#applyPreset(entry)}>
+                          Show in preview
+                        </button>`
+                        : html `<p class="wb-muted">
+                          Values not published (the example module was not loaded).
+                        </p>`}
+            </div>
+          </li>`;
+        })}
+      </ul>
+      ${!tools && ordered.length > 4
+            ? html `<button
+              type="button"
+              class="wb-more"
+              aria-expanded=${all ? 'true' : 'false'}
+              @click=${() => (this.#allExamples.value = !all)}
+            >
+              ${all ? 'Show fewer examples' : `Show all ${ordered.length} examples`}
+            </button>`
+            : nothing}`;
     }
     #tokens(page, at) {
         const mappings = Array.isArray(page.enrichment?.['styleMappings'])
@@ -1083,38 +1306,47 @@ export class ComponentDetailElement extends OddkinElement.with({
             </table>
           </div>`)}`;
     }
-    #behavior(page, facts, at) {
-        return html `<h3>Accessibility</h3>
-      ${at('behavior-and-accessibility/a11y', () => bullets(authoredValues(page.enrichment?.['a11y'])))}
-      <h3>Keyboard</h3>
-      ${at('behavior-and-accessibility/keyboard', () => bullets(authoredValues(page.enrichment?.['keyboard'])))}
-      ${facts.cssStates.length
-            ? html `<h3>States</h3>
-              <ul class="wb-list">
-                ${facts.cssStates.map((s) => html `<li>
-                      <code>:state(${s.name})</code
-                      >${s.description ? html ` — ${inline(s.description)}` : nothing}
-                    </li>`)}
-              </ul>`
-            : nothing}`;
+    /** Accessibility as two cards (Figma 20:2292): behavior, then keyboard and guidance. */
+    #behavior(page, at) {
+        const card = (title, key) => {
+            const items = authoredValues(page.enrichment?.[key]);
+            return this.layout === 'reference' && !items.length
+                ? nothing
+                : html `<div class="wb-box">
+            <h3>${title}</h3>
+            ${at(`behavior-and-accessibility/${key}`, () => bullets(items))}
+          </div>`;
+        };
+        return html `<div class="wb-boxes">
+      ${card('Behavior', 'a11y')} ${card('Keyboard and guidance', 'keyboard')}
+    </div>`;
     }
-    #source(page) {
+    /** Where the element lives and how to register it (Figma 232:9845). */
+    #source(page, at) {
         const definition = isRecord(page.enrichment?.['definition'])
             ? page.enrichment['definition']
             : undefined;
         const ref = isRecord(definition?.['ref']) ? definition['ref'] : undefined;
-        return html `<dl>
-      <dt>Package</dt>
-      <dd><code>${page.package}</code></dd>
-      <dt>Module</dt>
-      <dd><code>${page.module}</code></dd>
-      <dt>Class</dt>
-      <dd><code>${String(page.declaration['name'] ?? 'Unknown')}</code></dd>
-      ${ref
-            ? html `<dt>Definition</dt>
-              <dd><code>${String(ref['module'])}</code> (<code>${String(ref['name'])}</code>)</dd>`
-            : nothing}
-    </dl>`;
+        const field = (label, ...values) => html `<div class="wb-fact">
+        <span class="wb-fact-label">${label}</span>
+        ${values.map((value) => html `<code
+              >${String(value)
+            .split('/')
+            .map((part, i) => (i ? html `/<wbr />${part}` : part))}</code
+            >`)}
+      </div>`;
+        return html `<p class="wb-lede">
+        Where the element is published, so it is easy to locate, import, and verify.
+      </p>
+      ${at('source/module', () => html `<div class="wb-facts">
+            ${field('Package', page.package)} ${field('Module', page.module)}
+            ${field('Class', page.declaration['name'] ?? 'Unknown')}
+            ${ref ? field('Definition', ref['name'], ref['module']) : nothing}
+          </div>`)}
+      ${at('source/register', () => html `<div class="wb-fact wb-register">
+            <span class="wb-fact-label">Register</span>
+            <code>import '${String(registrationOf(page))}';</code>
+          </div>`)}`;
     }
 }
 //# sourceMappingURL=component-detail.js.map