@phila/layerboard 3.0.0-beta.3 → 3.0.0-beta.30

package/README.md

@@ -1,78 +1,206 @@
-# 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
 
-## Design Decisions
+```vue
+<template>
+  <Layerboard title="My Map App" web-map-id="1596df70df0349e293ceec46a06ccc50" />
+</template>
 
-### Compact Text Field Styling
+<script setup>
+import { Layerboard } from "@phila/layerboard";
+import "@phila/layerboard/dist/layerboard.css";
+</script>
+```
 
-The phila-ui TextField component has a standard height of 56px, designed for form inputs where touch targets and readability are priorities. In the layerboard context (sidebar filter and map search control), we intentionally use a more compact ~40px version to save vertical space.
+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.
 
-This is achieved through CSS overrides in:
-- **LayerPanel.vue** - for the layer filter search box
-- **MapPanel.vue** - for the MapSearchControl on the map
+## Layout Modes
 
-The overrides remove padding from `.state-layer` and `.content` elements. See the detailed comments in those files for the technical breakdown.
+### Flat Mode (default)
 
-## Development
+All layers in a searchable list. Set `show-default-sidebar` to `true` (default) and the built-in `LayerPanel` renders in the sidebar.
 
-### Recommended IDE Setup
+### Topics Mode
 
-[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
+Group layers into collapsible accordions using the sidebar slot:
 
-### Recommended Browser 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>
+```
 
-- 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/)
+## 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>
+}
+```
 
-### Type Support for `.vue` Imports in TS
+## Components
 
-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.
+All components are exported for building custom layouts:
 
-### Project Setup
+```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";
+```
 
-```sh
-npm install
+## 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,37 @@
+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>;
+    groupLabel: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLFieldSetElement>;
+export default _default;

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

@@ -0,0 +1,7 @@
+import { LegendItem } from '../types/layer';
+type __VLS_Props = {
+    items: LegendItem[];
+    label: string;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLUListElement>;
+export default _default;

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

@@ -0,0 +1,11 @@
+type __VLS_Props = {
+    layerId: string;
+    layerName: string;
+    opacity: number;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    "update:opacity": (opacity: number) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:opacity"?: ((opacity: number) => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+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,40 @@
+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>;
+    groupLabel: string;
+    groupName: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+export default _default;

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

@@ -0,0 +1,7 @@
+type __VLS_Props = {
+    loading: boolean;
+    error: string | null;
+    unavailable: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;