@colixsystems/widget-sdk 0.245.0 → 0.246.0

package/dist/tooltip-view.js

@@ -0,0 +1,137 @@
+// The ONE implementation behind `<Tooltip>`: a short label for the control it
+// wraps, usually an icon-only button. On the web it shows on hover and on
+// keyboard focus; on a touch screen, which has no hover, a long press shows
+// it instead (a sheet on a device, as `<Menu>` is).
+
+import React from "react";
+import { useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { isText } from "./form-control-logic.js";
+import { POPOVER_DEFAULTS, resolvePopoverTokens } from "./popover-tokens.js";
+import { elementRef, mergeRefs } from "./popover-view.js";
+
+const h = React.createElement;
+
+/**
+ * Bind the shared tooltip to one platform's primitives and anchored surface.
+ *
+ * @param {{View: any, Text: any}} rn
+ * @param {any} AnchoredSurface — from `makePopover()` for the same host.
+ */
+export function makeTooltip(rn, AnchoredSurface) {
+  const { View, Text } = rn;
+
+  // "hover" (pointer or keyboard focus) or "press" (a long press), else null.
+  function useTooltipMode() {
+    const [mode, setMode] = React.useState(null);
+    const timer = React.useRef(null);
+    const cancel = () => clearTimeout(timer.current);
+    React.useEffect(() => cancel, []);
+    const after = (ms, next) => {
+      cancel();
+      timer.current = setTimeout(() => setMode(next), ms);
+    };
+    const ifHover = (next) => (own) => (own === "press" ? own : next);
+    return {
+      mode,
+      hoverIn: () => after(POPOVER_DEFAULTS.tooltipShowDelayMs, ifHover("hover")),
+      hoverOut: () => after(POPOVER_DEFAULTS.tooltipHideDelayMs, ifHover(null)),
+      stay: cancel,
+      focus: () => {
+        cancel();
+        setMode(ifHover("hover"));
+      },
+      blur: () => {
+        cancel();
+        setMode(ifHover(null));
+      },
+      press: () => {
+        cancel();
+        setMode("press");
+      },
+      close: () => {
+        cancel();
+        setMode(null);
+      },
+    };
+  }
+
+  /**
+   * A short label for the control it wraps. Wrap one pressable element (a
+   * `Pressable`, an icon button) that already carries its own
+   * `accessibilityLabel`: the tooltip shows that name to sighted users.
+   * A child with its own `onLongPress` keeps it, and gets no long-press
+   * tooltip.
+   *
+   * @param {object} props
+   * @param {string} props.label — one short phrase.
+   * @param {"top"|"bottom"} [props.placement] — default "top"; flips.
+   * @param {string} [props.testID] — on the label.
+   * @param {any} props.children — the one element it labels.
+   */
+  const Tooltip = React.forwardRef(function Tooltip(
+    { label, placement = "top", testID, children, ...passThrough },
+    forwardedRef,
+  ) {
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const anchorRef = React.useRef(null);
+    const labelId = React.useId();
+    const tip = useTooltipMode();
+    if (!React.isValidElement(children)) return children ?? null;
+    if (!isText(label) || label === "") return children;
+
+    const popover = resolvePopoverTokens(theme);
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const typography = theme.typography || DEFAULT_THEME_TOKENS.typography;
+    const ownLongPress = typeof children.props.onLongPress === "function";
+    const child = React.cloneElement(children, {
+      ...passThrough,
+      ref: mergeRefs(elementRef(children), anchorRef, forwardedRef),
+      ...(ownLongPress ? null : { onLongPress: tip.press }),
+      ...(tip.mode ? { "aria-describedby": labelId } : null),
+    });
+
+    return h(
+      View,
+      { onMouseEnter: tip.hoverIn, onMouseLeave: tip.hoverOut, onFocus: tip.focus, onBlur: tip.blur },
+      child,
+      h(
+        AnchoredSurface,
+        {
+          visible: tip.mode !== null,
+          onRequestClose: tip.close,
+          anchorRef,
+          placement,
+          passive: tip.mode === "hover",
+          maxWidth: POPOVER_DEFAULTS.tooltipMaxWidth,
+          accessibilityLabel: String(label),
+        },
+        h(
+          View,
+          {
+            nativeID: labelId,
+            role: "tooltip",
+            onMouseEnter: tip.stay,
+            onMouseLeave: tip.hoverOut,
+            testID,
+            style: { paddingHorizontal: spacing.sm, paddingVertical: spacing.xs },
+          },
+          h(
+            Text,
+            {
+              style: {
+                fontFamily: typography.fontFamily,
+                fontSize: typography.sizes.sm,
+                color: popover.textColor,
+              },
+            },
+            String(label),
+          ),
+        ),
+      ),
+    );
+  });
+
+  Tooltip.displayName = "Tooltip";
+  return Tooltip;
+}

package/dist/web-modal.js

@@ -7,8 +7,8 @@
 // re-render rebuilt it, and its Escape and focus handling never re-armed.
 //
 // Implements only the `Modal` props `<Overlay>` passes: `visible`,
-// `onRequestClose`, the dialog's role and name, `initialFocusRef` and
-// `children`; it is never animated.
+// `onRequestClose`, the dialog's role and name, `initialFocusRef`, `passive`,
+// `closesOnOutsideScroll` and `children`; it is never animated.
 
 import React from "react";
 import { createPortal } from "react-dom";
@@ -28,30 +28,111 @@ const layerStyle = {
   outline: "none",
 };
 
-// Open layers, innermost last: only the top one handles Escape and Tab.
+// Open layers, innermost last. The top one handles Escape; the top modal
+// one traps Tab and focus, as a tooltip above it takes neither.
 const openLayers = [];
 
+function openLayer(passive) {
+  const layer = { passive };
+  openLayers.push(layer);
+  return {
+    isTop: () => openLayers[openLayers.length - 1] === layer,
+    isTopModal: () => openLayers.filter((open) => !open.passive).pop() === layer,
+    close: () => {
+      const index = openLayers.indexOf(layer);
+      if (index !== -1) openLayers.splice(index, 1);
+    },
+  };
+}
+
+// An anchored panel would drift from its trigger, so a scroll beneath closes it.
+function useCloseOnOutsideScroll(container, enabled, onCloseRef) {
+  React.useEffect(() => {
+    if (!container || !enabled) return undefined;
+    const onScroll = (event) => {
+      const target = event.target;
+      if (target instanceof Node && container.contains(target)) return;
+      if (typeof onCloseRef.current === "function") onCloseRef.current();
+    };
+    document.addEventListener("scroll", onScroll, { capture: true, passive: true });
+    return () => document.removeEventListener("scroll", onScroll, { capture: true });
+  }, [container, enabled, onCloseRef]);
+}
+
 function tabStops(dialog) {
   return Array.from(dialog.querySelectorAll(FOCUSABLE)).filter(
     (node) => node.getAttribute("aria-hidden") !== "true",
   );
 }
 
+const passiveLayerStyle = { ...layerStyle, pointerEvents: "none" };
+
+// Owns a body-level container while mounted, as the modal layer does.
+function useBodyContainer(visible) {
+  const [container, setContainer] = React.useState(null);
+  React.useLayoutEffect(() => {
+    if (!visible) return undefined;
+    const node = document.createElement("div");
+    document.body.appendChild(node);
+    setContainer(node);
+    return () => {
+      node.remove();
+      setContainer(null);
+    };
+  }, [visible]);
+  return container;
+}
+
+// A tooltip's layer: no focus trap, no modal semantics, the pointer passes
+// through. Escape dismisses it while it is the top layer, ahead of any
+// dialog beneath; a dialog opened above it takes Escape first.
+function PassiveLayer({ visible = true, onRequestClose, closesOnOutsideScroll, children }) {
+  const container = useBodyContainer(visible);
+  const onCloseRef = React.useRef(onRequestClose);
+  onCloseRef.current = onRequestClose;
+  useCloseOnOutsideScroll(container, closesOnOutsideScroll, onCloseRef);
+
+  React.useEffect(() => {
+    if (!container) return undefined;
+    const layer = openLayer(true);
+    const onKeyUp = (event) => {
+      if (event.key !== "Escape" || !layer.isTop()) return;
+      event.stopPropagation();
+      if (typeof onCloseRef.current === "function") onCloseRef.current();
+    };
+    document.addEventListener("keyup", onKeyUp);
+    return () => {
+      document.removeEventListener("keyup", onKeyUp);
+      layer.close();
+    };
+  }, [container]);
+
+  if (!visible || !container) return null;
+  return createPortal(
+    React.createElement("div", { style: passiveLayerStyle }, children),
+    container,
+  );
+}
+
 /**
  * @param {{visible?: boolean, onRequestClose?: () => void, role?: string,
  *   "aria-label"?: string, "aria-labelledby"?: string,
- *   initialFocusRef?: {current: any}, children?: any}} props
+ *   initialFocusRef?: {current: any}, passive?: boolean, children?: any}} props
  */
-export function WebModal({
+export function WebModal(props) {
+  return React.createElement(props.passive ? PassiveLayer : ModalLayer, props);
+}
+
+function ModalLayer({
   visible = true,
   onRequestClose,
   role = "dialog",
   "aria-label": ariaLabel,
   "aria-labelledby": ariaLabelledBy,
   initialFocusRef,
+  closesOnOutsideScroll,
   children,
 }) {
-  const [container, setContainer] = React.useState(null);
   const dialogRef = React.useRef(null);
   const onCloseRef = React.useRef(onRequestClose);
   onCloseRef.current = onRequestClose;
@@ -62,23 +143,15 @@ export function WebModal({
   const returnFocusRef = React.useRef(null);
 
   React.useLayoutEffect(() => {
-    if (!visible) return undefined;
-    returnFocusRef.current = document.activeElement;
-    const node = document.createElement("div");
-    document.body.appendChild(node);
-    setContainer(node);
-    return () => {
-      node.remove();
-      setContainer(null);
-    };
+    if (visible) returnFocusRef.current = document.activeElement;
   }, [visible]);
+  const container = useBodyContainer(visible);
+  useCloseOnOutsideScroll(container, closesOnOutsideScroll, onCloseRef);
 
   React.useEffect(() => {
     const dialog = dialogRef.current;
     if (!container || !dialog) return undefined;
-    const layer = {};
-    openLayers.push(layer);
-    const isTop = () => openLayers[openLayers.length - 1] === layer;
+    const layer = openLayer(false);
     const returnFocusTo = returnFocusRef.current;
     const wanted = initialFocusRefRef.current;
     const first = wanted && wanted.current;
@@ -91,12 +164,12 @@ export function WebModal({
     // keyup, as react-native-web's Modal did, so the keydown that opened a
     // nested overlay cannot also close it.
     const onKeyUp = (event) => {
-      if (event.key !== "Escape" || !isTop()) return;
+      if (event.key !== "Escape" || !layer.isTop()) return;
       event.stopPropagation();
       if (typeof onCloseRef.current === "function") onCloseRef.current();
     };
     const onKeyDown = (event) => {
-      if (event.key !== "Tab" || !isTop()) return;
+      if (event.key !== "Tab" || !layer.isTopModal()) return;
       const stops = tabStops(dialog);
       if (!stops.length) {
         event.preventDefault();
@@ -115,7 +188,7 @@ export function WebModal({
       }
     };
     const onFocusIn = (event) => {
-      if (isTop() && !dialog.contains(event.target)) {
+      if (layer.isTopModal() && !dialog.contains(event.target)) {
         dialog.focus({ preventScroll: true });
       }
     };
@@ -126,8 +199,7 @@ export function WebModal({
       document.removeEventListener("keyup", onKeyUp);
       document.removeEventListener("keydown", onKeyDown);
       document.removeEventListener("focusin", onFocusIn);
-      const index = openLayers.indexOf(layer);
-      if (index !== -1) openLayers.splice(index, 1);
+      layer.close();
       if (
         returnFocusTo &&
         typeof returnFocusTo.focus === "function" &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.245.0",
+  "version": "0.246.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",