From 1c4d4cd3c6f20f15bef62ad4b163d60c7e426f19 Mon Sep 17 00:00:00 2001 From: Miguel Andrade Date: Fri, 11 Feb 2022 15:35:05 +0000 Subject: [PATCH] update docs-link (#1130) * update docs-link * octanify nested app. fix @query argument. * fix typo on upgrade docs --- addon/components/docs-link.js | 15 -------- addon/components/docs-link/index.hbs | 27 ++++++++++++++ addon/components/docs-link/index.js | 36 +++++++++++++++++++ addon/models/component.js | 4 ++- addon/models/module.js | 4 ++- package.json | 1 - test-apps/new-addon/package.json | 4 +++ .../tests/dummy/config/optional-features.json | 6 ++++ tests/dummy/app/templates/docs/patterns.md | 2 +- tests/dummy/app/templates/docs/quickstart.md | 10 +++--- .../dummy/app/templates/docs/upgrade-to-5.md | 23 ++++++++++++ yarn.lock | 12 +------ 12 files changed, 109 insertions(+), 35 deletions(-) delete mode 100644 addon/components/docs-link.js create mode 100644 addon/components/docs-link/index.hbs create mode 100644 addon/components/docs-link/index.js create mode 100644 test-apps/new-addon/tests/dummy/config/optional-features.json diff --git a/addon/components/docs-link.js b/addon/components/docs-link.js deleted file mode 100644 index d7891d158..000000000 --- a/addon/components/docs-link.js +++ /dev/null @@ -1,15 +0,0 @@ -import { classNames } from '@ember-decorators/component'; -import { LinkComponent } from '@ember/legacy-built-in-components'; - -/** - Just a styled subclass of LinkComponent. Comes in handy when rending links in Markdown templates: - - ```md - Here I am, telling you about another page - ``` - - @class DocsLink - @public -*/ -@classNames('docs-md__a') -export default class DocsLink extends LinkComponent {} diff --git a/addon/components/docs-link/index.hbs b/addon/components/docs-link/index.hbs new file mode 100644 index 000000000..d69f45d26 --- /dev/null +++ b/addon/components/docs-link/index.hbs @@ -0,0 +1,27 @@ +{{#let + (if + this.isRouteOnly + (component "link-to" route=@route) + (if + this.isRouteAndModelOnly + (component "link-to" route=@route model=@model) + (if + this.isRouteAndModelsOnly + (component "link-to" route=@route models=@models) + (component "link-to") + ) + ) + ) + as |DocsLinkTo| +}} + + {{yield}} + +{{/let}} \ No newline at end of file diff --git a/addon/components/docs-link/index.js b/addon/components/docs-link/index.js new file mode 100644 index 000000000..87f9020d7 --- /dev/null +++ b/addon/components/docs-link/index.js @@ -0,0 +1,36 @@ +import Component from '@glimmer/component'; + +/** + A `` styled alternative. See [ember docs](https://api.emberjs.com/ember/release/classes/Ember.Templates.components/methods/input?anchor=LinkTo) on how to use it. + + + ```hbs + + Go to post + + ``` + + @class DocsLink + @public +*/ +export default class DocsLink extends Component { + get isRouteOnly() { + return ( + 'route' in this.args && + !('model' in this.args) && + !('models' in this.args) + ); + } + + get isRouteAndModelOnly() { + return ( + 'route' in this.args && 'model' in this.args && !('models' in this.args) + ); + } + + get isRouteAndModelsOnly() { + return ( + 'route' in this.args && !('model' in this.args) && 'models' in this.args + ); + } +} diff --git a/addon/models/component.js b/addon/models/component.js index 18dfeb061..37d2b90b6 100644 --- a/addon/models/component.js +++ b/addon/models/component.js @@ -81,7 +81,9 @@ export default class Component extends Class { /* This gives us a way to link to a model, since we don't always link by the actual ID: - {{link-to 'item' model.routingId}} + + Go to item + Possible refactoring is to always link by actual ID, and implement redirects. */ diff --git a/addon/models/module.js b/addon/models/module.js index 0202dff30..dd084f699 100644 --- a/addon/models/module.js +++ b/addon/models/module.js @@ -19,7 +19,9 @@ export default class Module extends Model { /* This gives us a way to link to a model, since we don't always link by the actual ID: - {{link-to 'item' model.routingId}} + + Go to item + Possible refactoring is to always link by actual ID, and implement redirects. */ diff --git a/package.json b/package.json index 728b8254d..1b8c6f5ef 100644 --- a/package.json +++ b/package.json @@ -40,7 +40,6 @@ }, "dependencies": { "@csstools/postcss-sass": "^4.0.0", - "@ember/legacy-built-in-components": "^0.4.0", "@ember/render-modifiers": "^2.0.0", "@glimmer/component": "^1.0.4", "@glimmer/syntax": "^0.83.1", diff --git a/test-apps/new-addon/package.json b/test-apps/new-addon/package.json index b56c250f7..d313d98e8 100644 --- a/test-apps/new-addon/package.json +++ b/test-apps/new-addon/package.json @@ -25,6 +25,7 @@ }, "devDependencies": { "@ember/test-helpers": "*", + "@ember/optional-features": "*", "ember-cli-addon-docs": "*", "ember-cli-addon-docs-yuidoc": "*", "broccoli-asset-rev": "*", @@ -58,5 +59,8 @@ }, "ember-addon": { "configPath": "tests/dummy/config" + }, + "ember": { + "edition": "octane" } } diff --git a/test-apps/new-addon/tests/dummy/config/optional-features.json b/test-apps/new-addon/tests/dummy/config/optional-features.json new file mode 100644 index 000000000..b26286e2e --- /dev/null +++ b/test-apps/new-addon/tests/dummy/config/optional-features.json @@ -0,0 +1,6 @@ +{ + "application-template-wrapper": false, + "default-async-observers": true, + "jquery-integration": false, + "template-only-glimmer-components": true +} diff --git a/tests/dummy/app/templates/docs/patterns.md b/tests/dummy/app/templates/docs/patterns.md index 6b52f3d4a..06b7e6634 100644 --- a/tests/dummy/app/templates/docs/patterns.md +++ b/tests/dummy/app/templates/docs/patterns.md @@ -40,7 +40,7 @@ In addition to authoring normal Markdown content, you can Here's an example of an aside. -- Use Handlebars helpers. For example, you can use `` to render a link to the home page, or you can even render a component. +- Use Handlebars helpers. For example, you can use `` to render a link to the home page, or you can even render a component. ## Design for your audience diff --git a/tests/dummy/app/templates/docs/quickstart.md b/tests/dummy/app/templates/docs/quickstart.md index 7511772f1..b49de7f87 100644 --- a/tests/dummy/app/templates/docs/quickstart.md +++ b/tests/dummy/app/templates/docs/quickstart.md @@ -16,7 +16,7 @@ For both classic and native classes, install the [YUIDoc](http://yui.github.io/y ember install ember-cli-addon-docs-yuidoc ``` -You can see an example of {{docs-link 'an autodocumented YUIDoc component' 'sandbox.api.item' 'components/yuidoc-component'}} in the sandbox, and view its source [on GitHub](https://github.com/ember-learn/ember-cli-addon-docs/blob/master/sandbox/app/components/yuidoc-component.js). +You can see an example of an autodocumented YUIDoc component in the sandbox, and view its source [on GitHub](https://github.com/ember-learn/ember-cli-addon-docs/blob/master/sandbox/app/components/yuidoc-component.js). ## 3. Add the docs routes @@ -50,7 +50,7 @@ So let's start with the application template: {{outlet}} -`` is an AddonDocs component that renders a header using data from your addon's `package.json`. It renders a homepage link, documentation link, version selector, search bar, and link to your GitHub repository. Check out {{docs-link 'the guide' 'docs.components.docs-header'}} for more on the header. +`` is an AddonDocs component that renders a header using data from your addon's `package.json`. It renders a homepage link, documentation link, version selector, search bar, and link to your GitHub repository. Check out the guide for more on the header. At this point, fire up `ember s` and you should see your new docs site & header at `localhost:4200`! @@ -131,9 +131,9 @@ Remember, the dummy site is a full Ember application and these components are ju ## 8. Add some API docs to a component, object or function -As you document the public objects in your addon, they'll automatically show up in the left-hand navigation of your `docs` route under the "API REFERENCE" section, assuming you added the `` component. +As you document the public objects in your addon, they'll automatically show up in the left-hand navigation of your `docs` route under the "API REFERENCE" section, assuming you added the `` component. -Check out {{docs-link 'the sandbox' 'sandbox'}} for an example addon with autogenerated API docs on the side. You can also take a look [at the code on GitHub](https://github.com/ember-learn/ember-cli-addon-docs/tree/master/sandbox) to see how these objects were documented. +Check out the sandbox for an example addon with autogenerated API docs on the side. You can also take a look [at the code on GitHub](https://github.com/ember-learn/ember-cli-addon-docs/tree/master/sandbox) to see how these objects were documented. ## 9. Add a 404 route @@ -148,7 +148,7 @@ Add the following route to the end of your router and create the associated temp

Not found

-

This page doesn't exist. {{#docs-link "index"}}Head home?{{/docs-link}}

+

This page doesn't exist. Head home?

 diff --git a/tests/dummy/app/templates/docs/upgrade-to-5.md b/tests/dummy/app/templates/docs/upgrade-to-5.md index e21fe5d9c..7b3e5820a 100644 --- a/tests/dummy/app/templates/docs/upgrade-to-5.md +++ b/tests/dummy/app/templates/docs/upgrade-to-5.md @@ -87,4 +87,27 @@ Example: + + +### Link + +`` is now a glimmer component. + +#### Actions: +1. Use angle bracket invocation syntax +2. Replace the `{{docs-link}}` positional argument with named `@route` and/or `@model` argument +3. blockless usage is *not* supported + +Example: + + + + {{docs-link 'go to post' 'post' post.id}} + + + + + + go to post + \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index 5b74b914d..0dfb42b80 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1185,16 +1185,6 @@ resolved "https://registry.yarnpkg.com/@ember/edition-utils/-/edition-utils-1.2.0.tgz#a039f542dc14c8e8299c81cd5abba95e2459cfa6" integrity sha512-VmVq/8saCaPdesQmftPqbFtxJWrzxNGSQ+e8x8LLe3Hjm36pJ04Q8LeORGZkAeOhldoUX9seLGmSaHeXkIqoog== -"@ember/legacy-built-in-components@^0.4.0": - version "0.4.0" - resolved "https://registry.yarnpkg.com/@ember/legacy-built-in-components/-/legacy-built-in-components-0.4.0.tgz#23d61c9220c04d3590644ffe427cc987db4880a7" - integrity sha512-nm0tTe9d7aYpPa8sk85M4AZ3iDfuVQ4/7M4D4IdI7frkAOGpy6gAKS9nR/UR8mJDW06CLz9NYEKWIlLopEu/Og== - dependencies: - "@embroider/macros" "^0.47.1" - ember-cli-babel "^7.26.6" - ember-cli-htmlbars "^5.7.1" - ember-cli-typescript "^4.1.0" - "@ember/optional-features@^2.0.0": version "2.0.0" resolved "https://registry.yarnpkg.com/@ember/optional-features/-/optional-features-2.0.0.tgz#c809abd5a27d5b0ef3c6de3941334ab6153313f0" @@ -1245,7 +1235,7 @@ ember-cli-version-checker "^5.1.2" semver "^7.3.5" -"@embroider/macros@0.49.0", "@embroider/macros@^0.41.0", "@embroider/macros@^0.47.1", "@embroider/macros@^0.49.0", "@embroider/macros@^0.50.0 || ^1.0.0", "@embroider/macros@^1.0.0": +"@embroider/macros@0.49.0", "@embroider/macros@^0.41.0", "@embroider/macros@^0.49.0", "@embroider/macros@^0.50.0 || ^1.0.0", "@embroider/macros@^1.0.0": version "0.49.0" resolved "https://registry.yarnpkg.com/@embroider/macros/-/macros-0.49.0.tgz#65b4ed734d1266013a452aed2a3adb8694832112" integrity sha512-4VsvlE0h8l1LPI6V2VufQimf7LGkSXd9AJLsrGs4/W8SqqdJHv4oY2DGzX1c0Te4VcD61lIzCkeOkzN2PMV3WQ==