@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/ImageCrop.md

@@ -0,0 +1,163 @@
+> **Breaking in 0.6.0:** `minZoom`, `maxZoom` and `showZoomControl` are deleted, with no replacement. The component is now a still image with a draggable, resizable crop box, so it is shorter (no slider row). A floating Reset button is opt-in via `showReset`. Scroll-wheel over the cropper now resizes the box (it no longer zooms the image). The i18n key `imageCrop.zoom` is removed (new keys: `imageCrop.reset`, `imageCrop.label`, `imageCrop.keyboardHint`, `imageCrop.aspectRatio`, `imageCrop.areaValue`); delete any `I18nProvider` override of `imageCrop.zoom`.
+
+# `<ImageCrop>` — controlled image cropper
+
+```tsx
+const [crop, setCrop] = useState<CropArea | null>(null);
+
+<ImageCrop src={file} value={crop} onChange={setCrop} aspectRatio={1} />;
+
+// In the Save handler:
+const handleSave = async () => {
+  if (!crop) return;
+  const blob = await extractCropBlob(file, crop, {
+    type: 'image/jpeg',
+    quality: 0.9,
+    outputWidth: 512,
+  });
+  await uploadToS3(blob);
+};
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `src` | `string \| File \| Blob` | yes | Image source. String URLs (HTTP/HTTPS, data:, blob:) pass through. File/Blob are normalized to object URLs internally via `URL.createObjectURL()`, with cleanup on unmount and `src` change. |
+| `value` | `CropArea \| null` | yes | Controlled crop area in SOURCE-IMAGE pixel coordinates. Pass `null` to use the component's default centered crop (80% of the largest centered region matching `aspectRatio`). |
+| `onChange` | `(area: CropArea) => void` | yes | Fires on every drag/resize tick. High frequency. Also fires once on first image load when `value` is `null`, with the computed default crop; after that the consumer owns the state. |
+| `onChangeEnd` | `((area: CropArea) => void)` | no | Fires on commit: when a drag/resize is released, ~200ms after the last wheel tick, on each key press, and on Reset/double-click. |
+| `aspectRatio` | `number` | no | Fixed aspect ratio for the crop box (e.g. `1` for square, `16/9`). Omit for free aspect — edge handles then appear too. Toggling it at runtime does NOT re-fit `value`; pass a fresh `value` (or `null`) with the change. |
+| `disabled` | `boolean` | no | Disable all interaction (move, resize). Default `false`. Image still renders. |
+| `showReset` | `boolean` | no | Render the on-canvas Reset button. Default `false`; double-click reset works regardless. |
+| `aspectRatios` | `ImageCropAspectOption[]` | no | Options for an on-canvas aspect-ratio switcher. Labels are consumer strings (your i18n). Controlled: the option whose `value === aspectRatio` shows as selected, and picking one calls `onAspectRatioChange`, then `onChange`/`onChangeEnd` with that ratio's default crop. Omit or pass `[]` for no switcher. Requires `onAspectRatioChange` and a controlled `aspectRatio`; without them the pick commits a crop in the old ratio. |
+| `onAspectRatioChange` | `((ratio: ImageCropAspectRatio) => void)` | no | Fires when an option is picked in the switcher (`undefined` = free aspect). Update your `aspectRatio` state here. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Move the box**: the image is still; drag the crop box to reposition it (clamped to the image).
+- **Resize**: the box never shrinks below 48 screen px per side. Corner handles always (ratio-locked when `aspectRatio` is set); edge handles appear in free aspect. Scroll wheel resizes around the box center, proportional to scroll distance (≈6% per mouse-wheel notch; scroll down grows, up shrinks).
+- **Reset**: double-click (always) or the floating Reset button (opt-in via `showReset`) restores the default crop (80% of the largest fitting box).
+- **`aspectRatio?: number`** — pass `1` for square, `16/9` for landscape, etc. Omit for free aspect (edge handles appear).
+- **Aspect-ratio switcher**: pass `aspectRatios` + `onAspectRatioChange` for an on-canvas segmented control (stock `ButtonGroup`). You still own `aspectRatio`; picking an option reports it, then commits that ratio's default crop through `onChange`/`onChangeEnd`. Labels are your strings. With neither switcher nor `showReset`, no toolbar renders and the image uses the full viewport.
+
+```tsx
+const [ratio, setRatio] = useState<number | undefined>(1);
+<ImageCrop
+  src={file}
+  value={crop}
+  onChange={setCrop}
+  aspectRatio={ratio}
+  aspectRatios={[
+    { label: '1:1', value: 1 },
+    { label: '3:4', value: 3 / 4 },
+    { label: '16:9', value: 16 / 9 },
+    { label: 'Free' },
+  ]}
+  onAspectRatioChange={setRatio}
+/>;
+```
+
+- **`onChange` fires per drag/resize tick (high frequency).** Debounce in the consumer OR use `onChangeEnd` (fires on drag/resize release, ~200ms after the last wheel tick, on each key press, and on Reset/double-click).
+- **`extractCropBlob(src, area, options?)`** is a top-level utility (NOT a ref method). Call it in the Save handler to produce the cropped Blob. Supports `type` (PNG/JPEG/WebP), `quality` (0..1 for lossy), and `outputWidth` (proportional resize — useful for capping avatar size).
+- **Keyboard** (when the crop area — `role="application"` "Crop area", whose `aria-valuetext` reads the current position and size — is focused; a screen-reader-only hint describes the keys): Arrow keys move the box by 5 source px. Shift+Arrows resize (Right/Down grow, Left/Up shrink; ratio-locked with `aspectRatio`, one axis in free mode). Home/End jump to top-left / bottom-right. Double-click resets to the default crop.
+- **Loading state**: shows `<Skeleton variant="rectangular">` until the image's `onload` fires. Errors show "Couldn't load image" in danger tone.
+- **`disabled`**: move, resize, wheel, keyboard, Reset and the ratio switcher all disabled. Viewport opacity dimmed.
+
+#### `CropArea` (in source-image pixels)
+
+```ts
+interface CropArea {
+  x: number; // top-left X in source-image pixels
+  y: number; // top-left Y in source-image pixels
+  width: number; // crop width in source-image pixels
+  height: number; // crop height in source-image pixels
+}
+```
+
+#### `ExtractCropOptions`
+
+```ts
+interface ExtractCropOptions {
+  type?: 'image/png' | 'image/jpeg' | 'image/webp'; // default 'image/png'
+  quality?: number; // 0..1, default 0.92 (ignored for PNG)
+  outputWidth?: number; // resize output width; height proportional
+}
+```
+
+#### `useCropPreview(src, crop, options?)` — live-preview hook
+
+Reusable hook for the canonical "avatar / cover photo picker" flow. Debounces an `extractCropBlob` encode on every crop change, guards against stale in-flight encodes, and owns the object URL lifecycle. Returns `{ previewUrl, previewBlob, previewSize, encoding }`.
+
+```tsx
+const [file, setFile] = useState<File | null>(null);
+const [crop, setCrop] = useState<CropArea | null>(null);
+
+const { previewUrl, previewBlob, encoding } = useCropPreview(file, crop, {
+  type: 'image/jpeg',
+  quality: 0.9,
+  outputWidth: 256,
+});
+
+const handleSave = async () => {
+  if (!previewBlob) return;
+  const fd = new FormData();
+  fd.append('file', previewBlob, 'avatar.jpg');
+  await fetch('/api/upload-avatar', { method: 'POST', body: fd });
+};
+
+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 }} />}
+        <Button onClick={handleSave} disabled={!previewBlob || encoding}>Save</Button>
+      </>
+    )}
+  </Stack>
+);
+```
+
+`previewBlob` is the same content backing `previewUrl` — reuse it in the Save handler instead of calling `extractCropBlob` again (the hook already encoded it).
+
+`UseCropPreviewOptions` extends `ExtractCropOptions` with one extra field:
+
+```ts
+interface UseCropPreviewOptions extends ExtractCropOptions {
+  debounceMs?: number; // default 120; set to 0 in tests, 250+ for 4K photos
+}
+```
+
+#### Hard rule
+
+- ❌ Hand-rolling a `<canvas>` + drag math per page. Use this.
+- ❌ Calling `extractCropBlob` on every `onChange` tick. Use `useCropPreview` if you need a live preview — it debounces and race-guards correctly. For one-shot extraction (Save click only), call `extractCropBlob` once in the handler.
+- ❌ Calling `extractCropBlob` AGAIN in the Save handler when you already have `useCropPreview` mounted. Reuse `previewBlob` — it's the same encoded result.
+- ❌ Wrapping `<img>` in CSS clip-path for a "crop preview" — that doesn't produce a cropped Blob. Use `extractCropBlob` or `useCropPreview`.
+- ❌ `<ImageCrop ref={ref}>` expecting `.getBlob()`. There's no imperative API. The extraction utility is a top-level export.
+- ❌ Calling `URL.revokeObjectURL(previewUrl)` from `useCropPreview` manually. The hook owns the URL lifecycle.
+- ❌ Cropping a circular avatar at the canvas level. Crop rectangular, then CSS-mask in the consumer.
+- Not for server-side cropping (send `value`'s `CropArea` coordinates to your backend instead of calling `extractCropBlob`), rotation (not supported), or pinch gestures (not supported; there is no zoom).
+
+```tsx
+// Free aspect (no aspectRatio prop)
+<ImageCrop src={imageUrl} value={crop} onChange={setCrop} />
+
+// Canonical "pick → crop → save" flow inside a Modal
+<Modal isOpen onClose={cancel}>
+  <Modal.Header>Crop your photo</Modal.Header>
+  <Modal.Body>
+    <ImageCrop src={file} value={crop} onChange={setCrop} aspectRatio={1} />
+  </Modal.Body>
+  <Modal.Footer>
+    <Button variant="secondary" onClick={cancel}>Cancel</Button>
+    <Button onClick={handleSave} disabled={!crop}>Save</Button>
+  </Modal.Footer>
+</Modal>
+```

package/docs/components/Indent.md

@@ -0,0 +1,31 @@
+# `<Indent>` — indent nested content by depth
+
+`<Indent level={n} gutter="lg">` indents its own box by `level × gutter` via `padding-inline-start` (token-based, RTL-aware). The DS-native way to express nesting depth — threaded comment trees, file/outline views — without inline CSS. `level={0}` is flush; nesting compounds. It pads its own box only (wrap a `<Stack>` inside for a multi-row block). For plain sibling spacing use `<Stack gap>`, not Indent.
+
+```tsx
+{
+  comments.map((c) => (
+    <Indent key={c.id} level={c.depth}>
+      <CommentCard comment={c} />
+    </Indent>
+  ));
+}
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `level` | `number` | no | 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`. |
+| `gutter` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | no | 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 |
+| `children` | `ReactNode` | yes | The nested content to indent. Required — an Indent with nothing inside indents nothing. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Don't pass a fractional or huge `level`.
+- Not for general left padding on non-nested content — it expresses hierarchy; use the parent layout primitive.
+- Not for a bordered / padded surface (`<Card>`) or arranging children in a row (`<Cluster>`).

package/docs/components/InlineDatePicker.md

@@ -0,0 +1,58 @@
+# `<InlineDatePicker>` — single-date calendar in flow
+
+```tsx
+const [date, setDate] = useState<Date | null>(null);
+<InlineDatePicker value={date} onChange={setDate} min={new Date()} />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `Date \| null` | no | Selected date. `null` = no value. Pair with `onChange` for controlled use. |
+| `defaultValue` | `Date \| null` | no | Initial selected date for uncontrolled use. |
+| `onChange` | `((date: Date \| null) => void)` | no | Fires when the user clicks a cell. Currently always fires with a `Date`; `null` is reserved for a future clear / deselect mechanism. |
+| `locale` | `string` | no | Override locale (otherwise reads `useLocale()`). |
+| `min` | `Date` | no | Earliest selectable date (inclusive). |
+| `max` | `Date` | no | Latest selectable date (inclusive). |
+| `isDateDisabled` | `((date: Date) => boolean)` | no | Per-date disable callback. Disabled cells are non-clickable; arrow-key nav skips them. |
+| `name` | `string` | no | Form name. When set, renders a hidden `<input type="hidden">` mirror with the ISO date. |
+| `disabled` | `boolean` | no | Disables interaction — cells / chevrons / keyboard nav all blocked. Defaults to `false`. |
+| `granularity` | `'day' \| 'minute'` | no | Picker precision. - `'day'` (default) — date only; behavior unchanged from prior releases. - `'minute'` — adds a manual-entry time input below the calendar grid. The hidden form mirror (when `name` is set) emits ISO local datetime (`2026-05-28T14:30`). Time is preserved across date re-picks. Picking from a `null` value defaults the time to `00:00`. |
+| `timeStep` | `number` | no | Minutes step for the `<TimeField>` popover and for rounding typed time input on commit. Defaults to `15`. Set `1` to disable rounding. Only meaningful when `granularity='minute'`. |
+| `hourCycle` | `'12' \| '24' \| 'auto'` | no | Display cycle for the embedded `<TimeField>`. - `'24'` — `"HH:mm"` text input; 24h hour list in the popover. - `'12'` — `"h:mm AM/PM"` text input; 12h hour list + AM/PM column. - `'auto'` (default) — derives from the active locale via Intl. en-US → `'12'`; ru-RU → `'24'`. Only meaningful when `granularity='minute'`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Same month-grid surface as `<DatePicker>` but always rendered in flow — no input, no popover, no portal. Use when the calendar should be visible at all times (sidebar pickers, schedule editors, quick-filter panels).
+- Cursor anchors to `value ?? new Date()` on mount and re-anchors each time `value` transitions from `null` to a non-null date (e.g. loading an async initial value, or a consumer clearing and re-setting). After a transition, later non-null `value` changes do not move the cursor — `ref` is the wrapper `<div>` and exposes no cursor API; to jump to the new month, remount with a changed `key`.
+- `forwardRef` points at the outer wrapper `<div>` (no input to forward to).
+- ARIA: same `role="grid"` + `role="gridcell"` cells from `DatePickerGrid`. No dialog role — the picker is in flow.
+- **Granularity.** Pass `granularity="minute"` to render a `<TimeField>` below the grid (always visible — there's no popover to gate it on); the hidden form mirror emits ISO local datetime. Defaults to `'day'`. Time is preserved across date re-picks; the field is disabled until a date is set. Same trigger-text contract is not applicable (no trigger). `timeStep` (default `15`, in minutes) controls the TimeField's minute-list row count AND rounds typed input in the time field on commit; set `timeStep={1}` to disable rounding. `hourCycle` (default `'auto'`) forwards to the embedded TimeField — `'12'` / `'24'` force a cycle, `'auto'` derives from locale.
+
+```tsx
+// Constrained + form mirror
+<form action="/api/dates">
+  <InlineDatePicker name="dob" min={new Date()} />
+  <button type="submit">Save</button>
+</form>
+
+// Disabled (read-only display)
+<InlineDatePicker disabled defaultValue={new Date()} />
+```
+
+#### When NOT to use
+
+- Compact form field: use `<DatePicker>` (the popover variant).
+- Choosing a range: use `<InlineDateRangePicker>`.
+- Seconds-precision tracking: only `granularity="minute"` is supported.
+- Time-only fields (no date): out of scope.
+
+#### Anti-patterns
+
+- ❌ Rendering several `<InlineDatePicker>`s in one flex row without giving them their intrinsic width — the calendars get squashed. Wrap in `<Stack>` or give each a column.
+- ❌ Using `value` without `onChange` — the picker is controlled when `value` is set; user clicks have no effect.

package/docs/components/InlineDateRangePicker.md

@@ -0,0 +1,57 @@
+# `<InlineDateRangePicker>` — date-range calendar in flow
+
+```tsx
+const [range, setRange] = useState<DateRange | null>(null);
+<InlineDateRangePicker value={range} onChange={setRange} />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `DateRange \| null` | no | Selected range. `null` = no range. Pair with `onChange` for controlled use. |
+| `defaultValue` | `DateRange \| null` | no | Initial range for uncontrolled use. |
+| `onChange` | `((range: DateRange \| null) => void)` | no | Fires when a complete range commits (second click, auto-swapped). Currently always fires with a complete `DateRange`; `null` is reserved for a future clear / deselect mechanism. |
+| `locale` | `string` | no | Override locale. |
+| `min` | `Date` | no | Earliest selectable date (inclusive). |
+| `max` | `Date` | no | Latest selectable date (inclusive). |
+| `isDateDisabled` | `((date: Date) => boolean)` | no | Per-date disable predicate. |
+| `nameStart` | `string` | no | Form name for the START half (hidden `<input>` mirror). |
+| `nameEnd` | `string` | no | Form name for the END half. |
+| `disabled` | `boolean` | no | Disables interaction. Defaults to `false`. |
+| `granularity` | `'day' \| 'minute'` | no | Picker precision. - `'day'` (default) — date only; behavior unchanged from prior releases. - `'minute'` — adds two manual-entry time inputs (start + end) below the two-month grid. Hidden form mirrors (when `nameStart` / `nameEnd` are set) emit ISO local datetime (`2026-05-28T14:30`). At `'minute'` the start/end time inputs are shown and editable even before a range is picked (defaulting to `00:00` / `23:59`). Times entered in the empty state are applied when the range is committed (instead of the bare defaults), and existing times are preserved across date re-picks. Same-day ranges with end-time < start-time are silently clamped so end-time ≥ start-time. |
+| `timeStep` | `number` | no | Minutes step for the start + end `<TimeField>` popovers and for rounding typed time input on commit. Defaults to `15`. Set `1` to disable rounding. Only meaningful when `granularity='minute'`. |
+| `hourCycle` | `'12' \| '24' \| 'auto'` | no | Display cycle for the two embedded `<TimeField>`s. - `'24'` — `"HH:mm"` text inputs; 24h hour list in popovers. - `'12'` — `"h:mm AM/PM"` text inputs; 12h hour list + AM/PM column. - `'auto'` (default) — derives from the active locale via Intl. en-US → `'12'`; ru-RU → `'24'`. Only meaningful when `granularity='minute'`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Two-month calendar grid (side-by-side) embedded directly in the page. Same click-1/click-2/restart selection machine, hover preview, auto-swap on out-of-order picks, and keyboard cross-grid navigation as `<DateRangePicker>` — without the input + popover.
+- External prev/next chevrons in the header shift both grids by ±1 month at once.
+- Cursor anchors to `value?.start ?? new Date()` on mount and re-anchors each time `value` transitions from `null` to a non-null range (e.g. loading an async initial value, or a consumer clearing and re-setting). After a transition, later non-null `value` changes do not move the cursor — `ref` is the wrapper `<div>` and exposes no cursor API; to jump to the new month, remount with a changed `key`.
+- Keyboard cross-grid navigation works in both directions between the two grids.
+- `ref` forwards to the outer wrapper.
+- Use when the consumer wants the calendar permanently visible. For a compact form field with the same selection model, use `<DateRangePicker>`. Don't render inside containers narrower than ~32rem — the two grids need side-by-side room.
+- **Granularity.** Pass `granularity="minute"` to render dual `<TimeField>`s (start + end) below the two-month grid; the hidden form mirrors emit ISO local datetime. Defaults to `'day'`. The start/end time inputs are shown and editable below the grid even before a range is picked — defaulting to `00:00` start / `23:59` end. Times set in this empty state are applied when the range is committed (no need to seed a placeholder range), and existing times are preserved across subsequent date picks. Same-day end-time silently clamps to ≥ start-time on every commit; different-day ranges are not clamped. `timeStep` (default `15`, in minutes) applies to BOTH TimeFields, controlling each minute-list row count AND rounding typed input in the time fields on commit; set `timeStep={1}` to disable rounding. `hourCycle` (default `'auto'`) forwards to both embedded TimeFields — `'12'` / `'24'` force a cycle, `'auto'` derives from locale.
+
+```tsx
+<form action="/api/bookings">
+  <InlineDateRangePicker nameStart="bookingStart" nameEnd="bookingEnd" min={new Date()} />
+  <button type="submit">Save</button>
+</form>
+```
+
+#### When NOT to use
+
+- Compact form field: use `<DateRangePicker>` (the popover variant).
+- Single-date selection: use `<InlineDatePicker>`.
+- Seconds-precision tracking: only `granularity="minute"` is supported.
+- Time-only fields (no date): out of scope.
+
+#### Anti-patterns
+
+- ❌ Wrapping in a narrow container (< ~32rem): the two grids need side-by-side room; squashing them clips the right grid.
+- ❌ Using `value` without `onChange`.

package/docs/components/Input.md

@@ -0,0 +1,54 @@
+# `<Input>` — single-line text
+
+```tsx
+<Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
+<Input invalid value={email} aria-describedby="email-error" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `invalid` | `boolean` | no | 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. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | 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. |
+| `disableAutofill` | `boolean` | no | 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). |
+| `suggestions` | `readonly string[]` | no | 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. |
+| …native | | | plus native `<input>` attributes |
+
+<!-- props:end -->
+
+- All native `<input>` attributes pass through, except `size` — that's been replaced by the component-level `size` prop (the native HTML `size` attribute, visible-character count, is shadowed).
+- **Autofill is BLOCKED by default** — `<Input />` carries `autoComplete="off"` + the 1Password / LastPass / generic data-\* opt-out hints so password managers don't misfire on search / filter / free-text fields. Set `autoComplete="email"` (or `"username"`, `"current-password"`, etc.) to opt INTO autofill for real form fields. Force the behavior either way via `disableAutofill={true | false}`.
+- Validation logic lives in your form layer (React Hook Form + Zod recommended), not in the component.
+- Not for multi-line (`Textarea`), a fixed list (`Select` — `suggestions` never restricts the value), date/time (`DatePicker` / `DateRangePicker`) or password reveal (`PasswordInput`).
+- ❌ Putting validation logic inside the component. ❌ Using `placeholder` as a label — it disappears on focus; pair the Input with a real `<label>`. ❌ `type="number"` for phone numbers or zip codes — it strips leading zeros; use `inputMode="numeric"`.
+
+```tsx
+<Input size="sm" placeholder="Filter…" />
+<Input size="lg" type="search" placeholder="Search the workspace" />
+<Input invalid value={value} aria-describedby="email-error" />
+<p id="email-error">Enter a valid email.</p>
+```
+
+## Suggestions
+
+Free text plus suggestions — e.g. a workspace slug prefilled with the last one used, suggesting the user's others:
+
+```tsx
+<Input
+  value={workspace}
+  onChange={(e) => setWorkspace(e.target.value)}
+  suggestions={['acme', 'acme-staging', 'northwind']}
+/>
+```
+
+- The input becomes an ARIA combobox with a listbox named "Suggestions" (i18n `input.suggestions`). Without `suggestions` (or with `[]`, or when `readOnly`) it is a plain textbox.
+- The list opens whenever the input gains focus — including Tab traversal, `autoFocus` and focus returned by a Modal — not only on click.
+- While `suggestions` is active, browser autofill is forced off (as `disableAutofill`) even if you pass a real `autoComplete`, so the browser dropdown cannot stack on this one.
+- Opens on focus, click or ↓ and shows **every** suggestion until the user edits the text, so a prefilled value doesn't hide the rest; then it filters by case-insensitive substring, in the given order. No matches → it stays closed (no "no results" row).
+- ↓/↑ move the highlight (wraps; nothing highlighted at first). Enter on a highlight or a click fills the value and fires `onChange` exactly like typing (controlled and uncontrolled). Enter with no highlight stays native (submits the form). Esc, Tab and blur close without changing the value.
+- The popup matches the input's width, flips when there's no room below and scrolls past `--input-suggestions-max-height`.
+- ❌ A fixed set of allowed values → `Select` (or `Select creatable`). ❌ Async / loaded results, groups or rich rows → `Select` with `loadOptions`, or `TopBar.Search`. ❌ Re-adding a native `<datalist>` — it looks different per browser and `Input` turns browser autocomplete off.

package/docs/components/Kanban.md

@@ -0,0 +1,122 @@
+# `<Kanban>` — multi-column board (drag-to-reorder + cross-column drag with live reflow)
+
+Trello/Jira-style board UI. Compound: `Kanban`, `Kanban.Column`, `Kanban.Card`, `Kanban.Handle` (re-exported `Sortable.Handle`). Built on the same `@dnd-kit/sortable` plumbing as `<Sortable>` with internal items state that re-arranges cards live as the dragged card crosses column boundaries.
+
+```tsx
+import { Kanban, type KanbanMoveEvent } from '@eocrm/design-system';
+
+const [board, setBoard] = useState({
+  todo: [{ id: 'a', title: 'Buy milk' }],
+  doing: [{ id: 'b', title: 'Write spec' }],
+  done: [{ id: 'c', title: 'Ship Sortable' }],
+});
+
+function handleMove(event: KanbanMoveEvent) {
+  const { from, to, cardId } = event;
+  setBoard((curr) => {
+    const next = { ...curr };
+    const source = [...next[from.columnId as keyof typeof curr]];
+    const [moved] = source.splice(from.index, 1);
+    next[from.columnId as keyof typeof curr] = source;
+    const target =
+      from.columnId === to.columnId ? source : [...(next[to.columnId as keyof typeof curr] ?? [])];
+    target.splice(to.index, 0, moved);
+    next[to.columnId as keyof typeof curr] = target;
+    return next;
+  });
+}
+
+<Kanban onMove={handleMove}>
+  {(['todo', 'doing', 'done'] as const).map((colId) => (
+    <Kanban.Column key={colId} id={colId}>
+      <Title order={3}>{colId}</Title>
+      {board[colId].map((c) => (
+        <Kanban.Card key={c.id} id={c.id}>
+          <Card>{c.title}</Card>
+        </Kanban.Card>
+      ))}
+    </Kanban.Column>
+  ))}
+</Kanban>;
+```
+
+<!-- props:start -->
+
+## Props
+
+### `KanbanProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `onMove` | `((event: KanbanMoveEvent) => void)` | no | Fires once per drag (on drop) with the from/to positions and the cardId. NOT fired on drag cancel. NOT fired when from === to (no-op drop). Consumer should update their items state immutably, e.g.: (example below) |
+| …native | | | plus native `<div>` attributes |
+
+**`onMove`** example:
+
+<!-- prettier-ignore -->
+```ts
+const [cols, setCols] = useState({ todo: ['a', 'b'], done: ['c'] });
+const handleMove = ({ from, to, cardId }) => {
+  setCols((prev) => {
+    const next = { ...prev };
+    next[from.columnId] = [...prev[from.columnId]];
+    next[from.columnId].splice(from.index, 1);
+    next[to.columnId] = [...prev[to.columnId]];
+    next[to.columnId].splice(to.index, 0, cardId);
+    return next;
+  });
+};
+```
+
+### `KanbanCardProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string \| number` | yes | Stable identifier for this card. Must be unique across ALL columns in the `<Kanban>`. Used by dnd-kit to track the card during drag. |
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<div>` attributes |
+
+### `KanbanColumnProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string \| number` | yes | Stable identifier for this column. Must be unique within a `<Kanban>`. Used internally to track which cards belong to which column. |
+| `children` | `ReactNode` | no |  |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+Controlled-only: the consumer applies each `onMove`. Column layout (header, footer) goes before / after the `<Kanban.Card>` children.
+
+**Drag origin** (hybrid): `<Kanban.Handle>` inside a Card restricts drag origin to the Handle. Without a Handle, the whole Card is draggable (and dnd-kit assigns it `role="button"`). With a Handle the card div gets `role="article"`.
+
+**Cross-column drag is LIVE**: as the dragged card crosses into a new column, cards in the target column shift to make room in real time. `onMove` still fires only once on release. This is driven by internal Kanban state — consumer's state is untouched until drop, so re-renders are scoped to the Kanban subtree (avoids the measureRect cascade that would happen if mid-drag mutations went through consumer setState).
+
+**Drop slot**: `to.index` is the slot the preview showed at release — it re-evaluates as the cursor moves inside the target column, not only when the card crosses the boundary.
+
+**Drop slot edge cases:** dropping onto an empty column lands at index 0; dropping in a column's padding past the last card appends to that column's end (including the source column's own padding). The drop target is decided by the pointer, while the dragged card itself stays clamped to the board — a card that looks parked on the last column has still cancelled if the cursor was released past it.
+
+**Releasing off the board cancels**: release with the cursor outside the columns — over unrelated page content, past the last column — and the card snaps back with NO `onMove`. "Outside" means outside the columns' collective bounding box, so the gutter between two columns still commits to the nearer one; only leaving the band of columns entirely cancels. Escape and a release that never left the card's own slot cancel the same way.
+
+**Overflowing boards auto-scroll**: the board is its own horizontal scroll container, so dragging a card near the left/right edge scrolls it — that is how you reach an off-screen column. The dragged card is confined to the board's scrollable content box on both axes (it stops at the outer edge of the first/last column rather than following the cursor out of the board). That bound is what keeps auto-scroll from running away: the card renders in flow, so an unbounded one would extend the board's own `scrollWidth` and auto-scroll would chase the edge it just created. Nothing to configure. Caveat: the bound is the card's NEAREST scrolling ancestor. Capping a column (`overflow-y: auto` + `max-height` on `<Kanban.Column>`) makes the column that ancestor, and the dragged card is then confined to its own column while dragging — the drop still lands wherever the cursor is, but the card won't visibly cross into the neighbour. Scroll the board, not the columns.
+
+**Keyboard reorder** works WITHIN a column (Tab to Card/Handle, Space pick up, Arrow keys move, Space drop). Cross-column keyboard moves are NOT supported in v1.
+
+**When NOT to use**
+
+- Single-column drag-to-reorder — use `<Sortable>`.
+- Pure display boards with no drag — use `<Stack>` + `<Card>`.
+- Column reordering is not supported; columns render in source JSX order.
+
+**Anti-patterns**
+
+- ❌ Expecting cross-column keyboard reorder. dnd-kit's stock coordinate-getter is per-`SortableContext`. v2 will ship a custom getter that bridges columns.
+- ❌ Leaving `<Kanban.Column>` unnamed. Screen-reader drag announcements name the destination column from its `aria-label` or `aria-labelledby`; without either they fall back to "column 2 of 3". A named column also renders as `role="group"` so the name isn't inert.
+- ❌ A content-heavy `<Kanban.Card>` with no `aria-label`. The card announces itself by its rendered text, so a card carrying title + assignee + due date + badges reads all of it on every drag step. One `aria-label` fixes it.
+- ❌ Interleaving non-`Kanban.Card` children with cards inside a `<Kanban.Column>`. The Root walks each column's children to extract a contiguous card block; if non-cards appear between cards, the rendering re-arranges them awkwardly. Keep header / count badges BEFORE the cards, footer / "Add card" buttons AFTER.
+- ❌ Wrapping `<Kanban.Card>` inside a custom component. The Root walks direct descendants of `<Kanban.Column>` to find cards; nested cards are invisible to it.
+- ❌ Non-stable column / card ids (e.g. array indices). Both must persist across reorders.
+- ❌ Mutating board state in place inside `onMove`. Always return a new object/array reference.

package/docs/components/Kbd.md

@@ -0,0 +1,41 @@
+# `Kbd`
+
+Inline keyboard-shortcut display: one `<kbd>` chip per key, joined with a faint `+` separator. Use for shortcut hints in tooltips, command palettes, search inputs, and help/shortcut sheets.
+
+```tsx
+<Kbd keys={['⌘', 'K']} />
+<Kbd keys={['Ctrl', 'Shift', 'P']} size="md" />
+<Kbd keys={['Esc']} />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `keys` | `string[]` | yes | Keys to display. Each entry renders one `<kbd>` chip. Multiple entries are joined with an inline `+` separator; a single-entry array renders no separator. Pass the literal label you want shown (`'⌘'`, `'Ctrl'`, `'Shift'`, `'K'`) — the component does NOT platform-translate. |
+| `size` | `'sm' \| 'md'` | no | Visual size. `'sm'` is the inline-chrome size (18px tall — matches `TopBar.Search`'s hotkey hint). `'md'` is the standalone shortcut size (24px tall — for command-palette / shortcut-sheet UI). Default: `'sm'`. |
+| `aria-label` | `string` | no | Accessible label for the whole shortcut, read as a single phrase by screen readers. Defaults to `keys.join(' + ')` (e.g. `'⌘ + K'`) when omitted OR empty — an empty string is not an explicit name, so it takes the default too. Override when the raw keys are unintuitive — e.g. `keys={['⌘', 'K']}` with `aria-label="Open command palette"`. |
+| …native | | | plus native `<span>` attributes |
+
+<!-- props:end -->
+
+- Wrapper carries `aria-label = keys.join(' + ')` (override via prop); inner `<kbd>` and `+` separator are `aria-hidden`.
+
+**When NOT to use:** for inline code use `<Code>`; for chip-shaped text labels use `<Badge>`. `<kbd>` implies keyboard input semantically.
+
+```tsx
+<Tooltip
+  content={
+    <>
+      Save <Kbd keys={['⌘', 'S']} />
+    </>
+  }
+>
+  <Button>Save</Button>
+</Tooltip>
+```
+
+- ❌ Nesting a `<Kbd>` inside a button as its only label. Use the button's `aria-label` and render the Kbd as a separate visual hint.