docs(mirinae): refactor hook names and use-tab hook and add use-tab h…

…ook story (#4888) * refactor: change mirinae hook file names Signed-off-by: Wanjin Noh <[email protected]> * refactor: change mirinae use-tab hook arg names Signed-off-by: Wanjin Noh <[email protected]> * refactor: change use-select hook arg name and remove useless type Signed-off-by: Wanjin Noh <[email protected]> * docs: refactor use-tab hook and add story Signed-off-by: Wanjin Noh <[email protected]> * fix: do not use type as assertion Signed-off-by: Wanjin Noh <[email protected]> * docs: add blockquote style to storybook Signed-off-by: Wanjin Noh <[email protected]> * docs: apply review Signed-off-by: Wanjin Noh <[email protected]> * docs: fix wrong import Signed-off-by: Wanjin Noh <[email protected]> --------- Signed-off-by: Wanjin Noh <[email protected]>
cloudforet-io · Oct 24, 2024 · 471d54e · 471d54e
1 parent f182336
commit 471d54e
Show file tree

Hide file tree

Showing 42 changed files with 544 additions and 131 deletions.
diff --git a/apps/storybook/.storybook/main.ts b/apps/storybook/.storybook/main.ts
@@ -33,6 +33,14 @@ const config: StorybookConfig = {
       <link rel='shortcut icon' type='image/x-icon' href="<%= BASE_URL %>favicon.ico">
       <link rel='manifest' type='image/x-icon' href="<%= BASE_URL %>manifest.json">
       <link rel="apple-touch-icon" href="<%= BASE_URL %>images/icons/icon-192x192.png">
+      <style>
+        blockquote {
+            background-color: #D9E8F2;
+            border-radius: 4px;
+            padding-top: 8px !important;
+            padding-bottom: 8px !important;
+        }  
+      </style>
       `
   },
   previewBody: (body) => {

diff --git a/...ules/top-bar-toolset/modules/top-bar-integration/modules/TopBarIntegrationContextMenu.vue b/...ules/top-bar-toolset/modules/top-bar-integration/modules/TopBarIntegrationContextMenu.vue
@@ -17,11 +17,11 @@ const labelRef = ref<HTMLElement|null>(null);
 const domainStore = useDomainStore();
 const state = reactive({
     integrationMenus: computed(() => domainStore.getters.domainExtraMenu?.contents ?? []),
-    tabs: computed(() => state.integrationMenus.map((menu) => ({
+    tabs: computed<TabItem[]>(() => state.integrationMenus.map((menu) => ({
         label: menu.title,
         name: menu.title,
         keepAlive: true,
-    })) as TabItem[]),
+    }))),
     activeTab: '',
 });
 

diff --git a/...able-data-sorting/__tests__/index.test.ts → ...able-data-sorting/__tests__/index.test.ts b/...able-data-sorting/__tests__/index.test.ts → ...able-data-sorting/__tests__/index.test.ts
diff --git a/packages/mirinae/src/data-display/tables/toolbox-table/PToolboxTable.stories.ts b/packages/mirinae/src/data-display/tables/toolbox-table/PToolboxTable.stories.ts
@@ -5,7 +5,7 @@ import type { ComponentProps } from 'vue-component-type-helpers';
 
 import { getUserFields, getUsers } from '@/data-display/tables/data-table/mock';
 import { getToolboxTableArgs, getToolboxTableArgTypes, getToolboxTableParameters } from '@/data-display/tables/toolbox-table/story-helper';
-import { useProxyValue } from '@/hooks/proxy-state';
+import { useProxyValue } from '@/hooks/use-proxy-state/use-proxy-state';
 import PButton from '@/inputs/buttons/button/PButton.vue';
 import PSelectStatus from '@/inputs/select-status/PSelectStatus.vue';
 

diff --git a/packages/mirinae/src/foundation/icons/config.ts b/packages/mirinae/src/foundation/icons/config.ts
@@ -1,6 +1,6 @@
 export const ANIMATION_TYPE = {
     spin: 'spin',
     reserveSpin: 'reserve-spin',
-};
+} as const;
 
 export type AnimationType = typeof ANIMATION_TYPE[keyof typeof ANIMATION_TYPE];
diff --git a/packages/mirinae/src/hooks/hookGuidelines.mdx b/packages/mirinae/src/hooks/hookGuidelines.mdx
@@ -0,0 +1,25 @@
+{/* hookGuidelines.mdx */}
+
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Hooks/Guidelines" />
+
+# Hook Guidelines
+
+This document outlines the guidelines for creating and using hooks within the design system, as well as for external usage, ensuring consistency and clarity across all hooks.
+<br/>
+
+## 1. Hook Argument - Options
+
+- **Single Argument**: Every hook accepts a single argument, which is always an object. This object is referred to as the "Hook Options."
+- **Naming Convention**: The interface for these options follows the naming rule `HookNameOptions`, where `HookName` is the name of the specific hook.
+  - **Example**: `UseTabOptions`
+<br/>
+
+## 2. Hook Returns
+
+- **Return Format**: Hooks always return a single object, called the "Hook Returns."
+- **Naming Convention**: The interface for the return object follows the naming rule `HookNameReturns`, where `HookName` is the name of the specific hook.
+  - **Example**: `UseTabReturns`
+<br/>
+
diff --git a/packages/mirinae/src/hooks/hookGuidelines.stories.ts b/packages/mirinae/src/hooks/hookGuidelines.stories.ts
@@ -0,0 +1,7 @@
+import type { Meta } from '@storybook/vue';
+
+const meta: Meta = {
+    title: 'Hooks/Guidelines',
+};
+
+export default meta;
diff --git a/packages/mirinae/src/hooks/index.ts b/packages/mirinae/src/hooks/index.ts
@@ -1,8 +1,8 @@
-export * from './context-menu-controller';
-export * from './context-menu-style';
-export * from './query-search';
-export * from './ignore-window-arrow-keydown-events';
-export * from './list-focus';
-export * from './proxy-state';
-export * from './select';
-export * from './tab';
+export * from './use-context-menu-controller/use-context-menu-controller';
+export * from './use-context-menu-style/use-context-menu-style';
+export * from './use-query-search/use-query-search';
+export * from './use-ignore-window-arrow-keydown-events/use-ignore-window-arrow-keydown-events';
+export * from './use-list-focus/use-list-focus';
+export * from './use-proxy-state/use-proxy-state';
+export * from './use-select/use-select';
+export * from './use-tab/use-tab';
diff --git a/packages/mirinae/src/hooks/tab/index.ts b/packages/mirinae/src/hooks/tab/index.ts
diff --git a/...t-menu-controller/__tests__/index.test.ts → ...t-menu-controller/__tests__/index.test.ts b/...t-menu-controller/__tests__/index.test.ts → ...t-menu-controller/__tests__/index.test.ts
@@ -3,8 +3,8 @@ import { defineComponent, ref } from 'vue';
 
 import { describe, expect } from 'vitest';
 
-import type { UseContextMenuControllerOptions } from '@/hooks/context-menu-controller';
-import { useContextMenuController } from '@/hooks/context-menu-controller';
+import type { UseContextMenuControllerOptions } from '@/hooks/use-context-menu-controller/use-context-menu-controller';
+import { useContextMenuController } from '@/hooks/use-context-menu-controller/use-context-menu-controller';
 import PContextMenu from '@/inputs/context-menu/PContextMenu.vue';
 import type { MenuItem } from '@/inputs/context-menu/type';
 

diff --git a/...xt-menu-controller/context-menu-attach.ts → ...enu-controller/use-context-menu-attach.ts b/...xt-menu-controller/context-menu-attach.ts → ...enu-controller/use-context-menu-attach.ts
diff --git a/...rc/hooks/context-menu-controller/index.ts → ...controller/use-context-menu-controller.ts b/...rc/hooks/context-menu-controller/index.ts → ...controller/use-context-menu-controller.ts
@@ -6,9 +6,9 @@ import {
 
 import { isEmpty } from 'lodash';
 
-import type { MenuAttachHandler } from '@/hooks/context-menu-controller/context-menu-attach';
-import { useContextMenuAttach } from '@/hooks/context-menu-controller/context-menu-attach';
-import { useContextMenuStyle } from '@/hooks/context-menu-style';
+import type { MenuAttachHandler } from '@/hooks/use-context-menu-controller/use-context-menu-attach';
+import { useContextMenuAttach } from '@/hooks/use-context-menu-controller/use-context-menu-attach';
+import { useContextMenuStyle } from '@/hooks/use-context-menu-style/use-context-menu-style';
 import type { MenuItem } from '@/inputs/context-menu/type';
 import { getTextHighlightRegex } from '@/utils/helpers';
 

diff --git a/...nae/src/hooks/context-menu-style/index.ts → ...text-menu-style/use-context-menu-style.ts b/...nae/src/hooks/context-menu-style/index.ts → ...text-menu-style/use-context-menu-style.ts
diff --git a/...nore-window-arrow-keydown-events/index.ts → ...use-ignore-window-arrow-keydown-events.ts b/...nore-window-arrow-keydown-events/index.ts → ...use-ignore-window-arrow-keydown-events.ts
diff --git a/...ges/mirinae/src/hooks/list-focus/index.ts → ...rc/hooks/use-list-focus/use-list-focus.ts b/...ges/mirinae/src/hooks/list-focus/index.ts → ...rc/hooks/use-list-focus/use-list-focus.ts
diff --git a/...es/mirinae/src/hooks/proxy-state/index.ts → .../hooks/use-proxy-state/use-proxy-state.ts b/...es/mirinae/src/hooks/proxy-state/index.ts → .../hooks/use-proxy-state/use-proxy-state.ts
diff --git a/...s/mirinae/src/hooks/query-search/index.ts → ...ooks/use-query-search/use-query-search.ts b/...s/mirinae/src/hooks/query-search/index.ts → ...ooks/use-query-search/use-query-search.ts
diff --git a/packages/mirinae/src/hooks/select/index.ts → ...irinae/src/hooks/use-select/use-select.ts b/packages/mirinae/src/hooks/select/index.ts → ...irinae/src/hooks/use-select/use-select.ts
@@ -5,21 +5,13 @@ import {
 
 import { pull, remove } from 'lodash';
 
-export interface SelectProps {
-    value?: any;
-    selected?: any | any[];
-    disabled?: boolean;
-    predicate?: Predicate;
-    multiSelectable?: boolean;
-}
-
-interface Predicate {
+export interface SelectionPredicate {
     (value: any, current: any): boolean;
 }
-interface SelectStateArgs {
+interface UseSelectOptions {
     value?: ComputedRef<any> | any;
     selected?: ComputedRef<any | any[]> | any | any[];
-    predicate?: ComputedRef<Predicate|undefined> | Predicate;
+    predicate?: ComputedRef<SelectionPredicate|undefined> | SelectionPredicate;
     disabled?: ComputedRef<boolean|undefined> | boolean;
     multiSelectable?: ComputedRef<boolean|undefined> | boolean;
 }
@@ -28,7 +20,7 @@ interface SelectState {
     isSelected: boolean;
 }
 
-const getSelectState = (state: UnwrapRef<SelectStateArgs>) => reactive({
+const getSelectState = (state: UnwrapRef<UseSelectOptions>) => reactive({
     isSelected: computed<boolean>(() => {
         if (Array.isArray(state.selected)) {
             if (state.predicate) {
@@ -41,7 +33,7 @@ const getSelectState = (state: UnwrapRef<SelectStateArgs>) => reactive({
         return state.selected === state.value;
     }),
 });
-const getSingleSelected = (state: UnwrapRef<SelectStateArgs>) => {
+const getSingleSelected = (state: UnwrapRef<UseSelectOptions>) => {
     if (state.disabled) return undefined;
 
     let result: any;
@@ -53,7 +45,7 @@ const getSingleSelected = (state: UnwrapRef<SelectStateArgs>) => {
 
     return result;
 };
-const getMultiSelected = (state: UnwrapRef<SelectStateArgs>, selectState: SelectState) => {
+const getMultiSelected = (state: UnwrapRef<UseSelectOptions>, selectState: SelectState) => {
     if (state.disabled) return undefined;
 
     let result: any;
@@ -78,7 +70,7 @@ const getMultiSelected = (state: UnwrapRef<SelectStateArgs>, selectState: Select
 
 export const useMultiSelect = ({
     value, selected, predicate, disabled,
-}: SelectStateArgs) => {
+}: UseSelectOptions) => {
     const state = reactive({
         value, selected, predicate, disabled,
     });
@@ -94,7 +86,7 @@ export const useMultiSelect = ({
 
 export const useSingleSelect = ({
     value, selected, predicate, disabled,
-}: SelectStateArgs) => {
+}: UseSelectOptions) => {
     const state = reactive({
         value, selected, predicate, disabled,
     });
@@ -110,7 +102,7 @@ export const useSingleSelect = ({
 
 export const useSelect = ({
     value, selected, predicate, disabled, multiSelectable,
-}: SelectStateArgs) => {
+}: UseSelectOptions) => {
     const state = reactive({
         value, selected, predicate, disabled, multiSelectable,
     });

diff --git a/packages/mirinae/src/hooks/use-tab/type.ts b/packages/mirinae/src/hooks/use-tab/type.ts
@@ -0,0 +1,36 @@
+import type { ComputedRef, Ref } from 'vue';
+
+import type { TranslateResult } from 'vue-i18n';
+
+/* Generic type T represents the additional properties that can be added to the tab item. */
+export type TabItem<T extends object> = {
+    /* name: The identifier for the tab. */
+    name: string;
+    /* label: The display label for the tab. This supports localized string or other message formats. */
+    label?: TranslateResult;
+    /* keepAlive: A flag indicating if the tab should be preserved when switching to other tabs. */
+    keepAlive?: boolean;
+    /* subItems: An array containing nested `TabItem` elements for hierarchical tab structures. */
+    subItems?: Array<string|TabItem<T>>;
+} & T;
+
+export interface UseTabOptions<T extends object> {
+    /* tabs: An array containing tab information. Each tab can be a `string` or an object that follows the `TabItem` structure. */
+    tabs: Ref<Array<string|TabItem<T>>> | Array<string|TabItem<T>>;
+    /* activeTab: Represents the currently active tab. */
+    activeTab: Ref<string> | string;
+    /* defaultItem: An object that provides default properties for all generated tabs.
+    This ensures consistency across tab items when only partial information is provided. */
+    defaultItem?: T;
+}
+
+export interface UseTabReturns<T extends object> {
+    /* tabItems: An array containing the resolved tab items based on the `tabs` input and the optional `defaultItem`. It provides a processed list of tabs with consistent structure. */
+    tabItems: ComputedRef<TabItem<T>[]>;
+    /* keepAliveTabNames: An array listing the names of tabs marked to be kept alive (`keepAlive: true`.) */
+    keepAliveTabNames: ComputedRef<string[]>;
+    /* nonKeepAliveTabNames: An array listing the names of tabs not set to be kept alive. */
+    nonKeepAliveTabNames: ComputedRef<string[]>;
+    /* currentTabItem: Represents the currently active tab item based on the `activeTab` input. If no matching tab is found, it returns `undefined`. */
+    currentTabItem: ComputedRef<TabItem<T>|undefined>;
+}