From 47336cf1c0075339137eedd8a0c3fd98c1b8841e Mon Sep 17 00:00:00 2001 From: Damien Retzinger Date: Wed, 17 Jul 2024 09:59:54 -0400 Subject: [PATCH] docs(design): add new docs for modal --- .../src/app/modal/modal.component.html | 87 ++++++++++++++++--- libs/design/modal/README.md | 57 +++++++++--- 2 files changed, 116 insertions(+), 28 deletions(-) diff --git a/apps/design-land/src/app/modal/modal.component.html b/apps/design-land/src/app/modal/modal.component.html index f96e0d78b6..5b94f793c7 100644 --- a/apps/design-land/src/app/modal/modal.component.html +++ b/apps/design-land/src/app/modal/modal.component.html @@ -1,17 +1,76 @@

Modal

-

Modal is a dynamically rendered element that floats about the rest of a page's content. It can be especially useful for interstitials that require additional user feedback.

+

Modal is a dynamically rendered element that floats above the rest of a page's content. It can be especially useful for interstitials that require additional user feedback.

-

Supported Content Types

-

These components and directives help to structure the content in your modal.

-

The DaffModalComponent optionally transcludes:

- - -

Usage

+

Basic Modal

+ +

Supported Content Types

+

A modal includes minimally pre-styled components and directives to help structure the content in your modal.

+ +

Header

+

Header can be added to a modal by using <daff-modal-header>. The header includes a title and an optional close button.

+ +

Title

+Title can be added to the header by using the daffModalTitle directive. + +

Close Button

+

The close button is shown by default but can be hidden by setting the dismissible property to false on the header.

+ +

Content

+

Content can be added to a modal by using <daff-modal-content>. It should only be used once. It's a wrapper container that can be used to place all additional components and text content within a modal. The content container allows for a ton of control and customization because it's minimally pre-styled and serves as a wrapping and spacing container that is scrollable.

+ +

Actions

+

Buttons can be added to a modal by using <daff-modal-actions>. This container will always be positioned at the bottom of a modal. The horizontal alignment of the actions is set to end.

+ +

Configurations

+

A modal relies on the use of entryComponents of the particular Angular @NgModule. To use the features of the modal:

+ +
    +
  1. Import the DaffModalModule as you would with any other @daffodil/design component.
    2. +
  2. Add the component that you want rendered inside the modal to your @NgModule's entryComponents.
    3. +
+ +
custom-modal.module.ts
+
+@NgModule({
+	declarations: [
+		CustomModalComponent,
+	],
+	imports: [
+		DaffModalModule,
+	],
+	entryComponents: [
+		CustomModalComponent,
+	]
+})
+
+export class CustomModalModule {}
+ +

After you have imported the DaffModalModule into your component or module's imports, you can use the DaffModalService to open and close instances of the DaffModalComponent.

+ +
custom-modal.component.ts
+
+@Component({
+	templated: '<button (click)="showModal()"><button>'
+})
+
+export class CustomModalComponent {
+	constructor(private modalService: DaffModalService) {}
+
+	showModal() {
+		this.modalService.open(CustomModalComponent);
+	}
+}
+
+ +
You will likely never render the DaffModalComponent directly like you would with other components due to its dynamic nature.
+ +

Dismissing a Modal

+

A modal can be dismissed via the close button or the ESC key. The close button is shown by default but can be hidden by setting the dismissible property to false on <daff-modal-header>. Additionally, the [daffModalClose] directive can be added to a <button> HTML element.

+ +

Accessibility

+

Modal works with the ARIA role="dialog" and aria-modal="true" attributes to provide an accessible experience. aria-labelledby is assigned the [daffModalTitle] string. When a modal is opened, the first tabbable element within it will receive focus.

+ +

Keyboard Interactions

+

A modal can be closed by choosing one of the actions buttons, the close button in the header, or it can be dismissed by pressing the ESC key.

+ diff --git a/libs/design/modal/README.md b/libs/design/modal/README.md index c64154423d..0fbd972446 100644 --- a/libs/design/modal/README.md +++ b/libs/design/modal/README.md @@ -1,41 +1,61 @@ -# Modal Component +# Modal +Modal is a dynamically rendered element that floats above the rest of a page's content. It can be especially useful for interstitials that require additional user feedback. -The `DaffModalComponent` is a dynamically rendered component that floats above the rest of a page's content. It can be especially useful for interstitials that require additional user feedback. +## Basic Modal + -## Usage +## Supported Content Types +A modal includes minimally pre-styled components and directives to help structure the content in your modal. -`DaffModalComponent` relies on using the `entryComponents` of the particular Angular `@NgModule`. To use the features of the `DaffModalComponent`: +### Header +Header can be added to a modal by using ``. The header includes a title and an optional close button. -* Import the `DaffModalModule` as you would with any other `@daffodil/design` component -* Add the component that you want rendered inside the modal to your `@NgModule`'s `entryComponents` +#### Title +Title can be added to the header by using the `[daffModalTitle]` directive. + +#### Close Button +The close button in the header is shown by default but can be hidden by setting the `dismissible` property to `false` on the header. + +### Content +Content can be added to a modal by using ``. It should only be used once. It's a wrapper container that can be used to place all additional components and text content within a modal. The content container allows for a ton of control and customization because it's minimally pre-styled and serves as a wrapping and spacing container that is scrollable. + +### Actions +Buttons can be added to a modal by using ``. This container will always be positioned at the bottom of a modal. The horizontal alignment of the actions is set to `end`. + +## Configurations + +A modal relies on using the `entryComponents` of the particular Angular `@NgModule`. To use the features of the `DaffModalComponent`: + +1. Import the `DaffModalModule` as you would with any other `@daffodil/design` component +2. Add the component that you want rendered inside the modal to your `@NgModule`'s `entryComponents` ```ts -my.module.ts +custom-modal.module.ts @NgModule({ declarations: [ - MyModalContentComponent, + CustomModalComponent, ], imports: [ DaffModalModule, ], entryComponents: [ - MyModalContentComponent + CustomModalComponent ] }) -export class ModalModule { +export class CustomModalModule { } ``` -Once your `@NgModule` has been configured, you can take advantage of the `DaffModalService` that is provided by the `DaffModalModule` to `open` and `close` the instance of the `DaffModalComponent`. +After you have imported the `DaffModalModule` into your component or module's imports, you can use the `DaffModalService` to open and close instances of the `DaffModalComponent`. ```ts -my-other.component.ts +custom-modal.component.ts @Component({ template: '' }) -export class MyOtherComponent { +export class CustomModalComponent { constructor(private modalService: DaffModalService) {} showModal() { @@ -44,4 +64,13 @@ export class MyOtherComponent { } ``` -> You will likely never render the `DaffModalComponent` directly like you would with other components due to its dynamic nature. \ No newline at end of file +> You will likely never render the `DaffModalComponent` directly like you would with other components due to its dynamic nature. + +## Dismissing a Modal +A modal can be dismissed via the close button or the `ESC` key. The close button is shown by default but can be hidden by setting the `disimssible` property to `false` on ``. Additionally, the `[daffModalClose]` directive can be added to a `