@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qbtrix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,94 @@
+NOTICE
+======
+
+@ripple-ui/svelte is MIT licensed (see LICENSE, Copyright (c) 2026 Qbtrix).
+
+It incorporates work from the MIT-licensed projects below. MIT requires the
+copyright notice and permission notice to travel with the work, which is what
+this file is for. Per-file `@provenance` headers name the specific upstream file
+each port came from.
+
+
+-------------------------------------------------------------------------------
+beautiful-ui
+-------------------------------------------------------------------------------
+
+  Source:    https://github.com/slev12397/beautiful-ui
+  Commit:    ff0f74d
+  Copyright: Copyright (c) 2026 Shane Levine
+  Licence:   MIT (full text below)
+
+Used as the visual source for ripple's component re-skin: design tokens, the
+`cubic-bezier(0.22, 1, 0.36, 1)` ease published as `--ripple-ease-out`, several
+CSS `@keyframes`, and the layout and type rhythm of a set of atoms and AI
+primitives. No source file is copied or imported; each component is a
+translation into Svelte 5 against ripple's own tokens. The mapping is recorded
+in `docs/design/beautiful-ui-translation.md`.
+
+MIT License
+
+Copyright (c) 2026 Shane Levine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+-------------------------------------------------------------------------------
+Other MIT upstreams already incorporated
+-------------------------------------------------------------------------------
+
+Each is MIT licensed. The per-file `@provenance` headers name the upstream
+project for each port, but they record the project rather than a copyright
+holder, and the copyright lines below have not been verified against the
+upstream LICENSE files. Reproducing them here in full is a follow-up; treat
+this section as an index of what is incorporated, not as completed attribution
+for these four.
+
+  Fluid Functionalism  — https://github.com/mickadesign/fluid-functionalism
+    The 8-step surface/elevation ladder (`src/lib/systems/elevation.css`), the
+    spring tokens in `src/lib/motion/presets.ts`, and the moving-indicator
+    primitive generalized from its checkbox-group.
+
+  svelte-animations    — https://github.com/SikandarJODD/svelte-animations
+    Several widgets in the premium pack (Shimmer, Marquee, BorderBeam,
+    TextEffect, BentoGrid).
+
+  Aceternity (Svelte)  — https://aceternity.sveltekit.io
+    Aurora, Spotlight and AnimatedBeam in the premium pack.
+
+  Skeleton v3          — https://skeleton.dev
+    The CSS-custom-property theming architecture followed by
+    `src/lib/core/theme-applier.ts`.
+
+
+-------------------------------------------------------------------------------
+Provenance header convention
+-------------------------------------------------------------------------------
+
+Every file re-skinned from beautiful-ui carries, in its top comment block, the
+line:
+
+  origin: slev12397/beautiful-ui@ff0f74d <path in that repo>
+
+for example:
+
+  origin: slev12397/beautiful-ui@ff0f74d components/primitives/ThinkingState.tsx
+
+Pinning the commit is what makes the claim checkable later — the upstream repo
+moves, and "ported from beautiful-ui" with no commit is unverifiable a year on.
+Cheap to add now, painful to backfill.

package/README.md

@@ -1,3 +1,317 @@
-# Temporary Holding Version
+# @ripple-ui/svelte
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Svelte 5 runtime that turns a JSON spec into a live, interactive UI.
+
+It renders while the spec is still streaming in from a model. Watch recorded
+model runs at [ripple.pocketpaw.xyz/live](https://ripple.pocketpaw.xyz/live)
+or try a spec in the [playground](https://ripple.pocketpaw.xyz/playground).
+
+> The engine underneath — schema, expressions, state, events, and a headless
+> runtime — is [`@ripple-ui/core`](../core), and it has no framework
+> dependency. This package is the Svelte renderer over it. You do not need to
+> install core separately; it comes as a dependency.
+
+## What this is
+
+Ripple is the rendering layer for AI-generated interfaces. An LLM (or any other source) emits a small JSON document describing what the UI should look like; Ripple mounts it as a real Svelte component tree with state, two-way bindings, expression evaluation, and event handling. The model writes structure; Ripple handles reactivity.
+
+You don't author Svelte components per screen. You hand Ripple a spec and it builds the UI.
+
+```json
+{
+  "version": "1.0",
+  "state": { "name": "" },
+  "ui": {
+    "type": "flex",
+    "props": { "direction": "column", "gap": "12px" },
+    "children": [
+      { "type": "input", "bind": "name", "props": { "label": "Your name" } },
+      { "type": "text", "props": { "text": "Hello, {state.name}!" } }
+    ]
+  }
+}
+```
+
+That spec is a fully working two-way-bound form. No glue code.
+
+## What it does
+
+Three things, in order of how often you'll touch them:
+
+1. **Renders 197 typed widgets from JSON.** Every node in the tree (`{ "type": "...", "props": {...}, "children": [...] }`) maps to a Svelte component — `flex`, `card`, `kanban`, `chart`, `comparison-layout`, `wizard-layout`, `pricing-table`, all of them. The full catalog with prop schemas lives in [`dist/manifest.json`](./dist/manifest.json).
+
+2. **Wires state and interactivity declaratively.** `state` is a top-level object on the spec. Inputs use `"bind": "<state-path>"` for two-way binding. Buttons fire `on_click` action chains (`set`, `push`, `remove`, `toggle`, `validate`, `branch`, `confirm`, `api`, `navigate`, `toast`, `emit`). Expressions inside any string — `{state.count + 1}`, `{state.x > 0 ? 'yes' : 'no'}`, `{item.price}` — are resolved at render time against state and loop context.
+
+3. **Hands back events.** Anything the host needs to handle (HTTP calls, navigation, toasts, custom signals) bubbles out via a single `onEvent` callback on the `<Ripple>` component. The spec doesn't reach into your app; it asks the host to do something.
+
+## How it works
+
+The pipeline in five steps:
+
+```
+   spec (JSON)
+        │
+        ▼
+  ┌──────────────┐    UISpec → UniversalSpec wrapper
+  │  normalizer  │    (or pass-through if already universal)
+  └──────┬───────┘
+         ▼
+  ┌──────────────┐    Svelte 5 $state proxy with dot-notation
+  │ StateManager │    `get("user.profile.name") / set("count", 7)`
+  └──────┬───────┘
+         ▼
+  ┌──────────────┐    Resolves `{state.x + 1}`, `{item.field}`,
+  │  Expression  │    ternaries, comparisons, method calls.
+  │   Resolver   │    Tracks reads inside derived blocks for
+  └──────┬───────┘    automatic reactivity.
+         ▼
+  ┌──────────────┐    Walks the tree, picks the Svelte component
+  │ NodeRenderer │    from the registry per `type`, evaluates
+  └──────┬───────┘    `show`/`bind`/`on_*`, renders children.
+         ▼
+  ┌──────────────┐    User clicks → `on_click` chain runs through
+  │   Event      │    the dispatcher: state mutations stay local,
+  │  Dispatcher  │    side-effecting actions (api/toast/navigate)
+  └──────────────┘    fire `onEvent` on the host.
+```
+
+Each piece is independent and Svelte 5 native:
+
+- **Normalizer** (`src/lib/core/normalizer.ts`) accepts either spec format and returns a `UniversalSpec`.
+- **StateManager** (`src/lib/core/state-manager.svelte.ts`) wraps a Svelte 5 `$state` proxy. Path-based reads/writes auto-create intermediate objects. Subscribe via `stateManager.subscribe(callback)`.
+- **ExpressionResolver** (`src/lib/core/expression-resolver.ts`) parses `{...}` strings — paths, arithmetic, comparisons, ternaries, optional chaining, whitelisted methods (`.includes`, `.length`, `.toFixed`, etc.). Detects UINode-shaped subtrees and leaves them raw so they can resolve later in their own loop context.
+- **EventDispatcher** (`src/lib/core/event-dispatcher.ts`) executes action chains. State actions (`set`/`push`/`remove`/`toggle`) write through StateManager; control actions (`branch`/`validate`/`confirm`) gate further actions; effect actions (`api`/`navigate`/`toast`/`emit`/`pin`/`unpin`) emit `RippleEvent`s the host can intercept.
+- **NodeRenderer** (`src/lib/components/NodeRenderer.svelte`) is the recursive walker. It evaluates `show` conditions, resolves props, builds loop contexts for `each`, manages `bind` two-way wiring, and renders children — including named slots (`header`, `footer`, `sidebar`, `topbar`, `actions`).
+- **Widget registry** (`src/lib/widgets/index.ts`) maps `type` strings to Svelte components. Aliases are flat entries (e.g. `dialog → Modal`, `comparison-cards → ComparisonLayout`). Register your own at runtime with `registerWidget(type, component)`.
+
+Reactivity is end-to-end: every state mutation flows through the proxy, Svelte recomputes any derived that read it, and only the affected widget re-renders. There is no virtual DOM diff phase you have to think about — it's the same system Svelte 5 uses for hand-written components.
+
+## Why JSON specs?
+
+Three reasons that compound:
+
+1. **LLMs produce structured data better than they produce code.** A model emits a spec like the one above with high reliability; the same model writing equivalent Svelte code is several times more error-prone.
+2. **Specs are inspectable, diffable, persistable.** You can save a UI to a database, send it over the wire, replay it from a log, run a regression test against it. JSX-as-rendered output gives you none of that.
+3. **The contract is small.** Every widget's prop schema lives in `dist/manifest.json` (197 widgets). A model can fetch it once and have a complete catalog, including runnable examples. New widgets ship by adding to the registry — no SDK update on the agent side.
+
+## Features
+
+- **JSON-driven rendering** — Define UIs as data, not code
+- **Two spec formats** — Low-level UISpec (v1.0) for full control, or high-level UniversalSpec (v2.0) for intent-based UIs
+- **197 built-in widgets** across nine categories — layout, display, input, data, overlay, control, composite, research, and enterprise verticals
+- **Reactive expressions** — `{state.user.name}` syntax with comparisons, ternary, and logical operators
+- **State management** — Svelte 5 rune-based with dot-notation path access
+- **Event system** — Declarative handlers for state updates, API calls, navigation, toasts, and custom events
+- **Intent system** — Auto-layout engine, pattern detection (quiz, charts, results), and multi-step flow chaining
+- **LLM-ready manifest** — `dist/manifest.json` ships with every release, declaring every widget's prop schema and a runnable example. Agents can fetch it at runtime to learn the API
+- **Extensible** — Register custom widgets at runtime
+- **Theming** — shadcn-svelte tokens with full color/radius/mode overrides
+
+## Installation
+
+```bash
+bun add @ripple-ui/svelte
+```
+
+Requires **Svelte 5** (`^5.0.0`).
+
+## Styling
+
+Widgets are styled with Tailwind CSS v4 classes, so your app needs Tailwind v4
+(for example `@tailwindcss/vite`), and Tailwind has to scan this package's
+`dist`. It skips `node_modules` on its own, so add an `@source` line. The path
+is relative to the CSS file it sits in.
+
+If your app has no design tokens of its own, import `styles.css`. It brings in
+Tailwind itself, default shadcn-style colour tokens (light, plus a `.dark`
+class), and Ripple's theme, so don't also `@import "tailwindcss"`:
+
+```css
+/* src/app.css */
+@import "@ripple-ui/svelte/styles.css";
+@source "../node_modules/@ripple-ui/svelte/dist";
+```
+
+If you already define shadcn tokens (`--background`, `--primary`, `--card`, ...)
+and map them with `@theme inline`, as a shadcn-svelte app does, keep your sheet
+and add only the theme. `theme.css` adds the `--ripple-*` tokens and their
+utilities (`bg-ripple-surface`, `rounded-ripple`, ...), which default to your
+shadcn tokens:
+
+```css
+@import "tailwindcss";
+@import "@ripple-ui/svelte/theme.css";
+@source "../node_modules/@ripple-ui/svelte/dist";
+```
+
+To restyle Ripple without touching your own tokens, override `--ripple-*`
+properties, scoped if you like:
+`.my-panel .ripple-root { --ripple-surface: transparent; }`.
+
+## Quick Start
+
+```svelte
+<script lang="ts">
+  import { Ripple } from '@ripple-ui/svelte';
+
+  const spec = {
+    version: '1.0',
+    state: { count: 0 },
+    ui: {
+      type: 'flex',
+      props: { direction: 'column', gap: 4 },
+      children: [
+        { type: 'heading', props: { text: 'Counter', level: 2 } },
+        { type: 'text', props: { text: 'Count: {state.count}' } },
+        {
+          type: 'button',
+          props: { label: '+1' },
+          on_click: { action: 'set', target: 'count', value: '{state.count}' }
+        }
+      ]
+    }
+  };
+</script>
+
+<Ripple {spec} />
+```
+
+## Spec Formats
+
+### UISpec (v1.0) — Full Control
+
+Explicit widget tree with props, events, and control flow:
+
+```json
+{
+  "version": "1.0",
+  "state": { "query": "" },
+  "ui": {
+    "type": "flex",
+    "props": { "direction": "column", "gap": 3 },
+    "children": [
+      { "type": "input", "props": { "placeholder": "Search..." }, "bind": "{state.query}" },
+      {
+        "type": "if",
+        "condition": "{state.query != ''}",
+        "children": [{ "type": "text", "props": { "text": "Searching: {state.query}" } }]
+      }
+    ]
+  }
+}
+```
+
+### UniversalSpec (v2.0) — Intent-Based
+
+Declare what the UI should do, and Ripple picks the layout:
+
+```json
+{
+  "version": "2.0",
+  "intent": "browse",
+  "title": "Products",
+  "data": {
+    "items": [
+      { "id": "1", "name": "Widget", "image": "/img/widget.jpg", "price": "$9.99" }
+    ]
+  },
+  "fields": { "title": "name", "image": "image", "subtitle": "price" },
+  "selection": "single"
+}
+```
+
+## Built-in Widgets
+
+| Category | Examples | Count |
+|----------|----------|-------|
+| **Layout** | `flex`, `grid`, `card`, `tabs`, `accordion`, `split`, `master-detail`, `app-shell`, `sidebar`, `page-header`, `hero`, `section`, `breadcrumb`, `dashboard` | 21 |
+| **Display** | `text`, `heading`, `image`, `badge`, `metric`, `stat`, `progress`, `progress-ring`, `avatar`, `markdown`, `code-block`, `kbd`, `chip`, `quote`, `definition-list`, `comparison-table`, `pros-cons`, `steps`, `link-preview`, `qr`, `diff` | 33 |
+| **Input** | `button`, `input`, `textarea`, `select`, `combobox`, `multi-select`, `checkbox`, `switch`, `radio-group`, `slider`, `rating`, `date-picker`, `time-picker`, `number-input`, `segmented`, `color-picker`, `file-upload`, `form`, `filter-bar`, `search`, `location-picker` | 24 |
+| **Data** | `table`, `data-grid`, `chart`, `kanban`, `gantt`, `calendar`, `timeline`, `tree`, `tree-table`, `virtual-list`, `sparkline`, `gauge`, `funnel`, `heatmap`, `sankey`, `treemap`, `map` | 18 |
+| **Overlay** | `alert`, `callout`, `tooltip`, `popover`, `dropdown-menu`, `toast`, `command-palette`, `context-menu`, `notification-center`, `error-state`, `coachmark` | 12 |
+| **Composite layouts** | `comparison-layout`, `entity-detail`, `form-layout`, `wizard-layout`, `checklist-layout`, `report-layout`, `invoice-layout`, `order-status`, plus dashboard variants (exec/ops/analytics/pipeline/project), `terminal`, `workflow`, `c4` | 16 |
+| **Research** | `source-card`, `citation`, `sources-bar`, `discover-card`, `follow-up`, `kv-table`, `news-card`, `ticker`, `company-header`, `callout`, `analyst-bar`, `range-bar` | 13 |
+| **Vertical** | `pricing-table`, `settings-list`, `comment-thread`, `audit-log`, `api-key`, `people-picker`, `permission-matrix`, `org-chart`, `invoice-lines`, `bulk-action-bar`, `saved-views` | 11 |
+| **Control** | `if`, `each` | 2 |
+
+The complete prop schema and a runnable example for every widget live in **[`dist/manifest.json`](./dist/manifest.json)** (regenerated by `bun run build:manifest`). LLM agents fetch this manifest to learn the API; treat it as the source of truth.
+
+## Expressions
+
+Reactive bindings using `{expression}` syntax:
+
+```
+{state.user.name}              — State path
+{item.price}                   — Loop variable
+{state.count > 0}              — Comparison
+{state.active ? 'On' : 'Off'}  — Ternary
+{state.a && state.b}           — Logical AND
+{!state.loading}               — Negation
+```
+
+## Event Handling
+
+Declarative handlers with 8 action types:
+
+```json
+{
+  "on_click": [
+    { "action": "set", "target": "loading", "value": true },
+    { "action": "api", "url": "/api/save", "method": "POST" },
+    { "action": "toast", "message": "Saved!", "variant": "success" }
+  ]
+}
+```
+
+| Action | Behavior |
+|--------|----------|
+| `set` | Update state |
+| `open` | Set state to true (dialog shorthand) |
+| `api` | HTTP request (emitted to parent) |
+| `navigate` | URL navigation (emitted to parent) |
+| `toast` | Show notification (emitted to parent) |
+| `emit` | Custom event (emitted to parent) |
+| `pin` / `unpin` | Sidebar persistence (emitted to parent) |
+
+## Custom Widgets
+
+```typescript
+import { registerWidget } from '@ripple-ui/svelte';
+import MyWidget from './MyWidget.svelte';
+
+registerWidget('my-widget', MyWidget);
+```
+
+## Development
+
+```bash
+bun install              # Install dependencies
+bun run dev              # Dev server with playground (also serves /manifest.json)
+bun run build            # Build library + manifest to dist/
+bun run build:manifest   # Regenerate dist/manifest.json and static/manifest.json
+bun run check            # Type-check
+bun run test             # Run tests
+```
+
+The dev server serves the widget manifest at `http://localhost:5174/manifest.json`. Point your LLM tooling at this URL to develop against live changes.
+
+## Documentation
+
+Full documentation at [ripple.pocketpaw.xyz/docs](https://ripple.pocketpaw.xyz/docs):
+
+- [Install](https://ripple.pocketpaw.xyz/docs/getting-started/install), [Render a spec](https://ripple.pocketpaw.xyz/docs/getting-started/render-a-spec), [Stream a spec](https://ripple.pocketpaw.xyz/docs/getting-started/stream-a-spec)
+- [The spec](https://ripple.pocketpaw.xyz/docs/concepts/the-spec)
+- [State and expressions](https://ripple.pocketpaw.xyz/docs/concepts/state-and-expressions)
+- [Actions and events](https://ripple.pocketpaw.xyz/docs/concepts/actions-and-events), [Flow actions](https://ripple.pocketpaw.xyz/docs/concepts/flow-actions)
+- [Streaming](https://ripple.pocketpaw.xyz/docs/concepts/streaming)
+- [Headless runtime](https://ripple.pocketpaw.xyz/docs/concepts/headless)
+- [Widgets](https://ripple.pocketpaw.xyz/docs/widgets)
+- [Custom widgets](https://ripple.pocketpaw.xyz/docs/guides/custom-widgets), [Theming](https://ripple.pocketpaw.xyz/docs/guides/theming), [Intents](https://ripple.pocketpaw.xyz/docs/guides/intents)
+- API reference: [@ripple-ui/svelte](https://ripple.pocketpaw.xyz/docs/api/svelte), [@ripple-ui/core](https://ripple.pocketpaw.xyz/docs/api/core)
+- [How Ripple works](https://ripple.pocketpaw.xyz/docs/architecture/overview)
+
+## License
+
+MIT. The isometric drawings (`figure`, `iso-scene`) are inspired by and built
+on a kit ported from [Anatomy](https://skills.wheresryan.sh/anatomy) by Ryan,
+MIT; the full license ships as `THIRD_PARTY_NOTICES.md` in `@ripple-ui/core`.