@soybeanjs/headless 0.17.0 → 0.18.0

package/README.md

@@ -13,6 +13,8 @@ A collection of unstyled, accessible UI primitives for Vue 3.
 
 Some multi-slot components also expose `Compact` aggregators, such as `AccordionCompact` and `TableCompact`. These headless entry points own item iteration and default content/icon composition, while styled wrappers stay focused on classes and prop forwarding.
 
+Current Compact coverage also includes stable structures such as card, date-field, dialog, editable, hover-card, layout, navigation-menu, pagination, popover, and stepper.
+
 ## 📦 Installation
 
 ```bash
@@ -63,27 +65,30 @@ import {
 
 ```
 headless/src/
-├── components/    # 50 primitives (accordion, dialog, select…)
-├── composables/   # 26 shared hooks (state, focus, floating, selection…)
+├── components/    # 95 component dirs (accordion, dialog, select…)
+├── composables/   # 25 shared hooks (state, focus, floating, selection…)
 ├── shared/        # Pure TS utilities (DOM, focus, tree, form, guard)
 ├── constants/     # ARIA attributes, component keys
+├── date/          # Shared date and calendar helpers
 ├── types/         # Global types (ClassValue, UiClass, PropsToContext…)
-└── index.ts        # Main barrel export
+└── index.ts       # Main barrel export
 ```
 
 ### Sub-path Exports
 
 ```ts
 import { AccordionRoot } from '@soybeanjs/headless'; // components + types
-import { useControllableState } from '@soybeanjs/headless/composables'; // 26 composables
+import { useControllableState } from '@soybeanjs/headless/composables'; // 25 composables
 import { transformPropsToContext } from '@soybeanjs/headless/shared'; // pure TS utils
+import { createMonth } from '@soybeanjs/headless/date'; // shared date helpers
 import * as H from '@soybeanjs/headless/namespaced'; // namespace object
 import type { AccordionUiSlot } from '@soybeanjs/headless/accordion'; // per-component
+import type { UiClass } from '@soybeanjs/headless/types'; // shared type surface
 ```
 
 ## 🧩 Composables
 
-26 hooks organized by category:
+25 hooks organized by category:
 
 | Category      | Composables                                                    |
 | ------------- | -------------------------------------------------------------- |

package/README.zh-CN.md

@@ -13,6 +13,8 @@
 
 部分多插槽组件还会暴露 `Compact` 聚合层，例如 `AccordionCompact` 和 `TableCompact`。这些 headless 入口负责条目遍历以及默认内容 / 图标组合，而样式包装层只专注于类名和 props 转发。
 
+目前这类 Compact 约定式组合还覆盖了 card、date-field、dialog、editable、hover-card、layout、navigation-menu、pagination、popover、stepper 等稳定结构。
+
 ## 📦 安装
 
 ```bash
@@ -63,27 +65,30 @@ import {
 
 ```
 headless/src/
-├── components/    # 50 个原语组件（accordion、dialog、select…）
-├── composables/   # 26 个共享 hook（状态、焦点、浮层、选择…）
+├── components/    # 95 个组件目录（accordion、dialog、select…）
+├── composables/   # 25 个共享 hook（状态、焦点、浮层、选择…）
 ├── shared/        # 纯 TS 工具函数（DOM、焦点、树、表单、守卫）
 ├── constants/     # ARIA 属性常量、组件标识键
+├── date/          # 共享日期与日历工具
 ├── types/         # 全局类型（ClassValue、UiClass、PropsToContext…）
-└── index.ts        # 主 barrel 导出
+└── index.ts       # 主 barrel 导出
 ```
 
 ### 子路径导出
 
 ```ts
 import { AccordionRoot } from '@soybeanjs/headless'; // 组件 + 类型
-import { useControllableState } from '@soybeanjs/headless/composables'; // 26 个 composable
+import { useControllableState } from '@soybeanjs/headless/composables'; // 25 个 composable
 import { transformPropsToContext } from '@soybeanjs/headless/shared'; // 纯 TS 工具
+import { createMonth } from '@soybeanjs/headless/date'; // 日期工具
 import * as H from '@soybeanjs/headless/namespaced'; // 命名空间导入
 import type { AccordionUiSlot } from '@soybeanjs/headless/accordion'; // 单组件类型
+import type { UiClass } from '@soybeanjs/headless/types'; // 共享类型导出
 ```
 
 ## 🧩 Composables
 
-26 个 hook，按功能分类：
+25 个 hook，按功能分类：
 
 | 分类     | Composables                                                    |
 | -------- | -------------------------------------------------------------- |

package/dist/components/_icon/types.d.ts

@@ -2,11 +2,11 @@ import { Component, VNode } from "vue";
 
 //#region src/components/_icon/types.d.ts
 /**
- * Type information for the icon value component.
+ * Type information for IconValue.
  */
 type IconValue = VNode | Component | string | null | undefined;
 /**
- * Props for the icon component.
+ * Properties for the Icon component.
  */
 interface IconProps {
   /**

package/dist/components/accordion/types.d.ts

@@ -5,7 +5,7 @@ import { ComputedRef, HTMLAttributes, ShallowRef } from "vue";
 
 //#region src/components/accordion/types.d.ts
 /**
- * Props for the accordion root component.
+ * Properties for the AccordionRoot component.
  */
 interface AccordionRootProps<M extends boolean = false> extends SelectionProps<M>, /** @vue-ignore */HTMLAttributes {
   /**
@@ -42,34 +42,34 @@ interface AccordionRootProps<M extends boolean = false> extends SelectionProps<M
   unmountOnHide?: boolean;
 }
 /**
- * Emits for the accordion root component.
+ * Events for the AccordionRoot component.
  */
 type AccordionRootEmits<M extends boolean = false> = SelectionEmits<M>;
 /**
- * Props for the accordion item component.
+ * Properties for the AccordionItem component.
  */
 interface AccordionItemProps extends Omit<CollapsibleRootProps, 'open' | 'defaultOpen' | 'onOpenChange'> {
   /** Value of the accordion item. All items within an accordion should use a unique value. */
   value: string;
 }
 /**
- * Props for the accordion header component.
+ * Properties for the AccordionHeader component.
  */
 interface AccordionHeaderProps extends /** @vue-ignore */HTMLAttributes {}
 /**
- * Props for the accordion trigger component.
+ * Properties for the AccordionTrigger component.
  */
 interface AccordionTriggerProps extends CollapsibleTriggerProps {}
 /**
- * Props for the accordion content component.
+ * Properties for the AccordionContent component.
  */
 interface AccordionContentProps extends CollapsibleContentProps {}
 /**
- * Props for the accordion description component.
+ * Properties for the AccordionDescription component.
  */
 interface AccordionDescriptionProps extends /** @vue-ignore */HTMLAttributes {}
 /**
- * Option data for the accordion component.
+ * Option data for the Accordion component.
  */
 interface AccordionOptionData extends Pick<AccordionItemProps, 'value' | 'disabled'> {
   /** The title of the accordion item. */
@@ -82,7 +82,7 @@ interface AccordionOptionData extends Pick<AccordionItemProps, 'value' | 'disabl
   icon?: IconValue;
 }
 /**
- * Props for the accordion compact component.
+ * Properties for the AccordionCompact component.
  */
 interface AccordionCompactProps<T extends AccordionOptionData = AccordionOptionData, M extends boolean = false> extends AccordionRootProps<M> {
   /**
@@ -90,32 +90,32 @@ interface AccordionCompactProps<T extends AccordionOptionData = AccordionOptionD
    */
   items: T[];
   /**
-   * Props forwarded to the item element.
+   * Properties forwarded to the item element.
    */
   itemProps?: AccordionItemProps;
   /**
-   * Props forwarded to the header element.
+   * Properties forwarded to the header element.
    */
   headerProps?: AccordionHeaderProps;
   /**
-   * Props forwarded to the trigger element.
+   * Properties forwarded to the trigger element.
    */
   triggerProps?: AccordionTriggerProps;
   /**
-   * Props forwarded to the content element.
+   * Properties forwarded to the content element.
    */
   contentProps?: AccordionContentProps;
   /**
-   * Props forwarded to the description element.
+   * Properties forwarded to the description element.
    */
   descriptionProps?: AccordionDescriptionProps;
 }
 /**
- * Emits for the accordion compact component.
+ * Events for the AccordionCompact component.
  */
 type AccordionCompactEmits<M extends boolean = false> = AccordionRootEmits<M>;
 /**
- * Slot props for the accordion compact component.
+ * Slot properties for the AccordionCompact component.
  */
 interface AccordionCompactSlotProps<T extends AccordionOptionData = AccordionOptionData, M extends boolean = false> {
   /**
@@ -136,7 +136,7 @@ interface AccordionCompactSlotProps<T extends AccordionOptionData = AccordionOpt
   open: boolean;
 }
 /**
- * Slots for the accordion compact component.
+ * Slots for the AccordionCompact component.
  */
 type AccordionCompactSlots<T extends AccordionOptionData = AccordionOptionData, M extends boolean = false> = {
   /**
@@ -161,11 +161,11 @@ type AccordionCompactSlots<T extends AccordionOptionData = AccordionOptionData,
   content?: (props: AccordionCompactSlotProps<T, M>) => any;
 };
 /**
- * Available UI slots for the accordion component.
+ * Available UI slots for the Accordion component.
  */
 type AccordionUiSlot = 'root' | 'item' | 'header' | 'trigger' | 'content' | 'description' | 'triggerLeadingIcon' | 'triggerIcon';
 /**
- * UI class overrides for the accordion component.
+ * UI class overrides for the Accordion component.
  */
 type AccordionUi = UiClass<AccordionUiSlot>;
 //#endregion

package/dist/components/affix/types.d.ts

@@ -3,15 +3,15 @@ import { ComputedRef, HTMLAttributes, ShallowRef } from "vue";
 
 //#region src/components/affix/types.d.ts
 /**
- * Type information for the affix target component.
+ * Type information for AffixTarget.
  */
 type AffixTarget = string | Window | HTMLElement | (() => HTMLElement);
 /**
- * State values for the affix component.
+ * State values for AffixState.
  */
 type AffixState = 'fixed' | 'static';
 /**
- * Props for the affix root component.
+ * Properties for the AffixRoot component.
  */
 interface AffixRootProps extends /** @vue-ignore */Omit<HTMLAttributes, 'onChange'> {
   /**
@@ -32,7 +32,7 @@ interface AffixRootProps extends /** @vue-ignore */Omit<HTMLAttributes, 'onChang
   target?: AffixTarget | null;
 }
 /**
- * Emits for the affix root component.
+ * Events for the AffixRoot component.
  */
 type AffixRootEmits = {
   /**
@@ -41,36 +41,36 @@ type AffixRootEmits = {
   change: [affixed: boolean];
 };
 /**
- * Props for the affix placeholder component.
+ * Properties for the AffixPlaceholder component.
  */
 interface AffixPlaceholderProps extends /** @vue-ignore */HTMLAttributes {}
 /**
- * Props for the affix content component.
+ * Properties for the AffixContent component.
  */
 interface AffixContentProps extends /** @vue-ignore */HTMLAttributes {}
 /**
- * Props for the affix compact component.
+ * Properties for the AffixCompact component.
  */
 interface AffixCompactProps extends AffixRootProps {
   /**
-   * Props forwarded to the placeholder element.
+   * Properties forwarded to the placeholder element.
    */
   placeholderProps?: AffixPlaceholderProps;
   /**
-   * Props forwarded to the content element.
+   * Properties forwarded to the content element.
    */
   contentProps?: AffixContentProps;
 }
 /**
- * Emits for the affix compact component.
+ * Events for the AffixCompact component.
  */
 type AffixCompactEmits = AffixRootEmits;
 /**
- * Available UI slots for the affix component.
+ * Available UI slots for the Affix component.
  */
 type AffixUiSlot = 'root' | 'placeholder' | 'content';
 /**
- * UI class overrides for the affix component.
+ * UI class overrides for the Affix component.
  */
 type AffixUi = UiClass<AffixUiSlot>;
 //#endregion

package/dist/components/alert/types.d.ts

@@ -5,7 +5,7 @@ import { ButtonHTMLAttributes, HTMLAttributes, ShallowRef } from "vue";
 
 //#region src/components/alert/types.d.ts
 /**
- * Props for the alert root component.
+ * Properties for the AlertRoot component.
  */
 interface AlertRootProps extends /** @vue-ignore */HTMLAttributes {
   /**
@@ -16,7 +16,7 @@ interface AlertRootProps extends /** @vue-ignore */HTMLAttributes {
   open?: boolean;
 }
 /**
- * Emits for the alert root component.
+ * Events for the AlertRoot component.
  */
 type AlertRootEmits = {
   /**
@@ -25,23 +25,23 @@ type AlertRootEmits = {
   'update:open': [open: boolean];
 };
 /**
- * Props for the alert content component.
+ * Properties for the AlertContent component.
  */
 interface AlertContentProps extends /** @vue-ignore */HTMLAttributes {}
 /**
- * Props for the alert title component.
+ * Properties for the AlertTitle component.
  */
 interface AlertTitleProps extends /** @vue-ignore */HTMLAttributes {}
 /**
- * Props for the alert description component.
+ * Properties for the AlertDescription component.
  */
 interface AlertDescriptionProps extends /** @vue-ignore */HTMLAttributes {}
 /**
- * Props for the alert close component.
+ * Properties for the AlertClose component.
  */
 interface AlertCloseProps extends PrimitiveProps, /** @vue-ignore */ButtonHTMLAttributes {}
 /**
- * Props for the alert compact component.
+ * Properties for the AlertCompact component.
  */
 interface AlertCompactProps extends AlertRootProps {
   /**
@@ -61,28 +61,28 @@ interface AlertCompactProps extends AlertRootProps {
    */
   closable?: boolean;
   /**
-   * Props forwarded to the content element.
+   * Properties forwarded to the content element.
    */
   contentProps?: AlertContentProps;
   /**
-   * Props forwarded to the title element.
+   * Properties forwarded to the title element.
    */
   titleProps?: AlertTitleProps;
   /**
-   * Props forwarded to the description element.
+   * Properties forwarded to the description element.
    */
   descriptionProps?: AlertDescriptionProps;
   /**
-   * Props forwarded to the close element.
+   * Properties forwarded to the close element.
    */
   closeProps?: AlertCloseProps;
 }
 /**
- * Emits for the alert compact component.
+ * Events for the AlertCompact component.
  */
 type AlertCompactEmits = AlertRootEmits;
 /**
- * Slots for the alert compact component.
+ * Slots for the AlertCompact component.
  */
 type AlertCompactSlots = {
   /**
@@ -111,11 +111,11 @@ type AlertCompactSlots = {
   close?: () => any;
 };
 /**
- * Available UI slots for the alert component.
+ * Available UI slots for the Alert component.
  */
 type AlertUiSlot = 'root' | 'icon' | 'title' | 'description' | 'content' | 'close';
 /**
- * UI class overrides for the alert component.
+ * UI class overrides for the Alert component.
  */
 type AlertUi = UiClass<AlertUiSlot>;
 //#endregion

package/dist/components/anchor/anchor-root.vue.d.ts

@@ -24,8 +24,8 @@ declare const __VLS_base: _$vue.DefineComponent<AnchorRootProps, {}, {}, {}, {},
 }>, {
   orientation: DataOrientation;
   modelValue: string;
-  bounds: number;
   offsetTop: number;
+  bounds: number;
 }, {}, {}, {}, string, _$vue.ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;

package/dist/components/anchor/types.d.ts

@@ -5,11 +5,11 @@ import { HTMLAttributes, ShallowRef } from "vue";
 
 //#region src/components/anchor/types.d.ts
 /**
- * Type information for the anchor container component.
+ * Type information for AnchorContainer.
  */
 type AnchorContainer = HTMLElement | Window;
 /**
- * Props for the anchor root component.
+ * Properties for the AnchorRoot component.
  */
 interface AnchorRootProps extends PrimitiveProps, /** @vue-ignore */HTMLAttributes {
   /**
@@ -50,7 +50,7 @@ interface AnchorRootProps extends PrimitiveProps, /** @vue-ignore */HTMLAttribut
   targetOffset?: number;
 }
 /**
- * Emits for the anchor root component.
+ * Events for the AnchorRoot component.
  */
 type AnchorRootEmits = {
   /**
@@ -69,11 +69,11 @@ type AnchorRootEmits = {
   }];
 };
 /**
- * Props for the anchor link component.
+ * Properties for the AnchorLink component.
  */
 interface AnchorLinkProps extends PrimitiveProps, LinkBaseProps, /** @vue-ignore */HTMLAttributes {
   /**
-   * Href.
+   * The link of anchor
    */
   href: string;
   /**
@@ -82,7 +82,7 @@ interface AnchorLinkProps extends PrimitiveProps, LinkBaseProps, /** @vue-ignore
   disabled?: boolean;
 }
 /**
- * Option data for the anchor component.
+ * Option data for the Anchor component.
  */
 interface AnchorOptionData extends Pick<AnchorLinkProps, 'disabled' | 'href' | 'target'> {
   /**
@@ -95,7 +95,7 @@ interface AnchorOptionData extends Pick<AnchorLinkProps, 'disabled' | 'href' | '
   title?: string;
 }
 /**
- * Props for the anchor item compact component.
+ * Properties for the AnchorItemCompact component.
  */
 interface AnchorItemCompactProps extends /** @vue-ignore */HTMLAttributes {
   /**
@@ -107,24 +107,24 @@ interface AnchorItemCompactProps extends /** @vue-ignore */HTMLAttributes {
    */
   item: AnchorOptionData;
   /**
-   * Props forwarded to the link element.
+   * Properties forwarded to the link element.
    */
   linkProps?: AnchorLinkProps;
   /**
-   * Props forwarded to the indicator element.
+   * Properties forwarded to the indicator element.
    */
   indicatorProps?: HTMLAttributes;
   /**
-   * Props forwarded to the title element.
+   * Properties forwarded to the title element.
    */
   titleProps?: HTMLAttributes;
   /**
-   * Props forwarded to the sub element.
+   * Properties forwarded to the sub element.
    */
   subProps?: HTMLAttributes;
 }
 /**
- * Props for the anchor compact component.
+ * Properties for the AnchorCompact component.
  */
 interface AnchorCompactProps extends AnchorRootProps {
   /**
@@ -132,32 +132,32 @@ interface AnchorCompactProps extends AnchorRootProps {
    */
   items: AnchorOptionData[];
   /**
-   * Props forwarded to the link element.
+   * Properties forwarded to the link element.
    */
   linkProps?: AnchorLinkProps;
   /**
-   * Props forwarded to the indicator element.
+   * Properties forwarded to the indicator element.
    */
   indicatorProps?: HTMLAttributes;
   /**
-   * Props forwarded to the title element.
+   * Properties forwarded to the title element.
    */
   titleProps?: HTMLAttributes;
   /**
-   * Props forwarded to the sub element.
+   * Properties forwarded to the sub element.
    */
   subProps?: HTMLAttributes;
 }
 /**
- * Emits for the anchor compact component.
+ * Events for the AnchorCompact component.
  */
 type AnchorCompactEmits = AnchorRootEmits;
 /**
- * Available UI slots for the anchor component.
+ * Available UI slots for the Anchor component.
  */
 type AnchorUiSlot = 'root' | 'link' | 'sub' | 'item' | 'indicator' | 'title';
 /**
- * UI class overrides for the anchor component.
+ * UI class overrides for the Anchor component.
  */
 type AnchorUi = UiClass<AnchorUiSlot>;
 //#endregion

package/dist/components/arrow/types.d.ts

@@ -2,7 +2,7 @@ import { SVGAttributes } from "vue";
 
 //#region src/components/arrow/types.d.ts
 /**
- * Props for the arrow component.
+ * Properties for the Arrow component.
  */
 interface ArrowProps extends /** @vue-ignore */SVGAttributes {}
 //#endregion

package/dist/components/aspect-ratio/types.d.ts

@@ -3,7 +3,7 @@ import { HTMLAttributes } from "vue";
 
 //#region src/components/aspect-ratio/types.d.ts
 /**
- * Props for the aspect ratio component.
+ * Properties for the AspectRatio component.
  */
 interface AspectRatioProps extends PrimitiveProps, /** @vue-ignore */HTMLAttributes {
   /**

package/dist/components/autocomplete/autocomplete-compact.vue.d.ts

@@ -6,15 +6,15 @@ declare const __VLS_export: <T extends AutocompleteSingleOptionData = Autocomple
   props: _$vue.PublicProps & __VLS_PrettifyLocal<AutocompleteCompactProps<T> & {
     onSelect?: ((item: T) => any) | undefined;
     "onUpdate:modelValue"?: ((value: string) => any) | undefined;
-    onHighlight?: ((payload?: AutocompleteHighlightPayload | undefined) => any) | undefined;
     "onUpdate:open"?: ((value: boolean) => any) | undefined;
+    onHighlight?: ((payload?: AutocompleteHighlightPayload | undefined) => any) | undefined;
   }> & (typeof globalThis extends {
     __VLS_PROPS_FALLBACK: infer P;
   } ? P : {});
   expose: (exposed: {}) => void;
   attrs: any;
   slots: AutocompleteCompactSlots<T>;
-  emit: ((evt: "select", item: T) => void) & ((evt: "update:modelValue", value: string) => void) & ((evt: "highlight", payload?: AutocompleteHighlightPayload | undefined) => void) & ((evt: "update:open", value: boolean) => void);
+  emit: ((evt: "select", item: T) => void) & ((evt: "update:modelValue", value: string) => void) & ((evt: "update:open", value: boolean) => void) & ((evt: "highlight", payload?: AutocompleteHighlightPayload | undefined) => void);
 }>) => _$vue.VNode & {
   __ctx?: Awaited<typeof __VLS_setup>;
 };

package/dist/components/autocomplete/autocomplete-root.vue.d.ts

@@ -20,17 +20,17 @@ declare const __VLS_base: _$vue.DefineComponent<AutocompleteRootProps, {
   highlightSelected: (event?: Event) => Promise<void> | undefined;
 }, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {
   "update:modelValue": (value: string) => any;
-  highlight: (payload?: AutocompleteHighlightPayload | undefined) => any;
   "update:open": (value: boolean) => any;
+  highlight: (payload?: AutocompleteHighlightPayload | undefined) => any;
 }, string, _$vue.PublicProps, Readonly<AutocompleteRootProps> & Readonly<{
   "onUpdate:modelValue"?: ((value: string) => any) | undefined;
-  onHighlight?: ((payload?: AutocompleteHighlightPayload | undefined) => any) | undefined;
   "onUpdate:open"?: ((value: boolean) => any) | undefined;
+  onHighlight?: ((payload?: AutocompleteHighlightPayload | undefined) => any) | undefined;
 }>, {
   modelValue: string;
-  highlightOnHover: boolean;
-  open: boolean;
   defaultOpen: boolean;
+  open: boolean;
+  highlightOnHover: boolean;
   openOnFocus: boolean;
   openOnClick: boolean;
 }, {}, {}, {}, string, _$vue.ComponentProvideOptions, false, {}, any>;