@proyecto-viviana/solidaria 0.1.3 → 0.2.0

package/src/landmark/createLandmark.ts

@@ -1,377 +0,0 @@
-/**
- * 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

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

package/src/link/createLink.ts

@@ -1,182 +0,0 @@
-/**
- * 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

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