# @samvera/nectar-iiif

> React.js UI component library of IIIF Presentation API 3.0 property fluent primitives.

Latest version **0.0.20** (published 2023-01-06) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @samvera/nectar-iiif
pnpm add @samvera/nectar-iiif
yarn add @samvera/nectar-iiif
bun add @samvera/nectar-iiif
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.0.20 |
| Published | 2023-01-06 |
| First published | 2022-04-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 74.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | Northwestern University Libraries |
| Maintainers | mathewjordan, adamjarling, dwithana, phuongdh |
| Keywords | IIIF |

## Links

- npm: https://www.npmjs.com/package/@samvera/nectar-iiif
- Repository: https://github.com/samvera-labs/nectar-iiif
- Homepage: https://github.com/samvera-labs/nectar-iiif.git#readme
- Issues: https://github.com/samvera-labs/nectar-iiif.git/issues
- npm.io page: https://npm.io/package/@samvera/nectar-iiif

## Dependencies (5)

- [react](https://npm.io/package/react.md) ^16.8  || ^17.0 || ^18.0
- [hls.js](https://npm.io/package/hls.js.md) ^1.2.8
- [react-dom](https://npm.io/package/react-dom.md) ^16.8  || ^17.0 || ^18.0
- [sanitize-html](https://npm.io/package/sanitize-html.md) ^2.7.3
- [@stitches/react](https://npm.io/package/@stitches/react.md) ^1.2.8

## Recent versions

- 0.0.20 (latest) — 2023-01-06
- 0.0.19 — 2022-12-06
- 0.0.18 — 2022-10-18
- 0.0.17 — 2022-10-04
- 0.0.16 — 2022-08-05
- 0.0.15 — 2022-07-15
- 0.0.14 — 2022-06-15
- 0.0.13 — 2022-05-27
- 0.0.12 — 2022-05-25
- 0.0.11 — 2022-05-24
- 0.0.10 — 2022-05-06
- 0.0.9 — 2022-05-06
- 0.0.7 — 2022-04-27
- 0.0.6 — 2022-04-26
- 0.0.6-alpha.7 — 2022-04-21
- … 20 more at https://npm.io/package/@samvera/nectar-iiif/versions

## README

# Nectar IIIF

React.js UI component library of IIIF Presentation API 3.0 property fluent primitives.

[**Demo**](https://samvera-labs.github.io/nectar-iiif) | [**Code**](https://github.com/samvera-labs/nectar-iiif)

---

## Documentation

- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Primitives](#primitives)
  - [Label](#label)
  - [Homepage](#homepage)
  - [Metadata](#metadata)
  - [PartOf](#partof)
  - [RequiredStatement](#requiredstatement)
  - [SeeAlso](#seealso)
  - [Summary](#summary)
  - [Thumbnail](#thumbnail)
- [Attributes](#attributes)
- [Language](#language-internationalization)

---

<h2 id="installation">Installation</h2>

Install the component from your command line using `npm install`,

```shell
npm install @samvera/nectar-iiif
```

**OR** if you prefer Yarn, use `yarn add`.

```shell
yarn add @samvera/nectar-iiif
```

---

<h2 id="basic-usage">Basic Usage</h2>

Add the Nectar component(s) to your `jsx` or `tsx` code.

```jsx
import { Label, Summary } from "@samvera/nectar-iiif";
```

```jsx
/**
 * Some logic may be required to retrieve the IIIF Manifest.
 */
const manifest = {...};

return (
  <>
    <Label label={manifest.label} as="h1" />
    <Summary summary={manifest.summary} as="p" />
  </>
);
```

---

## Primitives

Primitives aim to cover most of the noted [Descriptive](https://iiif.io/api/presentation/3.0/#31-descriptive-properties) and [Linking](https://iiif.io/api/presentation/3.0/#31-descriptive-properties) properties noted in the IIIF Presentation API 3.0 specification. Some of these, specifically `Provider` may have a more complex component structure.

Completed (initial release) and proposed primitives include:

**Descriptive Properties**

- [x] Label
- [x] Metadata
- [x] Summary
- [x] RequiredStatement
- [ ] Rights
- [ ] Provider
- [x] Thumbnail

**Linking Properties**

- [x] Homepage
- [ ] Logo
- [ ] Rendering
- [x] SeeAlso
- [x] PartOf

---

### Label

#### Reference

| Prop    | Type                                                                  | Default | Required |
| ------- | --------------------------------------------------------------------- | ------- | -------- |
| `as`    | ` span`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`, `label`, `dt`, `dd` | `span`  | --       |
| `label` | [label](https://iiif.io/api/presentation/3.0/#label)                  | --      | **Yes**  |

#### Usage

```jsx
import { Label } from "@samvera/nectar-iiif";
```

```jsx
return <Label label={manifest.label} as="h1" lang="en" />;
```

---

### Homepage

```jsx
import { Homepage } from "@samvera/nectar-iiif";
```

Wrap resource label with homepage id.

```jsx
return <Homepage homepage={manifest.homepage} />;
```

Wrap React children with homepage id.

```jsx
return (
  <Homepage homepage={manifest.homepage}>
    <figure>...</figure>
  </Homepage>
);
```

---

### Metadata

Metadata is rendered am HTML `dl` with corresponding `dt` and `dd` elements for they respective `label` and `value` pairs. By default `value` entries are rendered as a string, with `, ` interspersed to seperate multiple entries. A consuming application using can optionally update the `value` output for each entry.

#### Reference

| Prop                   | Type                                                       | Default | Required |
| ---------------------- | ---------------------------------------------------------- | ------- | -------- |
| `as`                   | `dl`                                                       | `dl`    |          |
| `metadata`             | [metadata](https://iiif.io/api/presentation/3.0/#metadata) | --      | **Yes**  |
| `customValueContent`   | NectarCustomValueContent[]                                 | --      | --       |
| `customValueDelimiter` | string?                                                    | `,`     | --       |

```jsx
import { Metadata } from "@samvera/nectar-iiif";
```

```jsx
return <Metadata metadata={manifest.metadata} />;
```

#### Custom Value Content

If a consumign application required rendering specific `metadata` item `values` in a custom pattern, the `customValueContent` prop can be set for the `<Metadata>` component. The pattern requires `matchingLabel` as following https://iiif.io/api/presentation/3.0/#label and `Content` asa ReactElement carrying `props`. The element set for `Content` must map `props.value` to the appropriate code in the custom pattern.

In the example below, the value of **Pantaloon** with a matching `label` of `{ none: ["Subject"] }` would be rendered as `<dd><a href="https://example.org/?subject=Pantaloon">Pantaloon</a><dd>`, while the `value` entry of **comic masks** would render simply as `<dd>comic masks</dd>`.

```jsx
const metadata = [
  {
    label: { none: ["Genre"] },
    value: { none: ["comic masks"] },
  },
  {
    label: { none: ["Subject"] },
    value: { none: ["Pantaloon"] },
  },
];

const CustomValueSubject = (props) => (
  <a href={encodeURI(`https://example.org/?subject=${props.value}`)}>
    {props.value}
  </a>
);

const customValueContent = [
  {
    matchingLabel: { none: ["Subject"] },
    Content: <CustomValueSubject />,
  },
];

return <Metadata metadata={metadata} customValueContent={customValueContent} />;
```

---

### RequiredStatement

```jsx
import { RequiredStatement } from "@samvera/nectar-iiif";
```

```jsx
return <RequiredStatement requiredStatement={manifest.requiredStatement} />;
```

#### Reference

| Prop                   | Type                                                                         | Default | Required |
| ---------------------- | ---------------------------------------------------------------------------- | ------- | -------- |
| `requiredStatement`    | [requiredStatement](https://iiif.io/api/presentation/3.0/#requiredstatement) | --      | **Yes**  |
| `customValueDelimiter` | string?                                                                      | `,`     | --       |

---

### PartOf

#### Reference

| Prop     | Type                                                   | Default | Required |
| -------- | ------------------------------------------------------ | ------- | -------- |
| `as`     | ` ol`, `ul`                                            | `ul`    | --       |
| `partOf` | [partOf](https://iiif.io/api/presentation/3.0/#partOf) | --      | **Yes**  |

```jsx
import { PartOf } from "@samvera/nectar-iiif";
```

```jsx
return <PartOf partOf={manifest.partOf} as="li" />;
```

---

### SeeAlso

#### Reference

| Prop      | Type                                                     | Default | Required |
| --------- | -------------------------------------------------------- | ------- | -------- |
| `as`      | ` ol`, `ul`                                              | `ul`    | --       |
| `seeAlso` | [seeAlso](https://iiif.io/api/presentation/3.0/#seealso) | --      | **Yes**  |

```jsx
import { SeeAlso } from "@samvera/nectar-iiif";
```

```jsx
return <SeeAlso seeAlso={manifest.seeAlso} as="li" />;
```

---

### Summary

#### Reference

| Prop                   | Type                                                     | Default | Required |
| ---------------------- | -------------------------------------------------------- | ------- | -------- |
| `as`                   | ` span`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`         | `span`  | --       |
| `summary`              | [summary](https://iiif.io/api/presentation/3.0/#summary) | --      | **Yes**  |
| `customValueDelimiter` | string?                                                  | `,`     | --       |

#### Usage

```jsx
import { Summary } from "@samvera/nectar-iiif";
```

```jsx
return <Summary summary={manifest.summary} as="p" />;
```

---

### Thumbnail

Thumbnails are rendered to a relative HTML `<img>` or `<video>` element dependendent on the type of the resource in the thumbnail entry. Currently, only `type` **Image** and **Video** are supported.

<img width="300" alt="image" src="https://github.com/mathewjordan/fet/blob/main/nectar-thumb-trimmed.gif?raw=true">

#### Reference

| Prop         | Type                                                         | Default | Required |
| ------------ | ------------------------------------------------------------ | ------- | -------- |
| `thumbnail`  | [thumbnail](https://iiif.io/api/presentation/3.0/#thumbnail) | --      | **Yes**  |
| `altAsLabel` | [label](https://iiif.io/api/presentation/3.0/#label)         | --      | --       |

```jsx
import { Thumbnail } from "@samvera/nectar-iiif";
```

```jsx
return <Thumbnail thumbnail={manifest.thumbnail} altAsLabel={manifest.label} />;
```

## Attributes

All primitives accept common HTMLElement attributes.

| Prop        | Type                          | Default     |
| ----------- | ----------------------------- | ----------- |
| `className` | `string`, `undefined`         | `undefined` |
| `style`     | `CSSProperties`, `undefined`  | `undefined` |
| `lang`      | `string`, `undefined`         | `undefined` |
| `title`     | `string`, `undefined`         | `undefined` |
| `data-*`    | `string`, `undefined`         | `undefined` |
| `aria-*`    | `AriaAttributes`, `undefined` | `undefined` |

## Language (Internationalization)

The value of `lang` will couple with [InternationalString](https://github.com/IIIF-Commons/presentation-3-types/blob/main/iiif/descriptive.d.ts#L6-L8) props to output the denoted `label`, `value`, `summary` entries. If `lang` is undefined, entries will default to the first entry in the array index.

---
_Source: https://npm.io/package/@samvera/nectar-iiif · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
