@leotang92/dsh-claude-dashboard 0.0.0-stage → 0.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 (35) hide show
  1. package/LICENSE +27 -0
  2. package/NOTICE.md +25 -0
  3. package/README.md +21 -2
  4. package/cordis.patch.yml +7 -0
  5. package/docs/DETAIL.md +27 -0
  6. package/docs/DETAIL.zh.md +16 -0
  7. package/icon.svg +9 -0
  8. package/lib/client.js +1800 -0
  9. package/lib/index.js +878 -0
  10. package/locale/en.json +7 -0
  11. package/locale/zh.json +7 -0
  12. package/package.json +69 -4
  13. package/skills/claude-dashboard/SKILL.md +495 -0
  14. package/skills/claude-dashboard/artifact-type/reference/admin-setup.md +106 -0
  15. package/skills/claude-dashboard/artifact-type/reference/dependent-calls.md +33 -0
  16. package/skills/claude-dashboard/artifact-type/reference/design-defaults.md +267 -0
  17. package/skills/claude-dashboard/artifact-type/reference/design-system.md +131 -0
  18. package/skills/claude-dashboard/artifact-type/reference/exporting.md +68 -0
  19. package/skills/claude-dashboard/artifact-type/reference/features.md +240 -0
  20. package/skills/claude-dashboard/artifact-type/reference/one-writer.md +104 -0
  21. package/skills/claude-dashboard/artifact-type/reference/read-aloud.md +118 -0
  22. package/skills/claude-dashboard/artifact-type/reference/remix.md +91 -0
  23. package/skills/claude-dashboard/artifact-type/reference/sources.md +234 -0
  24. package/skills/claude-dashboard/artifact-type/reference/visual-short-script.md +142 -0
  25. package/skills/claude-dashboard/artifact-type/reference/visual-short-skeleton.md +97 -0
  26. package/skills/claude-dashboard/artifact-type/reference/visual-short.md +227 -0
  27. package/skills/claude-dashboard/scripts/artifact.mjs +5541 -0
  28. package/skills/claude-dashboard/scripts/editor/assets/anthropicons-fizzy-lake-CPTdBYLV.woff2 +0 -0
  29. package/skills/claude-dashboard/scripts/editor/assets/index-BUtE2LuL.css +1 -0
  30. package/skills/claude-dashboard/scripts/editor/assets/index-DLvAt8Vr.js +553 -0
  31. package/skills/claude-dashboard/scripts/editor/comments.js +103 -0
  32. package/skills/claude-dashboard/scripts/editor/index.html +27 -0
  33. package/skills/claude-dashboard/scripts/editor/local-host.js +481 -0
  34. package/skills/claude-dashboard/scripts/editor/share-ui.js +208 -0
  35. package/skills/claude-dashboard/scripts/editor/third-party-licenses.txt +1141 -0
@@ -0,0 +1,227 @@
1
+ # Visual short
2
+
3
+ A Visual short is a dashboard that plays: one finding, told in a few chapters on
4
+ one stage, each a drawing that builds while a caption says what it shows, a
5
+ minute or two in all. It is for people who would rather watch than read: an
6
+ all-hands, a quarter's review, a link dropped in a channel. It works when one idea
7
+ is on screen at a time and each mark arrives with the words that name it.
8
+
9
+ It is built from datasets and marks like any dashboard. Below: what has to hold,
10
+ each with its reason, then suggestions, which give way to what the person asks
11
+ for.
12
+
13
+ Read `artifact-type/reference/visual-short-skeleton.md` (HTML and CSS) and
14
+ `artifact-type/reference/visual-short-script.md` next and start from them: they
15
+ already do what has to hold, so the work is the piece itself.
16
+
17
+ ## What has to hold
18
+
19
+ - **One writer for each part** (`artifact-type/reference/one-writer.md`), or the
20
+ page check fails. Words known as you write are in the HTML. Each marked figure
21
+ in the HTML, each chart and whatever else a script writes is a `data-draw`;
22
+ outside them a script, your scenes too, sets only `class`, `style` and
23
+ `aria-*`.
24
+ - **A mark holds its real value from the first draw.** The dashboard checks
25
+ every mark that is rendered against its data, at any opacity and at any
26
+ moment. So a chapter that isn't playing is drawn whole, as at its end, and
27
+ only the one playing is drawn at its time. A number that counts up does so in
28
+ an unmarked `aria-hidden="true"` copy, a drawing of its own, laid over the
29
+ marked one; once the count ends the marked one shows and the copy hides.
30
+ - **Chapters share one place and cross-fade.** Stack the chapters in one place,
31
+ and the captions in a stack of their own, and fade them with `opacity`: under
32
+ `display: none` a drawing measures 0 wide and its marks go unchecked. A
33
+ chapter not showing is `aria-hidden` and takes no pointer. That doesn't stop
34
+ the keyboard, so put nothing in a chapter that takes focus: no link, control
35
+ or `tabindex`.
36
+ - **Captions are hidden from the eye alone.** Where a sentence or a caption is
37
+ hidden (the sentences not being said; all of them with CC off; not one the
38
+ data rules out, which is `hidden`), hide it with `opacity`, never `display:
39
+ none`, `visibility: hidden`, `hidden` or `aria-hidden`: under any of those a
40
+ screen reader loses the words and Listen doesn't read them, and under
41
+ `display: none` or `hidden` a figure in the caption goes unchecked. With
42
+ `opacity` a screen reader and Listen get every caption, in order: to a screen
43
+ reader they are a transcript after the chapter showing. Every chapter keeps an
44
+ empty `.vs-say` after its headline, the row its caption is laid over: without
45
+ one the caption lies over the drawing.
46
+ - **Motion is drawn from time, in script.** Each chapter is a function of its
47
+ own time `t` in seconds, whole at the end of `t`, so it can be held, replayed
48
+ or jumped to and still look right. For this shape that replaces what
49
+ `design-defaults.md` says of `@keyframes`. `t` runs in one animation-frame
50
+ loop, stopped while nothing plays. Each frame writes only styles and
51
+ attributes that aren't marks; text and elements are written only when they
52
+ change, since each such write under `#dash-root` has the dashboard check all
53
+ the marks again. On new data or a new width the drawings run again, the
54
+ skeleton's `settle` last, which redraws the chapter showing at its current `t`
55
+ and leaves `t` alone.
56
+ - **The reader starts it.** It opens on its title, whole and at rest, which is
57
+ also what a thumbnail shows, and plays only when they press Play, pick a
58
+ chapter or, where there is a voice, press the speaker: motion nobody asked
59
+ for distracts. Its controls are `<button>`s in the HTML, each with a name (its words
60
+ or an `aria-label`), so a keyboard and a screen reader can work them.
61
+ - **It fits the room it is given.** A stage that runs off the view loses its
62
+ foot. The room changes with the window and with the dashboard's own bars,
63
+ above the page and under it, so measure it in the box the page scrolls in, and
64
+ set the stage's width from the height there is room for, so it keeps its shape
65
+ (`fit` in the script).
66
+ - **Sizes need a container.** Nothing above the page is a container, so
67
+ `@container` never matches and `cqi` measures the window. Set
68
+ `container-type: inline-size` on the wrapper, for rules at narrow widths, and on
69
+ the stage. Size what is inside the stage in `cqi`
70
+ (`.vs-caps { font-size: max(14px, 2cqi); }`): `cqi` on an element measures the
71
+ nearest container above it, never the element itself.
72
+ - **`prefers-reduced-motion: reduce`** shows each chapter's drawing whole at once,
73
+ with only the fade. Its sentences still take their turns.
74
+ - **The voice is an extra.** Some readers have Listen
75
+ (`artifact-type/reference/read-aloud.md`); many don't, so the piece plays whole
76
+ without it. Mark it to be read, as the skeleton does: the captions' holder
77
+ `data-read`, with nothing in it but the captions, each caption
78
+ `data-read-step`, and the stage around them `data-read-stage`. Without that last
79
+ one the dashboard tints the words and scrolls each caption to the middle. Keep
80
+ the captions as the same elements throughout: the dashboard stamps the ones that
81
+ were there when the reading started.
82
+ - **While a reading is open, the dashboard keeps time.** `#dash-root` then has
83
+ `data-dash-read-phase`, and the caption being read, or read last, has
84
+ `data-dash-read-now`. When that stamp lands on another caption, or the phase
85
+ turns to `starting` (a press can have the same caption read again), show its
86
+ chapter from `t` = 0. `t` runs only while the phase is `playing`: test for that,
87
+ since nothing is heard during `starting` or `paused` or after `ended`. The page
88
+ moves to no chapter by itself: one that finishes early waits, whole, for the
89
+ next stamp. At `ended`, once the last caption is read, show the chapter whole
90
+ and stay on it. When the phase goes the voice is off, by a press or because it
91
+ failed: carry on without it from the same place, playing if it was playing.
92
+ - **One set of controls, with the voice or without, and one clock at a time.**
93
+ The page keeps its own controls through a reading, and the dashboard draws
94
+ none; `read-aloud.md` has the rules. The speaker is `data-read-sound`, stored
95
+ `aria-pressed="false"`: a press brings the voice in at the top of the chapter
96
+ that is up, a second press takes it away, and the dashboard keeps
97
+ `aria-pressed`, by which CSS shows a speaker or a struck-out one. Play and Pause
98
+ is `data-read-pause`; Back, Next and each chapter mark are `data-read-move`.
99
+ While a reading is open their `onclick`s still show the chapter, but start and
100
+ stop no clock of the page's: the two would run against each other.
101
+ - **Every number in a caption is marked and filled from the data,** as a
102
+ Letter's are, whatever the source. Words you type are stored for everyone and
103
+ never change, while each reader's page runs a live query on their own
104
+ connection: a typed number would reach readers with no access to the source,
105
+ could contradict the figure on their stage, and would go stale. Words that
106
+ turn on the data (up, down, more, fewer) are filled too, from a calc. A goal
107
+ the person named is one constant in the script, unmarked, drawn wherever it
108
+ shows (`one-writer.md`). What you type is the gist, which holds whatever the
109
+ numbers are.
110
+
111
+ ## Suggestions
112
+
113
+ **The piece.** Five to seven chapters usually carry one finding. The first is a
114
+ title: what it is, the period and how long it runs (worked out from the captions,
115
+ not typed). Set the title at about 6cqi, or put the one figure the story turns on
116
+ under a headline. The last is what to do next; it reads best ending with every
117
+ mark at full strength, since it stays up. The stage stands alone: tiles, filters,
118
+ tabs, tables or text around it pull the eye from what is playing.
119
+
120
+ **The stage.** 16:9 suits a wide page; in a wrapper under 800px (beside a chat) a
121
+ square uses the room better, and under 560px `4 / 5`, sized as in the skeleton.
122
+ `background: var(--color-panel)`, `border: 1px solid var(--color-border-line)`,
123
+ `border-radius: var(--cds-radius)`; no shadow, gradient or rule down the left.
124
+
125
+ **A chapter's frame**, the same each time so only the content changes: a small
126
+ uppercase label for the part of the story; a one-sentence headline that states
127
+ the finding, not the topic; the caption's row; one drawing; a small muted source
128
+ line (measure, who, dates). The chapter marks run across the top of the stage,
129
+ and the controls stand at the top right, on the label's line. So keep the label
130
+ short, and keep it on every chapter, the title too.
131
+
132
+ **Type** is set as on a slide, in `cqi` of the stage: headline about 3.4 and 18px
133
+ at least, to stay larger than the caption under it, labels and values on marks
134
+ 1.8 (1em inside a drawing), captions 2, source line 1.3, a big number 12.
135
+
136
+ **The drawing fills its box,** the room between the caption's row and the source
137
+ line, which is most of the stage. The skeleton makes that box a container of both its sizes:
138
+ inside it `cqh` is 1% of its height, `cqi` 1% of its width, a little under the
139
+ stage's, and `em` the labels' size, set on the box. Size what is drawn from the
140
+ box, not from a fixed number of pixels. Bars share its height: each row is
141
+ 100cqh over their number, up to about 18cqh, and the bar some 60% of its row.
142
+ Columns stand its full height, less their labels. A dot grid is the largest
143
+ square the box holds, `min(100cqh, 100cqi)` a side. What can't fill the box sits
144
+ in its middle, as the skeleton has it, not at its top.
145
+
146
+ **The drawing** is the one that shows the sentence. A share of people: a 10 by 10
147
+ grid of dots that fills, then recolors. A total: one big number that counts, with
148
+ what made it up beside it. A comparison: horizontal bars from zero, slightly
149
+ rounded. A gap between two: two bars and a bracket naming the gap. A run of
150
+ chapters that are all bars is a sign another drawing would fit somewhere. A bar
151
+ or dot painted with `background` vanishes in forced colors, so give it
152
+ `forced-color-adjust: none` and, under `@media (forced-colors: active)`, a system
153
+ color such as `CanvasText`, as the chapter marks in the skeleton do.
154
+
155
+ **How marks arrive.** Bars grow from zero, a value fades in once its bar lands,
156
+ dots come in a quick wave. 400 to 700ms with `d3.easeCubicOut` feels right (for
157
+ the chapters' fade, `--cds-ease-out`); camera moves, 3D and bounce don't. Gray
158
+ first, with one accent color on what the sentence is about; to focus, fade the
159
+ rest to about 25% opacity rather than add a color. Labels sit on the marks, so
160
+ gridlines, axis numbers and legends can go, and so can the tooltip `SKILL.md`
161
+ asks of a chart: every value is labeled.
162
+
163
+ **Captions.** One paragraph a chapter, 150 to 250 characters in two to four
164
+ short sentences, each in its own `.vs-s` span as in the skeleton and under some
165
+ 100 characters, so that it fits its row. They read best
166
+ written as if said aloud, with no brackets or symbols, and are in the HTML. A
167
+ voice reads only the captions, so each says what its chapter shows without
168
+ leaning on the headline.
169
+
170
+ **Figures in captions.** Phrase each sentence so that it reads well around a
171
+ filled figure. By default that figure is rounded for the ear, to about two
172
+ significant figures ($100 for 102.08, 1,900 for 1,937), with "about" typed before
173
+ it where it helps, while the stage shows the exact one. A `dash.calc` returns the
174
+ rounded number and the caption's mark names that calc (`said` in the script), so
175
+ the dashboard still checks it. A calc can return words too ("almost half"); those
176
+ it can't check. Or a caption can leave the number out and let the figure on the
177
+ stage show it. Work out each mark's cue (see Pace) after the numbers are filled,
178
+ since filling moves where the words fall. A Visual short usually tells of a
179
+ period that has ended, so pin the dates in its queries: the gist is yours, and
180
+ should stay true.
181
+
182
+ **How captions show.** The sentence being said stands alone under the headline,
183
+ as plain words, so it covers nothing drawn. Each chapter keeps a row for it
184
+ (`.vs-say`, empty in the HTML), and the script lays the caption over that row.
185
+ The row is as tall whatever is being said, and with captions off, so the drawing
186
+ never moves. On the title before Play the sentence is the first; once a chapter
187
+ is whole, the last. A CC button among the controls, `aria-pressed` and on at
188
+ first, switches captions off and on; a page may use no storage, so the choice
189
+ lasts until it is loaded again.
190
+
191
+ **Pace.** People read the caption and watch the drawing at once, so a second for
192
+ every 15 characters is comfortable: a chapter lasts its caption's length divided
193
+ by 15, in seconds, plus 1. A mark's cue is the place where its word starts in
194
+ the caption (`indexOf`), divided by 15, so no seconds are typed. A voice keeps
195
+ its own pace, which the page isn't told. So while a reading is open the script times the voice: each caption it
196
+ reads through sets the pace for the next, and every cue, the sentences' too, is
197
+ scaled by it. A mark that hasn't moved when the voice goes on is drawn whole as
198
+ it leaves. When the voice goes off, `t` is divided by the pace, so the piece goes
199
+ on from the same place. With no reading open, at a chapter's end the next starts from `t` =
200
+ 0; at the last it stops, and Play starts over.
201
+
202
+ **Controls.** Play or Pause, Back, Next and one mark per chapter let a reader
203
+ hold it and find their place; a chapter is the smallest part that makes sense
204
+ alone, so a slider adds little. The marks are a band of bars across the top of
205
+ the stage, each a button named for its chapter's label that plays from that
206
+ chapter's start, the current one with `aria-current="true"` and filling as it
207
+ plays. They stay up: they show how far the piece has got. The rest are slight:
208
+ bare, with no box around them, at the stage's top right on the label's line,
209
+ away from claude.ai's own bars under the page; on a narrow stage they take a row
210
+ of their own above the label. In order: Play or Pause (both in the HTML, one
211
+ shown), Back, Next and the speaker, which the dashboard hides where there is no
212
+ voice, each the inline SVG in the skeleton (the dashboard's own icons; a page has no icon font, so no text,
213
+ emoji or other drawing in their place) and named by an `aria-label`, the
214
+ toggle's set by the script to Play or Pause; and CC. While the piece plays they
215
+ fade as a video's controls do: as the pointer leaves the stage, or after a mouse
216
+ has lain still on it for 3 seconds. They come back when the pointer moves or
217
+ presses on the stage, or the keyboard moves focus into it. At rest, paused and
218
+ at the end they stay up, so Play can always be found; where the main pointer
219
+ can't hover, as on a phone, they never fade. They fade by `opacity`, so a
220
+ keyboard and a screen reader still reach them. With the voice on they fade and
221
+ come back the same way.
222
+
223
+ ## Handing over
224
+
225
+ Besides what `design-defaults.md` has you tell the person: how long it runs, and
226
+ that Play starts it. Of the voice, say nothing unless the person asked to listen
227
+ (`read-aloud.md`).