This is an automated email from the ASF dual-hosted git repository. rusackas pushed a commit to branch docs/federate-storybook in repository https://gitbox.apache.org/repos/asf/superset.git
commit acac08a43bcfb03eea15c69900e3336055106bf2 Author: Evan Rusackas <[email protected]> AuthorDate: Thu Dec 18 23:16:21 2025 -0800 docs: consolidate Storybook documentation into Developer Portal - Create dedicated docs/developer_portal/testing/storybook.md - Update howtos.md to reference the new Storybook page - Convert superset-ui-demo README to redirect stub 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]> --- docs/developer_portal/contributing/howtos.md | 14 +-- docs/developer_portal/testing/storybook.md | 114 +++++++++++++++++++++ .../packages/superset-ui-demo/README.md | 55 ++-------- 3 files changed, 121 insertions(+), 62 deletions(-) diff --git a/docs/developer_portal/contributing/howtos.md b/docs/developer_portal/contributing/howtos.md index c353944d7e..61c654bb70 100644 --- a/docs/developer_portal/contributing/howtos.md +++ b/docs/developer_portal/contributing/howtos.md @@ -258,19 +258,7 @@ For debugging the Flask backend: ### Storybook -Storybook is used for developing and testing UI components in isolation: - -```bash -cd superset-frontend - -# Start Storybook -npm run storybook - -# Build static Storybook -npm run build-storybook -``` - -Access Storybook at http://localhost:6006 +See the dedicated [Storybook documentation](../testing/storybook) for information on running Storybook locally and adding new stories. ## Contributing Translations diff --git a/docs/developer_portal/testing/storybook.md b/docs/developer_portal/testing/storybook.md new file mode 100644 index 0000000000..0e190220f1 --- /dev/null +++ b/docs/developer_portal/testing/storybook.md @@ -0,0 +1,114 @@ +--- +title: Storybook +sidebar_position: 5 +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Storybook + +Superset uses [Storybook](https://storybook.js.org/) for developing and testing UI components in isolation. Storybook provides a sandbox to build components independently, outside of the main application. + +## Public Storybook + +A public Storybook with components from the `master` branch is available at: + +**[apache-superset.github.io/superset-ui](https://apache-superset.github.io/superset-ui/?path=/story/*)** + +## Running Locally + +### Main Superset Storybook + +To run the main Superset Storybook locally: + +```bash +cd superset-frontend + +# Start Storybook (opens at http://localhost:6006) +npm run storybook + +# Build static Storybook +npm run build-storybook +``` + +### @superset-ui Package Storybook + +The `@superset-ui` packages have a separate Storybook for component library development: + +```bash +cd superset-frontend + +# Install dependencies and bootstrap packages +npm ci && npm run bootstrap + +# Start the @superset-ui Storybook (opens at http://localhost:9001) +cd packages/superset-ui-demo +npm run storybook +``` + +## Adding Stories + +### To an Existing Package + +If stories already exist for the package, extend the `examples` array in the package's story file: + +``` +storybook/stories/<package>/index.js +``` + +### To a New Package + +1. Add package dependencies: + + ```bash + npm install <package> + ``` + +2. Create a story folder matching the package name: + + ```bash + mkdir storybook/stories/superset-ui-<package>/ + ``` + +3. Create an `index.js` file with the story configuration: + + ```javascript + export default { + examples: [ + { + storyPath: '@superset-ui/package', + storyName: 'My Story', + renderStory: () => <MyComponent />, + }, + ], + }; + ``` + + Use the `|` separator for nested stories: + ```javascript + storyPath: '@superset-ui/package|Category|Subcategory' + ``` + +## Best Practices + +- **Isolate components**: Stories should render components in isolation, without application context +- **Show variations**: Create stories for different states, sizes, and configurations +- **Document props**: Use Storybook's controls to expose configurable props +- **Test edge cases**: Include stories for loading states, error states, and empty states diff --git a/superset-frontend/packages/superset-ui-demo/README.md b/superset-frontend/packages/superset-ui-demo/README.md index b1a9be3a1f..c25c470628 100644 --- a/superset-frontend/packages/superset-ui-demo/README.md +++ b/superset-frontend/packages/superset-ui-demo/README.md @@ -17,55 +17,12 @@ specific language governing permissions and limitations under the License. --> -## @superset-ui/demo +# @superset-ui/demo -[](https://github.com/apache/superset/blob/master/superset-frontend/packages/superset-ui-demo/package.json) +Storybook for `@superset-ui` packages. -Storybook of `@superset-ui` packages. See it live at -[apache-superset.github.io/superset-ui](https://apache-superset.github.io/superset-ui) +**See it live:** [apache-superset.github.io/superset-ui](https://apache-superset.github.io/superset-ui) -### Development - -#### Run storybook - -To view the storybook locally, you should first run `npm ci && npm run bootstrap` in the -`@superset-ui` monorepo root directory, which will install all dependencies for this package and -sym-link any `@superset-ui` packages to your local system. - -After that run `npm run storybook` which will open up a dev server at http://localhost:9001. - -#### Adding new stories - -###### Existing package - -If stories already exist for the package you are adding, simply extend the `examples` already -exported for that package in the `storybook/stories/<package>/index.js` file. - -###### New package - -If you are creating stories for a package that doesn't yet have any stories, follow these steps: - -1. Add any new package dependencies (including any `@superset-ui/*` packages) via - `npm install <package>`. - -2. Create a new folder that mirrors the package name - - > e.g., `mkdir storybook/stories/superset-ui-color/` - -3. Add an `index.js` file to that folder with a default export with the following shape: - -> you can use the `|` separator within the `storyPath` string to denote _nested_ stories e.g., -> `storyPath: '@superset-ui/package|Nested i|Nested ii'` - -```javascript - default export { - examples: [ - { - storyPath: <string>, - storyName: <string>, - renderStory: <func> () => node, - }, - ... - ] - }; -``` +For documentation on running Storybook locally and adding stories, see the +[Storybook documentation](https://superset.apache.org/docs/developer_portal/testing/storybook) +in the Developer Portal.
