@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/ImageCrop/extractCropBlob.ts

@@ -0,0 +1,140 @@
+/**
+ * Output MIME type and encoding options for `extractCropBlob`.
+ */
+export interface ExtractCropOptions {
+  /**
+   * Output MIME type. Default `'image/png'` (lossless).
+   * - `'image/png'` — lossless, larger file size, supports transparency.
+   * - `'image/jpeg'` — smaller, lossy, no transparency. Use for photos.
+   * - `'image/webp'` — smaller than JPEG at similar quality, good browser support since 2020.
+   */
+  type?: 'image/png' | 'image/jpeg' | 'image/webp';
+  /**
+   * Encoding quality for lossy formats (0..1). Default `0.92`. Ignored for
+   * PNG. Lower values = smaller file + more artifacts.
+   */
+  quality?: number;
+  /**
+   * Resize the output to this width in pixels (height proportional). Omit
+   * to keep the source-pixel crop dimensions (no resize). Useful for capping
+   * avatar uploads (e.g. `outputWidth: 512` for a 512×512 max). The height
+   * is computed from the source crop aspect ratio.
+   */
+  outputWidth?: number;
+}
+
+/**
+ * Crop region in SOURCE-IMAGE pixel coordinates (not viewport pixels). Re-
+ * exported from `./ImageCrop` to keep `extractCropBlob`'s signature self-
+ * contained (consumers can import this utility without importing the
+ * component).
+ */
+export interface CropArea {
+  /** Top-left X in source-image pixels. */
+  x: number;
+  /** Top-left Y in source-image pixels. */
+  y: number;
+  /** Crop width in source-image pixels. */
+  width: number;
+  /** Crop height in source-image pixels. */
+  height: number;
+}
+
+/**
+ * Internal helper — load an image source (string URL, File, or Blob) into
+ * an HTMLImageElement and resolve when it's ready for canvas operations.
+ *
+ * Object URLs created from File/Blob are revoked after load to avoid leaks.
+ */
+function loadImage(src: string | File | Blob): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    let createdObjectUrl = false;
+    const url =
+      typeof src === 'string' ? src : ((createdObjectUrl = true), URL.createObjectURL(src));
+    const img = new Image();
+    // crossOrigin: 'anonymous' lets us read pixels from cross-origin images
+    // IF the server returns the right CORS headers. Same-origin / data: /
+    // blob: URLs are unaffected. Without this, drawImage on cross-origin
+    // sources taints the canvas and toBlob() throws SecurityError.
+    img.crossOrigin = 'anonymous';
+    img.onload = () => {
+      if (createdObjectUrl) URL.revokeObjectURL(url);
+      resolve(img);
+    };
+    img.onerror = () => {
+      if (createdObjectUrl) URL.revokeObjectURL(url);
+      reject(new Error('Failed to load image for cropping'));
+    };
+    img.src = url;
+  });
+}
+
+/**
+ * Extract the cropped region of an image as a Blob via an off-screen canvas.
+ *
+ * Accepts the same `src` shape as `<ImageCrop>` (string URL, File, or Blob)
+ * and a `CropArea` in source-image pixel coordinates. Returns a Promise
+ * resolving to a Blob with the configured type/quality/resize.
+ *
+ * The canonical "Save handler" recipe — the consumer's submit code calls
+ * this to produce the cropped Blob, then uploads to their backend / S3 /
+ * etc.
+ *
+ * @example
+ * const handleSave = async () => {
+ *   if (!crop) return;
+ *   const blob = await extractCropBlob(file, crop, {
+ *     type: 'image/jpeg',
+ *     quality: 0.9,
+ *     outputWidth: 512,
+ *   });
+ *   await uploadToS3(blob);
+ * };
+ *
+ * @remarks Cross-origin sources require the server to send
+ *   `Access-Control-Allow-Origin` headers. Without them, the browser taints
+ *   the canvas and `toBlob` rejects with a SecurityError. Same-origin URLs,
+ *   `data:` URLs, `blob:` URLs (from File/Blob), and properly CORS-enabled
+ *   third-party images are all safe.
+ *
+ * @throws Error if the image fails to load OR the canvas's `toBlob` returns
+ *   `null` (typically a CORS tainting failure — see `@remarks`).
+ */
+export async function extractCropBlob(
+  src: string | File | Blob,
+  area: CropArea,
+  options: ExtractCropOptions = {},
+): Promise<Blob> {
+  const { type = 'image/png', quality = 0.92, outputWidth } = options;
+  const img = await loadImage(src);
+
+  // Determine output dimensions. If outputWidth is set, scale proportionally;
+  // otherwise keep source-pixel crop dimensions.
+  const outW = outputWidth ?? area.width;
+  const outH = outputWidth ? outputWidth * (area.height / area.width) : area.height;
+
+  const canvas = document.createElement('canvas');
+  canvas.width = outW;
+  canvas.height = outH;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    throw new Error('Failed to get 2D canvas context');
+  }
+  // drawImage(src, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight) — the
+  // 9-arg form crops + scales in one call.
+  ctx.drawImage(img, area.x, area.y, area.width, area.height, 0, 0, outW, outH);
+
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => {
+        if (blob) {
+          resolve(blob);
+        } else {
+          reject(new Error('Canvas toBlob returned null'));
+        }
+      },
+      type,
+      quality,
+    );
+  });
+}

package/src/components/ImageCrop/index.ts

@@ -0,0 +1,11 @@
+export { ImageCrop } from './ImageCrop';
+export type {
+  ImageCropProps,
+  ImageCropAspectOption,
+  ImageCropAspectRatio,
+  CropArea,
+} from './ImageCrop';
+export { extractCropBlob } from './extractCropBlob';
+export type { ExtractCropOptions } from './extractCropBlob';
+export { useCropPreview } from './useCropPreview';
+export type { UseCropPreviewOptions, UseCropPreviewResult } from './useCropPreview';

package/src/components/ImageCrop/useCropPreview.ts

@@ -0,0 +1,161 @@
+import { useEffect, useRef, useState } from 'react';
+import { extractCropBlob, type CropArea, type ExtractCropOptions } from './extractCropBlob';
+
+/**
+ * Options for `useCropPreview`. All optional; sensible defaults match the
+ * canonical "avatar picker" recipe (JPEG, q=0.9, 256-wide preview).
+ */
+export interface UseCropPreviewOptions extends ExtractCropOptions {
+  /**
+   * Milliseconds to wait after the latest crop change before encoding.
+   * Default `120`. Set higher for very large source images (4K phone
+   * photos can spend ~100ms inside `drawImage` + `toBlob`); set to `0` to
+   * encode synchronously on every change (useful in tests).
+   */
+  debounceMs?: number;
+}
+
+/**
+ * Result of `useCropPreview`. `encoding` is `true` between a crop change
+ * and the matching preview's arrival; consumers can fade the `<img>` or
+ * overlay a spinner during that window.
+ */
+export interface UseCropPreviewResult {
+  /**
+   * Object URL of the latest preview Blob. `null` until the first encode
+   * completes (or when `src`/`crop` is null). The URL is owned by the
+   * hook — it auto-revokes the previous URL whenever a new one is set
+   * AND on unmount. Do NOT call `URL.revokeObjectURL` on it yourself.
+   */
+  previewUrl: string | null;
+  /**
+   * The latest encoded Blob itself. Same content as the URL; useful when
+   * the Save handler needs to POST the cropped result — no need to call
+   * `extractCropBlob` a second time, just `formData.append('file', previewBlob, 'cropped.jpg')`.
+   * `null` before the first encode completes.
+   */
+  previewBlob: Blob | null;
+  /** Latest preview's encoded byte size, or `null` before the first encode. */
+  previewSize: number | null;
+  /**
+   * `true` from the moment `crop` (or any option) changes until the new
+   * preview lands. Use to drive a loading affordance (CircularProgress,
+   * opacity fade, "Re-encoding…" label).
+   */
+  encoding: boolean;
+}
+
+/**
+ * Live-encoded preview of a cropped image. Produces a Blob via
+ * `extractCropBlob` on every `crop` change (debounced), exposes the
+ * resulting object URL, byte size, and an `encoding` flag for loading UI.
+ *
+ * Designed for the canonical CRM "avatar / cover photo" pick → crop → save
+ * flow: the user sees the cropped result update live as they drag/zoom,
+ * and the consumer's Save handler can `await extractCropBlob(...)` once
+ * the user confirms (the hook does NOT keep the Blob around — only the
+ * URL — so the Save call re-encodes; that's fine because the user only
+ * Saves once per session).
+ *
+ * Internally:
+ * - Debounces the encode by `debounceMs` (default 120) so rapid drags/zooms
+ *   don't spam the encoder.
+ * - Uses a generation counter to discard stale in-flight encodes — without
+ *   this, a slow encode from an older crop could resolve AFTER a newer one
+ *   and overwrite the preview img with the wrong frame.
+ * - Auto-revokes its object URLs on replacement and on unmount.
+ *
+ * @example
+ * // Avatar picker:
+ * const [file, setFile] = useState<File | null>(null);
+ * const [crop, setCrop] = useState<CropArea | null>(null);
+ * const { previewUrl, encoding } = useCropPreview(file, crop, {
+ *   type: 'image/jpeg',
+ *   quality: 0.9,
+ *   outputWidth: 256,
+ * });
+ *
+ * return (
+ *   <Stack gap="md">
+ *     <FileUpload onFilesAdded={([f]) => setFile(f)} ... />
+ *     {file && (
+ *       <>
+ *         <ImageCrop src={file} value={crop} onChange={setCrop} aspectRatio={1} />
+ *         {previewUrl && (
+ *           <img src={previewUrl} style={{ opacity: encoding ? 0.5 : 1 }} />
+ *         )}
+ *       </>
+ *     )}
+ *   </Stack>
+ * );
+ *
+ * @remarks When NOT to use
+ * - For one-shot extraction (the user clicks "Save" and you need the Blob
+ *   once). Call `extractCropBlob` directly in the Save handler.
+ * - For server-side cropping. Send the `crop` coordinates instead.
+ *
+ * @remarks Anti-patterns
+ * - ❌ Calling `URL.revokeObjectURL(previewUrl)` manually. The hook owns
+ *   the URL lifecycle. Revoking it yourself produces broken-image renders.
+ * - ❌ Using the hook with `outputWidth` matching the source image (e.g.,
+ *   4080 for a 4080×3072 photo). The encode becomes expensive on every
+ *   drag tick; cap `outputWidth` at the display size you actually need.
+ */
+export function useCropPreview(
+  src: string | File | Blob | null | undefined,
+  crop: CropArea | null,
+  options: UseCropPreviewOptions = {},
+): UseCropPreviewResult {
+  const { type = 'image/jpeg', quality = 0.9, outputWidth, debounceMs = 120 } = options;
+
+  const [previewUrl, setPreviewUrl] = useState<string | null>(null);
+  const [previewBlob, setPreviewBlob] = useState<Blob | null>(null);
+  const [previewSize, setPreviewSize] = useState<number | null>(null);
+  const [encoding, setEncoding] = useState(false);
+
+  const urlRef = useRef<string | null>(null);
+  const genRef = useRef(0);
+
+  useEffect(() => {
+    if (!src || !crop) {
+      if (urlRef.current) {
+        URL.revokeObjectURL(urlRef.current);
+        urlRef.current = null;
+      }
+      setPreviewUrl(null);
+      setPreviewBlob(null);
+      setPreviewSize(null);
+      setEncoding(false);
+      return;
+    }
+    const gen = ++genRef.current;
+    setEncoding(true);
+    const handle = setTimeout(async () => {
+      try {
+        const blob = await extractCropBlob(src, crop, { type, quality, outputWidth });
+        if (gen !== genRef.current) return; // a newer crop has superseded us
+        if (urlRef.current) URL.revokeObjectURL(urlRef.current);
+        const url = URL.createObjectURL(blob);
+        urlRef.current = url;
+        setPreviewUrl(url);
+        setPreviewBlob(blob);
+        setPreviewSize(blob.size);
+        setEncoding(false);
+      } catch {
+        if (gen !== genRef.current) return;
+        setEncoding(false);
+      }
+    }, debounceMs);
+    return () => clearTimeout(handle);
+  }, [src, crop, type, quality, outputWidth, debounceMs]);
+
+  // Cleanup on unmount.
+  useEffect(
+    () => () => {
+      if (urlRef.current) URL.revokeObjectURL(urlRef.current);
+    },
+    [],
+  );
+
+  return { previewUrl, previewBlob, previewSize, encoding };
+}

package/src/components/Indent/Indent.module.scss

@@ -0,0 +1,33 @@
+@use './Indent.tokens';
+
+// No base layout of children — Indent only pads its OWN box (mirrors Constrain,
+// which only sizes its own box). `padding-inline-start` is a logical property:
+// left gutter in LTR, right in RTL, for free. padding (not margin) is allowed
+// under Hard rule 4.
+.indent {
+  padding-inline-start: calc(var(--indent-level, 1) * var(--indent-gutter));
+}
+
+.gutter-xs {
+  --indent-gutter: var(--indent-gutter-xs);
+}
+
+.gutter-sm {
+  --indent-gutter: var(--indent-gutter-sm);
+}
+
+.gutter-md {
+  --indent-gutter: var(--indent-gutter-md);
+}
+
+.gutter-lg {
+  --indent-gutter: var(--indent-gutter-lg);
+}
+
+.gutter-xl {
+  --indent-gutter: var(--indent-gutter-xl);
+}
+
+.gutter-2xl {
+  --indent-gutter: var(--indent-gutter-2xl);
+}

package/src/components/Indent/Indent.tokens.scss

@@ -0,0 +1,10 @@
+// Component tokens for <Indent> — default to the --space-* primitives. Same
+// name→px mapping as Stack's gap, so an Indent gutter reads at the same scale.
+:root {
+  --indent-gutter-xs: var(--space-1); // 4px
+  --indent-gutter-sm: var(--space-2); // 8px
+  --indent-gutter-md: var(--space-3); // 12px
+  --indent-gutter-lg: var(--space-4); // 16px
+  --indent-gutter-xl: var(--space-6); // 24px
+  --indent-gutter-2xl: var(--space-8); // 32px
+}

package/src/components/Indent/Indent.tsx

@@ -0,0 +1,46 @@
+import { forwardRef, type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './Indent.module.scss';
+
+/** Per-level indent size — a spacing step. */
+export type IndentGutter = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+export interface IndentProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Nesting depth — multiplies the gutter. `0` = flush (no indent, e.g. a
+   * root-level comment). Defaults to `1` (one gutter). Negative values clamp to `0`.
+   */
+  level?: number;
+  /**
+   * Per-level indent size — a spacing step. Defaults to `'lg'` (16px per level).
+   * - `xs` 4px · `sm` 8px · `md` 12px · `lg` 16px · `xl` 24px · `2xl` 32px
+   */
+  gutter?: IndentGutter;
+  /** The nested content to indent. Required — an Indent with nothing inside indents nothing. */
+  children: ReactNode;
+}
+
+/**
+ * Indentation primitive — indents its own box by `level × gutter`.
+ * @see docs/components/Indent.md
+ */
+// {...rest} last so consumer attrs win (Pattern A). But `style` is spread FIRST in
+// the merge below so the internal --indent-level wins — depth is set via the `level`
+// prop, not a raw style var (same var-protection as Grid's --grid-columns).
+export const Indent = forwardRef<HTMLDivElement, IndentProps>(function Indent(
+  { level = 1, gutter = 'lg', className, style, children, ...rest },
+  ref,
+) {
+  // Clamp to a non-negative, finite depth (a NaN/∞ level would yield an invalid calc()).
+  const indentLevel = Number.isFinite(level) ? Math.max(0, level) : 0;
+  return (
+    <div
+      ref={ref}
+      className={clsx(styles.indent, styles[`gutter-${gutter}`], className)}
+      style={{ ...style, ['--indent-level' as string]: indentLevel } as CSSProperties}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+});

package/src/components/Indent/index.ts

@@ -0,0 +1,2 @@
+export { Indent } from './Indent';
+export type { IndentProps, IndentGutter } from './Indent';

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

@@ -0,0 +1,99 @@
+@use '../../styles/mixins' as *;
+@use './Input.tokens';
+
+.input {
+  display: block;
+  width: 100%;
+  border: var(--border-width) solid var(--input-border-color);
+  border-radius: var(--input-radius);
+  background: var(--input-bg);
+  color: var(--input-fg);
+  font-family: inherit;
+  line-height: var(--input-line-height);
+  transition:
+    border-color var(--transition-fast),
+    box-shadow var(--transition-fast);
+
+  &::placeholder {
+    color: var(--input-placeholder-fg);
+  }
+
+  &:focus-visible {
+    border-color: var(--input-border-color-focus);
+
+    @include focus-ring(var(--input-ring-focus));
+  }
+
+  &:disabled {
+    background: var(--input-bg-disabled);
+    border-color: var(--input-border-color-disabled);
+    color: var(--input-fg-disabled);
+    cursor: not-allowed;
+  }
+}
+
+// Size modifiers. md is the default — match the previous hard-coded values.
+.size-sm {
+  height: var(--input-height-sm);
+  padding: 0 var(--input-padding-x-sm);
+  font-size: var(--input-font-size-sm);
+}
+
+.size-md {
+  height: var(--input-height-md);
+  padding: 0 var(--input-padding-x-md);
+  font-size: var(--input-font-size-md);
+}
+
+.size-lg {
+  height: var(--input-height-lg);
+  padding: 0 var(--input-padding-x-lg);
+  font-size: var(--input-font-size-lg);
+}
+
+.invalid {
+  border-color: var(--input-border-color-invalid);
+
+  &:focus-visible {
+    border-color: var(--input-border-color-invalid);
+
+    @include focus-ring(var(--input-ring-invalid));
+  }
+}
+
+// `suggestions` popup. Width and the viewport room for max-height are written
+// by Suggestions.tsx's Floating UI `size` middleware; position comes from its
+// inline floating styles. Mirrors Select's option list.
+.suggestions {
+  z-index: var(--z-popover);
+  box-sizing: border-box;
+  max-height: min(
+    var(--input-suggestions-max-height),
+    var(--input-suggestions-available-height, 100vh)
+  );
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  padding: var(--input-suggestions-padding);
+  list-style: none;
+  background: var(--input-suggestions-bg);
+  border: var(--border-width) solid var(--input-suggestions-border-color);
+  border-radius: var(--input-suggestions-radius);
+  box-shadow: var(--input-suggestions-shadow);
+}
+
+.suggestions[data-in-overlay] {
+  z-index: var(--z-overlay-floating);
+}
+
+.suggestion {
+  padding: var(--input-suggestion-padding-y) var(--input-suggestion-padding-x);
+  font-size: var(--input-suggestion-font-size);
+  color: var(--input-suggestion-fg);
+  cursor: pointer;
+  border-radius: var(--input-suggestion-radius);
+  overflow-wrap: anywhere;
+}
+
+.suggestionActive {
+  background: var(--input-suggestion-bg-active);
+}

package/src/components/Input/Input.tokens.scss

@@ -0,0 +1,54 @@
+// Input.tokens.scss — component-scoped tokens for <Input>. Defaults preserve byte-identical visual output. Sister field components (DatePicker, DateRangePicker, Select) own their own wrappers but mirror these values.
+:root {
+  // Surface
+  --input-bg: var(--color-bg);
+  --input-fg: var(--color-fg);
+  --input-border-color: var(--color-border-strong);
+  --input-radius: var(--radius-md);
+  --input-line-height: var(--line-height-normal);
+
+  // Placeholder
+  --input-placeholder-fg: var(--color-fg-subtle);
+
+  // Focus
+  --input-border-color-focus: var(--color-accent);
+  --input-ring-focus: var(--ring-accent);
+
+  // Disabled
+  --input-bg-disabled: var(--color-bg-subtle);
+  --input-border-color-disabled: var(--color-border);
+  --input-fg-disabled: var(--color-fg-subtle);
+
+  // Invalid
+  --input-border-color-invalid: var(--color-danger);
+  --input-ring-invalid: var(--ring-danger);
+
+  // Size — height per size
+  --input-height-sm: var(--size-sm);
+  --input-height-md: var(--size-md);
+  --input-height-lg: var(--size-lg);
+
+  // Size — horizontal padding per size
+  --input-padding-x-sm: var(--space-2);
+  --input-padding-x-md: var(--space-3);
+  --input-padding-x-lg: var(--space-3);
+
+  // Size — font-size per size
+  --input-font-size-sm: var(--font-size-sm);
+  --input-font-size-md: var(--font-size-md);
+  --input-font-size-lg: var(--font-size-lg);
+
+  // Suggestions popup — same values as Select's listbox + option rows.
+  --input-suggestions-bg: var(--color-bg);
+  --input-suggestions-border-color: var(--color-border);
+  --input-suggestions-radius: var(--radius-md);
+  --input-suggestions-shadow: var(--shadow-md);
+  --input-suggestions-padding: var(--space-1);
+  --input-suggestions-max-height: 320px;
+  --input-suggestion-padding-y: var(--space-2);
+  --input-suggestion-padding-x: var(--space-3);
+  --input-suggestion-font-size: var(--font-size-md);
+  --input-suggestion-fg: var(--color-fg);
+  --input-suggestion-radius: var(--radius-sm);
+  --input-suggestion-bg-active: var(--color-bg-muted);
+}

package/src/components/Input/Input.tsx

@@ -0,0 +1,105 @@
+import { forwardRef, useMemo, type InputHTMLAttributes } from 'react';
+import clsx from 'clsx';
+import { mergeRefs } from '../_internal/refs';
+import { useSuggestions } from './Suggestions';
+import styles from './Input.module.scss';
+
+/**
+ * Field height + type scale. Pairs with `<Button>` and `<Select>` sizes.
+ */
+export type InputSize = 'sm' | 'md' | 'lg';
+
+export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+  /**
+   * Toggles the error visual (red border + focus ring) and sets `aria-invalid="true"`.
+   * Pair with a visible error message and `aria-describedby` pointing at the message id.
+   */
+  invalid?: boolean;
+  /**
+   * Visual size. Defaults to `'md'`.
+   * - `'sm'` — 24px tall; toolbars, secondary forms.
+   * - `'md'` — 32px tall (default); most form contexts.
+   * - `'lg'` — 40px tall; hero search, mobile-friendly forms.
+   *
+   * Same scale as `<Select>`; fields have no `xs` (unlike `<Button>`).
+   *
+   * Note: this shadows the native HTML `<input size>` attribute (visible
+   * character count). If you need that legacy attribute, set width via
+   * `style` or a parent container.
+   */
+  size?: InputSize;
+  /**
+   * Block browser autofill AND password managers from offering to fill
+   * this input. Applies the standard set of opt-out hints:
+   * - `autoComplete="off"`
+   * - `data-1p-ignore` (1Password)
+   * - `data-lpignore="true"` (LastPass)
+   * - `data-form-type="other"` (generic "not a login field")
+   *
+   * **Smart default**: when omitted, the input blocks autofill iff `autoComplete`
+   * is also omitted (or `'off'`). Explicit autocomplete hints
+   * (`autoComplete="email"`, `"current-password"`, `"username"`, etc.) opt back
+   * IN to autofill — the assumption is that a consumer specifying autoComplete
+   * actually wants password-manager interaction. Pass `disableAutofill={true}`
+   * to force-block even with an autocomplete hint, or `false` to force-allow
+   * (except while `suggestions` is active, which always blocks).
+   */
+  disableAutofill?: boolean;
+  /**
+   * Values to suggest while the value stays free text (e.g. the user's other
+   * workspace slugs). Makes the input an ARIA combobox with a suggestion list:
+   * it opens on focus, click or ↓ showing every suggestion, then filters by
+   * case-insensitive substring once the user types. ↑/↓ + Enter or a click
+   * fills the value and fires `onChange` exactly as typing would. Ignored when
+   * empty or `readOnly`. Browser autofill is forced off while active (even with
+   * an `autoComplete` hint) so its dropdown can't stack on this one. Default:
+   * none (a plain textbox). For a fixed set of allowed values use `<Select>`
+   * instead.
+   */
+  suggestions?: readonly string[];
+}
+
+const AUTOFILL_DISABLED_PROPS = {
+  autoComplete: 'off' as const,
+  'data-1p-ignore': '' as const,
+  'data-lpignore': 'true' as const,
+  'data-form-type': 'other' as const,
+};
+
+/**
+ * Single-line text input that forwards all native `<input>` attributes.
+ * @see docs/components/Input.md
+ */
+export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
+  { invalid, size = 'md', disableAutofill, suggestions, className, ...props },
+  ref,
+) {
+  const combobox = useSuggestions(suggestions, props.readOnly, props);
+  const mergedRef = useMemo(() => mergeRefs(ref, combobox.inputRef), [ref, combobox.inputRef]);
+
+  // Smart default: when `disableAutofill` is undefined, block autofill iff
+  // the consumer hasn't set a meaningful `autoComplete`. Explicit `true` /
+  // `false` always wins over the heuristic (except while `suggestions` is active).
+  const hasAutocompleteHint =
+    typeof props.autoComplete === 'string' && props.autoComplete !== 'off';
+  const blockAutofill = disableAutofill ?? !hasAutocompleteHint;
+
+  return (
+    <>
+      <input
+        // Plain consumer ref unless it's a combobox (no extra commit either way).
+        ref={combobox.enabled ? mergedRef : ref}
+        aria-invalid={invalid || undefined}
+        {...(blockAutofill ? AUTOFILL_DISABLED_PROPS : {})}
+        {...props}
+        // Suggestions force autofill off, beating any consumer autoComplete.
+        {...(combobox.enabled ? AUTOFILL_DISABLED_PROPS : {})}
+        // After {...props} so the combobox ARIA contract wins; its handlers
+        // already chain the consumer's.
+        {...combobox.inputProps}
+        className={clsx(styles.input, styles[`size-${size}`], invalid && styles.invalid, className)}
+      />
+      {combobox.popup}
+    </>
+  );
+});