jupyterlab-contrib · fcollonval · Jul 4, 2023 · Jun 30, 2023 · Jun 30, 2023 · Jun 30, 2023
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 <!-- <START NEW CHANGELOG ENTRY> -->
 
-## 0.10.1
+## 0.10.0
 
 ([Full Changelog](https://github.com/jupyterlab-contrib/jupyter-ui-toolkit/compare/v0.9.1...d687dc2f1f656ac2e6782cf8ffc6edcbf6bcf6bb))
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -14,7 +14,7 @@ questions about these issues.
 
 ## Development installation
 
-You will need to install `yarn` (for example with `npm install --global yarn`).
+You will need to install `yarn` (for example with `npm install --global yarn && yarn set version berry`).
 
 To build the components packages, execute:
 
@@ -35,7 +35,7 @@ yarn start
 To test locally the JupyterLab demo extension, using `conda` package manager:
 
 ```sh
-conda create -n jupyter-toolkit -c conda-forge -y nodejs yarn jupyterlab=3
+conda create -n jupyter-toolkit -c conda-forge -y nodejs yarn=3 jupyterlab=4
 conda activate jupyter-toolkit
 yarn install
 yarn build
@@ -70,7 +70,7 @@ and the issues it solves before a pull request is opened.
 
 ## Issue Management
 
-Opening an issue lets community members participate in the design
+[Opening an issue](https://github.com/jupyterlab-contrib/jupyter-ui-toolkit/issues/new/choose) lets community members participate in the design
 discussion, makes others aware of work being done, and sets the stage
 for a fruitful community interaction. A pull request should reference
 the issue it is addressing. Once the pull request is merged, the issue

diff --git a/README.md b/README.md
@@ -1,12 +1,12 @@
 # UI Toolkit for Jupyter
 
-**WIP this is early work in progress.** But don't hesitate to open issues and PRs if you want to
-help.
+> Don't hesitate to open issues and PRs if you want to
+> help.
 
 [![Extension status](https://img.shields.io/badge/status-ready-success 'The package is ready to be used')](https://jupyterlab-contrib.github.io/)
 [![NPM Version](https://img.shields.io/npm/v/@jupyter/web-components?color=blue)](https://www.npmjs.com/package/@jupyter/web-components)
-[![Extension status](https://img.shields.io/badge/cdn-jsdelivr-brightgreen)](https://www.jsdelivr.com/package/npm/@jupyter/web-components)
-[![Extension status](https://img.shields.io/badge/cdn-unpkg-brightgreen)](https://unpkg.com/browse/@jupyter/web-components/)
+[![jsdelivr status](https://img.shields.io/badge/cdn-jsdelivr-brightgreen)](https://www.jsdelivr.com/package/npm/@jupyter/web-components)
+[![unpkg status](https://img.shields.io/badge/cdn-unpkg-brightgreen)](https://unpkg.com/browse/@jupyter/web-components/)
 
 [![Toolkit CI Status](https://github.com/jupyterlab-contrib/jupyter-ui-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/jupyterlab-contrib/jupyter-ui-toolkit/actions/workflows/ci.yml)
 [![Deploy Docs Status](https://github.com/jupyterlab-contrib/jupyter-ui-toolkit/actions/workflows/docs-cd.yml/badge.svg)](https://jupyterlab-contrib.github.io/jupyter-ui-toolkit/)
@@ -77,7 +77,7 @@ A pre-bundled script that contains all APIs needed to use Jupyter UI Toolkit is
   <head>
     <script
       type="module"
-      src="https://unpkg.com/@jupyter/web-components"
+      src="https://unpkg.com/@jupyter/web-components/dist/toolkit.min.js"
     ></script>
   </head>
   <!-- ... -->
@@ -90,8 +90,7 @@ The above CDN location points to the latest release of `@jupyter/web-components`
 
 Further documentation can be found in the following places:
 
-- [Component Docs](https://github.com/jupyterlab-contrib/jupyter-ui-toolkit/tree/main/packages/components/docs/components.md)
-- [Storybook (Interactive Component Sandbox)](https://jupyterlab-contrib.github.io/jupyter-ui-toolkit/)
+- [Interactive documentation](https://jupyterlab-contrib.github.io/jupyter-ui-toolkit/)
 - [Toolkit Extension Samples](https://github.com/jupyterlab-contrib/jupyter-ui-toolkit/tree/main/packages/lab-example):
   [Try online](https://mybinder.org/v2/gh/jupyterlab-contrib/jupyter-ui-toolkit/main)
 

diff --git a/examples/cdn/README.md b/examples/cdn/README.md
@@ -0,0 +1,4 @@
+# Using the toolkit from CDN
+
+This example demonstrates how to use the Jupyter UI toolkit from CDN with
+JupyterLab theming on.
diff --git a/examples/cdn/index.html b/examples/cdn/index.html
@@ -0,0 +1,40 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8">
+    <title>Jupyter UI toolkit using CDN</title>
+    <script type="module" src="https://unpkg.com/@jupyter/web-components/dist/toolkit.min.js"></script>
+    <style>
+        /*
+            Minimal set of CSS properties from a JupyterLab theme
+            used to theme the toolkit.
+        */
+        :root {
+            --jp-brand-color1: #f2c812;
+            --jp-layout-color1: #808080;
+            --jp-border-width: 1px;
+            --jp-ui-font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+            --jp-ui-font-size1: 13px;
+        }
+    </style>
+</head>
+<!-- 
+    The toolkit supports theming from JupyterLab theme
+    For that you need to set `data-jp-theme-name` with a theme _name_
+    and `data-jp-theme-light` with `true` (ligth theme) or `false` (dark theme)
+-->
+
+<body data-jp-theme-name="default" data-jp-theme-light="true">
+
+    <jp-button appearance="accent" onclick="alert('Accent button pressed')">Click me!</jp-button>
+    <jp-button onclick="alert('Neutral button pressed')">Click me!</jp-button>
+
+    <script type="module">
+        // Inject JupyterLab theme listener
+        import { addJupyterLabThemeChangeListener } from 'https://unpkg.com/@jupyter/web-components/dist/toolkit.min.js';
+        addJupyterLabThemeChangeListener();
+    </script>
+</body>
+
+</html>
diff --git a/packages/components/.storybook/main.js b/packages/components/.storybook/main.js
@@ -1,30 +1,53 @@
+import remarkGfm from 'remark-gfm';
+
 module.exports = {
-  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.ts'],
+  stories: [
+    '../docs/**/*.mdx',
+    '../src/**/*.stories.mdx',
+    '../src/**/*.stories.ts'
+  ],
   addons: [
+    {
+      name: '@storybook/addon-docs',
+      options: {
+        mdxPluginOptions: {
+          mdxCompileOptions: {
+            remarkPlugins: [remarkGfm]
+          }
+        }
+      }
+    },
     '@storybook/addon-links',
     '@storybook/addon-essentials',
     '@storybook/addon-a11y'
   ],
-  features: {
-    postcss: false
-  },
   webpackFinal: async config => {
-    config.module.rules.push({
-      test: /\.ts$/,
-      sideEffects: true,
-      use: [
-        {
-          loader: 'ts-loader',
-          options: {
-            configFile: 'tsconfig.storybook.json'
+    config.module.rules.push(
+      {
+        test: /\.ts$/,
+        sideEffects: true,
+        use: [
+          {
+            loader: 'ts-loader',
+            options: {
+              configFile: 'tsconfig.storybook.json'
+            }
           }
-        }
-      ]
-    });
+        ]
+      },
+      {
+        test: /\.md$/,
+        type: 'asset/source'
+      }
+    );
     return config;
   },
   framework: {
     name: '@storybook/html-webpack5',
     options: {}
+  },
+  docs: {
+    autodocs: true,
+    defaultName: 'Documentation'
   }
 };
diff --git a/packages/components/.storybook/preview.js b/packages/components/.storybook/preview.js
@@ -41,10 +41,9 @@ const globalTypes = {
       // Array of plain string values or MenuItem shape (see below)
       items: [
         { value: '#006CBE', right: '🔵', title: 'blue' },
-        { value: '#DA1A5F', title: 'pink' }
-      ],
-      // Property that specifies if the name of the item will be displayed
-      showName: false
+        { value: '#DA1A5F', title: 'pink' },
+        { value: '#f2c812', title: 'yellow' }
+      ]
     }
   }
 };

diff --git a/packages/components/docs/Introduction.mdx b/packages/components/docs/Introduction.mdx
@@ -0,0 +1,40 @@
+# Jupyter UI toolkit
+
+## Components
+
+The component tags are prefixed by `jp-` (`anchored-region` ➙ `jp-anchored-region`)
+when using `@jupyter/web-components` and are capitalized (`anchored-region` ➙ `AnchoredRegion`) when using `@jupyter/react-components`.
+
+Here is the list of components part of the Jupyter UI toolkit:
+
+| Name              | Reference                                                                                      | Documentation                                                     |
+| ----------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `accordion`       | [Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)                       | [Stories](?path=/story/components-accordion--documentation)       |
+| `anchor`          | [Anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)                  | [Stories](?path=/story/components-anchor--documentation)          |
+| `anchored-region` | Position content relative to another "anchor" element                                          | [Stories](?path=/story/components-anchored-region--documentation) |
+| `avatar`          | Visual represent an user or an object                                                          | [Stories](?path=/story/components-avatar--documentation)          |
+| `badge`           | Highlight an item and attract attention or flag status                                         | [Stories](?path=/story/components-badge--documentation)           |
+| `breadcrumb`      | [Breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/)                     | [Stories](?path=/story/components-breadcrumb--documentation)      |
+| `button`          | [Button element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button)             | [Stories](?path=/story/components-button--documentation)          |
+| `card`            | Visual container                                                                               | [Stories](?path=/story/components-card--documentation)            |
+| `checkbox`        | [Checkbox element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input/checkbox)   | [Stories](?path=/story/components-checkbox--documentation)        |
+| `combobox`        | [Combobox element](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)                         | [Stories](?path=/story/components-combobox--documentation)        |
+| `data-grid`       | [Grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/)                                 | [Stories](?path=/story/components-data-grid--documentation)       |
+| `date-field`      | [Date input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date)     | [Stories](?path=/story/components-date-field--documentation)      |
+| `divider`         | [Horizontal or vertical rule](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr)    | [Stories](?path=/story/components-divider--documentation)         |
+| `menu`            | [Menu](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/)                                      | [Stories](?path=/story/components-menu--documentation)            |
+| `number-field`    | [Number input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number) | [Stories](?path=/story/components-number-field--documentation)    |
+| `progress`        | [Meter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/) as line                       | [Stories](?path=/story/components-progress--documentation)        |
+| `progress-ring`   | [Meter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/) as ring                       | [Stories](?path=/story/components-progress-ring--documentation)   |
+| `radio-group`     | [Radio pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)                               | [Stories](?path=/story/components-radio-group--documentation)     |
+| `search`          | [Search input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/search) | [Stories](?path=/story/components-search--documentation)          |
+| `select`          | [Select element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)             | [Stories](?path=/story/components-select--documentation)          |
+| `skeleton`        | [Skeleton element](https://open-ui.org/components/skeleton.research/)                          | [Stories](?path=/story/components-skeleton--documentation)        |
+| `slider`          | [Range input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/range)   | [Stories](?path=/story/components-slider--documentation)          |
+| `switch`          | [Switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)                             | [Stories](?path=/story/components-switch--documentation)          |
+| `tabs`            | [Tab panel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/)                            | [Stories](?path=/story/components-tabs--documentation)            |
+| `text-area`       | [Text area element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)        | [Stories](?path=/story/components-text-area--documentation)       |
+| `text-field`      | [Text input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/text)     | [Stories](?path=/story/components-text-field--documentation)      |
+| `toolbar`         | [Toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/)                           | [Stories](?path=/story/components-toolbar--documentation)         |
+| `tooltip`         | [Tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)                           | [Stories](?path=/story/components-tooltip--documentation)         |
+| `tree-view`       | [Tree view pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)                        | [Stories](?path=/story/components-tree-view--documentation)       |
diff --git a/packages/components/docs/api-report.mdx b/packages/components/docs/api-report.mdx
@@ -0,0 +1,7 @@
+import { Meta } from '@storybook/addon-docs';
+import { Markdown } from '@storybook/blocks';
+import APIReport from './api-report.md';
+
+<Meta title="API Report" />
+
+<Markdown>{APIReport}</Markdown>
diff --git a/packages/components/docs/assets/toolkit-artwork.png b/packages/components/docs/assets/toolkit-artwork.png
diff --git a/packages/components/docs/changelog.mdx b/packages/components/docs/changelog.mdx
@@ -0,0 +1,7 @@
+import { Meta } from '@storybook/addon-docs';
+import { Markdown } from '@storybook/blocks';
+import Changelog from '../../../CHANGELOG.md';
+
+<Meta title="Changelog" />
+
+<Markdown>{Changelog}</Markdown>
diff --git a/packages/components/docs/components.md b/packages/components/docs/components.md
diff --git a/packages/components/docs/contributing.mdx b/packages/components/docs/contributing.mdx
@@ -0,0 +1,7 @@
+import { Meta } from '@storybook/addon-docs';
+import { Markdown } from '@storybook/blocks';
+import Contributing from '../../../CONTRIBUTING.md';
+
+<Meta title="Contributing" />
+
+<Markdown>{Contributing}</Markdown>
diff --git a/packages/components/docs/getting-started.mdx b/packages/components/docs/getting-started.mdx
@@ -0,0 +1,49 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Getting started" />
+
+# Getting started
+
+This toolkit provides [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) styled for Jupyter frontends. But you can use
+them independently of Jupyter frontends.
+
+> As web components are a web standard, you can use them in any popular framework such as Vue, Svelte,... .
+> The only one not fully supported them yet is React. Therefore the toolkit provides a React flavored of
+> the component through the package `@jupyter/react-components`.
+
+The toolkit can be consumed directly by importing it in your HTML webpage or by adding as a NPM dependency to your project.
+
+## HTML integration (through CDN)
+
+A pre-bundled script that contains all APIs needed to use Jupyter UI Toolkit is available on CDN. You can use this script by adding [`type="module"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) to the script element and then importing from the CDN.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <script
+      type="module"
+      src="https://unpkg.com/@jupyter/web-components/dist/toolkit.min.js"
+    ></script>
+  </head>
+  <!-- ... -->
+</html>
+```
+
+The above CDN location points to the latest release of `@jupyter/web-components`. It is advised that when you deploy your site or app, you import the specific version you have developed and tested with.
+
+> A [example](https://raw.githubusercontent.com/jupyterlab-contrib/jupyter-ui-toolkit/main/examples/cdn) is available in the project repository.
+
+## NPM package
+
+To install the `web-components` library, use either `npm` or `yarn` as follows:
+
+```shell
+npm install --save @jupyter/web-components
+```
+
+```shell
+yarn add @jupyter/web-components
+```
+
+> If you need the React components of the toolkit, you need to install `@jupyter/react-components`.
diff --git a/packages/components/package.json b/packages/components/package.json
@@ -58,9 +58,11 @@
     "@rollup/plugin-typescript": "^8.2.0",
     "@storybook/addon-a11y": "^7.0.23",
     "@storybook/addon-actions": "^7.0.23",
+    "@storybook/addon-docs": "^7.0.24",
     "@storybook/addon-essentials": "^7.0.23",
     "@storybook/addon-links": "^7.0.23",
     "@storybook/addons": "^7.0.23",
+    "@storybook/blocks": "^7.0.24",
     "@storybook/html": "^7.0.23",
     "@storybook/html-webpack5": "^7.0.23",
     "@storybook/theming": "^7.0.23",
@@ -75,6 +77,7 @@
     "prettier": "^2.8.8",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
+    "remark-gfm": "^3.0.1",
     "rimraf": "^5.0.1",
     "rollup": "^2.40.0",
     "rollup-plugin-delete": "^2.0.0",

diff --git a/packages/components/src/accordion-item/accordion-item.stories.ts b/packages/components/src/accordion-item/accordion-item.stories.ts
@@ -4,7 +4,7 @@ import type { StoryFn, Meta, StoryObj } from '@storybook/html';
 import { setTheme } from '../utilities/storybook';
 
 export default {
-  title: 'Accordion Item',
+  title: 'Components/Accordion Item',
 
   parameters: {
     controls: {

diff --git a/packages/components/src/accordion-item/accordion-item.test.ts b/packages/components/src/accordion-item/accordion-item.test.ts
@@ -4,7 +4,7 @@
 import { test, expect } from '@playwright/test';
 
 test('Default', async ({ page }) => {
-  await page.goto('/iframe.html?id=accordion-item--default');
+  await page.goto('/iframe.html?id=components-accordion-item--default');
 
   expect(await page.locator('jp-accordion-item').screenshot()).toMatchSnapshot(
     'accordion-item-default.png'

diff --git a/packages/components/src/accordion/accordion.stories.ts b/packages/components/src/accordion/accordion.stories.ts
@@ -4,7 +4,7 @@ import type { HtmlRenderer, Meta, StoryObj, StoryFn } from '@storybook/html';
 import { setTheme } from '../utilities/storybook';
 
 export default {
-  title: 'Accordion',
+  title: 'Components/Accordion',
 
   parameters: {
     controls: {

diff --git a/packages/components/src/accordion/accordion.test.ts b/packages/components/src/accordion/accordion.test.ts
@@ -4,7 +4,7 @@
 import { test, expect } from '@playwright/test';
 
 test('Default', async ({ page }) => {
-  await page.goto('/iframe.html?id=accordion--default');
+  await page.goto('/iframe.html?id=components-accordion--default');
 
   expect(await page.locator('jp-accordion').screenshot()).toMatchSnapshot(
     'accordion-default.png'

diff --git a/packages/components/src/anchored-region/anchored-region.stories.mdx b/packages/components/src/anchored-region/anchored-region.stories.mdx
@@ -1,6 +1,6 @@
 import { Meta } from '@storybook/addon-docs';
 
-<Meta title="Anchored Region" />
+<Meta title="Components/Anchored Region" />
 
 # Anchored Region
 

diff --git a/packages/components/src/avatar/avatar.stories.ts b/packages/components/src/avatar/avatar.stories.ts
@@ -4,7 +4,7 @@ import type { StoryFn, Meta, StoryObj } from '@storybook/html';
 import { setTheme } from '../utilities/storybook';
 
 export default {
-  title: 'Avatar',
+  title: 'Components/Avatar',
   argTypes: {
     shape: { control: 'select', options: ['circle', 'square', 'default'] },
     fill: {