entangle-ui 0.2.0 → 0.4.0

package/dist/types/components/layout/Stack/Stack.d.ts

@@ -0,0 +1,166 @@
+import React from 'react';
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+/**
+ * Stack direction options
+ */
+type StackDirection = 'row' | 'column';
+/**
+ * Stack wrap options
+ */
+type StackWrap = 'nowrap' | 'wrap' | 'wrap-reverse';
+/**
+ * Justify content options for main axis alignment
+ */
+type StackJustify = 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly';
+/**
+ * Align items options for cross axis alignment
+ */
+type StackAlign = 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';
+/**
+ * Spacing multiplier (0-8) based on theme spacing unit
+ */
+type StackSpacing = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+interface StackBaseProps extends Omit<BaseComponent<HTMLDivElement>, 'children'> {
+    /**
+     * Stack content - any React elements
+     */
+    children: React.ReactNode;
+    /**
+     * Stack direction - controls main axis orientation
+     * - `row`: Left to right (horizontal)
+     * - `column`: Top to bottom (vertical)
+     * @default "column"
+     */
+    direction?: StackDirection | undefined;
+    /**
+     * Responsive stack direction
+     * Allows different directions at different breakpoints
+     * @example direction="column" md="row" // Vertical on mobile, horizontal on desktop
+     */
+    sm?: StackDirection | undefined;
+    md?: StackDirection | undefined;
+    lg?: StackDirection | undefined;
+    xl?: StackDirection | undefined;
+    /**
+     * Stack wrap behavior
+     * - `nowrap`: Items stay on one line (default)
+     * - `wrap`: Items wrap to new lines as needed
+     * - `wrap-reverse`: Items wrap in reverse order
+     * @default "nowrap"
+     */
+    wrap?: StackWrap | undefined;
+    /**
+     * Whether stack should expand to fill available space
+     * - For row direction: takes 100% width
+     * - For column direction: takes 100% height
+     * @default false
+     */
+    expand?: boolean;
+    /**
+     * Spacing between stack items (multiplier of base spacing unit)
+     * - `0`: No spacing (0px)
+     * - `1`: 1x base unit (4px)
+     * - `2`: 2x base unit (8px)
+     * - `3`: 3x base unit (12px)
+     * - `4`: 4x base unit (16px)
+     * @default 0
+     */
+    spacing?: StackSpacing | undefined;
+    /**
+     * Custom gap override (CSS value)
+     * Overrides spacing prop if provided
+     * @example "16px", "1rem", "2rem 1rem"
+     */
+    customGap?: string | number | undefined;
+    /**
+     * Justify content - distributes space along main axis
+     * - `flex-start`: Items packed to start (default)
+     * - `flex-end`: Items packed to end
+     * - `center`: Items centered
+     * - `space-between`: Even space between items
+     * - `space-around`: Even space around items
+     * - `space-evenly`: Equal space between and around items
+     * @default "flex-start"
+     */
+    justify?: StackJustify | undefined;
+    /**
+     * Align items - aligns items along cross axis
+     * - `flex-start`: Items align to start of cross axis (default)
+     * - `flex-end`: Items align to end of cross axis
+     * - `center`: Items centered on cross axis
+     * - `stretch`: Items stretch to fill container
+     * - `baseline`: Items align to text baseline
+     * @default "flex-start"
+     */
+    align?: StackAlign | undefined;
+}
+/**
+ * Props for the Stack component with prettified type for better IntelliSense
+ */
+type StackProps = Prettify<StackBaseProps>;
+/**
+ * A flexible stacking component for arranging elements vertically or horizontally.
+ *
+ * Built on flexbox with consistent spacing and alignment options. Perfect for
+ * simple layouts where you need to stack elements with controlled spacing.
+ * Use Grid or Flex components for more complex layout requirements.
+ *
+ * @example
+ * ```tsx
+ * // Basic vertical stack
+ * <Stack spacing={2}>
+ *   <Card>Item 1</Card>
+ *   <Card>Item 2</Card>
+ *   <Card>Item 3</Card>
+ * </Stack>
+ *
+ * // Horizontal stack with full width
+ * <Stack direction="row" expand spacing={3} justify="space-between">
+ *   <Button>Cancel</Button>
+ *   <Button variant="filled">Save</Button>
+ * </Stack>
+ *
+ * // Responsive stack
+ * <Stack
+ *   direction="column"
+ *   md="row"
+ *   spacing={2}
+ *   align="center"
+ * >
+ *   <Logo />
+ *   <Navigation />
+ *   <UserMenu />
+ * </Stack>
+ *
+ * // Centered content
+ * <Stack
+ *   direction="column"
+ *   expand
+ *   justify="center"
+ *   align="center"
+ *   spacing={4}
+ * >
+ *   <Icon />
+ *   <Title>Welcome</Title>
+ *   <Button>Get Started</Button>
+ * </Stack>
+ *
+ * // Wrapping horizontal stack
+ * <Stack
+ *   direction="row"
+ *   wrap="wrap"
+ *   spacing={2}
+ *   justify="center"
+ * >
+ *   <Tag>React</Tag>
+ *   <Tag>TypeScript</Tag>
+ *   <Tag>CSS</Tag>
+ * </Stack>
+ * ```
+ */
+declare const Stack: React.FC<StackProps>;
+
+export { Stack };
+export type { StackAlign, StackBaseProps, StackDirection, StackJustify, StackProps, StackSpacing, StackWrap };

package/dist/types/components/navigation/ContextMenu/ContextMenu.d.ts

@@ -0,0 +1,6 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ContextMenuProps } from './ContextMenu.types.js';
+
+declare function ContextMenu<TPayload = unknown>({ config, selectedItems, onChange, children, payload, checkboxIcon, radioIcon, disabled, className, style, testId, ref, ...rest }: ContextMenuProps<TPayload>): react_jsx_runtime.JSX.Element;
+
+export { ContextMenu };

package/dist/types/components/navigation/ContextMenu/ContextMenu.types.d.ts

@@ -0,0 +1,74 @@
+import React from 'react';
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent } from '../../../types/common.js';
+import { MenuConfig, MenuSelection } from '../Menu/Menu.types.js';
+
+interface ContextMenuTargetDetails<TPayload = unknown> {
+    /**
+     * Native browser contextmenu event from the latest trigger interaction.
+     * Null until the first right click.
+     */
+    event: MouseEvent | null;
+    /**
+     * Element that initiated the context menu interaction.
+     */
+    target: HTMLElement | null;
+    /**
+     * Optional payload associated with the trigger area.
+     */
+    payload?: TPayload;
+}
+type ContextMenuConfig<TPayload = unknown> = MenuConfig | ((context: ContextMenuTargetDetails<TPayload>) => MenuConfig);
+interface ContextMenuBaseProps<TPayload = unknown> extends Omit<BaseComponent<HTMLDivElement>, 'children' | 'onChange'> {
+    /**
+     * Static menu config or resolver function called with trigger context.
+     */
+    config: ContextMenuConfig<TPayload>;
+    /**
+     * Currently selected items grouped by id.
+     */
+    selectedItems?: MenuSelection;
+    /**
+     * Called when selection state changes.
+     */
+    onChange?: (selection: MenuSelection) => void;
+    /**
+     * Content that acts as the right-click trigger area.
+     */
+    children?: React.ReactNode;
+    /**
+     * Optional data attached to this trigger area and passed to config resolver.
+     */
+    payload?: TPayload;
+    /**
+     * Custom icon for checkbox selected state.
+     */
+    checkboxIcon?: React.ReactNode;
+    /**
+     * Custom icon for radio selected state.
+     */
+    radioIcon?: React.ReactNode;
+    /**
+     * Disables opening the context menu.
+     * @default false
+     */
+    disabled?: boolean;
+}
+type ContextMenuProps<TPayload = unknown> = Prettify<ContextMenuBaseProps<TPayload>>;
+interface UseContextMenuTargetResult<TPayload = unknown> {
+    /**
+     * Latest target context captured from right click interaction.
+     */
+    context: ContextMenuTargetDetails<TPayload>;
+    /**
+     * Attach this to an element if you want to capture context manually.
+     */
+    onContextMenuCapture: (event: React.MouseEvent<HTMLElement>) => void;
+    /**
+     * Callback ref that captures native right-click interactions on a node.
+     * Useful when you want ref-based wiring.
+     */
+    targetRef: (node: HTMLElement | null) => void;
+}
+
+export type { ContextMenuBaseProps, ContextMenuConfig, ContextMenuProps, ContextMenuTargetDetails, UseContextMenuTargetResult };

package/dist/types/components/navigation/ContextMenu/useContextMenuTarget.d.ts

@@ -0,0 +1,5 @@
+import { UseContextMenuTargetResult } from './ContextMenu.types.js';
+
+declare function useContextMenuTarget<TPayload = unknown>(payload?: TPayload): UseContextMenuTargetResult<TPayload>;
+
+export { useContextMenuTarget };

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

@@ -0,0 +1,42 @@
+import React from 'react';
+import { MenuProps } from './Menu.types.js';
+
+/**
+ * A configuration-driven menu component for editor interfaces.
+ *
+ * Automatically handles radio/checkbox selection states, grouping,
+ * and nested submenus based on provided configuration object.
+ *
+ * @example
+ * ```tsx
+ * const config = {
+ *   groups: [{
+ *     id: 'actions',
+ *     items: [
+ *       {
+ *         id: 'copy',
+ *         label: 'Copy',
+ *         onClick: handleCopy,
+ *         subMenu: nestedConfig,
+ *         submenuTrigger: 'hover' // Opens on hover (default)
+ *       },
+ *       {
+ *         id: 'paste',
+ *         label: 'Paste',
+ *         onClick: handlePaste,
+ *         subMenu: nestedConfig,
+ *         submenuTrigger: 'click' // Opens on click only
+ *       }
+ *     ],
+ *     itemSelectionType: 'none'
+ *   }]
+ * };
+ *
+ * <Menu config={config}>
+ *   <Button>Options</Button>
+ * </Menu>
+ * ```
+ */
+declare const Menu: React.FC<MenuProps>;
+
+export { Menu };

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

@@ -0,0 +1,94 @@
+import React from 'react';
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent } from '../../../types/common.js';
+
+/**
+ * How submenus should be triggered.
+ * - `hover`: Submenu opens on hover
+ * - `click`: Submenu opens on click only
+ */
+type SubmenuTrigger = 'hover' | 'click';
+/**
+ * Configuration for a single menu item.
+ */
+type MenuItem = {
+    /** Unique identifier for the menu item */
+    id: string;
+    /** Display text for the menu item */
+    label: string;
+    /** Click handler called with item id and event */
+    onClick: (id: string, event: MouseEvent) => void;
+    /** Optional icon rendered before the label */
+    icon?: React.ReactNode;
+    /** Whether the item is disabled */
+    disabled?: boolean;
+    /** Nested submenu configuration */
+    subMenu?: MenuConfig;
+    /** How submenu should be triggered when subMenu is present */
+    submenuTrigger?: SubmenuTrigger;
+};
+/**
+ * Type of item selection behavior within a group.
+ * - `radio`: Single selection within group
+ * - `checkbox`: Multiple selection within group
+ * - `none`: No selection state, just click handlers
+ */
+type ItemSelectionType = 'radio' | 'checkbox' | 'none';
+/**
+ * Configuration for a group of menu items.
+ * Groups are visually separated and can have different selection behaviors.
+ */
+type MenuGroup = {
+    /** Unique identifier for the group */
+    id: string;
+    /** Optional label displayed above the group */
+    label?: string;
+    /** Array of menu items in this group */
+    items: MenuItem[];
+    /** Selection behavior for items in this group */
+    itemSelectionType: ItemSelectionType;
+    /** Whether to close menu when any item in group is clicked */
+    closeOnItemClick?: boolean;
+};
+/**
+ * Configuration for a menu component.
+ * Defines structure, behavior, and selection state.
+ */
+type MenuConfig = {
+    /** Whether to open menu on hover instead of click */
+    openOnHover?: boolean;
+    /** Array of menu groups */
+    groups: MenuGroup[];
+};
+/**
+ * Selected items state organized by group.
+ * Maps group ID to array of selected item IDs.
+ */
+type MenuSelection = Record<string, string[]>;
+/**
+ * Base props for the Menu component.
+ */
+interface MenuBaseProps extends Omit<BaseComponent<HTMLDivElement>, 'onChange'> {
+    /** Menu configuration object */
+    config: MenuConfig;
+    /** Currently selected items organized by group */
+    selectedItems?: MenuSelection;
+    /** Callback when selection changes */
+    onChange?: (selection: MenuSelection) => void;
+    /** Menu trigger element */
+    children?: React.ReactNode;
+    /** Custom icon for checkbox selected state */
+    checkboxIcon?: React.ReactNode;
+    /** Custom icon for radio selected state */
+    radioIcon?: React.ReactNode;
+    /** Whether the menu is disabled */
+    disabled?: boolean;
+    /** Whether this menu is a submenu */
+    isSubmenu?: boolean;
+}
+/**
+ * Props for the Menu component using Prettify utility type.
+ */
+type MenuProps = Prettify<MenuBaseProps>;
+
+export type { ItemSelectionType, MenuBaseProps, MenuConfig, MenuGroup, MenuItem, MenuProps, MenuSelection, SubmenuTrigger };

package/dist/types/components/navigation/Menu/useMenu.d.ts

@@ -0,0 +1,16 @@
+import { MenuSelection, MenuGroup } from './Menu.types.js';
+
+/**
+ * Hook for managing menu selection state and interactions.
+ * Handles radio/checkbox logic, state updates, and submenu visibility.
+ */
+declare const useMenu: (selectedItems?: MenuSelection, onChange?: (selection: MenuSelection) => void) => {
+    handleItemClick: (groupId: string, itemId: string, group: MenuGroup) => void;
+    isItemSelected: (groupId: string, itemId: string) => boolean;
+    toggleSubmenu: (itemId: string) => void;
+    openSubmenu: (itemId: string) => void;
+    closeSubmenu: (itemId: string) => void;
+    isSubmenuOpen: (itemId: string) => boolean;
+};
+
+export { useMenu };

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

@@ -0,0 +1,6 @@
+import React from 'react';
+import { TabProps } from './Tabs.types.js';
+
+declare const Tab: React.FC<TabProps>;
+
+export { Tab };

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

@@ -0,0 +1,6 @@
+import React from 'react';
+import { TabListProps } from './Tabs.types.js';
+
+declare const TabList: React.FC<TabListProps>;
+
+export { TabList };

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

@@ -0,0 +1,6 @@
+import React from 'react';
+import { TabPanelProps } from './Tabs.types.js';
+
+declare const TabPanel: React.FC<TabPanelProps>;
+
+export { TabPanel };

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

@@ -0,0 +1,23 @@
+import React from 'react';
+import { TabsProps } from './Tabs.types.js';
+
+/**
+ * Tabs component for switching between views within a panel.
+ *
+ * Compound component pattern: use with TabList, Tab, and TabPanel.
+ *
+ * @example
+ * ```tsx
+ * <Tabs defaultValue="properties">
+ *   <TabList>
+ *     <Tab value="properties">Properties</Tab>
+ *     <Tab value="materials">Materials</Tab>
+ *   </TabList>
+ *   <TabPanel value="properties">Properties content</TabPanel>
+ *   <TabPanel value="materials">Materials content</TabPanel>
+ * </Tabs>
+ * ```
+ */
+declare const Tabs: React.FC<TabsProps>;
+
+export { Tabs };

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

@@ -0,0 +1,117 @@
+import React from 'react';
+import { Prettify } from '../../../types/utilities.js';
+import { BaseComponent, Size } from '../../../types/common.js';
+
+type TabsSize = Size;
+/**
+ * Visual variants for the tab list
+ * - `underline`: Bottom border indicator (default, like VS Code tabs)
+ * - `pills`: Filled background on active tab
+ * - `enclosed`: Bordered active tab with connected panel
+ */
+type TabsVariant = 'underline' | 'pills' | 'enclosed';
+interface TabsBaseProps extends Omit<BaseComponent, 'onChange'> {
+    /**
+     * Currently active tab value (controlled)
+     */
+    value?: string;
+    /**
+     * Default active tab (uncontrolled)
+     */
+    defaultValue?: string;
+    /**
+     * Tab list variant
+     * @default "underline"
+     */
+    variant?: TabsVariant;
+    /**
+     * Tab size
+     * - `sm`: 24px tab height, ultra-compact panels
+     * - `md`: 28px tab height, compact default
+     * - `lg`: 32px tab height, comfortable navigation
+     * @default "md"
+     */
+    size?: TabsSize;
+    /**
+     * Orientation of the tab list
+     * @default "horizontal"
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Whether tabs fill the available width equally
+     * @default false
+     */
+    fullWidth?: boolean;
+    /**
+     * Whether pills variant renders a framed tab-list container.
+     * When false, pills tabs render without surrounding border/background.
+     * @default true
+     */
+    pillsFrame?: boolean;
+    /**
+     * Children: TabList + TabPanel components
+     */
+    children: React.ReactNode;
+    /**
+     * Callback when active tab changes
+     */
+    onChange?: (value: string) => void;
+}
+type TabsProps = Prettify<TabsBaseProps>;
+interface TabListBaseProps extends BaseComponent {
+    /**
+     * Tab elements
+     */
+    children: React.ReactNode;
+}
+type TabListProps = Prettify<TabListBaseProps>;
+interface TabBaseProps extends BaseComponent<HTMLButtonElement> {
+    /**
+     * Unique value identifying this tab.
+     * Must match a TabPanel's value.
+     */
+    value: string;
+    /**
+     * Tab label content
+     */
+    children: React.ReactNode;
+    /**
+     * Icon displayed before the label
+     */
+    icon?: React.ReactNode;
+    /**
+     * Whether this tab is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Whether this tab can be closed
+     * @default false
+     */
+    closable?: boolean;
+    /**
+     * Callback when close button is clicked.
+     * Only relevant when closable is true.
+     */
+    onClose?: (value: string) => void;
+}
+type TabProps = Prettify<TabBaseProps>;
+interface TabPanelBaseProps extends BaseComponent {
+    /**
+     * Value matching a Tab's value
+     */
+    value: string;
+    /**
+     * Panel content — only rendered when this tab is active
+     */
+    children: React.ReactNode;
+    /**
+     * Whether to keep panel mounted when inactive (preserves state).
+     * When false, panel is unmounted when not active.
+     * @default false
+     */
+    keepMounted?: boolean;
+}
+type TabPanelProps = Prettify<TabPanelBaseProps>;
+
+export type { TabBaseProps, TabListBaseProps, TabListProps, TabPanelBaseProps, TabPanelProps, TabProps, TabsBaseProps, TabsProps, TabsSize, TabsVariant };