@fragments-sdk/ui 0.17.1 → 0.18.0

package/src/components/Checkbox/Checkbox.contract.json

@@ -0,0 +1,246 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Checkbox",
+  "description": "Binary toggle for form fields. Use for options that require explicit submission, unlike Switch which takes effect immediately.",
+  "category": "forms",
+  "tags": [
+    "checkbox",
+    "form",
+    "boolean",
+    "selection",
+    "input"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Checkbox/index.tsx",
+  "exportName": "Checkbox",
+  "propsSummary": [
+    "checked: boolean",
+    "defaultChecked: boolean",
+    "onCheckedChange: function",
+    "onChange: function",
+    "indeterminate: boolean (default: false)",
+    "disabled: boolean (default: false)",
+    "required: boolean (default: false)",
+    "size: sm|md|lg (default: md)",
+    "label: string",
+    "helperText: string",
+    "description: string",
+    "name: string",
+    "value: string",
+    "id: string",
+    "controlClassName: string",
+    "contentClassName: string",
+    "aria-label: string",
+    "aria-labelledby: string",
+    "aria-describedby: string"
+  ],
+  "props": {
+    "checked": {
+      "type": "boolean",
+      "description": "Controlled checked state",
+      "required": false
+    },
+    "defaultChecked": {
+      "type": "boolean",
+      "description": "Default checked state (uncontrolled)",
+      "required": false
+    },
+    "onCheckedChange": {
+      "type": "function",
+      "description": "Called when checked state changes",
+      "required": false
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Alias for onCheckedChange: (checked: boolean) => void",
+      "required": false
+    },
+    "indeterminate": {
+      "type": "boolean",
+      "description": "Indeterminate state (partial selection)",
+      "default": "false",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disable the checkbox",
+      "default": "false",
+      "required": false
+    },
+    "required": {
+      "type": "boolean",
+      "description": "Whether the checkbox is required",
+      "default": "false",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "description": "Checkbox size",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "label": {
+      "type": "string",
+      "description": "Label text",
+      "required": false
+    },
+    "helperText": {
+      "type": "string",
+      "description": "Helper text shown below the label (preferred)",
+      "required": false
+    },
+    "description": {
+      "type": "string",
+      "description": "Deprecated alias for helperText",
+      "required": false
+    },
+    "name": {
+      "type": "string",
+      "description": "Name attribute for form submission",
+      "required": false
+    },
+    "value": {
+      "type": "string",
+      "description": "Value attribute for form submission",
+      "required": false
+    },
+    "id": {
+      "type": "string",
+      "description": "ID for the checkbox input",
+      "required": false
+    },
+    "controlClassName": {
+      "type": "string",
+      "description": "Class name for the checkbox control element (stable styling target)",
+      "required": false
+    },
+    "contentClassName": {
+      "type": "string",
+      "description": "Class name for the label/description content wrapper",
+      "required": false
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "Accessible label for icon-only mode",
+      "required": false
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "description": "Accessible labelled-by relationship for icon-only mode",
+      "required": false
+    },
+    "aria-describedby": {
+      "type": "string",
+      "description": "Accessible described-by relationship",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Form fields requiring explicit submission",
+      "Multi-select from a list of options",
+      "Terms and conditions acceptance",
+      "Filter or preference checklists"
+    ],
+    "whenNot": [
+      "Immediate effect settings (use Switch)",
+      "Single selection from options (use RadioGroup)",
+      "Selecting from many options (use Select)"
+    ],
+    "guidelines": [
+      "Always include a visible label",
+      "Use helperText for additional context when needed",
+      "Group related checkboxes visually",
+      "Use indeterminate state for parent/child relationships"
+    ],
+    "accessibility": [
+      "Proper label association",
+      "Keyboard accessible (Space to toggle)",
+      "Visible focus indicator",
+      "Indeterminate state properly announced"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic checkbox with label",
+      "code": "<StatefulCheckbox label=\"Accept terms and conditions\" />"
+    },
+    {
+      "name": "With Helper Text",
+      "description": "Checkbox with helper text",
+      "code": "<StatefulCheckbox\n  label=\"Email notifications\"\n  helperText=\"Receive email updates about your account activity\"\n/>"
+    },
+    {
+      "name": "Checked",
+      "description": "Pre-checked checkbox",
+      "code": "<StatefulCheckbox defaultChecked label=\"Subscribe to newsletter\" />"
+    },
+    {
+      "name": "Indeterminate",
+      "description": "Partial selection state",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Checkbox indeterminate label=\"Select all\" />\n  <div style={{ marginLeft: '24px', display: 'flex', flexDirection: 'column', gap: '8px' }}>\n    <StatefulCheckbox defaultChecked label=\"Option 1\" />\n    <StatefulCheckbox label=\"Option 2\" />\n    <StatefulCheckbox defaultChecked label=\"Option 3\" />\n  </div>\n</div>"
+    },
+    {
+      "name": "Sizes",
+      "description": "Available size options",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>\n  <StatefulCheckbox size=\"sm\" label=\"Small checkbox\" />\n  <StatefulCheckbox size=\"md\" label=\"Medium checkbox\" />\n  <StatefulCheckbox size=\"lg\" label=\"Large checkbox\" />\n</div>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Non-interactive states",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>\n  <Checkbox disabled label=\"Disabled unchecked\" />\n  <Checkbox disabled checked label=\"Disabled checked\" />\n</div>"
+    },
+    {
+      "name": "Custom Styling Targets",
+      "description": "Use explicit class targets for control vs content styling",
+      "code": "<Checkbox\n  label=\"Styled checkbox\"\n  helperText=\"Control and content wrappers can be targeted independently\"\n  controlClassName=\"demo-checkbox-control\"\n  contentClassName=\"demo-checkbox-content\"\n/>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Switch",
+      "relationship": "alternative",
+      "note": "Use Switch for immediate-effect settings"
+    },
+    {
+      "component": "Input",
+      "relationship": "sibling",
+      "note": "Checkbox handles boolean; Input handles text"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "checked: boolean - controlled checked state",
+      "onCheckedChange: (checked) => void - change handler",
+      "onChange: (checked) => void - alias for onCheckedChange",
+      "indeterminate: boolean - partial selection state",
+      "label: string - checkbox label",
+      "helperText: string - helper text (preferred)",
+      "description: string - deprecated alias for helperText",
+      "controlClassName/contentClassName - explicit styling targets for control and content"
+    ],
+    "a11yRules": [
+      "A11Y_CHECKBOX_LABEL",
+      "A11Y_CHECKBOX_FOCUS",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:52.226Z"
+  }
+}

package/src/components/Chip/Chip.contract.json

@@ -0,0 +1,212 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Chip",
+  "description": "Interactive pill-shaped element for filtering, selecting, and tagging. Supports single and multi-select via Chip.Group.",
+  "category": "forms",
+  "tags": [
+    "chip",
+    "tag",
+    "filter",
+    "selection",
+    "multi-select",
+    "action"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Chip/index.tsx",
+  "exportName": "Chip",
+  "propsSummary": [
+    "children: node (required)",
+    "variant: filled|outlined|outline|soft (default: filled)",
+    "size: xs|sm|md|lg (default: md)",
+    "selected: boolean (default: false)",
+    "icon: node",
+    "avatar: node",
+    "onRemove: function",
+    "value: string",
+    "disabled: boolean (default: false)",
+    "onClick: function"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Chip label text",
+      "required": true
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual style variant",
+      "default": "filled",
+      "required": false,
+      "values": [
+        "filled",
+        "outlined",
+        "outline",
+        "soft"
+      ]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Chip size",
+      "default": "md",
+      "required": false,
+      "values": [
+        "xs",
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "selected": {
+      "type": "boolean",
+      "description": "Whether the chip is in a selected state",
+      "default": "false",
+      "required": false
+    },
+    "icon": {
+      "type": "node",
+      "description": "Icon element rendered before the label",
+      "required": false
+    },
+    "avatar": {
+      "type": "node",
+      "description": "Avatar element rendered before the label",
+      "required": false
+    },
+    "onRemove": {
+      "type": "function",
+      "description": "Makes chip removable. Called when X is clicked.",
+      "required": false
+    },
+    "value": {
+      "type": "string",
+      "description": "Value identifier used by Chip.Group for selection tracking",
+      "required": false
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "",
+      "default": "false",
+      "required": false
+    },
+    "onClick": {
+      "type": "function",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Filtering content by categories or tags",
+      "Multi-select scenarios like choosing interests or skills",
+      "Toggling options in a compact pill-shaped control",
+      "Displaying removable user-applied filters"
+    ],
+    "whenNot": [
+      "Display-only status labels (use Badge)",
+      "Navigation between views (use Tabs)",
+      "Binary on/off state (use Switch)",
+      "Primary call-to-action (use Button)"
+    ],
+    "guidelines": [
+      "Keep chip labels short (1-3 words)",
+      "Use Chip.Group for multi-select sets with shared state",
+      "Use onRemove only when users should be able to dismiss the chip",
+      "Pair avatar chips with user-related selections (assignees, reviewers)",
+      "Provide an explicit value on Chip when using non-string/custom JSX children inside Chip.Group"
+    ],
+    "accessibility": [
+      "Chips are buttons and use aria-pressed for selection state",
+      "Chip.Group is a grouping wrapper; add role/aria-label when needed for assistive context",
+      "Remove buttons include descriptive aria-label with chip text",
+      "Disabled chips are properly excluded from interaction"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic filled chip",
+      "code": "<Chip>Default</Chip>"
+    },
+    {
+      "name": "Outline",
+      "description": "Chip with border using the \"outline\" alias for \"outlined\"",
+      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip variant=\"outline\">Outline</Chip>\n  <Chip variant=\"outline\" selected>Outline Selected</Chip>\n</div>"
+    },
+    {
+      "name": "Selected",
+      "description": "Chip in selected state across variants",
+      "code": "<div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>\n  <Chip selected>Filled</Chip>\n  <Chip variant=\"outlined\" selected>Outlined</Chip>\n  <Chip variant=\"soft\" selected>Soft</Chip>\n</div>"
+    },
+    {
+      "name": "With Avatar",
+      "description": "Chip with a leading avatar image",
+      "code": "<Chip avatar={<img src=\"https://i.pravatar.cc/32?u=chip\" alt=\"\" />}>\n  Jane Doe\n</Chip>"
+    },
+    {
+      "name": "With Remove",
+      "description": "Removable chip with dismiss button",
+      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip onRemove={() => {}}>React</Chip>\n  <Chip onRemove={() => {}}>TypeScript</Chip>\n  <Chip onRemove={() => {}}>SCSS</Chip>\n</div>"
+    },
+    {
+      "name": "Chip Group",
+      "description": "Multi-select chip set with shared state",
+      "code": "<Chip.Group defaultValue={['react']}>\n  <Chip value=\"react\">React</Chip>\n  <Chip value=\"vue\">Vue</Chip>\n  <Chip value=\"angular\">Angular</Chip>\n  <Chip value=\"svelte\">Svelte</Chip>\n</Chip.Group>"
+    },
+    {
+      "name": "Chip Group with Custom Labels",
+      "description": "Use explicit values when chip labels are custom JSX",
+      "code": "<Chip.Group aria-label=\"Assignees\">\n  <Chip value=\"jane\">\n    <span>Jane Doe</span>\n  </Chip>\n  <Chip value=\"sam\">\n    <span>Sam Lee</span>\n  </Chip>\n</Chip.Group>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Chip in disabled state",
+      "code": "<div style={{ display: 'flex', gap: '8px' }}>\n  <Chip disabled>Disabled</Chip>\n  <Chip disabled selected>Disabled Selected</Chip>\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Badge",
+      "relationship": "sibling",
+      "note": "Badge is display-only; Chip is interactive"
+    },
+    {
+      "component": "ToggleGroup",
+      "relationship": "alternative",
+      "note": "Use ToggleGroup for mutually exclusive options"
+    },
+    {
+      "component": "Button",
+      "relationship": "alternative",
+      "note": "Use Button for primary actions, Chip for selection/filtering"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - chip label (required)",
+      "variant: filled|outlined|outline|soft - visual style",
+      "size: sm|md - chip size",
+      "selected: boolean - selection state",
+      "icon/avatar: ReactNode - leading visual",
+      "onRemove: () => void - makes chip removable",
+      "value: string - identifier for Chip.Group",
+      "Chip.Group forwards DOM props (id, role, aria-*, data-*, handlers)",
+      "Chip.Group: non-string chip labels should set an explicit value"
+    ],
+    "a11yRules": [
+      "A11Y_CHIP_SELECTION",
+      "A11Y_CHIP_DISMISS"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Group"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:54.270Z"
+  }
+}