@synerise/ds-time-picker 1.2.40 → 1.2.42

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 +8 -0
  2. package/CLAUDE.md +133 -0
  3. package/package.json +10 -9
package/CHANGELOG.md CHANGED
@@ -3,6 +3,14 @@
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.42](https://github.com/Synerise/synerise-design/compare/@synerise/ds-time-picker@1.2.41...@synerise/ds-time-picker@1.2.42) (2026-07-23)
7
+
8
+ **Note:** Version bump only for package @synerise/ds-time-picker
9
+
10
+ ## [1.2.41](https://github.com/Synerise/synerise-design/compare/@synerise/ds-time-picker@1.2.40...@synerise/ds-time-picker@1.2.41) (2026-07-16)
11
+
12
+ **Note:** Version bump only for package @synerise/ds-time-picker
13
+
6
14
  ## [1.2.40](https://github.com/Synerise/synerise-design/compare/@synerise/ds-time-picker@1.2.39...@synerise/ds-time-picker@1.2.40) (2026-07-09)
7
15
 
8
16
  **Note:** Version bump only for package @synerise/ds-time-picker
package/CLAUDE.md ADDED
@@ -0,0 +1,133 @@
1
+ # TimePicker (`@synerise/ds-time-picker`)
2
+ > A dropdown-based time picker that renders scrollable hour/minute/second columns with optional 12-hour (AM/PM) clock support, driven by a native `Date` value.
3
+
4
+ ## Package structure
5
+ ```
6
+ src/
7
+ TimePicker.tsx — main component; builds unit config, handles AM/PM toggling, renders Dropdown + Input
8
+ TimePicker.styles.tsx — styled-components for container, input wrapper, overlay, unit columns, cells
9
+ Unit.tsx — scrollable column for a single time unit (hour, minute, or second)
10
+ index.ts — public exports (default + constants + types)
11
+ modules.d.ts — ambient module declarations
12
+ types/
13
+ TimePicker.types.ts — TimePickerProps, TimePickerDisabledUnits, ClockModes
14
+ constants/
15
+ timePicker.constants.ts — HOUR, MINUTE, SECOND, CLOCK_MODES, AM, PM, HOUR_12,
16
+ DISABLE_CLOCK_MODE_HOUR, MAP_12_AM_TO_24_HOUR,
17
+ MAP_12_PM_TO_24_HOUR, MAP_24_HOUR_TO_12
18
+ timePicker.spec.constants.ts — test-only constants
19
+ utils/
20
+ timePicker.utils.ts — handleTimeChange: builds a new Date from a unit change or clock-mode toggle
21
+ clockMode.utils.ts — getClockModeFromDate, getOppositeClockMode
22
+ unit.utils.ts — getUnitSelectedNumber: converts 24-hour value to 12-hour display value
23
+ ```
24
+
25
+ ## Public exports
26
+
27
+ ### Default export: `TimePicker`
28
+
29
+ | Prop | Type | Default | Description |
30
+ |------|------|---------|-------------|
31
+ | `value` | `Date` | — | Controlled selected time value |
32
+ | `onChange` | `(value: Date \| undefined, timeString: string) => void` | — | Fired on unit select and on dropdown close |
33
+ | `units` | `dayjs.UnitType[]` | `['hour', 'minute', 'second']` | Which columns to render |
34
+ | `placeholder` | `string` | i18n `DS.TIME-PICKER.PLACEHOLDER` | Input placeholder text |
35
+ | `placement` | `'topLeft' \| 'topCenter' \| 'topRight' \| 'bottomLeft' \| 'bottomCenter' \| 'bottomRight'` | `'bottomLeft'` | Dropdown placement |
36
+ | `trigger` | `PopoverTriggerType[]` | `['click']` | What opens the dropdown |
37
+ | `defaultOpen` | `boolean` | — | Open on first render |
38
+ | `alwaysOpen` | `boolean` | — | Keeps dropdown open; clear button replaces clock icon whenever a value is set |
39
+ | `disabled` | `boolean` | — | Disables input and dropdown |
40
+ | `disabledHours` | `number[]` | — | Hour values (24-hour) to disable |
41
+ | `disabledMinutes` | `number[]` | — | Minute values to disable |
42
+ | `disabledSeconds` | `number[]` | — | Second values to disable |
43
+ | `use12HourClock` | `boolean` (**deprecated**) | derived from `DSProvider` | Override AM/PM mode; prefer `DSProvider::dataFormatConfig` |
44
+ | `timeFormat` | `string` (**deprecated**) | `'HH:mm:ss'` / `'hh:mm:ss A'` | dayjs format for display string; prefer `valueFormatOptions` |
45
+ | `valueFormatOptions` | `DateToFormatOptions` | — | Passed to `@synerise/ds-core` `formatValue` for display |
46
+ | `onClockModeChange` | `(mode: string) => void` | — | Fired when user switches AM/PM |
47
+ | `clearTooltip` | `string \| ReactNode` | `<FormattedMessage … "Clear" />` | Tooltip on the clear (×) icon |
48
+ | `overlayClassName` | `string` | — | CSS class on the dropdown overlay container |
49
+ | `className` | `string` | — | CSS class on the root container (also receives `ds-time-picker`) |
50
+ | `containerStyle` | `CSSProperties` | `{}` | Inline style on the root container |
51
+ | `dropdownProps` | `Partial<DropdownSharedProps>` (omits `children`, `overlay`, `open`, `onOpenChange`, `disabled`) | `{}` | Extra props forwarded to `@synerise/ds-dropdown` |
52
+ | `inputProps` | `Partial<InputProps>` | `{}` | Extra props forwarded to `@synerise/ds-input` |
53
+ | `raw` | `boolean` | — | When `true`, renders only the overlay (no input wrapper or dropdown chrome) |
54
+ | `errorText` | `ReactNode` | — | Error message shown on the input; hidden while the dropdown is open |
55
+
56
+ ### Named constant exports
57
+ | Export | Value / Type |
58
+ |--------|-------------|
59
+ | `AM` | `'AM'` |
60
+ | `PM` | `'PM'` |
61
+ | `HOUR` | `'hour'` (dayjs.UnitType) |
62
+ | `HOUR_12` | `12` |
63
+ | `CLOCK_MODES` | `['AM', 'PM']` |
64
+ | `DISABLE_CLOCK_MODE_HOUR` | `-1` (sentinel: disables the full AM or PM toggle) |
65
+ | `MAP_12_AM_TO_24_HOUR` | lookup: 12-hour AM index → 24-hour value |
66
+ | `MAP_12_PM_TO_24_HOUR` | lookup: 12-hour PM index → 24-hour value |
67
+ | `MAP_24_HOUR_TO_12` | lookup: 24-hour value → 12-hour display value |
68
+
69
+ ### Named type exports
70
+ - `ClockModes` — `'AM' | 'PM'`
71
+ - `TimePickerProps` — full props interface (re-exported for consumer typing)
72
+
73
+ ## Usage patterns
74
+
75
+ ```tsx
76
+ import TimePicker from '@synerise/ds-time-picker';
77
+
78
+ // Basic controlled usage
79
+ const [time, setTime] = React.useState<Date | undefined>(undefined);
80
+ <TimePicker value={time} onChange={(date) => setTime(date)} />
81
+
82
+ // Render just the panel (no input)
83
+ <TimePicker value={time} onChange={(date) => setTime(date)} raw />
84
+
85
+ // Only hour + minute columns
86
+ <TimePicker value={time} onChange={(date) => setTime(date)} units={['hour', 'minute']} />
87
+
88
+ // Disable specific hours (24-hour values)
89
+ <TimePicker
90
+ value={time}
91
+ onChange={(date) => setTime(date)}
92
+ disabledHours={[0, 1, 2, 3, 4, 5, 6]}
93
+ />
94
+
95
+ // Pass -1 in disabledHours to block the entire AM or PM toggle
96
+ // (DISABLE_CLOCK_MODE_HOUR = -1 disables PM; 12 + -1 disables AM)
97
+ import { DISABLE_CLOCK_MODE_HOUR } from '@synerise/ds-time-picker';
98
+ <TimePicker disabledHours={[DISABLE_CLOCK_MODE_HOUR]} .. />
99
+ ```
100
+
101
+ ## Styling
102
+
103
+ All visual elements use styled-components tokens (no hardcoded colours). Key styled components:
104
+ - `S.Container` — outermost wrapper with `ds-time-picker` class
105
+ - `S.OverlayContainer` — the dropdown panel (`data-testid="tp-overlay-container"`)
106
+ - `S.Unit` / `S.Cell` / `S.CellText` — column and row layout for each time unit
107
+ - `S.UnitSeperator` — colon divider between columns
108
+ - `S.ClearIcon` — styled icon wrapper used for the clear button
109
+
110
+ ## Key dependencies
111
+
112
+ | Package | Role |
113
+ |---------|------|
114
+ | `dayjs` + `dayjs/plugin/customParseFormat` | Date manipulation and display formatting |
115
+ | `lodash.range` | Generates `[0.23]` / `[0.59]` option arrays |
116
+ | `@synerise/ds-dropdown` | Dropdown wrapper |
117
+ | `@synerise/ds-input` | Trigger input field |
118
+ | `@synerise/ds-icon` | Clock and close icons (`ClockM`, `Close3S`) |
119
+ | `@synerise/ds-tooltip` | Wraps the clear icon |
120
+ | `@synerise/ds-scrollbar` | Scroll container inside each `Unit` column |
121
+ | `@synerise/ds-core` `useDataFormat` | Reads locale-aware 12/24-hour clock preference |
122
+ | `react-intl` | i18n strings for placeholder and clear tooltip |
123
+ | `debounce` | Scroll-snap debounce in `Unit.tsx` |
124
+
125
+ ## Implementation notes
126
+
127
+ - **12-hour clock detection:** `use12HourClock` prop overrides, otherwise read from `useDataFormat().is12HoursClock`.
128
+ - **Controlled-only value:** There is no uncontrolled mode. `onChange` is the only way to update the displayed time.
129
+ - **`onChange` fires twice per interaction:** once when a cell is clicked (immediate) and once when the dropdown closes (`onVisibleChange`).
130
+ - **`disabledHours` with AM/PM:** Use sentinel `-1` (`DISABLE_CLOCK_MODE_HOUR`) to disable the entire PM toggle. Use `12` (`HOUR_12`) combined with `-1` to disable the AM toggle.
131
+ - **Scroll snap in `Unit`:** The `Unit` component auto-scrolls to the selected cell and snaps free-scrolling to the nearest 32 px cell boundary via a debounced scroll handler.
132
+ - **Test runner:** Jest (not Vitest) — `jest.config.js` is present at the package root.
133
+ - **`timeFormat` / `use12HourClock`:** Both props are deprecated in favour of `valueFormatOptions` and `DSProvider::dataFormatConfig` respectively.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@synerise/ds-time-picker",
3
- "version": "1.2.40",
3
+ "version": "1.2.42",
4
4
  "description": "TimePicker 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,13 +42,13 @@
41
42
  ],
42
43
  "types": "dist/index.d.ts",
43
44
  "dependencies": {
44
- "@synerise/ds-dropdown": "^1.3.18",
45
- "@synerise/ds-icon": "^1.18.4",
46
- "@synerise/ds-input": "^1.7.12",
47
- "@synerise/ds-popover": "^1.6.1",
48
- "@synerise/ds-scrollbar": "^1.5.1",
49
- "@synerise/ds-tooltip": "^1.5.3",
50
- "@synerise/ds-typography": "^1.1.26",
45
+ "@synerise/ds-dropdown": "^1.3.20",
46
+ "@synerise/ds-icon": "^1.18.5",
47
+ "@synerise/ds-input": "^1.7.13",
48
+ "@synerise/ds-popover": "^1.6.2",
49
+ "@synerise/ds-scrollbar": "^1.5.2",
50
+ "@synerise/ds-tooltip": "^1.5.4",
51
+ "@synerise/ds-typography": "^1.1.27",
51
52
  "dayjs": "^1.8.19",
52
53
  "debounce": "^1.2.0",
53
54
  "lodash.range": "^3.2.0"
@@ -63,5 +64,5 @@
63
64
  "styled-components": "^5.3.3",
64
65
  "vitest": "4"
65
66
  },
66
- "gitHead": "5c90008871be36fb52553a2ed3a633acf5db5b3b"
67
+ "gitHead": "d0a43cc43d8528a36f105aceea52ab470edb71d9"
67
68
  }