@arcgis/common-components 6.0.0-next.19 → 6.0.0-next.20

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.
@@ -0,0 +1,437 @@
1
+ /// <reference path="../../index.d.ts" />
2
+ import type Layer from "@arcgis/core/layers/Layer.js";
3
+ import type Field from "@arcgis/core/layers/support/Field.js";
4
+ import type SubtypeSublayer from "@arcgis/core/layers/support/SubtypeSublayer.js";
5
+ import type { PublicLitElement as LitElement } from "@arcgis/lumina";
6
+ import type { T9nMeta } from "@arcgis/lumina/controllers";
7
+ import type { Icon as Icon } from "@esri/calcite-components/components/calcite-icon";
8
+
9
+ declare module "@arcgis/lumina" {
10
+ export interface DeclareCssProperties {
11
+ /**
12
+ * Specifies the text color of layer and field names.
13
+ *
14
+ * @internal
15
+ */
16
+ "--arcgis-layer-replace-color": "*";
17
+ /**
18
+ * Specifies the spacing between the layer selector and field mappings, and between field rows.
19
+ *
20
+ * @internal
21
+ */
22
+ "--arcgis-layer-replace-content-gap": "*";
23
+ /**
24
+ * Specifies the spacing between source and replacement columns.
25
+ *
26
+ * @internal
27
+ */
28
+ "--arcgis-layer-replace-row-gap": "*";
29
+ /**
30
+ * Specifies the spacing between icons and names, and between stacked labels and controls.
31
+ *
32
+ * @internal
33
+ */
34
+ "--arcgis-layer-replace-name-gap": "*";
35
+ /**
36
+ * Specifies the minimum width of the replacement column in the two-column layout.
37
+ *
38
+ * @internal
39
+ */
40
+ "--arcgis-layer-replace-min-column-width": "*";
41
+ }
42
+ }
43
+
44
+ /**
45
+ * Lets users choose a replacement layer and map its fields to source fields.
46
+ * Load layers before assigning them. The component does not load layers or apply replacements to your map.
47
+ * Read `mapping` or listen to `arcgisChange`, validate the selections, and apply them in your application.
48
+ *
49
+ * Use `layer-and-fields` mode to choose from `replacementCandidates`, or `fields-only` mode with a replacement
50
+ * chosen by your application. Fields are matched automatically; filters limit choices and `fieldMatcher`
51
+ * overrides the matching rules.
52
+ *
53
+ * @slot
54
+ * - Default slot for adding components to layer-replace, after the layer selector and before the field mappings.
55
+ * Slotted controls are shown only when a source is set and, in `fields-only` mode, a replacement is also set.
56
+ * @internal
57
+ */
58
+ export abstract class ArcgisLayerReplace extends LitElement {
59
+ /**
60
+ * Extra source fields that users need to map. For example, your application might still refer to a field that
61
+ * no longer exists in the source layer. Adding it here lets the user choose a replacement for it without
62
+ * changing the source layer itself.
63
+ *
64
+ * These fields appear after the layer's fields, in array order. A field is skipped if its name already appears
65
+ * in the layer or earlier in this array, ignoring differences in letter case.
66
+ * Setting a new array reruns matching when both layers are set, clearing previous selections.
67
+ *
68
+ * `source` must have a `fields` property to use these extra fields. `sourceFieldFilter` checks them just like
69
+ * the layer's own fields, before they are shown or passed to `fieldMatcher`.
70
+ */
71
+ accessor additionalSourceFields: readonly Field[] | undefined;
72
+ /**
73
+ * Allows multiple source fields to use the same replacement field. Defaults to `false`.
74
+ *
75
+ * When duplicates are not allowed, selecting a replacement field that is already used in another row clears
76
+ * the selection in that other row. Field names that differ only in letter case count as the same replacement field.
77
+ *
78
+ * Applies to manual selections and both matchers. For custom results with duplicates disabled, the first
79
+ * source field wins and the others remain unmapped.
80
+ *
81
+ * Setting this property to `false` also removes duplicates from the current selections, keeping the first one
82
+ * in source-field order. Changing it cancels pending matching but does not start a new run.
83
+ * Call `matchFields()` to match using the new setting.
84
+ *
85
+ * @default false
86
+ */
87
+ accessor allowDuplicateReplacementFields: boolean;
88
+ /**
89
+ * Overrides automatic matching. Set to `undefined` to use the default matcher.
90
+ *
91
+ * The default matcher favors equal names, then equal names or aliases, ignoring case. It also matches
92
+ * object-ID and GlobalID fields by type, and similar names or aliases. Object-ID and GlobalID source fields
93
+ * match only replacements of the same type; other source fields, including GUIDs, have no type restriction.
94
+ * Use `replacementFieldFilter` to enforce compatibility.
95
+ * Stronger matches take priority; ties use source order, then replacement-field order.
96
+ *
97
+ * The callback receives filtered choices and an abort signal. Return all matches, directly or in a promise,
98
+ * using field names, not aliases. Names resolve exactly first, then by a unique case-insensitive match.
99
+ * Unresolvable matches are ignored, and `allowDuplicateReplacementFields` applies to the result.
100
+ *
101
+ * With both layers set, matching runs when either layer, either field filter, `additionalSourceFields`, or this
102
+ * callback changes. Each run clears previous selections; omitted source fields remain unmapped.
103
+ * Call `matchFields()` to rerun after changes to data captured by a callback or to a layer's fields.
104
+ */
105
+ accessor fieldMatcher: FieldMatcher | undefined;
106
+ /**
107
+ * Customizes how fields are displayed.
108
+ * Receives the displayed field and its source or replacement layer, including extra fields supplied through
109
+ * `additionalSourceFields`. Return display options, or `undefined` to keep the default appearance.
110
+ * Translate group headings in your application.
111
+ *
112
+ * Replacement fields with the same heading appear together. When any fields are grouped, ungrouped fields
113
+ * appear first under the translated "Fields" heading. Source-field rows are not grouped.
114
+ *
115
+ * The component may call this callback again whenever it renders.
116
+ */
117
+ accessor getFieldDisplayInfo: FieldDisplayInfoCallback | undefined;
118
+ /**
119
+ * Customizes how the source layer and replacement choices are displayed.
120
+ * Return `undefined` to use the default icon, `{ icon: null }` to hide it, or an object such as `{ icon: "table" }`
121
+ * to show a different Calcite icon. The component may call this callback again whenever it renders.
122
+ * Called for `source` and `replacementCandidates` only in `layer-and-fields` mode.
123
+ */
124
+ accessor getLayerDisplayInfo: LayerDisplayInfoCallback | undefined;
125
+ /**
126
+ * The current layer and field selections, or `undefined` when no source is set.
127
+ * Selections may be incomplete, including while matching runs. Listen to `arcgisChange` for updates.
128
+ */
129
+ get mapping(): LayerReplacementMapping | undefined;
130
+ /**
131
+ * Overrides selected translated labels, prompts, and messages. Unspecified messages keep their translations.
132
+ * Keep placeholders such as `{field}`, `{layer}`, and `{count}` in messages that use them so the component
133
+ * can insert the names and counts. Set this property to `undefined` to restore all default messages.
134
+ */
135
+ accessor messageOverrides: {
136
+ fieldsCount?: string | undefined;
137
+ fields?: string | undefined;
138
+ fieldMappingFor?: string | undefined;
139
+ layerReplacement?: string | undefined;
140
+ noReplacementFields?: string | undefined;
141
+ noReplacementLayers?: string | undefined;
142
+ replacementField?: string | undefined;
143
+ replacementFieldFor?: string | undefined;
144
+ replacementLayer?: string | undefined;
145
+ selectField?: string | undefined;
146
+ selectLayer?: string | undefined;
147
+ selectLayerFirst?: string | undefined;
148
+ selectReplacementLayer?: string | undefined;
149
+ selectSourceLayer?: string | undefined;
150
+ sourceLayer?: string | undefined;
151
+ };
152
+ /** @internal */
153
+ protected messages: {
154
+ fieldsCount: string;
155
+ fields: string;
156
+ fieldMappingFor: string;
157
+ layerReplacement: string;
158
+ noReplacementFields: string;
159
+ noReplacementLayers: string;
160
+ replacementField: string;
161
+ replacementFieldFor: string;
162
+ replacementLayer: string;
163
+ selectField: string;
164
+ selectLayer: string;
165
+ selectLayerFirst: string;
166
+ selectReplacementLayer: string;
167
+ selectSourceLayer: string;
168
+ sourceLayer: string;
169
+ } & T9nMeta<{
170
+ fieldsCount: string;
171
+ fields: string;
172
+ fieldMappingFor: string;
173
+ layerReplacement: string;
174
+ noReplacementFields: string;
175
+ noReplacementLayers: string;
176
+ replacementField: string;
177
+ replacementFieldFor: string;
178
+ replacementLayer: string;
179
+ selectField: string;
180
+ selectLayer: string;
181
+ selectLayerFirst: string;
182
+ selectReplacementLayer: string;
183
+ selectSourceLayer: string;
184
+ sourceLayer: string;
185
+ }>;
186
+ /**
187
+ * Sets whether users choose a replacement layer as well as its field mappings, or just map the fields.
188
+ *
189
+ * - `layer-and-fields` (default): Shows the source layer, replacement selector, and field mappings.
190
+ * - `fields-only`: Hides the source layer and replacement selector. Your application must set `replacement`;
191
+ * until then, the component shows a prompt.
192
+ *
193
+ * In `layer-and-fields` mode, `replacement` must be an entry in `replacementCandidates`.
194
+ *
195
+ * @default "layer-and-fields"
196
+ */
197
+ accessor mode: "fields-only" | "layer-and-fields";
198
+ /**
199
+ * The loaded layer or sublayer to use in place of the source. Changing it reruns matching when a source is set.
200
+ * Clearing it clears all selected replacement fields.
201
+ *
202
+ * In `layer-and-fields` mode, users can choose it in the selector. It must be the same object as an entry in
203
+ * `replacementCandidates`, not just have the same ID; otherwise it is cleared.
204
+ * In `fields-only` mode, your application sets it and it need not appear in `replacementCandidates`.
205
+ */
206
+ accessor replacement: LayerOrSublayer | undefined;
207
+ /**
208
+ * The loaded layers or sublayers users can choose from, in the order shown in the selector.
209
+ * Set a new array when changing the choices so the component updates.
210
+ * Used only in `layer-and-fields` mode. Removing the selected replacement clears it and its field selections,
211
+ * but keeps the source-field rows. Ignored in `fields-only` mode.
212
+ */
213
+ accessor replacementCandidates: LayerOrSublayer[];
214
+ /**
215
+ * Filters replacement choices separately for each included source field. Return `false` to exclude a field
216
+ * from both the selector and automatic matching.
217
+ * Use this callback to enforce type compatibility, including for a custom `fieldMatcher`.
218
+ * Setting a new callback reruns matching when both layers are set, clearing previous selections.
219
+ *
220
+ * @example
221
+ * ```ts
222
+ * element.replacementFieldFilter = (field, _replacement, sourceField) => field.type === sourceField.type;
223
+ * ```
224
+ */
225
+ accessor replacementFieldFilter: ReplacementFieldFilter | undefined;
226
+ /**
227
+ * Shows aliases below source-field names and alongside replacement-field choices.
228
+ *
229
+ * @default false
230
+ */
231
+ accessor showFieldAliases: boolean;
232
+ /**
233
+ * The loaded layer or sublayer to replace. Its fields become mapping rows, subject to `sourceFieldFilter`
234
+ * and `additionalSourceFields`.
235
+ * Changing the source reruns matching when a replacement is set.
236
+ *
237
+ * @required
238
+ */
239
+ accessor source: LayerOrSublayer | undefined;
240
+ /**
241
+ * Filters fields from `source` and `additionalSourceFields`. Return `false` to omit a field from the rows,
242
+ * matcher input, and results.
243
+ * Setting a new callback reruns matching when both layers are set, clearing previous selections.
244
+ *
245
+ * @example
246
+ * ```ts
247
+ * element.sourceFieldFilter = (field) => field.type !== "oid";
248
+ * ```
249
+ */
250
+ accessor sourceFieldFilter: SourceFieldFilter | undefined;
251
+ /**
252
+ * Reruns matching with the current filters and duplicate policy, using `fieldMatcher` or the default matcher.
253
+ * With both layers set, clears all previous selections, including manual choices, before matching.
254
+ * Use after changing layer fields or data captured by a filter or matcher without assigning a new callback.
255
+ * Does nothing when `replacement` is unset.
256
+ *
257
+ * @returns A promise that settles when this run finishes, not necessarily when the latest run finishes.
258
+ * Rejects on filter or matcher errors. A canceled custom run can reject with an `AbortError`.
259
+ */
260
+ matchFields(): Promise<void>;
261
+ /**
262
+ * Fires when the source, replacement, or field selections change, including when a source is first assigned.
263
+ * `detail` contains the current mapping, or `null` when a previously set source is cleared.
264
+ *
265
+ * Matching may emit once after clearing selections and again after applying matches. Results can be incomplete;
266
+ * validate them before applying a replacement. Unchanged layer and field object references do not emit again.
267
+ */
268
+ readonly arcgisChange: import("@arcgis/lumina").TargetedEvent<this, LayerReplacementMapping | null>;
269
+ readonly "@eventTypes": {
270
+ arcgisChange: ArcgisLayerReplace["arcgisChange"]["detail"];
271
+ };
272
+ }
273
+
274
+ /**
275
+ * A layer (including a table) or subtype sublayer used as the source or replacement.
276
+ *
277
+ * @internal
278
+ */
279
+ export type LayerOrSublayer = Layer | SubtypeSublayer;
280
+
281
+ /**
282
+ * Current layer and field selections exposed by `mapping` and `arcgisChange`.
283
+ *
284
+ * @internal
285
+ */
286
+ export interface LayerReplacementMapping {
287
+ /** The layer or sublayer being replaced. This is the same object that was passed to the component. */
288
+ source: LayerOrSublayer;
289
+ /** The selected replacement layer or sublayer, or `undefined` if none is selected. */
290
+ replacement?: LayerOrSublayer;
291
+ /**
292
+ * One entry per source field that passes `sourceFieldFilter`, including unmapped fields.
293
+ * Preserves source-layer order, followed by `additionalSourceFields`.
294
+ */
295
+ fieldMappings: readonly FieldMapping[];
296
+ }
297
+
298
+ /**
299
+ * Chooses replacement fields using application-defined rules, synchronously or asynchronously.
300
+ * Return field names from the supplied choices, not aliases or `Field` objects.
301
+ * Each run replaces previous selections; omitted source fields remain unmapped.
302
+ *
303
+ * @param input - The layers, available field choices, and setting for allowing duplicate replacements.
304
+ * @param signal - Aborted when a newer run starts, inputs or the duplicate policy change, the user selects a field,
305
+ * or the component disconnects. Use it to cancel requests. Results from aborted runs are ignored.
306
+ * @returns All matches for this run, or a promise that resolves to them.
307
+ * @internal
308
+ */
309
+ export type FieldMatcher = (input: FieldMatcherInput, signal: AbortSignal) => FieldMatchResult | PromiseLike<FieldMatchResult>;
310
+
311
+ /**
312
+ * Chooses which source fields users need to map.
313
+ *
314
+ * @param field - A field from the source layer or `additionalSourceFields`.
315
+ * @param layer - The source layer or sublayer.
316
+ * @returns `true` to show and match the field, or `false` to leave it out of the component and its results.
317
+ * @internal
318
+ */
319
+ export type SourceFieldFilter = (field: Field, layer: LayerOrSublayer) => boolean;
320
+
321
+ /**
322
+ * Checks whether a replacement field can be used for a source field.
323
+ *
324
+ * @param field - The replacement field to check.
325
+ * @param layer - The replacement layer or sublayer.
326
+ * @param sourceField - The source field that needs a replacement.
327
+ * @returns `true` to let the user or matcher choose this field, or `false` to leave it out of the choices.
328
+ * @internal
329
+ */
330
+ export type ReplacementFieldFilter = (field: Field, layer: LayerOrSublayer, sourceField: Field) => boolean;
331
+
332
+ /**
333
+ * Customizes how fields are displayed.
334
+ *
335
+ * @param field - The field being displayed.
336
+ * @param source - The source or replacement layer being displayed. Additional source fields use the source layer.
337
+ * @returns Display options, or `undefined` to keep the default appearance.
338
+ * @internal
339
+ */
340
+ export type FieldDisplayInfoCallback = (field: Field, source: LayerOrSublayer) => FieldDisplayInfo | undefined;
341
+
342
+ /**
343
+ * Customizes how layers are displayed.
344
+ *
345
+ * @param source - The source layer or a replacement choice being displayed.
346
+ * @returns Display options, or `undefined` to keep the default appearance.
347
+ * @internal
348
+ */
349
+ export type LayerDisplayInfoCallback = (source: LayerOrSublayer) => LayerDisplayInfo | undefined;
350
+
351
+ /**
352
+ * A source field and its selected replacement. Both are the original `Field` objects, not copies.
353
+ *
354
+ * @internal
355
+ */
356
+ export interface FieldMapping {
357
+ /** A field from the source layer or `additionalSourceFields`. */
358
+ source: Field;
359
+ /** The selected replacement field, or `undefined` if unmapped. */
360
+ replacement?: Field;
361
+ }
362
+
363
+ /**
364
+ * The matches returned by a custom field matcher.
365
+ *
366
+ * @internal
367
+ */
368
+ export interface FieldMatchResult {
369
+ readonly matches: readonly FieldMatch[];
370
+ }
371
+
372
+ /**
373
+ * The layers and available field choices passed to a custom matcher each time it runs.
374
+ *
375
+ * @internal
376
+ */
377
+ export interface FieldMatcherInput {
378
+ /** Whether the matcher can use the same replacement field for more than one source field. */
379
+ allowDuplicateReplacementFields: boolean;
380
+ /** Source fields that pass `sourceFieldFilter`, each with choices allowed by `replacementFieldFilter`. */
381
+ fieldCandidates: readonly FieldMatchCandidate[];
382
+ /** The layer or sublayer selected as the replacement. */
383
+ replacement: LayerOrSublayer;
384
+ /** The layer or sublayer whose fields need replacements. */
385
+ source: LayerOrSublayer;
386
+ }
387
+
388
+ /**
389
+ * Display options for a field.
390
+ *
391
+ * @internal
392
+ */
393
+ export interface FieldDisplayInfo extends DisplayInfo {
394
+ /** A localized group heading for this field in the replacement-field selector. */
395
+ groupName?: string;
396
+ }
397
+
398
+ /**
399
+ * Display options for a layer.
400
+ *
401
+ * @internal
402
+ */
403
+ export type LayerDisplayInfo = DisplayInfo;
404
+
405
+ /**
406
+ * A source field and the replacement fields a custom matcher can choose for it.
407
+ *
408
+ * @internal
409
+ */
410
+ export interface FieldMatchCandidate {
411
+ /** Fields that pass `replacementFieldFilter` for this source field. */
412
+ replacementFields: readonly Field[];
413
+ /** A source field that passes `sourceFieldFilter`. */
414
+ sourceField: Field;
415
+ }
416
+
417
+ /**
418
+ * A source field name paired with its replacement field name.
419
+ *
420
+ * @internal
421
+ */
422
+ export interface FieldMatch {
423
+ /** The `name` of a field from the replacement choices supplied for this source field. */
424
+ replacementFieldName: string;
425
+ /** The `name` of a source field passed to the matcher. */
426
+ sourceFieldName: string;
427
+ }
428
+
429
+ /**
430
+ * Options for how a field or layer looks in the component.
431
+ *
432
+ * @internal
433
+ */
434
+ export interface DisplayInfo {
435
+ /** A Calcite icon name. `undefined` uses the default for the field or layer type; `null` hides the icon. */
436
+ icon?: Icon["icon"] | null;
437
+ }