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,300 @@
|
|
|
1
|
+
# ClojureScript + Tyrell Substrate Reference
|
|
2
|
+
|
|
3
|
+
> **Looking for the quickstart?** → [QUICKSTART.md](QUICKSTART.md) — two-track entry point (Reagent / re-frame / UIx / Helix via `tyrell.react`, or Replicant / vanilla via raw `<ty-*>`).
|
|
4
|
+
|
|
5
|
+
Use Tyrell from any ClojureScript app — Replicant, Reagent, UIx, Rum, or vanilla CLJS with no UI framework. This guide is the **substrate reference**: distribution, shadow-cljs setup, raw interop with web components, and icon tree-shaking.
|
|
6
|
+
|
|
7
|
+
For framework-specific patterns, see [REPLICANT_TY_GUIDE.md](REPLICANT_TY_GUIDE.md). The infrastructure guides ([ROUTING_GUIDE.md](ROUTING_GUIDE.md), [I18N_GUIDE.md](I18N_GUIDE.md), [LAYOUT_GUIDE.md](LAYOUT_GUIDE.md)) are already framework-agnostic.
|
|
8
|
+
|
|
9
|
+
## What you get
|
|
10
|
+
|
|
11
|
+
CLJS users add **one Clojars dep** — `dev.gersak/tyrell` — and that brings everything they need:
|
|
12
|
+
|
|
13
|
+
| What you get | Where it comes from |
|
|
14
|
+
|---|---|
|
|
15
|
+
| Routing, i18n, layout, icon registry, shim | CLJS namespaces in the JAR (`tyrell.router`, `tyrell.i18n`, `tyrell.layout`, `tyrell.icons`, `tyrell.shim`) |
|
|
16
|
+
| Web Components — `<ty-button>`, `<ty-input>`, etc. | npm `tyrell-components`, declared in this artifact's `deps.cljs` and **auto-installed** into your `package.json` by shadow-cljs |
|
|
17
|
+
| `tyrell.components` shim | A side-effect-import wrapper around npm `tyrell-components`, so CLJS users only ever require `tyrell.*` namespaces |
|
|
18
|
+
| React wrappers — `tyrell.react/Button`, `tyrell.react/Input`, ... | CLJS namespace re-exporting npm `tyrell-react`. Track A (React-based CLJS) only — npm package is **not** auto-pulled (opt-in) |
|
|
19
|
+
|
|
20
|
+
Icons are separate Clojars artifacts, one per set: `dev.gersak/tyrell-icons-lucide` (`tyrell.lucide`), `-heroicons` (`tyrell.heroicons.*`), `-material` (`tyrell.material.*`) and `-fontawesome` (`tyrell.fav6.*`). `dev.gersak/tyrell-icons` pulls in all four. Each icon is an individual CLJS `def` — shadow-cljs `:advanced` removes unused ones automatically.
|
|
21
|
+
|
|
22
|
+
> **How npm auto-install works.** The `dev.gersak/tyrell` JAR ships with a `deps.cljs` at the classpath root that declares `{:npm-deps {"tyrell-components" "<pinned-version>"}}`. shadow-cljs reads it on each build and runs `npm install --save --save-exact tyrell-components@<version>`, so you never write that line manually. The entry will appear in your `package.json` after the first build — that's the standard shadow-cljs contract for library-declared npm deps.
|
|
23
|
+
|
|
24
|
+
## Setup
|
|
25
|
+
|
|
26
|
+
[](https://clojars.org/dev.gersak/tyrell)
|
|
27
|
+
|
|
28
|
+
### 1. Add one Clojars dep
|
|
29
|
+
|
|
30
|
+
`deps.edn`:
|
|
31
|
+
|
|
32
|
+
```clojure
|
|
33
|
+
{:deps {dev.gersak/tyrell {:mvn/version "..."}}} ; latest from Clojars badge above
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
That single dep brings:
|
|
37
|
+
- The CLJS infrastructure (`tyrell.router`, `tyrell.i18n`, `tyrell.layout`, `tyrell.icons`, `tyrell.shim`)
|
|
38
|
+
- The `tyrell.components` shim namespace that side-effect-imports the npm package
|
|
39
|
+
|
|
40
|
+
The npm `tyrell-components` package is declared in this artifact's `deps.cljs`, so shadow-cljs auto-installs it into your `package.json` on first build. No manual `npm install tyrell-components` needed.
|
|
41
|
+
|
|
42
|
+
Icons are not included. Add the set jars you use:
|
|
43
|
+
```clojure
|
|
44
|
+
{:deps {dev.gersak/tyrell {:mvn/version "..."}
|
|
45
|
+
dev.gersak/tyrell-icons-lucide {:mvn/version "..."}}} ; tyrell.lucide
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### 2. Load `tyrell.css`
|
|
49
|
+
|
|
50
|
+
Component classes only work once the stylesheet is loaded. shadow-cljs doesn't process CSS imports from CLJS, so you load it separately. Pick one of the paths in [`### CSS handling`](#css-handling) below — recap:
|
|
51
|
+
|
|
52
|
+
```html
|
|
53
|
+
<!-- A. CDN <link> -->
|
|
54
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
|
|
55
|
+
<!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
|
|
56
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
# B. Fetch into your public/ once
|
|
61
|
+
cp node_modules/tyrell-components/css/tyrell.css public/css/tyrell.css
|
|
62
|
+
cp node_modules/tyrell-components/css/tyrell-theme.css public/css/tyrell-theme.css
|
|
63
|
+
# Then <link> both in your HTML, brand.css after tyrell.css
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```css
|
|
67
|
+
/* C. Tailwind / PostCSS pipeline — add to your CSS entrypoint */
|
|
68
|
+
@import "../node_modules/tyrell-components/css/tyrell.css";
|
|
69
|
+
@import "../node_modules/tyrell-components/css/tyrell-theme.css";
|
|
70
|
+
@import "tailwindcss";
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 3. Load components in your app
|
|
74
|
+
|
|
75
|
+
Two paths — pick one:
|
|
76
|
+
|
|
77
|
+
#### Path A — `tyrell.components` shim (recommended)
|
|
78
|
+
|
|
79
|
+
```clojure
|
|
80
|
+
(ns my-app.core
|
|
81
|
+
(:require [tyrell.components])) ; side-effect: registers all <ty-*> elements
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
That single CLJS require pulls in the npm package transitively (already declared via `deps.cljs`). Components are marked side-effectful in the npm package's `package.json`; icons are not — they only enter your bundle when you reference them.
|
|
85
|
+
|
|
86
|
+
For fine-grained tree-shaking, you can bypass the shim and import npm subpaths directly:
|
|
87
|
+
|
|
88
|
+
```clojure
|
|
89
|
+
(ns my-app.core
|
|
90
|
+
(:require ["tyrell-components/button"]
|
|
91
|
+
["tyrell-components/input"]
|
|
92
|
+
["tyrell-components/dropdown"]
|
|
93
|
+
["tyrell-components/modal"]))
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Subpaths match component names: `button`, `input`, `textarea`, `checkbox`, `dropdown`, `option`, `multiselect`, `tag`, `modal`, `popup`, `tooltip`, `tabs`, `tab`, `wizard`, `step`, `calendar`, `calendar-month`, `date-picker`, `icon`, `copy`, `resize-observer`, `scroll-container`.
|
|
97
|
+
|
|
98
|
+
#### Path B — CDN script tag
|
|
99
|
+
|
|
100
|
+
For server-rendered apps or when you don't want NPM in the loop:
|
|
101
|
+
|
|
102
|
+
```html
|
|
103
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
|
|
104
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
|
|
105
|
+
<script type="module" src="https://cdn.jsdelivr.net/npm/tyrell-components@latest/dist/tyrell.js"></script>
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The CDN bundle registers all components. From CLJS, you don't need to require anything — just use `<ty-*>` tags in your hiccup or DOM.
|
|
109
|
+
|
|
110
|
+
### 4. Verify
|
|
111
|
+
|
|
112
|
+
```clojure
|
|
113
|
+
(.appendChild js/document.body
|
|
114
|
+
(doto (js/document.createElement "ty-button")
|
|
115
|
+
(set! -textContent "Hello")))
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
If a styled button renders, you're set.
|
|
119
|
+
|
|
120
|
+
## Using Web Components from CLJS
|
|
121
|
+
|
|
122
|
+
The same three rules apply across every CLJS framework:
|
|
123
|
+
|
|
124
|
+
1. **Event payload lives on `event.detail`.** In CLJS: `(.. e -detail -value)` or `(j/get-in e [:detail :value])`.
|
|
125
|
+
2. **Properties vs attributes.** Booleans, arrays, objects must be set as JS properties, not attributes. Strings work as either.
|
|
126
|
+
3. **Don't conflate CLJS data and the DOM.** A `ty-select multiple` `value` is a JS array, not a CLJS vector — convert with `(clj->js)` going in and `(js->clj)` coming out (or use `js/Array.from`).
|
|
127
|
+
|
|
128
|
+
### Vanilla CLJS (no UI framework)
|
|
129
|
+
|
|
130
|
+
```clojure
|
|
131
|
+
(ns my-app.core
|
|
132
|
+
(:require [tyrell.components]
|
|
133
|
+
[tyrell.icons :as icons]
|
|
134
|
+
[tyrell.lucide :as lucide]))
|
|
135
|
+
|
|
136
|
+
(defn render []
|
|
137
|
+
(let [root (js/document.getElementById "app")
|
|
138
|
+
input (doto (js/document.createElement "ty-input")
|
|
139
|
+
(.setAttribute "label" "Email")
|
|
140
|
+
(.setAttribute "type" "email"))
|
|
141
|
+
button (doto (js/document.createElement "ty-button")
|
|
142
|
+
(.setAttribute "flavor" "primary")
|
|
143
|
+
(set! -textContent "Submit"))]
|
|
144
|
+
(.addEventListener input "change"
|
|
145
|
+
(fn [e]
|
|
146
|
+
(js/console.log "email:" (.. e -detail -value))))
|
|
147
|
+
(.addEventListener button "click"
|
|
148
|
+
(fn [_]
|
|
149
|
+
(js/console.log "value:" (.-value input))))
|
|
150
|
+
(.appendChild root input)
|
|
151
|
+
(.appendChild root button)))
|
|
152
|
+
|
|
153
|
+
(defn ^:export init []
|
|
154
|
+
(icons/register! {:check lucide/check})
|
|
155
|
+
(render))
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Hiccup (Replicant, Reagent, UIx, Rum)
|
|
159
|
+
|
|
160
|
+
Hiccup-based frameworks render `<ty-*>` tags directly. Each framework's idioms differ slightly — see [REPLICANT_TY_GUIDE.md](REPLICANT_TY_GUIDE.md) for one full example. The key concerns are framework-specific:
|
|
161
|
+
|
|
162
|
+
| Framework | Set property (not attribute) | Listen to event |
|
|
163
|
+
|---|---|---|
|
|
164
|
+
| Replicant | `:replicant/key` for stable identity; properties via DOM ops or `:dom/on-mount` | `[:on/change handler]` |
|
|
165
|
+
| Reagent | `:value-for-typeahead` etc. work as attrs; complex → use `:ref` | `:on-change` (lowercased) |
|
|
166
|
+
| UIx (Helix) | `$d` for DOM elements; props are camelCased | `:on-change` |
|
|
167
|
+
| Rum | Refs for property setting | `:on-change` |
|
|
168
|
+
|
|
169
|
+
Across all of them, `event.detail.value` access in CLJS:
|
|
170
|
+
|
|
171
|
+
```clojure
|
|
172
|
+
(fn [e] (.. e -detail -value))
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### React-based CLJS — use `tyrell.react`
|
|
176
|
+
|
|
177
|
+
For Reagent, re-frame, UIx, and Helix, prefer the wrappers from `tyrell.react` over raw `<ty-*>` tags. React's synthetic event system doesn't bridge custom events — `[:> :ty-input {:on-change ...}]` would never fire with `event.detail.value`. The wrappers attach `addEventListener` on the underlying element so `:on-change` works the way React libs expect.
|
|
178
|
+
|
|
179
|
+
```clojure
|
|
180
|
+
(ns my-app.core
|
|
181
|
+
(:require [tyrell.components] ; side-effect: registers <ty-*> elements
|
|
182
|
+
[tyrell.react :as ty] ; React component vars
|
|
183
|
+
[reagent.core :as r]))
|
|
184
|
+
|
|
185
|
+
[:> ty/Input
|
|
186
|
+
{:label "Email"
|
|
187
|
+
:value @email
|
|
188
|
+
:on-change #(reset! email (.. % -detail -value))}]
|
|
189
|
+
|
|
190
|
+
[:> ty/Button {:flavor "primary"} "Save"]
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
`tyrell.react` is a CLJS shim inside `dev.gersak/tyrell` that re-exports the wrappers from npm `tyrell-react`. The npm package itself is **not** auto-installed — install it explicitly the same way you install `react` and `react-dom`:
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
npm install tyrell-react
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Track B users (Replicant, vanilla) skip this step. Each wrapper exports under both `TyButton`/`TyInput` and short `Button`/`Input` names — pick one style.
|
|
200
|
+
|
|
201
|
+
## Icon registration in CLJS
|
|
202
|
+
|
|
203
|
+
`<ty-icon name="…">` is a runtime lookup, so register the icons you use. Each icon is a `def` holding an SVG string; `:advanced` drops the ones you don't reference.
|
|
204
|
+
|
|
205
|
+
```clojure
|
|
206
|
+
(ns my-app.icons
|
|
207
|
+
(:require [tyrell.icons :as icons]
|
|
208
|
+
[tyrell.lucide :as lucide]))
|
|
209
|
+
|
|
210
|
+
(icons/register! {:check lucide/check
|
|
211
|
+
:user lucide/user}) ; the key is the name
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Don't build names at runtime (`(symbol "lucide" name)`): the compiler can't see them. Register every candidate up front.
|
|
215
|
+
|
|
216
|
+
Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-clojure).
|
|
217
|
+
|
|
218
|
+
## Shadow-cljs configuration tips
|
|
219
|
+
|
|
220
|
+
### `:js-options` for npm interop
|
|
221
|
+
|
|
222
|
+
Default config works. If you see issues with `tyrell-components` ESM imports:
|
|
223
|
+
|
|
224
|
+
```clojure
|
|
225
|
+
{:builds
|
|
226
|
+
{:app
|
|
227
|
+
{:target :browser
|
|
228
|
+
:js-options {:resolve {"tyrell-components" {:target :npm
|
|
229
|
+
:require "tyrell-components"}}}}}}
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Usually unnecessary — shadow-cljs autodetects.
|
|
233
|
+
|
|
234
|
+
### CSS handling
|
|
235
|
+
|
|
236
|
+
Shadow-cljs doesn't process CSS imports from CLJS — `tyrell.css` lives outside the JS module graph and must be loaded separately. The simplest path is a `<link>` to the CDN:
|
|
237
|
+
|
|
238
|
+
```html
|
|
239
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css">
|
|
240
|
+
<!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
|
|
241
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css">
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
For offline-friendly local dev, fetch the files once into your static directory:
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
# Pin a version, no npm install required (use the version from the badge or your package.json)
|
|
248
|
+
curl -o public/css/tyrell.css https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell.css
|
|
249
|
+
curl -o public/css/tyrell-theme.css https://cdn.jsdelivr.net/npm/tyrell-components@latest/css/tyrell-theme.css
|
|
250
|
+
|
|
251
|
+
# Or copy from the version shadow-cljs already installed (after first build)
|
|
252
|
+
cp node_modules/tyrell-components/css/tyrell.css public/css/tyrell.css
|
|
253
|
+
cp node_modules/tyrell-components/css/tyrell-theme.css public/css/tyrell-theme.css
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Wire the second form as a `postinstall` script in `package.json` to keep the files in sync with whatever shadow-cljs installs:
|
|
257
|
+
|
|
258
|
+
```json
|
|
259
|
+
"scripts": {
|
|
260
|
+
"postinstall": "mkdir -p public/css && cp node_modules/tyrell-components/css/tyrell*.css public/css/"
|
|
261
|
+
}
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Then reference both with `<link>`, brand.css after tyrell.css. The `cp` form auto-tracks whatever version is installed by your deps.
|
|
265
|
+
|
|
266
|
+
Projects with a CSS pipeline (Tailwind, PostCSS) can import the files directly into their entrypoint instead:
|
|
267
|
+
|
|
268
|
+
```css
|
|
269
|
+
@import "../node_modules/tyrell-components/css/tyrell.css";
|
|
270
|
+
@import "../node_modules/tyrell-components/css/tyrell-theme.css";
|
|
271
|
+
@import "tailwindcss";
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Tyrell's CSS gets bundled into your output stylesheet alongside everything else.
|
|
275
|
+
|
|
276
|
+
### Code splitting (lazy loading)
|
|
277
|
+
|
|
278
|
+
See [CODE_SPLITTING.md](CODE_SPLITTING.md) for shadow-cljs `:modules` setup. Pattern: defer heavy components (calendar/date-picker/dropdown) until the route that needs them loads.
|
|
279
|
+
|
|
280
|
+
## What's CLJS-specific
|
|
281
|
+
|
|
282
|
+
A few things differ from JS:
|
|
283
|
+
|
|
284
|
+
- **One Clojars dep covers everything** — `dev.gersak/tyrell` declares the npm `tyrell-components` package via `deps.cljs`, so you `:require [tyrell.components]` once and shadow-cljs handles npm install + module resolution. JS users do `npm install tyrell-components` directly; CLJS users don't need to.
|
|
285
|
+
- **No `'use client'` boundary** — shadow-cljs targets the browser by default. SSR with `:target :node` requires extra care; see existing CLJS SSR docs (out of scope here).
|
|
286
|
+
- **Icons can use keyword names** — `(icons/register! {:check lucide/check})` is idiomatic. Strings also work.
|
|
287
|
+
- **Property setting** — CLJS hiccup renderers (Reagent, Replicant, UIx) all have framework-specific quirks for setting JS properties vs HTML attributes. The component itself doesn't care; the framework's bridge does.
|
|
288
|
+
- **React wrappers via CLJS namespace** — `tyrell.react` re-exports `tyrell-react`'s components, so React-based CLJS frameworks alias `[tyrell.react :as ty]` instead of `["tyrell-react" :as ty]`. The npm package still needs to be installed manually (Track A only).
|
|
289
|
+
|
|
290
|
+
## See also
|
|
291
|
+
|
|
292
|
+
- [TY_GUIDE.md](../TY_GUIDE.md) — universal component API reference
|
|
293
|
+
- [CSS_GUIDE.md](../CSS_GUIDE.md) — design system
|
|
294
|
+
- [REPLICANT_TY_GUIDE.md](REPLICANT_TY_GUIDE.md) — Replicant-specific integration patterns
|
|
295
|
+
- [ROUTING_GUIDE.md](ROUTING_GUIDE.md) — `tyrell.router` (framework-agnostic)
|
|
296
|
+
- [I18N_GUIDE.md](I18N_GUIDE.md) — `tyrell.i18n` (framework-agnostic)
|
|
297
|
+
- [LAYOUT_GUIDE.md](LAYOUT_GUIDE.md) — `tyrell.layout` (framework-agnostic)
|
|
298
|
+
- [COMPONENT_GUIDE.md](COMPONENT_GUIDE.md) — `tyrell.shim` for building Web Components in CLJS
|
|
299
|
+
- [CODE_SPLITTING.md](CODE_SPLITTING.md) — shadow-cljs lazy loading
|
|
300
|
+
- [../js/JAVASCRIPT_GUIDE.md](../js/JAVASCRIPT_GUIDE.md) — JS-side substrate (bundlers, side-effects, SSR)
|
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
# Code Splitting & Lazy Loading
|
|
2
|
+
|
|
3
|
+
> **Note:** This guide describes patterns and strategies, not exact code to copy. File names, module names, and folder structures are illustrative examples — adapt them to your project's conventions.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
Tyrell uses shadow-cljs module system to split components into separate chunks:
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
ty-lazy.js (core + lightweight components)
|
|
11
|
+
ty-select.js (loaded when <ty-select> is used)
|
|
12
|
+
ty-calendar.js (loaded when <ty-calendar> is used)
|
|
13
|
+
ty-date-picker.js (loaded when <ty-date-picker> is used)
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## shadow-cljs Configuration
|
|
19
|
+
|
|
20
|
+
```clojure
|
|
21
|
+
;; shadow-cljs.edn
|
|
22
|
+
{:builds
|
|
23
|
+
{:lib
|
|
24
|
+
{:target :browser
|
|
25
|
+
:output-dir "dist/"
|
|
26
|
+
:module-loader true ;; Enable dynamic loading
|
|
27
|
+
|
|
28
|
+
:modules
|
|
29
|
+
{;; Core module - always loaded
|
|
30
|
+
:ty-core
|
|
31
|
+
{:entries [tyrell.core]
|
|
32
|
+
:init-fn tyrell.core/init}
|
|
33
|
+
|
|
34
|
+
;; Lazy modules - loaded on demand
|
|
35
|
+
:ty-select
|
|
36
|
+
{:entries [tyrell.components.select]
|
|
37
|
+
:depends-on #{:ty-core}}
|
|
38
|
+
|
|
39
|
+
:ty-calendar
|
|
40
|
+
{:entries [tyrell.components.calendar
|
|
41
|
+
tyrell.components.calendar-navigation
|
|
42
|
+
tyrell.components.calendar-month]
|
|
43
|
+
:depends-on #{:ty-core}}
|
|
44
|
+
|
|
45
|
+
:ty-date-picker
|
|
46
|
+
{:entries [tyrell.components.date-picker]
|
|
47
|
+
:depends-on #{:ty-calendar}}
|
|
48
|
+
|
|
49
|
+
:ty-selected-options
|
|
50
|
+
{:entries [tyrell.components.selected-tags]
|
|
51
|
+
:depends-on #{:ty-select}}}}}}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Creating a Lazy Component Wrapper
|
|
57
|
+
|
|
58
|
+
### 1. The Real Component
|
|
59
|
+
|
|
60
|
+
```clojure
|
|
61
|
+
;; src/app/components/heavy_chart.cljs
|
|
62
|
+
(ns app.components.heavy-chart
|
|
63
|
+
(:require [tyrell.shim :as shim]
|
|
64
|
+
["chart.js" :as Chart])) ;; Heavy dependency
|
|
65
|
+
|
|
66
|
+
(defn render! [^js el]
|
|
67
|
+
;; Complex chart rendering...
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
(def configuration
|
|
71
|
+
{:observed [:data :type]
|
|
72
|
+
:connected render!
|
|
73
|
+
:attr (fn [el _] (render! el))})
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### 2. The Lazy Wrapper
|
|
77
|
+
|
|
78
|
+
```clojure
|
|
79
|
+
;; src/app/components/lazy/heavy_chart.cljs
|
|
80
|
+
(ns app.components.lazy.heavy-chart
|
|
81
|
+
(:require [shadow.lazy :as lazy]
|
|
82
|
+
[tyrell.shim :as shim]))
|
|
83
|
+
|
|
84
|
+
;; Mark the config as loadable
|
|
85
|
+
(def config (lazy/loadable app.components.heavy-chart/configuration))
|
|
86
|
+
|
|
87
|
+
;; Define component with lazy lifecycle
|
|
88
|
+
(defn lazy-connected [^js el]
|
|
89
|
+
(-> (lazy/load config)
|
|
90
|
+
(.then (fn [cfg]
|
|
91
|
+
((:connected cfg) el)))))
|
|
92
|
+
|
|
93
|
+
(defn lazy-attr [^js el delta]
|
|
94
|
+
(-> (lazy/load config)
|
|
95
|
+
(.then (fn [cfg]
|
|
96
|
+
((:attr cfg) el delta)))))
|
|
97
|
+
|
|
98
|
+
(shim/define! "app-heavy-chart"
|
|
99
|
+
{:observed [:data :type]
|
|
100
|
+
:connected lazy-connected
|
|
101
|
+
:attr lazy-attr})
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### 3. Configure Module
|
|
105
|
+
|
|
106
|
+
```clojure
|
|
107
|
+
;; shadow-cljs.edn
|
|
108
|
+
:modules
|
|
109
|
+
{:app-core
|
|
110
|
+
{:entries [app.core
|
|
111
|
+
app.components.lazy.heavy-chart] ;; Wrapper in core
|
|
112
|
+
:init-fn app.core/init}
|
|
113
|
+
|
|
114
|
+
:app-heavy-chart
|
|
115
|
+
{:entries [app.components.heavy-chart] ;; Real component separate
|
|
116
|
+
:depends-on #{:app-core}}}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Utility Helper
|
|
122
|
+
|
|
123
|
+
Simplify with a reusable helper:
|
|
124
|
+
|
|
125
|
+
```clojure
|
|
126
|
+
;; src/app/lazy_util.cljs
|
|
127
|
+
(ns app.lazy-util
|
|
128
|
+
(:require [shadow.lazy :as lazy]))
|
|
129
|
+
|
|
130
|
+
(defn create-lazy-lifecycle
|
|
131
|
+
"Create lazy-loading lifecycle hooks from a loadable config"
|
|
132
|
+
[loadable-config]
|
|
133
|
+
{:connected
|
|
134
|
+
(fn [^js el]
|
|
135
|
+
(-> (lazy/load loadable-config)
|
|
136
|
+
(.then #((:connected %) el))))
|
|
137
|
+
|
|
138
|
+
:disconnected
|
|
139
|
+
(fn [^js el]
|
|
140
|
+
(-> (lazy/load loadable-config)
|
|
141
|
+
(.then #(when-let [f (:disconnected %)] (f el)))))
|
|
142
|
+
|
|
143
|
+
:attr
|
|
144
|
+
(fn [^js el delta]
|
|
145
|
+
(-> (lazy/load loadable-config)
|
|
146
|
+
(.then #((:attr %) el delta))))
|
|
147
|
+
|
|
148
|
+
:prop
|
|
149
|
+
(fn [^js el delta]
|
|
150
|
+
(-> (lazy/load loadable-config)
|
|
151
|
+
(.then #((:prop %) el delta))))})
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Then your lazy wrapper becomes:
|
|
155
|
+
|
|
156
|
+
```clojure
|
|
157
|
+
(ns app.components.lazy.heavy-chart
|
|
158
|
+
(:require [shadow.lazy :as lazy]
|
|
159
|
+
[app.lazy-util :as lazy-util]
|
|
160
|
+
[tyrell.shim :as shim]))
|
|
161
|
+
|
|
162
|
+
(def config (lazy/loadable app.components.heavy-chart/configuration))
|
|
163
|
+
|
|
164
|
+
(shim/define! "app-heavy-chart"
|
|
165
|
+
(merge
|
|
166
|
+
{:observed [:data :type]}
|
|
167
|
+
(lazy-util/create-lazy-lifecycle config)))
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## Loading States
|
|
173
|
+
|
|
174
|
+
Show a placeholder while the component loads:
|
|
175
|
+
|
|
176
|
+
```clojure
|
|
177
|
+
(defn lazy-connected [^js el]
|
|
178
|
+
(let [root (shim/ensure-shadow el)]
|
|
179
|
+
;; Show loading state immediately
|
|
180
|
+
(set! (.-innerHTML root)
|
|
181
|
+
"<div class='ty-text- animate-pulse'>Loading...</div>")
|
|
182
|
+
|
|
183
|
+
;; Load and render real component
|
|
184
|
+
(-> (lazy/load config)
|
|
185
|
+
(.then (fn [cfg]
|
|
186
|
+
((:connected cfg) el))))))
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## Preloading
|
|
192
|
+
|
|
193
|
+
Preload modules you expect to need soon:
|
|
194
|
+
|
|
195
|
+
```clojure
|
|
196
|
+
(ns app.core
|
|
197
|
+
(:require [shadow.lazy :as lazy]))
|
|
198
|
+
|
|
199
|
+
;; Preload on hover
|
|
200
|
+
(defn preload-on-hover! [trigger-el loadable]
|
|
201
|
+
(.addEventListener trigger-el "mouseenter"
|
|
202
|
+
(fn [] (lazy/load loadable)) #js {:once true}))
|
|
203
|
+
|
|
204
|
+
;; Preload after idle
|
|
205
|
+
(defn preload-when-idle! [loadable]
|
|
206
|
+
(if js/requestIdleCallback
|
|
207
|
+
(js/requestIdleCallback #(lazy/load loadable))
|
|
208
|
+
(js/setTimeout #(lazy/load loadable) 200)))
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## Bundle Analysis
|
|
214
|
+
|
|
215
|
+
Check your bundle sizes:
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
# Build with report
|
|
219
|
+
npx shadow-cljs release lib --config-merge '{:build-report true}'
|
|
220
|
+
|
|
221
|
+
# View report
|
|
222
|
+
open target/shadow-cljs/build-report.html
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Best Practices
|
|
228
|
+
|
|
229
|
+
1. **Core module should be small** - Only essential components and initialization
|
|
230
|
+
2. **Group related components** - Calendar + navigation + month in one module
|
|
231
|
+
3. **Consider dependencies** - If A always needs B, put them together
|
|
232
|
+
4. **Lazy load heavy dependencies** - Chart libs, date libs, etc.
|
|
233
|
+
5. **Preload predictable paths** - User will likely click "Settings"? Preload it
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## Example: Full App Structure
|
|
238
|
+
|
|
239
|
+
```
|
|
240
|
+
src/
|
|
241
|
+
├── app/
|
|
242
|
+
│ ├── core.cljs ;; Init, router, lightweight components
|
|
243
|
+
│ ├── components/
|
|
244
|
+
│ │ ├── button.cljs ;; In core (used everywhere)
|
|
245
|
+
│ │ ├── input.cljs ;; In core
|
|
246
|
+
│ │ ├── heavy_table.cljs ;; Separate module
|
|
247
|
+
│ │ ├── chart.cljs ;; Separate module
|
|
248
|
+
│ │ └── lazy/
|
|
249
|
+
│ │ ├── heavy_table.cljs
|
|
250
|
+
│ │ └── chart.cljs
|
|
251
|
+
│ └── lazy_util.cljs
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
```clojure
|
|
255
|
+
;; shadow-cljs.edn
|
|
256
|
+
:modules
|
|
257
|
+
{:app-core
|
|
258
|
+
{:entries [app.core
|
|
259
|
+
app.components.button
|
|
260
|
+
app.components.input
|
|
261
|
+
app.components.lazy.heavy-table
|
|
262
|
+
app.components.lazy.chart]
|
|
263
|
+
:init-fn app.core/init}
|
|
264
|
+
|
|
265
|
+
:app-table
|
|
266
|
+
{:entries [app.components.heavy-table]
|
|
267
|
+
:depends-on #{:app-core}}
|
|
268
|
+
|
|
269
|
+
:app-chart
|
|
270
|
+
{:entries [app.components.chart]
|
|
271
|
+
:depends-on #{:app-core}}}
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## See Also
|
|
277
|
+
|
|
278
|
+
- [shadow-cljs Code Splitting](https://shadow-cljs.github.io/docs/UsersGuide.html#CodeSplitting)
|
|
279
|
+
- [Component Building Guide](COMPONENT_GUIDE.md) - tyrell.shim API for defining web components
|