@ryanhelsing/ry-ui 1.0.2 → 1.0.4

package/AGENT.md

@@ -0,0 +1,460 @@
+# ry-ui — Agent Reference
+
+> Framework-agnostic Light DOM web components. CSS is the source of truth.
+> This file is for AI agents building apps with ry-ui.
+
+## Quick Start
+
+```html
+<!-- CDN (full bundle) -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/dist/css/ry-ui.css">
+<script type="module" src="https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/dist/ry-ui.js"></script>
+
+<!-- Or individual layers (for custom themes) -->
+<link rel="stylesheet" href="ry-tokens.css">
+<link rel="stylesheet" href="ry-structure.css">
+<link rel="stylesheet" href="your-theme.css">
+```
+
+## Clean Syntax
+
+Wrap markup in `<ry>` to use unprefixed tags:
+
+```html
+<ry>
+  <accordion>
+    <accordion-item title="FAQ" open>No ry- prefix needed.</accordion-item>
+  </accordion>
+</ry>
+```
+
+---
+
+## Component Catalog
+
+### Layout (CSS-only, no JS)
+
+| Component | Attributes | Description |
+|-----------|-----------|-------------|
+| `<ry-page>` | — | Root page container, flex column, min-height 100dvh, container queries |
+| `<ry-header>` | `sticky` | Flex row, space-between. `sticky` pins to top |
+| `<ry-main>` | — | Content area, max-width 1200px, centered |
+| `<ry-footer>` | — | Footer with border-top |
+| `<ry-section>` | — | Block section with bottom margin, container queries |
+| `<ry-grid>` | `cols="1-6\|auto-fit\|auto-fill"`, `cols-sm="1-3"`, `cols-md="1-4"`, `cols-lg="2-6"` | CSS grid. See [Grid](#grid) |
+| `<ry-stack>` | `gap="sm\|md\|lg\|xl"` | Vertical flex column |
+| `<ry-cluster>` | `gap="sm\|md\|lg"` | Horizontal flex row, wraps |
+| `<ry-split>` | `resizable`, `persist="key"`, CSS vars: `--ry-split-width`, `--ry-split-min-width`, `--ry-split-max-width` | Two-column: flex-1 left + fixed right. Stacks on mobile. Optional drag resize + localStorage persistence |
+| `<ry-center>` | — | Flex center (both axes) |
+| `<ry-nav>` | — | Horizontal nav links. Active: `a[aria-current="page"]` |
+| `<ry-logo>` | — | Inline-flex, bold text |
+| `<ry-actions>` | — | Flex row for action buttons |
+| `<ry-divider>` | `vertical` | Horizontal line; `vertical` for inline separator |
+| `<ry-aside>` | — | Sidebar content area |
+
+### Interactive Components
+
+| Component | Key Attributes | Events |
+|-----------|---------------|--------|
+| `<ry-button>` | `variant="primary\|secondary\|outline\|ghost\|danger\|accent"`, `size="sm\|lg"`, `disabled`, `pressed`, `icon`, `modal="id"` | `ry:click` |
+| `<ry-button-group>` | `name`, `value` | `ry:change` `{value}` — radio-group behavior for child buttons |
+| `<ry-toggle-button>` | `pressed`, `name`, `value`, `size`, `icon`, `block`, `disabled` | `ry:change` `{pressed, value}` |
+| `<ry-modal>` | `id`, `title` | Trigger with `<ry-button modal="id">`. Centered with backdrop |
+| `<ry-drawer>` | `id`, `position="left\|right"`, `size` | Trigger with `<ry-button drawer="id">` |
+| `<ry-accordion>` | — | Container for accordion-items |
+| `<ry-accordion-item>` | `title`, `open` | Collapsible section |
+| `<ry-tabs>` | — | Container. Children: `<ry-tab title="...">content</ry-tab>` |
+| `<ry-dropdown>` | — | Dropdown trigger + menu |
+| `<ry-select>` | `placeholder`, `name`, `value`, `disabled` | `ry:change` `{value}`. Children: `<ry-option value="...">` |
+| `<ry-switch>` | `checked`, `disabled`, `name` | `ry:change` `{checked}` |
+| `<ry-tooltip>` | `content`, `position` | Hover tooltip |
+| `<ry-toast>` | — | Programmatic: `RyToast.success('msg')`, `.error()`, `.warning()`, `.info()` |
+| `<ry-slider>` | `min`, `max`, `step`, `value`, `color`, `disabled` | `ry:change` `{value}` |
+| `<ry-knob>` | `min`, `max`, `step`, `value`, `color`, `size`, `disabled` | `ry:change` `{value}` |
+| `<ry-number-select>` | `min`, `max`, `step`, `value`, `arrows`, `size`, `prefix`, `suffix`, `label` | `ry:change` `{value}` |
+| `<ry-color-picker>` | `value`, `format` | `ry:change` `{value}` |
+| `<ry-color-input>` | `value`, `format` | `ry:change` `{value}` |
+| `<ry-gradient-picker>` | `value` | `ry:change` `{value}` |
+| `<ry-tree>` | `data` (JSON) | `ry:select`, `ry:move` — file tree with drag-and-drop |
+| `<ry-tag>` | `removable` | `ry:remove` |
+| `<ry-tag-input>` | `name`, `value`, `placeholder` | `ry:change` `{tags}` |
+| `<ry-carousel>` | `autoplay`, `interval` | `ry:change` `{index}` |
+| `<ry-theme-toggle>` | `themes="light,dark"` | Cycles through themes |
+
+### Display Components
+
+| Component | Key Attributes | Description |
+|-----------|---------------|-------------|
+| `<ry-card>` | — | Bordered card with padding. Put any content inside |
+| `<ry-badge>` | `variant="primary\|success\|warning\|danger\|accent"` | Pill badge. Arbitrary color: `style="--ry-badge-color: #8B5CF6"` |
+| `<ry-alert>` | `type="info\|success\|warning\|danger"` | Alert box with optional `[slot="title"]` |
+| `<ry-field>` | `label`, `error`, `hint` | Form field wrapper. See [Forms](#forms) |
+| `<ry-icon>` | `name` | SVG icon from registry |
+| `<ry-code>` | `language`, `title` | Syntax-highlighted code block |
+| `<ry-hero>` | `size="sm\|lg"`, `full-bleed`, `align="left"` | Marketing hero section. Children: h1, p, buttons |
+| `<ry-stat>` | `size="sm\|lg"` | Stat card with `slot="value"`, `slot="label"`, trend arrows |
+| `<ry-feature>` | `icon` | Feature card with icon from registry |
+| `<ry-feature-grid>` | `cols="2\|3\|4"` | Responsive grid for feature cards |
+| `<ry-pricing>` | — | Container for pricing cards (flex row, responsive) |
+| `<ry-pricing-card>` | `featured` | Pricing tier card. `featured` scales up with bold border |
+
+---
+
+## Patterns
+
+### Grid
+
+```html
+<!-- Fixed columns with auto-responsive -->
+<ry-grid cols="3">...</ry-grid>
+<!-- cols 3-6 → 2 at ≤1024px → 1 at ≤640px (automatic) -->
+
+<!-- Explicit per-breakpoint -->
+<ry-grid cols="5" cols-md="3" cols-sm="1">...</ry-grid>
+
+<!-- Fluid auto-fit (like repeat(auto-fit, minmax(280px, 1fr))) -->
+<ry-grid cols="auto-fit">...</ry-grid>
+
+<!-- Custom min-width for auto-fit -->
+<ry-grid cols="auto-fit" style="--ry-grid-min: 240px">...</ry-grid>
+```
+
+### Split Layout
+
+```html
+<!-- Default 300px sidebar -->
+<ry-split>
+  <div>Main content</div>
+  <div>Sidebar</div>
+</ry-split>
+
+<!-- Custom width -->
+<ry-split style="--ry-split-width: 600px; --ry-split-min-width: 400px">
+  <div>Main</div>
+  <div>Panel</div>
+</ry-split>
+
+<!-- Resizable with persistence -->
+<ry-split resizable persist="my-panel" style="--ry-split-width: 400px">
+  <div>Main</div>
+  <div>Resizable panel — drag handle, keyboard arrows, double-click to reset</div>
+</ry-split>
+```
+
+Split resize features:
+- **Drag handle** between panes (mouse + touch)
+- **Keyboard**: Arrow keys (±10px), Shift+Arrow (±50px), Home/End for min/max
+- **Double-click** handle to reset to default width
+- **`persist="key"`**: Saves width to `localStorage` as `ry-split:key`, restores on load
+- **`ry:resize`** event fires with `{ width }` after drag ends
+
+### Forms
+
+```html
+<ry-field label="Email" hint="We'll never share your email">
+  <input type="email" placeholder="you@example.com">
+</ry-field>
+
+<ry-field label="Password" error="Must be at least 8 characters">
+  <input type="password">
+</ry-field>
+
+<!-- Error hides hint automatically. Set error="" to clear and show hint again. -->
+```
+
+### Button Group (Segmented Control)
+
+```html
+<!-- Radio-group behavior -->
+<ry-button-group name="billing" value="monthly">
+  <ry-button value="monthly">Monthly</ry-button>
+  <ry-button value="annually">Annually</ry-button>
+</ry-button-group>
+
+<!-- Mode switcher -->
+<ry-button-group name="mode" value="terminal">
+  <ry-button value="direct">Direct</ry-button>
+  <ry-button value="terminal">Terminal</ry-button>
+  <ry-button value="release">Release</ry-button>
+</ry-button-group>
+
+<!-- Listen for changes -->
+<script>
+document.querySelector('ry-button-group').addEventListener('ry:change', e => {
+  console.log(e.detail.value); // "monthly" | "annually"
+});
+</script>
+```
+
+### Button Variants
+
+```html
+<ry-button>Primary (default)</ry-button>
+<ry-button variant="secondary">Secondary</ry-button>
+<ry-button variant="outline">Outline</ry-button>
+<ry-button variant="ghost">Ghost</ry-button>
+<ry-button variant="danger">Danger</ry-button>
+<ry-button variant="accent">Accent</ry-button>
+<ry-button pressed>Pressed/Active</ry-button>
+<ry-button size="sm">Small</ry-button>
+<ry-button size="lg">Large</ry-button>
+```
+
+### Badge with Arbitrary Color
+
+```html
+<ry-badge variant="success">Active</ry-badge>
+<ry-badge variant="accent">Pro</ry-badge>
+<ry-badge style="--ry-badge-color: #8B5CF6">Custom</ry-badge>
+<ry-badge style="--ry-badge-color: oklch(0.7 0.15 200); --ry-badge-text: #000">Custom + text</ry-badge>
+```
+
+### Check List (Pricing Features)
+
+```html
+<ul class="ry-check-list">
+  <li>Unlimited projects</li>
+  <li>Priority support</li>
+  <li>Custom domains</li>
+</ul>
+```
+
+### Nav Bar
+
+```html
+<ry-header sticky>
+  <ry-cluster>
+    <ry-logo>MyApp</ry-logo>
+    <ry-divider vertical></ry-divider>
+    <ry-nav>
+      <a href="/" aria-current="page">Home</a>
+      <a href="/docs">Docs</a>
+      <a href="/pricing">Pricing</a>
+    </ry-nav>
+  </ry-cluster>
+  <ry-actions>
+    <ry-button variant="ghost" size="sm">Login</ry-button>
+    <ry-button size="sm">Sign Up</ry-button>
+  </ry-actions>
+</ry-header>
+```
+
+### Pricing Page
+
+```html
+<ry-pricing>
+  <ry-pricing-card>
+    <h3>Free</h3>
+    <div class="ry-pricing__price">$0<span>/mo</span></div>
+    <p>For individuals</p>
+    <ul class="ry-check-list">
+      <li>3 projects</li>
+      <li>Basic support</li>
+    </ul>
+    <ry-button variant="outline">Get Started</ry-button>
+  </ry-pricing-card>
+
+  <ry-pricing-card featured>
+    <h3>Pro</h3>
+    <div class="ry-pricing__price">$19<span>/mo</span></div>
+    <p>For teams</p>
+    <ul class="ry-check-list">
+      <li>Unlimited projects</li>
+      <li>Priority support</li>
+    </ul>
+    <ry-button>Upgrade</ry-button>
+  </ry-pricing-card>
+</ry-pricing>
+```
+
+### Hero Section
+
+```html
+<ry-hero>
+  <h1>Build faster with ry-ui</h1>
+  <p>Framework-agnostic components for any app.</p>
+  <ry-cluster>
+    <ry-button size="lg">Get Started</ry-button>
+    <ry-button variant="outline" size="lg">View Docs</ry-button>
+  </ry-cluster>
+</ry-hero>
+```
+
+### Modal & Drawer
+
+```html
+<!-- Modal -->
+<ry-button modal="confirm">Open Modal</ry-button>
+<ry-modal id="confirm" title="Confirm Action">
+  <p>Are you sure?</p>
+  <ry-cluster>
+    <ry-button variant="danger">Delete</ry-button>
+    <ry-button variant="ghost">Cancel</ry-button>
+  </ry-cluster>
+</ry-modal>
+
+<!-- Drawer -->
+<ry-button drawer="settings">Settings</ry-button>
+<ry-drawer id="settings" position="right" size="400px">
+  <h3>Settings</h3>
+  <!-- content -->
+</ry-drawer>
+```
+
+---
+
+## CSS Token System
+
+All visual properties use CSS custom properties. Override in your own CSS to customize.
+
+### Colors
+
+| Token | Purpose |
+|-------|---------|
+| `--ry-color-primary` / `-hover` / `-active` | Primary action color (blue) |
+| `--ry-color-secondary` / `-hover` / `-active` | Secondary muted color |
+| `--ry-color-accent` / `-hover` / `-active` | Accent/highlight color (purple) |
+| `--ry-color-success` | Green for positive states |
+| `--ry-color-warning` | Yellow/orange for caution |
+| `--ry-color-danger` / `-hover` | Red for destructive actions |
+| `--ry-color-info` | Blue for informational |
+| `--ry-color-text` / `-muted` / `-inverse` | Text colors |
+| `--ry-color-bg` / `-subtle` / `-muted` | Background colors |
+| `--ry-color-border` / `-strong` | Border colors |
+| `--ry-color-overlay` | Modal/drawer backdrop |
+
+Each color also has `-bg` and `-text` variants for alert/badge backgrounds:
+`--ry-color-{info,success,warning,danger}-bg` / `--ry-color-{info,success,warning,danger}-text`
+
+### Spacing
+
+`--ry-space-{0,1,2,3,4,5,6,8,10,12,16,20}` — 0 to 5rem
+
+### Typography
+
+| Token | Value |
+|-------|-------|
+| `--ry-font-sans` | system-ui stack |
+| `--ry-font-mono` | ui-monospace stack |
+| `--ry-text-{xs,sm,base,lg,xl,2xl,3xl,4xl}` | 0.75rem to 2.25rem |
+| `--ry-font-{normal,medium,semibold,bold}` | 400 to 700 |
+| `--ry-leading-{tight,normal,relaxed}` | 1.25 to 1.75 |
+
+### Borders & Shadows
+
+| Token | Value |
+|-------|-------|
+| `--ry-radius-{none,sm,md,lg,xl,2xl,full}` | 0 to 9999px |
+| `--ry-shadow-{sm,md,lg,xl}` | Elevation shadows |
+| `--ry-border-width` | 1px |
+
+### Transitions
+
+| Token | Value |
+|-------|-------|
+| `--ry-duration-{fast,normal,slow}` | 100ms, 200ms, 300ms |
+| `--ry-ease` / `-in` / `-out` | Cubic bezier easing |
+
+### Z-Index
+
+| Token | Value |
+|-------|-------|
+| `--ry-z-dropdown` | 1000 |
+| `--ry-z-sticky` | 1020 |
+| `--ry-z-fixed` | 1030 |
+| `--ry-z-modal-backdrop` | 1040 |
+| `--ry-z-modal` | 1050 |
+| `--ry-z-popover` | 1060 |
+| `--ry-z-tooltip` | 1070 |
+| `--ry-z-toast` | 1080 |
+
+---
+
+## CSS Architecture
+
+Three layers, ordered by specificity:
+
+1. **ry-tokens** — CSS custom properties (colors, spacing, etc.)
+2. **ry-structure** — Pure layout (no colors). Selectors: element names + `[data-ry-target]`
+3. **ry-theme** — All visual styling. Selectors: `.ry-*` classes + element names
+
+### Custom Theming
+
+Load structure only + your own theme:
+
+```html
+<link rel="stylesheet" href="ry-tokens.css">    <!-- or your own tokens -->
+<link rel="stylesheet" href="ry-structure.css">
+<link rel="stylesheet" href="your-theme.css">
+```
+
+### Dark Mode
+
+Built into tokens via `light-dark()`. No separate dark.css needed.
+
+```html
+<html data-ry-theme="dark">  <!-- force dark -->
+<html data-ry-theme="light"> <!-- force light -->
+<!-- omit attribute for OS preference -->
+```
+
+---
+
+## Patterns NOT in ry-ui (Keep Custom)
+
+These patterns are intentionally outside the design system's scope:
+
+| Pattern | Reason | Recommended approach |
+|---------|--------|---------------------|
+| Click-positioned dialog / popover | GSAP animations, cursor anchoring | Use ry-ui tokens inside custom dialog |
+| File drop zone | App-specific UX | Custom component, tokenize colors |
+| Color swatch selector | Too specialized | Custom radio buttons with ry-ui tokens |
+| Terminal / xterm.js wrapper | Third-party integration | Custom container, tokenize colors |
+| Infinite canvas / artboard | Canvas 2D, not DOM | Use `getComputedStyle` to read ry-ui tokens for canvas rendering |
+| Chat / streaming replay | App-specific data format | Custom layout, use ry-ui header/badge/button inside |
+| Floating properties panel | Positioned at coordinates | Use `position: absolute` + ry-ui form components inside |
+
+For all of these: **use ry-ui tokens for colors, spacing, and typography** so they match the theme, but keep the structural markup custom.
+
+---
+
+## TypeScript
+
+```ts
+import { RyElement, RyButton, RyToast } from '@ryanhelsing/ry-ui';
+
+// Programmatic toast
+RyToast.success('Saved!');
+RyToast.error('Failed to save');
+
+// Listen for component events
+document.querySelector('ry-select')?.addEventListener('ry:change', (e: CustomEvent) => {
+  console.log(e.detail.value);
+});
+
+// Extend components
+class MyWidget extends RyElement {
+  setup() {
+    this.on(this, 'click', () => this.emit('activate'));
+  }
+}
+```
+
+---
+
+## Icon Registry
+
+```ts
+import { registerIcon, registerIcons } from '@ryanhelsing/ry-ui';
+
+// Single icon
+registerIcon('custom', '<svg>...</svg>');
+
+// Batch
+registerIcons({
+  'app-logo': '<svg>...</svg>',
+  'custom-arrow': '<svg>...</svg>'
+});
+```
+
+Built-in icons: `settings`, `heart`, `star`, `chevron-up`, `chevron-down`, `chevron-left`, `chevron-right`, `check`, `x`, `plus`, `minus`, `search`, `sun`, `moon`, `copy`, `trash`, `edit`, `eye`, `folder`, `file`, `drag`

package/AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md — ry-ui
+
+> Web components. No framework. Light DOM. CSS is the source of truth.
+
+## Setup
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/css/ry-ui.css">
+<script type="module" src="https://unpkg.com/@ryanhelsing/ry-ui"></script>
+```
+
+Theme: `<html data-ry-theme="light">` — light | dark
+
+## Concepts
+
+- **Light DOM** — no shadow DOM, your CSS just works
+- **Clean syntax** — `<ry><stack><card>Hi</card></stack></ry>` (drops `ry-` prefix inside `<ry>`)
+- **Tokens** — all visuals via `--ry-*` CSS custom properties, override to customize
+- **Structure vs Theme** — load `ry-structure.css` alone + your own theme for full control
+- **Events** — all prefixed `ry:` — `ry:change`, `ry:input`, `ry:open`, `ry:close`, `ry:toggle`, `ry:select`, `ry:move`
+
+## Components
+
+| Category | Components |
+|----------|-----------|
+| **Layout** | page, header, main, footer, section, aside, grid, stack, cluster, split, center, card, nav, logo, actions, divider |
+| **Overlays** | modal, drawer, dropdown, tooltip, toast |
+| **Forms** | field, select, switch, button-group, toggle-button, checkbox/radio (native) |
+| **Values** | slider, knob, number-select, color-picker, color-input, gradient-picker |
+| **Display** | badge, alert, icon, code, table (native), tree |
+| **Utility** | theme-toggle |
+
+## Docs
+
+Pull the page you need for full attributes, events, JS API, and examples:
+
+| Doc | What's in it |
+|-----|-------------|
+| [docs/components/layout.md](docs/components/layout.md) | page, header, main, footer, section, aside, grid, stack, cluster, split, center, card, nav, logo, actions, divider |
+| [docs/components/button.md](docs/components/button.md) | button, toggle-button |
+| [docs/components/button-group.md](docs/components/button-group.md) | button-group (segmented control) |
+| [docs/components/accordion.md](docs/components/accordion.md) | accordion, accordion-item |
+| [docs/components/tabs.md](docs/components/tabs.md) | tabs, tab |
+| [docs/components/modal.md](docs/components/modal.md) | modal |
+| [docs/components/drawer.md](docs/components/drawer.md) | drawer |
+| [docs/components/dropdown.md](docs/components/dropdown.md) | dropdown, menu, menu-item |
+| [docs/components/tooltip.md](docs/components/tooltip.md) | tooltip |
+| [docs/components/toast.md](docs/components/toast.md) | toast (programmatic) |
+| [docs/components/forms.md](docs/components/forms.md) | field, select, switch, checkbox, radio |
+| [docs/components/slider.md](docs/components/slider.md) | slider |
+| [docs/components/knob.md](docs/components/knob.md) | knob |
+| [docs/components/number-select.md](docs/components/number-select.md) | number-select |
+| [docs/components/color.md](docs/components/color.md) | color-picker, color-input, gradient-picker |
+| [docs/components/tree.md](docs/components/tree.md) | tree, tree-item |
+| [docs/components/display.md](docs/components/display.md) | badge, alert, icon, code, table |
+| [docs/components/theme-toggle.md](docs/components/theme-toggle.md) | theme-toggle |
+| [docs/theming.md](docs/theming.md) | tokens, custom themes, structure-only loading |

package/README.md

@@ -17,7 +17,18 @@ ry-ui normalizes this. No decisions to make. No architecture to debate. An LLM c
 - [x] separate the css minimal structure from the theme
 - [x] separate the component behavior from the design (see `docs/arch/behavior-style-separation.md`)
 
-- [ ] Slider, Knob, Menu, Placeholder, Step/Wizard, Loader/Progress, Breadcrumb, Comment/Feed,  Statistic/Graph, Hero, Calendar, Rating , Search, Shape, Sticky, color-picker, dialog/alert, tree, carousel, qr-code, diff, split-panel, format-bytes-number-currency(rails things), mutation-observer and resize observer,
+### Next Up — Missing Primitives That Block Real Apps
+
+- [ ] **Table / Data Grid** — sorting, column resize, virtual scrolling for large datasets. Highest-value missing component for any dashboard.
+- [ ] **Form** — form orchestration around existing inputs. Validation, error states, submit handling, field grouping.
+- [ ] **Menu / Context Menu** — right-click menus, nested submenus. Required for any desktop-targeting app.
+- [ ] **Command Palette** — Cmd+K pattern. Table stakes for power-user apps and ry-os.
+- [ ] **Toast stacking** — ry-toast exists but needs positioning, stacking multiple toasts, auto-dismiss timers, queue behavior.
+- [ ] **Breadcrumb, Pagination, Stepper** — navigation patterns for any multi-page app.
+
+### Backlog
+
+- [ ] Placeholder, Step/Wizard, Loader/Progress, Comment/Feed, Statistic/Graph, Hero, Calendar, Rating, Search, Shape, Sticky, dialog/alert, carousel, qr-code, diff, format-bytes-number-currency, mutation-observer and resize observer
 
 - [ ] This is a theme on its own: https://codepen.io/oathanrex/pen/EayVMqZ
 
@@ -25,6 +36,7 @@ ry-ui normalizes this. No decisions to make. No architecture to debate. An LLM c
 - [ ] cross-platform transpiler - Swift/SwiftUI (see `docs/arch/cross-platform-transpiler.md`)
 - [ ] animation system with GSAP (see `docs/plans/animation-system.md`)
 - [ ] could use to write apps on ry-os lol.. rust based linux DE with html/js/css -> Dioxus -> rust apps / with an llm on device
+- [ ] https://github.com/GrapheneOS — hardened Android, good reference for security-first OS/DE design patterns
 
 ## Quick Start
 
@@ -42,8 +54,12 @@ ry-ui normalizes this. No decisions to make. No architecture to debate. An LLM c
 - `<ry-grid cols="3">` - Responsive grid
 - `<ry-stack>` / `<ry-cluster>` - Flex layouts
 
+### Layout
+- `<ry-split>` - Resizable two-column layout with optional `persist` for localStorage-backed width
+
 ### Interactive
 - `<ry-button>` - Buttons with variants
+- `<ry-button-group>` - Segmented control / radio button group
 - `<ry-modal>` - Modal dialogs
 - `<ry-drawer>` - Slide-out panels
 - `<ry-accordion>` - Collapsible sections
@@ -54,6 +70,9 @@ ry-ui normalizes this. No decisions to make. No architecture to debate. An LLM c
 - `<ry-tooltip>` - Hover tooltips
 - `<ry-toast>` - Notifications
 
+### Forms
+- `<ry-field>` - Form field wrapper with auto label, error, and hint
+
 ### Display
 - `<ry-card>` - Card containers
 - `<ry-badge>` - Status badges
@@ -90,6 +109,23 @@ Use `<ry>` wrapper to write unprefixed markup:
   <ry-option value="uk">United Kingdom</ry-option>
 </ry-select>
 
+<!-- Split Panel (resizable, persistent) -->
+<ry-split resizable persist="sidebar">
+  <main>Main content</main>
+  <aside>Sidebar</aside>
+</ry-split>
+
+<!-- Button Group -->
+<ry-button-group value="monthly">
+  <ry-button value="monthly">Monthly</ry-button>
+  <ry-button value="annually">Annually</ry-button>
+</ry-button-group>
+
+<!-- Form Field -->
+<ry-field label="Email" error="Invalid email">
+  <input type="email" name="email">
+</ry-field>
+
 <!-- Toast (programmatic) -->
 <script>
 RyToast.success('Saved!');
@@ -152,6 +188,14 @@ npm run build    # Production build
 npm run typecheck
 ```
 
+## Publishing
+
+```bash
+npm run release
+```
+
+Automatically available on CDN via [unpkg](https://unpkg.com/@ryanhelsing/ry-ui/) and [jsdelivr](https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/).
+
 ## TypeScript Philosophy
 
 ry-ui is written in strict TypeScript with a "vanilla-first" approach:

package/dist/components/ry-button-group.d.ts

@@ -0,0 +1,32 @@
+/**
+ * <ry-button-group>
+ *
+ * Segmented control / button group. Groups child buttons with
+ * connected borders and optional radio-group behavior.
+ *
+ * Usage (visual grouping only):
+ * <ry-button-group>
+ *   <ry-button>Left</ry-button>
+ *   <ry-button>Center</ry-button>
+ *   <ry-button>Right</ry-button>
+ * </ry-button-group>
+ *
+ * Usage (radio behavior — single selection):
+ * <ry-button-group name="mode" value="terminal">
+ *   <ry-button value="direct">Direct</ry-button>
+ *   <ry-button value="terminal">Terminal</ry-button>
+ *   <ry-button value="release">Release</ry-button>
+ * </ry-button-group>
+ *
+ * Emits ry:change with { value } when selection changes.
+ */
+import { RyElement } from '../core/ry-element.js';
+export declare class RyButtonGroup extends RyElement {
+    #private;
+    static get observedAttributes(): string[];
+    get value(): string;
+    set value(v: string);
+    setup(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+}
+//# sourceMappingURL=ry-button-group.d.ts.map

package/dist/components/ry-button-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ry-button-group.d.ts","sourceRoot":"","sources":["../../src/ts/components/ry-button-group.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,qBAAa,aAAc,SAAQ,SAAS;;IAC1C,MAAM,KAAK,kBAAkB,IAAI,MAAM,EAAE,CAExC;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,KAAK,CAAC,CAAC,EAAE,MAAM,EAElB;IAED,KAAK,IAAI,IAAI;IAMb,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;CAiC/F"}

package/dist/components/ry-carousel.d.ts

@@ -0,0 +1,21 @@
+/**
+ * <ry-carousel>
+ *
+ * Content slider with autoplay, touch/swipe, dots, arrows, keyboard nav.
+ *
+ * Usage:
+ * <ry-carousel autoplay interval="5000" dots arrows loop>
+ *   <div>Slide 1</div>
+ *   <div>Slide 2</div>
+ * </ry-carousel>
+ */
+import { RyElement } from '../core/ry-element.js';
+export declare class RyCarousel extends RyElement {
+    #private;
+    setup(): void;
+    goTo(index: number): void;
+    next(): void;
+    prev(): void;
+    teardown(): void;
+}
+//# sourceMappingURL=ry-carousel.d.ts.map

package/dist/components/ry-carousel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ry-carousel.d.ts","sourceRoot":"","sources":["../../src/ts/components/ry-carousel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,qBAAa,UAAW,SAAQ,SAAS;;IAOvC,KAAK,IAAI,IAAI;IAgJb,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IA6BzB,IAAI,IAAI,IAAI;IAIZ,IAAI,IAAI,IAAI;IAIZ,QAAQ,IAAI,IAAI;CAGjB"}