Skip to content

Commit 4abd6be

Browse files
lolmauslolmaus
committed
API docs
1 parent 3b78e5b commit 4abd6be

File tree

9 files changed

+213
-33
lines changed

9 files changed

+213
-33
lines changed

‎.github/workflows/github-pages.yml

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Deployment to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- gen-4
7+
pull_request:
8+
9+
env:
10+
NODE_VERSION: 14
11+
12+
jobs:
13+
docs-app-deploy:
14+
name: Deploy API docs
15+
runs-on: ubuntu-latest
16+
timeout-minutes: 7
17+
# Only run on pushes to gen-0 branch that aren't from the cron workflow
18+
if: github.event_name == 'push' && github.ref == 'refs/heads/gen-0' && contains(github.ref, 'cron') != true
19+
20+
steps:
21+
- name: Check out a copy of the repo
22+
uses: actions/checkout@v2
23+
24+
- name: Use Node.js ${{ env.NODE_VERSION }}
25+
uses: actions/setup-node@v2
26+
with:
27+
node-version: ${{ env.NODE_VERSION }}
28+
29+
# - name: Get Yarn cache path
30+
# id: yarn-cache-dir-path
31+
# run: echo "::set-output name=dir::$(yarn cache dir)"
32+
33+
# - name: Cache Yarn cache and node_modules
34+
# id: cache-dependencies
35+
# uses: actions/cache@v2
36+
# with:
37+
# path: |
38+
# ${{ steps.yarn-cache-dir-path.outputs.dir }}
39+
# node_modules
40+
# key: ${{ runner.os }}-${{ env.NODE_VERSION }}-${{ hashFiles('**/yarn.lock') }}
41+
# restore-keys: ${{ runner.os }}-${{ env.NODE_VERSION }}-
42+
43+
- name: Log yarn version
44+
run: yarn --version
45+
46+
- name: Install dependencies
47+
run: yarn install
48+
# if: steps.cache-dependencies.outputs.cache-hit != 'true'
49+
50+
- name: Build
51+
run: yarn typedoc
52+
53+
- name: Deploy
54+
uses: peaceiris/actions-gh-pages@v3
55+
with:
56+
github_token: ${{ secrets.GITHUB_TOKEN }}
57+
publish_dir: ./api-docs
58+
destination_dir: api

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# See https://help.github.com/ignore-files/ for more about ignoring files.
22

33
# compiled output
4+
/api-docs/
45
/dist/
56
/tmp/
67

‎README.md

Lines changed: 22 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
<!-- omit in toc -->
22
ember-element-query
33
![npm version](https://img.shields.io/npm/v/ember-element-query)
4-
![GitHub Workflow Status](https://img.shields.io/github/workflow/status/lolmaus/ember-element-query/CI)
5-
==============================================================================
4+
[![CI](https://github.com/lolmaus/ember-element-query/actions/workflows/ci.yml/badge.svg)](https://github.com/lolmaus/ember-element-query/actions/workflows/ci.yml)
5+
===================
66

77
* Use element queries effortlessly on any element or component.
88
* Use it in the form of the `{{element-query}}` modifier or the `<ElementQuery as |EQ|>` component.
@@ -74,8 +74,16 @@ See [detailed comparison](#comparison) with code samples.
7474

7575

7676

77+
API Docs
78+
--------
79+
80+
https://lolmaus.github.io/ember-element-query/api/
81+
82+
83+
84+
7785
Roadmap
78-
------------------------------------------------------------------------------
86+
-------
7987

8088
This addon is in active development.
8189

@@ -117,7 +125,7 @@ This addon is in active development.
117125

118126

119127
Rationale
120-
------------------------------------------------------------------------------
128+
---------
121129

122130
CSS media queries have a few disadvantages:
123131

@@ -153,7 +161,7 @@ Unfortunately, CSS is not aware of element's current width, so pseudoselectors l
153161

154162

155163
Concept of sizes
156-
------------------------------------------------------------------------------
164+
----------------
157165

158166
`ember-element-query` operates with *sizes*. "Sizes" are like T-shirt sizes, except they indicate element width.
159167

@@ -200,7 +208,7 @@ Here's an explicit sizes chart:
200208

201209

202210
How ember-element-query works
203-
------------------------------------------------------------------------------
211+
-----------------------------
204212

205213
`ember-element-query` applies HTML attributes to an element indicating its current size.
206214

@@ -280,7 +288,7 @@ aside[at-m] {
280288

281289

282290
Installation
283-
------------------------------------------------------------------------------
291+
------------
284292

285293
Use `ember-cli` to install the addon as usual:
286294

@@ -297,7 +305,7 @@ This addon does not do anything on install, so it can alternatively be installed
297305

298306

299307
Usage
300-
------------------------------------------------------------------------------
308+
-----
301309

302310
### As a modifier
303311

@@ -350,7 +358,7 @@ The second argument `EQInfo` is the same object that is passed to the [onResize
350358

351359

352360
Advanced usage
353-
------------------------------------------------------------------------------
361+
--------------
354362

355363
### onResize callback
356364

@@ -688,7 +696,7 @@ Unfortunately, this requires the parent to know which attributes are used in com
688696

689697

690698
Browser support
691-
------------------------------------------------------------------------------
699+
---------------
692700

693701
**IE is not supported** because `ember-element-query` uses modern ECMAScript APIs.
694702

@@ -707,7 +715,7 @@ See [caniuse.com](https://caniuse.com/#feat=resizeobserver) for detailed stats.
707715

708716

709717
Alternatives
710-
------------------------------------------------------------------------------
718+
------------
711719

712720
There are a few other Ember addons implementing element queries, such as:
713721

@@ -1073,7 +1081,7 @@ Given breakpoints 350, 700 and 1050:
10731081

10741082

10751083
Contributing
1076-
------------------------------------------------------------------------------
1084+
------------
10771085

10781086
### Tools
10791087

@@ -1116,14 +1124,14 @@ For more information on using ember-cli, visit [https://ember-cli.com/](https://
11161124

11171125

11181126
License
1119-
------------------------------------------------------------------------------
1127+
-------
11201128

11211129
This project is licensed under the [MIT License](LICENSE.md).
11221130

11231131

11241132

11251133
Credit
1126-
------------------------------------------------------------------------------
1134+
------
11271135

11281136
Initially implemented by Andrey Mikhaylov ([lolmaus](https://github.com/lolmaus)) and [contributors](https://github.com/lolmaus/ember-element-query/graphs/contributors).
11291137

‎addon/-private/component.ts

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
import Component from '@glimmer/component';
22
import { tracked } from '@glimmer/tracking';
33
import { action } from '@ember/object';
4-
import { ComponentArgs, EQInfo } from 'ember-element-query';
4+
import { Args, EQInfo } from 'ember-element-query';
55

6-
export default class ElementQuery extends Component<ComponentArgs> {
6+
/** @internal */
7+
export default class ElementQuery extends Component<Args> {
78
@tracked
89
eqInfo?: EQInfo;
910

‎addon/-private/modifier.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ export interface SizeObject {
2424

2525
export type RangeDirection = 'at' | 'from' | 'to';
2626

27+
/** @internal */
2728
export default class ElementQueryModifier extends Modifier<ModifierArgs> {
2829
// -------------------
2930
// Properties

‎addon/index.ts

Lines changed: 60 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,44 +3,88 @@ import { ModifierArgs as ModifierArgsBase } from 'ember-modifier';
33
export { default as component } from './-private/component';
44
export { default as modifier } from './-private/modifier';
55

6+
/**
7+
* Defines the direction for which HTML attributes are applied.
8+
*/
69
export type Dimension = 'width' | 'height' | 'both';
710

11+
/**
12+
* A format for defining sizes. Keys are size names and values are left breakpoints of each size.
13+
*
14+
* The first size *must* have a value of `0`.
15+
*/
816
export type Sizes = Record<string, number>;
917

18+
/**
19+
* A data structure passed as an argument to callbacks.
20+
*/
1021
export interface EQInfo {
22+
/** An element to which Element Query has been applied. */
1123
element: HTMLElement;
24+
25+
/** Current width of the element, in px. */
1226
width: number;
27+
28+
/** Current height of the element, in px. */
1329
height: number;
30+
31+
/** Current ratio of the element's width to height. */
1432
ratio: number;
33+
34+
/** Name of the current horizontal [[Sizes | size]] of the element. */
1535
size?: string;
36+
37+
/** Name of the current vertical [[Sizes | size]] of the element. */
1638
sizeHeight?: string;
39+
40+
/** Name of the current [[dimension]] (horizontal/vertical/both). */
1741
dimension: Dimension;
42+
43+
/** Prefix used for HTML attributes. */
1844
prefix?: string;
45+
46+
/** Array of HTML attribute names which are currently applied. */
1947
attributes: string[];
48+
49+
/**
50+
* Array of HTML attribute names which are currently applied where keys are attributes and values are all `true`.
51+
*
52+
* Mostly useful in templates.
53+
* */
2054
attributesRecord: Record<string, true>;
2155
}
2256

2357
export interface ModifierArgs extends ModifierArgsBase {
2458
positional: [];
25-
named: {
26-
onResize?: (eqInfo: EQInfo) => void;
27-
sizes?: Sizes;
28-
sizesHeight?: Sizes;
29-
prefix?: string;
30-
dimension?: Dimension;
31-
isDisabled?: boolean;
32-
};
59+
named: Args;
3360
}
3461

35-
export interface ComponentArgs {
62+
/**
63+
* API of the `eq` modifier and the `EQ` component.
64+
*/
65+
export interface Args extends Record<string, unknown> {
66+
/** Callback that will be called when the size of the element changes. It is not throttled. Accepts [[EQInfo]] as the first argument. */
67+
onResize?: (eqInfo: EQInfo) => void;
68+
69+
/** A definition of horizontal [Sizes]. Defaults to [[SIZES_DEFAULT]]. */
70+
sizes?: Sizes;
71+
72+
/** A definition of vertical [Sizes]. Defaults to [[SIZES_HEIGHT_DEFAULT]]. */
73+
sizesHeight?: Sizes;
74+
75+
/** Prefix to be used for HTML attributes. Defautls to `""`. */
76+
prefix?: string;
77+
78+
/** Direction of measuring the element. */
3679
dimension?: Dimension;
80+
81+
/** Use this to shut down the element query functionality for this element. */
3782
isDisabled?: boolean;
38-
prefix?: string;
39-
sizes?: Sizes;
40-
sizesHeight?: Sizes | true;
41-
onResize?: (eqInfo: EQInfo) => void;
4283
}
4384

85+
/**
86+
* Default value of horizontal [[Sizes]].
87+
*/
4488
// prettier-ignore
4589
export const SIZES_DEFAULT: Sizes = {
4690
xxs: 0,
@@ -53,6 +97,9 @@ export const SIZES_DEFAULT: Sizes = {
5397
xxxl: 1400,
5498
};
5599

100+
/**
101+
* Default value of vertical [[Sizes]].
102+
*/
56103
// prettier-ignore
57104
export const SIZES_HEIGHT_DEFAULT: Sizes = {
58105
'xxs-height': 0,

‎package.json

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,8 @@
3131
"test:ember-compatibility": "ember try:each",
3232
"prepublishOnly": "ember ts:precompile",
3333
"postpublish": "ember ts:clean",
34-
"release": "release-it"
34+
"release": "release-it",
35+
"typedoc": "typedoc"
3536
},
3637
"husky": {
3738
"hooks": {
@@ -104,6 +105,7 @@
104105
"release-it": "^14.10.0",
105106
"release-it-lerna-changelog": "^3.1.0",
106107
"sinon": "^11.1.1",
108+
"typedoc": "^0.21.5",
107109
"typescript": "^4.3.4"
108110
},
109111
"engines": {

‎typedoc.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"entryPoints": ["addon/index.ts"],
3+
"out": "api-docs",
4+
"excludeInternal": true
5+
}

0 commit comments

Comments
 (0)