@signalflare-ai/ui 0.5.0 → 1.0.0

package/CHANGELOG.md

@@ -1,11 +1,127 @@
 # @signalflare-ai/ui
 
+## 1.0.0
+
+### Major Changes
+
+- ffb8245: **Remove `AiLoader` component.**
+
+  `AiLoader` and its `./components/ai-loader` subpath export have been removed. Use `AiShimmer`, `AiStreamingText`, or the `Loader` primitive depending on the use case.
+
+  **Migration:**
+
+  - Replace `import { AiLoader } from "@signalflare-ai/ui"` with `import { Loader } from "@signalflare-ai/ui"` for a generic spinner, or `AiShimmer` for AI-specific loading affordance.
+  - Remove any deep imports from `@signalflare-ai/ui/components/ai-loader`.
+
+### Minor Changes
+
+- ffb8245: Extend `AiPartGroup` and ship a titled live state + conversation helpers.
+
+  - Streaming now renders a persistent title row with a spinner, step count, and
+    caret — the same footprint as the frozen summary, so settling doesn't shift
+    layout.
+  - New `groupParts(parts)` helper splits a message's parts into
+    alternating `text` / `activity` chunks so narrative text between tool work
+    starts a new group.
+  - `AgentHarness` now accepts `groupActivity` to render per-message activity
+    (thinking, OM, top-level tool calls) inside an `AiPartGroup` with a
+    rolling window while streaming and a frozen summary on completion.
+  - Added a conversation demo on the `AiPartGroup` docs page showing grouped
+    activity composed inside `AiMessage` bubbles with text-broken groups.
+
+- ffb8245: Add `AiPartGroup` for grouping streaming ephemeral activity in chat messages.
+
+  - Renders the most recent `max` (default 3) ephemeral children during streaming;
+    older rows fall off the top.
+  - Once the parent passes `complete`, writes a snapshot keyed by `groupKey` and
+    collapses to a static frozen summary line — ephemeral children unmount entirely.
+  - Re-renders after completion always render the cached snapshot, so scroll-back
+    into a virtualized chat list never re-fires animations or `useEffect`s.
+
+  Also visually aligns `AiReasoning variant="ephemeral"` with `AiToolCall variant="ephemeral"`:
+  single status symbol in the same leading slot (spinner while streaming → check on
+  settle), unified caret, no decorative reasoning icon.
+
+- ffb8245: **Theme overhaul + shadcn compatibility layer.**
+
+  - Default `sf` theme replaced with an accessible neutral palette based on the former `minimal` (WCAG 2.1 AA on all text tokens; stronger focus ring).
+  - Former `sf` visuals (blue-tinted dark surfaces) preserved as `data-theme="blue-tint"`.
+  - `minimal` theme kept as its own opt-in (`data-theme="minimal"`) — equivalent to the new default.
+  - `theme-navigator.css` rewritten to alias shadcn CSS variables (`--background`, `--foreground`, `--card`, `--primary`, `--muted`, `--border`, `--ring`, etc.) to the corresponding SF tokens. Dropping SF into a shadcn/TanStack app now restyles those components with the SF palette automatically.
+  - `ai/USAGE.md` (surfaced via `sf ai`) documents the compatibility layer, the chart-color fallback, and the shadcn-CLI `:root` pitfall.
+
+  **Migration notes:**
+
+  - Apps relying on the prior default dark palette should add `data-theme="blue-tint"` to their root element.
+  - Apps that installed shadcn components should delete any `:root { --background: …; --foreground: …; … }` block written by the shadcn CLI — the SF theme now provides those variables.
+
+- ffb8245: Add `ephemeral` variant to `AiToolCall` and `AiReasoning`.
+
+  - `variant="ephemeral"` renders a compact single-status row that auto-dismisses
+    `dismissDelay` ms (default 800) after the call/stream settles.
+  - Errors and user-expanded rows auto-pin and stay visible.
+  - New props on both components: `dismissDelay`, `persist`, `onDismiss`.
+  - Existing `default`, `inline`, and `minimal` variants are unchanged.
+
+- ffb8245: Add `PromptInputModelSelect` — compact toolbar-styled model picker (Base UI Select under the hood) that can be bound to `requestContext.model` via the prompt input controller or controlled explicitly.
+
+  `AgentHarness`:
+
+  - New `availableModels` prop renders a `PromptInputModelSelect` in the toolbar.
+  - Removed `showMode` / `showModel` props — mode and model now render only as interactive selectors (via `availableModes` / `availableModels`). The old plain-text fallback labels and the unused `getModelDisplayName` helper are gone.
+
+- e939e4f: **Shadcn compatibility layer is now opt-in and theme-aware.**
+
+  The shadcn variable bridge (formerly `theme-navigator.css`, auto-imported by `sf-binding.css`) has been moved to a dedicated opt-in stylesheet: `@signalflare-ai/ui/styles/shadcn`.
+
+  **Why:** The previous bridge shipped to all consumers unconditionally and contained hardcoded OKLCH literals for `--success`, `--chart-1..5`, and Sugar-High `--sh-*` tokens that did **not** track the active SignalFlare theme.
+
+  **What changed:**
+
+  - **New tokens in `theme-sf.css`:** `--color-sf-success`, `--color-sf-chart-1` through `--color-sf-chart-5`, and `--color-sf-syntax-{keyword,identifier,string,comment,jsxliterals,property,entity,sign}` — defined per-theme so they shift correctly with `data-theme`.
+  - **New stylesheet:** `@signalflare-ai/ui/styles/shadcn` is pure `var(--color-sf-*)` aliasing — no hardcoded literals. Imports it explicitly from your global stylesheet.
+  - **`sf-binding.css` no longer auto-imports the bridge.** Consumers who don't need shadcn-style tokens get a smaller bundle and a strict SignalFlare-only token surface.
+
+  **Migration:**
+
+  If you use shadcn-style classes (`bg-primary`, `text-foreground`, `border-border`, etc.) — for example with TanStack examples, Streamdown code blocks, or shadcn components — add the opt-in import after the main SignalFlare styles:
+
+  ```css
+  @import "@signalflare-ai/ui/styles";
+  @import "@signalflare-ai/ui/styles/shadcn";
+  @import "tailwindcss";
+  ```
+
+  If you only use SignalFlare tokens (`bg-sf-base`, `text-sf-default`, etc.), no change is needed.
+
+- ffb8245: Add `TextRoll` — letter-by-letter rotate-X roll animation for short labels
+  that change over time. Wraps the text in an `aria-hidden` visual stack with a
+  screen-reader-only copy so a11y tools always read the real content.
+
+  Used internally by `AiPartGroup` to animate the streaming title when the
+  derived reasoning snippet changes step-to-step.
+
+### Patch Changes
+
+- e939e4f: **Branding sweep:** updated LICENSE copyright to SignalFlare AI, Inc., swept residual "SF" prose references in JSDoc, console output, and AI prompts to "SignalFlare", and updated example URLs (`cloudflare.com` → `signalflare.ai`) in `Link` JSDoc and tests. Code identifiers (`SF_COMPONENT_NAMES`), the `sf` CLI command, and `sf-*` CSS tokens are unchanged.
+
+## 0.5.1
+
+### Patch Changes
+
+- d73a525: Verify Trusted Publishing and provenance attestation
+
+  This is a test release to verify the CI workflow correctly uses:
+
+  - Trusted Publishing (OIDC token exchange with npm)
+  - Automatic provenance generation
+  - No manual 2FA required
+
 ## 0.5.0
 
 ### Minor Changes
 
 - d85265a: Added Filters and DataGrid components
-
   - **Filters**: New filter component with text, select, multiselect, and custom filter types. Includes keyboard shortcuts, i18n support, and operator selection.
   - **DataGrid**: Full-featured data grid built on @tanstack/react-table with sorting, column visibility, row selection, pagination, and resizable columns.
   - Added documentation pages and demos for both components.

package/ai/USAGE.md

@@ -30,6 +30,70 @@ import { Button, Input, Dialog } from "@signalflare-ai/ui";
 3. **Merge classes with `cn()`** — import from `@signalflare-ai/ui` and use it to combine class names.
 4. **Compound components** — many components use a dot-notation API: `<Dialog.Root>`, `<Dialog.Trigger>`, etc.
 
+## Using With shadcn / TanStack / Other Libraries
+
+SignalFlare ships a compatibility layer at `@signalflare-ai/ui/styles/shadcn` that aliases the standard shadcn CSS variables (`--background`, `--primary`, `--border`, etc.) to SignalFlare tokens via `var()` references. This means shadcn-style classes used by TanStack examples, shadcn components, and similar libraries render with the SignalFlare palette — and follow any active `data-theme` automatically because they resolve sf tokens at use time.
+
+It is **opt-in**. If you don't use shadcn components, you don't pay the cost:
+
+```css
+@import "@signalflare-ai/ui/styles";
+@import "@signalflare-ai/ui/styles/shadcn";
+```
+
+### Aliases provided
+
+| shadcn class              | Aliased to           |
+| ------------------------- | -------------------- |
+| `bg-background`           | `bg-sf-base`         |
+| `text-foreground`         | `text-sf-default`    |
+| `bg-card`                 | `bg-sf-elevated`     |
+| `text-card-foreground`    | `text-sf-default`    |
+| `bg-primary`              | `bg-sf-contrast`     |
+| `text-primary-foreground` | `text-sf-inverse`    |
+| `bg-muted`                | `bg-sf-tint`         |
+| `text-muted-foreground`   | `text-sf-subtle`     |
+| `bg-accent`               | `bg-sf-fill`         |
+| `bg-destructive`          | `bg-sf-danger`       |
+| `border-border`           | `border-sf-line`     |
+| `border-input`            | `border-sf-interact` |
+| `ring-ring`               | `ring-sf-ring`       |
+
+Both `bg-background` and `bg-sf-base` render identically. Theme switches (`data-theme="fedramp"` etc.) and dark mode (`data-mode="dark"`) affect both sets of classes consistently.
+
+### Chart colors
+
+Recharts / TanStack Chart utilities (`bg-chart-1` through `bg-chart-5`) alias to `--color-sf-chart-1..5`. Themes can override these tokens like any other, so setting `data-theme="fedramp"` (or any custom theme you wire up) restyles charts consistently. Override per app if you want theme-aware charts tied to your semantic palette:
+
+```css
+:root {
+  --chart-1: var(--color-sf-brand);
+  --chart-2: var(--color-sf-info);
+  --chart-3: var(--color-sf-warning);
+  --chart-4: var(--color-sf-danger);
+  --chart-5: var(--color-sf-success);
+}
+```
+
+### ⚠️ Common pitfall
+
+When users run `npx shadcn@latest add <component>`, the shadcn CLI often appends a `:root { --background: …; --foreground: …; … }` block to the app's global CSS. **Delete that block** — the SF theme already provides those variables. If left in place, it will clobber the SF palette (later in the cascade = wins):
+
+```css
+/* ❌ Delete blocks like this that shadcn's CLI writes */
+@layer base {
+  :root {
+    --background: oklch(1 0 0);
+    --foreground: oklch(0.145 0 0);
+    /* … */
+  }
+}
+```
+
+### Preference order for new code
+
+When writing new SF components or blocks, **prefer SF tokens** (`bg-sf-base`, `text-sf-default`). The shadcn aliases exist for compatibility with third-party code — not as a second canonical token set.
+
 ## Component Quick Reference
 
 | Component          | Category   | Description                           | Key Props                                                                                                                      |