@iress-oss/ids-mcp-server 5.15.0 → 5.20.2

package/generated/docs/components_components-popover-recipes-docs.md

@@ -0,0 +1,491 @@
+Recipes
+=======
+
+With `IressMenu`
+----------------
+
+When an `IressMenu` is used inside `IressPopover`, it adds some additional functionality to the popover, including:
+
+*   `IressPopover` will automatically close the popover when a menu item is clicked.
+*   `IressMenu` will automatically focus the first menu item when the popover is opened.
+
+[](./iframe.html?id=components-popover-recipes--with-menu)
+
+role=menu
+
+### Application menu behaviour
+
+*   Once activated, focus is set to the first menu item
+*   Menu items can be navigated using the `up` and `down` arrow keys
+*   Popover will close when:
+    *   the `esc` key is pressed
+    *   the `tab` key is pressed (focus moves to the focusable element in the DOM)
+    *   a menu item is clicked
+
+role=list
+
+### Navigation/list menu behaviour
+
+*   Once activated, focus is set to the popover panel
+*   Menu items can be navigated using the `tab` key
+*   Popover will close when:
+    *   the `esc` key is pressed
+    *   the popover panel loses focus
+
+role=listbox
+
+Multi-select
+
+### Listbox menu behaviour
+
+*   Once activated, focus is set to the first menu item
+*   Menu items can be navigated using arrow keys
+*   Popover will close when:
+    *   the `esc` key is pressed
+    *   the `tab` key is pressed (focus moves to the next focusable element in the DOM)
+    *   a menu item is clicked (except when a listbox menu is in `multiSelect` mode)
+    *   When user presses the `up` key when the first item is focused
+
+role=nav
+
+### Navigation/list menu behaviour
+
+*   Once activated, focus is set to the popover panel
+*   Menu items can be navigated using the `tab` key
+*   Popover will close when:
+    *   the `esc` key is pressed
+    *   the popover panel loses focus
+
+Hide codedrawOpen in CodeSandbox
+
+{
+  args: {
+    menuChildren: 'selectable'
+  },
+  argTypes: {
+    ...disableArgTypes(\['activator', 'children', 'role', 'type'\])
+  },
+  render: ({
+    menuChildren,
+    ...args
+  }) \=> {
+    const \[multiSelect, setMultiSelect\] \= useState(false);
+    return <IressContainer className\="iress-u-stack iress--gutter--md"\>
+        {MENU\_ROLES.map(role \=> <IressRow gutter\={IressRow.Gutter.Lg} key\={role} verticalAlign\={IressRow.VerticalAlign.Middle}\>
+            <IressCol span\={IressCol.Span.Two}\>
+              <IressPopover {...args} activator\={<IressButton fluid\>role={role}</IressButton\>} container\={document.body} type\={role \=== 'listbox' || role \=== 'menu' ? role : undefined}\>
+                <IressMenu role\={role} defaultSelected\={3} multiSelect\={multiSelect && role \=== 'listbox'}\>
+                  {menuChildren}
+                </IressMenu\>
+              </IressPopover\>
+            </IressCol\>
+            <IressCol\>
+              <MenuInPopoverRoleDescription role\={role}\>
+                {role \=== 'listbox' && <IressToggle className\="iress-mb--md" checked\={multiSelect} onChange\={() \=> setMultiSelect(!multiSelect)}\>
+                    Multi-select                  </IressToggle\>}
+              </MenuInPopoverRoleDescription\>
+            </IressCol\>
+          </IressRow\>)}
+      </IressContainer\>;
+  }
+}
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| activator\* | 
+Content for an activator element, usually an `IressButton`.
+
+PopoverActivatorProps\['children'\]
+
+ | \- | \- |
+| align | 
+
+Sets the alignment of the popover relative to the activator element.
+
+union
+
+
+
+ | 
+
+'auto'
+
+ | Set object |
+| children | 
+
+The content to render within the popover.
+
+ReactReactNode
+
+
+
+ | \- | \- |
+| container | 
+
+The container element to render the popover into. By default, the popover will render where its parent is rendered.
+
+**Note:** If the `container` doesn’t exist when the popover is mounted, ensure you pass an element directly (not a ref) and specify null as the default value before it is set. This lets it wait for the root to be available. For example, if you reference the parent element of a popover.
+
+FloatingUIContainer
+
+
+
+ | \- | Set object |
+| contentClassName | 
+
+Class name of the popover content
+
+string
+
+
+
+ | \- | Set string |
+| defaultShow | 
+
+When set to `true` the popover will be visible by default. Use for uncontrolled popovers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| disabledAutoToggle | 
+
+When set to `true`, popover toggling can only be done through the toggle method on the `ref`.
+
+boolean
+
+<table class="css-ymgjf7"><tbody><tr><td colspan="2"><strong>Deprecated</strong>: Use a controlled `show` prop instead.</td></tr></tbody></table>
+
+ | \- | Set boolean |
+| displayMode | 
+
+Sets the display mode of popover.
+
+union
+
+
+
+ | 
+
+'overlay'
+
+ | Set object |
+| focusStartIndex | 
+
+Which index to start the focus on when the popover is opened. Only works with `type` listbox and menu. Note: The index must exist in the list of items, otherwise it will not work.
+
+number
+
+
+
+ | \- | Set number |
+| matchActivatorWidth | 
+
+Sets the popover to match the width of the activator. Note: This only works when `displayMode="overlay"`.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| menuChildren | 
+
+string
+
+
+
+ | \- | menuChildrenChoose option...nonebasiccomplexnavigationheadingsdividersslotsextraInformationselectable |
+| onActivated | 
+
+Is called when popover is activated.
+
+( e?: Event, reason?: OpenChangeReason, activeIndex?: number | null, ) => void
+
+ | \- | \- |
+| onDeactivated | 
+
+Is called when popover is deactivated.
+
+( e?: Event, reason?: OpenChangeReason, activeIndex?: number | null, ) => void
+
+ | \- | \- |
+| onNavigate | 
+
+Is called when registered popover items are navigated using arrow keys. Only works with `type` listbox and menu.
+
+(activeIndex: number | null) => void
+
+ | \- | \- |
+| role | 
+
+\-
+
+ | \- | \- |
+| show | 
+
+When set to `true` the modal will be visible. Use for controlled popovers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| type | 
+
+Describes the type of content contained in the popover.
+
+union
+
+
+
+ | \- | \- |
+| virtualFocus | 
+
+Whether the focus is virtual (using `aria-activedescendant`). Use this if you need focus to remain on the reference element (such as an input), but allow arrow keys to navigate items. Note: This is only applicable when type is set to: `listbox` or `menu`, and only works out of the box with `IressMenu` and its subcomponents.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| width | 
+
+Sets the width of the popover
+
+string
+
+<table class="css-ymgjf7"><tbody><tr><td colspan="2"><strong>Deprecated</strong>: use the `--iress-max-width` design token instead.</td></tr></tbody></table>
+
+ | \- | Set string |
+
+Focusable children
+------------------
+
+If you are using the `listbox` or `menu` type popovers, you will notice that focusable children (with the exception of `IressMenuItem`) are not automatically focusable with the arrow keys. To make them focusable, you will need to embed the focusable children using the `usePopoverItem` hook.
+
+The `usePopoverItem` hook will automatically handle the focus management for you. It has two optional arguments:
+
+*   The first argument is the typeahead label of the item you are registering. This will allow it to have a keyboard shortcut to focus the item.
+*   The second argument is a virtual node, which is used in `virtualFocus` enabled popovers and `IressInputPopover`, to mimic the `onKeyDown` and `onBlur` events of the original element when the item is virtually focused using `aria-activedescendant`. If not provided, nothing will happen when the element is virtually focused.
+
+The `usePopoverItem` hook returns an object with the following properties:
+
+*   `isActiveInPopover`: A boolean that indicates if the item is currently focused in the popover. This can be used to style the item differently when it is focused.
+*   `...popoverItemProps`: The rest of the props that you should spread on the focusable element to make it focusable.
+
+[](./iframe.html?id=components-popover-recipes--focusable-children)
+
+Toggle
+
+Hide codedrawOpen in CodeSandbox
+
+import { useState } from 'react';
+import {
+  ButtonCssClass,
+  IressButton,
+  IressPopover,
+  usePopoverItem,
+} from '@/main';
+const CountButton \= () \=> {
+  const \[count, setCount\] \= useState(0);
+  const { isActiveInPopover, ...popoverItemProps } \= usePopoverItem('Count', {
+    onKeyDown: (e) \=> {
+      if (e.key \=== '+') {
+        setCount(count + 1);
+      }
+    },
+  });
+  const className \= isActiveInPopover ? ButtonCssClass.Active : '';
+  return (
+    <IressButton
+      {...popoverItemProps}
+      className\={className}
+      mode\="tertiary"
+      fluid
+    \>
+      Increase count using the + key: {count}
+    </IressButton\>
+  );
+};
+export const UsePopoverExample \= () \=> (
+  <IressPopover
+    activator\={<IressButton\>Toggle</IressButton\>}
+    container\={document.body}
+    type\="listbox"
+    virtualFocus
+  \>
+    <CountButton />
+    <CountButton />
+  </IressPopover\>
+);
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| activator\* | 
+Content for an activator element, usually an `IressButton`.
+
+PopoverActivatorProps\['children'\]
+
+ | \- | Set object |
+| align | 
+
+Sets the alignment of the popover relative to the activator element.
+
+union
+
+
+
+ | 
+
+'auto'
+
+ | Set object |
+| children | 
+
+The content to render within the popover.
+
+ReactReactNode
+
+
+
+ | \- | \- |
+| container | 
+
+The container element to render the popover into. By default, the popover will render where its parent is rendered.
+
+**Note:** If the `container` doesn’t exist when the popover is mounted, ensure you pass an element directly (not a ref) and specify null as the default value before it is set. This lets it wait for the root to be available. For example, if you reference the parent element of a popover.
+
+FloatingUIContainer
+
+
+
+ | \- | Set object |
+| contentClassName | 
+
+Class name of the popover content
+
+string
+
+
+
+ | \- | Set string |
+| defaultShow | 
+
+When set to `true` the popover will be visible by default. Use for uncontrolled popovers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| disabledAutoToggle | 
+
+When set to `true`, popover toggling can only be done through the toggle method on the `ref`.
+
+boolean
+
+<table class="css-ymgjf7"><tbody><tr><td colspan="2"><strong>Deprecated</strong>: Use a controlled `show` prop instead.</td></tr></tbody></table>
+
+ | \- | Set boolean |
+| displayMode | 
+
+Sets the display mode of popover.
+
+union
+
+
+
+ | 
+
+'overlay'
+
+ | Set object |
+| focusStartIndex | 
+
+Which index to start the focus on when the popover is opened. Only works with `type` listbox and menu. Note: The index must exist in the list of items, otherwise it will not work.
+
+number
+
+
+
+ | \- | Set number |
+| matchActivatorWidth | 
+
+Sets the popover to match the width of the activator. Note: This only works when `displayMode="overlay"`.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| menuChildren | 
+
+\-
+
+ | \- | menuChildrenChoose option...nonebasiccomplexnavigationheadingsdividersslotsextraInformationselectable |
+| onActivated | 
+
+Is called when popover is activated.
+
+( e?: Event, reason?: OpenChangeReason, activeIndex?: number | null, ) => void
+
+ | \- | \- |
+| onDeactivated | 
+
+Is called when popover is deactivated.
+
+( e?: Event, reason?: OpenChangeReason, activeIndex?: number | null, ) => void
+
+ | \- | \- |
+| onNavigate | 
+
+Is called when registered popover items are navigated using arrow keys. Only works with `type` listbox and menu.
+
+(activeIndex: number | null) => void
+
+ | \- | \- |
+| show | 
+
+When set to `true` the modal will be visible. Use for controlled popovers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| type | 
+
+Describes the type of content contained in the popover.
+
+union
+
+
+
+ | \- | Set object |
+| virtualFocus | 
+
+Whether the focus is virtual (using `aria-activedescendant`). Use this if you need focus to remain on the reference element (such as an input), but allow arrow keys to navigate items. Note: This is only applicable when type is set to: `listbox` or `menu`, and only works out of the box with `IressMenu` and its subcomponents.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| width | 
+
+Sets the width of the popover
+
+string
+
+<table class="css-ymgjf7"><tbody><tr><td colspan="2"><strong>Deprecated</strong>: use the `--iress-max-width` design token instead.</td></tr></tbody></table>
+
+ | \- | Set string |

package/generated/docs/components_components-progress-docs.md

@@ -0,0 +1,115 @@
+Progress
+========
+
+Overview
+--------
+
+A progress component is used to indicate to a user the completion of a set of tasks or a process.
+
+[](./iframe.html?id=components-progress--default)
+
+Hide codedrawOpen in CodeSandbox
+
+{
+  args: {
+    min: 10,
+    max: 30,
+    value: 20
+  }
+}
+
+```
+
+Props
+-----
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| max | 
+The maximum value of the progress indicator.
+
+number
+
+
+
+ | 
+
+100
+
+ |  |
+| min | 
+
+The minimum value of the progress indicator.
+
+number
+
+
+
+ | 
+
+0
+
+ |  |
+| sectionTitle | 
+
+The text that is announced by the screen reader. Should contain a description of the section the progress is being measured for. You can use {{current}} and {{max}} as string replacers for the current value and maximum value respectively..
+
+string
+
+
+
+ | 'Progress is {{current}} of {{max}}' | Set string |
+| value | 
+
+The current value of the progress indicator.
+
+number
+
+
+
+ | 
+
+0
+
+ |  |
+
+Usage
+-----
+
+Progress shows how far through a task or operation you are in a graphical way. The simplest way to use it to set the `value` to specify how much of the task the user has completed, relative to the `max` value (which defaults to 100).
+
+### Calculation to convert value in to width
+
+The following calculation is used to derive the width percentage:
+
+Math.round(
+    ((this.value - this.min) / (this.max - this.min)) \* 100,
+)
+
+```
+
+This caters for those scenarios where the `min` or `max` values change.
+
+### Boundary limits
+
+There is a danger that the value can exceed the boundaries set in the `min` and `max` values, and cause the percentage width of the bar to overflow the indicator. To prevent this the following rules are applied:
+
+*   If the `value` is less than the `min` prop, it is reset to the `min` prop;
+*   If the `value` is more than the `max` prop, it is reset to the `max` prop;
+
+### Section Title
+
+The `section-title` prop is used by assistive technologies and allows you to tailor the message announced when the progress component is selected. This could be to add extra context about where the user is in a process or section with a multi-part form.
+
+### Use of tokens
+
+The message supports the use of two tokens within the announcement, which are replaced when the component is rendered. They are:
+
+*   `{{current}}` - replaced with the `value`;
+*   `{{max}}` - replaced with the maximum limit;
+
+For example, if the component has been implemented with a max of 10, a value of 6 has been set, and the default section title, the screen reader will announce:
+
+Step 6 of 10
+
+```

package/generated/docs/{components-provider-docs.md → components_components-provider-docs.md}

@@ -1,16 +1,16 @@
-[](#provider)Provider
-=====================
+Provider
+========
 
 Overview
 --------
 
 Provider is a component that sets up the Iress Design System for your application. It ensures that the design system is correctly configured and ready to use.
 
-Show modalShow slideoutShow toast
+[](./iframe.html?id=components-provider--provider)
 
-Hide code
+Show modalShow slideoutShow toast
 
-\[data-radix-scroll-area-viewport\] { scrollbar-width: none; -ms-overflow-style: none; -webkit-overflow-scrolling: touch; } \[data-radix-scroll-area-viewport\]::-webkit-scrollbar { display: none; } :where(\[data-radix-scroll-area-viewport\]) { display: flex; flex-direction: column; align-items: stretch; } :where(\[data-radix-scroll-area-content\]) { flex-grow: 1; }
+Hide codedrawOpen in CodeSandbox
 
 import {
   IressButton,
@@ -23,7 +23,7 @@ import {
   useModal,
   useSlideout,
   useToaster,
-} from '@iress-oss/ids-components';
+} from '@/main';
 const Page \= () \=> {
   const { showModal } \= useModal();
   const { showSlideout } \= useSlideout();
@@ -59,10 +59,42 @@ export const AppWithProvider \= () \=> (
   </IressProvider\>
 );
 
-Copy
+```
+
+Props
+-----
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+The contents of your application, and/or the components which will be calling slideouts, modals and toasts.
+
+ReactNode
+
+
+
+ | \- | \- |
+| container | 
+
+Container to render modal, slideouts and toasts into. If not provided, will render into the body of the document.
+
+FloatingUIContainer
+
 
-[](#usage)Usage
----------------
+
+ | \- | \- |
+| noIcons | 
+
+If you don't want to load the Iress Icon CSS from the CDN, set this to true.
+
+boolean
+
+
+
+ | \- | \- |
+
+Usage
+-----
 
 The design system provider automates some set-up tasks for you, including:
 
@@ -71,23 +103,6 @@ The design system provider automates some set-up tasks for you, including:
 
 In most cases, you should wrap the entire application with the `IressProvider` component. This will ensure that the design system is set up correctly and consistently across the application.
 
-\[data-radix-scroll-area-viewport\] {
-  scrollbar-width: none;
-  -ms-overflow-style: none;
-  -webkit-overflow-scrolling: touch;
-}
-\[data-radix-scroll-area-viewport\]::-webkit-scrollbar {
-  display: none;
-}
-:where(\[data-radix-scroll-area-viewport\]) {
-  display: flex;
-  flex-direction: column;
-  align-items: stretch;
-}
-:where(\[data-radix-scroll-area-content\]) {
-  flex-grow: 1;
-}
-
 import { IressProvider } from '@iress-oss/ids-components';
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <IressProvider\>
@@ -96,10 +111,4 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
   </IressProvider\>,
 );
 
-Copy
-
-On this page
-
-*   [Overview](#overview)
-*   [Props](#props)
-*   [Usage](#usage)
+```