@element-editor/ui 0.0.0-stage → 0.2.1

package/dist/components/ui/ToolButton.d.cts

@@ -0,0 +1,19 @@
+import { TooltipSide } from './Tooltip.cjs';
+interface ToolButtonProps {
+    active: boolean;
+    onClick: () => void;
+    label: string;
+    shortcut?: string;
+    /** Shortcut id (`data-elm-shortcut`): the key flashes this button pressed. */
+    shortcutId?: string;
+    color?: 'blue' | 'emerald' | 'amber' | 'violet';
+    /** Tooltip side. Omit to auto-pick from toolbar position/direction. */
+    tooltipSide?: TooltipSide;
+    disabled?: boolean;
+    children: React.ReactNode;
+}
+export declare function ToolButton({ active, onClick, label, shortcut, shortcutId, color, tooltipSide, disabled, children }: ToolButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function ToolbarDivider({ vertical }?: {
+    vertical?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ui/ToolButton.d.ts

@@ -0,0 +1,19 @@
+import { TooltipSide } from './Tooltip.js';
+interface ToolButtonProps {
+    active: boolean;
+    onClick: () => void;
+    label: string;
+    shortcut?: string;
+    /** Shortcut id (`data-elm-shortcut`): the key flashes this button pressed. */
+    shortcutId?: string;
+    color?: 'blue' | 'emerald' | 'amber' | 'violet';
+    /** Tooltip side. Omit to auto-pick from toolbar position/direction. */
+    tooltipSide?: TooltipSide;
+    disabled?: boolean;
+    children: React.ReactNode;
+}
+export declare function ToolButton({ active, onClick, label, shortcut, shortcutId, color, tooltipSide, disabled, children }: ToolButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function ToolbarDivider({ vertical }?: {
+    vertical?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ui/Tooltip.d.cts

@@ -0,0 +1,12 @@
+import { ReactNode } from 'react';
+export type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
+interface TooltipProps {
+    content: ReactNode;
+    shortcut?: ReactNode;
+    side?: TooltipSide;
+    /** Wrap long text at a max width instead of one long line. */
+    multiline?: boolean;
+    children: ReactNode;
+}
+export declare function Tooltip({ content, shortcut, side, multiline, children }: TooltipProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ui/Tooltip.d.ts

@@ -0,0 +1,12 @@
+import { ReactNode } from 'react';
+export type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
+interface TooltipProps {
+    content: ReactNode;
+    shortcut?: ReactNode;
+    side?: TooltipSide;
+    /** Wrap long text at a max width instead of one long line. */
+    multiline?: boolean;
+    children: ReactNode;
+}
+export declare function Tooltip({ content, shortcut, side, multiline, children }: TooltipProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/ui/panelHeader.d.cts

@@ -0,0 +1,2 @@
+export declare const panelHeaderIconBtn = "items-center justify-center flex-shrink-0 p-[3px] rounded-elm-control text-elm-text-secondary hover:bg-(--elm-surface-hover,var(--color-gray-100)) dark:hover:bg-(--elm-surface-hover,var(--color-gray-700)) active:scale-[0.95] disabled:text-elm-text-disabled disabled:hover:bg-transparent disabled:active:scale-100 disabled:cursor-not-allowed transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-elm-focus-ring";
+export declare const panelHeaderBar = "h-10 box-border flex items-center flex-shrink-0 border-b border-elm-border bg-elm-surface-sunken";

package/dist/components/ui/panelHeader.d.ts

@@ -0,0 +1,2 @@
+export declare const panelHeaderIconBtn = "items-center justify-center flex-shrink-0 p-[3px] rounded-elm-control text-elm-text-secondary hover:bg-(--elm-surface-hover,var(--color-gray-100)) dark:hover:bg-(--elm-surface-hover,var(--color-gray-700)) active:scale-[0.95] disabled:text-elm-text-disabled disabled:hover:bg-transparent disabled:active:scale-100 disabled:cursor-not-allowed transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-elm-focus-ring";
+export declare const panelHeaderBar = "h-10 box-border flex items-center flex-shrink-0 border-b border-elm-border bg-elm-surface-sunken";

package/dist/components/ui/resizeEdge.d.cts

@@ -0,0 +1,4 @@
+/** Vertical edge on a panel's left side (col-resize). */
+export declare const resizeEdgeLeft = "absolute left-0 top-0 h-full w-1 z-20 cursor-col-resize after:inset-y-0 after:left-0 after:w-0.5 after:absolute after:transition-colors hover:after:bg-elm-focus-ring data-[dragging]:after:bg-elm-focus-ring";
+/** Horizontal edge on a panel's top side (row-resize). */
+export declare const resizeEdgeTop = "absolute top-0 left-0 right-0 h-1 z-10 cursor-row-resize after:inset-x-0 after:top-0 after:h-0.5 after:absolute after:transition-colors hover:after:bg-elm-focus-ring data-[dragging]:after:bg-elm-focus-ring";

package/dist/components/ui/resizeEdge.d.ts

@@ -0,0 +1,4 @@
+/** Vertical edge on a panel's left side (col-resize). */
+export declare const resizeEdgeLeft = "absolute left-0 top-0 h-full w-1 z-20 cursor-col-resize after:inset-y-0 after:left-0 after:w-0.5 after:absolute after:transition-colors hover:after:bg-elm-focus-ring data-[dragging]:after:bg-elm-focus-ring";
+/** Horizontal edge on a panel's top side (row-resize). */
+export declare const resizeEdgeTop = "absolute top-0 left-0 right-0 h-1 z-10 cursor-row-resize after:inset-x-0 after:top-0 after:h-0.5 after:absolute after:transition-colors hover:after:bg-elm-focus-ring data-[dragging]:after:bg-elm-focus-ring";

package/dist/contexts/ElementEditorConfigContext.d.cts

@@ -0,0 +1,351 @@
+import { ReactNode } from 'react';
+import { NetworkConfig } from '@element-editor/core';
+export type DrawTool = 'polygon' | 'rectangle' | 'circle' | 'line' | 'point' | 'freehand' | 'route' | 'picker' | 'measure' | 'search';
+/** The editing mode each tool turns on (`'search'` is a box, not a mode). The tools that add a feature are all but `measure`. */
+export declare const TOOL_MODES: {
+    readonly point: "place-point";
+    readonly line: "draw-line";
+    readonly polygon: "draw-polygon";
+    readonly route: "draw-route";
+    readonly circle: "draw-circle";
+    readonly rectangle: "draw-rect";
+    readonly freehand: "draw-freehand";
+    readonly picker: "pick-shape";
+    readonly measure: "measure";
+};
+/**
+ * Where a control can go (`config.ui.layout`): eight places on the map (four
+ * corners, four edge centers) and the two ends of the status bar under it.
+ */
+export type LayoutSlot = MapSlot | StatusSlot;
+/** The eight places on the map. */
+export type MapSlot = 'topLeft' | 'topCenter' | 'topRight' | 'leftCenter' | 'rightCenter' | 'bottomLeft' | 'bottomCenter' | 'bottomRight';
+/** The two ends of the status bar under the map. */
+export type StatusSlot = 'statusLeft' | 'statusRight';
+/** Every placeable built-in control. */
+export type LayoutControl = 'toolbar' | 'undo' | 'redo' | 'fitBounds' | 'locate' | 'zoomIndicator' | 'table' | 'schema' | 'geojson' | 'settings' | 'keyboard' | 'applyChanges' | 'attribution' | 'basemap';
+type MapControl = Exclude<LayoutControl, 'attribution'>;
+type StatusControl = Exclude<LayoutControl, 'toolbar' | 'applyChanges'>;
+/** Controls drawn as one joined pill on the map. No toolbar or basemap picker inside. */
+export type MapGroup = {
+    group: ReadonlyArray<Exclude<MapControl, 'toolbar' | 'basemap'> | 'separator'>;
+};
+/** Controls drawn as a tight cluster in the status bar. */
+export type StatusGroup = {
+    group: ReadonlyArray<Exclude<StatusControl, 'basemap'> | 'separator'>;
+};
+/** A map slot entry. No bare `'separator'` (nothing to draw it on over the tiles): put it in a group. */
+export type MapEntry = MapControl | MapGroup;
+export type StatusEntry = StatusControl | 'separator' | StatusGroup;
+export type MapSlotConfig = readonly MapEntry[] | {
+    items: readonly MapEntry[];
+    direction?: 'horizontal' | 'vertical';
+};
+/** Status slots are always horizontal. */
+export type StatusSlotConfig = readonly StatusEntry[];
+export type LayoutGroup = MapGroup | StatusGroup;
+export type LayoutEntry = MapEntry | StatusEntry;
+export type LayoutSlotConfig = MapSlotConfig | StatusSlotConfig;
+/** Where every built-in control goes (`config.ui.layout`). Each slot only takes the entries it can show. */
+export type LayoutConfig = {
+    [S in MapSlot]?: MapSlotConfig;
+} & {
+    [S in StatusSlot]?: StatusSlotConfig;
+};
+/** A slot after resolution: duplicates and invalid entries removed, groups normalised. */
+export type ResolvedLayout = Record<LayoutSlot, {
+    items: LayoutEntry[];
+    direction: 'horizontal' | 'vertical';
+}>;
+/** Slot order. A control listed twice stays at its first place in this order. */
+export declare const LAYOUT_SLOTS: readonly LayoutSlot[];
+/**
+ * Layout used when `ui.layout` isn't set.
+ * Deep-frozen (shared by every editor on the page). To change it, use {@link withLayout}.
+ */
+export declare const DEFAULT_LAYOUT: LayoutConfig;
+/**
+ * Drop separators that would show nothing useful: at the start or end of a
+ * section and right after another separator. Call it after hidden buttons
+ * are removed, so a separator next to a hidden button disappears too.
+ */
+export declare function collapseSeparators<T>(entries: readonly (T | 'separator')[]): (T | 'separator')[];
+/**
+ * Whether a placed control renders at all, given the visibility flags.
+ * `<ElementEditor>` uses it both to render a control and to decide whether a
+ * slot, group or the status bar has anything left to show, so they can't drift.
+ */
+export declare function isControlVisible(id: LayoutControl, ui: ResolvedConfig['ui'], ctx: {
+    readonly: boolean;
+    canSubmit: boolean;
+    hasBasemaps: boolean;
+}): boolean;
+/**
+ * A slot's entries with hidden controls removed, then empty groups and
+ * dangling separators (also inside groups) dropped.
+ */
+export declare function visibleLayoutEntries(entries: readonly LayoutEntry[], isVisible: (id: LayoutControl) => boolean): LayoutEntry[];
+/** A raster tile basemap (XYZ). Engine-neutral, so the Leaflet drop-in needs no MapLibre types. */
+export interface RasterBasemap {
+    id?: string;
+    label?: string;
+    thumbnail?: string;
+    url: string;
+    attribution: string;
+    maxZoom?: number;
+}
+/**
+ * Where the floating toolbar is anchored inside the map container
+ * (`ResolvedConfig.toolbar.position`, derived from the toolbar's layout slot).
+ *
+ * Eight positions — the four corners, the four edge-centers:
+ *
+ *   top-left     top-center     top-right
+ *                                left-center · right-center
+ *   bottom-left  bottom-center  bottom-right
+ */
+export type ToolbarPosition = 'top-left' | 'top-center' | 'top-right' | 'left-center' | 'right-center' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+export interface ElementEditorConfig {
+    /** Color theme. Default: 'system' (follows OS preference). */
+    mode?: 'light' | 'dark' | 'system';
+    /**
+     * Brand accent: any CSS colour (`'#ea580c'`, `'rebeccapurple'`, `'oklch(…)'`).
+     * The whole primary 50…950 scale (buttons, active tools, selection, checkboxes,
+     * links) is derived from it in CSS. Applied as `--elm-accent` on the editor
+     * root and on Element's portals; updates live. Default: undefined (blue).
+     * `<ElementEditor accentColor>` wins over this.
+     */
+    accentColor?: string;
+    /**
+     * Default colour of every feature (polygon outline + fill, line, point): any
+     * CSS colour. Opacity and weight keep their defaults. `getFeatureStyle` (per
+     * field) and the selected / hovered looks win over it. Updates live.
+     * `<ElementEditor featureColor>` wins over this. Default: undefined (slate `#475569`).
+     */
+    featureColor?: string;
+    /** Which drawing tools are available. Default: 'all'. */
+    tools?: DrawTool[] | 'all';
+    /**
+     * Namespace for everything this editor remembers in localStorage (theme,
+     * settings, units, shortcuts, window positions/sizes, panel widths, map view,
+     * basemap pick, last schema): `elm_theme` becomes `elm_<persistKey>_theme`.
+     * Give each editor on an origin its own key so they don't overwrite each other.
+     * Default: undefined (the shared `elm_*` keys).
+     */
+    persistKey?: string;
+    /** `false`: read and write nothing in localStorage (every reload starts from config). Default: true. */
+    persist?: boolean;
+    /**
+     * Every third-party server this editor talks to: basemap tiles, glyphs, sprite and elevation,
+     * the Picker's Overpass lookups, the Route tool's routing, the search box's geocoder, plus a
+     * `fetch` for Element's own requests. Per editor. `false` on a service hides what needs it.
+     * Map tiles are read when a basemap loads (changes apply on the next basemap switch). Headers
+     * for map resources: the MapLibre drop-in's `mapOptions.transformRequest`.
+     * See the "Third-party services and self-hosting" guide.
+     *
+     * @example network: { routing: { apiKey: ORS_KEY }, nominatim: { url: 'https://geo.example.com/search' } }
+     */
+    network?: NetworkConfig;
+    /** UI element visibility. All default to true. */
+    ui?: {
+        /** Drawing action hints in the active toolbar (e.g. "Click and drag to size"). Default: true */
+        hints?: boolean;
+        /** Data table panel (spreadsheet view of all features). Default: true */
+        dataTable?: boolean;
+        /** Layers/features list panel. Default: true */
+        layerList?: boolean;
+        /** Schema editor button. Default: true */
+        schemaEditor?: boolean;
+        /** GeoJSON editor button. Default: true */
+        geojsonEditor?: boolean;
+        /**
+         * Open the GeoJSON inspector when the editor mounts (initial state only;
+         * the user's toggles win afterwards), in the user's last Dock/Undock mode,
+         * docked beside the map by default. `'docked'` behaves like `true` (the
+         * dock is the default now). Ignored when
+         * `geojsonEditor` is false. With an adapter it sets `codeModalOpen`; render
+         * `GeoJSONModal` from it. Default: false
+         */
+        geojsonEditorOpen?: boolean | 'docked';
+        /** Editor settings button. Default: true */
+        settings?: boolean;
+        /** "Fit all features" zoom button. Default: true */
+        zoomToAll?: boolean;
+        /** Click-to-edit zoom level indicator. Default: true */
+        zoomIndicator?: boolean;
+        /** "Fly to my location" geolocation button. Default: true */
+        locateButton?: boolean;
+        /**
+         * Where every built-in control goes: a map of slots to ordered entries.
+         * Map slots: `topLeft`, `topCenter`, `topRight`, `leftCenter`,
+         * `rightCenter`, `bottomLeft`, `bottomCenter`, `bottomRight`; status bar
+         * (under the map): `statusLeft`, `statusRight`.
+         *
+         * An entry is a control id, `'separator'`, or `{ group: [...] }` (one
+         * joined pill). A slot is an array, or `{ items, direction }` to pick a
+         * direction (map slots; default vertical for `leftCenter`/`rightCenter`,
+         * horizontal elsewhere). The first item sits at the slot's edge.
+         *
+         * Controls not listed are hidden, except `'attribution'`, which stays on
+         * the map unless placed in a status slot. A control listed twice stays at
+         * its first place. The visibility flags (`zoomToAll`, `dataTable`, …) still
+         * apply on top.
+         *
+         * `'separator'` (a thin divider) only goes inside a group or in a status
+         * slot; directly in a map slot there's no surface to draw it on.
+         *
+         * To move, add or hide a few controls and keep the rest of the default,
+         * use {@link withLayout}: `layout: withLayout({ move: { table: 'topRight' } })`.
+         * Default: {@link DEFAULT_LAYOUT}.
+         *
+         * @example layout: { topCenter: ['toolbar'], bottomLeft: ['fitBounds', { group: ['table', 'separator', 'schema'] }], statusRight: ['attribution'] }
+         */
+        layout?: LayoutConfig;
+        /**
+         * Keyboard shortcuts control.
+         * Pass `false` to disable shortcuts entirely.
+         * Pass `{ enabled, show, mapZoom }` for fine-grained control.
+         * Default: `{ enabled: true, show: true, mapZoom: false }`.
+         *
+         * `mapZoom`: when true, intercepts Cmd/Ctrl + (`+`/`=`) and Cmd/Ctrl + (`-`)
+         * to zoom the map (only while the cursor is over the editor and no input
+         * is focused). Defaults to false because hijacking the browser's
+         * page-zoom shortcut is a behavior change consumers should opt into.
+         */
+        keyboardShortcuts?: boolean | {
+            enabled?: boolean;
+            show?: boolean;
+            mapZoom?: boolean;
+        };
+    };
+    /** Floating toolbar layout. Its place is the `'toolbar'` entry in `ui.layout`. */
+    toolbar?: {
+        /**
+         * How tool buttons are laid out inside the toolbar.
+         * 'vertical' hides the search bar and stacks tools top-to-bottom.
+         * Default: 'horizontal'.
+         */
+        direction?: 'horizontal' | 'vertical';
+    };
+    /** Measurement and number display settings. */
+    units?: {
+        /** Length unit. 'auto' picks metric/imperial from the browser locale. Default: 'auto' */
+        length?: 'metric' | 'imperial' | 'auto';
+        /** Area unit. 'auto' picks metric/imperial from the browser locale. Default: 'auto' */
+        area?: 'metric' | 'imperial' | 'auto';
+        /** Number display style. 'human' = "1.2 km", 'raw' = "1234.56 m". Default: 'human' */
+        display?: 'human' | 'raw';
+        /** Decimal places in 'raw' display mode. Default: 2 */
+        precision?: number;
+    };
+}
+export interface ResolvedConfig {
+    mode: 'light' | 'dark' | 'system';
+    /** Storage scope; pass the resolved config itself to the core storage helpers. */
+    persistKey: string | undefined;
+    persist: boolean;
+    /** `config.network` as given (`{}` when absent); `fetch` is a stable wrapper around the latest one. */
+    network: NetworkConfig;
+    accentColor: string | undefined;
+    featureColor: string | undefined;
+    tools: DrawTool[] | 'all';
+    ui: {
+        hints: boolean;
+        dataTable: boolean;
+        layerList: boolean;
+        schemaEditor: boolean;
+        geojsonEditor: boolean;
+        /** Already false when `geojsonEditor` is false. */
+        geojsonEditorOpen: boolean | 'docked';
+        settings: boolean;
+        zoomToAll: boolean;
+        zoomIndicator: boolean;
+        locateButton: boolean;
+        keyboardShortcuts: {
+            enabled: boolean;
+            show: boolean;
+            mapZoom: boolean;
+        };
+        /** Every slot, resolved from `ui.layout` (or `DEFAULT_LAYOUT`). Rendering reads only this. */
+        layout: ResolvedLayout;
+    };
+    toolbar: {
+        /** The toolbar's slot as a position (tooltip/popup sides, standalone placement). */
+        position: ToolbarPosition;
+        direction: 'horizontal' | 'vertical';
+    };
+    units: {
+        length: 'metric' | 'imperial' | 'auto';
+        area: 'metric' | 'imperial' | 'auto';
+        display: 'human' | 'raw';
+        precision: number;
+    };
+}
+/**
+ * Normalise a `ui.layout` map: every slot present, groups as `{ group }`,
+ * invalid entries and repeats dropped (first place wins, in `LAYOUT_SLOTS`
+ * order then array order) with a dev-only warning, dangling separators gone.
+ */
+export declare function resolveLayout(layout: LayoutConfig): ResolvedLayout;
+/** The slots a control may go to (`'attribution'` only in the status bar, `'toolbar'` / `'applyChanges'` only on the map). */
+export type SlotFor<C extends LayoutControl> = C extends 'attribution' ? StatusSlot : C extends 'toolbar' | 'applyChanges' ? MapSlot : LayoutSlot;
+/** Changes to a layout for {@link withLayout}. */
+export interface LayoutPatch {
+    /**
+     * Put a control in a slot, wherever it was before (or add it if it wasn't
+     * placed). It goes at the end of the slot (farthest from the slot's edge),
+     * or first with `{ slot, at: 'start' }`. A control moved out of a group
+     * leaves the rest of the group in place.
+     */
+    move?: {
+        [C in LayoutControl]?: SlotFor<C> | {
+            slot: SlotFor<C>;
+            at?: 'start' | 'end';
+        };
+    };
+    /** Take controls off the layout (the feature itself stays; use the `ui` flags to turn it off). Wins over `move`. */
+    hide?: readonly LayoutControl[];
+}
+/**
+ * A copy of `base` (default {@link DEFAULT_LAYOUT}) with a few controls moved,
+ * added or hidden, so you don't have to relist every other control:
+ *
+ * @example layout: withLayout({ move: { table: 'topRight', attribution: 'statusRight' }, hide: ['keyboard'] })
+ */
+export declare function withLayout(patch: LayoutPatch, base?: LayoutConfig): LayoutConfig;
+/**
+ * Dev-only check that a layout doesn't leave something unreachable by surprise:
+ * the drawing toolbar, the "Apply changes" button with `onSubmit`, undo/redo
+ * with keyboard shortcuts off. Looks at placement only, so turning a control
+ * off with its `ui` flag never counts. Returns one message per gap.
+ */
+export declare function layoutGaps(layout: ResolvedLayout, ctx: {
+    readonly: boolean;
+    canSubmit: boolean;
+    tools: readonly string[] | null;
+    shortcuts: boolean;
+}): string[];
+export declare function resolveConfig(config?: ElementEditorConfig): ResolvedConfig;
+/** Runtime user override for units. Persists to localStorage so the choice
+ *  sticks across reloads. Any provided field overrides the consumer-supplied
+ *  `config.units.*`; missing fields fall through to the consumer config. */
+export type UnitsOverride = Partial<{
+    length: 'metric' | 'imperial' | 'auto';
+    area: 'metric' | 'imperial' | 'auto';
+    display: 'human' | 'raw';
+    precision: number;
+}>;
+interface UnitsContextValue {
+    override: UnitsOverride;
+    setUnits: (next: UnitsOverride | ((prev: UnitsOverride) => UnitsOverride)) => void;
+    resetUnits: () => void;
+}
+export declare function ElementEditorConfigProvider({ config, children, }: {
+    config?: ElementEditorConfig;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useElementEditorConfig(): ResolvedConfig;
+/** Read/write the user's persisted units override. Use this from settings UIs;
+ *  consumers reading current values should prefer `useElementEditorConfig().units`. */
+export declare function useUnitsOverride(): UnitsContextValue;
+export {};