npm package: @geogdev/styles
Description: Geog map styles for MapLibre GL
Author: The Geog Authors
Latest version: 0.1.5

# @geogdev/styles

MapLibre GL layer styles for OpenMapTiles-compatible vector tiles.

## Installation

### npm / pnpm / yarn

```bash
npm install @geogdev/styles
```

### CDN (Browser)

```html
<script src="https://unpkg.com/@geogdev/styles/dist/styles.js"></script>
```

## Quick Start

### ESM / TypeScript

```typescript
import maplibregl from "maplibre-gl";
import { layers, LIGHT, DARK, GRAY, WARM } from "@geogdev/styles";

const map = new maplibregl.Map({
  container: "map",
  center: [-93.265, 44.977],
  zoom: 12,
  style: {
    version: 8,
    glyphs: "https://your-server.com/fonts/{fontstack}/{range}.pbf",
    sprite: "https://your-server.com/sprites/light",
    sources: {
      basemap: {
        type: "vector",
        url: "https://your-server.com/tiles.json"
      }
    },
    layers: layers("basemap", LIGHT, { lang: "en" })
  }
});
```

### Browser (CDN)

```html
<script src="https://unpkg.com/maplibre-gl@5.0.1/dist/maplibre-gl.js"></script>
<script src="https://unpkg.com/@geogdev/styles/dist/styles.js"></script>
<script>
  const mapLayers = styles.layers("basemap", styles.LIGHT, { lang: "en" });

  const map = new maplibregl.Map({
    container: "map",
    style: {
      version: 8,
      glyphs: "https://your-server.com/fonts/{fontstack}/{range}.pbf",
      sprite: "https://your-server.com/sprites/light",
      sources: {
        basemap: { type: "vector", url: "https://your-server.com/tiles.json" }
      },
      layers: mapLayers
    }
  });
</script>
```

## Available Themes

| Theme | Description |
|-------|-------------|
| `LIGHT` | Natural colors, high contrast labels |
| `DARK` | Subdued colors for dark mode |
| `GRAY` | Monochrome, ideal for data viz overlays |
| `WARM` | Earthy, sepia-toned palette |

## API Reference

### `layers(source, style, options?)`

Generates MapLibre GL layer specifications.

```typescript
import { layers, LIGHT } from "@geogdev/styles";

// Generate all layers (base + labels)
layers("basemap", LIGHT, { lang: "en" });

// Generate base layers only (no labels)
layers("basemap", LIGHT);

// Generate labels only
layers("basemap", LIGHT, { labelsOnly: true, lang: "en" });
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `source` | `string` | Source ID matching your MapLibre sources config |
| `style` | `Style` | Theme preset (`LIGHT`, `DARK`, `GRAY`, `WARM`) |
| `options.lang` | `string` | Language code for labels (e.g., "en", "de", "ja") |
| `options.labelsOnly` | `boolean` | If true, only generate label layers |

### `namedStyle(name)`

Get a style preset by string name.

```typescript
import { namedStyle } from "@geogdev/styles";

const style = namedStyle("dark"); // Returns DARK
```

### Style Presets

```typescript
import { LIGHT, DARK, GRAY, WARM } from "@geogdev/styles";
import { STYLE_NAMES, isValidStyleName } from "@geogdev/styles";

// STYLE_NAMES = ["light", "dark", "gray", "warm"]
isValidStyleName("dark"); // true
```

### TypeScript Types

```typescript
import type { Style, StyleName } from "@geogdev/styles";

// StyleName = "light" | "dark" | "gray" | "warm"
// Style = interface with all color properties
```

## Theme Switching

```typescript
import { layers, LIGHT, DARK } from "@geogdev/styles";

function switchTheme(map, theme) {
  const newStyle = {
    version: 8,
    glyphs: "https://your-server.com/fonts/{fontstack}/{range}.pbf",
    sprite: `https://your-server.com/sprites/${theme === DARK ? "dark" : "light"}`,
    sources: {
      basemap: { type: "vector", url: "https://your-server.com/tiles.json" }
    },
    layers: layers("basemap", theme, { lang: "en" })
  };
  map.setStyle(newStyle);
}

// Usage
switchTheme(map, DARK);
```

## Requirements

This package generates **layer specifications only**. You must provide:

1. **Tile source** - OpenMapTiles-compatible vector tiles (PMTiles, TileJSON, etc.)
2. **Fonts (glyphs)** - PBF font files for text rendering
3. **Sprites** - Icon sprite sheets (PNG + JSON)

## Development

```bash
# Build the package
npm run build

# Run tests
npm test

# Type checking
npm run tsc

# Format code
npm run format

# Generate style JSON (via npm script)
npm run generate_style output.json https://example.com/tiles.json light en

# Or via the installed CLI
npx geog-generate-style output.json https://example.com/tiles.json light en
```

## License

MIT