From 7b3bd37066fa9e97e660792f930b6b67eb500b1f Mon Sep 17 00:00:00 2001 From: Thomas Gossmann Date: Thu, 6 Jul 2023 01:39:46 +0200 Subject: [PATCH] Documentation for ember-link (#773) --- .github/workflows/docs.yml | 45 ++ .gitignore | 5 + README.md | 633 ++------------------ docs/.vitepress/config.ts | 60 ++ docs/.vitepress/sidebar-api.ts | 89 +++ docs/api-examples.md | 49 ++ docs/behavior.md | 45 ++ docs/commands.md | 41 ++ docs/configuration.md | 38 ++ docs/customization.md | 83 +++ docs/getting-started.md | 84 +++ docs/helper.md | 99 ++++ docs/index.md | 23 + docs/installation.md | 7 + docs/link-builder.md | 98 ++++ docs/markdown-examples.md | 85 +++ docs/migration.md | 10 + docs/params.md | 120 ++++ docs/references.md | 15 + docs/service.md | 25 + docs/testing.md | 47 ++ docs/using-locales.md | 82 +++ docs/using-primitives.md | 72 +++ ember-link/README.md | 633 ++------------------ ember-link/package.json | 5 +- ember-link/src/helpers/link.ts | 21 +- ember-link/src/index.ts | 10 + ember-link/src/test-support/index.ts | 7 + ember-link/typedoc.json | 16 + package.json | 18 +- pnpm-lock.yaml | 835 ++++++++++++++++++++++++++- 31 files changed, 2179 insertions(+), 1221 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/.vitepress/config.ts create mode 100644 docs/.vitepress/sidebar-api.ts create mode 100644 docs/api-examples.md create mode 100644 docs/behavior.md create mode 100644 docs/commands.md create mode 100644 docs/configuration.md create mode 100644 docs/customization.md create mode 100644 docs/getting-started.md create mode 100644 docs/helper.md create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/link-builder.md create mode 100644 docs/markdown-examples.md create mode 100644 docs/migration.md create mode 100644 docs/params.md create mode 100644 docs/references.md create mode 100644 docs/service.md create mode 100644 docs/testing.md create mode 100644 docs/using-locales.md create mode 100644 docs/using-primitives.md create mode 100644 ember-link/typedoc.json diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..690af28d --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,45 @@ +name: Docs + +on: + workflow_dispatch: + push: + branches: + - main + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Setup + uses: wyvox/action@v1 + - name: Build Docs + run: pnpm build:docs + - name: Setup Pages + uses: actions/configure-pages@v3 + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: "docs/.vitepress/dist" + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/.gitignore b/.gitignore index 2a953744..1e4179bf 100644 --- a/.gitignore +++ b/.gitignore @@ -23,3 +23,8 @@ node_modules/ /.node_modules.ember-try/ /package.json.ember-try /yarn.lock.ember-try + +#vitepress +/docs/.vitepress/dist/ +/docs/.vitepress/cache/ +/docs/api diff --git a/README.md b/README.md index 0397f06c..7268317a 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,10 @@ [![npm version](https://badge.fury.io/js/ember-link.svg)](http://badge.fury.io/js/ember-link) [![Download Total](https://img.shields.io/npm/dt/ember-link.svg)](http://badge.fury.io/js/ember-link) [![Ember Observer Score](https://emberobserver.com/badges/ember-link.svg)](https://emberobserver.com/addons/ember-link) -[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) -[![Dependabot enabled](https://img.shields.io/badge/dependabot-enabled-blue.svg?logo=dependabot)](https://dependabot.com/) -[![dependencies Status](https://david-dm.org/buschtoens/ember-link/status.svg)](https://david-dm.org/buschtoens/ember-link) -[![devDependencies Status](https://david-dm.org/buschtoens/ember-link/dev-status.svg)](https://david-dm.org/buschtoens/ember-link?type=dev) Introduces a new `Link` primitive to pass around self-contained references to -routes, like URLs, but with state (`isActive`, ...) and methods (`transitionTo`, -...). Also brings along an accompanying template helper and component for easy +routes, like URLs, but with state (`isActive`, ...) and methods (`open`, +...). Also brings along an accompanying template helper for easy usage in templates. > `ember-link` does to routing what `ember-concurrency` did to asynchrony! @@ -20,633 +16,80 @@ usage in templates. ## Installation -``` +Install `ember-link` with: + +```sh ember install ember-link ``` ## Usage -- [`{{link}}` helper](#link-helper) -- [`` component](#link-component) -- [`Link` class](#link) -- [`UILink` class](#uilink) -- [`LinkManager` service](#linkmanager) -- [Testing](#testing) - -### `{{link}}` Helper - -The `{{link}}` helper returns a [`UILink`](#uilink) instance. - -#### Invocation Styles - -##### Positional Parameters - -```hbs -{{#let - (link - "blogs.posts.post" - @post.blog.id - @post.id - (query-params showFullPost=true) - ) - as |l| -}} - - Read the full "{{@post.title}}" story on our {{@post.blog.name}} blog! - -{{/let}} -``` - -##### Named Parameters - -```hbs -{{#let - (link - route="blogs.posts.post" - models=(array @post.blog.id @post.id) - query=(hash showFullPost=true) - ) - as |l| -}} - - Read the full "{{@post.title}}" story on our {{@post.blog.name}} blog! - -{{/let}} -``` - -When passing a single model, you can use `model` instead of `models`: - -```hbs -{{#let - (link - route="blogs.posts" - model=@post.blog.id - ) - as |l| -}} - - Read more stories in the {{@post.blog.name}} blog! - -{{/let}} -``` - -##### Mix & Match - -You can also mix and match the parameter styles, however you like. - -```hbs -{{#let - (link - "blogs.posts.post" - @post.blog.id - @post.id - query=(hash showFullPost=true) - ) - as |l| -}} - - Read the full "{{@post.title}}" story on our {{@post.blog.name}} blog! - -{{/let}} -``` +You can use `ember-link` in a declarative form with a [`(link)` +helper](https://buschtoens.github.io/ember-link/helper.html) or imperatively with the [`LinkManager` +Service](https://buschtoens.github.io/ember-link/service.html). -##### `fromURL` +### `(link)` Helper Example -Instead of the positional & named link parameters described above, you can also -create a `Link` instance from a serialized URL. +Use the `(link)` helper to create a link primitive and attach it to an element. ```hbs -{{! someURL = "/blogs/tech/posts/dont-break-the-web" }} -{{#let (link fromURL=this.someURL) as |l|}} - - Read the next great post. +{{#let (link "about") as |l|}} + + About us {{/let}} ``` -`fromURL` is mutually exclusive with the other link parameters: `route`, `model` -& `models`, `query` - -### Parameters - -In addition to the parameters shown above, the `{{link}}` helper also accepts a -`preventDefault` default parameter. It defaults to `true` and intelligently -prevents hard browser transitions when clicking `` elements. - -See [`@preventDefault`](#preventdefault) and [`UILink`](#uilink). - -### 💡 Pro Tips - -Instead of using the `{{#let}}` helper, you can use the -[`` component](#link-component) to achieve the same scoping effect, with -subjectively nicer syntax. - -Even better yet, make [`Link`](#link) / [`UILink`](#uilink) a first-class -primitive in your app architecture! Instead of manually wiring up -[`Link#url`](#url) and [`Link#transitionTo()`](#transitionto) every time, rather -create your own ready-to-use, style-guide-compliant link and button components -that accept `@link` as an argument instead of `@href` and `@onClick`. - -This is akin to the -[popular](https://github.com/rwjblue/ember-cli-async-button) -[async](https://github.com/DockYard/ember-async-button) -[task](https://github.com/quipuapp/ember-task-button) -button component concept. - -```hbs - - Become a Premium member - -``` - -```hbs - - {{yield}} - -``` - -### `` Component - -Similar to the the [`{{link}}` helper](#link-helper), the `` component -yields a [`UILink`](#uilink) instance. - -```hbs - - - Click me - - -``` - -#### Arguments - -##### `@route` - -Required. - -The target route name. - -**Example** - -```hbs - - - Click me - - -``` - -**`{{link-to}}` equivalent** - -```hbs -{{#link-to "some.route"}} - Click me -{{/link-to}} -``` - -##### `@models` - -Optional. Mutually exclusive with [`@model`](#model). - -An array of models / dynamic segments. - -**Example** - -```hbs - - - Click me - - -``` - -**`{{link-to}}` equivalent** - -```hbs -{{#link-to "some.route" someModel someNestedModel}} - Click me -{{/link-to}} -``` - -##### `@model` - -Optional. Mutually exclusive with [`@models`](#models). - -Shorthand for providing a single model / dynamic segment. The following two -invocations are equivalent: - -```hbs - - -``` - -##### `@query` +### `LinkManager` Service Example -Optional. - -Query Params object. - -**Example** - -```hbs - - - Click me - - -``` - -**`{{link-to}}` equivalent** - -```hbs -{{#link-to "some.route" (query-params foo="bar")}} - Click me -{{/link-to}} -``` - -##### `@fromURL` - -Optional. Mutually exclusive with [`@route`](#route), [`@model`](#model) / -[`@models`](#models), [`@query`](#query). - -**Example** - -```hbs - - - Click me - - -``` - -##### `@preventDefault` - -Optional. Default: `true` - -If enabled, the [`transitionTo`](#transitionto) and -[`replaceWith`](#replacewith) actions will try to call -[`event.preventDefault()`][prevent-default] on the first argument, if it is an -event. This is an anti-foot-gun to make `` _just work™️_ with `` and -`