@streamoid/ui 0.6.16 → 0.6.18

package/dist/docs/ScSidebarProfile.md

@@ -0,0 +1,231 @@
+---
+component: ScSidebarProfile
+package: "@streamoid/ui"
+category: sidebar
+status: legacy
+renders: div
+tags: [sidebar, profile, footer, avatar, user, legacy, placeholder]
+related: [ScProfile, StreamoidSidebar, ScProfilePopup, ScProfileOptions, ScDp]
+do_not_confuse_with: [ScProfile, ScProfileOptions, ScProfilePopup, ScProfileSettingsComp, ScProfileV2Mobile, ScIntialProfileCover]
+---
+
+# ScSidebarProfile
+
+**Legacy. Superseded by `StreamoidSidebar`'s `profile` prop.** A hover-able padded
+wrapper whose only job was to place a `ScProfile` in the old sidebar footer — and it
+renders that `ScProfile` **with no props at all**, so it always shows
+`"Chris Hemsworth" / "Kepler workspace"` and a broken `profile-image0.png`.
+
+## TL;DR for agents
+
+- **Reach for it when:** never. There is no way to pass a real user through it.
+- **Reach for this instead:** `StreamoidSidebar`'s
+  `profile={{ name, subtitle, avatar, onClick }}` for a rail footer, or `ScProfile`
+  directly if you just want the avatar + two-line identity block.
+- **Three things that will bite you:**
+  1. ⚠️ **There is no `name`, `subText` or `profileImage` prop.** The placeholder
+     identity is unavoidable.
+  2. `variant="collapsed"` does **not** collapse the inner `ScProfile` — the name and
+     subtitle still render, inside a 3 rem-wide box.
+  3. The root is a `<div>` with a hover background but no `role`/`tabIndex` — it looks
+     clickable and isn't, unless you wire it yourself.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSidebarProfile } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+// This is the whole API. The content is fixed.
+<ScSidebarProfile variant="expanded" onClick={openProfilePopup} />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `state` | `"default"` \| `"hover"` | `"default"` | `"hover"` force-renders the `fill-neutral-neutral` background (Figma parity). Real `:hover` already does this. |
+| `variant` | `"expanded"` \| `"collapsed"` | `"expanded"` | `expanded` = `align-self: stretch`, 8 / 12 px padding. `collapsed` = fixed `width: 3rem`, 8 px padding, and grows to `height: 3rem` on hover. |
+| `className` | `string` | – | Concatenated onto the root. ⚠️ Unguarded — omitting it puts a literal `undefined` in the class list. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | **Is** spread onto the root, so `onClick`, `style`, `aria-*`, `data-*` work. |
+
+There is deliberately **nothing else**. The child is a hardcoded
+`<ScProfile className={styles.scProfileInstance} />`.
+
+### What renders in each variant
+
+| | `expanded` | `collapsed` |
+|---|---|---|
+| Box | stretches to the rail width, `radius-3xl` | fixed 48 px wide |
+| `ScProfile` | avatar + name + subText | avatar + **name + subText still rendered**, squeezed into 48 px |
+| Hover | `fill-neutral-neutral` | `fill-neutral-neutral` + `height: 3rem` |
+
+### Recipes
+
+None worth having. Here is what replaces it:
+
+```tsx
+// A rail footer with a real user — StreamoidSidebar owns the profile row
+<StreamoidSidebar
+  expanded={expanded}
+  onToggle={() => setExpanded((v) => !v)}
+  config={config}
+  iconMap={iconMap}
+  profile={{
+    name: user.fullName,
+    subtitle: workspace.name,
+    avatar: <img src={user.photoUrl} alt="" />,
+    onClick: openProfilePopup,
+  }}
+  toggleInProfile          // profile + a separate collapse button, no version footer
+/>
+
+// Or, if you only want the identity block itself
+<ScProfile
+  name={user.fullName}
+  subText={workspace.name}
+  profileImage={user.photoUrl}
+  collapsed={expanded ? "false" : "true"}
+/>
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere. Its only render site in the whole codebase is inside the legacy `ScSidebar`
+(`src/SC-Sidebar/ScSidebar.tsx:134` and `:243`), which is itself unused.
+
+The current rail footer is built by `StreamoidSidebar` from its `profile` prop
+(optionally with `toggleInProfile` to put the collapse button beside it), and by
+`ScCatalogixSidebar` / `ScArtifaxSidebar` from their own `profile` configs.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- Never.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| The profile row in a real sidebar footer | `StreamoidSidebar`'s `profile` prop (or `ScCatalogixSidebar` / `ScArtifaxSidebar`) |
+| Just the avatar + name + subtitle block, with real data | `ScProfile` (`name`, `subText`, `profileImage`, `collapsed`) |
+| Just the avatar | `ScDp` |
+| The popup that opens when you click the footer | `ScProfilePopup` |
+| The menu rows inside that popup | `ScProfileOptions` |
+| The settings-page profile form | `ScProfileSettingsComp` |
+| A mobile profile screen | `ScProfileV2Mobile` |
+| The initials/cover block for a user with no photo | `ScIntialProfileCover` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScProfile` — the actual identity block, **with** `name` / `subText` / `profileImage` / `collapsed` props | `ScSidebarProfile` is a props-less wrapper around it |
+| `ScProfileOptions` — the list of actions (Settings, Theme, Log out) inside the profile popup | not a footer row |
+| `ScProfilePopup` — the whole floating popup | not a footer row |
+| `ScProfileSettingsComp` — the settings-page profile editor | different surface |
+| `ScProfileV2Mobile` — the mobile twin | different surface |
+| `ScIntialProfileCover` — initials avatar / cover | different job |
+
+Six profile-ish exports (`ScProfile`, `ScProfileOptions`, `ScProfilePopup`,
+`ScProfileSettingsComp`, `ScProfileImageUpdate`, `ScProfileV2Mobile`) plus this
+`ScSidebarProfile` — and this one is the only one you should never use. Read the table
+before picking.
+
+---
+
+## 4. Why to use it
+
+You wouldn't. What it demonstrates that's still correct:
+
+- The rail footer's hover affordance is a **background fill**
+  (`--alias-fill-neutral-neutral`), not a border or an opacity change.
+- Collapsed, the row is pinned to `width: 3rem` (48 px) with its height left to the
+  content, and `:hover` adds an explicit `height: 3rem` so the hovered box reads as a
+  48 × 48 square like the collapsed nav squares.
+- The 8 / 12 px padding + `radius-3xl` matches `ScSidebarMenu`, so the footer sits on
+  the same rhythm as the nav rows above it.
+
+Everything else — real identity, click target, popup wiring, keyboard access — you
+have to supply, and `StreamoidSidebar` already does.
+
+---
+
+## Gotchas
+
+**1. The user is hardcoded, two levels down.** `ScSidebarProfile` renders
+`<ScProfile />` with only a `className`. `ScProfile`'s own defaults then take over:
+`name = "Chris Hemsworth"`, `subText = "Kepler workspace"`,
+`profileImage = "profile-image0.png"`. That last one is a bare relative path, so it
+404s in every host and you get a broken-image glyph.
+
+```tsx
+// WRONG — there is no such prop; you still get "Chris Hemsworth"
+<ScSidebarProfile name={user.fullName} profileImage={user.photoUrl} />
+
+// RIGHT — use ScProfile directly, or StreamoidSidebar's `profile`
+<ScProfile name={user.fullName} subText={workspace.name} profileImage={user.photoUrl} />
+```
+
+**2. `variant="collapsed"` doesn't collapse the child.** `ScProfile` has its own
+`collapsed` prop (`"true"` / `"false"`, a *string* union), and `ScSidebarProfile` never
+passes it. So the collapsed variant renders the name and subtitle inside a 48 px box.
+This is a real bug, not a subtlety.
+
+**3. It only *looks* interactive.** `cursor` is never set, and there is no `role`,
+`tabIndex` or `onKeyDown` — but there **is** a hover background. `...props` does reach
+the root, so an `onClick` works for mouse users; keyboard users get nothing.
+
+**4. `className` produces a literal `undefined` class when omitted.**
+`styles.scSidebarProfile + " " + className + " " + variantsClassName`.
+
+**5. `align-self: stretch` in the expanded variant.** It assumes a stretching
+flex-column parent (the rail). In a row-direction container it collapses.
+
+**6. `state="hover"` is design parity only.** Never wire it to mouse handlers.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+Its only composition site is the legacy sidebar:
+
+```tsx
+// npm-components  packages/ui/src/SC-Sidebar/ScSidebar.tsx:134
+<ScSidebarProfile
+  variant="collapsed"
+  className={styles.scSidebarProfileInstance}
+/>
+```
+
+Where it *would* belong — the desktop rail footer — is now owned by
+`StreamoidSidebar`'s `profile` prop, which every host passes (e.g.
+`cxo-dashboard src/app/components/app-sidebar.tsx`).
+
+---
+
+## Related
+
+- `ScProfile` — the real identity block; use this if you need a props-driven avatar +
+  name + subtitle.
+- `StreamoidSidebar` — the current rail; owns the footer via `profile` and
+  `toggleInProfile`.
+- `ScProfilePopup` / `ScProfileOptions` — what the footer opens.
+- `ScDp` — avatar-only primitive.
+- `ScSidebar` / `ScLogoUnit` / `ScSidebarIcons` / `ScVersion` — the rest of this legacy
+  sidebar family.

package/dist/docs/ScSidebarSwitchMenu.md

@@ -0,0 +1,258 @@
+---
+component: ScSidebarSwitchMenu
+package: "@streamoid/ui"
+category: sidebar
+status: stable
+renders: div
+tags: [sidebar, app-switcher, product-switch, two-line, nav-row, description, switch-menu]
+related: [ScSidebarMenu, ScAppSwitchPanel, ScCatalogixSidebar, StreamoidSidebar, ScSideBarLogoUnit]
+do_not_confuse_with: [ScSidebarMenu, ScAppSwitchPanel, ScWorkspaceSwitchCard, StreamoidWorkspaceSwitcher, ScAppCard]
+---
+
+# ScSidebarSwitchMenu
+
+**The two-line row in a sidebar's app-switch list.** Icon + product name + a
+description line beneath it. Expanded it is content-height (8/12 px padding, two text
+lines) with a **square** hover fill; collapsed it becomes a rounded 40 × 40 icon
+square that matches `ScSidebarMenu`'s collapsed row exactly.
+
+## TL;DR for agents
+
+- **Reach for it when:** you're building a "switch to another product" list inside a
+  sidebar and each entry needs a name **and** a subtitle.
+- **Don't reach for it when:** the row is ordinary nav with one line
+  (→ `ScSidebarMenu`), or you want the whole ready-made switch panel
+  (→ `ScAppSwitchPanel`, which is what CXO and Catalogix pass to `StreamoidSidebar`'s
+  `switchPanel` slot — note it builds its own masked-wordmark rows and does **not**
+  compose this component).
+- **Three things that will bite you:**
+  1. `text` defaults to `"Pairtext"` and `description` to `"Description"`. ⚠️ Both are
+     real Figma placeholder strings that will ship.
+  2. `variant="collapsed"` drops **both** text lines and the kebab; only `icon`
+     survives. There is no tooltip.
+  3. Like `ScSidebarMenu`, the root is a bare `<div>` — no `role`, no `tabIndex`, no
+     key handling.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSidebarSwitchMenu } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+<ScSidebarSwitchMenu
+  icon={<img src={app.iconUrl} alt="" />}
+  text="Photogenix"
+  description="AI product photography"
+  onClick={() => openApp(app)}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `icon` | `ReactNode` | – | Optional. When omitted the icon wrapper is **not rendered at all** (unlike `ScSidebarMenu`, which has a default icon). The wrapper is 20 × 20, `overflow: hidden`, and clamps its child with `max-width/max-height: 100%`. |
+| `text` | `string` | `"Pairtext"` | ⚠️ Real default. Product name. Single line, ellipsised. **`expanded` only.** |
+| `description` | `string` | `"Description"` | ⚠️ Real default. Subtitle line. Single line, ellipsised. **`expanded` only.** |
+| `state` | `"default"` \| `"active"` \| `"hover"` \| `"default-highlight"` \| `"default-active"` | `"default"` | Same five-state vocabulary as `ScSidebarMenu`. Note: `state` only ever recolours **`text`**, never `description`. |
+| `variant` | `"expanded"` \| `"collapsed"` | `"expanded"` | `collapsed` = rounded 40 × 40 square, icon only. |
+| `moreIcon` | `ReactNode` | – | Trailing affordance. **`expanded` only**, hidden until `:hover`. |
+| `onMoreClick` | `(e: React.MouseEvent) => void` | – | Fires from the kebab wrapper, which `stopPropagation()`s first. |
+| `className` | `string` | – | Appended after the internal class. Guarded — no stray `undefined` here (this component is the fixed one in the family). |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root div — `onClick`, `style`, `aria-*`, `data-*`. |
+
+### What each `state` renders
+
+| `state` | Background | `text` colour | `description` colour |
+|---|---|---|---|
+| `default` | none (hover → `fill-neutral-neutral`) | tertiary | tertiary |
+| `active` | `fill-neutral-neutralselected` | primary | tertiary |
+| `hover` | `fill-neutral-neutral` (forced) | tertiary | tertiary |
+| `default-highlight` | none | primary | tertiary |
+| `default-active` | `surface-canvas` + 0.5 px inset ring | primary | tertiary |
+
+`default-highlight` is the idiomatic state for app-switch rows: bright title, no fill.
+
+### Recipes
+
+```tsx
+// The expanded app-switch list (this is what ScCatalogixSidebar does)
+<div style={{ display: "flex", flexDirection: "column", gap: "var(--spacing-md)" }}>
+  {switchApps.map((app) => (
+    <ScSidebarSwitchMenu
+      key={app.id}
+      icon={app.icon}
+      text={app.name}
+      description={app.description}
+      state="default-highlight"
+      variant="expanded"
+      onClick={app.onClick}
+    />
+  ))}
+</div>
+
+// The collapsed rail's inline icon list — no card, no labels
+<div style={{ display: "flex", flexDirection: "column", alignItems: "center" }}>
+  {switchApps.map((app) => (
+    <ScSidebarSwitchMenu
+      key={app.id}
+      icon={app.icon}
+      state="default"
+      variant="collapsed"
+      onClick={app.onClick}
+      aria-label={app.name}
+    />
+  ))}
+</div>
+```
+
+---
+
+## 2. Where to use it
+
+- **The app-switch list inside a sidebar.** `ScCatalogixSidebar` renders it twice: as
+  the expanded list (inside the switch card) and as the collapsed inline icon column.
+- **Any "pick a destination with a subtitle" column in a rail** — workspaces,
+  environments, tenants.
+
+It is not exported for a page body: the type ramp, the square hover fill and the
+`align-self: stretch` geometry are all rail-specific.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- The row needs **two lines** (name + description) and lives in a sidebar.
+- You are hand-composing the switch list because your app owns the catalogue data.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A ready-made app-switch panel from an `apps[]` array | `ScAppSwitchPanel` — pass it to `StreamoidSidebar`'s `switchPanel` prop |
+| A one-line sidebar nav row | `ScSidebarMenu` |
+| A whole branded sidebar with the switcher already wired | `ScCatalogixSidebar` / `ScArtifaxSidebar` / `StreamoidSidebar` |
+| Switching **workspace**, not product | `StreamoidWorkspaceSwitcher` / `ScWorkspaceSwitchCard` |
+| An app tile on a launcher/home grid | `ScAppCardV3` / `ScAppListingCard` |
+| A row in a floating popup menu | `ScMenuOptions` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScSidebarMenu` — one line, rounded 16 px pill, has a default icon | `ScSidebarSwitchMenu` is two lines, square when expanded, and renders **no** icon if you omit it |
+| `ScAppSwitchPanel` — the whole panel, driven by `apps[{ key, name, description?, onSelect }]` | It draws its own masked-wordmark rows; this component is **not** one of them |
+| `ScWorkspaceSwitchCard` / `StreamoidWorkspaceSwitcher` (folder `SC-WorkspaceSwitcher`) — workspace, not product | Different domain |
+| `ScAppCard` / `ScAppCardV3` / `ScAppCardForCopilot` — page-body app tiles | Rail row, not a card |
+
+---
+
+## 4. Why to use it
+
+- **The square/rounded split is a deliberate design rule.** Expanded rows use
+  `border-radius: 0` so the hover fill reads as a list band inside the switch card;
+  collapsed squares go back to `radius-3xl` so they read as icon buttons in the rail.
+  Hand-rolling this is where the switch panel usually starts looking wrong.
+- **Two-line truncation already works.** The text column (`.content`) is
+  `flex: 1 0 0; min-width: 0`, and both lines inside it are `width: 100%` with
+  `text-overflow: ellipsis`, so long product names shrink instead of pushing the kebab
+  out of the rail.
+- **Icon containment.** `.iconWrapper` is a hard 20 × 20 `overflow: hidden` box with
+  `max-width/max-height: 100%` on its child, so a remote product logo of any intrinsic
+  size lands at the right optical weight.
+- **Shares the state vocabulary with `ScSidebarMenu`**, so a switch row and a nav row
+  in the same rail agree on what "active" looks like.
+
+---
+
+## Gotchas
+
+**1. `text` and `description` default to Figma placeholders.** `"Pairtext"` and
+`"Description"` will render if you forget them (or typo the prop name).
+
+```tsx
+// WRONG — renders "Pairtext" / "Description"
+<ScSidebarSwitchMenu icon={icon} name="Photogenix" />
+
+// RIGHT
+<ScSidebarSwitchMenu icon={icon} text="Photogenix" description="AI product photography" />
+```
+
+**2. `state` never recolours `description`.** Only `.text` gets the primary colour in
+`active` / `default-highlight` / `default-active`. The subtitle stays tertiary in every
+state — by design, but surprising if you expected the whole row to brighten.
+
+**3. Collapsed loses everything but the icon.** `text`, `description`, `moreIcon` all
+live inside the `variant === "expanded"` branch. And there's no `title`/`aria-label` —
+pass `aria-label` yourself (it reaches the DOM via `...props`) or add a tooltip.
+
+**4. Omitting `icon` gives you a *left-flush text row*, not a placeholder.** The icon
+wrapper is conditional (`icon ? … : null`). This differs from `ScSidebarMenu`, which
+always renders an icon and defaults it to `<SiconHome />`.
+
+**5. No a11y wiring.** Plain `<div>` with `cursor: pointer`; no `role`, `tabIndex` or
+`onKeyDown`. Add them via `...props` if the row is a real navigation target.
+
+**6. `moreIcon` is `display: none` until `:hover`.** No focus-visible reveal, so it is
+unreachable by keyboard and on touch.
+
+**7. `align-self: stretch` in expanded state.** The row assumes a stretching
+flex-column parent. Drop it into a `flex-direction: row` container and it collapses.
+`collapsed` unsets this and pins 40 × 40.
+
+**8. The row is not a card.** It draws no border and no background of its own — the
+bordered "switch card" look comes from the sidebar shell (`StreamoidSidebar`'s
+`switchPanel` renders the logo + panel inside one bordered card and dims the rest).
+Don't try to reproduce that here.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+It is composed inside the design system, by the Catalogix sidebar wrapper:
+
+```tsx
+// npm-components  packages/ui/src/SC-Catalogix-Sidebar/ScCatalogixSidebar.tsx:180
+<ScSidebarSwitchMenu
+  key={app.id}
+  icon={app.icon}
+  text={app.name}
+  description={app.description}
+  state="default-highlight"
+  variant="expanded"
+  onClick={app.onClick}
+/>
+```
+
+…and again at `ScCatalogixSidebar.tsx:204` for the collapsed icon column. Those are its
+**only** two render sites anywhere. No host app reaches it, even indirectly: the
+Catalogix dashboard builds its rail from `StreamoidSidebar` directly
+(`app/containers/LeftMenu/index.jsx:991`) and hands it a `ScAppSwitchPanel`, and
+`ScAppSwitchPanel` draws its own rows. If you need a direct call site, it belongs in a
+sidebar's app/workspace-switch list — nowhere else.
+
+---
+
+## Related
+
+- `ScSidebarMenu` — the one-line sibling; the workhorse rail row.
+- `ScAppSwitchPanel` — the assembled switch panel; prefer it over hand-listing rows.
+- `StreamoidSidebar` — pass the panel via `switchPanel` + `switchPanelOpen`, **not**
+  inline in the logo slot (that pushes the nav down).
+- `ScCatalogixSidebar` / `ScArtifaxSidebar` — branded shells that already wire this up.
+- `ScSideBarLogoUnit` — the header row whose chevron opens the switch list.
+- `StreamoidWorkspaceSwitcher` / `ScWorkspaceSwitchCard` — the workspace-level equivalents.
+  (Note: the folder is `SC-WorkspaceSwitcher` but the export is `StreamoidWorkspaceSwitcher`;
+  there is no `ScWorkspaceSwitcher`.)

package/dist/docs/ScSlider.md

@@ -0,0 +1,194 @@
+---
+component: ScSlider
+package: "@streamoid/ui"
+category: forms
+status: legacy
+renders: div
+tags: [slider, range, steps, segmented-progress, strength, opacity, non-interactive, figma-trace]
+related: [ScProgressBar, ScCounter, ScTextField]
+do_not_confuse_with: [ScProgressBar, ScCounter, ScSelectionPillGroup, ScTabSwitcher]
+---
+
+# ScSlider
+
+**Not a working slider — a static five-segment bar.** It renders a fixed row of
+5 bars + 5 dots with the **first** segment painted warning-orange and the rest grey.
+Nothing is draggable, there is no `value`, and its one callback is never called.
+Treat it as an unfinished Figma trace.
+
+## TL;DR for agents
+
+- **Reach for it when:** essentially never in its current form. There is no host call
+  site, and it cannot report or receive a value.
+- **Don't reach for it when:** you need a real range input (→ native
+  `<input type="range">`), a progress indicator (→ `ScProgressBar`), or a bounded
+  numeric value (→ `ScCounter`).
+- **Three things that will bite you:**
+  1. **`onValueChange` is declared and never invoked.** Dead prop.
+  2. There is **no `value` / `min` / `max` / `step`** — the highlighted segment is
+     hardcoded to the first one.
+  3. The root is `overflow: hidden`, so a thumb or tooltip you try to inject gets
+     clipped.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScSlider } from "@streamoid/ui";
+import "@streamoid/ui/dist/index.css"; // once, at your app root
+```
+
+### Minimal usage
+
+```tsx
+// Renders the fixed 5-segment bar. This is all it does.
+<ScSlider />
+```
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `onValueChange` | `(value: number) => void` | – | ⚠️ **Never called.** Declared in the interface, destructured, and dropped. |
+| `className` | `string` | – | Concatenated onto the root. |
+| `...props` | `HTMLAttributes<HTMLDivElement>` | – | Spread onto the root — `onClick`, `onPointerDown`, `style`, `aria-*`. The only way to make it do anything. |
+
+### What it actually renders
+
+| Child | Count | Fill |
+|---|---|---|
+| First bar + first dot | 1 each | `--alias-fill-warning-solid` (orange) |
+| Remaining bars | 4 | `--alias-fill-neutral-neutralactive` |
+| Remaining dots | 4 | `--alias-text-and-icons-primary` (white) |
+
+Container: `--alias-surface-base` background, `--radius-full`, `1rem` padding,
+`0.25rem` gaps, `overflow: hidden`. Bars are `flex: 1` (they stretch); dots are
+fixed `0.5rem` squares.
+
+### Recipes
+
+```tsx
+// What you almost certainly want instead — a real range input, styled by you.
+// (Photogenix does exactly this locally: client/src/components/viewer/views/AdjustmentsView.tsx)
+<input
+  type="range"
+  min={0}
+  max={100}
+  value={strength}
+  onChange={(e) => setStrength(Number(e.target.value))}
+/>
+
+// A determinate progress bar from the DS — `progress` is a PERCENT (0–100, clamped),
+// not a 0–1 fraction. It defaults to 50.
+<ScProgressBar progress={42} />
+
+// A bounded numeric value with a stepper
+<ScCounter count={strength} min={0} max={100} onChange={setStrength} label="%" />
+```
+
+---
+
+## 2. Where to use it
+
+Nowhere today. No render site exists in CXO, Catalogix, Photogenix or Artifax, and no
+other DS component composes it. Its visual — a segmented bar with one hot segment —
+reads like a **"step 1 of 5" indicator** rather than a range control, so if it gets
+finished it most plausibly belongs to a **multi-step flow header** (feed import,
+onboarding) or a discrete strength picker in Photogenix's adjustments panel.
+
+---
+
+## 3. When to use it
+
+### Use it when
+
+- You deliberately want the static five-segment decoration and are fine with it being
+  non-interactive, **and** you accept that its API may change when someone finishes it.
+
+### Don't use it — reach for this instead
+
+| Situation | Use instead |
+|---|---|
+| A draggable numeric range (strength, opacity, threshold) | native `<input type="range">` — Photogenix's `AdjustmentsView` is the reference |
+| Determinate progress / percentage complete | `ScProgressBar` (`progress?: number`, 0–100, default `50`) |
+| A bounded integer the user nudges or types | `ScCounter` (has real `min`/`max`) |
+| Free numeric entry in a form | `ScTextField` / `ScOnlyField` |
+| Discrete choice between 2–5 options | `ScSelectionPillGroup` / `ScTabSwitcher` |
+
+### Don't confuse with
+
+| You may actually want | Not this |
+|---|---|
+| `ScProgressBar` — one bar driven by a real `progress` number | `ScSlider` has no value input at all |
+| `ScCounter` — the only DS control with working `min`/`max` clamping | Not a slider, but usually the right answer |
+| A "steps" indicator | This looks like one but exposes no current-step prop |
+
+---
+
+## 4. Why to use it
+
+Honestly: little. The only things it gives you are the token-driven fills
+(`--alias-fill-warning-solid`, `--alias-fill-neutral-neutralactive`) and the pill
+container geometry. Because it accepts no value and emits no events, **any real
+interaction has to be built on top of the spread `HTMLAttributes`**, at which point
+you are writing the slider yourself and should do so with a native
+`<input type="range">` that gets keyboard support, `aria-valuenow` and touch handling
+for free.
+
+If you need this component for real, the honest move is to fix it in the DS
+(add `value` / `min` / `max` / `step`, wire `onValueChange`, drop `overflow: hidden`)
+rather than to work around it at a call site.
+
+---
+
+## Gotchas
+
+**1. `onValueChange` never fires.** It is destructured out of props and then unused —
+so it is not even forwarded to the DOM.
+
+```tsx
+// WRONG — the handler is dead code
+<ScSlider onValueChange={setStrength} />
+
+// RIGHT — for a real slider, don't use this component
+<input type="range" min={0} max={100} value={strength}
+       onChange={(e) => setStrength(Number(e.target.value))} />
+```
+
+**2. The highlighted segment is hardcoded.** The first bar/dot pair always uses the
+warning colour; segments 2–5 always use the neutral pair. You cannot express "3 of 5".
+
+**3. `overflow: hidden` on the root.** Any absolutely-positioned thumb, value bubble
+or tooltip you add via children/`style` will be clipped by the pill.
+
+**4. Bars stretch, dots don't.** Bars are `flex: 1`; dots are fixed 8px. In a narrow
+container the bars collapse toward zero and you get a dotted line.
+
+**5. It has no accessible role.** No `role="slider"`, no `aria-valuemin/now/max`, no
+`tabIndex`. Screen readers see an empty group of divs.
+
+**6. `className` is string-concatenated**, so the DOM class list contains a literal
+`undefined` when you omit it.
+
+---
+
+## In the wild
+
+_No host render site found — used by the agent runtime / composed internally._
+
+In this case neither: nothing renders it. It exists only as an export. The nearest
+real implementation of the job it looks like it does is Photogenix's local
+`<input type="range">` in
+`photogenix_v2 dashboard/client/src/components/viewer/views/AdjustmentsView.tsx:60`.
+
+---
+
+## Related
+
+- `ScProgressBar` — determinate progress from a real `progress` number.
+- `ScCounter` — bounded numeric stepper with working `min`/`max`.
+- `ScSelectionPillGroup` / `ScTabSwitcher` — if the intent was discrete steps/choices.
+- `ScTextField` — plain numeric entry inside a form.