diff --git a/kit/src/sim/sim.css b/kit/src/sim/sim.css index 587fbec..1cd738d 100644 --- a/kit/src/sim/sim.css +++ b/kit/src/sim/sim.css @@ -21,6 +21,19 @@ .cl-sim *::after { box-sizing: inherit; } +/* The host page's element styles (a font or padding on every p, a centred + main) stop at the view: its own classes style what's inside. */ +.cl-sim { + text-align: left; +} +.cl-sim p, +.cl-sim a, +.cl-sim label, +.cl-sim span { + font-family: inherit; + color: inherit; + padding: 0; +} /* general utilities the view uses */ .cl-sim .is-hidden { @@ -921,3 +934,36 @@ .cl-sim .insp-crumb:hover { color: var(--accent); } + +/* ── lesson layout ─────────────────────────────────────────────────────── + One column (canvas, inspector, frames) that grows with its content, to sit + in a page rather than fill a window. */ +.cl-sim.lesson { + height: auto; + grid-template-columns: 1fr; + grid-template-rows: auto auto auto; + grid-template-areas: + "canvas" + "inspector" + "frames"; + border: 1px solid var(--border); + border-radius: 8px; + overflow: hidden; +} +.cl-sim.lesson .sim-canvas { + overflow: hidden; +} +.cl-sim.lesson .sim-inspector-wrap { + border-top: 1px solid var(--border); +} +.cl-sim.lesson .sim-frames { + border-top: 1px solid var(--border); + max-height: 16rem; +} +.cl-sim.lesson .sim-node-group, +.cl-sim.lesson .sim-wire .wire-hit { + cursor: default; +} +.cl-sim .clock-bar:empty { + display: none; +} diff --git a/kit/src/sim/ui/framelog.ts b/kit/src/sim/ui/framelog.ts index 4ee261c..382293c 100644 --- a/kit/src/sim/ui/framelog.ts +++ b/kit/src/sim/ui/framelog.ts @@ -105,7 +105,14 @@ function storedHeight(): number | null { } } -export function frameLog(): FrameLog { +export interface FrameLogOpts { + /** A grip that resizes the `.sim` grid's bottom row, and the height kept + * from last time. Default true; off in a layout that isn't that grid. */ + resizable?: boolean; +} + +export function frameLog(opts: FrameLogOpts = {}): FrameLog { + const resizable = opts.resizable ?? true; const el = document.createElement("div"); el.className = "sim-frames"; @@ -126,7 +133,7 @@ export function frameLog(): FrameLog { /* private mode — just don't persist */ } }; - const saved = storedHeight(); + const saved = resizable ? storedHeight() : null; if (saved !== null && typeof requestAnimationFrame === "function") { const apply = () => (el.closest(".sim") ? applyHeight(saved) : requestAnimationFrame(apply)); requestAnimationFrame(apply); @@ -216,7 +223,8 @@ export function frameLog(): FrameLog { const list = document.createElement("div"); list.className = "sim-frames-list"; list.append(table); - el.append(grip, head, list); + if (resizable) el.append(grip); + el.append(head, list); let sources: LogSource[] = []; let api: FrameSource = { frames: () => [], detail: () => null }; diff --git a/kit/src/sim/ui/view.ts b/kit/src/sim/ui/view.ts index 9d59171..12b3511 100644 --- a/kit/src/sim/ui/view.ts +++ b/kit/src/sim/ui/view.ts @@ -123,6 +123,21 @@ export interface SimOpts { * `comline-web-kit/sim/scripted`, or a test's own. Without it, the * `script` behaviour isn't offered. */ loadScripted?: () => Promise<{ Sim: typeof Sim }>; + /** `"sandbox"` (the default) is the playground's: a palette, a free canvas + * and every control. `"lesson"` is a fixed scene for a guided page, given + * by the session link passed to `setShape`. It has no palette, nothing on + * the canvas can be added, moved, connected, renamed or removed, the + * inspector shows only a server's behaviours and a client's calls, and the + * canvas, inspector and frames stack in one column. */ + layout?: "sandbox" | "lesson"; + /** The behaviour kinds a server offers, out of the engine's catalog. The + * one already set is always offered. Default: all of them. */ + behaviours?: string[]; + /** The clock bar above the frames (clock mode, seed, link, record and + * replay). Default: shown in a sandbox, hidden in a lesson. */ + clock?: boolean; + /** The instance to select once `setShape` loads a session, by id or name. */ + select?: string; } export function createSim(opts: SimOpts = {}): SimView { @@ -173,7 +188,13 @@ export function createSim(opts: SimOpts = {}): SimView { const sessionHasScript = () => !!model?.instances.some((i) => Object.values(i.behaviors).some((b) => b.kind === "script")); - const el = div("cl-sim sim"); + // A lesson is a fixed scene: everything that edits the topology is left out, + // and the parts stack instead of sitting in the sandbox's grid. + const lesson = opts.layout === "lesson"; + const showClock = opts.clock ?? !lesson; + const offered = opts.behaviours ? new Set(opts.behaviours) : null; + + const el = div(lesson ? "cl-sim sim lesson" : "cl-sim sim"); const paletteEl = div("sim-col sim-palette"); const canvasEl = div("sim-col sim-canvas"); const inspectorEl = div("sim-col sim-inspector"); @@ -181,20 +202,25 @@ export function createSim(opts: SimOpts = {}): SimView { const inspectorWrap = div("sim-inspector-wrap"); const inspectorGrip = div("sim-inspector-grip"); inspectorGrip.title = "drag to resize"; - inspectorWrap.append(inspectorGrip, inspectorEl); + inspectorWrap.append(...(lesson ? [] : [inspectorGrip]), inspectorEl); const wireSvg = document.createElementNS(SVGNS, "svg"); wireSvg.setAttribute("class", "sim-wire"); canvasEl.append(wireSvg); - const flog = frameLog(); + const flog = frameLog({ resizable: !lesson }); + /** The clock bar, unless this view hides it. */ + const paintClock = () => { + if (showClock) flog.setClockBar(clockBar()); + }; el.append( - labelled("palette", paletteEl), + ...(lesson ? [] : [labelled("palette", paletteEl)]), labelled("canvas", canvasEl), inspectorWrap, flog.el, ); - const onResize = () => drawWires(); + // a lesson re-fits its scene to the new width; a sandbox only redraws wires + const onResize = () => (lesson ? renderCanvas() : drawWires()); window.addEventListener("resize", onResize); // ── inspector resize grip ──────────────────────────────────────────── @@ -220,7 +246,7 @@ export function createSim(opts: SimOpts = {}): SimView { } drawWires(); }; - const savedInspectorWidth = storedInspectorWidth(); + const savedInspectorWidth = lesson ? null : storedInspectorWidth(); if (savedInspectorWidth !== null) applyInspectorWidth(savedInspectorWidth); inspectorGrip.addEventListener("pointerdown", (e) => { e.preventDefault(); @@ -259,7 +285,7 @@ export function createSim(opts: SimOpts = {}): SimView { // ── palette ────────────────────────────────────────────────────────── function renderPalette() { paletteEl.replaceChildren(); - if (!shape) return; + if (!shape || lesson) return; for (const schema of shape.schemas) { for (const protocol of schema.protocols) { const group = div("palette-group"); @@ -323,7 +349,7 @@ export function createSim(opts: SimOpts = {}): SimView { e.preventDefault(); clearDropTarget(); const raw = e.dataTransfer?.getData("application/json"); - if (!raw || !sim || !model) return; + if (!raw || !sim || !model || lesson) return; const spec = JSON.parse(raw) as { schemaNs: string; protocol: string; role: Role }; const ontoNode = (e.target as HTMLElement | null)?.closest(".sim-node-group"); const p = canvasPoint(e); @@ -385,21 +411,66 @@ export function createSim(opts: SimOpts = {}): SimView { function renderCanvas() { for (const g of [...canvasEl.querySelectorAll(".sim-node-group")]) g.remove(); if (!model) return; + lessonFit = lesson ? fitScene(model.nodes) : null; + // not laid out yet (the page hasn't attached the view): fit once it is + if (lesson && !lessonFit && model.nodes.length && typeof requestAnimationFrame === "function") { + requestAnimationFrame(() => { + if (canvasEl.clientWidth) renderCanvas(); + }); + } for (const nd of model.nodes) canvasEl.append(groupCard(nd)); - dropHint.hidden = model.nodes.length > 0; + dropHint.hidden = lesson || model.nodes.length > 0; + // A lesson's canvas isn't a grid cell that fills the view, so it grows to + // hold the scene's boxes (placed absolutely). + if (lesson) { + const bottom = Math.max(0, ...model.nodes.map((n) => at(n).y + 64 * n.instanceIds.length)); + canvasEl.style.minHeight = `${bottom + 24}px`; + } drawWires(); } + // A lesson's scene comes from a session link, placed for some other width. + // `fitScene` maps it onto this canvas: the boxes keep their order and rows, + // horizontal gaps shrink when the scene is wider than the canvas, and the + // whole is centred. Without a laid-out canvas (width 0), positions stay. + const BOX_W = 156; + const FIT_MARGIN = 16; + let lessonFit: ((nd: ModelNode) => { x: number; y: number }) | null = null; + const at = (nd: ModelNode) => (lessonFit ? lessonFit(nd) : { x: nd.x, y: nd.y }); + function fitScene(nodes: ModelNode[]): ((nd: ModelNode) => { x: number; y: number }) | null { + const width = canvasEl.clientWidth; + if (!width || nodes.length === 0) return null; + const minX = Math.min(...nodes.map((n) => n.x)); + const minY = Math.min(...nodes.map((n) => n.y)); + const span = Math.max(...nodes.map((n) => n.x)) - minX; + const room = Math.max(0, width - 2 * FIT_MARGIN - BOX_W); + const scale = span > room ? room / span : 1; + const left = Math.max(FIT_MARGIN, (width - (span * scale + BOX_W)) / 2); + return (nd) => ({ + x: Math.round(left + (nd.x - minX) * scale), + y: Math.round(FIT_MARGIN + nd.y - minY), + }); + } + function groupCard(nd: ModelNode): HTMLElement { const g = div("sim-node-group"); g.dataset.nodeId = nd.id; - g.style.left = `${nd.x}px`; - g.style.top = `${nd.y}px`; + const pos = at(nd); + g.style.left = `${pos.x}px`; + g.style.top = `${pos.y}px`; if (nd.id === selectedNodeId) g.classList.add("selected"); const cap = div("group-cap mono"); const count = nd.instanceIds.length > 1 ? ` · ${nd.instanceIds.length}` : ""; cap.textContent = nd.label + count; + g.append(cap); + for (const id of nd.instanceIds) { + const i = inst(id); + if (i) g.append(instRow(i)); + } + // In a lesson the box is a fixed label: only its instances are clickable. + if (lesson) return g; + cap.title = "click to select the box · double-click to rename"; cap.addEventListener("click", () => selectNode(nd.id)); cap.addEventListener("dblclick", (e) => { @@ -421,12 +492,6 @@ export function createSim(opts: SimOpts = {}): SimView { input.focus?.(); input.select?.(); }); - g.append(cap); - - for (const id of nd.instanceIds) { - const i = inst(id); - if (i) g.append(instRow(i)); - } g.addEventListener("pointerdown", (e) => startGroupDrag(e, nd, g)); return g; } @@ -443,15 +508,19 @@ export function createSim(opts: SimOpts = {}): SimView { const sub = document.createElement("div"); sub.className = "node-sub mono"; sub.textContent = `${i.protocol} · ${i.role}`; - const port = div("node-port"); - port.title = "drag to a partner to connect"; - n.append(name, sub, port); - + n.append(name, sub); n.addEventListener("click", () => select(i.id)); - port.addEventListener("pointerdown", (e) => { - e.stopPropagation(); - startConnectDrag(e, i); - }); + // A lesson's connections are given, so its rows have no port to drag from + // (a wire then attaches to the row itself, see `portAnchor`). + if (!lesson) { + const port = div("node-port"); + port.title = "drag to a partner to connect"; + n.append(port); + port.addEventListener("pointerdown", (e) => { + e.stopPropagation(); + startConnectDrag(e, i); + }); + } n.addEventListener("pointerenter", () => (hoverId = i.id)); n.addEventListener("pointerleave", () => { if (hoverId === i.id) hoverId = null; @@ -569,7 +638,7 @@ export function createSim(opts: SimOpts = {}): SimView { ln.setAttribute("y1", String(a.y)); ln.setAttribute("x2", String(b.x)); ln.setAttribute("y2", String(b.y)); - ln.addEventListener("click", () => selectConn(conn.id)); + if (!lesson) ln.addEventListener("click", () => selectConn(conn.id)); } wireSvg.append(hit, vis); } @@ -637,7 +706,7 @@ export function createSim(opts: SimOpts = {}): SimView { if (!sim) return; if (on) sim.record_start(); else lastRecording = JSON.parse(sim.record_stop()) as Recording; - flog.setClockBar(clockBar()); + paintClock(); }, onReplay: () => { if (lastRecording) void replayInView(lastRecording); @@ -687,21 +756,21 @@ export function createSim(opts: SimOpts = {}): SimView { afterAdvance(); if (sim.pending() === 0) pause(); }, 32); - flog.setClockBar(clockBar()); + paintClock(); } function pause() { if (playHandle !== null) { clearInterval(playHandle); playHandle = null; } - flog.setClockBar(clockBar()); + paintClock(); } /** Poll for settled calls + new frames after the clock moved. */ function afterAdvance() { settlePending(); flog.poll(); - flog.setClockBar(clockBar()); + paintClock(); } function errorName(throws: ThrowShape[], ordinal: number): string | undefined { @@ -758,7 +827,7 @@ export function createSim(opts: SimOpts = {}): SimView { refresh(); renderPalette(); flog.setSources(logSources(), frameApi); - flog.setClockBar(clockBar()); + paintClock(); renderCanvas(); renderInspector(); } @@ -811,7 +880,7 @@ export function createSim(opts: SimOpts = {}): SimView { } const box = node(sel.nodeId); - if (box) { + if (box && !lesson) { const crumb = document.createElement("button"); crumb.className = "insp-crumb"; crumb.textContent = `▸ in box ${box.label}`; @@ -945,10 +1014,16 @@ export function createSim(opts: SimOpts = {}): SimView { sel.role === "client" && connsFor(sel.id).some((c) => live(c.id)) ? mkPanel("call") : null; if (callPanel) callPanel.append(renderCallForm(sel)); - const panels: HTMLElement[] = [instPanel, connPanel, behPanel, callPanel].filter( - (p): p is HTMLDivElement => p !== null, - ); - if (!panels.some((p) => p.dataset.tab === inspectorTab)) inspectorTab = "instance"; + // A lesson keeps what its reader acts on: a server's behaviours and a + // client's calls. + const panels: HTMLElement[] = ( + lesson ? [behPanel, callPanel] : [instPanel, connPanel, behPanel, callPanel] + ).filter((p): p is HTMLDivElement => p !== null); + if (panels.length === 0) { + inspectorEl.append(muted(`${sel.name} has nothing to do here yet`)); + return; + } + if (!panels.some((p) => p.dataset.tab === inspectorTab)) inspectorTab = panels[0].dataset.tab!; const tabs = div("insp-tabs"); for (const p of panels) { @@ -1231,7 +1306,8 @@ export function createSim(opts: SimOpts = {}): SimView { }[] ) // `script` lazy-loads its wasm on first pick, so it needs a loader - .filter((e) => e.applies && (e.kind !== "script" || loadScripted !== null)); + .filter((e) => e.applies && (e.kind !== "script" || loadScripted !== null)) + .filter((e) => !offered || offered.has(e.kind) || e.kind === setting().kind); const wrap = div("behavior-row"); const head = div("behavior-head"); @@ -1468,6 +1544,8 @@ export function createSim(opts: SimOpts = {}): SimView { "title", "run this call over every framing/codec combo and compare the replies", ); + // comparing framings and codecs is a sandbox tool, not a lesson's + if (lesson) btns.lastElementChild!.remove(); b.append(btns, out, compareOut); return b; }; @@ -1498,7 +1576,7 @@ export function createSim(opts: SimOpts = {}): SimView { selectedNodeId = null; } flog.setSources(logSources(), frameApi); - flog.setClockBar(clockBar()); + paintClock(); renderCanvas(); renderInspector(); } @@ -1508,7 +1586,7 @@ export function createSim(opts: SimOpts = {}): SimView { refresh(); renderCanvas(); renderInspector(); - flog.setClockBar(clockBar()); + paintClock(); } return { @@ -1523,9 +1601,13 @@ export function createSim(opts: SimOpts = {}): SimView { } catch { sim = new SimClass(shapeJson); } - selectedId = null; selectedConnId = null; selectedNodeId = null; + refresh(); + const wanted = opts.select; + selectedId = wanted + ? (model?.instances.find((i) => i.id === wanted || i.name === wanted)?.id ?? null) + : null; renderPalette(); redraw(); // A restored link may carry `script` behaviours the lean wasm only stubs — @@ -1539,11 +1621,11 @@ export function createSim(opts: SimOpts = {}): SimView { if (!sim) return null; if (on) { sim.record_start(); - flog.setClockBar(clockBar()); + paintClock(); return null; } lastRecording = JSON.parse(sim.record_stop()) as Recording; - flog.setClockBar(clockBar()); + paintClock(); return lastRecording; }, async replay(rec) { diff --git a/kit/src/sim/view.test.ts b/kit/src/sim/view.test.ts index 4397b3c..639f515 100644 --- a/kit/src/sim/view.test.ts +++ b/kit/src/sim/view.test.ts @@ -1226,3 +1226,104 @@ test( sim.destroy(); }, ); + +// ── lesson layout ──────────────────────────────────────────────────── +/** A connected server + client, built in a sandbox and handed over as the + * session link a lesson starts from (what a tutorial ships). */ +function lessonLink(): { link: string; client: string } { + const sandbox = createSim(); + document.body.append(sandbox.el); + sandbox.setShape(shape()); + const { server, client } = place(sandbox); + fire(client, "click"); + pick(sandbox.el.querySelector(".connect-sel") as HTMLSelectElement, server.dataset.id!); + const link = sandbox.serialize(); + const name = client.querySelector(".node-name")!.textContent!; + sandbox.destroy(); + sandbox.el.remove(); + return { link, client: name }; +} + +test("lesson — the scene is fixed: no palette, ports, drops or box controls", () => { + const { link } = lessonLink(); + const sim = createSim({ layout: "lesson" }); + document.body.append(sim.el); + sim.setShape(shape(), link); + + assert.ok(sim.el.classList.contains("lesson")); + assert.equal(sim.el.querySelector(".sim-palette"), null, "no palette"); + assert.equal(sim.el.querySelectorAll(".sim-node").length, 2, "the session's instances are shown"); + assert.equal(sim.el.querySelector(".node-port"), null, "no ports to drag a connection from"); + assert.ok(sim.el.querySelector(".sim-wire .wire-live"), "the given connection is drawn"); + assert.equal(sim.el.querySelector(".sim-inspector-grip"), null, "no resize grips"); + assert.equal(sim.el.querySelector(".sim-frames-grip"), null); + + // a drop is ignored + drop(sim.el.querySelector(".sim-canvas")!, { schemaNs: "chat", protocol: "Chat", role: "server" }); + assert.equal(sim.el.querySelectorAll(".sim-node").length, 2, "nothing can be added"); + + // clicking the box's caption doesn't open the box inspector + fire(sim.el.querySelector(".group-cap")!, "click"); + assert.equal(sim.el.querySelector(".box-name"), null, "the box can't be renamed or removed"); + + // no clock bar by default + assert.equal(sim.el.querySelector(".clock-bar")!.children.length, 0); + sim.destroy(); +}); + +test("lesson — a server offers only the chosen behaviours, a client only its calls", () => { + const { link } = lessonLink(); + const sim = createSim({ layout: "lesson", behaviours: ["reply", "echo", "drop"] }); + document.body.append(sim.el); + sim.setShape(shape(), link); + const nodes = [...sim.el.querySelectorAll(".sim-node")] as HTMLElement[]; + const server = nodes.find((n) => n.classList.contains("role-server"))!; + const client = nodes.find((n) => n.classList.contains("role-client"))!; + + fire(server, "click"); + const tabs = () => [...sim.el.querySelectorAll(".insp-tab")].map((t) => t.textContent); + assert.deepEqual(tabs(), ["behaviours"]); + const kinds = [ + ...(sim.el.querySelector(".behavior-row .behavior-kind") as HTMLSelectElement).options, + ].map((o) => o.value); + assert.deepEqual(kinds.sort(), ["drop", "echo", "reply"]); + + fire(client, "click"); + assert.deepEqual(tabs(), ["call"]); + assert.equal(sim.el.querySelector(".insp-crumb"), null, "no link up to the box"); + const blk = callBlock(sim.el, "send"); + assert.deepEqual( + [...blk.querySelectorAll(".sim-btn")].map((b) => b.textContent), + ["send"], + "no compare button", + ); + sim.destroy(); +}); + +test("lesson — `select` opens on the client, and a call shows its reply and frames", async () => { + const { link, client } = lessonLink(); + const sim = createSim({ layout: "lesson", select: client }); + document.body.append(sim.el); + sim.setShape(shape(), link); + + const selected = sim.el.querySelector(".sim-node.selected") as HTMLElement; + assert.ok(selected?.classList.contains("role-client"), "the client is selected"); + + const blk = callBlock(sim.el, "send"); + (blk.querySelector(".call-args .arg-input") as HTMLInputElement).value = "hello"; + const out = fireSend(sim.el, "send"); + await tick(); + assert.ok(out.classList.contains("ok"), out.textContent!); + const frames = sim.el.querySelectorAll(".sim-frames-list .frame-row"); + assert.ok(frames.length >= 2, `expected the call's frames, got ${frames.length}`); + sim.destroy(); +}); + +test("sandbox — `clock: false` hides the clock bar there too", () => { + const sim = createSim({ clock: false }); + document.body.append(sim.el); + sim.setShape(shape()); + assert.ok(sim.el.querySelector(".sim-palette"), "still a sandbox"); + assert.equal(sim.el.querySelector(".clock-bar")!.children.length, 0); + sim.destroy(); +});