Skip to content

[FEATURE] UI Customization. Add Grid Component - #394

Merged
jgbernalp merged 17 commits into
ui-customizationfrom
zhuje/ou1609-ui-customization-grid-component
Nov 2, 2026
Merged

[FEATURE] UI Customization. Add Grid Component#394
jgbernalp merged 17 commits into
ui-customizationfrom
zhuje/ou1609-ui-customization-grid-component

Conversation

@zhuje

@zhuje zhuje commented Oct 26, 2026

Copy link
Copy Markdown
Contributor

Description

Adds Grid and GridItem to @perses-dev/components/next, the replacement for MUI's Grid/Grid item in the
UI customization effort (OU-1609, part of OU-1334 Phase 1).

API

  • Grid — a CSS-grid container. columns sets the number of equal-width columns (default 12); spacing is a
    responsive spacing token written to gap. Also accepts the shared spacing, sizing and overflow style props.
  • GridItem — a cell. size is a responsive number of columns to span (grid-column: span n); omitted, the
    item takes one column. Also accepts spacing, sizing and overflow.
  • Both forward refs, land className/style on a single div, and are registered in PersesComponents
    so apps can swap them via the provider.

Screenshots

Screenshot 2026-10-25 at 9 34 33 PM Screenshot 2026-10-25 at 9 34 43 PM Screenshot 2026-10-25 at 9 34 47 PM Screenshot 2026-10-25 at 9 34 54 PM

Checklist

  • Pull request has a descriptive title and context useful to a reviewer.
  • Pull request title follows the [<catalog_entry>] <commit message> naming convention using one of the
    following catalog_entry values: FEATURE, ENHANCEMENT, BUGFIX, BREAKINGCHANGE, DOC,IGNORE.
  • All commits have DCO signoffs.

UI Changes

  • Changes that impact the UI include screenshots and/or screencasts of the relevant changes.
  • Code follows the UI guidelines.
  • E2E tests are stable and unlikely to be flaky.
    See e2e docs for more details. Common issues include:
    • Is the data inconsistent? You need to mock API requests.
    • Does the time change? You need to use consistent time values or mock time utilities.
    • Does it have loading states? You need to wait for loading to complete.

@zhuje
zhuje requested a review from a team as a code owner October 26, 2026 01:40
@github-actions

github-actions Bot commented Oct 26, 2026 •
edited
Loading

Copy link
Copy Markdown

React Doctor found no new issues. 🎉

Reviewed by React Doctor for commit 7f2ed73.

@zhuje
zhuje force-pushed the zhuje/ou1609-ui-customization-grid-component branch 2 times, most recently from 3cef0d3 to 00b7139 Compare October 28, 2026 02:00
zhuje added 12 commits October 28, 2026 16:58
@zhuje
[FEATURE] UI Customization. Add Grid component
21688d1 
Add `Grid` and `GridItem` to `@perses-dev/components` `next` primitives as
the replacement for MUI `Grid`/`Grid2`:

- `Grid`: CSS grid container, `columns` (default 12, written to
  `--ps-grid-columns`) and `spacing` forwarded to the `gap` style prop.
- `GridItem`: `size?: Responsive<number>` → `grid-column: span n` via a
  new `gridColumn` registry entry in `system/grid.ts` and `.ps-grid-column`
  rules in `system/layout.css`.
- Both take spacing/sizing/overflow style props, forward refs and spread
  unregistered props to the `div`.
- Registered in `PersesComponents`, `defaultComponents` and the primitives
  barrel; Ladle stories (Basic, Columns, Nested, Form layout).

Audited against every MUI Grid call site in perses/shared, perses/plugins,
perses/perses and openshift/monitoring-plugin; spacing is a `gap`, so the
`!important` padding hacks and fractional spans are migrated by call-site
changes rather than ported into the primitive.

Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[BUGFIX] make Grid custom properties non-inheriting
e55fcaa 
Nested grids and partially responsive nested items inherited the ancestor's
--ps-grid-columns / --ps-grid-column* values. Declare them with @Property
inherits: false so unset values fall through to the stylesheet fallbacks.

Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[ENHANCEMENT] reset Grid custom properties without @Property
6c42809 
Replace the @Property declarations (unsupported in Firefox < 128) with
`--ps-grid-columns: initial` / `--ps-grid-column*: initial` resets on
:where(.ps-Grid) / :where(.ps-GridItem). `initial` is the guaranteed-invalid
value, so unset variables fall through to the stylesheet fallbacks in every
browser; inline values from styleProps.ts still win.

Also narrow GridStyle['--ps-grid-columns'] to number and document the valid
GridItem size range.

Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[ENHANCEMENT] address Grid review findings
6d3649a 
- Drop the box-sizing declaration that duplicates the perses.reset layer.
- Use the named clsx export and scope-justify the CSS side-effect imports
  so Grid adds no Oxlint warnings (Card pattern).
- Move story presentation styles to .ladle/stories.css (.story-grid-*).
- Replace an unfalsifiable paddingTop assertion with a check that the
  item carries no padding utility class.

Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[BUGFIX] set box-sizing on Grid and import the layer prelude
0bcbbc6 
Declare `box-sizing: border-box` on `.ps-Grid` and `.ps-GridItem`,
matching Box, Stack, Checkbox, Switch and Table, and flip the test to
assert it is present.

The design-tokens reset (`@layer perses.reset`) does set border-box on
every element, but `@perses-dev/components/next/css` deliberately does
not import that reset. A consumer who loads only the components CSS
therefore gets content-box, and `<Grid width="100%" px="md">` overflows
its container while the same props on Box and Stack do not.

Also add the `@perses-dev/design-tokens/css/layers` import prelude that
every primitive stylesheet must start with since #392 (layers.test.ts).

Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[ENHANCEMENT] inline Grid story styles and clarify Grid docs
edfedcb 
Move the Grid story scaffolding out of .ladle/stories.css into inline
CSSProperties constants in Grid.stories.tsx, matching the Box and Stack
stories. No other primitive ships story-only CSS, and a co-located
stylesheet under primitives/ would trip layers.test.ts.

Also reword the story, test, and JSDoc copy to spell out what the
breakpoint spans mean (e.g. "9 columns at md (900-1199px)") and drop
stale implementation comments.

Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[ENHANCEMENT] address Grid review findings (2026-10-25)
9fb8411 
- Remove the `GridStyle` type so `columns` is the only way to set the
  column count; `--ps-grid-columns` is engine plumbing, not public API.
  The caller-style test now overrides `gap` and asserts `columns` wins.
- Use design tokens (`--perses-border-width-sm`, `--perses-spacing-sm`)
  in the story presentation styles instead of raw `1px` / `0.5rem`.
- Drop the MUI comparison from the public `size` JSDoc.
- Use sentence case for the "Form layout" sample title.

Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[IGNORE] adapt Grid to mobile-first breakpoint classes from #398
aea931a 
Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[IGNORE] drop GridItem span resets made redundant by per-breakpoint c…
208d323 
…lasses

Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[IGNORE] describe Grid breakpoints with mobile-first ranges
cb48c8a 
Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[IGNORE] Clarify story component
b76f8c9 
Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[IGNORE] accept CSS custom properties on Grid style props
4c8e69d 
Type style as PersesCSSProperties on GridProps and GridItemProps so the
registry-derived check from #403 passes, and drop the as CSSProperties
cast that only existed to smuggle --ps-grid-columns past the old type.

Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
zhuje force-pushed the zhuje/ou1609-ui-customization-grid-component branch from 00b7139 to 4c8e69d Compare October 28, 2026 21:09
zhuje and others added 5 commits October 28, 2026 17:19
@zhuje
[IGNORE] add rounded style props to Grid and GridItem
63a5525 
Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[IGNORE] fix typecheck for react 19
c346283 
Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@zhuje
[IGNORE] fix react 19 ref types and lint
578edb1 
Signed-off-by: Jenny Zhu <jenny.a.zhu@gmail.com>
@jgbernalp
wip
61f3502 
Signed-off-by: Gabriel Bernal <gbernal@redhat.com>
@jgbernalp
[IGNORE] add row and column independent spacing
7f2ed73
@jgbernalp
jgbernalp force-pushed the zhuje/ou1609-ui-customization-grid-component branch from 193bb79 to 7f2ed73 Compare November 2, 2026 14:43
@jgbernalp
jgbernalp merged commit f9cdec9 into ui-customization Nov 2, 2026
15 checks passed
@jgbernalp
jgbernalp deleted the zhuje/ou1609-ui-customization-grid-component branch November 2, 2026 15:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@zhuje @jgbernalp