@astryxdesign/core 0.7.5 → 0.7.6-canary.00146a7

package/src/Timestamp/Timestamp.tsx

@@ -443,7 +443,10 @@ export function Timestamp({
         // before rendering — but keep the guard local: an empty aria-label
         // must be omitted entirely (not rendered as aria-label="") so AT
         // falls back to reading the visible <time> content.
-        {...(isRelativeFormat(effectiveFormat) && ariaLabelText !== ''
+        // A caller's own name wins (`component:Timestamp` FR5).
+        {...(isRelativeFormat(effectiveFormat) &&
+        ariaLabelText !== '' &&
+        rest['aria-label'] == null
           ? {'aria-label': ariaLabelText}
           : {})}
         // The hover card is anchored here with focusTrigger="always", which
@@ -454,7 +457,8 @@ export function Timestamp({
         // gratuitous tab stops otherwise. The card carries its own
         // dashed-underline hover indication as the affordance, so the anchor
         // needs no separate focus outline.
-        {...(showTooltip ? {tabIndex: 0} : {})}>
+        // A caller's own tabIndex wins (`component:Timestamp` FR9).
+        {...(showTooltip && rest.tabIndex == null ? {tabIndex: 0} : {})}>
         {displayText}
       </time>
     </Text>

package/src/Timestamp/TimestampHoverCard.tsx

@@ -26,11 +26,11 @@
 import type {ReactNode} from 'react';
 import {useCallback} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {HoverCard} from '../HoverCard';
-import {IconButton} from '../IconButton';
-import {Icon} from '../Icon';
+import {HoverCard} from '../HoverCard/HoverCard';
+import {IconButton} from '../IconButton/IconButton';
+import {Icon} from '../Icon/Icon';
 import {useClipboard} from '../hooks/useClipboard';
-import {useTranslator} from '../i18n';
+import {useTranslator} from '../i18n/useTranslator';
 import {themeProps} from '../utils/themeProps';
 import {
   colorVars,

package/src/Toast/Toast.tsx

@@ -18,7 +18,7 @@
  */
 
 import {useCallback, useEffect, useRef} from 'react';
-import type {ReactNode} from 'react';
+import type {FocusEvent, ReactNode, RefObject} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Button} from '../Button';
 import {Icon} from '../Icon';
@@ -172,6 +172,9 @@ export function Toast(props: ToastProps) {
   return <ToastSurface {...props} gestureDirection={1} />;
 }
 
+/** A condition that holds a toast's auto-hide timer. */
+type PauseSource = 'pointer' | 'focus' | 'gesture' | 'window';
+
 export function ToastSurface({
   type,
   body,
@@ -185,7 +188,13 @@ export function ToastSurface({
 }: ToastSurfaceProps) {
   const t = useTranslator();
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const isPausedRef = useRef(false);
+  // Every condition that holds the auto-hide timer (pointer over the card,
+  // focus inside it, a touch or pen gesture, the window blurred) is tracked on
+  // its own, so one ending resumes the timer only when no other still holds.
+  const pauseSourcesRef = useRef<Set<PauseSource>>(new Set());
+  // The card's root, read when a hold ends to drop a focus hold whose focused
+  // control was removed: an unmounting control fires no blur.
+  const cardRootRef = useRef<RefObject<HTMLDivElement | null> | null>(null);
   const remainingRef = useRef(autoHideDuration);
   // Will be initialized by startTimer when actually used
   const startTimeRef = useRef<number | null>(null);
@@ -197,7 +206,7 @@ export function ToastSurface({
   onDismissRef.current = onDismiss;
 
   const startTimer = useCallback(() => {
-    if (!isAutoHide || isPausedRef.current) {
+    if (!isAutoHide || pauseSourcesRef.current.size > 0) {
       return;
     }
     if (timerRef.current) {
@@ -209,28 +218,53 @@ export function ToastSurface({
     }, remainingRef.current);
   }, [isAutoHide]);
 
-  const pauseTimer = useCallback(() => {
-    if (!isAutoHide || isPausedRef.current) {
-      return;
-    }
-    isPausedRef.current = true;
-    if (timerRef.current) {
-      clearTimeout(timerRef.current);
-      timerRef.current = null;
-    }
-    if (startTimeRef.current != null) {
-      const elapsed = Date.now() - startTimeRef.current;
-      remainingRef.current = Math.max(remainingRef.current - elapsed, 1000);
-    }
-  }, [isAutoHide]);
+  const pauseTimer = useCallback(
+    (source: PauseSource) => {
+      if (!isAutoHide) {
+        return;
+      }
+      const sources = pauseSourcesRef.current;
+      const wasRunning = sources.size === 0;
+      sources.add(source);
+      if (!wasRunning) {
+        return;
+      }
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+      if (startTimeRef.current != null) {
+        const elapsed = Date.now() - startTimeRef.current;
+        remainingRef.current = Math.max(remainingRef.current - elapsed, 1000);
+      }
+    },
+    [isAutoHide],
+  );
 
-  const resumeTimer = useCallback(() => {
-    if (!isAutoHide || !isPausedRef.current) {
-      return;
-    }
-    isPausedRef.current = false;
-    startTimer();
-  }, [isAutoHide, startTimer]);
+  const resumeTimer = useCallback(
+    (source: PauseSource) => {
+      if (!isAutoHide) {
+        return;
+      }
+      const sources = pauseSourcesRef.current;
+      if (!sources.delete(source)) {
+        return;
+      }
+      const root = cardRootRef.current?.current;
+      if (
+        sources.has('focus') &&
+        root != null &&
+        !root.contains(document.activeElement)
+      ) {
+        sources.delete('focus');
+      }
+      if (sources.size > 0) {
+        return;
+      }
+      startTimer();
+    },
+    [isAutoHide, startTimer],
+  );
 
   useEffect(() => {
     remainingRef.current = autoHideDuration;
@@ -250,15 +284,48 @@ export function ToastSurface({
     if (!isAutoHide) {
       return;
     }
-    window.addEventListener('blur', pauseTimer);
-    window.addEventListener('focus', resumeTimer);
+    const pauseForWindow = () => pauseTimer('window');
+    const resumeForWindow = () => resumeTimer('window');
+    window.addEventListener('blur', pauseForWindow);
+    window.addEventListener('focus', resumeForWindow);
     return () => {
-      window.removeEventListener('blur', pauseTimer);
-      window.removeEventListener('focus', resumeTimer);
+      window.removeEventListener('blur', pauseForWindow);
+      window.removeEventListener('focus', resumeForWindow);
     };
   }, [isAutoHide, pauseTimer, resumeTimer]);
 
-  const isTimerPaused = useCallback(() => isPausedRef.current, []);
+  const isGesturePausing = useCallback(
+    () => pauseSourcesRef.current.has('gesture'),
+    [],
+  );
+  const pauseForGesture = useCallback(
+    () => pauseTimer('gesture'),
+    [pauseTimer],
+  );
+  const resumeForGesture = useCallback(
+    () => resumeTimer('gesture'),
+    [resumeTimer],
+  );
+  const pauseForPointer = useCallback(
+    () => pauseTimer('pointer'),
+    [pauseTimer],
+  );
+  const resumeForPointer = useCallback(
+    () => resumeTimer('pointer'),
+    [resumeTimer],
+  );
+  const pauseForFocus = useCallback(() => pauseTimer('focus'), [pauseTimer]);
+  const resumeForFocus = useCallback(
+    (event: FocusEvent<HTMLDivElement>) => {
+      // Focus moving between controls inside the card keeps it held.
+      const next = event.relatedTarget;
+      if (next instanceof Node && event.currentTarget.contains(next)) {
+        return;
+      }
+      resumeTimer('focus');
+    },
+    [resumeTimer],
+  );
   const dismissFromGesture = useCallback(() => {
     onDismissRef.current('manual');
   }, []);
@@ -266,12 +333,13 @@ export function ToastSurface({
     direction: gestureDirection,
     enabled: !isExiting,
     canPauseTimer: isAutoHide,
-    isTimerPaused,
-    pauseTimer,
-    resumeTimer,
+    isTimerPaused: isGesturePausing,
+    pauseTimer: pauseForGesture,
+    resumeTimer: resumeForGesture,
     dismiss: dismissFromGesture,
     shouldIgnoreTarget: isInteractiveTarget,
   });
+  cardRootRef.current = rootRef;
 
   const handleDismiss = useCallback(() => {
     onDismiss('manual');
@@ -290,10 +358,10 @@ export function ToastSurface({
       role={isError ? 'alert' : 'status'}
       aria-live={isError ? 'assertive' : 'polite'}
       aria-atomic="true"
-      onMouseEnter={pauseTimer}
-      onMouseLeave={resumeTimer}
-      onFocusCapture={pauseTimer}
-      onBlurCapture={resumeTimer}
+      onMouseEnter={pauseForPointer}
+      onMouseLeave={resumeForPointer}
+      onFocusCapture={pauseForFocus}
+      onBlurCapture={resumeForFocus}
       {...gestureBindings}
       {...mergeProps(
         themeProps('toast', {type}),

package/src/Toast/ToastViewport.tsx

@@ -15,7 +15,6 @@
  */
 
 import {
-  isValidElement,
   useCallback,
   useEffect,
   useLayoutEffect,
@@ -28,6 +27,7 @@ import {createPortal} from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {getNodeText} from '../utils/getNodeText';
 import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {layerTextReset} from '../Layer/layerTextReset.stylex';
@@ -172,29 +172,6 @@ const styles = stylex.create({
   },
 });
 
-// Flatten a toast's rendered content (title, description, etc.) to the plain
-// text that should be spoken by a screen reader. Only text is announced —
-// interactive endContent is deliberately excluded (it is reachable via F6).
-function getNodeText(node: ReactNode): string {
-  if (node == null || typeof node === 'boolean') {
-    return '';
-  }
-  if (typeof node === 'string') {
-    return node;
-  }
-  if (typeof node === 'number') {
-    return String(node);
-  }
-  if (Array.isArray(node)) {
-    return node.map(getNodeText).filter(Boolean).join(' ');
-  }
-  if (isValidElement(node)) {
-    const {children} = node.props as {children?: ReactNode};
-    return getNodeText(children);
-  }
-  return '';
-}
-
 export interface ToastViewportProps {
   position?: ToastPosition;
   /** Maximum number of visible toasts. @default 5 */
@@ -344,6 +321,19 @@ export function ToastViewport({
   const [exitingIds, setExitingIds] = useState<Set<string>>(new Set());
   const toastsRef = useRef(toasts);
   toastsRef.current = toasts;
+  // The list as last rendered: addToast moves toastsRef ahead of it within
+  // a batch, so this tells a rendered toast from one raised since.
+  const renderedToastsRef = useRef(toasts);
+  renderedToastsRef.current = toasts;
+  // Read by removeToast, which keeps one identity across renders.
+  const maxVisibleRef = useRef(maxVisible);
+  maxVisibleRef.current = maxVisible;
+  // Rendered entries a repeat has replaced in this batch: still found by a
+  // dismissal in the same handler, as before the swap. One replaced before it
+  // rendered was never shown and reports no onHide (Toast.spec.md FR3). A
+  // render starts a new batch.
+  const replacedRef = useRef<Map<string, ToastEntry>>(new Map());
+  replacedRef.current.clear();
 
   const viewportRef = useRef<HTMLDivElement>(null);
   // Toast ids whose exit has begun — guards onHide from double-firing (see
@@ -352,10 +342,13 @@ export function ToastViewport({
   // Toasts dispatched since the last commit, by id: a dismiss() called
   // before the toast first renders still finds it (and its onHide).
   const pendingEntriesRef = useRef<Map<string, ToastEntry>>(new Map());
-  // The element that was focused before the user jumped into the viewport
-  // (via F6). Used to restore focus once all toasts are dismissed so focus
-  // never falls to <body>.
+  // The element that was focused before focus entered the viewport, by F6,
+  // Tab or a click. Used to restore focus once all toasts are dismissed so
+  // focus never falls to <body> (FR10).
   const prevFocusRef = useRef<HTMLElement | null>(null);
+  // The element focus last reached inside the viewport's React tree,
+  // portaled toast content included.
+  const lastFocusedWithinRef = useRef<EventTarget | null>(null);
   // When a toast is dismissed while focus lives inside it, we need to move
   // focus to a sensible neighbor after that toast unmounts. This holds the
   // id of the toast whose removal should trigger a focus handoff.
@@ -410,6 +403,10 @@ export function ToastViewport({
   const addToast = useCallback(
     (entry: ToastEntry) => {
       const {uniqueID, collisionBehavior = 'overwrite'} = entry.options;
+      // A toast holds its uniqueID until it unmounts, leaving included
+      // (Toast.spec.md FR8): an overwrite replaces it in place, and an ignored
+      // namesake is dropped.
+      const holdsUniqueID = (t: ToastEntry) => t.options.uniqueID === uniqueID;
       // Resolve an ignored collision synchronously against the committed list
       // so a suppressed toast is neither shown nor announced. The remaining
       // announce + setToasts run outside the setToasts updater, which React may
@@ -417,16 +414,46 @@ export function ToastViewport({
       if (
         uniqueID &&
         collisionBehavior === 'ignore' &&
-        toastsRef.current.some(t => t.options.uniqueID === uniqueID)
+        toastsRef.current.some(holdsUniqueID)
       ) {
         return;
       }
+      // Only text is announced; interactive endContent is reachable via F6.
       const text = getNodeText(entry.options.body);
       if (text) {
         // Error toasts map to the assertive region (role="alert"); everything
         // else to the polite region (role="status") — mirrors Toast.tsx.
         announce(text, entry.options.type === 'error' ? 'assertive' : 'polite');
       }
+      // A leaving toast that a new one pushes out of the visible window can no
+      // longer finish its exit on screen, so it leaves the list now (it
+      // already reported onHide); otherwise its row would come back collapsed
+      // when the window reached it again, holding a slot and the landmark.
+      const committed = toastsRef.current;
+      const overwritten = uniqueID ? committed.find(holdsUniqueID) : undefined;
+      if (overwritten && renderedToastsRef.current.includes(overwritten)) {
+        replacedRef.current.set(overwritten.id, overwritten);
+      }
+      const projected = overwritten
+        ? committed.map(t => (t === overwritten ? entry : t))
+        : [...committed, entry];
+      // `maxVisible={0}` shows every toast (FR7): nothing leaves the window.
+      const firstVisible = maxVisible > 0 ? projected.length - maxVisible : 0;
+      const cutIds = new Set(
+        projected
+          .filter((t, i) => i < firstVisible && exitingIdsRef.current.has(t.id))
+          .map(t => t.id),
+      );
+      if (cutIds.size > 0) {
+        // Gone from every list, so a later dismissal reports nothing more.
+        for (const id of cutIds) {
+          exitingIdsRef.current.delete(id);
+          pendingEntriesRef.current.delete(id);
+        }
+        setExitingIds(prev => new Set([...prev].filter(id => !cutIds.has(id))));
+      }
+      // Later toasts in the same batch see this one before the next render.
+      toastsRef.current = projected.filter(t => !cutIds.has(t.id));
       const pending = pendingEntriesRef.current;
       if (uniqueID) {
         // An overwrite replaces a toast that has not rendered yet too.
@@ -442,17 +469,17 @@ export function ToastViewport({
       // dismissed. Its settled id is dropped by the prune below, which covers
       // every silent exit with one rule rather than one branch per path.
       setToasts(prev => {
-        if (uniqueID) {
-          const existing = prev.find(t => t.options.uniqueID === uniqueID);
-          if (existing) {
-            // An ignored collision already returned above; overwrite in place.
-            return prev.map(t => (t.options.uniqueID === uniqueID ? entry : t));
-          }
-        }
-        return [...prev, entry];
+        // The cut entries go first, then the choice the projection above made
+        // (by identity): a dismissal in the same handler may have marked the
+        // replaced namesake as leaving since, which must not turn the
+        // overwrite into an append. An ignored collision already returned.
+        const kept = prev.filter(t => !cutIds.has(t.id));
+        return overwritten && kept.includes(overwritten)
+          ? kept.map(t => (t === overwritten ? entry : t))
+          : [...kept, entry];
       });
     },
-    [announce],
+    [announce, maxVisible],
   );
 
   const removeToast = useCallback((id: string, reason: ToastDismissReason) => {
@@ -465,6 +492,7 @@ export function ToastViewport({
     }
     const entry =
       toastsRef.current.find(t => t.id === id) ??
+      replacedRef.current.get(id) ??
       pendingEntriesRef.current.get(id);
     if (entry == null) {
       // Already gone: nothing to hide or report.
@@ -485,29 +513,54 @@ export function ToastViewport({
       dismissedNode.contains(active)
     ) {
       focusHandoffIdRef.current = id;
-      // Pick the neighbor to receive focus while the DOM is still intact:
-      // prefer the next toast, then the previous, else restore.
-      const remaining = toastsRef.current.filter(t => t.id !== id);
-      if (remaining.length > 0) {
-        const dismissedIndex = toastsRef.current.findIndex(t => t.id === id);
-        const next =
-          toastsRef.current[dismissedIndex + 1] ??
-          toastsRef.current[dismissedIndex - 1];
-        pendingFocusRef.current = next ? next.id : 'restore';
-      } else {
-        pendingFocusRef.current = 'restore';
-      }
+      // Pick the toast to receive focus while the DOM is still intact: the
+      // nearest one after it, then before it, that shows once it is gone
+      // (FR10), else restore. The list may already run ahead of the render
+      // within this handler: a toast a repeat replaced has left it, and the
+      // replacement holds its place, so the neighbors are taken around the
+      // replacement, which takes focus only when no neighbor shows.
+      const list = toastsRef.current;
+      const {uniqueID} = entry.options;
+      const ownIndex = list.findIndex(t => t.id === id);
+      const placeIndex =
+        ownIndex >= 0 || uniqueID == null
+          ? ownIndex
+          : list.findIndex(t => t.options.uniqueID === uniqueID);
+      const remaining = list.filter(t => t.id !== id);
+      const max = maxVisibleRef.current;
+      const shown = new Set(max > 0 ? remaining.slice(-max) : remaining);
+      const isShown = (t: ToastEntry) => shown.has(t);
+      const replacement = ownIndex < 0 ? list[placeIndex] : undefined;
+      const next =
+        placeIndex < 0
+          ? undefined
+          : (list.slice(placeIndex + 1).find(isShown) ??
+            list.slice(0, placeIndex).reverse().find(isShown) ??
+            (replacement != null && isShown(replacement)
+              ? replacement
+              : undefined));
+      pendingFocusRef.current = next ? next.id : 'restore';
     }
-    if (dismissedNode == null) {
-      // No row is mounted for it: it is hidden past `maxVisible`, or it has
-      // not rendered yet. Nothing animates out, so it leaves the list now.
+    // A toast this handler has already pushed out of the visible window still
+    // has its row now, but loses it when the batch renders.
+    const index = toastsRef.current.findIndex(t => t.id === id);
+    const isPushedOut =
+      maxVisibleRef.current > 0 &&
+      index >= 0 &&
+      index < toastsRef.current.length - maxVisibleRef.current;
+    if (dismissedNode == null || isPushedOut) {
+      // No row is mounted for it, or none will be: it is hidden past
+      // `maxVisible`, or it has not rendered yet. Nothing animates out, so it
+      // leaves the list now.
       // Waiting for its row to finish exiting would keep it forever: when it
       // surfaced, its row would mount already collapsed, with no transition
       // left to end, and hold a visible slot as an empty row.
       // It leaves the committed list now too, so a second dismissal before
-      // the next render finds nothing to report.
+      // the next render finds nothing to report (nor does a toast a repeat
+      // replaced in this batch).
       exitingIdsRef.current.delete(id);
       pendingEntriesRef.current.delete(id);
+      replacedRef.current.delete(id);
       toastsRef.current = toastsRef.current.filter(t => t.id !== id);
       setToasts(prev => prev.filter(t => t.id !== id));
       return;
@@ -731,6 +784,21 @@ export function ToastViewport({
   const viewport = (
     <div
       ref={viewportRef}
+      onFocus={event => {
+        // Focus entering from outside, however it came, is where a dismissal
+        // of the last toast returns it. React also delivers focus inside a
+        // toast's portaled content here, so focus coming back from the last
+        // element focused within is not an entry, though it sits outside
+        // this element.
+        const from = event.relatedTarget;
+        const fromWithin =
+          from === lastFocusedWithinRef.current ||
+          (from instanceof Node && event.currentTarget.contains(from));
+        lastFocusedWithinRef.current = event.target;
+        if (from instanceof HTMLElement && !fromWithin) {
+          prevFocusRef.current = from;
+        }
+      }}
       role={hasToasts ? 'region' : undefined}
       aria-label={hasToasts ? t('@astryx.toast.viewport') : undefined}
       tabIndex={hasToasts ? -1 : undefined}

package/src/Toast/useToast.tsx

@@ -7,6 +7,7 @@ import {createRoot} from 'react-dom/client';
 import {dataAttr} from '../naming';
 import {ToastContext, type ToastContextValue} from './ToastContext';
 import {ToastViewport} from './ToastViewport';
+import {ThemeNestingContext} from '../theme/Theme';
 import {warnOnce} from '../utils/devWarning';
 import type {
   ToastOptions,
@@ -101,10 +102,14 @@ function getFallbackContext(): ToastContextValue {
   };
 
   fallbackRoot = createRoot(container);
+  // This root sits inside the app, so a <Theme> in toast content is nested:
+  // it themes its own subtree and leaves the app's <html> sync alone.
   fallbackRoot.render(
-    <ToastViewport>
-      <FallbackCapture />
-    </ToastViewport>,
+    <ThemeNestingContext value={true}>
+      <ToastViewport>
+        <FallbackCapture />
+      </ToastViewport>
+    </ThemeNestingContext>,
   );
 
   // Proxy that queues calls until real context is captured

package/src/ToggleButton/ToggleButton.tsx

@@ -29,7 +29,7 @@ import {Button, type ButtonSize} from '../Button';
 import type {Elevation} from '../utils/types';
 import {useToggleButtonGroup} from './ToggleButtonGroup';
 import type {BaseProps} from '../BaseProps';
-import {themeProps} from '../utils/themeProps';
+import {themeDataAttributes, themeProps} from '../utils/themeProps';
 import {mergeProps} from '../utils/mergeProps';
 
 // =============================================================================
@@ -319,6 +319,7 @@ export function ToggleButton({
 
   // isIconOnly prop is the source of truth for icon-only rendering.
   const labelContent =
+    // eslint-disable-next-line @astryx/no-nullish-jsx-guard -- switching to isRenderable would show `label` for children of '', false or true, a visible change that needs a decision
     children != null ? (
       <span {...stylex.props(labelStyles.wrapper)}>
         <span {...stylex.props(isPressed && labelStyles.pressed)}>
@@ -352,7 +353,6 @@ export function ToggleButton({
       isLoading={isLoading}
       isInterruptible
       isIconOnly={isIconOnly}
-      aria-pressed={isPressed}
       icon={resolvedIcon}
       tooltip={tooltip}
       {...mergeProps(
@@ -366,7 +366,14 @@ export function ToggleButton({
       style={style}
       onClick={handleClick}
       clickAction={clickAction}
-      {...props}>
+      {...props}
+      // The pressed state this component owns wins over a caller's
+      // same-named attributes (public-component-api INV5).
+      aria-pressed={isPressed}
+      {...themeDataAttributes({
+        isPressed: isPressed ? 'true' : 'false',
+        elevation,
+      })}>
       {labelContent}
     </Button>
   );

package/src/ToggleButton/ToggleButtonGroup.tsx

@@ -23,6 +23,7 @@ import {createLayerScopedContext as createContext} from '../Layer/layerScopedCon
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import type {ButtonSize} from '../Button';
+import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {themeProps} from '../utils/themeProps';
@@ -74,7 +75,15 @@ const styles = stylex.create({
 // Props — Discriminated Union
 // =============================================================================
 
-interface ToggleButtonGroupBaseProps {
+/**
+ * Host props reach the group element (`architecture:public-component-api`
+ * INV5): `className`, `style`, `id`, `aria-*`, `data-*` and handlers. The group
+ * keeps its own `role`, `aria-label` and theme target.
+ */
+interface ToggleButtonGroupBaseProps extends Omit<
+  BaseProps<HTMLDivElement>,
+  'onChange' | 'defaultValue' | 'role' | 'aria-label'
+> {
   /** Toggle button children. */
   children: ReactNode;
 
@@ -184,7 +193,14 @@ export function ToggleButtonGroup(props: ToggleButtonGroupProps): ReactNode {
     size,
     isDisabled = false,
     xstyle,
+    className,
+    style,
     'data-testid': testId,
+    // Read through `props` below, where the union narrows them by `type`.
+    type: _type,
+    value: _value,
+    onChange: _onChange,
+    ...hostProps
   } = props;
 
   const isMultiple = props.type === 'multiple';
@@ -225,6 +241,7 @@ export function ToggleButtonGroup(props: ToggleButtonGroupProps): ReactNode {
   return (
     <ToggleButtonGroupContext value={contextValue}>
       <div
+        {...hostProps}
         role="group"
         aria-label={label}
         data-testid={testId}
@@ -235,6 +252,8 @@ export function ToggleButtonGroup(props: ToggleButtonGroupProps): ReactNode {
             orientation === 'vertical' && styles.vertical,
             xstyle,
           ),
+          className,
+          style,
         )}>
         {children}
       </div>

package/src/Token/Token.doc.mjs

@@ -88,7 +88,7 @@ export const docs = {
     },
   ],  theming: {
     targets: [
-      {className: 'astryx-token', visualProps: ['color', 'size']},
+      {className: 'astryx-token', visualProps: ['color', 'size'], states: ['disabled']},
     ],
   },
   usage: {
@@ -193,7 +193,7 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-token', visualProps: ['color', 'size']},
+      {className: 'astryx-token', visualProps: ['color', 'size'], states: ['disabled']},
     ],
   },
   usage: {