@sfgrp/taxonpages 0.1.0

package/README.markdown

@@ -0,0 +1,432 @@
+# TaxonPages
+
+TaxonPages is a tool to serve taxon pages. At present it draws data from TaxonWorks' API, however we seek to keep the TaxonPages platform agnostic therefor facilitating the modular addition of functionality that may reference data from any biodiversity data-serving API.
+
+## Status Warning
+
+TaxonPages software is in active development and changes are expected that will cause the early first-adopters' instances to require rebuilding by refreshing one's forked branch using `git pull`. A first _stable version_ is expected by Spring 2023.
+
+## Usage
+
+1. Click on "Fork" button to create your own repository from this.
+2. Uncheck `Copy the setup branch only` and press `Save`
+3. After create your repo, go to `Settings > Pages`, on "Build and deployment - Source" select `GitHub Actions`.
+4. Go to `Actions` tab and press `I understand my workflows, go ahead and enable them` button
+5. Open `router.yml` file and change `base_url` to the name of your repository.
+6. After a couple of minutes, your public page should be available at `https://<your_user_name>.github.io/<your_repo_name>`
+
+### Setup
+
+1. Switch to `setup` branch in your TaxonPages repository.
+2. We provide some settings by default to setup your public pages, but API parameters are required and must be configured to get the data from your TaxonWorks project.
+
+```yaml
+# config/api.yml
+---
+url: https://<your.taxonworks.server>/api/v1
+project_token: yourprojecttoken
+```
+
+3. Push the changes after update the configuration files inside `setup` branch
+4. GitHub actions will build TaxonPages with the current configuration in `setup` branch and publish it to the `gh-pages` branch
+
+# Install
+
+Follow this steps to run TaxonPages in your local machine.
+
+1. Install [NodeJS](https://nodejs.org/en/download/)
+2. We recommend you to fork this repository to keep getting updates. Use [GIT](https://git-scm.com/) to clone the repo.
+
+```
+git clone https://github.com/<your_username>/<your_repository_name>.git
+```
+
+But if you don't want to fork it, you can clone directly from this
+
+```
+git clone https://github.com/SpeciesFileGroup/taxonpages.git
+```
+
+3. Go to `taxonpages` folder and enter the following commands to copy the software to your `setup` branch
+
+```
+git checkout main
+git checkout setup
+git checkout main .
+git reset
+git checkout .
+```
+
+5. Setup `config/api.yml` with the API server configuration
+
+6. Install node dependencies
+
+```
+npm install
+```
+
+## Start TaxonPages
+
+```
+npm run dev
+```
+
+TaxonPages will be running at http://localhost:5173/
+
+# NPM Installation (CLI)
+
+As an alternative to cloning the repository, you can use the TaxonPages CLI to scaffold and manage your project.
+
+### Requirements
+
+- [Node.js](https://nodejs.org/en/download/) >= 18.0.0
+
+### Quick start
+
+Create a new project using `npx` (no global install needed):
+
+```
+npx @sfgrp/taxonpages init my-project
+cd my-project
+npm install
+```
+
+Edit `config/api.yml` with your TaxonWorks API URL and project token, then start the development server:
+
+```
+npm run dev
+```
+
+Your site will be running at http://localhost:5173/
+
+### Global installation
+
+If you prefer to have the CLI available globally:
+
+```
+npm install -g @sfgrp/taxonpages
+```
+
+Then you can use it directly:
+
+```
+taxonpages init my-project
+```
+
+### CLI Commands
+
+All commands are available through `npm run` scripts in your project or directly via the `taxonpages` CLI:
+
+| Command                       | npm script          | Description                                    |
+| ----------------------------- | ------------------- | ---------------------------------------------- |
+| `taxonpages init [directory]` | —                   | Scaffold a new TaxonPages project              |
+| `taxonpages dev`              | `npm run dev`       | Start development server (SPA mode, port 5173) |
+| `taxonpages dev:ssr`          | `npm run dev:ssr`   | Start SSR development server (port 6173)       |
+| `taxonpages build`            | `npm run build`     | Build for production (SPA mode)                |
+| `taxonpages build:ssr`        | `npm run build:ssr` | Build for production (SSR mode)                |
+| `taxonpages serve`            | `npm run serve`     | Start production SSR server (port 6173)        |
+| `taxonpages preview`          | `npm run preview`   | Preview production build locally (port 4173)   |
+
+### Example workflow
+
+```
+npx @sfgrp/taxonpages init my-project
+cd my-project
+npm install
+# Edit config/api.yml with your API settings
+npm run dev
+```
+
+# Customization
+
+## Pages
+
+TaxonPages out of the box support markdown and vue for content sites. Add your content pages inside `pages` folder. By default, TaxonPages use the file name to create the route.
+For example, if the filename is "contributors.md" the route to access it will be http://yourtaxonpagessite/contributors
+
+### Markdown pages
+
+This software use [vite-plugin-md](https://github.com/antfu/vite-plugin-md) to render pages in Markdown format, the engine of this plugin is [markdown-it](https://github.com/markdown-it/markdown-it). For plugins and other configuration you can refer to this section https://github.com/antfu/vite-plugin-md#configuration--options
+
+Example: `welcome.md` file
+
+```
+---
+name: 'Charles Darwin'
+---
+
+# Welcome, {{ name }}!
+```
+
+To use TaxonPage internal variables in `config/*.yml`, you can either do so by adding the prefix {{ app:var_name }} or use the script tag in your markdown page and get them from the global object `__APP_ENV__`
+
+#### Prefix
+
+```markdown
+# Welcome to {{ app:project_name }}!
+```
+
+#### Script tag
+
+```javascript
+# Welcome to {{ project_name }}!
+
+<script setup>
+const { project_name } = __APP_ENV__
+</script>
+```
+
+#### Components
+
+TaxonPages global components are enable in your markdown pages, by default we provide a set of global components that you don't need to import them to use it. You can see the list of this global components [here](#global-components)
+
+### Style
+
+If you want to change the color palette, you can edit `/config/style/theme.css` file, colors must be in RGB format.
+TaxonPages use [TailwindCSS](https://tailwindcss.com/docs/configuration) framework for the style. We already provide default settings for colors and markdown. If you want to make any change to your configuration, you must do so in the `config/vendor/tailwind.config.js` file. This file uses the TaxonPages configuration as a default. It is possible to overwrite it as long as you use it as a preset.
+
+## Analytics
+
+TaxonPages has out-of-the-box support for the following list of analytics services:
+
+```yaml
+analytics_services:
+  enableDev: false # Set true to work in development mode
+  analytics:   # Google Analytics
+    - id: 'G-XXXXX'
+  gtm:         # Google Tag Manager
+    - id: 'GTM-XXXXX'
+  pixel:       # Facebook Pixel
+    - id: 'XXXXXXX'
+  retargeting: # VK Retargeting
+    - id: 'VK-RTRG-XXXXXX-XXXXX',
+  linkedin:    # Linkedin Insight
+    - id: 'XXXXXXX'
+  tongji:      # Baidu Tongji
+    - id: 'XXXXXXX',
+  metrica:     # Yendex Metrica
+    - id: 'XXXXXXX',
+  microsoft:   # Microsoft Analytics
+    id: 'XXXXXXX'
+  hotjar:      # Hotjar Analytics
+    id: 'XXXXXXX',
+  fullStory:   # Full story Analytics
+    org: 'X-XXXXXX-XXX'
+  tiktok:      # TikTok Pixel Analytics
+    id: 'XXXXXXX'
+```
+
+# Deep dive into TaxonPages
+
+## Access internal configuration vars
+
+To access the configuration in \*.yml files, we provide a global object that contains all the configuration values. This variable can be used in either JavaScript, Vue, or Markdown files. To access these values you must use the `__APP_ENV__` variable:
+
+```javascript
+const { project_name } = __APP_ENV__
+// or
+const projectName = __APP_ENV__.project_name
+```
+
+## Taxa Page
+
+### Layout
+
+To modify the position of the panels in the layout of the Taxa page, edit the `taxa_page.yml` file. There you can add/move/remove panels from the layout, also you can add new tabs and include new panels there. If you want to make some tabs visible or not depending the rank group, you can include `rankGroup`
+
+```yaml
+taxa_page:
+  overview:
+    panels:
+      - - - panel:gallery
+          - panel:type
+          - panel:type-specimen
+          - panel:nomenclature
+          - panel:nomenclature-references
+
+        - - panel:map
+          - panel:descendants
+          - panel:content
+          - panel:statistics
+#
+# An example of a new tab:
+#
+# type_specimens:
+#   rank_group: ['SpeciesGroup']
+#   panels:
+#     - - - panel:specimen-records
+```
+
+### Lifecycle hooks (Experimental feature)
+
+The `onCreatePage` and `onSSRPageCreate` functions allow you to execute code at the time the taxa page is created. `onSSRPageCreate` will be executed only on the server side in SSR mode. To make use of them it is necessary to include them in a file object called `pages/otus.config.js`. Both functions accept `otu`, `taxon`, `route` and `router` objects as parameters. Since `onCreatePage` runs on Taxa page component, it is possible to use hooks like `onMounted` or `onBeforeMount` inside it
+
+```javascript
+export default {
+  onSSRCreatePage: async ({ otu, taxon, route, router }) => {
+    // Your code here
+  },
+
+  onCreatePage: ({ otu, taxon, route, router }) => {
+    // Your code here
+  }
+}
+```
+
+### Customizing the Layout
+
+The application comes with a default layout that includes a header and a footer. If you'd like to replace this layout with your own, you can do so by creating a custom layout file.
+
+Steps to replace the default layout
+
+1. In the root folder of your project, create a new folder called `layouts` (if it doesn't already exist).
+2. Inside this folder, create a file named default.vue.
+3. Define your custom layout structure inside this file as needed.
+
+Example of layouts/default.vue
+
+```vuejs
+<template>
+  <div>
+    <slot />
+  </div>
+</template>
+```
+
+This custom layout will replace the default one and be applied throughout the application. You can include your own elements, such as a navigation bar or footer, as needed.
+
+#### Using Multiple Layouts
+
+In addition to replacing the default layout, you can create multiple layouts by adding more .vue files inside the layout folder. You can then specify which layout to use for a specific page by setting the layout name in the meta property of the `<route>` tag in your Single File Component (SFC).
+
+JSON5:
+
+```js
+<route>
+{
+  meta: {
+    layout: 'custom'
+  }
+}
+</route>
+```
+
+YAML:
+
+```yaml
+<route lang="yaml">
+meta:
+  layout: custom
+</route>
+```
+
+### External panels
+
+To add panels in Taxa pages, create a folder called `panels` in your `setup` branch, and inside it create another folder for your panel. For example: `panels/PanelTest`
+
+In `PanelTest` folder, create a `main.js` file, with the following structure:
+
+```javascript
+import MyPanelComponent from './MyPanelComponent.vue'
+
+export default {
+  id: 'panel:test', // ID to identify this panel
+  component: MyPanelComponent, // Vue component for your panel
+  rankGroup: [
+    'HigherClassificationGroup',
+    'FamilyGroup',
+    'GenusGroup',
+    'SpeciesGroup'
+  ] // <-- OPTIONAL: This will define for which rank group will be available, remove it if your panel will be available for all.
+}
+```
+
+This file is used to load your panel component in taxa page. Use the `id` to include and define the position in the layout in `taxa_page.yml`
+
+```yaml
+taxa_page_overview:
+  panels:
+    - - - panel:gallery
+        - panel:test # <--- Your new panel
+        - panel:type
+        - panel:type-specimen
+        - panel:nomenclature
+        - panel:nomenclature-references
+
+      - - panel:map
+        - panel:descendants
+        - panel:scrutiny
+        - panel:content
+        - panel:keys
+        - panel:etymology
+        - panel:gbif
+        - panel:statistics
+        - panel:sounds
+```
+
+## Defining global components
+
+TaxonPages provides an auto-import component from `src/components` and `/components` folders using special extensions for it. Some objects and functions are only present in the browser and not in the NodeJs server environment. When you run code that is not supported by the server, it ends up crashing. Some JavaScript libraries like `Leaflet` use the `document` or `window` object, which do not exist in the node environment. To handle this problem, TaxonPages provides 2 ways to import the components.
+
+### Client Side only (CSR):
+
+This auto import method will only load the component on the client side, while on the server it will create a fake empty component, which will be used later on the client side to be replaced by the original one when the hydration process occurs. To define this type of import, the component name must contain the word `.client.` before `.vue` extension.
+
+Example: `MyAmazingComponent.client.vue`
+
+### Global (CSR & SSR)
+
+This auto-import method will load the component both client and server side. To define this type of import, the component must contain the word `.client.` before the `.vue` extension.
+
+Example: `MyAmazingComponent.global.vue`
+
+### Global components
+
+TaxonPages provides a set of global components that could be used to create your own panels or pages. Here is the complete list:
+
+| Component             | Description                                    | Props                                                                                                                    |
+| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `<AnimationOpacity/>` | Add an opacity animation for a child component |                                                                                                                          |
+| `<Autocomplete/>`     | Used to perform searches in TaxonWorks         | [Link](https://github.com/SpeciesFileGroup/taxonpages/blob/main/src/components/Autocomplete/Autocomplete.global.vue#L42) |
+| `<AutocompleteOtu/>`  | A specific autocomplete for OTU search         |                                                                                                                          |
+| `<ClientOnly/>`       | Render child components only from client side  |                                                                                                                          |
+| `<VButton/>`          | Button component                               |                                                                                                                          |
+| `<VCard/>`            | Card component style                           |                                                                                                                          |
+| `<VCardContent/>`     | Card content body                              |                                                                                                                          |
+| `<VCardHeader/>`      | Card Header                                    |                                                                                                                          |
+| `<VClipboard/>`       | Copy a text to clipboard                       |                                                                                                                          |
+| `<Dropdown/>`         | Dropdown menu                                  |                                                                                                                          |
+| `<GalleryImage/>`     |                                                | [Link](https://github.com/SpeciesFileGroup/taxonpages/blob/main/src/components/Gallery/GalleryImage.global.vue#L40)      |
+| `<ImageViewer/>`      |                                                |                                                                                                                          |
+| `<TrackerReport/>`    | Show trackers to report issues                 | [Link](https://github.com/SpeciesFileGroup/taxonpages/blob/main/src/components/TrackerReport.global.vue#L47)             |
+| `<TabMenu/>`          |                                                |                                                                                                                          |
+| `<TabItem/>`          |                                                |                                                                                                                          |
+| `<VMap/>`             | Interactive map that use Leaflet library       |                                                                                                                          |
+| `<VModal/>`           | Create lightboxes                              |                                                                                                                          |
+| `<VSkeleton/>`        | Content loading placeholder                    |                                                                                                                          |
+| `<VSpinner/>`         | Loading spinner                                |                                                                                                                          |
+| `<VTable/>`           |                                                |                                                                                                                          |
+| `<VTableBody/>`       |                                                |                                                                                                                          |
+| `<VTableBodyCell/>`   |                                                |                                                                                                                          |
+| `<VTableBodyRow/>`    |                                                |                                                                                                                          |
+| `<VTableHeader/>`     |                                                |                                                                                                                          |
+| `<VTableHeaderCell/>` |                                                |                                                                                                                          |
+| `<VTableHeaderRow/>`  |                                                |                                                                                                                          |
+
+| Icons                |
+| -------------------- |
+| `<IconArrowDown/>`   |
+| `<IconArrowLeft/>`   |
+| `<IconArrowRight/>`  |
+| `<IconCheck/>`       |
+| `<IconClipboard/>`   |
+| `<IconClose/>`       |
+| `<IconDocument/>`    |
+| `<IconDownload/>`    |
+| `<IconHamburger/>`   |
+| `<IconJson/>`        |
+| `<IconMinusCircle/>` |
+| `<IconPlusCircle/>`  |
+| `<IconSearch/>`      |
+| `<IconTrash/>`       |
+| `<IconWarning/>`     |

package/bin/taxonpages.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'node:module'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Command } from 'commander'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(__dirname, '..')
+const require = createRequire(import.meta.url)
+const { version, description } = require('../package.json')
+
+const program = new Command()
+
+program.name('taxonpages').description(description).version(version)
+
+program
+  .command('dev')
+  .description('Start Vite development server with HMR (SPA mode)')
+  .option('-p, --port <number>', 'port number', '5173')
+  .option('--host [host]', 'expose to network')
+  .action(async (options) => {
+    const { startDev } = await import('../src/cli/commands/dev.js')
+    await startDev({ packageRoot, projectRoot: process.cwd(), ...options })
+  })
+
+program
+  .command('dev:ssr')
+  .description('Start SSR development server')
+  .option('-p, --port <number>', 'port number', '6173')
+  .action(async (options) => {
+    const { startDevSSR } = await import('../src/cli/commands/dev.js')
+    await startDevSSR({ packageRoot, projectRoot: process.cwd(), ...options })
+  })
+
+program
+  .command('build')
+  .description('Build for production (SPA mode)')
+  .action(async () => {
+    const { runBuild } = await import('../src/cli/commands/build.js')
+    await runBuild({ packageRoot, projectRoot: process.cwd(), mode: 'spa' })
+  })
+
+program
+  .command('build:ssr')
+  .description('Build for production (SSR mode)')
+  .action(async () => {
+    const { runBuild } = await import('../src/cli/commands/build.js')
+    await runBuild({ packageRoot, projectRoot: process.cwd(), mode: 'ssr' })
+  })
+
+program
+  .command('serve')
+  .description('Start production SSR server')
+  .option('-p, --port <number>', 'port number', '6173')
+  .action(async (options) => {
+    const { serve } = await import('../src/cli/commands/serve.js')
+    await serve({ packageRoot, projectRoot: process.cwd(), ...options })
+  })
+
+program
+  .command('preview')
+  .description('Preview production build locally')
+  .option('-p, --port <number>', 'port number', '4173')
+  .action(async (options) => {
+    const { preview } = await import('../src/cli/commands/preview.js')
+    await preview({ packageRoot, projectRoot: process.cwd(), ...options })
+  })
+
+program
+  .command('init [directory]')
+  .description('Scaffold a new TaxonPages project')
+  .action(async (directory) => {
+    const { init } = await import('../src/cli/commands/init.js')
+    await init({ packageRoot, directory: directory || '.' })
+  })
+
+program.parse()

package/index.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0"
+    />
+    <!--head-tags-->
+    <!--preload-links-->
+    <!--app-state-->
+  </head>
+  <body>
+    <!--body-tags-open-->
+    <div id="app"></div>
+    <script
+      type="module"
+      src="/src/entry-client.js"
+    ></script>
+    <!--body-tags-->
+  </body>
+</html>

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@sfgrp/taxonpages",
+  "version": "0.1.0",
+  "description": "CLI tool for building taxon pages powered by SpeciesFileGroup",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "taxonpages": "./bin/taxonpages.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "server.js",
+    "vite.config.js",
+    "index.html",
+    "tailwind.config.cjs",
+    "postcss.config.cjs"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "dev": "node bin/taxonpages.js dev",
+    "dev:ssr": "node bin/taxonpages.js dev:ssr",
+    "build": "node bin/taxonpages.js build",
+    "build:ssr": "node bin/taxonpages.js build:ssr",
+    "serve": "node bin/taxonpages.js serve",
+    "debug": "node --inspect-brk server",
+    "preview": "node bin/taxonpages.js preview",
+    "lint": "eslint --ext .js,.vue --ignore-path .gitignore --fix src"
+  },
+  "dependencies": {
+    "@geoman-io/leaflet-geoman-free": "^2.19.2",
+    "@nuxt/devalue": "^2.0.2",
+    "@sfgrp/distinguish": "^0.4.2",
+    "@sfgrp/pinpoint": "^0.0.12",
+    "@tailwindcss/typography": "^0.5.19",
+    "@unhead/ssr": "^2.1.4",
+    "@unhead/vue": "^2.1.4",
+    "@vitejs/plugin-vue": "^6.0.4",
+    "autoprefixer": "^10.4.24",
+    "axios": "^1.13.5",
+    "commander": "^14.0.3",
+    "compression": "^1.8.1",
+    "express": "^5.2.1",
+    "glob": "^13.0.3",
+    "js-yaml": "^4.1.1",
+    "leaflet": "^1.9.4",
+    "leaflet.markercluster": "^1.5.3",
+    "markdown-it-anchor": "^9.2.0",
+    "minimist": "^1.2.8",
+    "pinia": "^3.0.4",
+    "postcss": "^8.5.6",
+    "sass": "^1.97.3",
+    "serve-static": "^2.2.1",
+    "tailwindcss": "^3.4.17",
+    "unplugin-vue-markdown": "^29.2.0",
+    "vite": "^7.3.1",
+    "vite-plugin-pages": "^0.33.3",
+    "vite-plugin-radar": "^0.10.1",
+    "vue": "^3.5.28",
+    "vue-router": "^5.0.2"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.2",
+    "eslint-plugin-vue": "^10.7.0"
+  },
+  "keywords": [
+    "taxonworks",
+    "biodiversity",
+    "taxonomy",
+    "vue",
+    "ssr",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SpeciesFileGroup/taxonpages.git"
+  }
+}

package/postcss.config.cjs

@@ -0,0 +1,17 @@
+const fs = require('fs')
+const {
+  userTailwindConfigPath,
+  defaultTailwindConfigPath
+} = require('./src/constants/configPaths.cjs')
+
+module.exports = {
+  plugins: {
+    'tailwindcss/nesting': {},
+    tailwindcss: {
+      config: fs.existsSync(userTailwindConfigPath)
+        ? userTailwindConfigPath
+        : defaultTailwindConfigPath
+    },
+    autoprefixer: {}
+  }
+}