@fragments-sdk/ui 0.17.0 → 0.18.0

package/src/components/Editor/Editor.contract.json

@@ -0,0 +1,263 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Editor",
+  "description": "Rich text editor with formatting toolbar, auto-save, and word count",
+  "category": "forms",
+  "tags": [
+    "editor",
+    "rich-text",
+    "markdown",
+    "toolbar",
+    "writing",
+    "blog",
+    "content"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Editor/index.tsx",
+  "exportName": "Editor",
+  "propsSummary": [
+    "children: node",
+    "value: string",
+    "defaultValue: string (default: )",
+    "onValueChange: function",
+    "placeholder: string (default: Start typing...)",
+    "disabled: boolean (default: false)",
+    "readOnly: boolean (default: false)",
+    "formats: array",
+    "toolbar: boolean (default: true)",
+    "statusBar: boolean (default: true)",
+    "onAutoSave: function",
+    "autoSaveInterval: number (default: 30000)",
+    "size: sm|md|lg (default: md)",
+    "maxLength: number",
+    "toolbarIcons: object"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "",
+      "required": false
+    },
+    "value": {
+      "type": "string",
+      "description": "Controlled editor value",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "string",
+      "description": "Default value for uncontrolled usage",
+      "default": "",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "description": "Called when content changes",
+      "required": false
+    },
+    "placeholder": {
+      "type": "string",
+      "description": "Placeholder text shown when empty",
+      "default": "Start typing...",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disable the editor",
+      "default": "false",
+      "required": false
+    },
+    "readOnly": {
+      "type": "boolean",
+      "description": "Make the editor read-only",
+      "default": "false",
+      "required": false
+    },
+    "formats": {
+      "type": "array",
+      "description": "Which format buttons to show in the toolbar",
+      "default": "[\"bold\", \"italic\", \"strikethrough\", \"link\", \"code\", \"bulletList\"]",
+      "required": false
+    },
+    "toolbar": {
+      "type": "boolean",
+      "description": "Show default toolbar",
+      "default": "true",
+      "required": false
+    },
+    "statusBar": {
+      "type": "boolean",
+      "description": "Show default status bar with word/character counts",
+      "default": "true",
+      "required": false
+    },
+    "onAutoSave": {
+      "type": "function",
+      "description": "Auto-save callback, called at autoSaveInterval (may be async)",
+      "required": false
+    },
+    "autoSaveInterval": {
+      "type": "number",
+      "description": "Auto-save interval in milliseconds",
+      "default": "30000",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "description": "Editor size preset: \"sm\" (120px), \"md\" (200px), or \"lg\" (400px)",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "maxLength": {
+      "type": "number",
+      "description": "Maximum character count. Shows counter in status bar with warning (90%) and error (over limit) states",
+      "required": false
+    },
+    "toolbarIcons": {
+      "type": "object",
+      "description": "Optional toolbar icon overrides keyed by format/action (e.g. bold, italic, undo). Values can be React nodes or render functions.",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Building blog post or article editors",
+      "Need rich text editing with formatting controls",
+      "Content management with auto-save and word count",
+      "Markdown or WYSIWYG editing interfaces"
+    ],
+    "whenNot": [
+      "Simple single-line text input (use Input)",
+      "Plain multi-line without formatting (use Textarea)",
+      "Chat/AI prompt input (use Prompt)",
+      "Code editing (use CodeBlock)"
+    ],
+    "guidelines": [
+      "Use compound pattern for custom toolbar layouts",
+      "Install @tiptap/react, @tiptap/starter-kit, and @tiptap/extension-link for rich text mode",
+      "Falls back to a markdown-aware textarea when TipTap is not installed",
+      "Use onAutoSave for periodic content persistence",
+      "onAutoSave may return a Promise; save status updates after the async save resolves/rejects",
+      "Use size prop (sm/md/lg) to control editor height",
+      "Use maxLength to show character limit with visual warning states",
+      "New formats (headings, blockquote, orderedList, undo, redo) are opt-in via the formats prop",
+      "Use toolbarIcons to swap in icons from any icon package without changing toolbar button labels or accessibility behavior"
+    ],
+    "accessibility": [
+      "Toolbar has role=\"toolbar\" with aria-label",
+      "Format buttons use aria-pressed to indicate active state",
+      "Action buttons (undo/redo) omit aria-pressed since they are not toggles",
+      "Status indicator uses aria-live=\"polite\" for save status announcements",
+      "Keyboard shortcuts match standard text editor conventions (Ctrl+B, Ctrl+I, etc.)",
+      "Global shortcuts (e.g., Sidebar Ctrl+B) automatically yield when focus is inside the Editor",
+      "Focus ring appears on the editor container when any child element is focused"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Editor with default toolbar and status bar",
+      "code": "<Editor placeholder=\"Start typing your masterpiece here...\" />"
+    },
+    {
+      "name": "With Auto-Save and Publish",
+      "description": "Full compound usage with custom toolbar, auto-save indicator, and publish button",
+      "code": "<Editor\n  placeholder=\"Start typing your masterpiece here...\"\n  onValueChange={(v) => console.log(v)}\n>\n  <Editor.Toolbar>\n    <Editor.ToolbarGroup aria-label=\"Text formatting\">\n      <Editor.ToolbarButton format=\"bold\" />\n      <Editor.ToolbarButton format=\"italic\" />\n      <Editor.ToolbarButton format=\"strikethrough\" />\n      <Editor.ToolbarButton format=\"link\" />\n      <Editor.ToolbarButton format=\"code\" />\n      <Editor.ToolbarButton format=\"bulletList\" />\n    </Editor.ToolbarGroup>\n    <Editor.ToolbarGroup aria-label=\"Actions\">\n      <Editor.StatusIndicator status=\"saved\" />\n      <Button variant=\"accent\" size=\"sm\">\n        Publish\n      </Button>\n    </Editor.ToolbarGroup>\n  </Editor.Toolbar>\n  <Editor.Content />\n  <Editor.StatusBar showWordCount showCharCount />\n</Editor>"
+    },
+    {
+      "name": "Minimal",
+      "description": "Editor with subset of formats",
+      "code": "<Editor\n  placeholder=\"Quick note...\"\n  formats={['bold', 'italic', 'code']}\n/>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Non-interactive editor with content",
+      "code": "<Editor\n  defaultValue=\"This content cannot be edited.\"\n  disabled\n/>"
+    },
+    {
+      "name": "Read Only",
+      "description": "Visible content, non-editable",
+      "code": "<Editor\n  defaultValue=\"This content is read-only. You can select and copy text but cannot modify it.\"\n  readOnly\n/>"
+    },
+    {
+      "name": "Custom Toolbar",
+      "description": "Compound usage with custom toolbar layout and separator",
+      "code": "<Editor\n  placeholder=\"Write your blog post...\"\n  onValueChange={(v) => console.log(v)}\n>\n  <Editor.Toolbar>\n    <Editor.ToolbarGroup aria-label=\"Basic formatting\">\n      <Editor.ToolbarButton format=\"bold\" />\n      <Editor.ToolbarButton format=\"italic\" />\n    </Editor.ToolbarGroup>\n    <Editor.Separator />\n    <Editor.ToolbarGroup aria-label=\"Advanced formatting\">\n      <Editor.ToolbarButton format=\"link\" />\n      <Editor.ToolbarButton format=\"code\" />\n      <Editor.ToolbarButton format=\"bulletList\" />\n    </Editor.ToolbarGroup>\n    <Editor.ToolbarGroup aria-label=\"Status\">\n      <Editor.StatusIndicator status=\"saving\" />\n    </Editor.ToolbarGroup>\n  </Editor.Toolbar>\n  <Editor.Content />\n  <Editor.StatusBar showWordCount showCharCount />\n</Editor>"
+    },
+    {
+      "name": "Full Formatting",
+      "description": "All format options including headings, blockquote, ordered list, undo/redo",
+      "code": "<Editor\n  placeholder=\"Write an article...\"\n  size=\"lg\"\n>\n  <Editor.Toolbar>\n    <Editor.ToolbarGroup aria-label=\"History\">\n      <Editor.ToolbarButton format=\"undo\" />\n      <Editor.ToolbarButton format=\"redo\" />\n    </Editor.ToolbarGroup>\n    <Editor.Separator />\n    <Editor.ToolbarGroup aria-label=\"Headings\">\n      <Editor.ToolbarButton format=\"heading1\" />\n      <Editor.ToolbarButton format=\"heading2\" />\n      <Editor.ToolbarButton format=\"heading3\" />\n    </Editor.ToolbarGroup>\n    <Editor.Separator />\n    <Editor.ToolbarGroup aria-label=\"Text formatting\">\n      <Editor.ToolbarButton format=\"bold\" />\n      <Editor.ToolbarButton format=\"italic\" />\n      <Editor.ToolbarButton format=\"strikethrough\" />\n      <Editor.ToolbarButton format=\"code\" />\n    </Editor.ToolbarGroup>\n    <Editor.Separator />\n    <Editor.ToolbarGroup aria-label=\"Block formatting\">\n      <Editor.ToolbarButton format=\"bulletList\" />\n      <Editor.ToolbarButton format=\"orderedList\" />\n      <Editor.ToolbarButton format=\"blockquote\" />\n      <Editor.ToolbarButton format=\"link\" />\n    </Editor.ToolbarGroup>\n  </Editor.Toolbar>\n  <Editor.Content />\n  <Editor.StatusBar showWordCount showCharCount />\n</Editor>"
+    },
+    {
+      "name": "With Character Limit",
+      "description": "Editor with maxLength showing character count indicator with warning and error states",
+      "code": "<Editor\n  placeholder=\"Write a tweet-sized message...\"\n  maxLength={280}\n  size=\"sm\"\n  formats={['bold', 'italic', 'link']}\n/>"
+    },
+    {
+      "name": "Small Size",
+      "description": "Compact editor with sm size preset (120px min-height)",
+      "code": "<Editor\n  placeholder=\"Quick note...\"\n  size=\"sm\"\n  formats={['bold', 'italic', 'code']}\n/>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Prompt",
+      "relationship": "sibling",
+      "note": "Prompt is for AI/chat input; Editor is for long-form content editing"
+    },
+    {
+      "component": "Textarea",
+      "relationship": "alternative",
+      "note": "Use Textarea for simple multi-line input without formatting toolbar"
+    },
+    {
+      "component": "Input",
+      "relationship": "alternative",
+      "note": "Use Input for single-line text input"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "value: string - controlled editor value",
+      "onValueChange: (value: string) => void - change callback",
+      "placeholder: string - hint text (default: \"Start typing...\")",
+      "disabled: boolean - disables interaction",
+      "readOnly: boolean - prevents editing",
+      "formats: EditorFormat[] - toolbar buttons (default: all 6)",
+      "toolbar: boolean - show default toolbar (default: true)",
+      "statusBar: boolean - show word/char counts (default: true)",
+      "onAutoSave: (value: string) => void | Promise<void> - auto-save handler",
+      "size: \"sm\" | \"md\" | \"lg\" - editor height preset (default: \"md\")",
+      "maxLength: number - character limit with visual indicator",
+      "toolbarIcons: Partial<Record<EditorFormat, ReactNode | (state) => ReactNode>> - custom toolbar icons"
+    ],
+    "a11yRules": [
+      "A11Y_TOOLBAR_ROLE",
+      "A11Y_BUTTON_LABEL",
+      "A11Y_LIVE_REGION"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Toolbar",
+      "ToolbarGroup",
+      "ToolbarButton",
+      "Separator",
+      "StatusIndicator",
+      "Content",
+      "StatusBar"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:56.748Z"
+  }
+}

package/src/components/EmptyState/EmptyState.contract.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "EmptyState",
+  "description": "Placeholder for empty content areas. Provides context, guidance, and actions when no data is available.",
+  "category": "feedback",
+  "tags": [
+    "empty",
+    "placeholder",
+    "no-data",
+    "zero-state",
+    "blank-slate"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/EmptyState/index.tsx",
+  "exportName": "EmptyState",
+  "propsSummary": [
+    "children: node (required)",
+    "size: sm|md|lg (default: md)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "EmptyState content - use EmptyState.Icon, EmptyState.Title, EmptyState.Description, EmptyState.Actions sub-components",
+      "required": true
+    },
+    "size": {
+      "type": "enum",
+      "description": "Size variant",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    }
+  },
+  "usage": {
+    "when": [
+      "Empty lists, tables, or search results",
+      "New user onboarding (no content yet)",
+      "Filtered views with no matches",
+      "Error states where content failed to load"
+    ],
+    "whenNot": [
+      "Loading states (use skeleton or spinner)",
+      "Error messages with retry (use Alert)",
+      "Temporary messages (use Toast)"
+    ],
+    "guidelines": [
+      "Always explain why the area is empty",
+      "Provide a clear action to resolve the empty state",
+      "Use appropriate icons to reinforce the message",
+      "Keep messaging positive and actionable",
+      "EmptyState compound sub-components forward DOM props for ids, aria attributes, and handlers"
+    ],
+    "accessibility": [
+      "Empty state content is accessible to screen readers",
+      "Action buttons follow button accessibility guidelines"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic empty state with action",
+      "code": "<EmptyState>\n  <EmptyState.Icon><FolderIcon /></EmptyState.Icon>\n  <EmptyState.Title>No projects yet</EmptyState.Title>\n  <EmptyState.Description>Get started by creating your first project.</EmptyState.Description>\n  <EmptyState.Actions>\n    <Button>Create Project</Button>\n  </EmptyState.Actions>\n</EmptyState>"
+    },
+    {
+      "name": "No Results",
+      "description": "Empty search results",
+      "code": "<EmptyState>\n  <EmptyState.Icon><SearchIcon /></EmptyState.Icon>\n  <EmptyState.Title>No results found</EmptyState.Title>\n  <EmptyState.Description>Try adjusting your search terms or filters.</EmptyState.Description>\n  <EmptyState.Actions>\n    <Button variant=\"secondary\">Clear Filters</Button>\n  </EmptyState.Actions>\n</EmptyState>"
+    },
+    {
+      "name": "With Secondary Action",
+      "description": "Empty state with two actions",
+      "code": "<EmptyState>\n  <EmptyState.Icon><InboxIcon /></EmptyState.Icon>\n  <EmptyState.Title>Inbox is empty</EmptyState.Title>\n  <EmptyState.Description>You have no new messages.</EmptyState.Description>\n  <EmptyState.Actions>\n    <Button>Compose Message</Button>\n    <Button variant=\"secondary\">View Archive</Button>\n  </EmptyState.Actions>\n</EmptyState>"
+    },
+    {
+      "name": "Small",
+      "description": "Compact empty state for inline use",
+      "code": "<EmptyState size=\"sm\">\n  <EmptyState.Title>No items</EmptyState.Title>\n  <EmptyState.Description>Add items to see them here.</EmptyState.Description>\n</EmptyState>"
+    },
+    {
+      "name": "Large",
+      "description": "Prominent empty state for full-page use",
+      "code": "<EmptyState size=\"lg\">\n  <EmptyState.Icon><FolderIcon /></EmptyState.Icon>\n  <EmptyState.Title>Welcome to your workspace</EmptyState.Title>\n  <EmptyState.Description>\n    This is where your projects will appear. Create your first project to get started.\n  </EmptyState.Description>\n  <EmptyState.Actions>\n    <Button>Create Your First Project</Button>\n  </EmptyState.Actions>\n</EmptyState>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Alert",
+      "relationship": "alternative",
+      "note": "Use Alert for error states with retry"
+    },
+    {
+      "component": "Progress",
+      "relationship": "alternative",
+      "note": "Use Progress/Spinner for loading states"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "size: sm|md|lg (default: md)",
+      "Sub-components: EmptyState.Icon, EmptyState.Title, EmptyState.Description, EmptyState.Actions",
+      "Compound sub-components forward DOM props to their rendered elements"
+    ],
+    "a11yRules": [
+      "A11Y_EMPTY_STATE_CONTENT"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Icon",
+      "Title",
+      "Description",
+      "Actions"
+    ],
+    "requiredChildren": [
+      "Title"
+    ],
+    "commonPatterns": [
+      "<EmptyState><EmptyState.Title>{title}</EmptyState.Title><EmptyState.Description>{description}</EmptyState.Description></EmptyState>",
+      "<EmptyState><EmptyState.Icon>{icon}</EmptyState.Icon><EmptyState.Title>{title}</EmptyState.Title><EmptyState.Description>{description}</EmptyState.Description><EmptyState.Actions><Button>{action}</Button></EmptyState.Actions></EmptyState>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:56.922Z"
+  }
+}

package/src/components/Field/Field.contract.json

@@ -0,0 +1,157 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Field",
+  "description": "Compositional form field wrapper providing validation, labels, descriptions, and error messages. Use for advanced form needs beyond baked-in Input/Textarea props.",
+  "category": "forms",
+  "tags": [
+    "form",
+    "field",
+    "validation",
+    "label",
+    "error",
+    "input",
+    "accessible"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Field/index.tsx",
+  "exportName": "Field",
+  "propsSummary": [
+    "children: node (required)",
+    "name: string",
+    "disabled: boolean",
+    "invalid: boolean",
+    "validate: function",
+    "validationMode: onSubmit|onBlur|onChange",
+    "validationDebounceTime: number"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Field content (Label, Control, Description, Error)",
+      "required": true
+    },
+    "name": {
+      "type": "string",
+      "description": "Field name, used for error distribution from Form",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disables the field and its control",
+      "required": false
+    },
+    "invalid": {
+      "type": "boolean",
+      "description": "Marks the field as invalid",
+      "required": false
+    },
+    "validate": {
+      "type": "function",
+      "description": "Custom validation function returning error string(s) or null",
+      "required": false
+    },
+    "validationMode": {
+      "type": "enum",
+      "description": "When to trigger validation",
+      "required": false,
+      "values": [
+        "onSubmit",
+        "onBlur",
+        "onChange"
+      ]
+    },
+    "validationDebounceTime": {
+      "type": "number",
+      "description": "Debounce time in ms for onChange validation",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "You need granular validation with match-based error messages",
+      "Custom form controls need accessible labels and descriptions",
+      "Server-side errors need to be distributed to specific fields",
+      "You need dirty/touched tracking or custom validation logic"
+    ],
+    "whenNot": [
+      "Simple inputs with basic label and helper text (use Input with label prop)",
+      "Standalone selects or textareas with built-in error display"
+    ],
+    "guidelines": [
+      "Always provide a Field.Label for accessibility",
+      "Wrap any form control in Field.Control to connect it to the field context",
+      "Use match prop on Field.Error for granular native validation messages",
+      "Wrap in Form to enable server-side error distribution by field name"
+    ],
+    "accessibility": [
+      "Label automatically linked to control via aria-labelledby",
+      "Description linked via aria-describedby",
+      "Error messages announced to screen readers",
+      "Supports data-disabled and data-invalid attributes for styling"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Single field",
+      "description": "A single field with label, control, and description",
+      "code": "<Field name=\"email\">\n  <Field.Label>Email address</Field.Label>\n  <Field.Control>\n    <Input type=\"email\" placeholder=\"jane@example.com\" />\n  </Field.Control>\n  <Field.Description>We will never share your email.</Field.Description>\n</Field>"
+    },
+    {
+      "name": "Two-column layout",
+      "description": "Fields arranged in a two-column grid",
+      "code": "<Grid columns={2} gap=\"md\">\n  <Field name=\"firstName\">\n    <Field.Label>First Name</Field.Label>\n    <Field.Control>\n      <Input placeholder=\"Jane\" />\n    </Field.Control>\n  </Field>\n  <Field name=\"lastName\">\n    <Field.Label>Last Name</Field.Label>\n    <Field.Control>\n      <Input placeholder=\"Doe\" />\n    </Field.Control>\n  </Field>\n  <Grid.Item colSpan=\"full\">\n    <Field name=\"email\">\n      <Field.Label>Email</Field.Label>\n      <Field.Control>\n        <Input type=\"email\" placeholder=\"jane@example.com\" />\n      </Field.Control>\n      <Field.Error match=\"typeMismatch\">Enter a valid email address</Field.Error>\n    </Field>\n  </Grid.Item>\n</Grid>"
+    },
+    {
+      "name": "Custom validation",
+      "description": "Field with custom validate function",
+      "code": "<Field\n  name=\"age\"\n  validate={(value) => {\n    const num = Number(value);\n    if (isNaN(num) || num < 18) return 'Must be 18 or older';\n    return null;\n  }}\n  validationMode=\"onChange\"\n  validationDebounceTime={500}\n>\n  <Field.Label>Age</Field.Label>\n  <Field.Control>\n    <Input type=\"number\" placeholder=\"18\" />\n  </Field.Control>\n  <Field.Description>You must be at least 18 years old.</Field.Description>\n  <Field.Error match=\"customError\" />\n</Field>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Input",
+      "relationship": "alternative",
+      "note": "Use Input for simple fields with built-in label/error"
+    },
+    {
+      "component": "Form",
+      "relationship": "parent",
+      "note": "Wrap in Form for server-side error distribution"
+    },
+    {
+      "component": "Fieldset",
+      "relationship": "sibling",
+      "note": "Use Fieldset to group related fields"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "name: string - field name for error distribution",
+      "validate: (value) => string | null - custom validation",
+      "validationMode: onSubmit|onBlur|onChange - validation trigger",
+      "Field.Control: wraps any form component (Input, Textarea, etc.)",
+      "Field.Error match: valueMissing|typeMismatch|customError|... - granular errors"
+    ],
+    "a11yRules": [
+      "A11Y_FIELD_LABEL",
+      "A11Y_FIELD_ERROR",
+      "A11Y_FIELD_DESCRIPTION"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Label",
+      "Control",
+      "Description",
+      "Error",
+      "Validity"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:59.733Z"
+  }
+}