@hashicorp/design-system-components 3.0.2 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @hashicorp/design-system-components
 
+## 3.1.0
+
+### Minor Changes
+
+`CodeBlock` - Added new component
+
+<small>[#1687](https://github.com/hashicorp/design-system/pull/1687)</small>
+
+---
+
+### Patch Changes
+
+Upgraded the following dependencies:
+
+- `@ember/test-waiters` from `3.0.2` to `3.1.0`
+- `ember-cli-htmlbars` from `6.2.0` to `6.3.0`
+- `ember-focus-trap` from `1.0.2` to `1.1.0`
+- `ember-keyboard` from `8.2.0` to `8.2.1`
+- `sass` from `1.62.1` to `1.69.5`
+
+<small>[#1756](https://github.com/hashicorp/design-system/pull/1756)</small>
+
+---
+
+`Breadcrumb` - Added support for external links
+
+<small>[#1774](https://github.com/hashicorp/design-system/pull/1774)</small>
+
+---
+
+Upgraded the following dependencies:
+
+- `ember-cached-decorator-polyfill` from `0.1.4` to `1.0.2`
+- `ember-cli-babel` from `7.26.11` to `8.2.0`
+- `ember-cli-sass` from `10.0.1` to `11.0.1`
+- `ember-composable-helpers` from `4.5.0` to `5.0.0`
+
+<small>[#1761](https://github.com/hashicorp/design-system/pull/1761)</small>
+
+---
+
+`Button` - Fixed `HdsInteractiveSignature` type import
+
+<small>[#1769](https://github.com/hashicorp/design-system/pull/1769)</small>
+
+---
+
+**🔄 Updated dependencies:**
+
+- @hashicorp/ember-flight-icons@4.0.2
+
 ## 3.0.2
 
 ### Patch Changes

package/NEW-COMPONENT-CHECKLIST.md

@@ -1,70 +1,89 @@
 # New Component Checklist
 
-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`.
+This is the checklist the HDS team uses for any new component project. 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 Audit](https://www.figma.com/file/h3LtloARmbYVwh7z6XWHVb/Component-Audits-FY23?node-id=0%3A1): This audit should be completed by ambassadors before any work gets started.
-- [Component Requirement Document (CRD)](https://docs.google.com/document/d/1kGcdfnb_z5tVUUvkSJGQPOssNd1yl2SVyd7bqk1KXII/): This file should exist before any design explorations or code is written.
-- ["System of Systems" Storybook](https://unofficial-design-system-search.vercel.app) (storybook of storybooks): use for reference, to consider existing features that we might need to replicate in the component.
+The following should be available as resources for the Project Kickoff.
 
+- [Component Audit](https://www.figma.com/file/wPDhYo23Rk5WDZ5lHC04W3/Component-Audits-FY24?type=design&t=yWY94cHxIGiat5L7-6): This audit is performed by HDS Ambassadors and should be **complete** before the kickoff. 
+- [Component Requirement Document (CRD)](https://docs.google.com/document/d/1kGcdfnb_z5tVUUvkSJGQPOssNd1yl2SVyd7bqk1KXII/): This file should be started before the kickoff and include an early estimate of scope and any open questions that need to be answered during the kickoff.
+
+## Project Kickoff
+
+A project kickoff will be scheduled before the project start date. The kickoff will be used to align on project scope, timelines, and milestones and as a space to discuss any open questions. In attendance should be Design System team leadership, lead Designer and Engineer on the project, and Design/Engineer buddies (if applicable). 
 
 ## Design Checklist
-The design checklist has 5 parts:
-1. creating the branch
-2. design explorations and iterations
+The design checklist has 4 primary parts:
+1. component design
+2. testing
 3. documentation
-4. release
-5. testing
+4. final release
 
-The design process is largely cyclical, so some of these steps may need to be repeated until approval.
+The design process is largely cyclical, so some steps may be repeated until final approval.
 
-### Component Creation
+### Component Design
 - [ ] [create a branch](https://help.figma.com/hc/en-us/articles/360063144053-Create-branches-and-merge-changes#Create_a_branch) in the [product components ui kit](https://www.figma.com/file/noyY6dUMDYjmySpHcMjhkN/HDS-Product---Components)
 - [ ] add a new page for the component, as needed
-- [ ] copy & paste the [stickersheet template](https://www.figma.com/file/noyY6dUMDYjmySpHcMjhkN/HDS-Product---Components?node-id=2279%3A26800) found in UI Helpers to the new page
-  - [ ] update the status badge to "In progress"
-  - [ ] change "{DOC TYPE}" to "STICKERSHEET"
+- [ ] copy & paste the [new component template](https://www.figma.com/file/noyY6dUMDYjmySpHcMjhkN/HDS-Product---Components?type=design&node-id=46856-287&mode=design&t=V4zCk5Jv07PcHYzZ-4) to the new page
+  - [ ] set the position of this frame to 0, 0
+  - [ ] update the status badge in the banner to "In progress"
   - [ ] change "{Component name}" to the name of the component
-  - [ ] delete the sunset notice
-- [ ] **design**
-  - [ ] work through design explorations, providing 2-3 visual directions based on existing [foundations](https://www.figma.com/file/oQsMzMMnynfPWpMEt91OpH/HDS-Product---Foundations?node-id=2916%3A4) and patterns, as well as the findings from the audit and requirements from the CRD
-  - [ ] review with appropriate stakeholders (typically HDS designers, engineering partner, ambassadors) and iterate
-  - [ ] review for a11y considerations and iterate, as necessary
-  - [ ] review with design leadership and iterate, as necessary
-  - [ ] once approved, build out the design as a component
-    - ensure the variant and property names align with what was discussed/decided on with your engineering partner
-  - [ ] test the component with HDS designers and iterate, as necessary
-  - [ ] sync with your engineering partner (pseudo handoff)
-    - let them know it's been design approved and discuss any remaining questions (this should be an ongoing process as well)
-- [ ] **documentation**
-  - all documentation should be contained within frames so it can be easily linked to
-  - [ ] stickersheet
-    - make sure the component instances can be easily selected and other layers are locked
-  - [ ] design guidelines
-    - when complete, lock this frame
-  - [ ] figma tips, as necessary
-    - when complete, lock this frame
-  - [ ] migration details, as necessary
-    - when complete, lock this frame
-  - [ ] let your engineering partner know that design guidelines are ready to be added to the scrappy site (they will add it themselves)
-- [ ] **release**
-  - [ ] lock and hide the components leaving only the stickersheets and docs visible, and change the header's badge to Experimental
-  - [ ] add release notes to the changelog
-  - [ ] review with situationally appropriate reviewers to get final approval
+  - [ ] delete the figma tips frame, if not needed
+- [ ] design and build the component, taking into account existing [foundations](https://www.figma.com/file/oQsMzMMnynfPWpMEt91OpH/HDS-Product---Foundations?node-id=2916%3A4) and patterns, as well as the findings from the audit and requirements from the CRD
+  - artifacts should include: 
+    - component explorations
+    - examples in context
+    - built component
+- [ ] review with situationally appropriate stakeholders and iterate
+  - reviewers should include: 
+    - HDS designers and manager
+    - engineering partner(s)
+    - a11y SME
+    - other external stakeholders as defined during the kickoff
+    - consider also including the design ambassadors
+  - reviews should include checks for: 
+    - alignment to Helios design vision
+    - ux solution
+    - fulfillment of requirements from the audit and CRD
+    - a11y conformance
+    - alignment to code API
+    - consistent naming conventions
+    - token usage
+- [ ] have HDS designers test the component and iterate, as necessary
+- [ ] add a variety of examples to the stickersheet
+  - make sure the component instances can be easily selected and other layers are locked
+- [ ] add any necessary figma tips
+- [ ] request a final branch review from HDS designers
+- [ ] sync with your engineering partner
+  - let them know it's been approved and answer any remaining questions
+       
+### Component Testing
+- [ ] prepare for testing
+  - [ ] lock the components
+  - [ ] change the badge in the banner to "Experimental"
   - [ ] merge the branch
-  - [ ] publish the ui kit
-    - Important: do not communicate this release to consumers yet! (this will be done later in the process)
-- [ ] **testing**
-  - [ ] add a new page to the [playground](https://www.figma.com/file/95YqaJF4TNV72ucXbyC7A0/Playground?node-id=302%3A10) file and prepare a frame for each ambassador to test
+  - [ ] publish the component
+    - Important: do not communicate this release to consumers yet (this will be done later in the process)
+  - [ ] add a new page to the [playground](https://www.figma.com/file/JnkAC69NeUX83Pug32o7Mr/%F0%9F%AA%81-Playground-FY24?type=design&node-id=302-10&mode=design&t=Ov4rEelxWK7rxLdI-0) file and prepare a frame for each ambassador
     - provide a variety (basic to complex) of screenshots to recreate based on real world examples from the audit
-  - [ ] test the component with ambassadors
-  - if iterations are needed, work through the process until approved (don't forget to branch!)
-- [ ] **final release**
-  - this comes after ambassadors have tested the component in Figma and no other adjustments are needed
-  - [ ] if changes were required, follow the steps under "release" again
-  - [ ] share about the release in the slack channel [#team-design-systems](https://hashicorp.slack.com/archives/C7KTUHNUS) and let consumers know that the component is available for use in Figma
+- [ ] ask ambassadors to test the component
+  - depending on the complexity, we usually give them 3-4 days to complete the testing
+- [ ] if iterations are needed, work through the process until approved (don't forget to branch!)
+     
+### Documentation
+- [ ] while the component is being tested, write the documentation
+  - artifacts should include:
+    - design guidelines
+    - specifications
+    - relevant accessibility details
+       
+### Release in Figma
+Once ambassadors have tested the component and iterations are approved, prepare for a final release of the component.
+
+- [ ] add a changelog entry to [CHANGELOG-FIGMA-COMPONENTS.md](https://github.com/hashicorp/design-system/blob/main/packages/components/CHANGELOG-FIGMA-COMPONENTS.md)
+- [ ] if changes were made, publish the component
+- [ ] once the code has been released, communicate the release in the slack channel [#team-design-systems](https://hashicorp.slack.com/archives/C7KTUHNUS)
 
 
 ## Engineering Checklist

package/addon/components/hds/breadcrumb/item.hbs

@@ -13,18 +13,38 @@
       <span class="hds-breadcrumb__text">{{@text}}</span>
     </div>
   {{else}}
-    <LinkTo
-      class="hds-breadcrumb__link"
-      @models={{hds-link-to-models @model @models}}
-      @query={{hds-link-to-query @query}}
-      @route={{@route}}
-    >
-      {{#if @icon}}
-        <div class="hds-breadcrumb__icon">
-          <FlightIcon @name={{@icon}} @size="16" @stretched={{true}} />
-        </div>
-      {{/if}}
-      <span class="hds-breadcrumb__text">{{@text}}</span>
-    </LinkTo>
+    {{#if @isRouteExternal}}
+      <LinkToExternal
+        class="hds-breadcrumb__link"
+        @current-when={{@current-when}}
+        @models={{hds-link-to-models @model @models}}
+        @query={{hds-link-to-query @query}}
+        @replace={{@replace}}
+        @route={{@route}}
+      >
+        {{#if @icon}}
+          <div class="hds-breadcrumb__icon">
+            <FlightIcon @name={{@icon}} @size="16" @stretched={{true}} />
+          </div>
+        {{/if}}
+        <span class="hds-breadcrumb__text">{{@text}}</span>
+      </LinkToExternal>
+    {{else}}
+      <LinkTo
+        class="hds-breadcrumb__link"
+        @current-when={{@current-when}}
+        @models={{hds-link-to-models @model @models}}
+        @query={{hds-link-to-query @query}}
+        @replace={{@replace}}
+        @route={{@route}}
+      >
+        {{#if @icon}}
+          <div class="hds-breadcrumb__icon">
+            <FlightIcon @name={{@icon}} @size="16" @stretched={{true}} />
+          </div>
+        {{/if}}
+        <span class="hds-breadcrumb__text">{{@text}}</span>
+      </LinkTo>
+    {{/if}}
   {{/if}}
 </li>

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

@@ -5,7 +5,7 @@
 
 import Component from '@glimmer/component';
 import { assert } from '@ember/debug';
-import { HdsInteractiveSignature } from '../interactive';
+import { type HdsInteractiveSignature } from '../interactive';
 
 export const DEFAULT_SIZE = 'medium';
 export const DEFAULT_COLOR = 'primary';

package/addon/components/hds/code-block/copy-button.hbs

@@ -0,0 +1,13 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+
+<Hds::Copy::Button
+  class="hds-code-block__copy-button"
+  @text="Copy"
+  @isIconOnly={{true}}
+  @size="small"
+  @targetToCopy={{@targetToCopy}}
+  ...attributes
+/>

package/addon/components/hds/code-block/description.hbs

@@ -0,0 +1,8 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+
+<Hds::Text::Body @tag="p" @size="100" class="hds-code-block__description" ...attributes>
+  {{yield}}
+</Hds::Text::Body>

package/addon/components/hds/code-block/index.hbs

@@ -0,0 +1,30 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+
+<div class={{this.classNames}} ...attributes>
+  <div class="hds-code-block__header">
+    {{~yield (hash Title=(component "hds/code-block/title"))~}}
+    {{~yield (hash Description=(component "hds/code-block/description"))~}}
+  </div>
+  <div class="hds-code-block__body">
+    <pre
+      class="hds-code-block__code"
+      {{style maxHeight=@maxHeight}}
+      data-line={{@highlightLines}}
+      id={{this.preCodeId}}
+      tabindex="0"
+    >
+      {{~! ~}}
+      <code {{did-insert this.setPrismCode}} {{did-update this.setPrismCode this.code @language}}>
+        {{~this.prismCode~}}
+      </code>
+      {{~! ~}}
+    </pre>
+
+    {{#if @hasCopyButton}}
+      <Hds::CodeBlock::CopyButton @targetToCopy="#{{this.preCodeId}}" aria-describedby={{this.preCodeId}} />
+    {{/if}}
+  </div>
+</div>

package/addon/components/hds/code-block/index.js

@@ -0,0 +1,162 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import Component from '@glimmer/component';
+import { action } from '@ember/object';
+import { tracked } from '@glimmer/tracking';
+import { assert } from '@ember/debug';
+import { htmlSafe } from '@ember/template';
+import { guidFor } from '@ember/object/internals';
+
+import Prism from 'prismjs';
+
+import 'prismjs/plugins/line-numbers/prism-line-numbers';
+import 'prismjs/plugins/line-highlight/prism-line-highlight';
+
+import 'prismjs/components/prism-bash';
+import 'prismjs/components/prism-go';
+import 'prismjs/components/prism-hcl';
+import 'prismjs/components/prism-json';
+import 'prismjs/components/prism-log';
+import 'prismjs/components/prism-shell-session';
+import 'prismjs/components/prism-yaml';
+
+// These imports are required to overcome a global variable clash in Helios website
+// where language import are overriden by the Prism instance in `CodeBlock`
+// Note that `prism-handlebars` is dependant on `prism-markup-templating`
+import 'prismjs/components/prism-markup-templating';
+import 'prismjs/components/prism-handlebars';
+
+export default class HdsCodeBlockIndexComponent extends Component {
+  @tracked prismCode = '';
+
+  /**
+   * Generates a unique ID for the code content
+   *
+   * @param preCodeId
+   */
+  preCodeId = 'pre-code-' + guidFor(this);
+
+  /**
+   * @param code
+   * @type {string}
+   * @description code text content for the CodeBlock
+   */
+  get code() {
+    const code = this.args.value;
+
+    assert(
+      '@code for "Hds::CodeBlock" must have a valid value',
+      code !== undefined
+    );
+
+    if (Prism?.plugins?.NormalizeWhitespace) {
+      return Prism.plugins.NormalizeWhitespace.normalize(code);
+    }
+
+    return code;
+  }
+
+  /**
+   * @param language
+   * @type {string}
+   * @default undefined
+   * @description name of coding language used within CodeBlock for syntax highlighting
+   */
+  get language() {
+    return this.args.language ?? undefined;
+  }
+
+  /**
+   * @param hasLineNumbers
+   * @type {boolean}
+   * @default true
+   * @description Displays line numbers if true
+   */
+  get hasLineNumbers() {
+    return this.args.hasLineNumbers ?? true;
+  }
+
+  /**
+   * @param isStandalone
+   * @type {boolean}
+   * @default true
+   * @description Make CodeBlock container corners appear rounded
+   */
+  get isStandalone() {
+    return this.args.isStandalone ?? true;
+  }
+
+  /**
+   * @param hasLineWrapping
+   * @type {boolean}
+   * @default false
+   * @description Make text content wrap on multiple lines
+   */
+  get hasLineWrapping() {
+    return this.args.hasLineWrapping ?? false;
+  }
+
+  @action
+  setPrismCode(element) {
+    const code = this.code;
+    const language = this.language;
+    const grammar = Prism.languages[language];
+
+    if (code) {
+      if (language && grammar) {
+        this.prismCode = htmlSafe(Prism.highlight(code, grammar, language));
+      } else {
+        this.prismCode = htmlSafe(Prism.util.encode(code));
+      }
+
+      // Force prism-line-numbers plugin initialization, required for Prism.highlight usage
+      // See https://github.com/PrismJS/prism/issues/1234
+      Prism.hooks.run('complete', {
+        code,
+        element,
+      });
+
+      // Force prism-line-highlight plugin initialization
+      // Context: https://github.com/hashicorp/design-system/pull/1749#discussion_r1374288785
+      if (this.args.highlightLines) {
+        setTimeout(() => {
+          // we piggy-back on the plugin's `resize` event listener to trigger a new call of the `highlightLines` function: https://github.com/PrismJS/prism/blob/master/plugins/line-highlight/prism-line-highlight.js#L337
+          if (window) window.dispatchEvent(new Event('resize'));
+        }, 100);
+      }
+    }
+  }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  get classNames() {
+    // Currently there is only one theme so the class name is hard-coded.
+    // In the future, additional themes such as a "light" theme could be added.
+    let classes = ['hds-code-block', 'hds-code-block--theme-dark'];
+
+    if (this.language) {
+      classes.push(`language-${this.language}`);
+    }
+
+    if (this.isStandalone === true) {
+      classes.push('hds-code-block--is-standalone');
+    }
+
+    if (this.hasLineWrapping === true) {
+      classes.push('hds-code-block--has-line-wrapping');
+    }
+
+    // Note: Prism.js is using the specific class name "line-numbers" to determine implementation of line numbers in the UI
+    if (this.hasLineNumbers || this.args.highlightLines) {
+      classes.push('line-numbers');
+    }
+
+    return classes.join(' ');
+  }
+}

package/addon/components/hds/code-block/title.hbs

@@ -0,0 +1,8 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+
+<Hds::Text::Body @size="200" @tag="p" @weight="semibold" class="hds-code-block__title" ...attributes>
+  {{yield}}
+</Hds::Text::Body>

package/app/components/hds/code-block/copy-button.js

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

package/app/components/hds/code-block/description.js

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

package/app/components/hds/code-block/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/code-block/index';

package/app/components/hds/code-block/title.js

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

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

@@ -24,6 +24,7 @@
 @use "../components/button";
 @use "../components/button-set";
 @use "../components/card";
+@use "../components/code-block";
 @use "../components/copy";
 @use "../components/disclosure-primitive";
 @use "../components/dismiss-button";

package/app/styles/components/code-block/index.scss

@@ -0,0 +1,249 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+//
+// CODE-BLOCK
+//
+
+
+@use "../../mixins/focus-ring" as *;
+
+// Note: "theme" contains just color variables and syntax highlighting styles
+@import "theme";
+
+// DIMENSIONS
+$code-block-line-numbers-width: 49px; // 3em ≈ 49px
+$code-block-code-padding: 16px;
+
+// CODE-BLOCK PARENT/WRAPPER
+
+.hds-code-block {
+  position: relative;
+  color: var(--hds-code-block-color-foreground-primary);
+  background-color: var(--hds-code-block-color-surface-primary);
+  border: 1px solid var(--hds-code-block-color-border-strong);
+
+  pre,
+  code {
+    line-height: 1.4286;
+    white-space: pre;
+    text-align: left;
+    text-shadow: none;
+    word-wrap: normal;
+    word-break: normal;
+    word-spacing: normal;
+    tab-size: 4;
+    hyphens: none;
+
+    @media print { text-shadow: none; }
+  }
+}
+
+// VARIANTS
+
+// isStandalone
+.hds-code-block--is-standalone {
+  border-radius: 6px;
+}
+
+// hasLineWrapping
+.hds-code-block--has-line-wrapping {
+  .hds-code-block__code,
+  .hds-code-block__code code {
+    white-space: pre-wrap;
+  }
+}
+
+// CHILD COMPONENTS / ELEMENTS
+
+// Header (contains title & description)
+
+.hds-code-block__title {
+  color: var(--hds-code-block-color-foreground-primary);
+}
+
+.hds-code-block__description {
+  color: var(--hds-code-block-color-foreground-faint);
+}
+
+.hds-code-block__header {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 8px $code-block-code-padding;
+  background-color: var(--hds-code-block-color-surface-faint);
+  border-bottom: 1px solid var(--hds-code-block-color-border-primary);
+  border-top-left-radius: inherit;
+  border-top-right-radius: inherit;
+
+  &:empty {
+    display: none;
+  }
+
+  // we add very basic styling for elements that may be yielded in the "title"/"description" elements
+
+  strong {
+    font-weight: var(--token-typography-font-weight-semibold);
+  }
+
+  code,
+  pre {
+    display: inline;
+    font-size: 0.9em; // as discussed with designers, we reduce the size for optical/visual balance
+    font-family: var(--token-typography-code-100-font-family);
+    line-height: 1em;
+  }
+
+  // Default styling for bare HTML links not using HDS::Link components
+  a:not([class*="hds-"]) {
+    color: var(--hds-code-block-color-foreground-action);
+
+    &:focus,
+    &:focus-visible {
+      text-decoration: none;
+      outline: 2px solid var(--token-color-focus-action-internal);
+      outline-offset: 1px;
+    }
+
+    &:hover {
+      color: var(--token-color-foreground-action-hover);
+    }
+
+    &:active {
+      color: var(--token-color-foreground-action-active);
+    }
+  }
+}
+
+.hds-code-block__body {
+  position: relative;
+  border-radius: inherit;
+}
+
+// Code
+.hds-code-block__code {
+  @include hds-focus-ring-basic();
+  display: block;
+  margin: 0;
+  padding: $code-block-code-padding;
+  overflow: auto;
+  font-size: 0.8125rem;
+  font-family: var(--hds-typography-code-200);
+  border-radius: inherit;
+
+  ::selection {
+    color: var(--hds-code-block-color-foreground-selection);
+    background-color: var(--hds-code-block-color-surface-selection);
+  }
+}
+
+// CopyButton
+.hds-code-block__copy-button {
+  position: absolute;
+  top: 11px; // 12px -1px accounting for border
+  right: 12px; // 12px -1px accounting for border
+  // Overriding default colors
+  color: var(--hds-code-block-color-foreground-primary);
+  background-color: var(--hds-code-block-color-surface-faint);
+  border: 1px solid var(--hds-code-block-color-border-strong);
+
+  &:hover,
+  &.mock-hover {
+    background-color: var(--hds-code-block-color-surface-primary);
+    border-color: var(--hds-code-block-color-border-strong);
+  }
+
+  &:active,
+  &.mock-active {
+    background-color: var(--hds-code-block-color-surface-interactive-active);
+  }
+
+  &:focus,
+  &.mock-focus,
+  &:focus-visible {
+    background-color: var(--hds-code-block-color-surface-faint);
+  }
+
+  &.hds-copy-button--status-success {
+    .flight-icon {
+      color: var(--hds-code-block-color-foreground-success);
+    }
+  }
+
+  &.hds-copy-button--status-error {
+    .flight-icon {
+      color: var(--hds-code-block-color-foreground-critical);
+    }
+  }
+
+  .flight-icon { color: var(--hds-code-block-color-foreground-primary); }
+}
+
+.hds-code-block {
+  // LineNumbers plugin styles ---------------
+  // Note: Prism.js is using the specific class name "line-numbers" to determine implementation of line numbers in the UI
+  &.line-numbers {
+    counter-reset: linenumber;
+
+    .hds-code-block__code {
+      position: relative;
+      // reserve space for line numbers
+      padding-left: calc(#{$code-block-line-numbers-width} + #{$code-block-code-padding});
+    }
+
+    .line-numbers-rows {
+      position: absolute;
+      top: 0;
+      left: 0;
+      min-width: $code-block-line-numbers-width;
+      min-height: 100%;
+      padding: $code-block-code-padding 0;
+      border-right: 1px solid var(--hds-code-block-color-border-primary);
+      user-select: none;
+      pointer-events: none;
+
+      > span {
+        display: block;
+        counter-increment: linenumber;
+
+        &::before {
+          display: block;
+          padding-right: $code-block-code-padding;
+          text-align: right;
+          content: counter(linenumber);
+        }
+      }
+    }
+  }
+
+  // Highlighted Lines
+  .line-highlight {
+    position: absolute;
+    right: 0;
+    left: 0;
+    // Note: position seems off by a few px although not sure why
+    margin-top: -3px;
+    background-color: var(--hds-code-block-color-line-highlight);
+    border: solid var(--hds-code-block-color-line-highlight-border);
+    border-width: 1px 0 1px 4px;
+    mix-blend-mode: screen;
+    pointer-events: none;
+  }
+
+  @media print {
+    .line-highlight {
+      /*
+       * This will prevent browsers from replacing the background color with white.
+       * It's necessary because the element is layered on top of the displayed code.
+       */
+      -webkit-print-color-adjust: exact;
+      color-adjust: exact;
+    }
+  }
+
+  // commmon tokens
+  .token.bold { font-weight: bold; }
+  .token.italic { font-style: italic; }
+}

package/app/styles/components/code-block/theme.scss

@@ -0,0 +1,159 @@
+// THEMING
+
+.hds-code-block--theme-dark {
+  // COLORS
+
+  // Descriptive color names:
+
+  --hds-code-block-color-blue: #2d8eff;
+  --hds-code-block-color-cyan: #32fff7;
+  --hds-code-block-color-green: #86ff13;
+  --hds-code-block-color-orange: #ffa800;
+  --hds-code-block-color-purple: #c76cff;
+  --hds-code-block-color-red: #ff3b20;
+
+  // Semantic color names:
+
+  // Base UI colors:
+  --hds-code-block-color-foreground-primary: #d5d7db;
+  --hds-code-block-color-foreground-faint: #b2b6bd;
+  --hds-code-block-color-surface-primary: #0d0e12;
+  --hds-code-block-color-surface-faint: #15181e;
+  // status ----
+  --hds-code-block-color-foreground-success: #009241;
+  --hds-code-block-color-foreground-critical: #ef3016;
+  // interactive ---
+  --hds-code-block-color-foreground-interactive: #dedfe3;
+  --hds-code-block-color-foreground-interactive-hover: #fff;
+  --hds-code-block-color-foreground-interactive-active: #f1f2f3;
+  --hds-code-block-color-surface-interactive-active: #2b303c;
+  // actions ---
+  --hds-code-block-color-foreground-action: #2b89ff;
+  --hds-code-block-color-foreground-action-hover: #389aff;
+  --hds-code-block-color-foreground-action-active: #4ca1ff;
+  // borders
+  --hds-code-block-color-border-strong: rgba(178, 182, 189, 40%); // #b2b6bd66
+  --hds-code-block-color-border-primary: rgba(178, 182, 189, 20%); // #b2b6bd33
+  // selection
+  --hds-code-block-color-foreground-selection: #0d0e12;
+  --hds-code-block-color-surface-selection: #86ff13;
+
+  // CodeBlock UI:
+  // lines of code - highlighted ----
+  --hds-code-block-color-line-highlight: rgba(0, 74, 222, 20%);
+  --hds-code-block-color-line-highlight-border: #1555d4;
+
+  // Syntax highlighting tokens:
+  // general ----
+  --hds-code-block-color-token: var(--hds-code-block-color-green);
+  // specific ----
+  --hds-code-block-color-atrule: var(--hds-code-block-color-blue);
+  --hds-code-block-color-code-block-attr-name: var(--hds-code-block-color-blue);
+  --hds-code-block-color-attr-value: var(--hds-code-block-color-blue);
+  --hds-code-block-color-boolean: var(--hds-code-block-color-purple);
+  --hds-code-block-color-builtin: var(--hds-code-block-color-orange);
+  --hds-code-block-color-char: var(--hds-code-block-color-orange);
+  --hds-code-block-color-class-name: var(--hds-code-block-color-green);
+  --hds-code-block-color-comment: var(--hds-code-block-color-foreground-faint);
+  --hds-code-block-color-control: var(--hds-code-block-color-cyan);
+  --hds-code-block-color-constant: var(--hds-code-block-color-purple);
+  --hds-code-block-color-deleted: var(--hds-code-block-color-red);
+  --hds-code-block-color-entity: var(--hds-code-block-color-green);
+  --hds-code-block-color-function: var(--hds-code-block-color-blue);
+  --hds-code-block-color-important: var(--hds-code-block-color-red);
+  --hds-code-block-color-keyword: var(--hds-code-block-color-green);
+  --hds-code-block-color-namespace: var(--hds-code-block-color-red);
+  --hds-code-block-color-number: var(--hds-code-block-color-purple);
+  --hds-code-block-color-operator: var(--hds-code-block-color-cyan);
+  --hds-code-block-color-prolog: var(--hds-code-block-color-foreground-primary);
+  --hds-code-block-color-property: var(--hds-code-block-color-blue);
+  --hds-code-block-color-punctuation: var(--hds-code-block-color-foreground-primary);
+  --hds-code-block-color-regex: var(--hds-code-block-color-orange);
+  --hds-code-block-color-script: var(--hds-code-block-color-foreground-primary);
+  --hds-code-block-color-selector: var(--hds-code-block-color-green);
+  --hds-code-block-color-string: var(--hds-code-block-color-orange);
+  --hds-code-block-color-symbol: var(--hds-code-block-color-orange);
+  --hds-code-block-color-tag: var(--hds-code-block-color-green);
+  --hds-code-block-color-url: var(--hds-code-block-color-cyan);
+  // language-scoped:
+  // css ----
+  --hds-code-block-color-lang-css: var(--hds-code-block-color-purple);
+  --hds-code-block-color-lang-css-token: var(--hds-code-block-color-green);
+  --hds-code-block-color-lang-css-atrule: var(--hds-code-block-color-purple);
+  --hds-code-block-color-lang-css-entity: var(--hds-code-block-color-blue);
+  --hds-code-block-color-lang-css-function: var(--hds-code-block-color-cyan);
+  --hds-code-block-color-lang-css-property: var(--hds-code-block-color-cyan);
+  --hds-code-block-color-lang-css-punctuation: var(--hds-code-block-color-orange);
+  --hds-code-block-color-lang-css-not-atrule: var(--hds-code-block-color-foreground-primary);
+  --hds-code-block-color-lang-css-selector: var(--hds-code-block-color-blue);
+  --hds-code-block-color-lang-css-url: var(--hds-code-block-color-orange);
+  // javascript ----
+  --hds-code-block-color-lang-js-constant: var(--hds-code-block-color-orange);
+  // markup/html ----
+  --hds-code-block-color-lang-markup-attr-value: var(--hds-code-block-color-yellow);
+  --hds-code-block-color-lang-markup-entity-named: var(--hds-code-block-color-purple);
+  --hds-code-block-color-lang-markup-entity-not-named: var(--hds-code-block-color-green);
+}
+
+
+.hds-code-block {
+  // Syntax highlighting ----
+
+  // General tokens
+  .token { color: var(--hds-code-block-color-token); }
+
+  .token.atrule { color: var(--hds-code-block-color-atrule); }
+  .token.attr-name { color: var(--hds-code-block-color-attr-name); }
+  .token.attr-value { color: var(--hds-code-block-color-attr-value); }
+  .token.boolean { color: var(--hds-code-block-color-boolean); }
+  .token.builtin { color: var(--hds-code-block-color-builtin); }
+  .token.char { color: var(--hds-code-block-color-char); }
+  .token.class-name { color: var(--hds-code-block-color-class-name); }
+  .token.comment { color: var(--hds-code-block-color-comment); }
+  .token.constant { color: var(--hds-code-block-color-constant); }
+  .token.deleted { color: var(--hds-code-block-color-deleted); }
+  .token.entity { color: var(--hds-code-block-color-entity); }
+  .token.function { color: var(--hds-code-block-color-function); }
+  .token.important { color: var(--hds-code-block-color-important); }
+  .token.keyword { color: var(--hds-code-block-color-keyword); }
+  .token.namespace { color: var(--hds-code-block-color-namespace); }
+  .token.number { color: var(--hds-code-block-color-number); }
+  .token.operator { color: var(--hds-code-block-color-operator); }
+  .token.punctuation { color: var(--hds-code-block-color-punctuation); }
+  .token.prolog { color: var(--hds-code-block-color-prolog); }
+  .token.property { color: var(--hds-code-block-color-property); }
+  .token.regex { color: var(--hds-code-block-color-regex); }
+  .token.script { color: var(--hds-code-block-color-script); }
+  .token.selector { color: var(--hds-code-block-color-selector); }
+  .token.string { color: var(--hds-code-block-color-string); }
+  .token.symbol { color: var(--hds-code-block-color-symbol); }
+  .token.tag { color: var(--hds-code-block-color-tag); }
+  .token.url { color: var(--hds-code-block-color-url); }
+  .token.variable { color: var(--hds-code-block-color-comment); }
+
+  // Language-specific
+  .language-css {
+    color: var(--hds-code-block-color-lang-css);
+
+    .token { color: var(--hds-code-block-color-lang-css-token); }
+    .token.atrule { color: var(--hds-code-block-color-lang-css-atrule); }
+    .token.rule:not(.atrule) { color: var(--hds-code-block-color-lang-css-not-atrule); }
+    .token.entity { color: var(--hds-code-block-color-lang-css-entity); }
+    .token.function { color: var(--hds-code-block-color-lang-css-function); }
+    .token.property { color: var(--hds-code-block-color-lang-css-property); }
+    .token.punctuation { color: var(--hds-code-block-color-lang-css-punctuatione); }
+    .token.selector { color: var(--hds-code-block-color-lang-css-selector); }
+    .token.url { color: var(--hds-code-block-color-lang-css-url); }
+  }
+
+  .language-javascript {
+    .token.constant { color: var(--hds-code-block-color-lang-js-constant); }
+  }
+
+  .language-markup,
+  .language-html {
+    .token.attr-value { color: var(--hds-code-block-color-lang-markup-attr-value); }
+    .token.entity.named-entity { color: var(--hds-code-block-color-lang-markup-entity-named); }
+    .token.entity:not(.named-entity) { color: var(--hds-code-block-color-lang-markup-entity-not-named); }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashicorp/design-system-components",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Helios Design System Components",
   "keywords": [
     "hashicorp",
@@ -41,101 +41,85 @@
   },
   "dependencies": {
     "@ember/render-modifiers": "^2.0.5",
-    "@ember/test-waiters": "^3.0.2",
+    "@ember/test-waiters": "^3.1.0",
     "@hashicorp/design-system-tokens": "^1.9.0",
-    "@hashicorp/ember-flight-icons": "^4.0.1",
+    "@hashicorp/ember-flight-icons": "^4.0.2",
     "dialog-polyfill": "^0.5.6",
     "ember-a11y-refocus": "^3.0.2",
     "ember-auto-import": "^2.6.3",
-    "ember-cached-decorator-polyfill": "^0.1.4",
-    "ember-cli-babel": "^7.26.11",
-    "ember-cli-htmlbars": "^6.2.0",
-    "ember-cli-sass": "^10.0.1",
-    "ember-composable-helpers": "^4.5.0",
+    "ember-cached-decorator-polyfill": "^1.0.2",
+    "ember-cli-babel": "^8.2.0",
+    "ember-cli-htmlbars": "^6.3.0",
+    "ember-cli-sass": "^11.0.1",
+    "ember-composable-helpers": "^5.0.0",
     "ember-element-helper": "^0.8.5",
-    "ember-focus-trap": "^1.0.2",
-    "ember-keyboard": "^8.2.0",
+    "ember-focus-trap": "^1.1.0",
+    "ember-keyboard": "^8.2.1",
     "ember-stargate": "^0.4.3",
     "ember-style-modifier": "^3.0.1",
     "ember-truth-helpers": "^3.1.1",
-    "sass": "^1.62.1",
+    "prismjs": "^1.29.0",
+    "sass": "^1.69.5",
     "tippy.js": "^6.3.7"
   },
   "devDependencies": {
+    "@babel/core": "^7.23.2",
+    "@babel/eslint-parser": "^7.22.15",
+    "@babel/plugin-proposal-decorators": "^7.23.2",
     "@ember/optional-features": "^2.0.0",
-    "@ember/string": "^3.1.1",
-    "@ember/test-helpers": "^2.9.3",
-    "@embroider/test-setup": "^2.1.1",
+    "@ember/test-helpers": "^3.2.0",
+    "@embroider/test-setup": "^3.0.2",
     "@glimmer/component": "^1.1.2",
     "@glimmer/tracking": "^1.1.2",
-    "@glint/core": "^1.1.0",
-    "@glint/environment-ember-loose": "^1.1.0",
-    "@glint/template": "^1.1.0",
-    "@percy/cli": "^1.24.2",
+    "@glint/core": "^1.2.1",
+    "@glint/environment-ember-loose": "^1.2.1",
+    "@glint/template": "^1.2.1",
+    "@percy/cli": "^1.27.3",
     "@percy/ember": "^4.2.0",
-    "@tsconfig/ember": "latest",
-    "@types/ember": "latest",
-    "@types/ember-qunit": "latest",
-    "@types/ember-resolver": "latest",
-    "@types/ember__application": "latest",
-    "@types/ember__array": "latest",
-    "@types/ember__component": "latest",
-    "@types/ember__controller": "latest",
-    "@types/ember__debug": "latest",
-    "@types/ember__destroyable": "latest",
-    "@types/ember__engine": "latest",
-    "@types/ember__error": "latest",
-    "@types/ember__object": "latest",
-    "@types/ember__polyfills": "latest",
-    "@types/ember__routing": "latest",
-    "@types/ember__runloop": "latest",
-    "@types/ember__service": "latest",
-    "@types/ember__string": "latest",
-    "@types/ember__template": "latest",
-    "@types/ember__test": "latest",
-    "@types/ember__test-helpers": "latest",
-    "@types/ember__utils": "latest",
-    "@types/qunit": "latest",
-    "@types/rsvp": "latest",
-    "babel-eslint": "^10.1.0",
+    "@tsconfig/ember": "^3.0.2",
+    "@types/ember-qunit": "^6.1.1",
+    "@types/ember-resolver": "^9.0.0",
+    "@types/qunit": "^2.19.7",
+    "@types/rsvp": "^4.0.6",
     "broccoli-asset-rev": "^3.0.0",
-    "ember-a11y-testing": "^5.2.1",
+    "ember-a11y-testing": "^6.1.1",
     "ember-body-class": "^3.0.0",
-    "ember-cli": "~4.12.1",
-    "ember-cli-dependency-checker": "^3.3.1",
+    "ember-cli": "~5.3.0",
+    "ember-cli-clean-css": "^3.0.0",
+    "ember-cli-dependency-checker": "^3.3.2",
     "ember-cli-deprecation-workflow": "^2.1.0",
     "ember-cli-inject-live-reload": "^2.1.0",
     "ember-cli-sri": "^2.1.1",
     "ember-cli-string-helpers": "^6.1.0",
     "ember-cli-terser": "^4.0.2",
-    "ember-concurrency": "^2.3.7",
+    "ember-concurrency": "^3.1.1",
     "ember-load-initializers": "^2.1.2",
-    "ember-page-title": "^7.0.0",
-    "ember-power-select": "^6.0.1",
-    "ember-qunit": "^6.2.0",
-    "ember-resolver": "^10.1.0",
-    "ember-source": "~4.12.0",
+    "ember-page-title": "^8.0.0",
+    "ember-power-select": "^7.1.2",
+    "ember-qunit": "^8.0.1",
+    "ember-resolver": "^11.0.1",
+    "ember-source": "~5.3.0",
     "ember-source-channel-url": "^3.0.0",
     "ember-template-lint": "^4.18.2",
-    "ember-template-lint-plugin-prettier": "^4.1.0",
-    "ember-try": "^2.0.0",
-    "eslint": "^7.32.0",
-    "eslint-config-prettier": "^8.8.0",
-    "eslint-plugin-ember": "^11.7.2",
+    "ember-template-lint-plugin-prettier": "^4.2.0",
+    "ember-try": "^3.0.0",
+    "eslint": "^8.52.0",
+    "eslint-config-prettier": "^8.10.0",
+    "eslint-plugin-ember": "^11.11.1",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-qunit": "^7.3.4",
+    "eslint-plugin-qunit": "^8.0.1",
     "loader.js": "^4.7.0",
     "npm-run-all": "^4.1.5",
     "prettier": "^2.8.8",
-    "qunit": "^2.19.4",
-    "qunit-dom": "^2.0.0",
-    "sinon": "^15.2.0",
-    "stylelint": "^15.10.1",
+    "qunit": "^2.20.0",
+    "qunit-dom": "^3.0.0",
+    "sinon": "^17.0.0",
+    "stylelint": "^15.11.0",
     "stylelint-config-rational-order": "^0.1.2",
     "stylelint-config-standard-scss": "^5.0.0",
-    "typescript": "^5.1.6",
-    "webpack": "^5.84.1"
+    "typescript": "^5.2.2",
+    "webpack": "^5.89.0"
   },
   "engines": {
     "node": "16.* || >= 18"

package/tsconfig.declarations.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declarationDir": "declarations",
+    "emitDeclarationOnly": true,
+    "noEmit": false,
+    "rootDir": "."
+  },
+  "include": ["addon", "addon-test-support"]
+}

package/tsconfig.json

@@ -7,6 +7,7 @@
     // layout, which is not resolvable with the Node resolution algorithm, to
     // work with TypeScript.
     "baseUrl": ".",
+    "skipLibCheck": true,
     "paths": {
       "dummy/tests/*": [
         "tests/*"

package/types/dummy/index.d.ts

@@ -3,4 +3,5 @@
  * SPDX-License-Identifier: MPL-2.0
  */
 
+import 'ember-source/types';
 import '@glint/environment-ember-loose';