@gjsify/adwaita-storybook 0.35.0 → 0.37.0

package/lib/types/app.d.ts

@@ -29,18 +29,14 @@ export declare class StorybookWebApp implements StorybookView<StoryElement> {
     /** Build the UI, instantiate stories, and select the first one. */
     mount(): void;
     /**
-     * Adapt the two split views to the available width, the way a desktop
-     * Adwaita window sheds panes as it narrows. There are two thresholds:
-     *
-     *   - below {@link CONTROLS_BREAKPOINT} the controls panel folds away into an
-     *     on-demand overlay, so the sidebar + preview keep their room (this is
-     *     what a medium embed — e.g. the docs page — wants);
-     *   - below {@link NAV_BREAKPOINT} there isn't room for the sidebar either,
-     *     so the whole thing goes single-pane and navigates one column at a time.
+     * Adapt the two split views to the available width, the way a desktop Adwaita
+     * window sheds panes as it narrows: below {@link CONTROLS_BREAKPOINT} the controls
+     * panel folds into an on-demand overlay so sidebar + preview keep their room, and
+     * below {@link NAV_BREAKPOINT} the sidebar goes too and nav is single-pane.
      */
     private _observeBreakpoint;
     private _applyBreakpoint;
-    /** The currently-displayed story, or null. */
+    /** The currently-displayed story, or null. Also the MCP surface via `window.__storybook`. */
     get activeStory(): StoryElement | null;
     /** Every story flattened to a summary. */
     listStories(): StorySummary[];

package/lib/types/story-element.d.ts

@@ -5,24 +5,17 @@ export type StoryArgsListener = (args: StoryArgs) => void;
 /**
  * Base class for browser story elements.
  *
- * Provides default chrome — a clamped boxed group with a title + description
- * above a centered, dashed-framed preview stage — built programmatically. Simple
- * stories compose their preview by calling {@link addContent}; a subclass that
- * needs a bespoke layout passes its own root element to the constructor (then
- * {@link addContent} is a no-op).
+ * Provides default chrome — a clamped boxed group with a title + description above a
+ * centered, dashed-framed preview stage. Simple stories compose their preview by
+ * calling {@link addContent}; a subclass needing a bespoke layout passes its own root
+ * element to the constructor, and {@link addContent} is then a no-op.
  */
 export declare class StoryElement extends StoryViewBase<HTMLElement> {
     /**
-     * @param meta       The story's metadata (the same renderer-agnostic object
-     *                   its GTK twin uses).
-     * @param story      Variant name (defaults to "Default").
      * @param customRoot Opt out of the default chrome by supplying a root element.
      */
     constructor(meta: StoryMeta, story?: string, customRoot?: HTMLElement);
-    /**
-     * The root node inserted into the storybook's preview area. Alias for the
-     * base's {@link root} getter — kept because consumers reference `.element`.
-     */
+    /** Alias for the base's {@link root} getter — kept because consumers use `.element`. */
     get element(): HTMLElement;
     /** Build the @gjsify/adwaita-web DOM chrome — the single renderer seam. */
     protected createChrome(_meta: StoryMeta, customRoot?: HTMLElement): StoryChrome<HTMLElement>;

package/lib/types/types.d.ts

@@ -8,11 +8,7 @@ export interface WebStoryConstructor {
 }
 /** Wraps a story's content-build step (e.g. to install a shared environment). */
 export type WebStoryDecorator = (build: () => void, story: StoryElement) => void;
-/**
- * A group of related web stories, optionally wrapped by module-level decorators.
- * The DOM binding of {@link StoryModuleLike} over {@link StoryElement} +
- * {@link WebStoryConstructor}.
- */
+/** A group of related web stories, optionally wrapped by module-level decorators. */
 export interface WebStoryModule extends StoryModuleLike<StoryElement, WebStoryConstructor> {
     stories: WebStoryConstructor[];
     /** Populated by {@link StoryRegistry.createStoryInstances}. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-storybook",
-    "version": "0.35.0",
+    "version": "0.37.0",
     "description": "Browser renderer for the @gjsify/stories contract — the web counterpart of @gjsify/storybook, built on @gjsify/adwaita-web",
     "type": "module",
     "main": "./src/index.ts",
@@ -29,12 +29,12 @@
         "browser"
     ],
     "dependencies": {
-        "@gjsify/adwaita-web": "^0.35.0",
-        "@gjsify/stories": "^0.35.0",
-        "@gjsify/storybook-core": "^0.35.0"
+        "@gjsify/adwaita-web": "^0.37.0",
+        "@gjsify/stories": "^0.37.0",
+        "@gjsify/storybook-core": "^0.37.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.35.0",
+        "@gjsify/cli": "^0.37.0",
         "typescript": "^6.0.3"
     },
     "gjsify": {

package/src/app.ts

@@ -1,15 +1,11 @@
-// StorybookWebApp — the browser component browser: a sidebar of stories grouped
-// by category, a preview pane, and a controls panel that renders live-bound
-// adwaita-web rows from each story's controls. The web counterpart of
-// @gjsify/storybook's StorybookWindow, built from @gjsify/adwaita-web custom
-// elements so it looks and behaves like the native GTK storybook.
+// The browser component browser — sidebar of stories by category, preview pane, and a
+// controls panel of live-bound adwaita-web rows; the web counterpart of
+// `@gjsify/storybook`'s `StorybookWindow`.
 //
-// The app state machine (register/instantiate, category grouping, show + wire
-// controls, the MCP control surface) lives in @gjsify/storybook-core's
-// StorybookController. This class is the browser StorybookView<StoryElement>:
-// it owns ONLY the adwaita-web split-views chrome (_buildUI), the browser-only
-// responsive breakpoint fold (_observeBreakpoint/_applyBreakpoint), and the
-// window.__storybook MCP bridge (_exposeGlobal, delegating to the controller).
+// `StorybookController` in `@gjsify/storybook-core` owns the app state machine. This
+// class is the browser `StorybookView<StoryElement>` and owns ONLY the split-views
+// chrome (`_buildUI`), the browser-only responsive fold (`_observeBreakpoint` /
+// `_applyBreakpoint`) and the `window.__storybook` MCP bridge (`_exposeGlobal`).
 
 import '@gjsify/adwaita-web'; // registers the custom elements + self-injects the adwaita stylesheet
 import type { StoryArgValue } from '@gjsify/stories';
@@ -87,14 +83,10 @@ export class StorybookWebApp implements StorybookView<StoryElement> {
     }
 
     /**
-     * Adapt the two split views to the available width, the way a desktop
-     * Adwaita window sheds panes as it narrows. There are two thresholds:
-     *
-     *   - below {@link CONTROLS_BREAKPOINT} the controls panel folds away into an
-     *     on-demand overlay, so the sidebar + preview keep their room (this is
-     *     what a medium embed — e.g. the docs page — wants);
-     *   - below {@link NAV_BREAKPOINT} there isn't room for the sidebar either,
-     *     so the whole thing goes single-pane and navigates one column at a time.
+     * Adapt the two split views to the available width, the way a desktop Adwaita
+     * window sheds panes as it narrows: below {@link CONTROLS_BREAKPOINT} the controls
+     * panel folds into an on-demand overlay so sidebar + preview keep their room, and
+     * below {@link NAV_BREAKPOINT} the sidebar goes too and nav is single-pane.
      */
     private _observeBreakpoint(): void {
         const apply = (): void => this._applyBreakpoint();
@@ -115,18 +107,14 @@ export class StorybookWebApp implements StorybookView<StoryElement> {
         const osv = this._controlsSplit as HTMLElement & { collapsed: boolean; showSidebar: boolean };
         if (nav.collapsed !== navCollapsed) nav.collapsed = navCollapsed;
         if (osv.collapsed !== controlsCollapsed) osv.collapsed = controlsCollapsed;
-        // Single-pane nav shows the story list first (like native); the back
-        // button only appears once a story is pushed onto the content pane.
+        // Single-pane nav shows the story list first, as native does; the back button
+        // only appears once a story is pushed onto the content pane.
         this._navSplit.removeAttribute('show-content');
         this._backBtn.hidden = true;
-        // The controls panel docks only when there's room; otherwise it's an
-        // on-demand overlay so the sidebar + preview keep their space.
         osv.showSidebar = !controlsCollapsed;
     }
 
-    // --- control surface (delegates to the controller; driven by host-level MCP via window.__storybook) ---
-
-    /** The currently-displayed story, or null. */
+    /** The currently-displayed story, or null. Also the MCP surface via `window.__storybook`. */
     get activeStory(): StoryElement | null {
         return this._controller.activeStory;
     }
@@ -151,8 +139,6 @@ export class StorybookWebApp implements StorybookView<StoryElement> {
         return this._controller.setActiveArg(name, value);
     }
 
-    // --- StorybookView<StoryElement> render seams (driven by the controller) ---
-
     renderSidebar(groups: Array<CategoryGroup<StoryElement>>, onSelect: (instance: StoryElement) => void): void {
         this._listEl.replaceChildren();
         this._rowByTitle.clear();
@@ -217,7 +203,6 @@ export class StorybookWebApp implements StorybookView<StoryElement> {
     }
 
     private _buildUI(): void {
-        // --- Sidebar pane: header + scrollable story list ---
         this._listEl = h('div', { class: 'sb-sidebar-list navigation-sidebar' });
         const sidebarScroll = h('div', { class: 'sb-sidebar-scroll' }, [this._listEl]);
         const sidebarHeader = h('adw-header-bar', { slot: 'top' }, [
@@ -227,7 +212,6 @@ export class StorybookWebApp implements StorybookView<StoryElement> {
             h('adw-toolbar-view', {}, [sidebarHeader, sidebarScroll]),
         ]);
 
-        // --- Content pane: preview header + (preview | controls) split ---
         this._previewEl = h('div', { class: 'sb-preview-scroll' });
 
         this._controlsGroup = h('adw-preferences-group', { title: 'Controls' });
@@ -249,7 +233,6 @@ export class StorybookWebApp implements StorybookView<StoryElement> {
 
         this._controlsSplit = controlsSplit;
 
-        // Back button — only shown when collapsed, returns to the story list.
         this._backBtn = h('button', {
             class: 'adw-header-btn sb-back-btn',
             slot: 'start',
@@ -279,7 +262,6 @@ export class StorybookWebApp implements StorybookView<StoryElement> {
             h('adw-toolbar-view', {}, [previewHeader, controlsSplit]),
         ]);
 
-        // --- Outer split + window ---
         this._navSplit = h('adw-navigation-split-view', { 'min-sidebar-width': '220', 'max-sidebar-width': '320' }, [
             sidebarPane,
             contentPane,
@@ -289,8 +271,8 @@ export class StorybookWebApp implements StorybookView<StoryElement> {
     }
 
     private _exposeGlobal(): void {
-        // Expose a tiny control surface so the host browser's MCP `eval_js` can
-        // drive stories without an in-page devtools channel.
+        // A control surface for the host browser's MCP `eval_js`, so stories can be
+        // driven without an in-page devtools channel.
         (globalThis as unknown as { __storybook?: unknown }).__storybook = {
             listStories: () => this.listStories(),
             openStory: (title: string) => this.openStoryByTitle(title),

package/src/controls.ts

@@ -1,11 +1,8 @@
-// Control-row builders — render each @gjsify/stories ControlType as an
-// @gjsify/adwaita-web row, wired two-way to a StoryElement's args. The web
-// counterpart of StorybookWindow's _createControlRow family.
-//
-// All the per-kind value coercion (initial-value seeding, SELECT index↔value,
-// RANGE/NUMBER formatting + type guards, the refresh "set only if differs"
-// guard) now lives in @gjsify/storybook-core's bindControl. This file supplies
-// ONLY the adwaita-web leaf-widget factory — the single renderer seam.
+// Renders each `@gjsify/stories` ControlType as an `@gjsify/adwaita-web` row, wired
+// two-way to a StoryElement's args. Per-kind value coercion (initial-value seeding,
+// SELECT index↔value, RANGE/NUMBER formatting + guards, the refresh "set only if
+// differs" guard) belongs to `bindControl` in `@gjsify/storybook-core`; this file
+// supplies ONLY the adwaita-web leaf-widget factory, the single renderer seam.
 
 import type { StoryControl, StoryNumberControl, StorySelectControl } from '@gjsify/stories';
 import {
@@ -25,9 +22,8 @@ export function createControlRow(story: StoryElement, control: StoryControl): Co
 }
 
 /**
- * The @gjsify/adwaita-web leaf-widget factory — builds one `adw-*` (or range/
- * color) element per control kind with get/set/onChange over the DOM events the
- * widgets emit. The only renderer-specific seam; all coercion is in bindControl.
+ * One `adw-*` (or range/color) element per control kind, with get/set/onChange over the
+ * DOM events those widgets emit. The only renderer-specific seam.
  */
 const ADWAITA_WEB_FACTORY: ControlWidgetFactory<HTMLElement> = {
     text(label: string): ControlWidget<HTMLElement, string> {

package/src/index.ts

@@ -1,21 +1,16 @@
-// @gjsify/adwaita-storybook — browser renderer for the @gjsify/stories contract.
-// The web counterpart of @gjsify/storybook: author *.web.ts files as
-// StoryElement subclasses and render them in a generic Adwaita component browser
-// built from @gjsify/adwaita-web, looking and behaving like the native GTK
-// storybook.
+// Browser renderer for the `@gjsify/stories` contract, the web counterpart of
+// `@gjsify/storybook`: `*.web.ts` files author `StoryElement` subclasses, rendered in
+// an Adwaita component browser built from `@gjsify/adwaita-web`.
 //
-// A screenshot harness comparing the renderers is NOT implemented (#1052). What
-// holds their behaviour together is the @gjsify/adwaita-core/conformance vector
-// tables, which both renderer suites assert their real widgets against.
-//
-// A thin DOM adapter over @gjsify/storybook-core — the renderer-agnostic logic
-// (story base, registry, control binding, app controller) lives in core; this
-// package keeps only the @gjsify/adwaita-web view layer.
+// A thin DOM adapter over `@gjsify/storybook-core`, which owns the renderer-agnostic
+// logic (story base, registry, control binding, app controller) — this package is only
+// the view layer. Nothing compares the two renderers by screenshot (#1052); what holds
+// their behaviour together is the `@gjsify/adwaita-core/conformance` vector tables both
+// renderer suites assert their real widgets against.
 
-// Re-export the renderer-agnostic authoring contract so a story only needs one
-// import (`@gjsify/adwaita-storybook`). The web-specific WebStoryModule /
-// WebStoryDecorator (which reference StoryElement) intentionally shadow the
-// generic ones from @gjsify/stories.
+// The authoring contract is re-exported so a story needs one import only. The
+// web-specific WebStoryModule / WebStoryDecorator intentionally shadow the generic
+// ones from `@gjsify/stories`, because they reference `StoryElement`.
 export {
     ControlType,
     argsFromControls,

package/src/registry.ts

@@ -1,8 +1,4 @@
-// StoryRegistry — collects web story modules and instantiates their elements.
-//
-// The registration/instantiation logic (validate, filter, decorator reduceRight
-// fold over initialize()) is renderer-agnostic and now lives in
-// @gjsify/storybook-core. This file just re-exports the generic class; callers
-// type it as `StoryRegistry<StoryElement>`.
+// Re-export of the renderer-agnostic registry; web callers type it as
+// `StoryRegistry<StoryElement>`.
 
 export { StoryRegistry } from '@gjsify/storybook-core';

package/src/story-element.ts

@@ -1,15 +1,9 @@
-// StoryElement — base class for browser story implementations. The web
-// counterpart of @gjsify/storybook's StoryWidget (which extends Adw.Bin): it
-// builds DOM with @gjsify/adwaita-web components instead of GTK widgets, but
-// exposes the same authoring surface (getMetadata, initialize, updateArgs,
-// teardown, addContent, meta/story/args) so a story is a near-1:1 port of its
-// GTK twin. That is a claim about the story SOURCE, which is readable here; that
-// the two then render identically is not measured anywhere (#1052).
+// The web counterpart of `@gjsify/storybook`'s `StoryWidget` (an `Adw.Bin`): same
+// authoring surface, DOM instead of GTK widgets, so a story is a near-1:1 port of its
+// GTK twin in SOURCE. Whether the two then render identically is not measured (#1052).
 //
-// Thin DOM adapter over @gjsify/storybook-core's StoryViewBase: the
-// renderer-agnostic state (meta/story/args, onArgsChanged/setArg, the
-// initialize/updateArgs/teardown/addContent surface) lives in the base; this
-// class supplies ONLY the @gjsify/adwaita-web DOM chrome via createChrome().
+// Thin DOM adapter over `StoryViewBase`, which owns the renderer-agnostic state; this
+// class supplies ONLY the `@gjsify/adwaita-web` DOM chrome, via `createChrome()`.
 
 import type { StoryArgs, StoryMeta } from '@gjsify/stories';
 import { type StoryChrome, StoryViewBase } from '@gjsify/storybook-core';
@@ -20,17 +14,13 @@ export type StoryArgsListener = (args: StoryArgs) => void;
 /**
  * Base class for browser story elements.
  *
- * Provides default chrome — a clamped boxed group with a title + description
- * above a centered, dashed-framed preview stage — built programmatically. Simple
- * stories compose their preview by calling {@link addContent}; a subclass that
- * needs a bespoke layout passes its own root element to the constructor (then
- * {@link addContent} is a no-op).
+ * Provides default chrome — a clamped boxed group with a title + description above a
+ * centered, dashed-framed preview stage. Simple stories compose their preview by
+ * calling {@link addContent}; a subclass needing a bespoke layout passes its own root
+ * element to the constructor, and {@link addContent} is then a no-op.
  */
 export class StoryElement extends StoryViewBase<HTMLElement> {
     /**
-     * @param meta       The story's metadata (the same renderer-agnostic object
-     *                   its GTK twin uses).
-     * @param story      Variant name (defaults to "Default").
      * @param customRoot Opt out of the default chrome by supplying a root element.
      */
     constructor(meta: StoryMeta, story = 'Default', customRoot?: HTMLElement) {
@@ -38,10 +28,7 @@ export class StoryElement extends StoryViewBase<HTMLElement> {
         this.initBase(meta, story, customRoot);
     }
 
-    /**
-     * The root node inserted into the storybook's preview area. Alias for the
-     * base's {@link root} getter — kept because consumers reference `.element`.
-     */
+    /** Alias for the base's {@link root} getter — kept because consumers use `.element`. */
     get element(): HTMLElement {
         return this.root;
     }
@@ -77,9 +64,8 @@ export class StoryElement extends StoryViewBase<HTMLElement> {
         descEl.className = 'sb-story-group-description';
         header.append(titleEl, descEl);
 
-        // Subtle dashed frame so the preview's bounds stay locatable even when
-        // the widget is transparent or in an empty state (mirrors the native
-        // .story-stage in @gjsify/storybook).
+        // Dashed frame so the preview's bounds stay locatable even when the widget is
+        // transparent or empty (mirrors the native `.story-stage`).
         const stage = document.createElement('div');
         stage.className = 'story-stage';
 

package/src/styles.ts

@@ -1,7 +1,6 @@
-// Built-in storybook-web chrome styles, shipped as a string and injected once on
-// mount (mirrors @gjsify/adwaita-web's self-applied stylesheet and the native
-// renderer's STORYBOOK_CSS). Everything is driven by the adwaita-web CSS custom
-// properties so it follows the active light/dark theme.
+// Chrome styles, shipped as a string and injected once on mount (as adwaita-web's own
+// stylesheet and the native renderer's STORYBOOK_CSS are). Driven entirely by the
+// adwaita-web CSS custom properties, so it follows the active light/dark theme.
 
 export const STORYBOOK_WEB_CSS = `
 .sb-window {

package/src/types.ts

@@ -14,11 +14,7 @@ export interface WebStoryConstructor {
 /** Wraps a story's content-build step (e.g. to install a shared environment). */
 export type WebStoryDecorator = (build: () => void, story: StoryElement) => void;
 
-/**
- * A group of related web stories, optionally wrapped by module-level decorators.
- * The DOM binding of {@link StoryModuleLike} over {@link StoryElement} +
- * {@link WebStoryConstructor}.
- */
+/** A group of related web stories, optionally wrapped by module-level decorators. */
 export interface WebStoryModule extends StoryModuleLike<StoryElement, WebStoryConstructor> {
     stories: WebStoryConstructor[];
     /** Populated by {@link StoryRegistry.createStoryInstances}. */