`Layout::Grid` - documentation (HDS-4650) #2772

KristinLBradley · 2025-03-15T05:08:01Z

📌 Summary

If merged, this PR adds web documentation for the Grid component.

👉 Preview: https://hds-website-git-hds-4650-grid-documentation-hashicorp.vercel.app/layouts/grid

Component implementation PR: #2756

🔗 External links

Jira ticket: HDS-4650
Related PR for Layout::Flex: Layout::Flex - Component implementation #2751
Project plan: HDS Project Plan - Flex/Grid components

👀 Component checklist

Percy was checked for any visual regression
~~[ ] A changelog entry was added via Changesets if needed (see templates here)~~

💬 Please consider using conventional comments when reviewing this PR.

vercel · 2025-03-15T05:08:07Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
hds-showcase	✅ Ready (Inspect)	Visit Preview	Mar 18, 2025 10:54pm
hds-website	✅ Ready (Inspect)	Visit Preview	Mar 18, 2025 10:54pm

website/docs/layouts/grid/partials/code/how-to-use.md

didoo

@KristinLBradley left a few minor comments, nothing major that I can see

website/docs/layouts/grid/partials/code/how-to-use.md

website/docs/layouts/grid/partials/code/component-api.md

website/docs/layouts/grid/index.md

Co-authored-by: Lee White <lee.white@hashicorp.com>

website/docs/layouts/grid/partials/code/how-to-use.md

dchyun · 2025-03-18T20:03:09Z

website/docs/layouts/grid/partials/code/how-to-use.md

+</Hds::Layout::Grid>
+```
+
+### colspan & rowspan


[Suggestion] Adding some of the basic examples from the showcase for colspan and rowspan could help show how these arguments work in a simpler manner than the one example provided right now. The min-height example seems like a more nuanced use case.

I didn't want to make this section too long and to me these features seemed fairly straight forward to understand so I though one example could be sufficient. I could be wrong though. @didoo what do you think?

I agree with @KristinLBradley here, I think a single example with both rowspan/colspan is clear. What I maybe would do it to justify why there are three columns in the grid when in reality visually only two are needed

dchyun · 2025-03-18T20:05:12Z

website/docs/layouts/grid/partials/code/how-to-use.md

+
+**Important**
+
+The examples below are meant to show how one _could_ use the `Layout::Grid` component to implement certain common/standard UI patterns. They're **not** meant to be taken literally as they are and be used in production code. Also, some of these patterns are already implemented directly in HDS components that are ready to use.


[Question] Are there HDS components that implement the two patterns shown in the docs? If so, we should link to those components in the sections below where applicable.

This is just sort of disclaimer language that I followed from what @didoo had also included in the Flex component docs. I'll update it to say some of the patterns "may" already be implemented.

The only pattern that is similar is the RadioCard group, but it's implemented using flex, not grid.

website/docs/layouts/grid/partials/code/how-to-use.md

…eature to match Flex docs

… closely and fix heading levels

Co-authored-by: Dylan Hyun <dylan.hyun@hashicorp.com>

didoo

I did another pass an left a few comments/suggestions

didoo · 2025-03-19T10:52:13Z

website/app/styles/pages/layouts/grid.scss

+// COMPONENTS > GRID
+
+#show-content-layouts-grid {
+  .doc-grid-outline-children > * {


see comment below about the possibility of removing this outlining

didoo · 2025-03-19T11:00:11Z

website/docs/layouts/grid/partials/code/how-to-use.md

+  <Doc::Placeholder @height="40px" @text="Item 1" @background="#e4e4e4" />
+  <Doc::Placeholder @height="40px" @text="Item 2" @background="#e4e4e4" />
+  <Doc::Placeholder @height="40px" @text="Item 3" @background="#e4e4e4" />
+  <Doc::Placeholder @height="40px" @text="Item 4" @background="#e4e4e4" />


[suggestion] Since we are already declaring the background color inline in the snippet, what about using different colors to differentiate the items (with the benefit of making outlining them not necessary anymore? you may want to leave the outline only on the grid container, in case)

Suggested change

<Doc::Placeholder @height="40px" @text="Item 1" @background="#e4e4e4" />

<Doc::Placeholder @height="40px" @text="Item 2" @background="#e4e4e4" />

<Doc::Placeholder @height="40px" @text="Item 3" @background="#e4e4e4" />

<Doc::Placeholder @height="40px" @text="Item 4" @background="#e4e4e4" />

<Doc::Placeholder @height="40px" @text="Item 1" @background="#e4c5f3" />

<Doc::Placeholder @height="40px" @text="Item 2" @background="#e5ffd2" />

<Doc::Placeholder @height="40px" @text="Item 3" @background="#d2f4ff" />

<Doc::Placeholder @height="40px" @text="Item 4" @background="#fff8d2" />

same for the other examples

didoo · 2025-03-19T11:04:13Z

website/docs/layouts/grid/partials/code/how-to-use.md

+
+Every child of the **grid container** will be stretched to fit evenly within the underlying grid column tracks behaving as a **grid item** (for details on what this means, refer to the guide linked at the top of the page).
+
+In some cases, it may be necessary to wrap one or more content items within the optional `Layout::Grid::Item` component. i.e., to group content together within a column or row, prevent content from being stretched to fit the underlying grid column width, or to make use of `rowspan` and `colspan` options in order to create more complex layouts. (See below for more details and examples on these features.)


In the Flex documentation I've added a note about not using the item unless necessary, see if you want to port it over here too.

didoo · 2025-03-19T11:05:59Z

website/docs/layouts/grid/partials/code/how-to-use.md

+</Hds::Layout::Grid>
+```
+
+!!! Info


Ahh I see you've moved it here. Mmm, I think it's a bit lost here, no?

didoo · 2025-03-19T11:06:12Z

website/docs/layouts/grid/partials/code/how-to-use.md

+
+### Preventing content stretch
+
+```handlebars


[praise] Nice example! 🙌

(I copied it to Flex too 😀)

didoo · 2025-03-19T11:08:10Z

website/docs/layouts/grid/partials/version-history/version-history.md

+## 4.19.0
+
+TODO


Let's leave this to the automation

Suggested change

## 4.19.0

TODO

didoo · 2025-03-19T11:10:48Z

website/docs/layouts/grid/partials/code/how-to-use.md

+
+Use the `@align` argument to align grid items to the "start", "end", "center" or "stretch" them within the grid parent.
+
+Note: The `Grid` parent will need a height set for the affect to be visible.


Suggested change

Note: The `Grid` parent will need a height set for the affect to be visible.

Note: The `Grid` parent will need a height set for the effect to be visible.

didoo · 2025-03-19T11:11:54Z

website/docs/layouts/grid/partials/code/how-to-use.md

+  <Doc::Placeholder @height="1.2em" @text="Item 1" @background="#e4e4e4" />
+  <Doc::Placeholder @height="1.2em" @text="Item 2" @background="#e4e4e4" />
+  <Doc::Placeholder @height="1.2em" @text="Item 3" @background="#e4e4e4" />
+  <Doc::Placeholder @height="1.2sem" @text="Item 4" @background="#e4e4e4" />


Suggested change

<Doc::Placeholder @height="1.2sem" @text="Item 4" @background="#e4e4e4" />

<Doc::Placeholder @height="1.2em" @text="Item 4" @background="#e4e4e4" />

didoo · 2025-03-19T11:22:33Z

website/docs/layouts/grid/partials/code/how-to-use.md

+
+Note: The following example makes use of nested `Grid` and [Flex](/layouts/flex) components to achieve its layout. This may be overkill in actual practice but demonstrates the possibilities for achieving layouts with just these layout components alone.
+
+#### Basic 3 column layout


maybe?

Suggested change

#### Basic 3 column layout

#### Basic 3 columns layout

didoo · 2025-03-19T11:25:41Z

website/docs/layouts/grid/partials/code/how-to-use.md

+      <Hds::Layout::Grid @columnMinWidth="100%" @gap="16">
+        <div>
+          <Hds::Badge @text="In Preview" @type="outlined" @color="highlight" />
+          <Hds::Text::Display @tag="h2" @size="300" @weight="bold">Better together</Hds::Text::Display>
+        </div>


Suggested change

<Hds::Layout::Grid @columnMinWidth="100%" @gap="16">

<div>

<Hds::Badge @text="In Preview" @type="outlined" @color="highlight" />

<Hds::Text::Display @tag="h2" @size="300" @weight="bold">Better together</Hds::Text::Display>

</div>

<Hds::Layout::Grid @columnMinWidth="100%" @gap="16" as |LG|>

<LG.Item>

<Hds::Badge @text="In Preview" @type="outlined" @color="highlight" />

</LG.Item>

<Hds::Text::Display @tag="h2" @size="300" @weight="bold">Better together</Hds::Text::Display>

hashibot-hds added the docs-website Content updates to the documentation website label Mar 15, 2025

KristinLBradley mentioned this pull request Mar 15, 2025

Layout::Grid component implementation (HDS-4532) #2756

Open

2 tasks

KristinLBradley force-pushed the hds-4532-grid-component branch from 394d504 to 275a00a Compare March 17, 2025 16:10

KristinLBradley force-pushed the hds-4650-grid-documentation branch from 6352dea to da6b332 Compare March 17, 2025 16:11

vercel bot deployed to Preview – hds-showcase March 17, 2025 16:12 View deployment

vercel bot deployed to Preview – hds-website March 17, 2025 16:14 View deployment

vercel bot deployed to Preview – hds-showcase March 17, 2025 18:44 View deployment

vercel bot deployed to Preview – hds-website March 17, 2025 18:47 View deployment

vercel bot deployed to Preview – hds-showcase March 17, 2025 21:39 View deployment

KristinLBradley force-pushed the hds-4532-grid-component branch from 275a00a to 4c8cc80 Compare March 17, 2025 21:41

vercel bot deployed to Preview – hds-website March 17, 2025 21:41 View deployment

KristinLBradley force-pushed the hds-4650-grid-documentation branch from 6fceb6f to 88a1327 Compare March 17, 2025 21:41

vercel bot deployed to Preview – hds-showcase March 17, 2025 21:43 View deployment

vercel bot deployed to Preview – hds-website March 17, 2025 21:45 View deployment

KristinLBradley commented Mar 17, 2025

View reviewed changes

website/docs/layouts/grid/partials/code/how-to-use.md Outdated Show resolved Hide resolved

KristinLBradley commented Mar 17, 2025

View reviewed changes

website/docs/layouts/grid/partials/code/how-to-use.md Outdated Show resolved Hide resolved

vercel bot deployed to Preview – hds-showcase March 18, 2025 00:22 View deployment

vercel bot deployed to Preview – hds-website March 18, 2025 00:24 View deployment

KristinLBradley force-pushed the hds-4650-grid-documentation branch from 3b722e2 to 5d40954 Compare March 18, 2025 05:25

KristinLBradley changed the title ~~[WIP] Layout::Grid - documentation (HDS-4650)~~ Layout::Grid - documentation (HDS-4650) Mar 18, 2025

KristinLBradley marked this pull request as ready for review March 18, 2025 05:26

KristinLBradley requested review from a team as code owners March 18, 2025 05:26

KristinLBradley requested a review from didoo March 18, 2025 05:26

vercel bot deployed to Preview – hds-showcase March 18, 2025 05:27 View deployment

vercel bot deployed to Preview – hds-website March 18, 2025 05:29 View deployment

didoo reviewed Mar 18, 2025

View reviewed changes

KristinLBradley force-pushed the hds-4532-grid-component branch from 0586955 to 7f5c4b8 Compare March 18, 2025 16:15

KristinLBradley force-pushed the hds-4650-grid-documentation branch from 5d40954 to ac7b7d7 Compare March 18, 2025 16:16

KristinLBradley and others added 8 commits March 18, 2025 12:55

HDS-4650 Clean up TODOs in docs

db0e58b

HDS-4650 Delete TODO text

5b945f5

HDS-4650 Update colspan & rowspan docs to match component implementation

0dcffb0

HDS-4650 Update docs to mention stretched content issue & fix example

879e046

HDS-4650 Clean up old comment, update row & colspan example

5bfaf67

HDS-4650 Update rowspan colspan example code

33377fd

HDS-4650 Update example to combine rowspan and colspan on one Item

d50dc9d

Apply suggestions from code review

0f1d026

Co-authored-by: Lee White <lee.white@hashicorp.com>

KristinLBradley force-pushed the hds-4650-grid-documentation branch from c29456a to 0f1d026 Compare March 18, 2025 19:56

vercel bot deployed to Preview – hds-showcase March 18, 2025 19:57 View deployment

vercel bot deployed to Preview – hds-website March 18, 2025 20:00 View deployment

dchyun reviewed Mar 18, 2025

View reviewed changes

HDS-4650 Reduce size of simulated mobile layout, update docs on gap f…

c903f68

…eature to match Flex docs

vercel bot deployed to Preview – hds-showcase March 18, 2025 21:00 View deployment

vercel bot deployed to Preview – hds-website March 18, 2025 21:02 View deployment

HDS-4650 Refactor Grid::Item section of docs to follow Flex docs more…

2535906

… closely and fix heading levels

vercel bot deployed to Preview – hds-showcase March 18, 2025 22:32 View deployment

vercel bot deployed to Preview – hds-website March 18, 2025 22:34 View deployment

KristinLBradley and others added 2 commits March 18, 2025 15:36

HDS-4650 Tweaks to Grid docs

3b996d3

Apply suggestions from code review

71b3258

Co-authored-by: Dylan Hyun <dylan.hyun@hashicorp.com>

vercel bot deployed to Preview – hds-showcase March 18, 2025 22:39 View deployment

vercel bot deployed to Preview – hds-website March 18, 2025 22:43 View deployment

HDS-4650 Remove unneeded words from list of words for linter

e480149

vercel bot deployed to Preview – hds-showcase March 18, 2025 22:45 View deployment

vercel bot deployed to Preview – hds-website March 18, 2025 22:47 View deployment

HDS-4650 Update wording

c296be6

vercel bot deployed to Preview – hds-showcase March 18, 2025 22:52 View deployment

vercel bot deployed to Preview – hds-website March 18, 2025 22:54 View deployment

didoo mentioned this pull request Mar 19, 2025

Update the @tag entry in the Component API documentation for the Text component #2778

Open

didoo reviewed Mar 19, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`Layout::Grid` - documentation (HDS-4650) #2772

`Layout::Grid` - documentation (HDS-4650) #2772

KristinLBradley commented Mar 15, 2025 •

edited by didoo

Loading

vercel bot commented Mar 15, 2025 •

edited

Loading

didoo left a comment

dchyun Mar 18, 2025

KristinLBradley Mar 18, 2025

didoo Mar 19, 2025

dchyun Mar 18, 2025

KristinLBradley Mar 18, 2025

didoo Mar 19, 2025

didoo left a comment

didoo Mar 19, 2025

didoo Mar 19, 2025

didoo Mar 19, 2025

didoo Mar 19, 2025

didoo Mar 19, 2025

didoo Mar 19, 2025

didoo Mar 19, 2025

didoo Mar 19, 2025

didoo Mar 19, 2025

didoo Mar 19, 2025

didoo Mar 19, 2025


		Important

		The examples below are meant to show how one _could_ use the `Layout::Grid` component to implement certain common/standard UI patterns. They're not meant to be taken literally as they are and be used in production code. Also, some of these patterns are already implemented directly in HDS components that are ready to use.


		Every child of the grid container will be stretched to fit evenly within the underlying grid column tracks behaving as a grid item (for details on what this means, refer to the guide linked at the top of the page).

		In some cases, it may be necessary to wrap one or more content items within the optional `Layout::Grid::Item` component. i.e., to group content together within a column or row, prevent content from being stretched to fit the underlying grid column width, or to make use of `rowspan` and `colspan` options in order to create more complex layouts. (See below for more details and examples on these features.)


		Use the `@align` argument to align grid items to the "start", "end", "center" or "stretch" them within the grid parent.

		Note: The `Grid` parent will need a height set for the affect to be visible.

	<Doc::Placeholder @height="1.2sem" @text="Item 4" @background="#e4e4e4" />
	<Doc::Placeholder @height="1.2em" @text="Item 4" @background="#e4e4e4" />


		Note: The following example makes use of nested `Grid` and [Flex](/layouts/flex) components to achieve its layout. This may be overkill in actual practice but demonstrates the possibilities for achieving layouts with just these layout components alone.

		#### Basic 3 column layout

Layout::Grid - documentation (HDS-4650) #2772

Are you sure you want to change the base?

Layout::Grid - documentation (HDS-4650) #2772

Conversation

KristinLBradley commented Mar 15, 2025 • edited by didoo Loading

📌 Summary

🔗 External links

👀 Component checklist

vercel bot commented Mar 15, 2025 • edited Loading

didoo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

didoo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

`Layout::Grid` - documentation (HDS-4650) #2772

`Layout::Grid` - documentation (HDS-4650) #2772

KristinLBradley commented Mar 15, 2025 •

edited by didoo

Loading

vercel bot commented Mar 15, 2025 •

edited

Loading