/** * @license * Copyright 2024 Aglyn LLC * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ import { type GridProps } from '@mui/material'; export interface GridItemsProps extends GridProps, ReplaceKey { items: GridProps[]; /** * Lay the items out as MASONRY instead of rigid rows. * * ## The bug this exists to kill * * A `` of cards is a twelve-column flex row that wraps, and every * item in a wrapped row is as tall as the tallest one in it. Two consequences, * both reported from real pages: * * 1. **Holes.** Billing puts `Current plan` (4) beside `Usage` (8). `Usage` is * more than twice as tall, so the row is `Usage`-tall and the area under * `Current plan` is dead — while `Metered usage estimate` (4), the card * shaped to fill it, is pushed onto its own row far below with eight * columns of nothing beside it. * 2. **The stranded sidebar.** The marketplace listing detail is `body` (8), * `changelog` (8), `sidebar` (4). Two eights cannot share a row, so the * changelog wraps — and the sidebar, which follows it in source order, * wraps WITH it. `Install`, the point of the page, starts a screen below * the top of the content with blank space above it. * * ## What it does instead * * Items are bucketed into COLUMNS by their `size`, and each column stacks its * own cards at their natural heights. `Current plan` and `Metered usage * estimate` are both 4-wide, so they become one 4-wide column beside the * 8-wide `Usage` column; `body` and `changelog` become one 8-wide column * beside the 4-wide sidebar. A full-width item (span 12) interrupts the * bucketing and takes a band of its own, so source order is preserved across * it — without that, billing's five full-width cards would collect at the * bottom in one column and reorder the page. * * ## Why bucketing rather than measured row spans * * The obvious implementation is a fine-grained row grid where each card's * MEASURED height becomes a `grid-row: span n`, packed `dense`. It was built * that way first and it is a trap: `n` is only correct until the card's * content changes size, and a card whose `n` is too small does not merely * leave a gap — the next card is placed UNDERNEATH IT. Overlapping cards are * a far worse defect than the holes this mode exists to close, and they * appear exactly when measurement is least reliable (data still arriving, * images still decoding). Keeping the whole thing in CSS means there is no * measurement to go stale: heights are whatever the browser computes, every * frame, and cards cannot overlap because nothing ever claims a height on * their behalf. * * It also costs nothing at hydration. A measured layout renders wrong on the * server and corrects on mount; this renders identically in both. * * ## The one behaviour change * * At a breakpoint where every item is full width (`xs: 12`, the phone case) * the columns stack, so cards are read column by column rather than in the * authored order — on billing, `Current plan` then `Metered usage estimate` * then `Usage`. Cards that share a column are the ones that share a width, * which in practice is what makes them belong together. */ masonry?: boolean; } /** * Marks an element as a frame around content that others draw, such as the * console's widget zone stacking the cards plugins render (AGL-3050). * * `GridItems masonry` and `CardColumns` hide an item that rendered nothing. * An item holding only a frame whose contents all drew nothing is the same * absent card one level down, and the item is not `:empty` while the frame is * in it, so both hide that item too. The mark is what tells a frame apart * from an element that draws something with no children of its own: an item * whose one element is an image, a divider or a loading skeleton is never * mistaken for an absent card. */ export declare const ABSENT_WHEN_EMPTY_ATTRIBUTE = "data-absent-when-empty"; /** The mark, as props to spread onto the frame: ``. */ export declare const ABSENT_WHEN_EMPTY: { readonly "data-absent-when-empty": ""; }; /** * A marked frame that is its parent's only element and drew nothing. * * Attribute last: the selector engine jsdom ships misreads an attribute * selector that opens a compound inside `:has()`, and throws. */ export declare const EMPTY_FRAME_SELECTOR = ":only-child:empty[data-absent-when-empty]"; export declare const GridItems: import("react").ForwardRefExoticComponent & import("react").RefAttributes>; export default GridItems;