feat(layer-control): support collapsed groups and initial selection from layer visibility

.changeset/layer-control-initial-state.md

@@ -0,0 +1,6 @@
+---
+"@xtramaps/layer-control-maplibre": minor
+"@xtramaps/layer-control-maplibre-react": minor
+---
+
+LayerControl: groups and radio-groups accept `opened: false` to start collapsed, and the initial selection now follows the `visibility` layout property of the style's layers instead of activating every layer. Groups start checked if all of their entries are checked, merge-groups as soon as one of their layers is visible, and radio-groups select their first entry that is not hidden in the style.

package.json

@@ -34,13 +34,14 @@
   "devDependencies": {
     "@biomejs/biome": "2.4.6",
     "@changesets/cli": "^2.30.0",
+    "@commitlint/cli": "20.5.0",
+    "@commitlint/config-conventional": "20.5.0",
     "@storybook/addon-vitest": "10.5.7",
     "@storybook/react-vite": "10.5.7",
     "@vitest/browser": "4.1.10",
     "@vitest/browser-playwright": "4.1.10",
     "@vitest/coverage-v8": "4.1.10",
-    "@commitlint/cli": "20.5.0",
-    "@commitlint/config-conventional": "20.5.0",
+    "bootstrap": "5.3.8",
     "lefthook": "2.1.4",
     "npm-check-updates": "19.6.3",
     "playwright": "1.62.1",

packages/core/layer-control-maplibre/README.md

@@ -17,9 +17,13 @@ import { parse, initialCfg } from "@xtramaps/layer-control-maplibre";
 
 const config = await parse(style, entries, /* preferStyle */ true);
 // config.entries -> hydrated tree ready to render
+// config.selectedIds / radioIds -> initial selection, derived from the layers' `visibility`
+// config.openedIds -> initially expanded groups (all except those with `opened: false`)
 // config.deps / depsParent / depsChild -> selection-cascade dependency maps
 ```
 
+Layers with `layout.visibility: "none"` in the style start deselected, groups start selected only if all their entries are selected, merge-groups (shown as a single entry) as soon as one of their layers is visible, and radio-groups start with their first entry that is not hidden. Groups and radio-groups are expanded unless configured with `opened: false`.
+
 ### Exports
 
 - `parse()` - the main entry point: hydrates `entries` against a style's layers and loads sprites

packages/core/layer-control-maplibre/src/config.ts

@@ -57,6 +57,7 @@ export const getRadioGroups = (
 const getRadioGroupLayers = (
   groups: EntryLike[],
   selectedOnly?: boolean,
+  hidden: Set<string> = new Set(),
 ): Record<string, string | string[] | null> => {
   const radioGroups: Record<string, string | string[] | null> = {};
 
@@ -69,8 +70,10 @@ const getRadioGroupLayers = (
       const entries = g.entries as EntryLike[] | undefined;
       const id = g.id as string;
       if (selectedOnly) {
-        radioGroups[id] =
-          entries && entries.length > 0 ? getId(entries[0]) : null;
+        // first entry that is not hidden in the style, falling back to the first entry
+        const selected =
+          entries?.find((e) => !hidden.has(getId(e))) ?? entries?.[0];
+        radioGroups[id] = selected ? getId(selected) : null;
       } else {
         radioGroups[id] = entries ? entries.map((e) => getId(e)) : [];
       }
@@ -183,6 +186,88 @@ export function getChildDeps(
   return tmp ? deps : deps.clean;
 }
 
+/** Ids of all style layers with `layout.visibility: "none"`. */
+const getHiddenLayerIds = (style: StyleWithSpriteLoaded | null): Set<string> =>
+  new Set(
+    (style?.layers ?? [])
+      .filter(
+        (layer) =>
+          (layer as { layout?: { visibility?: string } }).layout?.visibility ===
+          "none",
+      )
+      .map((layer) => layer.id),
+  );
+
+/**
+ * Layers are selected unless hidden in the style. A merge-group is shown as a single entry,
+ * so it is selected as soon as one of its layers is visible; groups (whose entries are
+ * listed individually) are selected only if all of their entries are selected.
+ */
+const getSelectedIds = (
+  entries: EntryLike[],
+  hidden: Set<string>,
+): string[] => {
+  const selected: string[] = [];
+
+  const visit = (entry: EntryLike): boolean => {
+    if (typeof entry === "string") {
+      return true;
+    }
+    const id = entry.id as string;
+    if (entry.type === "layer") {
+      const isSelected = !hidden.has(id);
+      if (isSelected) selected.push(id);
+      return isSelected;
+    }
+    const states = ((entry.entries as EntryLike[] | undefined) ?? []).map(
+      visit,
+    );
+    const isSelected =
+      entry.type === "merge-group" && states.length > 0
+        ? states.some(Boolean)
+        : states.every(Boolean);
+    if (isSelected) selected.push(id);
+    return isSelected;
+  };
+
+  entries.forEach(visit);
+
+  return selected;
+};
+
+/** Ids of all groups and radio-groups, except those configured with `opened: false`. */
+const getOpenedIds = (entries: EntryLike[]): string[] => {
+  const ids: string[] = [];
+
+  entries.forEach((e) => {
+    if (typeof e === "string") {
+      return;
+    }
+    if (
+      (e.type === "group" || e.type === "radio-group") &&
+      e.opened !== false
+    ) {
+      ids.push(e.id as string);
+    }
+    if (e.entries) {
+      ids.push(...getOpenedIds(e.entries as EntryLike[]));
+    }
+  });
+
+  return ids;
+};
+
+const getMergeGroupLayerIds = (entries: EntryLike[]): string[] =>
+  entries.flatMap((e) => {
+    if (typeof e === "string" || !e.entries) {
+      return [];
+    }
+    const children = e.entries as EntryLike[];
+    return e.type === "merge-group"
+      ? children.map(getId)
+      : getMergeGroupLayerIds(children);
+  });
+
 const getLayers = (
   style: StyleWithSpriteLoaded | null,
 ): Record<string, Record<string, unknown>> =>
@@ -319,6 +404,7 @@ export const parse = async (
 
   const { opened, onlyLegend, entries = entriesCfg } = styleMetadataCfg;
   const layers = getLayers(style);
+  const hidden = getHiddenLayerIds(style);
   const hydrated = hydrate(entries as EntryLike[], layers);
 
   const config: LayerControlConfig = {
@@ -328,10 +414,14 @@ export const parse = async (
     allIds: getIds(hydrated as EntryLike[]),
     layerIds: getIds(hydrated as EntryLike[], ["layer"]),
     groupIds: getIds(hydrated as EntryLike[], ["group", "radio-group"]),
-    radioIds: getRadioGroupLayers(hydrated as EntryLike[], true) as Record<
-      string,
-      string | null
-    >,
+    selectedIds: getSelectedIds(hydrated as EntryLike[], hidden),
+    openedIds: getOpenedIds(hydrated as EntryLike[]),
+    mergeGroupLayerIds: getMergeGroupLayerIds(hydrated as EntryLike[]),
+    radioIds: getRadioGroupLayers(
+      hydrated as EntryLike[],
+      true,
+      hidden,
+    ) as Record<string, string | null>,
     radioGroups: getRadioGroupLayers(hydrated as EntryLike[]) as Record<
       string,
       string[]
@@ -355,6 +445,9 @@ export const initialCfg: LayerControlConfig = {
   allIds: [],
   layerIds: [],
   groupIds: [],
+  selectedIds: [],
+  openedIds: [],
+  mergeGroupLayerIds: [],
   radioIds: {},
   radioGroups: {},
   deps: {},

packages/core/layer-control-maplibre/src/types.ts

@@ -14,6 +14,7 @@ export interface RadioGroupEntry {
   id: string;
   label?: string;
   type: "radio-group";
+  opened?: boolean;
   entries?: LayerEntry[];
 }
 
@@ -29,6 +30,7 @@ export interface GroupEntry {
   id: string;
   label?: string;
   type: "group";
+  opened?: boolean;
   onlyLegend?: boolean;
   entries: LayerControlEntry[];
 }
@@ -55,6 +57,7 @@ export interface HydratedRadioGroup {
   id: string;
   label?: string;
   type: "radio-group";
+  opened?: boolean;
   entries: HydratedLayer[];
   onlyLegend?: boolean;
 }
@@ -72,6 +75,7 @@ export interface HydratedGroup {
   id: string;
   label?: string;
   type: "group";
+  opened?: boolean;
   onlyLegend?: boolean;
   entries: HydratedEntry[];
 }
@@ -93,6 +97,12 @@ export interface LayerControlConfig {
   allIds: string[];
   layerIds: string[];
   groupIds: string[];
+  /** Ids initially selected, derived from the `visibility` layout property of the style's layers. */
+  selectedIds: string[];
+  /** Ids of groups and radio-groups that are initially expanded (all except `opened: false`). */
+  openedIds: string[];
+  /** Ids of layers inside merge-groups - not shown as entries of their own. */
+  mergeGroupLayerIds: string[];
   radioIds: Record<string, string | null>;
   radioGroups: Record<string, string[]>;
   deps: Record<string, string[]>;

packages/react/layer-control-maplibre/src/Control.tsx

@@ -61,10 +61,16 @@ function Control({
         }
       });
 
+      // a parent is selected once all of its entries are - layers inside merge-groups are
+      // not entries of their own (a merge-group may be selected with some of them hidden)
       cfg.depsParent[id].forEach((parent) => {
         if (
           !newSelected.includes(parent) &&
-          cfg.depsChild[parent].every((child) => newSelected.includes(child))
+          cfg.depsChild[parent].every(
+            (child) =>
+              cfg.mergeGroupLayerIds.includes(child) ||
+              newSelected.includes(child),
+          )
         ) {
           newSelected.push(parent);
         }
@@ -103,8 +109,8 @@ function Control({
         if (config.opened === true) setIsVisible(true);
         if (config.onlyLegend === true) setIsControlable(false);
         setSelectedRadioGroups(config.radioIds);
-        setSelected(config.allIds);
-        setOpen(config.groupIds);
+        setSelected(config.selectedIds);
+        setOpen(config.openedIds);
       });
     };