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,346 @@
|
|
|
1
|
+
# Tyrell Router — ClojureScript Routing Guide
|
|
2
|
+
|
|
3
|
+
The `tyrell.router` namespace provides client-side routing for any ClojureScript framework (Replicant, UIx, Reagent, etc.). It uses a zipper-based tree structure with browser history integration.
|
|
4
|
+
|
|
5
|
+
## Setup
|
|
6
|
+
|
|
7
|
+
```clojure
|
|
8
|
+
(ns my-app.core
|
|
9
|
+
(:require [tyrell.router :as router]))
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Defining Routes
|
|
13
|
+
|
|
14
|
+
Routes are linked to parent nodes in a tree. The root is `::router/root`.
|
|
15
|
+
|
|
16
|
+
```clojure
|
|
17
|
+
;; Top-level routes
|
|
18
|
+
(router/link ::router/root
|
|
19
|
+
[{:id ::home
|
|
20
|
+
:segment "home"
|
|
21
|
+
:landing 10} ; highest :landing = default route
|
|
22
|
+
{:id ::about
|
|
23
|
+
:segment "about"}
|
|
24
|
+
{:id ::settings
|
|
25
|
+
:segment "settings"}])
|
|
26
|
+
|
|
27
|
+
;; Nested routes — link to parent
|
|
28
|
+
(router/link ::settings
|
|
29
|
+
[{:id ::settings-general
|
|
30
|
+
:segment "general"}
|
|
31
|
+
{:id ::settings-account
|
|
32
|
+
:segment "account"}])
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
**Route map keys:**
|
|
36
|
+
|
|
37
|
+
| Key | Description |
|
|
38
|
+
|-----|-------------|
|
|
39
|
+
| `:id` | Unique keyword identifying the route |
|
|
40
|
+
| `:segment` | URL path segment |
|
|
41
|
+
| `:landing` | Priority number — highest wins as default redirect |
|
|
42
|
+
| `:hash` | Hash fragment appended to URL. Routes can share a segment and differ only by hash (`/welcome#top`, `/welcome#examples`) |
|
|
43
|
+
| `:roles` | Set of roles required to access (optional) |
|
|
44
|
+
| `:permissions` | Set of permissions required to access (optional) |
|
|
45
|
+
|
|
46
|
+
## Initialization
|
|
47
|
+
|
|
48
|
+
```clojure
|
|
49
|
+
;; Initialize with optional base path
|
|
50
|
+
(router/init! "") ; root-level app
|
|
51
|
+
(router/init! "/my-app") ; app served under /my-app/
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`init!` does:
|
|
55
|
+
1. Sets the base path
|
|
56
|
+
2. Reads the current browser URL
|
|
57
|
+
3. Handles landing redirect if needed (404 or unauthorized → best landing route)
|
|
58
|
+
4. Listens for `popstate` and `hashchange` events
|
|
59
|
+
|
|
60
|
+
## Navigation
|
|
61
|
+
|
|
62
|
+
```clojure
|
|
63
|
+
;; Navigate by route id
|
|
64
|
+
(router/navigate! ::home)
|
|
65
|
+
(router/navigate! ::about)
|
|
66
|
+
|
|
67
|
+
;; Navigate with query parameters
|
|
68
|
+
(router/navigate! ::user {:id 123})
|
|
69
|
+
;; → /user?id=123
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Checking Active Route
|
|
73
|
+
|
|
74
|
+
```clojure
|
|
75
|
+
;; Is route anywhere in the current path?
|
|
76
|
+
(router/rendered? ::settings) ; true if /settings, /settings/general, etc.
|
|
77
|
+
|
|
78
|
+
;; Exact match only
|
|
79
|
+
(router/rendered? ::settings true) ; true only if exactly /settings
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Hashes in exact matching: a route with a `:hash` matches only that hash. A route without one also matches when the URL's hash isn't a route of its own, because that hash is an in-page anchor: `/settings#billing` still renders `::settings`.
|
|
83
|
+
|
|
84
|
+
## The Key Pattern: Self-Contained Views
|
|
85
|
+
|
|
86
|
+
Each view checks its own visibility. No `cond` or `case` in the parent — just list all views and each one decides whether to render.
|
|
87
|
+
|
|
88
|
+
```clojure
|
|
89
|
+
;; Each view owns its visibility
|
|
90
|
+
(defn home-view []
|
|
91
|
+
(when (router/rendered? ::home)
|
|
92
|
+
[:div.ty-elevated.p-6
|
|
93
|
+
[:h2 "Welcome Home"]]))
|
|
94
|
+
|
|
95
|
+
(defn about-view []
|
|
96
|
+
(when (router/rendered? ::about)
|
|
97
|
+
[:div.ty-elevated.p-6
|
|
98
|
+
[:h2 "About Us"]]))
|
|
99
|
+
|
|
100
|
+
;; App just lists all views — no cond needed
|
|
101
|
+
(defn app []
|
|
102
|
+
[:div.ty-canvas
|
|
103
|
+
(nav)
|
|
104
|
+
(home-view)
|
|
105
|
+
(about-view)])
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
This works the same in Replicant, UIx, Reagent, or any hiccup-based framework.
|
|
109
|
+
|
|
110
|
+
## Navigation UI
|
|
111
|
+
|
|
112
|
+
```clojure
|
|
113
|
+
(defn nav-button [route-id label icon-name]
|
|
114
|
+
(let [active? (router/rendered? route-id)]
|
|
115
|
+
[:button.px-4.py-2.rounded.flex.items-center.gap-2.transition-colors
|
|
116
|
+
{:class (if active?
|
|
117
|
+
["ty-bg-primary" "ty-text++"]
|
|
118
|
+
["ty-bg-neutral-" "ty-text" "hover:ty-bg-neutral"])
|
|
119
|
+
:on {:click #(router/navigate! route-id)}}
|
|
120
|
+
[:ty-icon {:name icon-name :size "sm"}]
|
|
121
|
+
label]))
|
|
122
|
+
|
|
123
|
+
(defn nav []
|
|
124
|
+
[:nav.ty-elevated.p-4.rounded-lg.mb-6
|
|
125
|
+
[:div.flex.gap-2
|
|
126
|
+
(nav-button ::home "Home" "home")
|
|
127
|
+
(nav-button ::about "About" "info")
|
|
128
|
+
(nav-button ::settings "Settings" "settings")]])
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Query Parameters
|
|
132
|
+
|
|
133
|
+
```clojure
|
|
134
|
+
;; Get current query params
|
|
135
|
+
(router/query-params)
|
|
136
|
+
;; => {:id 123, :tab "settings"}
|
|
137
|
+
|
|
138
|
+
;; Set query params (replaces history entry by default)
|
|
139
|
+
(router/set-query! {:page 2 :sort "name"})
|
|
140
|
+
|
|
141
|
+
;; Push new history entry
|
|
142
|
+
(router/set-query! {:page 3} :push)
|
|
143
|
+
|
|
144
|
+
;; Clear query params
|
|
145
|
+
(router/set-query! nil)
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## Authorization
|
|
149
|
+
|
|
150
|
+
Routes can restrict access by requiring `:roles` or `:permissions` (both are sets of keywords):
|
|
151
|
+
|
|
152
|
+
```clojure
|
|
153
|
+
(router/link ::router/root
|
|
154
|
+
[{:id ::home
|
|
155
|
+
:segment "home"
|
|
156
|
+
:landing 10}
|
|
157
|
+
{:id ::admin
|
|
158
|
+
:segment "admin"
|
|
159
|
+
:roles #{:admin}}
|
|
160
|
+
{:id ::dashboard
|
|
161
|
+
:segment "dashboard"
|
|
162
|
+
:permissions #{:view-dashboard}}
|
|
163
|
+
{:id ::reports
|
|
164
|
+
:segment "reports"
|
|
165
|
+
:roles #{:admin :analyst}
|
|
166
|
+
:permissions #{:view-reports}}])
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Setting Current User Context
|
|
170
|
+
|
|
171
|
+
The router exposes three dynamic vars for access control:
|
|
172
|
+
|
|
173
|
+
```clojure
|
|
174
|
+
;; *roles* and *permissions* are plain values (not atoms) — set! them directly
|
|
175
|
+
(set! router/*roles* #{:admin :user})
|
|
176
|
+
(set! router/*permissions* #{:view-dashboard :view-reports})
|
|
177
|
+
|
|
178
|
+
;; *user* is an atom — use reset! or swap!
|
|
179
|
+
(reset! router/*user* {:id 1 :name "Alice"})
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Typically you set these after login and clear them on logout:
|
|
183
|
+
|
|
184
|
+
```clojure
|
|
185
|
+
(defn on-login [user]
|
|
186
|
+
(reset! router/*user* user)
|
|
187
|
+
(set! router/*roles* (:roles user))
|
|
188
|
+
(set! router/*permissions* (:permissions user))
|
|
189
|
+
(router/navigate! ::home))
|
|
190
|
+
|
|
191
|
+
(defn on-logout []
|
|
192
|
+
(reset! router/*user* nil)
|
|
193
|
+
(set! router/*roles* nil)
|
|
194
|
+
(set! router/*permissions* nil)
|
|
195
|
+
(router/navigate! ::home))
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### How Authorization Works
|
|
199
|
+
|
|
200
|
+
`authorized?` checks whether the current user can access a route:
|
|
201
|
+
|
|
202
|
+
```clojure
|
|
203
|
+
(router/authorized? ::admin) ; => true/false
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
The logic:
|
|
207
|
+
1. If the route has **no roles and no permissions** — access is allowed (public route)
|
|
208
|
+
2. If the route has `:roles` — allowed if **any** of the user's `*roles*` intersect with the route's roles
|
|
209
|
+
3. If the route has `:permissions` — allowed if **any** of the user's `*permissions*` intersect with the route's permissions
|
|
210
|
+
4. Roles and permissions are OR'd — matching either one grants access
|
|
211
|
+
|
|
212
|
+
```clojure
|
|
213
|
+
;; Route: {:roles #{:admin :analyst} :permissions #{:view-reports}}
|
|
214
|
+
;; User has *roles* = #{:analyst} → authorized (role match)
|
|
215
|
+
;; User has *permissions* = #{:view-reports} → authorized (permission match)
|
|
216
|
+
;; User has *roles* = #{:user} and *permissions* = #{} → NOT authorized
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### Automatic Redirect on Unauthorized Access
|
|
220
|
+
|
|
221
|
+
When the router initializes or the URL changes, `handle-landing!` runs automatically. It checks:
|
|
222
|
+
1. If the current URL matches **no known routes** (404) — redirect to the best landing route
|
|
223
|
+
2. If **any route** in the current path is unauthorized — redirect to the best landing route
|
|
224
|
+
3. If the path only has routes **with a hash** and the URL has none (`/welcome` when only `#top` and `#examples` exist) — redirect to the best of those (highest `:landing`, then tree order)
|
|
225
|
+
|
|
226
|
+
A path *below* a route stays put (`/users/123` under `::users`), so views can read dynamic segments with non-exact `rendered?`. Redirects replace the history entry, so Back doesn't land on the URL that redirected.
|
|
227
|
+
|
|
228
|
+
The "best landing route" is the route with the highest `:landing` value that the user is authorized to access. This means different users can land on different default pages based on their roles.
|
|
229
|
+
|
|
230
|
+
```clojure
|
|
231
|
+
;; Admin lands on ::admin-dashboard, regular user lands on ::home
|
|
232
|
+
(router/link ::router/root
|
|
233
|
+
[{:id ::home
|
|
234
|
+
:segment "home"
|
|
235
|
+
:landing 10}
|
|
236
|
+
{:id ::admin-dashboard
|
|
237
|
+
:segment "admin"
|
|
238
|
+
:roles #{:admin}
|
|
239
|
+
:landing 20}]) ; higher priority, but only for admins
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
### Using rendered? with Authorization
|
|
243
|
+
|
|
244
|
+
Views should combine `rendered?` with `authorized?` for defense in depth:
|
|
245
|
+
|
|
246
|
+
```clojure
|
|
247
|
+
(defn admin-panel []
|
|
248
|
+
(when (and (router/rendered? ::admin)
|
|
249
|
+
(router/authorized? ::admin))
|
|
250
|
+
[:div.ty-elevated.p-6
|
|
251
|
+
[:h2 "Admin Panel"]
|
|
252
|
+
;; admin content
|
|
253
|
+
]))
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
## Watching Router Changes
|
|
257
|
+
|
|
258
|
+
The router state lives in `router/*router*` (an atom). Watch it to trigger re-renders in your framework:
|
|
259
|
+
|
|
260
|
+
```clojure
|
|
261
|
+
;; Replicant
|
|
262
|
+
(add-watch router/*router* ::render
|
|
263
|
+
(fn [_ _ _ _] (render!)))
|
|
264
|
+
|
|
265
|
+
;; Reagent — use ratom or re-frame subscription instead
|
|
266
|
+
;; UIx — use a hook that derefs the atom
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
## Router State
|
|
270
|
+
|
|
271
|
+
`@router/*router*` contains:
|
|
272
|
+
|
|
273
|
+
| Key | Description |
|
|
274
|
+
|-----|-------------|
|
|
275
|
+
| `:tree` | Route tree (zipper root node) |
|
|
276
|
+
| `:current` | Current URL path (without base) |
|
|
277
|
+
| `:base` | Base path prefix |
|
|
278
|
+
| `:known` | Set of registered route ids |
|
|
279
|
+
| `:unknown` | Queue of routes whose parent isn't registered yet |
|
|
280
|
+
| `:query` | Current query parameters |
|
|
281
|
+
|
|
282
|
+
## Utility Functions
|
|
283
|
+
|
|
284
|
+
```clojure
|
|
285
|
+
;; Get URL path for a route
|
|
286
|
+
(router/component-path (:tree @router/*router*) ::settings-general)
|
|
287
|
+
;; => "/settings/general"
|
|
288
|
+
|
|
289
|
+
;; Get all components rendered for current URL
|
|
290
|
+
(router/url->components)
|
|
291
|
+
|
|
292
|
+
;; Debug: see landing candidates
|
|
293
|
+
(router/landing-candidates)
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
## Complete Example
|
|
297
|
+
|
|
298
|
+
```clojure
|
|
299
|
+
(ns my-app.core
|
|
300
|
+
(:require [replicant.dom :as dom]
|
|
301
|
+
[tyrell.router :as router]
|
|
302
|
+
[tyrell.icons :as icons]
|
|
303
|
+
[tyrell.lucide :as lucide]))
|
|
304
|
+
|
|
305
|
+
(defonce state (atom {:counter 0}))
|
|
306
|
+
|
|
307
|
+
;; Routes
|
|
308
|
+
(router/link ::router/root
|
|
309
|
+
[{:id ::home :segment "home" :landing 10}
|
|
310
|
+
{:id ::about :segment "about"}])
|
|
311
|
+
|
|
312
|
+
;; Views
|
|
313
|
+
(defn home-view []
|
|
314
|
+
(when (router/rendered? ::home)
|
|
315
|
+
[:div.ty-elevated.p-6.rounded-lg
|
|
316
|
+
[:h2.ty-text++.text-2xl.mb-4 "Home"]
|
|
317
|
+
[:p.ty-text "Counter: " (:counter @state)]
|
|
318
|
+
[:ty-button {:flavor "primary"
|
|
319
|
+
:on {:click #(swap! state update :counter inc)}}
|
|
320
|
+
"Increment"]]))
|
|
321
|
+
|
|
322
|
+
(defn about-view []
|
|
323
|
+
(when (router/rendered? ::about)
|
|
324
|
+
[:div.ty-elevated.p-6.rounded-lg
|
|
325
|
+
[:h2.ty-text++.text-2xl.mb-4 "About"]
|
|
326
|
+
[:p.ty-text "This is the about page."]]))
|
|
327
|
+
|
|
328
|
+
(defn app []
|
|
329
|
+
[:div.ty-canvas.min-h-screen.p-6
|
|
330
|
+
(nav)
|
|
331
|
+
(home-view)
|
|
332
|
+
(about-view)])
|
|
333
|
+
|
|
334
|
+
;; Init
|
|
335
|
+
(defn render! []
|
|
336
|
+
(dom/render (.getElementById js/document "app") (app)))
|
|
337
|
+
|
|
338
|
+
(defn init []
|
|
339
|
+
(icons/register! {:home lucide/home :info lucide/info})
|
|
340
|
+
(router/init! "")
|
|
341
|
+
(add-watch router/*router* ::render (fn [_ _ _ _] (render!)))
|
|
342
|
+
(add-watch state ::render (fn [_ _ _ _] (render!)))
|
|
343
|
+
(render!))
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Replace `replicant.dom` with your framework's render call — the router API is identical.
|
|
@@ -0,0 +1,319 @@
|
|
|
1
|
+
# UIx + Tyrell Guide
|
|
2
|
+
|
|
3
|
+
[UIx](https://github.com/pitch-io/uix) is a thin macro layer over React. It speaks hiccup-shaped syntax via `$`, defines components with `defui`, and uses React hooks directly — no `r/atom`, no reactions. Tyrell ships React wrappers via `tyrell.react` so you write `($ ty/Input {:value v :on-change h})` and the wrapper bridges `event.detail.value` for you.
|
|
4
|
+
|
|
5
|
+
This guide covers what's specific to UIx + Tyrell. For framework-agnostic CLJS substrate concerns (icons, CSS, shadow-cljs), see [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md). Working example: [`examples/uix/`](../../examples/uix/).
|
|
6
|
+
|
|
7
|
+
## Setup
|
|
8
|
+
|
|
9
|
+
`deps.edn`:
|
|
10
|
+
|
|
11
|
+
```clojure
|
|
12
|
+
{:deps {com.pitch/uix.core {:mvn/version "1.4.4"}
|
|
13
|
+
com.pitch/uix.dom {:mvn/version "1.4.4"}
|
|
14
|
+
dev.gersak/tyrell {:mvn/version "1.0.0-rc.21"}
|
|
15
|
+
dev.gersak/tyrell-icons-lucide {:mvn/version "1.0.0-rc.21"}}} ; tyrell.lucide
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
`tyrell.react` is part of `dev.gersak/tyrell`, but the npm wrapper package isn't auto-pulled. Install it explicitly the same way you install React itself:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install react react-dom tyrell-react
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
`shadow-cljs.edn`:
|
|
25
|
+
|
|
26
|
+
```clojure
|
|
27
|
+
{:dependencies []
|
|
28
|
+
:builds {:app {:target :browser
|
|
29
|
+
:modules {:main {:init-fn my-app.core/init}}}}}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`tyrell-components` (the web components themselves) is declared in tyrell's `deps.cljs` and shadow-cljs auto-installs it on first build — no manual `npm install tyrell-components`.
|
|
33
|
+
|
|
34
|
+
Load the CSS once, in your HTML or via your CSS pipeline:
|
|
35
|
+
|
|
36
|
+
```html
|
|
37
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell.css">
|
|
38
|
+
<!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
|
|
39
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell-theme.css">
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Mount
|
|
43
|
+
|
|
44
|
+
UIx targets React 18. Create the root once, store it, re-render on `^:after-load`:
|
|
45
|
+
|
|
46
|
+
```clojure
|
|
47
|
+
(ns my-app.core
|
|
48
|
+
(:require [tyrell.components] ; side-effect: registers all <ty-*> elements
|
|
49
|
+
[tyrell.react :as ty]
|
|
50
|
+
[tyrell.icons :as icons]
|
|
51
|
+
[tyrell.lucide :as lucide]
|
|
52
|
+
[uix.core :as uix :refer [defui $]]
|
|
53
|
+
[uix.dom]))
|
|
54
|
+
|
|
55
|
+
(defui app []
|
|
56
|
+
($ :div.ty-canvas.min-h-screen.p-8
|
|
57
|
+
($ ty/Button {:flavor "primary"} "Hello")))
|
|
58
|
+
|
|
59
|
+
(defonce root
|
|
60
|
+
(uix.dom/create-root (js/document.getElementById "app")))
|
|
61
|
+
|
|
62
|
+
(defn ^:export init []
|
|
63
|
+
(icons/register! {:check lucide/check})
|
|
64
|
+
(.render root ($ app)))
|
|
65
|
+
|
|
66
|
+
(defn ^:after-load reload []
|
|
67
|
+
(.render root ($ app)))
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`defonce` is what keeps the root from being recreated on hot reload. Without it, every save would orphan a React tree.
|
|
71
|
+
|
|
72
|
+
## Components — `defui` and `$`
|
|
73
|
+
|
|
74
|
+
`defui` defines a component, `$` instantiates one (or any DOM element). UIx auto-camelCases prop names you pass to React components, so kebab-case on CLJS side maps to camelCase the wrapper expects:
|
|
75
|
+
|
|
76
|
+
```clojure
|
|
77
|
+
(defui labeled-input [{:keys [label value on-change]}]
|
|
78
|
+
($ :div.flex.flex-col.gap-1
|
|
79
|
+
($ :label.ty-text+ label)
|
|
80
|
+
($ ty/Input {:value value
|
|
81
|
+
:on-change on-change}))) ; UIx → onChange for React
|
|
82
|
+
|
|
83
|
+
(defui form []
|
|
84
|
+
(let [[email set-email] (uix/use-state "")]
|
|
85
|
+
($ labeled-input
|
|
86
|
+
{:label "Email"
|
|
87
|
+
:value email
|
|
88
|
+
:on-change #(set-email (.. % -detail -value))})))
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
CLJS class shortcuts on DOM elements work — `($ :div.foo.bar)` is the idiomatic way to set classes; pass `:class` for dynamic ones:
|
|
92
|
+
|
|
93
|
+
```clojure
|
|
94
|
+
($ :div.ty-elevated.p-6.rounded-lg
|
|
95
|
+
{:class (when active? "ty-bg-primary-")}
|
|
96
|
+
"Content")
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`$` accepts children as varargs after the props map. For lists, attach `:key` on the props of the iterated element (not as metadata — that's a Reagent idiom):
|
|
100
|
+
|
|
101
|
+
```clojure
|
|
102
|
+
($ :ul
|
|
103
|
+
(for [item items]
|
|
104
|
+
($ :li {:key (:id item)} (:name item))))
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## State — pure hooks, no atoms
|
|
108
|
+
|
|
109
|
+
UIx is hooks-first. `r/atom` is not part of the model. `use-state` returns `[value setter]`:
|
|
110
|
+
|
|
111
|
+
```clojure
|
|
112
|
+
(defui counter []
|
|
113
|
+
(let [[n set-n] (uix/use-state 0)]
|
|
114
|
+
($ :div.flex.items-center.gap-2
|
|
115
|
+
($ ty/Button {:flavor "primary"
|
|
116
|
+
:on-click #(set-n inc)}
|
|
117
|
+
"Inc")
|
|
118
|
+
($ :span.ty-text++.text-xl n))))
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
For derived state, use `use-memo`. For side effects, `use-effect` with an explicit dependency vector — UIx will warn at compile time if you reference state in the body that isn't declared:
|
|
122
|
+
|
|
123
|
+
```clojure
|
|
124
|
+
(uix/use-effect
|
|
125
|
+
(fn []
|
|
126
|
+
(js/document.title (str "Count: " n))
|
|
127
|
+
;; Cleanup is the function returned
|
|
128
|
+
(fn [] (js/console.log "unmount")))
|
|
129
|
+
[n])
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Event handling — `event.detail.value`
|
|
133
|
+
|
|
134
|
+
Tyrell's React wrappers attach `addEventListener` on the underlying custom element and forward the native `CustomEvent`. So `e.detail.value` is the same access path you'd use in plain JS:
|
|
135
|
+
|
|
136
|
+
```clojure
|
|
137
|
+
(defui email-field []
|
|
138
|
+
(let [[email set-email] (uix/use-state "")
|
|
139
|
+
[error set-error] (uix/use-state nil)]
|
|
140
|
+
($ ty/Input
|
|
141
|
+
{:label "Email"
|
|
142
|
+
:type "email"
|
|
143
|
+
:value email
|
|
144
|
+
:error error
|
|
145
|
+
:on-change (fn [e]
|
|
146
|
+
(let [v (.. e -detail -value)]
|
|
147
|
+
(set-email v)
|
|
148
|
+
(set-error (when-not (re-find #"@" v)
|
|
149
|
+
"Looks invalid"))))}
|
|
150
|
+
($ ty/Icon {:slot "start" :name "mail"}))))
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
**Component-specific event payloads** (matches what the wrapper exposes):
|
|
154
|
+
|
|
155
|
+
| Component | Access |
|
|
156
|
+
|---|---|
|
|
157
|
+
| `ty/Input`, `ty/Textarea`, `ty/Switch`, `ty/DatePicker` | `(.. e -detail -value)` |
|
|
158
|
+
| `ty/Checkbox` | `(.. e -detail -checked)` |
|
|
159
|
+
| `ty/Select` | `(.. e -detail -value)`; with `:multiple`, `(.. e -detail -values)` → JS array |
|
|
160
|
+
| `ty/RadioGroup` | `(.. e -detail -value)` |
|
|
161
|
+
| `ty/Tabs` | `(.. e -detail -tab)` |
|
|
162
|
+
| `ty/Wizard` step nav | `(.. e -detail -step)` |
|
|
163
|
+
|
|
164
|
+
For `Select` with `:multiple`, convert the JS array to a CLJS vector if you need it:
|
|
165
|
+
|
|
166
|
+
```clojure
|
|
167
|
+
:on-change (fn [e]
|
|
168
|
+
(let [vs (.. e -detail -values)]
|
|
169
|
+
(set-skills (vec vs))))
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## Composition — children with slots
|
|
173
|
+
|
|
174
|
+
Tyrell components accept slotted children — pass them as `$` children with a `:slot` attribute:
|
|
175
|
+
|
|
176
|
+
```clojure
|
|
177
|
+
($ ty/Input
|
|
178
|
+
{:label "Search" :placeholder "Type to search…"
|
|
179
|
+
:value q :on-change #(set-q (.. % -detail -value))}
|
|
180
|
+
($ ty/Icon {:slot "start" :name "search"}))
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
`Select` takes `Option` children directly:
|
|
184
|
+
|
|
185
|
+
```clojure
|
|
186
|
+
($ ty/Select
|
|
187
|
+
{:label "Country" :value country
|
|
188
|
+
:on-change #(set-country (.. % -detail -value))}
|
|
189
|
+
($ ty/Option {:value "us"} "United States")
|
|
190
|
+
($ ty/Option {:value "de"} "Germany"))
|
|
191
|
+
|
|
192
|
+
($ ty/Select
|
|
193
|
+
{:label "Skills" :multiple true :value (str/join "," skills)
|
|
194
|
+
:on-change (fn [e]
|
|
195
|
+
(set-skills (vec (.. e -detail -values))))}
|
|
196
|
+
($ ty/Option {:value "clojure" :flavor "primary"} "Clojure")
|
|
197
|
+
($ ty/Option {:value "react" :flavor "primary"} "React"))
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## Refs and imperative APIs — modals, popups
|
|
201
|
+
|
|
202
|
+
`ty-modal` exposes `.show()` / `.hide()` methods. `use-ref` + the wrapper's ref forwarding gives you that handle:
|
|
203
|
+
|
|
204
|
+
```clojure
|
|
205
|
+
(defui modal-demo []
|
|
206
|
+
(let [modal-ref (uix/use-ref nil)
|
|
207
|
+
open (fn [_] (some-> modal-ref .-current (.show)))
|
|
208
|
+
close (fn [_] (some-> modal-ref .-current (.hide)))]
|
|
209
|
+
($ :div
|
|
210
|
+
($ ty/Button {:flavor "primary" :on-click open} "Open")
|
|
211
|
+
($ ty/Modal {:ref modal-ref}
|
|
212
|
+
($ :div.ty-elevated.p-6.rounded-2xl
|
|
213
|
+
($ :h3.ty-text++ "Hello")
|
|
214
|
+
($ ty/Button {:on-click close} "Close"))))))
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
The same pattern works for `ty-popup` (`.openPopup()` / `.closePopup()` / `.togglePopup()`).
|
|
218
|
+
|
|
219
|
+
## Forms — controlled state
|
|
220
|
+
|
|
221
|
+
Tyrell components are form-associated, so a wrapping `<form>` element with a submit handler works without any extra wiring. UIx-side, treat the form like any controlled React form:
|
|
222
|
+
|
|
223
|
+
```clojure
|
|
224
|
+
(defui signup-form []
|
|
225
|
+
(let [[profile set-profile] (uix/use-state {:email "" :role "" :news? false})
|
|
226
|
+
update-field (uix/use-callback
|
|
227
|
+
(fn [k v] (set-profile #(assoc % k v)))
|
|
228
|
+
[])
|
|
229
|
+
on-submit (fn [^js e]
|
|
230
|
+
(.preventDefault e)
|
|
231
|
+
(js/console.log "submit:" (clj->js profile)))]
|
|
232
|
+
($ :form {:on-submit on-submit
|
|
233
|
+
:class "ty-elevated p-6 rounded-lg flex flex-col gap-4"}
|
|
234
|
+
($ ty/Input
|
|
235
|
+
{:label "Email" :type "email" :required true
|
|
236
|
+
:value (:email profile)
|
|
237
|
+
:on-change #(update-field :email (.. % -detail -value))})
|
|
238
|
+
($ ty/Select
|
|
239
|
+
{:label "Role" :value (:role profile)
|
|
240
|
+
:on-change #(update-field :role (.. % -detail -value))}
|
|
241
|
+
($ ty/Option {:value "developer"} "Developer")
|
|
242
|
+
($ ty/Option {:value "designer"} "Designer"))
|
|
243
|
+
($ :label.flex.items-center.gap-2.cursor-pointer
|
|
244
|
+
($ ty/Checkbox
|
|
245
|
+
{:checked (:news? profile)
|
|
246
|
+
:on-change #(update-field :news? (.. % -detail -checked))})
|
|
247
|
+
"Subscribe to newsletter")
|
|
248
|
+
($ ty/Button {:type "submit" :flavor "primary"} "Submit"))))
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
## Subscribing to non-React state
|
|
252
|
+
|
|
253
|
+
UIx hooks-only model means non-React atoms (e.g. `tyrell.router/*router*`, app state in a `defonce` atom) need explicit subscription. The pattern: a custom hook that adds a watch in `use-effect`:
|
|
254
|
+
|
|
255
|
+
```clojure
|
|
256
|
+
(defn use-watch
|
|
257
|
+
"Re-render when `a` (an IDeref + IWatchable) changes."
|
|
258
|
+
[a]
|
|
259
|
+
(let [[v set-v] (uix/use-state @a)]
|
|
260
|
+
(uix/use-effect
|
|
261
|
+
(fn []
|
|
262
|
+
(let [k (gensym "uix-watch")]
|
|
263
|
+
(add-watch a k (fn [_ _ _ new] (set-v new)))
|
|
264
|
+
(fn [] (remove-watch a k))))
|
|
265
|
+
[a])
|
|
266
|
+
v))
|
|
267
|
+
|
|
268
|
+
(defui current-route []
|
|
269
|
+
(let [router (use-watch tyrell.router/*router*)]
|
|
270
|
+
($ :div.ty-text- (str "Current: " (:current router)))))
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
This is the same approach the [`examples/uix/`](../../examples/uix/) app uses to subscribe to the Tyrell router.
|
|
274
|
+
|
|
275
|
+
## Icons — register at startup
|
|
276
|
+
|
|
277
|
+
```clojure
|
|
278
|
+
(ns my-app.icons
|
|
279
|
+
(:require [tyrell.icons :as icons]
|
|
280
|
+
[tyrell.lucide :as lucide]))
|
|
281
|
+
|
|
282
|
+
(icons/register! {:check lucide/check
|
|
283
|
+
:user lucide/user}) ; the key is the name
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Call it in `init` before the first render. Then `($ ty/Icon {:name "check"})`, or `($ :ty-icon {:name "check"})` for the plain element.
|
|
287
|
+
|
|
288
|
+
Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-clojure).
|
|
289
|
+
|
|
290
|
+
## Lazy loading — UIx native
|
|
291
|
+
|
|
292
|
+
UIx ships `uix.core/lazy` for component-level code splitting, paired with shadow-cljs `:modules`:
|
|
293
|
+
|
|
294
|
+
```clojure
|
|
295
|
+
(def calendar-page
|
|
296
|
+
(uix/lazy #(js/Promise.resolve (resolve 'my-app.calendar/page))))
|
|
297
|
+
|
|
298
|
+
($ uix/Suspense {:fallback ($ :div "Loading…")}
|
|
299
|
+
($ calendar-page))
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
For shadow-cljs module setup, see [CODE_SPLITTING.md](CODE_SPLITTING.md).
|
|
303
|
+
|
|
304
|
+
## Common pitfalls
|
|
305
|
+
|
|
306
|
+
- **Don't pass CLJS data structures as props** to wrapper components without conversion. `:value [:a :b]` will arrive as a CLJS persistent vector, which the underlying web component doesn't understand. Convert: `:value (clj->js skills)` or join into a string format the component expects (`Select` with `:multiple` accepts comma-separated `value="a,b"`).
|
|
307
|
+
- **`:variant` is not a valid prop** — Tyrell uses `:flavor` (mapped to the `flavor` attribute). The older example code may show `:variant`; that's outdated.
|
|
308
|
+
- **Don't render `<ty-*>` directly without the wrapper** if you need React-style event handling. `($ :ty-input {:on-change h})` will not fire — React's synthetic event system doesn't bridge custom element events. Either use `ty/Input` (recommended), or attach `addEventListener` manually in `use-effect` on a ref.
|
|
309
|
+
- **Boolean attributes**: pass them as `true`/`false`, not as strings. `($ ty/Modal {:open true})` works; `:open "true"` does not.
|
|
310
|
+
- **Don't forget `defonce` on the root**. Re-creating it on every reload leaks state.
|
|
311
|
+
- **Children of `Select`** must be `ty/Option` — not a plain `($ :option ...)` or `ty/Tag`. The selection is the select's `:value`; `:selected` on an option does nothing without `:external-selection`.
|
|
312
|
+
|
|
313
|
+
## See also
|
|
314
|
+
|
|
315
|
+
- [QUICKSTART.md](QUICKSTART.md) — Track A entry point
|
|
316
|
+
- [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md) — substrate (deps, CSS, shadow-cljs)
|
|
317
|
+
- [REPLICANT_TY_GUIDE.md](REPLICANT_TY_GUIDE.md) — non-React alternative
|
|
318
|
+
- [CODE_SPLITTING.md](CODE_SPLITTING.md) — shadow-cljs module setup
|
|
319
|
+
- [`examples/uix/`](../../examples/uix/) — full working app: routing, forms, modals, layouts
|