mdx improvements

ui/package.json

@@ -2,7 +2,7 @@
     "name": "web-ui-boilerplate",
     "description": "UI boilerplate for websites/webapps using vanilla HTML/CSS/JavaScript, powered by Storybook, bundled by Parcel.",
     "author": "basher",
-    "version": "3.1.6",
+    "version": "3.1.7",
     "license": "ISC",
     "repository": {
         "type": "git",

ui/stories/2. Design System/Colours/Colours.mdx

@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/blocks';
+import { Meta, Canvas } from '@storybook/blocks';
 import * as Colours from './Colours.stories';
 
 <Meta of={Colours} />
@@ -7,6 +7,8 @@ import * as Colours from './Colours.stories';
 
 The default Sass colour variables get automatically exported to a JSON file when Parcel server is started with `npm start`.
 
+<Canvas of={Colours.Colours} />
+
 ## Dark mode
 Colours in the swatch will be updated automatically if the operating system preference for `dark mode` is selected.
 - This triggers the CSS `prefers-color-scheme: dark` media query.

ui/stories/2. Design System/Icons/Icons.mdx

@@ -5,6 +5,9 @@ import * as Icons from './Icons.stories';
 
 # Icons
 
+<Canvas of={Icons.Icons} />
+<Controls of={Icons.Icons} />
+
 ## Accessibility considerations
 
 - Accessible HTML markup for icons is based on these 3 articles:
@@ -23,6 +26,3 @@ import * as Icons from './Icons.stories';
 
 - The default icon size is `1em` so that it inherits the font size of its parent container.
 - Selecting any of the available size variants will set a specific icon size in `rem` units.
-
-<Canvas of={Icons.Icons} />
-<Controls of={Icons.Icons} />

ui/stories/3. Layout/Flex/Flex.mdx

@@ -7,6 +7,9 @@ import * as Flex from './Flex.stories';
 - Flexbox should **not** be used for a grid system.
 - Use something like [grid layout](/story/layout-grid--grid) or [asymmetric 2-col grid](/story/layout-grid--grid-asymmetric) for that.
 
+<Canvas of={Flex.Flex} />
+<Controls of={Flex.Flex} />
+
 ## When to use Flexbox or Grid?
 - Please see [useful layout tips](/docs/layout-useful-layout-tips--docs).
 
@@ -20,6 +23,3 @@ Change flex direction | `flex--column`, `flex--row-reverse`, `flex--column-rever
 Align items | `flex--ai-center`, `flex--ai-start`, `flex--ai-end`
 Justify content | `flex--jc-center`, `flex--jc-end`, `flex--jc-between`
 Make ALL flex items grow to fill up available space | `flex--grow-all`
-
-<Canvas of={Flex.Flex} />
-<Controls of={Flex.Flex} />

ui/stories/3. Layout/Grid/Grid.mdx

@@ -17,6 +17,9 @@ grid-template-columns: repeat(
 );
 ```
 
+<Canvas of={Grid.Grid} />
+<Controls of={Grid.Grid} />
+
 ## When to use Grid or Flexbox?
 - Please see [useful layout tips](/docs/layout-useful-layout-tips--docs).
 
@@ -60,12 +63,6 @@ widget-grid.grid {
 - Add the appropriate classname in the HTML - `grid--centered`.
 - See [cards in a grid](/story/components-cards--card-grid) for a real example.
 
-## Grid layout using `<div>` elements
-- Use generic `<div` when sub-dividing a page, or part of a page, into a multi-column layout.
-
-<Canvas of={Grid.Grid} />
-<Controls of={Grid.Grid} />
-
 ## Grid layout using `<ul>` elements
 
 <Canvas of={Grid.GridList} />

ui/stories/3. Layout/Wrapper/Wrapper.mdx

@@ -9,6 +9,9 @@ import * as Wrapper from './Wrapper.stories';
 - For more complex layouts (e.g. multi-column), use one of the [grid layouts](/docs/layout-grid--docs).
 - Ideally, there should be **NO visual styles** applied to wrappers (e.g. background colour).
 
+<Canvas of={Wrapper.Wrapper} />
+<Controls of={Wrapper.Wrapper} />
+
 ## Override margin
 - Use [stack layout](/story/layout-stack--stack) to apply vertical `gutters` between sibling wrappers.
 
@@ -17,6 +20,3 @@ import * as Wrapper from './Wrapper.stories';
 
 ## Applying visual styles to wrapper
 - Add a [skin component](/story/components-skin--skin-wrapper) classname.
-
-<Canvas of={Wrapper.Wrapper} />
-<Controls of={Wrapper.Wrapper} />

ui/stories/5. Components/Accordion/Accordion.mdx

@@ -6,14 +6,13 @@ import * as Accordion from './Accordion.stories';
 # Accordion
 - Uses the native HTML `<details>`|`<summary>` elements.
 
+<Canvas of={Accordion.Accordion} />
+
 ## Accessibility considerations
 - There are several articles cautioning against using `<details>`|`<summary>` for accordions. For example:
     - [Scott O'Hara](https://www.scottohara.me//blog/2022/09/12/details-summary.html).
     - [Dave Rupert](https://daverupert.com/2019/12/why-details-is-not-an-accordion/).
 - An alternative approach is to use the [disclosure](/story/components-disclosure-or-show-hide--disclosure) component.
 
-<Canvas of={Accordion.Accordion} />
-
 ## With custom icon
-
 <Canvas of={Accordion.AccordionCustomIcon} />

ui/stories/5. Components/Cards/Cards.mdx

@@ -10,7 +10,7 @@ import * as CardsNoArgs from './CardsNoArgs.stories';
 - By default, cards have no visual treatment such as background colour, border, shadow, etc. Apply visual styles using the [skin component](/story/components-skin--skin).
 - Also see [Inclusive Components cards](https://inclusive-components.design/cards/).
 
-## Card
+## Default card
 - The default card component is marked up as an `<article>`, and should therefore contain a heading with the appropriate level.
 - Uses `<picture>` with a single fixed size image, whose orientation can be `top`, `bottom`, `left` or `right`.
 

ui/stories/5. Components/Carousel/Carousel.mdx

@@ -8,13 +8,13 @@ import * as Carousel from './Carousel.stories';
 - It leverages [CSS scroll snap](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-snap-type) to improve keyboard-only behaviour.
 - Slide widths are defined by the CSS `--slide-min-width` custom property. This can be overridden for specific carousel implementations. For example, see the [card carousel](/story/components-cards--card-carousel).
 
+<Canvas of={Carousel.Carousel} />
+
 ## Accessibility considerations
 - Based on [Inclusive Components carousel](https://inclusive-components.design/a-content-slider/) and [ARIA APG carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/).
 - The carousel has `tabindex="0"` so it can receive keyboard `focus`, and be operated via the `LEFT|RIGHT` arrow keys.
 - CSS `scroll-snap` ensures the carousel stops at a complete slide.
 
-<Canvas of={Carousel.Carousel} />
-
 ## CSS-only fullwidth slides (e.g. banner carousel)
 <Canvas of={Carousel.CarouselFullwidthSlides} />
 

ui/stories/5. Components/Images/Images.mdx

@@ -4,15 +4,14 @@ import * as Images from './Images.stories';
 <Meta of={Images} />
 
 # Images
+<Canvas of={Images.ResponsiveImage} />
 
 ## Responsive and performance considerations
 - Responsive images use the HTML `<picture>` element with multiple image `sources`.
 - The image `media` queries are based on the CSS breakpoint values.
 - Images are [lazy loaded](https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading), but be aware of [not lazy loading images above the fold](https://web.dev/lazy-loading-best-practices/).
 -  Images have [explicit height & width](https://www.smashingmagazine.com/2020/03/setting-height-width-images-important-again/) declared in the HTML.
 
-<Canvas of={Images.ResponsiveImage} />
-
 ## Fixed size images
 - If just 1 image size is needed, still use the `<picture>` element.
 - This allows **next-gen** images to be served - e.g. `type="image/webp"`.

ui/stories/5. Components/Responsive Media/ResponsiveMedia.mdx

@@ -11,15 +11,14 @@ import * as ResponsiveMedia from './ResponsiveMedia.stories';
 style="--media-aspect-ratio: 21/9;"
 ```
 
+<Canvas of={ResponsiveMedia.ResponsiveIframe} />
+
 ## Accessibility considerations
 - `<iframe>` should have a non-empty `title` attribute.
 
 ## Performance considerations
 - Native [lazy-loaded iframes](https://web.dev/iframe-lazy-loading/) are now supported in modern browsers.
 - See the [video player](/story/components-video-player--video-player) for a real use case, with a fallback for older browsers.
 
-## Iframe
-<Canvas of={ResponsiveMedia.ResponsiveIframe} />
-
 ## Video
 <Canvas of={ResponsiveMedia.ResponsiveVideo} />

ui/stories/6. Web Components Or Custom Elements/WebUI Ajax Loader/WebUIAjaxLoader.mdx

@@ -6,7 +6,7 @@ import * as WebUIAjaxLoader from './WebUIAjaxLoader.stories';
 # `<webui-ajax-loader>`
 - Renders an animated loader via JavaScript while Ajax requests are being handled.
 
+<Canvas of={WebUIAjaxLoader.WebUIAjaxLoader} />
+
 ## Accessibility considerations
 - The Ajax loading spinner is an `<svg>` with an accessible `loading` name.
-
-<Canvas of={WebUIAjaxLoader.WebUIAjaxLoader} />

ui/stories/6. Web Components Or Custom Elements/WebUI Carousel/WebUICarousel.mdx

@@ -9,6 +9,9 @@ import * as WebUICarousel from './WebUICarousel.stories';
 - Each slide has an `aria-label`, indicating the current slide number and the total number of slides.
 - When PREV and NEXT buttons are shown, keyboard `focus` is modified such that **only visible slides are focusable**.
 
+<Canvas of={WebUICarousel.WebUICarousel} />
+<Controls of={WebUICarousel.WebUICarousel} />
+
 ## Required and optional HTML  or `data-` attributes
 
 Attribute | Behaviour
@@ -19,6 +22,3 @@ Attribute | Behaviour
 
 ## TODO
 - Update counter with touch/swipe events?
-
-<Canvas of={WebUICarousel.WebUICarousel} />
-<Controls of={WebUICarousel.WebUICarousel} />

ui/stories/6. Web Components Or Custom Elements/WebUI Disclosure/WebUIDisclosure.mdx

@@ -8,6 +8,9 @@ import * as WebUIDisclosure from './WebUIDisclosure.stories';
 - Use this Web Component when [accordion](/story/components-accordion--accordion) or [tabs](/story/components-tabs--tabs) components cannot be used.
 - Also see the [ARIA APG disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/).
 
+<Canvas of={WebUIDisclosure.WebUIDisclosure} />
+<Controls of={WebUIDisclosure.WebUIDisclosure} />
+
 ## Accessibility considerations
 - The content can be hidden via the `ESC` key, or clicking outside the Web Component. See the table below.
 
@@ -20,6 +23,3 @@ Attribute | Behaviour
 `data-content` | Required. Content to be shown/hidden.
 `data-bind-escape-key` | Optional. `ESC` key hides the content.
 `data-bind-click-outside` | Optional. Hides the content when clicking anywhere outside the Web Component.
-
-<Canvas of={WebUIDisclosure.WebUIDisclosure} />
-<Controls of={WebUIDisclosure.WebUIDisclosure} />

ui/stories/6. Web Components Or Custom Elements/WebUI Fetch Html/WebUIFetchHtml.mdx

@@ -7,6 +7,8 @@ import * as WebUIFetchHtml from './WebUIFetchHtml.stories';
 - This is simply a demo to show the core features of a component that has some Ajax dependencies (e.g. fetching an HTML fragment).
 - A more realistic example can be found in the [`<webui-predictive-search>`](/docs/web-components-or-custom-elements-webui-predictive-search--docs) Web Component.
 
+<Canvas of={WebUIFetchHtml.WebUIFetchHtml} />
+
 ## Uses native Fetch API
 - See [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) docs on MDN.
 - Fetch aborts/timeouts are handled by an [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) in `src/javascript/utils/ajax-helpers.ts`.
@@ -21,5 +23,3 @@ Attribute | Behaviour
 --- | ---
 `data-fetch-target` | Required. On the button that triggers the Fetch request. The value must match `data-fetch-container`.
 `data-fetch-container` | Required. On the ARIA live region. The value must match `data-fetch-target`.
-
-<Canvas of={WebUIFetchHtml.WebUIFetchHtml} />

ui/stories/6. Web Components Or Custom Elements/WebUI Form Validate/WebUIFormValidate.mdx

@@ -6,8 +6,8 @@ import * as WebUIFormValidate from './WebUIFormValidate.stories';
 # `<webui-form-validate>`
 - Client-side validation using JavaScript.
 
+<Canvas of={WebUIFormValidate.WebUIFormValidate} />
+
 ## Additional reading
 - See a [better approach to form validation](https://adamsilver.io/blog/the-problem-with-live-validation-and-what-to-do-instead/) that uses form `submit` rather than live inline validation.
 - Uses the [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#validating_forms_using_javascript).
-
-<Canvas of={WebUIFormValidate.WebUIFormValidate} />

ui/stories/6. Web Components Or Custom Elements/WebUI Image Gallery/WebUIImageGallery.mdx

@@ -10,8 +10,8 @@ import * as WebUIImageGallery from './WebUIImageGallery.stories';
 
 > Please note: For brevity, the large images only have a subset of [responsive image](/story/components-images--responsive-image) `<source>` markup.
 
+<Canvas of={WebUIImageGallery.WebUIImageGallery} />
+
 ## TODO
 - Consider extending `<webui-modal>` Web Component to enable a single modal instance to be opened by multiple triggers?
 - Consider showing the large images in a carousel?
-
-<Canvas of={WebUIImageGallery.WebUIImageGallery} />

ui/stories/6. Web Components Or Custom Elements/WebUI Make Clickable/WebUIMakeClickable.mdx

@@ -7,10 +7,10 @@ import * as WebUIMakeClickable from './WebUIMakeClickable.stories';
 - The entire Web Component is made clickable via JavaScript.
 - CSS `focus-within` is utilised to add a focus indicator when the Web Component, or any of its descendents, receives keyboard `focus`.
 
+<Canvas of={WebUIMakeClickable.WebUIMakeClickable} />
+
 ## Required and optional HTML  or `data-` attributes
 
 Attribute | Behaviour
 --- | ---
 `data-url` | Optional. Identifies the link whose URL is used for the click event. Fallback is the first link inside the Web Component.
-
-<Canvas of={WebUIMakeClickable.WebUIMakeClickable} />

ui/stories/6. Web Components Or Custom Elements/WebUI Modal/WebUIModal.mdx

@@ -6,6 +6,8 @@ import * as WebUIModal from './WebUIModal.stories';
 # `<webui-modal>`
 - Uses the native HTML `<dialog>` element. See [dialog](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) docs on MDN.
 
+<Canvas of={WebUIModal.WebUIModal} />
+
 ## Accessibility considerations
 - There are ongoing discussions about the [initial focus behaviour](https://github.com/whatwg/html/wiki/dialog--initial-focus,-a-proposal) for `<dialog>`.
     - Keyboard `focus` is currently being set on the `data-content` using `tabindex="-1"` to ensure that content gets announced first, before the `close` button.
@@ -24,8 +26,6 @@ Attribute | Behaviour
 - [Is dialog ready to be used?](https://www.scottohara.me/blog/2019/03/05/open-dialog.html)
 - [Defending dialog](https://whistlr.info/2021/in-defence-of-dialog/) by the official polyfill maintainer.
 
-<Canvas of={WebUIModal.WebUIModal} />
-
 ## Modal with overflowing content
 <Canvas of={WebUIModal.WebUIModalOverflow} />
 

ui/stories/6. Web Components Or Custom Elements/WebUI Notify/WebUINotify.mdx

@@ -4,6 +4,8 @@ import * as WebUINotify from './WebUINotify.stories';
 <Meta of={WebUINotify} />
 
 # `<webui-notify>`
+<Canvas of={WebUINotify.WebUINotify} />
+<Controls of={WebUINotify.WebUINotify} />
 
 ## Accessibility considerations
 - Error notifications have an [ARIA alert role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role).
@@ -17,6 +19,3 @@ Attribute | Behaviour
 `role="status"` | Required if `data-success` or `data-warning` have been used.
 `data-success`, `data-warning`, `data-error` | Optional. Apply different visual styling.
 `data-close` | Required on close button.
-
-<Canvas of={WebUINotify.WebUINotify} />
-<Controls of={WebUINotify.WebUINotify} />

ui/stories/6. Web Components Or Custom Elements/WebUI Predictive Search/WebUIPredictiveSearch.mdx

@@ -7,6 +7,8 @@ import * as WebUIPredictiveSearch from './WebUIPredictiveSearch.stories';
 - Predictive search (with dynamic results from an API)
 - When JavaScript is enabled, form submit is disabled and submit button is hidden.
 
+<Canvas of={WebUIPredictiveSearch.WebUIPredictiveSearch} />
+
 ## Accessibility considerations
 - Dynamic search results are displayed in an [aria-live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions).
 
@@ -16,5 +18,3 @@ Attribute | Behaviour
 --- | ---
 `data-fetch-target` | Required. On the button that triggers the Fetch request. The value must match `data-fetch-container`.
 `data-fetch-container` | Required. On the ARIA live region. The value must match `data-fetch-target`.
-
-<Canvas of={WebUIPredictiveSearch.WebUIPredictiveSearch} />

ui/stories/6. Web Components Or Custom Elements/WebUI Range Input/WebUIRangeInput.mdx

@@ -6,7 +6,7 @@ import * as WebUIRangeInput from './WebUIRangeInput.stories';
 # `<webui-range-input>`
 - JavaScript is required to display the numeric range value inside the `<output>` element.
 
+<Canvas of={WebUIRangeInput.WebUIRangeInput} />
+
 ## Accessibility considerations
 - See the [ARIA APG slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/).
-
-<Canvas of={WebUIRangeInput.WebUIRangeInput} />

ui/stories/6. Web Components Or Custom Elements/WebUI Share/WebUIShare.mdx

@@ -8,6 +8,8 @@ import * as WebUIShare from './WebUIShare.stories';
 - Fallback behaviour in non-supporting browsers allows user to copy the URL.
 - This Web Component contains a [`<webui-disclosure>`](/docs/web-components-or-custom-elements-webui-disclosure--docs).
 
+<Canvas of={WebUIShare.WebUIShare} />
+
 ## Required and optional HTML  or `data-` attributes
 
 - In addition to the `data-` attributes used with the [`<webui-disclosure>`](/docs/web-components-or-custom-elements-webui-disclosure--docs) Web Component:
@@ -17,7 +19,5 @@ Attribute | Behaviour
 `data-url` | Optional. URL of a different page to be shared.
 `data-title` | Optional. Title of the different page.
 
-<Canvas of={WebUIShare.WebUIShare} />
-
 ## `<webui-share>` another URL
 <Canvas of={WebUIShare.WebUIShareAnotherUrl} />

ui/stories/6. Web Components Or Custom Elements/WebUI Tabs/WebUITabs.mdx

@@ -4,6 +4,7 @@ import * as WebUITabs from './WebUITabs.stories';
 <Meta of={WebUITabs} />
 
 # `<webui-tabs>`
+<Canvas of={WebUITabs.WebUITabs} />
 
 ## Accessibility and responsive behaviour considerations
 - Rather than [Stacking tabs vertically on narrow viewports](https://inclusive-components.design/tabbed-interfaces/#responsivedesign), a simple horizontal overflow scrolling solution is used instead to make tabs responsive.
@@ -23,7 +24,5 @@ Attribute | Behaviour
 `data-tabpanel` | Required. Add to content that will be shown/hidden.
 `data-vertical` | Optional. Add to parent `<webui-tabs>` to create vertical tabs.
 
-<Canvas of={WebUITabs.WebUITabs} />
-
 ## Vertical tabs
 <Canvas of={WebUITabs.WebUIVerticalTabs} />

ui/stories/6. Web Components Or Custom Elements/WebUI Toggle/WebUIToggle.mdx

@@ -6,11 +6,10 @@ import * as WebUIToggle from './WebUIToggle.stories';
 # `<webui-toggle>`
 - Toggle button (or switch)
 
+<Canvas of={WebUIToggle.WebUIToggle} />
+
 ## Accessibility considerations
 - See the [ARIA APG switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/examples/switch-button/) and [Inclusive Components toggle](https://inclusive-components.design/toggle-button/) examples.
 
-## Toggle with no visible label
-<Canvas of={WebUIToggle.WebUIToggle} />
-
 ## Toggle with visible label
 <Canvas of={WebUIToggle.WebUIToggleWithLabel} />

ui/stories/6. Web Components Or Custom Elements/WebUI Video Player/WebUIVideoPlayer.mdx

@@ -6,11 +6,11 @@ import * as WebUIVideoPlayer from './WebUIVideoPlayer.stories';
 # `<webui-video-player>`
 - This Web Component contains a [`<webui-modal>`](/docs/web-components-or-custom-elements-webui-modal--docs), creating a simple "lightbox".
 
+<Canvas of={WebUIVideoPlayer.WebUIVideoPlayer} />
+
 ## Responsive, accessibility and performance considerations
 - See the [responsive media/video](/story/components-responsive-media--responsive-video) component.
 - If the browser does not support native `<iframe loading="lazy">` behaviour, the iframe `src` is removed until the video is played.
 
 ## Required and optional HTML  or `data-` attributes
 - Same as the [`<webui-modal>`](/docs/web-components-or-custom-elements-webui-modal--docs).
-
-<Canvas of={WebUIVideoPlayer.WebUIVideoPlayer} />