forgebook 0.1.8 → 0.3.0

package/dist/src/codeLiteral.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Values written into generated code: a Vite module the plugin or an adapter generates, a `define` value, the code a
+ * transform inserts, or a script set inline in a page. Exported as `forgebook/code-literal`, so every adapter writes
+ * them the same way.
+ *
+ * @remarks
+ * `JSON.stringify` alone writes a valid JavaScript literal, but not one safe everywhere code goes: inside an inline
+ * `<script>`, a string holding `</script>` or `<!--` ends or changes the script, and before ES2019 a raw U+2028 or
+ * U+2029 ended a string literal. The literal written here escapes `<`, `>` and `/` and both separators, so it reads
+ * back as the same value in a module, in an inline script and in an older parser alike, wherever a generator places
+ * it. Each is written as a Unicode escape, never as a backslash before the character, so no escape depends on how the
+ * text's backslashes were escaped. The escapes only ever fall inside string literals: JSON writes those characters
+ * nowhere else. Each is a pass
+ * of its own, a native replacement as fast on a large document as one pass with a callback, and the form code
+ * scanners read as escaping.
+ *
+ * Imports nothing, so the shell (an embed's code), the plugin on Node and the adapters can all use it.
+ *
+ * @module
+ */
+/**
+ * JSON text as code: the same value, with `<`, `>`, `/`, U+2028 and U+2029 escaped. For JSON a caller already holds
+ * (a document also written to a file); otherwise `codeLiteral`. Only for JSON text: JSON writes those characters
+ * nowhere but inside strings, where their escapes read the same, while in other code (`a / b`, `x < y`) they would
+ * change it.
+ *
+ * @param json - the JSON text, as `JSON.stringify` writes it.
+ * @returns the text as a JavaScript expression of the same value.
+ */
+export declare const codeOfJson: (json: string) => string;
+/**
+ * A value as a JavaScript literal for generated code: `JSON.stringify` with the characters that could end a script
+ * or a string escaped (`codeOfJson`).
+ *
+ * @param value - a value JSON can write: a string, number, boolean, null, or an array or object of them.
+ * @returns the literal, which evaluates to an equal value.
+ * @throws `TypeError` when JSON writes nothing for the value (`undefined`, a function, a symbol), which would leave a
+ *   hole in the code, and for a `bigint`, which JSON cannot write. As in JSON, a key whose value is `undefined` is left
+ *   out and `NaN` is written `null`.
+ */
+export declare const codeLiteral: (value: unknown) => string;

package/dist/src/codeLiteral.js

@@ -0,0 +1,51 @@
+/**
+ * Values written into generated code: a Vite module the plugin or an adapter generates, a `define` value, the code a
+ * transform inserts, or a script set inline in a page. Exported as `forgebook/code-literal`, so every adapter writes
+ * them the same way.
+ *
+ * @remarks
+ * `JSON.stringify` alone writes a valid JavaScript literal, but not one safe everywhere code goes: inside an inline
+ * `<script>`, a string holding `</script>` or `<!--` ends or changes the script, and before ES2019 a raw U+2028 or
+ * U+2029 ended a string literal. The literal written here escapes `<`, `>` and `/` and both separators, so it reads
+ * back as the same value in a module, in an inline script and in an older parser alike, wherever a generator places
+ * it. Each is written as a Unicode escape, never as a backslash before the character, so no escape depends on how the
+ * text's backslashes were escaped. The escapes only ever fall inside string literals: JSON writes those characters
+ * nowhere else. Each is a pass
+ * of its own, a native replacement as fast on a large document as one pass with a callback, and the form code
+ * scanners read as escaping.
+ *
+ * Imports nothing, so the shell (an embed's code), the plugin on Node and the adapters can all use it.
+ *
+ * @module
+ */
+/**
+ * JSON text as code: the same value, with `<`, `>`, `/`, U+2028 and U+2029 escaped. For JSON a caller already holds
+ * (a document also written to a file); otherwise `codeLiteral`. Only for JSON text: JSON writes those characters
+ * nowhere but inside strings, where their escapes read the same, while in other code (`a / b`, `x < y`) they would
+ * change it.
+ *
+ * @param json - the JSON text, as `JSON.stringify` writes it.
+ * @returns the text as a JavaScript expression of the same value.
+ */
+export const codeOfJson = (json) => json
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/\//g, "\\u002f")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+/**
+ * A value as a JavaScript literal for generated code: `JSON.stringify` with the characters that could end a script
+ * or a string escaped (`codeOfJson`).
+ *
+ * @param value - a value JSON can write: a string, number, boolean, null, or an array or object of them.
+ * @returns the literal, which evaluates to an equal value.
+ * @throws `TypeError` when JSON writes nothing for the value (`undefined`, a function, a symbol), which would leave a
+ *   hole in the code, and for a `bigint`, which JSON cannot write. As in JSON, a key whose value is `undefined` is left
+ *   out and `NaN` is written `null`.
+ */
+export const codeLiteral = (value) => {
+    const json = JSON.stringify(value);
+    if (typeof json !== "string")
+        throw new TypeError(`A ${typeof value} has no literal in generated code`);
+    return codeOfJson(json);
+};

package/dist/src/componentDocs.d.ts

@@ -50,6 +50,22 @@ export type FunctionSignatureDocs = {
     /** Its `@returns` text; empty when it has none. */
     readonly returnsDescription: string;
 };
+/**
+ * One member of a prop's object type (a `texts` prop's `FileFinderTexts`), listed under the prop in the API
+ * reference.
+ */
+export type MemberDocs = {
+    /** The member's name. */
+    readonly name: string;
+    /** Its type as the source writes it, without `undefined` and `null`. */
+    readonly type: string;
+    /** The first paragraph of its TSDoc; empty when it has none. */
+    readonly description: string;
+    /** Its `@defaultValue`, when the TSDoc gives one. */
+    readonly defaultValue?: string;
+    /** Whether the member must be given. */
+    readonly isRequired: boolean;
+};
 /** One prop of a component. */
 export type PropDocs = {
     /** The prop's name. */
@@ -77,6 +93,16 @@ export type PropDocs = {
      * field for it. Left out when `false`.
      */
     readonly canTakeText?: boolean;
+    /**
+     * The group its TSDoc puts it in (`@group Selection`): the API reference and the Props tab list it under that
+     * heading. Left out when it names none.
+     */
+    readonly group?: string;
+    /**
+     * The members of its type, when that type is an object the package declares and documents (`texts?: FileFinderTexts`),
+     * in the order the source declares them: the API reference lists them under the prop, folded. Left out otherwise.
+     */
+    readonly members?: readonly MemberDocs[];
 };
 /** A part the component is used with, named in the meta's `subcomponents`: listed under it on its page. */
 export type SubcomponentDocs = {
@@ -87,6 +113,22 @@ export type SubcomponentDocs = {
     /** Its props declared in the package, in the same order as the component's. */
     readonly props: readonly PropDocs[];
 };
+/**
+ * When to use a component and when not, as its TSDoc says: the rule a person knows and an agent has no way to guess.
+ * Tags: `@useWhen`, `@avoidWhen`, `@alternatives`, `@deprecated`, `@replacedBy`.
+ */
+export type UsageGuidance = {
+    /** The situations it is for, one per `@useWhen`. */
+    readonly useWhen?: readonly string[];
+    /** The situations it is not for, one per `@avoidWhen`. */
+    readonly avoidWhen?: readonly string[];
+    /** Components to consider instead, from `@alternatives`, comma-separated. */
+    readonly alternatives?: readonly string[];
+    /** Why not to use it any more, from `@deprecated`. */
+    readonly deprecated?: string;
+    /** What to use instead, from `@replacedBy`. */
+    readonly replacedBy?: string;
+};
 /** A story file's component. */
 export type ComponentDocs = {
     /** The component's name. */
@@ -107,12 +149,27 @@ export type ComponentDocs = {
     readonly parts: readonly string[];
     /** The parts the meta names in `subcomponents`, in the order it writes them; empty when it names none. */
     readonly subcomponents: readonly SubcomponentDocs[];
+    /** When to use it and when not, from its TSDoc; left out when it says nothing. */
+    readonly guidance?: UsageGuidance;
     /**
      * Its call signature, when it has one: the parameters and the return value a story about logic shows first (the
      * meta's `component` is then the hook or the function).
      */
     readonly signature?: FunctionSignatureDocs;
+    /**
+     * The CSS selector a template writes the component with, for a framework whose components are matched by one rather
+     * than named (an Angular component's `fb-badge`, a directive's `button[fbButton]`): the code writer writes the story's
+     * markup from it. Left out when the component is written by its name.
+     */
+    readonly selector?: string;
 };
+/**
+ * The name a story's code writes the component with: its selector when its framework matches components by one, its
+ * name otherwise.
+ *
+ * @param docs - the component's docs.
+ */
+export declare const codeNameOf: (docs: ComponentDocs) => string;
 /** What the plugin answers for a story file whose meta names no component (a foundations page). */
 export type NoComponentDocs = {
     /** No component. */
@@ -124,4 +181,3 @@ export type NoComponentDocs = {
  * @param value - the module's default export.
  */
 export declare const isComponentDocs: (value: unknown) => value is ComponentDocs;
-//# sourceMappingURL=componentDocs.d.ts.map

package/dist/src/componentDocs.js

@@ -10,12 +10,26 @@
  *
  * @module
  */
+/**
+ * The name a story's code writes the component with: its selector when its framework matches components by one, its
+ * name otherwise.
+ *
+ * @param docs - the component's docs.
+ */
+export const codeNameOf = (docs) => docs.selector ?? docs.name;
 /** Whether a value is a plain object. */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** Whether a value is a list of strings. */
 const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
 /** The prop kinds, for the check. */
 const PROP_KINDS = ["choice", "text", "number", "toggle", "event", "other"];
+/** Whether a value is one member's docs. */
+const isMemberDocs = (value) => isRecord(value) &&
+    typeof value["name"] === "string" &&
+    typeof value["type"] === "string" &&
+    typeof value["description"] === "string" &&
+    typeof value["isRequired"] === "boolean" &&
+    (value["defaultValue"] === undefined || typeof value["defaultValue"] === "string");
 /** Whether a value is one prop's docs. */
 const isPropDocs = (value) => isRecord(value) &&
     typeof value["name"] === "string" &&
@@ -23,7 +37,10 @@ const isPropDocs = (value) => isRecord(value) &&
     typeof value["type"] === "string" &&
     typeof value["description"] === "string" &&
     typeof value["isRequired"] === "boolean" &&
-    (value["canTakeText"] === undefined || typeof value["canTakeText"] === "boolean");
+    (value["canTakeText"] === undefined || typeof value["canTakeText"] === "boolean") &&
+    (value["group"] === undefined || typeof value["group"] === "string") &&
+    (value["members"] === undefined ||
+        (Array.isArray(value["members"]) && value["members"].every(isMemberDocs)));
 /** Whether a value is a subcomponent's docs. */
 const isSubcomponentDocs = (value) => isRecord(value) &&
     typeof value["name"] === "string" &&
@@ -56,5 +73,5 @@ export const isComponentDocs = (value) => isRecord(value) &&
     isStringList(value["parts"]) &&
     Array.isArray(value["subcomponents"]) &&
     value["subcomponents"].every(isSubcomponentDocs) &&
-    (value["signature"] === undefined || isFunctionSignatureDocs(value["signature"]));
-//# sourceMappingURL=componentDocs.js.map
+    (value["signature"] === undefined || isFunctionSignatureDocs(value["signature"])) &&
+    (value["selector"] === undefined || typeof value["selector"] === "string");

package/dist/src/controlKeys.d.ts

@@ -82,4 +82,3 @@ export declare const cycledValue: <TValue>(values: readonly TValue[], current: T
  * @param each - the switch.
  */
 export declare const switchValues: (each: ViewSwitch) => string[];
-//# sourceMappingURL=controlKeys.d.ts.map

package/dist/src/controlKeys.js

@@ -120,4 +120,3 @@ export const cycledValue = (values, current, step) => {
  * @param each - the switch.
  */
 export const switchValues = (each) => each.values.map((value) => value.value);
-//# sourceMappingURL=controlKeys.js.map

package/dist/src/deviceDrawing.d.ts

@@ -0,0 +1,114 @@
+/**
+ * A device's drawing: the hardware around the screen (its band, its bezel, its buttons) and what sits over the story
+ * (the camera's cut, the status bar, the home indicator), as shapes in CSS px, for the shell's frame and for
+ * `forgebook shot`'s framed pictures to draw the same device.
+ *
+ * @remarks
+ * Shapes and not markup, so each side draws them its own way (React elements in the shell, an SVG text in the
+ * pictures) from one geometry. The hardware is laid out upright and turned with its top to the left for landscape,
+ * as a phone is turned; the status bar is laid out for the screen as held, since a system lays it out again when
+ * the phone turns (an iPhone on its side shows none). The paints are named, not coloured: the frame takes the
+ * shell's appearance, the status bar's ink the story's scheme, as a phone's status bar follows the app under it.
+ * Pure.
+ *
+ * @module
+ */
+import type { DeviceOrientation } from "@forgebook/story-format/csf";
+import { type DeviceModel } from "./devices.ts";
+/** What a shape is painted with: the hardware's band, its outline, the bezel, the camera's cut, the status bar's ink. */
+export type DevicePaint = "frame" | "edge" | "bezel" | "cutout" | "ink";
+/** One shape of a drawing, in CSS px. */
+export type DeviceShape = {
+    /** A rectangle, its corners rounded. */
+    readonly kind: "rect";
+    /** Its left. */
+    readonly x: number;
+    /** Its top. */
+    readonly y: number;
+    /** Its width. */
+    readonly width: number;
+    /** Its height. */
+    readonly height: number;
+    /** Its corners' radius. */
+    readonly radius: number;
+    /** Its fill; none for an outline only. */
+    readonly fill?: DevicePaint;
+    /** Its outline, 1 px wide; none by default. */
+    readonly stroke?: DevicePaint;
+    /** Its opacity, from 0 to 1; 1 by default. */
+    readonly opacity?: number;
+} | {
+    /** A disc. */
+    readonly kind: "circle";
+    /** Its centre's left. */
+    readonly cx: number;
+    /** Its centre's top. */
+    readonly cy: number;
+    /** Its radius. */
+    readonly r: number;
+    /** Its fill. */
+    readonly fill: DevicePaint;
+} | {
+    /** A path, in SVG's path syntax. */
+    readonly kind: "path";
+    /** Its commands. */
+    readonly d: string;
+    /** Its fill. */
+    readonly fill: DevicePaint;
+} | {
+    /** A line of text, centred on its height. */
+    readonly kind: "text";
+    /** Where it starts, or its middle. */
+    readonly x: number;
+    /** Its middle's height. */
+    readonly y: number;
+    /** What it says. */
+    readonly text: string;
+    /** Its size, in CSS px. */
+    readonly size: number;
+    /** Its weight. */
+    readonly weight: number;
+    /** Whether `x` is its start or its middle. */
+    readonly anchor: "start" | "middle";
+    /** Its fill. */
+    readonly fill: DevicePaint;
+};
+/** A rectangle, its corners rounded, in CSS px. */
+export type DeviceRect = {
+    /** Its left. */
+    readonly x: number;
+    /** Its top. */
+    readonly y: number;
+    /** Its width. */
+    readonly width: number;
+    /** Its height. */
+    readonly height: number;
+    /** Its corners' radius. */
+    readonly radius: number;
+};
+/** A device drawn: its size, where its screen is, and its shapes under and over the screen. */
+export type DeviceDrawing = {
+    /** The drawing's width, the buttons included, in CSS px. */
+    readonly width: number;
+    /** The drawing's height, in CSS px. */
+    readonly height: number;
+    /** The screen, where the story goes: its viewport's size, at its place in the drawing. */
+    readonly screen: DeviceRect;
+    /** Drawn under the screen: the buttons, the band and the bezel. */
+    readonly under: readonly DeviceShape[];
+    /** Drawn over the story, never taking the pointer: the camera's cut, the status bar, the home indicator. */
+    readonly over: readonly DeviceShape[];
+};
+/** The paints of the hardware in each of the shell's appearances: quiet greys, a black bezel, as phones are. */
+export declare const DEVICE_PAINTS: Readonly<Record<"light" | "dark", Readonly<Record<Exclude<DevicePaint, "ink">, string>>>>;
+/** The status bar's ink over a story of each scheme: dark on a light story, light on a dark one. */
+export declare const DEVICE_INK: Readonly<Record<"light" | "dark", string>>;
+/** The status bar's font: the system's, as the devices' own. */
+export declare const DEVICE_FONT = "-apple-system, BlinkMacSystemFont, \"SF Pro Text\", Roboto, system-ui, sans-serif";
+/**
+ * A model drawn, held one way.
+ *
+ * @param model - the model.
+ * @param orientation - how it is held: on its side, its top to the left.
+ */
+export declare const deviceDrawing: (model: DeviceModel, orientation: DeviceOrientation) => DeviceDrawing;