@cssints/stories 0.0.0-stage → 0.28.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Accio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# @cssints/stories
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The CSF 3 loader of a cssints storybook: the modules an app globs in, the entries with the ids Storybook builds out, and
+the controls a story declares.
+
+```ts
+// src/registry/button/button.stories.tsx — a Storybook CSF 3 file, unchanged
+import type { Meta, Story } from "@cssints/stories";
+import { Button, type ButtonProps } from "./button.tsx";
+
+const meta = {
+  title: "Button",
+  component: Button,
+  args: { children: "Save", tone: "neutral" },
+  argTypes: {
+    tone: { type: "select", options: ["neutral", "accent", "quiet"] },
+    disabled: { type: "boolean" },
+  },
+} satisfies Meta<ButtonProps>;
+export default meta;
+
+export const Default: Story<ButtonProps> = {};
+export const Publish: Story<ButtonProps> = { args: { tone: "accent", children: "Publish" } };
+```
+
+```ts
+// the app
+import { entries, parseHash, storyOfId, type Module } from "@cssints/stories";
+
+const modules = import.meta.glob<Module>("../registry/*/*.stories.tsx", { eager: true });
+export const stories = entries(modules); // [{ id: "button--default", item: "button", view, args, argTypes, … }]
+
+parseHash("#button--publish"); // { name: "button", story: "button--publish" }
+```
+
+## What it decides, and what it leaves to the app
+
+- **The id.** `button--publish`, the item's name and the story's, kebab-cased — what Storybook builds, so a story file
+  moves either way. Within a file the order is the module namespace's, alphabetical, which is Storybook's default.
+- **The args.** The meta's, the story's over them. A control in the host writes an arg and re-renders the view; the loader
+  does not care how.
+- **The controls.** `argTypes` is the model (`boolean`, `select` with `options`, `text`, `number`, `range` with
+  `min`/`max`/`step`). Storybook infers a control from a component's props; a Solid component carries none at run time, so
+  a story declares what it wants by hand. The panel is the app's: a row per declared arg.
+- **Nothing else.** No DOM, no styles, no routing: the chrome (a rail, a tablist, a native window) is the app's, and so is
+  the renderer — `entries<Node>()` returns views of whatever the app renders, so the same loader serves the web site, the
+  lab and cssints-native.
+
+## Tests
+
+`bun run test` — `test/stories.mjs` on the loader alone: ids, the arg merge, the exports it skips, the order, a component
+view through `createComponent` and a render view, and the hash split.

package/dist/index.d.mts

@@ -0,0 +1,95 @@
+/** A control a story declares for one of its args: only what is declared gets a row in the panel. */
+export type Control = {
+  readonly type: "boolean";
+} | {
+  readonly type: "select";
+  readonly options: ReadonlyArray<string>;
+} | {
+  readonly type: "text";
+} | {
+  readonly type: "number";
+  readonly min?: number;
+  readonly max?: number;
+  readonly step?: number;
+} | {
+  readonly type: "range";
+  readonly min: number;
+  readonly max: number;
+  readonly step?: number;
+};
+export type ArgTypes = Readonly<Record<string, Control>>;
+/**
+ * The part of CSF 3 that is read: a default `meta` export (title, component, args, argTypes) and one object per named export
+ * for a story. Storybook 11 keeps CSF 3 support, so a story file moves into a real Storybook unchanged; the ids this module
+ * builds are the ones Storybook builds (`button--primary`).
+ *
+ * `argTypes` is the one extension: Storybook infers a control from a component's props, which a Solid component does not
+ * carry at run time, so a story declares the controls it wants by hand.
+ */
+export interface Meta<Props extends object = Record<string, unknown>, Node = unknown> {
+  readonly title: string;
+  readonly component?: (props: Props) => Node;
+  /** Arguments every story of the file starts from. */
+  readonly args?: Partial<Props>;
+  readonly argTypes?: ArgTypes;
+}
+export interface Story<Props extends object = Record<string, unknown>, Node = unknown> {
+  /** The name in the rail, instead of the export's own. */
+  readonly name?: string;
+  /** Arguments this story adds to the meta's. */
+  readonly args?: Partial<Props>;
+  /** Markup instead of the meta's component: a story that composes several widgets. */
+  readonly render?: (args: Props) => Node;
+}
+/** The values a story renders with: the meta's args, the story's, and whatever a control wrote since. */
+export type Args = Record<string, unknown>;
+/** One story: the id Storybook would give it, its args and controls, and the view that draws it. */
+export interface Entry<Node = unknown> {
+  /** `button--primary`: the item's name and the story's, kebab-cased, as Storybook builds a story id. */
+  readonly id: string;
+  /** The item the file documents (`button`), from its path; in an app without a registry, the file's own name. */
+  readonly item: string;
+  readonly title: string;
+  readonly name: string;
+  /** The meta's args with the story's over them, before any control moves them. */
+  readonly args: Args;
+  /** The controls this story declares; a story with none gets no panel. */
+  readonly argTypes: ArgTypes;
+  /** Renders the story with the args it is given. */
+  readonly view: (args: Args) => Node;
+}
+/** A CSF module: the `import.meta.glob` result an app passes to `entries`. */
+export type Module<Node = unknown> = {
+  readonly default: Meta<Record<string, unknown>, Node>;
+} & Record<string, unknown>;
+/**
+ * Every story of every CSF module given, sorted by item and then by id.
+ *
+ * Within a file an ES module namespace lists its exports alphabetically, which is the order Storybook gives a component's
+ * stories by default, and the sort keeps it.
+ *
+ * @param {Readonly<Record<string, Module<Node>>>} modules the CSF modules, keyed by their path (an `import.meta.glob` result)
+ * @param {(path: string) => string} itemOf the item a module documents, from its path; a story beside its component names
+ *   the directory, which is the default
+ * @returns {ReadonlyArray<Entry<Node>>} the stories, sorted
+ */
+export declare const entries: <Node = unknown>(modules: Readonly<Record<string, Module<Node>>>, itemOf?: (path: string) => string) => ReadonlyArray<Entry<Node>>;
+/**
+ * The story an id names.
+ *
+ * @param {ReadonlyArray<Entry<Node>>} stories the stories of the app
+ * @param {string} id the id, `button--primary`
+ * @returns {Entry<Node> | undefined} the story, or nothing when no file declares it
+ */
+export declare const storyOfId: <Node>(stories: ReadonlyArray<Entry<Node>>, id: string) => Entry<Node> | undefined;
+/**
+ * A hash split into the page it names and the story, if it names one: `#button--primary` is the button's primary story,
+ * `#button` its first, `#installation` a guide. The split is on the first `--`, which no item or guide name holds.
+ *
+ * @param {string} hash the raw `location.hash`, with or without its `#`
+ * @returns {{ name: string, story: string | undefined }} the page and the full story id
+ */
+export declare const parseHash: (hash: string) => {
+  name: string;
+  story: string | undefined;
+};

package/dist/index.mjs

@@ -0,0 +1,76 @@
+import { createComponent } from "solid-js";
+// src/index.ts
+const kebab = (text) => text.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[^a-zA-Z0-9]+/g, "-").toLowerCase();
+const viewOf = (meta, story) => {
+	if (story.render) {
+		const render = story.render;
+		return (args) => render(args);
+	}
+	const component = meta.component;
+	if (!component) throw new Error(`stories: a story of "${meta.title}" has no render and its meta has no component`);
+	return (args) => createComponent(component, args);
+};
+/**
+* Every story of every CSF module given, sorted by item and then by id.
+*
+* Within a file an ES module namespace lists its exports alphabetically, which is the order Storybook gives a component's
+* stories by default, and the sort keeps it.
+*
+* @param {Readonly<Record<string, Module<Node>>>} modules the CSF modules, keyed by their path (an `import.meta.glob` result)
+* @param {(path: string) => string} itemOf the item a module documents, from its path; a story beside its component names
+*   the directory, which is the default
+* @returns {ReadonlyArray<Entry<Node>>} the stories, sorted
+*/
+const entries = (modules, itemOf = (path) => path.split("/").at(-2) ?? "") => {
+	const found = [];
+	for (const [path, module] of Object.entries(modules)) {
+		const meta = module.default;
+		const item = itemOf(path);
+		for (const [exported, value] of Object.entries(module)) {
+			if (exported === "default") continue;
+			if (typeof value !== "object" || value === null) continue;
+			const story = value;
+			const name = story.name ?? exported;
+			found.push({
+				id: `${kebab(item)}--${kebab(name)}`,
+				item,
+				title: meta.title,
+				name,
+				args: {
+					...meta.args,
+					...story.args
+				},
+				argTypes: meta.argTypes ?? {},
+				view: viewOf(meta, story)
+			});
+		}
+	}
+	return found.sort((a, b) => a.item.localeCompare(b.item) || a.id.localeCompare(b.id));
+};
+/**
+* The story an id names.
+*
+* @param {ReadonlyArray<Entry<Node>>} stories the stories of the app
+* @param {string} id the id, `button--primary`
+* @returns {Entry<Node> | undefined} the story, or nothing when no file declares it
+*/
+const storyOfId = (stories, id) => stories.find((entry) => entry.id === id);
+/**
+* A hash split into the page it names and the story, if it names one: `#button--primary` is the button's primary story,
+* `#button` its first, `#installation` a guide. The split is on the first `--`, which no item or guide name holds.
+*
+* @param {string} hash the raw `location.hash`, with or without its `#`
+* @returns {{ name: string, story: string | undefined }} the page and the full story id
+*/
+const parseHash = (hash) => {
+	const raw = hash.replace(/^#/, "");
+	const at = raw.indexOf("--");
+	return at === -1 ? {
+		name: raw,
+		story: void 0
+	} : {
+		name: raw.slice(0, at),
+		story: raw
+	};
+};
+export { entries, parseHash, storyOfId };

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@cssints/stories",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.28.0",
+  "description": "The CSF 3 loader of a cssints storybook: the modules an app globs in, the entries with Storybook's ids out, and the controls a story declares",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/stories"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "solid-js": "^2.0.0-rc.13"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}