@fragments-sdk/ui 0.3.0 → 0.5.0

package/src/components/Link/Link.fragment.tsx

@@ -0,0 +1,132 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Link } from '.';
+
+export default defineSegment({
+  component: Link,
+
+  meta: {
+    name: 'Link',
+    description: 'Styled anchor element for navigation. Supports internal and external links with consistent visual treatment.',
+    category: 'navigation',
+    status: 'stable',
+    tags: ['link', 'anchor', 'navigation', 'href', 'url'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Inline text links within paragraphs',
+      'Navigation links in footers or sidebars',
+      '"Forgot password?" or "Sign up" links in forms',
+      'External links to documentation or resources',
+    ],
+    whenNot: [
+      'Primary call-to-action (use Button instead)',
+      'Navigation tabs (use Tabs component)',
+      'Menu items in dropdowns (use Menu component)',
+      'Cards that link to detail pages (use Card with onClick)',
+    ],
+    guidelines: [
+      'Link text should describe the destination, not "click here"',
+      'Use external prop for links that open in new tabs',
+      'Use subtle variant for secondary/contextual links',
+      'Ensure links are distinguishable from regular text',
+    ],
+    accessibility: [
+      'Link text must be descriptive of the destination',
+      'External links should indicate they open in new window',
+      'Links must have visible focus indicators',
+      'Avoid using links that look like buttons without button semantics',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Link text content',
+      required: true,
+    },
+    href: {
+      type: 'string',
+      description: 'URL destination',
+    },
+    variant: {
+      type: 'enum',
+      description: 'Visual style variant',
+      values: ['default', 'subtle', 'muted'],
+      default: 'default',
+    },
+    underline: {
+      type: 'enum',
+      description: 'Underline behavior',
+      values: ['always', 'hover', 'none'],
+      default: 'hover',
+    },
+    external: {
+      type: 'boolean',
+      description: 'Opens in new tab with noopener noreferrer',
+      default: 'false',
+    },
+  },
+
+  relations: [
+    { component: 'Button', relationship: 'alternative', note: 'Use Button for primary actions, Link for navigation' },
+    { component: 'Text', relationship: 'parent', note: 'Links often appear within Text components' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'children: ReactNode - link text (required)',
+      'href: string - destination URL',
+      'variant: default|subtle|muted - visual style',
+      'underline: always|hover|none - underline behavior',
+      'external: boolean - opens in new tab',
+    ],
+    scenarioTags: [
+      'navigation.link',
+      'content.inline',
+      'action.navigate',
+    ],
+    a11yRules: ['A11Y_LINK_TEXT', 'A11Y_LINK_FOCUS'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Standard link with hover underline',
+      render: () => <Link href="#">Learn more about our services</Link>,
+    },
+    {
+      name: 'Variants',
+      description: 'Visual style options',
+      render: () => (
+        <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
+          <Link href="#" variant="default">Default</Link>
+          <Link href="#" variant="subtle">Subtle</Link>
+          <Link href="#" variant="muted">Muted</Link>
+        </div>
+      ),
+    },
+    {
+      name: 'Underline Styles',
+      description: 'Different underline behaviors',
+      render: () => (
+        <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
+          <Link href="#" underline="always">Always underlined</Link>
+          <Link href="#" underline="hover">Underline on hover</Link>
+          <Link href="#" underline="none">No underline</Link>
+        </div>
+      ),
+    },
+    {
+      name: 'External Link',
+      description: 'Link that opens in new tab',
+      render: () => (
+        <Link href="https://example.com" external>
+          View documentation ↗
+        </Link>
+      ),
+    },
+  ],
+});

package/src/components/Link/Link.module.scss

@@ -0,0 +1,67 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.link {
+  @include interactive-base;
+
+  display: inline;
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  text-decoration: none;
+  cursor: pointer;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+// Variants
+.default {
+  color: var(--fui-color-accent, $fui-color-accent);
+
+  &:hover {
+    color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+}
+
+.subtle {
+  color: var(--fui-text-primary, $fui-text-primary);
+
+  &:hover {
+    color: var(--fui-color-accent, $fui-color-accent);
+  }
+}
+
+.muted {
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+
+  &:hover {
+    color: var(--fui-text-secondary, $fui-text-secondary);
+  }
+}
+
+// Underline styles
+.underline-always {
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.underline-hover {
+  text-decoration: none;
+
+  &:hover {
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+}
+
+.underline-none {
+  text-decoration: none;
+
+  &:hover {
+    text-decoration: none;
+  }
+}

package/src/components/Link/index.tsx

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import styles from './Link.module.scss';
+import '../../styles/globals.scss';
+
+export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  children: React.ReactNode;
+  /** Visual variant */
+  variant?: 'default' | 'subtle' | 'muted';
+  /** Underline style */
+  underline?: 'always' | 'hover' | 'none';
+  /** Open in new tab (adds rel="noopener noreferrer") */
+  external?: boolean;
+  /** Additional class name */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+}
+
+export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
+  function Link(
+    {
+      children,
+      variant = 'default',
+      underline = 'hover',
+      external = false,
+      className,
+      style,
+      target,
+      rel,
+      ...props
+    },
+    ref
+  ) {
+    const classes = [
+      styles.link,
+      styles[variant],
+      styles[`underline-${underline}`],
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    // Handle external links
+    const externalProps = external
+      ? {
+          target: target || '_blank',
+          rel: rel || 'noopener noreferrer',
+        }
+      : { target, rel };
+
+    return (
+      <a ref={ref} className={classes} style={style} {...externalProps} {...props}>
+        {children}
+      </a>
+    );
+  }
+);

package/src/components/List/List.fragment.tsx

@@ -0,0 +1,152 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { List } from '.';
+import { Check, Star, ArrowRight } from '@phosphor-icons/react';
+
+export default defineSegment({
+  component: List,
+
+  meta: {
+    name: 'List',
+    description: 'Compound component for rendering ordered or unordered lists with consistent styling. Supports bullet, numbered, and icon-prefixed items.',
+    category: 'display',
+    status: 'stable',
+    tags: ['list', 'items', 'bullet', 'ordered', 'unordered'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Feature lists with checkmarks or icons',
+      'Ordered steps or instructions',
+      'Navigation lists in sidebars',
+      'Pricing plan feature comparisons',
+    ],
+    whenNot: [
+      'Interactive selection lists (use Menu or Select)',
+      'Data tables with columns (use Table)',
+      'Cards in a grid (use Grid with Card)',
+      'Navigation tabs (use Tabs)',
+    ],
+    guidelines: [
+      'Use as="ol" for sequential or numbered content',
+      'Use variant="icon" with meaningful icons for feature lists',
+      'Keep list items concise and parallel in structure',
+      'Use consistent icons within a single list',
+    ],
+    accessibility: [
+      'Use semantic list elements (ul, ol) for screen reader support',
+      'List items are automatically announced with count',
+      'Icons are decorative; ensure text conveys meaning',
+      'Avoid deeply nested lists (3+ levels)',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'List.Item components',
+      required: true,
+    },
+    as: {
+      type: 'enum',
+      description: 'List type',
+      values: ['ul', 'ol'],
+      default: 'ul',
+    },
+    variant: {
+      type: 'enum',
+      description: 'List style variant',
+      values: ['none', 'disc', 'decimal', 'icon'],
+      default: 'disc',
+    },
+    gap: {
+      type: 'enum',
+      description: 'Spacing between items',
+      values: ['none', 'xs', 'sm', 'md', 'lg'],
+      default: 'sm',
+    },
+  },
+
+  relations: [
+    { component: 'Icon', relationship: 'child', note: 'Use Icon as List.Item icon prop' },
+    { component: 'Stack', relationship: 'alternative', note: 'Use Stack for non-semantic vertical lists' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'children: List.Item[] - list items (required)',
+      'as: ul|ol - list type',
+      'variant: none|disc|decimal|icon - list style',
+      'gap: none|xs|sm|md|lg - item spacing',
+    ],
+    subComponents: [
+      {
+        name: 'List.Item',
+        props: [
+          'children: ReactNode - item content',
+          'icon: ReactNode - icon for variant="icon"',
+        ],
+      },
+    ],
+    scenarioTags: [
+      'content.list',
+      'layout.vertical',
+      'display.items',
+    ],
+    a11yRules: ['A11Y_LIST_SEMANTIC', 'A11Y_LIST_NESTING'],
+  },
+
+  variants: [
+    {
+      name: 'Bullet List',
+      description: 'Default unordered list with bullets',
+      render: () => (
+        <List variant="disc">
+          <List.Item>First item</List.Item>
+          <List.Item>Second item</List.Item>
+          <List.Item>Third item</List.Item>
+        </List>
+      ),
+    },
+    {
+      name: 'Numbered List',
+      description: 'Ordered list with numbers',
+      render: () => (
+        <List as="ol" variant="decimal">
+          <List.Item>Create your account</List.Item>
+          <List.Item>Configure your settings</List.Item>
+          <List.Item>Start building</List.Item>
+        </List>
+      ),
+    },
+    {
+      name: 'Icon List',
+      description: 'List with custom icons per item',
+      render: () => (
+        <List variant="icon">
+          <List.Item icon={<Check weight="bold" color="var(--fui-color-success)" />}>
+            Unlimited projects
+          </List.Item>
+          <List.Item icon={<Check weight="bold" color="var(--fui-color-success)" />}>
+            Priority support
+          </List.Item>
+          <List.Item icon={<Check weight="bold" color="var(--fui-color-success)" />}>
+            Advanced analytics
+          </List.Item>
+        </List>
+      ),
+    },
+    {
+      name: 'No Style',
+      description: 'Plain list without markers',
+      render: () => (
+        <List variant="none" gap="md">
+          <List.Item>Dashboard</List.Item>
+          <List.Item>Settings</List.Item>
+          <List.Item>Profile</List.Item>
+        </List>
+      ),
+    },
+  ],
+});

package/src/components/List/List.module.scss

@@ -0,0 +1,71 @@
+@use '../../tokens/variables' as *;
+
+.list {
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+// Variants
+.none {
+  list-style: none;
+}
+
+.disc {
+  list-style: disc;
+  padding-left: var(--fui-space-2, $fui-space-2);
+}
+
+.decimal {
+  list-style: decimal;
+  padding-left: var(--fui-space-2, $fui-space-2);
+}
+
+.icon {
+  list-style: none;
+}
+
+// Gap variants
+.gap-none {
+  gap: 0;
+}
+
+.gap-xs {
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+.gap-sm {
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+.gap-md {
+  gap: var(--fui-space-3, $fui-space-3);
+}
+
+.gap-lg {
+  gap: var(--fui-space-4, $fui-space-4);
+}
+
+// List item
+.item {
+  color: var(--fui-text-primary, $fui-text-primary);
+}
+
+.iconItem {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+.iconWrapper {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  line-height: 1.5;
+}
+
+.itemContent {
+  flex: 1;
+}

package/src/components/List/index.tsx

@@ -0,0 +1,106 @@
+import * as React from 'react';
+import styles from './List.module.scss';
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface ListProps extends React.HTMLAttributes<HTMLUListElement | HTMLOListElement> {
+  children: React.ReactNode;
+  /** List type */
+  as?: 'ul' | 'ol';
+  /** List style variant */
+  variant?: 'none' | 'disc' | 'decimal' | 'icon';
+  /** Spacing between items */
+  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg';
+}
+
+export interface ListItemProps extends React.HTMLAttributes<HTMLLIElement> {
+  children: React.ReactNode;
+  /** Icon to display (only used with variant="icon") */
+  icon?: React.ReactNode;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface ListContextValue {
+  variant: NonNullable<ListProps['variant']>;
+}
+
+const ListContext = React.createContext<ListContextValue>({ variant: 'disc' });
+
+function useListContext() {
+  return React.useContext(ListContext);
+}
+
+// ============================================
+// Components
+// ============================================
+
+function ListRoot({
+  children,
+  as: Component = 'ul',
+  variant = 'disc',
+  gap = 'sm',
+  className,
+  style,
+  ...htmlProps
+}: ListProps) {
+  const classes = [
+    styles.list,
+    styles[variant],
+    styles[`gap-${gap}`],
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <ListContext.Provider value={{ variant }}>
+      <Component {...htmlProps} className={classes} style={style}>
+        {children}
+      </Component>
+    </ListContext.Provider>
+  );
+}
+
+function ListItem({ children, icon, className, style, ...htmlProps }: ListItemProps) {
+  const { variant } = useListContext();
+
+  const classes = [
+    styles.item,
+    variant === 'icon' && styles.iconItem,
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  if (variant === 'icon' && icon) {
+    return (
+      <li {...htmlProps} className={classes} style={style}>
+        <span className={styles.iconWrapper}>{icon}</span>
+        <span className={styles.itemContent}>{children}</span>
+      </li>
+    );
+  }
+
+  return (
+    <li {...htmlProps} className={classes} style={style}>
+      {children}
+    </li>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const List = Object.assign(ListRoot, {
+  Item: ListItem,
+});
+
+// Re-export individual components for tree-shaking
+export { ListRoot, ListItem, useListContext };