@fragments-sdk/ui 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Customizable UI components built on Base UI headless primitives",
   "type": "module",
   "main": "src/index.ts",
@@ -10,7 +10,9 @@
     ".": "./src/index.ts",
     "./styles": "./src/styles/globals.scss",
     "./tokens": "./src/tokens/_variables.scss",
-    "./brand": "./src/brand.ts"
+    "./mixins": "./src/tokens/_mixins.scss",
+    "./brand": "./src/brand.ts",
+    "./fragments.json": "./fragments.json"
   },
   "publishConfig": {
     "access": "public"
@@ -21,7 +23,10 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.0.0",
-    "@tanstack/react-table": "^8.21.3"
+    "@phosphor-icons/react": "^2.1.10",
+    "@tanstack/react-table": "^8.21.3",
+    "react-colorful": "^5.6.1",
+    "shiki": "^3.0.0"
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
@@ -30,7 +35,7 @@
     "react-dom": "^19.0.0",
     "sass": "^1.83.0",
     "typescript": "^5.7.0",
-    "@fragments-sdk/cli": "0.3.3"
+    "@fragments-sdk/cli": "0.4.0"
   },
   "files": [
     "src",

package/src/components/Accordion/Accordion.fragment.tsx

@@ -0,0 +1,186 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Accordion } from './index.js';
+
+export default defineSegment({
+  component: Accordion,
+
+  meta: {
+    name: 'Accordion',
+    description: 'Vertically stacked, collapsible content sections. Use for organizing related content that can be progressively disclosed.',
+    category: 'layout',
+    status: 'stable',
+    tags: ['accordion', 'collapse', 'expand', 'disclosure', 'faq'],
+    since: '0.2.0',
+  },
+
+  usage: {
+    when: [
+      'FAQ pages with multiple questions and answers',
+      'Settings panels with grouped options',
+      'Long forms that benefit from progressive disclosure',
+      'Navigation menus with nested items',
+    ],
+    whenNot: [
+      'Primary content that all users need to see',
+      'Very short content (just display inline)',
+      'Sequential steps (use Stepper or wizard)',
+      'Tab-like navigation (use Tabs instead)',
+    ],
+    guidelines: [
+      'Keep section headers concise and descriptive',
+      'Use single mode when only one section should be open at a time',
+      'Use multiple mode when users may need to compare sections',
+      'Consider defaulting important sections to open',
+      'Avoid nesting accordions more than one level deep',
+    ],
+    accessibility: [
+      'Keyboard navigation with Enter/Space to toggle',
+      'Arrow keys navigate between accordion headers',
+      'Uses proper ARIA expanded/controls attributes',
+      'Focus is visible on accordion triggers',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Accordion items (use Accordion.Item with Accordion.Trigger and Accordion.Content)',
+      required: true,
+    },
+    type: {
+      type: 'enum',
+      description: 'Whether one or multiple items can be open',
+      values: ['single', 'multiple'],
+      default: 'single',
+    },
+    value: {
+      type: 'string | string[]',
+      description: 'Controlled open item(s)',
+    },
+    defaultValue: {
+      type: 'string | string[]',
+      description: 'Initially open item(s) for uncontrolled usage',
+    },
+    onValueChange: {
+      type: 'function',
+      description: 'Called when open items change',
+    },
+    collapsible: {
+      type: 'boolean',
+      description: 'Whether all items can be closed (single mode only)',
+      default: 'false',
+    },
+  },
+
+  relations: [
+    { component: 'Tabs', relationship: 'alternative', note: 'Use Tabs for horizontal switching between related views' },
+    { component: 'Dialog', relationship: 'alternative', note: 'Use Dialog for focused content that interrupts the flow' },
+    { component: 'Card', relationship: 'complementary', note: 'Accordion items can contain Card-like content' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'type: single|multiple - controls how many items can be open',
+      'value: string|string[] - controlled open items',
+      'defaultValue: string|string[] - initial open items',
+      'collapsible: boolean - allow all closed in single mode',
+    ],
+    scenarioTags: [
+      'layout.disclosure',
+      'navigation.collapsible',
+      'content.faq',
+    ],
+    a11yRules: ['A11Y_DISCLOSURE_KEYBOARD', 'A11Y_FOCUS_VISIBLE'],
+  },
+
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['Item', 'Trigger', 'Content'],
+    requiredChildren: ['Item'],
+    commonPatterns: [
+      '<Accordion type="single" collapsible><Accordion.Item value="item-1"><Accordion.Trigger>{title}</Accordion.Trigger><Accordion.Content>{content}</Accordion.Content></Accordion.Item></Accordion>',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Basic',
+      description: 'Single accordion with collapsible sections',
+      render: () => (
+        <Accordion type="single" collapsible defaultValue="item-1">
+          <Accordion.Item value="item-1">
+            <Accordion.Trigger>What is Fragments UI?</Accordion.Trigger>
+            <Accordion.Content>
+              Fragments UI is a modern React component library built on Base UI primitives, providing accessible and customizable components.
+            </Accordion.Content>
+          </Accordion.Item>
+          <Accordion.Item value="item-2">
+            <Accordion.Trigger>How do I install it?</Accordion.Trigger>
+            <Accordion.Content>
+              Install via npm or pnpm: <code>pnpm add @fragments-sdk/ui</code>
+            </Accordion.Content>
+          </Accordion.Item>
+          <Accordion.Item value="item-3">
+            <Accordion.Trigger>Is it accessible?</Accordion.Trigger>
+            <Accordion.Content>
+              Yes! All components follow WAI-ARIA guidelines and support keyboard navigation.
+            </Accordion.Content>
+          </Accordion.Item>
+        </Accordion>
+      ),
+    },
+    {
+      name: 'Multiple Open',
+      description: 'Allows multiple sections to be open simultaneously',
+      render: () => (
+        <Accordion type="multiple" defaultValue={['features', 'pricing']}>
+          <Accordion.Item value="features">
+            <Accordion.Trigger>Features</Accordion.Trigger>
+            <Accordion.Content>
+              Comprehensive component library with theming support, accessibility built-in, and TypeScript-first development.
+            </Accordion.Content>
+          </Accordion.Item>
+          <Accordion.Item value="pricing">
+            <Accordion.Trigger>Pricing</Accordion.Trigger>
+            <Accordion.Content>
+              Free and open source. MIT licensed for both personal and commercial use.
+            </Accordion.Content>
+          </Accordion.Item>
+          <Accordion.Item value="support">
+            <Accordion.Trigger>Support</Accordion.Trigger>
+            <Accordion.Content>
+              Community support via GitHub issues and discussions.
+            </Accordion.Content>
+          </Accordion.Item>
+        </Accordion>
+      ),
+    },
+    {
+      name: 'With Disabled',
+      description: 'Accordion with a disabled item',
+      render: () => (
+        <Accordion type="single" collapsible>
+          <Accordion.Item value="available">
+            <Accordion.Trigger>Available Section</Accordion.Trigger>
+            <Accordion.Content>
+              This section can be expanded and collapsed.
+            </Accordion.Content>
+          </Accordion.Item>
+          <Accordion.Item value="disabled" disabled>
+            <Accordion.Trigger>Disabled Section</Accordion.Trigger>
+            <Accordion.Content>
+              This content is not accessible because the item is disabled.
+            </Accordion.Content>
+          </Accordion.Item>
+          <Accordion.Item value="another">
+            <Accordion.Trigger>Another Section</Accordion.Trigger>
+            <Accordion.Content>
+              This section is also available for interaction.
+            </Accordion.Content>
+          </Accordion.Item>
+        </Accordion>
+      ),
+    },
+  ],
+});

package/src/components/Accordion/Accordion.module.scss

@@ -0,0 +1,111 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.accordion {
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  width: 100%;
+}
+
+.item {
+  border-bottom: 1px solid var(--fui-border, $fui-border);
+
+  &:first-child {
+    border-top: 1px solid var(--fui-border, $fui-border);
+  }
+
+  &[data-disabled] {
+    opacity: 0.5;
+    pointer-events: none;
+  }
+}
+
+// Reset heading styles (semantic wrapper for trigger)
+.heading {
+  margin: 0;
+  font-size: inherit;
+  font-weight: inherit;
+}
+
+.trigger {
+  @include button-reset;
+  @include interactive-base;
+
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: var(--fui-padding-item-md, $fui-padding-item-md) 0;
+  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);
+  text-align: left;
+
+  &:hover:not(:disabled) {
+    text-decoration: underline;
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+    border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  }
+}
+
+.triggerContent {
+  flex: 1;
+}
+
+.chevron {
+  flex-shrink: 0;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  transition: transform var(--fui-transition-normal, $fui-transition-normal);
+
+  [data-state='open'] & {
+    transform: rotate(180deg);
+  }
+}
+
+.content {
+  overflow: hidden;
+
+  // Base UI Collapsible handles height animation via CSS
+  // We need to handle the collapsed state
+  &[data-state='closed'] {
+    height: 0;
+  }
+
+  &[data-state='open'] {
+    height: auto;
+  }
+
+  // Smooth animation using Base UI's built-in transition
+  &[data-starting-style],
+  &[data-ending-style] {
+    transition:
+      height var(--fui-transition-normal, $fui-transition-normal),
+      padding var(--fui-transition-normal, $fui-transition-normal);
+  }
+}
+
+.contentInner {
+  padding-bottom: var(--fui-padding-item-md, $fui-padding-item-md);
+  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);
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .chevron {
+    transition: none;
+  }
+
+  .content {
+    &[data-starting-style],
+    &[data-ending-style] {
+      transition: none;
+    }
+  }
+}

package/src/components/Accordion/index.tsx

@@ -0,0 +1,271 @@
+'use client';
+
+import * as React from 'react';
+import { Collapsible as BaseCollapsible } from '@base-ui/react/collapsible';
+import styles from './Accordion.module.scss';
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export type AccordionValue = string | string[];
+
+export interface AccordionProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'defaultValue'> {
+  children: React.ReactNode;
+  /** Allow multiple items to be open at once */
+  type?: 'single' | 'multiple';
+  /** Controlled value - string for single, string[] for multiple */
+  value?: AccordionValue;
+  /** Default value for uncontrolled usage */
+  defaultValue?: AccordionValue;
+  /** Callback when value changes */
+  onValueChange?: (value: AccordionValue) => void;
+  /** Whether items can be fully collapsed (only for type="single") */
+  collapsible?: boolean;
+  /**
+   * Heading level for accordion triggers (for semantic HTML).
+   * The trigger will be wrapped in an <h{level}> element.
+   * @default 3
+   */
+  headingLevel?: 2 | 3 | 4 | 5 | 6;
+}
+
+export interface AccordionItemProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Unique value for this item */
+  value: string;
+  /** Disable this item */
+  disabled?: boolean;
+}
+
+export interface AccordionTriggerProps extends React.HTMLAttributes<HTMLButtonElement> {
+  children: React.ReactNode;
+}
+
+export interface AccordionContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface AccordionContextValue {
+  type: 'single' | 'multiple';
+  openItems: string[];
+  toggle: (value: string) => void;
+  collapsible: boolean;
+  headingLevel: 2 | 3 | 4 | 5 | 6;
+}
+
+const AccordionContext = React.createContext<AccordionContextValue | null>(null);
+
+interface AccordionItemContextValue {
+  value: string;
+  isOpen: boolean;
+  disabled: boolean;
+  triggerId: string;
+  contentId: string;
+}
+
+const AccordionItemContext = React.createContext<AccordionItemContextValue | null>(null);
+
+function useAccordionContext() {
+  const context = React.useContext(AccordionContext);
+  if (!context) {
+    throw new Error('Accordion components must be used within an Accordion');
+  }
+  return context;
+}
+
+function useAccordionItemContext() {
+  const context = React.useContext(AccordionItemContext);
+  if (!context) {
+    throw new Error('Accordion.Trigger/Content must be used within an Accordion.Item');
+  }
+  return context;
+}
+
+// ============================================
+// Components
+// ============================================
+
+function AccordionRoot({
+  children,
+  type = 'single',
+  value,
+  defaultValue,
+  onValueChange,
+  collapsible = false,
+  headingLevel = 3,
+  className,
+  ...htmlProps
+}: AccordionProps) {
+  // Normalize value to array for internal handling
+  const normalizeValue = (val: AccordionValue | undefined): string[] => {
+    if (val === undefined) return [];
+    return Array.isArray(val) ? val : [val];
+  };
+
+  const [openItems, setOpenItems] = React.useState<string[]>(() =>
+    normalizeValue(defaultValue)
+  );
+
+  // Use controlled value if provided
+  const controlledOpenItems = value !== undefined ? normalizeValue(value) : undefined;
+  const currentOpenItems = controlledOpenItems ?? openItems;
+
+  const toggle = React.useCallback((itemValue: string) => {
+    const newItems = (() => {
+      if (type === 'single') {
+        // For single, toggle or set new item
+        if (currentOpenItems.includes(itemValue)) {
+          return collapsible ? [] : currentOpenItems;
+        }
+        return [itemValue];
+      } else {
+        // For multiple, toggle item in array
+        if (currentOpenItems.includes(itemValue)) {
+          return currentOpenItems.filter(v => v !== itemValue);
+        }
+        return [...currentOpenItems, itemValue];
+      }
+    })();
+
+    if (controlledOpenItems === undefined) {
+      setOpenItems(newItems);
+    }
+
+    if (onValueChange) {
+      onValueChange(type === 'single' ? (newItems[0] ?? '') : newItems);
+    }
+  }, [type, currentOpenItems, collapsible, controlledOpenItems, onValueChange]);
+
+  const classes = [styles.accordion, className].filter(Boolean).join(' ');
+
+  return (
+    <AccordionContext.Provider value={{ type, openItems: currentOpenItems, toggle, collapsible, headingLevel }}>
+      <div {...htmlProps} className={classes} data-orientation="vertical" role="region">
+        {children}
+      </div>
+    </AccordionContext.Provider>
+  );
+}
+
+function AccordionItem({
+  children,
+  value,
+  disabled = false,
+  className,
+  ...htmlProps
+}: AccordionItemProps) {
+  const { openItems } = useAccordionContext();
+  const isOpen = openItems.includes(value);
+  const baseId = React.useId();
+  const triggerId = `accordion-trigger-${baseId}`;
+  const contentId = `accordion-content-${baseId}`;
+
+  const classes = [
+    styles.item,
+    isOpen && styles.itemOpen,
+    disabled && styles.itemDisabled,
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <AccordionItemContext.Provider value={{ value, isOpen, disabled, triggerId, contentId }}>
+      <BaseCollapsible.Root open={isOpen} disabled={disabled}>
+        <div {...htmlProps} className={classes} data-state={isOpen ? 'open' : 'closed'} data-disabled={disabled || undefined}>
+          {children}
+        </div>
+      </BaseCollapsible.Root>
+    </AccordionItemContext.Provider>
+  );
+}
+
+function AccordionTrigger({
+  children,
+  className,
+}: AccordionTriggerProps) {
+  const { toggle, headingLevel } = useAccordionContext();
+  const { value, isOpen, disabled, triggerId, contentId } = useAccordionItemContext();
+
+  const handleClick = () => {
+    if (!disabled) {
+      toggle(value);
+    }
+  };
+
+  const classes = [styles.trigger, className].filter(Boolean).join(' ');
+
+  // Create the heading element dynamically based on headingLevel
+  const HeadingTag = `h${headingLevel}` as 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
+  return (
+    <HeadingTag className={styles.heading}>
+      <BaseCollapsible.Trigger
+        id={triggerId}
+        className={classes}
+        onClick={handleClick}
+        aria-expanded={isOpen}
+        aria-controls={contentId}
+        data-state={isOpen ? 'open' : 'closed'}
+        disabled={disabled}
+      >
+        <span className={styles.triggerContent}>{children}</span>
+        <svg
+          className={styles.chevron}
+          width="16"
+          height="16"
+          viewBox="0 0 16 16"
+          fill="none"
+          aria-hidden="true"
+        >
+          <path
+            d="M4 6L8 10L12 6"
+            stroke="currentColor"
+            strokeWidth="1.5"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </svg>
+      </BaseCollapsible.Trigger>
+    </HeadingTag>
+  );
+}
+
+function AccordionContent({
+  children,
+  className,
+}: AccordionContentProps) {
+  const { isOpen, triggerId, contentId } = useAccordionItemContext();
+
+  const classes = [styles.content, className].filter(Boolean).join(' ');
+
+  return (
+    <BaseCollapsible.Panel
+      id={contentId}
+      className={classes}
+      data-state={isOpen ? 'open' : 'closed'}
+      role="region"
+      aria-labelledby={triggerId}
+    >
+      <div className={styles.contentInner}>
+        {children}
+      </div>
+    </BaseCollapsible.Panel>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Accordion = Object.assign(AccordionRoot, {
+  Item: AccordionItem,
+  Trigger: AccordionTrigger,
+  Content: AccordionContent,
+});
+
+export { AccordionRoot, AccordionItem, AccordionTrigger, AccordionContent };