@workday/canvas-kit-docs 17.0.0-alpha.0605-next.0 → 17.0.0-alpha.0613-next.0

package/dist/es6/lib/stackblitzFiles/packageJSONFile.js

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "16.1.1",
-    "@workday/canvas-kit-preview-react": "16.1.1",
-    "@workday/canvas-kit-react": "16.1.1",
-    "@workday/canvas-kit-react-fonts": "^16.1.1",
-    "@workday/canvas-kit-styling": "16.1.1",
+    "@workday/canvas-kit-labs-react": "16.1.2",
+    "@workday/canvas-kit-preview-react": "16.1.2",
+    "@workday/canvas-kit-react": "16.1.2",
+    "@workday/canvas-kit-react-fonts": "^16.1.2",
+    "@workday/canvas-kit-styling": "16.1.2",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts

@@ -19,11 +19,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "16.1.1",
-    "@workday/canvas-kit-preview-react": "16.1.1",
-    "@workday/canvas-kit-react": "16.1.1",
-    "@workday/canvas-kit-react-fonts": "^16.1.1",
-    "@workday/canvas-kit-styling": "16.1.1",
+    "@workday/canvas-kit-labs-react": "16.1.2",
+    "@workday/canvas-kit-preview-react": "16.1.2",
+    "@workday/canvas-kit-react": "16.1.2",
+    "@workday/canvas-kit-react-fonts": "^16.1.2",
+    "@workday/canvas-kit-styling": "16.1.2",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-expressive-icons-web": "1.0.1",
     "@workday/canvas-tokens-web": "4.4.0-beta.11"

package/dist/mdx/react/common/mdx/examples/CreateComponent.tsx

@@ -6,7 +6,7 @@ import {system} from '@workday/canvas-tokens-web';
 
 // Extend Heading Props and omitting size since we've added a default
 interface CardHeadingProps extends Omit<ExtractProps<typeof Heading>, 'size'> {}
-export default createComponent('h2')({
+export const CardHeading = createComponent('h2')({
   displayName: 'CardHeading',
   Component: ({children, ...elemProps}: CardHeadingProps, ref, Element) => {
     return (
@@ -19,7 +19,7 @@ export default createComponent('h2')({
 
 // Extend Box Props for customization
 interface CardProps extends BoxProps {}
-export default createComponent('div')({
+export const Card = createComponent('div')({
   displayName: 'Card',
   subComponents: {
     Heading: CardHeading,
@@ -39,7 +39,7 @@ const cardStyles = createStyles({
   padding: system.padding.sm,
 });
 
-export default () => {
+export const CreateComponent = () => {
   return (
     <Card cs={cardStyles} as="section">
       <Card.Heading>Card Heading</Card.Heading>

package/dist/mdx/react/expandable/Expandable.mdx

@@ -1,12 +1,12 @@
 import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';
 
-import StartIcon from './examples/StartIcon';
-import EndIcon from './examples/EndIcon';
 import Avatar from './examples/Avatar';
 import Depth from './examples/Depth';
-import RTL from './examples/RTL';
-import LongTitle from './examples/LongTitle';
+import EndIcon from './examples/EndIcon';
 import HoistedModel from './examples/HoistedModel';
+import LongTitle from './examples/LongTitle';
+import RTL from './examples/RTL';
+import StartIcon from './examples/StartIcon';
 
 
 # Canvas Kit Expandable
@@ -23,8 +23,8 @@ yarn add @workday/canvas-kit-react
 
 ### Start Icon
 
-For a basic expandable container with a chevron icon before the title, place`Expandable.Icon` before
-`Expandable.Title` as children of `Expandable.Target` and pass the `iconPosition` prop to
+For a basic expandable container with a chevron icon before the title, place `Expandable.Icon`
+before `Expandable.Title` as children of `Expandable.Target` and pass the `iconPosition` prop to
 `Expandable.Icon` with a value of `start`. `Expandable.Icon` will use a right chevron icon when
 collapsed and a down chevron icon when expanded.
 
@@ -46,18 +46,12 @@ To include an avatar image, `Expandable.Avatar` should be placed between `Expand
 to `Expandable.Icon` depending on whether the `Expandable.Icon` is placed before or after
 `Expandable.Title`.
 
-**Note:** If using an avatar image, do not also include an Icon component in addition to the Expandable.Icon.
-This component is meant to have either an avatar image or an icon in addition to the Expandable.Icon, or neither
-an avatar image nor an extra icon.
-
+**Note:** If using an avatar image, do not also include an Icon component in addition to the
+Expandable.Icon. This component is meant to have either an avatar image or an icon in addition to
+the Expandable.Icon, or neither an avatar image nor an extra icon.
 
 <ExampleCodeBlock code={Avatar} />
 
-> **Accessibility Note:** In this situation, the Avatar is decorative and should not be announced to
-> screen readers. The `<Expandable.Avatar>` component has `isDecorative` set to `true` by default to
-> hide it from screen readers, as avatars in expandable headers are typically decorative when paired
-> with adjacent text.
-
 ### Right to Left (RTL)
 
 Expandable container has bidirectional support and should function as expected with RTL languages as
@@ -78,8 +72,6 @@ Long titles will wrap to the next line and increase the height of the container.
 
 <ExampleCodeBlock code={LongTitle} />
 
-You can also have direct access to the model if
-
 ### Hoisted Model
 
 If you need direct access to the model, you can hoist it with the `useExpandableModel` hook. In the
@@ -87,47 +79,161 @@ example below, we're hoisting the models to expand and collapse all three contai
 
 <ExampleCodeBlock code={HoistedModel} />
 
-> **Accessibility Note:** When using multiple Expandable Containers on a page, use the `as` prop to
-> render the `<Expandable.Content>` sub-component as an HTML `<section>` element. Then, use
-> `aria-labelledby` to reference the unique `id` of the `<Expandable.Title>` element. This practice
-> can be useful to screen reader users when multiple Expandable Containers are opened at one time
-> for uniquely describing the boundaries of the expandable content.
+For the accordion composition (named regions on each panel), see
+[Accessibility Requirements](#accessibility-requirements).
 
 ## Accessibility
 
-Our Expandable component renders a semantic HTML `<button>` element to the DOM, with an optional
-parent heading element as defined by the `headingLevel` prop. The `aria-expanded` property is
-included on the button to indicate the state of the content to screen readers.
-
-[Accordion Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)
-
-- Use the `headingLevel` prop to assign an appropriate heading level based on the context of the
-  page content.
-- When using Expandable Container for navigation elements, then we don't recommend using the
-  `headingLevel` prop. This will render only expandable buttons to the DOM, reserving headings for
-  organizing content in the main body of the page.
-- The `as` prop may also be used on `<Expandable.Content>` to render an HTML `<ul>` element for
-  displaying a list of items. For example, check out
-  [Side Panel with Navigation](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-side-panel-navigation--docs).
-
-### Navigation
-
-- **Tab key**: Moves focus to the next expandable button or focusable element
-- **Shift + Tab**: Moves focus to the previous focusable element
-- **Enter or Space**: Toggles the expanded/collapsed state
-
-### Screen Reader Experience
-
-- The expandable button will be announced with its title text followed by the button role
-- The current state will be announced as either "collapsed" or "expanded" (For example: "Usage
-  Guidance, button, collapsed" or "Usage Guidance, button, expanded")
-- **State Changes:** When activating the button to expand content, screen readers will announce the
-  new "expanded" state and vice versa when collapsing content.
-- **Content Regions:** Screen reader users can use landmark navigation to jump between sections and
-  each section will be announced with its associated title (For example: "Usage Guidance, landmark
-  region")
-- **Heading Structure:** Using heading levels with expandable buttons allows screen reader users to
-  navigate by headings, making the document structure and hierarchy easier to understand.
+Ensure users of assistive technology can find the control, understand whether related content is
+shown or hidden, and reveal or hide that content from the keyboard. **`Expandable`** is an inline
+[disclosure (show/hide)](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) widget: a button
+toggles content that stays in the document flow.
+
+Use **`Expandable`** for show/hide sections in the page. Compose multiple instances to build an
+[accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) — see
+[Hoisted Model](#hoisted-model). For a navigation accordion, see
+[Side Panel with Navigation](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-side-panel-navigation--docs).
+
+### Minimum Accessible Structure
+
+The following matches the [Start Icon](#start-icon) example layout: **`Expandable.Icon`** before
+**`Expandable.Title`** inside **`Expandable.Target`**, then **`Expandable.Content`**.
+**`headingLevel`** is omitted here on purpose — add it only after asking which level matches the
+page outline (see **Accessibility Requirements**). The Basic Example code uses `headingLevel="h4"`
+as a sample, not a default.
+
+```tsx
+import {Expandable} from '@workday/canvas-kit-react/expandable';
+
+<Expandable>
+  <Expandable.Target>
+    <Expandable.Icon iconPosition="start" />
+    <Expandable.Title>Title</Expandable.Title>
+  </Expandable.Target>
+  <Expandable.Content>Content</Expandable.Content>
+</Expandable>;
+```
+
+### Built-in Behaviors
+
+Canvas Kit applies these automatically via `useExpandableModel` (a `DisclosureModel`) and Expandable
+subcomponents. **Do not duplicate them** in consuming code.
+
+**ARIA and DOM** (_applied by hooks/subcomponents_):
+
+- **`Expandable.Target`**: native `<button>` with `aria-expanded` (`true` when
+  `visibility !== 'hidden'`) and `aria-controls` set to the disclosure `id`. `onClick` toggles
+  `events.show()` / `events.hide()`.
+- **`headingLevel`**: when set (`'h1'`–`'h6'`), wraps the button in **`Heading`** rendered as that
+  heading element. When omitted, the button is not wrapped in a heading.
+- **`Expandable.Content`**: `id` set to the same disclosure `id`. Collapsed content stays in the DOM
+  with `display: none` (not unmounted). Default element is a `<div>`.
+- **`Expandable.Title`**: styled `<div>` for the visible name. It does **not** receive an `id` from
+  the model.
+- **`Expandable.Icon`**: decorative chevron that rotates from `visibility`. Expanded/collapsed state
+  for assistive technology comes from `aria-expanded`, not from the icon.
+- **`Expandable.Avatar`**: `isDecorative={true}` by default so the image is hidden from assistive
+  technology when paired with **`Expandable.Title`**.
+- Disclosure `id`: generated with `useUniqueId` unless you pass `id` to **`useExpandableModel`**.
+  Default `initialVisibility` is `'hidden'`.
+
+**Keyboard** (_native button behavior_):
+
+**`Expandable.Target`** uses native `<button>` keyboard behavior (tab order, <kbd>Enter</kbd> /
+
+<kbd>Space</kbd> to toggle). Collapsed content is not in the tab order (`display: none`). Focus
+stays on the button; Canvas Kit does not move focus into **`Expandable.Content`**.
+
+**Screen reader expectations** (_when built-in behaviors are used as intended_):
+
+- On focus, assistive technology announces the title text, the button role, and expanded/collapsed
+  state from `aria-expanded` (for example, "Title, button, collapsed")
+- Activating the button announces the updated expanded/collapsed state from `aria-expanded`
+- While collapsed, content is removed from the accessibility tree (`display: none`)
+- While expanded, content follows the button in reading order
+- When **`headingLevel`** is set, heading navigation includes the heading that wraps the button
+- When **`Expandable.Content as="section"`** is used with `aria-labelledby` pointing at
+  **`Expandable.Title`**, region/landmark navigation can name each open section
+
+### Accessibility Requirements
+
+Required in application code for an accessible Expandable. Hoist **`useExpandableModel`** when you
+need programmatic show/hide (for example, expand all) or a stable disclosure `id`. Rows marked
+_(conditional)_ apply only when the situation matches—otherwise omit.
+
+**If no design spec is provided:** use the **single disclosure** composition
+([Basic Example](#basic-example)). If the spec is several related headers, use the **accordion**
+composition. Omit **`Expandable.Avatar`**, **`initialVisibility`**, and a custom **`id`**.
+
+**Choose a composition** (pick one; **`Expandable.Content as="section"`** and **`as="ul"`** are
+mutually exclusive):
+
+- **Single disclosure** — one show/hide section. [Basic Example](#basic-example) /
+  [Minimum Accessible Structure](#minimum-accessible-structure). Default Content is a `<div>`.
+- **Accordion** — several related headers. [Hoisted Model](#hoisted-model): unique `id` on
+  **`Expandable.Title`**, **`Expandable.Content as="section"`** with `aria-labelledby`.
+- **Navigation list** — disclosed links.
+  [Side Panel with Navigation](https://workday.github.io/canvas-kit/?path=/docs/guides-accessibility-examples-side-panel-navigation--docs):
+  **`as="ul"`**, omit **`headingLevel`**.
+
+**Heading level:** Ask which heading (`h1`–`h6`) belongs in the document outline before setting
+**`headingLevel`**. Omit **`headingLevel`** for navigation. Do not generate **`headingLevel`** by
+default — the Basic Example code uses `h4` only as a sample.
+
+| Requirement                                     | How to satisfy                                                                                                                                                                                     |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Accessible name                                 | Non-empty **`Expandable.Title`** inside **`Expandable.Target`**.                                                                                                                                   |
+| Keyboard-operable toggle                        | **`Expandable.Target`** (native `<button>`).                                                                                                                                                       |
+| Visual expanded/collapsed indicator             | **`Expandable.Icon`** with `iconPosition` matching layout (`start` or `end`).                                                                                                                      |
+| Heading in the document outline _(conditional)_ | **`headingLevel`** on **`Expandable.Target`** when the control titles body content (single disclosure or accordion). Omit **`headingLevel`** for the navigation-list composition. Ask which level. |
+| Accordion named regions _(conditional)_         | Accordion composition: **`Expandable.Content as="section"`** plus `aria-labelledby` referencing a unique `id` on **`Expandable.Title`**.                                                           |
+| List markup _(conditional)_                     | Navigation-list composition: **`Expandable.Content as="ul"`** (and list items as children).                                                                                                        |
+| Decorative avatar _(conditional)_               | **`Expandable.Avatar`** when the design includes an avatar. Keep **`isDecorative`** at the default `true`.                                                                                         |
+| Start expanded _(conditional)_                  | `initialVisibility: 'visible'` on **`useExpandableModel`** (or the equivalent model config).                                                                                                       |
+| Programmatic expand/collapse _(conditional)_    | Hoist **`useExpandableModel`** and call `model.events.show()` / `model.events.hide()`.                                                                                                             |
+
+**Summary for code generation:**
+
+- **REQUIRED:** **`Expandable.Target`**, non-empty **`Expandable.Title`**, **`Expandable.Content`**,
+  **`Expandable.Icon`**
+- **CONDITIONAL:** composition (single disclosure vs accordion vs navigation list),
+  **`headingLevel`** (ask which; omit for navigation), accordion **`as="section"`** +
+  `aria-labelledby`, navigation **`as="ul"`**, **`Expandable.Avatar`**, hoisted
+  **`useExpandableModel`**, **`initialVisibility`**
+
+### Anti-Patterns
+
+Do **not** generate code that does the following (see **Accessibility Requirements** above for what
+to supply instead):
+
+- Manually set `aria-expanded`, `aria-controls`, or the disclosure `id` on **`Expandable.Target`**
+  or **`Expandable.Content`** — `useExpandableTarget` and `useExpandableContent` wire these
+- Rely on **`Expandable.Icon`** or **`Expandable.Avatar`** for the accessible name — use
+  **`Expandable.Title`**
+- Override **`Expandable.Target`** with a custom **`as`** — **`Expandable.Target`** already renders
+  a native `<button>`
+- Set `id` on **`Expandable`** to identify the outer wrapper — `id` is model config **and** is
+  forwarded to the container element, while **`Expandable.Content`** also uses `state.id`, which can
+  produce duplicate IDs. For a stable content `id`, hoist **`useExpandableModel({id: '…'})`**.
+  **`Expandable.Title`** still needs its own `id` when you set `aria-labelledby` on
+  **`Expandable.Content`**
+- Wrap **`Expandable.Target`** in your own heading — use **`headingLevel`** instead
+- Default **`headingLevel`** to `h4` (or any level) without asking, or set **`headingLevel`** on
+  navigation disclosures
+- Generate several Basic Example disclosures with default `div` Content when the spec is an
+  accordion — use the **accordion** composition (see **Choose a composition**)
+- Set **`as="section"`** and **`as="ul"`** on the same **`Expandable.Content`** — pick one
+  composition
+- Change **`Expandable.Title`** to encode state (for example "Collapsed" / "Expanded" or "Show" /
+  "Hide") — `aria-expanded` already exposes state
+- Unmount **`Expandable.Content`** when collapsed, or add `aria-hidden` on it — the library uses
+  `display: none`
+- Set **`isDecorative={false}`** on **`Expandable.Avatar`** by default, or pair an avatar with an
+  extra non-chevron icon
+- Use **`open`**, **`expanded`**, or **`onToggle`** props on **`Expandable`** — visibility is
+  `initialVisibility` plus **`useExpandableModel`** events
+- Assume default **`Expandable.Content`** is a landmark region — that is only true with
+  **`as="section"`**
 
 ## Component API
 

package/dist/mdx/styling/mdx/examples/CSProp.tsx

@@ -10,7 +10,7 @@ const myStencil = createStencil({
   },
 });
 
-export const CSProp = () => {
+export default () => {
   return (
     <Card cs={myStencil()}>
       <Card.Heading

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "17.0.0-alpha.0605-next.0",
+  "version": "17.0.0-alpha.0613-next.0",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -47,10 +47,10 @@
     "@stackblitz/sdk": "^1.11.0",
     "@storybook/csf": "0.0.1",
     "@workday/canvas-expressive-icons-web": "1.0.2",
-    "@workday/canvas-kit-labs-react": "^17.0.0-alpha.0605-next.0",
-    "@workday/canvas-kit-preview-react": "^17.0.0-alpha.0605-next.0",
-    "@workday/canvas-kit-react": "^17.0.0-alpha.0605-next.0",
-    "@workday/canvas-kit-styling": "^17.0.0-alpha.0605-next.0",
+    "@workday/canvas-kit-labs-react": "^17.0.0-alpha.0613-next.0",
+    "@workday/canvas-kit-preview-react": "^17.0.0-alpha.0613-next.0",
+    "@workday/canvas-kit-react": "^17.0.0-alpha.0613-next.0",
+    "@workday/canvas-kit-styling": "^17.0.0-alpha.0613-next.0",
     "@workday/canvas-system-icons-web": "^5.0.3",
     "@workday/canvas-tokens-web": "^4.4.0",
     "markdown-to-jsx": "^7.2.0",
@@ -63,5 +63,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "58ce933e857e255360611f2330a230b167cead8d"
+  "gitHead": "11919e5ffbe1b947f0e5d156e1efc91dfeffd259"
 }