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

Định nghĩa trong useMapLayers.ts qua getBaseMapStyle().

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
• graticules-line
• land
• bg-countries-fill
• bg-country-borders-line
• country-labels
• regions-line
• lakes-fill
• rivers-line
• geolines-line

Lưu ý:

• không phải layer nào trong list cũng nhất thiết được add từ cùng một source path trong tương lai
• BackgroundLayersPanel chỉ biết toggle theo id

Visibility mặc định:

• tất cả true
• đượ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
• war
• battle
• civilization
• rebellion_zone
• person_deathplace
• person_birthplace
• person_activity
• temple
• capital
• city
• fortress
• castle
• ruin
• port
• bridge

GEOMETRY_TYPE_OPTIONS trong 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)

Đ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.

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.