Typescript JQueryUI types and utilities

Provides Typescript types for jQuery UI modules and widgets.

Also provides a decorator for creating new jQuery UI as vanilla TS classes.

Preliminary warning

This package is the result of some unavoidable requirements of a private project.

jQuery UI seems pretty dead and lacks (and have lack for years) support for modern JS development tools including (but not limited to) source maps of minimized files or ESM/CommonJS modules support, witch prevent usage of tools like Vite.

It provided a valuable UI framework for years. Nowadays has been superseeded by more modern tools and approaches.

My opinion right now (2025-01) is this:

Get rid of jQuery UI and/or jQuery and adopt modern tools and frameworks when Web API is not enought.

jQuery UI Typescript types

Add development dependency with @orne/jqueryui-ts-widgets to have typed imports of jQuery UI packages and modules.

jQuery UI widgets as classes

To define new jQuery UI widgets as classes Typescript experimental support for decorators must be enabled:

1{
2    "compilerOptions": {
3      ...
4      "experimentalDecorators": true,
5      ...
6    }
7}

Once decorators are enabled jQuery UI widgets can be defined using Typescript classes:

1import 'jquery-ui/ui/widget';
2import { JQueryWidget } from '@orne/jqueryui-ts-widgets';
3
4/**
5 * Interface of widget styling classes.
6 */
7export type Classes = object & {
8    // Extra widget styling classes
9    "myns-mywidget-fancyclass"?: string | null;
10}
11/**
12 * Interface of widget options.
13 *
14 * @typeParam C The widget classes.
15 */
16export interface Options<C extends Classes = Classes>
17extends JQueryUI.Widget.Options<C> {
18    // Extra widget options
19    myTypedOption: boolean;
20}
21/**
22 * Interface of widget API.
23 *
24 * @typeParam This The JQuery instance.
25 */
26export type API<This extends JQuery<any>> =
27    JQueryUI.Widget.API<This, MyWidget> &
28    JQueryUI.Widget.API.Methods<This, MyWidget> &
29    {
30      /**
31       * Public widget method.
32       */
33      (methodName: 'myMethod'): This,
34    };
35/**
36 * The widget class.
37 * Note the `@JQueryWidget` decorator with namespace and widget name.
38 *
39 * @typeParam O The widget options.
40 */
41@JQueryWidget({ namespace: 'myNs', name: "myWidget" })
42export class MyWidget<O extends Options<any> = Options>
43extends Widget<O> {
44    public constructor(options?: Partial<O>, element?: JQuery<any>) {
45      super(options, element);
46    }
47    protected _init(): void {
48      super._init();
49    }
50    /**
51     * Public widget method.
52     */
53    public myMethod(): void {
54    }
55}
56declare global {
57  interface JQuery<TElement = HTMLElement> {
58    myWidget: API<this>;
59  }
60  interface JQueryStatic {
61    myNs: {
62      myWidget: typeof MyWidget;
63    };
64  }
65}

Widget API declaration can be ommited and extracted from widget type declaration, using JQueryUI.Widget.API.From. However, this shortcut losts public method's documentation.

1import 'jquery-ui/ui/widget';
2import { JQueryWidget } from '@orne/jqueryui-ts-widgets';
3
4/**
5 * Interface of widget styling classes.
6 */
7export type Classes = object & {
8    // Extra widget styling classes
9    "myns-mywidget-fancyclass"?: string | null;
10}
11/**
12 * Interface of widget options.
13 *
14 * @typeParam C The widget classes.
15 */
16export interface Options<C extends Classes = Classes>
17extends JQueryUI.Widget.Options<C> {
18    // Extra widget options
19    myTypedOption: boolean;
20}
21/**
22 * The widget class.
23 * Note the `@JQueryWidget` decorator with namespace and widget name.
24 *
25 * @typeParam O The widget options.
26 */
27@JQueryWidget({ namespace: 'myNs', name: "myWidget" })
28export class MyWidget<O extends Options<any> = Options>
29extends Widget<O> {
30    public constructor(options?: Partial<O>, element?: JQuery<any>) {
31      super(options, element);
32    }
33    protected _init(): void {
34      super._init();
35    }
36    /**
37     * Public widget method.
38     */
39    public myMethod(): void {
40    }
41}
42declare global {
43  interface JQuery<TElement = HTMLElement> {
44    myWidget: JQueryUI.Widget.API.From<this, MyWidget>;
45  }
46  interface JQueryStatic {
47    myNs: {
48      myWidget: typeof MyWidget;
49    };
50  }
51}

Events

To declare events triggered by widgets define the event type specifying the full event name and add it to the JQueryUI.Widget.Event.Mappings interface. This will automatically add signatures to JQuery.on() and JQuery.one() for the defined event type:

1export type MyEvent<TElement = HTMLElement> = JQueryUI.Widget.Event<"myFancyEvent", TElement>;
2declare namespace JQueryUI {
3    namespace Widget {
4        namespace Event {
5            interface Mappings<TElement = HTMLElement> {
6                'myFancyEvent': MyEvent<TElement>;
7            }
8        }
9    }
10}

JQuery UI widgets allow triggering events with data associated to the event. To provide data type information to event consumers add to the JQueryUI.Widget.Event.Mappings interface a definition including event type and event data type:

1export type MyEvent<TElement = HTMLElement> = JQueryUI.Widget.Event<"myFancyEvent", TElement>;
2export interface MyEventData {
3  ...
4  test: boolean;
5}
6interface MyEventDef<TElement = HTMLElement> {
7  event: MyEvent<TElement>,
8  ui: MyEventData
9}
10declare namespace JQueryUI {
11    namespace Widget {
12        namespace Event {
13            interface Mappings<TElement = HTMLElement> {
14                'myFancyEvent': MyEventDef<TElement>;
15            }
16        }
17    }
18}
19
20// Allows typed access to event data:
21$('#my-elem').on('myFancyEvent', (event, data) => {
22  // Typed data
23  data.test == true
24});

Existing widgets ambient types

To add typescript types for existing JQuery UI widgets add ambient widget namespace declaration and extend JQueryStatic interface with namespace:

1/// <reference types="jquery" />
2declare namespace AmbientWidgets {
3  interface WidgetsNamespace {
4  }
5}
6declare global {
7  interface JQueryStatic {
8    ambientNs: WidgetsNamespace;
9  }
10}

For each widget in the namespace add ambient module declaration for widget module, defining widget classes, options, widget API and, if required, events and extending JQuery interface as previously explained:

1/// <reference types="jquery" />
2/// <reference types="jquery-ui" />
3/// <reference types="./namespace" />
4export class AmbientWidget<O extends AmbientWidget.Options<any> = AmbientWidget.Options>
5extends jQuery.Widget<O> {
6  public someMethod(): void;
7}
8export namespace AmbientWidget {
9  type Classes = object & {
10    // Extra widget styling classes
11    "myns-mywidget-fancyclass"?: string | null;
12  }
13  interface Options<C extends Classes = Classes>
14  extends JQueryUI.Widget.Options<C> {
15      // Extra widget options
16      myTypedOption: boolean;
17  }
18}
19declare namespace AmbientWidgets {
20  interface WidgetsNamespace {
21    ambientWidget: typeof AmbientWidget;
22  }
23}
24interface JQuery<TElement = HTMLElement> {
25  ambientwidget: JQueryUI.Widget.API.From<this, AmbientWidget>;
26}
27declare module 'fancylib/my-ambient-widget' {
28  import 'jquery';
29  import 'jquery-ui';
30  // If module exports widget
31  export default jQuery.ambientNs.ambientWidget;
32}