@usefragments/ui 1.0.0

package/src/components/Loading/Loading.module.scss

@@ -0,0 +1,259 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Loading Base
+// ============================================
+
+.loading {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+// ============================================
+// Sizes
+// ============================================
+
+// Sizes ride the shared `--fui-icon-*` ladder. The step names are offset by one
+// (sm→icon-sm, md→icon-lg, lg→icon-xl, xl→icon-2xl), intentionally skipping
+// icon-md so the rendered px stays 14/20/24/32 for existing consumers.
+.sm {
+  --loading-size: var(--fui-icon-sm, #{$fui-icon-sm});  // 14px
+}
+
+.md {
+  --loading-size: var(--fui-icon-lg, #{$fui-icon-lg});  // 20px
+}
+
+.lg {
+  --loading-size: var(--fui-icon-xl, #{$fui-icon-xl});  // 24px
+}
+
+.xl {
+  --loading-size: var(--fui-icon-2xl, #{$fui-icon-2xl});  // 32px
+}
+
+// ============================================
+// Colors
+// ============================================
+
+.color-accent {
+  color: var(--fui-color-accent, $fui-color-accent);
+}
+
+.color-current {
+  color: currentColor;
+}
+
+.color-muted {
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+}
+
+// ============================================
+// Layout Modifiers
+// ============================================
+
+.centered {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.fill {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+// ============================================
+// Spinner Variant
+// ============================================
+
+.spinnerIcon {
+  width: var(--loading-size);
+  height: var(--loading-size);
+  animation: spin 0.8s linear infinite;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+    opacity: 0.7;
+  }
+}
+
+@keyframes spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+// ============================================
+// Dots Variant
+// ============================================
+
+.dots {
+  display: flex;
+  align-items: center;
+  gap: calc(var(--loading-size) * 0.3);
+}
+
+.dot {
+  width: calc(var(--loading-size) * 0.35);
+  height: calc(var(--loading-size) * 0.35);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  background-color: currentColor;
+  animation: bounce 1.4s ease-in-out infinite;
+
+  &:nth-child(1) {
+    animation-delay: 0s;
+  }
+
+  &:nth-child(2) {
+    animation-delay: 0.2s;
+  }
+
+  &:nth-child(3) {
+    animation-delay: 0.4s;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+    opacity: 0.6;
+  }
+}
+
+@keyframes bounce {
+  0%,
+  60%,
+  100% {
+    transform: translateY(0);
+    opacity: 0.4;
+  }
+  30% {
+    transform: translateY(-30%);
+    opacity: 1;
+  }
+}
+
+// ============================================
+// Pulse Variant
+// ============================================
+
+.pulse {
+  position: relative;
+  width: var(--loading-size);
+  height: var(--loading-size);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.pulseRing {
+  position: absolute;
+  width: 100%;
+  height: 100%;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  background-color: currentColor;
+  opacity: 0.3;
+  animation: pulseRing 1.5s ease-out infinite;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+    opacity: 0.2;
+  }
+}
+
+.pulseDot {
+  width: 50%;
+  height: 50%;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  background-color: currentColor;
+  z-index: 1;
+}
+
+@keyframes pulseRing {
+  0% {
+    transform: scale(0.5);
+    opacity: 0.5;
+  }
+  100% {
+    transform: scale(1.5);
+    opacity: 0;
+  }
+}
+
+// ============================================
+// Overlay
+// ============================================
+
+.overlayBackdrop {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--fui-backdrop, $fui-backdrop);
+  z-index: 50;
+}
+
+.overlay {
+  // Additional styling if needed when in overlay mode
+}
+
+// ============================================
+// Inline Variant
+// ============================================
+
+.inline {
+  display: inline-flex;
+  align-items: center;
+  vertical-align: middle;
+}
+
+.inline-sm {
+  --inline-size: 0.875em;  // Relative to surrounding text
+}
+
+.inline-md {
+  --inline-size: 1.125em;
+}
+
+.inlineSpinner {
+  width: var(--inline-size);
+  height: var(--inline-size);
+  animation: spin 0.8s linear infinite;
+  color: currentColor;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+    opacity: 0.7;
+  }
+}
+
+// ============================================
+// Screen (Full-screen loading)
+// ============================================
+
+.screen {
+  position: fixed;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--fui-space-3, $fui-space-3);
+  background-color: var(--fui-bg-primary, $fui-bg-primary);
+  z-index: 100;
+}
+
+.screenLabel {
+  @include text-base;
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+}

package/src/components/Loading/Loading.stories.tsx

@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Loading } from '.';
+
+/**
+ * Loading indicator for showing progress or waiting states. Offers spinner,
+ * dots, and pulse variants plus `Loading.Inline` and `Loading.Screen` helpers.
+ */
+const meta = {
+  title: 'Feedback/Loading',
+  component: Loading,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Versatile loading indicator with spinner, dots, and pulse variants.',
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg', 'xl'],
+      description: 'Size of the loading indicator',
+    },
+    variant: {
+      control: 'select',
+      options: ['spinner', 'dots', 'pulse'],
+      description: 'Visual style of the loading animation',
+    },
+    color: {
+      control: 'select',
+      options: ['accent', 'current', 'muted'],
+      description: 'Color variant',
+    },
+    centered: { control: 'boolean' },
+    fill: { control: 'boolean' },
+    overlay: { control: 'boolean' },
+  },
+  args: {
+    size: 'md',
+    variant: 'spinner',
+    color: 'accent',
+    label: 'Loading...',
+  },
+} satisfies Meta<typeof Loading>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Spinner: Story = {
+  args: { variant: 'spinner' },
+};
+
+export const Dots: Story = {
+  args: { variant: 'dots' },
+};
+
+export const Pulse: Story = {
+  args: { variant: 'pulse' },
+};
+
+export const Large: Story = {
+  args: { variant: 'spinner', size: 'xl' },
+};
+
+export const Muted: Story = {
+  args: { variant: 'spinner', color: 'muted' },
+};

package/src/components/Loading/index.tsx

@@ -0,0 +1,229 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Loading.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export type LoadingSize = 'sm' | 'md' | 'lg' | 'xl';
+export type LoadingVariant = 'spinner' | 'dots' | 'pulse';
+
+export interface LoadingProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Size of the loading indicator */
+  size?: LoadingSize;
+  /** Visual style of the loading indicator */
+  variant?: LoadingVariant;
+  /** Accessible label for screen readers */
+  label?: string;
+  /** Whether to center the loading indicator in its container */
+  centered?: boolean;
+  /** Whether to fill the parent container */
+  fill?: boolean;
+  /** Whether to show the loading indicator with a backdrop overlay */
+  overlay?: boolean;
+  /** Color variant - uses accent color by default, 'current' inherits text color */
+  color?: 'accent' | 'current' | 'muted';
+}
+
+export interface LoadingInlineProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Size of the loading indicator */
+  size?: 'sm' | 'md';
+  /** Accessible label */
+  label?: string;
+}
+
+export interface LoadingScreenProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Loading indicator size */
+  size?: LoadingSize;
+  /** Loading indicator variant */
+  variant?: LoadingVariant;
+  /** Optional label text to display */
+  label?: string;
+  /** Whether to show the label text visually */
+  showLabel?: boolean;
+}
+
+// ============================================
+// Icons/Animations
+// ============================================
+
+function SpinnerIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      className={className}
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M21 12a9 9 0 1 1-6.219-8.56" />
+    </svg>
+  );
+}
+
+function DotsAnimation({ className }: { className?: string }) {
+  return (
+    <span className={className} aria-hidden="true">
+      <span className={styles.dot} />
+      <span className={styles.dot} />
+      <span className={styles.dot} />
+    </span>
+  );
+}
+
+function PulseAnimation({ className }: { className?: string }) {
+  return (
+    <span className={className} aria-hidden="true">
+      <span className={styles.pulseRing} />
+      <span className={styles.pulseDot} />
+    </span>
+  );
+}
+
+// ============================================
+// Components
+// ============================================
+
+const LoadingRoot = React.forwardRef<HTMLDivElement, LoadingProps>(
+  function LoadingRoot(
+    {
+      size = 'md',
+      variant = 'spinner',
+      label = 'Loading...',
+      centered = false,
+      fill = false,
+      overlay = false,
+      color = 'accent',
+      className,
+      ...htmlProps
+    },
+    ref
+  ) {
+    const classes = [
+      styles.loading,
+      styles[size],
+      styles[variant],
+      styles[`color-${color}`],
+      centered && styles.centered,
+      fill && styles.fill,
+      overlay && styles.overlay,
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const animation = variant === 'dots'
+      ? <DotsAnimation className={styles.dots} />
+      : variant === 'pulse'
+        ? <PulseAnimation className={styles.pulse} />
+        : <SpinnerIcon className={styles.spinnerIcon} />;
+
+    const content = (
+      <div
+        ref={ref}
+        className={classes}
+        role="status"
+        aria-label={label}
+        aria-live="polite"
+        {...htmlProps}
+      >
+        {animation}
+      </div>
+    );
+
+    if (overlay) {
+      return (
+        <div className={styles.overlayBackdrop}>
+          {content}
+        </div>
+      );
+    }
+
+    return content;
+  }
+);
+
+// ============================================
+// Loading.Inline - Inline text loading indicator
+// ============================================
+
+function LoadingInline({
+  size = 'sm',
+  label = 'Loading...',
+  className,
+  ...htmlProps
+}: LoadingInlineProps) {
+  const classes = [
+    styles.inline,
+    styles[`inline-${size}`],
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <span
+      className={classes}
+      role="status"
+      aria-label={label}
+      {...htmlProps}
+    >
+      <SpinnerIcon className={styles.inlineSpinner} />
+    </span>
+  );
+}
+
+// ============================================
+// Loading.Screen - Full-screen loading state
+// ============================================
+
+function LoadingScreen({
+  size = 'lg',
+  variant = 'spinner',
+  label = 'Loading...',
+  showLabel = false,
+  className,
+  ...htmlProps
+}: LoadingScreenProps) {
+  const classes = [
+    styles.screen,
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <div
+      className={classes}
+      role="status"
+      aria-label={label}
+      aria-live="polite"
+      {...htmlProps}
+    >
+      <LoadingRoot size={size} variant={variant} label={label} />
+      {showLabel && <span className={styles.screenLabel}>{label}</span>}
+    </div>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Loading = Object.assign(LoadingRoot, {
+  Inline: LoadingInline,
+  Screen: LoadingScreen,
+});
+
+// Re-export individual components for tree-shaking
+export {
+  LoadingRoot,
+  LoadingInline,
+  LoadingScreen,
+};

package/src/components/Markdown/Markdown.contract.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Markdown",
+  "description": "Renders markdown strings as styled prose using react-markdown and remark-gfm. Supports headings, lists, tables, code blocks, blockquotes, and more.",
+  "category": "display",
+  "tags": [
+    "markdown",
+    "prose",
+    "content",
+    "text",
+    "ai",
+    "chat"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Markdown/index.tsx",
+  "exportName": "Markdown",
+  "propsSummary": [
+    "content: string (required)",
+    "components: object",
+    "className: string"
+  ],
+  "props": {
+    "content": {
+      "type": "string",
+      "description": "Markdown string to render",
+      "required": true
+    },
+    "components": {
+      "type": "object",
+      "description": "Override map for markdown element components (e.g., { h1: MyHeading }). Accepts custom renderer component signatures used by react-markdown",
+      "required": false
+    },
+    "className": {
+      "type": "string",
+      "description": "Additional CSS class name",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Rendering AI/LLM response content",
+      "Displaying user-authored markdown text",
+      "Showing documentation or readme content",
+      "Rich text display without a WYSIWYG editor"
+    ],
+    "whenNot": [
+      "Plain text without formatting (use Text)",
+      "Editing markdown (use a markdown editor component)",
+      "Rendering trusted HTML directly (use dangerouslySetInnerHTML)"
+    ],
+    "guidelines": [
+      "Install react-markdown and remark-gfm as peer dependencies",
+      "Use the components prop to override default element rendering",
+      "Content is sanitized by react-markdown by default",
+      "Falls back to plain text paragraphs if react-markdown is not installed",
+      "Standard div props (id, style, aria-*, data-*) are forwarded to the Markdown wrapper"
+    ],
+    "accessibility": [
+      "Rendered HTML follows semantic structure (headings, lists, tables)",
+      "Links are rendered as proper anchor elements",
+      "Images include alt text from markdown syntax",
+      "Tables use proper th/td structure for screen readers"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic markdown with headings, paragraphs, inline code, lists, and blockquote",
+      "code": "<Markdown content={`# Hello World\n\nThis is a paragraph with **bold text** and *italic text*.\n\nHere is some \\`inline code\\` within a sentence.\n\n- First item\n- Second item\n- Third item\n\n> A blockquote for emphasis.\n`} />"
+    },
+    {
+      "name": "GFM Table",
+      "description": "GitHub Flavored Markdown with tables and task lists",
+      "code": "<Markdown content={`## Data Overview\n\n| Feature    | Status    | Priority |\n|------------|-----------|----------|\n| Markdown   | Done      | High     |\n| Tables     | Done      | Medium   |\n| Task Lists | Planned   | Low      |\n\nNotes:\n- [x] Support GFM tables\n- [x] Support task lists\n- [ ] Syntax highlighting\n`} />"
+    },
+    {
+      "name": "Code Block",
+      "description": "Markdown with fenced code blocks and inline code",
+      "code": "<Markdown content={`## Code Example\\n\\nHere is a JavaScript function:\\n\\n```js\\nfunction greet(name) {\\n  return \\`Hello, ${name}!\\`;\\n}\\n```\\n\\nAnd some inline code: \\`const x = 42;\\``} />"
+    },
+    {
+      "name": "Mixed Content",
+      "description": "Complex markdown mixing headings, lists, tables, blockquotes, and task lists",
+      "code": "<Markdown content={`# Project Update\n\n## Summary\n\nThe project is progressing well. Here are the **key highlights**:\n\n1. Completed the *design system* components\n2. Added markdown rendering support\n3. Integrated with the documentation site\n\n### Performance Metrics\n\n| Metric      | Before | After |\n|-------------|--------|-------|\n| Bundle Size | 142kb  | 98kb  |\n| Load Time   | 1.2s   | 0.8s  |\n| Lighthouse  | 72     | 95    |\n\n> These improvements were achieved through tree-shaking and code splitting.\n\n### Next Steps\n\n- [ ] Add syntax highlighting\n- [ ] Support custom themes\n- [x] GFM table support\n`} />"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Text",
+      "relationship": "alternative",
+      "note": "Use Text for plain, non-markdown text"
+    },
+    {
+      "component": "CodeBlock",
+      "relationship": "complementary",
+      "note": "CodeBlock can be used via components prop for syntax highlighting"
+    },
+    {
+      "component": "Message",
+      "relationship": "parent",
+      "note": "Message wraps Markdown when markdown prop is true"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "content: string - Markdown string to render",
+      "components: object - Override map for element components (react-markdown renderer components)",
+      "className: string - Additional CSS class",
+      "Forwards standard HTML div attributes to the wrapper element"
+    ],
+    "a11yRules": [
+      "A11Y_SEMANTIC_HTML"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:06.091Z"
+  }
+}