@streamoid/ui 0.6.17 → 0.6.19

package/dist/docs/ScAccess.md

@@ -0,0 +1,259 @@
+---
+component: ScAccess
+package: "@streamoid/ui"
+category: profile
+status: stable
+renders: div
+tags: [access, permissions, apps, icon-chip, icon-group, entitlements, team-table, read-only]
+related: [ScTableList, ScRole, ScBadges, ScAppField]
+do_not_confuse_with: [ScAppField, ScRole, ScBadges, ScAppSwitchPanel, ScAppCard]
+---
+
+# ScAccess
+
+**A read-only chip holding up to three small icons.** (Its own fallback icons are
+pinned to 20×20; icons *you* pass keep their own size — `Sicon*` default to 24.)
+In the team table it is the
+"what does this user have access to" cell — one chip for the apps they can open,
+another for the permissions they hold. It is **not** a form control despite living
+next to them: there is no state, no click handler, and no label.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need a compact, non-interactive icon group summarising
+  entitlements in a dense table row.
+- **Don't reach for it when:** the user should be able to *change* those
+  entitlements (→ `ScAppField`), you need text (→ `ScBadges`), or you're showing a
+  role name (→ `ScRole`).
+- **Four things that will bite you:**
+  1. Every empty slot defaults to **`<SiconCatalogix />`** ⚠️ — forget a slot and you
+     ship a Catalogix logo.
+  2. `visibleSiconCatalogix` is **misnamed**: it gates the **third slot**, whatever
+     icon you put there.
+  3. **Hard cap of three icons.** Need four? Render two chips (that's what
+     `ScTableList` does).
+  4. **No props spread at all** — no `onClick`, `style`, `title`, `aria-*`, `id`. The
+     icons carry meaning with zero accessible text.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScAccess } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+// Always fill the slots — the defaults are Catalogix logos.
+// Size your own icons: the chip does not resize what you pass in.
+<ScAccess
+  component={<SiconArtifacts size={20} />}
+  component2={<SiconPhotogenix size={20} />}
+  component3={<SiconCatalogix size={20} />}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `component` | `JSX.Element` | `<SiconCatalogix />` | ⚠️ Slot 1. Always rendered. |
+| `component2` | `JSX.Element` | `<SiconCatalogix />` | ⚠️ Slot 2. Always rendered. |
+| `component3` | `JSX.Element` | `<SiconCatalogix />` | ⚠️ Slot 3. Rendered only while `visibleSiconCatalogix` is true. |
+| `visibleSiconCatalogix` | `boolean` | `true` | ⚠️ Misnamed — it is the **slot-3 visibility flag**, not a Catalogix-specific one. Set `false` for a two-icon chip. |
+| `className` | `string` | – | Concatenated onto the root. |
+
+That is the entire API. `IScAccessProps` does **not** extend `HTMLAttributes`, and
+the component spreads nothing onto the root: no `onClick`, `style`, `title`, `id`,
+`data-*`, `aria-*`, no `ref`.
+
+### What renders
+
+| Slots shown | Condition |
+|---|---|
+| 3 | default (`visibleSiconCatalogix` true) |
+| 2 | `visibleSiconCatalogix={false}` |
+| 1 or 0 | impossible — slots 1 and 2 always render (falling back to `SiconCatalogix`) |
+
+Chrome: `--alias-fill-neutral-neutral` fill, `--radius-lg`, `0.5rem` padding,
+`0.75rem` gap, **fixed `2.5rem` height**. The `1.25rem !important` size rules
+(`.siconCatalogixInstance{,2,3}`) are applied **only to the fallback icons** — an
+icon you pass via `component*` keeps whatever size you gave it (see Gotcha 6).
+
+### Recipes
+
+```tsx
+// The team-table pattern: two chips, apps then permissions
+<div style={{ display: "flex", gap: 8 }}>
+  <ScAccess
+    component={<SiconArtifacts size={20} />}
+    component2={<SiconPhotogenix size={20} />}
+    component3={<SiconCatalogix size={20} />}
+  />
+  <ScAccess
+    component={<SiconUserAdd size={20} />}
+    component2={<SiconCoins size={20} />}
+    visibleSiconCatalogix={false}
+  />
+</div>
+
+// Make it accessible + hoverable — wrap it, you can't pass props through
+<div title="Access: Artifax, Photogenix" aria-label="Access: Artifax, Photogenix">
+  <ScAccess component={<SiconArtifacts size={20} />} component2={<SiconPhotogenix size={20} />}
+            visibleSiconCatalogix={false} />
+</div>
+
+// Fewer than 2 entitlements? Don't fake it with a blank element —
+// render nothing, or a text badge instead.
+{apps.length >= 2
+  ? <ScAccess component={icon(apps[0])} component2={icon(apps[1])}
+              component3={apps[2] ? icon(apps[2]) : undefined}
+              visibleSiconCatalogix={!!apps[2]} />
+  : <ScBadges /* … */ />}
+```
+
+---
+
+## 2. Where to use it
+
+- **`ScTableList`** (the CXO team/members table) renders **two** of these per row
+  inside its `accessInfo` region: an apps chip (`SiconArtifacts` +
+  `SiconPhotogenix` + the default Catalogix icon) and a permissions chip
+  (`SiconUserAdd` + `SiconCoins`, third slot hidden). This is its only render site.
+- Any **dense table or list row** that needs an at-a-glance entitlement summary
+  beside `ScProfile` and `ScRole`.
+
+If you are building the CXO members table, use `ScTableList` /
+`ScTableListMobile` and let it place these — don't compose the row by hand.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You need a **read-only** summary of 2–3 entitlements in a fixed-height row.
+- The icons are self-evident brand/permission glyphs and the row already has a
+  header column explaining what the chip means.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The user must **toggle** app access (invite/manage flows) | `ScAppField` (+ `ScCatalogixInvite` / `ScPhtogenixInvite` / `ScArtifaxInvite`) |
+| A role name ("Admin" / "Member") | `ScRole` / `ScRoleMobile` |
+| A status or count chip **with text** | `ScBadges` |
+| More than three icons | two `ScAccess` chips, or your own icon row |
+| A clickable app entry point | `ScAppCard` / `ScAppCardV3` / `ScAppSwitchPanel` |
+| The whole members-table row | `ScTableList` (it composes this) |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScAppField` — the editable app-permission block with toggles and store pickers | `ScAccess` is display-only, no callbacks at all |
+| `ScAppSwitchPanel` — the app switcher you click to navigate | `ScAccess` is inert |
+| `ScRole` — text label for a role | `ScAccess` has no text |
+| `ScBadges` — labelled chip | Same chip shape family, but `ScBadges` carries words |
+| `ScAppCard` / `ScAppListingCard` — full app cards | Different scale entirely |
+
+---
+
+## 4. Why to use it
+
+- **Row-height stability.** The chip is a fixed `2.5rem` tall, so table rows can't
+  jitter when one user has more entitlements than another. (Icon sizing is still on
+  you — the `1.25rem !important` rules cover only the fallback icons.)
+- **Token-correct surface.** `--alias-fill-neutral-neutral` keeps the chip readable
+  against both the base surface and hovered row states, in both themes.
+- **Consistent icon rhythm** — the `0.75rem` gap and `0.5rem` padding match `ScRole`
+  and `ScBadges`, so the three sit together cleanly in one row.
+- **One place to change the entitlement summary shape**, which currently appears
+  twice per team-table row.
+
+---
+
+## Gotchas
+
+**1. Empty slots render a Catalogix logo.** All three slots default to
+`<SiconCatalogix />`. There is no "empty" state.
+
+```tsx
+// WRONG — slot 2 and 3 silently become Catalogix logos
+<ScAccess component={<SiconArtifacts />} />
+
+// RIGHT — fill what you show, hide what you don't
+<ScAccess component={<SiconArtifacts />} component2={<SiconPhotogenix />}
+          visibleSiconCatalogix={false} />
+```
+
+**2. `visibleSiconCatalogix` gates slot 3, not "the Catalogix icon".** Reading the
+name literally will lead you to the wrong conclusion about what disappears.
+
+**3. Only three slots, and slots 1–2 are unconditional.** You cannot render a
+one-icon chip, and you cannot render four. `ScTableList` handles four by rendering two
+chips.
+
+**4. No passthrough props whatsoever.** No `onClick`, `style`, `title`, `aria-label`,
+`data-testid`, `id`, `ref`. Wrap it in a div for tooltips, tests or hit areas.
+
+**5. Zero accessible text.** Screen readers get three unlabelled SVGs. Whatever the
+icons mean, put it on a wrapper (`aria-label` / `title`) or in a visible table header.
+
+**6. Your icons are NOT sized for you.** The `width/height: 1.25rem !important`
+rules live on `.siconCatalogixInstance{,2,3}`, and those classes are attached only to
+the three **fallback** `<SiconCatalogix />` elements. An element you pass via
+`component`/`component2`/`component3` is rendered verbatim — no `cloneElement`, no
+injected class — so `<SiconArtifacts size={32} />` really is 32px and will blow out
+the chip's `2.5rem` height. Size your own icons to `1.25rem` (that is what
+`ScTableList` does, with its own local classes).
+
+**7. `className` is string-concatenated**, so the DOM class list contains a literal
+`undefined` when omitted — don't assert on the class string.
+
+**8. Category note:** it ships in the `SC-Access` folder alongside the form controls
+but it is a **profile/table display** part. Don't try to use it as an "access
+control" input.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Composed internally by `ScTableList` — two chips per row:
+
+```tsx
+// @streamoid/ui  packages/ui/src/SC-tableList/ScTableList.tsx:45
+<ScAccess
+  component={<SiconArtifacts className={styles.siconArtifactsInstance} />}
+  component2={<SiconPhotogenix className={styles.siconPhotogenixInstance} />}
+  className={styles.scAccessInstance}
+/>
+<ScAccess
+  component={<SiconUserAdd className={styles.siconUserAddInstance} />}
+  component2={<SiconCoins className={styles.siconCoinsInstance} />}
+  visibleSiconCatalogix={false}
+  className={styles.scAccessInstance}
+/>
+```
+
+Note the first chip deliberately leaves `component3` unset so slot 3 falls back to
+`SiconCatalogix` — the one place where that surprising default is actually intended.
+If a host ever needs this outside a table, the natural home is a members/team row or
+a workspace-member popup beside `ScProfile` and `ScRole`.
+
+---
+
+## Related
+
+- `ScTableList` / `ScTableListMobile` — the members table that renders these.
+- `ScRole` / `ScRoleMobile` — the role label that sits beside it.
+- `ScBadges` — chip with text when icons aren't enough.
+- `ScAppField` — the editable counterpart for app permissions.
+- `@streamoid/icons` — the `Sicon*` set; check `packages/icons/ICONS.md` for names.

package/dist/docs/ScAppCard.md

@@ -0,0 +1,244 @@
+---
+component: ScAppCard
+package: "@streamoid/ui"
+category: cards
+status: stable
+renders: div
+tags: [card, app, product, row, icon, name, subtitle, invite, appfield, compact]
+related: [ScAppField, ScArtifaxInvite, ScCatalogixInvite, ScPhtogenixInvite, ScAppCardV3, ScAppListingCard]
+do_not_confuse_with: [ScAppCardV3, ScAppListingCard, ScAppCardForCopilot, ScAppSwitchRow]
+used_by: [cxo]
+---
+
+# ScAppCard
+
+**The compact icon + name + subtitle row for an app.** A 200px-wide horizontal
+strip: rounded icon chip on the left, two lines of text on the right, both
+single-line and ellipsised. It has no surface, no border and no hover — it is a
+*label block* meant to be dropped into a bordered parent next to a control.
+
+## TL;DR for agents
+
+- **Reach for it when:** you need to identify an app inside a row that already has
+  its own container and its own control (a toggle, a checkbox, a chevron).
+- **Don't reach for it when:** you want a clickable tile in a grid
+  (→ `ScAppListingCard` for a landing page, `ScAppCardV3` for the app switcher), or
+  a floating glassy card with a wordmark (→ `ScAppCardForCopilot`).
+- **Three things that will bite you:**
+  1. **It has a hardcoded `width: 12.5rem` (200px)** and no way to override it
+     except your own `className`. It does not grow with its parent.
+  2. **All three content props default to Artifax copy** — `appName` defaults to
+     `"Artifax"` and `appDescription` to `"Info about artifax"`.
+  3. It draws **no card chrome at all**: no background, no border, no radius, no
+     hover. If you expected a "card", you want a different component.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScAppCard } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScAppCard
+  appIcon={<SiconArtifacts size={20} />}
+  appName="Artifax"
+  appDescription="Planning & buying"
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `appIcon` | `JSX.Element` | `<SiconArtifacts />` | ⚠️ Real default. Typed `JSX.Element`, not `ReactNode`. Sits in a `radius-xl` chip filled with `--alias-fill-neutral-neutralhover`; the chip has 8px padding and no fixed size, so the icon's own `size` sets it. The chip sets `color: --alias-text-and-icons-primary`, so a `currentColor` icon themes itself. |
+| `appName` | `string` | `"Artifax"` | ⚠️ Real default. `text-sm-medium`, primary, **single line, ellipsised**. |
+| `appDescription` | `string` | `"Info about artifax"` | ⚠️ Real default. `text-xs-regular`, tertiary, **single line, ellipsised**. |
+| `className` | `string` | – | Appended after the internal class. The only way to beat the fixed width. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div (`onClick`, `style`, `title`, `aria-*`, …). |
+
+### Recipes
+
+```tsx
+// The DS idiom — an identity block beside a control, inside your own row
+<div style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+  <ScAppCard
+    appIcon={<SiconCatalog size={20} />}
+    appName="Catalogix"
+    appDescription="Catalog enrichment"
+  />
+  <ScToggleSwitch checked={enabled} onToggle={setEnabled} />
+</div>
+
+// Escape the 200px width when the parent is fluid
+<ScAppCard
+  appIcon={<SiconPhotogenix size={20} />}
+  appName={app.name}
+  appDescription={app.tagline}
+  style={{ width: "100%" }}   // inline style wins over the module class
+/>
+
+// Long names need a tooltip — the text is clipped, not wrapped
+<ScAppCard appName={app.name} appDescription={app.tagline} title={app.name} />
+```
+
+---
+
+## 2. Where to use it
+
+- **Inside the `Sc*Invite` trio.** `ScArtifaxInvite`, `ScCatalogixInvite` and
+  `ScPhtogenixInvite` each render one `ScAppCard` plus a `ScToggleSwitch` — the
+  "enable this product for the invitee" row.
+- **Therefore inside `ScAppField`**, which stacks all three invite rows; that is how
+  it reaches CXO's mobile teams invite/manage popups.
+- Any **settings row** where the left half must identify a product and the right
+  half carries the control.
+
+It is the oldest member of the app-card family, but it is **not superseded by
+`ScAppCardV3`** — they are different shapes (row vs tile) with different jobs.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The parent already owns the surface, border, spacing and interaction, and you
+  only need the icon+name+subtitle unit to look like everywhere else.
+- The text is **short** — both lines are single-line ellipsised by design.
+- 200px is the right width (or you are prepared to override it).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A large clickable product tile on a landing page | `ScAppListingCard` |
+| A tile in the cross-product app switcher (gradient border, `active`) | `ScAppCardV3` |
+| The whole "enable product X" row, toggle included | `ScArtifaxInvite` / `ScCatalogixInvite` / `ScPhtogenixInvite` — or `ScAppField` for all three |
+| A dark glassy card carrying a product **wordmark** | `ScAppCardForCopilot` |
+| A row in the app-switcher flyout | `ScAppSwitchPanel` (+ its item/row parts) |
+| Just the product wordmark art | `ScAppcardLogos` / `ProductWordmark` |
+| A generic option card with a centred title | `ScDefaultCard` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScAppCardV3` — a bordered, glowing, `active`-able tile; prop is `description` | `ScAppCard` has no chrome and uses `appDescription` |
+| `ScAppListingCard` — landing-page tile; props are `title`/`descrp` | This is a 200px row with `appName`/`appDescription` |
+| `ScAppSwitchRow` — a row in the app-switcher overlay | Different family, owns its own hover/active |
+
+Prop-name cheat sheet for the family:
+
+| Component | Title prop | Description prop | Icon prop |
+|---|---|---|---|
+| `ScAppCard` | `appName` | `appDescription` | `appIcon` |
+| `ScAppCardV3` | `appName` | `description` | `appIcon` |
+| `ScAppListingCard` | `title` | `descrp` | `icon` |
+| `ScAppCardForCopilot` | *(none — `product`)* | `subText` | *(none)* |
+
+---
+
+## 4. Why to use it
+
+- **Consistent icon chip.** The 8px-padded `radius-xl` chip filled with
+  `--alias-fill-neutral-neutralhover` is the product's standard "app mark" frame;
+  hand-rolling it is how invite rows drifted out of alignment before.
+- **Ellipsis behaviour is settled.** Both lines are `text-overflow: ellipsis` with
+  `white-space: nowrap`, so a long product name can never reflow the row and shove
+  the adjacent toggle out of place.
+- **The chip sets `color`,** so any `currentColor` `Sicon*` you pass is themed
+  correctly without you naming a token.
+- **Two type ramps already paired** (`text-sm-medium` over `text-xs-regular`,
+  primary over tertiary) — the same pairing used by every other identity row.
+
+---
+
+## Gotchas
+
+**1. Hardcoded `width: 12.5rem`.** The module CSS pins the root to 200px. In a
+fluid row it will not grow, and in a narrow one it will not shrink (it is a flex
+child with default `flex-shrink: 1`, so it *can* be squeezed, which then clips the
+text earlier than you expect).
+
+```tsx
+// WRONG — expecting the card to fill a fluid row
+<div style={{ display: "flex" }}><ScAppCard appName="Catalogix" /></div>
+
+// RIGHT
+<ScAppCard appName="Catalogix" style={{ width: "100%" }} />
+```
+
+**2. The defaults are Artifax copy.** Forget `appName`/`appDescription` and you
+ship `"Artifax"` / `"Info about artifax"` — a real string that has shipped before.
+
+```tsx
+// WRONG — renders "Artifax" / "Info about artifax"
+<ScAppCard appIcon={<SiconPhotogenix size={20} />} />
+
+// RIGHT
+<ScAppCard appIcon={<SiconPhotogenix size={20} />} appName="Photogenix" appDescription="Product imagery" />
+```
+
+**3. It is not a card.** No background, no border, no radius, no shadow, no hover,
+no `cursor`. If you place it on a page with nothing around it, it looks like loose
+text. That is by design — the parent supplies the container.
+
+**4. Both text lines are clipped, never wrapped.** There is no `title` attribute
+wired internally, so the clipped text has no tooltip. Pass `title={appName}`
+yourself if names can be long.
+
+**5. `appIcon` is typed `JSX.Element`.** `ScAppCardV3.appIcon` is `ReactNode`;
+these two are not interchangeable in TypeScript even though they look alike.
+
+**6. `className` is concatenated unguarded** — the root is
+`styles.scAppCard + " " + className`, so omitting `className` puts a literal
+`undefined` class in the DOM. Harmless visually, noisy in snapshot tests.
+
+**7. `appName`/`appDescription` render with a trailing space** (`{appName} ` in the
+JSX). Exact-string assertions must allow for it.
+
+**8. No interaction semantics.** If you attach `onClick`, add `role="button"`,
+`tabIndex={0}` and a key handler — and remember there is no `cursor: pointer`
+either, so you must supply that too.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+It is composed inside the DS by all three invite rows, e.g.
+`packages/ui/src/SC-artifaxInvite/ScArtifaxInvite.tsx:36`:
+
+```tsx
+<ScAppCard
+  appIcon={appIcon || <SiconArtifacts className={styles.siconArtifactsInstance} />}
+  appName={appName}
+  appDescription={appDescription}
+  className={styles.scAppCardInstance}
+/>
+```
+
+Those invite rows are stacked by `ScAppField`, which CXO renders at
+`cxo-dashboard src/app/components/mobile-teams-invite-popup.tsx:162` — so this is
+the path by which `ScAppCard` actually reaches a screen. If you are building a new
+"enable product X" row, reach for `ScAppField` or the invite trio rather than
+composing `ScAppCard` yourself.
+
+---
+
+## Related
+
+- `ScAppField` — the settings field that stacks all three product invite rows.
+- `ScArtifaxInvite` / `ScCatalogixInvite` / `ScPhtogenixInvite` — the rows that wrap
+  this card with a `ScToggleSwitch`.
+- `ScAppCardV3` — the app-switcher tile; different shape, not a newer version of this.
+- `ScAppListingCard` — the landing-page product tile.
+- `ScToggleSwitch` — the control you almost always place beside this card.