forgebook 0.3.3 → 0.4.1

package/dist/src/valueShape.js

@@ -0,0 +1,25 @@
+/**
+ * Whether the panel can give a shape a value at all: a required part the source names no value for leaves it no way.
+ *
+ * @param shape - the shape.
+ * @param namedValues - the source's named values.
+ */
+export const canSetShape = (shape, namedValues) => {
+    switch (shape.kind) {
+        case "named":
+            return (shape.canTakeText === true ||
+                (Object.hasOwn(namedValues, shape.type) && Object.keys(namedValues[shape.type] ?? {}).length > 0));
+        case "list":
+            return canSetShape(shape.of, namedValues);
+        case "record":
+            return canSetShape(shape.of, namedValues);
+        case "tuple":
+            return shape.items.every((item) => canSetShape(item, namedValues));
+        case "object":
+            return shape.fields.every((field) => !field.isRequired || canSetShape(field.shape, namedValues));
+        case "union":
+            return shape.of.some((member) => canSetShape(member, namedValues));
+        default:
+            return true;
+    }
+};

package/dist/src/viewState.d.ts

@@ -13,7 +13,7 @@
  * @module
  */
 import { type AudienceId } from "./audiences.ts";
-import type { CatalogueSettings } from "./catalogue.ts";
+import type { CatalogueSettings, PlaySwitch } from "./catalogue.ts";
 import { type DeviceChoice, type OrientationChoice } from "./deviceView.ts";
 import { type TouchChoice, type ViewSwitch } from "./switches.ts";
 /**
@@ -78,6 +78,11 @@ export type ViewState = {
     readonly device: DeviceChoice;
     /** How the device is held: the story's own default (`auto`), or one way. */
     readonly orientation: OrientationChoice;
+    /**
+     * Whether a story's play function runs when its frame opens. A frame's address says only `off`: one with no word plays,
+     * so a test, a check or a tool that opens a frame runs its story's play whatever a reader chose.
+     */
+    readonly play: PlaySwitch;
 };
 /** The part of the view a frame applies on its root without loading again, so the story keeps its state. */
 export type LiveView = Pick<ViewState, "switches" | "backdrop" | "text">;
@@ -94,7 +99,7 @@ export declare const isComparing: (view: ViewState) => boolean;
 /** Every tool, in the bar's order. */
 export declare const MEASURE_TOOLS: readonly MeasureTool[];
 /** What the view reads of a catalogue: its switches and the lists its values are checked against. */
-export type ViewCatalogue = Pick<CatalogueSettings, "switches" | "widthRange" | "zooms" | "textSizes" | "backdrops" | "tabs" | "ownControls" | "audience">;
+export type ViewCatalogue = Pick<CatalogueSettings, "switches" | "widthRange" | "zooms" | "textSizes" | "backdrops" | "tabs" | "ownControls" | "audience" | "readerPlay">;
 /**
  * A width kept in a catalogue's range, in whole pixels.
  *
@@ -135,7 +140,7 @@ export declare const defaultView: (catalogue: ViewCatalogue) => ViewState;
  * with another, or the link would open that one.
  * @returns the parameters, in a stable order.
  */
-export declare const viewParams: (view: ViewState, switches: readonly ViewSwitch[], defaultAudience?: AudienceId) => URLSearchParams;
+export declare const viewParams: (view: ViewState, switches: readonly ViewSwitch[], defaultAudience?: AudienceId, defaultPlay?: PlaySwitch) => URLSearchParams;
 /**
  * Whether one of the given controls' values is changed (a switch, the background, the style sheets, the text size;
  * the stage's width is not a view setting): the View menu's button shows a dot for the controls it holds, so a view

package/dist/src/viewState.js

@@ -14,11 +14,13 @@
  */
 import { AUDIENCE_IDS, DEFAULT_AUDIENCE } from "./audiences.js";
 import { DEVICE_PARAMETER, isDeviceId, isDeviceOrientation, ORIENTATION_PARAMETER } from "./deviceView.js";
-import { switchValueOf, switchWithRole } from "./switches.js";
+import { shownSwitches, switchValueOf, switchWithRole } from "./switches.js";
 /** The page's own colour: no backdrop drawn. */
 export const PLAIN_BACKDROP = "plain";
 /** Forgebook's own settings the compare view can set side by side. */
 export const OWN_COMPARE_AXES = ["text", "sheets"];
+/** The values of the play switch. */
+const PLAY_SWITCHES = ["on", "off"];
 /** The view without any change. */
 export const DEFAULT_VIEW = {
     switches: {},
@@ -34,7 +36,8 @@ export const DEFAULT_VIEW = {
     tools: [],
     audience: DEFAULT_AUDIENCE,
     device: "auto",
-    orientation: "auto"
+    orientation: "auto",
+    play: "on"
 };
 /** Every style sheet setting, in the menu's order. */
 export const SHEETS_CHOICES = ["full", "structure", "restyled"];
@@ -142,7 +145,8 @@ export const parseView = (search, catalogue) => {
         tools: toolsOf(params.get("tools")),
         audience: choice(shown("audience"), AUDIENCE_IDS, catalogue.audience),
         device: deviceChoice(params.get(DEVICE_PARAMETER)),
-        orientation: orientationChoice(params.get(ORIENTATION_PARAMETER))
+        orientation: orientationChoice(params.get(ORIENTATION_PARAMETER)),
+        play: choice(params.get("play"), PLAY_SWITCHES, catalogue.readerPlay)
     };
 };
 /**
@@ -180,6 +184,8 @@ const frameParams = (view, switches) => {
         params.set("text", String(view.text));
     if (language !== undefined)
         setSwitch(language);
+    if (view.play === "off")
+        params.set("play", "off");
     return params;
 };
 /**
@@ -191,8 +197,13 @@ const frameParams = (view, switches) => {
  * with another, or the link would open that one.
  * @returns the parameters, in a stable order.
  */
-export const viewParams = (view, switches, defaultAudience = DEFAULT_AUDIENCE) => {
+export const viewParams = (view, switches, defaultAudience = DEFAULT_AUDIENCE, defaultPlay = DEFAULT_VIEW.play) => {
     const params = frameParams(view, switches);
+    // the address says only what differs from the catalogue's default; the frames still hear `off`
+    if (view.play === defaultPlay)
+        params.delete("play");
+    else
+        params.set("play", view.play);
     if (isComparing(view))
         params.set("compare", view.compare.join(","));
     if (view.width !== DEFAULT_VIEW.width)
@@ -278,7 +289,7 @@ export const schemeOf = (view, switches) => {
     const scheme = switchWithRole(switches, "colorScheme");
     if (scheme === undefined)
         return "light";
-    return switchValueOf(scheme, view.switches[scheme.id])?.scheme ?? "light";
+    return switchValueOf(scheme, shownSwitches(view.switches, switches)[scheme.id])?.scheme ?? "light";
 };
 /**
  * Whether a view draws in the higher contrast: its contrast switch's value says so; never without one.
@@ -290,7 +301,7 @@ export const isMoreContrastOf = (view, switches) => {
     const contrast = switchWithRole(switches, "contrast");
     if (contrast === undefined)
         return false;
-    return switchValueOf(contrast, view.switches[contrast.id])?.isMore === true;
+    return switchValueOf(contrast, shownSwitches(view.switches, switches)[contrast.id])?.isMore === true;
 };
 /**
  * The language a view shows: the language switch's value, empty for the stories' own text.
@@ -300,7 +311,9 @@ export const isMoreContrastOf = (view, switches) => {
  */
 export const languageOf = (view, switches) => {
     const language = switchWithRole(switches, "language");
-    return language === undefined ? "" : (view.switches[language.id] ?? language.default);
+    return language === undefined
+        ? ""
+        : (shownSwitches(view.switches, switches)[language.id] ?? language.default);
 };
 /**
  * Whether a view simulates a finger.
@@ -341,11 +354,15 @@ export const withTouchOf = (view, from, choice) => {
  * @param view - the view's switches.
  * @param switches - the catalogue's switches.
  */
-export const codeGlobalsOf = (view, switches) => Object.fromEntries(switches
-    .filter((each) => each.apply.kind === "code" || each.role === "touch")
-    .map((each) => [each.id, view.switches[each.id] ?? each.default]));
+export const codeGlobalsOf = (view, switches) => {
+    const shown = shownSwitches(view.switches, switches);
+    return Object.fromEntries(switches
+        .filter((each) => each.apply.kind === "code" || each.role === "touch")
+        .map((each) => [each.id, shown[each.id] ?? each.default]));
+};
 /** The parameters only the shell reads: a frame's address leaves them out. */
 const SHELL_PARAMETERS = [
+    "tag",
     "compare",
     "width",
     "height",

package/dist/src/vite/adapter.d.ts

@@ -24,6 +24,8 @@ export type StoryComponent = {
      * can renew the docs.
      */
     readonly sources: readonly string[];
+    /** Whether its file exports it as its default, which an import then writes without braces; read for `forgebook new`. */
+    readonly isDefaultExport?: boolean;
 };
 /** What a framework reads of a story file: its component, `{ docs: { name: null } }` without one, or why it cannot. */
 export type StoryComponentResult = StoryComponent | {
@@ -35,6 +37,11 @@ export type StoryComponentResult = StoryComponent | {
  * @param storyFile - the story file's absolute path.
  */
 export type ExtractStoryComponent = (storyFile: string) => StoryComponentResult;
+/** What a catalogue tells an adapter of how much of the app's build it reads. */
+export type AdapterContext = {
+    /** Whether it reads the app's build at all: `false` with `appBuild: false`, when no project code of it may run. */
+    readonly readsAppBuild: boolean;
+};
 /** A framework, as the plugin uses it. */
 export type FrameworkAdapter = {
     /** The framework's name, as `forgebook-docs --framework` writes it (`react`). */
@@ -57,8 +64,12 @@ export type FrameworkAdapter = {
      * opens, since Vite's scanner cannot read pages that are generated; none by default.
      */
     readonly browserDependencies?: readonly string[];
-    /** The Vite plugins the framework needs in a catalogue (React's Fast Refresh); none by default. */
-    readonly vitePlugins?: () => Promise<readonly PluginOption[]>;
+    /**
+     * The Vite plugins the framework needs in a catalogue (React's Fast Refresh); none by default. Given what the catalogue
+     * reads of the app's build, for an adapter that reads more of it (Nuxt's modules); called with nothing by an older
+     * core.
+     */
+    readonly vitePlugins?: (context?: AdapterContext) => Promise<readonly PluginOption[]>;
     /** The framework's own kind of component file, for a framework whose components are not all TypeScript; none by default. */
     readonly componentFiles?: ComponentFiles;
     /**
@@ -73,6 +84,13 @@ export type FrameworkAdapter = {
      * program and leaves out the code Vite's plugins add to it (Angular's): an edit of its story files reloads the pages.
      */
     readonly redrawsEditedStories?: boolean;
+    /**
+     * Whether Forgebook compiles the JSX of the project's `.js` files with Vite's JSX options (`jsxInScripts.ts`), as
+     * Storybook's webpack builder lets a library write it: `true` for a framework whose JSX Vite's compiler writes
+     * (React's, Preact's). `false` by default: for one whose JSX is another compiler's (Solid's), or whose plugins compile
+     * such files themselves (React Native Web's, with Flow types).
+     */
+    readonly compilesJsxInScripts?: boolean;
 };
 /**
  * A framework's own kind of component file (Vue's `.vue`): what the plugin must know of a file that is not TypeScript,
@@ -98,12 +116,32 @@ export type StoryFileShape = {
 };
 /** Reads the component a file exports (`forgebook new`): the export named, or the file's only component. */
 export type ExtractFileComponent = (file: string, exportName?: string) => StoryComponentResult;
+/**
+ * One place the application draws a component, as `forgebook new` reads it: the props it gives with a value code can
+ * hold as it is (a literal, or a list or an object of literals), each written as source code.
+ */
+export type CallSite = {
+    /** The file that draws it, absolute. */
+    readonly file: string;
+    /** Each prop given a literal value, by name, as code (`"danger"`, `3`, `true`, `["a", "b"]`). */
+    readonly args: Readonly<Record<string, string>>;
+};
+/**
+ * Finds where an application draws a component.
+ *
+ * @param file - the component's file, absolute.
+ * @param name - the name the component is exported by (`default` for a default export).
+ * @returns the call sites, in the order of their files; a message when they cannot be read.
+ */
+export type ExtractCallSites = (file: string, name: string) => readonly CallSite[] | string;
 /** A framework's docs module, as the plugin and the commands load it. */
 export type DocsModule = {
     /** Reads a story file's component. */
     readonly extractStoryComponent: ExtractStoryComponent;
     /** Reads a component a file exports; none in a framework package that does not offer it yet. */
     readonly extractFileComponent?: ExtractFileComponent;
+    /** Finds where the application draws a component, for the values `forgebook new` writes; none when not offered. */
+    readonly extractCallSites?: ExtractCallSites;
     /** The module a story file imports its types from (`@forgebook/react`); none when not given. */
     readonly storyTypesModule?: string;
     /**

package/dist/src/vite/adapter.js

@@ -21,6 +21,7 @@ export const isDocsModule = (module) => typeof module === "object" &&
     "extractStoryComponent" in module &&
     typeof module.extractStoryComponent === "function" &&
     (!("extractFileComponent" in module) || typeof module.extractFileComponent === "function") &&
+    (!("extractCallSites" in module) || typeof module.extractCallSites === "function") &&
     (!("storyTypesModule" in module) || typeof module.storyTypesModule === "string") &&
     (!("storyFileShape" in module) || typeof module.storyFileShape === "function") &&
     (!("sourcesChanged" in module) || typeof module.sourcesChanged === "function");