Tippyjs: Need a typescript definitely typed file available in npm package

[vairamsvsjdo]

@artyomtrityak
Is there a typescript definitely typed file available for this library?

[renehamburger]

I don't have time for a PR right now, but here is an up-to-date d.ts file for tippy.js I created yesterday. It would be great if it could be included directly in this library (rather than in the DefinitelyTyped repository). It may be possible to take the popper definitions directly from here from the popper package. I adjusted them slightly by adding a namespace.

tippy.d.ts

// Type definitions for tippy.js v2.2.3
// Project: https://atomiks.github.io/tippyjs
// Definitions by: renehamburger <https://github.com/renehamburger>

///<reference path="./popper.d.ts" />

declare namespace Tippy {

  type Placement = 'top' | 'bottom' | 'left' | 'right';

  type Trigger = 'mouseenter' | 'focus' | 'click';

  /** @see https://atomiks.github.io/tippyjs/#all-options */
  interface Options {
    /**
     * Specifies which direction to place the tooltip in relation to the reference
     * element. Add the suffix `-start` or `-end` to shift the placement, e.g. `'top-end'`.
     * Default: 'top'
     */
    placement: Placement;
    /**
     * If `false`, the tooltip won't flip when scrolling. This was unconfigurable and
     * always `true` before v2.2.
     * Default: true
     */
    livePlacement: boolean;
    /**
     * Specifies which type of events will trigger a tooltip to show. Separate each
     * by a space. `mouseenter` is for hovering and touch on mobile, and `focus` is for
     * keyboard navigation. Use `manual` if you want to show/hide the tooltip manually
     * (see https://atomiks.github.io/tippyjs/#methods). You can also use any other event listener,
     * but it won't have the opposite "hide" event.
     * Default: 'mouseenter focus'
     */
    trigger: Trigger | 'manual' | string;
    /**
     * Whenever the `title` attribute on the reference element changes, the tooltip will
     * automatically be updated.
     * Default: false
     */
    dynamicTitle: boolean;
    /**
     * Makes a tooltip interactive, i.e. will not close when the user hovers over or
     * clicks on the tooltip. This lets you create a popover (similar to Bootstrap)
     * when used in conjunction with a `click` trigger.
     * Default: false
     */
    interactive: boolean;
    /**
     * Specifies the size in pixels of the invisible border around an interactive tooltip that will
     * prevent it from closing. Only applies to `mouseenter` triggered tooltips.
     * Default: 2
     */
    interactiveBorder: number;
    /**
     * Specifies the type of transition animation a tooltip has.
     * Default: 'shift-away'
     */
    animation: 'shift-away' | 'shift-toward' | 'perspective' | 'fade' | 'scale';
    /**
     * Adds a material design-esque filling animation. This is disabled if you have `arrow`
     * set to `true`.
     * Default: true
     */
    animateFill: boolean;
    /**
     * Adds an arrow pointing to the reference element. Setting this to `true` disables `animateFill`.
     * Default: false
     */
    arrow: boolean;
    /**
     * Specifies the type of arrow to use. Sharp is a CSS triangle, whereas Round is a
     * custom SVG shape.
     * Default: 'sharp'
     */
    arrowType: 'sharp' | 'round';
    /**
     * Allows you to transform the arrow with a css transform, such as the proportion using scale.
     * Because of flipping, the syntax becomes dynamic. You must use the syntax that gives
     * the desired results for the `top` placement, even if you use a different placement.
     * Only `translate` and `scale` are supported for dynamic syntax.
     *  'scaleX(1.5)' = wider arrow
     *  'scaleX(0.5)' = narrower arrow
     *  'scale(0.5)' = smaller arrow
     *  'scale(1.5)' = larger arrow
     *  'translateY(-5px)' = arrow closer to tooltip
     *  'translateY(5px)' = arrow farther from tooltip
     * Default: ''
     */
    arrowTransform: string;
    /**
     * A CSS selector string used for event delegation. When specified, it will make the
     * element a delegate. The selector should match the child elements that should receive
     * a tooltip.
     * Default: null
     */
    target: string | null;
    /**
     * Specifies how long it takes (in milliseconds) after a show or hide event is fired for a tooltip to
     * begin showing or hiding. Use an array to specify a different show and hide delay,
     * such as `[300, 100]`.
     * Default: 0
     */
    delay: number | [number, number];
    /**
     * Specifies whether the tooltip should flip (the reversing of placement based on the
     * amount of room in the viewport to display a tooltip).
     * Default: true
     */
    flip: boolean;
    /**
     * Specifies the flipping behavior of a tooltip. Based on the amount of room in the
     * viewport, the tooltip will choose which placement to use. For example, 'clockwise'
     * with a placement of 'right' will flip to the bottom when there is not enough room.
     * Default: 'flip'
     */
    flipBehavior: 'flip' | 'clockwise' | 'counterclockwise' | Placement[];
    /**
     * Specifies the maximum width of a tooltip. Ensure you add units, such as px, rem, etc.
     * Default: ''
     */
    maxWidth: string;
    /**
     * Specifies how long (in milliseconds) the transition animation takes to complete. A single number will
     * use the same duration for the show and hide events. Use an array to specify a different
     * show and hide duration, such as `[300, 100]`.
     * Default: [350, 300]
     */
    duration: number | [number, number];
    /**
     * Allows you to add HTML to a tooltip. A string can be used to specify a unique
     * css selector of the template element in the DOM.
     * @see https://atomiks.github.io/tippyjs/#creating-html-templates.
     * Default: false
     */
    html: false | string | Element;
    /**
     * Specifies how large the tooltip is.
     * Default: 'regular'
     */
    size: 'small' | 'regular' | 'large';
    /**
     * Specifies how far away (in px) the tooltip is from its reference element. This contrasts
     * the `offset` option in that it only applies to a single axis and allows tooltips to
     * still be interactive when their trigger is `mouseenter`.
     * Default: 10
     */
    distance: number;
    /**
     * You can create your own easily.
     * @see https://atomiks.github.io/tippyjs/#creating-themes
     * Default: 'dark'
     */
    theme: 'dark';
    /**
     * Offsets a tooltip on a certain axis. Use a string such as '25, 10' to offset it on
     * both the x and y axis. Both in px.
     * Default: 0
     */
    offset: number | string;
    /**
     * Specifies whether to hide a tooltip upon clicking its reference element after
     * hovering over and when clicking elsewhere on the document. For click-triggered
     * tooltips when using `false`, toggle functionality remains unless you use 'persistent'.
     * Default: true
     */
    hideOnClick: true | false | 'persistent';
    /**
     * Specifies whether to allow multiple tooltips open on the page (click trigger only).
     * Default: false
     */
    multiple: boolean;
    /**
     * Specifies whether to follow the user's mouse cursor (mouse devices only).
     * Default: false
     */
    followCursor: boolean;
    /**
     * Modifies the `transition-timing-function` with a cubic bezier to create a "slingshot"
     * intertial effect.
     * Default: false
     */
    inertia: boolean;
    /**
     * Specifies the transition duration (in milliseconds) between flips and when updating a tooltip's
     * position on the document.
     * Default: 350
     */
    updateDuration: number;
    /**
     * Specifies whether the tooltip should stick to its reference element when it's
     * showing (for example, if the element is animated/moves).
     * Default: false
     */
    sticky: boolean;
    /**
     * Specifies which element the tooltip popper is appended to. Use a function which
     * returns an Element for more advanced use cases.
     * Default:  document.body
     */
    appendTo: Element | (() => void);
    /**
     * Specifies the z-index of the tooltip popper.
     * Default: 9999
     */
    zIndex: number;
    /**
     * Changes the trigger behavior on touch devices. It will change it from a tap to
     * show and tap off to hide, to a tap and hold to show, and a release to hide.
     * Default: false
     */
    touchHold: boolean;
    /**
     * Disables `data-tippy-*` attribute options to make initial instantiation time faster.
     * Default: false
     */
    performance: boolean;
    /**
     * Callback function triggered when a tooltip begins to show.
     */
    onShow: (this: HTMLElement, instance: Instance) => void;
    /**
     * Callback function triggered when a tooltip has fully transitioned in.
     */
    onShown: (this: HTMLElement, instance: Instance) => void;
    /**
     * Callback function triggered when a tooltip begins to hide.
     */
    onHide: (this: HTMLElement, instance: Instance) => void;
    /**
     * Callback function triggered when a tooltip has fully transitioned out.
     */
    onHidden: (this: HTMLElement, instance: Instance) => void;
    /**
     * Delays showing the tooltip until you manually invoke `show()`.
     */
    wait: (this: HTMLElement, show: () => void, triggeringEvent: Event) => void;
    /**
     * By default, the popper instance for a tooltip is not created until it is shown
     * for the first time in order to optimize performance. In some cases this may cause
     * issues, so you can specify it to be created when you init with `tippy()`.
     * Safari seems to stutter slightly when the tooltip is shown for the first time.
     * Certain CSS effects may also cause the transition to stutter on the first show.
     * For these certain cases, you may want to set this option to `true`.
     * Default: false
     */
    createPopperInstanceOnInit: boolean;

    /**
     * Allows more control over tooltip positioning and behavior.
     * @see https://popper.js.org/popper-documentation.html#new_Popper_new
     * Default: {}
     */
    popperOptions: Popper.Options;
  }

  type Selector = string | Element | NodeList | Popper.ReferenceObject

  interface Object {
    /** The target references to be given tooltips. */
    selector: Selector | Selector[];
    /** Array of all Tippy instances that were created. */
    tooltips: Instance[];
    /** Default + instance options merged. */
    options: Options;
    /** Method to destroy all tooltips that were created (all Tippy instances inside `tooltips`) */
    destroyAll: () => void;
  }

  interface Instance {
    /** The ID of the instance. */
    id: number;
    /** The content of the tooltip (if not HTML). */
    title: string;
    /** The popper element which contains the tooltip element and content. */
    popper: Element;
    /** The Popper instance. Not created until the tooltip is shown for the
     * first time, unless specified otherwise. */
    popperInstance: Popper.Popper | null;
    /** The element you gave the tooltip to. */
    reference: Element;
    /** Array of objects containing the event type and handler which were bound to the reference element based on the `trigger` option. */
    listeners: { event: Trigger | string, handler: () => void }[];
    /** Default + instance + individual options merged together. */
    options: Options;
    /**
     * Object containing boolean values about the state of the tooltip.
     *  `destroyed` - has the instance been destroyed?
     *  `enabled` - is the tooltip enabled?
     *  `visible` - is the tooltip currently visible and not transitioning out?
    */
    state: { destroyed: boolean, enabled: boolean, visible: boolean };
  }
}

declare function tippy(selector: Tippy.Selector, options?: Partial<Tippy.Options>): Tippy.Object;

popper.d.ts (taken from here with slight adjustments)

// Type definitions for popper.js 1.10
// Project: https://github.com/FezVrasta/popper.js/
// Definitions by: edcarroll <https://github.com/edcarroll>, ggray <https://github.com/giladgray>, rhysd <https://rhysd.github.io>, joscha <https://github.com/joscha>, seckardt <https://github.com/seckardt>, marcfallows <https://github.com/marcfallows>

// This file only declares the public portions of the API.
// It should not define internal pieces such as utils or modifier details.

declare namespace Popper {
  type Position = 'top' | 'right' | 'bottom' | 'left';

  type Placement = 'auto-start'
    | 'auto'
    | 'auto-end'
    | 'top-start'
    | 'top'
    | 'top-end'
    | 'right-start'
    | 'right'
    | 'right-end'
    | 'bottom-end'
    | 'bottom'
    | 'bottom-start'
    | 'left-end'
    | 'left'
    | 'left-start';

  type Boundary = 'scrollParent' | 'viewport' | 'window';

  type ModifierFn = (data: Data, options: Object) => Data;

  interface BaseModifier {
    order?: number;
    enabled?: boolean;
    fn?: ModifierFn;
  }

  interface Modifiers {
    shift?: BaseModifier;
    offset?: BaseModifier & {
      offset?: number | string,
    };
    preventOverflow?: BaseModifier & {
      priority?: Position[],
      padding?: number,
      boundariesElement?: Boundary | Element,
      escapeWithReference?: boolean
    };
    keepTogether?: BaseModifier;
    arrow?: BaseModifier & {
      element?: string | Element,
    };
    flip?: BaseModifier & {
      behavior?: 'flip' | 'clockwise' | 'counterclockwise' | Position[],
      padding?: number,
      boundariesElement?: Boundary | Element,
    };
    inner?: BaseModifier;
    hide?: BaseModifier;
    applyStyle?: BaseModifier & {
      onLoad?: Function,
      gpuAcceleration?: boolean,
    };
    computeStyle?: BaseModifier & {
      gpuAcceleration?: boolean;
      x?: 'bottom' | 'top',
      y?: 'left' | 'right'
    };

    [name: string]: (BaseModifier & Record<string, any>) | undefined;
  }

  interface Offset {
    top: number;
    left: number;
    width: number;
    height: number;
  }

  interface Data {
    instance: Popper;
    placement: Placement;
    originalPlacement: Placement;
    flipped: boolean;
    hide: boolean;
    arrowElement: Element;
    styles: CSSStyleDeclaration;
    boundaries: Object;
    offsets: {
      popper: Offset,
      reference: Offset,
      arrow: {
        top: number,
        left: number,
      },
    };
  }

  interface Options {
    placement?: Placement;
    positionFixed: boolean;
    eventsEnabled?: boolean;
    modifiers?: Modifiers;
    removeOnDestroy?: boolean;

    onCreate?(data: Data): void;

    onUpdate?(data: Data): void;
  }

  interface ReferenceObject {
    clientHeight: number;
    clientWidth: number;

    getBoundingClientRect(): ClientRect;
  }

  class Popper {
    static modifiers: (BaseModifier & { name: string })[];
    static placements: Placement[];
    static Defaults: Options;

    options: Options;

    constructor(reference: Element | ReferenceObject, popper: Element, options?: Options);

    destroy(): void;

    update(): void;

    scheduleUpdate(): void;

    enableEventListeners(): void;

    disableEventListeners(): void;
  }
}

[gordinmitya]

@renehamburger Thank you! But could you provide example where should I put this files in my project? I tried with "src/@types/tippy.js/index.d.ts" – doesn't work for me.

[vairamsvsjdo]

@gordinmitya @renehamburger It's mentioned here on how to include part of the package 👍 https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html

[renehamburger]

I've just realised that publishing these typings to DefinitelyTyped repository is actually preferred if the module is _not_ written in TypeScript. @vairamsvsjdo, by any chance, would you have time to do this?

[vairamsvsjdo]

@renewhamburger, That definition over there will get out of sync very soon. Whereas having the definition and few test scripts could keep the binding here. Or we have to create a webhook to a fork created at atomiks that will create a PR for when they type definition auto generated using script. More tedium.

I encourage to generate the interface once, start any public method updates with update of the interface first thereafter.

[DrMabuse23]

export type TippyAnimations = 'shift-away' | 'shift-toward' | 'fade' | 'scale' | 'perspective';
export type TippyFlipBehavior = 'flip' | 'clockwise' | 'counterclockwise';
export type TippyArrowType = 'sharp' | 'round';
export type TippyPlacement =
  | 'top'
  | 'bottom'
  | 'left'
  | 'right'
  | 'top-start'
  | 'top-end'
  | 'left-end'
  | 'left-start'
  | 'right-end'
  | 'right-start'
  | 'bottom-end'
  | 'bottom-start';
export type TippySize = 'regular' | 'small' | 'large';
export type TippyTriggerType = 'mouseenter focus' | 'click' | 'manual';

export interface TyppiOptions {
  // Available v2.3+ - If boolean; HTML can be injected in the title attribute
  allowTitleHTML: boolean;

  // If boolean; the tooltip's background fill will be animated (material effect)
  animateFill: boolean;

  // The type of animation to use
  animation: TippyAnimations;

  // Which element to append the tooltip to
  appendTo: HTMLElement; // Element or Function that returns an element

  // Whether to display the arrow. Disables the animateFill option
  arrow: boolean;

  // Transforms the arrow element to make it larger, wider, skinnier, offset, etc.
  arrowTransform: string; // CSS syntax: 'scaleX(0.5)', 'scale(2)', 'translateX(5px)' etc.

  // The type of arrow. 'sharp' is a triangle and 'round' is an SVG shape
  arrowType: TippyArrowType;

  // The tooltip's Popper instance is not created until it is shown for the first
  // time by default to increase performance
  createPopperInstanceOnInit: boolean;

  // Delays showing/hiding a tooltip after a trigger event was fired, in ms
  delay: number | number[]; // Number or Array [show, hide] e.g. [100, 500]

  // How far the tooltip is from its reference element in pixels
  distance: number;

  // The transition duration
  duration: number[]; // Number or Array [show, hide]

  // If boolean; whenever the title attribute on the reference changes, the tooltip
  // will automatically be updated
  dynamicTitle: boolean;

  // If boolean; the tooltip will flip (change its placement) if there is not enough
  // room in the viewport to display it
  flip: boolean;

  // The behavior of flipping. Use an array of placement strings, such as
  // ['right', 'bottom'] for the tooltip to flip to the bottom from the right
  // if there is not enough room
  flipBehavior: TippyFlipBehavior;

  // Whether to follow the user's mouse cursor or not
  followCursor: boolean;

  // Upon clicking the reference element, the tooltip will hide.
  // Disable this if you are using it on an input for a focus trigger
  // Use 'persistent' to prevent the tooltip from closing on body OR reference
  // click
  hideOnClick: boolean | 'persistent'; // boolean; 'persistent'

  // Specifies that the tooltip should have HTML content injected into it.
  // A selector string indicates that a template should be cloned, whereas
  // a DOM element indicates it should be directly appended to the tooltip
  html: boolean; // 'selector', DOM Element

  // Adds an inertial slingshot effect to the animation. TIP! Use a show duration
  // that is twice as long as hide, such as `duration: [600, 300]`
  inertia: boolean;

  // If boolean; the tooltip becomes interactive and won't close when hovered over
  // or clicked
  interactive: boolean;

  // Specifies the size in pixels of the invisible border around an interactive
  // tooltip that prevents it from closing. Useful to prevent the tooltip
  // from closing from clumsy mouse movements
  interactiveBorder: number;

  // Available v2.2+ - If boolean; the tooltip won't update its position (or flip)
  // when scrolling
  livePlacement: boolean;

  // The maximum width of the tooltip. Add units such as px or rem
  // Avoid exceeding 300px due to mobile devices, or don't specify it at all
  maxWidth: string;

  // If boolean; multiple tooltips can be on the page when triggered by clicks
  multiple: boolean;

  // Offsets the tooltip popper in 2 dimensions. Similar to the distance option,
  // but applies to the parent popper element instead of the tooltip
  offset: string; // '50, 20' = 50px x-axis offset, 20px y-axis offset

  // Callback invoked when the tooltip fully transitions out
  onHidden: (instance) => void;

  // Callback invoked when the tooltip begins to transition out
  onHide: (instance) => void;

  // Callback invoked when the tooltip begins to transition in
  onShow: (instance) => void;

  // Callback invoked when the tooltip has fully transitioned in
  onShown: (instance) => void;

  // If boolean; data-tippy-* attributes will be disabled for increased performance
  performance: boolean;

  // The placement of the tooltip in relation to its reference
  placement: TippyPlacement;

  // Popper.js options. Allows more control over tooltip positioning and behavior
  popperOptions: {};

  // The size of the tooltip
  size: TippySize;

  // If boolean; the tooltip's position will be updated on each animation frame so
  // the tooltip will stick to its reference element if it moves
  sticky: boolean;

  // Available v2.1+ - CSS selector string used for event delegation
  target: any; // e.g. '.className'

  // The theme, which is applied to the tooltip element as a class name, i.e.
  // 'dark-theme'. Add multiple themes by separating each by a space, such as
  // 'dark custom'
  theme: string;

  // Changes trigger behavior on touch devices. It will change it from a tap
  // to show and a tap off to hide, to a touch-and-hold to show, and a release
  // to hide
  touchHold: boolean;

  // The events on the reference element which cause the tooltip to show
  trigger: TippyTriggerType;

  // Transition duration applied to the Popper element to transition between
  // position updates
  updateDuration: number;

  // The z-index of the popper
  zIndex: number;
}

only options declaration, may anyone can have a look on TippyTriggerType please looks for me i something missing thx!!

[DrMabuse23]

and btw thx for this wonderfull tool 💯

[smajl]

If anyone is interested, this is my enhanced update (it _should_ cover everything) for most recent version 3.0.2. I'm leaving out JSDoc for the sake of brevity. I you don't use standalone version like me, then probably replace tippy.js/dist/tippy.standalone.js with just tippy.js and probably install npm i -D popper.js just to properly import typings from it.

// Type definitions for tippy.js v3.0.2
// Project: https://atomiks.github.io/tippyjs

declare module "tippy.js/dist/tippy.standalone.js" {
    import Popper from "popper.js";

    export type BasicPlacement = "top" | "bottom" | "left" | "right";

    export type Placement =
        | BasicPlacement
        | "top-start" | "top-end" | "bottom-start" | "bottom-end"
        | "left-start" | "left-end" | "right-start" | "right-end";

    export type Content = string | Element;

    export type Selector = string | Element | NodeList | Popper.ReferenceObject;

    export interface Options {
        a11y?: boolean;
        allowHTML?: boolean;
        animateFill?: boolean;
        animation?: "fade" | "scale" | "shift-toward" | "perspective" | "shift-away";
        appendTo?: Element | ((ref: Element) => Element);
        arrow?: boolean;
        arrowType?: "sharp" | "round";
        arrowTransform?: string;
        content?: Content;
        delay?: number | [number, number];
        duration?: number | [number, number];
        distance?: number;
        flip?: boolean;
        flipBehavior?: "flip" | Placement[];
        followCursor?: boolean | "vertical" | "horizontal";
        hideOnClick?: boolean | "toggle";
        inertia?: boolean;
        interactive?: boolean;
        interactiveBorder?: number;
        interactiveDebounce?: number;
        lazy?: boolean;
        livePlacement?: boolean;
        multiple?: boolean;
        offset?: number | string;
        onHidden?(instance: Instance): void;
        onHide?(instance: Instance): void;
        onShow?(instance: Instance): void;
        onShown?(instance: Instance): void;
        performance?: boolean;
        placement?: ExtendedPlacement;
        popperOptions?: Popper.PopperOptions;
        shouldPopperHideOnBlur?: (event: FocusEvent) => boolean;
        showOnInit?: boolean;
        size?: "small" | "regular" | "large";
        sticky?: boolean;
        target?: string;
        theme?: string;
        touch?: boolean;
        touchHold?: boolean;
        trigger?: "mouseenter" | "focus" | "click" | "manual";
        updateDuration?: number;
        wait?(instance: Instance, event: Event): void;
        zIndex?: number;
    }

    export interface Instance {
        clearDelayTimeouts(): void;
        destroy(): void;
        disable(): void;
        enable(): void;
        hide(duration?: number): void;
        id: number;
        popper: Element;
        popperChildren: {
            arrow: Element | null;
            backdrop: Element | null;
            content: Element | null;
            tooltip: Element | null;
        };
        popperInstance: Popper.Popper | null;
        props: Options;
        reference: Element;
        set(options: Options): void;
        setContent(content: Content): void;
        show(duration?: number): void;
        state: {
            isEnabled: boolean;
            isVisible: boolean;
            isDestroyed: boolean;
        };
    }

    export interface Collection {
        destroyAll(): void;
        instances: Instance[];
        props: Options;
        targets: Selector | Selector[];
    }

    interface Tippy {
        (selector: Selector, options?: Options): Collection;
        readonly defaults: Options;
        readonly version: string;
        disableAnimations(): void;
        hideAllPoppers(): void;
        one(selector: Selector, options?: Options): Instance;
        setDefaults(options: Options): void;
        useCapture(): void;
    }

    const tippy: Tippy;
    export default tippy;
}

Drop this into your project and use e.g. like:

import tippy, {Instance, Options} from "tippy.js/dist/tippy.standalone.js";

const el = ...;
const options: Options = {...};
const tippyInstance: Instance = tippy.one(el, options);

BTW, big shout out to @atomiks for v3! 👍

[atomiks]

Thank you so much @smajl ❤️ ! I will definitely get around to publishing this with the package in the next version

Edit: Could you make a PR for this?

[KubaJastrz]

I believe this issue can be closed now, as #329 is merged.