feat: manual (#191)

* feat: add markdown render deps

* feat: add manual route

* feat: example toc

* feat: add highlight js dependency

* feat: add view page

* feat: add translations for property and manual in English and Thai

* feat: enhance drawer menu with internationalization support and manual section

* feat: add conditional internationalization for sub-menu labels

* feat: add video support

* refactor: add stores and type

* fix: wrong path

* feat: improve layout structure and enhance scroll functionality in ViewPage

* fix: scroll not working

* chore: change variable name

* feat: show sub tile of manual

* feat: add translation for 'Table of Contents' in English and Thai

* feat: enhance layout and add conditional rendering for Table of Contents in ViewPage

* chore: clean

* refactor: use expansion

* refactor: show icon

* refactor: spacing

---------

Co-authored-by: Methapon2001 <61303214+Methapon2001@users.noreply.github.com>
Co-authored-by: Thanaphon Frappet <thanaphon@frappet.com>

src/i18n/eng.ts

@@ -150,6 +150,7 @@ export default {
     notIncluded: 'Not Included',
     dueDate: 'Due date',
     year: 'year',
+    tableOfContent: 'Table of Contents',
   },
 
   menu: {
@@ -194,6 +195,7 @@ export default {
       personnel: 'Personnel',
       productService: 'Product and Service',
       workflow: 'Workflow',
+      property: 'Property',
       customer: 'Customer',
       mainData: 'Main Data',
       agencies: 'Agencies',
@@ -240,6 +242,11 @@ export default {
       mode: 'Mode',
       addSignature: 'Add Signature',
     },
+
+    manual: {
+      title: 'Manual',
+      usage: 'การใช้งาน',
+    },
   },
 
   noti: {

src/i18n/tha.ts

@@ -150,6 +150,7 @@ export default {
     notIncluded: 'ไม่รวม',
     dueDate: 'วันครบกำหนด',
     year: 'ปี',
+    tableOfContent: 'สารบัญ',
   },
 
   menu: {
@@ -241,6 +242,11 @@ export default {
       mode: 'โหมด',
       addSignature: 'เพิ่มลายเซ็น',
     },
+
+    manual: {
+      title: 'คู่มือ',
+      usage: 'การใช้งาน',
+    },
   },
 
   noti: {

src/layouts/DrawerComponent.vue

@@ -6,6 +6,7 @@ import { Icon } from '@iconify/vue';
 import useMyBranch from 'stores/my-branch';
 import { getUserId, getRole } from 'src/services/keycloak';
 import { useQuasar } from 'quasar';
+import { useI18n } from 'vue-i18n';
 
 type Menu = {
   label: string;
@@ -14,11 +15,13 @@ type Menu = {
   hidden?: boolean;
   disabled?: boolean;
   isax?: boolean;
+  noI18n?: boolean;
   children?: Menu[];
 };
 
 const router = useRouter();
 const $q = useQuasar();
+const { locale } = useI18n();
 
 const userBranch = useMyBranch();
 const { currentMyBranch } = storeToRefs(userBranch);
@@ -58,39 +61,7 @@ function branchSetting() {
   //TODO: click setting (cog icon) on drawer menu
 }
 
-watch(
-  () => currentPath.value,
-  () => {
-    if (currentPath.value === '/') {
-      menuActive.value.fill(false);
-      menuActive.value[0] = true;
-    } else reActiveMenu();
-  },
-);
-
-watch(
-  () => props.mini,
-  () => {
-    if (props.mini) {
-      reActiveMenu();
-    }
-  },
-);
-
-onMounted(async () => {
-  const uid = getUserId();
-
-  role.value = getRole();
-
-  if (!uid) return;
-
-  if (role.value.includes('system')) {
-    const result = await userBranch.fetchListOptionBranch();
-    if (result && result.total > 0) currentMyBranch.value = result.result[0];
-  }
-  const result = await userBranch.fetchListMyBranch(uid);
-  if (result && result.total > 0) currentMyBranch.value = result.result[0];
-
+function initMenu() {
   menuData.value = [
     {
       label: 'menu.manage',
@@ -185,7 +156,61 @@ onMounted(async () => {
         { label: 'dashboard', route: '/dash-board' },
       ],
     },
+
+    {
+      label: 'menu.manual',
+      icon: 'mdi-book-open-variant-outline',
+      children: [
+        {
+          label: 'usage',
+          route: `/manual`,
+        },
+      ],
+    },
   ];
+}
+
+watch(
+  () => currentPath.value,
+  () => {
+    if (currentPath.value === '/') {
+      menuActive.value.fill(false);
+      menuActive.value[0] = true;
+    } else reActiveMenu();
+  },
+);
+
+watch(
+  () => props.mini,
+  () => {
+    if (props.mini) {
+      reActiveMenu();
+    }
+  },
+);
+
+watch(
+  () => locale.value,
+  () => {
+    initMenu();
+  },
+);
+
+onMounted(async () => {
+  const uid = getUserId();
+
+  role.value = getRole();
+
+  if (!uid) return;
+
+  if (role.value.includes('system')) {
+    const result = await userBranch.fetchListOptionBranch();
+    if (result && result.total > 0) currentMyBranch.value = result.result[0];
+  }
+  const result = await userBranch.fetchListMyBranch(uid);
+  if (result && result.total > 0) currentMyBranch.value = result.result[0];
+
+  initMenu();
 
   menuActive.value = menuData.value.map(() => false);
 
@@ -266,10 +291,10 @@ onMounted(async () => {
                   style="white-space: nowrap"
                   :style="!menuActive[i] && `color: var(--foreground)`"
                 >
-                  {{ $t(`${menu.label}.title`) }}
+                  {{ menu.noI18n ? menu.label : $t(`${menu.label}.title`) }}
                 </span>
                 <q-tooltip :delay="500">
-                  {{ $t(`${menu.label}.title`) }}
+                  {{ menu.noI18n ? menu.label : $t(`${menu.label}.title`) }}
                 </q-tooltip>
 
                 <q-menu
@@ -298,7 +323,11 @@ onMounted(async () => {
                         :id="`sub-menu-${sub.label}`"
                       >
                         <span style="white-space: nowrap">
-                          {{ $t(`${menu.label}.${sub.label}`) }}
+                          {{
+                            sub.noI18n
+                              ? sub.label
+                              : $t(`${menu.label}.${sub.label}`)
+                          }}
                         </span>
                       </q-item>
                     </template>
@@ -320,12 +349,16 @@ onMounted(async () => {
                   <nav
                     class="row items-center no-wrap"
                     :class="{
-                      active: currentPath === sub.route,
+                      active: sub.route && currentPath.includes(sub.route),
                       disabled: sub.disabled,
                     }"
                   >
                     <span class="q-px-md" style="white-space: nowrap">
-                      {{ $t(`${menu.label}.${sub.label}`) }}
+                      {{
+                        sub.noI18n
+                          ? sub.label
+                          : $t(`${menu.label}.${sub.label}`)
+                      }}
                     </span>
                   </nav>
                 </div>

src/pages/00_manual/MainPage.vue

@@ -0,0 +1,81 @@
+<script setup lang="ts">
+// NOTE: Library
+import { storeToRefs } from 'pinia';
+import { onMounted } from 'vue';
+
+// NOTE:  Components
+
+// NOTE: Stores & Type
+
+import { useManualStore } from 'src/stores/manual';
+import { useNavigator } from 'src/stores/navigator';
+import { Icon } from '@iconify/vue/dist/iconify.js';
+
+// NOTE: Variable
+const manualStore = useManualStore();
+const navigatorStore = useNavigator();
+const { dataManual } = storeToRefs(manualStore);
+
+async function fetchManual() {
+  const res = await manualStore.getManual();
+  dataManual.value = res ? res : [];
+}
+
+onMounted(async () => {
+  navigatorStore.current.title = 'menu.manual.title';
+  navigatorStore.current.path = [{ text: '' }];
+  await fetchManual();
+});
+</script>
+
+<template>
+  <div
+    class="column full-height no-wrap surface-1 rounded bordered overflow-hidden q-pa-sm"
+  >
+    <section class="scroll q-gutter-y-sm">
+      <q-expansion-item
+        v-for="v in dataManual"
+        :content-inset-level="0.5"
+        class="rounded overflow-hidden bordered"
+        dense
+      >
+        <template #header>
+          <div class="row items-center full-width">
+            <Icon
+              v-if="!!v.icon"
+              :icon="v.icon"
+              :color="'var(--brand-1)'"
+              class="q-mr-sm"
+            />
+            {{ $i18n.locale === 'eng' ? v.labelEN : v.label }}
+          </div>
+        </template>
+
+        <q-item
+          v-for="x in v.page"
+          clickable
+          dense
+          class="dot items-center rounded q-my-xs"
+          :to="`/manual/${v.category}/${x.name}`"
+        >
+          <Icon
+            v-if="!!x.icon"
+            :icon="x.icon"
+            width="16px"
+            :color="'var(--brand-1)'"
+            class="q-mr-sm"
+          />
+          {{ $i18n.locale === 'eng' ? x.labelEN : x.label }}
+        </q-item>
+      </q-expansion-item>
+    </section>
+  </div>
+</template>
+
+<style scoped>
+.dot::before {
+  content: '•';
+  margin-right: 8px;
+  font-size: 1.2em;
+}
+</style>

src/pages/00_manual/ViewPage.vue

@@ -0,0 +1,288 @@
+<script setup lang="ts">
+import 'highlight.js/styles/magula.min.css';
+import MarkdownIt from 'markdown-it';
+import hljs from 'highlight.js';
+import { nextTick, onMounted, onUnmounted, ref } from 'vue';
+import { useRoute } from 'vue-router';
+
+// @ts-expect-error
+import mditFigureWithPCaption from 'markdown-it-image-figures';
+// @ts-expect-error
+import mditMedia from 'markdown-it-html5-media';
+import mditAnchor from 'markdown-it-anchor';
+import mditHighlight from 'markdown-it-highlightjs';
+import { initLang, initTheme } from 'src/utils/ui';
+import { baseUrl } from 'src/stores/utils';
+
+import { useManualStore } from 'src/stores/manual';
+
+const ROUTE = useRoute();
+const manualStore = useManualStore();
+
+const md = new MarkdownIt()
+  .use(mditAnchor)
+  .use(mditMedia.html5Media)
+  .use(mditHighlight, { hljs })
+  .use(mditFigureWithPCaption, { figcaption: 'alt' });
+
+const wrapper = ref<HTMLDivElement>();
+const category = ref('');
+const page = ref('');
+const content = ref('');
+const contentParsed = ref<ReturnType<typeof md.parse>>();
+const contentViewing = ref('');
+const toc = ref(true);
+
+onMounted(async () => {
+  if (typeof ROUTE.params['category'] === 'string') {
+    category.value = ROUTE.params['category'];
+  }
+
+  if (typeof ROUTE.params['page'] === 'string') {
+    page.value = ROUTE.params['page'];
+  }
+
+  initLang();
+  initTheme();
+
+  await getContent();
+
+  window.addEventListener('scroll', onScroll);
+  window.addEventListener('resize', onResize);
+});
+
+onUnmounted(() => {
+  window.removeEventListener('scroll', onScroll);
+  window.removeEventListener('resize', onResize);
+});
+
+async function getContent() {
+  if (!category.value || !page.value) return;
+  const res = await manualStore.getManualByPage({
+    category: category.value,
+    pageName: page.value,
+  });
+  if (res && res.ok) {
+    const text = await res.text();
+    content.value = text;
+    contentParsed.value = md.parse(text, {});
+  }
+}
+
+function onScroll() {
+  let current = '';
+  document.querySelectorAll<HTMLElement>('h2,h3').forEach((v) => {
+    if (
+      window.top &&
+      window.top.scrollY + window.innerHeight / 2 > v.offsetTop
+    ) {
+      current = v.id;
+    }
+  });
+  contentViewing.value = current;
+}
+
+function onResize() {
+  if (window.innerWidth > 1024) {
+    toc.value = true;
+  }
+}
+
+async function scrollTo(id: string) {
+  const pos = document.getElementById(id)?.offsetTop;
+  await nextTick(() => {
+    if (window.innerWidth < 1024) toc.value = false;
+  });
+  if (pos) {
+    wrapper.value?.scrollTo({
+      top: pos,
+      behavior: 'smooth',
+    });
+  }
+}
+</script>
+
+<template>
+  <main
+    class="full-height q-gutter-sm"
+    :class="{ 'row reverse': $q.screen.gt.xs, column: $q.screen.xs }"
+  >
+    <section
+      v-if="toc"
+      class="surface-1 rounded col-md-3 col-12 scroll full-height"
+    >
+      <q-list padding>
+        <template v-for="(token, idx) in contentParsed" :key="idx">
+          <q-item
+            v-if="token.tag === 'h2' && token.type === 'heading_open'"
+            class="tabNative"
+            active-class="text-blue-7 active-item text-weight-medium tabActive"
+            :active="contentViewing === token.attrGet('id')"
+            @click="scrollTo(token.attrGet('id') || '')"
+            clickable
+            v-ripple
+            dense
+            exact
+          >
+            <q-item-section>
+              <q-item-label>
+                <q-icon size="11px" name="mdi-circle-medium" />
+                <span class="q-pl-xs">
+                  {{ contentParsed?.[idx + 1].content }}
+                </span>
+              </q-item-label>
+            </q-item-section>
+          </q-item>
+          <q-item
+            v-if="token.tag === 'h3' && token.type === 'heading_open'"
+            class="tabNative child-tab"
+            active-class="text-blue-7 active-item text-weight-medium tabActive"
+            :active="contentViewing === token.attrGet('id')"
+            @click="scrollTo(token.attrGet('id') || '')"
+            clickable
+            v-ripple
+            dense
+            exact
+          >
+            <q-item-section>
+              <q-item-label>
+                <span class="q-pl-xl">
+                  {{ contentParsed?.[idx + 1].content }}
+                </span>
+              </q-item-label>
+            </q-item-section>
+          </q-item>
+        </template>
+      </q-list>
+    </section>
+
+    <section v-if="!toc && $q.screen.xs">
+      <q-btn
+        dense
+        class="full-width text-capitalize"
+        flat
+        @click="toc = true"
+        color="info"
+      >
+        {{ $t('general.tableOfContent') }}
+      </q-btn>
+    </section>
+
+    <section
+      v-if="content || (!toc && $q.screen.xs)"
+      ref="wrapper"
+      class="markdown col scroll full-height rounded"
+    >
+      <div
+        style="
+          width: 100%;
+          flex: 1;
+          border-radius: 0.5rem;
+          border: 1px solid var(--border-color);
+          padding: 1rem;
+        "
+        class="surface-1"
+        v-html="
+          md.render(
+            content.replaceAll(
+              'assets/',
+              `${baseUrl}/manual/${category}/assets/`,
+            ),
+          )
+        "
+      ></div>
+    </section>
+  </main>
+</template>
+
+<style lang="css" scoped>
+.toc {
+  top: 4rem;
+}
+
+.active {
+  color: red;
+}
+
+.markdown :deep(:where(h1, h2, h3, h4, h5, h6)) {
+  line-height: 1.5;
+  padding-block: 1rem !important;
+}
+
+.markdown :deep(blockquote) {
+  background-color: var(--surface-2);
+  border-radius: 8px;
+  padding: 8px;
+  margin-bottom: 1rem;
+}
+
+.markdown :deep(blockquote > p:last-child) {
+  margin-bottom: 0;
+}
+
+.markdown :deep(img) {
+  vertical-align: middle;
+}
+
+.markdown :deep(p img) {
+  padding-inline: 0.25rem;
+}
+
+.markdown :deep(figure) {
+  margin: 0;
+  text-align: center;
+  padding: 1rem;
+  width: 100%;
+}
+
+.markdown :deep(figure img) {
+  max-width: 90%;
+}
+
+.markdown :deep(p:has(img:only-child) img) {
+  max-width: 100%;
+}
+
+.markdown :deep(h1) {
+  text-align: left;
+  margin-top: -1rem;
+  margin-inline: -1rem;
+  font-size: 24px;
+  font-weight: 700;
+  background-color: var(--surface-2);
+  border-radius: 8px 8px 0px 0px;
+  padding: 0px 16px;
+}
+
+.markdown :deep(.hljs) {
+  border-radius: 8px;
+}
+
+.markdown :deep(a) {
+  color: hsla(var(--info-bg));
+}
+
+.markdown :deep(figcaption) {
+  text-align: center;
+}
+
+.markdown :deep(h2) {
+  text-align: left;
+  margin-block: 0;
+  font-size: 18px;
+  font-weight: 600;
+  padding: 0px 16px;
+}
+
+.markdown :deep(h3) {
+  text-align: left;
+  margin-block: 0;
+  font-size: 16px;
+  font-weight: 600;
+  padding: 0px 16px;
+}
+
+.markdown :deep(video) {
+  width: 100%;
+}
+</style>

src/router/routes.ts

@@ -145,6 +145,16 @@ const routes: RouteRecordRaw[] = [
         name: 'Notification',
         component: () => import('pages/00_notification/MainPage.vue'),
       },
+      {
+        path: '/manual',
+        name: 'Manual',
+        component: () => import('pages/00_manual/MainPage.vue'),
+      },
+      {
+        path: '/manual/:category/:page',
+        name: 'ManualView',
+        component: () => import('pages/00_manual/ViewPage.vue'),
+      },
     ],
   },
 
@@ -223,7 +233,6 @@ const routes: RouteRecordRaw[] = [
     name: 'DebitNoteDocumentView',
     component: () => import('pages/12_debit-note/document-view/MainPage.vue'),
   },
-
   // Always leave this as last one,
   // but you can also remove it
   {

src/stores/manual/index.ts

@@ -0,0 +1,40 @@
+import { ref } from 'vue';
+import { defineStore } from 'pinia';
+import { api } from 'src/boot/axios';
+import { getToken } from 'src/services/keycloak';
+import { Manual } from './types';
+import { baseUrl } from '../utils';
+
+const ENDPOINT = 'manual';
+
+export async function getManual() {
+  const res = await api.get<Manual[]>(`/${ENDPOINT}`);
+  if (res.status < 400) {
+    return res.data;
+  }
+  return null;
+}
+
+export async function getManualByPage(opt: {
+  category: string;
+  pageName: string;
+}) {
+  const res = await fetch(
+    `${baseUrl}/${ENDPOINT}/${opt.category}/page/${opt.pageName}`,
+  );
+  if (res.status < 400) {
+    return res;
+  }
+  return null;
+}
+
+export const useManualStore = defineStore('manual-store', () => {
+  const dataManual = ref<Manual[]>([]);
+
+  return {
+    getManual,
+    getManualByPage,
+
+    dataManual,
+  };
+});

src/stores/manual/types.ts

@@ -0,0 +1,14 @@
+export type Manual = {
+  label: string;
+  labelEN: string;
+  category: string;
+  icon?: string;
+  page: Page[];
+};
+
+type Page = {
+  name: string;
+  label: string;
+  labelEN: string;
+  icon?: string;
+};