@proyecto-viviana/solidaria 0.2.8 → 0.4.0

package/src/autocomplete/createAutocomplete.ts

@@ -7,91 +7,84 @@
  * Based on @react-aria/autocomplete useAutocomplete.
  */
 
-import {
-  createSignal,
-  createEffect,
-  onCleanup,
-  type Accessor,
-} from 'solid-js'
-import { createId, getOwnerDocument } from '../ssr'
-import { type AutocompleteState } from '@proyecto-viviana/solid-stately'
-
-// ============================================
-// TYPES
-// ============================================
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+import { createId, getOwnerDocument } from "../ssr";
+import { type AutocompleteState } from "@proyecto-viviana/solid-stately";
 
 export interface CollectionOptions {
   /** The id of the collection element. */
-  id?: string
+  id?: string;
   /** Accessible label for the collection. */
-  'aria-label'?: string
+  "aria-label"?: string;
   /** Whether the collection items should use virtual focus instead of being focused directly. */
-  shouldUseVirtualFocus: boolean
+  shouldUseVirtualFocus: boolean;
   /** Whether typeahead is disabled. */
-  disallowTypeAhead: boolean
+  disallowTypeAhead: boolean;
+  /** Whether and where to focus an item when the collection mounts. */
+  autoFocus?: boolean | "first" | "last";
 }
 
 export interface AutocompleteInputProps {
   /** Current input value. */
-  value: Accessor<string>
+  value: Accessor<string>;
   /** Handler for input value changes. */
-  onChange: (value: string) => void
+  onChange: (value: string) => void;
   /** Handler for key events. */
-  onKeyDown: (e: KeyboardEvent) => void
+  onKeyDown: (e: KeyboardEvent) => void;
   /** Handler for focus events. */
-  onFocus: (e: FocusEvent) => void
+  onFocus: (e: FocusEvent) => void;
   /** Handler for blur events. */
-  onBlur: (e: FocusEvent) => void
+  onBlur: (e: FocusEvent) => void;
   /** The id of the currently focused item for aria-activedescendant. */
-  'aria-activedescendant': Accessor<string | undefined>
+  "aria-activedescendant": Accessor<string | undefined>;
   /** The id of the controlled collection. */
-  'aria-controls': string
+  "aria-controls": string;
   /** Autocomplete type. */
-  'aria-autocomplete': 'list' | 'none' | 'inline' | 'both'
+  "aria-autocomplete": "list" | "none" | "inline" | "both";
   /** Enter key hint for mobile keyboards. */
-  enterKeyHint: 'go'
+  enterKeyHint: "go";
   /** Disable autocorrect. */
-  autoCorrect: 'off'
+  autoCorrect: "off";
   /** Disable spell check. */
-  spellCheck: 'false'
+  spellCheck: "false";
   /** Disable browser autocomplete. */
-  autoComplete: 'off'
+  autoComplete: "off";
 }
 
 export interface AriaAutocompleteOptions<_T = unknown> {
   /** Ref accessor for the input element. */
-  inputRef: Accessor<HTMLInputElement | undefined>
+  inputRef: Accessor<HTMLInputElement | undefined>;
   /** Ref accessor for the collection element. */
-  collectionRef: Accessor<HTMLElement | undefined>
+  collectionRef: Accessor<HTMLElement | undefined>;
   /** Optional id override for the controlled collection element. */
-  collectionId?: string
+  collectionId?: string;
   /** Optional accessible name for the controlled collection element. */
-  collectionAriaLabel?: string
+  collectionAriaLabel?: string;
   /**
    * An optional filter function used to determine if an option should be included.
    * @param textValue - The text value of the item
    * @param inputValue - The current input value
    */
-  filter?: (textValue: string, inputValue: string) => boolean
+  filter?: (textValue: string, inputValue: string) => boolean;
   /**
    * Whether to focus the first item after filtering.
    * @default false
    */
-  disableAutoFocusFirst?: boolean
+  disableAutoFocusFirst?: boolean;
   /**
    * Whether to disable virtual focus (aria-activedescendant).
    * @default false
    */
-  disableVirtualFocus?: boolean
+  disableVirtualFocus?: boolean;
 }
 
 export interface AutocompleteAria<_T = unknown> {
   /** Props for the autocomplete input element. */
-  inputProps: AutocompleteInputProps
+  inputProps: AutocompleteInputProps;
   /** Props for the collection (ListBox/Menu). */
-  collectionProps: CollectionOptions
+  collectionProps: CollectionOptions;
   /** A filter function that returns if the item should be shown. */
-  filter?: (textValue: string) => boolean
+  filter?: (textValue: string) => boolean;
 }
 
 function toKeyboardEventInit(e: KeyboardEvent): KeyboardEventInit {
@@ -107,20 +100,12 @@ function toKeyboardEventInit(e: KeyboardEvent): KeyboardEventInit {
     metaKey: e.metaKey,
     bubbles: e.bubbles,
     cancelable: e.cancelable,
-  }
+  };
 }
 
-// ============================================
-// CONSTANTS
-// ============================================
-
 // Custom event names for collection communication
-export const AUTOCOMPLETE_FOCUS_EVENT = 'autocomplete:focus'
-export const AUTOCOMPLETE_CLEAR_FOCUS_EVENT = 'autocomplete:clearfocus'
-
-// ============================================
-// CREATE AUTOCOMPLETE HOOK
-// ============================================
+export const AUTOCOMPLETE_FOCUS_EVENT = "autocomplete:focus";
+export const AUTOCOMPLETE_CLEAR_FOCUS_EVENT = "autocomplete:clearfocus";
 
 /**
  * Provides the behavior and accessibility implementation for an autocomplete component.
@@ -153,7 +138,7 @@ export const AUTOCOMPLETE_CLEAR_FOCUS_EVENT = 'autocomplete:clearfocus'
  */
 export function createAutocomplete<T = unknown>(
   props: AriaAutocompleteOptions<T>,
-  state: AutocompleteState
+  state: AutocompleteState,
 ): AutocompleteAria<T> {
   const {
     inputRef,
@@ -163,109 +148,129 @@ export function createAutocomplete<T = unknown>(
     collectionAriaLabel,
     disableAutoFocusFirst = false,
     disableVirtualFocus = false,
-  } = props
-
-  const collectionId = collectionIdProp ?? createId()
-  const [shouldUseVirtualFocus] = createSignal(!disableVirtualFocus)
-  let lastInputType = ''
-
-  // Track the input type for determining focus behavior
-  const handleInput = (e: Event) => {
-    const inputEvent = e as InputEvent
-    lastInputType = inputEvent.inputType || ''
-  }
-
-  // Set up input event listener
+  } = props;
+
+  const collectionId = collectionIdProp ?? createId();
+  const [shouldUseVirtualFocus] = createSignal(!disableVirtualFocus);
+  // When the first item should be focused but the collection hasn't mounted yet,
+  // defer it by threading autoFocus through collectionProps so the collection
+  // focuses on mount (mirrors upstream's autoFocusOnMount state).
+  const [autoFocusOnMount, setAutoFocusOnMount] = createSignal(false);
+  let lastInputType = "";
+
+  // Track the input type for determining focus behavior. We listen to
+  // `beforeinput` (not `input`) so `lastInputType` is set before the input's
+  // `onChange` runs, mirroring @react-aria/autocomplete.
+  const handleBeforeInput = (e: Event) => {
+    const inputEvent = e as InputEvent;
+    lastInputType = inputEvent.inputType || "";
+  };
+
+  // Set up beforeinput event listener
   createEffect(() => {
-    const input = inputRef()
+    const input = inputRef();
     if (input) {
-      input.addEventListener('input', handleInput)
+      input.addEventListener("beforeinput", handleBeforeInput);
       onCleanup(() => {
-        input.removeEventListener('input', handleInput)
-      })
+        input.removeEventListener("beforeinput", handleBeforeInput);
+      });
     }
-  })
+  });
 
   // Focus first item in collection
   const focusFirstItem = () => {
-    const collection = collectionRef()
-    if (collection) {
-      collection.dispatchEvent(
-        new CustomEvent(AUTOCOMPLETE_FOCUS_EVENT, {
-          cancelable: true,
-          bubbles: true,
-          detail: { focusStrategy: 'first' },
-        })
-      )
+    const collection = collectionRef();
+    if (!collection) {
+      // Collection isn't mounted yet — defer focusing the first item to mount
+      // time via collectionProps.autoFocus instead of firing a focus event into
+      // a not-yet-rendered collection.
+      setAutoFocusOnMount(true);
+      return;
     }
-  }
+    collection.dispatchEvent(
+      new CustomEvent(AUTOCOMPLETE_FOCUS_EVENT, {
+        cancelable: true,
+        bubbles: true,
+        detail: { focusStrategy: "first" },
+      }),
+    );
+  };
 
   // Clear virtual focus
   const clearVirtualFocus = (clearFocusKey = false) => {
-    state.setFocusedNodeId(null)
-    const collection = collectionRef()
+    setAutoFocusOnMount(false);
+    state.setFocusedNodeId(null);
+    const collection = collectionRef();
     if (collection) {
       collection.dispatchEvent(
         new CustomEvent(AUTOCOMPLETE_CLEAR_FOCUS_EVENT, {
           cancelable: true,
           bubbles: true,
           detail: { clearFocusKey },
-        })
-      )
+        }),
+      );
     }
-  }
+  };
 
   // Handle input value changes
   const onChange = (value: string) => {
-    // Focus first item when typing forward, clear when backspacing/pasting
-    if (lastInputType === 'insertText' && !disableAutoFocusFirst) {
-      focusFirstItem()
+    // Focus first item when typing forward, clear when backspacing/pasting.
+    // IME composition (e.g. CJK input) reports 'insertCompositionText'/
+    // 'insertFromComposition' instead of 'insertText'; treat those as forward
+    // typing so the first item still gets virtual focus.
+    if (
+      (lastInputType === "insertText" ||
+        lastInputType === "insertCompositionText" ||
+        lastInputType === "insertFromComposition") &&
+      !disableAutoFocusFirst
+    ) {
+      focusFirstItem();
     } else if (
       lastInputType &&
-      (lastInputType.includes('insert') ||
-        lastInputType.includes('delete') ||
-        lastInputType.includes('history'))
+      (lastInputType.includes("insert") ||
+        lastInputType.includes("delete") ||
+        lastInputType.includes("history"))
     ) {
-      clearVirtualFocus(true)
+      clearVirtualFocus(true);
     }
 
-    state.setInputValue(value)
-  }
+    state.setInputValue(value);
+  };
 
   // Handle keyboard navigation
   const onKeyDown = (e: KeyboardEvent) => {
-    if ('isComposing' in e && e.isComposing) {
-      return
+    if ("isComposing" in e && e.isComposing) {
+      return;
     }
 
-    const focusedNodeId = state.focusedNodeId()
-    const collection = collectionRef()
-    const ownerDocument = getOwnerDocument(inputRef() ?? collection)
+    const focusedNodeId = state.focusedNodeId();
+    const collection = collectionRef();
+    const ownerDocument = getOwnerDocument(inputRef() ?? collection);
 
     switch (e.key) {
-      case 'Escape':
+      case "Escape":
         // Let the input handle Escape (e.g., clear value)
         if (e.defaultPrevented) {
-          return
+          return;
         }
-        break
+        break;
 
-      case ' ':
+      case " ":
         // Space shouldn't trigger item action
-        return
+        return;
 
-      case 'Tab':
+      case "Tab":
         // Let Tab propagate normally for focus management
-        return
-
-      case 'ArrowUp':
-      case 'ArrowDown':
-      case 'Home':
-      case 'End':
-      case 'PageUp':
-      case 'PageDown': {
+        return;
+
+      case "ArrowUp":
+      case "ArrowDown":
+      case "Home":
+      case "End":
+      case "PageUp":
+      case "PageDown": {
         // Prevent cursor movement in input
-        e.preventDefault()
+        e.preventDefault();
 
         // Dispatch focus event to collection
         if (collection) {
@@ -273,68 +278,89 @@ export function createAutocomplete<T = unknown>(
             new CustomEvent(AUTOCOMPLETE_FOCUS_EVENT, {
               cancelable: true,
               bubbles: true,
-            })
-          )
+            }),
+          );
         }
-        break
+        break;
       }
 
-      case 'ArrowLeft':
-      case 'ArrowRight':
-        // Clear activedescendant so screen reader announces cursor movement
-        clearVirtualFocus()
-        return
+      case "ArrowLeft":
+      case "ArrowRight":
+        // With no virtual focus, just let the arrow move the text cursor; stop
+        // propagation so it doesn't leak into the collection. With virtual focus,
+        // fall through to dispatch the key to the focused item below, then clear
+        // the active descendant only after the item has seen it.
+        if (!focusedNodeId) {
+          e.stopPropagation();
+          return;
+        }
+        break;
 
-      case 'Enter':
+      case "Enter":
         // Trigger click on focused item
         if (focusedNodeId) {
-          const item = ownerDocument?.getElementById(focusedNodeId)
+          const item = ownerDocument?.getElementById(focusedNodeId);
           if (item) {
-            item.click()
-            e.preventDefault()
+            item.click();
+            e.preventDefault();
           }
         }
-        return
+        return;
     }
 
-    // Forward keyboard events to collection/focused item
+    // Forward keyboard events to the focused item (or the collection when there
+    // is no virtual focus) so the collection can act on them, e.g. onAction.
     if (!e.defaultPrevented && collection) {
-      e.stopPropagation()
+      e.stopPropagation();
 
+      let shouldPerformDefaultAction = true;
       if (focusedNodeId) {
-        const item = ownerDocument?.getElementById(focusedNodeId)
+        const item = ownerDocument?.getElementById(focusedNodeId);
         if (item) {
-          item.dispatchEvent(new KeyboardEvent(e.type, toKeyboardEventInit(e)))
+          shouldPerformDefaultAction = item.dispatchEvent(
+            new KeyboardEvent(e.type, toKeyboardEventInit(e)),
+          );
         }
       } else {
-        collection.dispatchEvent(new KeyboardEvent(e.type, toKeyboardEventInit(e)))
+        shouldPerformDefaultAction = collection.dispatchEvent(
+          new KeyboardEvent(e.type, toKeyboardEventInit(e)),
+        );
+      }
+
+      // After the focused item has seen ArrowLeft/ArrowRight, clear the active
+      // descendant so SR announcements aren't interrupted, but retain the
+      // collection's focused key so navigation restarts where it left off. If
+      // the item consumed the key (e.g. an expandable row collapsing), it
+      // cancels the event and we keep virtual focus.
+      if (shouldPerformDefaultAction && (e.key === "ArrowLeft" || e.key === "ArrowRight")) {
+        clearVirtualFocus();
       }
     }
-  }
+  };
 
   // Handle focus events
   const onFocus = (e: FocusEvent) => {
-    if (!e.isTrusted) return
+    if (!e.isTrusted) return;
 
     // Restore virtual focus when refocusing input
-    const focusedNodeId = state.focusedNodeId()
+    const focusedNodeId = state.focusedNodeId();
     if (focusedNodeId) {
-      const item = document.getElementById(focusedNodeId)
+      const item = document.getElementById(focusedNodeId);
       if (item) {
         // Item still exists, keep focus on it
       }
     }
-  }
+  };
 
   const onBlur = (e: FocusEvent) => {
-    if (!e.isTrusted) return
+    if (!e.isTrusted) return;
     // Virtual focus blur handling would go here
-  }
+  };
 
   // Create filter function
   const filterFn = filter
     ? (textValue: string) => filter(textValue, state.inputValue())
-    : undefined
+    : undefined;
 
   return {
     inputProps: {
@@ -343,22 +369,25 @@ export function createAutocomplete<T = unknown>(
       onKeyDown,
       onFocus,
       onBlur,
-      get 'aria-activedescendant'() {
-        return () => (shouldUseVirtualFocus() ? state.focusedNodeId() ?? undefined : undefined)
+      get "aria-activedescendant"() {
+        return () => (shouldUseVirtualFocus() ? (state.focusedNodeId() ?? undefined) : undefined);
       },
-      'aria-controls': collectionId,
-      'aria-autocomplete': 'list',
-      enterKeyHint: 'go',
-      autoCorrect: 'off',
-      spellCheck: 'false',
-      autoComplete: 'off',
+      "aria-controls": collectionId,
+      "aria-autocomplete": "list",
+      enterKeyHint: "go",
+      autoCorrect: "off",
+      spellCheck: "false",
+      autoComplete: "off",
     },
     collectionProps: {
       id: collectionId,
-      'aria-label': collectionAriaLabel,
+      "aria-label": collectionAriaLabel,
       shouldUseVirtualFocus: shouldUseVirtualFocus(),
       disallowTypeAhead: shouldUseVirtualFocus(),
+      get autoFocus() {
+        return autoFocusOnMount() ? "first" : false;
+      },
     },
     filter: filterFn,
-  }
+  };
 }

package/src/autocomplete/index.ts

@@ -6,4 +6,4 @@ export {
   type AutocompleteAria,
   type AutocompleteInputProps,
   type CollectionOptions,
-} from './createAutocomplete'
+} from "./createAutocomplete";

package/src/breadcrumbs/createBreadcrumbs.ts

@@ -5,22 +5,20 @@
  * Port of @react-aria/breadcrumbs.
  */
 
-import { createLink, type AriaLinkProps, type LinkAria } from '../link';
-import { filterDOMProps } from '../utils/filterDOMProps';
-import { mergeProps } from '../utils/mergeProps';
-import { type MaybeAccessor, access } from '../utils/reactivity';
-
-// ============================================
-// TYPES
-// ============================================
+import { createLink, type AriaLinkProps, type LinkAria } from "../link";
+import { filterDOMProps } from "../utils/filterDOMProps";
+import { mergeProps } from "../utils/mergeProps";
+import { type MaybeAccessor, access } from "../utils/reactivity";
 
 export interface AriaBreadcrumbsProps {
   /** Provides a label for the breadcrumbs navigation. */
-  'aria-label'?: string;
+  "aria-label"?: string;
   /** Identifies the element (or elements) that labels the breadcrumbs. */
-  'aria-labelledby'?: string;
+  "aria-labelledby"?: string;
   /** Identifies the element (or elements) that describes the breadcrumbs. */
-  'aria-describedby'?: string;
+  "aria-describedby"?: string;
+  /** Identifies the element (or elements) that provide a detailed description. */
+  "aria-details"?: string;
   /** Whether the breadcrumbs are disabled. */
   isDisabled?: boolean;
 }
@@ -30,13 +28,13 @@ export interface BreadcrumbsAria {
   navProps: Record<string, unknown>;
 }
 
-export interface AriaBreadcrumbItemProps extends Omit<AriaLinkProps, 'aria-current'> {
+export interface AriaBreadcrumbItemProps extends Omit<AriaLinkProps, "aria-current"> {
   /** The DOM id for the breadcrumb item. */
   id?: string;
   /** Whether this is the current/last item in the breadcrumb trail. */
   isCurrent?: boolean;
   /** The type of current location for aria-current. @default 'page' */
-  'aria-current'?: 'page' | 'step' | 'location' | 'date' | 'time' | boolean;
+  "aria-current"?: "page" | "step" | "location" | "date" | "time" | boolean;
   /** The HTML element type. @default 'a' */
   elementType?: string;
 }
@@ -46,15 +44,11 @@ export interface BreadcrumbItemAria extends LinkAria {
   itemProps: Record<string, unknown>;
 }
 
-// ============================================
-// IMPLEMENTATION
-// ============================================
-
 /**
  * Provides accessibility implementation for the breadcrumbs navigation container.
  */
 export function createBreadcrumbs(
-  props: MaybeAccessor<AriaBreadcrumbsProps> = {}
+  props: MaybeAccessor<AriaBreadcrumbsProps> = {},
 ): BreadcrumbsAria {
   const getProps = () => access(props);
 
@@ -62,15 +56,12 @@ export function createBreadcrumbs(
     const p = getProps();
 
     // Only apply a default label when no other label source exists.
-    const ariaLabel =
-      p['aria-label'] ?? (p['aria-labelledby'] ? undefined : 'Breadcrumbs');
-
-    return mergeProps(
-      filterDOMProps(p as Record<string, unknown>, { labelable: true }),
-      {
-        'aria-label': ariaLabel,
-      }
-    );
+    const ariaLabel = p["aria-label"] ?? (p["aria-labelledby"] ? undefined : "Breadcrumbs");
+
+    return mergeProps(filterDOMProps(p as Record<string, unknown>, { labelable: true }), {
+      "aria-label": ariaLabel,
+      "aria-details": p["aria-details"],
+    });
   };
 
   return {
@@ -84,13 +75,13 @@ export function createBreadcrumbs(
  * Provides accessibility implementation for an individual breadcrumb item.
  */
 export function createBreadcrumbItem(
-  props: MaybeAccessor<AriaBreadcrumbItemProps> = {}
+  props: MaybeAccessor<AriaBreadcrumbItemProps> = {},
 ): BreadcrumbItemAria {
   const getProps = () => access(props);
 
   const isCurrent = () => getProps().isCurrent ?? false;
   const isDisabled = () => getProps().isDisabled ?? false;
-  const elementType = () => getProps().elementType ?? 'a';
+  const elementType = () => getProps().elementType ?? "a";
 
   // Use createLink for base link behavior
   // Current items are treated as disabled (can't navigate to current page)
@@ -140,14 +131,17 @@ export function createBreadcrumbItem(
     get autoFocus() {
       return getProps().autoFocus;
     },
-    get 'aria-label'() {
-      return getProps()['aria-label'];
+    get "aria-label"() {
+      return getProps()["aria-label"];
     },
-    get 'aria-labelledby'() {
-      return getProps()['aria-labelledby'];
+    get "aria-labelledby"() {
+      return getProps()["aria-labelledby"];
     },
-    get 'aria-describedby'() {
-      return getProps()['aria-describedby'];
+    get "aria-describedby"() {
+      return getProps()["aria-describedby"];
+    },
+    get "aria-details"() {
+      return getProps()["aria-details"];
     },
   });
 
@@ -156,23 +150,20 @@ export function createBreadcrumbItem(
     const current = isCurrent();
 
     // Start with link props, forwarding id if provided
-    let baseProps: Record<string, unknown> = p.id
-      ? mergeProps(linkProps, { id: p.id })
-      : linkProps;
+    let baseProps: Record<string, unknown> = p.id ? mergeProps(linkProps, { id: p.id }) : linkProps;
 
     // Add aria-current for current page
     if (current) {
-      const ariaCurrent = p['aria-current'] ?? 'page';
+      const ariaCurrent = p["aria-current"] ?? "page";
       baseProps = mergeProps(baseProps, {
-        'aria-current': ariaCurrent,
+        "aria-current": ariaCurrent,
       });
-
     }
 
     // Add aria-disabled for disabled items
     if (isDisabled()) {
       baseProps = mergeProps(baseProps, {
-        'aria-disabled': true,
+        "aria-disabled": true,
       });
     }
 

package/src/breadcrumbs/index.ts

@@ -5,4 +5,4 @@ export {
   type BreadcrumbsAria,
   type AriaBreadcrumbItemProps,
   type BreadcrumbItemAria,
-} from './createBreadcrumbs';
+} from "./createBreadcrumbs";