From d47ccb859fb851a5f02624a2d50dbcf9121fef68 Mon Sep 17 00:00:00 2001 From: John Cowen Date: Wed, 17 Mar 2021 15:58:17 +0000 Subject: [PATCH] ui: Improves UI engineering docs (#9875) Also fixes some typos in with-overlay --- ui/packages/consul-ui/.docfy-config.js | 35 +++++- .../app/components/auth-dialog/README.mdx | 11 +- .../app/components/auth-form/README.mdx | 7 +- .../app/components/auth-profile/README.mdx | 13 ++- .../app/components/consul/loader/README.mdx | 12 +- .../consul/lock-session/list/README.mdx | 17 ++- .../consul/metadata/list/README.mdx | 26 +++-- .../components/consul/nspace/list/README.mdx | 17 ++- .../components/consul/policy/list/README.mdx | 12 +- .../components/consul/role/list/README.mdx | 6 +- .../components/consul/token/list/README.mdx | 6 +- .../consul/token/ruleset/list/README.mdx | 6 +- .../app/components/copy-button/README.mdx | 6 + .../app/components/data-collection/README.mdx | 7 +- .../app/components/data-sink/README.mdx | 3 + .../app/components/event-source/README.mdx | 5 +- .../app/components/jwt-source/README.mdx | 5 +- .../consul-ui/app/components/ref/README.mdx | 5 +- .../app/components/state-chart/README.mdx | 5 +- .../consul-ui/app/components/state/README.mdx | 5 +- .../app/components/toggle-button/README.mdx | 3 + .../app/components/token-source/README.mdx | 3 + .../consul-ui/app/helpers/flatten-property.js | 8 ++ ui/packages/consul-ui/app/helpers/is-href.mdx | 34 ++++++ ui/packages/consul-ui/app/helpers/to-route.js | 12 ++ .../app/instance-initializers/selection.js | 16 ++- .../consul-ui/app/modifiers/disabled.mdx | 39 +++++++ .../consul-ui/app/modifiers/tooltip.mdx | 37 ++++++ .../consul-ui/app/modifiers/with-overlay.js | 4 +- .../consul-ui/app/modifiers/with-overlay.mdx | 31 +++++ ui/packages/consul-ui/app/services/env.mdx | 14 +++ .../app/styles/base/icons/base-variables.scss | 2 + .../styles/base/icons/icon-placeholders.scss | 9 ++ ui/packages/consul-ui/app/styles/debug.scss | 65 ++++++++++- ui/packages/consul-ui/app/templates/debug.hbs | 54 ++++++--- ui/packages/consul-ui/docs/bookmarklets.mdx | 21 ++++ ui/packages/consul-ui/docs/index.mdx | 29 +++++ .../consul-ui/docs/significant-patterns.mdx | 108 ++++++++++++++++++ ui/packages/consul-ui/package.json | 2 +- ui/yarn.lock | 8 +- 40 files changed, 615 insertions(+), 93 deletions(-) create mode 100644 ui/packages/consul-ui/app/helpers/flatten-property.js create mode 100644 ui/packages/consul-ui/app/helpers/is-href.mdx create mode 100644 ui/packages/consul-ui/app/helpers/to-route.js create mode 100644 ui/packages/consul-ui/app/modifiers/disabled.mdx create mode 100644 ui/packages/consul-ui/app/modifiers/tooltip.mdx create mode 100644 ui/packages/consul-ui/app/modifiers/with-overlay.mdx create mode 100644 ui/packages/consul-ui/app/services/env.mdx create mode 100644 ui/packages/consul-ui/docs/bookmarklets.mdx create mode 100644 ui/packages/consul-ui/docs/index.mdx create mode 100644 ui/packages/consul-ui/docs/significant-patterns.mdx diff --git a/ui/packages/consul-ui/.docfy-config.js b/ui/packages/consul-ui/.docfy-config.js index 2c08b7ca8..6e14211f9 100644 --- a/ui/packages/consul-ui/.docfy-config.js +++ b/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" + } }; diff --git a/ui/packages/consul-ui/app/components/auth-dialog/README.mdx b/ui/packages/consul-ui/app/components/auth-dialog/README.mdx index 3436b7c1e..32d0dbff1 100644 --- a/ui/packages/consul-ui/app/components/auth-dialog/README.mdx +++ b/ui/packages/consul-ui/app/components/auth-dialog/README.mdx @@ -1,7 +1,10 @@ -## AuthDialog +--- +class: ember +--- +# AuthDialog -```hbs - +```hbs preview-template + {{#let components.AuthForm components.AuthProfile as |AuthForm AuthProfile|}} Here's the login form: @@ -10,7 +13,7 @@ Here's your profile: - {{/let}} diff --git a/ui/packages/consul-ui/app/components/auth-form/README.mdx b/ui/packages/consul-ui/app/components/auth-form/README.mdx index 942e9d813..37fb97ce8 100644 --- a/ui/packages/consul-ui/app/components/auth-form/README.mdx +++ b/ui/packages/consul-ui/app/components/auth-form/README.mdx @@ -1,6 +1,9 @@ -## AuthForm +--- +class: ember +--- +# AuthForm -```handlebars +```hbs preview-template ``` diff --git a/ui/packages/consul-ui/app/components/auth-profile/README.mdx b/ui/packages/consul-ui/app/components/auth-profile/README.mdx index 3dfaa8aef..cda8cd031 100644 --- a/ui/packages/consul-ui/app/components/auth-profile/README.mdx +++ b/ui/packages/consul-ui/app/components/auth-profile/README.mdx @@ -1,16 +1,21 @@ -## AuthProfile +--- +class: ember +--- +# AuthProfile -```hbs - +```hbs preview-template + ``` A straightforward partial-like component for rendering a user profile. +Only the last 8 characters are shown. + ### Arguments | Argument | Type | Default | Description | | --- | --- | --- | --- | -| `item` | `Object` | | A Consul shaped token object (currently only requires an AccessorID property to be set | +| `item` | `Object` | | A Consul shaped token object (currently only requires an AccessorID property to be set | ### See diff --git a/ui/packages/consul-ui/app/components/consul/loader/README.mdx b/ui/packages/consul-ui/app/components/consul/loader/README.mdx index 273d3f9fa..0c0611079 100644 --- a/ui/packages/consul-ui/app/components/consul/loader/README.mdx +++ b/ui/packages/consul-ui/app/components/consul/loader/README.mdx @@ -1,13 +1,13 @@ -## Consul::Loader +# Consul::Loader -`` +```hbs preview-template +
+ +
+``` Simple template-only component to show the circular animated Consul loader animation. -| Argument | Type | Default | Description | -| --- | --- | --- | --- | - - ### See - [Component Source Code](./index.js) diff --git a/ui/packages/consul-ui/app/components/consul/lock-session/list/README.mdx b/ui/packages/consul-ui/app/components/consul/lock-session/list/README.mdx index 04afe202b..29061447f 100644 --- a/ui/packages/consul-ui/app/components/consul/lock-session/list/README.mdx +++ b/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 + + + ``` A presentational component for rendering Node Lock Sessions diff --git a/ui/packages/consul-ui/app/components/consul/metadata/list/README.mdx b/ui/packages/consul-ui/app/components/consul/metadata/list/README.mdx index 6a9e33e17..d25869510 100644 --- a/ui/packages/consul-ui/app/components/consul/metadata/list/README.mdx +++ b/ui/packages/consul-ui/app/components/consul/metadata/list/README.mdx @@ -1,23 +1,27 @@ -## ConsulMetadataList - -`` +--- +class: ember +--- +# 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 + + + +``` + + ### 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 - -``` ### See diff --git a/ui/packages/consul-ui/app/components/consul/nspace/list/README.mdx b/ui/packages/consul-ui/app/components/consul/nspace/list/README.mdx index 44a10622a..a9bdb0f4f 100644 --- a/ui/packages/consul-ui/app/components/consul/nspace/list/README.mdx +++ b/ui/packages/consul-ui/app/components/consul/nspace/list/README.mdx @@ -1,10 +1,15 @@ -## ConsulNspaceList +--- +class: ember +--- +## Consul::Nspace::List -``` - +```hbs + + + ``` A presentational component for rendering Consul Namespaces diff --git a/ui/packages/consul-ui/app/components/consul/policy/list/README.mdx b/ui/packages/consul-ui/app/components/consul/policy/list/README.mdx index 37cd0a9a7..c431b16ff 100644 --- a/ui/packages/consul-ui/app/components/consul/policy/list/README.mdx +++ b/ui/packages/consul-ui/app/components/consul/policy/list/README.mdx @@ -1,10 +1,10 @@ -## ConsulPolicyList +# Consul::Policy::List -``` - +```hbs + ``` A presentational component for rendering Consul ACL policies diff --git a/ui/packages/consul-ui/app/components/consul/role/list/README.mdx b/ui/packages/consul-ui/app/components/consul/role/list/README.mdx index de229b56b..31780f83f 100644 --- a/ui/packages/consul-ui/app/components/consul/role/list/README.mdx +++ b/ui/packages/consul-ui/app/components/consul/role/list/README.mdx @@ -1,7 +1,7 @@ -## ConsulRoleList +## Consul::Role::List -``` - diff --git a/ui/packages/consul-ui/app/components/consul/token/list/README.mdx b/ui/packages/consul-ui/app/components/consul/token/list/README.mdx index ba65a5593..5f2f112f4 100644 --- a/ui/packages/consul-ui/app/components/consul/token/list/README.mdx +++ b/ui/packages/consul-ui/app/components/consul/token/list/README.mdx @@ -1,7 +1,7 @@ -## ConsulTokenList +## Consul::Token::List -``` - ``` diff --git a/ui/packages/consul-ui/app/components/copy-button/README.mdx b/ui/packages/consul-ui/app/components/copy-button/README.mdx index 826cfe20c..e176fc276 100644 --- a/ui/packages/consul-ui/app/components/copy-button/README.mdx +++ b/ui/packages/consul-ui/app/components/copy-button/README.mdx @@ -1,11 +1,17 @@ # CopyButton ```hbs preview-template +

+ Icon Only: +

+

+ Icon and text: +

{{collection.items.length}} diff --git a/ui/packages/consul-ui/app/components/data-sink/README.mdx b/ui/packages/consul-ui/app/components/data-sink/README.mdx index 08fab7b86..8cd7f6246 100644 --- a/ui/packages/consul-ui/app/components/data-sink/README.mdx +++ b/ui/packages/consul-ui/app/components/data-sink/README.mdx @@ -1,3 +1,6 @@ +--- +class: ember +--- ## DataSink ```hbs diff --git a/ui/packages/consul-ui/app/components/event-source/README.mdx b/ui/packages/consul-ui/app/components/event-source/README.mdx index 52951cc99..0e228f431 100644 --- a/ui/packages/consul-ui/app/components/event-source/README.mdx +++ b/ui/packages/consul-ui/app/components/event-source/README.mdx @@ -1,4 +1,7 @@ -## EventSource +--- +class: ember +--- +# EventSource ```hbs diff --git a/ui/packages/consul-ui/app/components/ref/README.mdx b/ui/packages/consul-ui/app/components/ref/README.mdx index 7eaedc530..040badca4 100644 --- a/ui/packages/consul-ui/app/components/ref/README.mdx +++ b/ui/packages/consul-ui/app/components/ref/README.mdx @@ -1,4 +1,7 @@ -## Ref +--- +class: ember +--- +# Ref `` diff --git a/ui/packages/consul-ui/app/components/state-chart/README.mdx b/ui/packages/consul-ui/app/components/state-chart/README.mdx index ba838595e..eb3a3fa1b 100644 --- a/ui/packages/consul-ui/app/components/state-chart/README.mdx +++ b/ui/packages/consul-ui/app/components/state-chart/README.mdx @@ -1,4 +1,7 @@ -## StateChart +--- +class: ember +--- +# StateChart ```hbs Currently Idle` diff --git a/ui/packages/consul-ui/app/components/toggle-button/README.mdx b/ui/packages/consul-ui/app/components/toggle-button/README.mdx index 7e20f9336..2c8acc834 100644 --- a/ui/packages/consul-ui/app/components/toggle-button/README.mdx +++ b/ui/packages/consul-ui/app/components/toggle-button/README.mdx @@ -1,3 +1,6 @@ +--- +class: ember +--- ## ToggleButton `Toggle` diff --git a/ui/packages/consul-ui/app/components/token-source/README.mdx b/ui/packages/consul-ui/app/components/token-source/README.mdx index bf6ba4b53..acaa38b88 100644 --- a/ui/packages/consul-ui/app/components/token-source/README.mdx +++ b/ui/packages/consul-ui/app/components/token-source/README.mdx @@ -1,3 +1,6 @@ +--- +class: ember +--- ## TokenSource ```hbs diff --git a/ui/packages/consul-ui/app/helpers/flatten-property.js b/ui/packages/consul-ui/app/helpers/flatten-property.js new file mode 100644 index 000000000..761785b55 --- /dev/null +++ b/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; +}); diff --git a/ui/packages/consul-ui/app/helpers/is-href.mdx b/ui/packages/consul-ui/app/helpers/is-href.mdx new file mode 100644 index 000000000..6e147e874 --- /dev/null +++ b/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 + +
    +
  • + Active +
    • +
  • + Not Active +
    • +
+``` + +The Consul UI generally uses this on `
  • ` elements of navigation, not the +`` anchors themselves. There are cases of course where we need this for +links that are not in `
  • `s so its fine to use it on the `` in those +cases. + +We currently use the `is-active` classname throughout the app to mirror the +ember `` class used for the same purpose. + +Different to `ember-href-to` and `` 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. diff --git a/ui/packages/consul-ui/app/helpers/to-route.js b/ui/packages/consul-ui/app/helpers/to-route.js new file mode 100644 index 000000000..7f3a6d4f5 --- /dev/null +++ b/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; + } +} diff --git a/ui/packages/consul-ui/app/instance-initializers/selection.js b/ui/packages/consul-ui/app/instance-initializers/selection.js index d39c2a4aa..faa9e7533 100644 --- a/ui/packages/consul-ui/app/instance-initializers/selection.js +++ b/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); - document.body.addEventListener('mouseup', mouseup); + doc.body.addEventListener('mousedown', mousedown); + doc.body.addEventListener('mouseup', mouseup); container.reopen({ willDestroy: function() { - document.body.removeEventListener('mousedown', mousedown); - document.body.removeEventListener('mouseup', mouseup); + doc.body.removeEventListener('mousedown', mousedown); + doc.body.removeEventListener('mouseup', mouseup); return this._super(...arguments); }, }); diff --git a/ui/packages/consul-ui/app/modifiers/disabled.mdx b/ui/packages/consul-ui/app/modifiers/disabled.mdx new file mode 100644 index 000000000..1c62bd155 --- /dev/null +++ b/ui/packages/consul-ui/app/modifiers/disabled.mdx @@ -0,0 +1,39 @@ +# disabled + +The disabled modifer works similarly to the [`
    ` +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 `
    ` 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. + + + +```hbs preview-template +
    + Disabled:
    + Disabled:
    + Enabled: +
    +``` diff --git a/ui/packages/consul-ui/app/modifiers/tooltip.mdx b/ui/packages/consul-ui/app/modifiers/tooltip.mdx new file mode 100644 index 000000000..dde6a6f99 --- /dev/null +++ b/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 + + Hover over me + +``` + +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 + + + + No need to hover over me + +``` + +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. diff --git a/ui/packages/consul-ui/app/modifiers/with-overlay.js b/ui/packages/consul-ui/app/modifiers/with-overlay.js index 137663c68..74ba4a608 100644 --- a/ui/packages/consul-ui/app/modifiers/with-overlay.js +++ b/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); diff --git a/ui/packages/consul-ui/app/modifiers/with-overlay.mdx b/ui/packages/consul-ui/app/modifiers/with-overlay.mdx new file mode 100644 index 000000000..dd6c5d376 --- /dev/null +++ b/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 +
    + The popover +
    + +``` + +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. + diff --git a/ui/packages/consul-ui/app/services/env.mdx b/ui/packages/consul-ui/app/services/env.mdx new file mode 100644 index 000000000..0af681c97 --- /dev/null +++ b/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'); + } +} +``` diff --git a/ui/packages/consul-ui/app/styles/base/icons/base-variables.scss b/ui/packages/consul-ui/app/styles/base/icons/base-variables.scss index 2dd1a649e..3916860ab 100644 --- a/ui/packages/consul-ui/app/styles/base/icons/base-variables.scss +++ b/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,'); $download-svg: url('data:image/svg+xml;charset=UTF-8,'); $edit-svg: url('data:image/svg+xml;charset=UTF-8,'); +$ember-circle-logo-color-svg: url('data:image/svg+xml;charset=UTF-8,'); $envelope-sealed-fill-svg: url('data:image/svg+xml;charset=UTF-8,'); $envelope-sealed-outline-svg: url('data:image/svg+xml;charset=UTF-8,'); $envelope-unsealed--outline-svg: url('data:image/svg+xml;charset=UTF-8,'); @@ -69,6 +70,7 @@ $git-branch-svg: url('data:image/svg+xml;charset=UTF-8,'); $git-pull-request-svg: url('data:image/svg+xml;charset=UTF-8,'); $git-repository-svg: url('data:image/svg+xml;charset=UTF-8,'); +$glimmer-logo-color-svg: url('data:image/svg+xml;charset=UTF-8,'); $hashicorp-logo-svg: url('data:image/svg+xml;charset=UTF-8,'); $health-svg: url('data:image/svg+xml;charset=UTF-8,'); $help-circle-fill-svg: url('data:image/svg+xml;charset=UTF-8,'); diff --git a/ui/packages/consul-ui/app/styles/base/icons/icon-placeholders.scss b/ui/packages/consul-ui/app/styles/base/icons/icon-placeholders.scss index 15e4366d1..43d10d456 100644 --- a/ui/packages/consul-ui/app/styles/base/icons/icon-placeholders.scss +++ b/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; diff --git a/ui/packages/consul-ui/app/styles/debug.scss b/ui/packages/consul-ui/app/styles/debug.scss index b70600c3c..77e7d176c 100644 --- a/ui/packages/consul-ui/app/styles/debug.scss +++ b/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 { - background-color: white; + .tabular-collection, + .list-collection { + height: 300px !important; } - [class^='docfy'] { - margin-bottom: 1em; + 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; + } + } } h1, h2, diff --git a/ui/packages/consul-ui/app/templates/debug.hbs b/ui/packages/consul-ui/app/templates/debug.hbs index e687db0f9..9ef84e6d3 100644 --- a/ui/packages/consul-ui/app/templates/debug.hbs +++ b/ui/packages/consul-ui/app/templates/debug.hbs @@ -1,24 +1,48 @@ + +{{page-title 'Engineering Docs - Consul' separator=' - '}} + +{{document-attrs class="is-debug"}} <:main-nav> - -
      - {{#each node.children as |child|}} - {{#each child.children as |child|}} - {{#each child.pages as |child|}} -
    • - - {{child.title}} - -
      • - {{/each}} - {{/each}} + + +
        +
      • Docs
        • +{{#each node.children as |child|}} + {{#each child.pages as |child|}} +
      • + + {{child.title}} + +
        • + {{/each}} + {{#each child.children as |section|}} +
      • {{section.label}}
        • + {{#each (flatten-property section 'pages') as |child|}} +
      • + + {{child.title}} + +
        • {{/each}} -
      -       + {{/each}} +{{/each}} +
    +     <:main> - {{outlet}} + + {{outlet}} +     diff --git a/ui/packages/consul-ui/docs/bookmarklets.mdx b/ui/packages/consul-ui/docs/bookmarklets.mdx new file mode 100644 index 000000000..b7647c077 --- /dev/null +++ b/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 | + + diff --git a/ui/packages/consul-ui/docs/index.mdx b/ui/packages/consul-ui/docs/index.mdx new file mode 100644 index 000000000..5dba6e8e8 --- /dev/null +++ b/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 + +``` +~~~ + +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) + diff --git a/ui/packages/consul-ui/docs/significant-patterns.mdx b/ui/packages/consul-ui/docs/significant-patterns.mdx new file mode 100644 index 000000000..38f10456b --- /dev/null +++ b/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 `` and +`` components that we use within our route templates to achieve +several different pieces of functionality. + +Every route template should be wrapped in a `` component and ever +`{{outlet}}` should be wrapped in `` 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 + +``` + +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. + + diff --git a/ui/packages/consul-ui/package.json b/ui/packages/consul-ui/package.json index 6f091f46b..03f46b5e8 100644 --- a/ui/packages/consul-ui/package.json +++ b/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", diff --git a/ui/yarn.lock b/ui/yarn.lock index 59fc376c4..64314d986 100644 --- a/ui/yarn.lock +++ b/ui/yarn.lock @@ -1084,10 +1084,10 @@ unist-util-visit "^2.0.2" yaml "^1.9.2" -"@docfy/ember@^0.4.0": - version "0.4.0" - resolved "https://registry.yarnpkg.com/@docfy/ember/-/ember-0.4.0.tgz#0eee5438970a0f41caeb521c4c65438b027cd9ba" - integrity sha512-I7n8qrwtnCsHxVdcIQTiFZqdnZXHczoOZbVQgFyhrQSX+q+2GablTEJFxicQx7AZSuXgJp9gipD6Ln59QZfvDA== +"@docfy/ember@^0.4.1": + version "0.4.1" + resolved "https://registry.yarnpkg.com/@docfy/ember/-/ember-0.4.1.tgz#1a46a21392ec07b87006f94eab4d5ebb4df77bf9" + integrity sha512-TBCc4WntXUydZZd9muF6S0DtMR0eTQkfJVC5v3+5dloOnY/avyz0fNwaldIrDIHXudl1cYentnEaxRP9Bp4o9g== dependencies: "@docfy/core" "^0.4.0" broccoli-bridge "^1.0.0"