@usefragments/ui 1.0.0

package/src/components/Popover/Popover.module.scss

@@ -0,0 +1,189 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// Local component tokens
+$fui-arrow-size: 10px !default;
+
+// Positioner — z-index must exceed Dialog positioner (51)
+.positioner {
+  z-index: 52;
+  outline: none;
+}
+
+// Popup container
+.popup {
+  @include surface-elevated;
+  @include text-base;
+
+  min-width: 12rem;
+  max-width: 24rem;
+  padding: var(--fui-space-2, $fui-space-2);
+  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+
+  // Animation
+  opacity: 0;
+  transform: scale(0.95) translateY(-$fui-anim-offset-sm);
+  transform-origin: var(--transform-origin);
+  transition:
+    opacity var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  &[data-open] {
+    opacity: 1;
+    transform: scale(1) translateY(0);
+  }
+
+  &[data-starting-style] {
+    opacity: 0;
+    transform: scale(0.95) translateY(-$fui-anim-offset-sm);
+  }
+
+  &[data-ending-style] {
+    opacity: 0;
+    transform: scale(0.95) translateY($fui-anim-offset-sm);
+  }
+
+  // Adjust animation direction based on side
+  &[data-side="top"] {
+    &[data-starting-style] {
+      transform: scale(0.95) translateY($fui-anim-offset-sm);
+    }
+
+    &[data-ending-style] {
+      transform: scale(0.95) translateY(-$fui-anim-offset-sm);
+    }
+  }
+
+  &[data-side="left"],
+  &[data-side="right"] {
+    &[data-starting-style],
+    &[data-ending-style] {
+      transform: scale(0.95) translateY(0);
+    }
+  }
+}
+
+// Size variants
+.sm {
+  padding: var(--fui-space-3, $fui-space-3);
+  max-width: 16rem;
+}
+
+.md {
+  // Default styles
+}
+
+.lg {
+  padding: var(--fui-space-6, $fui-space-6);
+  max-width: 32rem;
+}
+
+// Title
+.title {
+  margin: 0 0 var(--fui-space-1, $fui-space-1);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  color: var(--fui-text-primary, $fui-text-primary);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+}
+
+// Description
+.description {
+  margin: 0;
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+// Close button
+.close {
+  @include button-reset;
+  @include interactive-base;
+  @include touch-target;
+
+  position: absolute;
+  top: var(--fui-space-2, $fui-space-2);
+  right: var(--fui-space-2, $fui-space-2);
+  width: 1.5rem;
+  height: 1.5rem;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+
+  &:hover {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  svg {
+    width: 0.875rem;
+    height: 0.875rem;
+  }
+}
+
+// Arrow
+.arrow {
+  width: $fui-arrow-size;
+  height: $fui-arrow-size;
+  transform: rotate(45deg);
+  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  border: 1px solid var(--fui-border, $fui-border);
+
+  &[data-side="top"] {
+    border-top: none;
+    border-left: none;
+  }
+
+  &[data-side="bottom"] {
+    border-bottom: none;
+    border-right: none;
+  }
+
+  &[data-side="left"] {
+    border-left: none;
+    border-bottom: none;
+  }
+
+  &[data-side="right"] {
+    border-right: none;
+    border-top: none;
+  }
+}
+
+// Body content area
+.body {
+  margin-top: var(--fui-space-3, $fui-space-3);
+}
+
+// Footer for actions
+.footer {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--fui-space-2, $fui-space-2);
+  margin-top: var(--fui-space-4, $fui-space-4);
+  padding-top: var(--fui-space-3, $fui-space-3);
+  border-top: 1px solid var(--fui-border, $fui-border);
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .popup {
+    transition: none;
+    transform: none;
+
+    &[data-starting-style],
+    &[data-ending-style] {
+      transform: none;
+    }
+
+    &[data-side="top"] {
+      &[data-starting-style],
+      &[data-ending-style] {
+        transform: none;
+      }
+    }
+  }
+}

package/src/components/Popover/Popover.stories.tsx

@@ -0,0 +1,152 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Popover } from '.';
+
+/**
+ * Rich content overlay anchored to a trigger element. Compose with
+ * `Popover.Trigger`, `Popover.Content`, `Popover.Title`, `Popover.Description`,
+ * `Popover.Body`, `Popover.Footer`, and `Popover.Close`.
+ */
+const meta = {
+  title: 'Feedback/Popover',
+  component: Popover,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Floating content overlay anchored to a trigger element.',
+      },
+    },
+  },
+  argTypes: {
+    modal: { control: 'boolean' },
+    defaultOpen: { control: 'boolean' },
+  },
+  args: {
+    modal: false,
+    children: (
+      <>
+        <Popover.Trigger>Open Popover</Popover.Trigger>
+        <Popover.Content>
+          <Popover.Close />
+          <Popover.Title>Popover Title</Popover.Title>
+          <Popover.Description>
+            This is a popover with some content.
+          </Popover.Description>
+        </Popover.Content>
+      </>
+    ),
+  },
+} satisfies Meta<typeof Popover>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Popover {...args}>
+      <Popover.Trigger>Open Popover</Popover.Trigger>
+      <Popover.Content>
+        <Popover.Close />
+        <Popover.Title>Popover Title</Popover.Title>
+        <Popover.Description>
+          This is a popover with some content. It can contain text, forms, or
+          other elements.
+        </Popover.Description>
+      </Popover.Content>
+    </Popover>
+  ),
+};
+
+export const WithArrow: Story = {
+  render: (args) => (
+    <Popover {...args}>
+      <Popover.Trigger>Info</Popover.Trigger>
+      <Popover.Content arrow>
+        <Popover.Title>Quick Tip</Popover.Title>
+        <Popover.Description>
+          This popover has an arrow pointing to its trigger element.
+        </Popover.Description>
+      </Popover.Content>
+    </Popover>
+  ),
+};
+
+export const TopSide: Story = {
+  render: (args) => (
+    <Popover {...args}>
+      <Popover.Trigger>Top</Popover.Trigger>
+      <Popover.Content side="top" size="sm">
+        <Popover.Description>Popover on top</Popover.Description>
+      </Popover.Content>
+    </Popover>
+  ),
+};
+
+export const SmallSize: Story = {
+  render: (args) => (
+    <Popover {...args}>
+      <Popover.Trigger>Compact</Popover.Trigger>
+      <Popover.Content size="sm">
+        <Popover.Description>A small, focused popover.</Popover.Description>
+      </Popover.Content>
+    </Popover>
+  ),
+};
+
+function VirtualAnchorDemo(args: React.ComponentProps<typeof Popover>) {
+  const [anchor, setAnchor] = React.useState<HTMLDivElement | null>(null);
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{ paddingTop: 80 }}>
+      <div
+        ref={setAnchor}
+        style={{
+          width: 160,
+          height: 40,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          border: '1px dashed currentColor',
+          borderRadius: 8,
+        }}
+      >
+        Anchor element
+      </div>
+      <Popover {...args} open={open} onOpenChange={setOpen}>
+        <Popover.Trigger
+          style={{
+            position: 'absolute',
+            width: 1,
+            height: 1,
+            overflow: 'hidden',
+            clip: 'rect(0 0 0 0)',
+          }}
+          onClick={() => setOpen(true)}
+        >
+          Open (off-screen trigger)
+        </Popover.Trigger>
+        <Popover.Content anchor={anchor} positionMethod="fixed">
+          <Popover.Close />
+          <Popover.Title>Anchored elsewhere</Popover.Title>
+          <Popover.Description>
+            This content is positioned against the dashed box above, not the
+            (visually hidden) trigger button.
+          </Popover.Description>
+        </Popover.Content>
+      </Popover>
+    </div>
+  );
+}
+
+/**
+ * Positions content against an arbitrary DOM element instead of the
+ * trigger, via `anchor` + `positionMethod="fixed"`. Used by Fragments
+ * Inspect's element-anchored detail view, where the "anchor" is a node in
+ * the host page rather than something rendered by this popover's own tree.
+ */
+export const VirtualAnchor: Story = {
+  render: (args) => <VirtualAnchorDemo {...args} />,
+};

package/src/components/Popover/index.tsx

@@ -0,0 +1,284 @@
+'use client';
+
+import * as React from 'react';
+import { Popover as BasePopover } from '@base-ui/react/popover';
+import styles from './Popover.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+/**
+ * Popover for floating content attached to a trigger element.
+ * @see https://usefragments.com/components/popover
+ */
+export interface PopoverProps {
+  children: React.ReactNode;
+  /** Controlled open state */
+  open?: boolean;
+  /** Default open state */
+  defaultOpen?: boolean;
+  /** Called when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Whether the popover blocks interaction with the rest of the page.
+   * @default false */
+  modal?: boolean;
+}
+
+type PopoverTriggerAsButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  children: React.ReactNode;
+  asChild?: false;
+};
+type PopoverTriggerAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+  children: React.ReactElement;
+  asChild: true;
+};
+export type PopoverTriggerProps = PopoverTriggerAsButtonProps | PopoverTriggerAsChildProps;
+
+export interface PopoverContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  size?: 'sm' | 'md' | 'lg';
+  side?: 'top' | 'bottom' | 'left' | 'right';
+  align?: 'start' | 'center' | 'end';
+  sideOffset?: number;
+  arrow?: boolean;
+  /**
+   * Position the popover against an element outside the trigger-anchored
+   * flow (e.g. an arbitrary DOM node in a host page). Defaults to the
+   * trigger, like Base UI's own default.
+   */
+  anchor?: Element | null;
+  /** CSS `position` for the floating content. @default 'absolute' */
+  positionMethod?: 'absolute' | 'fixed';
+  /**
+   * Render the portal into a specific container instead of `document.body`
+   * (e.g. a shadow root whose styles wouldn't otherwise reach body-portaled
+   * content).
+   */
+  container?: HTMLElement | ShadowRoot | null;
+  /** Extra className applied to the positioner element (not the popup). */
+  positionerClassName?: string;
+}
+
+export interface PopoverTitleProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  children: React.ReactNode;
+}
+
+export interface PopoverDescriptionProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
+  children: React.ReactNode;
+}
+
+export interface PopoverBodyProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export interface PopoverFooterProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+type PopoverCloseAsButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  children?: React.ReactNode;
+  asChild?: false;
+};
+type PopoverCloseAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+  children: React.ReactElement;
+  asChild: true;
+};
+export type PopoverCloseProps = PopoverCloseAsButtonProps | PopoverCloseAsChildProps;
+
+// ============================================
+// Icons
+// ============================================
+
+function CloseIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <line x1="18" y1="6" x2="6" y2="18" />
+      <line x1="6" y1="6" x2="18" y2="18" />
+    </svg>
+  );
+}
+
+// ============================================
+// Components
+// ============================================
+
+function PopoverRoot({
+  children,
+  open,
+  defaultOpen,
+  onOpenChange,
+  modal = false,
+}: PopoverProps) {
+  return (
+    <BasePopover.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      modal={modal}
+    >
+      {children}
+    </BasePopover.Root>
+  );
+}
+
+function PopoverTrigger({ children, asChild, className, ...htmlProps }: PopoverTriggerProps) {
+  if (asChild) {
+    if (!React.isValidElement(children)) {
+      throw new Error('Popover.Trigger with asChild requires a single valid React element child.');
+    }
+    return (
+      <BasePopover.Trigger {...htmlProps} className={className} render={children as React.ReactElement}>
+        {null}
+      </BasePopover.Trigger>
+    );
+  }
+
+  return (
+    <BasePopover.Trigger
+      {...htmlProps}
+      type={(htmlProps as React.ButtonHTMLAttributes<HTMLButtonElement>).type ?? 'button'}
+      className={className}
+    >
+      {children}
+    </BasePopover.Trigger>
+  );
+}
+
+function PopoverContent({
+  children,
+  size = 'md',
+  side = 'bottom',
+  align = 'center',
+  sideOffset = 8,
+  arrow = false,
+  anchor,
+  positionMethod,
+  container,
+  positionerClassName,
+  className,
+  ...htmlProps
+}: PopoverContentProps) {
+  const popupClasses = [
+    styles.popup,
+    size !== 'md' && styles[size],
+    className,
+  ].filter(Boolean).join(' ');
+  const positionerClasses = [styles.positioner, positionerClassName].filter(Boolean).join(' ');
+
+  return (
+    <BasePopover.Portal container={container}>
+      <BasePopover.Positioner
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        anchor={anchor}
+        positionMethod={positionMethod}
+        className={positionerClasses}
+      >
+        <BasePopover.Popup {...htmlProps} className={popupClasses}>
+          {children}
+          {arrow && <BasePopover.Arrow className={styles.arrow} />}
+        </BasePopover.Popup>
+      </BasePopover.Positioner>
+    </BasePopover.Portal>
+  );
+}
+
+function PopoverTitle({ children, className, ...htmlProps }: PopoverTitleProps) {
+  const classes = [styles.title, className].filter(Boolean).join(' ');
+  return <BasePopover.Title {...htmlProps} className={classes}>{children}</BasePopover.Title>;
+}
+
+function PopoverDescription({ children, className, ...htmlProps }: PopoverDescriptionProps) {
+  const classes = [styles.description, className].filter(Boolean).join(' ');
+  return (
+    <BasePopover.Description {...htmlProps} className={classes}>
+      {children}
+    </BasePopover.Description>
+  );
+}
+
+function PopoverBody({ children, className, ...htmlProps }: PopoverBodyProps) {
+  const classes = [styles.body, className].filter(Boolean).join(' ');
+  return <div {...htmlProps} className={classes}>{children}</div>;
+}
+
+function PopoverFooter({ children, className, ...htmlProps }: PopoverFooterProps) {
+  const classes = [styles.footer, className].filter(Boolean).join(' ');
+  return <div {...htmlProps} className={classes}>{children}</div>;
+}
+
+function PopoverClose({ children, asChild, className, ...htmlProps }: PopoverCloseProps) {
+  // Default close button (X icon)
+  if (!children) {
+    return (
+      <BasePopover.Close
+        {...htmlProps}
+        type={(htmlProps as React.ButtonHTMLAttributes<HTMLButtonElement>).type ?? 'button'}
+        aria-label="Close popover"
+        className={[styles.close, className].filter(Boolean).join(' ')}
+      >
+        <CloseIcon />
+      </BasePopover.Close>
+    );
+  }
+
+  if (asChild) {
+    if (!React.isValidElement(children)) {
+      throw new Error('Popover.Close with asChild requires a single valid React element child.');
+    }
+    return (
+      <BasePopover.Close {...htmlProps} className={className} render={children as React.ReactElement}>
+        {null}
+      </BasePopover.Close>
+    );
+  }
+
+  return (
+    <BasePopover.Close
+      {...htmlProps}
+      type={(htmlProps as React.ButtonHTMLAttributes<HTMLButtonElement>).type ?? 'button'}
+      className={className}
+    >
+      {children}
+    </BasePopover.Close>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Popover = Object.assign(PopoverRoot, {
+  Trigger: PopoverTrigger,
+  Content: PopoverContent,
+  Title: PopoverTitle,
+  Description: PopoverDescription,
+  Body: PopoverBody,
+  Footer: PopoverFooter,
+  Close: PopoverClose,
+});
+
+// Re-export individual components
+export {
+  PopoverRoot,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverTitle,
+  PopoverDescription,
+  PopoverBody,
+  PopoverFooter,
+  PopoverClose,
+};