@sixthshift/design-system 0.2.1 → 0.3.0

package/src/components/LineChart/LineChart.tsx

@@ -1,6 +1,6 @@
 import { Tooltip } from "@sixthshift/design-system/tooltip";
 import { cn } from "@sixthshift/design-system/utils";
-import type * as React from "react";
+import * as React from "react";
 
 export type LineChartDataPoint = {
   label: string;
@@ -96,156 +96,162 @@ function buildPath(points: { x: number; y: number }[], interpolation: Interpolat
   return parts.join(" ");
 }
 
-export const LineChart = ({
-  series,
-  height = 200,
-  showGrid = true,
-  showAxes = true,
-  showDots = true,
-  showLabels = true,
-  showValues = false,
-  interpolation = "monotone",
-  fillArea = false,
-  yMin: yMinProp,
-  yMax: yMaxProp,
-  yTicks = 4,
-  showTooltip = false,
-  formatTooltip,
-  formatValue = (v) => String(v),
-  className,
-  ...rest
-}: LineChartProps) => {
-  const allValues = series.flatMap((s) => s.data.map((d) => d.value));
-  // Math.min() of an empty list is Infinity, which propagates NaN through the
-  // whole scale. Fall back to a plain 0-1 axis when there is no data.
-  const rawMin = yMinProp ?? (allValues.length > 0 ? Math.min(...allValues) : 0);
-  const rawMax = yMaxProp ?? (allValues.length > 0 ? Math.max(...allValues) : 1);
-  const scale = niceScale(rawMin, rawMax, yTicks);
-
-  const labelSet = new Set<string>();
-  for (const s of series) {
-    for (const d of s.data) {
-      labelSet.add(d.label);
+export const LineChart = React.forwardRef<HTMLDivElement, LineChartProps>(
+  (
+    {
+      series,
+      height = 200,
+      showGrid = true,
+      showAxes = true,
+      showDots = true,
+      showLabels = true,
+      showValues = false,
+      interpolation = "monotone",
+      fillArea = false,
+      yMin: yMinProp,
+      yMax: yMaxProp,
+      yTicks = 4,
+      showTooltip = false,
+      formatTooltip,
+      formatValue = (v) => String(v),
+      className,
+      ...rest
+    }: LineChartProps,
+    ref
+  ) => {
+    const allValues = series.flatMap((s) => s.data.map((d) => d.value));
+    // Math.min() of an empty list is Infinity, which propagates NaN through the
+    // whole scale. Fall back to a plain 0-1 axis when there is no data.
+    const rawMin = yMinProp ?? (allValues.length > 0 ? Math.min(...allValues) : 0);
+    const rawMax = yMaxProp ?? (allValues.length > 0 ? Math.max(...allValues) : 1);
+    const scale = niceScale(rawMin, rawMax, yTicks);
+
+    const labelSet = new Set<string>();
+    for (const s of series) {
+      for (const d of s.data) {
+        labelSet.add(d.label);
+      }
     }
-  }
-  const labels = [...labelSet];
-  const labelCount = labels.length;
-  const labelIndex = new Map(labels.map((l, i) => [l, i]));
+    const labels = [...labelSet];
+    const labelCount = labels.length;
+    const labelIndex = new Map(labels.map((l, i) => [l, i]));
 
-  const padding = showAxes ? PADDING : PADDING_NO_AXES;
-  const viewWidth = 600;
-  const chartW = viewWidth - padding.left - padding.right;
-  const chartH = height - padding.top - padding.bottom;
+    const padding = showAxes ? PADDING : PADDING_NO_AXES;
+    const viewWidth = 600;
+    const chartW = viewWidth - padding.left - padding.right;
+    const chartH = height - padding.top - padding.bottom;
 
-  const xStep = labelCount > 1 ? chartW / (labelCount - 1) : 0;
+    const xStep = labelCount > 1 ? chartW / (labelCount - 1) : 0;
 
-  function toX(i: number) {
-    return padding.left + i * xStep;
-  }
+    function toX(i: number) {
+      return padding.left + i * xStep;
+    }
 
-  function toY(v: number) {
-    const ratio = (v - scale.min) / (scale.max - scale.min);
-    return padding.top + chartH - ratio * chartH;
-  }
+    function toY(v: number) {
+      const ratio = (v - scale.min) / (scale.max - scale.min);
+      return padding.top + chartH - ratio * chartH;
+    }
 
-  const yTickValues: number[] = [];
-  for (let v = scale.min; v <= scale.max + scale.step * 0.01; v += scale.step) {
-    yTickValues.push(Math.round(v * 1e6) / 1e6);
-  }
+    const yTickValues: number[] = [];
+    for (let v = scale.min; v <= scale.max + scale.step * 0.01; v += scale.step) {
+      yTickValues.push(Math.round(v * 1e6) / 1e6);
+    }
 
-  function tooltipText(point: LineChartDataPoint, seriesName?: string) {
-    if (formatTooltip) return formatTooltip(point, seriesName);
-    const prefix = seriesName ? `${seriesName}: ` : `${point.label}: `;
-    return `${prefix}${formatValue(point.value)}`;
-  }
+    function tooltipText(point: LineChartDataPoint, seriesName?: string) {
+      if (formatTooltip) return formatTooltip(point, seriesName);
+      const prefix = seriesName ? `${seriesName}: ` : `${point.label}: `;
+      return `${prefix}${formatValue(point.value)}`;
+    }
+
+    return (
+      <div ref={ref} {...rest} className={cn("relative w-full", className)}>
+        <svg viewBox={`0 0 ${viewWidth} ${height}`} className="w-full" preserveAspectRatio="xMidYMid meet" role="img">
+          <title>Line chart</title>
+          {showGrid &&
+            yTickValues.map((v) => (
+              <line
+                key={`grid-${v}`}
+                x1={padding.left}
+                y1={toY(v)}
+                x2={viewWidth - padding.right}
+                y2={toY(v)}
+                className="stroke-border-subtle"
+                strokeWidth={1}
+                strokeDasharray="4 4"
+              />
+            ))}
 
-  return (
-    <div {...rest} className={cn("relative w-full", className)}>
-      <svg viewBox={`0 0 ${viewWidth} ${height}`} className="w-full" preserveAspectRatio="xMidYMid meet" role="img">
-        <title>Line chart</title>
-        {showGrid &&
-          yTickValues.map((v) => (
-            <line
-              key={`grid-${v}`}
-              x1={padding.left}
-              y1={toY(v)}
-              x2={viewWidth - padding.right}
-              y2={toY(v)}
-              className="stroke-border-subtle"
-              strokeWidth={1}
-              strokeDasharray="4 4"
-            />
-          ))}
-
-        {showAxes && (
-          <>
-            <line x1={padding.left} y1={padding.top} x2={padding.left} y2={padding.top + chartH} className="stroke-border-normal" strokeWidth={1} />
-            <line
-              x1={padding.left}
-              y1={padding.top + chartH}
-              x2={viewWidth - padding.right}
-              y2={padding.top + chartH}
-              className="stroke-border-normal"
-              strokeWidth={1}
-            />
-            {yTickValues.map((v) => (
-              <text key={`ytick-${v}`} x={padding.left - 8} y={toY(v)} textAnchor="end" dominantBaseline="middle" className="fill-fg-subtle" fontSize={11}>
-                {formatValue(v)}
+          {showAxes && (
+            <>
+              <line x1={padding.left} y1={padding.top} x2={padding.left} y2={padding.top + chartH} className="stroke-border-normal" strokeWidth={1} />
+              <line
+                x1={padding.left}
+                y1={padding.top + chartH}
+                x2={viewWidth - padding.right}
+                y2={padding.top + chartH}
+                className="stroke-border-normal"
+                strokeWidth={1}
+              />
+              {yTickValues.map((v) => (
+                <text key={`ytick-${v}`} x={padding.left - 8} y={toY(v)} textAnchor="end" dominantBaseline="middle" className="fill-fg-subtle" fontSize={11}>
+                  {formatValue(v)}
+                </text>
+              ))}
+            </>
+          )}
+
+          {showLabels &&
+            labels.map((label, i) => (
+              <text key={`xlabel-${label}`} x={toX(i)} y={height - 4} textAnchor="middle" className="fill-fg-subtle" fontSize={11}>
+                {label}
               </text>
             ))}
-          </>
-        )}
-
-        {showLabels &&
-          labels.map((label, i) => (
-            <text key={`xlabel-${label}`} x={toX(i)} y={height - 4} textAnchor="middle" className="fill-fg-subtle" fontSize={11}>
-              {label}
-            </text>
-          ))}
-
-        {series.map((s, si) => {
-          const color = s.color ?? SERIES_COLORS[si % SERIES_COLORS.length];
-          const points = s.data.map((d) => ({ x: toX(labelIndex.get(d.label)!), y: toY(d.value) }));
-          const path = buildPath(points, interpolation);
-
-          return (
-            <g key={s.name ?? si}>
-              {fillArea && path && (
-                <path
-                  d={`${path} L ${points[points.length - 1]!.x} ${padding.top + chartH} L ${points[0]!.x} ${padding.top + chartH} Z`}
-                  fill={color}
-                  opacity={0.1}
-                />
-              )}
-              {path && <path d={path} fill="none" stroke={color} strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" />}
-              {showDots && points.map((p, pi) => <circle key={`dot-${s.data[pi]!.label}`} cx={p.x} cy={p.y} r={3} fill={color} />)}
-              {showValues &&
-                points.map((p, vi) => (
-                  <text key={`val-${s.data[vi]!.label}`} x={p.x} y={p.y - 10} textAnchor="middle" className="fill-fg-normal" fontSize={10} fontWeight={600}>
-                    {formatValue(s.data[vi]!.value)}
-                  </text>
-                ))}
-            </g>
-          );
-        })}
-      </svg>
-
-      {showTooltip &&
-        series.map((s, si) =>
-          s.data.map((d) => {
-            const xPct = (toX(labelIndex.get(d.label)!) / viewWidth) * 100;
-            const yPct = (toY(d.value) / height) * 100;
+
+          {series.map((s, si) => {
+            const color = s.color ?? SERIES_COLORS[si % SERIES_COLORS.length];
+            const points = s.data.map((d) => ({ x: toX(labelIndex.get(d.label)!), y: toY(d.value) }));
+            const path = buildPath(points, interpolation);
 
             return (
-              <Tooltip key={`tip-${s.name ?? si}-${d.label}`} delayShow={0}>
-                <Tooltip.Trigger asChild>
-                  <span className="absolute block -translate-x-1/2 -translate-y-1/2" style={{ left: `${xPct}%`, top: `${yPct}%`, width: 16, height: 16 }} />
-                </Tooltip.Trigger>
-                <Tooltip.Body>{tooltipText(d, s.name)}</Tooltip.Body>
-              </Tooltip>
+              <g key={s.name ?? si}>
+                {fillArea && path && (
+                  <path
+                    d={`${path} L ${points[points.length - 1]!.x} ${padding.top + chartH} L ${points[0]!.x} ${padding.top + chartH} Z`}
+                    fill={color}
+                    opacity={0.1}
+                  />
+                )}
+                {path && <path d={path} fill="none" stroke={color} strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" />}
+                {showDots && points.map((p, pi) => <circle key={`dot-${s.data[pi]!.label}`} cx={p.x} cy={p.y} r={3} fill={color} />)}
+                {showValues &&
+                  points.map((p, vi) => (
+                    <text key={`val-${s.data[vi]!.label}`} x={p.x} y={p.y - 10} textAnchor="middle" className="fill-fg-normal" fontSize={10} fontWeight={600}>
+                      {formatValue(s.data[vi]!.value)}
+                    </text>
+                  ))}
+              </g>
             );
-          })
-        )}
-    </div>
-  );
-};
+          })}
+        </svg>
+
+        {showTooltip &&
+          series.map((s, si) =>
+            s.data.map((d) => {
+              const xPct = (toX(labelIndex.get(d.label)!) / viewWidth) * 100;
+              const yPct = (toY(d.value) / height) * 100;
+
+              return (
+                <Tooltip key={`tip-${s.name ?? si}-${d.label}`} delayShow={0}>
+                  <Tooltip.Trigger asChild>
+                    <span className="absolute block -translate-x-1/2 -translate-y-1/2" style={{ left: `${xPct}%`, top: `${yPct}%`, width: 16, height: 16 }} />
+                  </Tooltip.Trigger>
+                  <Tooltip.Body>{tooltipText(d, s.name)}</Tooltip.Body>
+                </Tooltip>
+              );
+            })
+          )}
+      </div>
+    );
+  }
+);
+LineChart.displayName = "LineChart";

package/src/components/Markdown/Markdown.tsx

@@ -2,6 +2,7 @@ import { Body } from "@sixthshift/design-system/body";
 import { Emphasis } from "@sixthshift/design-system/emphasis";
 import { Heading } from "@sixthshift/design-system/heading";
 import { cn } from "@sixthshift/design-system/utils";
+import * as React from "react";
 import ReactMarkdown from "react-markdown";
 
 export type MarkdownProps = {
@@ -9,8 +10,8 @@ export type MarkdownProps = {
   className?: string;
 };
 
-export const Markdown = ({ children, className }: MarkdownProps) => (
-  <div className={cn("flex flex-col", className)}>
+export const Markdown = React.forwardRef<HTMLDivElement, MarkdownProps>(({ children, className }, ref) => (
+  <div ref={ref} className={cn("flex flex-col", className)}>
     <ReactMarkdown
       components={{
         h1: ({ children }) => <Heading as="h3">{children}</Heading>,
@@ -36,5 +37,5 @@ export const Markdown = ({ children, className }: MarkdownProps) => (
       {children}
     </ReactMarkdown>
   </div>
-);
+));
 Markdown.displayName = "Markdown";

package/src/components/Message/Message.tsx

@@ -33,6 +33,22 @@ export type MessageProps = React.HTMLAttributes<HTMLDivElement> &
     icon?: React.ReactNode;
   };
 
+/**
+ * A message is a live region, and the intent decides how rudely it interrupts.
+ * `danger` is the only intent that earns `role="alert"` — an assertive region
+ * cuts off whatever the screen reader was saying. Everything else is
+ * `role="status"` (polite), which is announced at the next natural pause. A
+ * success confirmation or a static "Note" callout stamped as `alert` trains
+ * users to ignore the role that actually matters. Consumers can override by
+ * passing their own `role` — `props` is spread after this.
+ */
+const intentRole = {
+  neutral: "status",
+  success: "status",
+  warning: "status",
+  danger: "alert",
+} as const;
+
 export const Message = React.forwardRef<HTMLDivElement, MessageProps>(({ className, intent = "neutral", size, title, icon, children, ...props }, ref) => {
   const hasCompoundChildren = React.Children.toArray(children).some(
     (child) =>
@@ -41,7 +57,7 @@ export const Message = React.forwardRef<HTMLDivElement, MessageProps>(({ classNa
   );
 
   return (
-    <div ref={ref} role="alert" className={cn(messageVariants({ intent, size, className }))} {...props}>
+    <div ref={ref} role={intentRole[intent ?? "neutral"]} className={cn(messageVariants({ intent, size, className }))} {...props}>
       {hasCompoundChildren ? (
         children
       ) : (

package/src/components/MetricList/MetricList.tsx

@@ -1,13 +1,18 @@
 import { cn } from "@sixthshift/design-system/utils";
-import type { ReactNode } from "react";
+import * as React from "react";
 
 export type MetricListProps = {
   /** Metric rows */
-  children: ReactNode;
+  children: React.ReactNode;
   /** Additional CSS classes */
   className?: string;
 };
 
-export const MetricList = ({ children, className }: MetricListProps) => {
-  return <div className={cn("flex flex-col gap-2 text-fg-subtle", className)}>{children}</div>;
-};
+export const MetricList = React.forwardRef<HTMLDivElement, MetricListProps>(({ children, className }, ref) => {
+  return (
+    <div ref={ref} className={cn("flex flex-col gap-2 text-fg-subtle", className)}>
+      {children}
+    </div>
+  );
+});
+MetricList.displayName = "MetricList";

package/src/components/Modal/Modal.tsx

@@ -1,14 +1,14 @@
 import { FloatingFocusManager, FloatingOverlay, useDismiss, useFloating, useInteractions, useRole } from "@floating-ui/react";
 import { useMergedFloatingRef, usePresence } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
-import { type HTMLAttributes, type ReactNode, useCallback, useContext, useEffect, useMemo } from "react";
+import { forwardRef, type HTMLAttributes, type ReactNode, useCallback, useContext, useEffect, useId, useMemo, useState } from "react";
 import { ModalBody, ModalContext, ModalFooter, ModalHeader } from "./components";
 
 // =============================================================================
 // Types
 // =============================================================================
 
-export type ModalProps = Pick<HTMLAttributes<HTMLDivElement>, "className" | "style"> & {
+export type ModalProps = Pick<HTMLAttributes<HTMLDivElement>, "className" | "style" | "aria-label" | "aria-labelledby" | "aria-describedby"> & {
   /**
    * Called when the modal's open state should change. Today Modal is mount-driven
    * (parent conditionally renders), so this fires only with `false` on dismissal.
@@ -47,92 +47,124 @@ const sizeClasses = {
 // Modal
 // =============================================================================
 
-const ModalRoot = ({ onOpenChange, size = "md", className, style, children, dismissable = true, closable, align = "center" }: ModalProps) => {
-  // Prefer explicit prop over context (context is set by useModal's overlay system)
-  const contextValue = useContext(ModalContext);
-  // Context provides a parameterless onClose for programmatic modals; adapt to the boolean shape.
-  const handleDismiss = useCallback(() => {
-    if (onOpenChange) onOpenChange(false);
-    else contextValue?.onClose();
-  }, [onOpenChange, contextValue]);
-
-  const { ref: presenceRef, state, isMounted, show, hide } = usePresence();
-
-  useEffect(() => {
-    show();
-  }, [show]);
-
-  const handleClose = useCallback(() => {
-    hide(handleDismiss);
-  }, [handleDismiss, hide]);
-
-  const { refs, context } = useFloating({
-    open: true,
-    onOpenChange: (nextOpen) => {
-      if (!nextOpen) handleClose();
+const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
+  (
+    {
+      onOpenChange,
+      size = "md",
+      className,
+      style,
+      children,
+      dismissable = true,
+      closable,
+      align = "center",
+      "aria-label": ariaLabel,
+      "aria-labelledby": ariaLabelledBy,
+      "aria-describedby": ariaDescribedBy,
     },
-  });
-
-  const mergedRef = useMergedFloatingRef(refs, presenceRef);
-
-  const dismiss = useDismiss(context, {
-    enabled: dismissable,
-    // OverlayContext handles escape key for proper stack ordering
-    escapeKey: false,
-    outsidePress: true,
-    outsidePressEvent: "mousedown",
-  });
-
-  const role = useRole(context, {
-    role: "dialog",
-  });
-
-  const { getFloatingProps } = useInteractions([dismiss, role]);
-
-  const modalContextValue = useMemo(() => ({ onClose: handleClose, closable }), [closable, handleClose]); // eslint-disable-line react-hooks/exhaustive-deps
-
-  if (!isMounted) return null;
-
-  const isEntering = state === "entering";
-  const isExiting = state === "exiting";
-
-  return (
-    <FloatingFocusManager context={context} modal>
-      <FloatingOverlay lockScroll className={cn("fixed inset-0 z-modal bg-bg-overlay", isEntering && "animate-fade-in", isExiting && "animate-fade-out")}>
-        <div
-          ref={mergedRef}
-          role="dialog"
-          aria-modal="true"
-          tabIndex={-1}
-          data-state={state}
-          className={cn(
-            "fixed flex flex-col overflow-hidden outline-hidden",
-            "rounded-xl border border-border-normal bg-bg-normal",
-            // Size
-            sizeClasses[size],
-            // Cap height so ModalBody scrolls instead of overflowing the viewport
-            "max-h-[95%]",
-            // Mobile: slide up from bottom, full width
-            "max-sm:inset-x-0 max-sm:bottom-0 max-sm:rounded-b-none",
-            isEntering && "max-sm:animate-slide-up-in",
-            isExiting && "max-sm:animate-slide-up-out",
-            // Desktop: horizontal center + vertical alignment
-            "sm:left-1/2 sm:-translate-x-1/2",
-            align === "center" && "sm:top-1/2 sm:-translate-y-1/2",
-            align === "top" && "sm:top-[15vh]",
-            isEntering && "sm:animate-fade-in",
-            isExiting && "sm:animate-fade-out",
-            className
-          )}
-          style={style}
-          {...getFloatingProps({})}
-        >
-          <ModalContext.Provider value={modalContextValue}>{children}</ModalContext.Provider>
-        </div>
-      </FloatingOverlay>
-    </FloatingFocusManager>
-  );
-};
+    ref
+  ) => {
+    // Prefer explicit prop over context (context is set by useModal's overlay system)
+    const contextValue = useContext(ModalContext);
+    // Context provides a parameterless onClose for programmatic modals; adapt to the boolean shape.
+    const handleDismiss = useCallback(() => {
+      if (onOpenChange) onOpenChange(false);
+      else contextValue?.onClose();
+    }, [onOpenChange, contextValue]);
+
+    const { ref: presenceRef, state, isMounted, show, hide } = usePresence();
+
+    useEffect(() => {
+      show();
+    }, [show]);
+
+    const handleClose = useCallback(() => {
+      hide(handleDismiss);
+    }, [handleDismiss, hide]);
+
+    const { refs, context } = useFloating({
+      open: true,
+      onOpenChange: (nextOpen) => {
+        if (!nextOpen) handleClose();
+      },
+    });
+
+    const mergedRef = useMergedFloatingRef<HTMLDivElement>(refs, presenceRef, ref);
+
+    const dismiss = useDismiss(context, {
+      enabled: dismissable,
+      // OverlayContext handles escape key for proper stack ordering
+      escapeKey: false,
+      outsidePress: true,
+      outsidePressEvent: "mousedown",
+    });
+
+    const role = useRole(context, {
+      role: "dialog",
+    });
+
+    const { getFloatingProps } = useInteractions([dismiss, role]);
+
+    // The dialog names itself from its header. `Modal.Header` stamps `titleId`
+    // on itself and reports back, so a headerless modal falls through to the
+    // caller's `aria-label` instead of referencing an id that isn't there.
+    const titleId = useId();
+    const [hasTitle, setHasTitle] = useState(false);
+    const registerTitle = useCallback((present: boolean) => setHasTitle(present), []);
+
+    // `aria-labelledby` beats `aria-label` in the name computation, so a caller
+    // who passes a label must not also be pointed at the header — they would
+    // never see their own string win.
+    const labelledBy = ariaLabelledBy ?? (ariaLabel || !hasTitle ? undefined : titleId);
+
+    const modalContextValue = useMemo(() => ({ onClose: handleClose, closable, titleId, registerTitle }), [closable, handleClose, titleId, registerTitle]);
+
+    if (!isMounted) return null;
+
+    const isEntering = state === "entering";
+    const isExiting = state === "exiting";
+
+    return (
+      <FloatingFocusManager context={context} modal>
+        <FloatingOverlay lockScroll className={cn("fixed inset-0 z-modal bg-bg-overlay", isEntering && "animate-fade-in", isExiting && "animate-fade-out")}>
+          <div
+            ref={mergedRef}
+            role="dialog"
+            aria-modal="true"
+            aria-label={ariaLabel}
+            aria-labelledby={labelledBy}
+            aria-describedby={ariaDescribedBy}
+            tabIndex={-1}
+            data-state={state}
+            className={cn(
+              "fixed flex flex-col overflow-hidden outline-hidden",
+              "rounded-xl border border-border-normal bg-bg-normal",
+              // Size
+              sizeClasses[size],
+              // Cap height so ModalBody scrolls instead of overflowing the viewport
+              "max-h-[95%]",
+              // Mobile: slide up from bottom, full width
+              "max-sm:inset-x-0 max-sm:bottom-0 max-sm:rounded-b-none",
+              isEntering && "max-sm:animate-slide-up-in",
+              isExiting && "max-sm:animate-slide-up-out",
+              // Desktop: horizontal center + vertical alignment
+              "sm:left-1/2 sm:-translate-x-1/2",
+              align === "center" && "sm:top-1/2 sm:-translate-y-1/2",
+              align === "top" && "sm:top-[15vh]",
+              isEntering && "sm:animate-fade-in",
+              isExiting && "sm:animate-fade-out",
+              className
+            )}
+            style={style}
+            {...getFloatingProps({})}
+          >
+            <ModalContext.Provider value={modalContextValue}>{children}</ModalContext.Provider>
+          </div>
+        </FloatingOverlay>
+      </FloatingFocusManager>
+    );
+  }
+);
 ModalRoot.displayName = "Modal";
 
 // =============================================================================

package/src/components/Modal/components/ModalContext.tsx

@@ -9,6 +9,20 @@ export type OnClose = () => void;
 interface ModalContextValue {
   onClose: OnClose;
   closable?: boolean | undefined;
+  /**
+   * The id `Modal.Header` stamps on itself so the dialog can name itself from
+   * its own title. A dialog with no accessible name is announced as just
+   * "dialog", which tells a screen-reader user nothing about what interrupted
+   * them.
+   */
+  titleId?: string;
+  /**
+   * The header reports its presence, because a headerless modal must not point
+   * `aria-labelledby` at an element that never rendered — a dangling reference
+   * is worse than no reference at all (it resolves to an empty name and axe
+   * flags it as an invalid attribute value).
+   */
+  registerTitle?: (present: boolean) => void;
 }
 
 export const ModalContext = createContext<ModalContextValue | null>(null);