Feat#1417/add new menu component

packages/docs/modules/page-config/blocks/api/common-description.ts

@@ -15,6 +15,9 @@ export default
     eventArgument: "The event argument is:"
   },
   props: {
+    ariaLabel: "Sets the `aria-label` attribute.",
+    ariaLabeledby: "Sets the `aria-labelledby` attribute.",
+    role: "Sets the `role` attribute.",
     align: "Customizes horizontal position of component (flex based). Available values are strings: 'left', 'center', 'right', 'between', 'around', 'stretch'.",
     id: "Applies `id` to internal input component. Useful for native forms.",
     name: "Applies `name` to internal input component. Useful for native forms.",

packages/docs/modules/page-config/blocks/api/index.ts

@@ -3,6 +3,9 @@ import { definePageConfigBlock } from '../../types'
 import Component from './index.vue'
 import { VisualOptions, type ManualApiOptions, APIDescriptionOptions } from './types';
 import { parseComponent } from './component-parser'
+import type * as components from 'vuestic-ui/src/services/vue-plugin/components'
+import { ExtractComponentProps } from 'vuestic-ui/src/utils/component-options';
+import { VuesticComponent } from 'vuestic-ui/src/services/component-config';
 
 const setup = (
   componentName: string,
@@ -27,7 +30,20 @@ const setup = (
 }
 
 export default definePageConfigBlock({
-  setup: setup as unknown as (componentName: string, descriptionOptions: APIDescriptionOptions, manual?: ManualApiOptions, visualOptions?: VisualOptions) => ReturnType<typeof setup>,
+  setup: setup as unknown as <
+    ComponentName extends keyof typeof components,
+    Component extends typeof components[ComponentName] = typeof components[ComponentName]
+  >(
+    componentName: ComponentName,
+    descriptionOptions: {
+      props?: Partial<Record<keyof ExtractComponentProps<Component>, string>>,
+      events?: Partial<Record<keyof Component['emits'], string>>,
+      slots?: Record<string, string>,
+      methods?: Partial<Record<keyof Component['methods'], string>>,
+    },
+     manual?: ManualApiOptions,
+     visualOptions?: VisualOptions
+  ) => ReturnType<typeof setup>,
   component: Component,
 })
 

packages/docs/modules/page-config/runtime/index.ts

@@ -80,4 +80,4 @@ export type UnwrapPageConfigBlock<T extends Record<string, any>> = {
   _blockComponent: DefineComponent,
 } & T
 
-export const defineApiDescription = (options: APIDescriptionOptions) => options;
+export const defineApiDescription = <T extends APIDescriptionOptions>(options: T) => options;

packages/docs/page-config/navigationRoutes.ts

@@ -1,4 +1,3 @@
-import { navigationBadge } from './../utils/navigation/badge';
 import { navigationBadge, type NavigationBadge } from "../utils/navigation/badge";
 
 export type NavigationRoute = {
@@ -389,6 +388,20 @@ export const navigationRoutes: NavigationRoute[] = [
           badge : navigationBadge.updated('1.8.3'),
         }
       },
+      {
+        name: 'menu',
+        displayName: 'Menu',
+        meta: {
+          badge : navigationBadge.new('1.8.4'),
+        }
+      },
+      {
+        name: 'menu-list',
+        displayName: 'Menu List',
+        meta: {
+          badge : navigationBadge.new('1.8.4'),
+        }
+      },
       {
         category: "Utility",
         name: "value",

packages/docs/page-config/ui-elements/dropdown/api-description.ts

@@ -2,7 +2,10 @@ import { defineApiDescription } from "~/modules/page-config/runtime";
 
 export default defineApiDescription({
   props: {
+    anchor: "Anchor element. Dropdown will be opened when clicked on anchor. Can be `HTMLElement` or `CSS selector`",
+    closeOnAnchorClick: "Dropdown will be closed when clicked on anchor",
     closeOnContentClick: "Dropdown will be closed when clicked inside dropdown content",
+    closeOnFocusOutside: "Dropdown will be closed when focus is outside dropdown content and anchor",
     hoverOutTimeout: "Time in `ms` after mouse leave dropdown before it will be closed",
     hoverOverTimeout: "Time in `ms` after mouse enter dropdown before it will be opened",
     verticalScrollOnOverflow: "If true, dropdown content will adjust its height when the content is larger than available space",
@@ -11,14 +14,17 @@ export default defineApiDescription({
     placement: "Dropdown content will be placed on `placement` side of anchor",
     trigger: "Action that will triggered when open and close dropdown.",
     target: "Dropdown content parent. Dropdown content will be attached to `target` to prevent overflow",
-    closeOnAnchorClick:"Dropdown will be closed when anchor is clicked",
-    ariaLabel: "The aria-label of the component",
-    role: "The `role` attribute applied to the anchor"
+    role: "The role attribute of the dropdown",
   },
   events: {
     anchorClick: "The event is triggered when anchor is clicked",
-    clickOutside: "The event is triggered when clicked outside dropdown content and anchor",
-    contentClick: "The event is triggered when clicked inside dropdown content"
+    anchorDblclick: "The event is triggered when anchor is double clicked",
+    anchorRightClick: "The event is triggered when anchor is right clicked",
+    close: "The event is triggered when dropdown is closed",
+    open: "The event is triggered when dropdown is opened",
+    contentClick: "The event is triggered when clicked inside dropdown content",
+    focusOutside: "The event is triggered when focus is outside dropdown content and anchor",
+    clickOutside: "The event is triggered when clicked outside dropdown content and anchor"
   },
   slots: {
     anchor: "Slot for anchor. When anchor is clicked, dropdown will be opened",

packages/docs/page-config/ui-elements/menu-list/examples/Default.vue

@@ -0,0 +1,10 @@
+<template>
+  <VaMenuList
+    :options="['Option 1', 'Option 2', 'Option 3']"
+    @selected="(v) => alert(v)"
+  />
+</template>
+
+<script setup>
+  const alert = (...args) => window.alert(...args)
+</script>

packages/docs/page-config/ui-elements/menu-list/examples/Group.vue

@@ -0,0 +1,18 @@
+<template>
+  <VaMenuList
+    :options="options"
+    @selected="(v) => alert(v)"
+  />
+</template>
+
+<script setup>
+  const alert = (...args) => window.alert(...args)
+
+  const options = [
+    { id: '0', text: 'one', value: 'one', group: '' },
+    { id: '1', text: 'two', value: 'two', group: 'Group 1' },
+    { id: '2', text: 'three', value: 'three', group: '' },
+    { id: '3', text: 'four', value: 'four', group: 'Group 2' },
+    { id: '4', text: 'five', value: 'five', group: 'Group 2' },
+  ]
+</script>

packages/docs/page-config/ui-elements/menu-list/examples/Icon.vue

@@ -0,0 +1,18 @@
+<template>
+  <VaMenuList
+    :options="options"
+    @selected="(v) => alert(v)"
+  />
+</template>
+
+<script setup>
+  const alert = (...args) => window.alert(...args)
+
+  const options = [
+    { id: '0', text: 'copy', value: 'one', icon: 'content_copy', rightIcon: '' },
+    { id: '1', text: 'paste', value: 'two', icon: 'content_paste', rightIcon: '' },
+    { id: '2', text: 'cut', value: 'three', icon: 'content_cut', rightIcon: '' },
+    { id: '3', text: 'share', value: 'four', icon: '', rightIcon: 'share' },
+    { id: '4', text: 'delete', value: 'five', icon: 'delete' },
+  ]
+</script>

packages/docs/page-config/ui-elements/menu-list/examples/MenuItem.vue

@@ -0,0 +1,17 @@
+<template>
+  <VaMenuList>
+    <VaMenuItem @selected="alert">
+      Option 1
+    </VaMenuItem>
+    <VaMenuItem @selected="alert">
+      Option 2
+    </VaMenuItem>
+    <VaMenuItem @selected="alert">
+      Option 2
+    </VaMenuItem>
+  </VaMenuList>
+</template>
+
+<script setup lang="ts">
+  const alert = (...args) => window.alert(...args)
+</script>

packages/docs/page-config/ui-elements/menu-list/examples/WithDivider.vue

@@ -0,0 +1,27 @@
+<template>
+  <VaMenuList>
+    <VaMenuItem @selected="alert">
+      Option 1
+    </VaMenuItem>
+    <VaMenuItem @selected="alert">
+      Option 2
+    </VaMenuItem>
+    <VaDivider />
+    <VaMenuItem @selected="alert">
+      Option 3
+    </VaMenuItem>
+    <VaMenuItem @selected="alert">
+      Option 4
+    </VaMenuItem>
+    <div>
+      Custom divider
+    </div>
+    <VaMenuItem @selected="alert">
+      Option 5
+    </VaMenuItem>
+  </VaMenuList>
+</template>
+
+<script setup lang="ts">
+  const alert = (...args) => window.alert(...args)
+</script>

packages/docs/page-config/ui-elements/menu-list/index.ts

@@ -0,0 +1,49 @@
+export default definePageConfig({
+  blocks: [
+    block.title("Menu List"),
+    block.paragraph("The `VaMenuList` component is used to display structured information in selectable list format."),
+
+
+    block.link("VaMenu", "/ui-elements/menu", { preText: "See " }),
+
+    block.subtitle("Examples"),
+
+    block.example("Default", {
+      title: "Basic usage",
+      description: "To show menu items you can use `options` prop:",
+    }),
+    block.example("MenuItem", {
+      title: "Slot usage",
+      description: "You can also use slot and VaMenuItem component to achieve better flexibility.",
+    }),
+
+    block.example("Icon", {
+      title: "Icon",
+      description: "You can use `icon `and `rightIcon` properties in options or `left-icon` and `right-icon` slots in `VaMenuItem` component.",
+    }),
+
+    block.example("Group", {
+      title: "Group",
+      description: "You can use `group` property in options or `VaMenuGroup` component.",
+    }),
+
+    block.example("WithDivider", {
+      title: "With divider",
+      description: "You can use `VaDivider` component in pair with `VaMenuItem` components.",
+    }),
+
+    block.api("VaMenuList", {
+      props: {
+        textBy: 'When `options` prop items are an objects, this key will be used as displayed text. Can be string (path to the key) or function of type: `(option) => option.text`',
+        valueBy: 'When `options` prop items are an objects, this key will be used in `selected` event. Can be string (path to the key) or function of type: `(option) => option.value`',
+        trackBy: 'When `options` prop items are an objects, this key will be used to track selected `options`. Can be string (path to the key) or function of type: `(option) => option.track`',
+        groupBy: 'When `options` prop items are an objects, this key will be used to check correct option group',
+        disabledBy: "Specify the key in the object to be used as item `disabled` prop. Can be string (path to the key) or function of type: `(option) => option.disabled`",
+        options: "Available options that the user can select from",
+      },
+      events: {
+        selected: 'Emitted when an option is selected. Returns the selected option value as first argument and the selected option as second argument',
+      }
+    }),
+  ],
+})

packages/docs/page-config/ui-elements/menu/api-description.ts

@@ -0,0 +1,41 @@
+import { defineApiDescription } from "~/modules/page-config/runtime";
+
+export default defineApiDescription({
+  props: {
+    anchor: "Anchor element. Dropdown will be opened when clicked on anchor. Can be `HTMLElement` or `CSS selector`",
+    closeOnAnchorClick: "Dropdown will be closed when clicked on anchor",
+    closeOnContentClick: "Dropdown will be closed when clicked inside dropdown content",
+    closeOnFocusOutside: "Dropdown will be closed when focus is outside dropdown content and anchor",
+    hoverOutTimeout: "Time in `ms` after mouse leave dropdown before it will be closed",
+    hoverOverTimeout: "Time in `ms` after mouse enter dropdown before it will be opened",
+    verticalScrollOnOverflow: "If true, dropdown content will adjust its height when the content is larger than available space",
+    keepAnchorWidth: "If true, dropdown content will have exact same width as anchor",
+    offset: "Dropdown content will be moved by main and cross axis according to current `placement`",
+    placement: "Dropdown content will be placed on `placement` side of anchor",
+    trigger: "Action that will triggered when open and close dropdown.",
+    target: "Dropdown content parent. Dropdown content will be attached to `target` to prevent overflow",
+    role: "The role attribute of the dropdown",
+
+    textBy: 'When `options` prop items are an objects, this key will be used as displayed text. Can be string (path to the key) or function of type: `(option) => option.text`',
+    valueBy: 'When `options` prop items are an objects, this key will be used in `selected` event. Can be string (path to the key) or function of type: `(option) => option.value`',
+    trackBy: 'When `options` prop items are an objects, this key will be used to track selected `options`. Can be string (path to the key) or function of type: `(option) => option.track`',
+    groupBy: 'When `options` prop items are an objects, this key will be used to check correct option group',
+    disabledBy: "Specify the key in the object to be used as item `disabled` prop. Can be string (path to the key) or function of type: `(option) => option.disabled`",
+    options: "Available options that the user can select from",
+  },
+  events: {
+    anchorClick: "The event is triggered when anchor is clicked",
+    anchorDblclick: "The event is triggered when anchor is double clicked",
+    anchorRightClick: "The event is triggered when anchor is right clicked",
+    close: "The event is triggered when dropdown is closed",
+    open: "The event is triggered when dropdown is opened",
+    contentClick: "The event is triggered when clicked inside dropdown content",
+    focusOutside: "The event is triggered when focus is outside dropdown content and anchor",
+    clickOutside: "The event is triggered when clicked outside dropdown content and anchor",
+    selected: 'Emitted when an option is selected. Returns the selected option value as first argument and the selected option as second argument',
+  },
+  slots: {
+    anchor: "Slot for anchor. When anchor is clicked, dropdown will be opened",
+    default: "Dropdown content",
+  }
+});

packages/docs/page-config/ui-elements/menu/examples/Context.vue

@@ -0,0 +1,20 @@
+<template>
+  <VaMenu
+    :options="['Option 1', 'Option 2', 'Option 3']"
+    preset="context"
+    @selected="(v) => alert(v)"
+  >
+    <template #anchor>
+      <va-image
+        class="h-[300px] w-[300px]"
+        src="https://picsum.photos/1500"
+      >
+        <va-badge text="Right click this image" />
+      </va-image>
+    </template>
+  </VaMenu>
+</template>
+
+<script setup>
+  const alert = (...args) => window.alert(...args)
+</script>

packages/docs/page-config/ui-elements/menu/examples/Default.vue

@@ -0,0 +1,14 @@
+<template>
+  <VaMenu
+    :options="['Option 1', 'Option 2', 'Option 3']"
+    @selected="(v) => alert(v)"
+  >
+    <template #anchor>
+      <VaButton>Open menu</VaButton>
+    </template>
+  </VaMenu>
+</template>
+
+<script setup>
+  const alert = (...args) => window.alert(...args)
+</script>

packages/docs/page-config/ui-elements/menu/examples/Group.vue

@@ -0,0 +1,22 @@
+<template>
+  <VaMenu
+    :options="options"
+    @selected="(v) => alert(v)"
+  >
+    <template #anchor>
+      <VaButton>Open menu</VaButton>
+    </template>
+  </VaMenu>
+</template>
+
+<script setup>
+  const alert = (...args) => window.alert(...args)
+
+  const options = [
+    { id: '0', text: 'one', value: 'one', group: '' },
+    { id: '1', text: 'two', value: 'two', group: 'Group 1' },
+    { id: '2', text: 'three', value: 'three', group: '' },
+    { id: '3', text: 'four', value: 'four', group: 'Group 2' },
+    { id: '4', text: 'five', value: 'five', group: 'Group 2' },
+  ]
+</script>

packages/docs/page-config/ui-elements/menu/examples/Icon.vue

@@ -0,0 +1,22 @@
+<template>
+  <VaMenu
+    :options="options"
+    @selected="(v) => alert(v)"
+  >
+    <template #anchor>
+      <VaButton>Open menu</VaButton>
+    </template>
+  </VaMenu>
+</template>
+
+<script setup>
+  const alert = (...args) => window.alert(...args)
+
+  const options = [
+    { text: 'copy', value: 'one', icon: 'content_copy' },
+    { text: 'paste', value: 'two', icon: 'content_paste' },
+    { text: 'cut', value: 'three', icon: 'content_cut' },
+    { text: 'share', value: 'four', rightIcon: 'share' },
+    { text: 'delete', value: 'five', icon: 'delete' },
+  ]
+</script>

packages/docs/page-config/ui-elements/menu/examples/MenuItem.vue

@@ -0,0 +1,21 @@
+<template>
+  <VaMenu>
+    <template #anchor>
+      <VaButton>Open menu</VaButton>
+    </template>
+
+    <VaMenuItem @selected="alert">
+      Option 1
+    </VaMenuItem>
+    <VaMenuItem @selected="alert">
+      Option 2
+    </VaMenuItem>
+    <VaMenuItem @selected="alert">
+      Option 2
+    </VaMenuItem>
+  </VaMenu>
+</template>
+
+<script setup lang="ts">
+  const alert = (...args) => window.alert(...args)
+</script>