@usefragments/ui 1.0.0

package/src/components/Input/index.tsx

@@ -0,0 +1,301 @@
+"use client";
+
+import * as React from "react";
+import { Field } from "@base-ui/react/field";
+import { useResolvedControlSize } from "../ComponentDefaults";
+import { mergeAriaIds } from "../../utils/aria";
+import styles from "./Input.module.scss";
+
+/**
+ * Text input field with label, helper text, and validation.
+ * @see https://usefragments.com/components/input
+ */
+export interface InputProps extends Omit<
+  React.InputHTMLAttributes<HTMLInputElement>,
+  "size" | "onChange" | "onBlur" | "onFocus" | "onKeyDown" | "className" | "style"
+> {
+  /** Controlled input value */
+  value?: string;
+  /** Default value for uncontrolled usage */
+  defaultValue?: string;
+  /** Placeholder text shown when empty */
+  placeholder?: string;
+  /** HTML input type */
+  type?: "text" | "email" | "password" | "number" | "tel" | "url";
+  /** Input size.
+   * @default "md"
+   * @see https://usefragments.com/components/input#sizes */
+  size?: "sm" | "md" | "lg";
+  /** Whether the input is non-interactive */
+  disabled?: boolean;
+  /** Show error styling */
+  error?: boolean;
+  /** Show success styling */
+  success?: boolean;
+  /** Visible label text */
+  label?: string;
+  /** Whether the field is required */
+  required?: boolean;
+  /** Helper text shown below the input */
+  helperText?: string;
+  /** Content rendered before the input (e.g., icon or prefix text) */
+  startAdornment?: React.ReactNode;
+  /** Content rendered after the input (e.g., icon or suffix text) */
+  endAdornment?: React.ReactNode;
+  /** Keyboard shortcut hint displayed inside the input (e.g., "⌘K"). */
+  shortcut?: string;
+  /** Whether the shortcut should also register a global focus hotkey.
+   * @default "display-only" */
+  shortcutBehavior?: "display-only" | "focus-input";
+  /** Called when value changes (string value) */
+  onChange?: (value: string) => void;
+  /** Alias for onChange (value-first callback) */
+  onValueChange?: (value: string) => void;
+  onBlur?: React.FocusEventHandler<HTMLInputElement>;
+  onFocus?: React.FocusEventHandler<HTMLInputElement>;
+  onKeyDown?: (e: React.KeyboardEvent<HTMLInputElement>) => void;
+  /** Props applied to the wrapper element */
+  rootProps?: React.HTMLAttributes<HTMLDivElement>;
+  /** Styles applied directly to the input element */
+  inputStyle?: React.CSSProperties;
+  /** Class applied directly to the input element */
+  inputClassName?: string;
+  /** Whether to render the Base UI Field wrapper (label/description/invalid wiring)
+   * @default true */
+  withFieldWrapper?: boolean;
+  /** Wrapper class name */
+  className?: string;
+  /** Wrapper styles */
+  style?: React.CSSProperties;
+}
+
+function parseShortcut(
+  shortcut: string
+): { meta: boolean; shift: boolean; alt: boolean; key: string } | null {
+  let meta = false,
+    shift = false,
+    alt = false;
+  let remaining = shortcut;
+
+  if (remaining.includes("⌘")) {
+    meta = true;
+    remaining = remaining.replace("⌘", "");
+  }
+  if (remaining.includes("⇧")) {
+    shift = true;
+    remaining = remaining.replace("⇧", "");
+  }
+  if (remaining.includes("⌥")) {
+    alt = true;
+    remaining = remaining.replace("⌥", "");
+  }
+
+  remaining = remaining.trim();
+  if (!remaining) return null;
+
+  return { meta, shift, alt, key: remaining };
+}
+
+const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(function Input(
+  {
+    value,
+    defaultValue,
+    placeholder,
+    type = "text",
+    size: sizeProp,
+    disabled = false,
+    error = false,
+    success = false,
+    required = false,
+    label,
+    helperText,
+    startAdornment,
+    endAdornment,
+    shortcut,
+    shortcutBehavior = "display-only",
+    onChange,
+    onValueChange,
+    onBlur,
+    onFocus,
+    onKeyDown,
+    rootProps,
+    className,
+    style,
+    inputStyle,
+    inputClassName,
+    withFieldWrapper = true,
+    ...inputProps
+  },
+  ref
+) {
+  const size = useResolvedControlSize(sizeProp);
+  const generatedId = React.useId();
+  const helperId = helperText ? `input-helper-${generatedId}` : undefined;
+  const {
+    id,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledBy,
+    "aria-describedby": ariaDescribedBy,
+    ...nativeInputProps
+  } = inputProps;
+  const resolvedInputId = id ?? `input-${generatedId}`;
+
+  const internalRef = React.useRef<HTMLInputElement>(null);
+  const mergedRef = React.useCallback(
+    (node: HTMLInputElement | null) => {
+      internalRef.current = node;
+      if (typeof ref === "function") {
+        ref(node);
+      } else if (ref) {
+        (ref as React.MutableRefObject<HTMLInputElement | null>).current = node;
+      }
+    },
+    [ref]
+  );
+
+  // Register global keydown handler when shortcut is provided
+  React.useEffect(() => {
+    if (!shortcut) return;
+    if (shortcutBehavior !== "focus-input") return;
+    const parsed = parseShortcut(shortcut);
+    if (!parsed) return;
+
+    const handler = (e: KeyboardEvent) => {
+      if (parsed.meta && !(e.metaKey || e.ctrlKey)) return;
+      if (parsed.shift && !e.shiftKey) return;
+      if (parsed.alt && !e.altKey) return;
+      if (e.key.toLowerCase() !== parsed.key.toLowerCase()) return;
+      e.preventDefault();
+      internalRef.current?.focus();
+    };
+    document.addEventListener("keydown", handler);
+    return () => document.removeEventListener("keydown", handler);
+  }, [shortcut, shortcutBehavior]);
+
+  const hasAdornment = !!(startAdornment || endAdornment);
+
+  const inputClasses = [
+    styles.input,
+    styles[size],
+    error && styles.error,
+    success && styles.success,
+    shortcut && styles.hasShortcut,
+    inputClassName,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const helperClasses = [
+    styles.helper,
+    error && styles.helperError,
+    success && styles.helperSuccess,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const wrapperClasses = [styles.wrapper, className].filter(Boolean).join(" ");
+  const labelClasses = [styles.label, size === "sm" && styles.labelSm].filter(Boolean).join(" ");
+
+  const sharedInputProps = {
+    ...nativeInputProps,
+    ref: mergedRef,
+    id: resolvedInputId,
+    type,
+    value,
+    defaultValue,
+    placeholder,
+    disabled,
+    required,
+    onChange: (e: React.ChangeEvent<HTMLInputElement>) => {
+      onChange?.(e.target.value);
+      onValueChange?.(e.target.value);
+    },
+    onBlur: (e: React.FocusEvent<HTMLInputElement>) => onBlur?.(e),
+    onFocus: (e: React.FocusEvent<HTMLInputElement>) => onFocus?.(e),
+    onKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => onKeyDown?.(e),
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledBy,
+    "aria-describedby": mergeAriaIds(ariaDescribedBy, helperId),
+    className: inputClasses,
+    style: inputStyle,
+  } satisfies React.InputHTMLAttributes<HTMLInputElement> & {
+    ref: React.Ref<HTMLInputElement>;
+  };
+
+  const inputElement = <Field.Control {...sharedInputProps} render={<input />} />;
+
+  const fieldlessInputElement = <input {...sharedInputProps} aria-invalid={error || undefined} />;
+
+  const rawInput = withFieldWrapper ? inputElement : fieldlessInputElement;
+
+  const content =
+    hasAdornment || shortcut ? (
+      <div
+        className={[styles.inputContainer, hasAdornment && styles.hasAdornment]
+          .filter(Boolean)
+          .join(" ")}
+      >
+        {startAdornment && <span className={styles.adornment}>{startAdornment}</span>}
+        {rawInput}
+        {endAdornment && <span className={styles.adornment}>{endAdornment}</span>}
+        {shortcut && (
+          <kbd className={styles.shortcut} aria-hidden="true">
+            {shortcut}
+          </kbd>
+        )}
+      </div>
+    ) : (
+      rawInput
+    );
+
+  if (!withFieldWrapper) {
+    return (
+      <div
+        {...rootProps}
+        className={[styles.wrapper, rootProps?.className, className].filter(Boolean).join(" ")}
+        style={{ ...(rootProps?.style ?? {}), ...(style ?? {}) }}
+      >
+        {label && (
+          <label htmlFor={resolvedInputId} className={labelClasses}>
+            {label}
+            {required && <span className={styles.required}>*</span>}
+          </label>
+        )}
+        {content}
+        {helperText && (
+          <div id={helperId} className={helperClasses}>
+            {helperText}
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <Field.Root
+      {...rootProps}
+      disabled={disabled}
+      invalid={error}
+      data-success={success || undefined}
+      className={[wrapperClasses, rootProps?.className].filter(Boolean).join(" ")}
+      style={{ ...(rootProps?.style ?? {}), ...(style ?? {}) }}
+    >
+      {label && (
+        <Field.Label className={labelClasses}>
+          {label}
+          {required && <span className={styles.required}>*</span>}
+        </Field.Label>
+      )}
+      {content}
+      {helperText && (
+        <Field.Description id={helperId} className={helperClasses}>
+          {helperText}
+        </Field.Description>
+      )}
+    </Field.Root>
+  );
+});
+
+export const Input = Object.assign(InputRoot, {
+  Root: InputRoot,
+});

package/src/components/Link/Link.contract.json

@@ -0,0 +1,180 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Link",
+  "description": "Styled anchor element for navigation. Supports internal and external links with consistent visual treatment.",
+  "category": "navigation",
+  "tags": [
+    "link",
+    "anchor",
+    "navigation",
+    "href",
+    "url"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Link/index.tsx",
+  "exportName": "Link",
+  "propsSummary": [
+    "children: node (required)",
+    "variant: default|subtle|muted (default: default)",
+    "underline: always|hover|none (default: hover)",
+    "external: boolean (default: false)",
+    "asChild: boolean (default: false)",
+    "className: string",
+    "style: object",
+    "target: union",
+    "rel: string"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Link text content",
+      "required": true
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual style variant",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "subtle",
+        "muted"
+      ]
+    },
+    "underline": {
+      "type": "enum",
+      "description": "Underline behavior",
+      "default": "hover",
+      "required": false,
+      "values": [
+        "always",
+        "hover",
+        "none"
+      ]
+    },
+    "external": {
+      "type": "boolean",
+      "description": "Opens in new tab with noopener noreferrer",
+      "default": "false",
+      "required": false
+    },
+    "asChild": {
+      "type": "boolean",
+      "description": "Render as child element (polymorphic). Merges link props/classes and composes event handlers onto the single child (e.g. Next.js Link).",
+      "default": "false",
+      "required": false
+    },
+    "className": {
+      "type": "string",
+      "description": "Additional class name",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "Inline styles",
+      "required": false
+    },
+    "target": {
+      "type": "union",
+      "description": "",
+      "required": false
+    },
+    "rel": {
+      "type": "string",
+      "description": "",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Inline text links within paragraphs",
+      "Navigation links in footers or sidebars",
+      "\"Forgot password?\" or \"Sign up\" links in forms",
+      "External links to documentation or resources"
+    ],
+    "whenNot": [
+      "Primary call-to-action (use Button instead)",
+      "Navigation tabs (use Tabs component)",
+      "Menu items in dropdowns (use Menu component)",
+      "Cards that link to detail pages should still use real link semantics (Link or anchor inside Card)"
+    ],
+    "guidelines": [
+      "Link text should describe the destination, not \"click here\"",
+      "Use external prop for links that open in new tabs",
+      "Use subtle variant for secondary/contextual links",
+      "Ensure links are distinguishable from regular text",
+      "When using asChild, Link composes event handlers with the child instead of overwriting them"
+    ],
+    "accessibility": [
+      "Link text must be descriptive of the destination",
+      "External links should indicate they open in new window",
+      "Links must have visible focus indicators",
+      "Avoid using links that look like buttons without button semantics"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Standard link with hover underline",
+      "code": "<Link href=\"#\">Learn more about our services</Link>"
+    },
+    {
+      "name": "Variants",
+      "description": "Visual style options",
+      "code": "<div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>\n  <Link href=\"#\" variant=\"default\">Default</Link>\n  <Link href=\"#\" variant=\"subtle\">Subtle</Link>\n  <Link href=\"#\" variant=\"muted\">Muted</Link>\n</div>"
+    },
+    {
+      "name": "Underline Styles",
+      "description": "Different underline behaviors",
+      "code": "<div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>\n  <Link href=\"#\" underline=\"always\">Always underlined</Link>\n  <Link href=\"#\" underline=\"hover\">Underline on hover</Link>\n  <Link href=\"#\" underline=\"none\">No underline</Link>\n</div>"
+    },
+    {
+      "name": "External Link",
+      "description": "Link that opens in new tab",
+      "code": "<Link href=\"https://example.com\" external>\n  View documentation ↗\n</Link>"
+    },
+    {
+      "name": "As Child (Polymorphic)",
+      "description": "Renders as a custom element while applying Link styles and composing handlers. Useful with Next.js Link for client-side navigation.",
+      "code": "<Link asChild variant=\"subtle\" onClick={() => {}}>\n  <button type=\"button\" onClick={() => alert('Navigated!')}>\n    Polymorphic link as button\n  </button>\n</Link>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Button",
+      "relationship": "alternative",
+      "note": "Use Button for primary actions, Link for navigation"
+    },
+    {
+      "component": "Text",
+      "relationship": "parent",
+      "note": "Links often appear within Text components"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - link text (required)",
+      "href: string - destination URL",
+      "variant: default|subtle|muted - visual style",
+      "underline: always|hover|none - underline behavior",
+      "external: boolean - opens in new tab",
+      "asChild: boolean - polymorphic child rendering with merged styles and composed event handlers"
+    ],
+    "a11yRules": [
+      "A11Y_LINK_TEXT",
+      "A11Y_LINK_FOCUS"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:59.546Z"
+  }
+}

package/src/components/Link/Link.module.scss

@@ -0,0 +1,67 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.link {
+  @include interactive-base;
+
+  display: inline;
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: inherit;
+  line-height: inherit;
+  text-decoration: none;
+  cursor: pointer;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+// Variants
+.default {
+  color: var(--fui-color-accent, $fui-color-accent);
+
+  &:hover {
+    color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+}
+
+.subtle {
+  color: var(--fui-text-primary, $fui-text-primary);
+
+  &:hover {
+    color: var(--fui-color-accent, $fui-color-accent);
+  }
+}
+
+.muted {
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+
+  &:hover {
+    color: var(--fui-text-secondary, $fui-text-secondary);
+  }
+}
+
+// Underline styles
+.underline-always {
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.underline-hover {
+  text-decoration: none;
+
+  &:hover {
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+}
+
+.underline-none {
+  text-decoration: none;
+
+  &:hover {
+    text-decoration: none;
+  }
+}

package/src/components/Link/Link.stories.tsx

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Link } from '.';
+
+/**
+ * Styled anchor element for navigation. Supports internal and external links
+ * with consistent visual treatment, variants, and underline behaviors.
+ */
+const meta = {
+  title: 'Navigation/Link',
+  component: Link,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Styled anchor element for internal and external navigation.',
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'subtle', 'muted'],
+      description: 'Visual style variant',
+    },
+    underline: {
+      control: 'select',
+      options: ['always', 'hover', 'none'],
+      description: 'Underline behavior',
+    },
+    external: { control: 'boolean' },
+    asChild: { control: 'boolean' },
+  },
+  args: {
+    href: '#',
+    variant: 'default',
+    underline: 'hover',
+    children: 'Learn more about our services',
+  },
+} satisfies Meta<typeof Link>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { href: '#', children: 'Learn more about our services' },
+};
+
+export const Subtle: Story = {
+  args: { href: '#', variant: 'subtle', children: 'Secondary link' },
+};
+
+export const Muted: Story = {
+  args: { href: '#', variant: 'muted', children: 'Muted link' },
+};
+
+export const AlwaysUnderlined: Story = {
+  args: { href: '#', underline: 'always', children: 'Always underlined' },
+};
+
+export const External: Story = {
+  args: {
+    href: 'https://example.com',
+    external: true,
+    children: 'View documentation',
+  },
+};