@proyecto-viviana/solidaria 0.2.8 → 0.4.0

package/src/selection/createTypeSelect.ts

@@ -6,8 +6,10 @@
  * item text values. Supports multi-character search with debouncing.
  */
 
-import type { JSX, Accessor } from 'solid-js';
-import type { Key, Collection, CollectionNode } from '@proyecto-viviana/solid-stately';
+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.
@@ -53,44 +55,47 @@ function getStringForKey(key: string): string {
   if (key.length === 1 || !/^[A-Z]/i.test(key)) {
     return key;
   }
-  return '';
+  return "";
 }
 
 /**
  * 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,
-  isKeyDisabled?: (key: Key) => boolean
+  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) {
-    if (item.type === 'item') {
+    if (item.type === "item") {
       items.push(item);
     }
   }
 
   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);
+    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
-    const textValue = item.textValue || '';
-    if (textValue.toLowerCase().startsWith(searchLower)) {
+    // 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 || "";
+    const substring = textValue.slice(0, search.length);
+    if (textValue && collator.compare(substring, search) === 0) {
       return item.key;
     }
   }
@@ -125,76 +135,127 @@ function getKeyForSearch<T>(
 export function createTypeSelect<T>(options: TypeSelectOptions<T>): TypeSelectAria {
   // Create mutable state object to persist across keystrokes
   const state: TypeSelectState = {
-    search: '',
+    search: "",
     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

@@ -3,4 +3,35 @@
  * in collection components.
  */
 
-export { createTypeSelect, type TypeSelectOptions, type TypeSelectAria } from './createTypeSelect';
+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/separator/createSeparator.ts

@@ -5,15 +5,11 @@
  * e.g. groups of menu items or sections of a page.
  */
 
-import type { JSX } from 'solid-js';
-import { access, type MaybeAccessor } from '../utils';
-import { filterDOMProps } from '../utils';
+import type { JSX } from "solid-js";
+import { access, type MaybeAccessor } from "../utils";
+import { filterDOMProps } from "../utils";
 
-// ============================================
-// TYPES
-// ============================================
-
-export type Orientation = 'horizontal' | 'vertical';
+export type Orientation = "horizontal" | "vertical";
 
 export interface AriaSeparatorProps {
   /**
@@ -27,9 +23,13 @@ export interface AriaSeparatorProps {
    */
   elementType?: string;
   /** An accessibility label for the separator. */
-  'aria-label'?: string;
+  "aria-label"?: string;
   /** Identifies the element(s) that labels the separator. */
-  'aria-labelledby'?: string;
+  "aria-labelledby"?: string;
+  /** Identifies the element(s) that describes the separator. */
+  "aria-describedby"?: string;
+  /** Identifies the element(s) that provide a detailed description. */
+  "aria-details"?: string;
   /** The element's unique identifier. */
   id?: string;
 }
@@ -39,39 +39,34 @@ export interface SeparatorAria {
   separatorProps: JSX.HTMLAttributes<HTMLElement>;
 }
 
-// ============================================
-// CREATE SEPARATOR
-// ============================================
-
 /**
  * Provides the accessibility implementation for a separator.
  * A separator is a visual divider between two groups of content,
  * e.g. groups of menu items or sections of a page.
  */
-export function createSeparator(
-  props: MaybeAccessor<AriaSeparatorProps> = {}
-): SeparatorAria {
+export function createSeparator(props: MaybeAccessor<AriaSeparatorProps> = {}): SeparatorAria {
   const getSeparatorProps = (): JSX.HTMLAttributes<HTMLElement> => {
     const p = access(props);
     const domProps = filterDOMProps(p as Record<string, unknown>, { labelable: true });
 
     // if orientation is horizontal, aria-orientation default is horizontal, so we leave it undefined
     // if it's vertical, we need to specify it
-    let ariaOrientation: 'vertical' | undefined;
-    if (p.orientation === 'vertical') {
-      ariaOrientation = 'vertical';
+    let ariaOrientation: "vertical" | undefined;
+    if (p.orientation === "vertical") {
+      ariaOrientation = "vertical";
     }
 
-    // hr elements implicitly have role = separator and a horizontal orientation
-    if (p.elementType !== 'hr') {
+    if (p.elementType !== "hr") {
       return {
         ...domProps,
-        role: 'separator',
-        'aria-orientation': ariaOrientation,
+        role: "separator",
+        "aria-orientation": ariaOrientation,
       };
     }
 
-    return domProps;
+    return {
+      ...domProps,
+    };
   };
 
   return {

package/src/separator/index.ts

@@ -3,4 +3,4 @@ export {
   type AriaSeparatorProps,
   type SeparatorAria,
   type Orientation,
-} from './createSeparator';
+} from "./createSeparator";