@auriel/peppertino 0.3.0 → 0.5.0

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 (68) hide show
  1. package/CHANGELOG.txt +210 -122
  2. package/MIGRATION.md +52 -0
  3. package/README.md +284 -40
  4. package/dist/accordion.js +88 -0
  5. package/dist/accordion.js.map +7 -0
  6. package/dist/alert.js +26 -0
  7. package/dist/alert.js.map +7 -0
  8. package/dist/carousel.js +4 -0
  9. package/dist/carousel.js.map +2 -2
  10. package/dist/header.js +1 -0
  11. package/dist/header.js.map +2 -2
  12. package/dist/main.css +3607 -299
  13. package/dist/main.css.map +1 -1
  14. package/dist/modal.js +2 -0
  15. package/dist/modal.js.map +2 -2
  16. package/dist/peppertino.js +290 -11
  17. package/dist/peppertino.js.map +3 -3
  18. package/dist/select.js +2 -4
  19. package/dist/select.js.map +2 -2
  20. package/dist/switch.js +29 -0
  21. package/dist/switch.js.map +7 -0
  22. package/dist/tabs.js +27 -7
  23. package/dist/tabs.js.map +2 -2
  24. package/dist/theme.js +47 -0
  25. package/dist/theme.js.map +7 -0
  26. package/dist/toast.js +69 -0
  27. package/dist/toast.js.map +7 -0
  28. package/index.html +813 -48
  29. package/package.json +6 -4
  30. package/scripts/hex-to-hsl.mjs +75 -0
  31. package/scripts/lint-bem.mjs +53 -0
  32. package/scripts/lint-colors.mjs +87 -0
  33. package/src/js/accordion.js +103 -0
  34. package/src/js/alert.js +28 -0
  35. package/src/js/carousel.js +5 -0
  36. package/src/js/header.js +1 -0
  37. package/src/js/modal.js +4 -0
  38. package/src/js/peppertino.js +6 -0
  39. package/src/js/select.js +2 -4
  40. package/src/js/switch.js +28 -0
  41. package/src/js/tabs.js +31 -21
  42. package/src/js/theme.js +47 -0
  43. package/src/js/toast.js +79 -0
  44. package/src/scss/accordion.scss +156 -0
  45. package/src/scss/alert.scss +203 -0
  46. package/src/scss/badge.scss +90 -0
  47. package/src/scss/base.scss +331 -36
  48. package/src/scss/button.scss +44 -46
  49. package/src/scss/card.scss +4 -4
  50. package/src/scss/carousel.scss +18 -28
  51. package/src/scss/dark-mode.scss +514 -0
  52. package/src/scss/footer.scss +14 -14
  53. package/src/scss/forms/fieldset.scss +12 -12
  54. package/src/scss/forms/form-instructions.scss +8 -8
  55. package/src/scss/forms/text-field.scss +17 -17
  56. package/src/scss/forms/validation.scss +12 -12
  57. package/src/scss/gradient.scss +2 -2
  58. package/src/scss/header.scss +8 -8
  59. package/src/scss/main.scss +8 -0
  60. package/src/scss/modal.scss +2 -2
  61. package/src/scss/section.scss +1 -1
  62. package/src/scss/select.scss +8 -8
  63. package/src/scss/switch.scss +121 -0
  64. package/src/scss/table.scss +5 -5
  65. package/src/scss/tabs.scss +26 -26
  66. package/src/scss/toast.scss +170 -0
  67. package/src/scss/tooltip.scss +126 -0
  68. package/src/scss/utilities.scss +243 -0
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # PeppertinoCSS — An Apple-inspired CSS framework with a little spice.
1
+ # PeppertinoCSS — An Apple-inspired CSS framework with a little spice.
2
2
 
3
3
  PeppertinoCSS is an Apple-inspired CSS framework built with SCSS, featuring the clean geometry and restrained elegance of Cupertino design — but with a spicy red accent instead of blue, because we're not Apple and we're not pretending to be.
4
4
 
@@ -7,7 +7,7 @@ PeppertinoCSS is an Apple-inspired CSS framework built with SCSS, featuring the
7
7
  ## Getting started
8
8
 
9
9
  ```bash
10
- npm install @auriel/peppertino
10
+ bun add @auriel/peppertino
11
11
  ```
12
12
 
13
13
  CDN — stylesheet only:
@@ -34,8 +34,8 @@ Clone and build locally:
34
34
  ```bash
35
35
  git clone https://codeberg.org/debaditya/Peppertino
36
36
  cd Peppertino
37
- npm install
38
- npm run dev
37
+ bun install
38
+ bun run dev
39
39
  ```
40
40
 
41
41
  Then open `http://localhost:3000` in your browser.
@@ -46,14 +46,16 @@ Then open `http://localhost:3000` in your browser.
46
46
 
47
47
  | Command | Description |
48
48
  |---|---|
49
- | `npm run build` | Compile SCSS + JS to `dist/` |
50
- | `npm run build:css` | SCSS only, expanded with sourcemap |
51
- | `npm run build:css:min` | SCSS minified, no sourcemap |
52
- | `npm run build:js` | Bundle all `src/js/` components via esbuild |
53
- | `npm run watch:css` | Watch and recompile SCSS on save |
54
- | `npm run watch:js` | Watch and rebundle JS on save |
55
- | `npm run serve` | Serve project on `http://localhost:3000` |
56
- | `npm run dev` | Build + watch CSS/JS + serve, all in parallel |
49
+ | `bun run build` | Compile SCSS + JS to `dist/`, then run both linters |
50
+ | `bun run build:css` | SCSS only, expanded with sourcemap |
51
+ | `bun run build:css:min` | SCSS minified, no sourcemap |
52
+ | `bun run build:js` | Bundle all `src/js/` components via esbuild |
53
+ | `bun run lint:colors` | Fail if any component SCSS uses literal hex/SCSS color vars |
54
+ | `bun run lint:bem` | Fail if any `.pp-*` class in `dist/main.css` violates BEM |
55
+ | `bun run watch:css` | Watch and recompile SCSS on save |
56
+ | `bun run watch:js` | Watch and rebundle JS on save |
57
+ | `bun run serve` | Serve project on `http://localhost:3000` |
58
+ | `bun run dev` | Build + watch CSS/JS + serve, all in parallel |
57
59
 
58
60
  ---
59
61
 
@@ -87,6 +89,7 @@ cp -r agents/peppertino ~/.claude/skills/peppertino
87
89
  |---|---|
88
90
  | `skill.md` | Index, ARIA/WCAG requirements, conventions |
89
91
  | `base.md` | Design tokens, spacing, breakpoints, mixins |
92
+ | `badge.md` | Badge variants, sizes, dot indicator |
90
93
  | `button.md` | All button variants |
91
94
  | `card.md` | Card parts, variants, grid |
92
95
  | `carousel.md` | Carousel markup, API, keyboard |
@@ -101,8 +104,11 @@ cp -r agents/peppertino ~/.claude/skills/peppertino
101
104
  | `modal.md` | Modal, actions, `ppModal` API |
102
105
  | `section.md` | Section variants, scrollbar |
103
106
  | `select.md` | Native select, custom dropdown |
107
+ | `switch.md` | Toggle switch, sizes, `ppSwitch` events |
104
108
  | `table.md` | Table, column helpers |
105
109
  | `tabs.md` | Tabs, variants, keyboard nav |
110
+ | `toast.md` | Toast positions, variants, `ppToast` API |
111
+ | `tooltip.md` | Tooltip placements, CSS-only usage |
106
112
  | `typography.md` | All typography utility classes |
107
113
 
108
114
  The skill's `skill.md` enforces ARIA and WCAG AA compliance rules and instructs the agent to fetch authoritative specs from w3.org when uncertain.
@@ -116,10 +122,14 @@ The skill's `skill.md` enforces ARIA and WCAG AA compliance rules and instructs
116
122
  | File | Purpose |
117
123
  |---|---|
118
124
  | `reset.scss` | Opinionated modern reset |
119
- | `base.scss` | Design tokens, helper functions, base element styles |
120
- | `button.scss` | `.button`, `.button-outline`, semantic variants |
125
+ | `base.scss` | Design tokens, CSS custom properties, helper functions, base element styles |
126
+ | `accordion.scss` | `.pp-accordion` — collapsible panels; variants: `--flush`, `--dark`, `--primary` |
127
+ | `alert.scss` | `.pp-alert` — inline feedback; variants: `--info/success/warning/error/primary/neutral`, `--filled` |
128
+ | `badge.scss` | `.pp-badge` — pill badges; variants: `--primary/success/warning/error/info`, `--filled`, sizes `--sm/lg`, `--dot` |
129
+ | `button.scss` | `.pp-button`, `.pp-button--outline`, semantic variants |
121
130
  | `card.scss` | `.pp-card` and variants |
122
131
  | `carousel.scss` | `.pp-carousel` — CSS scroll-snap carousel |
132
+ | `dark-mode.scss` | `.dark` overrides for all `--pp-*` tokens — applied last |
123
133
  | `footer.scss` | `.pp-footer` — multi-column footer |
124
134
  | `forms.scss` | Aggregator for all form partials |
125
135
  | `forms/fieldset.scss` | `.pp-fieldset` + `.pp-legend` |
@@ -127,26 +137,37 @@ The skill's `skill.md` enforces ARIA and WCAG AA compliance rules and instructs
127
137
  | `forms/label.scss` | `.pp-label` — Apple HIG four-tier label system |
128
138
  | `forms/text-field.scss` | `.pp-field` — labelled input/textarea with validation states |
129
139
  | `forms/validation.scss` | `.pp-validation-summary`, `.pp-confirm`, `.pp-field--validate` |
130
- | `gradient.scss` | `.gradient-txt` |
140
+ | `gradient.scss` | `.pp-gradient-text` |
131
141
  | `header.scss` | `.pp-header` — glassmorphism sticky header |
132
142
  | `modal.scss` | `.pp-modal-backdrop` + `.pp-modal` — glassmorphic modals |
133
143
  | `section.scss` | `.pp-section` — full-viewport sections + custom scrollbar |
134
144
  | `select.scss` | Native `<select>` restyling + `.pp-select` custom dropdown |
145
+ | `switch.scss` | `.pp-switch` — iOS-style toggle; sizes `--sm/lg` |
135
146
  | `table.scss` | `.pp-table` — clean Apple-style data tables |
136
147
  | `tabs.scss` | `.pp-tabs` — pill-style tabs with icon + label |
148
+ | `toast.scss` | `.pp-toast-container` + `.pp-toast` — auto-dismiss notifications |
149
+ | `tooltip.scss` | `.pp-tooltip` — CSS-only tooltip; placements `--top/bottom/left/right` |
137
150
  | `typography.scss` | Utility classes for font, size, weight, spacing |
151
+ | `utilities.scss` | Single-purpose layout/spacing/display/visibility classes |
138
152
 
139
153
  ### JS components (`src/js/`)
140
154
 
155
+ Each file is a self-contained IIFE. Import only what you need, or include `peppertino.js` for everything.
156
+
141
157
  | File | Purpose |
142
158
  |---|---|
159
+ | `accordion.js` | `aria-expanded`/`aria-hidden`, keyboard nav (↑ ↓ Home End), `data-allow-multiple`; `ppAccordion.get(ref)` API |
160
+ | `alert.js` | `data-alert-dismiss` wiring; `window.ppAlert.dismiss(idOrEl)` |
143
161
  | `carousel.js` | ARIA wiring, IntersectionObserver sync, `ppCarousel` API |
144
162
  | `header.js` | Mobile drawer, dropdown ARIA wiring for `.pp-header` |
145
163
  | `modal.js` | Open/close, focus trap, focus restore, ARIA for `.pp-modal` |
146
164
  | `select.js` | Keyboard nav, ARIA listbox/option for `.pp-select` |
147
- | `tabs.js` | Click + arrow key activation, ARIA tablist for `.pp-tabs` |
165
+ | `switch.js` | `aria-checked` toggle, Space key, `pp:switch:change` event |
166
+ | `tabs.js` | Click + arrow key activation, ARIA tablist; `ppTabs.get(ref).activate(index)` |
167
+ | `theme.js` | `window.ppTheme.set/get/toggle`; persists to `localStorage`; `data-theme-toggle` wiring |
168
+ | `toast.js` | `window.ppToast.show({ message, title, variant, duration, position })`; auto-dismiss |
148
169
  | `validation.js` | `aria-invalid` wiring, summary focus, `ppValidation` API |
149
- | `peppertino.js` | Single-file bundle of all the above |
170
+ | `peppertino.js` | Aggregator — imports all of the above |
150
171
 
151
172
  All JS follows progressive enhancement — CSS provides the full visual baseline without JS. JS adds keyboard navigation, focus management, and ARIA state.
152
173
 
@@ -154,17 +175,25 @@ All JS follows progressive enhancement — CSS provides the full visual baseline
154
175
 
155
176
  ## Design tokens (`base.scss`)
156
177
 
157
- ### Colors
178
+ ### Colors — HSL channel system
158
179
 
159
- ```scss
160
- $color-primary: #e90111 // spicy red
161
- $color-primary-light: #ff4d5a
162
- $color-primary-dark: #a8000c
180
+ All color tokens are decomposed into H/S/L channel properties so any component can form alpha tints without `rgba()`:
181
+
182
+ ```css
183
+ /* Each token ships three channel vars + a composite shorthand */
184
+ --pp-primary-h: 356;
185
+ --pp-primary-s: 99.2%;
186
+ --pp-primary-l: 46.3%;
187
+ --pp-primary: hsl(var(--pp-primary-h) var(--pp-primary-s) var(--pp-primary-l));
163
188
 
164
- $gradient-start: #ffcf67
165
- $gradient-end: #ea5753
189
+ /* Alpha tints use the channels directly — no SCSS needed */
190
+ background: hsl(var(--pp-primary-h) var(--pp-primary-s) var(--pp-primary-l) / 0.15);
166
191
  ```
167
192
 
193
+ Available token families: `--pp-primary`, `--pp-gradient-start`, `--pp-gradient-end`, neutral scale (`--pp-neutral-50` → `--pp-neutral-900`), semantic scales `--pp-success-*`, `--pp-warning-*`, `--pp-error-*`, `--pp-info-*` (each with 50/100/200/300/400/500/600/700/800/900 levels).
194
+
195
+ Dark mode overrides channel properties (`-l`, `-s`) rather than full hex values — single-token changes cascade everywhere.
196
+
168
197
  ### Typography
169
198
 
170
199
  ```scss
@@ -222,22 +251,96 @@ Apple device breakpoints: `iphone-se` · `iphone` · `iphone-plus` · `iphone-pr
222
251
 
223
252
  ## Components
224
253
 
225
- ### Button
254
+ ### Accordion
255
+
256
+ ```html
257
+ <div class="pp-accordion" data-allow-multiple>
258
+ <div class="pp-accordion__item">
259
+ <button class="pp-accordion__trigger" aria-expanded="false" aria-controls="acc-1">
260
+ Question
261
+ <svg class="pp-accordion__icon" viewBox="0 0 24 24" aria-hidden="true"><polyline points="6 9 12 15 18 9"/></svg>
262
+ </button>
263
+ <div class="pp-accordion__panel" id="acc-1" aria-hidden="true">
264
+ <p class="pp-accordion__content">Answer text.</p>
265
+ </div>
266
+ </div>
267
+ </div>
268
+ <script src="dist/accordion.js" defer></script>
269
+ ```
270
+
271
+ Variants: `--flush` · `--dark` · `--primary`
272
+ Attribute: `data-allow-multiple` — allow multiple panels open at once
273
+ Keyboard: `↑` / `↓` arrows, `Home`, `End`
274
+
275
+ ### Alert
276
+
277
+ ```html
278
+ <div class="pp-alert pp-alert--info" role="note">
279
+ <span class="pp-alert__icon"><i data-lucide="info" aria-hidden="true"></i></span>
280
+ <div class="pp-alert__body">
281
+ <p class="pp-alert__title">Heads up</p>
282
+ <p class="pp-alert__message">Your session expires in 10 minutes.</p>
283
+ </div>
284
+ </div>
285
+
286
+ <!-- Dismissible -->
287
+ <div class="pp-alert pp-alert--success is-dismissible" role="status" id="a1">
288
+ <span class="pp-alert__icon"><i data-lucide="circle-check" aria-hidden="true"></i></span>
289
+ <div class="pp-alert__body"><p class="pp-alert__message">Saved.</p></div>
290
+ <button class="pp-alert__dismiss" aria-label="Dismiss"
291
+ onclick="const e=document.getElementById('a1');e.classList.add('is-dismissing');setTimeout(()=>e.remove(),200);">
292
+ <i data-lucide="x" aria-hidden="true"></i>
293
+ </button>
294
+ </div>
295
+ ```
296
+
297
+ Variants: `--info` · `--success` · `--warning` · `--error` · `--primary` · `--neutral`
298
+ Modifier: `--filled` (solid background instead of tint)
299
+ States: `.is-dismissible` · `.is-dismissing` (slide-out before removal)
300
+
301
+ JS API: `window.ppAlert.dismiss(idOrEl)` — accepts an element or its `id` string.
302
+ Event: `pp:alert:dismiss` dispatched on the alert element before removal.
303
+
304
+ ### Badge
226
305
 
227
306
  ```html
228
- <button class="button">Primary</button>
229
- <button class="button-success">Success</button>
230
- <button class="button-warning">Warning</button>
231
- <button class="button-error">Error</button>
232
- <button class="button-dark">Dark</button>
233
- <button class="button-gradient">Gradient</button>
234
- <button class="button-ghost">Ghost</button>
307
+ <!-- Tint variants (default) -->
308
+ <span class="pp-badge pp-badge--info">New</span>
309
+ <span class="pp-badge pp-badge--success">Active</span>
310
+ <span class="pp-badge pp-badge--warning">Review</span>
311
+ <span class="pp-badge pp-badge--error">Error</span>
312
+ <span class="pp-badge pp-badge--primary">Beta</span>
313
+
314
+ <!-- Filled (solid background) -->
315
+ <span class="pp-badge pp-badge--success pp-badge--filled">Active</span>
316
+
317
+ <!-- Sizes -->
318
+ <span class="pp-badge pp-badge--info pp-badge--sm">Small</span>
319
+ <span class="pp-badge pp-badge--info pp-badge--lg">Large</span>
320
+
321
+ <!-- Dot indicator (no text — pair with sr-only label) -->
322
+ <span class="pp-badge pp-badge--error pp-badge--dot" aria-label="3 unread"></span>
323
+ ```
324
+
325
+ Variants: `--primary` · `--success` · `--warning` · `--error` · `--info`
326
+ Modifiers: `--filled` · `--sm` · `--lg` · `--dot`
327
+
328
+ ### Button
235
329
 
236
- <button class="button-outline">Primary</button>
237
- <button class="button-outline-success">Success</button>
238
- <button class="button-outline-warning">Warning</button>
239
- <button class="button-outline-error">Error</button>
240
- <button class="button-outline-dark">Dark</button>
330
+ ```html
331
+ <button class="pp-button">Primary</button>
332
+ <button class="pp-button--success">Success</button>
333
+ <button class="pp-button--warning">Warning</button>
334
+ <button class="pp-button--error">Error</button>
335
+ <button class="pp-button--dark">Dark</button>
336
+ <button class="pp-button--gradient">Gradient</button>
337
+ <button class="pp-button--ghost">Ghost</button>
338
+
339
+ <button class="pp-button--outline">Primary</button>
340
+ <button class="pp-button--outline pp-button--success">Success</button>
341
+ <button class="pp-button--outline pp-button--warning">Warning</button>
342
+ <button class="pp-button--outline pp-button--error">Error</button>
343
+ <button class="pp-button--outline pp-button--dark">Dark</button>
241
344
  ```
242
345
 
243
346
  ### Card
@@ -376,7 +479,7 @@ Sizes: `--sm` · `--lg`
376
479
  <input class="pp-confirm__input" type="checkbox" />
377
480
  <span class="pp-confirm__label">I confirm this action.</span>
378
481
  </label>
379
- <button class="button pp-submit--gated" type="submit">Submit</button>
482
+ <button class="pp-button pp-submit--gated" type="submit">Submit</button>
380
483
  ```
381
484
 
382
485
  JS API (optional — CSS works without it):
@@ -392,7 +495,7 @@ ppValidation.setSummary([{ input, message }], summaryEl)
392
495
  ### Gradient text
393
496
 
394
497
  ```html
395
- <h1 class="gradient-txt">PeppertinoCSS</h1>
498
+ <h1 class="pp-gradient-text">PeppertinoCSS</h1>
396
499
  ```
397
500
 
398
501
  ### Header
@@ -463,6 +566,24 @@ ppValidation.setSummary([{ input, message }], summaryEl)
463
566
 
464
567
  Sizes: `.pp-select--sm` · `.pp-select--lg`
465
568
 
569
+ ### Switch
570
+
571
+ ```html
572
+ <!-- Basic toggle -->
573
+ <button class="pp-switch" role="switch" aria-checked="false" aria-label="Enable notifications"></button>
574
+
575
+ <!-- Pre-checked -->
576
+ <button class="pp-switch" role="switch" aria-checked="true" aria-label="Dark mode"></button>
577
+
578
+ <!-- Sizes -->
579
+ <button class="pp-switch pp-switch--sm" role="switch" aria-checked="false" aria-label="Compact mode"></button>
580
+ <button class="pp-switch pp-switch--lg" role="switch" aria-checked="false" aria-label="Accessibility features"></button>
581
+ ```
582
+
583
+ Sizes: `--sm` (32×20px) · default (44×26px) · `--lg` (56×32px)
584
+ JS handles `aria-checked` toggle on click and Space key.
585
+ Event: `pp:switch:change` with `{ checked: boolean }` on the switch element.
586
+
466
587
  ### Tabs
467
588
 
468
589
  ```html
@@ -477,7 +598,9 @@ Sizes: `.pp-select--sm` · `.pp-select--lg`
477
598
 
478
599
  Variants: default · `--outline` · `--gradient` · `--gradient-outline`
479
600
  Sizes: `--sm` · `--lg`
480
- Keyboard: `←` / `→` arrows, `Home`, `End`
601
+ Keyboard: `←` / `→` arrows, `Home`, `End`
602
+ JS API: `ppTabs.get(ref).activate(index)` — programmatically activate a tab by index.
603
+ Event: `pp:tabs:change` with `{ index }` on the `.pp-tabs` element.
481
604
 
482
605
  ### Table
483
606
 
@@ -491,6 +614,47 @@ Keyboard: `←` / `→` arrows, `Home`, `End`
491
614
 
492
615
  Column helpers: `.pp-table--cols-1` → `.pp-table--cols-4`
493
616
 
617
+ ### Toast
618
+
619
+ ```js
620
+ // Show a toast (JS required)
621
+ ppToast.show({ message: 'File saved.', variant: 'success' });
622
+ ppToast.show({ message: 'Sync failed.', title: 'Error', variant: 'error', duration: 6000 });
623
+ ppToast.show({ message: 'Update available.', variant: 'info', position: 'bottom-center' });
624
+ ```
625
+
626
+ ```html
627
+ <!-- Dismiss button with data attribute (no JS needed) -->
628
+ <button data-toast-dismiss aria-label="Dismiss">✕</button>
629
+ ```
630
+
631
+ Variants: `--info` · `--success` · `--warning` · `--error` · `--neutral`
632
+ Positions: `top-right` (default) · `top-left` · `top-center` · `bottom-right` · `bottom-left` · `bottom-center`
633
+ Options: `message` · `title` · `variant` · `duration` (ms, default 4000) · `position`
634
+ Events: `pp:toast:show` / `pp:toast:dismiss` on the toast element.
635
+
636
+ ### Tooltip
637
+
638
+ ```html
639
+ <!-- CSS-only: shows on hover and :focus-within -->
640
+ <span class="pp-tooltip">
641
+ Hover me
642
+ <span class="pp-tooltip__content" role="tooltip">Helpful hint</span>
643
+ </span>
644
+
645
+ <!-- Force-show via attribute (e.g. for testing) -->
646
+ <span class="pp-tooltip">
647
+ Click me
648
+ <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip" data-show>
649
+ Shown below
650
+ </span>
651
+ </span>
652
+ ```
653
+
654
+ Placements: default (top) · `--bottom` · `--left` · `--right`
655
+ Shown automatically on `:hover` and `:focus-within` — no JS required.
656
+ Add `data-show` to force-display for testing.
657
+
494
658
  ### Section
495
659
 
496
660
  ```html
@@ -505,6 +669,86 @@ Variants: `--primary` · `--dark` · `--muted` · `--gradient`
505
669
 
506
670
  ---
507
671
 
672
+ ## Utilities
673
+
674
+ Single-purpose classes — no JavaScript required. Import `utilities.scss` or use the compiled CSS.
675
+
676
+ | Group | Classes |
677
+ |---|---|
678
+ | Display | `.d-{block\|inline\|inline-block\|flex\|inline-flex\|grid\|inline-grid\|none\|contents}` |
679
+ | Visibility | `.visible` `.invisible` `.sr-only` `.not-sr-only` |
680
+ | Opacity | `.opacity-{0\|25\|50\|75\|100}` |
681
+ | Margin | `.m-*` `.mt-*` `.mb-*` `.ml-*` `.mr-*` `.mx-*` `.my-*` (keys 0–32, `auto`) |
682
+ | Padding | `.p-*` `.pt-*` `.pb-*` `.pl-*` `.pr-*` `.px-*` `.py-*` (keys 0–32) |
683
+ | Gap | `.gap-*` `.gap-x-*` `.gap-y-*` (keys 0–32) |
684
+ | Flex | direction, wrap, grow/shrink, justify-content, align-items, align-self |
685
+ | Grid | `.grid-cols-{1–6,12}` `.grid-rows-{1–4}` `.col-span-*` `.row-span-*` |
686
+ | Width | `.w-full` `.w-screen` `.w-auto` `.w-fit` `.w-min` `.w-max` `.w-half` |
687
+ | Height | `.h-full` `.h-screen` `.h-auto` `.h-fit` |
688
+ | Overflow | `.overflow-{auto\|hidden\|visible\|scroll}`, x/y variants |
689
+ | Position | `.static` `.relative` `.absolute` `.fixed` `.sticky` |
690
+ | Z-index | `.z-{below\|base\|raised\|overlay\|modal\|toast\|tooltip}` |
691
+ | Border-radius | `.rounded-{none\|sm\|base\|md\|lg\|xl\|2xl\|full}` |
692
+ | Shadow | `.shadow-{none\|sm\|md\|lg\|xl}` |
693
+ | Cursor | `.cursor-{default\|pointer\|not-allowed\|grab\|text}` |
694
+ | Responsive | `.sm-d-*` `.md-d-*` `.lg-d-*` `.xl-d-*` `.w2xl-d-*` (display only) |
695
+
696
+ ---
697
+
698
+ ## Dark mode
699
+
700
+ Add `class="dark"` to `<html>` (or any ancestor element). All component tokens flip automatically via CSS custom properties — no extra classes needed on individual components.
701
+
702
+ ```html
703
+ <html class="dark">
704
+ <!-- everything inside uses dark surface tokens -->
705
+ </html>
706
+ ```
707
+
708
+ Toggle from JS using the `ppTheme` API (requires `theme.js`):
709
+
710
+ ```js
711
+ ppTheme.set('dark'); // switch to dark mode
712
+ ppTheme.set('light'); // switch to light mode
713
+ ppTheme.toggle(); // flip current mode
714
+ ppTheme.get(); // → 'dark' | 'light'
715
+ ```
716
+
717
+ Or add `data-theme-toggle` to any button — it wires automatically:
718
+
719
+ ```html
720
+ <button data-theme-toggle aria-label="Toggle dark mode">Dark</button>
721
+ ```
722
+
723
+ The preference is persisted to `localStorage` under `pp-theme` and restored on page load. Event: `pp:theme:change` with `{ theme: 'dark' | 'light' }` dispatched on `document`.
724
+
725
+ All `--pp-*` tokens are defined on `:root` as light defaults. `dark-mode.scss` overrides them under `.dark`. The neutral scale is fully inverted (50 ↔ 900), surfaces swap, and glass/shadow values are strengthened for dark backgrounds.
726
+
727
+ ---
728
+
729
+ ## CustomEvents reference
730
+
731
+ All JS components dispatch `pp:<component>:<event>` CustomEvents that bubble. Listen at any ancestor:
732
+
733
+ | Event | Dispatched on | Detail |
734
+ |---|---|---|
735
+ | `pp:accordion:open` | `.pp-accordion` | `{ index, trigger, panel }` |
736
+ | `pp:accordion:close` | `.pp-accordion` | `{ index, trigger, panel }` |
737
+ | `pp:alert:dismiss` | `.pp-alert` | — |
738
+ | `pp:carousel:change` | `.pp-carousel` | `{ index, total, label }` |
739
+ | `pp:header:open` | `.pp-header` | — |
740
+ | `pp:header:close` | `.pp-header` | — |
741
+ | `pp:modal:open` | `.pp-modal-backdrop` | — |
742
+ | `pp:modal:close` | `.pp-modal-backdrop` | — |
743
+ | `pp:select:change` | `.pp-select` | `{ value }` |
744
+ | `pp:switch:change` | `.pp-switch` | `{ checked: boolean }` |
745
+ | `pp:tabs:change` | `.pp-tabs` | `{ index }` |
746
+ | `pp:theme:change` | `document` | `{ theme: 'dark' \| 'light' }` |
747
+ | `pp:toast:show` | `.pp-toast` | — |
748
+ | `pp:toast:dismiss` | `.pp-toast` | — |
749
+
750
+ ---
751
+
508
752
  ## Changelog
509
753
 
510
754
  See [CHANGELOG.txt](CHANGELOG.txt)
@@ -0,0 +1,88 @@
1
+ (() => {
2
+ (function() {
3
+ const registry = {};
4
+ document.querySelectorAll(".pp-accordion").forEach((accordion, accordionIdx) => {
5
+ const allowMultiple = accordion.hasAttribute("data-allow-multiple");
6
+ const id = accordion.id || `pp-accordion-${accordionIdx}`;
7
+ if (!accordion.id) accordion.id = id;
8
+ const triggers = [...accordion.querySelectorAll(".pp-accordion__trigger")];
9
+ triggers.forEach((trigger, i) => {
10
+ const panelId = trigger.getAttribute("aria-controls");
11
+ const panel = panelId ? document.getElementById(panelId) : trigger.nextElementSibling;
12
+ if (!panel) return;
13
+ const isOpen = trigger.getAttribute("aria-expanded") === "true";
14
+ panel.setAttribute("aria-hidden", isOpen ? "false" : "true");
15
+ if (isOpen) panel.classList.add("is-open");
16
+ trigger.addEventListener("click", () => {
17
+ const expanded = trigger.getAttribute("aria-expanded") === "true";
18
+ if (!allowMultiple) {
19
+ triggers.forEach((t) => {
20
+ if (t === trigger) return;
21
+ t.setAttribute("aria-expanded", "false");
22
+ const p = t.getAttribute("aria-controls") ? document.getElementById(t.getAttribute("aria-controls")) : t.nextElementSibling;
23
+ if (p) {
24
+ p.setAttribute("aria-hidden", "true");
25
+ p.classList.remove("is-open");
26
+ }
27
+ });
28
+ }
29
+ const next = !expanded;
30
+ trigger.setAttribute("aria-expanded", String(next));
31
+ panel.setAttribute("aria-hidden", String(!next));
32
+ panel.classList.toggle("is-open", next);
33
+ accordion.dispatchEvent(new CustomEvent(next ? "pp:accordion:open" : "pp:accordion:close", {
34
+ bubbles: true,
35
+ detail: { index: i, trigger, panel }
36
+ }));
37
+ });
38
+ trigger.addEventListener("keydown", (e) => {
39
+ const idx = triggers.indexOf(trigger);
40
+ if (e.key === "ArrowDown") {
41
+ e.preventDefault();
42
+ triggers[(idx + 1) % triggers.length].focus();
43
+ } else if (e.key === "ArrowUp") {
44
+ e.preventDefault();
45
+ triggers[(idx - 1 + triggers.length) % triggers.length].focus();
46
+ } else if (e.key === "Home") {
47
+ e.preventDefault();
48
+ triggers[0].focus();
49
+ } else if (e.key === "End") {
50
+ e.preventDefault();
51
+ triggers[triggers.length - 1].focus();
52
+ }
53
+ });
54
+ });
55
+ function setItem(index, open) {
56
+ const trigger = triggers[index];
57
+ if (!trigger) return;
58
+ const panelId = trigger.getAttribute("aria-controls");
59
+ const panel = panelId ? document.getElementById(panelId) : trigger.nextElementSibling;
60
+ if (!panel) return;
61
+ trigger.setAttribute("aria-expanded", String(open));
62
+ panel.setAttribute("aria-hidden", String(!open));
63
+ panel.classList.toggle("is-open", open);
64
+ accordion.dispatchEvent(new CustomEvent(open ? "pp:accordion:open" : "pp:accordion:close", {
65
+ bubbles: true,
66
+ detail: { index, trigger, panel }
67
+ }));
68
+ }
69
+ const api = {
70
+ open: (index) => setItem(index, true),
71
+ close: (index) => setItem(index, false),
72
+ toggleAll() {
73
+ const anyOpen = triggers.some((t) => t.getAttribute("aria-expanded") === "true");
74
+ triggers.forEach((_, i) => setItem(i, !anyOpen));
75
+ }
76
+ };
77
+ registry[id] = api;
78
+ });
79
+ window.ppAccordion = {
80
+ get(ref) {
81
+ if (typeof ref === "string") return registry[ref];
82
+ if (ref instanceof Element) return registry[ref.id];
83
+ return null;
84
+ }
85
+ };
86
+ })();
87
+ })();
88
+ //# sourceMappingURL=accordion.js.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../src/js/accordion.js"],
4
+ "sourcesContent": ["(function () {\n const registry = {};\n\n document.querySelectorAll('.pp-accordion').forEach((accordion, accordionIdx) => {\n const allowMultiple = accordion.hasAttribute('data-allow-multiple');\n const id = accordion.id || `pp-accordion-${accordionIdx}`;\n if (!accordion.id) accordion.id = id;\n\n const triggers = [...accordion.querySelectorAll('.pp-accordion__trigger')];\n\n triggers.forEach((trigger, i) => {\n const panelId = trigger.getAttribute('aria-controls');\n const panel = panelId\n ? document.getElementById(panelId)\n : trigger.nextElementSibling;\n\n if (!panel) return;\n\n const isOpen = trigger.getAttribute('aria-expanded') === 'true';\n panel.setAttribute('aria-hidden', isOpen ? 'false' : 'true');\n if (isOpen) panel.classList.add('is-open');\n\n trigger.addEventListener('click', () => {\n const expanded = trigger.getAttribute('aria-expanded') === 'true';\n\n if (!allowMultiple) {\n triggers.forEach((t) => {\n if (t === trigger) return;\n t.setAttribute('aria-expanded', 'false');\n const p = t.getAttribute('aria-controls')\n ? document.getElementById(t.getAttribute('aria-controls'))\n : t.nextElementSibling;\n if (p) {\n p.setAttribute('aria-hidden', 'true');\n p.classList.remove('is-open');\n }\n });\n }\n\n const next = !expanded;\n trigger.setAttribute('aria-expanded', String(next));\n panel.setAttribute('aria-hidden', String(!next));\n panel.classList.toggle('is-open', next);\n\n accordion.dispatchEvent(new CustomEvent(next ? 'pp:accordion:open' : 'pp:accordion:close', {\n bubbles: true,\n detail: { index: i, trigger, panel },\n }));\n });\n\n trigger.addEventListener('keydown', (e) => {\n const idx = triggers.indexOf(trigger);\n if (e.key === 'ArrowDown') {\n e.preventDefault();\n triggers[(idx + 1) % triggers.length].focus();\n } else if (e.key === 'ArrowUp') {\n e.preventDefault();\n triggers[(idx - 1 + triggers.length) % triggers.length].focus();\n } else if (e.key === 'Home') {\n e.preventDefault();\n triggers[0].focus();\n } else if (e.key === 'End') {\n e.preventDefault();\n triggers[triggers.length - 1].focus();\n }\n });\n });\n\n function setItem(index, open) {\n const trigger = triggers[index];\n if (!trigger) return;\n const panelId = trigger.getAttribute('aria-controls');\n const panel = panelId ? document.getElementById(panelId) : trigger.nextElementSibling;\n if (!panel) return;\n trigger.setAttribute('aria-expanded', String(open));\n panel.setAttribute('aria-hidden', String(!open));\n panel.classList.toggle('is-open', open);\n accordion.dispatchEvent(new CustomEvent(open ? 'pp:accordion:open' : 'pp:accordion:close', {\n bubbles: true,\n detail: { index, trigger, panel },\n }));\n }\n\n const api = {\n open: (index) => setItem(index, true),\n close: (index) => setItem(index, false),\n toggleAll() {\n const anyOpen = triggers.some((t) => t.getAttribute('aria-expanded') === 'true');\n triggers.forEach((_, i) => setItem(i, !anyOpen));\n },\n };\n\n registry[id] = api;\n });\n\n window.ppAccordion = {\n get(ref) {\n if (typeof ref === 'string') return registry[ref];\n if (ref instanceof Element) return registry[ref.id];\n return null;\n },\n };\n})();\n"],
5
+ "mappings": "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",
6
+ "names": []
7
+ }
package/dist/alert.js ADDED
@@ -0,0 +1,26 @@
1
+ (() => {
2
+ (function() {
3
+ function dismiss(alertEl) {
4
+ if (alertEl._dismissed) return;
5
+ alertEl._dismissed = true;
6
+ alertEl.classList.add("is-dismissing");
7
+ alertEl.dispatchEvent(new CustomEvent("pp:alert:dismiss", { bubbles: true }));
8
+ alertEl.addEventListener("animationend", () => alertEl.remove(), { once: true });
9
+ setTimeout(() => alertEl.remove(), 250);
10
+ }
11
+ window.ppAlert = {
12
+ dismiss(idOrEl) {
13
+ const el = typeof idOrEl === "string" ? document.getElementById(idOrEl) : idOrEl;
14
+ if (el) dismiss(el);
15
+ }
16
+ };
17
+ document.addEventListener("click", (e) => {
18
+ const btn = e.target.closest("[data-alert-dismiss]");
19
+ if (btn) {
20
+ const alert = btn.closest(".pp-alert");
21
+ if (alert) dismiss(alert);
22
+ }
23
+ });
24
+ })();
25
+ })();
26
+ //# sourceMappingURL=alert.js.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 3,
3
+ "sources": ["../src/js/alert.js"],
4
+ "sourcesContent": ["(function () {\n function dismiss(alertEl) {\n if (alertEl._dismissed) return;\n alertEl._dismissed = true;\n alertEl.classList.add('is-dismissing');\n alertEl.dispatchEvent(new CustomEvent('pp:alert:dismiss', { bubbles: true }));\n alertEl.addEventListener('animationend', () => alertEl.remove(), { once: true });\n setTimeout(() => alertEl.remove(), 250);\n }\n\n window.ppAlert = {\n dismiss(idOrEl) {\n const el = typeof idOrEl === 'string'\n ? document.getElementById(idOrEl)\n : idOrEl;\n if (el) dismiss(el);\n },\n };\n\n // Auto-wire [data-alert-dismiss] buttons\n document.addEventListener('click', (e) => {\n const btn = e.target.closest('[data-alert-dismiss]');\n if (btn) {\n const alert = btn.closest('.pp-alert');\n if (alert) dismiss(alert);\n }\n });\n})();\n"],
5
+ "mappings": ";AAAA,GAAC,WAAY;AACX,aAAS,QAAQ,SAAS;AACxB,UAAI,QAAQ,WAAY;AACxB,cAAQ,aAAa;AACrB,cAAQ,UAAU,IAAI,eAAe;AACrC,cAAQ,cAAc,IAAI,YAAY,oBAAoB,EAAE,SAAS,KAAK,CAAC,CAAC;AAC5E,cAAQ,iBAAiB,gBAAgB,MAAM,QAAQ,OAAO,GAAG,EAAE,MAAM,KAAK,CAAC;AAC/E,iBAAW,MAAM,QAAQ,OAAO,GAAG,GAAG;AAAA,IACxC;AAEA,WAAO,UAAU;AAAA,MACf,QAAQ,QAAQ;AACd,cAAM,KAAK,OAAO,WAAW,WACzB,SAAS,eAAe,MAAM,IAC9B;AACJ,YAAI,GAAI,SAAQ,EAAE;AAAA,MACpB;AAAA,IACF;AAGA,aAAS,iBAAiB,SAAS,CAAC,MAAM;AACxC,YAAM,MAAM,EAAE,OAAO,QAAQ,sBAAsB;AACnD,UAAI,KAAK;AACP,cAAM,QAAQ,IAAI,QAAQ,WAAW;AACrC,YAAI,MAAO,SAAQ,KAAK;AAAA,MAC1B;AAAA,IACF,CAAC;AAAA,EACH,GAAG;",
6
+ "names": []
7
+ }
package/dist/carousel.js CHANGED
@@ -56,6 +56,10 @@
56
56
  requestAnimationFrame(() => {
57
57
  announcer.textContent = label;
58
58
  });
59
+ root.dispatchEvent(new CustomEvent("pp:carousel:change", {
60
+ bubbles: true,
61
+ detail: { index: idx, total, label }
62
+ }));
59
63
  }
60
64
  const observer = new IntersectionObserver(
61
65
  (entries) => {