tyrell-components 1.0.0-TC8 → 1.0.0-rc.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +122 -0
- package/CHANGELOG.md +1531 -0
- package/README.md +71 -53
- package/css/tyrell-colors-static.css +1 -0
- package/css/tyrell-theme.css +1 -0
- package/css/tyrell.css +1 -1783
- package/dist/tyrell-colors-static.css +1 -0
- package/dist/tyrell-theme.css +1 -0
- package/dist/tyrell.css +1 -1783
- package/dist/tyrell.js +1 -1
- package/guides/AGENT_INSTRUCTIONS.md +124 -0
- package/guides/AI_GUIDE.md +53 -0
- package/guides/CSS_GUIDE.md +1016 -0
- package/guides/DATASTAR_TY_GUIDE.md +657 -0
- package/guides/ICONS_GUIDE.md +212 -0
- package/guides/TY_GUIDE.md +935 -0
- package/guides/clj/CLOJURESCRIPT_GUIDE.md +300 -0
- package/guides/clj/CODE_SPLITTING.md +279 -0
- package/guides/clj/COMPONENT_GUIDE.md +391 -0
- package/guides/clj/HELIX_TY_GUIDE.md +428 -0
- package/guides/clj/I18N_GUIDE.md +478 -0
- package/guides/clj/LAYOUT_GUIDE.md +273 -0
- package/guides/clj/QUICKSTART.md +266 -0
- package/guides/clj/REAGENT_TY_GUIDE.md +408 -0
- package/guides/clj/REPLICANT_TY_GUIDE.md +623 -0
- package/guides/clj/ROUTING_GUIDE.md +346 -0
- package/guides/clj/UIX_TY_GUIDE.md +319 -0
- package/guides/js/HTMX_TY_GUIDE.md +252 -0
- package/guides/js/JAVASCRIPT_GUIDE.md +388 -0
- package/guides/js/REACT_TY_GUIDE.md +983 -0
- package/guides/js/SVELTE_TY_GUIDE.md +682 -0
- package/guides/js/TYCOMPONENT_GUIDE.md +962 -0
- package/guides/js/VUE_TY_GUIDE.md +738 -0
- package/lib/base/ty-component.d.ts +57 -13
- package/lib/base/ty-component.js +266 -292
- package/lib/components/button.d.ts +42 -18
- package/lib/components/button.js +318 -235
- 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 +122 -0
- package/lib/components/file-upload.js +451 -0
- package/lib/components/icon.d.ts +3 -24
- package/lib/components/icon.js +141 -230
- package/lib/components/input.d.ts +93 -108
- package/lib/components/input.js +734 -710
- package/lib/components/modal.d.ts +39 -29
- package/lib/components/modal.js +419 -438
- package/lib/components/option.d.ts +20 -35
- package/lib/components/option.js +184 -309
- package/lib/components/popup.d.ts +2 -17
- package/lib/components/popup.js +353 -347
- package/lib/components/radio.d.ts +33 -25
- package/lib/components/radio.js +433 -422
- package/lib/components/resize-observer.d.ts +3 -30
- package/lib/components/resize-observer.js +71 -103
- package/lib/components/scroll-container.d.ts +21 -14
- package/lib/components/scroll-container.js +292 -234
- package/lib/components/select.d.ts +446 -0
- package/lib/components/select.js +1381 -0
- package/lib/components/selected-tags.d.ts +60 -0
- package/lib/components/selected-tags.js +225 -0
- package/lib/components/sortable.d.ts +175 -0
- package/lib/components/sortable.js +1844 -0
- package/lib/components/step.d.ts +1 -6
- package/lib/components/step.js +62 -68
- package/lib/components/switch.d.ts +15 -15
- package/lib/components/switch.js +237 -231
- package/lib/components/tab.d.ts +50 -7
- package/lib/components/tab.js +203 -69
- package/lib/components/tabs.d.ts +19 -64
- package/lib/components/tabs.js +600 -618
- package/lib/components/tag.d.ts +17 -55
- package/lib/components/tag.js +235 -308
- 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 +15 -4
- package/lib/index.js +28 -38
- package/lib/styles/button.d.ts +24 -7
- package/lib/styles/button.js +298 -417
- package/lib/styles/calendar-month.d.ts +7 -6
- package/lib/styles/calendar-month.js +157 -179
- package/lib/styles/calendar-navigation.d.ts +2 -6
- package/lib/styles/calendar-navigation.js +108 -109
- 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 +320 -352
- 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 -0
- package/lib/styles/file-upload.js +196 -0
- package/lib/styles/icon.d.ts +2 -6
- package/lib/styles/icon.js +92 -170
- package/lib/styles/input.d.ts +4 -7
- package/lib/styles/input.js +148 -643
- package/lib/styles/modal.d.ts +1 -2
- package/lib/styles/modal.js +127 -108
- package/lib/styles/option.d.ts +2 -6
- package/lib/styles/option.js +53 -96
- package/lib/styles/popup.d.ts +1 -2
- package/lib/styles/popup.js +47 -77
- package/lib/styles/radio.d.ts +3 -2
- package/lib/styles/radio.js +90 -116
- package/lib/styles/resize-observer.d.ts +1 -2
- package/lib/styles/resize-observer.js +2 -12
- package/lib/styles/scroll-container.d.ts +1 -2
- package/lib/styles/scroll-container.js +103 -146
- package/lib/styles/select-base.d.ts +8 -0
- package/lib/styles/select-base.js +747 -0
- package/lib/styles/select.d.ts +11 -0
- package/lib/styles/select.js +229 -0
- package/lib/styles/sortable.d.ts +16 -0
- package/lib/styles/sortable.js +85 -0
- package/lib/styles/step.d.ts +1 -2
- package/lib/styles/step.js +15 -34
- package/lib/styles/switch.d.ts +3 -2
- package/lib/styles/switch.js +52 -68
- package/lib/styles/tab.d.ts +1 -2
- package/lib/styles/tab.js +86 -34
- package/lib/styles/tabs.d.ts +3 -11
- package/lib/styles/tabs.js +204 -162
- package/lib/styles/tag.d.ts +2 -6
- package/lib/styles/tag.js +170 -359
- 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 +34 -0
- package/lib/utils/loader-registry.js +11 -0
- 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 -402
- package/lib/components/dropdown.d.ts.map +0 -1
- package/lib/components/dropdown.js +0 -1564
- package/lib/components/dropdown.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 -397
- package/lib/components/multiselect.d.ts.map +0 -1
- package/lib/components/multiselect.js +0 -1580
- 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 -983
- package/lib/styles/dropdown.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 -774
- 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/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,428 @@
|
|
|
1
|
+
# Helix + Tyrell Guide
|
|
2
|
+
|
|
3
|
+
[Helix](https://github.com/lilactown/helix) is a thin macro layer over React with a JSX-feeling API: `defnc` for components, `$` for component instantiation, `(d/div …)` for DOM elements, and `helix.hooks` for the React hooks. Props stay camelCase to match the underlying React contract — Helix doesn't auto-translate prop names. This is the framework Toddler was built on, so if you came from Toddler the muscle memory carries over.
|
|
4
|
+
|
|
5
|
+
Tyrell ships React wrappers via `tyrell.react`, so `($ ty/Input {:onChange h})` works the same way it does in any React-land — and `e.detail.value` is the access path because the wrapper forwards the native `CustomEvent`.
|
|
6
|
+
|
|
7
|
+
For shadow-cljs, CSS, and icon basics, see [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md). Working example: [`examples/helix/`](../../examples/helix/).
|
|
8
|
+
|
|
9
|
+
## Setup
|
|
10
|
+
|
|
11
|
+
`deps.edn`:
|
|
12
|
+
|
|
13
|
+
```clojure
|
|
14
|
+
{:deps {lilactown/helix {:mvn/version "0.2.0"}
|
|
15
|
+
dev.gersak/tyrell {:mvn/version "1.0.0-RC20"}
|
|
16
|
+
dev.gersak/tyrell-icons-lucide {:mvn/version "1.0.0-RC20"}}} ; tyrell.lucide
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`tyrell.react` is part of `dev.gersak/tyrell`; install React + the wrapper package via npm:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install react@18 react-dom@18 tyrell-react
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Helix doesn't ship a React DOM render helper of its own — use `react-dom/client` directly:
|
|
26
|
+
|
|
27
|
+
```clojure
|
|
28
|
+
(:require ["react-dom/client" :as rdom])
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Load the CSS:
|
|
32
|
+
|
|
33
|
+
```html
|
|
34
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell.css">
|
|
35
|
+
<!-- tyrell-theme.css: auto-contrast, seed-based rebranding, themes. See TY_GUIDE.md#quick-start -->
|
|
36
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tyrell-components/css/tyrell-theme.css">
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Mount
|
|
40
|
+
|
|
41
|
+
```clojure
|
|
42
|
+
(ns my-app.core
|
|
43
|
+
(:require [tyrell.components] ; side-effect: registers all <ty-*> elements
|
|
44
|
+
[tyrell.react :as ty]
|
|
45
|
+
[tyrell.icons :as icons]
|
|
46
|
+
[tyrell.lucide :as lucide]
|
|
47
|
+
[helix.core :refer [defnc $ <>]]
|
|
48
|
+
[helix.dom :as d]
|
|
49
|
+
[helix.hooks :as hooks]
|
|
50
|
+
["react-dom/client" :as rdom]))
|
|
51
|
+
|
|
52
|
+
(defnc app []
|
|
53
|
+
(d/div {:class "ty-canvas min-h-screen p-8"}
|
|
54
|
+
($ ty/Button {:flavor "primary"} "Hello")))
|
|
55
|
+
|
|
56
|
+
(defonce root
|
|
57
|
+
(rdom/createRoot (.getElementById js/document "app")))
|
|
58
|
+
|
|
59
|
+
(defn render! []
|
|
60
|
+
(.render root ($ app)))
|
|
61
|
+
|
|
62
|
+
(defn ^:export init []
|
|
63
|
+
(icons/register! {:check lucide/check})
|
|
64
|
+
(render!))
|
|
65
|
+
|
|
66
|
+
(defn ^:after-load reload []
|
|
67
|
+
(render!))
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`defonce` on the root is mandatory for hot reload — recreating the React root on every save throws.
|
|
71
|
+
|
|
72
|
+
## Components — `defnc`, `$`, `d/`
|
|
73
|
+
|
|
74
|
+
Helix splits the syntax cleanly:
|
|
75
|
+
|
|
76
|
+
- `(defnc my-comp [props] …)` defines a function component. `props` is a CLJS map you destructure with `{:keys [...]}`.
|
|
77
|
+
- `($ Component {…} children)` creates an element from a component (Helix's own `defnc` components, or React components like `tyrell.react/Button`).
|
|
78
|
+
- `(d/div {…} children)` creates a DOM element. Each HTML tag has a corresponding `d/` function — `d/section`, `d/form`, `d/label`, etc.
|
|
79
|
+
|
|
80
|
+
```clojure
|
|
81
|
+
(defnc labeled-input [{:keys [label value onChange]}]
|
|
82
|
+
(d/div {:class "flex flex-col gap-1"}
|
|
83
|
+
(d/label {:class "ty-text+"} label)
|
|
84
|
+
($ ty/Input {:value value :onChange onChange})))
|
|
85
|
+
|
|
86
|
+
(defnc form []
|
|
87
|
+
(let [[email setEmail] (hooks/use-state "")]
|
|
88
|
+
($ labeled-input
|
|
89
|
+
{:label "Email"
|
|
90
|
+
:value email
|
|
91
|
+
:onChange #(setEmail (.. % -detail -value))})))
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
**Props are camelCase.** Helix does *not* convert `:on-change` → `onChange` for you. Write the React-native form:
|
|
95
|
+
|
|
96
|
+
```clojure
|
|
97
|
+
($ ty/Input {:onChange handler ; not :on-change
|
|
98
|
+
:className "w-full" ; not :class on $-components for React
|
|
99
|
+
:value v})
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
For DOM elements via `d/`, you can use `:class` (Helix's `d/` macros do convert it to `className` under the hood) and either case form for events — Helix accepts `:on-click` on `d/button`. The asymmetry is jarring at first; the rule is: **`d/*` forgives, `$ Component` doesn't.**
|
|
103
|
+
|
|
104
|
+
## State — `helix.hooks`
|
|
105
|
+
|
|
106
|
+
`helix.hooks` mirrors React's hook API. The setter naming convention in the example uses `setX` (camelCase, JS-style) rather than `set-x`, matching the JSX feel:
|
|
107
|
+
|
|
108
|
+
```clojure
|
|
109
|
+
(defnc counter []
|
|
110
|
+
(let [[n setN] (hooks/use-state 0)]
|
|
111
|
+
(d/div {:class "flex items-center gap-2"}
|
|
112
|
+
($ ty/Button {:flavor "primary" :onClick #(setN inc)} "Inc")
|
|
113
|
+
(d/span {:class "ty-text++ text-xl"} n))))
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Side effects — `helix.hooks/use-effect` takes a deps vector first, body second (opposite of UIx, which takes the function first):
|
|
117
|
+
|
|
118
|
+
```clojure
|
|
119
|
+
(hooks/use-effect [n]
|
|
120
|
+
(set! (.-title js/document) (str "Count: " n))
|
|
121
|
+
;; Return cleanup, if any
|
|
122
|
+
(fn [] (js/console.log "unmount")))
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Helix has a useful shortcut — `:auto-deps` — that lets the macro infer the dependency vector from referenced symbols:
|
|
126
|
+
|
|
127
|
+
```clojure
|
|
128
|
+
(hooks/use-callback :auto-deps
|
|
129
|
+
(fn [k v]
|
|
130
|
+
(setProfile #(assoc % k v))))
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
`use-ref`, `use-memo`, `use-callback`, `use-context` all live in `helix.hooks`. Because `helix.hooks` is a namespace and not magic, you'll also see `(:require [helix.hooks :as hooks])` in real code.
|
|
134
|
+
|
|
135
|
+
## Event handling — `event.detail.value`
|
|
136
|
+
|
|
137
|
+
The wrapper hands you the native `CustomEvent`:
|
|
138
|
+
|
|
139
|
+
```clojure
|
|
140
|
+
($ ty/Input
|
|
141
|
+
{:label "Email"
|
|
142
|
+
:type "email"
|
|
143
|
+
:value (:email profile)
|
|
144
|
+
:error (:email errors)
|
|
145
|
+
:onChange #(setProfile (fn [p] (assoc p :email (.. % -detail -value))))}
|
|
146
|
+
($ ty/Icon {:slot "start" :name "mail"}))
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
| Component | Access |
|
|
150
|
+
|---|---|
|
|
151
|
+
| `ty/Input`, `ty/Textarea`, `ty/Switch`, `ty/DatePicker` | `(.. e -detail -value)` |
|
|
152
|
+
| `ty/Checkbox` | `(.. e -detail -checked)` |
|
|
153
|
+
| `ty/Select` | `(.. e -detail -value)`; with `:multiple`, `(.. e -detail -values)` → JS array |
|
|
154
|
+
| `ty/RadioGroup` | `(.. e -detail -value)` |
|
|
155
|
+
| `ty/Tabs` | `(.. e -detail -tab)` |
|
|
156
|
+
| `ty/Sortable` | `(.. e -detail -value)` → `{key, group, source, from, to, order}` |
|
|
157
|
+
|
|
158
|
+
For `Select` with `:multiple`, convert the JS array:
|
|
159
|
+
|
|
160
|
+
```clojure
|
|
161
|
+
:onChange (fn [^js e]
|
|
162
|
+
(let [vs (.. e -detail -values)]
|
|
163
|
+
(setSkills (vec vs))))
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Composition — `$ ty/X` with slotted children
|
|
167
|
+
|
|
168
|
+
Children come after the props map. `:slot` tells the host component where to render them:
|
|
169
|
+
|
|
170
|
+
```clojure
|
|
171
|
+
($ ty/Input
|
|
172
|
+
{:label "Search"
|
|
173
|
+
:value q
|
|
174
|
+
:onChange #(setQ (.. % -detail -value))}
|
|
175
|
+
($ ty/Icon {:slot "start" :name "search"}))
|
|
176
|
+
|
|
177
|
+
($ ty/Select
|
|
178
|
+
{:label "Country"
|
|
179
|
+
:value country
|
|
180
|
+
:onChange #(setCountry (.. % -detail -value))}
|
|
181
|
+
($ ty/Option {:value "us"} "United States")
|
|
182
|
+
($ ty/Option {:value "de"} "Germany"))
|
|
183
|
+
|
|
184
|
+
($ ty/Select
|
|
185
|
+
{:label "Skills"
|
|
186
|
+
:multiple true
|
|
187
|
+
:value (str/join "," skills)
|
|
188
|
+
:onChange #(setSkills (vec (.. % -detail -values)))}
|
|
189
|
+
($ ty/Option {:value "clojure" :flavor "primary"} "Clojure")
|
|
190
|
+
($ ty/Option {:value "react" :flavor "primary"} "React"))
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
`<>` from `helix.core` gives you a fragment when you need to return siblings without a wrapper:
|
|
194
|
+
|
|
195
|
+
```clojure
|
|
196
|
+
(defnc badges [{:keys [items]}]
|
|
197
|
+
(<>
|
|
198
|
+
(for [i items]
|
|
199
|
+
($ ty/Tag {:key (:id i) :value (:value i)} (:label i)))))
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## Refs — modal control
|
|
203
|
+
|
|
204
|
+
`use-ref` returns an object with a `.current` property — same as React. The wrapper forwards refs to the underlying custom element, so `.show()` / `.hide()` are available:
|
|
205
|
+
|
|
206
|
+
```clojure
|
|
207
|
+
(defnc modal-demo []
|
|
208
|
+
(let [modal-ref (hooks/use-ref nil)
|
|
209
|
+
open-modal (hooks/use-callback :auto-deps
|
|
210
|
+
(fn [_]
|
|
211
|
+
(when-let [^js m (.-current modal-ref)]
|
|
212
|
+
(.show m))))
|
|
213
|
+
close-modal (hooks/use-callback :auto-deps
|
|
214
|
+
(fn [_]
|
|
215
|
+
(when-let [^js m (.-current modal-ref)]
|
|
216
|
+
(.hide m))))]
|
|
217
|
+
(d/div nil
|
|
218
|
+
($ ty/Button {:flavor "primary" :onClick open-modal} "Open")
|
|
219
|
+
($ ty/Modal {:ref modal-ref}
|
|
220
|
+
(d/div {:class "ty-elevated p-6 rounded-2xl"}
|
|
221
|
+
(d/h3 {:class "ty-text++"} "Hello")
|
|
222
|
+
($ ty/Button {:onClick close-modal} "Close"))))))
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
The `^js` type hint on the destructured ref helps the compiler skip externs for `.show` / `.hide`.
|
|
226
|
+
|
|
227
|
+
## Forms — controlled, with form-association
|
|
228
|
+
|
|
229
|
+
Tyrell's form-associated components participate in `<form>` submission via `setFormValue()`. Wrap them in `d/form` and listen for `:onSubmit`:
|
|
230
|
+
|
|
231
|
+
```clojure
|
|
232
|
+
(def empty-profile
|
|
233
|
+
{:name "" :email "" :role "" :news? false})
|
|
234
|
+
|
|
235
|
+
(defn validate [p]
|
|
236
|
+
(cond-> {}
|
|
237
|
+
(str/blank? (:email p))
|
|
238
|
+
(assoc :email "Email is required")
|
|
239
|
+
|
|
240
|
+
(and (not (str/blank? (:email p)))
|
|
241
|
+
(not (re-matches #".+@.+\..+" (:email p))))
|
|
242
|
+
(assoc :email "Doesn't look like an email")))
|
|
243
|
+
|
|
244
|
+
(defnc signup-form []
|
|
245
|
+
(let [[profile setProfile] (hooks/use-state empty-profile)
|
|
246
|
+
[errors setErrors] (hooks/use-state {})
|
|
247
|
+
update-field (hooks/use-callback :auto-deps
|
|
248
|
+
(fn [k v]
|
|
249
|
+
(setProfile #(assoc % k v))
|
|
250
|
+
(setErrors #(dissoc % k))))
|
|
251
|
+
on-submit (hooks/use-callback [profile]
|
|
252
|
+
(fn [^js e]
|
|
253
|
+
(.preventDefault e)
|
|
254
|
+
(let [errs (validate profile)]
|
|
255
|
+
(setErrors errs)
|
|
256
|
+
(when (empty? errs)
|
|
257
|
+
(js/console.log "submit:" (clj->js profile))))))]
|
|
258
|
+
(d/form {:onSubmit on-submit
|
|
259
|
+
:class "ty-elevated p-6 rounded-lg flex flex-col gap-4"}
|
|
260
|
+
($ ty/Input
|
|
261
|
+
{:label "Email"
|
|
262
|
+
:name "email"
|
|
263
|
+
:type "email"
|
|
264
|
+
:required true
|
|
265
|
+
:value (:email profile)
|
|
266
|
+
:error (:email errors)
|
|
267
|
+
:onChange #(update-field :email (.. % -detail -value))})
|
|
268
|
+
|
|
269
|
+
($ ty/Select
|
|
270
|
+
{:label "Role"
|
|
271
|
+
:name "role"
|
|
272
|
+
:value (:role profile)
|
|
273
|
+
:onChange #(update-field :role (.. % -detail -value))}
|
|
274
|
+
($ ty/Option {:value "developer"} "Developer")
|
|
275
|
+
($ ty/Option {:value "designer"} "Designer"))
|
|
276
|
+
|
|
277
|
+
(d/label {:class "flex items-center gap-2 cursor-pointer"}
|
|
278
|
+
($ ty/Checkbox
|
|
279
|
+
{:name "news"
|
|
280
|
+
:checked (:news? profile)
|
|
281
|
+
:onChange #(update-field :news? (.. % -detail -checked))})
|
|
282
|
+
"Subscribe to newsletter")
|
|
283
|
+
|
|
284
|
+
($ ty/Button {:type "submit" :flavor "primary"} "Submit"))))
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
This is essentially the structure of [`examples/helix/src/hello/core.cljs`](../../examples/helix/src/hello/core.cljs) — clone the example to see the same pattern at full scale, including a multiple Select for skills, a DatePicker, a Tooltip, and the imperative-ref modal.
|
|
288
|
+
|
|
289
|
+
## Subscribing to non-React state
|
|
290
|
+
|
|
291
|
+
Helix's hooks-first model means non-React atoms (e.g. `tyrell.router/*router*`) need explicit subscription. Same shape as the UIx hook:
|
|
292
|
+
|
|
293
|
+
```clojure
|
|
294
|
+
(defn use-watch [a]
|
|
295
|
+
(let [[v setV] (hooks/use-state @a)]
|
|
296
|
+
(hooks/use-effect [a]
|
|
297
|
+
(let [k (gensym "helix-watch")]
|
|
298
|
+
(add-watch a k (fn [_ _ _ new] (setV new)))
|
|
299
|
+
(fn [] (remove-watch a k))))
|
|
300
|
+
v))
|
|
301
|
+
|
|
302
|
+
(defnc current-route []
|
|
303
|
+
(let [router (use-watch tyrell.router/*router*)]
|
|
304
|
+
(d/div {:class "ty-text-"} (str "Current: " (:current router)))))
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
## Icons
|
|
308
|
+
|
|
309
|
+
```clojure
|
|
310
|
+
(ns my-app.icons
|
|
311
|
+
(:require [tyrell.icons :as icons]
|
|
312
|
+
[tyrell.lucide :as lucide]))
|
|
313
|
+
|
|
314
|
+
(icons/register! {:check lucide/check
|
|
315
|
+
:user lucide/user}) ; the key is the name
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
Then `($ ty/Icon {:name "check" :size "sm"})`. The registry is global, so one call at init is enough.
|
|
319
|
+
|
|
320
|
+
Sets, tree-shaking, custom SVGs and troubleshooting: [ICONS_GUIDE.md](../ICONS_GUIDE.md#in-clojure).
|
|
321
|
+
|
|
322
|
+
## Calendar and wizard
|
|
323
|
+
|
|
324
|
+
### ty-calendar
|
|
325
|
+
|
|
326
|
+
```clojure
|
|
327
|
+
(defnc calendar-demo []
|
|
328
|
+
(let [now (js/Date.)
|
|
329
|
+
[[year month day] set-date]
|
|
330
|
+
(hooks/use-state [(.getFullYear now)
|
|
331
|
+
(inc (.getMonth now))
|
|
332
|
+
nil])]
|
|
333
|
+
(d/div {:class "flex flex-col gap-4"}
|
|
334
|
+
($ ty/Calendar
|
|
335
|
+
{:year year
|
|
336
|
+
:month month
|
|
337
|
+
:day day
|
|
338
|
+
:onChange (fn [^js e]
|
|
339
|
+
(set-date [(.. e -detail -year)
|
|
340
|
+
(.. e -detail -month)
|
|
341
|
+
(.. e -detail -day)]))})
|
|
342
|
+
(when day
|
|
343
|
+
(d/p {:class "ty-text-"}
|
|
344
|
+
(str "Selected: " year "-" month "-" day))))))
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
Event detail: `{ year, month, day, action, source }`. Form value is ISO `YYYY-MM-DD` when wrapped in `d/form` with a `name` attribute.
|
|
348
|
+
|
|
349
|
+
### ty-wizard
|
|
350
|
+
|
|
351
|
+
```clojure
|
|
352
|
+
(defnc wizard-demo []
|
|
353
|
+
(let [[step setStep] (hooks/use-state "info")
|
|
354
|
+
[completed setCompleted] (hooks/use-state [])
|
|
355
|
+
advance (hooks/use-callback :auto-deps
|
|
356
|
+
(fn [next-id]
|
|
357
|
+
(setCompleted #(conj % step))
|
|
358
|
+
(setStep next-id)))]
|
|
359
|
+
($ ty/Wizard
|
|
360
|
+
{:height "400px"
|
|
361
|
+
:active step
|
|
362
|
+
:completed (str/join "," completed)}
|
|
363
|
+
($ ty/Step {:id "info" :label "Info"}
|
|
364
|
+
(d/div {:class "p-6 flex flex-col gap-4"}
|
|
365
|
+
($ ty/Input {:label "Name" :required true})
|
|
366
|
+
($ ty/Button {:flavor "primary"
|
|
367
|
+
:onClick #(advance "review")} "Next")))
|
|
368
|
+
($ ty/Step {:id "review" :label "Review"}
|
|
369
|
+
(d/div {:class "p-6 flex gap-2"}
|
|
370
|
+
($ ty/Button {:onClick #(setStep "info")} "Back")
|
|
371
|
+
($ ty/Button {:flavor "success"
|
|
372
|
+
:onClick #(advance "done")} "Finish")))
|
|
373
|
+
($ ty/Step {:id "done" :label "Done"}
|
|
374
|
+
(d/div {:class "p-6"} "All done!")))))
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
Event detail: `{ activeId, activeIndex, previousId, previousIndex, direction }`.
|
|
378
|
+
|
|
379
|
+
## Reorderable lists (ty-sortable)
|
|
380
|
+
|
|
381
|
+
`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 React renders the items in the new order. Give each item a `:key` and a `:data-key` (or `:id`):
|
|
382
|
+
|
|
383
|
+
```clojure
|
|
384
|
+
(defnc board []
|
|
385
|
+
(let [[cols setCols] (hooks/use-state {"todo" ["a" "b"] "done" ["c"]})
|
|
386
|
+
[saving? setSaving] (hooks/use-state false)
|
|
387
|
+
on-move (fn [^js e]
|
|
388
|
+
(let [value (.. e -detail -value)]
|
|
389
|
+
(setSaving true)
|
|
390
|
+
(-> (save value)
|
|
391
|
+
(.then #(setCols (fn [c] (merge c (js->clj (.-order value))))))
|
|
392
|
+
(.finally #(setSaving false))))) ; order unchanged: snaps back
|
|
393
|
+
column (fn [id label]
|
|
394
|
+
($ ty/Sortable {:key id :id id :group "board" :label label
|
|
395
|
+
:aria-busy (when saving? "true")
|
|
396
|
+
:onChange on-move}
|
|
397
|
+
(for [k (get cols id)]
|
|
398
|
+
(d/div {:key k :data-key k}
|
|
399
|
+
(d/button {:type "button" :data-handle "" :aria-label (str "Move " k)}
|
|
400
|
+
($ ty/Icon {:name "grip-vertical"}))
|
|
401
|
+
k))))]
|
|
402
|
+
(<> (column "todo" "To do") (column "done" "Done"))))
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
- `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.
|
|
406
|
+
- `: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.
|
|
407
|
+
- 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.
|
|
408
|
+
- Props (camelCase, as for every `$` wrapper): `:group`, `:axis`, `:handle`, `:accepts`, `:disabled`, `:keyAttr`, `:holdTimeout`, `:label`, `:canDrop`, `:labels`, and `:onStart` / `:onCancel` / `:onSettle`.
|
|
409
|
+
|
|
410
|
+
---
|
|
411
|
+
|
|
412
|
+
## Common pitfalls
|
|
413
|
+
|
|
414
|
+
- **camelCase props on `$ Component`** — `:on-click` on a Tyrell wrapper component **does nothing**. It must be `:onClick`. Helix passes props through verbatim. The compiler won't warn.
|
|
415
|
+
- **`:class` on `$ Component`** — same rule: `:className` is the React prop name. `d/*` macros translate `:class`, but `$` does not.
|
|
416
|
+
- **`use-effect` deps are first, body is rest** — opposite of UIx. `(hooks/use-effect [n] body…)`. Easy to flip.
|
|
417
|
+
- **`:auto-deps` is a literal keyword** — not a value the macro infers. Pass `:auto-deps` as the *first* argument to `use-effect` / `use-callback` / `use-memo` to let Helix derive the dep vector by static analysis. Use it when the deps are obvious; provide an explicit vector when they aren't.
|
|
418
|
+
- **Don't pass CLJS data structures as wrapper props** unless you know the wrapper accepts them. `Select`'s `:value` with `:multiple` expects a comma string or JS array, not a CLJS vector.
|
|
419
|
+
- **Children of `Select`** must be `ty/Option` (or raw `<ty-option>`) — not native HTML `<option>`s or `ty/Tag`. The selection is the select's `:value`; `:selected` on an option does nothing without `:externalSelection`.
|
|
420
|
+
- **Setter naming is just convention** — `setProfile` vs `set-profile`. The example uses camelCase to match the JS-React feel; both compile.
|
|
421
|
+
|
|
422
|
+
## See also
|
|
423
|
+
|
|
424
|
+
- [QUICKSTART.md](QUICKSTART.md) — Track A entry point
|
|
425
|
+
- [CLOJURESCRIPT_GUIDE.md](CLOJURESCRIPT_GUIDE.md) — substrate (deps, CSS, shadow-cljs)
|
|
426
|
+
- [UIX_TY_GUIDE.md](UIX_TY_GUIDE.md) — same wrappers, kebab-case props, auto camelCase translation
|
|
427
|
+
- [REAGENT_TY_GUIDE.md](REAGENT_TY_GUIDE.md) — same wrappers, hiccup-and-`r/atom` model
|
|
428
|
+
- [`examples/helix/`](../../examples/helix/) — single-file demo: form, modal, tooltip, multiselect, live-state pane
|