@proyecto-viviana/solidaria 0.2.2 → 0.2.3

package/src/select/createSelect.ts

@@ -0,0 +1,395 @@
+/**
+ * Provides the behavior and accessibility implementation for a select component.
+ * A select displays a collapsible list of options and allows a user to select one of them.
+ * Based on @react-aria/select useSelect.
+ */
+
+import { type JSX, type Accessor, createEffect, onCleanup } from 'solid-js';
+import { createPress } from '../interactions/createPress';
+import { createFocusRing } from '../interactions/createFocusRing';
+import { createLabel } from '../label/createLabel';
+import { createTypeSelect } from '../selection/createTypeSelect';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { mergeProps } from '../utils/mergeProps';
+import { createId } from '../ssr';
+import { access, type MaybeAccessor } from '../utils/reactivity';
+import type { SelectState, CollectionNode } from '@proyecto-viviana/solid-stately';
+
+export interface AriaSelectProps {
+  /** An ID for the select. */
+  id?: string;
+  /** Whether the select is disabled. */
+  isDisabled?: boolean;
+  /** Whether the select is required. */
+  isRequired?: boolean;
+  /** The label for the select. */
+  label?: JSX.Element;
+  /** An accessible label for the select when no visible label is provided. */
+  'aria-label'?: string;
+  /** The ID of an element that labels the select. */
+  'aria-labelledby'?: string;
+  /** The ID of an element that describes the select. */
+  'aria-describedby'?: string;
+  /** Placeholder text when no option is selected. */
+  placeholder?: string;
+  /** Whether the select should be auto-focused. */
+  autoFocus?: boolean;
+  /** Handler called when focus moves to the select. */
+  onFocus?: (e: FocusEvent) => void;
+  /** Handler called when focus moves away from the select. */
+  onBlur?: (e: FocusEvent) => void;
+  /** Handler called when the focus state changes. */
+  onFocusChange?: (isFocused: boolean) => void;
+  /** The name of the select, used when submitting an HTML form. */
+  name?: string;
+  /** Whether type-to-select is disabled. @default false */
+  disallowTypeAhead?: boolean;
+}
+
+export interface SelectAria<T> {
+  /** Props for the label element. */
+  labelProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the trigger button element. */
+  triggerProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the value display element. */
+  valueProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the listbox/menu popup. */
+  menuProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the description element, if any. */
+  descriptionProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the error message element, if any. */
+  errorMessageProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Whether the select is currently focused. */
+  isFocused: Accessor<boolean>;
+  /** Whether the select has keyboard focus. */
+  isFocusVisible: Accessor<boolean>;
+  /** Whether the select is currently open. */
+  isOpen: Accessor<boolean>;
+  /** The currently selected item. */
+  selectedItem: Accessor<CollectionNode<T> | null>;
+}
+
+// Shared data between select and options
+const selectData = new WeakMap<object, SelectData>();
+
+interface SelectData {
+  id: string;
+}
+
+export function getSelectData(state: SelectState): SelectData | undefined {
+  return selectData.get(state);
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a select component.
+ */
+export function createSelect<T>(
+  props: MaybeAccessor<AriaSelectProps>,
+  state: SelectState<T>,
+  _ref?: () => HTMLElement | null
+): SelectAria<T> {
+  const getProps = () => access(props);
+  const id = createId(getProps().id);
+
+  // Generate IDs for associated elements
+  const buttonId = `${id}-button`;
+  const listBoxId = `${id}-listbox`;
+  const valueId = `${id}-value`;
+  const descriptionId = `${id}-description`;
+  const errorMessageId = `${id}-error`;
+
+  // Filter DOM props
+  const domProps = () =>
+    filterDOMProps(getProps() as unknown as Record<string, unknown>, { labelable: true });
+
+  // Share data with child options
+  createEffect(() => {
+    selectData.set(state, { id });
+
+    onCleanup(() => {
+      selectData.delete(state);
+    });
+  });
+
+  // Label handling
+  const { labelProps, fieldProps } = createLabel({
+    get id() {
+      return buttonId;
+    },
+    get label() {
+      return getProps().label;
+    },
+    get 'aria-label'() {
+      return getProps()['aria-label'];
+    },
+    get 'aria-labelledby'() {
+      return getProps()['aria-labelledby'];
+    },
+    labelElementType: 'span',
+  });
+
+  // Focus ring for keyboard focus styling
+  const { isFocusVisible, focusProps } = createFocusRing({
+    get autoFocus() {
+      return getProps().autoFocus;
+    },
+  });
+
+  // Track focus state
+  const isFocused = state.isFocused;
+
+  // Handle press on trigger
+  const { pressProps } = createPress({
+    get isDisabled() {
+      return getProps().isDisabled ?? state.isDisabled;
+    },
+    onPress() {
+      state.toggle();
+    },
+  });
+
+  // Helper to find next non-disabled key
+  const findNextKey = (fromKey: string | number | null, direction: 'forward' | 'backward'): string | number | null => {
+    const collection = state.collection();
+    let key = fromKey;
+
+    if (key == null) {
+      return direction === 'forward' ? collection.getFirstKey() : collection.getLastKey();
+    }
+
+    const getNext = direction === 'forward'
+      ? (k: string | number) => collection.getKeyAfter(k)
+      : (k: string | number) => collection.getKeyBefore(k);
+
+    let next = getNext(key);
+    while (next != null) {
+      // Check if item is disabled via state.isKeyDisabled or item.isDisabled
+      const isDisabled = state.isKeyDisabled?.(next) || collection.getItem(next)?.isDisabled;
+      if (!isDisabled) {
+        return next;
+      }
+      next = getNext(next);
+    }
+
+    return null;
+  };
+
+  // Helper to check if key is disabled
+  const isKeyDisabled = (key: string | number): boolean => {
+    const collection = state.collection();
+    return state.isKeyDisabled?.(key) || collection.getItem(key)?.isDisabled || false;
+  };
+
+  // Type-to-select - for Select, typing directly selects items when closed
+  const { typeSelectProps } = createTypeSelect({
+    collection: () => state.collection(),
+    focusedKey: () => state.selectedKey(), // Use selectedKey as the "focused" key for closed Select
+    onFocusedKeyChange: (key) => {
+      // When closed, type-to-select directly changes selection
+      if (!state.isOpen()) {
+        state.setSelectedKey(key);
+      } else {
+        // When open, update focused key (listbox handles selection)
+        state.setFocusedKey(key);
+      }
+    },
+    isKeyDisabled,
+    get isDisabled() {
+      return getProps().disallowTypeAhead ?? false;
+    },
+  });
+
+  // Keyboard navigation
+  const onKeyDown: JSX.EventHandler<HTMLElement, KeyboardEvent> = (e) => {
+    if (getProps().isDisabled) return;
+
+    const collection = state.collection();
+    const currentKey = state.selectedKey();
+
+    switch (e.key) {
+      case 'Enter':
+      case ' ':
+        e.preventDefault();
+        state.toggle();
+        break;
+
+      case 'ArrowDown':
+        e.preventDefault();
+        if (!state.isOpen()) {
+          // ArrowDown: Open the dropdown and focus first/selected item
+          state.open();
+          const focusKey = currentKey ?? collection.getFirstKey();
+          if (focusKey) {
+            state.setFocusedKey(focusKey);
+          }
+        }
+        // When open, navigation is handled by the listbox
+        break;
+
+      case 'ArrowUp':
+        e.preventDefault();
+        if (!state.isOpen()) {
+          // ArrowUp: Open the dropdown and focus last/selected item
+          state.open();
+          const focusKey = currentKey ?? collection.getLastKey();
+          if (focusKey) {
+            state.setFocusedKey(focusKey);
+          }
+        }
+        // When open, navigation is handled by the listbox
+        break;
+
+      case 'ArrowRight':
+        // ArrowRight: Select next option (for horizontal keyboard navigation pattern)
+        if (!state.isOpen()) {
+          e.preventDefault();
+          const nextKey = findNextKey(currentKey, 'forward');
+          if (nextKey != null) {
+            state.setSelectedKey(nextKey);
+          }
+        }
+        break;
+
+      case 'ArrowLeft':
+        // ArrowLeft: Select previous option (for horizontal keyboard navigation pattern)
+        if (!state.isOpen()) {
+          e.preventDefault();
+          const prevKey = findNextKey(currentKey, 'backward');
+          if (prevKey != null) {
+            state.setSelectedKey(prevKey);
+          }
+        }
+        break;
+
+      case 'Home':
+        // Home: Select first option
+        if (!state.isOpen()) {
+          e.preventDefault();
+          const firstKey = collection.getFirstKey();
+          if (firstKey != null) {
+            // Find first non-disabled key
+            const item = collection.getItem(firstKey);
+            if (item && !item.isDisabled) {
+              state.setSelectedKey(firstKey);
+            } else {
+              const nextKey = findNextKey(firstKey, 'forward');
+              if (nextKey != null) {
+                state.setSelectedKey(nextKey);
+              }
+            }
+          }
+        }
+        break;
+
+      case 'End':
+        // End: Select last option
+        if (!state.isOpen()) {
+          e.preventDefault();
+          const lastKey = collection.getLastKey();
+          if (lastKey != null) {
+            // Find last non-disabled key
+            const item = collection.getItem(lastKey);
+            if (item && !item.isDisabled) {
+              state.setSelectedKey(lastKey);
+            } else {
+              const prevKey = findNextKey(lastKey, 'backward');
+              if (prevKey != null) {
+                state.setSelectedKey(prevKey);
+              }
+            }
+          }
+        }
+        break;
+
+      case 'Escape':
+        if (state.isOpen()) {
+          e.preventDefault();
+          state.close();
+        }
+        break;
+    }
+  };
+
+  // Handle focus events
+  const handleFocus = (e: FocusEvent) => {
+    state.setFocused(true);
+    getProps().onFocus?.(e);
+    getProps().onFocusChange?.(true);
+  };
+
+  const handleBlur = (e: FocusEvent) => {
+    state.setFocused(false);
+    getProps().onBlur?.(e);
+    getProps().onFocusChange?.(false);
+  };
+
+  return {
+    get labelProps() {
+      return labelProps as JSX.HTMLAttributes<HTMLElement>;
+    },
+    get triggerProps() {
+      const p = getProps();
+      const isOpen = state.isOpen();
+      const isDisabled = p.isDisabled ?? state.isDisabled;
+
+      const baseProps = mergeProps(
+        domProps(),
+        pressProps as Record<string, unknown>,
+        focusProps as Record<string, unknown>,
+        fieldProps as Record<string, unknown>,
+        {
+          id: buttonId,
+          role: 'combobox',
+          type: 'button',
+          tabIndex: isDisabled ? undefined : 0,
+          'aria-haspopup': 'listbox',
+          'aria-expanded': isOpen,
+          'aria-controls': isOpen ? listBoxId : undefined,
+          'aria-disabled': isDisabled || undefined,
+          'aria-required': p.isRequired || undefined,
+          'aria-describedby': p['aria-describedby'] || undefined,
+          onKeyDown,
+          onFocus: handleFocus,
+          onBlur: handleBlur,
+          'data-open': isOpen || undefined,
+          'data-disabled': isDisabled || undefined,
+          'data-focus-visible': isFocusVisible() || undefined,
+        } as Record<string, unknown>
+      );
+
+      // Add type-select props if enabled
+      if (!p.disallowTypeAhead) {
+        return mergeProps(baseProps, typeSelectProps as Record<string, unknown>) as JSX.HTMLAttributes<HTMLElement>;
+      }
+
+      return baseProps as JSX.HTMLAttributes<HTMLElement>;
+    },
+    get valueProps() {
+      return {
+        id: valueId,
+      } as JSX.HTMLAttributes<HTMLElement>;
+    },
+    get menuProps() {
+      return {
+        id: listBoxId,
+        role: 'listbox',
+        'aria-labelledby': buttonId,
+        tabIndex: -1,
+      } as JSX.HTMLAttributes<HTMLElement>;
+    },
+    get descriptionProps() {
+      return {
+        id: descriptionId,
+      } as JSX.HTMLAttributes<HTMLElement>;
+    },
+    get errorMessageProps() {
+      return {
+        id: errorMessageId,
+      } as JSX.HTMLAttributes<HTMLElement>;
+    },
+    isFocused,
+    isFocusVisible: () => isFocused() && isFocusVisible(),
+    isOpen: state.isOpen,
+    selectedItem: state.selectedItem,
+  };
+}

package/src/select/index.ts

@@ -0,0 +1,14 @@
+export {
+  createSelect,
+  getSelectData,
+  type AriaSelectProps,
+  type SelectAria,
+} from './createSelect';
+
+export {
+  createHiddenSelect,
+  HiddenSelect,
+  type AriaHiddenSelectProps,
+  type HiddenSelectAria,
+  type HiddenSelectProps,
+} from './createHiddenSelect.jsx';

package/src/selection/createTypeSelect.ts

@@ -0,0 +1,201 @@
+/**
+ * createTypeSelect - Handles typeahead interactions with collections.
+ * Based on @react-aria/selection useTypeSelect.
+ *
+ * Allows users to navigate to items by typing characters that match
+ * 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';
+
+/**
+ * Controls how long to wait before clearing the typeahead buffer.
+ */
+const TYPEAHEAD_DEBOUNCE_WAIT_MS = 1000; // 1 second
+
+export interface TypeSelectOptions<T> {
+  /** The collection to search through. */
+  collection: Accessor<Collection<T>>;
+  /** The currently focused key. */
+  focusedKey: Accessor<Key | null>;
+  /** Callback to set the focused key when a match is found. */
+  onFocusedKeyChange: (key: Key) => void;
+  /** Callback when an item is focused by typing. */
+  onTypeSelect?: (key: Key) => void;
+  /** Function to check if a key is disabled. */
+  isKeyDisabled?: (key: Key) => boolean;
+  /** Whether type-to-select is disabled. */
+  isDisabled?: boolean;
+}
+
+export interface TypeSelectAria {
+  /** Props to spread on the collection element. */
+  typeSelectProps: JSX.HTMLAttributes<HTMLElement>;
+}
+
+// Internal state for tracking the search buffer
+interface TypeSelectState {
+  search: string;
+  timeout: ReturnType<typeof setTimeout> | undefined;
+}
+
+/**
+ * Get a printable character from a key event.
+ * Returns the character if it's a single printable character,
+ * or empty string for non-printable keys.
+ */
+function getStringForKey(key: string): string {
+  // If the key is of length 1, it is an ASCII value.
+  // Otherwise, if there are no ASCII characters in the key name,
+  // it is a Unicode character.
+  // See https://www.w3.org/TR/uievents-key/
+  if (key.length === 1 || !/^[A-Z]/i.test(key)) {
+    return key;
+  }
+  return '';
+}
+
+/**
+ * Search for a key in the collection that matches the search string.
+ * Starts searching from the key after `fromKey`, wrapping around if needed.
+ */
+function getKeyForSearch<T>(
+  collection: Collection<T>,
+  search: string,
+  fromKey: Key | null,
+  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') {
+      items.push(item);
+    }
+  }
+
+  if (items.length === 0) return null;
+
+  // Find the starting index
+  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;
+    }
+  }
+
+  // Search from startIndex, wrapping around
+  for (let i = 0; i < items.length; i++) {
+    const index = (startIndex + i) % items.length;
+    const item = items[index];
+
+    // Skip disabled items
+    if (item.isDisabled || (isKeyDisabled && isKeyDisabled(item.key))) {
+      continue;
+    }
+
+    // Check if the text value starts with the search string
+    const textValue = item.textValue || '';
+    if (textValue.toLowerCase().startsWith(searchLower)) {
+      return item.key;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Creates typeahead/type-to-select functionality for a collection.
+ *
+ * @example
+ * ```tsx
+ * const { typeSelectProps } = createTypeSelect({
+ *   collection: () => state.collection(),
+ *   focusedKey: () => state.focusedKey(),
+ *   onFocusedKeyChange: (key) => state.setFocusedKey(key),
+ * });
+ *
+ * return <ul {...mergeProps(listBoxProps, typeSelectProps)}>...</ul>;
+ * ```
+ */
+export function createTypeSelect<T>(options: TypeSelectOptions<T>): TypeSelectAria {
+  // Create mutable state object to persist across keystrokes
+  const state: TypeSelectState = {
+    search: '',
+    timeout: undefined,
+  };
+
+  const onKeyDownCapture: 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
+    if (
+      !character ||
+      e.ctrlKey ||
+      e.metaKey ||
+      e.altKey ||
+      !e.currentTarget.contains(e.target as HTMLElement)
+    ) {
+      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);
+    }
+
+    if (key != null) {
+      options.onFocusedKeyChange(key);
+      options.onTypeSelect?.(key);
+    }
+
+    // Reset the debounce timer
+    if (state.timeout !== undefined) {
+      clearTimeout(state.timeout);
+    }
+    state.timeout = setTimeout(() => {
+      state.search = '';
+    }, TYPEAHEAD_DEBOUNCE_WAIT_MS);
+  };
+
+  // Handler for bubble phase (used in test environments and as fallback)
+  const onKeyDown: JSX.EventHandler<HTMLElement, KeyboardEvent> = onKeyDownCapture;
+
+  return {
+    typeSelectProps: {
+      // Use capture phase to handle spacebar before other handlers in production
+      onKeyDownCapture,
+      // Also attach to bubble phase for test environments
+      onKeyDown,
+    } as JSX.HTMLAttributes<HTMLElement>,
+  };
+}

package/src/selection/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Selection utilities for managing typeahead and keyboard navigation
+ * in collection components.
+ */
+
+export { createTypeSelect, type TypeSelectOptions, type TypeSelectAria } from './createTypeSelect';

package/src/separator/createSeparator.ts

@@ -0,0 +1,82 @@
+/**
+ * createSeparator - SolidJS implementation of React Aria's useSeparator
+ *
+ * A separator is a visual divider between two groups of content,
+ * 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';
+
+// ============================================
+// TYPES
+// ============================================
+
+export type Orientation = 'horizontal' | 'vertical';
+
+export interface AriaSeparatorProps {
+  /**
+   * The orientation of the separator.
+   * @default 'horizontal'
+   */
+  orientation?: Orientation;
+  /**
+   * The HTML element type that will be used to render the separator.
+   * @default 'hr'
+   */
+  elementType?: string;
+  /** An accessibility label for the separator. */
+  'aria-label'?: string;
+  /** Identifies the element(s) that labels the separator. */
+  'aria-labelledby'?: string;
+  /** The element's unique identifier. */
+  id?: string;
+}
+
+export interface SeparatorAria {
+  /** Props for the separator element. */
+  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 {
+  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';
+    }
+
+    // hr elements implicitly have role = separator and a horizontal orientation
+    if (p.elementType !== 'hr') {
+      return {
+        ...domProps,
+        role: 'separator',
+        'aria-orientation': ariaOrientation,
+      };
+    }
+
+    return domProps;
+  };
+
+  return {
+    get separatorProps() {
+      return getSeparatorProps();
+    },
+  };
+}

package/src/separator/index.ts

@@ -0,0 +1,6 @@
+export {
+  createSeparator,
+  type AriaSeparatorProps,
+  type SeparatorAria,
+  type Orientation,
+} from './createSeparator';