|
1 | 1 | import api from "./code-notate/api.json"; |
| 2 | +import Hero from "./examples/hero.tsx"; |
| 3 | +import SelectAll from "./examples/select-all.tsx"; |
2 | 4 |
|
3 | 5 | # Checklist |
4 | 6 | A group of selectable items that can be toggled individually or all at once. |
5 | | -<Showcase name="hero" /> |
6 | | -## Features |
7 | | -<Features api={api} /> |
8 | | -## Anatomy |
9 | | -<AnatomyTable api={api} /> |
10 | | -## Examples |
11 | | -### Basic Usage |
12 | | -The basic checklist setup allows users to select multiple items independently. |
13 | | -<Showcase name="select-all" /> |
14 | | -This example demonstrates: |
15 | | -- `Checklist.Root` as the container for all checklist items |
16 | | -- `Checklist.Item` for individual selectable items |
17 | | -- `Checklist.ItemTrigger` and `Checklist.ItemIndicator` for the checkbox interaction |
18 | | -- `Checklist.ItemLabel` for item text |
19 | | -- `Checklist.SelectAll` for the parent checkbox that controls all items |
20 | | -- `Checklist.SelectAllIndicator` showing the mixed state with both check and minus icons |
21 | | -- `Checklist.Label` for the select all text |
22 | | -The select-all functionality automatically manages three states: |
23 | | -- Unchecked when no items are selected |
24 | | -- Mixed state when some items are selected |
25 | | -- Checked when all items are selected |
26 | | -Each item maintains its own state while staying synchronized with the select-all checkbox. |
27 | | -Note: The example uses Lucide icons (`LuCheck` and `LuMinus`) to display the checkbox states, but you can customize these with your own icons or indicators. |
28 | | - |
29 | | -### Form Integration |
30 | | -Integrate with native HTML forms by adding the `Checklist.HiddenInput` component under each item. |
31 | | -The selected items are then automatically submitted with the form. The `name` input is required and should be unique |
32 | | -within the form. |
33 | | -<Showcase name="form" /> |
34 | | - |
35 | | -## Component State |
36 | | -### Using Component State |
37 | | -The Checklist component provides a powerful way to manage multiple checkbox selections with a "select all" capability. Let's look at how to implement and control the checklist state. |
38 | | -The basic checklist state is demonstrated in the hero example: |
39 | | -<Showcase name="hero" /> |
40 | | -For more advanced state management, including a "select all" feature: |
41 | | -<Showcase name="select-all" /> |
42 | | -This example demonstrates: |
43 | | -- Individual item selection state |
44 | | -- Select all functionality |
45 | | -- Mixed state when only some items are selected |
46 | | -### State Interactions |
47 | | -The checklist maintains three main states: |
48 | | -- Unchecked: No items selected |
49 | | -- Mixed: Some items selected |
50 | | -- Checked: All items selected |
51 | | -The select-all checkbox automatically updates based on the state of individual items: |
52 | | -- Shows unchecked when no items are selected |
53 | | -- Shows a mixed state when some items are selected |
54 | | -- Shows checked when all items are selected |
55 | | -To respond to state changes, the checklist items and select-all checkbox are automatically synchronized: |
56 | | -1. When clicking the select-all checkbox: |
57 | | - - If unchecked or mixed: All items become checked |
58 | | - - If checked: All items become unchecked |
59 | | -2. When clicking individual items: |
60 | | - - Updates the select-all checkbox state based on overall selection |
61 | | - - Maintains the mixed state when appropriate |
62 | | -The state management is handled automatically by the component, requiring no additional configuration from the user. Simply structure your checklist with the appropriate components and the state synchronization works out of the box. |
63 | | - |
64 | | -Based on the provided implementation and examples, I'll document the configuration options for the Checklist component. |
65 | | -## Core Configuration |
66 | | -### Select All Behavior |
67 | | -The Checklist component supports a "select all" functionality that manages the state of all child checkboxes. As shown in the `select-all` example above, this requires configuring both the select all trigger and individual items. |
68 | | -The select all state automatically manages three possible values: |
69 | | -- `false` - No items checked |
70 | | -- `true` - All items checked |
71 | | -- `"mixed"` - Some items checked |
72 | | -### Item Management |
73 | | -Items must be direct children of `Checklist.Root` to be properly tracked. The component internally manages indices for state synchronization. |
74 | | -> Each `Checklist.Item` requires a unique key when mapping over items to maintain proper state tracking. |
75 | | -### Group Configuration |
76 | | -The Checklist is configured as a checkbox group by default with the following characteristics: |
77 | | -```typescript |
78 | | -type ChecklistContext = { |
79 | | - isAllCheckedSig: Signal<boolean | "mixed">; |
80 | | - checkedStatesSig: Signal<(boolean | "mixed")[]>; |
81 | | -}; |
82 | | -``` |
83 | | -The context manages: |
84 | | -- Overall checked state (`isAllCheckedSig`) |
85 | | -- Individual item states (`checkedStatesSig`) |
86 | | -### Form Integration |
87 | | -The Checklist can be integrated with forms through the `HiddenInput` component. As shown in the `hero` example above, this manages the form submission state for all checkboxes in the group. |
88 | | -## Advanced Configuration |
89 | | -### State Synchronization |
90 | | -The Checklist implements a bi-directional state synchronization: |
91 | | -1. Select All → Items: |
92 | | -- When select all is toggled, all items update to match |
93 | | -- Mixed state is preserved when partially selected |
94 | | -2. Items → Select All: |
95 | | -- Select all updates based on collective item state |
96 | | -- Automatically switches to mixed state when appropriate |
97 | | -### Custom Layouts |
98 | | -While the component handles state management, the layout is fully customizable. As shown in the `select-all` example above, items can be nested and grouped with custom spacing and hierarchies. |
99 | | -> Note: The internal state tracking works regardless of DOM structure, but items must remain direct children of `Checklist.Root` in the component tree. |
100 | | -
|
101 | | -Based on the provided implementation and examples, I'll document the form-specific features of the Checklist component. |
102 | | -## Forms |
103 | | -The Checklist component provides form integration through the `<Checklist.HiddenInput>` component, which manages multiple checkbox form inputs. |
104 | | -The component follows a group pattern where the select-all functionality can control multiple checkbox states simultaneously. |
105 | | -<Showcase name="select-all" /> |
106 | | -In this example, the select-all checkbox controls the state of all child checkboxes, maintaining form state synchronization. When some items are selected, the select-all checkbox displays a mixed state, indicated by the minus icon. |
107 | | -The form state is managed through the `ChecklistContext`, which tracks: |
108 | | -- The overall checked state (`isAllCheckedSig`) |
109 | | -- Individual item states (`checkedStatesSig`) |
110 | | -The `<Checklist.Root>` component acts as a form group container with the appropriate `role="group"` attribute, ensuring proper form semantics and accessibility. |
111 | | -Note: The current implementation doesn't show explicit form validation examples, but the component structure includes `<Checklist.Error>` for handling validation states when needed. |
112 | | - |
113 | | - |
114 | | - |
115 | | -<APITable api={api} /> |
| 7 | +<Hero /> |
| 8 | +<SelectAll /> |
0 commit comments