@proyecto-viviana/solidaria 0.3.0 → 0.4.0

package/src/numberfield/createNumberField.ts

@@ -109,15 +109,31 @@ export function createNumberField(
     get "aria-labelledby"() {
       return getProps()["aria-labelledby"];
     },
-    labelElementType: "span",
+    // Upstream react-aria `useNumberField` → `useField` → `useLabel` with the DEFAULT
+    // `labelElementType: 'label'`: the S2 NumberField label is a native `<label htmlFor>`
+    // (verified against the shipped React DOM: `<label id for=inputId>`). This hardcoded
+    // `"span"` was a self-inflicted divergence — it dropped the `for` association and made
+    // `NumberFieldLabel` render a `<span>`. Reverted to `"label"` so `createLabel` emits
+    // `for: inputId` (the input still also carries `aria-labelledby`, exactly as upstream).
+    labelElementType: "label",
   });
 
-  // Get the label text for button aria-labels
-  const getLabelText = (): string => {
-    const p = getProps();
-    if (p["aria-label"]) return p["aria-label"];
-    if (typeof p.label === "string") return p.label;
-    return "value";
+  // Increment/decrement button labels — a 1:1 port of upstream `useNumberField`'s
+  // four-case logic. Upstream RAC's `NumberField` component feeds `useNumberField` a
+  // BOOLEAN slot for `label` (from `useSlot`), never the label string, so a visible
+  // label is NEVER concatenated into the button `aria-label`. Instead: with a visible
+  // label the button reads `aria-label: "Increase"` PLUS `aria-labelledby: "<selfId>
+  // <labelId>"`; only an explicit `aria-label` (and no visible label) changes the text
+  // (`"Increase <aria-label>"`). The prior `Increase ${getLabelText()}` was a
+  // self-inflicted divergence that produced "Increase Quantity" where S2 ships
+  // "Increase". `fieldLabel` mirrors upstream: `props['aria-label'] || ''` — the visible
+  // label string is intentionally excluded (it arrives as a boolean slot in RAC).
+  const fieldLabel = (): string => getProps()["aria-label"] ?? "";
+  const buttonLabelledBy = (): string | undefined => {
+    if (fieldLabel()) return undefined;
+    return getProps().label != null
+      ? (labelProps.id as string | undefined)
+      : getProps()["aria-labelledby"];
   };
 
   // Filter DOM props
@@ -234,6 +250,15 @@ export function createNumberField(
 
     incrementTouchPressUp = false;
   };
+  const onIncrementClick = (e: MouseEvent) => {
+    if (!state.canIncrement()) {
+      e.preventDefault();
+      return;
+    }
+
+    state.increment();
+    inputRef?.()?.focus();
+  };
 
   const onDecrementPressStart = (e: PressEvent) => {
     if (e.pointerType !== "touch") {
@@ -258,6 +283,15 @@ export function createNumberField(
 
     decrementTouchPressUp = false;
   };
+  const onDecrementClick = (e: MouseEvent) => {
+    if (!state.canDecrement()) {
+      e.preventDefault();
+      return;
+    }
+
+    state.decrement();
+    inputRef?.()?.focus();
+  };
 
   // Build aria-describedby
   const getAriaDescribedBy = () => {
@@ -295,11 +329,29 @@ export function createNumberField(
           autoComplete: "off",
           autoCorrect: "off",
           spellcheck: false,
-          role: "spinbutton",
-          "aria-valuenow": isNaN(state.numberValue()) ? undefined : state.numberValue(),
-          "aria-valuemin": state.minValue(),
-          "aria-valuemax": state.maxValue(),
-          "aria-valuetext": isNaN(state.numberValue()) ? undefined : state.inputValue(),
+          // Upstream routes the input through useFormattedTextField → useTextField →
+          // useFocusable, which "always set[s] a tabIndex so that Safari allows
+          // focusing native buttons and inputs": `excludeFromTabOrder ? -1 : 0`, then
+          // `undefined` when disabled. The input is never excluded, so the rendered
+          // DOM carries `tabindex="0"` (absent only when disabled). We hand-roll
+          // inputProps (see the spinbutton-override note below) so we must replay that
+          // one focusable prop here to stay byte-identical to React's tab order.
+          tabIndex: isDisabled ? undefined : 0,
+          // Upstream useNumberField wraps useSpinButton but deliberately
+          // overrides its output: role=spinbutton can't be focused with
+          // VoiceOver, so the input is a plain textbox (inside the role=group
+          // wrapper above) and every aria-value* is dropped in favour of
+          // aria-roledescription. The formatted value is still announced via the
+          // input's own value. Mirror that contract instead of leaking the raw
+          // spinbutton semantics.
+          //
+          // The string MUST match upstream's `stringFormatter.format('numberField')`,
+          // whose en-US value is `Number field` (capitalised) — not a lowercase
+          // hand-roll. Full locale routing via `createStringFormatter` (as
+          // `createDateField` does) is tracked as `intl-roledescription-hardcodes`
+          // (also covers the ColorArea/ColorSwatch English hardcodes); this keeps the
+          // en-US roledescription byte-identical to React Spectrum in the meantime.
+          "aria-roledescription": "Number field",
           "aria-invalid": p.isInvalid || undefined,
           "aria-required": p.isRequired || undefined,
           "aria-describedby": getAriaDescribedBy(),
@@ -323,32 +375,48 @@ export function createNumberField(
       ) as JSX.InputHTMLAttributes<HTMLInputElement>;
     },
     get incrementButtonProps() {
+      const labelledBy = buttonLabelledBy();
       return {
         id: incrementId,
-        "aria-label": `Increase ${getLabelText()}`,
+        type: "button",
+        "aria-label": `Increase ${fieldLabel()}`.trim(),
+        "aria-labelledby": labelledBy ? `${incrementId} ${labelledBy}` : undefined,
         "aria-controls": inputId,
         excludeFromTabOrder: true,
         preventFocusOnPress: true,
         allowFocusWhenDisabled: true,
+        get disabled() {
+          return !state.canIncrement();
+        },
+        tabIndex: -1,
         get isDisabled() {
           return !state.canIncrement();
         },
+        onClick: onIncrementClick,
         onPressStart: onIncrementPressStart,
         onPressUp: onIncrementPressUp,
         onPressEnd: onIncrementPressEnd,
       } as AriaButtonProps;
     },
     get decrementButtonProps() {
+      const labelledBy = buttonLabelledBy();
       return {
         id: decrementId,
-        "aria-label": `Decrease ${getLabelText()}`,
+        type: "button",
+        "aria-label": `Decrease ${fieldLabel()}`.trim(),
+        "aria-labelledby": labelledBy ? `${decrementId} ${labelledBy}` : undefined,
         "aria-controls": inputId,
         excludeFromTabOrder: true,
         preventFocusOnPress: true,
         allowFocusWhenDisabled: true,
+        get disabled() {
+          return !state.canDecrement();
+        },
+        tabIndex: -1,
         get isDisabled() {
           return !state.canDecrement();
         },
+        onClick: onDecrementClick,
         onPressStart: onDecrementPressStart,
         onPressUp: onDecrementPressUp,
         onPressEnd: onDecrementPressEnd,

package/src/popover/calculatePosition.ts

@@ -78,6 +78,8 @@ export interface PositionOpts {
   crossOffset: number;
   maxHeight?: number;
   arrowBoundaryOffset?: number;
+  /** Overrides the target element's measured rect (e.g. position relative to a cursor point). */
+  targetRect?: Offset | null | undefined;
 }
 
 type HeightGrowthDirection = "top" | "bottom";
@@ -627,8 +629,12 @@ export function getRect(node: Element, ignoreScale: boolean) {
   return { top, left, width, height };
 }
 
-function getElementOffset(node: Element, ignoreScale: boolean): Offset {
-  const { top, left, width, height } = getRect(node, ignoreScale);
+function getElementOffset(
+  node: Element,
+  ignoreScale: boolean,
+  overrideRect?: Offset | null,
+): Offset {
+  const { top, left, width, height } = overrideRect || getRect(node, ignoreScale);
   const { scrollTop, scrollLeft, clientTop, clientLeft } = document.documentElement;
   return {
     top: top + scrollTop - clientTop,
@@ -638,13 +644,18 @@ function getElementOffset(node: Element, ignoreScale: boolean): Offset {
   };
 }
 
-function getPosition(node: Element, parent: Element, ignoreScale: boolean): Offset {
+function getPosition(
+  node: Element,
+  parent: Element,
+  ignoreScale: boolean,
+  overrideRect?: Offset | null,
+): Offset {
   const style = window.getComputedStyle(node);
   let offset: Offset;
   if (style.position === "fixed") {
-    offset = getRect(node, ignoreScale);
+    offset = overrideRect || getRect(node, ignoreScale);
   } else {
-    offset = getElementOffset(node, ignoreScale);
+    offset = getElementOffset(node, ignoreScale, overrideRect);
     const parentOffset = getElementOffset(parent, ignoreScale);
     const parentStyle = window.getComputedStyle(parent);
     parentOffset.top +=
@@ -712,6 +723,7 @@ export function calculatePosition(opts: PositionOpts): PositionResult {
     maxHeight,
     arrowSize,
     arrowBoundaryOffset = 0,
+    targetRect,
   } = opts;
 
   const visualViewport = getVisualViewport();
@@ -721,8 +733,8 @@ export function calculatePosition(opts: PositionOpts): PositionResult {
   const containerPositionStyle = window.getComputedStyle(container).position;
   const isContainerPositioned = !!containerPositionStyle && containerPositionStyle !== "static";
   const childOffset: Offset = isViewportContainer
-    ? getElementOffset(targetNode, false)
-    : getPosition(targetNode, container, false);
+    ? getElementOffset(targetNode, false, targetRect)
+    : getPosition(targetNode, container, false, targetRect);
 
   if (!isViewportContainer) {
     const { marginTop, marginLeft } = window.getComputedStyle(targetNode);

package/src/popover/createOverlayPosition.ts

@@ -94,6 +94,14 @@ export interface AriaPositionProps extends PositionProps {
    * @default 0
    */
   arrowBoundaryOffset?: number;
+  /**
+   * Overrides the target element's bounding rectangle. Useful for positioning relative to
+   * a specific point such as the mouse cursor (e.g. context menus) or text selection.
+   *
+   * @default target.getBoundingClientRect()
+   * @param target - The target element.
+   */
+  getTargetRect?: (target: Element) => DOMRect | null | undefined;
 }
 
 export interface PositionAria {
@@ -192,6 +200,7 @@ export function createOverlayPosition(props: AriaPositionProps): PositionAria {
       maxHeight: maxHeight(),
       arrowSize: arrowSize() ?? (arrowNode ? getRect(arrowNode, true).width : 0),
       arrowBoundaryOffset: arrowBoundaryOffset(),
+      targetRect: props.getTargetRect?.(targetNode),
     });
 
     if (!result.position) {

package/src/radio/createRadio.ts

@@ -14,6 +14,7 @@ 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";
@@ -62,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. */
@@ -133,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();
 
@@ -267,6 +270,10 @@ export function createRadio(
 
   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(),
@@ -276,10 +283,17 @@ export function createRadio(
       const p = getProps();
       const groupData = getGroupData();
 
+      // 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"]);
       }
+      const ownDescriptionId = descriptionId();
+      if (ownDescriptionId) {
+        describedByIds.push(ownDescriptionId);
+      }
       if (state.isInvalid && groupData?.errorMessageId) {
         describedByIds.push(groupData.errorMessageId);
       }
@@ -302,6 +316,9 @@ export function createRadio(
         "aria-describedby": ariaDescribedBy,
       }) as JSX.InputHTMLAttributes<HTMLInputElement>;
     },
+    get descriptionProps() {
+      return { id: descriptionId() };
+    },
     isDisabled: isDisabled(),
     isSelected,
     isPressed: combinedIsPressed,

package/src/select/createSelect.ts

@@ -344,15 +344,21 @@ export function createSelect<T>(
 
   // Handle focus events
   const handleFocus = (e: FocusEvent) => {
-    state.setFocused(true);
     getProps().onFocus?.(e);
     getProps().onFocusChange?.(true);
+    state.setFocused(true);
   };
 
   const handleBlur = (e: FocusEvent) => {
-    state.setFocused(false);
+    // Focus moving into the open listbox is not a select blur; the menu's own
+    // onBlur clears the state when focus leaves the listbox entirely.
+    if (state.isOpen()) {
+      return;
+    }
+
     getProps().onBlur?.(e);
     getProps().onFocusChange?.(false);
+    state.setFocused(false);
   };
 
   return {
@@ -410,6 +416,16 @@ export function createSelect<T>(
         "aria-labelledby": buttonId,
         "aria-multiselectable": state.selectionMode() === "multiple" ? true : undefined,
         tabIndex: -1,
+        onBlur: (e: FocusEvent) => {
+          // Only a blur that leaves the listbox entirely blurs the select.
+          if ((e.currentTarget as Node | null)?.contains(e.relatedTarget as Node)) {
+            return;
+          }
+
+          getProps().onBlur?.(e);
+          getProps().onFocusChange?.(false);
+          state.setFocused(false);
+        },
       } as JSX.HTMLAttributes<HTMLElement>;
     },
     get descriptionProps() {

package/src/selection/DOMLayoutDelegate.ts

@@ -0,0 +1,102 @@
+/**
+ * DOMLayoutDelegate - reads layout information for collection items directly
+ * from the DOM, used by {@link ListKeyboardDelegate} for page up/down
+ * navigation. Based on @react-aria/selection's `DOMLayoutDelegate`.
+ *
+ * React → Solid adaptation: the layout delegate captures a Solid ref accessor
+ * (`() => HTMLElement | null`) instead of a React `RefObject`; everything else
+ * is a faithful port.
+ */
+
+import type { Accessor } from "solid-js";
+import type { Key } from "@proyecto-viviana/solid-stately";
+import { getItemElement } from "./utils";
+
+/** A rectangle in the collection's scroll coordinate space. */
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** The size of the collection's scrollable content. */
+export interface Size {
+  width: number;
+  height: number;
+}
+
+/**
+ * Provides layout information about the items in a collection. By default this
+ * is read from the DOM (see {@link DOMLayoutDelegate}), but a virtualized
+ * collection can supply its own implementation. Mirrors @react-types/shared's
+ * `LayoutDelegate`, scoped to the members that selection navigation consumes.
+ */
+export interface LayoutDelegate {
+  /** Returns the rectangle for the item with the given key, in scroll coordinates. */
+  getItemRect(key: Key): Rect | null;
+  /** Returns the total size of the scrollable content. */
+  getContentSize(): Size;
+  /** Returns the currently visible rectangle (the scroll viewport). */
+  getVisibleRect(): Rect;
+  /** Returns the keys between two keys (inclusive), if known without walking the collection. */
+  getKeyRange?(from: Key, to: Key): Key[];
+  /** Returns the key spatially to the left of the given key, if known. */
+  getKeyLeftOf?(key: Key): Key | null;
+  /** Returns the key spatially to the right of the given key, if known. */
+  getKeyRightOf?(key: Key): Key | null;
+  /** Returns the key spatially above the given key, if known. */
+  getKeyAbove?(key: Key): Key | null;
+  /** Returns the key spatially below the given key, if known. */
+  getKeyBelow?(key: Key): Key | null;
+}
+
+/**
+ * A {@link LayoutDelegate} that measures items via the DOM.
+ */
+export class DOMLayoutDelegate implements LayoutDelegate {
+  private ref: Accessor<HTMLElement | null>;
+
+  constructor(ref: Accessor<HTMLElement | null>) {
+    this.ref = ref;
+  }
+
+  getItemRect(key: Key): Rect | null {
+    const container = this.ref();
+    if (!container) {
+      return null;
+    }
+    const item = key != null ? getItemElement(this.ref, key) : null;
+    if (!item) {
+      return null;
+    }
+
+    const containerRect = container.getBoundingClientRect();
+    const itemRect = item.getBoundingClientRect();
+
+    return {
+      x: itemRect.left - containerRect.left - container.clientLeft + container.scrollLeft,
+      y: itemRect.top - containerRect.top - container.clientTop + container.scrollTop,
+      width: itemRect.width,
+      height: itemRect.height,
+    };
+  }
+
+  getContentSize(): Size {
+    const container = this.ref();
+    return {
+      width: container?.scrollWidth ?? 0,
+      height: container?.scrollHeight ?? 0,
+    };
+  }
+
+  getVisibleRect(): Rect {
+    const container = this.ref();
+    return {
+      x: container?.scrollLeft ?? 0,
+      y: container?.scrollTop ?? 0,
+      width: container?.clientWidth ?? 0,
+      height: container?.clientHeight ?? 0,
+    };
+  }
+}