tyrell-components 1.0.0-TC9 → 1.0.0-rc.21
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.
- package/AGENTS.md +122 -0
- package/CHANGELOG.md +1531 -0
- package/README.md +71 -53
- package/css/tyrell-colors-static.css +1 -0
- package/css/tyrell-theme.css +1 -0
- package/css/tyrell.css +1 -1783
- package/dist/tyrell-colors-static.css +1 -0
- package/dist/tyrell-theme.css +1 -0
- package/dist/tyrell.css +1 -1783
- package/dist/tyrell.js +1 -1
- package/guides/AGENT_INSTRUCTIONS.md +124 -0
- package/guides/AI_GUIDE.md +53 -0
- package/guides/CSS_GUIDE.md +1016 -0
- package/guides/DATASTAR_TY_GUIDE.md +657 -0
- package/guides/ICONS_GUIDE.md +212 -0
- package/guides/TY_GUIDE.md +935 -0
- package/guides/clj/CLOJURESCRIPT_GUIDE.md +300 -0
- package/guides/clj/CODE_SPLITTING.md +279 -0
- package/guides/clj/COMPONENT_GUIDE.md +391 -0
- package/guides/clj/HELIX_TY_GUIDE.md +428 -0
- package/guides/clj/I18N_GUIDE.md +478 -0
- package/guides/clj/LAYOUT_GUIDE.md +273 -0
- package/guides/clj/QUICKSTART.md +266 -0
- package/guides/clj/REAGENT_TY_GUIDE.md +408 -0
- package/guides/clj/REPLICANT_TY_GUIDE.md +623 -0
- package/guides/clj/ROUTING_GUIDE.md +346 -0
- package/guides/clj/UIX_TY_GUIDE.md +319 -0
- package/guides/js/HTMX_TY_GUIDE.md +252 -0
- package/guides/js/JAVASCRIPT_GUIDE.md +388 -0
- package/guides/js/REACT_TY_GUIDE.md +983 -0
- package/guides/js/SVELTE_TY_GUIDE.md +682 -0
- package/guides/js/TYCOMPONENT_GUIDE.md +962 -0
- package/guides/js/VUE_TY_GUIDE.md +738 -0
- package/lib/base/ty-component.d.ts +57 -13
- package/lib/base/ty-component.js +266 -292
- package/lib/components/button.d.ts +33 -18
- package/lib/components/button.js +317 -267
- package/lib/components/calendar-month.d.ts +30 -47
- package/lib/components/calendar-month.js +455 -429
- package/lib/components/calendar-navigation.d.ts +41 -49
- package/lib/components/calendar-navigation.js +287 -346
- package/lib/components/calendar.d.ts +73 -83
- package/lib/components/calendar.js +837 -762
- package/lib/components/checkbox.d.ts +26 -75
- package/lib/components/checkbox.js +298 -391
- package/lib/components/copy.d.ts +20 -60
- package/lib/components/copy.js +276 -380
- package/lib/components/date-picker.d.ts +100 -183
- package/lib/components/date-picker.js +1155 -1570
- package/lib/components/file-upload.d.ts +16 -15
- package/lib/components/file-upload.js +436 -426
- package/lib/components/icon.d.ts +3 -24
- package/lib/components/icon.js +141 -230
- package/lib/components/input.d.ts +93 -108
- package/lib/components/input.js +734 -710
- package/lib/components/modal.d.ts +39 -29
- package/lib/components/modal.js +419 -438
- package/lib/components/option.d.ts +20 -35
- package/lib/components/option.js +184 -309
- package/lib/components/popup.d.ts +2 -17
- package/lib/components/popup.js +353 -347
- package/lib/components/radio.d.ts +33 -25
- package/lib/components/radio.js +433 -422
- package/lib/components/resize-observer.d.ts +3 -30
- package/lib/components/resize-observer.js +71 -103
- package/lib/components/scroll-container.d.ts +21 -14
- package/lib/components/scroll-container.js +292 -234
- package/lib/components/select.d.ts +446 -0
- package/lib/components/select.js +1381 -0
- package/lib/components/selected-tags.d.ts +60 -0
- package/lib/components/selected-tags.js +225 -0
- package/lib/components/sortable.d.ts +175 -0
- package/lib/components/sortable.js +1844 -0
- package/lib/components/step.d.ts +1 -6
- package/lib/components/step.js +62 -68
- package/lib/components/switch.d.ts +15 -15
- package/lib/components/switch.js +237 -231
- package/lib/components/tab.d.ts +50 -7
- package/lib/components/tab.js +203 -69
- package/lib/components/tabs.d.ts +19 -64
- package/lib/components/tabs.js +600 -618
- package/lib/components/tag.d.ts +14 -52
- package/lib/components/tag.js +231 -306
- package/lib/components/textarea.d.ts +58 -89
- package/lib/components/textarea.js +523 -573
- package/lib/components/tooltip.d.ts +8 -13
- package/lib/components/tooltip.js +322 -409
- package/lib/components/wizard.d.ts +7 -54
- package/lib/components/wizard.js +376 -606
- package/lib/icons/fontawesome/brands.d.ts +0 -1
- package/lib/icons/fontawesome/brands.js +0 -8
- package/lib/icons/fontawesome/regular.d.ts +0 -1
- package/lib/icons/fontawesome/regular.js +0 -8
- package/lib/icons/fontawesome/solid.d.ts +0 -1
- package/lib/icons/fontawesome/solid.js +0 -8
- package/lib/icons/heroicons/micro.d.ts +0 -1
- package/lib/icons/heroicons/micro.js +392 -400
- package/lib/icons/heroicons/mini.d.ts +0 -1
- package/lib/icons/heroicons/mini.js +382 -390
- package/lib/icons/heroicons/outline.d.ts +0 -1
- package/lib/icons/heroicons/outline.js +337 -345
- package/lib/icons/heroicons/solid.d.ts +0 -1
- package/lib/icons/heroicons/solid.js +407 -415
- package/lib/icons/lucide.d.ts +0 -1
- package/lib/icons/lucide.js +24479 -26351
- package/lib/icons/material/filled.d.ts +0 -1
- package/lib/icons/material/filled.js +9653 -9663
- package/lib/icons/material/outlined.d.ts +0 -1
- package/lib/icons/material/outlined.js +10271 -10281
- package/lib/icons/material/round.d.ts +0 -1
- package/lib/icons/material/round.js +10495 -10505
- package/lib/icons/material/sharp.d.ts +0 -1
- package/lib/icons/material/sharp.js +9905 -9915
- package/lib/icons/material/two-tone.d.ts +0 -1
- package/lib/icons/material/two-tone.js +12792 -12802
- package/lib/index.d.ts +7 -4
- package/lib/index.js +26 -39
- package/lib/styles/button.d.ts +24 -7
- package/lib/styles/button.js +285 -445
- package/lib/styles/calendar-month.d.ts +7 -6
- package/lib/styles/calendar-month.js +158 -226
- package/lib/styles/calendar-navigation.d.ts +2 -6
- package/lib/styles/calendar-navigation.js +108 -127
- package/lib/styles/calendar.d.ts +3 -3
- package/lib/styles/calendar.js +87 -23
- package/lib/styles/checkbox.d.ts +7 -6
- package/lib/styles/checkbox.js +101 -15
- package/lib/styles/copy.d.ts +3 -2
- package/lib/styles/copy.js +91 -71
- package/lib/styles/custom-scrollbar.d.ts +1 -2
- package/lib/styles/custom-scrollbar.js +80 -115
- package/lib/styles/date-picker.d.ts +4 -6
- package/lib/styles/date-picker.js +321 -388
- package/lib/styles/field-size.d.ts +6 -0
- package/lib/styles/field-size.js +91 -0
- package/lib/styles/file-upload.d.ts +1 -2
- package/lib/styles/file-upload.js +143 -188
- package/lib/styles/icon.d.ts +2 -6
- package/lib/styles/icon.js +92 -170
- package/lib/styles/input.d.ts +4 -7
- package/lib/styles/input.js +148 -643
- package/lib/styles/modal.d.ts +1 -2
- package/lib/styles/modal.js +127 -108
- package/lib/styles/option.d.ts +2 -6
- package/lib/styles/option.js +53 -96
- package/lib/styles/popup.d.ts +1 -2
- package/lib/styles/popup.js +47 -77
- package/lib/styles/radio.d.ts +3 -2
- package/lib/styles/radio.js +90 -116
- package/lib/styles/resize-observer.d.ts +1 -2
- package/lib/styles/resize-observer.js +2 -12
- package/lib/styles/scroll-container.d.ts +1 -2
- package/lib/styles/scroll-container.js +103 -146
- package/lib/styles/select-base.d.ts +8 -0
- package/lib/styles/select-base.js +747 -0
- package/lib/styles/select.d.ts +11 -0
- package/lib/styles/select.js +229 -0
- package/lib/styles/sortable.d.ts +16 -0
- package/lib/styles/sortable.js +85 -0
- package/lib/styles/step.d.ts +1 -2
- package/lib/styles/step.js +15 -34
- package/lib/styles/switch.d.ts +3 -2
- package/lib/styles/switch.js +52 -68
- package/lib/styles/tab.d.ts +1 -2
- package/lib/styles/tab.js +86 -34
- package/lib/styles/tabs.d.ts +3 -11
- package/lib/styles/tabs.js +204 -162
- package/lib/styles/tag.d.ts +2 -6
- package/lib/styles/tag.js +168 -362
- package/lib/styles/textarea.d.ts +1 -2
- package/lib/styles/textarea.js +238 -306
- package/lib/styles/tooltip.d.ts +4 -3
- package/lib/styles/tooltip.js +3 -131
- package/lib/styles/wizard.d.ts +8 -20
- package/lib/styles/wizard.js +306 -295
- package/lib/types/common.d.ts +9 -8
- package/lib/types/common.js +8 -5
- package/lib/utils/calendar-utils.d.ts +49 -65
- package/lib/utils/calendar-utils.js +158 -343
- package/lib/utils/custom-scrollbar.d.ts +6 -20
- package/lib/utils/custom-scrollbar.js +273 -317
- package/lib/utils/flavor-sheet.d.ts +31 -0
- package/lib/utils/flavor-sheet.js +17 -0
- package/lib/utils/icon-registry.d.ts +0 -15
- package/lib/utils/icon-registry.js +138 -279
- package/lib/utils/icons.d.ts +9 -0
- package/lib/utils/icons.js +1 -0
- package/lib/utils/loader-registry.d.ts +2 -3
- package/lib/utils/loader-registry.js +3 -35
- package/lib/utils/locale.d.ts +2 -80
- package/lib/utils/locale.js +30 -205
- package/lib/utils/mobile.d.ts +0 -1
- package/lib/utils/mobile.js +1 -18
- package/lib/utils/number-format.d.ts +6 -24
- package/lib/utils/number-format.js +53 -136
- package/lib/utils/positioning.d.ts +72 -22
- package/lib/utils/positioning.js +224 -298
- package/lib/utils/property-capture.d.ts +5 -27
- package/lib/utils/property-capture.js +36 -144
- package/lib/utils/property-manager.d.ts +6 -6
- package/lib/utils/property-manager.js +127 -196
- package/lib/utils/resize-observer.d.ts +0 -1
- package/lib/utils/resize-observer.js +23 -59
- package/lib/utils/scroll-lock.d.ts +10 -11
- package/lib/utils/scroll-lock.js +165 -173
- package/lib/utils/styles.d.ts +0 -6
- package/lib/utils/styles.js +17 -48
- package/lib/utils/upgrade-properties.d.ts +21 -0
- package/lib/utils/upgrade-properties.js +47 -0
- package/lib/utils/validity.d.ts +122 -0
- package/lib/utils/validity.js +289 -0
- package/lib/version.d.ts +1 -2
- package/lib/version.js +1 -11
- package/package.json +62 -18
- package/lib/base/ty-component.d.ts.map +0 -1
- package/lib/base/ty-component.js.map +0 -1
- package/lib/components/button.d.ts.map +0 -1
- package/lib/components/button.js.map +0 -1
- package/lib/components/calendar-month.d.ts.map +0 -1
- package/lib/components/calendar-month.js.map +0 -1
- package/lib/components/calendar-navigation.d.ts.map +0 -1
- package/lib/components/calendar-navigation.js.map +0 -1
- package/lib/components/calendar.d.ts.map +0 -1
- package/lib/components/calendar.js.map +0 -1
- package/lib/components/checkbox.d.ts.map +0 -1
- package/lib/components/checkbox.js.map +0 -1
- package/lib/components/copy.d.ts.map +0 -1
- package/lib/components/copy.js.map +0 -1
- package/lib/components/date-picker.d.ts.map +0 -1
- package/lib/components/date-picker.js.map +0 -1
- package/lib/components/dropdown.d.ts +0 -404
- package/lib/components/dropdown.d.ts.map +0 -1
- package/lib/components/dropdown.js +0 -1563
- package/lib/components/dropdown.js.map +0 -1
- package/lib/components/file-upload.d.ts.map +0 -1
- package/lib/components/file-upload.js.map +0 -1
- package/lib/components/icon.d.ts.map +0 -1
- package/lib/components/icon.js.map +0 -1
- package/lib/components/input.d.ts.map +0 -1
- package/lib/components/input.js.map +0 -1
- package/lib/components/modal.d.ts.map +0 -1
- package/lib/components/modal.js.map +0 -1
- package/lib/components/multiselect.d.ts +0 -408
- package/lib/components/multiselect.d.ts.map +0 -1
- package/lib/components/multiselect.js +0 -1611
- package/lib/components/multiselect.js.map +0 -1
- package/lib/components/option.d.ts.map +0 -1
- package/lib/components/option.js.map +0 -1
- package/lib/components/popup.d.ts.map +0 -1
- package/lib/components/popup.js.map +0 -1
- package/lib/components/radio.d.ts.map +0 -1
- package/lib/components/radio.js.map +0 -1
- package/lib/components/resize-observer.d.ts.map +0 -1
- package/lib/components/resize-observer.js.map +0 -1
- package/lib/components/scroll-container.d.ts.map +0 -1
- package/lib/components/scroll-container.js.map +0 -1
- package/lib/components/step.d.ts.map +0 -1
- package/lib/components/step.js.map +0 -1
- package/lib/components/switch.d.ts.map +0 -1
- package/lib/components/switch.js.map +0 -1
- package/lib/components/tab.d.ts.map +0 -1
- package/lib/components/tab.js.map +0 -1
- package/lib/components/tabs.d.ts.map +0 -1
- package/lib/components/tabs.js.map +0 -1
- package/lib/components/tag.d.ts.map +0 -1
- package/lib/components/tag.js.map +0 -1
- package/lib/components/textarea.d.ts.map +0 -1
- package/lib/components/textarea.js.map +0 -1
- package/lib/components/tooltip.d.ts.map +0 -1
- package/lib/components/tooltip.js.map +0 -1
- package/lib/components/wizard.d.ts.map +0 -1
- package/lib/components/wizard.js.map +0 -1
- package/lib/icons/fontawesome/brands.d.ts.map +0 -1
- package/lib/icons/fontawesome/brands.js.map +0 -1
- package/lib/icons/fontawesome/regular.d.ts.map +0 -1
- package/lib/icons/fontawesome/regular.js.map +0 -1
- package/lib/icons/fontawesome/solid.d.ts.map +0 -1
- package/lib/icons/fontawesome/solid.js.map +0 -1
- package/lib/icons/heroicons/micro.d.ts.map +0 -1
- package/lib/icons/heroicons/micro.js.map +0 -1
- package/lib/icons/heroicons/mini.d.ts.map +0 -1
- package/lib/icons/heroicons/mini.js.map +0 -1
- package/lib/icons/heroicons/outline.d.ts.map +0 -1
- package/lib/icons/heroicons/outline.js.map +0 -1
- package/lib/icons/heroicons/solid.d.ts.map +0 -1
- package/lib/icons/heroicons/solid.js.map +0 -1
- package/lib/icons/lucide.d.ts.map +0 -1
- package/lib/icons/lucide.js.map +0 -1
- package/lib/icons/material/filled.d.ts.map +0 -1
- package/lib/icons/material/filled.js.map +0 -1
- package/lib/icons/material/outlined.d.ts.map +0 -1
- package/lib/icons/material/outlined.js.map +0 -1
- package/lib/icons/material/round.d.ts.map +0 -1
- package/lib/icons/material/round.js.map +0 -1
- package/lib/icons/material/sharp.d.ts.map +0 -1
- package/lib/icons/material/sharp.js.map +0 -1
- package/lib/icons/material/two-tone.d.ts.map +0 -1
- package/lib/icons/material/two-tone.js.map +0 -1
- package/lib/index.d.ts.map +0 -1
- package/lib/index.js.map +0 -1
- package/lib/styles/button.d.ts.map +0 -1
- package/lib/styles/button.js.map +0 -1
- package/lib/styles/calendar-month.d.ts.map +0 -1
- package/lib/styles/calendar-month.js.map +0 -1
- package/lib/styles/calendar-navigation.d.ts.map +0 -1
- package/lib/styles/calendar-navigation.js.map +0 -1
- package/lib/styles/calendar.d.ts.map +0 -1
- package/lib/styles/calendar.js.map +0 -1
- package/lib/styles/checkbox.d.ts.map +0 -1
- package/lib/styles/checkbox.js.map +0 -1
- package/lib/styles/copy.d.ts.map +0 -1
- package/lib/styles/copy.js.map +0 -1
- package/lib/styles/custom-scrollbar.d.ts.map +0 -1
- package/lib/styles/custom-scrollbar.js.map +0 -1
- package/lib/styles/date-picker.d.ts.map +0 -1
- package/lib/styles/date-picker.js.map +0 -1
- package/lib/styles/dropdown.d.ts +0 -12
- package/lib/styles/dropdown.d.ts.map +0 -1
- package/lib/styles/dropdown.js +0 -1048
- package/lib/styles/dropdown.js.map +0 -1
- package/lib/styles/file-upload.d.ts.map +0 -1
- package/lib/styles/file-upload.js.map +0 -1
- package/lib/styles/icon.d.ts.map +0 -1
- package/lib/styles/icon.js.map +0 -1
- package/lib/styles/input.d.ts.map +0 -1
- package/lib/styles/input.js.map +0 -1
- package/lib/styles/modal.d.ts.map +0 -1
- package/lib/styles/modal.js.map +0 -1
- package/lib/styles/multiselect.d.ts +0 -6
- package/lib/styles/multiselect.d.ts.map +0 -1
- package/lib/styles/multiselect.js +0 -837
- package/lib/styles/multiselect.js.map +0 -1
- package/lib/styles/option.d.ts.map +0 -1
- package/lib/styles/option.js.map +0 -1
- package/lib/styles/popup.d.ts.map +0 -1
- package/lib/styles/popup.js.map +0 -1
- package/lib/styles/radio.d.ts.map +0 -1
- package/lib/styles/radio.js.map +0 -1
- package/lib/styles/resize-observer.d.ts.map +0 -1
- package/lib/styles/resize-observer.js.map +0 -1
- package/lib/styles/scroll-container.d.ts.map +0 -1
- package/lib/styles/scroll-container.js.map +0 -1
- package/lib/styles/step.d.ts.map +0 -1
- package/lib/styles/step.js.map +0 -1
- package/lib/styles/switch.d.ts.map +0 -1
- package/lib/styles/switch.js.map +0 -1
- package/lib/styles/tab.d.ts.map +0 -1
- package/lib/styles/tab.js.map +0 -1
- package/lib/styles/tabs.d.ts.map +0 -1
- package/lib/styles/tabs.js.map +0 -1
- package/lib/styles/tag.d.ts.map +0 -1
- package/lib/styles/tag.js.map +0 -1
- package/lib/styles/textarea.d.ts.map +0 -1
- package/lib/styles/textarea.js.map +0 -1
- package/lib/styles/tooltip.d.ts.map +0 -1
- package/lib/styles/tooltip.js.map +0 -1
- package/lib/styles/wizard.d.ts.map +0 -1
- package/lib/styles/wizard.js.map +0 -1
- package/lib/types/common.d.ts.map +0 -1
- package/lib/types/common.js.map +0 -1
- package/lib/utils/calendar-utils.d.ts.map +0 -1
- package/lib/utils/calendar-utils.js.map +0 -1
- package/lib/utils/custom-scrollbar.d.ts.map +0 -1
- package/lib/utils/custom-scrollbar.js.map +0 -1
- package/lib/utils/icon-registry.d.ts.map +0 -1
- package/lib/utils/icon-registry.js.map +0 -1
- package/lib/utils/loader-registry.d.ts.map +0 -1
- package/lib/utils/loader-registry.js.map +0 -1
- package/lib/utils/locale.d.ts.map +0 -1
- package/lib/utils/locale.js.map +0 -1
- package/lib/utils/mobile.d.ts.map +0 -1
- package/lib/utils/mobile.js.map +0 -1
- package/lib/utils/number-format.d.ts.map +0 -1
- package/lib/utils/number-format.js.map +0 -1
- package/lib/utils/parse-boolean.d.ts +0 -39
- package/lib/utils/parse-boolean.d.ts.map +0 -1
- package/lib/utils/parse-boolean.js +0 -58
- package/lib/utils/parse-boolean.js.map +0 -1
- package/lib/utils/positioning.d.ts.map +0 -1
- package/lib/utils/positioning.js.map +0 -1
- package/lib/utils/property-capture.d.ts.map +0 -1
- package/lib/utils/property-capture.js.map +0 -1
- package/lib/utils/property-manager.d.ts.map +0 -1
- package/lib/utils/property-manager.js.map +0 -1
- package/lib/utils/resize-observer.d.ts.map +0 -1
- package/lib/utils/resize-observer.js.map +0 -1
- package/lib/utils/scroll-lock.d.ts.map +0 -1
- package/lib/utils/scroll-lock.js.map +0 -1
- package/lib/utils/styles.d.ts.map +0 -1
- package/lib/utils/styles.js.map +0 -1
- package/lib/version.d.ts.map +0 -1
- package/lib/version.js.map +0 -1
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
# HTMX + Tyrell Guide
|
|
2
|
+
|
|
3
|
+
Tyrell ships standard Web Components, so they integrate with HTMX without a wrapper. Form-associated ty components participate in `FormData` automatically; `change` events bubble like native ones; swapped HTML upgrades into components on every swap.
|
|
4
|
+
|
|
5
|
+
This guide covers what's specific to that combination — the rest is just HTMX.
|
|
6
|
+
|
|
7
|
+
## Setup
|
|
8
|
+
|
|
9
|
+
Single CDN script tag, single stylesheet:
|
|
10
|
+
|
|
11
|
+
```html
|
|
12
|
+
<!DOCTYPE html>
|
|
13
|
+
<html>
|
|
14
|
+
<head>
|
|
15
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell.css">
|
|
16
|
+
<!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
|
|
17
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell-theme.css">
|
|
18
|
+
<script src="https://cdn.jsdelivr.net/npm/tyrell-components/dist/tyrell.js"></script>
|
|
19
|
+
<script src="https://unpkg.com/htmx.org@2"></script>
|
|
20
|
+
</head>
|
|
21
|
+
<body>
|
|
22
|
+
<main hx-boost="true">
|
|
23
|
+
<ty-button flavor="primary" hx-get="/api/hello" hx-target="#out">
|
|
24
|
+
Click me
|
|
25
|
+
</ty-button>
|
|
26
|
+
<div id="out"></div>
|
|
27
|
+
</main>
|
|
28
|
+
</body>
|
|
29
|
+
</html>
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
That's it. `<ty-*>` elements work as HTMX targets, triggers, and form fields with no glue code.
|
|
33
|
+
|
|
34
|
+
## Form submission — `FormData` works automatically
|
|
35
|
+
|
|
36
|
+
Every form-associated ty component (`ty-input`, `ty-textarea`, `ty-checkbox`, `ty-switch`, `ty-radio-group`, `ty-select`, `ty-date-picker`, `ty-file-upload`) calls `internals.setFormValue()` on every change. HTMX's `hx-post` / `hx-put` on a `<form>` includes them in the serialized payload under their `name` attribute — same as `<input>`.
|
|
37
|
+
|
|
38
|
+
```html
|
|
39
|
+
<form hx-post="/api/contact" hx-target="#result">
|
|
40
|
+
<ty-input name="email" type="email" label="Email" required></ty-input>
|
|
41
|
+
|
|
42
|
+
<ty-select name="topic" label="Topic">
|
|
43
|
+
<ty-option value="sales">Sales</ty-option>
|
|
44
|
+
<ty-option value="support">Support</ty-option>
|
|
45
|
+
</ty-select>
|
|
46
|
+
|
|
47
|
+
<ty-textarea name="message" label="Message" rows="4"></ty-textarea>
|
|
48
|
+
|
|
49
|
+
<ty-button type="submit" flavor="primary">Send</ty-button>
|
|
50
|
+
</form>
|
|
51
|
+
|
|
52
|
+
<div id="result"></div>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The server receives `email`, `topic`, `message` in the request body. No `hx-vals`, no `hx-include` needed.
|
|
56
|
+
|
|
57
|
+
**Multi-value fields** (`ty-select multiple`) post repeated `name=` entries — your framework's body parser must support multi-value form fields (most do).
|
|
58
|
+
|
|
59
|
+
**File uploads** (`ty-file-upload`) need `hx-encoding="multipart/form-data"` on the form, just like a native file input. Each selected file is appended to the body under the component's `name` attribute (multiple entries when `multiple` is set):
|
|
60
|
+
|
|
61
|
+
```html
|
|
62
|
+
<form hx-post="/api/upload"
|
|
63
|
+
hx-target="#result"
|
|
64
|
+
hx-encoding="multipart/form-data">
|
|
65
|
+
<ty-file-upload name="docs" label="Attachments" multiple
|
|
66
|
+
accept=".pdf,.docx"></ty-file-upload>
|
|
67
|
+
<ty-button type="submit" flavor="primary">Upload</ty-button>
|
|
68
|
+
</form>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Server-side: read repeated `docs` parts (Flask `request.files.getlist('docs')`, Rails `params[:docs]`, Express `req.files`, etc.).
|
|
72
|
+
|
|
73
|
+
## Triggering on user changes — `hx-trigger="change"`
|
|
74
|
+
|
|
75
|
+
Tyrell components emit a bubbling `change` event when the user commits a new value. HTMX picks that up the same way it does for native inputs:
|
|
76
|
+
|
|
77
|
+
```html
|
|
78
|
+
<ty-select name="country"
|
|
79
|
+
hx-get="/api/cities"
|
|
80
|
+
hx-trigger="change"
|
|
81
|
+
hx-target="#city-picker"
|
|
82
|
+
hx-vals='js:{country: event.detail.value}'>
|
|
83
|
+
<ty-option value="us">United States</ty-option>
|
|
84
|
+
<ty-option value="de">Germany</ty-option>
|
|
85
|
+
</ty-select>
|
|
86
|
+
|
|
87
|
+
<div id="city-picker"></div>
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The `hx-vals='js:{...}'` form lets you pull the actual value off `event.detail.value` rather than relying on serialization. For a single select inside a `<form>`, you can skip `hx-vals` and let normal form serialization handle it.
|
|
91
|
+
|
|
92
|
+
**Debouncing.** Use HTMX's built-in modifier — `hx-trigger="change delay:300ms"`. `ty-input` *also* has a built-in `debounce` attribute (ms) that debounces its own `change` event before HTMX ever sees it; pick one, don't double up.
|
|
93
|
+
|
|
94
|
+
## Swapped content auto-upgrades
|
|
95
|
+
|
|
96
|
+
`customElements.define()` is global, so any `<ty-*>` tag arriving via an HTMX swap becomes a fully functional component immediately — no `htmx:afterSwap` hook needed.
|
|
97
|
+
|
|
98
|
+
```html
|
|
99
|
+
<button hx-get="/fragments/wizard" hx-target="#region" hx-swap="innerHTML">
|
|
100
|
+
Load wizard
|
|
101
|
+
</button>
|
|
102
|
+
<div id="region"></div>
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Server returns:
|
|
106
|
+
```html
|
|
107
|
+
<ty-wizard>
|
|
108
|
+
<ty-step id="info" label="Info">…</ty-step>
|
|
109
|
+
<ty-step id="confirm" label="Confirm">…</ty-step>
|
|
110
|
+
</ty-wizard>
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The wizard renders, navigates, and animates as if it had been on the page from the start.
|
|
114
|
+
|
|
115
|
+
**Out-of-band swaps** (`hx-swap-oob`) work the same way. Modal-driven flows often pair `hx-target` with an OOB swap that injects `<ty-modal open>` into a slot at the bottom of `<body>`.
|
|
116
|
+
|
|
117
|
+
## Icons
|
|
118
|
+
|
|
119
|
+
Put the SVG inside the tag. The server already has it, so there's no registry and no boot script, and it works in every swap (regular, OOB, `hx-boost`):
|
|
120
|
+
|
|
121
|
+
```html
|
|
122
|
+
<ty-icon size="md">
|
|
123
|
+
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>
|
|
124
|
+
</ty-icon>
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
A template helper (Jinja macro, Go template func, Clojure fn) keeps templates short. To use `name="…"` instead, register once per page with `tyIcons.register`; swapped-in content reads the same registry.
|
|
128
|
+
|
|
129
|
+
Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-html).
|
|
130
|
+
|
|
131
|
+
## Modals and HTMX
|
|
132
|
+
|
|
133
|
+
`<ty-modal>` is a `<dialog>` wrapper. Two ergonomic patterns:
|
|
134
|
+
|
|
135
|
+
**Server controls open state** — toggle the `open` attribute via OOB swap:
|
|
136
|
+
|
|
137
|
+
```html
|
|
138
|
+
<!-- Trigger -->
|
|
139
|
+
<ty-button hx-get="/fragments/edit-modal" hx-target="#modal-slot" hx-swap="innerHTML">
|
|
140
|
+
Edit
|
|
141
|
+
</ty-button>
|
|
142
|
+
|
|
143
|
+
<div id="modal-slot"></div>
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Server returns the populated modal with `open` already set:
|
|
147
|
+
```html
|
|
148
|
+
<ty-modal open>
|
|
149
|
+
<form hx-post="/api/save"
|
|
150
|
+
hx-target="#modal-slot"
|
|
151
|
+
hx-swap="innerHTML">
|
|
152
|
+
…
|
|
153
|
+
<ty-button type="submit" flavor="primary">Save</ty-button>
|
|
154
|
+
</form>
|
|
155
|
+
</ty-modal>
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
After save, server returns an empty fragment, `#modal-slot` becomes empty, modal disappears.
|
|
159
|
+
|
|
160
|
+
**Client closes on success** — listen for the `htmx:afterRequest` event on the modal:
|
|
161
|
+
|
|
162
|
+
```html
|
|
163
|
+
<ty-modal id="m" open>
|
|
164
|
+
<form hx-post="/api/save"
|
|
165
|
+
hx-on::after-request="if (event.detail.successful) document.getElementById('m').removeAttribute('open')">
|
|
166
|
+
…
|
|
167
|
+
</form>
|
|
168
|
+
</ty-modal>
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Validation feedback
|
|
172
|
+
|
|
173
|
+
`hx-target-error` (or HTMX's response-target extension) lets the server return validation errors to a specific region. Pair with `ty-input`'s `error` attribute:
|
|
174
|
+
|
|
175
|
+
```html
|
|
176
|
+
<form hx-post="/api/signup" hx-target="#result">
|
|
177
|
+
<ty-input id="email" name="email" type="email" label="Email"></ty-input>
|
|
178
|
+
<div id="result"></div>
|
|
179
|
+
</form>
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Server returns on 422:
|
|
183
|
+
```html
|
|
184
|
+
<ty-input id="email" name="email" type="email" label="Email"
|
|
185
|
+
value="not-an-email"
|
|
186
|
+
error="Enter a valid email"
|
|
187
|
+
hx-swap-oob="true"></ty-input>
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
The OOB swap replaces the input with one carrying the error message. Tyrell renders the error text and the danger colors automatically. The server owns `error`: the next response that renders the input without it clears the message.
|
|
191
|
+
|
|
192
|
+
## Reorderable lists (ty-sortable)
|
|
193
|
+
|
|
194
|
+
`ty-sortable` never moves its children. A drop (or a keyboard move) fires `ty-sortable-change` on the destination list; post `event.detail.value` and let the server render the lists in the new order. Until the swap lands, the item stays where it was dropped. Use the idiomorph extension so the swap moves the existing item nodes:
|
|
195
|
+
|
|
196
|
+
```html
|
|
197
|
+
<script src="https://cdn.jsdelivr.net/npm/idiomorph@0.7.4/dist/idiomorph-ext.min.js"></script>
|
|
198
|
+
|
|
199
|
+
<div id="board" hx-ext="morph">
|
|
200
|
+
<ty-sortable id="todo" group="board" label="To do"
|
|
201
|
+
hx-post="/board/move"
|
|
202
|
+
hx-trigger="ty-sortable-change"
|
|
203
|
+
hx-vals='js:{move: JSON.stringify(event.detail.value)}'
|
|
204
|
+
hx-target="#board"
|
|
205
|
+
hx-swap="morph:innerHTML">
|
|
206
|
+
<div id="card-12">
|
|
207
|
+
<button type="button" data-handle aria-label="Move Fix login">
|
|
208
|
+
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>
|
|
209
|
+
</button>
|
|
210
|
+
Fix login
|
|
211
|
+
</div>
|
|
212
|
+
</ty-sortable>
|
|
213
|
+
<ty-sortable id="done" group="board" label="Done" hx-post="/board/move" …>…</ty-sortable>
|
|
214
|
+
</div>
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
The server parses `move`, saves it and returns both `<ty-sortable>` lists, with the same attributes, in the stored order.
|
|
218
|
+
|
|
219
|
+
- **Key every item** with `id` (or `data-key`). The key is what `value` reports and what idiomorph uses to move the node.
|
|
220
|
+
- **`value`** is `{ key, group, source, from, to, order }`. `order` is the new key order of each list the move touched, by list id. For fractional ranking, store a rank between `value.to.prev` and `value.to.next` instead.
|
|
221
|
+
- **Refusing a move:** htmx puts `htmx-request` on the list while the request runs, and ty reads it like `aria-busy="true"`. If the response renders the old order (or the request fails and nothing is swapped), the item snaps back when the request ends. Put `hx-post` on each list, not on a wrapper, so the class lands on the list.
|
|
222
|
+
- **Touch:** a `[data-handle]` drags at once and leaves the rest of the row to scroll; give it a 44px target. Without a handle the whole item drags after a 250 ms press.
|
|
223
|
+
- `group` lets lists trade items, `accepts="[data-kind=bug]"` limits what a list takes, `data-locked` pins an item. Full API: [TY_GUIDE.md](../TY_GUIDE.md#ty-sortable).
|
|
224
|
+
|
|
225
|
+
## Common pitfalls
|
|
226
|
+
|
|
227
|
+
- **Don't put HTMX attributes on the `<ty-option>` / `<ty-tab>` / `<ty-step>` children** — they're internal slots, not interactive. Put them on `<ty-select>` / `<ty-tabs>` / `<ty-wizard>` and use `hx-trigger="change"` (`hx-trigger="ty-tab-change"` for tabs). The exception is a lazy `<ty-tab>`, which loads itself:
|
|
228
|
+
|
|
229
|
+
```html
|
|
230
|
+
<ty-tab id="reports" label="Reports" lazy
|
|
231
|
+
hx-get="/tabs/reports" hx-trigger="ty-tab-load"
|
|
232
|
+
hx-on::response-error="this.loadFailed()"
|
|
233
|
+
hx-on::send-error="this.loadFailed()"></ty-tab>
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
The response is the panel's content (`innerHTML` of the tab). A failed request shows the tab's error and Retry only through `loadFailed()`; ty-tab doesn't watch htmx events itself.
|
|
237
|
+
- **Boolean values from `ty-checkbox`** post as `"on"` (or absent) — same as native `<input type="checkbox">`. `ty-switch` follows the same rule. If you need explicit `true`/`false`, wire it via `hx-vals='js:{enabled: this.checked}'`.
|
|
238
|
+
- **`ty-select multiple` posts repeated `name=` entries** (one per selected value). Confirm your backend reads multi-value fields (Express `body-parser` does, Ring's wrap-params does, Rails' `permit(:tags => [])` does).
|
|
239
|
+
- **A swapped `ty-select` takes its selection from `value`** — `<ty-option selected>` selects nothing. With idiomorph a different `value` wins, the same one changes nothing, none clears it. A server that re-renders a select renders `value="…"` with the current selection. For dependent selects (country → city), swap the whole select, not only its options: a swap of the options alone keeps the old value. A `ty-selected-options` outside the swapped region stays on the old select: swap it too, or use idiomorph, which keeps the select.
|
|
240
|
+
- **Date format**: `ty-date-picker` posts a UTC ISO instant (date-only: when the day starts in the browser's timezone, e.g. `2026-10-15T22:00:00.000Z` for Oct 16 in Zagreb). Add `native` to post `YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm` with `with-time`, like `<input type="date">`. An empty picker posts `name=`.
|
|
241
|
+
- **Don't manually re-register components after a swap** — `customElements.define` is global, registration persists across swaps. Re-running the CDN bundle script will throw `NotSupportedError: already defined`.
|
|
242
|
+
|
|
243
|
+
## Why no wrapper package?
|
|
244
|
+
|
|
245
|
+
HTMX speaks HTML. Web Components speak HTML. There is no impedance mismatch to bridge — you're already at the same layer. Anything a wrapper would do (`hx-on`, `hx-vals`, `hx-trigger`) HTMX already gives you, and ty's form-associated internals + bubbling events do the rest.
|
|
246
|
+
|
|
247
|
+
## See also
|
|
248
|
+
|
|
249
|
+
- [TY_GUIDE.md](../TY_GUIDE.md) — universal component API
|
|
250
|
+
- [JAVASCRIPT_GUIDE.md](JAVASCRIPT_GUIDE.md) — bundlers, subpath imports, icon tree-shaking (when you outgrow the CDN script tag)
|
|
251
|
+
- [DATASTAR_TY_GUIDE.md](../DATASTAR_TY_GUIDE.md) — sibling server-driven approach using SSE + signals
|
|
252
|
+
- [CSS_GUIDE.md](../CSS_GUIDE.md) — color and surface classes
|
|
@@ -0,0 +1,388 @@
|
|
|
1
|
+
# JavaScript + Tyrell Guide
|
|
2
|
+
|
|
3
|
+
Use Tyrell web components from vanilla JavaScript and any bundler. This guide covers distribution, the side-effects model, subpath imports, icon tree-shaking, code splitting, and the SSR boundary — the substrate every framework integration sits on.
|
|
4
|
+
|
|
5
|
+
For framework-specific patterns, see [REACT_TY_GUIDE.md](./REACT_TY_GUIDE.md), [VUE_TY_GUIDE.md](./VUE_TY_GUIDE.md), and [SVELTE_TY_GUIDE.md](./SVELTE_TY_GUIDE.md).
|
|
6
|
+
|
|
7
|
+
## Two distribution channels
|
|
8
|
+
|
|
9
|
+
Tyrell ships through two channels — pick one based on your build setup, not both at once.
|
|
10
|
+
|
|
11
|
+
### CDN — zero build
|
|
12
|
+
|
|
13
|
+
```html
|
|
14
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
|
|
15
|
+
<!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
|
|
16
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
|
|
17
|
+
<script type="module" src="https://cdn.jsdelivr.net/npm/tyrell-components@latest/dist/tyrell.js"></script>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The CDN bundle (`dist/tyrell.js`) registers every component and exposes the icon registry on `window.tyIcons`. Use this for HTMX, server-rendered apps, prototypes, multi-app domains where browser cache wins, or strict no-bundler workflows.
|
|
21
|
+
|
|
22
|
+
### NPM — tree-shakeable
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install tyrell-components
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
```js
|
|
29
|
+
import 'tyrell-components/css/tyrell.css' // structure — no color tokens
|
|
30
|
+
import 'tyrell-components/css/tyrell-theme.css' // colors — auto-contrast, seed-based rebranding
|
|
31
|
+
import 'tyrell-components' // registers everything
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Use this when you have a bundler (Vite, Webpack, Rollup, esbuild, Parcel, Bun). Subpath imports let you ship only the components you use.
|
|
35
|
+
|
|
36
|
+
## How registration works
|
|
37
|
+
|
|
38
|
+
Each component file ends with the same pattern:
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
// src/components/button.ts
|
|
42
|
+
export class TyButton extends TyComponent { ... }
|
|
43
|
+
|
|
44
|
+
if (!customElements.get("ty-button")) {
|
|
45
|
+
customElements.define("ty-button", TyButton);
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`customElements.define(...)` is a **side effect** — calling it makes `<ty-button>` work in the DOM. Importing the file triggers that side effect; once registered, the component class is rarely referenced from your code (you write `<ty-button>` in HTML or JSX, not `new TyButton()`).
|
|
50
|
+
|
|
51
|
+
This matters because modern bundlers eliminate "unused" code aggressively. Tyrell's `package.json` declares the side-effectful files explicitly:
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
"sideEffects": [
|
|
55
|
+
"./lib/index.js",
|
|
56
|
+
"./lib/components/**/*.js",
|
|
57
|
+
"./dist/*.js"
|
|
58
|
+
]
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Translation: "These files do real work just by being imported — keep them in the bundle even if no exported symbols are referenced." Everything else (utils, types, icon data) is pure and freely tree-shaken.
|
|
62
|
+
|
|
63
|
+
## Subpath imports
|
|
64
|
+
|
|
65
|
+
Import only the components you use:
|
|
66
|
+
|
|
67
|
+
```js
|
|
68
|
+
import 'tyrell-components/button'
|
|
69
|
+
import 'tyrell-components/input'
|
|
70
|
+
import 'tyrell-components/dropdown'
|
|
71
|
+
import 'tyrell-components/option' // dropdown children
|
|
72
|
+
import 'tyrell-components/modal'
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Available subpaths (each registers exactly one custom element):
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
button input textarea checkbox
|
|
79
|
+
dropdown option multiselect tag
|
|
80
|
+
modal popup tooltip
|
|
81
|
+
calendar calendar-month calendar-navigation date-picker
|
|
82
|
+
tabs tab wizard
|
|
83
|
+
icon copy file-upload sortable
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Subpath imports compose with `import('...')` for code splitting:
|
|
87
|
+
|
|
88
|
+
```js
|
|
89
|
+
// Calendar/date-picker is the heaviest component — defer until needed
|
|
90
|
+
async function openDatePicker() {
|
|
91
|
+
await import('tyrell-components/date-picker')
|
|
92
|
+
document.getElementById('picker').showModal()
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Webpack, Rollup, Vite, esbuild, and Parcel all honor subpath exports. Bun and Deno also work via the standard `exports` field.
|
|
97
|
+
|
|
98
|
+
## CSS distribution
|
|
99
|
+
|
|
100
|
+
Two files, both required: `css/tyrell.css` (structure — spacing, typography, shadows, component CSS; zero color tokens) and `css/tyrell-theme.css` (every color, via an OKLCH engine — auto-contrast, seed-based rebranding, themes). Load `tyrell-theme.css` after `tyrell.css`. Don't want the theme engine? Swap it for `css/tyrell-colors-static.css` — a plain hardcoded hex fallback, no theming API. Two consumption modes — pick whichever fits your build:
|
|
101
|
+
|
|
102
|
+
```js
|
|
103
|
+
// Bundler picks it up (Vite, Webpack, Next.js, etc.)
|
|
104
|
+
import 'tyrell-components/css/tyrell.css'
|
|
105
|
+
import 'tyrell-components/css/tyrell-theme.css'
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
```html
|
|
109
|
+
<!-- Or load directly -->
|
|
110
|
+
<link rel="stylesheet" href="/node_modules/tyrell-components/css/tyrell.css">
|
|
111
|
+
<link rel="stylesheet" href="/node_modules/tyrell-components/css/tyrell-theme.css">
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Neither file is split per-component. Both are small enough that splitting would cost more in HTTP overhead than it saves, and the design tokens (colors, surfaces, text classes) need to be globally available regardless of which components are loaded.
|
|
115
|
+
|
|
116
|
+
## Icons
|
|
117
|
+
|
|
118
|
+
`<ty-icon name="…">` is a runtime lookup, so the bundler can't see which icons you use. Import them by name and register them; everything you don't import is dropped.
|
|
119
|
+
|
|
120
|
+
```js
|
|
121
|
+
import { registerIcons } from 'tyrell-components/icons/registry'
|
|
122
|
+
import { check, chevronDown } from 'tyrell-components/icons/lucide'
|
|
123
|
+
|
|
124
|
+
registerIcons({ check, 'action-down': chevronDown }) // the key is the name
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Avoid `import * as lucide` + `registerIcons(lucide)`: it ships the whole set. On the CDN build, use `window.tyIcons.register`.
|
|
128
|
+
|
|
129
|
+
Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-javascript).
|
|
130
|
+
|
|
131
|
+
## Vanilla JS usage
|
|
132
|
+
|
|
133
|
+
Once components are registered, write plain HTML and listen for events:
|
|
134
|
+
|
|
135
|
+
```html
|
|
136
|
+
<ty-input id="email" type="email" label="Email"></ty-input>
|
|
137
|
+
<ty-button id="submit" flavor="primary">Submit</ty-button>
|
|
138
|
+
|
|
139
|
+
<script>
|
|
140
|
+
const email = document.getElementById('email')
|
|
141
|
+
const submit = document.getElementById('submit')
|
|
142
|
+
|
|
143
|
+
email.addEventListener('change', (e) => {
|
|
144
|
+
console.log('email:', e.detail.value)
|
|
145
|
+
})
|
|
146
|
+
|
|
147
|
+
submit.addEventListener('click', () => {
|
|
148
|
+
if (email.value) {
|
|
149
|
+
// submit form
|
|
150
|
+
}
|
|
151
|
+
})
|
|
152
|
+
</script>
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Three things to remember:
|
|
156
|
+
|
|
157
|
+
1. **Event payload lives on `event.detail`**, not `event` directly. Access values via `event.detail.value`.
|
|
158
|
+
2. **Properties vs attributes** — set primitives via attributes, set complex values (arrays, objects, functions) via JS properties:
|
|
159
|
+
```js
|
|
160
|
+
el.setAttribute('label', 'Email') // string attribute
|
|
161
|
+
el.disabled = true // boolean property
|
|
162
|
+
el.value = ['a', 'b', 'c'] // array property (multiselect)
|
|
163
|
+
```
|
|
164
|
+
3. **Wait for definition before scripting** if you call methods immediately:
|
|
165
|
+
```js
|
|
166
|
+
await customElements.whenDefined('ty-modal')
|
|
167
|
+
document.querySelector('ty-modal').show()
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## Reorderable lists (ty-sortable)
|
|
171
|
+
|
|
172
|
+
`ty-sortable` never moves its children. A drop (or a keyboard move) fires `ty-sortable-change` on the destination list, and the list holds the result on screen until your code puts the items in the new order. Key each item with `data-key` (or `id`):
|
|
173
|
+
|
|
174
|
+
```html
|
|
175
|
+
<ty-sortable id="todo" group="board" label="To do">
|
|
176
|
+
<div data-key="a">
|
|
177
|
+
<button type="button" data-handle aria-label="Move Design review">
|
|
178
|
+
<ty-icon name="grip-vertical"></ty-icon>
|
|
179
|
+
</button>
|
|
180
|
+
Design review
|
|
181
|
+
</div>
|
|
182
|
+
</ty-sortable>
|
|
183
|
+
<ty-sortable id="done" group="board" label="Done"></ty-sortable>
|
|
184
|
+
|
|
185
|
+
<script>
|
|
186
|
+
document.addEventListener('ty-sortable-change', async (e) => {
|
|
187
|
+
const { value, fromContainer, toContainer } = e.detail
|
|
188
|
+
const lists = [fromContainer, toContainer]
|
|
189
|
+
lists.forEach((l) => l.setAttribute('aria-busy', 'true'))
|
|
190
|
+
try {
|
|
191
|
+
await save(value)
|
|
192
|
+
// value.order: the new key order of each touched list, by list id
|
|
193
|
+
for (const [id, keys] of Object.entries(value.order)) {
|
|
194
|
+
const list = document.getElementById(id)
|
|
195
|
+
list.replaceChildren(...keys.map((k) => document.querySelector(`[data-key="${k}"]`)))
|
|
196
|
+
}
|
|
197
|
+
} finally {
|
|
198
|
+
lists.forEach((l) => l.removeAttribute('aria-busy')) // order unchanged: the item snaps back
|
|
199
|
+
}
|
|
200
|
+
})
|
|
201
|
+
</script>
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
- `value` is `{ key, group, source, from, to, order }`; `from` / `to` are `{ list, index, prev, next }`. For fractional ranking, save a rank between `value.to.prev` and `value.to.next` instead of the whole order.
|
|
205
|
+
- `aria-busy="true"` while saving makes a refused save snap back as soon as it is removed. Without it, call `toContainer.settle('rejected')`, or `e.preventDefault()` to reject at once. With no busy signal and no render, the hold ends after `hold-timeout` (5000 ms).
|
|
206
|
+
- On touch, a `[data-handle]` drags at once and leaves the rest of the row to scroll; give it a 44px target. Without a handle the whole item drags after a 250 ms press.
|
|
207
|
+
- `list.move('a', { to: 'done', index: 0 })` moves without a pointer and resolves `'accepted'`, `'rejected'`, `'reconciled'` or `'unknown'`. Full API: [TY_GUIDE.md](../TY_GUIDE.md#ty-sortable).
|
|
208
|
+
|
|
209
|
+
## Bundler notes
|
|
210
|
+
|
|
211
|
+
### Vite
|
|
212
|
+
|
|
213
|
+
Works out of the box. Subpath imports, CSS imports, and `import()` splits all behave correctly:
|
|
214
|
+
|
|
215
|
+
```js
|
|
216
|
+
// vite.config.js — no special config required
|
|
217
|
+
export default {
|
|
218
|
+
// ...
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
For Vue 3 inside Vite, see [VUE_TY_GUIDE.md](./VUE_TY_GUIDE.md).
|
|
223
|
+
|
|
224
|
+
### Webpack 5
|
|
225
|
+
|
|
226
|
+
Honors `sideEffects` and subpath exports. If you've manually overridden `sideEffects: false` for the project, you need to allow Tyrell's modules:
|
|
227
|
+
|
|
228
|
+
```js
|
|
229
|
+
// webpack.config.js
|
|
230
|
+
module.exports = {
|
|
231
|
+
module: {
|
|
232
|
+
rules: [{
|
|
233
|
+
test: /\.js$/,
|
|
234
|
+
// do NOT mark tyrell-components as side-effect-free
|
|
235
|
+
sideEffects: (resourcePath) => !resourcePath.includes('tyrell-components'),
|
|
236
|
+
}]
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### Rollup
|
|
242
|
+
|
|
243
|
+
Use `@rollup/plugin-node-resolve` with `exportConditions: ['import']`. `sideEffects` is honored automatically.
|
|
244
|
+
|
|
245
|
+
### esbuild / Bun
|
|
246
|
+
|
|
247
|
+
Both honor `exports` and `sideEffects`. No configuration needed.
|
|
248
|
+
|
|
249
|
+
### Parcel
|
|
250
|
+
|
|
251
|
+
Works automatically. Parcel respects `sideEffects` and resolves subpath exports.
|
|
252
|
+
|
|
253
|
+
## SSR and the registration boundary
|
|
254
|
+
|
|
255
|
+
`customElements.define` requires a browser. On Node.js, `customElements` is undefined. Server-side rendering tools must either:
|
|
256
|
+
|
|
257
|
+
- **Skip the registration import on the server**, importing it only in the client boundary, or
|
|
258
|
+
- **Render `<ty-*>` tags as opaque strings on the server** and let registration hydrate them on the client.
|
|
259
|
+
|
|
260
|
+
Most frameworks already handle this correctly when you import inside a client-only context. Specifics:
|
|
261
|
+
|
|
262
|
+
- **Next.js (App Router)** — Add `'use client'` to any file that imports `tyrell-components/...`, or perform the import inside a `useEffect` for purely client-side registration. See REACT_TY_GUIDE.md § Next.js Integration.
|
|
263
|
+
- **Nuxt 3** — Wrap registration in `if (process.client)` or place imports inside `<ClientOnly>` boundaries / `onMounted` hooks.
|
|
264
|
+
- **SvelteKit** — Use `import { browser } from '$app/environment'` and guard with `if (browser)`, or place imports inside `onMount`.
|
|
265
|
+
- **Astro** — Use `client:load` / `client:idle` directives on islands that contain `<ty-*>` elements; do not import `tyrell-components` from `.astro` files.
|
|
266
|
+
- **Remix** — Import inside `useEffect` or wrap with `ClientOnly` from `remix-utils`.
|
|
267
|
+
|
|
268
|
+
What you should **not** do is render `<ty-*>` tags on the server expecting them to "work" — they'll render as inert HTML until registration runs on the client. That's usually fine (graceful upgrade), but means initial paint shows unstyled content. Either:
|
|
269
|
+
|
|
270
|
+
- Accept the brief flash (acceptable for most apps), or
|
|
271
|
+
- Wrap critical UI with a skeleton until `customElements.whenDefined()` resolves, or
|
|
272
|
+
- Use Declarative Shadow DOM for SSR-friendly initial markup (advanced; not currently supported by Tyrell out of the box).
|
|
273
|
+
|
|
274
|
+
## Bundle size — what to expect
|
|
275
|
+
|
|
276
|
+
Approximate sizes for the most common configurations:
|
|
277
|
+
|
|
278
|
+
| Configuration | Minified |
|
|
279
|
+
|---|---:|
|
|
280
|
+
| Single primitive (`button`, `input`, `tag`) | 3–8 KB |
|
|
281
|
+
| Dropdown + option | ~15 KB |
|
|
282
|
+
| Modal + popup + tooltip | ~20 KB |
|
|
283
|
+
| Calendar + date-picker | ~25 KB |
|
|
284
|
+
| All components (full bundle) | ~150–200 KB |
|
|
285
|
+
| Per-icon SVG | 300–600 bytes |
|
|
286
|
+
| All lucide icons (mistake) | ~600 KB |
|
|
287
|
+
|
|
288
|
+
Components are bounded — even importing all 23 caps at ~200 KB. Icons are unbounded if you namespace-import a family. **The icon import pattern matters more than the component import pattern.**
|
|
289
|
+
|
|
290
|
+
## Code-splitting patterns
|
|
291
|
+
|
|
292
|
+
### Per-route splits
|
|
293
|
+
|
|
294
|
+
```js
|
|
295
|
+
// Defer calendar to the page that uses it
|
|
296
|
+
const DatePickerPage = () => import('./pages/date-picker.js')
|
|
297
|
+
const router = {
|
|
298
|
+
'/booking': DatePickerPage,
|
|
299
|
+
}
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
The dynamic `import()` triggers the route's components to register on demand.
|
|
303
|
+
|
|
304
|
+
### Component-level splits
|
|
305
|
+
|
|
306
|
+
```js
|
|
307
|
+
async function showModal() {
|
|
308
|
+
// Modal not registered yet
|
|
309
|
+
if (!customElements.get('ty-modal')) {
|
|
310
|
+
await import('tyrell-components/modal')
|
|
311
|
+
}
|
|
312
|
+
document.querySelector('ty-modal').show()
|
|
313
|
+
}
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### Icon-bundle splits
|
|
317
|
+
|
|
318
|
+
For very icon-heavy apps, split icon registration by feature:
|
|
319
|
+
|
|
320
|
+
```js
|
|
321
|
+
// chart-icons.js
|
|
322
|
+
import { registerIcons } from 'tyrell-components/icons/registry'
|
|
323
|
+
import { trendingUp, trendingDown, barChart } from 'tyrell-components/icons/lucide'
|
|
324
|
+
export function registerChartIcons() {
|
|
325
|
+
registerIcons({ trendingUp, trendingDown, barChart })
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
// chart.js
|
|
329
|
+
import { registerChartIcons } from './chart-icons.js'
|
|
330
|
+
registerChartIcons()
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
Combined with route-level splits, only the route that renders the chart pays the cost.
|
|
334
|
+
|
|
335
|
+
## Performance — startup ordering
|
|
336
|
+
|
|
337
|
+
If you load Tyrell via NPM and have hundreds of `<ty-*>` elements in initial HTML:
|
|
338
|
+
|
|
339
|
+
```js
|
|
340
|
+
// main.js — register first, paint second
|
|
341
|
+
import 'tyrell-components/css/tyrell.css'
|
|
342
|
+
import 'tyrell-components/css/tyrell-theme.css'
|
|
343
|
+
import 'tyrell-components'
|
|
344
|
+
|
|
345
|
+
import { registerIcons } from 'tyrell-components/icons/registry'
|
|
346
|
+
import { check, x } from 'tyrell-components/icons/lucide'
|
|
347
|
+
registerIcons({ check, x })
|
|
348
|
+
|
|
349
|
+
// Then mount your app
|
|
350
|
+
mountApp()
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
Registering before mounting avoids a flash of unregistered elements. With code splitting, accept the flash for offscreen content but prefetch eagerly for above-the-fold UI.
|
|
354
|
+
|
|
355
|
+
## TypeScript
|
|
356
|
+
|
|
357
|
+
The package ships `.d.ts` files for the component classes:
|
|
358
|
+
|
|
359
|
+
```ts
|
|
360
|
+
import type { TyButton } from 'tyrell-components/button'
|
|
361
|
+
|
|
362
|
+
const btn = document.querySelector('ty-button') as TyButton
|
|
363
|
+
btn.disabled = true
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
For framework-specific JSX types, see the framework guides. Plain TypeScript with `lib.dom.d.ts` does not know about `<ty-button>` — you'll need either the React wrapper types, the Vue/Svelte template type registration, or a manual `HTMLElementTagNameMap` augmentation.
|
|
367
|
+
|
|
368
|
+
## Quick reference — what to import where
|
|
369
|
+
|
|
370
|
+
| Goal | Import |
|
|
371
|
+
|---|---|
|
|
372
|
+
| Register everything | `import 'tyrell-components'` |
|
|
373
|
+
| Register one component | `import 'tyrell-components/button'` |
|
|
374
|
+
| Multiple components | One import line per component |
|
|
375
|
+
| Stylesheet — structure (bundler) | `import 'tyrell-components/css/tyrell.css'` |
|
|
376
|
+
| Stylesheet — colors (bundler) | `import 'tyrell-components/css/tyrell-theme.css'` |
|
|
377
|
+
| Icon registry function | `import { registerIcons } from 'tyrell-components/icons/registry'` |
|
|
378
|
+
| Specific icons | `import { check, heart } from 'tyrell-components/icons/lucide'` |
|
|
379
|
+
| Component class (typing) | `import type { TyButton } from 'tyrell-components/button'` |
|
|
380
|
+
|
|
381
|
+
## See also
|
|
382
|
+
|
|
383
|
+
- [TY_GUIDE.md](../TY_GUIDE.md) — universal HTML/JS API reference
|
|
384
|
+
- [CSS_GUIDE.md](../CSS_GUIDE.md) — design system (colors, surfaces, text)
|
|
385
|
+
- [REACT_TY_GUIDE.md](./REACT_TY_GUIDE.md) — React + `tyrell-react`
|
|
386
|
+
- [VUE_TY_GUIDE.md](./VUE_TY_GUIDE.md) — Vue 3 / Nuxt
|
|
387
|
+
- [SVELTE_TY_GUIDE.md](./SVELTE_TY_GUIDE.md) — Svelte 5 / SvelteKit
|
|
388
|
+
- [TYCOMPONENT_GUIDE.md](./TYCOMPONENT_GUIDE.md) — building custom components on `TyComponent`
|