AAE-40269 Add storybook v10 (#11401)

2026-09-09 18:03:21 +00:00 · 2026-01-09 18:17:43 +00:00
parent f0c6cc0ff7
commit 5f9de1fde8
119 changed files with 11010 additions and 753 deletions
@@ -0,0 +1,81 @@
+# Adding a New Story
+
+This guide describes how to create and structure a new story for a component in the Alfresco Angular Components repository.
+
+## File Location
+
+Story files should be co-located with the component they are documenting. This keeps the stories close to the source code and makes them easier to find and maintain.
+
+## Naming Convention
+
+The file should be named using the pattern:
+`[component-name].stories.ts`
+
+For example, if your component is `my-component.component.ts`, the story file should be `my-component.component.stories.ts`.
+
+## Basic Structure
+
+A typical story file includes:
+
+1.  Imports for `Meta`, `Story`, `moduleMetadata` from `@storybook/angular`.
+2.  The component configuration using `applicationConfig` to provide necessary dependencies.
+3.  Usage of `provideStoryCore()` (or other library-specific providers) to set up the environment.
+
+### Example
+
+Here is an example of how to set up a basic story for a component.
+
+```typescript
+import { Meta, StoryObj, moduleMetadata, applicationConfig } from '@storybook/angular';
+import { MyComponent } from './my.component';
+import { provideStoryCore } from '@alfresco/adf-core/testing'; // Adjust import based on your library location
+import { CommonModule } from '@angular/common';
+
+const meta: Meta<MyComponent> = {
+    title: 'Core/My Component',
+    component: MyComponent,
+    decorators: [
+        applicationConfig({
+            providers: [...provideStoryCore()]
+        }),
+        moduleMetadata({
+            imports: [MyComponent]
+        })
+    ],
+    argTypes: {
+        // Define controls for your inputs here
+        label: { control: 'text' },
+        isDisabled: { control: 'boolean' }
+    }
+};
+
+export default meta;
+type Story = StoryObj<MyComponent>;
+
+export const Default: Story = {
+    args: {
+        label: 'Click me',
+        isDisabled: false
+    }
+};
+
+export const Disabled: Story = {
+    args: {
+        label: 'Disabled',
+        isDisabled: true
+    }
+};
+```
+
+### Dependencies
+
+The `provideStoryCore()` function helper is essential for setting up the common providers required by ADF components, such as translation services, authentication mocks, and app configuration.
+
+If your component requires specific services not included in `provideStoryCore()`, you should add them to the `providers` array in the `applicationConfig`.
+
+## Useful Links
+
+- [Writing Stories](https://storybook.js.org/docs/angular/writing-stories/introduction)
+- [Args and Controls](https://storybook.js.org/docs/angular/writing-stories/args)
+- [Decorators](https://storybook.js.org/docs/angular/writing-stories/decorators)
+- [Naming Components and Hierarchy](https://storybook.js.org/docs/angular/writing-stories/naming-components-and-hierarchy)
@@ -0,0 +1,112 @@
+# Configuring Storybook for a New Library
+
+This guide outlines the steps to configure Storybook for a newly created Nx library within the repository.
+
+## Prerequisites
+
+Ensure that the library has been created using the Nx generator.
+
+## Configuration Steps
+
+### 1. Generate Storybook Configuration
+
+Run the Nx generator to add Storybook configuration to your library:
+
+```bash
+nx g @nx/angular:storybook-configuration [project-name]
+```
+
+Replace `[project-name]` with the name of your library (e.g., `my-new-lib`).
+
+### 2. Update `project.json`
+
+Verify that the `project.json` file of your library has the `storybook` and `build-storybook` targets correctly configured.
+
+### 3. Update `.storybook/main.ts`
+
+Update the `.storybook/main.ts` file in your library to extend the root configuration and handle static assets correctly.
+
+```typescript
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import type { StorybookConfig } from '@storybook/angular';
+import rootMain from '../../../.storybook/main'; // Adjust path to root
+
+const config: StorybookConfig = {
+    ...rootMain,
+    stories: ['../**/*.stories.@(js|jsx|ts|tsx)'],
+    staticDirs: [
+        // Add static directories if needed, e.g., for i18n or assets
+        { from: '../src/lib/i18n', to: 'assets/adf-my-lib/i18n' }
+    ],
+    framework: {
+        name: getAbsolutePath('@storybook/angular'),
+        options: {}
+    }
+};
+
+export default config;
+
+function getAbsolutePath(value: string): any {
+    return dirname(fileURLToPath(import.meta.resolve(`${value}/package.json`)));
+}
+```
+
+### 4. Update `.storybook/preview.ts`
+
+Update `.storybook/preview.ts` to import the root preview configuration and add any library-specific tags.
+
+```typescript
+import { type Preview } from '@storybook/angular';
+import rootPreview from '../../../.storybook/preview'; // Adjust path to root
+
+const preview: Preview = {
+    ...rootPreview,
+    tags: ['autodocs']
+};
+
+export default preview;
+```
+
+### 5. Update `.storybook/tsconfig.json`
+
+Ensure the `tsconfig.json` in the `.storybook` directory extends the main `tsconfig.json` and includes/excludes the correct files.
+
+```json
+{
+    "extends": "../../../tsconfig.json",
+    "compilerOptions": {
+        "emitDecoratorMetadata": true
+    },
+    "exclude": ["../**/*.spec.ts", "../**/*.mock.ts", "../**/test.ts", "../**/*.module.ts"],
+    "include": ["../src/**/*", "*.ts"]
+}
+```
+
+### 6. Update Root `lib/stories`
+
+To include the new library's stories in the aggregated Storybook (`nx run stories:storybook`), you need to update the `lib/stories/.storybook/main.ts` file.
+
+1.  **Add Stories Pattern**: Add the path to your new library's stories in the `stories` array.
+2.  **Add Static Assets**: If your library has static assets (like i18n files), add them to the `staticDirs` array.
+
+Example update in `lib/stories/.storybook/main.ts`:
+
+```typescript
+// ...
+stories: [
+    // ... existing entries
+    '../../my-new-lib/**/*.stories.ts'
+],
+staticDirs: [
+    // ... existing entries
+    { from: '../../my-new-lib/src/lib/i18n', to: 'assets/adf-my-lib/i18n' }
+],
+// ...
+```
+
+## Useful Links
+
+- [Configure Storybook](https://storybook.js.org/docs/angular/configure/overview)
+- [Framework Configuration (main.ts)](https://storybook.js.org/docs/angular/configure/framework-config)
+- [Story Rendering (preview.ts)](https://storybook.js.org/docs/angular/configure/story-rendering)
@@ -0,0 +1,33 @@
+# Using Storybook
+
+This guide explains how to run and build Storybook for the entire repository and for individual libraries within the Alfresco Angular Components project.
+
+## Introduction
+
+Storybook is used in this repository to develop and showcase components in isolation. It provides a sandbox environment where you can interact with components and view their different states.
+
+## Running All Stories
+
+To run the aggregated Storybook that includes stories from all libraries (Core, Content Services, Process Services Cloud, etc.), use the following command:
+
+```bash
+npm run storybook
+```
+
+Once started, you can access the Storybook interface at:
+[http://localhost:4400/](http://localhost:4400/)
+
+## Building Storybook
+
+To build the static Storybook application (e.g., for deployment), use the following command:
+
+```bash
+npm run build-storybook
+```
+
+The build artifacts will be output to `dist/storybook/stories`.
+
+## Useful Links
+
+- [Storybook CLI Options](https://storybook.js.org/docs/angular/api/cli-options)
+- [Storybook for Angular Introduction](https://storybook.js.org/docs/angular/get-started/introduction)