@phila/layerboard 3.0.0-beta.20 → 3.0.0-beta.21

package/dist/types/config.d.ts

@@ -0,0 +1,76 @@
+import { LayerConfig } from './layer';
+export interface LayerboardConfig {
+    /**
+     * ArcGIS Online WebMap ID to fetch layer configuration from
+     */
+    webMapId: string;
+    /**
+     * Mode for layer configuration
+     * - 'dynamic': Fetch from ArcGIS Online at runtime (recommended)
+     * - 'static': Use pre-generated static config files
+     */
+    mode?: "dynamic" | "static";
+    /**
+     * Layer panel display mode
+     * - 'flat': Simple list of all layers (OpenMaps style)
+     * - 'topics': Grouped by topic in accordion (StreetSmartPHL style)
+     */
+    panelMode?: "flat" | "topics";
+    /**
+     * Topic configuration (required when panelMode is 'topics')
+     */
+    topics?: TopicConfig[];
+    /**
+     * Static layer configurations (used when mode is 'static')
+     */
+    staticLayers?: LayerConfig[];
+    /**
+     * Initial map view settings
+     */
+    initialView?: InitialViewConfig;
+    /**
+     * Feature flags to enable/disable framework features
+     */
+    features?: FeatureFlags;
+    /**
+     * Optional callback when map is ready
+     */
+    onMapReady?: (map: unknown) => void;
+}
+/**
+ * Initial map view configuration
+ */
+export interface InitialViewConfig {
+    /** Center coordinates [longitude, latitude] */
+    center: [number, number];
+    /** Initial zoom level */
+    zoom: number;
+    /** Optional min zoom constraint */
+    minZoom?: number;
+    /** Optional max zoom constraint */
+    maxZoom?: number;
+}
+/**
+ * Feature flags for enabling/disabling framework features
+ */
+export interface FeatureFlags {
+    /** Enable address search (default: true) */
+    search?: boolean;
+    /** Enable geolocation/locate me button (default: true) */
+    geolocation?: boolean;
+    /** Enable Cyclomedia street-level imagery integration */
+    cyclomedia?: boolean;
+    /** Enable Pictometry oblique imagery integration */
+    pictometry?: boolean;
+    /** Enable layer opacity controls (default: true) */
+    opacitySliders?: boolean;
+    /** Enable layer legends (default: true) */
+    legends?: boolean;
+}
+export interface TopicConfig {
+    id: string;
+    title: string;
+    icon?: string;
+    layerIds: string[];
+    defaultExpanded?: boolean;
+}

package/dist/types/dataSource.d.ts

@@ -0,0 +1,40 @@
+/**
+ * DataSource Types
+ *
+ * Configuration and state types for fetching external data from APIs.
+ * Used by topic components to display dynamic content like notices, status, etc.
+ */
+/**
+ * Configuration for a data source
+ */
+export interface DataSourceConfig {
+    /** Unique identifier for the data source */
+    id: string;
+    /** URL to fetch data from */
+    url: string;
+    /** Type of data source - determines how data is fetched */
+    type: "http-get" | "http-post" | "esri";
+    /** Optional polling interval in milliseconds (for auto-refresh) */
+    pollInterval?: number;
+    /** Optional request options (headers, etc.) */
+    options?: RequestInit;
+    /** Optional transform function to process the response data */
+    transform?: (data: unknown) => unknown;
+}
+/**
+ * State for a single data source
+ */
+export interface DataSourceState<T = unknown> {
+    /** The fetched data (null if not yet loaded or error) */
+    data: T | null;
+    /** Whether the data is currently being fetched */
+    loading: boolean;
+    /** Error message if fetch failed */
+    error: string | null;
+    /** Timestamp of last successful fetch */
+    lastFetched: number | null;
+}
+/**
+ * Combined state for all data sources
+ */
+export type DataSourcesState = Record<string, DataSourceState>;

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './config';
+export * from './layer';
+export * from './dataSource';

package/dist/types/layer.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Layer Configuration Types
+ */
+export interface LegendItem {
+    type: "fill" | "line" | "circle";
+    color: string;
+    label: string;
+    width?: number;
+    radius?: number;
+}
+export interface PopupFieldFormat {
+    dateFormat?: string;
+    digitSeparator?: boolean;
+    places?: number;
+}
+export interface PopupField {
+    field: string;
+    label: string;
+    format?: PopupFieldFormat;
+}
+export interface PopupConfig {
+    title: string;
+    fields: PopupField[];
+    showTime?: boolean;
+}
+/**
+ * Display options for layer controls in the sidebar
+ * These match the original Layerboard's topicLayers options
+ */
+export interface LayerDisplayOptions {
+    /** Whether to show a checkbox for this layer (default: true) */
+    shouldShowCheckbox?: boolean;
+    /** Whether to show an opacity slider for this layer (default: true) */
+    shouldShowSlider?: boolean;
+    /** Whether to show the legend for this layer (default: true) */
+    shouldShowLegendBox?: boolean;
+    /** Alternative display name (overrides title in UI) */
+    layerNameChange?: string;
+}
+export interface LayerConfig {
+    id: string;
+    title: string;
+    type: "fill" | "line" | "circle";
+    url: string;
+    where?: string;
+    minZoom?: number;
+    maxZoom?: number;
+    opacity: number;
+    paint?: Record<string, unknown>;
+    outlinePaint?: Record<string, unknown>;
+    legend: LegendItem[];
+    popup: PopupConfig | null;
+    /** Display options for sidebar controls */
+    displayOptions?: LayerDisplayOptions;
+}
+/**
+ * Override configuration for popup behavior
+ */
+export interface PopupOverride {
+    showTime?: boolean;
+}
+/**
+ * Override configuration for layer styles
+ * Allows overriding the paint and legend from WebMap with custom values
+ */
+export interface LayerStyleOverride {
+    /** MapLibre paint properties to override */
+    paint?: Record<string, unknown>;
+    /** MapLibre outline paint properties (for polygons) */
+    outlinePaint?: Record<string, unknown>;
+    /** Legend items to override */
+    legend?: LegendItem[];
+    /** Override the layer type (fill, line, circle) */
+    type?: "fill" | "line" | "circle";
+}
+export interface CirclePaint {
+    "circle-radius": number | unknown[];
+    "circle-color": string | unknown[];
+    "circle-opacity"?: number;
+    "circle-stroke-width"?: number;
+    "circle-stroke-color"?: string;
+}
+export interface LinePaint {
+    "line-width": number | unknown[];
+    "line-color": string | unknown[];
+    "line-opacity"?: number;
+}
+export interface FillPaint {
+    "fill-color": string | unknown[];
+    "fill-opacity"?: number;
+    "fill-outline-color"?: string;
+}
+/**
+ * Configuration for ESRI tiled map layers (MapServer tiles)
+ * These are separate from WebMap feature layers and rendered as raster tiles.
+ * Used by topics like PickupPHL (collection day) and PlowPHL (plow status).
+ */
+export interface TiledLayerConfig {
+    /** Unique identifier for the tiled layer */
+    id: string;
+    /** Display title for the layer */
+    title: string;
+    /** ESRI MapServer tile URL (e.g., https://tiles.arcgis.com/.../MapServer) */
+    url: string;
+    /** Z-index for layer ordering (higher = on top) */
+    zIndex?: number;
+    /** Attribution text to display on the map */
+    attribution?: string;
+    /** Minimum zoom level at which the layer is visible */
+    minZoom?: number;
+    /** Maximum zoom level at which the layer is visible */
+    maxZoom?: number;
+    /** Initial opacity (0-1, default 1) */
+    opacity?: number;
+    /**
+     * Enable scale-based switching between tiled and dynamic rendering.
+     * When enabled, uses pre-rendered tiles when zoomed out (better performance)
+     * and switches to dynamic /export/ rendering when zoomed in (sharper imagery).
+     * The switch threshold is fetched from the MapServer's layer definitions.
+     */
+    scaleBasedRendering?: boolean;
+}

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export { transformWebMapToLayerConfigs } from './webmap-transformer';

package/dist/utils/webmap-transformer.d.ts

@@ -0,0 +1,222 @@
+import { LayerConfig, LegendItem, PopupConfig } from '../types';
+export interface EsriWebMap {
+    operationalLayers?: EsriOperationalLayer[];
+    [key: string]: unknown;
+}
+export interface EsriOperationalLayer {
+    id?: string;
+    title: string;
+    url?: string;
+    opacity?: number;
+    layerDefinition?: {
+        drawingInfo?: EsriDrawingInfo;
+        definitionExpression?: string;
+        minScale?: number;
+        maxScale?: number;
+    };
+    popupInfo?: EsriPopupInfo;
+    [key: string]: unknown;
+}
+export interface EsriDrawingInfo {
+    renderer?: EsriRenderer;
+    [key: string]: unknown;
+}
+export interface EsriRenderer {
+    type: "simple" | "uniqueValue" | "classBreaks";
+    symbol?: EsriSymbol;
+    label?: string;
+    field?: string;
+    field1?: string;
+    defaultSymbol?: EsriSymbol;
+    /** Minimum value for classBreaks renderer (used for label generation) */
+    minValue?: number;
+    uniqueValueInfos?: Array<{
+        value: string | number;
+        label?: string;
+        symbol?: EsriSymbol;
+    }>;
+    classBreakInfos?: Array<{
+        classMaxValue: number;
+        classMinValue?: number;
+        label?: string;
+        symbol?: EsriSymbol;
+    }>;
+    visualVariables?: Array<{
+        type: "colorInfo" | "sizeInfo" | "opacityInfo" | "rotationInfo";
+        field?: string;
+        stops?: Array<{
+            value: number;
+            color?: number[];
+            size?: number;
+            label?: string;
+        }>;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+}
+export interface EsriSymbol {
+    type: "esriSFS" | "esriSLS" | "esriSMS" | "esriPMS" | "esriPFS";
+    color?: number[];
+    size?: number;
+    width?: number;
+    outline?: {
+        color?: number[];
+        width?: number;
+        style?: string;
+    };
+    [key: string]: unknown;
+}
+export interface EsriPopupInfo {
+    title?: string;
+    fieldInfos?: Array<{
+        fieldName: string;
+        label?: string;
+        visible?: boolean;
+        format?: {
+            dateFormat?: string;
+            digitSeparator?: boolean;
+            places?: number;
+        };
+    }>;
+    [key: string]: unknown;
+}
+interface RendererResult {
+    paint: Record<string, unknown>;
+    legend: LegendItem[];
+    geomType: "fill" | "line" | "circle";
+    outlinePaint: Record<string, unknown> | null;
+}
+/**
+ * Convert Esri RGBA array to CSS color string
+ *
+ * Transforms Esri's RGBA color format [r, g, b, a] to CSS rgba() or hex.
+ * Esri uses 0-255 for alpha, CSS uses 0-1.
+ *
+ * @param color - Esri RGBA array [red, green, blue, alpha] where each value is 0-255
+ * @returns CSS color string (hex for opaque colors, rgba() for transparent)
+ * @example
+ * esriColorToCSS([255, 0, 0, 255]) // Returns "#ff0000"
+ * esriColorToCSS([255, 0, 0, 128]) // Returns "rgba(255, 0, 0, 0.50)"
+ */
+export declare function esriColorToCSS(color: number[] | null | undefined): string;
+/**
+ * Convert Esri opacity (0-1) to MapLibre opacity
+ */
+export declare function convertOpacity(opacity: number | undefined): number;
+/**
+ * Convert Esri minScale/maxScale to MapLibre minzoom/maxzoom
+ *
+ * Note: The relationship is inverted!
+ * - Esri minScale (large number) = zoomed out limit → MapLibre minzoom (small zoom level)
+ * - Esri maxScale (small number) = zoomed in limit → MapLibre maxzoom (large zoom level)
+ *
+ * Uses the formula: zoom ≈ log2(559082264 / scale)
+ * where 559082264 is the approximate scale at zoom level 0 at the equator.
+ *
+ * @param minScale - Esri minScale (layer disappears when zoomed out beyond this)
+ * @param maxScale - Esri maxScale (layer disappears when zoomed in beyond this)
+ * @returns Object with optional minZoom and maxZoom properties for MapLibre
+ * @example
+ * convertScaleToZoom(100000, 5000) // Returns { minZoom: 12.45, maxZoom: 17.11 }
+ */
+export declare function convertScaleToZoom(minScale?: number, maxScale?: number): {
+    minZoom?: number;
+    maxZoom?: number;
+};
+/**
+ * Transform Esri renderer to MapLibre paint styles
+ *
+ * Main renderer conversion function that handles all Esri renderer types:
+ * - Simple: Single symbol for all features
+ * - UniqueValue: Different symbols based on attribute field values
+ * - ClassBreaks: Graduated colors based on numeric ranges
+ *
+ * Converts Esri symbols and colors to MapLibre paint properties, generates
+ * legend entries, and handles outline styling for fill layers.
+ *
+ * The customLabelMap parameter (optional, only for unique value renderers):
+ * Enables hybrid approach where you can use renderer from one source (e.g., service)
+ * for field/colors/symbols, but labels from another source (e.g., service description)
+ * for human-readable names. This solves cases where:
+ * - Renderer has correct colors but only numeric labels (e.g., "11", "22")
+ * - Description field has detailed labels (e.g., "11 Residential Low Density")
+ * - Example: Land Use layer uses service renderer (c_dig2 field, correct colors) with
+ *   parsed description labels ("Residential Low Density" instead of just "11")
+ *
+ * @param drawingInfo - Esri drawing info containing renderer configuration
+ * @param layerOpacity - Layer opacity (0-1), defaults to 1
+ * @param customLabelMap - Optional map of field values to custom labels (unique value renderers only)
+ * @returns Object containing paint styles, legend items, geometry type, and optional outline paint
+ *
+ * @example Basic usage
+ * const result = transformEsriRenderer(layer.drawingInfo, 0.8);
+ * // result.paint = { 'fill-color': '#ff0000', 'fill-opacity': 0.8 }
+ * // result.legend = [{ type: 'fill', color: '#ff0000', label: 'Feature' }]
+ * // result.geomType = 'fill'
+ *
+ * @example With custom labels (hybrid approach for unique value renderers)
+ * const labelMap = new Map([
+ *   ['11', 'Residential Low Density'],
+ *   ['22', 'Commercial Business/Professional']
+ * ]);
+ * const result = transformEsriRenderer(serviceDrawingInfo, 1.0, labelMap);
+ * // result uses renderer's field/colors but labelMap's descriptive labels
+ */
+export declare function transformEsriRenderer(drawingInfo?: EsriDrawingInfo, layerOpacity?: number, customLabelMap?: Map<string, string>, layerTitle?: string): RendererResult;
+/**
+ * Transform Esri popupInfo to application popup configuration
+ *
+ * Converts Esri's popupInfo structure to the app's PopupConfig format.
+ * Filters to visible fields only and preserves field formatting options
+ * (date formats, number formatting, etc.).
+ *
+ * @param popupInfo - Esri popup info from layer definition
+ * @returns PopupConfig object with title and visible fields, or null if no popup info
+ * @example
+ * const popup = transformPopupConfig(layer.popupInfo);
+ * // Returns: { title: "{NAME}", fields: [{ field: "name", label: "Name" }] }
+ */
+export declare function transformPopupConfig(popupInfo?: EsriPopupInfo): PopupConfig | null;
+/**
+ * Generate legend entries from Esri renderer
+ *
+ * Convenience function that extracts just the legend items from the renderer
+ * transformation. This is the same as the legend array returned by
+ * transformEsriRenderer().
+ *
+ * @param drawingInfo - Esri drawing info containing renderer configuration
+ * @param layerOpacity - Layer opacity (0-1), defaults to 1
+ * @param customLabelMap - Optional map of field values to custom labels
+ * @returns Array of legend items with type, color, and label
+ * @example
+ * const legend = transformLegendConfig(layer.drawingInfo);
+ * // Returns: [{ type: 'fill', color: '#ff0000', label: 'Parks' }]
+ */
+export declare function transformLegendConfig(drawingInfo?: EsriDrawingInfo, layerOpacity?: number, customLabelMap?: Map<string, string>): LegendItem[];
+/**
+ * Extract Esri definitionExpression as where clause
+ *
+ * Simple extraction of the definitionExpression from Esri layer definition.
+ * This SQL-like expression filters which features are displayed on the map.
+ *
+ * @param layerDefinition - Esri layer definition object
+ * @returns Definition expression string, or undefined if not present
+ * @example
+ * const where = buildWhereClause(layer.layerDefinition);
+ * // Returns: "STATUS = 'Active' AND YEAR >= 2020"
+ */
+export declare function buildWhereClause(layerDefinition?: {
+    definitionExpression?: string;
+}): string | undefined;
+/**
+ * Transform Esri WebMap JSON to array of LayerConfig objects
+ *
+ * This is the main entry point for runtime transformation.
+ * Takes a WebMap JSON object and returns an array of layer configurations
+ * compatible with the app's LayerConfig interface.
+ *
+ * @param webMapJson The Esri WebMap JSON object
+ * @returns Array of LayerConfig objects ready to use with MapLibre
+ */
+export declare function transformWebMapToLayerConfigs(webMapJson: EsriWebMap): Promise<LayerConfig[]>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phila/layerboard",
-  "version": "3.0.0-beta.20",
+  "version": "3.0.0-beta.21",
   "type": "module",
   "description": "Vue 3 + MapLibre mapping framework for City of Philadelphia applications",
   "main": "./dist/index.js",