@geoit/ui 0.0.5 → 0.0.7

package/ai/catalog.json

@@ -1,8 +1,8 @@
 {
   "package": "@geoit/ui",
   "import": "@geoit/ui",
-  "version": "0.0.5",
-  "generatedAt": "2026-08-24T03:07:52.099Z",
+  "version": "0.0.7",
+  "generatedAt": "2026-09-04T07:20:22.166Z",
   "styles": [
     "@geoit/ui/src/lib/styles/design-tokens.scss",
     "@geoit/ui/src/lib/styles/theme.scss"
@@ -339,12 +339,15 @@
     {
       "name": "GeoChartComponent",
       "selector": "geo-chart",
-      "category": "other",
-      "summary": "GeoChartComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
-      "howTo": "",
-      "tips": [],
+      "category": "data",
+      "summary": "Bar / donut chart for dashboard statistics (ApexCharts).",
+      "whenToUse": "KPI breakdowns on dashboard pages.",
+      "doNotUseWhen": "Maps / spatial — use geo-map; single KPI — use geo-stat-card.",
+      "howTo": "Biểu đồ bar/donut cho dashboard. [data] = { label, value, color? }[]; (segmentClick) khi click lát.",
+      "tips": [
+        "Màu ưu tiên CSS var(--geo-color-*).",
+        "KPI đơn → geo-stat-card; ghép sẵn → geo-dashboard."
+      ],
       "binding": "none",
       "cva": false,
       "path": "projects/geo-ui/src/lib/figma/geo-chart/geo-chart.component.ts",
@@ -419,12 +422,17 @@
       ],
       "examples": [
         {
-          "title": "Example",
-          "lang": "html"
+          "title": "Bar",
+          "lang": "html",
+          "code": "<geo-chart type=\"bar\" title=\"Theo xã\" [data]=\"wardData\" [height]=\"280\"></geo-chart>"
         }
       ],
-      "example": "<geo-chart></geo-chart>",
-      "related": []
+      "example": "<geo-chart type=\"bar\" title=\"Theo xã\" [data]=\"wardData\" [height]=\"280\"></geo-chart>",
+      "related": [
+        "geo-stat-card",
+        "geo-dashboard",
+        "geo-empty-state"
+      ]
     },
     {
       "name": "GeoCheckboxComponent",
@@ -675,12 +683,14 @@
     {
       "name": "GeoDashboardComponent",
       "selector": "geo-dashboard",
-      "category": "other",
-      "summary": "GeoDashboardComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
-      "howTo": "",
-      "tips": [],
+      "category": "layout",
+      "summary": "Composed dashboard: period, KPI cards, ward/mismatch charts.",
+      "whenToUse": "TCQH overview pages (thống kê nhanh).",
+      "doNotUseWhen": "Custom layouts — compose geo-stat-card + geo-chart yourself.",
+      "howTo": "Dashboard ghép sẵn: stats + biểu đồ xã + lệch kỳ. [(period)] điều khiển kỳ thống kê.",
+      "tips": [
+        "Tự layout → geo-stat-card + geo-chart."
+      ],
       "binding": "none",
       "cva": false,
       "path": "projects/geo-ui/src/lib/figma/geo-dashboard/geo-dashboard.component.ts",
@@ -760,12 +770,17 @@
       ],
       "examples": [
         {
-          "title": "Example",
-          "lang": "html"
+          "title": "Basic",
+          "lang": "html",
+          "code": "<geo-dashboard [stats]=\"stats\" [wardData]=\"wards\" [mismatchData]=\"mismatch\" [(period)]=\"period\"></geo-dashboard>"
         }
       ],
-      "example": "<geo-dashboard></geo-dashboard>",
-      "related": []
+      "example": "<geo-dashboard [stats]=\"stats\" [wardData]=\"wards\" [mismatchData]=\"mismatch\" [(period)]=\"period\"></geo-dashboard>",
+      "related": [
+        "geo-stat-card",
+        "geo-chart",
+        "geo-page-header"
+      ]
     },
     {
       "name": "GeoDatePickerComponent",
@@ -1033,10 +1048,10 @@
     {
       "name": "GeoEmptyStateComponent",
       "selector": "geo-empty-state",
-      "category": "other",
-      "summary": "GeoEmptyStateComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "feedback",
+      "summary": "Empty region placeholder (icon + title + optional action).",
+      "whenToUse": "No data / no results areas inside pages or cards.",
+      "doNotUseWhen": "Inline form validation — use field errorMessage / geo-alert.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -1079,19 +1094,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-empty-state title=\"Chưa có dữ liệu\" description=\"Thử đổi bộ lọc.\"></geo-empty-state>"
         }
       ],
-      "example": "<geo-empty-state></geo-empty-state>",
+      "example": "<geo-empty-state title=\"Chưa có dữ liệu\" description=\"Thử đổi bộ lọc.\"></geo-empty-state>",
       "related": []
     },
     {
       "name": "GeoFeedbackFormComponent",
       "selector": "geo-feedback-form",
-      "category": "other",
-      "summary": "GeoFeedbackFormComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "forms",
+      "summary": "Citizen feedback / phản ánh form with validation.",
+      "whenToUse": "Public feedback submission pages.",
+      "doNotUseWhen": "Admin feedback inbox — use geo-list-page + geo-table.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -1175,10 +1191,11 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-feedback-form (submittedFeedback)=\"send($event)\"></geo-feedback-form>"
         }
       ],
-      "example": "<geo-feedback-form></geo-feedback-form>",
+      "example": "<geo-feedback-form (submittedFeedback)=\"send($event)\"></geo-feedback-form>",
       "related": []
     },
     {
@@ -1301,10 +1318,10 @@
     {
       "name": "GeoForgotPasswordComponent",
       "selector": "geo-forgot-password",
-      "category": "other",
-      "summary": "GeoForgotPasswordComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "forms",
+      "summary": "Forgot-password form (email + submit / back to login).",
+      "whenToUse": "Password reset entry page.",
+      "doNotUseWhen": "Inside login card — navigate to a dedicated route.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -1364,10 +1381,11 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-forgot-password\n  (submitEmail)=\"reset($event)\"\n  (backToLogin)=\"goLogin()\"\n></geo-forgot-password>"
         }
       ],
-      "example": "<geo-forgot-password></geo-forgot-password>",
+      "example": "<geo-forgot-password\n  (submitEmail)=\"reset($event)\"\n  (backToLogin)=\"goLogin()\"\n></geo-forgot-password>",
       "related": []
     },
     {
@@ -2282,10 +2300,10 @@
     {
       "name": "GeoListPageComponent",
       "selector": "geo-list-page",
-      "category": "other",
-      "summary": "GeoListPageComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "layout",
+      "summary": "List page chrome: title + breadcrumb shell for admin CRUD screens.",
+      "whenToUse": "Wrap table toolbars on admin list pages.",
+      "doNotUseWhen": "Map portals — use geo-map-shell; dashboards — use geo-dashboard.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -2316,21 +2334,25 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-list-page title=\"Quản lý người dùng\" [breadcrumb]=\"crumbs\">\n  <geo-table-toolbar ...></geo-table-toolbar>\n  <geo-table ...></geo-table>\n</geo-list-page>"
         }
       ],
-      "example": "<geo-list-page></geo-list-page>",
+      "example": "<geo-list-page title=\"Quản lý người dùng\" [breadcrumb]=\"crumbs\">\n  <geo-table-toolbar ...></geo-table-toolbar>\n  <geo-table ...></geo-table>\n</geo-list-page>",
       "related": []
     },
     {
       "name": "GeoLoginComponent",
       "selector": "geo-login",
-      "category": "other",
-      "summary": "GeoLoginComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
-      "howTo": "",
-      "tips": [],
+      "category": "forms",
+      "summary": "Login form (username, password, captcha, remember).",
+      "whenToUse": "Specialist / admin login page.",
+      "doNotUseWhen": "SSO-only flows without local credentials.",
+      "howTo": "Form đăng nhập: username/password/captcha/remember. (submitLogin) payload; (forgotPassword) điều hướng quên mật khẩu.",
+      "tips": [
+        "Cần FormsModule + styles tokens.",
+        "Ghép geo-forgot-password trên route riêng."
+      ],
       "binding": "none",
       "cva": false,
       "path": "projects/geo-ui/src/lib/figma/geo-login/geo-login.component.ts",
@@ -2411,12 +2433,17 @@
       ],
       "examples": [
         {
-          "title": "Example",
-          "lang": "html"
+          "title": "Basic",
+          "lang": "html",
+          "code": "<geo-login (submitLogin)=\"login($event)\" (forgotPassword)=\"goForgot()\"></geo-login>"
         }
       ],
-      "example": "<geo-login></geo-login>",
-      "related": []
+      "example": "<geo-login (submitLogin)=\"login($event)\" (forgotPassword)=\"goForgot()\"></geo-login>",
+      "related": [
+        "geo-forgot-password",
+        "geo-input",
+        "geo-button"
+      ]
     },
     {
       "name": "GeoMapComponent",
@@ -2424,9 +2451,13 @@
       "category": "map",
       "summary": "OpenLayers map host with basemap, typed layers, and GeoMapController.",
       "whenToUse": "Any map viewport (portal quy hoạch, tra cứu thửa). Peers: ol, proj4.",
-      "doNotUseWhen": "Non-map charting — use dashboard libs.",
-      "howTo": "",
-      "tips": [],
+      "doNotUseWhen": "Full portal chrome — prefer geo-map-shell; non-map charts — use geo-chart.",
+      "howTo": "Host OpenLayers thuần. (mapReady) nhận GeoMapController để zoom/fit/addLayer. Layers typed (osm/xyz/wms/wmts/geojson). Projections tùy chỉnh qua [projections] — không invent VN-2000.",
+      "tips": [
+        "Portal đầy đủ → geo-map-shell.",
+        "showZoomControl=false khi dùng geo-map-zoom riêng.",
+        "Peers: ol, proj4."
+      ],
       "binding": "none",
       "cva": false,
       "path": "projects/geo-ui/src/lib/figma/geo-map/geo-map.component.ts",
@@ -2535,21 +2566,25 @@
       ],
       "examples": [
         {
-          "title": "Example",
+          "title": "Basic",
           "lang": "html",
-          "code": "<geo-map\n  [center]=\"center\"\n  [zoom]=\"12\"\n  [layers]=\"layers\"\n  height=\"480px\"\n  (mapReady)=\"ctrl = $event\"\n></geo-map>"
+          "code": "<geo-map height=\"480px\" basemap=\"osm\" [center]=\"[108.45, 11.94]\" [zoom]=\"12\" (mapReady)=\"ctrl = $event\"></geo-map>"
         }
       ],
-      "example": "<geo-map\n  [center]=\"center\"\n  [zoom]=\"12\"\n  [layers]=\"layers\"\n  height=\"480px\"\n  (mapReady)=\"ctrl = $event\"\n></geo-map>",
-      "related": []
+      "example": "<geo-map height=\"480px\" basemap=\"osm\" [center]=\"[108.45, 11.94]\" [zoom]=\"12\" (mapReady)=\"ctrl = $event\"></geo-map>",
+      "related": [
+        "geo-map-shell",
+        "geo-map-zoom",
+        "geo-map-toolbar"
+      ]
     },
     {
       "name": "GeoMapAdminFilterComponent",
       "selector": "geo-map-admin-filter",
-      "category": "other",
-      "summary": "GeoMapAdminFilterComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Administrative unit tree filter (ĐVHC) for map extent.",
+      "whenToUse": "Filter map by tỉnh/huyện/xã; included in geo-map-shell.",
+      "doNotUseWhen": "Generic trees outside map — use geo-tree.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -2575,6 +2610,12 @@
           "default": "[]",
           "note": ""
         },
+        {
+          "name": "selectionMode",
+          "type": "'single' | 'multi'",
+          "default": "'multi'",
+          "note": "`single` — chọn đúng 1 xã/phường (BR-06-03); `multi` — checkbox nhiều cấp (mặc định)."
+        },
         {
           "name": "checkedKeys",
           "type": "Array<string | number>",
@@ -2618,19 +2659,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-admin-filter\n  [(open)]=\"adminOpen\"\n  [nodes]=\"adminNodes\"\n  [(checkedKeys)]=\"checked\"\n  (apply)=\"applyAdmin($event)\"\n></geo-map-admin-filter>"
         }
       ],
-      "example": "<geo-map-admin-filter></geo-map-admin-filter>",
+      "example": "<geo-map-admin-filter\n  [(open)]=\"adminOpen\"\n  [nodes]=\"adminNodes\"\n  [(checkedKeys)]=\"checked\"\n  (apply)=\"applyAdmin($event)\"\n></geo-map-admin-filter>",
       "related": []
     },
     {
       "name": "GeoMapBasemapSwitcherComponent",
       "selector": "geo-map-basemap-switcher",
-      "category": "other",
-      "summary": "GeoMapBasemapSwitcherComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Basemap preview chip (e.g. street ↔ satellite).",
+      "whenToUse": "Bottom-right basemap toggle; included in geo-map-shell.",
+      "doNotUseWhen": "Programmatic basemap only — set geo-map [basemap] / shell basemapId.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -2673,19 +2715,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-basemap-switcher\n  [options]=\"basemapOptions\"\n  [(selectedId)]=\"basemapId\"\n  (basemapChange)=\"onBasemap($event)\"\n></geo-map-basemap-switcher>"
         }
       ],
-      "example": "<geo-map-basemap-switcher></geo-map-basemap-switcher>",
+      "example": "<geo-map-basemap-switcher\n  [options]=\"basemapOptions\"\n  [(selectedId)]=\"basemapId\"\n  (basemapChange)=\"onBasemap($event)\"\n></geo-map-basemap-switcher>",
       "related": []
     },
     {
       "name": "GeoMapHelpComponent",
       "selector": "geo-map-help",
-      "category": "other",
-      "summary": "GeoMapHelpComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Map help / hướng dẫn popover with sections.",
+      "whenToUse": "Help affordance on map chrome.",
+      "doNotUseWhen": "App-wide help pages — use normal content pages.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -2716,19 +2759,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-help [(open)]=\"helpOpen\" [sections]=\"helpSections\"></geo-map-help>"
         }
       ],
-      "example": "<geo-map-help></geo-map-help>",
+      "example": "<geo-map-help [(open)]=\"helpOpen\" [sections]=\"helpSections\"></geo-map-help>",
       "related": []
     },
     {
       "name": "GeoMapLayerCardComponent",
       "selector": "geo-map-layer-card",
-      "category": "other",
-      "summary": "GeoMapLayerCardComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Basemap / layer preview card (thumbnail + title).",
+      "whenToUse": "Layer pickers and basemap grids.",
+      "doNotUseWhen": "Full layer management — use geo-map-layer-panel.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -2759,19 +2803,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-layer-card title=\"Đường phố\" [previewUrl]=\"url\" (clicked)=\"select()\"></geo-map-layer-card>"
         }
       ],
-      "example": "<geo-map-layer-card></geo-map-layer-card>",
+      "example": "<geo-map-layer-card title=\"Đường phố\" [previewUrl]=\"url\" (clicked)=\"select()\"></geo-map-layer-card>",
       "related": []
     },
     {
       "name": "GeoMapLayerPanelComponent",
       "selector": "geo-map-layer-panel",
-      "category": "other",
-      "summary": "GeoMapLayerPanelComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Layer list with visibility / opacity / group selection.",
+      "whenToUse": "Standalone layer manager or inside geo-map-layers-drawer.",
+      "doNotUseWhen": "Single opacity control — use geo-map-opacity.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -2814,19 +2859,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-layer-panel [layers]=\"layers\" [controller]=\"ctrl\" [embedded]=\"true\"></geo-map-layer-panel>"
         }
       ],
-      "example": "<geo-map-layer-panel></geo-map-layer-panel>",
+      "example": "<geo-map-layer-panel [layers]=\"layers\" [controller]=\"ctrl\" [embedded]=\"true\"></geo-map-layer-panel>",
       "related": []
     },
     {
       "name": "GeoMapLayersDrawerComponent",
       "selector": "geo-map-layers-drawer",
-      "category": "other",
-      "summary": "GeoMapLayersDrawerComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Popover/drawer hosting the layer panel (“Lớp bản đồ”).",
+      "whenToUse": "Portal layer UI; included in geo-map-shell.",
+      "doNotUseWhen": "Always-visible side panel — embed geo-map-layer-panel directly.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -2887,19 +2933,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-layers-drawer [(open)]=\"layersOpen\" [layers]=\"layers\" [controller]=\"ctrl\"></geo-map-layers-drawer>"
         }
       ],
-      "example": "<geo-map-layers-drawer></geo-map-layers-drawer>",
+      "example": "<geo-map-layers-drawer [(open)]=\"layersOpen\" [layers]=\"layers\" [controller]=\"ctrl\"></geo-map-layers-drawer>",
       "related": []
     },
     {
       "name": "GeoMapLegendComponent",
       "selector": "geo-map-legend",
-      "category": "other",
-      "summary": "GeoMapLegendComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Map legend popover / panel with color swatches.",
+      "whenToUse": "Show thematic legend; geo-map-shell includes this.",
+      "doNotUseWhen": "Non-map legends in dashboards — use static markup / geo-status-tag.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -2919,6 +2966,12 @@
           "default": "[]",
           "note": ""
         },
+        {
+          "name": "catalogMissing",
+          "type": "boolean",
+          "default": "false",
+          "note": "True khi danh mục chú giải không tải được (`ERR_MAP_LEGEND_CATALOG_MISSING`)."
+        },
         {
           "name": "open",
           "type": "boolean",
@@ -2936,19 +2989,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-legend [(open)]=\"legendOpen\" [items]=\"legendItems\"></geo-map-legend>"
         }
       ],
-      "example": "<geo-map-legend></geo-map-legend>",
+      "example": "<geo-map-legend [(open)]=\"legendOpen\" [items]=\"legendItems\"></geo-map-legend>",
       "related": []
     },
     {
       "name": "GeoMapLocateComponent",
       "selector": "geo-map-locate",
-      "category": "other",
-      "summary": "GeoMapLocateComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Geolocation button (browser GPS) for the map view.",
+      "whenToUse": "Locate-me control on custom map chrome.",
+      "doNotUseWhen": "Inside geo-map-shell (already wired) unless building a custom shell.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -2989,19 +3043,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-locate [controller]=\"ctrl\" (denied)=\"onDenied()\"></geo-map-locate>"
         }
       ],
-      "example": "<geo-map-locate></geo-map-locate>",
+      "example": "<geo-map-locate [controller]=\"ctrl\" (denied)=\"onDenied()\"></geo-map-locate>",
       "related": []
     },
     {
       "name": "GeoMapLocationChipComponent",
       "selector": "geo-map-location-chip",
-      "category": "other",
-      "summary": "GeoMapLocationChipComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Location breadcrumb chip shown on the map (ward / province).",
+      "whenToUse": "Show current admin context on map chrome.",
+      "doNotUseWhen": "Page breadcrumb — use geo-breadcrumb.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -3026,19 +3081,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-location-chip label=\"Phường 1 — TP Đà Lạt, Lâm Đồng\"></geo-map-location-chip>"
         }
       ],
-      "example": "<geo-map-location-chip></geo-map-location-chip>",
+      "example": "<geo-map-location-chip label=\"Phường 1 — TP Đà Lạt, Lâm Đồng\"></geo-map-location-chip>",
       "related": []
     },
     {
       "name": "GeoMapMeasureComponent",
       "selector": "geo-map-measure",
-      "category": "other",
-      "summary": "GeoMapMeasureComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Distance / area measure interaction on the map.",
+      "whenToUse": "Measure tool mode; usually driven by toolbar via geo-map-shell.",
+      "doNotUseWhen": "Static length labels without interaction.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -3075,19 +3131,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-measure [controller]=\"ctrl\" [(mode)]=\"measureMode\"></geo-map-measure>"
         }
       ],
-      "example": "<geo-map-measure></geo-map-measure>",
+      "example": "<geo-map-measure [controller]=\"ctrl\" [(mode)]=\"measureMode\"></geo-map-measure>",
       "related": []
     },
     {
       "name": "GeoMapOpacityComponent",
       "selector": "geo-map-opacity",
-      "category": "other",
-      "summary": "GeoMapOpacityComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Layer opacity slider bound to a map layer id.",
+      "whenToUse": "Adjust overlay transparency in custom layer UI.",
+      "doNotUseWhen": "Full layer list — use geo-map-layer-panel / layers drawer.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -3136,19 +3193,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-opacity [controller]=\"ctrl\" layerId=\"demo-qhsdd-2020\" [(opacity)]=\"opacity\"></geo-map-opacity>"
         }
       ],
-      "example": "<geo-map-opacity></geo-map-opacity>",
+      "example": "<geo-map-opacity [controller]=\"ctrl\" layerId=\"demo-qhsdd-2020\" [(opacity)]=\"opacity\"></geo-map-opacity>",
       "related": []
     },
     {
       "name": "GeoMapParcelPopupComponent",
       "selector": "geo-map-parcel-popup",
-      "category": "other",
-      "summary": "GeoMapParcelPopupComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Parcel detail popup (citizen / specialist audience).",
+      "whenToUse": "Show thửa detail after search or map click.",
+      "doNotUseWhen": "Full detail page — navigate to a route instead.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -3212,19 +3270,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-parcel-popup\n  [(open)]=\"parcelOpen\"\n  [parcel]=\"selected\"\n  audience=\"citizen\"\n  (exportClick)=\"exportPdf($event)\"\n></geo-map-parcel-popup>"
         }
       ],
-      "example": "<geo-map-parcel-popup></geo-map-parcel-popup>",
+      "example": "<geo-map-parcel-popup\n  [(open)]=\"parcelOpen\"\n  [parcel]=\"selected\"\n  audience=\"citizen\"\n  (exportClick)=\"exportPdf($event)\"\n></geo-map-parcel-popup>",
       "related": []
     },
     {
       "name": "GeoMapSearchComponent",
       "selector": "geo-map-search",
-      "category": "other",
-      "summary": "GeoMapSearchComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Map search panel (owner / certificate / parcel / address / coordinates).",
+      "whenToUse": "Tra cứu thửa on portal; prefer via geo-map-shell.",
+      "doNotUseWhen": "Global app search unrelated to map.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -3312,21 +3371,28 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-search\n  [(open)]=\"searchOpen\"\n  mode=\"parcel\"\n  [results]=\"results\"\n  (search)=\"runSearch($event)\"\n  (resultSelect)=\"onSelect($event)\"\n></geo-map-search>"
         }
       ],
-      "example": "<geo-map-search></geo-map-search>",
+      "example": "<geo-map-search\n  [(open)]=\"searchOpen\"\n  mode=\"parcel\"\n  [results]=\"results\"\n  (search)=\"runSearch($event)\"\n  (resultSelect)=\"onSelect($event)\"\n></geo-map-search>",
       "related": []
     },
     {
       "name": "GeoMapShellComponent",
       "selector": "geo-map-shell",
-      "category": "other",
-      "summary": "GeoMapShellComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
-      "howTo": "",
-      "tips": [],
+      "category": "map",
+      "summary": "Full map portal chrome: search, ĐVHC, layers, legend, measure, basemap, parcel popup.",
+      "whenToUse": "Public / specialist map portal pages (tra cứu quy hoạch). Prefer this over composing chrome by hand.",
+      "doNotUseWhen": "Bare map embed without UI chrome — use geo-map only.",
+      "howTo": "Shell portal tra cứu: gắn height + layers API; tắt demoSearch trên production. Lắng nghe (search)/(resultSelect)/(parcelExport). Models [(searchOpen)], [(layersOpen)], … để điều khiển panel từ ngoài.",
+      "tips": [
+        "Ưu tiên geo-map-shell thay vì tự ghép chrome.",
+        "Peers bắt buộc: ol, proj4.",
+        "demoSearch=true chỉ cho Storybook/demo — production phải false + API thật.",
+        "parcelAudience: citizen | specialist.",
+        "Đọc geo-map.md cho layer types / projections."
+      ],
       "binding": "none",
       "cva": false,
       "path": "projects/geo-ui/src/lib/figma/geo-map/chrome/geo-map-shell/geo-map-shell.component.ts",
@@ -3398,12 +3464,30 @@
           "default": "GEO_MAP_DEMO_ADMIN_NODES",
           "note": ""
         },
+        {
+          "name": "adminSelectionMode",
+          "type": "'single' | 'multi'",
+          "default": "'multi'",
+          "note": "`single` — chọn đúng 1 xã/phường (BR-06-03); `multi` — checkbox nhiều cấp (mặc định)."
+        },
         {
           "name": "locationLabel",
           "type": "string",
           "default": "'Phường 1 — TP Đà Lạt, Lâm Đồng'",
           "note": ""
         },
+        {
+          "name": "measureDisclaimer",
+          "type": "string | null",
+          "default": "'Giá trị tham khảo trên bản đồ, không có giá trị pháp lý. Diện tích pháp lý của thửa đất lấy theo hồ sơ địa chính.'",
+          "note": "Ghi chú pháp lý hiển thị khi đang đo (BR-10-03). `null` ẩn ghi chú — mặc định giữ nguyên câu chữ đã dùng ở `qh-map-shell`."
+        },
+        {
+          "name": "legendCatalogMissing",
+          "type": "boolean",
+          "default": "false",
+          "note": "True khi danh mục chú giải không tải được (`ERR_MAP_LEGEND_CATALOG_MISSING`)."
+        },
         {
           "name": "parcelAudience",
           "type": "GeoMapParcelAudience",
@@ -3530,11 +3614,21 @@
           "type": "OutputEmitterRef<GeoMapClickEvent>",
           "note": ""
         },
+        {
+          "name": "located",
+          "type": "OutputEmitterRef<[number, number]>",
+          "note": ""
+        },
         {
           "name": "locateDenied",
           "type": "OutputEmitterRef<void>",
           "note": ""
         },
+        {
+          "name": "locateError",
+          "type": "OutputEmitterRef<{ reason: GeoMapLocateErrorReason; message?: string }>",
+          "note": ""
+        },
         {
           "name": "actionClick",
           "type": "OutputEmitterRef<GeoMapToolbarAction>",
@@ -3564,24 +3658,45 @@
           "name": "adminApply",
           "type": "OutputEmitterRef<Array<string | number>>",
           "note": ""
+        },
+        {
+          "name": "snapshotCaptured",
+          "type": "OutputEmitterRef<void>",
+          "note": ""
+        },
+        {
+          "name": "snapshotError",
+          "type": "OutputEmitterRef<unknown>",
+          "note": ""
         }
       ],
       "examples": [
         {
-          "title": "Example",
-          "lang": "html"
+          "title": "Basic portal",
+          "lang": "html",
+          "code": "<geo-map-shell\n  height=\"640px\"\n  [demoSearch]=\"false\"\n  parcelAudience=\"citizen\"\n  [layers]=\"layers\"\n  (mapReady)=\"ctrl = $event\"\n  (search)=\"onSearch($event)\"\n></geo-map-shell>"
+        },
+        {
+          "title": "Open search panel",
+          "lang": "html",
+          "code": "<geo-map-shell\n  height=\"640px\"\n  [demoSearch]=\"false\"\n  [(searchOpen)]=\"searchOpen\"\n  [(searchResults)]=\"results\"\n  (search)=\"runQuery($event)\"\n  (resultSelect)=\"onResult($event)\"\n></geo-map-shell>"
         }
       ],
-      "example": "<geo-map-shell></geo-map-shell>",
-      "related": []
+      "example": "<geo-map-shell\n  height=\"640px\"\n  [demoSearch]=\"false\"\n  parcelAudience=\"citizen\"\n  [layers]=\"layers\"\n  (mapReady)=\"ctrl = $event\"\n  (search)=\"onSearch($event)\"\n></geo-map-shell>",
+      "related": [
+        "geo-map",
+        "geo-map-search",
+        "geo-map-toolbar",
+        "geo-map-layers-drawer"
+      ]
     },
     {
       "name": "GeoMapSnapshotComponent",
       "selector": "geo-map-snapshot",
-      "category": "other",
-      "summary": "GeoMapSnapshotComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Capture current map canvas to image / download.",
+      "whenToUse": "Export screenshot control on map chrome.",
+      "doNotUseWhen": "Server-side tile export pipelines.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -3623,19 +3738,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-snapshot [controller]=\"ctrl\" (captured)=\"onShot($event)\"></geo-map-snapshot>"
         }
       ],
-      "example": "<geo-map-snapshot></geo-map-snapshot>",
+      "example": "<geo-map-snapshot [controller]=\"ctrl\" (captured)=\"onShot($event)\"></geo-map-snapshot>",
       "related": []
     },
     {
       "name": "GeoMapSwipeComponent",
       "selector": "geo-map-swipe",
-      "category": "other",
-      "summary": "GeoMapSwipeComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Swipe compare control between two map layers.",
+      "whenToUse": "Before/after planning vs current-use comparison.",
+      "doNotUseWhen": "Simple opacity blend — use geo-map-opacity.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -3672,19 +3788,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-swipe [controller]=\"ctrl\" [(active)]=\"swipeOn\" layerId=\"demo-qhsdd-2020\"></geo-map-swipe>"
         }
       ],
-      "example": "<geo-map-swipe></geo-map-swipe>",
+      "example": "<geo-map-swipe [controller]=\"ctrl\" [(active)]=\"swipeOn\" layerId=\"demo-qhsdd-2020\"></geo-map-swipe>",
       "related": []
     },
     {
       "name": "GeoMapToolbarComponent",
       "selector": "geo-map-toolbar",
-      "category": "other",
-      "summary": "GeoMapToolbarComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Vertical map tool strip (search, pan, measure, layers, …).",
+      "whenToUse": "Custom map layouts; usually included inside geo-map-shell.",
+      "doNotUseWhen": "Full portal — use geo-map-shell.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -3732,19 +3849,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-toolbar\n  [controller]=\"ctrl\"\n  [actions]=\"actions\"\n  [(checkedMap)]=\"checked\"\n  (actionClick)=\"onTool($event)\"\n></geo-map-toolbar>"
         }
       ],
-      "example": "<geo-map-toolbar></geo-map-toolbar>",
+      "example": "<geo-map-toolbar\n  [controller]=\"ctrl\"\n  [actions]=\"actions\"\n  [(checkedMap)]=\"checked\"\n  (actionClick)=\"onTool($event)\"\n></geo-map-toolbar>",
       "related": []
     },
     {
       "name": "GeoMapZoomComponent",
       "selector": "geo-map-zoom",
-      "category": "other",
-      "summary": "GeoMapZoomComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "map",
+      "summary": "Zoom +/- and optional province / home navigation control.",
+      "whenToUse": "Custom map chrome; geo-map-shell embeds this.",
+      "doNotUseWhen": "Relying on OpenLayers built-in zoom alone is fine for bare geo-map.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -3787,19 +3905,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-map-zoom [controller]=\"ctrl\" [showNav]=\"true\"></geo-map-zoom>"
         }
       ],
-      "example": "<geo-map-zoom></geo-map-zoom>",
+      "example": "<geo-map-zoom [controller]=\"ctrl\" [showNav]=\"true\"></geo-map-zoom>",
       "related": []
     },
     {
       "name": "GeoOverlapResultComponent",
       "selector": "geo-overlap-result",
-      "category": "other",
-      "summary": "GeoOverlapResultComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "data",
+      "summary": "Overlap analysis result list (planning type, area, percent).",
+      "whenToUse": "Show giao cắt quy hoạch vs hiện trạng results.",
+      "doNotUseWhen": "Generic tables — use geo-table.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -3842,19 +3961,20 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-overlap-result [rows]=\"rows\" (rowClick)=\"focus($event)\"></geo-overlap-result>"
         }
       ],
-      "example": "<geo-overlap-result></geo-overlap-result>",
+      "example": "<geo-overlap-result [rows]=\"rows\" (rowClick)=\"focus($event)\"></geo-overlap-result>",
       "related": []
     },
     {
       "name": "GeoPageHeaderComponent",
       "selector": "geo-page-header",
-      "category": "other",
-      "summary": "GeoPageHeaderComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "display",
+      "summary": "Compact page header block (title + optional actions slot).",
+      "whenToUse": "Section headers on dashboard / list pages.",
+      "doNotUseWhen": "Full page title under breadcrumb — prefer geo-page-title.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -3885,10 +4005,11 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-page-header title=\"Thống kê nhanh\"></geo-page-header>"
         }
       ],
-      "example": "<geo-page-header></geo-page-header>",
+      "example": "<geo-page-header title=\"Thống kê nhanh\"></geo-page-header>",
       "related": []
     },
     {
@@ -4346,7 +4467,7 @@
       "selector": "geo-slider",
       "category": "forms",
       "summary": "Numeric range slider.",
-      "whenToUse": "Continuous numeric value in a range.",
+      "whenToUse": "Continuous numeric value in a range (opacity, percent).",
       "doNotUseWhen": "Discrete small sets — use select/radio.",
       "howTo": "Thanh trượt số liên tục. Two-way [(value)] / (valueChange); min/max/step; tipFormatter tùy chỉnh tooltip.",
       "tips": [
@@ -4418,10 +4539,10 @@
     {
       "name": "GeoStatCardComponent",
       "selector": "geo-stat-card",
-      "category": "other",
-      "summary": "GeoStatCardComponent",
-      "whenToUse": "",
-      "doNotUseWhen": "",
+      "category": "data",
+      "summary": "KPI stat card (label, value, optional delta / icon).",
+      "whenToUse": "Dashboard summary tiles.",
+      "doNotUseWhen": "Detailed tables — use geo-table.",
       "howTo": "",
       "tips": [],
       "binding": "none",
@@ -4500,10 +4621,11 @@
       "examples": [
         {
           "title": "Example",
-          "lang": "html"
+          "lang": "html",
+          "code": "<geo-stat-card label=\"Tổng thửa\" [value]=\"12450\" unit=\"thửa\"></geo-stat-card>"
         }
       ],
-      "example": "<geo-stat-card></geo-stat-card>",
+      "example": "<geo-stat-card label=\"Tổng thửa\" [value]=\"12450\" unit=\"thửa\"></geo-stat-card>",
       "related": []
     },
     {
@@ -5709,12 +5831,24 @@
           "default": "false",
           "note": ""
         },
+        {
+          "name": "selectionMode",
+          "type": "'single' | 'multi'",
+          "default": "'multi'",
+          "note": "`single` — click chọn đúng 1 node (BR-06-03); `multi` — giữ hành vi checkbox hiện có."
+        },
         {
           "name": "checkedKeys",
           "type": "Array<string | number>",
           "default": "[]",
           "note": "Two-way `model()` (supports banana binding)."
         },
+        {
+          "name": "selectedKeys",
+          "type": "Array<string | number>",
+          "default": "[]",
+          "note": "Two-way `model()` (supports banana binding)."
+        },
         {
           "name": "expandedKeys",
           "type": "Array<string | number>",