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,962 @@
|
|
|
1
|
+
# Building Web Components with TyComponent
|
|
2
|
+
|
|
3
|
+
## 🎯 Overview
|
|
4
|
+
|
|
5
|
+
**TyComponent** is an abstract base class that provides a unified, declarative property/attribute lifecycle for web components. It eliminates boilerplate code, ensures consistency, and makes components predictable and easy to maintain.
|
|
6
|
+
|
|
7
|
+
> The examples below use `ty-select` as the running case study of TyComponent internals — the same patterns apply to every ty component.
|
|
8
|
+
|
|
9
|
+
### Key Benefits
|
|
10
|
+
|
|
11
|
+
✅ **Single Code Path** - All property updates flow through one lifecycle
|
|
12
|
+
✅ **Declarative Configuration** - Define properties once, not in multiple places
|
|
13
|
+
✅ **Predictable Updates** - State → Render → Events (always in this order)
|
|
14
|
+
✅ **Smart Rendering** - Only render when visual properties change
|
|
15
|
+
✅ **Framework Agnostic** - Works with React, Vue, Reagent, vanilla JS
|
|
16
|
+
✅ **Form Integration** - Built-in ElementInternals support
|
|
17
|
+
✅ **Property Validation** - Automatic type coercion and validation
|
|
18
|
+
✅ **Attribute Aliases** - Extra attribute names that set a property to a fixed value
|
|
19
|
+
✅ **Dual Event System** - Separate 'prop:change' and 'change' events for clarity
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 📦 Architecture
|
|
24
|
+
|
|
25
|
+
### The Unified Property Lifecycle
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
Property Update (via attribute or property setter)
|
|
29
|
+
↓
|
|
30
|
+
PropertyManager.updateProperty()
|
|
31
|
+
↓
|
|
32
|
+
[Validation & Coercion]
|
|
33
|
+
↓
|
|
34
|
+
PropertyChange emitted
|
|
35
|
+
↓
|
|
36
|
+
TyComponent._handlePropertyChanges()
|
|
37
|
+
↓
|
|
38
|
+
┌─────────────────────────────────────┐
|
|
39
|
+
│ 1. onPropertiesChanged() hook │ ← Update internal state
|
|
40
|
+
│ 2. updateFormValue() (if formValue) │ ← Sync to form
|
|
41
|
+
│ 3. render() (if visual changed) │ ← Update DOM
|
|
42
|
+
│ 4. Emit 'change' event (if needed) │ ← Notify listeners
|
|
43
|
+
└─────────────────────────────────────┘
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Core Components
|
|
47
|
+
|
|
48
|
+
1. **PropertyManager** (`/utils/property-manager.ts`)
|
|
49
|
+
- Stores property values in a Map
|
|
50
|
+
- Handles type coercion (string/boolean/number/object/array)
|
|
51
|
+
- Validates property values
|
|
52
|
+
- Tracks property changes
|
|
53
|
+
|
|
54
|
+
2. **TyComponent** (`/base/ty-component.ts`)
|
|
55
|
+
- Base class for all components
|
|
56
|
+
- Unified `attributeChangedCallback`
|
|
57
|
+
- Automatic property capture for React/Reagent
|
|
58
|
+
- Lifecycle hooks (onConnect, onDisconnect, onPropertiesChanged)
|
|
59
|
+
- Form value handling via ElementInternals
|
|
60
|
+
|
|
61
|
+
3. **Your Component** (extends TyComponent)
|
|
62
|
+
- Property configuration
|
|
63
|
+
- Property accessors (getters/setters)
|
|
64
|
+
- Internal state management
|
|
65
|
+
- Render implementation
|
|
66
|
+
|
|
67
|
+
### Event System: `prop:change` vs `change`
|
|
68
|
+
|
|
69
|
+
TyComponent uses **two distinct event types** to avoid conflicts:
|
|
70
|
+
|
|
71
|
+
**`prop:change`** - Property Change Events
|
|
72
|
+
- Emitted when properties marked with `emitChange: true` change
|
|
73
|
+
- Triggered by: attribute changes, property setters, external updates
|
|
74
|
+
- Detail: `{ property: 'name', oldValue: any, newValue: any }`
|
|
75
|
+
- Use case: Reactive frameworks, property watchers, debugging
|
|
76
|
+
- Example: `<ty-select onPropChange={...} />` in React
|
|
77
|
+
|
|
78
|
+
**`change`** - User Interaction Events
|
|
79
|
+
- Emitted by component business logic (manually dispatched)
|
|
80
|
+
- Triggered by: user clicks, selections, form interactions
|
|
81
|
+
- Detail: Component-specific (e.g., ty-select emits `{ value, values, items, action, item }` — `value` is a scalar for single select, an array with `multiple`)
|
|
82
|
+
- Use case: Application logic, form handling, user actions
|
|
83
|
+
- Example: `<ty-select onChange={...} />` in React
|
|
84
|
+
|
|
85
|
+
**Why separate events?**
|
|
86
|
+
```javascript
|
|
87
|
+
// React example - clear distinction
|
|
88
|
+
<ty-select
|
|
89
|
+
// Listen to user interactions
|
|
90
|
+
onChange={(e) => console.log('User selected:', e.detail.value)}
|
|
91
|
+
|
|
92
|
+
// Listen to any property changes (including programmatic)
|
|
93
|
+
onPropChange={(e) => console.log('Value changed:', e.detail.newValue)}
|
|
94
|
+
/>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
This prevents double-event issues where frameworks would receive both property updates AND user interaction events for the same action.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## 🚀 Step-by-Step Guide
|
|
102
|
+
|
|
103
|
+
### Step 1: Extend TyComponent
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
import { TyComponent } from '../base/ty-component.js'
|
|
107
|
+
import type { PropertyChange } from '../utils/property-manager.js'
|
|
108
|
+
import type { Flavor, Size } from '../types/common.js'
|
|
109
|
+
|
|
110
|
+
// Define your component's internal state interface
|
|
111
|
+
interface SelectState {
|
|
112
|
+
open: boolean
|
|
113
|
+
search: string
|
|
114
|
+
highlightedIndex: number
|
|
115
|
+
filteredOptions: OptionData[]
|
|
116
|
+
currentValue: string | null
|
|
117
|
+
mode: 'desktop' | 'mobile'
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
export class TySelect extends TyComponent<SelectState> {
|
|
121
|
+
// Component implementation here...
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Step 2: Configure Properties (Declarative)
|
|
126
|
+
|
|
127
|
+
This is the **most important part** - define all your properties in one place:
|
|
128
|
+
|
|
129
|
+
```typescript
|
|
130
|
+
export class TySelect extends TyComponent<SelectState> {
|
|
131
|
+
// ============================================================================
|
|
132
|
+
// PROPERTY CONFIGURATION - Single source of truth
|
|
133
|
+
// ============================================================================
|
|
134
|
+
protected static properties = {
|
|
135
|
+
// String property with form value and property change events
|
|
136
|
+
value: {
|
|
137
|
+
type: 'string' as const,
|
|
138
|
+
visual: true, // Triggers render when changed
|
|
139
|
+
formValue: true, // Syncs to form value
|
|
140
|
+
emitChange: true, // Emits 'prop:change' event (separate from user 'change')
|
|
141
|
+
default: '' // Default value
|
|
142
|
+
},
|
|
143
|
+
|
|
144
|
+
// String property (non-visual)
|
|
145
|
+
name: {
|
|
146
|
+
type: 'string' as const,
|
|
147
|
+
default: ''
|
|
148
|
+
},
|
|
149
|
+
|
|
150
|
+
// String property with visual impact
|
|
151
|
+
placeholder: {
|
|
152
|
+
type: 'string' as const,
|
|
153
|
+
visual: true,
|
|
154
|
+
default: 'Select...'
|
|
155
|
+
},
|
|
156
|
+
|
|
157
|
+
// Boolean property
|
|
158
|
+
disabled: {
|
|
159
|
+
type: 'boolean' as const,
|
|
160
|
+
visual: true,
|
|
161
|
+
default: false
|
|
162
|
+
},
|
|
163
|
+
|
|
164
|
+
// camelCase property ↔ kebab-case attribute: <ty-select external-search>
|
|
165
|
+
externalSearch: {
|
|
166
|
+
type: 'boolean' as const,
|
|
167
|
+
visual: true,
|
|
168
|
+
default: false
|
|
169
|
+
},
|
|
170
|
+
|
|
171
|
+
// String property with validation
|
|
172
|
+
size: {
|
|
173
|
+
type: 'string' as const,
|
|
174
|
+
visual: true,
|
|
175
|
+
default: 'md',
|
|
176
|
+
validate: (v: any) => ['sm', 'md', 'lg'].includes(v),
|
|
177
|
+
coerce: (v: any) => {
|
|
178
|
+
if (!['sm', 'md', 'lg'].includes(v)) {
|
|
179
|
+
console.warn(`[ty-select] Invalid size. Using md.`)
|
|
180
|
+
return 'md'
|
|
181
|
+
}
|
|
182
|
+
return v
|
|
183
|
+
}
|
|
184
|
+
},
|
|
185
|
+
|
|
186
|
+
// Number property with bounds
|
|
187
|
+
debounce: {
|
|
188
|
+
type: 'number' as const,
|
|
189
|
+
default: 0,
|
|
190
|
+
validate: (v: any) => v >= 0 && v <= 5000,
|
|
191
|
+
coerce: (v: any) => {
|
|
192
|
+
const num = Number(v)
|
|
193
|
+
if (isNaN(num)) return 0
|
|
194
|
+
return Math.max(0, Math.min(5000, num))
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
#### Property Configuration Options
|
|
202
|
+
|
|
203
|
+
| Option | Type | Description |
|
|
204
|
+
|--------|------|-------------|
|
|
205
|
+
| `type` | `'string' \| 'boolean' \| 'number' \| 'object' \| 'array'` | Data type for automatic coercion |
|
|
206
|
+
| `visual` | `boolean` | If true, changing this property triggers `render()` |
|
|
207
|
+
| `formValue` | `boolean` | If true, changing this property updates form value |
|
|
208
|
+
| `emitChange` | `boolean` | If true, changing this property emits 'prop:change' event (distinct from user 'change' events) |
|
|
209
|
+
| `default` | `any` | Default value when property is undefined |
|
|
210
|
+
| `validate` | `(value: any) => boolean` | Custom validation function |
|
|
211
|
+
| `coerce` | `(value: any) => any` | Custom coercion/transformation function |
|
|
212
|
+
|
|
213
|
+
### Step 3: Create Property Accessors (Simple!)
|
|
214
|
+
|
|
215
|
+
These are **simple wrappers** with **no logic** - TyComponent handles everything:
|
|
216
|
+
|
|
217
|
+
```typescript
|
|
218
|
+
export class TySelect extends TyComponent<SelectState> {
|
|
219
|
+
// ... property configuration ...
|
|
220
|
+
|
|
221
|
+
// ============================================================================
|
|
222
|
+
// PROPERTY ACCESSORS - Just call getProperty/setProperty
|
|
223
|
+
// ============================================================================
|
|
224
|
+
|
|
225
|
+
get value(): string {
|
|
226
|
+
return this.getProperty('value')
|
|
227
|
+
}
|
|
228
|
+
set value(v: string) {
|
|
229
|
+
this.setProperty('value', v)
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
get placeholder(): string {
|
|
233
|
+
return this.getProperty('placeholder')
|
|
234
|
+
}
|
|
235
|
+
set placeholder(v: string) {
|
|
236
|
+
this.setProperty('placeholder', v)
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
get disabled(): boolean {
|
|
240
|
+
return this.getProperty('disabled')
|
|
241
|
+
}
|
|
242
|
+
set disabled(v: boolean) {
|
|
243
|
+
this.setProperty('disabled', v)
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
get externalSearch(): boolean {
|
|
247
|
+
return this.getProperty('externalSearch')
|
|
248
|
+
}
|
|
249
|
+
set externalSearch(v: boolean) {
|
|
250
|
+
this.setProperty('externalSearch', v)
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
get size(): Size {
|
|
254
|
+
return this.getProperty('size') as Size
|
|
255
|
+
}
|
|
256
|
+
set size(v: Size) {
|
|
257
|
+
this.setProperty('size', v)
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
get debounce(): number {
|
|
261
|
+
return this.getProperty('debounce')
|
|
262
|
+
}
|
|
263
|
+
set debounce(v: number) {
|
|
264
|
+
this.setProperty('debounce', v)
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
**Important**: Property accessors should **never** contain logic. All validation, coercion, and side effects are handled by PropertyManager and lifecycle hooks.
|
|
270
|
+
|
|
271
|
+
### Step 4: Initialize Internal State
|
|
272
|
+
|
|
273
|
+
```typescript
|
|
274
|
+
export class TySelect extends TyComponent<SelectState> {
|
|
275
|
+
// ... properties and accessors ...
|
|
276
|
+
|
|
277
|
+
// ============================================================================
|
|
278
|
+
// INTERNAL STATE - Component-specific state
|
|
279
|
+
// ============================================================================
|
|
280
|
+
|
|
281
|
+
private _state: SelectState = {
|
|
282
|
+
open: false,
|
|
283
|
+
search: '',
|
|
284
|
+
highlightedIndex: -1,
|
|
285
|
+
filteredOptions: [],
|
|
286
|
+
currentValue: null,
|
|
287
|
+
mode: isMobileDevice() ? 'mobile' : 'desktop'
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
// Other internal fields (not properties)
|
|
291
|
+
private _scrollLockId: string | null = null
|
|
292
|
+
private _searchDebounceTimer: number | null = null
|
|
293
|
+
}
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
### Step 5: Implement Constructor
|
|
297
|
+
|
|
298
|
+
```typescript
|
|
299
|
+
export class TySelect extends TyComponent<SelectState> {
|
|
300
|
+
// ... properties, accessors, state ...
|
|
301
|
+
|
|
302
|
+
constructor() {
|
|
303
|
+
super() // TyComponent handles attachInternals() and attachShadow()
|
|
304
|
+
|
|
305
|
+
const shadow = this.shadowRoot!
|
|
306
|
+
ensureStyles(shadow, { css: selectStyles, id: 'ty-select' })
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
**Note**: TyComponent's constructor automatically:
|
|
312
|
+
- Creates PropertyManager with your property configuration
|
|
313
|
+
- Calls `attachInternals()` for form association
|
|
314
|
+
- Calls `attachShadow({ mode: 'open' })`
|
|
315
|
+
|
|
316
|
+
### Step 6: Implement Lifecycle Hooks
|
|
317
|
+
|
|
318
|
+
#### `onConnect()` - Called when component connects to DOM
|
|
319
|
+
|
|
320
|
+
Use this instead of overriding `connectedCallback`:
|
|
321
|
+
|
|
322
|
+
```typescript
|
|
323
|
+
protected onConnect(): void {
|
|
324
|
+
// Initialize state
|
|
325
|
+
this.initializeState()
|
|
326
|
+
|
|
327
|
+
// Set up observers, resize listeners, etc.
|
|
328
|
+
this.setupResizeObserver()
|
|
329
|
+
}
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
#### `onDisconnect()` - Called when component disconnects from DOM
|
|
333
|
+
|
|
334
|
+
Use this for cleanup instead of overriding `disconnectedCallback`:
|
|
335
|
+
|
|
336
|
+
```typescript
|
|
337
|
+
protected onDisconnect(): void {
|
|
338
|
+
// Clean up document-level listeners
|
|
339
|
+
const outsideClickHandler = (this as any).tyOutsideClickHandler
|
|
340
|
+
const keyboardHandler = (this as any).tyKeyboardHandler
|
|
341
|
+
|
|
342
|
+
if (outsideClickHandler) {
|
|
343
|
+
document.removeEventListener('click', outsideClickHandler)
|
|
344
|
+
;(this as any).tyOutsideClickHandler = null
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
if (keyboardHandler) {
|
|
348
|
+
document.removeEventListener('keydown', keyboardHandler)
|
|
349
|
+
;(this as any).tyKeyboardHandler = null
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
// Clear any pending timers
|
|
353
|
+
if (this._searchDebounceTimer !== null) {
|
|
354
|
+
clearTimeout(this._searchDebounceTimer)
|
|
355
|
+
this._searchDebounceTimer = null
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
#### `onPropertiesChanged()` - Called when properties change
|
|
361
|
+
|
|
362
|
+
This is where you update internal state **before rendering**:
|
|
363
|
+
|
|
364
|
+
```typescript
|
|
365
|
+
protected onPropertiesChanged(changes: PropertyChange[]): void {
|
|
366
|
+
for (const { name, newValue } of changes) {
|
|
367
|
+
switch (name) {
|
|
368
|
+
case 'value':
|
|
369
|
+
// Update internal state when value changes
|
|
370
|
+
this._state.currentValue = newValue || null
|
|
371
|
+
this.syncSelectedOption()
|
|
372
|
+
break
|
|
373
|
+
|
|
374
|
+
case 'placeholder':
|
|
375
|
+
// Update placeholder in DOM if already rendered
|
|
376
|
+
this.updatePlaceholderInDOM()
|
|
377
|
+
break
|
|
378
|
+
|
|
379
|
+
case 'externalSearch':
|
|
380
|
+
// Update search row visibility
|
|
381
|
+
this.updateSearchRow()
|
|
382
|
+
break
|
|
383
|
+
|
|
384
|
+
case 'disabled':
|
|
385
|
+
// Update disabled state in DOM
|
|
386
|
+
this.updateDisabledState()
|
|
387
|
+
break
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
**Important**:
|
|
394
|
+
- This hook runs **before** `render()`
|
|
395
|
+
- Use it to update `_state` or other internal fields
|
|
396
|
+
- Don't call `render()` manually - TyComponent handles it
|
|
397
|
+
- Only visual properties trigger `render()` automatically
|
|
398
|
+
|
|
399
|
+
### Step 7: Implement Form Value Handling (Optional)
|
|
400
|
+
|
|
401
|
+
If your component is a form control, override `getFormValue()`:
|
|
402
|
+
|
|
403
|
+
```typescript
|
|
404
|
+
protected getFormValue(): FormDataEntryValue | null {
|
|
405
|
+
return this._state.currentValue || null
|
|
406
|
+
}
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
TyComponent automatically:
|
|
410
|
+
- Calls `getFormValue()` when a `formValue: true` property changes
|
|
411
|
+
- Syncs the value to the form via `this._internals.setFormValue()`
|
|
412
|
+
|
|
413
|
+
### Step 8: Implement Render Method
|
|
414
|
+
|
|
415
|
+
This is where you update the DOM. Focus on **pure rendering** - no property synchronization:
|
|
416
|
+
|
|
417
|
+
```typescript
|
|
418
|
+
protected render(): void {
|
|
419
|
+
if (this._state.mode === 'mobile') {
|
|
420
|
+
this.renderMobile()
|
|
421
|
+
} else {
|
|
422
|
+
this.renderDesktop()
|
|
423
|
+
}
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
private renderDesktop(): void {
|
|
427
|
+
const shadow = this.shadowRoot!
|
|
428
|
+
|
|
429
|
+
shadow.innerHTML = `
|
|
430
|
+
<div class="ty-select ${this.size}">
|
|
431
|
+
${this.label ? `<label>${this.label}</label>` : ''}
|
|
432
|
+
<div class="ty-select-trigger">
|
|
433
|
+
<span class="selected-display">${this.placeholder}</span>
|
|
434
|
+
<button class="chevron-btn">▼</button>
|
|
435
|
+
</div>
|
|
436
|
+
<div class="ty-select-popup">
|
|
437
|
+
<!-- Search row + options rendered here -->
|
|
438
|
+
</div>
|
|
439
|
+
</div>
|
|
440
|
+
`
|
|
441
|
+
|
|
442
|
+
// Attach event listeners
|
|
443
|
+
this.attachEventListeners()
|
|
444
|
+
}
|
|
445
|
+
```
|
|
446
|
+
|
|
447
|
+
**Important**:
|
|
448
|
+
- `render()` is called automatically when visual properties change
|
|
449
|
+
- Don't manually sync properties to DOM - they're already in `this.getProperty(name)`
|
|
450
|
+
- Use property getters to access values: `this.placeholder`, `this.disabled`, etc.
|
|
451
|
+
|
|
452
|
+
---
|
|
453
|
+
|
|
454
|
+
## 🎨 Common Patterns
|
|
455
|
+
|
|
456
|
+
### Pattern 1: Default-On Features
|
|
457
|
+
|
|
458
|
+
A feature that's on by default gets a boolean that names the deviation and defaults to `false`, like native `disabled`. Never a `default: true` boolean: frameworks render `false` by dropping the attribute, which would turn it back on.
|
|
459
|
+
|
|
460
|
+
```typescript
|
|
461
|
+
protected static properties = {
|
|
462
|
+
noClear: {
|
|
463
|
+
type: 'boolean' as const,
|
|
464
|
+
visual: true,
|
|
465
|
+
default: false
|
|
466
|
+
}
|
|
467
|
+
}
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
**Usage** (this is how `ty-date-picker` defines its clear button):
|
|
471
|
+
```html
|
|
472
|
+
<ty-date-picker></ty-date-picker> <!-- clear button -->
|
|
473
|
+
<ty-date-picker no-clear></ty-date-picker> <!-- none -->
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
### Pattern 2: Validated String Properties
|
|
477
|
+
|
|
478
|
+
```typescript
|
|
479
|
+
protected static properties = {
|
|
480
|
+
size: {
|
|
481
|
+
type: 'string' as const,
|
|
482
|
+
visual: true,
|
|
483
|
+
default: 'md',
|
|
484
|
+
validate: (v: any) => ['sm', 'md', 'lg'].includes(v),
|
|
485
|
+
coerce: (v: any) => {
|
|
486
|
+
const valid = ['sm', 'md', 'lg']
|
|
487
|
+
if (!valid.includes(v)) {
|
|
488
|
+
console.warn(`[my-component] Invalid size '${v}'. Using 'md'.`)
|
|
489
|
+
return 'md'
|
|
490
|
+
}
|
|
491
|
+
return v
|
|
492
|
+
}
|
|
493
|
+
}
|
|
494
|
+
}
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
### Pattern 3: Number Properties with Bounds
|
|
498
|
+
|
|
499
|
+
```typescript
|
|
500
|
+
protected static properties = {
|
|
501
|
+
debounce: {
|
|
502
|
+
type: 'number' as const,
|
|
503
|
+
default: 0,
|
|
504
|
+
validate: (v: any) => v >= 0 && v <= 5000,
|
|
505
|
+
coerce: (v: any) => {
|
|
506
|
+
const num = Number(v)
|
|
507
|
+
if (isNaN(num)) return 0
|
|
508
|
+
return Math.max(0, Math.min(5000, num))
|
|
509
|
+
}
|
|
510
|
+
}
|
|
511
|
+
}
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
### Pattern 4: Object/Array Properties
|
|
515
|
+
|
|
516
|
+
```typescript
|
|
517
|
+
protected static properties = {
|
|
518
|
+
options: {
|
|
519
|
+
type: 'array' as const,
|
|
520
|
+
visual: true,
|
|
521
|
+
default: [],
|
|
522
|
+
validate: (v: any) => Array.isArray(v),
|
|
523
|
+
coerce: (v: any) => {
|
|
524
|
+
// Handle string attribute: options='[{"value":"1","label":"One"}]'
|
|
525
|
+
if (typeof v === 'string') {
|
|
526
|
+
try {
|
|
527
|
+
return JSON.parse(v)
|
|
528
|
+
} catch {
|
|
529
|
+
console.warn('[my-component] Failed to parse options')
|
|
530
|
+
return []
|
|
531
|
+
}
|
|
532
|
+
}
|
|
533
|
+
return Array.isArray(v) ? v : []
|
|
534
|
+
}
|
|
535
|
+
}
|
|
536
|
+
}
|
|
537
|
+
```
|
|
538
|
+
|
|
539
|
+
### Pattern 5: Form-Associated Properties
|
|
540
|
+
|
|
541
|
+
```typescript
|
|
542
|
+
protected static properties = {
|
|
543
|
+
value: {
|
|
544
|
+
type: 'string' as const,
|
|
545
|
+
visual: true,
|
|
546
|
+
formValue: true, // ← Syncs to form
|
|
547
|
+
emitChange: true, // ← Emits 'prop:change' event
|
|
548
|
+
default: ''
|
|
549
|
+
}
|
|
550
|
+
}
|
|
551
|
+
|
|
552
|
+
// Override form value handling if needed
|
|
553
|
+
protected getFormValue(): FormDataEntryValue | null {
|
|
554
|
+
// Can return string, File, or FormData
|
|
555
|
+
return this._state.currentValue || null
|
|
556
|
+
}
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
### Pattern 6: Non-Visual Properties
|
|
560
|
+
|
|
561
|
+
Some properties don't require re-rendering (like `name` or `debounce`):
|
|
562
|
+
|
|
563
|
+
```typescript
|
|
564
|
+
protected static properties = {
|
|
565
|
+
name: {
|
|
566
|
+
type: 'string' as const,
|
|
567
|
+
// No 'visual: true' - changing this doesn't trigger render
|
|
568
|
+
default: ''
|
|
569
|
+
},
|
|
570
|
+
debounce: {
|
|
571
|
+
type: 'number' as const,
|
|
572
|
+
// No 'visual: true' - only affects event emission timing
|
|
573
|
+
default: 0
|
|
574
|
+
}
|
|
575
|
+
}
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
---
|
|
579
|
+
|
|
580
|
+
## 🔍 Real-World Example: TySelect
|
|
581
|
+
|
|
582
|
+
Here's how the actual `TySelect` component is structured:
|
|
583
|
+
|
|
584
|
+
```typescript
|
|
585
|
+
export class TySelect extends TyComponent<SelectState> {
|
|
586
|
+
// ============================================================================
|
|
587
|
+
// 1. PROPERTY CONFIGURATION
|
|
588
|
+
// ============================================================================
|
|
589
|
+
protected static properties = {
|
|
590
|
+
value: {
|
|
591
|
+
type: 'string' as const,
|
|
592
|
+
visual: true,
|
|
593
|
+
formValue: true,
|
|
594
|
+
emitChange: true,
|
|
595
|
+
default: ''
|
|
596
|
+
},
|
|
597
|
+
placeholder: {
|
|
598
|
+
type: 'string' as const,
|
|
599
|
+
visual: true,
|
|
600
|
+
default: 'Select...'
|
|
601
|
+
},
|
|
602
|
+
multiple: {
|
|
603
|
+
type: 'boolean' as const,
|
|
604
|
+
visual: true,
|
|
605
|
+
default: false
|
|
606
|
+
},
|
|
607
|
+
externalSearch: {
|
|
608
|
+
type: 'boolean' as const,
|
|
609
|
+
visual: true,
|
|
610
|
+
default: false
|
|
611
|
+
},
|
|
612
|
+
size: {
|
|
613
|
+
type: 'string' as const,
|
|
614
|
+
visual: true,
|
|
615
|
+
default: 'md',
|
|
616
|
+
validate: (v: any) => ['sm', 'md', 'lg'].includes(v),
|
|
617
|
+
coerce: (v: any) => {
|
|
618
|
+
if (!['sm', 'md', 'lg'].includes(v)) {
|
|
619
|
+
console.warn(`[ty-select] Invalid size. Using md.`)
|
|
620
|
+
return 'md'
|
|
621
|
+
}
|
|
622
|
+
return v
|
|
623
|
+
}
|
|
624
|
+
}
|
|
625
|
+
// ... more properties
|
|
626
|
+
}
|
|
627
|
+
|
|
628
|
+
// ============================================================================
|
|
629
|
+
// 2. INTERNAL STATE
|
|
630
|
+
// ============================================================================
|
|
631
|
+
private _state: SelectState = {
|
|
632
|
+
open: false,
|
|
633
|
+
search: '',
|
|
634
|
+
highlightedIndex: -1,
|
|
635
|
+
filteredOptions: [],
|
|
636
|
+
currentValue: null,
|
|
637
|
+
mode: isMobileDevice() ? 'mobile' : 'desktop'
|
|
638
|
+
}
|
|
639
|
+
|
|
640
|
+
// ============================================================================
|
|
641
|
+
// 3. PROPERTY ACCESSORS (Simple!)
|
|
642
|
+
// ============================================================================
|
|
643
|
+
get value(): string { return this.getProperty('value') }
|
|
644
|
+
set value(v: string) { this.setProperty('value', v) }
|
|
645
|
+
|
|
646
|
+
get placeholder(): string { return this.getProperty('placeholder') }
|
|
647
|
+
set placeholder(v: string) { this.setProperty('placeholder', v) }
|
|
648
|
+
|
|
649
|
+
get multiple(): boolean { return this.getProperty('multiple') }
|
|
650
|
+
set multiple(v: boolean) { this.setProperty('multiple', v) }
|
|
651
|
+
|
|
652
|
+
get externalSearch(): boolean { return this.getProperty('externalSearch') }
|
|
653
|
+
set externalSearch(v: boolean) { this.setProperty('externalSearch', v) }
|
|
654
|
+
|
|
655
|
+
get size(): Size { return this.getProperty('size') as Size }
|
|
656
|
+
set size(v: Size) { this.setProperty('size', v) }
|
|
657
|
+
|
|
658
|
+
// ============================================================================
|
|
659
|
+
// 4. CONSTRUCTOR
|
|
660
|
+
// ============================================================================
|
|
661
|
+
constructor() {
|
|
662
|
+
super()
|
|
663
|
+
const shadow = this.shadowRoot!
|
|
664
|
+
ensureStyles(shadow, { css: selectStyles, id: 'ty-select' })
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
// ============================================================================
|
|
668
|
+
// 5. LIFECYCLE HOOKS
|
|
669
|
+
// ============================================================================
|
|
670
|
+
protected onConnect(): void {
|
|
671
|
+
this.initializeState()
|
|
672
|
+
}
|
|
673
|
+
|
|
674
|
+
protected onDisconnect(): void {
|
|
675
|
+
// Cleanup listeners
|
|
676
|
+
}
|
|
677
|
+
|
|
678
|
+
protected onPropertiesChanged(changes: PropertyChange[]): void {
|
|
679
|
+
for (const { name, newValue } of changes) {
|
|
680
|
+
switch (name) {
|
|
681
|
+
case 'value':
|
|
682
|
+
this._state.currentValue = newValue || null
|
|
683
|
+
this.syncSelectedOption()
|
|
684
|
+
break
|
|
685
|
+
case 'externalSearch':
|
|
686
|
+
this.updateSearchRow()
|
|
687
|
+
break
|
|
688
|
+
}
|
|
689
|
+
}
|
|
690
|
+
}
|
|
691
|
+
|
|
692
|
+
protected getFormValue(): FormDataEntryValue | null {
|
|
693
|
+
return this._state.currentValue || null
|
|
694
|
+
}
|
|
695
|
+
|
|
696
|
+
// ============================================================================
|
|
697
|
+
// 6. RENDER
|
|
698
|
+
// ============================================================================
|
|
699
|
+
protected render(): void {
|
|
700
|
+
if (this._state.mode === 'mobile') {
|
|
701
|
+
this.renderMobile()
|
|
702
|
+
} else {
|
|
703
|
+
this.renderDesktop()
|
|
704
|
+
}
|
|
705
|
+
}
|
|
706
|
+
|
|
707
|
+
private renderDesktop(): void {
|
|
708
|
+
// Pure rendering logic
|
|
709
|
+
}
|
|
710
|
+
|
|
711
|
+
// ============================================================================
|
|
712
|
+
// 7. PRIVATE METHODS (Business Logic)
|
|
713
|
+
// ============================================================================
|
|
714
|
+
private initializeState(): void { /* ... */ }
|
|
715
|
+
private syncSelectedOption(): void { /* ... */ }
|
|
716
|
+
private updateSearchRow(): void { /* ... */ }
|
|
717
|
+
private attachEventListeners(): void { /* ... */ }
|
|
718
|
+
}
|
|
719
|
+
```
|
|
720
|
+
|
|
721
|
+
---
|
|
722
|
+
|
|
723
|
+
## ✅ Best Practices
|
|
724
|
+
|
|
725
|
+
### DO ✅
|
|
726
|
+
|
|
727
|
+
✅ **Use property configuration** for all component properties
|
|
728
|
+
✅ **Keep accessors simple** - just call `getProperty`/`setProperty`
|
|
729
|
+
✅ **Use `onPropertiesChanged`** for state updates before render
|
|
730
|
+
✅ **Mark visual properties** with `visual: true`
|
|
731
|
+
✅ **Mark form properties** with `formValue: true`
|
|
732
|
+
✅ **Provide validation** for properties with constraints
|
|
733
|
+
✅ **Provide coercion** for properties needing transformation
|
|
734
|
+
✅ **Use hooks** (`onConnect`, `onDisconnect`, `onPropertiesChanged`)
|
|
735
|
+
✅ **Focus on pure rendering** in `render()` method
|
|
736
|
+
|
|
737
|
+
### DON'T ❌
|
|
738
|
+
|
|
739
|
+
❌ **Don't put logic in property accessors** - use hooks instead
|
|
740
|
+
❌ **Don't manually call `render()`** - TyComponent handles it
|
|
741
|
+
❌ **Don't manually sync attributes** - TyComponent handles it
|
|
742
|
+
❌ **Don't override lifecycle methods** - use hooks instead
|
|
743
|
+
❌ **Don't update properties inside `render()`** - update in `onPropertiesChanged`
|
|
744
|
+
❌ **Don't forget `super()` in constructor**
|
|
745
|
+
❌ **Don't access `_internals` directly** - use `getFormValue()` hook
|
|
746
|
+
|
|
747
|
+
---
|
|
748
|
+
|
|
749
|
+
## 🧪 Testing Your Component
|
|
750
|
+
|
|
751
|
+
### Property Setting
|
|
752
|
+
|
|
753
|
+
```typescript
|
|
754
|
+
// Via attribute
|
|
755
|
+
select.setAttribute('value', 'test')
|
|
756
|
+
console.assert(select.value === 'test')
|
|
757
|
+
|
|
758
|
+
// Via property
|
|
759
|
+
select.value = 'test2'
|
|
760
|
+
console.assert(select.getAttribute('value') === 'test2')
|
|
761
|
+
|
|
762
|
+
// Before connectedCallback (React pattern)
|
|
763
|
+
const select = document.createElement('ty-select')
|
|
764
|
+
select.value = 'preset' // ← Set before mounting
|
|
765
|
+
document.body.appendChild(select)
|
|
766
|
+
console.assert(select.value === 'preset') // ← Should work!
|
|
767
|
+
```
|
|
768
|
+
|
|
769
|
+
### Boolean Properties
|
|
770
|
+
|
|
771
|
+
```typescript
|
|
772
|
+
// Attribute presence
|
|
773
|
+
select.setAttribute('disabled', '')
|
|
774
|
+
console.assert(select.disabled === true)
|
|
775
|
+
|
|
776
|
+
// Attribute absence
|
|
777
|
+
select.removeAttribute('disabled')
|
|
778
|
+
console.assert(select.disabled === false)
|
|
779
|
+
|
|
780
|
+
// kebab-case attribute → camelCase property
|
|
781
|
+
select.setAttribute('external-search', '')
|
|
782
|
+
console.assert(select.externalSearch === true)
|
|
783
|
+
|
|
784
|
+
// "false" is off, like every boolean attribute here
|
|
785
|
+
select.setAttribute('external-search', 'false')
|
|
786
|
+
console.assert(select.externalSearch === false)
|
|
787
|
+
```
|
|
788
|
+
|
|
789
|
+
### Form Integration
|
|
790
|
+
|
|
791
|
+
```typescript
|
|
792
|
+
const form = document.createElement('form')
|
|
793
|
+
const select = document.createElement('ty-select')
|
|
794
|
+
select.name = 'country'
|
|
795
|
+
select.value = 'us'
|
|
796
|
+
|
|
797
|
+
form.appendChild(select)
|
|
798
|
+
document.body.appendChild(form)
|
|
799
|
+
|
|
800
|
+
const formData = new FormData(form)
|
|
801
|
+
console.assert(formData.get('country') === 'us')
|
|
802
|
+
```
|
|
803
|
+
|
|
804
|
+
### Change Events
|
|
805
|
+
|
|
806
|
+
```typescript
|
|
807
|
+
// Listen to property changes (reactive frameworks)
|
|
808
|
+
select.addEventListener('prop:change', (e) => {
|
|
809
|
+
console.log('Property changed:', e.detail)
|
|
810
|
+
// { property: 'value', oldValue: 'old', newValue: 'new' }
|
|
811
|
+
})
|
|
812
|
+
|
|
813
|
+
// Listen to user interaction changes (business logic)
|
|
814
|
+
select.addEventListener('change', (e) => {
|
|
815
|
+
console.log('User changed:', e.detail)
|
|
816
|
+
// { value: 'new', values: ['new'], items: [...], action: 'add', item: 'new' }
|
|
817
|
+
})
|
|
818
|
+
|
|
819
|
+
select.value = 'new' // ← Triggers 'prop:change' if emitChange: true
|
|
820
|
+
```
|
|
821
|
+
|
|
822
|
+
---
|
|
823
|
+
|
|
824
|
+
## 🎯 Migration Checklist
|
|
825
|
+
|
|
826
|
+
When migrating an existing component to TyComponent:
|
|
827
|
+
|
|
828
|
+
- [ ] Create property configuration object
|
|
829
|
+
- [ ] Remove private field declarations for properties
|
|
830
|
+
- [ ] Simplify property accessors (use get/setProperty)
|
|
831
|
+
- [ ] Remove `observedAttributes` getter (auto-generated)
|
|
832
|
+
- [ ] Remove `attributeChangedCallback` method (inherited)
|
|
833
|
+
- [ ] Remove property capture code from `connectedCallback`
|
|
834
|
+
- [ ] Move initialization to `onConnect()` hook
|
|
835
|
+
- [ ] Move cleanup to `onDisconnect()` hook
|
|
836
|
+
- [ ] Move state updates to `onPropertiesChanged()` hook
|
|
837
|
+
- [ ] Remove manual `setAttribute` calls in setters
|
|
838
|
+
- [ ] Remove manual `render()` calls in setters
|
|
839
|
+
- [ ] Override `getFormValue()` instead of `updateFormValue()`
|
|
840
|
+
- [ ] Test all property setting scenarios
|
|
841
|
+
|
|
842
|
+
---
|
|
843
|
+
|
|
844
|
+
## 🚨 Common Pitfalls
|
|
845
|
+
|
|
846
|
+
### Pitfall 1: Logic in Property Accessors
|
|
847
|
+
|
|
848
|
+
❌ **Wrong**:
|
|
849
|
+
```typescript
|
|
850
|
+
set value(v: string) {
|
|
851
|
+
this.setProperty('value', v)
|
|
852
|
+
this._state.currentValue = v // ← Don't do this here!
|
|
853
|
+
this.render() // ← Don't do this here!
|
|
854
|
+
}
|
|
855
|
+
```
|
|
856
|
+
|
|
857
|
+
✅ **Correct**:
|
|
858
|
+
```typescript
|
|
859
|
+
set value(v: string) {
|
|
860
|
+
this.setProperty('value', v) // ← That's it!
|
|
861
|
+
}
|
|
862
|
+
|
|
863
|
+
protected onPropertiesChanged(changes: PropertyChange[]): void {
|
|
864
|
+
for (const { name, newValue } of changes) {
|
|
865
|
+
if (name === 'value') {
|
|
866
|
+
this._state.currentValue = newValue // ← Do it here instead
|
|
867
|
+
}
|
|
868
|
+
}
|
|
869
|
+
// render() is called automatically by TyComponent
|
|
870
|
+
}
|
|
871
|
+
```
|
|
872
|
+
|
|
873
|
+
### Pitfall 2: Forgetting to Mark Visual Properties
|
|
874
|
+
|
|
875
|
+
❌ **Wrong**:
|
|
876
|
+
```typescript
|
|
877
|
+
protected static properties = {
|
|
878
|
+
placeholder: {
|
|
879
|
+
type: 'string' as const,
|
|
880
|
+
// Missing: visual: true
|
|
881
|
+
default: 'Select...'
|
|
882
|
+
}
|
|
883
|
+
}
|
|
884
|
+
```
|
|
885
|
+
|
|
886
|
+
**Result**: Changing `placeholder` won't trigger re-render!
|
|
887
|
+
|
|
888
|
+
✅ **Correct**:
|
|
889
|
+
```typescript
|
|
890
|
+
protected static properties = {
|
|
891
|
+
placeholder: {
|
|
892
|
+
type: 'string' as const,
|
|
893
|
+
visual: true, // ← Add this!
|
|
894
|
+
default: 'Select...'
|
|
895
|
+
}
|
|
896
|
+
}
|
|
897
|
+
```
|
|
898
|
+
|
|
899
|
+
### Pitfall 3: Updating Properties During Render
|
|
900
|
+
|
|
901
|
+
❌ **Wrong**:
|
|
902
|
+
```typescript
|
|
903
|
+
protected render(): void {
|
|
904
|
+
// Don't update properties inside render!
|
|
905
|
+
if (this._state.open) {
|
|
906
|
+
this.placeholder = 'Search...' // ← Triggers another render!
|
|
907
|
+
}
|
|
908
|
+
}
|
|
909
|
+
```
|
|
910
|
+
|
|
911
|
+
✅ **Correct**:
|
|
912
|
+
```typescript
|
|
913
|
+
protected onPropertiesChanged(changes: PropertyChange[]): void {
|
|
914
|
+
// Update before render
|
|
915
|
+
if (changes.some(c => c.name === 'open')) {
|
|
916
|
+
if (this._state.open) {
|
|
917
|
+
// Update internal state, not properties
|
|
918
|
+
this._effectivePlaceholder = 'Search...'
|
|
919
|
+
}
|
|
920
|
+
}
|
|
921
|
+
}
|
|
922
|
+
|
|
923
|
+
protected render(): void {
|
|
924
|
+
// Use computed state
|
|
925
|
+
const placeholder = this._effectivePlaceholder || this.placeholder
|
|
926
|
+
}
|
|
927
|
+
```
|
|
928
|
+
|
|
929
|
+
---
|
|
930
|
+
|
|
931
|
+
## 📚 Summary
|
|
932
|
+
|
|
933
|
+
**TyComponent provides**:
|
|
934
|
+
1. ✅ Unified property/attribute synchronization
|
|
935
|
+
2. ✅ Automatic type coercion and validation
|
|
936
|
+
3. ✅ Declarative property configuration
|
|
937
|
+
4. ✅ Predictable lifecycle (State → Render → Events)
|
|
938
|
+
5. ✅ Form association support
|
|
939
|
+
6. ✅ Framework compatibility (React, Vue, Reagent)
|
|
940
|
+
7. ✅ Default-on features as `no-*` booleans (e.g., `no-clear`)
|
|
941
|
+
|
|
942
|
+
**You implement**:
|
|
943
|
+
1. Property configuration object
|
|
944
|
+
2. Simple property accessors
|
|
945
|
+
3. Internal state structure
|
|
946
|
+
4. Lifecycle hooks (onConnect, onDisconnect, onPropertiesChanged)
|
|
947
|
+
5. Render method (pure DOM updates)
|
|
948
|
+
6. Business logic (event handlers, etc.)
|
|
949
|
+
|
|
950
|
+
**Result**: Components are **consistent**, **maintainable**, and **work everywhere**!
|
|
951
|
+
|
|
952
|
+
---
|
|
953
|
+
|
|
954
|
+
## 🔗 Related Files
|
|
955
|
+
|
|
956
|
+
- `/packages/core/src/base/ty-component.ts` - Base class implementation
|
|
957
|
+
- `/packages/core/src/utils/property-manager.ts` - Property lifecycle manager
|
|
958
|
+
- `/packages/core/src/components/select.ts` - Complete real-world example
|
|
959
|
+
|
|
960
|
+
---
|
|
961
|
+
|
|
962
|
+
**Built with TyComponent. Framework-agnostic by design. Standards-based for longevity.**
|