sdaia-ui 1.0.1

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,398 @@
+'use client';
+
+import {
+  forwardRef,
+  useEffect,
+  useRef,
+  useState,
+  type FC,
+  type MutableRefObject,
+  type ReactNode,
+  type SVGProps,
+} from 'react';
+import { cn } from '../../lib/cn';
+import { Button } from '../Button';
+import { Link } from '../Link';
+import { CloseIcon, BeakUp, BeakDown, BeakLeft, BeakRight } from '../../icons/IconFactory';
+import type { PopoverProps } from './Popover.types';
+import {
+  PANEL_WRAPPER,
+  PANEL_BODY,
+  CONTENT_AREA,
+  TITLE_ROW,
+  TITLE_TEXT,
+  HELPER_TEXT,
+  SUPPORTING_TEXT,
+  FEATURED_ICON_WRAPPER,
+  FEATURED_ICON_SIZE,
+  IMAGE_WRAPPER,
+  CLOSE_BTN_POSITION,
+  CLOSE_BTN,
+  ACTIONS_ROW,
+  ACTIONS_FULL_WIDTH,
+  BEAK_COLOR,
+  PANEL_POSITION,
+  BEAK_DIRECTION,
+} from './Popover.variants';
+
+// ── Beak icon map ─────────────────────────────────────────────────────────────
+// Maps placement direction to the SVG beak that points *toward the trigger*.
+
+type BeakDir = 'col-start' | 'col-end' | 'row-start' | 'row-end';
+
+const BEAK_ICON: Record<BeakDir, FC<SVGProps<SVGSVGElement>>> = {
+  'col-start': BeakUp,    // panel below trigger → beak above panel (pointing up toward trigger)
+  'col-end':   BeakDown,  // panel above trigger → beak below panel (pointing down toward trigger)
+  'row-start': BeakLeft,  // panel to the right of trigger → beak on left side
+  'row-end':   BeakRight, // panel to the left of trigger → beak on right side
+};
+
+function getBeakContainerClass(dir: BeakDir): string {
+  switch (dir) {
+    case 'col-start': return 'flex items-center justify-center w-full order-first';
+    case 'col-end':   return 'flex items-center justify-center w-full order-last';
+    case 'row-start': return 'flex items-center justify-center self-center order-first';
+    case 'row-end':   return 'flex items-center justify-center self-center order-last';
+  }
+}
+
+function getPanelFlexClass(dir: BeakDir): string {
+  if (dir === 'row-start' || dir === 'row-end') return 'flex-row items-center';
+  return 'flex-col items-center';
+}
+
+// ── Instance row placeholder ──────────────────────────────────────────────────
+// Renders the Figma "Instance Slot" placeholder rectangles inline.
+function InstanceRowPlaceholders({ count }: { count: number }) {
+  const rows: ReactNode[] = [];
+  for (let i = 0; i < count; i++) {
+    rows.push(
+      <div
+        key={i}
+        className="w-full h-[40px] border border-dashed border-[#9747ff] bg-[rgba(151,71,255,0.05)] flex items-center justify-center"
+      >
+        <span className="text-[#9747ff] text-text-md whitespace-nowrap">
+          Instance Slot {i + 1}
+        </span>
+      </div>,
+    );
+  }
+  return <div className="flex flex-col gap-spacing-lg w-full">{rows}</div>;
+}
+
+// ── Component ─────────────────────────────────────────────────────────────────
+
+/**
+ * Popover — a floating panel attached to a trigger element.
+ *
+ * Supports:
+ * - Controlled (`open` + `onOpenChange`) and uncontrolled (`defaultOpen`) modes.
+ * - Custom `trigger` slot or built-in Button/Link trigger via `triggerType`.
+ * - 12 placement options with automatic beak direction.
+ * - Featured icon badge, title, helper text, supporting text, image, instance rows,
+ *   and a free-form children slot inside the panel body.
+ * - Primary + secondary action buttons with three alignment options.
+ * - Close button, click-outside-to-close, Escape key to close.
+ * - RTL-aware: placement `start`/`end`, close-button position, and title padding all flip.
+ * - Light and dark mode via design tokens.
+ */
+export const Popover = forwardRef<HTMLDivElement, PopoverProps>(function Popover(
+  {
+    // Trigger
+    trigger,
+    triggerType = 'button',
+    triggerLabel = 'Open',
+
+    // Placement
+    placement = 'bottom',
+    showBeak = true,
+
+    // Open state
+    open: openProp,
+    defaultOpen = false,
+    onOpenChange,
+
+    // Content slots
+    featuredIcon,
+    title,
+    helperText,
+    supportingText,
+    image,
+    imageAlt = '',
+    instanceRowCount = 0,
+    instanceRows,
+    children,
+
+    // Close button
+    showCloseButton = true,
+
+    // Actions
+    primaryActionLabel,
+    secondaryActionLabel,
+    onPrimaryAction,
+    onSecondaryAction,
+    actionsAlignment = 'start',
+
+    // RTL
+    dir,
+
+    className,
+    ...rest
+  },
+  ref,
+) {
+  /* ── Open state — controlled vs uncontrolled ──────────────────── */
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isControlled = openProp !== undefined;
+  const isOpen = isControlled ? openProp : internalOpen;
+
+  const toggle = (next: boolean) => {
+    if (!isControlled) setInternalOpen(next);
+    onOpenChange?.(next);
+  };
+
+  /* ── Click-outside and Escape-key to close ────────────────────── */
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handlePointerDown = (e: PointerEvent) => {
+      if (rootRef.current && !rootRef.current.contains(e.target as Node)) {
+        toggle(false);
+      }
+    };
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') toggle(false);
+    };
+
+    document.addEventListener('pointerdown', handlePointerDown);
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('pointerdown', handlePointerDown);
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isOpen]);
+
+  /* ── Merge refs ────────────────────────────────────────────────── */
+  const setRef = (node: HTMLDivElement | null) => {
+    rootRef.current = node;
+    if (typeof ref === 'function') {
+      ref(node);
+    } else if (ref) {
+      (ref as MutableRefObject<HTMLDivElement | null>).current = node;
+    }
+  };
+
+  /* ── Derived values ────────────────────────────────────────────── */
+  const hasActions = Boolean(primaryActionLabel);
+  const isFullWidth = ACTIONS_FULL_WIDTH[actionsAlignment];
+  const beakDir = BEAK_DIRECTION[placement];
+  const BeakIcon = BEAK_ICON[beakDir];
+
+  /* ── Image resolution — URL string or ReactNode ────────────────── */
+  const imageNode: ReactNode =
+    image == null
+      ? null
+      : typeof image === 'string'
+        ? <img src={image} alt={imageAlt} className="w-full h-full object-cover pointer-events-none" />
+        : image;
+
+  /* ── Panel ─────────────────────────────────────────────────────── */
+  const panel = isOpen ? (
+    <div
+      role="dialog"
+      aria-modal="false"
+      data-slot="popover-panel"
+      className={cn(
+        'motion-enter',
+        PANEL_WRAPPER,
+        PANEL_POSITION[placement],
+        getPanelFlexClass(beakDir),
+      )}
+    >
+      {/* Beak — rendered first or last depending on placement */}
+      {showBeak && (
+        <div
+          data-slot="popover-beak"
+          aria-hidden="true"
+          className={cn(getBeakContainerClass(beakDir), BEAK_COLOR)}
+        >
+          <BeakIcon />
+        </div>
+      )}
+
+      {/* Panel body */}
+      <div data-slot="popover-body" className={PANEL_BODY}>
+
+        {/* Close button — absolutely positioned in top-trailing corner */}
+        {showCloseButton && (
+          <button
+            type="button"
+            data-slot="popover-close"
+            aria-label="Close"
+            className={cn(CLOSE_BTN_POSITION, CLOSE_BTN)}
+            onClick={() => toggle(false)}
+          >
+            <CloseIcon width={16} height={16} aria-hidden="true" />
+          </button>
+        )}
+
+        {/* Content area */}
+        <div data-slot="popover-content" className={CONTENT_AREA}>
+
+          {/* Featured icon badge */}
+          {featuredIcon && (
+            <div data-slot="popover-featured-icon" className={FEATURED_ICON_WRAPPER}>
+              <span className={cn('inline-flex items-center justify-center', FEATURED_ICON_SIZE)}>
+                {featuredIcon}
+              </span>
+            </div>
+          )}
+
+          {/* Title row */}
+          {title && (
+            <div data-slot="popover-title-row" className={TITLE_ROW}>
+              <p data-slot="popover-title" className={TITLE_TEXT}>
+                {title}
+              </p>
+            </div>
+          )}
+
+          {/* Helper text */}
+          {helperText && (
+            <p data-slot="popover-helper-text" className={HELPER_TEXT}>
+              {helperText}
+            </p>
+          )}
+
+          {/* Supporting text */}
+          {supportingText && (
+            <p data-slot="popover-supporting-text" className={SUPPORTING_TEXT}>
+              {supportingText}
+            </p>
+          )}
+
+          {/* Image slot */}
+          {imageNode && (
+            <div data-slot="popover-image" className={IMAGE_WRAPPER}>
+              {imageNode}
+            </div>
+          )}
+
+          {/* Instance rows — either explicit ReactNode slot or placeholder count */}
+          {instanceRows && (
+            <div data-slot="popover-instance-rows" className="w-full">
+              {instanceRows}
+            </div>
+          )}
+          {!instanceRows && instanceRowCount > 0 && (
+            <div data-slot="popover-instance-rows" className="w-full">
+              <InstanceRowPlaceholders count={Math.min(Math.max(1, instanceRowCount), 9)} />
+            </div>
+          )}
+
+          {/* Free-form children slot */}
+          {children && (
+            <div data-slot="popover-slot" className="w-full">
+              {children}
+            </div>
+          )}
+        </div>
+
+        {/* Actions row */}
+        {hasActions && (
+          <div data-slot="popover-actions" className={ACTIONS_ROW[actionsAlignment]}>
+            <Button
+              variant="primary"
+              size="sm"
+              fullWidth={isFullWidth}
+              onClick={() => {
+                onPrimaryAction?.();
+                toggle(false);
+              }}
+            >
+              {primaryActionLabel}
+            </Button>
+
+            {secondaryActionLabel && (
+              <Button
+                variant="secondary-outline"
+                size="sm"
+                fullWidth={isFullWidth}
+                onClick={() => {
+                  onSecondaryAction?.();
+                  toggle(false);
+                }}
+              >
+                {secondaryActionLabel}
+              </Button>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  ) : null;
+
+  /* ── Trigger element ───────────────────────────────────────────── */
+  const builtInTrigger =
+    triggerType === 'link' ? (
+      <Link
+        variant="primary"
+        inline
+        href="#"
+        onClick={(e) => {
+          e.preventDefault();
+          toggle(!isOpen);
+        }}
+      >
+        {triggerLabel}
+      </Link>
+    ) : (
+      <Button
+        variant="primary"
+        size="md"
+        selected={isOpen}
+        aria-expanded={isOpen}
+        aria-haspopup="dialog"
+        onClick={() => toggle(!isOpen)}
+      >
+        {triggerLabel}
+      </Button>
+    );
+
+  const triggerEl = trigger ?? builtInTrigger;
+
+  return (
+    <div
+      ref={setRef}
+      data-slot="popover"
+      data-placement={placement}
+      data-open={isOpen || undefined}
+      dir={dir}
+      className={cn('relative inline-flex items-center justify-center', className)}
+      {...rest}
+    >
+      {/* Trigger */}
+      {trigger ? (
+        /* Custom trigger: wrap in a click handler */
+        <div
+          data-slot="popover-trigger"
+          className="cursor-pointer"
+          onClick={() => toggle(!isOpen)}
+        >
+          {triggerEl}
+        </div>
+      ) : (
+        /* Built-in trigger: click is handled inside the element itself */
+        <div data-slot="popover-trigger">
+          {triggerEl}
+        </div>
+      )}
+
+      {/* Floating panel */}
+      {panel}
+    </div>
+  );
+});

package/src/components/Popover/Popover.types.ts

@@ -0,0 +1,155 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+
+// ── Placement ─────────────────────────────────────────────────────────────────
+
+/**
+ * Where the popover panel appears relative to its trigger.
+ *
+ * - `top` / `bottom`        — panel centered on the trigger horizontally.
+ * - `*-start` / `*-end`     — panel aligned to the leading / trailing edge.
+ * - `left` / `right` (and variants) — panel placed to the side of the trigger.
+ *
+ * In RTL mode `start` and `end` are automatically mirrored.
+ */
+export type PopoverPlacement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end';
+
+// ── Actions alignment ─────────────────────────────────────────────────────────
+
+/**
+ * How action buttons are laid out in the panel footer.
+ *
+ * - `start`  — buttons sit at the leading edge (natural width).
+ * - `center` — buttons expand equally to fill the row.
+ * - `end`    — buttons sit at the trailing edge (natural width).
+ */
+export type PopoverActionsAlignment = 'start' | 'center' | 'end';
+
+// ── Trigger type ──────────────────────────────────────────────────────────────
+
+/** Whether the default built-in trigger is a Button or a Link. */
+export type PopoverTriggerType = 'button' | 'link';
+
+// ── Props ─────────────────────────────────────────────────────────────────────
+
+export interface PopoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  // ── Controlled / uncontrolled open state ─────────────────────────────────
+
+  /** Whether the popover panel is visible (controlled mode). */
+  open?: boolean;
+
+  /** Initial open state for uncontrolled mode. @default false */
+  defaultOpen?: boolean;
+
+  /** Called when the open state changes (close button click, outside click, Escape). */
+  onOpenChange?: (open: boolean) => void;
+
+  // ── Trigger slot ─────────────────────────────────────────────────────────
+
+  /**
+   * The element that opens/closes the popover on click.
+   * When omitted, a default trigger is rendered based on `triggerType`.
+   */
+  trigger?: ReactNode;
+
+  /**
+   * Whether the default built-in trigger is a Button or a Link.
+   * Only used when `trigger` is not provided.
+   * @default 'button'
+   */
+  triggerType?: PopoverTriggerType;
+
+  /**
+   * Label on the default trigger element.
+   * Only used when `trigger` is not provided.
+   * @default 'Open'
+   */
+  triggerLabel?: string;
+
+  // ── Panel content — named slots ───────────────────────────────────────────
+
+  /** Custom circular-badge icon shown above the title in the panel. */
+  featuredIcon?: ReactNode;
+
+  /** Semibold title text at the top of the panel body. */
+  title?: string;
+
+  /** Primary body text (text-sm / regular). */
+  helperText?: ReactNode;
+
+  /** Secondary body text (text-xs / regular, muted). */
+  supportingText?: ReactNode;
+
+  /**
+   * Image content rendered between supporting text and instance rows.
+   *
+   * Accepts either:
+   * - A `string` URL (rendered as `<img src={...} />`), or
+   * - A `ReactNode` (e.g. a pre-composed `<img>` or `<Image>` component).
+   */
+  image?: string | ReactNode;
+
+  /** Accessible alt text for the image when `image` is a URL string. @default '' */
+  imageAlt?: string;
+
+  /**
+   * Number of placeholder instance-row slots to render below the image.
+   * Range 0–9. `0` hides the slot entirely.
+   * @default 0
+   */
+  instanceRowCount?: number;
+
+  /** Custom slot rendered below the image inside the panel body. */
+  instanceRows?: ReactNode;
+
+  /**
+   * Free-form content rendered at the bottom of the panel body — after all named slots.
+   */
+  children?: ReactNode;
+
+  // ── Close button ─────────────────────────────────────────────────────────
+
+  /** Show the × close button in the top-trailing corner. @default true */
+  showCloseButton?: boolean;
+
+  // ── Actions ──────────────────────────────────────────────────────────────
+
+  /** Label for the primary (solid-green) action button. When omitted the actions row is hidden. */
+  primaryActionLabel?: string;
+
+  /** Label for the secondary (outlined) action button. When omitted only one button shows. */
+  secondaryActionLabel?: string;
+
+  /** Called when the primary action button is clicked. */
+  onPrimaryAction?: () => void;
+
+  /** Called when the secondary action button is clicked. */
+  onSecondaryAction?: () => void;
+
+  /** Alignment of action buttons in the footer. @default 'start' */
+  actionsAlignment?: PopoverActionsAlignment;
+
+  // ── Placement / beak ─────────────────────────────────────────────────────
+
+  /** Where the panel appears relative to the trigger. @default 'bottom' */
+  placement?: PopoverPlacement;
+
+  /** Whether to render the directional arrow (beak). @default true */
+  showBeak?: boolean;
+
+  // ── RTL / direction ──────────────────────────────────────────────────────
+
+  /** Text/layout direction. Placement `start`/`end` and close-button position flip in RTL. */
+  dir?: 'ltr' | 'rtl';
+}