@usefragments/ui 1.0.0

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

@@ -0,0 +1,325 @@
+{
+  "$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 as a visual kbd token 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",
+      "Use the shortcut prop for embedded keyboard hints instead of custom kbd markup around inputs",
+      "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": "Search With Shortcut",
+      "description": "Search input with a leading icon and embedded kbd hint",
+      "code": "<Input\n  aria-label=\"Search findings\"\n  placeholder=\"Search findings...\"\n  shortcut=\"⌘K\"\n  shortcutBehavior=\"focus-input\"\n  startAdornment={<MagnifyingGlass aria-hidden=\"true\" />}\n  withFieldWrapper={false}\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)",
+      "shortcut: string - visual kbd hint inside the input; do not hand-roll extra kbd markup",
+      "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

@@ -0,0 +1,231 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// Form field wrapper (label + helper + error)
+@include form-field-wrapper;
+
+.input {
+  @include text-base;
+  @include interactive-base;
+  @include field-shell;
+
+  display: block;
+  width: 100%;
+
+  &::placeholder {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+
+  &:focus-visible {
+    @include field-shell-focus;
+  }
+}
+
+// Size variants — shared control-size path (matches Select/DatePicker)
+.sm {
+  @include control-size("sm", "input");
+}
+
+.md {
+  @include control-size("md", "input");
+}
+
+.lg {
+  @include control-size("lg", "input");
+}
+
+.labelSm {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+// Error state via :has() — detects aria-invalid on the input element.
+// Replaces JS class toggle: `error && styles.error`
+// The .error class is kept as a fallback for direct usage.
+.error,
+.input[aria-invalid] {
+  border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+
+  &:focus-visible {
+    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+    @include focus-ring-error;
+  }
+}
+
+// Success state — green border for validated fields (DoorDash/Stocksy pattern)
+.success {
+  border-color: var(--fui-color-success-text, $fui-color-success-text);
+
+  &:focus-visible {
+    border-color: var(--fui-color-success-text, $fui-color-success-text);
+    @include focus-ring-success;
+  }
+}
+
+// Auto-detect error state via :has() — applies error color to helper when sibling has aria-invalid
+.wrapper:has([aria-invalid]) .helper {
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+// Auto-detect success state via :has() — applies success color to helper
+.wrapper[data-success] .helper,
+.helperSuccess {
+  color: var(--fui-color-success-text, $fui-color-success-text);
+}
+
+// ============================================
+// Input with adornments or shortcut indicator
+// ============================================
+
+.inputContainer {
+  position: relative;
+  display: flex;
+  align-items: center;
+
+  // Auto-detect shortcut kbd via :has() — replaces JS class toggle: `shortcut && styles.hasShortcut`
+  &:has(> .shortcut):not(.hasAdornment) .input {
+    padding-right: var(--fui-kbd-reserved-width, 2.714rem);
+    padding-left: var(--fui-space-2, $fui-space-2);
+  }
+}
+
+// Adornment container — wraps input with start/end adornments inside field-shell border
+.hasAdornment {
+  @include field-shell;
+
+  height: var(--fui-input-height, $fui-input-height);
+  min-height: var(--fui-target-size-min, $fui-target-size-min);
+  gap: var(--fui-space-2, $fui-space-2);
+  padding: 0 var(--fui-space-2, $fui-space-2);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+
+  &:has(.sm) {
+    height: var(--fui-input-height-sm, $fui-input-height-sm);
+  }
+
+  &:has(.lg) {
+    height: var(--fui-input-height-lg, $fui-input-height-lg);
+  }
+
+  &:has(> .shortcut) {
+    padding-right: calc(
+      var(--fui-space-2, #{$fui-space-2}) + var(--fui-kbd-reserved-width, 2.714rem)
+    );
+  }
+
+  &:focus-within {
+    @include field-shell-focus;
+  }
+
+  // Strip the input's own shell when inside adornment container
+  .input {
+    min-height: 0;
+    height: 100%;
+    border: none;
+    background: transparent;
+    padding: 0;
+    box-shadow: none;
+
+    &:focus-visible {
+      outline: none;
+      box-shadow: none;
+    }
+  }
+
+  // Error state on adornment container
+  &:has(.error) {
+    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+
+    &:focus-within {
+      border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+      @include focus-ring-error;
+    }
+  }
+
+  // Success state on adornment container
+  &:has(.success) {
+    border-color: var(--fui-color-success-text, $fui-color-success-text);
+
+    &:focus-within {
+      border-color: var(--fui-color-success-text, $fui-color-success-text);
+      @include focus-ring-success;
+    }
+  }
+}
+
+.adornment {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+
+  svg {
+    width: var(--fui-icon-sm, $fui-icon-sm);
+    height: var(--fui-icon-sm, $fui-icon-sm);
+  }
+}
+
+// Kept as fallback for direct usage
+.hasShortcut {
+  padding-right: var(--fui-kbd-reserved-width, 2.714rem);
+}
+
+.shortcut {
+  position: absolute;
+  right: var(--fui-space-1, $fui-space-1);
+  top: 50%;
+  transform: translateY(-50%);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--fui-kbd-gap, calc(var(--fui-space-px, #{$fui-space-px}) * 2));
+  min-width: var(--fui-kbd-min-width, 1.714rem);
+  height: var(--fui-kbd-height, 1.286rem);
+  padding: 0 var(--fui-kbd-padding-x, $fui-space-0-75);
+  font-family: var(--fui-font-mono, $fui-font-mono);
+  font-size: var(--fui-kbd-font-size, $fui-font-size-2xs);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  line-height: 1;
+  font-variant-numeric: tabular-nums;
+  color: var(--fui-kbd-color, var(--fui-text-tertiary, #{$fui-text-tertiary}));
+  background: var(--fui-kbd-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
+  border: 1px solid var(--fui-kbd-border, var(--fui-border, #{$fui-border}));
+  border-radius: var(--fui-kbd-radius, var(--fui-radius-sm, #{$fui-radius-sm}));
+  box-shadow: var(--fui-kbd-shadow, none);
+  pointer-events: none;
+  white-space: nowrap;
+  user-select: none;
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .input {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+
+    &:focus-visible {
+      border-color: var(--fui-color-accent, $fui-color-accent);
+    }
+  }
+
+  .error,
+  .input[aria-invalid] {
+    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+  }
+
+  .success {
+    border-color: var(--fui-color-success-text, $fui-color-success-text);
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .input {
+    transition: none;
+  }
+}

package/src/components/Input/Input.stories.tsx

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { MagnifyingGlass } from "@phosphor-icons/react";
+import { Input } from ".";
+
+/**
+ * Single-line text input with built-in label, helper text, and validation states.
+ * Supports controlled/uncontrolled values, adornments, and a keyboard shortcut hint.
+ */
+const meta = {
+  title: "Forms/Input",
+  component: Input,
+  tags: ["autodocs", "canonical"],
+  parameters: {
+    docs: {
+      description: {
+        component: "Text input field for single-line user data entry.",
+      },
+    },
+  },
+  argTypes: {
+    type: {
+      control: "select",
+      options: ["number", "text", "email", "password", "tel", "url"],
+      description: "HTML input type for validation and keyboard",
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+      description: "Size variant",
+    },
+    shortcutBehavior: {
+      control: "select",
+      options: ["display-only", "focus-input"],
+      description: "Whether the shortcut hint is visual only or registers a hotkey",
+    },
+    disabled: { control: "boolean" },
+    error: { control: "boolean" },
+    success: { control: "boolean" },
+    required: { control: "boolean" },
+    withFieldWrapper: { control: "boolean" },
+  },
+  args: {
+    label: "Name",
+    placeholder: "Enter your name",
+    type: "text",
+    size: "md",
+  },
+} satisfies Meta<typeof Input>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { label: "Name", placeholder: "Enter your name" },
+};
+
+export const Email: Story = {
+  args: { label: "Email", type: "email", placeholder: "user@example.com" },
+};
+
+export const WithHelper: Story = {
+  args: {
+    label: "Password",
+    type: "password",
+    placeholder: "Create a password",
+    helperText: "Must be at least 8 characters",
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    label: "Email",
+    type: "email",
+    value: "invalid-email",
+    error: true,
+    helperText: "Please enter a valid email address",
+  },
+};
+
+export const Disabled: Story = {
+  args: { label: "Username", value: "readonly-user", disabled: true },
+};
+
+export const Required: Story = {
+  args: {
+    label: "Email",
+    type: "email",
+    placeholder: "user@example.com",
+    required: true,
+  },
+};
+
+export const SearchWithShortcut: Story = {
+  args: {
+    "aria-label": "Search findings",
+    placeholder: "Search findings...",
+    shortcut: "⌘K",
+    shortcutBehavior: "focus-input",
+    startAdornment: <MagnifyingGlass aria-hidden="true" />,
+    withFieldWrapper: false,
+    rootProps: { style: { maxWidth: 420 } },
+  },
+};