feat: add contained-list

src/carbon.yml

@@ -113,6 +113,15 @@ assets:
         name: Storybook
         action: link
         url: https://angular.carbondesignsystem.com/?path=/story/components-combobox
+  contained-list:
+    status: stable
+    framework: angular
+    externalDocsUrl: https://carbondesignsystem.com/components/contained-list/usage/
+    demoLinks:
+      - type: storybook
+        name: Storybook
+        action: link
+        url: https://angular.carbondesignsystem.com/?path=/story/components-contained-list
   content-switcher:
     status: stable
     framework: angular

src/contained-list/contained-list-item.component.ts

@@ -0,0 +1,99 @@
+import {
+	ChangeDetectionStrategy,
+	Component,
+	EventEmitter,
+	HostBinding,
+	Input,
+	Output,
+	TemplateRef
+} from "@angular/core";
+
+@Component({
+	selector: "cds-contained-list-item, ibm-contained-list-item",
+	template: `
+		<ng-container *ngIf="clickable">
+			<button
+				class="cds--contained-list-item__content"
+				type="button"
+				[disabled]="disabled"
+				(click)="onClick()">
+				<ng-content select="[ibmContainedListItemButton]"></ng-content>
+			</button>
+		</ng-container>
+		<ng-container *ngIf="!clickable">
+			<div class="cds--contained-list-item__content">
+				<div *ngIf="icon" class="cds--contained-list-item__icon">
+					<ng-container *ngIf="!isTemplate(icon)"><svg [ibmIcon]="icon" size="16"></svg></ng-container>
+					<ng-template *ngIf="isTemplate(icon)" [ngTemplateOutlet]="icon"></ng-template>
+				</div>
+				<ng-content></ng-content>
+			</div>
+		</ng-container>
+		<div class="cds--contained-list-item__action" *ngIf="action">
+			<ng-template [ngTemplateOutlet]="action"></ng-template>
+		</div>
+	`,
+	changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class ContainedListItem {
+	/**
+	 * A slot for a possible interactive element to render within the item.
+	 */
+	@Input() action: TemplateRef<any>;
+
+	/**
+	 * Whether this item is disabled.
+	 */
+	@Input() disabled = false;
+
+	/**
+	 * Whether this item is clickable.
+	 */
+	@Input() clickable: boolean;
+
+	/**
+	 * Provide an optional icon to render in front of the item's content.
+	 *
+	 * Note that if you intend to use this as a string ref, it's important to remember
+	 * to register the icon that you wish to add. In this case, it's also worth noting
+	 * that only icons with a size of 16 are currently supported.
+	 */
+	@Input() icon: TemplateRef<any> | string;
+
+	/**
+	 * Emits click event.
+	 */
+	@Output() click = new EventEmitter<void>();
+
+	/**
+	 * Host binding item class.
+	 */
+	@HostBinding("class.cds--contained-list-item") itemClass = true;
+
+	/**
+	 * Host binding item role attribute
+	 */
+	@HostBinding("attr.role") role = "listitem";
+
+	/**
+	 * Host binding clickable item class.
+	 */
+	@HostBinding("class.cds--contained-list-item--clickable") get itemClickableClass() {
+		return this.clickable;
+	}
+
+	/**
+	 * Host binding item with icon class.
+	 */
+	@HostBinding("class.cds--contained-list-item--with-icon") get itemWithIconClass() {
+		return !!this.icon;
+	}
+
+	public onClick() {
+		this.click.emit();
+	}
+
+	public isTemplate(value: string | TemplateRef<any>) {
+		return value instanceof TemplateRef;
+	}
+}

src/contained-list/contained-list.component.spec.ts

@@ -0,0 +1,167 @@
+import { Component } from "@angular/core";
+import { ComponentFixture, TestBed } from "@angular/core/testing";
+import { By } from "@angular/platform-browser";
+import { ButtonModule } from "../button";
+import { IconModule, IconService } from "../icon";
+import { ContainedListItem } from "./contained-list-item.component";
+import Apple16 from "@carbon/icons/es/apple/16";
+import Fish16 from "@carbon/icons/es/fish/16";
+import { ContainedList } from "./contained-list.component";
+import { ContainedListKind, ContainedListSize } from "./contained-list.enums";
+
+@Component({
+	template: `
+		<ng-template #label>
+	  		<h1>My Contained List</h1>
+		</ng-template>
+
+		<ng-template #action>
+			<ibm-icon-button
+				type="button"
+				kind="primary"
+				align="left"
+				description="Add">
+				<svg class="cds--btn__icon" ibmIcon="add" size="16"></svg>
+			</ibm-icon-button>
+		</ng-template>
+
+		<ng-template #icon>
+			<svg ibmIcon="fish" size="16"></svg>
+		</ng-template>
+
+		<cds-contained-list [label]="label" [action]="action">
+			<cds-contained-list-item>List item</cds-contained-list-item>
+			<cds-contained-list-item [icon]="icon">List item with icon</cds-contained-list-item>
+			<cds-contained-list-item icon="apple">List item with string ref icon</cds-contained-list-item>
+			<cds-contained-list-item [action]="action">List item with action</cds-contained-list-item>
+			<cds-contained-list-item #clickableListItem [clickable]="true">
+				<ng-container ibmContainedListItemButton>Clickable list item</ng-container>
+			</cds-contained-list-item>
+		</cds-contained-list>
+	`
+})
+class WrapperComponent {
+	constructor(private iconService: IconService) {
+		this.iconService.registerAll([Apple16, Fish16]);
+	}
+}
+
+describe("ContainedList", () => {
+	let component: ContainedList;
+	let fixture: ComponentFixture<ContainedList>;
+
+	beforeEach(async () => {
+		await TestBed.configureTestingModule({
+			declarations: [ContainedList, ContainedListItem, WrapperComponent],
+			imports: [IconModule, ButtonModule]
+		}).compileComponents();
+
+		fixture = TestBed.createComponent(ContainedList);
+		component = fixture.componentInstance;
+	});
+
+	it("should set default inputs", () => {
+		fixture.detectChanges();
+		expect(component.action).toBeUndefined();
+		expect(component.isInset).toBeFalsy();
+		expect(component.kind).toBe(ContainedListKind.OnPage);
+		expect(component.label).toBeUndefined();
+		expect(component.size).toBe(ContainedListSize.Large);
+	});
+
+	it("should display the label when a string is provided", () => {
+		const label = "My Contained List";
+		component.label = label;
+		fixture.detectChanges();
+
+		const labelElement = fixture.nativeElement.querySelector(".cds--contained-list__label");
+		expect(labelElement.textContent.trim()).toEqual(label);
+	});
+
+	it("should have the correct isInset class", () => {
+		component.isInset = true;
+		fixture.detectChanges();
+
+		const listElement: HTMLElement = fixture.nativeElement.querySelector(".cds--contained-list");
+		expect(listElement).toHaveClass("cds--contained-list--inset-rulers");
+	});
+
+	it("should have the correct size class", () => {
+		component.size = ContainedListSize.Small;
+		fixture.detectChanges();
+
+		const listElement: HTMLElement = fixture.nativeElement.querySelector(".cds--contained-list");
+		expect(listElement).toHaveClass("cds--contained-list--sm");
+	});
+
+	it("should have the correct kind class", () => {
+		component.kind = ContainedListKind.Disclosed;
+		fixture.detectChanges();
+
+		const listElement: HTMLElement = fixture.nativeElement.querySelector(".cds--contained-list");
+		expect(listElement).toHaveClass("cds--contained-list--disclosed");
+	});
+
+	describe("TemplateRefs", () => {
+		it("should render the label if it is a TemplateRef", () => {
+			const wrapperFixture: ComponentFixture<WrapperComponent> = TestBed.createComponent(WrapperComponent);
+			wrapperFixture.detectChanges();
+
+			const labelRefElement = wrapperFixture.nativeElement.querySelector(".cds--contained-list .cds--contained-list__label h1");
+			expect(labelRefElement.textContent.trim()).toBe("My Contained List");
+		});
+
+		it("should render the action if it is a TemplateRef", () => {
+			const wrapperFixture: ComponentFixture<WrapperComponent> = TestBed.createComponent(WrapperComponent);
+			wrapperFixture.detectChanges();
+
+			const actionElementRef = wrapperFixture.nativeElement.querySelector(".cds--contained-list .cds--contained-list__action ibm-icon-button");
+			expect(actionElementRef).toBeTruthy();
+		});
+	});
+
+	describe("ContainedListItem", () => {
+		it("should render the content", () => {
+			const wrapperFixture: ComponentFixture<WrapperComponent> = TestBed.createComponent(WrapperComponent);
+			wrapperFixture.detectChanges();
+
+			const listItemElement = wrapperFixture.debugElement.query(By.css(".cds--contained-list-item:nth-child(1)"));
+			expect(listItemElement.nativeElement.textContent.trim()).toBe("List item");
+		});
+
+		it("should render the icon", () => {
+			const wrapperFixture: ComponentFixture<WrapperComponent> = TestBed.createComponent(WrapperComponent);
+			wrapperFixture.detectChanges();
+
+			const iconElement = wrapperFixture.debugElement.query(By.css(".cds--contained-list-item:nth-child(2) svg[ibmIcon='fish']"));
+			expect(iconElement).toBeTruthy();
+		});
+
+		it("should render the icon", () => {
+			const wrapperFixture: ComponentFixture<WrapperComponent> = TestBed.createComponent(WrapperComponent);
+			wrapperFixture.detectChanges();
+
+			const iconElement = wrapperFixture.debugElement.query(By.css(".cds--contained-list-item:nth-child(3) svg[ng-reflect-ibm-icon='apple']"));
+			expect(iconElement).toBeTruthy();
+		});
+
+		it("should render the action", () => {
+			const wrapperFixture: ComponentFixture<WrapperComponent> = TestBed.createComponent(WrapperComponent);
+			wrapperFixture.detectChanges();
+
+			const actionElement = wrapperFixture.debugElement.query(By.css(".cds--contained-list-item:nth-child(4) ibm-icon-button"));
+			expect(actionElement).toBeTruthy();
+		});
+
+		it("should render with the clickable state", () => {
+			const wrapperFixture: ComponentFixture<WrapperComponent> = TestBed.createComponent(WrapperComponent);
+			wrapperFixture.detectChanges();
+
+			const clickableListItemElement = wrapperFixture.debugElement.query(By.css(".cds--contained-list-item:nth-child(5)"));
+			expect(clickableListItemElement.nativeElement).toHaveClass("cds--contained-list-item--clickable");
+
+			const buttonElement = clickableListItemElement.nativeElement.querySelector("button");
+			expect(buttonElement.textContent.trim()).toBe("Clickable list item");
+		});
+	});
+});

src/contained-list/contained-list.component.ts

@@ -0,0 +1,88 @@
+import {
+	ChangeDetectionStrategy,
+	Component,
+	HostBinding,
+	Input,
+	TemplateRef
+} from "@angular/core";
+import { ContainedListKind, ContainedListSize } from "./contained-list.enums";
+
+@Component({
+	selector: "cds-contained-list, ibm-contained-list",
+	template: `
+		<div
+			class="cds--contained-list"
+			[ngClass]="{
+				'cds--contained-list--inset-rulers': isInset,
+				'cds--contained-list--on-page': kind === ContainedListKind.OnPage,
+				'cds--contained-list--disclosed': kind === ContainedListKind.Disclosed,
+				'cds--contained-list--sm': size === ContainedListSize.Small,
+				'cds--contained-list--md': size === ContainedListSize.Medium,
+				'cds--contained-list--lg': size === ContainedListSize.Large,
+				'cds--contained-list--xl': size === ContainedListSize.ExtraLarge
+			}">
+			<div class="cds--contained-list__header">
+				<div [id]="labelId" class="cds--contained-list__label">
+					<ng-container *ngIf="!isTemplate(label)">{{ label }}</ng-container>
+					<ng-template *ngIf="isTemplate(label)" [ngTemplateOutlet]="label"></ng-template>
+				</div>
+
+				<div class="cds--contained-list__action" *ngIf="action">
+					<ng-template [ngTemplateOutlet]="action"></ng-template>
+				</div>
+			</div>
+			<div role="list" [attr.aria-labelledby]="labelId">
+				<ng-content></ng-content>
+			</div>
+		</div>
+	`,
+	changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class ContainedList {
+	/** Used to generate unique IDs */
+	private static count = 0;
+
+	/**
+	 * A slot for a possible interactive element to render within the list header.
+	 */
+	@Input() action: TemplateRef<any>;
+
+	/**
+	 * Specify whether the dividing lines in between list items should be inset.
+	 */
+	@Input() isInset = false;
+
+	/**
+	 * The kind of ContainedList you want to display.
+	 */
+	@Input() kind: ContainedListKind = ContainedListKind.OnPage;
+
+	/**
+	 * A label describing the contained list.
+	 */
+	@Input() label: string | TemplateRef<any>;
+
+	/**
+	 * Specify the size of the contained list.
+	 */
+	@Input() size: ContainedListSize = ContainedListSize.Large;
+
+	/**
+	 * Label id for the contained list.
+	 */
+	readonly labelId = `contained-list-${ContainedList.count++}-header`;
+
+	/**
+	 * Exposing ContainedListSize enum to the template
+	 */
+	public ContainedListSize: typeof ContainedListSize = ContainedListSize;
+
+	/**
+	 * Exposing ContainedListKind enum to the template
+	 */
+	public ContainedListKind: typeof ContainedListKind = ContainedListKind;
+
+	public isTemplate(value: string | TemplateRef<any>) {
+		return value instanceof TemplateRef;
+	}
+}

src/contained-list/contained-list.enums.ts

@@ -0,0 +1,11 @@
+export enum ContainedListSize {
+	Small = "sm",
+	Medium = "md",
+	Large = "lg",
+	ExtraLarge = "xl"
+}
+
+export enum ContainedListKind {
+	OnPage = "on-page",
+	Disclosed = "disclosed"
+}

src/contained-list/contained-list.module.ts

@@ -0,0 +1,12 @@
+import { NgModule } from "@angular/core";
+import { CommonModule } from "@angular/common";
+import { ContainedList } from "./contained-list.component";
+import { ContainedListItem } from "./contained-list-item.component";
+import { IconModule } from "carbon-components-angular/icon";
+
+@NgModule({
+	declarations: [ContainedList, ContainedListItem],
+	exports: [ContainedList, ContainedListItem],
+	imports: [CommonModule, IconModule]
+})
+export class ContainedListModule {}