@proyecto-viviana/solidaria 0.2.2 → 0.2.3

package/src/breadcrumbs/createBreadcrumbs.ts

@@ -0,0 +1,196 @@
+/**
+ * Breadcrumbs hooks for Solidaria
+ *
+ * Provides accessibility implementation for breadcrumb navigation.
+ * Port of @react-aria/breadcrumbs.
+ */
+
+import { createLink, type AriaLinkProps, type LinkAria } from '../link';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { mergeProps } from '../utils/mergeProps';
+import { type MaybeAccessor, access } from '../utils/reactivity';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaBreadcrumbsProps {
+  /** Provides a label for the breadcrumbs navigation. */
+  'aria-label'?: string;
+  /** Identifies the element (or elements) that labels the breadcrumbs. */
+  'aria-labelledby'?: string;
+  /** Identifies the element (or elements) that describes the breadcrumbs. */
+  'aria-describedby'?: string;
+  /** Whether the breadcrumbs are disabled. */
+  isDisabled?: boolean;
+}
+
+export interface BreadcrumbsAria {
+  /** Props for the breadcrumbs nav element. */
+  navProps: Record<string, unknown>;
+}
+
+export interface AriaBreadcrumbItemProps extends Omit<AriaLinkProps, 'aria-current'> {
+  /** Whether this is the current/last item in the breadcrumb trail. */
+  isCurrent?: boolean;
+  /** The type of current location for aria-current. @default 'page' */
+  'aria-current'?: 'page' | 'step' | 'location' | 'date' | 'time' | boolean;
+  /** The HTML element type. @default 'a' */
+  elementType?: string;
+}
+
+export interface BreadcrumbItemAria extends LinkAria {
+  /** Props for the breadcrumb item element. */
+  itemProps: Record<string, unknown>;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides accessibility implementation for the breadcrumbs navigation container.
+ */
+export function createBreadcrumbs(
+  props: MaybeAccessor<AriaBreadcrumbsProps> = {}
+): BreadcrumbsAria {
+  const getProps = () => access(props);
+
+  const getNavProps = (): Record<string, unknown> => {
+    const p = getProps();
+
+    // Default aria-label to "Breadcrumbs" if not provided
+    const ariaLabel = p['aria-label'] ?? 'Breadcrumbs';
+
+    return mergeProps(
+      filterDOMProps(p as Record<string, unknown>, { labelable: true }),
+      {
+        'aria-label': ariaLabel,
+      }
+    );
+  };
+
+  return {
+    get navProps() {
+      return getNavProps();
+    },
+  };
+}
+
+/**
+ * Provides accessibility implementation for an individual breadcrumb item.
+ */
+export function createBreadcrumbItem(
+  props: MaybeAccessor<AriaBreadcrumbItemProps> = {}
+): BreadcrumbItemAria {
+  const getProps = () => access(props);
+
+  const isCurrent = () => getProps().isCurrent ?? false;
+  const isDisabled = () => getProps().isDisabled ?? false;
+  const elementType = () => getProps().elementType ?? 'a';
+
+  // Check if element is a heading
+  const isHeading = () => /^h[1-6]$/.test(elementType());
+
+  // Use createLink for base link behavior
+  // Current items are treated as disabled (can't navigate to current page)
+  const { linkProps, isPressed } = createLink({
+    get isDisabled() {
+      return isDisabled() || isCurrent();
+    },
+    get elementType() {
+      return elementType();
+    },
+    get href() {
+      return getProps().href;
+    },
+    get target() {
+      return getProps().target;
+    },
+    get rel() {
+      return getProps().rel;
+    },
+    get onPress() {
+      return getProps().onPress;
+    },
+    get onPressStart() {
+      return getProps().onPressStart;
+    },
+    get onPressEnd() {
+      return getProps().onPressEnd;
+    },
+    get onClick() {
+      return getProps().onClick;
+    },
+    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;
+    },
+    get autoFocus() {
+      return getProps().autoFocus;
+    },
+    get 'aria-label'() {
+      return getProps()['aria-label'];
+    },
+    get 'aria-labelledby'() {
+      return getProps()['aria-labelledby'];
+    },
+    get 'aria-describedby'() {
+      return getProps()['aria-describedby'];
+    },
+  });
+
+  const getItemProps = (): Record<string, unknown> => {
+    const p = getProps();
+    const current = isCurrent();
+
+    // Start with link props (unless it's a heading)
+    let baseProps: Record<string, unknown> = isHeading() ? {} : linkProps;
+
+    // Add aria-current for current page
+    if (current) {
+      const ariaCurrent = p['aria-current'] ?? 'page';
+      baseProps = mergeProps(baseProps, {
+        'aria-current': ariaCurrent,
+      });
+
+      // Adjust tabIndex for current item
+      // If autoFocus is true, we want the item focusable
+      if (p.autoFocus) {
+        baseProps = mergeProps(baseProps, {
+          tabIndex: -1,
+        });
+      }
+    }
+
+    // Add aria-disabled for disabled items
+    if (isDisabled()) {
+      baseProps = mergeProps(baseProps, {
+        'aria-disabled': true,
+      });
+    }
+
+    return baseProps;
+  };
+
+  return {
+    get itemProps() {
+      return getItemProps();
+    },
+    get linkProps() {
+      return linkProps;
+    },
+    isPressed,
+  };
+}

package/src/breadcrumbs/index.ts

@@ -0,0 +1,8 @@
+export {
+  createBreadcrumbs,
+  createBreadcrumbItem,
+  type AriaBreadcrumbsProps,
+  type BreadcrumbsAria,
+  type AriaBreadcrumbItemProps,
+  type BreadcrumbItemAria,
+} from './createBreadcrumbs';

package/src/button/createButton.ts

@@ -0,0 +1,142 @@
+import { Accessor } from 'solid-js';
+import { createPress } from '../interactions';
+import { createFocusable } from '../interactions';
+import { mergeProps, filterDOMProps } from '../utils';
+import type { AriaButtonProps, ButtonAria } from './types';
+
+function isDisabledValue(isDisabled: Accessor<boolean> | boolean | undefined): boolean {
+  if (typeof isDisabled === 'function') {
+    return isDisabled();
+  }
+  return isDisabled ?? false;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a button component.
+ * Handles press interactions across mouse, touch, keyboard and screen readers.
+ *
+ * Based on react-aria's useButton but adapted for SolidJS.
+ *
+ * @example
+ * ```tsx
+ * import { createButton } from 'solidaria';
+ *
+ * function Button(props) {
+ *   let ref;
+ *   const { buttonProps, isPressed } = createButton(props);
+ *
+ *   return (
+ *     <button
+ *       {...buttonProps}
+ *       ref={ref}
+ *       class={isPressed() ? 'pressed' : ''}
+ *     >
+ *       {props.children}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function createButton(props: AriaButtonProps = {}): ButtonAria {
+  const elementType = props.elementType ?? 'button';
+
+  const { pressProps, isPressed } = createPress({
+    isDisabled: props.isDisabled,
+    onPress: props.onPress,
+    onPressStart: props.onPressStart,
+    onPressEnd: props.onPressEnd,
+    onPressUp: props.onPressUp,
+    onPressChange: props.onPressChange,
+    onClick: props.onClick,
+    preventFocusOnPress: props.preventFocusOnPress,
+  });
+
+  const { focusableProps } = createFocusable({
+    isDisabled: props.isDisabled,
+    autoFocus: props.autoFocus,
+    excludeFromTabOrder: props.excludeFromTabOrder,
+  });
+
+  const isNativeButton = elementType === 'button' || elementType === 'input';
+  const isLink = elementType === 'a';
+  const disabled = isDisabledValue(props.isDisabled);
+
+  // Handle allowFocusWhenDisabled - set tabIndex to -1 when disabled but focusable
+  // This allows tooltips to be shown on disabled buttons
+  if (props.allowFocusWhenDisabled && disabled) {
+    (focusableProps as Record<string, unknown>).tabIndex = -1;
+  }
+
+  // Build base props based on element type
+  let additionalProps: Record<string, unknown> = {};
+
+  if (isNativeButton) {
+    additionalProps = {
+      type: props.type ?? 'button',
+      disabled: disabled,
+      // Form-related attributes
+      ...(props.form && { form: props.form }),
+      ...(props.formAction && { formAction: props.formAction }),
+      ...(props.formEncType && { formEncType: props.formEncType }),
+      ...(props.formMethod && { formMethod: props.formMethod }),
+      ...(props.formNoValidate && { formNoValidate: props.formNoValidate }),
+      ...(props.formTarget && { formTarget: props.formTarget }),
+      ...(props.name && { name: props.name }),
+      ...(props.value && { value: props.value }),
+    };
+  } else {
+    // Non-native buttons need role and tabIndex
+    additionalProps = {
+      role: 'button',
+      tabIndex: disabled ? undefined : 0,
+      'aria-disabled': disabled ? true : undefined,
+    };
+
+    if (isLink) {
+      additionalProps.href = props.href;
+      additionalProps.target = props.target;
+      additionalProps.rel = props.rel;
+    }
+  }
+
+  // ARIA attributes
+  const ariaProps: Record<string, unknown> = {};
+
+  if (props['aria-pressed'] !== undefined) {
+    ariaProps['aria-pressed'] = props['aria-pressed'];
+  }
+  if (props['aria-haspopup'] !== undefined) {
+    ariaProps['aria-haspopup'] = props['aria-haspopup'];
+  }
+  if (props['aria-expanded'] !== undefined) {
+    ariaProps['aria-expanded'] = props['aria-expanded'];
+  }
+  if (props['aria-label']) {
+    ariaProps['aria-label'] = props['aria-label'];
+  }
+  if (props['aria-labelledby']) {
+    ariaProps['aria-labelledby'] = props['aria-labelledby'];
+  }
+  if (props['aria-describedby']) {
+    ariaProps['aria-describedby'] = props['aria-describedby'];
+  }
+  if (props['aria-controls']) {
+    ariaProps['aria-controls'] = props['aria-controls'];
+  }
+  if (props['aria-current'] !== undefined) {
+    ariaProps['aria-current'] = props['aria-current'];
+  }
+
+  const buttonProps = mergeProps(
+    filterDOMProps(props as Record<string, unknown>, { labelable: true }),
+    additionalProps,
+    ariaProps,
+    focusableProps as Record<string, unknown>,
+    pressProps as Record<string, unknown>
+  );
+
+  return {
+    buttonProps,
+    isPressed,
+  };
+}

package/src/button/createToggleButton.ts

@@ -0,0 +1,101 @@
+import { Accessor, createSignal } from 'solid-js';
+import { createButton } from './createButton';
+import { mergeProps } from '../utils';
+import type { AriaButtonProps, ButtonAria } from './types';
+import type { PressEvent } from '../interactions';
+
+export interface AriaToggleButtonProps extends Omit<AriaButtonProps, 'aria-pressed'> {
+  /** Whether the button is selected (controlled). */
+  isSelected?: Accessor<boolean> | boolean;
+  /** Handler called when the button's selection state changes. */
+  onChange?: (isSelected: boolean) => void;
+  /** The default selected state (uncontrolled). */
+  defaultSelected?: boolean;
+}
+
+export interface ToggleButtonAria extends ButtonAria {
+  /** Whether the button is currently selected. */
+  isSelected: Accessor<boolean>;
+}
+
+function getSelectedValue(isSelected: Accessor<boolean> | boolean | undefined): boolean {
+  if (typeof isSelected === 'function') {
+    return isSelected();
+  }
+  return isSelected ?? false;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a toggle button component.
+ * Toggle buttons allow users to toggle a selection on or off.
+ *
+ * Based on react-aria's useToggleButton but adapted for SolidJS.
+ *
+ * @example
+ * ```tsx
+ * import { createToggleButton } from 'solidaria';
+ *
+ * function ToggleButton(props) {
+ *   const { buttonProps, isPressed, isSelected } = createToggleButton(props);
+ *
+ *   return (
+ *     <button
+ *       {...buttonProps}
+ *       class={isSelected() ? 'selected' : ''}
+ *       style={{ opacity: isPressed() ? 0.8 : 1 }}
+ *     >
+ *       {props.children}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function createToggleButton(props: AriaToggleButtonProps = {}): ToggleButtonAria {
+  // Handle controlled vs uncontrolled state
+  const isControlled = props.isSelected !== undefined;
+  const [uncontrolledSelected, setUncontrolledSelected] = createSignal(
+    props.defaultSelected ?? false
+  );
+
+  const isSelected = (): boolean => {
+    if (isControlled) {
+      return getSelectedValue(props.isSelected);
+    }
+    return uncontrolledSelected();
+  };
+
+  const toggleSelection = () => {
+    const newValue = !isSelected();
+    if (!isControlled) {
+      setUncontrolledSelected(newValue);
+    }
+    props.onChange?.(newValue);
+  };
+
+  // Create the press handler that toggles selection
+  const onPress = (e: PressEvent) => {
+    toggleSelection();
+    props.onPress?.(e);
+  };
+
+  // Get button props with our custom press handler
+  const { buttonProps: baseButtonProps, isPressed } = createButton(
+    mergeProps(props, {
+      onPress,
+    }) as AriaButtonProps
+  );
+
+  // Create buttonProps with a getter for aria-pressed so it stays reactive
+  const buttonProps = {
+    ...baseButtonProps,
+    get 'aria-pressed'() {
+      return isSelected();
+    },
+  };
+
+  return {
+    buttonProps,
+    isPressed,
+    isSelected,
+  };
+}

package/src/button/index.ts

@@ -0,0 +1,4 @@
+export { createButton } from './createButton';
+export { createToggleButton } from './createToggleButton';
+export type { AriaButtonProps, ButtonAria } from './types';
+export type { AriaToggleButtonProps, ToggleButtonAria } from './createToggleButton';

package/src/button/types.ts

@@ -0,0 +1,78 @@
+import { Accessor } from 'solid-js';
+import { PressEvent } from '../interactions';
+
+export interface AriaButtonProps {
+  /** Whether the button is disabled. */
+  isDisabled?: Accessor<boolean> | boolean;
+  /** Handler called when the press is released over the target. */
+  onPress?: (e: PressEvent) => void;
+  /** Handler called when a press interaction starts. */
+  onPressStart?: (e: PressEvent) => void;
+  /** Handler called when a press interaction ends. */
+  onPressEnd?: (e: PressEvent) => void;
+  /** Handler called when a press is released over the target. */
+  onPressUp?: (e: PressEvent) => void;
+  /** Handler called when the press state changes. */
+  onPressChange?: (isPressed: boolean) => void;
+  /**
+   * A native click handler, useful for form submission.
+   * Note: `onPress` is preferred for cross-device compatibility.
+   */
+  onClick?: (e: MouseEvent) => void;
+  /** Whether the button should not receive focus on press. */
+  preventFocusOnPress?: boolean;
+  /**
+   * Whether to allow focus on the button when it is disabled.
+   * This enables showing tooltips on disabled buttons.
+   * When true, the button gets `tabIndex=-1` instead of being removed from tab order.
+   */
+  allowFocusWhenDisabled?: boolean;
+  /** Whether the element should receive focus on render. */
+  autoFocus?: boolean;
+  /** The HTML element type to use for the button. */
+  elementType?: 'button' | 'a' | 'div' | 'input' | 'span';
+  /** The URL to link to (for anchor elements). */
+  href?: string;
+  /** The target for the link (for anchor elements). */
+  target?: string;
+  /** The rel attribute for the link (for anchor elements). */
+  rel?: string;
+  /** The type attribute for button elements. */
+  type?: 'button' | 'submit' | 'reset';
+  /** Whether the button is in a pressed state (controlled). */
+  'aria-pressed'?: boolean | 'true' | 'false' | 'mixed';
+  /** Whether the button has a popup. */
+  'aria-haspopup'?: boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' | 'true' | 'false';
+  /** Whether the popup is expanded. */
+  'aria-expanded'?: boolean | 'true' | 'false';
+  /** The accessible label for the button. */
+  'aria-label'?: string;
+  /** The id of the element that labels the button. */
+  'aria-labelledby'?: string;
+  /** The id of the element that describes the button. */
+  'aria-describedby'?: string;
+  /** Identifies the element (or elements) whose contents or presence are controlled by the button. */
+  'aria-controls'?: string;
+  /** Indicates the current "pressed" state of toggle buttons. */
+  'aria-current'?: boolean | 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false';
+  /** Additional attributes for form buttons. */
+  form?: string;
+  formAction?: string;
+  formEncType?: string;
+  formMethod?: string;
+  formNoValidate?: boolean;
+  formTarget?: string;
+  /** The name attribute for form buttons. */
+  name?: string;
+  /** The value attribute for form buttons. */
+  value?: string;
+  /** Whether to exclude the button from the tab order. */
+  excludeFromTabOrder?: boolean;
+}
+
+export interface ButtonAria {
+  /** Props to spread on the button element. */
+  buttonProps: Record<string, unknown>;
+  /** Whether the button is currently pressed. */
+  isPressed: Accessor<boolean>;
+}

package/src/calendar/createCalendar.ts

@@ -0,0 +1,138 @@
+/**
+ * createCalendar hook for Solidaria
+ *
+ * Provides the behavior and accessibility implementation for a calendar component.
+ * Based on @react-aria/calendar useCalendar
+ */
+
+import { createMemo } from 'solid-js';
+import { createId } from '../ssr';
+import { access, type MaybeAccessor } from '../utils/reactivity';
+import { mergeProps } from '../utils/mergeProps';
+import type { CalendarState } from '@proyecto-viviana/solid-stately';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaCalendarProps {
+  /** An ID for the calendar. */
+  id?: string;
+  /** Whether the calendar is disabled. */
+  isDisabled?: boolean;
+  /** Whether the calendar is read-only. */
+  isReadOnly?: boolean;
+  /** An accessible label for the calendar. */
+  'aria-label'?: string;
+  /** The ID of an element that labels the calendar. */
+  'aria-labelledby'?: string;
+  /** The ID of an element that describes the calendar. */
+  'aria-describedby'?: string;
+  /** Minimum number of visible months. */
+  visibleMonths?: number;
+}
+
+export interface CalendarAria {
+  /** Props for the calendar container element. */
+  calendarProps: Record<string, unknown>;
+  /** Props for the previous button. */
+  prevButtonProps: Record<string, unknown>;
+  /** Props for the next button. */
+  nextButtonProps: Record<string, unknown>;
+  /** Props for the title/heading element. */
+  titleProps: Record<string, unknown>;
+  /** An accessible label for the title. */
+  title: string;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the behavior and accessibility implementation for a calendar component.
+ */
+export function createCalendar<T extends CalendarState>(
+  props: MaybeAccessor<AriaCalendarProps>,
+  state: T
+): CalendarAria {
+  const getProps = () => access(props);
+  const id = createId(getProps().id);
+  const titleId = createId();
+
+  // Title (e.g., "December 2024")
+  const title = createMemo(() => state.title());
+
+  // Previous button props
+  const prevButtonProps = createMemo(() => {
+    const p = getProps();
+    const isDisabled = p.isDisabled || state.isDisabled();
+
+    return {
+      'aria-label': 'Previous month',
+      onClick: () => {
+        if (!isDisabled) {
+          state.focusPreviousPage();
+        }
+      },
+      disabled: isDisabled,
+      tabIndex: -1,
+    };
+  });
+
+  // Next button props
+  const nextButtonProps = createMemo(() => {
+    const p = getProps();
+    const isDisabled = p.isDisabled || state.isDisabled();
+
+    return {
+      'aria-label': 'Next month',
+      onClick: () => {
+        if (!isDisabled) {
+          state.focusNextPage();
+        }
+      },
+      disabled: isDisabled,
+      tabIndex: -1,
+    };
+  });
+
+  // Title props
+  const titleProps = createMemo(() => ({
+    id: titleId,
+    'aria-live': 'polite' as const,
+  }));
+
+  // Calendar container props
+  const calendarProps = createMemo(() => {
+    const p = getProps();
+
+    return mergeProps(
+      {
+        id,
+        role: 'group',
+        'aria-labelledby': p['aria-labelledby'] ?? titleId,
+        'aria-label': p['aria-label'],
+        'aria-describedby': p['aria-describedby'],
+      }
+    );
+  });
+
+  return {
+    get calendarProps() {
+      return calendarProps();
+    },
+    get prevButtonProps() {
+      return prevButtonProps();
+    },
+    get nextButtonProps() {
+      return nextButtonProps();
+    },
+    get titleProps() {
+      return titleProps();
+    },
+    get title() {
+      return title();
+    },
+  };
+}