@iress-oss/ids-mcp-server 6.0.0-alpha.1-canary-20251204032753-fe18cab → 6.0.0-alpha.1-canary-20251204040305-3639454

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

@@ -0,0 +1,537 @@
+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=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=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
+
+```
+
+<IressStack
+  gap\="md"
+  maxWidth\="container.lg"
+  mx\="auto"
+  px\="lg"
+\>
+  <IressRow
+    gutter\="lg"
+    verticalAlign\="middle"
+  \>
+    <IressCol span\={2}\>
+      <IressPopover
+        activator\={<IressButton fluid\>role=listbox</IressButton\>}
+        container\={document.body}
+        type\="listbox"
+      \>
+        <IressMenu
+          defaultSelected\={3}
+          role\="listbox"
+        \>
+          <IressMenuItem value\={0}\>
+            New task          </IressMenuItem\>
+          <IressMenuItem value\={1}\>
+            Send prospect welcome pack          </IressMenuItem\>
+          <IressMenuItem value\={2}\>
+            Book in Discovery meeting          </IressMenuItem\>
+          <IressMenuItem value\={3}\>
+            Prospect proceeding          </IressMenuItem\>
+        </IressMenu\>
+      </IressPopover\>
+    </IressCol\>
+    <IressCol\>
+      <MenuInPopoverRoleDescription role\="listbox"\>
+        <IressToggle
+          mb\="md"
+          onChange\={() \=> {}}
+        \>
+          Multi-select        </IressToggle\>
+      </MenuInPopoverRoleDescription\>
+    </IressCol\>
+  </IressRow\>
+  <IressRow
+    gutter\="lg"
+    verticalAlign\="middle"
+  \>
+    <IressCol span\={2}\>
+      <IressPopover
+        activator\={<IressButton fluid\>role=menu</IressButton\>}
+        container\={document.body}
+        type\="menu"
+      \>
+        <IressMenu
+          defaultSelected\={3}
+          role\="menu"
+        \>
+          <IressMenuItem value\={0}\>
+            New task          </IressMenuItem\>
+          <IressMenuItem value\={1}\>
+            Send prospect welcome pack          </IressMenuItem\>
+          <IressMenuItem value\={2}\>
+            Book in Discovery meeting          </IressMenuItem\>
+          <IressMenuItem value\={3}\>
+            Prospect proceeding          </IressMenuItem\>
+        </IressMenu\>
+      </IressPopover\>
+    </IressCol\>
+    <IressCol\>
+      <MenuInPopoverRoleDescription role\="menu" />
+    </IressCol\>
+  </IressRow\>
+  <IressRow
+    gutter\="lg"
+    verticalAlign\="middle"
+  \>
+    <IressCol span\={2}\>
+      <IressPopover
+        activator\={<IressButton fluid\>role=list</IressButton\>}
+        container\={document.body}
+      \>
+        <IressMenu
+          defaultSelected\={3}
+          role\="list"
+        \>
+          <IressMenuItem value\={0}\>
+            New task          </IressMenuItem\>
+          <IressMenuItem value\={1}\>
+            Send prospect welcome pack          </IressMenuItem\>
+          <IressMenuItem value\={2}\>
+            Book in Discovery meeting          </IressMenuItem\>
+          <IressMenuItem value\={3}\>
+            Prospect proceeding          </IressMenuItem\>
+        </IressMenu\>
+      </IressPopover\>
+    </IressCol\>
+    <IressCol\>
+      <MenuInPopoverRoleDescription role\="list" />
+    </IressCol\>
+  </IressRow\>
+</IressStack\>
+
+```
+
+#### 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.
+
+FloatingUIAligns
+
+
+
+ | 
+
+'auto'
+
+ | Set object |
+| children | 
+
+The content to render within the popover.
+
+ReactNode
+
+
+
+ | \- | \- |
+| 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
+
+<table class="css-3nr4py"><tbody><tr><td colspan="2"><strong>Deprecated</strong>: Use `contentStyle` instead.</td></tr></tbody></table>
+
+ | \- | Set string |
+| contentStyle | 
+
+This allows you to customise the content styling specifically, which is the floating element. It accepts an object with any of the styling properties available on `IressCSSProps`, as well as `className` and `style`.
+
+IressCustomiseSlot
+
+
+
+ | \- | Set object |
+| defaultShow | 
+
+When set to `true` the popover will be visible by default. Use for uncontrolled popovers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| displayMode | 
+
+Sets the display mode of popover.
+
+DisplayModes
+
+
+
+ | 
+
+'overlay'
+
+ | Set object |
+| fluid | 
+
+Popovers can be fluid, meaning they will take up the full width of their container.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| 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
+
+
+
+ | \- | Choose 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.
+
+PopoverHookReturn\['type'\]
+
+ | \- | \- |
+| 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 |
+
+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
+
+```
+
+const CountButton \= () \=> {
+  const \[count, setCount\] \= useState(0);
+  const { isActiveInPopover, ...popoverItemProps } \= usePopoverItem('Count', {
+    onKeyDown: (e) \=> {
+      if (e.key \=== '+') {
+        setCount(count + 1);
+      }
+    },
+  });
+  return (
+    <IressButton
+      {...popoverItemProps}
+      active\={isActiveInPopover}
+      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.
+
+FloatingUIAligns
+
+
+
+ | 
+
+'auto'
+
+ | Set object |
+| children | 
+
+The content to render within the popover.
+
+ReactNode
+
+
+
+ | \- | \- |
+| 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
+
+<table class="css-3nr4py"><tbody><tr><td colspan="2"><strong>Deprecated</strong>: Use `contentStyle` instead.</td></tr></tbody></table>
+
+ | \- | Set string |
+| contentStyle | 
+
+This allows you to customise the content styling specifically, which is the floating element. It accepts an object with any of the styling properties available on `IressCSSProps`, as well as `className` and `style`.
+
+IressCustomiseSlot
+
+
+
+ | \- | Set object |
+| defaultShow | 
+
+When set to `true` the popover will be visible by default. Use for uncontrolled popovers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| displayMode | 
+
+Sets the display mode of popover.
+
+DisplayModes
+
+
+
+ | 
+
+'overlay'
+
+ | Set object |
+| fluid | 
+
+Popovers can be fluid, meaning they will take up the full width of their container.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| 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 | 
+
+\-
+
+ | \- | Choose 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.
+
+PopoverHookReturn\['type'\]
+
+ | \- | 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 |

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

@@ -0,0 +1,128 @@
+Progress
+========
+
+Overview
+--------
+
+A progress component is used to indicate to a user the completion of a set of tasks or a process.
+
+* * *
+
+Updated
+
+**Recently updated**
+
+This component has been recently updated with new props. The props have been marked as beta. Please tell us if there are any issues.
+
+[](./iframe.html?id=components-progress--default)
+
+```
+
+<IressProgress
+  max\={30}
+  min\={10}
+  value\={20}
+/>
+
+```
+
+Props
+-----
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| borderRadius | 
+The **`border-radius`** CSS property rounds the corners of an element's outer border edge using the radius tokens in the design system.
+
+UtilityValues\['borderRadius'\]
+
+ | \- | Set object |
+| max | 
+
+The maximum value of the progress indicator.
+
+number
+
+
+
+ | 
+
+100
+
+ |  |
+| min | 
+
+The minimum value of the progress indicator. If `min` is set, the progress indicator will render as a `<meter />` element instead of a `<progress />` element, thereby changing its role to `meter` instead of `progressbar`.
+
+TMin
+
+
+
+ | \- | 
+
+10
+
+ |
+| 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
+
+```