svelte-p5-components 0.2.1 → 0.4.0

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

@@ -56,14 +56,14 @@
 		return typeof v === 'number' ? `${v}px` : v;
 	}
 
-	// Focus management — each window gets a reactive z-index slot shared
+	// Focus management - each window gets a reactive z-index slot shared
 	// across every DraggableWindow on the page. Clicking brings it to top.
 	const win = registerWindow();
 
 	// Live position. Neodrag's `position` plugin drives the element via
 	// transform; we update this state from onDrag AND on resize/clamp,
 	// and the Compartment re-evaluates to push changes back into neodrag.
-	// `untrack` prevents these props from forming a reactive dep — they're
+	// `untrack` prevents these props from forming a reactive dep - they're
 	// *initial* values only; later position comes from user drag.
 	let pos = $state(untrack(() => ({ x: initialX, y: initialY })));
 
@@ -74,9 +74,13 @@
 
 	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
+		// 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.
@@ -90,7 +94,7 @@
 		};
 	}
 
-	// Keep size fresh (used for clamp math) — ResizeObserver on our own
+	// Keep size fresh (used for clamp math) - ResizeObserver on our own
 	// root element catches CSS resize-from-corner too.
 	$effect(() => {
 		if (!rootEl) return;
@@ -106,7 +110,7 @@
 		return () => ro.disconnect();
 	});
 
-	// Re-clamp on window resize — this is the "snap back in when the
+	// Re-clamp on window resize - this is the "snap back in when the
 	// viewport shrinks" case.
 	$effect(() => {
 		if (typeof window === 'undefined') return;
@@ -139,6 +143,8 @@
 <div
 	bind:this={rootEl}
 	class="draggable-window"
+	class:dw-fixed={constrained !== 'parent'}
+	class:dw-absolute={constrained === 'parent'}
 	style:width={toCssSize(width)}
 	style:height={toCssSize(height)}
 	style:min-width={toCssSize(minWidth)}
@@ -162,7 +168,6 @@
 
 <style>
 	.draggable-window {
-		position: fixed;
 		top: 0;
 		left: 0;
 		display: flex;
@@ -177,6 +182,16 @@
 		/* Native resize from the bottom-right corner. */
 		resize: both;
 	}
+	/* Default: float above the viewport (suits constrained="viewport" or "none"). */
+	.dw-fixed {
+		position: fixed;
+	}
+	/* When constrained to a parent, position absolute inside that parent so
+	   the visual position matches the drag bounds. The parent must be a
+	   positioning context (`position: relative` or similar). */
+	.dw-absolute {
+		position: absolute;
+	}
 	.dw-titlebar {
 		display: flex;
 		align-items: center;

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 {};