@renko_1055/slidev-addon-studio 0.0.0-stage → 0.3.1-renko.1

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 (79) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +481 -2
  3. package/client/actions.ts +173 -0
  4. package/client/blocks.ts +85 -0
  5. package/client/composables/useCatalog.ts +61 -0
  6. package/client/composables/useDeckApi.ts +70 -0
  7. package/client/composables/useDeckPaint.ts +32 -0
  8. package/client/composables/useDomEvent.ts +20 -0
  9. package/client/composables/useSelection.ts +506 -0
  10. package/client/composables/useSlideCanvas.ts +142 -0
  11. package/client/composables/useSlideSource.ts +165 -0
  12. package/client/composables/useSnapping.ts +137 -0
  13. package/client/composables/useTransformGizmo.ts +458 -0
  14. package/client/context.ts +59 -0
  15. package/client/dom.ts +33 -0
  16. package/client/i18n/catalog.ts +65 -0
  17. package/client/i18n/en.ts +269 -0
  18. package/client/i18n/errors.ts +21 -0
  19. package/client/i18n/index.ts +64 -0
  20. package/client/i18n/zh-CN.ts +271 -0
  21. package/client/md/classes.ts +80 -0
  22. package/client/md/clicks.ts +193 -0
  23. package/client/md/drag.ts +162 -0
  24. package/client/md/format.ts +158 -0
  25. package/client/md/frontmatter.ts +108 -0
  26. package/client/md/html.ts +110 -0
  27. package/client/md/inline.ts +400 -0
  28. package/client/md/insert.ts +28 -0
  29. package/client/md/lines.ts +296 -0
  30. package/client/md/literals.ts +227 -0
  31. package/client/md/locate.ts +179 -0
  32. package/client/md/motion.ts +105 -0
  33. package/client/md/props.ts +104 -0
  34. package/client/md/tags.ts +173 -0
  35. package/client/state.ts +51 -0
  36. package/client/types.ts +121 -0
  37. package/client/ui/InlineEditor.vue +668 -0
  38. package/client/ui/SelectionLayer.vue +217 -0
  39. package/client/ui/StudioDock.vue +53 -0
  40. package/client/ui/StudioRoot.vue +186 -0
  41. package/client/ui/StudioToolbar.vue +88 -0
  42. package/client/ui/panels/PanelAnimate.vue +311 -0
  43. package/client/ui/panels/PanelAssets.vue +90 -0
  44. package/client/ui/panels/PanelComponents.vue +152 -0
  45. package/client/ui/panels/PanelInspect.vue +280 -0
  46. package/client/ui/panels/PanelLayout.vue +238 -0
  47. package/client/ui/panels/PanelSlides.vue +160 -0
  48. package/client/ui/parts/ColorSwatch.vue +97 -0
  49. package/client/ui/parts/ComponentPreview.vue +81 -0
  50. package/client/ui/parts/LayoutPreview.vue +111 -0
  51. package/client/ui/parts/ListField.vue +85 -0
  52. package/client/ui/parts/ObjectListField.vue +128 -0
  53. package/client/ui/parts/PropField.vue +200 -0
  54. package/client/ui/parts/SlideThumbnail.vue +50 -0
  55. package/client/ui/parts/StudioField.vue +10 -0
  56. package/client/ui/parts/StudioIcon.vue +60 -0
  57. package/client/ui/parts/StudioSegmented.vue +23 -0
  58. package/custom-nav-controls.vue +22 -0
  59. package/global-top.vue +24 -0
  60. package/index.d.ts +15 -0
  61. package/node/assets.ts +126 -0
  62. package/node/builtin-meta.ts +108 -0
  63. package/node/catalog.ts +725 -0
  64. package/node/deck.ts +130 -0
  65. package/node/html-scan.ts +118 -0
  66. package/node/markdown-source.ts +232 -0
  67. package/node/metadata.ts +293 -0
  68. package/node/palette.ts +87 -0
  69. package/node/plugin.ts +200 -0
  70. package/node/slide-source.ts +148 -0
  71. package/package.json +66 -4
  72. package/setup/context-menu.ts +127 -0
  73. package/setup/shortcuts.ts +63 -0
  74. package/setup/vite-plugins.ts +12 -0
  75. package/shared/errors.ts +34 -0
  76. package/shared/signature.ts +40 -0
  77. package/styles/studio.css +962 -0
  78. package/types/slidev-client.d.ts +67 -0
  79. package/vite.config.ts +27 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Daniel Christensen
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,482 @@
1
- # Temporary Holding Version
1
+ # @renko_1055/slidev-addon-studio
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Renko6626's fork adds English/Simplified Chinese interface switching and the
4
+ workbench's subpath and asset-directory support. It is published under
5
+ `@renko_1055/slidev-addon-studio`; the installation alias below keeps existing
6
+ Slidev addon configuration working.
7
+
8
+ ![slidev-addon-studio: a visual editor for Slidev. A slide canvas with a Shape component selected, showing the selection outline and resize handles](./docs/banner.png)
9
+
10
+ A visual editor for [Slidev](https://sli.dev). Select, drag, resize, animate and
11
+ compose slides directly on the canvas, the way you would in Keynote or
12
+ PowerPoint, while the deck stays exactly what it was: a Markdown file.
13
+
14
+ ![Studio open on a slide, with a component selected. The Element panel shows its props, its classes and the Markdown line it came from](./docs/framed/studio.png)
15
+
16
+ **Markdown is the source of truth.** Every action in Studio is a small, readable
17
+ edit to your `.md` file. There is no project format, no database and no lock-in.
18
+ Close the editor and the diff is something you could have typed by hand. That
19
+ constraint is the point: it is what lets a visual editor coexist with version
20
+ control, code review and hand editing.
21
+
22
+ ## Install
23
+
24
+ ```bash
25
+ pnpm add -D slidev-addon-studio@npm:@renko_1055/slidev-addon-studio@0.3.1-renko.1
26
+ ```
27
+
28
+ This installs the scoped fork under the local name `slidev-addon-studio`.
29
+ The workbench activity template pins the same npm alias and records the package
30
+ integrity in `pnpm-lock.yaml`. Installing `slidev-addon-studio` without the alias
31
+ still installs upstream.
32
+
33
+ Then enable it in your deck's headmatter:
34
+
35
+ ```yaml
36
+ ---
37
+ addons:
38
+ - slidev-addon-studio
39
+ ---
40
+ ```
41
+
42
+ or in `package.json`, which applies it to every deck in the project:
43
+
44
+ ```json
45
+ {
46
+ "slidev": {
47
+ "addons": ["slidev-addon-studio"]
48
+ }
49
+ }
50
+ ```
51
+
52
+ Start `slidev` as usual and press <kbd>E</kbd>, or use the pencil button in
53
+ Slidev's bottom bar. Studio adds nothing to the slide while it is closed.
54
+
55
+ ## Interface language
56
+
57
+ Studio supports English and Simplified Chinese. On first use it follows your
58
+ browser language: Chinese browsers use Simplified Chinese, and others use
59
+ English. Use the language selector in Studio's toolbar to change it. The choice
60
+ is remembered in this browser under `slidev-studio:locale`.
61
+
62
+ The setting changes Studio's interface. Slide content, component names, prop
63
+ keys, inserted Markdown snippets and third-party component descriptions keep
64
+ their original text. Labels and options Studio supplies for Slidev's builtin
65
+ components are translated as well. Page-operation and upload validation errors
66
+ use the selected language; their original English messages remain in the API
67
+ response for diagnostics. Unexpected system errors retain their original text.
68
+
69
+ Translations use a Studio-owned Vue I18n Composer, so they do not replace a
70
+ presentation's own Vue I18n plugin or global `$t`. English and Chinese messages
71
+ live in `client/i18n/en.ts` and `client/i18n/zh-CN.ts`. Add matching keys to both
72
+ files and use `t('messageKey', { name: value })` for parameterized messages. Keep
73
+ whole sentences in the dictionaries rather than joining translated fragments.
74
+ Vue I18n is pinned to 11.4.2 to retain the addon's existing Node 20 support.
75
+
76
+ ## Workbench mounts
77
+
78
+ Studio's API requests and asset thumbnails follow Vite's `base`, including
79
+ workbench paths such as `/edit/<workspace>/`. Editing raw HTML removes that
80
+ mount prefix from media URLs before saving, so Markdown keeps root-relative
81
+ asset paths. `SLIDEV_STUDIO_ASSET_DIR` optionally selects the upload directory
82
+ inside `public/`; an empty value uses `public/` itself. These adaptations are
83
+ included in the fork, so the workbench no longer needs a Studio package patch.
84
+
85
+ ## What it does
86
+
87
+ | Panel | What it edits |
88
+ | --- | --- |
89
+ | **Element** | Position, size, rotation, component props, utility classes, order, duplicate, delete, and the raw Markdown of the selection |
90
+ | **Components** | Markdown basics plus every component this deck can use, with live previews. Click to insert, drag onto the canvas to place freely |
91
+ | **Animate** | Click steps, reveal and hide, entrance animations, staggered lists, motion presets, slide transitions |
92
+ | **Layout** | The layout, with a live thumbnail of each one, the frontmatter keys that layout reads, and the slide's title, classes, background, zoom, click count and notes |
93
+ | **Slides** | Live thumbnails, drag to reorder, add, duplicate and delete |
94
+ | **Assets** | Drop images into `public/` and insert them |
95
+
96
+ ### Selecting and moving
97
+
98
+ Click anything on the slide. Studio traces the rendered element back to the
99
+ exact lines of Markdown it came from and shows them in the Element panel.
100
+
101
+ Drag the selection and the block leaves the document flow: Studio wraps it in
102
+ Slidev's own `v-drag`, so the position is written into the Markdown as
103
+ `pos="x,y,w,h"` in slide canvas units. Handles resize, the top handle rotates,
104
+ and <kbd>Backspace</kbd> deletes. "Return to flow" in the Element panel undoes
105
+ the free positioning.
106
+
107
+ Elements snap to the canvas edges, its centre and thirds, and to the edges and
108
+ centres of everything else on the slide. Hold <kbd>Alt</kbd> to place something
109
+ exactly where you want it instead.
110
+
111
+ ![A block being dragged across the slide, with the selection outline and handles following the pointer](./docs/framed/drag.png)
112
+
113
+ A move of an element that is already free is written straight into its `pos`,
114
+ without rebuilding the slide, so dragging stays as smooth as Slidev's own
115
+ handles. Only the first drag of a block in the document flow re-renders it,
116
+ because that one changes the Markdown's shape rather than four numbers in it.
117
+
118
+ ### Editing text
119
+
120
+ Double-click any block and it becomes editable where it sits, with a toolbar for
121
+ bold, italic, code, strikethrough, links, headings, lists and quotes.
122
+
123
+ What is edited is the block's Markdown, not its rendered HTML, which is why a
124
+ table or a fenced code block is editable too: to this editor they are text like
125
+ everything else. It is also why the toolbar can be trusted. Round-tripping
126
+ rendered HTML back into Markdown is where visual editors lose components,
127
+ directives and formatting, and a Slidev deck is full of all three.
128
+
129
+ ![A paragraph being edited in place, with a formatting toolbar above it](./docs/framed/inline.png)
130
+
131
+ <kbd>Ctrl</kbd> + <kbd>Enter</kbd> applies, <kbd>Esc</kbd> cancels,
132
+ <kbd>Ctrl</kbd> + <kbd>B</kbd> and <kbd>Ctrl</kbd> + <kbd>I</kbd> do what you
133
+ expect.
134
+
135
+ ### Editing props
136
+
137
+ Select a component and the Element panel becomes a form for it, built from the
138
+ component's own props. Numbers are written bound (`:size="140"`), enumerated
139
+ strings plainly (`color="red"`), and options backed by image files get a picker
140
+ that shows the images.
141
+
142
+ A prop that holds records is edited as one row per entry with a field per key,
143
+ typed from the element type the component declares, so an empty list still knows
144
+ what fields it wants. A prop that holds a colour offers the deck's own palette,
145
+ read from the custom properties in your theme's stylesheets, so picking one
146
+ keeps the slide pointing at `var(--accent)` rather than freezing a hex.
147
+
148
+ ![The Element panel editing a list of records as rows, with the theme's colour palette open below it](./docs/framed/element-props.png)
149
+
150
+ ### Animating
151
+
152
+ Slidev's animation model is a sequence of click steps per slide, so the Animate
153
+ panel leads with that sequence and lets you scrub it.
154
+
155
+ ![The Animate panel with a click scrubber and the reveal settings for the selected paragraph](./docs/framed/animate.png)
156
+
157
+ Studio writes whichever form fits the block:
158
+
159
+ ```md
160
+ <!-- an element or component takes the directive -->
161
+ <Pill v-click.fade="2">Later</Pill>
162
+
163
+ <!-- a Markdown block gets a wrapper, which renders no extra element -->
164
+ <v-click>
165
+
166
+ # A heading that appears on click
167
+
168
+ </v-click>
169
+
170
+ <!-- a list can reveal one item at a time -->
171
+ <v-clicks every="2">
172
+
173
+ - One
174
+ - Two
175
+
176
+ </v-clicks>
177
+ ```
178
+
179
+ ### Choosing a layout
180
+
181
+ A layout is picked from thumbnails rather than from a list of names. Each one
182
+ renders the layout at full slide size with this slide's own frontmatter, title
183
+ and lead line, then scales it down, so what you compare is the composition you
184
+ would get.
185
+
186
+ ![The Layout panel showing a thumbnail per layout, each rendering the current slide's title](./docs/framed/layout.png)
187
+
188
+ A layout's props are the frontmatter keys it reads, and they are edited in the
189
+ same panel. On a slide like `layout: fact`, whose entire visible text lives in
190
+ `value:` and `label:`, that panel is the only place to edit it: none of that
191
+ text ever passed through Markdown, so there is nothing on the canvas to click.
192
+
193
+ ### Working with slides
194
+
195
+ ![The Slides panel showing a live thumbnail per slide, with add, duplicate and delete](./docs/framed/slides.png)
196
+
197
+ Thumbnails are the real slide components rendered small, not captures, so they
198
+ are never out of date. Drag one to reorder, and add, duplicate or delete from
199
+ the same panel.
200
+
201
+ ### Inserting
202
+
203
+ ![The Components panel showing the deck's own components, each tile rendering the real component](./docs/framed/components.png)
204
+
205
+ The palette starts with the plain Markdown blocks, because most of what goes on
206
+ a slide is a heading, a paragraph or a list. Below those sit every component the
207
+ deck can actually use: Slidev's builtins, the active theme, each addon, and your
208
+ own `components/` directory.
209
+
210
+ ### Keyboard
211
+
212
+ | Key | Action |
213
+ | --- | --- |
214
+ | <kbd>E</kbd> | Open and close Studio |
215
+ | Double click | Edit the text of a block in place |
216
+ | Drag | Move the selection. A click on its own never repositions anything |
217
+ | <kbd>Backspace</kbd> or <kbd>Delete</kbd> | Delete the selected element |
218
+ | <kbd>Esc</kbd> | Back out one layer: the drag in progress, then the text editor, then the selection |
219
+ | <kbd>Ctrl</kbd> + <kbd>Z</kbd> | Undo |
220
+ | <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Z</kbd> | Redo |
221
+ | <kbd>Alt</kbd> (held) | Bypass snapping while dragging |
222
+ | <kbd>Shift</kbd> (held) | Keep aspect ratio, or snap rotation to 15 degrees |
223
+
224
+ Undo history lives in the page, so a reload clears it, and so does anything that
225
+ renumbers the deck: adding, duplicating, deleting, reordering or skipping a
226
+ slide. Undo replays a whole slide by its number, and after a renumbering those
227
+ numbers point somewhere else. Your deck is a file in git; that is the real undo.
228
+
229
+ ## Teaching Studio about your components
230
+
231
+ Any component Slidev can resolve appears in the palette automatically. Two
232
+ things happen without you writing a line of configuration:
233
+
234
+ **The usage example in the component's doc comment becomes the snippet.** A
235
+ component documented like this:
236
+
237
+ ```ts
238
+ /**
239
+ * BigCount - the talk's signature beat, a number that counts up on reveal.
240
+ *
241
+ * <BigCount :to="138723" label="Enheter" />
242
+ */
243
+ ```
244
+
245
+ is inserted as `<BigCount :to="138723" label="Enheter" />`, with real values, and
246
+ previewed with them. That beats anything synthesised from prop types, and it is
247
+ something most well-documented components already have.
248
+
249
+ **Props are read from `defineProps`.** Types drive the controls: a string union
250
+ becomes a dropdown, a number gets bound, a boolean gets a toggle.
251
+
252
+ For anything more, add a `<studio>` block to the component. It is a custom SFC
253
+ block holding plain YAML, so editors keep highlighting the file as Vue:
254
+
255
+ ```html
256
+ <studio lang="yaml">
257
+ description: One of the site's mascot illustrations
258
+ category: Brand
259
+ props:
260
+ name:
261
+ label: Mascot
262
+ options:
263
+ files: ../assets/mascots/*.svg
264
+ exclude: '*-stroke.svg'
265
+ stroke:
266
+ label: Light on dark
267
+ palette:
268
+ control: color[]
269
+ </studio>
270
+ ```
271
+
272
+ | Key | Meaning |
273
+ | --- | --- |
274
+ | `description` | One line shown under the name; defaults to the first line of the doc comment |
275
+ | `category` | Groups the component in the palette; defaults to its package |
276
+ | `snippet` | Markup inserted when the component is picked |
277
+ | `preview` | Markup rendered in the thumbnail; defaults to the snippet, or `false` to skip |
278
+ | `hidden` | Keep the component out of the palette entirely |
279
+ | `props.<name>.label` | Human label for the inspector |
280
+ | `props.<name>.hidden` | Keep the prop out of the inspector |
281
+ | `props.<name>.options` | A list of values, or `{ files, exclude }` globs |
282
+ | `props.<name>.control` | Force a control: `text`, `number`, `boolean`, `select`, `list`, `color`, `color[]` |
283
+ | `props.<name>.fields` | For a list of records, the fields each row gets; inferred from the declared element type when omitted |
284
+ | `hidden: true` | Keep the component out of the palette, for one that is not meant to be written by hand |
285
+
286
+ Controls are otherwise inferred. A string union gets a dropdown, a number is
287
+ written bound as `:size="140"`, and an array gets an editor matched to what it
288
+ holds:
289
+
290
+ - a list of strings becomes rows with add, remove and reorder
291
+ - a list of records, such as a timeline's entries or a terminal demo's steps,
292
+ becomes a row per entry with a field per key, typed from the element type the
293
+ component declares, so an empty list still knows what fields it wants
294
+ - values that look like colours get swatches and a picker, which resolves a
295
+ theme variable such as `var(--flag-red)` to what it currently paints
296
+
297
+ Colours are also inferred from the values themselves, so a palette prop is a
298
+ colour editor without being declared. `control: color` or `control: color[]`
299
+ covers a prop that has no value yet.
300
+
301
+ The colours offered are your deck's own. Studio reads the custom properties
302
+ declared globally in the stylesheets your theme, addons and deck already ship,
303
+ so choosing one writes `var(--accent)` rather than a hex that stops following
304
+ the theme. A property declared inside a component's own rule is left out, since
305
+ it resolves to nothing at the slide root.
306
+
307
+ Layouts are read the same way. A layout's props are the frontmatter keys it
308
+ understands, so a slide like `layout: fact`, whose entire visible text lives in
309
+ `value:` and `label:`, is edited under Layout rather than on the canvas.
310
+
311
+ The `files` glob is resolved against the component's own directory, so a
312
+ component that ships a folder of assets can offer them as choices with nothing
313
+ hardcoded in the editor. When the files are images, the inspector shows a
314
+ picker of the images themselves. `playground/components/Shape.vue` is a working
315
+ example of exactly that.
316
+
317
+ ## Text a layout renders
318
+
319
+ A layout is handed some of its words as frontmatter: a `title`, an `eyebrow`, a
320
+ speaker's `name`. Those words are not in the slide's body, so there is no line
321
+ of Markdown behind them and Studio cannot find them the way it finds a
322
+ paragraph. Mark them and it can:
323
+
324
+ ```vue
325
+ <h1 data-studio-prop="title">{{ title }}</h1>
326
+ ```
327
+
328
+ The element is then selectable on the canvas and editable in place, and what is
329
+ typed is written back to that frontmatter key. A value is a plain string, so the
330
+ formatting controls are not offered on one, and it opens with the whole value
331
+ selected the way a title placeholder does.
332
+
333
+ Keys holding a list rather than a string, such as an agenda's `items`, stay in
334
+ the Layout panel, where they are edited as rows.
335
+
336
+ ## Configuration
337
+
338
+ All optional, under `studio` in the headmatter:
339
+
340
+ ```yaml
341
+ ---
342
+ studio:
343
+ annotate: all # all | html | off
344
+ hideComponents:
345
+ - InternalThing
346
+ ---
347
+ ```
348
+
349
+ `annotate` controls how much of the rendered slide carries the source
350
+ annotations Studio needs to trace a click back to Markdown:
351
+
352
+ - `all` (default): HTML elements and Vue components
353
+ - `html`: HTML elements only. Use this if a fragment-root component logs
354
+ "extraneous non-props attributes" warnings in your console
355
+ - `off`: Markdown blocks only
356
+
357
+ Studio also respects Slidev's own `editor: false`, which disables it completely.
358
+
359
+ ## How it works
360
+
361
+ Studio is an ordinary Slidev addon. It hooks into the parts of Slidev that are
362
+ already there:
363
+
364
+ | What it needs | How it gets it |
365
+ | --- | --- |
366
+ | Editor UI over the deck | `global-top.vue`, teleported to `body` |
367
+ | Toolbar button | `custom-nav-controls.vue` |
368
+ | Keyboard shortcuts | `setup/shortcuts.ts` |
369
+ | Writing to the `.md` | `useDynamicSlideInfo().update()`, the same endpoint Slidev's own editor and `v-drag` use |
370
+ | Changing frontmatter | The same endpoint, but as `frontmatterRaw` rather than a `frontmatter` patch, edited line by line so comments and key order survive. A patch updates Slidev's own resolved copy of the deck, so the file watcher then finds nothing changed and never rebuilds the slide, and a layout switch appears to do nothing until the server restarts |
371
+ | Free positioning | Slidev's `v-drag`, so positions stay compatible with Slidev's own handles |
372
+ | Component and layout catalog | `setup/vite-plugins.ts`, which receives the fully resolved options including every theme and addon root |
373
+ | Adding and reordering slides | A small dev-only API in the addon's own Vite plugin, since Slidev's endpoint only patches slides in place |
374
+ | Tracing a click to its source | A markdown-it plugin that stamps each block with the line range it came from |
375
+
376
+ That last one is a hint, not a contract. A custom `setup/transformers.ts` can
377
+ move lines before markdown-it sees them, so the client re-checks every range
378
+ against the real Markdown and finds the block again by its content when the
379
+ range does not match. If it cannot be sure, it refuses to edit and says so.
380
+ Editing the wrong lines is the one failure that would cost you a deck, and it is
381
+ worth being dull about.
382
+
383
+ ## Limitations
384
+
385
+ - Editing only works while `slidev` is running with the editor enabled. A built,
386
+ exported or printed deck contains none of Studio.
387
+ - Slides imported from another file with `src:` can be reordered only within
388
+ their own file.
389
+ - The first slide of the entry file cannot be deleted or moved: its frontmatter
390
+ is the deck's global configuration.
391
+ - Components Slidev generates rather than authors write, such as `Monaco`,
392
+ `Mermaid` and `PlantUml`, are left out of the palette: they take a compressed
393
+ payload, so a hand-written tag cannot render. Write the fenced code block
394
+ instead and Slidev emits them for you.
395
+ - A component whose template has several root nodes is left out too. Vue drops
396
+ fallthrough attributes on a fragment root, so such a component can never carry
397
+ the annotation that makes it selectable.
398
+ - Prop extraction understands `defineProps` and the Options API. Anything more
399
+ exotic simply shows no props; the component still works, and a `<studio>`
400
+ block can describe the props by hand.
401
+ - An element nested inside a block of raw HTML can be selected, styled, animated
402
+ and deleted, but not reordered or duplicated on its own: it shares a Markdown
403
+ block with its siblings.
404
+ - Classes on a Markdown block use MDC's trailing `{.class}`, which attaches to
405
+ the last element on the line. That is the block itself for a one-line
406
+ paragraph or heading, so those are offered. A list, a quote and a paragraph
407
+ written across several lines are not: the class would land on the last
408
+ `<li>`, or inside the quote, or on a `<span>` around the last few words.
409
+ Wrap the block in a `<div>` to style it as a whole.
410
+ - Two blocks that are byte for byte identical cannot be told apart if the line
411
+ hint is ever wrong. Studio says so and refuses rather than picking one.
412
+ - Slidev's own controls sit invisibly over the slide's bottom left corner, so
413
+ while Studio is open they stop taking the pointer and that corner belongs to
414
+ the canvas. Studio's toolbar carries undo, redo, the grid, the outlines and
415
+ closing, and Slidev's own keyboard shortcuts are unaffected.
416
+ - Skipping a slide is a one way door from inside the editor. Slidev drops hidden
417
+ slides from the deck, so the slide loses its number and nothing can reach it
418
+ again: delete `hide: true` in the Markdown to bring it back.
419
+ - Adding, duplicating, deleting or reordering a slide reloads the page. Slidev's
420
+ own reload only refreshes slides it already knows, so a new slide would
421
+ otherwise come back rendering whatever used to carry its number.
422
+ - Content a component renders from *other* slides, such as `<Toc>`, carries
423
+ those slides' own annotations. Clicking an entry there selects nothing:
424
+ its lines belong to a different slide, and following them would edit it.
425
+ - A usage example that abbreviates, such as `:items="[{ … }, …]"`, is still
426
+ inserted as the snippet but cannot be previewed, since it is not valid
427
+ JavaScript. Add `preview:` to the `<studio>` block to give the palette
428
+ something it can render.
429
+ - If your project sets `slidev.markdown.markdownSetup` in its own Vite config,
430
+ it replaces the addon's and click-to-select stops working. Studio warns on
431
+ startup. Call `studioMarkdownSetup(md)` from your setup to restore it:
432
+
433
+ ```ts
434
+ import { studioMarkdownSetup } from 'slidev-addon-studio/node/markdown-source'
435
+
436
+ export default {
437
+ slidev: {
438
+ markdown: {
439
+ markdownSetup(md) {
440
+ studioMarkdownSetup(md)
441
+ // your own plugins here
442
+ },
443
+ },
444
+ },
445
+ }
446
+ ```
447
+
448
+ ## Development
449
+
450
+ ```bash
451
+ pnpm install
452
+ pnpm play # the playground deck in playground/
453
+ pnpm test # unit tests for the Markdown rewriting
454
+ pnpm typecheck
455
+ ```
456
+
457
+ There is also an end to end pass over a real deck. It generates a slide per
458
+ component from the catalog, then moves, animates and reconfigures each one,
459
+ posting every edit and recompiling the slide, so markup the editor produces that
460
+ Vue cannot compile fails here rather than in someone's deck:
461
+
462
+ ```bash
463
+ slidev decks/qa-studio.md --port 3060
464
+ STUDIO_QA_URL=http://localhost:3060 pnpm test
465
+ ```
466
+
467
+ The Markdown rewriting lives in `client/md/` and `node/slide-source.ts` as pure
468
+ functions with no DOM or Vue involved, which is where the tests are aimed.
469
+ Anything that changes a user's file should be provable at that level first.
470
+
471
+ To try it against a real deck, link it in:
472
+
473
+ ```bash
474
+ pnpm add -D "link:../slidev-addon-studio"
475
+ ```
476
+
477
+ `link:` rather than `file:`, so edits reach the running dev server instead of
478
+ being copied once at install time.
479
+
480
+ ## License
481
+
482
+ MIT
@@ -0,0 +1,173 @@
1
+ import { action, t, targetLabel, targetName } from './i18n'
2
+ import type { StudioContext } from './context'
3
+ import type { SourceRange, StudioTarget } from './types'
4
+ import { readDrag, removeDrag, writeDrag } from './md/drag'
5
+ import { duplicateListItem, getBlock, insertAfter, moveBlock, moveListItem, removeBlock } from './md/lines'
6
+ import { editing, reportError, selection } from './state'
7
+
8
+ /**
9
+ * What can be done to the selected block, in one place.
10
+ *
11
+ * The Element panel and the right-click menu offer the same handful of actions,
12
+ * and an action that behaves differently depending on where it was invoked from
13
+ * is a bug waiting to happen, so both call these.
14
+ */
15
+
16
+ /**
17
+ * The lines an arrange action owns.
18
+ *
19
+ * A block given a free position lives inside a `<v-drag>` wrapper, and the
20
+ * wrapper is part of the thing on screen: reordering only the block moved it
21
+ * out and left an empty wrapper behind, holding a position and nothing to
22
+ * position. Moving, duplicating or deleting takes the whole wrapper.
23
+ */
24
+ export function positionedUnit(content: string, range: SourceRange): SourceRange {
25
+ const wrapper = readDrag(content, range)
26
+ return wrapper?.via === 'wrapper' && wrapper.open !== undefined && wrapper.close !== undefined
27
+ ? [wrapper.open, wrapper.close + 1]
28
+ : range
29
+ }
30
+
31
+ /** Whether the block already carries a position of its own. */
32
+ export function isPositioned(content: string, range: SourceRange): boolean {
33
+ return !!readDrag(content, range)?.pos
34
+ }
35
+
36
+ export function editText() {
37
+ if (selection.value?.range)
38
+ editing.value = true
39
+ }
40
+
41
+ /**
42
+ * Lifts the block out of the document flow, where it is standing.
43
+ *
44
+ * Measured from what is on screen rather than from a guess, so the block does
45
+ * not jump the moment it becomes free.
46
+ */
47
+ export async function freePosition(studio: StudioContext, target: StudioTarget) {
48
+ if (!target.range)
49
+ return
50
+
51
+ /*
52
+ * A block that shares its Markdown block with siblings cannot be lifted out
53
+ * of it.
54
+ *
55
+ * The position is written by wrapping the block's lines in `<v-drag>`, and
56
+ * for one item of a list those lines sit in the middle of the list. Wrapping
57
+ * them splices an HTML block into it, which ends the list above and starts a
58
+ * new one below: the item is orphaned and its neighbours quietly change which
59
+ * list, and which level, they belong to. Refusing is the only honest answer
60
+ * until the item can be promoted out of its list first.
61
+ */
62
+ if (target.nested) {
63
+ reportError(new Error(
64
+ t('errorListPosition', { name: targetLabel(target) }),
65
+ ))
66
+ return
67
+ }
68
+ const box = studio.canvas.boxOf(target.el)
69
+ // Written in the coordinates Slidev will read it in, which are the block's
70
+ // own containing block rather than the slide when a layout positions its
71
+ // panes. Without this the block jumps by the pane's offset the moment it is
72
+ // given a position.
73
+ const origin = studio.canvas.originOf(target.el)
74
+ await studio.commit(
75
+ writeDrag(studio.content(), target.range, { x: box.x - origin.x, y: box.y - origin.y, w: box.w, h: null, rotate: 0 }),
76
+ action('actionFreePosition'),
77
+ )
78
+ }
79
+
80
+ export async function returnToFlow(studio: StudioContext, target: StudioTarget) {
81
+ if (!target.range)
82
+ return
83
+ await studio.commit(removeDrag(studio.content(), target.range), action('actionReturnFlow'))
84
+ }
85
+
86
+ /**
87
+ * Whether reordering and duplicating apply.
88
+ *
89
+ * A block that shares its Markdown with siblings usually cannot be moved on its
90
+ * own. A list item is the exception: it has its own line, and its siblings are
91
+ * the other lines of the same list, so the two operations mean something
92
+ * precise there. They are written by the list aware functions rather than the
93
+ * block ones, which is what stopped an item jumping over its siblings or
94
+ * breaking the list in two around a copy.
95
+ */
96
+ export function canReorder(target: StudioTarget): boolean {
97
+ return !target.nested || target.kind === 'list-item'
98
+ }
99
+
100
+ export async function duplicateBlock(studio: StudioContext, target: StudioTarget) {
101
+ if (!target.range)
102
+ return
103
+
104
+ if (target.kind === 'list-item') {
105
+ const next = duplicateListItem(studio.content(), target.range[0])
106
+ if (next)
107
+ await studio.commit(next, action('actionDuplicateItem'))
108
+ return
109
+ }
110
+ const unit = positionedUnit(studio.content(), target.range)
111
+ await studio.commit(
112
+ insertAfter(studio.content(), unit, getBlock(studio.content(), unit)),
113
+ action('actionDuplicateBlock'),
114
+ )
115
+ }
116
+
117
+ export async function deleteBlock(studio: StudioContext, target: StudioTarget) {
118
+ if (!target.range)
119
+ return
120
+ const unit = positionedUnit(studio.content(), target.range)
121
+ selection.value = null
122
+ await studio.commit(removeBlock(studio.content(), unit), action('actionDelete', { name: targetName(target) }))
123
+ }
124
+
125
+ /**
126
+ * Moves a positioned block by a few pixels, from the keyboard.
127
+ *
128
+ * A block still in the flow has no position to change: where it sits is decided
129
+ * by the text around it, and an arrow key there means the deck's own navigation,
130
+ * which is what it keeps doing. Only a block that has been given a position of
131
+ * its own can be nudged, which is also the only one where a pixel means
132
+ * anything.
133
+ */
134
+ export async function nudgeBlock(
135
+ studio: StudioContext,
136
+ target: StudioTarget,
137
+ dx: number,
138
+ dy: number,
139
+ ): Promise<boolean> {
140
+ if (!target.range)
141
+ return false
142
+
143
+ const content = studio.content()
144
+ const unit = positionedUnit(content, target.range)
145
+ const drag = readDrag(content, unit)
146
+ if (!drag?.pos)
147
+ return false
148
+
149
+ const pos = drag.pos
150
+ await studio.commit(
151
+ writeDrag(content, unit, { ...pos, x: pos.x + dx, y: pos.y + dy }),
152
+ action('actionNudge'),
153
+ // The numbers change, nothing else does, and rebuilding the slide for an
154
+ // arrow key would make holding one down unusable.
155
+ { keepSelection: true },
156
+ )
157
+ return true
158
+ }
159
+
160
+ export async function moveBlockBy(studio: StudioContext, target: StudioTarget, direction: -1 | 1) {
161
+ if (!target.range)
162
+ return
163
+
164
+ if (target.kind === 'list-item') {
165
+ const next = moveListItem(studio.content(), target.range[0], direction)
166
+ // Null means there is no sibling that way, so there is nothing to do.
167
+ if (next)
168
+ await studio.commit(next, action('actionReorderItem'))
169
+ return
170
+ }
171
+ const unit = positionedUnit(studio.content(), target.range)
172
+ await studio.commit(moveBlock(studio.content(), unit, direction), action('actionReorderBlock'))
173
+ }