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

@@ -0,0 +1,513 @@
+Toggle
+======
+
+Overview
+--------
+
+Toggles allow users to turn things on or off. When toggled, the associated change happens straight away.
+
+* * *
+
+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-toggle--default)
+
+Toggle
+
+```
+
+<IressToggle
+  layout\="inline"
+\>
+  Toggle
+</IressToggle\>
+
+```
+
+Props
+-----
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the toggle on. Please use this when are rendering the toggle in controlled mode, meaning it will not change unless you explicitly set the value using `onChange` and `checked`.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| children\* | 
+
+Provides the label for the Toggle.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Toggle"
+
+ |
+| defaultChecked | 
+
+If true, the toggle will be initially rendered as off. Please use this when are rendering the toggle in uncontrolled mode, meaning the value will change automatically when the user interacts with the toggle.
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| hiddenLabel | 
+
+Hides the label if true (label will still be read out by screen readers).
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| layout | 
+
+Determines the layout of the label with respect to the control.
+
+union
+
+
+
+ | 
+
+'inline'
+
+ | 
+
+inlineinline-betweeninline-reversestack
+
+ |
+| onChange | 
+
+Emitted when the checked state changes.
+
+(checked: boolean, event: MouseEvent<HTMLButtonElement>) => void
+
+ | \- | \- |
+
+Usage
+-----
+
+Toggles are typically on / off switches, similar to a household light switch. They allow users to choose between two mutually exclusive options, and will always have a default value.
+
+The `IressToggle` component should only be used for actions that happen immediately, for example switching a device's WiFi connection on or off.
+
+Don't use Toggles in forms
+--------------------------
+
+Toggles shouldn’t be used as part of a form as they don’t have the correct semantics, and won’t submit a value when the form data is submitted. If you need a toggleable component in a form, use a checkbox or radio group instead.
+
+### Labels
+
+Toggles should always have a label, which is set via its `children`.
+
+[](./iframe.html?id=components-toggle--default)
+
+Toggle
+
+```
+
+<IressToggle
+  layout\="inline"
+\>
+  Toggle
+</IressToggle\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the toggle on. Please use this when are rendering the toggle in controlled mode, meaning it will not change unless you explicitly set the value using `onChange` and `checked`.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| children\* | 
+
+Provides the label for the Toggle.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Toggle"
+
+ |
+| defaultChecked | 
+
+If true, the toggle will be initially rendered as off. Please use this when are rendering the toggle in uncontrolled mode, meaning the value will change automatically when the user interacts with the toggle.
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| hiddenLabel | 
+
+Hides the label if true (label will still be read out by screen readers).
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| layout | 
+
+Determines the layout of the label with respect to the control.
+
+union
+
+
+
+ | 
+
+'inline'
+
+ | 
+
+inlineinline-betweeninline-reversestack
+
+ |
+| onChange | 
+
+Emitted when the checked state changes.
+
+(checked: boolean, event: MouseEvent<HTMLButtonElement>) => void
+
+ | \- | \- |
+
+### Hidden labels
+
+Labels can be hidden via the `hiddenLabel` prop; this will hide the label from view, but it'll still be available to screen reader users.
+
+[](./iframe.html?id=components-toggle--hidden-label)
+
+Toggle
+
+```
+
+<IressToggle
+  hiddenLabel
+  layout\="inline"
+\>
+  Toggle
+</IressToggle\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the toggle on. Please use this when are rendering the toggle in controlled mode, meaning it will not change unless you explicitly set the value using `onChange` and `checked`.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| children\* | 
+
+Provides the label for the Toggle.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Toggle"
+
+ |
+| defaultChecked | 
+
+If true, the toggle will be initially rendered as off. Please use this when are rendering the toggle in uncontrolled mode, meaning the value will change automatically when the user interacts with the toggle.
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| hiddenLabel | 
+
+Hides the label if true (label will still be read out by screen readers).
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| layout | 
+
+Determines the layout of the label with respect to the control.
+
+union
+
+
+
+ | 
+
+'inline'
+
+ | 
+
+inlineinline-betweeninline-reversestack
+
+ |
+| onChange | 
+
+Emitted when the checked state changes.
+
+(checked: boolean, event: MouseEvent<HTMLButtonElement>) => void
+
+ | \- | \- |
+
+### Checked
+
+The on / off state of the toggle can be controlled by setting the `checked` prop (for controlled components). If you want an uncontrolled component, you can set the `defaultChecked` prop instead to set it checked by default.
+
+[](./iframe.html?id=components-toggle--checked)
+
+Controlled Toggle
+
+```
+
+import { IressToggle, type IressToggleProps } from '@iress-oss/ids-components';
+import { useState } from 'react';
+export const ControlledToggle \= (props: IressToggleProps) \=> {
+  const \[isChecked, setIsChecked\] \= useState(true);
+  return (
+    <IressToggle
+      {...props}
+      checked\={isChecked}
+      onChange\={() \=> setIsChecked(!isChecked)}
+    \>
+      Controlled Toggle    </IressToggle\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the toggle on. Please use this when are rendering the toggle in controlled mode, meaning it will not change unless you explicitly set the value using `onChange` and `checked`.
+
+boolean
+
+
+
+ | \- | \- |
+| children\* | 
+
+Provides the label for the Toggle.
+
+ReactNode
+
+
+
+ | \- | 
+
+"Toggle"
+
+ |
+| defaultChecked | 
+
+If true, the toggle will be initially rendered as off. Please use this when are rendering the toggle in uncontrolled mode, meaning the value will change automatically when the user interacts with the toggle.
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| hiddenLabel | 
+
+Hides the label if true (label will still be read out by screen readers).
+
+boolean
+
+
+
+ | \- | FalseTrue |
+| layout | 
+
+Determines the layout of the label with respect to the control.
+
+union
+
+
+
+ | 
+
+'inline'
+
+ | 
+
+inlineinline-betweeninline-reversestack
+
+ |
+| onChange | 
+
+Emitted when the checked state changes.
+
+(checked: boolean, event: MouseEvent<HTMLButtonElement>) => void
+
+ | \- | \- |
+
+### Layout
+
+The `layout` prop allows you to control the position of the label in relation to the control. The default layout is `inline`, but you can also choose the following options:',
+
+*   `inline-between` similar to inline, but this positions the label and control at opposite ends of their container
+*   `inline-reverse` renders the label after the control instead of before the control
+*   `stack` positions the label above the control
+
+[](./iframe.html?id=components-toggle--layout)
+
+### inline
+
+Toggle
+
+### inline-between
+
+Toggle
+
+### inline-reverse
+
+Toggle
+
+### stack
+
+Toggle
+
+```
+
+<IressStack gap\="lg"\>
+  <IressText\>
+    <h3\>
+      inline    </h3\>
+    <IressPanel bg\="alt"\>
+      <IressToggle layout\="inline"\>
+        Toggle      </IressToggle\>
+    </IressPanel\>
+  </IressText\>
+  <IressText\>
+    <h3\>
+      inline-between    </h3\>
+    <IressPanel bg\="alt"\>
+      <IressToggle
+        checked
+        layout\="inline-between"
+      \>
+        Toggle      </IressToggle\>
+    </IressPanel\>
+  </IressText\>
+  <IressText\>
+    <h3\>
+      inline-reverse    </h3\>
+    <IressPanel bg\="alt"\>
+      <IressToggle layout\="inline-reverse"\>
+        Toggle      </IressToggle\>
+    </IressPanel\>
+  </IressText\>
+  <IressText\>
+    <h3\>
+      stack    </h3\>
+    <IressPanel bg\="alt"\>
+      <IressToggle
+        checked
+        layout\="stack"
+      \>
+        Toggle      </IressToggle\>
+    </IressPanel\>
+  </IressText\>
+</IressStack\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| checked | 
+If true, the toggle on. Please use this when are rendering the toggle in controlled mode, meaning it will not change unless you explicitly set the value using `onChange` and `checked`.
+
+boolean
+
+
+
+ | \- | \- |
+| children\* | 
+
+Provides the label for the Toggle.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| defaultChecked | 
+
+If true, the toggle will be initially rendered as off. Please use this when are rendering the toggle in uncontrolled mode, meaning the value will change automatically when the user interacts with the toggle.
+
+boolean
+
+
+
+ | \- | Set boolean |
+| hiddenLabel | 
+
+Hides the label if true (label will still be read out by screen readers).
+
+boolean
+
+
+
+ | \- | \- |
+| label | 
+
+\-
+
+ | \- | \- |
+| layout | 
+
+Determines the layout of the label with respect to the control.
+
+union
+
+
+
+ | 
+
+'inline'
+
+ | \- |
+| onChange | 
+
+Emitted when the checked state changes.
+
+(checked: boolean, event: MouseEvent<HTMLButtonElement>) => void
+
+ | \- | \- |