@aurelia/storybook 2.0.0 → 2.2.1

package/README.md

@@ -1,132 +1,167 @@
 # @aurelia/storybook
 
-> **Note:** Storybook support is currently in an early stage, and there may be bugs, issues, or unsupported features in this plugin. The intention is to make this plugin more production-ready when Aurelia 2 reaches stable release.
+> **Note:** Storybook support is still early-stage. Expect a few rough edges while Aurelia 2 finishes its beta cycle, and please report anything that feels off.
 
-This package provides an integration between Aurelia 2 and Storybook 10 using Vite or Webpack. It lets you write and render Aurelia 2 components as Storybook stories with full support for Storybook controls, actions, and interactive testing.
+`@aurelia/storybook` is the glue between Aurelia 2 components and Storybook 10. It wires Aurelia's `enhance()` API into Storybook's rendering pipeline so you can preview, test, and document your components with either the Vite or Webpack builders.
 
-## Features
+## Compatibility at a Glance
 
-- **Vite & Webpack Support**: Works with both Vite (via `@storybook/builder-vite`) and Webpack 5 (via `@storybook/builder-webpack5`).
-- **Aurelia Enhancement**: Renders Aurelia 2 components using Aurelia's `enhance()` API.
-- **Storybook 10 Compatibility**: Fully compatible with Storybook 10's rendering API and ESM-only architecture.
-- **Arg & Action Support**: Use story args and actions as you would with any Storybook story.
+| Item | Supported versions | Notes |
+| --- | --- | --- |
+| Storybook | 10.x (ESM) | Tested with 10.0.5+; works with `storybook dev`/`storybook build` commands. |
+| Aurelia | 2.0.0-beta.25+ | Uses Aurelia's `enhance()` APIs under the hood. |
+| Bundlers | `@storybook/builder-vite` (Vite 5) · `@storybook/builder-webpack5` · `storybook-builder-rsbuild` (Rsbuild/Rspack) | Pick whichever matches your app; they share the same Aurelia preview runtime. |
+| Node.js | ≥ 20.19.0 or ≥ 22.12.0 | Matches the engines field in `package.json` and Storybook 10's baseline.
 
-## Installation
+## Requirements
+
+- An Aurelia 2 application (TypeScript or JavaScript) already set up with either Vite or Webpack.
+- Storybook 10.x installed in the project. (Run `npx storybook@latest init` if you are starting fresh.)
+- The peer dependencies listed in [`package.json`](package.json) that align with the Aurelia 2 beta train you are targeting.
 
-Install the plugin as a dev dependency:
+## Installation
 
 ```bash
-npm install --save-dev @aurelia/storybook
+npm install --save-dev @aurelia/storybook storybook @storybook/builder-vite
+# or, for Webpack builds:
+npm install --save-dev @aurelia/storybook storybook @storybook/builder-webpack5
+# or, for Rsbuild/Rspack builds:
+npm install --save-dev @aurelia/storybook storybook storybook-builder-rsbuild @rsbuild/core
 ```
 
-Also, make sure to have the required dependencies installed in your project:
+Add whichever addons you need (`@storybook/addon-links`, `@storybook/addon-actions`, etc.). Essentials functionality now ships with Storybook 10 core, so most projects only add optional extras.
+
+---
+
+## Quick Start (Vite Builder)
+
+1. **Install** the dev dependencies as shown above (or with `pnpm`/`yarn`).
+2. **Create `.storybook/main.ts`:**
+
+   ```ts
+   // .storybook/main.ts
+   import { mergeConfig, type InlineConfig } from 'vite';
+   import type { StorybookConfig } from 'storybook/internal/types';
+
+   const config: StorybookConfig & { viteFinal?: (config: InlineConfig) => InlineConfig | Promise<InlineConfig> } = {
+     stories: ['../src/stories/**/*.stories.@(ts|tsx|js|jsx|mdx)'],
+     addons: ['@storybook/addon-links'],
+     framework: {
+       name: '@aurelia/storybook',
+       options: {},
+     },
+     core: {
+       builder: '@storybook/builder-vite',
+     },
+     viteFinal: async (viteConfig) => {
+       // Ensure problematic Aurelia deps are excluded from pre-bundling.
+       viteConfig.optimizeDeps = viteConfig.optimizeDeps ?? {};
+       viteConfig.optimizeDeps.exclude = Array.from(new Set([...(viteConfig.optimizeDeps.exclude ?? []), '@aurelia/runtime-html']));
+
+       return mergeConfig(viteConfig, {
+         define: {
+           'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV ?? 'development'),
+         },
+       });
+     },
+   };
+
+   export default config;
+   ```
 
-```bash
-npm install --save-dev storybook @storybook/builder-vite
-```
+   - Excluding `@aurelia/runtime-html` keeps Vite from trying to pre-bundle Aurelia's DOM runtime, which is already ESM friendly.
+   - The `define` shim avoids `process is not defined` errors when Storybook code (or Aurelia plugins) look for `process.env.NODE_ENV` in the preview iframe.
 
-> **Tip:** Check your existing Aurelia 2 app for already installed versions. The peer dependencies are expected to be compatible with Aurelia 2 beta releases (see `package.json` for version details).
-
-## Getting Started
-
-### Storybook Configuration
-
-To integrate Aurelia 2 with your Storybook instance, follow these steps:
-
-1. **Preset Setup**:
-    The package comes with a minimal Storybook preset (see [src/preset.ts](src/preset.ts)) that allows you to adjust Vite's configuration if needed. Storybook will use this preset to set up the build system for your Aurelia stories.
-
-2. **Framework Setup**:
-    For a full Aurelia 2 integration with Vite and a TypeScript configuration, ensure that your Storybook configuration files are set up as follows:
-
-    -   **.storybook/main.ts**
-        Create or update your `.storybook/main.ts` file with the following contents:
-
-        ```typescript
-        import type { StorybookConfig } from 'storybook/internal/types';
-        import { mergeConfig, type InlineConfig } from 'vite';
-
-        const config: StorybookConfig & { viteFinal?: (config: InlineConfig, options: { configType: string }) => InlineConfig | Promise<InlineConfig> } = {
-          stories: ['../src/stories/**/*.stories.@(ts|tsx|js|jsx|mdx)'],
-          addons: [
-              // Additional addons (essentials are now built into Storybook 9 core):
-              '@storybook/addon-links'
-          ],
-          framework: {
-            name: '@aurelia/storybook',
-            options: {},
-          },
-          core: {
-            builder: '@storybook/builder-vite',
-          },
-          viteFinal: async (viteConfig) => {
-            viteConfig.optimizeDeps = viteConfig.optimizeDeps || {};
-            viteConfig.optimizeDeps.exclude = viteConfig.optimizeDeps.exclude || [];
-            if (!viteConfig.optimizeDeps.exclude.includes('@aurelia/runtime-html')) {
-              viteConfig.optimizeDeps.exclude.push('@aurelia/runtime-html');
-            }
-            return mergeConfig(viteConfig, {
-              // ...any additional Vite configuration
-            });
-          },
-        };
-
-        export default config;
-        ```
-
-    -   **.storybook/preview.ts**
-        Next, update or create your `.storybook/preview.ts` file with the following code to import the render functions from the Aurelia Storybook plugin:
-
-        ```typescript
-        // .storybook/preview.ts
-        // Import the render function from the plugin package.
-        export { render, renderToCanvas } from '@aurelia/storybook';
-        ```
-
-    > **Note:** Essential features like actions, controls, backgrounds, and viewport are now built into Storybook 10 core and don't need to be installed separately. However, if you need to use the `action()` function in your stories (for programmatic actions), you may still need to install `@storybook/addon-actions`. Additional addons like `@storybook/addon-links` can be installed and added to the `addons` array in your configuration.
-
-    ### Using with Webpack
-
-    If you prefer to use Webpack instead of Vite, update your `.storybook/main.ts` configuration:
-
-    ```typescript
-    import type { StorybookConfig } from 'storybook/internal/types';
-
-    const config: StorybookConfig = {
-      stories: ['../src/**/*.stories.@(ts|tsx|js|jsx|mdx)'],
-      addons: [
-        '@storybook/addon-links'
-      ],
-      framework: {
-        name: '@aurelia/storybook',
-        options: {},
-      },
-      core: {
-        builder: '@storybook/builder-webpack5',
-      },
-    };
+3. **Create `.storybook/preview.ts`:**
+
+   ```ts
+   // .storybook/preview.ts
+   export { render, renderToCanvas } from '@aurelia/storybook';
+   ```
+
+4. **Add `storybook` scripts** to `package.json`:
 
-    export default config;
-    ```
+   ```json
+   {
+     "scripts": {
+       "storybook": "storybook dev -p 6006",
+       "build-storybook": "storybook build"
+     }
+   }
+   ```
 
-    The `.storybook/preview.ts` file remains the same for both Vite and Webpack configurations.
+5. **Run Storybook:** `npm run storybook` starts the dev server at http://localhost:6006.
 
-3. **Add scripts to your package.json**:
-    Add the following scripts to your `package.json` file to work with Storybook:
+## Quick Start (Webpack Builder)
 
-    ```json
-    "scripts": {
-      "storybook": "storybook dev -p 6006",
-      "build-storybook": "storybook build"
-    }
-    ```
-    These scripts will allow you to start Storybook in development mode and build it for production.
+1. Install `@storybook/builder-webpack5` instead of the Vite builder.
+2. Create `.storybook/main.ts`:
 
-### Writing Stories
+   ```ts
+   import type { StorybookConfig } from 'storybook/internal/types';
+
+   const config: StorybookConfig = {
+     stories: ['../src/**/*.stories.@(ts|tsx|js|jsx|mdx)'],
+     addons: ['@storybook/addon-links'],
+     framework: {
+       name: '@aurelia/storybook',
+       options: {},
+     },
+     core: {
+       builder: '@storybook/builder-webpack5',
+     },
+   };
+
+   export default config;
+   ```
+
+   The preset embedded in this package injects the `ts-loader` + `@aurelia/webpack-loader` rules so you typically do not need extra config, but `webpackFinal` is available if you need to extend it further.
+
+3. Reuse the same `.storybook/preview.ts` and `package.json` scripts as in the Vite quick start.
+
+---
+
+## Quick Start (Rsbuild/Rspack Builder)
+
+1. Install `storybook-builder-rsbuild` and `@rsbuild/core`.
+2. Create `.storybook/main.ts`:
+
+   ```ts
+   import type { StorybookConfig } from 'storybook/internal/types';
+
+   const config: StorybookConfig = {
+     stories: ['../src/**/*.stories.@(ts|tsx|js|jsx|mdx)'],
+     addons: ['@storybook/addon-links'],
+     framework: {
+       name: '@aurelia/storybook',
+       options: {},
+     },
+     core: {
+       builder: 'storybook-builder-rsbuild',
+     },
+   };
+
+   export default config;
+   ```
 
-Aurelia 2 stories are written similarly to standard Storybook stories, with a few Aurelia-specific details. Below is an example story file (`hello-world.stories.ts`) that demonstrates various scenarios:
+   The Aurelia preset injects the `ts-loader` + `@aurelia/webpack-loader` rules via `rsbuildFinal`,
+   so most projects do not need extra Rsbuild configuration. If you do, add your own `rsbuildFinal`
+   and merge with `@rsbuild/core`'s `mergeRsbuildConfig`.
 
-```typescript
+3. Reuse the same `.storybook/preview.ts` and `package.json` scripts as in the Vite quick start.
+
+---
+
+## Writing Aurelia Stories
+
+Story files look exactly like standard Storybook CSF stories. The framework export automatically:
+
+- Registers the component you set on the default export.
+- Uses `renderToCanvas` to bootstrap an Aurelia app inside Storybook's preview iframe.
+- Generates a template for you if you omit the `render` function (it binds every declared `bindable`).
+
+```ts
+// src/stories/hello-world.stories.ts
 import { HelloWorld } from '../hello-world';
 import { fn, userEvent, within } from 'storybook/test';
 
@@ -138,82 +173,280 @@ const meta = {
   }),
   argTypes: {
     message: { control: 'text' },
-    onIncrement: { action: 'increment' }
-  }
+    onIncrement: { action: 'increment' },
+  },
 };
 
 export default meta;
 
 export const DefaultHelloWorld = {
   args: {
-    message: "Hello from Storybook!",
-    onIncrement: fn()
-  }
+    message: 'Hello from Storybook!',
+    onIncrement: fn(),
+  },
 };
 
 export const InteractiveHelloWorld = {
   args: {
-    message: "Try clicking the button!",
-    onIncrement: fn()
+    message: 'Try clicking the button!',
+    onIncrement: fn(),
   },
-  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+  async play({ canvasElement }: { canvasElement: HTMLElement }) {
     const canvas = within(canvasElement);
-    const button = canvas.getByRole('button');
-    // Simulate three button clicks
-    await userEvent.click(button);
-    await userEvent.click(button);
-    await userEvent.click(button);
-  }
+    await userEvent.click(canvas.getByRole('button'));
+  },
 };
 
 export const NoArgs = {
-  render: () => ({
-    template: `<hello-world></hello-world>`
-  })
+  render: () => ({ template: `<hello-world></hello-world>` }),
 };
 
 export const WithCustomTemplate = {
   render: () => ({
-    template: `<hello-world message.bind="message">Click me!</hello-world>`
+    template: `<hello-world message.bind="message">Click me!</hello-world>`,
   }),
   args: {
-    message: "This is a custom message"
-  }
+    message: 'This is a custom message',
+  },
+};
+```
+
+### Helper for Typed Story Results
+
+If you want stronger typing (especially for `props`), you can use the helper and types exported by the package:
+
+```ts
+import { defineAureliaStory, type AureliaStoryResult } from '@aurelia/storybook';
+
+const render = (args: { title: string }): AureliaStoryResult<{ title: string }> =>
+  defineAureliaStory({
+    template: `<my-card title.bind="title"></my-card>`,
+    props: args,
+  });
+```
+
+You can also import directly from `@aurelia/storybook/preview` or `@aurelia/storybook/preview/types` if you prefer.
+
+### Story Result Contract
+
+When you provide a custom `render` function, return an object with any of the following fields. The Aurelia runtime consumes them while creating the preview app:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `template` | `string` | Markup that will be enhanced inside Storybook's canvas. Required when you do not rely on the auto-generated template. |
+| `components` | `unknown[]` | Additional custom elements, value converters, etc. to register via `aurelia.register(...)`. |
+| `items` | `unknown[]` | Any DI registrations (e.g., `Registration.instance(...)`, services, or Aurelia plugins). |
+| `container` | `IContainer` | Supply a pre-configured Aurelia DI container if you need full control. |
+| `innerHtml` | `string` | Optional projection content used when a component template is auto-generated from the `component` export. |
+| `props` | `Record<string, any>` | Story-specific props that merge with Storybook `args`. Useful when you need defaults that should not surface as controls.
+
+## Registering Aurelia Dependencies & DI
+
+Use the `components`, `items`, or `container` fields to bring along everything your component needs:
+
+```ts
+import { DI, Registration } from 'aurelia';
+import { HttpClient } from '@aurelia/fetch-client';
+import { OrdersPanel } from '../orders-panel';
+
+const container = DI.createContainer();
+container.register(
+  HttpClient,
+  Registration.instance('apiBaseUrl', 'https://api.example.com')
+);
+
+export const WithServices = {
+  render: () => ({
+    template: `<orders-panel api-base-url.bind="apiBaseUrl"></orders-panel>`,
+    components: [OrdersPanel],
+    container,
+    props: {
+      apiBaseUrl: 'https://api.example.com',
+    },
+  }),
 };
 ```
 
-### How It Works
+Because the Aurelia app lives for the lifetime of the story iframe, DI registrations persist until the story is torn down or Storybook forces a remount. If you need a clean state between stories, set `parameters: { forceRemount: true }` on the story or click the *Remount component* toolbar button in Storybook.
 
-- **Render Function**:  
-  The integration exports a render function (`renderToCanvas`) that Storybook calls to mount your Aurelia component on the preview canvas. It clears the canvas, enhances it with Aurelia, and notifies Storybook when rendering is complete.
+### Global Aurelia Configuration (Preview + Story Parameters)
 
-- **Aurelia Enhancement**:  
-  Once the canvas is cleared, the integration instantiates a new Aurelia instance, registers your component (and any additional Aurelia modules you may specify), and calls the Aurelia `enhance()` API to bind your component's view to the DOM.
+You can register global resources/plugins and customize the DI container via Storybook parameters. The framework reads `parameters.aurelia` from the merged Storybook context (preview + component + story):
 
-- **Arg Integration and Interactions**:  
-  Just like with other Storybook frameworks, you can make your stories interactive by defining args and using the testing library's `play` function to simulate user interactions.
+```ts
+// .storybook/preview.ts
+import { Registration } from 'aurelia';
+import { CurrencyValueConverter } from '../src/resources/currency';
+import { FeatureFlags } from '../src/services/feature-flags';
+
+export const parameters = {
+  aurelia: {
+    register: [CurrencyValueConverter],
+    configureContainer: (container) => {
+      container.register(Registration.instance(FeatureFlags, { beta: true }));
+    },
+  },
+};
+```
+
+You can also override or extend per story:
+
+```ts
+export const WithOverrides = {
+  parameters: {
+    aurelia: {
+      configureContainer: (container) => {
+        container.register(Registration.instance('apiBaseUrl', 'https://staging.example.com'));
+      },
+    },
+  },
+};
+```
+
+These hooks run when the Aurelia app is created. If you rely on different container setups per story, use `parameters: { forceRemount: true }` to ensure a fresh app instance.
+
+#### Parameters API (Quick Reference)
+
+```ts
+export const parameters = {
+  aurelia: {
+    // Register global resources/plugins
+    register: [MyElement, MyValueConverter],
+    // Optional aliases for parity with story results
+    components: [MyElement],
+    items: [Registration.instance(MyService, new MyService())],
+    // Configure the DI container
+    configureContainer: (container, context) => {
+      // ...
+    },
+    // Configure the Aurelia instance
+    configure: (aurelia, context) => {
+      // ...
+    },
+  },
+};
+```
+
+## Cookbook
+
+### 1) Register global resources once
+
+```ts
+// .storybook/preview.ts
+import { Registration } from 'aurelia';
+import { CurrencyValueConverter } from '../src/resources/currency';
+import { FeatureFlags } from '../src/services/feature-flags';
+
+export const parameters = {
+  aurelia: {
+    register: [CurrencyValueConverter],
+    configureContainer: (container) => {
+      container.register(Registration.instance(FeatureFlags, { beta: true }));
+    },
+  },
+};
+```
+
+### 2) Mock a service per story
+
+```ts
+import { Registration } from 'aurelia';
+import { IWeatherService } from '../src/services/weather-service';
+
+export const WithMockedService = {
+  render: (args) =>
+    defineAureliaStory({
+      template: `<weather-widget location.bind="location"></weather-widget>`,
+      props: args,
+      items: [
+        Registration.instance(IWeatherService, {
+          getWeather: async () => ({ location: 'Seattle', condition: 'Sunny' }),
+        }),
+      ],
+    }),
+};
+```
+
+### 3) Force a clean DI container per story
+
+```ts
+export const CleanState = {
+  parameters: { forceRemount: true },
+  render: (args) =>
+    defineAureliaStory({
+      template: `<my-component value.bind="value"></my-component>`,
+      props: args,
+    }),
+};
+```
+
+## Example Apps Inside This Repo
+
+- `apps/hello-world` – Vite-based Aurelia starter that consumes `@aurelia/storybook`.
+- `apps/hello-world-webpack` – Equivalent Webpack example.
+
+To try them out:
+
+```bash
+cd apps/hello-world
+npm install
+npm run storybook
+
+cd ../hello-world-webpack
+npm install
+npm run storybook
+```
+
+Each sample project now includes a small library of showcase stories you can open in Storybook to see different aspects of the integration:
+
+- `HelloWorld` – the minimal counter example wired to Storybook controls and actions.
+- `StatCard` – demonstrates args-driven styling and wiring the `onRefresh` action.
+- `NotificationCenter` – renders repeating templates and exercises dismissal actions + play functions.
+- `FeedbackForm` – shows two-way bindings, form state, and Storybook interaction tests that fill and submit inputs.
+- `WeatherWidget` – uses Aurelia's DI plus `items` registration in the story to provide a mock `WeatherService` implementation.
+
+These are great references when you want to compare your configuration against a working baseline or copy/paste patterns into your own component library.
+
+## Troubleshooting & Tips
+
+- **`process is not defined` inside the preview iframe** – Add `define: { 'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV ?? 'development') }` in your `viteFinal` merge (shown above).
+- **Vite fails while pre-bundling Aurelia packages** – Ensure `@aurelia/runtime-html` (and any other Aurelia libs that re-export DOM globals) are listed in `optimizeDeps.exclude`.
+- **State leaks between stories** – By default we reuse the Aurelia app instance for performance. Pass `parameters: { forceRemount: true }` to stories that must start fresh.
+- **Need additional Storybook addons?** – Add them to the `addons` array as usual. The Aurelia framework only controls rendering, so controls, actions, interactions, and testing addons all work normally.
 
 ## Development
 
-If you wish to contribute or modify the integration:
+This repository publishes the Storybook framework itself. Helpful scripts:
 
-1. **Build the package** using TypeScript:
+- `npm run build` – bundle the framework with Rollup.
+- `npm run build:types` – emit `.d.ts` files via `tsc`.
+- `npm run watch` – development build with Rollup watch mode.
+- `npm run test` – run the Jest suite (uses the JSDOM environment).
 
-   ```bash
-   npm run build
-   ```
+While developing, you can link the package into one of the sample apps in `apps/` to manual-test Storybook changes end to end.
 
-2. **Watch for changes** during development:
+## Releases & Changelog
 
-   ```bash
-   npm run watch
-   ```
+- Keep `CHANGELOG.md` updated for each release (use the **Unreleased** section while working).
+- Align example app versions with the root package before tagging:
+  - `npm run sync:versions`
+- Tag releases as `vX.Y.Z` so the publish workflow can run.
+
+Publish flow (automated via GitHub Actions):
+1. Update `package.json` version.
+2. Generate `CHANGELOG.md` from conventional commits: `npm run changelog`.
+3. Run `npm run sync:versions` and commit changes.
+4. Create tag `vX.Y.Z` and push it.
+
+## Troubleshooting
 
-3. **Run Storybook** in your local application to see the integration in action.
+- **AUR0153 duplicate element registration**: ensure the same component isn't registered multiple times within the same story/container.
+- **Args undefined during first render**: defensively handle optional args in components (e.g., fallbacks for arrays/strings).
+- **Rsbuild `loader.loadModule is not a function`**: avoid `ts-loader` in Rsbuild/Rspack builds; use the built-in Rsbuild TS handling.
 
 ## Contributing
 
-Contributions, bug reports, and feature requests are welcome. Please open an issue or submit a pull request on the project repository.
+Bug reports, docs tweaks, and feature PRs are all welcome. Please open an issue to discuss significant changes, and spin up one of the example apps to verify the behavior you are touching.
 
 ## License
 
@@ -221,4 +454,4 @@ Contributions, bug reports, and feature requests are welcome. Please open an iss
 
 ## Acknowledgements
 
-Special shout out to Dmitry (@ekzobrain on GitHub) for the work he did on Storybook support for earlier versions of Storybook, which helped lay some of the groundwork for this implementation [https://github.com/ekzobrain/storybook](https://github.com/ekzobrain/storybook).
+Special shout out to Dmitry (@ekzobrain on GitHub) for the work he did on Storybook support for earlier versions of Storybook, which helped lay the groundwork for this implementation: [https://github.com/ekzobrain/storybook](https://github.com/ekzobrain/storybook).