@povio/ui 6.0.0-rc.11 → 6.0.0-rc.13

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.
Files changed (495) hide show
  1. package/README.md +470 -43
  2. package/dist/{Accordion-Cup5eRZz.d.ts → Accordion-CR9oomZY.d.ts} +29 -17
  3. package/dist/{Accordion-ORBin0EZ.js → Accordion-gUW7u1Zn.js} +41 -41
  4. package/dist/Alert-DwnALnFY.d.ts +36 -0
  5. package/dist/AlertDialog-BcRiqY_n.d.ts +70 -0
  6. package/dist/Autocomplete-CV4Aa1Ok.js +319 -0
  7. package/dist/Autocomplete-DRwQxx0U.d.ts +123 -0
  8. package/dist/Badge-CO-ZsmbR.d.ts +67 -0
  9. package/dist/{BottomSheet-CGipksM_.js → BottomSheet-APVu5TUd.js} +8 -8
  10. package/dist/BottomSheet-Be0HtQzP.d.ts +65 -0
  11. package/dist/{BottomSheet.lazy-CuJMUeJP.d.ts → BottomSheet.lazy-NNB7ivkW.d.ts} +1 -1
  12. package/dist/{Breadcrumbs-CcB0oOF8.d.ts → Breadcrumbs-Bn3fqVYx.d.ts} +6 -3
  13. package/dist/{Breadcrumbs-a1-q_he0.js → Breadcrumbs-Cd75RPbS.js} +33 -17
  14. package/dist/{Button-C1YB5dOw.js → Button-BJJkLVNj.js} +1 -5
  15. package/dist/{Button-BaODzvZd.js → Button-CzEs3tcV.js} +1 -1
  16. package/dist/{Button-0SswSdDg.d.ts → Button-Hk8zm9q_.d.ts} +2 -2
  17. package/dist/ButtonBase-Cp1w00t2.d.ts +47 -0
  18. package/dist/{ButtonBase-s-VV7oCa.js → ButtonBase-aGz6DYum.js} +10 -18
  19. package/dist/{ButtonContent-Dztbuz3q.js → ButtonContent-2KsbdWRO.js} +5 -5
  20. package/dist/{Calendar-DX0dVo6z.js → Calendar-DN-i_b-_.js} +19 -17
  21. package/dist/{Calendar.lazy-W51M56GQ.js → Calendar.lazy-CqmyDSND.js} +4 -4
  22. package/dist/{Checkbox-Bjsbx-wK.js → Checkbox-CzKXZw_w.js} +35 -9
  23. package/dist/Checkbox-D32MOIhF.d.ts +49 -0
  24. package/dist/CheckboxCheckmark-DDU_Ie7-.js +42 -0
  25. package/dist/CheckboxGroup-B5Mn1G3u.d.ts +52 -0
  26. package/dist/{CheckboxGroup-B3O3IUiu.js → CheckboxGroup-BqWt09kZ.js} +75 -35
  27. package/dist/DatePicker-CmoVbapu.d.ts +80 -0
  28. package/dist/{DatePicker-CqNS7lgR.js → DatePicker-DQewd1By.js} +80 -41
  29. package/dist/{DatePickerInput-vLlL5ATh.d.ts → DatePickerInput-B9VnExeA.d.ts} +3 -3
  30. package/dist/{DatePickerInput-B2Pc_aJr.js → DatePickerInput-Bp9ZIN5E.js} +37 -26
  31. package/dist/{DateRangePicker-C3ClfSfj.js → DateRangePicker-DRZ1hLlR.js} +93 -169
  32. package/dist/DateRangePicker-LX1VJlnD.d.ts +102 -0
  33. package/dist/DateTimePicker-D9pODhAj.d.ts +83 -0
  34. package/dist/{DateTimePicker-CYa2J-1r.js → DateTimePicker-DWtKPaE6.js} +70 -35
  35. package/dist/{Dialog-C9H9_BmK.js → Dialog-BJ13KRQo.js} +1 -1
  36. package/dist/{Dialog-96c4Pzfm.js → Dialog-BzQYDPJ9.js} +23 -19
  37. package/dist/Dialog-D0SeePPz.d.ts +66 -0
  38. package/dist/{Disclosure-BRSkMbZQ.js → Disclosure-Bjm5IOpg.js} +1 -1
  39. package/dist/Drawer-o018RqIt.d.ts +42 -0
  40. package/dist/DropdownMenu-DTr7b-XO.d.ts +51 -0
  41. package/dist/{DropdownMenu-DS0RaEfH.js → DropdownMenu-DrshB60h.js} +33 -21
  42. package/dist/{DropdownMenuDesktop-DGPIfex-.js → DropdownMenuDesktop-DxGA0yvx.js} +14 -8
  43. package/dist/FileInput-Bokcp9nH.d.ts +61 -0
  44. package/dist/{FileInput-IRM0C9W6.js → FileInput-LMhFxlqB.js} +75 -80
  45. package/dist/FileUpload-BqXd4_nz.d.ts +181 -0
  46. package/dist/FileUpload-CJZrkr_U.js +679 -0
  47. package/dist/{FormField-dduTMkNH.js → FormField-TI8Vx5aC.js} +10 -10
  48. package/dist/FormField-XQbjfGSv.d.ts +70 -0
  49. package/dist/{FormFieldError-BT4uxbKY.d.ts → FormFieldError-C7yOdjzQ.d.ts} +1 -0
  50. package/dist/FormFieldHeaderTooltip-DB7KrrcD.js +22 -0
  51. package/dist/HiddenFormValue-DZ2d9eoA.js +20 -0
  52. package/dist/IconButton-CQLHX8-Y.d.ts +24 -0
  53. package/dist/{IconSlot-CqNuZl0E.js → IconSlot-TAWTJ6iK.js} +2 -4
  54. package/dist/{InlineTooltipWrapper-CKTiFpZn.js → InlineTooltipWrapper-CjDUsi2I.js} +1 -1
  55. package/dist/{Input-UbFhc_J2.js → Input-CeRJeAoR.js} +94 -59
  56. package/dist/Input-onUj0DKg.d.ts +56 -0
  57. package/dist/{InputContent-D7lnNLWk.js → InputContent-B8OCdbVP.js} +15 -13
  58. package/dist/InputContent-D5ZkB9hO.d.ts +39 -0
  59. package/dist/Link-BdnWVYL9.d.ts +15 -0
  60. package/dist/{ListBox-DhR5kojP.js → ListBox-gR4iSV7N.js} +3 -3
  61. package/dist/{Modal-DcLWF9cB.js → Modal-DAMsCwzb.js} +1 -1
  62. package/dist/{NumberField-twW8zuJ9.js → NumberField-6Q9LHGSo.js} +91 -62
  63. package/dist/NumberField-Sb30Qao3.d.ts +41 -0
  64. package/dist/{NumberRangeInput-gT6gEJIz.js → NumberRangeInput-BDSkcHVJ.js} +152 -101
  65. package/dist/NumberRangeInput-Dvq8mOUY.d.ts +89 -0
  66. package/dist/{PageHeader-DTfzf-dA.d.ts → PageHeader-eJk6GNK6.d.ts} +6 -5
  67. package/dist/{PasswordInput.bound-CXtbMCD6.js → PasswordInput-BcHpV0Ie.js} +6 -6
  68. package/dist/PasswordInput-VHzP4VPU.d.ts +16 -0
  69. package/dist/Popover-qplPGDnR.d.ts +51 -0
  70. package/dist/Progress-DH-w99MU.d.ts +26 -0
  71. package/dist/Progress-WzWvbvtp.js +180 -0
  72. package/dist/ProgressBar-BsSimmJF.js +46 -0
  73. package/dist/RadioGroup-CC8bKtBN.d.ts +52 -0
  74. package/dist/{RadioGroup-IL4Y8XHO.js → RadioGroup-PKqFHoKP.js} +66 -26
  75. package/dist/{RangeCalendar-0W1YFZqn.js → RangeCalendar-DqCTlIuy.js} +42 -13
  76. package/dist/Select-CSyfDyxG.d.ts +248 -0
  77. package/dist/{Select-B-TuE_Fh.js → Select-D3fuXwVt.js} +435 -184
  78. package/dist/{SelectListBox-Dlonoc5z.js → SelectListBox-DqAxkT1f.js} +46 -37
  79. package/dist/{SidebarWorkspaces-DJknAfS9.js → SidebarWorkspaces-BGl_PIsH.js} +280 -363
  80. package/dist/{SidebarWorkspaces-DDHJAdNH.d.ts → SidebarWorkspaces-CdtK2M-C.d.ts} +31 -17
  81. package/dist/{Slider-DCsCCPFx.js → Slider-BCUiALjE.js} +69 -12
  82. package/dist/Slider-DxalZD3o.d.ts +57 -0
  83. package/dist/Spinner-BTrEbNFy.d.ts +13 -0
  84. package/dist/SplitButton-Dv5l8p5t.d.ts +25 -0
  85. package/dist/Stepper-B1IOUcSI.d.ts +49 -0
  86. package/dist/{Stepper-Dyhxp0Tl.js → Stepper-DA2G546I.js} +116 -88
  87. package/dist/{Switch-BfpSMMpv.js → Switch-Ce-bJOVw.js} +54 -12
  88. package/dist/Switch-urNrop0P.d.ts +42 -0
  89. package/dist/{TabsFilters-CWUNeqYa.js → TabsFilters-Cweij8He.js} +44 -33
  90. package/dist/TabsFilters-M5Ld7eb8.d.ts +59 -0
  91. package/dist/Tag-BKR1AZFa.d.ts +26 -0
  92. package/dist/TextArea-D7YVclaz.d.ts +33 -0
  93. package/dist/{TextArea-DakA3nzZ.js → TextArea-P8F0oD_A.js} +59 -32
  94. package/dist/TimePicker-Ai1M2TGW.d.ts +63 -0
  95. package/dist/{TimePicker-RFzfDezn.js → TimePicker-l4Ysk2AX.js} +99 -50
  96. package/dist/{TimePickerForm-DohOZViU.js → TimePickerForm-BMqNpDPT.js} +5 -5
  97. package/dist/{ToastContainer-Dd0LPykL.js → ToastContainer-BeklfvlK.js} +4 -4
  98. package/dist/{ToggleButton-HUZ8ij6i.d.ts → ToggleButton-DWw53pTt.d.ts} +2 -2
  99. package/dist/ToggleGroup-BQk3k0at.d.ts +95 -0
  100. package/dist/ToggleGroup-BdIgqoqA.js +500 -0
  101. package/dist/{Tooltip-DRB6lo0U.js → Tooltip-BkXPEBqw.js} +2 -2
  102. package/dist/Tooltip-H8OB7CqY.d.ts +33 -0
  103. package/dist/TooltipEllipsis-7QF00kXk.d.ts +21 -0
  104. package/dist/{TooltipWrapper-DLBksJsF.js → TooltipWrapper-ubbBHHVD.js} +6 -6
  105. package/dist/{Typography-DJojwiXV.d.ts → Typography-Cx1oRGxd.d.ts} +5 -1
  106. package/dist/{badgeButton.cva-t5PQOH4M.js → badge.cva-BpoxNggB.js} +20 -22
  107. package/dist/{button.cva-Ciga0rdG.js → button.cva-C2aoXMh-.js} +10 -16
  108. package/dist/{buttonContent.cva-BapnODby.d.ts → buttonContent.cva-Dyy_RUZU.d.ts} +1 -1
  109. package/dist/{checkbox.cva-aLJS7v4z.js → checkbox.cva-qU_q0lSX.js} +14 -14
  110. package/dist/components/accordion.d.ts +1 -1
  111. package/dist/components/accordion.js +1 -1
  112. package/dist/components/alert-dialog.d.ts +2 -2
  113. package/dist/components/alert-dialog.js +174 -128
  114. package/dist/components/alert.d.ts +1 -1
  115. package/dist/components/alert.js +17 -15
  116. package/dist/components/autocomplete.d.ts +2 -2
  117. package/dist/components/autocomplete.js +1 -1
  118. package/dist/components/badge.d.ts +2 -2
  119. package/dist/components/badge.js +159 -81
  120. package/dist/components/bottom-sheet-header.d.ts +1 -1
  121. package/dist/components/bottom-sheet-header.js +4 -4
  122. package/dist/components/bottom-sheet.d.ts +2 -2
  123. package/dist/components/bottom-sheet.js +2 -2
  124. package/dist/components/breadcrumbs.d.ts +1 -1
  125. package/dist/components/breadcrumbs.js +1 -1
  126. package/dist/components/button.d.ts +2 -2
  127. package/dist/components/button.js +1 -1
  128. package/dist/components/checkbox-group.d.ts +2 -2
  129. package/dist/components/checkbox-group.js +1 -1
  130. package/dist/components/checkbox.d.ts +2 -2
  131. package/dist/components/checkbox.js +1 -1
  132. package/dist/components/date-picker.d.ts +2 -2
  133. package/dist/components/date-picker.js +1 -1
  134. package/dist/components/date-range-picker.d.ts +4 -41
  135. package/dist/components/date-range-picker.js +4 -2
  136. package/dist/components/date-range-presets.d.ts +2 -0
  137. package/dist/components/date-range-presets.js +3 -0
  138. package/dist/components/date-time-picker.d.ts +2 -2
  139. package/dist/components/date-time-picker.js +1 -1
  140. package/dist/components/dialog.d.ts +1 -1
  141. package/dist/components/dialog.js +1 -1
  142. package/dist/components/drawer.d.ts +1 -1
  143. package/dist/components/drawer.js +16 -80
  144. package/dist/components/dropdown-menu.d.ts +2 -3
  145. package/dist/components/dropdown-menu.js +2 -3
  146. package/dist/components/file-input.d.ts +2 -2
  147. package/dist/components/file-input.js +1 -1
  148. package/dist/components/file-upload.d.ts +2 -3
  149. package/dist/components/file-upload.js +1 -1
  150. package/dist/components/form-field.d.ts +3 -2
  151. package/dist/components/form-field.js +1 -1
  152. package/dist/components/icon-button.d.ts +1 -1
  153. package/dist/components/icon-button.js +22 -25
  154. package/dist/components/icon-slot.d.ts +1 -2
  155. package/dist/components/icon-slot.js +2 -2
  156. package/dist/components/input-frame.d.ts +6 -10
  157. package/dist/components/input-frame.js +29 -26
  158. package/dist/components/input.d.ts +2 -2
  159. package/dist/components/input.js +2 -2
  160. package/dist/components/link.d.ts +1 -1
  161. package/dist/components/link.js +1 -1
  162. package/dist/components/number-field.d.ts +2 -2
  163. package/dist/components/number-field.js +2 -2
  164. package/dist/components/number-range-input.d.ts +2 -2
  165. package/dist/components/number-range-input.js +1 -1
  166. package/dist/components/page-header.d.ts +1 -1
  167. package/dist/components/page-header.js +5 -5
  168. package/dist/components/password-input.d.ts +2 -2
  169. package/dist/components/password-input.js +1 -22
  170. package/dist/components/popover.d.ts +1 -1
  171. package/dist/components/popover.js +105 -87
  172. package/dist/components/progress.d.ts +2 -2
  173. package/dist/components/progress.js +1 -1
  174. package/dist/components/radio-group.d.ts +2 -2
  175. package/dist/components/radio-group.js +1 -1
  176. package/dist/components/select.d.ts +2 -2
  177. package/dist/components/select.js +1 -1
  178. package/dist/components/sidebar.d.ts +1 -1
  179. package/dist/components/sidebar.js +1 -1
  180. package/dist/components/slider.d.ts +2 -2
  181. package/dist/components/slider.js +1 -1
  182. package/dist/components/spinner.d.ts +1 -1
  183. package/dist/components/spinner.js +71 -1
  184. package/dist/components/split-button.d.ts +1 -1
  185. package/dist/components/split-button.js +15 -4
  186. package/dist/components/stepper.d.ts +1 -1
  187. package/dist/components/stepper.js +1 -1
  188. package/dist/components/style-definitions.d.ts +2 -2
  189. package/dist/components/style-definitions.js +33 -18
  190. package/dist/components/switch.d.ts +2 -2
  191. package/dist/components/switch.js +1 -1
  192. package/dist/components/tabs-filters.d.ts +1 -1
  193. package/dist/components/tabs-filters.js +1 -1
  194. package/dist/components/tag.d.ts +1 -1
  195. package/dist/components/tag.js +50 -64
  196. package/dist/components/text-area.d.ts +2 -2
  197. package/dist/components/text-area.js +1 -1
  198. package/dist/components/time-picker.d.ts +2 -2
  199. package/dist/components/time-picker.js +1 -1
  200. package/dist/components/toast.d.ts +3 -3
  201. package/dist/components/toast.js +4 -3
  202. package/dist/components/toggle-button.d.ts +1 -1
  203. package/dist/components/toggle-button.js +1 -1
  204. package/dist/components/toggle-group.d.ts +2 -2
  205. package/dist/components/toggle-group.js +1 -1
  206. package/dist/components/tooltip-ellipsis.d.ts +1 -1
  207. package/dist/components/tooltip-ellipsis.js +1 -1
  208. package/dist/components/tooltip.d.ts +1 -1
  209. package/dist/components/tooltip.js +1 -1
  210. package/dist/components/typography.d.ts +2 -2
  211. package/dist/components/use-toast.d.ts +2 -2
  212. package/dist/components/use-toast.js +1 -41
  213. package/dist/config/component-configuration.d.ts +1 -1
  214. package/dist/config/component-configuration.js +53 -2
  215. package/dist/config/confirmation.d.ts +1 -1
  216. package/dist/config/confirmation.js +1 -1
  217. package/dist/config/link-context.d.ts +3 -3
  218. package/dist/config/link-context.js +1 -1
  219. package/dist/config/resources.d.ts +1 -1
  220. package/dist/config/resources.js +1 -1
  221. package/dist/config/ui-config.d.ts +2 -2
  222. package/dist/config/ui-config.js +1 -1
  223. package/dist/config/ui-router.d.ts +1 -1
  224. package/dist/config/ui-router.js +1 -1
  225. package/dist/confirmation.context-BflM4Vxg.js +93 -0
  226. package/dist/confirmation.context-C_js9qNv.d.ts +32 -0
  227. package/dist/{datePickerInput.cva-Du0Zn04v.js → datePickerInput.cva-CWkV2fut.js} +1 -1
  228. package/dist/dateRangePreset.utils-Bnb-rjTt.js +116 -0
  229. package/dist/{dialog.cva-BIpz6HcA.js → dialog.cva-BjVggO5l.js} +1 -1
  230. package/dist/{dist-DEZzXa0W.js → dist-DZOoWaZz.js} +63 -38
  231. package/dist/{dropdownMenu.cva-DwSOcbmR.js → dropdownMenu.cva-BopsvbOy.js} +19 -7
  232. package/dist/{exports-BNrTn8Tj.js → exports-DeBGRThC.js} +3 -3
  233. package/dist/{file.utils-Crb-mIHs.d.ts → file.utils-DUADtzdt.d.ts} +3 -3
  234. package/dist/{file.utils-DqQxnuAm.js → file.utils-X6tkeWaz.js} +2 -6
  235. package/dist/fileInputButton.cva-gbqRUf1g.js +39 -0
  236. package/dist/{fileUpload.cva-BYzXGc9C.js → fileUpload.cva-MH5ziWUe.js} +2 -2
  237. package/dist/form-field-Bw7U_ZPI.d.ts +1 -0
  238. package/dist/form.binding-Brdjq2yr.js +161 -0
  239. package/dist/form.binding-DSXB2AOD.d.ts +127 -0
  240. package/dist/form.types-a2WVJDQX.d.ts +43 -0
  241. package/dist/formReset-CnZl_yze.js +35 -0
  242. package/dist/hints-B09_WDhL.d.ts +17 -0
  243. package/dist/hooks/use-async-list.d.ts +1 -1
  244. package/dist/hooks/use-async-list.js +1 -1
  245. package/dist/hooks/use-breakpoint.d.ts +3 -0
  246. package/dist/hooks/use-breakpoint.js +2 -0
  247. package/dist/hooks/use-filters.d.ts +2 -2
  248. package/dist/hooks/use-filters.js +1 -1
  249. package/dist/{i18n-EDC8xyfH.d.ts → i18n-B3PeqBM7.d.ts} +100 -20
  250. package/dist/{i18n-BE9Wvs9L.js → i18n-DQs7jPjv.js} +99 -25
  251. package/dist/iconSlot.cva-DyhOI7EK.js +5 -0
  252. package/dist/{import-Dkfk7PHt.js → import-C73fI3WD.js} +2 -2
  253. package/dist/index.d.ts +64 -85
  254. package/dist/index.js +55 -92
  255. package/dist/{input.cva-DZii82eS.js → input.cva-mm1dnfKP.js} +27 -23
  256. package/dist/inputLayout-CIVpuUBq.js +7 -0
  257. package/dist/inputRow.clsx-BbcaXVta.js +6 -0
  258. package/dist/{label.cva-DTfT6FrX.js → label.cva-DJ5Dmbz5.js} +7 -7
  259. package/dist/link.context-BcBuP9ZT.d.ts +20 -0
  260. package/dist/{link.context-TPjDtjw3.js → link.context-CD5h_b5O.js} +12 -11
  261. package/dist/link.cva-D6L1c2wq.d.ts +2157 -0
  262. package/dist/{logger-CqZjM-sn.js → logger-CW24po62.js} +10 -1
  263. package/dist/{progress.cva-CsGaGVJ-.js → progress.cva-mkJxrrac.js} +2 -2
  264. package/dist/{radio.cva-DistaZtZ.js → radio.cva-Dt5N2ul2.js} +7 -7
  265. package/dist/rich-text-editor.d.ts +44 -2
  266. package/dist/rich-text-editor.js +733 -1
  267. package/dist/router.context-B6j_M4cN.js +151 -0
  268. package/dist/router.context-CSd9JYQ4.d.ts +33 -0
  269. package/dist/{selectDesktop.cva-DStkOdwm.js → selectDesktop.cva-30JAvtgB.js} +1 -1
  270. package/dist/sidebar.cva-BgxTCejU.js +150 -0
  271. package/dist/spinner.cva-j4kGmIWC.js +17 -0
  272. package/dist/{staticDateTimeSegments-4tIzPL8l.js → staticDateTimeSegments-BYk1tcxs.js} +43 -13
  273. package/dist/{status.cva-CYgi3Htz.js → status.cva-WLEqUAjH.js} +9 -9
  274. package/dist/styles/input.d.ts +1 -1
  275. package/dist/tanstack/form.d.ts +3 -3
  276. package/dist/tanstack/form.js +3 -3
  277. package/dist/tanstack/table.d.ts +5 -3
  278. package/dist/tanstack/table.js +2 -2
  279. package/dist/tanstack-ABeiJISz.js +10 -0
  280. package/dist/tanstack-bLXoUPDY.d.ts +165 -0
  281. package/dist/tanstack.d.ts +64 -85
  282. package/dist/tanstack.js +55 -92
  283. package/dist/{toast.cva-B6NXTwbZ.js → toast.cva-C3oA7He3.js} +8 -8
  284. package/dist/toast.runtime-BHXdSTXV.js +25 -0
  285. package/dist/{toggleGroup.cva-CJ-3Ps7j.js → toggleGroup.cva-CvNS5QO1.js} +2 -2
  286. package/dist/uiConfig.context-CN_QgxGO.d.ts +19 -0
  287. package/dist/{uiConfig.context-3DN9w6oU.js → uiConfig.context-CjnLnQOo.js} +5 -7
  288. package/dist/{uiConfig.context-BnCORTNm.d.ts → uiConfig.types-B0sPL7nN.d.ts} +34 -34
  289. package/dist/{useAsyncList-Ct74ve3i.js → useAsyncList-CQgkDfjW.js} +140 -35
  290. package/dist/useAsyncList-F-328rtE.d.ts +25 -0
  291. package/dist/useAutoFocus-K-bfNxa2.js +16 -0
  292. package/dist/{useBreakpoint-CJ3mx7UF.js → useBreakpoint-BrJrvp9_.js} +5 -1
  293. package/dist/useBreakpoint-D-SVcBeQ.d.ts +9 -0
  294. package/dist/useDebounceCallback-BjePw6y4.js +90 -0
  295. package/dist/useFilters-CybBXUAA.js +217 -0
  296. package/dist/useFilters-DrfBFNLw.d.ts +57 -0
  297. package/dist/useFormAutosave-BN-zueci.js +419 -0
  298. package/dist/{useFormAutosave-BBLm3Ujo.d.ts → useFormAutosave-ClMnzVE7.d.ts} +1 -1
  299. package/dist/{useIntersectionObserver-DFAhTsV0.js → useIntersectionObserver-B8msnQTR.js} +15 -3
  300. package/dist/{numberStatic.utils-BIyZuILs.js → useLiveNumberFieldState-B7qGzySj.js} +103 -2
  301. package/dist/useRemoveButton-B6-IGvpY.js +98 -0
  302. package/dist/useResolveDateRangePreset-C_L-doA6.js +26 -0
  303. package/dist/useResolveDateRangePreset-DOSzJR-N.d.ts +64 -0
  304. package/dist/{useScrollableListBox-oYKqU3Hp.js → useScrollableListBox-C8chM7c-.js} +1 -1
  305. package/dist/{useStaticInputHandoff-BN0fOerH.js → useStaticInputHandoff-DrNFrvD7.js} +6 -1
  306. package/dist/{useTableColumnConfig-D3KH4Rpo.js → useTableColumnConfig-B9cYBKo3.js} +956 -689
  307. package/dist/useTableNav-rP1wDkhV.d.ts +372 -0
  308. package/dist/useToast-D2C9pROU.d.ts +78 -0
  309. package/dist/useToast-DSoOiSw0.js +63 -0
  310. package/dist/utils/file.d.ts +1 -1
  311. package/dist/utils/file.js +1 -1
  312. package/dist/utils/logger.js +1 -1
  313. package/llms.txt +3116 -0
  314. package/package.json +13 -131
  315. package/MIGRATION.md +0 -673
  316. package/dist/Alert-D4X7OWiv.d.ts +0 -34
  317. package/dist/AlertDialog-DklLDjmw.d.ts +0 -26
  318. package/dist/Autocomplete-BgFz3kuR.d.ts +0 -23
  319. package/dist/Autocomplete-BxRjxjtp.js +0 -145
  320. package/dist/Autocomplete.bound-CpHZZ3C9.d.ts +0 -9
  321. package/dist/Autocomplete.bound-DweyHUI5.js +0 -28
  322. package/dist/Badge-Db1ndK67.d.ts +0 -30
  323. package/dist/BadgeButton-BPhWDAnc.d.ts +0 -15
  324. package/dist/BottomSheet-BZmDJBR-.d.ts +0 -33
  325. package/dist/ButtonBase-CZuEy3Pk.d.ts +0 -32
  326. package/dist/Checkbox-w2j5hLOQ.d.ts +0 -27
  327. package/dist/Checkbox.bound-D2nBglJz.js +0 -33
  328. package/dist/Checkbox.bound-DD_RCjVm.d.ts +0 -9
  329. package/dist/CheckboxCheckmark-DWsYVZuu.js +0 -25
  330. package/dist/CheckboxGroup-BYI15Y09.d.ts +0 -30
  331. package/dist/CheckboxGroup.bound-DY0HKGSh.js +0 -32
  332. package/dist/CheckboxGroup.bound-QiJ-P0KR.d.ts +0 -9
  333. package/dist/ComboBox-ChsdI0lt.js +0 -212
  334. package/dist/DatePicker-QzfQf21b.d.ts +0 -56
  335. package/dist/DatePicker.bound-DoCAqhM4.d.ts +0 -9
  336. package/dist/DatePicker.bound-Dxg2LM89.js +0 -36
  337. package/dist/DateRangePicker-32D4pWJg.d.ts +0 -97
  338. package/dist/DateRangePicker.bound-CVtoVsho.d.ts +0 -9
  339. package/dist/DateRangePicker.bound-PR9rBoXc.js +0 -35
  340. package/dist/DateTimePicker-BTRIUagV.d.ts +0 -55
  341. package/dist/DateTimePicker.bound-CQxnRveH.js +0 -32
  342. package/dist/DateTimePicker.bound-X4DTyQ1b.d.ts +0 -9
  343. package/dist/Dialog-CO9xljD3.d.ts +0 -21
  344. package/dist/Drawer-D1cHiBFO.d.ts +0 -18
  345. package/dist/DropdownMenu-D_9z9ond.d.ts +0 -25
  346. package/dist/FileInput-BEaECoBS.d.ts +0 -75
  347. package/dist/FileInput.bound-CctyulN9.js +0 -30
  348. package/dist/FileInput.bound-D2HuuqSb.d.ts +0 -8
  349. package/dist/FileUpload-BUTSqHVk.d.ts +0 -11
  350. package/dist/FileUpload-Dfs3FvJ7.js +0 -749
  351. package/dist/FileUpload.bound-CGQXb4iT.d.ts +0 -16
  352. package/dist/FileUpload.bound-vik_sTkm.js +0 -30
  353. package/dist/FileUploadContainer-Dzg5aXXZ.d.ts +0 -5
  354. package/dist/FormField-DGyCDxOp.d.ts +0 -42
  355. package/dist/FormFieldHeaderTooltip-Dt-g40Tc.js +0 -17
  356. package/dist/IconButton-shH_9wcl.d.ts +0 -25
  357. package/dist/Input-CTp_9mS9.d.ts +0 -34
  358. package/dist/Input.bound-0iJO2-ia.js +0 -31
  359. package/dist/Input.bound-B9a62ylL.d.ts +0 -9
  360. package/dist/InputContent-BCNkN4Fx.d.ts +0 -27
  361. package/dist/Link-PvYB_M-j.d.ts +0 -30
  362. package/dist/MenuItem-U3-pu1j5.d.ts +0 -6
  363. package/dist/NumberField-WXebfxjK.d.ts +0 -34
  364. package/dist/NumberField.bound-DHDsBNvI.js +0 -32
  365. package/dist/NumberField.bound-Dy0A5iVc.d.ts +0 -9
  366. package/dist/NumberRangeInput-BCKQaGpy.d.ts +0 -50
  367. package/dist/NumberRangeInput.bound-5Yv3Og73.js +0 -32
  368. package/dist/NumberRangeInput.bound-BNXxIQ0b.d.ts +0 -9
  369. package/dist/Pagination-BCGUVYOF.d.ts +0 -12
  370. package/dist/PaginationList-CvlSkJGn.d.ts +0 -18
  371. package/dist/PaginationList-D7SRwySe.js +0 -220
  372. package/dist/PasswordInput-EhQjYyJS.d.ts +0 -11
  373. package/dist/PasswordInput.bound-CK5GwKL4.d.ts +0 -9
  374. package/dist/Popover-D_t1XDPA.d.ts +0 -20
  375. package/dist/Progress-Ckfpi_-M.d.ts +0 -45
  376. package/dist/Progress-RiEGGxNG.js +0 -119
  377. package/dist/RadioGroup-6e-Z6jW8.d.ts +0 -26
  378. package/dist/RadioGroup.bound-BFWSq-on.js +0 -32
  379. package/dist/RadioGroup.bound-w3SZqSkH.d.ts +0 -9
  380. package/dist/RichTextEditor-BuqZth3X.js +0 -651
  381. package/dist/RichTextEditor-DHhuBeT6.d.ts +0 -28
  382. package/dist/Select-C34ENdjq.d.ts +0 -119
  383. package/dist/Select.bound-CNCChZww.js +0 -34
  384. package/dist/Select.bound-qOihchei.d.ts +0 -17
  385. package/dist/Slider-DRg8zKRM.d.ts +0 -23
  386. package/dist/Slider.bound-CByTXPTr.js +0 -31
  387. package/dist/Slider.bound-CaEF19um.d.ts +0 -9
  388. package/dist/Spinner-Cvy_6zgD.d.ts +0 -30
  389. package/dist/Spinner-DqjP06T1.js +0 -101
  390. package/dist/SplitButton-V1f2NWfh.d.ts +0 -15
  391. package/dist/Stepper-k91x_m-E.d.ts +0 -114
  392. package/dist/Switch-ELVPkPx0.d.ts +0 -24
  393. package/dist/Switch.bound-DeEdVvZV.d.ts +0 -9
  394. package/dist/Switch.bound-Dv0cHsMM.js +0 -33
  395. package/dist/TableDnd-CuHxANWh.js +0 -133
  396. package/dist/TableRowDetails-D8HFTghI.d.ts +0 -109
  397. package/dist/TabsFilters-DePddjCk.d.ts +0 -30
  398. package/dist/Tag-B2_ZiSE-.d.ts +0 -44
  399. package/dist/TextArea-iqUeB2QY.d.ts +0 -26
  400. package/dist/TextArea.bound-BJHyCogp.d.ts +0 -9
  401. package/dist/TextArea.bound-CDVPP_qb.js +0 -28
  402. package/dist/TimePicker-BZ1ocsBX.d.ts +0 -45
  403. package/dist/TimePicker.bound-8DmjMXuE.d.ts +0 -9
  404. package/dist/TimePicker.bound-DPia51Qs.js +0 -32
  405. package/dist/Toast-D9pdadZ4.d.ts +0 -16
  406. package/dist/ToggleGroup-CrDoeLN0.js +0 -333
  407. package/dist/ToggleGroup-DvjnSinl.d.ts +0 -42
  408. package/dist/ToggleGroup.bound-B03ISHQ8.d.ts +0 -9
  409. package/dist/ToggleGroup.bound-DCnYwmBt.js +0 -67
  410. package/dist/Tooltip-B8DTURLQ.d.ts +0 -16
  411. package/dist/TooltipEllipsis-Di9Dvd4x.d.ts +0 -11
  412. package/dist/badgeButton.cva-CBFIhr1S.d.ts +0 -41
  413. package/dist/button.cva-C8LGtNJ3.d.ts +0 -94
  414. package/dist/checkbox.cva-CCh_UlrC.d.ts +0 -76
  415. package/dist/components/badge-button.d.ts +0 -2
  416. package/dist/components/badge-button.js +0 -74
  417. package/dist/components/file-upload-container.d.ts +0 -3
  418. package/dist/components/file-upload-container.js +0 -15
  419. package/dist/components/pagination-list.d.ts +0 -2
  420. package/dist/components/pagination-list.js +0 -2
  421. package/dist/components/pagination.d.ts +0 -2
  422. package/dist/components/pagination.js +0 -138
  423. package/dist/confirmation.context-BwlIEVeF.js +0 -114
  424. package/dist/confirmation.context-C_GDRn3a.d.ts +0 -23
  425. package/dist/fileUpload.types-C-ke21yY.d.ts +0 -110
  426. package/dist/form.binding-DOR5gIQf.js +0 -49
  427. package/dist/form.types-C8P4sznq.d.ts +0 -22
  428. package/dist/formFieldHelper.cva-DRmSyRZN.js +0 -14
  429. package/dist/iconSlot.cva-CLB5Tlsr.d.ts +0 -9
  430. package/dist/icons.d.ts +0 -4
  431. package/dist/icons.js +0 -3
  432. package/dist/input.cva-BjuHsDGy.d.ts +0 -80
  433. package/dist/inputLayout-KdAtunGk.js +0 -5
  434. package/dist/link.context-BCHn7NSy.d.ts +0 -12
  435. package/dist/radio.cva-D7M1hqLe.d.ts +0 -56
  436. package/dist/router.context-CtafjXV7.d.ts +0 -16
  437. package/dist/router.context-MckTbHw9.js +0 -63
  438. package/dist/routing.utils-DfxEt0_Y.js +0 -30
  439. package/dist/style-definitions-Dx6aFDiR.d.ts +0 -1038
  440. package/dist/switch.cva-r6vcS25Q.d.ts +0 -16
  441. package/dist/tanstack/autocomplete.d.ts +0 -3
  442. package/dist/tanstack/autocomplete.js +0 -2
  443. package/dist/tanstack/checkbox-group.d.ts +0 -3
  444. package/dist/tanstack/checkbox-group.js +0 -2
  445. package/dist/tanstack/checkbox.d.ts +0 -3
  446. package/dist/tanstack/checkbox.js +0 -2
  447. package/dist/tanstack/date-picker.d.ts +0 -3
  448. package/dist/tanstack/date-picker.js +0 -2
  449. package/dist/tanstack/date-range-picker.d.ts +0 -3
  450. package/dist/tanstack/date-range-picker.js +0 -2
  451. package/dist/tanstack/date-time-picker.d.ts +0 -3
  452. package/dist/tanstack/date-time-picker.js +0 -2
  453. package/dist/tanstack/file-input.d.ts +0 -3
  454. package/dist/tanstack/file-input.js +0 -2
  455. package/dist/tanstack/file-upload.d.ts +0 -4
  456. package/dist/tanstack/file-upload.js +0 -2
  457. package/dist/tanstack/input.d.ts +0 -3
  458. package/dist/tanstack/input.js +0 -2
  459. package/dist/tanstack/number-field.d.ts +0 -3
  460. package/dist/tanstack/number-field.js +0 -2
  461. package/dist/tanstack/number-range-input.d.ts +0 -3
  462. package/dist/tanstack/number-range-input.js +0 -2
  463. package/dist/tanstack/password-input.d.ts +0 -2
  464. package/dist/tanstack/password-input.js +0 -2
  465. package/dist/tanstack/radio-group.d.ts +0 -3
  466. package/dist/tanstack/radio-group.js +0 -2
  467. package/dist/tanstack/rich-text-editor.d.ts +0 -9
  468. package/dist/tanstack/rich-text-editor.js +0 -28
  469. package/dist/tanstack/select.d.ts +0 -3
  470. package/dist/tanstack/select.js +0 -2
  471. package/dist/tanstack/slider.d.ts +0 -3
  472. package/dist/tanstack/slider.js +0 -2
  473. package/dist/tanstack/switch.d.ts +0 -3
  474. package/dist/tanstack/switch.js +0 -2
  475. package/dist/tanstack/text-area.d.ts +0 -3
  476. package/dist/tanstack/text-area.js +0 -2
  477. package/dist/tanstack/time-picker.d.ts +0 -3
  478. package/dist/tanstack/time-picker.js +0 -2
  479. package/dist/tanstack/toggle-group.d.ts +0 -3
  480. package/dist/tanstack/toggle-group.js +0 -2
  481. package/dist/tanstack-Bgdv0qU1.js +0 -19
  482. package/dist/tanstack-CtuKX9Ss.d.ts +0 -568
  483. package/dist/toast.cva-AmLw6Cf5.d.ts +0 -61
  484. package/dist/toast.runtime-Drd2IJ_j.js +0 -17
  485. package/dist/toastActivation.store-BELtcr76.js +0 -16
  486. package/dist/toggleGroup.cva-DA4U21gn.d.ts +0 -26
  487. package/dist/typography.cva-BCHlTHdM.d.ts +0 -36
  488. package/dist/useAsyncList-Cu-Y8If2.d.ts +0 -9
  489. package/dist/useFilters-BxRScJdn.d.ts +0 -11
  490. package/dist/useFilters-DMi94RZK.js +0 -190
  491. package/dist/useForm-Cb7KWLds.js +0 -217
  492. package/dist/useForm-I6z23FXf.d.ts +0 -51
  493. package/dist/useFormAutosave-BPGlChiY.js +0 -216
  494. package/dist/useTableNav-H5DrogZU.d.ts +0 -215
  495. package/dist/useToast-DsA8CVoY.d.ts +0 -16
package/llms.txt ADDED
@@ -0,0 +1,3116 @@
1
+ # @povio/ui
2
+
3
+ > React 19 components built on React Aria Components, styled with shadcn/ui design tokens and Tailwind 4. This file is the reference for coding agents: the rules first, then an index of every import path, then one canonical, type-checked example per component or hook.
4
+
5
+ ## Imports
6
+
7
+ - Import every component from its own subpath: `import { Button } from "@povio/ui/button"`. The subpath is the kebab-case name of the component or hook (`useAsyncList` from `@povio/ui/use-async-list`), and a component's types come from the same subpath (`UploadedFile` from `@povio/ui/file-upload`).
8
+ - Exceptions: `useForm`, `useFormValue`, `useFormState`, `BoundField`, `useAutosave` and `useFormAutosave` from `@povio/ui/tanstack/form`; `Table`, `InfiniteTable`, `ColumnConfigModal`, `useSorting`, `useTableColumnConfig`, `useTableNav` and the `ColumnDef`, `Row`, `RowSelectionState`, `SortingState` and `BulkSelectionActionsComponent` types from `@povio/ui/tanstack/table`; `ListTabs` from `@povio/ui/tabs-filters`; `ToastContainer` from `@povio/ui/toast` (`useToast` from there or `@povio/ui/use-toast`); `SidebarLayout`, `SidebarItem` and the other sidebar parts from `@povio/ui/sidebar`; `FormLayoutRow`, `FormLayoutSection` and `FormLayoutActions` from `@povio/ui/form-layout`; `PageHeaderDetails` from `@povio/ui/page-header`; date-range preset helpers such as `useResolveDateRangePreset` and `resolveDateRangePreset` from `@povio/ui/date-range-presets`; `OmitDiscriminatedUnion` from `@povio/ui/types`; React Aria primitives such as `I18nProvider` from `@povio/ui/<kebab-name>/react-aria` (`@povio/ui/i18n-provider/react-aria`).
9
+ - Never import from `@povio/ui/src/...` or `@povio/ui/dist/...`. `@povio/ui` and `@povio/ui/tanstack` are compatibility barrels; do not use them in new code. `installServiceWorker` is the exception: only `@povio/ui` exports it.
10
+
11
+ ## App root
12
+
13
+ Mount these once, around the whole app:
14
+
15
+ - Translations: merge `resources` from `@povio/ui/resources` (namespace `ns`, `"ui"`) into the app's i18next `init({ resources })`, and render inside react-i18next (`i18n.use(initReactI18next)` or `I18nextProvider`). Without them, labels and accessible names render as keys such as `ui.tag.dismiss`.
16
+ - `I18nProvider` from `@povio/ui/i18n-provider/react-aria` with i18next's language: `const { i18n } = useTranslation(); <I18nProvider locale={i18n.language}>`. React Aria's date formats and built-in labels otherwise follow the browser language, whatever i18next or `<html lang>` says.
17
+ - `UIRouter.UIRouterProvider` from `@povio/ui/ui-router`, with `push(path, search?)`, `replace(path, search?)` and `searchString` from the app router. `path` may be `"."` (the current route) and `search` is the complete search object: pass it to the router's `search`, e.g. TanStack Router `push={(to, search) => navigate({ to, search })}`, `replace={(to, search) => navigate({ to, search, replace: true })}`, `searchString={location.searchStr}`. Ignoring `search` compiles, but filters and sorting never reach the URL. `useFilters` and `useSorting` throw without the provider, and React Aria links navigate through its `push`.
18
+ - `LinkContext.LinkContextProvider` from `@povio/ui/link-context`: `const RouterLink = createLink(Link)` (TanStack Router's `createLink` over React Aria's `Link`, at module scope) and `<LinkContext.LinkContextProvider LinkComponent={RouterLink}>`, with no cast. `Link`, `SidebarItem`, breadcrumbs and buttons with `link` render it; without it they render React Aria's link.
19
+ - `Confirmation.Provider` from `@povio/ui/confirmation`: `Confirmation.useConfirmation()` throws without it.
20
+ - `<ToastContainer />` from `@povio/ui/toast`, next to the app content (it takes no children): the `useToast` functions show nothing without it.
21
+ - Optional: `UIConfig.Provider` (`@povio/ui/ui-config`) for app-wide default props and `UIOverrides.Provider` (`@povio/ui/ui-overrides`) for app-wide classes. Keep their `config` objects at module scope and type a partial config as `UIConfig.Config` (`const config: UIConfig.Config = { table: { rowDetailsMode: "split" } }`); `Partial<UIConfig.Options>` rejects partial sections.
22
+
23
+ ## One component per control
24
+
25
+ Every input is a single component with two mutually exclusive modes. There are no `Form*`, `Controlled*` or `*.bound` variants.
26
+
27
+ - Standalone: `value` + `onChange`, or `defaultValue` where the control supports uncontrolled use. Boolean controls use `isSelected` + `onChange`, or `defaultSelected`.
28
+ - Form-bound: `field={{ form, name }}`, where `form` comes from `useForm`. Do not pass `value`, `defaultValue`, `onChange` or `onBlur` together with `field`; put side effects in `field={{ form, name, onValueChange, onBlur }}`.
29
+ - `error` is allowed together with `field` and wins over the form's own message: use it for a server error on one field and clear it in `field.onValueChange`.
30
+ - An empty number, select or date field holds `null`, never `""`. Put the required message on the schema, `z.number({ error: "Age is required" })`, `z.string({ error: "Role is required" })` or `z.iso.datetime({ error: "Date is required" })`; otherwise the user sees zod's "Invalid input: expected number, received null". Make an optional one `.nullable()` (or `.nullish()`), not `.optional()`: clearing writes `null`, which `.optional()` rejects, and binding such an input to an `.optional()` path fails to type-check with "This input writes null when cleared…".
31
+ - Each input exports `<Name>Props` (the union), `Standalone<Name>Props` and `Controlled<Name>Props`. Type a wrapper that forwards `value`/`onChange` with the standalone type; a union cannot be extended with `interface … extends`, so intersect with `&` instead.
32
+ - A wrapper that forwards `field` can use the props type without a type argument (`(props: InputProps) => <Input {...props} />`): it accepts any form but does not check the path. To keep path and value checks, make it generic: `function EmailField<T extends Record<string, unknown>>(props: InputProps<T>) { return <Input type="email" {...props} />; }`. A generic `Select` or `Autocomplete` wrapper passes its key type explicitly (`<Select<T> {...props} />`, `<Autocomplete<T> {...props} />`); without it TypeScript cannot match the generic key and reports an error about `mapInitialToSelectItem`.
33
+ - To drop or preset a prop of a union props type (`<Name>Props`, `StandaloneSelectProps`, `DialogProps`, `BadgeProps`), use `OmitDiscriminatedUnion<Props, K>` from `@povio/ui/types`, not `Omit`: `Omit` merges the union, and the spread fails with an error about `field`, `selectionMode`, `as` or `label`. Example: `const CompactInput = (props: OmitDiscriminatedUnion<InputProps, "size">) => <Input {...props} size="sm" />;`.
34
+ - `Input`, `PasswordInput`, `TextArea` and `NumberField` also submit under `name` in a native `<form>` / `FormData` (`NumberField` submits the raw number, e.g. `1234.5`; disabled fields are left out). `Checkbox` and `Switch` (submitted as `on` when selected), `RadioGroup` (the selected id) and `CheckboxGroup` (one entry per checked id) submit natively too. Every other input (`NumberRangeInput`, `Select`, `Autocomplete`, `Slider`, `ToggleGroup`, `FileInput`, `FileUpload`, `RichTextEditor` and the date/time pickers) takes no `name`: bind it with `field`.
35
+
36
+ ## Forms
37
+
38
+ - Bound fields show schema errors after a submit attempt (default `mode: "onSubmit"`), or earlier with `useForm({ mode: "onBlur" | "onChange" | "onTouched" | "all" })`. `form.validateField` is not a submit attempt, so in the default mode it can fail without showing a message.
39
+ - Read form state in render with `useFormState(form, (s) => s.isSubmitting)` and values with `useFormValue(form, (v) => v.name)`. `form.state` and `form.state.values` are snapshots that do not re-render, so use them only in event handlers (`isLoading={form.state.isSubmitting}` never shows the spinner and allows a double submit).
40
+ - `useForm` reads `defaultValues` once, on mount; later changes are ignored (unlike plain TanStack Form). For an edit form, render the form component only after the record loads and pass the record as a prop (`EditProfileExample` in the tanstack/form example), or call `form.reset(record)` when it arrives; `defaultValues: async () => fetchRecord()` also works.
41
+ - For "has unsaved changes" use `useFormState(form, (s) => !s.isDefaultValue)`. TanStack's `isDirty` stays true once a field has changed, even after the edit is undone, until `form.reset()`.
42
+ - `form.handleSubmit(onValid, onInvalid)`: `onInvalid(errors, values)` gets `{ [fieldPath]: firstError }` for every invalid field, nested paths such as `range.start` included; the fields already show their messages. Server checks that should block the submit go in `useForm({ validateOnSubmitAsync: async ({ value }) => (taken ? { fields: { email: "Already taken" } } : undefined) })`. It runs after the schema passes, and it is a validator, not a submit handler.
43
+ - For a multi-step form, use one `useForm` per step, with Next as a `type="submit"` button and `<form onSubmit={stepForm.handleSubmit(goNext)}>`. Or use `mode: "onTouched"` and `await form.validateField(name, "submit")` for each field of the step. When a wizard footer swaps a Next button for a submit button in the same spot, give them distinct `key`s (`key="next"` / `key="submit"`); otherwise React reuses the element and the click that advanced the step also submits.
44
+ - Bind a custom control (colour, signature, map picker) with `BoundField`: `<BoundField field={{ form, name: "brandColor" }}>{({ value, onChange, onBlur, ref, error }) => <FormField label="Brand colour" error={error} labelProps={{ htmlFor: id }}><input id={id} ref={ref} value={value} onChange={(e) => onChange(e.target.value)} onBlur={onBlur} /></FormField>}</BoundField>`. It reveals errors, marks the field touched and notifies autosave like the library's inputs. Don't build this from `form.Field` + `field.state.meta.errors`: those errors show before the user has done anything. `FormField` itself has no `field` prop.
45
+
46
+ ## Prop names
47
+
48
+ Props follow React Aria. Each prop has one spelling; the names in the right-hand column are not props of the components that row names and fail type-checking there, most with an error that names the replacement (some, such as `label`, `text` or `emptyText`, are valid props of other components). The table gives the spelling, not availability: a component only has the props for concepts it supports (`Slider` has no `layout`; `Select`, `Slider`, `ToggleGroup`, `FileInput`, `FileUpload` and `RichTextEditor` have no `isReadOnly`).
49
+
50
+ | Use | Not |
51
+ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
52
+ | `isDisabled`, `isRequired`, `isReadOnly`, `isInvalid` | `disabled`, `required`, `readOnly` |
53
+ | `error="Message"` (marks the field invalid and shows the text) | `errorMessage` |
54
+ | `helperText` for the hint under a label; `hideLabel` to hide the label (it stays the accessible name) | `description`, `isHeaderHidden` |
55
+ | Render an input conditionally to hide it | `isHidden` |
56
+ | The form's `zodSchema` to validate; `error` or `isInvalid` to mark a field | `validate`, `validationBehavior`, `validationState` |
57
+ | `autoFocus` (it mounts the live control at once) on `Input`, `PasswordInput`, `TextArea`, `NumberField`, `NumberRangeInput`, `Autocomplete`, the date/time pickers, `Checkbox` and `Switch`; `Select`, `ToggleGroup`, `RichTextEditor`, `CheckboxGroup`, `RadioGroup`, `Slider`, `FileInput` and `FileUpload` take none | `autoFocusOnMount` |
58
+ | `onChange` on inputs; `field={{ form, name, onValueChange }}` when bound | `onValueChange` |
59
+ | `layout="default" \| "floating" \| "filter" \| "inline"` on inputs | `as` |
60
+ | `className` (field root) on every input; `inputClassName` (the bordered box) on `Input`, `PasswordInput`, `TextArea`, `NumberField`, `NumberRangeInput`, `Select`, `Autocomplete`, the date/time pickers, `CheckboxGroup` and `RadioGroup`; `editorClassName` (the editable area) on `RichTextEditor`; `toggleGroupItemClassName` (each item) on `ToggleGroup`; `onFocus` | `style`, `onClick`, `containerClassName` |
61
+ | `PasswordInput` for passwords, `NumberField` for numbers | `<Input type="password">`, `type="number"` |
62
+ | `minValue` / `maxValue` on `NumberField` | `min`, `max` |
63
+ | `startPlaceholder`, `startLabel`, `onStartChange` and the matching `end*` props on `NumberRangeInput` | `minPlaceholder`, `onMinChange` and the other `min*` / `max*` props |
64
+ | `action={{ icon, label, onPress }}` on `Input` and `NumberField` (one trailing icon button) | `onClick`, `altText` |
65
+ | `isSelected` + `onChange` on `Checkbox` and `Switch`, with the label as children | `checked`, `onCheckedChange`, `label` |
66
+ | `isLoading` on buttons, `AlertDialog` actions, `Table` and `InfiniteTable` (shows the spinner) | `loading`, `isPending` |
67
+ | `emptyState` on `Table` and `InfiniteTable` (any node) | `emptyText` |
68
+ | `validateOnSubmitAsync` on `useForm` (resolves `{ fields: { [path]: message } }` or `undefined`); submit with `form.handleSubmit` | `onSubmitAsync`, `onSubmit` |
69
+ | `width="fill"` on buttons | `fullWidth` |
70
+ | `icon` + `iconPosition="left" \| "right"` on buttons (one icon per button) | `startIcon`, `endIcon` |
71
+ | `disableWhileLoading={false}` on buttons | `noDisableWhenLoading` |
72
+ | `variant="contained"` / `variant="outlined"` on buttons and `Badge`; `variant="text"` for a text-styled `Button` (`Link` for a link in running text) | `solid`, `outline`, `variant="link"` |
73
+ | `color="error"` for a destructive button, badge, tag, alert or menu item | `color="destructive"` |
74
+ | `color="secondary"` for the neutral grey button, badge, tag, alert or toast (`secondaryToast` from `useToast`) | `color="neutral"`, `neutralToast` |
75
+ | `label` on `IconButton` (its accessible name) and `SplitButton` (the main button's text) | `ariaLabel`, `children` on `SplitButton` |
76
+ | `link={{ href }}` on `Button`, `IconButton`, `SplitButton`, breadcrumb items, `ListTab` items and the `PageHeader` back link; `href` directly on `Link`, `SidebarItem` and `DropdownMenu` items | `href` on the components that take `link` |
77
+ | `onRemove` on `Badge` and `Tag` (passing it renders the remove button, styled through `removeButtonProps`) | `dismissible`, `dismissable`, `onDismiss`, `dismissButtonProps` |
78
+ | `items: { id, label }[]` on every choice input, including `RadioGroup` and `CheckboxGroup`, and on `SidebarWorkspaces` | `options`, `{ value, label }`, `name` |
79
+ | `label` and `onPress` on action objects (`AlertDialog` actions, toast `actions`); `AlertDialog` actions also take `isLoading` and `isDisabled` | `text`, `onClick`, `loading`, `disabled` |
80
+ | `isOpen` + `onOpenChange` on `Dialog`, `Drawer`, `BottomSheet`, `Popover`, `AlertDialog` and `ColumnConfigModal` | `open`, `onClose` |
81
+ | `label` as the accessible name of `Dialog`, `Drawer`, `BottomSheet` and `Popover` (required; `Dialog` also takes `aria-labelledby`) | `aria-label`, `title`, `heading`, `sheetLabel` |
82
+ | `heading` + `description` on `AlertDialog`, which renders its content from props (use `Dialog` for custom content) | `title`, `children` |
83
+ | `headingClassName`, `headingTypography`, `descriptionClassName`, `descriptionTypography` on `AlertDialog` (`UIConfig` `alertDialog.headingTypography`) | `titleClassName`, `titleTypography` |
84
+ | `confirmAction` and `cancelAction` on `AlertDialog` (action objects); `primaryAction` on `PageHeader` and `TabsFilters` takes a rendered button | `primaryAction`, `secondaryAction` on `AlertDialog` |
85
+ | `className` for an overlay's visible surface; `contentClassName` on `Drawer` for the element that holds the children | `dialogClassName`, `popoverClassName`, `containerClassName` |
86
+ | `placement` on `Popover`, `Tooltip` and `DropdownMenu` | `popoverProps={{ placement }}` |
87
+ | `text` on `Tooltip`, `Alert` and `Toast` (the whole message); `rightContent` for the actions of an `Alert` | `content`, `message`, `title`, `description`, `children`, `actions`, `label` on `Tooltip` |
88
+ | `allowsMultiple` on `FileInput` and `FileUpload` | `multiple` |
89
+ | `onUpload`, `onRemove`, `orientation`, `actionStyle` on `FileUpload`; `buttonPosition` on `FileInput` | `fileUpload`, `fileRemove`, `defaultState`, `variant`, `as` |
90
+ | `selectionMode="multiple"` on `Select`, `Autocomplete` and `ToggleGroup` | `multiple`, `isMulti` |
91
+ | `isSearchable` on `Select`; `isClientSearchDisabled` only for `items` you filter on the server (a `list` already does) | `ignoreInputValueFiltering` |
92
+ | `value`, `defaultValue` and `onChange` on `Select`, `Autocomplete`, `ToggleGroup` and `SidebarWorkspaces` (`onChange` receives the value, not keys) | `selectedKey(s)`, `defaultSelectedKey(s)`, `onSelectionChange` |
93
+ | `hasNextPage`, `fetchNextPage`, `isFetchingNextPage` (TanStack names) on `Select`, `useAsyncList` | `hasMore`, `loadMore`, `hasLoadMore`, `onLoadMore` |
94
+ | `size="sm"` for compact buttons, inputs and `PageHeader`; omit `size` for the default. `Spinner` has the default and `size="lg"` | `s`, `small`, `compact`, `l` |
95
+ | `size="h4"` on `Typography` (its own size scale) | `variant` |
96
+ | `<Badge as="button">` (`onPress`) / `<Badge as="toggle">` (`isSelected` + `onChange`) for pressable badges | `BadgeButton`, `toggle`, `onPress` on a toggle or display badge |
97
+ | `<FileUpload>{({ files, onRemove, onCancel }) => …}</FileUpload>` for custom drop-zone content | `FileUploadContainer`, `listRenderer` |
98
+ | `items` on `Table`; table state is `<x>` + `on<X>Change` (`sorting` + `onSortingChange`, `rowSelection` + `onRowSelectionChange`, `defaultRowSelection`); `enableRowSelection` for selection | `data`, `pagination`, `setSorting` and the other `set<X>` props, `defaultSelectedRows`, `selectionMode`, `selectedKeys`, `onSelectionChange` |
99
+ | `onRowAction(item)` (click, or Enter on a focused cell) and `onRowDoubleClick(item)` on `Table`; both receive the row's item, not a TanStack `Row` | `onRowClick`, `onDoubleClick` |
100
+ | `value` (0–100, clamped) on `Progress`, as on React Aria's `ProgressBar`; `label` names it (`hideLabel` keeps it as the name only) | `progress`, `aria-label` |
101
+ | `valuePosition` (`trailing` \| `leading` \| `none`) on `Progress` places the percentage | `valueLabel` |
102
+ | `items: { id, label, description? }` on `Stepper`; `label` + `description` on `Accordion` items | `steps`, `title`, `subtext`, `heading`, `subheading` |
103
+ | `iconOnly`, `labelsOnly` and `onStepPress` on `Stepper` (`iconOnly` as on `Breadcrumbs`) | `iconsOnly`, `titlesOnly`, `onStepClick` |
104
+ | The types `DropdownMenuItem`, `DateRangePickerValue` and `UploadedFile` | `MenuItemDefinition`, `AbsoluteDateRangePickerValue`, `FileUploadState` |
105
+
106
+ ## Behaviour worth knowing
107
+
108
+ - Buttons, links and `as="button"` badges handle activation with `onPress`; toggle badges use `onChange`. `Button` renders `type="button"` by default, so a form's submit button needs `type="submit"` (pressing Enter in a field still submits without it).
109
+ - `field.onBlur` runs when focus actually leaves the control (including the date/time pickers, ranges, the rich text editor and a mobile `Select`'s trigger); moving between the two sides of a range, or into its calendar, is not a blur. A selection commit (a pick, a clear, a closed bottom sheet, a checkbox toggle) marks the field touched and notifies autosave but does not run `field.onBlur`.
110
+ - `Select` stores item IDs (`value` is an ID, or an array of IDs with `selectionMode="multiple"`). `Autocomplete` stores entries that are either a picked suggestion (`{ id, label }`, an exact match) or typed text (`{ label }`, a partial match): one entry or null by default, an array of chips with `selectionMode="multiple"` (like an email "To" line).
111
+ - `Select`, `Autocomplete`, `ToggleGroup`, `RadioGroup` and `CheckboxGroup` all take `items: { id, label }[]`; their values are the item `id`s, except `Autocomplete`, whose entries keep the `id` next to the `label`. `Select` and `Autocomplete` also take `list={useAsyncList<Item>(...)}` instead of `items`; pass the item type, or the list's items are `unknown` and `Select` rejects it. Give `Select` the saved record as `initialSelection` so its label shows before its page loads. `RadioGroup` and `CheckboxGroup` items may set `isDisabled`, and numeric ids stay numbers in the value.
112
+ - For a list that depends on another field (cities of the chosen country), read the parent with `useFormValue` inside the loader, and in the parent's `field.onValueChange` reset the child (`form.resetField("cityId")`) and call `cities.reload()`. `reload()` loads after that change renders, with the new loader, and keeps the current filter text (`DependentAsyncListExample` in the use-async-list example).
113
+ - `Checkbox` and `Switch` take their label as children; every other input takes `label`.
114
+ - `NumberField` values are `number | null`. `onChange` fires while the user types, with the parsed value; the displayed text is normalised on blur.
115
+ - Every range value is `{ start, end }`: `NumberRangeInput` (`number | null` sides), `Slider` with `isRange` (numbers) and `DateRangePicker` (ISO strings). `minValue` and `maxValue` are always the allowed bounds, never a side of the range.
116
+ - `isInvalid` marks a field invalid without a message; `error` marks it and shows the text. `isRequired` only marks the field (asterisk, `aria-required`); the form's schema enforces it. A `<form>` with a bound field gets `noValidate`, so `type="email"`, `minLength` and `pattern` never block the submit: put those rules in the schema too.
117
+ - Date and time controls use ISO strings, not `Date` objects. `DatePicker` emits UTC midnight (`YYYY-MM-DDT00:00:00.000Z`), or `YYYY-MM-DD` with `fullIso={false}`; `TimePicker` and `DateTimePicker` emit full UTC timestamps. `minValue`/`maxValue` take the same string format as `value`; `TimePicker` also takes `HH:mm`. An empty date or time value is `null`, never `""`. A string the picker cannot read (`""`, `"14:30"` in `value`, a timestamp without `Z` or an offset, `05/01/2024`) renders an empty field and logs a warning naming the component.
118
+ - Resolve a stored relative preset (`{ relativeValue: "lastWeek" }`) with `const resolvePreset = useResolveDateRangePreset()` (`{ fullIso: false }` for a `fullIso={false}` picker). It uses the picker's locale for the week start and `UIConfig.dateInput.timeZone` for today. Plain `resolveDateRangePreset(value)` defaults to `en-GB` (Monday weeks) and the browser zone, so its week presets are a day off from an en-US picker.
119
+ - `RichTextEditor` values are `{ html, json }`; content loads from `json`. Load its stylesheet with `@import "@povio/ui/rich-text-editor/styles";` in the app's global Tailwind CSS, after the theme. It uses `@apply` with theme tokens, so a JS/TS `import` fails both the Vite build and tsc (TS2882). Loading content (mount, `form.reset()`, a new `value`) never calls `onChange`, so a bound editor stays pristine until the user edits. The editable area is a `textbox` named by `label`, which stays the name with `hideLabel`, so test it with `getByRole("textbox", { name })`.
120
+ - `Input`, `PasswordInput`, `NumberField`, `NumberRangeInput`, `Select` and the date/time pickers render a lightweight static field first and mount the live control on hover, focus or press; pass `renderStaticInput={false}` to them when code needs the input ref right after mount. `TextArea`, `Autocomplete` and `RichTextEditor` are always live and take no `renderStaticInput`. `autoFocus` mounts the live control at once and focuses it once.
121
+ - Use `isReadOnly` for read-only presentation on the inputs that have it. It blocks edits and hides the clear button, and on the date and time pickers also disables the picker and today buttons. `Slider`, `FileInput` and `FileUpload` reject it with a hint: show the value as text, or use `isDisabled`.
122
+ - `IconButton` requires an accessible name: `label`, `aria-label` or `aria-labelledby`.
123
+ - `FileUpload` uploads each file through `onUpload(file, { signal, onProgress })`, which resolves with `{ id }`. `value`, `defaultValue`, `onChange` and a bound field hold `UploadedFile[]` (`{ id, name, size?, type?, url? }`), always an array and only finished uploads. A bound `FileUpload` fails the form's submit while an upload runs: `onInvalid` runs and the field shows "Wait for the upload to finish" until no upload is running. `FileInput` holds native `File`s and uploads nothing.
124
+ - A standalone `FileUpload` (`value`/`onChange`) does not block a submit: disable the submit button while uploads run, e.g. count them in your `onUpload` wrapper (`setActive((c) => c + 1); try { return await upload(file, options); } finally { setActive((c) => c - 1); }`) and set `isDisabled={active > 0}`. Pass the `signal` on to the request so cancelling or unmounting really stops the transfer. For previews of fresh uploads, return `{ id, url: URL.createObjectURL(file) }` from `onUpload` and revoke the URL when the file leaves `value`.
125
+ - A `FileUpload` without `label` renders no field header. Render-function children replace the browse button and the built-in file list.
126
+ - `Dialog`, `Drawer`, `BottomSheet` and `Popover` share one shape: pass `trigger` (a pressable element) and the overlay owns its open state, or control it with `isOpen` + `onOpenChange`. `label` is the required accessible name; only `BottomSheet` (and `Popover` below `md`) renders it, as the sheet header. `children` is content or `(close) => content`. `className` styles the visible surface: the panel of `Dialog` and `Drawer`, the sheet of `BottomSheet`, and the popover panel of `Popover` (its sheet below `md`, so scope widths with `md:`); the backdrop of `Dialog`, `Drawer` and `BottomSheet` is `overlayClassName`. `Popover` always needs `trigger`, which anchors it.
127
+ - `Dialog`, `Drawer` and `BottomSheet` close on outside press by default; pass `isDismissable={false}` to require an explicit action.
128
+ - `confirm()` closes the dialog as soon as the user answers. To keep it open with a loading confirm button while the action runs, pass `onConfirm: () => promise`; `confirm()` then resolves `true` after it finishes, or rejects with its error (the dialog closes). Queued `confirm()` calls show one after another, each as a new dialog.
129
+ - `AlertDialog` (and every `confirm()` prompt) renders `role="alertdialog"`, named by `heading` and described by `description`.
130
+ - Toast functions from `useToast` take a string or `{ text, icon, actions }`: `successToast("Saved")`. A toast closes after 2.5 s; one with `actions` stays, with a close button, until the user closes it or presses an action, which also closes it (pass `{ autoClose }` to time it out anyway). Pass `{ toastId }` to dedupe a toast: one whose ID is still on screen is not shown again, and `closeToast(toastId)` closes it. Toasts default to the `bottom-right` corner (`UIConfig` `toast.position`). `useToast` is exported from both `@povio/ui/toast` and `@povio/ui/use-toast`.
131
+ - An `Alert` that appears at runtime needs `role`: `role="alert"` for an error after an action, `role="status"` for other messages. Leave it unset for an `Alert` that is on the page from the start.
132
+ - `Progress` is a progressbar and needs a name: `label` (shown above the bar; add `hideLabel` when a caption is already visible) or `aria-labelledby`.
133
+ - `TooltipEllipsis`: the element that truncates needs a width limit, its own (`max-w-40`) or its container's (`block truncate` in a table cell).
134
+ - Display badges default to `variant="subtle"`, `as="button"` to `contained` and `as="toggle"` to `outlined`. Removable `Tag`/`Badge` buttons are named "Remove <text>"; `removeButtonProps={{ "aria-label": … }}` overrides it. Focus moves to the neighbouring remove button after a keyboard removal; after the last one, move focus yourself.
135
+ - A workspace rail goes next to the `Sidebar` in `SidebarLayout`'s `navigation`, never inside it: `navigation={<><SidebarWorkspaces items={[{ id, label }]} value={id} onChange={setId} /><Sidebar …>…</Sidebar></>}`. `value` may be `null`.
136
+ - `useBreakpoint` from `@povio/ui/use-breakpoint` reads the Tailwind breakpoints (SSR value from `UIConfig.responsive.ssrMatches`); don't write media queries by hand. `Popover` and `DropdownMenu` already switch to a sheet below `md`.
137
+ - `Slider` `value` and a bound slider's field value may be `null`, shown with the thumbs at `minValue`.
138
+ - `useFilters` and `useSorting` keep their state in the URL and need `UIRouter.UIRouterProvider` from `@povio/ui/ui-router` at the app root. They take one options object: `useFilters({ defaultValues, prefix, schema })`, `useSorting({ defaultSorting, prefix })`. With `schema`, `useFilters` is typed from it (no type argument) and leaves out URL values that fail it, so `filterData` is `Partial` of the schema output. Without `schema` the values are only decoded from the URL (`1` becomes the number 1) and typed `unknown`, and a type argument without `schema` does not compile. The URL keys are `filter[<key>]` (`filter[<prefix>][<key>]` with a `prefix`) and `order` (`order-<prefix>`), so a link into a filtered list sets e.g. `search: { "filter[status]": "open" }`. Give every store on a page its own `prefix`; each one reads and writes only its own keys, and prefixes and keys contain no `[` or `]`. URL values come back as text, with numbers, booleans and ISO dates (for `z.date()`) read back from it. Several `setFilterValue` calls in one handler build on each other, and `useSorting` follows the URL when it changes (back/forward, links). Once the user clears a sort it stays cleared (the next header click sorts again) until the URL changes from outside; `defaultSorting` applies only to a URL without a sort. A `schema` typed as possibly `undefined` matches neither form of `useFilters`: branch on it, or always pass one.
139
+ - `Table` has no pager; use `InfiniteTable` for server lists. The table does not reorder rows; send `order` from `useSorting` to the query (a sort in the URL wins over `defaultSorting`). Headers are sortable only when `onSortingChange` is passed.
140
+ - Tables show their own loading and empty states: pass the query's `isLoading` (the body shows a spinner) and optionally `emptyState` (any node; defaults to a translated "No results"). Wire `isLoading`, `hasNextPage`, `isFetchingNextPage` and `fetchNextPage` straight from the infinite query. Don't wrap the table in your own spinner or empty branch. A table has no error state: when the query has failed with no data (`query.error && !query.data`), render your error UI instead of the table, or a failed load shows "No results".
141
+ - `Table` and `InfiniteTable`: `className` styles the `<table>` element and `containerClassName` its scroll container (border, radius, background); use `maxHeight` (not a `max-h-*` class) for a table that scrolls with a pinned header.
142
+ - Type columns as `ColumnDef<Row>[]` from `@povio/ui/tanstack/table`; TanStack's own v9 `ColumnDef` takes the table features first.
143
+ - `enableRowSelection` adds the checkbox column with select-all; selection is multiple unless `enableMultiRowSelection={false}`, and a table without it selects nothing. Do not add your own checkbox column. Pass `getRowId={(row) => row.id}` for server-loaded rows: without it the selection is keyed by row index, so a refetch that removes, adds or reorders rows moves the selection to other rows, and bulk actions hit the wrong records. `bulkSelectionActions` is a component that receives `table`: define it at module scope, not inline. `ColumnConfigModal` opens like `Dialog`: `trigger`, or `isOpen` + `onOpenChange`. Columns with `enableHiding: false` (row actions) always show and are not listed in `ColumnConfigModal`; columns missing from a saved `columnOrder` go last.
144
+ - Tables are keyboard reachable: Tab lands on one body cell, the arrows move between cells (from a header button or row checkbox too), and Enter runs the row action. Drag handles reorder with Space, the arrows, then Space; Escape cancels.
145
+ - For tabs held in state use `ToggleGroup` with a literal `disallowEmptySelection`, so `onChange` always receives an id and accepts the state setter. `ListTabs` renders navigation links (one URL per tab, `activeId` from the route) and has no `onChange`.
146
+ - Use `ButtonGroup` for grouped independent actions and `ToggleGroup` only when the group holds a selected value.
147
+ - Use `Drawer` for side panels, `Dialog` for centred modals and `AlertDialog` for confirmations.
148
+
149
+ ## Styling
150
+
151
+ - Style a component through `className` where it has one; independently styled internal parts have their own `*ClassName` props.
152
+ - Use the shadcn colour roles in pairs (`bg-primary text-primary-foreground`, `text-muted-foreground`, `border-input`). Palette utilities such as `bg-neutral-500` do not exist.
153
+ - Colour props take the library's names, not shadcn's: `Button`, `IconButton` and `SplitButton` `color` is `primary`, `secondary`, `error` or `dual`, and `variant` is `contained`, `outlined`, `subtle`, `text` or `ghost`; `Badge` and `Tag` take `primary`, `secondary`, `success`, `warning` or `error`; `Alert` takes `secondary`, `success`, `warning` or `error`; `DropdownMenu` items take `default` or `error`; a toast's colour is the function that shows it (`successToast`, `errorToast`, `warningToast`, `secondaryToast`). `error` is the destructive colour and `secondary` the neutral grey; there is no `neutral`.
154
+ - App-wide defaults go through `UIConfig.Provider` (the default input layout is its `input.layout` key); app-wide class changes go through `UIOverrides.Provider`. Do not wrap a component just to change its default props or classes.
155
+ - Input-family recipes key their layout variant `layout`, like the prop (e.g. `variants: { layout: { floating: "…" } }`). Override configs are not type-checked against variant names, so a wrong key compiles and does nothing.
156
+ - Style recipes (`*Definition`) are exported only from `@povio/ui/style-definitions`.
157
+
158
+ ## Index
159
+
160
+ Every public import path, what it is for and its main exports. Each path with a component or hook has a canonical example under Examples.
161
+
162
+ | Import path | Main exports | For |
163
+ | --- | --- | --- |
164
+ | `@povio/ui/accordion` | `Accordion` | Collapsible sections, such as an FAQ. |
165
+ | `@povio/ui/alert` | `Alert` | An inline message about the state of a page or form. |
166
+ | `@povio/ui/alert-dialog` | `AlertDialog`, `AlertDialogAction` | A modal that asks the user to confirm or cancel one action. |
167
+ | `@povio/ui/autocomplete` | `Autocomplete`, `AutocompleteValue` | A text field with suggestions that also accepts text that is not in the list. |
168
+ | `@povio/ui/badge` | `Badge` | A compact label for a status or category, which can also be a small button or toggle. |
169
+ | `@povio/ui/bottom-sheet` | `BottomSheet` | A panel that slides up from the bottom of the screen. |
170
+ | `@povio/ui/bottom-sheet-header` | `BottomSheetHeader` | The title row of a `BottomSheet` with custom content. |
171
+ | `@povio/ui/breadcrumbs` | `Breadcrumbs` | The trail of links to the pages above the current one. |
172
+ | `@povio/ui/button` | `Button` | An action with a visible label, or a link that looks like a button. |
173
+ | `@povio/ui/button-group` | `ButtonGroup` | Groups buttons whose actions are independent of each other. |
174
+ | `@povio/ui/checkbox` | `Checkbox` | One checkbox for a yes or no value. |
175
+ | `@povio/ui/checkbox-group` | `CheckboxGroup` | Checkboxes for picking any number of options from a short list. |
176
+ | `@povio/ui/component-configuration` | `resolveUIConfiguration`, `parseComponentConfiguration` | Helpers for loading saved configurator output. |
177
+ | `@povio/ui/compound-mapper` | `compoundMapper` | Builds class maps for compound variants. |
178
+ | `@povio/ui/confirmation` | `Confirmation` | Asks the user to confirm an action from an event handler and resolves to the answer. |
179
+ | `@povio/ui/date-picker` | `DatePicker` | A date field with a calendar. |
180
+ | `@povio/ui/date-range-picker` | `DateRangePicker`, `DateRangePickerValue` | A field for a start and an end date, optionally with relative presets such as last week. |
181
+ | `@povio/ui/date-range-presets` | `isStoredRelativeDateRangeValue`, `useResolveDateRangePreset`, `StoredRelativeDateRangeValue` | Helpers that store and resolve the relative presets of a `DateRangePicker`. |
182
+ | `@povio/ui/date-time-picker` | `DateTimePicker` | A field for a date and a time of day. |
183
+ | `@povio/ui/date-time-utils` | `DateTimeUtils` | Conversions between ISO strings and calendar values. |
184
+ | `@povio/ui/date-utils` | `DateUtils` | Date formatting helpers. |
185
+ | `@povio/ui/dialog` | `Dialog` | A centred modal for a short task or message. |
186
+ | `@povio/ui/drawer` | `Drawer` | A panel that slides in from the side, for a form or the details of a record. |
187
+ | `@povio/ui/dropdown-menu` | `DropdownMenu`, `DropdownMenuItem` | A menu of actions opened from a button. |
188
+ | `@povio/ui/file-input` | `FileInput` | A file picker whose value is the picked files themselves, for forms that upload on submit. |
189
+ | `@povio/ui/file-upload` | `FileUpload`, `UploadedFile` | A drop zone and file list that uploads each file as soon as it is picked. |
190
+ | `@povio/ui/file-utils` | `FileUtils` | File size and type helpers. |
191
+ | `@povio/ui/form-field` | `FormField` | The label, helper text and error around a custom control. |
192
+ | `@povio/ui/form-layout` | `FormLayout`, `FormLayoutActions`, `FormLayoutRow`, `FormLayoutSection` | Lays out the fields and actions of a form. |
193
+ | `@povio/ui/icon-button` | `IconButton` | An action shown as an icon, with a tooltip. |
194
+ | `@povio/ui/icon-slot` | `IconSlot` | Renders an icon in the library's 16px icon box. |
195
+ | `@povio/ui/input` | `Input` | A single-line text field. |
196
+ | `@povio/ui/input-frame` | `InputFrame` | The field chrome (label, border, helper and error text) for building a custom input. |
197
+ | `@povio/ui/input-styles` | `InputVariantProps` | The `variant`, `layout` and `size` props shared by inputs. |
198
+ | `@povio/ui/intl-utils` | `IntlUtils` | Number and locale formatting helpers. |
199
+ | `@povio/ui/link` | `Link` | An inline text link to another page or site. |
200
+ | `@povio/ui/link-context` | `LinkContext` | Supplies the router link that `Link`, `SidebarItem`, breadcrumbs and buttons with `link` render; mount it once at the app root, around the router. |
201
+ | `@povio/ui/logger` | `logger` | The library logger. |
202
+ | `@povio/ui/number-field` | `NumberField` | A field for one number. |
203
+ | `@povio/ui/number-range-input` | `NumberRangeInput`, `NumberRangeValue` | Two number fields for a from-to range, such as a price filter. |
204
+ | `@povio/ui/outline` | `uiOutlineClass` | The shared focus-ring classes. |
205
+ | `@povio/ui/page-header` | `PageHeader`, `PageHeaderDetails` | The top of a page: title, breadcrumbs or a back link, status and actions. |
206
+ | `@povio/ui/password-input` | `PasswordInput` | A password field with a show and hide toggle. |
207
+ | `@povio/ui/popover` | `Popover` | Floating content anchored to a button, shown as a bottom sheet on small screens. |
208
+ | `@povio/ui/progress` | `Progress` | A progressbar that shows how far a task has got. |
209
+ | `@povio/ui/radio-group` | `RadioGroup` | Picks one option from a short list, with every option visible. |
210
+ | `@povio/ui/resources` | `ns`, `resources` | The library's i18next namespace and translations. |
211
+ | `@povio/ui/rich-text-editor` | `RichTextEditor`, `RichTextEditorValue` | A formatted text editor with a toolbar. |
212
+ | `@povio/ui/rich-text-editor/styles` | — | Stylesheet for `RichTextEditor`; `@import` it in the app's global Tailwind CSS, after the theme (not from JS). |
213
+ | `@povio/ui/select` | `Select` | A dropdown for picking one item, or several, from a list. |
214
+ | `@povio/ui/sidebar` | `Sidebar`, `SidebarContent`, `SidebarGroup`, `SidebarItem`, `SidebarLayout`, `SidebarWorkspaces`, `SidebarWorkspaceOption` | The app's side navigation and the page layout around it. |
215
+ | `@povio/ui/slider` | `Slider` | Picks a number, or a range, by dragging. |
216
+ | `@povio/ui/spinner` | `Spinner` | An animated indicator for content that is loading. |
217
+ | `@povio/ui/split-button` | `SplitButton` | A main action with a menu of related actions beside it. |
218
+ | `@povio/ui/stepper` | `Stepper`, `StepItem` | Shows the steps of a multi-step flow and which one is current. |
219
+ | `@povio/ui/string-utils` | `StringUtils` | String helpers. |
220
+ | `@povio/ui/style-definitions` | `*Definition`, `cvaDefinitions` | Every style recipe, for composing `UIOverrides`. |
221
+ | `@povio/ui/switch` | `Switch` | An on and off toggle for a setting. |
222
+ | `@povio/ui/tabs-filters` | `ListTabs`, `TabsFilters`, `ListTab` | The bar above a list that holds its tabs and filters. |
223
+ | `@povio/ui/tag` | `Tag` | A static chip for a keyword or category, optionally removable. |
224
+ | `@povio/ui/tanstack/form` | `useForm`, `useFormState`, `useFormValue` | Form state and validation: `useForm` with a zod schema, and hooks that read its values and state. |
225
+ | `@povio/ui/tanstack/table` | `ColumnConfigModal`, `InfiniteTable`, `Table`, `useSorting`, `useTableColumnConfig`, `BulkSelectionActionsComponent`, `ColumnDef`, `InfiniteTableProps`, `RowSelectionState` | Data tables: `InfiniteTable` for server lists, `Table` for short fixed data, sorting and configurable columns. |
226
+ | `@povio/ui/text-area` | `TextArea` | A multi-line text field. |
227
+ | `@povio/ui/theme-context` | `ThemeContext` | The active light or dark theme. |
228
+ | `@povio/ui/time-picker` | `TimePicker` | A field for a time of day. |
229
+ | `@povio/ui/toast` | `ToastContainer`, `useToast` | Temporary notifications shown over the page. |
230
+ | `@povio/ui/toggle-button` | `ToggleButton` | A button that stays pressed until it is pressed again, for one on or off option. |
231
+ | `@povio/ui/toggle-group` | `ToggleGroup` | A segmented control for picking one, or several, of a few options; also tabs held in state. |
232
+ | `@povio/ui/tooltip` | `Tooltip` | A short hint shown while the user hovers over or focuses its trigger. |
233
+ | `@povio/ui/tooltip-ellipsis` | `TooltipEllipsis` | Shows the full text in a tooltip while it is cut off with an ellipsis. |
234
+ | `@povio/ui/tw-ui-plugin` | — | Tailwind plugin with the library's variants; load it from the app stylesheet with `@plugin`. |
235
+ | `@povio/ui/types` | `OmitDiscriminatedUnion` | Shared utility types. |
236
+ | `@povio/ui/typography` | `Typography` | Text in the library's type scale, from page headings to small print. |
237
+ | `@povio/ui/ui-config` | `UIConfig` | App-wide default props, such as the default input layout. |
238
+ | `@povio/ui/ui-overrides` | `UIOverrides` | App-wide class changes to the component style recipes. |
239
+ | `@povio/ui/ui-router` | `UIRouter` | `UIRouter.UIRouterProvider` connects the app router (`push`, `replace`, `searchString`) to the URL state of `useFilters` and `useSorting`; mount it once at the app root. `UIRouter.useUIRouter()` returns the connection plus `searchParams` and `updateSearch((search) => next)`, which writes search keys on top of pending `useFilters`/`useSorting` writes. |
240
+ | `@povio/ui/use-async-list` | `useAsyncList` | Loads the items of a `Select` or `Autocomplete` from the server, page by page and per search. |
241
+ | `@povio/ui/use-breakpoint` | `useBreakpoint` | Whether the viewport is at least a Tailwind breakpoint wide (`sm`, `md`, `lg`, `xl`), the same switch the library's own components use. |
242
+ | `@povio/ui/use-filters` | `useFilters` | List filters kept in the URL query string. |
243
+ | `@povio/ui/use-local-storage` | `useLocalStorage` | State persisted in local storage. |
244
+ | `@povio/ui/use-toast` | `useToast` | Shows success, error, warning and secondary (neutral grey) toasts from code. |
245
+ | `@povio/ui/use-translation-memo` | `useTranslationMemo` | Memoises values that depend on the active language. |
246
+ | `@povio/ui` | — | Compatibility barrel; import from the component subpaths instead. `installServiceWorker` is only exported here. |
247
+ | `@povio/ui/tanstack` | — | Compatibility barrel; import from the component subpaths instead. |
248
+ | `@povio/ui/<component>/react-aria` | The matching React Aria primitive and its types | Custom implementations; also the hooks the library uses (`use-text-field`, `use-focus-within`, …) and the `key` and `selection` types. |
249
+
250
+ ## Examples
251
+
252
+ ### @povio/ui/accordion
253
+
254
+ ```tsx
255
+ import { Accordion } from "@povio/ui/accordion";
256
+
257
+ /** Collapsible sections, such as an FAQ. Sections are data in `items` (`id`, `label`, optional `description`, `children`), not JSX; disable one section with `isDisabled` on its item. */
258
+ export function AccordionExample({ faqs }: { faqs: { id: string; question: string; answer: string }[] }) {
259
+ return (
260
+ <Accordion
261
+ variant="outlined"
262
+ defaultExpandedKeys={faqs.slice(0, 1).map((faq) => faq.id)}
263
+ items={faqs.map((faq) => ({
264
+ id: faq.id,
265
+ label: faq.question,
266
+ children: <p className="text-muted-foreground">{faq.answer}</p>,
267
+ }))}
268
+ />
269
+ );
270
+ }
271
+ ```
272
+
273
+ ### @povio/ui/alert
274
+
275
+ ```tsx
276
+ import { TriangleAlert } from "lucide-react";
277
+ import { Alert } from "@povio/ui/alert";
278
+ import { Button } from "@povio/ui/button";
279
+
280
+ /** An inline message about the state of a page or form. The message is the `text` string prop (no children, no title) and actions go in `rightContent`; `color` is `secondary | success | warning | error` (`secondary`, the neutral grey, is the default). `icon` takes a component (`icon={TriangleAlert}`) or an element (`icon={<TriangleAlert />}`), as on `Button`. An Alert that appears at runtime needs `role` so screen readers announce it: `role="alert"` for an error after an action, `role="status"` for other messages; leave it unset for an Alert that is on the page from the start. */
281
+ export function AlertExample({
282
+ daysLeft,
283
+ isUpgrading,
284
+ onUpgrade,
285
+ }: {
286
+ daysLeft: number;
287
+ isUpgrading: boolean;
288
+ onUpgrade: () => void;
289
+ }) {
290
+ return (
291
+ <Alert
292
+ color="warning"
293
+ icon={TriangleAlert}
294
+ text={`Your trial ends in ${daysLeft} days.`}
295
+ isLoading={isUpgrading}
296
+ hasSeparator
297
+ rightContent={
298
+ <Button
299
+ size="sm"
300
+ variant="outlined"
301
+ onPress={onUpgrade}
302
+ >
303
+ Upgrade
304
+ </Button>
305
+ }
306
+ />
307
+ );
308
+ }
309
+
310
+ /** An Alert shown after an action fails: it appears at runtime, so it sets `role="alert"` and screen readers announce it. */
311
+ export function SaveErrorAlertExample({ error }: { error: string | null }) {
312
+ return error ? (
313
+ <Alert
314
+ role="alert"
315
+ color="error"
316
+ icon={TriangleAlert}
317
+ text={error}
318
+ />
319
+ ) : null;
320
+ }
321
+ ```
322
+
323
+ ### @povio/ui/alert-dialog
324
+
325
+ ```tsx
326
+ import { AlertDialog, type AlertDialogAction } from "@povio/ui/alert-dialog";
327
+
328
+ /** A modal that asks the user to confirm or cancel one action. Content is props, not children: `heading`, `description`, `confirmAction` and the optional `cancelAction` (`{ label, onPress, isLoading, isDisabled, color, variant }`). Actions do not close the dialog, so close it in `onPress` or when the request finishes; opening works as on `Dialog` (`isOpen` + `onOpenChange`, or `trigger`). It renders `role="alertdialog"`, named by `heading` and described by `description`; style those with `headingClassName`/`headingTypography` and `descriptionClassName`/`descriptionTypography`. */
329
+ export function AlertDialogExample({
330
+ userName,
331
+ isOpen,
332
+ isDeleting,
333
+ onOpenChange,
334
+ onDelete,
335
+ }: {
336
+ userName: string;
337
+ isOpen: boolean;
338
+ isDeleting: boolean;
339
+ onOpenChange: (isOpen: boolean) => void;
340
+ onDelete: () => Promise<void>;
341
+ }) {
342
+ const cancel: AlertDialogAction = { label: "Cancel", isDisabled: isDeleting, onPress: () => onOpenChange(false) };
343
+
344
+ return (
345
+ <AlertDialog
346
+ isOpen={isOpen}
347
+ onOpenChange={onOpenChange}
348
+ // Keep the dialog up while the request runs.
349
+ isDismissable={!isDeleting}
350
+ heading="Delete user?"
351
+ description={`${userName} will lose access immediately. This cannot be undone.`}
352
+ confirmAction={{
353
+ label: "Delete",
354
+ color: "error",
355
+ isLoading: isDeleting,
356
+ onPress: () => void onDelete().then(() => onOpenChange(false)),
357
+ }}
358
+ cancelAction={cancel}
359
+ />
360
+ );
361
+ }
362
+ ```
363
+
364
+ ### @povio/ui/autocomplete
365
+
366
+ ```tsx
367
+ import { Autocomplete, type AutocompleteValue } from "@povio/ui/autocomplete";
368
+ import { useForm } from "@povio/ui/tanstack/form";
369
+ import { useAsyncList } from "@povio/ui/use-async-list";
370
+ import { z } from "zod";
371
+
372
+ interface City {
373
+ id: string;
374
+ label: string;
375
+ }
376
+
377
+ const cities: City[] = [
378
+ { id: "lj", label: "Ljubljana" },
379
+ { id: "mb", label: "Maribor" },
380
+ ];
381
+
382
+ // One entry: a picked suggestion carries its `id` (exact match); typed text has only a `label` (partial match).
383
+ const entry = z.object({ id: z.string().optional(), label: z.string() });
384
+ const schema = z.object({ cities: z.array(entry).min(1, "Add at least one city"), destination: entry.nullable() });
385
+
386
+ /**
387
+ * A text field with suggestions that also accepts text that is not in the list.
388
+ * Holds picked suggestions and typed text side by side. Single mode is a text box holding one entry or null;
389
+ * `selectionMode="multiple"` is a row of chips, like an email "To" line (Enter or blur turns typed text into a chip).
390
+ * To allow only the listed options, use `Select isSearchable`.
391
+ */
392
+ export function AutocompleteExample({
393
+ value,
394
+ onChange,
395
+ searchCities,
396
+ }: {
397
+ value: AutocompleteValue<string> | null;
398
+ onChange: (value: AutocompleteValue<string> | null) => void;
399
+ searchCities: (search: string, signal: AbortSignal) => Promise<City[]>;
400
+ }) {
401
+ const form = useForm({ defaultValues: { cities: [], destination: null }, zodSchema: schema });
402
+ // Remote suggestions: the typed text reaches the loader as `filterText` (debounced).
403
+ const remoteCities = useAsyncList<City>({
404
+ load: async ({ signal, filterText = "" }) => ({ items: await searchCities(filterText, signal) }),
405
+ });
406
+ return (
407
+ <>
408
+ <Autocomplete
409
+ label="Birthplace"
410
+ items={cities}
411
+ value={value}
412
+ onChange={onChange}
413
+ />
414
+ <Autocomplete
415
+ label="Cities"
416
+ selectionMode="multiple"
417
+ items={cities}
418
+ field={{ form, name: "cities" }}
419
+ />
420
+ <Autocomplete
421
+ label="Destination"
422
+ list={remoteCities}
423
+ field={{ form, name: "destination" }}
424
+ />
425
+ </>
426
+ );
427
+ }
428
+
429
+ /** Turns the entries into a filter: ids match exactly, typed text matches partially. */
430
+ export const toCityFilter = (entries: AutocompleteValue<string>[]) => ({
431
+ cityIds: entries.flatMap((entry) => (entry.id == null ? [] : [entry.id])),
432
+ cityNameContains: entries.flatMap((entry) => (entry.id == null ? [entry.label] : [])),
433
+ });
434
+ ```
435
+
436
+ ### @povio/ui/badge
437
+
438
+ ```tsx
439
+ import { Badge } from "@povio/ui/badge";
440
+
441
+ /** A compact label for a status or category, which can also be a small button or toggle. Without `as` a badge is display-only (`onPress` and `onChange` do not compile) and `onRemove` adds a remove button; `as="button"` takes `onPress`, `as="toggle"` takes `isSelected` + `onChange` (not `onPress`). Display badges default to the `subtle` variant, `as="button"` to `contained` and `as="toggle"` to `outlined`, which fills when selected. A remove button is named "Remove <text>"; `removeButtonProps={{ "aria-label" }}` replaces that name. */
442
+ export function BadgeExample({
443
+ onRemoveFilter,
444
+ onClearFilters,
445
+ isPinned,
446
+ onPinnedChange,
447
+ }: {
448
+ onRemoveFilter: () => void;
449
+ onClearFilters: () => void;
450
+ isPinned: boolean;
451
+ onPinnedChange: (isPinned: boolean) => void;
452
+ }) {
453
+ return (
454
+ <div className="flex flex-wrap items-center gap-2">
455
+ <Badge color="success">Active</Badge>
456
+ <Badge onRemove={onRemoveFilter}>Status: open</Badge>
457
+ <Badge
458
+ as="button"
459
+ onPress={onClearFilters}
460
+ >
461
+ Clear filters
462
+ </Badge>
463
+ <Badge
464
+ as="toggle"
465
+ isSelected={isPinned}
466
+ onChange={onPinnedChange}
467
+ >
468
+ Pinned
469
+ </Badge>
470
+ </div>
471
+ );
472
+ }
473
+ ```
474
+
475
+ ### @povio/ui/bottom-sheet
476
+
477
+ ```tsx
478
+ import { BottomSheet } from "@povio/ui/bottom-sheet";
479
+ import { Button } from "@povio/ui/button";
480
+ import { Typography } from "@povio/ui/typography";
481
+
482
+ /** A panel that slides up from the bottom of the screen. Same shape as `Dialog`: pass `trigger`, or control it with `isOpen` + `onOpenChange`. Unlike the other overlays, `label` is rendered: it is the header text as well as the accessible name. `height` defaults to `full` (use `auto` for short content), and children are nodes or a function `(close) => …`. */
483
+ export function BottomSheetExample({ options, onSelect }: { options: string[]; onSelect: (option: string) => void }) {
484
+ return (
485
+ <BottomSheet
486
+ trigger={<Button variant="outlined">Sort</Button>}
487
+ label="Sort by"
488
+ height="auto"
489
+ >
490
+ {(close) => (
491
+ <div className="flex flex-col gap-1 p-4">
492
+ {options.map((option) => (
493
+ <Button
494
+ key={option}
495
+ variant="ghost"
496
+ onPress={() => {
497
+ onSelect(option);
498
+ close();
499
+ }}
500
+ >
501
+ {option}
502
+ </Button>
503
+ ))}
504
+ </div>
505
+ )}
506
+ </BottomSheet>
507
+ );
508
+ }
509
+
510
+ /** Controlled, with plain children. `onOpenChange(false)` fires on Escape, outside press, drag-to-close and the close button. */
511
+ export function ControlledBottomSheetExample({
512
+ isOpen,
513
+ onOpenChange,
514
+ terms,
515
+ }: {
516
+ isOpen: boolean;
517
+ onOpenChange: (isOpen: boolean) => void;
518
+ terms: string;
519
+ }) {
520
+ return (
521
+ <BottomSheet
522
+ isOpen={isOpen}
523
+ onOpenChange={onOpenChange}
524
+ label="Terms of service"
525
+ >
526
+ <Typography
527
+ size="body"
528
+ className="overflow-y-auto p-4"
529
+ >
530
+ {terms}
531
+ </Typography>
532
+ </BottomSheet>
533
+ );
534
+ }
535
+ ```
536
+
537
+ ### @povio/ui/breadcrumbs
538
+
539
+ ```tsx
540
+ import { Home } from "lucide-react";
541
+ import { Breadcrumbs } from "@povio/ui/breadcrumbs";
542
+
543
+ /** The trail of links to the pages above the current one. Every item needs an `id`; navigation goes in `link={{ href }}`, and the last item (the current page) has none. There is no max-items prop: a trail of three or more items that does not fit its container collapses by itself to the first item, a "…" menu of the middle items, and the current page. */
544
+ export function BreadcrumbsExample({ projectId, projectName }: { projectId: string; projectName: string }) {
545
+ return (
546
+ <Breadcrumbs
547
+ items={[
548
+ { id: "home", label: "Home", icon: Home, link: { href: "/" } },
549
+ { id: "projects", label: "Projects", link: { href: "/projects" } },
550
+ { id: projectId, label: projectName },
551
+ ]}
552
+ />
553
+ );
554
+ }
555
+ ```
556
+
557
+ ### @povio/ui/button
558
+
559
+ ```tsx
560
+ import { Plus } from "lucide-react";
561
+ import { Button } from "@povio/ui/button";
562
+
563
+ /** An action with a visible label, or a link that looks like a button. `icon` + `iconPosition` place one icon; `isLoading` shows a spinner and disables the button. Navigation goes in `link={{ href }}`, not `href`, and renders the router link registered through `LinkContext`. */
564
+ export function ButtonExample({
565
+ isSaving,
566
+ onSave,
567
+ invoiceId,
568
+ }: {
569
+ isSaving: boolean;
570
+ onSave: () => void;
571
+ invoiceId: string;
572
+ }) {
573
+ return (
574
+ <div className="flex items-center gap-2">
575
+ <Button
576
+ variant="outlined"
577
+ link={{ href: `/invoices/${invoiceId}` }}
578
+ >
579
+ View invoice
580
+ </Button>
581
+ <Button
582
+ icon={Plus}
583
+ isLoading={isSaving}
584
+ onPress={onSave}
585
+ >
586
+ Save
587
+ </Button>
588
+ </div>
589
+ );
590
+ }
591
+ ```
592
+
593
+ ### @povio/ui/button-group
594
+
595
+ ```tsx
596
+ import { Button } from "@povio/ui/button";
597
+ import { ButtonGroup } from "@povio/ui/button-group";
598
+
599
+ /** Groups buttons whose actions are independent of each other. A `role="group"` layout wrapper for independent actions: it adds no spacing (use `className`) and holds no selected value (that is `ToggleGroup`). */
600
+ export function ButtonGroupExample({
601
+ isSaving,
602
+ onCancel,
603
+ onSave,
604
+ }: {
605
+ isSaving: boolean;
606
+ onCancel: () => void;
607
+ onSave: () => void;
608
+ }) {
609
+ return (
610
+ <ButtonGroup
611
+ aria-label="Form actions"
612
+ className="gap-2"
613
+ >
614
+ <Button
615
+ variant="outlined"
616
+ onPress={onCancel}
617
+ >
618
+ Cancel
619
+ </Button>
620
+ <Button
621
+ isLoading={isSaving}
622
+ onPress={onSave}
623
+ >
624
+ Save
625
+ </Button>
626
+ </ButtonGroup>
627
+ );
628
+ }
629
+ ```
630
+
631
+ ### @povio/ui/checkbox
632
+
633
+ ```tsx
634
+ import { Checkbox } from "@povio/ui/checkbox";
635
+ import { useForm } from "@povio/ui/tanstack/form";
636
+ import { z } from "zod";
637
+
638
+ const schema = z.object({ acceptTerms: z.boolean() });
639
+
640
+ /** One checkbox for a yes or no value. Boolean control: `isSelected` + `onChange(isSelected)`, not `checked`/`value`; the label is `children`, not `label`. */
641
+ export function CheckboxExample({
642
+ isSelected,
643
+ onChange,
644
+ }: {
645
+ isSelected: boolean;
646
+ onChange: (isSelected: boolean) => void;
647
+ }) {
648
+ const form = useForm({ defaultValues: { acceptTerms: false }, zodSchema: schema });
649
+ return (
650
+ <>
651
+ <Checkbox
652
+ isSelected={isSelected}
653
+ onChange={onChange}
654
+ >
655
+ Send me product updates
656
+ </Checkbox>
657
+ <Checkbox field={{ form, name: "acceptTerms" }}>I accept the terms</Checkbox>
658
+ </>
659
+ );
660
+ }
661
+ ```
662
+
663
+ ### @povio/ui/checkbox-group
664
+
665
+ ```tsx
666
+ import { CheckboxGroup } from "@povio/ui/checkbox-group";
667
+ import { useForm } from "@povio/ui/tanstack/form";
668
+ import { z } from "zod";
669
+
670
+ const channels = [
671
+ { id: "email", label: "Email" },
672
+ { id: "sms", label: "SMS" },
673
+ { id: "push", label: "Push" },
674
+ { id: "fax", label: "Fax", isDisabled: true },
675
+ ];
676
+
677
+ const schema = z.object({ channels: z.array(z.string()).min(1) });
678
+
679
+ /** Checkboxes for picking any number of options from a short list. Takes `items` of `{ id, label, isDisabled? }` like `Select` (not `options`/`value`); the value is `string[] | null` of the checked `id`s. */
680
+ export function CheckboxGroupExample({
681
+ value,
682
+ onChange,
683
+ }: {
684
+ value: string[] | null;
685
+ onChange: (value: string[] | null) => void;
686
+ }) {
687
+ const form = useForm({ defaultValues: { channels: ["email"] }, zodSchema: schema });
688
+ return (
689
+ <>
690
+ <CheckboxGroup
691
+ label="Notify me by"
692
+ items={channels}
693
+ value={value}
694
+ onChange={onChange}
695
+ />
696
+ <CheckboxGroup
697
+ label="Channels"
698
+ items={channels}
699
+ field={{ form, name: "channels" }}
700
+ />
701
+ </>
702
+ );
703
+ }
704
+ ```
705
+
706
+ ### @povio/ui/confirmation
707
+
708
+ ```tsx
709
+ import { Trash2 } from "lucide-react";
710
+ import { Button } from "@povio/ui/button";
711
+ import { Confirmation } from "@povio/ui/confirmation";
712
+
713
+ /** Asks the user to confirm an action from an event handler and resolves to the answer. `confirm()` resolves to a boolean, so `await` it; the dialog closes as soon as the user answers. `Confirmation.useConfirmation()` throws unless `Confirmation.Provider` wraps the app root. */
714
+ export function ConfirmationExample({
715
+ invoiceNumber,
716
+ onDelete,
717
+ }: {
718
+ invoiceNumber: string;
719
+ onDelete: () => Promise<void>;
720
+ }) {
721
+ const { confirm } = Confirmation.useConfirmation();
722
+ return (
723
+ <Button
724
+ icon={Trash2}
725
+ variant="outlined"
726
+ color="error"
727
+ onPress={async () => {
728
+ const isConfirmed = await confirm({
729
+ heading: `Delete invoice ${invoiceNumber}?`,
730
+ description: "This cannot be undone.",
731
+ confirmLabel: "Delete",
732
+ confirmColor: "error",
733
+ });
734
+ if (isConfirmed) {
735
+ await onDelete();
736
+ }
737
+ }}
738
+ >
739
+ Delete
740
+ </Button>
741
+ );
742
+ }
743
+
744
+ /** `onConfirm` keeps the dialog open while the action runs: the confirm button shows a spinner and cancelling is disabled until the promise settles. `confirm()` then resolves to `true`, or rejects with the action's error, which closes the dialog. */
745
+ export function ConfirmationPendingExample({
746
+ invoiceNumber,
747
+ onDelete,
748
+ onDeleteFailed,
749
+ }: {
750
+ invoiceNumber: string;
751
+ onDelete: () => Promise<void>;
752
+ onDeleteFailed: (error: unknown) => void;
753
+ }) {
754
+ const { confirm } = Confirmation.useConfirmation();
755
+ return (
756
+ <Button
757
+ icon={Trash2}
758
+ variant="outlined"
759
+ color="error"
760
+ onPress={() =>
761
+ confirm({
762
+ heading: `Delete invoice ${invoiceNumber}?`,
763
+ description: "This cannot be undone.",
764
+ confirmLabel: "Delete",
765
+ confirmColor: "error",
766
+ onConfirm: onDelete,
767
+ }).catch(onDeleteFailed)
768
+ }
769
+ >
770
+ Delete
771
+ </Button>
772
+ );
773
+ }
774
+ ```
775
+
776
+ ### @povio/ui/date-picker
777
+
778
+ ```tsx
779
+ import { DatePicker } from "@povio/ui/date-picker";
780
+ import { useForm } from "@povio/ui/tanstack/form";
781
+ import { z } from "zod";
782
+
783
+ // A required date: the field starts empty (`null` default) and the message replaces zod's generic one.
784
+ const schema = z.object({ birthday: z.iso.date({ error: "Pick a date" }) });
785
+
786
+ /** A date field with a calendar. Value is a `string | null`, never a `Date`: `YYYY-MM-DDT00:00:00.000Z` by default, `YYYY-MM-DD` with `fullIso={false}`. `minValue`/`maxValue` take the same format. */
787
+ export function DatePickerExample({
788
+ value,
789
+ onChange,
790
+ }: {
791
+ value: string | null;
792
+ onChange: (value: string | null) => void;
793
+ }) {
794
+ const form = useForm({ defaultValues: { birthday: null }, zodSchema: schema });
795
+ return (
796
+ <>
797
+ <DatePicker
798
+ label="Due date"
799
+ minValue="2025-01-01T00:00:00.000Z"
800
+ value={value}
801
+ onChange={onChange}
802
+ />
803
+ <DatePicker
804
+ label="Birthday"
805
+ fullIso={false}
806
+ isRequired
807
+ field={{ form, name: "birthday" }}
808
+ />
809
+ </>
810
+ );
811
+ }
812
+ ```
813
+
814
+ ### @povio/ui/date-range-picker
815
+
816
+ ```tsx
817
+ import { type DateRangePickerValue, DateRangePicker } from "@povio/ui/date-range-picker";
818
+ import { useForm } from "@povio/ui/tanstack/form";
819
+ import { z } from "zod";
820
+
821
+ const schema = z.object({
822
+ stay: z.object({ start: z.iso.date().nullable(), end: z.iso.date().nullable() }).nullable(),
823
+ });
824
+
825
+ /** A field for a start and an end date, optionally with relative presets such as last week. Value is `{ start, end } | null` of strings, not `Date`s or a tuple: start `YYYY-MM-DDT00:00:00.000Z` and end `YYYY-MM-DDT23:59:59.999Z` by default, both `YYYY-MM-DD` with `fullIso={false}`. */
826
+ export function DateRangePickerExample({
827
+ value,
828
+ onChange,
829
+ }: {
830
+ value: DateRangePickerValue;
831
+ onChange: (value: DateRangePickerValue) => void;
832
+ }) {
833
+ const form = useForm({ defaultValues: { stay: null }, zodSchema: schema });
834
+ return (
835
+ <>
836
+ <DateRangePicker
837
+ label="Created between"
838
+ value={value}
839
+ onChange={onChange}
840
+ isClearable
841
+ />
842
+ <DateRangePicker
843
+ label="Stay"
844
+ fullIso={false}
845
+ field={{ form, name: "stay" }}
846
+ />
847
+ </>
848
+ );
849
+ }
850
+ ```
851
+
852
+ ### @povio/ui/date-range-presets
853
+
854
+ ```tsx
855
+ import { type DateRangePickerValue, DateRangePicker } from "@povio/ui/date-range-picker";
856
+ import {
857
+ type StoredRelativeDateRangeValue,
858
+ isStoredRelativeDateRangeValue,
859
+ useResolveDateRangePreset,
860
+ } from "@povio/ui/date-range-presets";
861
+
862
+ type SavedRange = StoredRelativeDateRangeValue | DateRangePickerValue;
863
+
864
+ /** Helpers that store and resolve the relative presets of a `DateRangePicker`. Save a preset as its key (`{ relativeValue: "lastWeek" }`), not its dates, and resolve it again on every read with `useResolveDateRangePreset`, which uses the picker's locale (week start) and time zone; pass `{ fullIso: false }` when the picker has `fullIso={false}`. */
865
+ export function DateRangePresetsExample({
866
+ saved,
867
+ onSavedChange,
868
+ }: {
869
+ saved: SavedRange;
870
+ onSavedChange: (saved: SavedRange) => void;
871
+ }) {
872
+ const resolvePreset = useResolveDateRangePreset();
873
+ const isRelative = isStoredRelativeDateRangeValue(saved);
874
+ const range = isRelative ? (resolvePreset(saved.relativeValue) ?? null) : saved;
875
+ return (
876
+ <DateRangePicker
877
+ label="Created"
878
+ enableRelativeMode
879
+ relativeValue={isRelative ? saved.relativeValue : null}
880
+ value={range}
881
+ onChange={onSavedChange}
882
+ // Fires after `onChange` when a preset is picked, so the key replaces the resolved dates.
883
+ onRelativeChange={(relativeValue) => {
884
+ if (relativeValue) onSavedChange({ relativeValue });
885
+ }}
886
+ />
887
+ );
888
+ }
889
+ ```
890
+
891
+ ### @povio/ui/date-time-picker
892
+
893
+ ```tsx
894
+ import { DateTimePicker } from "@povio/ui/date-time-picker";
895
+ import { useForm } from "@povio/ui/tanstack/form";
896
+ import { z } from "zod";
897
+
898
+ const schema = z.object({ startsAt: z.iso.datetime().nullable() });
899
+
900
+ /** A field for a date and a time of day. Value is a UTC ISO string `YYYY-MM-DDTHH:mm:ss.sssZ` or `null`, never a `Date`; `timeZone` only changes the display. `minValue`/`maxValue` take the same format. */
901
+ export function DateTimePickerExample({
902
+ value,
903
+ onChange,
904
+ }: {
905
+ value: string | null;
906
+ onChange: (value: string | null) => void;
907
+ }) {
908
+ const form = useForm({ defaultValues: { startsAt: null }, zodSchema: schema });
909
+ return (
910
+ <>
911
+ <DateTimePicker
912
+ label="Published at"
913
+ timeZone="Europe/Ljubljana"
914
+ value={value}
915
+ onChange={onChange}
916
+ />
917
+ <DateTimePicker
918
+ label="Starts at"
919
+ minValue="2025-01-01T00:00:00.000Z"
920
+ field={{ form, name: "startsAt" }}
921
+ />
922
+ </>
923
+ );
924
+ }
925
+ ```
926
+
927
+ ### @povio/ui/dialog
928
+
929
+ ```tsx
930
+ import { useState } from "react";
931
+ import { Button } from "@povio/ui/button";
932
+ import { Dialog } from "@povio/ui/dialog";
933
+ import { Typography } from "@povio/ui/typography";
934
+
935
+ /** A centred modal for a short task or message. Same shape as `Drawer`, `BottomSheet` and `Popover`: pass `trigger` to let the dialog own its state, or control it with `isOpen` + `onOpenChange`. `label` names the dialog but is not rendered, so render your own heading and buttons; children may be a function `(close) => …`. */
936
+ export function DialogExample({ onSendInvite }: { onSendInvite: () => void }) {
937
+ return (
938
+ <Dialog
939
+ trigger={<Button>Invite teammate</Button>}
940
+ label="Invite teammate"
941
+ showCloseIcon
942
+ className="w-modal"
943
+ >
944
+ {(close) => (
945
+ <>
946
+ <Typography
947
+ as="h2"
948
+ size="h3"
949
+ >
950
+ Invite teammate
951
+ </Typography>
952
+ <Typography size="body">They will receive an email with a link to join the workspace.</Typography>
953
+ <Button
954
+ onPress={() => {
955
+ onSendInvite();
956
+ close();
957
+ }}
958
+ >
959
+ Send invite
960
+ </Button>
961
+ </>
962
+ )}
963
+ </Dialog>
964
+ );
965
+ }
966
+
967
+ /** Controlled, for a dialog opened from elsewhere (a table row, a route). `onOpenChange(false)` fires on Escape, outside press and the close icon. */
968
+ export function ControlledDialogExample({ inviteEmail }: { inviteEmail: string }) {
969
+ const [isOpen, setIsOpen] = useState(false);
970
+
971
+ return (
972
+ <>
973
+ <Button
974
+ variant="outlined"
975
+ onPress={() => setIsOpen(true)}
976
+ >
977
+ Show invite
978
+ </Button>
979
+ <Dialog
980
+ isOpen={isOpen}
981
+ onOpenChange={setIsOpen}
982
+ label="Pending invite"
983
+ className="w-modal"
984
+ >
985
+ <Typography size="body">An invite is waiting for {inviteEmail}.</Typography>
986
+ <Button onPress={() => setIsOpen(false)}>Close</Button>
987
+ </Dialog>
988
+ </>
989
+ );
990
+ }
991
+ ```
992
+
993
+ ### @povio/ui/drawer
994
+
995
+ ```tsx
996
+ import { Button } from "@povio/ui/button";
997
+ import { Drawer } from "@povio/ui/drawer";
998
+ import { Typography } from "@povio/ui/typography";
999
+
1000
+ /** A panel that slides in from the side, for a form or the details of a record. Same shape as `Dialog`: pass `trigger`, or control it with `isOpen` + `onOpenChange`. `label` is required and names the drawer but is not rendered, and the panel has no width, padding or header of its own. Children are nodes or a function `(close) => …`. `className` styles the sliding panel, `contentClassName` the element that holds the children. */
1001
+ export function DrawerExample({ orderNumber, onRefund }: { orderNumber: string; onRefund: () => void }) {
1002
+ return (
1003
+ <Drawer
1004
+ label={`Order ${orderNumber}`}
1005
+ trigger={<Button variant="outlined">View order</Button>}
1006
+ >
1007
+ {(close) => (
1008
+ <div className="flex w-96 flex-col gap-4 p-6">
1009
+ <Typography
1010
+ as="h2"
1011
+ size="h3"
1012
+ >
1013
+ Order {orderNumber}
1014
+ </Typography>
1015
+ <Button
1016
+ color="error"
1017
+ onPress={() => {
1018
+ onRefund();
1019
+ close();
1020
+ }}
1021
+ >
1022
+ Refund order
1023
+ </Button>
1024
+ </div>
1025
+ )}
1026
+ </Drawer>
1027
+ );
1028
+ }
1029
+
1030
+ /** Controlled, with plain children. `onOpenChange(false)` fires on Escape and outside press. */
1031
+ export function ControlledDrawerExample({
1032
+ orderNumber,
1033
+ isOpen,
1034
+ onOpenChange,
1035
+ }: {
1036
+ orderNumber: string;
1037
+ isOpen: boolean;
1038
+ onOpenChange: (isOpen: boolean) => void;
1039
+ }) {
1040
+ return (
1041
+ <Drawer
1042
+ label={`Order ${orderNumber}`}
1043
+ isOpen={isOpen}
1044
+ onOpenChange={onOpenChange}
1045
+ contentClassName="w-96 p-6"
1046
+ >
1047
+ <Typography
1048
+ as="h2"
1049
+ size="h3"
1050
+ >
1051
+ Order {orderNumber}
1052
+ </Typography>
1053
+ </Drawer>
1054
+ );
1055
+ }
1056
+ ```
1057
+
1058
+ ### @povio/ui/dropdown-menu
1059
+
1060
+ ```tsx
1061
+ import { Ellipsis } from "lucide-react";
1062
+ import { DropdownMenu, type DropdownMenuItem } from "@povio/ui/dropdown-menu";
1063
+ import { IconButton } from "@povio/ui/icon-button";
1064
+
1065
+ /**
1066
+ * A menu of actions opened from a button.
1067
+ * Items are data (`label` plus `onAction`), not JSX children; `trigger` must be a pressable element like a button.
1068
+ * `color: "error"` marks a destructive entry; `children` turns an entry into a submenu.
1069
+ */
1070
+ export function DropdownMenuExample({
1071
+ canArchive,
1072
+ onEdit,
1073
+ onArchive,
1074
+ onDelete,
1075
+ onExport,
1076
+ }: {
1077
+ canArchive: boolean;
1078
+ onEdit: () => void;
1079
+ onArchive: () => void;
1080
+ onDelete: () => void;
1081
+ onExport: (format: "csv" | "pdf") => void;
1082
+ }) {
1083
+ const items: DropdownMenuItem[] = [
1084
+ { id: "edit", label: "Edit", onAction: onEdit },
1085
+ { id: "archive", label: "Archive", isDisabled: !canArchive, onAction: onArchive },
1086
+ {
1087
+ id: "export",
1088
+ label: "Export",
1089
+ children: [
1090
+ { id: "export-csv", label: "CSV", onAction: () => onExport("csv") },
1091
+ { id: "export-pdf", label: "PDF", onAction: () => onExport("pdf") },
1092
+ ],
1093
+ },
1094
+ { id: "delete", label: "Delete", color: "error", onAction: onDelete },
1095
+ ];
1096
+ return (
1097
+ <DropdownMenu
1098
+ placement="bottom end"
1099
+ trigger={
1100
+ <IconButton
1101
+ icon={Ellipsis}
1102
+ label="More actions"
1103
+ variant="ghost"
1104
+ color="secondary"
1105
+ size="sm"
1106
+ />
1107
+ }
1108
+ items={items}
1109
+ />
1110
+ );
1111
+ }
1112
+ ```
1113
+
1114
+ ### @povio/ui/file-input
1115
+
1116
+ ```tsx
1117
+ import { FileInput } from "@povio/ui/file-input";
1118
+ import { useForm } from "@povio/ui/tanstack/form";
1119
+ import { z } from "zod";
1120
+
1121
+ const schema = z.object({ attachments: z.array(z.instanceof(File)) });
1122
+
1123
+ /** A file picker whose value is the picked files themselves, for forms that upload on submit. Holds native files and uploads nothing: `File | null`, or `File[]` with `allowsMultiple` (never `FileList`). */
1124
+ export function FileInputExample({ value, onChange }: { value: File | null; onChange: (file: File | null) => void }) {
1125
+ const form = useForm({ defaultValues: { attachments: [] }, zodSchema: schema });
1126
+ return (
1127
+ <>
1128
+ <FileInput
1129
+ label="Contract"
1130
+ acceptedFileTypes={["application/pdf"]}
1131
+ value={value}
1132
+ onChange={onChange}
1133
+ />
1134
+ <FileInput
1135
+ label="Attachments"
1136
+ allowsMultiple
1137
+ field={{ form, name: "attachments" }}
1138
+ />
1139
+ </>
1140
+ );
1141
+ }
1142
+ ```
1143
+
1144
+ ### @povio/ui/file-upload
1145
+
1146
+ ```tsx
1147
+ import { useState } from "react";
1148
+ import { Button } from "@povio/ui/button";
1149
+ import { FileUpload, type UploadedFile } from "@povio/ui/file-upload";
1150
+ import { useForm } from "@povio/ui/tanstack/form";
1151
+ import { z } from "zod";
1152
+
1153
+ // What an upload field holds and the form submits: one record per finished upload.
1154
+ const uploadedFile = z.object({
1155
+ id: z.string(),
1156
+ name: z.string(),
1157
+ size: z.number().optional(),
1158
+ type: z.string().optional(),
1159
+ url: z.string().optional(),
1160
+ });
1161
+ const schema = z.object({ attachments: z.array(uploadedFile).min(1, "Attach at least one file") });
1162
+
1163
+ type UploadConfig = { signal: AbortSignal; onUploadProgress: (event: { loaded: number; total?: number }) => void };
1164
+
1165
+ /**
1166
+ * A drop zone and file list that uploads each file as soon as it is picked.
1167
+ * `onUpload(file, { signal, onProgress })` stores one native `File` and resolves with its `{ id }`. `value`,
1168
+ * `defaultValue`, `onChange` and a bound field all hold `UploadedFile[]` (always an array) with finished uploads only,
1169
+ * and a bound field fails the form's submit while an upload runs. For files that are not uploaded, use `FileInput`.
1170
+ */
1171
+ export function FileUploadExample({
1172
+ savedAvatar,
1173
+ savedAttachments,
1174
+ uploadFile,
1175
+ deleteFile,
1176
+ saveRecord,
1177
+ }: {
1178
+ savedAvatar: UploadedFile | null;
1179
+ savedAttachments: UploadedFile[];
1180
+ uploadFile: (file: File, config: UploadConfig) => Promise<{ id: string; url: string }>;
1181
+ deleteFile: (id: string) => Promise<void>;
1182
+ saveRecord: (values: { attachmentIds: string[] }) => Promise<void>;
1183
+ }) {
1184
+ // Saved files are records with their server ids; `onChange` keeps the state in sync after uploads and removals.
1185
+ // Pass the saved records as `defaultValue` instead to leave the state to the control.
1186
+ const [avatar, setAvatar] = useState<UploadedFile[]>(savedAvatar ? [savedAvatar] : []);
1187
+ const form = useForm({ defaultValues: { attachments: savedAttachments }, zodSchema: schema });
1188
+ return (
1189
+ <>
1190
+ <FileUpload
1191
+ label="Avatar"
1192
+ acceptedFileTypes={["image/png", "image/jpeg"]}
1193
+ value={avatar}
1194
+ onChange={setAvatar}
1195
+ onUpload={async (file, { signal, onProgress }) => {
1196
+ // A rejection fails the upload and shows its message as the field error.
1197
+ const stored = await uploadFile(file, { signal, onUploadProgress: onProgress });
1198
+ return { id: stored.id, url: stored.url };
1199
+ }}
1200
+ // Runs after the file has left the value: for server-side clean-up only.
1201
+ onRemove={(file) => deleteFile(file.id)}
1202
+ />
1203
+ <form
1204
+ className="flex flex-col gap-4"
1205
+ onSubmit={form.handleSubmit((values) =>
1206
+ saveRecord({ attachmentIds: values.attachments.map((attachment) => attachment.id) }),
1207
+ )}
1208
+ >
1209
+ {/* Each finished upload adds its record to the field; the remove action takes it out again. */}
1210
+ <FileUpload
1211
+ label="Attachments"
1212
+ allowsMultiple
1213
+ field={{ form, name: "attachments" }}
1214
+ onUpload={(file, { signal, onProgress }) => uploadFile(file, { signal, onUploadProgress: onProgress })}
1215
+ />
1216
+ <Button type="submit">Save</Button>
1217
+ </form>
1218
+ {/* Render-function children replace the browse button and the file list; the zone then accepts drops only. */}
1219
+ <FileUpload
1220
+ allowsMultiple
1221
+ onUpload={(file, { signal, onProgress }) => uploadFile(file, { signal, onUploadProgress: onProgress })}
1222
+ >
1223
+ {({ files, onRemove }) => (
1224
+ <ul>
1225
+ {files.map((file) => (
1226
+ <li key={file.key}>
1227
+ {file.name} {file.status === "uploading" ? `${file.progress}%` : null}
1228
+ <Button onPress={() => onRemove(file)}>Remove</Button>
1229
+ </li>
1230
+ ))}
1231
+ </ul>
1232
+ )}
1233
+ </FileUpload>
1234
+ </>
1235
+ );
1236
+ }
1237
+ ```
1238
+
1239
+ ### @povio/ui/form-field
1240
+
1241
+ ```tsx
1242
+ import { useId } from "react";
1243
+ import { Button } from "@povio/ui/button";
1244
+ import { FormField } from "@povio/ui/form-field";
1245
+ import { BoundField, useForm } from "@povio/ui/tanstack/form";
1246
+ import { z } from "zod";
1247
+
1248
+ /** The label, helper text and error around a custom control. Only for custom controls (library inputs already render it); the label is linked by you through `labelProps`. */
1249
+ export function FormFieldExample({
1250
+ value,
1251
+ onChange,
1252
+ error,
1253
+ }: {
1254
+ value: string;
1255
+ onChange: (value: string) => void;
1256
+ error?: string;
1257
+ }) {
1258
+ const id = useId();
1259
+ return (
1260
+ <FormField
1261
+ label="Brand colour"
1262
+ helperText="Used for buttons and links"
1263
+ isRequired
1264
+ error={error}
1265
+ labelProps={{ htmlFor: id }}
1266
+ >
1267
+ <input
1268
+ id={id}
1269
+ type="color"
1270
+ value={value}
1271
+ aria-invalid={!!error}
1272
+ onChange={(event) => onChange(event.target.value)}
1273
+ />
1274
+ </FormField>
1275
+ );
1276
+ }
1277
+
1278
+ const themeSchema = z.object({ brandColor: z.string().min(1, "Pick a colour") });
1279
+
1280
+ /** The same control bound to a form: `BoundField` reveals the schema error, marks the field touched and notifies autosave like the library's inputs. Don't build this from `form.Field`: its errors show before the user has done anything. */
1281
+ export function BoundFormFieldExample({ save }: { save: (values: z.output<typeof themeSchema>) => Promise<void> }) {
1282
+ const id = useId();
1283
+ const form = useForm({ defaultValues: { brandColor: "" }, zodSchema: themeSchema });
1284
+ return (
1285
+ <form onSubmit={form.handleSubmit(save)}>
1286
+ <BoundField field={{ form, name: "brandColor" }}>
1287
+ {({ value, onChange, onBlur, ref, error }) => (
1288
+ <FormField
1289
+ label="Brand colour"
1290
+ isRequired
1291
+ error={error}
1292
+ labelProps={{ htmlFor: id }}
1293
+ >
1294
+ <input
1295
+ id={id}
1296
+ ref={ref}
1297
+ type="color"
1298
+ value={value}
1299
+ aria-invalid={!!error}
1300
+ onChange={(event) => onChange(event.target.value)}
1301
+ onBlur={onBlur}
1302
+ />
1303
+ </FormField>
1304
+ )}
1305
+ </BoundField>
1306
+ <Button type="submit">Save</Button>
1307
+ </form>
1308
+ );
1309
+ }
1310
+ ```
1311
+
1312
+ ### @povio/ui/form-layout
1313
+
1314
+ ```tsx
1315
+ import { Button } from "@povio/ui/button";
1316
+ import { Checkbox } from "@povio/ui/checkbox";
1317
+ import { FormLayout, FormLayoutActions, FormLayoutRow, FormLayoutSection } from "@povio/ui/form-layout";
1318
+ import { Input } from "@povio/ui/input";
1319
+ import { useForm } from "@povio/ui/tanstack/form";
1320
+ import { z } from "zod";
1321
+
1322
+ const schema = z.object({ name: z.string().min(1), email: z.email(), newsletter: z.boolean() });
1323
+
1324
+ /** Lays out the fields and actions of a form. `FormLayout` goes inside `<form>` and sets `labelPosition` for every field in it; never lay fields out by hand. */
1325
+ export function FormLayoutExample({ onSubmit }: { onSubmit: (values: z.output<typeof schema>) => void }) {
1326
+ const form = useForm({ defaultValues: { name: "", email: "", newsletter: false }, zodSchema: schema });
1327
+ return (
1328
+ <form onSubmit={form.handleSubmit(onSubmit)}>
1329
+ <FormLayout labelPosition="side">
1330
+ <FormLayoutSection title="Contact" />
1331
+ <Input
1332
+ label="Name"
1333
+ field={{ form, name: "name" }}
1334
+ />
1335
+ <Input
1336
+ label="Email"
1337
+ type="email"
1338
+ field={{ form, name: "email" }}
1339
+ />
1340
+ <FormLayoutRow
1341
+ label="Updates"
1342
+ helperText="At most one email a month"
1343
+ >
1344
+ <Checkbox field={{ form, name: "newsletter" }}>Subscribe to the newsletter</Checkbox>
1345
+ </FormLayoutRow>
1346
+ <FormLayoutActions>
1347
+ <Button type="submit">Save</Button>
1348
+ </FormLayoutActions>
1349
+ </FormLayout>
1350
+ </form>
1351
+ );
1352
+ }
1353
+ ```
1354
+
1355
+ ### @povio/ui/icon-button
1356
+
1357
+ ```tsx
1358
+ import { Pencil, Trash2 } from "lucide-react";
1359
+ import { IconButton } from "@povio/ui/icon-button";
1360
+
1361
+ /** An action shown as an icon, with a tooltip. `label` is the accessible name and the tooltip text (a name is required); pass the icon through `icon`, never as children. */
1362
+ export function IconButtonExample({
1363
+ isDeleting,
1364
+ onEdit,
1365
+ onDelete,
1366
+ }: {
1367
+ isDeleting: boolean;
1368
+ onEdit: () => void;
1369
+ onDelete: () => void;
1370
+ }) {
1371
+ return (
1372
+ <div className="flex items-center gap-1">
1373
+ <IconButton
1374
+ label="Edit user"
1375
+ icon={Pencil}
1376
+ variant="ghost"
1377
+ color="secondary"
1378
+ size="sm"
1379
+ onPress={onEdit}
1380
+ />
1381
+ <IconButton
1382
+ label="Delete user"
1383
+ icon={Trash2}
1384
+ variant="ghost"
1385
+ color="error"
1386
+ size="sm"
1387
+ isLoading={isDeleting}
1388
+ onPress={onDelete}
1389
+ />
1390
+ </div>
1391
+ );
1392
+ }
1393
+ ```
1394
+
1395
+ ### @povio/ui/icon-slot
1396
+
1397
+ ```tsx
1398
+ import { CircleAlert, CircleCheck, UserPlus } from "lucide-react";
1399
+ import { Button } from "@povio/ui/button";
1400
+ import { IconSlot } from "@povio/ui/icon-slot";
1401
+
1402
+ /** Renders an icon in the library's 16px icon box. Pass the icon component through `icon` (no children); `className` styles the 16px slot, `iconClassName` the SVG, and a configured slot can be a Button's `icon`. */
1403
+ export function IconSlotExample({ isVerified, onInvite }: { isVerified: boolean; onInvite: () => void }) {
1404
+ return (
1405
+ <div className="flex items-center gap-3">
1406
+ <span className="inline-flex items-center gap-1.5 text-sm">
1407
+ <IconSlot
1408
+ icon={isVerified ? CircleCheck : CircleAlert}
1409
+ className={isVerified ? "text-success" : "text-warning"}
1410
+ aria-hidden
1411
+ />
1412
+ {isVerified ? "Verified" : "Verification pending"}
1413
+ </span>
1414
+ <Button
1415
+ size="sm"
1416
+ variant="outlined"
1417
+ icon={
1418
+ <IconSlot
1419
+ icon={UserPlus}
1420
+ scale={0.75}
1421
+ />
1422
+ }
1423
+ onPress={onInvite}
1424
+ >
1425
+ Invite
1426
+ </Button>
1427
+ </div>
1428
+ );
1429
+ }
1430
+ ```
1431
+
1432
+ ### @povio/ui/input
1433
+
1434
+ ```tsx
1435
+ import { Send } from "lucide-react";
1436
+ import { Input } from "@povio/ui/input";
1437
+ import { useForm } from "@povio/ui/tanstack/form";
1438
+ import { z } from "zod";
1439
+
1440
+ const schema = z.object({ email: z.email() });
1441
+
1442
+ /** A single-line text field. `onChange` receives the string, not an event; with `field` never also pass `value`, `defaultValue` or `onChange`. `action` is one icon button at the end of the field: `{ icon, label, onPress }`. */
1443
+ export function InputExample({
1444
+ value,
1445
+ onChange,
1446
+ onSend,
1447
+ }: {
1448
+ value: string;
1449
+ onChange: (value: string) => void;
1450
+ onSend: () => void;
1451
+ }) {
1452
+ const form = useForm({ defaultValues: { email: "" }, zodSchema: schema });
1453
+ return (
1454
+ <>
1455
+ <Input
1456
+ label="Name"
1457
+ value={value}
1458
+ onChange={onChange}
1459
+ isRequired
1460
+ />
1461
+ <Input
1462
+ label="Email"
1463
+ type="email"
1464
+ placeholder="ada@example.com"
1465
+ field={{ form, name: "email" }}
1466
+ />
1467
+ <Input
1468
+ label="Message"
1469
+ action={{ icon: Send, label: "Send message", onPress: onSend }}
1470
+ />
1471
+ </>
1472
+ );
1473
+ }
1474
+ ```
1475
+
1476
+ ### @povio/ui/link
1477
+
1478
+ ```tsx
1479
+ import { Link } from "@povio/ui/link";
1480
+
1481
+ /** An inline text link to another page or site. Navigate with `href` (a router link registered through `LinkContext` receives it as `to`) and handle presses with `onPress`; `variant` is `default` (underlined), `subtle` or `plain`. */
1482
+ export function LinkExample({ invoiceId, onOpenInvoice }: { invoiceId: string; onOpenInvoice: () => void }) {
1483
+ return (
1484
+ <nav className="flex items-center gap-4 text-sm">
1485
+ <Link
1486
+ href={`/invoices/${invoiceId}`}
1487
+ onPress={onOpenInvoice}
1488
+ >
1489
+ View invoice
1490
+ </Link>
1491
+ <Link
1492
+ href="https://docs.example.com/billing"
1493
+ target="_blank"
1494
+ rel="noreferrer"
1495
+ variant="subtle"
1496
+ >
1497
+ Billing docs
1498
+ </Link>
1499
+ </nav>
1500
+ );
1501
+ }
1502
+ ```
1503
+
1504
+ ### @povio/ui/link-context
1505
+
1506
+ ```tsx
1507
+ import { createLink } from "@tanstack/react-router";
1508
+ import type { ReactNode } from "react";
1509
+ import { Link as AriaLink } from "react-aria-components";
1510
+ import { LinkContext } from "@povio/ui/link-context";
1511
+
1512
+ // Module scope: a new component on every render would remount every link.
1513
+ const RouterLink = createLink(AriaLink);
1514
+
1515
+ /** Supplies the router link that `Link`, `SidebarItem`, breadcrumbs and buttons with `link` render; mount it once at the app root, around the router. Pass TanStack Router's `createLink(Link)` over React Aria's `Link` as is, without a cast: those components set `to` from `href`, so plain `href` strings navigate through the router. */
1516
+ export function LinkContextExample({ children }: { children: ReactNode }) {
1517
+ return <LinkContext.LinkContextProvider LinkComponent={RouterLink}>{children}</LinkContext.LinkContextProvider>;
1518
+ }
1519
+ ```
1520
+
1521
+ ### @povio/ui/number-field
1522
+
1523
+ ```tsx
1524
+ import { NumberField } from "@povio/ui/number-field";
1525
+ import { useForm } from "@povio/ui/tanstack/form";
1526
+ import { z } from "zod";
1527
+
1528
+ const schema = z.object({ price: z.number().min(0).nullable() });
1529
+
1530
+ /** A field for one number. Value is `number | null` (`null` when empty), never a string; `onChange` fires with the parsed number while typing. */
1531
+ export function NumberFieldExample({
1532
+ value,
1533
+ onChange,
1534
+ }: {
1535
+ value: number | null;
1536
+ onChange: (value: number | null) => void;
1537
+ }) {
1538
+ const form = useForm({ defaultValues: { price: null }, zodSchema: schema });
1539
+ return (
1540
+ <>
1541
+ <NumberField
1542
+ label="Quantity"
1543
+ minValue={0}
1544
+ step={1}
1545
+ value={value}
1546
+ onChange={onChange}
1547
+ />
1548
+ <NumberField
1549
+ label="Price"
1550
+ formatOptions={{ style: "currency", currency: "EUR" }}
1551
+ field={{ form, name: "price" }}
1552
+ />
1553
+ </>
1554
+ );
1555
+ }
1556
+ ```
1557
+
1558
+ ### @povio/ui/number-range-input
1559
+
1560
+ ```tsx
1561
+ import { NumberRangeInput, type NumberRangeValue } from "@povio/ui/number-range-input";
1562
+ import { useForm } from "@povio/ui/tanstack/form";
1563
+ import { z } from "zod";
1564
+
1565
+ const schema = z.object({ budget: z.object({ start: z.number().nullable(), end: z.number().nullable() }) });
1566
+
1567
+ /**
1568
+ * Two number fields for a from-to range, such as a price filter.
1569
+ * Value is one `{ start, end }` object of `number | null` (not a tuple); a cleared side is `null`, the object stays.
1570
+ * `defaultValue` takes the same shape when the input should own its range.
1571
+ */
1572
+ export function NumberRangeInputExample({
1573
+ value,
1574
+ onChange,
1575
+ }: {
1576
+ value: NumberRangeValue;
1577
+ onChange: (value: NumberRangeValue) => void;
1578
+ }) {
1579
+ const form = useForm({ defaultValues: { budget: { start: null, end: null } }, zodSchema: schema });
1580
+ return (
1581
+ <>
1582
+ <NumberRangeInput
1583
+ label="Age"
1584
+ startPlaceholder="From"
1585
+ endPlaceholder="To"
1586
+ value={value}
1587
+ onChange={onChange}
1588
+ />
1589
+ <NumberRangeInput
1590
+ label="Budget"
1591
+ field={{ form, name: "budget" }}
1592
+ />
1593
+ </>
1594
+ );
1595
+ }
1596
+ ```
1597
+
1598
+ ### @povio/ui/page-header
1599
+
1600
+ ```tsx
1601
+ import { Plus } from "lucide-react";
1602
+ import { Badge } from "@povio/ui/badge";
1603
+ import { Button } from "@povio/ui/button";
1604
+ import { PageHeader, PageHeaderDetails } from "@povio/ui/page-header";
1605
+
1606
+ /** The top of a page: title, breadcrumbs or a back link, status and actions. Pass `breadcrumbs` or `backLink`, never both; the page's one main button goes in `primaryAction`, not `actions`. */
1607
+ export function PageHeaderExample({
1608
+ project,
1609
+ onAddTask,
1610
+ }: {
1611
+ project: { name: string; owner: string; isAtRisk: boolean };
1612
+ onAddTask: () => void;
1613
+ }) {
1614
+ return (
1615
+ <PageHeader
1616
+ breadcrumbs={[
1617
+ { id: "projects", label: "Projects", link: { href: "/projects" } },
1618
+ { id: "current", label: project.name },
1619
+ ]}
1620
+ title={project.name}
1621
+ status={project.isAtRisk && <Badge color="error">At risk</Badge>}
1622
+ primaryAction={
1623
+ <Button
1624
+ icon={Plus}
1625
+ size="sm"
1626
+ width="hug"
1627
+ onPress={onAddTask}
1628
+ >
1629
+ New task
1630
+ </Button>
1631
+ }
1632
+ >
1633
+ <PageHeaderDetails items={[{ label: "Owner", value: project.owner }]} />
1634
+ </PageHeader>
1635
+ );
1636
+ }
1637
+ ```
1638
+
1639
+ ### @povio/ui/password-input
1640
+
1641
+ ```tsx
1642
+ import { PasswordInput } from "@povio/ui/password-input";
1643
+ import { useForm } from "@povio/ui/tanstack/form";
1644
+ import { z } from "zod";
1645
+
1646
+ const schema = z.object({ password: z.string().min(8) });
1647
+
1648
+ /** A password field with a show and hide toggle. The reveal toggle is built in: do not pass `type`, `action`, `trailingIcon` or `unit`; the value is a plain string. */
1649
+ export function PasswordInputExample({ value, onChange }: { value: string; onChange: (value: string) => void }) {
1650
+ const form = useForm({ defaultValues: { password: "" }, zodSchema: schema });
1651
+ return (
1652
+ <>
1653
+ <PasswordInput
1654
+ label="Current password"
1655
+ autoComplete="current-password"
1656
+ value={value}
1657
+ onChange={onChange}
1658
+ />
1659
+ <PasswordInput
1660
+ label="New password"
1661
+ autoComplete="new-password"
1662
+ field={{ form, name: "password" }}
1663
+ />
1664
+ </>
1665
+ );
1666
+ }
1667
+ ```
1668
+
1669
+ ### @povio/ui/popover
1670
+
1671
+ ```tsx
1672
+ import { useState } from "react";
1673
+ import { Button } from "@povio/ui/button";
1674
+ import { Popover } from "@povio/ui/popover";
1675
+ import { Typography } from "@povio/ui/typography";
1676
+
1677
+ /** Floating content anchored to a button, shown as a bottom sheet on small screens. Same shape as `Dialog`, except `trigger` is required (it anchors the popover) and goes in the prop, not in children. The popover owns its state unless you pass `isOpen` + `onOpenChange`. `label` is required: it names the popover and, below `md` where the content renders in a bottom sheet, is that sheet's header. Children are nodes or a function `(close) => …`. `className` styles the popover and, below `md`, the sheet, so widths take `md:`. */
1678
+ export function PopoverExample({ shareUrl, onCopyLink }: { shareUrl: string; onCopyLink: () => void }) {
1679
+ return (
1680
+ <Popover
1681
+ trigger={<Button variant="outlined">Share</Button>}
1682
+ label="Share report"
1683
+ className="md:w-80"
1684
+ >
1685
+ {(close) => (
1686
+ <div className="flex flex-col gap-3">
1687
+ <Typography
1688
+ size="small"
1689
+ className="break-all text-muted-foreground"
1690
+ >
1691
+ {shareUrl}
1692
+ </Typography>
1693
+ <Button
1694
+ size="sm"
1695
+ onPress={() => {
1696
+ onCopyLink();
1697
+ close();
1698
+ }}
1699
+ >
1700
+ Copy link
1701
+ </Button>
1702
+ </div>
1703
+ )}
1704
+ </Popover>
1705
+ );
1706
+ }
1707
+
1708
+ /** Controlled, for a popover that other code opens or closes. `placement` positions it, as on `Tooltip` and `DropdownMenu`. */
1709
+ export function ControlledPopoverExample({ activeFilterCount }: { activeFilterCount: number }) {
1710
+ const [isOpen, setIsOpen] = useState(false);
1711
+
1712
+ return (
1713
+ <Popover
1714
+ trigger={<Button variant="outlined">Filters</Button>}
1715
+ isOpen={isOpen}
1716
+ onOpenChange={setIsOpen}
1717
+ label="Filters"
1718
+ placement="bottom end"
1719
+ >
1720
+ <Typography size="small">{activeFilterCount} filters are active.</Typography>
1721
+ </Popover>
1722
+ );
1723
+ }
1724
+ ```
1725
+
1726
+ ### @povio/ui/progress
1727
+
1728
+ ```tsx
1729
+ import { Progress } from "@povio/ui/progress";
1730
+
1731
+ /** A progressbar that shows how far a task has got. `value` is on a 0–100 scale (not 0–1), as on React Aria's ProgressBar; it is clamped to that range and printed as given, so round it. `label` is shown above the bar and names it for screen readers (`hideLabel` keeps it as the name only, `aria-labelledby` points at a caption elsewhere); `valuePosition` places the percentage: `trailing` (default), `leading` or `none`. */
1732
+ export function ProgressExample({
1733
+ fileName,
1734
+ uploadedBytes,
1735
+ totalBytes,
1736
+ }: {
1737
+ fileName: string;
1738
+ uploadedBytes: number;
1739
+ totalBytes: number;
1740
+ }) {
1741
+ const percent = totalBytes > 0 ? Math.round((uploadedBytes / totalBytes) * 100) : 0;
1742
+
1743
+ return (
1744
+ <Progress
1745
+ label={`Uploading ${fileName}`}
1746
+ value={percent}
1747
+ />
1748
+ );
1749
+ }
1750
+ ```
1751
+
1752
+ ### @povio/ui/radio-group
1753
+
1754
+ ```tsx
1755
+ import { RadioGroup } from "@povio/ui/radio-group";
1756
+ import { useForm } from "@povio/ui/tanstack/form";
1757
+ import { z } from "zod";
1758
+
1759
+ const plans = [
1760
+ { id: "free", label: "Free" },
1761
+ { id: "pro", label: "Pro" },
1762
+ { id: "team", label: "Team (coming soon)", isDisabled: true },
1763
+ ];
1764
+
1765
+ const schema = z.object({ plan: z.enum(["free", "pro", "team"]) });
1766
+
1767
+ /** Picks one option from a short list, with every option visible. Takes `items` of `{ id, label, isDisabled? }` like `Select` (not `options`/`value`, not `<Radio>` children); the value is the chosen item's `id`. */
1768
+ export function RadioGroupExample({ value, onChange }: { value: string | null; onChange: (value: string) => void }) {
1769
+ const form = useForm({ defaultValues: { plan: "free" }, zodSchema: schema });
1770
+ return (
1771
+ <>
1772
+ <RadioGroup
1773
+ label="Billing"
1774
+ items={plans}
1775
+ value={value}
1776
+ onChange={onChange}
1777
+ />
1778
+ <RadioGroup
1779
+ label="Plan"
1780
+ items={plans}
1781
+ orientation="horizontal"
1782
+ field={{ form, name: "plan" }}
1783
+ />
1784
+ </>
1785
+ );
1786
+ }
1787
+ ```
1788
+
1789
+ ### @povio/ui/rich-text-editor
1790
+
1791
+ ```tsx
1792
+ // The editor needs its stylesheet: add `@import "@povio/ui/rich-text-editor/styles";` to the app's global Tailwind
1793
+ // stylesheet, after the theme. It uses `@apply` with the theme's tokens, so it cannot be imported from JS/TS.
1794
+ import { RichTextEditor, type RichTextEditorValue } from "@povio/ui/rich-text-editor";
1795
+ import { useForm } from "@povio/ui/tanstack/form";
1796
+ import { z } from "zod";
1797
+
1798
+ const schema = z.object({
1799
+ body: z.object({ html: z.string().nullish(), json: z.record(z.string(), z.unknown()).nullish() }).nullable(),
1800
+ });
1801
+
1802
+ /** A formatted text editor with a toolbar. Value is `{ html, json } | null`, not an HTML string: content is loaded from `json` (the TipTap document) and `onChange` emits both, so `html` alone never populates the editor. */
1803
+ export function RichTextEditorExample({
1804
+ value,
1805
+ onChange,
1806
+ }: {
1807
+ value: RichTextEditorValue | null;
1808
+ onChange: (value: RichTextEditorValue | null) => void;
1809
+ }) {
1810
+ const form = useForm({ defaultValues: { body: null }, zodSchema: schema });
1811
+ return (
1812
+ <>
1813
+ <RichTextEditor
1814
+ label="Description"
1815
+ placeholder="Describe the issue"
1816
+ value={value}
1817
+ onChange={onChange}
1818
+ />
1819
+ <RichTextEditor
1820
+ label="Body"
1821
+ field={{ form, name: "body" }}
1822
+ />
1823
+ </>
1824
+ );
1825
+ }
1826
+ ```
1827
+
1828
+ ### @povio/ui/select
1829
+
1830
+ ```tsx
1831
+ import { Select } from "@povio/ui/select";
1832
+ import { useForm } from "@povio/ui/tanstack/form";
1833
+ import { z } from "zod";
1834
+
1835
+ const countries = [
1836
+ { id: "si", label: "Slovenia" },
1837
+ { id: "at", label: "Austria" },
1838
+ { id: "it", label: "Italy" },
1839
+ ];
1840
+
1841
+ // An empty select holds `null`. `error` is the "required" message; without it the user sees zod's
1842
+ // "Invalid input: expected string, received null".
1843
+ const schema = z.object({ countryId: z.string({ error: "Choose a country" }), visitedIds: z.array(z.string()) });
1844
+
1845
+ /** One page of a TanStack infinite query (or any pager), with its fields named as `Select` names them. */
1846
+ interface OwnerPages {
1847
+ items: { id: string; label: string }[];
1848
+ isLoading: boolean;
1849
+ hasNextPage: boolean;
1850
+ fetchNextPage: () => void;
1851
+ isFetchingNextPage: boolean;
1852
+ }
1853
+
1854
+ /** A dropdown for picking one item, or several, from a list. Stores item `id`s, never labels or item objects: `id | null`, or `id[]` with `selectionMode="multiple"`; `isSearchable` adds type-to-filter without changing the value. As on the other text-like inputs, `className` styles the field root (label, field and error) and `inputClassName` the bordered box. */
1855
+ export function SelectExample({
1856
+ value,
1857
+ onChange,
1858
+ owners,
1859
+ ownerId,
1860
+ savedOwner,
1861
+ onOwnerChange,
1862
+ }: {
1863
+ value: string | null;
1864
+ onChange: (value: string | null) => void;
1865
+ owners: OwnerPages;
1866
+ ownerId: string | null;
1867
+ /** The saved record behind `ownerId`, which may not be on a loaded page yet. */
1868
+ savedOwner: { id: string; name: string } | null;
1869
+ onOwnerChange: (ownerId: string | null) => void;
1870
+ }) {
1871
+ const form = useForm({ defaultValues: { countryId: null, visitedIds: [] }, zodSchema: schema });
1872
+ return (
1873
+ <>
1874
+ <Select
1875
+ label="Country"
1876
+ items={countries}
1877
+ value={value}
1878
+ onChange={onChange}
1879
+ isClearable
1880
+ />
1881
+ {/* Uncontrolled: the select keeps its own value; `onChange` still reports every change. */}
1882
+ <Select
1883
+ label="Shipping from"
1884
+ items={countries}
1885
+ defaultValue="si"
1886
+ />
1887
+ <Select
1888
+ label="Residence"
1889
+ items={countries}
1890
+ isSearchable
1891
+ isRequired
1892
+ field={{ form, name: "countryId" }}
1893
+ />
1894
+ <Select
1895
+ label="Visited"
1896
+ items={countries}
1897
+ selectionMode="multiple"
1898
+ field={{ form, name: "visitedIds" }}
1899
+ />
1900
+ {/* Pages you load yourself; `initialSelection` supplies the label while the saved ID is not loaded. */}
1901
+ <Select
1902
+ label="Owner"
1903
+ items={owners.items}
1904
+ isLoading={owners.isLoading}
1905
+ hasNextPage={owners.hasNextPage}
1906
+ fetchNextPage={owners.fetchNextPage}
1907
+ isFetchingNextPage={owners.isFetchingNextPage}
1908
+ initialSelection={savedOwner}
1909
+ value={ownerId}
1910
+ onChange={onOwnerChange}
1911
+ />
1912
+ </>
1913
+ );
1914
+ }
1915
+ ```
1916
+
1917
+ ### @povio/ui/sidebar
1918
+
1919
+ ```tsx
1920
+ import { FileText, LayoutDashboard, Users } from "lucide-react";
1921
+ import type { ReactNode } from "react";
1922
+ import {
1923
+ Sidebar,
1924
+ SidebarContent,
1925
+ SidebarGroup,
1926
+ SidebarItem,
1927
+ SidebarLayout,
1928
+ type SidebarWorkspaceOption,
1929
+ SidebarWorkspaces,
1930
+ } from "@povio/ui/sidebar";
1931
+
1932
+ const pages = [
1933
+ { href: "/dashboard", label: "Dashboard", icon: LayoutDashboard },
1934
+ { href: "/invoices", label: "Invoices", icon: FileText },
1935
+ { href: "/customers", label: "Customers", icon: Users },
1936
+ ];
1937
+
1938
+ /** The app's side navigation and the page layout around it. `SidebarLayout` takes the `Sidebar` as `navigation` and the page as children; you set `isActive` on each item. */
1939
+ export function SidebarExample({ currentPath, children }: { currentPath: string; children: ReactNode }) {
1940
+ return (
1941
+ <SidebarLayout
1942
+ navigation={
1943
+ <Sidebar aria-label="Main">
1944
+ <SidebarContent>
1945
+ <SidebarGroup label="Workspace">
1946
+ {pages.map((page) => (
1947
+ <SidebarItem
1948
+ key={page.href}
1949
+ href={page.href}
1950
+ icon={page.icon}
1951
+ label={page.label}
1952
+ isActive={currentPath.startsWith(page.href)}
1953
+ />
1954
+ ))}
1955
+ </SidebarGroup>
1956
+ </SidebarContent>
1957
+ </Sidebar>
1958
+ }
1959
+ >
1960
+ <main className="min-w-0 flex-1">{children}</main>
1961
+ </SidebarLayout>
1962
+ );
1963
+ }
1964
+
1965
+ type WorkspaceId = "acme" | "globex";
1966
+
1967
+ const workspaces: SidebarWorkspaceOption<WorkspaceId>[] = [
1968
+ { id: "acme", label: "Acme" },
1969
+ { id: "globex", label: "Globex" },
1970
+ ];
1971
+
1972
+ /** With a workspace rail. `SidebarWorkspaces` sits next to the `Sidebar` in `navigation`, never inside it; its `items` take `id` and `label`, and `onChange` receives the picked `id`. */
1973
+ export function SidebarWithWorkspacesExample({
1974
+ currentPath,
1975
+ workspaceId,
1976
+ onWorkspaceChange,
1977
+ children,
1978
+ }: {
1979
+ currentPath: string;
1980
+ workspaceId: WorkspaceId | null;
1981
+ onWorkspaceChange: (workspaceId: WorkspaceId) => void;
1982
+ children: ReactNode;
1983
+ }) {
1984
+ return (
1985
+ <SidebarLayout
1986
+ navigation={
1987
+ <>
1988
+ <SidebarWorkspaces
1989
+ items={workspaces}
1990
+ value={workspaceId}
1991
+ onChange={onWorkspaceChange}
1992
+ />
1993
+ <Sidebar aria-label="Main">
1994
+ <SidebarContent>
1995
+ <SidebarGroup>
1996
+ {pages.map((page) => (
1997
+ <SidebarItem
1998
+ key={page.href}
1999
+ href={page.href}
2000
+ icon={page.icon}
2001
+ label={page.label}
2002
+ isActive={currentPath.startsWith(page.href)}
2003
+ />
2004
+ ))}
2005
+ </SidebarGroup>
2006
+ </SidebarContent>
2007
+ </Sidebar>
2008
+ </>
2009
+ }
2010
+ >
2011
+ <main className="min-w-0 flex-1">{children}</main>
2012
+ </SidebarLayout>
2013
+ );
2014
+ }
2015
+ ```
2016
+
2017
+ ### @povio/ui/slider
2018
+
2019
+ ```tsx
2020
+ import { Slider } from "@povio/ui/slider";
2021
+ import { useForm } from "@povio/ui/tanstack/form";
2022
+ import { z } from "zod";
2023
+
2024
+ const schema = z.object({ priceRange: z.object({ start: z.number(), end: z.number() }) });
2025
+
2026
+ /** Picks a number, or a range, by dragging. Value is a `number`; add `isRange` for two thumbs and the value becomes `{ start, end }`. */
2027
+ export function SliderExample({ value, onChange }: { value: number; onChange: (value: number) => void }) {
2028
+ const form = useForm({ defaultValues: { priceRange: { start: 20, end: 80 } }, zodSchema: schema });
2029
+ return (
2030
+ <>
2031
+ <Slider
2032
+ label="Volume"
2033
+ unit="%"
2034
+ minValue={0}
2035
+ maxValue={100}
2036
+ value={value}
2037
+ onChange={onChange}
2038
+ />
2039
+ <Slider
2040
+ label="Price"
2041
+ isRange
2042
+ minValue={0}
2043
+ maxValue={200}
2044
+ step={10}
2045
+ field={{ form, name: "priceRange" }}
2046
+ />
2047
+ </>
2048
+ );
2049
+ }
2050
+ ```
2051
+
2052
+ ### @povio/ui/spinner
2053
+
2054
+ ```tsx
2055
+ import type { ReactNode } from "react";
2056
+ import { Spinner } from "@povio/ui/spinner";
2057
+
2058
+ /** An animated indicator for content that is loading. Sizes are the default (16px) and `size="lg"` (32px); colour follows `currentColor`, and `className` styles the whole spinner (a `size-*` class sizes the icon too). Buttons already have `isLoading`, so do not nest a Spinner in them. */
2059
+ export function SpinnerExample({ isLoading, children }: { isLoading: boolean; children: ReactNode }) {
2060
+ if (isLoading) {
2061
+ return (
2062
+ <div
2063
+ role="status"
2064
+ aria-label="Loading"
2065
+ className="flex justify-center p-8 text-muted-foreground"
2066
+ >
2067
+ <Spinner size="lg" />
2068
+ </div>
2069
+ );
2070
+ }
2071
+
2072
+ return children;
2073
+ }
2074
+ ```
2075
+
2076
+ ### @povio/ui/split-button
2077
+
2078
+ ```tsx
2079
+ import { SplitButton } from "@povio/ui/split-button";
2080
+
2081
+ /** A main action with a menu of related actions beside it. `label` is the main action's text and `labelRight` names the chevron menu button; menu entries go in `items` (`label` + `onAction`), not children. */
2082
+ export function SplitButtonExample({
2083
+ isSaving,
2084
+ onSave,
2085
+ onSaveAndClose,
2086
+ onSaveAsTemplate,
2087
+ }: {
2088
+ isSaving: boolean;
2089
+ onSave: () => void;
2090
+ onSaveAndClose: () => void;
2091
+ onSaveAsTemplate: () => void;
2092
+ }) {
2093
+ return (
2094
+ <SplitButton
2095
+ label="Save"
2096
+ labelRight="More save options"
2097
+ isLoading={isSaving}
2098
+ onPress={onSave}
2099
+ items={[
2100
+ { label: "Save and close", onAction: onSaveAndClose },
2101
+ { label: "Save as template", onAction: onSaveAsTemplate },
2102
+ ]}
2103
+ />
2104
+ );
2105
+ }
2106
+ ```
2107
+
2108
+ ### @povio/ui/stepper
2109
+
2110
+ ```tsx
2111
+ import { type StepItem, Stepper } from "@povio/ui/stepper";
2112
+
2113
+ const steps: StepItem[] = [
2114
+ { id: "account", label: "Account", description: "Email and password" },
2115
+ { id: "company", label: "Company", description: "Billing details" },
2116
+ { id: "review", label: "Review", description: "Confirm and finish" },
2117
+ ];
2118
+
2119
+ /** Shows the steps of a multi-step flow and which one is current. Steps are `items: { id, label, description? }`. `currentStep` is a 0-based index, not an `id`; `onStepPress` fires only for completed steps. */
2120
+ export function StepperExample({
2121
+ currentStep,
2122
+ onStepChange,
2123
+ }: {
2124
+ currentStep: number;
2125
+ onStepChange: (stepIndex: number) => void;
2126
+ }) {
2127
+ return (
2128
+ <Stepper
2129
+ items={steps}
2130
+ currentStep={currentStep}
2131
+ onStepPress={onStepChange}
2132
+ />
2133
+ );
2134
+ }
2135
+ ```
2136
+
2137
+ ### @povio/ui/switch
2138
+
2139
+ ```tsx
2140
+ import { Switch } from "@povio/ui/switch";
2141
+ import { useForm } from "@povio/ui/tanstack/form";
2142
+ import { z } from "zod";
2143
+
2144
+ const schema = z.object({ isPublic: z.boolean() });
2145
+
2146
+ /** An on and off toggle for a setting. Boolean control: `isSelected` + `onChange(isSelected)`, not `checked`/`value`; the label is `children`, not `label`. */
2147
+ export function SwitchExample({
2148
+ isSelected,
2149
+ onChange,
2150
+ }: {
2151
+ isSelected: boolean;
2152
+ onChange: (isSelected: boolean) => void;
2153
+ }) {
2154
+ const form = useForm({ defaultValues: { isPublic: false }, zodSchema: schema });
2155
+ return (
2156
+ <>
2157
+ <Switch
2158
+ isSelected={isSelected}
2159
+ onChange={onChange}
2160
+ >
2161
+ Dark mode
2162
+ </Switch>
2163
+ <Switch field={{ form, name: "isPublic" }}>Public profile</Switch>
2164
+ </>
2165
+ );
2166
+ }
2167
+ ```
2168
+
2169
+ ### @povio/ui/tabs-filters
2170
+
2171
+ ```tsx
2172
+ import { Select } from "@povio/ui/select";
2173
+ import { type ListTab, ListTabs, TabsFilters } from "@povio/ui/tabs-filters";
2174
+
2175
+ const tabs: ListTab[] = [
2176
+ { id: "all", label: "All", link: { href: "/invoices" } },
2177
+ { id: "open", label: "Open", link: { href: "/invoices/open" } },
2178
+ ];
2179
+
2180
+ /**
2181
+ * The bar above a list that holds its tabs and filters.
2182
+ * `ListTabs` are links, one URL per tab, with `activeId` read from the route; they hold no state and have no `onChange`.
2183
+ * For tabs held in state pass a `ToggleGroup` as `tabs`. `filters` controls take `layout="filter"` and `size="sm"`.
2184
+ */
2185
+ export function TabsFiltersExample({
2186
+ activeTab,
2187
+ customers,
2188
+ customerId,
2189
+ onCustomerChange,
2190
+ }: {
2191
+ activeTab: string;
2192
+ customers: { id: string; label: string }[];
2193
+ customerId: string | null;
2194
+ onCustomerChange: (customerId: string | null) => void;
2195
+ }) {
2196
+ return (
2197
+ <TabsFilters
2198
+ tabs={
2199
+ <ListTabs
2200
+ items={tabs}
2201
+ activeId={activeTab}
2202
+ />
2203
+ }
2204
+ filters={
2205
+ <Select
2206
+ label="Customer"
2207
+ layout="filter"
2208
+ size="sm"
2209
+ items={customers}
2210
+ value={customerId}
2211
+ onChange={onCustomerChange}
2212
+ />
2213
+ }
2214
+ onClearFilters={customerId ? () => onCustomerChange(null) : undefined}
2215
+ />
2216
+ );
2217
+ }
2218
+ ```
2219
+
2220
+ ### @povio/ui/tag
2221
+
2222
+ ```tsx
2223
+ import { Tag } from "@povio/ui/tag";
2224
+
2225
+ /** A static chip for a keyword or category, optionally removable. Children must be a plain string, and a tag is never pressable; `onRemove` adds the remove button, named "Remove <text>" (an `aria-label` in `removeButtonProps` replaces it). When a keyboard removal unmounts the tag, focus moves to the next remove button in the same list, or the previous one; after the last tag is removed, move focus yourself, e.g. to the input that adds tags. Use `Badge` for icons or `as="button"`. */
2226
+ export function TagExample({ skills, onRemoveSkill }: { skills: string[]; onRemoveSkill: (skill: string) => void }) {
2227
+ return (
2228
+ <div className="flex flex-wrap items-center gap-1.5">
2229
+ <Tag color="success">Verified</Tag>
2230
+ {skills.map((skill) => (
2231
+ <Tag
2232
+ key={skill}
2233
+ color="secondary"
2234
+ onRemove={() => onRemoveSkill(skill)}
2235
+ >
2236
+ {skill}
2237
+ </Tag>
2238
+ ))}
2239
+ </div>
2240
+ );
2241
+ }
2242
+ ```
2243
+
2244
+ ### @povio/ui/tanstack/form
2245
+
2246
+ ```tsx
2247
+ import { useState } from "react";
2248
+ import { Button } from "@povio/ui/button";
2249
+ import { DatePicker } from "@povio/ui/date-picker";
2250
+ import { Input } from "@povio/ui/input";
2251
+ import { NumberField } from "@povio/ui/number-field";
2252
+ import { Select } from "@povio/ui/select";
2253
+ import { useForm, useFormState, useFormValue } from "@povio/ui/tanstack/form";
2254
+ import { useToast } from "@povio/ui/use-toast";
2255
+ import { z } from "zod";
2256
+
2257
+ const roles = [
2258
+ { id: "admin", label: "Admin" },
2259
+ { id: "member", label: "Member" },
2260
+ ];
2261
+
2262
+ // Empty number, select and date fields hold `null`. `error` on the schema is the "required" message; without it the
2263
+ // user sees zod's "Invalid input: expected number, received null".
2264
+ const schema = z.object({
2265
+ name: z.string().min(1, "Name is required"),
2266
+ email: z.email("Enter a valid email"),
2267
+ age: z.number({ error: "Age is required" }),
2268
+ roleId: z.string({ error: "Role is required" }),
2269
+ startDate: z.iso.datetime({ error: "Start date is required" }),
2270
+ });
2271
+
2272
+ type Values = z.output<typeof schema>;
2273
+
2274
+ /** Form state and validation: `useForm` with a zod schema, and hooks that read its values and state. Bind inputs with `field={{ form, name }}` (no `form.Field`); read values with `useFormValue`, not `form.watch`. */
2275
+ export function TanstackFormExample({ invite }: { invite: (values: Values) => Promise<{ isEmailTaken: boolean }> }) {
2276
+ const { errorToast } = useToast();
2277
+ const form = useForm({
2278
+ defaultValues: { name: "", email: "", age: null, roleId: null, startDate: null },
2279
+ zodSchema: schema,
2280
+ });
2281
+ const isSubmitting = useFormState(form, (state) => state.isSubmitting);
2282
+ const name = useFormValue(form, (values) => values.name);
2283
+ // A server error is not schema state: keep it next to the form and pass it as `error`, which wins over the form's.
2284
+ const [emailError, setEmailError] = useState<string>();
2285
+
2286
+ const onSubmit = async (values: Values) => {
2287
+ const { isEmailTaken } = await invite(values);
2288
+ if (isEmailTaken) {
2289
+ setEmailError("This email is already invited");
2290
+ return;
2291
+ }
2292
+ // The saved values become the new defaults, so the form is clean again.
2293
+ form.reset(values);
2294
+ };
2295
+
2296
+ return (
2297
+ <form
2298
+ className="flex flex-col gap-4"
2299
+ // The second handler runs when validation fails; field errors are already shown.
2300
+ onSubmit={form.handleSubmit(onSubmit, () => errorToast("Check the highlighted fields"))}
2301
+ >
2302
+ <Input
2303
+ label="Name"
2304
+ field={{ form, name: "name" }}
2305
+ isRequired
2306
+ />
2307
+ <Input
2308
+ label="Email"
2309
+ type="email"
2310
+ field={{ form, name: "email", onValueChange: () => setEmailError(undefined) }}
2311
+ error={emailError}
2312
+ isRequired
2313
+ />
2314
+ <NumberField
2315
+ label="Age"
2316
+ minValue={0}
2317
+ field={{ form, name: "age" }}
2318
+ isRequired
2319
+ />
2320
+ <Select
2321
+ label="Role"
2322
+ items={roles}
2323
+ field={{ form, name: "roleId" }}
2324
+ isRequired
2325
+ />
2326
+ <DatePicker
2327
+ label="Start date"
2328
+ field={{ form, name: "startDate" }}
2329
+ isRequired
2330
+ />
2331
+ <Button
2332
+ type="submit"
2333
+ isLoading={isSubmitting}
2334
+ >
2335
+ {name ? `Invite ${name}` : "Invite"}
2336
+ </Button>
2337
+ </form>
2338
+ );
2339
+ }
2340
+
2341
+ const profileSchema = z.object({ name: z.string().min(1, "Name is required"), age: z.number().nullable() });
2342
+
2343
+ type Profile = z.output<typeof profileSchema>;
2344
+
2345
+ // `useForm` reads `defaultValues` once, on mount: render the form only after the record has loaded.
2346
+ export function EditProfileExample({ profile, save }: { profile?: Profile; save: (values: Profile) => Promise<void> }) {
2347
+ return profile ? (
2348
+ <EditProfileForm
2349
+ profile={profile}
2350
+ save={save}
2351
+ />
2352
+ ) : null;
2353
+ }
2354
+
2355
+ function EditProfileForm({ profile, save }: { profile: Profile; save: (values: Profile) => Promise<void> }) {
2356
+ const form = useForm({ defaultValues: profile, zodSchema: profileSchema });
2357
+ // `isDirty` stays true after an edit is undone; "differs from the saved values" is `!isDefaultValue`.
2358
+ const hasChanges = useFormState(form, (state) => !state.isDefaultValue);
2359
+ const isSubmitting = useFormState(form, (state) => state.isSubmitting);
2360
+
2361
+ return (
2362
+ <form
2363
+ className="flex flex-col gap-4"
2364
+ onSubmit={form.handleSubmit(async (values) => {
2365
+ await save(values);
2366
+ form.reset(values);
2367
+ })}
2368
+ >
2369
+ <Input
2370
+ label="Name"
2371
+ field={{ form, name: "name" }}
2372
+ />
2373
+ {/* An optional number is `.nullable()`: clearing the field writes null. */}
2374
+ <NumberField
2375
+ label="Age"
2376
+ field={{ form, name: "age" }}
2377
+ />
2378
+ <Button
2379
+ type="submit"
2380
+ isDisabled={!hasChanges}
2381
+ isLoading={isSubmitting}
2382
+ >
2383
+ Save
2384
+ </Button>
2385
+ </form>
2386
+ );
2387
+ }
2388
+ ```
2389
+
2390
+ ### @povio/ui/tanstack/table
2391
+
2392
+ ```tsx
2393
+ import { useState } from "react";
2394
+ import { Button } from "@povio/ui/button";
2395
+ import {
2396
+ type BulkSelectionActionsComponent,
2397
+ type ColumnDef,
2398
+ type InfiniteTableProps,
2399
+ type RowSelectionState,
2400
+ ColumnConfigModal,
2401
+ InfiniteTable,
2402
+ Table,
2403
+ useSorting,
2404
+ useTableColumnConfig,
2405
+ } from "@povio/ui/tanstack/table";
2406
+
2407
+ interface Invoice {
2408
+ id: string;
2409
+ number: string;
2410
+ customer: string;
2411
+ isPaid: boolean;
2412
+ notes: string;
2413
+ }
2414
+
2415
+ // Stands in for the app's list query (for example a generated React Query hook).
2416
+ declare function useInvoices(query: { order: string }): Invoice[];
2417
+
2418
+ // `ColumnDef<Row>` from this entry; `@tanstack/react-table`'s v9 `ColumnDef` takes the table features first.
2419
+ const columns: ColumnDef<Invoice>[] = [
2420
+ { accessorKey: "number", header: "Number" },
2421
+ { accessorKey: "customer", header: "Customer" },
2422
+ { id: "status", header: "Status", enableSorting: false, cell: ({ row }) => (row.original.isPaid ? "Paid" : "Open") },
2423
+ ];
2424
+
2425
+ type Props = Pick<
2426
+ InfiniteTableProps<Invoice>,
2427
+ "items" | "isLoading" | "hasNextPage" | "isFetchingNextPage" | "fetchNextPage"
2428
+ >;
2429
+
2430
+ /**
2431
+ * Data tables: `InfiniteTable` for server lists, `Table` for short fixed data, sorting and configurable columns. Server
2432
+ * lists use `InfiniteTable`, never a pager; a row opens `rowDetails` (with `getRowId`), not `onRowAction`. Wire the
2433
+ * infinite query's `isLoading`, `hasNextPage`, `isFetchingNextPage` and `fetchNextPage` straight in: the table shows the
2434
+ * first load, and `emptyState` (default "No results") when there are no rows. The table has no error state: when the
2435
+ * query failed with no data, the caller renders its error UI instead of the table.
2436
+ */
2437
+ export function TanstackTableExample({ items, isLoading, hasNextPage, isFetchingNextPage, fetchNextPage }: Props) {
2438
+ return (
2439
+ <InfiniteTable
2440
+ items={items}
2441
+ columns={columns}
2442
+ isLoading={isLoading}
2443
+ emptyState="No invoices yet"
2444
+ hasNextPage={hasNextPage}
2445
+ isFetchingNextPage={isFetchingNextPage}
2446
+ fetchNextPage={fetchNextPage}
2447
+ getRowId={(invoice) => invoice.id}
2448
+ rowDetails={{
2449
+ title: (invoice) => `Invoice ${invoice.number}`,
2450
+ render: (invoice) => <p className="text-muted-foreground">{invoice.notes}</p>,
2451
+ }}
2452
+ />
2453
+ );
2454
+ }
2455
+
2456
+ /**
2457
+ * Replaces the header row while rows are selected; the table keeps its select-all checkbox next to it. Define it at
2458
+ * module scope, as here: the table renders it as a component and passes `table`, so an inline one remounts every render.
2459
+ */
2460
+ const InvoiceBulkActions: BulkSelectionActionsComponent<Invoice> = ({ table }) => (
2461
+ <div className="flex items-center gap-3">
2462
+ <span>{table.getSelectedRowModel().rows.length} selected</span>
2463
+ <Button
2464
+ variant="outlined"
2465
+ size="sm"
2466
+ onPress={() => table.resetRowSelection()}
2467
+ >
2468
+ Clear
2469
+ </Button>
2470
+ </div>
2471
+ );
2472
+
2473
+ /**
2474
+ * Sorting and selection; `InfiniteTable` takes the same props. Table state is always `<x>` + `on<X>Change`.
2475
+ * The table never reorders rows: `order` goes to the query and the server sorts.
2476
+ * `enableRowSelection` adds the checkbox column and select-all; do not define one in `columns`. Selection is multiple
2477
+ * unless `enableMultiRowSelection={false}`; pass `defaultRowSelection` instead when the table may keep it itself.
2478
+ */
2479
+ export function TanstackTableSortingSelectionExample() {
2480
+ const { sorting, setSorting, order } = useSorting({ defaultSorting: [{ id: "number", desc: true }] });
2481
+ const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
2482
+ const invoices = useInvoices({ order });
2483
+
2484
+ return (
2485
+ <Table
2486
+ items={invoices}
2487
+ columns={columns}
2488
+ getRowId={(invoice) => invoice.id}
2489
+ sorting={sorting}
2490
+ onSortingChange={setSorting}
2491
+ enableRowSelection
2492
+ rowSelection={rowSelection}
2493
+ onRowSelectionChange={setRowSelection}
2494
+ bulkSelectionActions={InvoiceBulkActions}
2495
+ />
2496
+ );
2497
+ }
2498
+
2499
+ /**
2500
+ * User-configurable columns: `useTableColumnConfig` owns visibility and order and returns the visible `columns`;
2501
+ * `ColumnConfigModal` edits them. The modal opens like `Dialog`: from `trigger`, or with `isOpen` + `onOpenChange`.
2502
+ * Columns with `enableHiding: false` (e.g. row actions) always show and are not listed; columns missing from a saved
2503
+ * `columnOrder` go last.
2504
+ */
2505
+ export function TanstackTableColumnConfigExample({ items }: { items: Invoice[] }) {
2506
+ const columnConfig = useTableColumnConfig(columns);
2507
+
2508
+ return (
2509
+ <>
2510
+ <ColumnConfigModal
2511
+ trigger={
2512
+ <Button
2513
+ variant="outlined"
2514
+ size="sm"
2515
+ >
2516
+ Columns
2517
+ </Button>
2518
+ }
2519
+ configColumns={columnConfig.configColumns}
2520
+ visibleColumns={columnConfig.visibleColumns}
2521
+ onVisibilityChange={columnConfig.onVisibilityChange}
2522
+ onOrderChange={columnConfig.onOrderChange}
2523
+ onReset={columnConfig.resetColumns}
2524
+ />
2525
+ <Table
2526
+ items={items}
2527
+ columns={columnConfig.columns}
2528
+ />
2529
+ </>
2530
+ );
2531
+ }
2532
+ ```
2533
+
2534
+ ### @povio/ui/text-area
2535
+
2536
+ ```tsx
2537
+ import { useForm } from "@povio/ui/tanstack/form";
2538
+ import { TextArea } from "@povio/ui/text-area";
2539
+ import { z } from "zod";
2540
+
2541
+ const schema = z.object({ notes: z.string().max(500) });
2542
+
2543
+ /** A multi-line text field. Value is a string and `onChange` receives the string, not an event; set the height with `rows`. */
2544
+ export function TextAreaExample({ value, onChange }: { value: string; onChange: (value: string) => void }) {
2545
+ const form = useForm({ defaultValues: { notes: "" }, zodSchema: schema });
2546
+ return (
2547
+ <>
2548
+ <TextArea
2549
+ label="Description"
2550
+ rows={4}
2551
+ value={value}
2552
+ onChange={onChange}
2553
+ />
2554
+ <TextArea
2555
+ label="Notes"
2556
+ helperText="Up to 500 characters"
2557
+ field={{ form, name: "notes" }}
2558
+ />
2559
+ </>
2560
+ );
2561
+ }
2562
+ ```
2563
+
2564
+ ### @povio/ui/time-picker
2565
+
2566
+ ```tsx
2567
+ import { useForm } from "@povio/ui/tanstack/form";
2568
+ import { TimePicker } from "@povio/ui/time-picker";
2569
+ import { z } from "zod";
2570
+
2571
+ const schema = z.object({ opensAt: z.iso.datetime().nullable() });
2572
+
2573
+ /** A field for a time of day. Value is a full UTC ISO timestamp `YYYY-MM-DDTHH:mm:ss.sssZ` or `null`, not `"HH:mm"`; `date` (same format) sets the day the emitted time lands on, today when omitted. `minValue`/`maxValue` also take `HH:mm`. */
2574
+ export function TimePickerExample({
2575
+ value,
2576
+ onChange,
2577
+ }: {
2578
+ value: string | null;
2579
+ onChange: (value: string | null) => void;
2580
+ }) {
2581
+ const form = useForm({ defaultValues: { opensAt: null }, zodSchema: schema });
2582
+ return (
2583
+ <>
2584
+ <TimePicker
2585
+ label="Departure"
2586
+ date="2025-03-04T12:00:00.000Z"
2587
+ value={value}
2588
+ onChange={onChange}
2589
+ />
2590
+ <TimePicker
2591
+ label="Opens at"
2592
+ timeZone="UTC"
2593
+ minValue="06:00"
2594
+ maxValue="22:00"
2595
+ field={{ form, name: "opensAt" }}
2596
+ />
2597
+ </>
2598
+ );
2599
+ }
2600
+ ```
2601
+
2602
+ ### @povio/ui/toast
2603
+
2604
+ ```tsx
2605
+ import type { ReactNode } from "react";
2606
+ import { Button } from "@povio/ui/button";
2607
+ import { ToastContainer, useToast } from "@povio/ui/toast";
2608
+
2609
+ /** Temporary notifications shown over the page. Mount `ToastContainer` once at the app root as a sibling of the app (it takes no children). Show toasts by calling the functions from `useToast`, not by rendering `Toast`. */
2610
+ export function ToastExample({ children }: { children: ReactNode }) {
2611
+ return (
2612
+ <>
2613
+ {children}
2614
+ <ToastContainer />
2615
+ </>
2616
+ );
2617
+ }
2618
+
2619
+ /** Each function takes the message as a string, or `{ text, icon, actions, … }` when it needs more than text. */
2620
+ export function ToastCallExample({ onArchive }: { onArchive: () => Promise<void> }) {
2621
+ const { successToast, errorToast } = useToast();
2622
+
2623
+ return (
2624
+ <Button
2625
+ variant="outlined"
2626
+ onPress={() =>
2627
+ void onArchive().then(
2628
+ () => successToast("Project archived"),
2629
+ () => errorToast("Could not archive the project"),
2630
+ )
2631
+ }
2632
+ >
2633
+ Archive
2634
+ </Button>
2635
+ );
2636
+ }
2637
+ ```
2638
+
2639
+ ### @povio/ui/toggle-button
2640
+
2641
+ ```tsx
2642
+ import { LayoutGrid, Star } from "lucide-react";
2643
+ import { ToggleButton } from "@povio/ui/toggle-button";
2644
+
2645
+ /** A button that stays pressed until it is pressed again, for one on or off option. State is `isSelected` + `onChange(isSelected)`, not `onPress`; with `iconOnly` the children are still required as the accessible name. */
2646
+ export function ToggleButtonExample({
2647
+ isFavorite,
2648
+ onFavoriteChange,
2649
+ isGridView,
2650
+ onGridViewChange,
2651
+ }: {
2652
+ isFavorite: boolean;
2653
+ onFavoriteChange: (isFavorite: boolean) => void;
2654
+ isGridView: boolean;
2655
+ onGridViewChange: (isGridView: boolean) => void;
2656
+ }) {
2657
+ return (
2658
+ <div className="flex items-center gap-2">
2659
+ <ToggleButton
2660
+ icon={Star}
2661
+ isSelected={isFavorite}
2662
+ onChange={onFavoriteChange}
2663
+ >
2664
+ Favorite
2665
+ </ToggleButton>
2666
+ <ToggleButton
2667
+ iconOnly
2668
+ icon={LayoutGrid}
2669
+ isSelected={isGridView}
2670
+ onChange={onGridViewChange}
2671
+ >
2672
+ Grid view
2673
+ </ToggleButton>
2674
+ </div>
2675
+ );
2676
+ }
2677
+ ```
2678
+
2679
+ ### @povio/ui/toggle-group
2680
+
2681
+ ```tsx
2682
+ import { LayoutGrid, List } from "lucide-react";
2683
+ import { useState } from "react";
2684
+ import { useForm } from "@povio/ui/tanstack/form";
2685
+ import { ToggleGroup } from "@povio/ui/toggle-group";
2686
+ import { z } from "zod";
2687
+
2688
+ // `as const` keeps the ids as literals, so the state below is typed by them.
2689
+ const views = [
2690
+ { id: "grid", label: "Grid", icon: LayoutGrid },
2691
+ { id: "list", label: "List", icon: List },
2692
+ ] as const;
2693
+
2694
+ const weekdays = [
2695
+ { id: "mon", label: "Mon" },
2696
+ { id: "tue", label: "Tue" },
2697
+ { id: "wed", label: "Wed" },
2698
+ ];
2699
+
2700
+ const schema = z.object({ days: z.array(z.string()).min(1, "Pick at least one day") });
2701
+
2702
+ /**
2703
+ * A segmented control for picking one, or several, of a few options; also tabs held in state.
2704
+ * Stores item `id`s: `id | null`, or `id[]` with `selectionMode="multiple"`. For tabs held in state add
2705
+ * `disallowEmptySelection`: the selection cannot be cleared, so `onChange` always receives an id and takes the state
2706
+ * setter. `label` names the group (`hideLabel` keeps it for screen readers only); an icon-only item needs its own
2707
+ * `aria-label`.
2708
+ */
2709
+ export function ToggleGroupExample() {
2710
+ const [view, setView] = useState<(typeof views)[number]["id"]>("grid");
2711
+ const form = useForm({ defaultValues: { days: ["mon"] }, zodSchema: schema });
2712
+ return (
2713
+ <>
2714
+ <ToggleGroup
2715
+ label="View"
2716
+ hideLabel
2717
+ items={views}
2718
+ disallowEmptySelection
2719
+ value={view}
2720
+ onChange={setView}
2721
+ />
2722
+ <ToggleGroup
2723
+ label="Days"
2724
+ items={weekdays}
2725
+ selectionMode="multiple"
2726
+ field={{ form, name: "days" }}
2727
+ />
2728
+ </>
2729
+ );
2730
+ }
2731
+ ```
2732
+
2733
+ ### @povio/ui/tooltip
2734
+
2735
+ ```tsx
2736
+ import { Info } from "lucide-react";
2737
+ import { Button } from "@povio/ui/button";
2738
+ import { IconSlot } from "@povio/ui/icon-slot";
2739
+ import { Tooltip } from "@povio/ui/tooltip";
2740
+
2741
+ /** A short hint shown while the user hovers over or focuses its trigger. The content prop is `text` (not `content`), and the child is the trigger; a child that is not focusable (icon, plain text) needs `isNonInteractiveTrigger`. `delay` and `closeDelay` are in milliseconds and default to 0. */
2742
+ export function TooltipExample({ onExport }: { onExport: () => void }) {
2743
+ return (
2744
+ <div className="flex items-center gap-2">
2745
+ <Tooltip
2746
+ text="Download all rows as CSV"
2747
+ placement="top"
2748
+ delay={300}
2749
+ >
2750
+ <Button
2751
+ variant="outlined"
2752
+ onPress={onExport}
2753
+ >
2754
+ Export
2755
+ </Button>
2756
+ </Tooltip>
2757
+ <Tooltip
2758
+ text="Exports include archived orders"
2759
+ isNonInteractiveTrigger
2760
+ >
2761
+ <IconSlot
2762
+ icon={Info}
2763
+ className="text-muted-foreground"
2764
+ />
2765
+ </Tooltip>
2766
+ </div>
2767
+ );
2768
+ }
2769
+ ```
2770
+
2771
+ ### @povio/ui/tooltip-ellipsis
2772
+
2773
+ ```tsx
2774
+ import { Tag } from "@povio/ui/tag";
2775
+ import { TooltipEllipsis } from "@povio/ui/tooltip-ellipsis";
2776
+
2777
+ /** Shows the full text in a tooltip while it is cut off with an ellipsis. Children is a render function: attach its `ref` to the truncating text element (`contentRef` on Button, Badge and Tag) and constrain the width, on the element itself (`max-w-40`) or through its container (`block truncate` in a table cell); a non-focusable child also needs `isNonInteractiveTrigger`. */
2778
+ export function TooltipEllipsisExample({ ownerEmail }: { ownerEmail: string }) {
2779
+ return (
2780
+ <TooltipEllipsis
2781
+ text={ownerEmail}
2782
+ isNonInteractiveTrigger
2783
+ >
2784
+ {(ref) => (
2785
+ <Tag
2786
+ color="secondary"
2787
+ contentRef={ref}
2788
+ className="max-w-40"
2789
+ >
2790
+ {ownerEmail}
2791
+ </Tag>
2792
+ )}
2793
+ </TooltipEllipsis>
2794
+ );
2795
+ }
2796
+ ```
2797
+
2798
+ ### @povio/ui/typography
2799
+
2800
+ ```tsx
2801
+ import { Typography } from "@povio/ui/typography";
2802
+
2803
+ /** Text in the library's type scale, from page headings to small print. `size` is required and only sets the text style; the element is always `<p>` unless `as` says otherwise. Weight and colour come from `className`. */
2804
+ export function TypographyExample({ title, description }: { title: string; description: string }) {
2805
+ return (
2806
+ <header className="flex flex-col gap-1">
2807
+ <Typography
2808
+ as="h1"
2809
+ size="h2"
2810
+ className="font-semibold"
2811
+ >
2812
+ {title}
2813
+ </Typography>
2814
+ <Typography
2815
+ size="body"
2816
+ className="text-muted-foreground"
2817
+ >
2818
+ {description}
2819
+ </Typography>
2820
+ </header>
2821
+ );
2822
+ }
2823
+ ```
2824
+
2825
+ ### @povio/ui/ui-config
2826
+
2827
+ ```tsx
2828
+ import type { ReactNode } from "react";
2829
+ import { UIConfig } from "@povio/ui/ui-config";
2830
+
2831
+ /** Merged over the defaults section by section, so each section lists only the keys it changes. Kept at module scope so the provider's deep compare has a stable object; `UIConfig.Config` is its type. */
2832
+ const config: UIConfig.Config = {
2833
+ input: { layout: "floating", isClearable: true },
2834
+ table: { rowDetailsMode: "split" },
2835
+ };
2836
+
2837
+ /** App-wide default props, such as the default input layout. Render once at the app root; `config` is merged over the defaults section by section, so pass only the keys you change. The default input layout is `input.layout`. */
2838
+ export function UiConfigExample({ children }: { children: ReactNode }) {
2839
+ return <UIConfig.Provider config={config}>{children}</UIConfig.Provider>;
2840
+ }
2841
+ ```
2842
+
2843
+ ### @povio/ui/ui-overrides
2844
+
2845
+ ```tsx
2846
+ import type { ReactNode } from "react";
2847
+ import { UIOverrides } from "@povio/ui/ui-overrides";
2848
+
2849
+ const buttonSizeOverride = UIOverrides.defineOverride("button.sizeCva", {
2850
+ mode: "merge",
2851
+ config: { variants: { size: { sm: "rounded-full", default: "rounded-full" } } },
2852
+ });
2853
+
2854
+ const overrides: UIOverrides.Config = { button: { sizeCva: buttonSizeOverride } };
2855
+
2856
+ /** App-wide class changes to the component style recipes. Keep the config at module level; `mode: "merge"` adds classes, `"overrideEntry"` replaces the parts you supply. */
2857
+ export function UiOverridesExample({ children }: { children: ReactNode }) {
2858
+ return <UIOverrides.Provider config={overrides}>{children}</UIOverrides.Provider>;
2859
+ }
2860
+ ```
2861
+
2862
+ ### @povio/ui/use-async-list
2863
+
2864
+ ```tsx
2865
+ import { Button } from "@povio/ui/button";
2866
+ import { Select } from "@povio/ui/select";
2867
+ import { useForm, useFormValue } from "@povio/ui/tanstack/form";
2868
+ import { useAsyncList } from "@povio/ui/use-async-list";
2869
+ import { z } from "zod";
2870
+
2871
+ interface City {
2872
+ id: string;
2873
+ label: string;
2874
+ }
2875
+
2876
+ interface CityPage {
2877
+ items: City[];
2878
+ nextCursor: string | null;
2879
+ }
2880
+
2881
+ // `error` is the "required" message; without it the user sees zod's "Invalid input: expected string, received null".
2882
+ const schema = z.object({ cityId: z.string({ error: "Choose a city" }) });
2883
+
2884
+ /**
2885
+ * Loads the items of a `Select` or `Autocomplete` from the server, page by page and per search.
2886
+ * Pass the result as `list` (instead of `items`) with `isSearchable`; return `cursor: undefined` on the last page.
2887
+ * The list supplies `isLoading`, `hasNextPage`, `fetchNextPage` and `isFetchingNextPage`, named as on a TanStack
2888
+ * infinite query, and sends the search text to the loader as `filterText`.
2889
+ */
2890
+ export function UseAsyncListExample({
2891
+ savedCity,
2892
+ searchCities,
2893
+ }: {
2894
+ /** The saved record, which may not be on the first page. */
2895
+ savedCity: City | null;
2896
+ searchCities: (search: string, cursor: string | undefined, signal: AbortSignal) => Promise<CityPage>;
2897
+ }) {
2898
+ const list = useAsyncList<City>({
2899
+ load: async ({ signal, filterText = "", cursor }) => {
2900
+ const page = await searchCities(filterText, cursor, signal);
2901
+ return { items: page.items, cursor: page.nextCursor ?? undefined };
2902
+ },
2903
+ });
2904
+ const form = useForm({ defaultValues: { cityId: savedCity?.id ?? null }, zodSchema: schema });
2905
+ return (
2906
+ <>
2907
+ {/* `initialSelection` supplies the label while the saved ID is not among the loaded items. */}
2908
+ <Select
2909
+ label="City"
2910
+ list={list}
2911
+ isSearchable
2912
+ isRequired
2913
+ initialSelection={savedCity}
2914
+ field={{ form, name: "cityId" }}
2915
+ error={list.error?.message}
2916
+ />
2917
+ {list.error && <Button onPress={() => list.reload()}>Retry</Button>}
2918
+ </>
2919
+ );
2920
+ }
2921
+
2922
+ const countries = [
2923
+ { id: "si", label: "Slovenia" },
2924
+ { id: "at", label: "Austria" },
2925
+ ];
2926
+
2927
+ const addressSchema = z.object({
2928
+ countryId: z.string({ error: "Choose a country" }),
2929
+ cityId: z.string({ error: "Choose a city" }),
2930
+ });
2931
+
2932
+ /**
2933
+ * A list that depends on another field, such as cities of the chosen country: the loader reads the parent value
2934
+ * with `useFormValue`. When the parent changes, clear the child and call `reload()`. It loads after that change
2935
+ * renders, so it already uses the new parent value.
2936
+ */
2937
+ export function DependentAsyncListExample({
2938
+ searchCities,
2939
+ }: {
2940
+ searchCities: (
2941
+ countryId: string,
2942
+ search: string,
2943
+ cursor: string | undefined,
2944
+ signal: AbortSignal,
2945
+ ) => Promise<CityPage>;
2946
+ }) {
2947
+ const form = useForm({ defaultValues: { countryId: null, cityId: null }, zodSchema: addressSchema });
2948
+ const countryId = useFormValue(form, (values) => values.countryId);
2949
+ const cities = useAsyncList<City>({
2950
+ load: async ({ signal, filterText = "", cursor }) => {
2951
+ if (!countryId) return { items: [] };
2952
+ const page = await searchCities(countryId, filterText, cursor, signal);
2953
+ return { items: page.items, cursor: page.nextCursor ?? undefined };
2954
+ },
2955
+ });
2956
+ return (
2957
+ <>
2958
+ <Select
2959
+ label="Country"
2960
+ items={countries}
2961
+ field={{
2962
+ form,
2963
+ name: "countryId",
2964
+ onValueChange: () => {
2965
+ form.resetField("cityId");
2966
+ cities.reload();
2967
+ },
2968
+ }}
2969
+ />
2970
+ <Select
2971
+ label="City"
2972
+ list={cities}
2973
+ isSearchable
2974
+ isDisabled={!countryId}
2975
+ field={{ form, name: "cityId" }}
2976
+ />
2977
+ </>
2978
+ );
2979
+ }
2980
+ ```
2981
+
2982
+ ### @povio/ui/use-breakpoint
2983
+
2984
+ ```tsx
2985
+ import type { ReactNode } from "react";
2986
+ import { BottomSheet } from "@povio/ui/bottom-sheet";
2987
+ import { Dialog } from "@povio/ui/dialog";
2988
+ import { useBreakpoint } from "@povio/ui/use-breakpoint";
2989
+
2990
+ /** Whether the viewport is at least a Tailwind breakpoint wide (`sm`, `md`, `lg`, `xl`), the same switch the library's own components use. Use it instead of a hand-written media query; during server rendering it returns `UIConfig.responsive.ssrMatches[breakpoint]` (false by default). `Popover` and `DropdownMenu` already turn into a bottom sheet below `md`, so reach for this only when the two layouts differ in more than the surface. */
2991
+ export function UseBreakpointExample({
2992
+ isOpen,
2993
+ onOpenChange,
2994
+ children,
2995
+ }: {
2996
+ isOpen: boolean;
2997
+ onOpenChange: (isOpen: boolean) => void;
2998
+ children: ReactNode;
2999
+ }) {
3000
+ const isDesktop = useBreakpoint("md");
3001
+
3002
+ return isDesktop ? (
3003
+ <Dialog
3004
+ isOpen={isOpen}
3005
+ onOpenChange={onOpenChange}
3006
+ label="Filters"
3007
+ className="w-modal"
3008
+ >
3009
+ {children}
3010
+ </Dialog>
3011
+ ) : (
3012
+ <BottomSheet
3013
+ isOpen={isOpen}
3014
+ onOpenChange={onOpenChange}
3015
+ label="Filters"
3016
+ >
3017
+ {children}
3018
+ </BottomSheet>
3019
+ );
3020
+ }
3021
+ ```
3022
+
3023
+ ### @povio/ui/use-filters
3024
+
3025
+ ```tsx
3026
+ import type { ReactNode } from "react";
3027
+ import { Button } from "@povio/ui/button";
3028
+ import { Input } from "@povio/ui/input";
3029
+ import { NumberField } from "@povio/ui/number-field";
3030
+ import { useFilters } from "@povio/ui/use-filters";
3031
+ import { z } from "zod";
3032
+
3033
+ const filterSchema = z.object({ customer: z.string().optional(), minAmount: z.number().optional() });
3034
+ type InvoiceFilter = z.output<typeof filterSchema>;
3035
+
3036
+ /**
3037
+ * List filters kept in the URL query string.
3038
+ * Takes one options object: `{ defaultValues, prefix, schema }`, all optional. With a `schema` (defined outside the
3039
+ * component) the store is typed from it and URL values that fail it are left out, so no type argument is needed. Set a
3040
+ * key to `undefined` to drop it from the URL; `clearAllFilters` restores `defaultValues`. The URL keys are
3041
+ * `filter[<key>]`, or `filter[<prefix>][<key>]` with a `prefix`; give every store on a page its own prefix. Dates are
3042
+ * written as ISO text and read back for `z.date()` fields. Needs `UIRouter.UIRouterProvider` from `@povio/ui/ui-router`
3043
+ * at the app root.
3044
+ */
3045
+ export function UseFiltersExample({ children }: { children: (filter: InvoiceFilter) => ReactNode }) {
3046
+ const filters = useFilters({ schema: filterSchema });
3047
+ return (
3048
+ <>
3049
+ <div className="flex flex-wrap items-center gap-3">
3050
+ <Input
3051
+ label="Customer"
3052
+ layout="filter"
3053
+ size="sm"
3054
+ isClearable
3055
+ value={filters.filterData.customer ?? ""}
3056
+ onChange={(customer) => filters.setFilterValue({ customer: customer || undefined })}
3057
+ />
3058
+ <NumberField
3059
+ label="Min amount"
3060
+ layout="filter"
3061
+ size="sm"
3062
+ value={filters.filterData.minAmount ?? null}
3063
+ onChange={(minAmount) => filters.setFilterValue({ minAmount: minAmount ?? undefined })}
3064
+ />
3065
+ <Button
3066
+ variant="ghost"
3067
+ size="sm"
3068
+ onPress={filters.clearAllFilters}
3069
+ >
3070
+ Clear all
3071
+ </Button>
3072
+ </div>
3073
+ {children(filters.filterData)}
3074
+ </>
3075
+ );
3076
+ }
3077
+ ```
3078
+
3079
+ ### @povio/ui/use-toast
3080
+
3081
+ ```tsx
3082
+ import { Check } from "lucide-react";
3083
+ import { Button } from "@povio/ui/button";
3084
+ import { useToast } from "@povio/ui/use-toast";
3085
+
3086
+ /** Shows success, error, warning and secondary (neutral grey) toasts from code. The hook (also exported from `@povio/ui/toast`) returns `successToast`, `errorToast`, `warningToast`, `secondaryToast` and `closeToast(id)`. Each takes the message as a string or `{ text, icon, actions, … }`, plus optional `{ autoClose }` in milliseconds and `{ toastId }` (a toast whose ID is still on screen is not shown twice), returns the toast ID and needs a mounted `ToastContainer`. A toast closes after 2.5 s, except one with `actions`: it stays, with a close button, until the user presses that or an action, and pressing an action also closes it. */
3087
+ export function UseToastExample({ onSave }: { onSave: () => Promise<void> }) {
3088
+ const { successToast, errorToast } = useToast();
3089
+
3090
+ const save = async () => {
3091
+ try {
3092
+ await onSave();
3093
+ successToast("Changes saved");
3094
+ } catch {
3095
+ errorToast({ text: "Could not save changes", actions: [{ label: "Retry", onPress: () => void save() }] });
3096
+ }
3097
+ };
3098
+
3099
+ return <Button onPress={() => void save()}>Save changes</Button>;
3100
+ }
3101
+
3102
+ /** `icon` takes a component or an element, as on `Button`. */
3103
+ export function UseToastIconExample({ fileName }: { fileName: string }) {
3104
+ const { successToast } = useToast();
3105
+
3106
+ return (
3107
+ <Button
3108
+ variant="outlined"
3109
+ onPress={() => successToast({ text: `${fileName} uploaded`, icon: Check }, { autoClose: 5000 })}
3110
+ >
3111
+ Upload
3112
+ </Button>
3113
+ );
3114
+ }
3115
+ ```
3116
+