@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-buttongroup-docs.md

@@ -0,0 +1,980 @@
+ButtonGroup
+===========
+
+Overview
+--------
+
+ButtonGroup allows users to switch between two or more possible states. ButtonGroups are only used for actions that occur immediately after the user “flips the switch”.
+
+* * *
+
+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-buttongroup--button-children)
+
+Button group
+
+Option 1Option 2Option 3Option 4
+
+```
+
+<IressButtonGroup label\="Button group"\>
+  <IressButton\>
+    Option 1  </IressButton\>
+  <IressButton\>
+    Option 2  </IressButton\>
+  <IressButton\>
+    Option 3  </IressButton\>
+  <IressButton\>
+    Option 4  </IressButton\>
+</IressButtonGroup\>
+
+```
+
+Props
+-----
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+Content of the button group, usually multiple `IressButton`.
+
+ReactNode
+
+
+
+ | \- | \- |
+| defaultSelected | 
+
+Initially selected value, use for uncontrolled components.
+
+unknown
+
+
+
+ | \- | Set object |
+| hiddenLabel | 
+
+Hides the label if set; label will still be read out by screen readers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| label\* | 
+
+Sets the label text for the button group. If passed an element, it will render the element with an id, to ensure its connection to the button group.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Button group"
+
+ |
+| multiple | 
+
+Allows multiple buttons to be selected.
+
+TMultiple
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Called when a user activates one of its children buttons.
+
+(newValue?: ControlledValue<T, TMultiple>) => void
+
+ | \- | \- |
+| selected | 
+
+Selected value, use for controlled components.
+
+unknown
+
+
+
+ | \- | Set object |
+
+Usage
+-----
+
+Button Group requires some `label` text to describe what the group of buttons represent. The `label` text can be visually hidden (but still read by screenreaders) using the `hiddenLabel` prop.
+
+The `children` prop should contain multiple `IressButton` components.
+
+You can use the `onChange` prop to watch when a button is clicked.
+
+**Note:**
+
+*   The `options` props, originally used to map a set of strings to `IressButton`, has been deprecated. Instead, you can use array.map to map the options to `IressButton` in your own application.
+*   The `mode` prop on `IressButton` is not supported when used inside an `IressButtonGroup`.
+
+[](./iframe.html?id=components-buttongroup--button-children)
+
+Button group
+
+Option 1Option 2Option 3Option 4
+
+```
+
+<IressButtonGroup label\="Button group"\>
+  <IressButton\>
+    Option 1  </IressButton\>
+  <IressButton\>
+    Option 2  </IressButton\>
+  <IressButton\>
+    Option 3  </IressButton\>
+  <IressButton\>
+    Option 4  </IressButton\>
+</IressButtonGroup\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+Content of the button group, usually multiple `IressButton`.
+
+ReactNode
+
+
+
+ | \- | \- |
+| defaultSelected | 
+
+Initially selected value, use for uncontrolled components.
+
+unknown
+
+
+
+ | \- | Set object |
+| hiddenLabel | 
+
+Hides the label if set; label will still be read out by screen readers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| label\* | 
+
+Sets the label text for the button group. If passed an element, it will render the element with an id, to ensure its connection to the button group.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Button group"
+
+ |
+| multiple | 
+
+Allows multiple buttons to be selected.
+
+TMultiple
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Called when a user activates one of its children buttons.
+
+(newValue?: ControlledValue<T, TMultiple>) => void
+
+ | \- | \- |
+| selected | 
+
+Selected value, use for controlled components.
+
+unknown
+
+
+
+ | \- | Set object |
+
+Examples
+--------
+
+### Rich buttons
+
+By passing the buttons as children you have more control over the display of the button allowing you to use icons or tooltips.
+
+**Note:** In this case, please set the `value` prop on the `IressButton` component to ensure the correct value is used when the button is clicked.
+
+[](./iframe.html?id=components-buttongroup--rich-buttons)
+
+Text alignment
+
+Left
+
+Center
+
+Right
+
+* * *
+
+Justify
+
+```
+
+<IressButtonGroup label\="Text alignment"\>
+  <IressTooltip tooltipText\="Left"\>
+    <IressButton value\="left"\>
+      <IressIcon name\="align-left" />
+      <span className\="iress-sr-only"\>
+        Left      </span\>
+    </IressButton\>
+  </IressTooltip\>
+  <IressTooltip tooltipText\="Center"\>
+    <IressButton value\="center"\>
+      <IressIcon name\="align-center" />
+      <span className\="iress-sr-only"\>
+        Center      </span\>
+    </IressButton\>
+  </IressTooltip\>
+  <IressTooltip tooltipText\="Right"\>
+    <IressButton value\="right"\>
+      <IressIcon name\="align-right" />
+      <span className\="iress-sr-only"\>
+        Right      </span\>
+    </IressButton\>
+  </IressTooltip\>
+  <IressDivider
+    mx\="xs"
+    vertical
+  />
+  <IressTooltip tooltipText\="Justify"\>
+    <IressButton value\="justify"\>
+      <IressIcon name\="align-justify" />
+      <span className\="iress-sr-only"\>
+        Justify      </span\>
+    </IressButton\>
+  </IressTooltip\>
+</IressButtonGroup\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+Content of the button group, usually multiple `IressButton`.
+
+ReactNode
+
+
+
+ | \- | \- |
+| defaultSelected | 
+
+Initially selected value, use for uncontrolled components.
+
+unknown
+
+
+
+ | \- | Set object |
+| hiddenLabel | 
+
+Hides the label if set; label will still be read out by screen readers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| label\* | 
+
+Sets the label text for the button group. If passed an element, it will render the element with an id, to ensure its connection to the button group.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Text alignment"
+
+ |
+| multiple | 
+
+Allows multiple buttons to be selected.
+
+TMultiple
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Called when a user activates one of its children buttons.
+
+(newValue?: ControlledValue<T, TMultiple>) => void
+
+ | \- | \- |
+| selected | 
+
+Selected value, use for controlled components.
+
+unknown
+
+
+
+ | \- | Set object |
+
+### Multi-select
+
+By default, only one button in the group can be selected at a time. By setting the `multiple` prop, multiple buttons can be selected.
+
+[](./iframe.html?id=components-buttongroup--multi-select)
+
+Multiple options can be selected
+
+Option 1Option 2Option 3Option 4
+
+```
+
+<IressButtonGroup
+  label\="Multiple options can be selected"
+  multiple
+\>
+  <IressButton\>
+    Option 1  </IressButton\>
+  <IressButton\>
+    Option 2  </IressButton\>
+  <IressButton\>
+    Option 3  </IressButton\>
+  <IressButton\>
+    Option 4  </IressButton\>
+</IressButtonGroup\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+Content of the button group, usually multiple `IressButton`.
+
+ReactNode
+
+
+
+ | \- | \- |
+| defaultSelected | 
+
+Initially selected value, use for uncontrolled components.
+
+unknown
+
+
+
+ | \- | Set object |
+| hiddenLabel | 
+
+Hides the label if set; label will still be read out by screen readers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| label\* | 
+
+Sets the label text for the button group. If passed an element, it will render the element with an id, to ensure its connection to the button group.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Multiple options can be selected"
+
+ |
+| multiple | 
+
+Allows multiple buttons to be selected.
+
+TMultiple
+
+
+
+ | \- | 
+
+true
+
+ |
+| onChange | 
+
+Called when a user activates one of its children buttons.
+
+(newValue?: ControlledValue<T, TMultiple>) => void
+
+ | \- | \- |
+| selected | 
+
+Selected value, use for controlled components.
+
+unknown
+
+
+
+ | \- | Set object |
+
+### Pre-selecting buttons
+
+Buttons within the group can be pre-selected using the `defaultSelected` prop (for uncontrolled components), or the `selected` prop if you are planning to control the state yourself.
+
+If the button group is in its default single select mode, these props expects a string that matches the text of one of the buttons, or the `value` prop of the button if it has been set.
+
+In multi-select mode, these props expects an array of matching strings.
+
+[](./iframe.html?id=components-buttongroup--selected-single)
+
+Selected option for single select
+
+Option 1Option 2Option 3Option 4
+
+```
+
+<IressButtonGroup
+  defaultSelected\="Option 2"
+  label\="Selected option for single select"
+\>
+  <IressButton\>
+    Option 1  </IressButton\>
+  <IressButton\>
+    Option 2  </IressButton\>
+  <IressButton\>
+    Option 3  </IressButton\>
+  <IressButton\>
+    Option 4  </IressButton\>
+</IressButtonGroup\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+Content of the button group, usually multiple `IressButton`.
+
+ReactNode
+
+
+
+ | \- | \- |
+| defaultSelected | 
+
+Initially selected value, use for uncontrolled components.
+
+unknown
+
+
+
+ | \- | 
+
+"Option 2"
+
+ |
+| hiddenLabel | 
+
+Hides the label if set; label will still be read out by screen readers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| label\* | 
+
+Sets the label text for the button group. If passed an element, it will render the element with an id, to ensure its connection to the button group.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Selected option for single select"
+
+ |
+| multiple | 
+
+Allows multiple buttons to be selected.
+
+TMultiple
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Called when a user activates one of its children buttons.
+
+(newValue?: ControlledValue<T, TMultiple>) => void
+
+ | \- | \- |
+| selected | 
+
+Selected value, use for controlled components.
+
+unknown
+
+
+
+ | \- | Set object |
+
+[](./iframe.html?id=components-buttongroup--selected-multiple)
+
+Selected option for multi-select
+
+Option 1Option 2Option 3Option 4
+
+```
+
+<IressButtonGroup
+  defaultSelected\={\[
+    'Option 2',
+    'Option 4'
+  \]}
+  label\="Selected option for multi-select"
+  multiple
+\>
+  <IressButton\>
+    Option 1  </IressButton\>
+  <IressButton\>
+    Option 2  </IressButton\>
+  <IressButton\>
+    Option 3  </IressButton\>
+  <IressButton\>
+    Option 4  </IressButton\>
+</IressButtonGroup\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+Content of the button group, usually multiple `IressButton`.
+
+ReactNode
+
+
+
+ | \- | \- |
+| defaultSelected | 
+
+Initially selected value, use for uncontrolled components.
+
+unknown
+
+
+
+ | \- | 
+
+RAW
+
+*   defaultSelected :
+    
+    \[
+    
+    *   0 : "Option 2"
+    *   1 : "Option 4"
+    
+    \]
+    
+
+
+
+ |
+| hiddenLabel | 
+
+Hides the label if set; label will still be read out by screen readers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| label\* | 
+
+Sets the label text for the button group. If passed an element, it will render the element with an id, to ensure its connection to the button group.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Selected option for multi-select"
+
+ |
+| multiple | 
+
+Allows multiple buttons to be selected.
+
+TMultiple
+
+
+
+ | \- | 
+
+true
+
+ |
+| onChange | 
+
+Called when a user activates one of its children buttons.
+
+(newValue?: ControlledValue<T, TMultiple>) => void
+
+ | \- | \- |
+| selected | 
+
+Selected value, use for controlled components.
+
+unknown
+
+
+
+ | \- | Set object |
+
+### `onChange` event
+
+The Button Group emits an event when any of the selected buttons change. The event detail (`ButtonGroupChange`) consist of a string or an array of strings (depending on if it's in single or multi select mode) that represents the selected button(s).
+
+[](./iframe.html?id=components-buttongroup--on-change)
+
+Trigger toasts by selecting an option below
+
+Option 1Option 2Option 3Option 4
+
+```
+
+{
+  args: {
+    ...ButtonChildren.args,
+    label: 'Trigger toasts by selecting an option below'
+  },
+  render: args \=> {
+    const {
+      success
+    } \= useToaster();
+    return <IressButtonGroup {...args} onChange\={selected \=> {
+      success({
+        content: \`Selected: ${selected ? String(selected) : 'none'}\`
+      });
+    }} /\>;
+  },
+  decorators: \[Story \=> <IressToasterProvider\>
+        <Story />
+      </IressToasterProvider\>\]
+}
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+Content of the button group, usually multiple `IressButton`.
+
+ReactNode
+
+
+
+ | \- | \- |
+| defaultSelected | 
+
+Initially selected value, use for uncontrolled components.
+
+unknown
+
+
+
+ | \- | Set object |
+| hiddenLabel | 
+
+Hides the label if set; label will still be read out by screen readers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| label\* | 
+
+Sets the label text for the button group. If passed an element, it will render the element with an id, to ensure its connection to the button group.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Trigger toasts by selecting an option below"
+
+ |
+| multiple | 
+
+Allows multiple buttons to be selected.
+
+TMultiple
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Called when a user activates one of its children buttons.
+
+(newValue?: ControlledValue<T, TMultiple>) => void
+
+ | \- | \- |
+| selected | 
+
+Selected value, use for controlled components.
+
+unknown
+
+
+
+ | \- | Set object |
+
+### Hidden label
+
+If you would like to visually hide the label, you can use the `hiddenLabel` prop.
+
+[](./iframe.html?id=components-buttongroup--hidden-label)
+
+Button group
+
+Option 1Option 2Option 3Option 4
+
+```
+
+<IressButtonGroup
+  hiddenLabel
+  label\="Button group"
+\>
+  <IressButton\>
+    Option 1  </IressButton\>
+  <IressButton\>
+    Option 2  </IressButton\>
+  <IressButton\>
+    Option 3  </IressButton\>
+  <IressButton\>
+    Option 4  </IressButton\>
+</IressButtonGroup\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+Content of the button group, usually multiple `IressButton`.
+
+ReactNode
+
+
+
+ | \- | \- |
+| defaultSelected | 
+
+Initially selected value, use for uncontrolled components.
+
+unknown
+
+
+
+ | \- | Set object |
+| hiddenLabel | 
+
+Hides the label if set; label will still be read out by screen readers.
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| label\* | 
+
+Sets the label text for the button group. If passed an element, it will render the element with an id, to ensure its connection to the button group.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Button group"
+
+ |
+| multiple | 
+
+Allows multiple buttons to be selected.
+
+TMultiple
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Called when a user activates one of its children buttons.
+
+(newValue?: ControlledValue<T, TMultiple>) => void
+
+ | \- | \- |
+| selected | 
+
+Selected value, use for controlled components.
+
+unknown
+
+
+
+ | \- | Set object |
+
+### Headings as labels
+
+For semantic reasons, you may need the label to be rendered as a heading. In this case, you can pass the element directly to the `label` prop. The component will automatically add the `id` required to connect the button group to its label.
+
+[](./iframe.html?id=components-buttongroup--heading-label)
+
+Heading as label
+----------------
+
+Option 1Option 2Option 3Option 4
+
+```
+
+{
+  args: {
+    ...ButtonChildren.args,
+    label: <IressText element\="h2"\>Heading as label</IressText\>
+  }
+}
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+Content of the button group, usually multiple `IressButton`.
+
+ReactNode
+
+
+
+ | \- | \- |
+| defaultSelected | 
+
+Initially selected value, use for uncontrolled components.
+
+unknown
+
+
+
+ | \- | Set object |
+| hiddenLabel | 
+
+Hides the label if set; label will still be read out by screen readers.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| label\* | 
+
+Sets the label text for the button group. If passed an element, it will render the element with an id, to ensure its connection to the button group.
+
+ReactNode
+
+
+
+ | \- | 
+
+RAW
+
+label :
+
+{
+
+*   $$typeof : Symbol(react.transitional.element)
+*   type : ({ className, ...restProps }) => { \_s(); const Component = useMemo( () => styled(restProps.element ?? "div", text), \[restProps.element\] ); return /\* @\_\_PURE\_\_ \*/ jsxDEV( Component, { ...restProps, className: cx(className, GlobalCSSClass.Text) }, void 0, false, { fileName: "/home/runner/work/design-system/design-system/packages/components/src/components/Text/Text.tsx", lineNumber: 46, columnNumber: 5 }, this ); }
+*   key : null
+*   props :
+    
+    {...} 2 keys
+    
+*   \_owner : null
+*   \_store :
+    
+    {...} 0 keys
+    
+
+}
+
+
+
+
+
+
+
+ |
+| multiple | 
+
+Allows multiple buttons to be selected.
+
+TMultiple
+
+
+
+ | \- | Set object |
+| onChange | 
+
+Called when a user activates one of its children buttons.
+
+(newValue?: ControlledValue<T, TMultiple>) => void
+
+ | \- | \- |
+| selected | 
+
+Selected value, use for controlled components.
+
+unknown
+
+
+
+ | \- | Set object |