@proyecto-viviana/solidaria 0.2.8 → 0.4.0

package/src/radio/createRadio.ts

@@ -7,20 +7,17 @@
  * This is a 1:1 port of @react-aria/radio's useRadio 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 { isDevEnv } from '../utils/env';
-import { type RadioGroupState, radioGroupSyncVersion } from '@proyecto-viviana/solid-stately';
-import { radioGroupData } from './createRadioGroup';
-import { type PressEvent } from '../interactions/PressEvent';
-
-// ============================================
-// TYPES
-// ============================================
+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 { isDevEnv } from "../utils/env";
+import { createSlotId } from "../ssr";
+import { type RadioGroupState, radioGroupSyncVersion } from "@proyecto-viviana/solid-stately";
+import { radioGroupData } from "./createRadioGroup";
+import { type PressEvent } from "../interactions/PressEvent";
 
 export interface AriaRadioProps {
   /** The value of the radio button, used when submitting an HTML form. */
@@ -30,11 +27,11 @@ export interface AriaRadioProps {
   /** The label for the radio button. */
   children?: JSX.Element;
   /** Defines a string value that labels the current element. */
-  'aria-label'?: string;
+  "aria-label"?: string;
   /** Identifies the element (or elements) that labels the current element. */
-  'aria-labelledby'?: string;
+  "aria-labelledby"?: string;
   /** Identifies the element (or elements) that describes the object. */
-  'aria-describedby'?: string;
+  "aria-describedby"?: 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. */
@@ -66,6 +63,8 @@ export interface RadioAria {
   labelProps: JSX.LabelHTMLAttributes<HTMLLabelElement>;
   /** Props for the input element. */
   inputProps: JSX.InputHTMLAttributes<HTMLInputElement>;
+  /** Props for the radio's description element, if any. */
+  descriptionProps: JSX.HTMLAttributes<HTMLElement>;
   /** Whether the radio is disabled. */
   isDisabled: boolean;
   /** Whether the radio is currently selected. */
@@ -74,10 +73,6 @@ export interface RadioAria {
   isPressed: Accessor<boolean>;
 }
 
-// ============================================
-// IMPLEMENTATION
-// ============================================
-
 /**
  * Provides the behavior and accessibility implementation for an individual
  * radio button in a radio group.
@@ -85,7 +80,7 @@ export interface RadioAria {
 export function createRadio(
   props: MaybeAccessor<AriaRadioProps>,
   state: RadioGroupState,
-  ref: () => HTMLInputElement | null
+  ref: () => HTMLInputElement | null,
 ): RadioAria {
   const getProps = () => access(props);
 
@@ -97,13 +92,14 @@ export function createRadio(
     return selected === v;
   };
 
-  // Warn if no accessible label
   createEffect(() => {
     const p = getProps();
     const hasChildren = p.children != null;
-    const hasAriaLabel = p['aria-label'] != null || p['aria-labelledby'] != null;
+    const hasAriaLabel = p["aria-label"] != null || p["aria-labelledby"] != null;
     if (!hasChildren && !hasAriaLabel && isDevEnv()) {
-      console.warn('If you do not provide children, you must specify an aria-label for accessibility');
+      console.warn(
+        "If you do not provide children, you must specify an aria-label for accessibility",
+      );
     }
   });
 
@@ -120,25 +116,19 @@ export function createRadio(
   // We track `syncVersion` to ensure this effect runs on EVERY selection attempt,
   // even in controlled mode where isSelected() may not change.
   createEffect(() => {
-    const inputEl = ref();
-    if (!inputEl) return;
-
-    // Track syncVersion to trigger on any selection attempt
-    // This is crucial for controlled mode where isSelected() may not change
-    // syncVersion is stored in an internal WeakMap to maintain API parity with React-Aria
+    // The WeakMap accessor is outside the public API to maintain React Aria parity.
     const syncVersion = radioGroupSyncVersion.get(state);
     syncVersion?.();
 
-    // Read the reactive state to establish tracking and get current value
     const shouldBeChecked = isSelected();
+    const inputEl = ref();
+    if (!inputEl) return;
 
-    // Sync the DOM checked state immediately
     if (inputEl.checked !== shouldBeChecked) {
       inputEl.checked = shouldBeChecked;
     }
   });
 
-  // Handle input change
   // SolidJS-specific: Unlike React, the input's `checked` state can get out of sync
   // with our reactive state. This happens because:
   // 1. A readonly `<input type="radio" />` is always "checkable" in the browser
@@ -146,8 +136,8 @@ export function createRadio(
   //    internal `checked` state when clicked, regardless of what the signal says
   //
   // To prevent this, we force the input's `checked` DOM property to match our state
-  // after processing the change. This is the pattern used by Kobalte and other
-  // SolidJS component libraries.
+  // after processing the change. This is a common pattern across SolidJS component
+  // libraries (see CREDITS.md for attribution).
   const onChange: JSX.EventHandler<HTMLInputElement, Event> = (e) => {
     e.stopPropagation();
 
@@ -172,49 +162,88 @@ export function createRadio(
 
   // 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(); },
+    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 onClick() {
+      return getProps().onClick;
+    },
+    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; },
+    get onPressStart() {
+      return getProps().onPressStart;
+    },
+    get onPressEnd() {
+      return getProps().onPressEnd;
+    },
+    get onPressChange() {
+      return getProps().onPressChange;
+    },
+    get onPressUp() {
+      return getProps().onPressUp;
+    },
+    get onClick() {
+      return getProps().onClick;
+    },
     onPress(e: PressEvent) {
       getProps().onPress?.(e);
       state.setSelectedValue(value());
       ref()?.focus();
     },
-    get isDisabled() { return isDisabled(); },
+    get isDisabled() {
+      return isDisabled();
+    },
   });
 
-  // Handle focusable
-  const { focusableProps } = createFocusable({
-    get isDisabled() { return isDisabled(); },
-    get autoFocus() { return getProps().autoFocus; },
-    onFocus(e: FocusEvent) {
-      getProps().onFocus?.(e);
-      state.setLastFocusedValue(value());
+  const { focusableProps } = createFocusable(
+    {
+      get isDisabled() {
+        return isDisabled();
+      },
+      get autoFocus() {
+        return getProps().autoFocus;
+      },
+      onFocus(e: FocusEvent) {
+        getProps().onFocus?.(e);
+        state.setLastFocusedValue(value());
+      },
+      get onBlur() {
+        return getProps().onBlur;
+      },
+      get onFocusChange() {
+        return getProps().onFocusChange;
+      },
+      get onKeyDown() {
+        return getProps().onKeyDown;
+      },
+      get onKeyUp() {
+        return getProps().onKeyUp;
+      },
     },
-    get onBlur() { return getProps().onBlur; },
-    get onFocusChange() { return getProps().onFocusChange; },
-    get onKeyDown() { return getProps().onKeyDown; },
-    get onKeyUp() { return getProps().onKeyUp; },
-  }, ref as unknown as (el: HTMLElement) => void);
+    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 });
+  const domProps = () =>
+    filterDOMProps(getProps() as unknown as Record<string, unknown>, { labelable: true });
 
-  // Calculate tabIndex based on selection and focus state
   const getTabIndex = (): number | undefined => {
     if (isDisabled()) {
       return undefined;
@@ -225,13 +254,11 @@ export function createRadio(
     const currentValue = value();
 
     if (selected != null) {
-      // If there's a selection, only the selected radio is focusable
       if (selected === currentValue) {
         return 0;
       }
       return -1;
     } else {
-      // If no selection, the last focused or first radio is focusable
       if (lastFocused === currentValue || lastFocused == null) {
         return 0;
       }
@@ -239,12 +266,14 @@ export function createRadio(
     }
   };
 
-  // Get group data
   const getGroupData = () => radioGroupData.get(state);
 
-  // Combined pressed state
   const combinedIsPressed: Accessor<boolean> = () => isPressed() || isLabelPressed();
 
+  // The radio's own description slot id — resolves only once an element with
+  // this id is rendered (e.g. a `<Text slot="description">` child).
+  const descriptionId = createSlotId();
+
   return {
     labelProps: mergeProps(labelPressProps, {
       onClick: (e: MouseEvent) => e.preventDefault(),
@@ -254,10 +283,16 @@ export function createRadio(
       const p = getProps();
       const groupData = getGroupData();
 
-      // Build aria-describedby
+      // Order mirrors upstream useRadio: the user's aria-describedby, then the
+      // radio's own description, then the group's error message (when invalid)
+      // and the group's shared description.
       const describedByIds: string[] = [];
-      if (p['aria-describedby']) {
-        describedByIds.push(p['aria-describedby']);
+      if (p["aria-describedby"]) {
+        describedByIds.push(p["aria-describedby"]);
+      }
+      const ownDescriptionId = descriptionId();
+      if (ownDescriptionId) {
+        describedByIds.push(ownDescriptionId);
       }
       if (state.isInvalid && groupData?.errorMessageId) {
         describedByIds.push(groupData.errorMessageId);
@@ -265,21 +300,25 @@ export function createRadio(
       if (groupData?.descriptionId) {
         describedByIds.push(groupData.descriptionId);
       }
-      const ariaDescribedBy = describedByIds.length > 0 ? describedByIds.join(' ') : undefined;
+      const ariaDescribedBy = describedByIds.length > 0 ? describedByIds.join(" ") : undefined;
+      const validationBehavior = groupData?.validationBehavior ?? "native";
 
       return mergeProps(domProps(), interactions, {
-        type: 'radio' as const,
+        type: "radio" as const,
         name: groupData?.name,
         form: groupData?.form,
         tabIndex: getTabIndex(),
         disabled: isDisabled(),
-        required: state.isRequired && groupData?.validationBehavior === 'native',
+        required: validationBehavior === "native" ? state.isRequired : undefined,
         checked: isSelected(),
         value: value(),
         onChange,
-        'aria-describedby': ariaDescribedBy,
+        "aria-describedby": ariaDescribedBy,
       }) as JSX.InputHTMLAttributes<HTMLInputElement>;
     },
+    get descriptionProps() {
+      return { id: descriptionId() };
+    },
     isDisabled: isDisabled(),
     isSelected,
     isPressed: combinedIsPressed,

package/src/radio/createRadioGroup.ts

@@ -7,20 +7,16 @@
  * This is a 1:1 port of @react-aria/radio's useRadioGroup hook.
  */
 
-import { JSX } from 'solid-js';
-import { createField } from '../label/createField';
-import { createFocusWithin } from '../interactions/createFocusWithin';
-import { mergeProps } from '../utils/mergeProps';
-import { filterDOMProps } from '../utils/filterDOMProps';
-import { focusSafely, getEventTarget } from '../utils';
-import { useLocale } from '../i18n';
-import { createId } from '../ssr';
-import { type MaybeAccessor, access } from '../utils/reactivity';
-import { type RadioGroupState, type ValidityState } from '@proyecto-viviana/solid-stately';
-
-// ============================================
-// TYPES
-// ============================================
+import { JSX } from "solid-js";
+import { createField } from "../label/createField";
+import { createFocusWithin } from "../interactions/createFocusWithin";
+import { mergeProps } from "../utils/mergeProps";
+import { filterDOMProps } from "../utils/filterDOMProps";
+import { focusSafely, getEventTarget } from "../utils";
+import { useLocale } from "../i18n";
+import { createId } from "../ssr";
+import { type MaybeAccessor, access } from "../utils/reactivity";
+import { type RadioGroupState, type ValidityState } from "@proyecto-viviana/solid-stately";
 
 export interface AriaRadioGroupProps {
   /** The content to display as the label. */
@@ -28,7 +24,9 @@ export interface AriaRadioGroupProps {
   /** A description for the radio group. Provides additional context. */
   description?: JSX.Element;
   /** An error message for the radio group. */
-  errorMessage?: JSX.Element | ((validation: { isInvalid: boolean; validationErrors: string[] }) => JSX.Element);
+  errorMessage?:
+    | JSX.Element
+    | ((validation: { isInvalid: boolean; validationErrors: string[] }) => JSX.Element);
   /** Whether the radio group is disabled. */
   isDisabled?: boolean;
   /** Whether the radio group is read only. */
@@ -38,13 +36,13 @@ export interface AriaRadioGroupProps {
   /** Whether the radio group is invalid. */
   isInvalid?: boolean;
   /** The axis the Radio Button(s) should align with. Defaults to 'vertical'. */
-  orientation?: 'horizontal' | 'vertical';
+  orientation?: "horizontal" | "vertical";
   /** The name of the radio group, used when submitting an HTML form. */
   name?: string;
   /** The form to associate the radio group with. */
   form?: string;
   /** Validation behavior for the radio group. */
-  validationBehavior?: 'aria' | 'native';
+  validationBehavior?: "aria" | "native";
   /** Handler that is called when the radio group receives focus. */
   onFocus?: (e: FocusEvent) => void;
   /** Handler that is called when the radio group loses focus. */
@@ -52,13 +50,13 @@ export interface AriaRadioGroupProps {
   /** Handler that is called when the radio group's focus status changes. */
   onFocusChange?: (isFocused: boolean) => void;
   /** Defines a string value that labels the current element. */
-  'aria-label'?: string;
+  "aria-label"?: string;
   /** Identifies the element (or elements) that labels the current element. */
-  'aria-labelledby'?: string;
+  "aria-labelledby"?: string;
   /** Identifies the element (or elements) that describes the object. */
-  'aria-describedby'?: string;
+  "aria-describedby"?: string;
   /** Identifies the element (or elements) that provide an error message for the object. */
-  'aria-errormessage'?: string;
+  "aria-errormessage"?: string;
   /** The element's unique identifier. */
   id?: string;
 }
@@ -86,31 +84,27 @@ interface RadioGroupData {
   form: string | undefined;
   descriptionId: string | undefined;
   errorMessageId: string | undefined;
-  validationBehavior: 'aria' | 'native';
+  validationBehavior: "aria" | "native";
 }
 
 export const radioGroupData: WeakMap<RadioGroupState, RadioGroupData> = new WeakMap();
 
-// ============================================
-// IMPLEMENTATION
-// ============================================
-
 /**
  * Provides the behavior and accessibility implementation for a radio group component.
  * Radio groups allow users to select a single item from a list of mutually exclusive options.
  */
 export function createRadioGroup(
   props: MaybeAccessor<AriaRadioGroupProps>,
-  state: RadioGroupState
+  state: RadioGroupState,
 ): RadioGroupAria {
   const getProps = () => access(props);
   const locale = useLocale();
 
-  const orientation = () => getProps().orientation ?? 'vertical';
+  const orientation = () => getProps().orientation ?? "vertical";
   const isReadOnly = () => getProps().isReadOnly ?? false;
   const isRequired = () => getProps().isRequired ?? false;
   const isDisabled = () => getProps().isDisabled ?? false;
-  const validationBehavior = () => getProps().validationBehavior ?? 'aria';
+  const validationBehavior = () => getProps().validationBehavior ?? "native";
   const displayValidation = () => state.displayValidation();
   const validationErrors = () => displayValidation().validationErrors;
   const validationDetails = () => displayValidation().validationDetails;
@@ -120,18 +114,31 @@ export function createRadioGroup(
     return errors.length > 0 ? errors : undefined;
   };
 
-  // Use field for label, description, error message
   const { labelProps, fieldProps, descriptionProps, errorMessageProps } = createField({
-    get id() { return getProps().id; },
-    get label() { return getProps().label; },
-    get 'aria-label'() { return getProps()['aria-label']; },
-    get 'aria-labelledby'() { return getProps()['aria-labelledby']; },
-    get description() { return getProps().description; },
-    get errorMessage() { return getProps().errorMessage ?? fallbackErrorMessage(); },
-    get isInvalid() { return isInvalid(); },
+    get id() {
+      return getProps().id;
+    },
+    get label() {
+      return getProps().label;
+    },
+    get "aria-label"() {
+      return getProps()["aria-label"];
+    },
+    get "aria-labelledby"() {
+      return getProps()["aria-labelledby"];
+    },
+    get description() {
+      return getProps().description;
+    },
+    get errorMessage() {
+      return getProps().errorMessage ?? fallbackErrorMessage();
+    },
+    get isInvalid() {
+      return isInvalid();
+    },
     // Radio group is not an HTML input element so it
     // shouldn't be labeled by a <label> element.
-    labelElementType: 'span',
+    labelElementType: "span",
   });
 
   // Handle focus within - reset focusable radio when group loses focus and no selection
@@ -146,13 +153,11 @@ export function createRadioGroup(
     onFocusWithinChange: (isFocused: boolean) => getProps().onFocusChange?.(isFocused),
   });
 
-  // Filter DOM props
-  const domProps = () => filterDOMProps(getProps() as unknown as Record<string, unknown>, { labelable: true });
+  const domProps = () =>
+    filterDOMProps(getProps() as unknown as Record<string, unknown>, { labelable: true });
 
-  // Generate group name
   const groupName = getProps().name ?? createId();
 
-  // Store data for radio items to access
   radioGroupData.set(state, {
     name: groupName,
     form: getProps().form,
@@ -162,31 +167,32 @@ export function createRadioGroup(
   });
 
   const getNavigableRadios = (root: HTMLElement): HTMLInputElement[] => {
-    return Array.from(root.querySelectorAll('input[type="radio"]'))
-      .filter((el): el is HTMLInputElement => {
-        return el instanceof HTMLInputElement && !el.matches(':disabled');
-      });
+    return Array.from(root.querySelectorAll('input[type="radio"]')).filter(
+      (el): el is HTMLInputElement => {
+        return el instanceof HTMLInputElement && !el.matches(":disabled");
+      },
+    );
   };
 
   // Keyboard navigation parity with React Aria.
   const onKeyDown: JSX.EventHandler<HTMLDivElement, KeyboardEvent> = (e) => {
-    let nextDir: 'next' | 'prev' | null = null;
+    let nextDir: "next" | "prev" | null = null;
     const currentOrientation = orientation();
-    const isHorizontal = currentOrientation !== 'vertical';
-    const isRTL = locale().direction === 'rtl' && isHorizontal;
+    const isHorizontal = currentOrientation !== "vertical";
+    const isRTL = locale().direction === "rtl" && isHorizontal;
 
     switch (e.key) {
-      case 'ArrowRight':
-        nextDir = isRTL ? 'prev' : 'next';
+      case "ArrowRight":
+        nextDir = isRTL ? "prev" : "next";
         break;
-      case 'ArrowLeft':
-        nextDir = isRTL ? 'next' : 'prev';
+      case "ArrowLeft":
+        nextDir = isRTL ? "next" : "prev";
         break;
-      case 'ArrowDown':
-        nextDir = 'next';
+      case "ArrowDown":
+        nextDir = "next";
         break;
-      case 'ArrowUp':
-        nextDir = 'prev';
+      case "ArrowUp":
+        nextDir = "prev";
         break;
       default:
         return;
@@ -207,17 +213,21 @@ export function createRadioGroup(
     const eventTarget = getEventTarget<Element>(e);
     const activeElement = root.ownerDocument.activeElement;
 
-    const currentRadio = eventTarget instanceof HTMLInputElement && eventTarget.type === 'radio'
-      ? eventTarget
-      : (activeElement instanceof HTMLInputElement && activeElement.type === 'radio' ? activeElement : null);
+    const currentRadio =
+      eventTarget instanceof HTMLInputElement && eventTarget.type === "radio"
+        ? eventTarget
+        : activeElement instanceof HTMLInputElement && activeElement.type === "radio"
+          ? activeElement
+          : null;
 
     const currentIndex = currentRadio ? radios.indexOf(currentRadio) : -1;
 
     let nextIndex: number;
-    if (nextDir === 'next') {
+    if (nextDir === "next") {
       nextIndex = currentIndex >= 0 ? (currentIndex + 1) % radios.length : 0;
     } else {
-      nextIndex = currentIndex >= 0 ? (currentIndex - 1 + radios.length) % radios.length : radios.length - 1;
+      nextIndex =
+        currentIndex >= 0 ? (currentIndex - 1 + radios.length) % radios.length : radios.length - 1;
     }
 
     const nextRadio = radios[nextIndex];
@@ -231,21 +241,17 @@ export function createRadioGroup(
 
   return {
     get radioGroupProps() {
-      return mergeProps(
-        domProps(),
-        focusWithinProps as unknown as Record<string, unknown>,
-        {
-          role: 'radiogroup',
-          onKeyDown,
-          'aria-invalid': isInvalid() || undefined,
-          'aria-errormessage': getProps()['aria-errormessage'],
-          'aria-readonly': isReadOnly() || undefined,
-          'aria-required': isRequired() || undefined,
-          'aria-disabled': isDisabled() || undefined,
-          'aria-orientation': orientation(),
-          ...fieldProps,
-        }
-      ) as JSX.HTMLAttributes<HTMLDivElement>;
+      return mergeProps(domProps(), focusWithinProps as unknown as Record<string, unknown>, {
+        role: "radiogroup",
+        onKeyDown,
+        "aria-invalid": isInvalid() || undefined,
+        "aria-errormessage": getProps()["aria-errormessage"],
+        "aria-readonly": isReadOnly() || undefined,
+        "aria-required": isRequired() || undefined,
+        "aria-disabled": isDisabled() || undefined,
+        "aria-orientation": orientation(),
+        ...fieldProps,
+      }) as JSX.HTMLAttributes<HTMLDivElement>;
     },
     labelProps: labelProps as JSX.HTMLAttributes<HTMLElement>,
     descriptionProps,