@proyecto-viviana/solidaria 0.0.1 → 0.0.2

package/src/interactions/index.ts

@@ -0,0 +1,45 @@
+// Press interactions
+export { createPress, type CreatePressProps, type PressResult } from './createPress';
+export { PressEvent, type IPressEvent, type PointerType, type PressEventType } from './PressEvent';
+
+// Focus interactions
+export { createFocus, type CreateFocusProps, type FocusResult, type FocusEvents } from './createFocus';
+export {
+  createFocusWithin,
+  type FocusWithinProps,
+  type FocusWithinResult,
+} from './createFocusWithin';
+export {
+  createFocusable,
+  FocusableContext,
+  type CreateFocusableProps,
+  type FocusableResult,
+  type FocusableContextValue,
+  type FocusableProviderProps,
+  type FocusableProps,
+  type FocusableDOMProps,
+} from './createFocusable';
+export { FocusableProvider } from './FocusableProvider';
+export {
+  createFocusRing,
+  type FocusRingProps,
+  type FocusRingResult,
+} from './createFocusRing';
+
+// Hover interactions
+export {
+  createHover,
+  type CreateHoverProps,
+  type HoverResult,
+  type HoverEvent,
+  type HoverEvents,
+} from './createHover';
+
+// Keyboard interactions
+export {
+  createKeyboard,
+  type CreateKeyboardProps,
+  type KeyboardResult,
+  type KeyboardEvents,
+  type KeyboardEvent,
+} from './createKeyboard';

package/src/label/createField.ts

@@ -0,0 +1,145 @@
+/**
+ * Field hook for Solidaria
+ *
+ * Provides the accessibility implementation for input fields.
+ * Fields accept user input, gain context from their label, and may display
+ * a description or error message.
+ *
+ * This is a 1:1 port of @react-aria/label's useField hook.
+ */
+
+import { JSX } from 'solid-js';
+import { createId } from '../ssr';
+import { createLabel, type LabelAriaProps, type LabelAria, type AriaLabelingProps, type DOMProps } from './createLabel';
+import { mergeProps } from '../utils/mergeProps';
+import { type MaybeAccessor, access } from '../utils/reactivity';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface HelpTextProps {
+  /** A description for the field. Provides a hint such as specific requirements for what to choose. */
+  description?: JSX.Element;
+  /** An error message for the field. */
+  errorMessage?: JSX.Element | ((validation: ValidationResult) => JSX.Element);
+}
+
+export interface ValidationResult {
+  /** Whether the input value is invalid. */
+  isInvalid: boolean;
+  /** The current error messages for the input if it is invalid, otherwise an empty array. */
+  validationErrors: string[];
+  /** The native validity state for the input. */
+  validationDetails: ValidityState;
+}
+
+export interface Validation<T> {
+  /** Whether the input value is invalid. */
+  isInvalid?: boolean;
+  /** Whether the input is required before form submission. */
+  isRequired?: boolean;
+  /** A function that returns an error message if a given value is invalid. */
+  validate?: (value: T) => string | string[] | true | null | undefined;
+}
+
+export interface AriaFieldProps extends LabelAriaProps, HelpTextProps, Omit<Validation<any>, 'isRequired'> {}
+
+export interface FieldAria extends LabelAria {
+  /** Props for the description element, if any. */
+  descriptionProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the error message element, if any. */
+  errorMessageProps: JSX.HTMLAttributes<HTMLElement>;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the accessibility implementation for input fields.
+ * Fields accept user input, gain context from their label, and may display
+ * a description or error message.
+ *
+ * @param props - Props for the Field.
+ */
+export function createField(props: MaybeAccessor<AriaFieldProps>): FieldAria {
+  const getProps = () => access(props);
+
+  const { labelProps, fieldProps: baseLabelFieldProps } = createLabel(props);
+
+  // Generate IDs for description and error message
+  const descriptionId = createId();
+  const errorMessageId = createId();
+
+  const getDescriptionProps = (): FieldAria['descriptionProps'] => {
+    const { description, errorMessage, isInvalid } = getProps();
+
+    // Only include ID if description exists or there's an error message that might be shown
+    if (!description && !errorMessage && !isInvalid) {
+      return {};
+    }
+
+    return {
+      id: descriptionId,
+    };
+  };
+
+  const getErrorMessageProps = (): FieldAria['errorMessageProps'] => {
+    const { errorMessage, isInvalid } = getProps();
+
+    // Only include ID if there's an error message and the field is invalid
+    if (!errorMessage && !isInvalid) {
+      return {};
+    }
+
+    return {
+      id: errorMessageId,
+    };
+  };
+
+  const getFieldProps = (): AriaLabelingProps & DOMProps => {
+    const { description, errorMessage, isInvalid } = getProps();
+
+    const describedByIds: string[] = [];
+
+    // Add description ID if description exists
+    if (description) {
+      describedByIds.push(descriptionId);
+    }
+
+    // Add error message ID if field is invalid and error message exists
+    // Use aria-describedby for error message because aria-errormessage is unsupported
+    // using VoiceOver or NVDA. See https://github.com/adobe/react-spectrum/issues/1346#issuecomment-740136268
+    if (isInvalid && errorMessage) {
+      describedByIds.push(errorMessageId);
+    }
+
+    // Add any existing aria-describedby from props
+    const existingDescribedBy = getProps()['aria-describedby'];
+    if (existingDescribedBy) {
+      describedByIds.push(existingDescribedBy);
+    }
+
+    const ariaDescribedBy = describedByIds.length > 0 ? describedByIds.join(' ') : undefined;
+
+    return mergeProps(baseLabelFieldProps, {
+      'aria-describedby': ariaDescribedBy,
+    }) as AriaLabelingProps & DOMProps;
+  };
+
+  return {
+    get labelProps() {
+      return labelProps;
+    },
+    get fieldProps() {
+      return getFieldProps();
+    },
+    get descriptionProps() {
+      return getDescriptionProps();
+    },
+    get errorMessageProps() {
+      return getErrorMessageProps();
+    },
+  };
+}

package/src/label/createLabel.ts

@@ -0,0 +1,116 @@
+/**
+ * Label hook for Solidaria
+ *
+ * Provides the accessibility implementation for labels and their associated elements.
+ * Labels provide context for user inputs.
+ *
+ * This is a 1:1 port of @react-aria/label's useLabel hook.
+ */
+
+import { JSX } from 'solid-js';
+import { createId } from '../ssr';
+import { createLabels } from './createLabels';
+import { type MaybeAccessor, access } from '../utils/reactivity';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaLabelingProps {
+  /** 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;
+  /** Identifies the element (or elements) that provide a detailed, extended description for the object. */
+  'aria-details'?: string;
+}
+
+export interface LabelableProps {
+  /** The content to display as the label. */
+  label?: JSX.Element;
+}
+
+export interface DOMProps {
+  /** The element's unique identifier. */
+  id?: string;
+}
+
+export interface LabelAriaProps extends LabelableProps, DOMProps, AriaLabelingProps {
+  /**
+   * The HTML element used to render the label, e.g. 'label', or 'span'.
+   * @default 'label'
+   */
+  labelElementType?: 'label' | 'span' | 'div';
+}
+
+export interface LabelAria {
+  /** Props to apply to the label container element. */
+  labelProps: JSX.LabelHTMLAttributes<HTMLLabelElement> | JSX.HTMLAttributes<HTMLSpanElement>;
+  /** Props to apply to the field container element being labeled. */
+  fieldProps: AriaLabelingProps & DOMProps;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the accessibility implementation for labels and their associated elements.
+ * Labels provide context for user inputs.
+ *
+ * @param props - The props for labels and fields.
+ */
+export function createLabel(props: MaybeAccessor<LabelAriaProps>): LabelAria {
+  const getProps = () => access(props);
+
+  const id = createId(getProps().id);
+  const labelId = createId();
+
+  const getLabelProps = (): LabelAria['labelProps'] => {
+    const { label, labelElementType = 'label' } = getProps();
+
+    if (!label) {
+      return {};
+    }
+
+    return {
+      id: labelId,
+      ...(labelElementType === 'label' ? { for: id } : {}),
+    };
+  };
+
+  const getFieldProps = (): LabelAria['fieldProps'] => {
+    const {
+      label,
+      'aria-labelledby': ariaLabelledby,
+      'aria-label': ariaLabel,
+    } = getProps();
+
+    let labelledBy = ariaLabelledby;
+
+    if (label) {
+      labelledBy = ariaLabelledby ? `${labelId} ${ariaLabelledby}` : labelId;
+    } else if (!ariaLabelledby && !ariaLabel && process.env.NODE_ENV !== 'production') {
+      console.warn(
+        'If you do not provide a visible label, you must specify an aria-label or aria-labelledby attribute for accessibility'
+      );
+    }
+
+    return createLabels({
+      id,
+      'aria-label': ariaLabel,
+      'aria-labelledby': labelledBy,
+    });
+  };
+
+  return {
+    get labelProps() {
+      return getLabelProps();
+    },
+    get fieldProps() {
+      return getFieldProps();
+    },
+  };
+}

package/src/label/createLabels.ts

@@ -0,0 +1,50 @@
+/**
+ * Labels utility for Solidaria
+ *
+ * Merges aria-label and aria-labelledby into aria-labelledby when both exist.
+ *
+ * This is a 1:1 port of @react-aria/utils's useLabels hook.
+ */
+
+import { createId } from '../ssr';
+import type { AriaLabelingProps, DOMProps } from './createLabel';
+
+/**
+ * Merges aria-label and aria-labelledby into aria-labelledby when both exist.
+ *
+ * @param props - Aria label props.
+ * @param defaultLabel - Default value for aria-label when not present.
+ */
+export function createLabels(
+  props: DOMProps & AriaLabelingProps,
+  defaultLabel?: string
+): DOMProps & AriaLabelingProps {
+  let {
+    id,
+    'aria-label': label,
+    'aria-labelledby': labelledBy,
+  } = props;
+
+  // Generate an ID if not provided
+  id = createId(id);
+
+  // If there is both an aria-label and aria-labelledby,
+  // combine them by pointing to the element itself.
+  if (labelledBy && label) {
+    const ids = new Set([id, ...labelledBy.trim().split(/\s+/)]);
+    labelledBy = [...ids].join(' ');
+  } else if (labelledBy) {
+    labelledBy = labelledBy.trim().split(/\s+/).join(' ');
+  }
+
+  // If no labels are provided, use the default
+  if (!label && !labelledBy && defaultLabel) {
+    label = defaultLabel;
+  }
+
+  return {
+    id,
+    'aria-label': label,
+    'aria-labelledby': labelledBy,
+  };
+}

package/src/label/index.ts

@@ -0,0 +1,19 @@
+export { createLabel } from './createLabel';
+export type {
+  LabelAriaProps,
+  LabelAria,
+  AriaLabelingProps,
+  LabelableProps,
+  DOMProps,
+} from './createLabel';
+
+export { createField } from './createField';
+export type {
+  AriaFieldProps,
+  FieldAria,
+  HelpTextProps,
+  ValidationResult,
+  Validation,
+} from './createField';
+
+export { createLabels } from './createLabels';

package/src/link/createLink.ts

@@ -0,0 +1,176 @@
+/**
+ * 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 - only call user's onClick when not disabled
+    const onClick = (e: MouseEvent) => {
+      // If disabled, prevent navigation and don't call user's onClick
+      if (disabled) {
+        e.preventDefault();
+        return;
+      }
+
+      // 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';

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';