@aleph-alpha/ui-library 1.8.0 → 1.10.0

package/src/primitives/UiDropdownMenu/types.ts

@@ -0,0 +1,219 @@
+/**
+ * A menu that appears on trigger click with actions and options. Use for
+ * context menus, action lists, or any menu triggered by a button.
+ *
+ * @category Overlays
+ * @useCases action menu, context menu, options list, user menu, settings menu
+ * @keywords dropdown, menu, actions, options, context, popover, list
+ * @related UiPopover, UiSelect
+ */
+export interface UiDropdownMenuProps {
+  /**
+   * The controlled open state of the dropdown menu.
+   * Must be used in conjunction with `update:open`.
+   */
+  open?: boolean;
+
+  /**
+   * The modality of the dropdown menu.
+   * When set to `true`, interaction with outside elements will be disabled
+   * and only menu content will be visible to screen readers.
+   * @default true
+   */
+  modal?: boolean;
+}
+
+export interface UiDropdownMenuEmits {
+  /**
+   * Event emitted when the open state changes.
+   */
+  'update:open': [value: boolean];
+}
+
+export interface UiDropdownMenuTriggerProps {
+  /**
+   * Accessible label for the trigger button.
+   * **REQUIRED** when trigger contains only icons or images (no visible text).
+   * Applied as `aria-label` attribute.
+   */
+  ariaLabel?: string;
+
+  /**
+   * Whether the trigger is disabled.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Render as child element (merges props into slotted element instead of wrapping).
+   * Set to `true` when using custom button components like `UiButton` or `UiIconButton`.
+   * @default false
+   */
+  asChild?: boolean;
+}
+
+export interface UiDropdownMenuContentProps {
+  /**
+   * The preferred side of the trigger to render against when open.
+   * @default 'bottom'
+   */
+  side?: 'top' | 'right' | 'bottom' | 'left';
+
+  /**
+   * The distance in pixels from the trigger.
+   * @default 4
+   */
+  sideOffset?: number;
+
+  /**
+   * The preferred alignment against the trigger.
+   * @default 'start'
+   */
+  align?: 'start' | 'center' | 'end';
+}
+
+export interface UiDropdownMenuContentEmits {
+  /**
+   * Event emitted when the escape key is pressed.
+   * Can be used to prevent closing or add custom behavior.
+   */
+  (e: 'escapeKeyDown', event: KeyboardEvent): void;
+}
+
+export interface UiDropdownMenuItemProps {
+  /**
+   * Visual variant of the menu item.
+   * @default 'default'
+   */
+  variant?: 'default' | 'destructive';
+
+  /**
+   * Whether the item is disabled.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Whether to add extra left padding (for items under a label).
+   * @default false
+   */
+  inset?: boolean;
+
+  /**
+   * Optional text used for typeahead purposes.
+   * Useful when the item contains icons or complex content.
+   */
+  textValue?: string;
+}
+
+export interface UiDropdownMenuLabelProps {
+  /**
+   * Whether to add extra left padding (for items under a label).
+   * @default false
+   */
+  inset?: boolean;
+}
+
+export interface UiDropdownMenuCheckboxItemProps {
+  /**
+   * The controlled checked state of the checkbox item.
+   * Use with v-model:checked
+   */
+  checked?: boolean;
+
+  /**
+   * Whether the checkbox item is disabled.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Optional text used for typeahead purposes.
+   */
+  textValue?: string;
+}
+
+export interface UiDropdownMenuCheckboxItemEmits {
+  'update:checked': [value: boolean];
+}
+
+export interface UiDropdownMenuRadioGroupProps {
+  /**
+   * The value of the selected radio item.
+   * Use with v-model
+   */
+  modelValue?: string;
+}
+
+export interface UiDropdownMenuRadioGroupEmits {
+  'update:modelValue': [value: string];
+}
+
+export interface UiDropdownMenuRadioItemProps {
+  /**
+   * The unique value of the radio item.
+   */
+  value: string;
+
+  /**
+   * Whether the radio item is disabled.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Optional text used for typeahead purposes.
+   */
+  textValue?: string;
+}
+
+export interface UiDropdownMenuSubProps {
+  /**
+   * The controlled open state of the submenu.
+   */
+  open?: boolean;
+
+  /**
+   * The open state of the submenu when it is initially rendered.
+   */
+  defaultOpen?: boolean;
+}
+
+export interface UiDropdownMenuSubEmits {
+  'update:open': [value: boolean];
+}
+
+export interface UiDropdownMenuSubTriggerProps {
+  /**
+   * Whether the sub trigger is disabled.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Whether to add extra left padding.
+   * @default false
+   */
+  inset?: boolean;
+
+  /**
+   * Optional text used for typeahead purposes.
+   */
+  textValue?: string;
+}
+
+export interface UiDropdownMenuSubContentProps {
+  /**
+   * The distance in pixels from the trigger.
+   * @default 0
+   */
+  sideOffset?: number;
+}
+
+export interface UiDropdownMenuSubContentEmits {
+  /**
+   * Event emitted when the escape key is pressed.
+   * Can be used to prevent closing or add custom behavior.
+   */
+  (e: 'escapeKeyDown', event: KeyboardEvent): void;
+}