@proyecto-viviana/solidaria 0.4.3 → 0.6.0-rc.1

package/src/interactions/createInteractionModality.ts

@@ -1,3 +1,17 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// Ported to SolidJS for Proyecto Viviana; based on packages/react-aria/src/interactions/useFocusVisible.ts
+
 /**
  * createInteractionModality + focus-visible tracking for solidaria
  *
@@ -6,9 +20,12 @@
  * provides focus-visible state and listeners.
  */
 
-import { type Accessor, createSignal, createEffect, onCleanup } from "solid-js";
-import { isServer } from "solid-js/web";
-import { getOwnerDocument, getOwnerWindow, isMac, isVirtualClick, openLink } from "../utils";
+import { createSignal, createTrackedEffect } from "solid-js";
+import type { Accessor } from "solid-js";
+import { isServer } from "@solidjs/web";
+import { getEventTarget, getOwnerDocument, getOwnerWindow, openLink } from "../utils/dom";
+import { isVirtualClick } from "../utils/events";
+import { isMac } from "../utils/platform";
 
 export type Modality = "keyboard" | "pointer" | "virtual";
 export type PointerType = "mouse" | "pen" | "touch" | "keyboard" | "virtual";
@@ -34,8 +51,34 @@ export interface InteractionModalityResult {
   modality: Accessor<Modality | null>;
 }
 
-let currentModality: Modality | null = null;
+// react-aria keeps `currentModality` in a module `let` that the same turn can
+// read (useFocusVisible.ts). `currentModalityValue` is that let: every read
+// returns it. The signal is a notification counter, not a copy of the word.
+// `writeModality` updates the let. `publishModality` updates the let and bumps
+// the counter. Bump where upstream calls `triggerChangeHandlers`
+// (keyboard, pointerdown/mousedown, virtual focus, setInteractionModality)
+// and on handleClickEvent's virtual write. That click handler
+// (useFocusVisible.ts:105-111) stays silent because React re-renders after
+// the click; #612 exists because Solid must notify instead. pointermove and
+// pointerup write the let only. Listener notification stays on
+// `triggerChangeHandlers`. `ownedWrite`: a module DOM listener and
+// `setInteractionModality` can write re-entrantly from an owned scope.
+// `untrack` stops tracking; it does not exempt the write.
+let currentModalityValue: Modality | null = null;
+const [modalityEpoch, bumpModalityEpoch] = createSignal(0, {
+  ownedWrite: true,
+});
 let currentPointerType: PointerType = "keyboard";
+
+function writeModality(next: Modality): void {
+  currentModalityValue = next;
+}
+
+function publishModality(next: Modality): void {
+  currentModalityValue = next;
+  bumpModalityEpoch((n) => n + 1);
+}
+
 const changeHandlers = new Set<Handler>();
 
 export let hasSetupGlobalListeners: Map<
@@ -44,7 +87,13 @@ export let hasSetupGlobalListeners: Map<
 > = new Map();
 let hasEventBeforeFocus = false;
 let hasBlurredWindowRecently = false;
-let ignoreFocusEvent = false;
+/** @private Set by `preventFocus` so programmatic refocus is not treated as a modality change. */
+export let ignoreFocusEvent = false;
+
+/** @private */
+export function setIgnoreFocusEvent(value: boolean): void {
+  ignoreFocusEvent = value;
+}
 
 const FOCUS_VISIBLE_INPUT_KEYS: Record<string, boolean> = {
   Tab: true,
@@ -72,50 +121,68 @@ function handleKeyboardEvent(e: KeyboardEvent) {
   hasEventBeforeFocus = true;
   const isOpening = (openLink as { isOpening?: boolean }).isOpening;
   if (!isOpening && isValidKey(e)) {
-    currentModality = "keyboard";
+    publishModality("keyboard");
     currentPointerType = "keyboard";
     triggerChangeHandlers("keyboard", e);
   }
 }
 
 function handlePointerEvent(e: PointerEvent | MouseEvent) {
-  currentModality = "pointer";
   currentPointerType = "pointerType" in e ? (e.pointerType as PointerType) : "mouse";
+  // useFocusVisible.ts:94-101. Move and up write the let. Down is the notify.
   if (e.type === "mousedown" || e.type === "pointerdown") {
+    publishModality("pointer");
     hasEventBeforeFocus = true;
     triggerChangeHandlers("pointer", e);
+  } else {
+    writeModality("pointer");
   }
 }
 
 function handleClickEvent(e: MouseEvent) {
-  if (!e.isTrusted) {
-    return;
-  }
-
+  // react-aria 3.52.0 useFocusVisible.ts:105-111. No isTrusted guard and no
+  // listener notification: keyboards, AT, and element.click() are virtual
+  // clicks (detail === 0). React re-renders after the click, so that silent
+  // write is enough there. Solid must notify tracked readers instead (#612).
   const isOpening = (openLink as { isOpening?: boolean }).isOpening;
   if (!isOpening && isVirtualClick(e)) {
     hasEventBeforeFocus = true;
-    currentModality = "virtual";
+    publishModality("virtual");
     currentPointerType = "virtual";
   }
 }
 
 function handleFocusEvent(e: FocusEvent) {
-  if (!e.isTrusted || ignoreFocusEvent) {
+  if (ignoreFocusEvent) {
     return;
   }
 
-  const target = e.target as EventTarget | null;
-  const targetElement = target && (target as Element).nodeType ? (target as Element) : null;
-  const ownerWindow = targetElement ? getOwnerWindow(targetElement) : window;
-  const ownerDocument = targetElement ? getOwnerDocument(targetElement) : document;
+  const target = getEventTarget(e);
+  const ownerWindow = getOwnerWindow(target);
+  const ownerDocument = getOwnerDocument(target);
+
+  // When the window regains focus, the browser restores focus to the element that was focused
+  // before, firing a focus event the user did not initiate. handleWindowBlur sets
+  // hasBlurredWindowRecently so restored focus doesn't switch to virtual modality below, but
+  // Safari fires the window/element focus pair twice when returning to a tab or app and the first
+  // element focus event clears the flag, so re-arm it whenever the window itself is focused.
+  // Like handleWindowBlur, this intentionally doesn't check isTrusted.
+  if (target === ownerWindow) {
+    hasBlurredWindowRecently = true;
+    return;
+  }
 
-  if (target === ownerWindow || target === ownerDocument) {
+  // Firefox fires two extra focus events when the user first clicks into an iframe:
+  // first on the window, then on the document. We ignore these events so they don't
+  // cause keyboard focus rings to appear.
+  if (target === ownerDocument || !e.isTrusted) {
     return;
   }
 
+  // If a focus event occurs without a preceding keyboard or pointer event, switch to virtual modality.
+  // This occurs, for example, when navigating a form with the next/previous buttons on iOS.
   if (!hasEventBeforeFocus && !hasBlurredWindowRecently) {
-    currentModality = "virtual";
+    publishModality("virtual");
     currentPointerType = "virtual";
     triggerChangeHandlers("virtual", e);
   }
@@ -261,31 +328,40 @@ if (typeof document !== "undefined") {
   addWindowFocusTracking();
 }
 
+function focusVisibleSnapshot(): boolean {
+  return currentModalityValue !== "pointer";
+}
+
 /**
- * If true, keyboard focus is visible.
+ * If true, keyboard focus is visible. The only tracked read of modality:
+ * useOption's render predicate re-reads this on every render.
  */
 export function isFocusVisible(): boolean {
-  return currentModality !== "pointer";
+  modalityEpoch();
+  return focusVisibleSnapshot();
 }
 
 /**
  * Gets the current interaction modality.
+ * The module let, not the signal. An effect that calls this does not re-run
+ * when modality changes; upstream's query is a plain variable.
  */
 export function getInteractionModality(): Modality | null {
-  return currentModality;
+  return currentModalityValue;
 }
 
 /**
  * Sets the current interaction modality.
  */
 export function setInteractionModality(modality: Modality): void {
-  currentModality = modality;
+  publishModality(modality);
   currentPointerType = modality === "pointer" ? "mouse" : modality;
   triggerChangeHandlers(modality, null);
 }
 
 /**
- * Gets the current pointer type.
+ * Gets the current pointer type. Separate from modality; this let is never
+ * the modality signal.
  */
 export function getPointerType(): PointerType {
   return currentPointerType;
@@ -338,14 +414,18 @@ function isKeyboardFocusEvent(isTextInput: boolean, modality: Modality, e: Handl
  */
 export function createFocusVisibleListener(
   handler: FocusVisibleHandler,
-  opts?: { isTextInput?: boolean },
+  opts?: { isTextInput?: boolean; enabled?: boolean },
 ): () => void {
   setupGlobalFocusEvents();
+  if (opts?.enabled === false) {
+    return () => {};
+  }
   const listener: Handler = (modality: Modality, e: HandlerEvent) => {
     if (!isKeyboardFocusEvent(!!opts?.isTextInput, modality, e)) {
       return;
     }
-    handler(isFocusVisible());
+    // Upstream's listener read is a plain variable (useFocusVisible.ts:424); the listener runs synchronously inside setInteractionModality, which an effect may call.
+    handler(focusVisibleSnapshot());
   };
   changeHandlers.add(listener);
   return () => {
@@ -357,18 +437,28 @@ export function createFocusVisibleListener(
  * Manages focus visible state for the page.
  */
 export function createFocusVisible(props: FocusVisibleProps = {}): FocusVisibleResult {
-  if (isServer) {
-    return { isFocusVisible: () => false };
-  }
-
   // autoFocus seeds the initial value once; isTextInput is read inside the effect
   // so it re-subscribes reactively (a top-level destructure would freeze it — the
   // body runs once). Mirrors upstream useFocusVisible's [isTextInput] dep.
-  const [isVisible, setIsVisible] = createSignal<boolean>(props.autoFocus || isFocusVisible());
+  // The let, not isFocusVisible(). During hydration that signal can still hold
+  // an unflushed write; reading it markLateLinker's the computing owner
+  // (REACTIVE_MISSED_WAKE) and the surrounding memo re-runs, so the second
+  // span misses its hydration key. The let is the same answer, written
+  // synchronously.
+  const [isVisible, setIsVisible] = createSignal<boolean>(
+    isServer ? false : props.autoFocus || focusVisibleSnapshot(),
+  );
+
+  // Reserve the effect owner during SSR too; its callback runs only on client.
+  createTrackedEffect(() => {
+    const _s2Cleanups: Array<() => void> = [];
 
-  createEffect(() => {
     const cleanup = createFocusVisibleListener(setIsVisible, { isTextInput: props.isTextInput });
-    onCleanup(cleanup);
+    _s2Cleanups.push(cleanup);
+
+    return () => {
+      for (const c of _s2Cleanups) c();
+    };
   });
 
   return { isFocusVisible: isVisible };
@@ -378,23 +468,27 @@ export function createFocusVisible(props: FocusVisibleProps = {}): FocusVisibleR
  * Tracks the current interaction modality.
  */
 export function createInteractionModality(): InteractionModalityResult {
-  if (isServer) {
-    return {
-      modality: () => null,
-    };
-  }
+  const [modality, setModality] = createSignal<Modality | null>(
+    isServer ? null : currentModalityValue,
+  );
 
-  const [modality, setModality] = createSignal<Modality | null>(currentModality);
+  // Register the owner on both sides; only the browser subscribes to events.
+  createTrackedEffect(() => {
+    if (isServer) return;
+    const _s2Cleanups: Array<() => void> = [];
 
-  createEffect(() => {
     setupGlobalFocusEvents();
     const handler: Handler = (newModality: Modality) => {
       setModality(newModality);
     };
     changeHandlers.add(handler);
-    onCleanup(() => {
+    _s2Cleanups.push(() => {
       changeHandlers.delete(handler);
     });
+
+    return () => {
+      for (const c of _s2Cleanups) c();
+    };
   });
 
   return {
@@ -419,10 +513,6 @@ export function addModalityListener(handler: (modality: Modality) => void): () =
  * Hook to track whether the user is currently interacting with the keyboard.
  */
 export function useIsKeyboardFocused(): Accessor<boolean> {
-  if (isServer) {
-    return () => false;
-  }
-
   const { modality } = createInteractionModality();
   return () => modality() === "keyboard";
 }

package/src/interactions/createKeyboard.ts

@@ -1,10 +1,31 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// Ported to SolidJS for Proyecto Viviana; based on packages/react-aria/src/interactions/useKeyboard.ts
+
 /**
  * createKeyboard - Handles keyboard interactions for a focusable element.
  *
  * This is a 1-1 port of React-Aria's useKeyboard hook adapted for SolidJS.
  */
 
-import { JSX } from "solid-js";
+import type { JSX } from "@solidjs/web";
+import { chain } from "../utils/events";
+import { getEventTarget, nodeContains, eventPathContains } from "../utils/dom";
+import { access, type MaybeAccessor } from "../utils";
+import {
+  createKeyboardShortcutHandler,
+  type KeyboardShortcutBindings,
+} from "./createKeyboardShortcutHandler";
 
 /**
  * Keyboard event with continuePropagation support.
@@ -24,12 +45,18 @@ export interface KeyboardEvents {
 
 export interface CreateKeyboardProps extends KeyboardEvents {
   /** Whether the keyboard events should be disabled. */
-  isDisabled?: boolean;
+  isDisabled?: MaybeAccessor<boolean>;
+  /** Keyboard shortcuts to handle. */
+  shortcuts?: KeyboardShortcutBindings;
+  /** Whether shortcut handlers receive repeated keydown events. @default false */
+  allowRepeats?: boolean;
+  /** Whether shortcut handlers receive composing keydown events. @default false */
+  allowComposing?: boolean;
 }
 
 export interface KeyboardResult {
   /** Props to spread onto the target element. */
-  keyboardProps: JSX.HTMLAttributes<HTMLElement>;
+  keyboardProps: Pick<JSX.HTMLAttributes<HTMLElement>, "onKeyDown" | "onKeyUp">;
 }
 
 /**
@@ -77,16 +104,65 @@ function createEventHandler<T extends globalThis.KeyboardEvent>(
  * Based on react-aria's useKeyboard but adapted for SolidJS.
  */
 export function createKeyboard(props: CreateKeyboardProps = {}): KeyboardResult {
-  if (props.isDisabled) {
-    return {
-      keyboardProps: {},
-    };
+  let onKeyDown: ((event: globalThis.KeyboardEvent) => void) | undefined;
+  let onKeyUp: ((event: globalThis.KeyboardEvent) => void) | undefined;
+
+  if (props.shortcuts) {
+    const shortcutHandler = createKeyboardShortcutHandler(props.shortcuts);
+    const shortcutOnKeyDown = createEventHandler((event) => {
+      if (!eventPathContains(event.currentTarget as Node | null, event)) {
+        event.continuePropagation();
+        return;
+      }
+
+      if (
+        (event.repeat && !(props.allowRepeats ?? false)) ||
+        (event.isComposing && !(props.allowComposing ?? false))
+      ) {
+        event.continuePropagation();
+        return;
+      }
+
+      shortcutHandler(event);
+    });
+    const shortcutOnKeyUp = createEventHandler((event) => {
+      if (!eventPathContains(event.currentTarget as Node | null, event)) {
+        event.continuePropagation();
+        return;
+      }
+
+      if (
+        (event.repeat && !(props.allowRepeats ?? false)) ||
+        (event.isComposing && !(props.allowComposing ?? false))
+      ) {
+        event.continuePropagation();
+        return;
+      }
+
+      event.continuePropagation();
+    });
+
+    onKeyDown = props.onKeyDown
+      ? chain(props.onKeyDown as (event: globalThis.KeyboardEvent) => void, shortcutOnKeyDown)
+      : shortcutOnKeyDown;
+    onKeyUp = props.onKeyUp
+      ? chain(props.onKeyUp as (event: globalThis.KeyboardEvent) => void, shortcutOnKeyUp)
+      : shortcutOnKeyUp;
+  } else {
+    onKeyDown = createEventHandler(props.onKeyDown);
+    onKeyUp = createEventHandler(props.onKeyUp);
   }
 
   return {
     keyboardProps: {
-      onKeyDown: createEventHandler(props.onKeyDown),
-      onKeyUp: createEventHandler(props.onKeyUp),
+      get onKeyDown() {
+        return access(props.isDisabled) ? undefined : onKeyDown;
+      },
+      get onKeyUp() {
+        return access(props.isDisabled) ? undefined : onKeyUp;
+      },
     },
   };
 }
+
+export type { KeyboardShortcutBindings } from "./createKeyboardShortcutHandler";

package/src/interactions/createKeyboardShortcutHandler.ts

@@ -0,0 +1,157 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// Ported to SolidJS for Proyecto Viviana; based on packages/react-aria/src/interactions/createKeyboardShortcutHandler.ts
+
+/**
+ * Keyboard shortcut parsing and exact-match dispatch.
+ *
+ * Port of React Aria's createKeyboardShortcutHandler.
+ */
+
+import { isMac } from "../utils/platform";
+import type { KeyboardEvent } from "./createKeyboard";
+
+export type KeyboardShortcutAction = (
+  event: KeyboardEvent,
+) =>
+  | void
+  | boolean
+  | Partial<{ shouldContinuePropagation?: boolean; shouldPreventDefault?: boolean }>;
+
+/** Maps shortcut strings such as `Mod+s` to handlers. */
+export type KeyboardShortcutBindings = Record<string, KeyboardShortcutAction>;
+
+const modifierNames = new Set(["shift", "alt", "control", "meta", "mod"]);
+const canonicalModifierOrder = ["Alt", "Control", "Meta", "Shift"] as const;
+
+export interface ParsedKeyboardShortcut {
+  shift: boolean;
+  alt: boolean;
+  ctrl: boolean;
+  meta: boolean;
+  mod: boolean;
+  key: string;
+}
+
+export function modifierSetFromParsed(parsed: ParsedKeyboardShortcut): Set<string> {
+  const modifiers = new Set<string>();
+  if (parsed.alt) modifiers.add("Alt");
+  if (parsed.shift) modifiers.add("Shift");
+  if (parsed.ctrl) modifiers.add("Control");
+  if (parsed.meta) modifiers.add("Meta");
+  if (parsed.mod) modifiers.add(isMac() ? "Meta" : "Control");
+  return modifiers;
+}
+
+export function modifierSetFromEvent(event: KeyboardEvent): Set<string> {
+  const modifiers = new Set<string>();
+  if (event.altKey) modifiers.add("Alt");
+  if (event.ctrlKey) modifiers.add("Control");
+  if (event.metaKey) modifiers.add("Meta");
+  if (event.shiftKey) modifiers.add("Shift");
+  return modifiers;
+}
+
+function sortedModifierTokens(modifiers: Set<string>): string[] {
+  return canonicalModifierOrder.filter((name) => modifiers.has(name));
+}
+
+/** Parses a shortcut. Modifier names are case-insensitive and order-independent. */
+export function parseKeyboardShortcut(specification: string): ParsedKeyboardShortcut {
+  const parsed = specification.split("+").reduce<ParsedKeyboardShortcut>(
+    (result, part) => {
+      const lowerPart = part.toLowerCase();
+      if (modifierNames.has(lowerPart)) {
+        if (lowerPart === "shift") result.shift = true;
+        else if (lowerPart === "alt") result.alt = true;
+        else if (lowerPart === "control") result.ctrl = true;
+        else if (lowerPart === "meta") result.meta = true;
+        else if (lowerPart === "mod") result.mod = true;
+      } else {
+        result.key = part;
+      }
+      return result;
+    },
+    { shift: false, alt: false, ctrl: false, meta: false, mod: false, key: "" },
+  );
+
+  if (parsed.key === "") {
+    throw new Error(
+      `Invalid keyboard shortcut: "${specification}". Must include exactly one non-modifier key (e.g. "a", "Enter", "ArrowDown"). Combine any of Shift, Alt, Ctrl, Meta, and Mod.`,
+    );
+  }
+
+  return parsed;
+}
+
+function normalizeEventKey(key: string): string {
+  return key.toLowerCase();
+}
+
+const keyAliases: Record<string, string> = {
+  space: " ",
+  esc: "escape",
+  del: "delete",
+  ins: "insert",
+  left: "arrowleft",
+  right: "arrowright",
+  up: "arrowup",
+  down: "arrowdown",
+  pageup: "pageup",
+  pagedown: "pagedown",
+};
+
+function canonicalKeyFromSpecification(key: string): string {
+  const normalizedKey = normalizeEventKey(key);
+  return keyAliases[normalizedKey] ?? normalizedKey;
+}
+
+export function canonicalKeyboardShortcut(parsed: ParsedKeyboardShortcut): string {
+  const modifiers = sortedModifierTokens(modifierSetFromParsed(parsed));
+  const key = canonicalKeyFromSpecification(parsed.key);
+  return modifiers.length > 0 ? `${modifiers.join("+")}+${key}` : key;
+}
+
+export function keyboardEventToCanonicalShortcut(event: KeyboardEvent): string {
+  const modifiers = sortedModifierTokens(modifierSetFromEvent(event));
+  const key = normalizeEventKey(event.key);
+  return modifiers.length > 0 ? `${modifiers.join("+")}+${key}` : key;
+}
+
+/** Returns a keydown handler that runs an action for an exact shortcut match. */
+export function createKeyboardShortcutHandler(
+  bindings: KeyboardShortcutBindings,
+): (event: KeyboardEvent) => void {
+  const actions = new Map<string, KeyboardShortcutAction>();
+  for (const [specification, action] of Object.entries(bindings)) {
+    actions.set(canonicalKeyboardShortcut(parseKeyboardShortcut(specification)), action);
+  }
+
+  return (event: KeyboardEvent) => {
+    const action = actions.get(keyboardEventToCanonicalShortcut(event));
+    let result = action?.(event);
+
+    if (result === undefined && action !== undefined) {
+      result = { shouldContinuePropagation: false, shouldPreventDefault: true };
+    } else if (typeof result === "boolean") {
+      result = { shouldContinuePropagation: !result, shouldPreventDefault: result };
+    }
+
+    if (result?.shouldPreventDefault) {
+      event.preventDefault();
+    }
+    if (!action || result?.shouldContinuePropagation) {
+      event.continuePropagation();
+    }
+  };
+}