@geolonia/maps-core 0.4.2 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,15 +1,29 @@
1
1
  import maplibregl, { IControl, ControlPosition, Map, MapOptions, ExpiryData, StyleSpecification, StyleSwapOptions, StyleOptions, GetResourceResponse, MarkerOptions } from 'maplibre-gl';
2
2
 
3
3
  /**
4
- * Custom Attribution Control using Shadow DOM.
5
- * Based on maplibre-gl-js's AttributionControl.
4
+ * Shadow DOM を用いたカスタム帰属表示コントロールの実装です。
5
+ * maplibre-gl-js の AttributionControl をもとにしています。
6
6
  * https://github.com/maplibre/maplibre-gl-js/blob/main/src/ui/control/attribution_control.ts
7
7
  *
8
- * Uses Shadow DOM to isolate attribution styles from the host page,
9
- * preventing style conflicts. Collapses to an "i" icon on small maps.
8
+ * Shadow DOM で帰属表示のスタイルをホストページから隔離し、スタイルの衝突を防ぎます。
9
+ * 地図の表示幅が小さい場合は "i" アイコンに折りたたみます。
10
+ */
11
+ /**
12
+ * {@link CustomAttributionControl} の生成時に渡すオプションです。
10
13
  */
11
14
  interface CustomAttributionControlOptions {
15
+ /**
16
+ * 帰属表示をコンパクト表示にするかどうかを指定します。
17
+ * `true` を指定すると常に "i" アイコンに折りたたんだコンパクト表示になり、
18
+ * `false` を指定すると常に展開したまま表示します。
19
+ * 省略した場合は地図の表示幅に応じて自動的に切り替わります
20
+ * (幅が 640px 以下のときにコンパクト表示になります)。
21
+ */
12
22
  compact?: boolean;
23
+ /**
24
+ * ソース由来の帰属表示に加えて表示する、独自の帰属表示テキストです。
25
+ * 文字列または文字列の配列で指定します。
26
+ */
13
27
  customAttribution?: string | string[];
14
28
  }
15
29
  interface StyleDataEvent {
@@ -17,6 +31,19 @@ interface StyleDataEvent {
17
31
  dataType?: string;
18
32
  type?: string;
19
33
  }
34
+ /**
35
+ * 帰属表示(アトリビューション)を表示する、Geolonia 向けにカスタムしたコントロールです。
36
+ *
37
+ * MapLibre 標準の `AttributionControl` をもとにしており、`IControl` を実装します。
38
+ * スタイルの衝突を防ぐためにコンテナを Shadow DOM で分離し、コントロール用の CSS を
39
+ * その内部に閉じ込めます。地図の表示幅が狭いとき(またはオプション指定時)は "i" アイコンに
40
+ * 折りたたむコンパクト表示に切り替わり、印刷時には自動的に展開表示へ切り替えます。
41
+ *
42
+ * @example
43
+ * ```ts
44
+ * map.addControl(new CustomAttributionControl(), "bottom-right");
45
+ * ```
46
+ */
20
47
  declare class CustomAttributionControl implements IControl {
21
48
  private options;
22
49
  private _map;
@@ -28,9 +55,35 @@ declare class CustomAttributionControl implements IControl {
28
55
  private _attribHTML;
29
56
  private printQuery;
30
57
  private onMediaPrintChange;
58
+ /**
59
+ * コントロールを生成します。
60
+ *
61
+ * @param options 帰属表示の挙動を指定するオプションです。省略した場合は空のオブジェクトが使われます。
62
+ */
31
63
  constructor(options?: CustomAttributionControlOptions);
64
+ /**
65
+ * このコントロールの既定の表示位置を返します。
66
+ *
67
+ * @returns 既定の表示位置である `"bottom-right"` を返します。
68
+ */
32
69
  getDefaultPosition(): ControlPosition;
70
+ /**
71
+ * コントロールが地図に追加されるときに呼び出されます。
72
+ *
73
+ * Shadow DOM を持つコンテナ要素を生成し、その内部に帰属表示用の要素と CSS を組み立てます。
74
+ * あわせて帰属表示の内容を初期化し、地図の各種イベント(`styledata`、`sourcedata`、`terrain`、
75
+ * `resize`、`drag`)や印刷メディアクエリの変化を監視するリスナーを登録します。
76
+ *
77
+ * @param map このコントロールを追加する対象の地図です。
78
+ * @returns 地図に挿入するコントロールのルート要素を返します。
79
+ */
33
80
  onAdd(map: Map): HTMLDivElement;
81
+ /**
82
+ * コントロールが地図から取り除かれるときに呼び出されます。
83
+ *
84
+ * 生成したコンテナ要素を DOM から削除し、`onAdd` で登録した地図のイベントリスナーと
85
+ * 印刷メディアクエリのリスナーを解除したうえで、内部で保持している状態を破棄します。
86
+ */
34
87
  onRemove(): void;
35
88
  _setElementTitle(element: HTMLElement, title: string): void;
36
89
  _toggleAttribution(): void;
@@ -40,110 +93,518 @@ declare class CustomAttributionControl implements IControl {
40
93
  _updateCompactMinimize(): void;
41
94
  }
42
95
 
96
+ /**
97
+ * 地図上に Geolonia のロゴを表示するコントロールです。
98
+ *
99
+ * MapLibre の `IControl` を実装しており、`Map.addControl` で地図に追加できます。
100
+ * 表示されるロゴは Geolonia のサイト(`https://geolonia.com/`)へのリンクになっており、
101
+ * クリックすると同サイトを開きます。
102
+ *
103
+ * @example
104
+ * ```ts
105
+ * map.addControl(new GeoloniaControl(), "bottom-left");
106
+ * ```
107
+ */
43
108
  declare class GeoloniaControl implements IControl {
44
109
  private container;
110
+ /**
111
+ * コントロールの DOM 要素を生成して返します。
112
+ *
113
+ * `IControl` の実装として、`Map.addControl` で地図に追加された際に MapLibre から呼び出されます。
114
+ * Geolonia のロゴ画像を含み、`https://geolonia.com/` へのリンクが設定された要素を組み立てて返します。
115
+ *
116
+ * @returns このコントロールのコンテナとなる `HTMLDivElement`。
117
+ */
45
118
  onAdd(): HTMLDivElement;
119
+ /**
120
+ * コントロールの DOM 要素を地図から除去します。
121
+ *
122
+ * `IControl` の実装として、`Map.removeControl` で地図から取り除かれた際に MapLibre から呼び出されます。
123
+ * `onAdd` で生成したコンテナを親ノードから削除します。
124
+ */
46
125
  onRemove(): void;
126
+ /**
127
+ * このコントロールの既定の表示位置を返します。
128
+ *
129
+ * `Map.addControl` で位置を明示しなかった場合に使用されます。
130
+ *
131
+ * @returns 既定の表示位置 `"bottom-left"`。
132
+ */
47
133
  getDefaultPosition(): ControlPosition;
48
134
  }
49
135
 
136
+ /**
137
+ * {@link GeoloniaMap} のコンストラクタに渡すオプション。
138
+ *
139
+ * MapLibre GL JS の `MapOptions` を拡張し、Geolonia 固有の設定
140
+ * (API キー、スタイル、マーカー、各種コントロール、GeoJSON 表示など)を
141
+ * 追加したものである。`container` や `center`、`zoom` などの基本オプションは
142
+ * MapLibre の `MapOptions` から継承する。
143
+ *
144
+ * @example
145
+ * ```typescript
146
+ * const map = new GeoloniaMap({
147
+ * container: "#map",
148
+ * apiKey: "YOUR-API-KEY",
149
+ * style: "geolonia/basic-v2",
150
+ * center: [139.7671, 35.6812],
151
+ * zoom: 14,
152
+ * lang: "ja",
153
+ * });
154
+ * ```
155
+ */
50
156
  type GeoloniaMapOptions = MapOptions & {
51
- /** Geolonia API key */
157
+ /**
158
+ * Geolonia の API キー。Geolonia がホストするスタイルやタイルを使う場合に必要。
159
+ * 指定するとキーリングにも設定される。
160
+ */
52
161
  apiKey?: string;
53
- /** API stage (e.g. 'dev', 'v1') */
162
+ /**
163
+ * API のステージ(`'dev'` / `'v1'` など)。API エンドポイントの選択に使う。
164
+ * @defaultValue `'dev'`
165
+ */
54
166
  stage?: string;
55
- /** Map style name or URL. Default: 'geolonia/basic-v2' */
167
+ /**
168
+ * 地図スタイル。Geolonia のスタイル論理名(`'geolonia/basic-v2'`)、
169
+ * style.json の完全な URL、または相対パスのいずれか。
170
+ * @defaultValue `'geolonia/basic-v2'`
171
+ */
56
172
  style?: string;
57
- /** Language for style labels. Default: 'auto' */
173
+ /**
174
+ * ラベルの言語。`'ja'` / `'en'` / `'auto'`(ブラウザ言語に従う)。
175
+ * `'auto'` または未指定のときは `getLang()` の結果(`'ja'` または `'en'`)になる。
176
+ * @defaultValue `'auto'`
177
+ */
58
178
  lang?: "ja" | "en" | "auto";
59
- /** Show default marker at center */
179
+ /**
180
+ * 中心にデフォルトマーカーを表示するかどうか。`center` が指定されている場合にのみ
181
+ * 実際に表示される。
182
+ */
60
183
  marker?: boolean;
61
- /** Marker color (CSS color string) */
184
+ /** マーカーの色(CSS カラー文字列)。 */
62
185
  markerColor?: string;
63
- /** Automatically open marker popup on load */
186
+ /** 読み込み時にマーカーのポップアップを自動的に開くかどうか。 */
64
187
  openPopup?: boolean;
65
- /** CSS selector for a custom marker element */
188
+ /** マーカーとして使うカスタム要素の CSS セレクタ。 */
66
189
  customMarker?: string;
67
- /** Offset for custom marker as [x, y] */
190
+ /** カスタムマーカーのオフセット。`[x, y]` のピクセル値。 */
68
191
  customMarkerOffset?: [number, number];
69
- /** Show loader animation during map load */
192
+ /**
193
+ * 地図の読み込み中にローディングアニメーションを表示するかどうか。
194
+ * @defaultValue `true`
195
+ */
70
196
  loader?: boolean;
71
- /** Enable gesture handling for scroll pages */
197
+ /**
198
+ * スクロール可能なページでジェスチャ操作(2本指での地図操作の要求など)を
199
+ * 有効にするかどうか。
200
+ * @defaultValue `true`
201
+ */
72
202
  gestureHandling?: boolean;
73
- /** Navigation control. true, false, or a position string */
203
+ /**
204
+ * ズームと回転のコントロール。`true` / `false`、または表示位置
205
+ * (`'top-right'`、`'bottom-left'` など)を指定する。
206
+ * @defaultValue `true`
207
+ */
74
208
  navigationControl?: boolean | ControlPosition;
75
- /** Geolocate control */
209
+ /**
210
+ * 現在地コントロール。`true` / `false`、または表示位置を指定する。
211
+ * @defaultValue `false`
212
+ */
76
213
  geolocateControl?: boolean | ControlPosition;
77
- /** Fullscreen control */
214
+ /**
215
+ * 全画面コントロール。`true` / `false`、または表示位置を指定する。
216
+ * @defaultValue `false`
217
+ */
78
218
  fullscreenControl?: boolean | ControlPosition;
79
- /** Scale control */
219
+ /**
220
+ * スケールコントロール。`true` / `false`、または表示位置を指定する。
221
+ * @defaultValue `false`
222
+ */
80
223
  scaleControl?: boolean | ControlPosition;
81
- /** Geolonia logo control */
224
+ /**
225
+ * Geolonia のロゴコントロール。`true` / `false`、または表示位置を指定する。
226
+ * @defaultValue `true`
227
+ */
82
228
  geoloniaControl?: boolean | ControlPosition;
83
- /** GeoJSON URL or object for SimpleStyle */
229
+ /**
230
+ * SimpleStyle で表示する GeoJSON。URL、または GeoJSON オブジェクトを指定する。
231
+ * `center` が未指定のときは、この GeoJSON の範囲に自動的にフィットする。
232
+ */
84
233
  geojson?: string | GeoJSON.FeatureCollection;
85
- /** Enable clustering for GeoJSON points */
234
+ /**
235
+ * `geojson` のポイント地物をクラスタリングするかどうか。
236
+ * @defaultValue `true`
237
+ */
86
238
  cluster?: boolean;
87
- /** Cluster marker color */
239
+ /**
240
+ * クラスタマーカーの色。
241
+ * @defaultValue `'#ff0000'`
242
+ */
88
243
  clusterColor?: string;
89
- /** Simple vector tile URL */
244
+ /** SimpleStyle Vector で表示するベクトルタイルの URL または論理名。 */
90
245
  simpleVector?: string;
91
- /** Enable 3D mode */
246
+ /**
247
+ * 3D モード(対応スタイルの建物などの 3D 表示)を有効にするかどうか。
248
+ * @defaultValue `false`
249
+ */
92
250
  "3d"?: boolean;
93
251
  };
94
252
 
95
253
  type GetImageCallback = (error?: Error | null, image?: HTMLImageElement | ImageBitmap | null, expiry?: ExpiryData | null) => void;
254
+ /**
255
+ * 与えられた URL が Geolonia のタイルホストかどうかを判定します。
256
+ *
257
+ * ホスト名が `tileserver.geolonia.com` に完全一致するか、または
258
+ * `.tiles.geolonia.com` で終わる場合に Geolonia のタイルホストとみなします。
259
+ * URL の解釈に失敗した場合は `false` を返します。
260
+ *
261
+ * @param url 判定対象の URL 文字列または `URL` オブジェクト。
262
+ * @returns Geolonia のタイルホストであれば `true`、それ以外や解釈に失敗した場合は `false`。
263
+ */
96
264
  declare function isGeoloniaTilesHost(url: string | URL): boolean;
97
265
  /**
98
- * Resolve style name or URL to a full style URL.
266
+ * スタイル名または URL を完全なスタイル URL に解決します。
267
+ *
268
+ * 解決のルールは次のとおりです。
269
+ *
270
+ * - `style` が空文字の場合は、`basic-v2` のデフォルトスタイル URL を返します。
271
+ * - `style` が絶対 URL または相対 URL の場合は、そのまま解決した URL を返します。
272
+ * - `style` が `.json` で終わる場合は、`.json` ファイルへの URL として解決します。
273
+ * - 上記以外は Geolonia の論理名とみなし、
274
+ * `https://cdn.geolonia.com/style/<name>/<ja|en>.json` を返します。
275
+ *
276
+ * `lang` が `"ja"` または `"ja-jp"` の場合は `ja` 版、それ以外は `en` 版のスタイルを返します。
277
+ *
278
+ * `style` が Geolonia のスタイルであるにもかかわらず API キーが指定されていない場合は
279
+ * エラーを投げます。API キーは `options.apiKey`、指定がなければ `keyring.apiKey` を使用します。
280
+ *
281
+ * @param style スタイル名または URL。空文字の場合はデフォルトスタイルを返します。
282
+ * @param options 解決時のオプション。
283
+ * @param options.lang 言語コード。`"ja"` または `"ja-jp"` で日本語版、省略時は `"en"`。
284
+ * @param options.apiKey Geolonia スタイルの利用に必要な API キー。省略時は `keyring.apiKey` を使用します。
285
+ * @returns 解決された完全なスタイル URL。
286
+ * @throws {Error} Geolonia のスタイルであるのに API キーが指定されていない場合。
287
+ *
288
+ * @example
289
+ * ```typescript
290
+ * // 論理名を日本語版のスタイル URL に解決する
291
+ * getStyle("geolonia/basic-v2", { lang: "ja", apiKey: "YOUR-API-KEY" });
292
+ * // => "https://cdn.geolonia.com/style/geolonia/basic-v2/ja.json"
293
+ *
294
+ * // 空文字を渡すとデフォルトスタイルを返す
295
+ * getStyle("", { apiKey: "YOUR-API-KEY" });
296
+ * // => "https://cdn.geolonia.com/style/geolonia/basic-v2/en.json"
297
+ *
298
+ * // URL はそのまま解決する
299
+ * getStyle("https://example.com/style.json", {});
300
+ * // => "https://example.com/style.json"
301
+ * ```
99
302
  */
100
303
  declare function getStyle(style: string, options: {
101
304
  lang?: string;
102
305
  apiKey?: string;
103
306
  }): string;
104
307
  /**
105
- * Detect browser language.
308
+ * ブラウザの言語設定を検出して `"ja"` または `"en"` を返します。
309
+ *
310
+ * `navigator.languages[0]`、なければ `navigator.language` を小文字化して判定します。
311
+ * 値が `"ja"` または `"ja-jp"` の場合は `"ja"`、それ以外は `"en"` を返します。
312
+ * `navigator` が存在しない環境では `"en"` を返します。
313
+ *
314
+ * @returns 検出された言語。日本語なら `"ja"`、それ以外は `"en"`。
106
315
  */
107
316
  declare function getLang(): "ja" | "en";
108
317
 
109
318
  /**
110
- * Geolonia Map - extends MapLibre GL Map with Geolonia-specific features.
319
+ * MapLibre GL JS の `Map` を拡張し、Geolonia 固有の機能を追加した地図クラスです。
320
+ *
321
+ * API キーによる認証、Geolonia のスタイルやタイルへの接続、PMTiles プロトコルの登録、
322
+ * デフォルトマーカーや各種コントロール、SimpleStyle による GeoJSON 表示、
323
+ * ジェスチャ操作、3D 表示などを、コンストラクタに渡す {@link GeoloniaMapOptions}
324
+ * だけで有効にできます。
111
325
  *
112
- * Accepts a {@link GeoloniaMapOptions} object, or — for backward compatibility
113
- * with the old embed API — a CSS selector string or an HTMLElement, in which
114
- * case the container's `data-*` attributes are read into options.
326
+ * コンストラクタには {@link GeoloniaMapOptions} オブジェクトを渡します。
327
+ * ただし旧 embed API との後方互換のため、CSS セレクタ文字列や `HTMLElement`
328
+ * を直接渡すこともできます。その場合はコンテナ要素の `data-*` 属性が
329
+ * オプションとして読み込まれます。
330
+ *
331
+ * 同一のコンテナ要素に対して二重にインスタンスを生成しようとした場合は、
332
+ * 新たに生成せず、既存のインスタンスをそのまま返します(シングルトン)。
333
+ *
334
+ * `Map` を継承しているため、`addLayer`、`addSource`、`on`、`getZoom` など
335
+ * MapLibre GL JS の API はすべてそのまま利用できます。
336
+ *
337
+ * @example
338
+ * ```typescript
339
+ * const map = new GeoloniaMap({
340
+ * container: "#map",
341
+ * apiKey: "YOUR-API-KEY",
342
+ * style: "geolonia/basic-v2",
343
+ * center: [139.7671, 35.6812],
344
+ * zoom: 14,
345
+ * });
346
+ *
347
+ * map.on("load", () => {
348
+ * console.log("地図の読み込みが完了しました");
349
+ * });
350
+ * ```
351
+ *
352
+ * @example
353
+ * 後方互換の書き方として、コンテナのセレクタ文字列だけを渡すこともできます。
354
+ * この場合は `data-*` 属性から設定を読み込みます。
355
+ * ```typescript
356
+ * // <div id="map" data-zoom="14" data-center="139.7671, 35.6812"></div>
357
+ * const map = new GeoloniaMap("#map");
358
+ * ```
115
359
  */
116
360
  declare class GeoloniaMap extends maplibregl.Map {
117
361
  private geoloniaSourcesUrl;
118
362
  private __styleExtensionLoadRequired;
363
+ /**
364
+ * 地図を生成します。
365
+ *
366
+ * `apiKey` や `stage` が指定されていればキーリングに設定し、スタイル
367
+ * (既定は `"geolonia/basic-v2"`)を実際の style.json の URL に解決してから
368
+ * MapLibre GL JS の `Map` を初期化します。あわせて Geolonia のロゴ、出典表示、
369
+ * ナビゲーションなどのコントロールを追加し、読み込み完了後にはローディング表示の
370
+ * 除去、デフォルトマーカーの配置、ジェスチャ操作やスタイル拡張の適用を行います。
371
+ *
372
+ * `arg` にコンテナを直接指定する後方互換の形式では、そのコンテナの `data-*`
373
+ * 属性から設定を読み込みます。指定したコンテナに既に地図が生成済みの場合は、
374
+ * 新規生成せず既存のインスタンスを返します。
375
+ *
376
+ * @param arg 地図の設定です。{@link GeoloniaMapOptions} オブジェクトのほか、
377
+ * 後方互換としてコンテナを指す CSS セレクタ文字列や `HTMLElement` も指定できます。
378
+ * @throws コンテナ要素が見つからない場合に `Error` を投げます。
379
+ * @throws Geolonia のスタイルを API キーなしで使おうとした場合に `Error` を投げます。
380
+ * @throws MapLibre GL JS の `Map` の初期化に失敗した場合、コンテナにエラー表示を
381
+ * 行ったうえで、その例外を再スローします。
382
+ *
383
+ * @example
384
+ * ```typescript
385
+ * const map = new GeoloniaMap({
386
+ * container: "#map",
387
+ * apiKey: "YOUR-API-KEY",
388
+ * center: [139.7671, 35.6812],
389
+ * zoom: 14,
390
+ * });
391
+ * ```
392
+ */
119
393
  constructor(arg: string | HTMLElement | GeoloniaMapOptions);
394
+ /**
395
+ * 地図のスタイルを差し替えます。
396
+ *
397
+ * `style` が文字列の場合は、Geolonia のスタイル論理名(`"geolonia/basic-v2"`
398
+ * など)、style.json の URL、相対パスのいずれかとして解釈し、実際の URL に
399
+ * 解決してから適用します。解決の際の言語はブラウザ言語に従い、API キーは
400
+ * キーリングに設定済みの値を使います。`StyleSpecification` オブジェクトを
401
+ * 直接渡した場合はそのまま適用します。
402
+ *
403
+ * @param style 新しいスタイルです。スタイル論理名や URL などの文字列、または
404
+ * `StyleSpecification` オブジェクトを指定します。
405
+ * @param options MapLibre GL JS に渡すスタイル差し替えオプションです。
406
+ * 既定は空のオブジェクトです。
407
+ * @returns メソッドチェーンのために自身を返します。
408
+ * @throws Geolonia のスタイルを API キーなしで使おうとした場合に `Error` を投げます。
409
+ *
410
+ * @example
411
+ * ```typescript
412
+ * const map = new GeoloniaMap({ container: "#map", apiKey: "YOUR-API-KEY" });
413
+ * map.setStyle("geolonia/gsi");
414
+ * ```
415
+ */
120
416
  setStyle(style: string | StyleSpecification, options?: StyleSwapOptions & StyleOptions): this;
417
+ /**
418
+ * 地図を破棄し、関連するリソースやイベントリスナーを解放します。
419
+ *
420
+ * MapLibre GL JS の破棄処理に加えて、コンテナ要素に保持している地図インスタンスへの
421
+ * 参照(`geoloniaMap`)も削除します。これにより、同じコンテナで再度
422
+ * {@link GeoloniaMap} を生成した際に、破棄済みのインスタンスが返されることを防ぎます。
423
+ *
424
+ * @example
425
+ * ```typescript
426
+ * const map = new GeoloniaMap({ container: "#map", apiKey: "YOUR-API-KEY" });
427
+ * // 不要になったら破棄します
428
+ * map.remove();
429
+ * ```
430
+ */
121
431
  remove(): void;
432
+ /**
433
+ * 画像を読み込み、結果をコールバックで受け取ります(後方互換のコールバック形式)。
434
+ *
435
+ * 読み込みに成功すると `callback(null, image, expiry)`、失敗すると
436
+ * `callback(error)` の形で呼び出されます。
437
+ *
438
+ * @param url 読み込む画像の URL です。
439
+ * @param callback 読み込み結果を受け取るコールバックです。
440
+ */
122
441
  loadImage(url: string, callback: GetImageCallback): void;
442
+ /**
443
+ * 画像を読み込み、`Promise` で結果を受け取ります。
444
+ *
445
+ * @param url 読み込む画像の URL です。
446
+ * @returns 読み込んだ画像を含むレスポンスに解決される `Promise` を返します。
447
+ */
123
448
  loadImage(url: string): Promise<GetResourceResponse<HTMLImageElement | ImageBitmap>>;
124
449
  }
125
450
 
451
+ /**
452
+ * 地図上に配置する Geolonia デフォルトデザインの点マーカーです。
453
+ *
454
+ * MapLibre GL JS の `maplibregl.Marker` を継承しており、`setLngLat` や `addTo`、
455
+ * `remove` などのメソッドはそのまま利用できます。オプションの `element` を
456
+ * 指定しなかった場合は、Geolonia デフォルトの水滴形 SVG マーカーを自動生成して
457
+ * 表示します。既定のマーカー色は `#E4402F` で、`color` オプションを指定すると
458
+ * その色でマーカーを描画します。このとき水滴の右半分には、指定色を暗くした色が
459
+ * 自動的に適用されます。また、`element` を指定しなかった場合の `offset` の既定値は
460
+ * `[0, -15]` であり、水滴の先端が指定した座標を指すように配置されます。
461
+ *
462
+ * `element` を指定した場合は、上記のデフォルト生成、色の適用、`offset` の既定値の
463
+ * いずれも適用されず、`maplibregl.Marker` の挙動がそのまま使われます。
464
+ *
465
+ * @example
466
+ * ```typescript
467
+ * const map = new GeoloniaMap({
468
+ * container: "#map",
469
+ * apiKey: "YOUR-API-KEY",
470
+ * center: [139.7671, 35.6812],
471
+ * zoom: 14,
472
+ * });
473
+ *
474
+ * new GeoloniaMarker({ color: "#4A90D9" })
475
+ * .setLngLat([139.7671, 35.6812])
476
+ * .addTo(map);
477
+ * ```
478
+ */
126
479
  declare class GeoloniaMarker extends maplibregl.Marker {
480
+ /**
481
+ * Geolonia マーカーを作成します。
482
+ *
483
+ * `options.element` が指定されていない場合は、Geolonia デフォルトの SVG マーカー
484
+ * 要素を生成して `options.element` に設定し、`options.color`(未指定時は `#E4402F`)で
485
+ * マーカーの色を適用したうえで、`options.offset` を `[0, -15]` に設定します。
486
+ * `options.element` が指定されている場合は、これらの処理を行わず指定された要素を
487
+ * そのまま使用します。
488
+ *
489
+ * @param options `maplibregl.Marker` の `MarkerOptions` です。`element` を省略すると
490
+ * Geolonia デフォルトのマーカーが生成され、`color` でその色を指定できます。
491
+ * 省略した場合は空のオブジェクトが使われます。
492
+ */
127
493
  constructor(options?: MarkerOptions);
128
494
  }
129
495
 
496
+ /**
497
+ * API キー、ステージ、現在のスタイルが Geolonia スタイルかどうかを保持するクラスです。
498
+ *
499
+ * これらの値は SDK 全体で共有され、地図タイルやスタイルの取得時に参照されます。
500
+ * 通常は `GeoloniaMap` の生成時に自動的に設定されるため、利用者が直接操作する必要はありません。
501
+ * ただし `@geolonia/embed/core` のように地図インスタンスを生成せずに SDK の機能を利用する場合など、
502
+ * 手動で API キーやステージを設定したいときに使用します。
503
+ *
504
+ * このクラスのインスタンスは {@link keyring} としてシングルトンで公開されます。
505
+ *
506
+ * @example
507
+ * ```typescript
508
+ * keyring.setApiKey("YOUR-API-KEY");
509
+ * ```
510
+ */
130
511
  declare class Keyring {
131
512
  #private;
513
+ /**
514
+ * 現在設定されている API キーを返します。
515
+ *
516
+ * 未設定の場合は空文字列を返します。
517
+ *
518
+ * @returns API キーの文字列を返します。
519
+ */
132
520
  get apiKey(): string;
521
+ /**
522
+ * 現在設定されているステージを返します。
523
+ *
524
+ * 初期値は `"dev"` です。
525
+ *
526
+ * @returns ステージを表す文字列を返します。
527
+ */
133
528
  get stage(): string;
529
+ /**
530
+ * 現在のスタイルが Geolonia スタイル(API キーが必要なスタイル)かどうかを返します。
531
+ *
532
+ * @returns Geolonia スタイルの場合は `true`、それ以外の場合は `false` を返します。
533
+ */
134
534
  get isGeoloniaStyle(): boolean;
535
+ /**
536
+ * 現在のスタイルが Geolonia スタイルかどうかを設定します。
537
+ *
538
+ * @param value Geolonia スタイルとして扱う場合は `true`、それ以外の場合は `false` を指定します。
539
+ */
135
540
  set isGeoloniaStyle(value: boolean);
541
+ /**
542
+ * API キーを設定します。
543
+ *
544
+ * @param key 設定する API キーの文字列を指定します。
545
+ */
136
546
  setApiKey(key: string): void;
547
+ /**
548
+ * ステージを設定します。
549
+ *
550
+ * @param stage 設定するステージの文字列を指定します。
551
+ */
137
552
  setStage(stage: string): void;
553
+ /**
554
+ * API キー、ステージ、Geolonia スタイル判定をすべて初期状態に戻します。
555
+ *
556
+ * API キーは空文字列、ステージは `"dev"`、Geolonia スタイル判定は `true` にリセットされます。
557
+ */
138
558
  reset(): void;
139
559
  /**
140
- * Check if the given style is a Geolonia style (requires API key)
560
+ * 与えられたスタイルが Geolonia スタイル(API キーが必要なスタイル)かどうかを判定します。
561
+ *
562
+ * 判定は次のロジックで行われます。
563
+ *
564
+ * - 空文字列(未指定)の場合は `true` を返します。
565
+ * - `https://cdn.geolonia.com/style/` または `https://api.geolonia.com/` で始まる URL の場合は `true` を返します。
566
+ * - 上記以外で `http://` または `https://` で始まる外部 URL の場合は `false` を返します。
567
+ * - `geolonia://` で始まる場合は Geolonia 独自プロトコルのため `true` を返します。
568
+ * - それ以外のプロトコル(`xxx://` 形式)で始まる場合は `false` を返します。
569
+ * - `.json` で終わる場合は `false` を返します。
570
+ * - 上記のいずれにも該当しない場合は、`geolonia/basic` のような Geolonia の論理名とみなして `true` を返します。
571
+ *
572
+ * @param style 判定対象のスタイル(URL、プロトコル付き文字列、または論理名)を指定します。
573
+ * @returns Geolonia スタイルの場合は `true`、それ以外の場合は `false` を返します。
141
574
  */
142
575
  isGeoloniaStyleCheck(style: string): boolean;
143
576
  }
577
+ /**
578
+ * {@link Keyring} のシングルトンインスタンスです。
579
+ *
580
+ * SDK 全体で共有される API キー、ステージ、Geolonia スタイル判定を保持します。
581
+ * 通常は `GeoloniaMap` の生成時に自動設定されますが、手動で設定することもできます。
582
+ *
583
+ * @example
584
+ * ```typescript
585
+ * keyring.setApiKey("YOUR-API-KEY");
586
+ * ```
587
+ */
144
588
  declare const keyring: Keyring;
145
589
 
146
590
  type FeatureCollection = GeoJSON.FeatureCollection;
591
+ /**
592
+ * simplestyle 仕様の GeoJSON を地図に表示するヘルパークラスです。
593
+ *
594
+ * ポリゴン、ライン、ポイントの各ジオメトリをそれぞれに適したレイヤーで描画し、
595
+ * `fill`、`stroke`、`marker-color`、`marker-size`、`title`、`description` などの
596
+ * simplestyle プロパティを解釈してスタイルへ反映します。ポイントについてはクラスタリング表示に対応します。
597
+ * ポリゴン、ライン、ポイントの各ジオメトリレイヤー上でクリックすると、`description` プロパティを持つ
598
+ * フィーチャーについてポップアップを表示します(ラベル用のシンボルレイヤーにはポップアップを登録しません)。
599
+ *
600
+ * GeoJSON は {@link FeatureCollection} を直接渡すほか、GeoJSON を返す URL 文字列を渡して非同期に取得させることもできます。
601
+ * `addTo`、`updateData`、`fitBounds`、`remove` は `this` を返すため、メソッドチェーンで記述できます。
602
+ *
603
+ * @example
604
+ * ```typescript
605
+ * new SimpleStyle(geojson).addTo(map);
606
+ * ```
607
+ */
147
608
  declare class SimpleStyle {
148
609
  _loadingPromise: Promise<unknown> | undefined;
149
610
  private callFitBounds;
@@ -151,57 +612,233 @@ declare class SimpleStyle {
151
612
  private map;
152
613
  private options;
153
614
  private _eventHandlers;
615
+ /**
616
+ * SimpleStyle を作成します。
617
+ *
618
+ * `geojson` に URL 文字列を渡した場合は、その URL から GeoJSON を非同期に取得します。
619
+ * 取得の完了は `_loadingPromise` で待つことができます。
620
+ *
621
+ * @param geojson 表示する GeoJSON です。{@link FeatureCollection} または GeoJSON を返す URL 文字列を指定します。
622
+ * @param options 表示オプションです。指定した項目のみが既定値を上書きします。既定値は
623
+ * `id: "geolonia-simple-style"`、`cluster: true`、`heatmap: false`、`clusterColor: "#ff0000"` です。
624
+ */
154
625
  constructor(geojson: string | FeatureCollection, options?: Record<string, unknown>);
626
+ /**
627
+ * 表示中のデータを新しい GeoJSON で差し替えます。
628
+ *
629
+ * フィーチャーをポイントとそれ以外(ポリゴン、ライン)に振り分け、
630
+ * それぞれ対応するソースの内容を更新します。レイヤー自体の追加は行わないため、
631
+ * あらかじめ {@link SimpleStyle.addTo | addTo} で地図に追加されている必要があります。
632
+ *
633
+ * @param geojson 差し替える {@link FeatureCollection} です。
634
+ * @returns メソッドチェーンのための `this` を返します。
635
+ */
155
636
  updateData(geojson: FeatureCollection): this;
637
+ /**
638
+ * 地図にソースとレイヤーを追加して GeoJSON を表示します。
639
+ *
640
+ * ポリゴンとラインのソース、ポイント用のソース(クラスタリング設定付き)を追加し、
641
+ * ポリゴンとラインのラベル用シンボルレイヤーを配置したうえで、
642
+ * {@link SimpleStyle.setPolygonGeometries | setPolygonGeometries}、
643
+ * {@link SimpleStyle.setLineGeometries | setLineGeometries}、
644
+ * {@link SimpleStyle.setPointGeometries | setPointGeometries}、
645
+ * {@link SimpleStyle.setCluster | setCluster} を呼び出して各ジオメトリのレイヤーを設定します。
646
+ *
647
+ * @param map 表示先の地図です。
648
+ * @returns メソッドチェーンのための `this` を返します。
649
+ *
650
+ * @example
651
+ * ```typescript
652
+ * new SimpleStyle(geojson).addTo(map);
653
+ * ```
654
+ */
156
655
  addTo(map: Map): this;
656
+ /**
657
+ * データ全体の範囲に地図をフィットさせます。
658
+ *
659
+ * 現在の GeoJSON のフィーチャーからバウンディングボックスを算出し、そこへ地図を移動します。
660
+ * フィーチャーが存在しない場合は何もしません。データを URL から取得中に呼び出した場合は、
661
+ * フィット要求を保持しておき、取得完了後に自動でフィットします。
662
+ *
663
+ * @param options `map.fitBounds` に渡すオプションです。既定値は `duration: 3000`、`padding: 30` で、
664
+ * 指定した項目のみがこれらを上書きします。
665
+ * @returns メソッドチェーンのための `this` を返します。
666
+ */
157
667
  fitBounds(options?: {}): this;
158
668
  /**
159
- * Set polygon geometries.
669
+ * ポリゴンの塗りレイヤーを設定します。
670
+ *
671
+ * `$type` が `Polygon` のフィーチャーを対象に塗りレイヤーを追加し、
672
+ * `fill`、`fill-opacity`、`stroke`(輪郭色)の各 simplestyle プロパティを反映します。
673
+ * あわせて {@link SimpleStyle.setPopup | setPopup} でこのレイヤーにポップアップを設定します。
674
+ * 通常は {@link SimpleStyle.addTo | addTo} から呼び出されます。
160
675
  */
161
676
  setPolygonGeometries(): void;
162
677
  /**
163
- * Set line geometries.
678
+ * ラインのレイヤーを設定します。
679
+ *
680
+ * `$type` が `LineString` のフィーチャーを対象にラインレイヤーを追加し、
681
+ * `stroke-width`(線幅)、`stroke`(線色)、`stroke-opacity`(不透明度)の各 simplestyle プロパティを反映します。
682
+ * 線端と結合は丸めて描画します。あわせて {@link SimpleStyle.setPopup | setPopup} でこのレイヤーにポップアップを設定します。
683
+ * 通常は {@link SimpleStyle.addTo | addTo} から呼び出されます。
164
684
  */
165
685
  setLineGeometries(): void;
166
686
  /**
167
- * Setup point geometries.
687
+ * ポイントのレイヤーを設定します。
688
+ *
689
+ * クラスターに属さないポイントを対象に、2 種類のレイヤーを追加します。
690
+ * `marker-symbol` を持たないポイントには円レイヤーを、
691
+ * `marker-symbol` を持つポイントにはアイコンとラベルのシンボルレイヤーを使います。
692
+ * `marker-size`(`small`、`large`、その他)に応じて円の半径やラベルのオフセットを変え、
693
+ * `marker-color`、`stroke`、`title`、`text-color` などの simplestyle プロパティを反映します。
694
+ * あわせて円レイヤーとシンボルレイヤーの双方に {@link SimpleStyle.setPopup | setPopup} でポップアップを設定します。
695
+ * 通常は {@link SimpleStyle.addTo | addTo} から呼び出されます。
168
696
  */
169
697
  setPointGeometries(): void;
698
+ /**
699
+ * 指定したレイヤーにクリックでポップアップを表示するイベントハンドラーを設定します。
700
+ *
701
+ * クリックされたフィーチャーが `description` プロパティを持つ場合、その中心座標に
702
+ * サニタイズ済みの HTML を表示するポップアップを追加します。あわせてホバー時に
703
+ * カーソルを変えるハンドラーも設定します。登録したハンドラーは `_eventHandlers` に記録され、
704
+ * {@link SimpleStyle.remove | remove} でまとめて解除されます。
705
+ *
706
+ * @param map ポップアップを表示する地図です。
707
+ * @param source ハンドラーを設定する対象のレイヤー ID です。
708
+ */
170
709
  setPopup(map: Map, source: string): Promise<void>;
171
710
  /**
172
- * Setup cluster markers
711
+ * クラスタリング用のレイヤーを設定します。
712
+ *
713
+ * `point_count` を持つクラスターを対象に、クラスターを表す円レイヤーと、
714
+ * 件数(`point_count_abbreviated`)を表示するラベルのシンボルレイヤーを追加します。
715
+ * 円の色は `clusterColor` オプションを使います。クラスターをクリックすると、
716
+ * そのクラスターが展開するズームレベルまで地図を移動します。あわせてホバー時に
717
+ * カーソルを変えるハンドラーも設定します。登録したハンドラーは `_eventHandlers` に記録され、
718
+ * {@link SimpleStyle.remove | remove} でまとめて解除されます。通常は
719
+ * {@link SimpleStyle.addTo | addTo} から呼び出されます。
173
720
  */
174
721
  setCluster(): void;
722
+ /**
723
+ * 追加したソース、レイヤー、イベントハンドラーを地図から除去します。
724
+ *
725
+ * {@link SimpleStyle.setPopup | setPopup} や {@link SimpleStyle.setCluster | setCluster}
726
+ * で登録したイベントハンドラーをすべて解除し、ポリゴン、ライン、ポイント、クラスターの各レイヤーと、
727
+ * それらのソースを削除します。カーソルのスタイルも元に戻します。まだ地図に追加されていない場合は何もしません。
728
+ *
729
+ * @returns メソッドチェーンのための `this` を返します。
730
+ */
175
731
  remove(): this;
732
+ /**
733
+ * 内部で保持する GeoJSON を設定します。
734
+ *
735
+ * `geojson` が URL 文字列の場合は、いったん空のデータを設定したうえで、その URL から GeoJSON を
736
+ * 非同期に取得します。取得中の Promise は `_loadingPromise` に保持され、取得完了後に
737
+ * {@link SimpleStyle.updateData | updateData} で表示を更新します。フィット要求が保留されていれば
738
+ * あわせてフィットします。応答が 2xx 以外の場合は空のデータとして扱い、通信や JSON の解析で
739
+ * 例外が発生した場合はエラーをコンソールに出力します。
740
+ * `geojson` が {@link FeatureCollection} の場合は、そのまま内部データとして設定します。
741
+ *
742
+ * @param geojson 設定する {@link FeatureCollection} または GeoJSON を返す URL 文字列です。
743
+ */
176
744
  setGeoJSON(geojson: string | FeatureCollection): void;
177
745
  }
178
746
 
747
+ /**
748
+ * ベクトルタイル(tiles.json / TileJSON)を simplestyle の規約に沿って地図に表示するヘルパーです。
749
+ *
750
+ * GeoJSON を対象とする SimpleStyle のベクトルタイル版に相当します。TileJSON の URL を渡すと、
751
+ * `g-simplestyle-v1` という source-layer に含まれるポリゴン、ライン、ポイントの各ジオメトリを、
752
+ * フィーチャーが持つ simplestyle プロパティ(`fill`、`stroke`、`marker-color`、`marker-size`、`title` など)
753
+ * に従って描画します。フィーチャーが該当プロパティを持たない場合は、既定の色やサイズが適用されます。
754
+ * ポリゴン、ライン、ポイントの各ジオメトリレイヤー上でクリックすると、`description` プロパティを持つ
755
+ * フィーチャーについて、その内容を HTML としてポップアップ表示します(ポリゴンやラインのラベル用
756
+ * シンボルレイヤーにはポップアップを登録しません)。
757
+ *
758
+ * @example
759
+ * ```typescript
760
+ * new SimpleStyleVector(url).addTo(map);
761
+ * ```
762
+ */
179
763
  declare class SimpleStyleVector {
180
764
  private url;
181
765
  private sourceName;
766
+ /**
767
+ * @param url 表示するベクトルタイルソースの TileJSON(tiles.json)URL です。
768
+ */
182
769
  constructor(url: string);
770
+ /**
771
+ * 地図にベクトルタイルソースと各レイヤーを追加し、simplestyle の規約に沿って表示します。
772
+ *
773
+ * ソースを追加したうえで、ポリゴン(塗り潰しとラベル)、ライン(線とラベル)、
774
+ * ポイント(円、アイコン、ラベル)の各レイヤーを設定します。あわせて、ポリゴンの塗り潰し、
775
+ * ラインの線、ポイントの円とアイコンの各レイヤーにクリック時のポップアップを登録します
776
+ * (ポリゴンやラインのラベル用シンボルレイヤーには登録しません)。
777
+ *
778
+ * 地図コンテナの `data-lng` および `data-lat` 属性がいずれも指定されていない場合は、
779
+ * ソースの読み込み完了を待って、そのソースの `bounds` に一度だけ地図の表示範囲を合わせます
780
+ * (`padding` は 30、アニメーションなし)。
781
+ *
782
+ * @param map レイヤーを追加する対象の地図インスタンスです。
783
+ *
784
+ * @example
785
+ * ```typescript
786
+ * new SimpleStyleVector(url).addTo(map);
787
+ * ```
788
+ */
183
789
  addTo(map: Map): void;
184
790
  /**
185
- * Set polygon geometries.
791
+ * ポリゴンジオメトリ用のレイヤーを設定します。
792
+ *
793
+ * `$type` が `Polygon` のフィーチャーに対して塗り潰しレイヤー(`fill` タイプ)を追加します。
794
+ * 塗り色はフィーチャーの `fill` プロパティ、不透明度は `fill-opacity`、
795
+ * 外周線の色は `stroke` プロパティを用い、いずれも未指定の場合は既定値を適用します。
796
+ * あわせて、このポリゴンレイヤーにクリック時のポップアップを登録します。
186
797
  *
187
- * @param map
798
+ * @param map レイヤーを追加する対象の地図インスタンスです。
188
799
  */
189
800
  setPolygonGeometries(map: Map): void;
190
801
  /**
191
- * Set line geometries.
802
+ * ラインジオメトリ用のレイヤーを設定します。
192
803
  *
193
- * @param map
804
+ * `$type` が `LineString` のフィーチャーに対して線レイヤー(`line` タイプ)を追加します。
805
+ * 線幅はフィーチャーの `stroke-width` プロパティ、線色は `stroke`、
806
+ * 不透明度は `stroke-opacity` を用い、いずれも未指定の場合は既定値を適用します。
807
+ * 線の端点と結合部はいずれも丸め(`round`)で描画します。
808
+ * あわせて、このラインレイヤーにクリック時のポップアップを登録します。
809
+ *
810
+ * @param map レイヤーを追加する対象の地図インスタンスです。
194
811
  */
195
812
  setLineGeometries(map: Map): void;
196
813
  /**
197
- * Setup point geometries.
814
+ * ポイントジオメトリ用のレイヤーを設定します。
815
+ *
816
+ * 2 つのレイヤーを追加します。1 つは `marker-symbol` を持たないポイント向けの円レイヤー
817
+ * (`circle` タイプ)で、半径はフィーチャーの `marker-size`(`small` は 7、`large` は 13、
818
+ * それ以外は 9)に応じて変化し、色は `marker-color`、外周線は `stroke` 系プロパティを用います。
819
+ * もう 1 つはすべてのポイント向けのシンボルレイヤー(`symbol` タイプ)で、`marker-symbol` を
820
+ * アイコン画像として、`title` をラベルとして表示します。ラベルの位置は `marker-size` に応じて調整します。
821
+ * あわせて、円レイヤーとシンボルレイヤーの両方にクリック時のポップアップを登録します。
198
822
  *
199
- * @param map
823
+ * @param map レイヤーを追加する対象の地図インスタンスです。
200
824
  */
201
825
  setPointGeometries(map: Map): void;
826
+ /**
827
+ * 指定したレイヤーにクリック時のポップアップ表示を設定します。
828
+ *
829
+ * 対象レイヤーのフィーチャーがクリックされると、そのフィーチャーの中心座標
830
+ * (`@turf/center` で算出)にポップアップを表示します。ポップアップの内容は、
831
+ * フィーチャーの `description` プロパティをサニタイズした HTML です。`description` を
832
+ * 持たないフィーチャーではポップアップを表示しません。あわせて、`description` を持つ
833
+ * フィーチャーにマウスが乗ったときはカーソルをポインターに変更し、離れたときに元へ戻します。
834
+ *
835
+ * @param map イベントを登録する対象の地図インスタンスです。
836
+ * @param source ポップアップを設定する対象のレイヤー ID です。
837
+ * @returns イベントリスナーの登録が完了すると解決する Promise です。
838
+ */
202
839
  setPopup(map: Map, source: string): Promise<void>;
203
840
  }
204
841
 
205
- declare const VERSION = "0.1.0";
842
+ declare const VERSION: string;
206
843
 
207
844
  export { CustomAttributionControl, GeoloniaControl, GeoloniaMap, type GeoloniaMapOptions, GeoloniaMarker, SimpleStyle, SimpleStyleVector, VERSION as coreVersion, getLang, getStyle, isGeoloniaTilesHost, keyring };