@streamoid/ui 0.6.17 → 0.6.18

package/dist/docs/ScFieldButton.md

@@ -0,0 +1,255 @@
+---
+component: ScFieldButton
+package: "@streamoid/ui"
+category: actions
+status: stable
+renders: div
+tags: [button, ghost-button, inline-action, attach, browse, apply, compact, toolbar, composer]
+related: [ScButton, ScOnlyIcon, ScMenuOptions, ScTextField, ScOnlyField]
+do_not_confuse_with: [ScButton, ScOnlyIcon, ScMenuOptions, ScTabComp]
+used_by: [cxo]
+---
+
+# ScFieldButton
+
+**A 36 px transparent text/icon chip for actions that sit next to a field.**
+No fill and no border at rest; a tertiary label that turns primary and picks up a
+neutral background on hover. Used for the small secondary affordances in a
+composer or field row — "Attach", "Browse", "Apply".
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a low-emphasis, compact action **beside** an
+  input or inside a composer toolbar, and a full `ScButton` would shout.
+- **Don't reach for it when:** it is a real CTA (→ `ScButton`), it needs
+  keyboard/`aria` semantics, or it is a row in a dropdown menu
+  (→ `ScMenuOptions`).
+- **Four things that will bite you:**
+  1. `type="icon-right"` renders the icon **on the LEFT** of the label, and
+     `type="icon-left"` renders it **on the RIGHT**. The names are inverted in the
+     render order — trust this table, not the prop name.
+  2. `icon` defaults to `<SiconHome />` and `text` defaults to `"Button"`.
+  3. Your own icon is **not size-normalised** — the 16 px `!important` rule only
+     applies to the built-in default. Pass a 16 px icon.
+  4. It is a plain `<div>`: no `role`, no `tabIndex`, no Enter/Space, no
+     `disabled` and no disabled styling. `onClick` works; keyboards don't.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScFieldButton } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScFieldButton text="Apply" onClick={handleApply} />
+```
+
+### Props
+
+Extends `React.HTMLAttributes<HTMLDivElement>`; unlisted props (`onClick`,
+`style`, `title`, `data-*`, `aria-*`) are spread onto the root div.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `text` | `string` | `"Button"` | ⚠️ Real default. Rendered for `default` / `icon-left` / `icon-right`; **not** for `only-icon`. A trailing space is appended in the markup. |
+| `icon` | `JSX.Element` | `<SiconHome />` | ⚠️ Real default — forget it on an icon `type` and you ship a house. Only the default gets the 16 px `!important` sizing. |
+| `type` | `"default"` \| `"icon-right"` \| `"icon-left"` \| `"only-icon"` | `"default"` | ⚠️ Controls presence **and side** of the icon — see the table below. |
+| `state` | `"default"` | `"default"` | The only allowed value. The stylesheet also has a `state-hover` skin, but the type won't let you reach it (real `:hover` already works). |
+| `className` | `string` | – | Appended to the root class list. |
+
+#### What each `type` renders, in DOM order
+
+| `type` | DOM order | Visual result |
+|---|---|---|
+| `"default"` | label | text only |
+| `"icon-right"` | **icon → label** | icon on the **left** ⚠️ |
+| `"icon-left"` | **label → icon** | icon on the **right** ⚠️ |
+| `"only-icon"` | icon | icon only, no label |
+
+### Recipes
+
+```tsx
+// Leading icon + label — note type="icon-right" for an icon on the LEFT
+<ScFieldButton
+  type="icon-right"
+  icon={<SiconAttach className="w-4 h-4" color="var(--alias-text-and-icons-tertiary)" />}
+  text="Attach"
+  onClick={handleAttachClick}
+/>
+
+// Trailing icon (e.g. a caret) — type="icon-left"
+<ScFieldButton
+  type="icon-left"
+  icon={<SiconDown size={16} color="var(--alias-text-and-icons-tertiary)" />}
+  text="More"
+  onClick={openMore}
+/>
+
+// Icon only — give it a label for assistive tech, since there is no text node
+<ScFieldButton
+  type="only-icon"
+  icon={<SiconClose size={16} />}
+  role="button"
+  tabIndex={0}
+  aria-label="Clear"
+  onClick={clear}
+  onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") clear(); }}
+/>
+
+// "Disabled" — there is no prop, so gate it yourself
+<ScFieldButton
+  text="Apply"
+  onClick={canApply ? apply : undefined}
+  style={{ opacity: canApply ? 1 : 0.5, pointerEvents: canApply ? "auto" : "none" }}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **Composer / prompt toolbars** — CXO's landing composer puts an "Attach"
+  field button next to the hidden `<input type="file">` and an icon-only
+  `ScButton` for send.
+- **Field rows** — a "Browse", "Generate", "Reset" affordance immediately after
+  an `ScTextField` / `ScOnlyField` (wrap both in a flex row; the button is 36 px
+  and the field is 48 px, so centre them).
+- **Card and panel headers** — a tertiary text action that must not compete with
+  the primary CTA.
+
+CXO is the only host rendering it today.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The action is **secondary**: it modifies the field next to it rather than
+  submitting the form.
+- You want a **transparent** control that only shows a background on hover.
+- 36 px is the right height — this is the compact chip, not a field-height button.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Any real CTA (Save, Invite, Delete, Upgrade) | `ScButton` — variants, sizes, loading, disabled, keyboard |
+| You need `disabled`, a spinner, or a destructive colour | `ScButton` (`state="disabled"`, `loading`, `variant="error"`) |
+| A bare icon affordance with keyboard support | `ScButton` with `styleVariant="icon-only"` |
+| A row inside a dropdown/popup menu | `ScMenuOptions` (+ `ScPopUpMenu`) |
+| A tab in a tab strip | `ScTabComp` / `ScTabs` / `ScTabSwitcher` |
+| Navigation to a route/URL | a real `<a>` / your router's `Link` — this is a `div` |
+| Mobile sticky footer action | `ScMobileBottomAction` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScButton` — the one button primitive (`div[role="button"]`, keyboard, 6 variants × 3 types × 3 sizes) | `ScFieldButton` is a styleless 36 px ghost chip with no states |
+| `ScOnlyIcon` — a 40 px hover square that **always** renders `SiconSettings` and takes no `icon` prop | `ScFieldButton type="only-icon"` is the one that accepts your icon |
+| “field-height, bordered” (as older docs describe it) | it is **36 px and borderless**; it does not line up with a 48 px field unless you centre it |
+| `ScMenuOptions` — visually similar row with icon + label, but built for menus | different padding/hover contract |
+
+---
+
+## 4. Why to use it
+
+- **The hover contract is right.** Background goes to
+  `--alias-fill-neutral-neutraltohover` and the label from
+  `text-and-icons-tertiary` to `-primary` in one step, matching every other
+  tertiary affordance in the product.
+- **Compact geometry that matches the composer spec** — 8/10 px padding around a
+  20 px line box (36 px total) with a 12 px radius.
+- **Cheap.** No variant matrix, no canvas texture, no spinner: a genuinely light
+  component for the many small actions where `ScButton` is overkill.
+
+---
+
+## Gotchas
+
+**1. The icon-side prop names are inverted.** `icon-right` puts the icon before
+the label in the DOM (so, on the left); `icon-left` puts it after. There is no
+`row-reverse` in the stylesheet to undo it. The CXO "Attach" call site relies on
+this inverted behaviour.
+
+```tsx
+// WRONG — expecting a trailing paperclip
+<ScFieldButton type="icon-right" icon={<SiconAttach />} text="Attach" />  // icon is on the LEFT
+
+// RIGHT — trailing icon
+<ScFieldButton type="icon-left" icon={<SiconDown />} text="More" />       // icon is on the RIGHT
+```
+
+**2. `icon` defaults to a home icon and `text` to `"Button"`.**
+
+```tsx
+// WRONG — renders 🏠 + "Button"
+<ScFieldButton type="icon-right" />
+
+// RIGHT
+<ScFieldButton type="icon-right" icon={<SiconAttach className="w-4 h-4" />} text="Attach" />
+```
+
+**3. Your icon is not resized for you.** `.siconHomeInstance { width: 1rem
+!important; height: 1rem !important }` is attached to the *default* icon element
+only. `Sicon*` components default to `size={24}`, so a custom icon renders 50 %
+too large. The inner `.container` is a fixed `height: 1.25rem` with no
+`overflow: hidden`, so the oversized icon **overflows the line box** (the chip stays
+36 px and the row looks misaligned) rather than growing the chip. Pass `size={16}`
+or `className="w-4 h-4"` (as the CXO call site does).
+
+**4. No colour normalisation.** Unlike `ScButton`, the icon is **not** cloned with
+`color="currentColor"`, so it will not follow the label's tertiary→primary hover
+transition. Set the colour explicitly on your icon (usually
+`var(--alias-text-and-icons-tertiary)`); accept that it stays that colour on hover.
+
+**5. It is a `div` with no semantics.** No `role`, no `tabIndex`, no
+Enter/Space handling, no focus ring. Add `role="button" tabIndex={0}` +
+`onKeyDown` yourself if the action matters — or use `ScButton`.
+
+**6. There is no `disabled` prop or skin.** `state` only accepts `"default"`.
+Gate `onClick` and dim it yourself (see the recipe).
+
+**7. `only-icon` renders no text node**, so screen readers get nothing. Always
+pass `aria-label` in that mode.
+
+**8. The radius uses a non-standard token,** `var(--medium-5, 0.75rem)`, not
+`--radius-xl`. If you are auditing tokens, this is a known outlier; don't copy the
+pattern into new components.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/landing-content.tsx:327
+<ScFieldButton
+  icon={
+    <SiconAttach
+      className="w-4 h-4"
+      color="var(--alias-text---icons-tertiary)"
+    />
+  }
+  type="icon-right"
+  text="Attach"
+  onClick={handleAttachClick}
+/>
+```
+
+---
+
+## Related
+
+- `ScButton` — the primitive for anything that is actually a CTA.
+- `ScOnlyIcon` — the confusable icon square (no `icon` prop; avoid).
+- `ScMenuOptions` / `ScPopUpMenu` — the menu-row vocabulary.
+- `ScTextField` / `ScOnlyField` — the fields this button is meant to sit beside.
+- `@streamoid/icons` — pass `size={16}`; see `packages/icons/ICONS.md`.

package/dist/docs/ScFileField.md

@@ -0,0 +1,268 @@
+---
+component: ScFileField
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div
+tags: [file, upload, dropzone, csv, import, progress, attachment, form-field]
+related: [ScImageField, ScProfileImageUpdate, ScTextField, ScFieldButton, ScProgressBar]
+do_not_confuse_with: [ScImageField, ScProfileImageUpdate, ScAppField, ScProgressBar]
+---
+
+# ScFileField
+
+**The generic file-upload form field.** A dashed dropzone with "Click to upload"
+that swaps, once you hand it a `fileName`, into a one-line file row with a file
+icon, an ellipsised name, an optional progress bar and an ✕ clear button. Error
+text renders under either state.
+
+## TL;DR for agents
+
+- **Reach for it when:** a form needs any *non-image* file — a CSV/XLSX feed, a PDF,
+  a ZIP — and you want a filename + progress + error line for free.
+- **Don't reach for it when:** the file is an image you want to preview
+  (→ `ScImageField`), or it's an avatar/profile picture (→ `ScProfileImageUpdate`).
+- **Four things that will bite you:**
+  1. **It says "or drag and drop" but drag-and-drop does not work.** There are no
+     drop handlers and the `<input>` is clipped to 1px. Copy is aspirational.
+  2. It is **fully controlled and stateless**. It never remembers the file you
+     picked — nothing changes on screen until *you* set `fileName`.
+  3. It does **not** extend `HTMLAttributes`. No `style`, no `id`, no `data-testid`,
+     no `onClick` — the props table is the whole API.
+  4. Setting `fileName` **removes the dropzone entirely**. Replacing a file requires
+     a clear first.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScFileField } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+const [file, setFile] = useState<File | null>(null);
+
+<ScFileField
+  label="Feed file"
+  accept=".csv,.xlsx"
+  fileName={file?.name ?? null}
+  onFileSelect={(files) => setFile(files?.[0] ?? null)}
+  onClear={() => setFile(null)}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | – | Small tertiary label above the control. Omit it and the label row is not rendered at all. **Not** wired to the input with `htmlFor` — see Gotcha 6. |
+| `onFileSelect` | `(files: FileList \| null) => void` | – | Fires on `change` with the raw `FileList`. Take `files?.[0]` yourself unless `multiple`. |
+| `accept` | `string` | – | Passed straight to the input's `accept`. When set, also prints a literal `Accepted: {accept}` hint under the dropzone — so pass something human-readable like `".csv,.xlsx"`, not a MIME soup. |
+| `multiple` | `boolean` | – (falsy) | Passed to the input. **`fileName` is still a single string** — you join the names. |
+| `fileName` | `string \| null` | – | **The state switch.** Truthy → file row; falsy → dropzone. |
+| `uploading` | `boolean` | – (falsy) | Shows the progress bar **and hides the clear button**. Also forces the file row even when `fileName` is empty. |
+| `progress` | `number` | `0` | 0–100. Clamped, so out-of-range values are safe. Only visible while `uploading`. |
+| `error` | `string \| null` | – | Red 12px line under the control. Renders in **both** states. |
+| `onClear` | `() => void` | – | The ✕ button. Not rendered while `uploading`. |
+| `className` | `string` | – | Appended after the internal root class. |
+
+There is **no** `...props` spread, no `disabled`, no `required`, no `id`.
+
+### What renders in each state
+
+| `fileName` | `uploading` | You get |
+|---|---|---|
+| falsy | falsy | Dashed dropzone: up-arrow, "**Click to upload** or drag and drop", `Accepted: …` |
+| truthy | falsy | File row: file icon, name (ellipsised), ✕ clear |
+| truthy | truthy | File row: file icon, name, progress bar. **No ✕** |
+| falsy | truthy | File row with an **empty name** and a progress bar — usually a bug in your state |
+
+### Recipes
+
+```tsx
+// Upload with progress, driven by your own XHR/fetch
+<ScFileField
+  label="Catalog export"
+  accept=".csv,.xlsx"
+  fileName={upload.name}
+  uploading={upload.status === "sending"}
+  progress={upload.pct}
+  error={upload.status === "failed" ? upload.message : null}
+  onFileSelect={(files) => files?.[0] && start(files[0])}
+  onClear={() => reset()}
+/>
+
+// Multiple files — you own the summary string
+<ScFileField
+  label="Attachments"
+  multiple
+  fileName={files.length ? files.map((f) => f.name).join(", ") : null}
+  onFileSelect={(fl) => setFiles(Array.from(fl ?? []))}
+  onClear={() => setFiles([])}
+/>
+
+// Client-side validation before you accept the file
+<ScFileField
+  accept=".csv"
+  fileName={name}
+  error={err}
+  onFileSelect={(fl) => {
+    const f = fl?.[0];
+    if (!f) return;
+    if (!f.name.endsWith(".csv")) { setErr("Only .csv is supported"); return; }
+    setErr(null); setName(f.name);
+  }}
+  onClear={() => { setName(null); setErr(null); }}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **Import / feed-upload steps** — the "pick your CSV" step before a mapping screen
+  (`ScMappingCard` is the screen after it).
+- **Inside `ScModal` / `ScDrawer` forms** — it is `width: 100%` and lays out as a
+  column, so it drops into a field stack next to `ScTextField` and `ScAppField`
+  without extra wrapping.
+- **Settings panels** that accept a document rather than an image.
+
+Currently it has **no host call site** — see "In the wild".
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The payload is a **document or data file**, not something you'd show a thumbnail of.
+- You want the DS's filename/progress/error line rather than inventing three more
+  bits of layout per form.
+- Your upload is asynchronous and you have a real percentage to show.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| An image with a square thumbnail preview (workspace logo, cover art) | `ScImageField` |
+| A round avatar with upload + delete icon buttons | `ScProfileImageUpdate` |
+| A "Browse…" button glued to a text input showing a path | `ScTextField` + `ScFieldButton` |
+| A bare progress bar with no file semantics | `ScProgressBar` |
+| Real drag-and-drop | Nothing in the DS does this. Wrap this component in your own `onDrop` container, or build it — see Gotcha 1. |
+| Toggling which apps a user can access | `ScAppField` (unrelated despite "Field") |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScImageField` — same "Click to upload" copy, but image-only (`accept="image/*"` is hardcoded), 120px tall, shows a thumbnail | `ScFileField` is type-agnostic, has progress + error, and shows no preview |
+| `ScProfileImageUpdate` — 100px circle + two icon buttons, avatar-shaped | `ScFileField` is a form row |
+| `ScProgressBar` — the standalone bar | The bar here is internal and only appears while `uploading` |
+
+The three uploaders are **not** variants of each other and share **no** props beyond
+`className`. Even the select callbacks differ in name *and* signature:
+`ScFileField.onFileSelect → FileList | null`, `ScImageField.onFileSelect → File`,
+`ScProfileImageUpdate.onUpload → File`.
+
+---
+
+## 4. Why to use it
+
+- **Two states, one prop.** The dropzone→file-row swap, the ellipsis on long names,
+  the progress track and the error line are 60 lines of markup you don't write.
+- **Theme-correct dashed border.** The dropzone border, hover fill and progress fill
+  are `--alias-*` tokens, so it survives light mode. Hand-rolled dropzones are
+  usually a hardcoded `#3e3e3e` dashed border that vanishes on white.
+- **Keyboard reaches it at all**, unlike its siblings. The input is *clipped*, not
+  `display: none`, and it's wrapped in a real `<label>`, so it stays in the tab order
+  and Space/Enter opens the picker (there is no visible focus ring, though).
+  `ScImageField` and `ScProfileImageUpdate` both use `display: none` + a
+  `div onClick`, so they are mouse-only.
+- **Progress is clamped**, so a runaway percentage can't blow the bar out of the card.
+
+---
+
+## Gotchas
+
+**1. "or drag and drop" is not implemented.** The dropzone has no `onDrop` /
+`onDragOver` / `onDragEnter`, and the `<input type="file">` is positioned absolutely
+at 1×1 with `clip: rect(0,0,0,0)`, so a dropped file lands on the label and nothing
+happens. Either accept the copy as decorative or wrap it yourself:
+
+```tsx
+// If you actually need drop support, own it outside the component
+<div
+  onDragOver={(e) => e.preventDefault()}
+  onDrop={(e) => { e.preventDefault(); onFileSelect(e.dataTransfer.files); }}
+>
+  <ScFileField fileName={name} onFileSelect={onFileSelect} onClear={clear} />
+</div>
+```
+
+**2. It is stateless — nothing happens until you set `fileName`.**
+
+```tsx
+// WRONG — user picks a file, the dropzone stays exactly as it was
+<ScFileField onFileSelect={(f) => upload(f?.[0])} />
+
+// RIGHT
+<ScFileField fileName={name} onFileSelect={(f) => { setName(f?.[0]?.name ?? null); upload(f?.[0]); }} onClear={() => setName(null)} />
+```
+
+**3. No `style`, no `data-*`, no `onClick`.** The interface does **not** extend
+`React.HTMLAttributes`, unlike most of the library. `className` is your only escape
+hatch — spacing has to come from the parent or a CSS class.
+
+**4. `uploading` hides the clear button, so there is no cancel affordance.** If a
+user needs to abort an upload, render your own cancel next to the field.
+
+**5. You cannot replace a file in place.** With `fileName` set, the input is
+unmounted. The user must ✕ first. If "Replace" matters, expose your own button that
+calls `onClear`.
+
+**6. The `label` is decorative, not associated.** It's a sibling `<div>`; the input
+has no `id`, no `aria-label` and no `aria-describedby`. A screen reader announces the
+generic file input and never hears your label, the `Accepted:` hint or the `error`.
+Add your own labelled wrapper if the surface must be accessible.
+
+**7. All copy is hardcoded English** — `"Click to upload"`, `"or drag and drop"`,
+`"Accepted: "`, and the `aria-label="Clear file"`. No label props. Don't use it in a
+localised surface without changing the DS.
+
+**8. `multiple` and `fileName` disagree.** `multiple` lets the user pick five files;
+the row shows one string. Join the names yourself, or the user sees only the first.
+
+**9. `uploading` alone forces the file row.** `uploading` without `fileName` renders
+an empty name beside a progress bar. Always set both.
+
+**10. The file row is `overflow: hidden`.** Nothing you render can escape it — but
+you can't render anything into it anyway; there is no slot.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+More precisely: no host app renders it yet, and it is not an agent-runtime
+component either — it is a form primitive waiting for a consumer. The only live
+render is the DS's own gallery, `apps/docs/pages/form-components-preview.tsx:130`,
+which exercises all four states. It most likely belongs on the **Catalogix feed
+upload step** (the screen immediately before `ScMappingCard`'s Map-Attributes list)
+and in any CXO settings flow that imports a CSV.
+
+---
+
+## Related
+
+- `ScImageField` — the image sibling: thumbnail preview, `image/*` only, no progress.
+- `ScProfileImageUpdate` — round avatar with upload/delete icon buttons.
+- `ScProgressBar` — the standalone progress bar if you need one outside a file row.
+- `ScTextField` + `ScFieldButton` — the "path + Browse" idiom.
+- `ScMappingCard` — the Catalogix screen this field's output feeds into.