API docs

Author: lolmaus

.github/workflows/github-pages.yml

@@ -0,0 +1,58 @@
+name: Deployment to GitHub Pages
+
+on:
+  push:
+    branches:
+      - gen-4
+  pull_request:
+
+env:
+  NODE_VERSION: 14
+
+jobs:
+  docs-app-deploy:
+    name: Deploy API docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 7
+    # Only run on pushes to gen-0 branch that aren't from the cron workflow
+    if: github.event_name == 'push' && github.ref == 'refs/heads/gen-0' && contains(github.ref, 'cron') != true
+
+    steps:
+      - name: Check out a copy of the repo
+        uses: actions/checkout@v2
+
+      - name: Use Node.js ${{ env.NODE_VERSION }}
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      # - name: Get Yarn cache path
+      #   id: yarn-cache-dir-path
+      #   run: echo "::set-output name=dir::$(yarn cache dir)"
+
+      # - name: Cache Yarn cache and node_modules
+      #   id: cache-dependencies
+      #   uses: actions/cache@v2
+      #   with:
+      #     path: |
+      #       ${{ steps.yarn-cache-dir-path.outputs.dir }}
+      #       node_modules
+      #     key: ${{ runner.os }}-${{ env.NODE_VERSION }}-${{ hashFiles('**/yarn.lock') }}
+      #     restore-keys: ${{ runner.os }}-${{ env.NODE_VERSION }}-
+
+      - name: Log yarn version
+        run: yarn --version
+
+      - name: Install dependencies
+        run: yarn install
+        # if: steps.cache-dependencies.outputs.cache-hit != 'true'
+
+      - name: Build
+        run: yarn typedoc
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./api-docs
+          destination_dir: api

.gitignore

@@ -1,6 +1,7 @@
 # See https://help.github.com/ignore-files/ for more about ignoring files.
 
 # compiled output
+/api-docs/
 /dist/
 /tmp/
 

README.md

@@ -1,8 +1,8 @@
 <!-- omit in toc -->
 ember-element-query
 ![npm version](https://img.shields.io/npm/v/ember-element-query)
-![GitHub Workflow Status](https://img.shields.io/github/workflow/status/lolmaus/ember-element-query/CI)
-==============================================================================
+[![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)
+===================
 
 * Use element queries effortlessly on any element or component.
 * 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.
 
 
 
+API Docs
+--------
+
+https://lolmaus.github.io/ember-element-query/api/
+
+
+
+
 Roadmap
-------------------------------------------------------------------------------
+-------
 
 This addon is in active development.
 
@@ -117,7 +125,7 @@ This addon is in active development.
 
 
 Rationale
-------------------------------------------------------------------------------
+---------
 
 CSS media queries have a few disadvantages:
 
@@ -153,7 +161,7 @@ Unfortunately, CSS is not aware of element's current width, so pseudoselectors l
 
 
 Concept of sizes
-------------------------------------------------------------------------------
+----------------
 
 `ember-element-query` operates with *sizes*. "Sizes" are like T-shirt sizes, except they indicate element width.
 
@@ -200,7 +208,7 @@ Here's an explicit sizes chart:
 
 
 How ember-element-query works
-------------------------------------------------------------------------------
+-----------------------------
 
 `ember-element-query` applies HTML attributes to an element indicating its current size.
 
@@ -280,7 +288,7 @@ aside[at-m] {
 
 
 Installation
-------------------------------------------------------------------------------
+------------
 
 Use `ember-cli` to install the addon as usual:
 
@@ -297,7 +305,7 @@ This addon does not do anything on install, so it can alternatively be installed
 
 
 Usage
-------------------------------------------------------------------------------
+-----
 
 ### As a modifier
 
@@ -350,7 +358,7 @@ The second argument `EQInfo` is the same object that is passed to the [onResize
 
 
 Advanced usage
-------------------------------------------------------------------------------
+--------------
 
 ### onResize callback
 
@@ -688,7 +696,7 @@ Unfortunately, this requires the parent to know which attributes are used in com
 
 
 Browser support
-------------------------------------------------------------------------------
+---------------
 
 **IE is not supported** because `ember-element-query` uses modern ECMAScript APIs.
 
@@ -707,7 +715,7 @@ See [caniuse.com](https://caniuse.com/#feat=resizeobserver) for detailed stats.
 
 
 Alternatives
-------------------------------------------------------------------------------
+------------
 
 There are a few other Ember addons implementing element queries, such as:
 
@@ -1073,7 +1081,7 @@ Given breakpoints 350, 700 and 1050:
 
 
 Contributing
-------------------------------------------------------------------------------
+------------
 
 ### Tools
 
@@ -1116,14 +1124,14 @@ For more information on using ember-cli, visit [https://ember-cli.com/](https://
 
 
 License
-------------------------------------------------------------------------------
+-------
 
 This project is licensed under the [MIT License](LICENSE.md).
 
 
 
 Credit
-------------------------------------------------------------------------------
+------
 
 Initially implemented by Andrey Mikhaylov ([lolmaus](https://github.com/lolmaus)) and [contributors](https://github.com/lolmaus/ember-element-query/graphs/contributors).
 

addon/-private/component.ts

@@ -1,9 +1,10 @@
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
 import { action } from '@ember/object';
-import { ComponentArgs, EQInfo } from 'ember-element-query';
+import { Args, EQInfo } from 'ember-element-query';
 
-export default class ElementQuery extends Component<ComponentArgs> {
+/** @internal */
+export default class ElementQuery extends Component<Args> {
   @tracked
   eqInfo?: EQInfo;
 

addon/-private/modifier.ts

@@ -24,6 +24,7 @@ export interface SizeObject {
 
 export type RangeDirection = 'at' | 'from' | 'to';
 
+/** @internal */
 export default class ElementQueryModifier extends Modifier<ModifierArgs> {
   // -------------------
   // Properties

addon/index.ts

@@ -3,44 +3,88 @@ import { ModifierArgs as ModifierArgsBase } from 'ember-modifier';
 export { default as component } from './-private/component';
 export { default as modifier } from './-private/modifier';
 
+/**
+ * Defines the direction for which HTML attributes are applied.
+ */
 export type Dimension = 'width' | 'height' | 'both';
 
+/**
+ * A format for defining sizes. Keys are size names and values are left breakpoints of each size.
+ *
+ * The first size *must* have a value of `0`.
+ */
 export type Sizes = Record<string, number>;
 
+/**
+ * A data structure passed as an argument to callbacks.
+ */
 export interface EQInfo {
+  /** An element to which Element Query has been applied. */
   element: HTMLElement;
+
+  /** Current width of the element, in px. */
   width: number;
+
+  /** Current height of the element, in px. */
   height: number;
+
+  /** Current ratio of the element's width to height. */
   ratio: number;
+
+  /** Name of the current horizontal [[Sizes | size]] of the element. */
   size?: string;
+
+  /** Name of the current vertical [[Sizes | size]] of the element. */
   sizeHeight?: string;
+
+  /** Name of the current [[dimension]] (horizontal/vertical/both). */
   dimension: Dimension;
+
+  /** Prefix used for HTML attributes. */
   prefix?: string;
+
+  /** Array of HTML attribute names which are currently applied. */
   attributes: string[];
+
+  /**
+   * Array of HTML attribute names which are currently applied where keys are attributes and values are all `true`.
+   *
+   * Mostly useful in templates.
+   * */
   attributesRecord: Record<string, true>;
 }
 
 export interface ModifierArgs extends ModifierArgsBase {
   positional: [];
-  named: {
-    onResize?: (eqInfo: EQInfo) => void;
-    sizes?: Sizes;
-    sizesHeight?: Sizes;
-    prefix?: string;
-    dimension?: Dimension;
-    isDisabled?: boolean;
-  };
+  named: Args;
 }
 
-export interface ComponentArgs {
+/**
+ * API of the `eq` modifier and the `EQ` component.
+ */
+export interface Args extends Record<string, unknown> {
+  /** Callback that will be called when the size of the element changes. It is not throttled. Accepts [[EQInfo]] as the first argument. */
+  onResize?: (eqInfo: EQInfo) => void;
+
+  /** A definition of horizontal [Sizes]. Defaults to [[SIZES_DEFAULT]]. */
+  sizes?: Sizes;
+
+  /** A definition of vertical [Sizes]. Defaults to [[SIZES_HEIGHT_DEFAULT]]. */
+  sizesHeight?: Sizes;
+
+  /** Prefix to be used for HTML attributes. Defautls to `""`. */
+  prefix?: string;
+
+  /** Direction of measuring the element. */
   dimension?: Dimension;
+
+  /** Use this to shut down the element query functionality for this element. */
   isDisabled?: boolean;
-  prefix?: string;
-  sizes?: Sizes;
-  sizesHeight?: Sizes | true;
-  onResize?: (eqInfo: EQInfo) => void;
 }
 
+/**
+ * Default value of horizontal [[Sizes]].
+ */
 // prettier-ignore
 export const SIZES_DEFAULT: Sizes = {
   xxs:  0,
@@ -53,6 +97,9 @@ export const SIZES_DEFAULT: Sizes = {
   xxxl: 1400,
 };
 
+/**
+ * Default value of vertical [[Sizes]].
+ */
 // prettier-ignore
 export const SIZES_HEIGHT_DEFAULT: Sizes = {
   'xxs-height':  0,

package.json

@@ -31,7 +31,8 @@
     "test:ember-compatibility": "ember try:each",
     "prepublishOnly": "ember ts:precompile",
     "postpublish": "ember ts:clean",
-    "release": "release-it"
+    "release": "release-it",
+    "typedoc": "typedoc"
   },
   "husky": {
     "hooks": {
@@ -104,6 +105,7 @@
     "release-it": "^14.10.0",
     "release-it-lerna-changelog": "^3.1.0",
     "sinon": "^11.1.1",
+    "typedoc": "^0.21.5",
     "typescript": "^4.3.4"
   },
   "engines": {

typedoc.json

@@ -0,0 +1,5 @@
+{
+  "entryPoints": ["addon/index.ts"],
+  "out": "api-docs",
+  "excludeInternal": true
+}