@proyecto-viviana/solidaria 0.3.0 → 0.4.1

package/src/spinbutton/createSpinButton.ts

@@ -0,0 +1,163 @@
+/**
+ * createSpinButton hook for Solidaria
+ *
+ * Provides the ARIA spinbutton props and live-region announcement behaviour for
+ * a single spinbutton (e.g. a date-field segment). Port of the keyboard/announce
+ * portion of @react-aria/spinbutton `useSpinButton`. The pointer press-and-hold
+ * button machinery (increment/decrement buttons) is intentionally omitted — date
+ * segments drive value changes through the keyboard only.
+ */
+
+import { createMemo, createEffect } from "solid-js";
+import { access, type MaybeAccessor } from "../utils/reactivity";
+import { createStringFormatter } from "../i18n";
+import { announce, clearAnnouncer } from "../live-announcer";
+import { spinButtonStrings, type SpinButtonStringKey } from "./intl";
+
+export interface SpinButtonProps {
+  /** The current value of the spinbutton. */
+  value?: number;
+  /** A human-readable text alternative for the value. */
+  textValue?: string;
+  /** The smallest value allowed. */
+  minValue?: number;
+  /** The largest value allowed. */
+  maxValue?: number;
+  /** Whether the spinbutton is disabled. */
+  isDisabled?: boolean;
+  /** Whether the spinbutton is read only. */
+  isReadOnly?: boolean;
+  /** Whether the spinbutton is required. */
+  isRequired?: boolean;
+  onIncrement?: () => void;
+  onIncrementPage?: () => void;
+  onDecrement?: () => void;
+  onDecrementPage?: () => void;
+  onDecrementToMin?: () => void;
+  onIncrementToMax?: () => void;
+}
+
+export interface SpinButtonAria {
+  /** Props for the spinbutton element. */
+  spinButtonProps: Record<string, unknown>;
+}
+
+/**
+ * Provides the behaviour and accessibility implementation for a spinbutton.
+ */
+export function createSpinButton(props: MaybeAccessor<SpinButtonProps>): SpinButtonAria {
+  const getProps = () => access(props);
+  const stringFormatter = createStringFormatter<SpinButtonStringKey>(
+    spinButtonStrings,
+    "@react-aria/spinbutton",
+  );
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    const p = getProps();
+    if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey || p.isReadOnly || e.isComposing) {
+      return;
+    }
+
+    switch (e.key) {
+      // Upstream deliberately falls through PageUp → ArrowUp when no page
+      // handler exists; our tsconfig forbids lexical fallthrough, so the
+      // PageUp case mirrors that branch inline instead.
+      case "PageUp":
+        if (p.onIncrementPage) {
+          e.preventDefault();
+          p.onIncrementPage();
+        } else if (p.onIncrement) {
+          e.preventDefault();
+          p.onIncrement();
+        }
+        break;
+      case "ArrowUp":
+      case "Up":
+        if (p.onIncrement) {
+          e.preventDefault();
+          p.onIncrement();
+        }
+        break;
+      // Same faithful fallthrough as PageUp, mirrored inline (PageDown → ArrowDown).
+      case "PageDown":
+        if (p.onDecrementPage) {
+          e.preventDefault();
+          p.onDecrementPage();
+        } else if (p.onDecrement) {
+          e.preventDefault();
+          p.onDecrement();
+        }
+        break;
+      case "ArrowDown":
+      case "Down":
+        if (p.onDecrement) {
+          e.preventDefault();
+          p.onDecrement();
+        }
+        break;
+      case "Home":
+        if (p.onDecrementToMin) {
+          e.preventDefault();
+          p.onDecrementToMin();
+        }
+        break;
+      case "End":
+        if (p.onIncrementToMax) {
+          e.preventDefault();
+          p.onIncrementToMax();
+        }
+        break;
+    }
+  };
+
+  // Non-reactive focus flag — matches upstream's `isFocused` ref. Toggling it must
+  // NOT re-run the announce effect; only a change in `ariaTextValue` announces.
+  let isFocused = false;
+  const onFocus = () => {
+    isFocused = true;
+  };
+  const onBlur = () => {
+    isFocused = false;
+  };
+
+  // Replace Unicode hyphen-minus (U+002D) with minus sign (U+2212) so VoiceOver
+  // announces it as "minus". Replace the empty string with the word "Empty".
+  const ariaTextValue = createMemo(() => {
+    const p = getProps();
+    return p.textValue === ""
+      ? stringFormatter().format("Empty")
+      : (p.textValue || `${p.value}`).replace("-", "−");
+  });
+
+  createEffect(() => {
+    const value = ariaTextValue();
+    if (isFocused) {
+      clearAnnouncer("assertive");
+      announce(value, "assertive");
+    }
+  });
+
+  const spinButtonProps = createMemo(() => {
+    const p = getProps();
+    const value = p.value;
+    return {
+      role: "spinbutton",
+      "aria-valuenow": value !== undefined && !isNaN(value) ? value : undefined,
+      "aria-valuetext": ariaTextValue(),
+      "aria-valuemin": p.minValue,
+      "aria-valuemax": p.maxValue,
+      "aria-disabled": p.isDisabled || undefined,
+      "aria-readonly": p.isReadOnly || undefined,
+      "aria-required": p.isRequired || undefined,
+      onKeyDown,
+      onFocus,
+      onBlur,
+    };
+  });
+
+  return {
+    get spinButtonProps() {
+      return spinButtonProps();
+    },
+  };
+}

package/src/spinbutton/index.ts

@@ -0,0 +1,10 @@
+export {
+  createSpinButton,
+  type SpinButtonProps,
+  type SpinButtonAria,
+} from "./createSpinButton";
+export {
+  spinButtonStrings,
+  spinButtonDictionary,
+  type SpinButtonStringKey,
+} from "./intl";

package/src/spinbutton/intl.ts

@@ -0,0 +1,115 @@
+// Spinbutton announcement catalog, ported verbatim from @react-aria/spinbutton's
+// intl/*.json (34 locales). Keep in sync with the vendored react-spectrum source on
+// every pin bump.
+import { LocalizedStringDictionary } from "@internationalized/string";
+
+export type SpinButtonStringKey = "Empty";
+
+export const spinButtonStrings: Record<string, Record<SpinButtonStringKey, string>> = {
+  "ar-AE": {
+  "Empty": `\u{641}\u{627}\u{631}\u{63A}`
+  },
+  "bg-BG": {
+  "Empty": `\u{418}\u{437}\u{43F}\u{440}\u{430}\u{437}\u{43D}\u{438}`
+  },
+  "cs-CZ": {
+  "Empty": `Pr\xe1zdn\xe9`
+  },
+  "da-DK": {
+  "Empty": `Tom`
+  },
+  "de-DE": {
+  "Empty": `Leer`
+  },
+  "el-GR": {
+  "Empty": `\u{386}\u{3B4}\u{3B5}\u{3B9}\u{3BF}`
+  },
+  "en-US": {
+  "Empty": `Empty`
+  },
+  "es-ES": {
+  "Empty": `Vac\xedo`
+  },
+  "et-EE": {
+  "Empty": `T\xfchjenda`
+  },
+  "fi-FI": {
+  "Empty": `Tyhj\xe4`
+  },
+  "fr-FR": {
+  "Empty": `Vide`
+  },
+  "he-IL": {
+  "Empty": `\u{5E8}\u{5D9}\u{5E7}`
+  },
+  "hr-HR": {
+  "Empty": `Prazno`
+  },
+  "hu-HU": {
+  "Empty": `\xdcres`
+  },
+  "it-IT": {
+  "Empty": `Vuoto`
+  },
+  "ja-JP": {
+  "Empty": `\u{7A7A}`
+  },
+  "ko-KR": {
+  "Empty": `\u{BE44}\u{C5B4} \u{C788}\u{C74C}`
+  },
+  "lt-LT": {
+  "Empty": `Tu\u{161}\u{10D}ias`
+  },
+  "lv-LV": {
+  "Empty": `Tuk\u{161}s`
+  },
+  "nb-NO": {
+  "Empty": `Tom`
+  },
+  "nl-NL": {
+  "Empty": `Leeg`
+  },
+  "pl-PL": {
+  "Empty": `Pusty`
+  },
+  "pt-BR": {
+  "Empty": `Vazio`
+  },
+  "pt-PT": {
+  "Empty": `Vazio`
+  },
+  "ro-RO": {
+  "Empty": `Gol`
+  },
+  "ru-RU": {
+  "Empty": `\u{41D}\u{435} \u{437}\u{430}\u{43F}\u{43E}\u{43B}\u{43D}\u{435}\u{43D}\u{43E}`
+  },
+  "sk-SK": {
+  "Empty": `Pr\xe1zdne`
+  },
+  "sl-SI": {
+  "Empty": `Prazen`
+  },
+  "sr-SP": {
+  "Empty": `Prazno`
+  },
+  "sv-SE": {
+  "Empty": `Tomt`
+  },
+  "tr-TR": {
+  "Empty": `Bo\u{15F}`
+  },
+  "uk-UA": {
+  "Empty": `\u{41F}\u{443}\u{441}\u{442}\u{43E}`
+  },
+  "zh-CN": {
+  "Empty": `\u{7A7A}`
+  },
+  "zh-TW": {
+  "Empty": `\u{7A7A}\u{767D}`
+  },
+};
+
+export const spinButtonDictionary = new LocalizedStringDictionary<SpinButtonStringKey, string>(
+  spinButtonStrings,
+);

package/src/ssr/index.tsx

@@ -80,6 +80,37 @@ export function createId(defaultId?: string): string {
   return ctx.prefix ? `solidaria-${ctx.prefix}-${uniqueId}` : `solidaria-${uniqueId}`;
 }
 
+/**
+ * Generates an id, but only resolves to it once an element with that id is
+ * actually present in the DOM. Returns `undefined` otherwise.
+ *
+ * This is a 1:1 port of @react-aria/utils's `useSlotId`. It exists so that an
+ * `aria-labelledby` can point at an optional slot (e.g. a section header) and
+ * automatically fall back to `undefined` when the slot is not rendered, instead
+ * of leaving a dangling reference to a non-existent id.
+ *
+ * The initial value is the generated id so that server and first client render
+ * agree (no hydration mismatch); a client-only effect then probes the DOM and
+ * clears the value when no matching element exists.
+ *
+ * @param deps - Accessors re-probed when their values change (mirrors the
+ *   dependency array of the upstream hook).
+ */
+export function createSlotId(deps: Array<Accessor<unknown>> = []): Accessor<string | undefined> {
+  const id = createId();
+  const [resolvedId, setResolvedId] = createSignal<string | undefined>(id);
+
+  createEffect(() => {
+    // Re-probe when any explicit dependency changes.
+    for (const dep of deps) {
+      dep();
+    }
+    setResolvedId(document.getElementById(id) ? id : undefined);
+  });
+
+  return resolvedId;
+}
+
 /**
  * Provides SSR context to the component tree.
  *

package/src/switch/createSwitch.ts

@@ -21,6 +21,10 @@ export interface SwitchAria {
   labelProps: JSX.LabelHTMLAttributes<HTMLLabelElement>;
   /** Props for the input element. */
   inputProps: JSX.InputHTMLAttributes<HTMLInputElement>;
+  /** Props for the switch description element, if any. */
+  descriptionProps: JSX.HTMLAttributes<HTMLElement>;
+  /** Props for the switch error message element, if any. */
+  errorMessageProps: JSX.HTMLAttributes<HTMLElement>;
   /** Whether the switch is selected. */
   isSelected: Accessor<boolean>;
   /** Whether the switch is in a pressed state. */
@@ -56,6 +60,12 @@ export function createSwitch(
         checked: toggle.isSelected(),
       };
     },
+    get descriptionProps() {
+      return toggle.descriptionProps;
+    },
+    get errorMessageProps() {
+      return toggle.errorMessageProps;
+    },
     isSelected: toggle.isSelected,
     isPressed: toggle.isPressed,
     isDisabled: toggle.isDisabled,

package/src/table/createTable.ts

@@ -10,6 +10,9 @@ import type { TableState, TableCollection, Key, GridNode } from "@proyecto-vivia
 import type { AriaTableProps, TableAria } from "./types";
 import { useLocale } from "../i18n";
 import { announce } from "../live-announcer";
+import { createDescription } from "../utils/createDescription";
+import { scrollIntoViewport } from "../utils";
+import { getInteractionModality } from "../interactions/createInteractionModality";
 
 // Global map to store table metadata for child components
 const tableMap = new WeakMap<
@@ -63,13 +66,6 @@ function isRow<T>(node: GridNode<T> | null): boolean {
   return node?.type === "item";
 }
 
-function focusCurrentElement(el: HTMLElement | null | undefined) {
-  const target = el?.querySelector<HTMLElement>(
-    '[role="row"][tabindex="0"], [role="rowheader"][tabindex="0"], [role="gridcell"][tabindex="0"], [role="columnheader"][tabindex="0"]',
-  );
-  target?.focus();
-}
-
 /**
  * Creates accessibility props for a table component.
  */
@@ -146,13 +142,20 @@ export function createTable<T extends object>(
     const isRTL = locale().direction === "rtl";
     const setFocusedKey = (key: Key) => {
       s.setFocusedKey(key);
-      queueMicrotask(() => focusCurrentElement(ref()));
     };
     const runTypeahead = (focusedKey: Key, focusedItem: GridNode<T>) => {
       if (e.key.length !== 1 || e.ctrlKey || e.metaKey || e.altKey) {
         return false;
       }
 
+      // A leading Spacebar is a selection/action key, not the start of a type-ahead
+      // search. Mirror upstream useTypeSelect (`search.length === 0 && character === ' '`)
+      // and let it fall through so the focused row's own Space handler toggles selection.
+      // Once a search is active, Space continues the query as normal.
+      if (e.key === " " && typeaheadBuffer.length === 0) {
+        return false;
+      }
+
       typeaheadBuffer += e.key.toLocaleLowerCase();
       if (typeaheadTimeout) {
         clearTimeout(typeaheadTimeout);
@@ -478,24 +481,12 @@ export function createTable<T extends object>(
         }
         return;
 
-      case " ":
-      case "Enter":
-        e.preventDefault();
-        // Toggle selection or trigger action
-        if (s.selectionMode !== "none") {
-          // For cells, select the parent row
-          const keyToSelect =
-            isCell(focusedItem) && focusedItem.parentKey != null
-              ? focusedItem.parentKey
-              : focusedKey;
-
-          if (e.shiftKey && s.selectionMode === "multiple") {
-            s.extendSelection(keyToSelect);
-          } else {
-            s.toggleSelection(keyToSelect);
-          }
-        }
-        return;
+      // NOTE: Space/Enter selection is intentionally NOT handled here. Upstream
+      // useSelectableCollection has no ' '/Enter case — keyboard selection is owned
+      // by the row (useSelectableItem, ported in createTableRow). Handling it here too
+      // double-toggled the selection (row toggles on, grid toggles back off → no-op),
+      // since the row handler does not stop propagation. Space/Enter fall through to
+      // the type-ahead path below, which ignores a leading Space and bails on Enter.
 
       default:
         if (runTypeahead(focusedKey, focusedItem)) {
@@ -552,6 +543,46 @@ export function createTable<T extends object>(
     }
   };
 
+  // Mirror React Aria's useSelectableCollection: once the roving tabindex for
+  // the focused key has been committed to the DOM, move browser focus onto that
+  // element from a post-commit effect — looking it up by its stable data-key
+  // rather than by transient tabindex. Doing this imperatively during the key
+  // handler (in a microtask) raced Solid's reconciliation and dropped focus to
+  // <body>, so Space/Enter never reached the grid's selection handler.
+  createEffect(() => {
+    const s = state();
+    const key = s.focusedKey;
+    const el = ref();
+    if (!el || key == null) {
+      return;
+    }
+
+    // Only manage focus while it already lives inside the table — i.e. the user
+    // is navigating with the keyboard. We gate on the *physical* position of
+    // browser focus rather than the grid's logical `isFocused` signal: focus can
+    // land directly on a row (a pointer click, or programmatic row focus) without
+    // ever firing the grid's own non-bubbling focus handler, so `isFocused` stays
+    // false even though the table genuinely holds focus. The contains() check is
+    // also what keeps us from pulling focus back from elsewhere on the page when
+    // the focused key changes from a background interaction.
+    const active = document.activeElement;
+    if (!active || (active !== el && !el.contains(active))) {
+      return;
+    }
+
+    const target = el.querySelector<HTMLElement>(`[data-key="${key}"]`);
+    if (target && target !== active) {
+      target.focus();
+
+      // Reveal the newly focused row/cell when navigating with the keyboard,
+      // mirroring useSelectableCollection. Pointer-driven focus changes should
+      // not shift the scroll position under the user's finger.
+      if (getInteractionModality() !== "pointer") {
+        scrollIntoViewport(target, { containingElement: el });
+      }
+    }
+  });
+
   // Warn if no label is provided
   createMemo(() => {
     const p = props();
@@ -560,16 +591,40 @@ export function createTable<T extends object>(
     }
   });
 
+  // A sorted table exposes a persistent sort description on the grid ("sorted by
+  // column {name} in {direction} order"), mirroring `useTable`'s
+  // `useDescription(sortDescription)` — separate from the transient live-region
+  // announcement above. `columnName` follows upstream exactly
+  // (`columns.find(c => c.key === column)?.textValue ?? ''`) so a header with no
+  // plain-text value yields an empty name, matching the S2 oracle.
+  const sortDescription = () => {
+    const s = state();
+    const descriptor = s.sortDescriptor;
+    const column = descriptor?.column;
+    const direction = descriptor?.direction;
+    if (!direction || column == null) {
+      return undefined;
+    }
+    const columnName = s.collection.columns.find((c) => c.key === column)?.textValue ?? "";
+    return `sorted by column ${columnName} in ${direction} order`;
+  };
+  const sortDescriptionProps = createDescription(sortDescription);
+
   const gridProps = createMemo(() => {
     const p = props();
     const s = state();
 
+    const describedBy =
+      [sortDescriptionProps["aria-describedby"], p["aria-describedby"]]
+        .filter(Boolean)
+        .join(" ") || undefined;
+
     const baseProps: Record<string, unknown> = {
       role: "grid",
       id,
       "aria-label": p["aria-label"],
       "aria-labelledby": p["aria-labelledby"],
-      "aria-describedby": p["aria-describedby"],
+      "aria-describedby": describedBy,
       "aria-multiselectable": s.selectionMode === "multiple" ? "true" : undefined,
       // Keep the grid itself tabbable so keyboard users can enter
       // row/cell navigation without requiring a prior pointer interaction.

package/src/table/createTableColumnHeader.ts

@@ -8,6 +8,7 @@ import type { JSX } from "solid-js";
 import type { TableState, TableCollection } from "@proyecto-viviana/solid-stately";
 import type { AriaTableColumnHeaderProps, TableColumnHeaderAria } from "./types";
 import { getTableData } from "./createTable";
+import { createDescription } from "../utils/createDescription";
 
 /**
  * Creates accessibility props for a table column header.
@@ -27,6 +28,14 @@ export function createTableColumnHeader<T extends object>(
     return s.focusedKey === p.node.key;
   });
 
+  // A sortable column header is described as "sortable column" — mirrors
+  // `useTableColumnHeader`'s `useDescription(stringFormatter.format('sortable'))`.
+  // Backed by a shared hidden element (ref-counted) and referenced via
+  // aria-describedby.
+  const sortDescriptionProps = createDescription(() =>
+    props().allowsSorting ? "sortable column" : undefined,
+  );
+
   const sortColumn = () => {
     const s = state();
     const p = props();
@@ -125,6 +134,7 @@ export function createTableColumnHeader<T extends object>(
       role: "columnheader",
       id: tableData ? `${tableData.tableId}-${node.key}` : undefined,
       "aria-sort": ariaSort,
+      "aria-describedby": sortDescriptionProps["aria-describedby"],
       tabIndex: isFocused() ? 0 : -1,
       onFocus,
     };