@fragments-sdk/ui 0.17.1 → 0.19.0

package/src/components/Avatar/Avatar.contract.json

@@ -0,0 +1,189 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Avatar",
+  "description": "Visual representation of a user or entity",
+  "category": "display",
+  "tags": [
+    "user",
+    "profile",
+    "image",
+    "identity"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Avatar/index.tsx",
+  "exportName": "Avatar",
+  "propsSummary": [
+    "src: string",
+    "alt: string (default: )",
+    "initials: string",
+    "name: string",
+    "size: xs|sm|md|lg|xl (default: md)",
+    "customSize: union",
+    "shape: circle|square (default: circle)",
+    "color: string",
+    "imageStyle: object",
+    "imageProps: object",
+    "style: object"
+  ],
+  "props": {
+    "src": {
+      "type": "string",
+      "description": "Image source URL",
+      "required": false
+    },
+    "alt": {
+      "type": "string",
+      "description": "Alt text for the image",
+      "default": "",
+      "required": false
+    },
+    "initials": {
+      "type": "string",
+      "description": "Fallback initials (1-2 characters)",
+      "required": false
+    },
+    "name": {
+      "type": "string",
+      "description": "Full name - used to generate initials",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "description": "Size variant",
+      "default": "md",
+      "required": false,
+      "values": [
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl"
+      ]
+    },
+    "customSize": {
+      "type": "union",
+      "description": "Custom avatar size (number in px or CSS size string like \"2.25rem\"), overrides size width/height",
+      "required": false
+    },
+    "shape": {
+      "type": "enum",
+      "description": "Shape variant",
+      "default": "circle",
+      "required": false,
+      "values": [
+        "circle",
+        "square"
+      ]
+    },
+    "color": {
+      "type": "string",
+      "description": "Custom background color for fallback avatar",
+      "required": false
+    },
+    "imageStyle": {
+      "type": "object",
+      "description": "Inline style object applied to the underlying image element",
+      "required": false
+    },
+    "imageProps": {
+      "type": "object",
+      "description": "Additional props for the underlying img element (except src/alt/className/style)",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Displaying user profile pictures",
+      "Showing team member lists",
+      "Representing entities in lists or cards",
+      "User identification in comments or messages"
+    ],
+    "whenNot": [
+      "Decorative images (use Image)",
+      "Logo display (use Logo component)",
+      "Large profile headers (use custom layout)"
+    ],
+    "guidelines": [
+      "Always provide alt text or name for accessibility",
+      "Use consistent sizes within the same context",
+      "Provide fallback initials when image may not load",
+      "Use Avatar.Group for multiple avatars in a row",
+      "Use imageProps for advanced img attributes (loading, decoding, referrerPolicy, etc.)"
+    ],
+    "accessibility": [
+      "Include meaningful alt text describing the user",
+      "Initials should be derived from name for screen readers",
+      "Decorative avatars should have empty alt"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Avatar with image",
+      "code": "import { Avatar } from '@/components/Avatar';\n\n<Avatar\n  src=\"https://i.pravatar.cc/150?u=jane\"\n  alt=\"Jane Doe\"\n  name=\"Jane Doe\"\n/>"
+    },
+    {
+      "name": "With Initials",
+      "description": "Fallback when no image is provided",
+      "code": "import { Avatar } from '@/components/Avatar';\n\n<Avatar name=\"John Smith\" />"
+    },
+    {
+      "name": "Sizes",
+      "description": "Available size options",
+      "code": "import { Avatar } from '@/components/Avatar';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\" wrap>\n  <Avatar name=\"XS\" size=\"xs\" />\n  <Avatar name=\"SM\" size=\"sm\" />\n  <Avatar name=\"MD\" size=\"md\" />\n  <Avatar name=\"LG\" size=\"lg\" />\n  <Avatar name=\"XL\" size=\"xl\" />\n</Stack>"
+    },
+    {
+      "name": "Custom Size",
+      "description": "Set an exact avatar size",
+      "code": "import { Avatar } from '@/components/Avatar';\n\n<Avatar name=\"Conan McNicholl\" customSize={36} />"
+    },
+    {
+      "name": "Square Shape",
+      "description": "Square variant for app icons or brands",
+      "code": "import { Avatar } from '@/components/Avatar';\n\n<Avatar name=\"App\" shape=\"square\" />"
+    },
+    {
+      "name": "Group",
+      "description": "Multiple avatars stacked together",
+      "code": "import { Avatar } from '@/components/Avatar';\n\n<Avatar.Group max={3} size=\"md\">\n  <Avatar name=\"Alice Johnson\" />\n  <Avatar name=\"Bob Smith\" />\n  <Avatar name=\"Carol Williams\" />\n  <Avatar name=\"David Brown\" />\n  <Avatar name=\"Eve Davis\" />\n</Avatar.Group>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Avatar",
+      "relationship": "parent",
+      "note": "Use Avatar.Group for stacked avatar displays"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "src: string - image URL",
+      "name: string - used for initials fallback",
+      "size: xs|sm|md|lg|xl (default: md)",
+      "customSize: number|string - custom size override",
+      "imageStyle: CSSProperties - inline image styling",
+      "imageProps: ImgHTMLAttributes - advanced img attributes",
+      "shape: circle|square (default: circle)"
+    ],
+    "a11yRules": [
+      "A11Y_IMG_ALT"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Group"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:50.743Z"
+  }
+}

package/src/components/Badge/Badge.contract.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Badge",
+  "description": "Compact label for status, counts, or categorization. Draws attention to metadata without dominating the layout.",
+  "category": "display",
+  "tags": [
+    "status",
+    "label",
+    "tag",
+    "count",
+    "chip"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Badge/index.tsx",
+  "exportName": "Badge",
+  "propsSummary": [
+    "children: node (required)",
+    "variant: default|success|warning|error|info|outline (default: default)",
+    "size: sm|md|lg (default: md)",
+    "dot: boolean (default: false)",
+    "icon: node",
+    "onRemove: function",
+    "announce: boolean (default: false)",
+    "role: union"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Badge label text",
+      "required": true
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual style indicating severity or category",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "success",
+        "warning",
+        "error",
+        "info",
+        "outline"
+      ]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Badge size",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "dot": {
+      "type": "boolean",
+      "description": "Show a colored dot indicator before the label",
+      "default": "false",
+      "required": false
+    },
+    "icon": {
+      "type": "node",
+      "description": "Optional icon element before the text",
+      "required": false
+    },
+    "onRemove": {
+      "type": "function",
+      "description": "Makes the badge removable. Called when X is clicked.",
+      "required": false
+    },
+    "announce": {
+      "type": "boolean",
+      "description": "Opt into role=\"status\" live announcement semantics",
+      "default": "false",
+      "required": false
+    },
+    "role": {
+      "type": "union",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Showing item status (active, pending, archived)",
+      "Displaying counts or quantities inline",
+      "Categorizing or tagging content",
+      "Highlighting new or updated items"
+    ],
+    "whenNot": [
+      "Conveying critical errors (use Alert instead)",
+      "Long-form status messages (use Alert)",
+      "Interactive filtering (use Chip/ToggleGroup)",
+      "Navigation labels (use Tabs or links)"
+    ],
+    "guidelines": [
+      "Keep badge text under 20 characters",
+      "Use dot variant for live status indicators",
+      "Pair success/error variants with meaningful labels, not just colors",
+      "Use onRemove for user-created tags only, not system-generated badges",
+      "Badges are not announced as live status updates by default; use announce for screen-reader status announcements when appropriate"
+    ],
+    "accessibility": [
+      "Badge text must be meaningful without relying on color alone",
+      "Removable badges must have accessible dismiss button labels",
+      "Avoid using badges as the sole indicator of important state changes"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Neutral badge for general labels",
+      "code": "import { Badge } from '@/components/Badge';\n\n<Badge>Default</Badge>"
+    },
+    {
+      "name": "Status Variants",
+      "description": "All severity variants for different contexts",
+      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"default\">Default</Badge>\n  <Badge variant=\"success\">Active</Badge>\n  <Badge variant=\"warning\">Pending</Badge>\n  <Badge variant=\"error\">Failed</Badge>\n  <Badge variant=\"info\">New</Badge>\n</Stack>"
+    },
+    {
+      "name": "With Dot",
+      "description": "Live status indicators using dot prefix",
+      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"success\" dot>Online</Badge>\n  <Badge variant=\"warning\" dot>Away</Badge>\n  <Badge variant=\"error\" dot>Offline</Badge>\n</Stack>"
+    },
+    {
+      "name": "Announced Status",
+      "description": "Opt into screen-reader status announcement behavior",
+      "code": "import { Badge } from '@/components/Badge';\n\n<Badge variant=\"success\" announce>Saved</Badge>"
+    },
+    {
+      "name": "Outline",
+      "description": "Minimal bordered badge for neutral emphasis",
+      "code": "import { Badge } from '@/components/Badge';\n\n<Badge variant=\"outline\">Outline</Badge>"
+    },
+    {
+      "name": "Small Size",
+      "description": "Compact badges for dense UIs",
+      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" align=\"center\" wrap>\n  <Badge size=\"sm\" variant=\"info\">v2.1</Badge>\n  <Badge size=\"sm\" variant=\"success\">Stable</Badge>\n  <Badge size=\"md\" variant=\"info\">Standard</Badge>\n</Stack>"
+    },
+    {
+      "name": "Removable",
+      "description": "User-created tags that can be dismissed",
+      "code": "import { Badge } from '@/components/Badge';\nimport { Stack } from '@/components/Stack';\n\n<Stack direction=\"row\" gap=\"sm\" wrap>\n  <Badge variant=\"info\" onRemove={() => {}}>React</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>TypeScript</Badge>\n  <Badge variant=\"info\" onRemove={() => {}}>CSS</Badge>\n</Stack>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Alert",
+      "relationship": "alternative",
+      "note": "Use Alert for prominent, longer messages with actions"
+    },
+    {
+      "component": "Chip",
+      "relationship": "sibling",
+      "note": "Chip is interactive (clickable/filterable); Badge is display-only"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - badge label (required)",
+      "variant: default|success|warning|error|info|outline - visual style",
+      "size: sm|md - badge size",
+      "dot: boolean - show status dot indicator",
+      "onRemove: () => void - makes badge removable",
+      "announce: boolean - opt into role=\"status\" + auto status aria-label"
+    ],
+    "a11yRules": [
+      "A11Y_BADGE_CONTRAST",
+      "A11Y_BADGE_DISMISS",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:50.941Z"
+  }
+}

package/src/components/BentoGrid/BentoGrid.contract.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "BentoGrid",
+  "description": "Asymmetric grid layout with responsive spans and built-in surface styling for bento-style feature sections",
+  "category": "layout",
+  "tags": [
+    "bento",
+    "grid",
+    "layout",
+    "responsive",
+    "feature-grid",
+    "asymmetric"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/BentoGrid/index.tsx",
+  "exportName": "BentoGrid",
+  "propsSummary": [
+    "children: node",
+    "columns: union (default: 3)",
+    "gap: none|xs|sm|md|lg|xl (default: md)",
+    "style: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "BentoGrid.Item children",
+      "required": false
+    },
+    "columns": {
+      "type": "union",
+      "description": "Number of columns — auto-collapses responsively (3→2→1)",
+      "default": "3",
+      "required": false,
+      "values": [
+        "2",
+        "3",
+        "4"
+      ]
+    },
+    "gap": {
+      "type": "enum",
+      "description": "Gap between grid items, mapped to spacing tokens",
+      "default": "md",
+      "required": false,
+      "values": [
+        "none",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl"
+      ]
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Asymmetric feature grids with hero + supporting items",
+      "Dashboard overviews where cards have different visual weight",
+      "Marketing pages with mixed-size content blocks",
+      "Any layout where items need per-breakpoint column/row spans"
+    ],
+    "whenNot": [
+      "Uniform grids where all items are the same size (use Grid)",
+      "Form layouts with labeled fields (use Grid)",
+      "Simple stacked content (use Stack)"
+    ],
+    "guidelines": [
+      "Use colSpan/rowSpan with responsive objects for layouts that adapt across breakpoints",
+      "The hero item typically uses colSpan={2} rowSpan={2} at lg and above",
+      "Items include built-in surface styling — no need to wrap children in Card",
+      "Grid auto-collapses: 3→2 columns below lg, all→1 column below sm",
+      "Root and Item forward DOM props (aria-*, data-*, handlers), and Item style merges with span CSS vars"
+    ],
+    "accessibility": [
+      "Grid is purely visual — it does not affect reading order or semantics",
+      "Ensure logical source order matches visual order for screen readers",
+      "Hover effects are disabled when prefers-reduced-motion is set",
+      "Border thickness increases in prefers-contrast: more mode"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic 3-column uniform bento grid",
+      "code": "<BentoGrid columns={3} gap=\"md\">\n  <BentoGrid.Item>Item 1</BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item>Item 3</BentoGrid.Item>\n  <BentoGrid.Item>Item 4</BentoGrid.Item>\n  <BentoGrid.Item>Item 5</BentoGrid.Item>\n  <BentoGrid.Item>Item 6</BentoGrid.Item>\n</BentoGrid>"
+    },
+    {
+      "name": "Hero Layout",
+      "description": "2×2 hero item with 4 supporting items in a 3-column grid",
+      "code": "<BentoGrid columns={3} gap=\"md\">\n  <BentoGrid.Item colSpan={{ base: 1, lg: 2 }} rowSpan={{ base: 1, lg: 2 }}>\n    Hero content\n  </BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item>Item 3</BentoGrid.Item>\n  <BentoGrid.Item>Item 4</BentoGrid.Item>\n  <BentoGrid.Item>Item 5</BentoGrid.Item>\n</BentoGrid>"
+    },
+    {
+      "name": "Two Column",
+      "description": "2-column bento with a wide item",
+      "code": "<BentoGrid columns={2} gap=\"md\">\n  <BentoGrid.Item>Item 1</BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item colSpan={2}>Wide item</BentoGrid.Item>\n  <BentoGrid.Item>Item 4</BentoGrid.Item>\n  <BentoGrid.Item>Item 5</BentoGrid.Item>\n</BentoGrid>"
+    },
+    {
+      "name": "Full-Width Banner",
+      "description": "3-column grid with a full-width item spanning all columns",
+      "code": "<BentoGrid columns={3} gap=\"md\">\n  <BentoGrid.Item>Item 1</BentoGrid.Item>\n  <BentoGrid.Item>Item 2</BentoGrid.Item>\n  <BentoGrid.Item>Item 3</BentoGrid.Item>\n  <BentoGrid.Item colSpan={3}>Full-width banner</BentoGrid.Item>\n</BentoGrid>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Grid",
+      "relationship": "alternative",
+      "note": "Use Grid for uniform layouts; BentoGrid for asymmetric spans with built-in surfaces"
+    },
+    {
+      "component": "Card",
+      "relationship": "sibling",
+      "note": "BentoGrid.Item has built-in surface styling similar to Card"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "columns: 2|3|4 (default: 3) — auto-collapses responsively",
+      "gap: none|xs|sm|md|lg|xl (default: md)",
+      "BentoGrid.Item colSpan: 1|2|3 | { base, sm, md, lg, xl }",
+      "BentoGrid.Item rowSpan: 1|2|3 | { base, sm, md, lg, xl }",
+      "BentoGrid and BentoGrid.Item forward div DOM props; Item style is merged with generated span vars"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:52.407Z"
+  }
+}