@astryx-vue/core 0.2.5 → 0.3.0

package/dist/index-DVmgNb78.d.ts

@@ -0,0 +1,143 @@
+import { n as LayerPlacement, t as LayerAlignment } from "./position-DFW5ymAF.js";
+import { a as PopoverRole, i as PopoverProps, n as PopoverPadding, r as PopoverPlacement, t as PopoverAlignment } from "./types-OGMYGejX.js";
+import { CSSProperties, ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+//#region src/Popover/Popover.vue.d.ts
+declare var __VLS_1: {}, __VLS_3: {}, __VLS_11: {};
+type __VLS_Slots = {} & {
+  default?: (props: typeof __VLS_1) => any;
+} & {
+  default?: (props: typeof __VLS_3) => any;
+} & {
+  content?: (props: typeof __VLS_11) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<PopoverProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+  openChange: (isOpen: boolean) => any;
+}, string, import("vue").PublicProps, Readonly<PopoverProps> & Readonly<{
+  onOpenChange?: ((isOpen: boolean) => any) | undefined;
+}>, {
+  label: string;
+  anchor: HTMLElement | null;
+  width: string | number;
+  isOpen: boolean;
+  placement: LayerPlacement;
+  alignment: LayerAlignment;
+  padding: PopoverPadding;
+  hasAutoFocus: boolean;
+  role: PopoverRole;
+  isEnabled: boolean;
+  isModal: boolean;
+  hasCloseButton: boolean;
+  closeButtonLabel: string;
+  hasLightDismiss: boolean;
+  hasEscapeDismiss: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+type __VLS_WithSlots<T, S> = T & {
+  new (): {
+    $slots: S;
+  };
+};
+//#endregion
+//#region src/Popover/usePopover.d.ts
+interface UsePopoverOptions {
+  /**
+   * 相对触发元素的方位。
+   * @default 'below'
+   */
+  placement?: MaybeRefOrGetter<PopoverPlacement>;
+  /**
+   * 沿方位轴的对齐方式。
+   * @default 'start'
+   */
+  alignment?: MaybeRefOrGetter<PopoverAlignment>;
+  /**
+   * 受控的打开状态。不传就自己管。
+   */
+  isOpen?: MaybeRefOrGetter<boolean | undefined>;
+  /**
+   * 是否响应触发器的点击。
+   * @default true
+   */
+  isEnabled?: MaybeRefOrGetter<boolean>;
+  /**
+   * 点击外部是否关闭。
+   * @default true
+   */
+  hasLightDismiss?: MaybeRefOrGetter<boolean>;
+  /**
+   * 按 Escape 是否关闭。
+   * @default true
+   */
+  hasEscapeDismiss?: MaybeRefOrGetter<boolean>;
+  /**
+   * 打开后是否把焦点移进内容。
+   * `role="dialog"` 且内容里没有可聚焦元素时，焦点落到内容容器上。
+   * @default true
+   */
+  hasAutoFocus?: MaybeRefOrGetter<boolean>;
+  /**
+   * 初始焦点要跳过的元素选择器，例如组件自带的关闭按钮。
+   */
+  closeButtonSelector?: string;
+  /**
+   * `role="dialog"` 时给浮层的无障碍名称。没有可见标题时请务必提供。
+   */
+  dialogLabel?: MaybeRefOrGetter<string | undefined>;
+  /**
+   * 内容容器的 ARIA role。
+   * 真正的对话内容用 `dialog`；菜单、列表框这类自己带 role 的弹层用 `none`，
+   * 并让触发器保持 DOM 焦点。
+   * @default 'dialog'
+   */
+  role?: MaybeRefOrGetter<PopoverRole>;
+  /**
+   * `role="dialog"` 时是否模态。
+   * @default true
+   */
+  isModal?: MaybeRefOrGetter<boolean>;
+  /** 浮层显示后调用。 */
+  onShow?: () => void;
+  /** 浮层隐藏后调用。 */
+  onHide?: () => void;
+}
+interface UsePopoverReturn {
+  /** 浮层当前是否打开。 */
+  isOpen: Ref<boolean>;
+  /** 触发器元素。hook 会给它挂点击、键盘和 ARIA 关系。 */
+  triggerRef: Ref<HTMLElement | null>;
+  /** 定位用的锚点元素。不传就用 `triggerRef`。 */
+  anchorRef: Ref<HTMLElement | null>;
+  /** 浮层内容容器。 */
+  contentRef: Ref<HTMLElement | null>;
+  /** 浮层的唯一 ID。 */
+  id: string;
+  /** 锚点的 CSS 标识，用于高级定位场景。 */
+  anchorId: string;
+  /** 浮层的内联定位样式。 */
+  contentStyle: ComputedRef<CSSProperties>;
+  /** 实际生效的方位（空间不够时会翻转）。 */
+  resolvedPlacement: ComputedRef<LayerPlacement>;
+  /** 直接摊到内容容器上的属性：ID、role、aria-modal、aria-label、tabindex。 */
+  surfaceProps: ComputedRef<Record<string, unknown>>;
+  /** 触发器上要摊的 ARIA 属性。hook 也会自动写到 `triggerRef` 指向的元素上。 */
+  triggerProps: ComputedRef<Record<string, unknown>>;
+  /** 打开浮层。 */
+  show: () => void;
+  /** 关闭浮层。 */
+  hide: () => void;
+  /** 在打开和关闭之间切换。 */
+  toggle: () => void;
+}
+/**
+ * 对应原版 Astryx 的 `hooks/usePopover`：点击触发、能把焦点管起来的浮层。
+ * 在 `useLayer` 之上叠了焦点陷阱、自动聚焦、点击外部 / Escape 关闭和 ARIA 关系，
+ * `Popover` 组件内部也用它。
+ *
+ * ```ts
+ * const { triggerRef, contentRef, contentStyle, surfaceProps } = usePopover({ dialogLabel: 'Actions' })
+ * ```
+ */
+declare function usePopover(options?: UsePopoverOptions): UsePopoverReturn;
+//#endregion
+export { _default as i, UsePopoverReturn as n, usePopover as r, UsePopoverOptions as t };

package/dist/{index-CDdRQQF3.d.ts → index-DWh2WC8W.d.ts}

@@ -1,5 +1,6 @@
-import { n as SpacingStep } from "./types-D7QNSqoN.js";
-import { n as SizeValue } from "./size-BuTzpgnR.js";
+import { n as SpacingStep } from "./types-BTk0WZ0b.js";
+import { o as SizeValue } from "./types-uFMH9NaM.js";
+import { r as ResizableProps } from "./useResizable-DDwPpPe6.js";
 import { ComputedRef, InjectionKey, VNodeChild } from "vue";
 //#region src/Layout/context.d.ts
 type LayoutArea = 'header' | 'start' | 'content' | 'end' | 'footer';
@@ -72,9 +73,14 @@ interface LayoutContentProps {
 interface LayoutContentSlots {
   default?: () => VNodeChild;
 }
-interface LayoutResizable {
-  _size: number;
-}
+/**
+ * `useResizable()` 返回的 `props`。
+ *
+ * 除 `_size` 外都写成可选，手写的 `{ _size: 250 }` 照样能编译。
+ * `_direction` 是这块区域拖拽的轴：`horizontal` 表示改宽度，`vertical` 表示改高度，
+ * 要和旁边 `ResizeHandle` 的 `direction` 保持一致。
+ */
+type LayoutResizable = Pick<ResizableProps, '_size'> & Partial<Omit<ResizableProps, '_size'>>;
 interface LayoutPanelProps {
   /** 朝向内容的那条边。和旁边的 ResizeHandle 分隔线不要同时开。 @default false */
   hasDivider?: boolean;
@@ -83,8 +89,14 @@ interface LayoutPanelProps {
   isScrollable?: boolean;
   label?: string;
   role?: string;
-  /** 宽度。数字是像素。传了 resizable 时以钩子的尺寸为准。 */
+  /**
+   * 宽度。数字是像素。传了 resizable 时以钩子的尺寸为准。
+   */
   width?: SizeValue;
+  /**
+   * `useResizable()` 给出的 `props`。传了之后宽度由钩子决定，`width` 不再生效。
+   * 对象里的 `_direction` 要和旁边 `ResizeHandle` 的 `direction` 一致。
+   */
   resizable?: LayoutResizable;
 }
 interface LayoutPanelSlots {

package/dist/index-DXpSFlPG.d.ts

@@ -0,0 +1,78 @@
+import { s as AstryxMessages } from "./loadCatalog-BGHKG_9N.js";
+import { ComputedRef, InjectionKey, MaybeRefOrGetter } from "vue";
+//#region src/locale/types.d.ts
+/** 内置文案的两种语言。其他语言用 `loadAstryxCatalog` 接原版 JSON。 */
+type AstryxLocale = 'en' | 'zh-CN';
+//#endregion
+//#region src/locale/context.d.ts
+declare const astryxLocaleKey: InjectionKey<MaybeRefOrGetter<string>>;
+declare const astryxMessagesKey: InjectionKey<MaybeRefOrGetter<AstryxMessages>>;
+/**
+ * 把语言标签收成组件能用的写法。
+ * `en` 和 `en-*` 收成 `en`。`zh`、`zh-CN`、`zh-Hans` 收成 `zh-CN`。
+ * `zh-TW` 以及其他标签保留规范写法，用来接 `loadAstryxCatalog` 的结果。
+ * 空值和解析不了的标签回到 `en`。
+ */
+declare function normalizeLocale(locale: string | null | undefined): string;
+declare function provideAstryxLocale(locale: MaybeRefOrGetter<string>, messages?: MaybeRefOrGetter<AstryxMessages>): void;
+declare function useAstryxLocale(): ComputedRef<string>;
+declare function useAstryxMessages(): ComputedRef<AstryxMessages>;
+//#endregion
+//#region src/locale/format.d.ts
+declare function formatCalendarMonth(year: number, month: number, locale: string): string;
+declare function weekdayNames(locale: string, style: 'long' | 'narrow' | 'short'): string[];
+//#endregion
+//#region src/locale/useCollator.d.ts
+/**
+ * 按当前语言比较字符串，对应原版的 `useCollator`。
+ * 没提供语言时用 `en`。`options` 用 ref 或 computed 包起来，变了才会重建比较器。
+ *
+ * @example
+ * ```ts
+ * const collator = useCollator({ numeric: true })
+ * items.sort((a, b) => collator.value.compare(a.name, b.name))
+ * ```
+ */
+declare function useCollator(options?: MaybeRefOrGetter<Intl.CollatorOptions | undefined>): ComputedRef<Intl.Collator>;
+//#endregion
+//#region src/locale/useLocale.d.ts
+interface UseLocaleReturn {
+  /**
+   * 最近的 `InternationalizationProvider` 的 BCP 47 语言标签。
+   * 没有 provider 时是 `'en'`。
+   */
+  locale: ComputedRef<string>;
+}
+/**
+ * 对应原版 Astryx 的 `hooks/useLocale`。
+ *
+ * 读当前生效的语言标签。把它交给需要显式语言的纯函数或别的包，
+ * 不要从 `navigator.language` 或者写死的字面量里另取一份，那样会跟 provider 对不上。
+ */
+declare function useLocale(): UseLocaleReturn;
+//#endregion
+//#region src/locale/useTranslator.d.ts
+/** 填进消息占位符的值。数字用来算复数和千分位。 */
+type TranslatorValues = Record<string, string | number>;
+/** 拿原文键换当前语言下的成品文案。 */
+type Translator = (key: string, values?: TranslatorValues) => string;
+interface UseTranslatorReturn {
+  /**
+   * 绑在当前 `InternationalizationProvider` 上的翻译函数。
+   * 生效的语言、`messages` 和 `overrides` 都由 provider 决定，这里只负责按键取。
+   */
+  t: Translator;
+}
+/**
+ * 对应原版 Astryx 的 `hooks/useTranslator`。
+ *
+ * 返回一个翻译函数，把原版的消息键（例如 `@astryx.pagination.next`）换成
+ * 当前语言下的成品文案。语言、`messages` 目录和 `overrides` 都取自最近的
+ * `InternationalizationProvider`；没有 provider 时用包内自带的英文文案。
+ *
+ * 占位符的值按参数顺序填进去，复数和千分位按当前语言的规则算。
+ * 认不出来的键原样返回。
+ */
+declare function useTranslator(): UseTranslatorReturn;
+//#endregion
+export { UseLocaleReturn as a, formatCalendarMonth as c, astryxMessagesKey as d, normalizeLocale as f, AstryxLocale as g, useAstryxMessages as h, useTranslator as i, weekdayNames as l, useAstryxLocale as m, TranslatorValues as n, useLocale as o, provideAstryxLocale as p, UseTranslatorReturn as r, useCollator as s, Translator as t, astryxLocaleKey as u };

package/dist/{index-C_2Z65Rp.d.ts → index-DeQwYJbg.d.ts}

@@ -55,13 +55,50 @@ type __VLS_WithSlots<T, S> = T & {
 //#endregion
 //#region src/TreeList/useTreeFocus.d.ts
 interface UseTreeFocusOptions {
+  /**
+   * 树容器里可见树节点的选择器，按 DOM 顺序。
+   * @default '[role="treeitem"]'
+   */
+  itemSelector?: string;
+  /**
+   * 判断某个树节点是否停用、导航时要跳过。
+   * 不传时看 `data-tree-disabled` 和 `aria-disabled`。
+   */
+  isItemDisabled?: (item: HTMLElement) => boolean;
+  /**
+   * 读某个树节点的层级（从 1 开始）。
+   * 不传时看 `aria-level`。
+   */
+  getLevel?: (item: HTMLElement) => number;
+  /** 展开或收起指定 id 的树节点时调用。 */
   onToggleExpand?: (id: string) => void;
-  onActivate?: (current: HTMLElement) => boolean;
+  /** Enter 或空格激活树节点时调用。返回 true 表示已处理，否则交给展开切换。 */
+  onActivate?: (item: HTMLElement, id: string | undefined) => boolean | void;
+  /** 这里把焦点移到某个树节点之后调用，用来同步你自己管理的 tab 停靠点。 */
+  onActiveChange?: (id: string | undefined) => void;
+  /**
+   * 是否由这里管理唯一的 tab 停靠点：给各项打上 `tabindex="0"` / `-1`，
+   * 挂载时对齐一次，导航时跟着走。挂载时已有的 `tabindex="0"` 会被保留为起点。
+   * @default false
+   */
+  hasRovingTabIndex?: boolean;
+  /**
+   * 是否启用 typeahead：敲字符跳到下一个以这些字符开头的节点。
+   * @default true
+   */
+  typeahead?: boolean;
 }
+/**
+ * 树形控件的方向键焦点：上下 Home End 在可见节点间线性走（跳过停用项），
+ * 左右走树的语义（展开收起、进第一个子节点、回父节点），Enter 和空格激活，
+ * 敲字符走 typeahead。方向键横过来时看容器的书写方向，RTL 里左右对调。
+ */
 declare function useTreeFocus(options: UseTreeFocusOptions): {
   treeRef: Ref<HTMLElement | null>;
   handleKeyDown: (event: KeyboardEvent) => void;
-  handleFocus: () => void;
+  handleFocus: (event?: FocusEvent) => void;
+  focusFirst: () => void;
+  focusLast: () => void;
 };
 //#endregion
 export { TreeListItemData as a, TreeListVariant as c, TreeListDensity as i, useTreeFocus as n, TreeListProps as o, _default as r, TreeListSlots as s, UseTreeFocusOptions as t };

package/dist/{index-JL4auphT.d.ts → index-GI9xIV9l.d.ts}

@@ -32,10 +32,10 @@ declare const __VLS_base$2: import("vue").DefineComponent<ItemProps, {
   focus: typeof focus;
   blur: typeof blur;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ItemProps> & Readonly<{}>, {
-  isSelected: boolean;
   isDisabled: boolean;
   as: ItemElement;
   density: ListDensity;
+  isSelected: boolean;
   align: ItemAlign;
   layout: ItemLayout;
   isHighlighted: boolean;
@@ -53,8 +53,8 @@ type __VLS_Slots$1 = ListSlots;
 declare const __VLS_base$1: import("vue").DefineComponent<ListProps, {
   element: import("vue").ComputedRef<HTMLUListElement | HTMLOListElement | null>;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ListProps> & Readonly<{}>, {
-  density: ListDensity;
   start: number;
+  density: ListDensity;
   hasDividers: boolean;
   listStyle: ListMarkerStyle;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;