feat(theme): add custom components

.eslintrc.cjs

@@ -19,7 +19,6 @@ module.exports = {
     "no-empty": "off",
     "prefer-const": "off",
     "no-fallthrough": "off",
-    quotes: "double"
   },
   overrides: [
     {

docs/.vitepress/config.mts

@@ -1,4 +1,5 @@
 import {defineConfig} from "vitepress";
+import {apiAnchor} from "./theme/markdown/api-anchor/api-anchor.js";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -27,6 +28,8 @@ export default defineConfig({
   ],
 
   themeConfig: {
+    apiUrl: "https://tsed.io/api.json",
+    apiRedirectUrl: "https://api-docs.tsed.io",
     search: {
       provider: "algolia",
       options: {
@@ -47,7 +50,7 @@ export default defineConfig({
               {text: "What is Ts.ED?", link: "/introduction/what-is-tsed"},
               {text: "Capabilities", link: "/introduction/capabilities"},
               {text: "Installation", link: "/introduction/getting-started"},
-              {text: "Create your first controller", link: "/introduction/create-your-first-controller"},
+              {text: "Create your first controller", link: "/introduction/create-your-first-controller"}
             ]
           },
           {
@@ -259,13 +262,12 @@ export default defineConfig({
       "/introduction/": [
         {
           text: "Introduction",
-          items:
-            [
-              {text: "What is Ts.ED?", link: "/introduction/what-is-tsed"},
-              {text: "Capabilities", link: "/introduction/capabilities"},
-              {text: "Installation", link: "/introduction/getting-started"},
-              {text: "Create your first controller", link: "/introduction/create-your-first-controller"}
-            ]
+          items: [
+            {text: "What is Ts.ED?", link: "/introduction/what-is-tsed"},
+            {text: "Capabilities", link: "/introduction/capabilities"},
+            {text: "Installation", link: "/introduction/getting-started"},
+            {text: "Create your first controller", link: "/introduction/create-your-first-controller"}
+          ]
         },
         {
           text: "Migration",
@@ -278,13 +280,12 @@ export default defineConfig({
       "/docs/": [
         {
           text: "Configuration",
-          items:
-            [
-              {text: "Options", link: "/docs/configuration/"},
-              {text: "Load config from file", link: "/docs/configuration/load-configuration-from-file"},
-              {text: "Express.js", link: "/docs/configuration/express"},
-              {text: "Koa.js", link: "/docs/configuration/koa"}
-            ]
+          items: [
+            {text: "Options", link: "/docs/configuration/"},
+            {text: "Load config from file", link: "/docs/configuration/load-configuration-from-file"},
+            {text: "Express.js", link: "/docs/configuration/express"},
+            {text: "Koa.js", link: "/docs/configuration/koa"}
+          ]
         },
         {
           text: "Controllers",
@@ -306,6 +307,9 @@ export default defineConfig({
   markdown: {
     image: {
       lazyLoading: true
+    },
+    config: (md) => {
+      md.use(apiAnchor);
     }
   }
 });

docs/.vitepress/theme/atoms/api-icon/ApiIcon.css

@@ -0,0 +1,73 @@
+[data-name="ApiIcon"] {
+  @apply hidden font-source rounded-xs text-white text-xxs text-center mr-2;
+  width: 1rem;
+  height: 1rem;
+  line-height: 1.1rem;
+  box-shadow: 0 1px 2px rgba(10, 16, 20, 0.24);
+
+  &[data-type="class"] {
+    @apply bg-blue-900 inline-block;
+
+    &:before {
+      content: "C";
+    }
+  }
+
+  &[data-type="interface"] {
+    @apply bg-teal-500 inline-block;
+
+    &:before {
+      content: "I";
+    }
+  }
+
+  &[data-type="decorator"] {
+    @apply bg-blue-600 inline-block;
+    line-height: 1rem;
+
+    &:before {
+      content: "@";
+    }
+  }
+
+  &[data-type="type"] {
+    @apply bg-emerald-300 inline-block;
+
+    &:before {
+      content: "T";
+    }
+  }
+
+  &[data-type="service"],
+  &[data-type="provider"] {
+    @apply bg-pink-600 inline-block;
+
+    &:before {
+      content: "S";
+    }
+  }
+
+  &[data-type="function"] {
+    @apply bg-emerald-600 inline-block;
+
+    &:before {
+      content: "F";
+    }
+  }
+
+  &[data-type="const"] {
+    @apply bg-gray-800 inline-block;
+
+    &:before {
+      content: "K";
+    }
+  }
+
+  &[data-type="enum"] {
+    @apply bg-amber-600 inline-block;
+
+    &:before {
+      content: "E";
+    }
+  }
+}

docs/.vitepress/theme/atoms/api-icon/ApiIcon.spec.ts

@@ -0,0 +1,22 @@
+import ApiIcon from "./ApiIcon.vue";
+import {render, screen} from "@testing-library/vue";
+
+describe("<ApiIcon />", () => {
+  it("should render the component", () => {
+    render(ApiIcon);
+
+    expect(screen.getByTestId("ApiIcon")).toBeInTheDocument();
+    expect(screen.getByTestId("ApiIcon")).toHaveAttribute("data-type", "class");
+  });
+
+  it("should render the component", () => {
+    render(ApiIcon, {
+      props: {
+        type: "enum"
+      }
+    });
+
+    expect(screen.getByTestId("ApiIcon")).toBeInTheDocument();
+    expect(screen.getByTestId("ApiIcon")).toHaveAttribute("data-type", "enum");
+  });
+});

docs/.vitepress/theme/atoms/api-icon/ApiIcon.stories.ts

@@ -0,0 +1,33 @@
+import type {Meta, StoryObj} from "@storybook/vue3";
+import ApiIcon from "./ApiIcon.vue";
+
+// More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+const meta = {
+  title: "ApiIcon",
+  component: ApiIcon,
+  // This component will have an automatically generated docsPage entry: https://storybook.js.org/docs/writing-docs/autodocs
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered"
+  },
+  argTypes: {
+    type: {
+      control: "select",
+      options: ["interface", "decorator", "class", "type", "enum", "const", "function", "service"]
+    }
+  },
+  args: {
+    type: "class"
+  } // default value,
+} satisfies Meta<typeof ApiIcon>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+/*
+ *👇 Render functions are a framework specific feature to allow you control on how the component renders.
+ * See https://storybook.js.org/docs/api/csf
+ * to learn how to use render functions.
+ */
+export const Default: Story = {
+  args: {}
+};

docs/.vitepress/theme/atoms/api-icon/ApiIcon.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type {ApiSymbolType} from "../../composables/api/interfaces/Api.js";
+import "./ApiIcon.css";
+
+interface Props {
+  type: ApiSymbolType;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  type: "class"
+});
+</script>
+<template>
+  <span data-name="ApiIcon" :data-type="props.type" data-testid="ApiIcon" />
+</template>

docs/.vitepress/theme/composables/api/__mocks__/useApiConfig.ts

@@ -0,0 +1,13 @@
+console.log("====> useApiConfig.ts <====");
+
+export function useApiConfig() {
+  const ref = {
+    apiUrl: "https://tsed.io/api.json",
+    apiRedirectUrl: "https://api-docs.tsed.io",
+    value: undefined
+  };
+
+  ref.value = ref;
+
+  return ref;
+}

docs/.vitepress/theme/composables/api/interfaces/Api.ts

@@ -0,0 +1,26 @@
+export interface ApiConfig {
+  apiUrl: string;
+  apiRedirectUrl: string;
+}
+
+export type ApiSymbolType = "interface" | "decorator" | "class" | "type" | "enum" | "const" | "function" | "service";
+export type ApiSymbolStatus = "stable" | "deprecated" | "experimental" | "private" | "public";
+export interface ApiSymbol {
+  path?: string;
+  symbolName: string;
+  symbolType: ApiSymbolType;
+  status: ApiSymbolStatus[];
+  module: string;
+  symbolLabel: string;
+  symbolCode: string;
+}
+
+export interface ApiResponse {
+  modules: Record<
+    string,
+    {
+      name?: string;
+      symbols: ApiSymbol[];
+    }
+  >;
+}

docs/.vitepress/theme/composables/api/mapSymbols.spec.ts

@@ -0,0 +1,48 @@
+import {mapSymbols} from "./mapSymbols.js";
+import type {ApiResponse} from "./interfaces/Api.js";
+
+describe("Map Symbols", () => {
+  it("should map symbols", () => {
+    const data = {
+      modules: {
+        "@tsed/core": {
+          symbols: [
+            {
+              path: "/api/core/types/decorators/Configurable",
+              symbolName: "Configurable",
+              module: "@tsed/core",
+              symbolType: "decorator",
+              symbolLabel: "Decorator",
+              symbolCode: "@",
+              status: ["stable"]
+            }
+          ]
+        }
+      }
+    } satisfies ApiResponse;
+
+    const result = mapSymbols(data);
+
+    expect(result).toMatchInlineSnapshot(`
+      [
+        {
+          "labels": [
+            "stable",
+          ],
+          "module": "@tsed/core",
+          "name": "Configurable",
+          "path": "/api/core/types/decorators/Configurable",
+          "status": [
+            "stable",
+          ],
+          "symbolCode": "@",
+          "symbolLabel": "Decorator",
+          "symbolName": "Configurable",
+          "symbolType": "decorator",
+          "tags": "stable",
+          "type": "decorator",
+        },
+      ]
+    `);
+  });
+});

docs/.vitepress/theme/composables/api/mapSymbols.ts

@@ -0,0 +1,19 @@
+import type {ApiResponse} from "./interfaces/Api";
+
+export function mapSymbols(items: ApiResponse) {
+  return Object.values(items.modules).reduce((symbols: any[], current) => {
+    return [
+      ...symbols,
+      ...current.symbols.map((symbol) => {
+        return {
+          ...symbol,
+          // additional properties for the Api search tools
+          name: symbol.symbolName,
+          type: symbol.symbolType,
+          tags: symbol.status.join(","),
+          labels: symbol.status
+        };
+      })
+    ];
+  }, []);
+}

docs/.vitepress/theme/composables/api/useApiConfig.spec.ts

@@ -0,0 +1,14 @@
+import {useApiConfig} from "./useApiConfig.js";
+
+describe("useApiConfig", () => {
+  it("should return the correct api config", () => {
+    const ref: any = {
+      apiRedirectUrl: "https://api-docs.tsed.io",
+      apiUrl: "https://tsed.io/api.json",
+      value: undefined
+    };
+    ref.value = ref;
+
+    expect(useApiConfig()).toEqual(ref);
+  });
+});

docs/.vitepress/theme/composables/api/useApiConfig.ts

@@ -0,0 +1,9 @@
+import {useData} from "vitepress/client";
+import type {DefaultTheme} from "vitepress";
+import type {ApiConfig} from "./interfaces/Api";
+
+export function useApiConfig() {
+  const {theme} = useData<DefaultTheme.Config & ApiConfig>();
+
+  return theme;
+}

docs/.vitepress/theme/composables/api/useApiContent.spec.ts

@@ -0,0 +1,34 @@
+import {beforeEach} from "vitest";
+import {useFavicon, useFetch} from "@vueuse/core";
+import {useApiContent} from "./useApiContent.js";
+
+vi.mock("@vueuse/core");
+
+describe("useApiContent", () => {
+  beforeEach(() => {
+    vi.mocked(useFetch).mockReturnValue({
+      get: vi.fn().mockReturnThis(),
+      json: vi.fn().mockReturnValue({
+        data: {
+          value: {
+            apiRedirectUrl: "https://api-docs.tsed.io",
+            apiUrl: "https://tsed.io/api.json"
+          }
+        }
+      })
+    } as any);
+  });
+  it("should fetch the Api.json content", () => {
+    const result = useApiContent();
+
+    expect(result).toEqual({
+      data: {
+        value: {
+          apiRedirectUrl: "https://api-docs.tsed.io",
+          apiUrl: "https://tsed.io/api.json"
+        }
+      }
+    });
+    expect(useFetch).toHaveBeenCalledWith("https://tsed.io/api.json");
+  });
+});