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

package/README.md

@@ -1,66 +1,213 @@
-# vue3-layerboard
+# @phila/layerboard
 
-A Vue 3 + MapLibre GL JS framework for building interactive map applications with layer management, measurement tools, and ArcGIS integration.
+A Vue 3 component framework for building interactive map applications powered by ArcGIS Online WebMaps and MapLibre GL JS. Provide a WebMap ID and get a full mapping app with layer management, popups, legends, search, and more.
 
-## Features
+## Live Examples
 
-- **MapLibre GL JS Integration** - Modern, performant vector tile mapping
-- **Layer Management** - Dynamic layer loading from ArcGIS Online web maps
-- **Measurement Tools** - Interactive area and distance measurement
-- **Geolocation** - User location tracking and display
-- **Legend & Layer Controls** - Configurable layer visibility and legends
-- **Popup System** - Feature identification and attribute display
+- [OpenMaps](https://openmaps.phila.gov) — flat layer list (all layers searchable)
+- [StreetSmartPHL](https://streetsmartphl.phila.gov) — topic-based layout (layers grouped in accordions)
 
 ## Installation
 
 ```sh
-npm install @phila/layerboard
+pnpm add @phila/layerboard
 ```
 
-## Peer Dependencies
+### Peer Dependencies
 
-This package requires the following peer dependencies:
+```sh
+pnpm add vue pinia maplibre-gl @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/vue-fontawesome
+```
 
-- `vue` ^3.5.0
-- `pinia` ^3.0.0
-- `maplibre-gl` ^5.0.0
-- `@fortawesome/fontawesome-svg-core` ^7.0.0
-- `@fortawesome/free-solid-svg-icons` ^7.0.0
-- `@fortawesome/vue-fontawesome` ^3.0.0
+## Quick Start
 
-## Development
+```vue
+<template>
+  <Layerboard
+    title="My Map App"
+    web-map-id="1596df70df0349e293ceec46a06ccc50"
+  />
+</template>
+
+<script setup>
+import { Layerboard } from "@phila/layerboard";
+import "@phila/layerboard/dist/layerboard.css";
+</script>
+```
 
-### Recommended IDE Setup
+This renders a full-screen map app with a sidebar listing all layers from the WebMap, complete with legends, opacity sliders, search, popups, and mobile responsiveness.
 
-[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
+## Layout Modes
 
-### Recommended Browser Setup
+### Flat Mode (default)
 
-- Chromium-based browsers (Chrome, Edge, Brave, etc.):
-  - [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
-  - [Turn on Custom Object Formatter in Chrome DevTools](http://bit.ly/object-formatters)
-- Firefox:
-  - [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
-  - [Turn on Custom Object Formatter in Firefox DevTools](https://fxdx.dev/firefox-devtools-custom-object-formatters/)
+All layers in a searchable list. Set `show-default-sidebar` to `true` (default) and the built-in `LayerPanel` renders in the sidebar.
 
-### Type Support for `.vue` Imports in TS
+### Topics Mode
 
-TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
+Group layers into collapsible accordions using the sidebar slot:
 
-### Project Setup
+```vue
+<Layerboard
+  title="StreetSmartPHL"
+  :web-map-id="webMapId"
+  :show-default-sidebar="false"
+>
+  <template #sidebar="{ layers, visibleLayers, toggleLayer, setOpacity }">
+    <TopicAccordion title="Paving" :expanded="true">
+      <LayerCheckboxSet
+        :layers="pavingLayers"
+        :visible-layer-ids="visibleLayers"
+        @toggle-layer="toggleLayer"
+        @set-opacity="setOpacity"
+      />
+    </TopicAccordion>
+  </template>
+</Layerboard>
+```
 
-```sh
-npm install
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | *required* | App title in header |
+| `webMapId` | `string` | *required* | ArcGIS Online WebMap ID |
+| `subtitle` | `string` | — | Subtitle in header |
+| `themeColor` | `string` | `"#0f4d90"` | Header/footer background color |
+| `showDefaultSidebar` | `boolean` | `true` | Show built-in LayerPanel (false for custom sidebar) |
+| `sidebarWidth` | `string` | `"30%"` | Sidebar width (CSS units) |
+| `sidebarLabel` | `string` | `"Layers"` | Mobile toggle label for sidebar view |
+| `mapLabel` | `string` | `"Map"` | Mobile toggle label for map view |
+| `fetchMetadata` | `boolean` | `false` | Fetch layer metadata from Carto |
+| `tiledLayers` | `TiledLayerConfig[]` | `[]` | ESRI MapServer tiled layers |
+| `dataSources` | `DataSourceConfig[]` | `[]` | External API data sources |
+| `layerStyleOverrides` | `Record<string, LayerStyleOverride>` | `{}` | Override paint/legend per layer |
+| `popupOverrides` | `Record<string, PopupOverride>` | `{}` | Override popup behavior per layer |
+| `initialZoom` | `number` | — | Initial map zoom level |
+| `initialCenter` | `[number, number]` | — | Initial map center `[lng, lat]` |
+| `cyclomediaConfig` | `CyclomediaConfig` | — | Cyclomedia street-level imagery config |
+| `pictometryCredentials` | `PictometryCredentials` | — | Pictometry oblique imagery credentials |
+
+### Control Positions
+
+All default to sensible positions. Each accepts `"top-left" | "top-right" | "bottom-left" | "bottom-right"`.
+
+| Prop | Default |
+|------|---------|
+| `basemapControlPosition` | `"top-right"` |
+| `navigationControlPosition` | `"bottom-right"` |
+| `geolocationControlPosition` | `"bottom-right"` |
+| `searchControlPosition` | `"top-left"` |
+| `drawControlPosition` | `"bottom-left"` (or `null` to remove) |
+| `cyclomediaButtonPosition` | `"top-right"` |
+| `pictometryButtonPosition` | `"top-right"` |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `configs-loaded` | `LayerConfig[]` | Layer configs loaded from WebMap |
+| `load-error` | `string` | Error message on load failure |
+| `zoom` | `number` | Zoom level changed |
+
+## Slots
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `header` | — | Replace default header |
+| `sidebar` | layer state + methods (see below) | Replace default LayerPanel |
+| `footer` | `{ openModal, closeModal, isModalOpen }` | Custom footer content |
+| `modal` | `{ closeModal }` | Modal content |
+
+### Sidebar Slot Scope
+
+The sidebar slot exposes the full layer state for building custom UIs:
+
+```typescript
+{
+  layers: Array<{ config: LayerConfig; component: string }>
+  visibleLayers: Set<string>
+  layerOpacities: Record<string, number>
+  loadingLayers: Set<string>
+  layerErrors: Record<string, string>
+  currentZoom: number
+  toggleLayer: (id: string) => void
+  setLayerVisible: (id: string, visible: boolean) => void
+  setLayersVisible: (ids: string[], visible: boolean) => void
+  setOpacity: (id: string, opacity: number) => void
+  // Tiled layers
+  tiledLayers: TiledLayerConfig[]
+  visibleTiledLayers: Set<string>
+  tiledLayerOpacities: Record<string, number>
+  toggleTiledLayer: (id: string) => void
+  setTiledLayerVisible: (id: string, visible: boolean) => void
+  setTiledLayerOpacity: (id: string, opacity: number) => void
+  // Data sources
+  dataSourcesState: Record<string, DataSourceState>
+  dataSourcesLoading: boolean
+  getDataSource: (id: string) => unknown | null
+  refetchDataSource: (id: string) => Promise<void>
+}
+```
+
+## Components
+
+All components are exported for building custom layouts:
+
+```typescript
+import {
+  Layerboard,          // Main framework component
+  LayerPanel,          // Flat layer list with search/legends/opacity
+  MapPanel,            // MapLibre map with layer rendering
+  TopicAccordion,      // Collapsible accordion for topic grouping
+  LayerCheckboxSet,    // Checkbox controls for layer toggling
+  LayerRadioButtonSet, // Radio buttons for mutually exclusive layers
+} from "@phila/layerboard";
+```
+
+## Types
+
+All types are exported:
+
+```typescript
+import type {
+  LayerConfig,
+  LayerDisplayOptions,
+  LayerStyleOverride,
+  LegendItem,
+  PopupConfig,
+  PopupField,
+  PopupOverride,
+  TiledLayerConfig,
+  DataSourceConfig,
+  DataSourceState,
+  LayerboardConfig,
+  TopicConfig,
+  FeatureFlags,
+  CyclomediaConfig,      // re-exported from @phila/phila-ui-map-core
+  PictometryCredentials,  // re-exported from @phila/phila-ui-map-core
+} from "@phila/layerboard";
 ```
 
-### Compile and Hot-Reload for Development
+## How It Works
+
+1. You provide an ArcGIS Online **WebMap ID**
+2. Layerboard fetches the WebMap JSON at runtime
+3. Esri renderers, symbols, scales, and popup configs are transformed into MapLibre-compatible layer configs
+4. Layers render on a MapLibre GL map — feature data is fetched from ArcGIS FeatureServer endpoints with spatial filtering and pagination
+5. Server-side geometry simplification (`maxAllowableOffset`) scales with zoom level for polygon layers
+
+## Development
 
 ```sh
-npm run dev
+pnpm install
+pnpm build        # type-check + vite build
 ```
 
-### Type-Check, Compile and Minify for Production
+### Publishing
 
 ```sh
-npm run build
+pnpm version prerelease   # bump beta version
+git push origin main
+git tag v<version> && git push origin v<version>   # triggers publish workflow
 ```

package/dist/components/LayerCheckboxSet.vue.d.ts

@@ -0,0 +1,36 @@
+import { LayerConfig } from '../types/layer';
+type __VLS_Props = {
+    /** Array of layer configurations to display */
+    layers: LayerConfig[];
+    /** Set of currently visible layer IDs */
+    visibleLayerIds: Set<string>;
+    /** Map of layer IDs to opacity values (0-1) */
+    layerOpacities?: Record<string, number>;
+    /** Set of layer IDs currently loading */
+    loadingLayerIds?: Set<string>;
+    /** Map of layer IDs to error messages */
+    layerErrors?: Record<string, string>;
+    /** Current map zoom level (for zoom-based availability) */
+    currentZoom?: number;
+    /** Whether to show opacity sliders (can be overridden per-layer) */
+    showOpacity?: boolean;
+    /** Whether to show legends (can be overridden per-layer) */
+    showLegend?: boolean;
+    /** Accessible label for the group */
+    groupLabel?: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    toggleLayer: (layerId: string) => any;
+    setOpacity: (layerId: string, opacity: number) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onToggleLayer?: ((layerId: string) => any) | undefined;
+    onSetOpacity?: ((layerId: string, opacity: number) => any) | undefined;
+}>, {
+    layerOpacities: Record<string, number>;
+    layerErrors: Record<string, string>;
+    currentZoom: number;
+    showOpacity: boolean;
+    showLegend: boolean;
+    loadingLayerIds: Set<string>;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLFieldSetElement>;
+export default _default;

package/dist/components/LayerPanel.vue.d.ts

@@ -0,0 +1,63 @@
+import { LayerConfig } from '../types/layer';
+type __VLS_Props = {
+    /** Array of layer configurations with component type */
+    layerList: Array<{
+        config: LayerConfig;
+        component: string;
+    }>;
+    /** Set of currently visible layer IDs */
+    visibleLayers: Set<string>;
+    /** Map of layer IDs to opacity values (0-1) */
+    layerOpacities: Record<string, number>;
+    /** Set of layer IDs currently loading */
+    loadingLayers: Set<string>;
+    /** Map of layer IDs to error messages */
+    layerErrors: Record<string, string>;
+    /** Current map zoom level */
+    currentZoom: number;
+    /** Current search query */
+    searchQuery: string;
+    /** Map of layer URLs to metadata page URLs */
+    layerMetadata: Record<string, string>;
+    /** Display mode: 'flat' for simple list, 'topics' for accordion grouping */
+    mode?: "flat" | "topics";
+    /** Whether to show the search box */
+    showSearch?: boolean;
+    /** Whether to show opacity sliders */
+    showOpacity?: boolean;
+    /** Whether to show legends */
+    showLegend?: boolean;
+    /** Placeholder text for search input */
+    searchPlaceholder?: string;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        topics?(_: {}): any;
+    };
+    refs: {};
+    rootEl: HTMLDivElement;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    toggleLayer: (layerId: string) => any;
+    setOpacity: (layerId: string, opacity: number) => any;
+    updateSearch: (query: string) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onToggleLayer?: ((layerId: string) => any) | undefined;
+    onSetOpacity?: ((layerId: string, opacity: number) => any) | undefined;
+    onUpdateSearch?: ((query: string) => any) | undefined;
+}>, {
+    mode: "flat" | "topics";
+    showSearch: boolean;
+    showOpacity: boolean;
+    showLegend: boolean;
+    searchPlaceholder: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/LayerRadioButtonSet.vue.d.ts

@@ -0,0 +1,39 @@
+import { LayerConfig } from '../types/layer';
+type __VLS_Props = {
+    /** Array of layer configurations to display */
+    layers: LayerConfig[];
+    /** Set of currently visible layer IDs */
+    visibleLayerIds: Set<string>;
+    /** Map of layer IDs to opacity values (0-1) */
+    layerOpacities?: Record<string, number>;
+    /** Set of layer IDs currently loading */
+    loadingLayerIds?: Set<string>;
+    /** Map of layer IDs to error messages */
+    layerErrors?: Record<string, string>;
+    /** Current map zoom level (for zoom-based availability) */
+    currentZoom?: number;
+    /** Whether to show opacity sliders (can be overridden per-layer) */
+    showOpacity?: boolean;
+    /** Whether to show legends (can be overridden per-layer) */
+    showLegend?: boolean;
+    /** Unique name for the radio button group */
+    groupName?: string;
+    /** Accessible label for the group */
+    groupLabel?: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    setOpacity: (layerId: string, opacity: number) => any;
+    selectLayer: (layerId: string, previousLayerIds: string[]) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onSetOpacity?: ((layerId: string, opacity: number) => any) | undefined;
+    onSelectLayer?: ((layerId: string, previousLayerIds: string[]) => any) | undefined;
+}>, {
+    layerOpacities: Record<string, number>;
+    layerErrors: Record<string, string>;
+    currentZoom: number;
+    showOpacity: boolean;
+    showLegend: boolean;
+    loadingLayerIds: Set<string>;
+    groupName: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;