@polymer/polymer/lib/mixins/properties-changed.d.ts

The Polymer library makes it easy to create your own web components. Give your element some markup and properties, and then use it on a site. Polymer provides features like dynamic templates and data binding to reduce the amount of boilerplate you need to

// tslint:disable:variable-name Describing an API that's defined elsewhere.
// tslint:disable:no-any describes the API as best we are able today

import {dedupingMixin} from '../utils/mixin.js';

import {microTask} from '../utils/async.js';

export {PropertiesChanged};


/**
 * Element class mixin that provides basic meta-programming for creating one
 * or more property accessors (getter/setter pair) that enqueue an async
 * (batched) `_propertiesChanged` callback.
 *
 * For basic usage of this mixin, call `MyClass.createProperties(props)`
 * once at class definition time to create property accessors for properties
 * named in props, implement `_propertiesChanged` to react as desired to
 * property changes, and implement `static get observedAttributes()` and
 * include lowercase versions of any property names that should be set from
 * attributes. Last, call `this._enableProperties()` in the element's
 * `connectedCallback` to enable the accessors.
 */
declare function PropertiesChanged<T extends new (...args: any[]) => {}>(base: T): T & PropertiesChangedConstructor;

interface PropertiesChangedConstructor {
  new(...args: any[]): PropertiesChanged;

  /**
   * Creates property accessors for the given property names.
   *
   * @param props Object whose keys are names of accessors.
   */
  createProperties(props: object): void;

  /**
   * Returns an attribute name that corresponds to the given property.
   * The attribute name is the lowercased property name. Override to
   * customize this mapping.
   *
   * @param property Property to convert
   * @returns Attribute name corresponding to the given property.
   */
  attributeNameForProperty(property: string): string;

  /**
   * Override point to provide a type to which to deserialize a value to
   * a given property.
   *
   * @param name Name of property
   */
  typeForProperty(name: string): void;
}

export {PropertiesChangedConstructor};

interface PropertiesChanged {

  /**
   * Creates a setter/getter pair for the named property with its own
   * local storage.  The getter returns the value in the local storage,
   * and the setter calls `_setProperty`, which updates the local storage
   * for the property and enqueues a `_propertiesChanged` callback.
   *
   * This method may be called on a prototype or an instance.  Calling
   * this method may overwrite a property value that already exists on
   * the prototype/instance by creating the accessor.
   *
   * @param property Name of the property
   * @param readOnly When true, no setter is created; the
   *   protected `_setProperty` function must be used to set the property
   */
  _createPropertyAccessor(property: string, readOnly?: boolean): void;

  /**
   * Adds the given `property` to a map matching attribute names
   * to property names, using `attributeNameForProperty`. This map is
   * used when deserializing attribute values to properties.
   *
   * @param property Name of the property
   */
  _addPropertyToAttributeMap(property: string): any;

  /**
   * Defines a property accessor for the given property.
   *
   * @param property Name of the property
   * @param readOnly When true, no setter is created
   */
  _definePropertyAccessor(property: string, readOnly?: boolean): void;

  /**
   * Lifecycle callback called when properties are enabled via
   * `_enableProperties`.
   *
   * Users may override this function to implement behavior that is
   * dependent on the element having its property data initialized, e.g.
   * from defaults (initialized from `constructor`, `_initializeProperties`),
   * `attributeChangedCallback`, or values propagated from host e.g. via
   * bindings.  `super.ready()` must be called to ensure the data system
   * becomes enabled.
   */
  ready(): void;

  /**
   * Initializes the local storage for property accessors.
   *
   * Provided as an override point for performing any setup work prior
   * to initializing the property accessor system.
   */
  _initializeProperties(): void;

  /**
   * Called at ready time with bag of instance properties that overwrote
   * accessors when the element upgraded.
   *
   * The default implementation sets these properties back into the
   * setter at ready time.  This method is provided as an override
   * point for customizing or providing more efficient initialization.
   *
   * @param props Bag of property values that were overwritten
   *   when creating property accessors.
   */
  _initializeInstanceProperties(props: object|null): void;

  /**
   * Updates the local storage for a property (via `_setPendingProperty`)
   * and enqueues a `_proeprtiesChanged` callback.
   *
   * @param property Name of the property
   * @param value Value to set
   */
  _setProperty(property: string, value: any): void;

  /**
   * Returns the value for the given property.
   *
   * @param property Name of property
   * @returns Value for the given property
   */
  _getProperty(property: string): any;

  /**
   * Updates the local storage for a property, records the previous value,
   * and adds it to the set of "pending changes" that will be passed to the
   * `_propertiesChanged` callback.  This method does not enqueue the
   * `_propertiesChanged` callback.
   *
   * @param property Name of the property
   * @param value Value to set
   * @param ext Not used here; affordance for closure
   * @returns Returns true if the property changed
   */
  _setPendingProperty(property: string, value: any, ext?: boolean): boolean;

  /**
   * @param property Name of the property
   * @returns Returns true if the property is pending.
   */
  _isPropertyPending(property: string): boolean;

  /**
   * Marks the properties as invalid, and enqueues an async
   * `_propertiesChanged` callback.
   */
  _invalidateProperties(): void;

  /**
   * Call to enable property accessor processing. Before this method is
   * called accessor values will be set but side effects are
   * queued. When called, any pending side effects occur immediately.
   * For elements, generally `connectedCallback` is a normal spot to do so.
   * It is safe to call this method multiple times as it only turns on
   * property accessors once.
   */
  _enableProperties(): void;

  /**
   * Calls the `_propertiesChanged` callback with the current set of
   * pending changes (and old values recorded when pending changes were
   * set), and resets the pending set of changes. Generally, this method
   * should not be called in user code.
   */
  _flushProperties(): void;

  /**
   * Called in `_flushProperties` to determine if `_propertiesChanged`
   * should be called. The default implementation returns true if
   * properties are pending. Override to customize when
   * `_propertiesChanged` is called.
   *
   * @param currentProps Bag of all current accessor values
   * @param changedProps Bag of properties changed since the last
   *   call to `_propertiesChanged`
   * @param oldProps Bag of previous values for each property
   *   in `changedProps`
   * @returns true if changedProps is truthy
   */
  _shouldPropertiesChange(currentProps: object, changedProps: object|null, oldProps: object|null): boolean;

  /**
   * Callback called when any properties with accessors created via
   * `_createPropertyAccessor` have been set.
   *
   * @param currentProps Bag of all current accessor values
   * @param changedProps Bag of properties changed since the last
   *   call to `_propertiesChanged`
   * @param oldProps Bag of previous values for each property
   *   in `changedProps`
   */
  _propertiesChanged(currentProps: object, changedProps: object|null, oldProps: object|null): void;

  /**
   * Method called to determine whether a property value should be
   * considered as a change and cause the `_propertiesChanged` callback
   * to be enqueued.
   *
   * The default implementation returns `true` if a strict equality
   * check fails. The method always returns false for `NaN`.
   *
   * Override this method to e.g. provide stricter checking for
   * Objects/Arrays when using immutable patterns.
   *
   * @param property Property name
   * @param value New property value
   * @param old Previous property value
   * @returns Whether the property should be considered a change
   *   and enqueue a `_proeprtiesChanged` callback
   */
  _shouldPropertyChange(property: string, value: any, old: any): boolean;

  /**
   * Implements native Custom Elements `attributeChangedCallback` to
   * set an attribute value to a property via `_attributeToProperty`.
   *
   * @param name Name of attribute that changed
   * @param old Old attribute value
   * @param value New attribute value
   * @param namespace Attribute namespace.
   */
  attributeChangedCallback(name: string, old: string|null, value: string|null, namespace: string|null): void;

  /**
   * Deserializes an attribute to its associated property.
   *
   * This method calls the `_deserializeValue` method to convert the string to
   * a typed value.
   *
   * @param attribute Name of attribute to deserialize.
   * @param value of the attribute.
   * @param type type to deserialize to, defaults to the value
   * returned from `typeForProperty`
   */
  _attributeToProperty(attribute: string, value: string|null, type?: any): void;

  /**
   * Serializes a property to its associated attribute.
   *
   * @param property Property name to reflect.
   * @param attribute Attribute name to reflect to.
   * @param value Property value to refect.
   */
  _propertyToAttribute(property: string, attribute?: string, value?: any): void;

  /**
   * Sets a typed value to an HTML attribute on a node.
   *
   * This method calls the `_serializeValue` method to convert the typed
   * value to a string.  If the `_serializeValue` method returns `undefined`,
   * the attribute will be removed (this is the default for boolean
   * type `false`).
   *
   * @param node Element to set attribute to.
   * @param value Value to serialize.
   * @param attribute Attribute name to serialize to.
   */
  _valueToNodeAttribute(node: Element|null, value: any, attribute: string): void;

  /**
   * Converts a typed JavaScript value to a string.
   *
   * This method is called when setting JS property values to
   * HTML attributes.  Users may override this method to provide
   * serialization for custom types.
   *
   * @param value Property value to serialize.
   * @returns String serialized from the provided
   * property  value.
   */
  _serializeValue(value: any): string|undefined;

  /**
   * Converts a string to a typed JavaScript value.
   *
   * This method is called when reading HTML attribute values to
   * JS properties.  Users may override this method to provide
   * deserialization for custom `type`s. Types for `Boolean`, `String`,
   * and `Number` convert attributes to the expected types.
   *
   * @param value Value to deserialize.
   * @param type Type to deserialize the string to.
   * @returns Typed value deserialized from the provided string.
   */
  _deserializeValue(value: string|null, type?: any): any;
}