website: Update checkbox documentation & demos

apps/website/src/examples/Checkbox.indeterminate.tsx

@@ -0,0 +1,58 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Checkbox, Flex } from '@itwin/itwinui-react';
+
+export default () => {
+  const [option1, setOption1] = React.useState(false);
+  const [option2, setOption2] = React.useState(true);
+  const [allOptions, setAllOptions] = React.useState(false);
+  const isIndeterminate = !(option1 && option2) && (option1 || option2);
+
+  React.useEffect(() => {
+    if (option1 && option2) {
+      setAllOptions(true);
+      return;
+    }
+    if (option1 || option2) {
+      setAllOptions(false);
+    } else {
+      setAllOptions(false);
+    }
+  }, [option1, option2]);
+
+  const onAllChange = (value: boolean) => {
+    setAllOptions(value);
+    setOption1(value);
+    setOption2(value);
+  };
+
+  return (
+    <Flex flexDirection='column' alignItems='flex-start'>
+      <Checkbox
+        label='Option 1'
+        onChange={(event) => onAllChange(event.target.checked)}
+        indeterminate={isIndeterminate}
+        checked={allOptions}
+      />
+      <Flex
+        flexDirection='column'
+        alignItems='flex-start'
+        style={{ marginLeft: 'var(--iui-size-l)' }}
+      >
+        <Checkbox
+          label='Option 1.1'
+          checked={option1}
+          onChange={(event) => setOption1(event.target.checked)}
+        />
+        <Checkbox
+          label='Option 1.2'
+          checked={option2}
+          onChange={(event) => setOption2(event.target.checked)}
+        />
+      </Flex>
+    </Flex>
+  );
+};

apps/website/src/examples/Checkbox.inputgroup.tsx

@@ -0,0 +1,17 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Checkbox, InputGroup } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <InputGroup label='What are your hobbies?'>
+      <Checkbox label='Sports' defaultChecked />
+      <Checkbox label='Writing' />
+      <Checkbox label='Cooking' />
+      <Checkbox label='Arts and crafts' />
+    </InputGroup>
+  );
+};

apps/website/src/examples/Checkbox.loading.tsx

@@ -0,0 +1,16 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Checkbox, Flex } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Flex flexDirection='column' alignItems='flex-start'>
+      <Checkbox label='Enable 2D mode' defaultChecked />
+      <Checkbox label='Enable 3D mode' isLoading />
+      <Checkbox label='Enable 4D mode' disabled />
+    </Flex>
+  );
+};

apps/website/src/examples/Checkbox.main.tsx

@@ -3,14 +3,15 @@
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 import * as React from 'react';
-import { Checkbox } from '@itwin/itwinui-react';
+import { Checkbox, Flex } from '@itwin/itwinui-react';
 
 export default () => {
   return (
-    <>
-      <Checkbox label='Basic' />
-      <Checkbox label='Disabled' disabled />
-      <Checkbox label='Loading' isLoading />
-    </>
+    <Flex flexDirection='column' alignItems='flex-start'>
+      <Checkbox label='Option 1' defaultChecked />
+      <Checkbox label='Option 2' />
+      <Checkbox label='Option 3' defaultChecked disabled />
+      <Checkbox label='Option 4' disabled />
+    </Flex>
   );
 };

apps/website/src/examples/Checkbox.statuses.tsx

@@ -0,0 +1,17 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Checkbox, Flex } from '@itwin/itwinui-react';
+
+export default () => {
+  return (
+    <Flex flexDirection='column' alignItems='flex-start'>
+      <Checkbox label='Default' />
+      <Checkbox label='Positive' status='positive' />
+      <Checkbox label='Warning' status='warning' />
+      <Checkbox label='Negative' status='negative' />
+    </Flex>
+  );
+};

apps/website/src/examples/Checkbox.visibility.tsx

@@ -0,0 +1,61 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+ * See LICENSE.md in the project root for license terms and full copyright notice.
+ *--------------------------------------------------------------------------------------------*/
+import * as React from 'react';
+import { Checkbox, Flex } from '@itwin/itwinui-react';
+
+export default () => {
+  const [option1, setOption1] = React.useState(false);
+  const [option2, setOption2] = React.useState(true);
+  const [allOptions, setAllOptions] = React.useState(false);
+  const isIndeterminate = !(option1 && option2) && (option1 || option2);
+
+  React.useEffect(() => {
+    if (option1 && option2) {
+      setAllOptions(true);
+      return;
+    }
+    if (option1 || option2) {
+      setAllOptions(false);
+    } else {
+      setAllOptions(false);
+    }
+  }, [option1, option2]);
+
+  const onAllChange = (value: boolean) => {
+    setAllOptions(value);
+    setOption1(value);
+    setOption2(value);
+  };
+
+  return (
+    <Flex flexDirection='column' alignItems='flex-start'>
+      <Checkbox
+        label='Option 1'
+        onChange={(event) => onAllChange(event.target.checked)}
+        indeterminate={isIndeterminate}
+        checked={allOptions}
+        variant='eyeball'
+      />
+      <Flex
+        flexDirection='column'
+        alignItems='flex-start'
+        style={{ marginLeft: 'var(--iui-size-l)' }}
+      >
+        <Checkbox
+          label='Option 1.1'
+          checked={option1}
+          onChange={(event) => setOption1(event.target.checked)}
+          variant='eyeball'
+        />
+        <Checkbox
+          label='Option 1.2'
+          checked={option2}
+          onChange={(event) => setOption2(event.target.checked)}
+          variant='eyeball'
+        />
+      </Flex>
+    </Flex>
+  );
+};

apps/website/src/examples/index.tsx

@@ -48,6 +48,11 @@ export { default as ButtonGroupMainExample } from './ButtonGroup.main';
 export { default as CarouselMainExample } from './Carousel.main';
 
 export { default as CheckboxMainExample } from './Checkbox.main';
+export { default as CheckboxIndeterminateExample } from './Checkbox.indeterminate';
+export { default as CheckboxLoadingExample } from './Checkbox.loading';
+export { default as CheckboxStatusesExample } from './Checkbox.statuses';
+export { default as CheckboxVisibilityExample } from './Checkbox.visibility';
+export { default as CheckboxInputGroupExample } from './Checkbox.inputgroup';
 
 export { default as CodeMainExample } from './Code.main';
 

apps/website/src/pages/docs/checkbox.mdx

@@ -9,22 +9,71 @@ group: inputs
 
 import PropsTable from '~/components/PropsTable.astro';
 import LiveExample from '~/components/LiveExample.astro';
-import Placeholder from '~/components/Placeholder.astro';
 import * as AllExamples from '~/examples';
 
 <p>{frontmatter.description}</p>
 
-<Placeholder componentPageName='input-checkbox' />
-
 <LiveExample src='Checkbox.main.tsx' truncate={false}>
   <AllExamples.CheckboxMainExample client:load />
 </LiveExample>
 
-A checkbox (or tickbox) is a form component allowing multiple options selection. It serves a similar purpose than the radio button, the main difference being that radio buttons only permits binary option selection.
+A checkbox is a form component, typically accompanied with a label, allowing for the selection of multiple items. A checkbox can be used for selecting one or more options within a list, or to enable / disable / show / hide a feature within the user interface.
+
+A checkbox should not be confused with a [toggle switch](toggleswitch), which has a similar role but is not appropriate in all scenarios. To learn more about when to use a toggle switch or a checkbox, please read [Checkbox vs Toggle Switch by Saadia Minhas](https://uxplanet.org/checkbox-vs-toggle-switch-7fc6e83f10b8).
+
+A checkbox is not interchangeable with a [radio](radio). A radio must have at minimum 2 choice options and only one option can be checked. A checkbox, however, can have as many or as few items checked, and can be displayed as standalone or within a group of two or more.
+
+## Variants
+
+### Default
+
+<LiveExample src='Checkbox.indeterminate.tsx'>
+  <AllExamples.CheckboxIndeterminateExample client:load />
+</LiveExample>
+
+The default checkboxes are used to turn on and off one or multiple options.
+
+### Visibility
+
+<LiveExample src='Checkbox.visibility.tsx'>
+  <AllExamples.CheckboxVisibilityExample client:load />
+</LiveExample>
+
+Often times checkboxes are used to visibly turn on and off a layer within a view. If the checkboxes are used for visibility you can use the eyeball variant which uses an eyeball icon instead of a checkmark to reinforce that something is being shown or hidden.
+
+## Usage
+
+### With input group
 
-Checkboxes are usually accompanied by a label. They can be used either for selecting one or more options in a list, or to enable, disable, show, or hide a feature in the UI. It should however not be confused with a toggle switch, which has a similar role but is not appropriate in all settings. To learn more about when to use a toggle switch or a checkbox, please read [Checkbox vs Toggle Switch by Saadia Minhas](https://uxplanet.org/checkbox-vs-toggle-switch-7fc6e83f10b8).
+<LiveExample src='Checkbox.inputgroup.tsx'>
+  <AllExamples.CheckboxInputGroupExample client:load />
+</LiveExample>
+
+Checkboxes are often paired with the [input group](inputgroup) which gives many additional options.
+
+### Indeterminate
+
+<LiveExample src='Checkbox.indeterminate.tsx'>
+  <AllExamples.CheckboxIndeterminateExample client:load />
+</LiveExample>
+
+When a main option has associated sub-options, parent-child checkboxes are used. They make selecting/unselecting the entirety of a list of options easier if all or neither of them apply to a user’s choice. If some, but not all, child checkboxes are checked, the parent checkbox becomes an indeterminate checkbox.
+
+### Loading
+
+<LiveExample src='Checkbox.loading.tsx'>
+  <AllExamples.CheckboxLoadingExample client:load />
+</LiveExample>
+
+If the checkbox is performing an action immediately after being checked, it may take the user interface some time before reflecting that change. While waiting for that change to occur you can display a loading checkbox so the user understands that the action taken has yet to be applied.
+
+### Statuses
+
+<LiveExample src='Checkbox.statuses.tsx'>
+  <AllExamples.CheckboxStatusesExample client:load />
+</LiveExample>
 
-A checkbox is not interchangeable with a radio button. A radio button must have at minimum 2 choice options, almost always has one option pre-selected, and cannot have several options selected at once. A checkbox, however, can be checked and unchecked at will, and can be displayed as standalone or in a group of two or more.
+If you ever need to display the status or severity of a single checkbox, you can apply a status on the checkbox. Before doing so, consider if using an [input group](inputgroup) with a status message makes more sense.
 
 ## Props