pinpoint

Pinpoint is an engine for displaying hierarchical keys that identify the Earth's species.

Install

npm install @sfgrp/pinpoint

Usage

<script setup>
import { VuePinpoint } from '@sfgrp/pinpoint'
import '@sfgrp/pinpoint/style.css'
</script>

<template>
  <VuePinpoint
    :lead-id="103"
    base-url="https://sfg.taxonworks.org/api/v1"
    project-token="YOUR_TOKEN"
  />
</template>

Props

| Prop | Type | Required | Description | | -------------- | -------------------------------------- | -------- | ------------------------------------------------------------------------------------ | | leadId | number \| string | yes | Id of the lead the key starts on. | | baseUrl | string | yes | TaxonWorks API base url. | | projectToken | string | yes | TaxonWorks project token. | | fetcher | (id: number) => Promise<KeyResponse> | no | Load the key payload from somewhere other than a TaxonWorks server. | | allowHtml | boolean | no | Render lead text as HTML. TaxonWorks marks up taxon names, so this is on by default. Defaults to true. |

Nothing is requested until leadId, baseUrl and projectToken are all set, so binding them to values that arrive asynchronously is safe.

Events

| Event | Payload | Fired when | | --------- | ------------- | --------------------------------- | | start | — | A load begins. | | loading | — | A load begins. | | end | KeyResponse | A load resolves. | | error | Error | A load rejects. |

Exposed methods

const pinpoint = ref()

pinpoint.value.getState()        // reactive store state
pinpoint.value.setCurrentNode(9) // navigate to a node by id
pinpoint.value.isLoading         // computed<boolean>

Slots

Every slot is declared on <VuePinpoint>, no matter how deep it renders.

Figures

Three levels of control, from most to least of the built-in UI replaced.

#figures — replace the whole gallery of a lead

<VuePinpoint v-bind="config">
  <template #figures="{ figures, node, open }">
    <MyGallery
      :images="figures"
      @select="(index) => open(index)"
    />
  </template>
</VuePinpoint>

| Slot prop | Type | Description | | --------- | ------------------------- | ---------------------------------------- | | figures | Figure[] | Figures attached to this lead. | | node | Node \| null | The lead the figures belong to. | | open | (index: number) => void | Opens the viewer on the given figure. |

#figure — replace a single thumbnail

<template #figure="{ figure, index, open }">
  <img
    :src="figure.thumb"
    :alt="figure.caption ?? ''"
    @click="open"
  />
</template>

| Slot prop | Type | Description | | --------- | ----------------- | --------------------------------- | | figure | Figure | The figure to render. | | index | number | Its position in figures. | | figures | Figure[] | The full list, for context. | | node | Node \| null | The lead the figure belongs to. | | open | () => void | Opens the viewer on this figure. |

#figure-viewer — keep the thumbnails, bring your own image viewer

This is usually what you want: pinpoint renders the thumbnails and tracks which figure is active, your component does the actual viewing.

<template #figure-viewer="{ figure, figures, index, close, next, previous }">
  <MyLightbox
    :items="figures"
    :start-index="index"
    @close="close"
  />
</template>

| Slot prop | Type | Description | | ---------- | -------------- | ---------------------------------------------- | | figure | Figure | The active figure. | | figures | Figure[] | The full list, so you can offer navigation. | | index | number | Index of the active figure. | | node | Node \| null | The lead the figures belong to. | | close | () => void | Closes the viewer. | | next | () => void | Advances to the next figure (wraps around). | | previous | () => void | Goes back one figure (wraps around). |

The slot only renders once a thumbnail has been activated, so there is no need to guard on visibility yourself.

Other slots

| Slot | Slot props | Replaces | | -------------------------- | --------------------------------- | ------------------------------------- | | title | { title, metadata } | The key title. | | loading | { leadId } | Shown while a key loads. See below. | | error | { error } | The error message. | | text | { text, node } | Lead text, wherever it renders. | | target | { label, id, node } | The target label of a lead. | | couplet-title | { node, coupletNumber } | "Couplet N". | | previous-couplets-title | — | "Previous couplets". | | button-up-label | { node } | "Up". | | button-go-label | { node } | "Go". | | button-next-label | { node } | "Next". | | figure-next-label | — | The viewer's next arrow. | | figure-previous-label | — | The viewer's previous arrow. |

#loading

Rendered while a key is in flight, and removed once it resolves or fails. Nothing at all is rendered when the slot is not provided, so this is opt-in.

<VuePinpoint v-bind="config">
  <template #loading>
    <MySpinner />
  </template>
</VuePinpoint>

The rest of the key stays mounted underneath while loading, so an overlay works without the content flickering out. If you would rather drive the state from outside, the loading/end/error events still fire, and isLoading is available on the component instance.

The Figure type

type Figure = {
  id: number | null
  caption: string | null
  label: string | null
  position: number
  contentType: string | null
  thumb: string     // small preview
  image: string     // medium size, used by the built-in thumbnails
  original: string  // full size, project token appended
  source: unknown   // the untouched API payload
}

source is the escape hatch: anything the adapters do not normalize is still reachable from your own viewer.

Using a data source other than TaxonWorks

fetcher replaces the request for the key payload. It receives the lead id and must resolve with the raw payload, in the same shape the TaxonWorks endpoint returns.

<VuePinpoint
  :lead-id="1"
  base-url="https://sfg.taxonworks.org/api/v1"
  project-token="YOUR_TOKEN"
  :fetcher="(id) => fetch(`/keys/${id}.json`).then((r) => r.json())"
/>

baseUrl and projectToken are still required with a fetcher: the API returns figure paths relative to the server (/api/v1/images/…), and the adapters need both to turn them into fetchable urls.

Development

npm run dev        # demo app
npm test           # unit + component tests
npm run typecheck  # vue-tsc
npm run build:lib  # library bundle + type declarations