@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScPendingAction.md

@@ -0,0 +1,238 @@
+---
+component: ScPendingAction
+package: "@streamoid/ui"
+category: actions
+status: stable
+renders: div
+tags: [pending, invite, cancel, resend, teams, members, action-pair, divider]
+related: [ScButton, ScVDivider, ScTableList, ScRole, ScArtifaxInvite]
+do_not_confuse_with: [ScButton, ScMobileBottomAction, ScSelectionList, ScMenuOptions]
+used_by: [cxo]
+---
+
+# ScPendingAction
+
+**A fixed 160px "Cancel | Resend" button pair.** Two hardcoded `ScButton`s — `Cancel`
+in `variant="error" type="tertiary"` and `Resend` in `variant="tertiary"`, both
+`size="sm"` — separated by a `ScVDivider`. It is the trailing cell of a pending-invite
+row in the CXO Teams table.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are rendering a **pending invite** row and want the exact
+  Cancel/Resend pair used in CXO Teams.
+- **Don't reach for it when:** you need *any* other labels, *any* callbacks per button,
+  or a general action pair — compose two `ScButton`s with a `ScVDivider` yourself.
+- **Three things that will bite you:**
+  1. It takes **no callbacks and no labels**. `className` plus `HTMLAttributes` is the
+     entire API. The only way to know which button was clicked is to inspect
+     `event.target` on a root-level `onClick`.
+  2. Because of (1), it is **keyboard-inaccessible**: the inner `ScButton`s call their
+     own (undefined) `onClick` on Enter/Space, and no click event bubbles to your root
+     handler.
+  3. Fixed `width: 10rem` (160px). It will not adapt to its cell.
+
+> **Category note:** `docs/COMPONENT-CATALOG.md` lists this under the Chat/InChat
+> family. That is wrong — it has nothing to do with the agent runtime. Its one real
+> call site is the CXO Teams pending-invite row, so it is documented here as an
+> **actions** component.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScPendingAction } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScPendingAction />
+```
+
+That already renders "Cancel" and "Resend". Wiring them is the hard part — see the
+recipe.
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `className` | `string` | – | **Always concatenated**, so omitting it puts a literal `undefined` class on the root. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `style`, `data-*`, `aria-*` on the root. **This is the only wiring point.** |
+
+There is no `onCancel`, no `onResend`, no `cancelText`, no `resendText`, no `disabled`,
+no `loading`. Everything below is baked into the render body:
+
+| Rendered child | Fixed configuration |
+|---|---|
+| Button 1 | `text="Cancel"`, `variant="error"`, `type="tertiary"`, `size="sm"` |
+| Divider | `ScVDivider` |
+| Button 2 | `text="Resend"`, `variant="tertiary"`, `size="sm"` |
+
+Both buttons are also passed `icon={<SiconHome />}` — but `styleVariant` is left at its
+default `"default"`, and `ScButton` only renders `icon` for `icon-left`/`icon-right`/
+`icon-only`. **The icons are dead code and never appear.**
+
+### Recipes
+
+```tsx
+// The only way to route the two actions: one root onClick + child hit-testing.
+// This is what CXO does. Child 0 is Cancel, the last child is Resend.
+<ScPendingAction
+  className="shrink-0"
+  onClick={(event) => {
+    event.stopPropagation();                       // the row itself is clickable
+    const target = event.target as HTMLElement | null;
+    if (!target) return;
+    const root = event.currentTarget as HTMLElement;
+    const cancelAction = root.children.item(0) as HTMLElement | null;
+    const resendAction = root.children.item(root.children.length - 1) as HTMLElement | null;
+    if (cancelAction?.contains(target)) return onCancelInvite?.();
+    if (resendAction?.contains(target)) return onResendInvite?.();
+  }}
+/>
+
+// PREFER THIS for anything that isn't literally the CXO Teams row:
+// compose the pair yourself and get real callbacks, labels and keyboard support.
+<div style={{ display: "flex", gap: 4, alignItems: "center" }}>
+  <ScButton text="Cancel" variant="error"    type="tertiary" size="sm" onClick={onCancel} />
+  <ScVDivider />
+  <ScButton text="Resend" variant="tertiary"                size="sm" onClick={onResend} />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **The CXO Teams / members table**, in the "signed on" column of a row whose invite is
+  still pending: the date is replaced by this pair. See
+  `cxo-dashboard src/app/components/teams-content.tsx`.
+- Nowhere else currently. The three invite components (`ScArtifaxInvite`,
+  `ScCatalogixInvite`, `ScPhtogenixInvite`) are the surrounding invite vocabulary, and
+  `ScRole` / `ScTableList` are the row primitives it sits beside.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are rebuilding **the CXO pending-invite row** and want pixel parity with it,
+  including the 160px width that lines the column up with the date text it replaces.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Any other label pair ("Approve/Deny", "Retry/Dismiss") | two `ScButton`s + `ScVDivider` |
+| You need per-button callbacks, disabled or loading states | two `ScButton`s — this component exposes none |
+| A single action | `ScButton`, or `ScOnlyIcon` for a bare icon |
+| A confirm/cancel pair in a modal or drawer footer | two `ScButton`s (`variant="mono"` / `variant="outline"`) |
+| A mobile sticky footer with 1–2 actions | `ScMobileBottomAction` |
+| A menu of row actions behind a `⋯` | `ScPopUpMenu` + `ScMenuOptions` |
+| Accepting/declining an agent suggestion in chat | `ScSelectionList` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScButton` — the actual primitive, with `onClick`, labels and states | This is a frozen pair of two of them |
+| `ScMobileBottomAction` — the mobile sticky action bar | Different surface, real props |
+| `ScSelectionList` — approve/reject **toggles** in the chat transcript | Different family entirely; it *does* have callbacks |
+| Something in the chat/agent family, from the name and the catalog listing | It's a Teams-table cell |
+
+---
+
+## 4. Why to use it
+
+- **Exactly one reason: parity with the CXO Teams row.** The 160px width, the 4px gap,
+  the `error/tertiary` + `tertiary` emphasis pairing and the divider between them are a
+  Figma spec, and this component is that spec frozen.
+- Everything else you would want from it — labels, callbacks, disabled, keyboard — is
+  better served by composing `ScButton` + `ScVDivider` directly, which costs three lines
+  and gives you a correct component.
+
+If you are choosing between this and hand-composing, **hand-compose** unless you are
+editing the CXO Teams table.
+
+---
+
+## Gotchas
+
+**1. There are no callbacks.** Not "they're optional" — they don't exist. The sanctioned
+workaround is a root `onClick` plus DOM hit-testing against `root.children` (see the
+recipe). That couples your call site to the component's child order: if the DS ever adds
+a wrapper or reorders the buttons, your handlers silently swap or stop firing.
+
+**2. It is keyboard-inaccessible.** Each `ScButton` is a `div[role="button"]
+tabIndex={0}` whose Enter/Space handler invokes **its own** `props.onClick` — which is
+`undefined` here — and does not dispatch a DOM click. So focusing "Cancel" and pressing
+Enter does nothing, and your root `onClick` never runs. Keyboard and screen-reader users
+cannot cancel or resend an invite through this component. Treat that as a blocking bug
+for any accessible surface.
+
+**3. Fixed `width: 10rem`.** The root is 160px regardless of content or container. In a
+narrower cell it overflows; in a wider one the two buttons stretch (each is
+`flex: 1 !important`) rather than hugging their labels.
+
+**4. The labels are hardcoded English.** "Cancel" and "Resend" cannot be changed. Not
+localisable.
+
+**5. The `SiconHome` icons never render.** Both buttons get `icon={<SiconHome/>}` but
+`styleVariant` stays `"default"`, and `ScButton` only draws `icon` for the `icon-*`
+variants. Harmless, but don't read the source and assume there are icons.
+
+**6. No pending/disabled state.** While a resend request is in flight you cannot dim or
+block the pair; the user can fire it repeatedly. Guard in your handler.
+
+**7. Omitting `className` puts a literal `undefined` class on the root** — the class list
+is plain string concatenation. Cosmetic, but visible in snapshot tests.
+
+**8. `event.stopPropagation()` is usually required.** The Teams row itself is clickable,
+so without it a Cancel click also opens the member drawer.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/teams-content.tsx:644
+<ScPendingAction
+  className="shrink-0"
+  onClick={(event) => {
+    event.stopPropagation();
+    const target = event.target as HTMLElement | null;
+    if (!target) return;
+    const root = event.currentTarget as HTMLElement;
+    const cancelAction = root.children.item(0) as HTMLElement | null;
+    const resendAction = root.children.item(
+      root.children.length - 1,
+    ) as HTMLElement | null;
+    if (cancelAction && cancelAction.contains(target)) {
+      onCancelInvite?.();
+      return;
+    }
+    if (resendAction && resendAction.contains(target)) {
+      onResendInvite?.();
+    }
+  }}
+/>
+```
+
+That handler is the tell: the DS gap (no `onCancel`/`onResend`) is being paid for at the
+call site.
+
+---
+
+## Related
+
+- `ScButton` — the primitive this freezes two of; use it directly for any variation.
+- `ScVDivider` — the separator between the pair.
+- `ScTableList` / `ScRole` — the Teams row primitives it sits inside.
+- `ScArtifaxInvite` / `ScCatalogixInvite` / `ScPhtogenixInvite` — the invite-flow cards.
+- `ScMobileBottomAction` — the mobile action-pair equivalent, with real props.

package/dist/docs/ScPhtogenixInvite.md

@@ -0,0 +1,275 @@
+---
+component: ScPhtogenixInvite
+package: "@streamoid/ui"
+category: cards
+status: stable
+renders: div
+tags: [invite, app-access, photogenix, toggle, permissions, user-management, settings, onboarding, row]
+related: [ScArtifaxInvite, ScCatalogixInvite, ScAppCard, ScToggleSwitch, ScAccess]
+do_not_confuse_with: [ScArtifaxInvite, ScCatalogixInvite, ScAppCard, ScAppListingCard, ScAppCardV3, ScAppCardForCopilot, ScAccess]
+---
+
+# ScPhtogenixInvite
+
+**The Photogenix "does this user get the app?" row for the invite / edit-user
+modal.** Markup-identical to `ScArtifaxInvite` — `ScAppCard` on the left,
+`ScToggleSwitch` on the right, hairline divider underneath — but with a different
+(worse) props API and no DOM prop forwarding.
+
+> **Note the spelling.** The export and the folder are `ScPhtogenixInvite` /
+> `SC-phtogenixInvite` — missing the **o** in "Photogenix". `ScPhotogenixInvite`
+> does not exist; importing it fails.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need the **Photogenix** row in a per-app access list
+  and want it to match the neighbouring rows exactly.
+- **Don't reach for it when:** the app needs a nested resource picker
+  (→ `ScCatalogixInvite`), or you're writing a new row and can pick the cleaner
+  API (→ `ScArtifaxInvite`, which takes `appName`/`appDescription`/`appIcon` and
+  forwards DOM props).
+- **Five things that will bite you:**
+  1. The content props are **prefixed**: `scAppCardappName`,
+     `scAppCardappDescription`, `scAppCardappIcon`. `appName` is not a prop here.
+  2. ⚠️ It defaults to **ON** (`active = "true"`). Pass `enabled` explicitly.
+  3. ⚠️ The default icon is `SiconArtifacts` — the **Artifax** icon on a
+     Photogenix row. Pass `scAppCardappIcon={<SiconPhotogenix />}`.
+  4. `...props` is destructured and **never spread**. `onClick`, `style`,
+     `data-*`, `id` reach nothing.
+  5. Default description is `"Info about photogenix"` — Figma filler copy.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScPhtogenixInvite } from "@streamoid/ui";
+import { SiconPhotogenix } from "@streamoid/icons";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScPhtogenixInvite
+  enabled={photogenixOn}
+  onToggle={setPhotogenixOn}
+  scAppCardappDescription="AI product photography"
+  scAppCardappIcon={<SiconPhotogenix size={24} />}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `enabled` | `boolean` | – | The real on/off. Overrides `active` whenever defined. **Use this one.** |
+| `active` | `"true"` \| `"false"` | `"true"` | ⚠️ Figma-variant leftover, a *string*. Consulted only when `enabled` is `undefined` — so the row renders **ON** by default. |
+| `onToggle` | `(active: boolean) => void` | – | Fires with the **next** value. Omit it and the switch is inert. |
+| `scAppCardappName` | `string` | `"Photogenix"` | ⚠️ Note the prefix and the lowercase `app`. Passed to `ScAppCard`'s `appName`. |
+| `scAppCardappDescription` | `string` | `"Info about photogenix"` | ⚠️ Real default, and it is placeholder copy. |
+| `scAppCardappIcon` | `JSX.Element` | `<SiconArtifacts />` | ⚠️ The **wrong brand's** icon by default (see Gotcha 3). |
+| `className` | `string` | – | Appended after internal classes. |
+
+There is **no** `...props` pass-through: the interface does not extend
+`React.HTMLAttributes`, and the rest parameter the component collects is never
+applied to the DOM.
+
+### Recipes
+
+```tsx
+// The Photogenix row done properly: explicit state, real copy, right icon
+<ScPhtogenixInvite
+  enabled={access.photogenix}
+  onToggle={(next) => setAccess((a) => ({ ...a, photogenix: next }))}
+  scAppCardappName="Photogenix"
+  scAppCardappDescription="AI product photography"
+  scAppCardappIcon={<SiconPhotogenix size={24} />}
+/>
+
+// Need a click target, a data-attribute or a style? Wrap it — nothing is forwarded.
+<div data-testid="access-photogenix" onClick={onRowClick}>
+  <ScPhtogenixInvite enabled={photogenixOn} onToggle={setPhotogenixOn} />
+</div>
+
+// Drop the divider on the last row of the stack
+<ScPhtogenixInvite
+  enabled={photogenixOn}
+  onToggle={setPhotogenixOn}
+  className={styles.lastRow}          // .lastRow { border-bottom-width: 0 }
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **The invite-user modal's "App access" section**, between the Artifax row and the
+  Catalogix row.
+- **The edit-user / manage-access drawer.**
+- **First-run onboarding** product picker.
+
+It composes `ScAppCard` (`flex: 1`) + `ScToggleSwitch` (`flex-shrink: 0`) and draws
+its own bottom hairline, so stacked rows need no `ScHDivider`.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You want the Photogenix row and you want it visually identical to the rest of the
+  access list (same 16px padding, same divider, same switch).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| You need `onClick` / `style` / `data-*` on the row itself | `ScArtifaxInvite` — same markup, spreads `...props` |
+| The app needs a nested resource picker (stores, projects) | `ScCatalogixInvite` |
+| App icon + name + description with **no** toggle | `ScAppCard` |
+| A read-only "which apps does this user have" indicator | `ScAccess` |
+| A marketing/launcher card for an app | `ScAppListingCard` / `ScAppCardV3` |
+| The app card on the copilot/agent surface | `ScAppCardForCopilot` |
+| Just the switch, in your own row | `ScToggleSwitch` |
+| A labelled boolean with real form semantics | `ScCheckField` / `ScCheckbox` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScArtifaxInvite` — the same row with **clean** prop names (`appName`, `appDescription`, `appIcon`) and DOM prop forwarding | `ScPhtogenixInvite`'s props are `scAppCardapp*` and nothing is forwarded |
+| `ScCatalogixInvite` — header row **plus** a store-access panel when enabled; defaults to **OFF** | This row is header-only and defaults to **ON** |
+| `ScAppCard` — the inner icon/name/description block | This row wraps one |
+| `ScPhotogenixInvite` (correct spelling) | Doesn't exist — the export is `ScPhtogenixInvite` |
+
+Nothing but the default strings ties this component to Photogenix. If you're
+adding a *new* app row, prefer `ScArtifaxInvite` with overridden copy: same
+result, better API.
+
+---
+
+## 4. Why to use it
+
+- **Pixel parity with the rest of the access list** — the flex/divider/padding
+  combination is the actual spec, and it's what keeps a stack of rows from going
+  ragged when one app has a longer description.
+- **The shared toggle.** `ScToggleSwitch` draws the exact Figma on/off SVGs from
+  alias tokens, so it flips with the theme and matches every other switch.
+- **Controlled boolean contract** (`enabled` + `onToggle(next)`), which is what an
+  invite form submits.
+- **It deletes duplicated markup.** `@streamoid/settings` hand-writes this row —
+  including the string `"Info about photogenix"` — with its own local
+  `ToggleSwitch`.
+
+If you're choosing between the trio for a new row, note plainly: this one is the
+weakest of the three (prefixed props, dropped DOM props, wrong default icon). It
+exists because it was generated per-Figma-frame, not because Photogenix needs
+different behaviour.
+
+---
+
+## Gotchas
+
+**1. The content props are prefixed and oddly cased.** `scAppCardappName`, not
+`appName`; `scAppCardappDescription`, not `appDescription`. Written as JSX
+attributes the unprefixed names are a TS error (the interface does not extend
+`HTMLAttributes`, so there is nothing for them to fall into) — but spread from a
+variable they slip past excess-property checking and vanish silently, leaving the
+Photogenix defaults on screen (same mechanism as Gotcha 4).
+
+```tsx
+// WRONG — type error as written; silent no-op if spread from an object
+<ScPhtogenixInvite appName="Photogenix Studio" appDescription="AI photography" />
+
+// RIGHT
+<ScPhtogenixInvite
+  scAppCardappName="Photogenix Studio"
+  scAppCardappDescription="AI photography"
+/>
+```
+
+**2. It renders ON unless you pass `enabled`.** `active` defaults to `"true"`.
+(`ScCatalogixInvite` defaults to `"false"` — the trio is inconsistent.)
+
+```tsx
+// WRONG — invite form starts with Photogenix already granted
+<ScPhtogenixInvite onToggle={setPhotogenixOn} />
+
+// RIGHT
+<ScPhtogenixInvite enabled={photogenixOn} onToggle={setPhotogenixOn} />
+```
+
+**3. The default icon is the Artifax icon.** `scAppCardappIcon` defaults to
+`<SiconArtifacts />`. Ship it and the Photogenix row wears Artifax's mark. There
+is a correct icon: `SiconPhotogenix` (see `packages/icons/ICONS.md`).
+
+**4. `...props` goes nowhere.** The root `<div>` receives only `className`.
+Spreading extra props from a variable type-checks (no excess-property check on
+spreads) and then vanishes at runtime.
+
+```tsx
+// WRONG — the handler and the test id are dropped on the floor
+<ScPhtogenixInvite {...{ onClick: onRowClick, "data-testid": "photogenix-row" }} />
+
+// RIGHT — wrap it
+<div onClick={onRowClick} data-testid="photogenix-row">
+  <ScPhtogenixInvite enabled={photogenixOn} onToggle={setPhotogenixOn} />
+</div>
+```
+
+**5. `active` is a string, not a boolean,** and `enabled` silently wins when both
+are present. Never pass both.
+
+**6. It is stateless.** No `onToggle` → clicking the switch does nothing, because
+`checked` is derived from your props on every render.
+
+**7. You cannot disable the toggle.** `ScToggleSwitch` has a `disabled` prop; this
+row never forwards it and exposes none. For read-only access, render `ScAppCard`
+plus your own indicator.
+
+**8. No keyboard or screen-reader support.** The switch is a `<div onClick>`, not
+an `<input type="checkbox">`; the row has no `role` and no focusable element. Use
+`ScCheckField` if the control must be operable without a mouse.
+
+**9. `styles["active-true"]` doesn't exist.** Only `.active-false` is defined (it
+thickens the divider from 0.5px to 1px), so in the ON state the variant class
+resolves to `undefined` and appears in the class attribute as the literal
+`"undefined"`, as does an omitted `className`. Don't assert on the class list.
+
+**10. Every row draws its own bottom divider,** including the last one. Strip it
+via `className`.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+The surface exists but is hand-rolled in the shared settings package, which
+duplicates this row rather than importing it:
+
+```tsx
+// @streamoid/settings  packages/settings/src/invite-update-modal.tsx:689
+<ToggleSwitch                       // local component, not ScToggleSwitch
+  active={photogenixOn}
+  onClick={() => { setPhotogenixOn(!photogenixOn); markChanged(); }}
+/>
+// …preceded by hand-written markup duplicating ScAppCard, with the literal
+// string "Info about photogenix" (line 685). Local ToggleSwitch: line 84.
+```
+
+That modal (CXO settings → Teams → invite/edit user) is where this component
+belongs.
+
+---
+
+## Related
+
+- `ScArtifaxInvite` — the same row with the cleaner API; prefer it for new rows.
+- `ScCatalogixInvite` — the same row plus a store-access panel when enabled.
+- `ScAppCard` — the icon/name/description block inside it.
+- `ScToggleSwitch` — the switch on the right, standalone.
+- `ScAccess` — read-only app-access icon row.