foldkit-mixins-ui 0.26.0 → 0.27.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2976 -887
- package/dist/accordion/state.d.ts +36 -0
- package/dist/accordion/state.d.ts.map +1 -0
- package/dist/accordion/state.js +35 -0
- package/dist/accordion/state.js.map +1 -0
- package/dist/accordion/toggled.d.ts +11 -0
- package/dist/accordion/toggled.d.ts.map +1 -0
- package/dist/accordion/toggled.js +17 -0
- package/dist/accordion/toggled.js.map +1 -0
- package/dist/accordion.d.ts +26 -11
- package/dist/accordion.d.ts.map +1 -1
- package/dist/accordion.js +26 -17
- package/dist/accordion.js.map +1 -1
- package/dist/adornments.d.ts +42 -0
- package/dist/adornments.d.ts.map +1 -0
- package/dist/adornments.js +35 -0
- package/dist/adornments.js.map +1 -0
- package/dist/alert.d.ts +35 -5
- package/dist/alert.d.ts.map +1 -1
- package/dist/alert.js +22 -5
- package/dist/alert.js.map +1 -1
- package/dist/anchor.d.ts +16 -3
- package/dist/anchor.d.ts.map +1 -1
- package/dist/anchor.js +123 -12
- package/dist/anchor.js.map +1 -1
- package/dist/angleSlider.d.ts +28 -3
- package/dist/angleSlider.d.ts.map +1 -1
- package/dist/angleSlider.js +19 -5
- package/dist/angleSlider.js.map +1 -1
- package/dist/appShell.d.ts +34 -5
- package/dist/appShell.d.ts.map +1 -1
- package/dist/appShell.js +23 -6
- package/dist/appShell.js.map +1 -1
- package/dist/aspectRatio.d.ts +9 -0
- package/dist/aspectRatio.d.ts.map +1 -1
- package/dist/aspectRatio.js +4 -1
- package/dist/aspectRatio.js.map +1 -1
- package/dist/avatar/picture.d.ts +15 -0
- package/dist/avatar/picture.d.ts.map +1 -0
- package/dist/avatar/picture.js +19 -0
- package/dist/avatar/picture.js.map +1 -0
- package/dist/avatar.d.ts +81 -28
- package/dist/avatar.d.ts.map +1 -1
- package/dist/avatar.js +54 -27
- package/dist/avatar.js.map +1 -1
- package/dist/badge.d.ts +40 -10
- package/dist/badge.d.ts.map +1 -1
- package/dist/badge.js +39 -6
- package/dist/badge.js.map +1 -1
- package/dist/breadcrumb/menu.d.ts +29 -0
- package/dist/breadcrumb/menu.d.ts.map +1 -0
- package/dist/breadcrumb/menu.js +30 -0
- package/dist/breadcrumb/menu.js.map +1 -0
- package/dist/breadcrumb.d.ts +57 -29
- package/dist/breadcrumb.d.ts.map +1 -1
- package/dist/breadcrumb.js +63 -45
- package/dist/breadcrumb.js.map +1 -1
- package/dist/bundles/accordion.d.ts +19 -0
- package/dist/bundles/accordion.d.ts.map +1 -0
- package/dist/bundles/accordion.js +20 -0
- package/dist/bundles/accordion.js.map +1 -0
- package/dist/bundles/angleSlider.d.ts +37 -0
- package/dist/bundles/angleSlider.d.ts.map +1 -0
- package/dist/bundles/angleSlider.js +46 -0
- package/dist/bundles/angleSlider.js.map +1 -0
- package/dist/bundles/calendar.d.ts +1245 -0
- package/dist/bundles/calendar.d.ts.map +1 -0
- package/dist/bundles/calendar.js +26 -0
- package/dist/bundles/calendar.js.map +1 -0
- package/dist/bundles/carousel.d.ts +50 -0
- package/dist/bundles/carousel.d.ts.map +1 -0
- package/dist/bundles/carousel.js +31 -0
- package/dist/bundles/carousel.js.map +1 -0
- package/dist/bundles/cascadeSelect.d.ts +80 -0
- package/dist/bundles/cascadeSelect.d.ts.map +1 -0
- package/dist/bundles/cascadeSelect.js +66 -0
- package/dist/bundles/cascadeSelect.js.map +1 -0
- package/dist/bundles/colorPicker.d.ts +78 -0
- package/dist/bundles/colorPicker.d.ts.map +1 -0
- package/dist/bundles/colorPicker.js +42 -0
- package/dist/bundles/colorPicker.js.map +1 -0
- package/dist/bundles/combobox.d.ts +135 -0
- package/dist/bundles/combobox.d.ts.map +1 -0
- package/dist/bundles/combobox.js +74 -0
- package/dist/bundles/combobox.js.map +1 -0
- package/dist/bundles/datePicker.d.ts +911 -0
- package/dist/bundles/datePicker.d.ts.map +1 -0
- package/dist/bundles/datePicker.js +25 -0
- package/dist/bundles/datePicker.js.map +1 -0
- package/dist/bundles/dialog.d.ts +71 -0
- package/dist/bundles/dialog.d.ts.map +1 -0
- package/dist/bundles/dialog.js +45 -0
- package/dist/bundles/dialog.js.map +1 -0
- package/dist/bundles/disclosure.d.ts +17 -0
- package/dist/bundles/disclosure.d.ts.map +1 -0
- package/dist/bundles/disclosure.js +20 -0
- package/dist/bundles/disclosure.js.map +1 -0
- package/dist/bundles/drawer.d.ts +76 -0
- package/dist/bundles/drawer.d.ts.map +1 -0
- package/dist/bundles/drawer.js +39 -0
- package/dist/bundles/drawer.js.map +1 -0
- package/dist/bundles/fileDrop.d.ts +29 -0
- package/dist/bundles/fileDrop.d.ts.map +1 -0
- package/dist/bundles/fileDrop.js +36 -0
- package/dist/bundles/fileDrop.js.map +1 -0
- package/dist/bundles/fileUpload.d.ts +183 -0
- package/dist/bundles/fileUpload.d.ts.map +1 -0
- package/dist/bundles/fileUpload.js +45 -0
- package/dist/bundles/fileUpload.js.map +1 -0
- package/dist/bundles/floatingPanel.d.ts +197 -0
- package/dist/bundles/floatingPanel.d.ts.map +1 -0
- package/dist/bundles/floatingPanel.js +52 -0
- package/dist/bundles/floatingPanel.js.map +1 -0
- package/dist/bundles/hoverIntent.d.ts +98 -0
- package/dist/bundles/hoverIntent.d.ts.map +1 -0
- package/dist/bundles/hoverIntent.js +28 -0
- package/dist/bundles/hoverIntent.js.map +1 -0
- package/dist/bundles/imageCropper.d.ts +136 -0
- package/dist/bundles/imageCropper.d.ts.map +1 -0
- package/dist/bundles/imageCropper.js +48 -0
- package/dist/bundles/imageCropper.js.map +1 -0
- package/dist/bundles/index.d.ts +42 -0
- package/dist/bundles/index.js +42 -0
- package/dist/bundles/inputCopy.d.ts +24 -0
- package/dist/bundles/inputCopy.d.ts.map +1 -0
- package/dist/bundles/inputCopy.js +21 -0
- package/dist/bundles/inputCopy.js.map +1 -0
- package/dist/bundles/listbox.d.ts +120 -0
- package/dist/bundles/listbox.d.ts.map +1 -0
- package/dist/bundles/listbox.js +52 -0
- package/dist/bundles/listbox.js.map +1 -0
- package/dist/bundles/marquee.d.ts +27 -0
- package/dist/bundles/marquee.d.ts.map +1 -0
- package/dist/bundles/marquee.js +25 -0
- package/dist/bundles/marquee.js.map +1 -0
- package/dist/bundles/menu.d.ts +310 -0
- package/dist/bundles/menu.d.ts.map +1 -0
- package/dist/bundles/menu.js +34 -0
- package/dist/bundles/menu.js.map +1 -0
- package/dist/bundles/menubar.d.ts +145 -0
- package/dist/bundles/menubar.d.ts.map +1 -0
- package/dist/bundles/menubar.js +28 -0
- package/dist/bundles/menubar.js.map +1 -0
- package/dist/bundles/messageScroller.d.ts +29 -0
- package/dist/bundles/messageScroller.d.ts.map +1 -0
- package/dist/bundles/messageScroller.js +24 -0
- package/dist/bundles/messageScroller.js.map +1 -0
- package/dist/bundles/nav.d.ts +39 -0
- package/dist/bundles/nav.d.ts.map +1 -0
- package/dist/bundles/nav.js +22 -0
- package/dist/bundles/nav.js.map +1 -0
- package/dist/bundles/passwordInput.d.ts +19 -0
- package/dist/bundles/passwordInput.d.ts.map +1 -0
- package/dist/bundles/passwordInput.js +20 -0
- package/dist/bundles/passwordInput.js.map +1 -0
- package/dist/bundles/picker.d.ts +211 -0
- package/dist/bundles/picker.d.ts.map +1 -0
- package/dist/bundles/picker.js +48 -0
- package/dist/bundles/picker.js.map +1 -0
- package/dist/bundles/popover.d.ts +212 -0
- package/dist/bundles/popover.d.ts.map +1 -0
- package/dist/bundles/popover.js +34 -0
- package/dist/bundles/popover.js.map +1 -0
- package/dist/bundles/radioGroup.d.ts +27 -0
- package/dist/bundles/radioGroup.d.ts.map +1 -0
- package/dist/bundles/radioGroup.js +19 -0
- package/dist/bundles/radioGroup.js.map +1 -0
- package/dist/bundles/resizable.d.ts +44 -0
- package/dist/bundles/resizable.d.ts.map +1 -0
- package/dist/bundles/resizable.js +34 -0
- package/dist/bundles/resizable.js.map +1 -0
- package/dist/bundles/sheet.d.ts +104 -0
- package/dist/bundles/sheet.d.ts.map +1 -0
- package/dist/bundles/sheet.js +47 -0
- package/dist/bundles/sheet.js.map +1 -0
- package/dist/bundles/signaturePad.d.ts +111 -0
- package/dist/bundles/signaturePad.d.ts.map +1 -0
- package/dist/bundles/signaturePad.js +48 -0
- package/dist/bundles/signaturePad.js.map +1 -0
- package/dist/bundles/tabs.d.ts +31 -0
- package/dist/bundles/tabs.d.ts.map +1 -0
- package/dist/bundles/tabs.js +20 -0
- package/dist/bundles/tabs.js.map +1 -0
- package/dist/bundles/tagsInput.d.ts +50 -0
- package/dist/bundles/tagsInput.d.ts.map +1 -0
- package/dist/bundles/tagsInput.js +29 -0
- package/dist/bundles/tagsInput.js.map +1 -0
- package/dist/bundles/thinkingSteps.d.ts +21 -0
- package/dist/bundles/thinkingSteps.d.ts.map +1 -0
- package/dist/bundles/thinkingSteps.js +19 -0
- package/dist/bundles/thinkingSteps.js.map +1 -0
- package/dist/bundles/timer.d.ts +34 -0
- package/dist/bundles/timer.d.ts.map +1 -0
- package/dist/bundles/timer.js +42 -0
- package/dist/bundles/timer.js.map +1 -0
- package/dist/bundles/toast.d.ts +132 -0
- package/dist/bundles/toast.d.ts.map +1 -0
- package/dist/bundles/toast.js +42 -0
- package/dist/bundles/toast.js.map +1 -0
- package/dist/bundles/toolbar.d.ts +15 -0
- package/dist/bundles/toolbar.d.ts.map +1 -0
- package/dist/bundles/toolbar.js +21 -0
- package/dist/bundles/toolbar.js.map +1 -0
- package/dist/bundles/tooltip.d.ts +43 -0
- package/dist/bundles/tooltip.d.ts.map +1 -0
- package/dist/bundles/tooltip.js +25 -0
- package/dist/bundles/tooltip.js.map +1 -0
- package/dist/bundles/tour.d.ts +87 -0
- package/dist/bundles/tour.d.ts.map +1 -0
- package/dist/bundles/tour.js +26 -0
- package/dist/bundles/tour.js.map +1 -0
- package/dist/bundles/treeView.d.ts +56 -0
- package/dist/bundles/treeView.d.ts.map +1 -0
- package/dist/bundles/treeView.js +46 -0
- package/dist/bundles/treeView.js.map +1 -0
- package/dist/bundles/virtualList.d.ts +688 -0
- package/dist/bundles/virtualList.d.ts.map +1 -0
- package/dist/bundles/virtualList.js +57 -0
- package/dist/bundles/virtualList.js.map +1 -0
- package/dist/bundles/windowList.d.ts +80 -0
- package/dist/bundles/windowList.d.ts.map +1 -0
- package/dist/bundles/windowList.js +37 -0
- package/dist/bundles/windowList.js.map +1 -0
- package/dist/button.d.ts +76 -9
- package/dist/button.d.ts.map +1 -1
- package/dist/button.js +65 -24
- package/dist/button.js.map +1 -1
- package/dist/buttonGroup.d.ts +2 -2
- package/dist/buttonGroup.js +5 -2
- package/dist/buttonGroup.js.map +1 -1
- package/dist/calendar/layout.d.ts +78 -0
- package/dist/calendar/layout.d.ts.map +1 -0
- package/dist/calendar/layout.js +78 -0
- package/dist/calendar/layout.js.map +1 -0
- package/dist/calendar/selection.d.ts +85 -0
- package/dist/calendar/selection.d.ts.map +1 -0
- package/dist/calendar/selection.js +136 -0
- package/dist/calendar/selection.js.map +1 -0
- package/dist/calendar/shown.d.ts +36 -0
- package/dist/calendar/shown.d.ts.map +1 -0
- package/dist/calendar/shown.js +52 -0
- package/dist/calendar/shown.js.map +1 -0
- package/dist/calendar/state.d.ts +579 -0
- package/dist/calendar/state.d.ts.map +1 -0
- package/dist/calendar/state.js +174 -0
- package/dist/calendar/state.js.map +1 -0
- package/dist/calendar/view.d.ts +71 -0
- package/dist/calendar/view.d.ts.map +1 -0
- package/dist/calendar/view.js +81 -0
- package/dist/calendar/view.js.map +1 -0
- package/dist/calendar.d.ts +44 -114
- package/dist/calendar.d.ts.map +1 -1
- package/dist/calendar.js +66 -182
- package/dist/calendar.js.map +1 -1
- package/dist/card/fluid.d.ts +11 -0
- package/dist/card/fluid.d.ts.map +1 -0
- package/dist/card/fluid.js +31 -0
- package/dist/card/fluid.js.map +1 -0
- package/dist/card.d.ts +70 -33
- package/dist/card.d.ts.map +1 -1
- package/dist/card.js +65 -57
- package/dist/card.js.map +1 -1
- package/dist/carousel.d.ts +54 -17
- package/dist/carousel.d.ts.map +1 -1
- package/dist/carousel.js +64 -27
- package/dist/carousel.js.map +1 -1
- package/dist/cascadeSelect.d.ts +89 -8
- package/dist/cascadeSelect.d.ts.map +1 -1
- package/dist/cascadeSelect.js +171 -61
- package/dist/cascadeSelect.js.map +1 -1
- package/dist/chart/area.d.ts +10 -0
- package/dist/chart/area.d.ts.map +1 -0
- package/dist/chart/area.js +11 -0
- package/dist/chart/area.js.map +1 -0
- package/dist/chart/bars.d.ts +13 -0
- package/dist/chart/bars.d.ts.map +1 -0
- package/dist/chart/bars.js +35 -0
- package/dist/chart/bars.js.map +1 -0
- package/dist/chart/cartesian.d.ts +52 -0
- package/dist/chart/cartesian.d.ts.map +1 -0
- package/dist/chart/cartesian.js +132 -0
- package/dist/chart/cartesian.js.map +1 -0
- package/dist/chart/donut.d.ts +20 -0
- package/dist/chart/donut.d.ts.map +1 -0
- package/dist/chart/donut.js +44 -0
- package/dist/chart/donut.js.map +1 -0
- package/dist/chart/kind.d.ts +62 -0
- package/dist/chart/kind.d.ts.map +1 -0
- package/dist/chart/kind.js +8 -0
- package/dist/chart/kind.js.map +1 -0
- package/dist/chart/line.d.ts +5 -0
- package/dist/chart/line.d.ts.map +1 -0
- package/dist/chart/line.js +11 -0
- package/dist/chart/line.js.map +1 -0
- package/dist/chart/paths.d.ts +15 -0
- package/dist/chart/paths.d.ts.map +1 -0
- package/dist/chart/paths.js +36 -0
- package/dist/chart/paths.js.map +1 -0
- package/dist/chart/scale.d.ts +10 -4
- package/dist/chart/scale.d.ts.map +1 -1
- package/dist/chart/scale.js +31 -12
- package/dist/chart/scale.js.map +1 -1
- package/dist/chart/slots.d.ts +72 -0
- package/dist/chart/slots.d.ts.map +1 -0
- package/dist/chart/slots.js +90 -0
- package/dist/chart/slots.js.map +1 -0
- package/dist/chart.d.ts +24 -110
- package/dist/chart.d.ts.map +1 -1
- package/dist/chart.js +46 -268
- package/dist/chart.js.map +1 -1
- package/dist/chatMessage.d.ts +55 -6
- package/dist/chatMessage.d.ts.map +1 -1
- package/dist/chatMessage.js +69 -6
- package/dist/chatMessage.js.map +1 -1
- package/dist/checkbox/slots.d.ts +19 -0
- package/dist/checkbox/slots.d.ts.map +1 -0
- package/dist/checkbox/slots.js +38 -0
- package/dist/checkbox/slots.js.map +1 -0
- package/dist/checkbox/view.d.ts +52 -0
- package/dist/checkbox/view.d.ts.map +1 -0
- package/dist/checkbox/view.js +50 -0
- package/dist/checkbox/view.js.map +1 -0
- package/dist/checkbox.d.ts +4 -13
- package/dist/checkbox.d.ts.map +1 -1
- package/dist/checkbox.js +4 -29
- package/dist/checkbox.js.map +1 -1
- package/dist/checkboxGroup.d.ts +26 -6
- package/dist/checkboxGroup.d.ts.map +1 -1
- package/dist/checkboxGroup.js +34 -6
- package/dist/checkboxGroup.js.map +1 -1
- package/dist/choice/many.d.ts +4 -0
- package/dist/choice/many.d.ts.map +1 -0
- package/dist/choice/many.js +23 -0
- package/dist/choice/many.js.map +1 -0
- package/dist/choice/one.d.ts +5 -0
- package/dist/choice/one.d.ts.map +1 -0
- package/dist/choice/one.js +25 -0
- package/dist/choice/one.js.map +1 -0
- package/dist/choice/text.d.ts +8 -0
- package/dist/choice/text.d.ts.map +1 -0
- package/dist/choice/text.js +23 -0
- package/dist/choice/text.js.map +1 -0
- package/dist/choice.d.ts +36 -0
- package/dist/choice.d.ts.map +1 -0
- package/dist/choice.js +28 -0
- package/dist/choice.js.map +1 -0
- package/dist/codeBlock/follow.d.ts +8 -0
- package/dist/codeBlock/follow.d.ts.map +1 -0
- package/dist/codeBlock/follow.js +47 -0
- package/dist/codeBlock/follow.js.map +1 -0
- package/dist/codeBlock/slots.d.ts +30 -0
- package/dist/codeBlock/slots.d.ts.map +1 -0
- package/dist/codeBlock/slots.js +47 -0
- package/dist/codeBlock/slots.js.map +1 -0
- package/dist/codeBlock.d.ts +52 -25
- package/dist/codeBlock.d.ts.map +1 -1
- package/dist/codeBlock.js +80 -26
- package/dist/codeBlock.js.map +1 -1
- package/dist/colorPicker/popover.d.ts +28 -0
- package/dist/colorPicker/popover.d.ts.map +1 -0
- package/dist/colorPicker/popover.js +56 -0
- package/dist/colorPicker/popover.js.map +1 -0
- package/dist/colorPicker.d.ts +66 -31
- package/dist/colorPicker.d.ts.map +1 -1
- package/dist/colorPicker.js +35 -63
- package/dist/colorPicker.js.map +1 -1
- package/dist/combobox/filters.d.ts +9 -0
- package/dist/combobox/filters.d.ts.map +1 -0
- package/dist/combobox/filters.js +12 -0
- package/dist/combobox/filters.js.map +1 -0
- package/dist/combobox/fluid.d.ts +9 -0
- package/dist/combobox/fluid.d.ts.map +1 -0
- package/dist/combobox/fluid.js +29 -0
- package/dist/combobox/fluid.js.map +1 -0
- package/dist/combobox/overlayBars.d.ts +8 -0
- package/dist/combobox/overlayBars.d.ts.map +1 -0
- package/dist/combobox/overlayBars.js +17 -0
- package/dist/combobox/overlayBars.js.map +1 -0
- package/dist/combobox/slots.d.ts +57 -0
- package/dist/combobox/slots.d.ts.map +1 -0
- package/dist/combobox/slots.js +114 -0
- package/dist/combobox/slots.js.map +1 -0
- package/dist/combobox/view.d.ts +88 -0
- package/dist/combobox/view.d.ts.map +1 -0
- package/dist/combobox/view.js +87 -0
- package/dist/combobox/view.js.map +1 -0
- package/dist/combobox/words.d.ts +10 -0
- package/dist/combobox/words.d.ts.map +1 -0
- package/dist/combobox/words.js +9 -0
- package/dist/combobox/words.js.map +1 -0
- package/dist/combobox.d.ts +17 -71
- package/dist/combobox.d.ts.map +1 -1
- package/dist/combobox.js +17 -144
- package/dist/combobox.js.map +1 -1
- package/dist/comboboxShared.d.ts +14 -9
- package/dist/comboboxShared.d.ts.map +1 -1
- package/dist/comboboxShared.js +53 -33
- package/dist/comboboxShared.js.map +1 -1
- package/dist/command/overlayBars.d.ts +8 -0
- package/dist/command/overlayBars.d.ts.map +1 -0
- package/dist/command/overlayBars.js +17 -0
- package/dist/command/overlayBars.js.map +1 -0
- package/dist/command/slots.d.ts +56 -0
- package/dist/command/slots.d.ts.map +1 -0
- package/dist/command/slots.js +80 -0
- package/dist/command/slots.js.map +1 -0
- package/dist/command/words.d.ts +10 -0
- package/dist/command/words.d.ts.map +1 -0
- package/dist/command/words.js +9 -0
- package/dist/command/words.js.map +1 -0
- package/dist/command.d.ts +51 -66
- package/dist/command.d.ts.map +1 -1
- package/dist/command.js +94 -109
- package/dist/command.js.map +1 -1
- package/dist/configure.d.ts +28 -0
- package/dist/configure.d.ts.map +1 -0
- package/dist/configure.js +38 -0
- package/dist/configure.js.map +1 -0
- package/dist/datePicker/state.d.ts +504 -0
- package/dist/datePicker/state.d.ts.map +1 -0
- package/dist/datePicker/state.js +157 -0
- package/dist/datePicker/state.js.map +1 -0
- package/dist/datePicker/view.d.ts +66 -0
- package/dist/datePicker/view.d.ts.map +1 -0
- package/dist/datePicker/view.js +79 -0
- package/dist/datePicker/view.js.map +1 -0
- package/dist/datePicker.d.ts +16 -9
- package/dist/datePicker.d.ts.map +1 -1
- package/dist/datePicker.js +15 -9
- package/dist/datePicker.js.map +1 -1
- package/dist/datePickerView.d.ts +26 -26
- package/dist/datePickerView.js +4 -4
- package/dist/datePickerView.js.map +1 -1
- package/dist/dialog/focusReturn.d.ts +11 -0
- package/dist/dialog/focusReturn.d.ts.map +1 -0
- package/dist/dialog/focusReturn.js +20 -0
- package/dist/dialog/focusReturn.js.map +1 -0
- package/dist/dialog/keyboard.d.ts +8 -0
- package/dist/dialog/keyboard.d.ts.map +1 -0
- package/dist/dialog/keyboard.js +17 -0
- package/dist/dialog/keyboard.js.map +1 -0
- package/dist/dialog/overlayBars.d.ts +7 -0
- package/dist/dialog/overlayBars.d.ts.map +1 -0
- package/dist/dialog/overlayBars.js +16 -0
- package/dist/dialog/overlayBars.js.map +1 -0
- package/dist/dialog/slots.d.ts +42 -0
- package/dist/dialog/slots.d.ts.map +1 -0
- package/dist/dialog/slots.js +64 -0
- package/dist/dialog/slots.js.map +1 -0
- package/dist/dialog.d.ts +51 -56
- package/dist/dialog.d.ts.map +1 -1
- package/dist/dialog.js +82 -75
- package/dist/dialog.js.map +1 -1
- package/dist/disclosure/slots.d.ts +12 -0
- package/dist/disclosure/slots.d.ts.map +1 -0
- package/dist/disclosure/slots.js +24 -0
- package/dist/disclosure/slots.js.map +1 -0
- package/dist/disclosure/state.d.ts +31 -0
- package/dist/disclosure/state.d.ts.map +1 -0
- package/dist/disclosure/state.js +26 -0
- package/dist/disclosure/state.js.map +1 -0
- package/dist/disclosure/view.d.ts +37 -0
- package/dist/disclosure/view.d.ts.map +1 -0
- package/dist/disclosure/view.js +33 -0
- package/dist/disclosure/view.js.map +1 -0
- package/dist/disclosure.d.ts +4 -5
- package/dist/disclosure.d.ts.map +1 -1
- package/dist/disclosure.js +4 -15
- package/dist/disclosure.js.map +1 -1
- package/dist/drawer/keepFocus.d.ts +2 -0
- package/dist/drawer/keepFocus.d.ts.map +1 -0
- package/dist/drawer/keepFocus.js +35 -0
- package/dist/drawer/keepFocus.js.map +1 -0
- package/dist/drawer/slots.d.ts +9 -0
- package/dist/drawer/slots.d.ts.map +1 -0
- package/dist/drawer/slots.js +16 -0
- package/dist/drawer/slots.js.map +1 -0
- package/dist/drawer.d.ts +11 -15
- package/dist/drawer.d.ts.map +1 -1
- package/dist/drawer.js +8 -17
- package/dist/drawer.js.map +1 -1
- package/dist/empty.d.ts +9 -0
- package/dist/empty.d.ts.map +1 -1
- package/dist/empty.js +4 -1
- package/dist/empty.js.map +1 -1
- package/dist/field.d.ts +7 -0
- package/dist/field.d.ts.map +1 -1
- package/dist/field.js +7 -1
- package/dist/field.js.map +1 -1
- package/dist/fieldShell.d.ts +75 -0
- package/dist/fieldShell.d.ts.map +1 -0
- package/dist/fieldShell.js +61 -0
- package/dist/fieldShell.js.map +1 -0
- package/dist/fieldset.d.ts +20 -2
- package/dist/fieldset.d.ts.map +1 -1
- package/dist/fieldset.js +15 -1
- package/dist/fieldset.js.map +1 -1
- package/dist/figure.d.ts +9 -0
- package/dist/figure.d.ts.map +1 -1
- package/dist/figure.js +4 -1
- package/dist/figure.js.map +1 -1
- package/dist/fileDrop.d.ts +8 -0
- package/dist/fileDrop.d.ts.map +1 -1
- package/dist/fileDrop.js +6 -1
- package/dist/fileDrop.js.map +1 -1
- package/dist/fileInput.d.ts +129 -0
- package/dist/fileInput.d.ts.map +1 -0
- package/dist/fileInput.js +151 -0
- package/dist/fileInput.js.map +1 -0
- package/dist/fileUpload/progress.d.ts +22 -0
- package/dist/fileUpload/progress.d.ts.map +1 -0
- package/dist/fileUpload/progress.js +34 -0
- package/dist/fileUpload/progress.js.map +1 -0
- package/dist/fileUpload/sort.d.ts +10 -0
- package/dist/fileUpload/sort.d.ts.map +1 -0
- package/dist/fileUpload/sort.js +22 -0
- package/dist/fileUpload/sort.js.map +1 -0
- package/dist/fileUpload.d.ts +641 -0
- package/dist/fileUpload.d.ts.map +1 -0
- package/dist/fileUpload.js +1004 -0
- package/dist/fileUpload.js.map +1 -0
- package/dist/floatingPanel/focusReturn.d.ts +10 -0
- package/dist/floatingPanel/focusReturn.d.ts.map +1 -0
- package/dist/floatingPanel/focusReturn.js +19 -0
- package/dist/floatingPanel/focusReturn.js.map +1 -0
- package/dist/floatingPanel/slots.d.ts +26 -0
- package/dist/floatingPanel/slots.d.ts.map +1 -0
- package/dist/floatingPanel/slots.js +61 -0
- package/dist/floatingPanel/slots.js.map +1 -0
- package/dist/floatingPanel.d.ts +141 -74
- package/dist/floatingPanel.d.ts.map +1 -1
- package/dist/floatingPanel.js +306 -169
- package/dist/floatingPanel.js.map +1 -1
- package/dist/frame.d.ts +53 -0
- package/dist/frame.d.ts.map +1 -0
- package/dist/frame.js +50 -0
- package/dist/frame.js.map +1 -0
- package/dist/hoverIntent.d.ts +5 -1
- package/dist/hoverIntent.d.ts.map +1 -1
- package/dist/hoverIntent.js +13 -3
- package/dist/hoverIntent.js.map +1 -1
- package/dist/icon.d.ts +31 -14
- package/dist/icon.d.ts.map +1 -1
- package/dist/icon.js +11 -8
- package/dist/icon.js.map +1 -1
- package/dist/image/audit.d.ts +10 -0
- package/dist/image/audit.d.ts.map +1 -0
- package/dist/image/audit.js +50 -0
- package/dist/image/audit.js.map +1 -0
- package/dist/image/slots.d.ts +18 -0
- package/dist/image/slots.d.ts.map +1 -0
- package/dist/image/slots.js +21 -0
- package/dist/image/slots.js.map +1 -0
- package/dist/image/watchLoad.d.ts +9 -0
- package/dist/image/watchLoad.d.ts.map +1 -0
- package/dist/image/watchLoad.js +45 -0
- package/dist/image/watchLoad.js.map +1 -0
- package/dist/image.d.ts +23 -36
- package/dist/image.d.ts.map +1 -1
- package/dist/image.js +22 -100
- package/dist/image.js.map +1 -1
- package/dist/imageAttributes.d.ts +1 -1
- package/dist/imageCropper/zoomSlider.d.ts +10 -0
- package/dist/imageCropper/zoomSlider.d.ts.map +1 -0
- package/dist/imageCropper/zoomSlider.js +14 -0
- package/dist/imageCropper/zoomSlider.js.map +1 -0
- package/dist/imageCropper.d.ts +46 -10
- package/dist/imageCropper.d.ts.map +1 -1
- package/dist/imageCropper.js +26 -17
- package/dist/imageCropper.js.map +1 -1
- package/dist/index.d.ts +63 -41
- package/dist/index.js +25 -8
- package/dist/input.d.ts +64 -14
- package/dist/input.d.ts.map +1 -1
- package/dist/input.js +61 -24
- package/dist/input.js.map +1 -1
- package/dist/inputCopy.d.ts +29 -6
- package/dist/inputCopy.d.ts.map +1 -1
- package/dist/inputCopy.js +65 -18
- package/dist/inputCopy.js.map +1 -1
- package/dist/item.d.ts +37 -5
- package/dist/item.d.ts.map +1 -1
- package/dist/item.js +38 -7
- package/dist/item.js.map +1 -1
- package/dist/kbd.d.ts +3 -2
- package/dist/kbd.d.ts.map +1 -1
- package/dist/kbd.js.map +1 -1
- package/dist/label.d.ts +45 -8
- package/dist/label.d.ts.map +1 -1
- package/dist/label.js +26 -6
- package/dist/label.js.map +1 -1
- package/dist/listbox/fluid.d.ts +9 -0
- package/dist/listbox/fluid.d.ts.map +1 -0
- package/dist/listbox/fluid.js +29 -0
- package/dist/listbox/fluid.js.map +1 -0
- package/dist/listbox/overlayBars.d.ts +8 -0
- package/dist/listbox/overlayBars.d.ts.map +1 -0
- package/dist/listbox/overlayBars.js +17 -0
- package/dist/listbox/overlayBars.js.map +1 -0
- package/dist/listbox/slots.d.ts +52 -0
- package/dist/listbox/slots.d.ts.map +1 -0
- package/dist/listbox/slots.js +94 -0
- package/dist/listbox/slots.js.map +1 -0
- package/dist/listbox/view.d.ts +88 -0
- package/dist/listbox/view.d.ts.map +1 -0
- package/dist/listbox/view.js +93 -0
- package/dist/listbox/view.js.map +1 -0
- package/dist/listbox/words.d.ts +8 -0
- package/dist/listbox/words.d.ts.map +1 -0
- package/dist/listbox/words.js +6 -0
- package/dist/listbox/words.js.map +1 -0
- package/dist/listbox.d.ts +22 -74
- package/dist/listbox.d.ts.map +1 -1
- package/dist/listbox.js +20 -130
- package/dist/listbox.js.map +1 -1
- package/dist/listboxShared.d.ts.map +1 -1
- package/dist/listboxShared.js +99 -74
- package/dist/listboxShared.js.map +1 -1
- package/dist/listboxView.d.ts.map +1 -1
- package/dist/listboxView.js.map +1 -1
- package/dist/marquee.d.ts +10 -5
- package/dist/marquee.d.ts.map +1 -1
- package/dist/marquee.js +28 -6
- package/dist/marquee.js.map +1 -1
- package/dist/menu/fluid.d.ts +8 -0
- package/dist/menu/fluid.d.ts.map +1 -0
- package/dist/menu/fluid.js +23 -0
- package/dist/menu/fluid.js.map +1 -0
- package/dist/menu/overlayBars.d.ts +8 -0
- package/dist/menu/overlayBars.d.ts.map +1 -0
- package/dist/menu/overlayBars.js +17 -0
- package/dist/menu/overlayBars.js.map +1 -0
- package/dist/menu/slots.d.ts +53 -0
- package/dist/menu/slots.d.ts.map +1 -0
- package/dist/menu/slots.js +94 -0
- package/dist/menu/slots.js.map +1 -0
- package/dist/menu.d.ts +81 -80
- package/dist/menu.d.ts.map +1 -1
- package/dist/menu.js +79 -199
- package/dist/menu.js.map +1 -1
- package/dist/menuView.d.ts.map +1 -1
- package/dist/menuView.js +34 -9
- package/dist/menuView.js.map +1 -1
- package/dist/menubar.d.ts +42 -10
- package/dist/menubar.d.ts.map +1 -1
- package/dist/menubar.js +49 -22
- package/dist/menubar.js.map +1 -1
- package/dist/messageScroller.d.ts +52 -11
- package/dist/messageScroller.d.ts.map +1 -1
- package/dist/messageScroller.js +65 -17
- package/dist/messageScroller.js.map +1 -1
- package/dist/meter.d.ts +4 -0
- package/dist/meter.d.ts.map +1 -1
- package/dist/meter.js +21 -1
- package/dist/meter.js.map +1 -1
- package/dist/nav.d.ts +48 -6
- package/dist/nav.d.ts.map +1 -1
- package/dist/nav.js +108 -33
- package/dist/nav.js.map +1 -1
- package/dist/numberField.d.ts +55 -8
- package/dist/numberField.d.ts.map +1 -1
- package/dist/numberField.js +89 -19
- package/dist/numberField.js.map +1 -1
- package/dist/otpField.d.ts +15 -1
- package/dist/otpField.d.ts.map +1 -1
- package/dist/otpField.js +19 -4
- package/dist/otpField.js.map +1 -1
- package/dist/pagination.d.ts +58 -16
- package/dist/pagination.d.ts.map +1 -1
- package/dist/pagination.js +78 -27
- package/dist/pagination.js.map +1 -1
- package/dist/passwordInput.d.ts +64 -13
- package/dist/passwordInput.d.ts.map +1 -1
- package/dist/passwordInput.js +90 -30
- package/dist/passwordInput.js.map +1 -1
- package/dist/patterns.d.ts +237 -15
- package/dist/patterns.d.ts.map +1 -1
- package/dist/patterns.js +451 -66
- package/dist/patterns.js.map +1 -1
- package/dist/picker.d.ts +82 -16
- package/dist/picker.d.ts.map +1 -1
- package/dist/picker.js +163 -67
- package/dist/picker.js.map +1 -1
- package/dist/popover.d.ts +1 -1
- package/dist/popupView.d.ts +3 -0
- package/dist/popupView.d.ts.map +1 -1
- package/dist/popupView.js +5 -1
- package/dist/popupView.js.map +1 -1
- package/dist/press.d.ts +23 -0
- package/dist/press.d.ts.map +1 -0
- package/dist/press.js +29 -0
- package/dist/press.js.map +1 -0
- package/dist/progress.d.ts +3 -2
- package/dist/progress.d.ts.map +1 -1
- package/dist/progress.js.map +1 -1
- package/dist/qrCode.d.ts +11 -2
- package/dist/qrCode.d.ts.map +1 -1
- package/dist/qrCode.js +10 -3
- package/dist/qrCode.js.map +1 -1
- package/dist/questionnaire.d.ts +15 -12
- package/dist/questionnaire.d.ts.map +1 -1
- package/dist/questionnaire.js +23 -12
- package/dist/questionnaire.js.map +1 -1
- package/dist/radioGroup/readingKeys.d.ts +11 -0
- package/dist/radioGroup/readingKeys.d.ts.map +1 -0
- package/dist/radioGroup/readingKeys.js +48 -0
- package/dist/radioGroup/readingKeys.js.map +1 -0
- package/dist/radioGroup/slots.d.ts +34 -0
- package/dist/radioGroup/slots.d.ts.map +1 -0
- package/dist/radioGroup/slots.js +58 -0
- package/dist/radioGroup/slots.js.map +1 -0
- package/dist/radioGroup/view.d.ts +55 -0
- package/dist/radioGroup/view.d.ts.map +1 -0
- package/dist/radioGroup/view.js +65 -0
- package/dist/radioGroup/view.js.map +1 -0
- package/dist/radioGroup.d.ts +12 -35
- package/dist/radioGroup.d.ts.map +1 -1
- package/dist/radioGroup.js +12 -57
- package/dist/radioGroup.js.map +1 -1
- package/dist/rating/words.d.ts +14 -0
- package/dist/rating/words.d.ts.map +1 -0
- package/dist/rating/words.js +11 -0
- package/dist/rating/words.js.map +1 -0
- package/dist/rating.d.ts +25 -16
- package/dist/rating.d.ts.map +1 -1
- package/dist/rating.js +52 -46
- package/dist/rating.js.map +1 -1
- package/dist/recipes/accordion.d.ts +7 -4
- package/dist/recipes/accordion.d.ts.map +1 -1
- package/dist/recipes/accordion.js +28 -9
- package/dist/recipes/accordion.js.map +1 -1
- package/dist/recipes/alert.d.ts +7 -1
- package/dist/recipes/alert.d.ts.map +1 -1
- package/dist/recipes/alert.js +18 -8
- package/dist/recipes/alert.js.map +1 -1
- package/dist/recipes/angleSlider.d.ts +2 -2
- package/dist/recipes/appShell.d.ts +2 -1
- package/dist/recipes/appShell.d.ts.map +1 -1
- package/dist/recipes/appShell.js +33 -1
- package/dist/recipes/appShell.js.map +1 -1
- package/dist/recipes/avatar.d.ts +8 -1
- package/dist/recipes/avatar.d.ts.map +1 -1
- package/dist/recipes/avatar.js +51 -8
- package/dist/recipes/avatar.js.map +1 -1
- package/dist/recipes/badge.d.ts +39 -13
- package/dist/recipes/badge.d.ts.map +1 -1
- package/dist/recipes/badge.js +126 -52
- package/dist/recipes/badge.js.map +1 -1
- package/dist/recipes/breadcrumb.d.ts +16 -4
- package/dist/recipes/breadcrumb.d.ts.map +1 -1
- package/dist/recipes/breadcrumb.js +68 -21
- package/dist/recipes/breadcrumb.js.map +1 -1
- package/dist/recipes/button.d.ts +15 -1
- package/dist/recipes/button.d.ts.map +1 -1
- package/dist/recipes/button.js +52 -5
- package/dist/recipes/button.js.map +1 -1
- package/dist/recipes/buttonGroup.d.ts +1 -1
- package/dist/recipes/calendar.d.ts +10 -1
- package/dist/recipes/calendar.d.ts.map +1 -1
- package/dist/recipes/calendar.js +34 -6
- package/dist/recipes/calendar.js.map +1 -1
- package/dist/recipes/card.d.ts +18 -0
- package/dist/recipes/card.d.ts.map +1 -1
- package/dist/recipes/card.js +65 -6
- package/dist/recipes/card.js.map +1 -1
- package/dist/recipes/carousel.d.ts.map +1 -1
- package/dist/recipes/carousel.js +2 -2
- package/dist/recipes/carousel.js.map +1 -1
- package/dist/recipes/cascadeSelect.d.ts +5 -1
- package/dist/recipes/cascadeSelect.d.ts.map +1 -1
- package/dist/recipes/cascadeSelect.js +13 -31
- package/dist/recipes/cascadeSelect.js.map +1 -1
- package/dist/recipes/chart.d.ts.map +1 -1
- package/dist/recipes/chart.js +2 -1
- package/dist/recipes/chart.js.map +1 -1
- package/dist/recipes/chatMessage.d.ts +10 -1
- package/dist/recipes/chatMessage.d.ts.map +1 -1
- package/dist/recipes/chatMessage.js +34 -1
- package/dist/recipes/chatMessage.js.map +1 -1
- package/dist/recipes/checkboxGroup.d.ts +10 -2
- package/dist/recipes/checkboxGroup.d.ts.map +1 -1
- package/dist/recipes/checkboxGroup.js +38 -4
- package/dist/recipes/checkboxGroup.js.map +1 -1
- package/dist/recipes/codeBlock.d.ts +20 -1
- package/dist/recipes/codeBlock.d.ts.map +1 -1
- package/dist/recipes/codeBlock.js +176 -67
- package/dist/recipes/codeBlock.js.map +1 -1
- package/dist/recipes/colorPicker.d.ts +2 -2
- package/dist/recipes/combobox.d.ts +7 -1
- package/dist/recipes/combobox.d.ts.map +1 -1
- package/dist/recipes/combobox.js +9 -21
- package/dist/recipes/combobox.js.map +1 -1
- package/dist/recipes/command.d.ts.map +1 -1
- package/dist/recipes/command.js +2 -2
- package/dist/recipes/command.js.map +1 -1
- package/dist/recipes/datePicker.d.ts +1 -0
- package/dist/recipes/datePicker.d.ts.map +1 -1
- package/dist/recipes/datePicker.js +5 -2
- package/dist/recipes/datePicker.js.map +1 -1
- package/dist/recipes/design.d.ts +46 -0
- package/dist/recipes/design.d.ts.map +1 -1
- package/dist/recipes/design.js +49 -16
- package/dist/recipes/design.js.map +1 -1
- package/dist/recipes/dialog.d.ts +38 -2
- package/dist/recipes/dialog.d.ts.map +1 -1
- package/dist/recipes/dialog.js +43 -18
- package/dist/recipes/dialog.js.map +1 -1
- package/dist/recipes/disclosure.d.ts +4 -1
- package/dist/recipes/disclosure.d.ts.map +1 -1
- package/dist/recipes/disclosure.js +11 -0
- package/dist/recipes/disclosure.js.map +1 -1
- package/dist/recipes/drawer.d.ts.map +1 -1
- package/dist/recipes/drawer.js +6 -1
- package/dist/recipes/drawer.js.map +1 -1
- package/dist/recipes/field.d.ts +57 -26
- package/dist/recipes/field.d.ts.map +1 -1
- package/dist/recipes/field.js +124 -25
- package/dist/recipes/field.js.map +1 -1
- package/dist/recipes/fieldShell.d.ts +12 -0
- package/dist/recipes/fieldShell.d.ts.map +1 -0
- package/dist/recipes/fieldShell.js +71 -0
- package/dist/recipes/fieldShell.js.map +1 -0
- package/dist/recipes/figure.d.ts +6 -0
- package/dist/recipes/figure.d.ts.map +1 -1
- package/dist/recipes/figure.js +14 -5
- package/dist/recipes/figure.js.map +1 -1
- package/dist/recipes/fileDrop.js +7 -1
- package/dist/recipes/fileDrop.js.map +1 -1
- package/dist/recipes/fileInput.d.ts +23 -0
- package/dist/recipes/fileInput.d.ts.map +1 -0
- package/dist/recipes/fileInput.js +92 -0
- package/dist/recipes/fileInput.js.map +1 -0
- package/dist/recipes/fileUpload.d.ts +86 -0
- package/dist/recipes/fileUpload.d.ts.map +1 -0
- package/dist/recipes/fileUpload.js +401 -0
- package/dist/recipes/fileUpload.js.map +1 -0
- package/dist/recipes/floatingPanel.d.ts +1 -1
- package/dist/recipes/floatingPanel.js +2 -2
- package/dist/recipes/floatingPanel.js.map +1 -1
- package/dist/recipes/frame.d.ts +51 -0
- package/dist/recipes/frame.d.ts.map +1 -0
- package/dist/recipes/frame.js +105 -0
- package/dist/recipes/frame.js.map +1 -0
- package/dist/recipes/icon.d.ts +50 -1
- package/dist/recipes/icon.d.ts.map +1 -1
- package/dist/recipes/icon.js +107 -21
- package/dist/recipes/icon.js.map +1 -1
- package/dist/recipes/imageCropper.d.ts +1 -0
- package/dist/recipes/imageCropper.d.ts.map +1 -1
- package/dist/recipes/imageCropper.js +7 -3
- package/dist/recipes/imageCropper.js.map +1 -1
- package/dist/recipes/index.d.ts +13 -6
- package/dist/recipes/index.js +12 -6
- package/dist/recipes/inputCopy.d.ts +5 -2
- package/dist/recipes/inputCopy.d.ts.map +1 -1
- package/dist/recipes/inputCopy.js +7 -3
- package/dist/recipes/inputCopy.js.map +1 -1
- package/dist/recipes/item.d.ts +7 -1
- package/dist/recipes/item.d.ts.map +1 -1
- package/dist/recipes/item.js +20 -0
- package/dist/recipes/item.js.map +1 -1
- package/dist/recipes/kbd.js +4 -0
- package/dist/recipes/kbd.js.map +1 -1
- package/dist/recipes/label.d.ts +4 -1
- package/dist/recipes/label.d.ts.map +1 -1
- package/dist/recipes/label.js +32 -9
- package/dist/recipes/label.js.map +1 -1
- package/dist/recipes/listbox.d.ts +7 -1
- package/dist/recipes/listbox.d.ts.map +1 -1
- package/dist/recipes/listbox.js +46 -7
- package/dist/recipes/listbox.js.map +1 -1
- package/dist/recipes/menu.d.ts +5 -1
- package/dist/recipes/menu.d.ts.map +1 -1
- package/dist/recipes/menu.js +26 -2
- package/dist/recipes/menu.js.map +1 -1
- package/dist/recipes/menubar.d.ts +5 -1
- package/dist/recipes/menubar.d.ts.map +1 -1
- package/dist/recipes/menubar.js +4 -3
- package/dist/recipes/menubar.js.map +1 -1
- package/dist/recipes/meter.d.ts +11 -1
- package/dist/recipes/meter.d.ts.map +1 -1
- package/dist/recipes/meter.js +60 -26
- package/dist/recipes/meter.js.map +1 -1
- package/dist/recipes/nav.d.ts +11 -3
- package/dist/recipes/nav.d.ts.map +1 -1
- package/dist/recipes/nav.js +56 -22
- package/dist/recipes/nav.js.map +1 -1
- package/dist/recipes/numberField.d.ts +16 -2
- package/dist/recipes/numberField.d.ts.map +1 -1
- package/dist/recipes/numberField.js +66 -49
- package/dist/recipes/numberField.js.map +1 -1
- package/dist/recipes/otpField.d.ts +1 -1
- package/dist/recipes/otpField.js +5 -5
- package/dist/recipes/otpField.js.map +1 -1
- package/dist/recipes/pagination.d.ts +26 -6
- package/dist/recipes/pagination.d.ts.map +1 -1
- package/dist/recipes/pagination.js +42 -13
- package/dist/recipes/pagination.js.map +1 -1
- package/dist/recipes/passwordInput.d.ts +7 -3
- package/dist/recipes/passwordInput.d.ts.map +1 -1
- package/dist/recipes/passwordInput.js +11 -4
- package/dist/recipes/passwordInput.js.map +1 -1
- package/dist/recipes/picker.d.ts +9 -6
- package/dist/recipes/picker.d.ts.map +1 -1
- package/dist/recipes/picker.js +18 -7
- package/dist/recipes/picker.js.map +1 -1
- package/dist/recipes/popover.d.ts.map +1 -1
- package/dist/recipes/popover.js +6 -3
- package/dist/recipes/popover.js.map +1 -1
- package/dist/recipes/popup.d.ts +11 -0
- package/dist/recipes/popup.d.ts.map +1 -1
- package/dist/recipes/popup.js +22 -8
- package/dist/recipes/popup.js.map +1 -1
- package/dist/recipes/progress.d.ts +1 -1
- package/dist/recipes/progress.d.ts.map +1 -1
- package/dist/recipes/progress.js +5 -4
- package/dist/recipes/progress.js.map +1 -1
- package/dist/recipes/radio.d.ts +20 -3
- package/dist/recipes/radio.d.ts.map +1 -1
- package/dist/recipes/radio.js +47 -4
- package/dist/recipes/radio.js.map +1 -1
- package/dist/recipes/rating.d.ts +12 -3
- package/dist/recipes/rating.d.ts.map +1 -1
- package/dist/recipes/rating.js +4 -1
- package/dist/recipes/rating.js.map +1 -1
- package/dist/recipes/resizable.d.ts +4 -1
- package/dist/recipes/resizable.d.ts.map +1 -1
- package/dist/recipes/resizable.js +19 -2
- package/dist/recipes/resizable.js.map +1 -1
- package/dist/recipes/scrollArea.d.ts +7 -1
- package/dist/recipes/scrollArea.d.ts.map +1 -1
- package/dist/recipes/scrollArea.js +26 -17
- package/dist/recipes/scrollArea.js.map +1 -1
- package/dist/recipes/searchField.d.ts +41 -0
- package/dist/recipes/searchField.d.ts.map +1 -0
- package/dist/recipes/searchField.js +96 -0
- package/dist/recipes/searchField.js.map +1 -0
- package/dist/recipes/segmented.d.ts +3 -2
- package/dist/recipes/segmented.d.ts.map +1 -1
- package/dist/recipes/segmented.js +9 -5
- package/dist/recipes/segmented.js.map +1 -1
- package/dist/recipes/select.d.ts +3 -0
- package/dist/recipes/select.d.ts.map +1 -1
- package/dist/recipes/select.js +3 -3
- package/dist/recipes/select.js.map +1 -1
- package/dist/recipes/sheet.d.ts +16 -3
- package/dist/recipes/sheet.d.ts.map +1 -1
- package/dist/recipes/sheet.js +29 -10
- package/dist/recipes/sheet.js.map +1 -1
- package/dist/recipes/sidebar.d.ts +2 -1
- package/dist/recipes/sidebar.d.ts.map +1 -1
- package/dist/recipes/sidebar.js +8 -1
- package/dist/recipes/sidebar.js.map +1 -1
- package/dist/recipes/signaturePad.d.ts +3 -1
- package/dist/recipes/signaturePad.d.ts.map +1 -1
- package/dist/recipes/signaturePad.js +1 -0
- package/dist/recipes/signaturePad.js.map +1 -1
- package/dist/recipes/skeleton.d.ts.map +1 -1
- package/dist/recipes/skeleton.js +5 -5
- package/dist/recipes/skeleton.js.map +1 -1
- package/dist/recipes/slider.d.ts +4 -3
- package/dist/recipes/slider.d.ts.map +1 -1
- package/dist/recipes/slider.js +8 -0
- package/dist/recipes/slider.js.map +1 -1
- package/dist/recipes/spinner.d.ts +12 -0
- package/dist/recipes/spinner.d.ts.map +1 -1
- package/dist/recipes/spinner.js +5 -1
- package/dist/recipes/spinner.js.map +1 -1
- package/dist/recipes/steps.d.ts +14 -1
- package/dist/recipes/steps.d.ts.map +1 -1
- package/dist/recipes/steps.js +43 -1
- package/dist/recipes/steps.js.map +1 -1
- package/dist/recipes/table.d.ts +23 -2
- package/dist/recipes/table.d.ts.map +1 -1
- package/dist/recipes/table.js +30 -2
- package/dist/recipes/table.js.map +1 -1
- package/dist/recipes/tabs.d.ts +3 -2
- package/dist/recipes/tabs.d.ts.map +1 -1
- package/dist/recipes/tabs.js +9 -1
- package/dist/recipes/tabs.js.map +1 -1
- package/dist/recipes/tagsInput.d.ts +18 -1
- package/dist/recipes/tagsInput.d.ts.map +1 -1
- package/dist/recipes/tagsInput.js +46 -15
- package/dist/recipes/tagsInput.js.map +1 -1
- package/dist/recipes/thinkingSteps.d.ts +5 -2
- package/dist/recipes/thinkingSteps.d.ts.map +1 -1
- package/dist/recipes/thinkingSteps.js +26 -2
- package/dist/recipes/thinkingSteps.js.map +1 -1
- package/dist/recipes/timer.js +1 -1
- package/dist/recipes/timer.js.map +1 -1
- package/dist/recipes/toast.d.ts +10 -1
- package/dist/recipes/toast.d.ts.map +1 -1
- package/dist/recipes/toast.js +46 -3
- package/dist/recipes/toast.js.map +1 -1
- package/dist/recipes/toggle.d.ts +46 -4
- package/dist/recipes/toggle.d.ts.map +1 -1
- package/dist/recipes/toggle.js +92 -10
- package/dist/recipes/toggle.js.map +1 -1
- package/dist/recipes/toolbar.d.ts +18 -0
- package/dist/recipes/toolbar.d.ts.map +1 -0
- package/dist/recipes/toolbar.js +53 -0
- package/dist/recipes/toolbar.js.map +1 -0
- package/dist/recipes/tooltip.d.ts.map +1 -1
- package/dist/recipes/tooltip.js.map +1 -1
- package/dist/recipes/tour.js +1 -1
- package/dist/recipes/tour.js.map +1 -1
- package/dist/recipes/treeView.d.ts +4 -2
- package/dist/recipes/treeView.d.ts.map +1 -1
- package/dist/recipes/treeView.js +14 -1
- package/dist/recipes/treeView.js.map +1 -1
- package/dist/recipes/typography.d.ts +1 -49
- package/dist/recipes/typography.d.ts.map +1 -1
- package/dist/recipes/typography.js +66 -65
- package/dist/recipes/typography.js.map +1 -1
- package/dist/recipes/virtualList.js +1 -1
- package/dist/recipes/virtualList.js.map +1 -1
- package/dist/resizable.d.ts +31 -2
- package/dist/resizable.d.ts.map +1 -1
- package/dist/resizable.js +75 -24
- package/dist/resizable.js.map +1 -1
- package/dist/rowContent.d.ts +16 -0
- package/dist/rowContent.d.ts.map +1 -0
- package/dist/rowContent.js +1 -0
- package/dist/scrollArea/overlayBars.d.ts +8 -0
- package/dist/scrollArea/overlayBars.d.ts.map +1 -0
- package/dist/scrollArea/overlayBars.js +17 -0
- package/dist/scrollArea/overlayBars.js.map +1 -0
- package/dist/scrollArea/slots.d.ts +12 -0
- package/dist/scrollArea/slots.d.ts.map +1 -0
- package/dist/scrollArea/slots.js +18 -0
- package/dist/scrollArea/slots.js.map +1 -0
- package/dist/scrollArea.d.ts +27 -17
- package/dist/scrollArea.d.ts.map +1 -1
- package/dist/scrollArea.js +11 -26
- package/dist/scrollArea.js.map +1 -1
- package/dist/searchField.d.ts +102 -0
- package/dist/searchField.d.ts.map +1 -0
- package/dist/searchField.js +117 -0
- package/dist/searchField.js.map +1 -0
- package/dist/segmented/fluid.d.ts +9 -0
- package/dist/segmented/fluid.d.ts.map +1 -0
- package/dist/segmented/fluid.js +36 -0
- package/dist/segmented/fluid.js.map +1 -0
- package/dist/segmented/slots.d.ts +28 -0
- package/dist/segmented/slots.d.ts.map +1 -0
- package/dist/segmented/slots.js +52 -0
- package/dist/segmented/slots.js.map +1 -0
- package/dist/segmented.d.ts +46 -40
- package/dist/segmented.d.ts.map +1 -1
- package/dist/segmented.js +78 -77
- package/dist/segmented.js.map +1 -1
- package/dist/select/slots.d.ts +17 -0
- package/dist/select/slots.d.ts.map +1 -0
- package/dist/select/slots.js +29 -0
- package/dist/select/slots.js.map +1 -0
- package/dist/select/view.d.ts +51 -0
- package/dist/select/view.d.ts.map +1 -0
- package/dist/select/view.js +53 -0
- package/dist/select/view.js.map +1 -0
- package/dist/select.d.ts +4 -12
- package/dist/select.d.ts.map +1 -1
- package/dist/select.js +4 -22
- package/dist/select.js.map +1 -1
- package/dist/sheet.d.ts +21 -27
- package/dist/sheet.d.ts.map +1 -1
- package/dist/sheet.js +53 -35
- package/dist/sheet.js.map +1 -1
- package/dist/sidebar/fluid.d.ts +9 -0
- package/dist/sidebar/fluid.d.ts.map +1 -0
- package/dist/sidebar/fluid.js +28 -0
- package/dist/sidebar/fluid.js.map +1 -0
- package/dist/sidebar/slots.d.ts +44 -0
- package/dist/sidebar/slots.d.ts.map +1 -0
- package/dist/sidebar/slots.js +70 -0
- package/dist/sidebar/slots.js.map +1 -0
- package/dist/sidebar.d.ts +30 -82
- package/dist/sidebar.d.ts.map +1 -1
- package/dist/sidebar.js +53 -133
- package/dist/sidebar.js.map +1 -1
- package/dist/signaturePad.d.ts +66 -7
- package/dist/signaturePad.d.ts.map +1 -1
- package/dist/signaturePad.js +85 -18
- package/dist/signaturePad.js.map +1 -1
- package/dist/skeleton.d.ts +29 -5
- package/dist/skeleton.d.ts.map +1 -1
- package/dist/skeleton.js +24 -5
- package/dist/skeleton.js.map +1 -1
- package/dist/slider.d.ts +54 -9
- package/dist/slider.d.ts.map +1 -1
- package/dist/slider.js +125 -61
- package/dist/slider.js.map +1 -1
- package/dist/spinner.d.ts +1 -1
- package/dist/spinner.js +1 -1
- package/dist/spinner.js.map +1 -1
- package/dist/splitter.d.ts +27 -0
- package/dist/splitter.d.ts.map +1 -0
- package/dist/splitter.js +30 -0
- package/dist/splitter.js.map +1 -0
- package/dist/steps.d.ts +41 -0
- package/dist/steps.d.ts.map +1 -1
- package/dist/steps.js +35 -4
- package/dist/steps.js.map +1 -1
- package/dist/swipe.d.ts +26 -0
- package/dist/swipe.d.ts.map +1 -0
- package/dist/swipe.js +29 -0
- package/dist/swipe.js.map +1 -0
- package/dist/switch/draggable.d.ts +11 -0
- package/dist/switch/draggable.d.ts.map +1 -0
- package/dist/switch/draggable.js +144 -0
- package/dist/switch/draggable.js.map +1 -0
- package/dist/switch/slots.d.ts +16 -0
- package/dist/switch/slots.d.ts.map +1 -0
- package/dist/switch/slots.js +35 -0
- package/dist/switch/slots.js.map +1 -0
- package/dist/switch/view.d.ts +50 -0
- package/dist/switch/view.d.ts.map +1 -0
- package/dist/switch/view.js +49 -0
- package/dist/switch/view.js.map +1 -0
- package/dist/switch.d.ts +5 -19
- package/dist/switch.d.ts.map +1 -1
- package/dist/switch.js +5 -163
- package/dist/switch.js.map +1 -1
- package/dist/table/checkboxes.d.ts +10 -0
- package/dist/table/checkboxes.d.ts.map +1 -0
- package/dist/table/checkboxes.js +18 -0
- package/dist/table/checkboxes.js.map +1 -0
- package/dist/table/fluid.d.ts +10 -0
- package/dist/table/fluid.d.ts.map +1 -0
- package/dist/table/fluid.js +30 -0
- package/dist/table/fluid.js.map +1 -0
- package/dist/table.d.ts +102 -30
- package/dist/table.d.ts.map +1 -1
- package/dist/table.js +57 -39
- package/dist/table.js.map +1 -1
- package/dist/tabs/fluid.d.ts +10 -0
- package/dist/tabs/fluid.d.ts.map +1 -0
- package/dist/tabs/fluid.js +37 -0
- package/dist/tabs/fluid.js.map +1 -0
- package/dist/tabs/readingKeys.d.ts +11 -0
- package/dist/tabs/readingKeys.d.ts.map +1 -0
- package/dist/tabs/readingKeys.js +20 -0
- package/dist/tabs/readingKeys.js.map +1 -0
- package/dist/tabs/slots.d.ts +31 -0
- package/dist/tabs/slots.d.ts.map +1 -0
- package/dist/tabs/slots.js +52 -0
- package/dist/tabs/slots.js.map +1 -0
- package/dist/tabs.d.ts +73 -46
- package/dist/tabs.d.ts.map +1 -1
- package/dist/tabs.js +80 -99
- package/dist/tabs.js.map +1 -1
- package/dist/tagsInput.d.ts +83 -15
- package/dist/tagsInput.d.ts.map +1 -1
- package/dist/tagsInput.js +206 -47
- package/dist/tagsInput.js.map +1 -1
- package/dist/textarea.d.ts +13 -1
- package/dist/textarea.d.ts.map +1 -1
- package/dist/textarea.js +19 -8
- package/dist/textarea.js.map +1 -1
- package/dist/thinkingIndicator.d.ts +13 -0
- package/dist/thinkingIndicator.d.ts.map +1 -1
- package/dist/thinkingIndicator.js +8 -1
- package/dist/thinkingIndicator.js.map +1 -1
- package/dist/thinkingSteps/state.d.ts +44 -0
- package/dist/thinkingSteps/state.d.ts.map +1 -0
- package/dist/thinkingSteps/state.js +56 -0
- package/dist/thinkingSteps/state.js.map +1 -0
- package/dist/thinkingSteps.d.ts +73 -15
- package/dist/thinkingSteps.d.ts.map +1 -1
- package/dist/thinkingSteps.js +60 -30
- package/dist/thinkingSteps.js.map +1 -1
- package/dist/timer.d.ts +19 -3
- package/dist/timer.d.ts.map +1 -1
- package/dist/timer.js +13 -6
- package/dist/timer.js.map +1 -1
- package/dist/toast/keepFocus.d.ts +10 -0
- package/dist/toast/keepFocus.d.ts.map +1 -0
- package/dist/toast/keepFocus.js +30 -0
- package/dist/toast/keepFocus.js.map +1 -0
- package/dist/toast/slots.d.ts +36 -0
- package/dist/toast/slots.d.ts.map +1 -0
- package/dist/toast/slots.js +61 -0
- package/dist/toast/slots.js.map +1 -0
- package/dist/toast.d.ts +50 -37
- package/dist/toast.d.ts.map +1 -1
- package/dist/toast.js +64 -69
- package/dist/toast.js.map +1 -1
- package/dist/toastView.d.ts +77 -0
- package/dist/toastView.d.ts.map +1 -1
- package/dist/toastView.js +15 -1
- package/dist/toastView.js.map +1 -1
- package/dist/toggleRow.d.ts +41 -0
- package/dist/toggleRow.d.ts.map +1 -0
- package/dist/toggleRow.js +41 -0
- package/dist/toggleRow.js.map +1 -0
- package/dist/toolbar.d.ts +149 -0
- package/dist/toolbar.d.ts.map +1 -0
- package/dist/toolbar.js +205 -0
- package/dist/toolbar.js.map +1 -0
- package/dist/tour/advanceOnClick.d.ts +14 -0
- package/dist/tour/advanceOnClick.d.ts.map +1 -0
- package/dist/tour/advanceOnClick.js +27 -0
- package/dist/tour/advanceOnClick.js.map +1 -0
- package/dist/tour/focusReturn.d.ts +10 -0
- package/dist/tour/focusReturn.d.ts.map +1 -0
- package/dist/tour/focusReturn.js +19 -0
- package/dist/tour/focusReturn.js.map +1 -0
- package/dist/tour/message.d.ts +20 -0
- package/dist/tour/message.d.ts.map +1 -0
- package/dist/tour/message.js +21 -0
- package/dist/tour/message.js.map +1 -0
- package/dist/tour/slots.d.ts +21 -0
- package/dist/tour/slots.d.ts.map +1 -0
- package/dist/tour/slots.js +40 -0
- package/dist/tour/slots.js.map +1 -0
- package/dist/tour.d.ts +84 -103
- package/dist/tour.d.ts.map +1 -1
- package/dist/tour.js +103 -151
- package/dist/tour.js.map +1 -1
- package/dist/treeView/fluid.d.ts +8 -0
- package/dist/treeView/fluid.d.ts.map +1 -0
- package/dist/treeView/fluid.js +24 -0
- package/dist/treeView/fluid.js.map +1 -0
- package/dist/treeView/slots.d.ts +24 -0
- package/dist/treeView/slots.d.ts.map +1 -0
- package/dist/treeView/slots.js +53 -0
- package/dist/treeView/slots.js.map +1 -0
- package/dist/treeView.d.ts +61 -50
- package/dist/treeView.d.ts.map +1 -1
- package/dist/treeView.js +102 -96
- package/dist/treeView.js.map +1 -1
- package/dist/typography.d.ts +14 -6
- package/dist/typography.d.ts.map +1 -1
- package/dist/typography.js +10 -9
- package/dist/typography.js.map +1 -1
- package/dist/virtualList/overlayBars.d.ts +8 -0
- package/dist/virtualList/overlayBars.d.ts.map +1 -0
- package/dist/virtualList/overlayBars.js +17 -0
- package/dist/virtualList/overlayBars.js.map +1 -0
- package/dist/virtualList/slots.d.ts +13 -0
- package/dist/virtualList/slots.d.ts.map +1 -0
- package/dist/virtualList/slots.js +16 -0
- package/dist/virtualList/slots.js.map +1 -0
- package/dist/virtualList.d.ts +4 -28
- package/dist/virtualList.d.ts.map +1 -1
- package/dist/virtualList.js +3 -32
- package/dist/virtualList.js.map +1 -1
- package/dist/windowList.d.ts +76 -6
- package/dist/windowList.d.ts.map +1 -1
- package/dist/windowList.js +319 -32
- package/dist/windowList.js.map +1 -1
- package/dist/words.d.ts +16 -0
- package/dist/words.d.ts.map +1 -0
- package/dist/words.js +27 -0
- package/dist/words.js.map +1 -0
- package/package.json +11 -9
package/README.md
CHANGED
|
@@ -1,43 +1,35 @@
|
|
|
1
1
|
# `foldkit-mixins-ui`
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
- **Components with a small Model of their own**: Menu, Menubar, Toast,
|
|
34
|
-
Sheet, Picker, WindowList, Drawer, TagsInput, TreeView, Carousel, Resizable, ColorPicker, InputCopy,
|
|
35
|
-
MessageScroller, Questionnaire, AngleSlider, Timer, Marquee, ImageCropper,
|
|
36
|
-
SignaturePad, Chart, CascadeSelect, FloatingPanel and Tour.
|
|
37
|
-
The Model holds interaction state only (what is open, a drag, a countdown,
|
|
38
|
-
a draft), and the application keeps it and folds it with the component's
|
|
39
|
-
`update`, as it folds an `@foldkit/ui` Submodel. The value chosen stays
|
|
40
|
-
the application's.
|
|
3
|
+
The widget catalog of Foldkit Plus: about ninety styled, accessible widgets
|
|
4
|
+
(buttons, fields, menus, dialogs, tables, charts, a chat vocabulary) in two
|
|
5
|
+
families. **Adapters** take a component [`@foldkit/ui`](https://www.npmjs.com/package/@foldkit/ui)
|
|
6
|
+
already owns, name its attribute bundles as typed [`foldkit-mixins`](../mixins)
|
|
7
|
+
Slots, and run the Mixins resolver over them, so a caller styles or decorates the
|
|
8
|
+
component without copying its markup or merging attribute arrays by hand.
|
|
9
|
+
**Views and components** are this package's own, where upstream has none. A
|
|
10
|
+
recipe (`Recipes.X`) gives either family a look from the theme's tokens.
|
|
11
|
+
|
|
12
|
+
Every value belongs to the application's Model: what is chosen, typed, checked
|
|
13
|
+
or sorted. A widget's `view` is a pure function from those values to markup. The
|
|
14
|
+
few widgets that keep a small Model of their own hold interaction state only
|
|
15
|
+
(what is open, a drag, a countdown, a draft); the application places that Model
|
|
16
|
+
and folds it with the widget's `update`, as it folds an `@foldkit/ui` Submodel.
|
|
17
|
+
|
|
18
|
+
A widget's `view` also reads nothing from the environment (no `window`,
|
|
19
|
+
`navigator`, feature test, clock or default locale): a server and a browser must
|
|
20
|
+
draw the same markup from the same Model, or a server-rendered page is rebuilt
|
|
21
|
+
when it takes over. A fact about the environment, such as whether the browser has
|
|
22
|
+
an eyedropper, is an input the application keeps in its Model, read once in `init`
|
|
23
|
+
or by a Command after hydration (see [ColorPicker](#colorpicker)).
|
|
24
|
+
|
|
25
|
+
- `@foldkit/ui` owns component state, accessibility behavior and base attributes.
|
|
26
|
+
- `foldkit-mixins` owns Slot, Style and Behavior and the resolver that merges them
|
|
27
|
+
safely.
|
|
28
|
+
- `foldkit-primitives` owns the interaction primitives widgets compose (focus
|
|
29
|
+
recovery, roving tab stops, drags, scroll bars, clipboard).
|
|
30
|
+
- `foldkit-mixins-ui` names the bundles as Slots, draws the widgets that have no
|
|
31
|
+
upstream, and ships their recipes and accessibility patterns.
|
|
32
|
+
- The application owns the values, and every transition of them.
|
|
41
33
|
|
|
42
34
|
Every shipped recipe is on the website's
|
|
43
35
|
[component pages](https://foldkit-plus.pages.dev/components), each with its
|
|
@@ -45,64 +37,108 @@ variants to pick and the code that draws it, and
|
|
|
45
37
|
[Create a theme](https://foldkit-plus.pages.dev/create) turns the theme's knobs
|
|
46
38
|
over all of them at once.
|
|
47
39
|
|
|
48
|
-
##
|
|
49
|
-
|
|
50
|
-
An `@foldkit/ui` component commonly hands its caller one or more attribute
|
|
51
|
-
bundles:
|
|
40
|
+
## When to use it
|
|
52
41
|
|
|
53
|
-
|
|
54
|
-
roles
|
|
55
|
-
aria-*
|
|
56
|
-
tabindex
|
|
57
|
-
event handlers
|
|
58
|
-
ChildAttributes
|
|
59
|
-
...
|
|
60
|
-
```
|
|
42
|
+
Use this package when:
|
|
61
43
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
44
|
+
- you want a styled, accessible widget from the catalog below;
|
|
45
|
+
- you already use `@foldkit/ui` and want reusable styling, ARIA decoration,
|
|
46
|
+
analytics or element-level behavior around one of its components, through its
|
|
47
|
+
consumer render seam (`toView`);
|
|
48
|
+
- you want conflicts diagnosed rather than resolved by attribute order.
|
|
65
49
|
|
|
66
|
-
|
|
50
|
+
It does not own application state. A Mixins `Behavior` contributes
|
|
51
|
+
element-level attributes and optional Mount behavior; it is not a hidden state
|
|
52
|
+
container. If you are building your own view rather than adapting a widget,
|
|
53
|
+
publish Slots directly with [`foldkit-mixins`](../mixins); for Slot / Style /
|
|
54
|
+
Behavior itself, read [Inside-out view composition](../../docs/mixins.md) first.
|
|
55
|
+
[Authoring components](../../docs/authoring-components.md) builds such a view from
|
|
56
|
+
primitives step by step, and lists what a widget for this catalog must carry.
|
|
67
57
|
|
|
68
|
-
|
|
69
|
-
@foldkit/ui component
|
|
70
|
-
|
|
|
71
|
-
| attribute bundles
|
|
72
|
-
v
|
|
73
|
-
foldkit-mixins-ui Slots
|
|
74
|
-
|
|
|
75
|
-
| Style + Behavior
|
|
76
|
-
v
|
|
77
|
-
foldkit-mixins resolver
|
|
78
|
-
|
|
|
79
|
-
v
|
|
80
|
-
component-owned attrs + safe additions
|
|
81
|
-
```
|
|
58
|
+
## The mental model
|
|
82
59
|
|
|
83
|
-
|
|
84
|
-
|
|
60
|
+
An `@foldkit/ui` component hands its caller attribute bundles (roles, `aria-*`,
|
|
61
|
+
`tabindex`, event handlers, `ChildAttribute`s). A raw array is not a public
|
|
62
|
+
customization contract: a caller can add a second `OnClick`, replace something
|
|
63
|
+
structural, or repeat merge code at every call site. `foldkit-mixins-ui` gives
|
|
64
|
+
each bundle a stable Slot name. Style and Behavior attach to those Slots, and the
|
|
65
|
+
`foldkit-mixins` resolver merges them into the component's own attributes plus the
|
|
66
|
+
caller's safe additions.
|
|
67
|
+
|
|
68
|
+
The component keeps control of the component, and callers get a typed place to
|
|
69
|
+
extend it. A view of this package's own draws its markup through the same Slots,
|
|
70
|
+
so one extension contract covers both families.
|
|
71
|
+
|
|
72
|
+
## Look, state, drawing, features: one factory each
|
|
73
|
+
|
|
74
|
+
A variation of a widget is a call with options, never a copied file. A widget
|
|
75
|
+
is made of four kinds of fact, and each has one place it is given:
|
|
76
|
+
|
|
77
|
+
- **Look** is CSS over fixed markup. `Recipes.X(selection)` picks values on
|
|
78
|
+
axes, `.extend` adjusts them and `.add` gives a recipe an axis or a value it
|
|
79
|
+
lacks ([Recipes](#recipes)).
|
|
80
|
+
- **State** is a Model and the Messages that change it, and it is the
|
|
81
|
+
application's: `X.init` and `X.update` for the widgets that keep interaction
|
|
82
|
+
state, folded by hand or placed as `Bundles.X`. The value a user chose stays
|
|
83
|
+
in the application's Model, unless its type is the widget's own (a
|
|
84
|
+
Calendar's selection).
|
|
85
|
+
- **Drawing** is markup, ARIA, events and words. `X.view(options, h)` draws,
|
|
86
|
+
and `X.configure({ base, presets })` returns a `view` with the options that
|
|
87
|
+
never change at a call site given once. Fixed text is `words`, an object of
|
|
88
|
+
strings with `{blanks}` (`'Remove {tag}'`), never a function.
|
|
89
|
+
- **Features** are code most pages never need: another widget, a Behavior
|
|
90
|
+
with a Mount, a second way to choose. A feature is a value the application
|
|
91
|
+
imports and passes (`fluid: Table.fluid`, `kind: Chart.bars`,
|
|
92
|
+
`choice: Combobox.many(items)`), so a page that never names it never ships
|
|
93
|
+
it. A boolean that switches code on is the one thing an option is not.
|
|
94
|
+
|
|
95
|
+
An option is therefore one of three things: **data** (text, a Message, an
|
|
96
|
+
`Html` you drew, a function you wrote), **a passed value** (a feature, above),
|
|
97
|
+
or **composition** (a widget with state of its own, placed beside this one and
|
|
98
|
+
drawn into a slot option such as `aside`, `footer`, `trailing` or `content`).
|
|
85
99
|
|
|
86
|
-
|
|
100
|
+
```ts standalone
|
|
101
|
+
import type { Html, HtmlBuilder } from 'foldkit/html'
|
|
102
|
+
import { defineMessageUnion } from 'foldkit/message'
|
|
103
|
+
import { Style } from 'foldkit-mixins'
|
|
104
|
+
import { Recipes, Table, TableSlots } from 'foldkit-mixins-ui'
|
|
87
105
|
|
|
88
|
-
|
|
106
|
+
const Message = defineMessageUnion({ Noop: {} })
|
|
107
|
+
type Message = typeof Message.Type
|
|
89
108
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
- you want conflicts to be diagnosed rather than resolved by attribute order.
|
|
109
|
+
interface Product {
|
|
110
|
+
readonly name: string
|
|
111
|
+
readonly price: string
|
|
112
|
+
}
|
|
95
113
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
element-level attributes and optional Mount behavior; it is not a hidden state
|
|
99
|
-
container.
|
|
114
|
+
// Look: compiled once, at module scope.
|
|
115
|
+
const ProductsStyle = Style.forSlots(TableSlots)(Recipes.Table({ density: 'compact' }))
|
|
100
116
|
|
|
101
|
-
|
|
102
|
-
|
|
117
|
+
// Drawing: `fluid` is a passed value, `words` is text with blanks.
|
|
118
|
+
export const products = (rows: ReadonlyArray<Product>, h: HtmlBuilder<Message>): Html =>
|
|
119
|
+
Table.view(
|
|
120
|
+
{
|
|
121
|
+
columns: [
|
|
122
|
+
{ header: 'Product', rowHeader: true, value: row => row.name },
|
|
123
|
+
{ header: 'Price', numeric: true, value: row => row.price },
|
|
124
|
+
],
|
|
125
|
+
rows,
|
|
126
|
+
rowKey: row => row.name,
|
|
127
|
+
fluid: Table.fluid,
|
|
128
|
+
words: { selectAll: 'Choose every product' },
|
|
129
|
+
style: ProductsStyle,
|
|
130
|
+
},
|
|
131
|
+
h,
|
|
132
|
+
)
|
|
133
|
+
```
|
|
103
134
|
|
|
104
|
-
|
|
105
|
-
|
|
135
|
+
`Table.configure({ base, presets })` would state `style`, `fluid` and `words`
|
|
136
|
+
once and leave `columns` and `rows` to each call. About fifty widgets have a
|
|
137
|
+
`configure`, and about forty keep state that `Bundles` places; Dialog,
|
|
138
|
+
Popover, Tooltip, HoverIntent and FileDrop stay adapters over `@foldkit/ui`,
|
|
139
|
+
because what they hold is your own content, and have a Bundle for their state
|
|
140
|
+
only. [One factory for each part](#one-factory-for-each-part) shows each with
|
|
141
|
+
code.
|
|
106
142
|
|
|
107
143
|
## Install
|
|
108
144
|
|
|
@@ -110,14 +146,14 @@ composition](../../docs/mixins.md) first.
|
|
|
110
146
|
pnpm add foldkit-mixins foldkit-mixins-ui foldkit-primitives @foldkit/ui
|
|
111
147
|
```
|
|
112
148
|
|
|
113
|
-
`foldkit`, `effect`, `foldkit-mixins`, `foldkit-primitives` and `@foldkit/ui` are peer dependencies.
|
|
149
|
+
`foldkit`, `effect`, `foldkit-mixins`, `foldkit-primitives` and `@foldkit/ui` are peer dependencies. So is `foldkit-bundle`, which only `Bundles` imports: add it when you place one ([State: fold it by hand, or place a Bundle](#state-fold-it-by-hand-or-place-a-bundle)).
|
|
114
150
|
|
|
115
151
|
## Sixty seconds: style a Button without copying it
|
|
116
152
|
|
|
117
153
|
Start with a normal `@foldkit/ui` Button. The adapter publishes its consumer
|
|
118
154
|
attribute bundle as the `button` Slot.
|
|
119
155
|
|
|
120
|
-
```ts
|
|
156
|
+
```ts standalone
|
|
121
157
|
import type { HtmlBuilder } from 'foldkit/html'
|
|
122
158
|
import { defineMessageUnion } from 'foldkit/message'
|
|
123
159
|
import * as UiButton from '@foldkit/ui/button'
|
|
@@ -147,39 +183,21 @@ The important line is:
|
|
|
147
183
|
toView: Button.toView(mixins, { h }, draw)
|
|
148
184
|
```
|
|
149
185
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
```text
|
|
153
|
-
attributes from @foldkit/ui
|
|
154
|
-
+
|
|
155
|
-
Style / Behavior mixins
|
|
156
|
-
|
|
|
157
|
-
v
|
|
158
|
-
Button.toView(...)
|
|
159
|
-
|
|
|
160
|
-
v
|
|
161
|
-
draw(resolved slot arrays)
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
The caller never copies Button's internal behavior and never has to know how to
|
|
165
|
-
merge its handlers/ARIA/structural attributes safely.
|
|
166
|
-
|
|
167
|
-
## Follow the click
|
|
186
|
+
`Button.toView(...)` takes the attributes from `@foldkit/ui` and your Style and
|
|
187
|
+
Behavior mixins, and calls `draw` with the resolved slot arrays.
|
|
168
188
|
|
|
169
189
|
`UiButton.view` builds the component's base attributes, including the click
|
|
170
190
|
Message, and calls `toView` with them. `Button.toView` applies the style to
|
|
171
191
|
those attributes and hands the result to `draw`, which puts it on the actual
|
|
172
|
-
element with `h.button`. Clicking emits `Saved` to the parent update.
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
`toView` performs no I/O and holds nothing: it is a pure function from the
|
|
177
|
-
component's bundles to your markup, run on every render.
|
|
192
|
+
element with `h.button`. Clicking emits `Saved` to the parent update. `toView`
|
|
193
|
+
performs no I/O and holds nothing: it is a pure function from the component's
|
|
194
|
+
bundles to your markup, run on every render, and the caller never copies the
|
|
195
|
+
button's behavior or merges its handlers and ARIA by hand.
|
|
178
196
|
|
|
179
|
-
Start by adding a class. Then add a non-conflicting attribute if needed.
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
197
|
+
Start by adding a class. Then add a non-conflicting attribute if needed. Do not
|
|
198
|
+
install another `OnClick` to intercept the component: the resolver rejects
|
|
199
|
+
competing event owners. Put every resolved bundle on its element, adding your
|
|
200
|
+
own attributes beside it where you need them:
|
|
183
201
|
|
|
184
202
|
```ts
|
|
185
203
|
import * as UiInput from '@foldkit/ui/input'
|
|
@@ -199,7 +217,9 @@ const zipInput = (h: HtmlBuilder<Message>) =>
|
|
|
199
217
|
)
|
|
200
218
|
```
|
|
201
219
|
|
|
202
|
-
##
|
|
220
|
+
## Core concepts
|
|
221
|
+
|
|
222
|
+
### `toView` and `resolve`
|
|
203
223
|
|
|
204
224
|
Every component adapter (all but Anchor, which is a Behavior) has both:
|
|
205
225
|
|
|
@@ -212,18 +232,15 @@ Adapter.resolve(attributes, mixins, { h, input? }) -> the resolved bundles
|
|
|
212
232
|
path. It fits a stateless component's `view` and a Submodel's `viewInputs`
|
|
213
233
|
alike. The Message type comes from `h`, and a Submodel's value type (a
|
|
214
234
|
RadioGroup's or Tabs' `Value`) from where the `toView` goes, so neither needs
|
|
215
|
-
writing out.
|
|
235
|
+
writing out. `input` is whatever attached Style/Behavior callbacks are allowed
|
|
236
|
+
to read (often a Surface's projected Model); leave it out when no Mixin reads one.
|
|
216
237
|
|
|
217
238
|
Every view takes the view's `h` last, as Foldkit's own views do. At runtime it
|
|
218
|
-
is the same builder everywhere; its type
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
deliver.
|
|
224
|
-
|
|
225
|
-
A button drawn as a button needs no `draw` at all. `Button.view` takes the
|
|
226
|
-
label, a style, and `@foldkit/ui`'s own config:
|
|
239
|
+
is the same builder everywhere; its type carries the Message the part of the app
|
|
240
|
+
being drawn can route (the root's, or a Submodel's own), so a handler built for
|
|
241
|
+
another part's Message is a compile error where it is written. Pass it down as a
|
|
242
|
+
parameter and never keep it: a builder kept and used in another frame builds
|
|
243
|
+
handlers that frame cannot deliver.
|
|
227
244
|
|
|
228
245
|
<!-- docs-check standalone
|
|
229
246
|
import { Schema } from 'effect'
|
|
@@ -275,6 +292,127 @@ declare const model: { readonly marks: ReadonlyArray<string> }
|
|
|
275
292
|
declare const iconUrl: (name: string) => string
|
|
276
293
|
-->
|
|
277
294
|
|
|
295
|
+
`resolve` is the seam underneath, for bundles already in hand: a view that
|
|
296
|
+
receives a Tabs `render` as its input, or a Calendar whose Mixins read the
|
|
297
|
+
mode it is showing, which is only known once the attributes arrive:
|
|
298
|
+
|
|
299
|
+
```ts
|
|
300
|
+
import type { CalendarAttributes } from '@foldkit/ui/calendar'
|
|
301
|
+
import { Calendar, CalendarSlots } from 'foldkit-mixins-ui'
|
|
302
|
+
|
|
303
|
+
const CalendarStyle = Style.forSlots(CalendarSlots)({
|
|
304
|
+
root: Style.whenInput<CalendarAttributes['_tag']>(mode => mode === 'Years', Style.class('years')),
|
|
305
|
+
})
|
|
306
|
+
|
|
307
|
+
const resolveCalendar = (attributes: CalendarAttributes, h: HtmlBuilder<Message>) =>
|
|
308
|
+
Calendar.resolve(attributes, [CalendarStyle.mixin], { input: attributes._tag, h })
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
`resolve` returns the shape the component passed to its render callback with
|
|
312
|
+
the published bundles resolved; values that are not Slots (`animatePanel`,
|
|
313
|
+
`isVisible`, `activeIndex`, `selectedValue`) pass through untouched. Each
|
|
314
|
+
adapter names what it returns (`ResolvedButton<Message>`, `ResolvedInput`,
|
|
315
|
+
`ResolvedDialog`, `ResolvedRadioGroup<Value, Message>`, `ResolvedTabs`,
|
|
316
|
+
`ResolvedCalendar`, `ResolvedMenu` with `ResolvedMenuGroup` and
|
|
317
|
+
`ResolvedMenuItem`, and so on), so a helper that draws part of a component is
|
|
318
|
+
typed without `ReturnType`. `ResolvedTextarea`'s `textarea` bundle is typed for
|
|
319
|
+
`h.textarea`, which refuses `InnerHTML`; the resolver refuses an `InnerHTML` from
|
|
320
|
+
any Mixin, so no cast is needed. Each adapter is both a namespace
|
|
321
|
+
(`Button.toView`, `Button.resolve`) and a flat Slot export (`ButtonSlots`).
|
|
322
|
+
|
|
323
|
+
### What the resolver protects
|
|
324
|
+
|
|
325
|
+
This package delegates merge semantics to `foldkit-mixins`; it does not
|
|
326
|
+
concatenate arrays. The resolver guarantees that:
|
|
327
|
+
|
|
328
|
+
- component/base attributes survive;
|
|
329
|
+
- `ChildAttribute`s survive by identity, preserving Submodel routing;
|
|
330
|
+
- classes are additive, and inline declarations merge by property;
|
|
331
|
+
- an event or scalar attribute has one owner, so a Behavior cannot silently
|
|
332
|
+
install a competing `OnClick` at a Slot whose component owns the click;
|
|
333
|
+
- structural attributes remain protected;
|
|
334
|
+
- conflicting ownership produces a `DiagnosticError`, never an accidental
|
|
335
|
+
second handler.
|
|
336
|
+
|
|
337
|
+
That is the main reason to use an adapter instead of another `className` or
|
|
338
|
+
`attributes` escape hatch.
|
|
339
|
+
|
|
340
|
+
### Submodel components remain Submodels
|
|
341
|
+
|
|
342
|
+
Dialog, Popover, Tooltip, Tabs, RadioGroup, Calendar and Menu publish
|
|
343
|
+
`ChildAttribute`s that carry the child state machine's dispatcher. The resolver
|
|
344
|
+
preserves them, so adapting the render seam does not flatten or bypass the child
|
|
345
|
+
boundary. Per-item components return structured groups rather than one flat
|
|
346
|
+
array, and the adapter keeps that shape: one Slot contribution applies to each
|
|
347
|
+
repeated item while every item's base attributes keep their own event ownership.
|
|
348
|
+
|
|
349
|
+
```text
|
|
350
|
+
Tabs -> { tablist, tabs, activeIndex }
|
|
351
|
+
RadioGroup -> { group, options, selectedValue, hiddenInput }
|
|
352
|
+
Calendar -> ResolvedDays | ResolvedMonths | ResolvedYears
|
|
353
|
+
Menu -> { wrapper, button, backdrop, items, scroll, groups, isVisible }
|
|
354
|
+
Toast -> { container, entries }
|
|
355
|
+
Listbox -> { wrapper, button, backdrop, items, scroll, groups, hiddenInputs, isVisible }
|
|
356
|
+
Combobox -> { wrapper, inputWrapper, input, toggleButton, backdrop, items, scroll, groups, hiddenInputs, isVisible }
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
## Finding a widget
|
|
360
|
+
|
|
361
|
+
| I need... | Use |
|
|
362
|
+
| --- | --- |
|
|
363
|
+
| a button, toggle button or icon button; a row of them | [Button](#buttons-actions-and-commands), ButtonGroup, [Toolbar](#toolbar) |
|
|
364
|
+
| a command palette | Command in a Dialog |
|
|
365
|
+
| a text field, a textarea, a password, a search box | [Input, Textarea](#text-and-number-fields), PasswordInput, [SearchField](#searchfield) |
|
|
366
|
+
| a number, a one-time code, tags, a copyable value | NumberField, OtpField, TagsInput, InputCopy |
|
|
367
|
+
| a file picker, a drop zone, files that are listed, checked, previewed and sent | [FileInput](#fileinput) (a native picker you own), FileDrop, [FileUpload](#fileupload) |
|
|
368
|
+
| on or off; one of a few; several of a few | Switch, Checkbox, CheckboxGroup, RadioGroup, Segmented |
|
|
369
|
+
| one from a long list; a path through nested options | Select, Listbox, Combobox, Picker, CascadeSelect |
|
|
370
|
+
| a number, a range, a rating, an angle, a color | Slider, NumberField, Rating, AngleSlider, ColorPicker |
|
|
371
|
+
| a date or a range of dates | Calendar, DatePicker |
|
|
372
|
+
| a dialog, a sheet, a docked drawer | [Dialog](#dialog) (with `focusReturn`), Sheet, Drawer |
|
|
373
|
+
| a popover, a tooltip, a hover card, a floating window, a guided tour | Popover, Tooltip, HoverIntent, FloatingPanel, Tour |
|
|
374
|
+
| a menu, a context menu, a menu bar | Menu, Menubar |
|
|
375
|
+
| tabs, site navigation, breadcrumbs, pages, a stepper | Tabs, Nav, Breadcrumb, Pagination, Steps |
|
|
376
|
+
| an app frame, a sidebar, an accordion, a tree | AppShell, Sidebar, Accordion, TreeView |
|
|
377
|
+
| a table, a card, a list row, an avatar | Table, Card, Item, Avatar |
|
|
378
|
+
| an alert, a toast, a progress bar, a loading state | Alert, Toast, Progress, Meter, Spinner, Skeleton |
|
|
379
|
+
| a very long list | VirtualList, WindowList |
|
|
380
|
+
| a chat | ChatMessage, MessageScroller, ThinkingIndicator, ThinkingSteps, Questionnaire |
|
|
381
|
+
| a widget's state placed in my Model without writing its fold | [`Bundles.X`](#state-fold-it-by-hand-or-place-a-bundle) |
|
|
382
|
+
| a widget's look, words and mixins stated once | [`X.configure`](#drawing-configure-once-call-with-what-differs), [`Recipes.X`](#recipes) |
|
|
383
|
+
| my own keyboard shortcut on a widget | [Application key routes](#application-key-routes) |
|
|
384
|
+
| focus that survives removing what had it | [Focus after removal](#focus-after-removal) |
|
|
385
|
+
| a form that submits natively | [Form participation](#form-participation) |
|
|
386
|
+
| a right-to-left page | [Right to left](#right-to-left) |
|
|
387
|
+
|
|
388
|
+
Each group below is a table (the widget, what it is and its call, its recipe
|
|
389
|
+
axes and Slots) and notes on the widgets whose behavior needs more than a line.
|
|
390
|
+
A row says `A small Model` where the widget keeps interaction state for the
|
|
391
|
+
application to place and fold with its `update`; the rest keep nothing. Every
|
|
392
|
+
view takes an optional `style` of its Slots and `mixins` beside it, and `h` last.
|
|
393
|
+
Style the Slots with the matching recipe ([Recipes](#recipes)); hide text with
|
|
394
|
+
`U.srOnly` from `foldkit-mixins/utilities`; name a control with
|
|
395
|
+
`FieldAssociation`, whose derived id `Label.view` takes.
|
|
396
|
+
|
|
397
|
+
Behavior shared by many widgets is described once, in [Mechanisms shared by many
|
|
398
|
+
widgets](#mechanisms-shared-by-many-widgets), and the rows link to it: application
|
|
399
|
+
key routes (`routes`), focus after removal, form participation (`name`),
|
|
400
|
+
right to left (`direction`), exits and reduced motion, the opt-in Mounts
|
|
401
|
+
(`fluid`, `overlayBars`) and the top layer.
|
|
402
|
+
|
|
403
|
+
## Buttons, actions and commands
|
|
404
|
+
|
|
405
|
+
| Widget | What it is | Recipe and Slots |
|
|
406
|
+
| --- | --- | --- |
|
|
407
|
+
| `Button` | Adapter over `@foldkit/ui`'s Button. `Button.view({ label, style, type?, disabled?, invalid?, busy?, pressed?, icon?, trailing?, description?, mark?, href?, external?, words?, onClick?, attributes?, mixins? }, h)`; `Button.toView` for your own `draw`. `disabled` writes `aria-disabled`, not `disabled`; `pressed` makes it a toggle (`aria-pressed`); an `icon` draws before the label, hidden from assistive technology. A button presses or it is a link: `href` draws an anchor and takes no `type` or `onClick`. | `tone`: `accent` (default), `neutral`, `danger`; `variant`: `solid` (default), `outline`, `ghost`, `primary`, `link`, `icon`; `size`: `xs`, `sm`, `md`, `lg`; `shape: 'square'`. Slots `button`, `icon`, `content`, `description`, `trailing`, `mark`. |
|
|
408
|
+
| `ButtonGroup` | `{ label, items, orientation?, separated? }`. A `role="group"` that joins its items: borders overlap by one and only the outer corners stay round. An item is the caller's button, field or Menu (a wrapper passes the corners to the face it holds), or a string drawn in the `text` box (a count, a field's prefix). `orientation: 'vertical'` stacks them; `separated` draws a rule on every seam, for solid buttons whose fills meet. `Segmented` is the control that selects. | `size` (`sm`, `md`, `lg`, for every item with no size of its own); `width: 'fill'` spans the container, a field taking what the buttons leave. Slots `root`, `separator`, `text`. |
|
|
409
|
+
| `Toolbar` | The APG's toolbar: one tab stop over controls you draw, the arrows along its orientation, Home and End. See [Toolbar](#toolbar). `Toolbar.view({ id, label, items, roving, onFocus, orientation?, direction?, loop?, disabled?, routes? }, h)`. | `size` is Button's ladder step, set on the toolbar. Slots `root`, `group`, `separator`. |
|
|
410
|
+
| `Command` | shadcn's Command and Fluid's CommandMenu: a search field over a list of grouped, filterable rows. `{ id, label, placeholder?, groups, query, onQuery, active, onActive, onRun, loading?, words?, page?, routes?, hints?, kbd? }`. `Command.configure({ base, presets })` fixes the placeholder, words, hints, `kbd`, style and mixins once. See [Command](#command). | `frame`: `card` (default) or `bare`, for inside a dialog. Slots `root`, `search`, `crumbs`, `crumb`, `input`, `list`, `group`, `heading`, `item`, `icon`, `text`, `label`, `description`, `shortcut`, `chevron`, `status`, `empty`, `loading`, `frame`, `bar`, `thumb`, `footer`, `hint`. |
|
|
411
|
+
| `Kbd` | `{ key }` names a key, as text or as a drawing (an arrow, a modifier's glyph; it carries its own label); `Kbd.combo({ keys, joiner? }, h)` draws several in one `kbd`. | No axis. Slots `key`, `combo`, `joiner`. |
|
|
412
|
+
|
|
413
|
+
A button drawn as a button needs no `draw` at all. `Button.view` takes the
|
|
414
|
+
label, a style, and `@foldkit/ui`'s own config:
|
|
415
|
+
|
|
278
416
|
```ts
|
|
279
417
|
import { Button } from 'foldkit-mixins-ui'
|
|
280
418
|
|
|
@@ -299,20 +437,163 @@ go.
|
|
|
299
437
|
`attributes: { button?, icon? }` adds what another component hands a slot,
|
|
300
438
|
before the mixins resolve, as `PasswordInput.view`'s do: a Dialog's
|
|
301
439
|
`initialFocus`, so the dialog opens on that button (`attributes: { button:
|
|
302
|
-
dialog.initialFocus }`). A class among them joins the style's, and an event
|
|
303
|
-
|
|
440
|
+
dialog.initialFocus }`). A class among them joins the style's, and an event or
|
|
441
|
+
attribute a mixin owns is a conflict. `Recipes.Button({ variant: 'icon' })`
|
|
442
|
+
shows the icon alone, the label still the button's name; `shape: 'square'` draws
|
|
443
|
+
any other variant as that square (an outlined icon button in a toolbar). A toggle
|
|
444
|
+
button, shadcn's Toggle, is a Button with `pressed`, and each variant has its on
|
|
445
|
+
look.
|
|
446
|
+
|
|
447
|
+
`trailing` draws after the label (a chevron, a count, a `Kbd.combo`); it is read as
|
|
448
|
+
drawn, so a decorative one carries its own `aria-hidden`. `description` is a second line
|
|
449
|
+
under the label, and both name the button. `mark` is a Badge or a dot on the button's
|
|
450
|
+
corner, on the end side whatever the writing direction. `invalid` writes `data-invalid` and
|
|
451
|
+
turns the button's colours to the danger tone: not `aria-invalid`, which a button's role
|
|
452
|
+
does not take, so the reason is text the application draws. `busy` writes `aria-busy` and
|
|
453
|
+
`data-busy`, and a press does nothing while it is on (a `type: 'submit'` button stops
|
|
454
|
+
submitting too); it stays focusable. There is no `loading` option that draws a spinner,
|
|
455
|
+
since that would put Spinner in every page that draws a button: compose
|
|
456
|
+
`icon: Spinner.view(...)`. `href` draws an anchor with the button's look; `external` opens
|
|
457
|
+
a new tab and says so (`words.external`, default `'Opens in a new tab'`), and a disabled
|
|
458
|
+
link has no `href`. `Recipes.Button({ variant: 'link' })` is the look of a link in running
|
|
459
|
+
text; `size: 'xs'` is a step below `sm`.
|
|
460
|
+
|
|
461
|
+
### Toolbar
|
|
462
|
+
|
|
463
|
+
A `Toolbar` is one tab stop over a row of controls you draw. It owns the keys
|
|
464
|
+
(the arrows along its orientation, Home and End) and hands each control the
|
|
465
|
+
attributes of its stop; you own which control holds the stop, so Tab comes back
|
|
466
|
+
to the control focused last, and you draw the controls. `Toolbar.view` draws
|
|
467
|
+
the toolbar and does no I/O; focus moves in the browser, and `onFocus` reports
|
|
468
|
+
where it went.
|
|
469
|
+
|
|
470
|
+
`items` are, in order, controls `{ id, disabled?, draw }`, where `draw`
|
|
471
|
+
receives `{ attributes, disabled }` and puts `attributes` (the id, the
|
|
472
|
+
`tabindex` and a focus report) on the one focusable element and draws it off when
|
|
473
|
+
`disabled`; groups `{ label, controls, disabled? }`, a named `role="group"`; and
|
|
474
|
+
the word `'separator'`, a rule between sets. `roving` is a placed
|
|
475
|
+
`RovingTabindex`'s slice (`{ current }`) and `onFocus(id)` is answered with its
|
|
476
|
+
`Focused`. A disabled control (its own, its group's, or the toolbar's) is skipped
|
|
477
|
+
by the arrows and never holds the tab stop; `Toolbar.controlId(toolbarId, id)` is
|
|
478
|
+
the id a control draws, for a Command that focuses it. A focused text field,
|
|
479
|
+
textarea, select or range keeps the keys it uses, so the arrows leave a text field
|
|
480
|
+
only from the edge they point at: place a field last, or leave it with Tab. A key
|
|
481
|
+
pressed in something the toolbar did not draw, such as a menu's rows, is left to
|
|
482
|
+
it.
|
|
483
|
+
|
|
484
|
+
```ts
|
|
485
|
+
import { Toolbar, ToolbarSlots } from 'foldkit-mixins-ui'
|
|
486
|
+
|
|
487
|
+
const BarModel = Schema.Struct({ stop: Schema.NullOr(Schema.String), bold: Schema.Boolean })
|
|
488
|
+
const BarMessage = defineMessageUnion({ Focused: { id: Schema.String }, ToggledBold: {} })
|
|
489
|
+
type BarMessage = typeof BarMessage.Type
|
|
304
490
|
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
491
|
+
const BarStyle = Style.forSlots(ToolbarSlots)(Recipes.Toolbar({}))
|
|
492
|
+
const ToolStyle = Style.forSlots(ButtonSlots)(
|
|
493
|
+
Recipes.Button({ tone: 'neutral', variant: 'outline' }),
|
|
494
|
+
)
|
|
309
495
|
|
|
310
|
-
|
|
311
|
-
|
|
496
|
+
const barView = (model: typeof BarModel.Type, h: HtmlBuilder<BarMessage>) =>
|
|
497
|
+
Toolbar.view(
|
|
498
|
+
{
|
|
499
|
+
id: 'format',
|
|
500
|
+
label: 'Formatting',
|
|
501
|
+
roving: { current: model.stop },
|
|
502
|
+
onFocus: id => BarMessage.Focused({ id }),
|
|
503
|
+
items: [
|
|
504
|
+
{
|
|
505
|
+
id: 'bold',
|
|
506
|
+
draw: control =>
|
|
507
|
+
Button.view(
|
|
508
|
+
{
|
|
509
|
+
label: 'Bold',
|
|
510
|
+
pressed: model.bold,
|
|
511
|
+
onClick: BarMessage.ToggledBold(),
|
|
512
|
+
attributes: { button: control.attributes },
|
|
513
|
+
style: ToolStyle,
|
|
514
|
+
},
|
|
515
|
+
h,
|
|
516
|
+
),
|
|
517
|
+
},
|
|
518
|
+
'separator',
|
|
519
|
+
{
|
|
520
|
+
id: 'link',
|
|
521
|
+
disabled: true,
|
|
522
|
+
draw: control =>
|
|
523
|
+
Button.view(
|
|
524
|
+
{
|
|
525
|
+
label: 'Link',
|
|
526
|
+
disabled: control.disabled,
|
|
527
|
+
attributes: { button: control.attributes },
|
|
528
|
+
style: ToolStyle,
|
|
529
|
+
},
|
|
530
|
+
h,
|
|
531
|
+
),
|
|
532
|
+
},
|
|
533
|
+
],
|
|
534
|
+
style: BarStyle,
|
|
535
|
+
},
|
|
536
|
+
h,
|
|
537
|
+
)
|
|
538
|
+
```
|
|
312
539
|
|
|
313
|
-
|
|
314
|
-
`
|
|
315
|
-
|
|
540
|
+
`roving` is the `{ current }` slice of a `RovingTabindex`: kept by hand here, or placed
|
|
541
|
+
as `Bundles.Toolbar` (`Bundle.withChild('bar', Bundles.Toolbar, { args: { current? } })`),
|
|
542
|
+
whose Model is passed as `roving` and whose Message `Toolbar.focused(wrap)` builds for
|
|
543
|
+
`onFocus`: `onFocus: Toolbar.focused(message => GotBar({ message }))`. Otherwise
|
|
544
|
+
`onFocus(id)` is answered by setting it. `Toolbar.configure({ base, presets })` returns a
|
|
545
|
+
`view` with `orientation`, `direction`, `loop` and the look given once, as every
|
|
546
|
+
`configure` does. `control.attributes` goes on the one focusable element, and `control.disabled`
|
|
547
|
+
says to draw it off: the arrows skip it. `routes` are
|
|
548
|
+
[application key routes](#application-key-routes) whose `input` is `undefined`.
|
|
549
|
+
|
|
550
|
+
### Command
|
|
551
|
+
|
|
552
|
+
The field points at the highlighted row through `aria-activedescendant`; ↑ and ↓
|
|
553
|
+
wrap through enabled rows, PageUp and PageDown move the highlight ten rows and
|
|
554
|
+
stop at the ends, Enter runs the highlighted one, and Home and End stay the
|
|
555
|
+
field's caret keys. Rows never re-sort, and a filtered-away highlight moves to
|
|
556
|
+
the first enabled row. A row is `{ value, label, description?, keywords?,
|
|
557
|
+
shortcut?, icon?, opensPage?, disabled? }`; a `shortcut` is a tuple of keys
|
|
558
|
+
(`['⌘', 'K']`) drawn as Kbd with `kbd` and reads left to right on a right-to-left
|
|
559
|
+
page. `page: { trail, onBack }` draws the pages stepped into as crumbs before the
|
|
560
|
+
field, and Backspace in an empty field sends `onBack`; a row with `opensPage` has
|
|
561
|
+
a chevron. `loading: true` says `words.loading` and marks the list
|
|
562
|
+
`aria-busy`, its rows still shown, and a list nothing matches says `words.empty`
|
|
563
|
+
(`Command.words` are the defaults, `Loading…` and `No results.`); `hints` are a
|
|
564
|
+
footer of keys.
|
|
565
|
+
|
|
566
|
+
`Command.hotkey(message)` is ⌘K or Ctrl+K anywhere, for an application to lift
|
|
567
|
+
with `Subscription.persistentEntry` and open its Dialog on; `Command.filtered(groups,
|
|
568
|
+
query)` is what a query leaves. `Command.keepActiveInView` beside the style
|
|
569
|
+
scrolls the highlighted row into view as the keys move it; like the other Mounts
|
|
570
|
+
that send no Message it is a mixin, off by default. The list stands in a `frame`
|
|
571
|
+
beside its bar, which `Command.overlayBars` drives (see [Overlay scroll
|
|
572
|
+
bars](#overlay-scroll-bars)). `routes` are [application key
|
|
573
|
+
routes](#application-key-routes) whose `handle` reads a `CommandKeyInput` of the
|
|
574
|
+
query, the highlighted row and the rows the keys step through.
|
|
575
|
+
|
|
576
|
+
## Text and number fields
|
|
577
|
+
|
|
578
|
+
| Widget | What it is | Recipe and Slots |
|
|
579
|
+
| --- | --- | --- |
|
|
580
|
+
| `Input` | Adapter over `@foldkit/ui`'s Input. `Input.view({ id, value, onInput, type?, placeholder?, name?, readOnly?, required?, autocomplete?, inputMode?, maxLength?, disabled?, invalid?, attributes?, style, label, description?, labelAside?, start?, end? }, h)` draws the field; with `draw` in place of `label` the application places the bundles; `Input.field` draws a whole field from a `FieldValidation.Field`. | `size`: `sm`, `md`, `lg`; `variant`: `outline` (default), `filled`, `ghost`, `underline`. Slots `input`, `label`, `description`, `root`, `header`, `labelAside`, `group`, `start`, `end`. |
|
|
581
|
+
| `Textarea` | `Textarea.view` takes the same and `rows`, `maxRows`, `maxLength`, `count`; `Textarea.field` is the whole field. | `size` and `variant` as Input's; `resize`: `auto` (default), `vertical`, `none`. Slots `textarea`, `label`, `description`, `count`, `frame`, `footer`, `meta`. |
|
|
582
|
+
| `PasswordInput` | `PasswordInput.view({ id, label, value, onInput, visible, onToggle, autocomplete?, description?, labelAside?, start?, end?, words?, invalid?, disabled?, name?, required?, attributes? }, h)`: a password field whose toggle (`aria-pressed`, `aria-controls`, one fixed name) shows it as text. `autocomplete` is `current-password` (default) or `new-password`; spellcheck and autocorrect stay off. `strength` is a gauge the app draws (`Meter.view(…, h)`) under the field, so a page with none ships no Meter; `requirements` are `{ label, met }[]` (`PasswordRequirement`), each read as met or not (`words.met`, `words.unmet`); `capsLock: { on, onKey }` says Caps Lock is on, politely, `onKey` given `capsLockOf(key, modifiers)` for each key (an `Option`). The application owns the text; the flag and the Caps Lock reading are the field's own small Model (`PasswordInput.init`, `update`, `Bundles.PasswordInput`), handed to the view by `...PasswordInput.controls(model, onMessage)`. `words`: `toggle`, `capsLock`, `met`, `unmet`. | `size` (`sm`, `md`, `lg`). Input's pieces in InputGroup's box; the eye is `Icons.glyph` by `aria-pressed`. Slots `root`, `label`, `header`, `labelAside`, `group`, `start`, `end`, `input`, `toggle`, `description`, `strength`, `requirements`, `requirement`, `requirementState`, `capsLock`. |
|
|
583
|
+
| `SearchField` | A native `type="search"` input named by `label`, with a clear button only while there is text. `SearchField.view({ id, label, value, onInput, clear?: { onClear, content? }, start?, end?, busy?, placeholder?, invalid?, disabled?, words?, routes?, style?, mixins? }, h)`. See [SearchField](#searchfield). | `size` and `variant` (`outline`, `filled`, `ghost`, `underline`) are Input's axes. One box (`group`) with a magnifier in `start` while it is empty, the clear button after the input (mirrored right to left), the browser's own cancel button hidden. Slots `root`, `group`, `start`, `end`, `input`, `clear`. |
|
|
584
|
+
| `NumberField` | The APG's editable spinbutton. `{ id, label, description?, value, onChange, min?, max?, step?, page?, locale?, name?, required?, disabled?, invalid?, readOnly?, start?, end?, words? }`, or `format` with `parse` in place of `locale`. `value` is an `Option<number>`: none is an empty field (no `aria-valuenow`, the steppers start from the bounds), and clearing the text sends `onChange(Option.none())`. `NumberField.parseNumber(text, locale?)` reads text as that locale writes a number; `NumberField.settled(value, bounds)` clamps onto the step. | `steppers`: `split` (default: a button at each side of the number), `end` (both after it) or `none`. Slots `root`, `label`, `group`, `start`, `end`, `input`, `decrement`, `increment`, `description`. `invalid` draws the error edge and marks the input; `readOnly` leaves it readable and selectable with its steppers disabled; `words` (`decrease`, `increase`) names the steppers; `start` and `end` go around the number inside the box. |
|
|
585
|
+
| `OtpField` | shadcn's input-otp: one real input (`autocomplete="one-time-code"`, paste and Backspace the browser's) over cells that mirror it, the next marked `data-next`. `{ id?, name?, label, value, onChange, length?, pattern?, groups?, mask?, disabled?, readOnly?, invalid? }` (`mask: true` makes the input a password field and shows a dot in each filled cell, or the string given); `OtpField.kept(text, length, pattern)` filters a code. | No axis. Slots `root`, `input`, `group`, `cell`, `separator`. |
|
|
586
|
+
| `TagsInput` | Zag's tags input. A small Model: `TagsInput.init({ id, tags?, delimiter?, max? })`, folded with `TagsInput.update` (which returns a focus Command). `TagsInput.view({ model, onMessage, label, placeholder?, name?, disabled?, direction?, addOnBlur?, routes?, words? }, h)`. See [TagsInput](#tagsinput). | No axis; `data-disabled` on `control`. Slots `root`, `label`, `control`, `list`, `tag`, `remove`, `input`, `message`, `hiddenInput`. |
|
|
587
|
+
| `InputCopy` | A read-only value with a copy button (Zag's clipboard). A small Model for the copied and failed marks. `InputCopy.view({ id, label, value, copied, failed?, onCopy, words?, copyContent?, start?, end? }, h)`; `Bundles.InputCopy` (args `{ resetAfter? }`) packages the Model. `words`: `copy`, `copied`, `failed`. `copyContent` is drawn in the button in place of its words, which stay in it for a screen reader. | No axis. Slots `root`, `label`, `group`, `start`, `end`, `input`, `button`, `buttonText`, `status`. |
|
|
588
|
+
| `Label` | `{ for, text, required?, optional?, disabled?, invalid?, trailing?, words? }`: a `label` that names a control by `for` (the id `FieldAssociation` derived). `required` draws a star the screen reader skips and `optional` the words `(optional)` that are read, after the text (`words`: `required`, `optional`); a field is one or the other. `disabled` and `invalid` mark the label (`data-disabled`, `data-invalid`) and do nothing to the control. `trailing` stands beside the label in a row with it, not inside it. | No axis. Slots `label`, `marker`, `trailing`, `root`. |
|
|
589
|
+
| `Field` | The shell around a control you drew: `Field.view({ id, label, control, description?, errors?, required? or optional?, orientation?, labelAside?, words?, style? }, h)`. The label names the control by `id`; `required` draws a mark hidden from a reader, `optional` words that are read (`words`: `required`, `optional`); `errors` are lines in an alert under the control; `orientation` is `vertical` (default) or `horizontal`. The control is drawn first, so it cannot know the shell's ids: give it `Field.describedBy(h, id, { description, errors })` as attributes. The shell owns no state. | Slots `root`, `header`, `label`, `marker`, `labelAside`, `control`, `description`, `errors`, `error`. `data-orientation` and `data-invalid` are on `root`. |
|
|
590
|
+
| `Fieldset` | Adapter: a `fieldset`, its `legend` and a `description`. `Fieldset.view({ id, legend, content, description?, disabled?, style?, mixins? }, h)` draws it with the `content` you drew; `toView` stays for one drawn as something else. | `variant`: `plain` (default, no box), `bordered`, `filled`. The recipe floats the legend into the group, so a box drawn round it holds the legend; a boxed group pads its fields, and a control in it takes a corner concentric with the box's; a disabled fieldset dims its legend and description. Slots `fieldset`, `legend`, `description`. |
|
|
591
|
+
| `FileInput` | A file picker, not a drop zone: a native `type="file"` input and the button that labels it. The application owns the files. See [FileInput](#fileinput). | `size` is Button's ladder step. Slots `root`, `input`, `trigger`, `description`, `list`, `item`, `name`, `remove`. |
|
|
592
|
+
| `FileUpload` | A field of files with a status each: a native `type="file"` input and the picker that labels it (`layout`: `button`, `zone`, `avatar`, `cover`), drop, previews, refusals, lanes for sending, `parts` for a layout of your own. A small Model: `FileUpload.Model`, `init`, `update`, placed by the application. See [FileUpload](#fileupload). | `layout`; `list`: `rows` (default), `grid`; `size` is Button's ladder step. Slots `root`, `input`, `picker`, `prompt`, `browse`, `constraints`, `description`, `picture`, `status`, `errors`, `error`, `summary`, `clear`, `list`, `item`, `preview`, `name`, `meta`, `state`, `progress`, `actions`, `retry`, `remove`, `grip`. |
|
|
593
|
+
| `FileDrop` | Adapter over `@foldkit/ui/fileDrop`: a drop zone. `FileDrop.Message` is upstream's four Messages over a `File` codec that needs no decoding services (upstream types its files as `Schema<File>`, whose services are `unknown`, so a Message holding it could not be a `Bundle.parent`'s); `FileDrop.update` of upstream takes it as it is. `Bundles.FileDrop` places upstream's Model with `{ id }` as its args and reports a drop in `onOut` as `FileDrop.OutMessage`, `ReceivedFiles { files }` or `RejectedNonFiles`; draw the placed Model through `h.submodel` with upstream's `view` and `FileDrop.toView`. | The recipe rings the zone while its input has keyboard focus (a press does not) and dims a disabled one. Slots `root`, `input`. |
|
|
594
|
+
|
|
595
|
+
`Input.view` and `Textarea.view` place their own bundles, so each takes a
|
|
596
|
+
`draw`:
|
|
316
597
|
|
|
317
598
|
```ts
|
|
318
599
|
import { Input } from 'foldkit-mixins-ui'
|
|
@@ -332,67 +613,54 @@ const emailField = (value: string, h: HtmlBuilder<Message>) =>
|
|
|
332
613
|
)
|
|
333
614
|
```
|
|
334
615
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
view adds it as it would the closure, and `KeepTyped` keeps what is typed
|
|
340
|
-
before the script runs:
|
|
616
|
+
Given a `label` instead of a `draw`, `Input.view` draws the field itself: the
|
|
617
|
+
label, the control, and the `description` under it, linked to it. `start` and
|
|
618
|
+
`end` are drawn inside the field's box beside the control, and `labelAside`
|
|
619
|
+
stands beside the label, not inside it:
|
|
341
620
|
|
|
342
621
|
```ts
|
|
343
|
-
import {
|
|
622
|
+
import { Input } from 'foldkit-mixins-ui'
|
|
344
623
|
|
|
345
|
-
const
|
|
346
|
-
|
|
347
|
-
return Input.view(
|
|
624
|
+
const siteField = (value: string, h: HtmlBuilder<Message>) =>
|
|
625
|
+
Input.view(
|
|
348
626
|
{
|
|
349
|
-
id: '
|
|
627
|
+
id: 'site',
|
|
628
|
+
label: 'Website',
|
|
629
|
+
description: 'Without the scheme.',
|
|
350
630
|
value,
|
|
351
|
-
onInput:
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
631
|
+
onInput: value => Message.TypedTitle({ value }),
|
|
632
|
+
start: h.span([], ['https://']),
|
|
633
|
+
end: h.span([], ['.com']),
|
|
634
|
+
style: FieldStyle,
|
|
355
635
|
},
|
|
356
|
-
|
|
636
|
+
h,
|
|
357
637
|
)
|
|
358
|
-
}
|
|
359
638
|
```
|
|
360
639
|
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
onInput: rh.OnInput(Message.TypedPassword),
|
|
377
|
-
visible: shown,
|
|
378
|
-
onToggle: Message.ToggledPassword(),
|
|
379
|
-
attributes: { input: [rh.KeepTyped()] },
|
|
380
|
-
},
|
|
381
|
-
rh,
|
|
382
|
-
)
|
|
383
|
-
}
|
|
384
|
-
```
|
|
640
|
+
The box is the `group` Slot (`data-field-group`): it carries the border, the
|
|
641
|
+
focus ring while the control has focus, and the dimming of a disabled field,
|
|
642
|
+
and the control inside goes borderless. With neither `start` nor `end` no group
|
|
643
|
+
is drawn and the control keeps its own border. SearchField, PasswordInput,
|
|
644
|
+
InputCopy and NumberField take the same two options. `variant` is `outline`,
|
|
645
|
+
`filled`, `ghost` or `underline`.
|
|
646
|
+
|
|
647
|
+
Beyond `type` and `placeholder`, `Input.view` takes `name`, `readOnly`, `required`,
|
|
648
|
+
`autocomplete`, `inputMode` and `maxLength`, so a form that submits natively needs
|
|
649
|
+
no hand-drawn `input`, and `attributes: { input?, label?, description? }` adds
|
|
650
|
+
what another component hands a slot (a blur handler, `aria-busy`) before the
|
|
651
|
+
mixins resolve. `Textarea.view` takes `name`, `required`, `autocomplete` and
|
|
652
|
+
`attributes` the same way. A field's description (`Input.field`'s and
|
|
653
|
+
`Textarea.field`'s) is an always-drawn `role="status"` span, even with nothing to
|
|
654
|
+
say, since a live region announces only what is put into it.
|
|
385
655
|
|
|
386
656
|
`Input.field` and `Textarea.field` draw a whole field from a
|
|
387
657
|
`FieldValidation.Field`: the value, its first error or checking mark as the
|
|
388
658
|
description, and `aria-invalid` where the field is invalid. `changed` maps the
|
|
389
659
|
typed value to a Message; `label` is the text over the control; and `draw`
|
|
390
|
-
places the resolved `label`, `control
|
|
660
|
+
places the resolved `label`, `control` and `description` bundles (the default
|
|
391
661
|
stacks them):
|
|
392
662
|
|
|
393
663
|
```ts
|
|
394
|
-
import { Input } from 'foldkit-mixins-ui'
|
|
395
|
-
|
|
396
664
|
const titleField = (field: FieldValidation.Field<string>, h: HtmlBuilder<Message>) =>
|
|
397
665
|
Input.field(
|
|
398
666
|
{ id: 'title', label: 'Title', field, changed: value => Message.TypedTitle({ value }) },
|
|
@@ -400,17 +668,18 @@ const titleField = (field: FieldValidation.Field<string>, h: HtmlBuilder<Message
|
|
|
400
668
|
)
|
|
401
669
|
```
|
|
402
670
|
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
the count
|
|
671
|
+
### Textarea
|
|
672
|
+
|
|
673
|
+
A textarea also takes what more than one line wants. The recipe's `resize` is how
|
|
674
|
+
it changes size: `auto` (the default) grows with its text from `rows` lines (two
|
|
675
|
+
unless given) to `maxRows`, then scrolls; `vertical` stays `rows` lines tall and
|
|
676
|
+
the reader drags it; `none` holds it. A `maxLength` caps the text and counts
|
|
677
|
+
toward it under the field, in the warning's ink from nine tenths and the error's
|
|
678
|
+
at the limit, and the count describes the textarea. A `footer` draws the field as
|
|
679
|
+
one box, a row of controls under the text and the count at its end:
|
|
411
680
|
|
|
412
681
|
```ts
|
|
413
|
-
import {
|
|
682
|
+
import { Textarea } from 'foldkit-mixins-ui'
|
|
414
683
|
|
|
415
684
|
const replyField = (field: FieldValidation.Field<string>, h: HtmlBuilder<Message>) =>
|
|
416
685
|
Textarea.field(
|
|
@@ -429,490 +698,1926 @@ const replyField = (field: FieldValidation.Field<string>, h: HtmlBuilder<Message
|
|
|
429
698
|
)
|
|
430
699
|
```
|
|
431
700
|
|
|
432
|
-
`Textarea.view` takes the same `rows`, `maxRows`, `maxLength
|
|
433
|
-
|
|
434
|
-
`Textarea.countOf(value, maxLength)` is the count's text. `resize: 'auto'`
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
701
|
+
`Textarea.view` takes the same `rows`, `maxRows`, `maxLength` and `count`, and
|
|
702
|
+
hands `draw` the `count`, `frame`, `footer` and `meta` bundles to place;
|
|
703
|
+
`Textarea.countOf(value, maxLength)` is the count's text. `resize: 'auto'` rests
|
|
704
|
+
on CSS `field-sizing`, which sizes the width by the text too where nothing else
|
|
705
|
+
gives one (it keeps at least 20 columns); a browser without it keeps the
|
|
706
|
+
textarea at its fewest lines, scrolling.
|
|
707
|
+
|
|
708
|
+
### SearchField
|
|
709
|
+
|
|
710
|
+
A native `type="search"` input (role `searchbox`) named by `label`, since a
|
|
711
|
+
search field wears no visible label, and a clear button drawn only while there is
|
|
712
|
+
text. The view keeps nothing: the application owns the text, `onInput` reports
|
|
713
|
+
typing, and `clear: { onClear, content? }` is what the button and Escape send; a
|
|
714
|
+
field given no `clear` has neither. `content` is drawn in the button in place of
|
|
715
|
+
the cross. Escape acts only on a
|
|
716
|
+
field with text, so on an empty one it still reaches an enclosing dialog.
|
|
717
|
+
`start` and `end` are drawn inside the field's box beside the input (a field
|
|
718
|
+
with no `start` draws a magnifier there), and `busy` sets `aria-busy` and
|
|
719
|
+
`data-busy` while a search runs: compose a spinner into `end`.
|
|
720
|
+
Pressing the button removes it and the focus it held, so answer `onClear` with the
|
|
721
|
+
`SearchField.Focus({ id })` Command, which puts focus back on the input and
|
|
722
|
+
answers `SearchField.Message.CompletedFocus` (`SearchField.inputId(id)` is the
|
|
723
|
+
input's id). `words: { clear? }` renames the button (default `Clear search`). A
|
|
724
|
+
disabled field takes no text or keys and draws no button. `routes` are
|
|
725
|
+
[application key routes](#application-key-routes) whose `input` is the field's
|
|
726
|
+
text.
|
|
438
727
|
|
|
439
|
-
`resolve` is the seam underneath, for bundles already in hand: a view that
|
|
440
|
-
receives a Tabs `render` as its input, or a Calendar whose Mixins read the
|
|
441
|
-
mode it is showing, which is only known once the attributes arrive:
|
|
442
728
|
```ts
|
|
443
|
-
import
|
|
444
|
-
import {
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
729
|
+
import { Option } from 'effect'
|
|
730
|
+
import { Behaviors } from 'foldkit-mixins'
|
|
731
|
+
import { SearchField, SearchFieldSlots } from 'foldkit-mixins-ui'
|
|
732
|
+
|
|
733
|
+
const Search = defineMessageUnion({
|
|
734
|
+
Typed: { text: Schema.String },
|
|
735
|
+
Cleared: {},
|
|
736
|
+
OpenedResults: {},
|
|
448
737
|
})
|
|
738
|
+
type Search = typeof Search.Type
|
|
449
739
|
|
|
450
|
-
const
|
|
451
|
-
Calendar.resolve(attributes, [CalendarStyle.mixin], { input: attributes._tag, h })
|
|
452
|
-
```
|
|
453
|
-
|
|
454
|
-
## What `resolve` does
|
|
455
|
-
|
|
456
|
-
`resolve(attributes, mixins, { input, h })` receives the shaped value the
|
|
457
|
-
component passed to its render callback and returns the same shape with published
|
|
458
|
-
attribute bundles resolved through Mixins.
|
|
740
|
+
const { Keys } = Behaviors
|
|
459
741
|
|
|
460
|
-
|
|
742
|
+
// ArrowDown opens the results, but only once there is text to search for.
|
|
743
|
+
const openResults: SearchField.Route<Search> = Keys.route('Open results', {
|
|
744
|
+
on: [Keys.chord('ArrowDown')],
|
|
745
|
+
handle: ({ input }) => (input === '' ? Option.none() : Option.some(Search.OpenedResults())),
|
|
746
|
+
})
|
|
461
747
|
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
{
|
|
748
|
+
const searchView = (text: string, h: HtmlBuilder<Search>) =>
|
|
749
|
+
SearchField.view(
|
|
750
|
+
{
|
|
751
|
+
id: 'find',
|
|
752
|
+
label: 'Search products',
|
|
753
|
+
value: text,
|
|
754
|
+
onInput: text => Search.Typed({ text }),
|
|
755
|
+
clear: { onClear: Search.Cleared() },
|
|
756
|
+
routes: [openResults],
|
|
757
|
+
style: Style.forSlots(SearchFieldSlots)(Recipes.SearchField({})),
|
|
758
|
+
},
|
|
759
|
+
h,
|
|
760
|
+
)
|
|
470
761
|
```
|
|
471
762
|
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
763
|
+
The search `update` answers `Cleared` with `SearchField.Focus({ id: 'find' })`.
|
|
764
|
+
|
|
765
|
+
### TagsInput
|
|
766
|
+
|
|
767
|
+
The tags are a list of chips named by the label, each with a `Remove <tag>`
|
|
768
|
+
button (`words.remove` names it, `words.mark` is its `×`), then a text input. Enter or the
|
|
769
|
+
delimiter (default `,`) adds the draft split at the delimiter and trimmed,
|
|
770
|
+
refusing empty and repeated parts and parts past `max`: a refusal
|
|
771
|
+
(`TagsInput.Refusal`: `Repeat`, `Empty`, `Full`) is said in a polite `message`
|
|
772
|
+
(worded by `words.repeat`, `words.empty` and `words.full`) and shakes the field
|
|
773
|
+
once, the shake travel-aware. Words are text with blanks, `{tag}` and `{max}`;
|
|
774
|
+
`TagsInput.words` holds the English defaults and `words` takes any of them.
|
|
775
|
+
`addOnBlur` adds the draft when the input loses focus (off by default).
|
|
776
|
+
|
|
777
|
+
Backspace in an empty input removes the last tag (`Message.BackspacedEmpty`, sent
|
|
778
|
+
only when the input itself holds no text, so text typed since the last frame is
|
|
779
|
+
edited, not skipped). The chips are one roving tab stop (`Model.chip`, set by
|
|
780
|
+
`Message.FocusMoved`): ArrowLeft and ArrowRight, swapped by `direction: 'rtl'`,
|
|
781
|
+
move among them, Home and End go to the ends, Backspace and Delete remove the
|
|
782
|
+
focused one, ArrowRight past the last returns to the input, and ArrowLeft from the
|
|
783
|
+
start of the input's text, with nothing selected, enters the last chip. A removal,
|
|
784
|
+
by button or key, focuses the chip that takes its place, else the one before it,
|
|
785
|
+
else the input, through the Command `update` returns. The input's keys are
|
|
786
|
+
`Behaviors.Keys` routes; `routes` adds the application's, and one on Enter, the
|
|
787
|
+
delimiter or Backspace is a `mixins:key-conflict`. With `name`, one hidden input
|
|
788
|
+
per tag, so a form submits the tags and not the draft.
|
|
789
|
+
|
|
790
|
+
### FileInput
|
|
791
|
+
|
|
792
|
+
A `FileInput` is a native file input and the button that labels it, so a press on
|
|
793
|
+
the button and Enter or Space on the focused input open the browser's dialog with
|
|
794
|
+
no script. The application owns the chosen files, `File`s compared by identity:
|
|
795
|
+
fold a pick in with `FileInput.added(files, picked, { multiple })` (a single field
|
|
796
|
+
takes the newest pick, `multiple` appends and skips a file already held by name,
|
|
797
|
+
size, type and modification time), and answer `onChange` and `onRemove` with the
|
|
798
|
+
`FileInput.Sync({ id, files })` Command, which writes the list back into the input
|
|
799
|
+
so a surrounding form submits exactly the list shown (Foldkit empties the input
|
|
800
|
+
after each pick; an empty list resets its value, so a removed file can be chosen
|
|
801
|
+
again). Answer `onRemove` with `FileInput.Focus({ id })` as well, which puts focus
|
|
802
|
+
on the input, since the button that held it left with its row, as
|
|
803
|
+
`SearchField.Focus` does; both answer `CompletedSync` and `CompletedFocus`, which
|
|
804
|
+
`...FileInput.cases` adds to your Message union (a missing one is a type error where
|
|
805
|
+
you return the Command). Each row has a `remove` button named `Remove {name}` (`words: {
|
|
806
|
+
remove? }`). `name`, `accept`, `multiple` and `required` are the native
|
|
807
|
+
attributes; `invalid` is `aria-invalid`, and `description` is read after the name.
|
|
808
|
+
A disabled field takes no pick and its rows no remove.
|
|
809
|
+
|
|
810
|
+
Keeping the `File`s in the Model or a Message (`Schema.instanceOf(File)`) has a cost under
|
|
811
|
+
`vite dev`: a `File` is not JSON, and Foldkit's dev-tools relay, which exists only where
|
|
812
|
+
`import.meta.hot` does, has been seen to reject with `SchemaError: Expected JSON value` as an
|
|
813
|
+
unhandled rejection. A production build has no relay; a test that fails on page errors (an
|
|
814
|
+
end-to-end run against `vite dev`) should expect it.
|
|
475
815
|
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
816
|
+
```ts
|
|
817
|
+
import { modifyFields } from 'foldkit/struct'
|
|
818
|
+
import type { Return } from 'foldkit/update'
|
|
819
|
+
import { FileInput, FileInputSlots } from 'foldkit-mixins-ui'
|
|
820
|
+
|
|
821
|
+
const FilesModel = Schema.Struct({ files: Schema.Array(Schema.instanceOf(File)) })
|
|
822
|
+
const FilesMessage = defineMessageUnion({
|
|
823
|
+
Picked: { files: Schema.Array(Schema.instanceOf(File)) },
|
|
824
|
+
Removed: { file: Schema.instanceOf(File) },
|
|
825
|
+
...FileInput.cases,
|
|
826
|
+
})
|
|
827
|
+
type FilesMessage = typeof FilesMessage.Type
|
|
828
|
+
|
|
829
|
+
const FileFieldStyle = Style.forSlots(FileInputSlots)(Recipes.FileInput({}))
|
|
830
|
+
|
|
831
|
+
const filesUpdate = (
|
|
832
|
+
model: typeof FilesModel.Type,
|
|
833
|
+
message: FilesMessage,
|
|
834
|
+
): Return<typeof FilesModel.Type, FilesMessage> =>
|
|
835
|
+
FilesMessage.match(message, {
|
|
836
|
+
Picked: ({ files }) => {
|
|
837
|
+
const next = FileInput.added(model.files, files, { multiple: true })
|
|
838
|
+
return {
|
|
839
|
+
model: modifyFields(model, { files: () => next }),
|
|
840
|
+
commands: [FileInput.Sync({ id: 'cv', files: next })],
|
|
841
|
+
}
|
|
842
|
+
},
|
|
843
|
+
Removed: ({ file }) => {
|
|
844
|
+
const next = model.files.filter(each => each !== file)
|
|
845
|
+
return {
|
|
846
|
+
model: modifyFields(model, { files: () => next }),
|
|
847
|
+
commands: [FileInput.Sync({ id: 'cv', files: next }), FileInput.Focus({ id: 'cv' })],
|
|
848
|
+
}
|
|
849
|
+
},
|
|
850
|
+
CompletedSync: () => ({ model }),
|
|
851
|
+
CompletedFocus: () => ({ model }),
|
|
852
|
+
})
|
|
499
853
|
|
|
500
|
-
|
|
854
|
+
const filesView = (model: typeof FilesModel.Type, h: HtmlBuilder<FilesMessage>) =>
|
|
855
|
+
FileInput.view(
|
|
856
|
+
{
|
|
857
|
+
id: 'cv',
|
|
858
|
+
label: 'Attach files',
|
|
859
|
+
name: 'attachments',
|
|
860
|
+
multiple: true,
|
|
861
|
+
files: model.files,
|
|
862
|
+
onChange: files => FilesMessage.Picked({ files }),
|
|
863
|
+
onRemove: file => FilesMessage.Removed({ file }),
|
|
864
|
+
style: FileFieldStyle,
|
|
865
|
+
},
|
|
866
|
+
h,
|
|
867
|
+
)
|
|
868
|
+
```
|
|
501
869
|
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
- inline declarations merge by property;
|
|
506
|
-
- an event or scalar attribute has one owner;
|
|
507
|
-
- structural attributes remain protected;
|
|
508
|
-
- conflicting ownership produces a `DiagnosticError` rather than an accidental
|
|
509
|
-
second handler.
|
|
870
|
+
Nothing here reads the input: the browser's dialog, the native input and the form
|
|
871
|
+
are the platform's, and the view declares them. `Sync` and `Focus` are the only
|
|
872
|
+
calls that touch the page.
|
|
510
873
|
|
|
511
|
-
|
|
512
|
-
silently install a competing `OnClick` at the same Slot.
|
|
874
|
+
### FileUpload
|
|
513
875
|
|
|
514
|
-
|
|
515
|
-
|
|
876
|
+
A `FileUpload` is a field that holds files and says what became of each: chosen by the
|
|
877
|
+
dialog, dropped or pasted, judged against limits (kind, size, count, duplicates), listed
|
|
878
|
+
with a thumbnail, and, when the application asks, sent. Its `Model` and `update` are the
|
|
879
|
+
whole machine, which the application places and folds as it places `TagsInput`; the
|
|
880
|
+
view draws them.
|
|
516
881
|
|
|
517
|
-
|
|
882
|
+
Choose by what you need to own:
|
|
518
883
|
|
|
519
|
-
|
|
520
|
-
|
|
884
|
+
| You need | Use |
|
|
885
|
+
| --- | --- |
|
|
886
|
+
| a native picker whose `File[]` you keep, with no checks, drop, previews or status | [FileInput](#fileinput) |
|
|
887
|
+
| a drop zone over `@foldkit/ui`'s Submodel | `FileDrop` |
|
|
888
|
+
| files judged, listed, previewed, dropped, removed, retried, optionally sent and sorted | `FileUpload` |
|
|
521
889
|
|
|
522
|
-
|
|
523
|
-
|
|
890
|
+
It owns the list and each entry's status. It does not own the transport (the
|
|
891
|
+
application's Subscription sends a file and answers in its own Messages), the order
|
|
892
|
+
(the application places `Reorder`), or the bytes of an uploaded file (a `Stored` entry
|
|
893
|
+
holds an address).
|
|
524
894
|
|
|
525
895
|
```text
|
|
526
|
-
|
|
527
|
-
|
|
|
528
|
-
resolved Slot attrs
|
|
529
|
-
|
|
|
530
|
-
ChildAttribute
|
|
531
|
-
|
|
|
532
|
-
component Submodel dispatcher
|
|
896
|
+
Offered -> validate -> Held | Queued -> Uploading(lane) -> Done | Failed -> Retried
|
|
533
897
|
```
|
|
534
898
|
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
899
|
+
A picked, dropped or pasted batch is one `Offered` Message. `update` checks each file
|
|
900
|
+
(kind, then size, then duplicate), refuses a whole batch that would pass `maxFiles`, and
|
|
901
|
+
lists the rest `Held`, or `Queued` when the field has `lanes`. A queued file starts as a
|
|
902
|
+
lane frees. The Model keeps each `File` and writes the list back into the native input
|
|
903
|
+
after every change (`FileInput.Sync`), so a plain form post carries exactly the local
|
|
904
|
+
files, dropped ones included.
|
|
540
905
|
|
|
541
|
-
|
|
542
|
-
Tabs -> { tablist, tabs, activeIndex }
|
|
543
|
-
RadioGroup -> { group, options, selectedValue, hiddenInput }
|
|
544
|
-
Calendar -> ResolvedDays | ResolvedMonths | ResolvedYears
|
|
545
|
-
Menu -> { wrapper, button, backdrop, items, scroll, groups, isVisible }
|
|
546
|
-
Toast -> { container, entries }
|
|
547
|
-
Listbox -> { wrapper, button, backdrop, items, scroll, groups, hiddenInputs, isVisible }
|
|
548
|
-
Combobox -> { wrapper, inputWrapper, input, toggleButton, backdrop, items, scroll, groups, hiddenInputs, isVisible }
|
|
549
|
-
```
|
|
906
|
+
Place it in the application's Model and wrap its Messages:
|
|
550
907
|
|
|
551
|
-
|
|
552
|
-
|
|
908
|
+
```ts
|
|
909
|
+
import * as Command from 'foldkit/command'
|
|
910
|
+
import { FileUpload, FileUploadSlots } from 'foldkit-mixins-ui'
|
|
911
|
+
|
|
912
|
+
const UpModel = Schema.Struct({ upload: FileUpload.Model })
|
|
913
|
+
type UpModel = typeof UpModel.Type
|
|
914
|
+
const UpMessage = defineMessageUnion({ GotUpload: { message: FileUpload.Message } })
|
|
915
|
+
type UpMessage = typeof UpMessage.Type
|
|
916
|
+
|
|
917
|
+
const upInit = (): UpModel => ({
|
|
918
|
+
upload: FileUpload.init({
|
|
919
|
+
id: 'documents',
|
|
920
|
+
multiple: true,
|
|
921
|
+
accept: ['.pdf', 'image/*'],
|
|
922
|
+
maxFiles: 5,
|
|
923
|
+
maxSize: 5_000_000,
|
|
924
|
+
}),
|
|
925
|
+
})
|
|
553
926
|
|
|
554
|
-
|
|
927
|
+
const upUpdate = (model: UpModel, message: UpMessage): Return<UpModel, UpMessage> =>
|
|
928
|
+
UpMessage.match(message, {
|
|
929
|
+
GotUpload: ({ message: inner }) => {
|
|
930
|
+
const { model: upload, commands } = FileUpload.update(model.upload, inner)
|
|
931
|
+
return {
|
|
932
|
+
model: upload === model.upload ? model : modifyFields(model, { upload: () => upload }),
|
|
933
|
+
commands: Command.mapMessages(commands ?? [], next => UpMessage.GotUpload({ message: next })),
|
|
934
|
+
}
|
|
935
|
+
},
|
|
936
|
+
})
|
|
555
937
|
|
|
556
|
-
|
|
557
|
-
adapter.
|
|
938
|
+
const UpStyle = Style.forSlots(FileUploadSlots)(Recipes.FileUpload({ layout: 'zone' }))
|
|
558
939
|
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
| HoverIntent | `trigger`, `panel`, `arrow` (open and close delays with intent, for a hover card or a menu). `anchored: { id, anchor? }` in the context anchors the panel to the trigger in the top layer (`HoverIntent.anchor()` unless given), the trigger taking `HoverIntent.triggerId(id)` |
|
|
573
|
-
| Tabs | `tablist`, `tab`, `panel`, and this package's `indicator` and `highlight` (drawn first in the tablist, for `Tabs.fluid`). and this package's `item`, `label`, `icon` and `close`: a tab is a flex row, so draw its words in `label` (`h.span(label, [words])`) and an icon in `icon`, a Badge after them for a count. `TabsContext.close: { onClose }` makes tabs closable: each gets a close button (no tab stop, hidden from assistive technology) and Delete, named in `aria-keyshortcuts`; answer with `Tabs.closing(tabs, chosen, closed)`, which gives the tabs left, the tab chosen and the index to focus with `FocusTab`. `Tabs.readingKeys` beside the style reads the arrow keys by the tablist's direction (see [Right to left](#right-to-left)). Recipe axes `variant`: `line` (default), `pill`; `size`: `sm`, `md`, `lg`; `overflow: 'scroll'` (one line, its edges fading) or `'wrap'` (a grid of equal columns that fills the row and falls to fewer columns, no tab cut off; a column is no narrower than three control heights; `.extend` the tablist's `--_fk-tab-min` to change it); pill-only `selection`: `raised` (default) or `tint`; upstream's `orientation: 'Vertical'` stands the rule at the tabs' inline end |
|
|
574
|
-
| RadioGroup | `group`, `option`, `label`, `description`, `hiddenInput`, and this package's `card`. Upstream's `option` is a `button` and its `label` bundle only an id, so a bare `label` takes no press: draw each row as a `label` element around its `option`, carrying the option's `card` bundle (`h.label(option.card, [h.button(option.option, []), …])`), and the browser sends a press on the words to the radio. `card` is `data-checked` while its option is. The recipe stacks the group unless `aria-orientation` is `horizontal`, and a row wraps. `variant: 'card'` frames each card and fills the one whose radio is checked. `tone`: `accent` (default), `neutral`; `size`: `sm`, `md`, `lg`. `RadioGroup.readingKeys` as Tabs' |
|
|
575
|
-
| Anchor | a Mount and a Behavior over `@foldkit/ui/anchor`: `Anchor.behavior(Slots)({ floating, config })` positions a floating slot against a button by id; `Anchor.topLayer(mount)` shows an in-place panel in the top layer around it (see [The top layer](#the-top-layer)) |
|
|
576
|
-
| Calendar | `root`, `header` (the heading's row, this package's own), `grid`, `headerRow`, `previousMonthButton`, `nextMonthButton`, `headingButton`, `previousPageButton`, `nextPageButton`, `columnHeader`, `weekRow`, `dayCell`, `dayButton`, `monthCell`, `monthButton`, `yearCell`, `yearButton`. `Calendar.readingKeys` as Tabs' |
|
|
577
|
-
| Menu | `wrapper`, `button`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator`, and this package's `rows`, `highlight`, `scrollBar` and `scrollThumb` (while the panel has a `scroll`), `label`, `sub` and `chevron` (the component's rows) (over the `MenuView` fork; see [Why some components needed a fork](#why-some-components-needed-a-fork)) |
|
|
578
|
-
| FileDrop | `root`, `input`. `FileDrop.Message` is `@foldkit/ui/fileDrop`'s four Messages over a `File` codec that needs no decoding services: upstream's own types its files as `Schema<File>`, whose services are `unknown`, so a Message holding it cannot be a `Bundle.parent`'s. `FileDrop.update` of upstream takes it as it is |
|
|
579
|
-
| Toast | `container`, `entry` (over the `ToastView` fork; the dismiss control stays inside the consumer's `entryToView`), and the slots the `Toast` component draws (see the vocabulary below) |
|
|
580
|
-
| Listbox | `wrapper`, `button`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator`, and this package's `rows`, `highlight`, `indicator`, `scrollBar`, `scrollThumb`, and an option's and the trigger's parts (`itemIcon`, `itemLabel`, `itemDescription`, `itemCheck`, `value`, `valueText`, `chevron`, …) (over the `ListboxView` fork; single and multi share one transcription). A custom select is a Listbox drawn with `Listbox.parts(mixins, { h })`: `part.option({ label, description?, icon? })` as an item's content and `part.trigger(chosen, placeholder)` as the button's, its value or the placeholder (muted, `data-placeholder`) and a chevron. Recipe axes `width`: `auto` (default) or `trigger`; `check`: `end` (default), `start`, `none`; `trigger`: `outline` (default), `filled`, `ghost`; `size`: `sm`, `md`, `lg` |
|
|
581
|
-
| Combobox | `wrapper`, `inputWrapper`, `input`, `toggleButton`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator`, and this package's `rows`, `highlight`, `indicator`, `scrollBar`, `scrollThumb`, `chips`, `chip`, `chipRemove`, `clearButton`, `empty` and an option's parts (over the `ComboboxView` fork; single and multi share one transcription). The view inputs add `chips: { label?, removeLabel? }` (each chosen value a chip in the field, its remove button choosing it again, which a multiple combobox toggles off: with `ComboboxView.Multi`, a tags field with suggestions), `clearContent` and `clearLabel` (a clear button while the field has text) and `empty` (shown, as a polite status, in the list's place while open with nothing to list; a loading line too). `Combobox.parts(mixins, { h }).option(content, query)` marks the typed text in an option's label. Recipe axis `width`: `trigger` (default) or `auto` |
|
|
582
|
-
| DatePicker | `trigger`, `panel`, `backdrop` (over the `DatePickerView` fork, which keeps upstream's Popover+Calendar composition and seams only the popover assembly). A range or many days in the popover: see [Why some components needed a fork](#why-some-components-needed-a-fork) |
|
|
583
|
-
|
|
584
|
-
A disclosure with its recipe: the recipe draws the button and the panel's box,
|
|
585
|
-
and `animatePanel` keeps the shut panel inert and moves its height.
|
|
940
|
+
const upView = (model: UpModel, h: HtmlBuilder<UpMessage>) =>
|
|
941
|
+
FileUpload.view(
|
|
942
|
+
{
|
|
943
|
+
model: model.upload,
|
|
944
|
+
onMessage: message => UpMessage.GotUpload({ message }),
|
|
945
|
+
label: 'browse',
|
|
946
|
+
name: 'documents',
|
|
947
|
+
words: { prompt: 'Drop files here or' },
|
|
948
|
+
style: UpStyle,
|
|
949
|
+
},
|
|
950
|
+
h,
|
|
951
|
+
)
|
|
952
|
+
```
|
|
586
953
|
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
954
|
+
`init` refuses an `accept` token that is not `.ext`, `type/*` or `type/subtype`, a
|
|
955
|
+
negative or fractional `maxSize`, `maxFiles` or `lanes`, a `maxFiles` without `multiple`,
|
|
956
|
+
and several `initial` files without it. `update` returns an `OutMessage`: `Picked`
|
|
957
|
+
(the ids added and replaced, and every `Refusal`) after an offer, `Removed` after a
|
|
958
|
+
removal. A no-op returns the Model it was given.
|
|
959
|
+
|
|
960
|
+
**The picker.** The `input` is a native `type="file"` drawn first, a transparent pixel
|
|
961
|
+
rather than hidden, and the `picker` is its `label`, always its next sibling. A press
|
|
962
|
+
on the picker, and Enter or Space on the focused input, open the browser's dialog with
|
|
963
|
+
no script between; the picker rings on keyboard focus. The picker also owns the four
|
|
964
|
+
drag events and `data-dragging`. `Recipes.FileUpload`'s `layout` (`button`, `zone`,
|
|
965
|
+
`avatar`, `cover`) only restyles it. What is drawn follows what the view is given, not
|
|
966
|
+
the recipe: `words.prompt` draws a drop zone's invitation, `picture` draws the
|
|
967
|
+
single-image face, `description` and the limits draw their paragraphs. The input is
|
|
968
|
+
named by the picker's words (`prompt` and `label`), so give `label` the words that name
|
|
969
|
+
the files.
|
|
970
|
+
|
|
971
|
+
**Refusals and the live region.** Each refusal names its file and is listed in
|
|
972
|
+
`errors`, which is not live; one polite `status` region, drawn always, says each change
|
|
973
|
+
once (`3 added`, `Removed a.png`, `a.png uploaded`) and never says a percentage. Two
|
|
974
|
+
identical notices in a row are not spoken twice. `words` holds every sentence, with
|
|
975
|
+
`{name}`, `{count}`, `{max}`, `{size}` and `{reason}` standing for what it is about.
|
|
976
|
+
|
|
977
|
+
**Previews.** An added image asks for an object URL through a Command and shows it in
|
|
978
|
+
the row's `preview`. `FileUpload.released(model)` revokes every URL: call it from the
|
|
979
|
+
Message that drops the widget (a route change, a dialog closing). Nothing revokes on
|
|
980
|
+
unmount, so without it the URLs live until the document unloads.
|
|
981
|
+
|
|
982
|
+
**A single image.** Give `picture` a function from the first entry's address to what the
|
|
983
|
+
picker holds. The list is not drawn, and the one file's Remove button follows the
|
|
984
|
+
picker, over its corner in `avatar` and `cover`:
|
|
590
985
|
|
|
591
986
|
```ts
|
|
592
|
-
|
|
593
|
-
import { Style } from 'foldkit-mixins'
|
|
594
|
-
import { Disclosure, DisclosureSlots, Recipes } from 'foldkit-mixins-ui'
|
|
987
|
+
const UpAvatarStyle = Style.forSlots(FileUploadSlots)(Recipes.FileUpload({ layout: 'avatar' }))
|
|
595
988
|
|
|
596
|
-
const
|
|
597
|
-
|
|
598
|
-
const details = (isOpen: boolean, h: HtmlBuilder<Message>) =>
|
|
599
|
-
UiDisclosure.view(
|
|
989
|
+
const upAvatar = (model: UpModel, h: HtmlBuilder<UpMessage>) =>
|
|
990
|
+
FileUpload.view(
|
|
600
991
|
{
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
h,
|
|
608
|
-
})
|
|
609
|
-
|
|
610
|
-
[],
|
|
611
|
-
[
|
|
612
|
-
h.button(disclosure.button, ['Shipping details']),
|
|
613
|
-
disclosure.animatePanel(h.div(disclosure.panel, ['Shipped in two days.'])),
|
|
614
|
-
],
|
|
615
|
-
)
|
|
616
|
-
},
|
|
992
|
+
model: model.upload,
|
|
993
|
+
onMessage: message => UpMessage.GotUpload({ message }),
|
|
994
|
+
label: 'Change photo',
|
|
995
|
+
picture: url =>
|
|
996
|
+
Option.match(url, {
|
|
997
|
+
onNone: () => h.span([], ['No photo']),
|
|
998
|
+
onSome: src => h.img([h.Src(src), h.Alt('')]),
|
|
999
|
+
}),
|
|
1000
|
+
style: UpAvatarStyle,
|
|
617
1001
|
},
|
|
618
1002
|
h,
|
|
619
1003
|
)
|
|
620
1004
|
```
|
|
621
1005
|
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
Every one takes an optional `style` of its slots and `mixins` beside it. Style
|
|
631
|
-
the slots with the matching recipe. Hide text with `U.srOnly` from
|
|
632
|
-
`foldkit-mixins/utilities`. Name a control with `FieldAssociation`;
|
|
633
|
-
`Label.view` takes the id that derived.
|
|
1006
|
+
**Uploads.** `init({ lanes })` sends that many files at once; `0` sends nothing and
|
|
1007
|
+
every file stays `Held`. A queued file takes the first free lane, and a lane number holds
|
|
1008
|
+
for the whole send, so one Subscription entry per lane never restarts another's upload.
|
|
1009
|
+
The application supplies the send (`foldkit-media/browser`'s `uploadFile`, a hand-written
|
|
1010
|
+
stream, a simulation) and answers in its own Messages, which fold `Progressed`,
|
|
1011
|
+
`Succeeded` or `Failed` back into the widget. `FileUpload.lanes` makes every lane's
|
|
1012
|
+
entry for a count, so the entries cannot be fewer than `lanes`: take the count from the
|
|
1013
|
+
one constant that feeds both.
|
|
634
1014
|
|
|
635
1015
|
```ts
|
|
636
|
-
import {
|
|
637
|
-
|
|
638
|
-
|
|
1016
|
+
import { Stream } from 'effect'
|
|
1017
|
+
|
|
1018
|
+
const UP_LANES = 2
|
|
1019
|
+
|
|
1020
|
+
const upSubscriptions = FileUpload.lanes<UpModel, UpMessage>({
|
|
1021
|
+
count: UP_LANES,
|
|
1022
|
+
model: parent => parent.upload,
|
|
1023
|
+
send: job =>
|
|
1024
|
+
Stream.make(
|
|
1025
|
+
UpMessage.GotUpload({
|
|
1026
|
+
message: FileUpload.Message.Succeeded({
|
|
1027
|
+
id: job.id,
|
|
1028
|
+
attempt: job.attempt,
|
|
1029
|
+
url: Option.none(),
|
|
1030
|
+
}),
|
|
1031
|
+
}),
|
|
1032
|
+
),
|
|
1033
|
+
})
|
|
1034
|
+
```
|
|
639
1035
|
|
|
640
|
-
|
|
641
|
-
|
|
1036
|
+
(`FileUpload.lane({ lane, model, send })` is one lane's entry, for an application that
|
|
1037
|
+
names its Subscription entries itself.) Removing an uploading entry empties its lane, the
|
|
1038
|
+
entry's dependency changes and the request aborts: the same button reads `Cancel {name}`
|
|
1039
|
+
while a file uploads. A `Failed` answer says whether it may be `retryable`; `Retried`
|
|
1040
|
+
queues it again, as a new `attempt`. A Message of another attempt, or of an entry that
|
|
1041
|
+
is gone, changes nothing.
|
|
642
1042
|
|
|
643
|
-
|
|
644
|
-
|
|
1043
|
+
Progress is a value the application builds, so a field that sends nothing never loads the
|
|
1044
|
+
Progress widget. Give the view `progress` and an uploading row draws a bar (or, with
|
|
1045
|
+
`Recipes.Progress({ shape: 'ring' })`, a ring) named by `Uploading {name}`; without it
|
|
1046
|
+
the row says the same in its state text:
|
|
645
1047
|
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
1048
|
+
```ts
|
|
1049
|
+
import { FileUploadProgress, ProgressSlots } from 'foldkit-mixins-ui'
|
|
1050
|
+
|
|
1051
|
+
const UpBar = FileUploadProgress.make({
|
|
1052
|
+
style: Style.forSlots(ProgressSlots)(Recipes.Progress({})),
|
|
1053
|
+
})
|
|
1054
|
+
// FileUpload.view({ ..., progress: UpBar }, h)
|
|
650
1055
|
```
|
|
651
1056
|
|
|
652
|
-
|
|
653
|
-
`
|
|
654
|
-
`
|
|
655
|
-
|
|
656
|
-
|
|
1057
|
+
**Pieces.** `FileUpload.parts(options, h)` returns the drawings `view` assembles, apart:
|
|
1058
|
+
`input`, `picker`, `errors`, `status`, `summary` and an `items` entry per file with its
|
|
1059
|
+
`preview`, `name`, `meta`, `state`, `progress`, `actions` and `grip` (an uploading row with `progress` draws no state text). Lay them into
|
|
1060
|
+
`Table.view` or `Card.view` yourself; `view` is written in terms of `parts`, so there is
|
|
1061
|
+
one drawing.
|
|
1062
|
+
|
|
1063
|
+
**Placed and configured.** `Bundles.FileUpload` is the same `init` and `update` for
|
|
1064
|
+
`foldkit-bundle`, with `init`'s options as the args. It reports `Picked` and `Removed`,
|
|
1065
|
+
which a placement answers with `onOut` or `Bundle.ignore`, and it sends nothing: an
|
|
1066
|
+
application with `lanes` still adds `FileUpload.lanes` to its own Subscriptions.
|
|
1067
|
+
`FileUpload.configure({ base, presets })` returns `{ view, parts }` bound to what a site
|
|
1068
|
+
gives once: `style`, `words`, `picture`, `itemActions`, `progress` and `mixins`. `sort`
|
|
1069
|
+
reads the Model at each draw and `routes` hold Messages, so both stay at the call.
|
|
1070
|
+
|
|
1071
|
+
**Sorting.** Order is the application's: it places `Reorder` as documented for
|
|
1072
|
+
primitives and hands the Behavior to the view as `sort: { input, mixin }`, which draws a
|
|
1073
|
+
grip per row, marks the list `data-sortable` and reads `input` for the Behavior. The widget
|
|
1074
|
+
imports neither Reorder nor its pointer drag, so a field with no sorting loads neither. The
|
|
1075
|
+
application's `onOut` applies the `Moved` fact with `FileUpload.ordered` and reads every fact
|
|
1076
|
+
out through the one live region with `FileUpload.announce`. A keyed move drops the browser's
|
|
1077
|
+
focus, so beside the widget's own focus Commands add `FileUploadSort.keepFocus` to `mixins`
|
|
1078
|
+
(it keeps a grip's focus and covers `without`); it is a module of its own because it loads
|
|
1079
|
+
`FocusRecovery`.
|
|
657
1080
|
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
| `Menu` | One menu, opened three ways: `Menu.init(id, rows, { isAnimated?, isModal? })` (a row with `items` hosts a submenu, one level deep; `isAnimated` gives the menu's and its submenus' panels upstream's transition marks, for the recipe's fade, and `isModal` makes the rest of the page inert while the menu is open), folded with `Menu.update`, drawn with `Menu.view({ model, rows, buttonContent, onMessage, opensAt?, direction?, isRowDisabled?, mixins, submenuMixins? }, h)`, the style being one of the `mixins` (`[MenuStyle.mixin]`). By a button (`opensAt` unset); at a point (`opensAt: 'point'`, with `Menu.target(onMessage, h)` on the area: a right press records its point and the `contextmenu` after it opens the menu there; a finger or a pen held there `Menu.HOLD_MS`, 500ms, opens it too, as iOS fires no `contextmenu`, while one that moves 10px is a scroll; give the area `-webkit-touch-callout: none` and `user-select: none`, or iOS shows its own callout over it). A row is an `ItemRow` (`{ label }`), a `CheckRow` (`check: 'checkbox' \| 'radio'`, `checked`: `menuitemcheckbox` or `menuitemradio` with `aria-checked`; choosing it sends `Selected` and leaves the menu open, the application keeping `checked`, a radio row's group being the rows of its `group`), or a `SubmenuRow` (`items`). Any row may name a `group` (rows next to each other with one group stand under its heading, a separator between groups), a `shortcut` (keys drawn at the row's end as Kbd with the view's `kbd`, named in `aria-keyshortcuts`; the menu binds nothing) and `tone: 'destructive'` (`data-tone`). A submenu's row is a `menuitem` with `aria-haspopup="menu"` and `aria-expanded`; ArrowRight, Enter or Space opens it on its first row, ArrowLeft or Escape closes it back to the row (under `direction: 'rtl'`, drawn as the root's `dir`, the submenu opens on the left, its chevron points there, and the arrows swap), a pointer resting 150ms opens it, and choosing a leaf closes everything. `Selected` names the value and the submenu it came from. Pass `Menu.fluid` beside the style (in `submenuMixins`, not `mixins`, where rows open submenus). Its panels, submenus included, draw in the top layer. A `@foldkit/ui` Menu the application folds itself, for typed items or groups, is drawn through the panel adapter instead, and opens at a point with `Menu.drawAtPoint` and `Menu.pointTarget` (see [Why some components needed a fork](#why-some-components-needed-a-fork)). | No axis. Slots `MenuSlots`. |
|
|
693
|
-
| `Menubar` | A row of `@foldkit/ui` Menus, shadcn's and the APG's menubar: `Menubar.view({ label, model, menus, onMessage, direction?, style?, menuMixins }, h)`, each menu's `{ label, rows, isRowDisabled? }` taking a Menu's rows (none opening a submenu), its Model (`Menubar.init(ids, { isAnimated?, isModal? })`) folded with `Menubar.update`, whose `Selected` OutMessage names the menu and the row. One trigger is the tab stop; ArrowLeft/ArrowRight (Home/End while all are shut) move it, swapped under `direction: 'rtl'` (drawn as the bar's `dir`), and with a menu open they open the next on its first row. While one is open, pointing at another opens it, and opening any shuts the rest. `Recipes.MenubarMenu` is the Menu recipe with a bar's flat triggers. | No axis. Slots `bar`, `menu`; each menu's are `MenuSlots`. |
|
|
694
|
-
| `MessageScroller` | A conversation's log that follows the newest message while the reader is at the end and stops when they scroll up. `MessageScroller.init({ id })` holds only whether it follows and how many arrived unseen; the scroll position is the browser's, read by its `FollowEnd` Mount. Fold `MessageScroller.update`, and send `Message.Appended({ count })` when your update appends messages (not when it loads older ones, which it holds in place). `MessageScroller.view({ model, label, content, onMessage, jumpLabel?, unseenLabel?, style?, areaStyle?, areaMixins? }, h)` draws a named `role="log"` in a ScrollArea, with a jump button counting what arrived while away; give its parent a height. | No axis. Slots `root`, `log`, `jump`, `count`. |
|
|
695
|
-
| `Meter` | `@foldkit/ui`'s Meter: `Meter.view({ id, label, value, min?, max?, low?, high?, optimum?, valueText?, style? }, h)` draws a `meter` named by its label. The root says how good the value is as `data-level` (`good`, `fair`, `poor`), as the HTML meter judges it; `Meter.levelOf` is that judgment. A measurement, where `Progress` is work. | No axis; the fill takes success, warning or error by level. Slots `root`, `label`, `track`, `fill`. |
|
|
696
|
-
| `Nav` | Two layers. `Nav.toView(mixins, { h }, label, draw?)` styles `@foldkit/ui`'s stateless Nav, drawing `nav > ul > li > a` with the current link `aria-current="page"`. `Nav.view({ model, entries, label, onMessage, orientation?, direction?, mixins? }, h)` is a navigation menu: links and triggers whose panels of link columns (`groups` of `{ label, href, description?, current? }`) show in the top layer, with the APG's disclosure-navigation keys (Escape, ArrowDown into a panel, the arrows, Home and End along the row; a press outside and focus leaving close it); which panel shows is `Nav.init(id)`'s Model, folded with `Nav.update`. `Nav.fluid` beside the style glides a line to the current link and a faint pill to the one the pointer nears. | `indicator`: `underline` (default), `pill`; `orientation: 'vertical'` is a column whose panels open beside it. Slots `nav`, `list`, `item`, `link`, `trigger`, `chevron`, `panel`, `groups`, `group`, `heading`, `links`, `panelItem`, `panelLink`, `title`, `description`, `indicator`, `highlight`. |
|
|
697
|
-
| `NumberField` | `{ id, label, description?, value, onChange, min?, max?, step?, page?, format?, disabled? }`; `NumberField.settled(value, bounds)` clamps a value onto its step. The APG's editable spinbutton: an input with `role="spinbutton"` that the arrows, PageUp and PageDown, Home and End step, a typed number committing on change, between steppers out of the tab order that disable at their bound. | No axis. Slots `root`, `label`, `group`, `input`, `decrement`, `increment`, `description`. |
|
|
698
|
-
| `OtpField` | `{ label, value, onChange, length?, pattern?, groups?, disabled? }`; `OtpField.kept(text, length, pattern)` filters a code. shadcn's input-otp: one real input (`autocomplete="one-time-code"`, paste and Backspace the browser's) over cells that mirror it, the next cell marked `data-next` for its caret. | No axis. Slots `root`, `input`, `group`, `cell`, `separator`. |
|
|
699
|
-
| `Pagination` | `{ page, pageCount, onPage, label?, siblings?, boundaries?, numbered?, ends?, range? }`. Fewer than two pages draws nothing. `Pagination.itemsOf(page, pageCount, window?)` is the stops; `Pagination.summaryOf(page, { total, perPage, text? })` is `"1–10 of 97"`, drawn before the stops when `range` is given. `range.choose: { sizes, onPerPage, label? }` adds a select of rows per page (labelled `Rows per page` by default) that sends `onPerPage` with the size; the application sets `perPage` and a page that keeps its rows in view. `numbered: false` leaves previous and next alone; `ends` draws first and last. The current stop holds ` / 12` in a `pageCount` span hidden from assistive technology. | `compact`: `narrow` (default, below a 30rem window), `always` or `never`. Compact shows only the current number, with its ` / 12`, and no ellipses. The current stop reads `aria-current`. Slots `root`, `summary`, `perPage`, `perPageSelect`, `first`, `prev`, `next`, `last`, `page`, `pageCount`, `ellipsis`. |
|
|
700
|
-
| `PasswordInput` | `PasswordInput.view({ id, label, value, onInput, visible, onToggle, autocomplete?, toggleLabel?, description?, invalid?, disabled?, attributes? }, h)`: a password field whose toggle button (`aria-pressed`, `aria-controls`, one fixed name) shows it as text. `autocomplete` is `current-password` (default) or `new-password`; spellcheck and autocorrect stay off. `strength` is a gauge the app draws (`Meter.view(…, h)`), placed under the field, so a page with none ships no Meter; `requirements` are `{ label, met }[]` (`PasswordRequirement`), listed and each read as met or not (`requirementStates`); `capsLock: { on, onKey }` says Caps Lock is on, politely, `onKey` given `capsLockOf(key, modifiers)` for each key (an `Option`: none for a key that says nothing of it). The app owns the text, the flag and the Caps Lock reading. `onInput` is a closure or a resumable builder's `OnInput` attribute, and `attributes` adds to any Slot (`{ input: [rh.KeepTyped()] }`), as the resumable examples above show. | `size` (`sm`, `md`, `lg`). Input's pieces in InputGroup's box; the eye is `Icons.glyph` by `aria-pressed`. Slots `root`, `label`, `group`, `input`, `toggle`, `description`, `strength`, `requirements`, `requirement`, `requirementState`, `capsLock`. |
|
|
701
|
-
| `Progress` | `@foldkit/ui`'s Progress: `Progress.view({ id, label, value, min?, max?, valueText?, style? }, h)` draws a `progressbar` named by its label. `value` is an `Option`; none is indeterminate, and the bar's fill sweeps toward the inline end, leftward right to left. The root carries the share done as `--fk-progress`. `showValue` draws the value (`valueText`, else a percentage) at the end of a bar's label line and inside a ring. A `value` given as `ProgressSection`s is one stacked bar of toned parts, read aloud as their sum; `buffer` draws how far the work could go behind the fill; `segments` cuts the track into steps. | `shape`: `bar` (default) or `ring`, Circular Progress; `tone`: `accent`, `neutral`, `success`, `warning`, `error`, `info` (Meter's tokens); `stripes`: `none` (default), `still`, `moving` (travel-aware); `size`: `sm`, `md`, `lg`. Slots `root`, `label`, `track`, `indicator`. |
|
|
702
|
-
| `QrCode` | After Zag's: `QrCode.view({ id, value, label?, level?, quietZone?, overlay?, tooLong?, style? }, h)`, one `img` named `QR code: <value>` (or `label`), every dark module one SVG `path` over a background that carries the quiet zone. `level` is the error correction, `M` by default and `H` under an `overlay` (a logo at the centre). `QrCode.encode(text, level)` gives the matrix, none when no version holds the text, and `pathOf` its path; both are pure. `QrCode.Download({ id, format, filename, pixels })` saves the drawn code as PNG or SVG in the colors it shows; the overlay is not in the file. | `scheme` (`light`, dark on light on any page, or `page`), `size`. Slots `root`, `frame`, `background`, `pattern`, `overlay`, `fallback`. |
|
|
703
|
-
| `Questionnaire` | An assistant's questions answered in the chat. `Questionnaire.init({ id, questions, layout? })` with `Questionnaire.single`, `multiple` and `text` questions (`Question` is a Schema, so a tool's input decodes into it), folded with `Questionnaire.update`, which says what is missing and focuses it, and returns `OutMessage.Answered({ answers })` once every required question is answered; the form then gives way to a summary. `Questionnaire.view({ model, onMessage, title?, style?, radioGroup?, checkboxGroup?, input?, textarea?, button?, submitButton? }, h)`: the controls are the package's RadioGroup, CheckboxGroup, Input and Textarea, each taking its own style. | `variant` (`plain`, `card`), `actions` (`end`, `start`). Slots `root`, `title`, `progress`, `question`, `prompt`, `words`, `field`, `other`, `otherLabel`, `error`, `actions`, `summary`, `asked`, `answer`. |
|
|
704
|
-
| `Rating` | `Rating.view({ id, label, value, onChange, max?, starLabel?, readOnly?, disabled?, style? }, h)`: a `radiogroup` of native radios named by its label, one per star under one name, so the browser's arrows move the choice and a form submits it. `value` is an `Option`; none is unrated. Read-only, it is one `img` whose name says the rating. `precision: 0.5` draws two radios a star; a read-only value of any fraction fills its last star part way. `onClear` is sent by a press on the star already chosen; `showValue` shows `starLabel` of the rating beside the stars, so a word per value is one function. Home and End go to the ends through the `Rating.Ends` Mount (resolve it in a Scene test with a choice's Message). A read-only rating (`readOnly: true`) takes no `onChange`. | `tone`: `warning` (default, gold), `accent` or `error`; `glyph`: `star` (default), `heart`, `circle`, or `--_fk-rating-shape`; `size`: `sm`, `md`, `lg`. Stars are a CSS `clip-path` on each radio's `::before`; pointing previews the rating. Slots `root`, `label`, `star`. |
|
|
705
|
-
| `Resizable` | `Resizable.Model` (`init(share)`), its `Message` and `update(model, message, bounds)`, which the application keeps and folds; `Resizable.view({ model, onMessage, label, first, second, orientation?, direction?, min?, max?, step? })`. shadcn's Resizable and the APG's window splitter: the handle is a `separator` with its value, stepped by the arrows and sent to the bounds by Home and End; a drag follows the `Move` Mount from where it began over the group the `Resize` Mount measured. Under `direction: 'rtl'`, drawn as the root's `dir`, the first panel is on the right, so ArrowLeft and a drag to the left grow it. `collapsible: 'first' | 'second'` (with `collapsedTo`) collapses that panel on Enter or a double-click and puts it back where it was, easing there while a drag follows the pointer at once; pass the same bounds to `update` and the view. A split fills its panel, so splits nest either way. | `handle`: `line` (default; a thicker accent line under the pointer) or `grip` (a pill of dots); `data-orientation` lays it out. Slots `root`, `first`, `handle`, `second`. |
|
|
706
|
-
| `ScrollArea` | `{ content }`. The height that makes it scroll is the caller's mixin, on `viewport` or `root`; a width goes on `root`, which the viewport fills and the bars lie over. The viewport is tabbable. A bar per axis is drawn beside the viewport, and `ScrollArea.overlayBars` beside the style lays them over its edge, driven by `ScrollBars` from `foldkit-primitives/dom`: a thumb that rests 4px wide, widens to 6px under the pointer, and fades once scrolling and the pointer rest; a coarse pointer keeps the browser's bar. See [Overlay scroll bars](#overlay-scroll-bars). | `orientation`: `vertical` (default), `horizontal`, `both`; `vertical` and `horizontal` fade the content toward an edge with more past it and draw a hairline there. Slots `root`, `viewport`, `bar`, `thumb`. |
|
|
707
|
-
| `Separator` | `{ orientation?, label?, decorative? }`, horizontal by default. A `label` sits between two drawn rules and is read as text; `decorative` is `role="none"`. The rule and a label's frame carry `data-orientation`, which the recipe reads, so one style draws both orientations. A vertical rule stretches across a flex or grid row, short of it by the inset, and elsewhere (running text) stands as tall as the letters. | `line`: `solid`, `dashed`, `dotted`; `thickness`: `thin`, `thick`; `spacing`: `none`, `sm`, `md`, `lg`; `inset`: `none`, `sm`, `md`. The line is a border in `outline.default`, which a dark page shows. Slots `rule`, `root`, `label`. |
|
|
708
|
-
| `Drawer` | A panel docked to the bottom of the screen that peeks or opens beside the page, not over it: no focus trap, backdrop or scroll lock, so the page under it stays live (a modal one is the `Sheet`). `Drawer.init({ id, open?, swipe? })` (down by default), folded with `Drawer.update`, opened with `Drawer.open` and `Drawer.close`, drawn with `Drawer.view({ model, onMessage, labels: { open, closed }, style?, mixins?, draw }, h)`, `draw` laying out `panel`, `handle`, `body` (the body may sit below what else peeks with the handle) and, optionally, `grip`, more to drag it by (a row of tabs: vertical swipes drag it, sideways ones still scroll). A drag follows the finger and lets go open or down by its speed, then by how far it came. `swipe: { from?, flickSpeed?, closeShare? }` says how it is swiped: a finger drags it from anywhere on the panel (`from: 'panel'`, the default), yielding to content that can still scroll its way, so a long one scrolls back to its top and then goes, and a field or `data-no-swipe` starts no drag; a mouse drags it by the handle, and `from: 'handle'` keeps every pointer there. A release faster than `flickSpeed` (0.4px/ms) is a flick, and a slow one goes once dragged `closeShare` (a quarter) of the panel. A click or Enter on the handle toggles it, and the click a browser sends after a drag does not. The panel's inline style is the drag's: set `--fk-drawer-peek` (default 5rem) and `--fk-drawer-height` (default 70dvh) on an ancestor or in a style. | `Recipes.Drawer`: `dock`: `always` (default), `below-lg` or `below-xl`, above which the panel is the column it sits in, with no handle. The handle's bar bends into a chevron going down, with the finger while dragged. Slots `panel`, `handle`, `body`, `grip`. The handle is a 44px target drawn tight to its bar, and the peek stays above the home indicator. |
|
|
709
|
-
| `Sheet` | A Dialog a finger drags, vaul's Drawer: `Sheet.init({ id, side?, points?, opensAt?, dismissible?, isAnimated?, swipe? })`, folded with `Sheet.update` and opened with `Sheet.open` and `Sheet.close` (each also reporting the Dialog's `Opened` or `Closed`), drawn with `Sheet.view({ model, onMessage, mixins, hasDescription?, covered?, scalesPage?, draw }, h)`, `draw` laying out `DialogSlots`' bundles with `h.div(sheet.handle)` in the panel. The panel stands on `side`'s edge (`data-side`); a drag follows the pointer and settles at the nearest of `points` (the share of the panel shown, ascending; a top or bottom sheet with a point below 1 takes its `size`'s full height, so a short one still shows its start, and below its highest point its content holds still, so a swipe up raises it), or, flicked or dragged far enough past the first, closes it, unless `dismissible: false`. `swipe: { from?, flickSpeed?, closeShare? }` says how it is swiped: a finger drags it from anywhere on the panel (`from: 'panel'`, the default), yielding to content that can still scroll its way, so a long one scrolls back to its top and then goes, and a field or `data-no-swipe` starts no drag; a mouse drags it by the handle, and `from: 'handle'` keeps every pointer there. A release faster than `flickSpeed` (0.4px/ms) is a flick, and a slow one goes once dragged `closeShare` (a quarter) of the panel. The Dialog keeps focus, Escape and scroll lock. `scalesPage` with `Recipes.sheetPage` on the page beside the sheet, never around it, steps the page back while it is open. | `Recipes.Sheet`: `size`: `sm`, `md` (default), `lg`, `full`; `handle`: `bar` (default) or `none`; `title`: `shown` (default) or `hidden`. Slots are `DialogSlots`. The panel's padding keeps clear of the safe areas (`Theme.tokens.safe`) on the sides it touches. |
|
|
710
|
-
| `Picker` | A select that is a dropdown on a desktop and a bottom sheet on a phone, with one Model and one set of Messages whatever the width: `Picker.init({ id, sheet? })` (upstream's Listbox Model and a `Sheet`'s), folded with `Picker.update`, which returns `Picker.OutMessage.Chose({ value })` for a choice made either way, drawn with `Picker.view({ model, onMessage, label, options, value, placeholder, anchor?, style?, mixins?, listbox?, sheet? }, h)`. The application keeps the value (`Option`), as with the Listbox; `options` are `{ value, label, description?, icon? }`, `Value` inferred from them. Both halves are drawn and the recipe shows one, so nothing reads the width: the Listbox (its panel kept in place) at or above the breakpoint, and below it an opener whose Sheet lists the options as a listbox, the chosen one (or the first) focused, the arrows, Home and End moving focus, Enter, Space or a tap choosing and closing it. Opening the Sheet closes a Listbox left open. `listbox` takes `Recipes.Listbox`, which also draws the options' and the trigger's content (`Listbox.parts`), and `sheet` takes `Recipes.Sheet`. | `Recipes.Picker`: `sheetBelow`: `sm`, `md` (default) or `lg`, the theme's breakpoint below which the Sheet's half shows; `trigger`: `outline` (default), `filled`, `ghost`, the opener's look, as the Listbox's; `size`: `sm`, `md`, `lg`. Slots `root`, `dropdown`, `opener`, `list`, `option`. |
|
|
711
|
-
| `Sidebar` | shadcn's sidebar with Fluid's collapse, keeping a Model: `Sidebar.init({ id, rows, open?, collapsed?, side?, width? })` (a Tooltip per row id, and the phone's Sheet), folded with `Sidebar.update`, drawn with `Sidebar.view({ model, onMessage, label, groups, header?, footer?, direction?, collapse?, style?, mixins?, tooltip?, sheet? }, h)`. `groups` are `{ id, title?, collapsible?, action?, rows }`, a row a `SidebarLink` (`{ id, label, href, current?, icon?, badge?, action? }`) or a `SidebarBranch` of nested links (`items`). An `action` (`SidebarAction`: `{ label, icon, message }`) is a button at a titled group's heading or beside a link, where it takes the badge's place under the pointer (both show on a touch screen). Groups and branches open like an accordion's, several at once; the current page is `aria-current` and `Sidebar.fluid` glides a marker to it. `collapse: 'offcanvas'` (default) takes the whole column off the page; `'icons'` leaves a rail of icons named in Tooltips (`tooltip`, a Tooltip style). With `sheet` (a Sheet style), an opener shows it in a Sheet on a phone. Shut groups and a collapsed column stay drawn and `inert`. `Sidebar.init({ width: { size?, min?, max? } })` makes the column resizable, its width in the Model: a `resize` handle on its edge drags it, the arrows step it, Enter or a double-click collapses it, and dragged below half `min` it collapses, coming back at the width the drag began at. | `variant`: `sidebar` (flush with the page's edge, the default), `floating` (a card lifted off it), `inset` (no edge, on the surface it stands on, for a page drawn as a card beside it); on a phone with a Sheet the column is its opener alone. Slots `root`, `header`, `footer`, `opener`, `title`, `toggle`, `nav`, `section`, `heading`, `trigger`, `chevron`, `links`, `item`, `branch`, `link`, `icon`, `mark`, `detail`, `label`, `badge`, `action`, `tip`, `indicator`, `highlight`, `resize`. |
|
|
712
|
-
| `SignaturePad` | After Zag's: strokes drawn by one pointer over a dashed line and "Sign here", undo, clear, and a typed name instead. `SignaturePad.init({ id, pen? })` holds the strokes (points with pressure, in the pad's coordinates), folded with `SignaturePad.update`. Drawn with `SignaturePad.view({ model, onMessage, label, fallback?, labels?, disabled?, style? }, h)`. `pathOf(stroke, pen)` and `toSvg(model, { color?, font? })` are pure; `RequestedPng({ scale, background })` returns `ExportPng`, answered by `ExportedPng({ url, width, height })` or `FailedExport`. | `surface` (`plain`, `muted`, `dashed`), `size`. Slots `root`, `label`, `control`, `segments`, `stroke`, `guide`, `placeholder`, `typedName`, `controls`, `undo`, `clear`, `fallback`, `fallbackLabel`, `input`. |
|
|
713
|
-
| `Skeleton` | `{ label? }`, `role="status"`, a bar a film of the text. `Skeleton.lines({ lines, label? })`, `avatarRow`, `card` and `tableRow({ columns })` draw the shapes content takes, in a `group`. | `shape`: `bar` (default), `circle`; `animation`: `pulse` (default), `shimmer`, `none`. Slots `bar`, `group`. |
|
|
714
|
-
| `Slider` | `Slider.view({ id, label, value, onChange, min?, max?, step?, format?, marks?, showValue?, name?, disabled?, style? }, h)`, where `value` is a number or a `{ low, high }` range and `onChange` is handed the same kind. Native `input type="range"` thumbs, so drag, keys, right to left and the form value are the browser's. One number is one thumb across the track, named by the label; a press anywhere on the track moves it. A range is a `group` named by its label holding two thumbs named by `thumbLabels` (default `Minimum` and `Maximum`), each bounded by the other (the low one's `max` is the high value), so the browser stops a drag or a key at the other thumb; `Slider.moved(range, 'low' \| 'high', value, bounds)` snaps, bounds and orders a range, and returns the same range when nothing changed. `marks` are values dotted on the track (`data-filled` where the fill covers them) and `showValue` draws each value, both hidden from assistive technology, which hears `aria-valuetext`. `@foldkit/ui`'s Slider is not adapted: draw its Submodel with Slots of your own. `orientation: 'vertical'` stands it upright; `ticks` dots every step; a mark may be `{ value, label }` (`SliderMark`), its words under the track, those at either end flush with its ends rather than hanging past them. | `tone`: `accent` (default) or `neutral`; `size`: `sm`, `md` (default), `lg`, the thumb's edge; `track`: `thick` (default; the fill reaches each thumb's far edge, Fluid's look), `thin` or `paint` (a track a holder paints, as the color picker's); `value`: `above` (default), `inside` (widens the thumb into a pill; best at `md` or `lg`) or `end` (at the end of the label's row); `label`: `shown` (default) or `hidden`. A Slider is at least 12rem wide; a holder that lays it narrower sets `--fk-slider-min-length`, as the ColorPicker's channels do. Slots `root`, `label`, `control`, `track`, `fill`, `mark`, `value`, `thumb`. |
|
|
715
|
-
| `Spinner` | `{ label?, showLabel? }`. `role="status"`; `showLabel` draws the label beside the wheel. A turn is about 720ms times `travel`. | `kind`: `ring` (default), `dots`, `bars`, `pulse`, `orbit`; `size`: `sm`, `md` (default), `lg`; `tone`: `accent` (default), `neutral`, `current`. Slots `wheel`, `part`, `root`, `text`. |
|
|
716
|
-
| `Steps` | `Steps.view({ label, steps: { title, description?, icon?, content? }[], current, onSelect?, style? }, h)`: a stepper, an ordered list named by `label`. The step at `current` is `aria-current="step"`, those before it `data-state="complete"` (a check replaces the number), those after `upcoming`. An `icon` stands in the marker for its number; `content` follows the step, beside the line in a vertical stepper. With `onSelect(index)`, completed steps are buttons for going back; steps ahead never are. The application owns `current`. `progress` (0 to 1) fills the connector after the current step when the recipe's connector is a progress bar. | `orientation`: `horizontal` (default) or `vertical`; `size`: `xs`, `sm`, `md`, `lg` (the Avatar's sizes; unset, 1.75rem); `marker`: `number` or `dot`; `connector`: `line` or `progress`. A horizontal row narrower than 32rem shows only the current step's words, wrapping inside an even share so the markers stay evenly spaced (a word longer than 40% of the row is cut), and narrower than 17rem draws them on a line of their own under the markers. Slots `root`, `item`, `step`, `trigger`, `marker`, `number` (the figure in a marker with no icon, trimmed to its digits so it centers in any face), `text`, `title`, `description`, `content`, `connector`. |
|
|
717
|
-
| `Table` | The presentational table: `{ columns: { header, value, numeric?, sortKey? }[], rows, rowKey?, caption?, fluid?, sort?, selection?, expansion?, empty? }`. A column with a `sortKey` heads with a button that sends `sort.onSort(column)`, and the sorted column carries `aria-sort`; `Table.nextSort(sort, column)` cycles ascending, descending and none. `selection` puts a checkbox on every row and one in the heading, mixed while only some are chosen; `expansion` opens a row's detail in a row below it (`aria-expanded`, `aria-controls`); `empty` stands across the table while there are no rows (an `Empty.view`). The sort, the chosen and the open rows are the application's. It stands in a `frame`, which scrolls sideways when the table is wider than the screen (under a `static` header; a `sticky` one sticks to the application's scroller, which scrolls it). With `fluid`, one highlight behind the body rows follows the pointer, skipping detail and empty rows. Filtering, column reorder and resize, and virtualized rows stay with `foldkit-data-grid`. | `rows`: `lined`, `striped`, `plain`; `density`: `compact`, `regular`, `comfortable` (none set follows the region); `header`: `static`, `sticky`. Slots `frame`, `highlight` (with `fluid`), `root`, `caption`, `head`, `headerRow`, `headerCell`, `sortButton`, `sortIcon`, `body`, `row`, `cell`, `controlCell`, `checkboxLabel`, `expandButton`, `expandIcon`, `detailRow`, `detailCell`, `emptyRow`, `emptyCell`. |
|
|
718
|
-
| `TagsInput` | Zag's tags input, a small Model of its own: `TagsInput.init({ id, tags?, delimiter?, max? })`, folded with `TagsInput.update` (which returns a focus Command), drawn with `TagsInput.view({ model, onMessage, label, placeholder?, disabled? }, h)`. The tags are a list of chips named by the label, each with a `Remove <tag>` button, then a text input. Enter or the delimiter (default `,`) adds the draft split at the delimiter and trimmed, refusing empty and repeated parts, and parts past `max`: a refusal (`TagsInput.Refusal`: `Repeat`, `Empty`, `Full`) is said in a polite `message` (worded by `refusalText`) and shakes the field once, the shake travel-aware; Backspace on an empty draft removes the last tag; a removal returns focus to the input. Keys reach `update`, which decides from its own draft. | No axis; `data-disabled` on `control`. Slots `root`, `label`, `control`, `list`, `tag`, `remove`, `input`, `message`. |
|
|
719
|
-
| `ThinkingIndicator` | An assistant at work: `ThinkingIndicator.view({ label?, detail?, active?, icon?, style? }, h)` draws dots, a pulse or the view's icon beside words a band of light sweeps, and a detail line, in a polite status. Keep it drawn with `active: false` before work starts, so what it says when it starts is announced. Every movement holds under reduced motion. | `mark` (`dots`, `pulse`, `none`), `label` (`shimmer`, `plain`, `hidden`), `tone` (`muted`, `accent`). Slots `root`, `mark`, `dot`, `icon`, `label`, `detail`. |
|
|
720
|
-
| `ThinkingSteps` | The trace of what an assistant did: `ThinkingSteps.view({ id, steps, open, onToggle, duration?, summary?, openSteps?, onToggleStep?, stateWords?, style? }, h)`. Each step is `{ id, title, state, duration?, detail?, icon?, steps? }`, `state` being `pending`, `running`, `done` or `failed`, said in words too. The button says the running step's title, or "Thought for 4s". Its openness is yours, an `Option<boolean>`: none opens it while a step runs and shuts it once all are done, and the press sends the state the reader asked for. `openSteps` and `onToggleStep` make each step's detail collapsible (`Accordion.toggled`). | `variant` (`plain`, `card`), `connector` (`line`, `none`). Slots `root`, `trigger`, `summary`, `chevron`, `panel`, `list`, `step`, `head`, `marker`, `title`, `state`, `duration`, `body`, `detail`. |
|
|
721
|
-
| `Timer` | After Zag's: a countdown (`Timer.init({ id, countdown: true, duration })`) or a stopwatch (`Timer.init({ id, interval? })`), folded with `Timer.update`, whose Commands (`Timer.Stamp`, `Timer.Tick`) read Effect's `Clock`, so TestClock drives a run. `Timer.view({ model, onMessage, label, units?, separator?, labels?, style? }, h)`: a `role="timer"` with each unit in a Slot, one press that says what comes next, and reset. `Timer.phase(model)` is `idle`, `running`, `paused` or `done`; to start at once, return `Timer.update(model, Timer.Message.Pressed({ action: 'start' }))` from `init`. | `tone`, `look`, `progress`, `size`. Slots `root`, `label`, `area`, `item`, `separator`, `controls`, `action`. |
|
|
722
|
-
| `Toast` | A stack of toasts, Sonner's: `Toast.init(id, { position?, direction?, duration?, max?, threshold? })`, folded with `Toast.update`, whose `Acted` OutMessage names a pressed action; `Toast.show(model, { type?, title, description?, action?, duration? })` returns the stack and the new toast's `id`, `Toast.settle(model, id, input)` turns a toast (a `loading` one, a promise's) into its outcome, and `Toast.dismiss(model, id)` takes it away; draw it with `Toast.view({ model, onMessage, label?, closeLabel?, expand?, icons?, style? }, h)`. The newest stand in front, spread out while the pointer or focus holds the stack, at most `max` (3) showing; a held stack or a hidden page pauses every countdown, keeping the time left; a swipe toward the edge past `threshold` dismisses one. A toast is spoken in a polite region, an error in an assertive one. A promise toast is `show` with `type: 'loading'`, the work run as a Command, and `settle` on the toast's `id` when its Message comes back. `ToastView` is the fork for toasts that carry their own payload. | `tone`: `plain` (default) or `rich` (each type on its tint). Slots `container`, `entry`, `list`, `icon`, `body`, `title`, `description`, `action`, `close`, `status`, `alert`. |
|
|
723
|
-
| `Tour` | Steps anchored beside their targets in the top layer, over a dim with a cutout the target's presses reach. `Tour.init({ id })`, started with `Tour.start(model, config, { opener })` and folded with `Tour.update(config)` (`config` is `{ steps: [{ title, description, target?, placement? }] }`); `Tour.view({ model, config, onMessage, padding?, interactive?, dismissOnOutside?, closeOnEscape?, labels?, direction?, style? }, h)`. The target scrolls into view; Next, Back and the arrows move on, Escape and Skip end it with focus back to the opener, and `update` returns `Ended { completed }`. A step without a target, or whose target is missing, stands in the middle. | No axis. Slots `layer`, `blocker`, `spotlight`, `panel`, `arrow`, `progress`, `title`, `description`, `actions`, `back`, `next`, `skip`. |
|
|
724
|
-
| `TreeView` | The APG's and Zag's tree view, a small Model of its own: `TreeView.init({ id, open?, checked? })`, folded with `TreeView.update(nodes, { checkable? })` (curried over the tree, flattened once), drawn with `TreeView.view({ label, model, nodes, onMessage, direction?, style?, mixins? }, h)` over nodes `{ id, label, children?, disabled?, icon?, openIcon? }`. `checkable` (on the view and `update`) gives each row a box: the Model's `checked` holds the leaves, a branch reads checked, mixed or not from them (`TreeView.checksOf`), and Space checks the current row in `update`. One tab stop; Up/Down move through the rows showing, stepping over shut and disabled ones; Right opens or steps in, Left shuts or steps out (swapped under `direction: 'rtl'`, drawn as the root's `dir`); Home/End; a character moves to the next showing row that starts with it; Enter, Space or a click chooses a row and opens or shuts a branch. Keys reach `update`, which decides from its own Model and sends a focus Command. Each item carries `--fk-tree-level`; a shut group stays drawn and `inert`. | `guides`: `none` (default) or `lines`, a guide down each open branch; `data-state` on a branch `item` and its `group`. Slots `root`, `item`, `row`, `chevron`, `checkbox`, `icon`, `label`, `group`. |
|
|
725
|
-
| `Typography` | `{ level, text }`. The level chooses the element (`h1`–`h4`, `lead`, `body`, `small`, `muted`, `quote`, `code`, and the interface roles `display`, `title`, `subtitle`, `caption`, `micro` as paragraphs). | `level`, same set; a role is its size and leading on the size ladder. Defaults to `body`. Slot `text`. |
|
|
726
|
-
| `VirtualList` | `@foldkit/ui`'s virtual list: `VirtualList.view({ model, items, itemToKey, itemToView, onMessage, overscan?, itemToRowHeightPx? \| dynamicRowHeights?, style?, mixins? }, h)` draws only the rows in view. Its Model is upstream's (`@foldkit/ui/virtualList`'s `init`), kept by the application and folded with that module's `update`. A row's mixins may style it, not handle its events, since it is drawn inside the list's submodel. A bar is drawn beside the list, and `VirtualList.overlayBars` lays it over the list's edge: `root` runs `ScrollBars` for upstream's list, which holds a Mount of its own. | No axis. Slots `root` (the box it scrolls within: 18rem tall by default and as wide as its container, offering 20rem where the container takes its width from it, so the rows drawn as it scrolls never resize it), `row`, `bar`, `thumb`. |
|
|
727
|
-
| `WindowList` | A virtual list that scrolls with the window: `WindowList.init({ id, estimatedHeight, unmeasured?, overscan?, viewportHeight?, from? })`, folded with `WindowList.update`, drawn with `WindowList.view({ model, items, itemToKey, itemToView, onMessage, label?, style?, mixins? }, h)`. It draws the rows in view of the document's viewport between spacers as tall as the rest, so the page keeps its own scrolling: the browser restores its offset, a `sticky` header above the list sticks, and Space and End move it. Its one Mount on `root`, `WindowList.Track`, reads where the viewport lies over the list on every scroll, resize and resize of the page (`WindowViewport`), so content above it, or growing above it, counts, and measures each drawn row's border box (`MeasureRows`; space rows with padding: a row is `flow-root`). The rows already drawn when it starts are read at once, so no row leaves before its height is known. A row not yet measured counts `estimatedHeight`, or with `unmeasured: 'mean'` the mean of the rows measured above 0: for rows whose height the window's width decides, which `init` cannot know. A Scene test of a page drawing the list resolves it with `Scene.Mount.resolveAll(WindowList.resolveTrack(onMessage, WindowList.Message.Placed({ top, height })))`, the reading going through the view's own `onMessage`. `WindowList.windowOf(model, keys)` is which rows are drawn, for loading what is in view, and `WindowList.keep(model, keys)` drops the heights of rows that left; a row still drawn is measured again only when it resizes, so keep the keys of the rows drawn. A server's page opens the list at a row with `from` (a page's `?from=`): the window starts at that row, with no overscan above it, and the rows above take no room until `Track` places the list, which gives them their room and scrolls the window by what that moved the first row drawn, so a reader sees the same rows before and after the runtime takes the page over. The first `Placed` sets `from` back to 0, and the list follows the window. For a page without scripts, `WindowList.pageOf(model, keys)` is `{ start, end, previous, next }`: the rows drawn and, as `Option`s, the rows the pages either side open at (`previous` the first whose window reaches this one's start), for links that set `?from=`. Use `VirtualList` for a list in a box of its own. | `Recipes.WindowList`: no look, only the spacers hidden where no script runs (`Utilities.scriptedOnly`), so the rows a server drew lie in the page's flow; `.extend` it with the list's look. Slots `root` (`role="list"`), `spacer` (`data-edge` `start` or `end`, hidden from assistive technology), `row` (`role="listitem"`). |
|
|
1081
|
+
```ts
|
|
1082
|
+
import { Bundle } from 'foldkit-bundle'
|
|
1083
|
+
import { Reorder } from 'foldkit-primitives/interaction'
|
|
1084
|
+
import { FileUploadSort } from 'foldkit-mixins-ui'
|
|
1085
|
+
|
|
1086
|
+
const SortRows = Bundle.declare(Reorder.bundle, 'rows')
|
|
1087
|
+
const SortModel = Schema.Struct({ ...SortRows.fields, upload: FileUpload.Model })
|
|
1088
|
+
type SortModel = typeof SortModel.Type
|
|
1089
|
+
const SortMessage = defineMessageUnion({
|
|
1090
|
+
...SortRows.cases,
|
|
1091
|
+
GotUpload: { message: FileUpload.Message },
|
|
1092
|
+
})
|
|
1093
|
+
type SortMessage = typeof SortMessage.Type
|
|
1094
|
+
|
|
1095
|
+
const SortAssembly = Bundle.parent({ Model: SortModel, Message: SortMessage }).assemble(
|
|
1096
|
+
Bundle.parent({ Model: SortModel, Message: SortMessage }).at(SortRows, {
|
|
1097
|
+
onOut: (fact: Reorder.OutMessage) => (model: SortModel) => {
|
|
1098
|
+
const label = (id: string) => model.upload.entries.find(entry => entry.id === id)?.name ?? id
|
|
1099
|
+
const said = FileUpload.announce(model.upload, Reorder.announcement(fact, { label }))
|
|
1100
|
+
return {
|
|
1101
|
+
model: Reorder.OutMessage.match(fact, {
|
|
1102
|
+
Moved: move =>
|
|
1103
|
+
modifyFields(model, {
|
|
1104
|
+
upload: () =>
|
|
1105
|
+
FileUpload.ordered(said, Reorder.apply(FileUpload.ids(model.upload), move)),
|
|
1106
|
+
}),
|
|
1107
|
+
PickedUp: () => modifyFields(model, { upload: () => said }),
|
|
1108
|
+
PassedOver: () => modifyFields(model, { upload: () => said }),
|
|
1109
|
+
PutBack: () => modifyFields(model, { upload: () => said }),
|
|
1110
|
+
}),
|
|
1111
|
+
}
|
|
1112
|
+
},
|
|
1113
|
+
}),
|
|
1114
|
+
)
|
|
728
1115
|
|
|
729
|
-
|
|
1116
|
+
const Sorting = Reorder.behavior(SortRows)(FileUploadSlots)<SortModel, SortMessage>({
|
|
1117
|
+
container: 'list',
|
|
1118
|
+
item: 'item',
|
|
1119
|
+
handle: 'grip',
|
|
1120
|
+
items: model => FileUpload.ids(model.upload),
|
|
1121
|
+
orientation: 'both',
|
|
1122
|
+
})
|
|
1123
|
+
// FileUpload.view({ ..., sort: { input: model, mixin: Sorting.mixin }, mixins: FileUploadSort.keepFocus }, h)
|
|
1124
|
+
```
|
|
730
1125
|
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
`
|
|
734
|
-
|
|
735
|
-
|
|
1126
|
+
**Keys.** Enter and Space belong to the dialog, and Backspace and Delete on the input
|
|
1127
|
+
remove the last file; `routes` takes the rest. A route on one of those four throws
|
|
1128
|
+
`mixins:key-conflict`, and `FileUpload.conflict(routes)` returns that diagnostic without
|
|
1129
|
+
drawing.
|
|
1130
|
+
|
|
1131
|
+
**Forms.** `name` goes on the real input, and `Sync` runs after every change. A `Stored`
|
|
1132
|
+
entry is not in the input: post its address with a hidden input of your own. Give no
|
|
1133
|
+
`name` when `lanes` sends the bytes. `required` is the native attribute, and a field with
|
|
1134
|
+
only stored files fails it, since the input holds none. `disabled` disables the input
|
|
1135
|
+
and the buttons; `readOnly` draws no picker, remove or grip and keeps the input out of
|
|
1136
|
+
the tab order, so a form still posts.
|
|
1137
|
+
|
|
1138
|
+
**Failure and recovery.** A Model holding a `Local` entry is not JSON: `settled(model)`
|
|
1139
|
+
turns uploaded entries into stored ones, drops every other local file and clears
|
|
1140
|
+
`dragging`, the refusals, the notice and the previews, and the result encodes and decodes.
|
|
1141
|
+
A removed entry takes its button, so focus moves by Command to the next entry's remove
|
|
1142
|
+
button, else the previous, else the input; `FileUpload.without(model, ids)` removes for
|
|
1143
|
+
the application and moves no focus. Dropping files, writing `input.files` and the
|
|
1144
|
+
synthetic drop are proven in Chromium only.
|
|
1145
|
+
|
|
1146
|
+
### Other fields
|
|
1147
|
+
|
|
1148
|
+
- **NumberField.** What the field draws is what it accepts: `locale` draws and
|
|
1149
|
+
reads that locale's marks (`de-DE`: `1.234,5`); `format` with its `parse`
|
|
1150
|
+
(`Option.none()` for text that is no number, which leaves the value as it was)
|
|
1151
|
+
is for anything else; with neither it is `String` and a plain number. Arrows,
|
|
1152
|
+
PageUp and PageDown, Home and End step it, a typed number commits on change, and
|
|
1153
|
+
the steppers sit out of the tab order and disable at their bound. `name` submits
|
|
1154
|
+
the text the field shows; `required` is the native `required` with
|
|
1155
|
+
`aria-required`.
|
|
1156
|
+
- **OtpField.** `id` names the input for a label or a form, `readOnly` lets the
|
|
1157
|
+
code be read and copied, and `invalid` marks the input `aria-invalid` and each
|
|
1158
|
+
cell `data-invalid`.
|
|
1159
|
+
- **InputCopy.** The view is stateless; answer `onCopy` with the
|
|
1160
|
+
`InputCopy.Copy({ text })` Command, which yields `foldkit-primitives/dom`'s
|
|
1161
|
+
`ClipboardMessage` (`Copied` or `CopyFailed`, never a throw). `InputCopy.Model`
|
|
1162
|
+
keeps the marks: `InputCopy.init({ resetAfter? })` (default 2000ms), folded with
|
|
1163
|
+
`InputCopy.update`, where `Copied` shows it copied and starts the `Reset` Command
|
|
1164
|
+
that sets it back unless a later copy came first, and `Failed` does the same for
|
|
1165
|
+
a refused copy (`failed`, never together with `copied`). Pass `model.copied` and
|
|
1166
|
+
`failed: model.failed`; the status region says `words.failed` (default `Copy
|
|
1167
|
+
failed`) while the button carries `data-failed`. The button is named `Copy
|
|
1168
|
+
<label>`; copied, it reads `Copied` and a polite status region says so.
|
|
1169
|
+
- **PasswordInput.** `onInput` is a closure or a resumable builder's `OnInput`
|
|
1170
|
+
attribute, and `attributes` adds to any Slot (`{ input: [rh.KeepTyped()] }`), as
|
|
1171
|
+
[Form participation](#form-participation) shows.
|
|
1172
|
+
|
|
1173
|
+
## Choosing a value
|
|
1174
|
+
|
|
1175
|
+
The application keeps the chosen value in its Model. The widgets that submit
|
|
1176
|
+
natively take a `name` (see [Form participation](#form-participation)).
|
|
1177
|
+
|
|
1178
|
+
| Widget | What it is | Recipe and Slots |
|
|
1179
|
+
| --- | --- | --- |
|
|
1180
|
+
| `Checkbox` | `Checkbox.view({ id, checked, onToggle, label, description?, position?, labelAside?, indeterminate?, disabled?, readOnly?, invalid?, name?, value? }, h)` draws the row: the box, its label and a line of description that also describes it; `position: 'end'` puts the words first, `labelAside` is a slot beside the label (a Badge, a Tooltip's trigger). `Checkbox.configure({ base, presets })` states the look once. `Checkbox.toView` stays the adapter, for a layout of your own. | `tone`: `accent` (default), `neutral` (checked in the page's ink), `danger`; `size`; `variant`: `plain` (default), `card` (the row boxed and filled while checked, one press target); `shape`: `square` (default), `round`. Slots `root`, `text`, `heading`, `aside`, `checkbox`, `label`, `description`, `hiddenInput`. |
|
|
1181
|
+
| `CheckboxGroup` | `{ id, legend, options, checked, onToggle, error?, name?, selectAll? }`, each option `RowContent` (`{ value, label, description?, icon?, trailing?, content?, disabled? }`: `description` is text or Html, `icon` a mark inside the label, `trailing` a badge or count after it, `content` the words of your own drawing, `label` still the name). `variant: 'card'` boxes each row and stretches its label over it, so a press anywhere on it chooses it. `CheckboxGroup.configure`. A `fieldset` named by its `legend`, each option the APG's checkbox named by a `label` for it, so a press on the words toggles it. `toggled(checked, value)` is one option's transition; `coverage(options, checked)` is `none`, `some` or `all` (a disabled option counts for neither); `setEnabled(options, checked, on)` is every enabled option or none, a disabled one keeping the state `checked` gives it. `selectAll: { label, onSet }` draws a first row checked, `mixed` or unchecked by `coverage` that controls every option; a press sends `onSet` with `setEnabled`'s values, on unless all already are. `error` is shown under the options: the `fieldset` is described by it and each checkbox is `aria-invalid`. | `variant`: `plain` (default), `list` (checked rows fill, and merge where they stand together); `orientation`: `vertical` (default), `horizontal` (a wrapping row). The checkbox sits on the label's row, so a description does not pull it down. Slots `root`, `legend`, `options`, `option`, `checkbox`, `label`, `description`, `error`. |
|
|
1182
|
+
| `Switch` | `Switch.view({ id, checked, onToggle, label, description?, position?, labelAside?, disabled?, readOnly?, invalid?, name?, value? }, h)`, as the Checkbox's without `indeterminate`; `Switch.configure`. `Switch.draggable(onToggle)` beside the style lets the thumb be dragged; it lives in a file of its own, so a page that never names it ships no part of it. An invalid switch's track is ringed. `Switch.toView` is the adapter. | `tone`: `accent` (default), `neutral`, `danger`; `size`; `variant`: `plain`, `card` as Checkbox. Slots `root`, `text`, `heading`, `aside`, `button`, `label`, `description`, `hiddenInput`. |
|
|
1183
|
+
| `RadioGroup` | `RadioGroup.view({ model, onMessage, legend, options, value, orientation?, hideLegend?, disabled?, readOnly?, invalid?, error?, name? }, h)` over the focus cursor `Bundles.RadioGroup` holds; `options` are `{ value, label, description?, icon?, trailing?, content?, disabled? }` (`RowContent`) and `value` is the application's `Option`, set from the `Selected` the Bundle reports. An `error` draws under the group, makes it `aria-invalid` and describes it. `RadioGroup.configure`. `RadioGroup.readingKeys` reads both arrow pairs whichever way the group stands (see [Right to left](#right-to-left)) and lives in a file of its own. `RadioGroup.toView` is the adapter: each row a `label` around its `option`, carrying the `card` bundle. | `variant`: `plain` (default), `card` (frames each card, filling the checked one); `tone`: `accent` (default), `neutral`, `danger`; `layout`: `stacked` (default), `grid` (rows in columns that fill the room); `size`. The recipe stacks the group unless `aria-orientation` is `horizontal`, and a row wraps. Slots `root`, `legend`, `text`, `group`, `option`, `label`, `description`, `icon`, `trailing`, `error`, `hiddenInput`, `card`. |
|
|
1184
|
+
| `Segmented` | A tray of buttons where pressing selects. `Segmented.view({ id, label, options: { value, label, icon?, iconOnly?, disabled? }[], pressed, onPress, multiple?, orientation?, direction?, name?, disabled? }, h)`; `Segmented.toggled(pressed, value, { multiple, optional })` is the transition `update` applies; `Segmented.configure`. `multiple` is a toggle group, `orientation: 'vertical'` stacks it. `Segmented.fluid` (the gliding pill) is a file of its own. See [Segmented](#segmented). | `tray`: `tray` (default, muted), `plain`, `underline`; `size`: `xs`, `sm`, `md`, `lg`; `width: 'fill'`. Slots `group`, `option`, `label`, `icon`, `content`, `indicator`, `highlight`, `hiddenInput`. |
|
|
1185
|
+
| `Select` | `Select.view({ id, label, options, value?, onChange?, placeholder?, description?, disabled?, invalid?, name? }, h)` draws the native `<select>` from `options: { value, label, group?, disabled? }[]` (neighbours with one `group` sit under an `optgroup`); `Select.configure`. `Select.toView` is the adapter. For icons, descriptions or a check in the list, draw a Listbox as a custom select with `Listbox.parts`. | `size`: `sm`, `md` (default), `lg`; `variant`: `outline` (default), `filled`. Slots `root`, `select`, `label`, `description`. |
|
|
1186
|
+
| `Listbox` | A custom select. `Listbox.view({ model, onMessage, label, choice, value, items?, option?, groupBy?, heading?, placeholder?, trigger?, clear?, disabled?, invalid?, readOnly?, name?, anchor?, direction?, words?, style?, mixins? }, h)` draws it over the interaction state `Bundles.Listbox` holds and a value the application owns, read through a `Choice` (`Listbox.one(items)`, `Listbox.many(items)`, or your own); a row is `RowContent`. The trigger is named "label: chosen rows" and shows the chosen row's icon and label, several labels joined, or the placeholder, muted; `trigger: rows => Html` draws something else for them (a stack of dots). `clear: { onClear, content? }` draws a button inside the trigger while something is chosen, and sends the application's own Message, since the value is the application's. `Listbox.configure({ base, presets })` binds `placeholder`, `anchor`, `direction`, `words`, `style` and `mixins`. A closed listbox submits its value under `name`. `Listbox.fluid` and `Listbox.overlayBars` are files of their own. `Listbox.toView`, `resolve` and `parts` are the adapter over a fork (see [Why some components needed a fork](#why-some-components-needed-a-fork)) for a drawing of your own: `parts(mixins, { h }).option(rowContent)` draws a row and `.trigger(chosenRows, placeholder, shown?)` the button's content. An invalid trigger writes `aria-invalid` and draws the error edge, a disabled one shows no hover, and a portaled panel carries the `direction`. | `width`: `auto` (default), `trigger`; `check`: `end` (default), `start`, `none`; `trigger`: `outline` (default), `filled`, `ghost`; `size`. Slots `root`, `wrapper`, `button`, `clear`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator`, `rows`, `highlight`, `indicator`, `scrollBar`, `scrollThumb`, the option's and trigger's parts (`itemIcon`, `itemLabel`, `itemDescription`, `itemTrailing`, `itemCheck`, `value`, `valueText`, `chevron`, …). |
|
|
1187
|
+
| `Combobox` | Adapter over a fork, single and multi. `Combobox.view({ model, onMessage, label, choice, value, … }, h)` draws it from options ([State](#state-fold-it-by-hand-or-place-a-bundle)). On the adapter, the view inputs add `chips: {}` (each chosen value a chip in the field, labelled by `itemToDisplayText`, its remove button choosing it again; with `ComboboxView.Multi`, a tags field with suggestions), `clearContent` and `clearLabel` (a clear button while the field has text; `clearContent: null` draws a cross), `words: { clear?, remove? }`, and `empty` (shown, as a polite status, in the list's place while open with nothing to list; a loading line too). `Combobox.parts(mixins, { h }).option(content, query)` draws a `RowContent` and marks the typed text in its label. A closed combobox submits its value under `formName` too. Home and End move the caret in the text: the list's ends are not bound to them. An invalid combobox writes `aria-invalid` on the input and draws the error edge on the field; the clear button is a touch-sized target. | `width`: `trigger` (default), `auto`; `size`. Slots as the Listbox's with `wrapper`, `inputWrapper`, `input`, `toggleButton`, `chips`, `chip`, `chipRemove`, `clearButton`, `empty`, `itemTrailing`. |
|
|
1188
|
+
| `Picker` | A select that is a dropdown on a desktop and a bottom sheet on a phone, with one Model and one set of Messages whatever the width. `Picker.view({ model, onMessage, label, choice, value, items?, option?, groupBy?, heading?, placeholder?, clear?, disabled?, invalid?, name?, anchor?, words?, style?, mixins?, listbox?, sheet?, routes? }, h)` takes the Listbox's `choice` (`Picker.one(items)`, or your own choice of at most one item) and draws both halves from it; `Bundles.Picker` holds the state and reports the `Selected` a choice in either half is. `Picker.configure({ base, presets })`. A small Model remains for the hand-written fold: `Picker.init({ id, sheet? })` and `Picker.update`, which returns `Picker.OutMessage.Chose({ value })`. See [Picker](#picker). | `sheetBelow`: `sm`, `md` (default), `lg`; `trigger`: `outline` (default), `filled`, `ghost`; `size`. Slots `root`, `dropdown`, `opener`, `list`, `option`, `group`, `heading`. |
|
|
1189
|
+
| `CascadeSelect` | After Zag's: one value chosen as a path of ids through nested options. The path is the widget's own value: `Bundles.CascadeSelect` holds it (and the path the keys are on) with the options, `config: { nodes, parents?, loop?, closeOnSelect?, inline? }`, as its args, and reports `Changed` when it moves; `helpers.set(path)` sets it from the parent and reports nothing. `CascadeSelect.view({ model, config, onMessage, label, placeholder?, levels?, layout?, expandOn?, separator?, triggerText?, clear?, option?, name?, disabled?, invalid?, direction?, words?, routes?, style? }, h)`; `option: node => RowContent` draws a row's icon, description and trailing part, `triggerText` the trigger's text for the chosen labels, `config.inline` the tree in place with no trigger. `CascadeSelect.configure`. A hand-written fold stays: `CascadeSelect.init`, `update(config)`. See [CascadeSelect](#cascadeselect). | `size`; `trigger`: `outline`, `filled`, `ghost`; `width`: `trigger`, `auto`. Slots `root`, `trigger`, `valueText`, `chevron`, `clear`, `input`, `layer`, `backdrop`, `panel`, `column`, `heading`, `back`, `item`, `itemIcon`, `itemText`, `itemLabel`, `itemDescription`, `itemTrailing`, `branch`. |
|
|
1190
|
+
| `Slider` | Native `input type="range"` thumbs, so drag, keys, right to left and the form value are the browser's. `Slider.view({ id, label, value, onChange, onCommit?, description?, min?, max?, step?, format?, marks?, showValue?, name?, disabled?, orientation?, ticks?, words? }, h)`; `value` is a number, a `{ low, high }` range or a list of numbers (a thumb each, stopping at its neighbours), and `onChange` is handed the same kind. `words` names a range's thumbs (`low`, `high`) and a list's (`thumb`, with `{index}` and `{count}`). `Slider.configure`. See [Slider](#slider). | `tone`: `accent` (default), `neutral`; `size`: `sm`, `md` (default), `lg`; `track`: `thick` (default), `thin`, `paint`; `value`: `above` (default), `inside`, `end`; `label`: `shown` (default), `hidden`. Slots `root`, `label`, `description`, `control`, `track`, `fill`, `mark`, `value`, `thumb`. |
|
|
1191
|
+
| `AngleSlider` | After Zag's: a dial in degrees, 0 at the top and clockwise. A small Model: `AngleSlider.init({ id, value? })` is the angle and the drag, folded with `AngleSlider.update(layout)`, where `layout` (`step`, `largeStep`, `marks`, `restrictToMarks`) is the object the view spreads in too; `Bundles.AngleSlider` packages both, with the layout as its args (`Bundles.AngleSlider.with({ id, ...layout })`), and `AngleSlider.configure` states the look, layout and `words` (`degrees`, the angle read aloud) once. `AngleSlider.view({ ...layout, model, onMessage, label, name?, format?, valueText?, showValue?, disabled?, readOnly?, invalid? }, h)`. A press or drag sends `Pointed` and `Released`; the APG's slider keys reach `update` as what was pressed, and go round past 0. | `tone`; `track`: `ring`, `plain`, `disc`; `value`: `inside`, `below`; `size`. Slots `root`, `label`, `control`, `needle`, `thumb`, `markers`, `marker`, `markerLabel`, `value`, `input`. |
|
|
1192
|
+
| `Rating` | A `radiogroup` of native radios named by its label, one per star under one name, so the browser's arrows move the choice and a form submits it. `Rating.view({ id, label, value, onChange, max?, labels?, words?, readOnly?, disabled?, name?, precision?, onClear?, showValue? }, h)`; `value` is an `Option`, none is unrated. `words` is the text with blanks (`one`, `other`, `rated`, `notRated`); `labels` names each whole number of stars. Read-only, it is one `img` whose name says the rating, and takes no `onChange`. `Rating.configure`. | `tone`: `warning` (default, gold), `accent`, `danger`, `success`, `info`, `neutral`; `glyph`: `star` (default), `heart`, `circle`; `size`. Slots `root`, `label`, `star`. |
|
|
1193
|
+
| `ColorPicker` | After ReUI's: a saturation and brightness area, hue and alpha Sliders, an eyedropper when the application asks for one (`eyedropper`, default `false`), text in hex, rgb, hsl or oklch, and `presets` as a radio group of swatches. A small Model: `ColorPicker.init({ id, color?, format? })` holds the color, its format and a draft being typed, folded with `ColorPicker.update`. `ColorPicker.view({ model, onMessage, label, presets?, alpha?, eyedropper?, words?, disabled?, slider?, style?, mixins? }, h)`; `ColorPicker.popover({ ...options, popover, onPopover, anchor?, popoverMixins? }, h)` draws it behind a swatch in a Popover. See [ColorPicker](#colorpicker). | `size`. Its Sliders take `Recipes.Slider({ track: 'paint', label: 'hidden' })`. Slots `root`, `label`, `area`, `areaThumb`, `controls`, `eyedropper`, `channels`, `channel`, `swatch`, `fields`, `format`, `input`, `presets`, `preset`, `picker`, `trigger`, `value`. |
|
|
1194
|
+
| `Calendar` | One date system, inline. `Calendar.Selection` is `Single`, `Range` or `Multiple`, held by the Calendar's state (`Bundles.Calendar`), or by the application on the adapter rung. See [Calendar and DatePicker](#calendar-and-datepicker). | `size`; `outside`: `shown` (default), `hidden`; `detail`: `text`, `dot`, unset by default. Slots `frame`, `body`, `main`, `months`, `todayButton`, `aside`, `footer` (what `Calendar.view` lays around the months), `root`, `header`, `grid`, `headerRow`, `previousMonthButton`, `nextMonthButton`, `headingButton`, `previousPageButton`, `nextPageButton`, `columnHeader`, `weekRow`, `dayCell`, `dayButton`, `monthCell`, `monthButton`, `yearCell`, `yearButton`. |
|
|
1195
|
+
| `DatePicker` | A Calendar in a popover, over a fork that keeps upstream's Popover and Calendar composition. A date, a range or many days. See [Calendar and DatePicker](#calendar-and-datepicker). | Slots `wrapper`, `trigger`, `panel`, `backdrop`. |
|
|
1196
|
+
|
|
1197
|
+
### Segmented
|
|
1198
|
+
|
|
1199
|
+
A single choice (the default) is a radio group: a `role="radiogroup"` of
|
|
1200
|
+
`role="radio"` options with `aria-checked`, one tab stop, and the arrows, Home and
|
|
1201
|
+
End move the choice and the focus. It requires `id`, which prefixes the options'
|
|
1202
|
+
ids, since the arrows move focus by them; `direction: 'rtl'` swaps ArrowLeft and
|
|
1203
|
+
ArrowRight. With `multiple: true` it is a toggle group, shadcn's and Zag's: a
|
|
1204
|
+
`role="group"` of `aria-pressed` buttons, each a tab stop and each filling itself
|
|
1205
|
+
(draw it without `Segmented.fluid`, whose pill marks one). `name` submits the
|
|
1206
|
+
chosen values as hidden inputs; `disabled` turns the group off (`aria-disabled`,
|
|
1207
|
+
no key or press taken). An option takes an `icon`, alone with `iconOnly` (named by
|
|
1208
|
+
`aria-label` and `title`). Its `indicator` and `highlight` Slots, drawn first in
|
|
1209
|
+
the group and given `Segmented.fluid`, slide the pressed option's pill to a new
|
|
1210
|
+
press and move the hover to the option the pointer is on (see [Fluid
|
|
1211
|
+
highlights](#fluid-highlights)); until it runs the pressed option fills itself.
|
|
1212
|
+
|
|
1213
|
+
The recipe: the chosen option takes the accent's tint, flat; that rule lives on the group, in
|
|
1214
|
+
`variants`, so icon tiles take the group piece alone, and an icon button's own background, a
|
|
1215
|
+
variant too, does not hide it. `tray` is a muted tray, a plain row (which sets no `display`: the
|
|
1216
|
+
Builder owns its narrow tabs' visibility; its options tint themselves on hover as every hover is)
|
|
1217
|
+
or an `underline`, each as wide as its options (`width: 'fill'` for a strip as wide as its
|
|
1218
|
+
container). `size` steps the tray and its options on the ladder (`xs` a half step below compact,
|
|
1219
|
+
24px), the tray's inset counted in, so a tray is as tall as a button beside it.
|
|
1220
|
+
|
|
1221
|
+
The recipe's tray and size are selected per slot:
|
|
736
1222
|
|
|
737
1223
|
```ts
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
1224
|
+
const SegmentedStyle = Style.forSlots(SegmentedSlots)(
|
|
1225
|
+
{
|
|
1226
|
+
group: Recipes.Segmented({ tray: 'plain', size: 'sm' }).group,
|
|
1227
|
+
option: Recipes.Segmented({ tray: 'plain', size: 'sm' }).option,
|
|
1228
|
+
},
|
|
1229
|
+
{ layer: Layers.standard.layer('app') },
|
|
744
1230
|
)
|
|
1231
|
+
```
|
|
745
1232
|
|
|
746
|
-
|
|
747
|
-
const theme = Theme.make({ accent: { hue: 280, chroma: 0.15, lightness: 60 } })
|
|
1233
|
+
Then a toggle group draws the options from the application's pressed values:
|
|
748
1234
|
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
1235
|
+
```ts
|
|
1236
|
+
Segmented.view(
|
|
1237
|
+
{
|
|
1238
|
+
multiple: true,
|
|
1239
|
+
label: 'Text style',
|
|
1240
|
+
options: [
|
|
1241
|
+
{ value: 'bold', label: 'Bold' },
|
|
1242
|
+
{ value: 'italic', label: 'Italic' },
|
|
1243
|
+
],
|
|
1244
|
+
pressed: model.marks,
|
|
1245
|
+
onPress: mark => Message.ToggledMark({ mark }),
|
|
1246
|
+
style: SegmentedStyle,
|
|
1247
|
+
},
|
|
1248
|
+
h,
|
|
753
1249
|
)
|
|
1250
|
+
// in update: modifyFields(model, { marks: () => Segmented.toggled(model.marks, mark, { multiple: true }) })
|
|
754
1251
|
```
|
|
755
1252
|
|
|
756
|
-
|
|
1253
|
+
### Switch and Checkbox
|
|
1254
|
+
|
|
1255
|
+
`Checkbox.view` and `Switch.view` draw the whole row from options: the control,
|
|
1256
|
+
its label, a line of description that also describes it, and a `labelAside` slot
|
|
1257
|
+
beside the label. The row carries `data-checked`, `data-disabled`, `data-invalid`
|
|
1258
|
+
and `data-position` for the recipe, so `variant: 'card'` (the row boxed, filled
|
|
1259
|
+
while checked, one press target with the label stretched over it) is CSS over the
|
|
1260
|
+
same markup. `Checkbox.toView` and `Switch.toView` stay the adapters, for a
|
|
1261
|
+
layout of your own.
|
|
1262
|
+
|
|
1263
|
+
`Switch.draggable(onToggle)` beside the style lets the thumb be dragged: it
|
|
1264
|
+
follows the pointer past 4px, and on release `onToggle` is sent for the side its
|
|
1265
|
+
middle is on (nothing when that is the side it began on); a click after a drag is
|
|
1266
|
+
swallowed, right to left mirrors it, and a disabled or read-only switch does not
|
|
1267
|
+
drag. The thumb is held where it was let go for 300ms or until `aria-checked`
|
|
1268
|
+
changes, so an `update` that refuses the toggle sends it back. Pass the
|
|
1269
|
+
`onToggle` the view was given.
|
|
1270
|
+
|
|
1271
|
+
### Picker
|
|
1272
|
+
|
|
1273
|
+
Both halves are drawn and the recipe shows one, so nothing reads the width: the
|
|
1274
|
+
Listbox (its panel kept in place) at or above the breakpoint, and below it an
|
|
1275
|
+
opener whose Sheet lists the options as a listbox, the chosen one (or the first)
|
|
1276
|
+
focused, the arrows, Home and End moving focus, Enter, Space or a tap choosing and
|
|
1277
|
+
closing it. The application keeps the value, read through the Listbox's `Choice`, and
|
|
1278
|
+
`Value` is inferred from the `choice` (`Picker.one(items)`: at most one item,
|
|
1279
|
+
since the Sheet closes at a pick). Rows are `RowContent`; `groupBy` and `heading`
|
|
1280
|
+
group them in the dropdown and in the Sheet; `clear` draws the Listbox's button
|
|
1281
|
+
beside the trigger and beside the opener; `name` submits the choice once.
|
|
1282
|
+
Opening the Sheet closes a Listbox left open. `listbox` takes `Recipes.Listbox`, which also draws the options' and the
|
|
1283
|
+
trigger's content (`Listbox.parts`), and `sheet` takes `Recipes.Sheet`. `routes`
|
|
1284
|
+
are [application key routes](#application-key-routes) on a Sheet option
|
|
1285
|
+
(`item.index` is its place); the dropdown's keys are the Listbox's.
|
|
1286
|
+
|
|
1287
|
+
### CascadeSelect
|
|
1288
|
+
|
|
1289
|
+
The trigger is a combobox opening a top-layer APG tree, a column per level or one
|
|
1290
|
+
level at a time (`layout: 'drill'`; the columns also drill in on their own when
|
|
1291
|
+
they would not fit the window, measured as the popup opens). `config` is `{ nodes,
|
|
1292
|
+
parents?, closeOnSelect?, loop? }`, the same object the view takes; only an
|
|
1293
|
+
option without children is chosen unless `parents` allows any. The arrows move
|
|
1294
|
+
within and between levels (swapped right to left), Home and End jump to the ends,
|
|
1295
|
+
letters typed within half a second find the row whose label starts with them
|
|
1296
|
+
(`CascadeSelect.Model.typeahead`, cleared by the `QueryExpired` Message), Enter and
|
|
1297
|
+
Space choose (Space opens the closed trigger too). With `name` a form submits one
|
|
1298
|
+
hidden `input` per level of the path (an id may hold any character, so no
|
|
1299
|
+
separator joins them), or one empty input when nothing is chosen.
|
|
1300
|
+
|
|
1301
|
+
The chosen path is the widget's own value, so `Bundles.CascadeSelect` holds it: its
|
|
1302
|
+
args are `{ id, value?, config }`, the `config` object the view takes too, and it
|
|
1303
|
+
reports `Changed { value }` when the path moves (answer `Bundle.ignore` where the
|
|
1304
|
+
parent only reads `model.<field>.value`). `helpers.set(path)` is how the parent
|
|
1305
|
+
writes it: an empty path clears, a path that cannot be chosen is ignored, and
|
|
1306
|
+
nothing is reported. The fixed text is `words` (`placeholder`, `clear`, `back` with
|
|
1307
|
+
`{label}`), and `clear: true` (or `{ content }`) draws the button that empties the
|
|
1308
|
+
value. `option: node => RowContent` draws a row's `icon`, `description` and
|
|
1309
|
+
`trailing` (its `disabled` is the node's); `triggerText: labels => string` collapses a
|
|
1310
|
+
long path on the trigger; `config.inline` draws the tree in place, always open,
|
|
1311
|
+
with no trigger, which Tab focuses (pass the same `config` to `init` or the
|
|
1312
|
+
Bundle). Not built: several chosen paths (a tree with indeterminate branches), a
|
|
1313
|
+
search field in the panel, a footer or side panel, and a loading level.
|
|
1314
|
+
|
|
1315
|
+
### Slider
|
|
1316
|
+
|
|
1317
|
+
`onCommit` is sent with the value when the reader lets go (the range input's
|
|
1318
|
+
native `change`, which fires on release after a drag and on each key press, where
|
|
1319
|
+
`onChange` has sent every step on the way), and `description` is a line under the
|
|
1320
|
+
slider that each thumb is described by. One number is one thumb across the track,
|
|
1321
|
+
named by the label; a press anywhere on the track moves it. A range is a `group`
|
|
1322
|
+
named by its label holding two thumbs named by `words.low` and `words.high`
|
|
1323
|
+
(default `Minimum` and `Maximum`), each bounded by the other, so the browser stops a drag or a key at
|
|
1324
|
+
the other thumb; `Slider.moved(range, 'low' | 'high', value, bounds)` snaps,
|
|
1325
|
+
bounds and orders a range, and returns the same range when nothing changed.
|
|
1326
|
+
`marks` are values dotted on the track (`data-filled` where the fill covers
|
|
1327
|
+
them) and `showValue` draws each value, both hidden from assistive technology,
|
|
1328
|
+
which hears `aria-valuetext`; a mark may be `{ value, label }` (`SliderMark`), its
|
|
1329
|
+
words under the track, those at either end flush with its ends. `orientation:
|
|
1330
|
+
'vertical'` stands it upright; `ticks` dots every step. A Slider is at least 12rem
|
|
1331
|
+
wide; a holder that lays it narrower sets `--fk-slider-min-length`. `@foldkit/ui`'s
|
|
1332
|
+
Slider is not adapted: draw its Submodel with Slots of your own.
|
|
1333
|
+
|
|
1334
|
+
### Rating
|
|
1335
|
+
|
|
1336
|
+
`precision: 0.5` draws two radios a star; a read-only value of any fraction fills
|
|
1337
|
+
its last star part way. `onClear` is sent by a press on the star already chosen;
|
|
1338
|
+
`showValue` shows the rating beside the stars, said as `words` or `labels` say it. Home and End on a
|
|
1339
|
+
star are a key route that focuses the first or last star by its id
|
|
1340
|
+
(`<id>-<value>`) and chooses it, as the arrows would; a read-only or disabled
|
|
1341
|
+
rating draws no route. `name` defaults to `id`. Its tones are the shared `Recipes.Tone` vocabulary.
|
|
1342
|
+
|
|
1343
|
+
### ColorPicker
|
|
1344
|
+
|
|
1345
|
+
Keys and drags reach `update` as what was pressed, so fast keys each step from the
|
|
1346
|
+
last color. `ColorPicker.popover` takes a Popover made with `contentFocus: true`
|
|
1347
|
+
(it throws for one without): the panel opens on the area's thumb, a press or a
|
|
1348
|
+
drag inside never closes it, and focus leaving it closes one the keys or a finger
|
|
1349
|
+
opened (a mouse's stays open, as upstream's Popover does). `popover` is a file of
|
|
1350
|
+
its own, so a page drawing the picker inline keeps neither upstream's Popover nor
|
|
1351
|
+
its anchoring. The picker's own words are `words` (`ColorPicker.words`: `area`,
|
|
1352
|
+
`saturation`, `brightness`, `hue`, `alpha`, `format`, `input`, `eyedropper`,
|
|
1353
|
+
`presets`), `Bundles.ColorPicker.with({ id, color?, format? })` places its state and
|
|
1354
|
+
reports `Changed { color }`, and `ColorPicker.configure({ base, presets })` fixes the
|
|
1355
|
+
swatches, the sliders' look and the words once.
|
|
1356
|
+
|
|
1357
|
+
The view reads nothing from the environment, so the eyedropper button is the
|
|
1358
|
+
`eyedropper` input, `false` by default on a server and in a browser alike.
|
|
1359
|
+
`ColorPicker.canEyedrop()` is the pure feature test; call it where the
|
|
1360
|
+
application learns its environment and keep the answer in the Model. An
|
|
1361
|
+
application that only runs in a browser reads it in `init`:
|
|
757
1362
|
|
|
758
|
-
|
|
1363
|
+
```ts
|
|
1364
|
+
import { Schema } from 'effect'
|
|
1365
|
+
import { ColorPicker } from 'foldkit-mixins-ui'
|
|
759
1366
|
|
|
760
|
-
|
|
761
|
-
the shipped tokens (`Theme.standard`), so another theme's knobs restyle
|
|
762
|
-
every recipe with no new CSS.
|
|
763
|
-
- **Bases sit in `components`, variants in `variants`** of `Layers.standard`,
|
|
764
|
-
so an application's `app` layer overrides both without specificity fights.
|
|
765
|
-
Every declaration is a layered rule and none is inline style, since inline
|
|
766
|
-
style beats every layer and could not be overridden this way:
|
|
1367
|
+
const PickerModel = Schema.Struct({ picker: ColorPicker.Model, eyedropper: Schema.Boolean })
|
|
767
1368
|
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
element). `--fk-knob-step: 1` on any element makes everything inside it
|
|
780
|
-
compact, the popups it opens included when they stay in the page (an
|
|
781
|
-
anchor's `portal: false`, as the gallery's do); upstream portals a panel
|
|
782
|
-
out of the page by default, where no region reaches it. A recipe's `size`
|
|
783
|
-
(`sm` compact, `md` default, `lg` a half step up at 40px) sets the step on
|
|
784
|
-
its own element and beats the region, and a popup's sets it on its panel
|
|
785
|
-
too, so it holds portaled or not; unset, which is the default, follows the
|
|
786
|
-
region. An icon, checkbox, radio or switch with no size stands on the
|
|
787
|
-
ladder's icon rung, 16px or 14px compact.
|
|
788
|
-
- **Text comes in roles.** `Theme.role(name)` is a size and its leading,
|
|
789
|
-
stepping with the ladder: `display`, `title`, `subtitle`, `body` (a
|
|
790
|
-
control's text, 14px on 20), `caption` (badges, tooltips, a table's
|
|
791
|
-
headings) and `micro` (keycaps). A tab's and a segmented option's label is
|
|
792
|
-
trimmed to its capitals (`text-box`), centering it optically; a pressed
|
|
793
|
-
segmented option and a chosen card title turn semibold without moving
|
|
794
|
-
anything (the card writes its title in `data-label`; give an option its
|
|
795
|
-
text there, `h.DataAttribute('label', 'Week')`, and draw its words in the
|
|
796
|
-
`label` Slot, which holds the trim: on the option itself, the hidden copy
|
|
797
|
-
took the trim's lower half); and a field's text is 16px on a coarse
|
|
798
|
-
pointer, so iOS Safari does not zoom the page into it.
|
|
799
|
-
- **A state is a tint, not a surface.** An unfilled control's hover is a
|
|
800
|
-
faint film of the state ink over whatever is under it, so it reads on a
|
|
801
|
-
muted page, a colored band or an inverted panel; a press lays that film
|
|
802
|
-
stronger (`state.press`, 1.75 of the hover's). The ink is the theme's
|
|
803
|
-
`--fk-state-ink` (`state.ink`: the element's own text, or the accent's ink
|
|
804
|
-
under `surface.hover: 'accent'`) unless a painted surface above names its paint
|
|
805
|
-
in the local `--_fk-state-ink`: the accent and danger tones name their
|
|
806
|
-
fill, a subtle alert band its ink and a bold one its fill, so a hover on
|
|
807
|
-
blue is a deeper blue. The neutral and ink tones name the theme's ink back,
|
|
808
|
-
so a neutral control on a band does not take the band's hue, and one
|
|
809
|
-
`surface.hover` choice reaches every component. The neutral button is
|
|
810
|
-
see-through (`state.tint`), and images carry a hairline inside their edge
|
|
811
|
-
(`state.edge`). A popup's rows round concentrically inside its panel
|
|
812
|
-
(`Theme.nested`), as a segmented option does inside its tray. A fluid
|
|
813
|
-
highlight — Table's, Segmented's, pill Tabs', Nav's, TreeView's, a Card
|
|
814
|
-
group's — lays that same film, so `surface.hover` and
|
|
815
|
-
`surface.hoverStrength` move it with every other hover.
|
|
816
|
-
- **Popups and dialogs enter and leave** when drawn with `@foldkit/ui`'s
|
|
817
|
-
`isAnimated` (the Menu component's `Menu.init(id, rows, { isAnimated:
|
|
818
|
-
true })`): a popup fades and grows on the fast tier, from the side its
|
|
819
|
-
anchor placed it on, and a dialog on the slow one, each leaving on the
|
|
820
|
-
quicker exit.
|
|
821
|
-
- **A press gives.** Held, every button scales to 98% (the 2% multiplied by
|
|
822
|
-
`travel`, so reduced motion holds its size). A solid or primary button's
|
|
823
|
-
fill also deepens to its family's `active` and clears the 1px border of its
|
|
824
|
-
own color that it stands in, so the fill draws in by 1px a side; an
|
|
825
|
-
outline, ghost or icon button lays a deeper film of its tone's ink. A
|
|
826
|
-
pressed toggle (`aria-pressed="true"`) rests on its tone's fill, a solid
|
|
827
|
-
one on the `active` fill; hovered, a solid toggle keeps it and an unfilled
|
|
828
|
-
one takes its tone's hover fill; held, it deepens to the `active` fill; and
|
|
829
|
-
its text stays the fill's throughout. A hovered row, tab, menu item or
|
|
830
|
-
accordion row darkens while the press is held, and a fluid highlight darkens
|
|
831
|
-
with the item it lights (`FluidHover` marks the container `data-fluid-held`).
|
|
832
|
-
Chosen rows next to each other in a multiple listbox or
|
|
833
|
-
combobox merge into one block. A disabled control fades by
|
|
834
|
-
`state.disabledOpacity` (half by default), so one page shows one fade.
|
|
835
|
-
- **Raised surfaces nest.** Popups, popovers, date picker panels and toasts
|
|
836
|
-
sit two levels above what holds them and dialogs four (`Theme.raise`), each
|
|
837
|
-
painted for its level, so a popover in a dialog lands above the dialog: a
|
|
838
|
-
step lighter in a dark scheme, the same flat surface with its own shadow in
|
|
839
|
-
a light one.
|
|
840
|
-
- **State comes from the component's own attributes.** Checked, selected, and
|
|
841
|
-
disabled looks read `aria-checked`, `aria-selected`, and `aria-disabled`,
|
|
842
|
-
which `@foldkit/ui` already writes; no `whenInput` is needed.
|
|
843
|
-
- **Tone and variant are independent.** A tone sets a few private custom
|
|
844
|
-
properties that `solid`, `outline`, and `ghost` read — except `primary`,
|
|
845
|
-
which is ink by definition, and `icon`, a square one rung of the size
|
|
846
|
-
ladder on a side. A tone
|
|
847
|
-
also carries the line an `outline` draws: the fill, or for `neutral`, whose
|
|
848
|
-
fill is a quiet grey, the page's default line. A neutral Checkbox or Switch
|
|
849
|
-
that is on is in the page's ink, not the neutral grey, so it stands out
|
|
850
|
-
without a color.
|
|
851
|
-
- **On a colored band, unfilled buttons take the band's color.** `outline` and
|
|
852
|
-
`ghost` draw their text in the tone's ink, which reads on the page's surface
|
|
853
|
-
and not on a band of the accent. A band sets
|
|
854
|
-
`Style.vars({ '--fk-ink': 'currentColor' })`, beside `--fk-heading` for its
|
|
855
|
-
headings, and their text is the band's.
|
|
856
|
-
|
|
857
|
-
Adjust a recipe with `extend` instead of forking it. Base pieces compose per
|
|
858
|
-
slot, a variant's pieces compose over the shipped ones, and compounds append:
|
|
1369
|
+
const initPicker = () => ({
|
|
1370
|
+
model: {
|
|
1371
|
+
picker: ColorPicker.init({ id: 'accent' }),
|
|
1372
|
+
eyedropper: ColorPicker.canEyedrop(),
|
|
1373
|
+
},
|
|
1374
|
+
})
|
|
1375
|
+
```
|
|
1376
|
+
|
|
1377
|
+
A server-rendered application starts `false`, so the served markup and the
|
|
1378
|
+
browser's first render agree, and learns the answer after it has taken over, so
|
|
1379
|
+
the button appears instead of the picker's controls being rebuilt:
|
|
859
1380
|
|
|
860
1381
|
```ts
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
1382
|
+
import { Effect, Schema } from 'effect'
|
|
1383
|
+
import * as Command from 'foldkit/command'
|
|
1384
|
+
import { defineMessageUnion } from 'foldkit/message'
|
|
1385
|
+
import { ColorPicker } from 'foldkit-mixins-ui'
|
|
1386
|
+
|
|
1387
|
+
const EyedropperMessage = defineMessageUnion({
|
|
1388
|
+
LearnedEyedropper: { available: Schema.Boolean },
|
|
864
1389
|
})
|
|
1390
|
+
|
|
1391
|
+
// Send it from the Command that starts the application, with the first frame drawn.
|
|
1392
|
+
const LearnEyedropperCommand = Command.define('LearnEyedropper', {
|
|
1393
|
+
messages: [EyedropperMessage.LearnedEyedropper],
|
|
1394
|
+
execute: Effect.sync(() =>
|
|
1395
|
+
EyedropperMessage.LearnedEyedropper({ available: ColorPicker.canEyedrop() }),
|
|
1396
|
+
),
|
|
1397
|
+
})
|
|
1398
|
+
```
|
|
1399
|
+
|
|
1400
|
+
Either way the view is given `eyedropper: model.eyedropper`. Pressing the button
|
|
1401
|
+
runs `ColorPicker.Eyedrop`, which answers `CancelledEyedropper` and nothing else
|
|
1402
|
+
when the runtime has no eyedropper or the user closes it: a cancel changes
|
|
1403
|
+
nothing and shows nothing.
|
|
1404
|
+
|
|
1405
|
+
`ColorPicker.color('#3b82f6')` reads a literal in code (it throws on a typo);
|
|
1406
|
+
`format`, `parse` (an `Option`) and `toOklch` are pure. `ColorPicker.Eyedrop` and
|
|
1407
|
+
`canEyedrop` are the eyedropper's Command and check.
|
|
1408
|
+
|
|
1409
|
+
### Calendar and DatePicker
|
|
1410
|
+
|
|
1411
|
+
A Calendar's value is a `Calendar.Selection`: `Single`, `Range` or `Multiple`,
|
|
1412
|
+
a type of the Calendar's own, so the Calendar's state holds it. `Calendar.init`
|
|
1413
|
+
makes that state (the month shown, a second month, the selection, a range's
|
|
1414
|
+
hover preview), `Calendar.update` folds it, and `Calendar.view(options, h)`
|
|
1415
|
+
draws it. `Bundles.Calendar` is the same `init` and `update` for
|
|
1416
|
+
`foldkit-bundle`; [State](#state-fold-it-by-hand-or-place-a-bundle) has a whole
|
|
1417
|
+
example.
|
|
1418
|
+
|
|
1419
|
+
- **Args** (`Calendar.Args`, also `init`'s options): `id`, `today`, and
|
|
1420
|
+
optionally `selection` (default `Calendar.empty('Single')`), `months` (`1` or
|
|
1421
|
+
`2`), `minDate`, `maxDate`, `disabledDaysOfWeek`, `disabledDates` and `locale`
|
|
1422
|
+
(`Calendar.localeOf('de-DE')` reads one from Intl).
|
|
1423
|
+
- **Reading the value**: `Calendar.selectedDate` (a Single's day), `rangeOf`
|
|
1424
|
+
(a range with both ends), `datesOf` (every day held, in order), `firstDate`,
|
|
1425
|
+
`isComplete`. The Bundle reports `Changed { selection }` whenever the
|
|
1426
|
+
selection holds other days; its `set` helper, and `Calendar.set(model,
|
|
1427
|
+
selection)`, set it from the parent and report nothing.
|
|
1428
|
+
- **View options**, all optional beyond `model`, `onMessage` and `label` (the
|
|
1429
|
+
group's name): `weekNumbers`; `caption`: `'grid'` (the default heading
|
|
1430
|
+
button, which opens the month and year grids), `'label'`, or `{ dropdowns: {
|
|
1431
|
+
years?, month? } }`, where `month: 'label'` writes the month as text beside a
|
|
1432
|
+
select of years; `paging`: `'both'`, `'previous'`, `'next'`, `'none'`, or
|
|
1433
|
+
`'end'` for both buttons after the caption; `today: { label, selects? }`, a
|
|
1434
|
+
button that turns back to today's month and, with `selects`, picks it;
|
|
1435
|
+
`presets`, a list of `{ label, selection }` built with `Calendar.lastDays`,
|
|
1436
|
+
`nextDays`, `monthOf` and `day`, or written by hand; `detail: date =>
|
|
1437
|
+
Option<string>`, a line under a day's number; `aside` and `footer`, drawings
|
|
1438
|
+
of the application's own placed beside and under the months; `words`
|
|
1439
|
+
(`Calendar.words` lists them; `{month}`, `{date}`, `{year}`, `{from}` and
|
|
1440
|
+
`{to}` are filled); `style` and `mixins`.
|
|
1441
|
+
- **Two months** share one selection and page together: the previous button is
|
|
1442
|
+
on the first, the next on the second, and dropdowns are on the first.
|
|
1443
|
+
- **A time list, an event list, a second field** is another widget with its own
|
|
1444
|
+
state, drawn into `aside` or `footer`. The Calendar places it and knows
|
|
1445
|
+
nothing of it.
|
|
1446
|
+
- **`Calendar.configure({ base, presets })`** binds `weekNumbers`, `caption`,
|
|
1447
|
+
`paging`, `today`, `presets`, `detail`, `words`, `style` and `mixins`
|
|
1448
|
+
([Drawing](#drawing-configure-once-call-with-what-differs)). Its `presets`
|
|
1449
|
+
key names sets of options; the view option `presets` lists selections.
|
|
1450
|
+
- **What it costs**: a page that draws through the adapter below keeps neither
|
|
1451
|
+
the state nor this view. Upstream's month and year grids ship with every
|
|
1452
|
+
calendar, since they are inside upstream's one Model and view; `caption:
|
|
1453
|
+
'label'` hides them and cannot drop them.
|
|
1454
|
+
|
|
1455
|
+
A DatePicker is the same Calendar in a popover, with the same split.
|
|
1456
|
+
`DatePicker.init(args)` makes its state (upstream's picker, the selection, a
|
|
1457
|
+
range's preview), `DatePicker.fold(model, message)` folds it, and
|
|
1458
|
+
`Bundles.DatePicker` packages both; it reports `Changed { selection }` as the
|
|
1459
|
+
Calendar's Bundle does. `DatePicker.view(options, h)` draws it:
|
|
1460
|
+
|
|
1461
|
+
- **`trigger: selection => string`** is the trigger's text, required: a date,
|
|
1462
|
+
both ends of a range, or a prompt. `label` names the trigger.
|
|
1463
|
+
- **`name`** submits each chosen day as an ISO date, a range's start then its
|
|
1464
|
+
end; **`disabled`** and **`anchor`** are the popover's (the default stands
|
|
1465
|
+
under the trigger's start and is not portaled).
|
|
1466
|
+
- **The Calendar's options go to the panel**: `weekNumbers`, `caption`,
|
|
1467
|
+
`paging`, `today`, `presets`, `detail`, `aside`, `footer` and `words`. A
|
|
1468
|
+
picker holds one month.
|
|
1469
|
+
- **Two styles**: `style` of `DatePickerSlots` (wrapper, trigger, panel, backdrop) and
|
|
1470
|
+
`calendarStyle` of `CalendarSlots`, with `calendarMixins` beside it.
|
|
1471
|
+
- **Closing** is the arg `closes`. `'complete'` (the default) closes the
|
|
1472
|
+
popover on the pick, or the preset, that makes the selection whole: a day,
|
|
1473
|
+
or a range's second end. `'manual'` closes on none, which a picker with a
|
|
1474
|
+
time list in `aside` needs. Escape, a press outside and the trigger close it
|
|
1475
|
+
either way.
|
|
1476
|
+
- **`DatePicker.configure({ base, presets })`** binds everything but the
|
|
1477
|
+
wiring, `trigger`, `name`, `disabled` and the two drawings.
|
|
1478
|
+
- The state's fold is `fold` because `DatePicker.update(selection, closes?)`
|
|
1479
|
+
is the adapter's, below.
|
|
1480
|
+
|
|
1481
|
+
The adapter is the rung below, for a calendar an application draws or folds
|
|
1482
|
+
itself. Fold each `SelectedDate` through `Calendar.picked`; `Calendar.empty(mode)` starts
|
|
1483
|
+
a selection and `Calendar.isComplete` says when a picker may close. Spread
|
|
1484
|
+
`Calendar.inputs(selection, mixins, { h })` into upstream `Calendar.view`'s
|
|
1485
|
+
inputs: its `toView` (`Calendar.toView(selection, mixins, { h })`) marks each
|
|
1486
|
+
chosen day `aria-selected`, a range's ends `data-selected` with
|
|
1487
|
+
`data-range-start`/`data-range-end` and every day between `data-in-range`, and its
|
|
1488
|
+
`maybeSelectedDate` (`Calendar.selectedDate(selection)`, a Single selection's day)
|
|
1489
|
+
agrees with it. The grid of a Range or Multiple selection is
|
|
1490
|
+
`aria-multiselectable`. `Calendar.localeOf('de-DE')` reads upstream's `locale`
|
|
1491
|
+
from Intl.
|
|
1492
|
+
|
|
1493
|
+
Options, the fourth argument of `toView`, `inputs` and `resolve`
|
|
1494
|
+
(`CalendarOptions`): `weekNumbers`, `caption: 'label'` or `dropdowns: { model,
|
|
1495
|
+
onShow, years?, month?, words? }` (month and year selects; answer `onShow` with
|
|
1496
|
+
`Calendar.show`), `paging`
|
|
1497
|
+
with `Calendar.alongside(model, other, offset)` for two months side by side,
|
|
1498
|
+
`preview: { date, onPreview }` for a range under the pointer, and `detail: date =>
|
|
1499
|
+
Option<string>` for a line under a day's number (a price, "2 events") that
|
|
1500
|
+
describes its button (`ResolvedDayCell.detail`). `ResolvedDays`' paging buttons
|
|
1501
|
+
are `Option`s, `pagingAtEnd` says both stand after the caption, and its heading
|
|
1502
|
+
is a `caption` of four kinds (`Grid`, `Label`, `Dropdowns`, `YearDropdown`).
|
|
1503
|
+
Presets: `Calendar.lastDays`,
|
|
1504
|
+
`nextDays`, `monthOf`, `day`, drawn by `Calendar.presetsView`.
|
|
1505
|
+
|
|
1506
|
+
A DatePicker also picks a whole `Calendar.Selection`. Fold it with
|
|
1507
|
+
`DatePicker.update(selection, closes?)`, given the selection the application keeps:
|
|
1508
|
+
upstream closes the popover on every day picked, and this keeps it open while the
|
|
1509
|
+
day leaves the selection unfinished (a range's first end, any day of a Multiple
|
|
1510
|
+
selection), reporting `SelectedDate` either way for the application to fold
|
|
1511
|
+
through `Calendar.picked`. Draw it with `DatePickerView.view` taking `selection`
|
|
1512
|
+
and `triggerContent: selection => Html` in place of upstream's
|
|
1513
|
+
`maybeSelectedDate` and `triggerContent`, and `toCalendarView:
|
|
1514
|
+
Calendar.toView(selection, mixins, { h })`. Its `toView` takes no builder of the
|
|
1515
|
+
application's: `DatePicker.toView(mixins, (resolved, h) => …)` hands `draw` the
|
|
1516
|
+
date picker's builder. Under `name`, each chosen day is a hidden input of its own,
|
|
1517
|
+
in order (a range's start, then its end), so `FormData.getAll(name)` reads
|
|
1518
|
+
`[start, end]`; nothing chosen submits the name once, empty.
|
|
1519
|
+
|
|
1520
|
+
## Menus and overlays
|
|
1521
|
+
|
|
1522
|
+
Panels that stay where they are drawn go in the browser's top layer (see [The top
|
|
1523
|
+
layer](#the-top-layer)). Dialogs, sheets, tours and floating panels return focus
|
|
1524
|
+
by [`focusReturn`](#focus-after-removal); the popups enter and leave as
|
|
1525
|
+
[Exits and reduced motion](#exits-and-reduced-motion) describes.
|
|
1526
|
+
|
|
1527
|
+
| Widget | What it is | Recipe and Slots |
|
|
1528
|
+
| --- | --- | --- |
|
|
1529
|
+
| `Menu` | One menu opened three ways: by a button, at a point (a context menu) or from a long press. A small Model: `Menu.init(id, rows, { isAnimated?, isModal? })`, folded with `Menu.update`. `Menu.view({ model, rows, buttonContent, onMessage, opensAt?, direction?, anchor?, header?, footer?, isRowDisabled?, mixins, submenuMixins? }, h)`, the style being one of the `mixins` (`[MenuStyle.mixin]`). `Bundles.Menu.with({ id, rows, isAnimated?, isModal? })` holds the state (it reads the rows' structure only) and answers `Selected`; `Menu.configure({ base, presets })` fixes the look, `anchor` and `direction` once. See [Menu](#menu). | No axis. Slots `wrapper`, `button`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator`, `rows`, `highlight`, `scrollBar`, `scrollThumb`, `label`, `sub`, `chevron`, `check`, `shortcut`, `icon`, `hint`. |
|
|
1530
|
+
| `Menubar` | A row of Menus, shadcn's and the APG's menubar. A small Model: `Menubar.init(ids, { isAnimated?, isModal? })`, folded with `Menubar.update`, whose `Selected` OutMessage names the menu and the row's `value`. `Menubar.view({ label, model, menus, onMessage, direction?, anchor?, routes?, style?, menuMixins? }, h)` (`Bundles.Menubar.with({ ids, isAnimated?, isModal? })` places the Model and reports `Selected` with the menu's index; `Menubar.configure({ base, presets })`), each menu `{ label, rows, isRowDisabled?, header?, footer? }` taking a Menu's rows (none opening a submenu). One trigger is the tab stop; ArrowLeft/ArrowRight (Home/End while all are shut) move it, and with a menu open they open the next on its first row. While one is open, pointing at another opens it, and opening any shuts the rest. | No axis. `Recipes.MenubarMenu` is the Menu recipe with a bar's flat triggers. Slots `bar`, `menu`; each menu's are `MenuSlots`. |
|
|
1531
|
+
| `Dialog` | Adapter over `@foldkit/ui`'s Dialog. See [Dialog](#dialog). | `size`: `sm`, `md` (default), `lg`, `xl`, `full`; `title`: `shown`, `hidden`; `close`: `corner`, `none`; `motion`: `standard`, `none`. Slots `dialog`, `backdrop`, `panel`, `title`, `description`, `initialFocus`, `closeButton`, `handle`, `body`, `scroll`, `scrollBar`, `scrollThumb`, `footer`. |
|
|
1532
|
+
| `Sheet` | A Dialog a finger drags, vaul's Drawer. A small Model: `Sheet.init({ id, side?, points?, opensAt?, dismissible?, isAnimated?, swipe? })`, folded with `Sheet.update`, opened with `Sheet.open` and `Sheet.close`. `Sheet.view({ model, onMessage, style?, mixins?, words?, hasDescription?, covered?, scalesPage?, draw }, h)`. See [Sheet and Drawer](#sheet-and-drawer). | `Recipes.Sheet`: `size`: `sm`, `md` (default), `lg`, `full`; `handle`: `bar` (default), `none`; `title`; `close` and `motion`, as on `Recipes.Dialog`. Slots are `DialogSlots`. |
|
|
1533
|
+
| `Drawer` | A panel docked to the bottom of the screen that peeks or opens beside the page, not over it: no focus trap, backdrop or scroll lock, so the page under it stays live (a modal one is the `Sheet`). A small Model: `Drawer.init({ id, open?, swipe? })`, folded with `Drawer.update`, opened with `Drawer.open` and `Drawer.close`. `Drawer.view({ model, onMessage, label, style?, mixins?, draw }, h)`. | `Recipes.Drawer`: `dock`: `always` (default), `below-lg`, `below-xl`, above which the panel is the column it sits in, with no handle. Slots `panel`, `handle`, `body`, `grip`. |
|
|
1534
|
+
| `Popover` | Adapter. `Popover.anchor(config?)` is the placement. The panel grows from the side it opened on and, with the Popover's `isAnimated`, fades out as it leaves; the open button keeps the hover film. | `arrow`: `shown` (default), `none`. Slots `button`, `panel`, `backdrop`, `arrow`, `layer`. |
|
|
1535
|
+
| `Tooltip` | Adapter. `Tooltip.toView(mixins, { h, id }, draw)` takes the Tooltip's id (`model.id`), whose trigger the arrow points at; `Tooltip.anchor(config?)` is the placement, above by default. | `arrow`: `shown` (default), `none`. Slots `trigger`, `panel`, `arrow`, `layer`. |
|
|
1536
|
+
| `HoverIntent` | Adapter: open and close delays with intent (200ms and 300ms by default), for a hover card or a menu. `anchored: { id, anchor? }` in the context anchors the panel to the trigger in the top layer (`HoverIntent.anchor()` unless given); the trigger takes `HoverIntent.triggerId(id)`, `aria-expanded` and, while open, `aria-describedby` naming the panel, whose id is `HoverIntent.panelId(id)`. `HoverCard` is its recipe. | `HoverCard`: no axis; a trigger read as a link, a raised panel fading in on the fast tier. Slots `trigger`, `panel`, `arrow`. |
|
|
1537
|
+
| `Anchor` | A Mount and a Behavior over `@foldkit/ui/anchor`: `Anchor.behavior(Slots)({ floating, config })` positions a floating slot against a button by id; `Anchor.topLayer(mount)` shows an in-place panel in the top layer around it. | |
|
|
1538
|
+
| `FloatingPanel` | After Zag's: a non-modal window. A small Model: `FloatingPanel.init({ id, rect, open?, min?, max?, grid?, overflow? })` holds its rect, stage, limits and a drag, folded with `FloatingPanel.update()`, or placed with `Bundles.FloatingPanel`; `FloatingPanel.open(model)` focuses it, `openBeside(model, openerId)` opens it beside an element and `close` closes it. `FloatingPanel.view({ model, onMessage, title, content, order?, draggable?, resizable?, closeOnEscape?, controls?, routes?, step?, direction?, words? }, h)`, and `FloatingPanel.configure`. See [FloatingPanel](#floatingpanel). | `header`. Slots `root`, `boundary`, `panel`, `header`, `dragTrigger`, `title`, `controls`, `minimize`, `maximize`, `restore`, `close`, `body`, `handle`. |
|
|
1539
|
+
| `Tour` | Steps anchored beside their targets in the top layer, over a dim with a cutout the target's presses reach. A small Model: `Tour.init({ id, steps })` (a step `{ title, description, target?, placement? }`), started with `Tour.start(model)` and folded with `Tour.update()`, or placed with `Bundles.Tour`. `Tour.view({ model, onMessage, content?, advanceOnClick?, padding?, interactive?, dismissOnOutside?, closeOnEscape?, routes?, words?, direction? }, h)`, and `Tour.configure`. | No axis. Slots `layer`, `blocker`, `spotlight`, `panel`, `arrow`, `progress`, `title`, `description`, `actions`, `back`, `next`, `skip`. |
|
|
1540
|
+
|
|
1541
|
+
### Menu
|
|
1542
|
+
|
|
1543
|
+
`anchor` is merged over the default `{ placement: 'bottom-start', gap: 4, padding: 8, portal: false }` (no gap at a point): `{ placement: 'top-end' }`. `header` and `footer` are Html drawn in the panel above and below the rows, in the `header` and `footer` slots, and are no row. A row's `content` Html is drawn in place of its words; `label` stays its name and typeahead key.
|
|
1544
|
+
|
|
1545
|
+
A row is an `ItemRow` (`{ value, label }`: the `value` names the row, unique among
|
|
1546
|
+
the menu's rows and their submenus' items, and is what `isRowDisabled`,
|
|
1547
|
+
`Selected` and `Menu.checkChosen` use; the `label` is what is drawn and what
|
|
1548
|
+
typeahead matches, so two rows may read alike; type the values by a union with
|
|
1549
|
+
`Row<'a' | 'b'>`), a `CheckRow` (`check: 'checkbox' | 'radio'`, `checked`:
|
|
1550
|
+
`menuitemcheckbox` or `menuitemradio` with `aria-checked`; choosing it sends
|
|
1551
|
+
`Selected` and leaves the menu open, the application keeping `checked`, a radio
|
|
1552
|
+
row's group being the rows of its `group`), or a `SubmenuRow` (`items`, each an
|
|
1553
|
+
`ItemRow`, one level deep, and `isItemDisabled?` asked of their values). Any row
|
|
1554
|
+
may name a `group` (rows next to each other with one group stand under its
|
|
1555
|
+
heading, a separator between groups), a `shortcut` (keys drawn at the row's end as
|
|
1556
|
+
Kbd with the view's `kbd`, named in `aria-keyshortcuts`; the menu binds nothing),
|
|
1557
|
+
an `icon` (an `Html` drawn before the label in the `icon` slot, hidden from
|
|
1558
|
+
assistive technology), a `hint` (a quiet note at the end of the row, before the
|
|
1559
|
+
shortcut, in the `hint` slot) and `tone: 'destructive'` (`data-tone`). A
|
|
1560
|
+
submenu's items take the same parts.
|
|
1561
|
+
|
|
1562
|
+
A submenu's row is a `menuitem` with `aria-haspopup="menu"` and `aria-expanded`;
|
|
1563
|
+
ArrowRight, Enter or Space opens it on its first row, ArrowLeft or Escape closes
|
|
1564
|
+
it back to the row (under `direction: 'rtl'` the submenu opens on the left and the
|
|
1565
|
+
arrows swap), a pointer resting 150ms opens it, and choosing a leaf closes
|
|
1566
|
+
everything. `Selected` names the row's `value` and the `value` of the submenu's row
|
|
1567
|
+
it came from. `isAnimated` gives the panels upstream's transition marks, for the
|
|
1568
|
+
recipe's fade; `isModal` makes the rest of the page inert while the menu is open.
|
|
1569
|
+
Pass `Menu.fluid` beside the style (in `submenuMixins`, not `mixins`, where rows
|
|
1570
|
+
open submenus).
|
|
1571
|
+
|
|
1572
|
+
`opensAt: 'point'`, with `Menu.target(onMessage, h)` on the area, is a context
|
|
1573
|
+
menu: a right press records its point and the `contextmenu` after it opens the
|
|
1574
|
+
menu there; a finger or a pen held there `Menu.HOLD_MS` (500ms) opens it too, as
|
|
1575
|
+
iOS fires no `contextmenu`, while one that moves 10px is a scroll. Give the area
|
|
1576
|
+
`-webkit-touch-callout: none` and `user-select: none`, or iOS shows its own callout
|
|
1577
|
+
over it. A `@foldkit/ui` Menu the application folds itself, for typed items or
|
|
1578
|
+
groups, is drawn through the panel adapter instead, and opens at a point with
|
|
1579
|
+
`Menu.drawAtPoint` and `Menu.pointTarget` (see [Why some components needed a
|
|
1580
|
+
fork](#why-some-components-needed-a-fork)).
|
|
1581
|
+
|
|
1582
|
+
### Dialog
|
|
1583
|
+
|
|
1584
|
+
Slots beyond upstream's are this package's: `handle` (the Sheet's grabber,
|
|
1585
|
+
`aria-hidden` unless the Sheet has more than one point, when it is a separator),
|
|
1586
|
+
`body`, `scroll`, `scrollBar`, `scrollThumb` and `footer`. Draw `scroll` and its bar
|
|
1587
|
+
inside `body` and the answers in `footer`, and a body taller than the screen
|
|
1588
|
+
scrolls under the title while the footer stays (`Dialog.overlayBars` beside the
|
|
1589
|
+
style draws the overlay bar).
|
|
1590
|
+
|
|
1591
|
+
- **Context.** `attributes` adds to a bundle before the mixins resolve.
|
|
1592
|
+
`covered: true` marks the panel `data-covered`, for a dialog another was opened
|
|
1593
|
+
from (draw the second inside the first's `dialog`, beside its panel), and the
|
|
1594
|
+
recipe steps it back. `isLeaving: Dialog.isLeaving(model)` draws the panel
|
|
1595
|
+
`inert` for the rest of its exit, so no press or key acts on it (upstream takes
|
|
1596
|
+
the backdrop and close button out of a leaving dialog but leaves the
|
|
1597
|
+
application's own controls live); the Sheet does this itself.
|
|
1598
|
+
- **Alert dialog.** `role: 'alertdialog'` in the context
|
|
1599
|
+
(`Dialog.toView(mixins, { h, role: 'alertdialog' }, draw)`) puts
|
|
1600
|
+
`role="alertdialog"` on the `dialog` bundle. Draw no close button, and drop the
|
|
1601
|
+
Messages `Dialog.isDismissal` names (Escape, the backdrop, the close button) in
|
|
1602
|
+
`update`, so only its own buttons, closing with `@foldkit/ui`'s `close`, answer it.
|
|
1603
|
+
- **Focus.** `Dialog.focusReturn` among the mixins gives focus a place to go when
|
|
1604
|
+
the opener is gone as the dialog closes (see [Focus after
|
|
1605
|
+
removal](#focus-after-removal)). `Dialog.update(model, message)` and
|
|
1606
|
+
`Dialog.open(model)` are `@foldkit/ui`'s `update` and `open` plus one repair: an
|
|
1607
|
+
open that meets the exit (the dialog opened again while it leaves) puts focus back
|
|
1608
|
+
inside it, on the `focusSelector`, the initial-focus mark, else the first control,
|
|
1609
|
+
which a bare upstream `open` does not.
|
|
1610
|
+
- **On-screen keyboard.** `Dialog.keyboard` among the mixins of a dialog or sheet
|
|
1611
|
+
that holds a field measures the keyboard on the panel, and the recipes keep the
|
|
1612
|
+
panel above it (a Dialog shrinks, a bottom Sheet stands on it): iOS Safari and
|
|
1613
|
+
Chrome on Android otherwise leave it under the keys.
|
|
1614
|
+
- **Recipe.** `title: 'hidden'` leaves the heading to a screen reader alone (it
|
|
1615
|
+
still names the dialog, as `display: none` would not). `close: 'none'` leaves the
|
|
1616
|
+
`closeButton` Slot unstyled for an application whose own buttons carry it (the
|
|
1617
|
+
Slot is still the Dialog's, with its `RequestedClose`). `motion: 'none'` opens,
|
|
1618
|
+
closes and steps back at once, backdrop and panel alike, whatever the `motion`
|
|
1619
|
+
knob (reduced motion is as it was). The backdrop is the `overlay.scrim` token.
|
|
1620
|
+
|
|
1621
|
+
```ts
|
|
1622
|
+
import * as UiDialog from '@foldkit/ui/dialog'
|
|
1623
|
+
import { Dialog, DialogSlots } from 'foldkit-mixins-ui'
|
|
1624
|
+
|
|
1625
|
+
const DialogStyle = Style.forSlots(DialogSlots)(Recipes.Dialog({ size: 'sm' }))
|
|
1626
|
+
|
|
1627
|
+
// The dialog's Model and Messages are @foldkit/ui's: the application folds them
|
|
1628
|
+
// with `Dialog.update`, and opens it with `Dialog.open`.
|
|
1629
|
+
const confirmDialog = (
|
|
1630
|
+
model: UiDialog.Model,
|
|
1631
|
+
toMessage: (message: UiDialog.Message) => Message,
|
|
1632
|
+
h: HtmlBuilder<Message>,
|
|
1633
|
+
) =>
|
|
1634
|
+
h.submodel({
|
|
1635
|
+
slotId: model.id,
|
|
1636
|
+
model,
|
|
1637
|
+
view: UiDialog.view,
|
|
1638
|
+
viewInputs: {
|
|
1639
|
+
toView: Dialog.toView(
|
|
1640
|
+
[DialogStyle.mixin, ...Dialog.focusReturn],
|
|
1641
|
+
{ h, isLeaving: Dialog.isLeaving(model) },
|
|
1642
|
+
dialog =>
|
|
1643
|
+
h.dialog(
|
|
1644
|
+
dialog.dialog,
|
|
1645
|
+
dialog.isVisible
|
|
1646
|
+
? [
|
|
1647
|
+
h.div(dialog.backdrop),
|
|
1648
|
+
h.div(dialog.panel, [
|
|
1649
|
+
h.h2(dialog.title, ['Discard changes?']),
|
|
1650
|
+
h.div(dialog.footer, [h.button(dialog.closeButton, ['Cancel'])]),
|
|
1651
|
+
]),
|
|
1652
|
+
]
|
|
1653
|
+
: [],
|
|
1654
|
+
),
|
|
1655
|
+
),
|
|
1656
|
+
},
|
|
1657
|
+
toParentMessage: toMessage,
|
|
1658
|
+
})
|
|
865
1659
|
```
|
|
866
1660
|
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
1661
|
+
### Sheet and Drawer
|
|
1662
|
+
|
|
1663
|
+
**Sheet.** `draw` lays out `DialogSlots`' bundles with `h.div(sheet.handle)` in
|
|
1664
|
+
the panel. The panel stands on `side`'s edge (`data-side`); a drag follows the
|
|
1665
|
+
pointer and settles at the nearest of `points` (the share of the panel shown,
|
|
1666
|
+
ascending; a top or bottom sheet with a point below 1 takes its `size`'s full
|
|
1667
|
+
height, and below its highest point its content holds still, so a swipe up raises
|
|
1668
|
+
it), or, flicked or dragged far enough past the first, closes it, unless
|
|
1669
|
+
`dismissible: false`. The Dialog keeps focus, Escape and scroll lock. With more
|
|
1670
|
+
than one point the handle is a focusable `separator` named by `words.handle`
|
|
1671
|
+
(default `Resize sheet`), its `aria-valuenow` the percent shown: the arrow keys
|
|
1672
|
+
along the edge (the one toward the page raises it: ArrowUp on a bottom sheet,
|
|
1673
|
+
ArrowDown on a top one, ArrowLeft on a right one, ArrowRight on a left one), Home
|
|
1674
|
+
and End step between the points through `Message.SnappedTo { at }` (an index into
|
|
1675
|
+
`points`) and stop at the ends, and Escape still closes; an opened sheet with
|
|
1676
|
+
points takes focus on the handle unless the panel has an initial-focus element.
|
|
1677
|
+
With one point the handle stays decoration, `aria-hidden`; with `handle: 'none'`
|
|
1678
|
+
an application moves the sheet with `SnappedTo` from a control of its own. A
|
|
1679
|
+
leaving Sheet's panel is `inert` until it is gone, and `Sheet.open` is
|
|
1680
|
+
`Dialog.open`'s, so a Sheet opened again while it leaves takes focus back; one
|
|
1681
|
+
whose opener is gone as it closes returns focus through `Dialog.focusReturn`
|
|
1682
|
+
among its mixins. `scalesPage` with `Recipes.sheetPage` on the page beside the
|
|
1683
|
+
sheet, never around it, steps the page back while it is open. The slide and its
|
|
1684
|
+
exit run on `Theme.tokens.motion.sheet` and `sheet-exit`, which default to the
|
|
1685
|
+
`slow` tier and its exit and are multiplied by `travel`: an application that
|
|
1686
|
+
keeps another timing sets them in its tokens (`Theme.define({ motion: { sheet:
|
|
1687
|
+
'500ms', 'sheet-exit': '500ms' } })`), and `sheetPage` follows `sheet`. The panel's
|
|
1688
|
+
padding keeps clear of the safe areas (`Theme.tokens.safe`) on the sides it touches.
|
|
1689
|
+
|
|
1690
|
+
**Swiping (Sheet and Drawer).** `swipe: { from?, flickSpeed?, closeShare? }` says
|
|
1691
|
+
how it is swiped: a finger drags it from anywhere on the panel (`from: 'panel'`, the
|
|
1692
|
+
default), yielding to content that can still scroll its way, so a long one scrolls
|
|
1693
|
+
back to its top and then goes, and a field or `data-no-swipe` starts no drag; a
|
|
1694
|
+
mouse drags it by the handle, and `from: 'handle'` keeps every pointer there. A
|
|
1695
|
+
release faster than `flickSpeed` (0.4px/ms) is a flick, and a slow one goes once
|
|
1696
|
+
dragged `closeShare` (a quarter) of the panel.
|
|
1697
|
+
|
|
1698
|
+
**Drawer.** `draw` lays out `panel`, `handle`, `body` (the body may sit below what
|
|
1699
|
+
else peeks with the handle) and, optionally, `grip`, more to drag it by (a row of
|
|
1700
|
+
tabs: vertical swipes drag it, sideways ones still scroll). A drag follows the
|
|
1701
|
+
finger and lets go open or down by its speed, then by how far it came. A click or
|
|
1702
|
+
Enter on the handle toggles it, and the click a browser sends after a drag does
|
|
1703
|
+
not. `label` names the handle once, and its `aria-expanded` says whether the panel
|
|
1704
|
+
is open, so the name does not change with the state. The body is hidden
|
|
1705
|
+
(`visibility: hidden`) when the slide ends, not as it starts. `Drawer.keepFocus`
|
|
1706
|
+
beside the style moves focus to the handle when the drawer closes with focus in its
|
|
1707
|
+
body, which the hidden body would otherwise drop to the page. The panel's inline
|
|
1708
|
+
style is the drag's: set `--fk-drawer-peek` (default 5rem) and
|
|
1709
|
+
`--fk-drawer-height` (default 70dvh) on an ancestor or in a style. The handle is a
|
|
1710
|
+
44px target drawn tight to its bar, and the peek stays above the home indicator.
|
|
1711
|
+
|
|
1712
|
+
### FloatingPanel
|
|
1713
|
+
|
|
1714
|
+
The drag trigger (`role="button"`, named `Move <title>`) moves the panel and eight
|
|
1715
|
+
edges resize it, kept within the viewport; the arrows move it from the drag
|
|
1716
|
+
trigger and resize it from the bottom-end corner; minimize, maximize, restore and
|
|
1717
|
+
close. A press or focus inside returns the `Raised` OutMessage, which the
|
|
1718
|
+
application folds into the `order` its panels stack by with
|
|
1719
|
+
`FloatingPanel.raise(order, id)`. `routes` are [application key
|
|
1720
|
+
routes](#application-key-routes) beside Escape (unless `closeOnEscape` is false);
|
|
1721
|
+
the arrows on the drag trigger and the corner are the panel's own, and a press they
|
|
1722
|
+
handled still reaches the panel. `FloatingPanel.focusReturn` is opt-in and is the
|
|
1723
|
+
one way focus returns.
|
|
1724
|
+
|
|
1725
|
+
The limits (`min`, `max`, `grid`, `overflow`) are `init`'s options and live in the
|
|
1726
|
+
Model, so `FloatingPanel.update()` reads the one copy; `update(limits)` still
|
|
1727
|
+
overrides them for a call. `Bundles.FloatingPanel` places the window with `init`'s
|
|
1728
|
+
options as its args and reports `Raised` in `onOut`; its helpers are `open`,
|
|
1729
|
+
`close`, `openBeside(openerId, { side?, gap? })` and `dock(edge, thickness)`.
|
|
1730
|
+
`openBeside` (also a function of the module) reads the opener's box in a Command
|
|
1731
|
+
and answers `Placed`, which puts the panel there within the limits and the
|
|
1732
|
+
viewport; `rectBeside(anchor, size, options)` is the pure rule, for a place of your
|
|
1733
|
+
own. `Docked { edge, thickness }` lays the panel along an edge of the viewport as
|
|
1734
|
+
measured when it lands; it stays a window and drags away. `controls` names the
|
|
1735
|
+
header's buttons (default all three; restore appears with whichever stage was
|
|
1736
|
+
reached), `words` their names and the drag trigger's and corner's (`Move {title}`,
|
|
1737
|
+
`Resize {title}`), and `FloatingPanel.configure({ base, presets })` fixes the look,
|
|
1738
|
+
words, controls and mixins once.
|
|
871
1739
|
|
|
872
1740
|
```ts
|
|
873
|
-
|
|
1741
|
+
import { Schema } from 'effect'
|
|
1742
|
+
import { Bundle } from 'foldkit-bundle'
|
|
1743
|
+
import { Bundles, FloatingPanel } from 'foldkit-mixins-ui'
|
|
1744
|
+
|
|
1745
|
+
const Windows = Bundle.compose({ order: Schema.Array(Schema.String) }).pipe(
|
|
1746
|
+
Bundle.withChild('notes', Bundles.FloatingPanel, {
|
|
1747
|
+
args: { id: 'notes', rect: { x: 80, y: 120, width: 320, height: 220 }, grid: 20 },
|
|
1748
|
+
onOut: out => model => ({
|
|
1749
|
+
model: { ...model, order: FloatingPanel.raise(model.order, out.id) },
|
|
1750
|
+
}),
|
|
1751
|
+
}),
|
|
1752
|
+
)
|
|
1753
|
+
```
|
|
1754
|
+
|
|
1755
|
+
### Tour
|
|
1756
|
+
|
|
1757
|
+
The target scrolls into view; Next, Back and the arrows move on, Escape and Skip
|
|
1758
|
+
end it, and `update` returns `Ended { completed }`. A step without a target, or
|
|
1759
|
+
whose target is missing, stands in the middle. `routes` are [application key
|
|
1760
|
+
routes](#application-key-routes) on a step, such as a digit jumping to that step,
|
|
1761
|
+
beside the arrows and, unless `closeOnEscape` is false, Escape. `Tour.focusReturn`
|
|
1762
|
+
is opt-in and is the one way focus returns: ending the tour gives focus back to what
|
|
1763
|
+
had it before it started.
|
|
1764
|
+
|
|
1765
|
+
The steps are data in the Model (`init`'s `steps`), so `update()`, `start(model)`
|
|
1766
|
+
and the view read one copy; `update(config)`, `start(model, config)` and the view's
|
|
1767
|
+
`config` override it for a call. `Bundles.Tour` places it with `{ id, steps? }` as
|
|
1768
|
+
its args, reports `Ended` in `onOut`, and `helpers.start` starts it. `content(step,
|
|
1769
|
+
index)` draws a step's words as Html in their place (a key to press, a list), still
|
|
1770
|
+
describing the step's dialog. `advanceOnClick: Tour.advanceOnClick` moves the tour on
|
|
1771
|
+
when the reader presses the step's target through the cutout (not with `interactive:
|
|
1772
|
+
false`); it is a value in a file of its own, so a tour without it loads no listener.
|
|
1773
|
+
`words` (`Tour.words`) are the buttons' names and the step's place, `{step} of
|
|
1774
|
+
{count}`; `Tour.configure({ base, presets })` fixes the look, words and mixins once.
|
|
1775
|
+
|
|
1776
|
+
### Popover, Tooltip and Hover Card
|
|
1777
|
+
|
|
1778
|
+
Popover, Tooltip and Hover Card are drawn by upstream views whose Mounts this
|
|
1779
|
+
package cannot wrap, so their panels go in the top layer by an element of their
|
|
1780
|
+
own (see [The top layer](#the-top-layer)). A Popover's `layer` Slot, `Popover.anchor()`
|
|
1781
|
+
and `Tooltip.anchor()` give `portal: false` and the placement: 12px and 8px off the
|
|
1782
|
+
trigger, 8px inside the viewport, flipping and shifting. Each draws an `arrow` slot
|
|
1783
|
+
in its panel that points at the trigger.
|
|
1784
|
+
|
|
1785
|
+
**State as Bundles.** Every overlay's state is a Bundle, one file apiece:
|
|
1786
|
+
`Bundles.Dialog.with({ id, isAnimated?, focusSelector?, dismissible? })`,
|
|
1787
|
+
`Bundles.Sheet`, `Bundles.Drawer`, `Bundles.Popover`, `Bundles.Tooltip` (`showDelay`
|
|
1788
|
+
in milliseconds) and `Bundles.HoverIntent` (`openDelay`, `closeDelay`). The upstream
|
|
1789
|
+
ones report `Opened` and `Closed` (a Tooltip `Shown` and `Hidden`) for `onOut`, and
|
|
1790
|
+
`helpers.open` and `helpers.close` are for a control of the application's. A Dialog
|
|
1791
|
+
that is not `dismissible` drops the `RequestedClose` that Escape, the backdrop and
|
|
1792
|
+
its close button send, so only an answer closes it, through `helpers.close`: an
|
|
1793
|
+
alert dialog is that, with `role: 'alertdialog'` in `Dialog.toView`'s context. A
|
|
1794
|
+
Sheet opened by the Dialog's own `RequestedOpen` rests at its `opensAt` point, as
|
|
1795
|
+
`helpers.open` does. Pass `isAnimated: true` and the panel stays drawn while it
|
|
1796
|
+
leaves, so the recipe's fade runs on the way out as on the way in. The drawing
|
|
1797
|
+
stays the adapter's: what a dialog or a popover holds is the application's
|
|
1798
|
+
content, so the examples compose it rather than pass it as options. `Dialog`'s
|
|
1799
|
+
`overlayBars`, `keyboard` and `focusReturn`, `Drawer.keepFocus` and `Toast.keepFocus`
|
|
1800
|
+
are files of their own, so a page that never names one keeps neither its Mount nor
|
|
1801
|
+
the primitive it runs. A Drawer imports no Sheet and no Dialog (`swipe.ts` holds
|
|
1802
|
+
what the two share).
|
|
1803
|
+
|
|
1804
|
+
## Navigation and structure
|
|
1805
|
+
|
|
1806
|
+
| Widget | What it is | Recipe and Slots |
|
|
1807
|
+
| --- | --- | --- |
|
|
1808
|
+
| `Tabs` | `Tabs.view({ model, onMessage, label, tabs: { value, label, icon?, trailing?, disabled?, panel? }[], value, orientation?, close?, routes? }, h)` draws the tablist and the chosen row's panel; `Bundles.Tabs.with({ id, activationMode? })` holds the focus cursor and reports `Selected`, the chosen `value` being the application's. `Tabs.configure({ base, presets })`. Below it, the adapter: a tab is a flex row, so draw its words in `label` (`h.span(label, [words])`), an icon in `icon`, a Badge after them for a count. `TabsContext.close: { onClose }` makes tabs closable; `TabsContext.routes` takes [application key routes](#application-key-routes). `Tabs.readingKeys` beside the style reads the arrow keys by the tablist's direction. See [Tabs](#tabs). | `variant`: `line` (default), `pill`; `size`; `overflow`: `scroll`, `wrap`; pill-only `selection`: `raised` (default), `tint`; upstream's `orientation: 'Vertical'`. Slots `root`, `tablist`, `tab`, `panel`, `indicator`, `highlight`, `item`, `label`, `icon`, `close`. |
|
|
1809
|
+
| `Nav` | Two layers. `Nav.toView(mixins, { h }, label, draw?)` styles `@foldkit/ui`'s stateless Nav (`nav > ul > li > a`, the current link `aria-current="page"`). `Nav.view({ model, entries, label, onMessage, orientation?, direction?, routes?, panelRoutes?, mixins? }, h)` is a navigation menu with panels of link columns; a link and a panel link take `icon` (Html before the words, in the `icon` slot, hidden from assistive technology) and a panel takes `footer` (Html after its groups, in the `panelFooter` slot). A small Model: `Nav.init(id)`, folded with `Nav.update`, or placed as `Bundles.Nav.with({ id })`; `Nav.configure({ base, presets })`. See [Nav](#nav). | `indicator`: `underline` (default), `pill`; `panel`: `list` (default), `grid` (the groups in equal columns); `orientation: 'vertical'`. Slots `nav`, `list`, `item`, `link`, `trigger`, `chevron`, `panel`, `groups`, `group`, `heading`, `links`, `panelItem`, `panelLink`, `icon`, `panelFooter`, `title`, `description`, `indicator`, `highlight`. |
|
|
1810
|
+
| `Breadcrumb` | `{ words?, steps: { label, href?, current?, icon?, trailing?, labelHidden? }[], separator?, collapse? }`. `words` is `{ label, more, ellipsis }` (defaults `Breadcrumb.words`, merged word by word): the landmark's name (`Breadcrumb`), the ellipsis's name (`Show {count} more`, `{count}` the hidden steps) and its mark (`…`). `current` is text with `aria-current="page"`; the others are links. `trailing` draws after the label (a count), in the `trailing` slot; `labelHidden` draws no words, and the label is the step's accessible name, for an `icon` that says it. `collapse: { max, onExpand }` folds the middle of a long trail into an ellipsis (`Breadcrumb.collapsedOf(steps, max)` is the split); `collapse: BreadcrumbMenu.make({ max, menu: { model, onMessage, mixins } })` makes the ellipsis open a Menu of the hidden steps (a value from its own module, so a trail that opens none loads no Menu; any `CollapseFeature`, `{ max, draw }`, is the same seam for a fold of your own), built from `Breadcrumb.menuRows(steps, max)`, with `Breadcrumb.chosen(steps, max, value)` the step a row leads to (a row's value is its step's place among the hidden steps, so two steps of one label are two rows). | `item`: `plain` (default), `pill`, `button`. `separator`: `slash` (default), `chevron`, `dot`. The separator is drawn after each step but the last, so a wrapped trail never begins a line with one. Slots `root`, `list`, `item`, `link`, `current`, `icon`, `trailing`, `separator`, `ellipsis`, `dots`. |
|
|
1811
|
+
| `Pagination` | `{ page, pageCount, onPage, siblings?, boundaries?, numbered?, ends?, icons?, range?, words? }`. `Pagination.itemsOf(page, pageCount, window?)` is the stops; `Pagination.summaryOf(page, { total, perPage }, summary?)` is `"1–10 of 97"`, drawn before the stops when `range` is given. See [Pagination](#pagination). | `compact`: `narrow` (default, below a 30rem window), `always`, `never`; `shape`: `square` (default), `round`; `treatment`: `ghost` (default), `outline`. Slots `root`, `summary`, `perPage`, `perPageSelect`, `first`, `prev`, `next`, `last`, `page`, `pageCount`, `ellipsis`. |
|
|
1812
|
+
| `Steps` | A stepper, an ordered list named by `label`. `Steps.view({ label, steps: { title, description?, icon?, content?, state?, trailing? }[], current, onSelect?, words?, progress? }, h)`. The step at `current` is `aria-current="step"`, those before it `data-state="complete"` (a check replaces the number), those after `upcoming`. With `onSelect(index)`, completed steps are buttons for going back; steps ahead never are. The application owns `current`. | `orientation`: `horizontal` (default), `vertical`; `size`: `xs`, `sm`, `md`, `lg`; `marker`: `number`, `dot`; `connector`: `line`, `progress`, `segments`; `labels`: `current`, `hidden`. Slots `root`, `item`, `step`, `trigger`, `marker`, `number`, `text`, `title`, `state`, `description`, `content`, `trailing`, `connector`. |
|
|
1813
|
+
| `Sidebar` | shadcn's sidebar with Fluid's collapse. A small Model: `Sidebar.init({ id, rows, open?, collapsed?, side?, width? })`, folded with `Sidebar.update`. `Sidebar.view({ model, onMessage, label, groups, header?, footer?, direction?, collapse?, words?, style?, mixins?, tooltip?, sheet? }, h)`. See [Sidebar](#sidebar). | `variant`: `sidebar` (flush with the page's edge, the default), `floating`, `inset`. Slots `root`, `header`, `footer`, `opener`, `title`, `toggle`, `nav`, `section`, `heading`, `trigger`, `chevron`, `links`, `item`, `branch`, `link`, `icon`, `mark`, `detail`, `label`, `badge`, `action`, `tip`, `indicator`, `highlight`, `resize`, `trailing`. |
|
|
1814
|
+
| `AppShell` | An application's page frame: `AppShell.view({ title, main, brand?, status?, actions?, side?, aside?, asideLabel?, footer?, mainId?, words? }, h)`, and `AppShell.configure({ base, presets })` for the look, `mainId` and words said once. A skip link to the main region, a header bar (the banner) with the title and, at its end, `status` and `actions`, an optional side column for a `Sidebar`'s view, the main region (`id` `main` by default, focusable by script so the skip link moves focus there), an `aside` column at its end (a contents list or details, an `aside` landmark named by `asideLabel`, pinned under the header and below the main region on a phone), and a footer. It holds no state and sends no Message. The header and the side column stay in view while the page scrolls; below `md` the side column sits at the start of the header's row. `Patterns.AppShell` is its contract. | `width`: `full` (default), `contained` (the main region's content kept to the theme's `width.page`). Slots `root`, `skip`, `header`, `brand`, `mark`, `title`, `status`, `actions`, `side`, `main`, `aside`, `footer`. |
|
|
1815
|
+
| `Accordion` | `{ id, items: { id, title, content, disabled? }[], open, onToggle, headingLevel? }`; `Accordion.toggled(open, id, { multiple?, collapsible? })` is the transition `update` applies, the open ids being the application's. Each trigger is a button in a heading naming its panel; a shut panel stays drawn and `inert`. A panel shuts over the time it opens in (default the theme's `moderate`), so switching sections moves both together; `--fk-collapse-duration` sets both and `--fk-collapse-close-duration` the shutting alone, each a time of the theme (`var(--fk-motion-slow)`) so the `motion` and `travel` knobs still apply. TreeView, Sidebar and ThinkingSteps groups share the two properties. The view takes an `icon` in place of the recipe's. An item may also carry `icon` (Html before its title) and `trailing` (after it: a badge, a role); its `title` stays text. `Bundles.Accordion.with({ open?, multiple?, collapsible? })` keeps the open ids and the two rules once, `Accordion.controls(model, onMessage)` is spread into the view, and `Accordion.configure({ base, presets })` fixes the look and heading level. | `variant`: `plain` (default), `bordered`, `separated`, `filled`, `ghost`; `separators`: `on`, `off`; `indicator`: `chevron`, `plus`; `indicatorPosition`: `end`, `start`; `active`: `none`, `trigger`, `item`. Slots `root`, `item`, `heading`, `trigger`, `leading`, `label`, `trailing`, `chevron`, `icon`, `panel`, `body`, `content`. |
|
|
1816
|
+
| `Disclosure` | `Disclosure.view({ id, isOpen, onToggle, label, content, icon?, peek?, disabled? }, h)` draws the button, its icon and label, and the panel; `@foldkit/ui`'s disclosure keeps no state, so `Bundles.Disclosure.with({ isOpen? })` holds the flag and `Disclosure.controls(model, onMessage)` is spread into the view. `peek` keeps a height of the shut panel as an inert preview. `Disclosure.configure({ base, presets })` binds the look. `toView` is the adapter for a layout of your own. Draw the panel only while open, or through upstream's `animatePanel`, which keeps a shut panel inert and moves its height itself by an inline transition that the recipe overrides with an important rule, so the `motion` knob scales it and reduced motion snaps it. | `variant`: `plain` (default), `bordered`, `ghost`; `indicator`: `chevron` (default), `none`. Slots `root`, `button`, `icon`, `label`, `panel`. |
|
|
1817
|
+
| `TreeView` | The APG's and Zag's tree view. A small Model: `TreeView.init({ id, open?, checked?, checkable? })`, folded with `TreeView.update(nodes)` (curried over the tree, flattened once); `checkable` lives in the Model, so `update` and the view read it from one place (each still accepts it as an override). `Bundles.TreeView.with({ id, nodes, open?, checked?, checkable? })` holds the tree's structure and builds `update` once. `TreeView.view({ label, model, nodes, onMessage, direction?, style?, mixins? }, h)` over nodes `{ id, label, children?, disabled?, icon?, openIcon?, content?, trailing?, action? }`: `content` is drawn in place of the label's text (the label still names the row and is what typing matches), `trailing` after it and `action` at the row's end. `TreeView.configure({ base, presets })` binds the look and glide. See [TreeView](#treeview). | `guides`: `none` (default), `lines`; `data-state` on a branch `item` and its `group`. Each item carries `--fk-tree-level`. Slots `root`, `item`, `row`, `chevron`, `checkbox`, `icon`, `label`, `trailing`, `action`, `group`. |
|
|
1818
|
+
|
|
1819
|
+
### Tabs
|
|
1820
|
+
|
|
1821
|
+
`Tabs.view` is the usual drawing (rows with a mark, words, a trailing Html and a panel; `orientation: 'vertical'` lays the panel beside the tabs; `close` and `routes` as below); it takes `mixins: [...Tabs.fluid]` as a value, so a page that never passes it never loads what glides the indicator. Its `root` slot holds the tablist and the panel. `Tabs.toView` stays the lower rung for a drawing of your own.
|
|
1822
|
+
|
|
1823
|
+
`TabsContext.close: { onClose }` gives each tab a close button (no tab stop, hidden
|
|
1824
|
+
from assistive technology) and Delete, named in `aria-keyshortcuts`; answer with
|
|
1825
|
+
`Tabs.closing(tabs, chosen, closed)`, which gives the tabs left, the tab chosen
|
|
1826
|
+
and the index to focus with `FocusTab`. `TabsContext.routes` takes keys the
|
|
1827
|
+
application answers on a tab, such as F2 renaming it, beside Delete: the input is
|
|
1828
|
+
the tab's `TabInfo`, and a tab with no key to answer draws no keydown at all.
|
|
1829
|
+
`overflow: 'scroll'` is one line with its edges fading; `'wrap'` is a grid of equal
|
|
1830
|
+
columns that fills the row and falls to fewer columns, no tab cut off (a column is
|
|
1831
|
+
no narrower than three control heights; `.extend` the tablist's `--_fk-tab-min` to
|
|
1832
|
+
change it). `selection: 'tint'` is the accent's tint and ink instead of the raised
|
|
1833
|
+
pill, as a pressed Segmented option is; upstream's `orientation: 'Vertical'` stands
|
|
1834
|
+
the rule at the tabs' inline end. `Tabs.fluid` glides the indicator (see [Fluid
|
|
1835
|
+
highlights](#fluid-highlights)).
|
|
1836
|
+
|
|
1837
|
+
### Nav
|
|
1838
|
+
|
|
1839
|
+
The navigation menu shows its panels in the top layer, with the APG's
|
|
1840
|
+
disclosure-navigation keys (Escape, ArrowDown into a panel, the arrows, Home and End
|
|
1841
|
+
along the row; a press outside and focus leaving close it). A trigger names its
|
|
1842
|
+
panel in `aria-controls` only while the panel is drawn, and links are keyed by place
|
|
1843
|
+
as well as address, so two links to one address do not collide. A panel's `groups`
|
|
1844
|
+
are `{ label, href, description?, current? }` columns. `routes` takes
|
|
1845
|
+
[application key routes](#application-key-routes) on the top-level links and
|
|
1846
|
+
triggers, beside the row's own: the input is the entry and `item.index` its place;
|
|
1847
|
+
`panelRoutes` takes keys on a panel's links, where the input is the link and
|
|
1848
|
+
`item.index` its place among the panel's links. `Nav.fluid` glides a line to the
|
|
1849
|
+
current link and a faint pill to the one the pointer nears.
|
|
1850
|
+
|
|
1851
|
+
### Pagination
|
|
1852
|
+
|
|
1853
|
+
Fewer than two pages draws no stops; with a `range` it still draws the summary and
|
|
1854
|
+
the page-size select. `range.choose: { sizes, onPerPage }` adds a select of
|
|
1855
|
+
rows per page (labelled `words.perPage`, `Rows per page`) that sends `onPerPage` with the
|
|
1856
|
+
size; the application sets `perPage` and a page that keeps its rows in view.
|
|
1857
|
+
`numbered: false` leaves previous and next alone; `ends` draws first and last.
|
|
1858
|
+
`icons: { first?, previous?, next?, last? }` draws an Html in place of a stop's word, which stays the button's accessible name.
|
|
1859
|
+
`Pagination.configure({ base, presets })` fixes the style, words, windows, `ends`, `numbered` and `icons` once.
|
|
1860
|
+
`words: { label, first, previous, next, last, stop, ellipsis, ofCount, perPage, summary }` (`Pagination.words`, merged word by word) is every word it says, as text with blanks: `stop` is `"{word} page"` (each stop's name), `ofCount` ` / {count}`, `summary` `"{from}–{to} of {total}"`, for another
|
|
1861
|
+
language. A stop at an end is `aria-disabled`, not `disabled`, so it keeps focus and
|
|
1862
|
+
sends nothing. The current stop reads `aria-current` and holds ` / 12` in a
|
|
1863
|
+
`pageCount` span hidden from assistive technology; compact shows only that stop and
|
|
1864
|
+
no ellipses.
|
|
1865
|
+
|
|
1866
|
+
### Steps
|
|
1867
|
+
|
|
1868
|
+
The marker is hidden from assistive technology, so `words: { complete?, current?,
|
|
1869
|
+
upcoming? }` (defaults `Steps.words`: `Completed`, an empty word that says nothing,
|
|
1870
|
+
`Upcoming`; the current step's `aria-current="step"` already says it) say each step's state in text after its
|
|
1871
|
+
title, in the `state` slot. `progress` (0 to 1) fills the connector after the
|
|
1872
|
+
current step when the recipe's connector is a progress bar. A horizontal row
|
|
1873
|
+
narrower than 32rem shows only the current step's words, wrapping inside an even
|
|
1874
|
+
share so the markers stay evenly spaced (a word longer than 40% of the row is cut),
|
|
1875
|
+
and narrower than 17rem draws them on a line of their own under the markers.
|
|
1876
|
+
|
|
1877
|
+
A step may state its own `state` (`complete`, `current`, `upcoming`, `loading` or `error`) over the one
|
|
1878
|
+
`current` gives it: a later step already complete, the one being taken `loading`, a step that
|
|
1879
|
+
`error`ed. `aria-current` still follows `current`, and each state has a word (`loading`: `In progress`,
|
|
1880
|
+
`error`: `Failed`). A step's `trailing` Html (a time, a badge) ends its row in the `trailing` slot, and
|
|
1881
|
+
the recipe's `labels: 'current'` keeps only the current step's words beside its marker, `'hidden'` none,
|
|
1882
|
+
the rest left to a screen reader. `Steps.configure({ base, presets })` fixes the style and words once.
|
|
1883
|
+
|
|
1884
|
+
### Sidebar
|
|
1885
|
+
|
|
1886
|
+
`groups` are `{ id, title?, collapsible?, action?, rows }`, a row a `SidebarLink` (`{
|
|
1887
|
+
id, label, href, current?, icon?, badge?, action? }`) or a `SidebarBranch` of nested
|
|
1888
|
+
links (`items`). An `action` (`SidebarAction`: `{ label, icon, message }`) is a button
|
|
1889
|
+
at a titled group's heading or beside a link, where it takes the badge's place under
|
|
1890
|
+
the pointer (both show on a touch screen). Groups and branches open like an
|
|
1891
|
+
accordion's, several at once; the current page is `aria-current` and `Sidebar.fluid`
|
|
1892
|
+
glides a marker to it. `collapse: 'offcanvas'` (default) takes the whole column off
|
|
1893
|
+
the page; `'icons'` leaves a rail of icons named in Tooltips (`tooltip`, a Tooltip
|
|
1894
|
+
style; a rail that draws a row `init`'s `rows` did not list throws, since a Tooltip
|
|
1895
|
+
is state only `init` can make). With `sheet` (a Sheet style), an opener shows it in a
|
|
1896
|
+
Sheet on a phone. Shut groups and a collapsed column stay drawn and `inert`.
|
|
1897
|
+
`Sidebar.init({ width: { size?, min?, max? } })` makes the column resizable, its
|
|
1898
|
+
width in the Model: a `resize` handle on its edge drags it, the arrows step it, Home
|
|
1899
|
+
collapses it (a collapsed one leaves the key alone) and End goes to the widest, Enter
|
|
1900
|
+
or a double-click collapses it, and dragged below half `min` it collapses, coming
|
|
1901
|
+
back at the width the drag began at.
|
|
1902
|
+
|
|
1903
|
+
A row and a nested link take `RowContent`'s parts: `content` drawn in place of the
|
|
1904
|
+
label's text (the label still names it), and `trailing` Html at its end in a
|
|
1905
|
+
`trailing` Slot (a key, a status dot), which gives way to the row's action under the
|
|
1906
|
+
pointer as the badge does. `words` (`Sidebar.words`: `show`, `hide`, `open`,
|
|
1907
|
+
`resize`, each with `{label}`) name the toggle, the phone's opener and the resize
|
|
1908
|
+
handle. A group shuts over the time it opens in. `Sidebar.fluid` and the Slots are
|
|
1909
|
+
files of their own, so a sidebar without the glide keeps no `FluidHover`.
|
|
1910
|
+
|
|
1911
|
+
### TreeView
|
|
1912
|
+
|
|
1913
|
+
One tab stop; Up/Down move through the rows showing, stepping over shut and disabled
|
|
1914
|
+
ones; Right opens or steps in, Left shuts or steps out (swapped under `direction:
|
|
1915
|
+
'rtl'`); Home/End; letters typed within 500ms of each other find the next showing row
|
|
1916
|
+
whose label starts with all of them (`TreeView.Model.typeahead`, cleared by the
|
|
1917
|
+
`QueryExpired` Message, which an application that wraps the Messages passes through to
|
|
1918
|
+
`update`); `*` opens every row beside the current one that holds rows; Enter, Space or
|
|
1919
|
+
a click chooses a row and opens or shuts a branch. Keys reach `update`, which decides
|
|
1920
|
+
from its own Model and sends a focus Command. A shut group stays drawn and `inert`.
|
|
1921
|
+
|
|
1922
|
+
`checkable` (on the view and `update`) gives each row a box: the Model's `checked`
|
|
1923
|
+
holds the leaves, a branch reads checked, mixed or not from them
|
|
1924
|
+
(`TreeView.checksOf`), and Space checks the current row in `update`. The Model's
|
|
1925
|
+
`checked` is the one owner: the checked rows that hold no rows. An application that
|
|
1926
|
+
stores or sends another shape converts at the edge, with two pure functions over the
|
|
1927
|
+
same `nodes`, `TreeView.checkedAs(nodes, checked, 'leaf' | 'branch' | 'trunk')` and
|
|
1928
|
+
`TreeView.leavesOf(nodes, value)`:
|
|
1929
|
+
|
|
1930
|
+
```ts
|
|
1931
|
+
import { TreeView, type TreeNode } from 'foldkit-mixins-ui'
|
|
1932
|
+
|
|
1933
|
+
const nodes: ReadonlyArray<TreeNode> = [
|
|
874
1934
|
{
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
1935
|
+
id: 'src',
|
|
1936
|
+
label: 'src',
|
|
1937
|
+
children: [
|
|
1938
|
+
{ id: 'button', label: 'button.ts' },
|
|
1939
|
+
{ id: 'tree', label: 'tree.ts' },
|
|
1940
|
+
],
|
|
879
1941
|
},
|
|
880
|
-
|
|
1942
|
+
{ id: 'readme', label: 'README.md' },
|
|
1943
|
+
]
|
|
1944
|
+
|
|
1945
|
+
TreeView.checkedAs(nodes, ['button', 'tree', 'readme'], 'branch') // ['src', 'button', 'tree', 'readme']
|
|
1946
|
+
TreeView.checkedAs(nodes, ['button', 'tree', 'readme'], 'trunk') // ['src', 'readme']
|
|
1947
|
+
|
|
1948
|
+
const seeded = TreeView.init({ id: 'files', checked: TreeView.leavesOf(nodes, ['src']) })
|
|
1949
|
+
// seeded.checked is ['button', 'tree']
|
|
881
1950
|
```
|
|
882
1951
|
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
1952
|
+
A row holding rows is listed once every row it holds that holds none is checked, a
|
|
1953
|
+
disabled one included. Ids the tree does not hold are left out of both. Independent
|
|
1954
|
+
checks that do not cascade, and branches whose rows are not loaded yet, are not
|
|
1955
|
+
modelled.
|
|
1956
|
+
|
|
1957
|
+
### Disclosure
|
|
1958
|
+
|
|
1959
|
+
`Disclosure.view` draws the button and the panel from options (see its row above);
|
|
1960
|
+
the adapter below is the rung for a layout of your own. The recipe draws the button
|
|
1961
|
+
and the panel's box, and `animatePanel` keeps the shut panel inert and moves its
|
|
1962
|
+
height.
|
|
886
1963
|
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
muted, and `control` makes the input inside borderless. They are pieces for
|
|
891
|
-
your own group, affix and control slots, as `foldkit-mixins-form`'s field
|
|
892
|
-
publishes them:
|
|
1964
|
+
<!-- docs-check
|
|
1965
|
+
declare const ToggledDetails: (payload: { readonly isOpen: boolean }) => Message
|
|
1966
|
+
-->
|
|
893
1967
|
|
|
894
1968
|
```ts
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
1969
|
+
import { Disclosure as UiDisclosure } from '@foldkit/ui'
|
|
1970
|
+
import { Style } from 'foldkit-mixins'
|
|
1971
|
+
import { Disclosure, DisclosureSlots, Recipes } from 'foldkit-mixins-ui'
|
|
1972
|
+
|
|
1973
|
+
const DetailsStyle = Style.forSlots(DisclosureSlots)(Recipes.Disclosure({ variant: 'bordered' }))
|
|
1974
|
+
|
|
1975
|
+
const details = (isOpen: boolean, h: HtmlBuilder<Message>) =>
|
|
1976
|
+
UiDisclosure.view(
|
|
1977
|
+
{
|
|
1978
|
+
id: 'details',
|
|
1979
|
+
isOpen,
|
|
1980
|
+
onToggle: isOpen => ToggledDetails({ isOpen }),
|
|
1981
|
+
toView: attributes => {
|
|
1982
|
+
const disclosure = Disclosure.resolve(attributes, [DetailsStyle.mixin], {
|
|
1983
|
+
input: undefined,
|
|
1984
|
+
h,
|
|
1985
|
+
})
|
|
1986
|
+
return h.div(
|
|
1987
|
+
[],
|
|
1988
|
+
[
|
|
1989
|
+
h.button(disclosure.button, ['Shipping details']),
|
|
1990
|
+
disclosure.animatePanel(h.div(disclosure.panel, ['Shipped in two days.'])),
|
|
1991
|
+
],
|
|
1992
|
+
)
|
|
1993
|
+
},
|
|
1994
|
+
},
|
|
1995
|
+
h,
|
|
1996
|
+
)
|
|
1997
|
+
```
|
|
1998
|
+
|
|
1999
|
+
## Showing content
|
|
2000
|
+
|
|
2001
|
+
Stateless views: they draw what the application passes and keep nothing. Hide text
|
|
2002
|
+
with `U.srOnly` from `foldkit-mixins/utilities`.
|
|
2003
|
+
|
|
2004
|
+
| Widget | What it is | Recipe and Slots |
|
|
2005
|
+
| --- | --- | --- |
|
|
2006
|
+
| `Table` | The presentational table. `Table.view({ columns: { header, value, numeric?, sortKey?, rowHeader? }[], rows, rowKey?, caption?, fluid?, words?, sort?, selection?, expansion?, empty? }, h)`. A column's `header` is text or markup, its `footer` draws a totals row, and its `value` returns text or markup. Sorting, selection and expansion are the application's. `fluid: Table.fluid` and `selection.control: Table.checkboxes(style?)` are values you pass: a table that passes neither loads neither the pointer highlight nor Checkbox. `Table.configure` binds a look, words and highlight once. See [Table](#table). | `rows`: `lined`, `striped`, `plain`; `density`: `compact`, `regular`, `comfortable`; `header`: `static`, `sticky`, `hidden` (headings for a screen reader alone); `borders`: `rows`, `cells`; `layout`: `auto`, `fixed`. Slots `frame`, `highlight`, `root`, `caption`, `head`, `headerRow`, `foot`, `footerRow`, `footerCell`, `headerCell`, `sortButton`, `sortIcon`, `body`, `row`, `cell`, `control`, `controlCell`, `checkboxLabel`, `expandButton`, `expandIcon`, `detailRow`, `detailCell`, `emptyRow`, `emptyCell`. |
|
|
2007
|
+
| `Card` | `{ title?, description?, content?, image?, media?, action?, footer?, press?, label?, selected?, disabled?, dismiss?, headingLevel?, recoveryPart?, words? }`. `press` is `Press`: `{ onClick }` or `{ href, external? }`, the one type Item shares. `words`: `dismiss` (`'Dismiss {name}'`, `{name}` the title or label), `dismissAlone`, `dismissMark` and `newTab`. `Card.configure({ base, presets })` returns `{ view, group }`. See [Card and Item](#card-and-item). | `orientation`: `stacked`, `inline`, `overlay` (the image fills the card, the text lies over it on a fade to the card's surface); `surface`: `outlined`, `elevated`, `filled`, `plain`; `padding`: `compact`, `comfortable`, `roomy`, `flush`; `elevation`: `0` to `3`; `divide`: `none`, `header`, `sections` (a hairline edge to edge); `lift`: `none`, `hover`, `zoom` (the picture grows inside its frame). Slots `root`, `image`, `media`, `header`, `title`, `description`, `action`, `content`, `footer`, `overlay`, `dismiss`. |
|
|
2008
|
+
| `Card.group` | `{ cards: (CardView & { key })[], columns?, fluid?, label?, wrap?, cardStyle? }`: a keyed list of cards in up to `columns` (default 1), wrapping to fewer where a column would be narrower than the recipe's `minColumn`. Given `fluid: Card.fluid` (from `card/fluid.ts`, so a page that never names it ships no `FluidHover`), one highlight follows the pointer and a press in a gap presses the highlighted card; without it the group draws no highlight and each card hovers on its own. `wrap(card, source)` draws around each card, such as a link. | `Recipes.CardGroup`: `layout`: `divided` (default), `separated`; `minColumn`: `none`, `sm`, `md` (default), `lg`; `border`: `none`, `outlined`. The highlight is a film over the card the pointer is on, and is that card's hover. Slots `root`, `list`, `item`, `highlight`. |
|
|
2009
|
+
| `Item` | The row primitive: `{ header?, media?, title?, description?, content?, actions?, footer?, press?, label?, selected?, disabled?, words? }`; `content` follows the title and description, and `header` and `footer` are bands across the row, pressable above a pressable one. `words.newTab` says what a link opening a new tab says. `Item.group({ items: (ItemView & { key })[], label?, wrap?, style?, itemStyle? })` is a list of them; `wrap(row, source)` draws around each row. `Item.configure({ base, presets })` returns `{ view, group }`. Field is for form controls. | `variant`: `plain`, `outline`, `muted`; `density`: `comfortable`, `compact`, `roomy`; `media`: `plain`, `icon`, `image`. Slots `root`, `header`, `media`, `content`, `title`, `description`, `actions`, `footer`, `overlay`. `Recipes.ItemGroup({ layout: 'divided' \| 'separated' })` over `ItemGroupSlots` (`root`, `row`). |
|
|
2010
|
+
| `Avatar` | `{ name, src?, picture?, initials?, status?, badges?, words? }`. The root is one `role="img"` named by the person (and the status, "Ada Lovelace, Online"); initials show until the picture covers them. `status` is `online`, `away`, `busy`, `offline`, read from `words`. `src` is a URL; `picture` is a value, `Avatar.picture({ asset, provider, width })` from `foldkit-media` (a file of its own, so a page that passes `src` as text ships no media code), drawn with its 1x and 2x candidates at `width` CSS pixels; a provider with no URL for it leaves the initials. Give one of the two. `Avatar.widthOf(size)` is a size's width in CSS pixels. `Avatar.group({ people, max?, label?, words?, rest?, wrap?, style?, avatarStyle? })` overlaps them and counts the rest as one more avatar (`words.more`, `'{count} more'`); `rest(count)` is what the `+N` disc holds in place of its text, an icon say; `wrap(avatar, person)` draws around each avatar, such as a Tooltip's trigger. `badges: [{ content, place, label? }]` puts a mark on a corner (`top-start`, `top-end`, `bottom-start`, `bottom-end`; the bottom end is the status dot's), hidden from assistive technology, its `label` read with the name. `Avatar.configure({ base, presets })` returns `{ view, group }`. | `size`: `xs` to `xl`; `shape`: `circle`, `rounded`, `square`; `color`: `neutral`, `name` (initials in a hue from the name); `ring`: `none`, `page`, `accent`. Slots `root`, `fallback`, `image`, `status`, `badge`. `Recipes.AvatarGroup({ overlap: 'tight' \| 'loose' \| 'none', lift: 'none' \| 'hover' })` over `AvatarGroupSlots` (`root`); `lift: 'hover'` raises the avatar under the pointer, which `travel` stills. |
|
|
2011
|
+
| `Badge` | `{ text, tone?, icon?, onDismiss?, href?, external?, words? }` writes `data-tone`; `onDismiss` draws a dismiss button, `href` draws a link (never both). | `Recipes.Badge({ appearance?, size? })`: `appearance` `tinted` (default), `dot`, `outline`, `solid`; `size` `sm`, `md`, `lg`. The tone is the word the badge carries (`accent`, `neutral`, `info`, `success`, `warning`, `danger`); `Recipes.badgeTones(attribute, map)` through `extend` maps an attribute of your own. Slots `badge`, `icon`, `dismiss`. |
|
|
2012
|
+
| `Typography` | `{ level, text }` or `{ level, content }`, where `content` is a list of text and `Html` (a link, emphasis) in place of `text`. The level chooses the element (`h1`–`h4`, `lead`, `body`, `small`, `muted`, `quote`, `code`, and the interface roles `display`, `title`, `subtitle`, `caption`, `micro` as paragraphs) and is written as `data-level`. | No `level` axis: the recipe reads `data-level`, so the view's level is the one fact; a role is its size and leading on the size ladder. Slot `text`. |
|
|
2013
|
+
| `Separator` | `{ orientation?, label?, decorative? }`, horizontal by default. A `label` sits between two drawn rules and is read as text; `decorative` is `role="none"`. One style draws both orientations. A vertical rule stretches across a flex or grid row, short of it by the inset, and elsewhere (running text) stands as tall as the letters. | `line`: `solid`, `dashed`, `dotted`; `thickness`: `thin`, `thick`; `spacing`: `none`, `sm`, `md`, `lg`; `inset`: `none`, `sm`, `md`. Slots `rule`, `root`, `label`. |
|
|
2014
|
+
| `Empty` | `{ title, description?, icon?, action? }`. The title takes the `subtitle` role; the icon is `aria-hidden`. `Empty.configure({ base, presets })` binds a look once. | `media`: `icon`, `illustration`; `frame`: `none`, `dashed`, `filled`; `tone`: `neutral`, `danger`; `size`: `compact`, `comfortable`. Slots `root`, `icon`, `title`, `description`, `action`. |
|
|
2015
|
+
| `Skeleton` | `{ label?, inline?, block? }`: `role="status"` named by `label`, and `aria-hidden` without one, so a page of placeholders is not a page of empty live regions. `inline` and `block` are CSS lengths of a lone bar (`--fk-skeleton-inline`, `--fk-skeleton-block`). `Skeleton.lines({ lines, label? })`, `avatarRow`, `card` and `tableRow({ columns })` draw the shapes content takes, in a `group`. `Skeleton.configure({ base, presets })` returns all five with one look. | `shape`: `bar`, `circle`; `animation`: `pulse`, `shimmer`, `none`. Slots `bar`, `group`. |
|
|
2016
|
+
| `Carousel` | The APG carousel. A small Model: `Carousel.init({ id, count?, perView?, loop?, index?, autoplay?, delay?, reducedMotion? })`, folded with `Carousel.update()`: the layout (`count`, `perView`, `loop`) is kept in the Model, so `update` and the view read it from one place (`update(layout)` and the view's `perView` and `loop` still override). `Bundles.Carousel.with({ id, count, ... })` places it. `Carousel.view({ label, model, slides, onMessage, loop?, perView?, picker?, thumbnails?, words? }, h)`, `words` being `Carousel.words`' `slide` (with `{index}` and `{count}`), `previous`, `next`, `picker`, `stop` and `start`, merged key by key; `Carousel.configure({ base, presets })` binds them with the look. See [Carousel](#carousel). | `peek`: `none`, `edge`. Slots `root`, `track`, `slide`, `controls`, `rotation`, `previous`, `next`, `picker`, `dot`, `thumbnail`, `status`. |
|
|
2017
|
+
| `Marquee` | After Zag's: content that scrolls on without a seam. A small Model: `Marquee.init({ id })` holds what it measured and whether it is paused, folded with `Marquee.update`. `Bundles.Marquee` places it with `{ id, paused? }` as its args, and reports nothing. `Marquee.view({ model, onMessage, label, items, side?, speed?, autoFill?, repeat?, delay?, loopCount?, words? }, h)` measures its content (`Resize`) and draws copies to fill the viewport, `inert` after the first and drawn without their `id`s, so a document holds each once. A pointer, focus or its pause press (WCAG 2.2.2) holds it; `Marquee.Message.Paused()` holds it from outside. Its motion is CSS, and under reduced motion the viewport scrolls instead. | `spacing`; `edges`: `fade`, `none`. Slots `root`, `viewport`, `content`, `item`, `pause`. |
|
|
2018
|
+
|
|
2019
|
+
### Images, icons and codes
|
|
2020
|
+
|
|
2021
|
+
| Widget | What it is | Recipe and Slots |
|
|
2022
|
+
| --- | --- | --- |
|
|
2023
|
+
| `Image` | `{ asset, provider, layout, alt, priority?, sizes? }` from `foldkit-media`. `Image.watchLoad` and `Image.audit` are mixins in files of their own (`image/watchLoad.ts`, `image/audit.ts`), so a page that names neither ships neither. `Image.configure({ base, presets })` binds a layout and a look; a use with no layout from any layer throws. See [Image](#image). | `fit`: `cover`, `contain`; `edge`: `none`, `line`; `ratio`: `auto`, `square`, `video`, `portrait`; `radius`. Slots `frame`, `source`, `image`. |
|
|
2024
|
+
| `Figure` | `{ content, caption? }`: a `figure` holding its content (an `Image.view`, a chart, a code block), then its caption in a `figcaption`, which names the figure for assistive technology by itself; no caption, no `figcaption`. `Figure.configure({ base, presets })` binds a look once. | `align`: `start`, `center`; `caption`: `after` (default), `before` (the caption is drawn above by CSS `order`; the markup keeps it after the content, so a screen reader reads it there). Slots `root`, `caption`. |
|
|
2025
|
+
| `Frame` | `{ title?, headingLevel?, description?, action?, panels, footer? }`: a tray holding several things that belong together, each in a panel of its own (a few Alerts, a list of Items, an accordion's items); the frame places what it is given and understands none of it. `Frame.configure({ base, presets })` binds a look once. Reach for `Card` when there is one thing to hold. | `variant`: `muted` (default, a quiet step off the page), `outline`, `plain`; `padding`: `comfortable` (default), `none` where the panel's content draws its own room; `spacing`: `compact`, `comfortable`, `roomy`; `radius`: `md`, `lg`, `none`. Slots `root`, `header`, `title`, `description`, `action`, `panels`, `panel`, `footer`. |
|
|
2026
|
+
| `AspectRatio` | `{ content? }`. `AspectRatio.configure({ base, presets })` binds a look (a ratio) once. | `ratio`: `square` (default), `video` (16/9), `portrait` (3/4); another ratio is `Recipes.AspectRatio.add({ ratio: { cinema: { frame: Style.self({ aspectRatio: '21 / 9' }) } } })`. The corner reads `radius`. Slot `frame`. |
|
|
2027
|
+
| `Icon` | `{ icon, label?, key?, mark?, style?, mixins? }` or `{ glyph, label?, mark? }`: an `IconData` drawn as inline SVG with `foldkit-media`'s `Icon.draw`, or a drawing of your own (initials, a count, an emoji) in the box; one or the other. A `label` makes it `role="img"`; without one the glyph is `aria-hidden`. `key` parts two copies of one icon on a page. `mark` is a Badge or a dot on the corner, inside the image. | `size`: `xs`, `sm`, `md`, `lg`, `xl` on the type scale; none (the default) stands on the size ladder. `surface`: `outline`, `soft`, `solid`, `raised` makes the box a tile twice the icon's size; `tone`: `accent`, `neutral`, `info`, `success`, `warning`, `danger`; `shape`: `circle`, `square`. Slots `glyph`, `mark`. |
|
|
2028
|
+
| `CodeBlock` | `{ code, tokens?, language?, title?, lineNumbers?, startLine?, gutter?, marks?, wrap?, collapsed?, onLineSelect?, lineAction?, copy?, words? }`. `tokens` are `{ from, to, kind }`, as `foldkit-richtext-code` and `foldkit-richtext-code-shiki` tokenizers return them; each is drawn with `data-kind`, and a token out of order or outside the code throws. Every line number the block hands out counts from `startLine` (default 1). `marks: [{ line, kind }]` writes `data-mark` on a whole line (`added`, `removed`, `highlight`, `error`, `warning`, `dim`, `selected`, or a kind of your own; a mark off the code, or two on a line, throws); `gutter(line)` is a line's gutter text in place of its number (a patch's `+`, two columns of numbers); `wrap` wraps long lines; `collapsed: { lines, onExpand }` draws the first lines and a button that sends `onExpand` (`words.expand`, `{count}`), the expanded state the application's; `onLineSelect(line)` makes each gutter a button (`words.selectLine`, pressed on a line marked `selected`); `lineAction(line)` is an `Option` of Html at the line's end. The gutter draws from `data-number`, so the block's text is the code exactly, bar what `lineAction` adds. `copy: { onCopy?, copied? }`: `onCopy` gets the code, so run `copyText` from `foldkit-primitives`; without it the button has no handler, for a page whose script copies. `CodeBlock.follow`, passed in `mixins`, keeps a growing block's end in view while the reader is at it. `CodeBlock.linesOf` is the cut; a final line break is not a numbered line, and a copy is announced in the `status` slot. | `header`: `bar` (default) or `float` (no bar; the copy button pins to the code's corner); `scheme`: `page` (default) or `dark`. Colors each kind from the theme's `syntax` group and tints each line by its mark across the row; `data-copied` marks a copy done. Slots `root`, `header`, `title`, `copy`, `status`, `body`, `code`, `line`, `gutter`, `token`, `lineAction`, `expand`. |
|
|
2029
|
+
| `QrCode` | After Zag's: `QrCode.view({ id, value, label?, level?, quietZone?, overlay?, words?, style? }, h)`, one `img` named `QR code: <value>` (or `label`), every dark module one SVG `path` over a background that carries the quiet zone. `level` is the error correction, `M` by default and `H` under an `overlay` (a logo at the centre). `QrCode.encode(text, level)` gives the matrix, none when no version holds the text, and `pathOf` its path; both are pure. `QrCode.Download({ id, format, filename, pixels })` saves the drawn code as PNG or SVG in the colors it shows; the overlay is not in the file. | `scheme`: `light` (dark on light on any page), `page`; `size`. Slots `root`, `frame`, `background`, `pattern`, `overlay`, `fallback`. |
|
|
2030
|
+
| `Chart` | After shadcn's Chart. A small Model for the lit point: `Chart.init()`, folded with `Chart.update`. `Chart.view({ id, label, kind, categories, series: [{ name, values, color? }], model, onMessage, description?, format?, legend?, table?, categoryLabel? }, h)`, where `kind` is a value you pass: `Chart.bars` (`stack?`), `Chart.line` (`curve?`, `markers?`) or `Chart.area` (`stack?`, `curve?`, `markers?`), or `Chart.donut` with `slices: [{ name, value, color? }]`, `totalLabel?` and `hole?` (`0` is a pie). A page ships the kinds it names. A `ChartKind` of your own is an object with `entries`, `points`, `head` and `draw`, and gets the title, legend, status line and data table from the chart. See [Chart](#chart). | `height`: `sm`, `md`, `lg`; `grid`: `lines`, `zero`; `indicator`: `dot`, `line`. Slots `root`, `title`, `description`, `legend`, `legendItem`, `swatch`, `body`, `yAxis`, `xAxis`, `yTick`, `xTick`, `plot`, `canvas`, `paths`, `grid`, `cursor`, `bar`, `line`, `area`, `dot`, `slice`, `band`, `center`, `centerValue`, `centerLabel`, `tooltip` and its parts, `status`, `table` and its parts. |
|
|
2031
|
+
| `ImageCropper` | After Zag's: the image fitted in a viewport, a selection that a drag moves and eight handles resize, zoom by a Slider, the wheel, two fingers or `+`/`-`, a pan of the zoomed image, quarter turns, an aspect lock and a round crop. A small Model: `ImageCropper.init({ id, aspect?, shape?, crop?, min?, maxZoom? })` holds the crop, in the turned image's pixels, folded with `ImageCropper.update`. `Bundles.ImageCropper` places it with `init`'s options as its args; an export the application asks for (`RequestedExport`, sent to the placed child) comes back in `onOut` as `ImageCropper.OutMessage`, `Exported { url, width, height }` or `FailedExport { reason }`. `ImageCropper.view({ model, onMessage, label, src, crossOrigin?, controls?, zoom?, words?, disabled? }, h)`. `zoom: ImageCropper.zoomSlider(style?)` draws the zoom Slider, and a cropper given none draws none and ships no Slider (the wheel and `+`/`-` still zoom). `ImageCropper.crop(model)` is the crop in whole pixels (an `Option`); `RequestedExport({ type, quality })` returns the `Export` Command, answered by `Exported({ url, width, height })` or `FailedExport`. Keys (arrows, Shift ×10, Alt to resize) step by screen pixels. | `guides`; `handles`: `all`, `corners`; `viewport`: `landscape`, `wide`, `square`. `zoomSlider`'s style takes `Recipes.Slider({ label: 'hidden' })`. Slots `root`, `label`, `viewport`, `stage`, `pan`, `image`, `selection`, `guides`, `handle`, `controls`, `zoom`, `rotate`, `reset`. |
|
|
2032
|
+
| `SignaturePad` | After Zag's: strokes drawn by one pointer over a dashed line and "Sign here", undo, redo, clear, and a typed name instead. A small Model: `SignaturePad.init({ id, pen?, pointers? })` holds the strokes (points with pressure, in the pad's coordinates) and what undo took, for redo (a new stroke or a clear forgets it), folded with `SignaturePad.update`. `pointers` are the kinds that may draw (`'mouse' | 'pen' | 'touch'`, default all), so `['pen']` ignores a resting palm. `Bundles.SignaturePad` places it with `{ id, pen?, pointers? }` as its args; a PNG the application asks for (`RequestedPng`) comes back in `onOut` as `SignaturePad.OutMessage`, `ExportedPng { url, width, height }` or `FailedExport { reason }`. `SignaturePad.view({ model, onMessage, label, fallback?, name?, words?, disabled? }, h)`. `name` submits the signature with a form, as the SVG `toSvg` writes (empty while there is none). `pathOf(stroke, pen)` and `toSvg(model, { color?, font? })` are pure; `RequestedPng({ scale, background })` returns `ExportPng`, answered by `ExportedPng({ url, width, height })` or `FailedExport`. | `surface`: `plain`, `muted`, `dashed`; `size`. Slots `root`, `label`, `control`, `segments`, `stroke`, `guide`, `placeholder`, `typedName`, `controls`, `undo`, `redo`, `clear`, `fallback`, `fallbackLabel`, `input`, `hiddenInput`. |
|
|
2033
|
+
|
|
2034
|
+
```ts
|
|
2035
|
+
import { parse } from 'foldkit-media/icons'
|
|
2036
|
+
import { Style } from 'foldkit-mixins'
|
|
2037
|
+
import { AspectRatio, AspectRatioSlots, Icon, IconSlots, Recipes } from 'foldkit-mixins-ui'
|
|
2038
|
+
|
|
2039
|
+
const Frame = Style.forSlots(AspectRatioSlots)(Recipes.AspectRatio({ ratio: 'video' }))
|
|
2040
|
+
const Mark = Style.forSlots(IconSlots)(Recipes.Icon({ size: 'sm' }))
|
|
2041
|
+
|
|
2042
|
+
// `h` is the view's builder. `content` is `Html`.
|
|
2043
|
+
AspectRatio.view({ content: h.span([], ['poster']), style: Frame }, h)
|
|
2044
|
+
|
|
2045
|
+
// An icon as data: an import from `virtual:foldkit-icons/…`, or parsed by a script.
|
|
2046
|
+
const check = parse('<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M20 6 9 17l-5-5"/></svg>', 'check')
|
|
2047
|
+
Icon.view({ icon: check, label: 'Done', style: Mark }, h)
|
|
2048
|
+
Icon.view({ icon: check, style: Mark }, h)
|
|
2049
|
+
```
|
|
2050
|
+
|
|
2051
|
+
`Icons.glyph` is the other tool: a mask on an element that already exists.
|
|
2052
|
+
|
|
2053
|
+
### Table
|
|
2054
|
+
|
|
2055
|
+
A column with `rowHeader` draws its cells as `th scope="row"`, so a screen reader
|
|
2056
|
+
names a row by it. A column with a `sortKey` heads with a button that sends
|
|
2057
|
+
`sort.onSort(column)`, and the sorted column carries `aria-sort`;
|
|
2058
|
+
`Table.nextSort(sort, column)` cycles ascending, descending and none. A column's
|
|
2059
|
+
`sortKey` keeps the literal it is written as, so `onSort` receives `'name' | 'price'`
|
|
2060
|
+
and not a `string`: a Message field of `Schema.Literals(['name', 'price'])` needs no guard
|
|
2061
|
+
in `update`. Columns written in the call infer it; columns hoisted into a constant go
|
|
2062
|
+
through `Table.defineColumns<Row>()([...])` (or `as const`), and a call that names its
|
|
2063
|
+
type arguments (`Table.view<Row, Message>`) gets `string`. `selection`
|
|
2064
|
+
puts a checkbox on every row and one in the heading, mixed while only some are
|
|
2065
|
+
chosen; `expansion` opens a row's detail in a row below it (`aria-expanded`,
|
|
2066
|
+
`aria-controls`; its buttons' column is headed `Details` for a screen reader,
|
|
2067
|
+
`words.details` renames it); `empty` stands across the table while there are no rows
|
|
2068
|
+
(an `Empty.view`). The sort, the chosen and the open rows are the application's. The
|
|
2069
|
+
table stands in a `frame`, which scrolls sideways when the table is wider than the
|
|
2070
|
+
screen (under a `static` header; a `sticky` one sticks to the application's scroller,
|
|
2071
|
+
which scrolls it). With `fluid: Table.fluid`, one highlight behind the body rows follows the
|
|
2072
|
+
pointer, skipping detail and empty rows. Filtering, column reorder and resize, and
|
|
2073
|
+
virtualized rows stay with `foldkit-data-grid`. A selection draws its boxes through `control: Table.checkboxes(style?)`, which is where Checkbox is imported, and one of your own is an object with a `draw`. A column's `footer` draws a totals row after the body, its control columns left blank; a `header` that is markup holds an icon beside the words; the recipe's `header: 'hidden'` keeps the headings for a screen reader (a table read down its first column), `borders: 'cells'` boxes the cells and `layout: 'fixed'` gives each column an equal share.
|
|
2074
|
+
|
|
2075
|
+
A keyed row that a re-sort moves is taken out of the tree and put back, which
|
|
2076
|
+
blurs the control focused inside it. `FocusRecovery.behavior(TableSlots)({ owner: 'frame',
|
|
2077
|
+
parts: { expandButton: ['same'], sortButton: ['same'], control: ['same'] } })`, given
|
|
2078
|
+
in `mixins`, finds the control again at its new place. A control you draw in a cell is
|
|
2079
|
+
a part when you mark it: `h.DataAttribute(FOCUS_MARK.part, 'control')` and
|
|
2080
|
+
`h.DataAttribute(FOCUS_MARK.key, rowKey)` (`FOCUS_MARK` is from `foldkit-primitives/dom`).
|
|
2081
|
+
|
|
2082
|
+
```ts
|
|
2083
|
+
import { Option } from 'effect'
|
|
2084
|
+
import { Table, TableSlots } from 'foldkit-mixins-ui'
|
|
2085
|
+
|
|
2086
|
+
interface Product {
|
|
2087
|
+
readonly name: string
|
|
2088
|
+
readonly price: string
|
|
2089
|
+
}
|
|
2090
|
+
|
|
2091
|
+
const Sort = defineMessageUnion({ Sorted: { column: Schema.Literal('name') } })
|
|
2092
|
+
type Sort = typeof Sort.Type
|
|
2093
|
+
|
|
2094
|
+
const ProductsStyle = Style.forSlots(TableSlots)(Recipes.Table({}))
|
|
2095
|
+
|
|
2096
|
+
const productsTable = (
|
|
2097
|
+
rows: ReadonlyArray<Product>,
|
|
2098
|
+
sorted: Option.Option<Table.TableSort<'name'>>,
|
|
2099
|
+
h: HtmlBuilder<Sort>,
|
|
2100
|
+
) =>
|
|
2101
|
+
Table.view(
|
|
2102
|
+
{
|
|
2103
|
+
columns: [
|
|
2104
|
+
{ header: 'Product', sortKey: 'name', rowHeader: true, value: row => row.name },
|
|
2105
|
+
{ header: 'Price', numeric: true, value: row => row.price },
|
|
2106
|
+
],
|
|
2107
|
+
rows,
|
|
2108
|
+
rowKey: row => row.name,
|
|
2109
|
+
sort: { by: sorted, onSort: column => Sort.Sorted({ column }) },
|
|
2110
|
+
style: ProductsStyle,
|
|
2111
|
+
},
|
|
2112
|
+
h,
|
|
2113
|
+
)
|
|
2114
|
+
// in update, on Sorted: modifyFields(model, { sorted: () => Table.nextSort(model.sorted, column) })
|
|
2115
|
+
```
|
|
2116
|
+
|
|
2117
|
+
### Card and Item
|
|
2118
|
+
|
|
2119
|
+
`press` is `{ onClick }` or `{ href, external? }`: one button or link stretched over
|
|
2120
|
+
the card (`overlay`, from `press.ts`, shared with Item; its type is `Press`), named by `label` or the title (a pressable
|
|
2121
|
+
card with neither throws); `action`, `footer` and the dismiss button stay pressable
|
|
2122
|
+
above it. `selected` is `aria-pressed` on the button, `aria-current="page"` on the
|
|
2123
|
+
link. `headingLevel` (2 to 6, default 3) is the level of the title's heading. A
|
|
2124
|
+
`disabled` card's overlay is `aria-disabled` and sends nothing, so it stays focusable
|
|
2125
|
+
(a link loses its `href`). `dismiss: { onDismiss, always? }` is revealed on
|
|
2126
|
+
hover and focus unless `always`, and always on a touch screen; its name and mark are
|
|
2127
|
+
`words.dismiss` and `words.dismissMark`. `recoveryPart` marks
|
|
2128
|
+
the dismiss button as a `FocusRecovery` part (see [Focus after
|
|
2129
|
+
removal](#focus-after-removal)). The root carries `data-selected`, `data-disabled`,
|
|
2130
|
+
`data-pressable` and `data-dismissible` (the header then keeps clear of the button).
|
|
2131
|
+
|
|
2132
|
+
In the recipe an `image` bleeds to the card's edges (16:9 when stacked); `media`
|
|
2133
|
+
puts a bare icon (`svg`, `img`) in a tile and lets anything else, an Avatar say, lead
|
|
2134
|
+
at its own size. `elevation` is a step of the surface ladder (lighter in a dark
|
|
2135
|
+
scheme; a contact and an ambient shadow in a light one). `lift: 'hover'` lifts under
|
|
2136
|
+
the pointer, which `travel` stills (not in a `Card.group` given `fluid: Card.fluid`, whose
|
|
2137
|
+
highlight is the hover there). In a group, a card draws no hover of its own, whatever its
|
|
2138
|
+
`surface`; divided cards are usually `surface: 'plain'`.
|
|
2139
|
+
|
|
2140
|
+
An `Item`'s `press` is the same stretched control, named by `label` or the title, with
|
|
2141
|
+
`actions` staying pressable above it; `selected` is `aria-pressed` or `aria-current`.
|
|
2142
|
+
An avatar beside a name and a line is an Item with the avatar as its media. `header` and
|
|
2143
|
+
`footer` are bands across the row above the overlay, for a heading or a note that holds
|
|
2144
|
+
controls of its own. An Item page does not ship `Card` or `FluidHover`: both read
|
|
2145
|
+
`press.ts`.
|
|
2146
|
+
|
|
2147
|
+
### Carousel
|
|
2148
|
+
|
|
2149
|
+
Previous and next are `aria-disabled` at the ends unless `loop`; a dot per place the
|
|
2150
|
+
track can rest (or `thumbnails` in their place) and a polite status name the slide
|
|
2151
|
+
shown. Each slide is a group named "2 of 5". The track is a CSS scroll-snap scroller,
|
|
2152
|
+
so swipes move it natively, and `ScrollSettle` reports where a swipe rests, so the
|
|
2153
|
+
dots follow the finger. Every press, swipe and timer reaches `update`, which returns
|
|
2154
|
+
the `Carousel.ShowSlide` Command that scrolls the track: do not keep the slide
|
|
2155
|
+
yourself. With `autoplay` it moves on every `delay` (4s), the current dot filling as
|
|
2156
|
+
it waits; it pauses under the pointer, stops when focus arrives by the keys, quiets
|
|
2157
|
+
its status while it rotates, and draws the APG's rotation button first.
|
|
2158
|
+
`reducedMotion` in `init` (the application's reading of `prefers-reduced-motion`,
|
|
2159
|
+
from its flags or a `MediaQuery`; `init` stays pure so a server's Model equals the
|
|
2160
|
+
client's) starts an autoplaying carousel stopped, with the rotation button to start
|
|
2161
|
+
it. A slide out of view is `inert`, so its content takes no focus, which would scroll
|
|
2162
|
+
the track.
|
|
2163
|
+
|
|
2164
|
+
### Image
|
|
2165
|
+
|
|
2166
|
+
A `picture` with a `source` per format the provider offers and an `img` with its
|
|
2167
|
+
candidates, `sizes`, `width` and `height` (the box is held before the file arrives),
|
|
2168
|
+
lazy unless `priority` (then `fetchpriority="high"`). `alt` is what the image shows in
|
|
2169
|
+
words (a string, or `Image.described(text)`) or `Image.decorative` (`alt=""`,
|
|
2170
|
+
`role="presentation"`), never omitted. `Provider.hosted` takes only a `HashedAsset`, so
|
|
2171
|
+
facts without a content hash are a type error there. The `img` carries
|
|
2172
|
+
`--fk-image-ratio`, `--fk-image-placeholder` (none behind a transparent image) and
|
|
2173
|
+
`data-layout` (`fixed`, `constrained`, `full`); a provider with no URL for the image
|
|
2174
|
+
leaves an empty frame marked `data-unavailable`, which keeps its box and is
|
|
2175
|
+
`role="img"` named by its alt text (hidden when decorative). `--fk-image-focus` places
|
|
2176
|
+
a crop at the asset's focal point. `placeholder: 'detail' | 'average'` chooses how much
|
|
2177
|
+
of a ThumbHash to paint; by default the picture for `priority`, the color otherwise.
|
|
2178
|
+
`Image.watchLoad`, beside the style, marks the `img`'s `data-state` (`loading`,
|
|
2179
|
+
`loaded`, `failed`); the recipe hides a failed image, keeping its box. `Image.audit`,
|
|
2180
|
+
beside the style in a development build, warns in the console of an image drawn wider
|
|
2181
|
+
than its file (blurry) or far narrower (wasted bytes), and of more than one image drawn
|
|
2182
|
+
with `priority`. `Image.preloadsIn` is a `foldkit-ssr` `Head`: the `<link
|
|
2183
|
+
rel="preload">` of each image the rendered page drew with `priority`.
|
|
2184
|
+
|
|
2185
|
+
### Chart
|
|
2186
|
+
|
|
2187
|
+
The value axis's ticks are round and reach both ends, zero included; the plot is drawn
|
|
2188
|
+
in percentages, so it fills its container's width with nothing measured and renders the
|
|
2189
|
+
same on a server. The pointer lights a category's band and its tooltip, and the plot is
|
|
2190
|
+
a tab stop whose arrows, Home and End step through the points while a polite status says
|
|
2191
|
+
each. The drawing is hidden from assistive technology, which reads a data table,
|
|
2192
|
+
visually hidden unless `table: 'shown'`. Series take `chart-1` to `chart-5` in order, or
|
|
2193
|
+
the `color` they name; a sixth series throws. `kind` is a value you import, so a page ships the kinds it draws: `Chart.bars` (`stack: true` puts one series on another), `Chart.line` and `Chart.area` (`curve: 'step'` runs level to the next category before it rises; `markers: 'always'` puts a dot on every point; an area takes `stack`), and `Chart.donut` (`hole: 0` is a pie, with no total in it). A kind of your own is a `ChartKind`: its `entries`, `points` and `head` say what the legend, the status line and the data table read, and its `draw` is given a `ChartFrame` (the lit point, the legend, the plot's attributes and a `pointer(at)` attribute) and returns the plot, so the title, the legend placement, the status and the table stay the chart's.
|
|
2194
|
+
|
|
2195
|
+
## Feedback and status
|
|
2196
|
+
|
|
2197
|
+
| Widget | What it is | Recipe and Slots |
|
|
2198
|
+
| --- | --- | --- |
|
|
2199
|
+
| `Alert` | `{ layout, title, description?, icon?, actions?, onDismiss?, words?, recoveryPart? }`, and by `layout`: `'inline'` takes `assertive?` and is a live region inside the content, of something that just happened (`role="alert"` when assertive, `role="status"` otherwise); `'banner'` takes `label` and is a full-width strip across a page or a section, there on load, so a `section` landmark named by `label` rather than a live region, which would say nothing on load. Each action is `{ label, href }` (a link) or `{ label, onClick }` (a button); `onDismiss` draws a close button named by `words.dismiss` (`'Dismiss {name}'`, `{name}` the title inline and the label as a banner) with the mark `words.dismissMark`. The icon is `aria-hidden`; whether it shows is the application's. The root writes `data-layout` and `data-dismissible`. `recoveryPart`: see [Focus after removal](#focus-after-removal). `Alert.configure({ base, presets })` binds a look and words. | `tone`: `info` (default), `success`, `warning`, `danger`, `neutral`, `accent`; `emphasis`: `subtle` (default, the family's tint), `bold` (its fill; the neutral tone inverts the page). Slots `root`, `icon`, `title`, `description`, `actions`, `action`, `dismiss`. |
|
|
2200
|
+
| `Toast` | A stack of toasts, Sonner's. A small Model: `Toast.init(id, { position?, direction?, duration?, max?, threshold? })`, folded with `Toast.update`, whose `Acted` OutMessage names a pressed action. `Toast.show(model, { type?, title, description?, actions?, cancel?, duration? })` returns the stack and the new toast's `id`; `Toast.settle(model, id, input)` turns a toast into its outcome; `Toast.dismiss(model, id)` takes it away; `Toast.nextId(model)` is the id the next `show` will give. `Toast.view({ model, onMessage, label?, words?, expand?, icons? }, h)`, with `Toast.configure({ base, presets })` and `Bundles.Toast.with({ id, position?, direction?, duration?, max?, threshold? })`, whose `helpers` are `show`, `settle` and `dismiss`. Adapter over the `ToastView` fork for toasts that carry their own payload. See [Toast](#toast). | `tone`: `plain` (default), `invert` (the text's ink as the card), `rich` (each type on its tint). Slots `container`, `entry`, `list`, `icon`, `body`, `title`, `description`, `actions`, `action`, `cancel`, `close`, `status`, `alert`. |
|
|
2201
|
+
| `Progress` | `@foldkit/ui`'s Progress. `Progress.view({ id, label, value, min?, max?, valueText?, showValue?, buffer?, segments? }, h)` draws a `progressbar` named by its label. `value` is an `Option`; none is indeterminate, and the bar's fill sweeps toward the inline end, leftward right to left. The root carries the share done as `--fk-progress`. `showValue` draws the value (`valueText`, else a percentage) at the end of a bar's label line and inside a ring. A `value` given as `ProgressSection`s is one stacked bar of toned parts, read aloud as their sum; `buffer` draws how far the work could go behind the fill; `segments` cuts the track into steps. | `shape`: `bar` (default), `ring`; `tone`: `accent`, `neutral`, `success`, `warning`, `danger`, `info`; `stripes`: `none`, `still`, `moving` (travel-aware); `size`. Slots `root`, `label`, `track`, `indicator`. |
|
|
2202
|
+
| `Meter` | `@foldkit/ui`'s Meter, a measurement where `Progress` is work. `Meter.view({ id, label, value, min?, max?, low?, high?, optimum?, valueText?, orientation?, segments? }, h)` draws a `meter` named by its label. `orientation: 'vertical'` stands the track upright (its length `--fk-meter-length`, 8rem), the fill growing from its block end; `segments` (an integer of at least 2) cuts the track into equal steps. The root says how good the value is as `data-level` (`good`, `fair`, `poor`), as the HTML meter judges it; `Meter.levelOf` is that judgment. | `size`: `sm`, `md`, `lg` (the track's thickness); the fill takes success, warning or error by level. Slots `root`, `label`, `track`, `fill`. |
|
|
2203
|
+
| `Spinner` | `{ label?, showLabel? }`. `role="status"` named by `label`, and `aria-hidden` without one; `showLabel` draws the label beside the wheel. A turn is about 720ms times `travel`. | `kind`: `ring` (default), `dots`, `bars`, `pulse`, `orbit`; `size`; `tone`: `accent`, `neutral`, `current`, and the status tones `info`, `success`, `warning`, `danger`. Slots `wheel`, `part`, `root`, `text`. |
|
|
2204
|
+
| `Timer` | After Zag's: a countdown (`Timer.init({ id, countdown: true, duration })`) or a stopwatch (`Timer.init({ id, interval? })`), folded with `Timer.update`, whose Commands (`Timer.Stamp`, `Timer.Tick`) read Effect's `Clock`, so TestClock drives a run. `Timer.view({ model, onMessage, label, units?, separator?, controls?, words? }, h)`: a `role="timer"` with each unit in a Slot, one press that says what comes next, and reset; `words` renames the presses (`Timer.words` are the defaults). `Bundles.Timer.with({ id, countdown?, duration?, interval? })` places the state (a countdown without a `duration` throws at placement), and `Timer.configure({ base, presets })` fixes the look, units and words once. `Timer.phase(model)` is `idle`, `running`, `paused` or `done`; to start at once, return `Timer.update(model, Timer.Message.Pressed({ action: 'start' }))` from `init`. | `tone`, `look`, `progress`, `size`. Slots `root`, `label`, `area`, `item`, `separator`, `controls`, `action`. |
|
|
2205
|
+
|
|
2206
|
+
### Toast
|
|
2207
|
+
|
|
2208
|
+
The newest stand in front, spread out while the pointer or focus holds the stack, at
|
|
2209
|
+
most `max` (3) showing; a held stack or a hidden page pauses every countdown, keeping
|
|
2210
|
+
the time left; a swipe toward the edge past `threshold` dismisses one. A toast is
|
|
2211
|
+
spoken in a polite region, an error in an assertive one, each toast a keyed child of
|
|
2212
|
+
its own (the regions are not atomic), so one added beside another, or with the same
|
|
2213
|
+
words, is still read by itself. A toast takes `actions` (each a `{ label, value }`
|
|
2214
|
+
that dismisses it and says its `value` in `Acted`) and a `cancel` (words for a button
|
|
2215
|
+
that only dismisses it), drawn in an `actions` row before the close button. A toast
|
|
2216
|
+
that is already leaving does not act again when an action is pressed. A promise toast
|
|
2217
|
+
is `show` with `type: 'loading'`, the work run as a Command, and `settle` on the
|
|
2218
|
+
toast's `id` when its Message comes back; through `Bundles.Toast` the helpers return
|
|
2219
|
+
no id, so read `Toast.nextId(model)` before `show`. `words` is `{ label, close }`
|
|
2220
|
+
(`Toast.words`); `tone: 'invert'` is the text's ink as the card, as Sonner's inverted
|
|
2221
|
+
toasts. A payload toast that shows progress replaces what an entry holds with
|
|
2222
|
+
`ToastView.make(schema).revise(model, entryId, payload)`, keeping its place,
|
|
2223
|
+
animation and dismissal timing; upstream has no such operation.
|
|
2224
|
+
`ToastView` binds upstream's `Toast.make` for the payload and swaps in the
|
|
2225
|
+
transcribed view; the dismiss control stays inside the consumer's `entryToView`, so it
|
|
2226
|
+
is content, not a slot. `Toast.keepFocus` hands focus from a dismissed toast to a
|
|
2227
|
+
neighbour (see [Focus after removal](#focus-after-removal)).
|
|
2228
|
+
|
|
2229
|
+
## Long lists and scrolling
|
|
2230
|
+
|
|
2231
|
+
| Widget | What it is | Recipe and Slots |
|
|
2232
|
+
| --- | --- | --- |
|
|
2233
|
+
| `ScrollArea` | `{ content }`. The height that makes it scroll is the caller's mixin, on `viewport` or `root`; a width goes on `root`, which the viewport fills and the bars lie over. The viewport is tabbable; a `label` makes it a `region` landmark of that name. A bar per axis is drawn beside the viewport, and `ScrollArea.overlayBars` lays them over its edge (see [Overlay scroll bars](#overlay-scroll-bars)). `overlayBars` lives in `scrollArea/overlayBars.ts`, so a page that never names it ships no `ScrollBars`. `ScrollArea.configure({ base, presets })` binds the look and the mixins (height, bars). | `orientation`: `vertical` (default), `horizontal`, `both`; `vertical` and `horizontal` fade the content toward an edge with more past it and draw a hairline there. `gutter`: `auto` (default), `stable` (`scrollbar-gutter: stable`, so content does not shift as a bar appears). Slots `root`, `viewport`, `bar`, `thumb`. |
|
|
2234
|
+
| `Resizable` | shadcn's Resizable and the APG's window splitter. A small Model: `Resizable.init(share, bounds?)`, its `Message`, and `update(model, message, bounds?)`; the bounds (`min`, `max`, `step`, `collapsible`, `collapsedTo`) are kept in `Model.bounds`, so `update` and the view read the one copy (a call's own bounds still win). `Bundles.Resizable.with({ share?, min?, max?, step?, collapsible?, collapsedTo? })` places it. `Resizable.view({ model, onMessage, id?, label, first, second, orientation?, direction?, min?, max?, step?, collapsible?, collapsedTo? })`. `Resizable.configure({ base, presets })` binds the look and orientation. See [Resizable](#resizable). | `handle`: `line` (default), `grip`, `pill` (a capsule that takes the accent while held); `data-orientation` lays it out. Slots `root`, `first`, `handle`, `second`. |
|
|
2235
|
+
| `VirtualList` | `@foldkit/ui`'s virtual list. `VirtualList.view({ model, items, itemToKey, itemToView, onMessage, overscan?, itemToRowHeightPx? \| dynamicRowHeights? }, h)` draws only the rows in view. Its Model is upstream's (`@foldkit/ui/virtualList`'s `init`), kept by the application and folded with that module's `update`, or placed with `Bundles.VirtualList` (args `{ id, rowHeightPx, initialScrollTop?, followEnd?, nearEndPx? }`), which with `nearEndPx` reports `NearEnd` when a scroll brings the list's end that close to the view, for loading the next page. A row's mixins may style it, not handle its events, since it is drawn inside the list's submodel. A bar is drawn beside the list, and `VirtualList.overlayBars` (a file of its own) lays it over the list's edge. It keeps no row drawn once it leaves the window, the one holding focus included, which `WindowList` does. | No axis. Slots `root` (the box it scrolls within: 18rem tall by default and as wide as its container, offering 20rem where the container takes its width from it), `row`, `bar`, `thumb`. |
|
|
2236
|
+
| `WindowList` | A virtual list that scrolls with the window. A small Model: `WindowList.init({ id, estimatedHeight, unmeasured?, overscan?, viewportHeight?, from? })`, folded with `WindowList.update`, which returns an `Update.Return` (the model and, for a `Found` match, the `Reveal` Command), so the application's own `update` returns the commands too; or placed with `Bundles.WindowList` (`init`'s options as args, `helpers.reveal(index, align?)`). `WindowList.view({ model, items, itemToKey, itemToView, onMessage, label?, findable? }, h)`. See [WindowList](#windowlist). | `Recipes.WindowList`: no look, only the spacers hidden where no script runs (`Utilities.scriptedOnly`); `.extend` it with the list's look. Slots `root` (`role="list"`), `spacer` (`data-edge` `start` or `end`, hidden from assistive technology), `row` (`role="listitem"`). |
|
|
2237
|
+
|
|
2238
|
+
### Resizable
|
|
2239
|
+
|
|
2240
|
+
The handle is a `separator` with its value, stepped by the arrows and sent to the
|
|
2241
|
+
bounds by Home and End (a `collapsible` panel collapses when the key reaches its
|
|
2242
|
+
side, as the APG asks, and a collapsed one leaves the key alone); with an `id` the
|
|
2243
|
+
handle's `aria-controls` names the first panel; a drag follows the `Move` Mount from
|
|
2244
|
+
where it began over the group the `Resize` Mount measured. Under `direction: 'rtl'`
|
|
2245
|
+
the first panel is on the right, so ArrowLeft and a drag to the left grow it.
|
|
2246
|
+
`collapsible: 'first' | 'second'` (with `collapsedTo`) collapses that panel on Enter or
|
|
2247
|
+
a double-click and puts it back where it was, easing there while a drag follows the
|
|
2248
|
+
pointer at once; the bounds `init` was given are read by both `update` and the view. A split fills its
|
|
2249
|
+
panel, so splits nest either way.
|
|
2250
|
+
|
|
2251
|
+
### WindowList
|
|
2252
|
+
|
|
2253
|
+
It draws the rows in view of the document's viewport between spacers as tall as the
|
|
2254
|
+
rest, so the page keeps its own scrolling: the browser restores its offset, a `sticky`
|
|
2255
|
+
header above the list sticks, and Space and End move it. Use `VirtualList` for a list
|
|
2256
|
+
in a box of its own.
|
|
2257
|
+
|
|
2258
|
+
- **Measuring.** Its one Mount on `root`, `WindowList.Track`, reads where the viewport
|
|
2259
|
+
lies over the list on every scroll, resize and resize of the page (`WindowViewport`),
|
|
2260
|
+
so content above it, or growing above it, counts, and measures each drawn row's border
|
|
2261
|
+
box (`MeasureRows`; space rows with padding: a row is `flow-root`). The rows already
|
|
2262
|
+
drawn when it starts are read at once, so no row leaves before its height is known. A
|
|
2263
|
+
row not yet measured counts `estimatedHeight`, or with `unmeasured: 'mean'` the mean of
|
|
2264
|
+
the rows measured above 0: for rows whose height the window's width decides, which
|
|
2265
|
+
`init` cannot know. A row still drawn is measured again only when it resizes, so keep
|
|
2266
|
+
the keys of the rows drawn: `WindowList.windowOf(model, keys)` is which rows are drawn,
|
|
2267
|
+
for loading what is in view, and `WindowList.keep(model, keys)` drops the heights of
|
|
2268
|
+
rows that left. A Scene test of a page drawing the list resolves it with
|
|
2269
|
+
`Scene.Mount.resolveAll(WindowList.resolveTrack(onMessage,
|
|
2270
|
+
WindowList.Message.Placed({ top, height })))`, the reading going through the view's own
|
|
2271
|
+
`onMessage`.
|
|
2272
|
+
- **Held row.** A row holding focus stays drawn beside the window while it is scrolled
|
|
2273
|
+
out (`Message.Focused` reports it as `Model.held`, `WindowList.heldRow(model, keys)` is
|
|
2274
|
+
its index, and `keep` retains its height), so the reader keeps their place in the tab
|
|
2275
|
+
order; `VirtualList` keeps neither.
|
|
2276
|
+
- **Reveal.** `WindowList.reveal(model, index, align?)` is the `Reveal` Command that
|
|
2277
|
+
scrolls the page until row `index` is drawn and shown, however far outside the window
|
|
2278
|
+
(`align`: `nearest` by default, `start`, `center` or `end`); return it from an
|
|
2279
|
+
`update`, and it answers `Message.CompletedReveal`.
|
|
2280
|
+
- **Find in page.** `findable: (item, index) => text` lets the browser's find in page
|
|
2281
|
+
match rows that are not drawn: each row outside the window is a `hidden="until-found"`
|
|
2282
|
+
stand-in holding that text in the spacers, which keep their height, and a match
|
|
2283
|
+
(`Message.Found`) reveals its row. It costs a node and a text node per row, so it is
|
|
2284
|
+
for lists of thousands; it is drawn once the runtime has placed the list and only where
|
|
2285
|
+
`WindowList.supportsFindable()` says the browser finds hidden text.
|
|
2286
|
+
- **Server pages.** A server's page opens the list at a row with `from` (a page's
|
|
2287
|
+
`?from=`): the window starts at that row, with no overscan above it, and the rows above
|
|
2288
|
+
take no room until `Track` places the list, which gives them their room and scrolls the
|
|
2289
|
+
window by what that moved the first row drawn, so a reader sees the same rows before and
|
|
2290
|
+
after the runtime takes the page over. The first `Placed` sets `from` back to 0, and
|
|
2291
|
+
the list follows the window. For a page without scripts, `WindowList.pageOf(model,
|
|
2292
|
+
keys)` is `{ start, end, previous, next }`: the rows drawn and, as `Option`s, the rows
|
|
2293
|
+
the pages either side open at (`previous` the first whose window reaches this one's
|
|
2294
|
+
start), for links that set `?from=`.
|
|
2295
|
+
|
|
2296
|
+
## Chat
|
|
2297
|
+
|
|
2298
|
+
| Widget | What it is | Recipe and Slots |
|
|
2299
|
+
| --- | --- | --- |
|
|
2300
|
+
| `ChatMessage` | One message of a chat. `ChatMessage.view({ from, content, author?, avatar?, time?, status?, onRetry?, actions?, reactions?, pinActions?, streaming?, words? }, h)`, `from` being `user`, `assistant` or `system`. The user's sits at the end in a bubble, an answer as text at the start. `status` is `sending`, `sent` or `failed`, which draws a retry; `actions` are named buttons (`{ key, label, onClick, icon?, pressed?, disabled? }`) shown on hover and focus unless pinned. A streamed answer is the same message drawn again with more `content` and `streaming: true` (`aria-busy`); its body wraps with `text-wrap: wrap`, so no earlier word moves line. `ChatMessage.group({ items, continues?, style?, messageStyle? }, h)` draws a run, a sender's following messages continued. Markdown is the application's to render (`foldkit-richtext-markdown`'s `parse`, `foldkit-richtext-dom/view`'s `renderDocument`). | `layout`: `chat`, `thread`; `bubble`: `muted`, `accent`, `outline`, `ghost`; `content`: `text`, `markdown`. `Recipes.ChatMessageGroup` for the group. Slots `root`, `avatar`, `main`, `header`, `author`, `time`, `bubble`, `body`, `footer`, `status`, `retry`, `actions`, `action`, `reactions`, `reaction`, `reactionCount`. `ChatMessage.configure({ base, presets })` gives `{ view, group }`. |
|
|
2301
|
+
| `MessageScroller` | A conversation's log that follows the newest message while the reader is at the end. A small Model: `MessageScroller.init({ id, opens? })` (`end` by default, `start` for a transcript) holds only whether it follows and how many arrived unseen; the scroll position is the browser's, read by its `FollowEnd` Mount. Fold `MessageScroller.update` (or place `Bundles.MessageScroller.with({ id, opens? })`), and send `Message.Appended({ count })` when your update appends messages (not when it loads older ones, which it holds in place). `MessageScroller.view({ model, label, content, onMessage, words?, areaStyle?, areaMixins? }, h)` draws a named `role="log"` in a ScrollArea, with a jump button counting what arrived while away; give its parent a height. | No axis. Slots `root`, `log`, `jump`, `count`. |
|
|
2302
|
+
| `ThinkingIndicator` | An assistant at work: `ThinkingIndicator.view({ label?, detail?, active?, icon? }, h)` draws dots, a pulse or the view's icon beside words a band of light sweeps, and a detail line, in a polite status. Keep it drawn with `active: false` before work starts, so what it says when it starts is announced. Every movement holds under reduced motion. | `mark`: `dots`, `pulse`, `none`; `label`: `shimmer`, `plain`, `hidden`; `tone`: `muted`, `accent`. Slots `root`, `mark`, `dot`, `icon`, `label`, `detail`. |
|
|
2303
|
+
| `ThinkingSteps` | The trace of what an assistant did. `ThinkingSteps.view({ id, steps, open, onToggle, duration?, summary?, openSteps?, onToggleStep?, words?, trigger? }, h)`. Each step is `{ id, title, state, duration?, detail?, icon?, steps? }`, `state` being `pending`, `running`, `done`, `failed` or `skipped`, said in words too; `href` makes the title a link (such a step never toggles), `trailing` draws beside the row, outside its button. `trigger: 'none'` draws the steps as a plain list. `Bundles.ThinkingSteps.with({ openSteps?, multiple? })` keeps the open state, and `ThinkingSteps.controls(model, onMessage)` feeds the view. The button says the running step's title, or "Thought for 4s". Its openness is an `Option<boolean>`: none opens it while a step runs and shuts it once all are done, and the press sends the state the reader asked for. `openSteps` and `onToggleStep` make each step's detail collapsible. | `variant`: `plain`, `card`; `connector`: `line`, `none`. Slots `root`, `trigger`, `summary`, `chevron`, `panel`, `list`, `step`, `row`, `head`, `marker`, `title`, `link`, `state`, `duration`, `trailing`, `body`, `detail`. |
|
|
2304
|
+
| `Questionnaire` | An assistant's questions answered in the chat. A small Model: `Questionnaire.init({ id, questions, layout? })` with `Questionnaire.single`, `multiple` and `text` questions (`Question` is a Schema, so a tool's input decodes into it), folded with `Questionnaire.update`, which says what is missing and focuses it, and returns `OutMessage.Answered({ answers })` once every required question is answered; the form then gives way to a summary. `Questionnaire.view({ model, onMessage, title?, words?, style?, mixins?, radioGroup?, checkboxGroup?, input?, textarea?, button?, submitButton? }, h)`: the controls are the package's RadioGroup, CheckboxGroup, Input and Textarea, each taking its own style. | `variant`: `plain`, `card`; `actions`: `end`, `start`. Slots `root`, `title`, `progress`, `question`, `prompt`, `words`, `field`, `other`, `otherLabel`, `error`, `actions`, `summary`, `asked`, `answer`. |
|
|
2305
|
+
|
|
2306
|
+
### MessageScroller
|
|
2307
|
+
|
|
2308
|
+
The log follows the newest message while the reader is at the end and stops when they
|
|
2309
|
+
scroll up, or when an upward wheel or ArrowUp, PageUp or Home arrives before that
|
|
2310
|
+
scroll. A Ctrl wheel, a wheel over a nested element that can scroll up itself, and a
|
|
2311
|
+
key another handler prevented, with Ctrl, Meta or Alt down, or typed into an input,
|
|
2312
|
+
textarea, select or editable element, do not count. A shorter viewport stays at the
|
|
2313
|
+
end while following. The messages and the text of a streamed answer are the
|
|
2314
|
+
application's.
|
|
2315
|
+
|
|
2316
|
+
## Mechanisms shared by many widgets
|
|
2317
|
+
|
|
2318
|
+
Each of these is described here once; the catalog rows link to it.
|
|
2319
|
+
|
|
2320
|
+
### Application key routes
|
|
2321
|
+
|
|
2322
|
+
A widget's own keys are `Behaviors.Keys` routes on one keydown owner, and the widgets
|
|
2323
|
+
below take a `routes` option for keys the application answers itself (F2 renaming a
|
|
2324
|
+
tab, Ctrl+A choosing every option, ArrowDown opening results). A route is built with
|
|
2325
|
+
`Keys.route(name, { on: [Keys.chord('ArrowDown')], handle })` from
|
|
2326
|
+
`foldkit-mixins`' `Behaviors`: `handle` receives the press (`key`, `modifiers`, the
|
|
2327
|
+
widget's `input` and, for a repeated slot, `item`) and returns an `Option` of a Message,
|
|
2328
|
+
or of `Keys.focus(id, message)` to move focus as well; `Option.none()` declines the
|
|
2329
|
+
press.
|
|
2330
|
+
|
|
2331
|
+
A route on a gesture another route on the same owner already takes throws
|
|
2332
|
+
`mixins:key-conflict`, naming both. `Keys.first(a, b)` is the way to let two routes
|
|
2333
|
+
declare one chord: `a` is asked first, and `b` only when `a` does not take the press or
|
|
2334
|
+
declines it.
|
|
2335
|
+
|
|
2336
|
+
| Widget | Keys the application's routes sit beside | The route's `input` |
|
|
2337
|
+
| --- | --- | --- |
|
|
2338
|
+
| `Command` | The field's: arrows, PageUp/PageDown, Enter; Home and End are the caret's. | `CommandKeyInput`: the query, the highlighted row and the rows the keys step through (`CommandRoute`). |
|
|
2339
|
+
| `SearchField` | Escape, which acts only on a field with text. | The field's text. |
|
|
2340
|
+
| `Menubar` | The arrows, Home and End. | Not read. |
|
|
2341
|
+
| `CascadeSelect` | On the open panel: the arrows, Home, End, Enter, Escape and every printable character (Space included, which still chooses). The closed trigger's keys are not open to routes. | `undefined` |
|
|
2342
|
+
| `Tour` | The arrows and, unless `closeOnEscape` is false, Escape. | `undefined` |
|
|
2343
|
+
| `FloatingPanel` | Escape (unless `closeOnEscape` is false); the arrows on the drag trigger and the corner are the panel's own, and a press they handled still reaches the panel. | `undefined` |
|
|
2344
|
+
| `Picker` | On a Sheet option: the arrows, Home and End (`item.index` is its place). The dropdown's keys are the Listbox's. | `undefined` |
|
|
2345
|
+
| `Nav` | `routes`: the row's own keys on the top-level links and triggers; `panelRoutes`: a panel's links. | `routes`: the entry, `item.index` its place; `panelRoutes`: the link, `item.index` its place among the panel's links. |
|
|
2346
|
+
| `Tabs` | `TabsContext.routes`: Delete, when tabs are closable. A tab with no key to answer draws no keydown at all. | The tab's `TabInfo`. |
|
|
2347
|
+
| `TagsInput` | The input's: Enter, the delimiter and Backspace. | The tags Model. |
|
|
2348
|
+
| `FileUpload` | The input's: Enter and Space (the dialog's, never routed) and Backspace and Delete (the last file). `FileUpload.conflict(routes)` names a clash. | The `FileUpload.Model`. |
|
|
2349
|
+
| `Toolbar` | The arrows, Home and End. | `undefined` |
|
|
2350
|
+
|
|
2351
|
+
```ts
|
|
2352
|
+
// ArrowDown asks the first route; when there is no text to search for it declines, and
|
|
2353
|
+
// the second moves focus into the results list and sends the same Message.
|
|
2354
|
+
const toResults: SearchField.Route<Search> = Keys.route('Focus results', {
|
|
2355
|
+
on: [Keys.chord('ArrowDown')],
|
|
2356
|
+
handle: () => Option.some(Keys.focus('results', Search.OpenedResults())),
|
|
899
2357
|
})
|
|
2358
|
+
|
|
2359
|
+
const searchWithFocus = (text: string, h: HtmlBuilder<Search>) =>
|
|
2360
|
+
SearchField.view(
|
|
2361
|
+
{
|
|
2362
|
+
id: 'find',
|
|
2363
|
+
label: 'Search products',
|
|
2364
|
+
value: text,
|
|
2365
|
+
onInput: text => Search.Typed({ text }),
|
|
2366
|
+
clear: { onClear: Search.Cleared() },
|
|
2367
|
+
routes: [Keys.first(openResults, toResults)],
|
|
2368
|
+
},
|
|
2369
|
+
h,
|
|
2370
|
+
)
|
|
2371
|
+
```
|
|
2372
|
+
|
|
2373
|
+
#### Checking routes without drawing
|
|
2374
|
+
|
|
2375
|
+
Each of these widgets exports `conflict(routes, input?)`: the `mixins:key-conflict` that
|
|
2376
|
+
drawing it with `routes` would throw, as an `Option` of the diagnostic, for a screen
|
|
2377
|
+
where a user rebinds keys and the candidate set must be judged before anything is drawn.
|
|
2378
|
+
It asks `Keys.conflict` of the widget's own routes and `routes` together, the own routes
|
|
2379
|
+
being the list the view itself draws, so it names the same two routes the view would,
|
|
2380
|
+
and also reports two application routes on one gesture. It reads gestures only: no
|
|
2381
|
+
handler runs and nothing is drawn.
|
|
2382
|
+
|
|
2383
|
+
`input` is the part of the view's options that decides which keys the widget owns, with
|
|
2384
|
+
the view's defaults. A widget whose own keys never vary takes `routes` alone. One that
|
|
2385
|
+
draws nothing while closed (`Tour`, `FloatingPanel`, the `CascadeSelect` panel) is
|
|
2386
|
+
checked as open, since a route that clashes in any state is a clash.
|
|
2387
|
+
|
|
2388
|
+
| Widget | `input` |
|
|
2389
|
+
| --- | --- |
|
|
2390
|
+
| `Command`, `SearchField`, `CascadeSelect`, `Picker` | none |
|
|
2391
|
+
| `Menubar` | `{ direction? }`: the same keys clash either way, and `'rtl'` changes which own route the diagnostic names. |
|
|
2392
|
+
| `Tour`, `FloatingPanel` | `{ closeOnEscape? }`: Escape is the widget's only while it is not `false`. |
|
|
2393
|
+
| `Toolbar` | `{ orientation? }`, default `'horizontal'`: the arrows along it. |
|
|
2394
|
+
| `Tabs` | `{ close? }`: Delete is the tabs' own key only when they are closable. |
|
|
2395
|
+
| `TagsInput` | `{ delimiter?, direction? }`: the Model's delimiter, default `,`, and which arrow enters the chips. |
|
|
2396
|
+
| `Nav` | `{ panelRoutes? }`: `routes` is checked against the row's keys, then `panelRoutes` against a panel's links'. |
|
|
2397
|
+
|
|
2398
|
+
```ts
|
|
2399
|
+
// Escape is the field's own key, so this candidate is refused with the diagnostic that
|
|
2400
|
+
// drawing the field with it would throw; a free key gives `Option.none()`.
|
|
2401
|
+
const candidate: SearchField.Route<Search> = Keys.route('Open results', {
|
|
2402
|
+
on: [Keys.chord('Escape')],
|
|
2403
|
+
handle: () => Option.some(Search.OpenedResults()),
|
|
2404
|
+
})
|
|
2405
|
+
const refusal = Option.map(SearchField.conflict([candidate]), diagnostic => diagnostic.message)
|
|
2406
|
+
```
|
|
2407
|
+
|
|
2408
|
+
### Focus after removal
|
|
2409
|
+
|
|
2410
|
+
When the element that held focus leaves the page, the browser drops focus to `body`.
|
|
2411
|
+
Three mechanisms keep it, all opt-in because none sends a Message, which a Scene test
|
|
2412
|
+
of every page drawing the widget would otherwise have to resolve.
|
|
2413
|
+
|
|
2414
|
+
- **A neighbour takes it** (`FocusRecovery`, from `foldkit-primitives/interaction`).
|
|
2415
|
+
`FocusRecovery.behavior(Slots)({ owner, parts, parent? })` on the slot that holds
|
|
2416
|
+
the repeated items (the `owner`) marks each `parts` slot and names where focus goes
|
|
2417
|
+
when that part is removed, hidden, made `inert` or `disabled`: steps tried in order
|
|
2418
|
+
(`same`, `next`, `previous`, `parent`, `stop`, `{ part }`, `owner`) until one can take
|
|
2419
|
+
it, and focus that was moved elsewhere is never taken. The widgets that draw a
|
|
2420
|
+
removable control take the part's name: `recoveryPart` on `Alert` and `Card` marks
|
|
2421
|
+
their dismiss button, and `Toast.keepFocus` is such a behavior on the
|
|
2422
|
+
toast container: from a dismissed toast's close button focus goes to the close
|
|
2423
|
+
button of the toast behind it, else the one in front, and from an action to a
|
|
2424
|
+
neighbour's action, else a close button; with no toast left, focus is not moved.
|
|
2425
|
+
Without `recoveryPart`, dismissing one drops focus to the page.
|
|
2426
|
+
- **The opener gets it back** (`focusReturn`). `Dialog.focusReturn`,
|
|
2427
|
+
`Tour.focusReturn` and `FloatingPanel.focusReturn` (a Sheet takes the Dialog's) give
|
|
2428
|
+
focus back to what had it before the widget opened, by `FocusReturn`'s rules when
|
|
2429
|
+
that is gone: an element with the opener's id, its `FocusRecovery` fallback steps,
|
|
2430
|
+
the dialog below, then the page's first tabbable element. The Tour and the
|
|
2431
|
+
FloatingPanel keep no opener of their own; upstream's Dialog return goes to the
|
|
2432
|
+
opener and, with none, to `body`.
|
|
2433
|
+
- **A control takes it** (`keepFocus`, a Command). `Drawer.keepFocus` moves focus to
|
|
2434
|
+
the handle when the drawer closes with focus in its body, which the hidden body would
|
|
2435
|
+
otherwise drop to the page. `SearchField.Focus` and `FileInput.Focus` put focus back
|
|
2436
|
+
on the input after the button that held it left, and `TagsInput.update` returns a
|
|
2437
|
+
focus Command after a removal. `FileUpload.update` does the same: the next entry's remove
|
|
2438
|
+
button, else the previous, else the input, and after a retry the entry's remove button;
|
|
2439
|
+
`FileUploadSort.keepFocus` (opt-in, in `mixins`) covers what no widget Message causes.
|
|
2440
|
+
|
|
2441
|
+
```ts
|
|
2442
|
+
import { Alert } from 'foldkit-mixins-ui'
|
|
2443
|
+
import { FocusRecovery } from 'foldkit-primitives/interaction'
|
|
2444
|
+
import { SlotView } from 'foldkit-mixins'
|
|
2445
|
+
|
|
2446
|
+
const AlertListSlots = Slots.define({ list: Container, item: Container })
|
|
2447
|
+
const Dismissal = defineMessageUnion({ Dismissed: { name: Schema.String } })
|
|
2448
|
+
type Dismissal = typeof Dismissal.Type
|
|
2449
|
+
|
|
2450
|
+
// Dismissing an alert hands its focus to the next one, else the previous one.
|
|
2451
|
+
const alertList = (names: ReadonlyArray<string>, h: HtmlBuilder<Dismissal>) => {
|
|
2452
|
+
const builders = SlotView.buildersFor(
|
|
2453
|
+
AlertListSlots,
|
|
2454
|
+
[
|
|
2455
|
+
FocusRecovery.behavior(AlertListSlots)<undefined, Dismissal>({
|
|
2456
|
+
owner: 'list',
|
|
2457
|
+
parts: { item: ['next', 'previous'] },
|
|
2458
|
+
}).mixin,
|
|
2459
|
+
],
|
|
2460
|
+
{ input: undefined, h },
|
|
2461
|
+
)
|
|
2462
|
+
return h.div(
|
|
2463
|
+
builders.list.attrs(),
|
|
2464
|
+
names.map(name =>
|
|
2465
|
+
h.keyed('div')(
|
|
2466
|
+
name,
|
|
2467
|
+
[],
|
|
2468
|
+
[
|
|
2469
|
+
Alert.view(
|
|
2470
|
+
{
|
|
2471
|
+
layout: 'inline',
|
|
2472
|
+
title: name,
|
|
2473
|
+
onDismiss: Dismissal.Dismissed({ name }),
|
|
2474
|
+
recoveryPart: 'item',
|
|
2475
|
+
},
|
|
2476
|
+
h,
|
|
2477
|
+
),
|
|
2478
|
+
],
|
|
2479
|
+
),
|
|
2480
|
+
),
|
|
2481
|
+
)
|
|
2482
|
+
}
|
|
2483
|
+
```
|
|
2484
|
+
|
|
2485
|
+
### Form participation
|
|
2486
|
+
|
|
2487
|
+
Widgets that carry a value take `name` and put it where a form reads it, so a form that
|
|
2488
|
+
submits natively needs no hand-drawn input:
|
|
2489
|
+
|
|
2490
|
+
| Widget | What `name` submits |
|
|
2491
|
+
| --- | --- |
|
|
2492
|
+
| `Input`, `Textarea`, `PasswordInput` | The text. Input also takes the native `required`, `readOnly`, `autocomplete`, `inputMode` and `maxLength`; Textarea `required` and `autocomplete`; PasswordInput `required`. |
|
|
2493
|
+
| `NumberField` | The text the field shows. |
|
|
2494
|
+
| `OtpField` | The code. |
|
|
2495
|
+
| `Slider`, `AngleSlider` | The slider's value (a range submits both, low first); the angle's hidden input. |
|
|
2496
|
+
| `Rating` | The native radio's value (`name` defaults to `id`). |
|
|
2497
|
+
| `CheckboxGroup` | One hidden input per checked value, in the options' order. |
|
|
2498
|
+
| `Segmented` | One hidden input per chosen value, in the options' order. |
|
|
2499
|
+
| `TagsInput` | One hidden input per tag, not the draft. |
|
|
2500
|
+
| `CascadeSelect` | One hidden input per level of the chosen path, or one empty input. |
|
|
2501
|
+
| `DatePicker` | One hidden input per chosen day; a range's start then its end. |
|
|
2502
|
+
| `FileInput` | The files, through the native input that `FileInput.Sync` keeps equal to the list. |
|
|
2503
|
+
| `FileUpload` | The local files, through the native input that `Sync` keeps equal to the list; stored files are not in it. |
|
|
2504
|
+
| `Checkbox`, `Switch`, `RadioGroup`, `Listbox`, `Combobox` | Their `hiddenInput` Slots (`hiddenInputs` for the popups). |
|
|
2505
|
+
|
|
2506
|
+
A `disabled` Button is `aria-disabled`, not `disabled`, and still submits: refuse the
|
|
2507
|
+
submit in `update`.
|
|
2508
|
+
|
|
2509
|
+
What reaches server markup is data, not closures. A page that answers before its script
|
|
2510
|
+
runs (`foldkit-ssr`'s [resumable
|
|
2511
|
+
pages](https://github.com/doeixd/foldkit-plus/blob/main/packages/ssr/README.md#resumable-pages-answering-before-the-runtime-boots))
|
|
2512
|
+
cannot write a closure into the server's markup. There, give `onInput` the `OnInput`
|
|
2513
|
+
attribute the resumable builder makes from a Message member; the view adds it as it
|
|
2514
|
+
would the closure, and `KeepTyped` keeps what is typed before the script runs:
|
|
2515
|
+
|
|
2516
|
+
```ts
|
|
2517
|
+
import { Resume } from 'foldkit-ssr/client'
|
|
2518
|
+
|
|
2519
|
+
const resumableEmail = (value: string, h: HtmlBuilder<Message>) => {
|
|
2520
|
+
const rh = Resume.builder(h)
|
|
2521
|
+
return Input.view(
|
|
2522
|
+
{
|
|
2523
|
+
id: 'email',
|
|
2524
|
+
value,
|
|
2525
|
+
onInput: rh.OnInput(Message.TypedEmail),
|
|
2526
|
+
type: 'email',
|
|
2527
|
+
draw: ({ input, label }) =>
|
|
2528
|
+
rh.div([], [rh.label(label, ['Email']), rh.input([...input, rh.KeepTyped()])]),
|
|
2529
|
+
},
|
|
2530
|
+
rh,
|
|
2531
|
+
)
|
|
2532
|
+
}
|
|
900
2533
|
```
|
|
901
2534
|
|
|
902
|
-
`
|
|
903
|
-
|
|
2535
|
+
`PasswordInput` draws its own input, so `KeepTyped` goes in its `attributes`, which adds
|
|
2536
|
+
to a Slot before the mixins resolve. Give it only while the field is enabled: a disabled
|
|
2537
|
+
field sends nothing, and the server refuses a kept field with nothing to replay
|
|
2538
|
+
(`UnkeepableField`).
|
|
904
2539
|
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
2540
|
+
```ts
|
|
2541
|
+
import { PasswordInput } from 'foldkit-mixins-ui'
|
|
2542
|
+
|
|
2543
|
+
const resumablePassword = (password: string, shown: boolean, h: HtmlBuilder<Message>) => {
|
|
2544
|
+
const rh = Resume.builder(h)
|
|
2545
|
+
return PasswordInput.view(
|
|
2546
|
+
{
|
|
2547
|
+
id: 'password',
|
|
2548
|
+
label: 'Password',
|
|
2549
|
+
value: password,
|
|
2550
|
+
onInput: rh.OnInput(Message.TypedPassword),
|
|
2551
|
+
visible: shown,
|
|
2552
|
+
onToggle: Message.ToggledPassword(),
|
|
2553
|
+
attributes: { input: [rh.KeepTyped()] },
|
|
2554
|
+
},
|
|
2555
|
+
rh,
|
|
2556
|
+
)
|
|
2557
|
+
}
|
|
2558
|
+
```
|
|
2559
|
+
|
|
2560
|
+
### Right to left
|
|
2561
|
+
|
|
2562
|
+
Logical properties carry most of the recipes, and a few things follow the direction
|
|
2563
|
+
explicitly:
|
|
2564
|
+
|
|
2565
|
+
- **A `direction` view option.** Menu, Menubar, Nav, TreeView, Resizable, Segmented,
|
|
2566
|
+
Toolbar, TagsInput, CascadeSelect, FloatingPanel, Tour, Sidebar and a horizontal
|
|
2567
|
+
Listbox take `direction?: 'ltr' | 'rtl'` (a Toast stack takes it in `init`). Under
|
|
2568
|
+
`'rtl'` the view swaps ArrowLeft and ArrowRight before building its Message, so
|
|
2569
|
+
Messages and `update` stay in reading order, and draws the direction as its root's
|
|
2570
|
+
`dir`, so the CSS (a submenu's side, a chevron) reads what the keys read. Unset, the
|
|
2571
|
+
keys read left to right and the page's `dir` stands.
|
|
2572
|
+
- **`readingKeys` for upstream's keys.** Tabs, RadioGroup and Calendar handle their
|
|
2573
|
+
arrows in upstream bundles no view option reaches, so `Tabs.readingKeys`,
|
|
2574
|
+
`RadioGroup.readingKeys` and `Calendar.readingKeys`, passed beside the style, are a
|
|
2575
|
+
Mount that reads each arrow by the element's own `:dir()` before upstream's handler
|
|
2576
|
+
sees it. They are opt-in for the reason `fluid` is (see [Fluid
|
|
2577
|
+
highlights](#fluid-highlights)). `RadioGroup.readingKeys` reads both arrow pairs
|
|
2578
|
+
whichever way the group stands (ArrowRight and ArrowDown go on, ArrowLeft and ArrowUp
|
|
2579
|
+
back; the horizontal pair swapped on a right-to-left page).
|
|
2580
|
+
- **Indicators.** `Segmented.fluid`, `Tabs.fluid` and `Nav.fluid` measure their
|
|
2581
|
+
indicator again when a `dir` anywhere in the document changes, since flipping it moves
|
|
2582
|
+
the items without resizing anything.
|
|
2583
|
+
|
|
2584
|
+
```ts
|
|
2585
|
+
Tabs.toView([TabsStyle.mixin, Tabs.readingKeys], { h }, ({ tablist, tabs }) =>
|
|
2586
|
+
h.div(tablist, tabs.map(tab => h.button(tab.tab, [tab.value]))),
|
|
2587
|
+
)
|
|
2588
|
+
```
|
|
911
2589
|
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
(`
|
|
2590
|
+
### Exits and reduced motion
|
|
2591
|
+
|
|
2592
|
+
A popup or dialog enters and leaves when drawn with `@foldkit/ui`'s `isAnimated`
|
|
2593
|
+
(`Menu.init(id, rows, { isAnimated: true })`, a Popover's `isAnimated`): a popup fades and
|
|
2594
|
+
grows on the fast tier, from the side its anchor placed it on, and a dialog on the slow
|
|
2595
|
+
one, each leaving on the quicker exit. A leaving Dialog is drawn `inert` with
|
|
2596
|
+
`isLeaving: Dialog.isLeaving(model)` in its context, and the Sheet does so itself; a
|
|
2597
|
+
Disclosure's `animatePanel` moves the panel's height, which the recipe scales by the
|
|
2598
|
+
`motion` knob. `Recipes.Dialog({ motion: 'none' })` (and the Sheet's) opens, closes and
|
|
2599
|
+
steps back at once.
|
|
2600
|
+
|
|
2601
|
+
Durations are the theme's: the `motion` knob multiplies them (`'0'` stills every recipe
|
|
2602
|
+
transition), and a duration of something that moves or resizes is also multiplied by
|
|
2603
|
+
`travel`, which reduced motion zeroes so that fades stay. A Marquee's viewport scrolls
|
|
2604
|
+
instead of moving under reduced motion, a ThinkingIndicator holds every movement, and a
|
|
2605
|
+
Carousel's `init` takes the application's reading of `prefers-reduced-motion` and starts
|
|
2606
|
+
an autoplaying carousel stopped.
|
|
2607
|
+
|
|
2608
|
+
### Fluid highlights
|
|
2609
|
+
|
|
2610
|
+
Tabs, Segmented, Nav, Sidebar, TreeView, Menu, Listbox and Combobox take a `fluid` mixin
|
|
2611
|
+
list beside the style that glides one highlight, or an indicator, to the item the
|
|
2612
|
+
pointer is near and back to the chosen one; a Table and a Card group take `fluid:
|
|
2613
|
+
Table.fluid` and `fluid: Card.fluid`, values passed the same way. A Mount does the measuring and moves it. It
|
|
2614
|
+
is off by default because a Scene test resolves every Mount with a Message and these
|
|
2615
|
+
send none, so a default would burden the tests of every page that drew one; the same
|
|
2616
|
+
reason makes `readingKeys`, `keepFocus`, `focusReturn`, `keepActiveInView` and the
|
|
2617
|
+
`overlayBars` opt-in mixins.
|
|
2618
|
+
|
|
2619
|
+
`Tabs.fluid` measures the chosen tab on the tablist (`Measure`) and moves one highlight
|
|
2620
|
+
to the tab nearest the pointer (`FluidHover`), born at the chosen tab and returning to it:
|
|
916
2621
|
|
|
917
2622
|
```ts
|
|
918
2623
|
Tabs.toView([TabsStyle.mixin, ...Tabs.fluid], { h }, ({ tablist, indicator, highlight, tabs }) =>
|
|
@@ -920,25 +2625,21 @@ Tabs.toView([TabsStyle.mixin, ...Tabs.fluid], { h }, ({ tablist, indicator, high
|
|
|
920
2625
|
)
|
|
921
2626
|
```
|
|
922
2627
|
|
|
923
|
-
The recipe draws the `line` variant's rule or the `pill` variant's pill on the
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
in
|
|
938
|
-
a listbox or combobox adds an `indicator` that glides to the chosen row. The
|
|
939
|
-
default draw places all three, and the rows drop their own hover and chosen
|
|
940
|
-
fill while the highlight runs. A press in a gap presses the lit row, except in
|
|
941
|
-
a combobox, whose field keeps focus.
|
|
2628
|
+
The recipe draws the `line` variant's rule or the `pill` variant's pill on the indicator,
|
|
2629
|
+
which springs to a new choice, and dims the pill while another tab is hovered. Until
|
|
2630
|
+
`Tabs.fluid` runs, as before a page hydrates, the indicator and highlight show nothing and
|
|
2631
|
+
the chosen tab marks itself: the recipe reads the `data-fluid-hover` attribute FluidHover
|
|
2632
|
+
sets while it runs.
|
|
2633
|
+
|
|
2634
|
+
Menus, listboxes and comboboxes draw their panels in the palette's `popup` tokens, so a
|
|
2635
|
+
theme's `menu: { accent, color }` (a bold accent row; a panel on the page's surface by default, or inverted or translucent)
|
|
2636
|
+
restyles all three, and they take `Menu.fluid`, `Listbox.fluid` and `Combobox.fluid`
|
|
2637
|
+
beside the style in `toView`. The open panel's rows sit in a `rows` box of this package's
|
|
2638
|
+
(the panel carries upstream's anchor, and an element holds one Mount), with a `highlight`
|
|
2639
|
+
first in it that follows the pointer, and the keys, which mark a row `data-active`; a
|
|
2640
|
+
listbox or combobox adds an `indicator` that glides to the chosen row. The default draw
|
|
2641
|
+
places all three, and the rows drop their own hover and chosen fill while the highlight
|
|
2642
|
+
runs. A press in a gap presses the lit row, except in a combobox, whose field keeps focus.
|
|
942
2643
|
|
|
943
2644
|
```ts
|
|
944
2645
|
Menu.toView([MenuStyle.mixin, ...Menu.fluid], { h })
|
|
@@ -946,26 +2647,22 @@ Menu.toView([MenuStyle.mixin, ...Menu.fluid], { h })
|
|
|
946
2647
|
|
|
947
2648
|
### Overlay scroll bars
|
|
948
2649
|
|
|
949
|
-
The scrolling recipes share one overlay bar, after Fluid Functionalism's: a
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
961
|
-
|
|
962
|
-
`
|
|
963
|
-
|
|
964
|
-
`
|
|
965
|
-
draws that `scroll` region only when given `itemsScrollClassName` or
|
|
966
|
-
`itemsScrollAttributes`, and its class joins the recipe's. Like `fluid`, it is off by default: a Scene test
|
|
967
|
-
resolves every Mount with a Message, and this one sends none, so a default
|
|
968
|
-
would burden the tests of every page that drew one.
|
|
2650
|
+
The scrolling recipes share one overlay bar, after Fluid Functionalism's: a 10px bar over
|
|
2651
|
+
the scroller's edge holding a thumb that rests 4px wide in a faint ink of the text, 2px
|
|
2652
|
+
off the edge, widens to 6px under the pointer and darkens while dragged. It fades in on
|
|
2653
|
+
`motion.moderate` while the box scrolls or the pointer moves over it, and out on
|
|
2654
|
+
`moderate-exit` once both rest, after a `moderate` delay that lets a widened thumb narrow
|
|
2655
|
+
first. The widening travels, so reduced motion keeps the fades alone. `ScrollBars` from
|
|
2656
|
+
`foldkit-primitives/dom` drives it and sends no Message; the bar is how it looks, the
|
|
2657
|
+
Mount only where the box is scrolled. On a coarse pointer the Mount does nothing, and the
|
|
2658
|
+
browser's bar, with its physics, stays; before it runs, as before a page hydrates, so does
|
|
2659
|
+
the browser's bar.
|
|
2660
|
+
|
|
2661
|
+
Every one is the same shape, a mixin list passed beside the style: `ScrollArea.overlayBars`,
|
|
2662
|
+
`Command.overlayBars`, `Dialog.overlayBars` and `VirtualList.overlayBars` in the view's
|
|
2663
|
+
`mixins`, and `Menu.overlayBars`, `Listbox.overlayBars` and `Combobox.overlayBars` in
|
|
2664
|
+
`toView`'s for a popup whose list scrolls: upstream draws that `scroll` region only when
|
|
2665
|
+
given `itemsScrollClassName` or `itemsScrollAttributes`, and its class joins the recipe's.
|
|
969
2666
|
|
|
970
2667
|
```ts
|
|
971
2668
|
ScrollArea.view(
|
|
@@ -979,216 +2676,634 @@ ScrollArea.view(
|
|
|
979
2676
|
Listbox.toView([ListboxStyle.mixin, ...Listbox.fluid, ...Listbox.overlayBars], { h })
|
|
980
2677
|
```
|
|
981
2678
|
|
|
982
|
-
The bar is a Slot of each component's own (`bar` and `thumb`; a popup's
|
|
983
|
-
`
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
`
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
The
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
|
-
|
|
2679
|
+
The bar is a Slot of each component's own (`bar` and `thumb`; a popup's `scrollBar` and
|
|
2680
|
+
`scrollThumb`), beside the scroller rather than inside it, so the scroller's edge fade
|
|
2681
|
+
does not erase it. ScrollArea, Command and VirtualList always draw it, and a popup
|
|
2682
|
+
whenever its panel has a `scroll`; the recipe leaves it undrawn until `ScrollBars` marks
|
|
2683
|
+
it scrollable. A ScrollArea also marks an edge with more past it with a hairline
|
|
2684
|
+
(`Utilities.scrollDivider` on `root`, `Utilities.scrollTimeline` on `viewport`), drawn
|
|
2685
|
+
where the browser lets a parent read a child's scroll timeline (`timeline-scope`).
|
|
2686
|
+
|
|
2687
|
+
### The top layer
|
|
2688
|
+
|
|
2689
|
+
The panels of Menu (submenus included), Menubar, Listbox and Combobox that stay where they
|
|
2690
|
+
are drawn (an anchor's `portal: false`) draw in the browser's top layer, so no stacking
|
|
2691
|
+
context or ancestor `overflow` reaches them. Such a panel carries `popover="manual"`, and
|
|
2692
|
+
its anchor Mount is wrapped in `Anchor.topLayer`, which shows the panel as a popover around
|
|
2693
|
+
the Mount's own acquire and hides it once the Mount releases; the wrapper keeps the Mount's
|
|
2694
|
+
name, args and Messages, so a Scene test still resolves it, and the node stays where the
|
|
2695
|
+
runtime drew it. Light dismiss stays the application's Messages.
|
|
2696
|
+
|
|
2697
|
+
- The panel sets `inset: auto`: the anchor writes only `left` and `top`, and the browser's
|
|
2698
|
+
`inset: 0` would otherwise leave `right: 0` winning right to left.
|
|
2699
|
+
- An unstyled panel keeps the browser's popover border, padding and `Canvas` fill. Every
|
|
2700
|
+
recipe's panel replaces them; an inline reset would beat the recipes.
|
|
2701
|
+
- `Anchor.topLayer` does nothing where the popover API or the element's `popover`
|
|
2702
|
+
attribute is missing (jsdom, a server render, a panel drawn without it), and the anchor
|
|
2703
|
+
places the panel in the page.
|
|
2704
|
+
- A panel that upstream portals keeps upstream's behavior, since moving a shown popover
|
|
2705
|
+
hides it again.
|
|
2706
|
+
|
|
2707
|
+
Popover, Tooltip and Hover Card are drawn by upstream views whose Mounts this package cannot
|
|
2708
|
+
wrap, so their panels go in the top layer another way: `Anchor.layer(h)`, the `layer` slot of
|
|
2709
|
+
`PopoverSlots` and `TooltipSlots`, is an element drawn around the panel that shows itself as a
|
|
2710
|
+
popover, and the panel inside keeps upstream's anchor (`Popover.anchor()` and
|
|
2711
|
+
`Tooltip.anchor()` give `portal: false` and the placement: 12px and 8px off the trigger, 8px
|
|
2712
|
+
inside the viewport, flipping and shifting). A Hover Card's panel is anchored in the top layer
|
|
2713
|
+
by `HoverIntent.toView(mixins, { h, anchored: { id, anchor? } }, draw)`, which gives the
|
|
2714
|
+
trigger `HoverIntent.triggerId(id)`. The DatePicker's panel and modal dialogs are not in the
|
|
2715
|
+
top layer.
|
|
2716
|
+
|
|
2717
|
+
A box of your own whose Mount is not `TopLayer` takes `Anchor.layerBox(h, style?)`: the same
|
|
2718
|
+
box without the Mount, for a Mount wrapped in `Anchor.topLayer` that sends Messages (Cascade
|
|
2719
|
+
Select's and Tour's do), so a Scene test can resolve it. Its inline style takes `style` too,
|
|
2720
|
+
since a second `h.Style` on the element would replace the first.
|
|
2721
|
+
|
|
2722
|
+
The popups' recipes take a `width` axis. `trigger` sets the panel's minimum width to its
|
|
2723
|
+
trigger's (`--button-width`, which upstream's anchor publishes once it has placed the panel),
|
|
2724
|
+
in place of the panel's 14rem minimum, so a narrow trigger gets a panel as narrow; `auto`
|
|
2725
|
+
keeps the 14rem. Combobox defaults to `trigger`, Listbox to `auto`.
|
|
2726
|
+
|
|
2727
|
+
### Accessibility patterns
|
|
2728
|
+
|
|
2729
|
+
Every adapter has an `A11y.pattern` beside its Slots, under `Patterns`: the slots a widget of
|
|
2730
|
+
that kind must publish and what each must expose. The catalog lists them with a `tier`
|
|
2731
|
+
(`stateful` for a Submodel, `stateless` for a decorated native control), the ARIA `roles`
|
|
2732
|
+
involved, and the platform `floor`: what the widget relies on the browser for (`focus-trap`,
|
|
2733
|
+
`escape-dismiss`, `top-layer`, `form-submission`, ...), so nothing here reimplements it and a
|
|
2734
|
+
reader or an agent can ask.
|
|
1011
2735
|
|
|
1012
2736
|
```ts
|
|
1013
|
-
|
|
2737
|
+
import { A11y } from 'foldkit-mixins'
|
|
2738
|
+
import { Patterns } from 'foldkit-mixins-ui'
|
|
2739
|
+
|
|
2740
|
+
A11y.validate(Patterns.Tabs, MyTabsSlots) // [] when a custom tabs view publishes what tabs need
|
|
2741
|
+
Patterns.catalog.find(entry => entry.name === 'dialog')?.floor // ['focus-trap', 'escape-dismiss', ...]
|
|
2742
|
+
```
|
|
2743
|
+
|
|
2744
|
+
A test iterates the catalog and validates each adapter's own Slots and `support` against its
|
|
2745
|
+
pattern, so an adapter cannot drift from the contract it claims. The patterns are written
|
|
2746
|
+
separately from the Slots, which is what makes the check mean something.
|
|
2747
|
+
|
|
2748
|
+
Where a pattern names obligations (who navigates, who makes an item reachable, who activates
|
|
2749
|
+
it, who names it), the entry's `support` lists who provides each: Mixins that contribute
|
|
2750
|
+
nothing, made with `A11y.base` (the widget's own markup or the upstream bundle it draws, named
|
|
2751
|
+
by source file) or `A11y.native` (what a native element does by itself). An adapter draws
|
|
2752
|
+
through `resolveFor`, so it has no view for `A11y.check` to read; the gate attaches `support`
|
|
2753
|
+
to a view over the adapter's Slots and `check` judges it, so an obligation nobody provides is
|
|
2754
|
+
a failure, and so is a provider nothing needs. These are claims found in source, not a
|
|
2755
|
+
rendered check; the rendered check is `Conformance` from `foldkit-mixins/testing`. Pagination,
|
|
2756
|
+
breadcrumb, table, scroll area, drawer, hover intent, picker, button group, window list, card,
|
|
2757
|
+
search field, toolbar and file input are in the catalog beside the older widgets, and a
|
|
2758
|
+
published `*Slots` that is neither in the catalog nor on the gate's list of Slots with nothing
|
|
2759
|
+
to require fails the gate. None of this is a WCAG claim.
|
|
2760
|
+
|
|
2761
|
+
### Touch targets and icons
|
|
2762
|
+
|
|
2763
|
+
`Touch` and `Icons` are style mechanisms, not components: no slots, no views. Compose them into
|
|
2764
|
+
your own slots. The recipes' own controls already stand 44px tall where the pointer is coarse:
|
|
2765
|
+
`Defaults.reset` sets `--fk-touch-floor` there, and a control's height on the size ladder is at
|
|
2766
|
+
least that (a region that must stay dense sets it to `0px`). For your own slots, `Touch.target`
|
|
2767
|
+
floors one control at 44px where the pointer is coarse; `Touch.targets` floors every boxed
|
|
2768
|
+
control a region draws. `Icons.glyph(size)` draws the icon in `--icon` before the element's
|
|
2769
|
+
words, and `Icons.byAttribute(attribute, icons)` sets `--icon` from an attribute's value, where
|
|
2770
|
+
`icons` maps each value to its resolved `url(…)`:
|
|
2771
|
+
|
|
2772
|
+
```ts
|
|
2773
|
+
const TileStyle = Style.forSlots(TileSlots)(
|
|
1014
2774
|
{
|
|
1015
|
-
|
|
1016
|
-
|
|
2775
|
+
tile: Style.compose(
|
|
2776
|
+
Touch.target,
|
|
2777
|
+
Icons.glyph('1rem'),
|
|
2778
|
+
Icons.byAttribute('data-block', { Hero: iconUrl('hero') }),
|
|
2779
|
+
),
|
|
1017
2780
|
},
|
|
1018
|
-
{ layer:
|
|
2781
|
+
{ layer: Layers.standard.layer('app') },
|
|
1019
2782
|
)
|
|
1020
2783
|
```
|
|
1021
2784
|
|
|
1022
|
-
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
`
|
|
2785
|
+
The icons the components draw themselves (a search field's magnifier, a toast's mark, a locked
|
|
2786
|
+
cell's padlock) are the theme's `icon` tokens: Heroicons' outline set (MIT), restroked to 2px,
|
|
2787
|
+
by default. An application's own pack replaces them as its own tokens: `AppStyle.make({ theme,
|
|
2788
|
+
tokens: Icons.tokens(pack, { width?, corners? }) })`, where `pack` holds an `IconData` for each
|
|
2789
|
+
name the components draw (`ChromeIcon` from `foldkit-mixins/theme`; one missing is a type
|
|
2790
|
+
error), and the stroke is redrawn into each mask, which CSS cannot reach once it is a `url()`.
|
|
2791
|
+
|
|
2792
|
+
## Recipes
|
|
2793
|
+
|
|
2794
|
+
The adapters only name slots. `Recipes` gives those slots, and the views above, a look:
|
|
2795
|
+
one `Style.recipeFor` per contract, built on the tokens of `foldkit-mixins/theme`. Select
|
|
2796
|
+
variants (an axis's values are listed in the catalog rows), hand the pieces to
|
|
2797
|
+
`Style.forSlots`, and attach the result like any other Style:
|
|
1027
2798
|
|
|
1028
2799
|
```ts
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
2800
|
+
import { Layers, Style } from 'foldkit-mixins'
|
|
2801
|
+
import { Theme } from 'foldkit-mixins/theme'
|
|
2802
|
+
import { ButtonSlots, Recipes } from 'foldkit-mixins-ui'
|
|
2803
|
+
|
|
2804
|
+
const DeleteStyle = Style.forSlots(ButtonSlots)(
|
|
2805
|
+
Recipes.Button({ tone: 'danger', variant: 'outline', size: 'sm' }),
|
|
2806
|
+
)
|
|
2807
|
+
|
|
2808
|
+
const L = Layers.standard
|
|
2809
|
+
const theme = Theme.make({ accent: { hue: 280, chroma: 0.15, lightness: 60 } })
|
|
2810
|
+
|
|
2811
|
+
export const sheet = Style.stylesheet(
|
|
2812
|
+
L.declare,
|
|
2813
|
+
L.in('theme', Theme.root(Theme.standard(theme))),
|
|
2814
|
+
DeleteStyle,
|
|
1041
2815
|
)
|
|
1042
|
-
// in update: modifyFields(model, { marks: () => Segmented.toggled(model.marks, mark, { multiple: true }) })
|
|
1043
2816
|
```
|
|
1044
2817
|
|
|
1045
|
-
|
|
2818
|
+
`DeleteStyle.mixin` then goes to `Button.toView` as in the first example. What a recipe
|
|
2819
|
+
assumes and does:
|
|
1046
2820
|
|
|
1047
|
-
The
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
|
-
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
|
|
1054
|
-
the node stays where the runtime drew it. Light dismiss stays the
|
|
1055
|
-
application's Messages.
|
|
1056
|
-
|
|
1057
|
-
- The panel sets `inset: auto`: the anchor writes only `left` and `top`, and
|
|
1058
|
-
the browser's `inset: 0` would otherwise leave `right: 0` winning right to
|
|
1059
|
-
left.
|
|
1060
|
-
- An unstyled panel keeps the browser's popover border, padding and
|
|
1061
|
-
`Canvas` fill. Every recipe's panel replaces them; an inline reset would
|
|
1062
|
-
beat the recipes.
|
|
1063
|
-
- `Anchor.topLayer` does nothing where the popover API or the element's
|
|
1064
|
-
`popover` attribute is missing (jsdom, a server render, a panel drawn
|
|
1065
|
-
without it), and the anchor places the panel in the page.
|
|
1066
|
-
- A panel that upstream portals keeps upstream's behavior, since moving a
|
|
1067
|
-
shown popover hides it again.
|
|
2821
|
+
- **The page ships the tokens.** Every value is a `var(--fk-…)` reference to the shipped
|
|
2822
|
+
tokens (`Theme.standard`), so another theme's knobs restyle every recipe with no new
|
|
2823
|
+
CSS.
|
|
2824
|
+
- **Bases sit in `components`, variants in `variants`** of `Layers.standard`, so an
|
|
2825
|
+
application's `app` layer overrides both without specificity fights. Every declaration
|
|
2826
|
+
is a layered rule and none is inline style, since inline style beats every layer and
|
|
2827
|
+
could not be overridden this way:
|
|
1068
2828
|
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
the
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
`Anchor
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
2829
|
+
```ts
|
|
2830
|
+
const Red = Style.forSlots(ButtonSlots)(
|
|
2831
|
+
{ button: Style.self({ background: 'red' }) },
|
|
2832
|
+
{ layer: L.layer('app') },
|
|
2833
|
+
)
|
|
2834
|
+
// Style.stylesheet(L.declare, …, DeleteStyle, Red): Red's background wins.
|
|
2835
|
+
```
|
|
2836
|
+
- **Controls stand on one size ladder.** A button, a field, a select, a tab, a segmented
|
|
2837
|
+
control, a table row and the rows of a menu, listbox or combobox are all one rung tall:
|
|
2838
|
+
36px by default and 28px compact, their padding, gap and text stepping with them
|
|
2839
|
+
(`Theme.ladder`, read on the element). `--fk-knob-step: 1` on any element makes
|
|
2840
|
+
everything inside it compact, the popups it opens included when they stay in the page (an
|
|
2841
|
+
anchor's `portal: false`, as the gallery's do); a panel upstream portals out of the page
|
|
2842
|
+
(the default of its own anchor) is given the region's custom properties as it leaves, so
|
|
2843
|
+
the region reaches it too, unless the panel sets the property itself. That holds for
|
|
2844
|
+
Menu, Listbox, Combobox and the `Anchor` Mount; a Popover or Tooltip with `portal: true`
|
|
2845
|
+
is not supported (draw it in place, as `anchor()` does). A recipe's `size` (`sm` compact,
|
|
2846
|
+
`md` default, `lg` a half step up at 40px) sets the step on its own element and beats the
|
|
2847
|
+
region, and a popup's sets it on its panel too, so it holds portaled or not; unset, which
|
|
2848
|
+
is the default, follows the region. An icon, checkbox, radio or switch with no size stands
|
|
2849
|
+
on the ladder's icon rung, 16px or 14px compact.
|
|
2850
|
+
- **Text comes in roles.** `Theme.role(name)` is a size and its leading, stepping with the
|
|
2851
|
+
ladder: `display`, `title`, `subtitle`, `body` (a control's text, 14px on 20), `caption`
|
|
2852
|
+
(badges, tooltips, a table's headings) and `micro` (keycaps). A tab's and a segmented
|
|
2853
|
+
option's label is trimmed to its capitals (`text-box`), centering it optically; a pressed
|
|
2854
|
+
segmented option and a chosen card title turn semibold without moving anything (the card
|
|
2855
|
+
writes its title in `data-label`; give an option its text there,
|
|
2856
|
+
`h.DataAttribute('label', 'Week')`, and draw its words in the `label` Slot, which holds the
|
|
2857
|
+
trim: on the option itself, the hidden copy took the trim's lower half); and a field's text
|
|
2858
|
+
is 16px on a coarse pointer, so iOS Safari does not zoom the page into it.
|
|
2859
|
+
- **A state is a tint, not a surface.** An unfilled control's hover is a faint film of the
|
|
2860
|
+
state ink over whatever is under it, so it reads on a muted page, a colored band or an
|
|
2861
|
+
inverted panel; a press lays that film stronger (`state.press`, 1.75 of the hover's). The
|
|
2862
|
+
ink is the theme's `--fk-state-ink` (`state.ink`: the element's own text, or the accent's
|
|
2863
|
+
ink under `surface.hover: 'accent'`) unless a painted surface above names its paint in the
|
|
2864
|
+
local `--_fk-state-ink`: the accent and danger tones name their fill, a subtle alert band
|
|
2865
|
+
its ink and a bold one its fill, so a hover on blue is a deeper blue. The neutral and ink
|
|
2866
|
+
tones name the theme's ink back, so a neutral control on a band does not take the band's
|
|
2867
|
+
hue, and one `surface.hover` choice reaches every component. The neutral button is
|
|
2868
|
+
see-through (`state.tint`), and images carry a hairline inside their edge (`state.edge`). A
|
|
2869
|
+
popup's rows round concentrically inside its panel (`Theme.nested`), as a segmented option
|
|
2870
|
+
does inside its tray. A fluid highlight (Table's, Segmented's, pill Tabs', Nav's,
|
|
2871
|
+
TreeView's, a Card group's) lays that same film, so `surface.hover` and
|
|
2872
|
+
`surface.hoverStrength` move it with every other hover.
|
|
2873
|
+
- **A press gives.** Held, every button scales to 98% (the 2% multiplied by `travel`, so
|
|
2874
|
+
reduced motion holds its size). A solid or primary button's fill also deepens to its
|
|
2875
|
+
family's `active` and clears the 1px border of its own color that it stands in, so the fill
|
|
2876
|
+
draws in by 1px a side; an outline, ghost or icon button lays a deeper film of its tone's
|
|
2877
|
+
ink. A pressed toggle (`aria-pressed="true"`) rests on its tone's fill, a solid one on the
|
|
2878
|
+
`active` fill; hovered, a solid toggle keeps it and an unfilled one takes its tone's hover
|
|
2879
|
+
fill; held, it deepens to the `active` fill; and its text stays the fill's throughout. A
|
|
2880
|
+
hovered row, tab, menu item or accordion row darkens while the press is held, and a fluid
|
|
2881
|
+
highlight darkens with the item it lights (`FluidHover` marks the container
|
|
2882
|
+
`data-fluid-held`). Chosen rows next to each other in a multiple listbox or combobox merge
|
|
2883
|
+
into one block. A disabled control fades by `state.disabledOpacity` (half by default), so
|
|
2884
|
+
one page shows one fade.
|
|
2885
|
+
- **Raised surfaces nest.** Popups, popovers, date picker panels and toasts sit two levels
|
|
2886
|
+
above what holds them and dialogs four (`Theme.raise`), each painted for its level, so a
|
|
2887
|
+
popover in a dialog lands above the dialog: a step lighter in a dark scheme, the same flat
|
|
2888
|
+
surface with its own shadow in a light one.
|
|
2889
|
+
- **State comes from the component's own attributes.** Checked, selected and disabled looks
|
|
2890
|
+
read `aria-checked`, `aria-selected` and `aria-disabled`, which `@foldkit/ui` already
|
|
2891
|
+
writes; no `whenInput` is needed.
|
|
2892
|
+
- **Tone and variant are independent.** A tone sets a few private custom properties that
|
|
2893
|
+
`solid`, `outline` and `ghost` read — except `primary`, which is ink by definition, and
|
|
2894
|
+
`icon`, a square one rung of the size ladder on a side. A tone also carries the line an
|
|
2895
|
+
`outline` draws: the fill, or for `neutral`, whose fill is a quiet grey, the page's default
|
|
2896
|
+
line. A neutral Checkbox or Switch that is on is in the page's ink, not the neutral grey, so
|
|
2897
|
+
it stands out without a color.
|
|
2898
|
+
- **On a colored band, unfilled buttons take the band's color.** `outline` and `ghost` draw
|
|
2899
|
+
their text in the tone's ink, which reads on the page's surface and not on a band of the
|
|
2900
|
+
accent. A band sets `Style.vars({ '--fk-ink': 'currentColor' })`, beside `--fk-heading` for
|
|
2901
|
+
its headings, and their text is the band's.
|
|
2902
|
+
|
|
2903
|
+
Adjust a recipe with `extend` instead of forking it. Base pieces compose per slot, a
|
|
2904
|
+
variant's pieces compose over the shipped ones, and compounds append:
|
|
1093
2905
|
|
|
1094
|
-
|
|
2906
|
+
```ts
|
|
2907
|
+
const BrandButton = Recipes.Button.extend({
|
|
2908
|
+
base: { button: Style.class('brand-button') },
|
|
2909
|
+
variants: { size: { lg: { button: Style.class('brand-button-lg') } } },
|
|
2910
|
+
})
|
|
2911
|
+
```
|
|
1095
2912
|
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
|
-
Messages and `update` stay in reading order, and draws the direction as
|
|
1103
|
-
its root's `dir`, so the CSS (a submenu's side, a chevron) reads what the
|
|
1104
|
-
keys read. Unset, the keys read left to right and the page's `dir` stands.
|
|
1105
|
-
- **`readingKeys` for upstream's keys.** Tabs, RadioGroup and Calendar handle
|
|
1106
|
-
their arrows in upstream bundles no view option reaches, so
|
|
1107
|
-
`Tabs.readingKeys`, `RadioGroup.readingKeys` and `Calendar.readingKeys`,
|
|
1108
|
-
passed beside the style, are a Mount that reads each arrow by the
|
|
1109
|
-
element's own `:dir()` before upstream's handler sees it. They are opt-in
|
|
1110
|
-
for the reason `fluid` is: a Scene test must resolve every Mount with a
|
|
1111
|
-
Message, and these send none.
|
|
1112
|
-
- **Indicators.** `Segmented.fluid`, `Tabs.fluid` and `Nav.fluid` measure
|
|
1113
|
-
their indicator again when a `dir` anywhere in the document changes, since
|
|
1114
|
-
flipping it moves the items without resizing anything.
|
|
1115
|
-
|
|
1116
|
-
## Mechanisms
|
|
1117
|
-
|
|
1118
|
-
`Touch` and `Icons` are style mechanisms, not components: no slots, no views.
|
|
1119
|
-
Compose them into your own slots. The recipes' own controls already stand
|
|
1120
|
-
44px tall where the pointer is coarse: `Defaults.reset` sets
|
|
1121
|
-
`--fk-touch-floor` there, and a control's height on the size ladder is at
|
|
1122
|
-
least that (a region that must stay dense sets it to `0px`). For your own
|
|
1123
|
-
slots, `Touch.target` floors one control at 44px where the pointer is coarse;
|
|
1124
|
-
`Touch.targets` floors every boxed control a region draws. `Icons.glyph(size)` draws the icon in `--icon` before the
|
|
1125
|
-
element's words, and `Icons.byAttribute(attribute, icons)` sets `--icon` from
|
|
1126
|
-
an attribute's value, where `icons` maps each value to its resolved `url(…)`:
|
|
2913
|
+
`Recipes.Badge` is a recipe of two axes, `appearance` and `size`. The tone is not an axis: the view
|
|
2914
|
+
writes it as `data-tone`, so one style serves badges of every tone, and the six names of the tone
|
|
2915
|
+
vocabulary are in the recipe. A badge toned by an attribute the application already writes maps its
|
|
2916
|
+
values with `Recipes.badgeTones` through `extend`; a value the map leaves out keeps the base pill.
|
|
2917
|
+
`Recipes.Badge.add` gives it a size or an appearance of your own. A toned pill is grounded on its
|
|
2918
|
+
tone's `subtle`, which keeps the tone's hue over a tinted page:
|
|
1127
2919
|
|
|
1128
2920
|
```ts
|
|
1129
|
-
const
|
|
1130
|
-
{
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
},
|
|
1137
|
-
{ layer: L.layer('app') },
|
|
1138
|
-
)
|
|
2921
|
+
const EntryStyle = Style.forSlots(EntrySlots)({
|
|
2922
|
+
badge: Recipes.Badge.extend({
|
|
2923
|
+
base: {
|
|
2924
|
+
badge: Recipes.badgeTones('data-state', { Published: 'success', Changed: 'warning' }),
|
|
2925
|
+
},
|
|
2926
|
+
})().badge,
|
|
2927
|
+
})
|
|
1139
2928
|
```
|
|
1140
2929
|
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
|
|
1144
|
-
|
|
1145
|
-
`
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
`
|
|
1150
|
-
|
|
1151
|
-
## Accessibility patterns
|
|
1152
|
-
|
|
1153
|
-
Every adapter has an `A11y.pattern` beside its Slots, under `Patterns`: the
|
|
1154
|
-
slots a widget of that kind must publish and what each must expose. The
|
|
1155
|
-
catalog lists them with a `tier` (`stateful` for a Submodel, `stateless` for
|
|
1156
|
-
a decorated native control), the ARIA `roles` involved, and the platform
|
|
1157
|
-
`floor`: what the widget relies on the browser for (`focus-trap`,
|
|
1158
|
-
`escape-dismiss`, `top-layer`, `form-submission`, ...), so nothing here
|
|
1159
|
-
reimplements it and a reader or an agent can ask.
|
|
2930
|
+
`Badge.view({ text, icon, onDismiss })` draws an icon before the text and a dismiss button named by
|
|
2931
|
+
`words.dismiss` (`'Dismiss {text}'`); `{ text, href, external }` draws the pill as a link. A link
|
|
2932
|
+
holds no dismiss button, and the types refuse both.
|
|
2933
|
+
|
|
2934
|
+
`Recipes.InputGroup` draws a text field with a prefix or suffix, such as an address's `/`, as one
|
|
2935
|
+
box: `group` carries the border, its hover and the focus ring (while the control inside has
|
|
2936
|
+
focus), `affix` sits inside it, muted, and `control` makes the input inside borderless. They are
|
|
2937
|
+
pieces for your own group, affix and control slots, as `foldkit-mixins-form`'s field publishes
|
|
2938
|
+
them. `control` is in `variants`, so it wins over a `components` look on the same slot; over a
|
|
2939
|
+
look of your own in a later layer, say the same in that layer:
|
|
1160
2940
|
|
|
1161
2941
|
```ts
|
|
1162
|
-
|
|
1163
|
-
|
|
2942
|
+
const AddressStyle = Style.forSlots(FieldSlots)({
|
|
2943
|
+
group: Recipes.InputGroup.group,
|
|
2944
|
+
affix: Recipes.InputGroup.affix,
|
|
2945
|
+
text: Style.compose(Recipes.Input({}).input, Recipes.InputGroup.control),
|
|
2946
|
+
})
|
|
2947
|
+
```
|
|
1164
2948
|
|
|
1165
|
-
|
|
1166
|
-
|
|
2949
|
+
`Recipes.Calendar` styles `CalendarSlots` in every mode: days in seven columns, months and years
|
|
2950
|
+
in three, each button reading its state off the cell (`data-today`, `data-selected`,
|
|
2951
|
+
`data-focused`, `data-outside-month`, `data-disabled`). Each cell is a rung of the size ladder,
|
|
2952
|
+
so `size` (`sm`, `md`) or the region steps it. It draws no card, so the same style serves a
|
|
2953
|
+
calendar on the page and one in a date picker's panel. `Recipes.Tabs({ variant: 'pill' })`'s
|
|
2954
|
+
chosen tab is a raised surface with a hairline edge and shadow on the tray, in the default text
|
|
2955
|
+
colour. To look at every recipe in every variant and state at once, in both schemes, write the
|
|
2956
|
+
specimen page: `pnpm --filter foldkit-mixins-ui specimen <out.html> [hue]`.
|
|
2957
|
+
|
|
2958
|
+
## One factory for each part
|
|
2959
|
+
|
|
2960
|
+
A widget's look, state, drawing and features each have one place they are
|
|
2961
|
+
given ([Look, state, drawing, features](#look-state-drawing-features-one-factory-each)).
|
|
2962
|
+
This section shows each with code.
|
|
2963
|
+
|
|
2964
|
+
### State: fold it by hand, or place a Bundle
|
|
2965
|
+
|
|
2966
|
+
A stateful widget exports `Model`, `Message`, `init` and `update`. The
|
|
2967
|
+
application keeps the Model in a field of its own, wraps the widget's Messages
|
|
2968
|
+
in one of its own, and folds them. Written out, for a field of tags:
|
|
2969
|
+
|
|
2970
|
+
```ts standalone
|
|
2971
|
+
import { Schema } from 'effect'
|
|
2972
|
+
import * as Command from 'foldkit/command'
|
|
2973
|
+
import type { Html, HtmlBuilder } from 'foldkit/html'
|
|
2974
|
+
import { defineMessageUnion } from 'foldkit/message'
|
|
2975
|
+
import { modifyFields } from 'foldkit/struct'
|
|
2976
|
+
import type { Return } from 'foldkit/update'
|
|
2977
|
+
import { TagsInput } from 'foldkit-mixins-ui'
|
|
2978
|
+
|
|
2979
|
+
const Model = Schema.Struct({ labels: TagsInput.Model })
|
|
2980
|
+
type Model = typeof Model.Type
|
|
2981
|
+
|
|
2982
|
+
const Message = defineMessageUnion({ GotLabelsMessage: { message: TagsInput.Message } })
|
|
2983
|
+
type Message = typeof Message.Type
|
|
2984
|
+
|
|
2985
|
+
export const initial: Model = {
|
|
2986
|
+
labels: TagsInput.init({ id: 'labels', tags: ['urgent'], max: 3 }),
|
|
2987
|
+
}
|
|
2988
|
+
|
|
2989
|
+
export const update = (model: Model, message: Message): Return<Model, Message> =>
|
|
2990
|
+
Message.match(message, {
|
|
2991
|
+
GotLabelsMessage: ({ message }) => {
|
|
2992
|
+
const result = TagsInput.update(model.labels, message)
|
|
2993
|
+
// The field's own Commands (it refocuses after a removal) speak its Messages.
|
|
2994
|
+
const commands = Command.mapMessages(result.commands, message =>
|
|
2995
|
+
Message.GotLabelsMessage({ message }),
|
|
2996
|
+
)
|
|
2997
|
+
// Nothing changed: hand back the Model given, so nothing is drawn again.
|
|
2998
|
+
return result.model === model.labels
|
|
2999
|
+
? { model, commands }
|
|
3000
|
+
: { model: modifyFields(model, { labels: () => result.model }), commands }
|
|
3001
|
+
},
|
|
3002
|
+
})
|
|
3003
|
+
|
|
3004
|
+
export const view = (model: Model, h: HtmlBuilder<Message>): Html =>
|
|
3005
|
+
TagsInput.view(
|
|
3006
|
+
{
|
|
3007
|
+
model: model.labels,
|
|
3008
|
+
onMessage: message => Message.GotLabelsMessage({ message }),
|
|
3009
|
+
label: 'Labels, up to three',
|
|
3010
|
+
},
|
|
3011
|
+
h,
|
|
3012
|
+
)
|
|
1167
3013
|
```
|
|
1168
3014
|
|
|
1169
|
-
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
|
-
|
|
3015
|
+
That is the whole of it, and for a page with one or two widgets it is the
|
|
3016
|
+
smaller choice: it adds nothing to the bundle. `Bundles.X` is the same `init`
|
|
3017
|
+
and `update` packaged for
|
|
3018
|
+
[`foldkit-bundle`](https://github.com/doeixd/foldkit-plus/blob/main/packages/bundle/README.md),
|
|
3019
|
+
which derives the field, the wrapper Message and the fold above from one
|
|
3020
|
+
placement:
|
|
3021
|
+
|
|
3022
|
+
```ts standalone
|
|
3023
|
+
import type { Html, HtmlBuilder } from 'foldkit/html'
|
|
3024
|
+
import { Bundle } from 'foldkit-bundle'
|
|
3025
|
+
import { Bundles, TagsInput } from 'foldkit-mixins-ui'
|
|
3026
|
+
|
|
3027
|
+
const App = Bundle.compose({}).pipe(
|
|
3028
|
+
Bundle.withChild('labels', Bundles.TagsInput, {
|
|
3029
|
+
args: { id: 'labels', tags: ['urgent'], max: 3 },
|
|
3030
|
+
}),
|
|
3031
|
+
)
|
|
3032
|
+
type Model = typeof App.Model.Type
|
|
3033
|
+
type Message = typeof App.Message.Type
|
|
3034
|
+
|
|
3035
|
+
const view = (model: Model, h: HtmlBuilder<Message>): Html =>
|
|
3036
|
+
TagsInput.view(
|
|
3037
|
+
{
|
|
3038
|
+
model: model.labels,
|
|
3039
|
+
onMessage: message => App.Message.GotLabelsMessage({ message }),
|
|
3040
|
+
label: 'Labels, up to three',
|
|
3041
|
+
},
|
|
3042
|
+
h,
|
|
3043
|
+
)
|
|
3044
|
+
|
|
3045
|
+
export const config = App.placements.runtime({ Model: App.Model, initial: {}, view })
|
|
3046
|
+
```
|
|
3047
|
+
|
|
3048
|
+
The first placement costs a page about 6 kB (brotli) of `foldkit-bundle`; the
|
|
3049
|
+
second and every later one share it. `foldkit-bundle` is a peer dependency:
|
|
3050
|
+
install it when you place a Bundle, and a page that folds by hand never loads
|
|
3051
|
+
it.
|
|
3052
|
+
|
|
3053
|
+
- **A Bundle is headless.** It holds no view; draw the placed Model with the
|
|
3054
|
+
widget's `view`.
|
|
3055
|
+
- **Its `args` are `init`'s options**, checked by a Schema and given to
|
|
3056
|
+
`update` too.
|
|
3057
|
+
- **`Bundles` is a namespace of one file per widget**, as `Recipes` is, so
|
|
3058
|
+
reading `Bundles.TagsInput` keeps that file and no other Bundle.
|
|
3059
|
+
|
|
3060
|
+
Who owns the value follows from its type. Where the value's type is the
|
|
3061
|
+
widget's own (a TagsInput's tags), the Bundle holds it and the application
|
|
3062
|
+
reads it from the placed Model, `model.labels.tags`. Where the type is the
|
|
3063
|
+
application's (the items of a Combobox), the application keeps the value in
|
|
3064
|
+
its own field and the Bundle holds only the interaction: open or closed, the
|
|
3065
|
+
row the keys are on, the text typed. A `Choice` says how that field is read
|
|
3066
|
+
and folded, and the Bundle reports each change for the application to answer:
|
|
3067
|
+
|
|
3068
|
+
```ts standalone
|
|
3069
|
+
import { Schema } from 'effect'
|
|
3070
|
+
import { Bundle } from 'foldkit-bundle'
|
|
3071
|
+
import type { Html, HtmlBuilder } from 'foldkit/html'
|
|
3072
|
+
import { Bundles, Combobox } from 'foldkit-mixins-ui'
|
|
3073
|
+
|
|
3074
|
+
const cities = ['Lisbon', 'Porto', 'Faro'] as const
|
|
3075
|
+
const City = Combobox.one(cities)
|
|
3076
|
+
|
|
3077
|
+
const App = Bundle.compose({ city: Schema.Option(Schema.Literals(cities)) }).pipe(
|
|
3078
|
+
Bundle.withChild('cityBox', Bundles.Combobox, {
|
|
3079
|
+
args: { id: 'city' },
|
|
3080
|
+
// `out` is a `ChoiceChange`; `City.picked` looks the reported value up
|
|
3081
|
+
// among `cities`, so `city` stays an `Option` of one of them.
|
|
3082
|
+
onOut: out => model => ({ model: { ...model, city: City.picked(model.city, out) } }),
|
|
3083
|
+
}),
|
|
3084
|
+
)
|
|
3085
|
+
|
|
3086
|
+
export const initial = App.placements.initial({ city: City.empty })
|
|
3087
|
+
|
|
3088
|
+
// The same `Choice` reads the field for the drawing: the chosen row, the resting text.
|
|
3089
|
+
export const cityField = (model: typeof App.Model.Type, h: HtmlBuilder<typeof App.Message.Type>): Html =>
|
|
3090
|
+
Combobox.view(
|
|
3091
|
+
{
|
|
3092
|
+
model: model.cityBox,
|
|
3093
|
+
onMessage: message => App.Message.GotCityBoxMessage({ message }),
|
|
3094
|
+
label: 'City',
|
|
3095
|
+
choice: City,
|
|
3096
|
+
value: model.city,
|
|
3097
|
+
filter: Combobox.contains,
|
|
3098
|
+
clear: true,
|
|
3099
|
+
},
|
|
3100
|
+
h,
|
|
3101
|
+
)
|
|
3102
|
+
```
|
|
3103
|
+
|
|
3104
|
+
`Combobox.one(items)` holds an `Option` of an item, `Combobox.many(items)` a
|
|
3105
|
+
list of them in the order chosen (place the Bundle with `multiple: true`, which
|
|
3106
|
+
its `update` reads: choosing leaves the list open), and `Combobox.text(items)`
|
|
3107
|
+
the typed text itself, with the items as suggestions. Each is a file of its
|
|
3108
|
+
own. `Choice` is an interface you may implement; a rule of your own usually
|
|
3109
|
+
wraps a shipped one:
|
|
3110
|
+
|
|
3111
|
+
```ts standalone
|
|
3112
|
+
import { Combobox, type Choice } from 'foldkit-mixins-ui'
|
|
3113
|
+
|
|
3114
|
+
/** At most three: a fourth choice leaves the value as it was. */
|
|
3115
|
+
export const upToThree = <Item extends string>(
|
|
3116
|
+
items: ReadonlyArray<Item>,
|
|
3117
|
+
): Choice<Item, ReadonlyArray<Item>> => {
|
|
3118
|
+
const many = Combobox.many(items)
|
|
3119
|
+
return {
|
|
3120
|
+
...many,
|
|
3121
|
+
picked: (value, change) => {
|
|
3122
|
+
const next = many.picked(value, change)
|
|
3123
|
+
return next.length > 3 ? value : next
|
|
3124
|
+
},
|
|
3125
|
+
}
|
|
3126
|
+
}
|
|
3127
|
+
```
|
|
3128
|
+
|
|
3129
|
+
Where the value's type is the widget's own and a parent usually acts on a
|
|
3130
|
+
change, the Bundle reports it. A Calendar holds its `Selection` and reports
|
|
3131
|
+
`Changed`, which a placement answers or ignores by name:
|
|
3132
|
+
|
|
3133
|
+
```ts standalone
|
|
3134
|
+
import { Option } from 'effect'
|
|
3135
|
+
import { Bundle } from 'foldkit-bundle'
|
|
3136
|
+
import * as Dates from 'foldkit/calendar'
|
|
3137
|
+
import type { Html, HtmlBuilder } from 'foldkit/html'
|
|
3138
|
+
import { Bundles, Calendar } from 'foldkit-mixins-ui'
|
|
3139
|
+
|
|
3140
|
+
const today = Dates.make(2026, 2, 11)
|
|
3141
|
+
|
|
3142
|
+
const App = Bundle.compose({}).pipe(
|
|
3143
|
+
Bundle.withChild('trip', Bundles.Calendar, {
|
|
3144
|
+
// The selection's tag is the mode; `months: 2` draws two side by side.
|
|
3145
|
+
args: { id: 'trip', today, selection: Calendar.empty('Range'), months: 2, minDate: today },
|
|
3146
|
+
// `Changed` carries the new selection; this page only reads it from the Model.
|
|
3147
|
+
onOut: Bundle.ignore,
|
|
3148
|
+
}),
|
|
3149
|
+
)
|
|
3150
|
+
type Model = typeof App.Model.Type
|
|
3151
|
+
type Message = typeof App.Message.Type
|
|
3152
|
+
|
|
3153
|
+
export const nights = (model: Model): number =>
|
|
3154
|
+
Option.match(Calendar.rangeOf(model.trip.selection), {
|
|
3155
|
+
onNone: () => 0,
|
|
3156
|
+
onSome: ({ start, end }) => Dates.daysUntil(start, end),
|
|
3157
|
+
})
|
|
3158
|
+
|
|
3159
|
+
export const view = (model: Model, h: HtmlBuilder<Message>): Html =>
|
|
3160
|
+
Calendar.view(
|
|
3161
|
+
{
|
|
3162
|
+
model: model.trip,
|
|
3163
|
+
onMessage: message => App.Message.GotTripMessage({ message }),
|
|
3164
|
+
label: 'Trip dates',
|
|
3165
|
+
presets: [{ label: 'Next week', selection: Calendar.nextDays(today, 7) }],
|
|
3166
|
+
today: { label: 'This month' },
|
|
3167
|
+
footer: h.p([], [`${nights(model)} nights`]),
|
|
3168
|
+
},
|
|
3169
|
+
h,
|
|
3170
|
+
)
|
|
3171
|
+
```
|
|
3172
|
+
|
|
3173
|
+
`Combobox.view(options, h)` takes that `choice` and the `value`, and draws
|
|
3174
|
+
the rest from data:
|
|
3175
|
+
|
|
3176
|
+
- **Rows.** `option: item => RowContent` gives a row its `label` (which also
|
|
3177
|
+
names a chip and the resting text), `description`, `icon`, `trailing`,
|
|
3178
|
+
`content` in the label's place, and `disabled`; without it a row is its
|
|
3179
|
+
item. `items` narrows what is offered now (a fetched page); `filter` keeps
|
|
3180
|
+
the rows whose label matches the typed text, with `Combobox.contains` and
|
|
3181
|
+
`Combobox.startsWith` shipped as values, so a page that fetches for the
|
|
3182
|
+
text ships neither. `groupBy` and `heading` group adjacent rows.
|
|
3183
|
+
- **The field.** `placeholder`, `empty` (drawn in the list's place),
|
|
3184
|
+
`clear` (`true` for a button with a drawn cross, or `{ content }`),
|
|
3185
|
+
`chips` for a choice of several, `buttonContent`, `disabled`, `invalid`,
|
|
3186
|
+
`readOnly`, `name`, `openOnFocus`, `anchor`, and `words` (`clear`,
|
|
3187
|
+
`remove`, the second with `{label}`).
|
|
3188
|
+
- **Clearing** empties the field's text through the Combobox's own Message.
|
|
3189
|
+
The value follows through the `Choice`: `Combobox.text` takes the empty
|
|
3190
|
+
text, and a combobox placed with `nullable: true` reports
|
|
3191
|
+
`ClearedSelection` when an emptied field is left.
|
|
3192
|
+
- **A value chosen before the page drew** needs the Bundle's `text` arg (the
|
|
3193
|
+
chosen row's label), since upstream writes the resting text only as the
|
|
3194
|
+
field is left.
|
|
3195
|
+
- **`Combobox.configure({ base, presets })`** binds `filter`, `placeholder`,
|
|
3196
|
+
`chips`, `openOnFocus`, `anchor`, `words`, `style`, `mixins` and `clear:
|
|
3197
|
+
true`.
|
|
3198
|
+
- **`Combobox.fluid` and `Combobox.overlayBars`** are files of their own: a
|
|
3199
|
+
page that passes neither ships neither `FluidHover`, `Measure` nor
|
|
3200
|
+
`ScrollBars`.
|
|
3201
|
+
|
|
3202
|
+
The `toView` adapter and the `ComboboxView` bundles stay as the rung below.
|
|
3203
|
+
|
|
3204
|
+
`Listbox.view(options, h)` and `Picker.view(options, h)` take the same `choice` and
|
|
3205
|
+
`value` and the same `option`, `groupBy`, `heading`, `items`, `placeholder`,
|
|
3206
|
+
`disabled`, `invalid`, `name` and `words` (`clear`, the button's name), over
|
|
3207
|
+
`Bundles.Listbox` and `Bundles.Picker`: a Listbox's `Listbox.one(items)` or
|
|
3208
|
+
`Listbox.many(items)` (`multiple: true` in the Bundle's args, since choosing
|
|
3209
|
+
leaves a multiple list open), a Picker's `Picker.one(items)`. The value is the
|
|
3210
|
+
application's, so `clear` is `{ onClear, content? }`: the button sends the
|
|
3211
|
+
application's own Message, which empties the field through the same choice
|
|
3212
|
+
(`ChoiceChange.ClearedSelection()`). `Listbox.fluid` and `Listbox.overlayBars` are
|
|
3213
|
+
files of their own, like the Combobox's.
|
|
3214
|
+
|
|
3215
|
+
### Drawing: configure once, call with what differs
|
|
3216
|
+
|
|
3217
|
+
`X.configure({ base, presets })` returns the widget's own `view`, bound to
|
|
3218
|
+
options an application would otherwise repeat at every call: its compiled
|
|
3219
|
+
style, its words, its mixins, its structural choices.
|
|
3220
|
+
|
|
3221
|
+
```ts standalone
|
|
3222
|
+
import type { Html, HtmlBuilder } from 'foldkit/html'
|
|
3223
|
+
import { defineMessageUnion } from 'foldkit/message'
|
|
3224
|
+
import { Style } from 'foldkit-mixins'
|
|
3225
|
+
import { Button, ButtonSlots, Recipes } from 'foldkit-mixins-ui'
|
|
3226
|
+
|
|
3227
|
+
const Message = defineMessageUnion({ Saved: {}, Deleted: {} })
|
|
3228
|
+
type Message = typeof Message.Type
|
|
3229
|
+
|
|
3230
|
+
// Styles are compiled once, in a module the build may ship as data.
|
|
3231
|
+
const Quiet = Style.forSlots(ButtonSlots)(Recipes.Button({ tone: 'neutral', variant: 'outline' }))
|
|
3232
|
+
const Danger = Style.forSlots(ButtonSlots)(Recipes.Button({ tone: 'danger' }))
|
|
3233
|
+
|
|
3234
|
+
export const AppButton = Button.configure({
|
|
3235
|
+
base: { style: Quiet },
|
|
3236
|
+
presets: { danger: { style: Danger } },
|
|
3237
|
+
})
|
|
3238
|
+
|
|
3239
|
+
export const actions = (h: HtmlBuilder<Message>): ReadonlyArray<Html> => [
|
|
3240
|
+
AppButton.view({ label: 'Save', onClick: Message.Saved() }, h),
|
|
3241
|
+
AppButton.view({ label: 'Delete', preset: 'danger', onClick: Message.Deleted() }, h),
|
|
3242
|
+
]
|
|
3243
|
+
```
|
|
3244
|
+
|
|
3245
|
+
- **The order is `base`, the named preset, the call.** A later one wins per
|
|
3246
|
+
option, so a style given at the call replaces the preset's. Two options
|
|
3247
|
+
merge instead: `mixins` concatenate in that order, and `words` merge word
|
|
3248
|
+
by word. An option given as `undefined` is not given.
|
|
3249
|
+
- **The preset names are the keys you wrote.** `preset: 'dangr'` is a type
|
|
3250
|
+
error, and `preset` is no option at all where `presets` was left out. A
|
|
3251
|
+
name computed at run time that matches none throws, naming the ones
|
|
3252
|
+
declared.
|
|
3253
|
+
- **A preset holds what takes no Message and no state**: `style`, `mixins`,
|
|
3254
|
+
`words` and each widget's own list (`type` for a Button; `placeholder`,
|
|
3255
|
+
`addOnBlur` and `direction` for a TagsInput; `weekNumbers`, `caption`,
|
|
3256
|
+
`paging`, `today`, `presets` and `detail` for a Calendar; `filter`,
|
|
3257
|
+
`placeholder`, `chips`, `openOnFocus`, `anchor` and `clear: true` for a
|
|
3258
|
+
Combobox). `onClick`,
|
|
3259
|
+
`onMessage`, `model`, `label` and anything drawn (`icon`, `aside`, `footer`)
|
|
3260
|
+
stay at the call.
|
|
3261
|
+
- **A preset may hold behaviour.** A mixin with a Mount given in a preset
|
|
3262
|
+
attaches to every use of that preset, and the page ships that Behavior
|
|
3263
|
+
only because the application's own module imported it. A Mount that sends
|
|
3264
|
+
no Message has to be resolved by the application's Scene tests of every
|
|
3265
|
+
page that draws the preset.
|
|
3266
|
+
- **It holds no state.** A widget's starting values are `init`'s options, or
|
|
3267
|
+
a Bundle's `args`.
|
|
3268
|
+
|
|
3269
|
+
### Look: recipe modules hold style and nothing else
|
|
3270
|
+
|
|
3271
|
+
A shipped recipe module imports style code only: `foldkit-mixins` styles,
|
|
3272
|
+
theme references, other recipes' pieces, icon masks. It never imports a
|
|
3273
|
+
widget, a Behavior or anything with a Mount, which is what lets a build
|
|
3274
|
+
evaluate a style module and ship class names in its place
|
|
3275
|
+
([Style modules shipped as data](https://github.com/doeixd/foldkit-plus/blob/main/packages/mixins/README.md#style-modules-shipped-as-data)).
|
|
3276
|
+
An axis selects what CSS can express over the same markup. A choice that
|
|
3277
|
+
changes the markup is a view option, which the view writes as a `data-*`
|
|
3278
|
+
attribute for the recipe to read. A look a shipped recipe lacks is added to
|
|
3279
|
+
it, not forked from it:
|
|
3280
|
+
|
|
3281
|
+
```ts standalone
|
|
3282
|
+
import { Style } from 'foldkit-mixins'
|
|
3283
|
+
import { ButtonSlots, Recipes } from 'foldkit-mixins-ui'
|
|
3284
|
+
|
|
3285
|
+
const Buttons = Recipes.Button.add({
|
|
3286
|
+
tone: { brand: { button: Style.self({ background: 'rebeccapurple', color: 'white' }) } },
|
|
3287
|
+
})
|
|
3288
|
+
|
|
3289
|
+
export const Brand = Style.forSlots(ButtonSlots)(Buttons({ tone: 'brand', variant: 'solid' }))
|
|
3290
|
+
```
|
|
1173
3291
|
|
|
1174
3292
|
## Why some components needed a fork
|
|
1175
3293
|
|
|
1176
|
-
The bridge needs a **consumer-visible attribute bundle**. `Menu`, `Listbox`,
|
|
1177
|
-
`
|
|
1178
|
-
|
|
1179
|
-
|
|
1180
|
-
|
|
1181
|
-
|
|
1182
|
-
|
|
1183
|
-
|
|
1184
|
-
|
|
1185
|
-
|
|
1186
|
-
|
|
1187
|
-
|
|
1188
|
-
|
|
1189
|
-
on it: the page can style it only from the panel's Slot, with a rule under it
|
|
1190
|
-
keyed on the role and the state attributes upstream writes. Drawn through
|
|
1191
|
-
the fork, the row is the `item` Slot, styled like any other:
|
|
3294
|
+
The bridge needs a **consumer-visible attribute bundle**. `Menu`, `Listbox`, `ComboBox`,
|
|
3295
|
+
`DatePicker` and `Toast` build (parts of) their element tree internally and expose no
|
|
3296
|
+
`toView`-style seam, so there is nothing for Mixins to attach to: a limitation of the exposed
|
|
3297
|
+
render seam, not of Slot resolution. Each is transcribed from the pinned `@foldkit/ui` source
|
|
3298
|
+
(attributed in its module) with the missing `toView` added, and a parity battery draws the fork
|
|
3299
|
+
and upstream's view over the same models; state, Messages, update, Commands and Mounts stay
|
|
3300
|
+
upstream in every case. If upstream gains seams, the forks go away.
|
|
3301
|
+
|
|
3302
|
+
That seam is what makes a row styleable. Drawn through `@foldkit/ui`'s own view, a Menu item or
|
|
3303
|
+
a Listbox or Combobox option takes only a `className` (its `itemToConfig`), so no Slot's
|
|
3304
|
+
attributes reach it and no Mixin can land on it: the page can style it only from the panel's
|
|
3305
|
+
Slot, with a rule under it keyed on the role and the state attributes upstream writes. Drawn
|
|
3306
|
+
through the fork, the row is the `item` Slot, styled like any other:
|
|
1192
3307
|
|
|
1193
3308
|
```ts standalone
|
|
1194
3309
|
import { Capability, Slot, Slots, Style } from 'foldkit-mixins'
|
|
@@ -1209,19 +3324,16 @@ const PanelStyle = Style.forSlots(PanelSlots)({
|
|
|
1209
3324
|
})
|
|
1210
3325
|
```
|
|
1211
3326
|
|
|
1212
|
-
The second keeps the rule in the panel's layer and reads only what
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
`Listbox`, `Combobox` and `Calendar` draw the standard markup from the
|
|
1218
|
-
styled bundles when `toView` is given no `draw`; pass a `draw` to arrange the
|
|
1219
|
-
parts yourself.
|
|
3327
|
+
The second keeps the rule in the panel's layer and reads only what `@foldkit/ui` publishes
|
|
3328
|
+
(`role`, `data-active`, `data-selected`, `data-disabled`), but no Behavior or Mount can reach the
|
|
3329
|
+
row that way. Use it for a port that keeps upstream's view; draw through the adapter otherwise.
|
|
3330
|
+
`Listbox`, `Combobox` and `Calendar` draw the standard markup from the styled bundles when
|
|
3331
|
+
`toView` is given no `draw`; pass a `draw` to arrange the parts yourself.
|
|
1220
3332
|
|
|
1221
3333
|
**The Menu is three layers**, each built on the one before:
|
|
1222
3334
|
|
|
1223
3335
|
```text
|
|
1224
|
-
Menu.init / update / view the component:
|
|
3336
|
+
Menu.init / update / view the component: rows with values, submenus, a point
|
|
1225
3337
|
|
|
|
1226
3338
|
MenuSlots, Menu.resolve, the panel adapter: styles any @foldkit/ui Menu
|
|
1227
3339
|
Menu.toView, fluid, drawn through the fork, whoever keeps its Model
|
|
@@ -1231,72 +3343,49 @@ pointTarget
|
|
|
1231
3343
|
MenuView the fork: @foldkit/ui/menu's view with a toView
|
|
1232
3344
|
```
|
|
1233
3345
|
|
|
1234
|
-
`MenuView` is the fork; the Menu's Model, `update` and Mounts are upstream's.
|
|
1235
|
-
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1240
|
-
|
|
1241
|
-
|
|
1242
|
-
`
|
|
1243
|
-
|
|
1244
|
-
|
|
1245
|
-
`contextmenu`
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
1251
|
-
|
|
1252
|
-
|
|
1253
|
-
|
|
1254
|
-
`
|
|
1255
|
-
|
|
1256
|
-
|
|
1257
|
-
(`
|
|
1258
|
-
|
|
1259
|
-
|
|
1260
|
-
|
|
1261
|
-
|
|
1262
|
-
|
|
1263
|
-
transcription (`ComboboxView.create` / `ComboboxView.Multi.create`).
|
|
1264
|
-
|
|
1265
|
-
`DatePicker`'s bundles mix the popover's pre-bound groups with the date
|
|
1266
|
-
picker's own attributes, so they speak only the date picker's Message. Its
|
|
1267
|
-
`toView` therefore takes no builder of the application's:
|
|
1268
|
-
`DatePicker.toView(mixins, (resolved, h) => …)` hands `draw` the date
|
|
1269
|
-
picker's builder, and without a `draw` draws upstream's markup.
|
|
1270
|
-
|
|
1271
|
-
A DatePicker also picks a whole `Calendar.Selection`, a range or many days.
|
|
1272
|
-
Fold it with `DatePicker.update(selection)`, given the selection the
|
|
1273
|
-
application keeps: upstream closes the popover on every day picked, and this
|
|
1274
|
-
keeps it open while the day leaves the selection unfinished (a range's first
|
|
1275
|
-
end, any day of a Multiple selection), reporting `SelectedDate` either way for
|
|
1276
|
-
the application to fold through `Calendar.picked`. Draw it with
|
|
1277
|
-
`DatePickerView.view` taking `selection` and `triggerContent: selection =>
|
|
1278
|
-
Html` in place of upstream's `maybeSelectedDate` and `triggerContent`, and
|
|
1279
|
-
`toCalendarView: Calendar.toView(selection, mixins, { h })`. Under `name`,
|
|
1280
|
-
each chosen day is a hidden input of its own, in order (a range's start,
|
|
1281
|
-
then its end), so `FormData.getAll(name)` reads `[start, end]`; nothing chosen
|
|
1282
|
-
submits the name once, empty.
|
|
1283
|
-
|
|
1284
|
-
`DragAndDrop` and `Animation` do not have adapters here yet.
|
|
1285
|
-
|
|
1286
|
-
## Status
|
|
3346
|
+
`MenuView` is the fork; the Menu's Model, `update` and Mounts are upstream's. The panel adapter
|
|
3347
|
+
styles a Menu drawn through it: `Menu.toView(mixins, { h }, draw?)` is that Menu's `toView`, and
|
|
3348
|
+
without a `draw` draws the panel through `drawMenu` (`Menu.toView([MenuStyle.mixin], { h })` is a
|
|
3349
|
+
whole styled menu). Menubar draws its menus this way, and so does an application that folds
|
|
3350
|
+
`@foldkit/ui`'s Menu itself, for typed items or groups, which the component's rows do not have.
|
|
3351
|
+
Such a Menu opens at a point with `Menu.drawAtPoint(point, h)` as `toView`'s `draw` (its button
|
|
3352
|
+
becomes a mark of no size at `point`, an `Option`, which the anchor places the rows against, so
|
|
3353
|
+
give the anchor `gap: 0`) and `Menu.pointTarget({ onPress, onOpen }, h)` on the area: a right
|
|
3354
|
+
press sends `onPress` with its point, which the application keeps, and the `contextmenu` after it
|
|
3355
|
+
(or Shift+F10, or the ContextMenu key) sends `onOpen`, which the application answers with the
|
|
3356
|
+
Menu's own `Opened` Message, the browser's menu kept shut. A finger's press sends `onPress` too,
|
|
3357
|
+
so Android's `contextmenu` for a held finger opens under it; iOS fires none, which the
|
|
3358
|
+
component's `Menu.target` answers by opening on the hold itself. The component is this package's
|
|
3359
|
+
own, drawn through the adapter, as the Slider is; its `Menu.target` is `pointTarget` wired to its
|
|
3360
|
+
own Messages.
|
|
3361
|
+
|
|
3362
|
+
`ToastView` follows the fork's shape: `ToastView.make` binds upstream's `Toast.make` for the
|
|
3363
|
+
payload and swaps in the transcribed view. `Listbox` forks both variants over one shared
|
|
3364
|
+
transcription (`ListboxView.create` and `ListboxView.Multi.create` bind the upstream bundles; the
|
|
3365
|
+
single and multi Models are structurally identical, so the single adaptor maps
|
|
3366
|
+
`maybeSelectedValue` to `selectedValues` exactly as upstream's does). The forks add one view input
|
|
3367
|
+
upstream lacks, `direction?: 'ltr' | 'rtl'`: under `'rtl'` a horizontal listbox's ArrowLeft moves
|
|
3368
|
+
to the next item. `Combobox` follows the same shape over its own shared transcription
|
|
3369
|
+
(`ComboboxView.create` / `ComboboxView.Multi.create`). `DatePicker`'s bundles mix the popover's
|
|
3370
|
+
pre-bound groups with the date picker's own attributes, so they speak only the date picker's
|
|
3371
|
+
Message: its `toView` takes no builder of the application's, and without a `draw` draws upstream's
|
|
3372
|
+
markup. `DragAndDrop` and `Animation` do not have adapters here yet.
|
|
3373
|
+
|
|
3374
|
+
## Limits and status
|
|
1287
3375
|
|
|
1288
3376
|
The API is still settling in the `0.x` series. This package should stay small:
|
|
1289
3377
|
|
|
1290
3378
|
```text
|
|
1291
3379
|
component state / accessibility -> @foldkit/ui
|
|
1292
3380
|
merge semantics -> foldkit-mixins
|
|
1293
|
-
adapter metadata
|
|
3381
|
+
adapter metadata, widgets -> foldkit-mixins-ui
|
|
1294
3382
|
```
|
|
1295
3383
|
|
|
1296
|
-
The components that keep a Model here (Menu, Toast, Sheet and the rest) do
|
|
1297
|
-
|
|
1298
|
-
|
|
1299
|
-
the
|
|
3384
|
+
The components that keep a Model here (Menu, Toast, Sheet and the rest) do so where
|
|
3385
|
+
`@foldkit/ui` has no such component, or composes one beneath them (a Sheet is a Dialog, a Menubar
|
|
3386
|
+
a row of Menus); when upstream gains one, the adapter is the better home. The recipes assume the
|
|
3387
|
+
page ships the theme's tokens; a widget never reads a value out of a theme. Accessibility
|
|
3388
|
+
`support` entries are claims found in source, not a WCAG conformance statement.
|
|
1300
3389
|
|
|
1301
3390
|
## See also
|
|
1302
3391
|
|