@proyecto-viviana/solidaria 0.3.0 → 0.4.0

package/src/selection/createTypeSelect.ts

@@ -6,8 +6,10 @@
  * item text values. Supports multi-character search with debouncing.
  */
 
+import { onCleanup } from "solid-js";
 import type { JSX, Accessor } from "solid-js";
 import type { Key, Collection, CollectionNode } from "@proyecto-viviana/solid-stately";
+import { createCollator } from "../i18n/createCollator";
 
 /**
  * Controls how long to wait before clearing the typeahead buffer.
@@ -58,16 +60,17 @@ function getStringForKey(key: string): string {
 
 /**
  * Search for a key in the collection that matches the search string.
- * Starts searching from the key after `fromKey`, wrapping around if needed.
+ * Starts *at* `fromKey` (inclusive) and scans to the end, with no internal
+ * wrap; the caller retries from the top to cover earlier items. Matching is
+ * locale-aware via the supplied `collator`.
  */
 function getKeyForSearch<T>(
   collection: Collection<T>,
   search: string,
   fromKey: Key | null,
+  collator: Intl.Collator,
   isKeyDisabled?: (key: Key) => boolean,
 ): Key | null {
-  const searchLower = search.toLowerCase();
-
   // Collect all items in order
   const items: CollectionNode<T>[] = [];
   for (const item of collection) {
@@ -78,19 +81,21 @@ function getKeyForSearch<T>(
 
   if (items.length === 0) return null;
 
-  // Find the starting index
+  // Find the starting index. Start *at* the currently focused item (inclusive),
+  // mirroring upstream ListKeyboardDelegate.getKeyForSearch (`key = fromKey ||
+  // getFirstKey()`): typing a prefix the focused item already matches keeps focus
+  // on it instead of advancing to the next match.
   let startIndex = 0;
   if (fromKey != null) {
     const fromIndex = items.findIndex((item) => item.key === fromKey);
     if (fromIndex !== -1) {
-      // Start searching from the item AFTER the current one
-      startIndex = (fromIndex + 1) % items.length;
+      startIndex = fromIndex;
     }
   }
 
-  // Search from startIndex, wrapping around
-  for (let i = 0; i < items.length; i++) {
-    const index = (startIndex + i) % items.length;
+  // Scan from startIndex to the end (no wrap). The caller retries from the top to
+  // cover items before the focused one, matching upstream useTypeSelect.
+  for (let index = startIndex; index < items.length; index++) {
     const item = items[index];
 
     // Skip disabled items
@@ -98,9 +103,14 @@ function getKeyForSearch<T>(
       continue;
     }
 
-    // Check if the text value starts with the search string
+    // Match the leading characters of the text value against the search string
+    // using locale-aware collation, mirroring upstream ListKeyboardDelegate
+    // (`collator.compare(textValue.slice(0, search.length), search) === 0`). The
+    // collator's `usage: 'search'` / `sensitivity: 'base'` makes this case- and
+    // diacritic-insensitive in a locale-aware way.
     const textValue = item.textValue || "";
-    if (textValue.toLowerCase().startsWith(searchLower)) {
+    const substring = textValue.slice(0, search.length);
+    if (textValue && collator.compare(substring, search) === 0) {
       return item.key;
     }
   }
@@ -129,72 +139,123 @@ export function createTypeSelect<T>(options: TypeSelectOptions<T>): TypeSelectAr
     timeout: undefined,
   };
 
+  // Locale-aware search collator, mirroring upstream useSelectableList's
+  // `useCollator({ usage: 'search', sensitivity: 'base' })`.
+  const collator = createCollator({ usage: "search", sensitivity: "base" });
+
+  // Append the search buffer, find a matching key (from the focused item,
+  // falling back to the whole list), focus it, and (re)start the debounce timer.
+  // Shared by both phase handlers below, mirroring the duplicated body in
+  // upstream useTypeSelect.
+  const searchAndFocus = (): Key | null => {
+    const collection = options.collection();
+    const currentKey = options.focusedKey();
+
+    // Prioritize items at/after the focused item, then retry from the top to
+    // cover earlier ones (upstream's two getKeyForSearch calls).
+    let key = getKeyForSearch(
+      collection,
+      state.search,
+      currentKey,
+      collator(),
+      options.isKeyDisabled,
+    );
+    if (key == null) {
+      key = getKeyForSearch(collection, state.search, null, collator(), options.isKeyDisabled);
+    }
+
+    if (key != null) {
+      options.onFocusedKeyChange(key);
+      options.onTypeSelect?.(key);
+    }
+
+    return key;
+  };
+
+  const restartDebounce = () => {
+    clearTimeout(state.timeout);
+    state.timeout = setTimeout(() => {
+      state.search = "";
+    }, TYPEAHEAD_DEBOUNCE_WAIT_MS);
+  };
+
+  // Capture phase: mid-search a Spacebar is part of the query, not a selection
+  // action, so we consume it before the collection's own keydown handler can act
+  // on it. Mirrors upstream useTypeSelect's onKeyDownCapture.
   const onKeyDownCapture: JSX.EventHandler<HTMLElement, KeyboardEvent> = (e) => {
     if (options.isDisabled) return;
 
+    if (state.search.length > 0 && e.key === " ") {
+      e.preventDefault();
+      // Upstream guards this with `!('continuePropagation' in e) ||
+      // !e.isPropagationStopped()`. Our raw DOM KeyboardEvents never carry
+      // `continuePropagation`, so the guard always holds — stop unconditionally.
+      e.stopPropagation();
+      state.search += " ";
+      searchAndFocus();
+      restartDebounce();
+    }
+  };
+
+  // Bubble phase: handles ordinary characters (and, in environments where the
+  // capture listener above is inert, mid-search Spacebar via its non-bailing
+  // branch). Mirrors upstream useTypeSelect's onKeyDown.
+  const onKeyDown: JSX.EventHandler<HTMLElement, KeyboardEvent> = (e) => {
+    if (options.isDisabled) return;
+
     const character = getStringForKey(e.key);
 
-    // Ignore non-printable characters, modifier key combos,
-    // and events that didn't originate from within the element
+    // Ignore non-printable keys, Ctrl/Meta/Alt combos (Alt is excluded to match
+    // upstream — AltGr-only layouts shouldn't drive type-select), events from
+    // outside the element, and a leading Space (a common action key).
     if (
       !character ||
       e.ctrlKey ||
       e.metaKey ||
       e.altKey ||
-      !e.currentTarget.contains(e.target as HTMLElement)
+      !e.currentTarget.contains(e.target as HTMLElement) ||
+      (state.search.length === 0 && character === " ")
     ) {
       return;
     }
 
-    // Don't start search with space (common action key)
-    if (state.search.length === 0 && character === " ") {
-      return;
-    }
-
-    // If there's already search text and the user types a space,
-    // prevent it from triggering selection and include it in the search
-    if (character === " " && state.search.trim().length > 0) {
-      e.preventDefault();
-      e.stopPropagation();
-    }
-
-    // Append to the search buffer
     state.search += character;
 
-    // Find a matching key
-    const collection = options.collection();
-    const currentKey = options.focusedKey();
-
-    // First, try to find a match starting after the current key
-    let key = getKeyForSearch(collection, state.search, currentKey, options.isKeyDisabled);
-
-    // If no match found, try from the beginning
-    if (key == null && currentKey != null) {
-      key = getKeyForSearch(collection, state.search, null, options.isKeyDisabled);
-    }
+    const key = searchAndFocus();
 
     if (key != null) {
-      options.onFocusedKeyChange(key);
-      options.onTypeSelect?.(key);
-    }
-
-    // Reset the debounce timer
-    if (state.timeout !== undefined) {
+      e.preventDefault();
+      // Our raw DOM events never carry `continuePropagation`, so upstream's
+      // `if (!('continuePropagation' in e)) e.stopPropagation()` is unconditional.
+      e.stopPropagation();
+    } else {
+      // Nothing matched even after retrying from the top: type-to-select is done,
+      // so reset the buffer and let the key propagate normally.
+      state.search = "";
       clearTimeout(state.timeout);
+      state.timeout = undefined;
+      return;
     }
-    state.timeout = setTimeout(() => {
-      state.search = "";
-    }, TYPEAHEAD_DEBOUNCE_WAIT_MS);
+
+    restartDebounce();
   };
 
-  // Handler for bubble phase (used in test environments and as fallback)
-  const onKeyDown: JSX.EventHandler<HTMLElement, KeyboardEvent> = onKeyDownCapture;
+  // Mirror upstream's unmount cleanup (a useEffect teardown) so a pending
+  // debounce timer never fires after the consumer is disposed.
+  onCleanup(() => {
+    clearTimeout(state.timeout);
+  });
 
   return {
     typeSelectProps: {
-      // Use capture phase to handle spacebar before other handlers in production
+      // Upstream binds `onKeyDownCapture` so Spacebar is handled before the
+      // collection's own keydown handler. In Solid a capture handler delivered
+      // through a `{...typeSelectProps}` spread is inert (it never fires), so the
+      // bubble-phase `onKeyDown` is the live path — and it also covers mid-search
+      // Space because its bail check only rejects a *leading* Space. True capture
+      // would need a ref-based addEventListener threaded through every consumer;
+      // see the typeahead follow-up in upstream-sync.md.
       onKeyDownCapture,
-      // Also attach to bubble phase for test environments
       onKeyDown,
     } as JSX.HTMLAttributes<HTMLElement>,
   };

package/src/selection/index.ts

@@ -4,3 +4,34 @@
  */
 
 export { createTypeSelect, type TypeSelectOptions, type TypeSelectAria } from "./createTypeSelect";
+export {
+  createScrollIntoViewOnFocus,
+  type ScrollIntoViewOnFocusOptions,
+} from "./createScrollIntoViewOnFocus";
+export { selectItem } from "./selectItem";
+export {
+  createSelectableItem,
+  ITEM_ACTION_EVENT,
+  type CreateSelectableItemOptions,
+  type SelectableItemAria,
+  type LinkBehavior,
+} from "./createSelectableItem";
+export { isNonContiguousSelectionModifier, getItemElement } from "./utils";
+export { FOCUS_EVENT, CLEAR_FOCUS_EVENT } from "./constants";
+export {
+  ListKeyboardDelegate,
+  type ListKeyboardDelegateOptions,
+  type Orientation,
+  type Direction,
+} from "./ListKeyboardDelegate";
+export { DOMLayoutDelegate, type LayoutDelegate, type Rect, type Size } from "./DOMLayoutDelegate";
+export {
+  createSelectableCollection,
+  type CreateSelectableCollectionOptions,
+  type SelectableCollectionAria,
+} from "./createSelectableCollection";
+export {
+  createSelectableList,
+  type CreateSelectableListOptions,
+  type SelectableListAria,
+} from "./createSelectableList";

package/src/selection/selectItem.ts

@@ -0,0 +1,80 @@
+/**
+ * The aria-layer selection decision, mirroring `@react-aria/selection`'s
+ * `useSelectableItem` `onSelect`. This is where the platform-aware modifier
+ * resolution lives — react-stately's `SelectionManager.select` only knows
+ * `pointerType` + `selectionBehavior`; the ctrl/meta/shift decision belongs one
+ * layer up, here, where `isMac` is reachable.
+ *
+ * The link branch (`linkBehavior` 'selection'/'override'/'none') is deferred to
+ * `createSelectableItem` (Phase 1 of the press-path epic); callers here pass
+ * non-link items.
+ */
+
+import type { Accessor } from "solid-js";
+import type {
+  Collection,
+  Key,
+  SelectionBehavior,
+  SelectionMode,
+  SelectionPressEvent,
+} from "@proyecto-viviana/solid-stately";
+
+import { isCtrlKeyPressed } from "../utils/keyboard";
+import { isNonContiguousSelectionModifier } from "./utils";
+
+export interface SelectItemState {
+  readonly selectionMode: Accessor<SelectionMode>;
+  readonly selectionBehavior: Accessor<SelectionBehavior>;
+  readonly disallowEmptySelection: Accessor<boolean>;
+  isSelected(key: Key): boolean;
+  toggleSelection(key: Key): void;
+  replaceSelection(key: Key): void;
+  extendSelection(toKey: Key, collection: Collection): void;
+}
+
+/**
+ * Resolve a press/keyboard interaction into a selection mutation on `manager`,
+ * faithful to `useSelectableItem.onSelect`. `collection` is required for the
+ * shift-extend (contiguous range) path.
+ */
+export function selectItem(
+  manager: SelectItemState,
+  key: Key,
+  e: SelectionPressEvent,
+  collection: Collection,
+): void {
+  // A keyboard non-contiguous modifier (Alt on Apple devices, Ctrl elsewhere)
+  // always toggles, independent of mode/behavior.
+  if (e.pointerType === "keyboard" && isNonContiguousSelectionModifier(e)) {
+    manager.toggleSelection(key);
+    return;
+  }
+
+  if (manager.selectionMode() === "none") {
+    return;
+  }
+
+  if (manager.selectionMode() === "single") {
+    // Single mode ignores selectionBehavior. Re-selecting the current item
+    // deselects it when empty selection is allowed; otherwise it stays
+    // selected (replace).
+    if (manager.isSelected(key) && !manager.disallowEmptySelection()) {
+      manager.toggleSelection(key);
+    } else {
+      manager.replaceSelection(key);
+    }
+  } else if (e.shiftKey) {
+    manager.extendSelection(key, collection);
+  } else if (
+    manager.selectionBehavior() === "toggle" ||
+    isCtrlKeyPressed(e) ||
+    e.pointerType === "touch" ||
+    e.pointerType === "virtual"
+  ) {
+    // touch / virtual (VoiceOver) have no modifier keys, so multi-select is
+    // only reachable by toggling.
+    manager.toggleSelection(key);
+  } else {
+    manager.replaceSelection(key);
+  }
+}

package/src/selection/utils.ts

@@ -0,0 +1,82 @@
+/**
+ * Selection helpers shared across collection item hooks.
+ * Based on @react-aria/selection's utilities.
+ */
+
+import type { Accessor } from "solid-js";
+import type { Key } from "@proyecto-viviana/solid-stately";
+import { isAppleDevice } from "../utils/platform";
+import { createId } from "../ssr";
+
+/**
+ * Resolves the DOM element rendered for a collection item by its key, scoped to
+ * the owning collection when a `data-collection` id is present. Mirrors
+ * `@react-aria/selection`'s `getItemElement`, adapted to take a Solid ref
+ * accessor instead of a React ref object.
+ */
+export function getItemElement(ref: Accessor<HTMLElement | null>, key: Key): HTMLElement | null {
+  const root = ref();
+  if (!root) {
+    return null;
+  }
+  let selector = `[data-key="${CSS.escape(String(key))}"]`;
+  const collectionId = root.dataset.collection;
+  if (collectionId) {
+    selector = `[data-collection="${CSS.escape(collectionId)}"]${selector}`;
+  }
+  return root.querySelector<HTMLElement>(selector);
+}
+
+/**
+ * A stable, SSR-safe id for a collection, shared between the collection
+ * container and its items so {@link getItemElement} can scope a query by
+ * `data-collection` (needed to disambiguate nested collections).
+ *
+ * Divergence from upstream: React's `useCollectionId` keys this WeakMap by the
+ * collection object and relies on a render-stable `useId`. A Solid collection is
+ * rebuilt with a new identity whenever its items change, so we key by the
+ * SelectionManager instance instead — it is created once and never replaced, so
+ * the container and its items always resolve to the same entry — and generate
+ * the id with our SSR-safe `createId`.
+ */
+const collectionIdMap = new WeakMap<object, string>();
+
+/**
+ * Registers (on first call) and returns the collection id for a SelectionManager.
+ * The collection container calls this; its items read the same id via
+ * {@link getCollectionId}. Must be called within a reactive owner (uses createId).
+ */
+export function registerCollectionId(manager: object): string {
+  let id = collectionIdMap.get(manager);
+  if (id == null) {
+    id = createId();
+    collectionIdMap.set(manager, id);
+  }
+  return id;
+}
+
+/**
+ * Returns the collection id registered for a SelectionManager, or `undefined`
+ * when its container has not registered one (e.g. an item not yet wired into a
+ * `createSelectableCollection`). A Solid `undefined` attribute is omitted, so an
+ * unregistered item simply renders no `data-collection`.
+ */
+export function getCollectionId(manager: object): string | undefined {
+  return collectionIdMap.get(manager);
+}
+
+/** The modifier-key fields consulted by {@link isNonContiguousSelectionModifier}. */
+interface ModifierKeyEvent {
+  altKey?: boolean;
+  ctrlKey?: boolean;
+}
+
+/**
+ * Returns whether the modifier for non-contiguous (toggle) keyboard selection
+ * is pressed. Mirrors `@react-aria/selection`'s `isNonContiguousSelectionModifier`:
+ * Ctrl + Arrow Up/Down has a system-wide meaning on macOS, so Apple devices use
+ * Alt instead; Windows and Ubuntu use Ctrl.
+ */
+export function isNonContiguousSelectionModifier(e: ModifierKeyEvent): boolean {
+  return isAppleDevice() ? e.altKey === true : e.ctrlKey === true;
+}

package/src/slider/createSlider.ts

@@ -11,6 +11,7 @@ import { filterDOMProps } from "../utils/filterDOMProps";
 import { focusWithoutScrolling } from "../utils/focus";
 import { mergeProps } from "../utils/mergeProps";
 import { createId } from "../ssr";
+import { useLocale } from "../i18n";
 import { access, type MaybeAccessor } from "../utils/reactivity";
 import type { SliderState, SliderOrientation } from "@proyecto-viviana/solid-stately";
 
@@ -61,6 +62,7 @@ export function createSlider(
 ): SliderAria {
   const getProps = () => access(props);
   const id = createId(getProps().id);
+  const locale = useLocale();
 
   // Generate IDs for associated elements
   const inputId = `${id}-input`;
@@ -158,6 +160,38 @@ export function createSlider(
     if (state.isDisabled) return;
 
     switch (e.key) {
+      case "ArrowRight":
+        e.preventDefault();
+        if (state.orientation === "horizontal" && locale().direction === "rtl") {
+          state.decrement();
+        } else {
+          state.increment();
+        }
+        break;
+      case "ArrowLeft":
+        e.preventDefault();
+        if (state.orientation === "horizontal" && locale().direction === "rtl") {
+          state.increment();
+        } else {
+          state.decrement();
+        }
+        break;
+      case "ArrowUp":
+        e.preventDefault();
+        if (state.orientation === "vertical") {
+          state.increment();
+        } else {
+          state.decrement();
+        }
+        break;
+      case "ArrowDown":
+        e.preventDefault();
+        if (state.orientation === "vertical") {
+          state.decrement();
+        } else {
+          state.increment();
+        }
+        break;
       case "PageUp":
         e.preventDefault();
         state.increment(state.pageStep / state.step);
@@ -277,8 +311,20 @@ export function createSlider(
       const isVertical = state.orientation === "vertical";
 
       return {
+        role: "slider",
+        "aria-valuemin": state.minValue,
+        "aria-valuemax": state.maxValue,
+        "aria-valuenow": state.value(),
+        "aria-valuetext": state.getFormattedValue(),
+        "aria-orientation": state.orientation,
+        "aria-disabled": state.isDisabled || undefined,
+        "aria-labelledby": labelledBy(),
+        "aria-label": labelledBy() ? undefined : ariaLabel(),
+        tabIndex: state.isDisabled ? undefined : 0,
         onPointerDown: onThumbPointerDown,
         onKeyDown: onThumbKeyDown,
+        onFocus,
+        onBlur,
         style: {
           position: "absolute",
           [isVertical ? "bottom" : "left"]: `${percent * 100}%`,
@@ -297,6 +343,7 @@ export function createSlider(
         {
           type: "range",
           id: inputId,
+          "aria-hidden": true,
           min: state.minValue,
           max: state.maxValue,
           step: state.step,
@@ -308,7 +355,7 @@ export function createSlider(
           "aria-valuetext": state.getFormattedValue(),
           "aria-labelledby": labelledBy(),
           "aria-label": labelledBy() ? undefined : ariaLabel(),
-          tabIndex: state.isDisabled ? undefined : 0,
+          tabIndex: -1,
           onInput: (e: Event) => {
             const target = e.target as HTMLInputElement;
             state.setValue(parseFloat(target.value));

package/src/ssr/index.tsx

@@ -80,6 +80,37 @@ export function createId(defaultId?: string): string {
   return ctx.prefix ? `solidaria-${ctx.prefix}-${uniqueId}` : `solidaria-${uniqueId}`;
 }
 
+/**
+ * Generates an id, but only resolves to it once an element with that id is
+ * actually present in the DOM. Returns `undefined` otherwise.
+ *
+ * This is a 1:1 port of @react-aria/utils's `useSlotId`. It exists so that an
+ * `aria-labelledby` can point at an optional slot (e.g. a section header) and
+ * automatically fall back to `undefined` when the slot is not rendered, instead
+ * of leaving a dangling reference to a non-existent id.
+ *
+ * The initial value is the generated id so that server and first client render
+ * agree (no hydration mismatch); a client-only effect then probes the DOM and
+ * clears the value when no matching element exists.
+ *
+ * @param deps - Accessors re-probed when their values change (mirrors the
+ *   dependency array of the upstream hook).
+ */
+export function createSlotId(deps: Array<Accessor<unknown>> = []): Accessor<string | undefined> {
+  const id = createId();
+  const [resolvedId, setResolvedId] = createSignal<string | undefined>(id);
+
+  createEffect(() => {
+    // Re-probe when any explicit dependency changes.
+    for (const dep of deps) {
+      dep();
+    }
+    setResolvedId(document.getElementById(id) ? id : undefined);
+  });
+
+  return resolvedId;
+}
+
 /**
  * Provides SSR context to the component tree.
  *

package/src/switch/createSwitch.ts

@@ -21,6 +21,10 @@ export interface SwitchAria {
   labelProps: JSX.LabelHTMLAttributes<HTMLLabelElement>;
   /** Props for the input element. */
   inputProps: JSX.InputHTMLAttributes<HTMLInputElement>;
+  /** Props for the switch description element, if any. */
+  descriptionProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the switch error message element, if any. */
+  errorMessageProps: JSX.HTMLAttributes<HTMLElement>;
   /** Whether the switch is selected. */
   isSelected: Accessor<boolean>;
   /** Whether the switch is in a pressed state. */
@@ -56,6 +60,12 @@ export function createSwitch(
         checked: toggle.isSelected(),
       };
     },
+    get descriptionProps() {
+      return toggle.descriptionProps;
+    },
+    get errorMessageProps() {
+      return toggle.errorMessageProps;
+    },
     isSelected: toggle.isSelected,
     isPressed: toggle.isPressed,
     isDisabled: toggle.isDisabled,