feat: prepare for TS defs generation [skip ci]

[web-padawan]

Fixes #143

Note, I couldn’t find a way to get correct types for IronResizableBehavior.
Tried @implements {IronResizableBehavior} but that didn’t help.

So, generated TS definitions look like this:

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

import {GestureEventListeners} from '@polymer/polymer/lib/mixins/gesture-event-listeners.js';

import {FlattenedNodesObserver} from '@polymer/polymer/lib/utils/flattened-nodes-observer.js';

import {IronResizableBehavior} from '@polymer/iron-resizable-behavior/iron-resizable-behavior.js';

import {ThemableMixin} from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';

import {ElementMixin} from '@vaadin/vaadin-element-mixin/vaadin-element-mixin.js';

import {html} from '@polymer/polymer/lib/utils/html-tag.js';

import {mixinBehaviors} from '@polymer/polymer/lib/legacy/class.js';

declare class SplitLayoutElement extends
  ElementMixin(
  ThemableMixin(
  GestureEventListeners(
  PolymerElement))) {
  orientation: string|null|undefined;
  ready(): void;
  _processChildren(): void;
}

declare global {
  interface HTMLElementTagNameMap {
    "vaadin-split-layout": SplitLayoutElement;
  }
}

export {SplitLayoutElement};

Question: do we want to have custom types for orientation same as in list-mixin?

[pekam]

Question: do we want to have custom types for orientation same as in list-mixin?

Yes, please. IMO this makes a huge difference in DX.

Also, not sure if nullish values should be accepted, since it has horizontal by default, and in practice it's always oriented one way or the other.
I guess it's fine though, as the code seems to handle it, and I can't think of why it would cause any issues. Setting orientation=null can be considered like removing the explicit configuration and resetting to the default.

[Haprog]

I agree with @pekam. There should be a type like:

export type SplitLayoutOrientation = 'horizontal' | 'vertical';

And orientation property should have @type {!SplitLayoutOrientation}

Since it also has a default value I think it's good to enforce this type in TS defs (even if it doesn't break with null or undefined).

Also I'm not sure why _processChildren() is protected. Seems like it could be @private too.

[web-padawan]

@Haprog @pekam added SplitLayoutOrientation as suggested.

[pekam]

When I run p3 conversion locally:

Loading config from "gen-tsd.json".
Writing type declarations to /home/pekka/dev/vaadin-split-layout
Verifying type declarations
Compilation failed
src/vaadin-split-layout.d.ts:182:16 - error TS2304: Cannot find name 'SplitLayoutOrientation'.

182   orientation: SplitLayoutOrientation;
                   ~~~~~~~~~~~~~~~~~~~~~~

import missing?

[web-padawan]

Thanks, I forgot about "autoImport" for this type. Fixed.

[pekam]

Note, I couldn’t find a way to get correct types for IronResizableBehavior.

As discussed in Slack, if proper solution is not found, let's override notifyResize (the only thing in IronResizableBehavior that might be useful for the user of split-layout) as a workaround to get it into the type definitions.

Otherwise LGTM.

[Haprog]

Note, I couldn’t find a way to get correct types for IronResizableBehavior.

As discussed in Slack, if proper solution is not found, let's override notifyResize (the only thing in IronResizableBehavior that might be useful for the user of split-layout) as a workaround to get it into the type definitions.

Otherwise LGTM.

I think we could maybe use addReferences instead of overriding a method just to get type defs for it.

But I think we also had some Iron behaviours in other already merged TS defs PRs similarly without type info (though I'm not sure if those had any relevant things we'd want to have types for).

[web-padawan]

@pekam added the method.

[pekam]

I think we could maybe use addReferences instead of overriding a method just to get type defs for it.

But I think we also had some Iron behaviours in other already merged TS defs PRs similarly without type info (though I'm not sure if those had any relevant things we'd want to have types for).

From the user's perspective, bloating the API with all the things in IronResizableBehavior might actually be a bad thing.

So IMO the current approach might be the best approach for the goal of these typings; better DX.

@Haprog do you approve?

[Haprog]

@pekam I agree. With addReferences my idea was also to add only the needed (manually written) types, but overriding actually seems simpler at least in this case.

[pekam]

@pekam I agree. With addReferences my idea was also to add only the needed (manually written) types, but overriding actually seems simpler at least in this case.

Ok, I misunderstood then. In a generic case, where there may be any number of props and functions we want to pull from a behavior, this might be the better way to separate them from the code.

For this case, either way is fine for me.

[pekam]

LGTM