@proyecto-viviana/solidaria 0.2.2 → 0.2.4

package/src/popover/createOverlayPosition.ts

@@ -0,0 +1,356 @@
+/**
+ * Handles positioning overlays like popovers and menus relative to a trigger
+ * element, and updating the position when the window resizes.
+ *
+ * Ported from @react-aria/overlays useOverlayPosition.
+ */
+
+import { createEffect, createSignal, onCleanup, type JSX } from 'solid-js';
+import {
+  calculatePosition,
+  getRect,
+  type Placement,
+  type PlacementAxis,
+  type PositionResult,
+} from './calculatePosition';
+
+export interface PositionProps {
+  /**
+   * The placement of the element with respect to its anchor element.
+   * @default 'bottom'
+   */
+  placement?: Placement;
+  /**
+   * The placement padding that should be applied between the element and its
+   * surrounding container.
+   * @default 12
+   */
+  containerPadding?: number;
+  /**
+   * The additional offset applied along the main axis between the element and its
+   * anchor element.
+   * @default 0
+   */
+  offset?: number;
+  /**
+   * The additional offset applied along the cross axis between the element and its
+   * anchor element.
+   * @default 0
+   */
+  crossOffset?: number;
+  /**
+   * Whether the element should flip its orientation (e.g. top to bottom or left to right) when
+   * there is insufficient room for it to render completely.
+   * @default true
+   */
+  shouldFlip?: boolean;
+  /** Whether the overlay is currently open. */
+  isOpen?: boolean;
+}
+
+export interface AriaPositionProps extends PositionProps {
+  /**
+   * Cross size of the overlay arrow in pixels.
+   * @default 0
+   */
+  arrowSize?: number;
+  /**
+   * Element that that serves as the positioning boundary.
+   * @default document.body
+   */
+  boundaryElement?: Element;
+  /**
+   * The ref for the element which the overlay positions itself with respect to.
+   */
+  targetRef: () => Element | null;
+  /**
+   * The ref for the overlay element.
+   */
+  overlayRef: () => Element | null;
+  /**
+   * The ref for the arrow element.
+   */
+  arrowRef?: () => Element | null;
+  /**
+   * A ref for the scrollable region within the overlay.
+   * @default overlayRef
+   */
+  scrollRef?: () => Element | null;
+  /**
+   * Whether the overlay should update its position automatically.
+   * @default true
+   */
+  shouldUpdatePosition?: boolean;
+  /** Handler that is called when the overlay should close. */
+  onClose?: (() => void) | null;
+  /**
+   * The maxHeight specified for the overlay element.
+   * By default, it will take all space up to the current viewport height.
+   */
+  maxHeight?: number;
+  /**
+   * The minimum distance the arrow's edge should be from the edge of the overlay element.
+   * @default 0
+   */
+  arrowBoundaryOffset?: number;
+}
+
+export interface PositionAria {
+  /** Props for the overlay container element. */
+  overlayProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the overlay tip arrow if any. */
+  arrowProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Placement of the overlay with respect to the overlay trigger. */
+  placement: () => PlacementAxis | null;
+  /** The origin of the target in the overlay's coordinate system. Useful for animations. */
+  triggerAnchorPoint: () => { x: number; y: number } | null;
+  /** Updates the position of the overlay. */
+  updatePosition: () => void;
+}
+
+const visualViewport = typeof document !== 'undefined' ? window.visualViewport : null;
+
+function translateRTL(position: string, direction: string): string {
+  if (direction === 'rtl') {
+    return position.replace('start', 'right').replace('end', 'left');
+  }
+  return position.replace('start', 'left').replace('end', 'right');
+}
+
+/**
+ * Handles positioning overlays like popovers and menus relative to a trigger
+ * element, and updating the position when the window resizes.
+ */
+export function createOverlayPosition(props: AriaPositionProps): PositionAria {
+  const direction = 'ltr'; // TODO: get from locale context
+
+  const arrowSize = () => props.arrowSize ?? 0;
+  const targetRef = () => props.targetRef();
+  const overlayRef = () => props.overlayRef();
+  const arrowRef = () => props.arrowRef?.() ?? null;
+  const scrollRef = () => props.scrollRef?.() ?? overlayRef();
+  const placement = () => (props.placement ?? 'bottom') as Placement;
+  const containerPadding = () => props.containerPadding ?? 12;
+  const shouldFlip = () => props.shouldFlip ?? true;
+  const boundaryElement = () =>
+    props.boundaryElement ?? (typeof document !== 'undefined' ? document.body : null);
+  const offset = () => props.offset ?? 0;
+  const crossOffset = () => props.crossOffset ?? 0;
+  const shouldUpdatePosition = () => props.shouldUpdatePosition ?? true;
+  const isOpen = () => props.isOpen ?? true;
+  const onClose = () => props.onClose;
+  const maxHeight = () => props.maxHeight;
+  const arrowBoundaryOffset = () => props.arrowBoundaryOffset ?? 0;
+
+  const [position, setPosition] = createSignal<PositionResult | null>(null);
+
+  // Track the last scale to freeze overlay during pinch zoom
+  let lastScale = visualViewport?.scale;
+
+  createEffect(() => {
+    if (isOpen()) {
+      lastScale = visualViewport?.scale;
+    }
+  });
+
+  const updatePosition = () => {
+    const overlayNode = overlayRef();
+    const targetNode = targetRef();
+    const boundary = boundaryElement();
+
+    if (!shouldUpdatePosition() || !isOpen() || !overlayNode || !targetNode || !boundary) {
+      return;
+    }
+
+    if (visualViewport?.scale !== lastScale) {
+      return;
+    }
+
+    const scrollNode = scrollRef();
+    const arrowNode = arrowRef();
+
+    // Reset overlay's previous max height
+    const overlay = overlayNode as HTMLElement;
+    if (!maxHeight() && overlayNode) {
+      overlay.style.top = '0px';
+      overlay.style.bottom = '';
+      overlay.style.maxHeight = (window.visualViewport?.height ?? window.innerHeight) + 'px';
+    }
+
+    const result = calculatePosition({
+      placement: translateRTL(placement(), direction) as Placement,
+      overlayNode,
+      targetNode,
+      scrollNode: scrollNode || overlayNode,
+      padding: containerPadding(),
+      shouldFlip: shouldFlip(),
+      boundaryElement: boundary,
+      offset: offset(),
+      crossOffset: crossOffset(),
+      maxHeight: maxHeight(),
+      arrowSize: arrowSize() ?? (arrowNode ? getRect(arrowNode, true).width : 0),
+      arrowBoundaryOffset: arrowBoundaryOffset(),
+    });
+
+    if (!result.position) {
+      return;
+    }
+
+    // Apply styles directly for immediate positioning
+    overlay.style.top = '';
+    overlay.style.bottom = '';
+    overlay.style.left = '';
+    overlay.style.right = '';
+
+    Object.keys(result.position).forEach((key) => {
+      (overlay.style as any)[key] = (result.position as any)[key] + 'px';
+    });
+    overlay.style.maxHeight = result.maxHeight != null ? result.maxHeight + 'px' : '';
+
+    setPosition(result);
+  };
+
+  // Update position when dependencies change
+  createEffect(() => {
+    // Track all dependencies
+    shouldUpdatePosition();
+    placement();
+    overlayRef();
+    targetRef();
+    arrowRef();
+    scrollRef();
+    containerPadding();
+    shouldFlip();
+    boundaryElement();
+    offset();
+    crossOffset();
+    isOpen();
+    maxHeight();
+    arrowBoundaryOffset();
+    arrowSize();
+
+    updatePosition();
+  });
+
+  // Update position on window resize
+  createEffect(() => {
+    if (!isOpen()) return;
+
+    const handleResize = () => updatePosition();
+    window.addEventListener('resize', handleResize, false);
+
+    onCleanup(() => {
+      window.removeEventListener('resize', handleResize, false);
+    });
+  });
+
+  // Update position when overlay changes size using ResizeObserver
+  createEffect(() => {
+    const overlayNode = overlayRef();
+    if (!overlayNode || !isOpen()) return;
+
+    const resizeObserver = new ResizeObserver(() => updatePosition());
+    resizeObserver.observe(overlayNode);
+
+    onCleanup(() => {
+      resizeObserver.disconnect();
+    });
+  });
+
+  // Update position when target changes size
+  createEffect(() => {
+    const targetNode = targetRef();
+    if (!targetNode || !isOpen()) return;
+
+    const resizeObserver = new ResizeObserver(() => updatePosition());
+    resizeObserver.observe(targetNode);
+
+    onCleanup(() => {
+      resizeObserver.disconnect();
+    });
+  });
+
+  // Handle visual viewport resize (for iOS virtual keyboard)
+  createEffect(() => {
+    if (!isOpen()) return;
+
+    let timeout: ReturnType<typeof setTimeout>;
+    let isResizing = false;
+
+    const onResize = () => {
+      isResizing = true;
+      clearTimeout(timeout);
+      timeout = setTimeout(() => {
+        isResizing = false;
+      }, 500);
+      updatePosition();
+    };
+
+    const onScroll = () => {
+      if (isResizing) {
+        onResize();
+      }
+    };
+
+    visualViewport?.addEventListener('resize', onResize);
+    visualViewport?.addEventListener('scroll', onScroll);
+
+    onCleanup(() => {
+      visualViewport?.removeEventListener('resize', onResize);
+      visualViewport?.removeEventListener('scroll', onScroll);
+      clearTimeout(timeout);
+    });
+  });
+
+  // Close on scroll (when scrolling a parent of the trigger)
+  createEffect(() => {
+    const targetNode = targetRef();
+    const closeHandler = onClose();
+    if (!targetNode || !isOpen() || !closeHandler) return;
+
+    const handleScroll = (e: Event) => {
+      const target = e.target as Element;
+      // Don't close if scrolling within the overlay
+      if (overlayRef()?.contains(target)) return;
+      // Close if scrolling a parent of the target (but not body/html)
+      if (
+        target !== document.body &&
+        target !== document.documentElement &&
+        target.contains(targetNode)
+      ) {
+        closeHandler();
+      }
+    };
+
+    document.addEventListener('scroll', handleScroll, true);
+
+    onCleanup(() => {
+      document.removeEventListener('scroll', handleScroll, true);
+    });
+  });
+
+  return {
+    overlayProps: {
+      style: {
+        position: position() ? 'absolute' : 'fixed',
+        top: !position() ? 0 : undefined,
+        left: !position() ? 0 : undefined,
+        'z-index': 100000,
+        'max-height': position()?.maxHeight ?? '100vh',
+      } as JSX.CSSProperties,
+    },
+    placement: () => position()?.placement ?? null,
+    triggerAnchorPoint: () => position()?.triggerAnchorPoint ?? null,
+    arrowProps: {
+      'aria-hidden': 'true',
+      role: 'presentation',
+      style: {
+        left: position()?.arrowOffsetLeft != null ? `${position()!.arrowOffsetLeft}px` : undefined,
+        top: position()?.arrowOffsetTop != null ? `${position()!.arrowOffsetTop}px` : undefined,
+      } as JSX.CSSProperties,
+    },
+    updatePosition,
+  };
+}
+
+export { type Placement, type PlacementAxis } from './calculatePosition';

package/src/popover/createPopover.ts

@@ -0,0 +1,170 @@
+/**
+ * Provides the behavior and accessibility implementation for a popover component.
+ * A popover is an overlay element positioned relative to a trigger.
+ *
+ * Ported from @react-aria/overlays usePopover.
+ */
+
+import { createEffect, onCleanup, type JSX } from 'solid-js';
+import { createOverlay } from '../overlays/createOverlay';
+import {
+  createOverlayPosition,
+  type AriaPositionProps,
+  type PlacementAxis,
+} from './createOverlayPosition';
+import { createPreventScroll } from '../overlays/createPreventScroll';
+import { ariaHideOutside, keepVisible } from '../overlays/ariaHideOutside';
+import { mergeProps } from '../utils/mergeProps';
+
+export interface OverlayTriggerState {
+  /** Whether the overlay is currently open. */
+  isOpen: () => boolean;
+  /** Opens the overlay. */
+  open: () => void;
+  /** Closes the overlay. */
+  close: () => void;
+  /** Toggles the overlay's open state. */
+  toggle: () => void;
+}
+
+export interface AriaPopoverProps
+  extends Omit<AriaPositionProps, 'isOpen' | 'onClose' | 'targetRef' | 'overlayRef'> {
+  /**
+   * The ref for the element which the popover positions itself with respect to.
+   */
+  triggerRef: () => Element | null;
+  /**
+   * The ref for the popover element.
+   */
+  popoverRef: () => Element | null;
+  /** A ref for the popover arrow element. */
+  arrowRef?: () => Element | null;
+  /**
+   * An optional ref for a group of popovers, e.g. submenus.
+   * When provided, this element is used to detect outside interactions
+   * and hiding elements from assistive technologies instead of the popoverRef.
+   */
+  groupRef?: () => Element | null;
+  /**
+   * Whether the popover is non-modal, i.e. elements outside the popover may be
+   * interacted with by assistive technologies.
+   *
+   * Most popovers should not use this option as it may negatively impact the screen
+   * reader experience. Only use with components such as combobox, which are designed
+   * to handle this situation carefully.
+   */
+  isNonModal?: boolean;
+  /**
+   * Whether pressing the escape key to close the popover should be disabled.
+   *
+   * Most popovers should not use this option. When set to true, an alternative
+   * way to close the popover with a keyboard must be provided.
+   *
+   * @default false
+   */
+  isKeyboardDismissDisabled?: boolean;
+  /**
+   * When user interacts with the argument element outside of the popover ref,
+   * return true if onClose should be called. This gives you a chance to filter
+   * out interaction with elements that should not dismiss the popover.
+   * By default, onClose will always be called on interaction outside the popover ref.
+   */
+  shouldCloseOnInteractOutside?: (element: Element) => boolean;
+  /**
+   * The type of trigger that opened the popover.
+   * Used for submenu detection.
+   */
+  trigger?: string;
+}
+
+export interface PopoverAria {
+  /** Props for the popover element. */
+  popoverProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the popover tip arrow if any. */
+  arrowProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props to apply to the underlay element, if any. */
+  underlayProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Placement of the popover with respect to the trigger. */
+  placement: () => PlacementAxis | null;
+  /** The origin of the target in the overlay's coordinate system. Useful for animations. */
+  triggerAnchorPoint: () => { x: number; y: number } | null;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a popover component.
+ * A popover is an overlay element positioned relative to a trigger.
+ */
+export function createPopover(
+  props: AriaPopoverProps,
+  state: OverlayTriggerState
+): PopoverAria {
+  const triggerRef = () => props.triggerRef();
+  const popoverRef = () => props.popoverRef();
+  const groupRef = () => props.groupRef?.() ?? null;
+  const isNonModal = () => props.isNonModal ?? false;
+  const isKeyboardDismissDisabled = () => props.isKeyboardDismissDisabled ?? false;
+  const shouldCloseOnInteractOutside = props.shouldCloseOnInteractOutside;
+  const isSubmenu = () => props.trigger === 'SubmenuTrigger';
+
+  // Overlay behavior (dismiss handling)
+  const { overlayProps, underlayProps } = createOverlay(
+    {
+      isOpen: state.isOpen(),
+      onClose: state.close,
+      shouldCloseOnBlur: true,
+      isDismissable: !isNonModal() || isSubmenu(),
+      isKeyboardDismissDisabled: isKeyboardDismissDisabled(),
+      shouldCloseOnInteractOutside,
+    },
+    () => groupRef() ?? popoverRef()
+  );
+
+  // Overlay positioning
+  const {
+    overlayProps: positionProps,
+    arrowProps,
+    placement,
+    triggerAnchorPoint,
+  } = createOverlayPosition({
+    ...props,
+    targetRef: triggerRef,
+    overlayRef: popoverRef,
+    isOpen: state.isOpen(),
+    onClose: isNonModal() && !isSubmenu() ? state.close : null,
+  });
+
+  // Prevent scroll when modal popover is open
+  createPreventScroll({
+    isDisabled: isNonModal() || !state.isOpen(),
+  });
+
+  // Aria-hide outside elements
+  createEffect(() => {
+    if (state.isOpen() && popoverRef()) {
+      const element = groupRef() ?? popoverRef();
+      if (!element) return;
+
+      let cleanup: (() => void) | undefined;
+
+      if (isNonModal()) {
+        cleanup = keepVisible(element);
+      } else {
+        cleanup = ariaHideOutside([element], { shouldUseInert: true });
+      }
+
+      onCleanup(() => {
+        cleanup?.();
+      });
+    }
+  });
+
+  return {
+    popoverProps: mergeProps(overlayProps, positionProps),
+    arrowProps,
+    underlayProps,
+    placement,
+    triggerAnchorPoint,
+  };
+}
+
+export { type PlacementAxis } from './createOverlayPosition';

package/src/popover/index.ts

@@ -0,0 +1,24 @@
+// Popover
+export {
+  createPopover,
+  type AriaPopoverProps,
+  type PopoverAria,
+  type OverlayTriggerState,
+} from './createPopover';
+
+// Overlay Position
+export {
+  createOverlayPosition,
+  type AriaPositionProps,
+  type PositionProps,
+  type PositionAria,
+} from './createOverlayPosition';
+
+// Position calculation utilities
+export {
+  calculatePosition,
+  type Placement,
+  type PlacementAxis,
+  type PositionOpts,
+  type PositionResult,
+} from './calculatePosition';

package/src/progress/createProgressBar.ts

@@ -0,0 +1,128 @@
+/**
+ * ProgressBar hook for Solidaria
+ *
+ * Provides the accessibility implementation for a progress bar component.
+ * Progress bars show either determinate or indeterminate progress of an operation
+ * over time.
+ *
+ * This is a 1:1 port of @react-aria/progress's useProgressBar hook.
+ */
+
+import { createLabel } from '../label/createLabel';
+import { mergeProps } from '../utils/mergeProps';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { type MaybeAccessor, access } from '../utils/reactivity';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaProgressBarProps {
+  /** The current value (controlled). */
+  value?: number;
+  /** The smallest value allowed for the input. @default 0 */
+  minValue?: number;
+  /** The largest value allowed for the input. @default 100 */
+  maxValue?: number;
+  /** The content to display as the value's label (e.g. 1 of 4). */
+  valueLabel?: string;
+  /** Whether presentation is indeterminate when progress isn't known. */
+  isIndeterminate?: boolean;
+  /** The display format of the value label. */
+  formatOptions?: Intl.NumberFormatOptions;
+  /** The content to display as the label. */
+  label?: string;
+  /** An accessibility label for this item. */
+  '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;
+  /** Identifies the element (or elements) that provide a detailed, extended description for the object. */
+  'aria-details'?: string;
+}
+
+export interface ProgressBarAria {
+  /** Props for the progress bar container element. */
+  progressBarProps: Record<string, unknown>;
+  /** Props for the progress bar's visual label element (if any). */
+  labelProps: Record<string, unknown>;
+}
+
+// ============================================
+// UTILITIES
+// ============================================
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the accessibility implementation for a progress bar component.
+ * Progress bars show either determinate or indeterminate progress of an operation
+ * over time.
+ */
+export function createProgressBar(
+  props: MaybeAccessor<AriaProgressBarProps> = {}
+): ProgressBarAria {
+  const getProps = () => access(props);
+
+  // Create label handling
+  const { labelProps, fieldProps } = createLabel({
+    get label() { return getProps().label; },
+    get 'aria-label'() { return getProps()['aria-label']; },
+    get 'aria-labelledby'() { return getProps()['aria-labelledby']; },
+    // Progress bar is not an HTML input element so it
+    // shouldn't be labeled by a <label> element.
+    labelElementType: 'span',
+  });
+
+  // Build progress bar props
+  const getProgressBarProps = (): Record<string, unknown> => {
+    const p = getProps();
+    const value = p.value ?? 0;
+    const minValue = p.minValue ?? 0;
+    const maxValue = p.maxValue ?? 100;
+    const isIndeterminate = p.isIndeterminate ?? false;
+    const formatOptions = p.formatOptions ?? { style: 'percent' as const };
+
+    const clampedValue = clamp(value, minValue, maxValue);
+    const percentage = (clampedValue - minValue) / (maxValue - minValue);
+
+    // Format value label
+    let valueLabel = p.valueLabel;
+    if (!isIndeterminate && !valueLabel) {
+      const valueToFormat = formatOptions.style === 'percent' ? percentage : clampedValue;
+      try {
+        const formatter = new Intl.NumberFormat(undefined, formatOptions);
+        valueLabel = formatter.format(valueToFormat);
+      } catch {
+        // Fallback if formatting fails
+        valueLabel = `${Math.round(percentage * 100)}%`;
+      }
+    }
+
+    const domProps = filterDOMProps(p as Record<string, unknown>, { labelable: true });
+
+    return mergeProps(domProps, fieldProps as Record<string, unknown>, {
+      'aria-valuenow': isIndeterminate ? undefined : clampedValue,
+      'aria-valuemin': minValue,
+      'aria-valuemax': maxValue,
+      'aria-valuetext': isIndeterminate ? undefined : valueLabel,
+      role: 'progressbar',
+    });
+  };
+
+  return {
+    get progressBarProps() {
+      return getProgressBarProps();
+    },
+    get labelProps() {
+      return labelProps as Record<string, unknown>;
+    },
+  };
+}

package/src/progress/index.ts

@@ -0,0 +1,5 @@
+export {
+  createProgressBar,
+  type AriaProgressBarProps,
+  type ProgressBarAria,
+} from './createProgressBar';