ApplicationState Enhancements - Documentation

showcase/app/templates/components/application-state.hbs

@@ -298,7 +298,7 @@
           />
           <A.Footer as |F|>
             <F.Button @color="primary" @text="Primary action" />
-            <F.Dropdown @listPosition="bottom-right" as |dd|>
+            <F.Dropdown @color="secondary" @listPosition="bottom-right" as |dd|>
               <dd.ToggleButton @text="Choose an option" />
               <dd.Title @text="Categories" />
               <dd.Interactive @text="Documentation" @href="#" />
@@ -318,7 +318,7 @@
           />
           <A.Footer as |F|>
             <F.Button @color="primary" @text="Primary action" />
-            <F.Dropdown @listPosition="bottom-right" as |dd|>
+            <F.Dropdown @color="secondary" @listPosition="bottom-right" as |dd|>
               <dd.ToggleButton @text="Choose an option" />
               <dd.Title @text="Categories" />
               <dd.Interactive @text="Documentation" @href="#" />

website/docs/components/application-state/index.md

@@ -11,6 +11,7 @@ navigation:
 ---
 
 <section data-tab="Guidelines">
+  @include "partials/guidelines/overview.md"
   @include "partials/guidelines/guidelines.md"
 </section>
 

website/docs/components/application-state/partials/code/component-api.md

@@ -3,6 +3,9 @@
 ### ApplicationState
 
 <Doc::ComponentApi as |C|>
+  <C.Property @name="<[A].Media>" @type="yielded component">
+    `ApplicationState::Media` yielded as contextual component (see below).
+  </C.Property>
   <C.Property @name="<[A].Header>" @type="yielded component">
     `ApplicationState::Header` yielded as contextual component (see below).
   </C.Property>
@@ -19,6 +22,19 @@
 
 ### Contextual components
 
+#### [A].Media
+
+The `ApplicationState::Media` component, yielded as contextual component.
+
+<Doc::ComponentApi as |C|>
+  <C.Property @name="yield">
+    Elements passed as children are yielded as inner content of the "media" block.
+  </C.Property>
+  <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>
+
 #### [A].Header
 
 The `ApplicationState::Header` component, yielded as contextual component.
@@ -30,7 +46,12 @@ The `ApplicationState::Header` component, yielded as contextual component.
   <C.Property @name="icon" @type="string">
     Adds a leading icon to the title. Accepts any [icon](/icons/library) name.
   </C.Property>
-  <C.Property @name="title" @type="string"  />
+  <C.Property @name="title" @type="string">
+    The text of the title
+  </C.Property>
+  <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>
 
 #### [A].Body
@@ -39,10 +60,13 @@ The `ApplicationState::Body` component, yielded as contextual component.
 
 <Doc::ComponentApi as |C|>
   <C.Property @name="yield">
-    Supports block invocation for custom content (see [Block Content](https://guides.emberjs.com/release/components/block-content/) in Ember docs).
+    Elements passed as children are yielded as inner content of the "body" block.
   </C.Property>
   <C.Property @name="text" @type="string">
-    Note: use `@text` for an inline invocation only. This component does not support `@text` on the component invocation if it is used as a block.
+    Note: use `@text` to pass directly text to the "body", with a predefined style. This component does not support `@text` on the component invocation if it is used with yielded content.
+  </C.Property>
+  <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>
 
@@ -51,10 +75,16 @@ The `ApplicationState::Body` component, yielded as contextual component.
 The `ApplicationState::Footer` component, yielded as contextual component.
 
 <Doc::ComponentApi as |C|>
-  <C.Property @name="hasDivider" @type="boolean" @default="false" @values={{array "true" "false"}}>
-    Indicates if there should be a visible divider above the footer.
+  <C.Property @name="<[F].Button>" @type="yielded component">
+    The `Button` component, yielded as contextual component inside the `"footer"` block of the ApplicationState. It exposes the same API as the [`Button` component](/components/button).
+  </C.Property>
+  <C.Property @name="<[F].Dropdown>" @type="yielded component">
+    The `Dropdown` component, yielded as contextual component inside the `"footer"` block of the ApplicationState. It exposes the same API as the [`Dropdown` component](/components/dropdown).
   </C.Property>
   <C.Property @name="<[F].LinkStandalone>" @type="yielded component">
     The `Link::Standalone` component, yielded as contextual component inside the `"footer"` block of the ApplicationState. It exposes the same API as the [`Link::Standalone` component](/components/link/standalone).
   </C.Property>
+  <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/application-state/partials/code/how-to-use.md

@@ -33,37 +33,49 @@ This component intends to replace a few different simple error and empty/zero st
 </Hds::ApplicationState>
 ```
 
-#### Empty state with a footer link and divider
+#### Empty state with yielded body block
 
 ```handlebars
 <Hds::ApplicationState as |A|>
   <A.Header @title="Empty state title text" />
-  <A.Body @text="The item you were looking for was not found." />
-  <A.Footer @hasDivider={{true}} as |F|>
-    <F.LinkStandalone @icon="help" @text="Need Help" @href="/components/alert"
-    @iconPosition="trailing" />
+  <A.Body>
+    <Doc::Placeholder @text="block yield" @height="100" @background="#eee" />
+  </A.Body>
+  <A.Footer as |F|>
+    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
   </A.Footer>
 </Hds::ApplicationState>
 ```
 
-#### Empty state with yielded body block
+#### Empty state with body text
 
 ```handlebars
 <Hds::ApplicationState as |A|>
   <A.Header @title="Empty state title text" />
-  <A.Body>
-    <Doc::Placeholder @text="block yield" @height="100" @background="#eee" />
-  </A.Body>
+  <A.Body @text="Some sentence that conveys a good message to the user" />
   <A.Footer as |F|>
     <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
   </A.Footer>
 </Hds::ApplicationState>
 ```
 
-#### Empty state with body text
+#### Empty state with center alignment
+
+```handlebars
+<Hds::ApplicationState @align="center" as |A|>
+  <A.Header @title="Empty state title text" />
+  <A.Body @text="Some sentence that conveys a good message to the user" />
+  <A.Footer as |F|>
+    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
+  </A.Footer>
+</Hds::ApplicationState>
+```
+
+#### Empty state with media
 
 ```handlebars
 <Hds::ApplicationState as |A|>
+  <A.Media><img src="/assets/images/avatar.png" alt="portrait of a cat wearing coat and tie" /></A.Media>
   <A.Header @title="Empty state title text" />
   <A.Body @text="Some sentence that conveys a good message to the user" />
   <A.Footer as |F|>
@@ -124,19 +136,37 @@ To indicate that the message is an error state, add `@errorCode` to the `[A].Hea
 </Hds::ApplicationState>
 ```
 
-#### Error state with a footer divider
+#### Error state with center alignment
+
+```handlebars
+<Hds::ApplicationState @align="center" as |A|>
+  <A.Header @title="An error has occurred" @errorCode="404" />
+  <A.Body
+    @text="Sorry, an unexpected error has occurred.
+    Please try again later or contact support for assistance."
+  />
+  <A.Footer as |F|>
+    <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
+    <F.LinkStandalone @icon="help" @text="Need Help" 
+      @href="/components/alert" @iconPosition="trailing" />
+  </A.Footer>
+</Hds::ApplicationState>
+```
+
+#### Error state with media
 
 ```handlebars
 <Hds::ApplicationState as |A|>
+  <A.Media><img src="/assets/images/avatar.png" alt="portrait of a cat wearing coat and tie" /></A.Media>
   <A.Header @title="An error has occurred" @errorCode="404" />
   <A.Body
     @text="Sorry, an unexpected error has occurred.
     Please try again later or contact support for assistance."
   />
-  <A.Footer @hasDivider={{true}} as |F|>
+  <A.Footer as |F|>
     <F.LinkStandalone @icon="arrow-left" @text="Go back" @href="/" />
-    <F.LinkStandalone @icon="help" @text="Need Help" @href="/components/alert" 
-      @iconPosition="trailing" />
+    <F.LinkStandalone @icon="help" @text="Need Help" 
+      @href="/components/alert" @iconPosition="trailing" />
   </A.Footer>
 </Hds::ApplicationState>
-```
+```

website/docs/components/application-state/partials/guidelines/guidelines.md

@@ -2,28 +2,117 @@
 
 ### When to use
 
-- When a user’s action does not yield any results due to incorrect or incomplete input.
 - When an application encounters an issue or error during its operation.
+- When emphasis is needed on the creation of a new object within a null state.
 
 ### When not to use
 
 - When the absence of content is expected and does not require an explanation to the user.
 - When there is a clear and intuitive way to add or populate content.
 
-## Icon
+## Alignment
 
-- The icon should align with the purpose of the content and effectively communicate the same message.
+The Application State supports two alignment options: `left` (default) and `center`. The alignment affects text alignment, action placement/alignment in the footer, and media placement; however, it does not change the default page alignment.
 
-## Actions
+!!! Info
 
-- In the footer, you can include up to two stand-alone links. 
-- We don’t recommend using buttons, as most actions will navigate the user away from this page. Learn more about [when to use a link vs. a button](https://helios.hashicorp.design/components/link/standalone#usage).
-- For the standalone link, we recommend using the medium size.
-- Use footer actions to redirect or guide users in solving errors/access issues with actionable steps.
+By default, the Application State has horizontal auto margins applied to it, always centering it on the page or containing element. This can be overridden with CSS properties.
 
-## Content
+!!!
 
-- The title should be short and provide a clear and concise message.
-- Focus on relevant information and avoid unnecessary details.
-- Provide a straightforward explanation of the problem or error.
-- Include suggestions or guidance for how the user can resolve the issue, if possible.
+### Left alignment
+
+![Left aligned application state](/assets/components/application-state/application-state-alignment-left.png)
+
+### Center alignment
+
+![Center aligned application state](/assets/components/application-state/application-state-alignment-center.png)
+
+## Media
+
+The media slot is used to add illustrations to increase the visual impact of the Application State.
+
+This provides additional visual prominence while also elevating the brand experience. If the illustration has a circular container, we recommend setting the `alignment` to `center`.
+
+![Empty state for Vault Secrets, guiding user to create new secrets or importing them](/assets/components/application-state/application-state-media-slot-spot-illustration-center-alignment.png)
+
+
+## Header
+
+### Icon
+
+When set, the icon is displayed side by side with the title.
+
+![Showing an icon left of the title, with some body text below it.](/assets/components/application-state/application-state-icon-usage.png)
+
+This is commonly used when displaying an error state for application failures. The icon must always be accompanied by a title.
+
+### Title
+
+The title should be short and provide a clear and concise message.
+
+### Error code
+
+If enabled and available, an error code will be shown, providing additional information associated with the title.
+
+## Body
+
+Focus on relevant information and avoid unnecessary details. If there is an error, include suggestions or guidance for how the user can resolve the issue, if possible. If no objects are found (zero/empty state), provide a brief explanation on how creating this new object will benefit the user. 
+
+The body allows for two types of content: `text` and `generic`.
+
+![Showing two different kind of body content types, one as text and another as generic yielded content](/assets/components/application-state/application-state-body-content-types.png)
+
+
+## Footer
+The Application State supports up to three actions, including [Dropdown](/components/dropdown), [Standalone Link](/components/link/standalone), and [Button](/components/button) components. Use footer actions to help users resolve errors or access issues with actionable steps.
+
+![A button set showing a dropdown, secondary button, and stand alone link](/assets/components/application-state/application-state-footer-action-types.png)
+
+### Using buttons or links
+
+Buttons, along with links, are the most common actions used in the footer. Buttons are more often used in empty state contexts because they provide high visibility for the primary action on the page. Links are more common in error state contexts as a means to provide a solution to the error they encountered. 
+
+Read more about when to use [Buttons](/components/button) and [Links](/components/link/standalone).
+
+!!! Dont
+
+When there is an empty state that occupies the majority of the page, do not display two similar actions in different areas of the UI. In this example, there is a primary button in the Page Header and in the Application State. 
+
+![Showing an empty state with a primary button and a page header with a primary button](/assets/components/application-state/application-state-empty-state-dont-duplicate-buttons.png)
+
+!!!
+
+!!! Do
+
+Instead, use the Application State as the only means of drawing attention to the primary action.
+
+![Showing an empty state with a primary button with a page header with out a primay button](/assets/components/application-state/application-state-empty-state-do-keep-one-primary-cta.png)
+
+!!!
+
+### Using dropdowns
+
+Dropdowns can be used as actions in the footer in rare cases. Limit dropdowns to one per Application State.
+
+![Showing an empty state with a primary button with a page header with out one](/assets/components/application-state/application-state-dropdown-actions.png)
+
+## Width constraints
+
+The Application State’s content has a max width of 480 pixels. This is done for better readability, ensuring that the max character count is close to 70 characters per line.
+
+## Examples
+
+Here are some common use cases for the Application State, however, it is not limited to just these two examples.
+
+### Error state
+
+Error states are used when the application encounters an issue or error during its operation. It shows the associated error code, icon, messages, and actions to help users find a solution.
+
+![Showing an example of an error state with a 404 error code and two links](/assets/components/application-state/application-state-error-state.png)
+
+### Empty state
+
+An empty state occurs when a user has yet to create an object. Illustrations are placed using the `media` slot to further elevate the experience and express the purpose of the object.
+
+![Showing an empty state with a primary and secondary button along with a stand alone link](/assets/components/application-state/application-state-empty-state.png)

website/docs/components/application-state/partials/guidelines/overview.md

@@ -0,0 +1 @@
+The Application State is used to communicate status, errors, and zero/empty states.

website/docs/components/application-state/partials/specifications/anatomy.md

@@ -4,10 +4,10 @@
 
 | Element          | Usage                                           |
 |------------------|-------------------------------------------------|
+| Media            | Optional.                                       |
 | Title            | Required.                                       |
 | Icon             | Optional, but recommended with errorCode.        |
 | errorCode        | Optional, but recommended when in errorState.        |
 | Body             | Required.        |
-| Separator        | Optional, but recommended when separating actions from content.        |
 | Footer           | Optional.        |
-| Action           | Required, if no footer; optional.        |
+| Actions          | Required, if no footer; optional.        |