@synerise/ds-checkbox 1.2.35 → 1.2.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/CLAUDE.md +139 -0
  3. package/package.json +4 -3
package/CHANGELOG.md CHANGED
@@ -3,6 +3,10 @@
3
3
  All notable changes to this project will be documented in this file.
4
4
  See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
5
5
 
6
+ ## [1.2.36](https://github.com/synerise/synerise-design/compare/@synerise/ds-checkbox@1.2.35...@synerise/ds-checkbox@1.2.36) (2026-07-23)
7
+
8
+ **Note:** Version bump only for package @synerise/ds-checkbox
9
+
6
10
  ## [1.2.35](https://github.com/synerise/synerise-design/compare/@synerise/ds-checkbox@1.2.34...@synerise/ds-checkbox@1.2.35) (2026-06-27)
7
11
 
8
12
  **Note:** Version bump only for package @synerise/ds-checkbox
package/CLAUDE.md ADDED
@@ -0,0 +1,139 @@
1
+ # Checkbox (`@synerise/ds-checkbox`)
2
+
3
+ > DS-native, antd-free checkbox with DS-specific extras (description, error text, error styling, padding control), a `Checkbox.Group`, and a three-state mode (unchecked → checked → indeterminate → unchecked) via the `tristate` prop.
4
+
5
+ ## Package structure
6
+
7
+ ```
8
+ src/
9
+ Checkbox.tsx — router: delegates to CheckboxBase or CheckboxTristate; attaches .Group
10
+ Checkbox.types.ts — CheckboxProps union, CheckboxGroupProps, event types, CheckboxValueType
11
+ Checkbox.styles.ts — CheckboxLabel (full visual), CheckboxWrapper, AdditionalData
12
+ CheckboxGroup.tsx — DS-native Checkbox.Group (context provider)
13
+ CheckboxContext.ts — group context (value + toggle + register)
14
+ index.ts — public exports
15
+ components/
16
+ CheckboxBase.tsx — DS-native checkbox input (DOM + group consumption + event synthesis)
17
+ CheckboxTristate.tsx — three-state stateful layer on top of CheckboxBase
18
+ utils/
19
+ isTristateCheckbox.ts — type guard: checks props.tristate === true
20
+ nextCheckedValues.ts — state machine: (checked, indeterminate) → [nextChecked, nextIndeterminate]
21
+ checkedValue.ts — maps (checked, indeterminate) → boolean | undefined for event payload
22
+ ```
23
+
24
+ No LESS, no antd — the antd base + `checkbox.mixin.less` + styled overrides were inlined into `Checkbox.styles.ts`.
25
+
26
+ ## Public exports
27
+
28
+ ### `Checkbox` (default)
29
+
30
+ Smart router component. If `tristate={true}`, renders `CheckboxTristate`; otherwise renders `CheckboxBase`. Attaches `Checkbox.Group` as a static property.
31
+
32
+ #### DS-specific props (from `BaseCheckboxProps`)
33
+
34
+ | Prop | Type | Default | Description |
35
+ |------|------|---------|-------------|
36
+ | `description` | `ReactNode` | `undefined` | Helper text rendered below the checkbox with `ds-typography` `Description`. Respects `disabled` state (greyed out). |
37
+ | `errorText` | `ReactNode` | `undefined` | Error message rendered below. Also triggers the error visual on the checkbox box. |
38
+ | `hasError` | `boolean` | `undefined` | Error visual (red border) without an error text message. |
39
+ | `withoutPadding` | `boolean` | `undefined` | Removes the default `4px 12px 8px 8px` padding from the wrapper div. |
40
+
41
+ #### Mode-selector prop
42
+
43
+ | Prop | Type | Default | Description |
44
+ |------|------|---------|-------------|
45
+ | `tristate` | `true` | `undefined` | Switches to tristate mode. Changes the `onChange` event signature (see below). Cannot be `false` — omit the prop entirely for standard mode. |
46
+
47
+ Standard checkbox props are supported: `checked`, `defaultChecked`, `disabled`, `indeterminate`, `autoFocus`, `onChange`, `children`, `value`, `name`, `id`, `tabIndex`. (DS-native types — no antd inheritance.)
48
+
49
+ #### `onChange` event in tristate mode
50
+
51
+ When `tristate={true}`, `onChange` receives a `CheckboxTristateChangeEvent` instead of the standard Ant Design `CheckboxChangeEvent`. The key difference: `event.target.checked` is `boolean | undefined` — `undefined` means the indeterminate state.
52
+
53
+ #### `Checkbox.Group`
54
+
55
+ DS-native group (`CheckboxGroup`) — a context provider that child `Checkbox`es read for their checked state and toggle through. Supports `value`/`defaultValue` (controlled/uncontrolled), `onChange(checkedValues)` (ordered by child mount order, or `options` order), `options`, `disabled`, `name`. Replaces the former antd `Checkbox.Group` re-export.
56
+
57
+ ### Utility functions (exported)
58
+
59
+ | Export | Signature | Description |
60
+ |--------|-----------|-------------|
61
+ | `isTristateCheckbox` | `(props) => props is CheckboxTristateProps` | Type guard: returns `true` when `props.tristate === true`. |
62
+ | `nextCheckedValues` | `(checked, indeterminate) => [boolean, boolean]` | Computes the next `[checked, indeterminate]` state in the tristate cycle. |
63
+ | `checkedValue` | `(checked, indeterminate) => boolean \| undefined` | Converts internal state to the external checked value (`undefined` = indeterminate). |
64
+
65
+ ### Types (exported)
66
+
67
+ | Export | Description |
68
+ |--------|-------------|
69
+ | `CheckboxProps` | `CheckboxBaseProps \| CheckboxTristateProps` — main union |
70
+ | `CheckboxBaseProps` | Ant `CheckboxProps` + `BaseCheckboxProps`, with standard `onChange` |
71
+ | `CheckboxTristateProps` | Ant `CheckboxProps` + `BaseCheckboxProps`, with `tristate: true` and tristate `onChange` |
72
+ | `BaseCheckboxProps` | DS-only additions: `description`, `errorText`, `hasError`, `withoutPadding` |
73
+ | `CheckboxTristateChangeEvent` | Tristate event type: `target.checked` is `boolean \| undefined` |
74
+ | `CheckboxTristateChangeEventTarget` | The `target` shape inside `CheckboxTristateChangeEvent` |
75
+
76
+ ## Usage patterns
77
+
78
+ ```tsx
79
+ import Checkbox from '@synerise/ds-checkbox';
80
+
81
+ // Standard checkbox
82
+ <Checkbox onChange={handleChange}>Label</Checkbox>
83
+
84
+ // With error and description
85
+ <Checkbox
86
+ hasError
87
+ errorText="This field is required"
88
+ description="Choose at least one option"
89
+ >
90
+ Accept terms
91
+ </Checkbox>
92
+
93
+ // Tristate (uncontrolled — cycles false → true → indeterminate)
94
+ <Checkbox
95
+ tristate
96
+ onChange={(e) => {
97
+ // e.target.checked: true | false | undefined (undefined = indeterminate)
98
+ console.log(e.target.checked);
99
+ }}
100
+ >
101
+ Select all
102
+ </Checkbox>
103
+
104
+ // Tristate (controlled)
105
+ <Checkbox
106
+ tristate
107
+ checked={someState} // boolean | undefined
108
+ onChange={(e) => setSomeState(e.target.checked)}
109
+ >
110
+ Select all
111
+ </Checkbox>
112
+
113
+ // Group (Ant Design pass-through)
114
+ <Checkbox.Group options={['A', 'B', 'C']} onChange={handleGroupChange} />
115
+ ```
116
+
117
+ ## Styling
118
+
119
+ `Checkbox.styles.ts` is pure styled-components (theme tokens). **Each element is its own styled-component and owns its styles** — the `.ant-checkbox-*` / `ds-checkbox-*` class names are kept on the elements purely as hooks (ui-tests / interim external CSS), never used as styling selectors. State is passed in as transient `$`-props by `CheckboxBase`:
120
+ - `CheckboxWrapper` — flex column container; `withoutPadding` removes default spacing.
121
+ - `CheckboxBox` — the `.ant-checkbox` span (positioning).
122
+ - `CheckboxInput` — the visually-hidden `<input>` overlaying the box.
123
+ - `CheckboxInner` — the visible box: `grey-300` border, white-tick check (inline SVG data URL) when `$checked`, 2px white bar when `$indeterminate`, `$error` border, `$disabled` greys.
124
+ - `CheckboxText` — the label text; `$checked`/`$disabled` drive its colour/opacity.
125
+ - `CheckboxLabel` — the `<label>`; layout + the **cross-element** rules (hover-preview, indeterminate hover, focus ring, disabled cursor) that reference the child styled-components (`&:hover ${CheckboxInner}`, `${CheckboxInput}:focus + ${CheckboxInner}`). The hover-preview rule is only emitted when `!$checked && !$indeterminate && !$disabled`, so checked/disabled states never fight it.
126
+ - `AdditionalData` — left-aligns `errorText` and `description` below the checkbox box (28px left indent to align with label text).
127
+
128
+ ## Implementation notes
129
+
130
+ - **Tristate state machine** — the cycle is: `false` (unchecked) → `true` (checked) → `indeterminate` (represented as `undefined` to consumers) → `false`. Implemented in `nextCheckedValues`:
131
+ - `checked=false` → `[true, false]`
132
+ - `checked=true, !indeterminate` → `[true, true]`
133
+ - anything else → `[false, false]`
134
+ - **`tristate` as discriminated union discriminant** — `tristate?: never | false | undefined` in `OnChangeBaseProps` vs `tristate: true` in `OnChangeTristateProps`. This means TypeScript narrows `onChange` type correctly, but `tristate={false}` is technically forbidden by the type (use omission instead).
135
+ - **Controlled tristate** — the `useEffect` in `CheckboxTristate` syncs external `checked` to internal state. If `checked === undefined` externally, sets `indeterminate=true` and internal `checked=false`. If `checked` is boolean, sets `indeterminate=false`.
136
+ - **`CheckboxBase` and `CheckboxTristate` are NOT re-exported** from the main `index.ts` — they are internal components. Import `Checkbox` and use the `tristate` prop instead.
137
+ - **`$solo` transient prop** — `CheckboxLabel` receives `$solo={!children && !errorText && !description}`. When true, adds `padding: 4px` to keep the bare checkbox box from being flush against its container.
138
+ - **`Checkbox.Group`** is a DS-native context provider (`CheckboxGroup`). Child `Checkbox`es read the group's `value`/`toggleOption` from `CheckboxContext`; `options`-mode renders `CheckboxBase` directly (avoids a `Checkbox` ↔ `CheckboxGroup` import cycle).
139
+ - **`onChange` event is synthesised** in `CheckboxBase` from the native input change: `{ target: { value, name, checked }, stopPropagation, preventDefault, nativeEvent }` — antd-compatible shape.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@synerise/ds-checkbox",
3
- "version": "1.2.35",
3
+ "version": "1.2.36",
4
4
  "description": "Checkbox UI Component for the Synerise Design System",
5
5
  "license": "ISC",
6
6
  "repository": "synerise/synerise-design",
@@ -17,6 +17,7 @@
17
17
  "files": [
18
18
  "/dist",
19
19
  "CHANGELOG.md",
20
+ "CLAUDE.md",
20
21
  "README.md",
21
22
  "package.json",
22
23
  "LICENSE.md"
@@ -40,7 +41,7 @@
40
41
  "*.less"
41
42
  ],
42
43
  "dependencies": {
43
- "@synerise/ds-typography": "^1.1.26"
44
+ "@synerise/ds-typography": "^1.1.27"
44
45
  },
45
46
  "devDependencies": {
46
47
  "vitest": "4"
@@ -50,5 +51,5 @@
50
51
  "react": ">=16.9.0 <= 18.3.1",
51
52
  "styled-components": "^5.3.3"
52
53
  },
53
- "gitHead": "dfd892acc1d02abebcf661db3fb32f0fc4b6c354"
54
+ "gitHead": "d0a43cc43d8528a36f105aceea52ab470edb71d9"
54
55
  }