@spinjs/components 0.0.0-stage → 0.1.0-preview.1

package/dist/async-list/async-list.presentation.d.ts

@@ -0,0 +1,294 @@
+import { AsyncListArgs, AsyncListContext, AsyncListState, SortDescriptor } from "./async-list.state.js";
+import { AsyncListEvents } from "./async-list.events.js";
+import { ApiOf, SlotViewFor, ViewFor } from "@spinjs/runtime";
+/**
+ * Async-list definition: the DOM contract as data.
+ *
+ * The fetch lives here and nowhere else: the abort controller and the
+ * sequence number are per-bridge reflexes over host data. The sequence
+ * makes a stale resolution a no-op instead of a write over newer data; the
+ * controller tells a superseded fetch to stop.
+ */
+export interface AsyncListRow {
+  readonly value: string;
+  readonly label: string;
+  readonly index: number;
+}
+/** A sort trigger. */
+export interface SortTrigger {
+  readonly column: string;
+  readonly direction: SortDescriptor["direction"];
+}
+export interface AsyncListSuccess {
+  readonly items: readonly unknown[];
+}
+export interface AsyncListFailure {
+  readonly error: unknown;
+}
+export interface LoadDetails {
+  readonly signal: AbortSignal | undefined;
+  readonly filterText: string;
+  readonly cursor: unknown;
+  readonly sortDescriptor: SortDescriptor | undefined;
+}
+export interface LoadResult {
+  readonly items: readonly unknown[];
+  readonly cursor?: unknown;
+}
+export type LoadFn = (details: LoadDetails) => Promise<LoadResult>;
+export interface SortDetails {
+  readonly items: readonly unknown[];
+  readonly descriptor: SortDescriptor | undefined;
+  readonly filterText: string;
+}
+export type SortResult = {
+  readonly items: readonly unknown[];
+} | undefined;
+export type SortFn = (details: SortDetails) => SortResult | Promise<SortResult>;
+type ScopeLike = ViewFor<AsyncListContext, AsyncListEvents, AsyncListState>;
+type SlotLike<R> = SlotViewFor<R, AsyncListContext, AsyncListEvents, AsyncListState>;
+declare const def: {
+  name: string;
+  machine: (args: AsyncListArgs, authored: (name: string) => boolean) => import("@spinjs/runtime").Machine<AsyncListContext, AsyncListEvents, AsyncListState>;
+  start: "idle";
+  establish: (raw: Record<string, unknown>) => {
+    type: string;
+  }[];
+  settled: ({ event, before, after, root, send }: {
+    readonly event: import("@spinjs/runtime").AnyEvent;
+    readonly before: {
+      readonly context: AsyncListContext;
+      readonly state: AsyncListState;
+    };
+    readonly after: {
+      readonly context: AsyncListContext;
+      readonly state: AsyncListState;
+    };
+    readonly props: Record<string, unknown>;
+    readonly root: () => Element;
+    readonly id: (part: string, slot?: unknown) => string;
+    readonly focus: (part: string, slot?: unknown) => void;
+    readonly measure: (part: string, slot?: unknown) => DOMRect | null;
+    readonly send: (event: import("@spinjs/runtime").AnyEvent) => void;
+  }) => void;
+  scalarsOf: (parsed: Record<string, unknown>) => {
+    hasSortFn: boolean;
+    load: unknown;
+    sortFn: unknown;
+  };
+  reconcile: ({ context, parsed, send }: {
+    readonly context: AsyncListContext;
+    readonly state: AsyncListState;
+    readonly parsed: Record<string, unknown>;
+    readonly authored: (name: string) => boolean;
+    readonly send: (event: {
+      type: string;
+    } & Record<string, unknown>) => void;
+  }) => boolean;
+  parts: {
+    root: {
+      attrs: (scope: ScopeLike) => {
+        "data-state": AsyncListState;
+        "data-loading": string | undefined;
+      };
+    };
+    progress: {
+      attrs: (scope: ScopeLike) => {
+        "data-state": AsyncListState;
+        role: string;
+      };
+    };
+    list: {
+      attrs: (scope: import("@spinjs/runtime").PartView<unknown, AsyncListContext, Record<string, unknown>, import("@spinjs/runtime").EventUnion<AsyncListEvents>, AsyncListState>) => {
+        "data-state": AsyncListState;
+        "data-count": number;
+        "data-empty": string | undefined;
+        role: string;
+      };
+    };
+    empty: {
+      attrs: (scope: import("@spinjs/runtime").PartView<unknown, AsyncListContext, Record<string, unknown>, import("@spinjs/runtime").EventUnion<AsyncListEvents>, AsyncListState>) => {
+        "data-empty": string | undefined;
+      };
+    };
+    error: {
+      attrs: (scope: import("@spinjs/runtime").PartView<unknown, AsyncListContext, Record<string, unknown>, import("@spinjs/runtime").EventUnion<AsyncListEvents>, AsyncListState>) => {
+        role: string;
+        "data-state": string;
+      };
+    };
+    filterInput: {
+      id: string;
+      attrs: (scope: import("@spinjs/runtime").PartView<unknown, AsyncListContext, Record<string, unknown>, import("@spinjs/runtime").EventUnion<AsyncListEvents>, AsyncListState>) => {
+        type: string;
+        value: string;
+        placeholder: string;
+        autoComplete: string;
+        "data-state": AsyncListState;
+        onInput: (event: InputEvent) => void;
+      };
+    };
+    clearFilter: {
+      id: string;
+      attrs: (scope: import("@spinjs/runtime").PartView<unknown, AsyncListContext, Record<string, unknown>, import("@spinjs/runtime").EventUnion<AsyncListEvents>, AsyncListState>) => {
+        type: string;
+        "aria-label": string;
+        "data-filled": string | undefined;
+        hidden: boolean;
+        onClick: () => void;
+      };
+    };
+    reload: {
+      attrs: (scope: ScopeLike) => {
+        type: string;
+        "data-state": AsyncListState;
+        onClick: () => void;
+      };
+    };
+    loadMore: {
+      id: string;
+      attrs: (scope: import("@spinjs/runtime").PartView<unknown, AsyncListContext, Record<string, unknown>, import("@spinjs/runtime").EventUnion<AsyncListEvents>, AsyncListState>) => {
+        type: string;
+        "data-state": AsyncListState;
+        "data-more": string | undefined;
+        hidden: boolean;
+        disabled: boolean;
+        onClick: () => void;
+      };
+    };
+    sentinel: {
+      attrs: (scope: import("@spinjs/runtime").PartView<unknown, AsyncListContext, Record<string, unknown>, import("@spinjs/runtime").EventUnion<AsyncListEvents>, AsyncListState>) => {
+        "data-state": AsyncListState;
+        hidden: boolean;
+        "data-more": string | undefined;
+        "use:infinite-scroll": {
+          enabled: boolean;
+          onLoadMore: () => void;
+        };
+      };
+    };
+  };
+  slots: {
+    item: {
+      indexes: (context: AsyncListContext) => readonly AsyncListRow[];
+      attrs: (scope: SlotLike<AsyncListRow>) => {
+        id: string;
+        role: string;
+        "data-value": string;
+        "data-index": number;
+      };
+    };
+    sortTrigger: {
+      id: string;
+      indexes: () => never[];
+      attrs: (scope: SlotLike<SortTrigger>) => {
+        onClick: () => void;
+        id: string;
+        type: string;
+        "data-column": string;
+        "data-direction": "ascending" | "descending";
+        "data-state": AsyncListState;
+        "data-active": string | undefined;
+      };
+    };
+  };
+  commands: {
+    abort: {
+      event: () => {
+        type: "ABORT";
+      };
+    };
+    reload: {
+      event: () => {
+        type: "RELOAD";
+      };
+    };
+    loadMore: {
+      event: () => {
+        type: "LOAD_MORE";
+      };
+    };
+    sort: {
+      event: ([descriptor]: [descriptor: SortDescriptor]) => {
+        type: "SORT";
+        sortDescriptor: SortDescriptor;
+      };
+    };
+    setFilterText: {
+      event: ([text]: [text: string]) => {
+        type: "FILTER";
+        filterText: string;
+      };
+    };
+    clearFilter: {
+      event: () => {
+        type: "FILTER";
+        filterText: string;
+      };
+    };
+  };
+  readers: {
+    items: {
+      read: (context: AsyncListContext) => unknown[];
+    };
+    loading: {
+      read: (_context: AsyncListContext, state: AsyncListState) => state is "loading" | "sorting";
+    };
+    sorting: {
+      read: (_context: AsyncListContext, state: AsyncListState) => state is "sorting";
+    };
+    empty: {
+      read: (context: AsyncListContext) => boolean;
+    };
+    hasMore: {
+      read: (context: AsyncListContext) => boolean;
+    };
+    error: {
+      read: (context: AsyncListContext) => unknown;
+    };
+    filterText: {
+      read: (context: AsyncListContext) => string;
+    };
+    cursor: {
+      read: (context: AsyncListContext) => {} | undefined;
+    };
+    sortDescriptor: {
+      read: (context: AsyncListContext) => SortDescriptor | undefined;
+    };
+  };
+  methods: {
+    getRows: {
+      call: (context: AsyncListContext) => readonly AsyncListRow[];
+    };
+  };
+  events: {
+    "load-success": {
+      prop: string;
+      watch: () => never[];
+      detail: () => {
+        items: never[];
+      };
+      select: (event: {
+        readonly type: string;
+      } & Record<string, unknown>) => {
+        items: unknown[];
+      } | null;
+    };
+    "load-error": {
+      prop: string;
+      watch: () => never[];
+      detail: () => {
+        error: undefined;
+      };
+      select: (event: {
+        readonly type: string;
+      } & Record<string, unknown>) => {
+        error: unknown;
+      } | null;
+    };
+  };
+};
+export type AsyncListApi = ApiOf<typeof def>;
+export declare const asyncList: import("@spinjs/runtime").DefinedComponent<AsyncListApi, AsyncListArgs>;
+export {};
+//# sourceMappingURL=async-list.presentation.d.ts.map

package/dist/async-list/async-list.presentation.js

@@ -0,0 +1,380 @@
+import { isSortDescriptor, itemsOf } from "./async-list.state.js";
+import { asyncList as asyncList$1 } from "./async-list.machine.js";
+import { ariaBusy, ariaHidden, ariaPressed, dataAttr, defineComponent, isRecord } from "@spinjs/runtime";
+// src/async-list/async-list.presentation.ts
+/** A host function is not something the scope grammar can type, so it
+* rides the prop channel as a property write: declared, read live,
+* checked before it is called. */
+const isLoadFn = (value) => typeof value === "function";
+const isSortFn = (value) => typeof value === "function";
+const filterTextOf = (event) => {
+	const text = event["filterText"];
+	return typeof text === "string" ? text : "";
+};
+const descriptorOf = (event) => {
+	const descriptor = event["sortDescriptor"];
+	return isSortDescriptor(descriptor) ? descriptor : void 0;
+};
+/** A fetch the host was told to stop is not a failure. */
+const isAbortError = (error) => error instanceof Error && error.name === "AbortError";
+const fieldOf = (raw, field) => isRecord(raw) ? raw[field] : void 0;
+const asLoadResult = (raw) => {
+	if (typeof raw !== "object" || raw === null) return { items: [] };
+	const cursor = fieldOf(raw, "cursor");
+	return {
+		items: itemsOf(fieldOf(raw, "items")),
+		...cursor === void 0 ? {} : { cursor }
+	};
+};
+/** No result keeps the items that were sorted. */
+const asSortResult = (raw) => {
+	if (typeof raw !== "object" || raw === null) return void 0;
+	return { items: itemsOf(fieldOf(raw, "items")) };
+};
+const textField = (item, field) => {
+	const raw = fieldOf(item, field);
+	return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+};
+const toRow = (item, index) => {
+	const value = textField(item, "value") ?? String(index);
+	return {
+		value,
+		label: textField(item, "label") ?? value,
+		index
+	};
+};
+const viewByRoot = /* @__PURE__ */ new WeakMap();
+const viewOf = (root) => {
+	let view = viewByRoot.get(root);
+	if (view === void 0) {
+		view = {
+			aborting: void 0,
+			seq: 0,
+			lastDependencies: void 0,
+			rowsSource: void 0,
+			rowsCache: void 0
+		};
+		viewByRoot.set(root, view);
+	}
+	return view;
+};
+/** Advance past the work in flight. A resolution from an earlier sequence
+* is dropped where it lands, and the previous fetch is told to stop. */
+const advanceSequence = (view) => {
+	view.seq += 1;
+	view.aborting?.abort();
+	view.aborting = void 0;
+	return view.seq;
+};
+const startFetch = (view, send, load, event, context) => {
+	const mine = advanceSequence(view);
+	const controller = new AbortController();
+	view.aborting = controller;
+	const loadMore = event.type === "LOAD_MORE";
+	load({
+		signal: controller.signal,
+		filterText: event.type === "FILTER" ? filterTextOf(event) : context.filterText,
+		cursor: loadMore ? context.cursor : null,
+		sortDescriptor: event.type === "SORT" ? descriptorOf(event) : context.sortDescriptor ?? void 0
+	}).then((result) => {
+		if (mine !== view.seq) return;
+		const resolved = asLoadResult(result);
+		send({
+			type: "SUCCESS",
+			items: resolved.items,
+			cursor: resolved.cursor,
+			append: loadMore
+		});
+	}, (error) => {
+		if (mine !== view.seq) return;
+		if (isAbortError(error)) return;
+		send({
+			type: "ERROR",
+			error
+		});
+	});
+};
+const startSort = (view, send, sort, event, context) => {
+	const mine = advanceSequence(view);
+	const details = {
+		items: context.items,
+		descriptor: event.type === "SORT" ? descriptorOf(event) : context.sortDescriptor ?? void 0,
+		filterText: context.filterText
+	};
+	let settled;
+	try {
+		settled = sort(details);
+	} catch (error) {
+		if (mine === view.seq) send({
+			type: "ERROR",
+			error
+		});
+		return;
+	}
+	Promise.resolve(settled).then((result) => {
+		if (mine !== view.seq) return;
+		send({
+			type: "SUCCESS",
+			items: asSortResult(result)?.items ?? context.items,
+			cursor: null,
+			append: false
+		});
+	}, (error) => {
+		if (mine !== view.seq) return;
+		send({
+			type: "ERROR",
+			error
+		});
+	});
+};
+const def = {
+	name: "async-list",
+	machine: (args, authored) => asyncList$1(args, authored),
+	start: "idle",
+	establish: (raw) => {
+		return raw["autoReload"] === true ? [{ type: "RELOAD" }] : [];
+	},
+	settled: ({ event, before, after, root, send }) => {
+		const view = viewOf(root());
+		const load = after.context.load;
+		const beforeState = before.state;
+		const afterCtx = after.context;
+		const afterState = after.state;
+		if (event.type === "ABORT") {
+			if (beforeState !== "idle") advanceSequence(view);
+			return;
+		}
+		if (event.type === "SUCCESS" || event.type === "ERROR") return;
+		if (afterState === "sorting") {
+			const sort = after.context.sortFn;
+			if (!isSortFn(sort)) return;
+			startSort(view, send, sort, event, afterCtx);
+			return;
+		}
+		if (!isLoadFn(load)) return;
+		if (afterState === "loading") startFetch(view, send, load, event, afterCtx);
+	},
+	scalarsOf: (parsed) => ({
+		hasSortFn: isSortFn(parsed["sortFn"]),
+		load: parsed["load"],
+		sortFn: parsed["sortFn"]
+	}),
+	reconcile: ({ context, parsed, send }) => {
+		let moved = false;
+		const raw = parsed["dependencies"];
+		const dependencies = itemsOf(raw).filter((dependency) => Boolean(dependency)).join(",");
+		if (context.dependenciesHash === void 0) {
+			context.dependenciesHash = dependencies;
+			return moved;
+		}
+		if (dependencies !== context.dependenciesHash) {
+			context.dependenciesHash = dependencies;
+			send({ type: "RELOAD" });
+			return true;
+		}
+		return moved;
+	},
+	parts: {
+		root: { attrs: (scope) => ({
+			"data-state": scope.state,
+			"data-loading": scope.attr(scope.state === "loading" || scope.state === "sorting")
+		}) },
+		progress: { attrs: (scope) => ({
+			role: "progressbar",
+			...ariaHidden(true),
+			...ariaBusy(scope.state === "loading" || scope.state === "sorting"),
+			"data-state": scope.state
+		}) },
+		list: { attrs: (scope) => {
+			const count = scope.context.items.length;
+			const loading = scope.state === "loading" || scope.state === "sorting";
+			return {
+				role: "list",
+				...ariaBusy(loading),
+				"data-state": scope.state,
+				"data-count": count,
+				"data-empty": dataAttr(count === 0)
+			};
+		} },
+		empty: { attrs: (scope) => {
+			const count = scope.context.items.length;
+			return { "data-empty": dataAttr(count === 0) };
+		} },
+		error: { attrs: (scope) => {
+			return {
+				role: "alert",
+				"data-state": scope.context.error !== void 0 ? "error" : "idle"
+			};
+		} },
+		filterInput: {
+			id: "filter",
+			attrs: (scope) => {
+				return {
+					type: "text",
+					value: scope.context.filterText,
+					placeholder: "Filter",
+					autoComplete: "off",
+					"data-state": scope.state,
+					onInput: (event) => {
+						const target = event.currentTarget;
+						if (!(target instanceof HTMLInputElement)) return;
+						scope.send({
+							type: "FILTER",
+							filterText: target.value
+						});
+					}
+				};
+			}
+		},
+		clearFilter: {
+			id: "clear-filter",
+			attrs: (scope) => {
+				const empty = scope.context.filterText.length === 0;
+				return {
+					type: "button",
+					"aria-label": "Clear filter",
+					"data-filled": dataAttr(!empty),
+					hidden: empty,
+					onClick: () => scope.send({
+						type: "FILTER",
+						filterText: ""
+					})
+				};
+			}
+		},
+		reload: { attrs: (scope) => ({
+			type: "button",
+			"data-state": scope.state,
+			onClick: () => scope.send({ type: "RELOAD" })
+		}) },
+		loadMore: {
+			id: "load-more",
+			attrs: (scope) => {
+				const more = scope.context.cursor != null;
+				const loading = scope.state === "loading" || scope.state === "sorting";
+				return {
+					type: "button",
+					"data-state": scope.state,
+					"data-more": dataAttr(more),
+					hidden: !more,
+					disabled: loading,
+					onClick: () => scope.send({ type: "LOAD_MORE" })
+				};
+			}
+		},
+		sentinel: { attrs: (scope) => {
+			const more = scope.context.cursor != null;
+			return {
+				...ariaHidden(true),
+				"data-state": scope.state,
+				hidden: !more,
+				"data-more": dataAttr(more),
+				"use:infinite-scroll": {
+					enabled: more,
+					onLoadMore: () => scope.send({ type: "LOAD_MORE" })
+				}
+			};
+		} }
+	},
+	slots: {
+		item: {
+			indexes: (context) => rowsFor(context.items),
+			attrs: (scope) => {
+				const row = scope.slot;
+				return {
+					id: scope.id("item", row.value),
+					role: "listitem",
+					"data-value": row.value,
+					"data-index": row.index
+				};
+			}
+		},
+		sortTrigger: {
+			id: "sort-trigger",
+			indexes: () => [],
+			attrs: (scope) => {
+				const trigger = scope.slot;
+				const ctx = scope.context;
+				const active = ctx.sortDescriptor?.column === trigger.column && ctx.sortDescriptor?.direction === trigger.direction;
+				return {
+					id: scope.id("sortTrigger", `${trigger.column}:${trigger.direction}`),
+					type: "button",
+					"data-column": trigger.column,
+					"data-direction": trigger.direction,
+					"data-state": scope.state,
+					"data-active": dataAttr(active),
+					...ariaPressed(active),
+					onClick: () => scope.send({
+						type: "SORT",
+						sortDescriptor: trigger
+					})
+				};
+			}
+		}
+	},
+	commands: {
+		abort: { event: () => ({ type: "ABORT" }) },
+		reload: { event: () => ({ type: "RELOAD" }) },
+		loadMore: { event: () => ({ type: "LOAD_MORE" }) },
+		sort: { event: ([descriptor]) => ({
+			type: "SORT",
+			sortDescriptor: descriptor
+		}) },
+		setFilterText: { event: ([text]) => ({
+			type: "FILTER",
+			filterText: text
+		}) },
+		clearFilter: { event: () => ({
+			type: "FILTER",
+			filterText: ""
+		}) }
+	},
+	readers: {
+		items: { read: (context) => [...context.items] },
+		loading: { read: (_context, state) => state === "loading" || state === "sorting" },
+		sorting: { read: (_context, state) => state === "sorting" },
+		empty: { read: (context) => context.items.length === 0 },
+		hasMore: { read: (context) => context.cursor != null },
+		error: { read: (context) => context.error },
+		filterText: { read: (context) => context.filterText },
+		cursor: { read: (context) => context.cursor ?? void 0 },
+		sortDescriptor: { read: (context) => context.sortDescriptor ?? void 0 }
+	},
+	methods: { getRows: { call: (context) => {
+		return rowsFor(context.items);
+	} } },
+	events: {
+		"load-success": {
+			prop: "onSuccess",
+			watch: () => [],
+			detail: () => ({ items: [] }),
+			select: (event) => {
+				if (event.type !== "SUCCESS") return null;
+				return { items: [...itemsOf(event["items"])] };
+			}
+		},
+		"load-error": {
+			prop: "onError",
+			watch: () => [],
+			detail: () => ({ error: void 0 }),
+			select: (event) => event.type === "ERROR" ? { error: event["error"] } : null
+		}
+	}
+};
+const toRowIndexed = (item, index) => toRow(item, index);
+/** Rows memoized on the items array's identity: a fresh row object per
+* read would replace the nodes and detach every gesture in flight. A load
+* produces a new array, so the rows rebuild exactly when the data does.
+* Pure data, so sharing one array's rows across bridges is correct. */
+const rowsByItems = /* @__PURE__ */ new WeakMap();
+const rowsFor = (items) => {
+	const hit = rowsByItems.get(items);
+	if (hit !== void 0) return hit;
+	const rows = items.map(toRowIndexed);
+	rowsByItems.set(items, rows);
+	return rows;
+};
+const asyncList = defineComponent(def);
+export { asyncList };
+
+//# sourceMappingURL=async-list.presentation.js.map

package/dist/async-list/async-list.state.d.ts

@@ -0,0 +1,27 @@
+export type AsyncListState = "idle" | "loading" | "sorting";
+export interface SortDescriptor {
+  readonly column: string;
+  readonly direction: "ascending" | "descending";
+}
+export interface AsyncListArgs {
+  initialItems?: readonly unknown[];
+  initialFilterText?: string;
+  initialSortDescriptor?: SortDescriptor;
+  sortFn?: unknown;
+  load?: unknown;
+}
+export interface AsyncListContext {
+  items: readonly unknown[];
+  cursor: unknown;
+  filterText: string;
+  sortDescriptor: SortDescriptor | null;
+  error: unknown;
+  hasSortFn: boolean;
+  dependenciesHash: string | undefined;
+  load?: unknown;
+  sortFn?: unknown;
+}
+export declare const isSortDescriptor: (value: unknown) => value is SortDescriptor;
+export declare function itemsOf(raw: unknown): readonly unknown[];
+export declare function initial(args?: AsyncListArgs, authored?: (name: string) => boolean): AsyncListContext;
+//# sourceMappingURL=async-list.state.d.ts.map