svelte-p5-components 0.4.1 → 0.6.0

package/README.md

@@ -8,6 +8,16 @@ Higher-level Svelte 5 components built on [`svelte-p5`](../core). The pieces tha
 pnpm add svelte-p5 svelte-p5-components p5
 ```
 
+To test a change that's merged on `main` but not yet released, install the preview build from [pkg.pr.new](https://pkg.pr.new/):
+
+```bash
+pnpm add \
+  https://pkg.pr.new/edw1nzhao/svelte-p5/svelte-p5@main \
+  https://pkg.pr.new/edw1nzhao/svelte-p5/svelte-p5-components@main
+```
+
+Pin to a SHA (`@<commit-sha>`) instead of `@main` for reproducible installs.
+
 ## `<Sketch>`
 
 `<P5Canvas>` plus a `ResizeObserver` on the parent element and automatic `pixelDensity(devicePixelRatio)`. The default you probably want.
@@ -31,6 +41,16 @@ pnpm add svelte-p5 svelte-p5-components p5
 </div>
 ```
 
+Props:
+
+| Prop       | Type                                 | Default | Notes                                                                                                                                                               |
+| ---------- | ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sketch`   | `SketchFn<Ext>`                      | —       | Required. Generic over custom instance members (see the core README).                                                                                               |
+| `hidpi`    | `boolean \| number`                  | `true`  | `true` → `devicePixelRatio`, `false` → `pixelDensity(1)`, number → that exact density (cap for large WEBGL canvases: `Math.min(devicePixelRatio, 2)`).              |
+| `instance` | `ExtendedP5<Ext> \| null` (bindable) | `null`  | The p5 instance once mounted.                                                                                                                                       |
+| `onReady`  | `(instance) => void`                 | —       | Fires once after creation, density, and initial sizing.                                                                                                             |
+| `onResize` | `(instance, width, height) => void`  | —       | Fires after each `ResizeObserver`-driven `resizeCanvas` (not the initial sizing). Rebuild size-dependent state here; call `instance.loop()` if you're noLoop-gated. |
+
 ## `<FPSMonitor>`
 
 Absolute-positioned FPS readout. Takes the p5 instance and samples `p.frameRate()` every 30 frames by default.

package/dist/ActivityBar.svelte

@@ -0,0 +1,227 @@
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+
+	/**
+	 * One item rendered as an icon button in the rail.
+	 */
+	export interface ActivityBarItem {
+		/** Stable id. Passed back via `onSelect` and used for `activeId`. */
+		id: string;
+		/** Snippet that renders the icon. Called with no arguments. */
+		icon: Snippet;
+		/** Accessible label + tooltip title. */
+		label: string;
+		/** Optional numeric badge rendered over the icon. */
+		badge?: number;
+	}
+</script>
+
+<script lang="ts">
+	/**
+	 * Vertical activity-bar rail (VS Code pattern). Renders a stack of
+	 * square icon buttons wired into a `role="tablist"` group. One item
+	 * can be "active"; callers own that state via the `activeId` prop.
+	 *
+	 * Visual contract: 48×48 square buttons. Active state renders an
+	 * accent-colored left border + subtle background tint. Hover is a
+	 * faint background. All class names are author-written (not scoped
+	 * hashes) so consumers can safely target them via `:global(...)`:
+	 *
+	 *   .activity-bar
+	 *   .activity-bar__item
+	 *   .activity-bar__item--active
+	 *   .activity-bar__badge
+	 *
+	 * Keyboard: Up/Down arrow moves focus between buttons (wraps); Enter
+	 * or Space activates the focused item.
+	 *
+	 * @example
+	 * ```svelte
+	 * <ActivityBar
+	 *   activeId={active}
+	 *   items={[
+	 *     { id: 'viz', label: 'Visualizations', icon: vizIcon },
+	 *     { id: 'filters', label: 'Filters', icon: filtersIcon }
+	 *   ]}
+	 *   onSelect={(id) => (active = active === id ? undefined : id)}
+	 * />
+	 * ```
+	 */
+	interface Props {
+		/** The items to render. */
+		items: ActivityBarItem[];
+		/**
+		 * The id of the currently-active item. When undefined, no item
+		 * shows the active treatment. Bindable.
+		 */
+		activeId?: string;
+		/** Click / keyboard-activation callback. */
+		onSelect?: (id: string) => void;
+		/** Rail width in px. Default: 48. */
+		width?: number;
+		/**
+		 * Rail orientation. Only `'vertical'` is supported today; the prop
+		 * is kept so future work can add horizontal without breaking API.
+		 */
+		orientation?: 'vertical';
+		class?: string;
+	}
+
+	let {
+		items,
+		activeId = $bindable<string | undefined>(undefined),
+		onSelect,
+		width = 48,
+		orientation = 'vertical',
+		class: className = ''
+	}: Props = $props();
+
+	let rootEl: HTMLDivElement | null = $state(null);
+
+	function handleItemClick(id: string) {
+		onSelect?.(id);
+	}
+
+	function handleKeydown(event: KeyboardEvent) {
+		if (!rootEl) return;
+		const buttons = Array.from(rootEl.querySelectorAll<HTMLButtonElement>('.activity-bar__item'));
+		if (buttons.length === 0) return;
+
+		const current = document.activeElement as HTMLElement | null;
+		const idx = current ? buttons.indexOf(current as HTMLButtonElement) : -1;
+
+		if (event.key === 'ArrowDown' || (orientation === 'vertical' && event.key === 'ArrowRight')) {
+			event.preventDefault();
+			const next = idx < 0 ? 0 : (idx + 1) % buttons.length;
+			buttons[next]?.focus();
+		} else if (
+			event.key === 'ArrowUp' ||
+			(orientation === 'vertical' && event.key === 'ArrowLeft')
+		) {
+			event.preventDefault();
+			const next = idx < 0 ? buttons.length - 1 : (idx - 1 + buttons.length) % buttons.length;
+			buttons[next]?.focus();
+		} else if (event.key === 'Enter' || event.key === ' ') {
+			if (idx >= 0) {
+				event.preventDefault();
+				const id = items[idx]?.id;
+				if (id) onSelect?.(id);
+			}
+		}
+	}
+</script>
+
+<div
+	bind:this={rootEl}
+	class="activity-bar {className}"
+	role="tablist"
+	aria-orientation={orientation}
+	style:width="{width}px"
+	onkeydown={handleKeydown}
+	tabindex="-1"
+>
+	{#each items as item (item.id)}
+		{@const isActive = item.id === activeId}
+		<button
+			type="button"
+			class="activity-bar__item {isActive ? 'activity-bar__item--active' : ''}"
+			role="tab"
+			aria-selected={isActive}
+			aria-label={item.label}
+			title={item.label}
+			tabindex={isActive ? 0 : -1}
+			onclick={() => handleItemClick(item.id)}
+		>
+			<span class="activity-bar__icon">
+				{@render item.icon()}
+			</span>
+			{#if item.badge !== undefined && item.badge > 0}
+				<span class="activity-bar__badge" aria-hidden="true">{item.badge}</span>
+			{/if}
+		</button>
+	{/each}
+</div>
+
+<style>
+	.activity-bar {
+		display: flex;
+		flex-direction: column;
+		align-items: stretch;
+		flex: 0 0 auto;
+		height: 100%;
+		background: var(--activity-bar-bg, #f3f3f3);
+		border-right: 1px solid var(--activity-bar-border, rgba(0, 0, 0, 0.08));
+		overflow: hidden;
+	}
+
+	.activity-bar__item {
+		position: relative;
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 48px;
+		height: 48px;
+		padding: 0;
+		margin: 0;
+		border: none;
+		background: transparent;
+		color: var(--activity-bar-fg, #555);
+		cursor: pointer;
+		transition:
+			background-color 120ms ease,
+			color 120ms ease;
+	}
+
+	.activity-bar__item:hover {
+		background: var(--activity-bar-bg-hover, rgba(0, 0, 0, 0.05));
+		color: var(--activity-bar-fg-hover, #111);
+	}
+
+	.activity-bar__item:focus-visible {
+		outline: 2px solid var(--activity-bar-focus, rgba(59, 130, 246, 0.55));
+		outline-offset: -2px;
+	}
+
+	.activity-bar__item--active {
+		color: var(--activity-bar-fg-active, #111);
+		background: var(--activity-bar-bg-active, rgba(59, 130, 246, 0.08));
+	}
+
+	.activity-bar__item--active::before {
+		content: '';
+		position: absolute;
+		left: 0;
+		top: 0;
+		bottom: 0;
+		width: 2px;
+		background: var(--activity-bar-accent, #3b82f6);
+	}
+
+	.activity-bar__icon {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 22px;
+		height: 22px;
+		pointer-events: none;
+	}
+
+	.activity-bar__badge {
+		position: absolute;
+		top: 6px;
+		right: 6px;
+		min-width: 16px;
+		height: 16px;
+		padding: 0 4px;
+		border-radius: 8px;
+		background: var(--activity-bar-badge-bg, #ef4444);
+		color: var(--activity-bar-badge-fg, #fff);
+		font:
+			10px/16px system-ui,
+			-apple-system,
+			Segoe UI,
+			sans-serif;
+		font-weight: 600;
+		text-align: center;
+	}
+</style>

package/dist/ActivityBar.svelte.d.ts

@@ -0,0 +1,66 @@
+import type { Snippet } from 'svelte';
+/**
+ * One item rendered as an icon button in the rail.
+ */
+export interface ActivityBarItem {
+    /** Stable id. Passed back via `onSelect` and used for `activeId`. */
+    id: string;
+    /** Snippet that renders the icon. Called with no arguments. */
+    icon: Snippet;
+    /** Accessible label + tooltip title. */
+    label: string;
+    /** Optional numeric badge rendered over the icon. */
+    badge?: number;
+}
+/**
+ * Vertical activity-bar rail (VS Code pattern). Renders a stack of
+ * square icon buttons wired into a `role="tablist"` group. One item
+ * can be "active"; callers own that state via the `activeId` prop.
+ *
+ * Visual contract: 48×48 square buttons. Active state renders an
+ * accent-colored left border + subtle background tint. Hover is a
+ * faint background. All class names are author-written (not scoped
+ * hashes) so consumers can safely target them via `:global(...)`:
+ *
+ *   .activity-bar
+ *   .activity-bar__item
+ *   .activity-bar__item--active
+ *   .activity-bar__badge
+ *
+ * Keyboard: Up/Down arrow moves focus between buttons (wraps); Enter
+ * or Space activates the focused item.
+ *
+ * @example
+ * ```svelte
+ * <ActivityBar
+ *   activeId={active}
+ *   items={[
+ *     { id: 'viz', label: 'Visualizations', icon: vizIcon },
+ *     { id: 'filters', label: 'Filters', icon: filtersIcon }
+ *   ]}
+ *   onSelect={(id) => (active = active === id ? undefined : id)}
+ * />
+ * ```
+ */
+interface Props {
+    /** The items to render. */
+    items: ActivityBarItem[];
+    /**
+     * The id of the currently-active item. When undefined, no item
+     * shows the active treatment. Bindable.
+     */
+    activeId?: string;
+    /** Click / keyboard-activation callback. */
+    onSelect?: (id: string) => void;
+    /** Rail width in px. Default: 48. */
+    width?: number;
+    /**
+     * Rail orientation. Only `'vertical'` is supported today; the prop
+     * is kept so future work can add horizontal without breaking API.
+     */
+    orientation?: 'vertical';
+    class?: string;
+}
+declare const ActivityBar: import("svelte").Component<Props, {}, "activeId">;
+type ActivityBar = ReturnType<typeof ActivityBar>;
+export default ActivityBar;