@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScAppField.md

@@ -0,0 +1,308 @@
+---
+component: ScAppField
+package: "@streamoid/ui"
+category: forms
+status: stable
+renders: div > (label row) + div > [ScArtifaxInvite, ScPhtogenixInvite, ScCatalogixInvite]
+tags: [app-permission, invite, teams, member, toggle, artifax, photogenix, catalogix, store-access]
+related: [ScArtifaxInvite, ScPhtogenixInvite, ScCatalogixInvite, ScCheckField, ScTabField, ScToggleSwitch, ScAppCard]
+do_not_confuse_with: [ScTextField, ScOnlyField, ScAppCard, ScAppSwitchPanel, ScCheckField]
+used_by: [cxo]
+---
+
+# ScAppField
+
+**Not a generic field — the "App permission" block from the invite/manage-member
+form.** It renders a label row plus exactly three hardcoded app rows, in this
+order: **Artifax**, **Photogenix**, **Catalogix** (each an app card with a toggle),
+and when Catalogix is on, its nested store-access list with a search box and a
+checkbox per store.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building the *invite a user* / *manage a user*
+  form and need the standard per-app permission section.
+- **Don't reach for it when:** you want a generic labelled field (→ `ScTextField`),
+  a label + checkbox group (→ `ScCheckField`), or control over which apps appear
+  (→ compose `ScArtifaxInvite` / `ScPhtogenixInvite` / `ScCatalogixInvite`
+  yourself).
+- **Five things that will bite you:**
+  1. The app list is **hardcoded**. No `apps` prop, no children, no reordering,
+     no way to hide an app.
+  2. Every row defaults to **enabled** — omit `artifaxEnabled` /
+     `photogenixEnabled` / `catalogixEnabled` and all three render as ON.
+  3. Enable Catalogix without passing `catalogixStores` and you ship **five
+     placeholder rows literally reading "Pairtext"**.
+  4. The descriptions are placeholder copy: *"Info about artifax"*, *"Info about
+     photogenix"*, *"Info about catalogix"* — and `ScAppField` exposes **no props
+     to change them**.
+  5. The root has no `width`, unlike every other `SC-*Field`. In a flex column
+     you must stretch it yourself (`className="w-full"`).
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScAppField } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+There is no useful "minimal" call — omitting the enabled flags turns everything
+on and omitting `catalogixStores` renders placeholders. The shortest *correct*
+call is:
+
+```tsx
+<ScAppField
+  artifaxEnabled={artifaxOn}
+  onArtifaxToggle={setArtifaxOn}
+  photogenixEnabled={photogenixOn}
+  onPhotogenixToggle={setPhotogenixOn}
+  catalogixEnabled={catalogixOn}
+  onCatalogixToggle={setCatalogixOn}
+  catalogixStores={stores}
+  catalogixSelectedStores={selectedStores}
+  onCatalogixStoreToggle={toggleStore}
+  className="w-full"
+/>
+```
+
+### Props
+
+Extends `React.HTMLAttributes<HTMLDivElement>`; unlisted props are spread onto
+the root div.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `appFieldTitle` | `string` | `"App permission"` | ⚠️ Hardcoded English default; the only label prop. |
+| `artifaxEnabled` | `boolean` | – | ⚠️ `undefined` ⇒ the row falls back to `ScArtifaxInvite`'s own `active="true"` default ⇒ **ON**. |
+| `onArtifaxToggle` | `(active: boolean) => void` | – | Fired by the row's `ScToggleSwitch`. |
+| `photogenixEnabled` | `boolean` | – | ⚠️ Same: `undefined` ⇒ ON. |
+| `onPhotogenixToggle` | `(active: boolean) => void` | – | |
+| `catalogixEnabled` | `boolean` | – | ⚠️ Same: `ScAppField` hardcodes `active="true"` on that row, so `undefined` ⇒ ON **and expanded**. |
+| `onCatalogixToggle` | `(active: boolean) => void` | – | |
+| `catalogixStores` | `{ id: string; name: string }[]` | – | ⚠️ `undefined` ⇒ 5 placeholder rows reading `"Pairtext"`. `[]` ⇒ the "No stores found" empty state. |
+| `catalogixSelectedStores` | `string[]` | – | Ticked stores. Also drives the "N Selected" counter. |
+| `onCatalogixStoreToggle` | `(storeId: string) => void` | – | Called with the store id; **you** own add/remove. |
+| `catalogixSearchValue` | `string` | – | Controlled search text. Filtering is **not** done for you. |
+| `onCatalogixSearchChange` | `(query: string) => void` | – | Receives the raw string. |
+| `className` | `string` | – | Appended to the root class list. |
+
+#### What is fixed and cannot be changed through this component
+
+| Fixed thing | Value |
+|---|---|
+| Rows and order | Artifax → Photogenix → Catalogix |
+| App names | `"Artifax"`, `"Photogenix"`, `"Catalogix"` |
+| App descriptions | `"Info about artifax"`, `"Info about photogenix"`, `"Info about catalogix"` |
+| App icons | Artifax/Catalogix: `SiconArtifacts`; Photogenix: `SiconPhotogenix` |
+| Store-access strings | `"Store access"`, `"N Selected"`, `"Search stores..."` |
+
+### Recipes
+
+```tsx
+// The full invite-form wiring (CXO mobile teams popup)
+<ScAppField
+  appFieldTitle="App permission"
+  artifaxEnabled={artifaxOn}
+  onArtifaxToggle={setArtifaxOn}
+  photogenixEnabled={photogenixOn}
+  onPhotogenixToggle={setPhotogenixOn}
+  catalogixEnabled={catalogixOn}
+  onCatalogixToggle={setCatalogixOn}
+  catalogixStores={stores}
+  catalogixSelectedStores={selectedStores}
+  onCatalogixStoreToggle={(id) =>
+    setSelectedStores((prev) =>
+      prev.includes(id) ? prev.filter((s) => s !== id) : [...prev, id]
+    )
+  }
+  catalogixSearchValue={storeSearch}
+  onCatalogixSearchChange={setStoreSearch}
+  className="w-full shrink-0"
+/>
+
+// YOU must filter — the search box only reports the query
+const visibleStores = useMemo(
+  () => allStores.filter((s) => s.name.toLowerCase().includes(storeSearch.toLowerCase())),
+  [allStores, storeSearch]
+);
+<ScAppField catalogixStores={visibleStores} catalogixSearchValue={storeSearch} … />
+
+// Only two apps, or a different order? Don't use ScAppField — compose the rows.
+<div className="flex flex-col">
+  <ScPhtogenixInvite
+    enabled={photogenixOn}
+    onToggle={setPhotogenixOn}
+    scAppCardappDescription="Generate on-brand product imagery"   // note the prop name
+  />
+  <ScCatalogixInvite
+    enabled={catalogixOn}
+    onToggle={setCatalogixOn}
+    appDescription="Manage catalogue and feeds"
+    stores={stores}
+    selectedStores={selectedStores}
+    onStoreToggle={toggleStore}
+  />
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO mobile teams flows** — `mobile-teams-invite-popup.tsx` and
+  `mobile-teams-manage-popup.tsx`, stacked after `ScTextField` (Email ID),
+  `ScTabField` (Role) and `ScCheckField` (Permission), inside a mobile popup with
+  an `ScButton` footer. It is rendered only for `role === "member"`.
+- Its natural desktop home is the invite/manage-user modal. CXO's desktop
+  `invite-update-modal.tsx` does **not** use it today — it hand-rolls the section
+  — so treat desktop parity as an open migration, not as prior art.
+
+CXO is the only host. Catalogix and Photogenix have their own team screens and do
+not render this.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You are reproducing the **Streamoid invite/manage-member form** exactly as
+  designed, with all three apps present.
+- You want the Catalogix store-access sub-panel (header, counter, search box,
+  checkbox rows) without building it.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A generic labelled input | `ScTextField` (or `ScOnlyField` unlabelled) |
+| A label + a group of checkboxes | `ScCheckField` |
+| A label + a segmented single choice (e.g. Role) | `ScTabField` |
+| One app row, or a subset/reordering of apps | `ScArtifaxInvite` / `ScCatalogixInvite` (real `appName`/`appDescription`/`appIcon`) and `ScPhtogenixInvite` (same three, but named `scAppCardappName`/`scAppCardappDescription`/`scAppCardappIcon`) |
+| A single on/off switch | `ScToggleSwitch` |
+| Showing an app (icon + name + description) with no toggle | `ScAppCard` |
+| Letting the user *switch* to another app | `ScAppSwitchPanel` / `ScAppCardV3` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScTextField` / `ScOnlyField` — the name pattern `Sc*Field` suggests an input; this one is a **permissions block** | `ScAppField` has no input of its own beyond the nested store search |
+| `ScAppCard` — the icon + name + description row itself (composed *inside* each invite row) | `ScAppField` is the whole three-app section |
+| `ScAppSwitchPanel` / `ScAppCardV3` / `ScAppListingCard` — app **navigation/marketing** surfaces | `ScAppField` is app **permission** in a form |
+| `ScCheckField` — label + checkbox list, which is what "app permission" looks like at first glance | `ScAppField` uses toggles and nested store access |
+
+---
+
+## 4. Why to use it
+
+- **Three composite rows for one prop set.** Each row is an `ScAppCard` +
+  `ScToggleSwitch`; the Catalogix row adds a search field and a checkbox list.
+  That is four DS components and ~120 lines of wiring you don't write.
+- **Correct enabled→expanded behaviour.** The Catalogix store panel is mounted
+  only while the app is on, and the "N Selected" counter is derived from
+  `catalogixSelectedStores` — so the counter can't drift from the ticks.
+- **One surface for the permission model.** When a fourth app ships, it lands
+  here once instead of in every host's invite modal.
+- **Token-correct nesting.** The container uses `surface-basesubtle` with
+  `radius-3xl` and forces each row to `align-self: stretch`, which is exactly the
+  case that collapses when hand-rolled inside a constrained flex column.
+
+---
+
+## Gotchas
+
+**1. Everything defaults to ON.** All three rows compute
+`enabled !== undefined ? enabled : active === "true"`, and every `active` default
+in play is `"true"` (Artifax's own default, Photogenix's own default, and
+Catalogix's `active="true"` hardcoded by `ScAppField`).
+
+```tsx
+// WRONG — renders all three apps enabled, Catalogix expanded
+<ScAppField onArtifaxToggle={a} onPhotogenixToggle={p} onCatalogixToggle={c} />
+
+// RIGHT — always pass the three booleans explicitly
+<ScAppField
+  artifaxEnabled={false} onArtifaxToggle={a}
+  photogenixEnabled={false} onPhotogenixToggle={p}
+  catalogixEnabled={false} onCatalogixToggle={c}
+/>
+```
+
+**2. Missing `catalogixStores` renders placeholder rows.** `ScCatalogixInvite`
+falls back to five `ScPairtext` checkbox rows; since they get no `content`, each
+one renders `ScPairtext`'s default label — the literal word **"Pairtext"**. Pass
+`[]` for the real "No stores found" empty state.
+
+**3. The search box does not filter.** It is an `ScOnlyField` reporting the query
+via `onCatalogixSearchChange`. Filter `catalogixStores` yourself.
+
+**4. `onCatalogixStoreToggle` is a signal, not a state update.** It receives only
+the store id — you must toggle membership in `catalogixSelectedStores`.
+
+**5. App names, descriptions and icons are not overridable here.** `ScAppField`
+passes literal strings to the child rows (Photogenix gets
+`"Info about photogenix"` and `SiconPhotogenix`; Artifax and Catalogix fall
+through to their own placeholder copy). If the design has real copy, drop
+`ScAppField` and compose the three `*Invite` components, which *do* expose the copy
+props — `appName`/`appDescription`/`appIcon` on `ScArtifaxInvite` and
+`ScCatalogixInvite`, but `scAppCardappName`/`scAppCardappDescription`/
+`scAppCardappIcon` on `ScPhtogenixInvite` (which also does **not** extend
+`HTMLAttributes`, so it spreads nothing onto its root).
+
+**6. No width.** `.scAppField` is a flex column with `align-items: flex-start`
+and **no `width: 100%`** (unlike `ScTextField`/`ScOnlyField`/`ScTextArea`). Inside
+a constrained flex column it can shrink to content — pass `className="w-full
+shrink-0"` as the CXO call sites do.
+
+**7. The label row always renders,** even with `appFieldTitle=""` — you get an
+empty 24 px row. There is no `labelGroup` switch.
+
+**8. Hardcoded English throughout** (`"App permission"`, `"Store access"`,
+`"N Selected"`, `"Search stores..."`, `"No stores found"`). Not localisable
+without changing the DS.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/mobile-teams-invite-popup.tsx:162
+<ScAppField
+  appFieldTitle="App permission"
+  artifaxEnabled={artifaxOn}
+  onArtifaxToggle={setArtifaxOn}
+  photogenixEnabled={photogenixOn}
+  onPhotogenixToggle={setPhotogenixOn}
+  catalogixEnabled={catalogixOn}
+  onCatalogixToggle={setCatalogixOn}
+  catalogixStores={stores}
+  catalogixSelectedStores={selectedStores}
+  onCatalogixStoreToggle={(id) => {
+    setSelectedStores((prev) =>
+      prev.includes(id) ? prev.filter((s) => s !== id) : [...prev, id]
+    );
+  }}
+  catalogixSearchValue={storeSearch}
+  onCatalogixSearchChange={setStoreSearch}
+  className="w-full shrink-0"
+/>
+```
+
+---
+
+## Related
+
+- `ScArtifaxInvite` / `ScPhtogenixInvite` / `ScCatalogixInvite` — the three rows;
+  use them directly when you need real copy, a subset, or a different order.
+- `ScAppCard` — the icon + name + description unit inside each row.
+- `ScToggleSwitch` — the switch each row renders.
+- `ScCheckField` / `ScTabField` / `ScTextField` — the sibling fields in the same
+  invite form.
+- `ScPairtext` — what each store row is made of.

package/dist/docs/ScAppListingCard.md

@@ -0,0 +1,271 @@
+---
+component: ScAppListingCard
+package: "@streamoid/ui"
+category: cards
+status: stable
+renders: div
+tags: [card, tile, app, product, listing, launcher, grid, service-catalog, cxo]
+related: [ScAppCardV3, ScAppCard, ScDefaultCard, ScStoreCard, ScAppCardForCopilot]
+do_not_confuse_with: [ScAppCard, ScAppCardV3, ScAppCardForCopilot, ScDefaultCard]
+used_by: [cxo]
+---
+
+# ScAppListingCard
+
+**The big product tile in a CXO app-landing grid.** An icon in a rounded chip, a
+title beside it, and a description line underneath — one 24px-padded card that
+scales up and lights its icon chip with a purple→peach gradient on hover.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building a grid of *entry points into a product*
+  (Catalogix / Photogenix / Artifax landing pages in CXO) and each tile is
+  icon + title + one-line description.
+- **Don't reach for it when:** you need the compact app-switcher tile with the
+  gradient border and selected state (→ `ScAppCardV3`), the 200px icon+name row
+  inside a toggle field (→ `ScAppCard`), the dark glassy copilot card
+  (→ `ScAppCardForCopilot`), or a generic "pick one option" card
+  (→ `ScDefaultCard`).
+- **Four things that will bite you:**
+  1. The description prop is **`descrp`**, not `description`. Every sibling card
+     spells it differently. Typo it and you ship the default sentence.
+  2. **All three content props have real defaults** — a missing `icon` renders a
+     24px shopping cart, a missing `title` renders `"Stores"`.
+  3. `cursor: pointer` is baked into the CSS whether or not you pass `onClick`,
+     and there is no `role`/`tabIndex` — you must add both yourself.
+  4. `:hover` applies `transform: scale(1.03)`. In a tight grid the card grows
+     over its neighbours.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScAppListingCard } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScAppListingCard
+  icon={<SiconStores size={24} />}
+  title="Stores"
+  descrp="Centralized product and asset management for every storefront"
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `icon` | `JSX.Element` | `<SiconCart />` | ⚠️ Has a real default — a 24px cart. Typed `JSX.Element`, **not** `ReactNode`, so a `ReactNode`-typed variable needs a cast. Rendered inside a padded chip that has no fixed size; the icon's own `size` decides the chip size. |
+| `title` | `string` | `"Stores"` | ⚠️ Real default. `text-md-medium`, `flex: 1`, no truncation — long titles wrap. |
+| `descrp` | `string` | `"Centralized product and asset management for every storefront"` | ⚠️ Real default, and ⚠️ **spelled `descrp`**. `text-sm-regular`, tertiary, no clamp — long copy grows the card. |
+| `className` | `string` | – | Appended after the internal class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | `onClick`, `style`, `role`, `tabIndex`, `onKeyDown`, `aria-*` all land on the root div. |
+
+### Recipes
+
+```tsx
+// The CXO idiom: a service-catalog entry, made clickable and keyboard-reachable
+<ScAppListingCard
+  icon={<img src={item.imgUrl} alt={item.title} className="w-6 h-6" />}
+  title={item.title}
+  descrp={item.descrp}
+  role="button"
+  tabIndex={0}
+  style={{ width: "100%", height: "100%", cursor: item.pageUrl ? "pointer" : "default" }}
+  onClick={() => item.pageUrl && window.open(item.pageUrl, "_blank", "noopener,noreferrer")}
+  onKeyDown={(e) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      item.pageUrl && window.open(item.pageUrl, "_blank", "noopener,noreferrer");
+    }
+  }}
+/>
+
+// A non-clickable informational tile — kill the inherited pointer cursor
+<ScAppListingCard
+  icon={<SiconInfo size={24} />}
+  title="Coming soon"
+  descrp="Asset pipelines land in the next release."
+  style={{ cursor: "default" }}
+/>
+
+// Equal-height responsive grid (the card has no intrinsic width)
+<div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(280px, 1fr))", gap: 16 }}>
+  {cards.map((c) => (
+    <ScAppListingCard key={c.id} icon={c.icon} title={c.title} descrp={c.descrp}
+      style={{ width: "100%", height: "100%" }} />
+  ))}
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO's per-product landing pages** — `photogenix-content`, `catalogix-content`
+  and `artifax-content` each render a grid of these from the workspace's
+  `serviceCatalog`. This is the component's whole reason for existing.
+- Any **app/product launcher grid** where a tile is one navigable destination.
+
+It composes nothing from the DS — the icon is entirely yours. It is *not* rendered
+inside any other DS component, so it never appears unless you place it.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The tile is a **destination**, not a form control: clicking it navigates or opens.
+- You want a description long enough to read (two-line body copy), which the
+  compact `ScAppCardV3` tile cannot carry as comfortably.
+- The surface is a **page-level grid** with generous space (24px padding, 16px radius).
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The cross-product app switcher grid (5-up, gradient border, `active` tile) | `ScAppCardV3` |
+| A 200px icon + name + subtitle row sitting next to a toggle | `ScAppCard` (that's what `ScAppField` / the `Sc*Invite` trio use) |
+| A dark glassy floating card with a product wordmark and hover arrow | `ScAppCardForCopilot` |
+| "Choose one of these options" in a modal/drawer, centred title + hint | `ScDefaultCard` |
+| A store summary tile (name, product count, status beacon) | `ScStoreCard` |
+| A row in a table rather than a tile in a grid | `ScTableList` / `ScTableHeader` |
+| A workspace, not a product | `ScWorkspaceSwitchCard` / `StreamoidWorkspaceSwitcher` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScAppCardV3` — compact switcher tile, gradient hover border, `active` prop, `description` | `ScAppListingCard` is the large landing tile with `descrp` and a scale-up hover |
+| `ScAppCard` — fixed `width: 12.5rem` horizontal row, prop is `appDescription` | This card is a full-width column tile |
+| `ScAppCardForCopilot` — real `<button>`, requires `product`, renders a wordmark not an icon | This card is a `div` and takes an arbitrary `icon` |
+
+Prop-name cheat sheet for the whole app-card family — the single biggest source of
+silent "why is my text the default?" bugs:
+
+| Component | Title prop | Description prop | Icon prop |
+|---|---|---|---|
+| `ScAppListingCard` | `title` | **`descrp`** | `icon` |
+| `ScAppCard` | `appName` | `appDescription` | `appIcon` |
+| `ScAppCardV3` | `appName` | `description` | `appIcon` |
+| `ScAppCardForCopilot` | *(none — `product` wordmark)* | `subText` | *(none)* |
+| `ScDefaultCard` | `title` | `description` | *(none)* |
+| `ScBriefCard` | *(none)* | `description` | *(none)* |
+
+---
+
+## 4. Why to use it
+
+- **Surface, border, radius and type ramp are tokenised** (`--alias-surface-base`,
+  `--alias-border-subtle`, `--text-text-md-medium-*`), so the tile is correct in
+  both themes without a conditional at the call site.
+- **The hover choreography is already tuned** — background lift, border warm-up,
+  a 1.03 scale and the icon-chip gradient all transition together over 200ms.
+  Hand-rolled tiles in this grid historically drifted apart on every one of those.
+- **One place to change the product-grid look.** CXO renders this on three landing
+  pages; a design tweak ships to all of them at once.
+- **It spreads native div attributes**, so you can bolt on `role`, `tabIndex`,
+  `onKeyDown` and data attributes without wrapping it in another element that
+  would break the grid sizing.
+
+---
+
+## Gotchas
+
+**1. `descrp`, not `description`.** TypeScript will not save you: an unknown extra
+prop on a `HTMLAttributes`-extending interface is only caught for literal objects,
+and even when it errors the runtime behaviour is "render the default sentence".
+
+```tsx
+// WRONG — renders "Centralized product and asset management for every storefront"
+<ScAppListingCard title="Assets" description="Manage your creative assets" />
+
+// RIGHT
+<ScAppListingCard title="Assets" descrp="Manage your creative assets" />
+```
+
+**2. Every content prop has a real default.** Passing `icon={undefined}` (very easy
+when your data model has an optional icon) re-triggers the default and ships a
+shopping cart.
+
+```tsx
+// WRONG — card.icon is optional; when it's undefined you get SiconCart
+<ScAppListingCard icon={card.icon} title={card.title} descrp={card.descrp} />
+
+// RIGHT — decide explicitly
+<ScAppListingCard
+  icon={card.icon ?? <SiconStores size={24} />}
+  title={card.title}
+  descrp={card.descrp}
+/>
+```
+
+**3. `icon` is typed `JSX.Element`, not `ReactNode`.** `ScAppCardV3.appIcon` *is*
+`ReactNode`. If your card model types the icon as `ReactNode`, narrow or cast it
+here — do not "fix" it by widening at the call site with `as any` and forgetting.
+
+**4. It is not keyboard accessible on its own.** No `role`, no `tabIndex`, no key
+handling — but the CSS sets `cursor: pointer` unconditionally, so it *looks*
+clickable. Add `role="button" tabIndex={0} onKeyDown` whenever you pass `onClick`,
+and override `cursor` when you don't.
+
+**5. `:hover` scales the card to 1.03.** In a dense grid the hovered tile overlaps
+its neighbours (there is no `z-index` management). Give the grid enough gap, or
+override `transform` via `className` if the design does not want it.
+
+**6. The hover accents are hardcoded, not tokens.** The hover border is `#ffa16b`
+and the icon chip's hover fill is `linear-gradient(135deg, #6d00db, #ffb88c)`.
+They are identical in dark and light mode — do not expect them to follow a theme
+or a brand override.
+
+**7. No truncation anywhere.** `title` wraps, `descrp` has no line clamp, and the
+card has no fixed height. In a grid, either cap your copy or set
+`height: 100%` on every card (as CXO does) so rows stay even.
+
+**8. `className` is concatenated unguarded.** The root is
+`styles.scAppListingCard + " " + className`, so when you omit `className` the DOM
+gets a literal `undefined` class. Harmless in the browser, noisy in snapshot tests
+and in DOM-diffing assertions.
+
+**9. `title` and `descrp` render with a trailing space** (`{title} ` in the JSX).
+Exact-string DOM assertions must allow for it.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/photogenix-content.tsx:56
+<ScAppListingCard
+  icon={card.icon}
+  title={card.title}
+  descrp={card.descrp}
+  style={{
+    width: "100%",
+    height: "100%",
+    cursor: card.pageUrl ? "pointer" : "default",
+  }}
+  onClick={card.pageUrl ? handleClick : undefined}
+/>
+```
+
+The same call shape appears in `src/app/components/catalogix-content.tsx:56` and
+`src/app/components/artifax-content.tsx:56`.
+
+---
+
+## Related
+
+- `ScAppCardV3` — the compact app-switcher tile (gradient border, `active` state).
+- `ScAppCard` — the 200px icon+name row used inside `ScAppField`'s invite rows.
+- `ScAppCardForCopilot` — dark glassy wordmark card, a real `<button>`.
+- `ScDefaultCard` — centred "choose an option" card with a forced `hover` state.
+- `ScStoreCard` — the store-listing equivalent of this tile.
+- `@streamoid/icons` — the `Sicon*` you pass as `icon`; see `packages/icons/ICONS.md`.