@servicetitan/anvil2 1.37.2 → 1.38.0

package/dist/components/Listbox/Listbox.d.ts

@@ -1,19 +1,143 @@
 import { ListboxProps as CoreListboxProps, ListboxOptionProps as CoreListboxOptionProps, ListboxOptionGroupProps as CoreListboxOptionGroupProps } from '@servicetitan/hammer-react';
 import { ForwardedRef } from 'react';
 import { DataTrackingId } from '../../types/DataTrackingId';
+/**
+ * Props for the Listbox component
+ * @property {"single" | "multiple"} [selectionMode] - Selection mode for the listbox
+ * @property {boolean} [disableAutoSelectOnFocus] - Whether to disable automatic selection when focusing on an option
+ * @property {string | string[] | ItemType<T> | ItemType<T>[]} [selected] - Currently selected item(s) (controlled)
+ * @property {string | string[] | ItemType<T> | ItemType<T>[]} [defaultSelected] - Default selected item(s) (uncontrolled)
+ * @property {function} [onSelectionChange] - Callback when selection changes
+ * @property {ItemType<T>[]} [items] - Array of items to render (when using items prop)
+ * @property {ReactNode | function} [children] - Child elements or render function for items
+ * @extends ComponentPropsWithoutRef<"ul">
+ * @extends LayoutUtilProps
+ */
 export type ListboxProps<T> = CoreListboxProps<T>;
+/**
+ * Props for the ListboxOption component
+ * @property {string} value - The value of the option
+ * @property {string} [label] - The display label for the option
+ * @property {boolean} [disabled] - Whether the option is disabled
+ * @property {ItemType<T>} [item] - The item object when using items prop
+ * @extends ComponentPropsWithoutRef<"li">
+ */
 export type ListboxOptionProps = CoreListboxOptionProps & DataTrackingId;
+/**
+ * Props for the ListboxOptionGroup component
+ * @property {string} label - The label for the option group
+ * @property {ReactNode} children - The options within this group
+ * @extends ComponentPropsWithoutRef<"div">
+ */
 export type ListboxOptionGroupProps = CoreListboxOptionGroupProps;
+/**
+ * Listbox component for selecting one or more items from a list
+ *
+ * Features:
+ * - Supports single and multiple selection modes
+ * - Keyboard navigation with arrow keys and type-ahead
+ * - Optional auto-selection on focus
+ * - Controlled and uncontrolled modes
+ * - Accessible with proper ARIA attributes
+ * - Supports custom item rendering
+ * - Option grouping for organization
+ * - Layout utilities for positioning and spacing
+ * - Automatic tracking ID generation for analytics
+ *
+ * @template T - The type of additional properties for items
+ * @example
+ * <Listbox selectionMode="single" onSelectionChange={handleSelection}>
+ *   <Listbox.Option value="option1">Option 1</Listbox.Option>
+ *   <Listbox.Option value="option2">Option 2</Listbox.Option>
+ * </Listbox>
+ */
 declare const ListboxElement: <T>(props: ListboxProps<T>, ref: ForwardedRef<HTMLUListElement>) => import("react/jsx-runtime").JSX.Element;
+/**
+ * ListboxOption component for individual selectable items within a listbox
+ *
+ * Features:
+ * - Displays selectable options with proper ARIA attributes
+ * - Supports disabled state for non-selectable options
+ * - Keyboard navigation support
+ * - Automatic tracking ID generation for analytics
+ * - Accessible with screen reader support
+ *
+ * @example
+ * <ListboxOption value="option1" label="Option 1" />
+ */
 export declare const ListboxOption: import('react').ForwardRefExoticComponent<ListboxOptionProps & import('react').RefAttributes<HTMLLIElement>>;
+/**
+ * ListboxOptionGroup component for grouping related options within a listbox
+ *
+ * Features:
+ * - Groups related options with a descriptive label
+ * - Maintains proper ARIA structure for accessibility
+ * - Supports keyboard navigation within groups
+ * - Visual separation of option categories
+ *
+ * @example
+ * <ListboxOptionGroup label="Fruits">
+ *   <ListboxOption value="apple">Apple</ListboxOption>
+ *   <ListboxOption value="banana">Banana</ListboxOption>
+ * </ListboxOptionGroup>
+ */
 export declare const ListboxOptionGroup: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
     disabled?: boolean;
     label: string;
 } & import('react').RefAttributes<HTMLDivElement>>;
+/**
+ * Listbox component for selecting one or more items from a list
+ *
+ * Features:
+ * - Supports single and multiple selection modes
+ * - Keyboard navigation with arrow keys and type-ahead
+ * - Optional auto-selection on focus
+ * - Controlled and uncontrolled modes
+ * - Accessible with proper ARIA attributes
+ * - Supports custom item rendering
+ * - Option grouping for organization
+ * - Layout utilities for positioning and spacing
+ * - Automatic tracking ID generation for analytics
+ *
+ * @template T - The type of additional properties for items
+ * @example
+ * <Listbox selectionMode="single" onSelectionChange={handleSelection}>
+ *   <Listbox.Option value="option1">Option 1</Listbox.Option>
+ *   <Listbox.Option value="option2">Option 2</Listbox.Option>
+ * </Listbox>
+ */
 export declare const Listbox: (<T>(props: ListboxProps<T> & {
     ref?: React.ForwardedRef<HTMLUListElement>;
 }) => ReturnType<typeof ListboxElement>) & {
+    /**
+     * ListboxOption component for individual selectable items within a listbox
+     *
+     * Features:
+     * - Displays selectable options with proper ARIA attributes
+     * - Supports disabled state for non-selectable options
+     * - Keyboard navigation support
+     * - Automatic tracking ID generation for analytics
+     * - Accessible with screen reader support
+     *
+     * @example
+     * <Listbox.Option value="option1" label="Option 1" />
+     */
     Option: import('react').ForwardRefExoticComponent<ListboxOptionProps & import('react').RefAttributes<HTMLLIElement>>;
+    /**
+     * ListboxOptionGroup component for grouping related options within a listbox
+     *
+     * Features:
+     * - Groups related options with a descriptive label
+     * - Maintains proper ARIA structure for accessibility
+     * - Supports keyboard navigation within groups
+     * - Visual separation of option categories
+     *
+     * @example
+     * <Listbox.OptionGroup label="Fruits">
+     *   <Listbox.Option value="apple">Apple</Listbox.Option>
+     *   <Listbox.Option value="banana">Banana</Listbox.Option>
+     * </Listbox.OptionGroup>
+     */
     OptionGroup: import('react').ForwardRefExoticComponent<Omit<import('react').DetailedHTMLProps<import('react').HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
         disabled?: boolean;
         label: string;

package/dist/components/Menu/Menu.d.ts

@@ -1,13 +1,97 @@
 import { MenuProps as CoreMenuProps, MenuItemProps as CoreMenuItemProps } from '@servicetitan/hammer-react';
 import { DataTrackingId } from '../../types/DataTrackingId';
+/**
+ * Props for the Menu component
+ * @property {string} [value] - The value associated with the menu for tracking
+ * @property {string} [aria-label] - Accessible label for the menu
+ */
 export type MenuProps = CoreMenuProps & DataTrackingId;
+/**
+ * Props for the MenuItem component
+ * @property {string} [label] - The label text for the menu item
+ */
 export type MenuItemProps = CoreMenuItemProps & DataTrackingId;
+/**
+ * MenuItem component for individual menu options within a Menu.
+ *
+ * Features:
+ * - Supports icons and labels
+ * - Keyboard navigation support
+ * - Disabled state handling
+ * - Automatic menu closing on selection
+ * - Fully accessible with proper ARIA attributes
+ * - Focus management and tab index handling
+ * - Click and mouse enter event handling
+ * - Legacy popover support with fallback
+ * - Automatic tracking ID generation for analytics
+ *
+ * @example
+ * <MenuItem
+ *   label="Edit Profile"
+ *   icon={EditIcon}
+ *   onClick={() => console.log('Edit profile clicked')}
+ * />
+ */
 export declare const MenuItem: import('react').ForwardRefExoticComponent<{
     icon?: import('@servicetitan/hammer-react').IconProps["svg"];
     label: import('react').ReactNode;
     disabled?: boolean;
 } & Omit<import('react').DetailedHTMLProps<import('react').ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref"> & DataTrackingId & import('react').RefAttributes<HTMLButtonElement>>;
-export declare const Menu: ((props: MenuProps) => import("react/jsx-runtime").JSX.Element) & {
+/**
+ * Menu component for displaying dropdown menus with navigation and actions.
+ *
+ * Features:
+ * - Supports both controlled and uncontrolled modes
+ * - Automatic positioning with fallback strategies
+ * - Keyboard navigation with arrow keys and escape
+ * - Custom trigger elements
+ * - Nested menu support
+ * - Automatic height adjustment
+ * - Scroll indicators for overflow content
+ * - Fully accessible with proper ARIA attributes
+ * - Popover API support with legacy fallback
+ * - Outside click detection and handling
+ * - Automatic tracking ID generation for analytics
+ *
+ * @example
+ * <Menu label="Edit">
+ *   <Menu.Item label="Cut" onClick={() => console.log('Cut clicked')} />
+ *   <Menu.Item label="Copy" onClick={() => console.log('Copy clicked')} />
+ *   <Menu label="Copy as">
+ *     <Menu.Item label="Text" onClick={() => console.log('Copy as Text')} />
+ *     <Menu.Item label="Video" onClick={() => console.log('Copy as Video')} />
+ *     <Menu label="Image">
+ *       <Menu.Item label=".png" onClick={() => console.log('Copy as PNG')} />
+ *       <Menu.Item label=".jpg" onClick={() => console.log('Copy as JPG')} />
+ *     </Menu>
+ *   </Menu>
+ * </Menu>
+ */
+export declare const Menu: {
+    (props: MenuProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string | undefined;
+} & {
+    /**
+     * MenuItem component for individual menu options.
+     *
+     * Features:
+     * - Supports icons and labels
+     * - Keyboard navigation support
+     * - Disabled state handling
+     * - Automatic menu closing on selection
+     * - Fully accessible with proper ARIA attributes
+     * - Focus management and tab index handling
+     * - Click and mouse enter event handling
+     * - Legacy popover support with fallback
+     * - Automatic tracking ID generation for analytics
+     *
+     * @example
+     * <Menu.Item
+     *   label="Edit Profile"
+     *   icon={EditIcon}
+     *   onClick={() => console.log('Edit profile clicked')}
+     * />
+     */
     Item: import('react').ForwardRefExoticComponent<{
         icon?: import('@servicetitan/hammer-react').IconProps["svg"];
         label: import('react').ReactNode;

package/dist/components/Overflow/Overflow.d.ts

@@ -1,8 +1,92 @@
 import { OverflowProps as CoreOverflowProps, OverflowTextProps as CoreOverflowTextProps } from '@servicetitan/hammer-react';
 import { DataTrackingId } from '../../types/DataTrackingId';
+/**
+ * Props for the Overflow component
+ * @property {string} [children] - The content to be displayed in the overflow container
+ * @property {number | string | "inherit"} [height] - The height of the overflow container
+ * @property {boolean | object} [truncate] - Whether to truncate content with expand/collapse functionality
+ */
 export type OverflowProps = CoreOverflowProps & DataTrackingId;
+/**
+ * Props for the OverflowText component
+ * @property {string} [children] - The text content to be displayed
+ * @property {number | "unlimited"} [rows] - Number of rows to display before truncation
+ * @property {boolean} [expandable] - Whether the text is expandable
+ * @property {string} [expandText] - Text to display on the expand button
+ * @property {string} [collapseText] - Text to display on the collapse button
+ */
 export type OverflowTextProps = CoreOverflowTextProps & DataTrackingId;
+/**
+ * OverflowText component for text content with line truncation and expansion.
+ *
+ * Features:
+ * - Configurable line limit with row-based truncation
+ * - Expandable content with custom expand/collapse text
+ * - Automatic height calculation and overflow detection
+ * - Keyboard navigation support for focusable elements
+ * - Resize observer for dynamic content changes
+ * - Accessibility features with proper focus management
+ * - Support for unlimited rows or specific row limits
+ * - Callback support for expand/collapse events
+ * - Layout utility props support
+ * - Automatic tracking ID generation for analytics
+ *
+ * @example
+ * <OverflowText rows={3} expandable>
+ *   <Text>
+ *     This is a long text that will be truncated to 3 rows
+ *     and can be expanded to show the full content.
+ *   </Text>
+ * </OverflowText>
+ */
 export declare const OverflowText: import('react').ForwardRefExoticComponent<OverflowTextProps & import('react').RefAttributes<HTMLDivElement>>;
+/**
+ * Overflow component for handling content that exceeds container boundaries.
+ *
+ * Features:
+ * - Supports both horizontal and vertical overflow
+ * - Automatic shadow indicators for scrollable content
+ * - Truncation with expand/collapse functionality
+ * - Keyboard navigation support for focusable elements
+ * - Automatic height and width management
+ * - Layout utility props support
+ * - Resize observer for dynamic content changes
+ * - Accessibility features with proper focus management
+ * - Scroll event handling with shadow updates
+ * - Automatic tracking ID generation for analytics
+ *
+ * @example
+ * <Overflow direction="column" height={400} gap="4">
+ *   {items.map((item, i) => (
+ *     <Card key={i} style={{ width: "100%", minHeight: 100 }}>
+ *       {item.content}
+ *     </Card>
+ *   ))}
+ * </Overflow>
+ */
 export declare const Overflow: import('react').ForwardRefExoticComponent<OverflowProps & import('react').RefAttributes<HTMLDivElement>> & {
+    /**
+     * OverflowText component for text content with line truncation and expansion.
+     *
+     * Features:
+     * - Configurable line limit with row-based truncation
+     * - Expandable content with custom expand/collapse text
+     * - Automatic height calculation and overflow detection
+     * - Keyboard navigation support for focusable elements
+     * - Resize observer for dynamic content changes
+     * - Accessibility features with proper focus management
+     * - Support for unlimited rows or specific row limits
+     * - Callback support for expand/collapse events
+     * - Layout utility props support
+     * - Automatic tracking ID generation for analytics
+     *
+     * @example
+     * <Overflow.Text rows={3} expandable>
+     *   <Text>
+     *     This is a long text that will be truncated to 3 rows
+     *     and can be expanded to show the full content.
+     *   </Text>
+     * </Overflow.Text>
+     */
     Text: import('react').ForwardRefExoticComponent<OverflowTextProps & import('react').RefAttributes<HTMLDivElement>>;
 };