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

package/dist/combobox/combobox.state.d.ts

@@ -0,0 +1,80 @@
+export interface ComboboxRow {
+  readonly value: string;
+  readonly label: string;
+  readonly disabled?: boolean;
+  readonly group?: string;
+  readonly index?: number;
+  readonly meta?: Readonly<Record<string, string>> | undefined;
+}
+export type ComboboxState = "idle" | "focused" | "interacting" | "suggesting";
+export interface ComboboxContext {
+  value: string[];
+  inputValue: string;
+  highlightedValue: string | null;
+  autofill: string | null;
+  order: string[];
+  labels: Record<string, string>;
+  multiple: boolean;
+  closeOnSelect: boolean;
+  allowCustomValue: boolean;
+  inputBehavior: "none" | "autocomplete" | "autohighlight";
+  selectionBehavior: "replace" | "preserve" | "clear";
+  openOnChange: boolean;
+  openOnKeyPress: boolean;
+  alwaysSubmitOnEnter: boolean;
+  items: readonly ComboboxRow[];
+  disabled: boolean;
+  readOnly: boolean;
+  invalid: boolean;
+  required: boolean;
+  composite: boolean;
+  placement: string;
+  name: string;
+  form: string;
+  placeholder: string;
+  triggerLabel: string;
+  clearTriggerLabel: string;
+  openOnClick: boolean;
+  loopFocus: boolean;
+  dir: "ltr" | "rtl";
+}
+export interface ComboboxArgs {
+  items?: readonly ComboboxRow[];
+  value?: string;
+  inputValue?: string;
+  highlightedValue?: string;
+  multiple?: boolean;
+  closeOnSelect?: boolean;
+  allowCustomValue?: boolean;
+  inputBehavior?: string;
+  selectionBehavior?: string;
+  openOnChange?: boolean;
+  openOnKeyPress?: boolean;
+  alwaysSubmitOnEnter?: boolean;
+  defaultOpenOnChange?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  invalid?: boolean;
+  required?: boolean;
+  composite?: boolean;
+  placement?: string;
+  name?: string;
+  form?: string;
+  placeholder?: string;
+  triggerLabel?: string;
+  clearTriggerLabel?: string;
+  openOnClick?: boolean;
+  loopFocus?: boolean;
+  dir?: "ltr" | "rtl";
+}
+/** Shape raw items the way `initial` does: arrays pass through, anything
+ * else becomes empty. Shared by `initial` and the field contract, so a
+ * host write parses exactly like the seed. */
+export declare function parseItems(raw: unknown): readonly ComboboxRow[];
+declare const parseKeys: (raw: unknown) => string[];
+export declare function initial(args: ComboboxArgs, authored: (name: string) => boolean): ComboboxContext;
+export declare const stringifyValues: (ctx: ComboboxContext, values: readonly string[]) => string;
+export declare const pickOutcome: (ctx: ComboboxContext, value: string) => string[];
+export declare const isCustomValue: (ctx: ComboboxContext) => boolean;
+export { parseKeys };
+//# sourceMappingURL=combobox.state.d.ts.map

package/dist/combobox/combobox.state.js

@@ -0,0 +1,71 @@
+import { defaultTwin } from "@spinjs/runtime";
+// src/combobox/combobox.state.ts
+/** Shape raw items the way `initial` does: arrays pass through, anything
+* else becomes empty. Shared by `initial` and the field contract, so a
+* host write parses exactly like the seed. */
+function parseItems(raw) {
+	return Array.isArray(raw) ? raw : [];
+}
+const parseKeys = (raw) => {
+	if (Array.isArray(raw)) return raw.filter((v) => typeof v === "string");
+	if (typeof raw !== "string") return [];
+	return raw.length > 0 ? raw.split(",").map((s) => s.trim()).filter(Boolean) : [];
+};
+const textProp = (raw) => typeof raw === "string" ? raw : "";
+const nullableProp = (raw) => typeof raw === "string" && raw.length > 0 ? raw : null;
+function initial(args, authored) {
+	const written = (field) => authored(field) || authored(defaultTwin(field)) || args[defaultTwin(field)] !== void 0;
+	const multiple = written("multiple") ? args.multiple === true : false;
+	const selectionRaw = args.selectionBehavior;
+	const selectionBehavior = written("selectionBehavior") ? selectionRaw === "preserve" || selectionRaw === "clear" ? selectionRaw : multiple ? "clear" : "replace" : multiple ? "clear" : "replace";
+	const behaviorRaw = args.inputBehavior;
+	const inputBehavior = written("inputBehavior") ? behaviorRaw === "autocomplete" || behaviorRaw === "autohighlight" ? behaviorRaw : "none" : "none";
+	const rows = parseItems(args.items);
+	const order = rows.map((r) => typeof r.value === "string" ? r.value : "").filter(Boolean);
+	const labels = Object.fromEntries(rows.map((r) => [String(r.value), typeof r.label === "string" ? r.label : String(r.value)]));
+	const value = parseKeys(args.value);
+	const seedCtx = {
+		value,
+		inputValue: "",
+		highlightedValue: nullableProp(args.highlightedValue),
+		autofill: null,
+		order,
+		labels,
+		multiple,
+		closeOnSelect: written("closeOnSelect") ? args.closeOnSelect === true : !multiple,
+		allowCustomValue: written("allowCustomValue") ? args.allowCustomValue === true : false,
+		inputBehavior,
+		selectionBehavior,
+		openOnChange: written("openOnChange") ? args.openOnChange !== false : true,
+		openOnKeyPress: written("openOnKeyPress") ? args.openOnKeyPress !== false : true,
+		alwaysSubmitOnEnter: written("alwaysSubmitOnEnter") ? args.alwaysSubmitOnEnter === true : false,
+		items: rows,
+		disabled: args.disabled === true,
+		readOnly: args.readOnly === true,
+		invalid: args.invalid === true,
+		required: args.required === true,
+		composite: args.composite !== false,
+		placement: typeof args.placement === "string" && args.placement.length > 0 ? args.placement : "bottom",
+		name: typeof args.name === "string" ? args.name : "",
+		form: typeof args.form === "string" ? args.form : "",
+		placeholder: typeof args.placeholder === "string" ? args.placeholder : "",
+		triggerLabel: typeof args.triggerLabel === "string" ? args.triggerLabel : "",
+		clearTriggerLabel: typeof args.clearTriggerLabel === "string" ? args.clearTriggerLabel : "",
+		openOnClick: args.openOnClick !== false,
+		loopFocus: args.loopFocus === true,
+		dir: args.dir === "rtl" ? "rtl" : "ltr"
+	};
+	const valueAsString = value.map((v) => labels[v] ?? v).join(", ");
+	const seeded = textProp(args.inputValue);
+	const inputValue = seeded.trim().length > 0 || multiple ? seeded : selectionBehavior === "clear" ? "" : valueAsString;
+	return {
+		...seedCtx,
+		inputValue
+	};
+}
+const stringifyValues = (ctx, values) => values.map((value) => ctx.labels[value]).filter((l) => l !== void 0).join(", ");
+const pickOutcome = (ctx, value) => ctx.multiple ? ctx.value.includes(value) ? ctx.value.filter((v) => v !== value) : [...ctx.value, value] : [value];
+const isCustomValue = (ctx) => ctx.inputValue !== stringifyValues(ctx, ctx.value);
+export { initial, isCustomValue, parseItems, parseKeys, pickOutcome, stringifyValues };
+
+//# sourceMappingURL=combobox.state.js.map

package/dist/combobox/combobox.transitions.d.ts

@@ -0,0 +1,28 @@
+import { ComboboxEvents } from "./combobox.events.js";
+import { ComboboxContext } from "./combobox.state.js";
+import { AssignFor, GuardFor } from "@spinjs/runtime/fsm";
+type Ctx = ComboboxContext;
+type Ev = ComboboxEvents;
+type ComboboxAssign<K extends keyof Ev = keyof Ev> = AssignFor<Ctx, Ev, K>;
+declare const at: (list: readonly string[], index: number) => string | null;
+declare const completion: (ctx: Ctx, value: string, keypress: boolean) => string | null;
+declare const inlineSingle: (ctx: Ctx) => boolean;
+declare const applySelection: (ctx: Ctx, next: readonly string[]) => Partial<Ctx>;
+export declare const setHighlightedValue: ComboboxAssign<"HIGHLIGHTED_VALUE.SET" | "ITEM.POINTER_MOVE">;
+export declare const clearHighlightedValue: () => Partial<Ctx>;
+export declare const moveHighlight: ComboboxAssign<"INPUT.ARROW_DOWN" | "INPUT.ARROW_UP" | "INPUT.HOME" | "INPUT.END">;
+export declare const highlightFirstItem: (ctx: Ctx) => Partial<Ctx>;
+export declare const highlightFirstOrSelectedItem: (ctx: Ctx) => Partial<Ctx>;
+export declare const selectItem: ComboboxAssign<"ITEM.SELECT" | "ITEM.CLICK">;
+export declare const selectHighlightedItem: ComboboxAssign<"INPUT.ENTER">;
+export declare const clearValue: (ctx: Ctx) => Partial<Ctx>;
+export declare const clearInputValue: () => Partial<Ctx>;
+export declare const setInputValue: ComboboxAssign<"INPUT.CHANGE" | "INPUT_VALUE.SET">;
+export declare const revertInputValue: (ctx: Ctx) => Partial<Ctx>;
+export declare const inlineAutocomplete: (ctx: Ctx) => boolean;
+export declare const closeOnSelect: (ctx: Ctx) => boolean;
+export declare const revertsToValue: (ctx: Ctx) => boolean;
+export declare const isCustomValueGuard: GuardFor<Ctx, Ev>;
+export declare const inlineSingleGuard: GuardFor<Ctx, Ev>;
+export { applySelection, at, completion, inlineSingle };
+//# sourceMappingURL=combobox.transitions.d.ts.map

package/dist/combobox/combobox.transitions.js

@@ -0,0 +1,91 @@
+import { isCustomValue, stringifyValues } from "./combobox.state.js";
+// src/combobox/combobox.transitions.ts
+const at = (list, index) => list.at(index) ?? null;
+const completion = (ctx, value, keypress) => {
+	if (!keypress || ctx.inputBehavior !== "autocomplete") return null;
+	return ctx.labels[value] ?? ctx.inputValue;
+};
+const inlineSingle = (ctx) => ctx.inputBehavior === "autocomplete" && !ctx.multiple;
+const applySelection = (ctx, next) => ({
+	value: [...next],
+	inputValue: ctx.selectionBehavior === "preserve" ? ctx.inputValue : ctx.selectionBehavior === "clear" ? "" : stringifyValues(ctx, next),
+	autofill: null
+});
+const setHighlightedValue = (ctx, e) => {
+	if (e.type === "ITEM.POINTER_MOVE") return {
+		highlightedValue: e.value,
+		autofill: completion(ctx, e.value, false)
+	};
+	if (e.type !== "HIGHLIGHTED_VALUE.SET" || e.value === null) return {};
+	return {
+		highlightedValue: e.value,
+		autofill: completion(ctx, e.value, e.keypress === true)
+	};
+};
+const clearHighlightedValue = () => ({
+	highlightedValue: null,
+	autofill: null
+});
+const moveHighlight = (ctx, e) => {
+	if (e.value === void 0) return {};
+	return {
+		highlightedValue: e.value,
+		autofill: completion(ctx, e.value, e.keypress === true)
+	};
+};
+const highlightFirstItem = (ctx) => ctx.order.length === 0 ? {} : {
+	highlightedValue: at(ctx.order, 0),
+	autofill: null
+};
+const highlightFirstOrSelectedItem = (ctx) => {
+	const selected = ctx.order.filter((value) => ctx.value.includes(value));
+	const value = selected.length > 0 ? at(selected, 0) : at(ctx.order, 0);
+	if (value === null) return {};
+	return {
+		highlightedValue: value,
+		autofill: null
+	};
+};
+const selectItem = (ctx, e) => {
+	if (e.type !== "ITEM.SELECT" && e.type !== "ITEM.CLICK") return {};
+	const value = e.value;
+	const next = ctx.multiple ? ctx.value.includes(value) ? ctx.value.filter((v) => v !== value) : [...ctx.value, value] : [value];
+	return applySelection(ctx, next);
+};
+const selectHighlightedItem = (ctx) => {
+	if (ctx.highlightedValue === null || !ctx.order.includes(ctx.highlightedValue)) return {};
+	const value = ctx.highlightedValue;
+	const next = ctx.multiple ? ctx.value.includes(value) ? ctx.value.filter((v) => v !== value) : [...ctx.value, value] : [value];
+	return applySelection(ctx, next);
+};
+const clearValue = (ctx) => applySelection(ctx, []);
+const clearInputValue = () => ({
+	inputValue: "",
+	autofill: null
+});
+const setInputValue = (_ctx, e) => {
+	if (e.type !== "INPUT.CHANGE" && e.type !== "INPUT_VALUE.SET") return {};
+	return {
+		inputValue: e.value,
+		autofill: null
+	};
+};
+const revertInputValue = (ctx) => {
+	if (ctx.selectionBehavior === "preserve") return {};
+	if (ctx.selectionBehavior === "clear") return {
+		inputValue: "",
+		autofill: null
+	};
+	return {
+		inputValue: ctx.value.length > 0 ? stringifyValues(ctx, ctx.value) : "",
+		autofill: null
+	};
+};
+const inlineAutocomplete = (ctx) => ctx.inputBehavior === "autocomplete" && !ctx.multiple;
+const closeOnSelect = (ctx) => ctx.closeOnSelect;
+const revertsToValue = (ctx) => isCustomValue(ctx) && !ctx.allowCustomValue && ctx.highlightedValue === null;
+const isCustomValueGuard = (ctx) => isCustomValue(ctx) && !ctx.allowCustomValue;
+const inlineSingleGuard = (ctx) => inlineAutocomplete(ctx) && ctx.highlightedValue === at(ctx.order, -1) ? true : false;
+export { applySelection, at, clearHighlightedValue, clearInputValue, clearValue, closeOnSelect, completion, highlightFirstItem, highlightFirstOrSelectedItem, inlineAutocomplete, inlineSingle, inlineSingleGuard, isCustomValueGuard, moveHighlight, revertInputValue, revertsToValue, selectHighlightedItem, selectItem, setHighlightedValue, setInputValue };
+
+//# sourceMappingURL=combobox.transitions.js.map

package/dist/combobox/examples/basic.html

@@ -0,0 +1,61 @@
+<script lang="ts">
+  import { combobox } from "../combobox.presentation.js";
+
+  const machine = combobox({items: [{"value":"apple","label":"Apple"},{"value":"apricot","label":"Apricot"},{"value":"banana","label":"Banana"},{"value":"blueberry","label":"Blueberry"}]});
+</script>
+
+<div class="relative w-64 max-w-full" {...machine.getRootProps()}>
+  <label
+    class={["block text-sm font-medium text-text transition-colors duration-fast ease-decelerate", { "opacity-50 cursor-not-allowed": machine.disabled, "text-primary": machine.focused }]}
+    {...machine.getLabelProps()}
+  >Fruit</label>
+
+  <div class="relative" {...machine.getControlProps()}>
+    <input
+      class={["w-full pr-16 transition-colors duration-fast ease-decelerate placeholder:text-text-muted", { "opacity-60 cursor-not-allowed": machine.disabled, "border-border-strong": machine.invalid, "border-primary": machine.open }]}
+      {...machine.getInputProps()}
+    />
+
+    <div class="absolute inset-y-0 right-0 flex items-center gap-1 pr-1">
+      <button
+        class={["ghost icon s-sm"]}
+        {...machine.getClearTriggerProps()}
+      ><span aria-hidden="true"><span class="inline-block icon-sm i-lucide-x" aria-hidden="true"></span></span></button>
+      <button
+        class={["ghost icon s-sm", { "cursor-not-allowed": machine.disabled }]}
+        {...machine.getTriggerProps()}
+      ><span aria-hidden="true" class={["text-xs transition-transform duration-fast ease-decelerate", { "rotate-180": machine.open }]} {...machine.getTriggerIndicatorProps()}><span class="inline-block icon-sm i-lucide-chevron-down" aria-hidden="true"></span></span></button>
+    </div>
+
+    <div
+      class={["absolute left-0 top-full z-dropdown mt-1 w-full origin-top transition duration-fast ease-decelerate", { "pointer-events-none invisible scale-95 opacity-0": !machine.open }]}
+      {...machine.getPositionerProps()}
+    >
+      <div
+        class={["overflow-hidden rounded-lg border border-solid border-border bg-surface-raised shadow-lg", { "opacity-60": machine.disabled }]}
+        {...machine.getContentProps()}
+      >
+        <div class={["max-h-[15rem] overflow-y-auto p-1 transition-opacity duration-fast ease-decelerate", { "hidden": machine.empty }]} {...machine.getListProps()}>
+          <template for={machine.getBlocks()} as={block} key={block.id}>
+            <div class="py-1" {...machine.getItemGroupProps(block)}>
+              <span class="block px-2 py-1 text-xs font-medium text-text-muted" {...machine.getItemGroupLabelProps(block)}>{block.label}</span>
+              <template for={machine.getRows(block)} as={row} key={row.value}>
+                <div
+                  class={["relative flex cursor-default select-none items-center gap-2 rounded-md px-2 py-1 text-sm text-text transition-colors duration-fast ease-decelerate", { "bg-surface": machine.highlightedValue === row.value, "text-primary": machine.value.includes(row.value), "cursor-not-allowed opacity-50": machine.disabled }]}
+                  {...machine.getItemProps(row)}
+                >
+                  <span class="min-w-0 flex-1 truncate" {...machine.getItemTextProps(row)}>{row.label}</span>
+                  <span
+                    aria-hidden="true"
+                    class={["shrink-0 text-xs text-primary scale-50 opacity-0 transition-all duration-fast ease-decelerate", { "scale-100 opacity-100": machine.value.includes(row.value) }]}
+                    {...machine.getItemIndicatorProps(row)}
+                  ><span class="inline-block icon-sm i-lucide-check" aria-hidden="true"></span></span>
+                </div>
+              </template>
+            </div>
+          </template>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>

package/dist/combobox/examples/directory.html

@@ -0,0 +1,71 @@
+<script lang="ts">
+  import { combobox } from "../combobox.presentation.js";
+
+  const machine = combobox({
+    placeholder: "Search directory...",
+    items: [
+      { value: "ada", label: "Ada Lovelace — Analytical Engine" },
+      { value: "grace", label: "Grace Hopper — Compiler Systems" },
+      { value: "margaret", label: "Margaret Hamilton — Flight Software" },
+      { value: "barbara", label: "Barbara Liskov — Distributed Systems" },
+      { value: "radia", label: "Radia Perlman — Network Routing" },
+    ],
+  });
+</script>
+
+<div class="relative w-64 max-w-full" {...machine.getRootProps()}>
+  <label
+    class={["block text-sm font-medium text-text transition-colors duration-fast ease-decelerate", { "opacity-50 cursor-not-allowed": machine.disabled, "text-primary": machine.focused }]}
+    {...machine.getLabelProps()}
+  >Assignee</label>
+
+  <div class="relative" {...machine.getControlProps()}>
+    <input
+      class={["w-full pr-16 transition-colors duration-fast ease-decelerate placeholder:text-text-muted", { "opacity-60 cursor-not-allowed": machine.disabled, "border-border-strong": machine.invalid, "border-primary": machine.open }]}
+      placeholder="Search directory..."
+      {...machine.getInputProps()}
+    />
+
+    <div class="absolute inset-y-0 right-0 flex items-center gap-1 pr-1">
+      <button
+        class={["ghost icon s-sm"]}
+        {...machine.getClearTriggerProps()}
+      ><span aria-hidden="true"><span class="inline-block icon-sm i-lucide-x" aria-hidden="true"></span></span></button>
+      <button
+        class={["ghost icon s-sm", { "cursor-not-allowed": machine.disabled }]}
+        {...machine.getTriggerProps()}
+      ><span aria-hidden="true" class={["text-xs transition-transform duration-fast ease-decelerate", { "rotate-180": machine.open }]} {...machine.getTriggerIndicatorProps()}><span class="inline-block icon-sm i-lucide-chevron-down" aria-hidden="true"></span></span></button>
+    </div>
+
+    <div
+      class={["absolute left-0 top-full z-dropdown mt-1 w-full origin-top transition duration-fast ease-decelerate", { "pointer-events-none invisible scale-95 opacity-0": !machine.open }]}
+      {...machine.getPositionerProps()}
+    >
+      <div
+        class={["overflow-hidden rounded-lg border border-solid border-border bg-surface-raised shadow-lg", { "opacity-60": machine.disabled }]}
+        {...machine.getContentProps()}
+      >
+        <div class={["max-h-[15rem] overflow-y-auto p-1 transition-opacity duration-fast ease-decelerate", { "hidden": machine.empty }]} {...machine.getListProps()}>
+          <template for={machine.getBlocks()} as={block} key={block.id}>
+            <div class="py-1" {...machine.getItemGroupProps(block)}>
+              <span class="block px-2 py-1 text-xs font-medium text-text-muted" {...machine.getItemGroupLabelProps(block)}>{block.label}</span>
+              <template for={machine.getRows(block)} as={row} key={row.value}>
+                <div
+                  class={["relative flex cursor-default select-none items-center gap-2 rounded-md px-2 py-1 text-sm text-text transition-colors duration-fast ease-decelerate", { "bg-surface": machine.highlightedValue === row.value, "text-primary": machine.value.includes(row.value), "cursor-not-allowed opacity-50": machine.disabled }]}
+                  {...machine.getItemProps(row)}
+                >
+                  <span class="min-w-0 flex-1 truncate" {...machine.getItemTextProps(row)}>{row.label}</span>
+                  <span
+                    aria-hidden="true"
+                    class={["shrink-0 text-xs text-primary scale-50 opacity-0 transition-all duration-fast ease-decelerate", { "scale-100 opacity-100": machine.value.includes(row.value) }]}
+                    {...machine.getItemIndicatorProps(row)}
+                  ><span class="inline-block icon-sm i-lucide-check" aria-hidden="true"></span></span>
+                </div>
+              </template>
+            </div>
+          </template>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>

package/dist/combobox/examples/grouping.html

@@ -0,0 +1,36 @@
+<script lang="ts">
+  import { combobox } from "../combobox.presentation.js";
+
+  const machine = combobox({items: [{"value":"react","label":"React","group":"JS"},{"value":"solid","label":"Solid","group":"JS"},{"value":"vue","label":"Vue","group":"JS"},{"value":"svelte","label":"Svelte","group":"JS"},{"value":"panda","label":"Panda","group":"CSS"},{"value":"tailwind","label":"Tailwind","group":"CSS"}]});
+</script>
+
+<div class="relative w-64 max-w-full" {...machine.getRootProps()}>
+  <label class={["block text-sm font-medium text-text transition-colors duration-fast ease-decelerate", { "opacity-50 cursor-not-allowed": machine.disabled, "text-primary": machine.focused }]} {...machine.getLabelProps()}>Technology</label>
+
+  <div class="relative" {...machine.getControlProps()}>
+    <input class={["w-full pr-16 transition-colors duration-fast ease-decelerate placeholder:text-text-muted", { "opacity-60 cursor-not-allowed": machine.disabled, "border-border-strong": machine.invalid, "border-primary": machine.open }]} {...machine.getInputProps()} placeholder="Select a technology..." />
+
+    <div class="absolute inset-y-0 right-0 flex items-center gap-1 pr-1">
+      <button class={["ghost icon s-sm"]} {...machine.getClearTriggerProps()}><span aria-hidden="true"><span class="inline-block icon-sm i-lucide-x" aria-hidden="true"></span></span></button>
+      <button class={["ghost icon s-sm", { "cursor-not-allowed": machine.disabled }]} {...machine.getTriggerProps()}><span aria-hidden="true" class={["text-xs transition-transform duration-fast ease-decelerate", { "rotate-180": machine.open }]} {...machine.getTriggerIndicatorProps()}><span class="inline-block icon-sm i-lucide-chevron-down" aria-hidden="true"></span></span></button>
+    </div>
+
+    <div class={["absolute left-0 top-full z-dropdown mt-1 w-full origin-top transition duration-fast ease-decelerate", { "pointer-events-none invisible scale-95 opacity-0": !machine.open }]} {...machine.getPositionerProps()}>
+      <div class={["overflow-hidden rounded-lg border border-solid border-border bg-surface-raised shadow-lg", { "opacity-60": machine.disabled }]} {...machine.getContentProps()}>
+        <div class={["max-h-[15rem] overflow-y-auto p-1 transition-opacity duration-fast ease-decelerate", { "hidden": machine.empty }]} {...machine.getListProps()}>
+          <template for={machine.getBlocks()} as={block} key={block.id}>
+            <div class="py-1" {...machine.getItemGroupProps(block)}>
+              <span class="block px-2 py-1 text-xs font-medium text-text-muted" {...machine.getItemGroupLabelProps(block)}>{block.label}</span>
+              <template for={machine.getRows(block)} as={row} key={row.value}>
+                <div class={["relative flex cursor-default select-none items-center gap-2 rounded-md px-2 py-1 text-sm text-text transition-colors duration-fast ease-decelerate", { "bg-surface": machine.highlightedValue === row.value, "text-primary": machine.value.includes(row.value), "cursor-not-allowed opacity-50": machine.disabled }]} {...machine.getItemProps(row)}>
+                  <span class="min-w-0 flex-1 truncate" {...machine.getItemTextProps(row)}>{row.label}</span>
+                  <span aria-hidden="true" class={["shrink-0 text-xs text-primary scale-50 opacity-0 transition-all duration-fast ease-decelerate", { "scale-100 opacity-100": machine.value.includes(row.value) }]} {...machine.getItemIndicatorProps(row)}><span class="inline-block icon-sm i-lucide-check" aria-hidden="true"></span></span>
+                </div>
+              </template>
+            </div>
+          </template>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>

package/dist/combobox/examples/multiple.html

@@ -0,0 +1,37 @@
+<script lang="ts">
+  import { combobox } from "../combobox.presentation.js";
+
+  const machine = combobox({multiple: true, items: [{"value":"javascript","label":"JavaScript"},{"value":"typescript","label":"TypeScript"},{"value":"react","label":"React"},{"value":"vue","label":"Vue"},{"value":"angular","label":"Angular"},{"value":"svelte","label":"Svelte"}]});
+</script>
+
+<div class="relative w-64 max-w-full" {...machine.getRootProps()}>
+  <label class={["block text-sm font-medium text-text transition-colors duration-fast ease-decelerate", { "opacity-50 cursor-not-allowed": machine.disabled, "text-primary": machine.focused }]} {...machine.getLabelProps()}>Skills</label>
+
+  <div class="relative" {...machine.getControlProps()}>
+    <input class={["w-full pr-16 transition-colors duration-fast ease-decelerate placeholder:text-text-muted", { "opacity-60 cursor-not-allowed": machine.disabled, "border-border-strong": machine.invalid, "border-primary": machine.open }]} {...machine.getInputProps()} placeholder="Add skills..." />
+
+    <div class="absolute inset-y-0 right-0 flex items-center gap-1 pr-1">
+      <button class={["ghost icon s-sm"]} {...machine.getClearTriggerProps()}><span aria-hidden="true"><span class="inline-block icon-sm i-lucide-x" aria-hidden="true"></span></span></button>
+      <button class={["ghost icon s-sm", { "cursor-not-allowed": machine.disabled }]} {...machine.getTriggerProps()}><span aria-hidden="true" class={["text-xs transition-transform duration-fast ease-decelerate", { "rotate-180": machine.open }]} {...machine.getTriggerIndicatorProps()}><span class="inline-block icon-sm i-lucide-chevron-down" aria-hidden="true"></span></span></button>
+    </div>
+
+    <div class={["absolute left-0 top-full z-dropdown mt-1 w-full origin-top transition duration-fast ease-decelerate", { "pointer-events-none invisible scale-95 opacity-0": !machine.open }]} {...machine.getPositionerProps()}>
+      <div class={["overflow-hidden rounded-lg border border-solid border-border bg-surface-raised shadow-lg", { "opacity-60": machine.disabled }]} {...machine.getContentProps()}>
+        <div class={["max-h-[15rem] overflow-y-auto p-1 transition-opacity duration-fast ease-decelerate", { "hidden": machine.empty }]} {...machine.getListProps()}>
+          <template for={machine.getBlocks()} as={block} key={block.id}>
+            <div class="py-1" {...machine.getItemGroupProps(block)}>
+              <span class="block px-2 py-1 text-xs font-medium text-text-muted" {...machine.getItemGroupLabelProps(block)}>{block.label}</span>
+              <template for={machine.getRows(block)} as={row} key={row.value}>
+                <div class={["relative flex cursor-default select-none items-center gap-2 rounded-md px-2 py-1 text-sm text-text transition-colors duration-fast ease-decelerate", { "bg-surface": machine.highlightedValue === row.value, "text-primary": machine.value.includes(row.value), "cursor-not-allowed opacity-50": machine.disabled }]} {...machine.getItemProps(row)}>
+                  <span class="min-w-0 flex-1 truncate" {...machine.getItemTextProps(row)}>{row.label}</span>
+                  <span aria-hidden="true" class={["shrink-0 text-xs text-primary scale-50 opacity-0 transition-all duration-fast ease-decelerate", { "scale-100 opacity-100": machine.value.includes(row.value) }]} {...machine.getItemIndicatorProps(row)}><span class="inline-block icon-sm i-lucide-check" aria-hidden="true"></span></span>
+                </div>
+              </template>
+            </div>
+          </template>
+        </div>
+      </div>
+    </div>
+  </div>
+  <p class="mt-2 text-xs text-text-muted" show={machine.hasSelectedItems}>Selected: {machine.valueAsString}</p>
+</div>

package/dist/controller.d.ts

@@ -0,0 +1,52 @@
+import { DefinedComponent } from "@spinjs/runtime";
+/**
+ * The app-controller surface: `{ commands, state, bind, ref }`, for whichever
+ * component the host is holding.
+ *
+ * A component owns its state — a machine does, or the platform does behind a
+ * thin adapter. This handle does not care which: it is the instrument the
+ * host's app controller uses to reach it, through the same context markup
+ * consumes. Nothing here owns state, and nothing here re-implements the
+ * element — the host already has the element; this is what you can DO with
+ * it.
+ *
+ * `bind` needs only the element, so it works before the component connects
+ * — which matters, because a seed (`defaultValue`, `startMs`) is read during
+ * the component's build and a write that arrives after it is too late.
+ * `commands` and `state` resolve through the component's registered
+ * controller, which exists once it has connected; before then commands are
+ * safe no-ops and unknown state keys read `undefined`, and after they are
+ * the component's own surface.
+ */
+/** Any element locator: the element now, or a read of it on every access. */
+export type ElementTarget = Element | (() => Element | null | undefined) | {
+  readonly current?: Element | null | undefined;
+} | {
+  readonly value?: Element | null | undefined;
+} | null | undefined;
+/** Prop-getter names never surface as commands. */
+export type PropGetterName = `get${string}Props` | `get${string}Indexes`;
+/** The callable members of an api, minus prop getters. */
+export type CommandsOf<Api extends object> = { readonly [K in keyof Api as K extends PropGetterName ? never : Api[K] extends ((...args: never[]) => unknown) ? K : never]: Api[K]; };
+/** The readable members of an api, as reactive thunks. */
+export type StateOf<Api extends object> = { readonly [K in keyof Api as Api[K] extends ((...args: never[]) => unknown) ? never : K]: () => Api[K]; };
+/** The inferred ctl for a `DefinedComponent`. */
+export type CtlFor<D> = D extends DefinedComponent<infer Api, infer A> ? SpinComponentCtl<CommandsOf<Api>, StateOf<Api>, Partial<A>> : never;
+/** What a host holds when it holds a spin component. */
+export interface SpinComponentCtl<TCommands extends object = object, TState extends object = Record<string, () => unknown>, TProps extends object = Record<string, unknown>> {
+  /** Imperative calls the component declares. */
+  readonly commands: TCommands;
+  /** Reactive reads of the component's observable state. */
+  readonly state: TState;
+  /** The element setter for JSX `ref={ctl.ref}`; feeds `bind` and resolution. */
+  readonly ref: (el: Element | null | undefined) => void;
+  /** The controlled channel: props down, events up. */
+  bind(props?: TProps, on?: Readonly<Record<string, (event: CustomEvent) => void>>): () => void;
+  /** Re-run `listener` on any state move; returns a disposer. */
+  subscribe(listener: () => void): () => void;
+}
+/** The ctl for `target` — never nullish; resolution happens at call time. */
+export declare function spinComponentCtl<D extends DefinedComponent<any, any>>(def: D): CtlFor<D>;
+export declare function spinComponentCtl<D extends DefinedComponent<any, any>>(target: ElementTarget, def: D): CtlFor<D>;
+export declare function spinComponentCtl<TCommands extends object = object, TState extends object = Record<string, () => unknown>, TProps extends object = Record<string, unknown>>(target: ElementTarget, handle?: object): SpinComponentCtl<TCommands, TState, TProps>;
+//# sourceMappingURL=controller.d.ts.map

package/dist/controller.js

@@ -0,0 +1,90 @@
+import { bindSpinElement } from "./spin-element.js";
+import { controllerOf, effect, scope, signal } from "@spinjs/runtime";
+// src/controller.ts
+function resolveTarget(target) {
+	if (target === null || target === void 0) return void 0;
+	if (typeof target === "function") return target() ?? void 0;
+	if (typeof target !== "object") return void 0;
+	if ("current" in target) return target.current ?? void 0;
+	if ("value" in target) return target.value ?? void 0;
+	return target;
+}
+function spinComponentCtl(target, handleOrDef) {
+	const isDef = (value) => typeof value === "function" && "createBridge" in value;
+	const targetArg = isDef(target) ? void 0 : target;
+	const node = signal(resolveTarget(targetArg));
+	const handle = isDef(handleOrDef) ? handleOrDef : handleOrDef;
+	const resolveController = () => {
+		const el = node() ?? resolveTarget(targetArg);
+		return el === void 0 ? void 0 : controllerOf(el, handle);
+	};
+	return {
+		commands: new Proxy({}, {
+			get: (_t, key) => {
+				const found = resolveController()?.commands[key];
+				if (typeof found === "function") return found;
+				return (..._args) => {};
+			},
+			has: (_t, key) => key in (resolveController()?.commands ?? {}),
+			ownKeys: () => Reflect.ownKeys(resolveController()?.commands ?? {}),
+			getOwnPropertyDescriptor: (_t, key) => {
+				const descriptor = Reflect.getOwnPropertyDescriptor(resolveController()?.commands ?? {}, key);
+				if (descriptor === void 0) return {
+					configurable: true,
+					enumerable: true
+				};
+				return {
+					...descriptor,
+					configurable: true
+				};
+			}
+		}),
+		state: new Proxy({}, {
+			get: (_t, key) => {
+				const found = resolveController()?.state[key];
+				if (typeof found === "function") return found;
+				return () => void 0;
+			},
+			has: (_t, key) => key in (resolveController()?.state ?? {}),
+			ownKeys: () => Reflect.ownKeys(resolveController()?.state ?? {}),
+			getOwnPropertyDescriptor: (_t, key) => {
+				const descriptor = Reflect.getOwnPropertyDescriptor(resolveController()?.state ?? {}, key);
+				if (descriptor === void 0) return {
+					configurable: true,
+					enumerable: true
+				};
+				return {
+					...descriptor,
+					configurable: true
+				};
+			}
+		}),
+		ref: (el) => {
+			node(el ?? void 0);
+		},
+		bind(props, on) {
+			const el = node() ?? resolveTarget(targetArg);
+			if (el === void 0) return () => {};
+			return bindSpinElement(el, {
+				props,
+				on
+			});
+		},
+		subscribe(listener) {
+			const owner = scope();
+			let first = true;
+			owner.run(() => effect(() => {
+				for (const read of Object.values(resolveController()?.state ?? {})) read();
+				if (first) {
+					first = false;
+					return;
+				}
+				listener();
+			}));
+			return () => owner.dispose();
+		}
+	};
+}
+export { spinComponentCtl };
+
+//# sourceMappingURL=controller.js.map