@aurelia/storybook 2.1.0 → 2.2.1

package/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.19.0
+          cache: npm
+
+      - name: Install root deps
+        run: npm install
+
+      - name: Verify example versions are aligned
+        run: npm run sync:versions:check
+
+      - name: Build package
+        run: npm run build
+
+      - name: Build types
+        run: npm run build:types
+
+      - name: Test package
+        run: npm test
+
+      - name: Build hello-world (Vite)
+        working-directory: apps/hello-world
+        run: |
+          npm pkg set "devDependencies.@aurelia/storybook=file:../.."
+          npm install
+          npx tsc --noEmit -p tsconfig.json
+          npm run build
+          npm run build-storybook
+
+      - name: Build hello-world-webpack
+        working-directory: apps/hello-world-webpack
+        run: |
+          npm pkg set "devDependencies.@aurelia/storybook=file:../.."
+          npm install
+          npx tsc --noEmit -p tsconfig.json
+          npm run build
+          npm run build-storybook
+
+      - name: Build hello-world-rsbuild
+        working-directory: apps/hello-world-rsbuild
+        run: |
+          npm pkg set "devDependencies.@aurelia/storybook=file:../.."
+          npm install
+          npx tsc --noEmit -p tsconfig.json
+          npm run build
+          npm run build-storybook

package/.github/workflows/publish.yml

@@ -0,0 +1,82 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to publish (e.g., v2.2.1)'
+        required: true
+        type: string
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.19.0
+          registry-url: https://registry.npmjs.org
+          cache: npm
+
+      - name: Install deps
+        run: npm install
+
+      - name: Verify versions aligned
+        run: npm run sync:versions:check
+
+      - name: Verify tag matches package version
+        run: |
+          TAG_INPUT="${{ inputs.tag }}"
+          if [ -n "$TAG_INPUT" ]; then
+            TAG="${TAG_INPUT#v}"
+          else
+            TAG="${GITHUB_REF_NAME#v}"
+          fi
+          VERSION="$(node -p "require('./package.json').version")"
+          if [ "$TAG" != "$VERSION" ]; then
+            echo "Tag ($TAG) does not match package.json version ($VERSION)"
+            exit 1
+          fi
+
+      - name: Build package
+        run: npm run build
+
+      - name: Build types
+        run: npm run build:types
+
+      - name: Test package
+        run: npm test
+
+      - name: Verify changelog exists
+        run: |
+          if [ ! -s CHANGELOG.md ]; then
+            echo "CHANGELOG.md is empty. Run npm run changelog before tagging."
+            exit 1
+          fi
+
+      - name: Verify changelog version matches package
+        run: |
+          VERSION="$(node -p "require('./package.json').version")"
+          CHANGELOG_VERSION="$(node -e "const fs=require('fs');const m=fs.readFileSync('CHANGELOG.md','utf8').match(/## \\[(\\d+\\.\\d+\\.\\d+(?:-[^\\]]+)?)\\]/);console.log(m?m[1]:'')")"
+          if [ "$VERSION" != "$CHANGELOG_VERSION" ]; then
+            echo "CHANGELOG.md latest version ($CHANGELOG_VERSION) does not match package.json ($VERSION)"
+            exit 1
+          fi
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/storybook-preview.yml

@@ -0,0 +1,62 @@
+name: Storybook Preview
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.19.0
+          cache: npm
+
+      - name: Install root deps
+        run: npm install
+
+      - name: Build package
+        run: npm run build
+
+      - name: Build Storybook (hello-world)
+        working-directory: apps/hello-world
+        run: |
+          npm pkg set "devDependencies.@aurelia/storybook=file:../.."
+          npm install
+          npm run build-storybook
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: apps/hello-world/storybook-static
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [2.2.1](https://github.com/aurelia/storybook/compare/2.1.0...2.2.1) (2026-01-23)
+
+### Features
+
+* **storybook:** update packages, tooling, rsbuild support ([3a97a99](https://github.com/aurelia/storybook/commit/3a97a9950693183b5880756a943e620895f9457b))

package/README.md

@@ -10,7 +10,7 @@
 | --- | --- | --- |
 | 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` | Pick whichever matches your app; both share the same Aurelia preview runtime. |
+| 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.
 
 ## Requirements
@@ -25,6 +25,8 @@
 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
 ```
 
 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.
@@ -119,6 +121,37 @@ Add whichever addons you need (`@storybook/addon-links`, `@storybook/addon-actio
 
 ---
 
+## 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;
+   ```
+
+   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`.
+
+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:
@@ -178,6 +211,22 @@ export const WithCustomTemplate = {
 };
 ```
 
+### 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:
@@ -220,6 +269,117 @@ export const WithServices = {
 
 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.
 
+### Global Aurelia Configuration (Preview + Story Parameters)
+
+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):
+
+```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`.
@@ -265,6 +425,25 @@ This repository publishes the Storybook framework itself. Helpful scripts:
 
 While developing, you can link the package into one of the sample apps in `apps/` to manual-test Storybook changes end to end.
 
+## Releases & Changelog
+
+- 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
+
+- **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
 
 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.

package/__tests__/create-aurelia-app.test.ts

@@ -0,0 +1,94 @@
+import { createAureliaApp } from '../src/preview/render';
+
+jest.mock('aurelia', () => {
+  let lastInstance: any;
+
+  class Aurelia {
+    public container: { has: jest.Mock };
+    public register = jest.fn();
+    public app = jest.fn(() => ({}));
+
+    constructor(container?: unknown) {
+      this.container = (container as any) ?? { has: jest.fn(() => false) };
+      lastInstance = this;
+    }
+  }
+
+  const CustomElement = {
+    define: jest.fn((definition: unknown, Type: new () => unknown) => Type),
+    getDefinition: jest.fn(() => ({ name: 'dummy', bindables: {}, key: 'au:ce:dummy' })),
+    isType: jest.fn(() => true),
+  };
+
+  return {
+    __esModule: true,
+    default: Aurelia,
+    CustomElement,
+    __getLastInstance: () => lastInstance,
+  };
+});
+
+describe('createAureliaApp', () => {
+  it('does not double-register the component when included in components', () => {
+    const Component = class {};
+    const host = document.createElement('div');
+
+    createAureliaApp(
+      { template: '<dummy></dummy>', components: [Component] } as any,
+      {},
+      host,
+      Component as any
+    );
+
+    const aurelia = (jest.requireMock('aurelia') as any).__getLastInstance();
+    const registerArgs = aurelia.register.mock.calls.flat();
+    const registrations = registerArgs.filter((entry: unknown) => entry === Component);
+    expect(registrations).toHaveLength(1);
+  });
+
+  it('skips registration when the container already has the component key', () => {
+    const Component = class {};
+    const host = document.createElement('div');
+    const container = { has: jest.fn(() => true) };
+
+    createAureliaApp(
+      { template: '<dummy></dummy>', components: [] as any, container } as any,
+      {},
+      host,
+      Component as any
+    );
+
+    const aurelia = (jest.requireMock('aurelia') as any).__getLastInstance();
+    expect(container.has).toHaveBeenCalled();
+    expect(aurelia.register).not.toHaveBeenCalled();
+  });
+
+  it('applies parameters.aurelia registrations and hooks', () => {
+    const GlobalComponent = class {};
+    const host = document.createElement('div');
+    const configureContainer = jest.fn();
+    const configure = jest.fn();
+    const storyContext = {
+      parameters: {
+        aurelia: {
+          register: [GlobalComponent],
+          configureContainer,
+          configure,
+        },
+      },
+    } as any;
+
+    createAureliaApp(
+      { template: '<dummy></dummy>' } as any,
+      {},
+      host,
+      undefined,
+      storyContext
+    );
+
+    const aurelia = (jest.requireMock('aurelia') as any).__getLastInstance();
+    expect(configureContainer).toHaveBeenCalledWith(aurelia.container, storyContext);
+    expect(aurelia.register).toHaveBeenCalledWith(GlobalComponent);
+    expect(configure).toHaveBeenCalledWith(aurelia, storyContext);
+  });
+});

package/__tests__/preset.test.ts

@@ -1,11 +1,28 @@
-import { webpackFinal, viteFinal } from '../src/preset';
-import { getRules } from '../src/webpack';
+import { rsbuildFinal, webpackFinal, viteFinal } from '../src/preset';
+import { getRsbuildRules, getRules } from '../src/webpack';
 
 jest.mock('../src/webpack', () => ({
   getRules: jest.fn(() => [
     { test: /\.ts$/, use: 'ts-loader' },
     { test: /\.html$/, use: 'html-loader' },
   ]),
+  getRsbuildRules: jest.fn(() => [
+    { test: /\.ts$/, use: '@aurelia/webpack-loader' },
+    { test: /\.html$/, use: '@aurelia/webpack-loader' },
+  ]),
+}));
+
+const mergeRsbuildConfig = jest.fn((base, extra) => ({
+  ...base,
+  ...extra,
+  tools: {
+    ...base?.tools,
+    ...extra?.tools,
+  },
+}));
+
+jest.mock('@rsbuild/core', () => ({
+  mergeRsbuildConfig,
 }));
 
 describe('preset', () => {
@@ -46,4 +63,16 @@ describe('preset', () => {
       expect(result).toBe(config);
     });
   });
-}); 
+
+  describe('rsbuildFinal', () => {
+    it('should merge rsbuild config and add Aurelia rules', async () => {
+      const config = { tools: {} };
+      const result = await rsbuildFinal(config);
+      expect(mergeRsbuildConfig).toHaveBeenCalledWith(config, expect.any(Object));
+
+      const rspackConfig = { module: { rules: [] as any[] } };
+      result.tools.rspack(rspackConfig);
+      expect(rspackConfig.module.rules).toEqual(getRsbuildRules());
+    });
+  });
+});