@proyecto-viviana/solid-stately 0.6.0-rc.0 → 0.6.0-rc.2

package/src/select/createSelectState.ts

@@ -17,13 +17,12 @@
  * Based on @react-stately/select useSelectState.
  */
 
-import { createMemo } from "solid-js";
+import { createMemo, untrack } from "solid-js";
 import type { Accessor } from "solid-js";
-import { createInternalSignal, access, type MaybeAccessor } from "../utils";
+import { createInternalSignal, propsAccessor, type MaybeAccessor } from "../utils";
 import { createListState } from "../collections/createListState";
 import { createOverlayTriggerState } from "../overlays";
-import type { Key, CollectionNode, Collection } from "../collections/types";
-import type { SelectionMode, Selection } from "../collections/types";
+import type { Key, CollectionNode, Collection, FocusStrategy } from "../collections/types";
 import type { SelectionManager } from "../selection/SelectionManager";
 import {
   createFormValidationState,
@@ -31,7 +30,22 @@ import {
   type ValidationFunction,
 } from "../form";
 
-export interface SelectStateProps<T = unknown> {
+/** Select never uses the collection `"none"` mode. */
+export type SelectSelectionMode = "single" | "multiple";
+
+/** Single mode is `Key | null`. Multiple mode is `readonly Key[]`. */
+export type SelectValueType<M extends SelectSelectionMode> = M extends "single"
+  ? Key | null
+  : readonly Key[];
+
+/** `onChange` receives a mutable `Key[]` in multiple mode. */
+export type SelectChangeValueType<M extends SelectSelectionMode> = M extends "single"
+  ? Key | null
+  : Key[];
+
+type SelectValidationType<M extends SelectSelectionMode> = M extends "single" ? Key : Key[];
+
+export interface SelectStateProps<T = unknown, M extends SelectSelectionMode = "single"> {
   /** The items to display in the select. */
   items: T[];
   /** Function to get the key for an item. */
@@ -42,26 +56,48 @@ export interface SelectStateProps<T = unknown> {
   getDisabled?: (item: T) => boolean;
   /** Keys of disabled items. */
   disabledKeys?: Iterable<Key>;
-  /** The currently selected key (controlled). */
+  /**
+   * Whether single or multiple selection is enabled.
+   * @default 'single'
+   */
+  selectionMode?: M;
+  /**
+   * The current value (controlled).
+   * Single mode is `Key | null`. Multiple mode is `readonly Key[]`.
+   */
+  value?: SelectValueType<M>;
+  /** The default value (uncontrolled). */
+  defaultValue?: SelectValueType<M>;
+  /** Handler called when the value changes. */
+  onChange?: (value: SelectChangeValueType<M>) => void;
+  /**
+   * The currently selected key in the collection (controlled).
+   * @deprecated Use `value`.
+   */
   selectedKey?: Key | null;
-  /** The default selected key (uncontrolled). */
+  /**
+   * The initial selected key in the collection (uncontrolled).
+   * @deprecated Use `defaultValue`.
+   */
   defaultSelectedKey?: Key | null;
-  /** The selected keys (controlled, for multiple selection mode). */
-  selectedKeys?: "all" | Iterable<Key>;
-  /** Default selected keys (uncontrolled, for multiple selection mode). */
-  defaultSelectedKeys?: "all" | Iterable<Key>;
-  /** Handler called when the selection changes. */
+  /**
+   * Handler that is called when the selection changes.
+   * @deprecated Use `onChange`.
+   */
   onSelectionChange?: (key: Key | null) => void;
-  /** Handler called when selected keys change. */
-  onSelectionChangeKeys?: (keys: Selection) => void;
-  /** Selection mode for the select. */
-  selectionMode?: Extract<SelectionMode, "single" | "multiple">;
   /** Whether the select is open (controlled). */
   isOpen?: boolean;
   /** Whether the select is open by default (uncontrolled). */
   defaultOpen?: boolean;
   /** Handler called when the open state changes. */
   onOpenChange?: (isOpen: boolean) => void;
+  /**
+   * Whether the Select should close when an item is selected. Defaults to true
+   * when selectionMode is single, false otherwise.
+   */
+  shouldCloseOnSelect?: boolean;
+  /** Whether the select should be allowed to be open when the collection is empty. */
+  allowsEmptyCollection?: boolean;
   /** Whether the select is disabled. */
   isDisabled?: boolean;
   /** Whether the select is required. */
@@ -71,7 +107,7 @@ export interface SelectStateProps<T = unknown> {
   /** @deprecated Use isInvalid instead. */
   validationState?: "valid" | "invalid";
   /** Custom validation function. */
-  validate?: ValidationFunction<Key | null | Selection>;
+  validate?: ValidationFunction<SelectValidationType<M> | null>;
   /**
    * Whether to use native HTML form validation or ARIA validation semantics.
    * @default "native"
@@ -81,7 +117,10 @@ export interface SelectStateProps<T = unknown> {
   name?: string | string[];
 }
 
-export interface SelectState<T = unknown> extends FormValidationState {
+export interface SelectState<
+  T = unknown,
+  M extends SelectSelectionMode = "single",
+> extends FormValidationState {
   /** The collection of items. */
   readonly collection: Accessor<Collection<T>>;
   /**
@@ -92,23 +131,48 @@ export interface SelectState<T = unknown> extends FormValidationState {
   /** Whether the select dropdown is open. */
   readonly isOpen: Accessor<boolean>;
   /** Open the select dropdown. */
-  open(): void;
+  open(focusStrategy?: FocusStrategy | null): void;
   /** Close the select dropdown. */
   close(): void;
   /** Toggle the select dropdown. */
-  toggle(): void;
-  /** The currently selected key. */
+  toggle(focusStrategy?: FocusStrategy | null): void;
+  /** Controls which item will be auto focused when the menu opens. */
+  readonly focusStrategy: Accessor<FocusStrategy | null>;
+  /**
+   * The key for the first selected item.
+   * @deprecated Use `value`.
+   */
   readonly selectedKey: Accessor<Key | null>;
-  /** The selected keys. */
-  readonly selectedKeys: Accessor<Selection>;
-  /** The currently selected item. */
-  readonly selectedItem: Accessor<CollectionNode<T> | null>;
-  /** The currently selected items. */
-  readonly selectedItems: Accessor<CollectionNode<T>[]>;
-  /** Set the selected key. */
+  /**
+   * The default selected key.
+   * @deprecated Use `defaultValue`.
+   */
+  readonly defaultSelectedKey: Key | null;
+  /**
+   * Sets the selected key.
+   * @deprecated Use `setValue`.
+   */
   setSelectedKey(key: Key | null): void;
-  /** Set selected keys. */
+  /** The current select value. */
+  readonly value: Accessor<SelectValueType<M>>;
+  /** The default select value. */
+  readonly defaultValue: SelectValueType<M>;
+  /** Sets the select value. */
+  setValue(value: Key | readonly Key[] | null): void;
+  /**
+   * Selected keys derived from `value`.
+   * Kept for list and hidden-select adapters. Never `"all"`.
+   */
+  readonly selectedKeys: Accessor<Set<Key>>;
+  /** Replace the selected keys. */
   setSelectedKeys(keys: Iterable<Key>): void;
+  /**
+   * The value of the first selected item.
+   * @deprecated Use `selectedItems`.
+   */
+  readonly selectedItem: Accessor<CollectionNode<T> | null>;
+  /** The value of the selected items. */
+  readonly selectedItems: Accessor<CollectionNode<T>[]>;
   /** The currently focused key. */
   readonly focusedKey: Accessor<Key | null>;
   /** Set the focused key. */
@@ -124,20 +188,29 @@ export interface SelectState<T = unknown> extends FormValidationState {
   /** Whether the select is required. */
   readonly isRequired: boolean;
   /** The selection mode. */
-  readonly selectionMode: Accessor<"single" | "multiple">;
+  readonly selectionMode: Accessor<M>;
+  /** Whether selecting an item closes the menu. */
+  readonly shouldCloseOnSelect: Accessor<boolean>;
+}
+
+function convertValue(value: Key | readonly Key[] | null | undefined): readonly Key[] | undefined {
+  if (value === undefined) return undefined;
+  if (value === null || typeof value === "string" || typeof value === "number") {
+    return value == null ? [] : [value];
+  }
+  return value;
 }
 
 /**
  * Creates state for a select component.
  * Combines list state with overlay trigger state for dropdown behavior.
  */
-export function createSelectState<T = unknown>(
-  props: MaybeAccessor<SelectStateProps<T>>,
-): SelectState<T> {
-  const getProps = () => access(props);
-  const selectionMode: Accessor<"single" | "multiple"> = () => getProps().selectionMode ?? "single";
+export function createSelectState<T = unknown, M extends SelectSelectionMode = "single">(
+  props: MaybeAccessor<SelectStateProps<T, M>>,
+): SelectState<T, M> {
+  const getProps = propsAccessor(props);
+  const selectionMode: Accessor<M> = () => (getProps().selectionMode ?? "single") as M;
 
-  // Overlay trigger state for open/close
   const overlayState = createOverlayTriggerState({
     get isOpen() {
       return getProps().isOpen;
@@ -150,85 +223,137 @@ export function createSelectState<T = unknown>(
     },
   });
 
-  // Track selected key
-  const isControlledSingle = () => getProps().selectedKey !== undefined;
-  const isControlledMultiple = () => getProps().selectedKeys !== undefined;
-  const [internalSelectedKey, setInternalSelectedKey] = createInternalSignal<Key | null>(
-    getProps().defaultSelectedKey ?? null,
-  );
-  const [internalSelectedKeys, setInternalSelectedKeys] = createInternalSignal<Selection>(
-    getProps().defaultSelectedKeys === "all"
-      ? "all"
-      : new Set(getProps().defaultSelectedKeys ?? []),
-  );
+  const resolvedDefault = untrack((): Key | readonly Key[] | null => {
+    const current = getProps();
+    if (current.defaultValue !== undefined) {
+      return current.defaultValue as Key | readonly Key[] | null;
+    }
+    const mode = current.selectionMode ?? "single";
+    return mode === "single" ? (current.defaultSelectedKey ?? null) : [];
+  });
 
-  const selectedKey: Accessor<Key | null> = () => {
-    if (selectionMode() === "multiple") {
-      const keys = selectedKeys();
-      if (keys === "all") return null;
-      return keys.size > 0 ? Array.from(keys)[0] : null;
+  const controlledProp = (): SelectValueType<M> | undefined => {
+    const current = getProps();
+    if (current.value !== undefined) return current.value;
+    if (selectionMode() === "single" && current.selectedKey !== undefined) {
+      return (current.selectedKey ?? null) as SelectValueType<M>;
     }
+    return undefined;
+  };
+
+  const [internalValue, setInternalValue] = createInternalSignal<Key | readonly Key[] | null>(
+    resolvedDefault,
+  );
 
-    return isControlledSingle() ? (getProps().selectedKey ?? null) : internalSelectedKey();
+  const readControlled = (): Key | readonly Key[] | null | undefined => {
+    const controlled = controlledProp();
+    return controlled === undefined ? undefined : (controlled as Key | readonly Key[] | null);
   };
 
-  const setSelectedKey = (key: Key | null) => {
-    if (selectionMode() === "multiple") {
-      if (key == null) {
-        if (!isControlledMultiple()) {
-          setInternalSelectedKeys(new Set<Key>());
-        }
-        getProps().onSelectionChangeKeys?.(new Set<Key>());
-        getProps().onSelectionChange?.(null);
-      } else {
-        const next = new Set([key]);
-        if (!isControlledMultiple()) {
-          setInternalSelectedKeys(next);
+  let valueRef: Key | readonly Key[] | null = untrack(() => {
+    const controlled = readControlled();
+    return controlled !== undefined ? controlled : internalValue();
+  });
+  let wroteThisTurn = false;
+
+  const syncValueRef = () => {
+    if (wroteThisTurn) return;
+    const controlled = readControlled();
+    valueRef = controlled !== undefined ? controlled : untrack(internalValue);
+  };
+
+  const displayValue = (): Key | readonly Key[] | null => {
+    const controlled = readControlled();
+    const raw = controlled !== undefined ? controlled : internalValue();
+    if (
+      selectionMode() === "single" &&
+      raw !== null &&
+      typeof raw !== "string" &&
+      typeof raw !== "number"
+    ) {
+      return raw[0] ?? null;
+    }
+    return raw;
+  };
+
+  const setValue = (next: Key | readonly Key[] | null) => {
+    syncValueRef();
+    if (selectionMode() === "single") {
+      const key: Key | null =
+        typeof next === "string" || typeof next === "number"
+          ? next
+          : next === null
+            ? null
+            : (next[0] ?? null);
+      // Both callbacks follow this request, not a comparison with displayValue.
+      // A refused controlled value stays stale for the turn, so a second
+      // same-key call would notify the legacy callback again. React Stately
+      // still compares displayValue; this is the Solid same-turn adaptation.
+      // A later turn resyncs valueRef, and a different key is its own request.
+      if (!Object.is(valueRef, key)) {
+        valueRef = key;
+        wroteThisTurn = true;
+        queueMicrotask(() => {
+          wroteThisTurn = false;
+        });
+        if (controlledProp() === undefined) {
+          setInternalValue(key);
         }
-        getProps().onSelectionChangeKeys?.(next);
+        getProps().onChange?.(key as SelectChangeValueType<M>);
         getProps().onSelectionChange?.(key);
       }
       return;
     }
 
-    if (!isControlledSingle()) {
-      setInternalSelectedKey(key);
-    }
-    getProps().onSelectionChange?.(key);
-    getProps().onSelectionChangeKeys?.(key != null ? new Set([key]) : new Set<Key>());
-  };
-
-  const selectedKeys: Accessor<Selection> = createMemo(() => {
-    if (selectionMode() === "multiple") {
-      if (isControlledMultiple()) {
-        const keys = getProps().selectedKeys;
-        return keys === "all" ? "all" : new Set<Key>(keys ?? []);
+    // Keep the readonly list for state. `onChange` receives its own mutable copy.
+    const keys: readonly Key[] =
+      typeof next === "string" || typeof next === "number" ? [next] : next === null ? [] : next;
+    if (!Object.is(valueRef, keys)) {
+      valueRef = keys;
+      wroteThisTurn = true;
+      queueMicrotask(() => {
+        wroteThisTurn = false;
+      });
+      if (controlledProp() === undefined) {
+        setInternalValue(keys);
       }
-      return internalSelectedKeys();
+      getProps().onChange?.([...keys] as SelectChangeValueType<M>);
     }
-
-    const key = selectedKey();
-    return key != null ? new Set<Key>([key]) : new Set<Key>();
-  });
+  };
 
   const setSelectedKeys = (keys: Iterable<Key>) => {
-    const next = new Set(keys);
     if (selectionMode() === "multiple") {
-      if (!isControlledMultiple()) {
-        setInternalSelectedKeys(next);
-      }
-      getProps().onSelectionChangeKeys?.(next);
-      getProps().onSelectionChange?.(next.size > 0 ? Array.from(next)[0] : null);
+      setValue([...keys]);
       return;
     }
-
-    const key = next.size > 0 ? Array.from(next)[0] : null;
-    setSelectedKey(key);
+    let key: Key | null = null;
+    for (const item of keys) {
+      key = item;
+      break;
+    }
+    setValue(key);
   };
 
+  const initialDisplay = untrack(displayValue);
+  const stateDefaultValue = (resolvedDefault ?? initialDisplay) as SelectValueType<M>;
+  const defaultSelectedKey =
+    untrack(() => getProps().defaultSelectedKey) ??
+    (untrack(() => getProps().selectionMode) === "single" ? (initialDisplay as Key) : null);
+
+  const shouldCloseOnSelect = () => getProps().shouldCloseOnSelect ?? selectionMode() === "single";
+
   const validation = createFormValidationState({
     get value() {
-      return selectionMode() === "multiple" ? selectedKeys() : selectedKey();
+      const display = displayValue();
+      if (
+        display !== null &&
+        typeof display !== "string" &&
+        typeof display !== "number" &&
+        display.length === 0
+      ) {
+        return null;
+      }
+      return display;
     },
     get isInvalid() {
       return getProps().isInvalid;
@@ -237,7 +362,7 @@ export function createSelectState<T = unknown>(
       return getProps().validationState;
     },
     get validate() {
-      return getProps().validate;
+      return getProps().validate as ValidationFunction<unknown> | undefined;
     },
     get name() {
       return getProps().name;
@@ -247,7 +372,6 @@ export function createSelectState<T = unknown>(
     },
   });
 
-  // Create list state with select selection mode
   const listState = createListState<T>({
     get items() {
       return getProps().items;
@@ -274,39 +398,32 @@ export function createSelectState<T = unknown>(
     },
     allowDuplicateSelectionEvents: true,
     get selectedKeys() {
-      const keys = selectedKeys();
-      if (keys === "all") return "all";
-      return keys;
+      return convertValue(displayValue()) ?? [];
     },
     onSelectionChange(keys) {
-      if (selectionMode() === "multiple") {
-        if (!isControlledMultiple()) {
-          setInternalSelectedKeys(keys);
-        }
-        getProps().onSelectionChangeKeys?.(keys);
-        if (keys !== "all") {
-          getProps().onSelectionChange?.(keys.size > 0 ? Array.from(keys)[0] : null);
-        }
-        validation.commitValidation();
-        return;
-      }
-
-      // Get the first (and only) selected key
       if (keys === "all") return;
-      const key = keys.size > 0 ? Array.from(keys)[0] : null;
-      setSelectedKey(key);
-      overlayState.close();
+      if (selectionMode() === "single") {
+        setValue(keys.values().next().value ?? null);
+      } else {
+        setValue([...keys]);
+      }
+      if (shouldCloseOnSelect()) {
+        overlayState.close();
+      }
       validation.commitValidation();
     },
   });
 
+  const [focusStrategy, setFocusStrategy] = createInternalSignal<FocusStrategy | null>(null);
   // The select's own focus state (the trigger), separate from the collection's
   // focus-within state on the selection manager — upstream useSelectState keeps
   // these apart with a dedicated useState. Sharing the manager's signal makes
   // trigger focus re-arm the item roving-focus effect and steal focus back.
   const [isFocused, setFocused] = createInternalSignal(false);
 
-  // Get the selected item from the collection (memoized)
+  const selectedKey: Accessor<Key | null> = () => listState.selectionManager.firstSelectedKey;
+  const selectedKeys: Accessor<Set<Key>> = () => new Set(convertValue(displayValue()) ?? []);
+
   const selectedItem: Accessor<CollectionNode<T> | null> = createMemo(() => {
     const key = selectedKey();
     if (key == null) return null;
@@ -314,48 +431,53 @@ export function createSelectState<T = unknown>(
   });
 
   const selectedItems: Accessor<CollectionNode<T>[]> = createMemo(() => {
-    const keys = selectedKeys();
-    if (keys === "all") {
-      return Array.from(listState.collection());
-    }
-
     const items: CollectionNode<T>[] = [];
-    for (const key of keys) {
+    for (const key of listState.selectionManager.selectedKeys) {
       const item = listState.collection().getItem(key);
       if (item) items.push(item);
     }
     return items;
   });
 
+  const canOpenMenu = () =>
+    listState.collection().size !== 0 || getProps().allowsEmptyCollection === true;
+
   return {
     realtimeValidation: validation.realtimeValidation,
     displayValidation: validation.displayValidation,
     updateValidation: validation.updateValidation,
     resetValidation: validation.resetValidation,
     commitValidation: validation.commitValidation,
-    // Collection
     collection: listState.collection,
     selectionManager: listState.selectionManager,
-
-    // Focus management
     focusedKey: listState.focusedKey,
     setFocusedKey: listState.setFocusedKey,
     isFocused,
     setFocused,
-
-    // Overlay state
     isOpen: overlayState.isOpen,
-    open: overlayState.open,
+    open(strategy: FocusStrategy | null = null) {
+      if (!canOpenMenu()) return;
+      setFocusStrategy(strategy);
+      overlayState.open();
+    },
     close: overlayState.close,
-    toggle: overlayState.toggle,
-
-    // Select-specific
+    toggle(strategy: FocusStrategy | null = null) {
+      if (!canOpenMenu()) return;
+      setFocusStrategy(strategy);
+      overlayState.toggle();
+    },
+    focusStrategy,
     selectionMode,
+    shouldCloseOnSelect,
+    value: () => displayValue() as SelectValueType<M>,
+    defaultValue: stateDefaultValue,
+    setValue,
     selectedKey,
+    defaultSelectedKey,
+    setSelectedKey: setValue,
     selectedKeys,
     selectedItem,
     selectedItems,
-    setSelectedKey,
     setSelectedKeys,
     isKeyDisabled: (key: Key) => listState.isDisabled(key),
     get isDisabled() {

package/src/select/index.ts

@@ -1 +1,8 @@
-export { createSelectState, type SelectStateProps, type SelectState } from "./createSelectState";
+export {
+  createSelectState,
+  type SelectStateProps,
+  type SelectState,
+  type SelectSelectionMode,
+  type SelectValueType,
+  type SelectChangeValueType,
+} from "./createSelectState";

package/src/selection/SelectionManager.ts

@@ -518,7 +518,9 @@ export class SelectionManager<T = unknown> {
     const item = this.collection.getItem(key);
     return (
       this.state.disabledBehavior === "all" &&
-      (this.state.disabledKeys.has(key) || !!item?.props?.isDisabled) &&
+      (this.state.disabledKeys.has(key) ||
+        !!item?.props?.isDisabled ||
+        item?.isDisabled === true) &&
       item?.props?.disabledBehavior !== "selection"
     );
   }

package/src/selection/createMultipleSelectionState.ts

@@ -25,7 +25,7 @@
 
 import { createMemo, createEffect } from "solid-js";
 import type { Accessor } from "solid-js";
-import { access, createInternalSignal, readNow, type MaybeAccessor } from "../utils";
+import { createInternalSignal, propsAccessor, readNow, type MaybeAccessor } from "../utils";
 import type { SelectionStateProps } from "../collections/createSelectionState";
 import type {
   DisabledBehavior,
@@ -114,7 +114,7 @@ function convertSelection(
 export function createMultipleSelectionState(
   props: MaybeAccessor<SelectionStateProps> = {},
 ): MultipleSelectionState {
-  const getProps = () => access(props);
+  const getProps = propsAccessor(props);
 
   // Focus is a plain signal in Solid; upstream needs a ref + state pair only
   // because React requires both a synchronous read and a re-render trigger.