# Mangrove Assets

This folder contains production-compiled Mangrove CSS and JS assets for use in static or simple sites.

- **Purpose:** Provide a simple way to include Mangrove styles and scripts in any site via the UNDRR asset library.
- **Sources:**
  - `latest/` - Assets from the [Mangrove Storybook build](https://mangrove.undrr.org/)
  - `{version}/` - Versioned releases from [@undrr/undrr-mangrove](https://www.npmjs.com/package/@undrr/undrr-mangrove) (1.2.8+)
- **Advanced usage:** For more complex integration, see the [Mangrove GitHub repository](https://github.com/unisdr/undrr-mangrove/) and [AI agent reference](https://mangrove.undrr.org/llms.txt).

### Static metadata for AI agents

Mangrove publishes static metadata for coding agents after each Storybook deploy:

- **AI guidance**: [`llms.txt`](https://mangrove.undrr.org/llms.txt)
- **Component index**: [`ai-components/index.json`](https://mangrove.undrr.org/ai-components/index.json) (summary, documentation links, rendered HTML, React requirements)
- **Per-component details**: `https://mangrove.undrr.org/ai-components/{id}.json`
- **Design tokens dictionary**: [`tokens.json`](https://mangrove.undrr.org/tokens.json) (token types, values, descriptions, and wrapping requirements)
- **CSS utility class reference**: [`ai-components/utilities.json`](https://mangrove.undrr.org/ai-components/utilities.json)
- **Machine-readable releases**: [`releases.json`](https://mangrove.undrr.org/releases.json)

Prereleases are published only under their complete version (for example,
`2.0.0-rc.3/`). The npm `latest` dist-tag remains the stable
fallback for `latest/`; npm's `next` tag does not replace it.

## Structure

```
mangrove/
├── latest/          # Latest development build from GitHub dist branch
│   ├── css/         # Stylesheets (e.g. css/style.css)
│   ├── js/          # JavaScript bundles
│   └── ...
├── 1.2.8/          # NPM release version 1.2.8
├── 1.2.9/          # NPM release version 1.2.9
├── ...
└── 2.2.0/          # Pinned release (CSS bundles, JS, assets)
```

Both `latest/` and versioned folders share the same flat layout (`css/`, `js/` at the root of each version directory).

## Theme stylesheets (Mangrove 2.0+)

Mangrove 2 provides single-theme CSS bundles containing only that property's design tokens, plus a multi-theme bundle:

- **UNDRR**: `https://assets.undrr.org/mangrove/2.2.0/css/style.css`
- **PreventionWeb**: `https://assets.undrr.org/mangrove/2.2.0/css/style-preventionweb.css`
- **MCR2030**: `https://assets.undrr.org/mangrove/2.2.0/css/style-mcr.css`
- **IRP**: `https://assets.undrr.org/mangrove/2.2.0/css/style-irp.css`
- **DELTA**: `https://assets.undrr.org/mangrove/2.2.0/css/style-delta.css`
- **All themes in one bundle**: `https://assets.undrr.org/mangrove/2.2.0/css/style-all.css`

Each single-theme bundle carries only its own tokens. Use `style-all.css` if a page switches themes at runtime using `.mg-theme-*` classes.

## Usage

```html
<!-- CSS (UNDRR theme) -->
<link rel="stylesheet" href="https://assets.undrr.org/mangrove/2.2.0/css/style.css" />

<!-- JS: load only the modules the page needs -->
<script type="module" src="https://assets.undrr.org/mangrove/2.2.0/js/tabs.js"></script>
```

Replace `2.2.0` with `latest` only for development/preview; always pin to a specific release version in production.

There is no combined bundle. Each interactive component ships as its own ES module, so load the ones the page uses and nothing else:

| Module | For |
| --- | --- |
| `js/tabs.js` | Tabs |
| `js/show-more.js` | Show more |
| `js/table-of-contents.js` | Table of contents |
| `js/on-this-page-nav.js` | On this page nav |
| `js/copy-button.js` | Copy button |
| `js/switch-pending.js` | Switch pending state |
| `js/preview-access.js` | Preview access |
| `js/undrr.js` | Shared UNDRR site behaviour |
| `js/drawer.js` | Drawer and floating-panel lifecycle (available from 2.0.0-rc.3) |
| `js/hub-header.js` | Hub header: current section from the URL, scroll into view and edge fades (available from 2.0.0) |

`type="module"` is required. These are ES modules, so a plain `<script src>` fails with `SyntaxError: Unexpected token 'export'`.

### Design token rules

1. **sRGB channel triples**: Most colour tokens are space-separated sRGB channels (e.g. `--mg-color-blue-900: 0 79 145;`). Always wrap in `rgb()`:
   ```css
   color: rgb(var(--mg-color-interactive));
   background: rgb(var(--mg-color-interactive) / 0.1); /* with alpha */
   ```
2. **Font roles**: Always use CSS custom property roles rather than hardcoded font families: `var(--mg-font-family-text)`, `-heading`, `-display`, `-ui`, `-code`.
3. **Z-index layers**: Use `--mg-z-index-*` tokens (`-behind`, `-nav`, `-sticky`, `-nav-toggle`, `-header`, `-drawer`, `-dropdown`, `-modal`, `-toast`) for global stacking contexts.
4. **Skip link**: Use `<a class="mg-skip-link" href="#main">Skip to content</a>` with `tabindex="-1"` on the target element.

## Recommended version: 2.2.0

Pin new and updated pages, templates and examples to Mangrove **2.2.0**.
Existing authored pages retain their explicit version pins until updated.
The Street Map references use its buttons, breadcrumbs and empty-state component
for map-loading errors. The library's 404 page uses the error-page component,
with inline fallback styles so it remains readable if the stylesheet cannot load.
Existing version directories remain available; CI publishes all qualifying npm
releases automatically.

## Mangrove 2.0 release history

Mangrove 2.0.0 was the first stable release of Mangrove 2. Sites pinned to a 2.0.0 release candidate should move to `2.2.0/`; sites on 1.x should read the migration notes below before upgrading.

Compared with 2.0.0-rc.3, the versioned asset folder adds the dependency-free `js/hub-header.js` module for static hub header markup. The release-candidate folders (`2.0.0-alpha.*` to `2.0.0-rc.3/`) stay published but should not be used for new work.

Full detail and migration steps: [v2.0 release notes](https://mangrove.undrr.org/?path=/docs/getting-started-release-notes-v2-0--docs) (source: [`docs/RELEASE-2.0.md`](https://github.com/unisdr/undrr-mangrove/blob/main/docs/RELEASE-2.0.md)).

_This folder is updated automatically by CI with the latest development build and all npm releases starting from version 1.2.8._