@ryanhelsing/ry-ui 1.0.2 → 1.0.4

package/docs/components/knob.md

@@ -0,0 +1,42 @@
+# Knob
+
+## `<ry-knob>`
+
+Rotary dial control. Great for audio/settings UIs.
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `min` | number | Minimum (default: 0) |
+| `max` | number | Maximum (default: 100) |
+| `step` | number | Step (default: 0 = smooth) |
+| `value` | number | Current value |
+| `label` | string | Label below knob |
+| `labels` | string | Comma-separated labels for discrete steps |
+| `description` | string | Tooltip on hover |
+| `color` | primary \| secondary \| success \| warning \| danger | Track color |
+| `size` | sm \| lg | Size |
+| `disabled` | boolean | Disable |
+
+Events: `ry:input` (during drag), `ry:change` (on release)
+
+```html
+<ry-knob min="0" max="100" value="50" label="Volume"></ry-knob>
+<ry-knob min="0" max="3" step="1" value="1" labels="Off,Low,Med,High" label="Mode"></ry-knob>
+<ry-knob value="60" color="warning" label="Warning"></ry-knob>
+<ry-knob size="sm" value="25" label="Small"></ry-knob>
+```
+
+JS:
+```js
+const knob = document.querySelector('ry-knob');
+
+knob.addEventListener('ry:input', (e) => {
+  updateVolume(e.detail.value); // fires during drag
+});
+knob.addEventListener('ry:change', (e) => {
+  saveSettings({ volume: e.detail.value }); // fires on release
+});
+
+knob.value;      // 50
+knob.value = 75;
+```

package/docs/components/layout.md

@@ -0,0 +1,217 @@
+# Layout Components
+
+CSS-only layout primitives. No JavaScript needed.
+
+## `<ry-page>`
+
+Top-level page shell. Contains header, main, footer.
+
+```html
+<ry-page>
+  <ry-header sticky>...</ry-header>
+  <ry-main>...</ry-main>
+  <ry-footer>...</ry-footer>
+</ry-page>
+```
+
+## `<ry-header>`
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `sticky` | boolean | Sticks to top of viewport |
+
+Horizontal flex with space-between. Two direct children = left and right.
+
+```html
+<ry-header sticky>
+  <ry-cluster><strong>App</strong></ry-cluster>
+  <ry-cluster><ry-theme-toggle themes="light,dark"></ry-theme-toggle></ry-cluster>
+</ry-header>
+```
+
+## `<ry-grid>`
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `cols` | 1–6 | Number of columns |
+
+```html
+<ry-grid cols="3">
+  <ry-card>One</ry-card>
+  <ry-card>Two</ry-card>
+  <ry-card>Three</ry-card>
+</ry-grid>
+```
+
+## `<ry-stack>`
+
+Vertical flex layout.
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `gap` | sm \| md \| lg | Vertical spacing |
+
+```html
+<ry-stack gap="sm">
+  <p>Item 1</p>
+  <p>Item 2</p>
+</ry-stack>
+```
+
+## `<ry-cluster>`
+
+Horizontal flex, wraps.
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `gap` | sm \| md \| lg | Horizontal spacing |
+
+```html
+<ry-cluster>
+  <ry-badge>A</ry-badge>
+  <ry-badge>B</ry-badge>
+</ry-cluster>
+```
+
+## `<ry-card>`
+
+Content container with padding and border. Use `<ry-actions>` inside for button groups.
+
+```html
+<ry-card>
+  <h3>Title</h3>
+  <p>Content.</p>
+  <ry-actions>
+    <ry-button>Save</ry-button>
+    <ry-button variant="ghost">Cancel</ry-button>
+  </ry-actions>
+</ry-card>
+```
+
+## `<ry-section>`
+
+Content section block. Adds bottom margin between sections, removed on last child.
+
+```html
+<ry-main>
+  <ry-section><h2>Section 1</h2><p>Content.</p></ry-section>
+  <ry-section><h2>Section 2</h2><p>Content.</p></ry-section>
+</ry-main>
+```
+
+## `<ry-aside>`
+
+Sidebar / secondary content block.
+
+```html
+<ry-split>
+  <ry-main>Primary content</ry-main>
+  <ry-aside>Sidebar content</ry-aside>
+</ry-split>
+```
+
+## `<ry-split>`
+
+Two-pane layout: content (flexible) + sidebar (fixed). Stacks vertically on mobile (<768px).
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `resizable` | boolean | Enables drag handle between panes |
+| `persist` | string | localStorage key — saves/restores width as `ry-split:{key}` |
+
+CSS custom properties:
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `--ry-split-width` | `300px` | Sidebar width |
+| `--ry-split-min-width` | `100px` | Minimum width during resize |
+| `--ry-split-max-width` | `80%` | Maximum width during resize |
+
+Events: `ry:resize` — `e.detail.width`
+
+```html
+<!-- Basic -->
+<ry-split>
+  <div>Main content (flex: 1)</div>
+  <div>Sidebar (300px)</div>
+</ry-split>
+
+<!-- Resizable with persistence -->
+<ry-split resizable persist="sidebar" style="--ry-split-width: 400px">
+  <main>Content</main>
+  <aside>Resizable sidebar</aside>
+</ry-split>
+```
+
+Resize interaction:
+- **Drag** handle between panes (mouse + touch)
+- **Arrow keys** ±10px, **Shift+Arrow** ±50px
+- **Home/End** jump to min/max
+- **Double-click** handle to reset to default
+
+## `<ry-center>`
+
+Centers content both horizontally and vertically.
+
+```html
+<ry-center>
+  <h1>Centered title</h1>
+  <p>Centered paragraph</p>
+</ry-center>
+```
+
+## `<ry-nav>`
+
+Horizontal navigation links. Use `aria-current="page"` to highlight the active link.
+
+```html
+<ry-nav>
+  <a href="/" aria-current="page">Home</a>
+  <a href="/about">About</a>
+  <a href="/contact">Contact</a>
+</ry-nav>
+```
+
+## `<ry-logo>`
+
+Inline logo element. Bold, large text. Typically used inside `<ry-header>`.
+
+```html
+<ry-header>
+  <ry-logo>My App</ry-logo>
+  <ry-nav>...</ry-nav>
+</ry-header>
+```
+
+## `<ry-actions>`
+
+Horizontal button group. Use inside cards, modals, or any container.
+
+```html
+<ry-actions>
+  <ry-button>Primary</ry-button>
+  <ry-button variant="ghost">Cancel</ry-button>
+</ry-actions>
+```
+
+## `<ry-divider>`
+
+Horizontal or vertical separator line.
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `vertical` | boolean | Vertical orientation (for use inside flex rows) |
+
+```html
+<ry-stack>
+  <p>Above</p>
+  <ry-divider></ry-divider>
+  <p>Below</p>
+</ry-stack>
+
+<ry-cluster>
+  <span>Left</span>
+  <ry-divider vertical></ry-divider>
+  <span>Right</span>
+</ry-cluster>
+```

package/docs/components/modal.md

@@ -0,0 +1,38 @@
+# Modal
+
+## `<ry-modal>`
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `id` | string | Identifier (match button's `modal` attr) |
+| `title` | string | Header title |
+
+Put `close` attribute on any button inside to dismiss. Uses focus trapping.
+
+Events: `ry:open`, `ry:close`
+API: `.open()`, `.close()`, `.state`
+
+```html
+<ry-button modal="demo">Open</ry-button>
+
+<ry-modal id="demo" title="Confirm">
+  <p>Are you sure?</p>
+  <ry-actions slot="footer">
+    <ry-button variant="ghost" close>Cancel</ry-button>
+    <ry-button>OK</ry-button>
+  </ry-actions>
+</ry-modal>
+```
+
+JS:
+```js
+const modal = document.querySelector('ry-modal');
+
+modal.addEventListener('ry:open', () => console.log('opened'));
+modal.addEventListener('ry:close', () => console.log('closed'));
+
+// Programmatic
+modal.open();
+modal.close();
+modal.state; // "open" or "closed"
+```

package/docs/components/number-select.md

@@ -0,0 +1,42 @@
+# Number Select
+
+## `<ry-number-select>`
+
+Numeric stepper with increment/decrement buttons and optional drag-to-adjust.
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `min` | number | Minimum (default: 0) |
+| `max` | number | Maximum (default: 100) |
+| `step` | number | Step (default: 1) |
+| `value` | number | Current value |
+| `arrows` | both \| start \| end \| stacked \| stacked-end \| stacked-start \| none | Button placement |
+| `icons` | plus-minus \| chevron \| arrow | Icon style |
+| `drag` | x \| y \| none | Drag direction |
+| `prefix` | string | Before value ("$") |
+| `suffix` | string | After value ("°", "%") |
+| `editable` | boolean | Allow typing directly |
+| `wrap` | boolean | Wrap around min/max |
+| `size` | xs \| sm \| lg | Size |
+| `disabled` | boolean | Disable |
+
+Events: `ry:input` (during drag), `ry:change` (on commit)
+
+```html
+<ry-number-select min="0" max="100" value="50"></ry-number-select>
+<ry-number-select min="0" max="360" value="90" suffix="°" arrows="stacked" icons="chevron"></ry-number-select>
+<ry-number-select min="0" max="1000" value="50" prefix="$" editable></ry-number-select>
+<ry-number-select min="0" max="7" value="3" wrap></ry-number-select>
+```
+
+JS:
+```js
+const ns = document.querySelector('ry-number-select');
+
+ns.addEventListener('ry:input', (e) => console.log(e.detail.value));
+ns.addEventListener('ry:change', (e) => console.log(e.detail.value));
+
+ns.value;      // 50
+ns.value = 75;
+ns.step = 5;
+```

package/docs/components/slider.md

@@ -0,0 +1,48 @@
+# Slider
+
+## `<ry-slider>`
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `min` | number | Minimum (default: 0) |
+| `max` | number | Maximum (default: 100) |
+| `step` | number | Step (default: 1, 0 = smooth) |
+| `value` | number | Current value (single mode) |
+| `start` / `end` | number | Range values (with `range`) |
+| `range` | boolean | Dual-handle mode |
+| `labeled` | boolean | Show min/max labels |
+| `ticked` | boolean | Show tick marks |
+| `tooltip` | boolean | Show value on hover |
+| `vertical` | boolean | Vertical orientation |
+| `reversed` | boolean | Reverse direction |
+| `color` | primary \| secondary \| success \| warning \| danger \| info | Track color |
+| `size` | sm \| lg | Size |
+| `disabled` | boolean | Disable |
+
+Events: `ry:input` (during drag), `ry:change` (on release)
+
+```html
+<ry-slider min="0" max="100" value="50"></ry-slider>
+<ry-slider min="0" max="100" start="25" end="75" range labeled></ry-slider>
+<ry-slider min="0" max="10" step="1" value="5" ticked labeled tooltip></ry-slider>
+<ry-slider min="0" max="100" value="60" color="success"></ry-slider>
+```
+
+JS:
+```js
+const slider = document.querySelector('ry-slider');
+
+slider.addEventListener('ry:input', (e) => {
+  console.log(e.detail.value); // fires during drag
+});
+slider.addEventListener('ry:change', (e) => {
+  saveValue(e.detail.value); // fires on release
+});
+
+slider.value;      // 50
+slider.value = 75;
+
+// Range slider
+rangeSlider.start; // 25
+rangeSlider.end;   // 75
+```

package/docs/components/tabs.md

@@ -0,0 +1,30 @@
+# Tabs
+
+## `<ry-tabs>`
+
+| Attribute (on tab) | Values | Description |
+|---------------------|--------|-------------|
+| `title` | string | Tab label |
+| `active` | boolean | Initially selected |
+
+Events: `ry:change` — `e.detail.index`, `e.detail.title`
+
+```html
+<ry-tabs>
+  <ry-tab title="Overview" active><p>Overview content.</p></ry-tab>
+  <ry-tab title="Settings"><p>Settings content.</p></ry-tab>
+</ry-tabs>
+```
+
+JS:
+```js
+const tabs = document.querySelector('ry-tabs');
+
+tabs.addEventListener('ry:change', (e) => {
+  console.log(e.detail.index); // 0, 1, 2...
+  console.log(e.detail.title); // "Overview"
+});
+
+// Switch programmatically
+tabs.activeIndex = 1;
+```

package/docs/components/theme-toggle.md

@@ -0,0 +1,36 @@
+# Theme Toggle
+
+## `<ry-theme-toggle>`
+
+Cycles through themes on click. Sets `data-ry-theme` on `<html>`.
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `themes` | string | Comma-separated theme names (default: "light,dark") |
+
+Events: `ry:theme-change` — `e.detail.theme`
+API: `.theme` (get/set), `.toggle()`
+
+```html
+<ry-theme-toggle themes="light,dark"></ry-theme-toggle>
+<ry-theme-toggle themes="light,dark,ocean"></ry-theme-toggle>
+```
+
+JS:
+```js
+const toggle = document.querySelector('ry-theme-toggle');
+
+toggle.addEventListener('ry:theme-change', (e) => {
+  console.log(e.detail.theme); // "dark"
+});
+
+// Programmatic
+toggle.theme;         // "light"
+toggle.theme = 'dark';
+toggle.toggle();      // cycles to next
+```
+
+Or skip the component and set the theme directly:
+```js
+document.documentElement.dataset.ryTheme = 'dark';
+```

package/docs/components/toast.md

@@ -0,0 +1,27 @@
+# Toast
+
+## `RyToast` (programmatic API)
+
+No HTML element needed. Call globally after ry-ui loads.
+
+```js
+RyToast.success('Saved!');
+RyToast.error('Something went wrong');
+RyToast.warning('Please review');
+RyToast.info('New update available');
+
+// With options
+RyToast.success('Done!', { duration: 5000 }); // default: 3000ms
+```
+
+Common pattern:
+```js
+async function saveData() {
+  try {
+    await api.save(data);
+    RyToast.success('Saved!');
+  } catch (err) {
+    RyToast.error(err.message);
+  }
+}
+```

package/docs/components/tooltip.md

@@ -0,0 +1,14 @@
+# Tooltip
+
+## `<ry-tooltip>`
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `content` | string | Tooltip text |
+| `position` | top \| bottom \| left \| right | Position |
+
+```html
+<ry-tooltip content="Save changes" position="top">
+  <ry-button>Save</ry-button>
+</ry-tooltip>
+```

package/docs/components/tree.md

@@ -0,0 +1,46 @@
+# Tree
+
+## `<ry-tree>`
+
+File-tree / nested list with expand/collapse and optional drag-and-drop.
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `sortable` | boolean | Enable drag-and-drop (on tree) |
+| `no-animate` | boolean | Disable animation |
+| `label` | string | Item label (on tree-item) |
+| `open` | boolean | Expanded folder (on tree-item with children) |
+| `selected` | boolean | Selected item (on leaf tree-item) |
+
+Events: `ry:select` (file click), `ry:toggle` (folder expand/collapse), `ry:move` (drag-drop)
+API: `.toJSON()`, `.value`, `RyTree.from(json)`
+
+```html
+<ry-tree sortable>
+  <ry-tree-item label="src" open>
+    <ry-tree-item label="app">
+      <ry-tree-item label="page.tsx"></ry-tree-item>
+    </ry-tree-item>
+    <ry-tree-item label="utils.ts"></ry-tree-item>
+  </ry-tree-item>
+</ry-tree>
+```
+
+JS:
+```js
+const tree = document.querySelector('ry-tree');
+
+tree.addEventListener('ry:select', (e) => {
+  console.log(e.detail.label); // "page.tsx"
+});
+tree.addEventListener('ry:toggle', (e) => {
+  console.log(e.detail.label, e.detail.open);
+});
+tree.addEventListener('ry:move', (e) => {
+  console.log(`Moved "${e.detail.item}" ${e.detail.position} "${e.detail.target}"`);
+});
+
+// Serialize/deserialize
+tree.toJSON(); // [{ label: "src", open: true, children: [...] }]
+const copy = RyTree.from(tree.toJSON());
+```