@proyecto-viviana/solidaria 0.0.1 → 0.0.2

package/src/separator/createSeparator.ts

@@ -0,0 +1,82 @@
+/**
+ * createSeparator - SolidJS implementation of React Aria's useSeparator
+ *
+ * A separator is a visual divider between two groups of content,
+ * e.g. groups of menu items or sections of a page.
+ */
+
+import type { JSX } from 'solid-js';
+import { access, type MaybeAccessor } from '../utils';
+import { filterDOMProps } from '../utils';
+
+// ============================================
+// TYPES
+// ============================================
+
+export type Orientation = 'horizontal' | 'vertical';
+
+export interface AriaSeparatorProps {
+  /**
+   * The orientation of the separator.
+   * @default 'horizontal'
+   */
+  orientation?: Orientation;
+  /**
+   * The HTML element type that will be used to render the separator.
+   * @default 'hr'
+   */
+  elementType?: string;
+  /** An accessibility label for the separator. */
+  'aria-label'?: string;
+  /** Identifies the element(s) that labels the separator. */
+  'aria-labelledby'?: string;
+  /** The element's unique identifier. */
+  id?: string;
+}
+
+export interface SeparatorAria {
+  /** Props for the separator element. */
+  separatorProps: JSX.HTMLAttributes<HTMLElement>;
+}
+
+// ============================================
+// CREATE SEPARATOR
+// ============================================
+
+/**
+ * Provides the accessibility implementation for a separator.
+ * A separator is a visual divider between two groups of content,
+ * e.g. groups of menu items or sections of a page.
+ */
+export function createSeparator(
+  props: MaybeAccessor<AriaSeparatorProps> = {}
+): SeparatorAria {
+  const getSeparatorProps = (): JSX.HTMLAttributes<HTMLElement> => {
+    const p = access(props);
+    const domProps = filterDOMProps(p as Record<string, unknown>, { labelable: true });
+
+    // if orientation is horizontal, aria-orientation default is horizontal, so we leave it undefined
+    // if it's vertical, we need to specify it
+    let ariaOrientation: 'vertical' | undefined;
+    if (p.orientation === 'vertical') {
+      ariaOrientation = 'vertical';
+    }
+
+    // hr elements implicitly have role = separator and a horizontal orientation
+    if (p.elementType !== 'hr') {
+      return {
+        ...domProps,
+        role: 'separator',
+        'aria-orientation': ariaOrientation,
+      };
+    }
+
+    return domProps;
+  };
+
+  return {
+    get separatorProps() {
+      return getSeparatorProps();
+    },
+  };
+}

package/src/separator/index.ts

@@ -0,0 +1,6 @@
+export {
+  createSeparator,
+  type AriaSeparatorProps,
+  type SeparatorAria,
+  type Orientation,
+} from './createSeparator';

package/src/ssr/index.ts

@@ -0,0 +1,36 @@
+/**
+ * SSR utilities for Solidaria
+ *
+ * SolidJS has built-in SSR support with `isServer` and `createUniqueId()`.
+ * These utilities provide a consistent API matching React-Aria's patterns.
+ */
+
+import { createUniqueId } from 'solid-js';
+import { isServer } from 'solid-js/web';
+
+/**
+ * Returns whether the component is currently being server side rendered.
+ * Can be used to delay browser-specific rendering until after hydration.
+ */
+export function createIsSSR(): boolean {
+  return isServer;
+}
+
+/**
+ * Generate a unique ID that is stable across server and client.
+ * Uses SolidJS's built-in createUniqueId which handles SSR correctly.
+ *
+ * @param defaultId - Optional default ID to use instead of generating one.
+ */
+export function createId(defaultId?: string): string {
+  if (defaultId) {
+    return defaultId;
+  }
+  return `solidaria-${createUniqueId()}`;
+}
+
+/**
+ * Check if we can use DOM APIs.
+ * This is useful for code that needs to run only in the browser.
+ */
+export const canUseDOM = !isServer;

package/src/switch/createSwitch.ts

@@ -0,0 +1,70 @@
+/**
+ * Switch hook for Solidaria
+ *
+ * Provides the behavior and accessibility implementation for a switch component.
+ * A switch is similar to a checkbox, but represents on/off values as opposed to selection.
+ *
+ * This is a 1:1 port of @react-aria/switch's useSwitch hook.
+ */
+
+import { JSX, Accessor } from 'solid-js';
+import { createToggle, type AriaToggleProps } from '../toggle/createToggle';
+import { type ToggleState } from '@proyecto-viviana/solid-stately';
+import { type MaybeAccessor } from '../utils/reactivity';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaSwitchProps extends AriaToggleProps {
+  // Switch uses the same props as toggle
+}
+
+export interface SwitchAria {
+  /** Props for the label wrapper element. */
+  labelProps: JSX.LabelHTMLAttributes<HTMLLabelElement>;
+  /** Props for the input element. */
+  inputProps: JSX.InputHTMLAttributes<HTMLInputElement>;
+  /** Whether the switch is selected. */
+  isSelected: Accessor<boolean>;
+  /** Whether the switch is in a pressed state. */
+  isPressed: Accessor<boolean>;
+  /** Whether the switch is disabled. */
+  isDisabled: boolean;
+  /** Whether the switch is read only. */
+  isReadOnly: boolean;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the behavior and accessibility implementation for a switch component.
+ * A switch is similar to a checkbox, but represents on/off values as opposed to selection.
+ */
+export function createSwitch(
+  props: MaybeAccessor<AriaSwitchProps>,
+  state: ToggleState,
+  ref: () => HTMLInputElement | null
+): SwitchAria {
+  // Don't destructure inputProps - it's a getter that needs to be evaluated each time
+  const toggle = createToggle(props, state, ref);
+
+  return {
+    labelProps: toggle.labelProps,
+    get inputProps() {
+      // Access toggle.inputProps (the getter) each time to get fresh values
+      const baseProps = toggle.inputProps;
+      return {
+        ...baseProps,
+        role: 'switch' as const,
+        checked: toggle.isSelected(),
+      };
+    },
+    isSelected: toggle.isSelected,
+    isPressed: toggle.isPressed,
+    isDisabled: toggle.isDisabled,
+    isReadOnly: toggle.isReadOnly,
+  };
+}

package/src/switch/index.ts

@@ -0,0 +1 @@
+export { createSwitch, type AriaSwitchProps, type SwitchAria } from './createSwitch';

package/src/textfield/createTextField.ts

@@ -0,0 +1,198 @@
+/**
+ * TextField hook for Solidaria
+ *
+ * Provides the behavior and accessibility implementation for a text field.
+ *
+ * This is a 1:1 port of @react-aria/textfield's useTextField hook.
+ */
+
+import { JSX } from 'solid-js';
+import { createField, type AriaFieldProps, type FieldAria } from '../label';
+import { createFocusable, type FocusableProps } from '../interactions';
+import { mergeProps, filterDOMProps } from '../utils';
+import { type MaybeAccessor, access } from '../utils/reactivity';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaTextFieldProps extends AriaFieldProps, FocusableProps {
+  /** The current value (controlled). */
+  value?: string;
+  /** The default value (uncontrolled). */
+  defaultValue?: string;
+  /** Handler that is called when the value changes. */
+  onChange?: (value: string) => void;
+  /** Whether the input is disabled. */
+  isDisabled?: boolean;
+  /** Whether the input is read only. */
+  isReadOnly?: boolean;
+  /** Whether the input is required. */
+  isRequired?: boolean;
+  /** The type of input to render. */
+  type?: 'text' | 'search' | 'url' | 'tel' | 'email' | 'password' | string;
+  /** The input mode hint for virtual keyboards. */
+  inputMode?: 'none' | 'text' | 'tel' | 'url' | 'email' | 'numeric' | 'decimal' | 'search';
+  /** The name of the input element, used when submitting an HTML form. */
+  name?: string;
+  /** Regex pattern to validate the input value. */
+  pattern?: string;
+  /** The maximum number of characters supported by the input. */
+  maxLength?: number;
+  /** The minimum number of characters required by the input. */
+  minLength?: number;
+  /** Placeholder text for the input. */
+  placeholder?: string;
+  /** Whether to enable auto complete. */
+  autoComplete?: string;
+  /** Whether to enable auto correct. */
+  autoCorrect?: string;
+  /** Whether to enable spell check. */
+  spellCheck?: 'true' | 'false';
+  /** Controls whether and how text input is automatically capitalized. */
+  autoCapitalize?: 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
+  /** The element type to use for the input. Defaults to 'input'. */
+  inputElementType?: 'input' | 'textarea';
+
+  // Clipboard events
+  onCopy?: JSX.EventHandler<HTMLInputElement | HTMLTextAreaElement, ClipboardEvent>;
+  onCut?: JSX.EventHandler<HTMLInputElement | HTMLTextAreaElement, ClipboardEvent>;
+  onPaste?: JSX.EventHandler<HTMLInputElement | HTMLTextAreaElement, ClipboardEvent>;
+
+  // Composition events
+  onCompositionStart?: JSX.EventHandler<HTMLInputElement | HTMLTextAreaElement, CompositionEvent>;
+  onCompositionEnd?: JSX.EventHandler<HTMLInputElement | HTMLTextAreaElement, CompositionEvent>;
+  onCompositionUpdate?: JSX.EventHandler<HTMLInputElement | HTMLTextAreaElement, CompositionEvent>;
+
+  // Selection events
+  onSelect?: JSX.EventHandler<HTMLInputElement | HTMLTextAreaElement, Event>;
+
+  // Input events
+  onBeforeInput?: JSX.EventHandler<HTMLInputElement | HTMLTextAreaElement, InputEvent>;
+  onInput?: JSX.EventHandler<HTMLInputElement | HTMLTextAreaElement, InputEvent>;
+}
+
+export interface TextFieldAria<T extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement> extends Omit<FieldAria, 'fieldProps'> {
+  /** Props for the input element. */
+  inputProps: JSX.InputHTMLAttributes<T>;
+  /** Whether the text field is invalid. */
+  isInvalid: boolean;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the behavior and accessibility implementation for a text field.
+ * Text fields allow users to input text with a keyboard.
+ *
+ * @param props - Props for the text field.
+ * @param ref - Optional ref callback for the input element.
+ */
+export function createTextField<T extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement>(
+  props: MaybeAccessor<AriaTextFieldProps>,
+  ref?: (el: T) => void
+): TextFieldAria<T> {
+  const getProps = () => access(props);
+
+  // Get field accessibility props (label, description, error message)
+  const { labelProps, fieldProps, descriptionProps, errorMessageProps } = createField(props);
+
+  // Get focusable props
+  const { focusableProps } = createFocusable(
+    {
+      get isDisabled() {
+        return getProps().isDisabled;
+      },
+      get autoFocus() {
+        return getProps().autoFocus;
+      },
+      onFocus: getProps().onFocus,
+      onBlur: getProps().onBlur,
+      onFocusChange: getProps().onFocusChange,
+      onKeyDown: getProps().onKeyDown,
+      onKeyUp: getProps().onKeyUp,
+    },
+    ref as ((el: HTMLElement) => void) | undefined
+  );
+
+  // Filter DOM props
+  const getDomProps = () => filterDOMProps(getProps() as Record<string, unknown>, { labelable: true });
+
+  // Build input props
+  const getInputProps = (): JSX.InputHTMLAttributes<T> => {
+    const p = getProps();
+    const isInvalid = p.isInvalid ?? false;
+    const isTextarea = p.inputElementType === 'textarea';
+
+    return mergeProps(
+      getDomProps(),
+      {
+        disabled: p.isDisabled,
+        readOnly: p.isReadOnly,
+        required: p.isRequired,
+        'aria-required': p.isRequired || undefined,
+        'aria-invalid': isInvalid || undefined,
+        value: p.value ?? p.defaultValue ?? '',
+        onChange: (e: Event) => {
+          const target = e.target as HTMLInputElement | HTMLTextAreaElement;
+          p.onChange?.(target.value);
+        },
+        // Don't include type and pattern for textarea elements
+        type: isTextarea ? undefined : (p.type ?? 'text'),
+        inputMode: p.inputMode,
+        name: p.name,
+        pattern: isTextarea ? undefined : p.pattern,
+        maxLength: p.maxLength,
+        minLength: p.minLength,
+        placeholder: p.placeholder,
+        autoComplete: p.autoComplete,
+        autoCorrect: p.autoCorrect,
+        autoCapitalize: p.autoCapitalize,
+        spellCheck: p.spellCheck,
+
+        // Clipboard events
+        onCopy: p.onCopy,
+        onCut: p.onCut,
+        onPaste: p.onPaste,
+
+        // Composition events
+        onCompositionStart: p.onCompositionStart,
+        onCompositionEnd: p.onCompositionEnd,
+        onCompositionUpdate: p.onCompositionUpdate,
+
+        // Selection events
+        onSelect: p.onSelect,
+
+        // Input events
+        onBeforeInput: p.onBeforeInput,
+        onInput: p.onInput,
+      },
+      focusableProps as Record<string, unknown>,
+      fieldProps as Record<string, unknown>
+    ) as JSX.InputHTMLAttributes<T>;
+  };
+
+  const getIsInvalid = () => {
+    return getProps().isInvalid ?? false;
+  };
+
+  return {
+    get labelProps() {
+      return labelProps;
+    },
+    get inputProps() {
+      return getInputProps();
+    },
+    get descriptionProps() {
+      return descriptionProps;
+    },
+    get errorMessageProps() {
+      return errorMessageProps;
+    },
+    get isInvalid() {
+      return getIsInvalid();
+    },
+  };
+}

package/src/textfield/index.ts

@@ -0,0 +1,5 @@
+export {
+  createTextField,
+  type AriaTextFieldProps,
+  type TextFieldAria,
+} from './createTextField';

package/src/toggle/createToggle.ts

@@ -0,0 +1,222 @@
+/**
+ * Toggle hook for Solidaria
+ *
+ * Handles interactions for toggle elements, e.g. Checkboxes and Switches.
+ *
+ * This is a 1:1 port of @react-aria/toggle's useToggle hook.
+ */
+
+import { JSX, Accessor, createEffect } 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 ToggleState } from '@proyecto-viviana/solid-stately';
+import { type PressEvent } from '../interactions/PressEvent';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaToggleProps {
+  /** Whether the element should be selected (controlled). */
+  isSelected?: boolean;
+  /** Whether the element should be selected by default (uncontrolled). */
+  defaultSelected?: boolean;
+  /** Handler that is called when the element's selection state changes. */
+  onChange?: (isSelected: boolean) => void;
+  /** The value of the input element, used when submitting an HTML form. */
+  value?: string;
+  /** The name of the input element, used when submitting an HTML form. */
+  name?: string;
+  /** The form to associate the input with. */
+  form?: string;
+  /** Whether the element is disabled. */
+  isDisabled?: boolean;
+  /** Whether the element is read only. */
+  isReadOnly?: boolean;
+  /** Whether the element is required. */
+  isRequired?: boolean;
+  /** Whether the element is invalid. */
+  isInvalid?: boolean;
+  /** The element's children. */
+  children?: JSX.Element;
+  /** 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 an error message for the object. */
+  'aria-errormessage'?: string;
+  /** Identifies the element (or elements) whose contents or presence are controlled by the current element. */
+  'aria-controls'?: string;
+  /** The element's unique identifier. */
+  id?: 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, either over the target or when the pointer leaves the target. */
+  onPressEnd?: (e: PressEvent) => void;
+  /** Handler that is called when the press state changes. */
+  onPressChange?: (isPressed: boolean) => void;
+  /** Handler that is called when a press is released over the target, regardless of whether it started on the target or not. */
+  onPressUp?: (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 exclude the element from the tab order. */
+  excludeFromTabOrder?: boolean;
+  /** Whether to autofocus the element. */
+  autoFocus?: boolean;
+}
+
+export interface ToggleAria {
+  /** Props to be spread on the label element. */
+  labelProps: JSX.LabelHTMLAttributes<HTMLLabelElement>;
+  /** Props to be spread on the input element. */
+  inputProps: JSX.InputHTMLAttributes<HTMLInputElement>;
+  /** Whether the toggle is selected. */
+  isSelected: Accessor<boolean>;
+  /** Whether the toggle is in a pressed state. */
+  isPressed: Accessor<boolean>;
+  /** Whether the toggle is disabled. */
+  isDisabled: boolean;
+  /** Whether the toggle is read only. */
+  isReadOnly: boolean;
+  /** Whether the toggle is invalid. */
+  isInvalid: boolean;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Handles interactions for toggle elements, e.g. Checkboxes and Switches.
+ */
+export function createToggle(
+  props: MaybeAccessor<AriaToggleProps>,
+  state: ToggleState,
+  ref: () => HTMLInputElement | null
+): ToggleAria {
+  const getProps = () => access(props);
+
+  const isDisabled = () => getProps().isDisabled ?? false;
+  const isReadOnly = () => getProps().isReadOnly ?? false;
+  const isInvalid = () => {
+    return getProps().isInvalid ?? false;
+  };
+
+  // Handle press state for keyboard interactions and cases where labelProps is not used.
+  const { pressProps, isPressed } = createPress({
+    get onPressStart() { return getProps().onPressStart; },
+    get onPressEnd() { return getProps().onPressEnd; },
+    get onPressChange() { return getProps().onPressChange; },
+    get onPress() { return getProps().onPress; },
+    get onPressUp() { return getProps().onPressUp; },
+    get isDisabled() { return isDisabled(); },
+  });
+
+  // Handle press state on the label.
+  const { pressProps: labelPressProps, isPressed: isLabelPressed } = createPress({
+    get onPressStart() { return getProps().onPressStart; },
+    get onPressEnd() { return getProps().onPressEnd; },
+    get onPressChange() { return getProps().onPressChange; },
+    get onPressUp() { return getProps().onPressUp; },
+    onPress(e: PressEvent) {
+      getProps().onPress?.(e);
+      state.toggle();
+      ref()?.focus();
+    },
+    get isDisabled() { return isDisabled() || isReadOnly(); },
+  });
+
+  // Handle focusable - extract the relevant props for createFocusable
+  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; },
+    get excludeFromTabOrder() { return getProps().excludeFromTabOrder; },
+  }, ref as unknown as (el: HTMLElement) => void);
+
+  // Combine press and focusable props for input
+  const interactions = mergeProps(pressProps, focusableProps);
+
+  // Filter DOM props
+  const domProps = () => filterDOMProps(getProps() as unknown as Record<string, unknown>, { labelable: true });
+
+  // Handle input change
+  const onChange: JSX.EventHandler<HTMLInputElement, Event> = (e) => {
+    // Since we spread props on label, onChange will end up there as well as in here.
+    // So we have to stop propagation at the lowest level that we care about
+    e.stopPropagation();
+
+    // Don't update state if readonly
+    if (isReadOnly()) {
+      // Reset the checkbox to its previous state since the browser already toggled it
+      e.currentTarget.checked = state.isSelected();
+      return;
+    }
+
+    state.setSelected(e.currentTarget.checked);
+  };
+
+  // Warn if no accessible label
+  createEffect(() => {
+    const p = getProps();
+    const hasChildren = p.children != null;
+    const hasAriaLabel = p['aria-label'] != null || p['aria-labelledby'] != null;
+    if (!hasChildren && !hasAriaLabel && process.env.NODE_ENV !== 'production') {
+      console.warn('If you do not provide children, you must specify an aria-label for accessibility');
+    }
+  });
+
+  // Combined pressed state
+  const combinedIsPressed: Accessor<boolean> = () => isPressed() || isLabelPressed();
+
+  return {
+    labelProps: mergeProps(labelPressProps, {
+      onClick: (e: MouseEvent) => e.preventDefault(),
+    }),
+    get inputProps() {
+      const p = getProps();
+      return mergeProps(domProps(), {
+        'aria-invalid': isInvalid() || undefined,
+        'aria-errormessage': p['aria-errormessage'],
+        'aria-controls': p['aria-controls'],
+        'aria-readonly': isReadOnly() || undefined,
+        onChange,
+        disabled: isDisabled(),
+        ...(p.value == null ? {} : { value: p.value }),
+        name: p.name,
+        form: p.form,
+        type: 'checkbox' as const,
+        ...interactions,
+        // Stop click propagation to prevent labelProps.onClick from calling preventDefault
+        // which would prevent the checkbox from toggling in JSDOM/testing-library environments
+        onClick: (e: MouseEvent) => e.stopPropagation(),
+      }) as JSX.InputHTMLAttributes<HTMLInputElement>;
+    },
+    isSelected: state.isSelected,
+    isPressed: combinedIsPressed,
+    isDisabled: isDisabled(),
+    isReadOnly: isReadOnly(),
+    isInvalid: isInvalid(),
+  };
+}