Skip to content

Commit f8aa421

Browse files
fcollonvalfcollonval
authored
Improve the documentation (#57)
* Add CDN example * Update toolkit artwork * Storybook as only documentation website * Improve documentation structure * Fulfill the components list
1 parent 001a17a commit f8aa421

File tree

84 files changed

+1369
-187
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

84 files changed

+1369
-187
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
<!-- <START NEW CHANGELOG ENTRY> -->
44

5-
## 0.10.1
5+
## 0.10.0
66

77
([Full Changelog](https://github.com/jupyterlab-contrib/jupyter-ui-toolkit/compare/v0.9.1...d687dc2f1f656ac2e6782cf8ffc6edcbf6bcf6bb))
88

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ questions about these issues.
1414

1515
## Development installation
1616

17-
You will need to install `yarn` (for example with `npm install --global yarn`).
17+
You will need to install `yarn` (for example with `npm install --global yarn && yarn set version berry`).
1818

1919
To build the components packages, execute:
2020

@@ -35,7 +35,7 @@ yarn start
3535
To test locally the JupyterLab demo extension, using `conda` package manager:
3636

3737
```sh
38-
conda create -n jupyter-toolkit -c conda-forge -y nodejs yarn jupyterlab=3
38+
conda create -n jupyter-toolkit -c conda-forge -y nodejs yarn=3 jupyterlab=4
3939
conda activate jupyter-toolkit
4040
yarn install
4141
yarn build
@@ -70,7 +70,7 @@ and the issues it solves before a pull request is opened.
7070

7171
## Issue Management
7272

73-
Opening an issue lets community members participate in the design
73+
[Opening an issue](https://github.com/jupyterlab-contrib/jupyter-ui-toolkit/issues/new/choose) lets community members participate in the design
7474
discussion, makes others aware of work being done, and sets the stage
7575
for a fruitful community interaction. A pull request should reference
7676
the issue it is addressing. Once the pull request is merged, the issue

‎README.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
# UI Toolkit for Jupyter
22

3-
**WIP this is early work in progress.** But don't hesitate to open issues and PRs if you want to
4-
help.
3+
> Don't hesitate to open issues and PRs if you want to
4+
> help.
55
66
[![Extension status](https://img.shields.io/badge/status-ready-success 'The package is ready to be used')](https://jupyterlab-contrib.github.io/)
77
[![NPM Version](https://img.shields.io/npm/v/@jupyter/web-components?color=blue)](https://www.npmjs.com/package/@jupyter/web-components)
8-
[![Extension status](https://img.shields.io/badge/cdn-jsdelivr-brightgreen)](https://www.jsdelivr.com/package/npm/@jupyter/web-components)
9-
[![Extension status](https://img.shields.io/badge/cdn-unpkg-brightgreen)](https://unpkg.com/browse/@jupyter/web-components/)
8+
[![jsdelivr status](https://img.shields.io/badge/cdn-jsdelivr-brightgreen)](https://www.jsdelivr.com/package/npm/@jupyter/web-components)
9+
[![unpkg status](https://img.shields.io/badge/cdn-unpkg-brightgreen)](https://unpkg.com/browse/@jupyter/web-components/)
1010

1111
[![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)
1212
[![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
7777
<head>
7878
<script
7979
type="module"
80-
src="https://unpkg.com/@jupyter/web-components"
80+
src="https://unpkg.com/@jupyter/web-components/dist/toolkit.min.js"
8181
></script>
8282
</head>
8383
<!-- ... -->
@@ -90,8 +90,7 @@ The above CDN location points to the latest release of `@jupyter/web-components`
9090

9191
Further documentation can be found in the following places:
9292

93-
- [Component Docs](https://github.com/jupyterlab-contrib/jupyter-ui-toolkit/tree/main/packages/components/docs/components.md)
94-
- [Storybook (Interactive Component Sandbox)](https://jupyterlab-contrib.github.io/jupyter-ui-toolkit/)
93+
- [Interactive documentation](https://jupyterlab-contrib.github.io/jupyter-ui-toolkit/)
9594
- [Toolkit Extension Samples](https://github.com/jupyterlab-contrib/jupyter-ui-toolkit/tree/main/packages/lab-example):
9695
[Try online](https://mybinder.org/v2/gh/jupyterlab-contrib/jupyter-ui-toolkit/main)
9796

‎examples/cdn/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Using the toolkit from CDN
2+
3+
This example demonstrates how to use the Jupyter UI toolkit from CDN with
4+
JupyterLab theming on.

‎examples/cdn/index.html‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
4+
<head>
5+
<meta charset="utf-8">
6+
<title>Jupyter UI toolkit using CDN</title>
7+
<script type="module" src="https://unpkg.com/@jupyter/web-components/dist/toolkit.min.js"></script>
8+
<style>
9+
/*
10+
Minimal set of CSS properties from a JupyterLab theme
11+
used to theme the toolkit.
12+
*/
13+
:root {
14+
--jp-brand-color1: #f2c812;
15+
--jp-layout-color1: #808080;
16+
--jp-border-width: 1px;
17+
--jp-ui-font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
18+
--jp-ui-font-size1: 13px;
19+
}
20+
</style>
21+
</head>
22+
<!--
23+
The toolkit supports theming from JupyterLab theme
24+
For that you need to set `data-jp-theme-name` with a theme _name_
25+
and `data-jp-theme-light` with `true` (ligth theme) or `false` (dark theme)
26+
-->
27+
28+
<body data-jp-theme-name="default" data-jp-theme-light="true">
29+
30+
<jp-button appearance="accent" onclick="alert('Accent button pressed')">Click me!</jp-button>
31+
<jp-button onclick="alert('Neutral button pressed')">Click me!</jp-button>
32+
33+
<script type="module">
34+
// Inject JupyterLab theme listener
35+
import { addJupyterLabThemeChangeListener } from 'https://unpkg.com/@jupyter/web-components/dist/toolkit.min.js';
36+
addJupyterLabThemeChangeListener();
37+
</script>
38+
</body>
39+
40+
</html>

‎packages/components/.storybook/main.js‎

Lines changed: 38 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,53 @@
1+
import remarkGfm from 'remark-gfm';
2+
13
module.exports = {
2-
stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.ts'],
4+
stories: [
5+
'../docs/**/*.mdx',
6+
'../src/**/*.stories.mdx',
7+
'../src/**/*.stories.ts'
8+
],
39
addons: [
10+
{
11+
name: '@storybook/addon-docs',
12+
options: {
13+
mdxPluginOptions: {
14+
mdxCompileOptions: {
15+
remarkPlugins: [remarkGfm]
16+
}
17+
}
18+
}
19+
},
420
'@storybook/addon-links',
521
'@storybook/addon-essentials',
622
'@storybook/addon-a11y'
723
],
8-
features: {
9-
postcss: false
10-
},
1124
webpackFinal: async config => {
12-
config.module.rules.push({
13-
test: /\.ts$/,
14-
sideEffects: true,
15-
use: [
16-
{
17-
loader: 'ts-loader',
18-
options: {
19-
configFile: 'tsconfig.storybook.json'
25+
config.module.rules.push(
26+
{
27+
test: /\.ts$/,
28+
sideEffects: true,
29+
use: [
30+
{
31+
loader: 'ts-loader',
32+
options: {
33+
configFile: 'tsconfig.storybook.json'
34+
}
2035
}
21-
}
22-
]
23-
});
36+
]
37+
},
38+
{
39+
test: /\.md$/,
40+
type: 'asset/source'
41+
}
42+
);
2443
return config;
2544
},
2645
framework: {
2746
name: '@storybook/html-webpack5',
2847
options: {}
48+
},
49+
docs: {
50+
autodocs: true,
51+
defaultName: 'Documentation'
2952
}
3053
};

‎packages/components/.storybook/preview.js‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,9 @@ const globalTypes = {
4141
// Array of plain string values or MenuItem shape (see below)
4242
items: [
4343
{ value: '#006CBE', right: '🔵', title: 'blue' },
44-
{ value: '#DA1A5F', title: 'pink' }
45-
],
46-
// Property that specifies if the name of the item will be displayed
47-
showName: false
44+
{ value: '#DA1A5F', title: 'pink' },
45+
{ value: '#f2c812', title: 'yellow' }
46+
]
4847
}
4948
}
5049
};

‎packages/components/docs/Introduction.mdx‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Jupyter UI toolkit
2+
3+
## Components
4+
5+
The component tags are prefixed by `jp-` (`anchored-region` ➙ `jp-anchored-region`)
6+
when using `@jupyter/web-components` and are capitalized (`anchored-region` ➙ `AnchoredRegion`) when using `@jupyter/react-components`.
7+
8+
Here is the list of components part of the Jupyter UI toolkit:
9+
10+
| Name | Reference | Documentation |
11+
| ----------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
12+
| `accordion` | [Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) | [Stories](?path=/story/components-accordion--documentation) |
13+
| `anchor` | [Anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) | [Stories](?path=/story/components-anchor--documentation) |
14+
| `anchored-region` | Position content relative to another "anchor" element | [Stories](?path=/story/components-anchored-region--documentation) |
15+
| `avatar` | Visual represent an user or an object | [Stories](?path=/story/components-avatar--documentation) |
16+
| `badge` | Highlight an item and attract attention or flag status | [Stories](?path=/story/components-badge--documentation) |
17+
| `breadcrumb` | [Breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/) | [Stories](?path=/story/components-breadcrumb--documentation) |
18+
| `button` | [Button element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) | [Stories](?path=/story/components-button--documentation) |
19+
| `card` | Visual container | [Stories](?path=/story/components-card--documentation) |
20+
| `checkbox` | [Checkbox element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Input/checkbox) | [Stories](?path=/story/components-checkbox--documentation) |
21+
| `combobox` | [Combobox element](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) | [Stories](?path=/story/components-combobox--documentation) |
22+
| `data-grid` | [Grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) | [Stories](?path=/story/components-data-grid--documentation) |
23+
| `date-field` | [Date input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date) | [Stories](?path=/story/components-date-field--documentation) |
24+
| `divider` | [Horizontal or vertical rule](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr) | [Stories](?path=/story/components-divider--documentation) |
25+
| `menu` | [Menu](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) | [Stories](?path=/story/components-menu--documentation) |
26+
| `number-field` | [Number input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number) | [Stories](?path=/story/components-number-field--documentation) |
27+
| `progress` | [Meter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/) as line | [Stories](?path=/story/components-progress--documentation) |
28+
| `progress-ring` | [Meter pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/) as ring | [Stories](?path=/story/components-progress-ring--documentation) |
29+
| `radio-group` | [Radio pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) | [Stories](?path=/story/components-radio-group--documentation) |
30+
| `search` | [Search input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/search) | [Stories](?path=/story/components-search--documentation) |
31+
| `select` | [Select element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select) | [Stories](?path=/story/components-select--documentation) |
32+
| `skeleton` | [Skeleton element](https://open-ui.org/components/skeleton.research/) | [Stories](?path=/story/components-skeleton--documentation) |
33+
| `slider` | [Range input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/range) | [Stories](?path=/story/components-slider--documentation) |
34+
| `switch` | [Switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) | [Stories](?path=/story/components-switch--documentation) |
35+
| `tabs` | [Tab panel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) | [Stories](?path=/story/components-tabs--documentation) |
36+
| `text-area` | [Text area element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea) | [Stories](?path=/story/components-text-area--documentation) |
37+
| `text-field` | [Text input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/text) | [Stories](?path=/story/components-text-field--documentation) |
38+
| `toolbar` | [Toolbar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) | [Stories](?path=/story/components-toolbar--documentation) |
39+
| `tooltip` | [Tooltip pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) | [Stories](?path=/story/components-tooltip--documentation) |
40+
| `tree-view` | [Tree view pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/) | [Stories](?path=/story/components-tree-view--documentation) |

‎packages/components/docs/api-report.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
import { Meta } from '@storybook/addon-docs';
2+
import { Markdown } from '@storybook/blocks';
3+
import APIReport from './api-report.md';
4+
5+
<Meta title="API Report" />
6+
7+
<Markdown>{APIReport}</Markdown>

‎packages/components/docs/assets/toolkit-artwork.png‎

2.83 KB
Loading

0 commit comments

Comments
 (0)