@axium/client 0.29.0 → 0.30.0

package/dist/gui/controls.d.ts

@@ -0,0 +1,31 @@
+export interface TriggerModifiers {
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+}
+export interface MouseTrigger extends TriggerModifiers {
+    button: number;
+}
+/** @see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/location */
+export declare const enum KeyLocation {
+    Standard = 0,
+    Left = 1,
+    Right = 2,
+    Numpad = 3
+}
+export interface KeyboardTrigger extends TriggerModifiers {
+    key: string;
+    location?: KeyLocation;
+}
+export type Trigger = KeyboardTrigger | MouseTrigger;
+export interface WithAction<TData extends unknown[]> {
+    action(...args: TData): unknown;
+}
+export interface KeyboardHandler<TData extends unknown[]> extends KeyboardTrigger, WithAction<TData> {
+}
+export interface MouseHandler<TData extends unknown[]> extends MouseTrigger, WithAction<TData> {
+}
+export type Handler<TData extends unknown[]> = KeyboardHandler<TData> | MouseHandler<TData>;
+export declare function isMatch(trigger: Trigger, event: KeyboardEvent | MouseEvent): boolean;
+export declare function find<T extends Trigger>(triggers: T[], event: KeyboardEvent | MouseEvent): T | undefined;

package/dist/gui/controls.js

@@ -0,0 +1,24 @@
+/** @see https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/location */
+export var KeyLocation;
+(function (KeyLocation) {
+    KeyLocation[KeyLocation["Standard"] = 0] = "Standard";
+    KeyLocation[KeyLocation["Left"] = 1] = "Left";
+    KeyLocation[KeyLocation["Right"] = 2] = "Right";
+    KeyLocation[KeyLocation["Numpad"] = 3] = "Numpad";
+})(KeyLocation || (KeyLocation = {}));
+export function isMatch(trigger, event) {
+    if (('ctrl' in trigger && trigger.ctrl !== event.ctrlKey) ||
+        ('shift' in trigger && trigger.shift !== event.shiftKey) ||
+        ('alt' in trigger && trigger.alt !== event.altKey) ||
+        ('meta' in trigger && trigger.meta !== event.metaKey))
+        return false;
+    return 'key' in trigger
+        ? 'key' in event && event.key === trigger.key && (!('location' in trigger) || trigger.location === event.location)
+        : 'button' in event && event.button === trigger.button;
+}
+export function find(triggers, event) {
+    for (const trigger of triggers) {
+        if (isMatch(trigger, event))
+            return trigger;
+    }
+}

package/dist/gui/index.d.ts

@@ -1,2 +1,3 @@
 export * from './animate.js';
 export * from './clipboard.js';
+export * as controls from './controls.js';

package/dist/gui/index.js

@@ -1,2 +1,3 @@
 export * from './animate.js';
 export * from './clipboard.js';
+export * as controls from './controls.js';

package/lib/Audio.svelte

@@ -3,7 +3,7 @@
 	import type { Snippet } from 'svelte';
 	import Icon from './Icon.svelte';
 	import MediaControls from './MediaControls.svelte';
-	import { getMetadata, MediaState, type MediaPicture, type MediaProps } from './media.svelte.js';
+	import { getMetadata, MediaState, type MediaPicture, type MediaProps } from './reactive/media.svelte.js';
 
 	interface Props extends MediaProps {
 		cover?: boolean;

package/lib/MediaControls.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import { formatDuration } from '@axium/core';
 	import Icon from './Icon.svelte';
-	import type { MediaState } from './media.svelte.js';
+	import type { MediaState } from './reactive/media.svelte.js';
 	import type { Snippet } from 'svelte';
 
 	interface Props {

package/lib/Video.svelte

@@ -2,7 +2,7 @@
 	import type { Snippet } from 'svelte';
 	import Icon from './Icon.svelte';
 	import MediaControls from './MediaControls.svelte';
-	import { MediaState, type MediaProps } from './media.svelte.js';
+	import { MediaState, type MediaProps } from './reactive/media.svelte.js';
 
 	interface Props extends MediaProps {
 		extraControls?: Snippet;

package/lib/attachments/selection.ts

@@ -1,6 +1,10 @@
+import { controls } from '@axium/client/gui';
 import type { Attachment } from 'svelte/attachments';
 import { SvelteSet } from 'svelte/reactivity';
 
+/** A keyboard control bound to a {@link Selection}, e.g. `F2` to rename or `Ctrl+C` to copy. */
+export type SelectionControl = controls.KeyboardHandler<[selection: Selection]>;
+
 /**
  * Manages a reusable, list-wide selection across items rendered with the {@link selectable} attachment.
  *
@@ -16,6 +20,13 @@ export class Selection extends SvelteSet<string> {
 	/** The id of the last item interacted with, used as the anchor for shift-click ranges. */
 	#anchor?: string;
 
+	constructor(
+		/** Keyboard controls dispatched by {@link handleKeyboard}. */
+		protected readonly controls: SelectionControl[] = []
+	) {
+		super();
+	}
+
 	/**
 	 * Update the ordered list of item ids. Call this whenever the rendered order changes
 	 * (e.g. after sorting or loading a new directory).
@@ -32,6 +43,12 @@ export class Selection extends SvelteSet<string> {
 		this.#anchor = undefined;
 	}
 
+	add(id: string): this {
+		super.add(id);
+		this.#anchor = id;
+		return this;
+	}
+
 	/** Apply selection behavior for a click on `id` with the given modifier keys. */
 	handleClick(id: string, e: { shiftKey: boolean; ctrlKey: boolean; metaKey: boolean }): void {
 		if (e.shiftKey && this.#anchor) {
@@ -41,7 +58,7 @@ export class Selection extends SvelteSet<string> {
 				const [lo, hi] = start < end ? [start, end] : [end, start];
 				const range = new Set(this.#order.slice(lo, hi + 1));
 				super.clear();
-				for (const rangeId of range) this.add(rangeId);
+				for (const rangeId of range) super.add(rangeId);
 				return;
 			}
 		}
@@ -49,13 +66,22 @@ export class Selection extends SvelteSet<string> {
 		if (e.ctrlKey || e.metaKey) {
 			if (this.has(id)) this.delete(id);
 			else this.add(id);
-			this.#anchor = id;
 			return;
 		}
 
 		super.clear();
 		this.add(id);
-		this.#anchor = id;
+	}
+
+	/**
+	 * Dispatch a keyboard event to a matching control, if any. Returns whether a control handled it.
+	 */
+	handleKeyboard(e: KeyboardEvent): boolean {
+		const control = controls.find(this.controls, e);
+		if (!control) return false;
+
+		control.action(this);
+		return true;
 	}
 }
 
@@ -69,10 +95,8 @@ export class Selection extends SvelteSet<string> {
 export function selectable(selection: Selection, id: string): Attachment<HTMLElement> {
 	return function _attachSelectable(element: HTMLElement) {
 		function onclick(e: MouseEvent) {
-			// Let interactive descendants (action buttons, etc.) opt out of triggering selection.
-			for (let node = e.target as HTMLElement | null; node && node != element; node = node.parentElement) {
+			for (let node = e.target as HTMLElement | null; node && node != element; node = node.parentElement)
 				if (node.hasAttribute('data-no-select')) return;
-			}
 
 			if (e.shiftKey || e.ctrlKey || e.metaKey) {
 				e.preventDefault();
@@ -82,9 +106,33 @@ export function selectable(selection: Selection, id: string): Attachment<HTMLEle
 		}
 
 		element.addEventListener('click', onclick, { capture: true });
+		return () => element.removeEventListener('click', onclick, { capture: true });
+	};
+}
+
+/** Elements that consume keyboard input themselves, and so should suppress selection controls. */
+function isTypingTarget(target: EventTarget | null): boolean {
+	if (!(target instanceof HTMLElement)) return false;
+	return target.isContentEditable || target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement;
+}
+
+/**
+ * Register a {@link Selection}'s keyboard controls (e.g. `F2` to rename) on the document.
+ *
+ * This is separate from {@link selectable} so the controls work regardless of which element is focused.
+ * Controls are ignored while the user is typing in an input, textarea, or other editable element.
+ */
+export function selectionControls(selection: Selection): Attachment {
+	return function _attachSelectionControls() {
+		function onkeydown(e: KeyboardEvent) {
+			if (isTypingTarget(e.target)) return;
+			if (selection.handleKeyboard(e)) {
+				e.preventDefault();
+				e.stopPropagation();
+			}
+		}
 
-		return () => {
-			element.removeEventListener('click', onclick, { capture: true });
-		};
+		document.addEventListener('keydown', onkeydown);
+		return () => document.removeEventListener('keydown', onkeydown);
 	};
 }

package/lib/reactive/clipboard.svelte.ts

@@ -0,0 +1,77 @@
+import { SvelteSet } from 'svelte/reactivity';
+
+interface StoredClipboard<T extends string | boolean | bigint | number> {
+	isCopy: boolean;
+	values: T[];
+}
+
+/**
+ * A reactive, cross-tab clipboard for "cut" and "copy" of values.
+ *
+ * State is mirrored to `localStorage` so it is shared across all tabs of the origin.
+ */
+export class SyncedClipboard<T extends string | boolean | bigint | number> extends SvelteSet<T> {
+	/** The current clipboard mode, or `undefined` when the clipboard is empty. Reactive. */
+	isCopy = $state<boolean>();
+
+	constructor(protected readonly key = 'clipboard') {
+		super();
+
+		this.load();
+
+		addEventListener('storage', e => {
+			if (e.key == this.key) this.load();
+		});
+	}
+
+	/** Whether the clipboard currently holds anything. */
+	get active(): boolean {
+		return typeof this.isCopy === 'boolean' && this.size > 0;
+	}
+
+	/** Place the given values on the clipboard to be moved on paste. */
+	cut(values: Iterable<T>): void {
+		this.isCopy = false;
+		this.set([...values]);
+	}
+
+	/** Place the given values on the clipboard to be duplicated on paste. */
+	copy(values: Iterable<T>): void {
+		this.isCopy = true;
+		this.set([...values]);
+	}
+
+	/** Empty the clipboard. */
+	clear(): void {
+		this.isCopy = undefined;
+		super.clear();
+		if (typeof localStorage != 'undefined') localStorage.removeItem(this.key);
+	}
+
+	protected set(values: T[]): void {
+		super.clear();
+		for (const value of values) this.add(value);
+		if (typeof localStorage != 'undefined')
+			localStorage.setItem(this.key, JSON.stringify({ isCopy: this.isCopy!, values } satisfies StoredClipboard<T>));
+	}
+
+	protected load(): void {
+		if (typeof localStorage == 'undefined') return;
+
+		const raw = localStorage.getItem(this.key);
+		if (!raw) {
+			this.isCopy = undefined;
+			super.clear();
+			return;
+		}
+
+		try {
+			const { isCopy, values } = JSON.parse(raw) as StoredClipboard<T>;
+			this.isCopy = isCopy;
+			for (const value of this) if (!values.includes(value)) this.delete(value);
+			for (const value of values) this.add(value);
+		} catch {
+			this.clear();
+		}
+	}
+}

package/lib/reactive/index.svelte.ts

@@ -0,0 +1,2 @@
+export * from './clipboard.svelte.js';
+export * from './media.svelte.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@axium/client",
-	"version": "0.29.0",
+	"version": "0.30.0",
 	"author": "James Prevett <jp@jamespre.dev>",
 	"funding": {
 		"type": "individual",
@@ -39,6 +39,7 @@
 		"./components/*": "./lib/*.svelte",
 		"./toast": "./lib/toast.js",
 		"./attachments": "./lib/attachments/index.js",
+		"./reactive": "./lib/reactive/index.svelte.js",
 		"./styles/*": "./styles/*.css"
 	},
 	"scripts": {