@povio/ui 6.0.0-rc.12 → 6.0.0-rc.14

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