@scalewing/react 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalewing/react
 
+## 1.19.0
+
+### Minor Changes
+
+- 596b74b: `Tooltip` `disabled` (`docs/requests/teisoro-tooltip-disabled.md`, Teisoro's workspace navigation). `disabled?: boolean` turns the tooltip off, not its trigger, which stays mounted, enabled and focusable: the tooltip element is not rendered, the trigger keeps only its own `aria-describedby`, and Escape reaches the page. Focus, hover and touch are still followed, so a trigger that still has focus, the pointer or an open touch toggle shows the tooltip as soon as it is enabled again. `disabled` must match between the server render and the first client render. A product toggles it at a breakpoint instead of rendering the trigger with and without a `Tooltip`, which mounted a new trigger and lost its focus. Without `disabled` the markup and behavior are unchanged. No new classes, tokens or dependencies.
+
 ## 1.18.0
 
 ### Minor Changes

package/README.md

@@ -247,7 +247,7 @@ An option's optional `description` (a `ReactNode`) is secondary text for that op
 
 `Progress` shows a known value between zero and a positive maximum. It uses native progressbar semantics and displays the value and maximum beside the localized label. Invalid bounds throw instead of silently clamping. Optional `tone` is `accent`, `success`, or `danger`. `showCount={false}` hides the visible `value / max` count when the page shows its own count caption, so the count appears once; the progress bar still exposes its value and maximum.
 
-`Tooltip` adds supplementary plain-text help to one labelled, focusable trigger. Supply localized `content` and an existing trigger element with its own accessible name. It opens on hover or focus, closes on pointer leave, blur, Escape, or outside touch, and toggles on touch. Keep required instructions visible outside the tooltip.
+`Tooltip` adds supplementary plain-text help to one labelled, focusable trigger. Supply localized `content` and an existing trigger element with its own accessible name. It opens on hover or focus, closes on pointer leave, blur, Escape, or outside touch, and toggles on touch. Keep required instructions visible outside the tooltip. `disabled` turns the tooltip off, not its trigger: the trigger stays mounted, enabled and focusable, and there is no tooltip, no `aria-describedby` from it, and Escape is left to the page. Use it when what the tooltip says is visible at some widths, such as text shown only from `md` up, instead of rendering the trigger with and without a `Tooltip`, which mounts a new trigger and drops its focus. Focus, hover and touch are still followed, so a trigger that still has focus, the pointer or an open touch toggle shows the tooltip as soon as it is enabled again (Escape pressed while disabled reaches the page and does not stop that). `disabled` must be the same in the server render and the first client render, or hydration mismatches; read a breakpoint through a hydration-safe store, such as `useSyncExternalStore` with a server snapshot.
 
 `Separator` divides sections with a token-colored line. It is horizontal by default; use `orientation="vertical"` in a flex row. Set `decorative` when the line only supports layout so assistive technology ignores it.
 

package/dist/components/Tooltip.d.ts

@@ -1,8 +1,18 @@
 import { type ReactElement } from 'react';
 export type TooltipProps = {
     content: string;
+    /**
+     * Turns the tooltip off, not its trigger: no tooltip, no description and no
+     * Escape handling, while the trigger stays mounted, enabled and focusable
+     * (and keeps its focus). Focus, hover and touch are still followed, so the
+     * tooltip shows as soon as it is enabled again on a trigger that still has
+     * focus, the pointer or an open touch toggle; Escape pressed while disabled
+     * reaches the page and does not stop that. It must match between the server
+     * render and the first client render.
+     */
+    disabled?: boolean;
     trigger: ReactElement<{
         'aria-describedby'?: string;
     }>;
 };
-export declare function Tooltip({ content, trigger }: TooltipProps): import("react").JSX.Element;
+export declare function Tooltip({ content, disabled, trigger }: TooltipProps): import("react").JSX.Element;

package/dist/components/Tooltip.js

@@ -1,15 +1,18 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cloneElement, useEffect, useId, useRef, useState, } from 'react';
-export function Tooltip({ content, trigger }) {
+export function Tooltip({ content, disabled = false, trigger }) {
     if (!content.trim())
         throw new RangeError('content must not be empty');
+    // `open` follows focus, hover and touch even while disabled; `shown` is
+    // what the page gets.
     const [open, setOpen] = useState(false);
+    const shown = open && !disabled;
     const id = useId();
     const wrapperRef = useRef(null);
-    const describedBy = [trigger.props['aria-describedby'], id]
+    const describedBy = [trigger.props['aria-describedby'], disabled ? undefined : id]
         .filter(Boolean)
-        .join(' ');
+        .join(' ') || undefined;
     useEffect(() => {
         if (!open)
             return;
@@ -27,7 +30,7 @@ export function Tooltip({ content, trigger }) {
         }, onFocusCapture: () => setOpen(true), onKeyDownCapture: (event) => {
             // Escape hides a visible tooltip and nothing else, so a surrounding
             // Dialog does not also close. A hidden tooltip leaves Escape alone.
-            if (event.key !== 'Escape' || !open)
+            if (event.key !== 'Escape' || !shown)
                 return;
             event.preventDefault();
             setOpen(false);
@@ -40,5 +43,5 @@ export function Tooltip({ content, trigger }) {
         }, onPointerDownCapture: (event) => {
             if (event.pointerType === 'touch')
                 setOpen((current) => !current);
-        }, ref: wrapperRef, children: [cloneElement(trigger, { 'aria-describedby': describedBy }), _jsx("span", { className: "sw-tooltip", hidden: !open, id: id, role: "tooltip", children: content })] }));
+        }, ref: wrapperRef, children: [cloneElement(trigger, { 'aria-describedby': describedBy }), disabled ? null : (_jsx("span", { className: "sw-tooltip", hidden: !shown, id: id, role: "tooltip", children: content }))] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalewing/react",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Scalewing DOM components and package-owned CSS utilities.",
   "type": "module",
   "license": "MIT",