@sixthshift/design-system 0.1.0 → 0.3.0

package/src/components/Select/useSelectKeyboard.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useCallback } from "react";
 import type { SelectOption } from "./Select";
 
 interface UseSelectKeyboardOptions<T extends string> {
@@ -14,6 +14,20 @@ interface UseSelectKeyboardOptions<T extends string> {
   focusTrigger: () => void;
 }
 
+/**
+ * Returns the keydown handler for an open Select. It is attached to the element
+ * that actually holds focus — the listbox, or the search input in searchable
+ * mode — rather than to `document`.
+ *
+ * A document-level listener fired for every keystroke on the page while any
+ * Select was open, which meant a Select could swallow Escape or an arrow key
+ * from an overlay stacked above it, and two open Selects raced each other. It
+ * also decoupled key handling from focus, so nothing guaranteed the element the
+ * user was typing into was the one being navigated. Scoping the handler to the
+ * focused element makes both problems structurally impossible and is what lets
+ * `aria-activedescendant` mean something: the focused element owns the active
+ * option.
+ */
 export function useSelectKeyboard<T extends string>({
   open,
   searchable,
@@ -26,8 +40,8 @@ export function useSelectKeyboard<T extends string>({
   handleSelect,
   focusTrigger,
 }: UseSelectKeyboardOptions<T>) {
-  useEffect(() => {
-    const handleKeyDown = (event: KeyboardEvent) => {
+  return useCallback(
+    (event: React.KeyboardEvent<HTMLElement>) => {
       if (!open) return;
 
       const isTyping = searchable && event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;
@@ -101,11 +115,7 @@ export function useSelectKeyboard<T extends string>({
             }
           }
       }
-    };
-
-    if (open) {
-      document.addEventListener("keydown", handleKeyDown);
-      return () => document.removeEventListener("keydown", handleKeyDown);
-    }
-  }, [open, searchable, searchValue, highlightedIndex, displayOptions, setOpen, setHighlightedIndex, setSearchValue, handleSelect, focusTrigger]);
+    },
+    [open, searchable, searchValue, highlightedIndex, displayOptions, setOpen, setHighlightedIndex, setSearchValue, handleSelect, focusTrigger]
+  );
 }

package/src/components/Sheet/Sheet.tsx

@@ -1,14 +1,14 @@
 import { FloatingFocusManager, 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, useEffect, useMemo } from "react";
+import { forwardRef, type HTMLAttributes, type ReactNode, useCallback, useEffect, useId, useMemo, useState } from "react";
 import { SheetBody, SheetContext, SheetFooter, SheetHeader } from "./components";
 
 // =============================================================================
 // Types
 // =============================================================================
 
-export type SheetProps = Pick<HTMLAttributes<HTMLDivElement>, "className" | "style"> & {
+export type SheetProps = Pick<HTMLAttributes<HTMLDivElement>, "className" | "style" | "aria-label" | "aria-labelledby" | "aria-describedby"> & {
   /** Whether the sheet is open. Sheet owns its own mount lifecycle so exit animations can play. */
   open: boolean;
   /** Called when the sheet requests a state change (Esc, outside press, X button). */
@@ -41,88 +41,113 @@ const sizeClasses = {
 // Sheet
 // =============================================================================
 
-const SheetRoot = ({
-  open,
-  onOpenChange,
-  side = "right",
-  size = "md",
-  dismissable = true,
-  dismissOnOutsidePress = false,
-  closable,
-  className,
-  style,
-  children,
-}: SheetProps) => {
-  const { ref: presenceRef, state, isMounted, show, hide } = usePresence();
-
-  // Drive presence from the controlled `open` prop.
-  // When `open` flips to false, we play the exit animation, then unmount.
-  useEffect(() => {
-    if (open) {
-      show();
-    } else if (isMounted) {
-      hide();
-    }
-  }, [open, isMounted, show, hide]);
-
-  const requestClose = useCallback(() => {
-    onOpenChange(false);
-  }, [onOpenChange]);
-
-  const { refs, context } = useFloating({
-    open,
-    onOpenChange: (nextOpen) => {
-      if (!nextOpen) requestClose();
+const SheetRoot = forwardRef<HTMLDivElement, SheetProps>(
+  (
+    {
+      open,
+      onOpenChange,
+      side = "right",
+      size = "md",
+      dismissable = true,
+      dismissOnOutsidePress = false,
+      closable,
+      className,
+      style,
+      children,
+      "aria-label": ariaLabel,
+      "aria-labelledby": ariaLabelledBy,
+      "aria-describedby": ariaDescribedBy,
     },
-  });
-
-  const mergedRef = useMergedFloatingRef(refs, presenceRef);
-
-  const dismiss = useDismiss(context, {
-    enabled: dismissable,
-    escapeKey: true,
-    outsidePress: dismissOnOutsidePress,
-    outsidePressEvent: "mousedown",
-  });
-
-  const role = useRole(context, { role: "dialog" });
-
-  const { getFloatingProps } = useInteractions([dismiss, role]);
-
-  const sheetContextValue = useMemo(() => ({ onClose: requestClose, closable }), [requestClose, closable]);
-
-  if (!isMounted) return null;
-
-  const isEntering = state === "entering";
-  const isExiting = state === "exiting";
-
-  return (
-    <FloatingFocusManager context={context} modal={false}>
-      <div
-        ref={mergedRef}
-        tabIndex={-1}
-        data-state={state}
-        data-side={side}
-        className={cn(
-          "fixed top-0 bottom-0 z-sheet flex flex-col overflow-hidden bg-bg-normal outline-hidden",
-          "border-border-normal shadow-lg",
-          side === "right" ? "right-0 border-l" : "left-0 border-r",
-          sizeClasses[size],
-          "max-sm:inset-x-0",
-          isEntering && side === "right" && "animate-slide-right-in",
-          isExiting && side === "right" && "animate-slide-right-out",
-          isEntering && side === "left" && "animate-slide-left-in",
-          isExiting && side === "left" && "animate-slide-left-out",
-          className
-        )}
-        style={style}
-        {...getFloatingProps({})}
-      >
-        <SheetContext.Provider value={sheetContextValue}>{children}</SheetContext.Provider>
-      </div>
-    </FloatingFocusManager>
-  );
-};
+    ref
+  ) => {
+    const { ref: presenceRef, state, isMounted, show, hide } = usePresence();
+
+    // Drive presence from the controlled `open` prop.
+    // When `open` flips to false, we play the exit animation, then unmount.
+    useEffect(() => {
+      if (open) {
+        show();
+      } else if (isMounted) {
+        hide();
+      }
+    }, [open, isMounted, show, hide]);
+
+    const requestClose = useCallback(() => {
+      onOpenChange(false);
+    }, [onOpenChange]);
+
+    const { refs, context } = useFloating({
+      open,
+      onOpenChange: (nextOpen) => {
+        if (!nextOpen) requestClose();
+      },
+    });
+
+    const mergedRef = useMergedFloatingRef<HTMLDivElement>(refs, presenceRef, ref);
+
+    const dismiss = useDismiss(context, {
+      enabled: dismissable,
+      escapeKey: true,
+      outsidePress: dismissOnOutsidePress,
+      outsidePressEvent: "mousedown",
+    });
+
+    const role = useRole(context, { role: "dialog" });
+
+    const { getFloatingProps } = useInteractions([dismiss, role]);
+
+    // Named from its header, same contract as Modal — see SheetContext.
+    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 sheetContextValue = useMemo(() => ({ onClose: requestClose, closable, titleId, registerTitle }), [requestClose, closable, titleId, registerTitle]);
+
+    if (!isMounted) return null;
+
+    const isEntering = state === "entering";
+    const isExiting = state === "exiting";
+
+    return (
+      <FloatingFocusManager context={context} modal={false}>
+        <div
+          ref={mergedRef}
+          // Explicit, though `getFloatingProps` also supplies it from `useRole`:
+          // the ARIA attributes below are only valid on a dialog, and static
+          // analysis cannot see a role that arrives through a spread. Matches Modal.
+          role="dialog"
+          aria-label={ariaLabel}
+          aria-labelledby={labelledBy}
+          aria-describedby={ariaDescribedBy}
+          tabIndex={-1}
+          data-state={state}
+          data-side={side}
+          className={cn(
+            "fixed top-0 bottom-0 z-sheet flex flex-col overflow-hidden bg-bg-normal outline-hidden",
+            "border-border-normal shadow-lg",
+            side === "right" ? "right-0 border-l" : "left-0 border-r",
+            sizeClasses[size],
+            "max-sm:inset-x-0",
+            isEntering && side === "right" && "animate-slide-right-in",
+            isExiting && side === "right" && "animate-slide-right-out",
+            isEntering && side === "left" && "animate-slide-left-in",
+            isExiting && side === "left" && "animate-slide-left-out",
+            className
+          )}
+          style={style}
+          {...getFloatingProps({})}
+        >
+          <SheetContext.Provider value={sheetContextValue}>{children}</SheetContext.Provider>
+        </div>
+      </FloatingFocusManager>
+    );
+  }
+);
 SheetRoot.displayName = "Sheet";
 
 // =============================================================================

package/src/components/Sheet/components/SheetContext.tsx

@@ -5,6 +5,16 @@ export type OnClose = (event?: MouseEvent<Element> | KeyboardEvent<Element>) =>
 interface SheetContextValue {
   onClose: OnClose;
   closable?: boolean | undefined;
+  /**
+   * The id `Sheet.Header` stamps on itself so the dialog can name itself from
+   * its own title instead of being announced as a bare "dialog".
+   */
+  titleId?: string;
+  /**
+   * The header reports its presence — a headerless sheet must not point
+   * `aria-labelledby` at an element that never rendered.
+   */
+  registerTitle?: (present: boolean) => void;
 }
 
 export const SheetContext = createContext<SheetContextValue | null>(null);

package/src/components/Sheet/components/SheetHeader.tsx

@@ -5,13 +5,28 @@ import { SheetContext } from "./SheetContext";
 
 export type SheetHeaderProps = React.HTMLAttributes<HTMLDivElement>;
 
-export const SheetHeader = React.forwardRef<HTMLDivElement, SheetHeaderProps>(({ className, children, ...props }, ref) => {
+export const SheetHeader = React.forwardRef<HTMLDivElement, SheetHeaderProps>(({ className, children, id, ...props }, ref) => {
   const context = React.useContext(SheetContext);
   const closable = context?.closable;
   const onClose = context?.onClose;
+  const registerTitle = context?.registerTitle;
+
+  // Report the title to the sheet so it can name itself, and withdraw it on
+  // unmount. A caller-supplied `id` wins over the generated one — which the
+  // sheet can no longer resolve, so it is told there is no title to point at.
+  const ownsTitleId = id === undefined;
+  React.useEffect(() => {
+    registerTitle?.(ownsTitleId);
+    return () => registerTitle?.(false);
+  }, [registerTitle, ownsTitleId]);
 
   return (
-    <div ref={ref} className={cn("flex flex-col space-y-1.5 border-border-normal border-b p-6", closable && "pr-12", className)} {...props}>
+    <div
+      ref={ref}
+      id={id ?? context?.titleId}
+      className={cn("flex flex-col space-y-1.5 border-border-normal border-b p-6", closable && "pr-12", className)}
+      {...props}
+    >
       {children}
       {closable && (
         <button

package/src/components/Skeleton/Skeleton.tsx

@@ -1,7 +1,9 @@
 import { cn } from "@sixthshift/design-system/utils";
+import * as React from "react";
 
-const Skeleton = ({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) => {
-  return <div className={cn("animate-pulse rounded-md bg-bg-strong/10", className)} {...props} />;
-};
+const Skeleton = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(({ className, ...props }, ref) => {
+  return <div ref={ref} className={cn("animate-pulse rounded-md bg-bg-strong/10", className)} {...props} />;
+});
+Skeleton.displayName = "Skeleton";
 
 export { Skeleton };

package/src/components/Sparkline/Sparkline.tsx

@@ -1,6 +1,6 @@
 import type { Interpolation } from "@sixthshift/design-system/line-chart";
 import { cn } from "@sixthshift/design-system/utils";
-import type * as React from "react";
+import * as React from "react";
 
 export type SparklineProps = React.HTMLAttributes<HTMLSpanElement> & {
   data: number[];
@@ -51,43 +51,36 @@ function buildPath(points: { x: number; y: number }[], interpolation: Interpolat
   return parts.join(" ");
 }
 
-export const Sparkline = ({
-  data,
-  width = 80,
-  height = 24,
-  color = "var(--fg-brand)",
-  fillArea = false,
-  interpolation = "monotone",
-  strokeWidth = 1.5,
-  className,
-  ...rest
-}: SparklineProps) => {
-  if (data.length < 2) return null;
+export const Sparkline = React.forwardRef<HTMLSpanElement, SparklineProps>(
+  ({ data, width = 80, height = 24, color = "var(--fg-brand)", fillArea = false, interpolation = "monotone", strokeWidth = 1.5, className, ...rest }, ref) => {
+    if (data.length < 2) return null;
 
-  const min = Math.min(...data);
-  const max = Math.max(...data);
-  const range = max - min || 1;
+    const min = Math.min(...data);
+    const max = Math.max(...data);
+    const range = max - min || 1;
 
-  const padY = 2;
-  const padX = 1;
-  const innerW = width - padX * 2;
-  const innerH = height - padY * 2;
+    const padY = 2;
+    const padX = 1;
+    const innerW = width - padX * 2;
+    const innerH = height - padY * 2;
 
-  const points = data.map((v, i) => ({
-    x: padX + (i / (data.length - 1)) * innerW,
-    y: padY + innerH - ((v - min) / range) * innerH,
-  }));
+    const points = data.map((v, i) => ({
+      x: padX + (i / (data.length - 1)) * innerW,
+      y: padY + innerH - ((v - min) / range) * innerH,
+    }));
 
-  const path = buildPath(points, interpolation);
+    const path = buildPath(points, interpolation);
 
-  return (
-    <span {...rest} className={cn("inline-block align-middle", className)}>
-      <svg width={width} height={height} viewBox={`0 0 ${width} ${height}`} role="img" aria-label="Trend line">
-        {fillArea && path && (
-          <path d={`${path} L ${points[points.length - 1]!.x} ${height - padY} L ${points[0]!.x} ${height - padY} Z`} fill={color} opacity={0.12} />
-        )}
-        <path d={path} fill="none" stroke={color} strokeWidth={strokeWidth} strokeLinecap="round" strokeLinejoin="round" />
-      </svg>
-    </span>
-  );
-};
+    return (
+      <span ref={ref} {...rest} className={cn("inline-block align-middle", className)}>
+        <svg width={width} height={height} viewBox={`0 0 ${width} ${height}`} role="img" aria-label="Trend line">
+          {fillArea && path && (
+            <path d={`${path} L ${points[points.length - 1]!.x} ${height - padY} L ${points[0]!.x} ${height - padY} Z`} fill={color} opacity={0.12} />
+          )}
+          <path d={path} fill="none" stroke={color} strokeWidth={strokeWidth} strokeLinecap="round" strokeLinejoin="round" />
+        </svg>
+      </span>
+    );
+  }
+);
+Sparkline.displayName = "Sparkline";

package/src/components/StatsCard/StatsCard.tsx

@@ -1,6 +1,6 @@
 import { Caption } from "@sixthshift/design-system/caption";
 import { cn } from "@sixthshift/design-system/utils";
-import type { ReactNode } from "react";
+import * as React from "react";
 
 export type StatsCardProps = {
   /** Title of the stats card */
@@ -8,11 +8,11 @@ export type StatsCardProps = {
   /** Description text shown below the title */
   description: string;
   /** Optional icon displayed in the header */
-  icon?: ReactNode;
+  icon?: React.ReactNode;
   /** Visual status indicator via left border color */
   status?: "healthy" | "warning" | "error" | "neutral";
   /** Card content */
-  children: ReactNode;
+  children: React.ReactNode;
   /** Additional CSS classes */
   className?: string;
 };
@@ -24,9 +24,9 @@ const statusColors = {
   neutral: "border-l-border-subtle",
 };
 
-export const StatsCard = ({ title, description, icon, status = "neutral", children, className }: StatsCardProps) => {
+export const StatsCard = React.forwardRef<HTMLDivElement, StatsCardProps>(({ title, description, icon, status = "neutral", children, className }, ref) => {
   return (
-    <div className={cn("flex flex-col gap-3 rounded border border-border-subtle border-l-2 bg-bg-subtle p-4", statusColors[status], className)}>
+    <div ref={ref} className={cn("flex flex-col gap-3 rounded border border-border-subtle border-l-2 bg-bg-subtle p-4", statusColors[status], className)}>
       <div className="flex items-start justify-between gap-2">
         <div className="flex flex-col gap-0.5">
           <span className="font-medium text-fg-normal">{title}</span>
@@ -37,4 +37,5 @@ export const StatsCard = ({ title, description, icon, status = "neutral", childr
       <div className="flex-1">{children}</div>
     </div>
   );
-};
+});
+StatsCard.displayName = "StatsCard";

package/src/components/Tabs/components/TabsList.tsx

@@ -1,6 +1,6 @@
 import { cn } from "@sixthshift/design-system/utils";
 import type * as React from "react";
-import { useCallback, useRef } from "react";
+import { forwardRef, useCallback, useRef } from "react";
 import { useTabsContext } from "./TabsContext";
 import { TabsTrigger } from "./TabsTrigger";
 
@@ -11,7 +11,7 @@ export type TabsListProps = {
   className?: string;
 };
 
-export const TabsList = ({ orientation = "horizontal", className }: TabsListProps) => {
+export const TabsList = forwardRef<HTMLDivElement, TabsListProps>(({ orientation = "horizontal", className }, ref) => {
   const { items, value, onValueChange } = useTabsContext();
   const triggerRefs = useRef<(HTMLButtonElement | null)[]>([]);
 
@@ -78,6 +78,7 @@ export const TabsList = ({ orientation = "horizontal", className }: TabsListProp
 
   return (
     <div
+      ref={ref}
       role="tablist"
       aria-orientation={orientation}
       className={cn("inline-flex gap-1", orientation === "vertical" ? "flex-col" : "flex-row items-center", className)}
@@ -95,4 +96,5 @@ export const TabsList = ({ orientation = "horizontal", className }: TabsListProp
       ))}
     </div>
   );
-};
+});
+TabsList.displayName = "TabsList";

package/src/components/Tabs/components/TabsPanels.tsx

@@ -1,4 +1,5 @@
 import { cn } from "@sixthshift/design-system/utils";
+import { forwardRef } from "react";
 import { useTabsContext } from "./TabsContext";
 
 export type TabsPanelsProps = {
@@ -6,7 +7,7 @@ export type TabsPanelsProps = {
   className?: string;
 };
 
-export const TabsPanels = ({ className }: TabsPanelsProps) => {
+export const TabsPanels = forwardRef<HTMLDivElement, TabsPanelsProps>(({ className }, ref) => {
   const { items, value, baseId } = useTabsContext();
 
   const activeItem = items.find((item) => item.value === value);
@@ -19,8 +20,9 @@ export const TabsPanels = ({ className }: TabsPanelsProps) => {
   const content = typeof activeItem.content === "function" ? activeItem.content() : activeItem.content;
 
   return (
-    <div id={panelId} role="tabpanel" aria-labelledby={triggerId} className={cn("focus-visible:outline-hidden", className)}>
+    <div ref={ref} id={panelId} role="tabpanel" aria-labelledby={triggerId} className={cn("focus-visible:outline-hidden", className)}>
       {content}
     </div>
   );
-};
+});
+TabsPanels.displayName = "TabsPanels";

package/src/components/TagChip/TagChip.tsx

@@ -1,6 +1,7 @@
 import { Badge } from "@sixthshift/design-system/badge";
 import { cn } from "@sixthshift/design-system/utils";
 import { X } from "lucide-react";
+import * as React from "react";
 
 /**
  * One tag, rendered prettily. A `namespace:value` tag (`project:website`)
@@ -22,13 +23,18 @@ export type TagChipProps = {
   className?: string;
 };
 
-export const TagChip = ({ tag, onRemove, size = "sm", className }: TagChipProps) => {
+export const TagChip = React.forwardRef<HTMLSpanElement, TagChipProps>(({ tag, onRemove, size = "sm", className }, ref) => {
   const sep = tag.indexOf(":");
   const namespace = sep > 0 ? tag.slice(0, sep) : null;
   const value = sep > 0 ? tag.slice(sep + 1) : tag;
 
   return (
-    <Badge variant="outline" intent="muted" className={cn("gap-1 font-normal", size === "sm" ? "px-1.5 py-0 text-[10px]" : "px-2 py-0.5 text-xs", className)}>
+    <Badge
+      ref={ref}
+      variant="outline"
+      intent="muted"
+      className={cn("gap-1 font-normal", size === "sm" ? "px-1.5 py-0 text-[10px]" : "px-2 py-0.5 text-xs", className)}
+    >
       {namespace && <span className="text-fg-subtle">{namespace}:</span>}
       <span>{value}</span>
       {onRemove && (
@@ -43,4 +49,5 @@ export const TagChip = ({ tag, onRemove, size = "sm", className }: TagChipProps)
       )}
     </Badge>
   );
-};
+});
+TagChip.displayName = "TagChip";

package/src/components/TagInput/TagInput.tsx

@@ -1,6 +1,6 @@
 import { TagChip } from "@sixthshift/design-system/tag-chip";
 import { cn } from "@sixthshift/design-system/utils";
-import { type KeyboardEvent, useState } from "react";
+import { forwardRef, type KeyboardEvent, useState } from "react";
 
 /**
  * Token input for tags: existing tags render as removable chips, typing plus
@@ -18,7 +18,7 @@ export type TagInputProps = {
   className?: string;
 };
 
-export const TagInput = ({ value, onChange, placeholder = "Add a tag…", id, className }: TagInputProps) => {
+export const TagInput = forwardRef<HTMLDivElement, TagInputProps>(({ value, onChange, placeholder = "Add a tag…", id, className }, ref) => {
   const [draft, setDraft] = useState("");
 
   const commit = () => {
@@ -38,6 +38,7 @@ export const TagInput = ({ value, onChange, placeholder = "Add a tag…", id, cl
 
   return (
     <div
+      ref={ref}
       className={cn(
         "flex min-h-9 flex-wrap items-center gap-1.5 rounded-md border border-border-normal bg-bg-normal px-2 py-1.5 text-sm shadow-xs transition-colors focus-within:ring-2 focus-within:ring-focus-ring",
         className
@@ -57,4 +58,5 @@ export const TagInput = ({ value, onChange, placeholder = "Add a tag…", id, cl
       />
     </div>
   );
-};
+});
+TagInput.displayName = "TagInput";