ui: Improves UI engineering docs (#9875)

Also fixes some typos in with-overlay

ui/packages/consul-ui/.docfy-config.js

@@ -20,11 +20,44 @@ module.exports = {
     prism
   ],
   sources: [
+    {
+      root: path.resolve(__dirname, 'docs'),
+      pattern: '**/*.mdx',
+      urlSchema: 'auto',
+      urlPrefix: 'docs',
+    },
+    {
+      root: path.resolve(__dirname, 'app/modifiers'),
+      pattern: '**/*.mdx',
+      urlSchema: 'auto',
+      urlPrefix: 'docs/modifiers',
+    },
+    {
+      root: path.resolve(__dirname, 'app/helpers'),
+      pattern: '**/*.mdx',
+      urlSchema: 'auto',
+      urlPrefix: 'docs/helpers',
+    },
+    {
+      root: path.resolve(__dirname, 'app/services'),
+      pattern: '**/*.mdx',
+      urlSchema: 'auto',
+      urlPrefix: 'docs/services',
+    },
     {
       root: path.resolve(__dirname, 'app/components'),
-      pattern: '**/README.mdx',
+      pattern: '**(!consul)/README.mdx',
       urlSchema: 'auto',
       urlPrefix: 'docs/components',
+    },
+    {
+      root: path.resolve(__dirname, 'app/components/consul'),
+      pattern: '**/README.mdx',
+      urlSchema: 'auto',
+      urlPrefix: 'docs/consul',
     }
   ],
+  labels: {
+    "consul": "Consul Components"
+  }
 };

ui/packages/consul-ui/app/components/auth-dialog/README.mdx

@@ -1,7 +1,10 @@
-## AuthDialog
+---
+class: ember
+---
+# AuthDialog
 
-```hbs
+```hbs preview-template
-<AuthDialog @dc={{dc}} @nspace={{ns}} @onchange={{action 'change'}} as |api components|>
+<AuthDialog @dc={{'dc-1'}} @nspace={{'default'}} @onchange={{action (noop)}} as |api components|>
   {{#let components.AuthForm components.AuthProfile as |AuthForm AuthProfile|}}
     <BlockSlot @name="unauthorized">
       Here's the login form:
@@ -10,7 +13,7 @@
     <BlockSlot @name="authorized">
       Here's your profile:
       <AuthProfile />
-      <button onclick={{action api.logout}} />
+      <button onclick={{action api.logout}}>Logout</button>
     </BlockSlot>
   {{/let}}
 </AuthDialog>

ui/packages/consul-ui/app/components/auth-form/README.mdx

@@ -1,6 +1,9 @@
-## AuthForm
+---
+class: ember
+---
+# AuthForm
 
-```handlebars
+```hbs preview-template
 <AuthForm as |api|></AuthForm>
 ```
 

ui/packages/consul-ui/app/components/auth-profile/README.mdx

@@ -1,11 +1,16 @@
-## AuthProfile
+---
+class: ember
+---
+# AuthProfile
 
-```hbs
+```hbs preview-template
-<AuthProfile @item={{token}} />
+<AuthProfile @item={{hash AccessorID='123456-1234567-123456'}} />
 ```
 
 A straightforward partial-like component for rendering a user profile.
 
+Only the last 8 characters are shown.
+
 ### Arguments
 
 | Argument | Type | Default | Description |

ui/packages/consul-ui/app/components/consul/loader/README.mdx

@@ -1,13 +1,13 @@
-## Consul::Loader
+# Consul::Loader
 
-`<Consul::Loader />`
+```hbs preview-template
+<div style="position: relative;height: 300px;width: 300px;margin: 0 auto;">
+  <Consul::Loader />
+</div>
+```
 
 Simple template-only component to show the circular animated Consul loader animation.
 
-| Argument | Type | Default | Description |
-| --- | --- | --- | --- |
-
-
 ### See
 
 - [Component Source Code](./index.js)

ui/packages/consul-ui/app/components/consul/lock-session/list/README.mdx

@@ -1,10 +1,15 @@
-## ConsulLockSessionList
+---
+class: ember
+---
+# Consul::LockSession::List
 
-```
+```hbs preview-template
-<ConsulLockSessionList
+<DataSource @src="/default/dc-1/sessions/for-node/my-node" as |source|>
-  @items={{items}}
+  <Consul::LockSession::List
-  @onInvalidate={{action send 'invalidateSession'}}
+    @items={{source.data}}
+    @onInvalidate={{action (noop)}}
   />
+</DataSource>
 ```
 
 A presentational component for rendering Node Lock Sessions

ui/packages/consul-ui/app/components/consul/metadata/list/README.mdx

@@ -1,23 +1,27 @@
-## ConsulMetadataList
+---
-
+class: ember
-`<ConsulMetadataList @items={{meta}} />`
+---
+# Consul::Metadata::List
 
 A presentational component for presenting Consul Metadata
 
+The following example shows how to construct the required structure from the Consul API using ember-componsable-helpers' `entries` helper.
+
+```hbs
+<DataSource @src="/default/dc-1/service-instance/service-id/node-0/service-0" as |source|>
+  <Consul::Metadata::List
+    @items={{entries source.data.firstObject.Meta}}
+  />
+</DataSource>
+```
+
+
 ### Arguments
 
 | Argument/Attribute | Type | Default | Description |
 | --- | --- | --- | --- |
 | `items` | `array` |  | An array of entries or `[key, value]` pairs as returned by `Object.entries()` |
 
-### Example
-
-The following example shows how to construct the required structure from the
-Consul API using a `object-entries` helper.
-
-```hbs
-  <ConsulMetadataList @items={{object-entries item.Meta}} />
-```
 
 ### See
 

ui/packages/consul-ui/app/components/consul/nspace/list/README.mdx

@@ -1,10 +1,15 @@
-## ConsulNspaceList
+---
+class: ember
+---
+## Consul::Nspace::List
 
-```
+```hbs
-<ConsulNspaceList
+<DataSource @src="/default/dc-1/namespaces" as |source|>
-  @items={{items}}
+  <Consul::Nspace::List
-  @ondelete={{action 'delete'}}
+    @items={{source.data}}
+    @ondelete={{action (noop)}}
   />
+</DataSource>
 ```
 
 A presentational component for rendering Consul Namespaces

ui/packages/consul-ui/app/components/consul/policy/list/README.mdx

@@ -1,9 +1,9 @@
-## ConsulPolicyList
+# Consul::Policy::List
 
-```
+```hbs
-<ConsulPolicyList
+  <Consul::Policy::List
     @items={{items}}
-  @ondelete={{action 'delete'}}
+    @ondelete={{action (noop)}}
   />
 ```
 

ui/packages/consul-ui/app/components/consul/role/list/README.mdx

@@ -1,7 +1,7 @@
-## ConsulRoleList
+## Consul::Role::List
 
-```
+```hbs
-<ConsulRoleList
+<Consul::Role::List
   @items={{items}}
   @ondelete={{action 'delete'}}
 />

ui/packages/consul-ui/app/components/consul/token/list/README.mdx

@@ -1,7 +1,7 @@
-## ConsulTokenList
+## Consul::Token::List
 
-```
+```hbs
-<ConsulTokenList
+<Consul::Token::List
   @items={{items}}
   @token={{userToken}}
   @onuse={{action 'use'}}

ui/packages/consul-ui/app/components/consul/token/ruleset/list/README.mdx

@@ -1,7 +1,7 @@
-## ConsulTokenRulesetList
+## Consul::Token::Ruleset::List
 
-```
+```hbs
-<ConsulTokenRulesetList
+<Consul::Token::Ruleset::List
   @item={{item}}
 />
 ```

ui/packages/consul-ui/app/components/copy-button/README.mdx

@@ -1,11 +1,17 @@
 # CopyButton
 
 ```hbs preview-template
+<p>
+  Icon Only:
+</p>
 <CopyButton
   @value={{stringToCopy}}
   @name="Thing"
 />
 
+<p>
+  Icon and text:
+</p>
 <CopyButton
   @value={{stringToCopy}}
   @name="Thing"

ui/packages/consul-ui/app/components/data-collection/README.mdx

@@ -1,4 +1,7 @@
-## DataCollection
+---
+class: ember
+---
+# DataCollection
 
 ```hbs
 <DataCollection
@@ -7,7 +10,7 @@
   @filter={{hash
     searchproperties=(array)
   }}
-  @items={{array}}
+  @items={{array 'hi'}}
 as |collection|>
   {{collection.items.length}}
   <collection.Collection>

ui/packages/consul-ui/app/components/data-sink/README.mdx

@@ -1,3 +1,6 @@
+---
+class: ember
+---
 ## DataSink
 
 ```hbs

ui/packages/consul-ui/app/components/event-source/README.mdx

@@ -1,4 +1,7 @@
-## EventSource
+---
+class: ember
+---
+# EventSource
 
 ```hbs
 <EventSource

ui/packages/consul-ui/app/components/jwt-source/README.mdx

@@ -1,4 +1,7 @@
-## JwtSource
+---
+class: ember
+---
+# JwtSource
 
 ```hbs
 <JwtSource @src={{url}} @onchange={{action 'change'}} @onerror={{action 'error'}} />

ui/packages/consul-ui/app/components/ref/README.mdx

@@ -1,4 +1,7 @@
-## Ref
+---
+class: ember
+---
+# Ref
 
 `<Ref @target={{this}} @name="api" @value={{api}} />`
 

ui/packages/consul-ui/app/components/state-chart/README.mdx

@@ -1,4 +1,7 @@
-## StateChart
+---
+class: ember
+---
+# StateChart
 
 ```hbs
 <StateChart

ui/packages/consul-ui/app/components/state/README.mdx

@@ -1,4 +1,7 @@
-## State
+---
+class: ember
+---
+# State
 
 `<State @state={{matchableStateObject}} @matches="idle">Currently Idle</State>`
 

ui/packages/consul-ui/app/components/toggle-button/README.mdx

@@ -1,3 +1,6 @@
+---
+class: ember
+---
 ## ToggleButton
 
 `<ToggleButton checked="checked" @onchange={{action 'change'}} as |api|>Toggle</ToggleButton>`

ui/packages/consul-ui/app/components/token-source/README.mdx

@@ -1,3 +1,6 @@
+---
+class: ember
+---
 ## TokenSource
 
 ```hbs

ui/packages/consul-ui/app/helpers/flatten-property.js

@@ -0,0 +1,8 @@
+import { helper } from '@ember/component/helper';
+
+export default helper(function flattenProperty([obj, prop], hash) {
+  const pages = hash.pages || [];
+  pages.push(...obj.pages);
+  obj.children.forEach(child => flattenProperty([child], { pages: pages }));
+  return pages;
+});

ui/packages/consul-ui/app/helpers/is-href.mdx

@@ -0,0 +1,34 @@
+# is-href
+
+`{{is-href routeName}}` is used to determine whether the current route is the
+specified route, for example:
+
+```hbs preview-template
+<style>
+  .is-active {
+    color: red;
+  }
+</style>
+<ul>
+  <li class={{if (is-href 'docs.helpers.is-href') 'is-active'}}>
+    Active
+  </li>
+  <li class={{if (is-href 'docs.helpers.not-is-href') 'is-active'}}>
+    Not Active
+  </li>
+</ul>
+```
+
+The Consul UI generally uses this on `<li>` elements of navigation, not the
+`<a>` anchors themselves. There are cases of course where we need this for
+links that are not in `<li>`s so its fine to use it on the `<a>` in those
+cases.
+
+We currently use the `is-active` classname throughout the app to mirror the
+ember `<LinkTo />` class used for the same purpose.
+
+Different to `ember-href-to` and `<LinkTo />` our custom `is-href` helper will
+become `true` when you begin the transition to the specified route, not when
+the specified route is loaded. This means active states will happen when the
+user clicks the link and will remain active through the loading state until
+the user clicks on another link.

ui/packages/consul-ui/app/helpers/to-route.js

@@ -0,0 +1,12 @@
+import Helper from '@ember/component/helper';
+import { inject as service } from '@ember/service';
+
+export default class ToRouteHelper extends Helper {
+  @service('router') router;
+  @service('env') env;
+
+  compute([url]) {
+    const info = this.router.recognize(`${this.env.var('rootURL')}${url}`);
+    return info.name;
+  }
+}

ui/packages/consul-ui/app/instance-initializers/selection.js

@@ -19,10 +19,15 @@ export default {
       return;
     }
     const dom = container.lookup('service:dom');
+    const doc = dom.document();
+    const $html = doc.getElementsByTagName('html')[0];
     const findAnchor = function(el) {
       return el.tagName === 'A' ? el : dom.closest('a', el);
     };
     const mousedown = function(e) {
+      if ($html.classList.contains('is-debug')) {
+        return;
+      }
       const $a = findAnchor(e.target);
       if ($a) {
         if (typeof e.button !== 'undefined' && e.button === SECONDARY_BUTTON) {
@@ -40,6 +45,9 @@ export default {
       }
     };
     const mouseup = function(e) {
+      if ($html.classList.contains('is-debug')) {
+        return;
+      }
       const $a = findAnchor(e.target);
       if ($a) {
         const href = $a.dataset.href;
@@ -49,13 +57,13 @@ export default {
       }
     };
 
-    document.body.addEventListener('mousedown', mousedown);
+    doc.body.addEventListener('mousedown', mousedown);
-    document.body.addEventListener('mouseup', mouseup);
+    doc.body.addEventListener('mouseup', mouseup);
 
     container.reopen({
       willDestroy: function() {
-        document.body.removeEventListener('mousedown', mousedown);
+        doc.body.removeEventListener('mousedown', mousedown);
-        document.body.removeEventListener('mouseup', mouseup);
+        doc.body.removeEventListener('mouseup', mouseup);
         return this._super(...arguments);
       },
     });

ui/packages/consul-ui/app/modifiers/disabled.mdx

@@ -0,0 +1,39 @@
+# disabled
+
+The disabled modifer works similarly to the [`<fieldset disabled>`
+attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset#attr-disabled),
+in that it will disable all form elements within the fieldset, which is really
+useful for controlling disabled states of entire forms with just one
+modifier/attributes
+
+There are three downsides to the `<fieldset disabled>` attribute:
+
+1. It only works for fieldsets and its descendants.
+2. fieldsets can cause trouble with flex-box
+3. You cannot opt out for an individual form element. Say if you want to say 'all but one of these form elements should be disabled'
+
+Therefore we use a `{{disabled true|false}}` modifier to work around these
+downsides.
+
+The following shows a disabling a group of form elements but excluding one
+single form element from being disabled.
+
+<style>
+  input {
+    border: 1px solid black;
+  }
+</style>
+
+```hbs preview-template
+<div
+  {{disabled true}}
+>
+  Disabled: <input type="text" placeholder="Disabled" /><br />
+  Disabled: <input type="checkbox" /><br />
+  Enabled: <input
+    {{disabled false}}
+    placeholder="Not disabled"
+    type="text"
+  />
+</div>
+```

ui/packages/consul-ui/app/modifiers/tooltip.mdx

@@ -0,0 +1,37 @@
+# tooltip
+
+Our tooltip modifier is a thin wrapper around the excellent `tippy.js`. The
+most common usage will be something like the below:
+
+```hbs preview-template
+<span
+  {{tooltip "Tooltip message"}}
+>
+  Hover over me
+</span>
+```
+
+An additional options hash can be passed into the tooltip the contents of
+which are passed along to `tippy.js` [so all of the `tippy.js`
+props](https://atomiks.github.io/tippyjs/v5/all-props/) can be used to control
+tooltips, including `tippy.js` plugins.
+
+```hbs preview-template
+
+
+<span
+  {{tooltip "Tooltip message" options=(hash
+    showOnCreate=true
+    hideOnClick=false
+    placement="bottom"
+  )}}
+>
+  No need to hover over me
+</span>
+```
+
+An options hash has been chosen to begin, as and when its clear what common
+groups of settings are used throughout the app we can add new properties to
+the modifer without the risk of clashing with any `tippy.js` props.
+
+We also have a Tooltip component but this modifier is preferred over that.

ui/packages/consul-ui/app/modifiers/with-overlay.js

@@ -40,7 +40,7 @@ export default modifier(($element, [content], hash = {}) => {
     // amount of time specified by the delay
     const delay = options.delay || [];
     if (typeof delay[1] !== 'undefined') {
-      hash.options.onShown = popover => {
+      options.onShown = popover => {
         clearInterval(interval);
         interval = setTimeout(() => {
           popover.hide();
@@ -58,7 +58,7 @@ export default modifier(($element, [content], hash = {}) => {
     plugins: [typeof options.followCursor !== 'undefined' ? followCursor : undefined].filter(item =>
       Boolean(item)
     ),
-    ...hash.options,
+    ...options,
   });
   if (hash.returns) {
     hash.returns(popover);

ui/packages/consul-ui/app/modifiers/with-overlay.mdx

@@ -0,0 +1,31 @@
+# with-overlay
+
+Our `{{with-overlay}}` modifier is a thin wrapper around the excellent `tippy.js`. The most common usage will be something like the below:
+
+```hbs preview-template
+<div
+  {{did-insert (set this 'popover')}}
+>
+  The popover
+</div>
+<button
+  {{with-overlay
+    this.popover
+    returns=(set this 'popoverController')
+  }}
+
+  {{on 'click' (fn (optional this.popoverController.show))}}
+>
+  Click me
+</button>
+```
+
+The first positional parameter is a reference to a DOM element to use for the
+popover. The easiest way to provide this is to use `{{did-insert
+(set this 'popoverName'}}}` on any DOM element (as seen above). This DOM element is then
+automatically removed from the DOM until the popover needs to be shown.
+
+The `returns` named attribute of the modifer allows you to save a reference to
+the overlay itself, which is a reference to a [tippy.js instance](https://atomiks.github.io/tippyjs/v5/methods/).
+This instance can then be used with conventional ember to control the overlay. In the example above we use `{{on 'click'}}` to show the overlay but once you have a reference to the tippy.js instance you can control it by any other means.
+

ui/packages/consul-ui/app/services/env.mdx

@@ -0,0 +1,14 @@
+# env
+
+Our env service (along with the `env` helper which is backed by this service)
+is used to access various global 'environment style' variables throughout the
+app.
+
+```js
+export default class extends Ability {
+  @service('env') env;
+  canRead() {
+    return this.env.var('CONSUL_ACLS_ENABLED');
+  }
+}
+```

ui/packages/consul-ui/app/styles/base/icons/base-variables.scss

@@ -48,6 +48,7 @@ $disabled-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fi
 $docs-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M18 11h2v9.5c0 .786-.714 1.5-1.5 1.5h-14c-.786 0-1.5-.714-1.5-1.5v-17C3 2.714 3.714 2 4.5 2H13v2H5v16h13v-9zM7 17.714h9v-1.428H7v1.428zm0-2.857h9V13.43H7v1.427zM7 12h9v-1.429H7V12zm0-4.286V6.286h5v1.428H7zM17 2.5V1h6v6h-1.5V3.429L18 7l-1-1 3.5-3.5H17z" fill="%23000"/></svg>');
 $download-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M19 9h-4V3H9v6H5l7 7 7-7zM5 18v2h14v-2H5zm-2 2h2v-4H3v4zm16 0h2v-4h-2v4z" fill="%23000"/></svg>');
 $edit-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M17.23 9.68l1.326-1.324a1.016 1.016 0 0 0 0-1.437l-1.62-1.621h-.001l-.001-.001a1.015 1.015 0 0 0-1.436 0l-1.325 1.327L17.23 9.68zM5 18.855v-3.058l8.154-8.153 3.057 3.057-8.153 8.154H5zm2.038-3.058H6.02v2.038h2.038v-1.018h-1.02v-1.02z" fill="%23000"/></svg>');
+$ember-circle-logo-color-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 128 128" xmlns="http://www.w3.org/2000/svg"><g fill="none" fill-rule="evenodd"><path d="M64 0c35.346 0 64 28.654 64 64 0 35.346-28.654 64-64 64-35.346 0-64-28.654-64-64C0 28.654 28.654 0 64 0z" fill="%23E05C43" fill-rule="nonzero"/><path d="M65.265 24.128c8.246-.163 14.073 2.073 19.087 9.19 10.934 27.109-28.147 41.1-29.714 41.65l-.049.016s-1.18 7.363 10.028 7.08c13.793 0 28.294-10.691 33.81-15.21a3.293 3.293 0 0 1 4.468.265l4.13 4.29a3.291 3.291 0 0 1 .085 4.491c-3.59 3.997-12.014 12.203-24.696 17.504 0 0-21.16 9.798-35.42.52-8.503-5.53-10.842-12.151-11.793-19.038.005 0-10.324-.524-16.957-3.114-6.635-2.592.049-10.411.049-10.411s2.04-3.233 5.92 0c3.883 3.228 11.13 1.772 11.13 1.772.646-5.099 1.72-11.828 4.884-18.93 6.632-14.885 16.789-19.915 25.038-20.075zm4.853 14.915c-4.369-4.21-16.984 4.202-17.471 23.45 0 0 3.724 1.134 11.97-4.53 8.25-5.661 9.87-14.718 5.501-18.92z" fill="%23FFF"/></g></svg>');
 $envelope-sealed-fill-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M4 4a2 2 0 0 0-2 2l9.486 5.691a1 1 0 0 0 1.028 0L22 6a2 2 0 0 0-2-2H4zm18 4l-4.383 2.63L22 15.5V8zm0 10l-5.94-6.436-3.545 2.127a1 1 0 0 1-1.03 0l-3.544-2.127L2 18a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2zM2 15.5l4.383-4.87L2 8v7.5z" fill="%23000"/></svg>');
 $envelope-sealed-outline-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M4 4h16a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2zm0 5.2v6.3l3.682-4.09L4 9.2zm0-2V6h16v1.2l-7.486 4.491a1 1 0 0 1-1.028 0L4 7.2zm16 2l-3.682 2.21L20 15.5V9.2zm0 8.8l-5.228-5.663-2.258 1.354a1 1 0 0 1-1.028 0l-2.258-1.354L4 18h16z" fill="%23000"/></svg>');
 $envelope-unsealed--outline-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M2.004 8.002a2 2 0 0 1 1.119-1.668l8.438-4.12a1 1 0 0 1 .878 0l8.438 4.12a2 2 0 0 1 1.119 1.668L22 8v11.882a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V8l.004.002zM4 11.2v6.3l3.682-4.09L4 11.2zM4 20l5.228-5.663 2.258 1.354a1 1 0 0 0 1.028 0l2.258-1.354L20 20H4zm16-2.5v-6.3l-3.682 2.21L20 17.5zm0-8.3l-7.486 4.491a1 1 0 0 1-1.028 0L4 9.2V8l7.553-3.776a1 1 0 0 1 .894 0L20 8v1.2z" fill="%23000"/></svg>');
@@ -69,6 +70,7 @@ $git-branch-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24"
 $git-commit-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M12 14.971a2.82 2.82 0 0 1-2.829-2.828A2.82 2.82 0 0 1 12 9.314a2.82 2.82 0 0 1 2.829 2.829A2.82 2.82 0 0 1 12 14.97zm4.963-4.114C16.384 8.646 14.39 7 12 7s-4.384 1.646-4.963 3.857H3v2.572h4.037C7.616 15.64 9.61 17.286 12 17.286s4.384-1.646 4.963-3.857H21v-2.572h-4.037z" fill="%23000"/></svg>');
 $git-pull-request-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M7.398 8.04c-.792 0-1.44-.66-1.44-1.44 0-.78.66-1.44 1.44-1.44.78 0 1.44.66 1.44 1.44 0 .78-.66 1.44-1.44 1.44zm1.44 10.56c0 .792-.66 1.44-1.44 1.44-.78 0-1.44-.66-1.44-1.44 0-.781.66-1.44 1.44-1.44.78 0 1.44.659 1.44 1.44zm.96-12c0-1.332-1.068-2.4-2.4-2.4a2.391 2.391 0 0 0-1.2 4.464v7.872A2.39 2.39 0 0 0 7.398 21a2.39 2.39 0 0 0 1.2-4.464V8.664a2.386 2.386 0 0 0 1.2-2.064zm7.2 13.44c-.792 0-1.44-.66-1.44-1.44 0-.781.66-1.44 1.44-1.44.78 0 1.44.659 1.44 1.44 0 .78-.66 1.44-1.44 1.44zm1.2-3.504V9c-.035-.936-.407-1.764-1.128-2.472-.72-.708-1.536-1.092-2.472-1.128h-1.2V3l-3.6 3.6 3.6 3.6V7.8h1.2c.324.024.576.132.829.372.252.24.36.504.372.828v7.536a2.392 2.392 0 0 0 1.2 4.464 2.39 2.39 0 0 0 1.2-4.464z" fill="%23000"/></svg>');
 $git-repository-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M20 19V4c0-1-1-2-2-2H6C5 2 4 3 4 4v15c0 1 1 2 2 2h1v3l2-2 2 2v-3h7c1 0 2-1 2-2zM9 5H7v2h2V5zM7 8h2v2H7V8zm0 3h2v2H7v-2zm11 5H6v3h1v-2h4v2h7v-3zM6 4h12v11H6V4z" fill="%23000"/></svg>');
+$glimmer-logo-color-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 256 256" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid"><path d="M256 128c0 70.692-57.308 128-128 128C57.307 256 0 198.692 0 128 0 57.308 57.307 0 128 0c70.692 0 128 57.308 128 128" fill="%23F8835A"/><path d="M78.63 140.37a11.39 11.39 0 0 1-7.951-3.222c-4.533-4.392-4.648-11.627-.256-16.16l77.144-79.619c4.39-4.533 11.626-4.648 16.16-.256 4.532 4.392 4.647 11.628.255 16.161l-77.143 79.62a11.397 11.397 0 0 1-8.21 3.475zm50.31 3.036a11.356 11.356 0 0 1-7.926-3.21c-4.52-4.38-4.633-11.592-.254-16.111L181.687 61.2c4.379-4.52 11.59-4.632 16.11-.254s4.634 11.59.256 16.11l-60.928 62.884a11.363 11.363 0 0 1-8.184 3.465zm-24.69 79.286a11.383 11.383 0 0 1-7.951-3.221c-4.533-4.391-4.648-11.627-.256-16.16L202.61 93.322c4.39-4.532 11.627-4.647 16.16-.255 4.534 4.392 4.648 11.627.255 16.161L112.459 219.216a11.397 11.397 0 0 1-8.21 3.476zm-33.44-19.44c-2.865 0-5.73-1.07-7.95-3.222-4.534-4.392-4.649-11.628-.257-16.16l29.053-29.986c4.393-4.533 11.628-4.648 16.161-.256 4.533 4.393 4.647 11.628.255 16.161L79.02 199.775a11.397 11.397 0 0 1-8.209 3.476zm-23.179-86.764a11.39 11.39 0 0 1-7.952-3.221c-4.533-4.392-4.647-11.627-.255-16.16L68.477 67.12c4.393-4.533 11.628-4.647 16.161-.255 4.533 4.392 4.647 11.627.255 16.16L55.84 113.013a11.398 11.398 0 0 1-8.209 3.476zm149.433 65.295a11.39 11.39 0 0 1-7.95-3.221c-4.534-4.392-4.649-11.627-.257-16.16l13.754-14.195c4.391-4.532 11.627-4.65 16.16-.255 4.533 4.392 4.647 11.627.255 16.16l-13.753 14.195a11.397 11.397 0 0 1-8.209 3.476zm-26.78 28.338c0 6.312-5.117 11.428-11.43 11.428-6.31 0-11.428-5.116-11.428-11.428 0-6.312 5.118-11.429 11.429-11.429 6.312 0 11.429 5.117 11.429 11.43zM61.06 158.925c0 6.312-5.117 11.43-11.43 11.43-6.311 0-11.427-5.118-11.427-11.43 0-6.312 5.116-11.428 11.428-11.428 6.312 0 11.429 5.116 11.429 11.428zm54.284-112.142c0 6.312-5.117 11.428-11.428 11.428-6.312 0-11.429-5.116-11.429-11.428 0-6.312 5.117-11.43 11.429-11.43 6.311 0 11.428 5.118 11.428 11.43z" fill="%23FFF"/></svg>');
 $hashicorp-logo-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 107 114" width="100%" height="100%" xmlns="http://www.w3.org/2000/svg"><path d="M44.54 0L0 25.69V87.41l16.73 9.66V35.35L44.54 19.3z"/><path d="M62.32 0v49.15H44.54V30.81L27.8 40.47v62.97l16.74 9.68V64.11h17.78v18.22l16.73-9.66V9.66z"/><path d="M62.32 113.14l44.54-25.69V25.73l-16.74-9.66v61.72l-27.8 16.05z"/></svg>');
 $health-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M9.5 8.5l5 10.5 3.5-6h4v-2h-5l-2.5 4.5L9.5 5 6 11H2v2h5l2.5-4.5z" fill="%23000"/></svg>');
 $help-circle-fill-svg: url('data:image/svg+xml;charset=UTF-8,<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 17h-2v-2h2v2zm2.07-7.75l-.9.92C13.45 12.9 13 13.5 13 15h-2v-.5c0-1.1.45-2.1 1.17-2.83l1.24-1.26c.37-.36.59-.86.59-1.41 0-1.1-.9-2-2-2s-2 .9-2 2H8c0-2.21 1.79-4 4-4s4 1.79 4 4c0 .88-.36 1.68-.93 2.25z" fill="%23000"/></svg>');

ui/packages/consul-ui/app/styles/base/icons/icon-placeholders.scss

@@ -488,6 +488,11 @@
   mask-image: $edit-svg;
 }
 
+%with-ember-circle-logo-color-icon {
+  @extend %with-icon;
+  background-image: $ember-circle-logo-color-svg;
+}
+
 %with-envelope-sealed-fill-icon {
   @extend %with-icon;
   background-image: $envelope-sealed-fill-svg;
@@ -698,6 +703,10 @@
   mask-image: $git-repository-svg;
 }
 
+%with-glimmer-logo-color-icon {
+  @extend %with-icon;
+  background-image: $glimmer-logo-color-svg;
+}
 %with-hashicorp-logo-icon {
   @extend %with-icon;
   background-image: $hashicorp-logo-svg;

ui/packages/consul-ui/app/styles/debug.scss

@@ -1,13 +1,68 @@
 @import './base/reset/index';
 @import './base/index';
 @import 'prism-coldark-dark';
-
 .docs {
-  main {
+  .tabular-collection,
-    background-color: white;
+  .list-collection {
+    height: 300px !important;
+  }
+  nav:first-of-type {
+    & {
+      padding-top: 0 !important;
+    }
+    ul {
+      margin-bottom: 100px;
+      padding-top: 0 !important;
+    }
+    li.consul-components a::before,
+    li.components a::before {
+      @extend %with-glimmer-logo-color-icon, %as-pseudo;
+      margin-right: 5px;
+    }
+    li.consul-components.ember-component a::before,
+    li.components.ember-component a::before {
+      @extend %with-ember-circle-logo-color-icon, %as-pseudo;
+    }
+  }
+  main {
+    & {
+      background-color: white;
+      margin-bottom: 2rem;
+    }
+    ol,
+    ul {
+      list-style-position: inside;
+      margin-bottom: 1rem;
+    }
+  }
+  .docfy-demo {
+    & {
+      margin-bottom: 1rem;
+    }
+    &__example {
+      & {
+        border-top: 1px solid;
+        border-left: 1px solid;
+        border-right: 1px solid;
+        border-color: var(--gray-200);
+        padding: 1rem;
+        margin-bottom: 0;
+      }
+      ol,
+      ul {
+        margin-bottom: 0;
+      }
+    }
+    // &__snippets__tabs__button {
+    //   display: none;
+    // }
+    &__snippet {
+      pre {
+        margin: 0 !important;
+        border-bottom-left-radius: 5px;
+        border-bottom-right-radius: 5px;
+      }
     }
-  [class^='docfy'] {
-    margin-bottom: 1em;
   }
   h1,
   h2,

ui/packages/consul-ui/app/templates/debug.hbs

@@ -1,11 +1,33 @@
+<HeadLayout />
+{{page-title 'Engineering Docs - Consul' separator=' - '}}
+
+{{document-attrs class="is-debug"}}
 <App class="docs" id="wrapper">
   <:main-nav>
+
     <DocfyOutput as |node|>
       <ul>
+          <li role="separator">Docs</li>
 {{#each node.children as |child|}}
-          {{#each child.children as |child|}}
   {{#each child.pages as |child|}}
-                  <li>
+          <li
+            class={{if (is-href (to-route child.url)) 'is-active'}}
+          >
+            <DocfyLink @to={{child.url}}>
+              {{child.title}}
+            </DocfyLink>
+          </li>
+  {{/each}}
+  {{#each child.children as |section|}}
+          <li role="separator">{{section.label}}</li>
+    {{#each (flatten-property section 'pages') as |child|}}
+          <li
+            class={{concat
+              (slugify section.label) ' '
+              (if (eq child.frontmatter.class 'ember') 'ember-component') ' '
+              (if (is-href (to-route child.url)) 'is-active')
+            }}
+          >
             <DocfyLink @to={{child.url}}>
               {{child.title}}
             </DocfyLink>
@@ -18,7 +40,9 @@
 
   </:main-nav>
   <:main>
+    <DocfyOutput @fromCurrentURL={{true}} as |page|>
       {{outlet}}
+    </DocfyOutput>
   </:main>
 </App>
 

ui/packages/consul-ui/docs/bookmarklets.mdx

@@ -0,0 +1,21 @@
+# Debug/Engineering Utilities
+
+The Consul UI has a set of debug/engineering utility functions that only exist in non-production environments (they are noop'ed from production builds using Ember's `runInDebug`). You can call these either straight from Web Inspectors `console`, or by using `javascript:` URLs i.e. `javascript:Routes()`.
+
+Below is a list of the most commonly used functions as bookmarklets followed by more detailed documentation on these utilities. The bookmarklets can be added to your browser by dragging the bookmarklet link into your browsers Bookmarks Bar.
+
+| Link/Bookmarklet | Description |
+| ---- | ----------- |
+| [Print Routing DSL](javascript:Routes()) | Print out Ember's Route DSL for the application |
+| [Save Current Scenario](javascript:Scenario()) | Opens a tab with links to allow you to create a bookmarklet or share a URL of your current scenario (your Consul UI relarted development/debug cookies) |
+| [Enable ACLs](javascript:Scenario('CONSUL_ACLS_ENABLE=1')) | Enable ACLs |
+| [Enable Nspaces](javascript:Scenario('CONSUL_NSPACES_ENABLE=1')) | Enable Namespace Support |
+| [Enable SSO ](javascript:Scenario('CONSUL_SSO_ENABLE=1')) | Enable SSO Support |
+| [Enable Metrics](javascript:Scenario('CONSUL_METRICS_PROXY_ENABLE=1;CONSUL_METRICS_PROVIDER=prometheus')) | Enable all configuration required for viewing the full Metrics Visualization |
+
+| Function | Arguments | Description |
+| -------- | --------- | ----------- |
+| `Routes(url)` | url: The url to pass the DSL to, if left `undefined` just use a blank tab | Provides a way to easily print out Embers Route DSL for the application or to pass it straight to any third party utility such as ember-diagonal |
+| `Scenario(str)` | str: 'Cookie formatted' string, if left `undefined` open a new tab with a link/bookmarklet to the current Scenario | Provides a way to easily save and reload scenarios of configurations via URLs or bookmarklets |
+
+

ui/packages/consul-ui/docs/index.mdx

@@ -0,0 +1,29 @@
+---
+title: Introduction
+---
+# Consul UI Engineering Docs
+
+Welcome to Consul UIs engineering documentation.
+
+## Adding documentation
+
+Our documentation use [docfy](https://docfy.dev/docs) for rendering our markdown+glimmer-component documentation. In order to live render any code examples use the `preview-template` meta, for example:
+
+~~~md
+```hbs preview-template
+<YourComponent
+  @thing={{var}}
+/>
+```
+~~~
+
+The above will render the same code snippet in a box above the snippet.
+
+The location and name of markdown files within the project differs slightly depending on what you need to add documentation for:
+
+- **docs**: `docs/filename.mdx`
+- **components**: `components/your-component-name/README.mdx`
+- **helpers**: `helpers/your-helper-name.mdx`
+- **modifiers**: `modifiers/your-modifier-name.mdx`
+- **services**: `services/your-service-name.mdx` (eventually these will partly use jsdoc code style generation)
+

ui/packages/consul-ui/docs/significant-patterns.mdx

@@ -0,0 +1,108 @@
+# Significant patterns
+
+The Consul UI tries to follow typical conventional ember but differs
+significantly in several places:
+
+## Routing
+
+We use a declarative configuration format for our routing rather than Ember's
+DSL. The format is closely modeled on Ember's DSL and if you need to generate
+Ember's DSL from this for some reason you can use one of our Debug Utilities
+to do this.
+
+## Routes
+
+We use a specific BaseRoute as a parent Route for **all** our Routes. This contains project wide
+functionality for several important additions. If you use the normal `ember
+generate route route-name` generator this inheritance is automatically added
+for you. If you don't use the generator please ensure you use:
+
+```js
+import Route from 'consul-ui/routing/route';
+export default class NameOfRoute extends Route {}
+```
+
+Query parameters should be added to Routes, not Controllers. If a controller
+has no query parameters configured they are copied over from the Route.
+Preferably we don't use Controllers, but this doesn't mean you shouldn't if
+you need to.
+
+## Routlets
+
+We use have a concept of 'routlets', the combination of a `<Route />` and
+`<Outlet />` components that we use within our route templates to achieve
+several different pieces of functionality.
+
+Every route template should be wrapped in a `<Route @name={{routeName}}>` component and ever
+`{{outlet}}` should be wrapped in `<Outlet @name={{routeName}}>` component.
+The `routeName` variable is made available in every single route template and
+it equal to the routeName of the current template e.g. `dc.services.index`
+
+## DataSources
+
+In order to support our live updating long-polling blocking queries we use
+'DataSources' which come in two flavours. A service backed
+approach for use within javascript:
+
+```js
+class RouteName extends Route {
+  @service('datasource/service') data;
+  async model(params) {
+    return this.data.source(uri => uri`/${params.nspace}/${params.dc}/services`)
+  }
+}
+```
+
+This method returns an Ember proxy that lets you access the data as if it was
+'just the data', but is also reactive/auto updates when the data in the
+backend updates, for example:
+
+```hbs
+
+{{@model.Name}}
+
+```
+
+And a component based approach for use within templates.
+
+```hbs
+<DataSource @src={{
+  uri '/${nspace}/${dc}/services'
+  (hash
+    nspace="default"
+    dc="dc"
+  )
+  }}
+  @onchange=""
+/>
+```
+
+See the relavant component/service documentation for more detail.
+
+## Components
+
+You could group our components into two different groups:
+
+1. UI Components - generic components not necessarily specific to the product.
+2. Consul Components - Components that are specific to Consul/the product.
+These are mostly 'glorified partials'.
+
+Mostly the CSS for a component lives in the component folder itself, but if it
+makes sense for it not to live here, thats fine.
+
+We currently use a mix of named/block slots and contextual components and its
+fair to say that we use more named/block slots, but both are fine depending on
+your use case.
+
+## Significant Addons
+
+- `ember-data` - model layer
+- `ember-stargate` - wormhole/portal/put this DOM over there functionality
+- `ember-can` - user abilities and permissions
+- `ember-composable-helpers`, `ember-string-fns`, `ember-truth-helpers` - helpers x lots
+- `ember-changeset` and `ember-changeset-validations` - form validation
+- `ember-cli-flash` - notifications
+
+Please see our package.json file dependencies.
+
+

ui/packages/consul-ui/package.json

@@ -58,7 +58,7 @@
     "@babel/helper-call-delegate": "^7.10.1",
     "@babel/plugin-proposal-class-properties": "^7.10.1",
     "@babel/plugin-proposal-object-rest-spread": "^7.5.5",
-    "@docfy/ember": "^0.4.0",
+    "@docfy/ember": "^0.4.1",
     "@ember/optional-features": "^1.3.0",
     "@ember/render-modifiers": "^1.0.2",
     "@glimmer/component": "^1.0.0",

ui/yarn.lock

@@ -1084,10 +1084,10 @@
     unist-util-visit "^2.0.2"
     yaml "^1.9.2"
 
-"@docfy/ember@^0.4.0":
+"@docfy/ember@^0.4.1":
-  version "0.4.0"
+  version "0.4.1"
-  resolved "https://registry.yarnpkg.com/@docfy/ember/-/ember-0.4.0.tgz#0eee5438970a0f41caeb521c4c65438b027cd9ba"
+  resolved "https://registry.yarnpkg.com/@docfy/ember/-/ember-0.4.1.tgz#1a46a21392ec07b87006f94eab4d5ebb4df77bf9"
-  integrity sha512-I7n8qrwtnCsHxVdcIQTiFZqdnZXHczoOZbVQgFyhrQSX+q+2GablTEJFxicQx7AZSuXgJp9gipD6Ln59QZfvDA==
+  integrity sha512-TBCc4WntXUydZZd9muF6S0DtMR0eTQkfJVC5v3+5dloOnY/avyz0fNwaldIrDIHXudl1cYentnEaxRP9Bp4o9g==
   dependencies:
     "@docfy/core" "^0.4.0"
     broccoli-bridge "^1.0.0"