@usefragments/ui 1.0.0

package/src/components/Collapsible/Collapsible.contract.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Collapsible",
+  "description": "An interactive component that expands/collapses to show or hide content",
+  "category": "layout",
+  "tags": [
+    "collapsible",
+    "expandable",
+    "accordion",
+    "disclosure",
+    "toggle"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Collapsible/index.tsx",
+  "exportName": "Collapsible",
+  "propsSummary": [
+    "children: node (required)",
+    "defaultOpen: boolean (default: false)",
+    "open: boolean",
+    "onOpenChange: function",
+    "disabled: boolean (default: false)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Collapsible.Trigger and Collapsible.Content components",
+      "required": true
+    },
+    "defaultOpen": {
+      "type": "boolean",
+      "description": "Whether the collapsible is initially open (uncontrolled)",
+      "default": "false",
+      "required": false
+    },
+    "open": {
+      "type": "boolean",
+      "description": "Controlled open state",
+      "required": false
+    },
+    "onOpenChange": {
+      "type": "function",
+      "description": "Callback when open state changes - (open: boolean) => void",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Whether the collapsible is disabled",
+      "default": "false",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Showing/hiding additional content on demand",
+      "Building accordions or expandable sections",
+      "Collapsible navigation sections",
+      "FAQ sections with expandable answers",
+      "Settings panels with grouped options"
+    ],
+    "whenNot": [
+      "Single item disclosure (use Accordion instead)",
+      "Navigation menus with complex interactions (use Menu)",
+      "Modal or overlay content (use Dialog or Popover)"
+    ],
+    "guidelines": [
+      "Use clear trigger labels that indicate expandable content",
+      "Consider defaultOpen for primary content users often need",
+      "Keep trigger text concise but descriptive",
+      "Use chevron icons consistently to indicate collapsible state"
+    ],
+    "accessibility": [
+      "Trigger must have aria-expanded to indicate state",
+      "Content region needs aria-labelledby pointing to trigger",
+      "Keyboard: Enter/Space toggles open state",
+      "Focus should remain on trigger after toggle"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic collapsible with trigger and content",
+      "code": "<Collapsible>\n  <Collapsible.Trigger>Click to expand</Collapsible.Trigger>\n  <Collapsible.Content>\n    <p>This content is hidden by default and revealed when the trigger is clicked.</p>\n  </Collapsible.Content>\n</Collapsible>"
+    },
+    {
+      "name": "Default Open",
+      "description": "Collapsible that starts in the expanded state",
+      "code": "<Collapsible defaultOpen>\n  <Collapsible.Trigger>Section Title</Collapsible.Trigger>\n  <Collapsible.Content>\n    <p>This content is visible by default. Click the trigger to collapse.</p>\n  </Collapsible.Content>\n</Collapsible>"
+    },
+    {
+      "name": "Chevron Start",
+      "description": "Collapsible with chevron icon on the left",
+      "code": "<Collapsible>\n  <Collapsible.Trigger chevronPosition=\"start\">Navigation</Collapsible.Trigger>\n  <Collapsible.Content>\n    <ul style={{ margin: 0, paddingLeft: '1.5rem' }}>\n      <li>Dashboard</li>\n      <li>Settings</li>\n      <li>Profile</li>\n    </ul>\n  </Collapsible.Content>\n</Collapsible>"
+    },
+    {
+      "name": "No Chevron",
+      "description": "Collapsible without chevron indicator",
+      "code": "<Collapsible>\n  <Collapsible.Trigger showChevron={false}>Show more details</Collapsible.Trigger>\n  <Collapsible.Content>\n    <p>Hidden details that appear when triggered.</p>\n  </Collapsible.Content>\n</Collapsible>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Collapsible in disabled state",
+      "code": "<Collapsible disabled>\n  <Collapsible.Trigger>Cannot toggle (disabled)</Collapsible.Trigger>\n  <Collapsible.Content>\n    <p>This content cannot be shown because the collapsible is disabled.</p>\n  </Collapsible.Content>\n</Collapsible>"
+    },
+    {
+      "name": "Multiple Sections",
+      "description": "Multiple independent collapsible sections",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>\n  <Collapsible defaultOpen>\n    <Collapsible.Trigger>Getting Started</Collapsible.Trigger>\n    <Collapsible.Content>\n      <p>Introduction and setup instructions.</p>\n    </Collapsible.Content>\n  </Collapsible>\n  <Collapsible>\n    <Collapsible.Trigger>Advanced Usage</Collapsible.Trigger>\n    <Collapsible.Content>\n      <p>Advanced configuration options.</p>\n    </Collapsible.Content>\n  </Collapsible>\n  <Collapsible>\n    <Collapsible.Trigger>API Reference</Collapsible.Trigger>\n    <Collapsible.Content>\n      <p>Complete API documentation.</p>\n    </Collapsible.Content>\n  </Collapsible>\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Accordion",
+      "relationship": "alternative",
+      "note": "Use Accordion for multiple exclusive collapsible sections"
+    },
+    {
+      "component": "Sidebar",
+      "relationship": "used-by",
+      "note": "Sidebar uses Collapsible for section expand/collapse"
+    },
+    {
+      "component": "Menu",
+      "relationship": "alternative",
+      "note": "Use Menu for dropdown navigation with actions"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "defaultOpen: boolean - initial open state (default: false)",
+      "open: boolean - controlled open state",
+      "onOpenChange: (open: boolean) => void - state change callback",
+      "disabled: boolean - prevents interaction"
+    ],
+    "a11yRules": [
+      "A11Y_EXPANDED_STATE",
+      "A11Y_REGION_LABEL",
+      "A11Y_KEYBOARD_NAV"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root",
+      "Trigger",
+      "Content"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:52.800Z"
+  }
+}

package/src/components/Collapsible/Collapsible.module.scss

@@ -0,0 +1,119 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.root {
+  width: 100%;
+}
+
+.trigger {
+  display: flex;
+  align-items: center;
+  width: 100%;
+  padding: var(--fui-space-1, $fui-space-1);
+  background: transparent;
+  border: none;
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  color: var(--fui-text-primary, $fui-text-primary);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  text-align: left;
+  cursor: pointer;
+  transition: background-color var(--fui-transition-fast, $fui-transition-fast);
+  gap: var(--fui-space-2, $fui-space-2);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.triggerContent {
+  flex: 1;
+  min-width: 0;
+}
+
+.chevron {
+  flex-shrink: 0;
+  width: var(--fui-icon-md, $fui-icon-md);
+  height: var(--fui-icon-md, $fui-icon-md);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  transition: transform var(--fui-transition-normal, $fui-transition-normal);
+}
+
+.chevronOpen {
+  transform: rotate(90deg);
+}
+
+.content {
+  overflow: hidden;
+  transition:
+    max-height var(--fui-transition-normal, $fui-transition-normal),
+    opacity var(--fui-transition-normal, $fui-transition-normal);
+}
+
+.contentOpen {
+  max-height: 2000px; // Large enough for most content
+  opacity: 1;
+}
+
+.contentClosed {
+  max-height: 0;
+  opacity: 0;
+}
+
+.contentInner {
+  padding-top: var(--fui-space-1, $fui-space-1);
+}
+
+.disabled {
+  .trigger {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+// Animation variant using CSS animation instead of max-height
+// Can be used with forceMount for smoother animations
+.root[data-animated='true'] {
+  // Duration + easing come from --fui-transition-normal (matches the
+  // max-height/opacity transition above); fill-mode keeps the end state.
+  .contentOpen {
+    animation: collapsibleSlideDown var(--fui-transition-normal, $fui-transition-normal)
+      forwards;
+  }
+
+  .contentClosed {
+    animation: collapsibleSlideUp var(--fui-transition-normal, $fui-transition-normal)
+      forwards;
+  }
+}
+
+@keyframes collapsibleSlideDown {
+  from {
+    max-height: 0;
+    opacity: 0;
+  }
+  to {
+    max-height: var(--collapsible-content-height, 2000px);
+    opacity: 1;
+  }
+}
+
+@keyframes collapsibleSlideUp {
+  from {
+    max-height: var(--collapsible-content-height, 2000px);
+    opacity: 1;
+  }
+  to {
+    max-height: 0;
+    opacity: 0;
+  }
+}

package/src/components/Collapsible/Collapsible.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Collapsible } from '.';
+
+/**
+ * Disclosure component that expands and collapses to show or hide content.
+ * Compose Collapsible.Trigger and Collapsible.Content as children. Supports
+ * controlled `open`, uncontrolled `defaultOpen`, and a disabled state.
+ */
+const meta = {
+  title: 'Layout/Collapsible',
+  component: Collapsible,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Expands and collapses to show or hide content.',
+      },
+    },
+  },
+  argTypes: {
+    defaultOpen: { control: 'boolean', description: 'Initial open state' },
+    disabled: { control: 'boolean' },
+  },
+  args: {
+    defaultOpen: false,
+    disabled: false,
+    children: (
+      <>
+        <Collapsible.Trigger>Click to expand</Collapsible.Trigger>
+        <Collapsible.Content>
+          <p>This content is hidden by default and revealed on click.</p>
+        </Collapsible.Content>
+      </>
+    ),
+  },
+} satisfies Meta<typeof Collapsible>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Collapsible {...args}>
+      <Collapsible.Trigger>Click to expand</Collapsible.Trigger>
+      <Collapsible.Content>
+        <p>This content is hidden by default and revealed on click.</p>
+      </Collapsible.Content>
+    </Collapsible>
+  ),
+};
+
+export const DefaultOpen: Story = {
+  args: { defaultOpen: true },
+  render: (args) => (
+    <Collapsible {...args}>
+      <Collapsible.Trigger>Section Title</Collapsible.Trigger>
+      <Collapsible.Content>
+        <p>This content is visible by default. Click to collapse.</p>
+      </Collapsible.Content>
+    </Collapsible>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+  render: (args) => (
+    <Collapsible {...args}>
+      <Collapsible.Trigger>Cannot toggle (disabled)</Collapsible.Trigger>
+      <Collapsible.Content>
+        <p>This content cannot be shown because the collapsible is disabled.</p>
+      </Collapsible.Content>
+    </Collapsible>
+  ),
+};
+
+export const MultipleSections: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>
+      <Collapsible defaultOpen>
+        <Collapsible.Trigger>Getting Started</Collapsible.Trigger>
+        <Collapsible.Content>
+          <p>Introduction and setup instructions.</p>
+        </Collapsible.Content>
+      </Collapsible>
+      <Collapsible>
+        <Collapsible.Trigger>Advanced Usage</Collapsible.Trigger>
+        <Collapsible.Content>
+          <p>Advanced configuration options.</p>
+        </Collapsible.Content>
+      </Collapsible>
+    </div>
+  ),
+};

package/src/components/Collapsible/index.tsx

@@ -0,0 +1,254 @@
+'use client';
+
+import React, { useState, useCallback, useId, createContext, useContext } from 'react';
+import styles from './Collapsible.module.scss';
+
+function composeEventHandlers<E extends { defaultPrevented: boolean }>(
+  userHandler: ((event: E) => void) | undefined,
+  internalHandler: (event: E) => void
+) {
+  return (event: E) => {
+    userHandler?.(event);
+    if (event.defaultPrevented) return;
+    internalHandler(event);
+  };
+}
+
+// Context for sharing state between compound components
+interface CollapsibleContextValue {
+  isOpen: boolean;
+  toggle: () => void;
+  contentId: string;
+  triggerId: string;
+  disabled?: boolean;
+}
+
+const CollapsibleContext = createContext<CollapsibleContextValue | null>(null);
+
+function useCollapsibleContext() {
+  const context = useContext(CollapsibleContext);
+  if (!context) {
+    throw new Error('Collapsible compound components must be used within Collapsible.Root');
+  }
+  return context;
+}
+
+// Root component
+export interface CollapsibleRootProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Whether the collapsible is initially open */
+  defaultOpen?: boolean;
+  /** Controlled open state */
+  open?: boolean;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Whether the collapsible is disabled */
+  disabled?: boolean;
+}
+
+function CollapsibleRoot({
+  children,
+  defaultOpen = false,
+  open: controlledOpen,
+  onOpenChange,
+  disabled = false,
+  className,
+  ...htmlProps
+}: CollapsibleRootProps) {
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isControlled = controlledOpen !== undefined;
+  const isOpen = isControlled ? controlledOpen : internalOpen;
+
+  const uniqueId = useId();
+  const contentId = `collapsible-content-${uniqueId}`;
+  const triggerId = `collapsible-trigger-${uniqueId}`;
+
+  const toggle = useCallback(() => {
+    if (disabled) return;
+
+    if (isControlled) {
+      onOpenChange?.(!isOpen);
+    } else {
+      setInternalOpen((prev) => {
+        const newValue = !prev;
+        onOpenChange?.(newValue);
+        return newValue;
+      });
+    }
+  }, [disabled, isControlled, isOpen, onOpenChange]);
+
+  const contextValue: CollapsibleContextValue = {
+    isOpen,
+    toggle,
+    contentId,
+    triggerId,
+    disabled,
+  };
+
+  return (
+    <CollapsibleContext.Provider value={contextValue}>
+      <div
+        {...htmlProps}
+        className={`${styles.root} ${isOpen ? styles.open : ''} ${disabled ? styles.disabled : ''} ${className || ''}`}
+        data-state={isOpen ? 'open' : 'closed'}
+        data-disabled={disabled || undefined}
+      >
+        {children}
+      </div>
+    </CollapsibleContext.Provider>
+  );
+}
+
+// Trigger component
+export interface CollapsibleTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  children: React.ReactNode;
+  /** Show chevron indicator */
+  showChevron?: boolean;
+  /** Chevron position */
+  chevronPosition?: 'start' | 'end';
+  /** Render as child element (for custom triggers) */
+  asChild?: boolean;
+}
+
+function CollapsibleTrigger({
+  children,
+  className,
+  showChevron = true,
+  chevronPosition = 'end',
+  asChild = false,
+  onClick,
+  onKeyDown,
+  ...htmlProps
+}: CollapsibleTriggerProps) {
+  const { isOpen, toggle, contentId, triggerId, disabled } = useCollapsibleContext();
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      toggle();
+    }
+  };
+
+  const handleClick = () => {
+    toggle();
+  };
+
+  const chevronIcon = showChevron && (
+    <svg
+      className={`${styles.chevron} ${isOpen ? styles.chevronOpen : ''}`}
+      viewBox="0 0 16 16"
+      fill="none"
+      aria-hidden="true"
+    >
+      <path
+        d="M6 4L10 8L6 12"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+
+  if (asChild && React.isValidElement(children)) {
+    const childProps = children.props as {
+      className?: string;
+      onClick?: (event: React.MouseEvent<HTMLElement>) => void;
+      onKeyDown?: (event: React.KeyboardEvent<HTMLElement>) => void;
+    };
+
+    return React.cloneElement(children as React.ReactElement<any>, {
+      ...htmlProps,
+      id: (htmlProps.id as string | undefined) ?? triggerId,
+      'aria-expanded': isOpen,
+      'aria-controls': contentId,
+      'aria-disabled': disabled || undefined,
+      onClick: composeEventHandlers(
+        (event: React.MouseEvent<HTMLElement>) => {
+          childProps.onClick?.(event);
+          onClick?.(event as unknown as React.MouseEvent<HTMLButtonElement>);
+        },
+        () => handleClick()
+      ),
+      onKeyDown: composeEventHandlers(
+        (event: React.KeyboardEvent<HTMLElement>) => {
+          childProps.onKeyDown?.(event);
+          onKeyDown?.(event as unknown as React.KeyboardEvent<HTMLButtonElement>);
+        },
+        (event) => handleKeyDown(event as unknown as React.KeyboardEvent)
+      ),
+      className: [className, childProps.className].filter(Boolean).join(' '),
+    });
+  }
+
+  return (
+    <button
+      {...htmlProps}
+      type="button"
+      id={(htmlProps.id as string | undefined) ?? triggerId}
+      className={`${styles.trigger} ${className || ''}`}
+      aria-expanded={isOpen}
+      aria-controls={contentId}
+      aria-disabled={disabled || undefined}
+      onClick={composeEventHandlers(onClick, handleClick)}
+      onKeyDown={composeEventHandlers(onKeyDown, handleKeyDown)}
+      disabled={disabled}
+    >
+      {chevronPosition === 'start' && chevronIcon}
+      <span className={styles.triggerContent}>{children}</span>
+      {chevronPosition === 'end' && chevronIcon}
+    </button>
+  );
+}
+
+// Content component
+export interface CollapsibleContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Force mount content even when closed (useful for animations) */
+  forceMount?: boolean;
+}
+
+function CollapsibleContent({
+  children,
+  className,
+  forceMount = false,
+  ...htmlProps
+}: CollapsibleContentProps) {
+  const { isOpen, contentId, triggerId } = useCollapsibleContext();
+
+  // If not force mounted and closed, don't render
+  if (!forceMount && !isOpen) {
+    return null;
+  }
+
+  return (
+    <div
+      {...htmlProps}
+      id={(htmlProps.id as string | undefined) ?? contentId}
+      role="region"
+      aria-labelledby={triggerId}
+      className={`${styles.content} ${isOpen ? styles.contentOpen : styles.contentClosed} ${className || ''}`}
+      data-state={isOpen ? 'open' : 'closed'}
+      hidden={!isOpen && !forceMount}
+    >
+      <div className={styles.contentInner}>{children}</div>
+    </div>
+  );
+}
+
+// Compound component export
+export const Collapsible = Object.assign(CollapsibleRoot, {
+  Root: CollapsibleRoot,
+  Trigger: CollapsibleTrigger,
+  Content: CollapsibleContent,
+});
+
+// Named exports for direct imports
+export {
+  CollapsibleRoot,
+  CollapsibleTrigger,
+  CollapsibleContent,
+  useCollapsibleContext,
+};
+
+export type CollapsibleProps = CollapsibleRootProps;