@synerise/ds-card-select 1.1.55 → 1.1.56

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 +116 -0
  3. package/package.json +7 -6
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.1.56](https://github.com/Synerise/synerise-design/compare/@synerise/ds-card-select@1.1.55...@synerise/ds-card-select@1.1.56) (2026-07-23)
7
+
8
+ **Note:** Version bump only for package @synerise/ds-card-select
9
+
6
10
  ## [1.1.55](https://github.com/Synerise/synerise-design/compare/@synerise/ds-card-select@1.1.54...@synerise/ds-card-select@1.1.55) (2026-06-17)
7
11
 
8
12
  **Note:** Version bump only for package @synerise/ds-card-select
package/CLAUDE.md ADDED
@@ -0,0 +1,116 @@
1
+ # CardSelect (`@synerise/ds-card-select`)
2
+
3
+ > A selectable card component with a tick/checkbox indicator, optional icon, tag ribbon, and info tooltip; `CardSelectGroup` lays multiple cards in a CSS grid.
4
+
5
+ ## Package structure
6
+
7
+ ```
8
+ src/
9
+ CardSelect.tsx — main component (wrapped in styled-components withTheme)
10
+ CardSelect.types.ts — CardSelectProps, CardSelectAlignType, CardSelectSizeType
11
+ CardSelect.styles.ts — all styled-components; uses styled-is for conditional styles
12
+ CardSelectGroup/
13
+ CardSelectGroup.tsx — grid wrapper; renders from items array or children
14
+ CardSelectGroup.types.ts — CardSelectGroupProps
15
+ CardSelectGroup.styles.ts — CSS grid; deprecated CardGroup alias
16
+ constants.ts — default icon/tick sizes per size variant
17
+ index.ts — public exports
18
+ ```
19
+
20
+ ## Public exports
21
+
22
+ ### `CardSelect` (default export)
23
+
24
+ Wrapped in `withTheme` — do **not** pass `theme` manually (it is `@deprecated`).
25
+
26
+ | Prop | Type | Default | Description |
27
+ |------|------|---------|-------------|
28
+ | `value` | `boolean` | `false` | Whether the card is selected. Controls blue outline + tick state. |
29
+ | `onChange` | `(value: boolean) => void` | `undefined` | Fires with toggled boolean on click, **unless** `onClick` is also set. |
30
+ | `onClick` | `() => void` | `undefined` | When set, `onChange` is suppressed — use this for custom toggle logic. |
31
+ | `size` | `'small' \| 'medium'` | `'medium'` | Card padding, font sizes, icon/tick sizes, gap in group. |
32
+ | `title` | `ReactNode` | `undefined` | Card title text. |
33
+ | `description` | `ReactNode` | `undefined` | Subtitle text. **Not rendered when `size='small'`**. |
34
+ | `icon` | `ReactNode` | `undefined` | Icon element rendered above the title. |
35
+ | `iconSize` | `number` | `96` (medium) / `48` (small) | Overrides the default icon size in px. |
36
+ | `tickSize` | `number` | `30` (medium) / `24` (small) | Overrides the default tick/check icon size in px. |
37
+ | `tickVisible` | `boolean` | `true` | Shows the tick / radio-circle indicator in the top corner. |
38
+ | `customTickVisible` | `boolean` | `undefined` | Shows `customTickVisibleComponent` in the opposite corner from the tick. |
39
+ | `customTickVisibleComponent` | `ReactNode` | `undefined` | Rendered when `customTickVisible=true`. |
40
+ | `elementsPosition` | `'left' \| 'center' \| 'right'` | `'center'` | Aligns title, description, icon, and tick horizontally. |
41
+ | `raised` | `boolean` | `undefined` | Uses `@box-shadow-base` / `@box-shadow-active` instead of the 1px border outline. |
42
+ | `stretchToFit` | `boolean` | `undefined` | Sets `height: 100%` — use inside a grid to equalise card heights. |
43
+ | `disabled` | `boolean` | `undefined` | 40% opacity + `pointer-events: none`. `cursor: not-allowed` on the outer wrapper. |
44
+ | `error` | `boolean` | `undefined` | Shows a 2px red-500 outline. |
45
+ | `tagProps` | `Omit<TagProps, 'shape'\|'removable'\|'asPill'\|'onRemove'\|'image'\|'texts'>` | `undefined` | Renders a `TagShape.DEFAULT_SQUARE` pill ribbon above the card. |
46
+ | `tagTooltipProps` | `TooltipProps` | `undefined` | Wraps the tag ribbon in a `<Tooltip>`. |
47
+ | `infoTooltipProps` | `TooltipProps` | `undefined` | Renders an `InfoFillS` icon with tooltip in the top-corner `Aside`. |
48
+ | `className` | `string` | `undefined` | Additional class on the inner container (also always gets `ds-card-select`). |
49
+ | `key` | `Key` | `undefined` | Standard React key (used by `CardSelectGroup` when rendering `items`). |
50
+ | `theme` | `{ [k: string]: string }` | — | **@deprecated** — injected by `withTheme`, do not pass manually. |
51
+
52
+ ### `CardSelectGroup`
53
+
54
+ CSS grid container for multiple `CardSelect` items.
55
+
56
+ | Prop | Type | Default | Description |
57
+ |------|------|---------|-------------|
58
+ | `items` | `(CardSelectProps & { key: Key })[]` | `undefined` | Preferred way to supply cards. Renders `<CardSelect>` elements internally. |
59
+ | `children` | `ReactNode` | `undefined` | **@deprecated** — pass `CardSelect` elements as children instead of `items`. |
60
+ | `columns` | `number \| null` | `2` | Number of grid columns. Pass `null` to put all items in a single row. |
61
+ | `size` | `'small' \| 'medium'` | `undefined` | Passed to each `CardSelect` and controls grid gap (16px for small, 24px for medium/large). |
62
+ | `width` | `'small' \| 'large'` | `'large'` | **@deprecated** — use `size` instead. Controls gap only. |
63
+ | `className` | `string` | `undefined` | Class on the grid wrapper. |
64
+
65
+ ### Type exports
66
+
67
+ `CardSelectProps`, `CardSelectGroupProps`
68
+
69
+ ## Usage patterns
70
+
71
+ ```tsx
72
+ import CardSelect, { CardSelectGroup } from '@synerise/ds-card-select';
73
+
74
+ // Uncontrolled toggle
75
+ const [selected, setSelected] = useState(false);
76
+ <CardSelect
77
+ title="Option A"
78
+ description="Some details"
79
+ value={selected}
80
+ onChange={setSelected}
81
+ tickVisible
82
+ />
83
+
84
+ // Group from items array (preferred)
85
+ <CardSelectGroup
86
+ columns={3}
87
+ size="medium"
88
+ items={[
89
+ { key: '1', title: 'Type A', value: selected === 'A', onChange: () => setSelected('A') },
90
+ { key: '2', title: 'Type B', value: selected === 'B', onChange: () => setSelected('B') },
91
+ ]}
92
+ />
93
+
94
+ // Tag ribbon + info tooltip
95
+ <CardSelect
96
+ title="Premium"
97
+ tagProps={{ name: 'NEW', color: '#54cb0b', textColor: '#fff' }}
98
+ infoTooltipProps={{ title: 'This is the premium tier' }}
99
+ value={false}
100
+ onChange={setValue}
101
+ />
102
+ ```
103
+
104
+ ## Styling
105
+
106
+ Styles are in `CardSelect.styles.ts` using `styled-is` for `is(prop)` / `isNot(prop)` conditional CSS blocks. All colours are resolved from `@synerise/ds-core` theme palette tokens — no hardcoded hex values except in comments. The `styled-is` library is an additional dependency not used elsewhere in the DS.
107
+
108
+ ## Implementation notes
109
+
110
+ - **`onClick` suppresses `onChange`**: the click handler does `onClick ? onClick() : onChange && onChange(!value)`. If you need both, call `onChange` yourself inside `onClick`.
111
+ - **`isPressed` state**: a brief `isPressed=true` is set on click and cleared by `useOnClickOutside`. This controls the pressed box-shadow state but is visual-only.
112
+ - **`description` is silently dropped** when `size='small'` — the JSX is `{description && size !== 'small' && …}`.
113
+ - **Tag ribbon offset**: the `TagRibbonAnchor` padding is calculated from constants (`TAG_LEFT_OFFSET*`) to align the ribbon with or without a tick. Position (`left`/`right`) is mirrored based on `elementsPosition`.
114
+ - **`CardSelectGroup` columns fallback**: when `columns` is `null`, the grid uses `itemsCount` columns (i.e. all items in one row). When both `items` and `children` are provided, `items` takes precedence.
115
+ - **`width` prop is deprecated**: it maps to the same styled `size` prop on the wrapper and only affects gap, not card size. Use `size` for both.
116
+ - **`withTheme` wrapper**: `CardSelect` is exported as `withTheme(CardSelect)` so the component receives `theme` as a prop. Internally it also calls `useTheme()` from `@synerise/ds-core`. The `theme` prop type is marked `@deprecated`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@synerise/ds-card-select",
3
- "version": "1.1.55",
3
+ "version": "1.1.56",
4
4
  "description": "Card-Select 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"
@@ -41,10 +42,10 @@
41
42
  ],
42
43
  "types": "dist/index.d.ts",
43
44
  "dependencies": {
44
- "@synerise/ds-icon": "^1.18.4",
45
- "@synerise/ds-tag": "^1.4.31",
46
- "@synerise/ds-tooltip": "^1.5.3",
47
- "@synerise/ds-utils": "^1.10.1",
45
+ "@synerise/ds-icon": "^1.18.5",
46
+ "@synerise/ds-tag": "^1.4.32",
47
+ "@synerise/ds-tooltip": "^1.5.4",
48
+ "@synerise/ds-utils": "^1.10.2",
48
49
  "styled-is": "^1.3.0"
49
50
  },
50
51
  "peerDependencies": {
@@ -54,5 +55,5 @@
54
55
  "styled-components": "^5.3.3",
55
56
  "vitest": "4"
56
57
  },
57
- "gitHead": "d8c64070f58f14e3fb1bfbcbf00d1e3b8fd51eb8"
58
+ "gitHead": "d0a43cc43d8528a36f105aceea52ab470edb71d9"
58
59
  }