@uniflowed/story 0.0.0-alpha.18 → 0.14.1

package/collect.js

@@ -2,41 +2,39 @@
 //
 // `@uniflowed/story/collect`: which files are stories, and what is in them.
 //
-// A story file is `_uf.story.js`, beside the component it describes.
+// A story file is `$story.js`, beside the component it describes.
 //
 //   src/components/Button.js
-//   src/components/_uf.story.js
+//   src/components/$story.js
 //
 // # The name is the repository's own grammar, not a second one
 //
-// uf already reserves `_uf.<role>[.<variant>].js` for the files the framework
+// uf already reserves `$<role>[.<variant>].js` for the files the framework
 // gives meaning to, and `crates/uf_router/src/reserved.rs` is its single
 // source of truth: `uf create` generates those names, the router looks for
 // them, and `uf lint`'s `router/reserved-files` rejects the ones that do not
 // fit. A story file is exactly such a file — a name uf assigns meaning to, in
-// a project's own source tree — so it is spelled `_uf.story.js` and not
+// a project's own source tree — so it is spelled `$story.js` and not
 // `*.stories.js`.
 //
 // The variants are the same vocabulary for the same reason, and the rule
 // about them is the router's too: only the default variant is the thing the
-// runner renders. `_uf.story.native.js` is a companion for a React Native
-// build, the way `_uf.page.native.js` is, and [`findStoryFiles`] leaves it
+// runner renders. `$story.native.js` is a companion for a React Native
+// build, the way `$page.native.js` is, and [`findStoryFiles`] leaves it
 // alone until there is a renderer that could mount it.
 //
-// **`story` is not yet one of the roles the Rust grammar defines.** Adding it
-// is one arm in `ReservedRole` in `crates/uf_router/src/reserved.rs`, and
-// this package cannot make that change from JavaScript. Until it lands,
-// `uf lint` reports `router/reserved-files` on every `_uf.story.js` — the
-// name is right and the linter has not been told. `index.js` lists it under
-// **Readiness** rather than leaving it to be discovered by whoever writes the
-// first story file.
+// `story` is one of the roles `ReservedRole` in
+// `crates/uf_router/src/reserved.rs` defines, so `uf lint`'s
+// `router/reserved-files` accepts `$story.js` and its variants and still
+// reports a misspelling such as `$stori.js`. The variant list below mirrors
+// `ReservedVariant`, `client` included; a test pins it.
 //
 // # What makes a file a story file is the name, and what makes it valid is
 // the export
 //
 // Discovery is by name alone: a walk that had to read every file to find out
 // whether it declared stories would be a parse of the whole tree. Loading is
-// where a file is judged, and a `_uf.story.js` that exports no story set is
+// where a file is judged, and a `$story.js` that exports no story set is
 // an error rather than an empty result — the name is a claim, and a file that
 // does not honour it is a mistake somebody made, not a fact about the
 // project.
@@ -72,17 +70,24 @@ import { isStorySet } from "./story.js";
 export const STORY_ROLE: "story" = "story";
 
 /** The name of a story file with no variant: the one the runner renders. */
-export const STORY_FILE: "_uf.story.js" = "_uf.story.js";
+export const STORY_FILE: "$story.js" = "$story.js";
 
 /**
  * Which build a story file applies to.
  *
  * The router's vocabulary, exactly. `"default"` has no segment in the name.
  */
-export type StoryVariant = "default" | "native" | "ios" | "android" | "web" | "test";
+export type StoryVariant = "default" | "native" | "ios" | "android" | "web" | "test" | "client";
 
-/** The variants, in the order `uf_router::ReservedVariant` declares them. */
-const VARIANTS: $ReadOnlyArray<StoryVariant> = ["native", "ios", "android", "web", "test"];
+/** The variants, in the order `uf_router::ReservedVariant::all` lists them. */
+const VARIANTS: $ReadOnlyArray<StoryVariant> = [
+  "native",
+  "ios",
+  "android",
+  "web",
+  "test",
+  "client",
+];
 
 /** Directory names the walk never descends into. */
 const IGNORED: $ReadOnlyArray<string> = [
@@ -102,10 +107,10 @@ const IGNORED: $ReadOnlyArray<string> = [
  * a caller with a path can normalise it two ways and get two answers.
  */
 export function classifyStoryFile(fileName: string): StoryVariant | null {
-  if (!fileName.startsWith("_uf.") || !fileName.endsWith(".js")) {
+  if (!fileName.startsWith("$") || !fileName.endsWith(".js")) {
     return null;
   }
-  const segments = fileName.slice("_uf.".length, -".js".length).split(".");
+  const segments = fileName.slice("$".length, -".js".length).split(".");
   if (segments[0] !== STORY_ROLE) {
     return null;
   }
@@ -113,7 +118,7 @@ export function classifyStoryFile(fileName: string): StoryVariant | null {
     return "default";
   }
   if (segments.length > 2) {
-    // `_uf.story.native.test.js`: one variant, not a stack of them.
+    // `$story.native.test.js`: one variant, not a stack of them.
     return null;
   }
   const variant = VARIANTS.find((each) => each === segments[1]);
@@ -202,6 +207,9 @@ export async function findStoryFiles(root: string, options?: FindOptions): Promi
  */
 export async function loadStoryFile(file: string): Promise<Array<StorySet>> {
   const absolute = path.resolve(file);
+  // The user's story file, known only at run time; Flow types only a literal
+  // specifier, and `isStorySet` checks every export before it is kept.
+  // $FlowFixMe[unsupported-syntax]
   const module = await import(pathToFileURL(absolute).href);
   const sets: Array<StorySet> = [];
   for (const name of Object.keys(module)) {

package/index.js

@@ -17,7 +17,7 @@
 // they are declared as data, the same declaration serves the assertion and
 // the picture.
 //
-//   // src/components/_uf.story.js
+//   // src/components/$story.js
 //   export const stories = defineStories({
 //     title: "Button",
 //     component: Button,
@@ -63,7 +63,7 @@
 // - `story.js` — **declaring**: `defineStories`, what a story inherits from
 //   its set, and where the `Props` type parameter is checked and why it is
 //   then erased. Pure data; declaring a story runs nothing.
-// - `collect.js` — **finding**: `_uf.story.js`, the repository's own reserved
+// - `collect.js` — **finding**: `$story.js`, the repository's own reserved
 //   name grammar, the walk, and what makes a story file valid.
 // - `render.js` — **rendering one**: the mock lifetime, the decorators, the
 //   mount, and the markup. Everything here is about *time*.
@@ -84,7 +84,8 @@
 // props on the set and a partial override per story, with per-story and
 // per-set decorators, mocks and play functions; names defaulting to the
 // declaration key; stable `title--name` ids. Collecting them: the
-// `_uf.story.js` reserved name with the router's variant vocabulary, a
+// `$story.js` reserved name — a role in `crates/uf_router/src/reserved.rs`,
+// so `uf lint` accepts it — with the router's variant vocabulary, a
 // bounded walk that skips `node_modules` and symlinks, loading every story
 // set a file exports, and rejecting two stories that share an id. Rendering
 // one into `@uniflowed/react-testing`'s DOM, with the story's handlers
@@ -94,19 +95,10 @@
 // path and the original error. `renderStoryToHtml` for something that is not
 // a test. One `it` per story through `@uniflowed/story/runner`.
 //
-// **Experimental.** The `_uf.story.js` name itself. It follows uf's reserved
-// grammar — `_uf.<role>[.<variant>].js` — but `story` is not yet one of the
-// roles `crates/uf_router/src/reserved.rs` defines, and that file is the
-// grammar's single source of truth for `uf create`, the router and the
-// linter. Until a `story` role is added there, **`uf lint` reports
-// `router/reserved-files` on every `_uf.story.js`**: the name is right and
-// the linter has not been told. The alternative was to invent a second
-// convention (`*.stories.js`) that no uf tool knows about, which is worse.
-//
-// `describeStories` is experimental for a different reason, and it is a
-// property of `uf test` rather than of this package: discovery scans source
-// text for `it(` with a string-literal name, so a file whose only content is
-// a `describeStories` call is skipped — silently, reporting zero files and
+// **Experimental.** `describeStories`, and for a reason that is a property of
+// `uf test` rather than of this package: discovery scans source text for
+// `it(` or `test(` with a string-literal name, so a file whose only content
+// is a `describeStories` call is skipped — silently, reporting zero files and
 // exiting 0. `runner.js` documents the shape that works today and
 // `storyTest` is the escape hatch.
 //
@@ -114,11 +106,12 @@
 // no browser canvas and no static story site: this package produces the index
 // and the markup those would need, and nothing renders them for a person yet
 // beyond a string. `withBrowser` is deliberately gone rather than carried
-// over — `@uniflowed/browser` is still a declaration whose every function
-// throws, so a story that claimed to drive a real browser would be claiming a
-// capability that does not exist. For the same reason nothing here talks to
-// `@uniflowed/vrt`; `storyId` is exported so that a baseline can be filed
-// under the same name when it does.
+// over. `@uniflowed/test/browser` now wraps `@uniflowed/test/browser`, which drives
+// a real page under `uf test --browser`, but no story API is built on it yet:
+// a story renders into `@uniflowed/react-testing`'s DOM, and a story test that
+// wants a real browser opens one itself. Nothing here talks to
+// `@uniflowed/vrt` either; `storyId` is exported so that a baseline can be
+// filed under the same name when something does.
 //
 // Also absent, and each for a reason rather than by oversight: no Storybook
 // CSF compatibility, no `argTypes`, controls or knobs (a control panel needs
@@ -128,7 +121,7 @@
 // remote catalogues, and no story-level snapshot testing —
 // `@uniflowed/test`'s snapshots work on the string `renderStoryToHtml`
 // returns. Only the default variant of the reserved name is rendered:
-// `_uf.story.native.js` is recognised and skipped, because a React Native
+// `$story.native.js` is recognised and skipped, because a React Native
 // renderer does not exist here either. Nothing renders a story through RSC or
 // server rendering; a story mounts on the client, which is what
 // `@uniflowed/react-testing` provides.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/story",
-  "version": "0.0.0-alpha.18",
+  "version": "0.14.1",
   "description": "Named, rendered states of a component that a person and a test can both reach, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -8,7 +8,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ubugeeei-prod/uf.git",
-    "directory": "packages/story"
+    "directory": "npm/story"
   },
   "exports": {
     ".": "./index.js",
@@ -23,10 +23,10 @@
     "!*.test.js"
   ],
   "dependencies": {
-    "@uniflowed/mock": "0.0.0-alpha.18",
-    "@uniflowed/react": "0.0.0-alpha.18",
-    "@uniflowed/react-testing": "0.0.0-alpha.18",
-    "@uniflowed/test": "0.0.0-alpha.18"
+    "@uniflowed/mock": "0.14.1",
+    "@uniflowed/react": "0.14.1",
+    "@uniflowed/react-testing": "0.14.1",
+    "@uniflowed/test": "0.14.1"
   },
   "peerDependencies": {
     "react": ">=19"

package/runner.js

@@ -7,8 +7,9 @@
 // does not write the same mount-play-unmount block once per story.
 //
 //   import { describe, it } from "@uniflowed/test";
+//   import { findStory } from "@uniflowed/story";
 //   import { describeStories, storyTest } from "@uniflowed/story/runner";
-//   import { stories } from "./_uf.story.js";
+//   import { stories } from "./$story.js";
 //
 //   it("renders every Button story", storyTest(findStory(stories, "Primary")));
 //   describe("Button", () => {
@@ -37,11 +38,12 @@
 // # What `uf test` can and cannot see here
 //
 // `uf test` discovers test declarations by scanning source text for `it(` and
-// `describe(` with a **string literal** first argument, and a file with no
-// such declaration is not run at all. [`describeStories`] registers its cases
-// from the set, so their names are not literals — which means a file whose
-// only content is a `describeStories` call is skipped silently, reported as
-// zero files and zero tests, and exits 0.
+// `test(` with a **string literal** first argument, and a file with no such
+// declaration is not run at all. `describe(` is read too, for the names of the
+// cases inside it, but a `describe` alone does not make a file runnable.
+// [`describeStories`] registers its cases from the set, so their names are not
+// literals — which means a file whose only content is a `describeStories` call
+// is skipped silently, reported as zero files and zero tests, and exits 0.
 //
 // So a story test file must contain at least one literal declaration, and the
 // shape above is the recommended one: a literal `describe` is not enough,