@proyecto-viviana/solidaria 0.2.2 → 0.2.3

package/src/utils/reactivity.ts

@@ -0,0 +1,36 @@
+/**
+ * Reactivity utilities for Solidaria
+ *
+ * Provides type-safe utilities for working with SolidJS reactivity patterns.
+ */
+
+import { Accessor } from 'solid-js';
+
+/**
+ * A value that may be either a raw value or an accessor function.
+ * This is a common pattern in SolidJS for props that may be reactive.
+ */
+export type MaybeAccessor<T> = T | Accessor<T>;
+
+/**
+ * Unwraps a MaybeAccessor to get the underlying value.
+ * If the input is a function, it calls it to get the value.
+ * Otherwise, it returns the value directly.
+ *
+ * @param value - The value or accessor to unwrap.
+ */
+export function access<T>(value: MaybeAccessor<T>): T {
+  return typeof value === 'function' ? (value as Accessor<T>)() : value;
+}
+
+/**
+ * A value that may be undefined or an accessor that returns the value or undefined.
+ */
+export type MaybeAccessorValue<T> = T | undefined | Accessor<T | undefined>;
+
+/**
+ * Checks if a value is an accessor function.
+ */
+export function isAccessor<T>(value: MaybeAccessor<T>): value is Accessor<T> {
+  return typeof value === 'function';
+}

package/src/utils/textSelection.ts

@@ -0,0 +1,114 @@
+/**
+ * Text selection management utilities.
+ * Based on @react-aria/interactions textSelection utilities.
+ *
+ * On iOS, long press triggers text selection. The only way to prevent this
+ * is to set user-select: none on the entire page. On other platforms,
+ * we can just set it on the target element.
+ */
+
+import { isIOS } from './platform';
+import { getOwnerDocument } from './dom';
+
+type State = 'default' | 'disabled' | 'restoring';
+
+// Global state to manage text selection across multiple press interactions
+let state: State = 'default';
+let savedUserSelect = '';
+let modifiedElementMap = new WeakMap<HTMLElement, string>();
+
+/**
+ * Disables text selection on the page or element during press.
+ * On iOS, applies to the entire document. On other platforms, just the target.
+ */
+export function disableTextSelection(target?: HTMLElement): void {
+  if (isIOS()) {
+    // iOS requires disabling selection on the entire page
+    if (state === 'default') {
+      const documentElement = getOwnerDocument(target).documentElement;
+      savedUserSelect = documentElement.style.webkitUserSelect;
+      documentElement.style.webkitUserSelect = 'none';
+    }
+    state = 'disabled';
+  } else if (target) {
+    // On other platforms, just disable on the target
+    const element = target as HTMLElement;
+    if (!modifiedElementMap.has(element)) {
+      modifiedElementMap.set(element, element.style.userSelect);
+      element.style.userSelect = 'none';
+    }
+  }
+}
+
+/**
+ * Restores text selection after press ends.
+ * On iOS, waits 300ms to avoid selection appearing during tap.
+ */
+export function restoreTextSelection(target?: HTMLElement): void {
+  if (isIOS()) {
+    // Don't restore if another press is active
+    if (state !== 'disabled') {
+      return;
+    }
+
+    state = 'restoring';
+
+    // Wait for iOS to finish any pending selection actions
+    // 300ms is the iOS long-press delay
+    setTimeout(() => {
+      // Use runAfterTransition to avoid CSS recomputation during animation
+      runAfterTransition(() => {
+        // Only restore if still in 'restoring' state (no new press started)
+        if (state === 'restoring') {
+          const documentElement = getOwnerDocument(target).documentElement;
+          if (savedUserSelect) {
+            documentElement.style.webkitUserSelect = savedUserSelect;
+          } else {
+            documentElement.style.removeProperty('-webkit-user-select');
+          }
+          savedUserSelect = '';
+          state = 'default';
+        }
+      });
+    }, 300);
+  } else if (target) {
+    // On other platforms, restore immediately
+    const element = target as HTMLElement;
+    const savedValue = modifiedElementMap.get(element);
+    if (savedValue !== undefined) {
+      if (savedValue) {
+        element.style.userSelect = savedValue;
+      } else {
+        element.style.removeProperty('user-select');
+      }
+      modifiedElementMap.delete(element);
+    }
+  }
+}
+
+// Tracks pending transitions for runAfterTransition
+const pendingTransitions = new Set<() => void>();
+let transitionTimeout: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * Runs a callback after CSS transitions complete.
+ * Batches multiple callbacks to avoid unnecessary layout thrashing.
+ */
+function runAfterTransition(callback: () => void): void {
+  // If we haven't started tracking transitions, run immediately
+  pendingTransitions.add(callback);
+
+  // Debounce - wait for any transitions to settle
+  if (transitionTimeout != null) {
+    clearTimeout(transitionTimeout);
+  }
+
+  transitionTimeout = setTimeout(() => {
+    // Run all pending callbacks
+    for (const cb of pendingTransitions) {
+      cb();
+    }
+    pendingTransitions.clear();
+    transitionTimeout = null;
+  }, 0);
+}

package/src/visually-hidden/createVisuallyHidden.ts

@@ -0,0 +1,124 @@
+/**
+ * createVisuallyHidden hook for solidaria
+ *
+ * Provides styles and props to visually hide content while keeping it
+ * accessible to screen readers.
+ *
+ * Port of react-aria's useVisuallyHidden.
+ */
+
+import { type Accessor, type JSX, createMemo, createSignal } from 'solid-js';
+import { createFocusWithin } from '../interactions/createFocusWithin';
+import { access, type MaybeAccessor } from '../utils';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaVisuallyHiddenProps {
+  /** Inline styles to merge with the visually hidden styles. */
+  style?: JSX.CSSProperties;
+  /** Whether the element should become visible when focused (e.g., skip links). */
+  isFocusable?: boolean;
+}
+
+export interface VisuallyHiddenAria {
+  /** Props to spread on the visually hidden element. */
+  visuallyHiddenProps: Accessor<JSX.HTMLAttributes<HTMLElement>>;
+}
+
+// ============================================
+// STYLES
+// ============================================
+
+/**
+ * CSS styles that visually hide an element while keeping it accessible.
+ * These styles ensure the element is read by screen readers but not visible on screen.
+ */
+export const visuallyHiddenStyles: JSX.CSSProperties = {
+  border: '0',
+  clip: 'rect(0 0 0 0)',
+  'clip-path': 'inset(50%)',
+  height: '1px',
+  margin: '-1px',
+  overflow: 'hidden',
+  padding: '0',
+  position: 'absolute',
+  width: '1px',
+  'white-space': 'nowrap',
+};
+
+// ============================================
+// HOOK
+// ============================================
+
+/**
+ * Provides props for an element that hides its children visually
+ * but keeps content visible to assistive technology.
+ *
+ * @example
+ * ```tsx
+ * function SkipLink() {
+ *   let ref: HTMLAnchorElement | undefined;
+ *   const { visuallyHiddenProps } = createVisuallyHidden({ isFocusable: true });
+ *
+ *   return (
+ *     <a
+ *       ref={ref}
+ *       href="#main-content"
+ *       {...visuallyHiddenProps()}
+ *     >
+ *       Skip to main content
+ *     </a>
+ *   );
+ * }
+ *
+ * // For content that should always be hidden
+ * function ScreenReaderOnly(props: ParentProps) {
+ *   const { visuallyHiddenProps } = createVisuallyHidden();
+ *
+ *   return (
+ *     <span {...visuallyHiddenProps()}>
+ *       {props.children}
+ *     </span>
+ *   );
+ * }
+ * ```
+ */
+export function createVisuallyHidden(
+  props: MaybeAccessor<AriaVisuallyHiddenProps> = {}
+): VisuallyHiddenAria {
+  const [isFocused, setIsFocused] = createSignal(false);
+
+  const isFocusable = () => access(props).isFocusable ?? false;
+  const style = () => access(props).style;
+
+  // Track focus within for focusable visually hidden elements
+  const { focusWithinProps } = createFocusWithin({
+    get isDisabled() {
+      return !isFocusable();
+    },
+    onFocusWithinChange: (val: boolean) => setIsFocused(val),
+  });
+
+  // Compute combined styles
+  const combinedStyles = createMemo<JSX.CSSProperties>(() => {
+    if (isFocused()) {
+      // If focused, show the element (for skip links, etc.)
+      return style() ?? {};
+    } else if (style()) {
+      return { ...visuallyHiddenStyles, ...style() };
+    } else {
+      return visuallyHiddenStyles;
+    }
+  });
+
+  const visuallyHiddenProps = createMemo<JSX.HTMLAttributes<HTMLElement>>(() => ({
+    ...focusWithinProps,
+    style: combinedStyles(),
+  }));
+
+  return {
+    visuallyHiddenProps,
+  };
+}

package/src/visually-hidden/index.ts

@@ -0,0 +1,6 @@
+export {
+  createVisuallyHidden,
+  visuallyHiddenStyles,
+  type AriaVisuallyHiddenProps,
+  type VisuallyHiddenAria,
+} from './createVisuallyHidden';