@proyecto-viviana/solidaria 0.2.2 → 0.2.3

package/src/toolbar/createToolbar.ts

@@ -0,0 +1,369 @@
+/**
+ * createToolbar - Accessibility hook for toolbar elements
+ *
+ * Provides keyboard navigation between toolbar items using arrow keys.
+ * Based on @react-aria/toolbar useToolbar.
+ */
+
+import {
+  createSignal,
+  createEffect,
+  onMount,
+  onCleanup,
+  type Accessor,
+} from 'solid-js'
+import { type MaybeAccessor, access } from '../utils'
+import { useLocale } from '../i18n'
+import { getOwnerDocument, isFocusable } from '../utils'
+import { focusSafely } from '../utils/focus'
+
+// ============================================
+// TYPES
+// ============================================
+
+export type Orientation = 'horizontal' | 'vertical'
+
+export interface AriaToolbarProps {
+  /** The orientation of the toolbar. @default 'horizontal' */
+  orientation?: MaybeAccessor<Orientation>
+  /** An accessibility label for the toolbar. */
+  'aria-label'?: MaybeAccessor<string>
+  /** Identifies the element (or elements) that labels the toolbar. */
+  'aria-labelledby'?: MaybeAccessor<string>
+}
+
+export interface ToolbarAria {
+  /** Props for the toolbar container element. */
+  toolbarProps: {
+    role: 'toolbar' | 'group'
+    'aria-orientation': Orientation
+    'aria-label'?: string
+    'aria-labelledby'?: string
+    tabIndex?: number
+    ref: (el: HTMLElement) => void
+  }
+  /** The orientation of the toolbar. */
+  orientation: Accessor<Orientation>
+}
+
+// ============================================
+// FOCUS MANAGER FOR TOOLBAR
+// ============================================
+
+interface FocusManagerOptions {
+  from?: Element
+  tabbable?: boolean
+  wrap?: boolean
+  accept?: (node: Element) => boolean
+}
+
+interface FocusManager {
+  focusNext(opts?: FocusManagerOptions): HTMLElement | null
+  focusPrevious(opts?: FocusManagerOptions): HTMLElement | null
+  focusFirst(opts?: FocusManagerOptions): HTMLElement | null
+  focusLast(opts?: FocusManagerOptions): HTMLElement | null
+}
+
+function isTabbable(element: Element): boolean {
+  if (!isFocusable(element)) {
+    return false
+  }
+  const tabIndex = element.getAttribute('tabindex')
+  if (tabIndex != null) {
+    return parseInt(tabIndex, 10) >= 0
+  }
+  return true
+}
+
+function getFocusableElements(root: Element, tabbable = false): HTMLElement[] {
+  const elements: HTMLElement[] = []
+  const filter = tabbable ? isTabbable : isFocusable
+
+  // Check the root element itself
+  if (filter(root)) {
+    elements.push(root as HTMLElement)
+  }
+
+  // Check all descendants
+  const descendants = root.querySelectorAll('*')
+  for (let i = 0; i < descendants.length; i++) {
+    const el = descendants[i]
+    if (filter(el)) {
+      elements.push(el as HTMLElement)
+    }
+  }
+
+  return elements
+}
+
+function getActiveElement(doc: Document): Element | null {
+  let activeElement = doc.activeElement
+  while (activeElement?.shadowRoot?.activeElement) {
+    activeElement = activeElement.shadowRoot.activeElement
+  }
+  return activeElement
+}
+
+function createFocusManager(ref: Accessor<HTMLElement | undefined>): FocusManager {
+  return {
+    focusNext(opts: FocusManagerOptions = {}) {
+      const root = ref()
+      if (!root) return null
+
+      const { from, tabbable = true, wrap = false, accept } = opts
+      const doc = getOwnerDocument(root)
+      const current = from || getActiveElement(doc)
+
+      let elements = getFocusableElements(root, tabbable)
+      if (accept) {
+        elements = elements.filter(accept)
+      }
+
+      if (!current || elements.length === 0) return null
+
+      const currentIndex = elements.indexOf(current as HTMLElement)
+      let nextIndex = currentIndex + 1
+
+      if (nextIndex >= elements.length) {
+        if (wrap) {
+          nextIndex = 0
+        } else {
+          return null
+        }
+      }
+
+      const nextElement = elements[nextIndex]
+      if (nextElement) {
+        focusSafely(nextElement)
+        return nextElement
+      }
+
+      return null
+    },
+
+    focusPrevious(opts: FocusManagerOptions = {}) {
+      const root = ref()
+      if (!root) return null
+
+      const { from, tabbable = true, wrap = false, accept } = opts
+      const doc = getOwnerDocument(root)
+      const current = from || getActiveElement(doc)
+
+      let elements = getFocusableElements(root, tabbable)
+      if (accept) {
+        elements = elements.filter(accept)
+      }
+
+      if (!current || elements.length === 0) return null
+
+      const currentIndex = elements.indexOf(current as HTMLElement)
+      let prevIndex = currentIndex - 1
+
+      if (prevIndex < 0) {
+        if (wrap) {
+          prevIndex = elements.length - 1
+        } else {
+          return null
+        }
+      }
+
+      const prevElement = elements[prevIndex]
+      if (prevElement) {
+        focusSafely(prevElement)
+        return prevElement
+      }
+
+      return null
+    },
+
+    focusFirst(opts: FocusManagerOptions = {}) {
+      const root = ref()
+      if (!root) return null
+
+      const { tabbable = true, accept } = opts
+      let elements = getFocusableElements(root, tabbable)
+      if (accept) {
+        elements = elements.filter(accept)
+      }
+
+      if (elements.length > 0) {
+        focusSafely(elements[0])
+        return elements[0]
+      }
+
+      return null
+    },
+
+    focusLast(opts: FocusManagerOptions = {}) {
+      const root = ref()
+      if (!root) return null
+
+      const { tabbable = true, accept } = opts
+      let elements = getFocusableElements(root, tabbable)
+      if (accept) {
+        elements = elements.filter(accept)
+      }
+
+      if (elements.length > 0) {
+        const lastElement = elements[elements.length - 1]
+        focusSafely(lastElement)
+        return lastElement
+      }
+
+      return null
+    },
+  }
+}
+
+// ============================================
+// CREATE TOOLBAR HOOK
+// ============================================
+
+/**
+ * Provides the behavior and accessibility implementation for a toolbar.
+ * A toolbar is a container for a set of interactive controls with arrow key navigation.
+ *
+ * @example
+ * ```tsx
+ * let ref;
+ * const { toolbarProps } = createToolbar({ orientation: 'horizontal' });
+ * return (
+ *   <div {...toolbarProps}>
+ *     <Button>Cut</Button>
+ *     <Button>Copy</Button>
+ *     <Button>Paste</Button>
+ *   </div>
+ * );
+ * ```
+ */
+export function createToolbar(props: AriaToolbarProps = {}): ToolbarAria {
+  let toolbarRef: HTMLElement | undefined
+  const [isInToolbar, setIsInToolbar] = createSignal(false)
+  let lastFocusedElement: Element | null = null
+
+  const locale = useLocale()
+  const orientation = () => access(props.orientation) ?? 'horizontal'
+  const ariaLabel = () => access(props['aria-label'])
+  const ariaLabelledby = () => access(props['aria-labelledby'])
+
+  const focusManager = createFocusManager(() => toolbarRef)
+
+  // Check if this toolbar is nested inside another toolbar
+  onMount(() => {
+    if (toolbarRef) {
+      const parentToolbar = toolbarRef.parentElement?.closest('[role="toolbar"]')
+      setIsInToolbar(!!parentToolbar)
+    }
+  })
+
+  // Keyboard event handler
+  const onKeyDown = (e: KeyboardEvent) => {
+    // Don't handle if nested toolbar (parent handles navigation)
+    if (isInToolbar()) return
+
+    const dir = locale().direction
+    const isRTL = dir === 'rtl'
+    const isHorizontal = orientation() === 'horizontal'
+
+    let handled = false
+
+    switch (e.key) {
+      case 'ArrowRight':
+        if (isHorizontal) {
+          if (isRTL) {
+            focusManager.focusPrevious({ tabbable: true })
+          } else {
+            focusManager.focusNext({ tabbable: true })
+          }
+          handled = true
+        }
+        break
+      case 'ArrowLeft':
+        if (isHorizontal) {
+          if (isRTL) {
+            focusManager.focusNext({ tabbable: true })
+          } else {
+            focusManager.focusPrevious({ tabbable: true })
+          }
+          handled = true
+        }
+        break
+      case 'ArrowDown':
+        if (!isHorizontal) {
+          focusManager.focusNext({ tabbable: true })
+          handled = true
+        }
+        break
+      case 'ArrowUp':
+        if (!isHorizontal) {
+          focusManager.focusPrevious({ tabbable: true })
+          handled = true
+        }
+        break
+      case 'Tab':
+        // Store the last focused element for re-entry
+        lastFocusedElement = e.target as Element
+        break
+    }
+
+    if (handled) {
+      e.preventDefault()
+      e.stopPropagation()
+    }
+  }
+
+  // Focus handler - restore last focused element when re-entering
+  const onFocus = (e: FocusEvent) => {
+    if (isInToolbar()) return
+
+    // Only restore if focus is coming from outside the toolbar
+    const root = toolbarRef
+    if (!root) return
+
+    const relatedTarget = e.relatedTarget as Element | null
+
+    // If focus came from outside and we have a last focused element
+    if (
+      lastFocusedElement &&
+      root.contains(lastFocusedElement) &&
+      (!relatedTarget || !root.contains(relatedTarget))
+    ) {
+      // Restore focus to the last focused element
+      focusSafely(lastFocusedElement as HTMLElement)
+    }
+  }
+
+  // Set up capture event listeners
+  const setRef = (el: HTMLElement) => {
+    toolbarRef = el
+
+    // Use capture phase for keyboard events
+    el.addEventListener('keydown', onKeyDown, true)
+    el.addEventListener('focus', onFocus, true)
+
+    onCleanup(() => {
+      el.removeEventListener('keydown', onKeyDown, true)
+      el.removeEventListener('focus', onFocus, true)
+    })
+  }
+
+  return {
+    toolbarProps: {
+      get role() {
+        return isInToolbar() ? 'group' : 'toolbar'
+      },
+      get 'aria-orientation'() {
+        return orientation()
+      },
+      get 'aria-label'() {
+        return ariaLabel()
+      },
+      get 'aria-labelledby'() {
+        // Only use aria-labelledby if no aria-label is provided
+        return ariaLabel() ? undefined : ariaLabelledby()
+      },
+      ref: setRef,
+    },
+    orientation,
+  }
+}

package/src/toolbar/index.ts

@@ -0,0 +1,6 @@
+export {
+  createToolbar,
+  type AriaToolbarProps,
+  type ToolbarAria,
+  type Orientation,
+} from './createToolbar'

package/src/tooltip/createTooltip.ts

@@ -0,0 +1,79 @@
+/**
+ * createTooltip hook for Solidaria
+ *
+ * Provides the accessibility implementation for a Tooltip component.
+ *
+ * Port of @react-aria/tooltip useTooltip.
+ */
+
+import { type JSX } from 'solid-js';
+import { type TooltipTriggerState } from '@proyecto-viviana/solid-stately';
+import { createHover } from '../interactions/createHover';
+import { filterDOMProps, mergeProps } from '../utils';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface TooltipProps {
+  /** Whether the tooltip is disabled. */
+  isDisabled?: boolean;
+  /** Custom aria-label for the tooltip. */
+  'aria-label'?: string;
+  /** ID of an element that labels the tooltip. */
+  'aria-labelledby'?: string;
+  /** ID of an element that describes the tooltip. */
+  'aria-describedby'?: string;
+}
+
+export interface TooltipAria {
+  /** Props to spread on the tooltip element. */
+  tooltipProps: JSX.HTMLAttributes<HTMLElement>;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the accessibility implementation for a Tooltip component.
+ *
+ * When hovering over the tooltip itself, it stays open. When the mouse leaves
+ * the tooltip, it closes.
+ *
+ * @example
+ * ```tsx
+ * import { createTooltip } from 'solidaria';
+ * import { createTooltipTriggerState } from 'solid-stately';
+ *
+ * function Tooltip(props) {
+ *   const state = props.state;
+ *   const { tooltipProps } = createTooltip(props, state);
+ *
+ *   return (
+ *     <div {...tooltipProps} role="tooltip">
+ *       {props.children}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function createTooltip(
+  props: TooltipProps = {},
+  state?: TooltipTriggerState
+): TooltipAria {
+  const domProps = filterDOMProps(props, { labelable: true });
+
+  const { hoverProps } = createHover({
+    onHoverStart: () => state?.open(true),
+    onHoverEnd: () => state?.close(),
+  });
+
+  return {
+    tooltipProps: mergeProps<JSX.HTMLAttributes<HTMLElement>>(
+      domProps,
+      hoverProps,
+      { role: 'tooltip' }
+    ),
+  };
+}

package/src/tooltip/createTooltipTrigger.ts

@@ -0,0 +1,222 @@
+/**
+ * createTooltipTrigger hook for Solidaria
+ *
+ * Provides the behavior and accessibility implementation for a tooltip trigger,
+ * e.g. a button that shows a description when focused or hovered.
+ *
+ * Port of @react-aria/tooltip useTooltipTrigger.
+ */
+
+import { type JSX, createEffect, onCleanup } from 'solid-js';
+import { type TooltipTriggerState } from '@proyecto-viviana/solid-stately';
+import { createHover } from '../interactions/createHover';
+import { createFocusable } from '../interactions/createFocusable';
+import { mergeProps } from '../utils';
+import { createId } from '../ssr';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface TooltipTriggerProps {
+  /** Whether the tooltip should be disabled. */
+  isDisabled?: boolean;
+  /**
+   * The trigger mechanism for the tooltip.
+   * @default 'focus'
+   */
+  trigger?: 'focus';
+  /**
+   * Whether the tooltip should close when the trigger is pressed.
+   * @default true
+   */
+  shouldCloseOnPress?: boolean;
+}
+
+export interface TooltipTriggerAria {
+  /** Props to spread on the trigger element. */
+  triggerProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props to spread on the tooltip element (id for accessibility). */
+  tooltipProps: { id: string };
+}
+
+// ============================================
+// GLOBAL STATE
+// ============================================
+
+type Modality = 'keyboard' | 'pointer' | 'virtual';
+let currentModality: Modality | null = null;
+
+// Track interaction modality (pointer vs keyboard)
+if (typeof document !== 'undefined') {
+  document.addEventListener('keydown', () => {
+    currentModality = 'keyboard';
+  }, true);
+  document.addEventListener('pointerdown', () => {
+    currentModality = 'pointer';
+  }, true);
+  document.addEventListener('pointermove', () => {
+    currentModality = 'pointer';
+  }, true);
+}
+
+function isFocusVisible(): boolean {
+  return currentModality === 'keyboard';
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the behavior and accessibility implementation for a tooltip trigger.
+ *
+ * @example
+ * ```tsx
+ * import { createTooltipTrigger } from 'solidaria';
+ * import { createTooltipTriggerState } from 'solid-stately';
+ *
+ * function TooltipButton(props) {
+ *   let ref;
+ *   const state = createTooltipTriggerState({ delay: 500 });
+ *   const { triggerProps, tooltipProps } = createTooltipTrigger(
+ *     { isDisabled: props.isDisabled },
+ *     state,
+ *     () => ref
+ *   );
+ *
+ *   return (
+ *     <>
+ *       <button ref={ref} {...triggerProps}>
+ *         Hover me
+ *       </button>
+ *       <Show when={state.isOpen()}>
+ *         <div {...tooltipProps}>Tooltip content</div>
+ *       </Show>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function createTooltipTrigger(
+  props: TooltipTriggerProps,
+  state: TooltipTriggerState,
+  ref: () => HTMLElement | null | undefined
+): TooltipTriggerAria {
+  const {
+    isDisabled = false,
+    trigger,
+    shouldCloseOnPress = true,
+  } = props;
+
+  const tooltipId = createId();
+
+  // Track hover and focus state
+  let isHovered = false;
+  let isFocused = false;
+
+  const handleShow = () => {
+    if (isHovered || isFocused) {
+      state.open(isFocused);
+    }
+  };
+
+  const handleHide = (immediate?: boolean) => {
+    if (!isHovered && !isFocused) {
+      state.close(immediate);
+    }
+  };
+
+  // Handle Escape key to dismiss tooltip
+  createEffect(() => {
+    if (!state.isOpen()) return;
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      const element = ref();
+      if (element) {
+        if (e.key === 'Escape') {
+          e.stopPropagation();
+          state.close(true);
+        }
+      }
+    };
+
+    document.addEventListener('keydown', onKeyDown, true);
+    onCleanup(() => {
+      document.removeEventListener('keydown', onKeyDown, true);
+    });
+  });
+
+  const onHoverStart = () => {
+    if (trigger === 'focus') {
+      return;
+    }
+    // Hover events (onPointerEnter) only fire from pointer interactions,
+    // so we can always set isHovered to true here
+    isHovered = true;
+    handleShow();
+  };
+
+  const onHoverEnd = () => {
+    if (trigger === 'focus') {
+      return;
+    }
+    isFocused = false;
+    isHovered = false;
+    handleHide();
+  };
+
+  const onPressStart = () => {
+    if (!shouldCloseOnPress) {
+      return;
+    }
+    isFocused = false;
+    isHovered = false;
+    handleHide(true);
+  };
+
+  const onFocus = () => {
+    const visible = isFocusVisible();
+    if (visible) {
+      isFocused = true;
+      handleShow();
+    }
+  };
+
+  const onBlur = () => {
+    isFocused = false;
+    isHovered = false;
+    handleHide(true);
+  };
+
+  const { hoverProps } = createHover({
+    isDisabled,
+    onHoverStart,
+    onHoverEnd,
+  });
+
+  const { focusableProps } = createFocusable({
+    isDisabled,
+    onFocus,
+    onBlur,
+  });
+
+  const triggerProps = {
+    ...focusableProps,
+    ...hoverProps,
+    get 'aria-describedby'() {
+      return state.isOpen() ? tooltipId : undefined;
+    },
+    onPointerDown: onPressStart,
+    onKeyDown: onPressStart,
+    // Remove tabIndex set by focusableProps to avoid overriding
+    tabIndex: undefined,
+  };
+
+  return {
+    triggerProps: triggerProps as JSX.HTMLAttributes<HTMLElement>,
+    tooltipProps: {
+      id: tooltipId,
+    },
+  };
+}

package/src/tooltip/index.ts

@@ -0,0 +1,6 @@
+export { createTooltip, type TooltipProps, type TooltipAria } from './createTooltip';
+export {
+  createTooltipTrigger,
+  type TooltipTriggerProps,
+  type TooltipTriggerAria,
+} from './createTooltipTrigger';