third_party/polymer/v1_0/components/polymer-externs/polymer.externs.js

   1 /**
   2  * @fileoverview Closure compiler externs for the Polymer library.
   3  *
   4  * @externs
   5  * @license
   6  * Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
   7  * This code may only be used under the BSD style license found at
   8  * http://polymer.github.io/LICENSE.txt. The complete set of authors may be
   9  * found at http://polymer.github.io/AUTHORS.txt. The complete set of
  10  * contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt. Code
  11  * distributed by Google as part of the polymer project is also subject to an
  12  * additional IP rights grant found at http://polymer.github.io/PATENTS.txt.
  13  */
  14
  15 /**
  16  * @param {!{is: string}} descriptor The Polymer descriptor of the element.
  17  * @see https://github.com/Polymer/polymer/blob/0.8-preview/PRIMER.md#custom-element-registration
  18  */
  19 var Polymer = function(descriptor) {};
  20
  21
  22 /** @constructor @extends {HTMLElement} */
  23 var PolymerElement = function() {};
  24
  25 /**
  26  * A mapping from ID to element in this Polymer Element's local DOM.
  27  * @type {!Object}
  28  */
  29 PolymerElement.prototype.$;
  30
  31 /**
  32  * True if the element has been attached to the DOM.
  33  * @type {boolean}
  34  */
  35 PolymerElement.prototype.isAttached;
  36
  37 /**
  38  * The root node of the element.
  39  * @type {!Node}
  40  */
  41 PolymerElement.prototype.root;
  42
  43 /**
  44  * Returns the first node in this element’s local DOM that matches selector.
  45  * @param {string} selector
  46  */
  47 PolymerElement.prototype.$$ = function(selector) {};
  48
  49 /** @type {string} The Custom element tag name. */
  50 PolymerElement.prototype.is;
  51
  52 /** @type {string} The native element this element extends. */
  53 PolymerElement.prototype.extends;
  54
  55 /**
  56  * An array of objects whose properties get added to this element.
  57  * @see https://www.polymer-project.org/1.0/docs/devguide/behaviors.html
  58  * @type {!Array<!Object>|undefined}
  59  */
  60 PolymerElement.prototype.behaviors;
  61
  62 /**
  63  * A string-separated list of dependent properties that should result in a
  64  * change function being called. These observers differ from single-property
  65  * observers in that the change handler is called asynchronously.
  66  *
  67  * @type {!Object<string, string>|undefined}
  68  */
  69 PolymerElement.prototype.observers;
  70
  71 /** On create callback. */
  72 PolymerElement.prototype.created = function() {};
  73 /** On ready callback. */
  74 PolymerElement.prototype.ready = function() {};
  75 /** On registered callback. */
  76 PolymerElement.prototype.registered = function() {};
  77 /** On attached to the DOM callback. */
  78 PolymerElement.prototype.attached = function() {};
  79 /** On detached from the DOM callback. */
  80 PolymerElement.prototype.detached = function() {};
  81
  82 /**
  83  * Callback fired when an attribute on the element has been changed.
  84  *
  85  * @param {string} name The name of the attribute that changed.
  86  */
  87 PolymerElement.prototype.attributeChanged = function(name) {};
  88
  89 /** @typedef {!{
  90  *    type: !Function,
  91  *    reflectToAttribute: (boolean|undefined),
  92  *    readOnly: (boolean|undefined),
  93  *    notify: (boolean|undefined),
  94  *    value: *,
  95  *    computed: (string|undefined),
  96  *    observer: (string|undefined)
  97  *  }} */
  98 PolymerElement.PropertyConfig;
  99
 100 /** @typedef {!Object<string, (!Function|!PolymerElement.PropertyConfig)>} */
 101 PolymerElement.Properties;
 102
 103 /** @type {!PolymerElement.Properties} */
 104 PolymerElement.prototype.properties;
 105
 106 /** @type {!Object<string, *>} */
 107 PolymerElement.prototype.hostAttributes;
 108
 109 /**
 110  * An object that maps events to event handler function names.
 111  * @type {!Object<string, string>}
 112  */
 113 PolymerElement.prototype.listeners;
 114
 115 /**
 116  * Return the element whose local dom within which this element is contained.
 117  * @type {?Element}
 118  */
 119 PolymerElement.prototype.domHost;
 120
 121 /**
 122  * Notifies the event binding system of a change to a property.
 123  * @param  {string} path  The path to set.
 124  * @param  {*}      value The value to send in the update notification.
 125  */
 126 PolymerElement.prototype.notifyPath = function(path, value) {};
 127
 128 /**
 129  * Convienence method for setting a value to a path and notifying any
 130  * elements bound to the same path.
 131  *
 132  * Note, if any part in the path except for the last is undefined,
 133  * this method does nothing (this method does not throw when
 134  * dereferencing undefined paths).
 135  *
 136  * @param {(string|Array<(string|number)>)} path Path to the value
 137  *   to read.  The path may be specified as a string (e.g. `foo.bar.baz`)
 138  *   or an array of path parts (e.g. `['foo.bar', 'baz']`).  Note that
 139  *   bracketed expressions are not supported; string-based path parts
 140  *   *must* be separated by dots.  Note that when dereferencing array
 141  *   indicies, the index may be used as a dotted part directly
 142  *   (e.g. `users.12.name` or `['users', 12, 'name']`).
 143  * @param {*} value Value to set at the specified path.
 144  * @param {Object=} root Root object from which the path is evaluated.
 145 */
 146 PolymerElement.prototype.set = function(path, value, root) {};
 147
 148 /**
 149  * Convienence method for reading a value from a path.
 150  *
 151  * Note, if any part in the path is undefined, this method returns
 152  * `undefined` (this method does not throw when dereferencing undefined
 153  * paths).
 154  *
 155  * @param {(string|Array<(string|number)>)} path Path to the value
 156  *   to read.  The path may be specified as a string (e.g. `foo.bar.baz`)
 157  *   or an array of path parts (e.g. `['foo.bar', 'baz']`).  Note that
 158  *   bracketed expressions are not supported; string-based path parts
 159  *   *must* be separated by dots.  Note that when dereferencing array
 160  *   indicies, the index may be used as a dotted part directly
 161  *   (e.g. `users.12.name` or `['users', 12, 'name']`).
 162  * @param {Object=} root Root object from which the path is evaluated.
 163  * @return {*} Value at the path, or `undefined` if any part of the path
 164  *   is undefined.
 165  */
 166 PolymerElement.prototype.get = function(path, root) {};
 167
 168 /**
 169  * Adds items onto the end of the array at the path specified.
 170  *
 171  * The arguments after `path` and return value match that of
 172  * `Array.prototype.push`.
 173  *
 174  * This method notifies other paths to the same array that a
 175  * splice occurred to the array.
 176  *
 177  * @param {string} path Path to array.
 178  * @param {...*} var_args Items to push onto array
 179  * @return {number} New length of the array.
 180  */
 181 PolymerElement.prototype.push = function(path, var_args) {};
 182
 183 /**
 184  * Removes an item from the end of array at the path specified.
 185  *
 186  * The arguments after `path` and return value match that of
 187  * `Array.prototype.pop`.
 188  *
 189  * This method notifies other paths to the same array that a
 190  * splice occurred to the array.
 191  *
 192  * @param {string} path Path to array.
 193  * @return {*} Item that was removed.
 194  */
 195 PolymerElement.prototype.pop = function(path) {};
 196
 197 /**
 198  * Starting from the start index specified, removes 0 or more items
 199  * from the array and inserts 0 or more new itms in their place.
 200  *
 201  * The arguments after `path` and return value match that of
 202  * `Array.prototype.splice`.
 203  *
 204  * This method notifies other paths to the same array that a
 205  * splice occurred to the array.
 206  *
 207  * @param {string} path Path to array.
 208  * @param {number} start Index from which to start removing/inserting.
 209  * @param {number} deleteCount Number of items to remove.
 210  * @param {...*} var_args Items to insert into array.
 211  * @return {!Array} Array of removed items.
 212  */
 213 PolymerElement.prototype.splice = function(path, start, deleteCount, var_args) {};
 214
 215 /**
 216  * Removes an item from the beginning of array at the path specified.
 217  *
 218  * The arguments after `path` and return value match that of
 219  * `Array.prototype.pop`.
 220  *
 221  * This method notifies other paths to the same array that a
 222  * splice occurred to the array.
 223  *
 224  * @param {string} path Path to array.
 225  * @return {*} Item that was removed.
 226  */
 227 PolymerElement.prototype.shift = function(path) {};
 228
 229 /**
 230  * Adds items onto the beginning of the array at the path specified.
 231  *
 232  * The arguments after `path` and return value match that of
 233  * `Array.prototype.push`.
 234  *
 235  * This method notifies other paths to the same array that a
 236  * splice occurred to the array.
 237  *
 238  * @param {string} path Path to array.
 239  * @param {...*} var_args Items to insert info array
 240  * @return {number} New length of the array.
 241  */
 242 PolymerElement.prototype.unshift = function(path, var_args) {};
 243
 244 /**
 245  * Fire an event.
 246  *
 247  * @param {string} type An event name.
 248  * @param {Object=} detail
 249  * @param {{
 250  *   bubbles: (boolean|undefined),
 251  *   cancelable: (boolean|undefined),
 252  *   node: (!HTMLElement|undefined)}=} options
 253  * @return {Object} event
 254  */
 255 PolymerElement.prototype.fire = function(type, detail, options) {};
 256
 257 /**
 258  * Toggles the named boolean class on the host element, adding the class if
 259  * bool is truthy and removing it if bool is falsey. If node is specified, sets
 260  * the class on node instead of the host element.
 261  * @param {string} name
 262  * @param {boolean} bool
 263  * @param {HTMLElement=} node
 264  */
 265 PolymerElement.prototype.toggleClass = function(name, bool, node) {};
 266
 267 /**
 268  * Toggles the named boolean attribute on the host element, adding the attribute
 269  * if bool is truthy and removing it if bool is falsey. If node is specified,
 270  * sets the attribute on node instead of the host element.
 271  * @param {string} name
 272  * @param {boolean} bool
 273  * @param {HTMLElement=} node
 274  */
 275 PolymerElement.prototype.toggleAttribute = function(name, bool, node) {};
 276
 277 /**
 278  * Moves a boolean attribute from oldNode to newNode, unsetting the attribute
 279  * (if set) on oldNode and setting it on newNode.
 280  * @param {string} name
 281  * @param {!HTMLElement} newNode
 282  * @param {!HTMLElement} oldNode
 283  */
 284 PolymerElement.prototype.attributeFollows = function(name, newNode, oldNode) {};
 285
 286 /**
 287  * Convenience method to add an event listener on a given element, late bound to
 288  * a named method on this element.
 289  * @param {!Element} node Element to add event listener to.
 290  * @param {string} eventName Name of event to listen for.
 291  * @param {string} methodName Name of handler method on this to call.
 292  */
 293 PolymerElement.prototype.listen = function(node, eventName, methodName) {};
 294
 295 /**
 296  * Convenience method to remove an event listener from a given element.
 297  * @param {!Element} node Element to remove event listener from.
 298  * @param {string} eventName Name of event to stop listening for.
 299  * @param {string} methodName Name of handler method on this to remove.
 300  */
 301 PolymerElement.prototype.unlisten = function(node, eventName, methodName) {};
 302
 303 /**
 304  * Override scrolling behavior to all direction, one direction, or none.
 305  *
 306  * Valid scroll directions:
 307  * 'all': scroll in any direction
 308  * 'x': scroll only in the 'x' direction
 309  * 'y': scroll only in the 'y' direction
 310  * 'none': disable scrolling for this node
 311  *
 312  * @param {string=} direction Direction to allow scrolling Defaults to all.
 313  * @param {HTMLElement=} node Element to apply scroll direction setting.
 314  *     Defaults to this.
 315  */
 316 PolymerElement.prototype.setScrollDirection = function(direction, node) {};
 317
 318 /**
 319  * @param {!Function} method
 320  * @param {number=} wait
 321  * @return {number} A handle which can be used to cancel the job.
 322  */
 323 PolymerElement.prototype.async = function(method, wait) {};
 324
 325 /**
 326  * @param {...*} var_args
 327  */
 328 PolymerElement.prototype.factoryImpl = function(var_args) {};
 329
 330 Polymer.Base;
 331
 332 /**
 333  * Used by the promise-polyfill on its own.
 334  *
 335  * @param {!Function} method
 336  * @param {number=} wait
 337  * @return {number} A handle which can be used to cancel the job.
 338  */
 339 Polymer.Base.async = function(method, wait) {};
 340
 341 /**
 342  * Returns a property descriptor object for the property specified.
 343  *
 344  * This method allows introspecting the configuration of a Polymer element's
 345  * properties as configured in its `properties` object.  Note, this method
 346  * normalizes shorthand forms of the `properties` object into longhand form.
 347  *
 348  * @param {string} property Name of property to introspect.
 349  * @return {Object} Property descriptor for specified property.
 350 */
 351 Polymer.Base.getPropertyInfo = function(property) {};
 352
 353 /**
 354  * @param {number} handle
 355  */
 356 PolymerElement.prototype.cancelAsync = function(handle) {};
 357
 358 /**
 359  * Call debounce to collapse multiple requests for a named task into one
 360  * invocation, which is made after the wait time has elapsed with no new
 361  * request. If no wait time is given, the callback is called at microtask timing
 362  * (guaranteed to be before paint).
 363  * @param {string} jobName
 364  * @param {!Function} callback
 365  * @param {number=} wait
 366  */
 367 PolymerElement.prototype.debounce = function(jobName, callback, wait) {};
 368
 369 /**
 370  * Cancels an active debouncer without calling the callback.
 371  * @param {string} jobName
 372  */
 373 PolymerElement.prototype.cancelDebouncer = function(jobName) {};
 374
 375 /**
 376  * Calls the debounced callback immediately and cancels the debouncer.
 377  * @param {string} jobName
 378  */
 379 PolymerElement.prototype.flushDebouncer = function(jobName) {};
 380
 381 /**
 382  * @param {string} jobName
 383  * @return {boolean} True if the named debounce task is waiting to run.
 384  */
 385 PolymerElement.prototype.isDebouncerActive = function(jobName) {};
 386
 387
 388 /**
 389  * Applies a CSS transform to the specified node, or this element if no node is
 390  * specified. transform is specified as a string.
 391  * @param {string} transform
 392  * @param {HTMLElement=} node
 393  */
 394 PolymerElement.prototype.transform = function(transform, node) {};
 395
 396 /**
 397  * Transforms the specified node, or this element if no node is specified.
 398  * @param {number|string} x
 399  * @param {number|string} y
 400  * @param {number|string} z
 401  * @param {HTMLElement=} node
 402  */
 403 PolymerElement.prototype.translate3d = function(x, y, z, node) {};
 404
 405 /**
 406  * Dynamically imports an HTML document.
 407  * @param {string} href
 408  * @param {Function=} onload
 409  * @param {Function=} onerror
 410  */
 411 PolymerElement.prototype.importHref = function(href, onload, onerror) {};
 412
 413 /**
 414  * Delete an element from an array.
 415  * @param {!Array} array
 416  * @param {*} item
 417  */
 418 PolymerElement.prototype.arrayDelete = function(array, item) {};
 419
 420 /**
 421  * Resolve a url to make it relative to the current doc.
 422  * @param {string} url
 423  * @return {string}
 424  */
 425 PolymerElement.prototype.resolveUrl = function(url) {};
 426
 427 /**
 428  * Logs a message to the console.
 429  *
 430  * @param {!Array} var_args
 431  * @protected
 432  */
 433 PolymerElement.prototype._log = function(var_args) {};
 434
 435 /**
 436  * Logs a message to the console with a 'warn' level.
 437  *
 438  * @param {!Array} var_args
 439  * @protected
 440  */
 441 PolymerElement.prototype._warn = function(var_args) {};
 442
 443 /**
 444  * Logs a message to the console with an 'error' level.
 445  *
 446  * @param {!Array} var_args
 447  * @protected
 448  */
 449 PolymerElement.prototype._error = function(var_args) {};
 450
 451 /**
 452  * Formats string arguments together for a console log.
 453  *
 454  * @param {...*} var_args
 455  * @return {!Array} The formatted array of args to a log function.
 456  * @protected
 457  */
 458 PolymerElement.prototype._logf = function(var_args) {};
 459
 460
 461 /**
 462  * A Polymer DOM API for manipulating DOM such that local DOM and light DOM
 463  * trees are properly maintained.
 464  *
 465  * @constructor
 466  */
 467 var PolymerDomApi = function() {};
 468
 469 /** @param {!Node} node */
 470 PolymerDomApi.prototype.appendChild = function(node) {};
 471
 472 /**
 473  * @param {!Node} node
 474  * @param {!Node} beforeNode
 475  */
 476 PolymerDomApi.prototype.insertBefore = function(node, beforeNode) {};
 477
 478 /** @param {!Node} node */
 479 PolymerDomApi.prototype.removeChild = function(node) {};
 480
 481 /** @type {!Array<!Node>} */
 482 PolymerDomApi.prototype.childNodes;
 483
 484 /** @type {?Node} */
 485 PolymerDomApi.prototype.parentNode;
 486
 487 /** @type {?Node} */
 488 PolymerDomApi.prototype.firstChild;
 489
 490 /** @type {?Node} */
 491 PolymerDomApi.prototype.lastChild;
 492
 493 /** @type {?HTMLElement} */
 494 PolymerDomApi.prototype.firstElementChild;
 495
 496 /** @type {?HTMLElement} */
 497 PolymerDomApi.prototype.lastElementChild;
 498
 499 /** @type {?Node} */
 500 PolymerDomApi.prototype.previousSibling;
 501
 502 /** @type {?Node} */
 503 PolymerDomApi.prototype.nextSibling;
 504
 505 /** @type {string} */
 506 PolymerDomApi.prototype.textContent;
 507
 508 /** @type {string} */
 509 PolymerDomApi.prototype.innerHTML;
 510
 511 /**
 512  * @param {string} selector
 513  * @return {?HTMLElement}
 514  */
 515 PolymerDomApi.prototype.querySelector = function(selector) {};
 516
 517 /**
 518  * @param {string} selector
 519  * @return {!Array<!HTMLElement>}
 520  */
 521 PolymerDomApi.prototype.querySelectorAll = function(selector) {};
 522
 523 /** @return {!Array<!Node>} */
 524 PolymerDomApi.prototype.getDistributedNodes = function() {};
 525
 526 /** @return {!Array<!Node>} */
 527 PolymerDomApi.prototype.getDestinationInsertionPoints = function() {};
 528
 529 /** @return {?Node} */
 530 PolymerDomApi.prototype.getOwnerRoot = function() {};
 531
 532 /**
 533  * @param {string} attribute
 534  * @param {string|number|boolean} value Values are converted to strings with
 535  *     ToString, so we accept number and boolean since both convert easily to
 536  *     strings.
 537  */
 538 PolymerDomApi.prototype.setAttribute = function(attribute, value) {};
 539
 540 /** @param {string} attribute */
 541 PolymerDomApi.prototype.removeAttribute = function(attribute) {};
 542
 543 /** @type {?DOMTokenList} */
 544 PolymerDomApi.prototype.classList;
 545
 546 /**
 547  * @param {string} selector
 548  * @return {!Array<!HTMLElement>}
 549  */
 550 PolymerDomApi.prototype.queryDistributedElements = function(selector) {};
 551
 552 /**
 553  * A Polymer Event API.
 554  *
 555  * @constructor
 556  */
 557 var PolymerEventApi = function() {};
 558
 559 /** @type {?EventTarget} */
 560 PolymerEventApi.prototype.rootTarget;
 561
 562 /** @type {?EventTarget} */
 563 PolymerEventApi.prototype.localTarget;
 564
 565 /** @type {?Array<!Element>|undefined} */
 566 PolymerEventApi.prototype.path;
 567
 568 /**
 569  * Returns a Polymer-friendly API for manipulating DOM of a specified node or
 570  * an event API for a specified event..
 571  *
 572  * @param {?Node|?Event} nodeOrEvent
 573  * @return {!PolymerDomApi|!PolymerEventApi}
 574  */
 575 Polymer.dom = function(nodeOrEvent) {};
 576
 577 Polymer.dom.flush = function() {};
 578
 579 Polymer.CaseMap;
 580
 581 /**
 582  * Convert a string from dash to camel-case.
 583  * @param {string} dash
 584  * @return {string} The string in camel-case.
 585  */
 586 Polymer.CaseMap.dashToCamelCase = function(dash) {};
 587
 588 /**
 589  * Convert a string from camel-case to dash format.
 590  * @param {string} camel
 591  * @return {string} The string in dash format.
 592  */
 593 Polymer.CaseMap.camelToDashCase = function(camel) {};
 594
 595
 596 /**
 597  * Settings pulled from
 598  * https://github.com/Polymer/polymer/blob/master/src/lib/settings.html
 599  */
 600 Polymer.Settings;
 601
 602 /** @type {boolean} */
 603 Polymer.Settings.wantShadow;
 604
 605 /** @type {boolean} */
 606 Polymer.Settings.hasShadow;
 607
 608 /** @type {boolean} */
 609 Polymer.Settings.nativeShadow;
 610
 611 /** @type {boolean} */
 612 Polymer.Settings.useShadow;
 613
 614 /** @type {boolean} */
 615 Polymer.Settings.useNativeShadow;
 616
 617 /** @type {boolean} */
 618 Polymer.Settings.useNativeImports;
 619
 620 /** @type {boolean} */
 621 Polymer.Settings.useNativeCustomElements;
 622
 623
 624 /**
 625  * @see https://github.com/Polymer/polymer/blob/master/src/lib/template/templatizer.html
 626  * @polymerBehavior
 627  */
 628 Polymer.Templatizer = {
 629   /**
 630    * @param {?Object} model
 631    * @return {?Element}
 632    */
 633   stamp: function(model) {},
 634
 635   /**
 636    * @param {?Element} template
 637    */
 638   templatize: function(template) {},
 639 };
 640
 641
 642 /**
 643  * An Event type fired when moving while finger/button is down.
 644  * state - a string indicating the tracking state:
 645  *     + start: fired when tracking is first detected (finger/button down and
 646  *              moved past a pre-set distance threshold)
 647  *     + track: fired while tracking
 648  *     + end: fired when tracking ends
 649  * x - clientX coordinate for event
 650  * y - clientY coordinate for event
 651  * dx - change in pixels horizontally since the first track event
 652  * dy - change in pixels vertically since the first track event
 653  * ddx - change in pixels horizontally since last track event
 654  * ddy - change in pixels vertically since last track event
 655  * hover() - a function that may be called to determine the element currently
 656  *           being hovered
 657  *
 658  * @typedef {{
 659  *   state: string,
 660  *   x: number,
 661  *   y: number,
 662  *   dx: number,
 663  *   dy: number,
 664  *   ddx: number,
 665  *   ddy: number,
 666  *   hover: (function(): Node)
 667  * }}
 668  */
 669 var PolymerTrackEvent;
 670
 671 /**
 672  * An Event type fired when a finger does down, up, or taps.
 673  * x - clientX coordinate for event
 674  * y - clientY coordinate for event
 675  * sourceEvent - the original DOM event that caused the down action
 676  *
 677  * @typedef {{
 678  *   x: number,
 679  *   y: number,
 680  *   sourceEvent: Event
 681  * }}
 682  */
 683 var PolymerTouchEvent;