tyrell-components 1.0.0-TC9 → 1.0.0-rc.22
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 +1541 -0
- package/README.md +71 -53
- package/bin/tyrell.mjs +77 -0
- 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 +937 -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 +458 -0
- package/lib/components/select.js +1458 -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 +752 -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 +66 -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,408 @@
|
|
|
1
|
+
# Reagent + Tyrell Guide
|
|
2
|
+
|
|
3
|
+
Reagent's model is hiccup vectors and reactive atoms. Components are plain `defn`, instantiated with `[my-comp props]`, and React interop happens through the `:>` reader. State lives in `r/atom`s — derefing one inside a component subscribes that component to changes.
|
|
4
|
+
|
|
5
|
+
This guide focuses on what's specific to Reagent + Tyrell. For shadow-cljs, CSS, and icon basics, see [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md). Working example: [`examples/reagent/`](../../examples/reagent/).
|
|
6
|
+
|
|
7
|
+
## Setup
|
|
8
|
+
|
|
9
|
+
`deps.edn`:
|
|
10
|
+
|
|
11
|
+
```clojure
|
|
12
|
+
{:deps {reagent/reagent {:mvn/version "1.2.0"}
|
|
13
|
+
dev.gersak/tyrell {:mvn/version "1.0.0-rc.21"}
|
|
14
|
+
dev.gersak/tyrell-icons-lucide {:mvn/version "1.0.0-rc.21"}}} ; tyrell.lucide
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
`tyrell.react` ships inside `dev.gersak/tyrell` and re-exports the npm wrappers. The npm package isn't auto-pulled — install it explicitly:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install react@18 react-dom@18 tyrell-react
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Reagent 1.2 supports React 18 via `reagent.dom.client`. If you're on Reagent <1.2, upgrade — the older `reagent.dom/render` API is deprecated.
|
|
24
|
+
|
|
25
|
+
Load the CSS:
|
|
26
|
+
|
|
27
|
+
```html
|
|
28
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell.css">
|
|
29
|
+
<!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
|
|
30
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell-theme.css">
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Mount — React 18 + Reagent
|
|
34
|
+
|
|
35
|
+
```clojure
|
|
36
|
+
(ns my-app.core
|
|
37
|
+
(:require [tyrell.components] ; side-effect: registers all <ty-*> elements
|
|
38
|
+
[tyrell.react :as ty]
|
|
39
|
+
[tyrell.icons :as icons]
|
|
40
|
+
[tyrell.lucide :as lucide]
|
|
41
|
+
[reagent.core :as r]
|
|
42
|
+
[reagent.dom.client :as rdom]))
|
|
43
|
+
|
|
44
|
+
(defn app []
|
|
45
|
+
[:div.ty-canvas.min-h-screen.p-8
|
|
46
|
+
[:> ty/Button {:flavor "primary"} "Hello"]])
|
|
47
|
+
|
|
48
|
+
(defonce root
|
|
49
|
+
(rdom/create-root (.getElementById js/document "app")))
|
|
50
|
+
|
|
51
|
+
(defn render! []
|
|
52
|
+
(rdom/render root [app]))
|
|
53
|
+
|
|
54
|
+
(defn ^:export init []
|
|
55
|
+
(icons/register! {:check lucide/check})
|
|
56
|
+
(render!))
|
|
57
|
+
|
|
58
|
+
(defn ^:after-load reload []
|
|
59
|
+
(render!))
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`defonce` keeps the root stable across reloads. The vector form `[app]` is what Reagent expects — not `(app)` and not React elements; Reagent converts hiccup to React internally.
|
|
63
|
+
|
|
64
|
+
## Components — plain functions, hiccup vectors
|
|
65
|
+
|
|
66
|
+
A Reagent component is a function returning hiccup. Call it with a vector:
|
|
67
|
+
|
|
68
|
+
```clojure
|
|
69
|
+
(defn labeled-input [{:keys [label value on-change]}]
|
|
70
|
+
[:div.flex.flex-col.gap-1
|
|
71
|
+
[:label.ty-text+ label]
|
|
72
|
+
[:> ty/Input {:value value :onChange on-change}]])
|
|
73
|
+
|
|
74
|
+
(defn form []
|
|
75
|
+
(let [email (r/atom "")]
|
|
76
|
+
(fn [] ; Form-2: returns the render fn
|
|
77
|
+
[:div
|
|
78
|
+
[labeled-input
|
|
79
|
+
{:label "Email"
|
|
80
|
+
:value @email
|
|
81
|
+
:on-change #(reset! email (.. % -detail -value))}]])))
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Reagent has three component shapes:
|
|
85
|
+
|
|
86
|
+
- **Form-1** — `(defn x [] [:div])` — pure render. Re-runs on every prop change.
|
|
87
|
+
- **Form-2** — `(defn x [] (let [a (r/atom 0)] (fn [] [:div @a])))` — outer `let` runs once for setup; inner fn is the render. Use this when you need component-local state.
|
|
88
|
+
- **Form-3** — `r/create-class` with explicit lifecycle methods. Rarely needed; mostly use form-2 or form-1 with `r/with-let`.
|
|
89
|
+
|
|
90
|
+
For most Tyrell-driven UIs, form-2 with a local `r/atom` is the workhorse for unsaved-edit state, modal toggles, etc.
|
|
91
|
+
|
|
92
|
+
## Props — kebab-case for hiccup, camelCase for `:>` interop
|
|
93
|
+
|
|
94
|
+
Reagent normalizes `:on-change` → `onChange` for **HTML elements** in hiccup (`[:input {:on-change …}]`). But when you cross into React-component territory via `:>`, **you write camelCase yourself** — Reagent doesn't transform props that pass through `:>`:
|
|
95
|
+
|
|
96
|
+
```clojure
|
|
97
|
+
;; HTML element — kebab-case is fine, Reagent converts it
|
|
98
|
+
[:button {:on-click handler} "Click"]
|
|
99
|
+
|
|
100
|
+
;; React component via :> — write camelCase explicitly
|
|
101
|
+
[:> ty/Input {:onChange handler ; ← camelCase!
|
|
102
|
+
:className "w-full" ; ← className, not :class
|
|
103
|
+
:value @v}]
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
This is the most common Reagent + Tyrell mistake. Look at any working file and you'll see `:onChange`, `:onClick`, `:className` everywhere wrappers are involved. The `examples/reagent/` source uses this convention throughout.
|
|
107
|
+
|
|
108
|
+
## State — `r/atom`s and reactivity
|
|
109
|
+
|
|
110
|
+
Deref a reagent atom inside a component, and the component re-renders when it changes:
|
|
111
|
+
|
|
112
|
+
```clojure
|
|
113
|
+
(defonce form-state
|
|
114
|
+
(r/atom {:email "" :role "" :errors {}}))
|
|
115
|
+
|
|
116
|
+
(defn email-field []
|
|
117
|
+
(let [{:keys [email errors]} @form-state] ; deref → subscribe
|
|
118
|
+
[:> ty/Input
|
|
119
|
+
{:label "Email"
|
|
120
|
+
:type "email"
|
|
121
|
+
:value email
|
|
122
|
+
:error (:email errors)
|
|
123
|
+
:onChange (fn [e]
|
|
124
|
+
(let [v (.. e -detail -value)]
|
|
125
|
+
(swap! form-state assoc :email v)
|
|
126
|
+
(swap! form-state update :errors
|
|
127
|
+
(fn [errs]
|
|
128
|
+
(if (re-find #"@" v)
|
|
129
|
+
(dissoc errs :email)
|
|
130
|
+
(assoc errs :email "Looks invalid"))))))}]))
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`r/track` and reactions (`r/reaction`) give you derived values that re-compute lazily. For most Tyrell forms, plain `swap!` + a single atom is enough.
|
|
134
|
+
|
|
135
|
+
## Event handling — `event.detail.value`
|
|
136
|
+
|
|
137
|
+
`tyrell.react` wrappers attach `addEventListener` on the underlying custom element and pass the native `CustomEvent` through to your handler. Access the payload off `.-detail`:
|
|
138
|
+
|
|
139
|
+
```clojure
|
|
140
|
+
[:> ty/Input
|
|
141
|
+
{:label "Email"
|
|
142
|
+
:value @email
|
|
143
|
+
:onChange #(reset! email (.. % -detail -value))}]
|
|
144
|
+
|
|
145
|
+
[:> ty/Checkbox
|
|
146
|
+
{:checked @subscribed?
|
|
147
|
+
:onChange #(reset! subscribed? (.. % -detail -checked))}]
|
|
148
|
+
|
|
149
|
+
[:> ty/Select
|
|
150
|
+
{:multiple true
|
|
151
|
+
:value (str/join "," @skills)
|
|
152
|
+
:onChange (fn [^js e]
|
|
153
|
+
(reset! skills (vec (.. e -detail -values))))}
|
|
154
|
+
[:> ty/Option {:value "clojure" :flavor "primary"} "Clojure"]
|
|
155
|
+
[:> ty/Option {:value "react" :flavor "primary"} "React"]]
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
| Component | Access |
|
|
159
|
+
|---|---|
|
|
160
|
+
| `ty/Input`, `ty/Textarea`, `ty/Switch`, `ty/DatePicker` | `(.. e -detail -value)` |
|
|
161
|
+
| `ty/Checkbox` | `(.. e -detail -checked)` |
|
|
162
|
+
| `ty/Select` | `(.. e -detail -value)`; with `:multiple`, `(.. e -detail -values)` → JS array |
|
|
163
|
+
| `ty/RadioGroup` | `(.. e -detail -value)` |
|
|
164
|
+
| `ty/Tabs` | `(.. e -detail -tab)` |
|
|
165
|
+
| `ty/Sortable` | `(.. e -detail -value)` → `{key, group, source, from, to, order}` |
|
|
166
|
+
|
|
167
|
+
## Composition — children with slots
|
|
168
|
+
|
|
169
|
+
Pass children after the props map in the same hiccup vector. Use `:slot` on Tyrell icon children:
|
|
170
|
+
|
|
171
|
+
```clojure
|
|
172
|
+
[:> ty/Input
|
|
173
|
+
{:label "Search" :value @q
|
|
174
|
+
:onChange #(reset! q (.. % -detail -value))}
|
|
175
|
+
[:> ty/Icon {:slot "start" :name "search"}]]
|
|
176
|
+
|
|
177
|
+
[:> ty/Select
|
|
178
|
+
{:label "Country" :value @country
|
|
179
|
+
:onChange #(reset! country (.. % -detail -value))}
|
|
180
|
+
[:> ty/Option {:value "us"} "United States"]
|
|
181
|
+
[:> ty/Option {:value "de"} "Germany"]]
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## Refs — modal control
|
|
185
|
+
|
|
186
|
+
`use-state`-style hooks aren't idiomatic Reagent. For imperative refs on `ty-modal` / `ty-popup`, the `:ref` prop accepts a callback:
|
|
187
|
+
|
|
188
|
+
```clojure
|
|
189
|
+
(defn modal-demo []
|
|
190
|
+
(let [modal-el (r/atom nil)]
|
|
191
|
+
(fn []
|
|
192
|
+
[:div
|
|
193
|
+
[:> ty/Button
|
|
194
|
+
{:flavor "primary"
|
|
195
|
+
:onClick #(some-> @modal-el (.show))}
|
|
196
|
+
"Open"]
|
|
197
|
+
[:> ty/Modal
|
|
198
|
+
{:ref #(reset! modal-el %)}
|
|
199
|
+
[:div.ty-elevated.p-6.rounded-2xl
|
|
200
|
+
[:h3.ty-text++ "Hello"]
|
|
201
|
+
[:> ty/Button
|
|
202
|
+
{:onClick #(some-> @modal-el (.hide))}
|
|
203
|
+
"Close"]]]])))
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Storing the DOM node in an atom isn't reactive in the usual sense (you don't deref it inside render), but it gives you a stable handle for imperative calls.
|
|
207
|
+
|
|
208
|
+
## Forms — `<form>` + Tyrell's form-association
|
|
209
|
+
|
|
210
|
+
Every form-associated Tyrell component (`ty/Input`, `ty/Textarea`, `ty/Checkbox`, `ty/Switch`, `ty/RadioGroup`, `ty/Select`, `ty/DatePicker`) calls `setFormValue()` internally. A wrapping `<form>` with an `onSubmit` handler picks them up:
|
|
211
|
+
|
|
212
|
+
```clojure
|
|
213
|
+
(defn signup-form []
|
|
214
|
+
(let [profile (r/atom {:email "" :role "" :news? false :errors {}})]
|
|
215
|
+
(fn []
|
|
216
|
+
(let [{:keys [email role news? errors]} @profile
|
|
217
|
+
update-field (fn [k v]
|
|
218
|
+
(swap! profile assoc k v)
|
|
219
|
+
(swap! profile update :errors dissoc k))
|
|
220
|
+
on-submit (fn [^js e]
|
|
221
|
+
(.preventDefault e)
|
|
222
|
+
(js/console.log "submit:" (clj->js @profile)))]
|
|
223
|
+
[:form {:on-submit on-submit
|
|
224
|
+
:class "ty-elevated p-6 rounded-lg flex flex-col gap-4"}
|
|
225
|
+
[:> ty/Input
|
|
226
|
+
{:label "Email" :name "email" :type "email" :required true
|
|
227
|
+
:value email :error (:email errors)
|
|
228
|
+
:onChange #(update-field :email (.. % -detail -value))}]
|
|
229
|
+
[:> ty/Select
|
|
230
|
+
{:label "Role" :name "role" :value role
|
|
231
|
+
:onChange #(update-field :role (.. % -detail -value))}
|
|
232
|
+
[:> ty/Option {:value "developer"} "Developer"]
|
|
233
|
+
[:> ty/Option {:value "designer"} "Designer"]]
|
|
234
|
+
[:label.flex.items-center.gap-2.cursor-pointer
|
|
235
|
+
[:> ty/Checkbox
|
|
236
|
+
{:name "news" :checked news?
|
|
237
|
+
:onChange #(update-field :news? (.. % -detail -checked))}]
|
|
238
|
+
"Subscribe to newsletter"]
|
|
239
|
+
[:> ty/Button {:type "submit" :flavor "primary"} "Submit"]]))))
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
The `[:form …]` element here is HTML, so `:on-submit` (kebab) is correct; the Tyrell components inside use `:onChange` (camel) because they're routed through `:>`.
|
|
243
|
+
|
|
244
|
+
## Subscribing to non-Reagent atoms
|
|
245
|
+
|
|
246
|
+
Tyrell's router state lives in a non-Reagent atom (`tyrell.router/*router*`). Reagent doesn't auto-subscribe to it — but a one-line trick makes it reactive: deref it inside the component, *and* derefing a regular atom inside a Reagent component triggers re-render only if Reagent considers it reactive (it doesn't, by default). Two patterns work:
|
|
247
|
+
|
|
248
|
+
**A. Wrap the foreign atom in a Reagent ratom mirror** — keep them in sync via `add-watch`:
|
|
249
|
+
|
|
250
|
+
```clojure
|
|
251
|
+
(defonce router-state (r/atom @tyrell.router/*router*))
|
|
252
|
+
|
|
253
|
+
(defonce _watch
|
|
254
|
+
(add-watch tyrell.router/*router* ::mirror
|
|
255
|
+
(fn [_ _ _ new] (reset! router-state new))))
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Then `[:span @router-state]` re-renders normally.
|
|
259
|
+
|
|
260
|
+
**B. Re-render the whole tree on watch** — what `examples/reagent/` does:
|
|
261
|
+
|
|
262
|
+
```clojure
|
|
263
|
+
(defn render! []
|
|
264
|
+
(rdom/render root [main-layout]))
|
|
265
|
+
|
|
266
|
+
(defn init []
|
|
267
|
+
;; …
|
|
268
|
+
(add-watch tyrell.router/*router* ::render
|
|
269
|
+
(fn [_ _ _ _] (render!))))
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
This is heavier but simpler — fine for small apps. For larger apps, pattern A is cleaner.
|
|
273
|
+
|
|
274
|
+
## Icons
|
|
275
|
+
|
|
276
|
+
```clojure
|
|
277
|
+
(ns my-app.icons
|
|
278
|
+
(:require [tyrell.icons :as icons]
|
|
279
|
+
[tyrell.lucide :as lucide]))
|
|
280
|
+
|
|
281
|
+
(icons/register! {:check lucide/check
|
|
282
|
+
:user lucide/user}) ; the key is the name
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Then `[:> ty/Icon {:name "check"}]`, or `[:ty-icon {:name "check"}]` for a render-only icon.
|
|
286
|
+
|
|
287
|
+
Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-clojure).
|
|
288
|
+
|
|
289
|
+
## Calendar and wizard
|
|
290
|
+
|
|
291
|
+
### ty-calendar
|
|
292
|
+
|
|
293
|
+
```clojure
|
|
294
|
+
(defn calendar-demo []
|
|
295
|
+
(let [now (js/Date.)
|
|
296
|
+
sel (r/atom {:year (.getFullYear now)
|
|
297
|
+
:month (inc (.getMonth now))
|
|
298
|
+
:day nil})]
|
|
299
|
+
(fn []
|
|
300
|
+
(let [{:keys [year month day]} @sel]
|
|
301
|
+
[:div.flex.flex-col.gap-4
|
|
302
|
+
[:> ty/Calendar
|
|
303
|
+
{:year year
|
|
304
|
+
:month month
|
|
305
|
+
:day day
|
|
306
|
+
:onChange (fn [^js e]
|
|
307
|
+
(reset! sel {:year (.. e -detail -year)
|
|
308
|
+
:month (.. e -detail -month)
|
|
309
|
+
:day (.. e -detail -day)}))}]
|
|
310
|
+
(when day
|
|
311
|
+
[:p.ty-text- (str "Selected: " year "-" (when (< month 10) "0") month "-" (when (< day 10) "0") day)])]))))
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Event detail: `{ year, month, day, action, source }`. Form value is ISO `YYYY-MM-DD` when wrapped in `<form>` with a `name` attribute.
|
|
315
|
+
|
|
316
|
+
### ty-wizard
|
|
317
|
+
|
|
318
|
+
```clojure
|
|
319
|
+
(defn wizard-demo []
|
|
320
|
+
(let [step (r/atom "info")
|
|
321
|
+
completed (r/atom [])]
|
|
322
|
+
(fn []
|
|
323
|
+
(let [advance #(do (swap! completed conj @step)
|
|
324
|
+
(reset! step %))]
|
|
325
|
+
[:> ty/Wizard
|
|
326
|
+
{:height "400px"
|
|
327
|
+
:active @step
|
|
328
|
+
:completed (str/join "," @completed)}
|
|
329
|
+
[:> ty/Step {:id "info" :label "Info"}
|
|
330
|
+
[:div.p-6.flex.flex-col.gap-4
|
|
331
|
+
[:> ty/Input {:label "Name" :required true}]
|
|
332
|
+
[:> ty/Button {:flavor "primary"
|
|
333
|
+
:onClick #(advance "review")} "Next"]]]
|
|
334
|
+
[:> ty/Step {:id "review" :label "Review"}
|
|
335
|
+
[:div.p-6.flex.gap-2
|
|
336
|
+
[:> ty/Button {:onClick #(reset! step "info")} "Back"]
|
|
337
|
+
[:> ty/Button {:flavor "success"
|
|
338
|
+
:onClick #(advance "done")} "Finish"]]]
|
|
339
|
+
[:> ty/Step {:id "done" :label "Done"}
|
|
340
|
+
[:div.p-6 "All done!"]]]))))
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
Event detail: `{ activeId, activeIndex, previousId, previousIndex, direction }` via `onChange` — or listen on the element directly for `ty-wizard-step-change`.
|
|
344
|
+
|
|
345
|
+
## Reorderable lists (ty-sortable)
|
|
346
|
+
|
|
347
|
+
`ty/Sortable` never moves its children. A drop (or a keyboard move) calls `:onChange` (`ty-sortable-change`) on the destination list, and the list holds the result on screen until Reagent renders the items in the new order. Give each item a `:key` and a `:data-key` (or `:id`):
|
|
348
|
+
|
|
349
|
+
```clojure
|
|
350
|
+
(defonce board (r/atom {"todo" ["a" "b"] "done" ["c"]}))
|
|
351
|
+
(defonce saving? (r/atom false))
|
|
352
|
+
|
|
353
|
+
(defn on-move [^js e]
|
|
354
|
+
(let [value (.. e -detail -value)]
|
|
355
|
+
(reset! saving? true)
|
|
356
|
+
(-> (save value)
|
|
357
|
+
(.then #(swap! board merge (js->clj (.-order value)))) ; new key order per touched list
|
|
358
|
+
(.finally #(reset! saving? false))))) ; order unchanged: snaps back
|
|
359
|
+
|
|
360
|
+
(defn column [id label]
|
|
361
|
+
[:> ty/Sortable {:id id :group "board" :label label
|
|
362
|
+
:aria-busy (when @saving? "true")
|
|
363
|
+
:onChange on-move}
|
|
364
|
+
(for [k (get @board id)]
|
|
365
|
+
^{:key k}
|
|
366
|
+
[:div {:data-key k}
|
|
367
|
+
[:button {:type "button" :data-handle "" :aria-label (str "Move " k)}
|
|
368
|
+
[:> ty/Icon {:name "grip-vertical"}]]
|
|
369
|
+
k])])
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
- `order` is the new key order of each list the move touched, by list id, so one `merge` renders both lists. For fractional ranking, save a rank between `(.. value -to -prev)` and `(.. value -to -next)` instead.
|
|
373
|
+
- `:aria-busy` while saving makes a refused save snap back as soon as it clears. Without it, call `(.settle (.. e -detail -toContainer) "rejected")`, or `(.preventDefault e)` to reject at once.
|
|
374
|
+
- 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.
|
|
375
|
+
- Props: `:group`, `:axis`, `:handle`, `:accepts`, `:disabled`, `:keyAttr`, `:holdTimeout`, `:label`, `:canDrop`, `:labels`, and `:onStart` / `:onCancel` / `:onSettle`.
|
|
376
|
+
|
|
377
|
+
---
|
|
378
|
+
|
|
379
|
+
## Common pitfalls
|
|
380
|
+
|
|
381
|
+
- **`:on-change` vs `:onChange`** — easy to mix up. Through `:>`, you must write camelCase. In a plain `[:input ...]` (HTML), kebab-case works. Reagent does *not* transform props for `:>` components.
|
|
382
|
+
- **`:className`, not `:class`, when going through `:>`** — same reason. (Reagent's hiccup converts `:class` for HTML elements only.)
|
|
383
|
+
- **Don't destructure props in the outer Form-2 fn** — only the inner returned fn gets the latest props. Destructure inside the render fn:
|
|
384
|
+
```clojure
|
|
385
|
+
;; Wrong
|
|
386
|
+
(defn x [{:keys [v]}]
|
|
387
|
+
(let [a (r/atom 0)]
|
|
388
|
+
(fn [] [:div v]))) ; v is stale on update
|
|
389
|
+
|
|
390
|
+
;; Right
|
|
391
|
+
(defn x []
|
|
392
|
+
(let [a (r/atom 0)]
|
|
393
|
+
(fn [{:keys [v]}] [:div v])))
|
|
394
|
+
```
|
|
395
|
+
- **Don't pass CLJS persistent vectors as props** to `Select` with `:multiple`. Convert to a comma-string or JS array on the way in:
|
|
396
|
+
```clojure
|
|
397
|
+
:value (str/join "," @skills)
|
|
398
|
+
```
|
|
399
|
+
- **`reagent.dom/render` is deprecated** in React 18 mode — use `reagent.dom.client`.
|
|
400
|
+
- **`r/as-element`** is rarely needed. Only reach for it if a third-party React component asks for a React element directly (e.g. `Suspense`'s `:fallback`).
|
|
401
|
+
- **Children of `Select`** must be `ty/Option` (or raw `[:ty-option …]`) — not native `<option>`s or `ty/Tag`. The selection is the select's `:value`; `:selected` on an option does nothing without `:external-selection`.
|
|
402
|
+
|
|
403
|
+
## See also
|
|
404
|
+
|
|
405
|
+
- [QUICKSTART.md](QUICKSTART.md) — Track A entry point
|
|
406
|
+
- [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md) — substrate (deps, CSS, shadow-cljs)
|
|
407
|
+
- [UIX_TY_GUIDE.md](UIX_TY_GUIDE.md) — same React wrapper, hooks-only model
|
|
408
|
+
- [`examples/reagent/`](../../examples/reagent/) — full working app: routing, forms, validation
|