layers-select-control 0.3.0 → 0.4.0

package/README.md

@@ -5,11 +5,13 @@ A high-performance React component for selecting layers, inspired by the **Googl
 ## Features
 
 * **Google Maps UI:** Seamlessly transitions between a collapsed thumbnail and an expanded list.
-* **Intelligent Image Loading:** The `ManagedImage` system handles HD transitions and fallbacks without UI flickering.
-* **Interactive Scrolling:** Automatically provides navigation arrows for horizontal scrolling when items exceed `maxVisible`.
-* **Theming & Sizing:** Built-in `dark` and `light` themes with three size presets (`small`, `medium`, `large`).
-* **Adaptive Positioning:** Easily anchor the control to any corner of its parent container.
-* **Mobile Optimized:** Includes touch-start detection and pointer-event handling for mobile maps.
+* **Intelligent Image Loading:** The `ManagedImage` system handles HD transitions and fallbacks (`thumbnailHd` -> `thumbnail` -> `noImageThumb`) without UI flickering.
+* **Ref/Imperative API:** Access internal state and control selection programmatically using `useImperativeHandle`.
+* **Adaptive Positioning:** Anchor the control to any corner using `xRel` and `yRel`.
+* **Dynamic Sizing:** Built-in `small`, `medium`, and `large` presets that scale all dimensions via CSS variables.
+* **Interactive Scrolling:** Automatically detects overflow and provides navigation arrows for horizontal scrolling.
+* **Lifecycle Hooks:** `onExpand` and `onCollapse` callbacks for integration with other UI elements.
+* **Touch Optimized:** Includes pointer-event handling and touch-start detection for mobile map environments.
 
 ## Installation
 
@@ -28,22 +30,25 @@ The component is highly configurable to fit different map layouts and branding r
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `items` | `LayerItem[]` | **Required** | Array of items to display in the panel. |
+| `items` | `LayerItem[]` | **Required** | Array of items to display in the main scrollable area. |
 | `onSelect` | `(item: LayerItem) => void` | **Required** | Callback triggered when a layer is selected. |
 | `onDefault` | `(item?: LayerItem) => void` | **Required** | Callback for the "Default" tile click. |
 | `value` | `string` | - | **Controlled mode**: The ID of the currently selected item. |
 | `defaultValue` | `string` | - | **Uncontrolled mode**: The initial ID to be selected. |
-| `defaultItem` | `LayerItem` | - | Optional item that appears as the "Default" tile. |
-| `size` | `"small" | "medium" | "large"` | `"small"` | Adjusts dimensions of the control and tiles. |
-| `theme` | `"dark" | "light"` | `"dark"` | Built-in color scheme. |
-| `maxVisible` | `number` | `4` | Number of items visible before enabling horizontal scroll. |
+| `defaultItem` | `LayerItem` | - | A special tile that appears fixed at the start of the list. |
+| `moreItem` | `LayerItem` | - | Custom title/description for the "More" tile. |
+| `size` | `"small" | "medium" | "large"` |
+| `theme` | `"dark" | "light"` | `"dark"` |
+| `maxVisible` | `number` | `5` | Number of items visible before enabling horizontal scroll. |
 | `x`, `y` | `number` | `8`, `32` | Numerical offset from the anchor point. |
-| `xRel` | `"left" | "right"` | `"left"` | Horizontal anchor (relative to parent). |
-| `yRel` | `"top" | "bottom"` | `"bottom"` | Vertical anchor (relative to parent). |
+| `xRel` | `"left" | "right"` | `"left"` |
+| `yRel` | `"top" | "bottom"` | `"bottom"` |
 | `onMore` | `() => void` | - | If provided, a "More..." tile is appended to the list. |
-| `hoverCloseDelayMs` | `number` | `160` | Delay before closing the panel on `mouseleave`. |
-| `panelGap` | `number` | `8` | Space between the collapsed thumb and the panel. |
-| `parentGap` | `number` | `8` | Margin maintained between the panel and the parent edge. |
+| `onExpand` | `() => void` | - | Fired when the panel opens. |
+| `onCollapse` | `() => void` | - | Fired when the panel closes. |
+| `defaultThumb` | `string` | - | Override the default "reset" icon URL. |
+| `noImageThumb` | `string` | - | Fallback image for items without thumbnails. |
+| `moreThumb` | `string` | - | Icon for the "More" tile. |
 
 ## Data Interfaces
 
@@ -55,7 +60,19 @@ export interface LayerItem {
     title: string;
     description?: string;
     thumbnail?: string;     // Standard thumbnail
-    thumbnailHd?: string;   // High-quality version loaded when expanded
+    thumbnailHd?: string;   // HD version loaded only when panel expands
+}
+
+```
+
+### Imperative Handle (Ref)
+
+You can control the component externally by passing a `ref`:
+
+```ts
+export interface LayersSelectControlRef {
+    setSelectedItem: (id: string) => void;
+    getSelectedItem: () => LayerItem | undefined;
 }
 
 ```
@@ -63,8 +80,8 @@ export interface LayerItem {
 ## Usage Example
 
 ```tsx
-import React from "react";
-import { LayersSelectControl, LayerItem } from "layers-select-control";
+import React, { useRef } from "react";
+import { LayersSelectControl, LayerItem, LayersSelectControlRef } from "layers-select-control";
 
 const LAYERS: LayerItem[] = [
   { 
@@ -75,17 +92,20 @@ const LAYERS: LayerItem[] = [
     thumbnailHd: "/thumbs/sat-hd.jpg" 
   },
   { id: "terrain", title: "Terrain", description: "Topographic maps", thumbnail: "/thumbs/terrain.jpg" },
-  { id: "streets", title: "Streets", description: "Urban navigation", thumbnail: "/thumbs/streets.jpg" },
 ];
 
 export const App = () => {
+  const controlRef = useRef<LayersSelectControlRef>(null);
+
   return (
-    <div style={{ position: "relative", width: "100%", height: "500px", background: "#eee" }}>
+    <div style={{ position: "relative", width: "100%", height: "600px" }}>
       <LayersSelectControl
+        ref={controlRef}
         items={LAYERS}
         size="medium"
         theme="light"
-        onSelect={(item) => console.log("Selected:", item.title)}
+        defaultItem={{ id: "base", title: "Standard", description: "Default Map" }}
+        onSelect={(item) => console.log("Active Layer:", item.id)}
         onDefault={() => console.log("Reset to default")}
         onMore={() => alert("Open full catalog")}
       />
@@ -97,10 +117,11 @@ export const App = () => {
 
 ## Styling & Theme
 
-The component uses scoped CSS injected via a `<style>` tag, ensuring no styles leak out to the rest of your application. It supports:
+The component uses scoped CSS logic to manage layouts dynamically:
 
-* **Automatic Overflow:** Handles parent container width constraints using `ResizeObserver`.
-* **Responsive Scaling:** Sizes automatically adjust based on the `size` prop.
+* **Responsive Scaling:** Uses internal configurations to calculate exact pixel dimensions for thumbnails and tiles.
+* **Auto-Width:** Utilizes `ResizeObserver` on the parent container to ensure the expanded panel never overflows the screen boundaries.
+* **Pointer Awareness:** Automatically switches between `hover` and `touch` events depending on the user's device.
 
 ## License
 

package/dist/LayersSelectControl.d.ts

@@ -7,9 +7,11 @@ export interface LayerItem {
     thumbnailHd?: string;
 }
 interface Props {
+    title?: string;
     value?: string;
     defaultValue?: string;
     defaultItem?: LayerItem;
+    externalItem?: LayerItem;
     moreItem?: LayerItem;
     items: LayerItem[];
     x?: number;
@@ -31,6 +33,10 @@ interface Props {
     onExpand?: () => void;
     onCollapse?: () => void;
 }
-export declare const LayersSelectControl: React.FC<Props>;
+export interface LayersSelectControlRef {
+    setSelectedItem: (id: string) => void;
+    getSelectedItem: () => LayerItem | undefined;
+}
+export declare const LayersSelectControl: React.ForwardRefExoticComponent<Props & React.RefAttributes<LayersSelectControlRef>>;
 export {};
 //# sourceMappingURL=LayersSelectControl.d.ts.map

package/dist/LayersSelectControl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LayersSelectControl.d.ts","sourceRoot":"","sources":["../src/LayersSelectControl.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAEjF,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,KAAK;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IAEnB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAExB,SAAS,EAAE,CAAC,IAAI,CAAC,EAAE,SAAS,KAAK,IAAI,CAAC;IACtC,QAAQ,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAkED,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,EAAE,CAAC,KAAK,CA0Q/C,CAAC"}
+{"version":3,"file":"LayersSelectControl.d.ts","sourceRoot":"","sources":["../src/LayersSelectControl.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAEjF,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,KAAK;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;IAEnB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAExB,SAAS,EAAE,CAAC,IAAI,CAAC,EAAE,SAAS,KAAK,IAAI,CAAC;IACtC,QAAQ,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AA+DD,MAAM,WAAW,sBAAsB;IACnC,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,eAAe,EAAE,MAAM,SAAS,GAAG,SAAS,CAAC;CAChD;AAKD,eAAO,MAAM,mBAAmB,sFAoR9B,CAAC"}

package/dist/LayersSelectControl.js

@@ -1,8 +1,41 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LayersSelectControl = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
-const react_1 = require("react");
+const react_1 = __importStar(require("react"));
 const DEFAULT_RESET_IMAGE_URL = "./firstplace.svg";
 const DEFAULT_NO_IMAGE_URL = "./noimage.png";
 const DEFAULT_IMAGE_MORE = "./more-images.png";
@@ -47,7 +80,7 @@ function ManagedImage({ candidates, initial, alt, className, expanded, noImageTh
 // ------------------------------------------------------
 // COMPONENT (LOGIC PRESERVED)
 // ------------------------------------------------------
-const LayersSelectControl = ({ items, value, defaultValue, x = 8, y = 32, xRel = "left", yRel = "bottom", defaultItem, moreItem, onSelect, onMore, onDefault, maxVisible = DEFAULT_MAX_VISIBLE, hoverCloseDelayMs = 160, theme = "dark", defaultThumb = DEFAULT_RESET_IMAGE_URL, noImageThumb = DEFAULT_NO_IMAGE_URL, moreThumb = DEFAULT_IMAGE_MORE, size = "small", panelGap = 8, parentGap = 8, onCollapse, onExpand }) => {
+exports.LayersSelectControl = react_1.default.forwardRef(({ title, items, value, defaultValue, x = 8, y = 32, xRel = "left", yRel = "bottom", defaultItem, externalItem, moreItem, onSelect, onMore, onDefault, maxVisible = DEFAULT_MAX_VISIBLE, hoverCloseDelayMs = 160, theme = "dark", defaultThumb = DEFAULT_RESET_IMAGE_URL, noImageThumb = DEFAULT_NO_IMAGE_URL, moreThumb = DEFAULT_IMAGE_MORE, size = "small", panelGap = 8, parentGap = 8, onCollapse, onExpand }, ref) => {
     const isControlled = value !== undefined;
     const [internalValue, setInternalValue] = (0, react_1.useState)(defaultValue);
     const selectedId = isControlled ? value : internalValue;
@@ -108,6 +141,8 @@ const LayersSelectControl = ({ items, value, defaultValue, x = 8, y = 32, xRel =
     const selectedItem = (0, react_1.useMemo)(() => {
         if (defaultItem && selectedId === defaultItem.id)
             return defaultItem;
+        if (externalItem && selectedId === externalItem.id)
+            return externalItem;
         return items.find((x) => x.id === selectedId);
     }, [items, selectedId, defaultItem]);
     const collapsedCandidates = (0, react_1.useMemo)(() => [collapsedThumb(selectedItem)], [collapsedThumb, selectedItem]);
@@ -147,7 +182,12 @@ const LayersSelectControl = ({ items, value, defaultValue, x = 8, y = 32, xRel =
     const toggleExpanded = () => {
         setExpanded((s) => (s ? false : hasContent()));
     };
-    return ((0, jsx_runtime_1.jsxs)("div", { ref: rootRef, className: `lsc-root ${theme === "light" ? "lsc-light" : ""}`, style: {
+    // ----- Expose methods to parent -----
+    react_1.default.useImperativeHandle(ref, () => ({
+        setSelectedItem: (id) => setSelectedId(id),
+        getSelectedItem: () => selectedItem,
+    }), [selectedItem, setSelectedId]);
+    return ((0, jsx_runtime_1.jsxs)("div", { title: title, ref: rootRef, className: `lsc-root ${theme === "light" ? "lsc-light" : ""}`, style: {
             [xRel]: `${x}px`,
             [yRel]: `${y}px`,
             "--lsc-collapsed": `${cfg.collapsed}px`,
@@ -186,5 +226,4 @@ const LayersSelectControl = ({ items, value, defaultValue, x = 8, y = 32, xRel =
                                 onMore === null || onMore === void 0 ? void 0 : onMore();
                                 setExpanded(false);
                             }, children: [(0, jsx_runtime_1.jsx)(ManagedImage, { candidates: [moreThumb], initial: moreThumb, expanded: expanded, className: "lsc-t-thumb", noImageThumb: noImageThumb }), (0, jsx_runtime_1.jsx)("div", { className: "lsc-title", children: (moreItem === null || moreItem === void 0 ? void 0 : moreItem.title) ? moreItem === null || moreItem === void 0 ? void 0 : moreItem.title : "More…" }), (0, jsx_runtime_1.jsx)("div", { className: "lsc-desc", children: (moreItem === null || moreItem === void 0 ? void 0 : moreItem.description) ? moreItem === null || moreItem === void 0 ? void 0 : moreItem.description : "Show all" })] }))] }) })] }));
-};
-exports.LayersSelectControl = LayersSelectControl;
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "layers-select-control",
   "description": "Mimics Google layer select layers.",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {