@usefragments/ui 1.0.0

package/src/components/Accordion/Accordion.stories.tsx

@@ -0,0 +1,106 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Accordion } from '.';
+
+/**
+ * Accordion presents vertically stacked, collapsible content sections for
+ * progressive disclosure. It is a compound component: compose Accordion.Item,
+ * Accordion.Trigger, and Accordion.Content inside the root.
+ */
+const meta = {
+  title: 'Layout/Accordion',
+  component: Accordion,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Vertically stacked, collapsible content sections for progressive disclosure.',
+      },
+    },
+  },
+  argTypes: {
+    type: {
+      control: 'select',
+      options: ['single', 'multiple'],
+      description: 'Whether one or multiple items can be open',
+    },
+    collapsible: {
+      control: 'boolean',
+      description: 'Whether all items can be closed (single mode only)',
+    },
+    headingLevel: {
+      control: 'select',
+      options: ['2', '3', '4', '5', '6'],
+      description: 'Semantic heading level for accordion triggers',
+    },
+  },
+  args: {
+    type: 'single',
+    collapsible: true,
+    children: (
+      <Accordion.Item value="item-1">
+        <Accordion.Trigger>Section</Accordion.Trigger>
+        <Accordion.Content>Collapsible content.</Accordion.Content>
+      </Accordion.Item>
+    ),
+  },
+} satisfies Meta<typeof Accordion>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Single: Story = {
+  render: () => (
+    <Accordion type="single" collapsible defaultValue="item-1">
+      <Accordion.Item value="item-1">
+        <Accordion.Trigger>What is Fragments UI?</Accordion.Trigger>
+        <Accordion.Content>
+          A React component library built on Base UI primitives.
+        </Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="item-2">
+        <Accordion.Trigger>How do I install it?</Accordion.Trigger>
+        <Accordion.Content>Install via pnpm add @usefragments/ui.</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.</Accordion.Content>
+      </Accordion.Item>
+    </Accordion>
+  ),
+};
+
+export const Multiple: Story = {
+  render: () => (
+    <Accordion type="multiple" defaultValue={['features', 'pricing']}>
+      <Accordion.Item value="features">
+        <Accordion.Trigger>Features</Accordion.Trigger>
+        <Accordion.Content>Comprehensive components with theming support.</Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="pricing">
+        <Accordion.Trigger>Pricing</Accordion.Trigger>
+        <Accordion.Content>Free and open source, MIT licensed.</Accordion.Content>
+      </Accordion.Item>
+      <Accordion.Item value="support">
+        <Accordion.Trigger>Support</Accordion.Trigger>
+        <Accordion.Content>Community support via GitHub.</Accordion.Content>
+      </Accordion.Item>
+    </Accordion>
+  ),
+};
+
+export const WithDisabledItem: Story = {
+  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.</Accordion.Content>
+      </Accordion.Item>
+    </Accordion>
+  ),
+};

package/src/components/Accordion/index.tsx

@@ -0,0 +1,306 @@
+"use client";
+
+import * as React from "react";
+import { Collapsible as BaseCollapsible } from "@base-ui/react/collapsible";
+import styles from "./Accordion.module.scss";
+
+// ============================================
+// Types
+// ============================================
+
+export type AccordionValue = string | string[];
+
+interface AccordionSharedProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue"> {
+  children: React.ReactNode;
+  /** 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 AccordionSingleProps extends AccordionSharedProps {
+  /** Allow multiple items to be open at once */
+  type?: "single";
+  /** Controlled value for single mode */
+  value?: string;
+  /** Default value for uncontrolled usage */
+  defaultValue?: string;
+  /** Callback when value changes */
+  onValueChange?: (value: string | undefined) => void;
+}
+
+export interface AccordionMultipleProps extends AccordionSharedProps {
+  /** Allow multiple items to be open at once */
+  type: "multiple";
+  /** Controlled values for multiple mode */
+  value?: string[];
+  /** Default values for uncontrolled usage */
+  defaultValue?: string[];
+  /** Callback when value changes */
+  onValueChange?: (value: string[]) => void;
+}
+
+export type AccordionProps = AccordionSingleProps | AccordionMultipleProps;
+
+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.ButtonHTMLAttributes<HTMLButtonElement> {
+  children: React.ReactNode;
+}
+
+export interface AccordionContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Keep panel content mounted while collapsed */
+  keepMounted?: boolean;
+  /** Let browser find-in-page reveal collapsed content */
+  hiddenUntilFound?: boolean;
+}
+
+// ============================================
+// 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 (type === "single") {
+        (onValueChange as AccordionSingleProps["onValueChange"] | undefined)?.(newItems[0]);
+      } else {
+        (onValueChange as AccordionMultipleProps["onValueChange"] | undefined)?.(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">
+        {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,
+  type: buttonType,
+  onClick,
+  ...htmlProps
+}: AccordionTriggerProps) {
+  const { toggle, headingLevel } = useAccordionContext();
+  const { value, isOpen, disabled, triggerId, contentId } = useAccordionItemContext();
+
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    onClick?.(event);
+    if (event.defaultPrevented) return;
+    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
+        {...htmlProps}
+        type={buttonType ?? "button"}
+        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} 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,
+  keepMounted = false,
+  hiddenUntilFound = false,
+  className,
+  ...htmlProps
+}: AccordionContentProps) {
+  const { isOpen, triggerId, contentId } = useAccordionItemContext();
+
+  const classes = [styles.content, className].filter(Boolean).join(" ");
+
+  return (
+    <BaseCollapsible.Panel
+      {...htmlProps}
+      id={contentId}
+      className={classes}
+      data-state={isOpen ? "open" : "closed"}
+      role="region"
+      aria-labelledby={triggerId}
+      keepMounted={keepMounted}
+      hiddenUntilFound={hiddenUntilFound}
+    >
+      <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 };

package/src/components/Alert/Alert.contract.json

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Alert",
+  "description": "Contextual feedback messages for user actions or system status. Supports multiple severity levels with optional actions and dismissibility.",
+  "category": "feedback",
+  "tags": [
+    "notification",
+    "message",
+    "feedback",
+    "banner",
+    "toast"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Alert/index.tsx",
+  "exportName": "Alert",
+  "propsSummary": [
+    "children: node (required)",
+    "severity: info|success|warning|error (default: info)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Alert content - use Alert.Icon, Alert.Body, Alert.Title, Alert.Content, Alert.Actions, Alert.Close sub-components",
+      "required": true
+    },
+    "severity": {
+      "type": "enum",
+      "description": "Visual severity level",
+      "default": "info",
+      "required": false,
+      "values": [
+        "info",
+        "success",
+        "warning",
+        "error"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Communicating the result of a user action (success, error)",
+      "Warning about potential issues before they occur",
+      "Providing important contextual information inline",
+      "System status notifications that require attention"
+    ],
+    "whenNot": [
+      "Brief status labels (use Badge instead)",
+      "Transient notifications (use Toast/Snackbar)",
+      "Form-field-level errors (use Input error prop)",
+      "Confirmation before destructive actions (use Dialog)"
+    ],
+    "guidelines": [
+      "Match severity to the actual importance: info for context, warning for potential issues, error for failures",
+      "Always provide actionable guidance in error alerts",
+      "Use Alert.Title for complex messages; skip titles for brief one-liners",
+      "Limit to one action per alert to avoid decision paralysis",
+      "Use Alert.Close only for non-critical information",
+      "Alert.Action and Alert.Close render buttons with type=\"button\" by default (safe inside forms)",
+      "Alert.Close composes your onClick handler with built-in dismiss behavior and respects preventDefault()",
+      "Alert sub-components forward DOM props (aria-*, data-*, id, handlers) to their rendered elements"
+    ],
+    "accessibility": [
+      "Uses role=\"alert\" for screen reader announcement",
+      "Error and warning alerts are announced immediately by assistive technology",
+      "Alert.Close must have an accessible label",
+      "Color alone must not convey meaning - icons and text reinforce severity"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Info",
+      "description": "Informational context for the user",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"info\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Content>\n      Your session will expire in 15 minutes. Save your work to avoid losing changes.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+    },
+    {
+      "name": "Success",
+      "description": "Positive confirmation of completed action",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"success\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Payment processed</Alert.Title>\n    <Alert.Content>\n      Your order #12345 has been confirmed. You will receive a confirmation email shortly.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+    },
+    {
+      "name": "Warning",
+      "description": "Caution about potential issues",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"warning\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Storage almost full</Alert.Title>\n    <Alert.Content>\n      You have used 90% of your storage quota. Consider deleting unused files.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+    },
+    {
+      "name": "Error",
+      "description": "Error state requiring user attention",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"error\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Upload failed</Alert.Title>\n    <Alert.Content>\n      The file could not be uploaded. Check your connection and try again.\n    </Alert.Content>\n  </Alert.Body>\n</Alert>"
+    },
+    {
+      "name": "With Action",
+      "description": "Alert with an actionable button",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"warning\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Title>Update available</Alert.Title>\n    <Alert.Content>\n      A new version is available with important security fixes.\n    </Alert.Content>\n    <Alert.Actions>\n      <Alert.Action onClick={() => {}}>Update now</Alert.Action>\n    </Alert.Actions>\n  </Alert.Body>\n</Alert>"
+    },
+    {
+      "name": "Dismissible",
+      "description": "Alert that can be closed by the user",
+      "code": "import { Alert } from '@/components/Alert';\n\n<Alert severity=\"info\">\n  <Alert.Icon />\n  <Alert.Body>\n    <Alert.Content>\n      You can customize your notification preferences in Settings.\n    </Alert.Content>\n  </Alert.Body>\n  <Alert.Close />\n</Alert>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Badge",
+      "relationship": "alternative",
+      "note": "Use Badge for compact, inline status labels"
+    },
+    {
+      "component": "Toast",
+      "relationship": "alternative",
+      "note": "Use Toast for transient notifications that auto-dismiss"
+    },
+    {
+      "component": "Dialog",
+      "relationship": "sibling",
+      "note": "Use Dialog for blocking confirmations"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "severity: info|success|warning|error - visual severity",
+      "Sub-components: Alert.Icon, Alert.Body, Alert.Title, Alert.Content, Alert.Actions, Alert.Action, Alert.Close",
+      "Alert.Action / Alert.Close accept button props and default type=\"button\""
+    ],
+    "a11yRules": [
+      "A11Y_ALERT_ROLE",
+      "A11Y_ALERT_DISMISS",
+      "A11Y_ALERT_CONTRAST",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Icon",
+      "Body",
+      "Title",
+      "Content",
+      "Actions",
+      "Action",
+      "Close"
+    ],
+    "requiredChildren": [
+      "Body"
+    ],
+    "commonPatterns": [
+      "<Alert severity=\"info\"><Alert.Icon /><Alert.Body><Alert.Content>{message}</Alert.Content></Alert.Body></Alert>",
+      "<Alert severity=\"warning\"><Alert.Icon /><Alert.Body><Alert.Title>{title}</Alert.Title><Alert.Content>{message}</Alert.Content></Alert.Body></Alert>",
+      "<Alert severity=\"error\"><Alert.Icon /><Alert.Body><Alert.Title>{title}</Alert.Title><Alert.Content>{message}</Alert.Content></Alert.Body><Alert.Close /></Alert>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:50.066Z"
+  }
+}

package/src/components/Alert/Alert.module.scss

@@ -0,0 +1,130 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+.alert {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--fui-space-3, $fui-space-3);
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+// Severity variants
+.info {
+  background: var(--fui-color-info-bg, $fui-color-info-bg);
+  border: 1px solid var(--fui-color-info-border, $fui-color-info-border);
+  color: var(--fui-color-info-text, $fui-color-info-text);
+}
+
+.success {
+  background: var(--fui-color-success-bg, $fui-color-success-bg);
+  border: 1px solid var(--fui-color-success-border, $fui-color-success-border);
+  color: var(--fui-color-success-text, $fui-color-success-text);
+}
+
+.warning {
+  background: var(--fui-color-warning-bg, $fui-color-warning-bg);
+  border: 1px solid var(--fui-color-warning-border, $fui-color-warning-border);
+  color: var(--fui-color-warning-text, $fui-color-warning-text);
+}
+
+.error {
+  background: var(--fui-color-danger-bg, $fui-color-danger-bg);
+  border: 1px solid var(--fui-color-danger-border, $fui-color-danger-border);
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+.icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: $fui-icon-lg;
+  height: $fui-icon-lg;
+  border-radius: 50%;
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  flex-shrink: 0;
+  margin-top: var(--fui-space-px, $fui-space-px);
+  color: var(--fui-text-inverse, $fui-text-inverse);
+}
+
+.info .icon {
+  background-color: var(--fui-color-info-text, $fui-color-info-text);
+}
+
+.success .icon {
+  background-color: var(--fui-color-success-text, $fui-color-success-text);
+}
+
+.warning .icon {
+  background-color: var(--fui-color-warning-text, $fui-color-warning-text);
+}
+
+.error .icon {
+  background-color: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+.body {
+  flex: 1;
+  min-width: 0;
+}
+
+.title {
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  margin-bottom: var(--fui-space-0-5, $fui-space-0-5);
+}
+
+.content {
+  opacity: 0.9;
+}
+
+.actions {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-3, $fui-space-3);
+}
+
+.close {
+  @include button-reset;
+  @include interactive-base;
+  @include min-target-size;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0 var(--fui-space-1, $fui-space-1);
+  font-size: var(--fui-font-size-lg, $fui-font-size-lg);
+  color: inherit;
+  opacity: 0.6;
+  line-height: 1;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  margin-left: auto;
+  flex-shrink: 0;
+
+  &:hover {
+    opacity: 1;
+  }
+}
+
+.action {
+  @include button-reset;
+  @include min-target-size;
+
+  display: inline-flex;
+  align-items: center;
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: inherit;
+  text-decoration: underline;
+
+  &:hover {
+    opacity: 0.8;
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}