@gjsify/stories 0.7.5

package/README.md

@@ -0,0 +1,38 @@
+# @gjsify/stories
+
+The runtime-agnostic **story-authoring contract** for gjsify's storybook. It defines the vocabulary every renderer shares — control kinds, argument maps, and story metadata — with **zero platform imports**, so the GTK renderer ([`@gjsify/storybook`](../../framework/storybook)) and any future web / NativeScript renderer can consume one set of types.
+
+## Exports
+
+- `ControlType` — `TEXT | NUMBER | BOOLEAN | SELECT | RANGE | COLOR`
+- `StoryControl` — discriminated union (per-kind fields type-checked: `min`/`max`/`step` only on `NUMBER`/`RANGE`, `options` only on `SELECT`)
+- `StoryArgs` / `StoryArgValue` — the live argument map a story renders from
+- `StoryMeta<TComponent>` — `title` (`"Category/Name"`), `description`, `component`, `tags`, `controls`
+- `StoryModule<TWidget>` / `StoryComponentConstructor<TWidget>` — the registration shape a renderer fills with instances
+- `StoryDecorator<TWidget>` — wraps a story's build step
+- `argsFromControls(controls)` — derive initial args from control defaults (defaults spelled once)
+- `isStoryModule(value)` — narrowing guard used by story auto-discovery
+
+## Usage
+
+```ts
+import { ControlType, type StoryControl, argsFromControls } from '@gjsify/stories';
+
+const controls: StoryControl[] = [
+    { name: 'label', label: 'Label', type: ControlType.TEXT, defaultValue: 'Click me' },
+    { name: 'size', label: 'Size', type: ControlType.RANGE, min: 16, max: 96, step: 2, defaultValue: 42 },
+];
+
+const args = argsFromControls(controls); // { label: 'Click me', size: 42 }
+```
+
+You normally do not import this package directly to author a story — you import the **renderer** (`@gjsify/storybook`), which re-exports this contract alongside its `StoryWidget` base class. Import `@gjsify/stories` directly only when writing a new renderer or renderer-agnostic tooling.
+
+## Build / test
+
+```bash
+gjsify workspace @gjsify/stories build
+gjsify workspace @gjsify/stories test
+```
+
+The contract is pure TypeScript with no platform imports, so a future `@gjsify/storybook-web` / `-nativescript` renderer can reuse it. Today the only renderer is `@gjsify/storybook` (GTK), so the package is declared `gjs`-only (it lives on the framework axis); a cross-runtime renderer would bump the `gjsify.runtimes` slots and add a `src/test.browser.mts`.

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/args.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import"./types.js";function argsFromControls(e=[]){let t={};for(let n of e)t[n.name]=defaultFor(n);return t}function defaultFor(e){if(e.defaultValue!==void 0)return e.defaultValue;switch(e.type){case`text`:return``;case`color`:return`#000000`;case`boolean`:return!1;case`number`:case`range`:return e.min??0;case`select`:return e.options[0]?.value??null;default:return null}}export{argsFromControls};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{ControlType as e,isStoryModule as t}from"./types.js";import{argsFromControls as n}from"./args.js";export{e as ControlType,n as argsFromControls,t as isStoryModule};

package/lib/esm/types.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";let e=function(e){return e.TEXT=`text`,e.NUMBER=`number`,e.BOOLEAN=`boolean`,e.SELECT=`select`,e.RANGE=`range`,e.COLOR=`color`,e}({});function isStoryModule(e){return typeof e==`object`&&!!e&&Array.isArray(e.stories)}export{e as ControlType,isStoryModule};

package/lib/types/args.d.ts

@@ -0,0 +1,11 @@
+import { type StoryArgs, type StoryControl } from './types.js';
+/**
+ * Derive the initial {@link StoryArgs} from a control list's `defaultValue`s so
+ * a story spells its defaults once (in `controls`) rather than duplicating them
+ * in a constructor.
+ *
+ * A control without an explicit `defaultValue` falls back to a kind-appropriate
+ * empty value: TEXT → `''`, COLOR → `'#000000'`, BOOLEAN → `false`,
+ * NUMBER/RANGE → `min ?? 0`, SELECT → first option's value (or `null`).
+ */
+export declare function argsFromControls(controls?: StoryControl[]): StoryArgs;

package/lib/types/args.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types.js';
+export * from './args.js';

package/lib/types/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Value type for a single story argument — covers every {@link ControlType}.
+ * `null` represents "not set".
+ */
+export type StoryArgValue = string | number | boolean | null;
+/** Map of story-argument name → current value. */
+export type StoryArgs = Record<string, StoryArgValue>;
+/** Control kinds a story can expose for live editing in the runner. */
+export declare enum ControlType {
+    TEXT = "text",
+    NUMBER = "number",
+    BOOLEAN = "boolean",
+    SELECT = "select",
+    RANGE = "range",
+    COLOR = "color"
+}
+/** A single choice in a {@link ControlType.SELECT} control. */
+export interface StorySelectOption {
+    label: string;
+    value: StoryArgValue;
+}
+interface StoryControlBase {
+    /** Argument key this control drives (matches a key in {@link StoryArgs}). */
+    name: string;
+    /** Human-readable label shown beside the control. */
+    label: string;
+    /** Optional help / tooltip text. */
+    description?: string;
+}
+/** Free-text control. */
+export interface StoryTextControl extends StoryControlBase {
+    type: ControlType.TEXT;
+    defaultValue?: string;
+}
+/** Color picker — `defaultValue` is a `#rrggbb` hex string. */
+export interface StoryColorControl extends StoryControlBase {
+    type: ControlType.COLOR;
+    defaultValue?: string;
+}
+/** Toggle control. */
+export interface StoryBooleanControl extends StoryControlBase {
+    type: ControlType.BOOLEAN;
+    defaultValue?: boolean;
+}
+/** Numeric spinner ({@link ControlType.NUMBER}) or slider ({@link ControlType.RANGE}). */
+export interface StoryNumberControl extends StoryControlBase {
+    type: ControlType.NUMBER | ControlType.RANGE;
+    min?: number;
+    max?: number;
+    step?: number;
+    defaultValue?: number;
+}
+/** Single-choice dropdown. */
+export interface StorySelectControl extends StoryControlBase {
+    type: ControlType.SELECT;
+    options: StorySelectOption[];
+    defaultValue?: StoryArgValue;
+}
+/**
+ * A control descriptor — a discriminated union on `type` so per-kind fields are
+ * compile-time-checked (`min`/`max`/`step` only on NUMBER/RANGE, `options` only
+ * on SELECT).
+ */
+export type StoryControl = StoryTextControl | StoryColorControl | StoryBooleanControl | StoryNumberControl | StorySelectControl;
+/**
+ * Metadata describing one story (or a group of variants of one component).
+ *
+ * `TComponent` defaults to `unknown` to keep this contract platform-free — the
+ * GTK renderer passes a `GObject.GType`, a future web renderer might pass a tag
+ * name. It is display-only.
+ */
+export interface StoryMeta<TComponent = unknown> {
+    /** `"Category/Name"` — the slash-prefix groups the navigation sidebar. */
+    title: string;
+    /** What the story demonstrates. */
+    description?: string;
+    /** The component under test — a renderer-specific handle, display only. */
+    component?: TComponent;
+    /** Free-form tags (`'autodocs'` is reserved for generated docs). */
+    tags?: string[];
+    /** Editable controls that drive this story's {@link StoryArgs}. */
+    controls?: StoryControl[];
+}
+/**
+ * A renderer's story-widget contract: a zero-arg constructor that also exposes
+ * static metadata. Each renderer specializes `TWidget` with its own base class
+ * (the GTK renderer's `StoryWidget`, a future web renderer's element).
+ */
+export interface StoryComponentConstructor<TWidget = unknown> {
+    new (): TWidget;
+    getMetadata(): StoryMeta;
+}
+/**
+ * A group of related story constructors. `instances` is populated by a renderer
+ * registry once the widgets are constructed.
+ */
+export interface StoryModule<TWidget = unknown> {
+    stories: StoryComponentConstructor<TWidget>[];
+    instances?: TWidget[];
+}
+/**
+ * Wraps a story's content-build step — e.g. to install a shared action group or
+ * a mock environment around every story in a module. Runs in the renderer's
+ * initialize path: call `build()` to perform the default construction.
+ */
+export type StoryDecorator<TWidget = unknown> = (build: () => void, widget: TWidget) => void;
+/** Narrowing guard — `true` when `value` is a {@link StoryModule}. */
+export declare function isStoryModule(value: unknown): value is StoryModule;
+export {};

package/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "@gjsify/stories",
+    "version": "0.7.5",
+    "description": "Runtime-agnostic story-authoring contract (controls, args, metadata) shared by every gjsify storybook renderer",
+    "type": "module",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib"
+    ],
+    "scripts": {
+        "clear": "rm -rf lib tmp tsconfig.tsbuildinfo test.gjs.mjs || exit 0",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "storybook",
+        "stories",
+        "gtk",
+        "adwaita"
+    ],
+    "dependencies": {},
+    "devDependencies": {
+        "@gjsify/cli": "^0.7.5",
+        "@gjsify/unit": "^0.7.5",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        }
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/framework/stories"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/framework/stories#readme"
+}