@aurelia/storybook 0.1.1 → 1.0.1

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,14 +1,14 @@
 # @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 9 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.
+- **Storybook 9 Compatibility**: Fully compatible with Storybook 9's new rendering API.
 - **Arg & Action Support**: Use story args and actions as you would with any Storybook story.
 
 ## Installation
@@ -22,7 +22,13 @@ 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
+npm install --save-dev storybook @storybook/builder-vite
+```
+
+For testing functionality, you may also want to install:
+
+```bash
+npm install --save-dev @storybook/test @storybook/addon-actions
 ```
 
 > **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).
@@ -43,16 +49,14 @@ To integrate Aurelia 2 with your Storybook instance, follow these steps:
         Create or update your `.storybook/main.ts` file with the following contents:
 
         ```typescript
-        import type { StorybookConfig } from '@storybook/core-common';
-        import { mergeConfig } from 'vite';
+        import type { StorybookConfig } from 'storybook/internal/types';
+        import { mergeConfig, type InlineConfig } from 'vite';
 
-        const config: StorybookConfig & { viteFinal?: (config: any, options: any) => any } = {
+        const config: StorybookConfig & { viteFinal?: (config: InlineConfig, options: { configType: string }) => InlineConfig | Promise<InlineConfig> } = {
           stories: ['../src/stories/**/*.stories.@(ts|tsx|js|jsx|mdx)'],
           addons: [
-              // Addons like:
-              // '@storybook/addon-links',
-              // '@storybook/addon-essentials',
-              // '@storybook/addon-interactions'
+              // Additional addons (essentials are now built into Storybook 9 core):
+              '@storybook/addon-links'
           ],
           framework: {
             name: '@aurelia/storybook',
@@ -73,7 +77,7 @@ To integrate Aurelia 2 with your Storybook instance, follow these steps:
           },
         };
 
-        export default config as any;
+        export default config;
         ```
 
     -   **.storybook/preview.ts**
@@ -85,7 +89,34 @@ To integrate Aurelia 2 with your Storybook instance, follow these steps:
         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.
+    > **Note:** Essential features like actions, controls, backgrounds, and viewport are now built into Storybook 9 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-webpack5-compiler-swc',
+        '@storybook/addon-links'
+      ],
+      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:
@@ -105,7 +136,7 @@ Aurelia 2 stories are written similarly to standard Storybook stories, with a fe
 ```typescript
 import { HelloWorld } from '../hello-world';
 import { action } from '@storybook/addon-actions';
-import { userEvent, within } from '@storybook/testing-library';
+import { userEvent, within } from '@storybook/test';
 
 const meta = {
   title: 'Example/HelloWorld',
@@ -186,13 +217,7 @@ If you wish to contribute or modify the integration:
    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.
+3. **Run Storybook** in your local application to see the integration in action.
 
 ## Contributing
 

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 { STORY_CHANGED } from 'storybook/internal/core-events';
 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,28 @@
+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: [
+    '@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;

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>
+