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,657 @@
|
|
|
1
|
+
# Datastar + Tyrell Guide
|
|
2
|
+
|
|
3
|
+
Use Tyrell web components with Datastar for reactive server-driven UIs. No JavaScript framework needed — just HTML attributes, SSE, and your backend of choice.
|
|
4
|
+
|
|
5
|
+
## Why they fit together
|
|
6
|
+
|
|
7
|
+
Datastar and Tyrell are built around the same philosophy: **standard HTML attributes, standard DOM events, standard form association**. There is no adapter layer because none is needed.
|
|
8
|
+
|
|
9
|
+
| What Datastar does | How Tyrell meets it |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `data-bind="x"` — two-way bind to a form element | Tyrell form components implement `ElementInternals` — they behave as native inputs for `data-bind` |
|
|
12
|
+
| `data-on:change="..."` — listen to any DOM event | Tyrell emits standard `CustomEvent` on `change`; `evt.detail.value` is the payload |
|
|
13
|
+
| `data-attr:flavor="$x"` — bind any HTML attribute to a signal | Tyrell attributes are plain HTML attributes — reactive binding just works |
|
|
14
|
+
| `@post('/api/...')` — send signals to server | Server reads signals as JSON, returns SSE with fresh Tyrell HTML |
|
|
15
|
+
| `patch-elements` — morph DOM to new HTML | Server renders Tyrell hiccup; Datastar morphs it in place |
|
|
16
|
+
|
|
17
|
+
The result: **a full interactive UI driven entirely by server-rendered HTML**. The client runs Datastar (one script tag) and Tyrell (one script tag). Your server emits HTML strings. No build step, no component tree, no hydration.
|
|
18
|
+
|
|
19
|
+
### PocketLedger — a real app
|
|
20
|
+
|
|
21
|
+
[`examples/pocketledger/`](../examples/pocketledger/) is a production-quality expense tracker built with this exact stack: **Clojure + Datastar + Tyrell + Tauri** (desktop/Android). It shows tabs, wizard-style setup, forms with currency input, date picker, multi-select categories, scroll container for transaction history, dark mode toggle, and full SSE-driven CRUD — all in ~600 lines of Clojure with no client-side framework.
|
|
22
|
+
|
|
23
|
+
### Go examples — every component in one place
|
|
24
|
+
|
|
25
|
+
Two minimal single-file Go servers (standard library only, no external Go deps) that exercise the full primitive surface against the latest TC build:
|
|
26
|
+
|
|
27
|
+
- [`examples/datastar-go/`](../examples/datastar-go/) — support-ticket form. Covers `ty-input`, `ty-textarea`, `ty-select` + `ty-option`, `ty-radio-group`, `ty-date-picker`, `ty-switch`, `ty-checkbox`, `ty-button`, `ty-modal`, `ty-scroll-container`, `ty-icon`, plus debounced server-side validation and a keep-alive SSE feed.
|
|
28
|
+
- [`examples/datastar-go-workspace/`](../examples/datastar-go-workspace/) — workspace dashboard covering everything the first example doesn't: `ty-tabs`, `ty-select` (`multiple`) + `ty-selected-options` + `ty-tag`, `ty-copy`, `ty-file-upload`, `ty-calendar`, `ty-wizard` + `ty-step`, `ty-popup`, `ty-tooltip`, `ty-resize-observer`, with server-driven wizard transitions and SSE upload progress.
|
|
29
|
+
|
|
30
|
+
Both pin the CDN to `tyrell-components@tc` (the dist tag that follows the latest TC build) so they track the version under active development. They also demonstrate **server-rendered icons** — inline `<svg>` slotted into `<ty-icon>` so icons paint with zero client-side JS.
|
|
31
|
+
|
|
32
|
+
## Setup
|
|
33
|
+
|
|
34
|
+
### HTML Head
|
|
35
|
+
|
|
36
|
+
```html
|
|
37
|
+
<!-- Tyrell CSS and Components -->
|
|
38
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
|
|
39
|
+
<!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
|
|
40
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
|
|
41
|
+
<script type="module" src="https://cdn.jsdelivr.net/npm/tyrell-components@latest/dist/tyrell.js"></script>
|
|
42
|
+
|
|
43
|
+
<!-- Datastar -->
|
|
44
|
+
<script type="module" src="https://cdn.jsdelivr.net/gh/starfederation/datastar@v1.0.0-RC.8/bundles/datastar.js"></script>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Two-Way Binding
|
|
48
|
+
|
|
49
|
+
Use `data-bind` for form inputs — it handles wiring automatically:
|
|
50
|
+
|
|
51
|
+
```html
|
|
52
|
+
<div data-signals="{name: '', email: '', country: '', tags: ''}">
|
|
53
|
+
|
|
54
|
+
<ty-input data-bind="name" label="Name" placeholder="Your name"></ty-input>
|
|
55
|
+
|
|
56
|
+
<ty-input data-bind="email" label="Email" type="email"></ty-input>
|
|
57
|
+
|
|
58
|
+
<ty-select data-bind="country" label="Country" placeholder="Select...">
|
|
59
|
+
<ty-option value="us">United States</ty-option>
|
|
60
|
+
<ty-option value="de">Germany</ty-option>
|
|
61
|
+
</ty-select>
|
|
62
|
+
|
|
63
|
+
<!-- Multi-select: add `multiple`. $tags holds the comma-joined value
|
|
64
|
+
("frontend,ops"); evt.detail.values has it as an array. -->
|
|
65
|
+
<ty-select data-bind="tags" multiple label="Tags" placeholder="Select tags...">
|
|
66
|
+
<ty-option value="frontend">Frontend</ty-option>
|
|
67
|
+
<ty-option value="backend">Backend</ty-option>
|
|
68
|
+
<ty-option value="ops">Ops</ty-option>
|
|
69
|
+
</ty-select>
|
|
70
|
+
|
|
71
|
+
<ty-button flavor="primary" data-on:click="@post('/api/submit')">
|
|
72
|
+
Submit
|
|
73
|
+
</ty-button>
|
|
74
|
+
|
|
75
|
+
</div>
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### ty-select and patch-elements
|
|
79
|
+
|
|
80
|
+
The select's `value` is its selection; `<ty-option selected>` selects nothing. When a patch reaches a select, the server's `value` decides: a different one wins, the same one changes nothing, none clears the selection. So a server that patches a region containing a select renders `value="…"` with the current selection:
|
|
81
|
+
|
|
82
|
+
```html
|
|
83
|
+
<ty-select id="skills" multiple data-bind="skills" value="clj,rs">
|
|
84
|
+
<ty-option value="clj">Clojure</ty-option>
|
|
85
|
+
<ty-option value="rs">Rust</ty-option>
|
|
86
|
+
</ty-select>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
A patched `value` changes the select but not the `data-bind` signal: no `change` fires, as with a native input. To change a bound selection from the server, patch the signal (`datastar-patch-signals`).
|
|
90
|
+
|
|
91
|
+
When the server keeps the selection (hundreds of values, a remote list), use `external-selection`: the server marks the options it sends `selected`, a pick fires `change` with `evt.detail.value` and `evt.detail.selected` and changes nothing, and the server patches the marked options back. The select holds no value and submits nothing.
|
|
92
|
+
|
|
93
|
+
```html
|
|
94
|
+
<ty-select id="robots" multiple external-selection external-search
|
|
95
|
+
data-on:search="@get('/robots?q=' + evt.detail.query)"
|
|
96
|
+
data-on:change="@post('/robots/pick?id=' + evt.detail.value + '&on=' + evt.detail.selected)">
|
|
97
|
+
<ty-option value="r1" selected>Rob Roy</ty-option>
|
|
98
|
+
</ty-select>
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Slots
|
|
102
|
+
|
|
103
|
+
Use `slot="start"` and `slot="end"` for icons inside buttons, inputs, and tags:
|
|
104
|
+
|
|
105
|
+
```html
|
|
106
|
+
<!-- Button with start icon -->
|
|
107
|
+
<ty-button flavor="primary">
|
|
108
|
+
<ty-icon slot="start" name="save" size="sm"></ty-icon>
|
|
109
|
+
Save
|
|
110
|
+
</ty-button>
|
|
111
|
+
|
|
112
|
+
<!-- Button with end icon -->
|
|
113
|
+
<ty-button flavor="neutral">
|
|
114
|
+
Next
|
|
115
|
+
<ty-icon slot="end" name="chevron-right" size="sm"></ty-icon>
|
|
116
|
+
</ty-button>
|
|
117
|
+
|
|
118
|
+
<!-- Input with icon -->
|
|
119
|
+
<ty-input type="currency" currency="EUR" label="Price" data-bind="amount">
|
|
120
|
+
<ty-icon slot="start" name="euro"></ty-icon>
|
|
121
|
+
</ty-input>
|
|
122
|
+
|
|
123
|
+
<!-- Tag with icon -->
|
|
124
|
+
<ty-tag flavor="primary">
|
|
125
|
+
<ty-icon slot="start" name="star" size="sm"></ty-icon>
|
|
126
|
+
Featured
|
|
127
|
+
</ty-tag>
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Event Binding
|
|
131
|
+
|
|
132
|
+
### Standard Events
|
|
133
|
+
|
|
134
|
+
```html
|
|
135
|
+
<!-- Button click -->
|
|
136
|
+
<ty-button data-on:click="@post('/api/action')">Do it</ty-button>
|
|
137
|
+
|
|
138
|
+
<!-- Update signal on change -->
|
|
139
|
+
<ty-select data-on:change="$currency = evt.detail.value">
|
|
140
|
+
<ty-option value="USD">$ USD</ty-option>
|
|
141
|
+
<ty-option value="EUR">EUR</ty-option>
|
|
142
|
+
</ty-select>
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Manual Event Binding
|
|
146
|
+
|
|
147
|
+
When you need custom logic beyond simple binding:
|
|
148
|
+
|
|
149
|
+
```html
|
|
150
|
+
<ty-input data-on:change="$username = evt.detail.value; $dirty = true"></ty-input>
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Always access Tyrell values through `evt.detail.value`.
|
|
154
|
+
|
|
155
|
+
## Dynamic Attributes
|
|
156
|
+
|
|
157
|
+
Bind Tyrell component attributes to signal values:
|
|
158
|
+
|
|
159
|
+
```html
|
|
160
|
+
<!-- Toggle tag flavor based on state -->
|
|
161
|
+
<ty-tag
|
|
162
|
+
data-attr:flavor="$txType === 'expense' ? 'danger' : 'success'"
|
|
163
|
+
data-on:click="$txType = 'expense'">
|
|
164
|
+
Expense
|
|
165
|
+
</ty-tag>
|
|
166
|
+
|
|
167
|
+
<!-- Set active tab from signal.
|
|
168
|
+
ty-tabs dispatches `ty-tab-change` (not `change`); detail.activeId is the new id. -->
|
|
169
|
+
<ty-tabs data-attr:active="$activeTab"
|
|
170
|
+
data-on:ty-tab-change="$activeTab = evt.detail.activeId">
|
|
171
|
+
<ty-tab id="overview" label="Overview">...</ty-tab>
|
|
172
|
+
<ty-tab id="settings" label="Settings">...</ty-tab>
|
|
173
|
+
</ty-tabs>
|
|
174
|
+
<!-- Patching this ty-tabs keeps the user's tab: no data-preserve-attr needed.
|
|
175
|
+
$activeTab wins over any `active` the patch carries; to switch tabs
|
|
176
|
+
from the server, patch the signal. Without data-attr, a patch that
|
|
177
|
+
sends `active` switches to it, so render the current tab or leave it out. -->
|
|
178
|
+
|
|
179
|
+
<!-- Lazy tab: loads when shown (not as the tab shown at page load: render
|
|
180
|
+
that one's content with the page). The response patches #reports (same
|
|
181
|
+
attributes, plus content). Datastar reports fetch errors on document,
|
|
182
|
+
so the tab picks out its own and calls loadFailed() for error + Retry.
|
|
183
|
+
A network failure reaches 'retries-failed' only after Datastar's retries
|
|
184
|
+
(10, about 2.5 minutes); @get('/tabs/reports', {retryMaxCount: 2}) gives up sooner. -->
|
|
185
|
+
<ty-tab id="reports" label="Reports" lazy
|
|
186
|
+
data-on:ty-tab-load="@get('/tabs/reports')"
|
|
187
|
+
data-on:datastar-fetch="evt.detail.el === el && ['error', 'retries-failed'].includes(evt.detail.type) && el.loadFailed()">
|
|
188
|
+
</ty-tab>
|
|
189
|
+
|
|
190
|
+
<!-- Conditional wizard step -->
|
|
191
|
+
<ty-wizard data-attr:active="$wizardStep"
|
|
192
|
+
data-attr:completed="$wizardCompleted">
|
|
193
|
+
<ty-step id="welcome" label="Welcome">...</ty-step>
|
|
194
|
+
<ty-step id="budget" label="Budget">...</ty-step>
|
|
195
|
+
</ty-wizard>
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Conditional Visibility
|
|
199
|
+
|
|
200
|
+
```html
|
|
201
|
+
<div data-show="!$setupComplete">
|
|
202
|
+
<ty-input data-bind="userName" label="Your name"></ty-input>
|
|
203
|
+
<ty-button data-on:click="$setupComplete = true">Continue</ty-button>
|
|
204
|
+
</div>
|
|
205
|
+
|
|
206
|
+
<div data-show="$setupComplete">
|
|
207
|
+
<p data-text="'Welcome, ' + $userName"></p>
|
|
208
|
+
</div>
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## Server-Side: SSE Responses
|
|
212
|
+
|
|
213
|
+
Datastar communicates with your backend through Server-Sent Events.
|
|
214
|
+
|
|
215
|
+
### Patch Elements (Update DOM)
|
|
216
|
+
|
|
217
|
+
```
|
|
218
|
+
event: datastar-patch-elements
|
|
219
|
+
data: selector #dashboard
|
|
220
|
+
data: mode innerHTML
|
|
221
|
+
data: elements <div id="dashboard"><h2>Updated!</h2></div>
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Field errors follow the patch too: a patched field renders its `error="…"`, and a patch that renders it without `error` clears the message. With `data-attr:error="$errors.email"` the signal owns it instead.
|
|
225
|
+
|
|
226
|
+
### Patch Signals (Update State)
|
|
227
|
+
|
|
228
|
+
```
|
|
229
|
+
event: datastar-patch-signals
|
|
230
|
+
data: signals {"txDesc":"","txAmount":"","txDate":""}
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
### Combined Response
|
|
234
|
+
|
|
235
|
+
```
|
|
236
|
+
event: datastar-patch-elements
|
|
237
|
+
data: selector #transaction-list
|
|
238
|
+
data: mode innerHTML
|
|
239
|
+
data: elements <div id="transaction-list">...</div>
|
|
240
|
+
|
|
241
|
+
event: datastar-patch-signals
|
|
242
|
+
data: signals {"txDesc":"","txAmount":"","txCategory":"","txDate":""}
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
## Clojure Backend Example
|
|
246
|
+
|
|
247
|
+
### Parse Incoming Signals
|
|
248
|
+
|
|
249
|
+
```clojure
|
|
250
|
+
(defn parse-signals
|
|
251
|
+
"Extract Datastar signals from request.
|
|
252
|
+
GET -> query param, POST -> body."
|
|
253
|
+
[request]
|
|
254
|
+
(let [raw (or (get-in request [:params :datastar])
|
|
255
|
+
(when-let [body (:body request)]
|
|
256
|
+
(if (string? body) body (slurp body))))]
|
|
257
|
+
(when (and raw (not (str/blank? raw)))
|
|
258
|
+
(json/read-str raw :key-fn keyword))))
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
### Send SSE Responses
|
|
262
|
+
|
|
263
|
+
```clojure
|
|
264
|
+
(defn patch-elements [& fragments]
|
|
265
|
+
(str "event: datastar-patch-elements\n"
|
|
266
|
+
"data: mode innerHTML\n"
|
|
267
|
+
"data: elements " (render-html fragments) "\n\n"))
|
|
268
|
+
|
|
269
|
+
(defn patch-signals [signals]
|
|
270
|
+
(str "event: datastar-patch-signals\n"
|
|
271
|
+
"data: signals " (json/write-str signals) "\n\n"))
|
|
272
|
+
|
|
273
|
+
(defn sse-response [& events]
|
|
274
|
+
{:status 200
|
|
275
|
+
:headers {"Content-Type" "text/event-stream"
|
|
276
|
+
"Cache-Control" "no-cache"}
|
|
277
|
+
:body (apply str events)})
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
### Form Handler
|
|
281
|
+
|
|
282
|
+
```clojure
|
|
283
|
+
(defn add-transaction [request]
|
|
284
|
+
(let [{:keys [txDesc txAmount txType]} (parse-signals request)]
|
|
285
|
+
(if (or (empty? txDesc) (nil? txAmount))
|
|
286
|
+
(sse-response
|
|
287
|
+
(patch-elements
|
|
288
|
+
[:div#result.ty-bg-danger-.p-3.rounded-lg.border.ty-border-danger
|
|
289
|
+
[:p.ty-text-danger "Please fill in all fields."]]))
|
|
290
|
+
(do
|
|
291
|
+
(save-transaction! {:desc txDesc :amount txAmount :type txType})
|
|
292
|
+
(sse-response
|
|
293
|
+
(patch-elements (transaction-list-fragment))
|
|
294
|
+
(patch-elements (summary-fragment))
|
|
295
|
+
(patch-signals {:txDesc "" :txAmount "" :txDate ""}))))))
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
### Middleware
|
|
299
|
+
|
|
300
|
+
Pre-read the body before Ring's `wrap-params` consumes it:
|
|
301
|
+
|
|
302
|
+
```clojure
|
|
303
|
+
(defn wrap-slurp-body
|
|
304
|
+
"Capture POST body as string for Datastar signal parsing."
|
|
305
|
+
[handler]
|
|
306
|
+
(fn [request]
|
|
307
|
+
(let [body (:body request)
|
|
308
|
+
body-str (when body
|
|
309
|
+
(if (string? body) body
|
|
310
|
+
(let [s (slurp body)]
|
|
311
|
+
(when-not (empty? s) s))))]
|
|
312
|
+
(handler (assoc request :body body-str)))))
|
|
313
|
+
|
|
314
|
+
(def app
|
|
315
|
+
(-> handler
|
|
316
|
+
wrap-slurp-body
|
|
317
|
+
wrap-params
|
|
318
|
+
wrap-keyword-params))
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
## More form controls
|
|
322
|
+
|
|
323
|
+
### ty-textarea
|
|
324
|
+
|
|
325
|
+
```html
|
|
326
|
+
<div data-signals="{notes: ''}">
|
|
327
|
+
<ty-textarea
|
|
328
|
+
data-bind="notes"
|
|
329
|
+
label="Notes"
|
|
330
|
+
placeholder="Any additional notes..."
|
|
331
|
+
rows="4"
|
|
332
|
+
max-height="200px"
|
|
333
|
+
></ty-textarea>
|
|
334
|
+
</div>
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
`data-bind` wires the `change` event automatically. Attrs: `rows`, `min-height`, `max-height`, `resize`.
|
|
338
|
+
|
|
339
|
+
### ty-checkbox and ty-switch
|
|
340
|
+
|
|
341
|
+
Wrap in `<label>` to make the text clickable. **Don't use `data-bind` here:** on a custom element it binds `value`, not `checked`, so the box ignores the signal and the signal gets the strings `"true"`/`"false"`. Mirror the signal with `data-attr:checked` and write it back from `evt.detail.checked`, which keeps both directions working (a server patch to `$agreed` checks the box):
|
|
342
|
+
|
|
343
|
+
```html
|
|
344
|
+
<div data-signals="{agreed: false, darkMode: false}">
|
|
345
|
+
|
|
346
|
+
<label class="flex items-center gap-2">
|
|
347
|
+
<ty-checkbox
|
|
348
|
+
data-attr:checked="$agreed"
|
|
349
|
+
data-on:change="$agreed = evt.detail.checked"
|
|
350
|
+
></ty-checkbox>
|
|
351
|
+
I agree to the terms
|
|
352
|
+
</label>
|
|
353
|
+
|
|
354
|
+
<label class="flex items-center gap-2">
|
|
355
|
+
<ty-switch
|
|
356
|
+
data-attr:checked="$darkMode"
|
|
357
|
+
data-on:change="$darkMode = evt.detail.checked;
|
|
358
|
+
document.documentElement.classList.toggle('dark', $darkMode)"
|
|
359
|
+
></ty-switch>
|
|
360
|
+
Dark mode
|
|
361
|
+
</label>
|
|
362
|
+
|
|
363
|
+
<ty-button
|
|
364
|
+
flavor="primary"
|
|
365
|
+
data-attr:disabled="!$agreed"
|
|
366
|
+
data-on:click="@post('/api/submit')"
|
|
367
|
+
>
|
|
368
|
+
Continue
|
|
369
|
+
</ty-button>
|
|
370
|
+
|
|
371
|
+
</div>
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
### ty-radio-group / ty-radio
|
|
375
|
+
|
|
376
|
+
```html
|
|
377
|
+
<div data-signals="{plan: 'starter'}">
|
|
378
|
+
|
|
379
|
+
<ty-radio-group
|
|
380
|
+
label="Plan"
|
|
381
|
+
data-on:change="$plan = evt.detail.value"
|
|
382
|
+
>
|
|
383
|
+
<label class="flex items-center gap-2">
|
|
384
|
+
<ty-radio value="starter"></ty-radio> Starter
|
|
385
|
+
</label>
|
|
386
|
+
<label class="flex items-center gap-2">
|
|
387
|
+
<ty-radio value="pro"></ty-radio> Pro
|
|
388
|
+
</label>
|
|
389
|
+
<label class="flex items-center gap-2">
|
|
390
|
+
<ty-radio value="enterprise"></ty-radio> Enterprise
|
|
391
|
+
</label>
|
|
392
|
+
</ty-radio-group>
|
|
393
|
+
|
|
394
|
+
<p data-text="'Selected: ' + $plan"></p>
|
|
395
|
+
|
|
396
|
+
</div>
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
Add `orientation="horizontal"` for a side-by-side layout. `data-bind="plan"` on the group also works, both ways.
|
|
400
|
+
|
|
401
|
+
---
|
|
402
|
+
|
|
403
|
+
## Calendar
|
|
404
|
+
|
|
405
|
+
### ty-date-picker (in a form)
|
|
406
|
+
|
|
407
|
+
By default the picker's `value` is a UTC ISO timestamp: right for a server, wrong for display. Date-only, it's the instant the day starts in the browser's timezone, so it reads a day early east of UTC (picking the 18th in Zagreb gives `…-17T23:00:00.000Z`). For the date as the user picked it, read `evt.detail.localValue` (`2026-03-18`, or `2026-03-18T14:30` with `with-time`):
|
|
408
|
+
|
|
409
|
+
```html
|
|
410
|
+
<div data-signals="{txDate: ''}">
|
|
411
|
+
<ty-date-picker
|
|
412
|
+
label="Date"
|
|
413
|
+
placeholder="Pick a date"
|
|
414
|
+
data-on:change="$txDate = evt.detail.localValue"
|
|
415
|
+
></ty-date-picker>
|
|
416
|
+
<p data-text="$txDate"></p>
|
|
417
|
+
</div>
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
`data-bind="txDate"` also works if you want the UTC value; it then holds the timestamp, not the picked date. Add `native` and the value is the picked date itself, like `<input type="date">` (`2026-03-18`, or `2026-03-18T14:30` with `with-time`), so `data-bind` holds it directly:
|
|
421
|
+
|
|
422
|
+
```html
|
|
423
|
+
<ty-date-picker label="Date" native data-bind="txDate"></ty-date-picker>
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
### ty-calendar (standalone / inline)
|
|
427
|
+
|
|
428
|
+
For an always-visible calendar, bind year/month/day separately:
|
|
429
|
+
|
|
430
|
+
```html
|
|
431
|
+
<div data-signals="{calYear: 2025, calMonth: 1, calDay: null}">
|
|
432
|
+
|
|
433
|
+
<ty-calendar
|
|
434
|
+
data-attr:year="$calYear"
|
|
435
|
+
data-attr:month="$calMonth"
|
|
436
|
+
data-attr:day="$calDay"
|
|
437
|
+
data-on:change="$calYear = evt.detail.year;
|
|
438
|
+
$calMonth = evt.detail.month;
|
|
439
|
+
$calDay = evt.detail.day"
|
|
440
|
+
data-on:navigate="$calYear = evt.detail.year;
|
|
441
|
+
$calMonth = evt.detail.month"
|
|
442
|
+
></ty-calendar>
|
|
443
|
+
|
|
444
|
+
<div data-show="$calDay !== null">
|
|
445
|
+
<ty-button
|
|
446
|
+
flavor="primary"
|
|
447
|
+
data-on:click="@post('/api/book')"
|
|
448
|
+
>
|
|
449
|
+
Book selected date
|
|
450
|
+
</ty-button>
|
|
451
|
+
</div>
|
|
452
|
+
|
|
453
|
+
</div>
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
Event detail for `change`: `{ year, month, day, action, source }`. Event detail for `navigate`: `{ year, month }`.
|
|
457
|
+
|
|
458
|
+
---
|
|
459
|
+
|
|
460
|
+
## Tooltip and popup
|
|
461
|
+
|
|
462
|
+
### ty-tooltip
|
|
463
|
+
|
|
464
|
+
Nest inside the trigger element — positioning is automatic:
|
|
465
|
+
|
|
466
|
+
```html
|
|
467
|
+
<ty-button flavor="primary">
|
|
468
|
+
Save
|
|
469
|
+
<ty-tooltip placement="top">Saves to your account</ty-tooltip>
|
|
470
|
+
</ty-button>
|
|
471
|
+
|
|
472
|
+
<ty-icon name="info">
|
|
473
|
+
<ty-tooltip flavor="primary" delay="300">Required field</ty-tooltip>
|
|
474
|
+
</ty-icon>
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
No Datastar wiring needed — tooltip shows on hover/focus automatically.
|
|
478
|
+
|
|
479
|
+
### ty-popup (for context menus, dropdowns, popovers)
|
|
480
|
+
|
|
481
|
+
```html
|
|
482
|
+
<ty-button>
|
|
483
|
+
Actions
|
|
484
|
+
<ty-popup placement="bottom-start">
|
|
485
|
+
<div class="ty-elevated p-2 rounded-lg min-w-40">
|
|
486
|
+
<div class="px-3 py-2 rounded cursor-pointer hover:ty-bg-neutral-">Edit</div>
|
|
487
|
+
<div
|
|
488
|
+
class="px-3 py-2 rounded cursor-pointer hover:ty-bg-danger- ty-text-danger"
|
|
489
|
+
data-on:click="@post('/api/delete')"
|
|
490
|
+
>Delete</div>
|
|
491
|
+
</div>
|
|
492
|
+
</ty-popup>
|
|
493
|
+
</ty-button>
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
The popup closes automatically on outside click or ESC — no Datastar wiring needed for open/close.
|
|
497
|
+
|
|
498
|
+
---
|
|
499
|
+
|
|
500
|
+
## Utilities
|
|
501
|
+
|
|
502
|
+
### ty-copy
|
|
503
|
+
|
|
504
|
+
```html
|
|
505
|
+
<ty-copy
|
|
506
|
+
label="API Key"
|
|
507
|
+
format="code"
|
|
508
|
+
value="sk-1234abcd"
|
|
509
|
+
></ty-copy>
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
Copy happens internally — no event handling or signals needed.
|
|
513
|
+
|
|
514
|
+
### ty-scroll-container
|
|
515
|
+
|
|
516
|
+
Use when the transaction list (or any list) needs a fixed-height scrollable area:
|
|
517
|
+
|
|
518
|
+
```html
|
|
519
|
+
<ty-scroll-container max-height="400px">
|
|
520
|
+
<div id="transaction-list">
|
|
521
|
+
<!-- Server renders this via patch-elements -->
|
|
522
|
+
</div>
|
|
523
|
+
</ty-scroll-container>
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
When `patch-elements` targets `#transaction-list`, the scroll container maintains its position and the shadow edge indicators update automatically.
|
|
527
|
+
|
|
528
|
+
---
|
|
529
|
+
|
|
530
|
+
## Reorderable lists (ty-sortable)
|
|
531
|
+
|
|
532
|
+
`ty-sortable` never moves its children. A drop (or a keyboard move) fires `ty-sortable-change` on the destination list; post `evt.detail.value` and let the server patch the lists in the new order. Until the patch lands, the item stays where it was dropped.
|
|
533
|
+
|
|
534
|
+
```html
|
|
535
|
+
<ty-sortable id="todo" group="board" label="To do"
|
|
536
|
+
data-signals:move="null"
|
|
537
|
+
data-indicator:_saving
|
|
538
|
+
data-attr:aria-busy="$_saving ? 'true' : 'false'"
|
|
539
|
+
data-on:ty-sortable-change="$move = evt.detail.value; @post('/board/move')">
|
|
540
|
+
<div id="card-12">
|
|
541
|
+
<button type="button" data-handle aria-label="Move Fix login">
|
|
542
|
+
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>
|
|
543
|
+
</button>
|
|
544
|
+
Fix login
|
|
545
|
+
</div>
|
|
546
|
+
</ty-sortable>
|
|
547
|
+
<ty-sortable id="done" group="board" label="Done" …>…</ty-sortable>
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
The server reads `move` from the signals, saves it and patches every list in `move.order` (each `<ty-sortable>` is matched by its `id`):
|
|
551
|
+
|
|
552
|
+
```
|
|
553
|
+
event: datastar-patch-elements
|
|
554
|
+
data: elements <ty-sortable id="todo" group="board" label="To do" …><div id="card-7">…</div></ty-sortable>
|
|
555
|
+
data: elements <ty-sortable id="done" group="board" label="Done" …><div id="card-12">…</div><div id="card-3">…</div></ty-sortable>
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
- **Key every item** with `id` (or `data-key`). The key is what `value` reports, and without an `id` Datastar's morph matches items by position.
|
|
559
|
+
- **`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.
|
|
560
|
+
- **Refusing a move:** keep `aria-busy` on the list while the request runs (`data-indicator` above). If the response doesn't change the order, or patches nothing, the item snaps back when the request ends. With no busy signal and no patch, the hold gives up after `hold-timeout` (5000 ms).
|
|
561
|
+
- **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.
|
|
562
|
+
- `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).
|
|
563
|
+
|
|
564
|
+
---
|
|
565
|
+
|
|
566
|
+
## Icons
|
|
567
|
+
|
|
568
|
+
Put the SVG inside the tag. The server already has it, so there's no registry and no boot script, and it survives SSE patches like any markup:
|
|
569
|
+
|
|
570
|
+
```html
|
|
571
|
+
<ty-icon size="md">
|
|
572
|
+
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">…</svg>
|
|
573
|
+
</ty-icon>
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
The reference examples (`examples/datastar-go/`, `examples/datastar-go-workspace/`) use this pattern. To use `name="…"` instead, register once per page (`tyIcons.register`).
|
|
577
|
+
|
|
578
|
+
Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](ICONS_GUIDE.md#in-html).
|
|
579
|
+
|
|
580
|
+
## Complete Form Example
|
|
581
|
+
|
|
582
|
+
```html
|
|
583
|
+
<div class="ty-elevated p-6 rounded-lg max-w-lg mx-auto"
|
|
584
|
+
data-signals="{txDesc: '', txAmount: '', txType: 'expense', txCategory: '', txDate: ''}">
|
|
585
|
+
|
|
586
|
+
<h2 class="ty-text++ text-xl mb-4">Add Transaction</h2>
|
|
587
|
+
|
|
588
|
+
<!-- Type toggle -->
|
|
589
|
+
<div class="flex gap-2 mb-4">
|
|
590
|
+
<ty-tag size="md"
|
|
591
|
+
data-attr:flavor="$txType === 'expense' ? 'danger' : 'neutral'"
|
|
592
|
+
data-on:click="$txType = 'expense'">
|
|
593
|
+
Expense
|
|
594
|
+
</ty-tag>
|
|
595
|
+
<ty-tag size="md"
|
|
596
|
+
data-attr:flavor="$txType === 'income' ? 'success' : 'neutral'"
|
|
597
|
+
data-on:click="$txType = 'income'">
|
|
598
|
+
Income
|
|
599
|
+
</ty-tag>
|
|
600
|
+
</div>
|
|
601
|
+
|
|
602
|
+
<!-- Form fields -->
|
|
603
|
+
<ty-input data-bind="txDesc" label="Description" placeholder="What was it for?"></ty-input>
|
|
604
|
+
<ty-input data-bind="txAmount" label="Amount" type="currency" currency="EUR"></ty-input>
|
|
605
|
+
<ty-date-picker data-bind="txDate" label="Date" placeholder="Pick a date"></ty-date-picker>
|
|
606
|
+
|
|
607
|
+
<ty-select data-bind="txCategory" label="Category" placeholder="Select category">
|
|
608
|
+
<ty-option value="food">Food</ty-option>
|
|
609
|
+
<ty-option value="transport">Transport</ty-option>
|
|
610
|
+
<ty-option value="utilities">Utilities</ty-option>
|
|
611
|
+
</ty-select>
|
|
612
|
+
|
|
613
|
+
<!-- Submit -->
|
|
614
|
+
<ty-button flavor="primary" class="w-full mt-4"
|
|
615
|
+
data-on:click="@post('/api/transactions/add')">
|
|
616
|
+
Add Transaction
|
|
617
|
+
</ty-button>
|
|
618
|
+
|
|
619
|
+
<!-- Server updates this -->
|
|
620
|
+
<div id="result" class="mt-2"></div>
|
|
621
|
+
</div>
|
|
622
|
+
```
|
|
623
|
+
|
|
624
|
+
## Wizard Pattern
|
|
625
|
+
|
|
626
|
+
```html
|
|
627
|
+
<div data-signals="{wizardStep: 'welcome', wizardCompleted: ''}">
|
|
628
|
+
|
|
629
|
+
<ty-wizard data-attr:active="$wizardStep"
|
|
630
|
+
data-attr:completed="$wizardCompleted">
|
|
631
|
+
|
|
632
|
+
<ty-step id="welcome" label="Welcome">
|
|
633
|
+
<ty-input data-bind="userName" label="Your name"></ty-input>
|
|
634
|
+
<ty-button flavor="primary"
|
|
635
|
+
data-on:click="$wizardStep = 'preferences'; $wizardCompleted = 'welcome'">
|
|
636
|
+
Next
|
|
637
|
+
</ty-button>
|
|
638
|
+
</ty-step>
|
|
639
|
+
|
|
640
|
+
<ty-step id="preferences" label="Preferences">
|
|
641
|
+
<ty-select data-bind="currency" label="Currency">
|
|
642
|
+
<ty-option value="EUR">EUR</ty-option>
|
|
643
|
+
<ty-option value="USD">$ USD</ty-option>
|
|
644
|
+
</ty-select>
|
|
645
|
+
<ty-button flavor="primary"
|
|
646
|
+
data-on:click="$wizardStep = 'done'; $wizardCompleted = 'welcome,preferences'">
|
|
647
|
+
Finish
|
|
648
|
+
</ty-button>
|
|
649
|
+
</ty-step>
|
|
650
|
+
|
|
651
|
+
<ty-step id="done" label="Done">
|
|
652
|
+
<p class="ty-text">All set, <span data-text="$userName"></span>!</p>
|
|
653
|
+
</ty-step>
|
|
654
|
+
|
|
655
|
+
</ty-wizard>
|
|
656
|
+
</div>
|
|
657
|
+
```
|