Layout::Flex - Component implementation

.changeset/funny-dragons-kneel.md

@@ -0,0 +1,5 @@
+---
+"@hashicorp/design-system-components": minor
+---
+
+`Layout::Flex` - Added `Flex` and `Flex::Item` components

packages/components/package.json

@@ -253,6 +253,8 @@
       "./components/hds/icon-tile/index.js": "./dist/_app_/components/hds/icon-tile/index.js",
       "./components/hds/icon/index.js": "./dist/_app_/components/hds/icon/index.js",
       "./components/hds/interactive/index.js": "./dist/_app_/components/hds/interactive/index.js",
+      "./components/hds/layout/flex/index.js": "./dist/_app_/components/hds/layout/flex/index.js",
+      "./components/hds/layout/flex/item.js": "./dist/_app_/components/hds/layout/flex/item.js",
       "./components/hds/link/inline.js": "./dist/_app_/components/hds/link/inline.js",
       "./components/hds/link/standalone.js": "./dist/_app_/components/hds/link/standalone.js",
       "./components/hds/menu-primitive/index.js": "./dist/_app_/components/hds/menu-primitive/index.js",

packages/components/src/components/hds/layout/flex/index.hbs

@@ -0,0 +1,15 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+{{!
+  Dynamically generating an HTML tag in Ember creates a dynamic component class (with the corresponding tagName), while rendering
+  a plain HTML element requires less computing cycles for Ember (you will notice it doesn't add the `ember-view` class to it).
+}}
+{{#if (eq this.componentTag "div")}}
+  <div class={{this.classNames}} ...attributes>{{yield (hash Item=(component "hds/layout/flex/item"))}}</div>
+{{else}}
+  {{#let (element this.componentTag) as |Tag|}}
+    <Tag class={{this.classNames}} ...attributes>{{yield (hash Item=(component "hds/layout/flex/item"))}}</Tag>
+  {{/let}}
+{{/if}}

packages/components/src/components/hds/layout/flex/index.ts

@@ -0,0 +1,165 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import Component from '@glimmer/component';
+import { assert } from '@ember/debug';
+
+import type { ComponentLike } from '@glint/template';
+
+import type { HdsLayoutFlexItemSignature } from './item.ts';
+
+import {
+  HdsLayoutFlexDirectionValues,
+  HdsLayoutFlexJustifyValues,
+  HdsLayoutFlexAlignValues,
+  HdsLayoutFlexGapValues,
+} from './types.ts';
+
+import type {
+  HdsLayoutFlexDirections,
+  HdsLayoutFlexJustifys,
+  HdsLayoutFlexAligns,
+  HdsLayoutFlexGaps,
+  AvailableTagNames,
+  AvailableElements,
+} from './types.ts';
+
+export const DEFAULT_DIRECTION = HdsLayoutFlexDirectionValues.Row;
+export const DIRECTIONS: string[] = Object.values(HdsLayoutFlexDirectionValues);
+export const JUSTIFYS: string[] = Object.values(HdsLayoutFlexJustifyValues);
+export const ALIGNS: string[] = Object.values(HdsLayoutFlexAlignValues);
+export const GAPS: string[] = Object.values(HdsLayoutFlexGapValues);
+
+export interface HdsLayoutFlexSignature {
+  Args: {
+    tag?: AvailableTagNames;
+    direction?: HdsLayoutFlexDirections;
+    justify?: HdsLayoutFlexJustifys;
+    align?: HdsLayoutFlexAligns;
+    wrap?: boolean;
+    gap?: HdsLayoutFlexGaps | [HdsLayoutFlexGaps, HdsLayoutFlexGaps];
+    isInline?: boolean;
+  };
+  Blocks: {
+    default: [
+      {
+        Item?: ComponentLike<HdsLayoutFlexItemSignature>;
+      },
+    ];
+  };
+  Element: AvailableElements;
+}
+
+export default class HdsLayoutFlex extends Component<HdsLayoutFlexSignature> {
+  get componentTag(): AvailableTagNames {
+    return this.args.tag ?? 'div';
+  }
+
+  get direction(): HdsLayoutFlexDirections {
+    const { direction = DEFAULT_DIRECTION } = this.args;
+
+    assert(
+      `@direction for "Hds::Layout::Flex" must be one of the following: ${DIRECTIONS.join(
+        ', '
+      )}; received: ${direction}`,
+      DIRECTIONS.includes(direction)
+    );
+
+    return direction;
+  }
+
+  get justify(): HdsLayoutFlexJustifys | undefined {
+    const { justify } = this.args;
+
+    if (justify) {
+      assert(
+        `@justify for "Hds::Layout::Flex" must be one of the following: ${JUSTIFYS.join(
+          ', '
+        )}; received: ${justify}`,
+        JUSTIFYS.includes(justify)
+      );
+    }
+
+    return justify;
+  }
+
+  get align(): HdsLayoutFlexAligns | undefined {
+    const { align } = this.args;
+
+    if (align) {
+      assert(
+        `@align for "Hds::Layout::Flex" must be one of the following: ${ALIGNS.join(
+          ', '
+        )}; received: ${align}`,
+        ALIGNS.includes(align)
+      );
+    }
+
+    return align;
+  }
+
+  get gap():
+    | [HdsLayoutFlexGaps]
+    | [HdsLayoutFlexGaps, HdsLayoutFlexGaps]
+    | undefined {
+    const { gap } = this.args;
+
+    if (gap) {
+      assert(
+        `@gap for "Hds::Layout::Flex" must be a single value or an array of two values of one of the following: ${GAPS.join(
+          ', '
+        )}; received: ${gap}`,
+        (!Array.isArray(gap) && GAPS.includes(gap)) ||
+          (Array.isArray(gap) &&
+            gap.length === 2 &&
+            GAPS.includes(gap[0]) &&
+            GAPS.includes(gap[1]))
+      );
+      return Array.isArray(gap) ? gap : [gap];
+    } else {
+      return undefined;
+    }
+  }
+
+  get classNames() {
+    const classes = ['hds-layout-flex'];
+
+    // add a class based on the @direction argument
+    classes.push(`hds-layout-flex--direction-${this.direction}`);
+
+    // add a class based on the @justify argument
+    if (this.justify) {
+      classes.push(`hds-layout-flex--justify-content-${this.justify}`);
+    }
+
+    // add a class based on the @align argument
+    if (this.align) {
+      classes.push(`hds-layout-flex--align-items-${this.align}`);
+    }
+
+    // add a class based on the @gap argument
+    if (this.gap) {
+      if (this.gap.length === 2) {
+        classes.push(`hds-layout-flex--row-gap-${this.gap[0]}`);
+        classes.push(`hds-layout-flex--column-gap-${this.gap[1]}`);
+      } else if (this.gap.length === 1) {
+        classes.push(`hds-layout-flex--row-gap-${this.gap[0]}`);
+        classes.push(`hds-layout-flex--column-gap-${this.gap[0]}`);
+      }
+    }
+
+    // add a class based on the @wrap argument
+    if (this.args.wrap) {
+      classes.push('hds-layout-flex--has-wrapping');
+    }
+
+    // add a class based on the @isInline argument
+    if (this.args.isInline) {
+      classes.push('hds-layout-flex--is-inline');
+    }
+
+    return classes.join(' ');
+  }
+}

packages/components/src/components/hds/layout/flex/item.hbs

@@ -0,0 +1,17 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+{{!
+  Dynamically generating an HTML tag in Ember creates a dynamic component class (with the corresponding tagName), while rendering
+  a plain HTML element requires less computing cycles for Ember (you will notice it doesn't add the `ember-view` class to it).
+}}
+{{#if (eq this.componentTag "div")}}
+  <div class={{this.classNames}} {{style this.inlineStyles}} ...attributes>{{yield}}</div>
+{{else}}
+  {{#let (element this.componentTag) as |Tag|}}<Tag
+      class={{this.classNames}}
+      {{style this.inlineStyles}}
+      ...attributes
+    >{{yield}}</Tag>{{/let}}
+{{/if}}

packages/components/src/components/hds/layout/flex/item.ts

@@ -0,0 +1,90 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import Component from '@glimmer/component';
+
+import type { AvailableTagNames, AvailableElements } from './types.ts';
+
+export interface HdsLayoutFlexItemSignature {
+  Args: {
+    tag?: AvailableTagNames;
+    basis?: string | 0;
+    grow?: boolean | number | string;
+    shrink?: boolean | number | string;
+    // TODO final name TBD
+    enableCollapseBelowContentSize?: boolean;
+  };
+  Blocks: {
+    default: [];
+  };
+  Element: AvailableElements;
+}
+
+export default class HdsLayoutFlexItem extends Component<HdsLayoutFlexItemSignature> {
+  get componentTag(): AvailableTagNames {
+    return this.args.tag ?? 'div';
+  }
+
+  get inlineStyles(): Record<string, unknown> {
+    const inlineStyles: {
+      'flex-basis'?: string;
+      'flex-grow'?: string;
+      'flex-shrink'?: string;
+    } = {};
+
+    // we handle all non-zero cases of `basis` values via inline styles
+    if (typeof this.args.basis === 'string') {
+      inlineStyles['flex-basis'] = this.args.basis;
+    }
+
+    // we handle non-standard cases of `grow` values via inline styles
+    if (typeof this.args.grow === 'number' && this.args.grow > 1) {
+      // the `{{style}}` modifier accepts only strings
+      inlineStyles['flex-grow'] = this.args.grow.toString();
+    } else if (typeof this.args.grow === 'string') {
+      inlineStyles['flex-grow'] = this.args.grow;
+    }
+
+    // we handle non-standard cases of `shrink` values via inline styles
+    if (typeof this.args.shrink === 'number' && this.args.shrink > 1) {
+      // the `{{style}}` modifier accepts only strings
+      inlineStyles['flex-shrink'] = this.args.shrink.toString();
+    } else if (typeof this.args.shrink === 'string') {
+      inlineStyles['flex-shrink'] = this.args.shrink;
+    }
+
+    return inlineStyles;
+  }
+
+  get classNames() {
+    const classes = ['hds-layout-flex-item'];
+
+    // add a class based on the @basis argument (if set to `0`)
+    if (this.args.basis === 0) {
+      classes.push('hds-layout-flex-item--basis-0');
+    }
+
+    // add a class based on the @grow argument (if set to `0/1` or `true/false`)
+    if (this.args.grow === 0 || this.args.grow === false) {
+      classes.push('hds-layout-flex-item--grow-0');
+    } else if (this.args.grow === 1 || this.args.grow === true) {
+      classes.push('hds-layout-flex-item--grow-1');
+    }
+
+    // add a class based on the @shrink argument (if set to `0/1` or `true/false`)
+    if (this.args.shrink === 0 || this.args.shrink === false) {
+      classes.push('hds-layout-flex-item--shrink-0');
+    } else if (this.args.shrink === 1 || this.args.shrink === true) {
+      classes.push('hds-layout-flex-item--shrink-1');
+    }
+
+    // add a class based on the @enableCollapseBelowContentSize argument (applies a `min-width: 0`)
+    if (this.args.enableCollapseBelowContentSize) {
+      classes.push('hds-layout-flex-item--enable-collapse-below-content-size');
+    }
+
+    return classes.join(' ');
+  }
+}

packages/components/src/components/hds/layout/flex/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+export enum HdsLayoutFlexDirectionValues {
+  Row = 'row',
+  Column = 'column',
+}
+
+export type HdsLayoutFlexDirections = `${HdsLayoutFlexDirectionValues}`;
+
+export enum HdsLayoutFlexJustifyValues {
+  Start = 'start',
+  Center = 'center',
+  End = 'end',
+  SpaceBetween = 'space-between',
+  SpaceAround = 'space-around',
+  SpaceEvenly = 'space-evenly',
+}
+
+export type HdsLayoutFlexJustifys = `${HdsLayoutFlexJustifyValues}`;
+
+export enum HdsLayoutFlexAlignValues {
+  Start = 'start',
+  Center = 'center',
+  End = 'end',
+  Stretch = 'stretch',
+}
+
+export type HdsLayoutFlexAligns = `${HdsLayoutFlexAlignValues}`;
+
+export enum HdsLayoutFlexGapValues {
+  'Four' = '4',
+  'Eight' = '8',
+  'Twelve' = '12',
+  'Sixteen' = '16',
+  'TwentyFour' = '24',
+  'ThirtyTwo' = '32',
+  'FortyEight' = '48',
+}
+
+export type HdsLayoutFlexGaps = `${HdsLayoutFlexGapValues}`;
+
+// A list of all existing tag names in the HTMLElementTagNameMap interface
+export type AvailableTagNames = keyof HTMLElementTagNameMap;
+// A union of all types in the HTMLElementTagNameMap interface
+export type AvailableElements =
+  HTMLElementTagNameMap[keyof HTMLElementTagNameMap];

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

@@ -37,6 +37,7 @@
 @use "../components/form"; // multiple components
 @use "../components/icon";
 @use "../components/icon-tile";
+@use "../components/layout"; // multiple components
 @use "../components/link"; // multiple components
 @use "../components/menu-primitive";
 @use "../components/modal";