Update Storybook and document the @tektoncd/dashboard-* packages

Add a welcome page to the Storybook providing a brief overview and
describing the purpose of each section in the Storybook.

When running in dev mode, include the Carbon storybooks for easier
reference. Also include links to commonly used pages in the Carbon
documentation.

Add documentation to each of the package folders describing their
purpose, any additional required setup, and providing examples of
their use.

.storybook/Container.scss

@@ -12,6 +12,7 @@ limitations under the License.
 */
 
 @import '../src/scss/App';
+@import './welcome';
 
 @import '@tektoncd/dashboard-graph/src/components/Graph.scss';
 @import '@tektoncd/dashboard-graph/src/components/ZoomablePipelineGraph.scss';

.storybook/Welcome.mdx

@@ -0,0 +1,99 @@
+{/*
+Copyright 2023 The Tekton Authors
+Licensed 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.
+*/}
+
+import { Canvas, Meta, Unstyled } from '@storybook/blocks';
+import LinkTo from '@storybook/addon-links/react';
+
+import PackageInfo from '../packages/components/package.json';
+import * as DetailsHeaderStories from '../packages/components/src/components/DetailsHeader/DetailsHeader.stories';
+import * as GraphStories from '../packages/graph/src/components/Graph/Graph.stories';
+import * as NodeStories from '../packages/graph/src/components/Node/Node.stories';
+import * as RunHeaderStories from '../packages/components/src/components/RunHeader/RunHeader.stories';
+
+import tektonDashboardLogo from '../src/images/tekton-dashboard-color.svg';
+
+<Meta
+ name="Welcome"
+ parameters={{
+ backgrounds: {
+ default: 'gray10'
+ }
+ }}
+ title="Getting started/Welcome"
+/>
+
+<Unstyled>
+ <div className="welcome__container">
+ <div className="welcome__heading">
+ <div>
+ ## Tekton Dashboard
+ ### {`v${PackageInfo.version}`}
+
+ [Tekton Dashboard documentation](https://tekton.dev/docs/dashboard/)
+
+ GitHub repository links:
+ - [@tektoncd/dashboard-components](https://github.com/tektoncd/dashboard/tree/main/packages/components/)
+ - [@tektoncd/dashboard-utils](https://github.com/tektoncd/dashboard/tree/main/packages/utils/)
+ - [@tektoncd/dashboard-graph (experimental)](https://github.com/tektoncd/dashboard/tree/main/packages/graph/)
+ </div>
+ <img src={tektonDashboardLogo} alt="Tekton Dashboard logo" />
+ </div>
+
+ ### Overview
+
+ Tekton Dashboard uses the [Carbon Design System](https://v10.carbondesignsystem.com/) to guide its design, leveraging many of the base components it provides. Tekton Dashboard also publishes a number of its own npm packages containing additional components and utilities used to build on top of these.
+
+ This Storybook showcases each of the published UI components, including examples of variants or customisation where applicable. It also contains some content not included in the published packages. You can find more details in the following sections.
+
+ ### Carbon
+
+ {
+ process.env.NODE_ENV === 'development' && (
+ <p>
+ The Carbon storybook can be found at the bottom of the side nav when running in development mode. There are 2 versions included, Carbon v10 is the version currently used by the Dashboard. The Carbon v11 storybook is provided for reference purposes only, to help with decisions to consume new components. We will be adopting v11 in the future, but it should not be used in the Dashboard yet.
+ </p>
+ )
+ }
+
+ Useful links:
+ - [Carbon v10 documentation](https://v10.carbondesignsystem.com/)
+ - [Carbon v10 storybook](https://v7-react.carbondesignsystem.com/)
+ - [Colour usage](https://v10.carbondesignsystem.com/guidelines/color/usage/)
+ - [Icon library](https://v10.carbondesignsystem.com/guidelines/icons/library/)
+
+
+ ### Components
+
+ This section contains stories for the UI components published in the `@tektoncd/dashboard-components` package.
+
+ These are pure UI / presentational components, completely agnostic of any API layer or URL structure, and can be consumed by other applications.
+
+ For example, one variation each of the <LinkTo className="storylink" kind="Components/DetailsHeader" story="Completed">`DetailsHeader`</LinkTo> and <LinkTo className="storylink" kind="Components/RunHeader" story="Failed">`RunHeader`</LinkTo> components are shown below, along with the code used to create these examples.
+
+ <Canvas of={DetailsHeaderStories.Completed} />
+ <Canvas of={RunHeaderStories.Failed} />
+
+ ### Containers
+
+ These are containers which are specific to the Tekton Dashboard application and are not included in the published packages. These generally use the UI components above, so can be used as examples of consuming them in a larger component / application, but rely on API providers or URL structures specific to the Dashboard.
+
+ ### Experimental
+
+ This section contains components that are not currently stable. They may be incomplete or change significantly without notice, therefore are not recommended for consumption by others at this time. They may be explorations for future functionality, or experiments with new designs / behaviours.
+
+ An example of these are the <LinkTo className="storylink" kind="Experimental/Graph/Graph" story="Detailed-1">`Graph`</LinkTo> components published in `@tektoncd/dashboard-graph` which provide a visualisation of a pipeline's structure.
+
+ <Canvas className="tkn-graph-story" of={GraphStories.Condensed1} withToolbar />
+ <Canvas className="tkn-graph-story" of={GraphStories.Detailed1} showToolbar />
+ </div>
+</Unstyled>

.storybook/main.js

@@ -16,6 +16,7 @@ const path = require('path');
 const config = {
  addons: [
  '@storybook/addon-essentials',
+ '@storybook/addon-links',
  '@storybook/addon-storysource',
  {
  name: '@storybook/addon-styling',
@@ -46,7 +47,25 @@ const config = {
  }
  }
  },
+ refs: (_config, { configType }) => {
+ if (configType === 'DEVELOPMENT') {
+ return {
+ carbon10: {
+ title: 'Carbon v10',
+ url: 'https://v7-react.carbondesignsystem.com/',
+ expanded: false
+ },
+ carbon11: {
+ title: 'Carbon v11 (do not use yet, for reference only)',
+ url: 'https://react.carbondesignsystem.com/',
+ expanded: false
+ }
+ };
+ }
+ return {};
+ },
  stories: [
+ { directory: '.', files: 'Welcome.mdx' },
  { directory: '../src', files: '**/*.stories.js', titlePrefix: 'Containers' },
  { directory: '../packages/components', files: '**/*.stories.js', titlePrefix: 'Components' },
  { directory: '../packages/graph', files: '**/*.stories.js', titlePrefix: 'Experimental/Graph' }

.storybook/preview.js

@@ -18,7 +18,7 @@ import Container from './Container';
 const parameters = {
  options: {
  storySort: {
- order: ['Components', 'Containers', '*', 'Experimental']
+ order: ['Getting started', 'Components', 'Containers', '*', 'Experimental']
  }
  },
  backgrounds: {

.storybook/theme.js

@@ -1,5 +1,5 @@
 /*
-Copyright 2020 The Tekton Authors
+Copyright 2020-2023 The Tekton Authors
 Licensed 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
@@ -12,12 +12,12 @@ limitations under the License.
 */
 
 import { create } from '@storybook/theming/create';
-import brandImage from './tekton-horizontal-color.png';
+
+import PackageInfo from '../packages/components/package.json';
 
 export default create({
  base: 'light',
 
- brandTitle: 'Tekton Components',
- brandUrl: 'https://github.com/tektoncd/dashboard',
- brandImage
+ brandTitle: `Tekton Dashboard packages @${PackageInfo.version}`,
+ brandUrl: 'https://github.com/tektoncd/dashboard/tree/main/packages'
 });

.storybook/welcome.scss

@@ -0,0 +1,78 @@
+/*
+Copyright 2023 The Tekton Authors
+Licensed 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.
+*/
+
+.welcome__container {
+ position: absolute;
+ top: 0;
+ left: 0;
+ width: 100vw;
+ max-width: 120ch;
+ padding: 3rem;
+ background-color: $ui-background;
+
+ .welcome__heading {
+ display: flex;
+ margin-bottom: 2rem;
+ }
+
+ h2 {
+ @include type-style('productive-heading-07');
+ color: $text-01;
+ }
+
+ h2 + p {
+ @include type-style('productive-heading-03');
+ font-weight: 600;
+ }
+
+ h3 {
+ margin-top: 2rem;
+ }
+
+ img {
+ height: 250px;
+ margin-left: auto;
+ }
+
+ a {
+ @include type-style('body-short-01');
+ outline: none;
+ text-decoration: none;
+ transition: color 70ms cubic-bezier(0.2, 0, 0.38, 0.9);
+ }
+
+ a, a:hover, a:visited, a.storylink code {
+ color: $link-01;
+ }
+
+ a:hover {
+ color: $hover-primary-text;
+ text-decoration: underline;
+ }
+
+ a:focus {
+ outline: 1px solid $focus;
+ }
+
+ p {
+ margin-top: 1rem;
+ }
+
+ ul li {
+ margin-top: 0.5rem;
+ }
+
+ .tkn-graph-story .sb-story {
+ background-color: $ui-background;
+ }
+}