update docs-link (#1130)

* update docs-link * octanify nested app. fix @query argument. * fix typo on upgrade docs
ember-learn · Feb 11, 2022 · 1c4d4cd · 1c4d4cd
1 parent 5b9e6ba
commit 1c4d4cd
Show file tree

Hide file tree

Showing 12 changed files with 109 additions and 35 deletions.
diff --git a/addon/components/docs-link.js b/addon/components/docs-link.js
diff --git a/addon/components/docs-link/index.hbs 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|
+}}
+  <DocsLinkTo
+    class="docs-md__a"
+    @query={{or @query (hash)}}
+    @disabled={{@disabled}}
+    @activeClass={{@activeClass}}
+    @current-when={{@current-when}}
+    ...attributes
+  >
+    {{yield}}
+  </DocsLinkTo>
+{{/let}}
diff --git a/addon/components/docs-link/index.js b/addon/components/docs-link/index.js
@@ -0,0 +1,36 @@
+import Component from '@glimmer/component';
+
+/**
+  A `<LinkTo>` 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
+  <DocsLink @route="post" @model={{post.id}}>
+    Go to post
+  </DocsLink>
+  ```
+
+  @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
@@ -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}}
+      <LinkTo @route="item" @model={{model.routingId}}>
+        Go to item
+      </LinkTo>
 
     Possible refactoring is to always link by actual ID, and implement redirects.
   */

diff --git 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}}
+      <LinkTo @route="item" @model={{model.routingId}}>
+        Go to item
+      </LinkTo>
 
     Possible refactoring is to always link by actual ID, and implement redirects.
   */

diff --git 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
@@ -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
@@ -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
@@ -40,7 +40,7 @@ In addition to authoring normal Markdown content, you can
   Here's an example of an aside.
 </aside>
 
-- Use Handlebars helpers. For example, you can use `<LinkTo/>` to render a link to <DocsLink  @route="index">the home page</DocsLink>, or you can even render a component.
+- Use Handlebars helpers. For example, you can use `<LinkTo/>` to render a link to <DocsLink @route="index">the home page</DocsLink>, 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
@@ -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 <DocsLink @route="sandbox.api.item" @model="components/yuidoc-component">an autodocumented YUIDoc component</DocsLink> 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}}
 </DocsSnippet>
 
-`<DocsHeader />` 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.
+`<DocsHeader />` 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 <DocsLink @route="docs.components.docs-header">the guide</DocsLink> 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 `<DocsViewer />` 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 `<DocsViewer/>` 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 <DocsLink @route="sandbox">the sandbox</DocsLink> 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
 <DocsSnippet @name="quickstart-404.hbs" @title="tests/dummy/app/templates/not-found.hbs">
     <div style="max-width: 40rem; margin: 0 auto; padding: 0 1.5rem">
       <h1>Not found</h1>
-      <p>This page doesn't exist. {{#docs-link "index"}}Head home?{{/docs-link}}</p>
+      <p>This page doesn't exist. <DocsLink @route="index">Head home?</DocsLink></p>
     </div>
 </DocsSnippet>
 

diff --git 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:
 <DocsSnippet @name="upgrade-to-v5-logo-after.hbs" @title="After">
 
     <DocsLogo @logo="ember-cli"/>
+</DocsSnippet>
+
+### Link
+
+`<DocsLink/>` 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:
+
+<DocsSnippet @name="upgrade-to-v5-link-before.hbs" @title="Before">
+
+    {{docs-link 'go to post' 'post' post.id}}
+</DocsSnippet>
+
+<DocsSnippet @name="upgrade-to-v5-link-after.hbs" @title="After">
+
+    <DocsLink @route="post" @model={{post.id}}>
+      go to post
+    </DocsLink>
 </DocsSnippet>
diff --git 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/[email protected]", "@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/[email protected]", "@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==