@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.
- package/LICENSE +21 -0
- package/README.md +481 -2
- package/client/actions.ts +173 -0
- package/client/blocks.ts +85 -0
- package/client/composables/useCatalog.ts +61 -0
- package/client/composables/useDeckApi.ts +70 -0
- package/client/composables/useDeckPaint.ts +32 -0
- package/client/composables/useDomEvent.ts +20 -0
- package/client/composables/useSelection.ts +506 -0
- package/client/composables/useSlideCanvas.ts +142 -0
- package/client/composables/useSlideSource.ts +165 -0
- package/client/composables/useSnapping.ts +137 -0
- package/client/composables/useTransformGizmo.ts +458 -0
- package/client/context.ts +59 -0
- package/client/dom.ts +33 -0
- package/client/i18n/catalog.ts +65 -0
- package/client/i18n/en.ts +269 -0
- package/client/i18n/errors.ts +21 -0
- package/client/i18n/index.ts +64 -0
- package/client/i18n/zh-CN.ts +271 -0
- package/client/md/classes.ts +80 -0
- package/client/md/clicks.ts +193 -0
- package/client/md/drag.ts +162 -0
- package/client/md/format.ts +158 -0
- package/client/md/frontmatter.ts +108 -0
- package/client/md/html.ts +110 -0
- package/client/md/inline.ts +400 -0
- package/client/md/insert.ts +28 -0
- package/client/md/lines.ts +296 -0
- package/client/md/literals.ts +227 -0
- package/client/md/locate.ts +179 -0
- package/client/md/motion.ts +105 -0
- package/client/md/props.ts +104 -0
- package/client/md/tags.ts +173 -0
- package/client/state.ts +51 -0
- package/client/types.ts +121 -0
- package/client/ui/InlineEditor.vue +668 -0
- package/client/ui/SelectionLayer.vue +217 -0
- package/client/ui/StudioDock.vue +53 -0
- package/client/ui/StudioRoot.vue +186 -0
- package/client/ui/StudioToolbar.vue +88 -0
- package/client/ui/panels/PanelAnimate.vue +311 -0
- package/client/ui/panels/PanelAssets.vue +90 -0
- package/client/ui/panels/PanelComponents.vue +152 -0
- package/client/ui/panels/PanelInspect.vue +280 -0
- package/client/ui/panels/PanelLayout.vue +238 -0
- package/client/ui/panels/PanelSlides.vue +160 -0
- package/client/ui/parts/ColorSwatch.vue +97 -0
- package/client/ui/parts/ComponentPreview.vue +81 -0
- package/client/ui/parts/LayoutPreview.vue +111 -0
- package/client/ui/parts/ListField.vue +85 -0
- package/client/ui/parts/ObjectListField.vue +128 -0
- package/client/ui/parts/PropField.vue +200 -0
- package/client/ui/parts/SlideThumbnail.vue +50 -0
- package/client/ui/parts/StudioField.vue +10 -0
- package/client/ui/parts/StudioIcon.vue +60 -0
- package/client/ui/parts/StudioSegmented.vue +23 -0
- package/custom-nav-controls.vue +22 -0
- package/global-top.vue +24 -0
- package/index.d.ts +15 -0
- package/node/assets.ts +126 -0
- package/node/builtin-meta.ts +108 -0
- package/node/catalog.ts +725 -0
- package/node/deck.ts +130 -0
- package/node/html-scan.ts +118 -0
- package/node/markdown-source.ts +232 -0
- package/node/metadata.ts +293 -0
- package/node/palette.ts +87 -0
- package/node/plugin.ts +200 -0
- package/node/slide-source.ts +148 -0
- package/package.json +66 -4
- package/setup/context-menu.ts +127 -0
- package/setup/shortcuts.ts +63 -0
- package/setup/vite-plugins.ts +12 -0
- package/shared/errors.ts +34 -0
- package/shared/signature.ts +40 -0
- package/styles/studio.css +962 -0
- package/types/slidev-client.d.ts +67 -0
- 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
|
-
#
|
|
1
|
+
# @renko_1055/slidev-addon-studio
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+

|
|
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
|
+
}
|