silversonicaxel/maplibre-layer-factory

1. What this repository is

- maplibre-layer-factory is a TypeScript UI plugin for MapLibre GL JS. It is not a standalone app or backend service; it is a control library that gets mounted into an existing MapLibre map via map.addControl(...).

2. Top-level shape of the repo

- The repository is very small and library-focused: one source entrypoint in src/index.ts, one stylesheet in src/index.css, and a Vite setup (vite.config.ts) for building/distributing the package.

- index.html is likely a local demo/dev entry used by Vite, not a production surface.

3. Primary runtime boundary

- The library lives entirely on the browser side and depends on the MapLibre GL JS runtime.

- Its main integration boundary is the MapLibre control API: it receives a map instance from the host app and renders a custom control into the map UI.

4. Core responsibility

- The library’s job is to inspect layer metadata and render a selector UI that toggles layer visibility.

- It abstracts the complexity of layer switching into a reusable “factory” control, rather than forcing the app to build a custom legend or layer switcher.

5. Main UI subsystems

- The README describes a control structure with:

- a container

- a toggle

- a panel

- panel sections for layers, label, and overlays

- This suggests the entrypoint builds a composite control with both a collapsed/expanded state and separate rendering paths for different layer types.

6. Layer classification flow

- Each layer is driven by a metadata object with fields like name, caption, placeholder, ignore, overlay, and group.

- The control likely partitions incoming layers into:

- base layers: single-select, rendered as squared buttons

- overlay layers: multi-select, rendered as checkboxes

- ignored layers: excluded from the UI entirely

- Overlays can also be grouped under collapsible accordion sections.

7. Configuration and styling flow

- The factory accepts a single options object with:

- orientation for layout

- panel and button styles

- label styles

- overlay styles

- a withLabel flag

- Styling is intentionally split into granular style slots, which implies the control assembles DOM elements and applies inline style objects or style mappings per region/state.

8. State and interaction model

- The control likely maintains local UI state for:

- panel open/closed state

- currently selected base layer

- overlay checkbox states

- accordion open/closed state for overlay groups

- Interaction is centered on showing/hiding MapLibre layers, so the control acts as the state bridge between the DOM and the map style layer visibility.

9. Asset and presentation layer

- src/index.css is a dedicated styling layer, meaning the package ships a base visual skin in addition to runtime-generated styles.

- Consumers are expected to import that CSS alongside the library, so the architecture separates default presentation from runtime customization.

10. Build/distribution architecture

- The presence of package.json, package-lock.json, tsconfig.json, and vite.config.ts indicates a bundled library distribution rather than raw source publishing.

- Vite is the build tool, likely producing a browser-ready package and associated stylesheet for npm consumption.

11. Consumer integration boundary

- The host application is responsible for:

- creating the MapLibre map

- supplying layer metadata/configuration

- importing the library and its CSS

- mounting the control into a chosen map corner

- The plugin does not appear to own map creation, layer loading, or data fetching.

12. Notable architectural characteristic

- This is a single-feature library with a shallow file tree, so most architecture is concentrated in one entrypoint rather than spread across services or modules.

- For a diagram, the best representation is: host app → MapLibre map instance → custom layer factory control → DOM UI + layer visibility updates.