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