@ryanhelsing/ry-ui 1.0.2 → 1.0.3

package/docs/components/layout.md

@@ -0,0 +1,189 @@
+# 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 (300px). Stacks vertically on mobile (<768px).
+
+```html
+<ry-split>
+  <div>Main content (flex: 1)</div>
+  <div>Sidebar (300px)</div>
+</ry-split>
+```
+
+## `<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());
+```

package/docs/theming.md

@@ -0,0 +1,182 @@
+# ry-ui Theming Guide
+
+## Built-in Themes
+
+Set on `<html>`:
+```html
+<html data-ry-theme="light">  <!-- light | dark | ocean -->
+```
+
+Toggle at runtime:
+```html
+<ry-theme-toggle themes="light,dark"></ry-theme-toggle>
+```
+
+Or programmatically:
+```js
+document.documentElement.setAttribute('data-ry-theme', 'dark');
+```
+
+## Dark Mode
+
+Dark mode is built into the base bundle via `light-dark()` + `color-scheme`. No extra files needed.
+
+```html
+<!-- This is all you need — dark mode works automatically -->
+<link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/css/ry-ui.css">
+```
+
+Without a `data-ry-theme` attribute, the OS preference is respected automatically. Setting `data-ry-theme="dark"` forces dark mode.
+
+## Token Override (Quickest Customization)
+
+Use the full bundle, override specific tokens:
+
+```css
+:root {
+  --ry-color-primary: oklch(0.541 0.218 293);
+  --ry-color-primary-hover: oklch(0.491 0.234 292);
+  --ry-radius-md: 0;
+  --ry-radius-lg: 0;
+}
+```
+
+> **Note:** Tokens use `oklch()` color values. Hex still works for overrides but won't participate in `light-dark()` automatic switching. For dark-aware overrides, use `light-dark()`:
+> ```css
+> :root {
+>   --ry-color-primary: light-dark(oklch(0.541 0.218 293), oklch(0.65 0.2 293));
+> }
+> ```
+
+## Custom Theme (Full Control)
+
+Load structure only, bring your own visuals:
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/css/ry-structure.css">
+<link rel="stylesheet" href="/your-tokens.css">
+<link rel="stylesheet" href="/your-theme.css">
+```
+
+Structure CSS has layout only — no colors, shadows, borders. Your theme provides all visuals.
+
+## Token Reference
+
+### Colors
+
+All color tokens use `oklch()` and `light-dark()` for automatic dark mode:
+
+```css
+--ry-color-primary: light-dark(oklch(0.623 0.188 259.8), oklch(0.714 0.143 254.6));
+--ry-color-primary-hover: light-dark(oklch(0.546 0.215 262.9), oklch(0.623 0.188 259.8));
+--ry-color-primary-active: light-dark(oklch(0.488 0.217 264.4), oklch(0.546 0.215 262.9));
+--ry-color-secondary: light-dark(oklch(0.554 0.041 257.4), oklch(0.714 0.035 253.3));
+--ry-color-success: light-dark(oklch(0.723 0.192 149.6), oklch(0.723 0.192 149.6));
+--ry-color-warning: light-dark(oklch(0.769 0.165 70.1), oklch(0.769 0.165 70.1));
+--ry-color-danger: light-dark(oklch(0.637 0.208 25.3), oklch(0.637 0.208 25.3));
+--ry-color-info: light-dark(oklch(0.715 0.126 215.2), oklch(0.715 0.126 215.2));
+--ry-color-text: light-dark(oklch(0.279 0.037 260), oklch(0.95 0.008 255));
+--ry-color-text-muted: light-dark(oklch(0.554 0.041 257.4), oklch(0.714 0.035 253.3));
+--ry-color-text-inverse: light-dark(oklch(1 0 0), oklch(0.279 0.037 260));
+--ry-color-bg: light-dark(oklch(1 0 0), oklch(0.205 0.027 261));
+--ry-color-bg-subtle: light-dark(oklch(0.984 0.003 248.2), oklch(0.249 0.03 261));
+--ry-color-bg-muted: light-dark(oklch(0.968 0.007 248.1), oklch(0.279 0.033 261));
+--ry-color-border: light-dark(oklch(0.929 0.013 255.6), oklch(0.372 0.039 257.3));
+--ry-color-overlay: light-dark(oklch(0 0 0 / 0.5), oklch(0 0 0 / 0.7));
+```
+
+### Typography
+```css
+--ry-font-sans: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+--ry-font-mono: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
+
+/* Sizes */
+--ry-text-xs: 0.75rem;
+--ry-text-sm: 0.875rem;
+--ry-text-base: 1rem;
+--ry-text-lg: 1.125rem;
+--ry-text-xl: 1.25rem;
+--ry-text-2xl: 1.5rem;
+--ry-text-3xl: 1.875rem;
+--ry-text-4xl: 2.25rem;
+
+/* Weights */
+--ry-font-normal: 400;
+--ry-font-medium: 500;
+--ry-font-semibold: 600;
+--ry-font-bold: 700;
+```
+
+### Spacing
+```css
+--ry-space-0: 0;
+--ry-space-1: 0.25rem;
+--ry-space-2: 0.5rem;
+--ry-space-3: 0.75rem;
+--ry-space-4: 1rem;
+--ry-space-5: 1.25rem;
+--ry-space-6: 1.5rem;
+--ry-space-8: 2rem;
+--ry-space-10: 2.5rem;
+--ry-space-12: 3rem;
+--ry-space-16: 4rem;
+--ry-space-20: 5rem;
+```
+
+### Border Radius
+```css
+--ry-radius-none: 0;
+--ry-radius-sm: 0.25rem;
+--ry-radius-md: 0.375rem;
+--ry-radius-lg: 0.5rem;
+--ry-radius-xl: 0.75rem;
+--ry-radius-2xl: 1rem;
+--ry-radius-full: 9999px;
+```
+
+### Shadows
+
+Shadows use sub-tokens for dark-mode-aware intensity:
+
+```css
+--ry-shadow-color: light-dark(oklch(0 0 0 / 0.1), oklch(0 0 0 / 0.4));
+--ry-shadow-sm: 0 1px 2px 0 var(--ry-shadow-color-sm);
+--ry-shadow-md: 0 4px 6px -1px var(--ry-shadow-color), 0 2px 4px -2px var(--ry-shadow-color);
+--ry-shadow-lg: 0 10px 15px -3px var(--ry-shadow-color), 0 4px 6px -4px var(--ry-shadow-color);
+--ry-shadow-xl: 0 20px 25px -5px var(--ry-shadow-color), 0 8px 10px -6px var(--ry-shadow-color);
+```
+
+### Transitions
+```css
+--ry-duration-fast: 100ms;
+--ry-duration-normal: 200ms;
+--ry-duration-slow: 300ms;
+--ry-ease: cubic-bezier(0.4, 0, 0.2, 1);
+--ry-ease-in: cubic-bezier(0.4, 0, 1, 1);
+--ry-ease-out: cubic-bezier(0, 0, 0.2, 1);
+```
+
+### Z-Index Layers
+```css
+--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;
+```
+
+### Focus
+```css
+--ry-focus-ring: 0 0 0 3px light-dark(oklch(0.623 0.188 259.8 / 0.5), oklch(0.714 0.143 254.6 / 0.5));
+```
+
+## Best Practices
+
+- Always use `--ry-*` tokens instead of hardcoding values
+- Use `var(--ry-color-text)` and `var(--ry-color-bg)` on your own elements to stay theme-consistent
+- Semantic colors (`success`, `warning`, `danger`, `info`) are available as both `--ry-color-*` tokens and component `variant`/`type`/`color` attributes
+- For inline styles, reference tokens: `style="color: var(--ry-color-text-muted); padding: var(--ry-space-4);"`
+- Set `background: var(--ry-color-bg); color: var(--ry-color-text);` on `<body>` for full-page theme support

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanhelsing/ry-ui",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Framework-agnostic, Light DOM web components. CSS is the source of truth.",
   "type": "module",
   "main": "./dist/ry-ui.js",
@@ -16,13 +16,15 @@
   },
   "files": [
     "dist",
-    "USING_CDN.md"
+    "AGENTS.md",
+    "docs/components",
+    "docs/theming.md"
   ],
   "scripts": {
     "dev": "vite",
     "build": "vite build && npm run build:types && npm run build:css",
     "build:types": "tsc --emitDeclarationOnly",
-    "build:css": "mkdir -p dist/css && cp src/css/*.css dist/css/ && mkdir -p dist/themes && cp src/themes/*.css dist/themes/",
+    "build:css": "mkdir -p dist/css && node -e \"const fs=require('fs'); const files=['src/css/ry-tokens.css','src/css/ry-structure.css','src/css/ry-theme.css']; const out=files.map(f=>fs.readFileSync(f,'utf8')).join('\\n'); fs.writeFileSync('dist/css/ry-ui.css',out);\" && cp src/css/ry-tokens.css src/css/ry-structure.css src/css/ry-theme.css dist/css/ && mkdir -p dist/themes && cp src/themes/*.css dist/themes/",
     "preview": "vite preview",
     "typecheck": "tsc --noEmit"
   },