@hina-ui/vue 1.0.0

package/src/components/tree-select/tree-select.variants.ts

@@ -0,0 +1,27 @@
+import { tv } from '../../lib/tv'
+
+export const treeSelectContent = tv({
+  base: [
+    'hn-anim-pop z-(--hn-z-overlay) flex w-[var(--reka-popover-trigger-width)] min-w-40 flex-col overflow-hidden shadow-md outline-none',
+  ],
+})
+
+export const treeSelectList = tv({
+  base: 'max-h-[min(20rem,var(--reka-popover-content-available-height))]',
+})
+
+export const treeSelectRow = tv({
+  base: [
+    'hn-interactive hn-state-layer hn-press-none relative isolate flex w-full cursor-pointer',
+    'items-center gap-1 rounded-md py-2 pe-2.5 text-start text-sm select-none',
+    'text-fg [&_svg]:size-4 [&_svg]:shrink-0',
+    'data-disabled:pointer-events-none data-disabled:opacity-50',
+  ],
+})
+
+export const treeSelectToggle = tv({
+  base: [
+    'text-muted flex size-5 shrink-0 cursor-pointer items-center justify-center rounded-sm',
+    '[&>span>svg]:size-3.5',
+  ],
+})

package/src/components/tree-select/types.ts

@@ -0,0 +1,34 @@
+export interface TreeSelectNode {
+  value: string | number
+  label: string
+  description?: string
+  disabled?: boolean
+  children?: TreeSelectNode[]
+}
+
+export function findNode(
+  nodes: TreeSelectNode[],
+  value: string | number | null | undefined,
+): TreeSelectNode | undefined {
+  for (const node of nodes) {
+    if (node.value === value) return node
+    const hit = node.children && findNode(node.children, value)
+    if (hit) return hit
+  }
+  return undefined
+}
+
+export function pathTo(
+  nodes: TreeSelectNode[],
+  value: string | number | null | undefined,
+  trail: Array<string | number> = [],
+): Array<string | number> | null {
+  for (const node of nodes) {
+    if (node.value === value) return trail
+    if (node.children) {
+      const hit = pathTo(node.children, value, [...trail, node.value])
+      if (hit) return hit
+    }
+  }
+  return null
+}

package/src/components/visually-hidden/VisuallyHidden.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+  import { VisuallyHidden as RekaVisuallyHidden } from 'reka-ui'
+
+  defineOptions({ name: 'HnVisuallyHidden' })
+</script>
+
+<template>
+  <RekaVisuallyHidden>
+    <slot />
+  </RekaVisuallyHidden>
+</template>

package/src/index.ts

@@ -0,0 +1,252 @@
+export { cn } from './lib/cn'
+export { tv } from './lib/tv'
+export type { VariantProps } from './lib/tv'
+
+export { EASE, DURATION, TRAVEL, STAGGER, TRANSITION, cssEase } from './motion'
+export type { Bezier, TransitionName } from './motion'
+
+export { provideUiLocale, useUiLocale, zhCN, enUS } from './locale'
+export type { UiMessages, PartialUiMessages } from './locale'
+
+export { REQUIRED_SINGLETONS } from './singletons'
+export type { RequiredSingleton } from './singletons'
+
+export { default as Button } from './components/button/Button.vue'
+export { default as IconButton } from './components/icon-button/IconButton.vue'
+export { default as CloseButton } from './components/close-button/CloseButton.vue'
+export { default as CopyButton } from './components/copy-button/CopyButton.vue'
+export { default as ButtonGroup } from './components/button-group/ButtonGroup.vue'
+export { default as Tag } from './components/tag/Tag.vue'
+export { default as Chip } from './components/chip/Chip.vue'
+export { default as Avatar } from './components/avatar/Avatar.vue'
+export { default as AvatarGroup } from './components/avatar/AvatarGroup.vue'
+export type { AvatarVariants } from './components/avatar/avatar.variants'
+export { default as Badge } from './components/badge/Badge.vue'
+export { default as Indicator } from './components/indicator/Indicator.vue'
+export { default as Callout } from './components/callout/Callout.vue'
+export { default as Alert } from './components/alert/Alert.vue'
+export { default as PrevNext } from './components/prev-next/PrevNext.vue'
+export { default as PrevNextLink } from './components/prev-next/PrevNextLink.vue'
+export { default as Table } from './components/table/Table.vue'
+export { default as TableHeader } from './components/table/TableHeader.vue'
+export { default as TableBody } from './components/table/TableBody.vue'
+export { default as TableRow } from './components/table/TableRow.vue'
+export { default as TableHead } from './components/table/TableHead.vue'
+export { default as TableCell } from './components/table/TableCell.vue'
+export { default as Tabs } from './components/tabs/Tabs.vue'
+export { default as TabsList } from './components/tabs/TabsList.vue'
+export { default as TabsTrigger } from './components/tabs/TabsTrigger.vue'
+export { default as TabsContent } from './components/tabs/TabsContent.vue'
+export type { ButtonVariants } from './components/button/button.variants'
+export { default as Ripple } from './components/ripple/Ripple.vue'
+export { default as Input } from './components/input/Input.vue'
+export type { InputVariants } from './components/input/input.variants'
+export { default as Textarea } from './components/textarea/Textarea.vue'
+export type { TextareaVariants } from './components/textarea/textarea.variants'
+export { default as NumberInput } from './components/number-input/NumberInput.vue'
+export { default as PasswordInput } from './components/password-input/PasswordInput.vue'
+export { default as SearchInput } from './components/search-input/SearchInput.vue'
+export { default as InputGroup } from './components/input-group/InputGroup.vue'
+export { default as InputGroupAddon } from './components/input-group/InputGroupAddon.vue'
+export { default as Select } from './components/select/Select.vue'
+export type { SelectOption, SelectOptionGroup, SelectItems } from './components/select/types'
+export { default as MultiSelect } from './components/multi-select/MultiSelect.vue'
+export { default as Combobox } from './components/combobox/Combobox.vue'
+export { default as CommandPalette } from './components/command-palette/CommandPalette.vue'
+export type { CommandItem, CommandGroup, CommandItems } from './components/command-palette/types'
+export { default as Listbox } from './components/listbox/Listbox.vue'
+export type { ListboxVariants } from './components/listbox/listbox.variants'
+export { default as TreeSelect } from './components/tree-select/TreeSelect.vue'
+export type { TreeSelectNode } from './components/tree-select/types'
+export { default as Checkbox } from './components/checkbox/Checkbox.vue'
+export type { CheckboxVariants } from './components/checkbox/checkbox.variants'
+export { default as CheckboxGroup } from './components/checkbox-group/CheckboxGroup.vue'
+export type { CheckboxGroupVariants } from './components/checkbox-group/checkbox-group.variants'
+export { default as RadioGroup } from './components/radio-group/RadioGroup.vue'
+export { default as Switch } from './components/switch/Switch.vue'
+export type { SwitchVariants } from './components/switch/switch.variants'
+export { default as Slider } from './components/slider/Slider.vue'
+export type { SliderVariants } from './components/slider/slider.variants'
+export { default as RangeSlider } from './components/range-slider/RangeSlider.vue'
+export { default as Toggle } from './components/toggle/Toggle.vue'
+export type { ToggleVariants } from './components/toggle/toggle.variants'
+export { default as TagsInput } from './components/tags-input/TagsInput.vue'
+export { default as MultiCombobox } from './components/multi-combobox/MultiCombobox.vue'
+export { default as Calendar } from './components/calendar/Calendar.vue'
+export type { CalendarVariants } from './components/calendar/calendar.variants'
+export { default as DateField } from './components/date-field/DateField.vue'
+export { default as DatePicker } from './components/date-picker/DatePicker.vue'
+export { default as DateRangeField } from './components/date-range-field/DateRangeField.vue'
+export { default as DateRangePicker } from './components/date-range-picker/DateRangePicker.vue'
+export { default as DateTimePicker } from './components/date-time-picker/DateTimePicker.vue'
+export { default as RangeCalendar } from './components/range-calendar/RangeCalendar.vue'
+export { default as Rating } from './components/rating/Rating.vue'
+export { default as FileUpload } from './components/file-upload/FileUpload.vue'
+export { default as AlertDialog } from './components/alert-dialog/AlertDialog.vue'
+export { default as Popconfirm } from './components/popconfirm/Popconfirm.vue'
+export { default as HoverCard } from './components/hover-card/HoverCard.vue'
+export { default as ContextMenu } from './components/context-menu/ContextMenu.vue'
+export { default as ContextMenuItem } from './components/context-menu/ContextMenuItem.vue'
+export { default as ContextMenuCheckboxItem } from './components/context-menu/ContextMenuCheckboxItem.vue'
+export { default as ContextMenuGroup } from './components/context-menu/ContextMenuGroup.vue'
+export { default as ContextMenuSub } from './components/context-menu/ContextMenuSub.vue'
+export { default as ContextMenuLabel } from './components/context-menu/ContextMenuLabel.vue'
+export { default as ContextMenuSeparator } from './components/context-menu/ContextMenuSeparator.vue'
+export { default as ContextMenuRadioGroup } from './components/context-menu/ContextMenuRadioGroup.vue'
+export { default as ContextMenuRadioItem } from './components/context-menu/ContextMenuRadioItem.vue'
+export { default as Sheet } from './components/sheet/Sheet.vue'
+export { default as LoadingOverlay } from './components/loading-overlay/LoadingOverlay.vue'
+export { default as Panel } from './components/panel/Panel.vue'
+export { default as Progress } from './components/progress/Progress.vue'
+export { default as RingProgress } from './components/ring-progress/RingProgress.vue'
+export { default as MeterGroup } from './components/meter-group/MeterGroup.vue'
+export { default as Empty } from './components/empty/Empty.vue'
+export { default as Result } from './components/result/Result.vue'
+export { default as Statistic } from './components/statistic/Statistic.vue'
+export { default as Banner } from './components/banner/Banner.vue'
+export type { BannerNotice, BannerTone } from './components/banner/types'
+export type { MeterItem, MeterTone } from './components/meter-group/types'
+export { default as Menubar } from './components/menubar/Menubar.vue'
+export { default as MenubarMenu } from './components/menubar/MenubarMenu.vue'
+export { default as MenubarItem } from './components/menubar/MenubarItem.vue'
+export { default as MenubarCheckboxItem } from './components/menubar/MenubarCheckboxItem.vue'
+export { default as MenubarGroup } from './components/menubar/MenubarGroup.vue'
+export { default as MenubarSub } from './components/menubar/MenubarSub.vue'
+export { default as MenubarLabel } from './components/menubar/MenubarLabel.vue'
+export { default as MenubarSeparator } from './components/menubar/MenubarSeparator.vue'
+export { default as MenubarRadioGroup } from './components/menubar/MenubarRadioGroup.vue'
+export { default as MenubarRadioItem } from './components/menubar/MenubarRadioItem.vue'
+export { default as Form } from './components/form/Form.vue'
+export { default as FormField } from './components/form-field/FormField.vue'
+export { default as FormLayout } from './components/form-layout/FormLayout.vue'
+export type { FormLayoutVariants } from './components/form-layout/form-layout.variants'
+export type { FormValidateOn } from './components/form/composables/useForm'
+export type {
+  FormErrors,
+  FormRules,
+  FormValidator,
+  FormValues,
+  StandardSchema,
+} from './components/form/standard-schema'
+export type { FileUploadReason, FileUploadRejection } from './components/file-upload/utils/select'
+export type { RatingVariants } from './components/rating/rating.variants'
+export { default as TimeField } from './components/time-field/TimeField.vue'
+export type { DateGranularity, DateRangeValue, TimeGranularity } from './lib/date'
+export { default as PinInput } from './components/pin-input/PinInput.vue'
+export type { PinInputVariants } from './components/pin-input/pin-input.variants'
+export { default as SegmentedControl } from './components/segmented-control/SegmentedControl.vue'
+export type {
+  SegmentedControlVariants,
+  SegmentedItemVariants,
+} from './components/segmented-control/segmented-control.variants'
+export { default as Card } from './components/card/Card.vue'
+export type { CardVariants } from './components/card/card.variants'
+export { default as VisuallyHidden } from './components/visually-hidden/VisuallyHidden.vue'
+export { default as Text } from './components/text/Text.vue'
+export type { TextVariants } from './components/text/text.variants'
+export { default as Heading } from './components/heading/Heading.vue'
+export type { HeadingVariants } from './components/heading/heading.variants'
+export { default as Prose } from './components/prose/Prose.vue'
+export { default as Link } from './components/link/Link.vue'
+export { default as Code } from './components/code/Code.vue'
+export { default as Kbd } from './components/kbd/Kbd.vue'
+export { default as Blockquote } from './components/blockquote/Blockquote.vue'
+export { default as Mark } from './components/mark/Mark.vue'
+export { default as CodeBlock } from './components/code-block/CodeBlock.vue'
+export { tokenize, tokensToHtml } from './components/code-block/highlighter'
+export { default as List } from './components/list/List.vue'
+export { default as ListItem } from './components/list/ListItem.vue'
+export { default as DescriptionList } from './components/description-list/DescriptionList.vue'
+export { default as DescriptionTerm } from './components/description-list/DescriptionTerm.vue'
+export { default as DescriptionDetails } from './components/description-list/DescriptionDetails.vue'
+export { default as Time } from './components/time/Time.vue'
+export { default as NumberFormat } from './components/number-format/NumberFormat.vue'
+export { default as Stack } from './components/stack/Stack.vue'
+export type { StackVariants } from './components/stack/stack.variants'
+export { default as Inline } from './components/inline/Inline.vue'
+export type { InlineVariants } from './components/inline/inline.variants'
+export { default as Flex } from './components/flex/Flex.vue'
+export type { FlexVariants } from './components/flex/flex.variants'
+export { default as Grid } from './components/grid/Grid.vue'
+export type { GridVariants } from './components/grid/grid.variants'
+export { default as SimpleGrid } from './components/simple-grid/SimpleGrid.vue'
+export type { SimpleGridVariants } from './components/simple-grid/simple-grid.variants'
+export { default as Container } from './components/container/Container.vue'
+export type { ContainerVariants } from './components/container/container.variants'
+export { default as Center } from './components/center/Center.vue'
+export { default as Space } from './components/space/Space.vue'
+export { default as AspectRatio } from './components/aspect-ratio/AspectRatio.vue'
+export { default as Divider } from './components/divider/Divider.vue'
+export { default as Splitter } from './components/splitter/Splitter.vue'
+export { default as SplitterPanel } from './components/splitter/SplitterPanel.vue'
+export { default as SplitterHandle } from './components/splitter/SplitterHandle.vue'
+export { default as Collapsible } from './components/collapsible/Collapsible.vue'
+export { default as CollapsibleTrigger } from './components/collapsible/CollapsibleTrigger.vue'
+export { default as DisclosureIcon } from './components/disclosure-icon/DisclosureIcon.vue'
+export { default as CollapsibleContent } from './components/collapsible/CollapsibleContent.vue'
+export { default as Accordion } from './components/accordion/Accordion.vue'
+export { default as AccordionItem } from './components/accordion/AccordionItem.vue'
+export { default as AccordionTrigger } from './components/accordion/AccordionTrigger.vue'
+export { default as AccordionContent } from './components/accordion/AccordionContent.vue'
+export { default as NavLink } from './components/nav-link/NavLink.vue'
+export { default as Sidebar } from './components/sidebar/Sidebar.vue'
+export { default as SidebarGroup } from './components/sidebar/SidebarGroup.vue'
+export { default as AppShell } from './components/app-shell/AppShell.vue'
+export { default as Page } from './components/page/Page.vue'
+export { default as PageHeader } from './components/page/PageHeader.vue'
+export { default as PageBody } from './components/page/PageBody.vue'
+export { default as PageAside } from './components/page/PageAside.vue'
+export { default as Section } from './components/section/Section.vue'
+export { default as Highlight } from './components/highlight/Highlight.vue'
+export { default as Anchor } from './components/anchor/Anchor.vue'
+export type { AnchorItem } from './components/anchor/Anchor.vue'
+export { default as Breadcrumb } from './components/breadcrumb/Breadcrumb.vue'
+export { default as BreadcrumbItem } from './components/breadcrumb/BreadcrumbItem.vue'
+export { default as BreadcrumbSeparator } from './components/breadcrumb/BreadcrumbSeparator.vue'
+export { default as TooltipProvider } from './components/tooltip/TooltipProvider.vue'
+export { default as Tooltip } from './components/tooltip/Tooltip.vue'
+export { default as Popover } from './components/popover/Popover.vue'
+export { default as DropdownMenu } from './components/dropdown-menu/DropdownMenu.vue'
+export { default as DropdownMenuItem } from './components/dropdown-menu/DropdownMenuItem.vue'
+export { default as DropdownMenuCheckboxItem } from './components/dropdown-menu/DropdownMenuCheckboxItem.vue'
+export { default as DropdownMenuGroup } from './components/dropdown-menu/DropdownMenuGroup.vue'
+export { default as DropdownMenuSub } from './components/dropdown-menu/DropdownMenuSub.vue'
+export { default as DropdownMenuLabel } from './components/dropdown-menu/DropdownMenuLabel.vue'
+export { default as DropdownMenuSeparator } from './components/dropdown-menu/DropdownMenuSeparator.vue'
+export { default as DropdownMenuRadioGroup } from './components/dropdown-menu/DropdownMenuRadioGroup.vue'
+export { default as DropdownMenuRadioItem } from './components/dropdown-menu/DropdownMenuRadioItem.vue'
+export { default as Dialog } from './components/dialog/Dialog.vue'
+export { default as Drawer } from './components/drawer/Drawer.vue'
+export { default as SidebarTrigger } from './components/sidebar/SidebarTrigger.vue'
+export type { SidebarState } from './components/sidebar/context'
+export { default as Toaster } from './components/toast/Toaster.vue'
+export { toast } from './components/toast/store'
+export type { ToastTone, ToastOptions, ToasterPosition } from './components/toast/store'
+export { default as Spoiler } from './components/spoiler/Spoiler.vue'
+export { default as Skeleton } from './components/skeleton/Skeleton.vue'
+export { default as Image } from './components/image/Image.vue'
+export { default as ImageGroup } from './components/image/ImageGroup.vue'
+export { provideImageResolver, useImageResolver } from './components/image/resolver'
+export type { ImageResolver } from './components/image/resolver'
+export type { ImageVariants } from './components/image/image.variants'
+export { default as Spinner } from './components/spinner/Spinner.vue'
+export { default as ScrollArea } from './components/scroll-area/ScrollArea.vue'
+export {
+  SCROLL_STATE_FIELD,
+  RESTORE_DEADLINE_MS,
+  SAVE_THROTTLE_MS,
+  SCROLL_RESTORE_ATTR,
+  SCROLL_ATOP_ATTR,
+  SCROLL_AT_ATTR,
+  SCROLL_ATOP_HIDE_PX,
+  atopOff,
+  firstPaintRestoreScript,
+  readScrollRecord,
+  writeScrollRecord,
+  createScrollRestorer,
+} from './components/scroll-area/scroll-restore'
+export type {
+  ScrollRecord,
+  ScrollRestorer,
+  ScrollRestorerPorts,
+} from './components/scroll-area/scroll-restore'

package/src/lib/a11y.ts

@@ -0,0 +1,20 @@
+import { useAttrs, watchEffect } from 'vue'
+import { devWarn } from './dev'
+
+export function useAccessibleName(scope: string, required: () => boolean) {
+  if (!import.meta.env.DEV) return
+  const attrs = useAttrs()
+  watchEffect(() => {
+    if (!required()) return
+    if (attrs['aria-label'] || attrs['aria-labelledby'] || attrs.title) return
+    devWarn(scope, '缺少可访问名称,请提供 aria-label 或 aria-labelledby。', 'accessible-name')
+  })
+}
+
+export function useRequiredLabel(scope: string, has: () => boolean, what: string) {
+  if (!import.meta.env.DEV) return
+  watchEffect(() => {
+    if (has()) return
+    devWarn(scope, `缺少${what},屏幕阅读器无法识别该控件。`, `required-label:${what}`)
+  })
+}

package/src/lib/caret.ts

@@ -0,0 +1,52 @@
+const MIRRORED = [
+  'font-family',
+  'font-size',
+  'font-weight',
+  'font-style',
+  'font-variant',
+  'font-feature-settings',
+  'line-height',
+  'letter-spacing',
+  'word-spacing',
+  'text-indent',
+  'text-transform',
+  'tab-size',
+  'direction',
+  'padding-top',
+  'padding-right',
+  'padding-bottom',
+  'padding-left',
+  'border-top-width',
+  'border-right-width',
+  'border-bottom-width',
+  'border-left-width',
+]
+
+/**
+ * 量出 textarea 光标所在行的顶边（相对 textarea 自身的边框盒）。
+ * 原生没有光标几何 API，只能用同排版的镜像块把光标前的文字排一遍。
+ */
+export function caretTop(node: HTMLTextAreaElement, at = node.selectionEnd): number {
+  const style = getComputedStyle(node)
+  const mirror = node.ownerDocument.createElement('div')
+  for (const prop of MIRRORED) mirror.style.setProperty(prop, style.getPropertyValue(prop))
+  Object.assign(mirror.style, {
+    position: 'absolute',
+    top: '0',
+    insetInlineStart: '-9999px',
+    visibility: 'hidden',
+    pointerEvents: 'none',
+    boxSizing: 'border-box',
+    width: `${node.offsetWidth}px`,
+    whiteSpace: 'pre-wrap',
+    overflowWrap: 'break-word',
+  })
+  mirror.textContent = node.value.slice(0, at)
+  const marker = node.ownerDocument.createElement('span')
+  marker.textContent = node.value.slice(at) || '​'
+  mirror.append(marker)
+  node.ownerDocument.body.append(mirror)
+  const top = marker.offsetTop
+  mirror.remove()
+  return top
+}

package/src/lib/cn.ts

@@ -0,0 +1,9 @@
+import { clsx, type ClassValue } from 'clsx'
+import { extendTailwindMerge } from 'tailwind-merge'
+import { TW_MERGE_CONFIG, type HnClassGroupIds } from './tw-merge'
+
+const twMerge = extendTailwindMerge<HnClassGroupIds>(TW_MERGE_CONFIG)
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/lib/collapse.ts

@@ -0,0 +1,45 @@
+import { getCurrentInstance, onBeforeUpdate, onMounted } from 'vue'
+
+export type CollapseAxis = 'y' | 'x'
+
+export function collapseGapOf(parent: Element | null, axis: CollapseAxis = 'y') {
+  if (!parent) return '0px'
+  const style = getComputedStyle(parent)
+  const stacked = style.display.includes('flex') || style.display.includes('grid')
+  const gap = axis === 'y' ? style.rowGap : style.columnGap
+  return stacked && gap !== 'normal' ? gap : '0px'
+}
+
+export function writeCollapseGap(el: Element, parent: Element | null, axis: CollapseAxis = 'y') {
+  ;(el as HTMLElement).style.setProperty('--hn-collapse-gap', collapseGapOf(parent, axis))
+}
+
+export function collapseHooks(axis: CollapseAxis = 'y', parentOf?: () => Element | null) {
+  function beforeEnter(el: Element) {
+    writeCollapseGap(el, el.parentElement ?? parentOf?.() ?? null, axis)
+  }
+
+  function beforeLeave(el: Element) {
+    writeCollapseGap(el, el.parentElement, axis)
+  }
+
+  function afterEnter(el: Element) {
+    ;(el as HTMLElement).style.removeProperty('--hn-collapse-gap')
+  }
+
+  return { beforeEnter, afterEnter, beforeLeave }
+}
+
+export function useCollapseHooks(axis: CollapseAxis = 'y') {
+  const instance = getCurrentInstance()
+  let parent: Element | null = null
+
+  function remember() {
+    parent = (instance?.proxy?.$el as Node | null)?.parentElement ?? parent
+  }
+
+  onMounted(remember)
+  onBeforeUpdate(remember)
+
+  return collapseHooks(axis, () => parent)
+}

package/src/lib/date.ts

@@ -0,0 +1,111 @@
+import {
+  CalendarDate,
+  CalendarDateTime,
+  Time,
+  parseDate,
+  parseDateTime,
+  parseTime,
+  type DateValue,
+} from '@internationalized/date'
+
+export type DateGranularity = 'day' | 'hour' | 'minute' | 'second'
+export type TimeGranularity = 'hour' | 'minute' | 'second'
+
+const TIME_LENGTH: Record<TimeGranularity, number> = {
+  hour: 'HH:mm'.length,
+  minute: 'HH:mm'.length,
+  second: 'HH:mm:ss'.length,
+}
+
+export function parseTimeValue(value: string | null | undefined): Time | undefined {
+  if (!value) return undefined
+  try {
+    return parseTime(value)
+  } catch {
+    return undefined
+  }
+}
+
+export function formatTimeValue(
+  value: { hour: number; minute: number; second: number },
+  granularity: TimeGranularity = 'minute',
+): string {
+  return new Time(value.hour, value.minute, value.second)
+    .toString()
+    .slice(0, TIME_LENGTH[granularity])
+}
+
+export function splitDateTime(value: string | null | undefined) {
+  if (!value) return { date: null, time: null }
+  const [date, time] = value.split('T')
+  return { date: date || null, time: time || null }
+}
+
+export function joinDateTime(date: string | null, time: string | null) {
+  return date && time ? `${date}T${time}` : null
+}
+
+export interface DateRangeValue {
+  start: string | null
+  end: string | null
+}
+
+interface DateRangeParts {
+  start: DateValue | undefined
+  end: DateValue | undefined
+}
+
+const LENGTH: Record<DateGranularity, number> = {
+  day: 'YYYY-MM-DD'.length,
+  hour: 'YYYY-MM-DDTHH:mm'.length,
+  minute: 'YYYY-MM-DDTHH:mm'.length,
+  second: 'YYYY-MM-DDTHH:mm:ss'.length,
+}
+
+export function parseDateValue(
+  value: string | null | undefined,
+  granularity: DateGranularity = 'day',
+): DateValue | undefined {
+  if (!value) return undefined
+  try {
+    if (granularity === 'day') return parseDate(value.slice(0, LENGTH.day))
+    return value.includes('T')
+      ? parseDateTime(value)
+      : parseDate(value).toDate('UTC')
+        ? toDateTime(parseDate(value))
+        : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function formatDateValue(value: DateValue, granularity: DateGranularity = 'day'): string {
+  if (granularity === 'day') return new CalendarDate(value.year, value.month, value.day).toString()
+  const time = value instanceof CalendarDateTime ? value : toDateTime(value)
+  return time.toString().slice(0, LENGTH[granularity])
+}
+
+export function parseDateRange(
+  value: DateRangeValue | null | undefined,
+  granularity: DateGranularity = 'day',
+): DateRangeParts {
+  return {
+    start: parseDateValue(value?.start, granularity),
+    end: parseDateValue(value?.end, granularity),
+  }
+}
+
+export function formatDateRange(
+  value: DateRangeParts,
+  granularity: DateGranularity = 'day',
+): DateRangeValue | null {
+  if (!value.start && !value.end) return null
+  return {
+    start: value.start ? formatDateValue(value.start, granularity) : null,
+    end: value.end ? formatDateValue(value.end, granularity) : null,
+  }
+}
+
+function toDateTime(value: DateValue) {
+  return new CalendarDateTime(value.year, value.month, value.day)
+}

package/src/lib/dev.ts

@@ -0,0 +1,13 @@
+const warned = new Set<string>()
+
+export function devWarn(scope: string, message: string, key?: string) {
+  if (!import.meta.env.DEV) return
+  const id = `${scope}:${key ?? message}`
+  if (warned.has(id)) return
+  warned.add(id)
+  console.warn(`[Hina UI] ${scope}: ${message}`)
+}
+
+export function resetDevWarnings() {
+  warned.clear()
+}

package/src/lib/field-focus.ts

@@ -0,0 +1,40 @@
+const INTERACTIVE = 'button, a, input, textarea, select, [contenteditable], [role="button"]'
+const CONTROL = 'input:not([type="hidden"]), textarea'
+
+function controlOf(node: Element) {
+  const control = node.matches(CONTROL) ? node : node.querySelector(CONTROL)
+  return control instanceof HTMLInputElement || control instanceof HTMLTextAreaElement
+    ? control
+    : null
+}
+
+/**
+ * 点击输入面里非交互的部分（附属格、前后缀、空白）时把焦点交给最近的输入区，返回被聚焦的输入区；点击落在交互元素上或者没有可聚焦的输入区时返回 null。
+ * 点击所在的段自己含输入区时只认它、不动光标（段内的处理器已经定过位）；否则先向后找，再向前找；落在点击位置之后的输入区把光标放到开头，之前的放到末尾。
+ */
+export function focusFieldFrom(root: HTMLElement, target: HTMLElement) {
+  if (target.closest(INTERACTIVE)) return null
+  const segments = Array.from(root.children)
+  const from = segments.findIndex(segment => segment.contains(target))
+  const own = from >= 0 ? controlOf(segments[from]!) : null
+  if (own && !own.disabled) {
+    own.focus()
+    return own
+  }
+  const after = segments.slice(from + 1)
+  const before = segments.slice(0, Math.max(from, 0)).reverse()
+  for (const [list, caret] of [
+    [after, 'start'],
+    [before, 'end'],
+  ] as const) {
+    for (const segment of list) {
+      const control = controlOf(segment)
+      if (!control || control.disabled) continue
+      control.focus()
+      const at = caret === 'start' ? 0 : control.value.length
+      control.setSelectionRange(at, at)
+      return control
+    }
+  }
+  return null
+}

package/src/lib/passthrough.ts

@@ -0,0 +1,9 @@
+import { defineComponent } from 'vue'
+
+export const Passthrough = defineComponent({
+  name: 'HnPassthrough',
+  setup:
+    (_, { slots }) =>
+    () =>
+      slots.default?.(),
+})

package/src/lib/tv.ts

@@ -0,0 +1,6 @@
+import { createTV } from 'tailwind-variants'
+import { TW_MERGE_CONFIG } from './tw-merge'
+
+export const tv = createTV({ twMergeConfig: TW_MERGE_CONFIG })
+
+export type { VariantProps } from 'tailwind-variants'