``` --- # Recommendation Card > Agent suggestion with a confidence meter and alternatives. - **Slug:** `recommendation-card` - **Kind:** component · **Category:** Agent - **Source:** ported from [Beautiful UI](https://github.com/slev12397/beautiful-ui/blob/main/components/primitives/RecommendationCard.tsx) (MIT) - **Docs page:** https://viewership.ai/ui/components/recommendation-card - **All files in one bundle:** https://viewership.ai/ui/components/recommendation-card.bundle.txt - **Structured JSON:** https://viewership.ai/ui/components/recommendation-card.json ## Install 1. Import the foundation tokens once (download: https://viewership.ai/ui/raw/foundation.css.txt): ```astro --- // src/layouts/Layout.astro import "../styles/foundation.css"; --- ``` 2. Copy this file into `src/components/viewership/recommendation-card/`: - `RecommendationCard.astro` (raw: https://viewership.ai/ui/raw/recommendation-card/RecommendationCard.astro.txt) 3. Copy its registry dependencies, each into its own sibling folder under `src/components/viewership/`: - `button`: `Button.astro` (docs: https://viewership.ai/ui/components/button.md) - `entity-chip`: `EntityChip.astro`, `Monogram.astro` (docs: https://viewership.ai/ui/components/entity-chip.md) - `value-pill`: `ValuePill.astro` (docs: https://viewership.ai/ui/components/value-pill.md) npm packages: none. ## Usage ```astro --- import RecommendationCard from "../components/viewership/recommendation-card/RecommendationCard.astro"; --- ``` ## Example The gallery demo, verbatim. Use the import path from Usage instead of `./`. ```astro --- import RecommendationCard from "./RecommendationCard.astro"; import type { RecommendationOption } from "./RecommendationCard.astro"; const options: RecommendationOption[] = [ { key: "shift", body: [ "Shift budget to", { entity: "Northwind Spring Search", color: "var(--vs-green)" }, "with ROAS", { value: "4.2x", tone: "green" }, ], short: "Shift budget to Spring Search · 4.2x", signal: 3, tone: "green", label: "High confidence", cta: "Accept", ctaVariant: "accent", }, { key: "swap", body: ["Swap the hero creative to", { value: "Trail Test video" }, "for the spring launch."], short: "Swap hero creative to Trail Test", signal: 2, tone: "orange", label: "Needs review", cta: "Configure", ctaVariant: "primary", }, { key: "even", body: ["Fall back to an", { strong: "even split" }, "across every campaign."], short: "Even split across every campaign", signal: 0, tone: "neutral", label: "No signal", cta: "Accept even split", ctaVariant: "primary", }, ]; ---

``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `title` | `string` | | The agent's question. | | `options` | `RecommendationOption[]` | | { key, body, short, signal (0–3), tone, label, cta, ctaVariant? }. body is a string or parts: strings, { entity, color? }, { value, tone? }, { strong }. | | `selected` | `number` | `0` | Initial option index. | | `labels` | `Partial` | | alternatives, otherOptions, accepted, confidence (meter name). | | `vs-recommendation-accept` | `CustomEvent<{ key: string; index: number }>` | | Fires on accept. The card only shows "Accepted"; do the work in your handler. | | `vs-recommendation-select` | `CustomEvent<{ key: string; index: number }>` | | Fires when an alternative is promoted. | | `vs-recommendation-toggle` | `CustomEvent<{ open: boolean }>` | | Fires when the drawer toggles. | ## Source ### `src/components/viewership/recommendation-card/RecommendationCard.astro` ```astro --- /** * RecommendationCard: agent suggestion with a confidence meter, * alternatives and an accept button. * * Ported from Beautiful UI `components/primitives/RecommendationCard.tsx` * (MIT, © 2026 Shane Levine). * * The card does no work itself. It reports choices as events. Bodies are * built from parts: strings, `{ entity }`, `{ value }` and `{ strong }`. * * Events (bubbling, on the root): * vs-recommendation-accept detail: { key, index } * vs-recommendation-select detail: { key, index } * vs-recommendation-toggle detail: { open } * * @example * */ import type { HTMLAttributes } from "astro/types"; import Button from "../button/Button.astro"; import EntityChip from "../entity-chip/EntityChip.astro"; import ValuePill from "../value-pill/ValuePill.astro"; type Tone = "green" | "orange" | "red" | "accent" | "neutral"; type CtaVariant = "primary" | "secondary" | "ghost" | "accent" | "success" | "quiet"; /** An EntityChip inside the body. */ export interface RecommendationEntityPart { entity: string; color?: string; monogram?: string; } /** A ValuePill inside the body. */ export interface RecommendationValuePart { value: string; tone?: Tone; } /** Emphasized text inside the body. */ export interface RecommendationStrongPart { strong: string; } export type RecommendationBodyPart = string | RecommendationEntityPart | RecommendationValuePart | RecommendationStrongPart; export interface RecommendationOption { /** Stable id, reported in events. */ key: string; /** The recommendation in prose. */ body: string | RecommendationBodyPart[]; /** One-line summary used in the alternatives drawer. */ short: string; /** Confidence, 0–3 bars. */ signal: number; tone: Tone; /** Confidence label, e.g. "High confidence". */ label: string; /** Primary action text. */ cta: string; ctaVariant?: CtaVariant; } export interface RecommendationLabels { alternatives: string; otherOptions: string; accepted: string; /** Accessible name of the meter. */ confidence: string; } type Props = HTMLAttributes<"div"> & { title: string; options: RecommendationOption[]; /** Index of the initial recommendation. */ selected?: number; labels?: Partial; }; const { title, options = [], selected = 0, labels, class: className, ...rest } = Astro.props; const l: RecommendationLabels = { alternatives: "Alternatives", otherOptions: "Other options", accepted: "Accepted", confidence: "Confidence", ...labels, }; const uid = `vs-rec-${Math.random().toString(36).slice(2, 8)}`; const sel = Math.min(Math.max(0, selected), Math.max(0, options.length - 1)); const active = options[sel]; const TONE: Record = { green: "var(--vs-green)", orange: "var(--vs-orange)", red: "var(--vs-red)", accent: "var(--vs-accent)", neutral: "var(--vs-ink-3)", }; const toneOf = (tone: Tone) => TONE[tone] ?? TONE.neutral; const bars = [0, 1, 2]; const parts = (body: RecommendationOption["body"]): RecommendationBodyPart[] => (typeof body === "string" ? [body] : body); const config = options.map((o) => ({ key: o.key, signal: o.signal, tone: toneOf(o.tone), label: o.label, cta: o.cta, ctaVariant: o.ctaVariant ?? "primary", })); ---

``` --- # Context Cards > Retrieved knowledge chunks with sources, entering in sequence. - **Slug:** `context-cards` - **Kind:** component · **Category:** Agent - **Source:** ported from [Beautiful UI](https://github.com/slev12397/beautiful-ui/blob/main/components/primitives/ContextCards.tsx) (MIT) - **Docs page:** https://viewership.ai/ui/components/context-cards - **All files in one bundle:** https://viewership.ai/ui/components/context-cards.bundle.txt - **Structured JSON:** https://viewership.ai/ui/components/context-cards.json ## Install 1. Import the foundation tokens once (download: https://viewership.ai/ui/raw/foundation.css.txt): ```astro --- // src/layouts/Layout.astro import "../styles/foundation.css"; --- ``` 2. Copy this file into `src/components/viewership/context-cards/`: - `ContextCards.astro` (raw: https://viewership.ai/ui/raw/context-cards/ContextCards.astro.txt) npm packages: none. ## Usage ```astro --- import ContextCards from "../components/viewership/context-cards/ContextCards.astro"; --- ``` ## Example The gallery demo, verbatim. Use the import path from Usage instead of `./`. ```astro --- import ContextCards, { type ContextChunk } from "./ContextCards.astro"; const chunks: ContextChunk[] = [ { title: "Brand voice rule", chars: 290, body: "Headlines stay under 60 characters, with no exclamation marks, before a draft goes to client review.", source: "Brand Voice Guide.pdf", badge: "PDF", tone: "red", }, { title: "Weekly traffic row", chars: 1250, body: "Q4 sessions by channel: organic +18%, paid search +6%, email -11%; pause ad groups under 40 clicks weekly.", source: "GA4 Channel Export.csv", badge: "CSV", tone: "green", }, ]; ---

``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `chunks` | `{ title; chars: string \| number; body; source; badge; tone?: "red" \| "green" \| "orange" \| "accent"; href? }[]` | `[]` | Retrieved chunks. A source chip with `href` is a link; otherwise a button that emits `vs-context-source`. | | `header` | `string` | `"All chunks"` | Header label and section name. | | `count` | `string \| number` | `chunks.length` | Count beside the header. | | `autoplay` | `boolean` | `true` | Play entrance once in view. false shows the final state. | ## Source ### `src/components/viewership/context-cards/ContextCards.astro` ```astro --- /** * ContextCards: retrieved knowledge chunks with their sources, entering in * sequence. A source chip is a link (with `href`) or a button that emits * `vs-context-source`. * * Ported from Beautiful UI `components/primitives/ContextCards.tsx` * (MIT, © 2026 Shane Levine). * * @example * * * Events: `vs-context-source` (detail: { index, source, title }) when a * button-style source chip is activated. */ import type { HTMLAttributes } from "astro/types"; export type ContextChunk = { title: string; /** Size line, e.g. "290 characters". A number is formatted as "N characters". */ chars: string | number; body: string; /** Source document name. */ source: string; /** Short file-type badge, e.g. "PDF". */ badge: string; tone?: "red" | "green" | "orange" | "accent"; /** Optional link for the source chip. */ href?: string; }; type Props = HTMLAttributes<"section"> & { chunks?: ContextChunk[]; /** Header label. */ header?: string; /** Count beside the header (e.g. total chunks in the index). Defaults to chunks.length. */ count?: string | number; /** Play the entrance when scrolled into view. false renders the final state. */ autoplay?: boolean; }; const { chunks = [], header = "All chunks", count, autoplay = true, class: className, ...rest } = Astro.props; const chars = (c: ContextChunk["chars"]) => (typeof c === "number" ? `${c.toLocaleString("en-US")} characters` : c); ---

{chunks.map((chunk, i) => { const Source = chunk.href ? "a" : "button"; return (

{chunk.title} {chars(chunk.chars)}

{chunk.body}

{chunk.source}

); })}

``` --- # Diff Table > AI-proposed table edits you include or skip, then apply. - **Slug:** `diff-table` - **Kind:** component · **Category:** Data - **Source:** ported from [Beautiful UI](https://github.com/slev12397/beautiful-ui/blob/main/components/primitives/DiffTable.tsx) (MIT) - **Docs page:** https://viewership.ai/ui/components/diff-table - **All files in one bundle:** https://viewership.ai/ui/components/diff-table.bundle.txt - **Structured JSON:** https://viewership.ai/ui/components/diff-table.json ## Install 1. Import the foundation tokens once (download: https://viewership.ai/ui/raw/foundation.css.txt): ```astro --- // src/layouts/Layout.astro import "../styles/foundation.css"; --- ``` 2. Copy this file into `src/components/viewership/diff-table/`: - `DiffTable.astro` (raw: https://viewership.ai/ui/raw/diff-table/DiffTable.astro.txt) 3. Copy its registry dependencies, each into its own sibling folder under `src/components/viewership/`: - `button`: `Button.astro` (docs: https://viewership.ai/ui/components/button.md) npm packages: none. ## Usage ```astro --- import DiffTable from "../components/viewership/diff-table/DiffTable.astro"; --- ``` ## Example The gallery demo, verbatim. Use the import path from Usage instead of `./`. ```astro --- import DiffTable from "./DiffTable.astro"; import type { DiffColumn, DiffRow } from "./DiffTable.astro"; const columns: DiffColumn[] = [ { key: "asset", label: "Asset", kind: "title" }, { key: "channel", label: "Channel", kind: "tag" }, { key: "owner", label: "Owner" }, ]; const rows: DiffRow[] = [ { key: "faq", cells: { asset: "Old FAQ Post", channel: "Blog", owner: "dana-w" }, change: "remove" }, { key: "recap", cells: { asset: "Recap Thread", channel: "Social", owner: "marcus-t" }, change: "remove" }, { key: "trail", cells: { asset: "Trail Guide", channel: "Blog", owner: "priya-s" } }, { key: "care", cells: { asset: "Gear Care Email", channel: "Email", owner: "dana-w" }, change: "add" }, ]; ---

``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `columns` | `{ key: string; label: string; width?: string; kind?: "title" \| "tag" \| "text" }[]` | | Column order and headers. The first column names the row. | | `rows` | `{ key: string; cells: Record; change?: "remove" \| "add" }[]` | | Table data. Rows with `change` are proposed edits. | | `tagTones` | `Record` | `{}` | Dot color per tag value. | | `labels` | `Partial` | | Text overrides: title, hint, removal(s), addition(s), apply, applied, includeRemove, includeAdd, removedRow, addedRow. | | `autoplay` | `boolean` | `true` | Play when scrolled into view. Reduced motion and no-JS show the final diff. | | `loop` | `boolean` | `false` | Replay after a 4s hold until interaction. | | `vs-diff-toggle` | `CustomEvent<{ key: string; included: boolean }>` | | Fires when a change is included or skipped. | | `vs-diff-apply` | `CustomEvent<{ removed: string[]; added: string[]; skipped: string[] }>` | | Fires on Apply with row keys by kind. The table only shows a confirmation. | ## Source ### `src/components/viewership/diff-table/DiffTable.astro` ```astro --- /** * DiffTable: AI-proposed edits sweeping through tabular data. * * Ported from Beautiful UI `components/primitives/DiffTable.tsx` * (MIT, © 2026 Shane Levine). * * The proposed edit plays once when the table scrolls into view and rests on * the completed diff: removals turn red and strike through, then added rows * grow in with include checkboxes and a summary footer. Clicking a changed * row toggles it. "Apply" reports the included edits; the table itself * changes nothing. Without JS or with reduced motion, the final diff renders. * * Events (bubbling, on the root): * vs-diff-toggle detail: { key, included } * vs-diff-apply detail: { removed: string[], added: string[], skipped: string[] } * * @example * */ import type { HTMLAttributes } from "astro/types"; import Button from "../button/Button.astro"; type Tone = "accent" | "neutral" | "green" | "orange" | "red"; export interface DiffColumn { key: string; label: string; /** CSS width for the column, e.g. "34%". */ width?: string; /** "title" = strong first column, "tag" = dot pill, "text" = muted text (default). */ kind?: "title" | "tag" | "text"; } export interface DiffRow { key: string; cells: Record; /** The proposed edit for this row, if any. */ change?: "remove" | "add"; } export interface DiffTableLabels { title: string; hint: string; removal: string; removals: string; addition: string; additions: string; /** {n} is replaced. */ apply: string; applyPlural: string; applied: string; appliedPlural: string; /** Checkbox names; {name} is the row's first cell. */ includeRemove: string; includeAdd: string; /** Screen-reader suffix on changed rows. */ removedRow: string; addedRow: string; } type Props = HTMLAttributes<"div"> & { columns: DiffColumn[]; rows: DiffRow[]; /** Dot color per tag value (for "tag" columns). */ tagTones?: Record; labels?: Partial; /** Play the sweep when scrolled into view. */ autoplay?: boolean; /** Replay after a hold, until someone interacts. */ loop?: boolean; }; const { columns = [], rows = [], tagTones = {}, labels, autoplay = true, loop = false, class: className, ...rest } = Astro.props; const l: DiffTableLabels = { title: "Proposed changes", hint: "Click changed rows to toggle", removal: "removal", removals: "removals", addition: "addition", additions: "additions", apply: "Apply {n} change", applyPlural: "Apply {n} changes", applied: "{n} edit applied", appliedPlural: "{n} edits applied", includeRemove: "Include: remove {name}", includeAdd: "Include: add {name}", removedRow: "proposed removal", addedRow: "proposed addition", ...labels, }; const uid = `vs-diff-${Math.random().toString(36).slice(2, 8)}`; const TONE: Record = { accent: "var(--vs-accent)", neutral: "var(--vs-ink-3)", green: "var(--vs-green)", orange: "var(--vs-orange)", red: "var(--vs-red)", }; const DEFAULT_WIDTHS = ["34%", "30%", "36%"]; const removals = rows.filter((r) => r.change === "remove").length; const additions = rows.filter((r) => r.change === "add").length; const total = removals + additions; const plural = (n: number, one: string, many: string) => (n === 1 ? one : many).replace("{n}", String(n)); const summary = `${removals} ${removals === 1 ? l.removal : l.removals} · ${additions} ${additions === 1 ? l.addition : l.additions}`; const lastCol = columns.length - 1; const checkPath = ''; ---

{l.title} {l.hint}

{columns.map((c, i) => )} {columns.map((c) => )} {rows.map((row) => { const name = row.cells[columns[0]?.key ?? ""] ?? row.key; return ( {columns.map((c, ci) => { const value = row.cells[c.key] ?? ""; const kind = c.kind ?? (ci === 0 ? "title" : "text"); const content = (

{kind === "tag" ? ( {value} ) : ci === lastCol && row.change ? ( {value} ) : ( {value} {ci === 0 && row.change && , {row.change === "remove" ? l.removedRow : l.addedRow}} )}

); return ( ); })} ); })}

{c.label}
{row.change === "add" ? ( {content} ) : ( content )}

``` --- # Records Table > CRM-style AI spreadsheet with tags, sorting and configurable AI columns. - **Slug:** `records-table` - **Kind:** component · **Category:** Data - **Source:** ported from [Beautiful UI](https://github.com/slev12397/beautiful-ui/blob/main/components/primitives/RecordsTable.tsx) (MIT) - **Docs page:** https://viewership.ai/ui/components/records-table - **All files in one bundle:** https://viewership.ai/ui/components/records-table.bundle.txt - **Structured JSON:** https://viewership.ai/ui/components/records-table.json ## Install 1. Import the foundation tokens once (download: https://viewership.ai/ui/raw/foundation.css.txt): ```astro --- // src/layouts/Layout.astro import "../styles/foundation.css"; --- ``` 2. Copy this file into `src/components/viewership/records-table/`: - `RecordsTable.astro` (raw: https://viewership.ai/ui/raw/records-table/RecordsTable.astro.txt) 3. Copy its registry dependencies, each into its own sibling folder under `src/components/viewership/`: - `glide-menu`: `GlideMenu.astro`, `glide-menu.ts` (docs: https://viewership.ai/ui/components/glide-menu.md) - `switch`: `Switch.astro` (docs: https://viewership.ai/ui/components/switch.md) npm packages: none. ## Usage ```astro --- import RecordsTable from "../components/viewership/records-table/RecordsTable.astro"; --- ``` ## Example The gallery demo, verbatim. Use the import path from Usage instead of `./`. ```astro --- import RecordsTable, { type RecordRow } from "./RecordsTable.astro"; /* Sources that AI engines cite for Northwind Outdoor. All names are fictional. */ const accounts: RecordRow[] = [ { id: "campinggear", name: "r/CampingGear · Reddit", tags: ["Reddit", "Cited"], last: "9 days ago", lastDays: 9, strength: "strong", website: "reddit.test", ai: "Ridgecrest, Summit & Pine" }, { id: "trailnotes", name: "Trail Notes Weekly · Leeds", tags: ["Reddit", "YouTube", "Blog"], last: "3 weeks ago", lastDays: 21, strength: "strong", website: "trailnotes.test", ai: "Alder Peak, Two Rivers Co" }, { id: "gearlab", name: "Gear Lab Reviews · Melbourne", tags: ["Forum", "Reviews"], last: "2 months ago", lastDays: 60, strength: "weak", website: "gearlab-reviews.test", ai: "Summit & Pine, Saltline Gear" }, { id: "basecamp-pod", name: "Basecamp Podcast · Ghent", tags: ["Podcast", "Cited", "Seasonal"], last: "15 days ago", lastDays: 15, strength: "weak", website: "basecamp-pod.test", ai: "Two Rivers Co, Emberline" }, { id: "outdoor-wire", name: "Outdoor Wire News · Denver", tags: ["News", "Newsletter"], last: "over 1 year ago", lastDays: 400, strength: "veryweak", website: "outdoor-wire.test", ai: "Ridgecrest, Pale Ridge" }, { id: "packlight", name: "Packlight Shorts · Lisbon", tags: ["Shorts", "YouTube"], last: "5 months ago", lastDays: 150, strength: "veryweak", ai: "Saltline Gear, Alder Peak" }, { id: "ul-hikers", name: "r/Ultralight · Reddit", tags: ["Reddit", "Guides", "Seasonal"], last: "No contact", strength: "none", website: "reddit.test", ai: "Pale Ridge, Emberline" }, { id: "alpine-stay", name: "Alpine Stay Guide · Banff", tags: ["Travel", "Reviews"], last: "3 months ago", lastDays: 90, strength: "veryweak", website: "alpine-stay.test", ai: "Summit & Pine, Two Rivers Co" }, { id: "hike-forum", name: "HikeTalk Forum · Chicago", tags: ["Forum", "Cited"], last: "over 1 year ago", lastDays: 420, strength: "veryweak", website: "hiketalk.test", ai: "Ridgecrest, Saltline Gear" }, { id: "orchard-outfit", name: "Orchard Outfitters · Hobart", tags: ["Retailer", "Blog", "Newsletter"], last: "2 months ago", lastDays: 62, strength: "weak", website: "orchard-outfit.test", ai: "Alder Peak, Pale Ridge" }, { id: "kiln-trails", name: "Kiln Trails Channel · Kyoto", tags: ["Reddit", "Reviews", "Seasonal"], last: "11 days ago", lastDays: 11, strength: "strong", website: "kiln-trails.test", ai: "Emberline, Summit & Pine" }, { id: "saltgrass", name: "Saltgrass Daily · Oslo", tags: ["News", "YouTube"], last: "about 1 month ago", lastDays: 33, strength: "weak", website: "saltgrass.test", ai: "Two Rivers Co, Ridgecrest" }, { id: "wren", name: "Wren & Wild Blog · Edinburgh", tags: ["Reddit", "Podcast"], last: "4 days ago", lastDays: 4, strength: "strong", website: "wren-wild.test", ai: "Saltline Gear, Pale Ridge" }, { id: "dune", name: "Dune Road Surf Talk · San Diego", tags: ["Shorts", "Seasonal"], last: "8 months ago", lastDays: 240, strength: "weak", website: "dune-road.test", ai: "Alder Peak, Emberline" }, { id: "foundry", name: "Foundry Expo Hall · Pittsburgh", tags: ["Events", "Cited", "Reviews"], last: "about 2 years ago", lastDays: 730, strength: "none", website: "foundry-expo.test", ai: "Summit & Pine, Ridgecrest" }, { id: "parlour", name: "Parlour Nine Vlog · Montréal", tags: ["Reddit", "YouTube"], last: "about 1 month ago", lastDays: 30, strength: "veryweak", ai: "Two Rivers Co, Saltline Gear" }, { id: "greenhouse", name: "Greenhouse Goods · Copenhagen", tags: ["Retailer", "Guides"], last: "15 days ago", lastDays: 15, strength: "weak", website: "greenhouse-goods.test", ai: "Pale Ridge, Alder Peak" }, { id: "low-tide", name: "Low Tide Paddle Club · Halifax", tags: ["Forum", "Blog"], last: "9 days ago", lastDays: 9, strength: "strong", website: "low-tide.test", ai: "Emberline, Two Rivers Co" }, { id: "sundial", name: "Sundial Books & Maps · Seville", tags: ["Reddit", "Retailer"], last: "over 2 years ago", lastDays: 800, strength: "none", website: "sundial-maps.test", ai: "Ridgecrest, Summit & Pine" }, { id: "meridian", name: "Meridian Media · Singapore", tags: ["News", "Newsletter", "Cited"], last: "about 1 month ago", lastDays: 35, strength: "veryweak", website: "meridian-media.test", ai: "Saltline Gear, Emberline" }, { id: "thistle", name: "Thistle Trail Guides · Dublin", tags: ["Reddit", "Guides"], last: "No contact", strength: "none", ai: "Alder Peak, Pale Ridge" }, { id: "clay", name: "Clay Ridge Climbing · Naples", tags: ["Forum", "YouTube"], last: "almost 2 years ago", lastDays: 700, strength: "veryweak", website: "clay-ridge.test", ai: "Two Rivers Co, Summit & Pine" }, { id: "cobalt", name: "Cobalt Climbing Blog · Boulder", tags: ["Shorts", "Newsletter"], last: "6 days ago", lastDays: 6, strength: "strong", website: "cobalt-climbing.test", ai: "Ridgecrest, Emberline" }, { id: "verandah", name: "Verandah Travel Notes · Galle", tags: ["Travel", "Seasonal", "Reviews"], last: "18 days ago", lastDays: 18, strength: "weak", website: "verandah-travel.test", ai: "Pale Ridge, Saltline Gear" }, { id: "loom", name: "Loom & Ledge · Glasgow", tags: ["Reddit", "Events", "Blog"], last: "2 days ago", lastDays: 2, strength: "strong", website: "loom-ledge.test", ai: "Summit & Pine, Alder Peak" }, { id: "pressroom", name: "The Gear Pressroom · Wellington", tags: ["Reddit", "YouTube", "Cited"], last: "5 weeks ago", lastDays: 36, strength: "weak", website: "gear-pressroom.test", ai: "Two Rivers Co, Ridgecrest" }, { id: "alder", name: "Alder Camp Forum · Tallinn", tags: ["Forum", "Reviews"], last: "No contact", strength: "none", ai: "Emberline, Pale Ridge" }, { id: "bluebird", name: "Bluebird Bike Trails · Utrecht", tags: ["Reddit", "Blog", "Seasonal"], last: "7 days ago", lastDays: 7, strength: "strong", website: "bluebird-trails.test", ai: "Saltline Gear, Summit & Pine" }, ]; --- ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `rows` | `RecordRow[]` | | { id, name, tags, last, lastDays?, strength, website?, ai? }. Omit `lastDays` for no contact. `ai` is the AI column value. | | `caption` | `string` | `"Records"` | Hidden caption. Also names the scroll region and select-all. | | `columns` | `{ company?, categories?, last?, strength?, links? }` | | Header labels. | | `columnConfig` | `Partial>>` | | Popover overrides: type, tool, toolKind, inputs, prompt. | | `tagColors` | `Record` | | Tag → palette name (amber, lime, yellow, purple, orange, cyan, red, magenta, green, pink) or CSS color. | | `strengthLabels` | `Partial>` | | Strength level labels. | | `models` | `string[]` | `["Atlas 5", "Atlas 4.2", "Atlas Mini"]` | Tool picker models. First is the default. | | `aiColumn` | `{ label, type?, tool?, prompt? } \| null` | `{ label: "Competitors" }` | AI property added by the + menu. Cells resolve to each row's `ai`. | | `sort` | `{ key: "name" \| "last" \| "strength"; dir?: 1 \| -1 }` | `{ key: "name", dir: 1 }` | Initial sort. | | `fill` | `boolean` | `false` | Fill the parent card, no border or shadow. | | `maxHeight` | `string` | `"438px"` | Scroll viewport max height. | | `Events` | `CustomEvent` | | vs-records-selection { ids }, vs-records-sort { key, dir }, vs-records-calculate { column, label }, vs-records-property { type }, vs-records-add-calculation. | ## Source ### `src/components/viewership/records-table/RecordsTable.astro` ```astro --- /** * RecordsTable: CRM-style AI spreadsheet. Click a header to configure the * column and run "Go calculate". The + header adds an AI property. * * Ported from Beautiful UI `components/primitives/RecordsTable.tsx` * (MIT, © 2026 Shane Levine). * * - Real ; sortable headers expose `aria-sort`. * - Resize by dragging the header edge or ←/→ on the handle (Shift = bigger steps). * - Popovers use the top layer (Popover API), with a `position: fixed` fallback. * - Renders without JS (sorted by name); interaction needs the script. * * Events (bubbling, on the root): * vs-records-selection detail: { ids: string[] } * vs-records-sort detail: { key: "name" | "last" | "strength", dir: 1 | -1 } * vs-records-calculate detail: { column: ColumnKey, label: string } * vs-records-property detail: { type: string } * vs-records-add-calculation * * @example * */ import type { HTMLAttributes } from "astro/types"; import GlideMenu from "../glide-menu/GlideMenu.astro"; import Switch from "../switch/Switch.astro"; export type Strength = "strong" | "weak" | "veryweak" | "none"; export type ColumnKey = "company" | "categories" | "last" | "strength" | "links" | "ai"; export interface RecordRow { id: string; name: string; tags: string[]; /** Display text for the last interaction, e.g. "9 days ago" or "No contact". */ last: string; /** Days since the last interaction, for sorting. Omit (or null) for no contact. */ lastDays?: number | null; strength: Strength; /** Bare domain, e.g. "northwind.test". */ website?: string; /** The value the AI column resolves to for this row. */ ai?: string; } export interface RecordsPrompt { before: string; /** An @-mentioned input, rendered as a chip. */ chip?: string; after?: string; } export interface ColumnConfig { label: string; /** Property type shown in the popover (one of the property types). */ type: string; /** Tool label, e.g. a model name, "Web search" or "User input". */ tool: string; toolKind: "model" | "web" | "user"; inputs: string[]; prompt?: RecordsPrompt; } export interface AiColumn { label: string; type?: string; tool?: string; prompt?: RecordsPrompt; } type Props = HTMLAttributes<"div"> & { rows: RecordRow[]; /** Table caption (visually hidden) and scroll-region name. */ caption?: string; /** Header labels. */ columns?: Partial, string>>; /** Per-column popover configuration overrides. */ columnConfig?: Partial>>; /** Tag → palette name or CSS color. Unlisted tags get a stable color. */ tagColors?: Record; /** Labels for the four strength levels. */ strengthLabels?: Partial>; /** Models offered in the Tool picker; the first is the default. */ models?: string[]; /** The AI property the + menu adds. `null` hides the + menu's effect. */ aiColumn?: AiColumn | null; /** Initial sort. */ sort?: { key: "name" | "last" | "strength"; dir?: 1 | -1 }; /** Stretch to fill a parent card, dropping the border and shadow. */ fill?: boolean; /** Max height of the scroll viewport (ignored with `fill`). */ maxHeight?: string; }; const { rows, caption = "Records", columns = {}, columnConfig = {}, tagColors = {}, strengthLabels = {}, models = ["Atlas 5", "Atlas 4.2", "Atlas Mini"], aiColumn = { label: "Competitors" }, sort = { key: "name", dir: 1 }, fill = false, maxHeight = "438px", class: className, style, ...rest } = Astro.props; const uid = `vs-rt-${Math.random().toString(36).slice(2, 8)}`; /* ── labels ─────────────────────────────────────────────── */ const L = { company: columns.company ?? "Company", categories: columns.categories ?? "Categories", last: columns.last ?? "Last interaction", strength: columns.strength ?? "Connection strength", links: columns.links ?? "Links", ai: aiColumn?.label ?? "Insights", }; const STRENGTH: Record = { strong: { label: strengthLabels.strong ?? "Very strong", color: "var(--vs-green)", rank: 3 }, weak: { label: strengthLabels.weak ?? "Weak", color: "var(--vs-orange)", rank: 2 }, veryweak: { label: strengthLabels.veryweak ?? "Very weak", color: "var(--vs-red)", rank: 1 }, none: { label: strengthLabels.none ?? "No communication", color: "var(--vs-ink-3)", rank: 0 }, }; /* ── tag colors: one mid-lightness base hue per tag, mixed against the theme ── */ const PALETTE: Record = { amber: "oklch(0.76 0.13 70)", lime: "oklch(0.77 0.16 122)", yellow: "oklch(0.80 0.15 101)", purple: "oklch(0.62 0.18 293)", orange: "oklch(0.71 0.16 48)", cyan: "oklch(0.72 0.10 221)", red: "oklch(0.64 0.19 27)", magenta: "oklch(0.66 0.21 323)", green: "oklch(0.70 0.13 162)", pink: "oklch(0.67 0.19 3)", }; const paletteKeys = Object.keys(PALETTE); const tagBase = (tag: string) => { const chosen = tagColors[tag]; if (chosen) return PALETTE[chosen] ?? chosen; let h = 0; for (const ch of tag) h = (h * 31 + ch.charCodeAt(0)) >>> 0; return PALETTE[paletteKeys[h % paletteKeys.length]]; }; /* ── glyphs (upstream-drawn, MIT) ───────────────────────── */ const TYPE_GLYPHS: Record = { Text: '', File: '', Collection: '', "Single select": '', "Multi select": '', URL: '', Reference: '', JSON: '', "File splitter": '', Date: '', }; const TOOL_GLYPHS = { model: '', web: '', user: '', }; const PROPERTY_TYPES = ["Text", "File", "Collection", "Single select", "Multi select", "URL", "Reference", "JSON", "File splitter"]; const svg = (inner: string, size = 14, sw = 1.8) => ``; const modelSvg = () => ``; const I = { check: '', chevron: '', arrowDown: '', plus: '', external: '', info: '', refresh: '', pin: '', gear: '', eyeOff: '', compact: '', reset: '', clear: '', }; /* ── per-column popover configuration ───────────────────── */ const model0 = models[0] ?? "Model"; const baseConfig: Record = { company: { label: L.company, type: "Text", tool: "User input", toolKind: "user", inputs: [] }, categories: { label: L.categories, type: "Multi select", tool: model0, toolKind: "model", inputs: [L.company], prompt: { before: "Tag each ", chip: L.company, after: " with its market categories." }, }, last: { label: L.last, type: "Date", tool: "User input", toolKind: "user", inputs: [] }, strength: { label: L.strength, type: "Single select", tool: model0, toolKind: "model", inputs: [L.last], prompt: { before: "Score the relationship from ", chip: L.last, after: "." }, }, links: { label: L.links, type: "URL", tool: "Web search", toolKind: "web", inputs: [L.company], prompt: { before: "Find the website for ", chip: L.company, after: "." }, }, ai: { label: L.ai, type: aiColumn?.type ?? "Text", tool: aiColumn?.tool ?? "Web search", toolKind: "web", inputs: [L.company], prompt: aiColumn?.prompt ?? { before: `Find ${L.ai.toLowerCase()} for `, chip: L.company }, }, }; const config = Object.fromEntries( (Object.keys(baseConfig) as ColumnKey[]).map((k) => [k, { ...baseConfig[k], ...columnConfig[k] }]), ) as Record; const inputOptions = [L.company, L.categories, L.last, L.strength, L.links]; /* ── initial order (server render matches the script's sort) ── */ const rank = (s: Strength) => STRENGTH[s].rank; const lastValue = (r: RecordRow) => (r.lastDays === undefined || r.lastDays === null ? Number.POSITIVE_INFINITY : r.lastDays); const dir = sort.dir ?? 1; const sorted = [...rows].sort((a, b) => { const v = sort.key === "name" ? a.name.localeCompare(b.name) : sort.key === "last" ? lastValue(a) - lastValue(b) || a.name.localeCompare(b.name) : rank(a.strength) - rank(b.strength); return (Number.isNaN(v) ? 0 : v) * dir; }); const avg = rows.length ? Math.round((rows.reduce((sum, r) => sum + rank(r.strength), 0) / rows.length / 3) * 100) : 0; const avgColor = avg >= 67 ? "var(--vs-green)" : avg >= 34 ? "var(--vs-orange)" : "var(--vs-red)"; const linkCount = rows.filter((r) => r.website).length; const ariaSort = (key: string) => (sort.key === key ? (dir === 1 ? "ascending" : "descending") : undefined); const clientConfig = { uid, rows: rows.map((r) => ({ id: r.id, name: r.name, lastDays: lastValue(r), last: r.last, rank: rank(r.strength), ai: r.ai ?? "" })), sort: { key: sort.key, dir }, columns: config, typeGlyphs: TYPE_GLYPHS, toolGlyphs: TOOL_GLYPHS, aiEnabled: aiColumn !== null, }; const rootStyle = [fill ? "" : `--rt-max-h: ${maxHeight}`, typeof style === "string" ? style : ""].filter(Boolean).join("; ") || undefined; const headers: Array<{ key: Exclude; glyph: string; sortKey?: "last" | "strength" }> = [ { key: "categories", glyph: TYPE_GLYPHS["Multi select"] }, { key: "last", glyph: TYPE_GLYPHS.Date, sortKey: "last" }, { key: "strength", glyph: TYPE_GLYPHS["Single select"], sortKey: "strength" }, { key: "links", glyph: TYPE_GLYPHS.URL }, ]; ---

``` --- # Filter Table > Status chips that filter a table in place. - **Slug:** `filter-table` - **Kind:** component · **Category:** Data - **Source:** ported from [Beautiful UI](https://github.com/slev12397/beautiful-ui/blob/main/components/primitives/FilterTable.tsx) (MIT) - **Docs page:** https://viewership.ai/ui/components/filter-table - **All files in one bundle:** https://viewership.ai/ui/components/filter-table.bundle.txt - **Structured JSON:** https://viewership.ai/ui/components/filter-table.json ## Install 1. Import the foundation tokens once (download: https://viewership.ai/ui/raw/foundation.css.txt): ```astro --- // src/layouts/Layout.astro import "../styles/foundation.css"; --- ``` 2. Copy this file into `src/components/viewership/filter-table/`: - `FilterTable.astro` (raw: https://viewership.ai/ui/raw/filter-table/FilterTable.astro.txt) npm packages: none. ## Usage ```astro --- import FilterTable from "../components/viewership/filter-table/FilterTable.astro"; --- ``` ## Example The gallery demo, verbatim. Use the import path from Usage instead of `./`. ```astro --- import FilterTable, { type FilterColumn, type FilterRow } from "./FilterTable.astro"; const columns: FilterColumn[] = [ { key: "task", label: "Task name", width: 1.3, kind: "title" }, { key: "date", label: "Date", width: 0.6, kind: "date" }, { key: "status", label: "Status", width: 0.95, kind: "status" }, { key: "account", label: "Channel", width: 0.9, kind: "muted" }, ]; const rows: FilterRow[] = [ { task: "Draft spring trail email", date: "Dec 03", status: "todo", account: "Email" }, { task: "Review GEO citation report", date: "Sep 22", status: "progress", account: "Perplexity" }, { task: "Approve gear guide video", date: "Jan 02", status: "todo", account: "YouTube" }, { task: "Reply to camping thread", date: "Nov 08", status: "progress", account: "Reddit" }, { task: "Send weekly GA4 report", date: "Apr 14", status: "done", account: "GA4" }, ]; ---

``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `rows` | `Record[]` | `[]` | One object per row, keyed by column key. | | `columns` | `{ key; label; width?; kind?: "title" \| "muted" \| "date" \| "status" }[]` | `task / date / status / owner` | Column order, labels, widths and cell style. | | `statuses` | `{ key; label; tone?: "amber" \| "cyan" \| "green" \| "red" \| "violet" \| "gray" }[]` | `To do / In Progress / Completed` | Filter chips and status pills. Counts come from `rows`. | | `statusKey` | `string` | `"status"` | Row field holding the status key. | | `filter` | `string` | `"all"` | Initial filter. | | `caption` | `string` | `"Tasks"` | Hidden table caption. | | `labels` | `{ all?, filterGroup?, result? }` | | Chip and screen reader text. `result` takes {shown}, {total}, {filter}. | ## Source ### `src/components/viewership/filter-table/FilterTable.astro` ```astro --- /** * FilterTable: status chips that filter a table in place. Chip counts come * from the data. * * Ported from Beautiful UI `components/primitives/FilterTable.tsx` * (MIT, © 2026 Shane Levine). * * @example * * * Events: `vs-filter-change` (detail: { filter, shown, total }) on the root. */ import type { HTMLAttributes } from "astro/types"; export type FilterTone = "amber" | "cyan" | "green" | "red" | "violet" | "gray"; export type FilterStatus = { key: string; label: string; tone?: FilterTone }; export type FilterColumn = { key: string; label: string; /** Relative column width. */ width?: number; /** title = emphasised, muted = secondary ink, date = muted + tabular, status = pill. */ kind?: "title" | "muted" | "date" | "status"; }; export type FilterRow = Record; type Props = HTMLAttributes<"div"> & { rows?: FilterRow[]; columns?: FilterColumn[]; statuses?: FilterStatus[]; /** Row field that holds the status key. */ statusKey?: string; /** Initially selected filter ("all" or a status key). */ filter?: string; /** Visually hidden table caption (also names the scroll region). */ caption?: string; labels?: { all?: string; filterGroup?: string; /** Announced after filtering. Tokens: {shown}, {total}, {filter}. */ result?: string; }; }; const DEFAULT_COLUMNS: FilterColumn[] = [ { key: "task", label: "Task name", width: 1.3, kind: "title" }, { key: "date", label: "Date", width: 0.6, kind: "date" }, { key: "status", label: "Status", width: 0.95, kind: "status" }, { key: "owner", label: "Owner", width: 0.9, kind: "muted" }, ]; const DEFAULT_STATUSES: FilterStatus[] = [ { key: "todo", label: "To do", tone: "amber" }, { key: "progress", label: "In Progress", tone: "cyan" }, { key: "done", label: "Completed", tone: "green" }, ]; const { rows = [], columns = DEFAULT_COLUMNS, statuses = DEFAULT_STATUSES, statusKey = "status", filter = "all", caption = "Tasks", labels, class: className, ...rest } = Astro.props; const text = { all: "All", filterGroup: "Filter by status", result: "{filter}: showing {shown} of {total} rows", ...labels, }; const uid = `vs-ft-${Math.random().toString(36).slice(2, 8)}`; const statusOf = new Map(statuses.map((s) => [s.key, s])); const filters = [ { key: "all", label: text.all, tone: undefined as FilterTone | undefined, count: rows.length }, ...statuses.map((s) => ({ ...s, count: rows.filter((r) => r[statusKey] === s.key).length })), ]; const totalWidth = columns.reduce((n, c) => n + (c.width ?? 1), 0); const shown = (row: FilterRow) => filter === "all" || row[statusKey] === filter; ---

{filters.map((f) => ( ))}

{columns.map((c) => )} {columns.map((c) => )} {rows.map((row) => ( {columns.map((c) => { const value = row[c.key] ?? ""; const status = c.kind === "status" ? statusOf.get(value) : undefined; return ( ); })} ))}

{caption}
{c.label}
{c.kind === "status" ? ( {status?.label ?? value} ) : ( {value} )}

``` ### `src/components/viewership/flowchart/layout.ts` ```ts /** * Flowchart layout math, shared by the server render (estimated heights) * and the client script (measured heights, live width, drag offsets). * Adapted from Beautiful UI Flowchart (MIT, © 2026 Shane Levine). */ const PAD_Y = 24; const ROW_GAP = 64; /** Kind pill + gap above a card. */ export const PILL_OFFSET = 30; export type LayoutNode = { id: string; row: number; x: number; w: number; kind: boolean }; export type Point = { x: number; y: number }; /** Row tops and total canvas height from per-node heights. */ export function rowLayout(nodes: LayoutNode[], heights: Record) { const rows = [...new Set(nodes.map((n) => n.row))].sort((a, b) => a - b); const rowH = rows.map((r) => Math.max(...nodes.filter((n) => n.row === r).map((n) => heights[n.id] ?? 90))); const rowY: number[] = []; rows.forEach((_, i) => { rowY[i] = i === 0 ? PAD_Y : rowY[i - 1] + rowH[i - 1] + ROW_GAP; }); const canvasH = rows.length ? rowY[rows.length - 1] + rowH[rows.length - 1] + PAD_Y : PAD_Y * 2; const topOf = (n: LayoutNode) => rowY[rows.indexOf(n.row)]; return { canvasH, topOf }; } /** The connector between two anchors: a clamped vertical bezier. */ export function bezier(from: Point, to: Point) { const k = Math.min(Math.max(Math.abs(to.y - from.y) * 0.55, 24), 84); return `M ${from.x} ${from.y} C ${from.x} ${from.y + k}, ${to.x} ${to.y - k}, ${to.x} ${to.y}`; } ``` --- # Insight Cards > Paged agent insights with scrubbable SVG charts and follow-up prompts. - **Slug:** `insight-cards` - **Kind:** component · **Category:** Data - **Source:** ported from [Beautiful UI](https://github.com/slev12397/beautiful-ui/blob/main/components/primitives/InsightCards.tsx) (MIT) - **Docs page:** https://viewership.ai/ui/components/insight-cards - **All files in one bundle:** https://viewership.ai/ui/components/insight-cards.bundle.txt - **Structured JSON:** https://viewership.ai/ui/components/insight-cards.json ## Install 1. Import the foundation tokens once (download: https://viewership.ai/ui/raw/foundation.css.txt): ```astro --- // src/layouts/Layout.astro import "../styles/foundation.css"; --- ``` 2. Copy these files into `src/components/viewership/insight-cards/`: - `InsightCards.astro` (raw: https://viewership.ai/ui/raw/insight-cards/InsightCards.astro.txt) - `insight-chart.ts` (raw: https://viewership.ai/ui/raw/insight-cards/insight-chart.ts.txt) npm packages: none. ## Usage ```astro --- import InsightCards from "../components/viewership/insight-cards/InsightCards.astro"; --- ``` ## Example The gallery demo, verbatim. Use the import path from Usage instead of `./`. ```astro --- import InsightCards from "./InsightCards.astro"; import type { InsightPage } from "./insight-chart"; const days = ["Mar 6", "Mar 7", "Mar 8", "Mar 9", "Mar 10", "Mar 11", "Mar 12", "Mar 13"]; const pages: InsightPage[] = [ { key: "channels", prose: [ "The weakest channel for ", { entity: "Northwind", color: "var(--vs-orange)" }, " is Paid Social: down ", { mono: "-6%", tone: "red" }, " or ", { mono: "-$2,453", tone: "red" }, ".", ], card: { kind: "compare", caption: "Revenue vs. last week", series: [ { name: "Paid Social", values: [-2.9, -3.4, -3.05, -3.86, -3.52, -4.1, -3.82, -4.41], sub: "-$2,377", tone: "red", color: "var(--vs-orange)" }, { name: "Organic Search", values: [0.22, 0.58, 0.42, 0.91, 0.76, 1.08, 0.96, 1.15], sub: "+$617", tone: "green", color: "var(--vs-accent)" }, ], labels: days, }, pill: "Should I rebalance the channel mix?", }, { key: "spend", prose: ["Unusually high ad spend on ", { strong: "Mar 13" }, ": ", { mono: "+$1,834", tone: "red" }, " above your daily average."], card: { kind: "anomaly", title: "High ad spend", metrics: [ { key: "spend", label: "Spend", values: [274, 289, 264, 307, 331, 1210, 1718, 2112], format: { style: "money" }, threshold: "$2,112 threshold" }, { key: "usage", label: "Usage", values: [18, 19, 17, 21, 22, 58, 81, 96], format: { style: "unit", unit: "clicks" }, threshold: "82 clicks threshold" }, ], total: "$2,112 spent", delta: "+$1,834", deltaNote: "vs 3 weeks", labels: days, }, pill: "Get tips on cutting wasted ad spend", }, { key: "mix", prose: ["You're heavily reliant on ", { entity: "Organic Search", color: "var(--vs-orange)" }, ": it's ", { strong: "72.5%" }, " of your tracked revenue."], card: { kind: "allocation", title: "Organic Search allocation", monogram: "O", color: "var(--vs-orange)", segments: [ { name: "ORGANIC", label: "Organic Search", pct: 72.5, amount: "$51,785", color: "var(--vs-orange)" }, { name: "PAID", label: "Paid Search", pct: 22.8, amount: "$16,278", color: "var(--vs-line-strong)", tone: "var(--vs-ink-2)" }, { name: "EMAIL", label: "Email", pct: 4.7, amount: "$3,357", color: "var(--vs-line)", tone: "var(--vs-ink-3)" }, ], note: "Share of current attributed revenue. Choosing a channel changes the inspected group without moving the card.", }, pill: "If we add a GEO campaign, what changes?", }, ]; --- ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `pages` | `InsightPage[]` | | { key, prose, card, pill? }. Prose tokens: string, { entity, color? }, { mono, tone }, { strong }. Types are in insight-chart.ts. | | `card (compare)` | `{ kind: "compare"; series: { name, values, sub, tone, color }[]; caption?; badge?; format?; labels? }` | | Two-series comparison with a scrubbable line chart. | | `card (anomaly)` | `{ kind: "anomaly"; title; metrics: { key, label, values, format, threshold }[]; total; delta; deltaNote; color?; labels? }` | | Line chart with a metric toggle. | | `card (allocation)` | `{ kind: "allocation"; title; segments: { name, label, pct, amount, color, tone? }[]; note; monogram?; color? }` | | Segmented bar with legend and detail box. | | `format` | `{ style: "percent" \| "money" \| "unit"; unit?; decimals?; signed?; currency? }` | | Value format in tooltips, readouts and summaries. | | `title` | `string` | `"Insights"` | Pager heading. | | `page` | `number` | `0` | Initial page. | | `autoplay / interval` | `boolean / number` | `false / 6000` | Advance pages while in view. Pauses on hover or focus, stops on interaction, off with reduced motion. | | `Events` | `CustomEvent` | | vs-insight-page { index, key }, vs-insight-ask { key, text }. | ## Source ### `src/components/viewership/insight-cards/InsightCards.astro` ```astro --- /** * InsightCards: paged agent insights. Each page has a sentence with inline * entities and deltas, a mini chart and a suggested follow-up. Card kinds: * comparison chart, anomaly chart with a metric toggle, allocation bar. * * Ported from Beautiful UI `components/primitives/InsightCards.tsx` * (MIT, © 2026 Shane Levine). * Charts are native SVG (see insight-chart.ts) and render on the server. * * - Charts scrub by pointer, or focus (a slider) and use ←/→, Home/End; * Escape clears. Each has a text summary. * - Charts draw in on scroll into view (instantly under reduced motion or * without JS). * - `autoplay` pauses on hover/focus and stops on any interaction. * * Events (bubbling CustomEvents on the root): * vs-insight-page detail: { index, key } * vs-insight-ask detail: { key, text } (the follow-up pill) * * @example * */ import type { HTMLAttributes } from "astro/types"; import { areaPath, domain, formatValue, linePath, niceTicks, smooth, summarize, yOf, ANOMALY_BOX, COMPARE_BOX, type AnomalyCard, type CompareCard, type InsightPage, type ProseEntity, type ProseMono, type ProseStrong, type ProseToken, } from "./insight-chart"; type Props = HTMLAttributes<"div"> & { pages: InsightPage[]; /** Heading shown before the page count. */ title?: string; /** Initially shown page. */ page?: number; /** Advance pages automatically while in view. */ autoplay?: boolean; /** Autoplay interval in ms. */ interval?: number; }; const { pages, title = "Insights", page = 0, autoplay = false, interval = 6000, class: className, ...rest } = Astro.props; const uid = `vs-ic-${Math.random().toString(36).slice(2, 8)}`; const start = Math.min(Math.max(0, page), Math.max(0, pages.length - 1)); const isEntity = (t: ProseToken): t is ProseEntity => typeof t === "object" && "entity" in t; const isMono = (t: ProseToken): t is ProseMono => typeof t === "object" && "mono" in t; const isStrong = (t: ProseToken): t is ProseStrong => typeof t === "object" && "strong" in t; const compareChart = (card: CompareCard) => { const f = card.format ?? { style: "percent" as const }; const dense = card.series.map((s) => smooth(s.values)); const dom = domain(dense); return { f, dense, dom, lines: dense.map((d) => linePath(d, dom, COMPARE_BOX)), areas: dense.map((d) => areaPath(d, dom, COMPARE_BOX)), ends: dense.map((d) => yOf(d[d.length - 1] ?? 0, dom, COMPARE_BOX)), summary: summarize(card.series, f, card.labels), last: card.series.map((s) => s.values[s.values.length - 1] ?? 0), }; }; const anomalyChart = (card: AnomalyCard) => { const m = card.metrics[0]; const dense = smooth(m.values); const dom = domain([dense]); return { m, line: linePath(dense, dom, ANOMALY_BOX), end: yOf(dense[dense.length - 1] ?? 0, dom, ANOMALY_BOX), ticks: niceTicks(dom, 3).map((v) => ({ v, y: yOf(v, dom, ANOMALY_BOX), label: formatValue(v, { ...m.format, signed: false }) })), summary: summarize([{ name: m.label, values: m.values }], m.format, card.labels), }; }; const xLabels = (labels?: string[]) => labels?.length ? [labels[0], labels[Math.floor((labels.length - 1) / 2)], labels[labels.length - 1]] : null; const chevrons = ["M15 18l-6-6 6-6", "M9 6l6 6-6 6"]; ---

``` ### `src/components/viewership/insight-cards/insight-chart.ts` ```ts /** * insight-chart: types and chart maths for . * * Ported from Beautiful UI `components/primitives/InsightCards.tsx` * (MIT, © 2026 Shane Levine). Native SVG line chart: Catmull-Rom * smoothing, paths, grid ticks, value formatting and a text summary. No DOM * access, so server render and client script share it. */ export type Tone = "red" | "green"; /** Prose is a list of tokens: plain strings, @entities, mono deltas and emphasis. */ export interface ProseEntity { entity: string; /** Dot color, any CSS color. */ color?: string; } export interface ProseMono { mono: string; tone: Tone; } export interface ProseStrong { strong: string; } export type ProseToken = string | ProseEntity | ProseMono | ProseStrong; export interface ValueFormat { style: "percent" | "money" | "unit"; /** Suffix for style "unit", e.g. "clicks". */ unit?: string; /** Fraction digits (percent defaults to 2, others to 0). */ decimals?: number; /** Prefix positive values with "+" (percent defaults to true). */ signed?: boolean; /** Currency symbol for style "money". Default "$". */ currency?: string; } export interface CompareSeries { name: string; values: number[]; /** Mono sub-line under the big value, e.g. "-$2,377.66". */ sub: string; tone: Tone; /** Line color, any CSS color. */ color: string; } export interface CompareCard { kind: "compare"; /** Chart toolbar caption. */ caption?: string; badge?: string; series: CompareSeries[]; format?: ValueFormat; /** X-axis labels, one per value (first, middle and last are shown). */ labels?: string[]; } export interface AnomalyMetric { key: string; label: string; values: number[]; format: ValueFormat; /** Shown in the chart toolbar when not scrubbing, e.g. "$2,112 threshold". */ threshold: string; } export interface AnomalyCard { kind: "anomaly"; title: string; badge?: string; metrics: AnomalyMetric[]; /** Line color. Default var(--vs-red). */ color?: string; /** Footer: big value, mono delta and a note. */ total: string; delta: string; deltaTone?: Tone; deltaNote: string; labels?: string[]; } export interface AllocationSegment { name: string; label: string; pct: number; amount: string; /** Segment fill, any CSS color. */ color: string; /** Label color in the detail box (defaults to `color`). */ tone?: string; } export interface AllocationCard { kind: "allocation"; title: string; monogram?: string; /** Monogram disc color. */ color?: string; segments: AllocationSegment[]; note: string; } export type InsightCard = CompareCard | AnomalyCard | AllocationCard; export interface InsightPage { key: string; prose: ProseToken[]; card: InsightCard; /** Suggested follow-up shown as a pill button. */ pill?: string; } /* ── maths ─────────────────────────────────────────────── */ export const SAMPLES_PER_SEGMENT = 9; export const VIEW_W = 1000; /** Catmull-Rom resample: a sparse series becomes a dense, smoothly curved one. */ export function smooth(values: number[], perSegment = SAMPLES_PER_SEGMENT): number[] { if (values.length < 3) return values.slice(); const out: number[] = []; const n = values.length; for (let i = 0; i < n - 1; i += 1) { const p0 = values[Math.max(0, i - 1)]; const p1 = values[i]; const p2 = values[i + 1]; const p3 = values[Math.min(n - 1, i + 2)]; for (let s = 0; s < perSegment; s += 1) { const t = s / perSegment; const t2 = t * t; const t3 = t2 * t; out.push(0.5 * (2 * p1 + (-p0 + p2) * t + (2 * p0 - 5 * p1 + 4 * p2 - p3) * t2 + (-p0 + 3 * p1 - 3 * p2 + p3) * t3)); } } out.push(values[n - 1]); return out; } export interface Box { height: number; top: number; bottom: number; } /** Plot boxes (px in the 1000x166 viewBox); must match the viewBox in InsightCards.astro. */ export const COMPARE_BOX: Box = { height: 166, top: 40, bottom: 22 }; export const ANOMALY_BOX: Box = { height: 166, top: 34, bottom: 22 }; export function domain(series: number[][]): [number, number] { const all = series.flat(); let min = Math.min(...all); let max = Math.max(...all); if (!Number.isFinite(min) || !Number.isFinite(max)) return [0, 1]; if (min === max) { min -= 1; max += 1; } const pad = (max - min) * 0.06; return [min - pad, max + pad]; } export function yOf(value: number, [min, max]: [number, number], box: Box): number { const plot = box.height - box.top - box.bottom; return box.top + (1 - (value - min) / (max - min)) * plot; } /** SVG path for a dense series across the full view width. */ export function linePath(dense: number[], dom: [number, number], box: Box): string { if (!dense.length) return ""; const step = dense.length > 1 ? VIEW_W / (dense.length - 1) : 0; return dense.map((v, i) => `${i ? "L" : "M"}${(i * step).toFixed(1)},${yOf(v, dom, box).toFixed(1)}`).join(""); } export function areaPath(dense: number[], dom: [number, number], box: Box): string { const line = linePath(dense, dom, box); return line ? `${line}L${VIEW_W},${box.height}L0,${box.height}Z` : ""; } /** About `count` round tick values inside the domain. */ export function niceTicks([min, max]: [number, number], count = 3): number[] { const raw = (max - min) / (count + 1); const mag = 10 ** Math.floor(Math.log10(raw)); const norm = raw / mag; const step = (norm >= 5 ? 5 : norm >= 2 ? 2 : 1) * mag; const ticks: number[] = []; for (let v = Math.ceil(min / step) * step; v <= max; v += step) ticks.push(Number(v.toFixed(10))); return ticks; } export function formatValue(value: number, f: ValueFormat = { style: "percent" }): string { const decimals = f.decimals ?? (f.style === "percent" ? 2 : 0); const signed = f.signed ?? f.style === "percent"; const abs = Math.abs(value).toLocaleString("en-US", { minimumFractionDigits: decimals, maximumFractionDigits: decimals }); const sign = value < 0 ? "-" : signed && value > 0 ? "+" : ""; if (f.style === "percent") return `${sign}${abs}%`; if (f.style === "money") return `${sign}${f.currency ?? "$"}${abs}`; return `${sign}${abs}${f.unit ? ` ${f.unit}` : ""}`; } /** Plain-language chart summary for assistive tech. */ export function summarize(series: Array<{ name: string; values: number[] }>, f: ValueFormat, labels?: string[]): string { const span = labels?.length ? ` from ${labels[0]} to ${labels[labels.length - 1]}` : ` over ${series[0]?.values.length ?? 0} readings`; const parts = series.map((s) => { const first = s.values[0] ?? 0; const last = s.values[s.values.length - 1] ?? 0; const peak = Math.max(...s.values); const low = Math.min(...s.values); const dir = last > first ? "rose" : last < first ? "fell" : "held"; return `${s.name} ${dir} from ${formatValue(first, f)} to ${formatValue(last, f)} (high ${formatValue(peak, f)}, low ${formatValue(low, f)})`; }); return `Line chart${span}. ${parts.join("; ")}.`; } ``` --- # Code Block > Line-numbered code listing with copy, or a unified diff. - **Slug:** `code-block` - **Kind:** component · **Category:** Content - **Source:** ported from [Beautiful UI](https://github.com/slev12397/beautiful-ui/blob/main/components/primitives/CodeBlock.tsx) (MIT) - **Docs page:** https://viewership.ai/ui/components/code-block - **All files in one bundle:** https://viewership.ai/ui/components/code-block.bundle.txt - **Structured JSON:** https://viewership.ai/ui/components/code-block.json ## Install 1. Import the foundation tokens once (download: https://viewership.ai/ui/raw/foundation.css.txt): ```astro --- // src/layouts/Layout.astro import "../styles/foundation.css"; --- ``` 2. Copy these files into `src/components/viewership/code-block/`: - `CodeBlock.astro` (raw: https://viewership.ai/ui/raw/code-block/CodeBlock.astro.txt) - `highlight.ts` (raw: https://viewership.ai/ui/raw/code-block/highlight.ts.txt) npm packages: none. ## Usage ```astro --- import CodeBlock from "../components/viewership/code-block/CodeBlock.astro"; --- ``` ## Example The gallery demo, verbatim. Use the import path from Usage instead of `./`. ```astro --- import CodeBlock from "./CodeBlock.astro"; interface Props { variant?: string; } const { variant = "Code" } = Astro.props; const before = `export async function draftPost() { const brief = await getBrief("spring-trails"); const data = await ga4.fetch({ brief }); await voice.apply(data, { tone: "plain" }); return data.summary; }`; const after = `export async function draftPost() { const brief = await getBrief("spring-trails"); const data = await ga4.fetch({ brief }); await voice.apply(data, { tone: "direct" }); if (!data.approved) return null; return data.summary; }`; const brief = `{ "campaign": "Spring Trails", "channel": "Email", "drafts": 12, "score": 87.5, "approved": true, "publishDate": null }`; ---

{variant === "Code" && } {variant === "Diff" && } {variant === "JSON" && }

``` ## Variants Demo variants: `Code`, `Diff`, `JSON`. ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `variant` | `"code" \| "diff"` | `"code"` | Code listing or unified diff. | | `code` | `string` | | Source text for the code view. | | `lines` | `string[]` | | Alternative to `code`: one string per line. | | `language` | `"ts" \| "js" \| "json" \| "text"` | | Highlighting hint. Inferred from `filename`. | | `diff` | `DiffRow[] \| { before: string; after: string }` | | Diff rows, or two texts diffed at build time. | | `filename` | `string` | `"index.ts"` | Shown in the header. | | `copyText` | `string` | | Clipboard text. Defaults to the listing. | | `labels` | `{ copy?, copied?, copiedAnnouncement? }` | | Copy button and screen reader text. | ## Source ### `src/components/viewership/code-block/CodeBlock.astro` ```astro --- /** * CodeBlock: a light editor panel with two views. * - code: line-numbered listing with a Copy button * - diff: unified diff with word-level add/del highlights * Syntax colouring happens at build time, so no-JS renders fully. * * Adapted from Beautiful UI CodeBlock (MIT, © 2026 Shane Levine). * * @example * * * * Events: `vs-code-copy` (detail: { text }) fires on the root after a copy. */ import type { HTMLAttributes } from "astro/types"; import { diffLines, languageFor, tokenize, tokenizeLines, type DiffRow, type Language } from "./highlight"; export type { CodePiece, DiffRow, Language } from "./highlight"; type Props = HTMLAttributes<"div"> & { /** "code" (line-numbered listing) or "diff" (unified diff). */ variant?: "code" | "diff"; /** Source text for the code view (split on newlines). */ code?: string; /** Alternative to `code`: one string per line. */ lines?: string[]; /** Language hint for highlighting. Inferred from `filename` when omitted. */ language?: Language; /** Diff view: explicit rows, or two texts to diff at build time. */ diff?: DiffRow[] | { before: string; after: string }; /** Filename shown in the header (also the region's accessible name). */ filename?: string; /** Text placed on the clipboard; defaults to the listing. */ copyText?: string; labels?: { copy?: string; copied?: string; copiedAnnouncement?: string }; }; const { variant = "code", code, lines, language, diff = [], filename = "index.ts", copyText, labels, class: className, ...rest } = Astro.props; const text = { copy: "Copy", copied: "Copied", copiedAnnouncement: "Code copied to clipboard", ...labels }; const lang = language ?? languageFor(filename); const isDiff = variant === "diff"; const source = code ?? (lines ?? []).join("\n"); const listing = isDiff ? [] : tokenizeLines(source.replace(/\n$/, ""), lang); const rows: DiffRow[] = Array.isArray(diff) ? diff : diffLines(diff.before, diff.after); const added = rows.filter((r) => r.type === "add").length; const removed = rows.filter((r) => r.type === "del").length; const gutter = Math.max(isDiff ? Math.max(0, ...rows.map((r) => r.old ?? r.cur ?? 0)) : listing.length, 1); const gutterWidth = gutter >= 100 ? 28 : 20; const config = JSON.stringify({ text: copyText ?? source, copied: text.copied, announce: text.copiedAnnouncement }); ---

{filename} {isDiff ? ( ) : ( <> ``` ### `src/components/viewership/code-block/highlight.ts` ```ts /** * Build-time helpers for CodeBlock: a JS/TS/JSON tokenizer and a unified * line diff with word-level pieces. * * Adapted from Beautiful UI CodeBlock (MIT, © 2026 Shane Levine). */ export type Language = "ts" | "js" | "json" | "text"; export type TokenKind = "keyword" | "string" | "number" | "fn" | "key" | "comment"; export type Token = { text: string; kind?: TokenKind }; /** A run of code within a diff row; `change` marks a word-level add/del. */ export type CodePiece = { text: string; change?: "add" | "del" }; /** One row of a unified diff: old/new line numbers, its kind, and its pieces. */ export type DiffRow = { old: number | null; cur: number | null; type: "ctx" | "add" | "del"; pieces: CodePiece[]; }; const JS_KEYWORDS = new Set([ "import", "from", "export", "default", "async", "function", "const", "let", "var", "await", "return", "if", "else", "for", "while", "new", "throw", "try", "catch", "null", "true", "false", "undefined", "type", "interface", "as", "of", "in", "class", "extends", "switch", "case", "break", "continue", "this", "typeof", "satisfies", ]); const JS_TOKEN = /(\/\/[^\n]*|\/\*[\s\S]*?\*\/)|("(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*'|`(?:\\.|[^`\\])*`)|(\b\d+(?:\.\d+)?\b)|([A-Za-z_$][\w$]*)/g; const JSON_TOKEN = /("(?:\\.|[^"\\\n])*")|(-?\b\d+(?:\.\d+)?(?:[eE][+-]?\d+)?\b)|\b(true|false|null)\b/g; /** Infer a language from a filename extension. */ export function languageFor(filename = ""): Language { const ext = filename.split(".").pop()?.toLowerCase() ?? ""; if (ext === "json" || ext === "jsonc") return "json"; if (["js", "mjs", "cjs", "jsx"].includes(ext)) return "js"; return "ts"; } /** Tokenize source text. Unmatched text becomes plain (kind-less) tokens. */ export function tokenize(text: string, language: Language = "ts"): Token[] { if (language === "text") return [{ text }]; const out: Token[] = []; let last = 0; const push = (t: string, kind?: TokenKind) => { if (!t) return; const prev = out[out.length - 1]; if (!kind && prev && !prev.kind) prev.text += t; else out.push({ text: t, kind }); }; const re = new RegExp(language === "json" ? JSON_TOKEN : JS_TOKEN); for (const m of text.matchAll(re)) { const idx = m.index ?? 0; const rest = text.slice(idx + m[0].length); push(text.slice(last, idx)); if (language === "json") { if (m[1]) push(m[1], /^\s*:/.test(rest) ? "key" : "string"); else if (m[2]) push(m[2], "number"); else push(m[0], "keyword"); } else if (m[1]) push(m[1], "comment"); else if (m[2]) push(m[2], "string"); else if (m[3]) push(m[3], "number"); else if (m[4] && JS_KEYWORDS.has(m[4])) push(m[4], "keyword"); else if (m[4] && /^\s*\(/.test(rest)) push(m[4], "fn"); else push(m[0]); last = idx + m[0].length; } push(text.slice(last)); return out; } /** Tokenize a whole listing, then split it into per-line token arrays * (so block comments and template strings may span lines). */ export function tokenizeLines(text: string, language: Language = "ts"): Token[][] { const lines: Token[][] = [[]]; for (const tok of tokenize(text, language)) { tok.text.split("\n").forEach((part, i) => { if (i > 0) lines.push([]); if (part) lines[lines.length - 1].push({ text: part, kind: tok.kind }); }); } return lines; } /* ── diff ── */ function lcsTable(a: T[], b: T[]): number[][] { const t = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0)); for (let i = a.length - 1; i >= 0; i--) for (let j = b.length - 1; j >= 0; j--) t[i][j] = a[i] === b[j] ? t[i + 1][j + 1] + 1 : Math.max(t[i + 1][j], t[i][j + 1]); return t; } type Op = { type: "ctx" | "add" | "del"; value: T; ai: number; bi: number }; function diffSeq(a: T[], b: T[]): Op[] { const t = lcsTable(a, b); const ops: Op[] = []; let i = 0; let j = 0; while (i < a.length && j < b.length) { if (a[i] === b[j]) ops.push({ type: "ctx", value: a[i], ai: i++, bi: j++ }); else if (t[i + 1][j] >= t[i][j + 1]) ops.push({ type: "del", value: a[i], ai: i++, bi: -1 }); else ops.push({ type: "add", value: b[j], ai: -1, bi: j++ }); } while (i < a.length) ops.push({ type: "del", value: a[i], ai: i++, bi: -1 }); while (j < b.length) ops.push({ type: "add", value: b[j], ai: -1, bi: j++ }); return ops; } const WORD = /"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`[^`]*`|[\w$]+|\s+|[^\w$\s]/g; /** Word-level pieces for a removed/added line pair. Returns null when the * lines share too little to make a highlight meaningful. */ function wordPieces(before: string, after: string): [CodePiece[], CodePiece[]] | null { const a = before.match(WORD) ?? []; const b = after.match(WORD) ?? []; const ops = diffSeq(a, b); const common = ops.filter((o) => o.type === "ctx").reduce((n, o) => n + o.value.trim().length, 0); const longest = Math.max(before.trim().length, after.trim().length, 1); if (common / longest < 0.4) return null; const build = (side: "del" | "add") => { const pieces: CodePiece[] = []; const kept = ops.filter((o) => o.type === "ctx" || o.type === side); kept.forEach((o, k) => { let changed = o.type === side; // whitespace sandwiched between two changes joins the highlight if (!changed && /^\s+$/.test(o.value) && kept[k - 1]?.type === side && kept[k + 1]?.type === side) changed = true; const prev = pieces[pieces.length - 1]; const change = changed ? side : undefined; if (prev && prev.change === change) prev.text += o.value; else pieces.push({ text: o.value, change }); }); return pieces; }; return [build("del"), build("add")]; } /** Unified diff of two texts, with word-level highlights on paired lines. */ export function diffLines(before: string, after: string): DiffRow[] { const ops = diffSeq(before.split("\n"), after.split("\n")); const rows: DiffRow[] = []; let k = 0; while (k < ops.length) { const op = ops[k]; if (op.type === "ctx") { rows.push({ old: op.ai + 1, cur: op.bi + 1, type: "ctx", pieces: [{ text: op.value }] }); k++; continue; } // a hunk: every consecutive del/add, rendered dels-then-adds const dels: Op[] = []; const adds: Op[] = []; while (k < ops.length && ops[k].type !== "ctx") (ops[k].type === "del" ? dels : adds).push(ops[k++]); const pairs = dels.map((d, i) => (adds[i] ? wordPieces(d.value, adds[i].value) : null)); dels.forEach((d, i) => rows.push({ old: d.ai + 1, cur: null, type: "del", pieces: pairs[i]?.[0] ?? [{ text: d.value }] }), ); adds.forEach((a, i) => rows.push({ old: null, cur: a.bi + 1, type: "add", pieces: pairs[i]?.[1] ?? [{ text: a.value }] }), ); } return rows; } ``` --- # Fine-tune Card > Compact inspector the agent adjusts, then hands back to you. - **Slug:** `fine-tune-card` - **Kind:** component · **Category:** Agent - **Source:** ported from [Beautiful UI](https://github.com/slev12397/beautiful-ui/blob/main/components/primitives/FineTuneCard.tsx) (MIT) - **Docs page:** https://viewership.ai/ui/components/fine-tune-card - **All files in one bundle:** https://viewership.ai/ui/components/fine-tune-card.bundle.txt - **Structured JSON:** https://viewership.ai/ui/components/fine-tune-card.json ## Install 1. Import the foundation tokens once (download: https://viewership.ai/ui/raw/foundation.css.txt): ```astro --- // src/layouts/Layout.astro import "../styles/foundation.css"; --- ``` 2. Copy this file into `src/components/viewership/fine-tune-card/`: - `FineTuneCard.astro` (raw: https://viewership.ai/ui/raw/fine-tune-card/FineTuneCard.astro.txt) 3. Copy its registry dependencies, each into its own sibling folder under `src/components/viewership/`: - `glide-menu`: `GlideMenu.astro`, `glide-menu.ts` (docs: https://viewership.ai/ui/components/glide-menu.md) npm packages: none. ## Usage ```astro --- import FineTuneCard from "../components/viewership/fine-tune-card/FineTuneCard.astro"; --- ``` ## Example The gallery demo, verbatim. Use the import path from Usage instead of `./`. ```astro --- import FineTuneCard from "./FineTuneCard.astro"; import type { FineTuneEdit, FineTuneField } from "./FineTuneCard.astro"; const fields: FineTuneField[] = [ { key: "width", label: "W", name: "Width", value: 324, min: 40, max: 999 }, { key: "height", label: "H", name: "Height", value: 96, min: 24, max: 999 }, { key: "radius", label: "Radius", value: 28, min: 0, max: 64 }, { key: "opacity", label: "Opacity", value: 100, min: 0, max: 100, suffix: "%" }, ]; // What the agent changes when the card scrolls into view. const edits: FineTuneEdit[] = [ { field: "radius", value: 14 }, { field: "height", value: 120 }, { layout: 2 }, { type: "Launch" }, ]; ---

``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `fields` | `{ key; label; name?; value; min; max; step?; suffix? }[]` | | Scrub-able number fields in pairs. `name` is the full accessible name when label is short. | | `options` | `string[]` | | Type menu options. | | `layout` | `0 \| 1 \| 2` | `0` | Initial layout: row, column, grid. | | `type` | `string` | | Initial type. Empty shows the placeholder. | | `edits` | `{ field?: string; value?: number; layout?: number; type?: string }[]` | `[]` | Changes the agent makes, in order, when scrolled into view. Interaction takes over. | | `autoplay` | `boolean` | `true` | Play edits on scroll into view. | | `loop` | `boolean` | `false` | Replay after a 4s hold until interaction. | | `labels` | `Partial` | | Text overrides: title, layout, type, placeholder, adjust, edited, layouts. | | `vs-fine-tune-change` | `CustomEvent<{ layout; layoutName; values; type; source: "user" \| "agent" }>` | | Fires on every change, by you or the agent. | ## Source ### `src/components/viewership/fine-tune-card/FineTuneCard.astro` ```astro --- /** * FineTuneCard: a compact inspector the agent (and you) can adjust. * * Adapted from Beautiful UI FineTuneCard (MIT, © 2026 Shane Levine). * * A layout switch (row / column / grid), scrub-able number fields and a type * menu. Drag a field's label sideways, use up/down arrows (Shift for x10), or * type. Changed fields turn accent and the header flips from "Adjust" to * "Edited". * * Pass `edits` to have the agent make changes when the card scrolls into * view. Any interaction hands control back to you. Without JS or with * reduced motion, the edits render already applied. * * Number fields are labelled text inputs with spinbutton semantics, the * layout switch is a radio group, and the type menu is a listbox. Each has a * `name` so the card can sit inside a form. * * Events (bubbling, on the root): * vs-fine-tune-change detail: { layout, layoutName, values, type, source: "user" | "agent" } * * @example * */ import type { HTMLAttributes } from "astro/types"; import GlideMenu from "../glide-menu/GlideMenu.astro"; export interface FineTuneField { key: string; /** Visible label (the scrub handle), e.g. "W". */ label: string; /** Full accessible name when the label is abbreviated, e.g. "Width". */ name?: string; /** Starting value; the field turns accent once it differs. */ value: number; min: number; max: number; step?: number; suffix?: string; } /** One agent step: set a field, the layout, or the type. */ export interface FineTuneEdit { /** Field key to change (with `value`). */ field?: string; value?: number; /** Layout index: 0 row, 1 column, 2 grid. */ layout?: number; /** Type option to pick. */ type?: string; } export interface FineTuneCardLabels { title: string; layout: string; type: string; placeholder: string; adjust: string; edited: string; /** Names of the three layout options. */ layouts: [string, string, string]; } type Props = HTMLAttributes<"div"> & { fields: FineTuneField[]; /** Options in the Type menu. */ options: string[]; labels?: Partial; /** Initial layout index. */ layout?: number; /** Initial type (defaults to the placeholder). */ type?: string; /** Changes the agent makes on its own. */ edits?: FineTuneEdit[]; /** Play `edits` when scrolled into view. */ autoplay?: boolean; /** Replay the edits after a hold, until someone interacts. */ loop?: boolean; }; const { fields = [], options = [], labels, layout = 0, type, edits = [], autoplay = true, loop = false, class: className, ...rest } = Astro.props; const l: FineTuneCardLabels = { title: "Card", layout: "Layout", type: "Type", placeholder: "Select type", adjust: "Adjust", edited: "Edited", layouts: ["Row", "Column", "Grid"], ...labels, }; const uid = `vs-ftc-${Math.random().toString(36).slice(2, 8)}`; /* The no-JS / reduced-motion render shows the agent's edits already applied. */ const initial = { layout, type: type ?? "", values: Object.fromEntries(fields.map((f) => [f.key, f.value])) as Record, }; const final = { layout: initial.layout, type: initial.type, values: { ...initial.values } }; for (const e of edits) { if (e.field !== undefined && e.value !== undefined && e.field in final.values) final.values[e.field] = e.value; if (e.layout !== undefined) final.layout = e.layout; if (e.type !== undefined) final.type = e.type; } const changed = final.layout !== layout || final.type !== initial.type || fields.some((f) => final.values[f.key] !== f.value); const pairs: FineTuneField[][] = []; for (let i = 0; i < fields.length; i += 2) pairs.push(fields.slice(i, i + 2)); const config = { initial, edits, layouts: l.layouts, placeholder: l.placeholder }; ---

``` --- # Selection Actions > Select text and a floating toolbar rewrites it in place. - **Slug:** `selection-actions` - **Kind:** component · **Category:** Agent - **Source:** ported from [Beautiful UI](https://github.com/slev12397/beautiful-ui/blob/main/components/primitives/SelectionActions.tsx) (MIT) - **Docs page:** https://viewership.ai/ui/components/selection-actions - **All files in one bundle:** https://viewership.ai/ui/components/selection-actions.bundle.txt - **Structured JSON:** https://viewership.ai/ui/components/selection-actions.json ## Install 1. Import the foundation tokens once (download: https://viewership.ai/ui/raw/foundation.css.txt): ```astro --- // src/layouts/Layout.astro import "../styles/foundation.css"; --- ``` 2. Copy this file into `src/components/viewership/selection-actions/`: - `SelectionActions.astro` (raw: https://viewership.ai/ui/raw/selection-actions/SelectionActions.astro.txt) 3. Copy its registry dependencies, each into its own sibling folder under `src/components/viewership/`: - `button`: `Button.astro` (docs: https://viewership.ai/ui/components/button.md) - `shimmer`: `Shimmer.astro` (docs: https://viewership.ai/ui/components/shimmer.md) - `stream-text`: `StreamText.astro`, `stream-text.ts` (docs: https://viewership.ai/ui/components/stream-text.md) npm packages: none. ## Usage ```astro --- import SelectionActions from "../components/viewership/selection-actions/SelectionActions.astro"; --- ``` ## Example The gallery demo, verbatim. Use the import path from Usage instead of `./`. ```astro --- import SelectionActions, { type SelectionSegment } from "./SelectionActions.astro"; const passage: SelectionSegment[] = [ { text: "The trail pack page gets most AI citations. ", rewrite: "Most AI citations point to the trail pack page. " }, { text: "Keep it in this week's client report. ", rewrite: "Add it to this week's Northwind report. " }, { text: "Update it first thing Friday so the copy has a full day for review before the weekend launch.", rewrites: { Improve: "Update the trail pack page Friday morning so the copy gets a full day of review before launch.", Shorten: "Update it Friday morning so review finishes before launch.", "Change tone": "Let's update it first thing Friday, so the team has a full day to review before launch.", "Fix grammar": "Update it first thing on Friday so the copy has a full day for review before the weekend launch.", custom: "Update the trail pack page at 9 am Friday. A full review day keeps the launch copy on brand.", }, }, ]; --- ``` ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `passage` | `{ text, rewrites?, rewrite? }[]` | | Segments (usually sentences). Selection snaps to them. `rewrites` is keyed by action or "custom"; `rewrite` is the fallback. | | `selected` | `number \| [number, number]` | `0` | Initial segment or inclusive range. | | `actions` | `{ primary: SelectionAction[]; more: SelectionAction[] }` | `Explain, Improve · Shorten, Tone, Grammar` | { id, icon?, action?, busyLabel? }. Omit `action` for non-rewrite actions. | | `labels` | `{ keep?, discard?, placeholder?, toolbar? }` | | UI and aria text. | | `autoShow` | `boolean` | `true` | Show the toolbar once in view. | | `Events` | `CustomEvent` | | vs-selection-action { action, prompt?, text, rewrite, respondWith(text \| Promise) }, vs-selection-keep { original, text }, vs-selection-discard { original }. | ## Source ### `src/components/viewership/selection-actions/SelectionActions.astro` ```astro --- /** * SelectionActions: select text and a floating toolbar rewrites it in place. * Running an action shimmers a busy label, streams the rewrite, then asks * to Keep, Discard or Try again. * * Ported from Beautiful UI `components/primitives/SelectionActions.tsx` * (MIT, © 2026 Shane Levine). Icons are Lucide (ISC) equivalents. * * The passage is a list of segments (usually sentences). Mouse selection, * tapping a sentence, or ←/→ (Shift to extend) snaps to whole segments. * Tab enters the toolbar; Escape returns to the passage. * * Rewrites come from each segment's `rewrites` (keyed by action or "custom") * or `rewrite`. To produce your own, listen for `vs-selection-action` and * call `event.detail.respondWith(stringOrPromise)` synchronously. * * Events (bubbling, on the root): * vs-selection-action detail: { action, prompt?, text, rewrite: boolean, respondWith(text | Promise) } * vs-selection-keep detail: { original, text } * vs-selection-discard detail: { original } * * @example * */ import type { HTMLAttributes } from "astro/types"; import Button from "../button/Button.astro"; import Shimmer from "../shimmer/Shimmer.astro"; export interface SelectionSegment { text: string; /** Rewrite per action name (e.g. "Improve", "Shorten", "Change tone", "Fix grammar", or "custom"). */ rewrites?: Record; /** Fallback rewrite for any action. */ rewrite?: string; } export interface SelectionAction { /** Visible label. */ id: string; /** Built-in icon (explain, improve, shorten, tone, grammar) or inner SVG markup. */ icon?: string; /** Action name sent with the event and used to pick a rewrite. Omit for actions that don't rewrite (e.g. Explain). */ action?: string; /** Gerund shown while it runs, e.g. "Improving". */ busyLabel?: string; } export interface SelectionActionSet { primary: SelectionAction[]; more: SelectionAction[]; } export interface SelectionLabels { keep: string; discard: string; placeholder: string; toolbar: string; } type Props = HTMLAttributes<"div"> & { passage: SelectionSegment[]; /** Initially selected segment index, or an inclusive [start, end] range. */ selected?: number | [number, number]; actions?: SelectionActionSet; labels?: Partial; /** Show the toolbar for the initial selection once in view. */ autoShow?: boolean; }; const DEFAULT_ACTIONS: SelectionActionSet = { primary: [ { id: "Explain", icon: "explain" }, { id: "Improve", icon: "improve", action: "Improve", busyLabel: "Improving" }, ], more: [ { id: "Shorten", icon: "shorten", action: "Shorten", busyLabel: "Shortening" }, { id: "Tone", icon: "tone", action: "Change tone", busyLabel: "Changing tone" }, { id: "Grammar", icon: "grammar", action: "Fix grammar" }, ], }; const { passage, selected = 0, actions = DEFAULT_ACTIONS, labels = {}, autoShow = true, class: className, ...rest } = Astro.props; const copy: SelectionLabels = { keep: "Keep", discard: "Discard", placeholder: "Describe edits", toolbar: "Edit selection", ...labels }; const uid = `vs-sa-${Math.random().toString(36).slice(2, 8)}`; const [selStart, selEnd] = Array.isArray(selected) ? selected : [selected, selected]; /* Lucide (ISC) */ const ICONS: Record = { explain: '', improve: '', shorten: '', tone: '', grammar: '', send: '', chevron: '', check: '', close: '', retry: '', }; const icon = (name: string | undefined, size = 14, sw = 1.8) => { const inner = !name ? "" : name.includes("<") ? name : (ICONS[name] ?? ""); return ``; }; const clientConfig = { segments: passage.map((s) => ({ text: s.text, rewrites: s.rewrites ?? {}, rewrite: s.rewrite ?? null })), selected: [selStart, selEnd], busy: Object.fromEntries([...actions.primary, ...actions.more].filter((a) => a.action).map((a) => [a.action, a.busyLabel ?? "Editing"])), autoShow, }; ---

``` --- # Agent Screen > An agent's live screen with an expandable viewer and recording. - **Slug:** `agent-screen` - **Kind:** component · **Category:** Agent - **Source:** ported from [Beautiful UI](https://github.com/slev12397/beautiful-ui/blob/main/components/primitives/AgentScreen.tsx) (MIT) - **Docs page:** https://viewership.ai/ui/components/agent-screen - **All files in one bundle:** https://viewership.ai/ui/components/agent-screen.bundle.txt - **Structured JSON:** https://viewership.ai/ui/components/agent-screen.json ## Install 1. Import the foundation tokens once (download: https://viewership.ai/ui/raw/foundation.css.txt): ```astro --- // src/layouts/Layout.astro import "../styles/foundation.css"; --- ``` 2. Copy this file into `src/components/viewership/agent-screen/`: - `AgentScreen.astro` (raw: https://viewership.ai/ui/raw/agent-screen/AgentScreen.astro.txt) 3. Copy its registry dependencies, each into its own sibling folder under `src/components/viewership/`: - `button`: `Button.astro` (docs: https://viewership.ai/ui/components/button.md) npm packages: none. ## Usage ```astro --- import AgentScreen from "../components/viewership/agent-screen/AgentScreen.astro"; --- ``` ## Example The gallery demo, verbatim. Use the import path from Usage instead of `./`. ```astro --- import AgentScreen from "./AgentScreen.astro"; interface Props { variant?: string; } const { variant = "Working" } = Astro.props; ---

``` ## Variants Demo variants: `Working`, `Loading`. ## Props | Prop | Type | Default | Description | | --- | --- | --- | --- | | `agentName` | `string` | `"Agent"` | Caption and viewer title. | | `state` | `"live" \| "connecting"` | `"live"` | connecting disables opening. | | `src` | `string` | | Image or video URL. Falls back to a sample desktop. | | `` | `HTML` | | Custom screen markup. Size in em or cqw. | | `labels` | `Partial` | | Text overrides. | | `vs-agent-screen-open / -close` | `CustomEvent` | | Fires when the viewer opens or collapses. | | `vs-agent-screen-record` | `CustomEvent<{ recording: true }>` | | Fires when recording starts. | | `vs-agent-screen-end` | `CustomEvent<{ seconds: number }>` | | Fires when recording ends. | ## Source ### `src/components/viewership/agent-screen/AgentScreen.astro` ```astro --- /** * AgentScreen: a card showing an agent's screen, with a viewer and recording. * * Ported from Beautiful UI `components/primitives/AgentScreen.tsx` * (MIT, © 2026 Shane Levine). * * Hover or focus shows "Open", which expands a native