@bento/checkbox 0.1.2 → 0.1.3

package/README.md

@@ -0,0 +1,284 @@
+# Checkbox
+
+The `@bento/checkbox` package provides accessible and customizable checkbox inputs. It exports the **CheckboxGroup** and **Checkbox** primitives, enabling you to build individual or groups of checkboxes with consistent keyboard navigation, focus management, and ARIA support. React Aria is used to ensure that the checkboxes are accessible to all users.
+
+The `CheckboxGroup` allows a user to select multiple items from a list of `Checkbox` components.
+
+The `Checkbox` is a single checkbox option that can be selected by the user.
+
+# Installation
+
+```bash
+npm install --save @bento/checkbox
+```
+
+## Props
+
+The following properties are available to be used on the `CheckboxGroup` and `Checkbox` primitives:
+
+### Checkbox
+
+| Prop | Type | Required | Description |
+|------|------|----------|------------|
+| `value` | `string` | No | The value of the checkbox, used when submitting an HTML form. |
+| `name` | `string` | No | The name of the checkbox. |
+| `inputRef` | `Ref<HTMLInputElement>` | No | A ref for the HTML input element. |
+| `children` | `ReactNode` | No | The label for the checkbox. Accepts any renderable node. |
+| `isRequired` | `boolean` | No | Whether the checkbox is required or not. |
+| `isReadOnly` | `boolean` | No | Whether the input can be selected but not changed by the user. |
+| `isDisabled` | `boolean` | No | Whether the checkbox is disabled or not. Shows that a selection exists,
+but is not available in that circumstance. |
+| `autoFocus` | `boolean` | No | Whether the element should receive focus on render. |
+| `isIndeterminate` | `boolean` | No | Whether the checkbox is in an indeterminate state. |
+| `isSelected` | `boolean` | No | Whether the checkbox is in a selected state. |
+| `label` | `ReactNode` | No | The label for the control. |
+| `slot` | `string` | No | A named part of a component that can be customized. This is implemented by the consuming component.
+The exposed slot names of a component are available in the components documentation. |
+| `inputProps` | `DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>` | No | Props to pass to the underlying input element. |
+| `labelProps` | `DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>` | No | Props to pass to the label element. |
+| `slots` | `Record<string, object \| Function>` | No | An object that contains the customizations for the slots.
+The main way you interact with the slot system as a consumer. |
+
+### CheckboxGroup
+
+| Prop | Type | Required | Description |
+|------|------|----------|------------|
+| `value` | `string[]` | No | The current value of the checkbox group (controlled). |
+| `defaultValue` | `string[]` | No | The default value of the checkbox group (uncontrolled). |
+| `isDisabled` | `boolean` | No | Whether the input is disabled. |
+| `isReadOnly` | `boolean` | No | Whether the input can be selected but not changed by the user. |
+| `isRequired` | `boolean` | No | Whether user input is required on the input before form submission. |
+| `isInvalid` | `boolean` | No | Whether the input value is invalid. |
+| `name` | `string` | No | The name of the input element, used when submitting an HTML form. |
+| `form` | `string` | No | The <form> element to associate the input with.
+The value of this attribute must be the id of a <form> in the same document. |
+| `description` | `string` | No | Description for the checkbox group. |
+| `children` | `ReactNode` | No | Checkbox children. |
+| `errorMessage` | `ReactNode \| ((val: ValidationResult) => ReactNode)` | No | Error message for the checkbox group. |
+| `slot` | `string` | No | A named part of a component that can be customized. This is implemented by the consuming component.
+The exposed slot names of a component are available in the components documentation. |
+| `labelProps` | `DetailedHTMLProps<LabelHTMLAttributes<HTMLLabelElement>, HTMLLabelElement>` | No | Props to pass to the label element. |
+| `descriptionProps` | `DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>` | No | Props to pass to the description element. |
+| `errorMessageProps` | `DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>` | No | Props to pass to the error message element. |
+| `contentProps` | `DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>` | No | The props passed to the content element. |
+| `slots` | `Record<string, object \| Function>` | No | An object that contains the customizations for the slots.
+The main way you interact with the slot system as a consumer. |
+
+## Data Attributes, Slot Map and Props
+
+### Data Attributes
+
+The following data attributes can be used to style and customize the `CheckboxGroup` and `Checkbox` primitives.
+
+#### `CheckboxGroup` Data Attributes
+
+| Attribute       | Description                     |
+| --------------- | ------------------------------- |
+| `data-disabled` | Indicates the checkbox group is disabled |
+| `data-read-only` | Indicates the checkbox group is readonly |
+| `data-required` | Indicates the checkbox group is required |
+| `data-invalid`  | Indicates the checkbox group is invalid  |
+
+#### `Checkbox` Data Attributes
+
+| Attribute       | Description                     |
+| --------------- | ------------------------------- |
+| `data-disabled` | Indicates the checkbox is disabled |
+| `data-read-only` | Indicates the checkbox is readonly |
+| `data-required` | Indicates the checkbox is required |
+| `data-invalid`  | Indicates the checkbox is invalid  |
+| `data-indeterminate` | Indicates the checkbox is in an indeterminate state |
+| `data-pressed`       | Indicates the checkbox is being pressed |
+| `data-hovered`       | Indicates the checkbox is hovered       |
+| `data-focused`       | Indicates the checkbox has focus        |
+| `data-focus-visible` | Indicates focus should be visible    |
+| `data-selected`      | Indicates the checkbox is selected      |
+
+### Slot Map
+
+The `CheckboxGroup` and `Checkbox` primitives are built off of the `Control` and `ControlGroup` primitives, which provide a consisten set of slot values, as shown below.
+
+#### `CheckboxGroup` Slot Map
+
+| Slot Name           | Description                  |
+| ------------------- | ---------------------------- |
+| `group.label`       | Label for checkbox group     |
+| `group.description` | Description for checkbox group|
+| `group.error`       | Error message for checkbox group|
+
+#### `Checkbox` Slot Map
+
+| Slot Name       | Description    |
+| --------------- | -------------- |
+| `control.icon-checked`  | Icon for checked checkbox |
+| `control.icon-unchecked`  | Icon for unchecked checkbox |
+| `control.icon-indeterminate`  | Icon for indeterminate checkbox |
+| `control.label` | Text for checkbox |
+
+## Examples
+
+### Default Checkbox - Uncontrolled
+
+The `Checkbox` primitive is uncontrolled by default, meaning it manages its own state internally. You can also use it in a controlled manner by providing the `checked` and `onChange` props.
+
+```tsx
+/* v8 ignore next */
+import React from 'react';
+import { Checkbox } from '@bento/checkbox';
+
+export function CheckboxExample(args: React.ComponentProps<typeof Checkbox>) {
+  return (
+    <Checkbox name="checkbox-example" value="checkbox-value" {...args}>
+      Checkbox Label
+    </Checkbox>
+  );
+}
+```
+
+### Controlled Checkbox
+
+The `Checkbox` can also be used in a controlled manner, where you manage its state externally with the `checked` and `onChange` props.
+
+```tsx
+/* v8 ignore next */
+import React, { useState } from 'react';
+import { Checkbox } from '@bento/checkbox';
+
+export function CheckboxControlledExample() {
+  const [checked, setChecked] = useState(false);
+
+  return (
+    <Checkbox
+      name="checkbox-controlled-example"
+      value="checkbox-controlled-value"
+      isSelected={checked}
+      onChange={setChecked}
+    >
+      Controlled Checkbox
+    </Checkbox>
+  );
+}
+```
+
+### Checkbox Group
+
+The `CheckboxGroup` allows a user to select multiple items from a list of `Checkbox` components.
+
+```tsx
+/* v8 ignore next */
+import React from 'react';
+import { Checkbox, CheckboxGroup } from '@bento/checkbox';
+
+export function CheckboxGroupExample(args: React.ComponentProps<typeof CheckboxGroup>) {
+  return (
+    <CheckboxGroup label="Checkbox Group" name="checkbox-group-example" {...args}>
+      <Checkbox value="checkbox-1">Checkbox 1</Checkbox>
+      <Checkbox value="checkbox-2">Checkbox 2</Checkbox>
+    </CheckboxGroup>
+  );
+}
+```
+
+### Controlled Checkbox Group
+
+The `CheckboxGroup` can also be used in a controlled manner, where you manage the state of the checkboxes externally with the `value` and `onChange` props.
+
+```tsx
+/* v8 ignore next */
+import React, { useState } from 'react';
+import { Checkbox, CheckboxGroup } from '@bento/checkbox';
+
+export function CheckboxGroupControlledExample() {
+  const [selectedValues, setSelectedValues] = useState<string[]>([]);
+
+  return (
+    <CheckboxGroup label="Checkbox Group" value={selectedValues} onChange={setSelectedValues}>
+      <Checkbox value="option1">Option 1</Checkbox>
+      <Checkbox value="option2">Option 2</Checkbox>
+      <Checkbox value="option3">Option 3</Checkbox>
+    </CheckboxGroup>
+  );
+}
+```
+
+### Checkbox Group with Indeterminate State
+
+The `CheckboxGroup` can also support an indeterminate state, which is useful when some but not all checkboxes are selected. The complex state management shown here is an example of how to handle indeterminate states in a checkbox group in a common way.
+
+```tsx
+/* v8 ignore next */
+import React, { useState } from 'react';
+import { Checkbox, CheckboxGroup } from '@bento/checkbox';
+
+export function CheckboxGroupIndeterminateExample() {
+  const [checkedItems, setCheckedItems] = useState<Set<string>>(new Set());
+
+  const items = [
+    { id: 'option1', label: 'Option 1' },
+    { id: 'option2', label: 'Option 2' },
+    { id: 'option3', label: 'Option 3' }
+  ];
+
+  const allItemIds = items.map(function getItemId(item) {
+    return item.id;
+  });
+  const isAllSelected = checkedItems.size === items.length;
+  const isIndeterminate = checkedItems.size > 0 && checkedItems.size < items.length;
+
+  function handleSelectAll(checked: boolean) {
+    if (checked) {
+      setCheckedItems(new Set([...allItemIds, 'select-all']));
+    } else {
+      setCheckedItems(new Set());
+    }
+  }
+
+  function handleItemChange(itemId: string, checked: boolean) {
+    setCheckedItems(function updateCheckedItems(prev) {
+      const newSet = new Set(prev);
+      if (checked) {
+        newSet.add(itemId);
+        if (
+          allItemIds.every(function checkItemInSet(id) {
+            return newSet.has(id);
+          })
+        ) {
+          newSet.add('select-all');
+        }
+      } else {
+        newSet.delete(itemId);
+        newSet.delete('select-all');
+      }
+      return newSet;
+    });
+  }
+
+  return (
+    <CheckboxGroup label="Select Items" value={Array.from(checkedItems)}>
+      <Checkbox
+        name="select-all"
+        value="select-all"
+        isSelected={isAllSelected}
+        isIndeterminate={isIndeterminate}
+        onChange={handleSelectAll}
+      >
+        Select All
+      </Checkbox>
+
+      {items.map((item) => (
+        <Checkbox
+          key={item.id}
+          name={item.id}
+          value={item.id}
+          isSelected={checkedItems.has(item.id)}
+          onChange={function handleItemChangeForItem(checked) {
+            return handleItemChange(item.id, checked);
+          }}
+        >
+          {item.label}
+        </Checkbox>
+      ))}
+    </CheckboxGroup>
+  );
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bento/checkbox",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Checkbox component",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -9,6 +9,7 @@
     "build": "tsup-node",
     "lint": "biome lint && tsc",
     "posttest": "npm run lint",
+    "prepublishOnly": "node ../../scripts/compile-readme.ts",
     "pretest": "npm run build",
     "test": "vitest --run",
     "test:watch": "vitest"
@@ -39,11 +40,11 @@
     "package.json"
   ],
   "dependencies": {
-    "@bento/control": "^0.1.1",
-    "@bento/icon": "^0.1.1",
-    "@bento/slots": "^0.1.2",
-    "@bento/use-data-attributes": "^0.1.0",
-    "@bento/use-props": "^0.1.0",
+    "@bento/control": "^0.1.2",
+    "@bento/icon": "^0.1.2",
+    "@bento/slots": "^0.1.3",
+    "@bento/use-data-attributes": "^0.1.1",
+    "@bento/use-props": "^0.1.1",
     "@react-aria/utils": "^3.30.0",
     "react-aria": "^3.44.0",
     "react-stately": "^3.42.0"