@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScGoogleSignIn.md

@@ -0,0 +1,250 @@
+---
+component: ScGoogleSignIn
+package: "@streamoid/ui"
+category: actions
+status: legacy
+renders: div
+tags: [google, sign-in, oauth, sso, login, auth, social-login]
+related: [ScButton, ScTextField]
+do_not_confuse_with: [ScButton, ScAppSwitchPanel, ScAppCard]
+---
+
+# ScGoogleSignIn
+
+**The "Sign in with Google" row.** A raised 1rem-radius bar: 24px logo image on the
+left, "Sign in with Google" in md/500 on the right, inverting to a white fill with
+dark text on hover. That is the whole component — 30 lines, no auth logic.
+
+> **status: legacy.** It ships a **broken default image path**
+> (`googleLogoSrc = "google-logo0.png"`, an asset the package does not contain), has
+> **no `cursor: pointer`**, and is not a button in any semantic sense. CXO's login
+> screen hand-rolls the identical row rather than importing this. Use it only if you
+> pass `googleLogoSrc` and add your own semantics — otherwise copy the CXO pattern
+> (see "In the wild").
+
+## TL;DR for agents
+
+- **Reach for it when:** you want the Figma-exact Google row *and* you already have
+  the "G" asset in your app's bundle.
+- **Don't reach for it when:** you want a real button (→ `ScButton`), or you want
+  Google's own rendered button (→ Google Identity Services' `renderButton`, which is
+  what Google's brand terms actually expect).
+- **Four things that will bite you:**
+  1. ⚠️ `googleLogoSrc` defaults to **`"google-logo0.png"`** — a bare relative path.
+     The package ships no such file, so the default renders a broken image.
+  2. `hover` is the **string** `"true"` / `"false"`, not a boolean.
+  3. **No `cursor: pointer`, no `role`, no `tabIndex`, no keyboard.** It looks
+     clickable and behaves like a `div`.
+  4. The `<img>` has **no `alt`** at all.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScGoogleSignIn } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+The minimum that isn't broken — your own asset, plus the semantics the component
+omits:
+
+```tsx
+import googleLogo from "../assets/google-logo.png";
+
+<ScGoogleSignIn
+  googleLogoSrc={googleLogo}
+  role="button"
+  tabIndex={0}
+  aria-label="Sign in with Google"
+  style={{ cursor: "pointer", width: "100%" }}
+  onClick={handleGoogleSignIn}
+  onKeyDown={(e) => { if (e.key === "Enter" || e.key === " ") handleGoogleSignIn(); }}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `googleLogoSrc` | `string` | `"google-logo0.png"` | ⚠️ **Broken default.** A relative path resolved against the current page URL; no such asset is published in `@streamoid/ui`. Always pass an imported asset or an absolute URL. |
+| `signInText` | `string` | `"Sign in with Google"` | Rendered with a trailing space in the text node. Localise here if you must. |
+| `hover` | `"false"` \| `"true"` | `"false"` | ⚠️ **String union, not boolean.** `"true"` force-renders the inverted (white fill / dark text) skin, for Figma parity and screenshots. Real `:hover` already works — don't wire this to mouse handlers. |
+| `className` | `string` | – | Concatenated between the root class and the variant class. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root `div`. **This is how you attach `onClick`, `role`, `tabIndex`, `style` and `aria-label`** — there are no dedicated props for any of them. |
+
+No `onClick` prop, no `loading`, no `disabled`, no `size`, no `variant`.
+
+### Recipes
+
+```tsx
+// Under an email field, above/below a divider — the real login layout
+<ScTextField label="Work email" value={email} onChange={(e) => setEmail(e.target.value)} />
+<ScButton text="Continue" variant="mono" size="md" onClick={handleLogin} />
+<span>or</span>
+<ScGoogleSignIn
+  googleLogoSrc={googleLogo}
+  role="button"
+  tabIndex={0}
+  aria-label="Sign in with Google"
+  style={{ cursor: "pointer", width: "100%" }}
+  onClick={startGoogleFlow}
+/>
+
+// Screenshot / Figma-parity render of the hover skin
+<ScGoogleSignIn googleLogoSrc={googleLogo} hover="true" />
+
+// Blocking double-submits — the component has no loading/disabled state
+<ScGoogleSignIn
+  googleLogoSrc={googleLogo}
+  signInText={busy ? "Signing in…" : "Sign in with Google"}
+  style={{ cursor: busy ? "default" : "pointer", opacity: busy ? 0.6 : 1 }}
+  onClick={busy ? undefined : startGoogleFlow}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+- **The login / sign-up screen**, as the social alternative under the email +
+  OTP path. That is the only surface it was drawn for.
+- Potentially a **re-auth or "connect Google" row** in settings — but nothing renders
+  it there today.
+
+It composes nothing (no `ScButton` inside — the fill, radius and typography are its
+own CSS), so it does **not** inherit `ScButton`'s hover, focus ring or keyboard
+behaviour.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You need the exact Figma Google row and you're supplying the logo asset yourself.
+- You are comfortable adding `role`/`tabIndex`/`cursor` at the call site.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Any ordinary action, including "Continue with email" | `ScButton` (`variant="mono" \| "outline"`) |
+| A button with an icon on the left | `ScButton styleVariant="icon-left" icon={…}` — gets you real keyboard activation, focus ring, `loading`, and `state="disabled"` |
+| Google's *officially rendered* button (brand-compliant, handles One Tap) | `google.accounts.id.renderButton()` from Google Identity Services — CXO already loads that script for the credential flow |
+| Any other SSO provider (Microsoft, Apple, SAML) | `ScButton` with your own icon — there is no `ScMicrosoftSignIn`, and this component's copy/logo are Google-specific |
+| Switching between Streamoid apps | `ScAppSwitchPanel` / `ScAppSwitchRow` / `ScAppCard*` — unrelated, despite also being logo + label rows |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScButton` — the one button primitive: real keyboard activation, `variant` × `type` × `size` × `state`, `loading`, tokenised focus | `ScGoogleSignIn` is a styled `div` with a hover skin and nothing else |
+| `hover={true}` (boolean) | It's `hover="true"` — a string. `hover={true}` is a type error. |
+| `@streamoid/icons` for the G mark | There is **no** `SiconGoogle`. The logo must come from your app's assets. |
+
+---
+
+## 4. Why to use it
+
+Thin, but real:
+
+- **Token-correct inversion.** The rest state is `surface-raised` with
+  `text-and-icons-primary`; hover flips to `surface-inverse` + `text-and-icons-inverse`,
+  so it stays legible in light mode. The CXO hand-rolled copy instead hardcodes
+  `isDark ? "#f5f5f5" : "#ffffff"` for the label — exactly the bug the DS avoids.
+- **Figma parity** on the numbers you'd otherwise guess: 1rem padding, 0.625rem gap,
+  `radius-3xl`, 24px square logo, md/500 label.
+- **One place to change** if the auth row's look is ever revised.
+
+What it does **not** give you: semantics, keyboard access, a cursor, an asset, a
+loading state, or brand compliance. If you're not getting the token inversion for
+free, `ScButton` is the better trade.
+
+---
+
+## Gotchas
+
+**1. The default logo is a broken image.**
+
+```tsx
+// WRONG — <img src="google-logo0.png"> resolved against the current route; 404s
+<ScGoogleSignIn onClick={signIn} />
+
+// RIGHT — bundle your own asset
+import googleLogo from "../assets/google-logo.png";
+<ScGoogleSignIn googleLogoSrc={googleLogo} onClick={signIn} />
+```
+
+**2. `hover` is a string union.** `hover={true}` fails to compile; `hover` is for
+design parity, not for reacting to the mouse. And `hover="false"` produces **no**
+CSS class (there is no `.hover-false` rule), so the root class list contains the
+literal `undefined` — as it also does when `className` is omitted, which is
+concatenated unguarded. Don't assert on exact class strings.
+
+**3. It is not a button.** Root is a bare `<div>`: no `role="button"`, no `tabIndex`,
+no Enter/Space handling, no focus ring, and — because the CSS has no `cursor` rule —
+**the pointer stays an arrow** even though the background changes on hover. All of
+that has to be supplied through the DOM spread.
+
+**4. The `<img>` has no `alt` attribute.** Screen readers get an unlabelled image
+inside an unlabelled div. Pass `aria-label` on the root.
+
+**5. No `loading` and no `disabled`.** OAuth redirects are slow and this will happily
+fire twice. Gate `onClick` yourself.
+
+**6. No width.** The root is `display: flex` with `justify-content: center` and no
+`width`, so it shrinks to its content. Login screens want full width — pass
+`style={{ width: "100%" }}` or a `className`.
+
+**7. `signInText` renders with a trailing space** (`{signInText} `), so
+`textContent` is `"Sign in with Google "` in tests.
+
+**8. Google brand terms.** Google's identity guidelines constrain the mark, the
+wording and the button's proportions. This component neither ships the asset nor
+enforces the geometry, so compliance is entirely on the caller. If that matters,
+render Google's own button via Google Identity Services instead.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Neither applies, so precisely: **nothing imports it.** Its only render is the DS
+gallery, via the name→component map at `apps/docs/utils/componentMap.tsx:13`; the
+gallery's usage snippet (`apps/docs/utils/componentData.ts:475`) reproduces the broken
+`googleLogoSrc="google-logo0.png"` default. The surface it belongs to already exists
+and hand-rolls the row — this is the pattern to copy or to migrate (abridged; the
+real markup nests two more flex `div`s):
+
+```tsx
+// cxo-dashboard  src/app/components/login-content.tsx:886
+<div
+  className="w-full shrink-0 cursor-pointer"
+  style={googleButtonStyle}
+  onClick={handleGoogleSignIn}
+>
+  {/* … flex wrappers … */}
+  <img alt="Google" src={imgGoogleLogo} /* 24×24 */ />
+  <p className="whitespace-nowrap">Sign in with Google</p>
+</div>
+```
+
+Same geometry, same copy — plus the `cursor-pointer` and `alt` this component is
+missing, and its own bundled PNG (`src/assets/e01edaaf…52.png`, imported at
+`login-content.tsx:23`), which is where the logo has to come from either way.
+
+---
+
+## Related
+
+- `ScButton` — the real button primitive; prefer it for every other action, and for
+  other SSO providers.
+- `ScTextField` — the email field this row sits under on the login screen.
+- `@streamoid/icons` — check `packages/icons/ICONS.md`; there is no Google mark there,
+  so the asset stays in your app.

package/dist/docs/ScGuide.md

@@ -0,0 +1,278 @@
+---
+component: ScGuide
+package: "@streamoid/ui"
+category: overlays
+status: stable
+renders: div
+tags: [guide, tour, walkthrough, onboarding, coachmark, callout, popover-card, next, skip]
+related: [ScHDivider, ScInfoPopup, ScBeacon, ScModal, ScButton]
+do_not_confuse_with: [ScInfoPopup, ScModal, ScDrawer, ScBeacon, ScPopUpMenu]
+used_by: [cxo]
+---
+
+# ScGuide
+
+**The guided-tour step card.** A fixed-width 261px panel: title, description, a
+divider, then a `Skip` / `Next →` action row with the CXO gradient on the Next label
+and an optional centred "1 of 3" counter. It is **only the card** — positioning,
+anchoring, the spotlight and the portal are the host's job.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are building a product walkthrough / coachmark sequence
+  and need the step card.
+- **Don't reach for it when:** you want a "?" tooltip (→ `ScInfoPopup`), a blocking
+  dialog (→ `ScModal`), a pulsing "new" dot (→ `ScBeacon`), or a menu (→ `ScPopUpMenu`).
+- **Four things that will bite you:**
+  1. It is **not** a popover: no anchor, no arrow, no portal, no backdrop, and no
+     `position: fixed`/`absolute` of its own. You position it (CXO uses
+     `position: fixed` + `createPortal`).
+  2. **`title` defaults to `"Title"` and `description` to `"Description"`** — the
+     placeholders ship if you forget.
+  3. Width is a hardcoded **16.3125rem (261px)** with no `width` prop.
+  4. The Next label is **gradient-clipped text** (hardcoded `#d91536 → #ee5e3a`, not
+     tokens), so any colour you set on a custom `nextLabel` node is erased.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScGuide } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScGuide
+  title="Your workspace"
+  description="Everything you create lives here."
+  onSkip={endTour}
+  onNext={goToNextStep}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `title` | `ReactNode` | `"Title"` | ⚠️ Real default. Rendered in a `<p>`, 16px/500, `word-break: break-word`. |
+| `description` | `ReactNode` | `"Description"` | ⚠️ Real default. `<p>`, 14px/400, tertiary colour. |
+| `skipLabel` | `ReactNode` | `"Skip"` | Left action's label. **Still used for width when `hideSkip`** — see Gotcha 5. |
+| `nextLabel` | `ReactNode` | `"Next"` | Right action's label. Painted with the gradient via `background-clip: text`. |
+| `nextIcon` | `ReactNode` | – (falls back to `<SiconRight size={16} strokeWidth={1.5} />` at render, via `nextIcon ?? …`) | ⚠️ Effectively defaulted, so you always get a chevron. Sits in a wrapper whose `color` is hardcoded `#ee5e3a`, so `currentColor` icons come out orange. |
+| `stepLabel` | `ReactNode` | – | "1 of 3" counter. **Hidden entirely when omitted** (`!= null` check). Absolutely centred, `pointer-events: none`. |
+| `onSkip` | `() => void` | – | Skip click. |
+| `onNext` | `() => void` | – | Next click. |
+| `hideSkip` | `boolean` | `false` | Replaces the Skip button with an `aria-hidden`, `visibility: hidden` spacer — the space is still reserved. |
+| `hideNext` | `boolean` | `false` | Removes the Next button entirely (no spacer). |
+| `disabled` | `boolean` | `false` | Sets `disabled` on both buttons and dims them to `opacity: .5`. No spinner. |
+| `className` | `string` | – | Appended (guarded — no stray `"undefined"`). |
+| `style` | `CSSProperties` | – | Applied to the root. Use it to override the fixed width. |
+
+No other DOM props are accepted — the component does **not** spread `...props`, so
+`onClick`, `data-*`, `aria-*` and `id` on the root are unavailable.
+
+### What renders in each configuration
+
+| Config | Left | Centre | Right |
+|---|---|---|---|
+| default | `<button>` Skip | — | `<button>` Next + chevron |
+| `stepLabel="1 of 3"` | Skip | "1 of 3" (absolute, non-interactive) | Next |
+| `hideSkip` | invisible spacer sized to `skipLabel` | `stepLabel` | Next |
+| `hideNext` | Skip | `stepLabel` | — |
+| `hideSkip hideNext` | invisible spacer | `stepLabel` | — (an empty-looking row) |
+| `disabled` | Skip, dimmed + `disabled` | unchanged | Next, dimmed + `disabled` |
+
+### Recipes
+
+```tsx
+// A step sequence with a counter, and "Done ✓" on the last step
+<ScGuide
+  title={step.title}
+  description={step.description}
+  stepLabel={`${index + 1} of ${steps.length}`}
+  nextLabel={isLast ? "Done" : "Next"}
+  nextIcon={isLast ? <CheckIcon /> : undefined}   // undefined → the default chevron
+  hideSkip={isLast}
+  onSkip={skipTour}
+  onNext={isLast ? completeTour : next}
+/>
+
+// Positioning it: the card has no anchoring of its own
+createPortal(
+  <div style={{ position: "fixed", top: popoverTop, left: popoverLeft, zIndex: 10000 }}>
+    <ScGuide title={step.title} description={step.description} onSkip={skip} onNext={next} />
+  </div>,
+  document.body,
+)
+
+// Wider than 261px (there is no width prop)
+<ScGuide style={{ width: 320 }} title="…" description="…" onNext={next} />
+
+// Freeze the card while a step's side effect runs
+<ScGuide title="…" description="…" disabled={isSaving} onNext={saveThenAdvance} />
+```
+
+---
+
+## 2. Where to use it
+
+- **CXO's onboarding walkthrough.** `src/app/components/guided-walkthrough.tsx` owns
+  the step list, resolves each step's target element, paints a spotlight cutout, and
+  portals a `ScGuide` next to the highlighted rect. That wrapper — not this card — is
+  where "Done + checkmark on the last step" logic lives.
+- **Any first-run tour** over an existing screen: sidebar intro, new-feature callout,
+  multi-step "here's how this page works".
+
+### What it composes
+
+- `ScHDivider` between the header and the action row (always — no way to hide it).
+- `SiconRight` as the default `nextIcon`.
+- Two real `<button type="button">` elements (so it is safe inside a `<form>`).
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The content is a **step in a sequence** with forward/skip affordances.
+- You already have (or will build) the positioning + spotlight layer around it.
+- The copy is short: a line of title and one or two lines of description at 261px wide.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| Contextual "?" help on a field | `ScInfoPopup` |
+| A blocking, focused task | `ScModal` |
+| A side panel for create/edit | `ScDrawer` |
+| A pulsing dot that says "new here" | `ScBeacon` (often paired *with* a guide) |
+| A menu of choices | `ScPopUpMenu` + `ScMenuOptions` |
+| A persistent page banner (e.g. low credits) | `CreditWarningBanner` (⚠️ exported without the `Sc` prefix) |
+| An empty-state card with a CTA | your own card + `ScButton` — this one's actions are Skip/Next shaped |
+| A confirm/cancel pair | `ScButton` ×2 — `ScGuide`'s actions are text links, not buttons visually |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScInfoPopup` — small anchored info popover | `ScGuide` is a 261px step card with a tour footer |
+| `ScModal` — has a backdrop, traps focus, centres itself | `ScGuide` has none of that |
+| `ScQuickPrompt` / `ScBriefCard` — chat-runtime suggestion cards | Different family (agent runtime) |
+
+---
+
+## 4. Why to use it
+
+- **The action row is the fiddly part and it's already right.** Skip left, Next right,
+  counter dead-centre regardless of the two buttons' differing widths (absolute
+  centring), and the counter is `pointer-events: none` so it can't swallow a click
+  aimed at the row.
+- **`hideSkip` keeps the layout stable.** The invisible spacer means the Next button
+  doesn't jump left on the final step — the single most common polish bug in a tour.
+- **Real `<button type="button">` elements** with a working `disabled` state: keyboard
+  reachable, no accidental form submits (unlike `ScButton`, which is a `div`).
+- **Token-styled surface**: `--alias-surface-subtleraised` + `--radius-3xl` + the DS
+  divider, so the card sits correctly on both the dark and light canvas.
+- **The gradient is centralised.** The "CXO Linear 2" ramp appears identically here and
+  nowhere else at the call site, so a brand change is one file.
+
+---
+
+## Gotchas
+
+**1. It is not a popover.** No anchor, arrow, portal, z-index or backdrop; the root's
+only positioning is `position: relative` (a containing block for the absolutely-centred
+`stepLabel`), never `fixed`/`absolute`. Dropped into normal flow it renders as a
+261px-wide block where you put it.
+
+```tsx
+// WRONG — appears in the document flow, not next to the thing it describes
+<ScGuide title="Your workspace" description="…" onNext={next} />
+
+// RIGHT — you own positioning
+createPortal(
+  <div style={{ position: "fixed", top, left, zIndex: 10000 }}>
+    <ScGuide title="Your workspace" description="…" onNext={next} />
+  </div>,
+  document.body,
+)
+```
+
+**2. `title` / `description` default to `"Title"` / `"Description"`.** There is no
+required prop, so an incomplete call renders placeholder copy instead of failing.
+
+**3. The Next label is gradient-clipped, so its colour is not yours.**
+`-webkit-text-fill-color: transparent` + `background-clip: text` means any `color` on a
+custom `nextLabel` element is invisible. And the icon wrapper is hardcoded `#ee5e3a`,
+so an icon drawn with `currentColor` comes out orange in both themes.
+
+```tsx
+// POINTLESS — colour is erased by the gradient clip
+<ScGuide nextLabel={<span style={{ color: "var(--alias-text-and-icons-primary)" }}>Done</span>} />
+
+// RIGHT — pass plain text (or an icon you're happy to see orange)
+<ScGuide nextLabel="Done" nextIcon={<CheckIcon />} />
+```
+
+**4. Fixed 261px width, and the card centres its own children.** No `width`/`size`
+prop; override via `style` or `className`. Long titles wrap (`word-break: break-word`)
+rather than truncate, so the card grows *taller*, never wider.
+
+**5. `hideSkip` still reserves the Skip's width.** The spacer renders `skipLabel` with
+`visibility: hidden`, so a long `skipLabel` you thought was hidden still pushes the
+layout. Shorten `skipLabel` if that matters.
+
+**6. `stepLabel` is out of flow.** Absolutely centred with `pointer-events: none`, so a
+long counter can overlap Skip or Next instead of pushing them apart. Keep it to
+"N of M".
+
+**7. `disabled` only dims.** Both buttons get `disabled` + `opacity: .5`; there is no
+loading/spinner state. If the Next action is async, hold `disabled` yourself for the
+duration.
+
+**8. Root DOM props are not spread.** Only `className` and `style` reach the root — no
+`onClick`, `data-testid`, `role="dialog"`, `aria-labelledby`. Wrap it if you need a
+dialog role or a test hook.
+
+**9. The divider is unconditional.** `ScHDivider` always renders between header and
+actions, even with `hideSkip hideNext` (which leaves a rule above an empty row).
+
+**10. Nothing dismisses it.** No close button, no Esc handling, no outside-click. The
+host owns the tour lifecycle — CXO's wrapper wires Skip → `onSkip` and the last step's
+Next → `onComplete`.
+
+---
+
+## In the wild
+
+```tsx
+// cxo-dashboard  src/app/components/guided-walkthrough.tsx:225
+<ScGuide
+  title={step.title}
+  description={step.description}
+  nextLabel={nextLabel}   // step.nextLabel ?? (isLast ? "Done" : "Next")
+  nextIcon={nextIcon}     // step.nextIcon  ?? (isLast ? <DoneIcon /> : undefined)
+  onSkip={handleSkip}
+  onNext={handleNext}
+/>
+```
+
+(That call site wraps the card in a `position: fixed` div inside a
+`createPortal(…, document.body)` with `zIndex: 10000` — the canonical way to use it.)
+
+---
+
+## Related
+
+- `ScHDivider` — rendered inside the card; don't add a second one.
+- `ScInfoPopup` — anchored contextual help, for one-off "?" hints.
+- `ScBeacon` — the pulsing dot that usually *precedes* a guide step.
+- `ScModal` / `ScDrawer` — when the step should block or slide in instead.
+- `ScButton` — for real CTAs; `ScGuide`'s Skip/Next are text-link buttons by design.
+- `@streamoid/icons` — `SiconRight` is the default `nextIcon`; see `packages/icons/ICONS.md`.