@servicetitan/anvil2 3.14.1 → 3.15.0

package/dist/src/components/Toast/internal/Toaster.d.ts

@@ -3,31 +3,26 @@ import { ToastUpdateProps } from './types';
 import { ToastProps } from './Toast';
 import { ToastStackProps } from './ToastStack';
 export type ToastEventType = {
+    /** Lifecycle operation reported by the toaster. */
     eventType: "add" | "update" | "dismiss" | "dismiss-all";
+    /** Number of toasts remaining when the callback runs. */
     toastCount: number;
+    /** Toast affected by the operation. Omitted for `dismiss-all`. */
     id?: string;
+    /** Toaster that handled the operation. */
     toasterId?: string;
+    /** Values used to add or update the toast. */
     toastProps?: ToastProps | ToastUpdateProps;
 };
-/**
- * Props for the Toaster component
- * @extends ComponentPropsWithoutRef<"div">
- * @extends Omit<ToastStackProps, "toasts">
- */
 export type ToasterProps = ComponentPropsWithoutRef<"div"> & Omit<ToastStackProps, "toasts"> & {
     /**
-     * When `true`, the toaster will not listen for custom events to add, update, or dismiss toasts.
-     * Use this to prevent multiple toasters from displaying the same toasts.
-     * @default false
+     * Prevents this instance from handling shared toast events. Defaults to
+     * `false`.
      */
     disableEvents?: boolean;
-    /**
-     * Unique toaster id.
-     */
+    /** Identifies this toaster in lifecycle callbacks and targeted add events. */
     id: string;
-    /**
-     * Callback function that is called when toasts are added, updated, or dismissed.
-     */
+    /** Runs after a shared toast event is handled. */
     onToastEvent?: (toastEvent: ToastEventType) => void;
     /**
      * Callback function that is called with the number of toasts this toaster is
@@ -37,49 +32,16 @@ export type ToasterProps = ComponentPropsWithoutRef<"div"> & Omit<ToastStackProp
      */
     onToastCountChange?: (toastCount: number) => void;
 };
-/**
- * Toaster component for managing and displaying toast notifications.
- *
- * Features:
- * - Manages multiple toast notifications in a stack
- * - Handles toast positioning and stacking behavior
- * - Supports custom events for toast management
- * - Automatic toast dismissal with configurable duration
- * - Keyboard navigation and accessibility support
- * - Dialog-aware positioning for modal contexts
- * - Session storage for dialog toaster state
- * - Custom event system for toast lifecycle management
- * - Responsive design with mobile support
- *
- * @example
- * <Toaster
- *   id="main-toaster"
- *   duration={5000}
- *   toastsBeforeStack={3}
- *   onToastEvent={(event) => console.log('Toast event:', event)}
- * />
- *
- * @example
- * <Toaster
- *   id="dialog-toaster"
- *   disableEvents={false}
- *   focusKey="t"
- * />
- */
+/** Event-driven toaster content shared by page and dialog hosts. */
 export declare const ToasterContent: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & Omit<ToastStackProps, "toasts"> & {
     /**
-     * When `true`, the toaster will not listen for custom events to add, update, or dismiss toasts.
-     * Use this to prevent multiple toasters from displaying the same toasts.
-     * @default false
+     * Prevents this instance from handling shared toast events. Defaults to
+     * `false`.
      */
     disableEvents?: boolean;
-    /**
-     * Unique toaster id.
-     */
+    /** Identifies this toaster in lifecycle callbacks and targeted add events. */
     id: string;
-    /**
-     * Callback function that is called when toasts are added, updated, or dismissed.
-     */
+    /** Runs after a shared toast event is handled. */
     onToastEvent?: (toastEvent: ToastEventType) => void;
     /**
      * Callback function that is called with the number of toasts this toaster is
@@ -91,18 +53,13 @@ export declare const ToasterContent: import('react').ForwardRefExoticComponent<O
 } & import('react').RefAttributes<HTMLDivElement>>;
 export declare const Toaster: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & Omit<ToastStackProps, "toasts"> & {
     /**
-     * When `true`, the toaster will not listen for custom events to add, update, or dismiss toasts.
-     * Use this to prevent multiple toasters from displaying the same toasts.
-     * @default false
+     * Prevents this instance from handling shared toast events. Defaults to
+     * `false`.
      */
     disableEvents?: boolean;
-    /**
-     * Unique toaster id.
-     */
+    /** Identifies this toaster in lifecycle callbacks and targeted add events. */
     id: string;
-    /**
-     * Callback function that is called when toasts are added, updated, or dismissed.
-     */
+    /** Runs after a shared toast event is handled. */
     onToastEvent?: (toastEvent: ToastEventType) => void;
     /**
      * Callback function that is called with the number of toasts this toaster is

package/dist/src/components/Toast/internal/ToasterPopover.d.ts

@@ -1,19 +1,4 @@
-/**
- * ToasterPopover component for displaying toast notifications in a popover.
- *
- * Features:
- * - Displays toast notifications in a native popover element
- * - Automatically shows/hides based on toast count
- * - Handles dialog toaster state management
- * - Browser compatibility checking for popover support
- * - Smooth transitions between show/hide states
- * - Integration with toast provider context
- *
- * @example
- * <ToasterPopover>
- *   <ToastStack toasts={toastList} />
- * </ToasterPopover>
- */
+/** Keeps active notifications in the browser's top layer. */
 export declare const ToasterPopover: import('react').ForwardRefExoticComponent<{
     children?: import('react').ReactNode | undefined;
 } & import('react').RefAttributes<HTMLDivElement>>;

package/dist/src/components/Toast/internal/addOrUpdateToastHeight.d.ts

@@ -1,8 +1,3 @@
 import { ToastProviderContextProps } from './ToastProvider';
-/**
- * Adds or updates the height of a toast in the height tracking system
- * @param toastId - The unique identifier of the toast
- * @param toastHeight - The height of the toast in pixels
- * @param setToastHeights - Function to update toast heights
- */
+/** Records the latest measured height for a toast. */
 export declare const addOrUpdateToastHeight: (toastId: string, toastHeight: number, setToastHeights: ToastProviderContextProps["setToastHeights"]) => void;

package/dist/src/components/Toast/internal/constants.d.ts

@@ -1,20 +1,5 @@
-/**
- * Animation duration for toast transitions in milliseconds
- */
 export declare const ANIMATION_DURATION = 300;
-/**
- * Total padding around the toast stack (top + bottom approximation)
- */
 export declare const TOAST_STACK_PADDING = 48;
-/**
- * Height of the expand/collapse button plus its padding
- */
 export declare const EXPAND_BUTTON_HEIGHT_WITH_PADDING = 64;
-/**
- * Scroll threshold in pixels from bottom to hide bottom gradient
- */
 export declare const SCROLL_THRESHOLD = 64;
-/**
- * Throttle interval for scroll and resize event handlers in milliseconds
- */
 export declare const EVENT_THROTTLE_MS = 16;

package/dist/src/components/Toast/internal/types.d.ts

@@ -2,6 +2,7 @@ import { ToastProps } from './Toast';
 import { toastProps } from '../toast';
 export type ToastUpdateProps = Partial<toastProps> & {
     id: string;
+    /** Replaces the alert treatment and status icon when provided. */
     status?: ToastProps["status"];
 };
 export type ToastCustomEventDetailAdd = ToastProps & {

package/dist/src/components/Toast/internal/useCloseToast.d.ts

@@ -1,7 +1,3 @@
 import { ToastProps } from './Toast';
-/**
- * Hook that returns a function to close toasts
- * @param closingToastClassName - CSS class for closing animation
- * @returns Function to close toasts by ID or all toasts
- */
+/** Returns a callback that closes one toast, or every toast when passed no ID. */
 export declare const useCloseToast: (closingToastClassName: ToastProps["toastClassName"]) => (id?: string) => void;

package/dist/src/components/Toast/internal/useHotkeyFocus.d.ts

@@ -8,16 +8,8 @@ type HotkeyFocusParams = {
     rootRef: MutableRefObject<HTMLElement>;
 };
 /**
- * A hook that listens for a hotkey press and focuses an element when the hotkey is pressed.
- * The hook also listens for the Escape key to blur the element and refocus the previous element.
- *
- * @param params
- * @param params.disabled - If true, the hotkey will not be active
- * @param params.hotkey - The key to press to focus the element
- * @param params.onHotkeyIn - A function to run when the hotkey is pressed; this runs before the element is focused
- * @param params.onHotkeyOut - A function to run when the user presses Escape after focusing the element
- * @param params.refToFocus - The ref to the element that will be focused when the hotkey is pressed
- * @param params.rootRef - The ref to the element that will listen for changes to focus, disabling the Escape key
+ * Moves focus into a region on a hotkey and restores the previous target on
+ * Escape.
  */
 export declare const useHotkeyFocus: ({ disabled, hotkey, onHotkeyIn, onHotkeyOut, refToFocus, rootRef, }: HotkeyFocusParams) => {
     returnFocusRef: MutableRefObject<HTMLElement | null>;

package/dist/src/components/Toast/internal/useShowMoreButtonPositionStyles.d.ts

@@ -1,6 +1,3 @@
 import { CSSProperties } from 'react';
-/**
- * Hook for calculating position styles for the show more button
- * @returns CSS properties for positioning the show more button
- */
+/** Positions the expand button after the visible toast heights. */
 export declare const useShowMoreButtonPositionStyles: () => CSSProperties;

package/dist/src/components/Toast/internal/useToastPositionStyles.d.ts

@@ -1,7 +1,3 @@
 import { CSSProperties } from 'react';
-/**
- * Hook for calculating position styles for individual toasts
- * @param index - The index of the toast in the stack
- * @returns CSS properties for positioning the toast
- */
+/** Positions one toast within the visible or collapsed stack. */
 export declare const useToastPositionStyles: (index: number) => CSSProperties | undefined;

package/dist/src/components/Toast/internal/useToasts.d.ts

@@ -1,6 +1,2 @@
-/**
- * Hook for accessing toast context and state management functions
- * @returns ToastProviderContextProps - The toast context with state and functions
- * @throws Error when used outside of ToastProvider
- */
+/** Returns the nearest toast provider state; throws outside `ToastProvider`. */
 export declare const useToasts: () => import('./ToastProvider').ToastProviderContextProps;

package/dist/src/components/Toast/toast.d.ts

@@ -1,92 +1,40 @@
 import { ToastUpdateProps } from './internal/types';
 import { ToastProps } from './internal/Toast';
+/** Content and behavior shared by the status-specific toast methods. */
 export type toastProps = Pick<ToastProps, "actions" | "aiMark" | "containerClassName" | "duration" | "message" | "onClose" | "onDismiss" | "progress" | "title" | "toastClassName">;
 /**
- * Use to run toast methods for adding, updating, and dismissing toasts.
- *
- * @method info
- * @method success
- * @method warning
- * @method danger
- * @method promise
- * @method update
- * @method dismiss
+ * Imperative methods for adding, updating, and dismissing notifications in a
+ * mounted {@link Toaster}.
  */
 export declare const toast: {
     (): void;
     /**
-     * Use to add info toast to the stack.
-     *
-     * @example
-     * import { toast } from "@servicetitan/anvil2";
-     * const id = toast.info({
-     *   message: "This is an info toast",
-     *   title: "Info",
-     * });
+     * Adds an informational toast and returns its generated ID.
      */
     info: (props: toastProps) => string;
     /**
-     * Use to add success toast to the stack.
-     *
-     * @example
-     * import { toast } from "@servicetitan/anvil2";
-     * const id = toast.success({
-     *   message: "This is an info toast",
-     *   title: "Info",
-     * });
+     * Adds a success toast and returns its generated ID.
      */
     success: (props: toastProps) => string;
     /**
-     * Use to add warning toast to the stack.
-     *
-     * @example
-     * import { toast } from "@servicetitan/anvil2";
-     * const id = toast.warning({
-     *   message: "This is an info toast",
-     *   title: "Info",
-     * });
+     * Adds a warning toast and returns its generated ID.
      */
     warning: (props: toastProps) => string;
     /**
-     * Use to add danger toast to the stack.
-     *
-     * @example
-     * import { toast } from "@servicetitan/anvil2";
-     * const id = toast.danger({
-     *   message: "This is an info toast",
-     *   title: "Info",
-     * });
+     * Adds a danger toast and returns its generated ID.
      */
     danger: (props: toastProps) => string;
     /**
-     * Use to update a specific toast in the stack.
-     *
-     * @example
-     * import { toast } from "@servicetitan/anvil2";
-     * const id = toast.info({
-     *   message: "This is an info toast",
-     *   title: "Info",
-     * });
-     * toast.update(id, {
-     *   message: "This is an updated toast",
-     *   title: "Updated",
-     * });
+     * Updates the toast with the matching ID.
      */
     update: (id: string, props: Omit<ToastUpdateProps, "id">) => void;
     /**
-     * Use to dismiss a specific toast in the stack.
-     *
-     * @example
-     * import { toast } from "@servicetitan/anvil2";
-     * const id = toast.info({
-     *   message: "This is an info toast",
-     *   title: "Info",
-     * });
-     * toast.dismiss(id);
+     * Dismisses the matching toast, or every toast when no ID is provided.
      */
     dismiss: (id?: string) => void;
     /**
-     * Use to create a toast that updates itself based on a Promise state.
+     * Shows a non-expiring loading toast, then replaces it with the resolved or
+     * rejected configuration. Closing it while pending creates a new result toast.
      *
      * @example
      * ```ts
@@ -115,8 +63,11 @@ export declare const toast: {
      * ```
      */
     promise: (promise: Promise<string>, toastConfig: {
+        /** Content shown while the promise is pending. */
         loading: toastProps;
+        /** Maps the resolved value to the result toast. */
         success: (data: string) => Omit<toastProps, "id">;
+        /** Maps the rejection value to the result toast. */
         error: (error: string) => Omit<toastProps, "id">;
     }) => Promise<string>;
 };

package/dist/src/components/Toolbar/Toolbar.d.ts

@@ -1,163 +1,41 @@
 import { ToolbarOverflowTypes, ToolbarSize } from './types';
 import { ComponentPropsWithoutRef, ReactElement } from 'react';
 import { DataAttributes, LayoutUtilProps } from '../../types';
-/**
- * Props for the Toolbar component
- * @extends ComponentPropsWithoutRef<"div">
- * @extends LayoutUtilProps
- */
 export type ToolbarProps = ComponentPropsWithoutRef<"div"> & LayoutUtilProps & DataAttributes & {
-    /**
-     * Description of the content this toolbar is associated with, used for accessibility
-     */
+    /** Names the content associated with the toolbar in its accessible label. */
     associatedContent: string;
-    /**
-     * Orientation of the toolbar
-     * @default horizontal
-     */
+    /** Sets both the visual layout and arrow-key axis. Defaults to `horizontal`. */
     direction?: "vertical" | "horizontal";
-    /**
-     * How to handle overflow when items don't fit
-     * @default wrap
-     */
+    /** Wraps items or moves clipped items into a menu. Defaults to `wrap`. */
     overflow?: ToolbarOverflowTypes;
-    /**
-     * Additional items to display in the overflow menu
-     */
+    /** Appends custom actions to the overflow menu, even when no toolbar items overflow. */
     additionalItems?: ReactElement[];
-    /**
-     * Size of toolbar items
-     * @default xsmall
-     */
+    /** Size inherited by the toolbar controls. Defaults to `xsmall`. */
     size?: ToolbarSize;
 };
 /**
- * Toolbar component for grouping related interactive elements with anvil2 tracking.
- *
- * Features:
- * - Horizontal or vertical orientation
- * - Overflow handling with wrap or collapse behavior
- * - Keyboard navigation following ARIA best practices
- * - Screen reader announcements and accessibility
- * - Automatic overflow menu for collapsed items
- * - Support for buttons, toggles, selects, and links
- * - Layout utilities for positioning and spacing
- * - Context-based state management for child components
- * - Automatic tracking ID generation for analytics
- * - Integration with anvil2 tracking system
- *
- * @example
- * <Toolbar associatedContent="document editor" overflow="collapse">
- *   <Toolbar.Button icon={BoldIcon} aria-label="Bold" />
- *   <Toolbar.ButtonToggle icon={ItalicIcon} aria-label="Italic" />
- *   <Toolbar.Select
- *     items={fontOptions}
- *     selected="arial"
- *     accessibleLabel="Font family"
- *   />
- * </Toolbar>
+ * Groups related controls with roving keyboard focus. Items can wrap or move
+ * into an overflow menu when space is constrained.
  */
 export declare const Toolbar: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & LayoutUtilProps & DataAttributes & {
-    /**
-     * Description of the content this toolbar is associated with, used for accessibility
-     */
+    /** Names the content associated with the toolbar in its accessible label. */
     associatedContent: string;
-    /**
-     * Orientation of the toolbar
-     * @default horizontal
-     */
+    /** Sets both the visual layout and arrow-key axis. Defaults to `horizontal`. */
     direction?: "vertical" | "horizontal";
-    /**
-     * How to handle overflow when items don't fit
-     * @default wrap
-     */
+    /** Wraps items or moves clipped items into a menu. Defaults to `wrap`. */
     overflow?: ToolbarOverflowTypes;
-    /**
-     * Additional items to display in the overflow menu
-     */
+    /** Appends custom actions to the overflow menu, even when no toolbar items overflow. */
     additionalItems?: ReactElement[];
-    /**
-     * Size of toolbar items
-     * @default xsmall
-     */
+    /** Size inherited by the toolbar controls. Defaults to `xsmall`. */
     size?: ToolbarSize;
 } & import('react').RefAttributes<HTMLDivElement>> & {
-    /**
-     * ToolbarButton component for standard clickable actions within a toolbar with anvil2 tracking.
-     *
-     * Features:
-     * - Designed specifically for toolbar integration
-     * - Consistent styling with other toolbar items
-     * - Automatic tooltip for icon-only buttons
-     * - Overflow menu support
-     * - Accessibility enforcement for aria-labels
-     * - Ghost and primary appearance options
-     * - Automatic tracking ID generation for analytics
-     *
-     * @example
-     * <Toolbar.Button icon={BoldIcon} aria-label="Bold text" />
-     *
-     * @example
-     * <Toolbar.Button appearance="primary">
-     *   Save
-     * </Toolbar.Button>
-     */
+    /** Button action that participates in toolbar sizing and overflow. */
     Button: import('react').ForwardRefExoticComponent<import('./ToolbarButton').ToolbarButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
-    /**
-     * ToolbarButtonToggle component for toggleable actions within a toolbar with anvil2 tracking.
-     *
-     * Features:
-     * - Toggle state management
-     * - Designed specifically for toolbar integration
-     * - Consistent styling with other toolbar items
-     * - Overflow menu support
-     * - Accessibility enforcement for aria-labels
-     * - Ghost and primary appearance options
-     * - Automatic tracking ID generation for analytics
-     *
-     * @example
-     * <Toolbar.ButtonToggle icon={BoldIcon} aria-label="Bold" checked={isBold} />
-     */
+    /** Toggle action that participates in toolbar sizing and overflow. */
     ButtonToggle: import('react').ForwardRefExoticComponent<import('./ToolbarButtonToggle').ToolbarButtonToggleProps & import('react').RefAttributes<HTMLButtonElement>>;
-    /**
-     * ToolbarButtonLink component for link actions within a toolbar with anvil2 tracking.
-     *
-     * Features:
-     * - Link functionality with href support
-     * - Designed specifically for toolbar integration
-     * - Consistent styling with other toolbar items
-     * - Overflow menu support
-     * - Accessibility enforcement for aria-labels
-     * - Ghost and primary appearance options
-     * - Automatic tracking ID generation for analytics
-     *
-     * @example
-     * <Toolbar.ButtonLink href="/help">
-     *   Help
-     * </Toolbar.ButtonLink>
-     */
+    /** Link action that participates in toolbar sizing and overflow. */
     ButtonLink: import('react').ForwardRefExoticComponent<import('./ToolbarButtonLink').ToolbarButtonLinkProps & import('react').RefAttributes<HTMLAnchorElement>>;
-    /**
-     * ToolbarSelect component provides a dropdown selector within a toolbar with anvil2 tracking.
-     *
-     * Features:
-     * - Dropdown menu with selectable options
-     * - Controlled and uncontrolled usage patterns
-     * - Automatic overflow menu integration
-     * - Accessibility support with proper ARIA labels
-     * - Ghost and primary appearance options
-     * - Dropdown arrow icon indicator
-     * - Listbox integration for keyboard navigation
-     * - Automatic tracking ID generation for analytics
-     *
-     * @example
-     * <Toolbar.Select
-     *   items={fontOptions}
-     *   selected="arial"
-     *   accessibleLabel="Font family"
-     *   onChange={(id) => setFont(id)}
-     * />
-     */
+    /** Listbox selector that participates in toolbar sizing and overflow. */
     Select: import('react').ForwardRefExoticComponent<Omit<Omit<Omit<Omit<import('react').DetailedHTMLProps<import('react').ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref">, "children"> & LayoutUtilProps & import('../..').DataTrackingId & {
         aiMark?: boolean | import('..').AiIconName;
         appearance?: import('../..').ButtonAppearance;

package/dist/src/components/Toolbar/ToolbarButton.d.ts

@@ -1,44 +1,19 @@
 import { ButtonProps } from '../Button';
 import { ToolbarItemAppearance, WithAriaLabelEnforcement } from './types';
 import { DataTrackingId } from '../../types';
-/**
- * Base props for the ToolbarButton component
- * @extends Omit<ButtonProps, "appearance" | "aria-label" | "children"  "onClick">
- */
 type ToolbarButtonBaseProps = Omit<ButtonProps, "appearance" | "aria-label" | "children" | "onClick"> & {
-    /**
-     * Visual appearance of the button
-     * @default ghost
-     */
+    /** Limited to Toolbar-supported appearances. Defaults to `ghost`. */
     appearance?: ToolbarItemAppearance;
-    /**
-     * Click event handler for the button
-     */
+    /** Handles activation in either the toolbar or its overflow menu. */
     onClick: ButtonProps["onClick"];
 };
-/**
- * Props for the ToolbarButton component
- * @extends WithAriaLabelEnforcement<ToolbarButtonBaseProps>
- */
 export type ToolbarButtonProps = WithAriaLabelEnforcement<ToolbarButtonBaseProps> & DataTrackingId;
 /**
- * ToolbarButton component for standard clickable actions within a toolbar.
- *
- * Features:
- * - Designed specifically for toolbar integration
- * - Consistent styling with other toolbar items
- * - Automatic tooltip for icon-only buttons
- * - Overflow menu support
- * - Accessibility enforcement for aria-labels
- * - Ghost and primary appearance options
+ * Button action that inherits its size from Toolbar. In collapse mode,
+ * clipped actions move into the overflow menu; icon-only actions show a tooltip.
  *
  * @example
  * <ToolbarButton icon={BoldIcon} aria-label="Bold text" />
- *
- * @example
- * <ToolbarButton appearance="primary">
- *   Save
- * </ToolbarButton>
  */
 export declare const ToolbarButton: import('react').ForwardRefExoticComponent<ToolbarButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
 export {};

package/dist/src/components/Toolbar/ToolbarButtonLink.d.ts

@@ -1,39 +1,14 @@
 import { ButtonLinkProps } from '../ButtonLink';
 import { ToolbarItemAppearance, WithAriaLabelEnforcement } from './types';
 import { DataTrackingId } from '../../types';
-/**
- * Base props for the ToolbarButtonLink component
- * @extends Omit<ButtonLinkProps, "appearance" | "aria-label" | "children">
- */
 type ToolbarButtonLinkBaseProps = Omit<ButtonLinkProps, "appearance" | "aria-label" | "children"> & {
-    /**
-     * Visual appearance of the button link
-     * @default ghost
-     */
+    /** Limited to Toolbar-supported appearances. Defaults to `ghost`. */
     appearance?: ToolbarItemAppearance;
 };
-/**
- * Props for the ToolbarButtonLink component
- * @extends WithAriaLabelEnforcement<ToolbarButtonLinkBaseProps>
- */
 export type ToolbarButtonLinkProps = WithAriaLabelEnforcement<ToolbarButtonLinkBaseProps> & DataTrackingId;
 /**
- * ToolbarButtonLink component for link actions within a toolbar.
- *
- * Features:
- * - Link functionality with href support
- * - Designed specifically for toolbar integration
- * - Consistent styling with other toolbar items
- * - Automatic tooltip for icon-only links
- * - Overflow menu support
- * - Accessibility enforcement for aria-labels
- * - Ghost and primary appearance options
- * - Proper anchor element semantics
- *
- * @example
- * <ToolbarButtonLink href="/help">
- *   Help
- * </ToolbarButtonLink>
+ * Link action that inherits its size from Toolbar. In collapse mode, clipped
+ * links move into the overflow menu; icon-only links show a tooltip.
  *
  * @example
  * <ToolbarButtonLink icon={ExternalLinkIcon} href="/docs" aria-label="Documentation" />