@tinyvolt/pie 0.0.0-stage → 0.2.0

package/src/components/SplitPane.tsx

@@ -0,0 +1,170 @@
+import { createSignal, Show, type JSX } from 'solid-js';
+import { Chevron, type Direction } from './icons';
+
+/** The edge the first pane sits against. */
+export type SplitSide = 'left' | 'right' | 'top' | 'bottom';
+type Collapsed = 'none' | 'first' | 'second';
+
+// Limits on the first pane's share, in %, while dragging.
+const MIN_PERCENT = 20;
+const MAX_PERCENT = 85;
+/** Dragging a pane below this share, in %, collapses it. */
+const SNAP_PERCENT = 8;
+
+const SIDE_DIRECTION: Record<SplitSide, Direction> = { left: 'left', right: 'right', top: 'up', bottom: 'down' };
+const OPPOSITE: Record<Direction, Direction> = { left: 'right', right: 'left', up: 'down', down: 'up' };
+const BUTTONS_TRANSFORM: Record<Direction | 'center', string> = {
+  center: 'translate(-50%, -50%)',
+  left: 'translate(-100%, -50%)',
+  right: 'translate(0, -50%)',
+  up: 'translate(-50%, -100%)',
+  down: 'translate(-50%, 0)',
+};
+
+const HIDDEN_PANE: JSX.CSSProperties = { flex: '0 0 0%', overflow: 'hidden', visibility: 'hidden' };
+
+/** The first pane's share of `rect`, in %, with the pointer at (`x`, `y`). */
+function firstPercentAt(side: SplitSide, rect: DOMRect, x: number, y: number): number {
+  const fraction = {
+    left: (x - rect.left) / rect.width,
+    right: (rect.right - x) / rect.width,
+    top: (y - rect.top) / rect.height,
+    bottom: (rect.bottom - y) / rect.height,
+  }[side];
+  return fraction * 100;
+}
+
+/**
+ * Calls `onMove` on every pointer move until the pointer is released.
+ * Listens on the window, so the drag goes on after the pointer leaves the divider.
+ * Text selection is off meanwhile, so dragging doesn't highlight page text.
+ */
+function trackDrag(onMove: (ev: PointerEvent) => void) {
+  document.body.style.userSelect = 'none';
+  const stop = () => {
+    document.body.style.userSelect = '';
+    window.removeEventListener('pointermove', onMove);
+    window.removeEventListener('pointerup', stop);
+  };
+  window.addEventListener('pointermove', onMove);
+  window.addEventListener('pointerup', stop);
+}
+
+/** The draggable bar between the panes, with a button to collapse each one. */
+function SplitDivider(props: {
+  side: SplitSide;
+  collapsed: Collapsed;
+  setCollapsed: (c: Collapsed) => void;
+  firstLabel: string;
+  secondLabel: string;
+  onPointerDown: (e: PointerEvent) => void;
+}) {
+  const isStacked = () => props.side === 'top' || props.side === 'bottom';
+  const firstDirection = () => SIDE_DIRECTION[props.side];
+  const secondDirection = () => OPPOSITE[firstDirection()];
+  // A collapsed pane's buttons sit beside the bar, on the open pane's side.
+  const buttonsTransform = () => {
+    const c = props.collapsed;
+    return BUTTONS_TRANSFORM[c === 'first' ? secondDirection() : c === 'second' ? firstDirection() : 'center'];
+  };
+  const firstButtonLabel = () => (props.collapsed === 'second' ? `Show ${props.secondLabel}` : `Hide ${props.firstLabel}`);
+  const secondButtonLabel = () => (props.collapsed === 'first' ? `Show ${props.firstLabel}` : `Hide ${props.secondLabel}`);
+
+  return (
+    <div
+      class="split-pane-divider"
+      classList={{ 'split-pane-divider--horizontal': isStacked() }}
+      onPointerDown={props.onPointerDown}
+      role="separator"
+      aria-orientation={isStacked() ? 'horizontal' : 'vertical'}
+    >
+      <div class="split-pane-buttons" style={{ transform: buttonsTransform() }}>
+        <Show when={props.collapsed !== 'first'}>
+          <button
+            class="split-pane-button"
+            onPointerDown={(e) => e.stopPropagation()}
+            onClick={() => props.setCollapsed(props.collapsed === 'second' ? 'none' : 'first')}
+            aria-label={firstButtonLabel()}
+            title={firstButtonLabel()}
+          >
+            <Chevron direction={firstDirection()} />
+          </button>
+        </Show>
+        <Show when={props.collapsed !== 'second'}>
+          <button
+            class="split-pane-button"
+            onPointerDown={(e) => e.stopPropagation()}
+            onClick={() => props.setCollapsed(props.collapsed === 'first' ? 'none' : 'second')}
+            aria-label={secondButtonLabel()}
+            title={secondButtonLabel()}
+          >
+            <Chevron direction={secondDirection()} />
+          </button>
+        </Show>
+      </div>
+    </div>
+  );
+}
+
+export interface SplitPaneProps {
+  side: SplitSide;
+  first: JSX.Element;
+  second: JSX.Element;
+  /** Names used on the collapse buttons, e.g. "Hide canvas". */
+  firstLabel: string;
+  secondLabel: string;
+  class?: string;
+}
+
+/**
+ * Two panes split by a draggable divider: `first` against `side`, `second` in the rest.
+ * Each pane can be collapsed with a button on the divider, or by dragging it nearly shut.
+ */
+export function SplitPane(props: SplitPaneProps) {
+  let ref: HTMLDivElement | undefined;
+  const [firstPercent, setFirstPercent] = createSignal(50);
+  const [collapsed, setCollapsed] = createSignal<Collapsed>('none');
+
+  const startResize = (e: PointerEvent) => {
+    e.preventDefault();
+    trackDrag((ev) => {
+      if (!ref) return;
+      const pct = firstPercentAt(props.side, ref.getBoundingClientRect(), ev.clientX, ev.clientY);
+      if (pct < SNAP_PERCENT) {
+        setCollapsed('first');
+      } else if (pct > 100 - SNAP_PERCENT) {
+        setCollapsed('second');
+      } else {
+        setCollapsed('none');
+        setFirstPercent(Math.min(MAX_PERCENT, Math.max(MIN_PERCENT, pct)));
+      }
+    });
+  };
+
+  const firstStyle = (): JSX.CSSProperties => {
+    const c = collapsed();
+    if (c === 'first') return HIDDEN_PANE;
+    if (c === 'second') return { flex: '1 1 0%' };
+    return { flex: `0 0 ${firstPercent()}%` };
+  };
+  const secondStyle = (): JSX.CSSProperties => (collapsed() === 'second' ? HIDDEN_PANE : { flex: '1 1 0%' });
+
+  return (
+    <div class={`split-pane split-pane--${props.side} ${props.class ?? ''}`} ref={ref}>
+      <div class="split-pane-pane" style={firstStyle()}>
+        {props.first}
+      </div>
+      <SplitDivider
+        side={props.side}
+        collapsed={collapsed()}
+        setCollapsed={setCollapsed}
+        firstLabel={props.firstLabel}
+        secondLabel={props.secondLabel}
+        onPointerDown={startResize}
+      />
+      <div class="split-pane-pane" style={secondStyle()}>
+        {props.second}
+      </div>
+    </div>
+  );
+}

package/src/components/icons.tsx

@@ -0,0 +1,94 @@
+import type { JSX } from 'solid-js';
+
+export type Direction = 'left' | 'right' | 'up' | 'down';
+
+const CHEVRON_TURN: Record<Direction, number> = { left: 0, up: 90, right: 180, down: 270 };
+
+/** A small arrow pointing `direction`. */
+export function Chevron(props: { direction: Direction }) {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      style={{ transform: `rotate(${CHEVRON_TURN[props.direction]}deg)` }}
+    >
+      <path d="M15 18l-6-6 6-6" />
+    </svg>
+  );
+}
+
+/** The shared frame for the icons below: 24×24 drawing, lines in the text color. */
+function Icon(props: { children: JSX.Element }) {
+  return (
+    <svg
+      class="icon"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      {props.children}
+    </svg>
+  );
+}
+
+export function PlayIcon() {
+  return (
+    <Icon>
+      <path d="M6 4l14 8-14 8z" fill="currentColor" />
+    </Icon>
+  );
+}
+
+export function StopIcon() {
+  return (
+    <Icon>
+      <rect x="5" y="5" width="14" height="14" rx="1" fill="currentColor" />
+    </Icon>
+  );
+}
+
+export function ResetIcon() {
+  return (
+    <Icon>
+      <path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8" />
+      <path d="M3 3v5h5" />
+    </Icon>
+  );
+}
+
+export function CopyIcon() {
+  return (
+    <Icon>
+      <rect x="8" y="8" width="14" height="14" rx="2" />
+      <path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" />
+    </Icon>
+  );
+}
+
+export function CheckIcon() {
+  return (
+    <Icon>
+      <path d="M20 6L9 17l-5-5" />
+    </Icon>
+  );
+}
+
+export function CrossIcon() {
+  return (
+    <Icon>
+      <path d="M18 6L6 18M6 6l12 12" />
+    </Icon>
+  );
+}

package/src/entry-client.tsx

@@ -0,0 +1,4 @@
+// @refresh reload
+import { mount, StartClient } from "@solidjs/start/client";
+
+mount(() => <StartClient />, document.getElementById("app")!);

package/src/entry-server.tsx

@@ -0,0 +1,21 @@
+// @refresh reload
+import { createHandler, StartServer } from "@solidjs/start/server";
+
+export default createHandler(() => (
+  <StartServer
+    document={({ assets, children, scripts }) => (
+      <html lang="en">
+        <head>
+          <meta charset="utf-8" />
+          <meta name="viewport" content="width=device-width, initial-scale=1" />
+          <link rel="icon" href="/favicon.ico" />
+          {assets}
+        </head>
+        <body>
+          <div id="app">{children}</div>
+          {scripts}
+        </body>
+      </html>
+    )}
+  />
+));

package/src/global.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="@solidjs/start/env" />
+
+// The root `site.yml`, turned into a module by `src/lib/site/vitePlugin.ts`.
+declare module '*/site.yml' {
+  const site: import('./lib/site/vitePlugin').Site;
+  export default site;
+}

package/src/lib/appDir.ts

@@ -0,0 +1,4 @@
+import path from 'node:path';
+
+/** The app's `src/` folder: in this repo, or in `node_modules/@tinyvolt/pie` in a site. */
+export const APP_DIR = path.resolve(import.meta.dirname, '..');

package/src/lib/autodiff/index.ts

@@ -0,0 +1,49 @@
+import { grad, numpy as np } from '@jax-js/jax';
+
+/**
+ * How to walk a graph whose items carry their own inputs.
+ * `inputs` gives undefined for an item that wasn't computed from others.
+ */
+export interface Graph<T> {
+  id: (item: T) => string;
+  inputs: (item: T) => T[] | undefined;
+  /** Computes `item` again from new inputs. */
+  recompute: (item: T, inputs: T[]) => T;
+}
+
+/**
+ * `target` computed again, with the item whose id is `varId` swapped for
+ * `replacement`. Items that don't read that item, directly or through others,
+ * are returned as they are and not recomputed.
+ */
+export function replay<T>(graph: Graph<T>, target: T, varId: string, replacement: T): T {
+  const done = new Map<string, T>();
+  const visit = (item: T): T => {
+    const id = graph.id(item);
+    if (id === varId) return replacement;
+    if (done.has(id)) return done.get(id)!;
+    const inputs = graph.inputs(item);
+    let result = item;
+    if (inputs) {
+      const newInputs = inputs.map(visit);
+      if (newInputs.some((input, i) => input !== inputs[i])) result = graph.recompute(item, newInputs);
+    }
+    done.set(id, result);
+    return result;
+  };
+  return visit(target);
+}
+
+/**
+ * df/dxᵢ for each xᵢ in `xs`.
+ *
+ * jax-js frees an array once it is used. This uses up `xs` and whatever `f`
+ * returns, so pass `.ref` copies of values you keep.
+ *
+ * Nesting works: `f` may itself call `gradient`. Any value the inner `f` reads
+ * from an outer one must be captured by `f`, not passed in as an extra argument —
+ * jax-js drops the gradient through arguments it is not differentiating.
+ */
+export function gradient(f: (...xs: np.Array[]) => np.Array, xs: np.Array[]): np.Array[] {
+  return grad(f, { argnums: xs.map((_, i) => i) })(...xs);
+}

package/src/lib/layouts/layout.ts

@@ -0,0 +1,20 @@
+import type { Component } from 'solid-js';
+
+export type LayoutModules = Record<string, { default?: Component }>;
+
+/**
+ * The default export of a `layouts/` file, given an `import.meta.glob` of that one file,
+ * or `builtIn` when the site has no such file. Throws, naming the file, when it has no default export.
+ */
+export function layout(modules: LayoutModules, builtIn: Component): Component {
+  const [entry] = Object.entries(modules);
+  if (!entry) return builtIn;
+  const [file, mod] = entry;
+  if (typeof mod.default !== 'function') throw new Error(noDefaultExport(file.slice(1)));
+  return mod.default;
+}
+
+/** Shared with `vitePlugin.ts`, so dev and build say the same thing. */
+export function noDefaultExport(file: string): string {
+  return `${file} must have a default export: a Solid component`;
+}

package/src/lib/layouts/vitePlugin.ts

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseSync, type Plugin } from 'vite';
+import { noDefaultExport } from './layout';
+
+// Each `layouts/` file that replaces a built-in part of the site.
+const LAYOUT_FILES = ['layouts/header.tsx', 'layouts/index.tsx'];
+
+/**
+ * Fails the build when a `layouts/` file has no default export.
+ * Without this, the error only stops pages from prerendering.
+ */
+export function checkLayouts(): Plugin {
+  let root = '';
+  let checked = false;
+
+  return {
+    name: 'check-layouts',
+    apply: 'build',
+    configResolved(config) {
+      root = config.root;
+    },
+    // Runs once per build environment (client, ssr, ...); one check is enough.
+    buildStart() {
+      if (checked) return;
+      checked = true;
+      const bad = LAYOUT_FILES.filter(file => {
+        const full = path.join(root, file);
+        if (!fs.existsSync(full)) return false;
+        const { module, errors } = parseSync(full, fs.readFileSync(full, 'utf8'));
+        // Vite reports syntax errors itself, with a better message.
+        if (errors.length) return false;
+        return !module.staticExports.some(e =>
+          e.entries.some(entry => entry.exportName.kind === 'Default' || entry.exportName.name === 'default'));
+      });
+      if (bad.length) this.error(bad.map(noDefaultExport).join('\n'));
+    },
+  };
+}

package/src/lib/markdown/components/CanvasPage.tsx

@@ -0,0 +1,25 @@
+import { SplitPane } from '~/components/SplitPane';
+import { NodeCanvas } from '~/lib/nodes/components/NodeCanvas';
+import { NodeStore } from '~/lib/nodes/state/NodeStore';
+import type { CanvasSide } from '../frontmatter';
+import { MarkdownBody } from './MarkdownBody';
+
+/** A canvas on `side` of the page's text. `python-editor` blocks in the text draw on it. */
+export function CanvasPage(props: { side: Exclude<CanvasSide, 'none'>; html: string }) {
+  const store = new NodeStore();
+
+  return (
+    <SplitPane
+      class="canvas-page"
+      side={props.side}
+      first={
+        <div class="canvas-page-canvas">
+          <NodeCanvas store={store} />
+        </div>
+      }
+      second={<MarkdownBody class="canvas-page-text" html={props.html} store={store} />}
+      firstLabel="canvas"
+      secondLabel="text"
+    />
+  );
+}

package/src/lib/markdown/components/MarkdownBody.tsx

@@ -0,0 +1,42 @@
+import { onCleanup, onMount } from 'solid-js';
+import { render } from 'solid-js/web';
+import type { NodeStore } from '~/lib/nodes/state/NodeStore';
+import { PythonScope } from '~/lib/python/runner';
+
+const PYTHON_EDITOR_LANG = 'python-editor';
+
+/**
+ * Rendered markdown. On the client, each ```python-editor block becomes a runnable editor;
+ * until then it shows as a plain code block. All editors on the page share Python variables.
+ * `store`: the canvas their `pie.*` calls draw on.
+ */
+export function MarkdownBody(props: { html: string; store?: NodeStore; class?: string }) {
+  let ref!: HTMLElement;
+
+  onMount(() => {
+    const blocks = ref.querySelectorAll<HTMLElement>(`pre > code.language-${PYTHON_EDITOR_LANG}`);
+    if (blocks.length === 0) return;
+
+    const scope = new PythonScope(props.store);
+    const disposers: (() => void)[] = [];
+    onCleanup(() => {
+      disposers.forEach((dispose) => dispose());
+      scope.dispose();
+    });
+
+    // Loaded only on pages that have an editor.
+    import('./PythonEditor').then(({ PythonEditor }) => {
+      blocks.forEach((codeEl) => {
+        const pre = codeEl.parentElement!;
+        if (!pre.isConnected) return;
+        const code = codeEl.textContent ?? '';
+        const collapsed = codeEl.hasAttribute('data-collapsed');
+        const host = document.createElement('div');
+        pre.replaceWith(host);
+        disposers.push(render(() => <PythonEditor code={code} collapsed={collapsed} scope={scope} />, host));
+      });
+    });
+  });
+
+  return <main ref={ref} class={props.class} innerHTML={props.html} />;
+}