@wells-nelson/interactions 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @wells-nelson/interactions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Svelte 5 inputs, actions and account UI. Peer dependencies: `@wells-nelson/displays` (install it
+alongside, so the app and this package share one theme and icon registry) and `svelte`. No
+storage dependency: the account components take the sync layer through interfaces.
+
+```sh
+npm install @wells-nelson/displays @wells-nelson/interactions
+```
+
+## Inputs
+
+`TextField` (label, error, hint), `Checkbox` (optionally hidden label), `Toggle` (a switch for
+settings that apply at once), `Combobox` (type to filter, offers "Create …"; plus `sameName`),
+`AddRow` (inline "name + plus" that refocuses), `Segmented` (one of a few) and `SearchBar`
+(fixed at the bottom, with a clear button).
+
+```svelte
+<ActiveList
+	items={people}
+	noun="People"
+	label={(p) => p.name}
+	onopen={edit}
+	ontoggle={(p, on) => setActive(p, on)}
+	bind:inactiveOpen={() => !prefs.isCollapsed('people-inactive', true), (open) => prefs.setCollapsed('people-inactive', !open)}
+/>
+
+<CollapsibleSection title={status.name} count={rows.length} collapsed={…} ontogglecollapse={…}
+	onadd={…} onedit={…} dragData={{ type: 'section', id: status.id }} drop={{ accepts, ondrop, ordered: true }}>
+	{#each rows as row (row.id)}<li data-dnd-item>…</li>{/each}
+</CollapsibleSection>
+```
+
+Both take `appearance`: `card` (default) draws rounded cards; `lines` fills the container edge to
+edge with rules between rows, like lines on paper. A `lines` CollapsibleSection's pinned header
+needs an opaque background: set `--section-header-bg` to whatever it sits on (default `--bg`).
+
+## Actions
+
+- `use:longpress={handler}`: fires after a 500 ms still hold and swallows the click that follows.
+- `use:draggable={{ data, onstart, onend }}` / `use:dropZone={{ accepts, ondrop, ordered }}` /
+  `reorder(ids, id, index)`: long-press (300 ms) drag for touch and mouse, with an insertion line
+  for ordered zones and the scroll position restored after the drop. Both actions use the same
+  press detection (`watchPress`).
+
+## Undo
+
+```ts
+const undo = new UndoStack(); // button visible 5 s, history kept 1 min idle
+setDone(task, true);
+undo.push({ undo: () => setDone(task, false) });
+```
+
+```svelte
+<UndoButton stack={undo} />
+```
+
+## Dev wipe
+
+```svelte
+{#if import.meta.env.DEV}
+	<DevWipeButton onconfirm={() => wipeAllData({ beforeWipe: store.resetDevice, redirectTo: resolve('/') })} />
+{/if}
+```
+
+## Account and sharing (`@wells-nelson/interactions/account`)
+
+`AccountPanel` (or the `SignInCard`, `SyncStatusCard`, `SignOutCard` it's made of),
+`LocalItemsPrompt`, `ShareModal`, `ContainerEditModal`. Pass `store.cloud` as `cloud`/`account`
+and `store.supabase` as `members` from `@wells-nelson/data-storage`, or anything with the same
+shape. Wording comes from `nouns` (`{ singular: 'project', plural: 'projects' }`) and `appName`.
+
+```svelte
+<AccountPanel cloud={store.cloud} account={store.cloud} nouns={NOUNS} appName="My App"
+	returnUrl={() => new URL(resolve('/profile'), location.origin).href}
+	pendingName={(id) => projects.find(id)?.container.name ?? 'Deleted project'} />
+
+<ShareModal containerId={id} name={entry.container.name} location={entry?.location} ready={projects.ready}
+	role={entry.role} roles cloud={store.cloud} members={store.supabase} nouns={NOUNS} appName="My App"
+	signInHref={resolve('/profile')} onmakecloud={() => store.ops.makeCloud(id)} {onclose} />
+```
+
+With `roles`, `ShareModal` shows a role picker and protects the last owner, and
+`ContainerEditModal` offers "Leave" instead of "Delete" while other owners remain. Without roles
+every member counts as an owner. The sandbox's Account page drives every state with a mock.

package/dist/ActiveList.svelte

@@ -0,0 +1,168 @@
+<script lang="ts" generics="T extends { id: string; active: boolean }">
+	import { Icon, IconButton } from '@wells-nelson/displays';
+	import Checkbox from './Checkbox.svelte';
+
+	/**
+	 * Active rows first, then a collapsible inactive section. Each row has an active checkbox and a
+	 * pencil that opens it; tapping the name does nothing. Bind `inactiveOpen` to persist whether
+	 * the inactive section is expanded (e.g. to device preferences).
+	 */
+	let {
+		items,
+		noun,
+		label,
+		onopen,
+		ontoggle,
+		readOnly = false,
+		inactiveOpen = $bindable(false),
+		emptyText = 'None yet.',
+		appearance = 'card'
+	}: {
+		items: T[];
+		/** Plural noun for headings, e.g. "Members". */
+		noun: string;
+		label: (item: T) => string;
+		onopen: (item: T) => void;
+		ontoggle: (item: T, active: boolean) => void;
+		readOnly?: boolean;
+		inactiveOpen?: boolean;
+		emptyText?: string;
+		/**
+		 * `card` (default): rounded cards. `lines`: fills its container edge to edge with no card,
+		 * so the rows read like lines on paper.
+		 */
+		appearance?: 'card' | 'lines';
+	} = $props();
+
+	const sectionClass = $derived(['group', appearance, appearance === 'card' && 'card']);
+
+	const active = $derived(items.filter((i) => i.active));
+	const inactive = $derived(items.filter((i) => !i.active));
+</script>
+
+{#snippet row(item: T)}
+	<li class="row">
+		{#if readOnly}
+			<span class="state" class:on={item.active}><Icon name={item.active ? 'check' : 'x'} size={16} /></span>
+		{:else}
+			<Checkbox
+				checked={item.active}
+				label={`${label(item)} active`}
+				hideLabel
+				onchange={(checked) => ontoggle(item, checked)}
+			/>
+		{/if}
+		<span class="name">{label(item)}</span>
+		<IconButton icon="pencil" label={`${readOnly ? 'View' : 'Edit'} ${label(item)}`} size={18} onclick={() => onopen(item)} />
+	</li>
+{/snippet}
+
+<section class={sectionClass}>
+	<h2>Active {noun.toLowerCase()} <span class="count">{active.length}</span></h2>
+	<ul>
+		{#each active as item (item.id)}
+			{@render row(item)}
+		{:else}
+			<li class="muted empty-row">{emptyText}</li>
+		{/each}
+	</ul>
+</section>
+
+{#if inactive.length > 0}
+	<section class={sectionClass}>
+		<button type="button" class="toggle" aria-expanded={inactiveOpen} onclick={() => (inactiveOpen = !inactiveOpen)}>
+			<span class="chev" class:collapsed={!inactiveOpen}><Icon name="chevron" size={20} /></span>
+			Inactive {noun.toLowerCase()} <span class="count">{inactive.length}</span>
+		</button>
+		{#if inactiveOpen}
+			<ul>
+				{#each inactive as item (item.id)}
+					{@render row(item)}
+				{/each}
+			</ul>
+		{/if}
+	</section>
+{/if}
+
+<style>
+	.card {
+		margin-bottom: 0.75rem;
+		overflow: hidden;
+	}
+	.lines {
+		width: 100%;
+		border-bottom: 1px solid var(--border);
+	}
+	h2,
+	.toggle {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		margin: 0;
+		padding: 0.75rem 1rem;
+		font-size: 1rem;
+		font-weight: 700;
+	}
+	.toggle {
+		width: 100%;
+		border: none;
+		background: none;
+		cursor: pointer;
+		padding-left: 0.5rem;
+		color: var(--muted);
+	}
+	.chev {
+		display: grid;
+		transition: transform 0.15s;
+	}
+	.chev.collapsed {
+		transform: rotate(-90deg);
+	}
+	.count {
+		min-width: 1.6rem;
+		padding: 0 0.45rem;
+		border-radius: 1rem;
+		background: var(--surface-2);
+		color: var(--muted);
+		font-size: 0.8rem;
+		text-align: center;
+		line-height: 1.5rem;
+		font-weight: 600;
+	}
+	ul {
+		list-style: none;
+		margin: 0;
+		padding: 0;
+	}
+	.row {
+		display: flex;
+		align-items: center;
+		gap: 0.25rem;
+		min-height: 3rem;
+		padding: 0 0.5rem 0 0.25rem;
+		border-top: 1px solid var(--border);
+	}
+	.state {
+		display: grid;
+		place-items: center;
+		width: 2.5rem;
+		color: var(--muted);
+	}
+	.state.on {
+		color: var(--accent-text);
+	}
+	.name {
+		flex: 1;
+		min-width: 0;
+		padding: 0.7rem 0.25rem;
+		font-weight: 500;
+		overflow-wrap: anywhere;
+	}
+	.row :global(.icon-btn) {
+		color: var(--muted);
+	}
+	.empty-row {
+		padding: 0.75rem 1rem;
+		border-top: 1px solid var(--border);
+	}
+</style>

package/dist/ActiveList.svelte.d.ts

@@ -0,0 +1,54 @@
+declare function $$render<T extends {
+    id: string;
+    active: boolean;
+}>(): {
+    props: {
+        items: T[];
+        /** Plural noun for headings, e.g. "Members". */
+        noun: string;
+        label: (item: T) => string;
+        onopen: (item: T) => void;
+        ontoggle: (item: T, active: boolean) => void;
+        readOnly?: boolean;
+        inactiveOpen?: boolean;
+        emptyText?: string;
+        /**
+         * `card` (default): rounded cards. `lines`: fills its container edge to edge with no card,
+         * so the rows read like lines on paper.
+         */
+        appearance?: "card" | "lines";
+    };
+    exports: {};
+    bindings: "inactiveOpen";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends {
+    id: string;
+    active: boolean;
+}> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "inactiveOpen";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends {
+        id: string;
+        active: boolean;
+    }>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends {
+        id: string;
+        active: boolean;
+    }>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const ActiveList: $$IsomorphicComponent;
+type ActiveList<T extends {
+    id: string;
+    active: boolean;
+}> = InstanceType<typeof ActiveList<T>>;
+export default ActiveList;

package/dist/AddRow.svelte

@@ -0,0 +1,69 @@
+<script lang="ts">
+	import { Icon } from '@wells-nelson/displays';
+
+	let { placeholder, label, onadd }: { placeholder: string; label: string; onadd: (name: string) => void } =
+		$props();
+
+	let value = $state('');
+	let input: HTMLInputElement | undefined = $state();
+
+	function submit(e: SubmitEvent) {
+		e.preventDefault();
+		const name = value.trim();
+		if (!name) return;
+		onadd(name);
+		value = '';
+		// Ready for the next one, whether Enter or the plus button was used.
+		input?.focus();
+	}
+</script>
+
+<form class="add-row" onsubmit={submit}>
+	<input type="text" bind:this={input} bind:value {placeholder} aria-label={label} enterkeyhint="done" />
+	<button type="submit" aria-label={label} title={label} disabled={!value.trim()}>
+		<Icon name="plus" />
+	</button>
+</form>
+
+<style>
+	.add-row {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		padding: 0.4rem 0.4rem 0.4rem 0.9rem;
+		background: var(--surface);
+		border: 1px dashed var(--border-strong);
+		border-radius: var(--radius);
+	}
+	input {
+		flex: 1;
+		min-width: 0;
+		border: none;
+		background: transparent;
+		padding: 0.4rem 0;
+		box-shadow: none;
+	}
+	input:focus {
+		outline: none;
+		box-shadow: none;
+	}
+	.add-row:focus-within {
+		border-style: solid;
+		border-color: var(--accent);
+	}
+	button {
+		display: grid;
+		place-items: center;
+		width: 2.4rem;
+		height: 2.4rem;
+		border: none;
+		border-radius: 50%;
+		background: var(--accent);
+		color: var(--on-accent);
+		cursor: pointer;
+	}
+	button:disabled {
+		background: var(--border-strong);
+		cursor: not-allowed;
+	}
+</style>

package/dist/AddRow.svelte.d.ts

@@ -0,0 +1,8 @@
+type $$ComponentProps = {
+    placeholder: string;
+    label: string;
+    onadd: (name: string) => void;
+};
+declare const AddRow: import("svelte").Component<$$ComponentProps, {}, "">;
+type AddRow = ReturnType<typeof AddRow>;
+export default AddRow;

package/dist/Checkbox.svelte

@@ -0,0 +1,65 @@
+<script lang="ts">
+	import { Icon } from '@wells-nelson/displays';
+
+	let {
+		checked = $bindable(false),
+		label,
+		hideLabel = false,
+		onchange
+	}: { checked?: boolean; label: string; hideLabel?: boolean; onchange?: (checked: boolean) => void } =
+		$props();
+</script>
+
+<label class="checkbox" class:bare={hideLabel}>
+	<input type="checkbox" bind:checked onchange={() => onchange?.(checked)} aria-label={hideLabel ? label : undefined} />
+	<span class="box" aria-hidden="true"><Icon name="check" size={16} /></span>
+	{#if !hideLabel}<span class="text">{label}</span>{/if}
+</label>
+
+<style>
+	.checkbox {
+		position: relative;
+		display: inline-flex;
+		align-items: center;
+		gap: 0.6rem;
+		cursor: pointer;
+		min-height: 2.25rem;
+	}
+	.bare {
+		min-width: 2.5rem;
+		justify-content: center;
+	}
+	/* The real input covers the whole control (invisible), so every tap lands on it. */
+	input {
+		position: absolute;
+		inset: 0;
+		width: 100%;
+		height: 100%;
+		margin: 0;
+		opacity: 0;
+		cursor: pointer;
+		z-index: 1;
+	}
+	.box {
+		display: grid;
+		place-items: center;
+		width: 1.4rem;
+		height: 1.4rem;
+		border: 2px solid var(--border-strong);
+		border-radius: 0.4rem;
+		color: transparent;
+		background: var(--surface);
+		transition:
+			background-color 0.15s,
+			border-color 0.15s;
+	}
+	input:checked + .box {
+		background: var(--accent);
+		border-color: var(--accent);
+		color: var(--on-accent);
+	}
+	input:focus-visible + .box {
+		outline: 2px solid var(--accent);
+		outline-offset: 2px;
+	}
+</style>

package/dist/Checkbox.svelte.d.ts

@@ -0,0 +1,9 @@
+type $$ComponentProps = {
+    checked?: boolean;
+    label: string;
+    hideLabel?: boolean;
+    onchange?: (checked: boolean) => void;
+};
+declare const Checkbox: import("svelte").Component<$$ComponentProps, {}, "checked">;
+type Checkbox = ReturnType<typeof Checkbox>;
+export default Checkbox;

package/dist/CollapsibleSection.svelte

@@ -0,0 +1,225 @@
+<script lang="ts">
+	import { Icon, IconButton } from '@wells-nelson/displays';
+	import { tick, type Snippet } from 'svelte';
+	import { draggable, dropZone, type DragData, type DropZoneOptions } from './dnd.js';
+
+	/**
+	 * A card whose header (chevron, title, count, add and edit actions) stays pinned below the app
+	 * header while you scroll through its rows. Collapsed sections hide rows with CSS rather than
+	 * unmounting them, so a row being dragged stays attached to the page.
+	 * Children are rendered inside a <ul>; give draggable rows `data-dnd-item`.
+	 */
+	let {
+		title,
+		count,
+		countLabel = (n: number) => `${n} items`,
+		collapsed,
+		ontogglecollapse,
+		onedit,
+		editLabel = 'Edit',
+		onadd,
+		addLabel = 'Add item',
+		dragData,
+		ondragstart,
+		ondragend,
+		drop,
+		variant = 'default',
+		appearance = 'card',
+		appHeaderSelector = '.app-header',
+		children
+	}: {
+		title: string;
+		count: number;
+		countLabel?: (count: number) => string;
+		collapsed: boolean;
+		ontogglecollapse: () => void;
+		/** Opens the section's settings (pencil icon, right of the plus). */
+		onedit?: () => void;
+		editLabel?: string;
+		onadd?: () => void;
+		addLabel?: string;
+		/** Set to make the whole section long-press draggable (reordering sections). */
+		dragData?: DragData;
+		ondragstart?: () => void;
+		ondragend?: () => void;
+		/** Accept dropped rows. */
+		drop?: DropZoneOptions;
+		/** `subtle` gives the header a muted background (e.g. an "unallocated" bucket). */
+		variant?: 'default' | 'subtle';
+		/**
+		 * `card` (default): a rounded card. `lines`: fills its container edge to edge with no card,
+		 * so sections and rows read like lines on paper. The pinned header needs an opaque
+		 * background: set `--section-header-bg` to whatever it sits on (default `--bg`).
+		 */
+		appearance?: 'card' | 'lines';
+		/** The fixed app header, measured when scrolling a collapsed section back into view. */
+		appHeaderSelector?: string;
+		children: Snippet;
+	} = $props();
+
+	const noDrop: DropZoneOptions = { accepts: () => false, ondrop: () => {} };
+	const noDrag: DragData = { type: 'none', id: '' };
+
+	let section: HTMLElement | undefined = $state();
+	let header: HTMLElement | undefined = $state();
+
+	/** Space left above a section scrolled back into view after collapsing. */
+	const COLLAPSE_MARGIN = 12;
+
+	/**
+	 * Collapsing from the pinned header while scrolled down inside a long section would leave the
+	 * page somewhere further down; scroll up so the collapsed section is in view near the top.
+	 * Scrolling up brings an auto-hiding app header back, so the section lands below the header's
+	 * full height plus a small margin, not where the pinned header happened to be.
+	 */
+	async function toggle() {
+		const pinnedTop = header?.getBoundingClientRect().top ?? 0;
+		const wasPinned = !collapsed && !!section && section.getBoundingClientRect().top < pinnedTop - 1;
+		ontogglecollapse();
+		if (!wasPinned) return;
+		await tick();
+		if (!section) return;
+		const appHeader = document.querySelector(appHeaderSelector);
+		const target = (appHeader?.getBoundingClientRect().height ?? 0) + COLLAPSE_MARGIN;
+		window.scrollBy({ top: section.getBoundingClientRect().top - target });
+	}
+</script>
+
+<section
+	bind:this={section}
+	class={['group', variant, appearance, appearance === 'card' && 'card', collapsed && 'collapsed']}
+	data-dnd-item={dragData ? '' : undefined}
+	use:dropZone={drop ?? noDrop}
+>
+	<div
+		bind:this={header}
+		class="group-header"
+		use:draggable={{ data: dragData ?? noDrag, disabled: !dragData, onstart: ondragstart, onend: ondragend }}
+	>
+		<button
+			type="button"
+			class="collapse"
+			aria-expanded={!collapsed}
+			aria-label={collapsed ? `Expand ${title}` : `Collapse ${title}`}
+			onclick={toggle}
+		>
+			<span class="chev" class:collapsed><Icon name="chevron" size={20} /></span>
+		</button>
+		<!-- The name toggles collapse too; settings live behind the pencil. -->
+		<button type="button" class="title" aria-expanded={!collapsed} onclick={toggle}>{title}</button>
+		<span class="count" aria-label={countLabel(count)}>{count}</span>
+		{#if onadd}
+			<IconButton icon="plus" label={addLabel} onclick={onadd} />
+		{/if}
+		{#if onedit}
+			<IconButton icon="pencil" label={editLabel} size={20} onclick={onedit} />
+		{/if}
+	</div>
+	<ul class="items" hidden={collapsed}>
+		{@render children()}
+	</ul>
+</section>
+
+<style>
+	.group {
+		position: relative;
+	}
+	.group-header {
+		position: sticky;
+		top: var(--header-offset, 0px);
+		z-index: 5;
+		display: flex;
+		align-items: center;
+		gap: 0.15rem;
+		min-height: 3rem;
+		padding: 0.15rem 0.25rem;
+		background: var(--surface);
+		transition: top 0.2s ease;
+		-webkit-touch-callout: none;
+		user-select: none;
+	}
+	.subtle .group-header {
+		background: var(--surface-2);
+	}
+
+	/*
+	 * Card: the section can't clip its children (that would break the sticky header), so whatever
+	 * sits at the bottom rounds its own corners to match the card's: the header while nothing is
+	 * below it, otherwise the rows. Inner radius = card radius minus its 1px border.
+	 */
+	.card {
+		--inner-radius: calc(var(--radius) - 1px);
+	}
+	.card .group-header {
+		border-radius: var(--inner-radius) var(--inner-radius) 0 0;
+	}
+	.card.collapsed .group-header,
+	.card .group-header:has(+ .items:empty) {
+		border-radius: var(--inner-radius);
+	}
+	.card .items {
+		overflow: hidden;
+		border-radius: 0 0 var(--inner-radius) var(--inner-radius);
+	}
+
+	/* Lines: edge to edge, a rule under each section; rows bring their own rules. */
+	.lines {
+		width: 100%;
+		border-bottom: 1px solid var(--border);
+	}
+	.lines .group-header {
+		background: var(--section-header-bg, var(--bg));
+	}
+	.lines.subtle .group-header {
+		background: var(--surface-2);
+	}
+	.collapse {
+		display: grid;
+		place-items: center;
+		width: 2.5rem;
+		height: 2.5rem;
+		border: none;
+		background: none;
+		border-radius: 50%;
+		cursor: pointer;
+		color: var(--muted);
+	}
+	.collapse:hover {
+		background: var(--surface-hover);
+	}
+	.chev {
+		transition: transform 0.15s;
+	}
+	.chev.collapsed {
+		transform: rotate(-90deg);
+	}
+	.title {
+		flex: 1;
+		min-width: 0;
+		padding: 0.5rem 0.25rem;
+		border: none;
+		background: none;
+		text-align: left;
+		font-weight: 700;
+		font-size: 1.02rem;
+		cursor: pointer;
+		overflow-wrap: anywhere;
+	}
+	.count {
+		min-width: 1.6rem;
+		padding: 0 0.45rem;
+		border-radius: 1rem;
+		background: var(--surface-2);
+		color: var(--muted);
+		font-size: 0.8rem;
+		text-align: center;
+		line-height: 1.5rem;
+	}
+	.items {
+		margin: 0;
+		padding: 0;
+	}
+	.items:empty {
+		display: none;
+	}
+</style>