@aurelia/storybook 0.1.1 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Dwayne Charrington
+Copyright (c) 2025 aurelia
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,12 +1,12 @@
 # @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.
+> **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.
 
-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.
+This package provides an integration between Aurelia 2 and Storybook 8 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.
 
 ## Features
 
-- **Vite-Powered Build**: Uses Vite (via the provided preset) to bundle your stories.
+- **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 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.
@@ -87,6 +87,34 @@ To integrate Aurelia 2 with your Storybook instance, follow these steps:
 
     > **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.
 
+    ### Using with Webpack
+
+    If you prefer to use Webpack instead of Vite, update your `.storybook/main.ts` configuration:
+
+    ```typescript
+    import type { StorybookConfig } from '@storybook/core-common';
+
+    const config: StorybookConfig = {
+      stories: ['../src/**/*.stories.@(ts|tsx|js|jsx|mdx)'],
+      addons: [
+        '@storybook/addon-webpack5-compiler-swc',
+        '@storybook/addon-links',
+        '@storybook/addon-essentials'
+      ],
+      framework: {
+        name: '@aurelia/storybook',
+        options: {},
+      },
+      core: {
+        builder: '@storybook/builder-webpack5',
+      },
+    };
+
+    export default config;
+    ```
+
+    The `.storybook/preview.ts` file remains the same for both Vite and Webpack configurations.
+
 3. **Add scripts to your package.json**:
     Add the following scripts to your `package.json` file to work with Storybook:
 

package/__tests__/preset.test.ts

@@ -0,0 +1,49 @@
+import { webpackFinal, viteFinal } from '../src/preset';
+import { getRules } from '../src/webpack';
+
+jest.mock('../src/webpack', () => ({
+  getRules: jest.fn(() => [
+    { test: /\.ts$/, use: 'ts-loader' },
+    { test: /\.html$/, use: 'html-loader' },
+  ]),
+}));
+
+describe('preset', () => {
+  describe('webpackFinal', () => {
+    it('should add rules to the webpack config', async () => {
+      const config = {
+        module: {
+          rules: [],
+        },
+      };
+      const result = await webpackFinal(config);
+      expect(result.module.rules).toEqual(getRules());
+      expect(getRules).toHaveBeenCalled();
+    });
+
+    it('should handle a config with no module.rules', async () => {
+      const config = {};
+      const result = await webpackFinal(config);
+      expect(result).toEqual(config);
+    });
+
+    it('should handle a config with existing rules', async () => {
+      const existingRule = { test: /\.js$/, use: 'babel-loader' };
+      const config = {
+        module: {
+          rules: [existingRule],
+        },
+      };
+      const result = await webpackFinal(config);
+      expect(result.module.rules).toEqual([existingRule, ...getRules()]);
+    });
+  });
+
+  describe('viteFinal', () => {
+    it('should return the config unchanged', async () => {
+      const config = { some: 'property' };
+      const result = await viteFinal(config);
+      expect(result).toBe(config);
+    });
+  });
+}); 

package/__tests__/preview.test.ts

@@ -0,0 +1,139 @@
+import { render } from '../src/preview';
+import * as renderUtils from '../src/preview/render';
+
+jest.mock('../src/preview/render', () => ({
+  ...jest.requireActual('../src/preview/render'),
+  bootstrapAureliaApp: jest.fn(),
+}));
+
+describe('preview', () => {
+  let bootstrapAureliaAppSpy: jest.SpyInstance;
+  let fakeAureliaApp: { start: jest.Mock; stop: jest.Mock };
+
+  beforeEach(() => {
+    bootstrapAureliaAppSpy = jest.spyOn(renderUtils, 'bootstrapAureliaApp');
+    fakeAureliaApp = {
+      start: jest.fn().mockResolvedValue(undefined),
+      stop: jest.fn().mockResolvedValue(undefined),
+    };
+    bootstrapAureliaAppSpy.mockReturnValue(fakeAureliaApp);
+    document.body.innerHTML = '';
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should return a container element', () => {
+    const context = {
+      storyFn: () => ({ Component: class {} }),
+      component: class {},
+    };
+    const container = render({}, context);
+    expect(container).toBeInstanceOf(HTMLElement);
+    expect(container.tagName).toBe('DIV');
+  });
+
+  it('should call storyFn', () => {
+    const storyFn = jest.fn(() => ({ Component: class {} }));
+    const context = {
+      storyFn,
+      component: class {},
+    };
+    render({}, context);
+    expect(storyFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should not bootstrap Aurelia if story has no Component or template', () => {
+    const context = {
+      storyFn: () => ({}),
+      component: class {},
+    };
+    render({}, context);
+    expect(bootstrapAureliaAppSpy).not.toHaveBeenCalled();
+  });
+
+  it('should bootstrap Aurelia if story has a Component', () => {
+    const DummyComponent = class {};
+    const context = {
+      storyFn: () => ({ Component: DummyComponent }),
+      component: class {},
+    };
+    const args = { a: 1 };
+    const container = render(args, context);
+    expect(bootstrapAureliaAppSpy).toHaveBeenCalledWith(
+      { Component: DummyComponent },
+      args,
+      container,
+      DummyComponent
+    );
+    expect(fakeAureliaApp.start).toHaveBeenCalled();
+  });
+
+  it('should bootstrap Aurelia if story has a template', () => {
+    const template = '<div></div>';
+    const context = {
+      storyFn: () => ({ template }),
+      component: class {},
+    };
+    const args = { a: 1 };
+    const container = render(args, context);
+    expect(bootstrapAureliaAppSpy).toHaveBeenCalledWith(
+      { template },
+      args,
+      container,
+      context.component
+    );
+    expect(fakeAureliaApp.start).toHaveBeenCalled();
+  });
+
+  it('should call cleanup for the previous story', () => {
+    const storyFn1 = () => ({ Component: class {} });
+    const storyFn2 = () => ({ template: 'hello' });
+
+    // First render
+    render({}, { storyFn: storyFn1, component: class {} });
+
+    // Second render
+    render({}, { storyFn: storyFn2, component: class {} });
+
+    expect(fakeAureliaApp.stop).toHaveBeenCalledTimes(1);
+  });
+
+  it('should handle Aurelia start failure', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    const error = new Error('Failed to start');
+    fakeAureliaApp.start.mockRejectedValue(error);
+
+    const context = {
+      storyFn: () => ({ Component: class {} }),
+      component: class {},
+    };
+    
+    render({}, context);
+    
+    // allow microtasks to run
+    await new Promise(resolve => setTimeout(resolve, 0));
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith('Failed to start Aurelia app:', error);
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('should handle Aurelia stop failure', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    const error = new Error('Failed to stop');
+    fakeAureliaApp.stop.mockRejectedValue(error);
+  
+    // First render
+    render({}, { storyFn: () => ({ Component: class {} }), component: class {} });
+  
+    // Second render to trigger cleanup
+    render({}, { storyFn: () => ({ Component: class {} }), component: class {} });
+    
+    // allow microtasks to run
+    await new Promise(resolve => setTimeout(resolve, 0));
+  
+    expect(consoleErrorSpy).toHaveBeenCalledWith('Failed to stop Aurelia app:', error);
+    consoleErrorSpy.mockRestore();
+  });
+}); 

package/__tests__/render.test.ts

@@ -1,5 +1,4 @@
 import { STORY_CHANGED } from '@storybook/core-events';
-import { CustomElement } from 'aurelia';
 import {
   render,
   renderToCanvas,

package/__tests__/webpack.test.ts

@@ -0,0 +1,21 @@
+import { getRules } from '../src/webpack';
+
+describe('webpack', () => {
+  describe('getRules', () => {
+    it('should return the correct rules', () => {
+      const rules = getRules();
+      expect(rules).toEqual([
+        {
+          test: /\.ts$/i,
+          use: ['ts-loader', '@aurelia/webpack-loader'],
+          exclude: /node_modules/,
+        },
+        {
+          test: /\.html$/i,
+          use: '@aurelia/webpack-loader',
+          exclude: /node_modules/,
+        },
+      ]);
+    });
+  });
+}); 

package/apps/hello-world/.storybook/main.ts

@@ -0,0 +1,30 @@
+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: [
+    '@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;

package/apps/hello-world/.storybook/preview.ts

@@ -0,0 +1 @@
+export { render, renderToCanvas } from '@aurelia/storybook';

package/apps/hello-world/.stylelintrc.json

@@ -0,0 +1,5 @@
+{
+  "extends": [
+    "stylelint-config-standard"
+  ]
+}

package/apps/hello-world/.yarnrc.yml

@@ -0,0 +1,2 @@
+# For compatibility in yarn 2+
+nodeLinker: node-modules

package/apps/hello-world/README.md

@@ -0,0 +1,28 @@
+# Aurelia Storybook Hello World
+
+This project is bootstrapped by [aurelia/new](https://github.com/aurelia/new).
+
+## Start dev web server
+
+    npm start
+
+## Start Storybook
+
+    npm run storybook
+
+## Build the app in production mode
+
+    npm run build
+
+## Build Storybook
+
+    npm run build-storybook
+
+## Unit Tests
+
+    npm run test
+
+Run unit tests in watch mode.
+
+    npm run test:watch
+

package/apps/hello-world/eslint.config.mjs

@@ -0,0 +1,25 @@
+import eslint from "@eslint/js";
+import tseslint from 'typescript-eslint';
+import tsParser from "@typescript-eslint/parser";
+import globals from "globals";
+
+export default [
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ["**/*.ts"],
+
+    languageOptions: {
+      globals: {
+        ...globals.builtin,
+        ...globals.nodeBuiltin,
+        ...globals.browser,
+        ...globals.node,
+      },
+
+      parser: tsParser,
+      ecmaVersion: 2019,
+      sourceType: "module",
+    },
+  }
+];

package/apps/hello-world/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="utf-8">
+  <title>Aurelia</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <script type="module" src="/src/main.ts"></script>
+  <base href="/">
+</head>
+
+<body>
+  <my-app></my-app>
+</body>
+
+</html>
+

package/apps/hello-world/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "apptasks-video",
+  "description": "An Aurelia 2 client application.",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "???"
+  },
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@aurelia/router": "^2.0.0-beta.24",
+    "@aurelia/validation": "^2.0.0-beta.24",
+    "@aurelia/validation-html": "^2.0.0-beta.24",
+    "aurelia": "^2.0.0-beta.24"
+  },
+  "devDependencies": {
+    "@aurelia/storybook": "^0.1.1",
+    "@aurelia/testing": "^2.0.0-beta.24",
+    "@aurelia/vite-plugin": "^2.0.0-beta.24",
+    "@storybook/addon-actions": "^8.5.3",
+    "@storybook/addon-essentials": "^8.5.3",
+    "@storybook/addon-interactions": "^8.5.3",
+    "@storybook/addon-links": "^8.5.3",
+    "@storybook/builder-vite": "^8.5.3",
+    "@storybook/core-common": "^8.5.3",
+    "@storybook/preview-api": "^8.5.3",
+    "@storybook/testing-library": "^0.2.1",
+    "@storybook/types": "^8.5.3",
+    "@tailwindcss/vite": "^4.0.0",
+    "@types/node": "^22.10.2",
+    "eslint": "^9.17.0",
+    "globals": "^15.14.0",
+    "jsdom": "^25.0.1",
+    "node-html-parser": "^7.0.1",
+    "sass": "^1.83.4",
+    "stylelint": "^16.12.0",
+    "stylelint-config-standard": "^36.0.1",
+    "stylus": "^0.64.0",
+    "tailwindcss": "^4.0.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.1",
+    "vite": "^6.0.3",
+    "vite-plugin-node-polyfills": "^0.22.0",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "lint:js": "eslint src test",
+    "lint:css": "stylelint \"src/**/*.css\"",
+    "lint": "npm run lint:js && npm run lint:css",
+    "pretest": "npm run lint",
+    "start": "vite",
+    "build": "vite build",
+    "test": "vitest",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  },
+  "type": "module",
+  "overrides": {
+    "vite-plugin-node-polyfills": {
+      "vite": "^6.0.0"
+    }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
+}

package/apps/hello-world/src/hello-world.html

@@ -0,0 +1,6 @@
+<div style="border: 1px solid #ccc; padding: 16px; border-radius: 4px;">
+  <h1>${message}</h1>
+  <p>Counter: ${counter}</p>
+  <button click.trigger="increment()">Increment</button>
+  <au-slot></au-slot>
+</div>

package/apps/hello-world/src/hello-world.ts

@@ -0,0 +1,17 @@
+import { bindable } from 'aurelia';
+
+export class HelloWorld {
+  @bindable() message = 'Hello from Aurelia!';
+  // New reactive counter property to track number of clicks
+  counter = 0;
+  // New bindable event callback for the increment action
+  @bindable() onIncrement;
+
+  // Method to increment the counter and fire the onIncrement callback if provided.
+  increment() {
+    this.counter++;
+    if (this.onIncrement) {
+      this.onIncrement(this.counter);
+    }
+  }
+}

package/apps/hello-world/src/main.ts

@@ -0,0 +1,6 @@
+import Aurelia from 'aurelia';
+import { MyApp } from './my-app';
+
+Aurelia
+  .app(MyApp)
+  .start();

package/apps/hello-world/src/my-app.html

@@ -0,0 +1 @@
+<h1>Hello World</h1>

package/apps/hello-world/src/my-app.ts

@@ -0,0 +1,3 @@
+export class MyApp {
+  // Your app logic
+}

package/apps/hello-world/src/resource.d.ts

@@ -0,0 +1,15 @@
+declare module '*.html' {
+  import { IContainer, PartialBindableDefinition } from 'aurelia';
+  export const name: string;
+  export const template: string;
+  export default template;
+  export const dependencies: string[];
+  export const containerless: boolean | undefined;
+  export const bindables: Record<string, PartialBindableDefinition>;
+  export const shadowOptions: { mode: 'open' | 'closed' } | undefined;
+  export function register(container: IContainer): void;
+}
+
+declare module '*.css';
+
+declare module '*.au';

package/apps/hello-world/src/stories/hello-world.stories.ts

@@ -0,0 +1,53 @@
+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');
+    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"
+  }
+};

package/apps/hello-world/test/my-app.spec.ts

@@ -0,0 +1,15 @@
+import { describe, it } from 'vitest';
+import { MyApp } from '../src/my-app';
+import { createFixture } from '@aurelia/testing';
+
+describe('my-app', () => {
+  it('should render message', async () => {
+    const { assertText } = await createFixture(
+      '<my-app></my-app>',
+      {},
+      [MyApp],
+    ).started;
+
+    assertText('Hello World!', { compact: true });
+  });
+});

package/apps/hello-world/test/setup.ts

@@ -0,0 +1,29 @@
+import { BrowserPlatform } from '@aurelia/platform-browser';
+import { setPlatform, onFixtureCreated, type IFixture } from '@aurelia/testing';
+import { beforeAll, afterEach } from 'vitest';
+
+// Sets up the Aurelia environment for testing
+function bootstrapTextEnv() {
+  const platform = new BrowserPlatform(window);
+  setPlatform(platform);
+  BrowserPlatform.set(globalThis, platform);
+}
+
+const fixtures: IFixture<object>[] = [];
+beforeAll(() => {
+  bootstrapTextEnv();
+  onFixtureCreated(fixture => {
+    fixtures.push(fixture);
+  });
+});
+
+afterEach(() => {
+  fixtures.forEach(async f => {
+    try {
+      await f.stop(true);
+    } catch {
+      // ignore
+    }
+  });
+  fixtures.length = 0;
+});

package/apps/hello-world/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "node",
+    "skipLibCheck": true,
+    "target": "ES2017",
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "importHelpers": true,
+    "sourceMap": true
+  },
+  "include": [
+    "src"
+, "aurelia-sfc-plugin.js"  ],
+  "files": [
+    "src/resource.d.ts"
+  ]
+}

package/apps/hello-world/tsconfig.vitest.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.vitest.tsbuildinfo",
+    "types": [
+      "node",
+      "jsdom"
+    ]
+  }
+}

package/apps/hello-world/vite.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vite';
+import { nodePolyfills } from 'vite-plugin-node-polyfills'
+import aurelia from '@aurelia/vite-plugin';
+
+export default defineConfig({
+  server: {
+    open: !process.env.CI,
+    port: 9000,
+  },
+  esbuild: {
+    target: 'es2022'
+  },
+  plugins: [
+    aurelia({
+      useDev: true,
+    }),
+    nodePolyfills(),
+  ],
+});