npm - @ryanhelsing/ry-ui - Versions diffs - 1.0.9 → 1.0.11 - Mend

@ryanhelsing/ry-ui 1.0.9 → 1.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/.claude/skills/ry-ui-builder/SKILL.md +186 -0
package/README.dev.md +302 -0
package/README.md +462 -187
package/dist/_redirects +1 -0
package/dist/app.d.ts +2 -0
package/dist/app.d.ts.map +1 -0
package/dist/components/ry-testimonial.d.ts +19 -0
package/dist/components/ry-testimonial.d.ts.map +1 -0
package/dist/components/ry-theme-panel.d.ts +25 -0
package/dist/components/ry-theme-panel.d.ts.map +1 -0
package/dist/core/ry-icons.d.ts.map +1 -1
package/dist/core/ry-transform.d.ts.map +1 -1
package/dist/css/ry-structure.css +122 -3
package/dist/css/ry-theme.css +133 -0
package/dist/css/ry-tokens.css +4 -26
package/dist/css/ry-ui.css +259 -29
package/dist/pages/components.html +1827 -0
package/dist/pages/landing.html +229 -0
package/dist/ry-ui.d.ts +2 -0
package/dist/ry-ui.d.ts.map +1 -1
package/dist/ry-ui.js +382 -245
package/dist/ry-ui.js.map +1 -1
package/dist/themes/antigravity.css +56 -0
package/docs/components/forms.md +10 -3
package/package.json +12 -6
package/AGENT.md +0 -490
package/AGENTS.md +0 -57

package/.claude/skills/ry-ui-builder/SKILL.md ADDED Viewed

@@ -0,0 +1,186 @@
+---
+name: ry-ui-builder
+description: Build UIs with ry-ui web components. Use when creating pages, layouts, forms, dashboards, or any HTML interface. Provides component catalog, patterns, and anti-patterns so you use existing components instead of writing custom CSS/JS.
+user-invocable: true
+---
+# ry-ui Component Builder
+**ALWAYS use ry-ui components instead of writing custom CSS or JavaScript.**
+## Setup
+Add these two lines to any HTML page:
+```html
+<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>
+```
+Set theme: `<html data-ry-theme="light">` (or `"dark"`, or omit for OS preference)
+Set body: `<body style="background: var(--ry-color-bg); color: var(--ry-color-text);">`
+## Rules
+1. **NEVER write custom modal, dropdown, tab, accordion, toast, or button CSS.** ry-ui has these built in.
+2. **NEVER write flexbox/grid layout CSS for page structure.** Use `<ry-page>`, `<ry-header>`, `<ry-main>`, `<ry-grid>`, `<ry-stack>`, `<ry-cluster>`.
+3. **NEVER create CSS variables for colors or spacing.** Use `--ry-color-*`, `--ry-space-*`, `--ry-radius-*` tokens.
+4. **DO use ry-ui tokens** in any custom CSS you write: `color: var(--ry-color-text-muted)`, `padding: var(--ry-space-4)`.
+5. **DO compose pages from ry-ui primitives** — they handle accessibility, keyboard nav, focus trapping, and dark mode automatically.
+## Page Template
+```html
+<!DOCTYPE html>
+<html lang="en" data-ry-theme="light">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My App</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/dist/css/ry-ui.css">
+</head>
+<body style="background: var(--ry-color-bg); color: var(--ry-color-text);">
+  <ry-page>
+    <ry-header sticky>
+      <ry-cluster><strong>App Name</strong></ry-cluster>
+      <ry-actions><ry-theme-toggle themes="light,dark"></ry-theme-toggle></ry-actions>
+    </ry-header>
+    <ry-main>
+      <ry-section>
+        <!-- your content -->
+      </ry-section>
+    </ry-main>
+    <ry-footer>Footer</ry-footer>
+  </ry-page>
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/dist/ry-ui.js"></script>
+</body>
+</html>
+```
+## Component Reference
+### Layout (CSS-only)
+- `<ry-page>` — root container, full height
+- `<ry-header sticky>` — top bar, space-between
+- `<ry-main>` — centered content, max-width 1200px
+- `<ry-footer>` — footer with border-top
+- `<ry-section>` — content block with margin
+- `<ry-grid cols="3">` — responsive grid (cols-sm, cols-md, cols-lg for breakpoints)
+- `<ry-stack gap="md">` — vertical flex
+- `<ry-cluster gap="sm">` — horizontal flex, wraps
+- `<ry-center>` — center both axes
+- `<ry-card>` — card container (lifts on hover), `interactive` for clickable
+- `<ry-split resizable persist="key">` — two-column with drag resize
+- `<ry-divider>` / `<ry-divider vertical>` — separator line
+- `<ry-nav>` — nav links, active: `<a aria-current="page">`
+- `<ry-logo>` — bold inline text
+- `<ry-actions>` — flex row for buttons
+### Buttons
+```html
+<ry-button>Default</ry-button>
+<ry-button variant="primary|secondary|outline|ghost|danger|accent">Styled</ry-button>
+<ry-button size="sm|lg">Sized</ry-button>
+<ry-button modal="modal-id">Opens modal</ry-button>
+<ry-button drawer="drawer-id">Opens drawer</ry-button>
+<ry-button disabled>Disabled</ry-button>
+```
+### Modal
+```html
+<ry-button modal="my-modal">Open</ry-button>
+<ry-modal id="my-modal" title="Title">Content</ry-modal>
+```
+### Drawer
+```html
+<ry-button drawer="my-drawer">Open</ry-button>
+<ry-drawer id="my-drawer" side="left|right|bottom" title="Title">Content</ry-drawer>
+```
+### Tabs
+```html
+<ry-tabs>
+  <ry-tab title="Tab 1" active>Content 1</ry-tab>
+  <ry-tab title="Tab 2">Content 2</ry-tab>
+</ry-tabs>
+```
+### Accordion
+```html
+<ry-accordion>
+  <ry-accordion-item title="Section" open>Content</ry-accordion-item>
+</ry-accordion>
+```
+### Forms
+```html
+<ry-field label="Email" hint="Help text" error="Error msg">
+  <input type="email">
+</ry-field>
+<ry-select placeholder="Choose..." name="field">
+  <ry-option value="a">A</ry-option>
+</ry-select>
+<ry-switch name="toggle" checked></ry-switch>
+<!-- ry:change event detail: { value: "true"/"false" (STRING not boolean!), label: "on"/"off" }
+     Use e.detail.value === 'true' to get a boolean — "false" is truthy in JS! -->
+<ry-slider min="0" max="100" value="50"></ry-slider>
+```
+### Dropdown Menu
+```html
+<ry-dropdown>
+  <ry-button slot="trigger">Menu</ry-button>
+  <ry-menu>
+    <ry-menu-item>Item</ry-menu-item>
+  </ry-menu>
+</ry-dropdown>
+```
+### Display
+```html
+<ry-alert type="info|success|warning|danger" dismissible>Message</ry-alert>
+<ry-badge variant="primary|success|warning|danger|accent">Label</ry-badge>
+<ry-tooltip content="Help" position="top|bottom|left|right"><span>Hover me</span></ry-tooltip>
+```
+### Toast (JS only)
+```javascript
+RyToast.success('Saved!');
+RyToast.error('Failed');
+RyToast.info('FYI');
+RyToast.warning('Careful');
+```
+### Button Group
+```html
+<ry-button-group name="view" value="grid">
+  <ry-button value="grid">Grid</ry-button>
+  <ry-button value="list">List</ry-button>
+</ry-button-group>
+```
+### Events
+All events prefixed `ry:` — `ry:change`, `ry:open`, `ry:close`, `ry:click`, `ry:select`
+```javascript
+element.addEventListener('ry:change', (e) => console.log(e.detail));
+document.querySelector('ry-modal').open();
+document.querySelector('ry-modal').close();
+```
+## Theming
+Override tokens — no build step:
+```css
+:root {
+  --ry-color-primary: oklch(0.541 0.218 293);
+  --ry-radius-md: 0;
+}
+```
+Key tokens: `--ry-color-{primary,secondary,accent,success,warning,danger,info,text,bg,border}`,
+`--ry-space-{1-20}`, `--ry-radius-{sm,md,lg,full}`, `--ry-shadow-{sm,md,lg,xl}`

package/README.dev.md ADDED Viewed

@@ -0,0 +1,302 @@
+# ry-ui
+Framework-agnostic, Light DOM web components. CSS is the source of truth.
+## North Star
+There are only so many types of things we do in any app. There should be one opinionated default way to do each of them. Invent all the wheels once, then never again.
+Every app is a composition of the same finite primitives: layout, navigation, data display, data entry, feedback, actions, auth, state. The patterns are solved. The industry just keeps re-solving them because engineers enjoy the puzzle.
+ry-ui normalizes this. No decisions to make. No architecture to debate. An LLM can leverage these primitives to build any app, anywhere, with a structure that is grokkable, dumb, and repeatable. Over-engineering becomes irrelevant when there's nothing left to over-engineer.
+**The goal:** Write once in HTML/CSS/JS. Deploy to web, iOS, Android, desktop. The primitives are portable because they're universal.
+### FUNCTION / FORM / THEME
+Every component is three independent layers:
+- **FUNCTION** (JS) — Behavior. Extends `RyElement`. Manages state, events, keyboard, ARIA. Queries via `data-ry-target`.
+- **FORM** (Structure CSS) — Layout. `ry-structure.css`. Display, flex, grid, padding, overflow, transform/opacity transitions. No colors.
+- **THEME** (Visual CSS) — Appearance. `ry-theme.css`. Colors, shadows, borders, typography, focus rings. Entirely swappable.
+These layers are independently replaceable. Structure works with any theme or no theme. Function works regardless of CSS loaded.
+---
+- [x] separate the css minimal structure from the theme
+- [x] separate the component behavior from the design (see `docs/arch/behavior-style-separation.md`)
+### 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
+- [ ] bring in examples and extract and normalize - Flat Clean (accord/tailwind) / Flat Fun Waves (zevo) / Game (mario/astrobot/stardew/animal crossing) / Brute (square game) / Skeuomorphic / Glass ( dark and light, color sets 1,2,3 )
+- [ ] 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
+```html
+<link rel="stylesheet" href="https://cdn.example.com/ry-ui.css">
+<script type="module" src="https://cdn.example.com/ry-ui.js"></script>
+```
+## Components
+### Layout (CSS-only)
+- `<ry-page>` - Page container
+- `<ry-header>` / `<ry-footer>` - Page sections
+- `<ry-main>` / `<ry-section>` - Content areas
+- `<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
+- `<ry-tabs>` - Tabbed content
+- `<ry-dropdown>` - Dropdown menus
+- `<ry-select>` - Custom select
+- `<ry-combobox>` - Searchable dropdown
+- `<ry-switch>` - Toggle switch
+- `<ry-tooltip>` - Hover tooltips
+- `<ry-toast>` - Notifications
+- `<ry-theme-panel>` - Floating theme/mode selector (none, default, ocean + light/dark)
+- `<ry-testimonial>` - Customer testimonial / quote card with avatar and star rating
+### Forms
+- `<ry-field>` - Form field wrapper with auto label, error, and hint
+### Display
+- `<ry-card>` - Card containers
+- `<ry-badge>` - Status badges
+- `<ry-alert>` - Alert messages
+## Clean Syntax
+Use `<ry>` wrapper to write unprefixed markup:
+```html
+<ry>
+  <accordion>
+    <accordion-item title="FAQ" open>
+      No ry- prefix needed inside the wrapper.
+    </accordion-item>
+  </accordion>
+</ry>
+```
+## Examples
+```html
+<!-- Modal -->
+<ry-button modal="demo">Open Modal</ry-button>
+<ry-modal id="demo" title="Hello">Content here</ry-modal>
+<!-- Drawer -->
+<ry-button drawer="menu">Open</ry-button>
+<ry-drawer id="menu" side="left">Menu content</ry-drawer>
+<!-- Select -->
+<ry-select placeholder="Country" name="country">
+  <ry-option value="us">United States</ry-option>
+  <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!');
+RyToast.error('Failed');
+</script>
+```
+## Themes
+Theme and mode are orthogonal — every theme supports light and dark:
+```html
+<!-- Theme controls visual skin -->
+<html data-ry-theme="ocean">
+<!-- Mode controls light/dark (independent of theme) -->
+<html data-ry-mode="dark">
+<!-- "none" theme shows pure structure (no visual styling) -->
+<html data-ry-theme="none">
+```
+Available themes: `none`, `default`, `ocean`
+Available modes: `auto` (OS preference), `light`, `dark`
+Use `<ry-theme-panel>` for an interactive floating selector.
+## CSS Architecture
+ry-ui separates **structure** (layout/behavior) from **theme** (visual styling):
+```
+ry-tokens.css     # Design tokens (CSS variables)
+ry-structure.css  # Pure layout - no colors, shadows, or borders
+ry-theme.css      # All visual styling
+ry-ui.css         # Bundled (all three combined)
+```
+### Custom Themes
+For completely custom styling, load only structure + your own theme:
+```html
+<!-- Use default look -->
+<link rel="stylesheet" href="ry-ui.css">
+<!-- OR: Custom theme -->
+<link rel="stylesheet" href="ry-structure.css">
+<link rel="stylesheet" href="your-tokens.css">
+<link rel="stylesheet" href="your-theme.css">
+```
+Structure CSS contains only:
+- Display modes, positioning, flexbox, grid
+- Sizing, padding, margins, gaps
+- State transitions (opacity, visibility, transform)
+Theme CSS contains:
+- Colors, backgrounds, borders
+- Shadows, border-radius
+- Typography styling
+- Focus rings
+---
+## Development
+```bash
+npm install
+npm run dev      # Dev server with HMR
+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:
+### No Decorators, No Magic
+We use plain class syntax with private fields (`#field`) instead of decorators. The code reads like standard JavaScript with type annotations.
+```typescript
+// What we do
+class RySelect extends RyElement {
+  #highlightedIndex = -1;
+  #typeahead = '';
+  setup(): void { ... }
+}
+// What we avoid
+@customElement('ry-select')
+class RySelect extends LitElement {
+  @property() value = '';
+  @state() private _open = false;
+}
+```
+### Strict Mode, No Exceptions
+```json
+{
+  "strict": true,
+  "noUncheckedIndexedAccess": true,
+  "noImplicitReturns": true
+}
+```
+### Type Patterns
+**Explicit over inferred for public APIs:**
+```typescript
+get value(): string { return this.getAttribute('value') ?? ''; }
+emit<T = void>(name: string, detail?: T): boolean { ... }
+```
+**Union types for constrained values:**
+```typescript
+type ToastVariant = 'info' | 'success' | 'warning' | 'error';
+static observedAttributes = ['value', 'disabled'] as const;
+```
+**Extend globals for custom events:**
+```typescript
+declare global {
+  interface HTMLElementEventMap {
+    'ry:change': CustomEvent<{ value: string }>;
+  }
+}
+```
+### Build Output
+Single bundled ESM file for CDN simplicity:
+```
+dist/
+├── ry-ui.js      # 32KB (7KB gzip)
+├── ry-ui.js.map  # Source maps
+└── ry-ui.d.ts    # Type declarations
+```
+Vite builds with esbuild for speed, Rollup for optimization, and generates `.d.ts` for library consumers.
+---
+## Inspiration
+- [/e/OS](https://e.foundation/e-os/) — deGoogled Android OS focused on privacy and user freedom
+- [Ramotion](https://dribbble.com/ramotion) — UI/UX design inspiration on Dribbble
+- [Landing Folio](https://www.landingfolio.com/library) — Landing page design inspiration and components
+---
+See [CLAUDE.md](CLAUDE.md) for component development guide.