@proyecto-viviana/solidaria 0.2.2 → 0.2.4

package/src/checkbox/createCheckbox.ts

@@ -0,0 +1,135 @@
+/**
+ * Checkbox hook for Solidaria
+ *
+ * Provides the behavior and accessibility implementation for a checkbox component.
+ * Checkboxes allow users to select multiple items from a list of individual items,
+ * or to mark one individual item as selected.
+ *
+ * This is a 1:1 port of @react-aria/checkbox's useCheckbox hook.
+ */
+
+import { JSX, Accessor, createEffect } from 'solid-js';
+import { createToggle, type AriaToggleProps } from '../toggle';
+import { type ToggleState } from '@proyecto-viviana/solid-stately';
+import { createPress } from '../interactions/createPress';
+import { mergeProps } from '../utils/mergeProps';
+import { type MaybeAccessor, access } from '../utils/reactivity';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaCheckboxProps extends AriaToggleProps {
+  /**
+   * Indeterminism is presentational only.
+   * The indeterminate visual representation remains regardless of user interaction.
+   */
+  isIndeterminate?: boolean;
+  /**
+   * Whether the checkbox is required.
+   */
+  isRequired?: boolean;
+  /**
+   * The validation behavior for the checkbox.
+   * @default 'aria'
+   */
+  validationBehavior?: 'aria' | 'native';
+}
+
+export interface CheckboxAria {
+  /** Props for the label wrapper element. */
+  labelProps: JSX.LabelHTMLAttributes<HTMLLabelElement>;
+  /** Props for the input element. */
+  inputProps: JSX.InputHTMLAttributes<HTMLInputElement>;
+  /** Whether the checkbox is selected. */
+  isSelected: Accessor<boolean>;
+  /** Whether the checkbox is in a pressed state. */
+  isPressed: Accessor<boolean>;
+  /** Whether the checkbox is disabled. */
+  isDisabled: boolean;
+  /** Whether the checkbox is read only. */
+  isReadOnly: boolean;
+  /** Whether the checkbox is invalid. */
+  isInvalid: boolean;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the behavior and accessibility implementation for a checkbox component.
+ * Checkboxes allow users to select multiple items from a list of individual items,
+ * or to mark one individual item as selected.
+ *
+ * @param props - Props for the checkbox.
+ * @param state - State for the checkbox, as returned by `createToggleState`.
+ * @param inputRef - A ref accessor for the HTML input element.
+ */
+export function createCheckbox(
+  props: MaybeAccessor<AriaCheckboxProps>,
+  state: ToggleState,
+  inputRef: () => HTMLInputElement | null
+): CheckboxAria {
+  const getProps = () => access(props);
+
+  // Get toggle aria props
+  const toggleResult = createToggle(props, state, inputRef);
+  const {
+    labelProps: baseLabelProps,
+    isSelected,
+    isPressed,
+    isDisabled,
+    isReadOnly,
+    isInvalid,
+  } = toggleResult;
+
+  // Handle indeterminate state
+  createEffect(() => {
+    const input = inputRef();
+    const isIndeterminate = getProps().isIndeterminate;
+    if (input) {
+      // indeterminate is a property, but it can only be set via javascript
+      // https://css-tricks.com/indeterminate-checkboxes/
+      input.indeterminate = !!isIndeterminate;
+    }
+  });
+
+  // Reset validation state on label press for checkbox with a hidden input.
+  const { pressProps } = createPress({
+    get isDisabled() {
+      return isDisabled || isReadOnly;
+    },
+    onPress() {
+      // Validation state reset would be handled here if we had form validation
+      // For now, this is a no-op placeholder matching React-Aria's pattern
+    },
+  });
+
+  return {
+    labelProps: mergeProps(
+      baseLabelProps as unknown as Record<string, unknown>,
+      pressProps as unknown as Record<string, unknown>,
+      {
+        // Prevent label from being focused when mouse down on it.
+        // Note, this does not prevent the input from being focused in the `click` event.
+        onMouseDown: (e: MouseEvent) => e.preventDefault(),
+      } as Record<string, unknown>
+    ) as JSX.LabelHTMLAttributes<HTMLLabelElement>,
+    get inputProps() {
+      const p = getProps();
+      const { isRequired, validationBehavior = 'aria' } = p;
+
+      return mergeProps(toggleResult.inputProps, {
+        checked: isSelected(),
+        'aria-required': (isRequired && validationBehavior === 'aria') || undefined,
+        required: isRequired && validationBehavior === 'native',
+      }) as JSX.InputHTMLAttributes<HTMLInputElement>;
+    },
+    isSelected,
+    isPressed,
+    isDisabled,
+    isReadOnly,
+    isInvalid,
+  };
+}

package/src/checkbox/createCheckboxGroup.ts

@@ -0,0 +1,137 @@
+/**
+ * Checkbox group hook for Solidaria
+ *
+ * Provides the behavior and accessibility implementation for a checkbox group component.
+ * Checkbox groups allow users to select multiple items from a list of options.
+ *
+ * This is a 1:1 port of @react-aria/checkbox's useCheckboxGroup hook.
+ */
+
+import { JSX } from 'solid-js';
+import { createField } from '../label';
+import { createFocusWithin } from '../interactions/createFocusWithin';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { mergeProps } from '../utils/mergeProps';
+import { type MaybeAccessor, access } from '../utils/reactivity';
+import { type CheckboxGroupState, type CheckboxGroupProps } from '@proyecto-viviana/solid-stately';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaCheckboxGroupProps extends CheckboxGroupProps {
+  /** 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;
+  /** 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;
+}
+
+export interface CheckboxGroupAria {
+  /** Props for the checkbox group wrapper element. */
+  groupProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the checkbox group's visible label (if any). */
+  labelProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the checkbox group description element, if any. */
+  descriptionProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the checkbox group error message element, if any. */
+  errorMessageProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Whether the checkbox group is invalid. */
+  isInvalid: boolean;
+}
+
+// WeakMap to share data between checkbox group and checkbox group items
+export const checkboxGroupData = new WeakMap<
+  CheckboxGroupState,
+  {
+    name?: string;
+    form?: string;
+    descriptionId?: string;
+    errorMessageId?: string;
+    validationBehavior: 'aria' | 'native';
+  }
+>();
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the behavior and accessibility implementation for a checkbox group component.
+ * Checkbox groups allow users to select multiple items from a list of options.
+ *
+ * @param props - Props for the checkbox group.
+ * @param state - State for the checkbox group, as returned by `createCheckboxGroupState`.
+ */
+export function createCheckboxGroup(
+  props: MaybeAccessor<AriaCheckboxGroupProps>,
+  state: CheckboxGroupState
+): CheckboxGroupAria {
+  const getProps = () => access(props);
+
+  const isInvalid = () => state.isInvalid;
+
+  // Use field for label association
+  const { labelProps, fieldProps, descriptionProps, errorMessageProps } = createField({
+    get label() { return getProps().label; },
+    get 'aria-label'() { return getProps()['aria-label']; },
+    get 'aria-labelledby'() { return getProps()['aria-labelledby']; },
+    get 'aria-describedby'() { return getProps()['aria-describedby']; },
+    get 'aria-details'() { return getProps()['aria-details']; },
+    get description() { return getProps().description; },
+    get errorMessage() { return getProps().errorMessage ?? (isInvalid() ? 'Invalid selection' : undefined); },
+    get isInvalid() { return isInvalid(); },
+    // Checkbox group is not an HTML input element so it
+    // shouldn't be labeled by a <label> element.
+    labelElementType: 'span',
+  });
+
+  // Store data for checkbox group items
+  checkboxGroupData.set(state, {
+    name: getProps().name,
+    form: getProps().form,
+    descriptionId: descriptionProps.id,
+    errorMessageId: errorMessageProps.id,
+    validationBehavior: 'aria',
+  });
+
+  // Filter DOM props
+  const domProps = () => filterDOMProps(getProps() as unknown as Record<string, unknown>, { labelable: true });
+
+  // Handle focus within
+  const { focusWithinProps } = createFocusWithin({
+    get onBlurWithin() { return getProps().onBlur; },
+    get onFocusWithin() { return getProps().onFocus; },
+    get onFocusWithinChange() { return getProps().onFocusChange; },
+  });
+
+  return {
+    get groupProps() {
+      return mergeProps(domProps(), {
+        role: 'group',
+        'aria-disabled': state.isDisabled || undefined,
+        ...fieldProps,
+        ...focusWithinProps,
+      }) as JSX.HTMLAttributes<HTMLElement>;
+    },
+    get labelProps() {
+      return labelProps as JSX.HTMLAttributes<HTMLElement>;
+    },
+    get descriptionProps() {
+      return descriptionProps;
+    },
+    get errorMessageProps() {
+      return errorMessageProps;
+    },
+    get isInvalid() {
+      return isInvalid();
+    },
+  };
+}

package/src/checkbox/createCheckboxGroupItem.ts

@@ -0,0 +1,117 @@
+/**
+ * Checkbox group item hook for Solidaria
+ *
+ * Provides the behavior and accessibility implementation for a checkbox component
+ * contained within a checkbox group.
+ *
+ * This is a 1:1 port of @react-aria/checkbox's useCheckboxGroupItem hook.
+ */
+
+import { JSX } from 'solid-js';
+import { createCheckbox, type AriaCheckboxProps, type CheckboxAria } from './createCheckbox';
+import { type ToggleState, type CheckboxGroupState } from '@proyecto-viviana/solid-stately';
+import { checkboxGroupData } from './createCheckboxGroup';
+import { type MaybeAccessor, access } from '../utils/reactivity';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface AriaCheckboxGroupItemProps extends Omit<AriaCheckboxProps, 'isSelected' | 'defaultSelected'> {
+  /** The value of the checkbox. */
+  value: string;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides the behavior and accessibility implementation for a checkbox component
+ * contained within a checkbox group.
+ *
+ * @param props - Props for the checkbox.
+ * @param state - State for the checkbox group, as returned by `createCheckboxGroupState`.
+ * @param inputRef - A ref accessor for the HTML input element.
+ */
+export function createCheckboxGroupItem(
+  props: MaybeAccessor<AriaCheckboxGroupItemProps>,
+  state: CheckboxGroupState,
+  inputRef: () => HTMLInputElement | null
+): CheckboxAria {
+  const getProps = () => access(props);
+
+  // Create toggle state that syncs with the group state
+  const toggleState: ToggleState = {
+    isSelected: () => state.isSelected(getProps().value),
+    defaultSelected: state.defaultValue.includes(getProps().value),
+    setSelected(isSelected: boolean) {
+      const value = getProps().value;
+      if (isSelected) {
+        state.addValue(value);
+      } else {
+        state.removeValue(value);
+      }
+      getProps().onChange?.(isSelected);
+    },
+    toggle() {
+      state.toggleValue(getProps().value);
+    },
+  };
+
+  // Get group data
+  const getGroupData = () => checkboxGroupData.get(state);
+
+  // Build checkbox props
+  const checkboxProps = (): AriaCheckboxProps => {
+    const p = getProps();
+    const groupData = getGroupData();
+
+    return {
+      ...p,
+      isReadOnly: p.isReadOnly ?? state.isReadOnly,
+      isDisabled: p.isDisabled ?? state.isDisabled,
+      name: p.name ?? groupData?.name,
+      form: p.form ?? groupData?.form,
+      isRequired: p.isRequired ?? state.isRequired(),
+      validationBehavior: p.validationBehavior ?? groupData?.validationBehavior ?? 'aria',
+    };
+  };
+
+  // Use the checkbox hook
+  const result = createCheckbox(checkboxProps, toggleState, inputRef);
+
+  // Add group-level aria-describedby
+  return {
+    ...result,
+    get inputProps() {
+      const baseInputProps = result.inputProps;
+      const groupData = getGroupData();
+
+      const describedByIds: string[] = [];
+
+      // Add props aria-describedby
+      const propsDescribedBy = getProps()['aria-describedby'];
+      if (propsDescribedBy) {
+        describedByIds.push(propsDescribedBy);
+      }
+
+      // Add error message ID if group is invalid
+      if (state.isInvalid && groupData?.errorMessageId) {
+        describedByIds.push(groupData.errorMessageId);
+      }
+
+      // Add description ID
+      if (groupData?.descriptionId) {
+        describedByIds.push(groupData.descriptionId);
+      }
+
+      const ariaDescribedBy = describedByIds.length > 0 ? describedByIds.join(' ') : undefined;
+
+      return {
+        ...baseInputProps,
+        'aria-describedby': ariaDescribedBy,
+      } as JSX.InputHTMLAttributes<HTMLInputElement>;
+    },
+  };
+}

package/src/checkbox/createCheckboxGroupState.ts

@@ -0,0 +1,193 @@
+/**
+ * Checkbox group state for Solidaria
+ *
+ * Provides state management for a checkbox group component.
+ * Provides a name for the group, and manages selection and focus state.
+ *
+ * This is a 1:1 port of @react-stately/checkbox's useCheckboxGroupState.
+ */
+
+import { createSignal, Accessor } from 'solid-js';
+import { type MaybeAccessor, access } from '../utils/reactivity';
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface CheckboxGroupProps {
+  /** The current selected values (controlled). */
+  value?: string[];
+  /** The default selected values (uncontrolled). */
+  defaultValue?: string[];
+  /** Handler that is called when the value changes. */
+  onChange?: (value: string[]) => void;
+  /** Whether the checkbox group is disabled. */
+  isDisabled?: boolean;
+  /** Whether the checkbox group is read only. */
+  isReadOnly?: boolean;
+  /** Whether the checkbox group is required. */
+  isRequired?: boolean;
+  /** Whether the checkbox group is invalid. */
+  isInvalid?: boolean;
+  /** The name of the checkbox group, used when submitting an HTML form. */
+  name?: string;
+  /** The form to associate the checkbox group with. */
+  form?: string;
+  /** The label for the checkbox group. */
+  label?: string;
+  /** Handler that is called when the checkbox group receives focus. */
+  onFocus?: (e: FocusEvent) => void;
+  /** Handler that is called when the checkbox group loses focus. */
+  onBlur?: (e: FocusEvent) => void;
+  /** Handler that is called when the checkbox group's focus status changes. */
+  onFocusChange?: (isFocused: boolean) => void;
+}
+
+export interface CheckboxGroupState {
+  /** Current selected values. */
+  readonly value: Accessor<readonly string[]>;
+  /** Default selected values. */
+  readonly defaultValue: readonly string[];
+  /** Whether the checkbox group is disabled. */
+  readonly isDisabled: boolean;
+  /** Whether the checkbox group is read only. */
+  readonly isReadOnly: boolean;
+  /** Whether the checkbox group is invalid. */
+  readonly isInvalid: boolean;
+  /**
+   * Whether the checkboxes in the group are required.
+   * This changes to false once at least one item is selected.
+   */
+  readonly isRequired: Accessor<boolean>;
+  /** Returns whether the given value is selected. */
+  isSelected(value: string): boolean;
+  /** Sets the selected values. */
+  setValue(value: string[]): void;
+  /** Adds a value to the set of selected values. */
+  addValue(value: string): void;
+  /** Removes a value from the set of selected values. */
+  removeValue(value: string): void;
+  /** Toggles a value in the set of selected values. */
+  toggleValue(value: string): void;
+}
+
+// ============================================
+// IMPLEMENTATION
+// ============================================
+
+/**
+ * Provides state management for a checkbox group component.
+ * Provides a name for the group, and manages selection and focus state.
+ */
+export function createCheckboxGroupState(
+  props: MaybeAccessor<CheckboxGroupProps> = {}
+): CheckboxGroupState {
+  const getProps = () => access(props);
+
+  // Get initial values
+  const initialProps = getProps();
+  const initialValue = initialProps.value ?? initialProps.defaultValue ?? [];
+
+  // Create internal signal for uncontrolled mode
+  const [internalValue, setInternalValue] = createSignal<readonly string[]>(initialValue);
+
+  // Determine if controlled
+  const isControlled = () => getProps().value !== undefined;
+
+  // Get current value
+  const value: Accessor<readonly string[]> = () => {
+    const p = getProps();
+    return isControlled() ? (p.value ?? []) : internalValue();
+  };
+
+  // Check if required (true if isRequired and no items selected)
+  const isRequired: Accessor<boolean> = () => {
+    const p = getProps();
+    return !!p.isRequired && value().length === 0;
+  };
+
+  // Check if invalid
+  const isInvalid = () => {
+    return getProps().isInvalid ?? false;
+  };
+
+  // Set value
+  function setValue(newValue: string[]): void {
+    const p = getProps();
+    if (p.isReadOnly || p.isDisabled) {
+      return;
+    }
+
+    if (!isControlled()) {
+      setInternalValue(newValue);
+    }
+
+    p.onChange?.(newValue);
+  }
+
+  // Check if value is selected
+  function isSelected(checkValue: string): boolean {
+    return value().includes(checkValue);
+  }
+
+  // Add value
+  function addValue(addVal: string): void {
+    const p = getProps();
+    if (p.isReadOnly || p.isDisabled) {
+      return;
+    }
+
+    const current = value();
+    if (!current.includes(addVal)) {
+      setValue([...current, addVal]);
+    }
+  }
+
+  // Remove value
+  function removeValue(removeVal: string): void {
+    const p = getProps();
+    if (p.isReadOnly || p.isDisabled) {
+      return;
+    }
+
+    const current = value();
+    if (current.includes(removeVal)) {
+      setValue(current.filter((v) => v !== removeVal));
+    }
+  }
+
+  // Toggle value
+  function toggleValue(toggleVal: string): void {
+    const p = getProps();
+    if (p.isReadOnly || p.isDisabled) {
+      return;
+    }
+
+    const current = value();
+    if (current.includes(toggleVal)) {
+      setValue(current.filter((v) => v !== toggleVal));
+    } else {
+      setValue([...current, toggleVal]);
+    }
+  }
+
+  return {
+    value,
+    defaultValue: initialProps.defaultValue ?? initialValue,
+    get isDisabled() {
+      return getProps().isDisabled ?? false;
+    },
+    get isReadOnly() {
+      return getProps().isReadOnly ?? false;
+    },
+    get isInvalid() {
+      return isInvalid();
+    },
+    isRequired,
+    isSelected,
+    setValue,
+    addValue,
+    removeValue,
+    toggleValue,
+  };
+}

package/src/checkbox/index.ts

@@ -0,0 +1,13 @@
+export { createCheckbox } from './createCheckbox';
+export type { AriaCheckboxProps, CheckboxAria } from './createCheckbox';
+
+// Re-export state from solid-stately
+export { createCheckboxGroupState } from '@proyecto-viviana/solid-stately';
+export type { CheckboxGroupProps, CheckboxGroupState } from '@proyecto-viviana/solid-stately';
+
+// ARIA hooks (solidaria-specific)
+export { createCheckboxGroup, checkboxGroupData } from './createCheckboxGroup';
+export type { AriaCheckboxGroupProps, CheckboxGroupAria } from './createCheckboxGroup';
+
+export { createCheckboxGroupItem } from './createCheckboxGroupItem';
+export type { AriaCheckboxGroupItemProps } from './createCheckboxGroupItem';