Docs and cypress

.github/workflows/deploy-docs.yml

@@ -0,0 +1,59 @@
+name: Deploy Docs to Pages
+
+on:
+  # Runs on pushes targeting the `docs` branch and `main` branch.
+  push:
+    branches: ["docs", "main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+# concurrency:
+#   group: pages
+#   cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18.17.1'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build with VitePress
+        run: |
+          npm run docs:build
+          touch docs/.vitepress/dist/.nojekyll
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to Github Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -22,3 +22,13 @@ dist-ssr
 *.njsproj
 *.sln
 *.sw?
+
+# API Documentation
+docs/.vitepress/dist
+docs/.vitepress/cache
+docs/components
+
+# Cypress Test
+cypress/screenshots/
+cypress/reports/
+cypress/videos

README.md

@@ -67,3 +67,15 @@ This template should help get you started developing with Vue 3 in Vite. The tem
 ## Recommended IDE Setup
 
 - [VS Code](https://code.visualstudio.com/) + [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (previously Volar) and disable Vetur
+
+
+## API Documentation
+
+The API documentation is developed with `vitepress` and `vuese`. Documentation pages are in the `docs` folder.
+
+### To run in local development mode
+```bash
+npm run docs:watch
+```
+
+This will start the documentation server with `vitepress` on port `:5173` and watch the components' changes.

cypress.config.js

@@ -0,0 +1,10 @@
+import { defineConfig } from "cypress";
+
+export default defineConfig({
+  component: {
+    devServer: {
+      framework: "vue",
+      bundler: "vite",
+    },
+  },
+});

cypress/component/ImageDialog.cy.js

@@ -0,0 +1,55 @@
+import ImageDialog from '../../src/components/index.js'
+
+describe('<ImageDialog />', () => {
+
+  it('renders iframe', () => {
+
+    // see: https://on.cypress.io/mounting-vue
+    cy.mount(ImageDialog, {
+      props: {
+        imageIframeURL: 'https://sparc.biolucida.net/image?c=NzQ5My1jb2wtMTkz',
+        imageGalleryItems: [],
+        imageDialogOpen: true
+      }
+    })
+
+    cy.get('.image-dialog').should('exist')
+    cy.get('.image-dialog-close').should('exist')
+
+    // Testing iframe image
+    cy.get('.image-iframe-container').should('exist')
+  })
+
+  it('renders gallery', () => {
+    // see: https://on.cypress.io/mounting-vue
+    cy.mount(ImageDialog, {
+      props: {
+        imageIframeURL: '',
+        imageGalleryItems: [
+          {
+            title: 'Title 1',
+            type: 'data1',
+            userData: 'https://sparc.science/',
+          },
+          {
+            title: 'Title 2',
+            type: 'data2',
+            link: 'https://sparc.science/',
+          },
+          {
+            title: 'Title 3',
+            type: 'data3',
+            link: 'https://sparc.science/',
+          },
+        ],
+        imageDialogOpen: true
+      }
+    })
+
+    cy.get('.image-dialog').should('exist')
+    cy.get('.image-dialog-close').should('exist')
+
+    // Testing gallery items
+    cy.get('.image-gallery-container').should('exist')
+  })
+})

cypress/support/commands.js

@@ -0,0 +1,25 @@
+// ***********************************************
+// This example commands.js shows you how to
+// create various custom commands and overwrite
+// existing commands.
+//
+// For more comprehensive examples of custom
+// commands please read more here:
+// https://on.cypress.io/custom-commands
+// ***********************************************
+//
+//
+// -- This is a parent command --
+// Cypress.Commands.add('login', (email, password) => { ... })
+//
+//
+// -- This is a child command --
+// Cypress.Commands.add('drag', { prevSubject: 'element'}, (subject, options) => { ... })
+//
+//
+// -- This is a dual command --
+// Cypress.Commands.add('dismiss', { prevSubject: 'optional'}, (subject, options) => { ... })
+//
+//
+// -- This will overwrite an existing command --
+// Cypress.Commands.overwrite('visit', (originalFn, url, options) => { ... })

cypress/support/component-index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width,initial-scale=1.0">
+    <title>Components App</title>
+  </head>
+  <body>
+    <div data-cy-root></div>
+  </body>
+</html>

cypress/support/component.js

@@ -0,0 +1,27 @@
+// ***********************************************************
+// This example support/component.js is processed and
+// loaded automatically before your test files.
+//
+// This is a great place to put global configuration and
+// behavior that modifies Cypress.
+//
+// You can change the location of this file or turn off
+// automatically serving support files with the
+// 'supportFile' configuration option.
+//
+// You can read more here:
+// https://on.cypress.io/configuration
+// ***********************************************************
+
+// Import commands.js using ES2015 syntax:
+import './commands'
+
+// Alternatively you can use CommonJS syntax:
+// require('./commands')
+
+import { mount } from 'cypress/vue'
+
+Cypress.Commands.add('mount', mount)
+
+// Example use:
+// cy.mount(MyComponent)

docs/.vitepress/config.js

@@ -0,0 +1,74 @@
+import path from 'path'
+import { defineConfig } from 'vitepress'
+import Components from 'unplugin-vue-components/vite'
+import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'
+
+const versionNumber = process.env.npm_package_version
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "ImageDialog",
+  description: "API documentation for ImageDialog",
+  base: '/image-dialog/',
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      {
+        text: 'API Reference',
+        link: '/components/ImageDialog'
+      }
+    ],
+
+    sidebar: [
+      {
+        text: 'Live Demo',
+        link: '/demo'
+      },
+      {
+        text: 'API Reference',
+        link: '/components/ImageDialog'
+      },
+      {
+        text: 'Version',
+        items: [
+          {
+            text: `${versionNumber}`
+          }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/ABI-Software/image-dialog' }
+    ]
+  },
+  markdown: { attrs: { disable: true } },
+  vite: {
+    css: {
+      preprocessorOptions: {
+        scss: {
+          additionalData: `@use '../src/assets/styles' as *;`
+        },
+      },
+    },
+    resolve: {
+      alias: {
+        '@': path.resolve(__dirname, '../../src'),
+      }
+    },
+    plugins: [
+      Components({
+        // Allow auto load markdown components under `./src/components/`.
+        extensions: ['vue'],
+        // Allow auto import and register the components used in markdown.
+        include: [/\.vue$/, /\.vue\?vue/],
+        resolvers: [
+          ElementPlusResolver({
+            importStyle: 'css',
+          }),
+        ],
+      }),
+    ]
+  }
+})

docs/.vitepress/theme/custom.css

@@ -0,0 +1,58 @@
+/* Modify content styles for the desktop view. */
+@media (min-width: 1280px) {
+  .VPContent .VPDoc.has-aside {
+    & .content-container {
+      max-width: none;
+    }
+
+    .content-container .vp-doc {
+      & table {
+        overflow: unset;
+      }
+
+      & table thead {
+        position: sticky;
+        top: 64px; /* Navigation height. */
+
+        & th {
+          background-color: var(--vp-c-gray-1);
+        }
+      }
+
+      & table tr {
+        th, td {
+          vertical-align: top;
+        }
+
+        th:first-child,
+        td:first-child {
+          width: 10%;
+          text-wrap: nowrap;
+        }
+
+        /* Description column. */
+        th:nth-child(2),
+        td:nth-child(2) {
+          width: 40%;
+        }
+
+        th:nth-child(3),
+        td:nth-child(3) {
+          width: 10%;
+        }
+
+        th:nth-child(4),
+        td:nth-child(4) {
+          width: 10%;
+        }
+
+        th:last-child,
+        td:last-child {
+          width: 20%;
+          word-wrap: break-word;
+          word-break: break-word;
+        }
+      }
+    }
+  }
+}

docs/.vitepress/theme/index.js

@@ -0,0 +1,4 @@
+import DefaultTheme from "vitepress/theme";
+import "./custom.css";
+
+export default DefaultTheme;