Skip to content

Commit

Permalink
feat: add typescript types generated from jsdoc
Browse files Browse the repository at this point in the history
  • Loading branch information
alangdm committed Mar 10, 2021
1 parent 2acfb2f commit f14032f
Show file tree
Hide file tree
Showing 8 changed files with 267 additions and 20 deletions.
24 changes: 13 additions & 11 deletions custom-elements.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,6 @@
"path": "./src\\HeliumAnimatedPages.js",
"description": "A light spiritual successor to neon-animated-pages using only css animations",
"attributes": [
{
"name": "animationClasses",
"description": "This property is required for the animations to run, it maps which\nanimations to run depending on what the transition will be.\n\nIf the property isn't set the transitions will run without animations.\n\nThe properties of this object each represent a different transition rule.\nThe transition rules can be of one of the following types.\nThe rule types are listed in order of priority.\nAll the examples assume you have at least two pages identified respectively as `page1` and `page2`.\n- `from_to`: The most specific kind of transition.\n It defines an animation which will run when both the newly selected\n page and the previously selected page match with the rule. For\n example: `page1_page2`.\n- `_to `: This is a special subtype of the previous rule applied when there was no\n previously selected page. For example: `_page1`\n- `*_to`: It defines an animation that will run whenever the newly selected page\n matches this rule. This rule will ignore the previously selected page.\n For example: `*_page2`\n- `from_*`: It defines an animation that will run whenever the previously selected page\n matches this rule. This rule will ignore the newly selected page.\n For example: `page1_*`\n- `default`: It defines an animation which will run when none of the\n other rules apply.\n\nPlease bear in mind 'undefined' and 'null' are not valid identifiers.\n\nAll transition rules must be an object with the following format:\n```javascript\n{\n in: 'inbound_css_animation_class_name',\n out: 'outbound_css_animation_class_name'\n}\n```",
"type": "Object.<string, {in: string, out: string}>"
},
{
"name": "selected",
"description": "The numerical index or the value of the attribute of the currently\nselected node. It's only the index if `attrForSelected` isn't defined.\nModifying this property achieves the same results as invoking\nthe `select(next)` method.\nWarning: using this property together with any of the selection\nmethods might cause state inconsistencies.",
Expand All @@ -21,15 +16,15 @@
"description": "If set, it will be the name of the attribute used to identify\nthe pages added inside the instance of `helium-animated-pages`.\nOtherwise, the index of the children page will be used. Any page\nwithout this attribute will be ignored. If two pages with\nthe same value for the attribute exist, only the first one will be selectable.",
"type": "string",
"default": "\"\""
}
],
"properties": [
},
{
"name": "animationClasses",
"attribute": "animationClasses",
"description": "This property is required for the animations to run, it maps which\nanimations to run depending on what the transition will be.\n\nIf the property isn't set the transitions will run without animations.\n\nThe properties of this object each represent a different transition rule.\nThe transition rules can be of one of the following types.\nThe rule types are listed in order of priority.\nAll the examples assume you have at least two pages identified respectively as `page1` and `page2`.\n- `from_to`: The most specific kind of transition.\n It defines an animation which will run when both the newly selected\n page and the previously selected page match with the rule. For\n example: `page1_page2`.\n- `_to `: This is a special subtype of the previous rule applied when there was no\n previously selected page. For example: `_page1`\n- `*_to`: It defines an animation that will run whenever the newly selected page\n matches this rule. This rule will ignore the previously selected page.\n For example: `*_page2`\n- `from_*`: It defines an animation that will run whenever the previously selected page\n matches this rule. This rule will ignore the newly selected page.\n For example: `page1_*`\n- `default`: It defines an animation which will run when none of the\n other rules apply.\n\nPlease bear in mind 'undefined' and 'null' are not valid identifiers.\n\nAll transition rules must be an object with the following format:\n```javascript\n{\n in: 'inbound_css_animation_class_name',\n out: 'outbound_css_animation_class_name'\n}\n```",
"type": "Object.<string, {in: string, out: string}>"
},
"type": "AnimationClasses",
"default": "{}"
}
],
"properties": [
{
"name": "isAnimating",
"description": "This property will get the state of the animation. Whether it's currently in the middle of an animation or not.",
Expand All @@ -52,6 +47,13 @@
"description": "If set, it will be the name of the attribute used to identify\nthe pages added inside the instance of `helium-animated-pages`.\nOtherwise, the index of the children page will be used. Any page\nwithout this attribute will be ignored. If two pages with\nthe same value for the attribute exist, only the first one will be selectable.",
"type": "string",
"default": "\"\""
},
{
"name": "animationClasses",
"attribute": "animationClasses",
"description": "This property is required for the animations to run, it maps which\nanimations to run depending on what the transition will be.\n\nIf the property isn't set the transitions will run without animations.\n\nThe properties of this object each represent a different transition rule.\nThe transition rules can be of one of the following types.\nThe rule types are listed in order of priority.\nAll the examples assume you have at least two pages identified respectively as `page1` and `page2`.\n- `from_to`: The most specific kind of transition.\n It defines an animation which will run when both the newly selected\n page and the previously selected page match with the rule. For\n example: `page1_page2`.\n- `_to `: This is a special subtype of the previous rule applied when there was no\n previously selected page. For example: `_page1`\n- `*_to`: It defines an animation that will run whenever the newly selected page\n matches this rule. This rule will ignore the previously selected page.\n For example: `*_page2`\n- `from_*`: It defines an animation that will run whenever the previously selected page\n matches this rule. This rule will ignore the newly selected page.\n For example: `page1_*`\n- `default`: It defines an animation which will run when none of the\n other rules apply.\n\nPlease bear in mind 'undefined' and 'null' are not valid identifiers.\n\nAll transition rules must be an object with the following format:\n```javascript\n{\n in: 'inbound_css_animation_class_name',\n out: 'outbound_css_animation_class_name'\n}\n```",
"type": "AnimationClasses",
"default": "{}"
}
],
"events": [
Expand Down
34 changes: 28 additions & 6 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 4 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
"./": "./helium-animated-pages.js",
"./sample-animations": "./sample-animations/index.js"
},
"types": "./types/HeliumAnimatedPages.d.ts",
"repository": "https://github.com/alangdm/helium-animated-pages",
"author": "alangdm",
"license": "BSD-3-Clause",
Expand All @@ -23,11 +24,13 @@
"husky": "4.3.8",
"lint-staged": "10.5.4",
"prettier": "2.2.1",
"typescript": "4.2.3",
"web-component-analyzer": "1.1.6"
},
"scripts": {
"start": "npm run analyze && web-dev-server --node-resolve --open --watch",
"start": "npm run analyze && npm run types && web-dev-server --node-resolve --open --watch",
"analyze": "wca analyze src/HeliumAnimatedPages.js --format json --outFile ./custom-elements.json",
"types": "tsc",
"lint:eslint": "eslint --ext .js . --ignore-path .gitignore",
"format:eslint": "eslint --ext .js . --fix --ignore-path .gitignore",
"lint:prettier": "prettier \"**/*.js\" --check --ignore-path .gitignore",
Expand Down
19 changes: 17 additions & 2 deletions src/HeliumAnimatedPages.js
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ const _isString = next => {
* @cssprop --helium-children-visible - Whether this component should be visible if it's a children of another `helium-animated-pages`.
*
* @prop {Boolean} isAnimating - This property will get the state of the animation. Whether it's currently in the middle of an animation or not.
*
* @typedef {{in: string, out: string}} AnimationRule - An animation rule with in and out classes to apply
* @typedef {Object.<string, AnimationRule>} AnimationClasses - The ruleset of animations to apply
*/
export default class HeliumAnimatedPages extends LitElement {
render() {
Expand Down Expand Up @@ -92,7 +95,7 @@ export default class HeliumAnimatedPages extends LitElement {
* out: 'outbound_css_animation_class_name'
* }
* ```
* @type {Object.<string, {in: string, out: string}>}
* @type {AnimationClasses}
* @attr
*/
animationClasses: { type: Object },
Expand Down Expand Up @@ -127,6 +130,8 @@ export default class HeliumAnimatedPages extends LitElement {
this._inAnimation = this._inAnimation.bind(this);
this._outAnimation = this._outAnimation.bind(this);
this.attrForSelected = '';
/** @type {AnimationClasses} */
this.animationClasses = {};
}

get isAnimating() {
Expand All @@ -137,7 +142,7 @@ export default class HeliumAnimatedPages extends LitElement {
return this._selected;
}

set selected(next) {
set selected(/** @type {string|number} */ next) {
if (typeof next === 'undefined' || next === null || this._animating) {
return;
}
Expand Down Expand Up @@ -243,6 +248,11 @@ export default class HeliumAnimatedPages extends LitElement {
this.selected = nextIndex;
}

/**
*
* @param {string|number} next
* @param {string|number} prev
*/
_changeActive(next, prev) {
const startEvent = new CustomEvent('helium-start', {
composed: true,
Expand Down Expand Up @@ -283,6 +293,11 @@ export default class HeliumAnimatedPages extends LitElement {
this._inPage.setAttribute('active', true);
}

/**
*
* @param {string|number} next
* @param {string|number} prev
*/
_animationClasses(next, prev) {
const fullId = `${prev}_${next}`;
const toId = `*_${next}`;
Expand Down
8 changes: 8 additions & 0 deletions src/serializers.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
export const stringOrIntSerializer = {
/**
*
* @param {string} attr
*/
fromAttribute(attr) {
if (!attr) {
return undefined;
Expand All @@ -13,6 +17,10 @@ export const stringOrIntSerializer = {
}
return index;
},
/**
*
* @param {string|number} value
*/
toAttribute(value) {
return typeof value !== 'undefined' ? `${value}` : null;
},
Expand Down
10 changes: 10 additions & 0 deletions tsconfig.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"include": ["src/HeliumAnimatedPages.js"],
"exclude": [],
"compilerOptions": {
"allowJs": true,
"declaration": true,
"emitDeclarationOnly": true,
"outDir": "./types",
}
}
165 changes: 165 additions & 0 deletions types/HeliumAnimatedPages.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
/**
* A light spiritual successor to neon-animated-pages using only css animations
*
* @element helium-animated-pages
*
* @slot - The slot for the pages to animate
*
* @fires helium-start - Fires when the page transition starts
* @fires helium-end - Fires when the page transition ends
*
* @cssprop --helium-children-visible - Whether this component should be visible if it's a children of another `helium-animated-pages`.
*
* @prop {Boolean} isAnimating - This property will get the state of the animation. Whether it's currently in the middle of an animation or not.
*
* @typedef {{in: string, out: string}} AnimationRule - An animation rule with in and out classes to apply
* @typedef {Object.<string, AnimationRule>} AnimationClasses - The ruleset of animations to apply
*/
export default class HeliumAnimatedPages extends LitElement {
static get styles(): import("lit").CSSResultGroup[];
static get properties(): {
/**
* This property is required for the animations to run, it maps which
* animations to run depending on what the transition will be.
*
* If the property isn't set the transitions will run without animations.
*
* The properties of this object each represent a different transition rule.
* The transition rules can be of one of the following types.
* The rule types are listed in order of priority.
* All the examples assume you have at least two pages identified respectively as `page1` and `page2`.
* - `from_to`: The most specific kind of transition.
* It defines an animation which will run when both the newly selected
* page and the previously selected page match with the rule. For
* example: `page1_page2`.
* - `_to `: This is a special subtype of the previous rule applied when there was no
* previously selected page. For example: `_page1`
* - `*_to`: It defines an animation that will run whenever the newly selected page
* matches this rule. This rule will ignore the previously selected page.
* For example: `*_page2`
* - `from_*`: It defines an animation that will run whenever the previously selected page
* matches this rule. This rule will ignore the newly selected page.
* For example: `page1_*`
* - `default`: It defines an animation which will run when none of the
* other rules apply.
*
* Please bear in mind 'undefined' and 'null' are not valid identifiers.
*
* All transition rules must be an object with the following format:
* ```javascript
* {
* in: 'inbound_css_animation_class_name',
* out: 'outbound_css_animation_class_name'
* }
* ```
* @type {AnimationClasses}
* @attr
*/
animationClasses: AnimationClasses;
/**
* If set, it will be the name of the attribute used to identify
* the pages added inside the instance of `helium-animated-pages`.
* Otherwise, the index of the children page will be used. Any page
* without this attribute will be ignored. If two pages with
* the same value for the attribute exist, only the first one will be selectable.
* @type {string}
* @attr
*/
attrForSelected: string;
/**
* The numerical index or the value of the attribute of the currently
* selected node. It's only the index if `attrForSelected` isn't defined.
* Modifying this property achieves the same results as invoking
* the `select(next)` method.
* Warning: using this property together with any of the selection
* methods might cause state inconsistencies.
* @type {string|number}
* @attr
*/
selected: string | number;
};
_inAnimation(): void;
_outAnimation(): void;
attrForSelected: string;
/** @type {AnimationClasses} */
animationClasses: AnimationClasses;
get isAnimating(): boolean;
set selected(arg: string | number);
get selected(): string | number;
_inPage: any;
_outPage: Element;
_selected: any;
/**
* The currently selected item's DOM node.
* @type {Element}
* @readonly
*/
readonly get selectedItem(): Element;
/**
* select - Makes a transition into the page identified with next.
*
* - If `next` is a string, the new page will be searched depending on
* `attrForSelected`.
* - If next is a number or a string which can be parsed to an integer,
* the new page will be searched by index.
*
* It will do nothing if one of the following conditions applies:
*
* - No page is found corresponding to the identifier.
* - An animation is running.
* - The new page is the same as the previous page.
*
* @param {string|number} next next page index or attribute value
*/
select(next: string | number): void;
/**
* selectNext - Makes a transition to the page which is the next sibling of
* the currently selected page.
*
* The first page will be selected if no page was selected or
* the currently selected page is the last page.
*
*/
selectNext(): void;
/**
* selectPrevious - Makes a transition to the page which is the previous sibling
* of the currently selected page.
*
* The last page will be selected if no page was selected or
* the currently selected page is the first page.
*
*/
selectPrevious(): void;
/**
*
* @param {string|number} next
* @param {string|number} prev
*/
_changeActive(next: string | number, prev: string | number): void;
_currentClasses: AnimationRule;
_beginAnimation(): void;
_animating: boolean;
_outAnimationEnded: boolean;
/**
*
* @param {string|number} next
* @param {string|number} prev
*/
_animationClasses(next: string | number, prev: string | number): AnimationRule;
_inAnimationEnded: boolean;
_onAnimationEnd(): void;
}
/**
* - An animation rule with in and out classes to apply
*/
export type AnimationRule = {
in: string;
out: string;
};
/**
* - The ruleset of animations to apply
*/
export type AnimationClasses = {
[x: string]: AnimationRule;
};
import { LitElement } from "lit-element";
Loading

0 comments on commit f14032f

Please sign in to comment.