@fragments-sdk/ui 0.17.1 → 0.19.0

package/src/components/Image/Image.contract.json

@@ -0,0 +1,209 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Image",
+  "description": "Responsive image component with aspect ratio control, loading states, and error fallbacks. Handles image display with consistent styling.",
+  "category": "display",
+  "tags": [
+    "image",
+    "media",
+    "photo",
+    "picture",
+    "visual"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Image/index.tsx",
+  "exportName": "Image",
+  "propsSummary": [
+    "src: string (required)",
+    "alt: string (required)",
+    "aspectRatio: 1:1|4:3|16:9|21:9|auto (default: auto)",
+    "objectFit: cover|contain|fill|none (default: cover)",
+    "width: union",
+    "height: union",
+    "rounded: none|sm|md|lg|full (default: none)",
+    "fallback: node",
+    "className: string",
+    "style: object",
+    "imgProps: object",
+    "onImageLoad: function",
+    "onImageError: function"
+  ],
+  "props": {
+    "src": {
+      "type": "string",
+      "description": "Image source URL",
+      "required": true
+    },
+    "alt": {
+      "type": "string",
+      "description": "Alt text for accessibility (required)",
+      "required": true
+    },
+    "aspectRatio": {
+      "type": "enum",
+      "description": "Aspect ratio of the image container",
+      "default": "auto",
+      "required": false,
+      "values": [
+        "1:1",
+        "4:3",
+        "16:9",
+        "21:9",
+        "auto"
+      ]
+    },
+    "objectFit": {
+      "type": "enum",
+      "description": "How the image fits within its container",
+      "default": "cover",
+      "required": false,
+      "values": [
+        "cover",
+        "contain",
+        "fill",
+        "none"
+      ]
+    },
+    "width": {
+      "type": "union",
+      "description": "Width of the image container",
+      "required": false
+    },
+    "height": {
+      "type": "union",
+      "description": "Height of the image container",
+      "required": false
+    },
+    "rounded": {
+      "type": "enum",
+      "description": "Border radius",
+      "default": "none",
+      "required": false,
+      "values": [
+        "none",
+        "sm",
+        "md",
+        "lg",
+        "full"
+      ]
+    },
+    "fallback": {
+      "type": "node",
+      "description": "Content to show while loading or on error",
+      "required": false
+    },
+    "className": {
+      "type": "string",
+      "description": "Additional class name",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "Inline styles",
+      "required": false
+    },
+    "imgProps": {
+      "type": "object",
+      "description": "Additional props for the underlying img element (except src/alt/size/style/events)",
+      "required": false
+    },
+    "onImageLoad": {
+      "type": "function",
+      "description": "Called when the underlying img element loads",
+      "required": false
+    },
+    "onImageError": {
+      "type": "function",
+      "description": "Called when the underlying img element fails to load",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Displaying product images in cards or grids",
+      "Hero images with specific aspect ratios",
+      "User-uploaded content that may fail to load",
+      "Thumbnails in lists or galleries"
+    ],
+    "whenNot": [
+      "User avatars (use Avatar component)",
+      "Icons or symbols (use Icon component)",
+      "Background images (use CSS background-image)",
+      "SVG illustrations (use inline SVG or Image component)"
+    ],
+    "guidelines": [
+      "Always provide meaningful alt text for accessibility",
+      "Use appropriate aspect ratios for consistent layouts",
+      "Provide fallback content for failed loads",
+      "Use objectFit=\"contain\" for logos to preserve aspect ratio",
+      "Use imgProps / onImageLoad / onImageError when you need lower-level img control"
+    ],
+    "accessibility": [
+      "Alt text is required and must describe the image content",
+      "Decorative images should have empty alt=\"\"",
+      "Avoid text in images; if necessary, describe the text in alt",
+      "Ensure sufficient contrast between image and surrounding content"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic image display",
+      "code": "<Image\n  src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=400&h=300&fit=crop\"\n  alt=\"Code on a screen\"\n  width={300}\n/>"
+    },
+    {
+      "name": "Aspect Ratios",
+      "description": "Different aspect ratio options",
+      "code": "<div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=200&h=200&fit=crop\"\n    alt=\"Square image\"\n    aspectRatio=\"1:1\"\n    width={100}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=200&h=150&fit=crop\"\n    alt=\"4:3 image\"\n    aspectRatio=\"4:3\"\n    width={120}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=320&h=180&fit=crop\"\n    alt=\"16:9 image\"\n    aspectRatio=\"16:9\"\n    width={160}\n  />\n</div>"
+    },
+    {
+      "name": "Rounded Corners",
+      "description": "Border radius options",
+      "code": "<div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"No rounding\"\n    rounded=\"none\"\n    width={80}\n    height={80}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"Medium rounding\"\n    rounded=\"md\"\n    width={80}\n    height={80}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"Full rounding\"\n    rounded=\"full\"\n    width={80}\n    height={80}\n  />\n</div>"
+    },
+    {
+      "name": "With Fallback",
+      "description": "Fallback content for loading/error states",
+      "code": "<Image\n  src=\"https://invalid-url.example/image.jpg\"\n  alt=\"Image that will fail\"\n  width={200}\n  height={150}\n  rounded=\"md\"\n  fallback={\n    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', height: '100%', background: 'var(--fui-color-surface-secondary)' }}>\n      <span style={{ color: 'var(--fui-color-text-tertiary)' }}>No image</span>\n    </div>\n  }\n/>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Card",
+      "relationship": "child",
+      "note": "Common pattern to use Image at top of product cards"
+    },
+    {
+      "component": "Avatar",
+      "relationship": "alternative",
+      "note": "Use Avatar for user profile pictures"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "src: string - image URL (required)",
+      "alt: string - accessibility text (required)",
+      "aspectRatio: 1:1|4:3|16:9|21:9|auto - container ratio",
+      "objectFit: cover|contain|fill|none - image fitting",
+      "rounded: none|sm|md|lg|full - border radius",
+      "fallback: ReactNode - loading/error content",
+      "imgProps/onImageLoad/onImageError - low-level img customization and events"
+    ],
+    "a11yRules": [
+      "A11Y_IMG_ALT",
+      "A11Y_IMG_DECORATIVE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:59.379Z"
+  }
+}

package/src/components/Input/Input.contract.json

@@ -0,0 +1,344 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Input",
+  "description": "Text input field for single-line user data entry",
+  "category": "forms",
+  "tags": [
+    "form",
+    "input",
+    "text"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Input/index.tsx",
+  "exportName": "Input",
+  "propsSummary": [
+    "value: string",
+    "defaultValue: string",
+    "placeholder: string",
+    "type: number|text|email|password|tel|url (default: text)",
+    "size: sm|md|lg (default: md)",
+    "disabled: boolean (default: false)",
+    "error: boolean (default: false)",
+    "success: boolean (default: false)",
+    "label: string",
+    "required: boolean (default: false)",
+    "helperText: string",
+    "startAdornment: node",
+    "endAdornment: node",
+    "shortcut: string",
+    "shortcutBehavior: display-only|focus-input (default: display-only)",
+    "onChange: function",
+    "onValueChange: function",
+    "onBlur: function",
+    "onFocus: function",
+    "onKeyDown: function",
+    "rootProps: object",
+    "inputStyle: object",
+    "inputClassName: string",
+    "withFieldWrapper: boolean (default: true)",
+    "className: string",
+    "style: object"
+  ],
+  "props": {
+    "value": {
+      "type": "string",
+      "description": "Current input value (controlled)",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "string",
+      "description": "Default value for uncontrolled usage",
+      "required": false
+    },
+    "placeholder": {
+      "type": "string",
+      "description": "Placeholder text shown when empty",
+      "required": false,
+      "constraints": [
+        "Use for format hints only, not as a replacement for labels"
+      ]
+    },
+    "type": {
+      "type": "enum",
+      "description": "HTML input type for validation and keyboard",
+      "default": "text",
+      "required": false,
+      "values": [
+        "number",
+        "text",
+        "email",
+        "password",
+        "tel",
+        "url"
+      ]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Size variant",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Whether the input is interactive",
+      "default": "false",
+      "required": false
+    },
+    "error": {
+      "type": "boolean",
+      "description": "Whether to show error styling",
+      "default": "false",
+      "required": false
+    },
+    "success": {
+      "type": "boolean",
+      "description": "Whether to show success/validated styling",
+      "default": "false",
+      "required": false
+    },
+    "label": {
+      "type": "string",
+      "description": "Label text displayed above input",
+      "required": false
+    },
+    "required": {
+      "type": "boolean",
+      "description": "Whether the field is required (shows asterisk)",
+      "default": "false",
+      "required": false
+    },
+    "helperText": {
+      "type": "string",
+      "description": "Helper or error message below input",
+      "required": false
+    },
+    "startAdornment": {
+      "type": "node",
+      "description": "Content rendered before the input (icon or prefix text)",
+      "required": false
+    },
+    "endAdornment": {
+      "type": "node",
+      "description": "Content rendered after the input (icon or suffix text)",
+      "required": false
+    },
+    "shortcut": {
+      "type": "string",
+      "description": "Keyboard shortcut hint displayed inside the input",
+      "required": false
+    },
+    "shortcutBehavior": {
+      "type": "enum",
+      "description": "Whether shortcut hint is visual only or also registers a global focus hotkey",
+      "default": "display-only",
+      "required": false,
+      "values": [
+        "display-only",
+        "focus-input"
+      ]
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Called with new value on change",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "description": "Value-first change callback alias: (value: string) => void",
+      "required": false
+    },
+    "onBlur": {
+      "type": "function",
+      "description": "",
+      "required": false
+    },
+    "onFocus": {
+      "type": "function",
+      "description": "",
+      "required": false
+    },
+    "onKeyDown": {
+      "type": "function",
+      "description": "",
+      "required": false
+    },
+    "rootProps": {
+      "type": "object",
+      "description": "HTML attributes applied to the wrapper element",
+      "required": false
+    },
+    "inputStyle": {
+      "type": "object",
+      "description": "Inline styles applied directly to the input element",
+      "required": false
+    },
+    "inputClassName": {
+      "type": "string",
+      "description": "Class name applied directly to the input element",
+      "required": false
+    },
+    "withFieldWrapper": {
+      "type": "boolean",
+      "description": "Render built-in label/helper wrapper (set false for Field composition or bare input rendering)",
+      "default": "true",
+      "required": false
+    },
+    "className": {
+      "type": "string",
+      "description": "Wrapper class name",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "Wrapper styles",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Collecting single-line text data from users",
+      "Email, password, phone number, or URL input",
+      "Search fields",
+      "Short form fields (name, title, etc.)"
+    ],
+    "whenNot": [
+      "Multi-line text (use Textarea)",
+      "Selecting from predefined options (use Select)",
+      "Boolean input (use Checkbox or Switch)",
+      "Date/time input (use DatePicker)"
+    ],
+    "guidelines": [
+      "Always provide a label for accessibility",
+      "Use appropriate input type for data validation",
+      "Show validation errors with error prop and helperText",
+      "Use placeholder for format hints, not labels",
+      "Shortcut hints are display-only by default; set shortcutBehavior=\"focus-input\" to opt into global hotkey focusing"
+    ],
+    "accessibility": [
+      "Labels must be associated with inputs",
+      "Error messages should be announced to screen readers",
+      "Required fields should be indicated"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic text input",
+      "code": "<Input label=\"Name\" placeholder=\"Enter your name\" />"
+    },
+    {
+      "name": "With Value",
+      "description": "Input with pre-filled value",
+      "code": "<Input label=\"Email\" type=\"email\" value=\"user@example.com\" />"
+    },
+    {
+      "name": "With Helper",
+      "description": "Input with helper text",
+      "code": "<Input\n  label=\"Password\"\n  type=\"password\"\n  placeholder=\"Create a password\"\n  helperText=\"Must be at least 8 characters\"\n/>"
+    },
+    {
+      "name": "Error State",
+      "description": "Input showing validation error",
+      "code": "<Input\n  label=\"Email\"\n  type=\"email\"\n  value=\"invalid-email\"\n  error\n  helperText=\"Please enter a valid email address\"\n/>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Non-interactive input",
+      "code": "<Input label=\"Username\" value=\"readonly-user\" disabled />"
+    },
+    {
+      "name": "Required",
+      "description": "Required field with asterisk indicator",
+      "code": "<Input\n  label=\"Email\"\n  type=\"email\"\n  placeholder=\"user@example.com\"\n  required\n/>"
+    },
+    {
+      "name": "Sizes",
+      "description": "Available size variants",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '12px', maxWidth: '300px' }}>\n  <Input label=\"Small\" size=\"sm\" placeholder=\"Small input\" />\n  <Input label=\"Medium\" size=\"md\" placeholder=\"Medium input\" />\n  <Input label=\"Large\" size=\"lg\" placeholder=\"Large input\" />\n</div>"
+    },
+    {
+      "name": "Bare Input (Field Composition)",
+      "description": "Disable the built-in wrapper for custom Field composition",
+      "code": "<Input\n  withFieldWrapper={false}\n  aria-label=\"Search\"\n  placeholder=\"Search...\"\n  rootProps={{ 'data-demo': 'bare-input-wrapper' }}\n/>"
+    },
+    {
+      "name": "Shortcut Focus Hotkey",
+      "description": "Display shortcut hint and opt into focus behavior",
+      "code": "<Input\n  label=\"Command Palette\"\n  placeholder=\"Search commands\"\n  shortcut=\"⌘K\"\n  shortcutBehavior=\"focus-input\"\n/>"
+    },
+    {
+      "name": "Success State",
+      "description": "Input showing validated/success styling",
+      "code": "<Input\n  label=\"Email\"\n  type=\"email\"\n  value=\"user@example.com\"\n  success\n  helperText=\"Email verified\"\n/>"
+    },
+    {
+      "name": "With Start Adornment",
+      "description": "Input with icon or prefix before the text",
+      "code": "<Input\n  label=\"Price\"\n  placeholder=\"0.00\"\n  startAdornment={<span>$</span>}\n/>"
+    },
+    {
+      "name": "With End Adornment",
+      "description": "Input with icon or suffix after the text",
+      "code": "<Input\n  label=\"Weight\"\n  placeholder=\"0\"\n  endAdornment={<span>kg</span>}\n/>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Textarea",
+      "relationship": "alternative",
+      "note": "Use Textarea for multi-line text input"
+    },
+    {
+      "component": "Select",
+      "relationship": "alternative",
+      "note": "Use Select when choosing from predefined options"
+    },
+    {
+      "component": "Field",
+      "relationship": "parent",
+      "note": "Use Field for advanced form composition and custom controls"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "type: text|email|password|number|tel|url (default: text)",
+      "value: string - controlled input value",
+      "label: string - accessible label text",
+      "placeholder: string - format hint only",
+      "disabled: boolean - disables interaction",
+      "required: boolean - required field indicator",
+      "error: boolean - shows error styling",
+      "success: boolean - shows success/validated styling",
+      "startAdornment: ReactNode - content before the input (icon or prefix)",
+      "endAdornment: ReactNode - content after the input (icon or suffix)",
+      "helperText: string - helper/error message",
+      "onValueChange: (value: string) => void - value-first change callback alias",
+      "rootProps: HTMLAttributes<HTMLDivElement> - wrapper element props",
+      "withFieldWrapper: boolean - toggle built-in wrapper/label rendering (default: true)",
+      "shortcutBehavior: display-only|focus-input (default: display-only)",
+      "...native input attributes are supported (autoComplete, required, inputMode, pattern, etc.)"
+    ],
+    "a11yRules": [
+      "A11Y_INPUT_LABEL",
+      "A11Y_INPUT_ERROR",
+      "A11Y_INPUT_REQUIRED"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:59.208Z"
+  }
+}

package/src/components/Input/Input.module.scss

@@ -88,8 +88,11 @@
   align-items: center;
 
   // Auto-detect shortcut kbd via :has() — replaces JS class toggle: `shortcut && styles.hasShortcut`
+  // Optical alignment: nudge left padding slightly to center the placeholder
+  // in the visible area between the left edge and the kbd badge.
   &:has(> .shortcut) .input {
     padding-right: var(--fui-space-12, 3rem);
+    padding-left: var(--fui-space-3, $fui-space-3);
   }
 }
 
@@ -101,6 +104,16 @@
   padding: 0 var(--fui-space-3, $fui-space-3);
   border-radius: var(--fui-radius-md, $fui-radius-md);
 
+  // Optical alignment: icons have built-in whitespace, so reduce padding
+  // on the side with an adornment to keep the content optically centered.
+  &:has(> .adornment:first-child) {
+    padding-left: var(--fui-space-2, $fui-space-2);
+  }
+
+  &:has(> .adornment:last-of-type:not(:first-child)) {
+    padding-right: var(--fui-space-2, $fui-space-2);
+  }
+
   &:focus-within {
     @include field-shell-focus;
   }
@@ -165,8 +178,8 @@
   align-items: center;
   justify-content: center;
   gap: calc(var(--fui-space-px, $fui-space-px) * 2);
-  min-width: 1.25rem;
-  height: 1.25rem;
+  min-width: 24px;
+  height: 24px;
   padding: 0 var(--fui-space-1, $fui-space-1);
   font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
   font-family: var(--fui-font-sans, $fui-font-sans);
@@ -175,11 +188,8 @@
   letter-spacing: 0.02em;
   color: var(--fui-text-tertiary, $fui-text-tertiary);
   background: var(--fui-bg-elevated, $fui-bg-elevated);
-  border: 1px solid var(--fui-border-default, $fui-border-default);
-  border-bottom-width: 2px;
+  border: 1px solid var(--fui-field-border, $fui-border);
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
-  box-shadow:
-    inset 0 0.5px 0 color-mix(in srgb, white 6%, transparent);
   pointer-events: none;
   white-space: nowrap;
   user-select: none;