@geoit/ui 0.0.5 → 0.0.7

package/ai/components/geo-map-opacity.md

@@ -5,7 +5,7 @@
 > Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-GeoMapOpacityComponent
+Layer opacity slider bound to a map layer id.
 
 ## Import
 
@@ -23,13 +23,13 @@ imports: [GeoMapOpacityComponent]
 `geo-map-opacity`
 
 ## Category
-`other`
+`map`
 
 ## When to use
-—
+Adjust overlay transparency in custom layer UI.
 
 ## Do not use when
-—
+Full layer list — use geo-map-layer-panel / layers drawer.
 
 
 ## Binding
@@ -59,7 +59,7 @@ _None_
 ### Example
 
 ```html
-<geo-map-opacity></geo-map-opacity>
+<geo-map-opacity [controller]="ctrl" layerId="demo-qhsdd-2020" [(opacity)]="opacity"></geo-map-opacity>
 ```
 
 ## Package path

package/ai/components/geo-map-parcel-popup.md

@@ -5,7 +5,7 @@
 > Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-GeoMapParcelPopupComponent
+Parcel detail popup (citizen / specialist audience).
 
 ## Import
 
@@ -23,13 +23,13 @@ imports: [GeoMapParcelPopupComponent]
 `geo-map-parcel-popup`
 
 ## Category
-`other`
+`map`
 
 ## When to use
-—
+Show thửa detail after search or map click.
 
 ## Do not use when
-—
+Full detail page — navigate to a route instead.
 
 
 ## Binding
@@ -63,7 +63,12 @@ Every supported Input (do not invent others):
 ### Example
 
 ```html
-<geo-map-parcel-popup></geo-map-parcel-popup>
+<geo-map-parcel-popup
+  [(open)]="parcelOpen"
+  [parcel]="selected"
+  audience="citizen"
+  (exportClick)="exportPdf($event)"
+></geo-map-parcel-popup>
 ```
 
 ## Package path

package/ai/components/geo-map-search.md

@@ -5,7 +5,7 @@
 > Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-GeoMapSearchComponent
+Map search panel (owner / certificate / parcel / address / coordinates).
 
 ## Import
 
@@ -23,13 +23,13 @@ imports: [GeoMapSearchComponent]
 `geo-map-search`
 
 ## Category
-`other`
+`map`
 
 ## When to use
-—
+Tra cứu thửa on portal; prefer via geo-map-shell.
 
 ## Do not use when
-—
+Global app search unrelated to map.
 
 
 ## Binding
@@ -67,7 +67,13 @@ Every supported Input (do not invent others):
 ### Example
 
 ```html
-<geo-map-search></geo-map-search>
+<geo-map-search
+  [(open)]="searchOpen"
+  mode="parcel"
+  [results]="results"
+  (search)="runSearch($event)"
+  (resultSelect)="onSelect($event)"
+></geo-map-search>
 ```
 
 ## Package path

package/ai/components/geo-map-shell.md

@@ -5,7 +5,7 @@
 > Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-GeoMapShellComponent
+Full map portal chrome: search, ĐVHC, layers, legend, measure, basemap, parcel popup.
 
 ## Import
 
@@ -23,14 +23,17 @@ imports: [GeoMapShellComponent]
 `geo-map-shell`
 
 ## Category
-`other`
+`map`
 
 ## When to use
-—
+Public / specialist map portal pages (tra cứu quy hoạch). Prefer this over composing chrome by hand.
 
 ## Do not use when
-—
+Bare map embed without UI chrome — use geo-map only.
 
+## How to use
+
+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.
 
 ## Binding
 
@@ -53,7 +56,10 @@ Every supported Input (do not invent others):
 | `showNav` | `boolean` | `true` | — |
 | `includeDemoLayers` | `boolean` | `true` | — |
 | `adminNodes` | `GeoTreeNode[]` | `GEO_MAP_DEMO_ADMIN_NODES` | — |
+| `adminSelectionMode` | `'single' \| 'multi'` | `'multi'` | `single` — chọn đúng 1 xã/phường (BR-06-03); `multi` — checkbox nhiều cấp (mặc định). |
 | `locationLabel` | `string` | `'Phường 1 — TP Đà Lạt, Lâm Đồng'` | — |
+| `measureDisclaimer` | `string \| null` | `'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.'` | 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`. |
+| `legendCatalogMissing` | `boolean` | `false` | True khi danh mục chú giải không tải được (`ERR_MAP_LEGEND_CATALOG_MISSING`). |
 | `parcelAudience` | `GeoMapParcelAudience` | `'citizen'` | — |
 | `provinceExtent` | `readonly [number, number, number, number]` | `GEO_MAP_DEFAULT_PROVINCE_EXTENT_4326` | — |
 | `demoSearch` | `boolean` | `true` | When true, shell seeds mock search results (Storybook / demos). |
@@ -80,23 +86,60 @@ Every supported Input (do not invent others):
 |--------|---------|-------------|
 | `mapReady` | `OutputEmitterRef<GeoMapController>` | — |
 | `mapClick` | `OutputEmitterRef<GeoMapClickEvent>` | — |
+| `located` | `OutputEmitterRef<[number, number]>` | — |
 | `locateDenied` | `OutputEmitterRef<void>` | — |
+| `locateError` | `OutputEmitterRef<{ reason: GeoMapLocateErrorReason; message?: string }>` | — |
 | `actionClick` | `OutputEmitterRef<GeoMapToolbarAction>` | — |
 | `search` | `OutputEmitterRef<GeoMapSearchQuery>` | — |
 | `searchReset` | `OutputEmitterRef<void>` | — |
 | `resultSelect` | `OutputEmitterRef<GeoMapSearchResultItem>` | — |
 | `parcelExport` | `OutputEmitterRef<GeoMapParcelDetail>` | — |
 | `adminApply` | `OutputEmitterRef<Array<string \| number>>` | — |
+| `snapshotCaptured` | `OutputEmitterRef<void>` | — |
+| `snapshotError` | `OutputEmitterRef<unknown>` | — |
 
 
 ## Examples
 
-### Example
+### Basic portal
 
 ```html
-<geo-map-shell></geo-map-shell>
+<geo-map-shell
+  height="640px"
+  [demoSearch]="false"
+  parcelAudience="citizen"
+  [layers]="layers"
+  (mapReady)="ctrl = $event"
+  (search)="onSearch($event)"
+></geo-map-shell>
 ```
 
+### Open search panel
+
+```html
+<geo-map-shell
+  height="640px"
+  [demoSearch]="false"
+  [(searchOpen)]="searchOpen"
+  [(searchResults)]="results"
+  (search)="runQuery($event)"
+  (resultSelect)="onResult($event)"
+></geo-map-shell>
+```
+
+## 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.
+## Related components
+
+- [`geo-map`](./geo-map.md)
+- [`geo-map-search`](./geo-map-search.md)
+- [`geo-map-toolbar`](./geo-map-toolbar.md)
+- [`geo-map-layers-drawer`](./geo-map-layers-drawer.md)
 ## Package path
 `node_modules/@geoit/ui/ai/components/geo-map-shell.md`
 

package/ai/components/geo-map-snapshot.md

@@ -5,7 +5,7 @@
 > Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-GeoMapSnapshotComponent
+Capture current map canvas to image / download.
 
 ## Import
 
@@ -23,13 +23,13 @@ imports: [GeoMapSnapshotComponent]
 `geo-map-snapshot`
 
 ## Category
-`other`
+`map`
 
 ## When to use
-—
+Export screenshot control on map chrome.
 
 ## Do not use when
-—
+Server-side tile export pipelines.
 
 
 ## Binding
@@ -59,7 +59,7 @@ Every supported Input (do not invent others):
 ### Example
 
 ```html
-<geo-map-snapshot></geo-map-snapshot>
+<geo-map-snapshot [controller]="ctrl" (captured)="onShot($event)"></geo-map-snapshot>
 ```
 
 ## Package path

package/ai/components/geo-map-swipe.md

@@ -5,7 +5,7 @@
 > Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-GeoMapSwipeComponent
+Swipe compare control between two map layers.
 
 ## Import
 
@@ -23,13 +23,13 @@ imports: [GeoMapSwipeComponent]
 `geo-map-swipe`
 
 ## Category
-`other`
+`map`
 
 ## When to use
-—
+Before/after planning vs current-use comparison.
 
 ## Do not use when
-—
+Simple opacity blend — use geo-map-opacity.
 
 
 ## Binding
@@ -57,7 +57,7 @@ _None_
 ### Example
 
 ```html
-<geo-map-swipe></geo-map-swipe>
+<geo-map-swipe [controller]="ctrl" [(active)]="swipeOn" layerId="demo-qhsdd-2020"></geo-map-swipe>
 ```
 
 ## Package path

package/ai/components/geo-map-toolbar.md

@@ -5,7 +5,7 @@
 > Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-GeoMapToolbarComponent
+Vertical map tool strip (search, pan, measure, layers, …).
 
 ## Import
 
@@ -23,13 +23,13 @@ imports: [GeoMapToolbarComponent]
 `geo-map-toolbar`
 
 ## Category
-`other`
+`map`
 
 ## When to use
-—
+Custom map layouts; usually included inside geo-map-shell.
 
 ## Do not use when
-—
+Full portal — use geo-map-shell.
 
 
 ## Binding
@@ -60,7 +60,12 @@ Every supported Input (do not invent others):
 ### Example
 
 ```html
-<geo-map-toolbar></geo-map-toolbar>
+<geo-map-toolbar
+  [controller]="ctrl"
+  [actions]="actions"
+  [(checkedMap)]="checked"
+  (actionClick)="onTool($event)"
+></geo-map-toolbar>
 ```
 
 ## Package path

package/ai/components/geo-map-zoom.md

@@ -5,7 +5,7 @@
 > Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-GeoMapZoomComponent
+Zoom +/- and optional province / home navigation control.
 
 ## Import
 
@@ -23,13 +23,13 @@ imports: [GeoMapZoomComponent]
 `geo-map-zoom`
 
 ## Category
-`other`
+`map`
 
 ## When to use
-—
+Custom map chrome; geo-map-shell embeds this.
 
 ## Do not use when
-—
+Relying on OpenLayers built-in zoom alone is fine for bare geo-map.
 
 
 ## Binding
@@ -58,7 +58,7 @@ _None_
 ### Example
 
 ```html
-<geo-map-zoom></geo-map-zoom>
+<geo-map-zoom [controller]="ctrl" [showNav]="true"></geo-map-zoom>
 ```
 
 ## Package path

package/ai/components/geo-map.md

@@ -29,8 +29,11 @@ imports: [GeoMapComponent]
 Any map viewport (portal quy hoạch, tra cứu thửa). Peers: ol, proj4.
 
 ## Do not use when
-Non-map charting — use dashboard libs.
+Full portal chrome — prefer geo-map-shell; non-map charts — use geo-chart.
 
+## How to use
+
+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.
 
 ## Binding
 
@@ -180,18 +183,22 @@ export interface GeoMapLayerVisibilityChange {
 
 ## Examples
 
-### Example
+### Basic
 
 ```html
-<geo-map
-  [center]="center"
-  [zoom]="12"
-  [layers]="layers"
-  height="480px"
-  (mapReady)="ctrl = $event"
-></geo-map>
+<geo-map height="480px" basemap="osm" [center]="[108.45, 11.94]" [zoom]="12" (mapReady)="ctrl = $event"></geo-map>
 ```
 
+## Tips
+
+- Portal đầy đủ → geo-map-shell.
+- showZoomControl=false khi dùng geo-map-zoom riêng.
+- Peers: ol, proj4.
+## Related components
+
+- [`geo-map-shell`](./geo-map-shell.md)
+- [`geo-map-zoom`](./geo-map-zoom.md)
+- [`geo-map-toolbar`](./geo-map-toolbar.md)
 ## Package path
 `node_modules/@geoit/ui/ai/components/geo-map.md`
 

package/ai/components/geo-overlap-result.md

@@ -5,7 +5,7 @@
 > Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-GeoOverlapResultComponent
+Overlap analysis result list (planning type, area, percent).
 
 ## Import
 
@@ -23,13 +23,13 @@ imports: [GeoOverlapResultComponent]
 `geo-overlap-result`
 
 ## Category
-`other`
+`data`
 
 ## When to use
-—
+Show giao cắt quy hoạch vs hiện trạng results.
 
 ## Do not use when
-—
+Generic tables — use geo-table.
 
 
 ## Binding
@@ -72,7 +72,7 @@ export interface GeoOverlapResultRow {
 ### Example
 
 ```html
-<geo-overlap-result></geo-overlap-result>
+<geo-overlap-result [rows]="rows" (rowClick)="focus($event)"></geo-overlap-result>
 ```
 
 ## Package path

package/ai/components/geo-page-header.md

@@ -5,7 +5,7 @@
 > Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-GeoPageHeaderComponent
+Compact page header block (title + optional actions slot).
 
 ## Import
 
@@ -23,13 +23,13 @@ imports: [GeoPageHeaderComponent]
 `geo-page-header`
 
 ## Category
-`other`
+`display`
 
 ## When to use
-—
+Section headers on dashboard / list pages.
 
 ## Do not use when
-—
+Full page title under breadcrumb — prefer geo-page-title.
 
 
 ## Binding
@@ -56,7 +56,7 @@ _None_
 ### Example
 
 ```html
-<geo-page-header></geo-page-header>
+<geo-page-header title="Thống kê nhanh"></geo-page-header>
 ```
 
 ## Package path

package/ai/components/geo-slider.md

@@ -26,7 +26,7 @@ imports: [GeoSliderComponent]
 `forms`
 
 ## When to use
-Continuous numeric value in a range.
+Continuous numeric value in a range (opacity, percent).
 
 ## Do not use when
 Discrete small sets — use select/radio.

package/ai/components/geo-stat-card.md

@@ -5,7 +5,7 @@
 > Read this file before using the component. Use **only** the Inputs/Outputs listed here.
 
 ## Summary
-GeoStatCardComponent
+KPI stat card (label, value, optional delta / icon).
 
 ## Import
 
@@ -23,13 +23,13 @@ imports: [GeoStatCardComponent]
 `geo-stat-card`
 
 ## Category
-`other`
+`data`
 
 ## When to use
-—
+Dashboard summary tiles.
 
 ## Do not use when
-—
+Detailed tables — use geo-table.
 
 
 ## Binding
@@ -82,7 +82,7 @@ export interface GeoStatCardItem {
 ### Example
 
 ```html
-<geo-stat-card></geo-stat-card>
+<geo-stat-card label="Tổng thửa" [value]="12450" unit="thửa"></geo-stat-card>
 ```
 
 ## Package path

package/ai/components/geo-tree.md

@@ -47,7 +47,9 @@ Every supported Input (do not invent others):
 |-------|------|---------|-------------|
 | `nodes` | `GeoTreeNode[]` | `[]` | — |
 | `checkable` | `boolean` | `false` | — |
+| `selectionMode` | `'single' \| 'multi'` | `'multi'` | `single` — click chọn đúng 1 node (BR-06-03); `multi` — giữ hành vi checkbox hiện có. |
 | `checkedKeys` | `Array<string \| number>` | `[]` | Two-way `model()` (supports banana binding). |
+| `selectedKeys` | `Array<string \| number>` | `[]` | Two-way `model()` (supports banana binding). |
 | `expandedKeys` | `Array<string \| number>` | `[]` | Two-way `model()` (supports banana binding). |
 | `showLine` | `boolean` | `false` | — |
 | `blockNode` | `boolean` | `false` | — |

package/ai/mockup.html

@@ -5,7 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>@geoit/ui — Component mockup (design tokens)</title>
   <!-- Generated by tools/generate-mockup.js — do not edit ai/mockup.html by hand -->
-  <!-- 2026-08-24T03:07:52.146Z -->
+  <!-- 2026-09-04T07:20:22.216Z -->
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
   <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
@@ -685,7 +685,7 @@
           HTML tĩnh mô phỏng visual của các <code>geo-*</code> trong <code>ai/components</code>,
           dùng đúng CSS variables từ <code>design-tokens.scss</code>.
           Tokens được inject tự động khi <code>npm run ai:docs</code> / <code>npm run build</code>.
-          <br /><span class="typo-caption typo-secondary">Generated 2026-08-24T03:07:52.146Z · source: projects/geo-ui/src/lib/styles/design-tokens.scss · 66 component docs in ai/components</span>
+          <br /><span class="typo-caption typo-secondary">Generated 2026-09-04T07:20:22.216Z · source: projects/geo-ui/src/lib/styles/design-tokens.scss · 66 component docs in ai/components</span>
         </p>
       </header>
 

package/ai/recipes.md

@@ -194,3 +194,89 @@ Primitives: `geo-stat-card`, `geo-chart` (bar/donut), `geo-page-header`, `geo-em
 List pages (thống kê tờ/bản đồ, QL người dùng, đồng bộ iLIS, QL bản đồ): `geo-list-page` + `geo-table-toolbar` + `geo-table` + `geo-form-modal`.
 
 Storybook: `GEO/Pages/Admin CRUD` (STT 28, TCQH.24, STT 31).
+
+## 13. Map portal (`geo-map-shell`) — recommended
+
+Peers: `ol`, `proj4`. Prefer shell over hand-wiring chrome.
+
+```ts
+import {
+  GeoMapShellComponent,
+  type GeoMapController,
+  type GeoMapSearchQuery,
+  type GeoMapSearchResultItem,
+} from "@geoit/ui";
+```
+
+```html
+<geo-map-shell
+  height="calc(100vh - 64px)"
+  [demoSearch]="false"
+  parcelAudience="citizen"
+  [includeDemoLayers]="false"
+  [layers]="layers"
+  [(searchOpen)]="searchOpen"
+  (mapReady)="onMapReady($event)"
+  (search)="onSearch($event)"
+  (resultSelect)="onResult($event)"
+  (parcelExport)="onExport($event)"
+></geo-map-shell>
+```
+
+```ts
+ctrl: GeoMapController | null = null;
+searchOpen = false;
+layers = []; // GeoMapLayerConfig[] from API
+
+onMapReady(c: GeoMapController): void {
+  this.ctrl = c;
+}
+
+onSearch(q: GeoMapSearchQuery): void {
+  // call API → patch shell [(searchResults)] / selectedParcel
+}
+
+onResult(item: GeoMapSearchResultItem): void {
+  // optional: flyTo via this.ctrl
+}
+```
+
+### Bare map (no chrome)
+
+```html
+<geo-map
+  height="480px"
+  [center]="[108.45, 11.94]"
+  [zoom]="12"
+  basemap="osm"
+  [layers]="layers"
+  [showZoomControl]="false"
+  (mapReady)="ctrl = $event"
+></geo-map>
+```
+
+### Map chrome pieces (custom shells only)
+
+Use when **not** using `geo-map-shell`: `geo-map-toolbar`, `geo-map-search`, `geo-map-admin-filter`, `geo-map-layers-drawer`, `geo-map-legend`, `geo-map-help`, `geo-map-basemap-switcher`, `geo-map-zoom`, `geo-map-measure`, `geo-map-swipe`, `geo-map-parcel-popup`, `geo-map-location-chip`.
+
+Read `ai/components/geo-map-shell.md` and `ai/components/geo-map.md` before composing.
+
+## 14. Date / date range in forms
+
+```html
+<geo-date-picker
+  label="Ngày hiệu lực"
+  format="dd/MM/yyyy"
+  [required]="true"
+  [block]="true"
+  [(ngModel)]="effectiveDate"
+></geo-date-picker>
+
+<geo-date-range-picker
+  label="Khoảng thời gian"
+  [block]="true"
+  [(ngModel)]="range"
+></geo-date-range-picker>
+```
+
+App must provide `provideAnimations()` + `provideNzI18n(vi_VN)` for the picker overlay.