diff --git a/.gitignore b/.gitignore index 45174e387b..99bc180f89 100644 --- a/.gitignore +++ b/.gitignore @@ -18,7 +18,3 @@ analysis.json # NPM artifact polymer-polymer-*.tgz - -# Typings are generated upon publish to NPM, except for one. -*.d.ts -!interfaces.d.ts diff --git a/gen-tsd.json b/gen-tsd.json deleted file mode 100644 index 475d21b2cf..0000000000 --- a/gen-tsd.json +++ /dev/null @@ -1,46 +0,0 @@ -{ - "excludeFiles": [ - "dist/**", - "externs/**", - "gulpfile.js", - "test/**", - "util/**", - "index.html" - ], - "excludeIdentifiers": [ - "templatizedBase", - "setAttribute" - ], - "removeReferences": [ - "../shadycss/apply-shim.d.ts", - "../shadycss/custom-style-interface.d.ts" - ], - "renameTypes": { - "Polymer_PropertyEffects": "PropertyEffects", - "PolymerDomApi": "DomApi", - "PolymerDomApi.ObserveHandle": "FlattenedNodesObserver" - }, - "autoImport": { - "./interfaces": [ - "PolymerElementPropertiesMeta", - "PolymerElementProperties", - "PolymerInit", - "StampedTemplate", - "NodeInfo", - "TemplateInfo", - "LiteralBindingPart", - "MethodArg", - "MethodSignature", - "ExpressionBindingPart", - "BindingPart", - "Binding", - "AsyncInterface", - "GestureRecognizer", - "IdleDeadline", - "PolymerElementConstructor" - ], - "./lib/utils/debounce.js": [ - "Debouncer" - ] - } -} diff --git a/lib/elements/array-selector.d.ts b/lib/elements/array-selector.d.ts new file mode 100644 index 0000000000..90e374e0bc --- /dev/null +++ b/lib/elements/array-selector.d.ts @@ -0,0 +1,213 @@ +// 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 {PolymerElement} from '../../polymer-element.js'; + +import {dedupingMixin} from '../utils/mixin.js'; + +import {calculateSplices} from '../utils/array-splice.js'; + +import {ElementMixin} from '../mixins/element-mixin.js'; + + +/** + * Element mixin for recording dynamic associations between item paths in a + * master `items` array and a `selected` array such that path changes to the + * master array (at the host) element or elsewhere via data-binding) are + * correctly propagated to items in the selected array and vice-versa. + * + * The `items` property accepts an array of user data, and via the + * `select(item)` and `deselect(item)` API, updates the `selected` property + * which may be bound to other parts of the application, and any changes to + * sub-fields of `selected` item(s) will be kept in sync with items in the + * `items` array. When `multi` is false, `selected` is a property + * representing the last selected item. When `multi` is true, `selected` + * is an array of multiply selected items. + */ +declare function ArraySelectorMixin {}>(base: T): T & ArraySelectorMixinConstructor & ElementMixinConstructor & PropertyEffectsConstructor & TemplateStampConstructor & PropertyAccessorsConstructor & PropertiesChangedConstructor & PropertiesMixinConstructor; + +import {ElementMixinConstructor} from '../mixins/element-mixin.js'; + +import {PropertyEffectsConstructor, PropertyEffects} from '../mixins/property-effects.js'; + +import {TemplateStampConstructor, TemplateStamp} from '../mixins/template-stamp.js'; + +import {PropertyAccessorsConstructor, PropertyAccessors} from '../mixins/property-accessors.js'; + +import {PropertiesChangedConstructor, PropertiesChanged} from '../mixins/properties-changed.js'; + +import {PropertiesMixinConstructor, PropertiesMixin} from '../mixins/properties-mixin.js'; + +interface ArraySelectorMixinConstructor { + new(...args: any[]): ArraySelectorMixin; +} + +export {ArraySelectorMixinConstructor}; + +interface ArraySelectorMixin extends ElementMixin, PropertyEffects, TemplateStamp, PropertyAccessors, PropertiesChanged, PropertiesMixin { + + /** + * An array containing items from which selection will be made. + */ + items: any[]|null|undefined; + + /** + * When `true`, multiple items may be selected at once (in this case, + * `selected` is an array of currently selected items). When `false`, + * only one item may be selected at a time. + */ + multi: boolean|null|undefined; + + /** + * When `multi` is true, this is an array that contains any selected. + * When `multi` is false, this is the currently selected item, or `null` + * if no item is selected. + */ + selected: object|object[]|null; + + /** + * When `multi` is false, this is the currently selected item, or `null` + * if no item is selected. + */ + selectedItem: object|null; + + /** + * When `true`, calling `select` on an item that is already selected + * will deselect the item. + */ + toggle: boolean|null|undefined; + + /** + * Clears the selection state. + */ + clearSelection(): void; + + /** + * Returns whether the item is currently selected. + * + * @param item Item from `items` array to test + * @returns Whether the item is selected + */ + isSelected(item: any): boolean; + + /** + * Returns whether the item is currently selected. + * + * @param idx Index from `items` array to test + * @returns Whether the item is selected + */ + isIndexSelected(idx: number): boolean; + + /** + * Deselects the given item if it is already selected. + * + * @param item Item from `items` array to deselect + */ + deselect(item: any): void; + + /** + * Deselects the given index if it is already selected. + * + * @param idx Index from `items` array to deselect + */ + deselectIndex(idx: number): void; + + /** + * Selects the given item. When `toggle` is true, this will automatically + * deselect the item if already selected. + * + * @param item Item from `items` array to select + */ + select(item: any): void; + + /** + * Selects the given index. When `toggle` is true, this will automatically + * deselect the item if already selected. + * + * @param idx Index from `items` array to select + */ + selectIndex(idx: number): void; +} + +export {ArraySelectorMixin}; + +/** + * Element implementing the `ArraySelector` mixin, which records + * dynamic associations between item paths in a master `items` array and a + * `selected` array such that path changes to the master array (at the host) + * element or elsewhere via data-binding) are correctly propagated to items + * in the selected array and vice-versa. + * + * The `items` property accepts an array of user data, and via the + * `select(item)` and `deselect(item)` API, updates the `selected` property + * which may be bound to other parts of the application, and any changes to + * sub-fields of `selected` item(s) will be kept in sync with items in the + * `items` array. When `multi` is false, `selected` is a property + * representing the last selected item. When `multi` is true, `selected` + * is an array of multiply selected items. + * + * Example: + * + * ```js + * import {PolymerElement} from '@polymer/polymer'; + * import '@polymer/polymer/lib/elements/array-selector.js'; + * + * class EmployeeList extends PolymerElement { + * static get _template() { + * return html` + *
Employee list:
+ * + * + * + * + * + * + *
Selected employees:
+ * + * + * `; + * } + * static get is() { return 'employee-list'; } + * static get properties() { + * return { + * employees: { + * value() { + * return [ + * {first: 'Bob', last: 'Smith'}, + * {first: 'Sally', last: 'Johnson'}, + * ... + * ]; + * } + * } + * }; + * } + * toggleSelection(e) { + * const item = this.$.employeeList.itemForElement(e.target); + * this.$.selector.select(item); + * } + * } + * ``` + */ +declare class ArraySelector extends + ArraySelectorMixin( + PolymerElement) { +} + +declare global { + + interface HTMLElementTagNameMap { + "array-selector": ArraySelector; + } +} + +export {ArraySelector}; diff --git a/lib/elements/custom-style.d.ts b/lib/elements/custom-style.d.ts new file mode 100644 index 0000000000..2207ff1478 --- /dev/null +++ b/lib/elements/custom-style.d.ts @@ -0,0 +1,65 @@ +// tslint:disable:variable-name Describing an API that's defined elsewhere. + +import {cssFromModules} from '../utils/style-gather.js'; + +export {CustomStyle}; + +/** + * Custom element for defining styles in the main document that can take + * advantage of [shady DOM](https://github.com/webcomponents/shadycss) shims + * for style encapsulation, custom properties, and custom mixins. + * + * - Document styles defined in a `` are shimmed to ensure they + * do not leak into local DOM when running on browsers without native + * Shadow DOM. + * - Custom properties can be defined in a ``. Use the `html` selector + * to define custom properties that apply to all custom elements. + * - Custom mixins can be defined in a ``, if you import the optional + * [apply shim](https://github.com/webcomponents/shadycss#about-applyshim) + * (`shadycss/apply-shim.html`). + * + * To use: + * + * - Import `custom-style.html`. + * - Place a `` element in the main document, wrapping an inline ` + * + * ``` + */ +declare class CustomStyle extends HTMLElement { + + /** + * Returns the light-DOM ` + *
${this.partialTemplate}
+ * ${super.template} + * `; + * } + * static get partialTemplate() { return html`Partial!`; } + * + * @returns Constructed HTMLTemplateElement + */ +declare function html(strings: TemplateStringsArray, ...values: any[]): HTMLTemplateElement; + +export {htmlLiteral}; + + +/** + * An html literal tag that can be used with `html` to compose. + * a literal string. + * + * Example: + * + * static get template() { + * return html` + * + *
${staticValue}
+ * ${super.template} + * `; + * } + * static get styleTemplate() { + * return htmlLiteral`.shadowed { background: gray; }`; + * } + * + * @returns Constructed literal string + */ +declare function htmlLiteral(strings: TemplateStringsArray, ...values: any[]): LiteralString; diff --git a/lib/utils/mixin.d.ts b/lib/utils/mixin.d.ts new file mode 100644 index 0000000000..4f519e657d --- /dev/null +++ b/lib/utils/mixin.d.ts @@ -0,0 +1,11 @@ +// tslint:disable:variable-name Describing an API that's defined elsewhere. + +export {dedupingMixin}; + + +/** + * Wraps an ES6 class expression mixin such that the mixin is only applied + * if it has not already been applied its base argument. Also memoizes mixin + * applications. + */ +declare function dedupingMixin(mixin: T): T; diff --git a/lib/utils/path.d.ts b/lib/utils/path.d.ts new file mode 100644 index 0000000000..2d8d7e07f1 --- /dev/null +++ b/lib/utils/path.d.ts @@ -0,0 +1,159 @@ +// tslint:disable:variable-name Describing an API that's defined elsewhere. +// tslint:disable:no-any describes the API as best we are able today + +export {isPath}; + + +/** + * Returns true if the given string is a structured data path (has dots). + * + * Example: + * + * ``` + * isPath('foo.bar.baz') // true + * isPath('foo') // false + * ``` + * + * @returns True if the string contained one or more dots + */ +declare function isPath(path: string): boolean; + +export {root}; + + +/** + * Returns the root property name for the given path. + * + * Example: + * + * ``` + * root('foo.bar.baz') // 'foo' + * root('foo') // 'foo' + * ``` + * + * @returns Root property name + */ +declare function root(path: string): string; + +export {isAncestor}; + + +/** + * Given `base` is `foo.bar`, `foo` is an ancestor, `foo.bar` is not + * Returns true if the given path is an ancestor of the base path. + * + * Example: + * + * ``` + * isAncestor('foo.bar', 'foo') // true + * isAncestor('foo.bar', 'foo.bar') // false + * isAncestor('foo.bar', 'foo.bar.baz') // false + * ``` + * + * @returns True if `path` is an ancestor of `base`. + */ +declare function isAncestor(base: string, path: string): boolean; + +export {isDescendant}; + + +/** + * Given `base` is `foo.bar`, `foo.bar.baz` is an descendant + * + * Example: + * + * ``` + * isDescendant('foo.bar', 'foo.bar.baz') // true + * isDescendant('foo.bar', 'foo.bar') // false + * isDescendant('foo.bar', 'foo') // false + * ``` + * + * @returns True if `path` is a descendant of `base`. + */ +declare function isDescendant(base: string, path: string): boolean; + +export {translate}; + + +/** + * Replaces a previous base path with a new base path, preserving the + * remainder of the path. + * + * User must ensure `path` has a prefix of `base`. + * + * Example: + * + * ``` + * translate('foo.bar', 'zot', 'foo.bar.baz') // 'zot.baz' + * ``` + * + * @returns Translated string + */ +declare function translate(base: string, newBase: string, path: string): string; + +export {matches}; + + +/** + * @returns True if `path` is equal to `base` + */ +declare function matches(base: string, path: string): boolean; + +export {normalize}; + + +/** + * Converts array-based paths to flattened path. String-based paths + * are returned as-is. + * + * Example: + * + * ``` + * normalize(['foo.bar', 0, 'baz']) // 'foo.bar.0.baz' + * normalize('foo.bar.0.baz') // 'foo.bar.0.baz' + * ``` + * + * @returns Flattened path + */ +declare function normalize(path: string|Array): string; + +export {split}; + + +/** + * Splits a path into an array of property names. Accepts either arrays + * of path parts or strings. + * + * Example: + * + * ``` + * split(['foo.bar', 0, 'baz']) // ['foo', 'bar', '0', 'baz'] + * split('foo.bar.0.baz') // ['foo', 'bar', '0', 'baz'] + * ``` + * + * @returns Array of path parts + */ +declare function split(path: string|Array): string[]; + +export {get}; + + +/** + * Reads a value from a path. If any sub-property in the path is `undefined`, + * this method returns `undefined` (will never throw. + * + * @returns Value at path, or `undefined` if the path could not be + * fully dereferenced. + */ +declare function get(root: object|null, path: string|Array, info?: object|null): any; + +export {set}; + + +/** + * Sets a value to a path. If any sub-property in the path is `undefined`, + * this method will no-op. + * + * @returns The normalized version of the input path + */ +declare function set(root: object|null, path: string|Array, value: any): string|undefined; diff --git a/lib/utils/render-status.d.ts b/lib/utils/render-status.d.ts new file mode 100644 index 0000000000..993354c13b --- /dev/null +++ b/lib/utils/render-status.d.ts @@ -0,0 +1,40 @@ +// tslint:disable:variable-name Describing an API that's defined elsewhere. +// tslint:disable:no-any describes the API as best we are able today + +export {flush}; + + +/** + * Flushes all `beforeNextRender` tasks, followed by all `afterNextRender` + * tasks. + */ +declare function flush(): void; + +export {beforeNextRender}; + + +/** + * Enqueues a callback which will be run before the next render, at + * `requestAnimationFrame` timing. + * + * This method is useful for enqueuing work that requires DOM measurement, + * since measurement may not be reliable in custom element callbacks before + * the first render, as well as for batching measurement tasks in general. + * + * Tasks in this queue may be flushed by calling `flush()`. + */ +declare function beforeNextRender(context: any, callback: (...p0: any[]) => void, args?: any[]): void; + +export {afterNextRender}; + + +/** + * Enqueues a callback which will be run after the next render, equivalent + * to one task (`setTimeout`) after the next `requestAnimationFrame`. + * + * This method is useful for tuning the first-render performance of an + * element or application by deferring non-critical work until after the + * first paint. Typical non-render-critical work may include adding UI + * event listeners and aria attributes. + */ +declare function afterNextRender(context: any, callback: (...p0: any[]) => void, args?: any[]): void; diff --git a/lib/utils/resolve-url.d.ts b/lib/utils/resolve-url.d.ts new file mode 100644 index 0000000000..eb36fb8020 --- /dev/null +++ b/lib/utils/resolve-url.d.ts @@ -0,0 +1,37 @@ +// tslint:disable:variable-name Describing an API that's defined elsewhere. + +export {resolveUrl}; + + +/** + * Resolves the given URL against the provided `baseUri'. + * + * Note that this function performs no resolution for URLs that start + * with `/` (absolute URLs) or `#` (hash identifiers). For general purpose + * URL resolution, use `window.URL`. + * + * @returns resolved URL + */ +declare function resolveUrl(url: string, baseURI?: string|null): string; + +export {resolveCss}; + + +/** + * Resolves any relative URL's in the given CSS text against the provided + * `ownerDocument`'s `baseURI`. + * + * @returns Processed CSS text with resolved URL's + */ +declare function resolveCss(cssText: string, baseURI: string): string; + +export {pathFromUrl}; + + +/** + * Returns a path from a given `url`. The path includes the trailing + * `/` from the url. + * + * @returns resolved path + */ +declare function pathFromUrl(url: string): string; diff --git a/lib/utils/scope-subtree.d.ts b/lib/utils/scope-subtree.d.ts new file mode 100644 index 0000000000..1553d30da8 --- /dev/null +++ b/lib/utils/scope-subtree.d.ts @@ -0,0 +1,13 @@ +// tslint:disable:variable-name Describing an API that's defined elsewhere. + +export {scopeSubtree}; + + +/** + * Ensure that elements in a ShadowDOM container are scoped correctly. + * This function is only needed when ShadyDOM is used and unpatched DOM APIs are used in third party code. + * This can happen in noPatch mode or when specialized APIs like ranges or tables are used to mutate DOM. + * + * @returns Returns a new MutationObserver on `container` if `shouldObserve` is true. + */ +declare function scopeSubtree(container: Element, shouldObserve?: boolean): MutationObserver|null; diff --git a/lib/utils/settings.d.ts b/lib/utils/settings.d.ts new file mode 100644 index 0000000000..046d4baa6a --- /dev/null +++ b/lib/utils/settings.d.ts @@ -0,0 +1,150 @@ +// 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 {pathFromUrl} from './resolve-url.js'; + +export {setRootPath}; + + +/** + * Sets the global rootPath property used by `ElementMixin` and + * available via `rootPath`. + */ +declare function setRootPath(path: string): void; + +export {setSanitizeDOMValue}; + + +/** + * Sets the global sanitizeDOMValue available via this module's exported + * `sanitizeDOMValue` variable. + */ +declare function setSanitizeDOMValue(newSanitizeDOMValue: ((p0: any, p1: string, p2: string, p3: Node|null) => any)|undefined): void; + +export {getSanitizeDOMValue}; + + +/** + * Gets sanitizeDOMValue, for environments that don't well support `export let`. + * + * @returns sanitizeDOMValue + */ +declare function getSanitizeDOMValue(): ((p0: any, p1: string, p2: string, p3: Node|null) => any)|undefined; + +export {setPassiveTouchGestures}; + + +/** + * Sets `passiveTouchGestures` globally for all elements using Polymer Gestures. + */ +declare function setPassiveTouchGestures(usePassive: boolean): void; + +export {setStrictTemplatePolicy}; + + +/** + * Sets `strictTemplatePolicy` globally for all elements + */ +declare function setStrictTemplatePolicy(useStrictPolicy: boolean): void; + +export {setAllowTemplateFromDomModule}; + + +/** + * Sets `lookupTemplateFromDomModule` globally for all elements + */ +declare function setAllowTemplateFromDomModule(allowDomModule: boolean): void; + +export {setLegacyOptimizations}; + + +/** + * Sets `legacyOptimizations` globally for all elements to enable optimizations + * when only legacy based elements are used. + */ +declare function setLegacyOptimizations(useLegacyOptimizations: boolean): void; + +export {setLegacyWarnings}; + + +/** + * Sets `legacyWarnings` globally for all elements to migration warnings. + */ +declare function setLegacyWarnings(useLegacyWarnings: boolean): void; + +export {setSyncInitialRender}; + + +/** + * Sets `syncInitialRender` globally for all elements to enable synchronous + * initial rendering. + */ +declare function setSyncInitialRender(useSyncInitialRender: boolean): void; + +export {setLegacyUndefined}; + + +/** + * Sets `legacyUndefined` globally for all elements to enable legacy + * multi-property behavior for undefined values. + */ +declare function setLegacyUndefined(useLegacyUndefined: boolean): void; + +export {setOrderedComputed}; + + +/** + * Sets `orderedComputed` globally for all elements to enable ordered computed + * property computation. + */ +declare function setOrderedComputed(useOrderedComputed: boolean): void; + +export {setCancelSyntheticClickEvents}; + + +/** + * Sets `setCancelSyntheticEvents` globally for all elements to cancel synthetic click events. + */ +declare function setCancelSyntheticClickEvents(useCancelSyntheticClickEvents: boolean): void; + +export {setRemoveNestedTemplates}; + + +/** + * Sets `removeNestedTemplates` globally, to eliminate nested templates + * inside `dom-if` and `dom-repeat` as part of template parsing. + */ +declare function setRemoveNestedTemplates(useRemoveNestedTemplates: boolean): void; + +export {setFastDomIf}; + + +/** + * Sets `fastDomIf` globally, to put `dom-if` in a performance-optimized mode. + */ +declare function setFastDomIf(useFastDomIf: boolean): void; + +export {setSuppressTemplateNotifications}; + + +/** + * Sets `suppressTemplateNotifications` globally, to disable `dom-change` and + * `rendered-item-count` events from `dom-if` and `dom-repeat`. + */ +declare function setSuppressTemplateNotifications(suppress: boolean): void; + +export {setLegacyNoObservedAttributes}; + + +/** + * Sets `legacyNoObservedAttributes` globally, to disable `observedAttributes`. + */ +declare function setLegacyNoObservedAttributes(noObservedAttributes: boolean): void; + +export {setUseAdoptedStyleSheetsWithBuiltCSS}; + + +/** + * Sets `useAdoptedStyleSheetsWithBuiltCSS` globally. + */ +declare function setUseAdoptedStyleSheetsWithBuiltCSS(value: boolean): void; diff --git a/lib/utils/style-gather.d.ts b/lib/utils/style-gather.d.ts new file mode 100644 index 0000000000..ec6a472516 --- /dev/null +++ b/lib/utils/style-gather.d.ts @@ -0,0 +1,101 @@ +// tslint:disable:variable-name Describing an API that's defined elsewhere. + +import {DomModule} from '../elements/dom-module.js'; + +import {resolveCss} from './resolve-url.js'; + +export {stylesFromModules}; + + +/** + * Returns a list of