@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScHDivider.md

@@ -0,0 +1,213 @@
+---
+component: ScHDivider
+package: "@streamoid/ui"
+category: layout
+status: stable
+renders: div
+tags: [divider, separator, hairline, rule, hr, horizontal, line, section-break]
+related: [ScVDivider]
+do_not_confuse_with: [ScVDivider]
+used_by: [cxo, photogenix, catalogix, artifax]
+---
+
+# ScHDivider
+
+**The horizontal hairline.** A single `<div>` that is 0.5px tall, stretched across
+its parent, painted with `--alias-border-divider`. No margin, no text, no
+semantics — it exists so nobody hand-rolls a `border-top` with a hex colour again.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a horizontal rule between stacked sections, rows,
+  or card regions.
+- **Don't reach for it when:** the rule runs vertically between two columns
+  (→ `ScVDivider`), or you need a semantic `<hr>` in prose.
+- **Three things that will bite you:**
+  1. `IScHDividerProps` only declares `className`. `style`, `onClick`, `data-*`
+     are **TypeScript errors** even though they are spread onto the div at runtime.
+  2. It has **no margin**. Two sections separated by it will look cramped unless the
+     parent supplies the gap.
+  3. In a **flex-row** parent it vanishes (0.5px tall, no width). It needs a block
+     or flex-column parent.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScHDivider } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScHDivider />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `className` | `string` | – | Appended after the internal class. **The only typed prop** — it is your hook for margin, colour and width overrides. |
+| `...props` | *(untyped)* | – | ⚠️ Spread onto the root div at runtime, but `IScHDividerProps` does **not** extend `HTMLAttributes`, so passing `style`/`onClick`/`role`/`data-*` is a compile error. See Gotcha 1. |
+
+### What the stylesheet does
+
+| Declaration | Consequence |
+|---|---|
+| `height: 0.5px` | A hairline, deliberately lighter than a 1px border. |
+| `background-color: var(--alias-border-divider)` | Theme-correct in dark **and** light (both map to `--primitives-neutral-800`). |
+| `align-self: stretch` | Full width inside a flex-column parent, without you setting `width`. |
+| `flex-shrink: 0` | Survives a constrained flex column — it will not be squeezed to nothing. |
+
+### Recipes
+
+```tsx
+// Between sidebar sections — the host supplies the vertical rhythm
+<div className="flex flex-col gap-2">
+  <NavSection />
+  <ScHDivider />
+  <NavSection />
+</div>
+
+// With its own spacing, via className (Tailwind hosts do exactly this)
+<ScHDivider className="my-2" />
+
+// Inside a card, edge-to-edge under the header
+<div className={styles.card}>
+  <CardHeader />
+  <ScHDivider className={styles.cardRule} />
+  <CardBody />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **Sidebars** — between the logo unit, the top items, the nav sections and the
+  footer. CXO's `app-sidebar`, Artifax's `DashboardSidebar` and Catalogix's
+  `LeftMenu` all do this.
+- **Cards** — as the internal rule. Several DS cards already render one for you:
+  `ScCreditsUsageCard`, `ScPlanDetailsCard`, `ScStoreCard`, `ScProfileOptions`,
+  `ScCalendar`, `ScGuide`, `ScArtifaxSidebar`, `ScCatalogixSidebar`, `ScSidebar`.
+  Don't add a second one on top of theirs.
+- **Menus and popovers** — between option groups (`ScProfilePopup` uses it twice).
+- **Notice / locked-state panels** — between body copy and the action row.
+
+Used by all four host apps; it's part of the universal core.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Two stacked regions need visual separation and a full card/border would be too much.
+- You want the divider colour to track the theme without writing a
+  `prefers-color-scheme` branch.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The rule runs vertically between two columns | `ScVDivider` |
+| You need a recolourable rule via a prop | `ScVDivider` (it has a `color` prop; this one does not) |
+| Semantic content separation in prose / a11y-meaningful break | a real `<hr>`, or a `role="separator"` element |
+| A section heading with a rule under it | `ScHeader` (table column label) or your own heading + this divider |
+| Spacing only, with no visible line | a `gap` / margin — don't ship an invisible divider |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScVDivider` — vertical, implemented as a `border-left` on a 0-width div, accepts `color` | `ScHDivider` is a 0.5px-tall background fill and takes no colour prop |
+| `ScHeader` — the uppercase table **column header** label | Despite the name, `ScHeader` is not a header *bar* and draws no rule |
+
+---
+
+## 4. Why to use it
+
+- **One token, one place.** Every rule in the product resolves
+  `--alias-border-divider`, so the day design changes divider contrast (it already
+  did once, `#ededed` → `#d2d2d2` for light-mode AA), all four apps change together.
+- **It survives constrained flex columns.** `flex-shrink: 0` is the reason DS
+  elements don't collapse to zero inside a host's `min-h-0` scroll column — a bug
+  class that has bitten this codebase before.
+- **`align-self: stretch` means no width plumbing.** Hand-rolled rules typically get
+  `width: 100%` which then fights the parent's padding.
+
+---
+
+## Gotchas
+
+**1. The props type is not `HTMLAttributes`.** The component spreads `...props`, but
+the interface declares `className` only — so the compiler rejects everything else.
+
+```tsx
+// WRONG — TS error (Property 'style' does not exist on type 'IScHDividerProps')
+<ScHDivider style={{ margin: "8px 0" }} />
+
+// RIGHT — spacing via a class
+<ScHDivider className="my-2" />
+```
+
+**2. `className` is concatenated unconditionally.** Omitting it produces
+`class="scHDivider undefined"`. Harmless in a browser, but exact-`className`
+assertions in tests will fail.
+
+**3. It disappears in a flex-row parent.** `height: 0.5px` beats `align-self:
+stretch`, and there is no `width`, so a row-direction parent gives it zero area.
+
+```tsx
+// WRONG — nothing renders between the two columns
+<div style={{ display: "flex", flexDirection: "row" }}>
+  <Left /><ScHDivider /><Right />
+</div>
+
+// RIGHT
+<div style={{ display: "flex", flexDirection: "row" }}>
+  <Left /><ScVDivider /><Right />
+</div>
+```
+
+**4. No margin, ever.** The parent owns the rhythm. Use the parent's `gap`, or pass
+a spacing class.
+
+**5. No `color` prop.** Its sibling `ScVDivider` has one; this doesn't. To recolour,
+override `background-color` from your own class.
+
+**6. It carries no semantics.** It is a decorative `<div>` — no `role="separator"`,
+no `<hr>`. Screen readers skip it. That is usually what you want; if it isn't, use
+a real `<hr>`.
+
+**7. Don't double up on DS cards.** `ScPlanDetailsCard`, `ScCreditsUsageCard`,
+`ScStoreCard`, `ScProfileOptions`, `ScGuide` and the sidebar wrappers already render
+their own — adding another gives you two rules 0.5px apart.
+
+---
+
+## In the wild
+
+```tsx
+// artifax  packages/shared/src/components/DashboardSidebar.tsx:875
+<ScHDivider className="my-2" />
+
+// catalogix/dashboard  app/components/LockedScreen/index.jsx:53
+<ScHDivider className={styles["notice-divider"]} />
+
+// cxo-dashboard  src/app/components/app-sidebar.tsx:939
+<ScHDivider />
+```
+
+---
+
+## Related
+
+- `ScVDivider` — the vertical sibling; has a `color` prop and is a `border-left`.
+- `ScHeader` — uppercase table **column** label (not a header bar, despite the name).
+- `ScGuide`, `ScStoreCard`, `ScProfileOptions`, `ScCreditsUsageCard`,
+  `ScPlanDetailsCard` — DS components that already compose one internally.

package/dist/docs/ScHeader.md

@@ -0,0 +1,222 @@
+---
+component: ScHeader
+package: "@streamoid/ui"
+category: layout
+status: stable
+renders: div
+tags: [table, column-header, th, sort, sort-arrow, uppercase, label, caption]
+related: [ScTableHeader, ScBillingHistoryHeader, ScBillingLogsTableHeader, ScReferralTableHeader]
+do_not_confuse_with: [ScTableHeader, ScMobileTopNav, ScSideBarLogoUnit, ScHDivider]
+---
+
+# ScHeader
+
+**One column-header label for a table — not a page header.** It renders an uppercase
+12px muted string plus an optional decorative double-chevron. The name is misleading:
+this is a `<th>`-shaped *cell label*, and it is only ever composed inside the DS's
+table-header rows.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building a bespoke table header row and want the
+  column captions to match every other table in the product.
+- **Don't reach for it when:** you want the whole header row for a known table
+  (→ `ScTableHeader`, `ScBillingHistoryHeader`, `ScBillingLogsTableHeader`,
+  `ScReferralTableHeader`), a page title bar (→ your own heading), or a mobile app
+  bar (→ `ScMobileTopNav`).
+- **Three things that will bite you:**
+  1. `state` defaults to **`"up"`**, so a bare `<ScHeader text="App" />` ships a
+     sort chevron you didn't ask for. Every real call site passes `state="none"`.
+  2. The chevrons are **decoration only** — the component does not sort and wires no
+     handler. `state` is *your* sort indicator to drive.
+  3. `text` defaults to `"Header"`, and CSS uppercases it. Don't `.toUpperCase()` in JS.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScHeader } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScHeader text="App" state="none" />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `text` | `string` | `"Header"` | ⚠️ Has a real default. Rendered with a **trailing space** in the DOM, and uppercased by CSS. |
+| `state` | `"up"` \| `"down"` \| `"none"` | `"up"` | ⚠️ Default draws `SiconDoubleArrowUp`. `"down"` draws `SiconDoubleArrowDown`. `"none"` draws no icon. Purely visual. |
+| `className` | `string` | – | Appended after the internal class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div — this is how you supply `style={{ flex: 1 }}` / fixed widths and `onClick` for sorting. |
+
+### What renders in each state
+
+| `state` | Icon | CSS variant class present? |
+|---|---|---|
+| `"up"` | `SiconDoubleArrowUp` (1rem) | ❌ no `.state-up` rule exists — the class resolves to `undefined` |
+| `"down"` | `SiconDoubleArrowDown` (1rem) | ✅ `.scHeader.state-down .siconDoubleArrowDownInstance` |
+| `"none"` | none | ❌ no `.state-none` rule exists |
+
+### Recipes
+
+```tsx
+// A custom header row — column widths come from YOUR style props
+<div style={{ display: "flex", gap: "var(--spacing-6xl)", alignItems: "center" }}>
+  <ScHeader text="App"      state="none" style={{ flex: 1, alignItems: "flex-start", gap: "0.25rem" }} />
+  <ScHeader text="Activity" state="none" style={{ flex: 1, alignItems: "flex-start", gap: "0.25rem" }} />
+  <ScHeader text="Used by"  state="none" style={{ flexShrink: 0, width: "7.5rem" }} />
+  <ScHeader text="Date"     state="none" style={{ flexShrink: 0, width: "7.5rem" }} />
+</div>
+
+// Driving it as a real sort control (you own the sorting)
+<ScHeader
+  text="Signed on"
+  state={sortKey === "signedOn" ? (sortDir === "asc" ? "up" : "down") : "none"}
+  onClick={() => toggleSort("signedOn")}
+  role="columnheader"
+  aria-sort={sortKey === "signedOn" ? (sortDir === "asc" ? "ascending" : "descending") : "none"}
+  style={{ cursor: "pointer", flex: 1 }}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **Inside DS table-header rows.** It is the atom of `ScTableHeader` (User / Role /
+  Access / Invited by / Signed On | Invite action), `ScBillingHistoryHeader`,
+  `ScBillingLogsTableHeader` and `ScReferralTableHeader`. If your table is one of
+  those, render the parent, not this.
+- **In `@streamoid/settings`** — the billing "credits used" table builds its header
+  row from five `ScHeader`s (App / Activity / Used by / Date / Credits) with inline
+  flex/width styling, because the column set is screen-specific.
+- **Any bespoke table** whose columns don't match an existing DS header component.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You need a **single column caption** with the product's uppercase/muted treatment.
+- You are assembling a header row whose columns are app-specific.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The teams/users table header | `ScTableHeader` (`type="default" \| "pending"`) |
+| Billing history table header | `ScBillingHistoryHeader` |
+| Credit/usage logs table header | `ScBillingLogsTableHeader` |
+| Referral table header | `ScReferralTableHeader` |
+| Catalogix stores table header | `ScCatalogixStoreHeader` |
+| A page/screen title | your own heading element — this is 12px uppercase muted, not a title |
+| A mobile screen's top app bar | `ScMobileTopNav` |
+| A sidebar's logo/app-switcher row | `ScSideBarLogoUnit` |
+| A horizontal rule under a heading | `ScHDivider` |
+| A tab strip | `ScTabs` / `ScTabSwitcher` + `ScTabComp` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTableHeader` — the whole header **row**, composed of `ScHeader` cells | `ScHeader` is one cell |
+| A page header bar (title + actions) | `ScHeader` renders no bar, no background, no actions |
+| A sortable column that actually sorts | `state` is a static indicator; sorting is entirely yours |
+
+The catalog line "Page/section header bar" is wrong — read this file, not that row.
+
+---
+
+## 4. Why to use it
+
+- **Column captions stay identical across every table.** 12px / `line-height-xs` /
+  `--alias-text-and-icons-muted` / uppercase, in one place. Tables built by hand
+  drift within a release.
+- **The sort chevrons are the DS's icons at the DS's size** (1rem, forced with
+  `!important`), so a sorted column looks the same in billing, teams and referrals.
+- **Typed props spread**, so column sizing (`flex: 1` vs a fixed `7.5rem`) stays a
+  call-site decision instead of a fork of the component.
+
+---
+
+## Gotchas
+
+**1. `state="up"` is the default.** A "plain" header is `state="none"`.
+
+```tsx
+// WRONG — renders an up-chevron beside every caption
+<ScHeader text="Credits" />
+
+// RIGHT
+<ScHeader text="Credits" state="none" />
+```
+
+**2. It doesn't sort.** No `onClick`, no `aria-sort`, no cursor change. Add all three
+yourself (props are spread, so they compile).
+
+**3. `text` defaults to `"Header"`.** Forget the prop and you ship the placeholder.
+
+**4. CSS uppercases the label.** `text-transform: uppercase` means `"Used by"`,
+`"used by"` and `"USED BY"` all render identically. Uppercasing in JS only makes the
+source harder to read (and breaks your own `getByText`).
+
+**5. There is a trailing space in the DOM.** The JSX is `{text} `, so
+`el.textContent === "App "`. Whitespace-normalising queries (testing-library's
+`getByText`) are fine; strict equality assertions are not.
+
+**6. `.state-up` and `.state-none` don't exist in the stylesheet.** Only
+`.state-down` has a rule, so `className` ends up containing the literal string
+`"undefined"` for the other two states. Don't use the variant class as a styling or
+test hook.
+
+**7. Omitting `className` also injects `"undefined"`** — the class string is built
+with unguarded concatenation.
+
+**8. No width, no truncation, no `title`.** It's a flex row that sizes to content.
+Long captions push the row wide; column widths are the caller's job.
+
+**9. Not a `<th>`.** It's a div with no table semantics. Inside a real `<table>`,
+render it *inside* a `<th>`; otherwise add `role="columnheader"`.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+It belongs inside table-header rows, and that is where it lives today — in the DS's
+own header components and in the shared settings package:
+
+```tsx
+// npm-components  packages/ui/src/SC-tableHeader/ScTableHeader.tsx:22
+<ScHeader text="User" state="down" className={styles.scHeaderInstance} />
+
+// npm-components  packages/settings/src/billing-content.tsx:1221
+<ScHeader
+  text="App"
+  state="none"
+  style={{ flex: 1, alignItems: "flex-start", gap: "0.25rem" }}
+/>
+```
+
+(CXO renders that settings screen, so `ScHeader` reaches production through
+`@streamoid/settings` rather than through a `cxo-dashboard` call site.)
+
+---
+
+## Related
+
+- `ScTableHeader` — the generic users/teams header row built from these.
+- `ScBillingHistoryHeader` / `ScBillingLogsTableHeader` / `ScReferralTableHeader` —
+  billing-family header rows, also built from these.
+- `ScTableList` / `ScTableListMobile` — the row components that sit under a header.
+- `ScHDivider` — the rule you usually want beneath a header row.

package/dist/docs/ScImageField.md

@@ -0,0 +1,253 @@
+---
+component: ScImageField
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div
+tags: [image, upload, logo, avatar, workspace-image, preview, thumbnail, form-field]
+related: [ScFileField, ScProfileImageUpdate, ScDp, ScTextField]
+do_not_confuse_with: [ScFileField, ScProfileImageUpdate, ScDp, ScIntialProfileCover]
+used_by: [cxo]
+---
+
+# ScImageField
+
+**The image-upload form field.** A labelled 120px-tall panel that reads
+"⬆ Click to upload" until you hand it a preview URL, then swaps to a square
+thumbnail + filename + a red delete icon. It is the workspace-logo picker in CXO's
+mobile settings.
+
+## TL;DR for agents
+
+- **Reach for it when:** a form takes **one image** and the user should see it —
+  workspace logo, brand mark, cover image.
+- **Don't reach for it when:** the file isn't an image or you need progress/error
+  (→ `ScFileField`), or it's a round profile avatar with separate upload/delete
+  buttons (→ `ScProfileImageUpdate`).
+- **Four things that will bite you:**
+  1. `label` defaults to the literal string **`"Label"`**. ⚠️ Always pass one.
+  2. `accept="image/*"` is **hardcoded**. No prop. You cannot restrict to PNG.
+  3. It is **controlled by `imagePreview`** — you create the blob URL (and revoke it).
+  4. Both affordances are **`div`/`svg` with `onClick`**: no button, no `tabIndex`,
+     no `aria-label`. Mouse-only, invisible to a screen reader.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScImageField } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+const [file, setFile] = useState<File | null>(null);
+const [preview, setPreview] = useState<string | null>(null);
+
+<ScImageField
+  label="Workspace profile image"
+  imagePreview={preview}
+  imageName={file?.name}
+  onFileSelect={(f) => { setFile(f); setPreview(URL.createObjectURL(f)); }}
+  onRemove={() => { if (preview) URL.revokeObjectURL(preview); setFile(null); setPreview(null); }}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | `"Label"` | ⚠️ Has a real default — forget it and you ship the word "Label". Always rendered (unlike `ScFileField`, there is no "no label" path). |
+| `imagePreview` | `string \| null` | – | **The state switch.** Truthy → preview row; falsy → upload panel. A blob URL or a remote URL. |
+| `imageName` | `string \| null` | – | Filename beside the thumbnail. ⚠️ Falls back to the literal `"image"` when empty. |
+| `onFileSelect` | `(file: File) => void` | – | A **single `File`**, not a `FileList`. Only fires when a file was actually chosen. The input's value is reset afterwards, so re-picking the same file fires again. |
+| `onRemove` | `() => void` | – | The red trash icon in the preview row. `stopPropagation` is already called for you. |
+| `className` | `string` | – | Appended after the root class. |
+
+Extra DOM props are **not** accepted (the interface does not extend
+`HTMLAttributes`) — no `style`, no `data-*`, no `id`, no `onClick`.
+
+### What renders in each state
+
+| `imagePreview` | You get |
+|---|---|
+| falsy | 7.5rem panel, centred `SiconUpload` + "Click to upload", whole panel clickable |
+| truthy | 7.5rem panel: square `object-fit: cover` thumbnail, `imageName` (ellipsised), red `SiconDelete`. **The panel itself is no longer clickable.** |
+
+### Recipes
+
+```tsx
+// Editing an existing workspace: seed the preview from the server URL
+<ScImageField
+  label="Workspace profile image"
+  imagePreview={newPreview ?? workspace.logoUrl ?? null}
+  imageName={newFile?.name ?? workspace.logoName}
+  onFileSelect={handleFileSelect}
+  onRemove={handleRemoveImage}
+  className="w-full shrink-0"
+/>
+
+// Enforcing a stricter type / size than the hardcoded image/*
+<ScImageField
+  label="Brand logo (PNG, under 2 MB)"
+  imagePreview={preview}
+  onFileSelect={(f) => {
+    if (f.type !== "image/png") return setError("PNG only");
+    if (f.size > 2_000_000) return setError("Under 2 MB please");
+    setError(null); setPreview(URL.createObjectURL(f));
+  }}
+  onRemove={clear}
+/>
+{error && <span style={{ color: "var(--alias-text-and-icons-error)" }}>{error}</span>}
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO mobile settings** — the create-workspace and manage-workspace bottom sheets,
+  stacked directly under a `ScTextField` for the workspace name.
+- **Any `ScModal` / `ScDrawer` form** that takes a logo or cover: it is
+  `width: 100%`, `flex-direction: column`, and matches `ScTextField`'s label
+  typography and 0.25rem label gap, so a field stack lines up with no extra work.
+- Anywhere a **workspace / brand logo** is picked. That is the shape CXO uses it in,
+  and the only shape it is designed for — one image, one preview.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Exactly **one image**, and seeing it matters (a logo the user must confirm).
+- The surrounding form already uses `ScTextField` — this is the matching image row.
+- You are happy owning the blob URL lifecycle and any validation.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A non-image file, or you need upload progress / an error line | `ScFileField` |
+| A round **profile avatar** with initials fallback and separate upload + delete icon buttons | `ScProfileImageUpdate` |
+| Just *displaying* an existing image/initials (no upload) | `ScDp` (`variant="workspace" \| "profile"`) or `ScIntialProfileCover` |
+| Multiple images / a gallery | Nothing in this family — `ScMediaSelect` / `ScMediaApproval` exist but are **chat-runtime** components, not form fields |
+| Restricting to a specific image type at the OS picker level | Nothing — `accept` is hardcoded; validate in `onFileSelect` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScFileField` — same "Click to upload" copy, dashed border, has `accept`, `multiple`, `uploading`, `progress`, `error`, and gives you a `FileList` | `ScImageField` is image-only, has none of those, and gives you a single `File` |
+| `ScProfileImageUpdate` — 100px circle, `initials` fallback, two `ScButton`s | `ScImageField` is a rectangular labelled form row |
+| `ScDp` / `ScIntialProfileCover` — read-only avatar renderers | Neither uploads anything |
+
+The three uploaders (`ScFileField`, `ScImageField`, `ScProfileImageUpdate`) share
+**no** props beyond `className`, and their select callbacks differ:
+`ScFileField → FileList | null`, `ScImageField → File`, `ScProfileImageUpdate → File`.
+
+---
+
+## 4. Why to use it
+
+- **Label + control + preview in one prop set.** The 0.25rem label gap, tertiary
+  label colour, 1rem radius panel and 1:1 `object-fit: cover` thumbnail all match
+  `ScTextField` and `ScDp` without you measuring anything.
+- **The input is already reset after each pick** (`e.target.value = ""`), so the
+  classic "user re-selects the same file and nothing fires" bug is handled.
+- **Theme-correct surfaces.** Panel fill, label and text are `--alias-*` tokens; the
+  delete icon uses `--alias-text-and-icons-error`, so it is the same red as every
+  other destructive affordance.
+- **One place to fix.** The a11y gaps below are DS bugs — fixing them here fixes
+  every consumer, which is not true of a hand-rolled `<input type="file">`.
+
+---
+
+## Gotchas
+
+**1. `label` defaults to `"Label"`.**
+
+```tsx
+// WRONG — renders the word "Label" above the panel
+<ScImageField imagePreview={preview} onFileSelect={pick} />
+
+// RIGHT
+<ScImageField label="Workspace profile image" imagePreview={preview} onFileSelect={pick} />
+```
+
+**2. `accept="image/*"` is hardcoded and there is no prop for it.** PNG-only or
+size limits must be enforced in your `onFileSelect` *after* the user has picked.
+
+**3. It's controlled — nothing appears until `imagePreview` is truthy.** The
+component never derives a preview from the `File` you were handed.
+
+```tsx
+// WRONG — user picks an image, the panel still says "Click to upload"
+<ScImageField label="Logo" onFileSelect={(f) => setFile(f)} />
+
+// RIGHT
+<ScImageField label="Logo" imagePreview={preview} onFileSelect={(f) => { setFile(f); setPreview(URL.createObjectURL(f)); }} />
+```
+
+**4. You must revoke the blob URL.** The component creates nothing and cleans up
+nothing. Call `URL.revokeObjectURL(preview)` in `onRemove` and on unmount, or you
+leak.
+
+**5. You cannot replace the image by clicking the preview.** `onClick` sits only on
+the upload panel; in the preview state the panel is inert. The user must delete
+first. Add your own "Replace" control if that flow matters.
+
+**6. Mouse-only, and silent to assistive tech.** The upload panel is a
+`div onClick` with no `role`, no `tabIndex`, no `aria-label`; the delete affordance is
+the raw `SiconDelete` **svg** with an `onClick` — also unfocusable. The `<img>` has
+`alt="preview"` hardcoded, and the `<input>` is `display: none` (so, unlike
+`ScFileField`, it can't be reached by keyboard either). Tab order skips the whole
+component.
+
+**7. `imageName` falls back to `"image"`.** An uploaded file with no name prop shows
+the literal word "image" — pass `file.name`.
+
+**8. Fixed 7.5rem (120px) height, both states.** Not a prop. A tall portrait image is
+cropped to a square via `object-fit: cover` and `aspect-ratio: 1`; there is no
+"fit" mode.
+
+**9. `className` is concatenated with a space even when undefined,** so the root
+class list can contain a stray empty segment. Harmless, but don't assert on exact
+`className` strings in tests.
+
+**10. Hardcoded English:** `"Click to upload"`, the `"image"` fallback, `alt="preview"`.
+No label props for any of them.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-settings-create-workspace-popup.tsx:116
+<ScImageField
+  label="Workspace profile image"
+  imagePreview={imagePreview}
+  imageName={imageFile?.name}
+  onFileSelect={handleFileSelect}
+  onRemove={handleRemoveImage}
+  className="w-full shrink-0"
+/>
+```
+
+The same call shape appears in
+`cxo-dashboard src/app/components/mobile-settings-manage-workspace-popup.tsx:140`.
+CXO's `handleFileSelect` is the canonical pattern:
+`setImageFile(file); setImagePreview(URL.createObjectURL(file));` with
+`URL.revokeObjectURL` in `handleRemoveImage`.
+
+---
+
+## Related
+
+- `ScFileField` — non-image sibling; adds `accept`, `multiple`, `uploading`, `progress`, `error`.
+- `ScProfileImageUpdate` — round avatar editor with upload + delete icon buttons.
+- `ScDp` / `ScIntialProfileCover` — read-only avatar/initials renderers for the value once saved.
+- `ScTextField` — the field this one is almost always stacked with.