Merge pull request #1393 from hashicorp/alex-ju/add-separator-component

Add `Separator` component

.changeset/moody-donkeys-rule.md

@@ -0,0 +1,5 @@
+---
+"@hashicorp/design-system-components": minor
+---
+
+Add `Separator` component

packages/components/addon/components/hds/separator/index.hbs

@@ -0,0 +1,5 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+<hr class={{this.classNames}} ...attributes />

packages/components/addon/components/hds/separator/index.js

@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import Component from '@glimmer/component';
+import { assert } from '@ember/debug';
+
+export const DEFAULT_SPACING = '24';
+export const SPACING = ['24', '0'];
+
+export default class HdsSeparatorIndexComponent extends Component {
+  /**
+   * Sets the margin for the separator
+   * Accepted values: 24, 0
+   *
+   * @param spacing
+   * @type {string}
+   * @default 'default'
+   */
+  get spacing() {
+    let { spacing = DEFAULT_SPACING } = this.args;
+
+    assert(
+      `@spacing for "Hds::Separator" must be one of the following: ${SPACING.join(
+        ', '
+      )}; received: ${spacing}`,
+      SPACING.includes(spacing)
+    );
+
+    return spacing;
+  }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  get classNames() {
+    let classes = ['hds-separator'];
+
+    // add a class based on the @spacing argument
+    classes.push(`hds-separator--spacing-${this.spacing}`);
+
+    return classes.join(' ');
+  }
+}

packages/components/app/components/hds/separator/index.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+export { default } from '@hashicorp/design-system-components/components/hds/separator/index';

packages/components/app/styles/@hashicorp/design-system-components.scss

@@ -34,6 +34,7 @@
 @use "../components/pagination";
 @use "../components/reveal";
 @use "../components/segmented-group";
+@use "../components/separator";
 @use "../components/side-nav";
 @use "../components/stepper";
 @use "../components/table";

packages/components/app/styles/components/separator.scss

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+//
+// SEPARATOR
+//
+
+.hds-separator {
+  border: none;
+  border-top: 1px solid var(--token-color-border-primary);
+}
+
+.hds-separator--spacing-24 {
+  margin: 24px 0;
+}
+
+.hds-separator--spacing-0 {
+  margin: 0;
+}

packages/components/tests/acceptance/percy-test.js

@@ -107,6 +107,9 @@ module('Acceptance | Percy test', function (hooks) {
     await visit('/components/segmented-group');
     await percySnapshot('Segmented Group');
 
+    await visit('/components/separator');
+    await percySnapshot('Separator');
+
     await visit('/components/side-nav');
     await percySnapshot('SideNav');
 

packages/components/tests/dummy/app/router.js

@@ -48,15 +48,16 @@ Router.map(function () {
     });
     this.route('modal');
     this.route('pagination');
+    this.route('reveal');
+    this.route('segmented-group');
+    this.route('separator');
+    this.route('side-nav');
     this.route('stepper');
     this.route('table');
     this.route('tag');
     this.route('toast');
     this.route('tabs');
     this.route('tooltip');
-    this.route('side-nav');
-    this.route('segmented-group');
-    this.route('reveal');
   });
   this.route('layouts', function () {
     this.route('app-frame');

packages/components/tests/dummy/app/routes/components/separator.js

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import Route from '@ember/routing/route';
+
+export default class ComponentsSeparatorRoute extends Route {}

packages/components/tests/dummy/app/styles/app.scss

@@ -49,6 +49,7 @@
 @import "./showcase-pages/pagination";
 @import "./showcase-pages/power-select";
 @import "./showcase-pages/reveal";
+@import "./showcase-pages/separator";
 @import "./showcase-pages/side-nav";
 @import "./showcase-pages/table";
 @import "./showcase-pages/tabs";

packages/components/tests/dummy/app/styles/showcase-pages/separator.scss

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+// SEPARATOR
+
+body.components-separator {
+  .shw-component-separator-container {
+    display: grid;
+  }
+}

packages/components/tests/dummy/app/templates/components/separator.hbs

@@ -0,0 +1,23 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+
+{{page-title "Separator Component"}}
+
+<Shw::Text::H1>Separator</Shw::Text::H1>
+
+<section data-test-percy>
+  <Shw::Flex @direction="column" as |SF|>
+    <SF.Item @label="Default (24px)">
+      <Shw::Outliner class="shw-component-separator-container">
+        <Hds::Separator />
+      </Shw::Outliner>
+    </SF.Item>
+    <SF.Item @label="No spacing (0px)">
+      <Shw::Outliner class="shw-component-separator-container">
+        <Hds::Separator @spacing="0" />
+      </Shw::Outliner>
+    </SF.Item>
+  </Shw::Flex>
+</section>

packages/components/tests/dummy/app/templates/index.hbs

@@ -166,6 +166,11 @@
           SegmentedGroup
         </LinkTo>
       </li>
+      <li>
+        <LinkTo @route="components.separator">
+          Separator
+        </LinkTo>
+      </li>
       <li>
         <LinkTo @route="components.side-nav">
           SideNav

packages/components/tests/integration/components/hds/separator/index-test.js

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import { module, test } from 'qunit';
+import { setupRenderingTest } from 'ember-qunit';
+import { render, resetOnerror, setupOnerror } from '@ember/test-helpers';
+import { hbs } from 'ember-cli-htmlbars';
+
+module('Integration | Component | hds/separator/index', function (hooks) {
+  setupRenderingTest(hooks);
+
+  hooks.afterEach(() => {
+    resetOnerror();
+  });
+
+  test('it should render the component with a CSS class that matches the component name', async function (assert) {
+    await render(hbs`<Hds::Separator id="test-separator" />`);
+    assert.dom('#test-separator').hasClass('hds-separator');
+  });
+
+  // SPACING
+
+  test('it should render the component with CSS classes that reflect the default vaules if no arguments provided', async function (assert) {
+    await render(hbs`<Hds::Separator id="test-separator" />`);
+    assert.dom('#test-separator').hasClass('hds-separator--spacing-24');
+  });
+
+  test('it should render the component with CSS classes that reflect the arguments provided', async function (assert) {
+    await render(hbs`<Hds::Separator @spacing="0" id="test-separator" />`);
+    assert.dom('#test-separator').hasClass('hds-separator--spacing-0');
+  });
+
+  // ASSERTIONS
+
+  test('it should throw an assertion if an incorrect value for @spacing is provided', async function (assert) {
+    const errorMessage =
+      '@spacing for "Hds::Separator" must be one of the following: 24, 0; received: foo';
+    assert.expect(2);
+    setupOnerror(function (error) {
+      assert.strictEqual(error.message, `Assertion Failed: ${errorMessage}`);
+    });
+    await render(hbs`<Hds::Separator @spacing="foo" id="test-separator" />`);
+    assert.throws(function () {
+      throw new Error(errorMessage);
+    });
+  });
+});

website/docs/components/separator/index.md

@@ -0,0 +1,27 @@
+---
+title: Separator
+description: Creates visual breaks between different sections of content
+caption: Creates visual breaks between different sections of content
+status: released
+links:
+  figma: https://www.figma.com/file/9QeyvUQ8kuyIity6knrznO/Separator-Component?node-id=36433-70314&t=PXCxiaccZSis4g9x-4
+  github: https://github.com/hashicorp/design-system/tree/main/packages/components/addon/components/hds/separator
+previewImage: assets/illustrations/components/separator.jpg
+navigation:
+  keywords: ['horizontal', 'rule', 'line' , 'hr', 'section', 'divider', 'break']
+---
+
+<section data-tab="Guidelines">
+  @include "partials/guidelines/overview.md"
+  @include "partials/guidelines/guidelines.md"
+</section>
+
+<section data-tab="Code">
+  @include "partials/code/how-to-use.md"
+  @include "partials/code/component-api.md"
+  <!-- @include "partials/code/showcase.md" -->
+</section>
+
+<section data-tab="Accessibility">
+  @include "partials/accessibility/accessibility.md"
+</section>

website/docs/components/separator/partials/accessibility/accessibility.md

@@ -0,0 +1,9 @@
+## Conformance rating
+
+<Doc::Badge @type="success">Conformant</Doc::Badge>
+
+When used as recommended, there should not be any WCAG conformance issues with this component.
+
+---
+
+<Doc::A11ySupport />

website/docs/components/separator/partials/code/component-api.md

@@ -0,0 +1,8 @@
+## Component API
+
+<Doc::ComponentApi as |C|>
+  <C.Property @name="spacing" @type="string" @values={{array "0" "24" }} @default="24"/>
+  <C.Property @name="...attributes">
+    This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering).
+  </C.Property>
+</Doc::ComponentApi>

website/docs/components/separator/partials/code/how-to-use.md

@@ -0,0 +1,15 @@
+## How to use this component
+
+The Separator renders a thematic break element (also known as horizontal rule, or `<hr/>` element) with equal top and bottom margins to create space between sections.
+
+```handlebars
+<Hds::Separator/>
+```
+
+### Spacing
+
+The default spacing value is `24` pixels. If you need to use the Separator without margins set `@spacing` to `0`.
+
+```handlebars
+<Hds::Separator @spacing="0"/>
+```

website/docs/components/separator/partials/code/showcase.md

@@ -0,0 +1,3 @@
+## Showcase
+
+<!-- Leave it as is, we don't expose the component showcase for now. -->

website/docs/components/separator/partials/guidelines/guidelines.md

@@ -0,0 +1,27 @@
+
+## Placement
+
+Use separators to distinguish between sections on a page visually. Use them sparingly and purposefully to avoid cluttering the UI and distracting users from the main content.
+
+!!! Do
+
+Use to create a clear break between paragraphs, blocks, or sections.
+
+![Example of the separator component used correctly between content sections] (/assets/components/separator/separator-do.png =275x*)
+
+!!!
+
+!!! Dont
+
+Don’t use to separate headings and body text. Instead, emphasize hierarchy by using the proper [Display font style](https://helios.hashicorp.design/foundations/typography?tab=code#font-styles). 
+
+![Example of the separator component used improperly, causing clutter and disrupting content flow."](/assets/components/separator/separator-dont.png =600x*)
+
+!!!
+
+## Spacing
+
+We recommend using meaningful spacing between content elements, allowing users to scan and understand information quickly.
+
+- Use the `0px` spacing option for a tightly integrated layout without any visible gaps between elements.
+- Use the `24px` spacing option to visually distinguish between different sections, making it simpler for users to navigate and understand the content.