History-user/src/uhm/doc/map_styling.md

UHM map styling - hệ thống layer và style

Tài liệu này mô tả styling thật đang được map editor dùng.

1. Hai nhóm style chính

Map hiện có hai nhóm style tách biệt:

• background/base map style
• geotype style cho dữ liệu editor

Background/base map

getBaseMapStyle() chỉ tạo skeleton style có background layer và Goong glyph proxy. Raster/vector background thật được thêm sau khi map load qua mapUtils.ts và tiles.ts.

Geotype style

Định nghĩa trong src/uhm/lib/map/styles/.

2. Background layers đang có

Danh sách layer toggle được expose ở backgroundLayers.ts:

• raster-base-layer
• bg-country-borders-line
• bg-province-borders-line
• bg-district-borders-line
• country-labels
• rivers-line

Lưu ý:

• raster-base-layer là layer raster lazy-add từ goong_satellite.json
• các nhóm còn lại là overlay layer clone từ goong_map_web.json
• overlay layer thật có id dạng goong-..., nhưng metadata uhmBackgroundGroupId trỏ về toggle id ở trên
• BackgroundLayersPanel chỉ biết toggle theo id

Visibility mặc định:

• raster-base-layer, bg-country-borders-line, country-labels, rivers-line bật
• bg-province-borders-line, bg-district-borders-line tắt
• được persist bằng uhm.backgroundLayerVisibility.v1

3. Geotype registry

Geotype render hiện được tập trung ở getAllGeotypeLayers(...) trong geotypeLayers.ts.

Các type đang được register:

• defense_line
• attack_route
• retreat_route
• invasion_route
• migration_route
• refugee_route
• trade_route
• shipping_route
• country
• state
• empire
• kingdom
• faction
• war
• battle
• civilization
• rebellion_zone
• person_deathplace
• person_birthplace
• person_activity
• temple
• capital
• city
• fortress
• castle
• ruin
• port
• bridge

GEOMETRY_TYPE_OPTIONS trong src/uhm/lib/map/geo/geometryTypeOptions.ts phải khớp với tập geotype này nếu muốn user chọn được từ UI.

4. Type matching

Style matcher trung tâm là:

• TYPE_MATCH_EXPR = ["coalesce", ["get", "type"], ["get", "entity_type_id"], ""]

Điều này cho phép layer match theo:

• feature.properties.type
• fallback sang entity_type_id nếu cần

Với editor hiện tại, type là field chính.

5. Point, line, polygon và label sources

Map không render mọi thứ từ một source duy nhất theo nghĩa trực tiếp. Pipeline hiện tại tách ra:

• countries
  • polygon và line-like feature data
• places
  • point data
• PATH_ARROW_SOURCE_ID
  • arrow shapes cho route/path
• POLYGON_LABEL_SOURCE_ID
  • polygon labels

Label layer cho polygon/line đi qua:

• getAllGeotypeLabelLayers(...)
• helper trong shared/polygonLabels.ts
• helper trong shared/lineLabels.ts

6. Icon point

Point geotype dùng icon pipeline trong:

• shared/pointStyle.ts
• ensurePointGeotypeIcons(map)

Icon point hiện chọn theo geotype bình thường. Không còn branch icon/style riêng cho draft-orphan geometry.

Điều này có nghĩa là khi thêm geotype point mới, chỉ thêm layer là chưa đủ; cần chắc icon/style builder cũng hiểu type mới đó.

7. Preview và edit styling

Ngoài style dữ liệu chính, map còn có style riêng cho:

Draw preview

• draw-preview-fill
• draw-preview-line
• draw-circle-preview-fill
• draw-circle-preview-line
• draw-line-preview-line
• draw-path-preview-line
• draw-path-preview-arrows

Editing overlay

• edit-shape-line
• edit-handles-circle

Focus/highlight

• entity-focus-fill
• entity-focus-line
• entity-focus-points

Các layer này không đi qua geotype registry.

8. Visibility filtering

Có ba lớp filter hiển thị trong runtime:

1. background layer visibility
2. geometry visibility theo type key từ panel phải
3. binding filter / replay filter / timeline filter ở phía data trước khi set source

Vì vậy khi một geometry "không hiện", có thể nguyên nhân nằm ở data filtering chứ không phải style layer.

Geometry không bind entity không có màu/icon riêng trên map. Trạng thái orphan/time/timeline nằm trong GeometryBindingPanel, còn map chỉ giữ style geotype + selected/focus/edit states.

9. Thêm geotype mới - checklist đúng với code hiện tại

Nếu thêm một geotype mới, nên đi theo checklist này:

1. Thêm mapping vào geoTypeMap nếu backend dùng numeric/type code.
2. Thêm option vào geometryTypeOptions.ts.
3. Tạo file style mới trong styles/geotypes/.
4. Register nó trong getAllGeotypeLayers(...).
5. Nếu cần label riêng, cập nhật layer builder tương ứng.
6. Nếu là point type, kiểm tra icon pipeline.
7. Nếu muốn user tạo geometry mới với type đó mặc định từ tool nào đó, cập nhật useMapInteraction.ts.

10. Điều doc cũ mô tả chưa chính xác

Doc cũ nói tới filter thời gian ở từng layer như một biểu thức layer-level chuẩn. Implementation hiện tại không làm vậy.

Thay vào đó:

• timeline filter đang chạy phía data trong page.tsx
• binding filter và geometry visibility cũng chủ yếu chạy trước khi set source

Tức là phần lớn filtering là prepare data -> set source, không phải add layer filter expression per year.