@cube-dev/ui-kit 0.102.0 → 0.103.0

package/types/components/navigation/Tabs/types.d.ts

@@ -0,0 +1,238 @@
+import type { Key } from '@react-types/shared';
+import type { ReactNode } from 'react';
+import type { BaseProps, OuterStyleProps, Styles } from '../../../tasty';
+import type { CubeItemActionProps } from '../../actions/ItemAction';
+import type { CubeMenuProps } from '../../actions/Menu';
+import type { CubeItemProps } from '../../content/Item';
+/** Visual appearance type for tabs */
+export type TabType = 'default' | 'narrow' | 'file' | 'panel' | 'radio';
+/**
+ * Tab size options.
+ * Radio type only supports 'medium' | 'large' (mapped to smaller Item sizes).
+ */
+export type TabSize = 'xsmall' | 'small' | 'medium' | 'large';
+/**
+ * Size mapping for radio type tabs.
+ * Radio type uses smaller sizes similar to RadioGroup tabs mode.
+ */
+export declare const RADIO_SIZE_MAP: Record<'medium' | 'large', TabSize>;
+/** Common props for panel rendering behavior */
+export interface PanelBehaviorProps {
+    /** If true, panel is rendered but hidden when not active. */
+    prerender?: boolean;
+    /** If true, once visited the panel stays in DOM. */
+    keepMounted?: boolean;
+}
+/** Common props for QA attributes */
+export interface QAProps {
+    /** QA selector attribute. */
+    qa?: string;
+    /** Additional QA value attribute. */
+    qaVal?: string;
+}
+/** Props from CubeItemProps that don't apply to Tab */
+type OmittedItemProps = 'id' | 'type' | 'size' | 'theme' | 'shape' | 'icon' | 'rightIcon' | 'prefix' | 'suffix' | 'description' | 'descriptionPlacement' | 'descriptionProps' | 'tooltip' | 'defaultTooltipPlacement' | 'hotkeys' | 'keyboardShortcutProps' | 'loadingSlot' | 'isLoading' | 'labelProps' | 'labelRef' | 'level' | 'highlight' | 'highlightCaseSensitive' | 'highlightStyles' | 'variant' | 'htmlType' | 'isSelected' | 'preserveActionsSpace' | 'disableActionsFocus' | 'actions' | 'showActionsOnHover';
+/** Common styling props for tabs - inherits style props from CubeItemProps */
+export interface TabStyleProps extends Omit<CubeItemProps, OmittedItemProps> {
+    /**
+     * Tab size. Supports 'xsmall', 'small', 'medium', 'large'.
+     * Radio type only supports 'medium' | 'large' (mapped to smaller Item sizes).
+     */
+    size?: TabSize;
+    /** Visual appearance type. */
+    type?: TabType;
+    /** Whether to show actions only on hover. */
+    showActionsOnHover?: boolean;
+}
+/** Cache key type - primitives only for reliable comparison */
+export type CacheKeyValue = string | number | boolean | null | undefined;
+export interface CubeTabsProps extends BaseProps, OuterStyleProps, PanelBehaviorProps {
+    /** Controlled active tab key. When provided, component is controlled. */
+    activeKey?: Key;
+    /** Initial active tab key for uncontrolled mode. */
+    defaultActiveKey?: Key;
+    /**
+     * Visual appearance type for tabs.
+     * - `default` - Standard tabs with selection indicator below (default)
+     * - `narrow` - Same as default but with collapsed vertical padding on labels
+     * - `file` - File-style tabs with fill highlight on selection, delimiter between tabs
+     * - `panel` - Panel-style tabs with border bottom highlight on selection, delimiter between tabs
+     * - `radio` - Radio button style for tab selection
+     * @default 'default'
+     */
+    type?: TabType;
+    /**
+     * Tab size. Supports 'xsmall', 'small', 'medium', 'large'.
+     * Radio type only supports 'medium' | 'large' (mapped to smaller Item sizes).
+     * @default 'medium'
+     */
+    size?: TabSize;
+    /** Accessible label for the tab list. */
+    label?: string;
+    /** Content rendered before the tab list. */
+    prefix?: ReactNode;
+    /** Content rendered after the tab list. */
+    suffix?: ReactNode;
+    /** Callback when active tab changes. */
+    onChange?: (key: Key) => void;
+    /** Callback when tab delete button is clicked. Presence enables delete buttons. */
+    onDelete?: (key: Key) => void;
+    /** Callback when a tab title is changed. Enables title editing on tabs with isEditable. */
+    onTitleChange?: (key: Key, newTitle: string) => void;
+    /** Whether to show tab actions only on hover. Can be overridden per-tab. */
+    showActionsOnHover?: boolean;
+    /**
+     * Whether tabs are editable by default.
+     * Can be overridden per-tab via Tab's isEditable prop.
+     * @default false
+     */
+    isEditable?: boolean;
+    /**
+     * Default menu items for all tabs.
+     * Can be overridden per-tab via Tab's menu prop.
+     * Set to `null` on individual Tab to disable menu for that tab.
+     */
+    menu?: ReactNode;
+    /**
+     * Default props for the menu trigger button.
+     * Can be overridden per-tab via Tab's menuTriggerProps prop.
+     * @default { icon: <MoreIcon /> }
+     */
+    menuTriggerProps?: Partial<CubeItemActionProps>;
+    /**
+     * Default props passed to the Menu component.
+     * Can be overridden per-tab via Tab's menuProps prop.
+     */
+    menuProps?: Partial<CubeMenuProps<object>>;
+    /**
+     * Whether to show context menu on right-click for all tabs.
+     * Can be overridden per-tab via Tab's contextMenu prop.
+     * @default false
+     */
+    contextMenu?: boolean;
+    /**
+     * Callback when a menu action is triggered on any tab.
+     * Called with the action key and the tab key.
+     * Tab-level onAction is called first, then this.
+     */
+    onAction?: (action: Key, tabKey: Key) => void;
+    /** Custom tasty styles for the tab bar container. */
+    styles?: Styles;
+    /** QA selector attribute. */
+    qa?: string;
+    /** Tab components or Tabs.List with Tabs.Panel. */
+    children?: ReactNode;
+    /**
+     * Functional content renderer for optimized lazy evaluation.
+     * When provided, panel content is only evaluated for the active tab,
+     * while inactive tabs use cached content.
+     */
+    renderPanel?: (key: Key) => ReactNode;
+    /**
+     * Cache keys for individual panels. Enables caching for specified panels.
+     */
+    panelCacheKeys?: Record<string | number, CacheKeyValue>;
+    /**
+     * Enable drag-and-drop tab reordering.
+     * @default false
+     */
+    isReorderable?: boolean;
+    /**
+     * Controlled order of tab keys.
+     * When provided, tabs are displayed in this order.
+     */
+    keyOrder?: Key[];
+    /**
+     * Callback when tabs are reordered via drag-and-drop.
+     */
+    onReorder?: (newOrder: Key[]) => void;
+    /**
+     * Whether to show a tab picker dropdown in the suffix area.
+     * - `true` - always show the tab picker
+     * - `false` - never show the tab picker (default)
+     * - `'auto'` - show only when tabs overflow (has horizontal scroll)
+     * @default false
+     */
+    showTabPicker?: boolean | 'auto';
+}
+export interface CubeTabProps extends TabStyleProps, PanelBehaviorProps {
+    /**
+     * Unique identifier for the tab.
+     * Auto-injected from the React `key` prop (converted to string).
+     */
+    id?: string;
+    /** Content displayed in the tab button. */
+    title: ReactNode;
+    /** Panel content rendered when tab is active. */
+    children?: ReactNode;
+    /** Disables the tab (cannot be selected). */
+    isDisabled?: boolean;
+    /** Actions to render in the tab. Rendered before menu trigger if tab has menu. */
+    actions?: ReactNode;
+    /** Whether the tab title can be edited. Overrides the Tabs-level isEditable default. */
+    isEditable?: boolean;
+    /** Callback when this tab's title is changed. Overrides parent's onTitleChange. */
+    onTitleChange?: (newTitle: string) => void;
+    /**
+     * Menu items to display in a dropdown menu on the tab.
+     * Pass Menu.Item elements directly - they will be wrapped in a Menu internally.
+     * Overrides the Tabs-level menu default. Set to `null` to disable menu.
+     */
+    menu?: ReactNode | null;
+    /**
+     * Props to customize the menu trigger button.
+     * Overrides the Tabs-level menuTriggerProps default.
+     */
+    menuTriggerProps?: Partial<CubeItemActionProps>;
+    /**
+     * Props passed to the Menu component.
+     * Overrides the Tabs-level menuProps default.
+     */
+    menuProps?: Partial<CubeMenuProps<object>>;
+    /**
+     * Whether to show context menu on right-click.
+     * Uses the same menu items as `menu` prop.
+     * @default false
+     */
+    contextMenu?: boolean;
+    /**
+     * Callback when a menu action is triggered.
+     * Called with the action key from Menu.Item.
+     */
+    onAction?: (action: Key) => void;
+}
+export interface CubeTabPanelProps extends PanelBehaviorProps, QAProps {
+    /**
+     * Panel identifier. Must match a Tab's id.
+     * Auto-injected from the React `key` prop (converted to string).
+     */
+    id?: string;
+    /** Panel content. */
+    children?: ReactNode;
+    /** Custom tasty styles for the panel container. */
+    styles?: Styles;
+}
+export interface CubeTabListProps {
+    /** Tab components. */
+    children?: ReactNode;
+}
+/**
+ * Internal representation of a parsed Tab.
+ * Uses `content` instead of `children` to distinguish panel content.
+ */
+export interface ParsedTab extends Omit<CubeTabProps, 'id' | 'children'> {
+    /** Tab key (always a string internally for React Aria compatibility) */
+    key: string;
+    /** Panel content extracted from Tab's children prop */
+    content: ReactNode;
+}
+/**
+ * Internal representation of a parsed TabPanel.
+ */
+export interface ParsedPanel extends Omit<CubeTabPanelProps, 'id' | 'children'> {
+    /** Panel key (always a string internally for React Aria compatibility) */
+    key: string;
+    /** Panel content extracted from TabPanel's children prop */
+    content: ReactNode;
+}
+export {};

package/types/components/navigation/Tabs/use-tab-editing.d.ts

@@ -0,0 +1,30 @@
+import type { Key } from '@react-types/shared';
+export interface UseTabEditingOptions {
+    /** Callback when tab selection changes (used to select tab when editing starts) */
+    onChange?: (key: Key) => void;
+    /** Callback when a tab title is changed */
+    onTitleChange?: (key: Key, newTitle: string) => void;
+}
+export interface UseTabEditingResult {
+    /** Currently editing tab key (null if not editing) */
+    editingKey: Key | null;
+    /** Current edit input value */
+    editValue: string;
+    /** Set the edit value */
+    setEditValue: (value: string) => void;
+    /** Start editing a tab with the given title */
+    startEditing: (key: Key, currentTitle: string) => void;
+    /** Submit the current edit */
+    submitEditing: (key: Key, newTitle: string, tabOnTitleChange?: (title: string) => void) => void;
+    /** Cancel the current edit */
+    cancelEditing: () => void;
+}
+/**
+ * Hook to manage tab title editing state.
+ *
+ * Provides state and callbacks for inline title editing with support for:
+ * - Starting edit mode (selecting the tab and focusing input)
+ * - Submitting changes (with tab-level or parent-level callback)
+ * - Canceling edits
+ */
+export declare function useTabEditing({ onChange, onTitleChange, }?: UseTabEditingOptions): UseTabEditingResult;

package/types/components/navigation/Tabs/use-tab-indicator.d.ts

@@ -0,0 +1,20 @@
+import { RefObject } from 'react';
+import type { Key } from '@react-types/shared';
+export interface IndicatorStyle {
+    left: number;
+    width: number;
+}
+/**
+ * Hook to track and animate tab indicator position.
+ *
+ * Calculates the position and width of the selection indicator
+ * based on the currently selected tab. Returns null if disabled
+ * (e.g., for non-default tab types).
+ *
+ * @param containerRef - Ref to the tab container element
+ * @param selectedKey - Currently selected tab key
+ * @param enabled - Whether the indicator should be shown
+ * @param orderToken - Optional token that changes when tab order changes (triggers recalculation)
+ * @returns Indicator style (left, width) or null if disabled/not ready
+ */
+export declare function useTabIndicator(containerRef: RefObject<HTMLElement | null>, selectedKey: Key | null, enabled: boolean, orderToken?: string): IndicatorStyle | null;