open-consul/ui/packages/consul-ui/app/components/horizontal-kv-list
John Cowen 2200cde988
ui: Replaces almost all remaining instances of SASS variables with CSS (#11200)
From an engineers perspective, whenever specifying colors from now on we should use the form:

```
color: rgb(var(--tone-red-500));
```

Please note:

- Use rgb. This lets us do this like rgb(var(--tone-red-500) / 10%) so we can use a 10% opacity red-500 if we ever need to whilst still making use of our color tokens.
- Use --tone-colorName-000 (so the prefix tone). Previously we could use a mix of --gray-500: $gray-500 (note the left hand CSS prop and right hand SASS var) for the things we need to theme currently. As we no longer use SASS we can't do --gray-500: --gray-500, so we now do --tone-gray-500: --gray-500.

Just for clarity after that, whenever specifying a color anywhere, use rgb and --tone. There is only one reason where you might not use tone, and that is if you never want a color to be affected by a theme (for example a background shadow probably always should use --black)

There are a 2 or 3 left for the code editor, plus our custom-query values
2021-10-07 19:21:11 +01:00
..
debug.scss ui: Replaces almost all remaining instances of SASS variables with CSS (#11200) 2021-10-07 19:21:11 +01:00
index.scss
layout.scss
README.mdx ui: Replaces almost all remaining instances of SASS variables with CSS (#11200) 2021-10-07 19:21:11 +01:00
skin.scss

---
class: css
---
# horizontal-kv-list

Provides a horizontally stacked list of key/value pairs, commonly used with a
definition/description list.

The keys can be configured to be either, visible, invisible, or with an icon.

- **Icon Configuration:** Add a `class` that describes the key/value pair and configure the icon for that class in the CSS
- **Visible Title Configuration:** Add an empty `class` attribute. A trailing `:`
  will be added to the title (ensure you collapse the whitespace in the `dt`).
- **Invisible Title Configuration:** Don't add a `class` attribute at all, i.e. by default
  the title is not shown.

If you are providing an icon, you should also use the `{{tooltip}}` modifier
to provide a textual tooltip for the icon. Using the `{{tooltip}}` modifier
with no arguments will make it use the text/DOM content of the DOM element it
is attached to, see below for a full usage example.

`<CopyButton />` components are commonly added to the value, and can be added
to the left or right of the value.

```hbs preview-template
<figure>
  <figcaption>
    All KVs can be specified in a single list
  </figcaption>

  <dl>
    <dt class="kind-terminating-gateway">Kind</dt>
    <dd>
      Terminating Gateway
    </dd>
{{#if true}}
    <dt
      {{tooltip}}
      class="lock-delay"
    >
      Lock Delay
    </dt>
    <dd>10ms</dd>
{{/if}}
    <dt
      {{tooltip}}
      class="ttl"
    >
      TTL
    </dt>
    <dd>
      <CopyButton
        @value={{"1m30s10ms"}}
        @name="TTL"
      />
      1m30s10ms
    </dd>
    <dt>
      Invisible title
    </dt>
    <dd>
      local
    </dd>
    <dt class>Visible title</dt>
    <dd>
      global
    </dd>
  </dl>

</figure>
<hr />
<figure>
  <figcaption>...or they can all be specified as individual lists (for if you have a component that is already wrapped in a dl, such as our TagList)</figcaption>

  <dl>
    <dt
      class="service-identity"
    >
      Service Identity
    </dt>
    <dd>service-0</dd>
  </dl><dl>
    <dt
      {{tooltip}}
      class="lock-delay"
    >
      Lock Delay
    </dt>
    <dd>10ms</dd>
  </dl><dl>
    <dt
      {{tooltip}}
      class="ttl"
    >
      TTL
    </dt>
    <dd>
      1m30s10ms
      <CopyButton
        @value={{"1m30s10ms"}}
        @name="TTL"
      />
    </dd>
  </dl><dl>
    <dt>
      No visible title
    </dt>
    <dd>local</dd>
  </dl><dl>
    <dt class>Visible title</dt>
    <dd>global</dd>
  </dl><!--
      Collapse the whitespace but keep our indentation
--><TagList @tags={{array 'one' 'two'}} />

</figure>
<hr />
<figure class="reversed">
  <figcaption>When reversing, you'll probably want to use indiviudual dl's so as to not reverse the order of the KV pairs</figcaption>
  <dl>
      <dt class="kind-terminating-gateway">Kind</dt>
      <dd>
        Terminating Gateway
      </dd>
  </dl>
  <dl>
    <dt
      class="service-identity"
    >
      Service Identity
    </dt>
    <dd>service-0</dd>
  </dl>
  <dl>
    <dt
      {{tooltip}}
      class="lock-delay"
    >
      Lock Delay
    </dt>
    <dd>10ms</dd>
  </dl><dl>
    <dt
      {{tooltip}}
      class="ttl"
    >
      TTL
    </dt>
    <dd>
      <CopyButton
        @value={{"1m30s10ms"}}
        @name="TTL"
      />
      1m30s10ms
    </dd>
  </dl><dl>
    <dt>
      No visible title
    </dt>
    <dd>local</dd>
  </dl><dl>
    <dt class>Visible title</dt>
    <dd>global</dd>
  </dl>

</figure>
```
When conditionally listing key/values within a single `dl`, be aware that if no key/values should be shown, then you will be left with an empty `dl`. If you collapse the whitespace using handlebars whitespace collapsing `~`, then this empty `dl` will be removed from the flow via CSS. Alternatively consider using multiple `dl`s which can be wrapped with conditionals individually and therefore leave no empty DOM.

When using as individual `dl` lists be aware of whitespace between `dl`s. There are various ways you can counter this:

1. remove the whitespace `</dl><dl>`.
2. Wrap the whitespace in comments `</dl><!-- carriage return --><dl>`
3. Use handlebars whitespace removal `~` as above.
4. Put a `display: inline-flex` on the parent element (this can affect other layout).

Depending on your exact usecase one of the above options may be more suited than others.

```hbs preview-template
<figure>
  <figcaption>
    Conditionally showing multiple key/values sometimes means that you insert an empty `dl` into the DOM
  </figcaption>

  <dl>
    {{~#if false}}
      <dt>Something that might not be set</dt>
      <dd>No value!</dd>
    {{/if~}}
    {{~#if false}}
      <dt>Something that might not be set</dt>
      <dd>No value!</dd>
    {{/if~}}
  </dl>
</figure>
```


```css
dl {
  @extend %horizontal-kv-list;
}
.lock-delay::before {
  @extend %with-delay-mask, %as-pseudo;
  color: rgb(var(--tone-gray-700));
}
.ttl::before {
  @extend %with-history-mask, %as-pseudo;
  color: rgb(var(--tone-blue-500));
}
.service-identity {
  @extend %badge;
}
.kind-terminating-gateway {
  @extend %badge, %badge-with-icon;
}
.kind-terminating-gateway::before {
  @extend %with-gateway-mask, %as-pseudo;
}
.reversed > dl {
  @extend %horizontal-kv-list-reversed;
}
.reversed .service-identity {
  @extend %badge-reversed;
}
.reversed .kind-terminating-gateway {
  @extend %badge-with-icon-reversed;
}
```

## Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `--horizontal-kv-list-separator-width` | `length-percentage` | `18px` | The width of the whitespace between two sets of key/value pairs |
| `--horizontal-kv-list-key-separator` | `string` | `:` | Separator used for between `Key: Value` for textual key/values |
| `--horizontal-kv-list-key-wrapper-start` | `string` | `(` | Starting wrapper used for wrapping `Value (Key)` for reversed textual key/values |
| `--horizontal-kv-list-key-wrapper-end` | `string` | `)` | Ending wrapper used for wrapping `Value (Key)` for reversed textual key/values |