@hashicorp/design-system-components 0.0.13 → 0.0.17

package/.github/ISSUE_TEMPLATE/new-component-quest-issue-engineering-checklist.md

@@ -0,0 +1,78 @@
+---
+name: New Component Quest Issue/Engineering Checklist
+about: 'DS Team: Engineering Checklist for New Components'
+title: "[Quest] New Component: Component Name"
+labels: ''
+assignees: ''
+
+---
+
+This is the quest issue/engineering checklist for the COMPONENT_NAME Component. All new components will have their own feature branch, and any PR that adds an item from the checklist should target the feature branch, and not `main`. 
+
+## Pre-Flight Checklist
+Update this list and these links as appropriate.
+
+- [Component Doc](url_here): This file should exist before any code is written.
+- [FIGMA Design](url_here): Since we are trying to align the component API naming with the same terms used in the Figma file, it is likely useful to have a fairly stable Figma design before we create a component; it should definitely be finalized before the component ships, however. 
+- [Design System Website](https://design-system-website.vercel.app/?path=/story/example-introduction--page) (storybook of storybooks): use for reference, to consider existing features that we might need to replicate in the component.
+
+## Engineering Checklist 
+The engineering checklist has six parts: creating the feature branch, component template, component backing class, component style, tests, and documentation.
+
+### Component Creation
+
+- [ ] create new branch from main for the component.
+- [ ] create new component
+  - `ember generate component hds/COMPONENT_NAME/index --gc` (the component won't need to be invoked with index, it's just to put all the files in the correct place)
+  - if it's a variation on a component, then `hds/COMPONENT_NAME/VARIATION` instead of `index`
+- [ ] **component template**
+  - use semantic HTML
+  - the component should have a css class that is the same as the component (e.g. `hds/button` should have a class name of `hds-button` on the component, and additional CSS classes should start with this same class name.
+  - add `...attributes` unless doing so would be detrimental (e.g., a parent component and child component that both have ...attributes) 
+- [ ] **component class**
+  - use getters (vs template conditionals or constructors, if possible)
+  - write API comments in the JS doc way (copy from an existing DS component)
+  - use the same naming as the Figma file for the components API unless it conflicts with a pre-existing HTML attribute. If that is the case, document the difference in the comment.
+  - ensure that all existing functionality (from a Structure component) is accounted for in some way. If we are not providing existing functionality at all, it should be documented (along with the reason why). If we are providing temporary functionality, explain that it's temporary and why.
+  - check the [design system website](https://design-system-website.vercel.app/?path=/story/example-introduction--page) to see what kind of component functionality is being used across all products
+  - booleans should start with a verb (is/has/etc)
+  - assertion text should match the content style of the other components.
+  - goal is a terse invocation
+- [ ] **component style**
+  - create `component/COMPONENT_NAME.scss` in `app/styles` 
+  - add `@use` to `app/styles/@hashicorp/design-system-components.scss` (see existing code for precise syntax)
+  - use design tokens wherever possible, comment where they are not
+  - sizes should be in relative units
+  - line heights should be unitless
+- [ ] **testing**
+  - [ ] test basic functionality
+  - [ ] test defaults
+  - [ ] try not to repeat tests (i.e., don't have to test all sizes, all colors, etc.)
+  - [ ] test all accessibility attributes
+- [ ] **documentation**
+  - create component page `ember generate route components/COMPONENT_NAME --dummy`
+  - add link to `templates/index.hbs` page
+  - [ ] API docs
+  - [ ] Usage 
+  - [ ] Showcase 
+
+### Component Review
+
+Pre-review request checks:
+
+- [ ] make sure all tests pass (`ember s` then visit /tests; or `ember t -s`)
+- [ ] check for basic a11y on docs page: 
+  - keyboard navigation
+  - logical DOM order
+  - zoom up to 400% 
+  - color contrast
+  - (the axe-core browser plugin can run some basic tests and give immediate feedback) 
+- [ ] check page on browsers
+  - Chrome
+  - Firefox
+  - Safari
+  - Edge (once available) 
+
+When ready for review: 
+- [ ] add situationally appropriate reviewers
+- [ ] added instructions for reviewers in your PR, letting them know what kind of review you need

package/addon/components/hds/badge/index.hbs

@@ -1,4 +1,4 @@
-<div class="hds-badge {{this.sizeClass}} {{this.typeClass}} {{this.colorClass}}" ...attributes>
+<div class={{this.classNames}} ...attributes>
   {{#if @icon}}
     <div class="hds-badge__icon">
       <FlightIcon @name={{this.icon}} @size="16" @stretched="true" />

package/addon/components/hds/badge/index.js

@@ -37,15 +37,6 @@ export default class HdsBadgeIndexComponent extends Component {
     return size;
   }
 
-  /**
-   * Get a class to apply to the component based on the size argument.
-   * @method Badge#sizeClass
-   * @return {string} The css class to apply to the component.
-   */
-  get sizeClass() {
-    return `hds-badge--size-${this.size}`;
-  }
-
   /**
    * Sets the type of the component
    * Accepted values: filled, inverted, outlined
@@ -67,15 +58,6 @@ export default class HdsBadgeIndexComponent extends Component {
     return type;
   }
 
-  /**
-   * Get a class to apply to the component based on the type argument.
-   * @method Badge#typeClass
-   * @return {string} The css class to apply to the component.
-   */
-  get typeClass() {
-    return `hds-badge--type-${this.type}`;
-  }
-
   /**
    * Sets the color scheme for the component
    * Accepted values: neutral, neutral-dark-mode, highlight, success, warning, critical
@@ -97,15 +79,6 @@ export default class HdsBadgeIndexComponent extends Component {
     return color;
   }
 
-  /**
-   * Get a class to apply to the component based on the color argument.
-   * @method Badge#colorClass
-   * @return {string} The css class to apply to the component.
-   */
-  get colorClass() {
-    return `hds-badge--color-${this.color}`;
-  }
-
   /**
    * @param text
    * @type {string}
@@ -145,4 +118,24 @@ export default class HdsBadgeIndexComponent extends Component {
     }
     return false;
   }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method Badge#classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  get classNames() {
+    let classes = ['hds-badge'];
+
+    // add a class based on the @size argument
+    classes.push(`hds-badge--size-${this.size}`);
+
+    // add a class based on the @type argument
+    classes.push(`hds-badge--type-${this.type}`);
+
+    // add a class based on the @color argument
+    classes.push(`hds-badge--color-${this.color}`);
+
+    return classes.join(' ');
+  }
 }

package/addon/components/hds/badge-count/index.hbs

@@ -1,3 +1,3 @@
-<div class="hds-badge-count {{this.sizeClass}} {{this.typeClass}} {{this.colorClass}}" ...attributes>
+<div class={{this.classNames}} ...attributes>
   {{@text}}
 </div>

package/addon/components/hds/badge-count/index.js

@@ -30,15 +30,6 @@ export default class HdsBadgeCountIndexComponent extends Component {
     return size;
   }
 
-  /**
-   * Get a class to apply to the component based on the size argument.
-   * @method BadgeCount#sizeClass
-   * @return {string} The css class to apply to the component.
-   */
-  get sizeClass() {
-    return `hds-badge-count--size-${this.size}`;
-  }
-
   /**
    * Sets the type of the component
    * Accepted values: filled, inverted, outlined
@@ -60,15 +51,6 @@ export default class HdsBadgeCountIndexComponent extends Component {
     return type;
   }
 
-  /**
-   * Get a class to apply to the component based on the type argument.
-   * @method BadgeCount#typeClass
-   * @return {string} The css class to apply to the component.
-   */
-  get typeClass() {
-    return `hds-badge-count--type-${this.type}`;
-  }
-
   /**
    * Sets the color scheme for the component
    * Accepted colors: neutral, neutral-dark-mode
@@ -91,11 +73,22 @@ export default class HdsBadgeCountIndexComponent extends Component {
   }
 
   /**
-   * Get a class to apply to the component based on the color argument.
-   * @method BadgeCount#colorClass
-   * @return {string} The css class to apply to the component.
+   * Get the class names to apply to the component.
+   * @method BadgeCount#classNames
+   * @return {string} The "class" attribute to apply to the component.
    */
-  get colorClass() {
-    return `hds-badge-count--color-${this.color}`;
+  get classNames() {
+    let classes = ['hds-badge-count'];
+
+    // add a class based on the @size argument
+    classes.push(`hds-badge-count--size-${this.size}`);
+
+    // add a class based on the @type argument
+    classes.push(`hds-badge-count--type-${this.type}`);
+
+    // add a class based on the @color argument
+    classes.push(`hds-badge-count--color-${this.color}`);
+
+    return classes.join(' ');
   }
 }

package/addon/components/hds/button/index.hbs

@@ -1,5 +1,5 @@
 <button
-  class="hds-button {{this.sizeClass}} {{this.colorClass}} {{this.widthClass}}"
+  class={{this.classNames}}
   ...attributes
   aria-label={{if this.isIconOnly this.text null}}
   type={{this.type}}

package/addon/components/hds/button/index.js

@@ -46,16 +46,6 @@ export default class HdsButtonIndexComponent extends Component {
     return size;
   }
 
-  /**
-   * @param sizeClass
-   * @type {string}
-   * @default hds-button--size-medium
-   * @description Determines the CSS class that the button should have, based on the size value; automatically set.
-   */
-  get sizeClass() {
-    return `hds-button--size-${this.size}`;
-  }
-
   /**
    * @param color
    * @type {string}
@@ -75,16 +65,6 @@ export default class HdsButtonIndexComponent extends Component {
     return color;
   }
 
-  /**
-   * @param colorClass
-   * @type {string}
-   * @default hds-button--color-primary
-   * @description Determines the CSS class that the button should have, based on the color value; automatically set
-   */
-  get colorClass() {
-    return `hds-button--color-${this.color}`;
-  }
-
   /**
    * @param icon
    * @type {string}
@@ -170,20 +150,6 @@ export default class HdsButtonIndexComponent extends Component {
     return this.args.isFullWidth ?? false;
   }
 
-  /**
-   * @param widthClass
-   * @type {string|null}
-   * @default null
-   * @description Determines if the full-width class should be applied to the component. This is set automatically based on the value of `isFullWidth`.
-   */
-  get widthClass() {
-    if (this.isFullWidth === true) {
-      return 'hds-button--width-full';
-    } else {
-      return null;
-    }
-  }
-
   /**
    * @param isDisabled
    * @type {boolean}
@@ -193,4 +159,30 @@ export default class HdsButtonIndexComponent extends Component {
   get isDisabled() {
     return this.args.isDisabled ?? null;
   }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method Badge#classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  // "hds-button {{this.sizeClass}} {{this.colorClass}} {{this.widthClass}}"
+  get classNames() {
+    let classes = ['hds-button'];
+
+    // add a class based on the @size argument
+    classes.push(`hds-button--size-${this.size}`);
+
+    // add a class based on the @color argument
+    classes.push(`hds-button--color-${this.color}`);
+
+    // add a class based on the @isFullWidth argument
+    if (this.isFullWidth) {
+      classes.push('hds-button--width-full');
+    }
+
+    // the button has a "low" elevation effect applied to it
+    classes.push('hds-elevation-low');
+
+    return classes.join(' ');
+  }
 }

package/addon/components/hds/card/container.hbs

@@ -1,6 +1,3 @@
-<div
-  class="hds-card__container {{this.levelClass}} {{this.borderClass}} {{this.backgroundClass}} {{this.overflowClass}}"
-  ...attributes
->
+<div class={{this.classNames}} ...attributes>
   {{yield}}
 </div>

package/addon/components/hds/card/container.js

@@ -30,15 +30,6 @@ export default class HdsCardContainerComponent extends Component {
     return level;
   }
 
-  /**
-   * Get a class to apply to the component based on the level argument.
-   * @method Card#levelClass
-   * @return {string} The css class to apply to the component.
-   */
-  get levelClass() {
-    return `hds-card__container--level-${this.level}`;
-  }
-
   /**
    * Sets the background for the component
    * Accepted values: neutral-primary, neutral-secondary
@@ -60,24 +51,6 @@ export default class HdsCardContainerComponent extends Component {
     return background;
   }
 
-  /**
-   * Get a class to apply to the component based on the background argument.
-   * @method Card#backgroundClass
-   * @return {string} The css class to apply to the component.
-   */
-  get backgroundClass() {
-    return `hds-card__container--background-${this.background}`;
-  }
-
-  /**
-   * Get a class to apply to the component based on the hasBorder argument.
-   * @method Card#hasBorderClass
-   * @return {string} The css class to apply to the component.
-   */
-  get borderClass() {
-    return this.args.hasBorder ? `hds-card__container--has-border` : undefined;
-  }
-
   /**
    * Sets the level for the card
    * Accepted values: visible, hidden
@@ -100,11 +73,24 @@ export default class HdsCardContainerComponent extends Component {
   }
 
   /**
-   * Get a class to apply to the component based on the overflow argument.
-   * @method Card#overflowClass
-   * @return {string} The css class to apply to the component.
+   * Get the class names to apply to the component.
+   * @method Card#classNames
+   * @return {string} The "class" attribute to apply to the component.
    */
-  get overflowClass() {
-    return `hds-card__container--overflow-${this.overflow}`;
+  get classNames() {
+    let classes = ['hds-card__container'];
+
+    // add an "elevation" class helper based on the @level and @hasBorder arguments
+    classes.push(
+      `hds-${this.args.hasBorder ? 'surface' : 'elevation'}-${this.level}`
+    );
+
+    // add a class based on the @background argument
+    classes.push(`hds-card__container--background-${this.background}`);
+
+    // add a class based on the @overflow argument
+    classes.push(`hds-card__container--overflow-${this.overflow}`);
+
+    return classes.join(' ');
   }
 }

package/addon/components/hds/icon-tile/index.hbs

@@ -1,4 +1,4 @@
-<div class="hds-icon-tile {{this.entityClass}} {{this.sizeClass}} {{this.colorClass}}" aria-hidden="true" ...attributes>
+<div class={{this.classNames}} aria-hidden="true" ...attributes>
   {{#if @icon}}
     <div class="hds-icon-tile__icon">
       <FlightIcon @name={{this.icon}} @size={{this.iconSize}} @stretched="true" />

package/addon/components/hds/icon-tile/index.js

@@ -39,15 +39,6 @@ export default class HdsIconTileIndexComponent extends Component {
     return size;
   }
 
-  /**
-   * Get a class to apply to the component based on the size argument.
-   * @method IconTile#sizeClass
-   * @return {string} The css class to apply to the component.
-   */
-  get sizeClass() {
-    return `hds-icon-tile--size-${this.size}`;
-  }
-
   /**
    * Sets the color scheme for the component
    * Accepted values: see THE COLORS LIST
@@ -75,15 +66,6 @@ export default class HdsIconTileIndexComponent extends Component {
     return color;
   }
 
-  /**
-   * Get a class to apply to the component based on the color argument.
-   * @method IconTile#colorClass
-   * @return {string} The css class to apply to the component.
-   */
-  get colorClass() {
-    return `hds-icon-tile--color-${this.color}`;
-  }
-
   /**
    * Sets the icon name (one of the FlightIcons)
    *
@@ -167,15 +149,6 @@ export default class HdsIconTileIndexComponent extends Component {
     return entity;
   }
 
-  /**
-   * Get a class to apply to the component based on the its entity.
-   * @method IconTile#entityClass
-   * @return {string} The css class to apply to the component.
-   */
-  get entityClass() {
-    return `hds-icon-tile--${this.entity}`;
-  }
-
   /**
    * Sets the "secondary" icon name (one of the FlightIcons)
    *
@@ -186,4 +159,25 @@ export default class HdsIconTileIndexComponent extends Component {
   get iconSecondary() {
     return this.args.iconSecondary ?? null;
   }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method IconTile#classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  // hds-icon-tile {{this.entityClass}} {{this.sizeClass}} {{this.colorClass}}"
+  get classNames() {
+    let classes = ['hds-icon-tile'];
+
+    // add a class based on its entity argument
+    classes.push(`hds-icon-tile--${this.entity}`);
+
+    // add a class based on the @size argument
+    classes.push(`hds-icon-tile--size-${this.size}`);
+
+    // add a class based on the @color argument
+    classes.push(`hds-icon-tile--color-${this.color}`);
+
+    return classes.join(' ');
+  }
 }

package/addon/components/hds/link/standalone.hbs

@@ -0,0 +1,20 @@
+{{! template-lint-disable link-href-attributes }}
+{{! we can disable this linting rule because the developer will add the html attribute themselves }}
+<a class={{this.classNames}} target="_blank" rel="noopener noreferrer" ...attributes>
+  {{#if (eq this.iconPosition "leading")}}
+    <div class="hds-link-standalone__icon">
+      <FlightIcon @name={{this.icon}} @size={{this.iconSize}} @stretched={{true}} />
+    </div>
+    <div class="hds-link-standalone__text">
+      {{this.text}}
+    </div>
+  {{else}}
+    <div class="hds-link-standalone__text">
+      {{this.text}}
+    </div>
+    <div class="hds-link-standalone__icon">
+      <FlightIcon @name={{this.icon}} @size={{this.iconSize}} @stretched={{true}} />
+    </div>
+  {{/if}}
+</a>
+{{! template-lint-enable link-href-attributes }}

package/addon/components/hds/link/standalone.js

@@ -0,0 +1,135 @@
+import Component from '@glimmer/component';
+import { assert } from '@ember/debug';
+
+export const DEFAULT_ICONPOSITION = 'leading';
+export const DEFAULT_COLOR = 'primary';
+export const DEFAULT_SIZE = 'medium';
+export const ICONPOSITIONS = ['leading', 'trailing'];
+export const COLORS = ['primary', 'secondary'];
+export const SIZES = ['small', 'medium', 'large'];
+
+export default class HdsLinkStandaloneComponent extends Component {
+  /**
+   * @param text
+   * @type {string}
+   * @description The text of the link. If no text value is defined an error will be thrown.
+   */
+  get text() {
+    let { text } = this.args;
+
+    assert(
+      '@text for "Hds::Link::Standalone" must have a valid value',
+      text !== undefined
+    );
+
+    return text;
+  }
+
+  /**
+   * @param color
+   * @type {string}
+   * @default primary
+   * @description Determines the color of link to be used; acceptable values are `primary` and `secondary`
+   */
+  get color() {
+    let { color = DEFAULT_COLOR } = this.args;
+
+    assert(
+      `@color for "Hds::Link::Standalone" must be one of the following: ${COLORS.join(
+        ', '
+      )}; received: ${color}`,
+      COLORS.includes(color)
+    );
+
+    return color;
+  }
+
+  /**
+   * @param icon
+   * @type {string|null}
+   * @default null
+   * @description The name of the icon to be used. An icon name must be defined.
+   */
+  get icon() {
+    let { icon } = this.args;
+
+    assert(
+      '@icon for "Hds::Link::Standalone" must have a valid value',
+      icon !== undefined
+    );
+
+    return icon;
+  }
+
+  /**
+   * @param iconPosition
+   * @type {string}
+   * @default leading
+   * @description Positions the icon before or after the text; allowed values are `leading` or `trailing`
+   */
+  get iconPosition() {
+    let { iconPosition = DEFAULT_ICONPOSITION } = this.args;
+
+    assert(
+      `@iconPosition for "Hds::Link::Standalone" must be one of the following: ${ICONPOSITIONS.join(
+        ', '
+      )}; received: ${iconPosition}`,
+      ICONPOSITIONS.includes(iconPosition)
+    );
+
+    return iconPosition;
+  }
+
+  /**
+   * @param size
+   * @type {string}
+   * @default medium
+   * @description The size of the standalone link; acceptable values are `small`, `medium`, and `large`
+   */
+  get size() {
+    let { size = DEFAULT_SIZE } = this.args;
+
+    assert(
+      `@size for "Hds::Link::Standalone" must be one of the following: ${SIZES.join(
+        ', '
+      )}; received: ${size}`,
+      SIZES.includes(size)
+    );
+
+    return size;
+  }
+
+  /**
+   * @param iconSize
+   * @type {string}
+   * @default 16
+   * @description ensures that the correct icon size is used. Automatically calculated.
+   */
+  get iconSize() {
+    if (this.args.size === 'large') {
+      return '24';
+    } else {
+      return '16';
+    }
+  }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method LinkStandalone#classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  get classNames() {
+    let classes = ['hds-link-standalone'];
+
+    // add a class based on the @size argument
+    classes.push(`hds-link-standalone--size-${this.size}`);
+
+    // add a class based on the @color argument
+    classes.push(`hds-link-standalone--color-${this.color}`);
+
+    // add a class based on the @iconPosition argument
+    classes.push(`hds-link-standalone--icon-position-${this.iconPosition}`);
+
+    return classes.join(' ');
+  }
+}

package/addon/components/hds/link-to/standalone.hbs

@@ -0,0 +1,25 @@
+<LinkTo
+  class={{this.classNames}}
+  @current-when={{@current-when}}
+  @models={{hds-link-to-models @model @models}}
+  @query={{this.queryParams}}
+  @replace={{@replace}}
+  @route={{this.route}}
+  ...attributes
+>
+  {{#if (eq this.iconPosition "leading")}}
+    <div class="hds-link-standalone__icon">
+      <FlightIcon @name={{this.icon}} @size={{this.iconSize}} @stretched={{true}} />
+    </div>
+    <div class="hds-link-standalone__text">
+      {{this.text}}
+    </div>
+  {{else}}
+    <div class="hds-link-standalone__text">
+      {{this.text}}
+    </div>
+    <div class="hds-link-standalone__icon">
+      <FlightIcon @name={{this.icon}} @size={{this.iconSize}} @stretched={{true}} />
+    </div>
+  {{/if}}
+</LinkTo>