@mks2508/mks-ui 0.1.3 → 0.2.0

package/src/react/ui/Menu/Menu.types.ts

@@ -0,0 +1,425 @@
+/**
+ * Type definitions for the Menu component.
+ *
+ * All interfaces use the IPrefix convention. Type aliases do not.
+ * This module re-exports relevant types from base-ui and motion
+ * combined with the v0.2.0 SlotOverrides/IBaseConfig pattern.
+ *
+ * @module @mks2508/mks-ui/react/ui/Menu/Menu.types
+ */
+
+import type * as React from 'react';
+import type { Menu as MenuPrimitive } from '@base-ui/react/menu';
+import type { HTMLMotionProps, Transition } from 'motion/react';
+
+import type { IBaseConfig, SlotOverrides } from '@/core/types';
+import type { IHighlightProps, IHighlightItemProps } from '@/react/primitives/Highlight';
+import type { MenuSlot } from './Menu.styles';
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration interface for Menu behavior and animation.
+ *
+ * @example
+ * ```tsx
+ * const config: IMenuConfig = {
+ *   animation: { duration: 0.2, easing: 'ease-out' },
+ * };
+ * ```
+ */
+export interface IMenuConfig extends IBaseConfig {
+  /** Default motion transition for the popup entrance/exit. */
+  popupTransition?: Transition;
+}
+
+// ---------------------------------------------------------------------------
+// Context types (type aliases -- no IPrefix)
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal context carrying the highlighted (focused) item value.
+ *
+ * @example
+ * ```typescript
+ * const ctx: MenuActiveValueContextType = {
+ *   highlightedValue: 'edit',
+ *   setHighlightedValue: (v) => {},
+ * };
+ * ```
+ */
+export type MenuActiveValueContextType = {
+  /** Currently highlighted item value, or null if none. */
+  highlightedValue: string | null;
+  /** Setter for the highlighted item value. */
+  setHighlightedValue: (value: string | null) => void;
+};
+
+/**
+ * Internal context for Menu open/close state.
+ *
+ * @example
+ * ```typescript
+ * const ctx: MenuContextType = { isOpen: true, setIsOpen: (v) => {} };
+ * ```
+ */
+export type MenuContextType = {
+  /** Whether the menu is open. */
+  isOpen: boolean | undefined;
+  /** Setter for open state, matching base-ui's onOpenChange signature. */
+  setIsOpen: IMenuProps['onOpenChange'];
+};
+
+// ---------------------------------------------------------------------------
+// Root
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for the root Menu component.
+ * Extends base-ui Menu.Root props with slot overrides and config.
+ *
+ * @example
+ * ```tsx
+ * <Menu slots={{ popup: 'bg-zinc-900' }} config={{ popupTransition: { duration: 0.3 } }}>
+ *   ...
+ * </Menu>
+ * ```
+ */
+export interface IMenuProps extends React.ComponentProps<typeof MenuPrimitive.Root> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+  /** Menu behavior / animation configuration. */
+  config?: IMenuConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Trigger
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for MenuTrigger -- the element that opens the menu.
+ *
+ * @example
+ * ```tsx
+ * <MenuTrigger className="px-3 py-2">Open</MenuTrigger>
+ * ```
+ */
+export interface IMenuTriggerProps
+  extends React.ComponentProps<typeof MenuPrimitive.Trigger> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}
+
+// ---------------------------------------------------------------------------
+// Portal
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for MenuPortal. Wraps AnimatePresence for enter/exit transitions.
+ * The `keepMounted` prop is managed internally.
+ *
+ * @example
+ * ```tsx
+ * <MenuPortal>
+ *   <MenuPositioner>...</MenuPositioner>
+ * </MenuPortal>
+ * ```
+ */
+export interface IMenuPortalProps
+  extends Omit<React.ComponentProps<typeof MenuPrimitive.Portal>, 'keepMounted'> {}
+
+// ---------------------------------------------------------------------------
+// Group / GroupLabel
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for MenuGroup -- groups related items with a label.
+ *
+ * @example
+ * ```tsx
+ * <MenuGroup>
+ *   <MenuGroupLabel>Actions</MenuGroupLabel>
+ *   <MenuItem>Edit</MenuItem>
+ * </MenuGroup>
+ * ```
+ */
+export interface IMenuGroupProps
+  extends React.ComponentProps<typeof MenuPrimitive.Group> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}
+
+/**
+ * Props for MenuGroupLabel -- the label rendered above a group.
+ *
+ * @example
+ * ```tsx
+ * <MenuGroupLabel className="text-xs uppercase">Section</MenuGroupLabel>
+ * ```
+ */
+export interface IMenuGroupLabelProps
+  extends React.ComponentProps<typeof MenuPrimitive.GroupLabel> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}
+
+// ---------------------------------------------------------------------------
+// Submenu
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for MenuSubmenu -- a nested menu with its own open state.
+ *
+ * @example
+ * ```tsx
+ * <MenuSubmenu>
+ *   <MenuSubmenuTrigger>More...</MenuSubmenuTrigger>
+ *   <MenuPortal>...</MenuPortal>
+ * </MenuSubmenu>
+ * ```
+ */
+export interface IMenuSubmenuProps
+  extends React.ComponentProps<typeof MenuPrimitive.SubmenuRoot> {}
+
+/**
+ * Props for MenuSubmenuTrigger -- the item that opens a submenu.
+ * Combines base-ui's SubmenuTrigger props with motion HTML props.
+ *
+ * @example
+ * ```tsx
+ * <MenuSubmenuTrigger id="more-actions">More...</MenuSubmenuTrigger>
+ * ```
+ */
+export interface IMenuSubmenuTriggerProps
+  extends Omit<Omit<React.ComponentProps<typeof MenuPrimitive.SubmenuTrigger>, 'render'>, keyof HTMLMotionProps<'div'>>,
+    HTMLMotionProps<'div'> {
+  /** Whether the trigger is disabled. */
+  disabled?: boolean;
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}
+
+// ---------------------------------------------------------------------------
+// Highlight
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for MenuHighlight -- animated background that follows the focused item.
+ * Wraps the Highlight primitive with menu-specific defaults.
+ *
+ * @example
+ * ```tsx
+ * <MenuHighlight className="rounded-md bg-white/10" />
+ * ```
+ */
+export interface IMenuHighlightProps
+  extends Omit<IHighlightProps, 'controlledItems' | 'enabled' | 'hover'> {
+  /** Whether to animate on hover. */
+  animateOnHover?: boolean;
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}
+
+/**
+ * Props for MenuHighlightItem -- wraps a menu item for highlight tracking.
+ *
+ * @example
+ * ```tsx
+ * <MenuHighlightItem>
+ *   <MenuItem>Edit</MenuItem>
+ * </MenuHighlightItem>
+ * ```
+ */
+export interface IMenuHighlightItemProps extends IHighlightItemProps {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}
+
+// ---------------------------------------------------------------------------
+// Positioner / Popup
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for MenuPositioner -- positions the popup relative to the trigger.
+ *
+ * @example
+ * ```tsx
+ * <MenuPositioner sideOffset={8} align="start">
+ *   <MenuPopup>...</MenuPopup>
+ * </MenuPositioner>
+ * ```
+ */
+export interface IMenuPositionerProps
+  extends React.ComponentProps<typeof MenuPrimitive.Positioner> {}
+
+/**
+ * Props for MenuPopup -- the visible flyout container.
+ * Combines base-ui Popup with motion HTML props for animated entrance.
+ *
+ * @example
+ * ```tsx
+ * <MenuPopup className="rounded-lg border shadow-lg">
+ *   <MenuItem>Edit</MenuItem>
+ * </MenuPopup>
+ * ```
+ */
+export interface IMenuPopupProps
+  extends Omit<Omit<React.ComponentProps<typeof MenuPrimitive.Popup>, 'render'>, keyof HTMLMotionProps<'div'>>,
+    HTMLMotionProps<'div'> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}
+
+// ---------------------------------------------------------------------------
+// Item
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for MenuItem -- a single actionable row in the menu.
+ * Combines base-ui Item with motion HTML props.
+ *
+ * @example
+ * ```tsx
+ * <MenuItem id="edit" label="Edit">
+ *   <PencilIcon /> Edit
+ * </MenuItem>
+ * ```
+ */
+export interface IMenuItemProps
+  extends Omit<Omit<React.ComponentProps<typeof MenuPrimitive.Item>, 'render'>, keyof HTMLMotionProps<'div'>>,
+    HTMLMotionProps<'div'> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}
+
+// ---------------------------------------------------------------------------
+// Checkbox Item
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for MenuCheckboxItem -- a toggleable checkbox menu item.
+ *
+ * @example
+ * ```tsx
+ * <MenuCheckboxItem checked={showGrid} onCheckedChange={setShowGrid}>
+ *   Show Grid
+ * </MenuCheckboxItem>
+ * ```
+ */
+export interface IMenuCheckboxItemProps
+  extends Omit<React.ComponentProps<typeof MenuPrimitive.CheckboxItem>, 'render'> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}
+
+/**
+ * Props for MenuCheckboxItemIndicator -- the check/indeterminate indicator.
+ * Combines base-ui CheckboxItemIndicator with motion HTML props.
+ *
+ * @example
+ * ```tsx
+ * <MenuCheckboxItemIndicator>
+ *   <CheckIcon />
+ * </MenuCheckboxItemIndicator>
+ * ```
+ */
+export interface IMenuCheckboxItemIndicatorProps
+  extends Omit<
+      Omit<React.ComponentProps<typeof MenuPrimitive.CheckboxItemIndicator>, 'render'>,
+      keyof HTMLMotionProps<'div'>
+    >,
+    HTMLMotionProps<'div'> {}
+
+// ---------------------------------------------------------------------------
+// Radio Group / Radio Item
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for MenuRadioGroup -- groups radio items for single-selection.
+ *
+ * @example
+ * ```tsx
+ * <MenuRadioGroup value={sortBy} onValueChange={setSortBy}>
+ *   <MenuRadioItem value="name">Name</MenuRadioItem>
+ *   <MenuRadioItem value="date">Date</MenuRadioItem>
+ * </MenuRadioGroup>
+ * ```
+ */
+export interface IMenuRadioGroupProps
+  extends React.ComponentProps<typeof MenuPrimitive.RadioGroup> {}
+
+/**
+ * Props for MenuRadioItem -- a single option within a radio group.
+ *
+ * @example
+ * ```tsx
+ * <MenuRadioItem value="name">Sort by Name</MenuRadioItem>
+ * ```
+ */
+export interface IMenuRadioItemProps
+  extends Omit<React.ComponentProps<typeof MenuPrimitive.RadioItem>, 'render'> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}
+
+/**
+ * Props for MenuRadioItemIndicator -- the selection indicator dot/icon.
+ * Combines base-ui RadioItemIndicator with motion HTML props.
+ *
+ * @example
+ * ```tsx
+ * <MenuRadioItemIndicator>
+ *   <DotIcon />
+ * </MenuRadioItemIndicator>
+ * ```
+ */
+export interface IMenuRadioItemIndicatorProps
+  extends Omit<
+      Omit<React.ComponentProps<typeof MenuPrimitive.RadioItemIndicator>, 'render'>,
+      keyof HTMLMotionProps<'div'>
+    >,
+    HTMLMotionProps<'div'> {}
+
+// ---------------------------------------------------------------------------
+// Shortcut / Arrow / Separator
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for MenuShortcut -- displays a keyboard shortcut hint.
+ *
+ * @example
+ * ```tsx
+ * <MenuShortcut>Ctrl+C</MenuShortcut>
+ * ```
+ */
+export interface IMenuShortcutProps extends React.ComponentProps<'span'> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}
+
+/**
+ * Props for MenuArrow -- the directional arrow/caret of the popup.
+ *
+ * @example
+ * ```tsx
+ * <MenuArrow className="fill-zinc-800" />
+ * ```
+ */
+export interface IMenuArrowProps
+  extends React.ComponentProps<typeof MenuPrimitive.Arrow> {}
+
+/**
+ * Props for MenuSeparator -- a horizontal divider between items.
+ *
+ * @example
+ * ```tsx
+ * <MenuSeparator className="my-1 border-white/10" />
+ * ```
+ */
+export interface IMenuSeparatorProps
+  extends React.ComponentProps<typeof MenuPrimitive.Separator> {
+  /** Partial class overrides per slot. */
+  slots?: SlotOverrides<MenuSlot>;
+}