@fragments-sdk/ui 0.1.0

package/src/components/Menu/Menu.module.scss

@@ -0,0 +1,190 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// Positioner
+.positioner {
+  z-index: 50;
+  outline: none;
+}
+
+// Popup container
+.popup {
+  @include surface-elevated;
+
+  min-width: 12rem;
+  padding: var(--fui-space-1, $fui-space-1);
+  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+
+  // Animation
+  opacity: 0;
+  transform: scale(0.95);
+  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);
+  }
+
+  &[data-starting-style],
+  &[data-ending-style] {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+}
+
+// Menu item (shared base)
+.item {
+  @include button-reset;
+  @include text-base;
+
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  width: 100%;
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  cursor: pointer;
+  outline: none;
+
+  &[data-highlighted] {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &[data-disabled] {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+    cursor: not-allowed;
+  }
+}
+
+// Danger variant for destructive actions
+.itemDanger {
+  color: var(--fui-color-danger, $fui-color-danger);
+
+  &[data-highlighted] {
+    background-color: var(--fui-color-danger-bg, $fui-color-danger-bg);
+  }
+}
+
+// Item with icon
+.itemIcon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1rem;
+  height: 1rem;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+
+  .itemDanger & {
+    color: var(--fui-color-danger, $fui-color-danger);
+  }
+
+  svg {
+    width: 1rem;
+    height: 1rem;
+  }
+}
+
+// Item label (main text)
+.itemLabel {
+  flex: 1;
+}
+
+// Item shortcut (keyboard shortcut hint)
+.itemShortcut {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+  margin-left: auto;
+}
+
+// Checkbox/Radio indicator
+.itemIndicator {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1rem;
+  height: 1rem;
+
+  svg {
+    width: 0.75rem;
+    height: 0.75rem;
+  }
+}
+
+// Checkbox item states
+.checkboxItem {
+  &[data-checked] .itemIndicator {
+    color: var(--fui-color-accent, $fui-color-accent);
+  }
+}
+
+// Radio item states
+.radioItem {
+  &[data-checked] .itemIndicator {
+    color: var(--fui-color-accent, $fui-color-accent);
+  }
+}
+
+// Separator
+.separator {
+  height: 1px;
+  margin: var(--fui-space-1, $fui-space-1) 0;
+  background-color: var(--fui-border, $fui-border);
+}
+
+// Group container
+.group {
+  // No specific styles needed
+}
+
+// Group label
+.groupLabel {
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+}
+
+// Arrow
+.arrow {
+  width: 10px;
+  height: 10px;
+  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;
+  }
+}
+
+// Submenu trigger (has arrow on right)
+.submenuTrigger {
+  &::after {
+    content: '';
+    margin-left: auto;
+    width: 0;
+    height: 0;
+    border-style: solid;
+    border-width: 4px 0 4px 6px;
+    border-color: transparent transparent transparent var(--fui-text-secondary, $fui-text-secondary);
+  }
+}

package/src/components/Menu/index.tsx

@@ -0,0 +1,318 @@
+import * as React from 'react';
+import { Menu as BaseMenu } from '@base-ui/react/menu';
+import styles from './Menu.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface MenuProps {
+  children: React.ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  modal?: boolean;
+}
+
+export interface MenuTriggerProps {
+  children: React.ReactNode;
+  asChild?: boolean;
+  className?: string;
+}
+
+export interface MenuContentProps {
+  children: React.ReactNode;
+  className?: string;
+  side?: 'top' | 'bottom' | 'left' | 'right';
+  align?: 'start' | 'center' | 'end';
+  sideOffset?: number;
+}
+
+export interface MenuItemProps {
+  children: React.ReactNode;
+  disabled?: boolean;
+  danger?: boolean;
+  onSelect?: () => void;
+  className?: string;
+  icon?: React.ReactNode;
+  shortcut?: string;
+}
+
+export interface MenuCheckboxItemProps {
+  children: React.ReactNode;
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+  disabled?: boolean;
+  className?: string;
+}
+
+export interface MenuRadioGroupProps {
+  children: React.ReactNode;
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+}
+
+export interface MenuRadioItemProps {
+  children: React.ReactNode;
+  value: string;
+  disabled?: boolean;
+  className?: string;
+}
+
+export interface MenuGroupProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface MenuGroupLabelProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface MenuSeparatorProps {
+  className?: string;
+}
+
+// ============================================
+// Icons
+// ============================================
+
+function CheckIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="12"
+      height="12"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="3"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="20 6 9 17 4 12" />
+    </svg>
+  );
+}
+
+function DotIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="12"
+      height="12"
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <circle cx="12" cy="12" r="5" />
+    </svg>
+  );
+}
+
+// ============================================
+// Components
+// ============================================
+
+function MenuRoot({
+  children,
+  open,
+  defaultOpen,
+  onOpenChange,
+  modal = true,
+}: MenuProps) {
+  return (
+    <BaseMenu.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      modal={modal}
+    >
+      {children}
+    </BaseMenu.Root>
+  );
+}
+
+function MenuTrigger({ children, asChild, className }: MenuTriggerProps) {
+  if (asChild) {
+    return (
+      <BaseMenu.Trigger className={className} render={children as React.ReactElement}>
+        {null}
+      </BaseMenu.Trigger>
+    );
+  }
+
+  return (
+    <BaseMenu.Trigger className={className}>
+      {children}
+    </BaseMenu.Trigger>
+  );
+}
+
+function MenuContent({
+  children,
+  className,
+  side = 'bottom',
+  align = 'start',
+  sideOffset = 4,
+}: MenuContentProps) {
+  const popupClasses = [styles.popup, className].filter(Boolean).join(' ');
+
+  return (
+    <BaseMenu.Portal>
+      <BaseMenu.Positioner
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        className={styles.positioner}
+      >
+        <BaseMenu.Popup className={popupClasses}>
+          {children}
+        </BaseMenu.Popup>
+      </BaseMenu.Positioner>
+    </BaseMenu.Portal>
+  );
+}
+
+function MenuItem({
+  children,
+  disabled,
+  danger,
+  onSelect,
+  className,
+  icon,
+  shortcut,
+}: MenuItemProps) {
+  const classes = [
+    styles.item,
+    danger && styles.itemDanger,
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <BaseMenu.Item
+      disabled={disabled}
+      onClick={onSelect}
+      className={classes}
+    >
+      {icon && <span className={styles.itemIcon}>{icon}</span>}
+      <span className={styles.itemLabel}>{children}</span>
+      {shortcut && <span className={styles.itemShortcut}>{shortcut}</span>}
+    </BaseMenu.Item>
+  );
+}
+
+function MenuCheckboxItem({
+  children,
+  checked,
+  defaultChecked,
+  onCheckedChange,
+  disabled,
+  className,
+}: MenuCheckboxItemProps) {
+  const classes = [styles.item, styles.checkboxItem, className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <BaseMenu.CheckboxItem
+      checked={checked}
+      defaultChecked={defaultChecked}
+      onCheckedChange={onCheckedChange}
+      disabled={disabled}
+      className={classes}
+    >
+      <span className={styles.itemIndicator}>
+        <CheckIcon />
+      </span>
+      <span className={styles.itemLabel}>{children}</span>
+    </BaseMenu.CheckboxItem>
+  );
+}
+
+function MenuRadioGroup({
+  children,
+  value,
+  defaultValue,
+  onValueChange,
+}: MenuRadioGroupProps) {
+  return (
+    <BaseMenu.RadioGroup
+      value={value}
+      defaultValue={defaultValue}
+      onValueChange={onValueChange}
+    >
+      {children}
+    </BaseMenu.RadioGroup>
+  );
+}
+
+function MenuRadioItem({
+  children,
+  value,
+  disabled,
+  className,
+}: MenuRadioItemProps) {
+  const classes = [styles.item, styles.radioItem, className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <BaseMenu.RadioItem value={value} disabled={disabled} className={classes}>
+      <span className={styles.itemIndicator}>
+        <DotIcon />
+      </span>
+      <span className={styles.itemLabel}>{children}</span>
+    </BaseMenu.RadioItem>
+  );
+}
+
+function MenuGroup({ children, className }: MenuGroupProps) {
+  const classes = [styles.group, className].filter(Boolean).join(' ');
+  return <BaseMenu.Group className={classes}>{children}</BaseMenu.Group>;
+}
+
+function MenuGroupLabel({ children, className }: MenuGroupLabelProps) {
+  const classes = [styles.groupLabel, className].filter(Boolean).join(' ');
+  return <BaseMenu.GroupLabel className={classes}>{children}</BaseMenu.GroupLabel>;
+}
+
+function MenuSeparator({ className }: MenuSeparatorProps) {
+  const classes = [styles.separator, className].filter(Boolean).join(' ');
+  return <BaseMenu.Separator className={classes} />;
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Menu = Object.assign(MenuRoot, {
+  Trigger: MenuTrigger,
+  Content: MenuContent,
+  Item: MenuItem,
+  CheckboxItem: MenuCheckboxItem,
+  RadioGroup: MenuRadioGroup,
+  RadioItem: MenuRadioItem,
+  Group: MenuGroup,
+  GroupLabel: MenuGroupLabel,
+  Separator: MenuSeparator,
+});
+
+// Re-export individual components
+export {
+  MenuRoot,
+  MenuTrigger,
+  MenuContent,
+  MenuItem,
+  MenuCheckboxItem,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuGroup,
+  MenuGroupLabel,
+  MenuSeparator,
+};

package/src/components/Popover/Popover.fragment.tsx

@@ -0,0 +1,178 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Popover } from './index.js';
+import { Button } from '../Button/index.js';
+import { Input } from '../Input/index.js';
+
+export default defineSegment({
+  component: Popover,
+
+  meta: {
+    name: 'Popover',
+    description: 'Rich content overlay anchored to a trigger element. Use for forms, detailed information, or interactive content that should stay in context.',
+    category: 'overlays',
+    status: 'stable',
+    tags: ['popover', 'overlay', 'dropdown', 'floating', 'contextual'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Inline editing forms',
+      'Rich preview content',
+      'Filter panels',
+      'Date/color pickers',
+      'Content that needs more space than a tooltip',
+    ],
+    whenNot: [
+      'Simple hints (use Tooltip)',
+      'Action lists (use Menu)',
+      'Blocking user interaction (use Dialog)',
+      'System notifications (use Toast or Alert)',
+    ],
+    guidelines: [
+      'Keep popover content focused and minimal',
+      'Include a clear way to close (X button or action buttons)',
+      'Position to avoid covering important content',
+      'Use arrow to visually connect popover to trigger',
+    ],
+    accessibility: [
+      'Focus is moved to popover content on open',
+      'Closes on Escape key',
+      'Focus returns to trigger on close',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Popover trigger and content',
+      required: true,
+    },
+    open: {
+      type: 'boolean',
+      description: 'Controlled open state',
+    },
+    defaultOpen: {
+      type: 'boolean',
+      description: 'Default open state (uncontrolled)',
+      default: 'false',
+    },
+    onOpenChange: {
+      type: 'function',
+      description: 'Called when open state changes',
+    },
+    modal: {
+      type: 'boolean',
+      description: 'Whether to block page interaction',
+      default: 'false',
+    },
+  },
+
+  relations: [
+    { component: 'Tooltip', relationship: 'alternative', note: 'Use Tooltip for brief, non-interactive hints' },
+    { component: 'Menu', relationship: 'alternative', note: 'Use Menu for action lists' },
+    { component: 'Dialog', relationship: 'alternative', note: 'Use Dialog for blocking interactions' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'open: boolean - controlled open state',
+      'onOpenChange: (open) => void - state handler',
+      'modal: boolean - blocks page interaction (default: false)',
+      'Popover.Content side: top|bottom|left|right - position',
+    ],
+    scenarioTags: [
+      'overlay.popover',
+      'form.inline',
+      'content.preview',
+    ],
+    a11yRules: ['A11Y_POPOVER_FOCUS', 'A11Y_POPOVER_ESCAPE'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic popover with content',
+      render: () => (
+        <Popover>
+          <Popover.Trigger asChild>
+            <Button variant="secondary">Open Popover</Button>
+          </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>
+      ),
+    },
+    {
+      name: 'With Form',
+      description: 'Popover containing a form',
+      render: () => (
+        <Popover>
+          <Popover.Trigger asChild>
+            <Button variant="secondary">Edit Name</Button>
+          </Popover.Trigger>
+          <Popover.Content size="sm">
+            <Popover.Close />
+            <Popover.Title>Edit Name</Popover.Title>
+            <Popover.Body>
+              <Input label="Display Name" placeholder="Enter name" />
+            </Popover.Body>
+            <Popover.Footer>
+              <Popover.Close asChild>
+                <Button variant="secondary" size="sm">Cancel</Button>
+              </Popover.Close>
+              <Button variant="primary" size="sm">Save</Button>
+            </Popover.Footer>
+          </Popover.Content>
+        </Popover>
+      ),
+    },
+    {
+      name: 'With Arrow',
+      description: 'Popover with pointing arrow',
+      render: () => (
+        <Popover>
+          <Popover.Trigger asChild>
+            <Button variant="secondary">Info</Button>
+          </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>
+      ),
+    },
+    {
+      name: 'Positions',
+      description: 'Popover on different sides',
+      render: () => (
+        <div style={{ display: 'flex', gap: '16px', padding: '60px' }}>
+          <Popover>
+            <Popover.Trigger asChild>
+              <Button variant="secondary">Top</Button>
+            </Popover.Trigger>
+            <Popover.Content side="top" size="sm">
+              <Popover.Description>Popover on top</Popover.Description>
+            </Popover.Content>
+          </Popover>
+          <Popover>
+            <Popover.Trigger asChild>
+              <Button variant="secondary">Bottom</Button>
+            </Popover.Trigger>
+            <Popover.Content side="bottom" size="sm">
+              <Popover.Description>Popover on bottom</Popover.Description>
+            </Popover.Content>
+          </Popover>
+        </div>
+      ),
+    },
+  ],
+});