@tinyvolt/pie 0.6.1 → 0.8.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 (37) hide show
  1. package/init/index.js +1 -0
  2. package/init/site-agents.md +98 -4
  3. package/package.json +2 -1
  4. package/pages/_terms.md +12 -0
  5. package/pages/about.md +1 -0
  6. package/pages/example.md +152 -19
  7. package/src/app.css +200 -0
  8. package/src/lib/markdown/components/CanvasPage.tsx +2 -0
  9. package/src/lib/markdown/components/PythonEditor.tsx +16 -0
  10. package/src/lib/markdown/features/build.ts +17 -11
  11. package/src/lib/markdown/features/glossary/View.tsx +64 -0
  12. package/src/lib/markdown/features/glossary/build.ts +89 -0
  13. package/src/lib/markdown/features/sidebar/build.ts +2 -1
  14. package/src/lib/markdown/features/tags/build.ts +22 -0
  15. package/src/lib/markdown/features/tags/pages.ts +42 -0
  16. package/src/lib/markdown/features/tags/url.ts +12 -0
  17. package/src/lib/markdown/features/views.tsx +2 -0
  18. package/src/lib/markdown/frontmatter.ts +14 -0
  19. package/src/lib/markdown/pages.ts +7 -4
  20. package/src/lib/markdown/render.ts +12 -2
  21. package/src/lib/markdown/vitePlugin.ts +14 -5
  22. package/src/lib/python/py/pie.py +42 -0
  23. package/src/lib/python/runner.ts +15 -3
  24. package/src/lib/python/worker.ts +4 -1
  25. package/src/lib/ui/UiLayer.tsx +15 -0
  26. package/src/lib/ui/UiView.tsx +74 -0
  27. package/src/lib/ui/components/checkboxes.tsx +40 -0
  28. package/src/lib/ui/components/latex.tsx +44 -0
  29. package/src/lib/ui/components/radio.tsx +25 -0
  30. package/src/lib/ui/components/slider.tsx +18 -0
  31. package/src/lib/ui/components/textbox.tsx +22 -0
  32. package/src/lib/ui/dragUi.ts +133 -0
  33. package/src/lib/ui/nodeHandle.ts +47 -0
  34. package/src/lib/ui/registry.ts +33 -0
  35. package/src/routes/_tags/[tag].tsx +47 -0
  36. package/src/routes/_tags/index.tsx +22 -0
  37. package/ui/stepper.tsx +17 -0
package/init/index.js CHANGED
@@ -14,6 +14,7 @@ const FILES = {
14
14
  'pages': 'pages',
15
15
  'functions': 'functions',
16
16
  'nodes': 'nodes',
17
+ 'ui': 'ui',
17
18
  'styles': 'styles',
18
19
  'layouts': 'layouts',
19
20
  'public': 'public',
@@ -16,9 +16,10 @@ npm run preview # preview the build with vite
16
16
 
17
17
  | Folder / file | What it holds |
18
18
  | --- | --- |
19
- | `pages/` | Markdown pages. `pages/a/b.md` is served at `/a/b`. A file whose name starts with `_`, e.g. `pages/_topics.md`, gets no URL; use it as a sidebar. |
19
+ | `pages/` | Markdown pages. `pages/a/b.md` is served at `/a/b`. A file whose name starts with `_`, e.g. `pages/_topics.md`, gets no URL; use it as a sidebar or a glossary. |
20
20
  | `functions/` | Your own TypeScript functions, called from Python as `pie.<keyword>(...)`. |
21
21
  | `nodes/` | Your own node types: what a node holds and how it is drawn. |
22
+ | `ui/` | Your own UIs for nodes, called from Python as `pie.ui.<name>(...)`. |
22
23
  | `layouts/` | Optional overrides: `header.tsx` (top of every page) and `index.tsx` (homepage, `/`). |
23
24
  | `styles/` | CSS. Every `.css` file here loads after the built-in styles, so it wins. |
24
25
  | `public/` | Static files, served as-is. |
@@ -34,7 +35,7 @@ Flat `key: value` lines. Values may be quoted. A key may appear only once.
34
35
  - `title` (required): shown in the header and in every browser tab title.
35
36
  - `url`: where the site is deployed, e.g. `https://example.com`. Needed for `sitemap.xml`, `robots.txt`, canonical links and `og:url`; without it the build skips them and warns.
36
37
  - `description`: shown in search results and link previews for a page with no `description` of its own.
37
- - `sidebar`, `toc`: the value for every page that doesn't set the key itself (see "Pages"). A `sidebar` path here is relative to the project root, e.g. `sidebar: pages/_topics.md`.
38
+ - `sidebar`, `toc`, `glossary`: the value for every page that doesn't set the key itself (see "Pages"). A `sidebar` or `glossary` path here is relative to the project root, e.g. `sidebar: pages/_topics.md`.
38
39
 
39
40
  ## Pages
40
41
 
@@ -57,12 +58,22 @@ canvas: left
57
58
  - On screens narrower than `--sidebar-drawer-below` (768px by default), it opens over the page instead. Tapping outside it or on one of its links closes it.
58
59
  - Its frontmatter is ignored. Its Python editors share variables only with each other, and have no canvas: a `pie.*` call there raises "this page has no canvas".
59
60
  - `toc`: `true` or `false`. `true` adds a table of contents of the page's `##` and `###` headings, after its leading `#` title, or at the very start if it has none. Each `###` is nested under the `##` before it. Every heading gets an `id`, and duplicate headings get `-2`, `-3`, …. No list if the page has no `##` or `###`. Left out: `site.yml`'s `toc`, else `false`.
61
+ - `glossary`: a `.md` file of terms, e.g. `glossary: _terms.md`. The path is relative to the page's file. `none`: no glossary, even when `site.yml` sets one. Left out: `site.yml`'s `glossary`.
62
+ - In that file, each `##` heading is a term, and the text up to the next `##` is its definition, in any markdown. Its `#` heading names the section at the end of the page; without one, the section is called "Glossary". Other text before the first `##` is ignored.
63
+ - In the page, `[[term]]` marks a term, and `[[shown|term]]` shows other words. Matching ignores case. `[[...]]` inside code is left alone.
64
+ - Hovering a term shows a popup with the first 4 lines of its definition and a "more" link. On touch screens, a tap shows it and a tap anywhere else hides it.
65
+ - "more" opens a collapsed section at the end of the page and scrolls to the term. The section lists only the terms the page uses, in the file's order.
66
+ - `[[...]]` only works in the page's own text. In a sidebar file, in the glossary file, or on a page without a glossary, it shows as written, brackets included.
67
+ - `tags`: hashtags separated by spaces or commas, e.g. `tags: #math #linear-algebra`. A tag is made of letters, digits, `_`, `+` and `-`, and is turned into lower case. A word that isn't a tag, e.g. `math` without its `#`, is skipped without an error.
68
+ - The page shows its tags as links at the end of its text. Each opens `/_tags/<tag>`, which lists the pages with that tag, sorted by title. A page without a `title` is listed by its URL.
69
+ - `/_tags` lists every tag and how many pages have it. Only the tag pages link to it.
70
+ - Only a page's own frontmatter counts: `tags` in `site.yml` does nothing.
60
71
 
61
72
  Other keys are ignored. A bad value fails the build, and shows an error screen in dev.
62
73
 
63
74
  Math uses KaTeX: `$…$` inline, and `$$…$$` on its own lines for a display block.
64
75
 
65
- A page's URL must not match a route in `node_modules/@tinyvolt/pie/src/routes/` (`/`, `/pages`). For example, `pages/pages.md` fails the build.
76
+ A page's URL must not match a route in `node_modules/@tinyvolt/pie/src/routes/` (`/`, `/pages`, `/_tags`, `/_tags/<tag>`). For example, `pages/pages.md` fails the build.
66
77
 
67
78
  ## Python editors
68
79
 
@@ -168,6 +179,46 @@ Limits:
168
179
  - A lifted function can't call `pie.*` or index arrays.
169
180
  - `pie.partial` can't differentiate through a lifted function.
170
181
 
182
+ ### UIs for nodes: `pie.ui`
183
+
184
+ `pie.ui.<name>(...)` shows a UI, such as a slider, for one or more nodes. The UI shows the nodes' values and updates when they change. A UI that writes, such as a slider, changes its node, and every node built from it updates:
185
+
186
+ ```python
187
+ r = pie.scalar(1, out='r')
188
+ pie.circle(pie.point(0, 0), r)
189
+ pie.ui.slider(r, min=0, max=4, label='radius')
190
+ pie.ui.latex(r)
191
+ ```
192
+
193
+ - Positional arguments are nodes, or lists of nodes at any depth. Keyword arguments are plain values, never nodes.
194
+ - Every UI takes `label='<text>'`, shown in front of it. Default: none.
195
+ - The UIs show below the editor that made them, outside its box: collapsing the editor doesn't hide them. Running the block again replaces them, instead of adding more.
196
+ - A UI hides while one of its nodes is removed, and shows again if a node with the same id comes back.
197
+ - Writing a node is like `translate_*`: the node stops following the nodes it was built from.
198
+
199
+ | Call | Shows |
200
+ | --- | --- |
201
+ | `pie.ui.slider(n, min=0, max=1, step=0.01)` | a slider for Scalar `n` |
202
+ | `pie.ui.textbox(n)` | a text box for Scalar or Text `n`. It writes on Enter or on leaving the box. Text that isn't a number puts a Scalar's value back |
203
+ | `pie.ui.radio(n, options=['a', 'b'])` | one radio button per option. Scalar `n` holds the chosen index. `options` is required |
204
+ | `pie.ui.checkboxes(mask, options=['a', 'b'])` | one checkbox per item of Array of Scalars `mask`, in row-major order: 1 when ticked, 0 when not; any value other than 0 shows ticked. `options`: one label per item; without it, the labels are the item positions |
205
+ | `pie.ui.latex(a, b, ...)` | the nodes as LaTeX, side by side. A Scalar shows its number (at most 4 decimals), a Point `(x, y)`, a Text its value as LaTeX source, an Array of 1 dimension a column and of 2 a matrix. A list of nodes is shown like an Array |
206
+
207
+ Errors:
208
+
209
+ - Python raises for an unknown UI name, an unknown node, a node in a keyword argument, or a keyword argument named `args`.
210
+ - A UI given the wrong kind of node, e.g. `pie.ui.slider(point)`, shows the error in red in its place. Python doesn't raise.
211
+ - Sidebar editors have no canvas, so `pie.ui.*` there raises "this page has no canvas".
212
+
213
+ #### Dragging UIs
214
+
215
+ **Every UI can be dragged; readers may not notice unless the text tells them.** Each UI has a grip, ⋮⋮, at its left. With a mouse it shows on hover; on touchscreens it always shows. Only the grip starts a drag, so sliders and text boxes work as usual. Dragging the grip:
216
+
217
+ - into the page's text puts the UI between two top-level blocks (paragraphs, headings, editors, …), never inside an editor. A line shows where it will land. Near the text's top or bottom edge, the text scrolls.
218
+ - onto the canvas puts the UI at that spot on the screen. Panning and zooming the canvas don't move it. Resizing the canvas keeps it inside.
219
+
220
+ A UI moves freely between the text and the canvas. Running its block again puts it back below the editor. Positions aren't saved when the page reloads.
221
+
171
222
  ## Your own functions: `functions/`
172
223
 
173
224
  Each `functions/**/*.ts` file exports one or more `Node2NodeFunc` objects. Each becomes `pie.<keyword>` in Python. Copy `functions/midpoint.ts` as a starting point:
@@ -245,6 +296,39 @@ export const Square: NodeDefinition<SquareNode> = { type: 'Square', prefix: 'sq'
245
296
  - The built-in node types are in `node_modules/@tinyvolt/pie/src/lib/nodes/state/Node.ts`, and their render functions are in `node_modules/@tinyvolt/pie/src/lib/nodes/render/renderLogic.tsx`.
246
297
  - A type name used twice, by two of your files or by yours and a built-in, fails the build.
247
298
 
299
+ ## Your own UIs: `ui/`
300
+
301
+ Each PascalCase export of a `ui/**/*.{ts,tsx}` file is a UI: a Solid component. Its Python name is the export name in snake_case: `Slider` is `pie.ui.slider`, `MatrixProduct` is `pie.ui.matrix_product`. Other exports, e.g. a camelCase helper, are ignored. Copy `ui/stepper.tsx` as a starting point:
302
+
303
+ ```tsx
304
+ import type { ScalarNode } from '~/lib/nodes/state/Node';
305
+ import { num, scalar } from '~/lib/nodes/jax';
306
+ import { expectNode, type UiArg } from '~/lib/ui/nodeHandle';
307
+
308
+ /** `pie.ui.stepper(n, step=1)`: − and + buttons that change Scalar `n` by `step`, with its value between them. */
309
+ export function Stepper(props: { args: UiArg[]; step?: number }) {
310
+ const [n, setN] = expectNode<ScalarNode>(props.args[0], ['Scalar']);
311
+ const step = props.step ?? 1;
312
+ const add = (delta: number) => setN({ value: scalar(num(n().value) + delta) });
313
+ return (
314
+ <span>
315
+ <button type="button" onClick={() => add(-step)}>−</button>
316
+ {' '}{num(n().value)}{' '}
317
+ <button type="button" onClick={() => add(step)}>+</button>
318
+ </span>
319
+ );
320
+ }
321
+ ```
322
+
323
+ - `props.args` holds the positional arguments. Each node in them is a pair `[n, setN]`, like a Solid signal: `n()` returns the node's current data; call it inside the JSX so the UI updates. `setN(changes)` writes fields of the node, e.g. `{ value: scalar(2) }`. A list stays a list of pairs.
324
+ - The keyword arguments are the other props, as plain values.
325
+ - `expectNode(arg, types)` checks that `arg` is one node of one of `types` and returns its pair. Otherwise it throws, and the UI shows the error.
326
+ - `useSetNode()` returns `setNode(node, changes)`, to write a node that isn't an argument, such as an Array's item: `setNode(array().items[i], { value: scalar(1) })`. Write an Array's items one by one: replacing the whole Array removes its item nodes and everything built from them.
327
+ - A UI that throws shows `pie.ui.<name>: <message>` in red in its place.
328
+ - Don't add a grip or a label: every UI gets both. `args` and `label` are reserved prop names.
329
+ - The built-in UIs are in `node_modules/@tinyvolt/pie/src/lib/ui/components/`.
330
+ - A name used twice, by two of your files or by yours and a built-in, raises an error when a page with a Python editor loads. It doesn't fail the build.
331
+
248
332
  ## Layouts: `layouts/`
249
333
 
250
334
  - `layouts/header.tsx`: replaces the header on every page.
@@ -258,13 +342,23 @@ Change the CSS variables in `styles/theme.css` (colors, fonts, text width), or a
258
342
 
259
343
  - Sidebar: `--sidebar-width` (default `16rem`), `--sidebar-drawer-below` (default `768px`; narrower screens open it over the page) and `--color-backdrop` (behind it when it opens over the page). Its parts have the classes `.sidebar`, `.sidebar-text`, `.sidebar-edge`, `.sidebar-toggle` and `.sidebar-backdrop`.
260
344
  - Table of contents: `.toc`.
345
+ - Glossary: `.term` (a term in the text), `.term-popup` (its popup), which holds `.term-popup-text` and `.term-more` (the "more" link), and `.glossary` (the section at the end of the page).
346
+ - Tags: `.tags` (the links at the end of a page) and `.tagged-description` (a page's description on a tag's page).
347
+ - UIs (`pie.ui.*`):
348
+ - `.python-editor-uis`: a block's UIs below its editor.
349
+ - `.python-editor-ui`: one UI, wherever it is. It holds `.python-editor-ui-grip` (the ⋮⋮ drag grip), `.python-editor-ui-label` (the `label`) and `.python-editor-ui-body` (the UI itself).
350
+ - Where it is: `main > .python-editor-ui` (dropped in the text), `.canvas-ui-layer > .python-editor-ui` (on the canvas), `.python-editor-ui-dragging` (while dragged).
351
+ - `.python-editor-ui-drop-line`: the line that shows where a dragged UI lands in the text.
352
+ - Built-in UIs: match by element, e.g. `.python-editor-ui input[type=range]` (slider), `.python-editor-ui input[type=text]` (text box), `.python-editor-ui .katex` (LaTeX). `.pie-ui-choices` holds the radio buttons or checkboxes.
353
+ - E.g. a wider slider: `.python-editor-ui input[type=range] { width: 16rem; }`. A grip that always shows: `.python-editor-ui-grip { opacity: 1; }`.
261
354
 
262
355
  ## Build checks
263
356
 
264
357
  `npm run build` fails, with a message naming the file, when:
265
358
 
266
359
  - a page's frontmatter or `site.yml` has a bad line or value, or `site.yml` has no `title`
267
- - a `sidebar` file doesn't exist or is outside the project
360
+ - a `sidebar` or `glossary` file doesn't exist or is outside the project
361
+ - a page uses a `[[term]]` its glossary file doesn't have, or that file has a term twice, ignoring case
268
362
  - a page's URL matches a route in `node_modules/@tinyvolt/pie/src/routes/`
269
363
  - a `functions/` keyword is used twice
270
364
  - a `nodes/` type name is used twice
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tinyvolt/pie",
3
- "version": "0.6.1",
3
+ "version": "0.8.0",
4
4
  "description": "A Markdown-based SSG for interactive science explainers. Create a site with: npx @tinyvolt/pie init my-site",
5
5
  "type": "module",
6
6
  "repository": {
@@ -20,6 +20,7 @@
20
20
  "pages",
21
21
  "functions",
22
22
  "nodes",
23
+ "ui",
23
24
  "styles",
24
25
  "layouts",
25
26
  "public",
@@ -0,0 +1,12 @@
1
+ ## Gradient
2
+ The vector of partial derivatives of a function, $\nabla f = (\partial f / \partial x_1, \dots, \partial f / \partial x_n)$. It points in the direction in which the function grows fastest, and its length is how fast it grows in that direction.
3
+
4
+ At a minimum or maximum, the gradient is zero. Gradient descent uses this: it steps against the gradient, again and again, until the steps get tiny.
5
+
6
+ A third paragraph, so the popup has to cut the text off. It should end in "…" after four lines.
7
+
8
+ ## Node
9
+ One shape or value on the canvas.
10
+
11
+ ## Slider
12
+ A UI that sets a [[node]]'s value by dragging.
package/pages/about.md CHANGED
@@ -1,6 +1,7 @@
1
1
  ---
2
2
  title: About
3
3
  sidebar: _topics.md
4
+ tags: #math
4
5
  ---
5
6
 
6
7
  # About
package/pages/example.md CHANGED
@@ -1,41 +1,174 @@
1
1
  ---
2
2
  toc: true
3
3
  sidebar: _topics.md
4
+ canvas: right
5
+ glossary: _terms.md
4
6
  ---
5
- # Table of contents test
6
7
 
7
- ### Before any h2
8
+ ## Heading
8
9
 
9
- Should be a top-level entry.
10
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit, the [[gradient]] of a long sentence that wraps onto the next line near the edge of the text, [[Gradient]].
10
11
 
11
- ## The $\nabla$ operator
12
+ Lorem ipsum dolor [[nodes|node]] sit amet, consectetur adipiscing elit, [[slider]].
12
13
 
13
- Math in a heading.
14
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit.
14
15
 
15
- ### Sub *one*
16
+ ---
16
17
 
17
- Nested under the operator.
18
+ ## Generative UI
18
19
 
19
- ### Sub two
20
+ Run the blocks in order. Most examples start with `pie.clear()`, which removes every node, so the UIs of earlier examples hide.
20
21
 
21
- Also nested.
22
+ ### One Scalar, three UIs
22
23
 
23
- ## Repeat
24
+ Move the slider: the text box, the LaTeX and the circle follow. Type `2.5` in the text box and press Enter: the slider moves. Collapse the editor: the UIs stay. Run it again: the UIs are replaced, not doubled.
24
25
 
25
- First "Repeat", links to `#repeat`.
26
+ ```python-editor
27
+ r = pie.scalar(1, out='r')
28
+ c = pie.point(0, 0, out='c')
29
+ pie.circle(c, r)
30
+ pie.ui.slider(r, min=0, max=4, label='radius')
31
+ pie.ui.textbox(r)
32
+ pie.ui.latex(r)
33
+ ```
26
34
 
27
- ## Repeat
35
+ A UI for `r` from another block. It stays in sync with the ones above.
28
36
 
29
- Second "Repeat", links to `#repeat-2`.
37
+ ```python-editor
38
+ pie.ui.slider(r, min=0, max=4, step=0.5)
39
+ ```
30
40
 
31
- #### Deep
41
+ Remove `r`: its UIs in both blocks hide, and so does the circle. Run the first block again to bring them back.
32
42
 
33
- Not listed: only `##` and `###` are.
43
+ ```python-editor
44
+ pie.remove(r)
45
+ ```
34
46
 
35
- ## Last
47
+ ### Radio and slider: pick a function
36
48
 
37
- Lorem ipsum dolor sit amet, consectetur adipiscing elit.
49
+ The radio button sets `choice` to 0, 1 or 2. The slider sets the amplitude.
38
50
 
39
- Lorem ipsum dolor sit amet, consectetur adipiscing elit.
51
+ ```python-editor
52
+ import numpy as np
53
+ pie.clear()
54
+ choice = pie.scalar(0, out='choice')
55
+ amp = pie.scalar(1, out='amp')
40
56
 
41
- Lorem ipsum dolor sit amet, consectetur adipiscing elit.
57
+ def curve(k, a):
58
+ xs = np.linspace(-4, 4, 81)
59
+ f = [np.sin, np.cos, np.tanh][int(k)]
60
+ return np.stack([xs, a * f(xs)], axis=1)
61
+
62
+ pie.lift(curve, pie.Array[pie.Point])(choice, amp)
63
+ pie.ui.radio(choice, options=['sin', 'cos', 'tanh'])
64
+ pie.ui.slider(amp, min=-2, max=2, label='amplitude')
65
+ pie.ui.latex(choice, amp)
66
+ ```
67
+
68
+ ### Checkboxes: build a square wave
69
+
70
+ Each checkbox adds one odd harmonic. Tick them all to get close to a square wave.
71
+
72
+ ```python-editor
73
+ import numpy as np
74
+ pie.clear()
75
+ harmonics = pie.scalar([1, 0, 0, 0, 0], out='harmonics')
76
+
77
+ def wave(mask):
78
+ xs = np.linspace(-4, 4, 161)
79
+ ys = sum(m * np.sin((2 * k + 1) * xs) / (2 * k + 1) for k, m in enumerate(mask))
80
+ return np.stack([xs, 4 / np.pi * ys], axis=1)
81
+
82
+ pie.lift(wave, pie.Array[pie.Point])(harmonics)
83
+ pie.ui.checkboxes(harmonics, options=['sin x', 'sin 3x', 'sin 5x', 'sin 7x', 'sin 9x'])
84
+ pie.ui.latex(harmonics)
85
+ ```
86
+
87
+ ### Text box and slider: a label on the canvas
88
+
89
+ ```python-editor
90
+ pie.clear()
91
+ label = pie.text('Hello', out='label')
92
+ size = pie.scalar(24, out='size')
93
+ pie.text(label, 0, 0, size)
94
+ pie.ui.textbox(label)
95
+ pie.ui.slider(size, min=8, max=60, step=1, label='font size')
96
+ ```
97
+
98
+ ### Text box and LaTeX: a live formula
99
+
100
+ A Text node holds LaTeX source. Edit it and press Enter.
101
+
102
+ ```python-editor
103
+ formula = pie.text(r'e^{i\pi} + 1 = 0', out='formula')
104
+ pie.ui.textbox(formula)
105
+ pie.ui.latex(formula)
106
+ ```
107
+
108
+ ### Matrix playground
109
+
110
+ `q = m p`. The sliders set the items of `m`. Drag `p` on the canvas: the LaTeX and `q` follow.
111
+
112
+ ```python-editor
113
+ import numpy as np
114
+ pie.clear()
115
+ m = pie.scalar([[1, 0], [0, 1]], out='m')
116
+ o = pie.point(0, 0, out='o')
117
+ p = pie.point(1, 1, out='p')
118
+
119
+ def apply(m, p):
120
+ return tuple(m @ np.array(p))
121
+
122
+ q = pie.lift(apply, pie.Point)(m, p, out='q', fill='crimson')
123
+ pie.line(o, p)
124
+ pie.line(o, q, stroke='crimson')
125
+ eq = pie.text('=', out='eq')
126
+ pie.ui.latex(m, p, eq, q)
127
+ for i in range(2):
128
+ for j in range(2):
129
+ pie.ui.slider(m[i, j], min=-2, max=2, label=f'm[{i}, {j}]')
130
+ ```
131
+
132
+ ### Canvas controls
133
+
134
+ UIs on the system nodes. Zooming or panning the canvas moves the sliders too. `pie.clear()` resets these nodes, and the UIs keep following them.
135
+
136
+ ```python-editor
137
+ pie.ui.radio(pie.get_node('gridOpacity'), options=['grid off', 'grid on'])
138
+ pie.ui.slider(pie.get_node('unit'), min=10, max=120, step=1, label='zoom')
139
+ pie.ui.slider(pie.get_node('originX'), min=-5, max=5, label='origin x')
140
+ pie.ui.slider(pie.get_node('originY'), min=-5, max=5, label='origin y')
141
+ ```
142
+
143
+ ### A UI from `/ui`
144
+
145
+ `Stepper` in `ui/stepper.tsx` is a site's own UI. Its buttons and the slider stay in sync.
146
+
147
+ ```python-editor
148
+ pie.clear()
149
+ k = pie.scalar(2, out='k')
150
+ pie.circle(pie.point(0, 0), k)
151
+ pie.ui.stepper(k, step=0.5, label='radius')
152
+ pie.ui.slider(k, min=0, max=5)
153
+ ```
154
+
155
+ ### Errors
156
+
157
+ A wrong node type: the error shows in red below the editor. Python doesn't raise.
158
+
159
+ ```python-editor
160
+ pie.ui.slider(pie.point(0, 0))
161
+ ```
162
+
163
+ An unknown UI: Python raises.
164
+
165
+ ```python-editor
166
+ pie.ui.dial(pie.scalar(1))
167
+ ```
168
+
169
+ A node in a keyword argument: Python raises.
170
+
171
+ ```python-editor
172
+ n = pie.scalar(1)
173
+ pie.ui.slider(n, max=n)
174
+ ```
package/src/app.css CHANGED
@@ -254,6 +254,7 @@ main .katex-display {
254
254
  }
255
255
 
256
256
  .canvas-page-canvas {
257
+ position: relative;
257
258
  height: 100%;
258
259
  }
259
260
 
@@ -384,6 +385,106 @@ main .katex-display {
384
385
  text-decoration: underline;
385
386
  }
386
387
 
388
+ /* `tags: #math`: the page's tags, at the end of its text. */
389
+ .tags {
390
+ display: flex;
391
+ flex-wrap: wrap;
392
+ gap: 0.25rem 0.75rem;
393
+ margin: 2rem 0 1rem;
394
+ font-size: 0.95em;
395
+ }
396
+
397
+ .tags a {
398
+ text-decoration: none;
399
+ }
400
+
401
+ .tags a:hover {
402
+ color: var(--color-hover, #000);
403
+ text-decoration: underline;
404
+ }
405
+
406
+ /* A page's description in the list of pages with a tag. */
407
+ .tagged-description {
408
+ margin: 0;
409
+ color: var(--color-muted, #555);
410
+ font-size: 0.95em;
411
+ }
412
+
413
+ /* `glossary: _terms.md`: a term in the text. */
414
+ .term {
415
+ text-decoration: underline dotted;
416
+ text-underline-offset: 0.15em;
417
+ cursor: pointer;
418
+ }
419
+
420
+ /* GlossaryView sets its top or bottom, and `--term-left`. It stays on screen, at most 22rem wide. */
421
+ .term-popup {
422
+ --term-popup-width: min(22rem, 100vw - 2rem);
423
+ display: none;
424
+ position: fixed;
425
+ z-index: 30;
426
+ left: clamp(1rem, var(--term-left), 100vw - 1rem - var(--term-popup-width));
427
+ box-sizing: border-box;
428
+ width: var(--term-popup-width);
429
+ padding: 0.5rem 0.75rem;
430
+ background: var(--color-bg, #fff);
431
+ border: 1px solid var(--color-border, #ddd);
432
+ border-radius: 4px;
433
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
434
+ font-size: 0.9rem;
435
+ font-style: normal;
436
+ font-weight: normal;
437
+ cursor: auto;
438
+ }
439
+
440
+ @media (hover: hover) {
441
+ .term:hover > .term-popup {
442
+ display: block;
443
+ }
444
+ }
445
+
446
+ .term--open > .term-popup {
447
+ display: block;
448
+ }
449
+
450
+ /* The first 4 lines of the definition, then "…". */
451
+ .term-popup-text {
452
+ display: -webkit-box;
453
+ -webkit-box-orient: vertical;
454
+ -webkit-line-clamp: 4;
455
+ line-clamp: 4;
456
+ overflow: hidden;
457
+ }
458
+
459
+ .term-popup-text > * {
460
+ margin: 0;
461
+ }
462
+
463
+ .term-more {
464
+ color: var(--color-muted, #555);
465
+ }
466
+
467
+ /* The page's glossary, at its end, collapsed. */
468
+ .glossary {
469
+ margin: 2rem 0 0;
470
+ padding-top: 1rem;
471
+ border-top: 1px solid var(--color-border, #ddd);
472
+ }
473
+
474
+ .glossary summary {
475
+ cursor: pointer;
476
+ font-weight: 600;
477
+ }
478
+
479
+ .glossary dt {
480
+ margin-top: 1rem;
481
+ font-weight: 600;
482
+ }
483
+
484
+ .glossary dd {
485
+ margin: 0.25rem 0 0;
486
+ }
487
+
387
488
  /* Hidden until MarkdownBody swaps it for the editor; keeps its space so the text below doesn't jump. */
388
489
  pre:has(> code.language-python-editor) {
389
490
  visibility: hidden;
@@ -513,6 +614,105 @@ pre:has(> code.language-python-editor) {
513
614
  color: var(--color-error, #c00);
514
615
  }
515
616
 
617
+ /* Outside the editor's box, so collapsing the editor keeps them. */
618
+ .python-editor-uis {
619
+ margin: 1rem 0;
620
+ }
621
+
622
+ /* Hidden when its UIs were all dragged away. */
623
+ .python-editor-uis:not(:has(.python-editor-ui)) {
624
+ display: none;
625
+ }
626
+
627
+ /* A UI: a grip to drag it, then the UI. */
628
+ .python-editor-ui {
629
+ display: flex;
630
+ align-items: center;
631
+ gap: 0.25rem;
632
+ margin: 0.25rem 0;
633
+ }
634
+
635
+ /* Dropped into the page's text. */
636
+ main > .python-editor-ui {
637
+ margin: 1rem 0;
638
+ }
639
+
640
+ /* One of its nodes is removed. */
641
+ .python-editor-ui-hidden {
642
+ display: none;
643
+ }
644
+
645
+ .python-editor-ui-grip {
646
+ padding: 0 0.125rem;
647
+ color: var(--color-subtle, #666);
648
+ line-height: 1;
649
+ cursor: grab;
650
+ user-select: none;
651
+ /* A touch drag moves the UI, not the page. */
652
+ touch-action: none;
653
+ opacity: 0;
654
+ }
655
+
656
+ .python-editor-ui:hover > .python-editor-ui-grip,
657
+ .python-editor-ui-dragging > .python-editor-ui-grip {
658
+ opacity: 1;
659
+ }
660
+
661
+ .python-editor-ui-label {
662
+ white-space: nowrap;
663
+ }
664
+
665
+ /* Touchscreens have no hover. */
666
+ @media (hover: none) {
667
+ .python-editor-ui-grip {
668
+ opacity: 1;
669
+ }
670
+ }
671
+
672
+ /* Floating over the page while dragged, or on the canvas: a box, so it reads over anything under it. */
673
+ .python-editor-ui-dragging,
674
+ .canvas-ui-layer > .python-editor-ui {
675
+ margin: 0;
676
+ padding: 0.25rem 0.5rem;
677
+ background: var(--color-bg, #fff);
678
+ border: 1px solid var(--color-border, #ddd);
679
+ border-radius: 4px;
680
+ }
681
+
682
+ .python-editor-ui-dragging {
683
+ z-index: 1000;
684
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
685
+ cursor: grabbing;
686
+ }
687
+
688
+ /* Where a dragged UI lands in the text. */
689
+ .python-editor-ui-drop-line {
690
+ position: fixed;
691
+ z-index: 1000;
692
+ height: 2px;
693
+ margin-top: -1px;
694
+ background: var(--color-hover, #000);
695
+ pointer-events: none;
696
+ }
697
+
698
+ /* Lets clicks through to the canvas, except on the UIs in it. */
699
+ .canvas-ui-layer {
700
+ position: absolute;
701
+ inset: 0;
702
+ overflow: hidden;
703
+ pointer-events: none;
704
+ }
705
+
706
+ .canvas-ui-layer > * {
707
+ pointer-events: auto;
708
+ }
709
+
710
+ .pie-ui-choices {
711
+ display: inline-flex;
712
+ flex-wrap: wrap;
713
+ gap: 0.75rem;
714
+ }
715
+
516
716
  .python-editor-note {
517
717
  color: var(--color-subtle, #666);
518
718
  }
@@ -1,6 +1,7 @@
1
1
  import { SplitPane } from '~/components/SplitPane';
2
2
  import { NodeCanvas } from '~/lib/nodes/components/NodeCanvas';
3
3
  import { NodeStore } from '~/lib/nodes/state/NodeStore';
4
+ import { UiLayer } from '~/lib/ui/UiLayer';
4
5
  import type { CanvasSide } from '../frontmatter';
5
6
  import { MarkdownBody } from './MarkdownBody';
6
7
 
@@ -15,6 +16,7 @@ export function CanvasPage(props: { side: Exclude<CanvasSide, 'none'>; html: str
15
16
  first={
16
17
  <div class="canvas-page-canvas">
17
18
  <NodeCanvas store={store} />
19
+ <UiLayer />
18
20
  </div>
19
21
  }
20
22
  second={<MarkdownBody class="canvas-page-text" html={props.html} store={store} />}