@proyecto-viviana/solidaria 0.2.1 → 0.2.3

package/src/landmark/createLandmark.ts

@@ -0,0 +1,377 @@
+/**
+ * createLandmark - SolidJS implementation of React Aria's useLandmark
+ *
+ * Provides landmark navigation in an application. Call this with a role and label
+ * to register a landmark navigable with the F6 key.
+ *
+ * ARIA landmarks help screen reader users navigate between major sections of a page.
+ * The F6 key (or Shift+F6) cycles through all registered landmarks.
+ */
+
+import type { JSX, Accessor } from 'solid-js';
+import { createEffect, onCleanup } from 'solid-js';
+import { access, type MaybeAccessor } from '../utils';
+import { filterDOMProps } from '../utils';
+
+// ============================================
+// TYPES
+// ============================================
+
+/** ARIA landmark roles */
+export type AriaLandmarkRole =
+  | 'main'
+  | 'region'
+  | 'search'
+  | 'navigation'
+  | 'form'
+  | 'banner'
+  | 'contentinfo'
+  | 'complementary';
+
+export interface AriaLandmarkProps {
+  /** The ARIA landmark role. */
+  role: AriaLandmarkRole;
+  /**
+   * A human-readable label for the landmark.
+   * Required when multiple landmarks with the same role exist on a page.
+   */
+  'aria-label'?: string;
+  /** Identifies the element(s) that labels the landmark. */
+  'aria-labelledby'?: string;
+  /** The element's unique identifier. */
+  id?: string;
+  /**
+   * A custom focus handler called when this landmark receives focus via F6 navigation.
+   * Use this to focus a specific element within the landmark instead of the container.
+   */
+  focus?: () => void;
+}
+
+export interface LandmarkAria<T extends HTMLElement = HTMLElement> {
+  /** Props to spread on the landmark element. */
+  landmarkProps: JSX.HTMLAttributes<T>;
+}
+
+export interface LandmarkController {
+  /** Focus the next landmark in DOM order. */
+  focusNext: () => void;
+  /** Focus the previous landmark in DOM order. */
+  focusPrevious: () => void;
+  /** Focus the main landmark. */
+  focusMain: () => void;
+  /** Navigate to a specific landmark by role. If multiple exist, the first one is focused. */
+  navigate: (role: AriaLandmarkRole) => void;
+}
+
+// ============================================
+// INTERNAL: Landmark Entry
+// ============================================
+
+interface LandmarkEntry {
+  ref: HTMLElement;
+  role: AriaLandmarkRole;
+  label?: string;
+  focus?: () => void;
+  lastFocused?: HTMLElement;
+}
+
+// ============================================
+// LANDMARK MANAGER (Singleton)
+// ============================================
+
+/**
+ * Manages all registered landmarks and handles F6 keyboard navigation.
+ */
+class LandmarkManager {
+  private landmarks: LandmarkEntry[] = [];
+  private currentIndex = -1;
+  private listening = false;
+
+  constructor() {
+    if (typeof window !== 'undefined') {
+      this.startListening();
+    }
+  }
+
+  private startListening() {
+    if (this.listening) return;
+    this.listening = true;
+
+    window.addEventListener('keydown', this.handleKeyDown.bind(this), true);
+  }
+
+  private handleKeyDown(event: KeyboardEvent) {
+    // F6 to navigate landmarks
+    if (event.key === 'F6') {
+      event.preventDefault();
+      if (event.shiftKey) {
+        this.focusPrevious();
+      } else {
+        this.focusNext();
+      }
+    }
+  }
+
+  register(entry: LandmarkEntry): void {
+    // Insert in DOM order using compareDocumentPosition
+    const index = this.findInsertionIndex(entry.ref);
+    this.landmarks.splice(index, 0, entry);
+
+    // Validate: if multiple landmarks have the same role, they should have different labels
+    this.validateLabels();
+  }
+
+  unregister(ref: HTMLElement): void {
+    const index = this.landmarks.findIndex((l) => l.ref === ref);
+    if (index !== -1) {
+      this.landmarks.splice(index, 1);
+      // Adjust currentIndex if needed
+      if (this.currentIndex >= this.landmarks.length) {
+        this.currentIndex = this.landmarks.length - 1;
+      }
+    }
+  }
+
+  private findInsertionIndex(ref: HTMLElement): number {
+    // Binary search for insertion point based on DOM order
+    let low = 0;
+    let high = this.landmarks.length;
+
+    while (low < high) {
+      const mid = Math.floor((low + high) / 2);
+      const comparison = this.landmarks[mid].ref.compareDocumentPosition(ref);
+
+      // Node.DOCUMENT_POSITION_FOLLOWING = 4
+      if (comparison & Node.DOCUMENT_POSITION_FOLLOWING) {
+        low = mid + 1;
+      } else {
+        high = mid;
+      }
+    }
+
+    return low;
+  }
+
+  private validateLabels(): void {
+    // Group landmarks by role
+    const roleGroups = new Map<AriaLandmarkRole, LandmarkEntry[]>();
+    for (const landmark of this.landmarks) {
+      const group = roleGroups.get(landmark.role) || [];
+      group.push(landmark);
+      roleGroups.set(landmark.role, group);
+    }
+
+    // Warn if multiple landmarks with the same role lack unique labels
+    for (const [role, group] of roleGroups) {
+      if (group.length > 1) {
+        const labels = group.map((l) => l.label);
+        const uniqueLabels = new Set(labels.filter(Boolean));
+        if (uniqueLabels.size < group.length) {
+          console.warn(
+            `Multiple landmarks with role "${role}" exist. Each should have a unique aria-label or aria-labelledby.`
+          );
+        }
+      }
+    }
+  }
+
+  focusNext(): void {
+    if (this.landmarks.length === 0) return;
+
+    // Find the currently focused landmark
+    const activeElement = document.activeElement;
+    this.currentIndex = this.findCurrentLandmarkIndex(activeElement);
+
+    // Move to next
+    this.currentIndex = (this.currentIndex + 1) % this.landmarks.length;
+    this.focusLandmark(this.landmarks[this.currentIndex]);
+  }
+
+  focusPrevious(): void {
+    if (this.landmarks.length === 0) return;
+
+    // Find the currently focused landmark
+    const activeElement = document.activeElement;
+    this.currentIndex = this.findCurrentLandmarkIndex(activeElement);
+
+    // Move to previous
+    this.currentIndex =
+      (this.currentIndex - 1 + this.landmarks.length) % this.landmarks.length;
+    this.focusLandmark(this.landmarks[this.currentIndex]);
+  }
+
+  focusMain(): void {
+    const main = this.landmarks.find((l) => l.role === 'main');
+    if (main) {
+      this.focusLandmark(main);
+    }
+  }
+
+  navigate(role: AriaLandmarkRole): void {
+    const landmark = this.landmarks.find((l) => l.role === role);
+    if (landmark) {
+      this.focusLandmark(landmark);
+    }
+  }
+
+  private findCurrentLandmarkIndex(activeElement: Element | null): number {
+    if (!activeElement) return -1;
+
+    // Check if active element is within any landmark
+    for (let i = 0; i < this.landmarks.length; i++) {
+      if (this.landmarks[i].ref.contains(activeElement)) {
+        // Store the last focused element for this landmark
+        if (activeElement instanceof HTMLElement) {
+          this.landmarks[i].lastFocused = activeElement;
+        }
+        return i;
+      }
+    }
+
+    return -1;
+  }
+
+  private focusLandmark(landmark: LandmarkEntry): void {
+    // If a custom focus handler is provided, use it
+    if (landmark.focus) {
+      landmark.focus();
+      return;
+    }
+
+    // If we previously focused an element in this landmark, try to restore it
+    if (landmark.lastFocused && landmark.ref.contains(landmark.lastFocused)) {
+      landmark.lastFocused.focus();
+      return;
+    }
+
+    // Try to find the first focusable element
+    const focusable = this.findFirstFocusable(landmark.ref);
+    if (focusable) {
+      focusable.focus();
+      return;
+    }
+
+    // Fallback: make the landmark itself focusable and focus it
+    if (!landmark.ref.hasAttribute('tabindex')) {
+      landmark.ref.setAttribute('tabindex', '-1');
+    }
+    landmark.ref.focus();
+  }
+
+  private findFirstFocusable(container: HTMLElement): HTMLElement | null {
+    const focusableSelectors = [
+      'a[href]',
+      'button:not([disabled])',
+      'input:not([disabled])',
+      'select:not([disabled])',
+      'textarea:not([disabled])',
+      '[tabindex]:not([tabindex="-1"])',
+    ].join(', ');
+
+    return container.querySelector<HTMLElement>(focusableSelectors);
+  }
+
+  getController(): LandmarkController {
+    return {
+      focusNext: () => this.focusNext(),
+      focusPrevious: () => this.focusPrevious(),
+      focusMain: () => this.focusMain(),
+      navigate: (role) => this.navigate(role),
+    };
+  }
+}
+
+// Global singleton instance
+let landmarkManager: LandmarkManager | null = null;
+
+function getLandmarkManager(): LandmarkManager {
+  if (!landmarkManager) {
+    landmarkManager = new LandmarkManager();
+  }
+  return landmarkManager;
+}
+
+// ============================================
+// CREATE LANDMARK
+// ============================================
+
+/**
+ * Provides landmark navigation in an application.
+ * Call this with a role and label to register a landmark navigable with F6.
+ *
+ * @example
+ * ```tsx
+ * function Navigation(props) {
+ *   let ref: HTMLElement;
+ *   const { landmarkProps } = createLandmark({
+ *     role: 'navigation',
+ *     'aria-label': 'Main navigation'
+ *   });
+ *
+ *   return (
+ *     <nav {...landmarkProps} ref={ref}>
+ *       {props.children}
+ *     </nav>
+ *   );
+ * }
+ * ```
+ */
+export function createLandmark<T extends HTMLElement = HTMLElement>(
+  props: MaybeAccessor<AriaLandmarkProps>,
+  ref: Accessor<T | undefined>
+): LandmarkAria<T> {
+  // Register with the landmark manager
+  createEffect(() => {
+    const element = ref();
+    if (!element) return;
+
+    const p = access(props);
+    const entry: LandmarkEntry = {
+      ref: element,
+      role: p.role,
+      label: p['aria-label'],
+      focus: p.focus,
+    };
+
+    const manager = getLandmarkManager();
+    manager.register(entry);
+
+    onCleanup(() => {
+      manager.unregister(element);
+    });
+  });
+
+  const getLandmarkProps = (): JSX.HTMLAttributes<T> => {
+    const p = access(props);
+    const domProps = filterDOMProps(p as unknown as Record<string, unknown>, { labelable: true });
+
+    return {
+      ...domProps,
+      role: p.role,
+    };
+  };
+
+  return {
+    get landmarkProps() {
+      return getLandmarkProps();
+    },
+  };
+}
+
+// ============================================
+// LANDMARK CONTROLLER
+// ============================================
+
+/**
+ * Returns a controller for programmatic landmark navigation.
+ *
+ * @example
+ * ```tsx
+ * const controller = getLandmarkController();
+ * controller.focusMain(); // Focus the main landmark
+ * controller.focusNext(); // Focus the next landmark
+ * ```
+ */
+export function getLandmarkController(): LandmarkController {
+  return getLandmarkManager().getController();
+}

package/src/landmark/index.ts

@@ -0,0 +1,8 @@
+export {
+  createLandmark,
+  getLandmarkController,
+  type AriaLandmarkRole,
+  type AriaLandmarkProps,
+  type LandmarkAria,
+  type LandmarkController,
+} from './createLandmark';

package/src/link/createLink.ts

@@ -0,0 +1,182 @@
+/**
+ * Link hook for Solidaria
+ *
+ * Provides the behavior and accessibility implementation for a link component.
+ * A link allows a user to navigate to another page or resource within a web page
+ * or application.
+ *
+ * This is a 1:1 port of @react-aria/link's useLink hook.
+ */
+
+import { type Accessor } from 'solid-js';
+import { createPress } from '../interactions/createPress';
+import { createFocusable } from '../interactions/createFocusable';
+import { mergeProps } from '../utils/mergeProps';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { type MaybeAccessor, access } from '../utils/reactivity';
+import { type PressEvent } from '../interactions/PressEvent';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaLinkProps {
+  /** Whether the link is disabled. */
+  isDisabled?: boolean;
+  /** The HTML element used to render the link, e.g. 'a', or 'span'. @default 'a' */
+  elementType?: string;
+  /** The URL to link to. */
+  href?: string;
+  /** The target window for the link. */
+  target?: string;
+  /** The relationship between the linked resource and the current page. */
+  rel?: string;
+  /** Handler that is called when the press is released over the target. */
+  onPress?: (e: PressEvent) => void;
+  /** Handler that is called when a press interaction starts. */
+  onPressStart?: (e: PressEvent) => void;
+  /** Handler that is called when a press interaction ends. */
+  onPressEnd?: (e: PressEvent) => void;
+  /** Handler that is called when the element is clicked. */
+  onClick?: (e: MouseEvent) => void;
+  /** Handler that is called when the element receives focus. */
+  onFocus?: (e: FocusEvent) => void;
+  /** Handler that is called when the element loses focus. */
+  onBlur?: (e: FocusEvent) => void;
+  /** Handler that is called when the element's focus status changes. */
+  onFocusChange?: (isFocused: boolean) => void;
+  /** Handler that is called when a key is pressed. */
+  onKeyDown?: (e: KeyboardEvent) => void;
+  /** Handler that is called when a key is released. */
+  onKeyUp?: (e: KeyboardEvent) => void;
+  /** Whether to autofocus the element. */
+  autoFocus?: boolean;
+  /** Indicates the current "page" or state within a set of related elements. */
+  'aria-current'?: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false' | boolean;
+  /** Defines a string value that labels the current element. */
+  'aria-label'?: string;
+  /** Identifies the element (or elements) that labels the current element. */
+  'aria-labelledby'?: string;
+  /** Identifies the element (or elements) that describes the object. */
+  'aria-describedby'?: string;
+}
+
+export interface LinkAria {
+  /** Props for the link element. */
+  linkProps: Record<string, unknown>;
+  /** Whether the link is currently pressed. */
+  isPressed: Accessor<boolean>;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the behavior and accessibility implementation for a link component.
+ * A link allows a user to navigate to another page or resource within a web page
+ * or application.
+ */
+export function createLink(
+  props: MaybeAccessor<AriaLinkProps> = {}
+): LinkAria {
+  const getProps = () => access(props);
+
+  const isDisabled = () => getProps().isDisabled ?? false;
+  const elementType = () => getProps().elementType ?? 'a';
+
+  // Create press handling
+  const { pressProps, isPressed } = createPress({
+    get isDisabled() { return isDisabled(); },
+    get onPress() { return getProps().onPress; },
+    get onPressStart() { return getProps().onPressStart; },
+    get onPressEnd() { return getProps().onPressEnd; },
+  });
+
+  // Create focusable handling
+  const { focusableProps } = createFocusable({
+    get isDisabled() { return isDisabled(); },
+    get autoFocus() { return getProps().autoFocus; },
+    get onFocus() { return getProps().onFocus; },
+    get onBlur() { return getProps().onBlur; },
+    get onFocusChange() { return getProps().onFocusChange; },
+    get onKeyDown() { return getProps().onKeyDown; },
+    get onKeyUp() { return getProps().onKeyUp; },
+  });
+
+  // Build link props
+  const getLinkProps = (): Record<string, unknown> => {
+    const p = getProps();
+    const elType = elementType();
+    const disabled = isDisabled();
+
+    let baseProps: Record<string, unknown> = {};
+
+    // If not an <a>, add role and tabIndex
+    if (elType !== 'a') {
+      baseProps = {
+        role: 'link',
+        tabIndex: disabled ? undefined : 0,
+      };
+    }
+
+    // Add link-specific props
+    if (elType === 'a') {
+      if (p.href) baseProps.href = p.href;
+      if (p.target) baseProps.target = p.target;
+      if (p.rel) baseProps.rel = p.rel;
+    }
+
+    // ARIA attributes
+    const ariaProps: Record<string, unknown> = {
+      'aria-disabled': disabled || undefined,
+    };
+
+    if (p['aria-current'] !== undefined) {
+      ariaProps['aria-current'] = p['aria-current'];
+    }
+    if (p['aria-label']) {
+      ariaProps['aria-label'] = p['aria-label'];
+    }
+    if (p['aria-labelledby']) {
+      ariaProps['aria-labelledby'] = p['aria-labelledby'];
+    }
+    if (p['aria-describedby']) {
+      ariaProps['aria-describedby'] = p['aria-describedby'];
+    }
+
+    // Handle onClick - prevent default navigation when appropriate
+    const onClick = (e: MouseEvent) => {
+      // If disabled, prevent navigation and don't call user's onClick
+      if (disabled) {
+        e.preventDefault();
+        return;
+      }
+
+      // If onPress is provided, prevent default navigation
+      // This allows onPress to handle the action (e.g., client-side routing)
+      if (p.onPress) {
+        e.preventDefault();
+      }
+
+      // Call user's onClick if provided
+      p.onClick?.(e);
+    };
+
+    return mergeProps(
+      filterDOMProps(p as Record<string, unknown>, { labelable: true }),
+      baseProps,
+      ariaProps,
+      focusableProps as Record<string, unknown>,
+      pressProps as Record<string, unknown>,
+      { onClick }
+    );
+  };
+
+  return {
+    get linkProps() {
+      return getLinkProps();
+    },
+    isPressed,
+  };
+}

package/src/link/index.ts

@@ -0,0 +1 @@
+export { createLink, type AriaLinkProps, type LinkAria } from './createLink';