svelte-p5-components 0.3.0 → 0.4.1

package/dist/CanvasFrame.svelte

@@ -0,0 +1,129 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	/**
+	 * Layout shell for canvas-driven apps.
+	 *
+	 * Every multi-panel p5 app ends up with the same picture: a canvas filling
+	 * the bulk of the viewport, one or more toolbars anchored to its edges,
+	 * and overlays (tooltips, FPS readouts, legends) painted on top. Each app
+	 * reinvents the flex math, the ResizeObserver coordination (so the canvas
+	 * doesn't thrash when a toolbar's height changes), and the z-index/pointer
+	 * discipline for overlays that must *not* swallow canvas input.
+	 *
+	 * `<CanvasFrame>` is that shell. It exposes snippet slots for each region
+	 * and otherwise stays out of the way:
+	 *
+	 * - `canvas` (required): render your `<Sketch>` / `<P5Canvas>` here.
+	 * - `top` / `bottom` / `leftRail` / `rightRail` (optional): chrome docked
+	 *   to each edge. Natural content height/width; does not fight the canvas
+	 *   for flex space.
+	 * - `overlay` (optional): absolutely positioned over the canvas region.
+	 *   `pointer-events: none` by default so it doesn't block canvas input;
+	 *   individual children can opt in with `pointer-events: auto`.
+	 *
+	 * The frame itself fills whatever parent it's mounted in — typically
+	 * `height: 100vh` or a flex child. It assumes a bounded height from the
+	 * parent; inside it, the canvas region flexes to consume whatever remains
+	 * after the toolbars.
+	 *
+	 * @example
+	 * ```svelte
+	 * <div style="height: 100vh">
+	 *   <CanvasFrame>
+	 *     {#snippet top()}<MyMenuBar />{/snippet}
+	 *     {#snippet bottom()}<MyTimeline /><MySpeakerList />{/snippet}
+	 *     {#snippet canvas()}<Sketch {sketch} bind:instance />{/snippet}
+	 *     {#snippet overlay()}<FPSMonitor {instance} />{/snippet}
+	 *   </CanvasFrame>
+	 * </div>
+	 * ```
+	 */
+	interface Props {
+		canvas: Snippet;
+		top?: Snippet;
+		bottom?: Snippet;
+		leftRail?: Snippet;
+		rightRail?: Snippet;
+		overlay?: Snippet;
+		class?: string;
+		style?: string;
+	}
+
+	let {
+		canvas,
+		top,
+		bottom,
+		leftRail,
+		rightRail,
+		overlay,
+		class: className = '',
+		style
+	}: Props = $props();
+</script>
+
+<div class="canvas-frame {className}" {style}>
+	{#if top}
+		<div class="canvas-frame__region canvas-frame__top">{@render top()}</div>
+	{/if}
+	<div class="canvas-frame__middle">
+		{#if leftRail}
+			<div class="canvas-frame__region canvas-frame__rail">{@render leftRail()}</div>
+		{/if}
+		<div class="canvas-frame__stage">
+			{@render canvas()}
+			{#if overlay}
+				<div class="canvas-frame__overlay">{@render overlay()}</div>
+			{/if}
+		</div>
+		{#if rightRail}
+			<div class="canvas-frame__region canvas-frame__rail">{@render rightRail()}</div>
+		{/if}
+	</div>
+	{#if bottom}
+		<div class="canvas-frame__region canvas-frame__bottom">{@render bottom()}</div>
+	{/if}
+</div>
+
+<style>
+	.canvas-frame {
+		display: flex;
+		flex-direction: column;
+		width: 100%;
+		height: 100%;
+		min-width: 0;
+		min-height: 0;
+		overflow: hidden;
+		position: relative;
+	}
+
+	.canvas-frame__region {
+		flex: 0 0 auto;
+	}
+
+	.canvas-frame__middle {
+		display: flex;
+		flex: 1 1 auto;
+		min-width: 0;
+		min-height: 0;
+	}
+
+	.canvas-frame__rail {
+		min-height: 0;
+	}
+
+	.canvas-frame__stage {
+		flex: 1 1 auto;
+		min-width: 0;
+		min-height: 0;
+		position: relative;
+		overflow: hidden;
+	}
+
+	.canvas-frame__overlay {
+		position: absolute;
+		inset: 0;
+		pointer-events: none;
+		z-index: 10;
+	}
+</style>

package/dist/CanvasFrame.svelte.d.ts

@@ -0,0 +1,52 @@
+import type { Snippet } from 'svelte';
+/**
+ * Layout shell for canvas-driven apps.
+ *
+ * Every multi-panel p5 app ends up with the same picture: a canvas filling
+ * the bulk of the viewport, one or more toolbars anchored to its edges,
+ * and overlays (tooltips, FPS readouts, legends) painted on top. Each app
+ * reinvents the flex math, the ResizeObserver coordination (so the canvas
+ * doesn't thrash when a toolbar's height changes), and the z-index/pointer
+ * discipline for overlays that must *not* swallow canvas input.
+ *
+ * `<CanvasFrame>` is that shell. It exposes snippet slots for each region
+ * and otherwise stays out of the way:
+ *
+ * - `canvas` (required): render your `<Sketch>` / `<P5Canvas>` here.
+ * - `top` / `bottom` / `leftRail` / `rightRail` (optional): chrome docked
+ *   to each edge. Natural content height/width; does not fight the canvas
+ *   for flex space.
+ * - `overlay` (optional): absolutely positioned over the canvas region.
+ *   `pointer-events: none` by default so it doesn't block canvas input;
+ *   individual children can opt in with `pointer-events: auto`.
+ *
+ * The frame itself fills whatever parent it's mounted in — typically
+ * `height: 100vh` or a flex child. It assumes a bounded height from the
+ * parent; inside it, the canvas region flexes to consume whatever remains
+ * after the toolbars.
+ *
+ * @example
+ * ```svelte
+ * <div style="height: 100vh">
+ *   <CanvasFrame>
+ *     {#snippet top()}<MyMenuBar />{/snippet}
+ *     {#snippet bottom()}<MyTimeline /><MySpeakerList />{/snippet}
+ *     {#snippet canvas()}<Sketch {sketch} bind:instance />{/snippet}
+ *     {#snippet overlay()}<FPSMonitor {instance} />{/snippet}
+ *   </CanvasFrame>
+ * </div>
+ * ```
+ */
+interface Props {
+    canvas: Snippet;
+    top?: Snippet;
+    bottom?: Snippet;
+    leftRail?: Snippet;
+    rightRail?: Snippet;
+    overlay?: Snippet;
+    class?: string;
+    style?: string;
+}
+declare const CanvasFrame: import("svelte").Component<Props, {}, "">;
+type CanvasFrame = ReturnType<typeof CanvasFrame>;
+export default CanvasFrame;

package/dist/CanvasFrame.test.svelte.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/CanvasFrame.test.svelte.js

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/svelte';
+import { createRawSnippet } from 'svelte';
+import CanvasFrame from './CanvasFrame.svelte';
+const snippet = (html) => createRawSnippet(() => ({ render: () => html }));
+describe('<CanvasFrame>', () => {
+    it('renders the required canvas snippet inside the stage', () => {
+        const { container } = render(CanvasFrame, {
+            canvas: snippet('<div data-testid="canvas">CANVAS</div>')
+        });
+        const stage = container.querySelector('.canvas-frame__stage');
+        expect(stage).not.toBeNull();
+        expect(stage?.textContent).toContain('CANVAS');
+    });
+    it('omits optional regions when their snippets are absent', () => {
+        const { container } = render(CanvasFrame, {
+            canvas: snippet('<div>c</div>')
+        });
+        expect(container.querySelector('.canvas-frame__top')).toBeNull();
+        expect(container.querySelector('.canvas-frame__bottom')).toBeNull();
+        expect(container.querySelector('.canvas-frame__rail')).toBeNull();
+        expect(container.querySelector('.canvas-frame__overlay')).toBeNull();
+    });
+    it('renders top, bottom, leftRail, rightRail when provided', () => {
+        const { container } = render(CanvasFrame, {
+            canvas: snippet('<div>c</div>'),
+            top: snippet('<span>T</span>'),
+            bottom: snippet('<span>B</span>'),
+            leftRail: snippet('<span>L</span>'),
+            rightRail: snippet('<span>R</span>')
+        });
+        expect(container.querySelector('.canvas-frame__top')?.textContent).toBe('T');
+        expect(container.querySelector('.canvas-frame__bottom')?.textContent).toBe('B');
+        const rails = container.querySelectorAll('.canvas-frame__rail');
+        expect(rails).toHaveLength(2);
+        expect(rails[0]?.textContent).toBe('L');
+        expect(rails[1]?.textContent).toBe('R');
+    });
+    it('overlay region renders with the dedicated class that applies pointer-events:none', () => {
+        // happy-dom doesn't resolve Svelte's scoped stylesheet cascade, so we
+        // assert on the marker class instead of the computed value. The actual
+        // CSS is covered by a Playwright smoke pass on docs/examples.
+        const { container } = render(CanvasFrame, {
+            canvas: snippet('<div>c</div>'),
+            overlay: snippet('<div>o</div>')
+        });
+        const overlay = container.querySelector('.canvas-frame__overlay');
+        expect(overlay).not.toBeNull();
+    });
+    it('forwards class and style to the root container', () => {
+        const { container } = render(CanvasFrame, {
+            canvas: snippet('<div>c</div>'),
+            class: 'extra-class',
+            style: 'background: red;'
+        });
+        const root = container.querySelector('.canvas-frame');
+        expect(root?.classList.contains('extra-class')).toBe(true);
+        expect(root.style.background).toBe('red');
+    });
+});

package/dist/DraggableWindow.svelte

@@ -72,36 +72,59 @@
 	let size = $state(untrack(() => ({ w: typeof width === 'number' ? width : 480, h: 40 })));
 	let rootEl: HTMLDivElement | null = $state(null);
 
-	function clampToViewport() {
-		if (typeof window === 'undefined') return;
-		// When constrained to a parent, neodrag's `bounds(BoundsFrom.parent())`
-		// already keeps the window inside; viewport math here would be wrong
-		// because positions are relative to the parent, not the viewport.
-		if (constrained === 'parent') return;
-		const vw = window.innerWidth;
-		const vh = window.innerHeight;
-		// Never allow the titlebar above the viewport top - that's the
-		// "unreachable" case. Allow partial horizontal overflow so narrow
-		// screens don't trap wide windows, but always keep `minVisible`
-		// pixels of the window on-screen for a grab handle.
-		const minX = -(size.w - minVisible);
-		const maxX = vw - minVisible;
-		const minY = 0;
-		const maxY = vh - minVisible;
-		pos = {
-			x: Math.max(minX, Math.min(maxX, pos.x)),
-			y: Math.max(minY, Math.min(maxY, pos.y))
-		};
+	// Clamp `pos` back inside whatever sandbox `constrained` points at.
+	// Runs on drag end (drag might overshoot during pointer-move) AND on
+	// any resize of the sandbox (window → viewport mode, parent element →
+	// parent mode) so the window snaps back into view when its container
+	// shrinks underneath it.
+	function clamp() {
+		if (typeof window === 'undefined' || !rootEl) return;
+
+		if (constrained === 'parent') {
+			// Position is relative to the parent's padding-box, so bounds
+			// are [0, parentSize - windowSize]. Falls through to no-op if
+			// the window is somehow larger than the parent (Math.max(0, ...)).
+			const parent = rootEl.parentElement;
+			if (!parent) return;
+			const r = parent.getBoundingClientRect();
+			const maxX = Math.max(0, r.width - size.w);
+			const maxY = Math.max(0, r.height - size.h);
+			pos = {
+				x: Math.max(0, Math.min(maxX, pos.x)),
+				y: Math.max(0, Math.min(maxY, pos.y))
+			};
+			return;
+		}
+
+		if (constrained === 'viewport') {
+			// Never allow the titlebar above the viewport top - that's the
+			// "unreachable" case. Allow partial horizontal overflow so narrow
+			// screens don't trap wide windows, but always keep `minVisible`
+			// pixels of the window on-screen for a grab handle.
+			const vw = window.innerWidth;
+			const vh = window.innerHeight;
+			const minX = -(size.w - minVisible);
+			const maxX = vw - minVisible;
+			const minY = 0;
+			const maxY = vh - minVisible;
+			pos = {
+				x: Math.max(minX, Math.min(maxX, pos.x)),
+				y: Math.max(minY, Math.min(maxY, pos.y))
+			};
+		}
+		// 'none': no clamping.
 	}
 
 	// Keep size fresh (used for clamp math) - ResizeObserver on our own
-	// root element catches CSS resize-from-corner too.
+	// root element catches CSS resize-from-corner too. We also re-clamp
+	// after each size change so corner-resizing past a bound snaps back.
 	$effect(() => {
 		if (!rootEl) return;
 		const el = rootEl;
 		const ro = new ResizeObserver(() => {
 			const r = el.getBoundingClientRect();
 			size = { w: r.width, h: r.height };
+			clamp();
 		});
 		ro.observe(el);
 		// seed
@@ -110,15 +133,30 @@
 		return () => ro.disconnect();
 	});
 
-	// Re-clamp on window resize - this is the "snap back in when the
-	// viewport shrinks" case.
+	// Re-clamp on window resize - the "snap back when the viewport shrinks"
+	// case. Harmless in parent mode (clamp() handles parent bounds too), so
+	// we keep a single global listener instead of branching.
 	$effect(() => {
 		if (typeof window === 'undefined') return;
-		const onResize = () => clampToViewport();
+		const onResize = () => clamp();
 		window.addEventListener('resize', onResize);
 		return () => window.removeEventListener('resize', onResize);
 	});
 
+	// Parent mode: watch the parent element's size too. A flex/grid row
+	// resizing around us wouldn't trigger `window.resize`, so without this
+	// the window can end up stranded outside a shrunken container until the
+	// user nudges it.
+	$effect(() => {
+		if (typeof window === 'undefined') return;
+		if (constrained !== 'parent' || !rootEl) return;
+		const parent = rootEl.parentElement;
+		if (!parent) return;
+		const ro = new ResizeObserver(() => clamp());
+		ro.observe(parent);
+		return () => ro.disconnect();
+	});
+
 	// The neodrag `position` plugin takes a `current: {x, y}` and forces
 	// the element to that transform. Wrapped in a Compartment so updates
 	// to `pos` re-run just this plugin (not the whole plugin list).
@@ -132,7 +170,7 @@
 			onDrag: ({ offset }) => {
 				pos = { x: offset.x, y: offset.y };
 			},
-			onDragEnd: () => clampToViewport()
+			onDragEnd: () => clamp()
 		}),
 		...(constrained === 'viewport' ? [bounds(BoundsFrom.viewport())] : []),
 		...(constrained === 'parent' ? [bounds(BoundsFrom.parent())] : []),

package/dist/EntityToggleList.svelte

@@ -0,0 +1,269 @@
+<script lang="ts" module>
+	/**
+	 * A single entity (speaker, actor, track, class, series, etc.) rendered
+	 * as a toggle button in the list. Consumers supply a flat array; optional
+	 * `group` buckets entities into labeled sections.
+	 */
+	export interface Entity {
+		/** Stable id. Used in onToggle/onColorChange callbacks. */
+		id: string;
+		/** Human-readable label shown on the button. */
+		label: string;
+		/** Color swatch. Any CSS color string. */
+		color: string;
+		/** Default: true. When false, the entity renders dimmed. */
+		visible?: boolean;
+		/** Optional group label. Entities with the same `group` are rendered together. */
+		group?: string;
+	}
+</script>
+
+<script lang="ts">
+	// Entity visibility/color toggle panel.
+	//
+	// Canvas apps that render N separately-colored series (speakers,
+	// actors, clusters, channels) nearly always grow a panel like this:
+	// a row of buttons with a colored swatch and a label, each toggling
+	// the corresponding entity's visibility in the viz. Optional color
+	// editing. Optional grouping (family, cluster). Optional overflow
+	// expander once the list exceeds a threshold.
+	//
+	// The list binds `entities[].visible` back via callbacks rather than
+	// by mutating the prop in place — consumers keep their own authoritative
+	// state and this component stays stateless.
+	//
+	// See the package README for a usage example.
+
+	interface Props {
+		/** The list of entities. */
+		entities: Entity[];
+		/** Called when a visibility toggle is clicked. */
+		onToggle?: (id: string, visible: boolean) => void;
+		/** When provided, a native color input is shown and clicking the swatch opens it. */
+		onColorChange?: (id: string, color: string) => void;
+		/** Max entities to show before collapsing the remainder behind a "+N more" expander. */
+		maxVisible?: number;
+		/** Optional heading above the list. */
+		heading?: string;
+		class?: string;
+	}
+
+	let {
+		entities,
+		onToggle,
+		onColorChange,
+		maxVisible,
+		heading,
+		class: className = ''
+	}: Props = $props();
+
+	let expanded = $state(false);
+
+	const visibleEntities = $derived(
+		expanded || maxVisible === undefined ? entities : entities.slice(0, maxVisible)
+	);
+
+	const groupKeys = $derived.by(() => {
+		const keys: string[] = [];
+		for (const e of visibleEntities) {
+			const k = e.group ?? '';
+			if (!keys.includes(k)) keys.push(k);
+		}
+		return keys;
+	});
+
+	const hasGroupBoundaries = $derived(groupKeys.some((k) => k !== ''));
+
+	const hiddenCount = $derived(
+		maxVisible === undefined || expanded ? 0 : Math.max(0, entities.length - maxVisible)
+	);
+
+	function entitiesInGroup(key: string): Entity[] {
+		return visibleEntities.filter((e) => (e.group ?? '') === key);
+	}
+
+	function isVisible(e: Entity) {
+		return e.visible !== false;
+	}
+
+	function handleToggle(e: Entity) {
+		onToggle?.(e.id, !isVisible(e));
+	}
+
+	function handleColorInput(e: Entity, event: Event) {
+		const target = event.currentTarget as HTMLInputElement;
+		onColorChange?.(e.id, target.value);
+	}
+</script>
+
+<div class="entity-toggle-list {className}" data-has-groups={hasGroupBoundaries}>
+	{#if heading}
+		<div class="entity-toggle-list__heading">{heading}</div>
+	{/if}
+
+	{#each groupKeys as key (key)}
+		{#if hasGroupBoundaries && key}
+			<div class="entity-toggle-list__group-label">{key}</div>
+		{/if}
+		<div class="entity-toggle-list__row">
+			{#each entitiesInGroup(key) as entity (entity.id)}
+				<div class="entity-toggle-list__item" class:is-hidden={!isVisible(entity)}>
+					{#if onColorChange}
+						<label
+							class="entity-toggle-list__swatch-wrap"
+							aria-label="Change color for {entity.label}"
+						>
+							<span class="entity-toggle-list__swatch" style:background-color={entity.color}></span>
+							<input
+								type="color"
+								class="entity-toggle-list__color-input"
+								value={entity.color}
+								oninput={(e) => handleColorInput(entity, e)}
+							/>
+						</label>
+					{:else}
+						<span
+							class="entity-toggle-list__swatch"
+							style:background-color={entity.color}
+							aria-hidden="true"
+						></span>
+					{/if}
+					<button
+						type="button"
+						class="entity-toggle-list__label"
+						aria-pressed={isVisible(entity)}
+						title={isVisible(entity) ? `Hide ${entity.label}` : `Show ${entity.label}`}
+						onclick={() => handleToggle(entity)}
+					>
+						{entity.label}
+					</button>
+				</div>
+			{/each}
+		</div>
+	{/each}
+
+	{#if hiddenCount > 0}
+		<button
+			type="button"
+			class="entity-toggle-list__expand"
+			onclick={() => (expanded = true)}
+			title="Show {hiddenCount} more"
+		>
+			+{hiddenCount} more
+		</button>
+	{:else if expanded && maxVisible !== undefined && entities.length > maxVisible}
+		<button
+			type="button"
+			class="entity-toggle-list__expand"
+			onclick={() => (expanded = false)}
+			title="Collapse"
+		>
+			show less
+		</button>
+	{/if}
+</div>
+
+<style>
+	.entity-toggle-list {
+		display: flex;
+		flex-direction: column;
+		gap: 6px;
+		font:
+			12px/1.3 system-ui,
+			-apple-system,
+			Segoe UI,
+			sans-serif;
+
+		--entity-swatch-size: 12px;
+		--entity-btn-bg: transparent;
+		--entity-btn-bg-hover: rgba(0, 0, 0, 0.05);
+		--entity-btn-fg: #111;
+		--entity-btn-fg-hidden: #9ca3af;
+		--entity-heading-fg: #6b7280;
+	}
+
+	.entity-toggle-list__heading,
+	.entity-toggle-list__group-label {
+		font-size: 11px;
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.04em;
+		color: var(--entity-heading-fg);
+	}
+
+	.entity-toggle-list__row {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 4px 8px;
+		align-items: center;
+	}
+
+	.entity-toggle-list__item {
+		display: inline-flex;
+		align-items: center;
+		gap: 6px;
+		padding: 2px 6px 2px 4px;
+		border-radius: 4px;
+		background: var(--entity-btn-bg);
+	}
+
+	.entity-toggle-list__item:hover {
+		background: var(--entity-btn-bg-hover);
+	}
+
+	.entity-toggle-list__item.is-hidden .entity-toggle-list__label {
+		color: var(--entity-btn-fg-hidden);
+		text-decoration: line-through;
+	}
+
+	.entity-toggle-list__item.is-hidden .entity-toggle-list__swatch {
+		opacity: 0.3;
+	}
+
+	.entity-toggle-list__swatch {
+		display: inline-block;
+		width: var(--entity-swatch-size);
+		height: var(--entity-swatch-size);
+		border-radius: 50%;
+		border: 1px solid rgba(0, 0, 0, 0.15);
+		flex: 0 0 auto;
+	}
+
+	.entity-toggle-list__swatch-wrap {
+		position: relative;
+		display: inline-flex;
+		cursor: pointer;
+	}
+
+	.entity-toggle-list__color-input {
+		position: absolute;
+		inset: 0;
+		opacity: 0;
+		cursor: pointer;
+		width: 100%;
+		height: 100%;
+	}
+
+	.entity-toggle-list__label {
+		background: none;
+		border: none;
+		padding: 0;
+		margin: 0;
+		font: inherit;
+		color: var(--entity-btn-fg);
+		cursor: pointer;
+		text-align: left;
+	}
+
+	.entity-toggle-list__expand {
+		align-self: flex-start;
+		background: none;
+		border: none;
+		padding: 0;
+		color: var(--entity-heading-fg);
+		font: inherit;
+		font-size: 11px;
+		text-decoration: underline;
+		cursor: pointer;
+	}
+</style>

package/dist/EntityToggleList.svelte.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A single entity (speaker, actor, track, class, series, etc.) rendered
+ * as a toggle button in the list. Consumers supply a flat array; optional
+ * `group` buckets entities into labeled sections.
+ */
+export interface Entity {
+    /** Stable id. Used in onToggle/onColorChange callbacks. */
+    id: string;
+    /** Human-readable label shown on the button. */
+    label: string;
+    /** Color swatch. Any CSS color string. */
+    color: string;
+    /** Default: true. When false, the entity renders dimmed. */
+    visible?: boolean;
+    /** Optional group label. Entities with the same `group` are rendered together. */
+    group?: string;
+}
+interface Props {
+    /** The list of entities. */
+    entities: Entity[];
+    /** Called when a visibility toggle is clicked. */
+    onToggle?: (id: string, visible: boolean) => void;
+    /** When provided, a native color input is shown and clicking the swatch opens it. */
+    onColorChange?: (id: string, color: string) => void;
+    /** Max entities to show before collapsing the remainder behind a "+N more" expander. */
+    maxVisible?: number;
+    /** Optional heading above the list. */
+    heading?: string;
+    class?: string;
+}
+declare const EntityToggleList: import("svelte").Component<Props, {}, "">;
+type EntityToggleList = ReturnType<typeof EntityToggleList>;
+export default EntityToggleList;

package/dist/EntityToggleList.test.svelte.d.ts

@@ -0,0 +1 @@
+export {};