1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
7 |
|
8 |
|
9 |
|
10 |
|
11 |
|
12 |
|
13 |
|
14 |
|
15 |
|
16 |
|
17 | export interface ComplexAttributeConverter<Type = any, TypeHint = any> {
|
18 | |
19 |
|
20 |
|
21 |
|
22 | fromAttribute?(value: string, type?: TypeHint): Type;
|
23 | |
24 |
|
25 |
|
26 |
|
27 | toAttribute?(value: Type, type?: TypeHint): string | null;
|
28 | }
|
29 | declare type AttributeConverter<Type = any, TypeHint = any> = ComplexAttributeConverter<Type> | ((value: string, type?: TypeHint) => Type);
|
30 | /**
|
31 | * Defines options for a property accessor.
|
32 | */
|
33 | export interface PropertyDeclaration<Type = any, TypeHint = any> {
|
34 | /**
|
35 | * Indicates how and whether the property becomes an observed attribute.
|
36 | * If the value is `false`, the property is not added to `observedAttributes`.
|
37 | * If true or absent, the lowercased property name is observed (e.g. `fooBar`
|
38 | * becomes `foobar`). If a string, the string value is observed (e.g
|
39 | * `attribute: 'foo-bar'`).
|
40 | */
|
41 | attribute?: boolean | string;
|
42 | /**
|
43 | * Indicates the type of the property. This is used only as a hint for the
|
44 | * `converter` to determine how to convert the attribute
|
45 | * to/from a property.
|
46 | */
|
47 | type?: TypeHint;
|
48 | /**
|
49 | * Indicates how to convert the attribute to/from a property. If this value
|
50 | * is a function, it is used to convert the attribute value a the property
|
51 | * value. If it's an object, it can have keys for `fromAttribute` and
|
52 | * `toAttribute`. If no `toAttribute` function is provided and
|
53 | * `reflect` is set to `true`, the property value is set directly to the
|
54 | * attribute. A default `converter` is used if none is provided; it supports
|
55 | * `Boolean`, `String`, `Number`, `Object`, and `Array`. Note,
|
56 | * when a property changes and the converter is used to update the attribute,
|
57 | * the property is never updated again as a result of the attribute changing,
|
58 | * and vice versa.
|
59 | */
|
60 | converter?: AttributeConverter<Type, TypeHint>;
|
61 | /**
|
62 | * Indicates if the property should reflect to an attribute.
|
63 | * If `true`, when the property is set, the attribute is set using the
|
64 | * attribute name determined according to the rules for the `attribute`
|
65 | * property option and the value of the property converted using the rules
|
66 | * from the `converter` property option.
|
67 | */
|
68 | reflect?: boolean;
|
69 | /**
|
70 | * A function that indicates if a property should be considered changed when
|
71 | * it is set. The function should take the `newValue` and `oldValue` and
|
72 | * return `true` if an update should be requested.
|
73 | */
|
74 | hasChanged?(value: Type, oldValue: Type): boolean;
|
75 | /**
|
76 | * Indicates whether an accessor will be created for this property. By
|
77 | * default, an accessor will be generated for this property that requests an
|
78 | * update when set. If this flag is `true`, no accessor will be created, and
|
79 | * it will be the user's responsibility to call
|
80 | * `this.requestUpdate(propertyName, oldValue)` to request an update when
|
81 | * the property changes.
|
82 | */
|
83 | noAccessor?: boolean;
|
84 | }
|
85 | /**
|
86 | * Map of properties to PropertyDeclaration options. For each property an
|
87 | * accessor is made, and the property is processed according to the
|
88 | * PropertyDeclaration options.
|
89 | */
|
90 | export interface PropertyDeclarations {
|
91 | [key: string]: PropertyDeclaration;
|
92 | }
|
93 | export declare type PropertyValues = Map<PropertyKey, unknown>;
|
94 | export declare const defaultConverter: ComplexAttributeConverter;
|
95 | export interface HasChanged {
|
96 | (value: unknown, old: unknown): boolean;
|
97 | }
|
98 | /**
|
99 | * Change function that returns true if `value` is different from `oldValue`.
|
100 | * This method is used as the default for a property's `hasChanged` function.
|
101 | */
|
102 | export declare const notEqual: HasChanged;
|
103 | /**
|
104 | * Base element class which manages element properties and attributes. When
|
105 | * properties change, the `update` method is asynchronously called. This method
|
106 | * should be supplied by subclassers to render updates as desired.
|
107 | */
|
108 | export declare abstract class UpdatingElement extends HTMLElement {
|
109 | /**
|
110 | * Maps attribute names to properties; for example `foobar` attribute to
|
111 | * `fooBar` property. Created lazily on user subclasses when finalizing the
|
112 | * class.
|
113 | */
|
114 | private static _attributeToPropertyMap;
|
115 | /**
|
116 | * Marks class as having finished creating properties.
|
117 | */
|
118 | protected static finalized: boolean;
|
119 | /**
|
120 | * Memoized list of all class properties, including any superclass properties.
|
121 | * Created lazily on user subclasses when finalizing the class.
|
122 | */
|
123 | private static _classProperties?;
|
124 | /**
|
125 | * User-supplied object that maps property names to `PropertyDeclaration`
|
126 | * objects containing options for configuring the property.
|
127 | */
|
128 | static properties: PropertyDeclarations;
|
129 | /**
|
130 | * Returns a list of attributes corresponding to the registered properties.
|
131 | * @nocollapse
|
132 | */
|
133 | static readonly observedAttributes: string[];
|
134 | /**
|
135 | * Ensures the private `_classProperties` property metadata is created.
|
136 | * In addition to `_finalize` this is also called in `createProperty` to
|
137 | * ensure the `@property` decorator can add property metadata.
|
138 | */
|
139 | /** @nocollapse */
|
140 | private static _ensureClassProperties;
|
141 | /**
|
142 | * Creates a property accessor on the element prototype if one does not exist.
|
143 | * The property setter calls the property's `hasChanged` property option
|
144 | * or uses a strict identity check to determine whether or not to request
|
145 | * an update.
|
146 | * @nocollapse
|
147 | */
|
148 | static createProperty(name: PropertyKey, options?: PropertyDeclaration): void;
|
149 | /**
|
150 | * Creates property accessors for registered properties and ensures
|
151 | * any superclasses are also finalized.
|
152 | * @nocollapse
|
153 | */
|
154 | private static _finalize;
|
155 | /**
|
156 | * Returns the property name for the given attribute `name`.
|
157 | * @nocollapse
|
158 | */
|
159 | private static _attributeNameForProperty;
|
160 | /**
|
161 | * Returns true if a property should request an update.
|
162 | * Called when a property value is set and uses the `hasChanged`
|
163 | * option for the property if present or a strict identity check.
|
164 | * @nocollapse
|
165 | */
|
166 | private static _valueHasChanged;
|
167 | /**
|
168 | * Returns the property value for the given attribute value.
|
169 | * Called via the `attributeChangedCallback` and uses the property's
|
170 | * `converter` or `converter.fromAttribute` property option.
|
171 | * @nocollapse
|
172 | */
|
173 | private static _propertyValueFromAttribute;
|
174 | /**
|
175 | * Returns the attribute value for the given property value. If this
|
176 | * returns undefined, the property will *not* be reflected to an attribute.
|
177 | * If this returns null, the attribute will be removed, otherwise the
|
178 | * attribute will be set to the value.
|
179 | * This uses the property's `reflect` and `type.toAttribute` property options.
|
180 | * @nocollapse
|
181 | */
|
182 | private static _propertyValueToAttribute;
|
183 | private _updateState;
|
184 | private _instanceProperties;
|
185 | private _updatePromise;
|
186 | private _hasConnectedResolver;
|
187 | /**
|
188 | * Map with keys for any properties that have changed since the last
|
189 | * update cycle with previous values.
|
190 | */
|
191 | private _changedProperties;
|
192 | /**
|
193 | * Map with keys of properties that should be reflected when updated.
|
194 | */
|
195 | private _reflectingProperties;
|
196 | constructor();
|
197 | /**
|
198 | * Performs element initialization. By default captures any pre-set values for
|
199 | * registered properties.
|
200 | */
|
201 | protected initialize(): void;
|
202 | /**
|
203 | * Fixes any properties set on the instance before upgrade time.
|
204 | * Otherwise these would shadow the accessor and break these properties.
|
205 | * The properties are stored in a Map which is played back after the
|
206 | * constructor runs. Note, on very old versions of Safari (<=9) or Chrome
|
207 | * (<=41), properties created for native platform properties like (`id` or
|
208 | * `name`) may not have default values set in the element constructor. On
|
209 | * these browsers native properties appear on instances and therefore their
|
210 | * default value will overwrite any element default (e.g. if the element sets
|
211 | * this.id = 'id' in the constructor, the 'id' will become '' since this is
|
212 | * the native platform default).
|
213 | */
|
214 | private _saveInstanceProperties;
|
215 | /**
|
216 | * Applies previously saved instance properties.
|
217 | */
|
218 | private _applyInstanceProperties;
|
219 | connectedCallback(): void;
|
220 | /**
|
221 | * Allows for `super.disconnectedCallback()` in extensions while
|
222 | * reserving the possibility of making non-breaking feature additions
|
223 | * when disconnecting at some point in the future.
|
224 | */
|
225 | disconnectedCallback(): void;
|
226 | /**
|
227 | * Synchronizes property values when attributes change.
|
228 | */
|
229 | attributeChangedCallback(name: string, old: string, value: string): void;
|
230 | private _propertyToAttribute;
|
231 | private _attributeToProperty;
|
232 | /**
|
233 | * Requests an update which is processed asynchronously. This should
|
234 | * be called when an element should update based on some state not triggered
|
235 | * by setting a property. In this case, pass no arguments. It should also be
|
236 | * called when manually implementing a property setter. In this case, pass the
|
237 | * property `name` and `oldValue` to ensure that any configured property
|
238 | * options are honored. Returns the `updateComplete` Promise which is resolved
|
239 | * when the update completes.
|
240 | *
|
241 | * @param name {PropertyKey} (optional) name of requesting property
|
242 | * @param oldValue {any} (optional) old value of requesting property
|
243 | * @returns {Promise} A Promise that is resolved when the update completes.
|
244 | */
|
245 | requestUpdate(name?: PropertyKey, oldValue?: any): Promise<unknown>;
|
246 | /**
|
247 | * Sets up the element to asynchronously update.
|
248 | */
|
249 | private _enqueueUpdate;
|
250 | private readonly _hasConnected;
|
251 | private readonly _hasRequestedUpdate;
|
252 | protected readonly hasUpdated: number;
|
253 | /**
|
254 | * Performs an element update.
|
255 | *
|
256 | * You can override this method to change the timing of updates. For instance,
|
257 | * to schedule updates to occur just before the next frame:
|
258 | *
|
259 | * ```
|
260 | * protected async performUpdate(): Promise<unknown> {
|
261 | * await new Promise((resolve) => requestAnimationFrame(() => resolve()));
|
262 | * super.performUpdate();
|
263 | * }
|
264 | * ```
|
265 | */
|
266 | protected performUpdate(): void | Promise<unknown>;
|
267 | private _markUpdated;
|
268 | /**
|
269 | * Returns a Promise that resolves when the element has completed updating.
|
270 | * The Promise value is a boolean that is `true` if the element completed the
|
271 | * update without triggering another update. The Promise result is `false` if
|
272 | * a property was set inside `updated()`. This getter can be implemented to
|
273 | * await additional state. For example, it is sometimes useful to await a
|
274 | * rendered element before fulfilling this Promise. To do this, first await
|
275 | * `super.updateComplete` then any subsequent state.
|
276 | *
|
277 | * @returns {Promise} The Promise returns a boolean that indicates if the
|
278 | * update resolved without triggering another update.
|
279 | */
|
280 | readonly updateComplete: Promise<unknown>;
|
281 | /**
|
282 | * Controls whether or not `update` should be called when the element requests
|
283 | * an update. By default, this method always returns `true`, but this can be
|
284 | * customized to control when to update.
|
285 | *
|
286 | * * @param _changedProperties Map of changed properties with old values
|
287 | */
|
288 | protected shouldUpdate(_changedProperties: PropertyValues): boolean;
|
289 | /**
|
290 | * Updates the element. This method reflects property values to attributes.
|
291 | * It can be overridden to render and keep updated element DOM.
|
292 | * Setting properties inside this method will *not* trigger
|
293 | * another update.
|
294 | *
|
295 | * * @param _changedProperties Map of changed properties with old values
|
296 | */
|
297 | protected update(_changedProperties: PropertyValues): void;
|
298 | /**
|
299 | * Invoked whenever the element is updated. Implement to perform
|
300 | * post-updating tasks via DOM APIs, for example, focusing an element.
|
301 | *
|
302 | * Setting properties inside this method will trigger the element to update
|
303 | * again after this update cycle completes.
|
304 | *
|
305 | * * @param _changedProperties Map of changed properties with old values
|
306 | */
|
307 | protected updated(_changedProperties: PropertyValues): void;
|
308 | /**
|
309 | * Invoked when the element is first updated. Implement to perform one time
|
310 | * work on the element after update.
|
311 | *
|
312 | * Setting properties inside this method will trigger the element to update
|
313 | * again after this update cycle completes.
|
314 | *
|
315 | * * @param _changedProperties Map of changed properties with old values
|
316 | */
|
317 | protected firstUpdated(_changedProperties: PropertyValues): void;
|
318 | }
|
319 | export {};
|
320 | //# sourceMappingURL=updating-element.d.ts.map |
\ | No newline at end of file |