@mks2508/mks-ui 0.1.4 → 0.2.1

package/src/react-ui/ui/Popover/Popover.styles.ts

@@ -0,0 +1,55 @@
+/**
+ * Style definitions for the Popover component.
+ *
+ * Provides StyleSlots for each visual region. Uses only CSS variable
+ * utilities; never hard-coded color values.
+ *
+ * @module @mks2508/mks-ui/react/ui/Popover/Popover.styles
+ */
+
+import type { StyleSlots } from '@/core/types';
+import type { PopoverSlot } from './Popover.types';
+
+/**
+ * Default Tailwind classes for each Popover visual region.
+ * Consumers override via the `slots` prop; the merge order is:
+ * `base -> slots -> className`.
+ *
+ * @example
+ * ```typescript
+ * import { popoverStyles } from './Popover.styles';
+ * // popoverStyles.popup => 'z-50 w-72 rounded-md border ...'
+ * ```
+ */
+export const popoverStyles: StyleSlots<PopoverSlot> = {
+  /** Root wrapper — no visual styling by default. */
+  root: '',
+
+  /** Popup content container. */
+  popup: [
+    'z-50 w-72 rounded-md border border-border',
+    'bg-popover p-4 text-popover-foreground shadow-md outline-none',
+  ].join(' '),
+
+  /** Trigger element — no default styling. */
+  trigger: '',
+
+  /** Positioner wrapper — handles absolute placement. */
+  positioner: '',
+
+  /** Optional backdrop overlay. */
+  backdrop: 'fixed inset-0',
+
+  /** Directional arrow pointing toward the trigger. */
+  arrow: 'fill-popover',
+
+  /** Popover title text. */
+  title: 'font-medium leading-none text-foreground',
+
+  /** Popover description text. */
+  description: 'text-sm text-muted-foreground',
+
+  /** Close button. */
+  close:
+    'rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2',
+};

package/src/react-ui/ui/Popover/Popover.types.ts

@@ -0,0 +1,261 @@
+/**
+ * Type definitions for the Popover component.
+ *
+ * Provides all prop interfaces, slot types, context types, and configuration
+ * for the animated popover system built on Base UI and Motion.
+ *
+ * @module @mks2508/mks-ui/react/ui/Popover/Popover.types
+ */
+
+import type * as React from 'react';
+import type { Popover as PopoverPrimitive } from '@base-ui/react/popover';
+import type { HTMLMotionProps } from 'motion/react';
+
+import type { SlotOverrides, IBaseConfig } from '@/core/types';
+
+/* -------------------------------------------------------------------------- */
+/*  Slot                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Visual regions available for class-name overrides via the `slots` prop.
+ *
+ * @example
+ * ```tsx
+ * <PopoverPopup slots={{ popup: 'rounded-xl shadow-xl', arrow: 'fill-popover' }} />
+ * ```
+ */
+export type PopoverSlot =
+  | 'root'
+  | 'popup'
+  | 'trigger'
+  | 'positioner'
+  | 'backdrop'
+  | 'arrow'
+  | 'title'
+  | 'description'
+  | 'close';
+
+/* -------------------------------------------------------------------------- */
+/*  Config                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Extended configuration for the Popover component.
+ * Inherits base animation settings and adds popover-specific options.
+ *
+ * @example
+ * ```typescript
+ * const config: IPopoverConfig = {
+ *   animation: { duration: 0.25, easing: 'ease-out' },
+ * };
+ * ```
+ */
+export interface IPopoverConfig extends IBaseConfig {
+  // Reserved for future popover-specific config.
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Context                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Internal context type shared between Popover sub-components.
+ * Tracks open state so AnimatePresence can coordinate enter/exit animations.
+ *
+ * @example
+ * ```tsx
+ * const { isOpen, setIsOpen } = usePopover();
+ * ```
+ */
+export type PopoverContextType = {
+  /** Whether the popover is currently open. */
+  isOpen: boolean;
+  /** Callback to change the open state. */
+  setIsOpen: IPopoverProps['onOpenChange'];
+};
+
+/* -------------------------------------------------------------------------- */
+/*  Props interfaces                                                          */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Props for the root `Popover` component.
+ * Wraps Base UI Popover.Root with controlled-state support and context provider.
+ *
+ * @example
+ * ```tsx
+ * <Popover open={isOpen} onOpenChange={setIsOpen}>
+ *   <PopoverTrigger>Toggle</PopoverTrigger>
+ *   <PopoverPortal>
+ *     <PopoverPositioner>
+ *       <PopoverPopup>Content here</PopoverPopup>
+ *     </PopoverPositioner>
+ *   </PopoverPortal>
+ * </Popover>
+ * ```
+ */
+export interface IPopoverProps
+  extends React.ComponentProps<typeof PopoverPrimitive.Root> {
+  /** Style slot overrides for the root wrapper. */
+  slots?: SlotOverrides<PopoverSlot>;
+  /** Component configuration. */
+  config?: IPopoverConfig;
+}
+
+/**
+ * Props for the `PopoverTrigger` component.
+ * Renders the element that toggles the popover on interaction.
+ *
+ * @example
+ * ```tsx
+ * <PopoverTrigger>
+ *   <Button>Show info</Button>
+ * </PopoverTrigger>
+ * ```
+ */
+export interface IPopoverTriggerProps
+  extends React.ComponentProps<typeof PopoverPrimitive.Trigger> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<PopoverSlot>;
+}
+
+/**
+ * Props for the `PopoverPortal` component.
+ * Renders children into a React portal with AnimatePresence for exit animations.
+ * The `keepMounted` prop is handled internally and cannot be overridden.
+ *
+ * @example
+ * ```tsx
+ * <PopoverPortal>
+ *   <PopoverPositioner>
+ *     <PopoverPopup>...</PopoverPopup>
+ *   </PopoverPositioner>
+ * </PopoverPortal>
+ * ```
+ */
+export interface IPopoverPortalProps
+  extends Omit<
+    React.ComponentProps<typeof PopoverPrimitive.Portal>,
+    'keepMounted'
+  > {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<PopoverSlot>;
+}
+
+/**
+ * Props for the `PopoverPositioner` component.
+ * Handles automatic positioning relative to the trigger.
+ *
+ * @example
+ * ```tsx
+ * <PopoverPositioner sideOffset={8}>
+ *   <PopoverPopup>Content</PopoverPopup>
+ * </PopoverPositioner>
+ * ```
+ */
+export interface IPopoverPositionerProps
+  extends React.ComponentProps<typeof PopoverPrimitive.Positioner> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<PopoverSlot>;
+}
+
+/**
+ * Props for the `PopoverPopup` component.
+ * The main content container with scale entrance animation.
+ * Accepts all HTMLMotionProps for full animation control.
+ *
+ * @example
+ * ```tsx
+ * <PopoverPopup className="p-4 rounded-lg">
+ *   <PopoverTitle>Info</PopoverTitle>
+ *   <PopoverDescription>Details here.</PopoverDescription>
+ * </PopoverPopup>
+ * ```
+ */
+export interface IPopoverPopupProps
+  extends Omit<
+      Omit<React.ComponentProps<typeof PopoverPrimitive.Popup>, 'render'>,
+      keyof HTMLMotionProps<'div'>
+    >,
+    HTMLMotionProps<'div'> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<PopoverSlot>;
+}
+
+/**
+ * Props for the `PopoverBackdrop` component.
+ * Optional overlay rendered behind the popover.
+ *
+ * @example
+ * ```tsx
+ * <PopoverBackdrop className="bg-black/20" />
+ * ```
+ */
+export interface IPopoverBackdropProps
+  extends React.ComponentProps<typeof PopoverPrimitive.Backdrop> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<PopoverSlot>;
+}
+
+/**
+ * Props for the `PopoverArrow` component.
+ * Renders a directional arrow pointing toward the trigger.
+ *
+ * @example
+ * ```tsx
+ * <PopoverArrow className="fill-popover" />
+ * ```
+ */
+export interface IPopoverArrowProps
+  extends React.ComponentProps<typeof PopoverPrimitive.Arrow> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<PopoverSlot>;
+}
+
+/**
+ * Props for the `PopoverTitle` component.
+ * Renders the accessible title for the popover.
+ *
+ * @example
+ * ```tsx
+ * <PopoverTitle>Quick Info</PopoverTitle>
+ * ```
+ */
+export interface IPopoverTitleProps
+  extends React.ComponentProps<typeof PopoverPrimitive.Title> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<PopoverSlot>;
+}
+
+/**
+ * Props for the `PopoverDescription` component.
+ * Renders the accessible description for the popover.
+ *
+ * @example
+ * ```tsx
+ * <PopoverDescription>Additional details about this item.</PopoverDescription>
+ * ```
+ */
+export interface IPopoverDescriptionProps
+  extends React.ComponentProps<typeof PopoverPrimitive.Description> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<PopoverSlot>;
+}
+
+/**
+ * Props for the `PopoverClose` component.
+ * Renders a button that closes the popover when clicked.
+ *
+ * @example
+ * ```tsx
+ * <PopoverClose>
+ *   <button aria-label="Close">X</button>
+ * </PopoverClose>
+ * ```
+ */
+export interface IPopoverCloseProps
+  extends React.ComponentProps<typeof PopoverPrimitive.Close> {
+  /** Style slot overrides. */
+  slots?: SlotOverrides<PopoverSlot>;
+}