or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

data-binding.mdelement-creation.mdgesture-system.mdindex.mdlegacy-support.mdmixins.mdproperty-system.mdutilities.md
tile.json

tessl/npm-polymer--polymer

JavaScript library for building web components with data binding, property observation, templating, and declarative element definition.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@polymer/polymer@3.5.x

To install, run

npx @tessl/cli install tessl/npm-polymer--polymer@3.5.0

index.mddocs/

Polymer

Polymer is a JavaScript library for building web components with features like data binding, property observation, declarative templating, and lifecycle management. It provides both modern ES6 module-based APIs and legacy compatibility for existing applications.

Package Information

  • Package Name: @polymer/polymer
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install @polymer/polymer

Core Imports

Modern ES6 modules (recommended):

import { PolymerElement, html } from '@polymer/polymer/polymer-element.js';

For CommonJS:

const { PolymerElement, html } = require('@polymer/polymer/polymer-element.js');

Legacy support:

import { Polymer, html } from '@polymer/polymer/polymer-legacy.js';

Basic Usage

import { PolymerElement, html } from '@polymer/polymer/polymer-element.js';

class MyElement extends PolymerElement {
  static get is() { return 'my-element'; }
  
  static get template() {
    return html`
      <div>Hello [[name]]!</div>
    `;
  }
  
  static get properties() {
    return {
      name: {
        type: String,
        value: 'World'
      }
    };
  }
}

customElements.define(MyElement.is, MyElement);

Architecture

Polymer is built around several key architectural concepts:

  • Element Base Class: PolymerElement provides core functionality for custom elements
  • Mixin System: Composable mixins add specific capabilities like property effects and templating
  • Template System: HTML template literals with data binding and conditional rendering
  • Built-in Elements: Pre-built elements for common patterns (dom-repeat, dom-if, etc.)
  • Property System: Declarative property configuration with automatic attribute synchronization
  • Data Binding: Two-way data binding with property path observation
  • Legacy Support: Full backward compatibility with Polymer 1.x and 2.x applications

Capabilities

Element Creation

Core functionality for creating custom elements with the modern Polymer API, including the base class and template system.

class PolymerElement extends HTMLElement {
  static get is(): string;
  static get template(): HTMLTemplateElement;
  static get properties(): PropertyDeclarations;
  static get observers(): string[];
  
  connectedCallback(): void;
  disconnectedCallback(): void;
  ready(): void;
  updateStyles(properties?: StyleProperties): void;
  resolveUrl(url: string, base?: string): string;
}

function html(strings: TemplateStringsArray, ...values: any[]): HTMLTemplateElement;

const version: string;

Element Creation

Property System

Declarative property configuration with automatic attribute synchronization, change notification, and computed properties.

interface PropertyDeclaration {
  type?: PropertyType;
  value?: any | (() => any);
  reflectToAttribute?: boolean;
  readOnly?: boolean;
  notify?: boolean;
  computed?: string;
  observer?: string;
}

interface PropertyDeclarations {
  [property: string]: PropertyDeclaration;
}

type PropertyType = StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor;

Property System

Data Binding & Templates

Template system with data binding, conditional rendering, and list iteration capabilities.

// Built-in template elements
class DomIf extends PolymerElement {
  if: boolean;
  restamp: boolean;
}

class DomRepeat extends PolymerElement {
  items: any[];
  as: string;
  indexAs: string;
  sort: (a: any, b: any) => number;
  filter: (item: any) => boolean;
  observe: string;
  delay: number;
  renderedItemCount: number;
  
  render(): void;
  itemForElement(el: Element): any;
  indexForElement(el: Element): number;
}

Data Binding & Templates

Mixins

Composable mixins that provide specific functionality to elements, following a modular architecture pattern.

function ElementMixin<T extends Constructor<HTMLElement>>(base: T): T & ElementMixinConstructor;
function PropertyEffections<T extends Constructor<HTMLElement>>(base: T): T & PropertyEffectsConstructor;
function PropertiesMixin<T extends Constructor<HTMLElement>>(base: T): T & PropertiesMixinConstructor;
function TemplateStamp<T extends Constructor<HTMLElement>>(base: T): T & TemplateStampConstructor;
function GestureEventListeners<T extends Constructor<HTMLElement>>(base: T): T & GestureEventListenersConstructor;

Mixins

Utility Functions

Helper functions for common operations including path manipulation, async operations, debouncing, and DOM utilities.

// Path utilities
function get(object: any, path: string): any;
function set(object: any, path: string, value: any): void;
function isPath(path: string): boolean;

// Async utilities
const timeOut: AsyncInterface;
const animationFrame: AsyncInterface;
const microTask: AsyncInterface;

// Debouncing
class Debouncer {
  constructor(asyncModule: AsyncInterface);
  debounce(fn: () => void): void;
  cancel(): void;
  flush(): void;
}

Utility Functions

Gesture System

Cross-platform gesture event handling with support for mouse, touch, and pointer events, including gesture recognizers and event management utilities.

function addListener(node: Element, evType: string, handler: (event: Event) => void): void;
function removeListener(node: Element, evType: string, handler: (event: Event) => void): void;
function register(recognizer: GestureRecognizer): void;
function setTouchAction(node: Element, value: string): void;
function prevent(evName: string): void;
function deepTargetFind(x: number, y: number): Element | null;

const gestures: {[eventType: string]: GestureRecognizer};
const recognizers: GestureRecognizer[];

Gesture System

Legacy Support

Legacy Polymer 1.x/2.x compatibility APIs for existing applications that need to migrate gradually.

function Polymer(prototype: PolymerInit): PolymerElementConstructor;

interface PolymerInit {
  is: string;
  template?: HTMLTemplateElement | string;
  properties?: PropertyDeclarations;
  observers?: string[];
  behaviors?: Behavior[];
  
  // Lifecycle methods
  created?(): void;
  ready?(): void;
  attached?(): void;
  detached?(): void;
}

const Base: PolymerLegacyElementBase;

Legacy Support

Types

type Constructor<T = {}> = new (...args: any[]) => T;

interface StyleProperties {
  [property: string]: string;
}

interface AsyncInterface {
  run(fn: () => void, delay?: number): number;
  cancel(handle: number): void;
}

interface ElementMixinConstructor {
  new(): ElementMixin;
  polymerElementVersion: string;
  template: HTMLTemplateElement;
  importPath: string;
  createProperties(props: PropertyDeclarations): void;
  createObservers(observers: string[], dynamicFns: object): void;
  finalize(): void;
}

interface GestureRecognizer {
  name?: string;
  deps?: string[];
  flow?: {
    start: string[];
    end: string[];
  };
  emits?: string[];
  reset(): void;
  mousedown?(event: MouseEvent): boolean | void;
  mousemove?(event: MouseEvent): boolean | void;
  mouseup?(event: MouseEvent): boolean | void;
  touchstart?(event: TouchEvent): boolean | void;
  touchmove?(event: TouchEvent): boolean | void;
  touchend?(event: TouchEvent): boolean | void;
  click?(event: MouseEvent): boolean | void;
}

interface Behavior {
  properties?: PropertyDeclarations;
  observers?: string[];
  listeners?: {[key: string]: string};
  hostAttributes?: {[key: string]: any};
  behaviors?: Behavior[];
  [key: string]: any;
}

interface PolymerLegacyElementBase {
  create(proto: any, api: any): PolymerElementConstructor;
  mixin(target: any, source: any): any;
  chainObject(object: any, inherited: any): any;
}

interface CSSResult {
  cssText: string;
  styleSheet?: CSSStyleSheet;
}

interface PolymerElementConstructor {
  new (): HTMLElement;
  is?: string;
  extends?: string;
  properties?: PropertyDeclarations;
  observers?: string[];
  template?: string | HTMLTemplateElement | null;
}

interface ElementMixin extends HTMLElement {
  $: {[key: string]: Element};
  root: ShadowRoot | HTMLElement;
  importPath: string;
  rootPath: string;
  updateStyles(properties?: StyleProperties): void;
  resolveUrl(url: string, base?: string): string;
  ready(): void;
}