@fragments-sdk/ui 0.1.0

package/src/components/Toggle/Toggle.module.scss

@@ -0,0 +1,103 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.root {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--fui-space-3, $fui-space-3);
+  cursor: pointer;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+
+  &[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+}
+
+.track {
+  @include button-reset;
+  @include interactive-base;
+
+  position: relative;
+  flex-shrink: 0;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  margin-top: 2px;
+  background-color: var(--fui-border-strong, $fui-border-strong);
+
+  &[data-checked] {
+    background-color: var(--fui-color-accent, $fui-color-accent);
+  }
+
+  &:hover:not(:disabled) {
+    opacity: 0.9;
+  }
+}
+
+.trackSm {
+  width: var(--fui-toggle-width-sm, $fui-toggle-width-sm);
+  height: var(--fui-toggle-height-sm, $fui-toggle-height-sm);
+}
+
+.trackMd {
+  width: var(--fui-toggle-width-md, $fui-toggle-width-md);
+  height: var(--fui-toggle-height-md, $fui-toggle-height-md);
+}
+
+.thumb {
+  position: absolute;
+  top: 2px;
+  left: 2px;
+  border-radius: 50%;
+  background-color: var(--fui-bg-primary, $fui-bg-primary);
+  box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
+  transition: transform var(--fui-transition-normal, $fui-transition-normal);
+
+  [data-checked] > & {
+    // Move thumb to the right when checked
+    transform: translateX(calc(100%));
+  }
+}
+
+.thumbSm {
+  width: 14px;
+  height: 14px;
+
+  [data-checked] > & {
+    transform: translateX(14px);
+  }
+}
+
+.thumbMd {
+  width: 18px;
+  height: 18px;
+
+  [data-checked] > & {
+    transform: translateX(18px);
+  }
+}
+
+.content {
+  flex: 1;
+}
+
+.label {
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-primary, $fui-text-primary);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+}
+
+.labelSm {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.description {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  margin-top: 2px;
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+}
+
+.descriptionSm {
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+}

package/src/components/Toggle/index.tsx

@@ -0,0 +1,80 @@
+import * as React from 'react';
+import { Switch } from '@base-ui/react/switch';
+import styles from './Toggle.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+export interface ToggleProps {
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onChange?: (checked: boolean) => void;
+  label?: string;
+  description?: string;
+  disabled?: boolean;
+  size?: 'sm' | 'md';
+  className?: string;
+  name?: string;
+}
+
+export const Toggle = React.forwardRef<HTMLButtonElement, ToggleProps>(
+  function Toggle(
+    {
+      checked,
+      defaultChecked,
+      onChange,
+      label,
+      description,
+      disabled = false,
+      size = 'md',
+      className,
+      name,
+    },
+    ref
+  ) {
+    const trackClasses = [
+      styles.track,
+      size === 'sm' ? styles.trackSm : styles.trackMd,
+    ].join(' ');
+
+    const thumbClasses = [
+      styles.thumb,
+      size === 'sm' ? styles.thumbSm : styles.thumbMd,
+    ].join(' ');
+
+    const labelClasses = [styles.label, size === 'sm' && styles.labelSm]
+      .filter(Boolean)
+      .join(' ');
+
+    const descClasses = [
+      styles.description,
+      size === 'sm' && styles.descriptionSm,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const rootClasses = [styles.root, className].filter(Boolean).join(' ');
+
+    return (
+      <Switch.Root
+        ref={ref}
+        checked={checked}
+        defaultChecked={defaultChecked}
+        onCheckedChange={onChange}
+        disabled={disabled}
+        name={name}
+        className={rootClasses}
+      >
+        <Switch.Thumb className={trackClasses}>
+          <span className={thumbClasses} aria-hidden="true" />
+        </Switch.Thumb>
+
+        {(label || description) && (
+          <div className={styles.content}>
+            {label && <span className={labelClasses}>{label}</span>}
+            {description && <span className={descClasses}>{description}</span>}
+          </div>
+        )}
+      </Switch.Root>
+    );
+  }
+);

package/src/components/Tooltip/Tooltip.fragment.tsx

@@ -0,0 +1,158 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Tooltip, TooltipProvider } from './index.js';
+import { Button } from '../Button/index.js';
+
+export default defineSegment({
+  component: Tooltip,
+
+  meta: {
+    name: 'Tooltip',
+    description: 'Contextual help text that appears on hover or focus. Perfect for explaining icons, truncated text, or providing additional context.',
+    category: 'overlays',
+    status: 'stable',
+    tags: ['tooltip', 'hint', 'help', 'hover', 'contextual'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Explaining icon-only buttons',
+      'Showing full text for truncated content',
+      'Providing keyboard shortcuts',
+      'Brief contextual help that fits in one line',
+    ],
+    whenNot: [
+      'Long-form help content (use Popover)',
+      'Critical information users must see (use Alert)',
+      'Interactive content (use Popover or Menu)',
+      'Mobile-primary interfaces (tooltips require hover)',
+    ],
+    guidelines: [
+      'Keep tooltip text concise (under 80 characters)',
+      'Use sentence case, no period for single sentences',
+      'Avoid duplicating visible label text',
+      'Consider mobile users who cannot hover',
+    ],
+    accessibility: [
+      'Accessible via focus as well as hover',
+      'Uses role="tooltip" with proper aria association',
+      'Delay prevents tooltips from appearing during navigation',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'element',
+      description: 'The element that triggers the tooltip',
+      required: true,
+    },
+    content: {
+      type: 'node',
+      description: 'Content to display in the tooltip',
+      required: true,
+    },
+    side: {
+      type: 'enum',
+      description: 'Which side to show the tooltip',
+      values: ['top', 'bottom', 'left', 'right'],
+      default: 'top',
+    },
+    align: {
+      type: 'enum',
+      description: 'Alignment along the side',
+      values: ['start', 'center', 'end'],
+      default: 'center',
+    },
+    sideOffset: {
+      type: 'number',
+      description: 'Distance from trigger in pixels',
+      default: '6',
+    },
+    delay: {
+      type: 'number',
+      description: 'Delay before showing (ms)',
+      default: '400',
+    },
+    arrow: {
+      type: 'boolean',
+      description: 'Show arrow pointing to trigger',
+      default: 'true',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disable the tooltip',
+      default: 'false',
+    },
+  },
+
+  relations: [
+    { component: 'Popover', relationship: 'alternative', note: 'Use Popover for interactive or longer content' },
+    { component: 'Alert', relationship: 'alternative', note: 'Use Alert for critical information that must be visible' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'content: ReactNode - tooltip content',
+      'side: top|bottom|left|right - position',
+      'delay: number - show delay in ms (default: 400)',
+      'arrow: boolean - show arrow (default: true)',
+    ],
+    scenarioTags: [
+      'help.tooltip',
+      'content.hint',
+      'action.explain',
+    ],
+    a11yRules: ['A11Y_TOOLTIP_FOCUS', 'A11Y_TOOLTIP_ROLE'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic tooltip on hover',
+      render: () => (
+        <Tooltip content="Save your changes">
+          <Button>Save</Button>
+        </Tooltip>
+      ),
+    },
+    {
+      name: 'Positions',
+      description: 'Tooltips on different sides',
+      render: () => (
+        <div style={{ display: 'flex', gap: '16px', padding: '40px' }}>
+          <Tooltip content="Top tooltip" side="top">
+            <Button variant="secondary">Top</Button>
+          </Tooltip>
+          <Tooltip content="Bottom tooltip" side="bottom">
+            <Button variant="secondary">Bottom</Button>
+          </Tooltip>
+          <Tooltip content="Left tooltip" side="left">
+            <Button variant="secondary">Left</Button>
+          </Tooltip>
+          <Tooltip content="Right tooltip" side="right">
+            <Button variant="secondary">Right</Button>
+          </Tooltip>
+        </div>
+      ),
+    },
+    {
+      name: 'With Shortcut',
+      description: 'Tooltip showing keyboard shortcut',
+      render: () => (
+        <Tooltip content="Undo (Ctrl+Z)">
+          <Button variant="ghost">Undo</Button>
+        </Tooltip>
+      ),
+    },
+    {
+      name: 'No Arrow',
+      description: 'Tooltip without arrow',
+      render: () => (
+        <Tooltip content="Clean tooltip" arrow={false}>
+          <Button variant="secondary">Hover me</Button>
+        </Tooltip>
+      ),
+    },
+  ],
+});

package/src/components/Tooltip/Tooltip.module.scss

@@ -0,0 +1,82 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// Positioner (handles placement)
+.positioner {
+  z-index: 60;
+  pointer-events: none;
+}
+
+// The tooltip popup
+.popup {
+  @include text-base;
+
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+  // Tooltips use inverted colors - always dark bg with light text
+  color: #f8fafc;
+  background-color: #1e293b;
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.2), 0 2px 4px -2px rgba(0, 0, 0, 0.15);
+  max-width: 20rem; // 320px
+  word-wrap: break-word;
+
+  // 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] {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+
+  &[data-ending-style] {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+
+  // Instant transitions (when moving between tooltips)
+  &[data-instant] {
+    transition-duration: 0ms;
+  }
+}
+
+// Arrow element
+.arrow {
+  width: 8px;
+  height: 8px;
+  transform: rotate(45deg);
+  background-color: #1e293b;
+
+  // Position based on side
+  &[data-side='top'] {
+    bottom: -4px;
+  }
+
+  &[data-side='bottom'] {
+    top: -4px;
+  }
+
+  &[data-side='left'] {
+    right: -4px;
+  }
+
+  &[data-side='right'] {
+    left: -4px;
+  }
+}
+
+// Trigger wrapper (when using asChild)
+.trigger {
+  display: inline-flex;
+}

package/src/components/Tooltip/index.tsx

@@ -0,0 +1,135 @@
+import * as React from 'react';
+import { Tooltip as BaseTooltip } from '@base-ui/react/tooltip';
+import styles from './Tooltip.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
+export type TooltipAlign = 'start' | 'center' | 'end';
+
+export interface TooltipProps {
+  /** The element that triggers the tooltip */
+  children: React.ReactElement;
+  /** Content to display in the tooltip */
+  content: React.ReactNode;
+  /** Which side to show the tooltip */
+  side?: TooltipSide;
+  /** Alignment along the side */
+  align?: TooltipAlign;
+  /** Offset from the trigger (px) */
+  sideOffset?: number;
+  /** Delay before showing (ms) */
+  delay?: number;
+  /** Delay before hiding (ms) */
+  closeDelay?: number;
+  /** Whether the tooltip is disabled */
+  disabled?: boolean;
+  /** Show arrow pointing to trigger */
+  arrow?: boolean;
+  /** Controlled open state */
+  open?: boolean;
+  /** Default open state */
+  defaultOpen?: boolean;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+}
+
+export interface TooltipProviderProps {
+  children: React.ReactNode;
+  /** Default delay for all tooltips (ms) */
+  delay?: number;
+  /** Default close delay for all tooltips (ms) */
+  closeDelay?: number;
+  /** Timeout for instant open when moving between tooltips (ms) */
+  timeout?: number;
+}
+
+// ============================================
+// Components
+// ============================================
+
+/**
+ * Tooltip - Shows contextual information on hover/focus
+ *
+ * @example
+ * ```tsx
+ * <Tooltip content="Save your changes">
+ *   <Button>Save</Button>
+ * </Tooltip>
+ * ```
+ */
+export function Tooltip({
+  children,
+  content,
+  side = 'top',
+  align = 'center',
+  sideOffset = 6,
+  delay = 400,
+  closeDelay = 0,
+  disabled = false,
+  arrow = true,
+  open,
+  defaultOpen,
+  onOpenChange,
+}: TooltipProps) {
+  if (disabled) {
+    return children;
+  }
+
+  return (
+    <BaseTooltip.Provider delay={delay} closeDelay={closeDelay}>
+      <BaseTooltip.Root
+        open={open}
+        defaultOpen={defaultOpen}
+        onOpenChange={onOpenChange}
+      >
+        <BaseTooltip.Trigger render={(props) => React.cloneElement(children, props)} />
+        <BaseTooltip.Portal>
+          <BaseTooltip.Positioner
+            side={side}
+            align={align}
+            sideOffset={sideOffset}
+            className={styles.positioner}
+          >
+            <BaseTooltip.Popup className={styles.popup}>
+              {content}
+              {arrow && <BaseTooltip.Arrow className={styles.arrow} />}
+            </BaseTooltip.Popup>
+          </BaseTooltip.Positioner>
+        </BaseTooltip.Portal>
+      </BaseTooltip.Root>
+    </BaseTooltip.Provider>
+  );
+}
+
+/**
+ * TooltipProvider - Manages shared delay behavior for multiple tooltips
+ *
+ * @example
+ * ```tsx
+ * <TooltipProvider delay={200}>
+ *   <Tooltip content="First">...</Tooltip>
+ *   <Tooltip content="Second">...</Tooltip>
+ * </TooltipProvider>
+ * ```
+ */
+export function TooltipProvider({
+  children,
+  delay = 400,
+  closeDelay = 0,
+  timeout = 400,
+}: TooltipProviderProps) {
+  return (
+    <BaseTooltip.Provider
+      delay={delay}
+      closeDelay={closeDelay}
+      timeout={timeout}
+    >
+      {children}
+    </BaseTooltip.Provider>
+  );
+}

package/src/index.ts

@@ -0,0 +1,151 @@
+// Import CSS variables and base styles
+// This ensures --fui-* variables are available when using any component
+import './styles/globals.scss';
+
+// Core Components
+export { Button, type ButtonProps } from './components/Button';
+export { Input, type InputProps } from './components/Input';
+export { Textarea, type TextareaProps } from './components/Textarea';
+export { Card, type CardProps } from './components/Card';
+export { Toggle, type ToggleProps } from './components/Toggle';
+export { Alert, type AlertProps } from './components/Alert';
+export { Badge, type BadgeProps } from './components/Badge';
+export { Avatar, type AvatarProps, type AvatarGroupProps, type AvatarSize } from './components/Avatar';
+
+// Dialog
+export {
+  Dialog,
+  type DialogProps,
+  type DialogContentProps,
+  type DialogTitleProps,
+  type DialogDescriptionProps,
+  type DialogHeaderProps,
+  type DialogBodyProps,
+  type DialogFooterProps,
+  type DialogTriggerProps,
+  type DialogCloseProps,
+} from './components/Dialog';
+
+// Tabs
+export {
+  Tabs,
+  type TabsProps,
+  type TabsListProps,
+  type TabProps,
+  type TabsPanelProps,
+  type TabValue,
+} from './components/Tabs';
+
+// Tooltip
+export {
+  Tooltip,
+  TooltipProvider,
+  type TooltipProps,
+  type TooltipProviderProps,
+  type TooltipSide,
+  type TooltipAlign,
+} from './components/Tooltip';
+
+// Select
+export {
+  Select,
+  type SelectProps,
+  type SelectTriggerProps,
+  type SelectContentProps,
+  type SelectItemProps,
+  type SelectGroupProps,
+  type SelectGroupLabelProps,
+  type SelectValue,
+  type SelectOption,
+} from './components/Select';
+
+// Menu
+export {
+  Menu,
+  type MenuProps,
+  type MenuTriggerProps,
+  type MenuContentProps,
+  type MenuItemProps,
+  type MenuCheckboxItemProps,
+  type MenuRadioGroupProps,
+  type MenuRadioItemProps,
+  type MenuGroupProps,
+  type MenuGroupLabelProps,
+  type MenuSeparatorProps,
+} from './components/Menu';
+
+// Popover
+export {
+  Popover,
+  type PopoverProps,
+  type PopoverTriggerProps,
+  type PopoverContentProps,
+  type PopoverTitleProps,
+  type PopoverDescriptionProps,
+  type PopoverBodyProps,
+  type PopoverFooterProps,
+  type PopoverCloseProps,
+} from './components/Popover';
+
+// Progress
+export {
+  Progress,
+  CircularProgress,
+  type ProgressProps,
+  type CircularProgressProps,
+} from './components/Progress';
+
+// Checkbox
+export { Checkbox, type CheckboxProps } from './components/Checkbox';
+
+// RadioGroup
+export {
+  RadioGroup,
+  type RadioGroupProps,
+  type RadioItemProps,
+} from './components/RadioGroup';
+
+// Separator
+export { Separator, type SeparatorProps } from './components/Separator';
+
+// Skeleton
+export {
+  Skeleton,
+  type SkeletonProps,
+  type SkeletonTextProps,
+  type SkeletonVariant,
+  type SkeletonSize,
+} from './components/Skeleton';
+
+// Table
+export {
+  Table,
+  createColumns,
+  type TableProps,
+  type TableColumn,
+  type ColumnDef,
+  type SortingState,
+  type RowSelectionState,
+} from './components/Table';
+
+// EmptyState
+export {
+  EmptyState,
+  type EmptyStateProps,
+  type EmptyStateAction,
+} from './components/EmptyState';
+
+// Toast
+export {
+  Toast,
+  ToastProvider,
+  useToast,
+  type ToastProps,
+  type ToastProviderProps,
+  type ToastData,
+  type ToastVariant,
+  type ToastPosition,
+} from './components/Toast';
+
+// Brand
+export { BRAND, type Brand } from './brand';

package/src/scss.d.ts

@@ -0,0 +1,4 @@
+declare module '*.module.scss' {
+  const classes: { [key: string]: string };
+  export default classes;
+}