piri 1.1.1 → 1.1.2

package/README.md

@@ -1,6 +1,6 @@
 # piri
 
-A lightweight utility to create beautiful, dotted SVG maps with a bring-your-own-styles mentality. Heavily based on the [Dotted Map](https://github.com/NTag/dotted-map/tree/main) library, with more customization.
+A lightweight utility to create beautiful, stylized SVG maps with a bring-your-own-styles mentality. Heavily based on the [Dotted Map](https://github.com/NTag/dotted-map/tree/main) library, with more customization.
 
 ![a dotted map on an abstract background](https://raw.githubusercontent.com/thejessewinton/piri/refs/heads/main/image.jpeg "SVG Dotted Map")
 
@@ -12,7 +12,7 @@ A lightweight utility to create beautiful, dotted SVG maps with a bring-your-own
 pnpm install piri
 ```
 
-## Quick Start
+## Usage
 
 ```tsx
 import { createMap } from "piri";
@@ -23,174 +23,70 @@ const { points, addMarkers } = createMap({
 });
 ```
 
-`createMap` returns:
+It's that simple. `points` represents land mass, `addMarkers` projects your markers onto the same coordinate space.
 
-- **`points`** — an array of `{ x, y }` coordinates representing land masses, snapped to a dot grid
-- **`addMarkers`** — a function to convert lat/lng markers into the same coordinate space
-
-## API Reference
-
-### `createMap(options)`
-
-Creates a dot grid representing the world (or a subset of it) and returns the grid points along with a marker projection function.
-
-#### Options
+### Options
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `width` | `number` | **required** | Width of the SVG viewBox in px. |
-| `height` | `number` | **required** | Height of the SVG viewBox in px. |
-| `mapSamples` | `number` | `6000` | Total number of grid cells sampled. Higher values produce denser, more detailed maps at the cost of more points to render. |
-| `radius` | `number` | `0.3` | The base dot radius in viewBox units. Controls the margin/padding around the edges of the map (`margin = radius * 1.25`). |
-| `countries` | `CountryCode[]` | `undefined` | ISO 3166-1 alpha-3 country codes to render (e.g. `["USA", "CAN"]`). When provided, only the specified countries are drawn and the region auto-fits to their bounding box. |
-| `region` | `Region` | auto | A custom lat/lng bounding box to control which part of the world is visible. Overrides the auto-fit behavior when `countries` is set. |
-
-#### Region
-
-```typescript
-interface Region {
-  lat: { min: number; max: number };
-  lng: { min: number; max: number };
-}
-```
-
-Latitudes are clamped to `[-85, 85]` internally (the limit of the Web Mercator projection).
+| `width` | `number` | **required** | Width of the SVG viewBox. |
+| `height` | `number` | **required** | Height of the SVG viewBox. |
+| `mapSamples` | `number` | `6000` | Grid cells sampled. Higher = denser dots. |
+| `radius` | `number` | `0.3` | Base dot radius in viewBox units. Controls edge margin (`radius * 1.25`). |
+| `countries` | `CountryCode[]` | `undefined` | ISO 3166-1 alpha-3 codes (e.g. `["USA", "CAN"]`). Auto-fits the region to the bounding box. Fully typesafe — you get autocomplete on all ~170 supported codes. |
+| `region` | `Region` | auto | Custom lat/lng bounding box. Overrides the auto-fit from `countries`. Latitudes clamped to `[-85, 85]` (Web Mercator limit). |
 
-#### Return Value
+### Markers
 
-```typescript
-{
-  points: Point[];          // { x: number; y: number }[]
-  addMarkers: <MarkerData>(markers: Marker<MarkerData>[]) => (Point & MarkerData)[];
-}
-```
-
-### `addMarkers<MarkerData>(markers)`
-
-Projects an array of lat/lng markers into the map's coordinate space. Each marker is snapped to the nearest grid position so it aligns with the dot grid.
-
-#### Marker
-
-```typescript
-type Marker<MarkerData = void> = {
-  lat: number;
-  lng: number;
-  size?: number;
-} & MarkerData;
-```
+By default `addMarkers` expects an array with, at minimum, the latitude and longitude of your markers, and an optional `size` parameter.
 
-- `lat` / `lng` — geographic coordinates
-- `size` — **pass-through only**. Not used internally; it's returned as-is for your renderer to consume.
-- Any additional properties from `MarkerData` are preserved in the output.
-
-#### Generic Custom Data
-
-`addMarkers` accepts a generic type parameter, giving you full type safety on custom marker properties:
-
-```typescript
-const markers = addMarkers<{ label: string; visited: boolean }>([
+```ts
+const markers = addMarkers([
   { 
     lat: 40.7128, 
     lng: -74.006, 
-    label: "New York", 
-    visited: true 
-  },
+    size: 0.4
+  }, // New York
   { lat: 51.5074, 
-    lng: -0.1278, 
-    label: "London", 
-    visited: false 
-  },
+    lng: -0.1278 
+  }, // London
 ]);
 ```
 
-## Usage Examples
+#### Expanding the output
 
-### World Map
-
-```tsx
-import { createMap } from "piri";
+`addMarkers` is generic, and any extra properties you pass in are preserved and fully typed in the output.
 
-const { points, addMarkers } = createMap({
-  width: 150,
-  height: 75,
-  mapSamples: 4500,
-});
-
-const markers = addMarkers([
-  { lat: 40.7128, lng: -74.006, size: 0.5 },   // New York
-  { lat: 34.0522, lng: -118.2437, size: 0.5 },  // Los Angeles
-  { lat: 51.5074, lng: -0.1278, size: 0.5 },    // London
-  { lat: -33.8688, lng: 151.2093, size: 0.5 },  // Sydney
+```ts
+const markers = addMarkers<{ visited: boolean}>([
+  { 
+    lat: 40.7128, 
+    lng: -74.006, 
+    size: 0.4
+    visited: true
+  }, // New York
+  { lat: 51.5074, 
+    lng: -0.1278 
+    visited: false
+  }, // London
 ]);
 ```
 
-### Single Country
-
-When `countries` is provided, the map automatically zooms to fit those countries:
-
-```typescript
-const { points, addMarkers } = createMap({
-  width: 200,
-  height: 100,
-  countries: ["USA"],
-});
-```
-
-### Multiple Countries
-
-```typescript
-const { points, addMarkers } = createMap({
-  width: 200,
-  height: 100,
-  countries: ["USA", "CAN", "MEX"],
-});
-```
-
-### Custom Region
-
-Override the viewport with a specific lat/lng bounding box:
-
-```typescript
-const { points } = createMap({
-  width: 200,
-  height: 100,
-  region: {
-    lat: { min: 35, max: 72 },
-    lng: { min: -25, max: 45 },
-  },
-});
-```
-
-### Controlling Density
-
-`mapSamples` controls the total grid cells tested. More samples = more dots = more detail:
-
-```typescript
-// Sparse — fast, lightweight
-const sparse = createMap({ width: 200, height: 100, mapSamples: 500 });
-
-// Dense — detailed, more points to render
-const dense = createMap({ width: 200, height: 100, mapSamples: 10000 });
-```
-
 ### Rendering
 
-After creating a map, render it as an SVG, with whatever customizations you'd like. This example uses React:
+After these steps, render the map as an SVG, with whatever customizations you need. This example uses React:
 
 ```tsx
 export const DottedMap = () => {
-  const { points, addMarkers } = createMap({
-    width: 150,
-    height: 75,
-  });
+  const { points, addMarkers } = createMap({ width: 150, height: 75 })
 
   const markers = addMarkers<{ visited: boolean }>([
     { lat: 40.7128, lng: -74.006, size: 0.5, visited: true },
     { lat: 51.5074, lng: -0.1278, size: 0.5, visited: false },
-  ]);
+  ])
 
   return (
-    <svg viewBox="0 0 150 75" style={{ width: "100%", height: "100%" }}>
+    <svg viewBox="0 0 150 75" style={{ width: '100%', height: '100%' }}>
       {points.map((point) => (
         <circle
           cx={point.x}
@@ -205,15 +101,15 @@ export const DottedMap = () => {
           cx={marker.x}
           cy={marker.y}
           r={marker.size ?? 0.25}
-          fill={marker.visited ? "#4A0404" : "#999"}
+          fill={marker.visited ? '#4A0404' : '#999'}
           key={`${marker.x}-${marker.y}`}
         />
       ))}
     </svg>
-  );
-};
+  )
+}
 ```
 
 ## Caching
 
-Point calculations are cached automatically. Calling `createMap` with identical options returns the same points without recalculating. The cache invalidates when any option changes (dimensions, countries, region, radius, or sample count).
+Point calculations are cached automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "piri",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "type": "module",
   "exports": {
     ".": {
@@ -11,17 +11,8 @@
   },
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "keywords": [
-    "map",
-    "dotted map",
-    "svg map",
-    "svg",
-    "stylized map",
-    "piri"
-  ],
+  "files": ["dist"],
+  "keywords": ["map", "dotted map", "svg map", "svg", "stylized map", "piri"],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",