@vscode/component-explorer 0.2.1-161 → 0.2.1-162

package/README.md

@@ -43,10 +43,19 @@ Options:
 | `background` | `'light' \| 'dark'` | `'light'` | Preview canvas background pattern. |
 | `description` | `string` | — | Documentation description. |
 
-Page fixtures open in **Fit** mode in the normal Explorer UI. Their compact viewport toolbar can
-select a declared preset, edit logical width/height, switch to **Responsive** canvas sizing, or
-render at unscaled **1:1** size. These persisted UI settings do not affect embedded or headless
-rendering.
+The sidebar's **Preview Sizing** dropdown applies to all fixtures and persists across navigation
+and reloads. **Fit** scales down to fit the preview viewport's width and height, **1:1** shows
+natural size, and **Responsive (Pages)** resizes page fixtures while using Fit for components.
+Page fixtures retain their per-fixture toolbar for selecting a viewport preset and editing logical
+width/height. These UI settings do not affect embedded or headless rendering.
+
+Natural-size component fixtures also default to **Fit**, shrinking to the available preview
+width and height without upscaling small components. Both fixed dimensions and dynamically
+changing content retain their natural layout: only the preview presentation is scaled.
+Dynamic size changes and preview resizing update the scale without remounting the fixture.
+Fit uses a shared preview-viewport budget with fixed allowances for padding and fixture chrome.
+It does not depend on a fixture's position, wrapping, neighboring fixtures, or its scaled bounds.
+Small variants can share a row; large variants wrap without shrinking to their toolbar's width.
 
 ### Render timeout and diagnostics
 
@@ -114,7 +123,12 @@ single control that edits them all at once.
 
 Use `inputControls` with `placement: 'toolbar'` for compact boolean or enum controls beside the
 fixture dimensions. Opt a property into live updates with `watchInput`; changed properties without
-a watcher keep the default full-remount behavior:
+a watcher keep the default full-remount behavior. A fixture can call
+`reportInput(key, value)` after its component changes a watched property itself.
+This updates the sidebar/shared input store without echoing the change to that
+fixture's watcher or remounting it. Reports are coalesced per microtask and
+discarded after disposal; unwatched properties are rejected. This also works
+across iframe isolation.
 
 ```ts
 defineFixture({
@@ -162,8 +176,73 @@ defineFixture({
 ```
 
 Panels default beside a single logical fixture and in the shared bottom workbench for variant rows.
-Set `placement: 'canvas-right'` or `'bottom-panel'` on the panel to override this rule. Golden Layout
-tabs can be dragged into splits when multiple panels need to remain visible.
+Set `placement: 'canvas-right'` or `'bottom-panel'` on the panel to override this rule.
+Closed inline panels are grouped in a **Debug panels** dropdown. When a stack's tabs do not fit,
+the active tab remains visible and a **More debug panels** dropdown (`...`) offers the other panels.
+Select a panel, then drag its tab into a split to keep multiple panels visible. During dragging,
+overflowing tabs are revealed; hovering near the tab strip's edges scrolls it. Drop onto a tab
+header to reorder or move tabs between panes.
+
+**Split right** creates a second live view of the selected debug panel, leaving the original open.
+Both copies share fixture state but have independent tab selections and view instances. Close a
+pane using its **Close debug pane** button; its other tabs remain available in the workbench.
+
+Drag the bottom edge of inline debug panes to give them more vertical space independently of the
+fixture. The resize handle also supports Up/Down arrow keys; double-click or press Home to reset.
+**Viewport height** fills the available preview height without stretching or remounting the fixture.
+Open/closed panes, tab order and selection, duplicate views, split ratios, widths, and heights
+survive navigation and reload in this browser. Storage is scoped to the project supplied by the
+Vite/Webpack plugin. Custom hosts can supply `ExplorerAppOptions.storageScope` (the default is the
+Explorer URL path). Storage errors are reported in the sidebar and console.
+
+Enable **Synchronize debug panes** in the properties sidebar to copy the current fixture's
+arrangement into a shared template. Other fixtures use that template with their own live data.
+Missing panel types are temporarily hidden, and empty groups collapse. Navigation and panel
+preference changes do not rewrite the template. An explicit layout edit (including selecting a
+tab or resizing) saves the visible arrangement, discarding hidden groups from the template.
+Turning synchronization off restores the independent fixture layouts and preferences from before
+it was enabled. The aggregated bottom workbench, including Console, persists independently and
+does not participate in synchronization.
+
+### Persistent panel UI state
+
+Panels can opt into validated, versioned, JSON-serializable view preferences without accessing
+browser storage. Call `context.viewState` with a stable schema/version and one state object per
+panel and scope. `get()` restores state before rendering; `set()` validates and saves it; `onChange()`
+subscribes to changes (dispose the subscription with the panel).
+
+```ts
+render(container, context) {
+  const preferences = context.viewState({
+    version: 1,
+    scope: 'pane',
+    schema: z.object({ renderer: z.enum(['cmark-gfm', 'markdown-it']) }),
+    defaultValue: { renderer: 'cmark-gfm' },
+  });
+  const select = document.createElement('select');
+  for (const renderer of ['cmark-gfm', 'markdown-it']) {
+    select.add(new Option(renderer, renderer));
+  }
+  select.value = preferences.get().renderer;
+  select.onchange = () => {
+    preferences.set({ renderer: select.value === 'markdown-it' ? 'markdown-it' : 'cmark-gfm' });
+  };
+  const subscription = preferences.onChange(value => { select.value = value.renderer; });
+  container.append(select);
+  return {
+    update(source) { /* render live fixture data separately */ },
+    dispose() { subscription.dispose(); select.remove(); },
+  };
+}
+```
+
+Use `scope: 'pane'` for preferences that follow a synchronized pane between fixtures (for example,
+the Markdown Reference renderer). Use `scope: 'fixture'` for fixture-dependent selections or scroll
+positions. Split right copies the current preferences once; the two tab instances then evolve
+independently. Docking and reordering retain their identities, even when duplicate tabs are placed
+in the same group. Unsupported versions or invalid saved values use the declared default and
+report a warning; bump the version when changing the state shape. Fixture data, actions, and
+headless rendering are unaffected.
 
 Any defined `RenderResult.output` gets a built-in read-only JSON panel. Wrap it with
 `interactiveOutput({ getSnapshot, activate })` to opt into JSON editing; output actions update the