@fragments-sdk/ui 0.1.0

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

@@ -0,0 +1,165 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// Positioner
+.positioner {
+  z-index: 50;
+  outline: none;
+}
+
+// Popup container
+.popup {
+  @include surface-elevated;
+  @include text-base;
+
+  min-width: 12rem;
+  max-width: 24rem;
+  padding: var(--fui-space-4, $fui-space-4);
+  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+
+  // Animation
+  opacity: 0;
+  transform: scale(0.95) translateY(-4px);
+  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(-4px);
+  }
+
+  &[data-ending-style] {
+    opacity: 0;
+    transform: scale(0.95) translateY(4px);
+  }
+
+  // Adjust animation direction based on side
+  &[data-side='top'] {
+    &[data-starting-style] {
+      transform: scale(0.95) translateY(4px);
+    }
+
+    &[data-ending-style] {
+      transform: scale(0.95) translateY(-4px);
+    }
+  }
+
+  &[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-5, $fui-space-5);
+  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;
+
+  position: absolute;
+  top: var(--fui-space-2, $fui-space-2);
+  right: var(--fui-space-2, $fui-space-2);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  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: 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;
+  }
+}
+
+// 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);
+}

package/src/components/Popover/index.tsx

@@ -0,0 +1,229 @@
+import * as React from 'react';
+import { Popover as BasePopover } from '@base-ui/react/popover';
+import styles from './Popover.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface PopoverProps {
+  children: React.ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  modal?: boolean;
+}
+
+export interface PopoverTriggerProps {
+  children: React.ReactNode;
+  asChild?: boolean;
+  className?: string;
+}
+
+export interface PopoverContentProps {
+  children: React.ReactNode;
+  size?: 'sm' | 'md' | 'lg';
+  side?: 'top' | 'bottom' | 'left' | 'right';
+  align?: 'start' | 'center' | 'end';
+  sideOffset?: number;
+  arrow?: boolean;
+  className?: string;
+}
+
+export interface PopoverTitleProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface PopoverDescriptionProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface PopoverBodyProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface PopoverFooterProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface PopoverCloseProps {
+  children?: React.ReactNode;
+  asChild?: boolean;
+  className?: string;
+}
+
+// ============================================
+// 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 }: PopoverTriggerProps) {
+  if (asChild) {
+    return (
+      <BasePopover.Trigger className={className} render={children as React.ReactElement}>
+        {null}
+      </BasePopover.Trigger>
+    );
+  }
+
+  return (
+    <BasePopover.Trigger className={className}>
+      {children}
+    </BasePopover.Trigger>
+  );
+}
+
+function PopoverContent({
+  children,
+  size = 'md',
+  side = 'bottom',
+  align = 'center',
+  sideOffset = 8,
+  arrow = false,
+  className,
+}: PopoverContentProps) {
+  const popupClasses = [
+    styles.popup,
+    size !== 'md' && styles[size],
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <BasePopover.Portal>
+      <BasePopover.Positioner
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        className={styles.positioner}
+      >
+        <BasePopover.Popup className={popupClasses}>
+          {children}
+          {arrow && <BasePopover.Arrow className={styles.arrow} />}
+        </BasePopover.Popup>
+      </BasePopover.Positioner>
+    </BasePopover.Portal>
+  );
+}
+
+function PopoverTitle({ children, className }: PopoverTitleProps) {
+  const classes = [styles.title, className].filter(Boolean).join(' ');
+  return <BasePopover.Title className={classes}>{children}</BasePopover.Title>;
+}
+
+function PopoverDescription({ children, className }: PopoverDescriptionProps) {
+  const classes = [styles.description, className].filter(Boolean).join(' ');
+  return (
+    <BasePopover.Description className={classes}>
+      {children}
+    </BasePopover.Description>
+  );
+}
+
+function PopoverBody({ children, className }: PopoverBodyProps) {
+  const classes = [styles.body, className].filter(Boolean).join(' ');
+  return <div className={classes}>{children}</div>;
+}
+
+function PopoverFooter({ children, className }: PopoverFooterProps) {
+  const classes = [styles.footer, className].filter(Boolean).join(' ');
+  return <div className={classes}>{children}</div>;
+}
+
+function PopoverClose({ children, asChild, className }: PopoverCloseProps) {
+  // Default close button (X icon)
+  if (!children) {
+    return (
+      <BasePopover.Close className={[styles.close, className].filter(Boolean).join(' ')}>
+        <CloseIcon />
+      </BasePopover.Close>
+    );
+  }
+
+  if (asChild) {
+    return (
+      <BasePopover.Close className={className} render={children as React.ReactElement}>
+        {null}
+      </BasePopover.Close>
+    );
+  }
+
+  return (
+    <BasePopover.Close 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,
+};

package/src/components/Progress/Progress.fragment.tsx

@@ -0,0 +1,142 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Progress, CircularProgress } from './index.js';
+
+export default defineSegment({
+  component: Progress,
+
+  meta: {
+    name: 'Progress',
+    description: 'Visual indicator of task completion or loading state. Available in linear and circular variants.',
+    category: 'feedback',
+    status: 'stable',
+    tags: ['progress', 'loading', 'indicator', 'percentage', 'status'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Showing upload/download progress',
+      'Displaying task completion percentage',
+      'Form completion indicators',
+      'Loading states with known duration',
+    ],
+    whenNot: [
+      'Unknown loading duration (use Spinner)',
+      'Step-based progress (use Stepper)',
+      'Status without percentage (use Badge)',
+    ],
+    guidelines: [
+      'Use determinate progress when you know the completion percentage',
+      'Use indeterminate for unknown durations',
+      'Include a label for context when the purpose isnt obvious',
+      'Use appropriate color variants for success/warning/danger states',
+    ],
+    accessibility: [
+      'Uses role="progressbar" with aria-valuenow',
+      'Label is associated with the progress bar',
+      'State changes are announced to screen readers',
+    ],
+  },
+
+  props: {
+    value: {
+      type: 'number',
+      description: 'Current progress value (0-100). Null for indeterminate.',
+    },
+    size: {
+      type: 'enum',
+      description: 'Size of the progress bar',
+      values: ['sm', 'md', 'lg'],
+      default: 'md',
+    },
+    variant: {
+      type: 'enum',
+      description: 'Color variant',
+      values: ['default', 'success', 'warning', 'danger'],
+      default: 'default',
+    },
+    label: {
+      type: 'string',
+      description: 'Label text above the progress bar',
+    },
+    showValue: {
+      type: 'boolean',
+      description: 'Show percentage value',
+      default: 'false',
+    },
+  },
+
+  relations: [
+    { component: 'Badge', relationship: 'alternative', note: 'Use Badge for status without percentage' },
+    { component: 'Alert', relationship: 'sibling', note: 'Use Alert for completion messages' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'value: number|null - progress percentage (null for indeterminate)',
+      'size: sm|md|lg - bar thickness',
+      'variant: default|success|warning|danger - color',
+      'label: string - descriptive label',
+      'showValue: boolean - display percentage',
+    ],
+    scenarioTags: [
+      'feedback.progress',
+      'status.loading',
+      'display.percentage',
+    ],
+    a11yRules: ['A11Y_PROGRESS_ROLE', 'A11Y_PROGRESS_VALUE'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic progress bar with percentage',
+      render: () => (
+        <Progress value={60} label="Uploading..." showValue />
+      ),
+    },
+    {
+      name: 'Variants',
+      description: 'Different color variants for different states',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+          <Progress value={75} variant="default" label="Processing" showValue />
+          <Progress value={100} variant="success" label="Complete" showValue />
+          <Progress value={80} variant="warning" label="Almost full" showValue />
+          <Progress value={95} variant="danger" label="Storage critical" showValue />
+        </div>
+      ),
+    },
+    {
+      name: 'Sizes',
+      description: 'Different progress bar sizes',
+      render: () => (
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>
+          <Progress value={50} size="sm" label="Small" />
+          <Progress value={50} size="md" label="Medium" />
+          <Progress value={50} size="lg" label="Large" />
+        </div>
+      ),
+    },
+    {
+      name: 'Indeterminate',
+      description: 'Loading state with unknown duration',
+      render: () => (
+        <Progress value={null} label="Loading..." />
+      ),
+    },
+    {
+      name: 'Circular',
+      description: 'Circular progress indicator',
+      render: () => (
+        <div style={{ display: 'flex', gap: '24px', alignItems: 'center' }}>
+          <CircularProgress value={25} size="sm" />
+          <CircularProgress value={50} size="md" showValue />
+          <CircularProgress value={75} size="lg" showValue variant="success" />
+          <CircularProgress value={null} size="md" />
+        </div>
+      ),
+    },
+  ],
+});

package/src/components/Progress/Progress.module.scss

@@ -0,0 +1,185 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// Root container
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-1, $fui-space-1);
+  width: 100%;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+}
+
+// Header with label and value
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+// Label text
+.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);
+}
+
+// Value display
+.value {
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-variant-numeric: tabular-nums;
+}
+
+// Track (background bar)
+.track {
+  position: relative;
+  width: 100%;
+  overflow: hidden;
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+}
+
+// Size variants for track
+.trackSm {
+  height: 4px;
+}
+
+.trackMd {
+  height: 8px;
+}
+
+.trackLg {
+  height: 12px;
+}
+
+// Indicator (filled portion)
+.indicator {
+  height: 100%;
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  transition: width var(--fui-transition-normal, $fui-transition-normal);
+}
+
+// Color variants
+.indicatorSuccess {
+  background-color: var(--fui-color-success, $fui-color-success);
+}
+
+.indicatorWarning {
+  background-color: var(--fui-color-warning, $fui-color-warning);
+}
+
+.indicatorDanger {
+  background-color: var(--fui-color-danger, $fui-color-danger);
+}
+
+// Indeterminate animation
+.indicatorIndeterminate {
+  width: 50% !important;
+  animation: indeterminate 1.5s ease-in-out infinite;
+}
+
+@keyframes indeterminate {
+  0% {
+    transform: translateX(-100%);
+  }
+  50% {
+    transform: translateX(100%);
+  }
+  100% {
+    transform: translateX(-100%);
+  }
+}
+
+// Complete state
+.root[data-complete] .indicator {
+  background-color: var(--fui-color-success, $fui-color-success);
+}
+
+// Circular progress variant
+.circular {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.circularSvg {
+  transform: rotate(-90deg);
+}
+
+.circularTrack {
+  stroke: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  fill: none;
+}
+
+.circularIndicator {
+  stroke: var(--fui-color-accent, $fui-color-accent);
+  fill: none;
+  stroke-linecap: round;
+  transition: stroke-dashoffset var(--fui-transition-normal, $fui-transition-normal);
+}
+
+.circularIndicatorSuccess {
+  stroke: var(--fui-color-success, $fui-color-success);
+}
+
+.circularIndicatorWarning {
+  stroke: var(--fui-color-warning, $fui-color-warning);
+}
+
+.circularIndicatorDanger {
+  stroke: var(--fui-color-danger, $fui-color-danger);
+}
+
+.circularIndicatorIndeterminate {
+  animation: circularIndeterminate 1.5s ease-in-out infinite;
+}
+
+@keyframes circularIndeterminate {
+  0% {
+    stroke-dashoffset: 280;
+    transform: rotate(0deg);
+  }
+  50% {
+    stroke-dashoffset: 70;
+  }
+  100% {
+    stroke-dashoffset: 280;
+    transform: rotate(360deg);
+  }
+}
+
+.circularValue {
+  position: absolute;
+  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);
+  font-variant-numeric: tabular-nums;
+}
+
+// Size variants for circular
+.circularSm {
+  width: 32px;
+  height: 32px;
+
+  .circularValue {
+    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  }
+}
+
+.circularMd {
+  width: 48px;
+  height: 48px;
+}
+
+.circularLg {
+  width: 64px;
+  height: 64px;
+
+  .circularValue {
+    font-size: var(--fui-font-size-base, $fui-font-size-base);
+  }
+}