@neshan-maps-platform/maplibre-sdk 1.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Neshan Maps Platform
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# @neshan-maps-platform/maplibre-sdk
+
+[![npm version](https://img.shields.io/npm/v/@neshan-maps-platform/maplibre-sdk.svg)](https://www.npmjs.com/package/@neshan-maps-platform/maplibre-sdk)
+[![license](https://img.shields.io/npm/l/@neshan-maps-platform/maplibre-sdk.svg)](./LICENSE)
+
+> **Status: alpha.** The package is versioned `1.0.0-alpha` — the public API
+> described below is expected to be stable, but breaking changes may still
+> land before `1.0.0`.
+
+A drop-in wrapper around [MapLibre GL JS](https://maplibre.org/) that
+transparently decodes the platform's encoded, gzip-compressed vector tiles,
+injects a client API key on every tile request, enables RTL text, and applies
+custom branding — while being used **exactly like plain `maplibre-gl`**.
+MapLibre is bundled into the package, so consumers install one thing.
+
+## Contents
+
+- [Install & quick start](#neshan-maps-platformmaplibre-sdk)
+- [How it works](#how-it-works)
+  - [API key](#api-key)
+  - [Custom branding](#custom-branding)
+  - [RTL text](#rtl-text-on-by-default)
+  - [Projection override](#projection-override)
+  - [Minimum zoom](#minimum-zoom)
+  - [Styles](#styles)
+- [Browser support](#browser-support)
+- [Package contents](#package-contents)
+- [License](#license)
+
+```bash
+npm install @neshan-maps-platform/maplibre-sdk
+```
+
+```js
+import maplibregl from "@neshan-maps-platform/maplibre-sdk";
+import "@neshan-maps-platform/maplibre-sdk/style.css";
+
+const map = new maplibregl.Map({
+  container: "map",
+  style: "https://static.neshan.org/sdk/maplibre/styles/light.json",
+  center: [59.6, 36.3],
+  zoom: 12,
+  apiKey: "YOUR_API_KEY",
+});
+```
+
+That's the whole API. No protocol registration, no key handling, no
+decompression, no control wiring — the subclass does all of it.
+
+## How it works
+
+### API key
+
+Get an API key from [platform.neshan.org](https://platform.neshan.org/), then
+pass it as `apiKey` to `new Map(...)`. It is appended as a `key` query
+parameter to every tile request. It is your access/quota credential — not
+secret in any meaningful sense, and enforced server-side.
+
+`apiKey` is required — constructing a `Map` without one throws immediately.
+
+### Custom branding
+
+The logo and copyright are added at the bottom of the map. The user can
+change the location of the logo and copyright, but they are not allowed to
+remove or hide them.
+
+Placement is configurable via `NeshanMapOptions` — note that, despite the
+names, `logoPosition` places the attribution control and `copyRightPosition`
+places the brand logo:
+
+```js
+new maplibregl.Map({
+  /* ... */
+  logoPosition: "bottom-left",
+  copyRightPosition: "bottom-right",
+});
+```
+
+Both accept MapLibre's `ControlPosition` (`'top-left'`, `'top-right'`,
+`'bottom-left'`, `'bottom-right'`). `logoPosition` defaults to `'bottom-left'`;
+`copyRightPosition` defaults to `'bottom-right'`.
+
+### RTL text (on by default)
+
+Arabic/Persian/Hebrew labels need MapLibre's `mapbox-gl-rtl-text` plugin. The
+SDK registers it **automatically** — RTL shaping is on by default with no
+consumer action. The plugin is bundled locally, so there's no separate file to
+host and no CDN dependency.
+
+To customize or opt out per map:
+
+```js
+new maplibregl.Map({ /* ... */, rtl: false });          // disable
+new maplibregl.Map({ /* ... */, rtl: { lazy: false } }); // evaluate eagerly
+new maplibregl.Map({ /* ... */, rtl: { url: '/rtl.js' }}); // self-hosted URL instead of inlined
+```
+
+Registration is global and idempotent, shared across all maps on the page.
+
+### Projection override
+
+Pass `projection` to force a projection regardless of what the loaded style
+specifies, without editing the style JSON. It's re-applied on every
+`style.load`, so it survives `setStyle` swaps too:
+
+```js
+new maplibregl.Map({ /* ... */, projection: { type: "mercator" } });
+new maplibregl.Map({ /* ... */, projection: { type: "globe" } });
+```
+
+- `mercator` — the classic flat, 2D cylindrical map projection. Predictable
+  and familiar, but distorts area and shape at high latitudes.
+- `globe` — renders the map as a 3D sphere that reveals its curvature at low
+  zoom levels, then blends into standard Mercator tiles as you zoom in.
+  More visually engaging for whole-world or low-zoom views.
+
+### Minimum zoom
+
+`minZoom` is accepted as usual, but the SDK enforces a floor of `1.5` — if you
+pass a lower value (or omit it), it's clamped up to `1.5`.
+
+### Styles
+
+`style` is passed straight through to MapLibre, same as plain `maplibre-gl` —
+point it at a style JSON URL. Five ready-made styles are hosted at
+`https://static.neshan.org/sdk/maplibre/styles/`:
+
+| Style                   | File                    | URL                                                                   |
+| ----------------------- | ----------------------- | --------------------------------------------------------------------- |
+| Light                   | `light.json`            | `https://static.neshan.org/sdk/maplibre/styles/light.json`            |
+| Dark                    | `dark.json`             | `https://static.neshan.org/sdk/maplibre/styles/dark.json`             |
+| Neshan Monochrome Light | `monochrome_light.json` | `https://static.neshan.org/sdk/maplibre/styles/monochrome_light.json` |
+| Neshan Monochrome Dark  | `monochrome_dark.json`  | `https://static.neshan.org/sdk/maplibre/styles/monochrome_dark.json`  |
+| Pastel                  | `pastel.json`           | `https://static.neshan.org/sdk/maplibre/styles/pastel.json`           |
+
+```js
+new maplibregl.Map({
+  /* ... */
+  style: "https://static.neshan.org/sdk/maplibre/styles/dark.json",
+});
+```
+
+## Browser support
+
+Tile decoding uses the standard [`DecompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream)
+API, so it needs Chrome 80+, Firefox 113+, or Safari 16.4+ (same floor as
+`maplibre-gl` itself already requires). There is no fallback for older
+browsers — tile requests will fail on them.
+
+## Package contents
+
+| File                              | Format                                            |
+| --------------------------------- | ------------------------------------------------- |
+| `dist/neshan-maplibre-sdk.js`     | ESM                                               |
+| `dist/neshan-maplibre-sdk.cjs`    | CJS                                               |
+| `dist/neshan-maplibre-sdk.umd.js` | UMD (global `maplibregl`)                         |
+| `dist/neshan-maplibre-sdk.css`    | extracted MapLibre CSS                            |
+| `dist/index.d.ts`                 | rolled-up type declarations (public surface only) |

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+import { ControlPosition } from 'maplibre-gl';
+import { default as default_2 } from 'maplibre-gl';
+import { MapOptions } from 'maplibre-gl';
+import { ProjectionSpecification } from 'maplibre-gl';
+
+/**
+ * Drop-in replacement for maplibregl.Map. On construction it:
+ *  - registers the nsh:// protocol (once per page, shared by all maps)
+ *  - stores the consumer's `apiKey` for the protocol handler
+ *  - disables the stock attribution and adds one carrying the brand entry
+ *  - hides MapLibre's default logo and adds the custom brand logo control
+ *
+ * Consumers use it exactly like plain maplibre-gl plus one extra option:
+ *
+ *   const map = new maplibregl.Map({
+ *     container: 'map', style, center, zoom,
+ *     apiKey: 'YOUR_API_KEY',
+ *   });
+ */
+declare class Map_2 extends default_2.Map {
+    constructor(options: NeshanMapOptions);
+}
+export { Map_2 as Map }
+
+export declare interface NeshanMapOptions extends MapOptions {
+    /**
+     * Client-facing API key. NOT the tile decode key. Appended automatically
+     * as `?key=...` to every nsh:// tile request.
+     */
+    apiKey?: string;
+    /**
+     * RTL text shaping (Arabic/Persian/Hebrew). Enabled by default.
+     * Pass `false` to disable, or an options object to customize.
+     */
+    rtl?: boolean | RtlOptions;
+    logoPosition?: ControlPosition;
+    copyRightPosition?: ControlPosition;
+    /**
+     * Overrides the style's `projection`. Pass e.g. `{ type: 'mercator' }` to
+     * force mercator regardless of what the loaded style specifies, without
+     * editing the style JSON.
+     */
+    projection?: ProjectionSpecification;
+}
+
+/**
+ * RTL (right-to-left) text shaping for Arabic/Persian/Hebrew labels.
+ *
+ * MapLibre needs the mapbox-gl-rtl-text plugin registered once, globally,
+ * before it renders RTL glyphs. We inline the vendored plugin as a string and
+ * hand MapLibre a Blob URL, so it's fully self-contained.
+ *
+ * The SDK's Map subclass calls ensureRtlTextPlugin() automatically, so RTL is
+ * on by default. Exported for manual/advanced use as well.
+ */
+export declare interface RtlOptions {
+    /**
+     * Defer downloading/evaluating the plugin until RTL text is first
+     * encountered. Default true. For a mostly-RTL basemap you can pass false to
+     * evaluate eagerly.
+     */
+    lazy?: boolean;
+    /**
+     * Override the plugin URL instead of using the inlined vendored file (e.g.
+     * point at a self-hosted copy). When set, the inlined file is ignored.
+     */
+    url?: string;
+}
+
+declare const sdk: Omit<typeof default_2, "Map"> & {
+    Map: typeof Map_2;
+};
+export default sdk;
+
+export { }