Skip to content

Commit

Permalink
docs: Fix Markdown tables (#2986)
Browse files Browse the repository at this point in the history
Add Github Flavored Markdown back to Storybook 7

[category:Documentation]
  • Loading branch information
NicholasBoll authored Oct 14, 2024
1 parent 4fa21d7 commit 55250dd
Show file tree
Hide file tree
Showing 11 changed files with 665 additions and 149 deletions.
11 changes: 11 additions & 0 deletions .storybook/main.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
const path = require('node:path');
const remarkGfm = require('remark-gfm').default;

const modulesPath = path.resolve(__dirname, '../modules');
const getSpecifications = require('../modules/docs/utils/get-specifications');
Expand All @@ -22,6 +23,16 @@ const config: StorybookConfig = {
},
'./readme-panel/preset.js',
'@storybook/addon-storysource',
{
name: '@storybook/addon-docs',
options: {
mdxPluginOptions: {
mdxCompileOptions: {
remarkPlugins: [remarkGfm],
},
},
},
},
],
core: {
builder: '@storybook/builder-webpack5',
Expand Down
16 changes: 3 additions & 13 deletions modules/docs/mdx/10.0-UPGRADE-GUIDE.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
import {Markdown} from '@storybook/blocks';

<Meta title="Guides/Upgrade Guides/v10.0" />

# Canvas Kit 10.0 Upgrade Guide
Expand Down Expand Up @@ -162,8 +160,6 @@ updated on a 1:1 basis. None of the base values have changed, only the unit.
The table below shows what each token value is, what it corresponds to, and what the new `rem` value
is in `px`:

<Markdown>
{`
| px Value | rem Value | space Token |
| -------- | --------- | ----------- |
| 0 | 0 | zero |
Expand All @@ -176,23 +172,17 @@ is in `px`:
| 40px | 2.5rem | xl |
| 64px | 4rem | xxl |
| 80px | 5rem | xxxl |
`}
</Markdown>

You can convert a `px` value to a `rem` value by dividing your `px` value by `16`(if your default
browser font size hasn't been updated, the value will be `16`).

For example:

<Markdown>
{`
| Equation | rem Value |
| ----------- | --------- |
| \`16px/16px\` | \`1rem\` |
| \`32px/16px\` | \`2rem\` |
| \`8px/16px\` | \`0.5rem\` |
`}
</Markdown>
| `16px/16px` | `1rem` |
| `32px/16px` | `2rem` |
| `8px/16px` | `0.5rem` |

#### Why Did We Make This Change?

Expand Down
97 changes: 36 additions & 61 deletions modules/docs/mdx/5.0-UPGRADE-GUIDE.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
import {Markdown} from '@storybook/blocks';

<Meta title="Guides/Upgrade Guides/v5.0" />

# Canvas Kit 5.0 Upgrade Guide
Expand Down Expand Up @@ -124,51 +122,43 @@ updated as you expect.
tokens in `@workday/canvas-kit-labs-react-core`, but some are using the Legacy type in
`@workday/canvas-kit-react-core`.

<Markdown>{`
| Legacy Type (px) | Responsive Type (rem) |
| ----------------- | ---------------------------------------- |
| \`dataViz1\` (56px) | \`levels.title.large\` (3.5rem \ 56px) |
| \`dataViz2\` (34px) | \`levels.heading.large\` (2rem \ 32px) |
| \`h1\` (28px) | \`levels.heading.medium\` (1.75rem \ 28px) |
| \`h2\` (24px) | \`levels.heading.small\` (1.5rem \ 24px) |
| \`h3\` (20px) | \`levels.body.large\` (1.25rem,) \ 20px |
| \`h4\` (16px) | \`levels.body.small\` (1rem \ 16px) |
| \`h5\` (16px) | \`levels.body.small\` (1rem \ 16px) |
| \`body\` (14px) | \`levels.subtext.large\` (0.875rem \ 14px) |
| \`body2\` (13px) | \`levels.subtext.medium\` (0.75rem \ 12px) |
| \`small\` (12px) | \`levels.subtext.medium\` (0.75rem \ 12px) |
`}</Markdown>
| `dataViz1` (56px) | `levels.title.large` (3.5rem \ 56px) |
| `dataViz2` (34px) | `levels.heading.large` (2rem \ 32px) |
| `h1` (28px) | `levels.heading.medium` (1.75rem \ 28px) |
| `h2` (24px) | `levels.heading.small` (1.5rem \ 24px) |
| `h3` (20px) | `levels.body.large` (1.25rem,) \ 20px |
| `h4` (16px) | `levels.body.small` (1rem \ 16px) |
| `h5` (16px) | `levels.body.small` (1rem \ 16px) |
| `body` (14px) | `levels.subtext.large` (0.875rem \ 14px) |
| `body2` (13px) | `levels.subtext.medium` (0.75rem \ 12px) |
| `small` (12px) | `levels.subtext.medium` (0.75rem \ 12px) |

- 🤖 Property Updates

All `fontFamily`, `fontSize`, and `fontWeight` property updates are handled by the codemod.

<Markdown>
{`| CSS Property | Corresponding Token | Notes |
| CSS Property | Corresponding Token | Notes |
| ------------ | ------------------------------ | --------------------------------------------------------------- |
| \`fontFamily\` | \`type.properties.fontFamilies\` | \`default\` (Roboto) and \`monospace\` (Roboto Mono) are available |
| \`fontSize\` | \`type.properties.fontSizes\` | please consult the type hierarchies above to map values |
| \`fontWeight\` | \`type.properties.fontWeights\` | \`regular\` (400), \`medium\` (500), and \`bold\` (700) are available |`}
</Markdown>
| `fontFamily` | `type.properties.fontFamilies` | `default` (Roboto) and `monospace` (Roboto Mono) are available |
| `fontSize` | `type.properties.fontSizes` | please consult the type hierarchies above to map values |
| `fontWeight` | `type.properties.fontWeights` | `regular` (400), `medium` (500), and `bold` (700) are available |

- 🤖 Variant Updates

All `variant` updates _except `link`_ are handled by the codemod. Please see the
[variants](#variants) section below for more information.

<Markdown>
{`
| Variant | Transformation | Notes |
| ---------------------- | ------------------------------------------------------------------------------ | --------------------------------------- |
| \`type.variant.error\` | \`type.variants.error\` | name change only |
| \`type.variant.hint\` | \`type.variants.hint\` | name change only |
| \`type.variant.inverse\` | \`type.variants.inverse\` | name change only |
| \`type.variant.button\` | \`{fontWeight: type.properties.fontWeights.bold}\` | variant deprecated, use type properties |
| \`type.variant.caps\` | \`{textTransform: 'uppercase', fontWeight: type.properties.fontWeights.medium}\` | variant deprecated, use type properties |
| \`type.variant.label\` | \`{fontWeight: type.properties.fontWeights.medium}\` | variant deprecated, use type properties |
| \`type.variant.mono\` | \`{fontFamily: type.properties.fontFamilies.monospace}\` | variant deprecated, use type properties |
`}
</Markdown>
| `type.variant.error` | `type.variants.error` | name change only |
| `type.variant.hint` | `type.variants.hint` | name change only |
| `type.variant.inverse` | `type.variants.inverse` | name change only |
| `type.variant.button` | `{fontWeight: type.properties.fontWeights.bold}` | variant deprecated, use type properties |
| `type.variant.caps` | `{textTransform: 'uppercase', fontWeight: type.properties.fontWeights.medium}` | variant deprecated, use type properties |
| `type.variant.label` | `{fontWeight: type.properties.fontWeights.medium}` | variant deprecated, use type properties |
| `type.variant.mono` | `{fontFamily: type.properties.fontFamilies.monospace}` | variant deprecated, use type properties |

#### Manual Updates

Expand Down Expand Up @@ -636,20 +626,14 @@ types (which were too generic) and their JSDoc hints.

The following table describes each update:

<Markdown>
{`
| Before | After | Change Description |
| --------------------- | ------------------------- | -------------------------------- |
| \`spacing\` | \`space\` | name change only |
| \`spacingNumbers\` | \`spaceNumbers\` | name change only |
| \`CanvasSpacing\` | \`CanvasSpace\` | name change and improved types\* |
| \`CanvasSpacingValue\` | \`CanvasSpaceValues\` | name change only |
| \`CanvasSpacingNumber\` | \`CanvasSpaceNumbers\` | name change and improved types\* |
| \`n/a\` | \`CanvasSpaceNumberValues\` | new type! |
`}

</Markdown>
| `spacing` | `space` | name change only |
| `spacingNumbers` | `spaceNumbers` | name change only |
| `CanvasSpacing` | `CanvasSpace` | name change and improved types\* |
| `CanvasSpacingValue` | `CanvasSpaceValues` | name change only |
| `CanvasSpacingNumber` | `CanvasSpaceNumbers` | name change and improved types\* |
| `n/a` | `CanvasSpaceNumberValues` | new type! |

\* Before, the types were too generic and not very useful. They now better reflect the values they
represent.
Expand Down Expand Up @@ -1202,18 +1186,14 @@ Pass a `css` prop or a styled button instead to have a custom styled button. You

If you were using `usePopup` before, here's a list of equivalent APIs:

<Markdown>
{`
| Before | After |
| ----------------------------------------------------------------------- | ------------------------------------- |
| \`const { popperProps, targetProps, closePopup, stackRef } = usePopup()\` | \`const model = usePopupModel()\` |
| \`popperProps.open\` | \`model.state.visibility !== 'hidden'\` |
| \`closePopup()\` | \`model.events.hide()\` |
| \`stackRef\` or \`popperProps.ref\` | \`model.state.stackRef\` |
| \`popperProps.anchorElement\` | \`model.state.targetRef.current\` |
| \`targetProps.onClick\` | \`usePopupTarget(model).onClick\` |
`}
</Markdown>
| `const { popperProps, targetProps, closePopup, stackRef } = usePopup()` | `const model = usePopupModel()` |
| `popperProps.open` | `model.state.visibility !== 'hidden'` |
| `closePopup()` | `model.events.hide()` |
| `stackRef` or `popperProps.ref` | `model.state.stackRef` |
| `popperProps.anchorElement` | `model.state.targetRef.current` |
| `targetProps.onClick` | `usePopupTarget(model).onClick` |

#### New Focus Management

Expand Down Expand Up @@ -1288,16 +1268,11 @@ model and behaviors, the following is equivalent:

`Popup.Card` uses `Card`, which is now using `Box`. Consequently, the following props have changed:

<Markdown>
{`
| Before | After |
| ------------------------------ | ------------------------------------------ |
| \`padding={Popup.Padding.zero}\` | \`padding="zero"\` or \`padding={space.zero}\` |
| \`depth={depth[0]}\` | \`depth={0}\` |
| \`popupRef={ref}\` | \`ref={ref}\` |
`}

</Markdown>
| `padding={Popup.Padding.zero}` | `padding="zero"` or `padding={space.zero}` |
| `depth={depth[0]}` | `depth={0}` |
| `popupRef={ref}` | `ref={ref}` |

#### Transitioning

Expand Down
16 changes: 5 additions & 11 deletions modules/docs/mdx/6.0-UPGRADE-GUIDE.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
import {Markdown} from '@storybook/blocks';

<Meta title="Guides/Upgrade Guides/v6.0" />

# Canvas Kit 6.0 Upgrade Guide
Expand Down Expand Up @@ -369,17 +367,13 @@ layout. If you have questions about this testing, please reach out to our team.

Below is a reference table for the V5 and V6 breakpoint values.

<Markdown>
{`
| Breakpoint Name | V5 Value (px) | V6 Value (px) |
| --------------- | ------------- | ------------- |
| \`zero\` | 0 | 0 |
| \`s\` | 600 | 320 |
| \`m\` | 900 | 768 |
| \`l\` | 1280 | 1024 |
| \`xl\` | 1920 | 1440 |
`}
</Markdown>
| `zero` | 0 | 0 |
| `s` | 600 | 320 |
| `m` | 900 | 768 |
| `l` | 1280 | 1024 |
| `xl` | 1920 | 1440 |

Also for reference, these are our viewport ranges:

Expand Down
22 changes: 8 additions & 14 deletions modules/docs/mdx/7.0-UPGRADE-GUIDE.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
import {Markdown} from '@storybook/blocks';

<Meta title="Guides/Upgrade Guides/v7.0" />

# Canvas Kit 7.0 Upgrade Guide
Expand Down Expand Up @@ -563,19 +561,15 @@ To consolidate Button APIs, we've removed `IconButton` in favor of `SecondaryBut
`TertiaryButton`. The following table shows how `IconButton` variants in v6 map to their
corresponding buttons in v7.

<Markdown>
{`
| v6 \`IconButton\` variant | v7 button (and variant, if necessary) |
| v6 `IconButton` variant | v7 button (and variant, if necessary) |
| -------------------------- | ---------------------------------------- |
| \`circle\` (default variant) | \`TertiaryButton\` |
| \`circleFilled\` | \`SecondaryButton\` |
| \`inverse\` | \`TertiaryButton\` with \`inverse\` variant |
| \`inverseFilled\` | \`SecondaryButton\` with \`inverse\` variant |
| \`plain\` | Unsupported |
| \`square\` | Unsupported |
| \`squareFilled\` | Unsupported |
`}
</Markdown>
| `circle` (default variant) | `TertiaryButton` |
| `circleFilled` | `SecondaryButton` |
| `inverse` | `TertiaryButton` with `inverse` variant |
| `inverseFilled` | `SecondaryButton` with `inverse` variant |
| `plain` | Unsupported |
| `square` | Unsupported |
| `squareFilled` | Unsupported |

> Note: See below for more information about how to manually migrate from
> [unsupported v6 variants](#unsupported-iconbutton-variants).
Expand Down
16 changes: 5 additions & 11 deletions modules/docs/mdx/MAINTAINING.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
import {Markdown} from '@storybook/blocks';

<Meta title="Guides/Maintaining" />

# Maintaining Canvas Kit
Expand Down Expand Up @@ -52,17 +50,13 @@ runs on `support`, `master`, and `prerelease/minor` branches. Forward merges for
starts with `chore: Release`, and that's how the forward merge workflow identifies them. Forward
merges will run on every merge to `prerelease/minor` regardless of the commit message.

<Markdown>
{`
| Run Forward Merge? | Branch | Commit Message |
| ------------------ | ------------------ | --------------------------------------- |
| ✅ | \`support\` | \`chore: Release v6.8.14 [skip release]\` |
| ⛔️ | \`support\` | \`fix: Remove unused props\` |
| ✅ | \`master\` | \`chore: Release v7.3.0 [skip release]\` |
| ⛔️ | \`master\` | \`fix: Update Popup types\` |
| ✅ | \`prerelease/minor\` | \`feat: Add new Layout components\` |
`}
</Markdown>
|| `support` | `chore: Release v6.8.14 [skip release]` |
| ⛔️ | `support` | `fix: Remove unused props` |
|| `master` | `chore: Release v7.3.0 [skip release]` |
| ⛔️ | `master` | `fix: Update Popup types` |
|| `prerelease/minor` | `feat: Add new Layout components` |

If the forward merge workflow fails and cannot automatically merge the update to the next branch, it
will generate a PR with instructions on how to handle the forward merge manually. For a more
Expand Down
20 changes: 7 additions & 13 deletions modules/preview-react/menu/stories/Menu.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
import {Markdown} from '@storybook/blocks';

import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
import {StatusIndicator} from '@workday/canvas-kit-preview-react/status-indicator';
import * as MenuStories from './Menu.stories';
Expand Down Expand Up @@ -53,19 +51,15 @@ closing the `DeprecatedMenu`.
using `aria-activedescendant`. Below is table of supported keyboard shortcuts and associated
actions.

<Markdown>
{`
| Key | Action |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| \`Enter\` or \`Space\` | Activates the menu item and then closes the menu |
| \`Escape\` | Closes the menu |
| \`Up Arrow\` | Moves focus to the previous menu item – if focus is on first menu item, it moves focus to the last menu item |
| \`Down Arrow\` | Moves focus to the next menu item – if focus is on last menu item, it moves focus to the first menu item |
| \`Home\` | Moves focus to the first menu item |
| \`End\` | Moves focus to the last menu item |
| \`A-Z / a-z\` | Moves focus to the next menu item with a label that starts with the typed character if such an menu item exists – otherwise, focus does not move |
`}
</Markdown>
| `Enter` or `Space` | Activates the menu item and then closes the menu |
| `Escape` | Closes the menu |
| `Up Arrow` | Moves focus to the previous menu item – if focus is on first menu item, it moves focus to the last menu item |
| `Down Arrow` | Moves focus to the next menu item – if focus is on last menu item, it moves focus to the first menu item |
| `Home` | Moves focus to the first menu item |
| `End` | Moves focus to the last menu item |
| `A-Z / a-z` | Moves focus to the next menu item with a label that starts with the typed character if such an menu item exists – otherwise, focus does not move |

Note that although `DeprecatedMenu` includes support for keyboard shortcuts for the menu itself,
you'll need to add your own keyboard handling and aria attributes to the triggering button.
Expand Down
Loading

0 comments on commit 55250dd

Please sign in to comment.