@aurelia/故事书

@aurelia/storybook 运行 Aurelia 2 组件 在故事书 10 。 它提供渲染器,构建器预设,CSF类型,可绑定控制,docs支持,可移植故事,以及从一等故事书框架所期望的测试集成.

该框架与Vite、Webpack 5和Rsbuilding/Rspack合作。 你准备好了 component 在故事元数据中写出正常的"故事本"故事; 里面没有渲染器锅炉板 .storybook/preview.ts。 。 。 .

兼容性

奥雷利亚 2.0.0-rc.2 支持Vite 8的Oxc管道,包括TC39装饰. 不需要额外的 Babel 或 SWC 配置 .

何谓有效

• CSF 3 和输入的 CSF 工厂, 装有装饰器、装入器、 全球器、 标签、 故事扩展和 run
• 自动组件渲染, 将可装订的组件映射到 Storybook 参数和控件
• 通过操作和互动测试 storybook/test
• 播放函数 mount
• 自动文档, MDX, 可绑定的参数类型、 组件描述和动态 Aurelia 源标记
• 故事层面和全球Aurelia资源、DI注册、容器和设置钩
• live arg 更新而不重新启动 Aurelia app; 结构变化 清空重挂载
• 便携式故事通过 composeStory, (中文(简体) ), composeStories,以及 setProjectAnnotations
• Vite、Webpack 5和Rsbuilt/Rspack开发和静态建筑
• 故事书的Vitest addon 运行真正的铬测试

安装

从您的构建者的命令开始 。 已存在的 Aurelia app 通常已有 Aurelia 构建器插件或加载器 .

维特

npm install --save-dev @aurelia/storybook storybook @storybook/builder-vite @aurelia/vite-plugin

Vite 7和Vite 8获得支持. 使用 Vite 8 时 @aurelia/vite-plugin 2.0.0-rc.2 或更新.

网页包 5

npm install --save-dev @aurelia/storybook storybook @storybook/builder-webpack5 @aurelia/webpack-loader ts-loader

建设/包装

npm install --save-dev @aurelia/storybook storybook storybook-builder-rsbuild @rsbuild/core @aurelia/webpack-loader

添加 @storybook/addon-docs, (中文(简体) ), @storybook/addon-a11y,并视需要提供其他补充.

配置故事书

对于 Vite , 创建 .storybook/main.ts数字 :

import { defineMain } from '@aurelia/storybook/node';

export default defineMain({
  stories: ['../src/**/*.@(mdx|stories.@(ts|js))'],
  addons: ['@storybook/addon-docs', '@storybook/addon-a11y'],
  framework: {
    name: '@aurelia/storybook',
    options: {},
  },
  core: {
    builder: '@storybook/builder-vite',
  },
});

框架预设在故事本配置还没有时会添加Aurelia Vite插件. 也使Aurelia的运行时包脱离了Vite依赖性预捆绑,因此渲染器和组件使用一个运行时实例.

Webpack 用不同的构建器使用相同的文件 :

core: {
  builder: '@storybook/builder-webpack5',
},

预设添加 ts-loader 财务报告和审定财务报表 @aurelia/webpack-loader 规则一次,保留任何已经在配置中的规则.

用于 Rsbuilding,使用:

core: {
  builder: 'storybook-builder-rsbuild',
},

Rsbuild预设增加了相匹配的Aurelia Rspack规则.

 .storybook/preview.ts 包含工程设置和附加类型 :

import { definePreview } from '@aurelia/storybook';
import addonA11y from '@storybook/addon-a11y';
import addonDocs from '@storybook/addon-docs';

export default definePreview({
  addons: [addonA11y(), addonDocs()],
  tags: ['autodocs'],
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
});

不导出 render 或者说 renderToCanvas 从预览文件。 故事本从框架预设中加载它们.

上面的工厂表可以输入故事本 preview.meta 财务报告和审定财务报表 meta.story APIs (英语). 使用正则对象 satisfies Preview 继续支助CSF 3项目.

添加常用脚本 :

{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  }
}

写故事

故事书的CSF 工厂 API 推断 Aurelia 组件实例、附加参数、装饰器和故事参数:

import preview from '../../.storybook/preview';
import { expect, fn, userEvent } from 'storybook/test';
import { HelloWorld } from '../hello-world';

const meta = preview.meta({
  title: 'Example/HelloWorld',
  component: HelloWorld,
  args: {
    message: 'Hello from Storybook',
    onIncrement: fn(),
  },
});

export const Default = meta.story({
  play: async ({ args, canvas }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'Increment' }));
    await expect(args.onIncrement).toHaveBeenCalledWith(1);
  },
});

export const Renamed = Default.extend({
  args: { message: 'Extended story' },
});

工厂故事也揭露了故事书的元数据, run, (中文(简体) ), extend,测试API。 当项目倾向于物品出口时,CSF 3仍然可用.

自动渲染覆盖了普通大小写 :

import type { Meta, StoryObj } from '@aurelia/storybook';
import { fn, userEvent, within } from 'storybook/test';
import { HelloWorld } from '../hello-world';

const meta = {
  title: 'Example/HelloWorld',
  component: HelloWorld,
  args: {
    message: 'Hello from Storybook',
    onIncrement: fn(),
  },
  argTypes: {
    message: { control: 'text' },
    onIncrement: { action: 'increment' },
  },
} satisfies Meta<typeof HelloWorld>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Default = {} satisfies Story;

export const Interaction = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    await userEvent.click(canvas.getByRole('button', { name: 'Increment' }));
  },
} satisfies Story;

生成的 Aurelia 模板只绑定了存在的参数 。 Oncentables 保存组件自身的默认值. 添加或去除可绑定的参数重挂已生成的模板;更改已存在的值更新运行中的视图模型.

自定义模板和计划内容

使用 defineAureliaStory 当组件需要具体标记、本地资源或预测内容时:

import {
  defineAureliaStory,
  type Meta,
  type StoryObj,
} from '@aurelia/storybook';
import { CardHeading } from '../card-heading';
import { ProductCard } from '../product-card';

const meta = {
  component: ProductCard,
} satisfies Meta<typeof ProductCard>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Detailed = {
  render: (args) =>
    defineAureliaStory({
      template: `
        <product-card product.bind="product">
          <card-heading>Featured</card-heading>
        </product-card>
      `,
      props: args,
      register: [ProductCard, CardHeading],
    }),
  args: {
    product: { name: 'Desk lamp' },
  },
} satisfies Story;

故事结果可以包含:

渲染函数也可能直接返回模板字符串或Aurelia自定义元素类.

Aurelia 配置

为预览、组件组或单个故事注册资源 parameters.aurelia数字 :

import { Registration } from 'aurelia';
import type { Preview } from '@aurelia/storybook';
import { FeatureFlags } from '../src/feature-flags';
import { MoneyValueConverter } from '../src/money-value-converter';

const preview = {
  parameters: {
    aurelia: {
      register: [MoneyValueConverter],
      configureContainer: (container) => {
        container.register(
          Registration.instance(FeatureFlags, { newCheckout: true })
        );
      },
      configure: (aurelia, context) => {
        // Configure the app before it starts.
      },
    },
  },
} satisfies Preview;

export default preview;

全包设置, 使用 setup 从 .storybook/preview.ts数字 :

import { setup } from '@aurelia/storybook';

setup(async (aurelia, context) => {
  // Runs for every newly mounted story app.
});

setup 返回未注册函数,该函数在测试环境中有用.

从播放函数挂起

结构 mount 当播放函数控制初始渲染时 :

import { expect } from 'storybook/test';

export const MountedByPlay = {
  play: async ({ mount }) => {
    const canvas = await mount({
      Component: HelloWorld,
      props: { message: 'Mounted from play' },
    });

    await expect(canvas.getByText('Mounted from play')).toBeVisible();
  },
};

故事书检测到已解结构的参数,并在运行故事后检查前等待这个挂载.

文档和MDX

添加 @storybook/addon-docs 以启用 autodocs 和 MDX。 Aurelia 可绑定物出现在 bindables 类别,和动态源块显示故事使用的 Aurelia 标记。 设定 parameters.docs.source.code 当一个故事需要一个手写源的例子时.

常规故事书 MDX 工作没有奥雷利亚特有的包装:

import { Meta, Canvas } from '@storybook/addon-docs/blocks';
import * as Stories from './hello-world.stories';

<Meta of={Stories} />

# Hello World

<Canvas of={Stories.Default} />

Vest 浏览器测试

故事书"Vitest"的"addon"可以在Chrimium运行同样的故事. 扩展该应用程序的 Vite 配置, 以便测试项目得到一个完全的 Aurelia 插件实例 :

import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
import { playwright } from '@vitest/browser-playwright';
import { defineConfig } from 'vitest/config';

const dirname = path.dirname(fileURLToPath(import.meta.url));

export default defineConfig({
  test: {
    projects: [
      {
        extends: './vite.config.ts',
        plugins: [
          storybookTest({ configDir: path.join(dirname, '.storybook') }),
        ],
        test: {
          name: 'storybook',
          browser: {
            enabled: true,
            headless: true,
            provider: playwright({}),
            instances: [{ browser: 'chromium' }],
          },
        },
      },
    ],
  },
});

不添加另一个 aurelia() 当扩展的 Vite 配置已经拥有时, 请调用此工程 。 将奥雷利亚公约模板两次将第一个生成的模块变为模板文本.

Vite 8 和工厂预览, 预装该预览导入的附加入口 。 这使得Vite无法在发现浏览器时重新加载首个浏览器测试运行:

optimizeDeps: {
  include: [
    '@storybook/addon-a11y',
    '@storybook/addon-docs',
    '@storybook/addon-vitest',
    'storybook/internal/csf',
  ],
},

便携式故事

该套件输出Aurelia-aware可移植-故事帮助:

import { composeStories } from '@aurelia/storybook/portable-stories';
import * as stories from './hello-world.stories';

const { Default } = composeStories(stories);

await Default.run();

何时 .storybook/preview.ts 导出一个 CSF 3 配置对象, 使用 setProjectAnnotations 一次在一个测试设置文件中,如此可移植的故事收到:

import { setProjectAnnotations } from '@aurelia/storybook/portable-stories';
import preview from '../.storybook/preview';

setProjectAnnotations(preview);

国别服务框架 工厂故事已经带有预览说明. 导入一个并拨打 await Story.run() 直接代替再编组.

发展

这个寄存器是一个npm工作空间,包含框架和Vite,Webpack,和Rsbuild等实例.

npm ci
npm run sync:versions:check
npm run lint
npm run typecheck
npm test
npm run build
npm run lint:examples
npm run typecheck:examples
npm run test:examples
npm run build:examples
npm run build:storybooks
npm run test:storybook

npm run test:storybook 需要一个铬二进制。 安装它 npx playwright install chromium 如果Playwright还没有这样做.

许可证

麻省理工学院