@scalewing/react 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalewing/react
 
+## 1.20.0
+
+### Minor Changes
+
+- cfcac1a: `Tooltip` `relationship` (`docs/requests/teisoro-tooltip-labels.md`, Teisoro's workspace navigation). `relationship?: 'description' | 'label'`, default `'description'`, and the exported type `TooltipRelationship`. `'label'` makes the tooltip its trigger's accessible name: the trigger gets `aria-labelledby` with the tooltip's id (after its own, if any) instead of `aria-describedby`, so an icon-only control's name is read once rather than as both name and description. The tooltip stays in the page, hidden, so it names the trigger while not shown. With `disabled` there is no tooltip and no reference to it; the trigger then needs its own name (visible text or `aria-label`). Without `relationship` the markup and behavior are unchanged. No new classes, tokens or dependencies.
+
 ## 1.19.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. `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.
+`Tooltip` adds supplementary plain-text help to one labelled, focusable trigger, or names an icon-only one (`relationship="label"`, below). Supply localized `content` and an existing trigger element; by default it has 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. `relationship="label"` makes the tooltip its trigger's name instead of its description, for an icon-only control whose tooltip says what it is: the trigger gets `aria-labelledby` (after its own, if any) and no `aria-describedby` from the tooltip, so the text is read once. The tooltip stays in the page, hidden, so it names the trigger while it is not shown, and it wins over an `aria-label`. While `disabled` there is no tooltip to name the trigger, so give the trigger its own name for that state: visible text, such as a label shown only from `md` up, or an `aria-label`. Do not use `relationship="label"` while the trigger shows visible text that differs from `content`: the tooltip would replace that visible label as the name (WCAG 2.5.3, label in name). The default, `relationship="description"`, is the supplementary help above. `relationship` must also be the same in the server render and the first client render.
 
 `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,4 +1,6 @@
 import { type ReactElement } from 'react';
+import { type TooltipRelationship, type TooltipTriggerAria } from './tooltip-trigger-aria.js';
+export type { TooltipRelationship };
 export type TooltipProps = {
     content: string;
     /**
@@ -11,8 +13,19 @@ export type TooltipProps = {
      * render and the first client render.
      */
     disabled?: boolean;
-    trigger: ReactElement<{
-        'aria-describedby'?: string;
-    }>;
+    /**
+     * `'description'` (default) adds supplementary help to a trigger that has
+     * its own name, through `aria-describedby`. `'label'` makes `content` the
+     * trigger's accessible name, through `aria-labelledby`, for an icon-only
+     * control: the text is read once, as its name. The tooltip stays in the
+     * DOM, hidden, so it names the trigger while it is not shown. While
+     * `disabled` there is no tooltip to name it, so the trigger then needs its
+     * own name: visible text, or an `aria-label` (which the tooltip overrides
+     * while enabled). The trigger's own `aria-labelledby` and `aria-describedby`
+     * are kept. It must match between the server render and the first client
+     * render.
+     */
+    relationship?: TooltipRelationship;
+    trigger: ReactElement<TooltipTriggerAria>;
 };
-export declare function Tooltip({ content, disabled, trigger }: TooltipProps): import("react").JSX.Element;
+export declare function Tooltip({ content, disabled, relationship, trigger, }: TooltipProps): import("react").JSX.Element;

package/dist/components/Tooltip.js

@@ -1,7 +1,8 @@
 '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, disabled = false, trigger }) {
+import { tooltipTriggerAria, } from './tooltip-trigger-aria.js';
+export function Tooltip({ content, disabled = false, relationship = 'description', trigger, }) {
     if (!content.trim())
         throw new RangeError('content must not be empty');
     // `open` follows focus, hover and touch even while disabled; `shown` is
@@ -10,9 +11,7 @@ export function Tooltip({ content, disabled = false, trigger }) {
     const shown = open && !disabled;
     const id = useId();
     const wrapperRef = useRef(null);
-    const describedBy = [trigger.props['aria-describedby'], disabled ? undefined : id]
-        .filter(Boolean)
-        .join(' ') || undefined;
+    const triggerAria = tooltipTriggerAria(trigger.props, disabled ? undefined : id, relationship);
     useEffect(() => {
         if (!open)
             return;
@@ -43,5 +42,5 @@ export function Tooltip({ content, disabled = false, trigger }) {
         }, onPointerDownCapture: (event) => {
             if (event.pointerType === 'touch')
                 setOpen((current) => !current);
-        }, ref: wrapperRef, children: [cloneElement(trigger, { 'aria-describedby': describedBy }), disabled ? null : (_jsx("span", { className: "sw-tooltip", hidden: !shown, id: id, role: "tooltip", children: content }))] }));
+        }, ref: wrapperRef, children: [cloneElement(trigger, triggerAria), disabled ? null : (_jsx("span", { className: "sw-tooltip", hidden: !shown, id: id, role: "tooltip", children: content }))] }));
 }

package/dist/components/tooltip-trigger-aria.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What a tooltip is to its trigger. A `description` supplements a trigger
+ * that already has a name; a `label` is the trigger's name, for an icon-only
+ * control whose tooltip says what it is.
+ */
+export type TooltipRelationship = 'description' | 'label';
+/** The trigger's own references, kept and joined with the tooltip's id. */
+export type TooltipTriggerAria = {
+    'aria-describedby'?: string;
+    'aria-labelledby'?: string;
+};
+export declare function tooltipTriggerAria(own: TooltipTriggerAria, tooltipId: string | undefined, relationship: TooltipRelationship): TooltipTriggerAria;

package/dist/components/tooltip-trigger-aria.js

@@ -0,0 +1,23 @@
+/*
+ * A description tooltip adds its id to the trigger's own `aria-describedby`
+ * and leaves its `aria-labelledby` exactly as it was. A label tooltip adds
+ * its id to the trigger's own `aria-labelledby` instead and leaves its
+ * `aria-describedby` as it was, so its text is the trigger's name (it wins
+ * over an `aria-label`) and is read once, not as both name and description.
+ * A disabled tooltip is not rendered (`tooltipId` undefined), so the trigger
+ * never points at a missing element.
+ */
+export function tooltipTriggerAria(own, tooltipId, relationship) {
+    if (relationship === 'label')
+        return {
+            'aria-describedby': own['aria-describedby'],
+            'aria-labelledby': joinIdRefs(own['aria-labelledby'], tooltipId),
+        };
+    return {
+        'aria-describedby': joinIdRefs(own['aria-describedby'], tooltipId),
+        'aria-labelledby': own['aria-labelledby'],
+    };
+}
+function joinIdRefs(...ids) {
+    return ids.filter(Boolean).join(' ') || undefined;
+}

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { CalendarButton, type CalendarButtonLabels, type CalendarButtonProps, }
 export { Checkbox, type CheckboxProps } from './components/Checkbox.js';
 export { Spinner, type SpinnerProps, type SpinnerSize, } from './components/Spinner.js';
 export { Progress, type ProgressProps, type ProgressTone, } from './components/Progress.js';
-export { Tooltip, type TooltipProps } from './components/Tooltip.js';
+export { Tooltip, type TooltipProps, type TooltipRelationship, } from './components/Tooltip.js';
 export { RadioGroup, type RadioGroupOption, type RadioGroupProps, } from './components/RadioGroup.js';
 export { AppHeader, type AppHeaderProps } from './components/AppHeader.js';
 export { Badge, type BadgeProps, type BadgeSize, type BadgeTone, badgeSizes, badgeTones, } from './components/Badge.js';

package/dist/index.js

@@ -7,7 +7,7 @@ export { CalendarButton, } from './components/CalendarButton.js';
 export { Checkbox } from './components/Checkbox.js';
 export { Spinner, } from './components/Spinner.js';
 export { Progress, } from './components/Progress.js';
-export { Tooltip } from './components/Tooltip.js';
+export { Tooltip, } from './components/Tooltip.js';
 export { RadioGroup, } from './components/RadioGroup.js';
 export { AppHeader } from './components/AppHeader.js';
 export { Badge, badgeSizes, badgeTones, } from './components/Badge.js';

package/package.json

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