@molecule/app-feature-piano-roll-solid 0.0.1-stage → 1.1.0

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 (2) hide show
  1. package/README.md +344 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,351 @@
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-11-21T12:46:32.348Z
7
+ -->
8
+
1
9
  # @molecule/app-feature-piano-roll-solid
2
10
 
3
- MIDI piano roll editor — note grid with vertical piano keys + horizontal time grid + draggable/resizable note rectangles for music-daw
11
+ Solid piano roll — MIDI note-grid editor for music-daw and other DAW-style
12
+ surfaces. Renders a vertical piano keyboard on the left, a horizontal time
13
+ grid on the right, and draggable / resizable note rectangles on top.
14
+
15
+ Solid counterpart of `@molecule/app-feature-piano-roll-react`: the same props
16
+ (React names), the same DOM for the same input, and the same callback calls,
17
+ so an app switches framework by changing only the package name it imports.
18
+
19
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
20
+ > It is written to be read by coding agents as much as by people, and is generated from this
21
+ > package's source — edit `src/index.ts` JSDoc, not this file.
22
+
23
+ ## Quick Start
24
+
25
+ ```tsx
26
+ import { createSignal, For } from 'solid-js'
27
+ import { PianoRoll, type MidiNote } from '@molecule/app-feature-piano-roll-solid'
28
+
29
+ export function Roll() {
30
+ const [notes, setNotes] = createSignal<MidiNote[]>([])
31
+
32
+ return (
33
+ <PianoRoll
34
+ notes={notes()}
35
+ snap="1/16"
36
+ onNoteAdd={(note) => setNotes((all) => [...all, note])}
37
+ onNoteMove={(noteId, startBeat, pitch) =>
38
+ setNotes((all) => all.map((n) => (n.id === noteId ? { ...n, startBeat, pitch } : n)))
39
+ }
40
+ onNoteResize={(noteId, durationBeats) =>
41
+ setNotes((all) => all.map((n) => (n.id === noteId ? { ...n, durationBeats } : n)))
42
+ }
43
+ onNoteDelete={(noteId) => setNotes((all) => all.filter((n) => n.id !== noteId))}
44
+ />
45
+ )
46
+ }
47
+ ```
48
+
49
+ ## Type
50
+
51
+ `feature`
52
+
53
+ ## Installation
54
+
55
+ ```bash
56
+ npm install @molecule/app-feature-piano-roll-solid @molecule/app-solid @molecule/app-ui @molecule/app-ui-solid solid-js
57
+ ```
58
+
59
+ ## API
60
+
61
+ ### Interfaces
62
+
63
+ #### `MidiNote`
64
+
65
+ A single MIDI note rendered on the piano roll. `pitch` is a standard MIDI
66
+ pitch number in the closed interval `[0, 127]` where `60` represents middle C
67
+ (`C4`). `startBeat` is the note's start position on the time grid, and
68
+ `durationBeats` is its length in beats. `id` is a stable identifier used as
69
+ the row key and as the argument passed back to all event handlers.
70
+ `velocity` is an optional MIDI velocity in the closed interval `[0, 127]`
71
+ (defaults to a neutral mid-range).
72
+
73
+ ```typescript
74
+ interface MidiNote {
75
+ /** Stable identifier for the note (used as the row key + handler arg). */
76
+ id: string
77
+ /** MIDI pitch number, `0..127`. `60` is middle C. */
78
+ pitch: number
79
+ /** Start beat on the timeline (>= 0). */
80
+ startBeat: number
81
+ /** Duration in beats (always positive — minimum is enforced). */
82
+ durationBeats: number
83
+ /** Optional MIDI velocity, `0..127`. */
84
+ velocity?: number
85
+ }
86
+ ```
87
+
88
+ #### `PianoRollProps`
89
+
90
+ Props accepted by the {@link PianoRoll} component.
91
+
92
+ ```typescript
93
+ interface PianoRollProps {
94
+ /** MIDI notes rendered on the grid. Order is preserved as-is. */
95
+ notes: MidiNote[]
96
+ /** Horizontal scale: pixels rendered per musical beat. Defaults to `80`. */
97
+ pixelsPerBeat?: number
98
+ /** Vertical row height per pitch in pixels. Defaults to `20`. */
99
+ noteHeight?: number
100
+ /** Lowest visible pitch (top-most row excluded — see `highestPitch`). Defaults to `21` (A0). */
101
+ lowestPitch?: number
102
+ /** Highest visible pitch (top-most row inclusive). Defaults to `108` (C8). */
103
+ highestPitch?: number
104
+ /** Snap resolution applied to clicks, drags, and resizes. Defaults to `'1/16'`. */
105
+ snap?: PianoRollSnap
106
+ /**
107
+ * Total beats rendered in the time grid. When omitted, the grid extends to
108
+ * cover all notes plus a small trailing pad (minimum 16 beats so empty rolls
109
+ * are still usable).
110
+ */
111
+ beatsCount?: number
112
+ /**
113
+ * Called with a freshly-created note when the user paints an empty cell — by
114
+ * clicking it, or via the keyboard cell cursor (arrow keys to move, Enter /
115
+ * Space to paint).
116
+ */
117
+ onNoteAdd?: (note: MidiNote) => void
118
+ /** Called with the updated note when a note is dragged horizontally / vertically. */
119
+ onNoteMove?: (noteId: string, startBeat: number, pitch: number) => void
120
+ /** Called with the updated duration when a note's right-edge handle is dragged. */
121
+ onNoteResize?: (noteId: string, durationBeats: number) => void
122
+ /** Called when the user right-clicks a note. */
123
+ onNoteDelete?: (noteId: string) => void
124
+ /** Extra classes merged onto the root element. */
125
+ className?: string
126
+ }
127
+ ```
128
+
129
+ ### Types
130
+
131
+ #### `PianoRollSnap`
132
+
133
+ Snap resolution for note placement / movement / resize. Each value is a
134
+ fraction of a beat: `'1/16'` is sixteenth-notes (a quarter of a beat), `'1/4'`
135
+ is quarter-notes (one beat), `'1'` snaps to whole beats with no
136
+ sub-divisions, etc.
137
+
138
+ ```typescript
139
+ type PianoRollSnap = '1/16' | '1/8' | '1/4' | '1/2' | '1'
140
+ ```
141
+
142
+ ### Functions
143
+
144
+ #### `PianoRoll(props)`
145
+
146
+ MIDI piano-roll editor. Renders a vertical piano keyboard on the left, a
147
+ horizontal time grid on the right, and draggable / resizable note rectangles
148
+ on top. Click an empty cell to paint a new note, drag a note body to move it
149
+ (snapped), drag the right-edge handle to resize, right-click a note to
150
+ delete it.
151
+
152
+ Keyboard users get the same paint action: focus the grid (Tab), move the cell
153
+ cursor with the arrow keys, and press Enter or Space to paint a new note at
154
+ the cursor cell.
155
+
156
+ React keys each note by its `id` value, so a re-passed or re-ordered array
157
+ keeps the rendered notes per id. Solid's `For` keys by reference, so the
158
+ notes are keyed through stable per-id records: the record for an id is
159
+ created once and reused, while the note's content reads the CURRENT note for
160
+ that id reactively.
161
+
162
+ ```typescript
163
+ function PianoRoll(props: PianoRollProps): JSX.Element
164
+ ```
165
+
166
+ - `props` — Component props (see {@link PianoRollProps}).
167
+
168
+ **Returns:** The rendered piano roll.
169
+
170
+ #### `snapToBeats(snap)`
171
+
172
+ Convert a snap setting to its size in beats.
173
+
174
+ ```typescript
175
+ function snapToBeats(snap: PianoRollSnap): number
176
+ ```
177
+
178
+ - `snap` — Snap resolution.
179
+
180
+ **Returns:** Snap step size in beats.
181
+
182
+ #### `snapBeat(beat, snap)`
183
+
184
+ Snap a beat value to the nearest multiple of the snap step (rounding down).
185
+
186
+ ```typescript
187
+ function snapBeat(beat: number, snap: PianoRollSnap): number
188
+ ```
189
+
190
+ - `beat` — Raw beat value (may be fractional).
191
+ - `snap` — Snap resolution.
192
+
193
+ **Returns:** The floored snapped beat (>= 0).
194
+
195
+ #### `snapBeatRound(beat, snap)`
196
+
197
+ Round a beat value to the nearest snap step.
198
+
199
+ ```typescript
200
+ function snapBeatRound(beat: number, snap: PianoRollSnap): number
201
+ ```
202
+
203
+ - `beat` — Raw beat value (may be fractional).
204
+ - `snap` — Snap resolution.
205
+
206
+ **Returns:** The rounded snapped beat (>= 0).
207
+
208
+ #### `pixelsToBeats(pixels, pixelsPerBeat)`
4
209
 
210
+ Convert a pixel offset into beats given the horizontal scale.
211
+
212
+ ```typescript
213
+ function pixelsToBeats(pixels: number, pixelsPerBeat: number): number
214
+ ```
215
+
216
+ - `pixels` — Offset in pixels.
217
+ - `pixelsPerBeat` — Horizontal scale.
218
+
219
+ **Returns:** Beats represented by the offset (may be negative).
220
+
221
+ #### `beatsToPixels(beats, pixelsPerBeat)`
222
+
223
+ Convert a beat value into pixels given the horizontal scale.
224
+
225
+ ```typescript
226
+ function beatsToPixels(beats: number, pixelsPerBeat: number): number
227
+ ```
228
+
229
+ - `beats` — Beat value.
230
+ - `pixelsPerBeat` — Horizontal scale.
231
+
232
+ **Returns:** Pixel offset.
233
+
234
+ #### `yToPitch(y, noteHeight, highestPitch, lowestPitch)`
235
+
236
+ Convert a vertical pixel offset into a MIDI pitch. Higher pitches sit at the
237
+ top, so `y = 0` maps to `highestPitch`.
238
+
239
+ ```typescript
240
+ function yToPitch(y: number, noteHeight: number, highestPitch: number, lowestPitch: number): number
241
+ ```
242
+
243
+ - `y` — Vertical pixel offset from the top of the grid.
244
+ - `noteHeight` — Row height per pitch.
245
+ - `highestPitch` — Top-most pitch in the visible range.
246
+ - `lowestPitch` — Bottom-most pitch in the visible range.
247
+
248
+ **Returns:** A MIDI pitch clamped into `[lowestPitch, highestPitch]`.
249
+
250
+ #### `pitchToY(pitch, noteHeight, highestPitch)`
251
+
252
+ Convert a MIDI pitch into the vertical pixel offset of its row.
253
+
254
+ ```typescript
255
+ function pitchToY(pitch: number, noteHeight: number, highestPitch: number): number
256
+ ```
257
+
258
+ - `pitch` — MIDI pitch number.
259
+ - `noteHeight` — Row height per pitch.
260
+ - `highestPitch` — Top-most pitch in the visible range.
261
+
262
+ **Returns:** Vertical pixel offset for the pitch's row.
263
+
264
+ #### `isBlackKey(pitch)`
265
+
266
+ Determine whether a MIDI pitch corresponds to a black key on a piano
267
+ keyboard.
268
+
269
+ ```typescript
270
+ function isBlackKey(pitch: number): boolean
271
+ ```
272
+
273
+ - `pitch` — MIDI pitch number.
274
+
275
+ **Returns:** `true` if the pitch is a black key.
276
+
277
+ #### `pitchLabel(pitch)`
278
+
279
+ Format a MIDI pitch as a scientific-pitch-notation label.
280
+
281
+ ```typescript
282
+ function pitchLabel(pitch: number): string
283
+ ```
284
+
285
+ - `pitch` — MIDI pitch number.
286
+
287
+ **Returns:** Formatted label.
288
+
289
+ ### Constants
290
+
291
+ #### `PIANO_KEYS_WIDTH_PX`
292
+
293
+ Pixel width of the leading piano-keys column.
294
+
295
+ ```typescript
296
+ const PIANO_KEYS_WIDTH_PX: 56
297
+ ```
298
+
299
+ #### `MIN_NOTE_DURATION_BEATS`
300
+
301
+ Minimum note duration in beats — notes can't be resized below this.
302
+
303
+ ```typescript
304
+ const MIN_NOTE_DURATION_BEATS: number
5
305
  ```
6
- npm install @molecule/app-feature-piano-roll-solid
306
+
307
+ #### `DRAG_DISTANCE_THRESHOLD_PX`
308
+
309
+ Pointer-distance threshold (px) before a press becomes a drag.
310
+
311
+ ```typescript
312
+ const DRAG_DISTANCE_THRESHOLD_PX: 3
313
+ ```
314
+
315
+ #### `DEFAULT_NOTE_VELOCITY`
316
+
317
+ Default MIDI velocity assigned to freshly-painted notes.
318
+
319
+ ```typescript
320
+ const DEFAULT_NOTE_VELOCITY: 96
7
321
  ```
8
322
 
9
- Part of the [Molecule](https://www.molecule.dev) package fleet. This page carries the manifest summary; the full generated documentation ships with the package's first committed version.
323
+ ## Injection Notes
324
+
325
+ ### Requirements
326
+
327
+ Peer dependencies:
328
+
329
+ - `@molecule/app-solid` ^3.5.0
330
+ - `@molecule/app-ui` ^1.0.1
331
+ - `@molecule/app-ui-solid` ^1.1.0
332
+ - `solid-js` ^1.8.0
333
+
334
+ ### Runtime Dependencies
335
+
336
+ - `@molecule/app-solid`
337
+ - `@molecule/app-ui`
338
+ - `@molecule/app-ui-solid`
339
+ - `solid-js`
340
+
341
+ - Requires a bonded ClassMap (`cm.cn`, `cm.cursorPointer`, …) — rendering
342
+ throws otherwise. No router dependency.
343
+ - Every visible string comes from `useTranslation()` (`pianoRoll.aria.*`)
344
+ via the companion `@molecule/app-locales-feature-piano-roll` locale bond,
345
+ so a locale switch re-renders it.
346
+ - The grid is focusable and paints from the keyboard (arrow keys move the
347
+ cell cursor, Enter / Space paints), exactly as React's.
348
+
349
+ ## Translations
10
350
 
11
- License: Apache-2.0
351
+ Translation strings are provided by `@molecule/app-locales-feature-piano-roll`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-feature-piano-roll-solid",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "MIDI piano roll editor — note grid with vertical piano keys + horizontal time grid + draggable/resizable note rectangles for music-daw",
5
5
  "homepage": "https://www.molecule.dev/packages/app-feature-piano-roll-solid",
6
6
  "type": "module",
@@ -55,9 +55,9 @@
55
55
  "@molecule/app-framework-conformance": "0.0.0",
56
56
  "@molecule/app-i18n": "1.2.2",
57
57
  "@molecule/app-icons": "1.0.4",
58
- "@molecule/app-solid": "3.7.2",
59
- "@molecule/app-ui": "1.4.0",
60
- "@molecule/app-ui-solid": "1.1.5",
58
+ "@molecule/app-solid": "3.9.0",
59
+ "@molecule/app-ui": "1.5.0",
60
+ "@molecule/app-ui-solid": "1.2.1",
61
61
  "@types/node": "26.6.5",
62
62
  "jsdom": "30.1.3",
63
63
  "solid-js": "1.9.17",