rift-ds 1.9.0 → 1.11.0

package/components/Timeline/Timeline.css

@@ -116,7 +116,7 @@
 
 /* Align dot markers with the title's line box */
 .ds-timeline--vertical .ds-timeline__marker {
-  margin-top: 6px;
+  margin-top: 6px; /* ds-allow(spacing): centres the dot on the title's first line box */
 }
 
 .ds-timeline--vertical .ds-timeline__marker--badge,
@@ -315,7 +315,7 @@
 
 .ds-timeline__role-bullets {
   margin: 0;
-  padding-left: 20px;
+  padding-left: var(--padding-500);
   list-style: disc;
   display: flex;
   flex-direction: column;

package/components/Timeline/Timeline.d.ts

@@ -54,14 +54,23 @@ export interface TimelineCompanyProps {
     variant: 'company';
     /** Ordered list of company/tool entries */
     items: TimelineCompany[];
+    /** Text shown in place of the end date for a role marked `present` */
+    presentLabel?: string;
     /** Additional CSS classes */
     className?: string;
 }
-export type TimelineProps = TimelineDefaultProps | TimelineCompanyProps;
+/**
+ * Timeline props: one of the two variants' own props, plus the native `<ol>`
+ * attributes, which reach the list in both variants.
+ */
+export type TimelineProps = (TimelineDefaultProps | TimelineCompanyProps) & Omit<React.ComponentPropsWithoutRef<'ol'>, keyof TimelineDefaultProps | keyof TimelineCompanyProps | 'children'>;
 /**
  * Timeline component — an ordered sequence of steps or events with
  * connected markers. Vertical for histories and process narratives,
  * horizontal for compact steppers. The `company` variant groups one or
  * more roles under a logo marker for résumé/pipeline histories.
+ *
+ * The forwarded ref and any unrecognised props target the `<ol>` in both
+ * variants.
  */
-export declare const Timeline: (props: TimelineProps) => React.JSX.Element;
+export declare const Timeline: React.ForwardRefExoticComponent<TimelineProps & React.RefAttributes<HTMLOListElement>>;

package/components/Timeline/Timeline.js

@@ -1,40 +1,50 @@
 import { jsx, jsxs } from "react/jsx-runtime";
-import "react";
+import React from "react";
 import "./Timeline.css";
 import "../../fonts/material-symbols.css";
 const BASE_CLASS = "ds-timeline";
-const renderRoleDates = (role) => {
+const renderRoleDates = (role, presentLabel) => {
   if (!role.start) return null;
   return /* @__PURE__ */ jsxs("span", { className: `${BASE_CLASS}__role-dates`, children: [
     role.start,
     " –",
     " ",
-    role.present ? /* @__PURE__ */ jsx("span", { className: `${BASE_CLASS}__present`, children: "Present" }) : role.end
+    role.present ? /* @__PURE__ */ jsx("span", { className: `${BASE_CLASS}__present`, children: presentLabel }) : role.end
   ] });
 };
-const CompanyTimeline = ({ items, className = "" }) => {
-  const classes = [BASE_CLASS, `${BASE_CLASS}--vertical`, `${BASE_CLASS}--company`, className].filter(Boolean).join(" ");
-  return /* @__PURE__ */ jsx("ol", { className: classes, children: items.map((company, index) => /* @__PURE__ */ jsxs("li", { className: `${BASE_CLASS}__item`, children: [
-    /* @__PURE__ */ jsx("span", { className: `${BASE_CLASS}__marker ${BASE_CLASS}__marker--logo`, "aria-hidden": "true", children: company.logo }),
-    /* @__PURE__ */ jsxs("div", { className: `${BASE_CLASS}__content`, children: [
-      /* @__PURE__ */ jsx("span", { className: `${BASE_CLASS}__company-name`, children: company.name }),
-      /* @__PURE__ */ jsx("div", { className: `${BASE_CLASS}__roles`, children: company.roles.map((role, roleIndex) => /* @__PURE__ */ jsxs("div", { className: `${BASE_CLASS}__role`, children: [
-        /* @__PURE__ */ jsxs("div", { className: `${BASE_CLASS}__role-header`, children: [
-          /* @__PURE__ */ jsx("h3", { className: `${BASE_CLASS}__role-title`, children: role.title }),
-          renderRoleDates(role)
-        ] }),
-        role.subtitle && /* @__PURE__ */ jsx("p", { className: `${BASE_CLASS}__role-subtitle`, children: role.subtitle }),
-        role.description && /* @__PURE__ */ jsx("p", { className: `${BASE_CLASS}__role-description`, children: role.description }),
-        role.bullets && role.bullets.length > 0 && /* @__PURE__ */ jsx("ul", { className: `${BASE_CLASS}__role-bullets`, children: role.bullets.map((bullet, bulletIndex) => /* @__PURE__ */ jsx("li", { children: bullet }, bulletIndex)) })
-      ] }, `${role.title}-${roleIndex}`)) })
-    ] })
-  ] }, `${company.name}-${index}`)) });
-};
-const Timeline = (props) => {
+const CompanyTimeline = React.forwardRef(
+  // `variant` is the discriminant, not an <ol> attribute, so it is held back from the spread.
+  ({ variant: _variant, items, presentLabel = "Present", className = "", ...rest }, ref) => {
+    const classes = [BASE_CLASS, `${BASE_CLASS}--vertical`, `${BASE_CLASS}--company`, className].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsx("ol", { ...rest, ref, className: classes, children: items.map((company, index) => /* @__PURE__ */ jsxs("li", { className: `${BASE_CLASS}__item`, children: [
+      /* @__PURE__ */ jsx("span", { className: `${BASE_CLASS}__marker ${BASE_CLASS}__marker--logo`, "aria-hidden": "true", children: company.logo }),
+      /* @__PURE__ */ jsxs("div", { className: `${BASE_CLASS}__content`, children: [
+        /* @__PURE__ */ jsx("span", { className: `${BASE_CLASS}__company-name`, children: company.name }),
+        /* @__PURE__ */ jsx("div", { className: `${BASE_CLASS}__roles`, children: company.roles.map((role, roleIndex) => /* @__PURE__ */ jsxs("div", { className: `${BASE_CLASS}__role`, children: [
+          /* @__PURE__ */ jsxs("div", { className: `${BASE_CLASS}__role-header`, children: [
+            /* @__PURE__ */ jsx("h3", { className: `${BASE_CLASS}__role-title`, children: role.title }),
+            renderRoleDates(role, presentLabel)
+          ] }),
+          role.subtitle && /* @__PURE__ */ jsx("p", { className: `${BASE_CLASS}__role-subtitle`, children: role.subtitle }),
+          role.description && /* @__PURE__ */ jsx("p", { className: `${BASE_CLASS}__role-description`, children: role.description }),
+          role.bullets && role.bullets.length > 0 && /* @__PURE__ */ jsx("ul", { className: `${BASE_CLASS}__role-bullets`, children: role.bullets.map((bullet, bulletIndex) => /* @__PURE__ */ jsx("li", { children: bullet }, bulletIndex)) })
+        ] }, `${role.title}-${roleIndex}`)) })
+      ] })
+    ] }, `${company.name}-${index}`)) });
+  }
+);
+CompanyTimeline.displayName = "CompanyTimeline";
+const Timeline = React.forwardRef(({
+  orientation = "vertical",
+  numbered = false,
+  presentLabel = "Present",
+  className = "",
+  ...props
+}, ref) => {
   if (props.variant === "company") {
-    return /* @__PURE__ */ jsx(CompanyTimeline, { ...props });
+    return /* @__PURE__ */ jsx(CompanyTimeline, { ...props, presentLabel, className, ref });
   }
-  const { items, orientation = "vertical", numbered = false, className = "" } = props;
+  const { variant: _variant, items, ...rest } = props;
   const classes = [
     BASE_CLASS,
     `${BASE_CLASS}--${orientation}`,
@@ -53,7 +63,7 @@ const Timeline = (props) => {
     }
     return null;
   };
-  return /* @__PURE__ */ jsx("ol", { className: classes, children: items.map((item, index) => /* @__PURE__ */ jsxs("li", { className: `${BASE_CLASS}__item`, children: [
+  return /* @__PURE__ */ jsx("ol", { ...rest, ref, className: classes, children: items.map((item, index) => /* @__PURE__ */ jsxs("li", { className: `${BASE_CLASS}__item`, children: [
     /* @__PURE__ */ jsx(
       "span",
       {
@@ -67,7 +77,8 @@ const Timeline = (props) => {
       item.description && /* @__PURE__ */ jsx("div", { className: `${BASE_CLASS}__description`, children: item.description })
     ] })
   ] }, `${item.title}-${index}`)) });
-};
+});
+Timeline.displayName = "Timeline";
 export {
   Timeline
 };

package/components/Toast/Toast.css

@@ -17,7 +17,7 @@
 
 .ds-toast-container {
   position: fixed;
-  z-index: var(--ds-toast-z, 200);
+  z-index: var(--ds-toast-z, var(--layer-toast));
   display: flex;
   flex-direction: column;
   gap: var(--gap-200); /* 8px */
@@ -170,7 +170,7 @@
   height: 3px;
   width: 100%;
   transform-origin: left;
-  animation: ds-toast-progress linear forwards;
+  animation: ds-toast-progress var(--motion-ease-linear) forwards;
 }
 
 /* ============================================

package/components/Toast/Toast.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode } from 'react';
+import { default as React, ReactNode } from 'react';
 export interface ToastData {
     /** Unique ID (auto-generated if not provided) */
     id?: string;
@@ -22,6 +22,10 @@ export interface ToastProviderProps {
     position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center';
     /** Maximum number of visible toasts */
     maxToasts?: number;
+    /** Accessible name of the toast stack's region landmark */
+    regionLabel?: string;
+    /** Accessible name of every toast's dismiss button */
+    dismissLabel?: string;
 }
 export interface ToastContextValue {
     /** Add a toast */
@@ -41,23 +45,37 @@ export declare const useToast: () => ToastContextValue;
  * toast context. Renders a fixed container that stacks
  * toast notifications.
  */
-export declare const ToastProvider: ({ children, position, maxToasts, }: ToastProviderProps) => import("react").JSX.Element;
-export interface ToastProps {
-    /** Toast title text */
+export declare const ToastProvider: ({ children, position, maxToasts, regionLabel, dismissLabel, }: ToastProviderProps) => React.JSX.Element;
+/** Props owned by the standalone Toast itself — everything else falls through to its `role="status"` `<div>`. */
+type ToastOwnProps = {
+    /**
+     * Toast title text.
+     * Note: this shadows the native `title` tooltip attribute, which Toast does not expose.
+     */
     title?: string;
     /** Toast description / body text */
     description?: string;
     /** Toast variant */
     variant?: 'info' | 'positive' | 'warning' | 'error' | 'neutral';
-    /** Whether the toast can be manually dismissed */
+    /** Whether the toast can be manually dismissed. The dismiss button renders only when `onDismiss` is also given */
     dismissible?: boolean;
     /** Custom icon override — Material Symbol name (string) or custom element (ReactNode) */
     icon?: string | React.ReactNode;
+    /** Fires when the dismiss button is pressed. The button renders only when this is given (and `dismissible` is not false); the host owns removing the toast */
+    onDismiss?: () => void;
+    /** Accessible name of the dismiss button */
+    dismissLabel?: string;
     /** Additional CSS classes */
     className?: string;
+};
+export interface ToastProps extends ToastOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof ToastOwnProps | 'role' | 'children'> {
 }
 /**
  * Standalone Toast component for static display.
  * For dynamic toast notifications, use ToastProvider + useToast.
+ *
+ * The forwarded ref and any unrecognised props target the `role="status"`
+ * `<div>`.
  */
-export declare const Toast: ({ title, description, variant, dismissible, icon, className, }: ToastProps) => import("react").JSX.Element;
+export declare const Toast: React.ForwardRefExoticComponent<ToastProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/components/Toast/Toast.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsxs, jsx } from "react/jsx-runtime";
-import { useState, useSyncExternalStore, useCallback, useContext, createContext, useRef, useEffect } from "react";
+import React, { useState, useSyncExternalStore, useCallback, useContext, createContext, useRef, useEffect } from "react";
 import { MOTION_AUTO_DISMISS_MS, MOTION_EXIT_SYNC_MS } from "../../tokens/motion.js";
 import ReactDOM from "react-dom";
 import "./Toast.css";
@@ -31,6 +31,7 @@ const ToastItem = ({
   dismissible,
   icon,
   duration,
+  dismissLabel,
   onDismiss
 }) => {
   const [exiting, setExiting] = useState(false);
@@ -87,7 +88,7 @@ const ToastItem = ({
             type: "button",
             className: `${baseClass}__dismiss`,
             onClick: handleDismiss,
-            "aria-label": "Dismiss notification",
+            "aria-label": dismissLabel,
             children: /* @__PURE__ */ jsx("span", { className: "material-symbols-rounded", "aria-hidden": "true", children: "close" })
           }
         ),
@@ -108,7 +109,9 @@ const ToastItem = ({
 const ToastProvider = ({
   children,
   position = "bottom-right",
-  maxToasts = 5
+  maxToasts = 5,
+  regionLabel = "Notifications",
+  dismissLabel = "Dismiss notification"
 }) => {
   const [toasts, setToasts] = useState([]);
   const mounted = useSyncExternalStore(emptySubscribe, () => true, () => false);
@@ -149,7 +152,7 @@ const ToastProvider = ({
         {
           className: containerClasses,
           role: "region",
-          "aria-label": "Notifications",
+          "aria-label": regionLabel,
           "aria-live": "polite",
           children: toasts.map((t) => /* @__PURE__ */ jsx(
             ToastItem,
@@ -161,6 +164,7 @@ const ToastProvider = ({
               dismissible: t.dismissible ?? true,
               icon: t.icon,
               duration: t.duration ?? MOTION_AUTO_DISMISS_MS,
+              dismissLabel,
               onDismiss: dismiss
             },
             t.id
@@ -171,43 +175,48 @@ const ToastProvider = ({
     )
   ] });
 };
-const Toast = ({
-  title,
-  description,
-  variant = "info",
-  dismissible = true,
-  icon,
-  className = ""
-}) => {
-  const baseClass = "ds-toast";
-  const iconName = icon || defaultIcons[variant];
-  const classes = [baseClass, `${baseClass}--${variant}`, className].filter(Boolean).join(" ");
-  return /* @__PURE__ */ jsxs("div", { className: classes, role: "status", children: [
-    /* @__PURE__ */ jsx(
-      "span",
-      {
-        className: `${baseClass}__icon${typeof iconName === "string" ? " material-symbols-rounded" : ""}`,
-        "aria-hidden": "true",
-        children: iconName
-      }
-    ),
-    /* @__PURE__ */ jsxs("div", { className: `${baseClass}__content`, children: [
-      title && /* @__PURE__ */ jsx("p", { className: `${baseClass}__title`, children: title }),
-      description && /* @__PURE__ */ jsx("p", { className: `${baseClass}__description`, children: description })
-    ] }),
-    dismissible && /* @__PURE__ */ jsx(
-      "button",
-      {
-        type: "button",
-        className: `${baseClass}__dismiss`,
-        onClick: () => {
-        },
-        "aria-label": "Dismiss notification",
-        children: /* @__PURE__ */ jsx("span", { className: "material-symbols-rounded", "aria-hidden": "true", children: "close" })
-      }
-    )
-  ] });
-};
+const Toast = React.forwardRef(
+  ({
+    title,
+    description,
+    variant = "info",
+    dismissible = true,
+    icon,
+    onDismiss,
+    dismissLabel = "Dismiss notification",
+    className = "",
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-toast";
+    const iconName = icon || defaultIcons[variant];
+    const classes = [baseClass, `${baseClass}--${variant}`, className].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsxs("div", { ...rest, ref, className: classes, role: "status", children: [
+      /* @__PURE__ */ jsx(
+        "span",
+        {
+          className: `${baseClass}__icon${typeof iconName === "string" ? " material-symbols-rounded" : ""}`,
+          "aria-hidden": "true",
+          children: iconName
+        }
+      ),
+      /* @__PURE__ */ jsxs("div", { className: `${baseClass}__content`, children: [
+        title && /* @__PURE__ */ jsx("p", { className: `${baseClass}__title`, children: title }),
+        description && /* @__PURE__ */ jsx("p", { className: `${baseClass}__description`, children: description })
+      ] }),
+      dismissible && onDismiss && /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          className: `${baseClass}__dismiss`,
+          onClick: () => onDismiss(),
+          "aria-label": dismissLabel,
+          children: /* @__PURE__ */ jsx("span", { className: "material-symbols-rounded", "aria-hidden": "true", children: "close" })
+        }
+      )
+    ] });
+  }
+);
+Toast.displayName = "Toast";
 export {
   Toast,
   ToastProvider,

package/components/ToggleGroup/ToggleGroup.css

@@ -63,9 +63,10 @@
 }
 
 /* ============================================
-   NEUTRAL VARIANT
+   NEUTRAL TONE (tone="neutral"; the legacy
+   variant="neutral" keeps this class)
    Active items fill grey instead of the action
-   teal — for sets where the selection should
+   colour — for sets where the selection should
    not carry the action colour's weight.
    ============================================ */
 

package/components/ToggleGroup/ToggleGroup.d.ts

@@ -11,13 +11,32 @@ export interface ToggleGroupItem {
 type ToggleGroupOwnProps = {
     /** Available items */
     items: ToggleGroupItem[];
-    /** Currently active value(s) */
+    /**
+     * Currently active value(s), controlled. Leave undefined to let the group
+     * keep its own selection, seeded from `defaultValue`.
+     */
     value?: string | string[];
-    /** Allow multiple selection */
+    /** Active value(s) on first render when uncontrolled (`value` undefined). */
+    defaultValue?: string | string[];
+    /**
+     * Allow multiple selection, where each item toggles on or off. Without it
+     * exactly one item is active once chosen, and pressing it again keeps it.
+     */
     multiple?: boolean;
     /** Component size */
     size?: 'default' | 'compact';
-    /** Visual treatment of active items — teal by default, `neutral` fills them grey */
+    /**
+     * Colour of active items: `default` takes the action colour, `neutral`
+     * fills them grey, for a set whose selection should not carry the action
+     * colour's weight.
+     */
+    tone?: 'default' | 'neutral';
+    /**
+     * Legacy name for `tone`, from before colour moved onto its own prop:
+     * `primary` is `tone="default"`.
+     *
+     * @deprecated Use `tone` instead.
+     */
     variant?: 'primary' | 'neutral';
     /** Whether the whole group is disabled */
     disabled?: boolean;
@@ -41,7 +60,10 @@ type ToggleGroupOwnProps = {
 export interface ToggleGroupProps extends ToggleGroupOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof ToggleGroupOwnProps> {
 }
 /**
- * ToggleGroup is a set of two-state buttons that can be toggled on or off.
+ * ToggleGroup is a set of pressable buttons. By default it is single
+ * selection: pressing an item makes it the one active item, and pressing the
+ * active item again keeps it active. With `multiple`, each item toggles on or
+ * off independently.
  *
  * Forwards a ref to the wrapping group element and spreads unrecognised props
  * onto it.

package/components/ToggleGroup/ToggleGroup.js

@@ -5,10 +5,12 @@ import "./ToggleGroup.css";
 const ToggleGroup = React.forwardRef(
   ({
     items,
-    value = [],
+    value,
+    defaultValue = [],
     multiple = false,
     size = "default",
-    variant = "primary",
+    tone,
+    variant,
     disabled = false,
     onValueChange,
     onChange,
@@ -17,15 +19,20 @@ const ToggleGroup = React.forwardRef(
     ...rest
   }, ref) => {
     const baseClass = "ds-toggle-group";
+    const resolvedTone = tone ?? (variant === "neutral" ? "neutral" : "default");
     const classes = [
       baseClass,
       `${baseClass}--${size}`,
-      `${baseClass}--${variant}`,
+      `${baseClass}--${resolvedTone === "neutral" ? "neutral" : "primary"}`,
       disabled ? `${baseClass}--disabled` : "",
       className
     ].filter(Boolean).join(" ");
-    const activeValues = Array.isArray(value) ? value : [value];
+    const [internalValue, setInternalValue] = React.useState(defaultValue);
+    const isControlled = value !== void 0;
+    const currentValue = isControlled ? value : internalValue;
+    const activeValues = Array.isArray(currentValue) ? currentValue : [currentValue];
     const emit = (next) => {
+      if (!isControlled) setInternalValue(next);
       onValueChange?.(next);
       onChange?.(next);
     };
@@ -45,7 +52,7 @@ const ToggleGroup = React.forwardRef(
         ref,
         className: classes,
         role: "group",
-        "aria-label": ariaLabel || rest["aria-label"],
+        "aria-label": rest["aria-label"] ?? ariaLabel,
         children: items.map((item) => {
           const isActive = activeValues.includes(item.value);
           const btnClass = [`${baseClass}__item`, isActive ? `${baseClass}__item--active` : ""].filter(Boolean).join(" ");

package/components/ToggleSwitch/ToggleSwitch.d.ts

@@ -1,8 +1,13 @@
 import { default as React } from 'react';
 /** Props owned by ToggleSwitch itself — everything else falls through to the <button>. */
 type ToggleSwitchOwnProps = {
-    /** Whether the toggle is on (checked) */
+    /**
+     * Whether the toggle is on, controlled. Leave undefined to let the switch
+     * keep its own state, seeded from `defaultChecked`.
+     */
     checked?: boolean;
+    /** Whether the toggle starts on when uncontrolled (`checked` undefined). Defaults to true, so an uncontrolled switch starts on unless this is false. */
+    defaultChecked?: boolean;
     /** Label text displayed next to the toggle */
     label?: string;
     /** Whether to show the label */

package/components/ToggleSwitch/ToggleSwitch.js

@@ -1,11 +1,12 @@
 "use client";
 import { jsxs, jsx } from "react/jsx-runtime";
-import React, { useId } from "react";
+import React, { useState, useId } from "react";
 import "./ToggleSwitch.css";
 import "../../fonts/material-symbols.css";
 const ToggleSwitch = React.forwardRef(
   ({
-    checked = true,
+    checked: checkedProp,
+    defaultChecked = true,
     label = "Toggle",
     showLabel = true,
     helperText,
@@ -20,6 +21,9 @@ const ToggleSwitch = React.forwardRef(
     ...rest
   }, ref) => {
     const baseClass = "ds-toggle-switch";
+    const [internalChecked, setInternalChecked] = useState(defaultChecked);
+    const isControlled = checkedProp !== void 0;
+    const checked = isControlled ? checkedProp : internalChecked;
     const generatedId = useId();
     const helperId = helperText ? `${generatedId}-helper` : void 0;
     const describedBy = helperId ?? rest["aria-describedby"];
@@ -35,6 +39,7 @@ const ToggleSwitch = React.forwardRef(
     const handleClick = (e) => {
       onClick?.(e);
       if (disabled) return;
+      if (!isControlled) setInternalChecked(!checked);
       onCheckedChange?.(!checked);
       onChange?.(!checked);
     };

package/components/ToolCall/ToolCall.js

@@ -50,7 +50,7 @@ const ToolCall = React.forwardRef(
       className
     ].filter(Boolean).join(" ");
     const header = /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx("span", { className: `${baseClass}__indicator`, "aria-hidden": "true", children: status === "running" ? /* @__PURE__ */ jsx(Spinner, { size: "sm", variant: "inherit" }) : /* @__PURE__ */ jsx("span", { className: "material-symbols-rounded", children: STATUS_ICONS[status] }) }),
+      /* @__PURE__ */ jsx("span", { className: `${baseClass}__indicator`, "aria-hidden": "true", children: status === "running" ? /* @__PURE__ */ jsx(Spinner, { size: "sm", tone: "inherit" }) : /* @__PURE__ */ jsx("span", { className: "material-symbols-rounded", children: STATUS_ICONS[status] }) }),
       /* @__PURE__ */ jsx("span", { className: `${baseClass}__name`, children: name }),
       summary && /* @__PURE__ */ jsx("span", { className: `${baseClass}__summary`, children: summary }),
       /* @__PURE__ */ jsx("span", { className: `${baseClass}__status`, children: statusLabel ?? DEFAULT_STATUS_LABELS[status] }),

package/components/Tooltip/Tooltip.css

@@ -14,7 +14,7 @@
 
 .ds-tooltip__panel {
   position: absolute;
-  z-index: 50;
+  z-index: var(--layer-floating);
   padding: var(--padding-150) var(--padding-200); /* 6px 8px */
   border-radius: var(--radius-100); /* 4px */
   /* The floating surface, same recipe as Popover: page background (the
@@ -142,7 +142,7 @@
 .ds-tooltip__panel--top .ds-tooltip__arrow {
   bottom: -5px;
   left: 50%;
-  margin-left: -4px;
+  margin-left: -4px; /* ds-allow(spacing): half the 8px arrow, centring it on the panel edge */
   border-right: var(--border-025) solid var(--color-bg-container-border);
   border-bottom: var(--border-025) solid var(--color-bg-container-border);
 }
@@ -151,7 +151,7 @@
 .ds-tooltip__panel--bottom .ds-tooltip__arrow {
   top: -5px;
   left: 50%;
-  margin-left: -4px;
+  margin-left: -4px; /* ds-allow(spacing): half the 8px arrow */
   border-top: var(--border-025) solid var(--color-bg-container-border);
   border-left: var(--border-025) solid var(--color-bg-container-border);
 }
@@ -160,7 +160,7 @@
 .ds-tooltip__panel--left .ds-tooltip__arrow {
   right: -5px;
   top: 50%;
-  margin-top: -4px;
+  margin-top: -4px; /* ds-allow(spacing): half the 8px arrow */
   border-top: var(--border-025) solid var(--color-bg-container-border);
   border-right: var(--border-025) solid var(--color-bg-container-border);
 }
@@ -169,7 +169,7 @@
 .ds-tooltip__panel--right .ds-tooltip__arrow {
   left: -5px;
   top: 50%;
-  margin-top: -4px;
+  margin-top: -4px; /* ds-allow(spacing): half the 8px arrow */
   border-bottom: var(--border-025) solid var(--color-bg-container-border);
   border-left: var(--border-025) solid var(--color-bg-container-border);
 }

package/components/Tooltip/Tooltip.d.ts

@@ -1,8 +1,11 @@
-import { ReactNode } from 'react';
-export interface TooltipProps {
+import { default as React, ReactNode } from 'react';
+type TooltipOwnProps = {
     /** Trigger element */
     children?: ReactNode;
-    /** Tooltip text content */
+    /**
+     * Tooltip text content. Replaces the native `content` attribute, which only
+     * means something on a `<meta>` element.
+     */
     content: string;
     /** Preferred position */
     position?: 'top' | 'bottom' | 'left' | 'right';
@@ -12,11 +15,19 @@ export interface TooltipProps {
     hideDelay?: number;
     /** Additional CSS classes */
     className?: string;
+};
+export interface TooltipProps extends TooltipOwnProps, Omit<React.ComponentPropsWithoutRef<'span'>, keyof TooltipOwnProps> {
 }
 /**
  * Tooltip component for contextual text labels.
  * Appears on hover or focus with a short delay.
  * Rides the system's floating surface — page background, hairline border,
  * floating shadow — so the bubble stays light in light theme and dark in dark.
+ *
+ * A visible tooltip is a layer on the shared dismissal stack
+ * (src/behaviors/useLayer): Escape hides it wherever focus is (WCAG 1.4.13),
+ * and hides only it, so inside a Dialog the first Escape clears the tooltip
+ * and the second closes the Dialog.
  */
-export declare const Tooltip: ({ children, content, position, showDelay, hideDelay, className, }: TooltipProps) => import("react").JSX.Element;
+export declare const Tooltip: React.ForwardRefExoticComponent<TooltipProps & React.RefAttributes<HTMLSpanElement>>;
+export {};