@element-editor/ui 0.0.0-stage → 0.2.1

package/dist/hooks/useInlineRename.d.cts

@@ -0,0 +1,26 @@
+interface UseInlineRenameOptions {
+    initialLabel: string;
+    onCommit: (name: string) => void;
+    autoFocus?: boolean;
+    /** When this becomes true, activates rename mode (parent-driven, e.g. via Tab navigation). */
+    activate?: boolean;
+    /** Called after commit or cancel, so parent can clear its activation id. */
+    onEnd?: () => void;
+    /** Called when Tab / Shift+Tab is pressed inside the input. Parent should commit-and-advance. */
+    onTab?: (direction: 'next' | 'prev') => void;
+    /** No renaming (readonly editor): `startRenaming` and `activate` do nothing. */
+    disabled?: boolean;
+}
+export declare function useInlineRename({ initialLabel, onCommit, autoFocus, activate, onEnd, onTab, disabled }: UseInlineRenameOptions): {
+    isRenaming: boolean;
+    startRenaming: (label: string) => void;
+    inputProps: {
+        ref: import('react').RefObject<HTMLInputElement | null>;
+        value: string;
+        onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+        onBlur: () => void;
+        onKeyDown: (e: React.KeyboardEvent) => void;
+        onClick: (e: React.MouseEvent) => void;
+    };
+};
+export {};

package/dist/hooks/useInlineRename.d.ts

@@ -0,0 +1,26 @@
+interface UseInlineRenameOptions {
+    initialLabel: string;
+    onCommit: (name: string) => void;
+    autoFocus?: boolean;
+    /** When this becomes true, activates rename mode (parent-driven, e.g. via Tab navigation). */
+    activate?: boolean;
+    /** Called after commit or cancel, so parent can clear its activation id. */
+    onEnd?: () => void;
+    /** Called when Tab / Shift+Tab is pressed inside the input. Parent should commit-and-advance. */
+    onTab?: (direction: 'next' | 'prev') => void;
+    /** No renaming (readonly editor): `startRenaming` and `activate` do nothing. */
+    disabled?: boolean;
+}
+export declare function useInlineRename({ initialLabel, onCommit, autoFocus, activate, onEnd, onTab, disabled }: UseInlineRenameOptions): {
+    isRenaming: boolean;
+    startRenaming: (label: string) => void;
+    inputProps: {
+        ref: import('react').RefObject<HTMLInputElement | null>;
+        value: string;
+        onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+        onBlur: () => void;
+        onKeyDown: (e: React.KeyboardEvent) => void;
+        onClick: (e: React.MouseEvent) => void;
+    };
+};
+export {};

package/dist/hooks/useJumpToFeature.d.cts

@@ -0,0 +1,3 @@
+import { GeoJSONFeature } from '@element-editor/core';
+/** Moves the map to a feature: pans to a point, fits anything else. */
+export declare function useJumpToFeature(): (f: GeoJSONFeature) => void;

package/dist/hooks/useJumpToFeature.d.ts

@@ -0,0 +1,3 @@
+import { GeoJSONFeature } from '@element-editor/core';
+/** Moves the map to a feature: pans to a point, fits anything else. */
+export declare function useJumpToFeature(): (f: GeoJSONFeature) => void;

package/dist/hooks/useKeyboardShortcuts.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Predicate for window/document key listeners: true when the event belongs to
+ * the editor of the surrounding GeoStore (same rules as the global shortcuts).
+ * Use it in every window-level keydown/keyup that acts on editor state, so a
+ * key pressed in the host page or in a second editor is ignored. Stable
+ * identity; reads the scope at call time.
+ */
+export declare function useIsEventForEditor(): (e: Event) => boolean;
+export declare function useKeyboardShortcuts(container?: HTMLElement | null): void;

package/dist/hooks/useKeyboardShortcuts.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Predicate for window/document key listeners: true when the event belongs to
+ * the editor of the surrounding GeoStore (same rules as the global shortcuts).
+ * Use it in every window-level keydown/keyup that acts on editor state, so a
+ * key pressed in the host page or in a second editor is ignored. Stable
+ * identity; reads the scope at call time.
+ */
+export declare function useIsEventForEditor(): (e: Event) => boolean;
+export declare function useKeyboardShortcuts(container?: HTMLElement | null): void;

package/dist/hooks/useNominatim.d.cts

@@ -0,0 +1,24 @@
+export interface NominatimGeometry {
+    type: 'Point' | 'LineString' | 'Polygon' | 'MultiPolygon';
+    coordinates: unknown;
+}
+export interface NominatimResult {
+    place_id: number;
+    display_name: string;
+    lat: string;
+    lon: string;
+    type: string;
+    addresstype: string;
+    geojson?: NominatimGeometry;
+}
+interface UseNominatimReturn {
+    results: NominatimResult[];
+    loading: boolean;
+    error: string | null;
+    /** Run the pending (debounced) search now, e.g. on Enter. No-op when none is waiting. */
+    flush: () => void;
+}
+export declare const NOMINATIM_URL = "https://nominatim.openstreetmap.org/search";
+export declare const NOMINATIM_ATTRIBUTION = "Geocoding by <a href=\"https://nominatim.org/\" target=\"_blank\" rel=\"noopener\">Nominatim</a>";
+export declare function useNominatim(query: string): UseNominatimReturn;
+export {};

package/dist/hooks/useNominatim.d.ts

@@ -0,0 +1,24 @@
+export interface NominatimGeometry {
+    type: 'Point' | 'LineString' | 'Polygon' | 'MultiPolygon';
+    coordinates: unknown;
+}
+export interface NominatimResult {
+    place_id: number;
+    display_name: string;
+    lat: string;
+    lon: string;
+    type: string;
+    addresstype: string;
+    geojson?: NominatimGeometry;
+}
+interface UseNominatimReturn {
+    results: NominatimResult[];
+    loading: boolean;
+    error: string | null;
+    /** Run the pending (debounced) search now, e.g. on Enter. No-op when none is waiting. */
+    flush: () => void;
+}
+export declare const NOMINATIM_URL = "https://nominatim.openstreetmap.org/search";
+export declare const NOMINATIM_ATTRIBUTION = "Geocoding by <a href=\"https://nominatim.org/\" target=\"_blank\" rel=\"noopener\">Nominatim</a>";
+export declare function useNominatim(query: string): UseNominatimReturn;
+export {};

package/dist/hooks/usePanelOffset.d.cts

@@ -0,0 +1,14 @@
+import { RefObject } from 'react';
+/**
+ * Publish the right-hand panels' width (open layers panel + docked GeoJSON
+ * inspector; 0 while the table is fullscreen) as --elm-panel-offset on the
+ * nearest Element root, so map controls under them (attribution) can clear
+ * them in every host. Called by both panels; both write the same value from
+ * the same store state, so whichever is mounted keeps it right. Layout effect:
+ * lands in the same frame as the panels' own `right` transition starts.
+ *
+ * Also keeps uiStore `narrow` in step with the root's width (the editor's,
+ * not the viewport's). A narrow editor's panels overlay the map, so they add
+ * nothing to the offset.
+ */
+export declare function usePanelOffset(ref: RefObject<HTMLElement | null>, enabled?: boolean): void;

package/dist/hooks/usePanelOffset.d.ts

@@ -0,0 +1,14 @@
+import { RefObject } from 'react';
+/**
+ * Publish the right-hand panels' width (open layers panel + docked GeoJSON
+ * inspector; 0 while the table is fullscreen) as --elm-panel-offset on the
+ * nearest Element root, so map controls under them (attribution) can clear
+ * them in every host. Called by both panels; both write the same value from
+ * the same store state, so whichever is mounted keeps it right. Layout effect:
+ * lands in the same frame as the panels' own `right` transition starts.
+ *
+ * Also keeps uiStore `narrow` in step with the root's width (the editor's,
+ * not the viewport's). A narrow editor's panels overlay the map, so they add
+ * nothing to the offset.
+ */
+export declare function usePanelOffset(ref: RefObject<HTMLElement | null>, enabled?: boolean): void;

package/dist/hooks/useResizablePanel.d.cts

@@ -0,0 +1,4 @@
+export declare function useResizablePanel(storageKey: string, defaultWidth: number, min: number, max: number): {
+    width: number;
+    onHandleMouseDown: (e: React.MouseEvent) => void;
+};

package/dist/hooks/useResizablePanel.d.ts

@@ -0,0 +1,4 @@
+export declare function useResizablePanel(storageKey: string, defaultWidth: number, min: number, max: number): {
+    width: number;
+    onHandleMouseDown: (e: React.MouseEvent) => void;
+};

package/dist/hooks/useRootTokens.d.cts

@@ -0,0 +1,27 @@
+import { CSSProperties } from 'react';
+/**
+ * The public design tokens. Element never declares them itself (its
+ * defaults live in private `--_elm-*` variables, see ui/src/styles/shared.css),
+ * so a token with a non-empty computed value on the editor root is one the
+ * integrator set: through a stylesheet rule (`.my-editor[data-elm-theme="dark"]`,
+ * `[data-elm-theme]`, `:root`, an ancestor class), through `style`, or through
+ * `accentColor`. Keep in sync with shared.css and docs/guides/theming.md.
+ */
+export declare const THEME_TOKENS: readonly ["--elm-font", "--elm-font-mono", "--elm-radius", "--elm-radius-control", "--elm-shadow", "--elm-shadow-raised", "--elm-shadow-control", "--elm-surface", "--elm-surface-raised", "--elm-surface-sunken", "--elm-surface-hover", "--elm-control-hover", "--elm-text", "--elm-text-secondary", "--elm-text-muted", "--elm-text-subtle", "--elm-text-disabled", "--elm-border", "--elm-border-subtle", "--elm-border-strong", "--elm-focus-ring", "--elm-tooltip", "--elm-tooltip-text"];
+/**
+ * The root's custom tokens as resolved by the browser (`{ '--elm-surface': '#fdf8f0', … }`),
+ * or undefined when none is set. Reads computed style: call it on theme changes, not per frame.
+ */
+export declare function readRootTokens(root: Element | null | undefined): Record<string, string> | undefined;
+/**
+ * The editor root's custom tokens, kept current: re-read (once per frame at most)
+ * when the root's style/class/mode, `<html>`'s style/class or the page's
+ * stylesheets change. Same object while nothing changed. Body-level portals
+ * spread it (through `useAccentStyle()`), because they sit outside the root and
+ * a rule like `.my-editor[data-elm-theme="dark"] { --elm-surface: … }` never
+ * matches them.
+ */
+export declare function useRootTokens(root: HTMLElement | null | undefined): Record<string, string> | undefined;
+/** The editor root's custom tokens for portals; provided by `<ElementEditor>` and `ElementEditorUIProvider`. */
+export declare const RootTokensContext: import('react').Context<CSSProperties | undefined>;
+export declare function applyRootTokens(el: HTMLElement, root: Element | null | undefined): void;

package/dist/hooks/useRootTokens.d.ts

@@ -0,0 +1,27 @@
+import { CSSProperties } from 'react';
+/**
+ * The public design tokens. Element never declares them itself (its
+ * defaults live in private `--_elm-*` variables, see ui/src/styles/shared.css),
+ * so a token with a non-empty computed value on the editor root is one the
+ * integrator set: through a stylesheet rule (`.my-editor[data-elm-theme="dark"]`,
+ * `[data-elm-theme]`, `:root`, an ancestor class), through `style`, or through
+ * `accentColor`. Keep in sync with shared.css and docs/guides/theming.md.
+ */
+export declare const THEME_TOKENS: readonly ["--elm-font", "--elm-font-mono", "--elm-radius", "--elm-radius-control", "--elm-shadow", "--elm-shadow-raised", "--elm-shadow-control", "--elm-surface", "--elm-surface-raised", "--elm-surface-sunken", "--elm-surface-hover", "--elm-control-hover", "--elm-text", "--elm-text-secondary", "--elm-text-muted", "--elm-text-subtle", "--elm-text-disabled", "--elm-border", "--elm-border-subtle", "--elm-border-strong", "--elm-focus-ring", "--elm-tooltip", "--elm-tooltip-text"];
+/**
+ * The root's custom tokens as resolved by the browser (`{ '--elm-surface': '#fdf8f0', … }`),
+ * or undefined when none is set. Reads computed style: call it on theme changes, not per frame.
+ */
+export declare function readRootTokens(root: Element | null | undefined): Record<string, string> | undefined;
+/**
+ * The editor root's custom tokens, kept current: re-read (once per frame at most)
+ * when the root's style/class/mode, `<html>`'s style/class or the page's
+ * stylesheets change. Same object while nothing changed. Body-level portals
+ * spread it (through `useAccentStyle()`), because they sit outside the root and
+ * a rule like `.my-editor[data-elm-theme="dark"] { --elm-surface: … }` never
+ * matches them.
+ */
+export declare function useRootTokens(root: HTMLElement | null | undefined): Record<string, string> | undefined;
+/** The editor root's custom tokens for portals; provided by `<ElementEditor>` and `ElementEditorUIProvider`. */
+export declare const RootTokensContext: import('react').Context<CSSProperties | undefined>;
+export declare function applyRootTokens(el: HTMLElement, root: Element | null | undefined): void;

package/dist/hooks/useSearchState.d.cts

@@ -0,0 +1,23 @@
+import { NominatimResult } from './useNominatim.cjs';
+export declare function useSearchState(): {
+    query: string;
+    setQuery: import('react').Dispatch<import('react').SetStateAction<string>>;
+    setOpen: import('react').Dispatch<import('react').SetStateAction<boolean>>;
+    showDropdown: boolean;
+    containerRef: import('react').RefObject<HTMLDivElement | null>;
+    inputRef: import('react').RefObject<HTMLInputElement | null>;
+    focused: boolean;
+    setFocused: import('react').Dispatch<import('react').SetStateAction<boolean>>;
+    results: NominatimResult[];
+    loading: boolean;
+    error: string | null;
+    flyToResult: (r: NominatimResult) => void;
+    handleAdd: (r: NominatimResult) => void;
+    handleAddShape: (r: NominatimResult) => void;
+    clear: () => void;
+    activeIndex: number;
+    setActiveIndex: import('react').Dispatch<import('react').SetStateAction<number>>;
+    handleInputKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => void;
+};
+/** The key was pressed in a CodeMirror editor (the GeoJSON inspector), which has its own Cmd+F. */
+export declare function inCodeEditor(e: KeyboardEvent): boolean;

package/dist/hooks/useSearchState.d.ts

@@ -0,0 +1,23 @@
+import { NominatimResult } from './useNominatim.js';
+export declare function useSearchState(): {
+    query: string;
+    setQuery: import('react').Dispatch<import('react').SetStateAction<string>>;
+    setOpen: import('react').Dispatch<import('react').SetStateAction<boolean>>;
+    showDropdown: boolean;
+    containerRef: import('react').RefObject<HTMLDivElement | null>;
+    inputRef: import('react').RefObject<HTMLInputElement | null>;
+    focused: boolean;
+    setFocused: import('react').Dispatch<import('react').SetStateAction<boolean>>;
+    results: NominatimResult[];
+    loading: boolean;
+    error: string | null;
+    flyToResult: (r: NominatimResult) => void;
+    handleAdd: (r: NominatimResult) => void;
+    handleAddShape: (r: NominatimResult) => void;
+    clear: () => void;
+    activeIndex: number;
+    setActiveIndex: import('react').Dispatch<import('react').SetStateAction<number>>;
+    handleInputKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => void;
+};
+/** The key was pressed in a CodeMirror editor (the GeoJSON inspector), which has its own Cmd+F. */
+export declare function inCodeEditor(e: KeyboardEvent): boolean;

package/dist/hooks/useServiceAttribution.d.cts

@@ -0,0 +1,13 @@
+import { NetworkConfig, RoutingConfig } from '@element-editor/core';
+/** Credits for the services in use: the geocoder while search is offered, the router while the Route tool is. */
+export declare function serviceAttribution(network: NetworkConfig, on: {
+    search: boolean;
+    route: boolean;
+}): string[];
+/**
+ * This editor's routing: `config.network.routing`, with the deprecated `routingApiKey` prop as the
+ * key when the config gives none (`network.routing.apiKey` wins).
+ */
+export declare function useRouting(routingApiKey?: string): RoutingConfig | false;
+/** `serviceAttribution` for this editor, joined with " | " (a string, so it's stable while nothing changes). */
+export declare function useServiceAttribution(routingApiKey?: string): string;

package/dist/hooks/useServiceAttribution.d.ts

@@ -0,0 +1,13 @@
+import { NetworkConfig, RoutingConfig } from '@element-editor/core';
+/** Credits for the services in use: the geocoder while search is offered, the router while the Route tool is. */
+export declare function serviceAttribution(network: NetworkConfig, on: {
+    search: boolean;
+    route: boolean;
+}): string[];
+/**
+ * This editor's routing: `config.network.routing`, with the deprecated `routingApiKey` prop as the
+ * key when the config gives none (`network.routing.apiKey` wins).
+ */
+export declare function useRouting(routingApiKey?: string): RoutingConfig | false;
+/** `serviceAttribution` for this editor, joined with " | " (a string, so it's stable while nothing changes). */
+export declare function useServiceAttribution(routingApiKey?: string): string;

package/dist/hooks/useWindowEscape.d.cts

@@ -0,0 +1,25 @@
+import { RefObject } from 'react';
+/** Marks a floating window's root: the editor's global Escape handler leaves keys pressed inside it to the window. */
+export declare const WINDOW_ATTR = "data-elm-window";
+/**
+ * Close the editor's topmost open floating window (keyboard shortcuts,
+ * settings, schema). Called by the global Escape handler once there is
+ * nothing else to cancel (no dialog, tool, edit or selection), so Escape
+ * closes a window opened by its shortcut (K) without first clicking into it.
+ * Returns whether one was closed.
+ */
+export declare function closeTopWindow(uiStore: object): boolean;
+/**
+ * Escape + focus return for a floating window:
+ * - Escape pressed inside the window closes it (unless something inside
+ *   handled it first, e.g. a key-capture field or a rename input).
+ * - While open it's registered for `closeTopWindow` (Escape from the map).
+ * - On close, focus goes back to what had it when the window opened (the
+ *   button or the map), if it was inside the window or nowhere.
+ * Put `{...{ [WINDOW_ATTR]: '' }}` on the window root and pass its ref.
+ * `topWindow: false` (a docked panel): Escape inside still closes it, but
+ * Escape from the map doesn't.
+ */
+export declare function useWindowEscape(ref: RefObject<HTMLElement | null>, open: boolean, onClose: () => void, zIndex: number, { topWindow }?: {
+    topWindow?: boolean;
+}): void;

package/dist/hooks/useWindowEscape.d.ts

@@ -0,0 +1,25 @@
+import { RefObject } from 'react';
+/** Marks a floating window's root: the editor's global Escape handler leaves keys pressed inside it to the window. */
+export declare const WINDOW_ATTR = "data-elm-window";
+/**
+ * Close the editor's topmost open floating window (keyboard shortcuts,
+ * settings, schema). Called by the global Escape handler once there is
+ * nothing else to cancel (no dialog, tool, edit or selection), so Escape
+ * closes a window opened by its shortcut (K) without first clicking into it.
+ * Returns whether one was closed.
+ */
+export declare function closeTopWindow(uiStore: object): boolean;
+/**
+ * Escape + focus return for a floating window:
+ * - Escape pressed inside the window closes it (unless something inside
+ *   handled it first, e.g. a key-capture field or a rename input).
+ * - While open it's registered for `closeTopWindow` (Escape from the map).
+ * - On close, focus goes back to what had it when the window opened (the
+ *   button or the map), if it was inside the window or nowhere.
+ * Put `{...{ [WINDOW_ATTR]: '' }}` on the window root and pass its ref.
+ * `topWindow: false` (a docked panel): Escape inside still closes it, but
+ * Escape from the map doesn't.
+ */
+export declare function useWindowEscape(ref: RefObject<HTMLElement | null>, open: boolean, onClose: () => void, zIndex: number, { topWindow }?: {
+    topWindow?: boolean;
+}): void;

package/dist/hooks/useWindowFocus.d.cts

@@ -0,0 +1,4 @@
+export declare function useWindowFocus(isOpen?: boolean): {
+    zIndex: number;
+    focus: () => void;
+};

package/dist/hooks/useWindowFocus.d.ts

@@ -0,0 +1,4 @@
+export declare function useWindowFocus(isOpen?: boolean): {
+    zIndex: number;
+    focus: () => void;
+};

package/dist/hooks/useWorkerGeometryPreview.d.cts

@@ -0,0 +1,22 @@
+import { Geometry } from '@element-editor/core';
+import { GeometryWorkerRequest } from '@element-editor/core/internal';
+export type PreviewPayload = Extract<GeometryWorkerRequest['payload'], {
+    type: 'buffer' | 'simplify' | 'smooth';
+}>;
+/**
+ * Computes a live geometry preview (buffer / simplify / smooth) in the geometry
+ * worker so slider ticks never block the main thread.
+ *
+ * - At most one request is in flight. Ticks that arrive meanwhile collapse into a
+ *   single queued payload (latest wins), sent when the current one settles.
+ * - Every request gets a sequence number. A finished result is applied only if it
+ *   is the latest request, or a newer one is queued for the SAME source geometry
+ *   (an intermediate frame of the same drag). Results for a replaced source, a
+ *   cleared payload or an unmounted panel are dropped.
+ * - While computing, the previous preview stays on screen (no flash to empty).
+ * - `whenSettled(fn)` runs fn once the preview matches the latest payload, so
+ *   Apply / Enter never commits a stale preview.
+ *
+ * `payload` must be memoised by the caller; `null` means "no preview".
+ */
+export declare function useWorkerGeometryPreview(payload: PreviewPayload | null, setPreview: (geom: Geometry | null) => void): (fn: () => void) => void;

package/dist/hooks/useWorkerGeometryPreview.d.ts

@@ -0,0 +1,22 @@
+import { Geometry } from '@element-editor/core';
+import { GeometryWorkerRequest } from '@element-editor/core/internal';
+export type PreviewPayload = Extract<GeometryWorkerRequest['payload'], {
+    type: 'buffer' | 'simplify' | 'smooth';
+}>;
+/**
+ * Computes a live geometry preview (buffer / simplify / smooth) in the geometry
+ * worker so slider ticks never block the main thread.
+ *
+ * - At most one request is in flight. Ticks that arrive meanwhile collapse into a
+ *   single queued payload (latest wins), sent when the current one settles.
+ * - Every request gets a sequence number. A finished result is applied only if it
+ *   is the latest request, or a newer one is queued for the SAME source geometry
+ *   (an intermediate frame of the same drag). Results for a replaced source, a
+ *   cleared payload or an unmounted panel are dropped.
+ * - While computing, the previous preview stays on screen (no flash to empty).
+ * - `whenSettled(fn)` runs fn once the preview matches the latest payload, so
+ *   Apply / Enter never commits a stale preview.
+ *
+ * `payload` must be memoised by the caller; `null` means "no preview".
+ */
+export declare function useWorkerGeometryPreview(payload: PreviewPayload | null, setPreview: (geom: Geometry | null) => void): (fn: () => void) => void;