@synerise/ds-condition 1.6.42 → 1.6.44

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 +185 -0
  3. package/package.json +16 -15
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.6.44](https://github.com/Synerise/synerise-design/compare/@synerise/ds-condition@1.6.43...@synerise/ds-condition@1.6.44) (2026-07-23)
7
+
8
+ **Note:** Version bump only for package @synerise/ds-condition
9
+
10
+ ## [1.6.43](https://github.com/Synerise/synerise-design/compare/@synerise/ds-condition@1.6.42...@synerise/ds-condition@1.6.43) (2026-07-16)
11
+
12
+ **Note:** Version bump only for package @synerise/ds-condition
13
+
6
14
  ## [1.6.42](https://github.com/Synerise/synerise-design/compare/@synerise/ds-condition@1.6.41...@synerise/ds-condition@1.6.42) (2026-07-09)
7
15
 
8
16
  **Note:** Version bump only for package @synerise/ds-condition
package/CLAUDE.md ADDED
@@ -0,0 +1,185 @@
1
+ # Condition (`@synerise/ds-condition`)
2
+
3
+ > Multi-step condition builder that composes Subject/Context selectors, parameter/operator/factor selectors, and drag-and-drop step reordering into a single controlled component.
4
+
5
+ ## Package structure
6
+
7
+ ```
8
+ src/
9
+ Condition.tsx — main component, manages active-field state machine
10
+ Condition.types.ts — all prop interfaces and shared types
11
+ Condition.style.ts — styled-components for the whole tree
12
+ Condition.spec.tsx — unit tests (in __specs__/)
13
+ constants.ts — field-type string constants and DEFAULT_INPUT_PROPS
14
+ index.ts — public exports
15
+ hooks/
16
+ useTranslations.ts — react-intl hook, merges defaults with texts prop
17
+ ConditionStep/
18
+ ConditionStep.tsx — per-step wrapper (subject/context, header, rows)
19
+ ConditionStep.types.ts
20
+ StepHeader/ — drag handle + inline-edit step name + CRUD actions
21
+ StepName/ — read-only "Step N · name" label (used in drag overlay)
22
+ ConditionRow/ — single parameter → operator → factor row
23
+ AddCondition/ — "Add condition" button with disabled/error state
24
+ EmptyCondition/ — placeholder shown before subject/context is selected
25
+ ```
26
+
27
+ ## Public exports
28
+
29
+ ### `Condition` (default export)
30
+
31
+ Primary component. No `forwardRef`.
32
+
33
+ | Prop | Type | Default | Description |
34
+ |------|------|---------|-------------|
35
+ | `steps` | `ConditionStep[]` | — | **Required.** Array of step data. |
36
+ | `minConditionsLength` | `number` | `1` | **Required.** Minimum conditions per step (hides remove button at this count). |
37
+ | `onChangeContext` | `(stepId, value) => void` | — | **Required.** Called when context selector changes. |
38
+ | `onChangeSubject` | `(stepId, value) => void` | — | **Required.** Called when subject selector changes. |
39
+ | `onChangeParameter` | `(stepId, conditionId, value) => void` | — | **Required.** |
40
+ | `onChangeOperator` | `(stepId, conditionId, value) => void` | — | **Required.** |
41
+ | `onChangeFactorValue` | `(stepId, conditionId, value) => void` | — | **Required.** |
42
+ | `onChangeFactorType` | `(stepId, conditionId, value) => void` | — | **Required.** |
43
+ | `maxConditionsLength` | `number \| undefined` | `undefined` | Hides "Add condition" button when reached. |
44
+ | `addCondition` | `(stepId) => string \| void` | — | Returns new condition id; used to auto-focus it. |
45
+ | `removeCondition` | `(stepId, conditionRowId) => void` | — | |
46
+ | `addStep` | `() => ReactText \| void` | — | Returns new step id; used to auto-focus it. |
47
+ | `renderAddStep` | `() => ReactNode` | — | Replaces the default "Add step" button. Hidden in `readOnly` mode. |
48
+ | `removeStep` | `(stepId) => void` | — | |
49
+ | `duplicateStep` | `(stepId) => void` | — | |
50
+ | `onChangeOrder` | `(newOrder: ConditionStep[]) => void` | — | Enables drag-to-reorder when provided AND `steps.length > 1`. |
51
+ | `onUpdateStepName` | `(stepId, value) => void` | — | Shows editable step name header when provided. |
52
+ | `onChangeActionAttribute` | `(stepId, value) => void` | — | |
53
+ | `onDeactivate` | `(stepId, conditionId) => void` | — | Fires when active field is blurred/cleared. |
54
+ | `texts` | `Partial<ConditionTexts>` | see `useTranslations` | Override any label. Uses `react-intl` defaults. |
55
+ | `autoClearCondition` | `boolean` | `false` | When `true`, changing subject/context/parameter clears downstream values. |
56
+ | `readOnly` | `boolean` | `false` | Disables all editing; hides add/remove/duplicate controls. |
57
+ | `singleStepCondition` | `boolean` | — | Hides step CRUD and drag handle (single-step mode). |
58
+ | `showActionAttribute` | `boolean` | — | Renders action-attribute selector after subject/context selection. |
59
+ | `showEmptyConditionPlaceholder` | `boolean` | `false` | Shows `EmptyCondition` placeholder when no subject/context chosen. |
60
+ | `showSuffix` | `boolean` | — | Renders `conditionSuffix` text ("and") between condition rows. |
61
+ | `hoverDisabled` | `boolean` | — | Disables hover highlight on steps. Also set automatically on non-active steps. |
62
+ | `autoOpenedComponent` | `'subject' \| 'operator' \| 'factor' \| 'parameter' \| 'context'` | `''` | Which selector to auto-open on mount (only if operator has no value). |
63
+ | `type` | `'attribute' \| 'event'` | — | Passed through to sub-components. |
64
+ | `inputProps` | `Partial<InputProps>` | `{ autoResize: { minWidth: '173px', stretchToFit: true } }` | Merged with `DEFAULT_INPUT_PROPS` for factor text inputs. |
65
+ | `factorValueExtraProps` | `FactorsProps['factorValueExtraProps']` | — | Extra props forwarded to all factor value components. |
66
+ | `getPopupContainerOverride` | `(trigger) => HTMLElement` | — | Overrides popup container for all nested dropdowns/tooltips. |
67
+ | `contextSelectorComponent` | `ComponentType<CustomContextSelectorProps>` | — | Replaces default context selector. |
68
+ | `parameterSelectorComponent` | `ComponentType<FactorValueComponentProps>` | — | Replaces default parameter value component. |
69
+ | `factorParameterSelectorComponent` | `ComponentType<FactorValueComponentProps>` | — | Replaces default factor parameter selector. |
70
+ | `actionAttributeParameterSelectorComponent` | `ComponentType<FactorValueComponentProps>` | — | Replaces default action-attribute parameter selector. |
71
+
72
+ ### `ConditionStep` (type)
73
+
74
+ Shape of each element in `steps`:
75
+
76
+ | Field | Type | Description |
77
+ |-------|------|-------------|
78
+ | `id` | `ReactText` | Unique step id. |
79
+ | `conditions` | `StepConditions[]` | At least one required. |
80
+ | `stepName` | `string?` | Display name; editable when `onUpdateStepName` is provided. |
81
+ | `subject` | `Omit<SubjectProps, 'onSelectItem'>?` | Renders a Subject selector if provided (mutually exclusive with `context`). |
82
+ | `context` | `Omit<ContextProps, 'onSelectItem'>?` | Renders a Context selector if provided. |
83
+ | `actionAttribute` | `Omit<FactorsProps, 'onChangeValue' \| 'selectedFactorType' \| 'defaultFactorType'>?` | Optional action-attribute selector; shown when `showActionAttribute` is true. |
84
+ | `addConditionErrorText` | `ReactNode?` | Error shown below the "Add condition" button. |
85
+
86
+ ### `StepConditions` (type)
87
+
88
+ Shape of each element in `ConditionStep.conditions`:
89
+
90
+ | Field | Type | Description |
91
+ |-------|------|-------------|
92
+ | `id` | `ReactText` | Unique condition id. |
93
+ | `parameter` | `Omit<FactorsProps, 'onChangeValue'>?` | Rendered when provided. |
94
+ | `operator` | `Omit<OperatorsProps, 'onChange'>?` | Rendered when `parameter.value` is set (or when `parameter` is absent). |
95
+ | `factor` | `Omit<FactorsProps, 'onChangeValue' \| 'setSelectedFactorType'> & { withCustomFactor?: ReactNode }?` | Rendered only when `operator.value` is set. |
96
+
97
+ ### `ConditionTexts` (type)
98
+
99
+ All keys are `string | ReactNode`. Defaults provided via `react-intl`:
100
+
101
+ | Key | Default |
102
+ |-----|---------|
103
+ | `stepNamePrefix` | `'Step'` |
104
+ | `stepNamePlaceholder` | `'Step name'` |
105
+ | `emptyConditionLabel` | `'Choose event first'` |
106
+ | `removeConditionRowTooltip` | `'Delete'` |
107
+ | `addConditionRowButton` | `'Add condition'` |
108
+ | `addFirstConditionRowButton` | `'Add condition'` |
109
+ | `addStep` | `'Add step'` |
110
+ | `dropLabel` | `'Drop me here'` |
111
+ | `moveTooltip` | `'Move'` |
112
+ | `duplicateTooltip` | `'Duplicate'` |
113
+ | `removeTooltip` | `'Delete'` |
114
+ | `conditionSuffix` | `'and'` |
115
+
116
+ ### `ConditionStepCrudActions` (type)
117
+
118
+ `{ removeStep?, duplicateStep? }` — intersected into `ConditionProps`.
119
+
120
+ ## Usage patterns
121
+
122
+ ```tsx
123
+ import Condition from '@synerise/ds-condition';
124
+
125
+ // Minimal controlled usage
126
+ <Condition
127
+ steps={steps}
128
+ minConditionsLength={1}
129
+ onChangeSubject={(stepId, value) => {}}
130
+ onChangeContext={(stepId, value) => {}}
131
+ onChangeParameter={(stepId, conditionId, value) => {}}
132
+ onChangeOperator={(stepId, conditionId, value) => {}}
133
+ onChangeFactorValue={(stepId, conditionId, value) => {}}
134
+ onChangeFactorType={(stepId, conditionId, value) => {}}
135
+ />
136
+
137
+ // With full step management
138
+ <Condition
139
+ {...baseProps}
140
+ addStep={() => newId}
141
+ removeStep={(id) => {}}
142
+ duplicateStep={(id) => {}}
143
+ addCondition={(stepId) => newConditionId}
144
+ removeCondition={(stepId, condId) => {}}
145
+ onChangeOrder={(ordered) => setSteps(ordered)}
146
+ onUpdateStepName={(stepId, name) => {}}
147
+ autoClearCondition
148
+ texts={{ addStep: 'New step', addConditionRowButton: 'and where' }}
149
+ />
150
+ ```
151
+
152
+ ## Selector appearance rules
153
+
154
+ Within each `ConditionRow`:
155
+ 1. **Parameter** appears when `parameter` prop is provided.
156
+ 2. **Operator** appears when `operator` is provided AND (`parameter` is absent OR `parameter.value` is set).
157
+ 3. **Factor** appears only when `operator.value` is set.
158
+
159
+ ## Custom hooks
160
+
161
+ ### `useTranslations`
162
+
163
+ Merges the `texts` prop with react-intl defaults. Requires `IntlProvider` in the tree. Returns a complete `ConditionTexts` object — never partial.
164
+
165
+ ## Key dependencies
166
+
167
+ - `@synerise/ds-sortable` — `SortableContainer` + `DragOverlay` for step reordering (dnd-kit based)
168
+ - `@synerise/ds-factors` — parameter and factor value selectors
169
+ - `@synerise/ds-operators` — operator dropdown
170
+ - `@synerise/ds-subject` — subject selector
171
+ - `@synerise/ds-context-selector` — context selector
172
+ - `@synerise/ds-cruds` — duplicate/delete action buttons in StepHeader
173
+ - `@synerise/ds-inline-edit` — editable step name with debounce
174
+ - `react-intl` — i18n for default labels
175
+
176
+ ## Implementation notes
177
+
178
+ - **Controlled-only** — the component holds no data state. All step and condition data lives in the parent. The component only manages UI state: which step/condition/field is currently active (`currentStepId`, `currentConditionId`, `currentField`).
179
+ - **Active-field state machine** — selecting a subject auto-advances focus to `parameter` (or `actionAttribute` if `showActionAttribute`). Selecting a parameter advances to `operator`. Selecting an operator advances to `factor`. This is implemented via `setCurrentField` calls in `selectSubject`, `selectContext`, `selectParameter`, `selectOperator`.
180
+ - **Drag is only enabled** when both `onChangeOrder` is provided AND `steps.length > 1`. The drag handle and `SortableContainer` are always rendered; the handle just has no effect without these.
181
+ - **`autoClearCondition`** — when `true`, changing subject/context also fires `onChangeParameter`, `onChangeOperator`, `onChangeFactorValue` with `undefined` for all existing conditions, and removes all conditions beyond the first. This clears downstream values but the parent must still handle the callbacks to update its state.
182
+ - **`hoverDisabled`** is also set automatically on steps that are not the currently active step (`currentStepId !== step.id`), creating a "focus" effect.
183
+ - **`renderAddStep`** is hidden in `readOnly` mode; `addStep` button is also skipped when `addStep` prop is absent.
184
+ - **`data-popup-container`** attribute is on the root `S.Condition` element — used as the default popup container by nested dropdowns.
185
+ - **`IntlProvider` required** — `useTranslations` calls `useIntl()`. If the app does not wrap with `IntlProvider`, this will throw. Provide `texts` prop with all keys as a workaround if needed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@synerise/ds-condition",
3
- "version": "1.6.42",
3
+ "version": "1.6.44",
4
4
  "description": "Condition 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,19 +42,19 @@
41
42
  ],
42
43
  "types": "dist/index.d.ts",
43
44
  "dependencies": {
44
- "@synerise/ds-button": "^1.5.33",
45
- "@synerise/ds-context-selector": "^1.3.42",
46
- "@synerise/ds-cruds": "^1.1.15",
47
- "@synerise/ds-factors": "^1.12.9",
48
- "@synerise/ds-icon": "^1.18.4",
49
- "@synerise/ds-inline-edit": "^1.1.46",
50
- "@synerise/ds-input": "^1.7.12",
51
- "@synerise/ds-operators": "^1.1.44",
52
- "@synerise/ds-sortable": "^1.3.20",
53
- "@synerise/ds-subject": "^1.1.42",
54
- "@synerise/ds-tooltip": "^1.5.3",
55
- "@synerise/ds-typography": "^1.1.26",
56
- "@synerise/ds-utils": "^1.10.1",
45
+ "@synerise/ds-button": "^1.5.35",
46
+ "@synerise/ds-context-selector": "^1.3.44",
47
+ "@synerise/ds-cruds": "^1.1.16",
48
+ "@synerise/ds-factors": "^1.12.11",
49
+ "@synerise/ds-icon": "^1.18.5",
50
+ "@synerise/ds-inline-edit": "^1.1.48",
51
+ "@synerise/ds-input": "^1.7.13",
52
+ "@synerise/ds-operators": "^1.1.46",
53
+ "@synerise/ds-sortable": "^1.3.21",
54
+ "@synerise/ds-subject": "^1.1.44",
55
+ "@synerise/ds-tooltip": "^1.5.4",
56
+ "@synerise/ds-typography": "^1.1.27",
57
+ "@synerise/ds-utils": "^1.10.2",
57
58
  "lodash.debounce": "^4.0.8"
58
59
  },
59
60
  "devDependencies": {
@@ -67,5 +68,5 @@
67
68
  "react-intl": ">=3.12.0 <= 6.8",
68
69
  "styled-components": "^5.3.3"
69
70
  },
70
- "gitHead": "5c90008871be36fb52553a2ed3a633acf5db5b3b"
71
+ "gitHead": "d0a43cc43d8528a36f105aceea52ab470edb71d9"
71
72
  }