@fragments-sdk/ui 0.17.1 → 0.19.0

package/src/components/Text/Text.contract.json

@@ -0,0 +1,239 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Text",
+  "description": "Typography component for rendering text with consistent styling. Supports various sizes, weights, colors, and semantic elements.",
+  "category": "display",
+  "tags": [
+    "text",
+    "typography",
+    "heading",
+    "paragraph",
+    "font"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Text/index.tsx",
+  "exportName": "Text",
+  "propsSummary": [
+    "children: node (required)",
+    "as: h1|h2|h3|h4|h5|h6|p|span|label|div|strong|em|small|mark|del|ins|sub|sup|time|address|blockquote|cite|code|abbr (default: span)",
+    "variant: section-label",
+    "size: 2xs|xs|sm|base|md|lg|xl|2xl",
+    "weight: normal|medium|semibold|bold (default: \"normal\")",
+    "color: primary|secondary|tertiary|muted (default: \"primary\")",
+    "font: sans|mono (default: sans)",
+    "truncate: boolean",
+    "lineClamp: number",
+    "style: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Text content",
+      "required": true
+    },
+    "as": {
+      "type": "enum",
+      "description": "HTML element to render",
+      "default": "span",
+      "required": false,
+      "values": [
+        "h1",
+        "h2",
+        "h3",
+        "h4",
+        "h5",
+        "h6",
+        "p",
+        "span",
+        "label",
+        "div",
+        "strong",
+        "em",
+        "small",
+        "mark",
+        "del",
+        "ins",
+        "sub",
+        "sup",
+        "time",
+        "address",
+        "blockquote",
+        "cite",
+        "code",
+        "abbr"
+      ]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Preset text variant",
+      "required": false,
+      "values": [
+        "section-label"
+      ]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Font size (md is an alias for base)",
+      "required": false,
+      "values": [
+        "2xs",
+        "xs",
+        "sm",
+        "base",
+        "md",
+        "lg",
+        "xl",
+        "2xl"
+      ]
+    },
+    "weight": {
+      "type": "enum",
+      "description": "Font weight",
+      "default": "\"normal\"",
+      "required": false,
+      "values": [
+        "normal",
+        "medium",
+        "semibold",
+        "bold"
+      ]
+    },
+    "color": {
+      "type": "enum",
+      "description": "Text color (muted is an alias for tertiary)",
+      "default": "\"primary\"",
+      "required": false,
+      "values": [
+        "primary",
+        "secondary",
+        "tertiary",
+        "muted"
+      ]
+    },
+    "font": {
+      "type": "enum",
+      "description": "Font family",
+      "default": "sans",
+      "required": false,
+      "values": [
+        "sans",
+        "mono"
+      ]
+    },
+    "truncate": {
+      "type": "boolean",
+      "description": "Truncate with ellipsis on overflow",
+      "required": false
+    },
+    "lineClamp": {
+      "type": "number",
+      "description": "Number of lines before truncating (requires truncate)",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Displaying text with specific typography styles",
+      "Creating headings, paragraphs, or labels",
+      "Text that needs truncation or line clamping",
+      "Consistent typography across the application"
+    ],
+    "whenNot": [
+      "Complex rich text (use a rich text editor)",
+      "Code display (use CodeBlock)",
+      "Interactive text (use Link or Button)"
+    ],
+    "guidelines": [
+      "Use semantic elements (h1-h6, p) via the \"as\" prop",
+      "Maintain heading hierarchy for accessibility",
+      "Use color variants sparingly for visual hierarchy",
+      "Consider truncation for user-generated content"
+    ],
+    "accessibility": [
+      "Use proper heading levels (h1-h6) for document structure",
+      "Semantic elements convey meaning to screen readers",
+      "Truncated text should have full content in title/tooltip"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Sizes",
+      "description": "Different text sizes",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text size=\"2xs\">Extra extra small (2xs)</Text>\n  <Text size=\"xs\">Extra small (xs)</Text>\n  <Text size=\"sm\">Small (sm)</Text>\n  <Text size=\"base\">Base size</Text>\n  <Text size=\"lg\">Large (lg)</Text>\n  <Text size=\"xl\">Extra large (xl)</Text>\n  <Text size=\"2xl\">Extra extra large (2xl)</Text>\n</div>"
+    },
+    {
+      "name": "Weights",
+      "description": "Different font weights",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text weight=\"normal\">Normal weight</Text>\n  <Text weight=\"medium\">Medium weight</Text>\n  <Text weight=\"semibold\">Semibold weight</Text>\n  <Text weight=\"bold\">Bold weight</Text>\n</div>"
+    },
+    {
+      "name": "Colors",
+      "description": "Different text colors",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text color=\"primary\">Primary color (default)</Text>\n  <Text color=\"secondary\">Secondary color</Text>\n  <Text color=\"tertiary\">Tertiary color</Text>\n  <Text color=\"muted\">Muted color (alias for tertiary)</Text>\n</div>"
+    },
+    {
+      "name": "Semantic Elements",
+      "description": "Using appropriate HTML elements",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <Text as=\"h1\" size=\"2xl\" weight=\"semibold\">Heading 1</Text>\n  <Text as=\"h2\" size=\"xl\" weight=\"semibold\">Heading 2</Text>\n  <Text as=\"h3\" size=\"lg\" weight=\"medium\">Heading 3</Text>\n  <Text as=\"p\" color=\"secondary\">\n    This is a paragraph of text that demonstrates the Text component\n    with semantic paragraph element.\n  </Text>\n</div>"
+    },
+    {
+      "name": "Monospace",
+      "description": "Monospace font for code-like text",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Text font=\"mono\" size=\"sm\">const greeting = \"Hello, World!\";</Text>\n  <Text font=\"mono\" size=\"sm\" color=\"secondary\">npm install @fragments-sdk/ui</Text>\n</div>"
+    },
+    {
+      "name": "Truncation",
+      "description": "Text truncation with ellipsis",
+      "code": "<div style={{ width: '200px', display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <Text truncate>\n    This is a very long text that will be truncated with an ellipsis when it overflows.\n  </Text>\n  <Text truncate lineClamp={2}>\n    This text will be clamped to two lines. Any content beyond two lines\n    will be hidden and replaced with an ellipsis at the end.\n  </Text>\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Link",
+      "relationship": "sibling",
+      "note": "Use Link for clickable text"
+    },
+    {
+      "component": "CodeBlock",
+      "relationship": "alternative",
+      "note": "Use CodeBlock for code display"
+    },
+    {
+      "component": "Badge",
+      "relationship": "sibling",
+      "note": "Use Badge for labels/tags"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "as: string - HTML element",
+      "size: 2xs|xs|sm|base|md|lg|xl|2xl - font size (md = base)",
+      "weight: normal|medium|semibold|bold - font weight",
+      "color: primary|secondary|tertiary|muted - text color (muted = tertiary)",
+      "font: sans|mono - font family",
+      "truncate: boolean - enable truncation",
+      "lineClamp: number - max lines"
+    ],
+    "a11yRules": [
+      "A11Y_HEADING_HIERARCHY",
+      "A11Y_SEMANTIC_ELEMENTS"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:05.045Z"
+  }
+}

package/src/components/Textarea/Textarea.contract.json

@@ -0,0 +1,308 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Textarea",
+  "description": "Multi-line text input for longer form content",
+  "category": "forms",
+  "tags": [
+    "input",
+    "text",
+    "form",
+    "multiline"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Textarea/index.tsx",
+  "exportName": "Textarea",
+  "propsSummary": [
+    "value: string",
+    "defaultValue: string",
+    "placeholder: string",
+    "rows: number (default: 3)",
+    "minRows: number",
+    "maxRows: number",
+    "resize: none|vertical|horizontal|both (default: vertical)",
+    "size: sm|md|lg (default: md)",
+    "disabled: boolean (default: false)",
+    "error: boolean (default: false)",
+    "success: boolean (default: false)",
+    "showCharCount: boolean (default: false)",
+    "label: string",
+    "helperText: string",
+    "onChange: function",
+    "onValueChange: function",
+    "onBlur: function",
+    "onFocus: function",
+    "name: string",
+    "maxLength: number",
+    "required: boolean",
+    "aria-label: string",
+    "aria-labelledby: string",
+    "aria-describedby: string",
+    "rootProps: object",
+    "className: string",
+    "style: object"
+  ],
+  "props": {
+    "value": {
+      "type": "string",
+      "description": "Controlled value",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "string",
+      "description": "Default value for uncontrolled usage",
+      "required": false
+    },
+    "placeholder": {
+      "type": "string",
+      "description": "Placeholder text",
+      "required": false
+    },
+    "rows": {
+      "type": "number",
+      "description": "Number of visible text rows",
+      "default": "3",
+      "required": false
+    },
+    "minRows": {
+      "type": "number",
+      "description": "Minimum number of rows when auto-resizing",
+      "required": false
+    },
+    "maxRows": {
+      "type": "number",
+      "description": "Maximum number of rows when auto-resizing",
+      "required": false
+    },
+    "resize": {
+      "type": "enum",
+      "description": "Resize behavior",
+      "default": "vertical",
+      "required": false,
+      "values": [
+        "none",
+        "vertical",
+        "horizontal",
+        "both"
+      ]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Size variant",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disabled state",
+      "default": "false",
+      "required": false
+    },
+    "error": {
+      "type": "boolean",
+      "description": "Error state",
+      "default": "false",
+      "required": false
+    },
+    "success": {
+      "type": "boolean",
+      "description": "Whether to show success/validated styling",
+      "default": "false",
+      "required": false
+    },
+    "showCharCount": {
+      "type": "boolean",
+      "description": "Show character counter when maxLength is set",
+      "default": "false",
+      "required": false
+    },
+    "label": {
+      "type": "string",
+      "description": "Label text above the textarea",
+      "required": false
+    },
+    "helperText": {
+      "type": "string",
+      "description": "Helper text below the textarea",
+      "required": false
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Called when the textarea value changes",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "description": "Value-first change callback alias: (value: string) => void",
+      "required": false
+    },
+    "onBlur": {
+      "type": "function",
+      "description": "Called when textarea loses focus",
+      "required": false
+    },
+    "onFocus": {
+      "type": "function",
+      "description": "Called when textarea receives focus",
+      "required": false
+    },
+    "name": {
+      "type": "string",
+      "description": "Form field name",
+      "required": false
+    },
+    "maxLength": {
+      "type": "number",
+      "description": "Maximum character length",
+      "required": false
+    },
+    "required": {
+      "type": "boolean",
+      "description": "Required field",
+      "required": false
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "Accessible label for no-visible-label usage",
+      "required": false
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "description": "Accessible labelled-by relationship",
+      "required": false
+    },
+    "aria-describedby": {
+      "type": "string",
+      "description": "Accessible described-by relationship",
+      "required": false
+    },
+    "rootProps": {
+      "type": "object",
+      "description": "HTML attributes applied to the wrapper element",
+      "required": false
+    },
+    "className": {
+      "type": "string",
+      "description": "Wrapper class name",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "Wrapper styles",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Collecting multi-line text (comments, descriptions)",
+      "Free-form text input that may span multiple lines",
+      "Message composition fields",
+      "Code or content editing"
+    ],
+    "whenNot": [
+      "Single-line input (use Input)",
+      "Rich text editing (use rich text editor)",
+      "Selecting from predefined options (use Select)"
+    ],
+    "guidelines": [
+      "Set appropriate rows for expected content length",
+      "Use placeholder to show example format",
+      "Show character count when maxLength is set",
+      "Consider auto-resize for better UX"
+    ],
+    "accessibility": [
+      "Always provide a visible label",
+      "Use helperText for format hints",
+      "Error messages should be descriptive"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic textarea with label",
+      "code": "<Textarea\n  label=\"Description\"\n  placeholder=\"Enter a description...\"\n/>"
+    },
+    {
+      "name": "With Helper Text",
+      "description": "Textarea with additional guidance",
+      "code": "<Textarea\n  label=\"Bio\"\n  placeholder=\"Tell us about yourself...\"\n  helperText=\"Max 500 characters\"\n  maxLength={500}\n/>"
+    },
+    {
+      "name": "Error State",
+      "description": "Textarea showing validation error",
+      "code": "<Textarea\n  label=\"Comments\"\n  placeholder=\"Add your comments...\"\n  error\n  helperText=\"This field is required\"\n/>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Non-interactive textarea",
+      "code": "<Textarea\n  label=\"Notes\"\n  placeholder=\"Cannot edit...\"\n  disabled\n/>"
+    },
+    {
+      "name": "Custom Rows",
+      "description": "Textarea with more visible rows",
+      "code": "<Textarea\n  label=\"Long Description\"\n  placeholder=\"Enter detailed information...\"\n  rows={6}\n/>"
+    },
+    {
+      "name": "Sizes",
+      "description": "Available size variants",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: '400px' }}>\n  <Textarea label=\"Small\" size=\"sm\" placeholder=\"Small textarea\" />\n  <Textarea label=\"Medium\" size=\"md\" placeholder=\"Medium textarea\" />\n  <Textarea label=\"Large\" size=\"lg\" placeholder=\"Large textarea\" />\n</div>"
+    },
+    {
+      "name": "With Root Props",
+      "description": "Pass wrapper attributes/styling via rootProps",
+      "code": "<Textarea\n  label=\"Notes\"\n  placeholder=\"Add notes...\"\n  rootProps={{ 'data-demo': 'textarea-wrapper' }}\n/>"
+    },
+    {
+      "name": "Success State",
+      "description": "Textarea showing validated/success styling",
+      "code": "<Textarea\n  label=\"Bio\"\n  value=\"A short bio about myself.\"\n  success\n  helperText=\"Looks great!\"\n/>"
+    },
+    {
+      "name": "With Character Counter",
+      "description": "Textarea with character count and maxLength",
+      "code": "<Textarea\n  label=\"Bio\"\n  placeholder=\"Tell us about yourself...\"\n  maxLength={200}\n  showCharCount\n/>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Input",
+      "relationship": "alternative",
+      "note": "Use Input for single-line text"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "value: string - controlled value",
+      "rows: number - visible rows (default: 3)",
+      "label: string - label text",
+      "size: sm|md|lg (default: md)",
+      "error: boolean - error state",
+      "success: boolean - shows success/validated styling",
+      "showCharCount: boolean - show character counter (requires maxLength)",
+      "disabled: boolean - disabled state",
+      "resize: none|vertical|horizontal|both",
+      "onValueChange: (value: string) => void - value-first change callback alias",
+      "rootProps: HTMLAttributes<HTMLDivElement> - wrapper element props",
+      "...native textarea attributes are supported (readOnly, autoComplete, maxLength, onKeyDown, etc.)"
+    ],
+    "a11yRules": [
+      "A11Y_LABEL_REQUIRED"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:05.217Z"
+  }
+}