@molecule/app-adjustment-slider-react 1.0.0 → 1.0.2
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.
- package/README.md +238 -0
- package/package.json +15 -8
package/README.md
ADDED
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-08-04T01:49:53.072Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
9
|
+
# @molecule/app-adjustment-slider-react
|
|
10
|
+
|
|
11
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
12
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
13
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
14
|
+
|
|
15
|
+
Adjustment slider feature for molecule.dev.
|
|
16
|
+
|
|
17
|
+
Bipolar (zero-center) numeric slider tuned for photo-editor / DAW /
|
|
18
|
+
animation parameter controls (brightness, contrast, saturation, exposure,
|
|
19
|
+
gain, pan, etc.). Pairs well with `@molecule/app-feature-image-canvas-react`.
|
|
20
|
+
|
|
21
|
+
## Quick Start
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
import { AdjustmentSlider } from '@molecule/app-adjustment-slider-react'
|
|
25
|
+
|
|
26
|
+
;<AdjustmentSlider
|
|
27
|
+
label="Exposure"
|
|
28
|
+
value={exposure}
|
|
29
|
+
onChange={setExposure}
|
|
30
|
+
min={-100}
|
|
31
|
+
max={100}
|
|
32
|
+
step={1}
|
|
33
|
+
bipolar
|
|
34
|
+
unit="%"
|
|
35
|
+
/>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Type
|
|
39
|
+
|
|
40
|
+
`feature`
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npm install @molecule/app-adjustment-slider-react @molecule/app-react @molecule/app-ui react
|
|
46
|
+
npm install -D @types/react
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## API
|
|
50
|
+
|
|
51
|
+
### Interfaces
|
|
52
|
+
|
|
53
|
+
#### `AdjustmentSliderProps`
|
|
54
|
+
|
|
55
|
+
Public props for `<AdjustmentSlider>`.
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
interface AdjustmentSliderProps {
|
|
59
|
+
/** Visible label (rendered to the left of the slider). */
|
|
60
|
+
label: string
|
|
61
|
+
/** Current numeric value. */
|
|
62
|
+
value: number
|
|
63
|
+
/** Called whenever the slider value changes. */
|
|
64
|
+
onChange: (value: number) => void
|
|
65
|
+
/** Lower bound. Defaults to `-100`. */
|
|
66
|
+
min?: number
|
|
67
|
+
/** Upper bound. Defaults to `100`. */
|
|
68
|
+
max?: number
|
|
69
|
+
/** Step increment. Defaults to `1`. */
|
|
70
|
+
step?: number
|
|
71
|
+
/**
|
|
72
|
+
* When `true` (default), the slider is bipolar with a center mark at zero
|
|
73
|
+
* and double-click / Reset returns the value to `0`. When `false`, the
|
|
74
|
+
* slider is unipolar (a normal range slider) and double-click resets to
|
|
75
|
+
* `min`.
|
|
76
|
+
*/
|
|
77
|
+
bipolar?: boolean
|
|
78
|
+
/** Optional unit suffix (e.g. `'%'`, `'dB'`) appended to the default formatter. */
|
|
79
|
+
unit?: string
|
|
80
|
+
/**
|
|
81
|
+
* Optional formatter overriding the default `value + (unit || '')` display.
|
|
82
|
+
* Useful for rendering e.g. `+12` (signed) or `1.4 EV`.
|
|
83
|
+
*/
|
|
84
|
+
format?: AdjustmentSliderFormatter
|
|
85
|
+
/**
|
|
86
|
+
* Optional reset handler. When provided, double-clicking the slider OR
|
|
87
|
+
* pressing the visual Reset button calls this instead of resetting to
|
|
88
|
+
* the default reset value.
|
|
89
|
+
*/
|
|
90
|
+
onReset?: () => void
|
|
91
|
+
/** Optional extra class names appended to the outer container. */
|
|
92
|
+
className?: string
|
|
93
|
+
/** Optional `data-mol-id` for AI-agent / E2E targeting. */
|
|
94
|
+
dataMolId?: string
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Types
|
|
99
|
+
|
|
100
|
+
#### `AdjustmentSliderFormatter`
|
|
101
|
+
|
|
102
|
+
Function signature used to format the rendered numeric value.
|
|
103
|
+
|
|
104
|
+
```typescript
|
|
105
|
+
type AdjustmentSliderFormatter = (value: number) => string
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Functions
|
|
109
|
+
|
|
110
|
+
#### `AdjustmentSlider(props)`
|
|
111
|
+
|
|
112
|
+
Bipolar (zero-center) adjustment slider — a labelled `<input type="range">`
|
|
113
|
+
tuned for photo-editor / DAW / animation parameter controls (brightness,
|
|
114
|
+
contrast, saturation, exposure, gain, pan, etc.).
|
|
115
|
+
|
|
116
|
+
Behaviour:
|
|
117
|
+
|
|
118
|
+
- When `bipolar` is `true` (default), a center mark is rendered at zero
|
|
119
|
+
and the reset target is `0`. When `false`, the slider is unipolar and
|
|
120
|
+
the reset target is `min`.
|
|
121
|
+
- Double-clicking the input resets the value (calling `onReset` if
|
|
122
|
+
provided, otherwise emitting `defaultResetValue(min, bipolar)` via
|
|
123
|
+
`onChange`).
|
|
124
|
+
- Up/Right arrows nudge by `step`; Down/Left arrows nudge by `-step`.
|
|
125
|
+
Holding Shift multiplies the nudge by 10.
|
|
126
|
+
- The numeric value display is formatted via `format` if supplied,
|
|
127
|
+
otherwise via `value + (unit || '')`.
|
|
128
|
+
|
|
129
|
+
```typescript
|
|
130
|
+
function AdjustmentSlider({
|
|
131
|
+
label,
|
|
132
|
+
value,
|
|
133
|
+
onChange,
|
|
134
|
+
min = -100,
|
|
135
|
+
max = 100,
|
|
136
|
+
step = 1,
|
|
137
|
+
bipolar = true,
|
|
138
|
+
unit,
|
|
139
|
+
format,
|
|
140
|
+
onReset,
|
|
141
|
+
className,
|
|
142
|
+
dataMolId,
|
|
143
|
+
}: AdjustmentSliderProps): ReactElement<unknown, string | JSXElementConstructor<any>>
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
- `props` — Component props.
|
|
147
|
+
- `props.label` — Visible control label.
|
|
148
|
+
- `props.value` — Current numeric value.
|
|
149
|
+
- `props.onChange` — Called whenever the value changes.
|
|
150
|
+
- `props.min` — Lower bound (default `-100`).
|
|
151
|
+
- `props.max` — Upper bound (default `100`).
|
|
152
|
+
- `props.step` — Step increment (default `1`).
|
|
153
|
+
- `props.bipolar` — Bipolar / zero-center mode (default `true`).
|
|
154
|
+
- `props.unit` — Optional unit suffix appended to the default formatter.
|
|
155
|
+
- `props.format` — Optional custom value formatter.
|
|
156
|
+
- `props.onReset` — Optional reset handler (overrides default reset).
|
|
157
|
+
- `props.className` — Optional extra classes for the outer container.
|
|
158
|
+
- `props.dataMolId` — Optional `data-mol-id` for the outer container.
|
|
159
|
+
|
|
160
|
+
**Returns:** The rendered adjustment slider.
|
|
161
|
+
|
|
162
|
+
#### `clampStep(value, min, max, step)`
|
|
163
|
+
|
|
164
|
+
Clamp a numeric value to the inclusive `[min, max]` range, snapping to the
|
|
165
|
+
nearest multiple of `step` measured from `min`. Does not assume `min === 0`
|
|
166
|
+
(so bipolar `[-100, 100]` works correctly with non-integer steps).
|
|
167
|
+
|
|
168
|
+
```typescript
|
|
169
|
+
function clampStep(value: number, min: number, max: number, step: number): number
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
- `value` — The raw value to normalise.
|
|
173
|
+
- `min` — Inclusive lower bound.
|
|
174
|
+
- `max` — Inclusive upper bound.
|
|
175
|
+
- `step` — Step increment (must be > 0).
|
|
176
|
+
|
|
177
|
+
**Returns:** The clamped + step-snapped value.
|
|
178
|
+
|
|
179
|
+
#### `defaultFormatter(unit)`
|
|
180
|
+
|
|
181
|
+
Build the default value formatter — appends an optional unit suffix.
|
|
182
|
+
|
|
183
|
+
```typescript
|
|
184
|
+
function defaultFormatter(unit?: string): AdjustmentSliderFormatter
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
- `unit` — Optional unit string (e.g. `'%'`).
|
|
188
|
+
|
|
189
|
+
**Returns:** A formatter producing `"<value><unit>"`.
|
|
190
|
+
|
|
191
|
+
#### `defaultResetValue(min, bipolar)`
|
|
192
|
+
|
|
193
|
+
Compute the value the slider should reset to when double-clicked.
|
|
194
|
+
|
|
195
|
+
```typescript
|
|
196
|
+
function defaultResetValue(min: number, bipolar: boolean): number
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
- `min` — Inclusive lower bound.
|
|
200
|
+
- `bipolar` — Whether the slider is in bipolar (zero-center) mode.
|
|
201
|
+
|
|
202
|
+
**Returns:** `0` for bipolar sliders, `min` otherwise.
|
|
203
|
+
|
|
204
|
+
#### `keyboardNudge(step, shift)`
|
|
205
|
+
|
|
206
|
+
Compute the keyboard nudge step for arrow keys.
|
|
207
|
+
|
|
208
|
+
Plain arrow → `step`. Shift-modifier → `step * 10` so users can move in
|
|
209
|
+
coarser increments. Always at least `step`.
|
|
210
|
+
|
|
211
|
+
```typescript
|
|
212
|
+
function keyboardNudge(step: number, shift: boolean): number
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
- `step` — The base step increment.
|
|
216
|
+
- `shift` — Whether the Shift modifier is held.
|
|
217
|
+
|
|
218
|
+
**Returns:** The effective per-keypress delta.
|
|
219
|
+
|
|
220
|
+
## Injection Notes
|
|
221
|
+
|
|
222
|
+
### Requirements
|
|
223
|
+
|
|
224
|
+
Peer dependencies:
|
|
225
|
+
|
|
226
|
+
- `@molecule/app-react` ^1.0.1
|
|
227
|
+
- `@molecule/app-ui` ^1.0.1
|
|
228
|
+
- `react` ^18.0.0 || ^19.0.0
|
|
229
|
+
|
|
230
|
+
### Runtime Dependencies
|
|
231
|
+
|
|
232
|
+
- `@molecule/app-react`
|
|
233
|
+
- `@molecule/app-ui`
|
|
234
|
+
- `react`
|
|
235
|
+
|
|
236
|
+
## Translations
|
|
237
|
+
|
|
238
|
+
Translation strings are provided by `@molecule/app-locales-adjustment-slider`.
|
package/package.json
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/app-adjustment-slider-react",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.2",
|
|
4
4
|
"description": "Bipolar (zero-center) adjustment slider for photo-editor / DAW / animation parameters (brightness, exposure, gain, etc.) with double-click reset and arrow-key nudging",
|
|
5
|
+
"homepage": "https://www.molecule.dev/packages/app-adjustment-slider-react",
|
|
5
6
|
"type": "module",
|
|
6
7
|
"main": "dist/index.js",
|
|
7
8
|
"types": "dist/index.d.ts",
|
|
@@ -17,7 +18,8 @@
|
|
|
17
18
|
}
|
|
18
19
|
},
|
|
19
20
|
"files": [
|
|
20
|
-
"dist"
|
|
21
|
+
"dist",
|
|
22
|
+
"README.md"
|
|
21
23
|
],
|
|
22
24
|
"keywords": [
|
|
23
25
|
"molecule",
|
|
@@ -28,15 +30,20 @@
|
|
|
28
30
|
"react"
|
|
29
31
|
],
|
|
30
32
|
"license": "Apache-2.0",
|
|
33
|
+
"repository": {
|
|
34
|
+
"type": "git",
|
|
35
|
+
"url": "https://github.com/molecule-dev/molecule.git",
|
|
36
|
+
"directory": "packages/app/features/adjustment-slider-react"
|
|
37
|
+
},
|
|
31
38
|
"peerDependencies": {
|
|
32
|
-
"@molecule/app-react": "^1.0.
|
|
33
|
-
"@molecule/app-ui": "^1.0.
|
|
39
|
+
"@molecule/app-react": "^1.0.1",
|
|
40
|
+
"@molecule/app-ui": "^1.0.1",
|
|
34
41
|
"react": "^18.0.0 || ^19.0.0"
|
|
35
42
|
},
|
|
36
43
|
"devDependencies": {
|
|
37
|
-
"@molecule/app-i18n": "1.0.
|
|
38
|
-
"@molecule/app-react": "1.
|
|
39
|
-
"@molecule/app-ui": "1.
|
|
44
|
+
"@molecule/app-i18n": "1.0.2",
|
|
45
|
+
"@molecule/app-react": "1.5.1",
|
|
46
|
+
"@molecule/app-ui": "1.1.1",
|
|
40
47
|
"@testing-library/react": "16.3.2",
|
|
41
48
|
"@types/node": "26.1.2",
|
|
42
49
|
"@types/react": "19.2.17",
|
|
@@ -44,6 +51,6 @@
|
|
|
44
51
|
"react": "19.2.8",
|
|
45
52
|
"react-dom": "19.2.8",
|
|
46
53
|
"typescript": "6.0.3",
|
|
47
|
-
"vitest": "4.1.
|
|
54
|
+
"vitest": "4.1.11"
|
|
48
55
|
}
|
|
49
56
|
}
|