@defra/interactive-map 0.0.3-alpha → 0.0.5-alpha

package/docs/api/map-style-config.md

@@ -0,0 +1,76 @@
+# MapStyleConfig
+
+Configuration for a map style (basemap appearance).
+
+## Properties
+
+---
+
+### `id`
+**Type:** `string`
+
+Unique identifier for the style. Used to reference the style programmatically.
+
+---
+
+### `url`
+**Type:** `string`
+**Required**
+
+URL to the style.json (Mapbox Style Specification).
+
+---
+
+### `label`
+**Type:** `string`
+
+Display label for the style. Shown in style switcher UI.
+
+---
+
+### `appColorScheme`
+**Type:** `'light' | 'dark'`
+
+App UI colour scheme. Ensures that panels, buttons, and controls use the appropriate colour scheme to match the map style.
+
+---
+
+### `mapColorScheme`
+**Type:** `'light' | 'dark'`
+
+Map colour scheme. Used to determine the style of controls rendered on the map, such as halo colours.
+
+---
+
+### `backgroundColor`
+**Type:** `string`
+
+CSS background colour. Allows the viewport background to match the background layer of the style, preventing flash of incorrect colour during load.
+
+---
+
+### `attribution`
+**Type:** `string`
+
+Attribution text for the map style.
+
+---
+
+### `logo`
+**Type:** `string`
+
+URL to logo image.
+
+---
+
+### `logoAltText`
+**Type:** `string`
+
+Alt text for the logo image.
+
+---
+
+### `thumbnail`
+**Type:** `string`
+
+URL to thumbnail image. Used in style switcher UI.

package/docs/api/marker-config.md

@@ -0,0 +1,51 @@
+# MarkerConfig
+
+Configuration for a map marker. Used in the `markers` option to define initial markers.
+
+## Properties
+
+---
+
+### `id`
+**Type:** `string`
+**Required**
+
+Unique marker identifier. Use this ID to reference the marker when calling `removeMarker()`.
+
+---
+
+### `coords`
+**Type:** `[number, number]`
+**Required**
+
+Coordinates [lng, lat] or [easting, northing] depending on the CRS of the map provider.
+
+---
+
+### `options`
+**Type:** `MarkerOptions`
+
+Optional marker appearance options. See [MarkerOptions](#markeroptions) below.
+
+---
+
+## MarkerOptions
+
+Options for customising marker appearance.
+
+### `color`
+**Type:** `string | Object<string, string>`
+
+Marker colour. Can be:
+- A single colour value applied to all map styles
+- An object keyed by map style ID, allowing different colours per style
+
+Overrides the default `markerColor` option.
+
+### `shape`
+**Type:** `string`
+
+Marker shape (e.g., `'pin'`). Overrides the default `markerShape` option.
+
+> [!NOTE]
+> Currently only `'pin'` is available. Additional shapes are planned for a future release.

package/docs/api/panel-definition.md

@@ -0,0 +1,117 @@
+# PanelDefinition
+
+Defines a panel that can be rendered in the UI at various breakpoints.
+
+## Properties
+
+---
+
+### `id`
+**Type:** `string`
+**Required**
+
+Unique panel identifier. Use this ID to associate a button with the panel via the `panelId` property.
+
+---
+
+### `label`
+**Type:** `string`
+**Required**
+
+Accessible label. Used as the panel heading.
+
+---
+
+### `mobile`
+**Type:** `PanelBreakpointConfig`
+**Required**
+
+Mobile breakpoint configuration. See [Breakpoint Configuration](#breakpoint-configuration) below.
+
+---
+
+### `tablet`
+**Type:** `PanelBreakpointConfig`
+**Required**
+
+Tablet breakpoint configuration. See [Breakpoint Configuration](#breakpoint-configuration) below.
+
+---
+
+### `desktop`
+**Type:** `PanelBreakpointConfig`
+**Required**
+
+Desktop breakpoint configuration. See [Breakpoint Configuration](#breakpoint-configuration) below.
+
+---
+
+### `render`
+**Type:** `ComponentType`
+
+A React/Preact component to render as the panel content. Receives [Context](./context.md) as props (or [PluginContext](../plugins/plugin-context.md) when used in a plugin manifest).
+
+```jsx
+const MyPanelContent = ({ context }) => {
+  const { pluginState } = context
+  return <div>Panel content here</div>
+}
+```
+
+> [!NOTE]
+> Use `render` when defining panels in a plugin manifest. For API methods like `addPanel()`, use `html` instead.
+
+---
+
+### `html`
+**Type:** `string`
+
+HTML content to render in the panel.
+
+> [!NOTE]
+> Use `html` when adding panels via API methods like `addPanel()`. For plugin manifests with dynamic content, use `render` instead.
+
+---
+
+### `showLabel`
+**Type:** `boolean`
+**Default:** `true`
+
+Whether to show the panel heading. If `false`, the heading is visually hidden but remains accessible to screen readers.
+
+---
+
+## Breakpoint Configuration
+
+Each breakpoint (`mobile`, `tablet`, `desktop`) accepts the following properties:
+
+### `slot`
+**Type:** `string`
+**Required**
+
+The [slot](./slots.md) where the panel should appear at this breakpoint. Slots are named regions in the UI layout.
+
+### `dismissable`
+**Type:** `boolean`
+
+Whether the panel can be dismissed (closed) by the user.
+
+### `exclusive`
+**Type:** `boolean`
+
+Whether the panel is exclusive. An exclusive panel will hide other panels when it becomes visible.
+
+### `initiallyOpen`
+**Type:** `boolean`
+
+Whether the panel is initially open when the app loads.
+
+### `modal`
+**Type:** `boolean`
+
+Whether the panel is modal. A modal panel overlays the map and requires user interaction to dismiss.
+
+### `width`
+**Type:** `string`
+
+Panel width. Accepts any valid CSS width value (e.g., `'300px'`, `'50%'`).

package/docs/api/slots.md

@@ -0,0 +1,25 @@
+# Slots
+
+Slots are named regions in the UI where buttons, controls, and panels can be placed. The slot system enables responsive layouts by allowing elements to appear in different locations at different breakpoints.
+
+## Slot Map
+
+<!-- TODO: Add visual diagram showing slot locations -->
+
+## Available Slots
+
+<!-- TODO: Document available slots and their positions -->
+
+## Usage
+
+Specify a slot in the breakpoint configuration for buttons, controls, or panels:
+
+```js
+{
+  mobile: { slot: 'top-left' },
+  tablet: { slot: 'top-left' },
+  desktop: { slot: 'top-left' }
+}
+```
+
+Elements in the same slot are rendered in order based on their `order` property (where supported).