@aurelia/storybook 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dwayne Charrington
+
+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

@@ -0,0 +1,207 @@
+# @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. Currently, it only works with Vite, with Webpack support planned shortly.
+
+This package provides an integration between Aurelia 2 and Storybook 8 using Vite. It lets you write and render Aurelia 2 components as Storybook stories with full support for Storybook controls, actions, and interactive testing.
+
+## Features
+
+- **Vite-Powered Build**: Uses Vite (via the provided preset) to bundle your stories.
+- **Aurelia Enhancement**: Renders Aurelia 2 components using Aurelia's `enhance()` API.
+- **Storybook 8 Compatibility**: Fully compatible with Storybook 8's new rendering API.
+- **Arg & Action Support**: Use story args and actions as you would with any Storybook story.
+
+## Installation
+
+Install the plugin as a dev dependency:
+
+```bash
+npm install --save-dev @aurelia/storybook
+```
+
+Also, make sure to have the required dependencies installed in your project:
+
+```bash
+npm install --save-dev @storybook/addons @storybook/core-events @storybook/builder-vite @storybook/core-common @storybook/preview-api @storybook/types
+```
+
+> **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/core-common';
+        import { mergeConfig } from 'vite';
+
+        const config: StorybookConfig & { viteFinal?: (config: any, options: any) => any } = {
+          stories: ['../src/stories/**/*.stories.@(ts|tsx|js|jsx|mdx)'],
+          addons: [
+              // Addons like:
+              // '@storybook/addon-links',
+              // '@storybook/addon-essentials',
+              // '@storybook/addon-interactions'
+          ],
+          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 as any;
+        ```
+
+    -   **.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:** Addons such as `@storybook/addon-links`, `@storybook/addon-essentials`, and `@storybook/addon-interactions` are supported by installing them and adding them to the `addons` array in your configuration.
+
+3. **Add scripts to your package.json**:
+    Add the following scripts to your `package.json` file to work with Storybook:
+
+    ```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.
+
+### Writing Stories
+
+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:
+
+```typescript
+import { HelloWorld } from '../hello-world';
+import { action } from '@storybook/addon-actions';
+import { userEvent, within } from '@storybook/testing-library';
+
+const meta = {
+  title: 'Example/HelloWorld',
+  component: HelloWorld,
+  render: (args) => ({
+    template: <hello-world message.bind="message" on-increment.bind="onIncrement"></hello-world>,
+  }),
+  argTypes: {
+    message: { control: 'text' },
+    onIncrement: { action: 'increment' }
+  }
+};
+
+export default meta;
+
+export const DefaultHelloWorld = {
+  args: {
+    message: "Hello from Storybook!",
+    onIncrement: action('increment')
+  }
+};
+
+export const InteractiveHelloWorld = {
+  args: {
+    message: "Try clicking the button!",
+    onIncrement: action('increment')
+  },
+  play: async ({ canvasElement }) => {
+    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);
+  }
+};
+
+export const NoArgs = {
+  render: () => ({
+    template: <hello-world></hello-world>
+  })
+};
+
+export const WithCustomTemplate = {
+  render: (args) => ({
+    template: <hello-world message.bind="message">Click me!</hello-world>
+  }),
+  args: {
+    message: "This is a custom message"
+  }
+};
+```
+
+### How It Works
+
+- **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.
+
+- **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.
+
+- **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.
+
+## Development
+
+If you wish to contribute or modify the integration:
+
+1. **Build the package** using TypeScript:
+
+   ```bash
+   npm run build
+   ```
+
+2. **Watch for changes** during development:
+
+   ```bash
+   npm run watch
+   ```
+
+3. **Link the package** in your Aurelia project:
+
+   ```bash
+   npm link @aurelia/storybook
+   ```
+
+4. **Run Storybook** in your local Aurelia application to see the integration in action.
+
+## Contributing
+
+Contributions, bug reports, and feature requests are welcome. Please open an issue or submit a pull request on the project repository.
+
+## License
+
+[MIT](LICENSE)
+
+## 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).

package/__tests__/render.test.ts

@@ -0,0 +1,188 @@
+import { STORY_CHANGED } from '@storybook/core-events';
+import { CustomElement } from 'aurelia';
+import {
+  render,
+  renderToCanvas,
+  bootstrapAureliaApp,
+  createComponentTemplate,
+} from '../src/preview/render';
+
+// Add this at the very top of the file, before any imports.
+jest.mock('aurelia', () => {
+  const actual = jest.requireActual('aurelia');
+  return {
+    ...actual,
+    CustomElement: {
+      ...actual.CustomElement,
+      getDefinition: jest.fn().mockReturnValue({
+         name: 'dummy-comp',
+         bindables: { prop: { attribute: 'prop', name: 'prop' } },
+      }),
+    },
+  };
+});
+
+describe('render', () => {
+  it('throws an error when no component is provided', () => {
+    expect(() =>
+      render({}, { id: 'story-1', component: undefined as any } as any)
+    ).toThrowError(
+      'Unable to render story story-1 as the component annotation is missing from the default export'
+    );
+  });
+
+  it('returns the expected object when a component is provided', () => {
+    const DummyComponent = () => {};
+    const args = { foo: 'bar' };
+    const result = render(args, { id: 'story-1', component: DummyComponent as any } as any);
+    expect(result).toEqual({ Component: DummyComponent, props: args, template: '' });
+  });
+});
+
+describe('renderToCanvas', () => {
+  let canvas: HTMLElement;
+  let dummyChannel: { on: jest.Mock; off: jest.Mock };
+  const DummyComponent = class {};
+
+  beforeEach(() => {
+    canvas = document.createElement('div');
+    dummyChannel = { on: jest.fn(), off: jest.fn() } as any;
+  });
+
+  it('calls showError when the story function returns a falsy value', async () => {
+    const storyFn = jest.fn(() => null) as any;
+    const showError = jest.fn() as any;
+    const showMain = jest.fn() as any;
+    const context = {
+      storyFn,
+      title: 'Test Title',
+      name: 'Test Story',
+      showMain,
+      showError,
+      storyContext: {
+        parameters: {},
+        component: DummyComponent as any,
+        args: {},
+        viewMode: 'story',
+        channel: dummyChannel,
+      },
+      forceRemount: false,
+    } as any;
+
+    const cleanup = await renderToCanvas(context, canvas);
+    expect(showError).toHaveBeenCalled();
+    expect(typeof cleanup).toBe('function');
+  });
+
+  it('bootstraps an Aurelia app when none exists or forceRemount is true', async () => {
+    const fakeAurelia = {
+      start: jest.fn().mockResolvedValue(undefined),
+      stop: jest.fn().mockResolvedValue(undefined),
+      root: { controller: { viewModel: {} } },
+    } as any;
+    const story = { template: '<div></div>', props: { test: 'value' } } as any;
+    const storyFn = jest.fn(() => story) as any;
+    const showError = jest.fn() as any;
+    const showMain = jest.fn() as any;
+
+    // Spy on bootstrapAureliaApp to simulate app creation.
+    const bootstrapSpy = jest
+      .spyOn(require('../src/preview/render'), 'bootstrapAureliaApp')
+      .mockReturnValue(fakeAurelia);
+
+    const context = {
+      storyFn,
+      title: 'Test Title',
+      name: 'Test Story',
+      showMain,
+      showError,
+      storyContext: {
+        parameters: { args: { param: 'foo' } },
+        component: DummyComponent as any,
+        args: { test: 'bar' },
+        viewMode: 'story',
+        channel: dummyChannel,
+      },
+      forceRemount: false,
+    } as any;
+
+    const cleanup = await renderToCanvas(context, canvas, bootstrapAureliaApp);
+    expect(showError).not.toHaveBeenCalled();
+    expect(showMain).toHaveBeenCalled();
+    expect(bootstrapSpy).toHaveBeenCalled();
+
+    // Simulate cleanup (which should remove the STORY_CHANGED listener)
+    await cleanup();
+    expect(dummyChannel.off).toHaveBeenCalledWith(
+      STORY_CHANGED,
+      expect.any(Function)
+    );
+    bootstrapSpy.mockRestore();
+  });
+
+  it('updates the existing app viewModel when re-rendering without forceRemount', async () => {
+    // Create a fake Aurelia app with a mutable viewModel.
+    const fakeViewModel: Record<string, any> = {};
+    const fakeAurelia = {
+      start: jest.fn().mockResolvedValue(undefined),
+      stop: jest.fn().mockResolvedValue(undefined),
+      root: { controller: { viewModel: fakeViewModel } },
+    } as any;
+
+    const story = { template: '<div></div>', props: { test: 'initial' } } as any;
+    const storyFn = jest.fn(() => story) as any;
+    const showError = jest.fn() as any;
+    const showMain = jest.fn() as any;
+
+    const bootstrapSpy = jest
+      .spyOn(require('../src/preview/render'), 'bootstrapAureliaApp')
+      .mockReturnValue(fakeAurelia);
+
+    // First render: bootstrap the app.
+    const context = {
+      storyFn,
+      title: 'Title',
+      name: 'Name',
+      showMain,
+      showError,
+      storyContext: {
+        parameters: { args: { param: 'foo' } },
+        component: DummyComponent as any,
+        args: { test: 'bar' },
+        viewMode: 'story',
+        channel: dummyChannel,
+      },
+      forceRemount: false,
+    } as any;
+    await renderToCanvas(context, canvas, bootstrapAureliaApp);
+    expect(bootstrapSpy).toHaveBeenCalledTimes(1);
+
+    // Second render with new args; should update viewModel instead of re-bootstrap.
+    const newStory = { template: '<div></div>', props: { test: 'updated' } } as any;
+    storyFn.mockReturnValueOnce(newStory);
+    const newContext = {
+      ...context,
+      storyContext: {
+        ...context.storyContext,
+        parameters: { args: { param: 'baz' } },
+        args: { test: 'qux' },
+      },
+    } as any;
+    await renderToCanvas(newContext, canvas, bootstrapAureliaApp);
+    expect(bootstrapSpy).toHaveBeenCalledTimes(1);
+    expect(fakeViewModel).toEqual({ param: 'baz', test: 'qux' });
+    bootstrapSpy.mockRestore();
+  });
+});
+
+describe('createComponentTemplate', () => {
+  it('generates the correct template string', () => {
+    const DummyComponent = class {};
+    // The definition is already provided via module mocking.
+
+    const template = createComponentTemplate(DummyComponent as any, '<span>inner</span>');
+    expect(template).toBe(
+      '<dummy-comp prop.bind="prop"><span>inner</span></dummy-comp>'
+    );
+  });
+});

package/dist/__tests__/example.test.js

@@ -0,0 +1,6 @@
+"use strict";
+describe('sample test', () => {
+    it('adds numbers', () => {
+        expect(2 + 2).toBe(4);
+    });
+});

package/dist/__tests__/render.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/render.test.js

@@ -0,0 +1,156 @@
+import { STORY_CHANGED } from '@storybook/core-events';
+import { render, renderToCanvas, bootstrapAureliaApp, createComponentTemplate, } from '../src/preview/render';
+// Add this at the very top of the file, before any imports.
+jest.mock('aurelia', () => {
+    const actual = jest.requireActual('aurelia');
+    return {
+        ...actual,
+        CustomElement: {
+            ...actual.CustomElement,
+            getDefinition: jest.fn().mockReturnValue({
+                name: 'dummy-comp',
+                bindables: { prop: { attribute: 'prop', name: 'prop' } },
+            }),
+        },
+    };
+});
+describe('render', () => {
+    it('throws an error when no component is provided', () => {
+        expect(() => render({}, { id: 'story-1', component: undefined })).toThrowError('Unable to render story story-1 as the component annotation is missing from the default export');
+    });
+    it('returns the expected object when a component is provided', () => {
+        const DummyComponent = () => { };
+        const args = { foo: 'bar' };
+        const result = render(args, { id: 'story-1', component: DummyComponent });
+        expect(result).toEqual({ Component: DummyComponent, props: args, template: '' });
+    });
+});
+describe('renderToCanvas', () => {
+    let canvas;
+    let dummyChannel;
+    const DummyComponent = class {
+    };
+    beforeEach(() => {
+        canvas = document.createElement('div');
+        dummyChannel = { on: jest.fn(), off: jest.fn() };
+    });
+    it('calls showError when the story function returns a falsy value', async () => {
+        const storyFn = jest.fn(() => null);
+        const showError = jest.fn();
+        const showMain = jest.fn();
+        const context = {
+            storyFn,
+            title: 'Test Title',
+            name: 'Test Story',
+            showMain,
+            showError,
+            storyContext: {
+                parameters: {},
+                component: DummyComponent,
+                args: {},
+                viewMode: 'story',
+                channel: dummyChannel,
+            },
+            forceRemount: false,
+        };
+        const cleanup = await renderToCanvas(context, canvas);
+        expect(showError).toHaveBeenCalled();
+        expect(typeof cleanup).toBe('function');
+    });
+    it('bootstraps an Aurelia app when none exists or forceRemount is true', async () => {
+        const fakeAurelia = {
+            start: jest.fn().mockResolvedValue(undefined),
+            stop: jest.fn().mockResolvedValue(undefined),
+            root: { controller: { viewModel: {} } },
+        };
+        const story = { template: '<div></div>', props: { test: 'value' } };
+        const storyFn = jest.fn(() => story);
+        const showError = jest.fn();
+        const showMain = jest.fn();
+        // Spy on bootstrapAureliaApp to simulate app creation.
+        const bootstrapSpy = jest
+            .spyOn(require('../src/preview/render'), 'bootstrapAureliaApp')
+            .mockReturnValue(fakeAurelia);
+        const context = {
+            storyFn,
+            title: 'Test Title',
+            name: 'Test Story',
+            showMain,
+            showError,
+            storyContext: {
+                parameters: { args: { param: 'foo' } },
+                component: DummyComponent,
+                args: { test: 'bar' },
+                viewMode: 'story',
+                channel: dummyChannel,
+            },
+            forceRemount: false,
+        };
+        const cleanup = await renderToCanvas(context, canvas, bootstrapAureliaApp);
+        expect(showError).not.toHaveBeenCalled();
+        expect(showMain).toHaveBeenCalled();
+        expect(bootstrapSpy).toHaveBeenCalled();
+        // Simulate cleanup (which should remove the STORY_CHANGED listener)
+        await cleanup();
+        expect(dummyChannel.off).toHaveBeenCalledWith(STORY_CHANGED, expect.any(Function));
+        bootstrapSpy.mockRestore();
+    });
+    it('updates the existing app viewModel when re-rendering without forceRemount', async () => {
+        // Create a fake Aurelia app with a mutable viewModel.
+        const fakeViewModel = {};
+        const fakeAurelia = {
+            start: jest.fn().mockResolvedValue(undefined),
+            stop: jest.fn().mockResolvedValue(undefined),
+            root: { controller: { viewModel: fakeViewModel } },
+        };
+        const story = { template: '<div></div>', props: { test: 'initial' } };
+        const storyFn = jest.fn(() => story);
+        const showError = jest.fn();
+        const showMain = jest.fn();
+        const bootstrapSpy = jest
+            .spyOn(require('../src/preview/render'), 'bootstrapAureliaApp')
+            .mockReturnValue(fakeAurelia);
+        // First render: bootstrap the app.
+        const context = {
+            storyFn,
+            title: 'Title',
+            name: 'Name',
+            showMain,
+            showError,
+            storyContext: {
+                parameters: { args: { param: 'foo' } },
+                component: DummyComponent,
+                args: { test: 'bar' },
+                viewMode: 'story',
+                channel: dummyChannel,
+            },
+            forceRemount: false,
+        };
+        await renderToCanvas(context, canvas, bootstrapAureliaApp);
+        expect(bootstrapSpy).toHaveBeenCalledTimes(1);
+        // Second render with new args; should update viewModel instead of re-bootstrap.
+        const newStory = { template: '<div></div>', props: { test: 'updated' } };
+        storyFn.mockReturnValueOnce(newStory);
+        const newContext = {
+            ...context,
+            storyContext: {
+                ...context.storyContext,
+                parameters: { args: { param: 'baz' } },
+                args: { test: 'qux' },
+            },
+        };
+        await renderToCanvas(newContext, canvas, bootstrapAureliaApp);
+        expect(bootstrapSpy).toHaveBeenCalledTimes(1);
+        expect(fakeViewModel).toEqual({ param: 'baz', test: 'qux' });
+        bootstrapSpy.mockRestore();
+    });
+});
+describe('createComponentTemplate', () => {
+    it('generates the correct template string', () => {
+        const DummyComponent = class {
+        };
+        // The definition is already provided via module mocking.
+        const template = createComponentTemplate(DummyComponent, '<span>inner</span>');
+        expect(template).toBe('<dummy-comp prop.bind="prop"><span>inner</span></dummy-comp>');
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { renderToCanvas } from './preview/render';
+export { renderToCanvas };
+export declare const render: typeof renderToCanvas;

package/dist/index.js

@@ -0,0 +1,3 @@
+import { renderToCanvas } from './preview/render';
+export { renderToCanvas };
+export const render = renderToCanvas;

package/dist/preset.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Optionally adjust the Vite configuration.
+ */
+export declare function viteFinal(config: any): Promise<any>;
+declare const _default: {
+    viteFinal: typeof viteFinal;
+};
+export default _default;

package/dist/preset.js

@@ -0,0 +1,11 @@
+// src/preset.ts
+// Minimal preset for Storybook-Aurelia2
+/**
+ * Optionally adjust the Vite configuration.
+ */
+export async function viteFinal(config) {
+    // For now, return the config unchanged.
+    return config;
+}
+// Export a default for compatibility.
+export default { viteFinal };

package/dist/preview/render.d.ts

@@ -0,0 +1,17 @@
+import type { RenderContext, ArgsStoryFn } from '@storybook/types';
+import type { AureliaRenderer } from './types';
+import Aurelia, { Constructable } from 'aurelia';
+interface AureliaStoryResult {
+    template: string;
+    components?: unknown[];
+    Component?: unknown;
+    container?: any;
+    items?: unknown[];
+    innerHtml?: string;
+    props?: Record<string, any>;
+}
+export declare const render: ArgsStoryFn<AureliaRenderer>;
+export declare function renderToCanvas({ storyFn, title, name, showMain, showError, storyContext, forceRemount, }: RenderContext<AureliaRenderer>, canvasElement: HTMLElement): Promise<() => void>;
+export declare function bootstrapAureliaApp(story: AureliaStoryResult, args: Record<string, any>, domElement: HTMLElement, component?: Constructable): Omit<Aurelia, "enhance" | "register" | "app">;
+export declare function createComponentTemplate(component: Constructable, innerHtml?: string): string;
+export {};