@antsoo-lib/components 0.1.2 → 0.1.4

package/src/menu/index.en-US.md

@@ -0,0 +1,166 @@
+---
+category: Components
+cols: 1
+type: Navigation
+title: Menu
+cover: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*KeyQQL5iKkkAAAAAAAAAAAAADrJ8AQ/original
+coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*Vn4XSqJFAxcAAAAAAAAAAAAADrJ8AQ/original
+---
+
+A versatile menu for navigation.
+
+## When To Use
+
+Navigation is an important part of any website, as a good navigation setup allows users to move around the site quickly and efficiently. Ant Design offers two navigation options: top and side. Top navigation provides all the categories and functions of the website. Side navigation provides the multi-level structure of the website.
+
+More layouts with navigation: [Layout](/components/layout).
+
+## Notes for developers
+
+- Menu is rendered as a `ul` element, so it only supports [`li` and `script-supporting` elements](https://html.spec.whatwg.org/multipage/grouping-content.html#the-ul-element) as children nodes。Your customized node should be wrapped by `Menu.Item`.
+- Menu needs to collect its node structure, so its children should be `Menu.*` or encapsulated HOCs.
+- Must set unique key for `SubMenu`
+
+## API
+
+### Menu
+
+| Param                 | Description                                                                  | Type                                   | Default value          |
+| --------------------- | ---------------------------------------------------------------------------- | -------------------------------------- | ---------------------- | ------ |
+| forceSubMenuRender    | render submenu into DOM before it shows                                      | boolean                                | false                  |
+| inlineCollapsed       | specifies the collapsed status when menu is inline mode                      | boolean                                | -                      |
+| inlineIndent          | indent px of inline menu item on each level                                  | number                                 | 24                     |
+| items                 | Menu item content                                                            | [ItemType\[\]](#itemtype)              | -                      | 4.20.0 |
+| mode                  | type of the menu; `vertical`, `horizontal`, and `inline` modes are supported | `vertical` \| `horizontal` \| `inline` | `vertical`             |
+| multiple              | Allow selection of multiple items                                            | boolean                                | false                  |
+| openKeys(v-model)     | array with the keys of currently opened sub menus                            | (string \| number)[]                   |                        |
+| overflowedIndicator   | Customized the ellipsis icon when menu is collapsed horizontally             | slot                                   | `<EllipsisOutlined />` |
+| selectable            | allow selecting menu items                                                   | boolean                                | true                   |
+| selectedKeys(v-model) | array with the keys of currently selected menu items                         | (string \| number)[]                   |                        |
+| style                 | style of the root node                                                       | object                                 |                        |
+| subMenuCloseDelay     | delay time to hide submenu when mouse leave, unit: second                    | number                                 | 0.1                    |
+| subMenuOpenDelay      | delay time to show submenu when mouse enter, unit: second                    | number                                 | 0                      |
+| theme                 | color theme of the menu                                                      | `light` \| `dark`                      | `light`                |
+| triggerSubMenuAction  | method of trigger submenu                                                    | `click` \| `hover`                     | `hover`                |
+
+### Menu Events
+
+| Events Name | Description                                                                        | Arguments                                |
+| ----------- | ---------------------------------------------------------------------------------- | ---------------------------------------- |
+| click       | callback executed when a menu item is clicked                                      | function({ item, key, keyPath })         |
+| deselect    | callback executed when a menu item is deselected, only supported for multiple mode | function({ item, key, selectedKeys })    |
+| openChange  | called when open/close sub menu                                                    | function(openKeys: (string \| number)[]) |
+| select      | callback executed when a menu item is selected                                     | function({ item, key, selectedKeys })    |
+
+### Menu.Item
+
+| Param    | Description                          | Type             | Default value |
+| -------- | ------------------------------------ | ---------------- | ------------- |
+| disabled | whether menu item is disabled or not | boolean          | false         |
+| key      | unique id of the menu item           | string \| number |               |
+| title    | set display title for collapsed item | string \| slot   |               |
+
+### ItemType
+
+> type ItemType = [MenuItemType](#menuitemtype) | [SubMenuType](#submenutype) | [MenuItemGroupType](#menuitemgrouptype) | [MenuDividerType](#menudividertype);
+
+#### MenuItemType
+
+| Param    | Description                          | Type                                     | Default value | Version |
+| -------- | ------------------------------------ | ---------------------------------------- | ------------- | ------- |
+| danger   | Display the danger style             | boolean                                  | false         |         |
+| disabled | Whether menu item is disabled        | boolean                                  | false         |         |
+| icon     | The icon of the menu item            | VueNode \| (item: MenuItemType) => VNode | -             |         |
+| key      | Unique ID of the menu item           | string \| number                         | -             |         |
+| label    | Menu label                           | VueNode                                  | -             |         |
+| title    | Set display title for collapsed item | string                                   | -             |         |
+
+#### SubMenuType
+
+<!-- prettier-ignore -->
+| Property | Description | Type | Default value | Version |
+| --- | --- | --- | --- | --- |
+| children | Sub-menus or sub-menu items | [ItemType\[\]](#itemtype) | - |  |
+| disabled | Whether sub-menu is disabled | boolean | false |  |
+| icon | Icon of sub menu | VueNode \| (item: SubMenuType) => VueNode | - |  |
+| key | Unique ID of the sub-menu | string \| number | - |  |
+| label | Menu label | VueNode | - |  |
+| popupClassName | Sub-menu class name, not working when `mode="inline"` | string | - |  |
+| popupOffset | Sub-menu offset, not working when `mode="inline"` | \[number, number] | - |  |
+| theme | Color theme of the SubMenu (inherits from Menu by default) |  | `light` \| `dark` | - |  |
+| onTitleClick | Callback executed when the sub-menu title is clicked | function({ key, domEvent }) | - |  |
+
+#### MenuItemGroupType
+
+Define `type` as `group` to make as group:
+
+```ts
+const groupItem = {
+  type: 'group', // Must have
+  label: 'My Group',
+  children: [],
+}
+```
+
+| Param    | Description            | Type                              | Default value | Version |
+| -------- | ---------------------- | --------------------------------- | ------------- | ------- |
+| children | Sub-menu items         | [MenuItemType\[\]](#menuitemtype) | -             |         |
+| label    | The title of the group | VueNode                           | -             |         |
+
+#### MenuDividerType
+
+Divider line in between menu items, only used in vertical popup Menu or Dropdown Menu. Need define the `type` as `divider`：
+
+```ts
+const dividerItem = {
+  type: 'divider', // Must have
+}
+```
+
+| Param  | Description            | Type    | Default value | Version |
+| ------ | ---------------------- | ------- | ------------- | ------- |
+| dashed | Whether line is dashed | boolean | false         |         |
+
+### Menu.SubMenu
+
+| Param          | Description                                       | Type              | Default value | Version |
+| -------------- | ------------------------------------------------- | ----------------- | ------------- | ------- |
+| disabled       | whether sub menu is disabled or not               | boolean           | false         |         |
+| expandIcon     | Customized expandIcon                             | slot              | arrow icon    | ｜      |
+| key            | Unique ID of the sub menu, required               | string \| number  |               |         |
+| popupClassName | Sub-menu class name                               | string            |               | 1.5.0   |
+| popupOffset    | Sub-menu offset, not working when `mode="inline"` | \[number, number] | -             |         |
+| title          | title of the sub menu                             | string\|slot      |               |         |
+
+The children of Menu.SubMenu must be `MenuItem` or `SubMenu`.
+
+`SubMenu` must pass the key. If it is not passed, the sub-elements under the SubMenu will be rendered in advance, and some scenes cannot be effectively highlighted.
+
+### Menu.SubMenu Events
+
+| Events Name | Description                                          | Arguments                   |
+| ----------- | ---------------------------------------------------- | --------------------------- |
+| titleClick  | callback executed when the sub menu title is clicked | function({ key, domEvent }) |
+
+### Menu.ItemGroup
+
+| Param    | Description        | Type         | Default value |
+| -------- | ------------------ | ------------ | ------------- |
+| children | sub-menu items     | MenuItem\[]  |               |
+| title    | title of the group | string\|slot |               |
+
+The children of Menu.ItemGroup must be `MenuItem`.
+
+### Menu.Divider
+
+Divider line in between menu items, only used in vertical popup Menu or Dropdown Menu.
+
+| Param  | Description            | Type    | Default value | Version |
+| ------ | ---------------------- | ------- | ------------- | ------- |
+| dashed | Whether line is dashed | boolean | false         | 4.17.0  |
+
+## FAQ
+
+### Why will Menu's children be rendered twice?
+
+Menu collects structure info with twice-render to support HOC usage. Merging into one render may cause the logic to become much more complex. Contributions to help improve the collection logic are welcomed.

package/src/menu/index.tsx

@@ -0,0 +1,56 @@
+import type { App, Plugin } from 'vue'
+
+import Divider from './src/Divider'
+import type { MenuDividerProps } from './src/Divider'
+import type { MenuItemGroupProps } from './src/ItemGroup'
+import ItemGroup from './src/ItemGroup'
+import type { MenuProps } from './src/Menu'
+import Menu from './src/Menu'
+import type { MenuItemProps } from './src/MenuItem'
+import MenuItem from './src/MenuItem'
+import type { SubMenuProps } from './src/SubMenu'
+import SubMenu from './src/SubMenu'
+import type { ItemType } from './src/hooks/useItems'
+import type { MenuMode, MenuTheme } from './src/interface'
+
+/* istanbul ignore next */
+Menu.install = function (app: App) {
+  app.component(Menu.name, Menu)
+  app.component(MenuItem.name, MenuItem)
+  app.component(SubMenu.name, SubMenu)
+  app.component(Divider.name, Divider)
+  app.component(ItemGroup.name, ItemGroup)
+  return app
+}
+
+Menu.Item = MenuItem
+Menu.Divider = Divider
+Menu.SubMenu = SubMenu
+Menu.ItemGroup = ItemGroup
+export type {
+  ItemType,
+  MenuDividerProps,
+  MenuItemGroupProps,
+  MenuItemProps,
+  MenuMode,
+  MenuProps,
+  MenuTheme,
+  SubMenuProps,
+}
+export {
+  Divider,
+  MenuItem as Item,
+  ItemGroup,
+  Divider as MenuDivider,
+  MenuItem,
+  ItemGroup as MenuItemGroup,
+  SubMenu,
+}
+
+export default Menu as typeof Menu &
+  Plugin & {
+    readonly Item: typeof MenuItem
+    readonly SubMenu: typeof SubMenu
+    readonly Divider: typeof Divider
+    readonly ItemGroup: typeof ItemGroup
+  }

package/src/menu/index.zh-CN.md

@@ -0,0 +1,166 @@
+---
+category: Components
+cols: 1
+type: 导航
+title: Menu
+subtitle: 导航菜单
+cover: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*KeyQQL5iKkkAAAAAAAAAAAAADrJ8AQ/original
+coverDark: https://mdn.alipayobjects.com/huamei_7uahnr/afts/img/A*Vn4XSqJFAxcAAAAAAAAAAAAADrJ8AQ/original
+---
+
+为页面和功能提供导航的菜单列表。
+
+## 何时使用
+
+导航菜单是一个网站的灵魂，用户依赖导航在各个页面中进行跳转。一般分为顶部导航和侧边导航，顶部导航提供全局性的类目和功能，侧边导航提供多级结构来收纳和排列网站架构。
+
+更多布局和导航的使用可以参考：[通用布局](/components/layout-cn)。
+
+## 开发者注意事项
+
+- Menu 元素为 `ul`，因而仅支持 [`li` 以及 `script-supporting` 子元素](https://html.spec.whatwg.org/multipage/grouping-content.html#the-ul-element)。因而你的子节点元素应该都在 `Menu.Item` 内使用。
+- Menu 需要计算节点结构，因而其子元素仅支持 `Menu.*` 以及对此进行封装的 HOC 组件。
+- 必须为 SubMenu 设置唯一 key
+
+## API
+
+### Menu
+
+| 参数                  | 说明                                           | 类型                                   | 默认值                 |
+| --------------------- | ---------------------------------------------- | -------------------------------------- | ---------------------- | --- |
+| forceSubMenuRender    | 在子菜单展示之前就渲染进 DOM                   | boolean                                | false                  |
+| inlineCollapsed       | inline 时菜单是否收起状态                      | boolean                                | -                      |
+| inlineIndent          | inline 模式的菜单缩进宽度                      | number                                 | 24                     |
+| items                 | 菜单内容                                       | [ItemType\[\]](#itemtype)              | -                      |     |
+| mode                  | 菜单类型，现在支持垂直、水平、和内嵌模式三种   | `vertical` \| `horizontal` \| `inline` | `vertical`             |
+| multiple              | 是否允许多选                                   | boolean                                | false                  |
+| openKeys(v-model)     | 当前展开的 SubMenu 菜单项 key 数组             | (string \| number)[]                   |                        |
+| overflowedIndicator   | 用于自定义 Menu 水平空间不足时的省略收缩的图标 | slot                                   | `<EllipsisOutlined />` |
+| selectable            | 是否允许选中                                   | boolean                                | true                   |
+| selectedKeys(v-model) | 当前选中的菜单项 key 数组                      | (string \| number)[]                   |                        |
+| subMenuCloseDelay     | 用户鼠标离开子菜单后关闭延时，单位：秒         | number                                 | 0.1                    |
+| subMenuOpenDelay      | 用户鼠标进入子菜单后开启延时，单位：秒         | number                                 | 0                      |
+| theme                 | 主题颜色                                       | `light` \| `dark`                      | `light`                |
+| triggerSubMenuAction  | 修改 Menu 子菜单的触发方式                     | `click` \| `hover`                     | `hover`                |
+
+### Menu 事件
+
+| 事件名称   | 说明                               | 回调参数                                 |
+| ---------- | ---------------------------------- | ---------------------------------------- |
+| click      | 点击 MenuItem 调用此函数           | function({ item, key, keyPath })         |
+| deselect   | 取消选中时调用，仅在 multiple 生效 | function({ item, key, selectedKeys })    |
+| openChange | SubMenu 展开/关闭的回调            | function(openKeys: (string \| number)[]) |
+| select     | 被选中时调用                       | function({ item, key, selectedKeys })    |
+
+### Menu.Item
+
+| 参数     | 说明                     | 类型             | 默认值 | 版本  |
+| -------- | ------------------------ | ---------------- | ------ | ----- |
+| disabled | 是否禁用                 | boolean          | false  |       |
+| icon     | 菜单图标                 | slot             |        | 2.8.0 |
+| key      | item 的唯一标志          | string \| number |        |       |
+| title    | 设置收缩时展示的悬浮标题 | string \| slot   |        |       |
+
+### ItemType
+
+> type ItemType = [MenuItemType](#menuitemtype) | [SubMenuType](#submenutype) | [MenuItemGroupType](#menuitemgrouptype) | [MenuDividerType](#menudividertype);
+
+### MenuItemType
+
+| 参数     | 说明                     | 类型                                   | 默认值 | 版本 |
+| -------- | ------------------------ | -------------------------------------- | ------ | ---- |
+| danger   | 展示错误状态样式         | boolean                                | false  |      |
+| disabled | 是否禁用                 | boolean                                | false  |      |
+| icon     | 菜单图标                 | VueNode\|(item: MenuItemType)=>VueNode | -      |      |
+| key      | item 的唯一标志          | string \| number                       | -      |      |
+| label    | 菜单项标题               | VueNode                                | -      |      |
+| title    | 设置收缩时展示的悬浮标题 | string                                 | -      |      |
+
+#### SubMenuType
+
+| 参数           | 说明                                 | 类型                                  | 默认值 | 版本 |
+| -------------- | ------------------------------------ | ------------------------------------- | ------ | ---- |
+| children       | 子菜单的菜单项                       | [ItemType\[\]](#itemtype)             | -      |      |
+| disabled       | 是否禁用                             | boolean                               | false  |      |
+| icon           | 菜单图标                             | VueNode\|(item: SubMenuType)=>VueNode | -      |      |
+| key            | 唯一标志                             | string \| number                      | -      |      |
+| label          | 菜单项标题                           | VueNode                               | -      |      |
+| popupClassName | 子菜单样式，`mode="inline"` 时无效   | string                                | -      |      |
+| popupOffset    | 子菜单偏移量，`mode="inline"` 时无效 | \[number, number]                     | -      |      |
+| onTitleClick   | 点击子菜单标题                       | function({ key, domEvent })           | -      |      |
+| theme          | 设置子菜单的主题，默认从 Menu 上继承 | `light` \| `dark`                     | -      |      |
+
+#### MenuItemGroupType
+
+定义类型为 `group` 时，会作为分组处理:
+
+```ts
+const groupItem = {
+  type: 'group', // Must have
+  label: 'My Group',
+  children: [],
+}
+```
+
+| 参数     | 说明         | 类型                              | 默认值 | 版本 |
+| -------- | ------------ | --------------------------------- | ------ | ---- |
+| children | 分组的菜单项 | [MenuItemType\[\]](#menuitemtype) | -      |      |
+| label    | 分组标题     | VueNode                           | -      |      |
+
+#### MenuDividerType
+
+菜单项分割线，只用在弹出菜单内，需要定义类型为 `divider`：
+
+```ts
+const dividerItem = {
+  type: 'divider', // Must have
+}
+```
+
+| 参数   | 说明     | 类型    | 默认值 | 版本 |
+| ------ | -------- | ------- | ------ | ---- |
+| dashed | 是否虚线 | boolean | false  |      |
+
+### Menu.SubMenu
+
+| 参数           | 说明                                 | 类型              | 默认值   | 版本  |
+| -------------- | ------------------------------------ | ----------------- | -------- | ----- |
+| disabled       | 是否禁用                             | boolean           | false    |       |
+| expandIcon     | 自定义 Menu 展开收起图标             | slot              | 箭头图标 |       |
+| icon           | 菜单图标                             | slot              |          | 2.8.0 |
+| key            | 唯一标志, 必填                       | string \| number  |          |       |
+| popupClassName | 子菜单样式                           | string            |          | 1.5.0 |
+| popupOffset    | 子菜单偏移量，`mode="inline"` 时无效 | \[number, number] | -        |       |
+| title          | 子菜单项值                           | string\|slot      |          |       |
+
+Menu.SubMenu 的子元素必须是 `MenuItem` 或者 `SubMenu`.
+
+`SubMenu` 必须传递 key，如不传递，该 SubMenu 下子元素将提前渲染，而且部分场景无法进行有效高亮。
+
+### SubMenu 事件
+
+| 事件名称   | 说明           | 回调参数            |
+| ---------- | -------------- | ------------------- |
+| titleClick | 点击子菜单标题 | ({ key, domEvent }) |
+
+### Menu.ItemGroup
+
+| 参数  | 说明     | 类型         | 默认值 |
+| ----- | -------- | ------------ | ------ |
+| title | 分组标题 | string\|slot |        |
+
+Menu.ItemGroup 的子元素必须是 `MenuItem`.
+
+### Menu.Divider
+
+菜单项分割线，只用在弹出菜单内。
+
+| 参数   | 说明     | 类型    | 默认值 | 版本 |
+| ------ | -------- | ------- | ------ | ---- |
+| dashed | 是否虚线 | boolean | false  | 3.0  |
+
+## FAQ
+
+### 为何 Menu 的子元素会渲染两次？
+
+Menu 通过二次渲染收集嵌套结构信息以支持 HOC 的结构。合并成一个推导结构会使得逻辑变得十分复杂，欢迎 PR 以协助改进该设计。

package/src/menu/src/Divider.tsx

@@ -0,0 +1,29 @@
+import type { ExtractPropTypes } from 'vue'
+import { computed, defineComponent } from 'vue'
+
+import { useInjectMenu } from './hooks/useMenuContext'
+
+export const menuDividerProps = () => ({
+  prefixCls: String,
+  dashed: Boolean,
+})
+
+export type MenuDividerProps = Partial<ExtractPropTypes<ReturnType<typeof menuDividerProps>>>
+
+export default defineComponent({
+  compatConfig: { MODE: 3 },
+  name: 'AMenuDivider',
+  props: menuDividerProps(),
+  setup(props) {
+    const { prefixCls } = useInjectMenu()
+    const cls = computed(() => {
+      return {
+        [`${prefixCls.value}-item-divider`]: true,
+        [`${prefixCls.value}-item-divider-dashed`]: !!props.dashed,
+      }
+    })
+    return () => {
+      return <li class={cls.value} />
+    }
+  },
+})

package/src/menu/src/InlineSubMenuList.tsx

@@ -0,0 +1,56 @@
+import { Transition, computed, defineComponent, ref, watch } from 'vue'
+
+import SubMenuList from './SubMenuList'
+import { MenuContextProvider, useInjectMenu } from './hooks/useMenuContext'
+import type { MenuMode } from './interface'
+
+export default defineComponent({
+  compatConfig: { MODE: 3 },
+  name: 'InlineSubMenuList',
+  inheritAttrs: false,
+  props: {
+    id: String,
+    open: Boolean,
+    keyPath: Array,
+  },
+  setup(props, { slots }) {
+    const fixedMode = computed<MenuMode>(() => 'inline')
+    const { motion, mode, defaultMotions } = useInjectMenu()
+    const sameModeRef = computed(() => mode.value === fixedMode.value)
+    const destroy = ref(!sameModeRef.value)
+
+    const mergedOpen = computed(() => (sameModeRef.value ? props.open : false))
+
+    // ================================= Effect =================================
+    // Reset destroy state when mode change back
+    watch(
+      mode,
+      () => {
+        if (sameModeRef.value) {
+          destroy.value = false
+        }
+      },
+      { flush: 'post' },
+    )
+    const mergedMotion = computed(() => {
+      const m =
+        motion.value || defaultMotions.value?.[fixedMode.value] || defaultMotions.value?.other
+      const res = typeof m === 'function' ? m() : m
+      return { ...res, appear: props.keyPath.length <= 1 }
+    })
+    return () => {
+      if (destroy.value) {
+        return null
+      }
+      return (
+        <MenuContextProvider mode={fixedMode.value}>
+          <Transition {...mergedMotion.value}>
+            <SubMenuList v-show={mergedOpen.value} id={props.id}>
+              {slots.default?.()}
+            </SubMenuList>
+          </Transition>
+        </MenuContextProvider>
+      )
+    }
+  },
+})

package/src/menu/src/ItemGroup.tsx

@@ -0,0 +1,48 @@
+import type { ExtractPropTypes } from 'vue'
+import { computed, defineComponent } from 'vue'
+
+import { getPropsSlot } from '../../_util/props-util'
+import { objectType } from '../../_util/type'
+import type { CustomSlotsType } from '../../_util/type'
+import PropTypes from '../../_util/vue-types'
+import { useMeasure } from './hooks/useKeyPath'
+import { useInjectMenu } from './hooks/useMenuContext'
+import type { ItemType } from './interface'
+
+export const menuItemGroupProps = () => ({
+  title: PropTypes.any,
+  // Internal user prop
+  originItemValue: objectType<ItemType>(),
+})
+
+export type MenuItemGroupProps = Partial<ExtractPropTypes<ReturnType<typeof menuItemGroupProps>>>
+
+export default defineComponent({
+  compatConfig: { MODE: 3 },
+  name: 'AMenuItemGroup',
+  inheritAttrs: false,
+  props: menuItemGroupProps(),
+  slots: Object as CustomSlotsType<{
+    title?: any
+    default?: any
+  }>,
+  setup(props, { slots, attrs }) {
+    const { prefixCls } = useInjectMenu()
+    const groupPrefixCls = computed(() => `${prefixCls.value}-item-group`)
+    const isMeasure = useMeasure()
+    return () => {
+      if (isMeasure) return slots.default?.()
+      return (
+        <li {...attrs} onClick={(e) => e.stopPropagation()} class={groupPrefixCls.value}>
+          <div
+            title={typeof props.title === 'string' ? props.title : undefined}
+            class={`${groupPrefixCls.value}-title`}
+          >
+            {getPropsSlot(slots, props, 'title')}
+          </div>
+          <ul class={`${groupPrefixCls.value}-list`}>{slots.default?.()}</ul>
+        </li>
+      )
+    }
+  },
+})