@ryanhelsing/ry-ui 1.0.0 → 1.0.1

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 (12) hide show
  1. package/USING_CDN.md +390 -0
  2. package/dist/components/ry-example.d.ts +7 -0
  3. package/dist/components/ry-example.d.ts.map +1 -1
  4. package/dist/css/ry-structure.css +30 -0
  5. package/dist/css/ry-theme.css +14 -0
  6. package/dist/css/ry-ui.css +8 -0
  7. package/dist/ry-ui.js +87 -73
  8. package/dist/ry-ui.js.map +1 -1
  9. package/dist/themes/dark.css +92 -0
  10. package/dist/themes/light.css +38 -0
  11. package/dist/themes/ocean.css +48 -0
  12. package/package.json +6 -4
package/USING_CDN.md ADDED
@@ -0,0 +1,390 @@
1
+ # Using ry-ui via CDN
2
+
3
+ ## Quick Start
4
+
5
+ ```html
6
+ <!DOCTYPE html>
7
+ <html lang="en" data-ry-theme="light">
8
+ <head>
9
+ <meta charset="UTF-8">
10
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
11
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/css/ry-ui.css">
12
+ </head>
13
+ <body>
14
+ <ry-button>Hello World</ry-button>
15
+
16
+ <script type="module" src="https://unpkg.com/@ryanhelsing/ry-ui/dist/ry-ui.js"></script>
17
+ </body>
18
+ </html>
19
+ ```
20
+
21
+ ## CDN URLs
22
+
23
+ The package is available via unpkg and jsdelivr:
24
+
25
+ **unpkg:**
26
+ ```
27
+ https://unpkg.com/@ryanhelsing/ry-ui/dist/ry-ui.js
28
+ https://unpkg.com/@ryanhelsing/ry-ui/dist/css/ry-ui.css
29
+ ```
30
+
31
+ **jsdelivr:**
32
+ ```
33
+ https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/dist/ry-ui.js
34
+ https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/dist/css/ry-ui.css
35
+ ```
36
+
37
+ ## Element Syntax: Prefixed vs Wrapper
38
+
39
+ CDN users should use **prefixed elements** (`<ry-button>`, `<ry-modal>`, etc.):
40
+
41
+ ```html
42
+ <ry-button variant="primary">Click me</ry-button>
43
+
44
+ <ry-modal id="demo" title="Hello">
45
+ Modal content here
46
+ </ry-modal>
47
+
48
+ <ry-accordion>
49
+ <ry-accordion-item title="First" open>Content</ry-accordion-item>
50
+ <ry-accordion-item title="Second">More content</ry-accordion-item>
51
+ </ry-accordion>
52
+ ```
53
+
54
+ ### The `<ry>` Wrapper (Optional)
55
+
56
+ The kitchen sink demo uses a clean syntax wrapper that transforms unprefixed tags:
57
+
58
+ ```html
59
+ <ry>
60
+ <button>Becomes ry-button</button>
61
+ <modal id="demo">Becomes ry-modal</modal>
62
+ </ry>
63
+ ```
64
+
65
+ This works via CDN too, but **prefixed elements are recommended** because:
66
+ - No transformation step needed
67
+ - Works immediately as the page loads
68
+ - More explicit about what components are being used
69
+ - Better IDE/editor support
70
+
71
+ The `<ry>` wrapper runs automatically when ry-ui.js loads. Both syntaxes work together:
72
+
73
+ ```html
74
+ <ry>
75
+ <accordion>
76
+ <ry-accordion-item>Prefixed - unchanged</ry-accordion-item>
77
+ <accordion-item>Unprefixed - gets transformed</accordion-item>
78
+ </accordion>
79
+ </ry>
80
+ ```
81
+
82
+ ## Themes
83
+
84
+ The base CSS includes light theme values. Set the theme via `data-ry-theme`:
85
+
86
+ ```html
87
+ <html data-ry-theme="light">
88
+ ```
89
+
90
+ ### Using Dark Theme
91
+
92
+ Load the dark theme CSS alongside the main bundle:
93
+
94
+ ```html
95
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/css/ry-ui.css">
96
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/themes/dark.css">
97
+ ```
98
+
99
+ Then set the theme:
100
+
101
+ ```html
102
+ <html data-ry-theme="dark">
103
+ ```
104
+
105
+ ### Available Themes
106
+
107
+ | Theme | URL |
108
+ |-------|-----|
109
+ | Light | `dist/themes/light.css` |
110
+ | Dark | `dist/themes/dark.css` |
111
+ | Ocean | `dist/themes/ocean.css` |
112
+
113
+ Load whichever themes you need:
114
+
115
+ ```html
116
+ <!-- Load both light and dark for theme switching -->
117
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/css/ry-ui.css">
118
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/themes/light.css">
119
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/themes/dark.css">
120
+ ```
121
+
122
+ ### Theme Toggle Component
123
+
124
+ ```html
125
+ <ry-theme-toggle themes="light,dark"></ry-theme-toggle>
126
+ ```
127
+
128
+ This component:
129
+ - Cycles through specified themes on click
130
+ - Sets `data-ry-theme` on the `<html>` element
131
+ - Emits `ry:theme-change` events
132
+
133
+ ```javascript
134
+ document.addEventListener('ry:theme-change', (e) => {
135
+ console.log('Theme changed to:', e.detail.theme);
136
+ });
137
+ ```
138
+
139
+ ### Switching Themes Programmatically
140
+
141
+ ```javascript
142
+ // Set theme
143
+ document.documentElement.dataset.ryTheme = 'dark';
144
+
145
+ // Get current theme
146
+ const current = document.documentElement.dataset.ryTheme;
147
+ ```
148
+
149
+ ## CSS Loading Options
150
+
151
+ ### Option 1: Full Bundle (Simplest)
152
+
153
+ ```html
154
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/css/ry-ui.css">
155
+ ```
156
+
157
+ Contains tokens + structure + theme. Works out of the box.
158
+
159
+ ### Option 2: Custom Theme (Full Control)
160
+
161
+ Load structure without default theme, then add your own:
162
+
163
+ ```html
164
+ <!-- Required: tokens -->
165
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/css/ry-tokens.css">
166
+ <!-- Required: structure (layout, no colors) -->
167
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/css/ry-structure.css">
168
+ <!-- Your custom theme -->
169
+ <link rel="stylesheet" href="/your-theme.css">
170
+ ```
171
+
172
+ Structure CSS contains only layout properties (display, flex, positioning, sizing). No colors, shadows, or borders. Your theme provides all visual styling.
173
+
174
+ ### Option 3: Override Tokens Only
175
+
176
+ Use the full bundle but override specific tokens:
177
+
178
+ ```html
179
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/css/ry-ui.css">
180
+ <style>
181
+ :root {
182
+ --ry-color-primary: #e11d48;
183
+ --ry-color-primary-hover: #be123c;
184
+ --ry-radius-md: 0;
185
+ --ry-radius-lg: 0;
186
+ }
187
+ </style>
188
+ ```
189
+
190
+ ## Available CSS Files
191
+
192
+ **Main files** (`dist/css/`):
193
+
194
+ | File | Size | Purpose |
195
+ |------|------|---------|
196
+ | `ry-ui.css` | 68KB | Complete bundle (tokens + structure + theme) |
197
+ | `ry-tokens.css` | 6KB | CSS custom properties only |
198
+ | `ry-structure.css` | 51KB | Layout/behavior (no visual styling) |
199
+ | `ry-theme.css` | 47KB | Visual styling (colors, shadows, borders) |
200
+
201
+ **Theme files** (`dist/themes/`):
202
+
203
+ | File | Purpose |
204
+ |------|---------|
205
+ | `light.css` | Light theme overrides (code syntax, etc.) |
206
+ | `dark.css` | Dark theme (dark backgrounds, light text) |
207
+ | `ocean.css` | Ocean theme (blue-tinted, cyan accents) |
208
+
209
+ ## CSS Tokens Reference
210
+
211
+ All styling uses CSS custom properties. Override any of these:
212
+
213
+ ### Colors
214
+ ```css
215
+ --ry-color-primary
216
+ --ry-color-primary-hover
217
+ --ry-color-primary-active
218
+ --ry-color-secondary
219
+ --ry-color-success
220
+ --ry-color-warning
221
+ --ry-color-danger
222
+ --ry-color-info
223
+ --ry-color-text
224
+ --ry-color-text-muted
225
+ --ry-color-text-inverse
226
+ --ry-color-bg
227
+ --ry-color-bg-subtle
228
+ --ry-color-bg-muted
229
+ --ry-color-border
230
+ --ry-color-border-strong
231
+ --ry-color-overlay
232
+ ```
233
+
234
+ ### Typography
235
+ ```css
236
+ --ry-font-sans
237
+ --ry-font-mono
238
+ --ry-text-xs through --ry-text-4xl
239
+ --ry-font-normal (400)
240
+ --ry-font-medium (500)
241
+ --ry-font-semibold (600)
242
+ --ry-font-bold (700)
243
+ ```
244
+
245
+ ### Spacing
246
+ ```css
247
+ --ry-space-1 through --ry-space-20 /* 0.25rem to 5rem */
248
+ ```
249
+
250
+ ### Borders & Shadows
251
+ ```css
252
+ --ry-radius-none through --ry-radius-full
253
+ --ry-shadow-sm, --ry-shadow-md, --ry-shadow-lg, --ry-shadow-xl
254
+ --ry-focus-ring
255
+ ```
256
+
257
+ ### Timing
258
+ ```css
259
+ --ry-duration-fast (100ms)
260
+ --ry-duration-normal (200ms)
261
+ --ry-duration-slow (300ms)
262
+ --ry-ease
263
+ ```
264
+
265
+ ## Component Examples
266
+
267
+ ### Button
268
+ ```html
269
+ <ry-button>Default</ry-button>
270
+ <ry-button variant="primary">Primary</ry-button>
271
+ <ry-button variant="secondary">Secondary</ry-button>
272
+ <ry-button variant="danger">Danger</ry-button>
273
+ <ry-button disabled>Disabled</ry-button>
274
+ ```
275
+
276
+ ### Modal
277
+ ```html
278
+ <ry-button modal="my-modal">Open Modal</ry-button>
279
+
280
+ <ry-modal id="my-modal" title="Modal Title">
281
+ <p>Modal content goes here.</p>
282
+ </ry-modal>
283
+ ```
284
+
285
+ ### Drawer
286
+ ```html
287
+ <ry-button drawer="my-drawer">Open Drawer</ry-button>
288
+
289
+ <ry-drawer id="my-drawer" side="left" title="Menu">
290
+ <nav>Navigation items...</nav>
291
+ </ry-drawer>
292
+ ```
293
+
294
+ ### Tabs
295
+ ```html
296
+ <ry-tabs>
297
+ <ry-tab title="First" active>First tab content</ry-tab>
298
+ <ry-tab title="Second">Second tab content</ry-tab>
299
+ <ry-tab title="Third">Third tab content</ry-tab>
300
+ </ry-tabs>
301
+ ```
302
+
303
+ ### Accordion
304
+ ```html
305
+ <ry-accordion>
306
+ <ry-accordion-item title="Section One" open>
307
+ Content for section one.
308
+ </ry-accordion-item>
309
+ <ry-accordion-item title="Section Two">
310
+ Content for section two.
311
+ </ry-accordion-item>
312
+ </ry-accordion>
313
+ ```
314
+
315
+ ### Select
316
+ ```html
317
+ <ry-select placeholder="Choose country" name="country">
318
+ <ry-option value="us">United States</ry-option>
319
+ <ry-option value="uk">United Kingdom</ry-option>
320
+ <ry-option value="ca">Canada</ry-option>
321
+ </ry-select>
322
+ ```
323
+
324
+ ### Toast (Programmatic)
325
+ ```html
326
+ <script type="module">
327
+ // Global access
328
+ RyToast.success('Saved successfully!');
329
+ RyToast.error('Something went wrong');
330
+ RyToast.info('FYI...');
331
+ RyToast.warning('Be careful');
332
+ </script>
333
+ ```
334
+
335
+ ### Alert
336
+ ```html
337
+ <ry-alert type="info">Information message</ry-alert>
338
+ <ry-alert type="success">Success message</ry-alert>
339
+ <ry-alert type="warning">Warning message</ry-alert>
340
+ <ry-alert type="danger">Error message</ry-alert>
341
+ ```
342
+
343
+ ## Full Example
344
+
345
+ ```html
346
+ <!DOCTYPE html>
347
+ <html lang="en" data-ry-theme="light">
348
+ <head>
349
+ <meta charset="UTF-8">
350
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
351
+ <title>My App</title>
352
+ <!-- Base CSS -->
353
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/css/ry-ui.css">
354
+ <!-- Themes for switching -->
355
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/themes/light.css">
356
+ <link rel="stylesheet" href="https://unpkg.com/@ryanhelsing/ry-ui/dist/themes/dark.css">
357
+ </head>
358
+ <body style="background: var(--ry-color-bg); color: var(--ry-color-text);">
359
+
360
+ <ry-page>
361
+ <ry-header>
362
+ <strong>My App</strong>
363
+ <ry-theme-toggle themes="light,dark"></ry-theme-toggle>
364
+ </ry-header>
365
+
366
+ <ry-main>
367
+ <ry-section>
368
+ <h1>Welcome</h1>
369
+ <ry-button variant="primary" modal="demo">Open Modal</ry-button>
370
+ </ry-section>
371
+ </ry-main>
372
+
373
+ <ry-modal id="demo" title="Hello">
374
+ <p>This is a modal dialog.</p>
375
+ </ry-modal>
376
+ </ry-page>
377
+
378
+ <script type="module" src="https://unpkg.com/@ryanhelsing/ry-ui/dist/ry-ui.js"></script>
379
+ </body>
380
+ </html>
381
+ ```
382
+
383
+ ## Browser Support
384
+
385
+ ry-ui targets ES2022 and modern browsers:
386
+ - Chrome/Edge 94+
387
+ - Firefox 93+
388
+ - Safari 15.4+
389
+
390
+ No IE11 support. No polyfills included.
package/dist/components/ry-example.d.ts CHANGED
@@ -13,6 +13,13 @@
13
13
  * </accordion-item>
14
14
  * </accordion>
15
15
  * </template>
16
+ * <!-- Optional: JS usage examples in collapsible section -->
17
+ * <script slot="js">
18
+ * // Listen for changes
19
+ * element.addEventListener('ry:change', (e) => {
20
+ * console.log(e.detail.value);
21
+ * });
22
+ * </script>
16
23
  * </ry-example>
17
24
  */
18
25
  import { RyElement } from '../core/ry-element.js';
package/dist/components/ry-example.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ry-example.d.ts","sourceRoot":"","sources":["../../src/ts/components/ry-example.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,qBAAa,SAAU,SAAQ,SAAS;;IACtC,KAAK,IAAI,IAAI;CA8Dd"}
1
+ {"version":3,"file":"ry-example.d.ts","sourceRoot":"","sources":["../../src/ts/components/ry-example.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,qBAAa,SAAU,SAAQ,SAAS;;IACtC,KAAK,IAAI,IAAI;CA0Gd"}
package/dist/css/ry-structure.css CHANGED
@@ -1363,6 +1363,36 @@ ry-example[data-stacked] {
1363
1363
  grid-template-columns: 1fr;
1364
1364
  }
1365
1365
 
1366
+ .ry-example__usage {
1367
+ grid-column: 1 / -1;
1368
+ margin-top: var(--ry-space-2, 0.5rem);
1369
+ }
1370
+
1371
+ .ry-example__usage-toggle {
1372
+ display: flex;
1373
+ align-items: center;
1374
+ gap: var(--ry-space-2, 0.5rem);
1375
+ padding: var(--ry-space-2, 0.5rem) var(--ry-space-3, 0.75rem);
1376
+ width: 100%;
1377
+ cursor: pointer;
1378
+ }
1379
+
1380
+ .ry-example__usage-toggle ry-icon {
1381
+ transition: transform var(--ry-duration-fast, 150ms) ease;
1382
+ }
1383
+
1384
+ .ry-example__usage-toggle[aria-expanded="true"] ry-icon {
1385
+ transform: rotate(180deg);
1386
+ }
1387
+
1388
+ .ry-example__usage-panel {
1389
+ margin-top: var(--ry-space-2, 0.5rem);
1390
+ }
1391
+
1392
+ .ry-example__usage-panel[hidden] {
1393
+ display: none;
1394
+ }
1395
+
1366
1396
  /* ═══════════════════════════════════════════════════════════════
1367
1397
  ICON
1368
1398
  ═══════════════════════════════════════════════════════════════ */
package/dist/css/ry-theme.css CHANGED
@@ -1050,6 +1050,20 @@ ry-code {
1050
1050
  border-radius: var(--ry-radius-lg);
1051
1051
  }
1052
1052
 
1053
+ .ry-example__usage-toggle {
1054
+ background-color: var(--ry-color-bg-subtle);
1055
+ border: var(--ry-border-width) solid var(--ry-color-border);
1056
+ border-radius: var(--ry-radius-md);
1057
+ color: var(--ry-color-text-muted);
1058
+ font-size: var(--ry-text-sm);
1059
+ font-weight: 500;
1060
+ }
1061
+
1062
+ .ry-example__usage-toggle:hover {
1063
+ background-color: var(--ry-color-bg-hover);
1064
+ color: var(--ry-color-text);
1065
+ }
1066
+
1053
1067
  /* ═══════════════════════════════════════════════════════════════
1054
1068
  ICON
1055
1069
  ═══════════════════════════════════════════════════════════════ */
package/dist/css/ry-ui.css CHANGED
@@ -619,6 +619,12 @@ ry-example [data-ry-target="code"] { min-width: 0; }
619
619
  ry-example [data-ry-target="preview"] { min-width: 0; padding: var(--ry-space-4); }
620
620
  @media (max-width: 768px) { ry-example { grid-template-columns: 1fr; } }
621
621
  ry-example[data-stacked] { grid-template-columns: 1fr; }
622
+ .ry-example__usage { grid-column: 1 / -1; margin-top: var(--ry-space-2); }
623
+ .ry-example__usage-toggle { display: flex; align-items: center; gap: var(--ry-space-2); padding: var(--ry-space-2) var(--ry-space-3); width: 100%; cursor: pointer; }
624
+ .ry-example__usage-toggle ry-icon { transition: transform var(--ry-duration-fast) ease; }
625
+ .ry-example__usage-toggle[aria-expanded="true"] ry-icon { transform: rotate(180deg); }
626
+ .ry-example__usage-panel { margin-top: var(--ry-space-2); }
627
+ .ry-example__usage-panel[hidden] { display: none; }
622
628
 
623
629
  /* Icon */
624
630
  ry-icon { display: inline-flex; align-items: center; justify-content: center; vertical-align: middle; flex-shrink: 0; }
@@ -1124,6 +1130,8 @@ ry-code { background-color: var(--ry-code-bg, #f6f8fa); border-radius: var(--ry-
1124
1130
 
1125
1131
  /* Example */
1126
1132
  .ry-example__preview { background-color: var(--ry-color-bg-subtle); border: var(--ry-border-width) solid var(--ry-color-border); border-radius: var(--ry-radius-lg); }
1133
+ .ry-example__usage-toggle { background-color: var(--ry-color-bg-subtle); border: var(--ry-border-width) solid var(--ry-color-border); border-radius: var(--ry-radius-md); color: var(--ry-color-text-muted); font-size: var(--ry-text-sm); font-weight: 500; }
1134
+ .ry-example__usage-toggle:hover { background-color: var(--ry-color-bg-hover); color: var(--ry-color-text); }
1127
1135
 
1128
1136
  /* Icon */
1129
1137
  ry-icon { color: currentColor; }