@proyecto-viviana/solidaria 0.2.5 → 0.3.0

package/src/tree/index.ts

@@ -1,16 +1,16 @@
-/**
- * Tree ARIA layer exports.
- */
-
-export { createTree, getTreeData } from './createTree';
-export { createTreeItem } from './createTreeItem';
-export { createTreeSelectionCheckbox } from './createTreeSelectionCheckbox';
-
-export type {
-  AriaTreeProps,
-  TreeAria,
-  AriaTreeItemProps,
-  TreeItemAria,
-  AriaTreeSelectionCheckboxProps,
-  TreeSelectionCheckboxAria,
-} from './types';
+/**
+ * Tree ARIA layer exports.
+ */
+
+export { createTree, getTreeData } from "./createTree";
+export { createTreeItem } from "./createTreeItem";
+export { createTreeSelectionCheckbox } from "./createTreeSelectionCheckbox";
+
+export type {
+  AriaTreeProps,
+  TreeAria,
+  AriaTreeItemProps,
+  TreeItemAria,
+  AriaTreeSelectionCheckboxProps,
+  TreeSelectionCheckboxAria,
+} from "./types";

package/src/tree/types.ts

@@ -1,87 +1,95 @@
-/**
- * Tree ARIA types.
- * Based on @react-aria/tree.
- */
-
-import type { JSX } from 'solid-js';
-import type { Key, TreeNode } from '@proyecto-viviana/solid-stately';
-
-/**
- * Props for createTree.
- */
-export interface AriaTreeProps {
-  /** The unique id for the tree. */
-  id?: string;
-  /** Label for accessibility. */
-  'aria-label'?: string;
-  /** ID of an element that labels the tree. */
-  'aria-labelledby'?: string;
-  /** ID of an element that describes the tree. */
-  'aria-describedby'?: string;
-  /** Whether the tree is virtualized. */
-  isVirtualized?: boolean;
-  /** Handler called when an item action is triggered. */
-  onAction?: (key: Key) => void;
-  /** Whether the tree is disabled. */
-  isDisabled?: boolean;
-}
-
-/**
- * Return value for createTree.
- */
-export interface TreeAria {
-  /** Props for the tree container (role="treegrid"). */
-  treeProps: JSX.HTMLAttributes<HTMLDivElement>;
-}
-
-/**
- * Props for createTreeItem.
- */
-export interface AriaTreeItemProps<T = unknown> {
-  /** The tree node this item represents. */
-  node: TreeNode<T>;
-  /** Whether the item is rendered in a virtualized list. */
-  isVirtualized?: boolean;
-  /** Handler called when this item's action is triggered. */
-  onAction?: () => void;
-}
-
-/**
- * Return value for createTreeItem.
- */
-export interface TreeItemAria {
-  /** Props for the row element. */
-  rowProps: JSX.HTMLAttributes<HTMLDivElement>;
-  /** Props for the grid cell content wrapper. */
-  gridCellProps: JSX.HTMLAttributes<HTMLDivElement>;
-  /** Props for the expand button (if the item is expandable). */
-  expandButtonProps: JSX.ButtonHTMLAttributes<HTMLButtonElement>;
-  /** Whether the item is selected. */
-  isSelected: boolean;
-  /** Whether the item is disabled. */
-  isDisabled: boolean;
-  /** Whether the item is being pressed. */
-  isPressed: boolean;
-  /** Whether the item is expanded. */
-  isExpanded: boolean;
-  /** Whether the item is expandable (has children). */
-  isExpandable: boolean;
-  /** The nesting level of the item (0 for root). */
-  level: number;
-}
-
-/**
- * Props for createTreeSelectionCheckbox.
- */
-export interface AriaTreeSelectionCheckboxProps {
-  /** The key of the tree item this checkbox belongs to. */
-  key: Key;
-}
-
-/**
- * Return value for createTreeSelectionCheckbox.
- */
-export interface TreeSelectionCheckboxAria {
-  /** Props for the checkbox input element. */
-  checkboxProps: JSX.InputHTMLAttributes<HTMLInputElement>;
-}
+/**
+ * Tree ARIA types.
+ * Based on @react-aria/tree.
+ */
+
+import type { JSX } from "solid-js";
+import type { Key, TreeNode } from "@proyecto-viviana/solid-stately";
+
+/**
+ * Props for createTree.
+ */
+export interface AriaTreeProps {
+  /** The unique id for the tree. */
+  id?: string;
+  /** Label for accessibility. */
+  "aria-label"?: string;
+  /** ID of an element that labels the tree. */
+  "aria-labelledby"?: string;
+  /** ID of an element that describes the tree. */
+  "aria-describedby"?: string;
+  /** Whether the tree is virtualized. */
+  isVirtualized?: boolean;
+  /** Handler called when an item action is triggered. */
+  onAction?: (key: Key) => void;
+  /** Whether the tree is disabled. */
+  isDisabled?: boolean;
+  /** The writing direction for the tree. Determines expand/collapse key mapping. */
+  direction?: "ltr" | "rtl";
+}
+
+/**
+ * Return value for createTree.
+ */
+export interface TreeAria {
+  /** Props for the tree container (role="treegrid"). */
+  treeProps: JSX.HTMLAttributes<HTMLDivElement>;
+}
+
+/**
+ * Props for createTreeItem.
+ */
+export interface AriaTreeItemProps<T = unknown> {
+  /** The tree node this item represents. */
+  node: TreeNode<T>;
+  /** Whether the item is rendered in a virtualized list. */
+  isVirtualized?: boolean;
+  /** How selection should behave when pressing an item. */
+  selectionBehavior?: "replace" | "toggle";
+  /** Handler called when this item's action is triggered. */
+  onAction?: () => void;
+  /** Whether this item is disabled. */
+  isDisabled?: boolean;
+  /** The text value for the item (used for aria-label on the row). */
+  textValue?: string;
+}
+
+/**
+ * Return value for createTreeItem.
+ */
+export interface TreeItemAria {
+  /** Props for the row element. */
+  rowProps: JSX.HTMLAttributes<HTMLDivElement>;
+  /** Props for the grid cell content wrapper. */
+  gridCellProps: JSX.HTMLAttributes<HTMLDivElement>;
+  /** Props for the expand button (if the item is expandable). */
+  expandButtonProps: JSX.ButtonHTMLAttributes<HTMLButtonElement>;
+  /** Whether the item is selected. */
+  isSelected: boolean;
+  /** Whether the item is disabled. */
+  isDisabled: boolean;
+  /** Whether the item is being pressed. */
+  isPressed: boolean;
+  /** Whether the item is expanded. */
+  isExpanded: boolean;
+  /** Whether the item is expandable (has children). */
+  isExpandable: boolean;
+  /** The nesting level of the item (0 for root). */
+  level: number;
+}
+
+/**
+ * Props for createTreeSelectionCheckbox.
+ */
+export interface AriaTreeSelectionCheckboxProps {
+  /** The key of the tree item this checkbox belongs to. */
+  key: Key;
+}
+
+/**
+ * Return value for createTreeSelectionCheckbox.
+ */
+export interface TreeSelectionCheckboxAria {
+  /** Props for the checkbox input element. */
+  checkboxProps: JSX.InputHTMLAttributes<HTMLInputElement>;
+}

package/src/utils/createDescription.ts

@@ -23,28 +23,16 @@
  * ```
  */
 
-import { createSignal, createEffect, onCleanup, type Accessor } from 'solid-js';
-import { isServer } from 'solid-js/web';
-
-// ============================================
-// TYPES
-// ============================================
+import { createSignal, createEffect, onCleanup, type Accessor } from "solid-js";
+import { isServer } from "solid-js/web";
 
 export interface DescriptionProps {
-  'aria-describedby'?: string;
+  "aria-describedby"?: string;
 }
 
-// ============================================
-// STATE
-// ============================================
-
 let descriptionId = 0;
 const descriptionNodes = new Map<string, { refCount: number; element: Element }>();
 
-// ============================================
-// IMPLEMENTATION
-// ============================================
-
 /**
  * Creates an invisible description element and returns aria-describedby props.
  *
@@ -62,7 +50,6 @@ const descriptionNodes = new Map<string, { refCount: number; element: Element }>
  * ```
  */
 export function createDescription(description: Accessor<string | undefined>): DescriptionProps {
-  // SSR: return empty object
   if (isServer) {
     return {};
   }
@@ -80,26 +67,23 @@ export function createDescription(description: Accessor<string | undefined>): De
     let node = descriptionNodes.get(desc);
 
     if (!node) {
-      // Create new description element
       const newId = `solidaria-description-${descriptionId++}`;
       setId(newId);
 
-      const element = document.createElement('div');
+      const element = document.createElement("div");
       element.id = newId;
-      element.style.display = 'none';
+      element.style.display = "none";
       element.textContent = desc;
       document.body.appendChild(element);
 
       node = { refCount: 0, element };
       descriptionNodes.set(desc, node);
     } else {
-      // Reuse existing element
       setId(node.element.id);
     }
 
     node.refCount++;
 
-    // Cleanup when description changes or component unmounts
     onCleanup(() => {
       if (node && --node.refCount === 0) {
         node.element.remove();
@@ -108,9 +92,8 @@ export function createDescription(description: Accessor<string | undefined>): De
     });
   });
 
-  // Return reactive props object
   return {
-    get 'aria-describedby'() {
+    get "aria-describedby"() {
       const desc = description();
       return desc ? id() : undefined;
     },

package/src/utils/dom.ts

@@ -54,7 +54,7 @@ export function nodeContains(parent: Node | null, child: Node | null): boolean {
  */
 export function getEventTarget<T extends EventTarget>(event: Event): T | null {
   // Use composedPath to get the real target when using Shadow DOM
-  if (typeof event.composedPath === 'function') {
+  if (typeof event.composedPath === "function") {
     const path = event.composedPath();
     if (path.length > 0) {
       return path[0] as T;
@@ -74,22 +74,26 @@ export function isFocusable(element: Element): boolean {
 
   // Check native focusable elements
   const tagName = element.tagName.toLowerCase();
-  if (['input', 'select', 'textarea', 'button', 'a', 'area'].includes(tagName)) {
+  if (["input", "select", "textarea", "button", "a", "area"].includes(tagName)) {
     // For anchor elements, they must have href to be focusable
-    if (tagName === 'a' || tagName === 'area') {
-      return element.hasAttribute('href');
+    if (tagName === "a" || tagName === "area") {
+      return element.hasAttribute("href");
     }
     return true;
   }
 
-  // Check for tabIndex
-  const tabIndex = element.getAttribute('tabindex');
-  if (tabIndex != null && tabIndex !== '-1') {
+  // A negative tabIndex is not tabbable, but it is still programmatically focusable.
+  // React Aria's focusable selector includes all tabindex values for this reason.
+  const tabIndex = element.getAttribute("tabindex");
+  if (tabIndex != null) {
     return true;
   }
 
   // Check for contenteditable
-  if (element.hasAttribute('contenteditable') && element.getAttribute('contenteditable') !== 'false') {
+  if (
+    element.hasAttribute("contenteditable") &&
+    element.getAttribute("contenteditable") !== "false"
+  ) {
     return true;
   }
 
@@ -103,16 +107,16 @@ export function isValidKeyboardEvent(event: KeyboardEvent, currentTarget: Elemen
   const { key, code } = event;
   const element = currentTarget as HTMLElement;
   const tagName = element.tagName.toLowerCase();
-  const role = element.getAttribute('role');
+  const role = element.getAttribute("role");
 
   // Only accept Enter and Space
-  const isActivationKey = key === 'Enter' || key === ' ' || key === 'Spacebar' || code === 'Space';
+  const isActivationKey = key === "Enter" || key === " " || key === "Spacebar" || code === "Space";
   if (!isActivationKey) {
     return false;
   }
 
   // Text inputs should handle their own keyboard events
-  if (tagName === 'textarea') {
+  if (tagName === "textarea") {
     return false;
   }
 
@@ -122,13 +126,13 @@ export function isValidKeyboardEvent(event: KeyboardEvent, currentTarget: Elemen
   }
 
   // Links should only respond to Enter, not Space
-  const isLink = role === 'link' || (!role && isHTMLAnchorLink(element));
-  if (isLink && key !== 'Enter') {
+  const isLink = role === "link" || (!role && isHTMLAnchorLink(element));
+  if (isLink && key !== "Enter") {
     return false;
   }
 
   // Input elements have specific key handling
-  if (tagName === 'input') {
+  if (tagName === "input") {
     return isValidInputKey(element as HTMLInputElement, key);
   }
 
@@ -142,14 +146,24 @@ export function isValidInputKey(target: HTMLInputElement, key: string): boolean
   const type = target.type.toLowerCase();
 
   // Checkbox and radio only respond to Space
-  if (type === 'checkbox' || type === 'radio') {
-    return key === ' ' || key === 'Spacebar';
+  if (type === "checkbox" || type === "radio") {
+    return key === " " || key === "Spacebar";
   }
 
   // Text-like inputs handle their own keyboard events
   const textInputTypes = [
-    'text', 'search', 'url', 'tel', 'email', 'password',
-    'date', 'month', 'week', 'time', 'datetime-local', 'number'
+    "text",
+    "search",
+    "url",
+    "tel",
+    "email",
+    "password",
+    "date",
+    "month",
+    "week",
+    "time",
+    "datetime-local",
+    "number",
   ];
   if (textInputTypes.includes(type)) {
     return false;
@@ -162,34 +176,18 @@ export function isValidInputKey(target: HTMLInputElement, key: string): boolean
  * Checks if an element is an HTML anchor link (has href attribute).
  */
 export function isHTMLAnchorLink(target: Element): boolean {
-  return target.tagName === 'A' && target.hasAttribute('href');
+  return target.tagName === "A" && target.hasAttribute("href");
 }
 
 /**
  * Whether to prevent default on keyboard events for this element.
  */
 export function shouldPreventDefaultKeyboard(target: Element, key: string): boolean {
-  const tagName = target.tagName.toLowerCase();
-
-  // Never prevent default on inputs - they handle their own behavior
-  if (tagName === 'input' || tagName === 'textarea' || tagName === 'select') {
-    return false;
-  }
-
-  // Don't prevent default on links for Enter (native navigation)
-  if ((tagName === 'a' || target.getAttribute('role') === 'link') && key === 'Enter') {
-    return false;
-  }
-
-  // Buttons with submit/reset type should not prevent default
-  if (tagName === 'button') {
-    const type = (target as HTMLButtonElement).type;
-    if (type === 'submit' || type === 'reset') {
-      return false;
-    }
+  if (target instanceof HTMLInputElement) {
+    return !isValidInputKey(target, key);
   }
 
-  return true;
+  return shouldPreventDefaultUp(target);
 }
 
 /**
@@ -199,19 +197,19 @@ export function shouldPreventDefaultUp(target: Element): boolean {
   const tagName = target.tagName.toLowerCase();
 
   // Never prevent default on form elements
-  if (tagName === 'input' || tagName === 'textarea' || tagName === 'select') {
+  if (tagName === "input" || tagName === "textarea" || tagName === "select") {
     return false;
   }
 
   // Don't prevent default on links
-  if (tagName === 'a' || target.getAttribute('role') === 'link') {
+  if (tagName === "a" || target.getAttribute("role") === "link") {
     return false;
   }
 
   // Buttons with submit/reset type should not prevent default
-  if (tagName === 'button') {
+  if (tagName === "button") {
     const type = (target as HTMLButtonElement).type;
-    if (type === 'submit' || type === 'reset') {
+    if (type === "submit" || type === "reset") {
       return false;
     }
   }
@@ -230,15 +228,15 @@ export function openLink(target: HTMLAnchorElement, event: Event, allowOpener =
   // Handle modifier keys for open-in-new-tab behavior
   const keyEvent = event as KeyboardEvent;
   const shouldOpenInNewTab =
-    linkTarget === '_blank' ||
+    linkTarget === "_blank" ||
     keyEvent?.metaKey ||
     keyEvent?.ctrlKey ||
     keyEvent?.shiftKey ||
     keyEvent?.altKey;
 
   if (shouldOpenInNewTab) {
-    const features = !allowOpener && rel?.includes('noopener') ? 'noopener' : undefined;
-    window.open(href, linkTarget || '_blank', features);
+    const features = !allowOpener && rel?.includes("noopener") ? "noopener" : undefined;
+    window.open(href, linkTarget || "_blank", features);
   } else {
     window.location.href = href;
   }
@@ -248,10 +246,6 @@ export function openLink(target: HTMLAnchorElement, event: Event, allowOpener =
 
 (openLink as { isOpening?: boolean }).isOpening = false;
 
-// ============================================
-// Scroll utilities
-// ============================================
-
 /**
  * Checks if an element is scrollable based on its overflow style.
  * @param node - The element to check
@@ -303,23 +297,36 @@ export function willOpenKeyboard(target: Element | null): boolean {
   const tagName = target.tagName.toLowerCase();
 
   // Inputs that open keyboard (not all input types do)
-  if (tagName === 'input') {
+  if (tagName === "input") {
     const type = (target as HTMLInputElement).type.toLowerCase();
     // These input types open the keyboard
     const keyboardTypes = [
-      'text', 'search', 'url', 'tel', 'email', 'password',
-      'date', 'month', 'week', 'time', 'datetime-local', 'number'
+      "text",
+      "search",
+      "url",
+      "tel",
+      "email",
+      "password",
+      "date",
+      "month",
+      "week",
+      "time",
+      "datetime-local",
+      "number",
     ];
     return keyboardTypes.includes(type);
   }
 
   // Textareas always open keyboard
-  if (tagName === 'textarea') {
+  if (tagName === "textarea") {
     return true;
   }
 
   // Contenteditable elements open keyboard
-  if (target.hasAttribute('contenteditable') && target.getAttribute('contenteditable') !== 'false') {
+  if (
+    target.hasAttribute("contenteditable") &&
+    target.getAttribute("contenteditable") !== "false"
+  ) {
     return true;
   }
 

package/src/utils/env.ts

@@ -1,54 +1,53 @@
-/**
- * Environment detection utilities.
- * These avoid direct references to process.env which can cause TypeScript issues in browser environments.
- * Compatible with Node.js, Deno, and Vite environments.
- */
-
-// Type-safe access to import.meta.env (Vite) and Deno.env
-declare const Deno: { env?: { get(key: string): string | undefined } } | undefined;
-
-function getEnvVar(key: string): string | undefined {
-  // Check Vite's import.meta.env
-  if (typeof import.meta !== 'undefined' && (import.meta as any).env) {
-    return (import.meta as any).env[key];
-  }
-  // Check Deno
-  if (typeof Deno !== 'undefined' && Deno.env) {
-    return Deno.env.get(key);
-  }
-  // Check Node.js process.env via globalThis
-  if (typeof globalThis !== 'undefined' && (globalThis as any).process?.env) {
-    return (globalThis as any).process.env[key];
-  }
-  return undefined;
-}
-
-/**
- * Check if we're running in a test environment.
- */
-export function isTestEnv(): boolean {
-  return getEnvVar('NODE_ENV') === 'test';
-}
-
-/**
- * Check if we're running in a development environment (not production).
- */
-export function isDevEnv(): boolean {
-  // Check Vite's DEV flag
-  if (typeof import.meta !== 'undefined' && (import.meta as any).env?.DEV) {
-    return true;
-  }
-  const nodeEnv = getEnvVar('NODE_ENV');
-  return nodeEnv !== 'production';
-}
-
-/**
- * Check if we're running in production.
- */
-export function isProdEnv(): boolean {
-  // Check Vite's PROD flag
-  if (typeof import.meta !== 'undefined' && (import.meta as any).env?.PROD) {
-    return true;
-  }
-  return getEnvVar('NODE_ENV') === 'production';
-}
+/**
+ * Environment detection utilities.
+ * These avoid direct references to process.env which can cause TypeScript issues in browser environments.
+ * Compatible with Node.js and Vite environments.
+ */
+
+type ImportMetaWithEnv = ImportMeta & {
+  env?: Record<string, unknown> & { DEV?: boolean; PROD?: boolean };
+};
+type ProcessLike = { env?: Record<string, string | undefined> };
+
+function getEnvVar(key: string): string | undefined {
+  const importMetaEnv = (import.meta as ImportMetaWithEnv).env;
+  if (importMetaEnv && typeof importMetaEnv[key] === "string") {
+    return importMetaEnv[key] as string;
+  }
+
+  const processEnv = (globalThis as typeof globalThis & { process?: ProcessLike }).process?.env;
+  if (processEnv) {
+    return processEnv[key];
+  }
+  return undefined;
+}
+
+/**
+ * Check if we're running in a test environment.
+ */
+export function isTestEnv(): boolean {
+  return getEnvVar("NODE_ENV") === "test";
+}
+
+/**
+ * Check if we're running in a development environment (not production).
+ */
+export function isDevEnv(): boolean {
+  const importMetaEnv = (import.meta as ImportMetaWithEnv).env;
+  if (importMetaEnv?.DEV === true) {
+    return true;
+  }
+  const nodeEnv = getEnvVar("NODE_ENV");
+  return nodeEnv !== "production";
+}
+
+/**
+ * Check if we're running in production.
+ */
+export function isProdEnv(): boolean {
+  const importMetaEnv = (import.meta as ImportMetaWithEnv).env;
+  if (importMetaEnv?.PROD === true) {
+    return true;
+  }
+  return getEnvVar("NODE_ENV") === "production";
+}