@tileflow/dev 0.1.0-alpha.1 → 0.1.0-alpha.11

package/README.md

@@ -2,12 +2,23 @@
 
 Node utilities used by the Tileflow CLI and build integrations.
 
+Most apps should use `@tileflow/cli`, `@tileflow/vite`, or `@tileflow/next` directly. Use this
+package when you are building a custom dev server, bundler plugin, or deployment adapter that needs
+to load and compile a `tileflow.config.ts`.
+
 ```ts
-import { createTileflowBuildArtifacts } from "@tileflow/dev";
+import {createTileflowBuildArtifacts} from '@tileflow/dev';
 
 const artifacts = await createTileflowBuildArtifacts({
-  config: "tileflow.config.ts",
+  config: 'tileflow.config.ts',
 });
 ```
 
+If a map uses `icons: './icons/brand'`, build artifacts include the generated
+MapLibre `sprite.json`, `sprite.png`, `sprite@2x.json`, and `sprite@2x.png`
+assets alongside the styles.
+
+This package is public, but it is an integration layer. Map styling primitives live in
+`@tileflow/core`; React rendering lives in `@tileflow/react`.
+
 Docs: https://tileflow.dev/docs

package/dist/index.d.ts

@@ -1,5 +1,12 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
 import { TileflowManifest, MapLibreStyle, ValidationMessage, TileflowProjectConfig, TileflowStyleOptions } from '@tileflow/core';
 
+type TileflowBuildAsset = {
+    contentType: string;
+    fileName: string;
+    source: string | Uint8Array;
+};
+
 declare const defaultTileflowApiUrl = "https://api.tileflow.dev";
 declare const defaultTileflowConfigPath = "tileflow.config.ts";
 declare const defaultTileflowManifestPath = "public/tileflow/manifest.json";
@@ -21,14 +28,17 @@ type TileflowDevRequestHandlerOptions = {
     tileBaseUrl?: string;
 };
 type TileflowBuildArtifactsOptions = {
+    assetBaseUrl?: string;
     config?: string;
     cwd?: string;
     styleBaseUrl?: string;
     tileBaseUrl?: string;
 };
 type TileflowBuildArtifacts = {
+    assets: TileflowBuildAsset[];
     manifest: TileflowManifest;
     styles: Record<string, MapLibreStyle>;
+    watchPaths: string[];
 };
 type WriteTileflowBuildArtifactsOptions = TileflowBuildArtifactsOptions & {
     outDir: string;
@@ -47,8 +57,15 @@ declare function getTileflowStyleMapName(path: string): string;
 declare function createTileflowManifest(project: TileflowProjectConfig, options?: TileflowManifestOptions): TileflowManifest;
 declare function createTileflowStyle(project: TileflowProjectConfig, mapName: string, options?: TileflowStyleOptions): MapLibreStyle;
 declare function createTileflowBuildArtifacts(options?: TileflowBuildArtifactsOptions): Promise<TileflowBuildArtifacts>;
+declare function getTileflowWatchPaths(options?: Pick<TileflowBuildArtifactsOptions, 'config' | 'cwd'>): Promise<string[]>;
 declare function writeTileflowBuildArtifacts(options: WriteTileflowBuildArtifactsOptions): Promise<TileflowBuildArtifacts>;
+declare function isTileflowRequestUrl(url: string | undefined, basePath: string): boolean;
+declare function createTileflowNodeRequest(request: IncomingMessage): Request;
+declare function writeTileflowNodeResponse(response: ServerResponse, tileflowResponse: Response): Promise<void>;
+declare function joinTileflowPublicUrl(publicBase: string, basePath: string): string;
+declare function getTileflowAssetBasePath(basePath: string): string;
+declare function getTileflowAssetFileName(basePath: string, fileName: string): string;
 declare function createTileflowDevRequestHandler(options?: TileflowDevRequestHandlerOptions): (request: Request) => Promise<Response>;
 declare function normalizeTileflowBasePath(value?: string): string;
 
-export { type LoadTileflowConfigOptions, type TileflowBuildArtifacts, type TileflowBuildArtifactsOptions, type TileflowDevRequestHandlerOptions, type TileflowManifestOptions, TileflowValidationError, type WriteTileflowBuildArtifactsOptions, asTileflowProjectConfig, assertValidTileflowConfig, createTileflowBuildArtifacts, createTileflowDevRequestHandler, createTileflowManifest, createTileflowStyle, defaultTileflowApiUrl, defaultTileflowConfigPath, defaultTileflowManifestPath, defaultTileflowTileset, getFirstTileflowMapName, getTileflowMapNames, getTileflowStyleMapName, loadTileflowConfig, loadValidTileflowConfig, normalizeTileflowBasePath, writeTileflowBuildArtifacts };
+export { type LoadTileflowConfigOptions, type TileflowBuildArtifacts, type TileflowBuildArtifactsOptions, type TileflowDevRequestHandlerOptions, type TileflowManifestOptions, TileflowValidationError, type WriteTileflowBuildArtifactsOptions, asTileflowProjectConfig, assertValidTileflowConfig, createTileflowBuildArtifacts, createTileflowDevRequestHandler, createTileflowManifest, createTileflowNodeRequest, createTileflowStyle, defaultTileflowApiUrl, defaultTileflowConfigPath, defaultTileflowManifestPath, defaultTileflowTileset, getFirstTileflowMapName, getTileflowAssetBasePath, getTileflowAssetFileName, getTileflowMapNames, getTileflowStyleMapName, getTileflowWatchPaths, isTileflowRequestUrl, joinTileflowPublicUrl, loadTileflowConfig, loadValidTileflowConfig, normalizeTileflowBasePath, writeTileflowBuildArtifacts, writeTileflowNodeResponse };

package/dist/index.js

@@ -1,13 +1,206 @@
 // src/index.ts
+import { createJiti } from "jiti";
+import { existsSync as existsSync2 } from "fs";
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, resolve as resolve2 } from "path";
 import {
   createManifest,
   createStyleFromProject,
   validateConfig
 } from "@tileflow/core";
+
+// src/icons.ts
 import { existsSync } from "fs";
-import { mkdir, writeFile } from "fs/promises";
-import { resolve } from "path";
-import { createJiti } from "jiti";
+import { readdir } from "fs/promises";
+import { extname, resolve } from "path";
+var iconFileExtensions = /* @__PURE__ */ new Set([".svg", ".png", ".jpg", ".jpeg", ".webp"]);
+var iconSpriteSize = 24;
+async function prepareTileflowProjectIcons(project, options) {
+  const nextProject = cloneProject(project);
+  const localSources = getLocalIconSources(project, options.cwd);
+  for (const localSource of localSources) {
+    const mapConfig = nextProject.maps[localSource.mapName];
+    if (!mapConfig) {
+      continue;
+    }
+    const iconSet = resolveIconSet(mapConfig.icons, nextProject.icons);
+    if (!iconSet) {
+      continue;
+    }
+    const spriteUrl = joinUrl(options.assetBaseUrl, `icons/${localSource.mapName}/sprite`);
+    mapConfig.icons = {
+      ...iconSet,
+      sprite: spriteUrl
+    };
+  }
+  if (localSources.length === 0) {
+    return {
+      assets: [],
+      project: nextProject,
+      watchPaths: []
+    };
+  }
+  const assets = (await Promise.all(
+    localSources.map(async (source) => buildSpriteAssets(source.sourceDir, source.mapName))
+  )).flat();
+  return {
+    assets,
+    project: nextProject,
+    watchPaths: localSources.map((source) => source.sourceDir)
+  };
+}
+function getTileflowIconWatchPaths(project, cwd) {
+  return uniqueStrings(getLocalIconSources(project, cwd).map((source) => source.sourceDir));
+}
+function getLocalIconSources(project, cwd) {
+  return Object.entries(project.maps).flatMap(([mapName, mapConfig]) => {
+    const iconSet = resolveIconSet(mapConfig.icons, project.icons);
+    const sourceDir = resolveLocalIconSource(iconSet, cwd);
+    return sourceDir ? [{ mapName, sourceDir }] : [];
+  });
+}
+function resolveLocalIconSource(iconSet, cwd) {
+  if (!iconSet?.source) {
+    return null;
+  }
+  return resolve(cwd, iconSet.source);
+}
+function resolveIconSet(icons, iconSets, path = []) {
+  if (!icons) {
+    return void 0;
+  }
+  if (typeof icons === "string") {
+    const referenced = iconSets?.[icons];
+    if (referenced) {
+      if (path.includes(icons)) {
+        throw new Error(`Circular Tileflow icon set extends: ${[...path, icons].join(" -> ")}`);
+      }
+      return resolveIconSet(referenced, iconSets, [...path, icons]);
+    }
+    return isRemoteSpriteReference(icons) ? { sprite: icons } : { source: icons };
+  }
+  const extended = icons.extends ? resolveIconSet(icons.extends, iconSets, path) : void 0;
+  return {
+    ...extended,
+    ...icons,
+    mapping: {
+      ...extended?.mapping,
+      ...icons.mapping
+    }
+  };
+}
+async function buildSpriteAssets(sourceDir, mapName) {
+  const icons = await readIconFiles(sourceDir);
+  if (icons.length === 0) {
+    throw new Error(`No SVG or PNG icons found in ${sourceDir}.`);
+  }
+  const [sprite, sprite2x] = await Promise.all([
+    buildSprite(sourceDir, icons, 1),
+    buildSprite(sourceDir, icons, 2)
+  ]);
+  return [
+    jsonAsset(`icons/${mapName}/sprite.json`, sprite.index),
+    binaryAsset(`icons/${mapName}/sprite.png`, sprite.image, "image/png"),
+    jsonAsset(`icons/${mapName}/sprite@2x.json`, sprite2x.index),
+    binaryAsset(`icons/${mapName}/sprite@2x.png`, sprite2x.image, "image/png")
+  ];
+}
+async function readIconFiles(sourceDir) {
+  if (!existsSync(sourceDir)) {
+    throw new Error(`Icon source not found: ${sourceDir}`);
+  }
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && iconFileExtensions.has(extname(entry.name).toLowerCase())).map((entry) => ({
+    name: entry.name.slice(0, -extname(entry.name).length),
+    path: resolve(sourceDir, entry.name)
+  })).sort((left, right) => left.name.localeCompare(right.name));
+}
+async function buildSprite(sourceDir, icons, pixelRatio) {
+  const sharp = await loadSharp();
+  const cellSize = iconSpriteSize * pixelRatio;
+  const columns = Math.ceil(Math.sqrt(icons.length));
+  const rows = Math.ceil(icons.length / columns);
+  const width = columns * cellSize;
+  const height = rows * cellSize;
+  const index = {};
+  const composite = await Promise.all(
+    icons.map(async (icon, indexNumber) => {
+      const column = indexNumber % columns;
+      const row = Math.floor(indexNumber / columns);
+      const left = column * cellSize;
+      const top = row * cellSize;
+      index[icon.name] = {
+        height: cellSize,
+        pixelRatio,
+        width: cellSize,
+        x: left,
+        y: top
+      };
+      return {
+        input: await sharp(icon.path, { density: 72 * pixelRatio }).resize(cellSize, cellSize, {
+          background: { alpha: 0, b: 0, g: 0, r: 0 },
+          fit: "contain"
+        }).png().toBuffer(),
+        left,
+        top
+      };
+    })
+  );
+  const image = await sharp({
+    create: {
+      background: { alpha: 0, b: 0, g: 0, r: 0 },
+      channels: 4,
+      height,
+      width
+    }
+  }).composite(composite).png().toBuffer();
+  return {
+    image,
+    index,
+    sourceDir
+  };
+}
+async function loadSharp() {
+  try {
+    return (await import("sharp")).default;
+  } catch (error) {
+    throw new Error(
+      'Local icon sprites require the optional "sharp" package. Install sharp or disable local icons.',
+      { cause: error }
+    );
+  }
+}
+function jsonAsset(fileName, value) {
+  return {
+    contentType: "application/json; charset=utf-8",
+    fileName,
+    source: `${JSON.stringify(value, null, 2)}
+`
+  };
+}
+function binaryAsset(fileName, source, contentType) {
+  return {
+    contentType,
+    fileName,
+    source
+  };
+}
+function cloneProject(project) {
+  return JSON.parse(JSON.stringify(project));
+}
+function isRemoteSpriteReference(value) {
+  return value.startsWith("http://") || value.startsWith("https://") || value.startsWith("/") || value.startsWith("data:");
+}
+function joinUrl(base, path) {
+  const trimmedBase = base.replace(/\/+$/g, "");
+  const trimmedPath = path.replace(/^\/+/g, "");
+  return trimmedBase ? `${trimmedBase}/${trimmedPath}` : trimmedPath;
+}
+function uniqueStrings(values) {
+  return [...new Set(values)];
+}
+
+// src/index.ts
 var defaultTileflowApiUrl = "https://api.tileflow.dev";
 var defaultTileflowConfigPath = "tileflow.config.ts";
 var defaultTileflowManifestPath = "public/tileflow/manifest.json";
@@ -22,8 +215,8 @@ var TileflowValidationError = class extends Error {
 };
 async function loadTileflowConfig(configPath = defaultTileflowConfigPath, options = {}) {
   const cwd = options.cwd ?? process.cwd();
-  const resolvedPath = resolve(cwd, configPath);
-  if (!existsSync(resolvedPath)) {
+  const resolvedPath = resolve2(cwd, configPath);
+  if (!existsSync2(resolvedPath)) {
     throw new Error(`Config not found: ${configPath}`);
   }
   const jiti = createJiti(import.meta.url, {
@@ -81,50 +274,104 @@ function createTileflowStyle(project, mapName, options = {}) {
   return createStyleFromProject(project, mapName, options);
 }
 async function createTileflowBuildArtifacts(options = {}) {
-  const project = await loadValidTileflowConfig(
-    options.config ?? defaultTileflowConfigPath,
-    {
-      cwd: options.cwd,
-      fresh: true
-    }
-  );
+  const project = await loadValidTileflowConfig(options.config ?? defaultTileflowConfigPath, {
+    cwd: options.cwd,
+    fresh: true
+  });
+  const prepared = await prepareTileflowProjectIcons(project, {
+    assetBaseUrl: resolveAssetBaseUrl(options),
+    cwd: options.cwd ?? process.cwd()
+  });
   const styleOptions = { tileBaseUrl: options.tileBaseUrl };
   const styles = Object.fromEntries(
-    getTileflowMapNames(project).map((mapName) => [
+    getTileflowMapNames(prepared.project).map((mapName) => [
       mapName,
-      createStyleFromProject(project, mapName, styleOptions)
+      createStyleFromProject(prepared.project, mapName, styleOptions)
     ])
   );
   return {
-    manifest: createManifest(project, {
+    assets: prepared.assets,
+    manifest: createManifest(prepared.project, {
       styleBaseUrl: options.styleBaseUrl,
       tileBaseUrl: options.tileBaseUrl
     }),
-    styles
+    styles,
+    watchPaths: prepared.watchPaths
   };
 }
+async function getTileflowWatchPaths(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const project = await loadValidTileflowConfig(options.config ?? defaultTileflowConfigPath, {
+    cwd,
+    fresh: true
+  });
+  return getTileflowIconWatchPaths(project, cwd);
+}
 async function writeTileflowBuildArtifacts(options) {
   const cwd = options.cwd ?? process.cwd();
-  const outDir = resolve(cwd, options.outDir);
-  const stylesDir = resolve(outDir, "styles");
+  const outDir = resolve2(cwd, options.outDir);
+  const stylesDir = resolve2(outDir, "styles");
   const artifacts = await createTileflowBuildArtifacts(options);
   await mkdir(stylesDir, { recursive: true });
   for (const [mapName, style] of Object.entries(artifacts.styles)) {
     await writeFile(
-      resolve(stylesDir, `${mapName}.json`),
+      resolve2(stylesDir, `${mapName}.json`),
       `${JSON.stringify(style, null, 2)}
 `,
       "utf8"
     );
   }
+  for (const asset of artifacts.assets) {
+    const outputPath = resolve2(outDir, asset.fileName);
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, asset.source);
+  }
   await writeFile(
-    resolve(outDir, "manifest.json"),
+    resolve2(outDir, "manifest.json"),
     `${JSON.stringify(artifacts.manifest, null, 2)}
 `,
     "utf8"
   );
   return artifacts;
 }
+function isTileflowRequestUrl(url, basePath) {
+  const pathname = (url ?? "/").split("?")[0] ?? "/";
+  if (!basePath) {
+    return pathname === "/manifest.json" || pathname === "/style.json" || pathname === "/" || pathname.startsWith("/icons/") || pathname.startsWith("/styles/");
+  }
+  return pathname === basePath || pathname.startsWith(`${basePath}/`);
+}
+function createTileflowNodeRequest(request) {
+  const protocol = getNodeHeader(request, "x-forwarded-proto") ?? "http";
+  const host = getNodeHeader(request, "host") ?? "localhost";
+  return new Request(`${protocol}://${host}${request.url ?? "/"}`, {
+    method: request.method
+  });
+}
+async function writeTileflowNodeResponse(response, tileflowResponse) {
+  response.statusCode = tileflowResponse.status;
+  tileflowResponse.headers.forEach((value, key) => {
+    response.setHeader(key, value);
+  });
+  response.end(Buffer.from(await tileflowResponse.arrayBuffer()));
+}
+function joinTileflowPublicUrl(publicBase, basePath) {
+  const trimmedBase = publicBase.replace(/\/+$/g, "");
+  const trimmedPath = basePath.replace(/^\/+|\/+$/g, "");
+  if (!trimmedPath) {
+    return trimmedBase || "";
+  }
+  if (!trimmedBase || trimmedBase === ".") {
+    return `/${trimmedPath}`;
+  }
+  return `${trimmedBase}/${trimmedPath}`;
+}
+function getTileflowAssetBasePath(basePath) {
+  return basePath.replace(/^\/+|\/+$/g, "");
+}
+function getTileflowAssetFileName(basePath, fileName) {
+  return basePath ? `${basePath}/${fileName}` : fileName;
+}
 function createTileflowDevRequestHandler(options = {}) {
   const basePath = normalizeTileflowBasePath(options.basePath);
   const configPath = options.config ?? defaultTileflowConfigPath;
@@ -136,6 +383,16 @@ function createTileflowDevRequestHandler(options = {}) {
     }
     const url = new URL(request.url);
     const path = stripTileflowBasePath(url.pathname, basePath);
+    const loadPreparedProject = async () => {
+      const project = await loadValidTileflowConfig(configPath, {
+        cwd,
+        fresh: true
+      });
+      return prepareTileflowProjectIcons(project, {
+        assetBaseUrl: `${url.origin}${basePath}`,
+        cwd
+      });
+    };
     if (path === null) {
       return jsonResponse({ error: "Not found" }, 404);
     }
@@ -145,9 +402,7 @@ function createTileflowDevRequestHandler(options = {}) {
           cwd,
           fresh: true
         });
-        return htmlResponse(
-          previewHtml(getFirstTileflowMapName(project), basePath)
-        );
+        return htmlResponse(previewHtml(getFirstTileflowMapName(project), basePath));
       }
       if (path === "/manifest.json") {
         const project = await loadValidTileflowConfig(configPath, {
@@ -163,31 +418,34 @@ function createTileflowDevRequestHandler(options = {}) {
         );
       }
       if (path === "/style.json") {
-        const project = await loadValidTileflowConfig(configPath, {
-          cwd,
-          fresh: true
-        });
+        const prepared = await loadPreparedProject();
         return jsonResponse(
-          createStyleFromProject(project, getFirstTileflowMapName(project), {
+          createStyleFromProject(prepared.project, getFirstTileflowMapName(prepared.project), {
             tileBaseUrl
           })
         );
       }
       if (path.startsWith("/styles/")) {
-        const project = await loadValidTileflowConfig(configPath, {
-          cwd,
-          fresh: true
-        });
+        const prepared = await loadPreparedProject();
         const mapName = getTileflowStyleMapName(path);
-        if (!project.maps[mapName]) {
+        if (!prepared.project.maps[mapName]) {
           return jsonResponse({ error: `Unknown map: ${mapName}` }, 404);
         }
         return jsonResponse(
-          createStyleFromProject(project, mapName, {
+          createStyleFromProject(prepared.project, mapName, {
             tileBaseUrl
           })
         );
       }
+      if (path.startsWith("/icons/")) {
+        const prepared = await loadPreparedProject();
+        const assetName = path.replace(/^\/+/, "");
+        const asset = prepared.assets.find((candidate) => candidate.fileName === assetName);
+        if (!asset) {
+          return jsonResponse({ error: `Unknown icon asset: ${assetName}` }, 404);
+        }
+        return assetResponse(asset);
+      }
       return jsonResponse({ error: "Not found" }, 404);
     } catch (error) {
       options.onError?.(error);
@@ -195,6 +453,10 @@ function createTileflowDevRequestHandler(options = {}) {
     }
   };
 }
+function getNodeHeader(request, name) {
+  const value = request.headers[name];
+  return Array.isArray(value) ? value[0] : value;
+}
 function normalizeTileflowBasePath(value = "") {
   const trimmed = value.trim().replace(/^\/+|\/+$/g, "");
   return trimmed ? `/${trimmed}` : "";
@@ -245,6 +507,28 @@ function htmlResponse(body, status = 200) {
     status
   });
 }
+function assetResponse(asset) {
+  const body = typeof asset.source === "string" ? asset.source : Buffer.from(asset.source);
+  return new Response(body, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Cache-Control": "no-store",
+      "Content-Type": asset.contentType
+    }
+  });
+}
+function resolveAssetBaseUrl(options) {
+  if (options.assetBaseUrl !== void 0) {
+    return options.assetBaseUrl;
+  }
+  if (options.styleBaseUrl && !isRelativePublicUrl(options.styleBaseUrl)) {
+    return options.styleBaseUrl;
+  }
+  return "..";
+}
+function isRelativePublicUrl(value) {
+  return !(value.startsWith("http://") || value.startsWith("https://") || value.startsWith("/") || value.startsWith("data:"));
+}
 function previewHtml(mapName, basePath) {
   const styleUrl = `${basePath}/styles/${mapName}.json`;
   return `<!doctype html>
@@ -299,16 +583,23 @@ export {
   createTileflowBuildArtifacts,
   createTileflowDevRequestHandler,
   createTileflowManifest,
+  createTileflowNodeRequest,
   createTileflowStyle,
   defaultTileflowApiUrl,
   defaultTileflowConfigPath,
   defaultTileflowManifestPath,
   defaultTileflowTileset,
   getFirstTileflowMapName,
+  getTileflowAssetBasePath,
+  getTileflowAssetFileName,
   getTileflowMapNames,
   getTileflowStyleMapName,
+  getTileflowWatchPaths,
+  isTileflowRequestUrl,
+  joinTileflowPublicUrl,
   loadTileflowConfig,
   loadValidTileflowConfig,
   normalizeTileflowBasePath,
-  writeTileflowBuildArtifacts
+  writeTileflowBuildArtifacts,
+  writeTileflowNodeResponse
 };

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@tileflow/dev",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.11",
   "description": "Node development utilities for Tileflow configs and builds.",
   "type": "module",
+  "sideEffects": false,
   "homepage": "https://tileflow.dev",
   "repository": {
     "type": "git",
@@ -36,10 +37,13 @@
   },
   "dependencies": {
     "jiti": "^2.7.0",
-    "@tileflow/core": "0.1.0-alpha.1"
+    "@tileflow/core": "0.1.0-alpha.11"
+  },
+  "optionalDependencies": {
+    "sharp": "^0.34.5"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean --platform node",
+    "build": "tsup src/index.ts --format esm --dts --clean --platform node --external sharp",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsc -p tsconfig.json --noEmit"
   }