@aglyn/shared-ui-jsx 1.0.0-beta.143

package/src/lib/components/grid-items.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/components/grid-items.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2024 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Box, Grid, type GridProps } from '@mui/material'\nimport { forwardRef } from 'react'\n\n/* eslint-disable-next-line */\nexport interface GridItemsProps\n  extends GridProps,\n    ReplaceKey<JSX.OverrideableComponentProps, 'component', 'itemComponent'> {\n  items: GridProps[]\n  /**\n   * Lay the items out as MASONRY instead of rigid rows.\n   *\n   * ## The bug this exists to kill\n   *\n   * A `<GridItems>` of cards is a twelve-column flex row that wraps, and every\n   * item in a wrapped row is as tall as the tallest one in it. Two consequences,\n   * both reported from real pages:\n   *\n   * 1. **Holes.** Billing puts `Current plan` (4) beside `Usage` (8). `Usage` is\n   *    more than twice as tall, so the row is `Usage`-tall and the area under\n   *    `Current plan` is dead — while `Metered usage estimate` (4), the card\n   *    shaped to fill it, is pushed onto its own row far below with eight\n   *    columns of nothing beside it.\n   * 2. **The stranded sidebar.** The marketplace listing detail is `body` (8),\n   *    `changelog` (8), `sidebar` (4). Two eights cannot share a row, so the\n   *    changelog wraps — and the sidebar, which follows it in source order,\n   *    wraps WITH it. `Install`, the point of the page, starts a screen below\n   *    the top of the content with blank space above it.\n   *\n   * ## What it does instead\n   *\n   * Items are bucketed into COLUMNS by their `size`, and each column stacks its\n   * own cards at their natural heights. `Current plan` and `Metered usage\n   * estimate` are both 4-wide, so they become one 4-wide column beside the\n   * 8-wide `Usage` column; `body` and `changelog` become one 8-wide column\n   * beside the 4-wide sidebar. A full-width item (span 12) interrupts the\n   * bucketing and takes a band of its own, so source order is preserved across\n   * it — without that, billing's five full-width cards would collect at the\n   * bottom in one column and reorder the page.\n   *\n   * ## Why bucketing rather than measured row spans\n   *\n   * The obvious implementation is a fine-grained row grid where each card's\n   * MEASURED height becomes a `grid-row: span n`, packed `dense`. It was built\n   * that way first and it is a trap: `n` is only correct until the card's\n   * content changes size, and a card whose `n` is too small does not merely\n   * leave a gap — the next card is placed UNDERNEATH IT. Overlapping cards are\n   * a far worse defect than the holes this mode exists to close, and they\n   * appear exactly when measurement is least reliable (data still arriving,\n   * images still decoding). Keeping the whole thing in CSS means there is no\n   * measurement to go stale: heights are whatever the browser computes, every\n   * frame, and cards cannot overlap because nothing ever claims a height on\n   * their behalf.\n   *\n   * It also costs nothing at hydration. A measured layout renders wrong on the\n   * server and corrects on mount; this renders identically in both.\n   *\n   * ## The one behaviour change\n   *\n   * At a breakpoint where every item is full width (`xs: 12`, the phone case)\n   * the columns stack, so cards are read column by column rather than in the\n   * authored order — on billing, `Current plan` then `Metered usage estimate`\n   * then `Usage`. Cards that share a column are the ones that share a width,\n   * which in practice is what makes them belong together.\n   */\n  masonry?: boolean\n}\n\n/**\n * Cards of unequal height are the common case, and a row is as tall as its\n * tallest card, so the default leaves no hole for a short card to sit in.\n * Pass `masonry={false}` where the items really are a ROW — tiles, buttons, a\n * navigation column beside its content, a band of stat figures — and say so\n * where you pass it, because a row is now the deliberate choice.\n */\nconst MASONRY_BY_DEFAULT = true\n\n/** A per-breakpoint column count, normalized from MUI's `size`. */\ntype SpanProfile = Record<string, number>\n\n/** The breakpoint an item with no explicit `size` is sized at. */\nconst BASE_BREAKPOINT = 'xs'\nconst FULL_SPAN = 12\n\n/**\n * MUI Grid props that describe the flex-row layout masonry replaces, and so\n * must not reach the masonry container.\n */\nconst FLEX_ROW_PROPS = [\n  'container',\n  'spacing',\n  'rowSpacing',\n  'columnSpacing',\n  'columns',\n  'direction',\n  'wrap',\n  'size',\n  'offset',\n] as const\n\n/**\n * An item's `size` as a per-breakpoint column count.\n *\n * `'auto'`/`'grow'` have no column-count equivalent and become full width,\n * which is the safe reading: an item that wanted to size itself gets a band of\n * its own rather than being bucketed against a width it never declared.\n */\nfunction spanProfile(size: GridProps['size']): SpanProfile {\n  const one = (value: unknown) =>\n    typeof value === 'number' && value > 0 ? Math.min(FULL_SPAN, Math.round(value)) : FULL_SPAN\n  if (size == null) return { [BASE_BREAKPOINT]: FULL_SPAN }\n  if (typeof size === 'number' || typeof size === 'string')\n    return { [BASE_BREAKPOINT]: one(size) }\n  if (Array.isArray(size)) return { [BASE_BREAKPOINT]: one(size[0]) }\n  const entries = Object.entries(size).map(\n    ([breakpoint, value]) => [breakpoint, one(value)] as const,\n  )\n  return entries.length ? Object.fromEntries(entries) : { [BASE_BREAKPOINT]: FULL_SPAN }\n}\n\n/** The profile as a `grid-column` value `sx` can resolve per breakpoint. */\nconst gridColumnFor = (profile: SpanProfile) =>\n  Object.fromEntries(\n    Object.entries(profile).map(([breakpoint, span]) => [breakpoint, `span ${span}`]),\n  )\n\n/** MUI's breakpoint keys, narrowest first. */\nconst BREAKPOINT_ORDER = ['xs', 'sm', 'md', 'lg', 'xl'] as const\n\n/**\n * The column count at the WIDEST breakpoint the item declares — the width it is\n * bucketed by.\n *\n * Not `Math.max` over the profile, which was the first attempt and is wrong in\n * a way that silently disables the whole mode: essentially every item in this\n * codebase is written `{ xs: 12, md: 4 }`, so the maximum is 12 for all of them\n * and every card reads as full width. It has to be the value at the widest\n * declared breakpoint — 4 — because the multi-column arrangement only exists at\n * wide viewports in the first place.\n *\n * Read from the profile rather than from the current viewport on purpose:\n * measuring the breakpoint in JS would make the server and client renders\n * disagree. Bucketing is decided once; `sx` resolves the responsive\n * `grid-column` in CSS, so the narrow layout still collapses to a stack.\n */\nconst layoutSpan = (profile: SpanProfile) => {\n  const declared = BREAKPOINT_ORDER.filter((breakpoint) => profile[breakpoint] != null)\n  const widest = declared[declared.length - 1]\n  return widest ? profile[widest] : FULL_SPAN\n}\n\n/** `sx` (which may already be an array or a function) as a flat array. */\nconst sxArray = (sx: unknown): any[] => (sx == null ? [] : Array.isArray(sx) ? sx : [sx])\n\ninterface MasonryColumn {\n  key: string\n  profile: SpanProfile\n  entries: Array<{ item: GridProps; index: number }>\n}\n\n/**\n * A band of ONE width fans out; a band of mixed widths does not.\n *\n * Same-size items sharing a column is right when something else occupies the\n * rest of the row — billing's two 4-wide cards stacked beside its 8-wide\n * `Usage` is the case this mode was built for. It is wrong when the band is\n * ALL of that width: eight `md: 6` health probes then queue in one 6-wide\n * column with six columns of nothing beside them, which is a worse layout than\n * the rigid rows masonry replaced.\n *\n * So a single-width band spreads across the `12 / span` columns it was asking\n * for, round-robin, which keeps left-to-right reading order — item 0 top-left,\n * item 1 top-right — rather than the column-major order that filling one\n * column at a time would give.\n */\nfunction fanOut(band: MasonryColumn[]): MasonryColumn[] {\n  if (band.length !== 1) return band\n  const [column] = band\n  const span = layoutSpan(column.profile)\n  const columns = Math.floor(FULL_SPAN / span)\n  if (columns < 2 || column.entries.length < 2) return band\n  const spread: MasonryColumn[] = Array.from({ length: columns }, (_, i) => ({\n    key: `${column.key}#${i}`,\n    profile: column.profile,\n    // Typed, not inferred: an empty literal is `any[]` under the stricter\n    // library tsconfigs even though the annotation above it is not enough to\n    // narrow a property inside `Array.from`'s callback.\n    entries: [] as MasonryColumn['entries'],\n  }))\n  column.entries.forEach((entry, index) => {\n    spread[index % columns].entries.push(entry)\n  })\n  return spread.filter((candidate) => candidate.entries.length > 0)\n}\n\n/**\n * Marks an element as a frame around content that others draw, such as the\n * console's widget zone stacking the cards plugins render (AGL-3050).\n *\n * `GridItems masonry` and `CardColumns` hide an item that rendered nothing.\n * An item holding only a frame whose contents all drew nothing is the same\n * absent card one level down, and the item is not `:empty` while the frame is\n * in it, so both hide that item too. The mark is what tells a frame apart\n * from an element that draws something with no children of its own: an item\n * whose one element is an image, a divider or a loading skeleton is never\n * mistaken for an absent card.\n */\nexport const ABSENT_WHEN_EMPTY_ATTRIBUTE = 'data-absent-when-empty'\n\n/** The mark, as props to spread onto the frame: `<Stack {...ABSENT_WHEN_EMPTY}>`. */\nexport const ABSENT_WHEN_EMPTY = { [ABSENT_WHEN_EMPTY_ATTRIBUTE]: '' } as const\n\n/**\n * A marked frame that is its parent's only element and drew nothing.\n *\n * Attribute last: the selector engine jsdom ships misreads an attribute\n * selector that opens a compound inside `:has()`, and throws.\n */\nexport const EMPTY_FRAME_SELECTOR = `:only-child:empty[${ABSENT_WHEN_EMPTY_ATTRIBUTE}]`\n\n/**\n * A column with nothing to draw, hidden wherever it spans the whole row.\n *\n * Hiding its item is not enough. The column is a grid item of its own, so a\n * column whose item is hidden would stay behind as a zero-height grid row with\n * the grid's `gap` on both sides of it: a double gap between the cards around\n * an absent full-width band. A full-width item is always the only item in its\n * column, and it is absent in two shapes: it rendered nothing, or it holds\n * only a frame that drew nothing.\n *\n * Only at the widths where the column spans all twelve tracks. A narrower\n * column shares its row with the columns beside it, so an empty one adds no\n * row there, and hiding it would let auto-placement slide the next column into\n * its tracks.\n */\nfunction emptyColumnRules(profile: SpanProfile) {\n  const display = Object.fromEntries(\n    Object.entries(profile).map(([breakpoint, span]) => [\n      breakpoint,\n      span >= FULL_SPAN ? 'none' : 'flex',\n    ]),\n  )\n  return {\n    '&:has(> :only-child:empty)': { display },\n    [`&:has(> :only-child > ${EMPTY_FRAME_SELECTOR})`]: { display },\n  }\n}\n\n/**\n * Items → bands → columns.\n *\n * A band is a maximal run of items that are not full width; a full-width item\n * is a band on its own. Within a band, items that declare the same `size` share\n * a column, in source order — unless the band is entirely one width, which\n * {@link fanOut} spreads.\n */\nfunction buildBands(items: GridProps[]): MasonryColumn[][] {\n  const bands: MasonryColumn[][] = []\n  let current: MasonryColumn[] | null = null\n\n  items.forEach((item, index) => {\n    const profile = spanProfile(item.size)\n    const key = JSON.stringify(profile)\n    if (layoutSpan(profile) >= FULL_SPAN) {\n      bands.push([{ key, profile, entries: [{ item, index }] }])\n      current = null\n      return\n    }\n    if (!current) {\n      current = []\n      bands.push(current)\n    }\n    const column = current.find((candidate) => candidate.key === key)\n    if (column) column.entries.push({ item, index })\n    else current.push({ key, profile, entries: [{ item, index }] })\n  })\n\n  return bands.map(fanOut)\n}\n\nexport const GridItems = forwardRef<any, GridItemsProps>((props, ref) => {\n  const {\n    items = [],\n    itemComponent: ItemComponent = Grid,\n    masonry = MASONRY_BY_DEFAULT,\n    spacing = 0,\n    sx,\n    ...rest\n  } = props\n\n  if (!masonry) {\n    return (\n      <Grid ref={ref} container spacing={spacing} sx={sx as any} {...rest}>\n        {items.map(\n          ({ key: itemKey, id, ...item }: GridProps & { id?: unknown }, index: number) => (\n            <ItemComponent key={itemKey ?? id ?? index} {...item} />\n          ),\n        )}\n      </Grid>\n    )\n  }\n\n  const gap = spacing\n  const containerProps = Object.fromEntries(\n    Object.entries(rest).filter(([key]) => !FLEX_ROW_PROPS.includes(key as any)),\n  )\n\n  return (\n    <Box\n      ref={ref}\n      {...(containerProps as any)}\n      sx={[\n        {\n          display: 'grid',\n          // Twelve fractional tracks with a zero minimum. A `span` can never\n          // resolve wider than its share of the container, and `minmax(0, 1fr)`\n          // stops a wide child (a table, a long unbroken string) from pushing a\n          // track past the edge — which is what used to shove the listing\n          // page's sidebar out of the viewport.\n          gridTemplateColumns: `repeat(${FULL_SPAN}, minmax(0, 1fr))`,\n          // Columns are as tall as their own contents, never as tall as the\n          // tallest column beside them.\n          alignItems: 'start',\n          gap,\n        },\n        ...sxArray(sx),\n      ]}\n    >\n      {buildBands(items).map((band, bandIndex) =>\n        band.map((column) => (\n          <Box\n            key={`${bandIndex}:${column.key}`}\n            sx={{\n              gridColumn: gridColumnFor(column.profile),\n              display: 'flex',\n              flexDirection: 'column',\n              gap,\n              // Without this a flex column refuses to shrink below its content's\n              // intrinsic width and the grid track overflows with it.\n              minWidth: 0,\n              // An item whose children rendered NOTHING must not leave a gap.\n              // A plugin widget slot renders nothing when no plugin is\n              // entitled for it, and the wrapper it leaves behind is still a\n              // flex child — so the column's `gap` is applied on both sides of\n              // a zero-height box, drawing a hole exactly where the absent card\n              // was. `:empty` is exact: the wrapper has no element and no text\n              // node in that case and only in that case.\n              '& > *:empty': { display: 'none' },\n              // The same absent card one level down: the item's one element is\n              // a marked frame whose contents all drew nothing.\n              [`& > *:has(> ${EMPTY_FRAME_SELECTOR})`]: { display: 'none' },\n              ...emptyColumnRules(column.profile),\n            }}\n          >\n            {column.entries.map(({ item, index }) => {\n              const { key: itemKey, id, size, sx: itemSx, ...itemRest } = item as GridProps & {\n                id?: unknown\n              }\n              return (\n                <ItemComponent\n                  key={itemKey ?? id ?? index}\n                  {...itemRest}\n                  sx={[{ minWidth: 0 }, ...sxArray(itemSx)]}\n                />\n              )\n            })}\n          </Box>\n        )),\n      )}\n    </Box>\n  )\n})\n\nGridItems.displayName = 'GridItems'\nGridItems.aglyn = true\n\nexport default GridItems\n"],"names":["Box","Grid","forwardRef","MASONRY_BY_DEFAULT","BASE_BREAKPOINT","FULL_SPAN","FLEX_ROW_PROPS","spanProfile","size","one","value","Math","min","round","Array","isArray","entries","Object","map","breakpoint","length","fromEntries","gridColumnFor","profile","span","BREAKPOINT_ORDER","layoutSpan","declared","filter","widest","sxArray","sx","fanOut","band","column","columns","floor","spread","from","_","i","key","forEach","entry","index","push","candidate","ABSENT_WHEN_EMPTY_ATTRIBUTE","ABSENT_WHEN_EMPTY","EMPTY_FRAME_SELECTOR","emptyColumnRules","display","buildBands","items","bands","current","item","JSON","stringify","find","GridItems","props","ref","itemComponent","ItemComponent","masonry","spacing","rest","container","itemKey","id","gap","containerProps","includes","gridTemplateColumns","alignItems","bandIndex","gridColumn","flexDirection","minWidth","itemSx","itemRest","displayName","aglyn"],"mappings":"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"}

package/src/lib/components/grid-list.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2023 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 SxProps } from '@aglyn/shared-ui-theme';
+import { type GridProps as MuiGridProps } from '@mui/material';
+import { type VirtuosoGridHandle, type VirtuosoGridProps } from 'react-virtuoso';
+import { type ContainerProps } from './container';
+export type VirtualizedGridProps = VirtuosoGridProps<any> & {
+    sx?: SxProps;
+    as?: any;
+};
+export type GridListItemData<P = any> = {
+    id: MapKey;
+} & P;
+export interface GridListProps extends Partial<VirtualizedGridProps> {
+    items?: GridListItemData[];
+    renderItemContent?: (item: GridListProps['items'][number], index: number, items: GridListProps['items']) => JSX.Node;
+    GridContainerProps?: MuiGridProps;
+    GridItemProps?: MuiGridProps;
+    ListWrapperProps?: ContainerProps;
+    sx?: SxProps;
+}
+export declare const GridList: import("react").ForwardRefExoticComponent<GridListProps & import("react").RefAttributes<VirtuosoGridHandle>>;
+export default GridList;

package/src/lib/components/grid-list.js

@@ -0,0 +1,156 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * @license
+ * Copyright 2023 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 { generateComponentClassKeys, mergeSxProps, styled } from "@aglyn/shared-ui-theme";
+import { Box, Card, Grid } from "@mui/material";
+import clsx from "clsx";
+import { forwardRef, useCallback, useMemo } from "react";
+import { VirtuosoGrid } from "react-virtuoso";
+import Container from "./container.js";
+const classKey = generateComponentClassKeys('AglynGridList', [
+    'itemWrapper',
+    'itemContent',
+    'gridContainer',
+    'gridItem'
+]);
+const ItemWrapper = styled(/*#__PURE__*/ forwardRef((props, ref)=>{
+    const { children, className, sx } = props, rest = _object_without_properties_loose(props, [
+        "children",
+        "className",
+        "sx"
+    ]);
+    return /*#__PURE__*/ _jsx(Box, _extends({
+        ref: ref,
+        className: clsx(classKey.itemWrapper, className),
+        sx: mergeSxProps({
+            height: 0,
+            position: 'relative',
+            paddingTop: `${3 / 4 * 100}%`
+        }, sx)
+    }, rest, {
+        children: /*#__PURE__*/ _jsx(Card, {
+            className: classKey.itemContent,
+            sx: {
+                position: 'absolute',
+                left: 0,
+                top: 0,
+                width: '100%',
+                height: '100%',
+                display: 'flex',
+                textAlign: 'center',
+                flexDirection: 'column',
+                justifyContent: 'space-evenly'
+            },
+            children: children
+        })
+    }));
+}), {
+    name: 'AglynItemWrapper'
+})({});
+const VirtualizedGrid = styled(VirtuosoGrid, {
+    name: 'AglynVirtualizedGrid'
+})({});
+export const GridList = /*#__PURE__*/ forwardRef(function RefRenderFn(props, ref) {
+    const { items = [], renderItemContent = (item)=>item, ListWrapperProps = {}, GridContainerProps = {}, GridItemProps = {}, components } = props, rest = _object_without_properties_loose(props, [
+        "items",
+        "renderItemContent",
+        "ListWrapperProps",
+        "GridContainerProps",
+        "GridItemProps",
+        "components"
+    ]);
+    const computeItemKey = useCallback((index)=>{
+        var _ref, _ref1;
+        const item = items[index];
+        return (_ref = (_ref1 = item == null ? void 0 : item.key) != null ? _ref1 : item == null ? void 0 : item.id) != null ? _ref : items.indexOf(item);
+    }, [
+        items
+    ]);
+    const GridContainer = useMemo(()=>/*#__PURE__*/ forwardRef(function RefRenderFn(_0, _1) {
+            let _ref = [
+                _0,
+                _1
+            ], [_ref1, ..._rest] = _ref, { className } = _ref1, props = _object_without_properties_loose(_ref1, [
+                "className"
+            ]), [ref] = _rest;
+            const { className: gridClassName, children } = GridContainerProps, restGridProps = _object_without_properties_loose(GridContainerProps, [
+                "className",
+                "children"
+            ]);
+            return /*#__PURE__*/ _jsxs(Container, _extends({
+                gutterY: true
+            }, ListWrapperProps, {
+                children: [
+                    children,
+                    /*#__PURE__*/ _jsx(Grid, _extends({
+                        ref: ref,
+                        className: clsx(classKey.gridContainer, gridClassName, className),
+                        container: true
+                    }, restGridProps, props))
+                ]
+            }));
+        }), [
+        ListWrapperProps,
+        GridContainerProps
+    ]);
+    const GridItem = useMemo(()=>{
+        const Component = /*#__PURE__*/ forwardRef(function RefRenderFn(itemProps, ref) {
+            const { className: gridClassName } = GridItemProps, restGridProps = _object_without_properties_loose(GridItemProps, [
+                "className"
+            ]);
+            const { className } = itemProps, rest = _object_without_properties_loose(itemProps, [
+                "className"
+            ]);
+            // `rest` carries Virtuoso's per-item props INCLUDING `children`
+            // (the rendered item) — dropping it rendered every cell empty
+            // (AGL-459: blank icon picker).
+            return /*#__PURE__*/ _jsx(Grid, _extends({
+                ref: ref,
+                className: clsx(classKey.gridItem, gridClassName, className)
+            }, restGridProps, rest));
+        });
+        Component.displayName = 'GridListItem';
+        Component.aglyn = true;
+        return Component;
+    }, [
+        GridItemProps
+    ]);
+    const handleItemContent = useCallback((index)=>{
+        return /*#__PURE__*/ _jsx(ItemWrapper, {
+            children: renderItemContent(items[index], index, items)
+        });
+    }, [
+        items,
+        renderItemContent
+    ]);
+    return /*#__PURE__*/ _jsx(VirtualizedGrid, _extends({
+        ref: ref,
+        computeItemKey: computeItemKey,
+        itemContent: handleItemContent,
+        totalCount: items.length,
+        components: _extends({
+            Item: GridItem,
+            List: GridContainer
+        }, components)
+    }, rest));
+});
+GridList.displayName = 'GridList';
+GridList.aglyn = true;
+export default GridList;
+
+//# sourceMappingURL=grid-list.js.map

package/src/lib/components/grid-list.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/components/grid-list.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2023 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  generateComponentClassKeys,\n  mergeSxProps,\n  styled,\n  type SxProps,\n} from '@aglyn/shared-ui-theme'\nimport {\n  Box,\n  type BoxProps,\n  Card,\n  Grid,\n  type GridProps as MuiGridProps,\n} from '@mui/material'\nimport clsx from 'clsx'\nimport { forwardRef, useCallback, useMemo } from 'react'\nimport {\n  VirtuosoGrid,\n  type VirtuosoGridHandle,\n  type VirtuosoGridProps,\n} from 'react-virtuoso'\nimport Container, { type ContainerProps } from './container'\n\nconst classKey = generateComponentClassKeys('AglynGridList', [\n  'itemWrapper',\n  'itemContent',\n  'gridContainer',\n  'gridItem',\n])\n\nconst ItemWrapper = styled(\n  forwardRef<any, BoxProps>((props, ref) => {\n    const { children, className, sx, ...rest } = props\n    return (\n      <Box\n        ref={ref}\n        className={clsx(classKey.itemWrapper, className)}\n        sx={mergeSxProps(\n          {\n            height: 0,\n            position: 'relative',\n            paddingTop: `${(3 / 4) * 100}%`, // 4:3\n          },\n          sx,\n        )}\n        {...rest}\n      >\n        <Card\n          className={classKey.itemContent}\n          sx={{\n            position: 'absolute',\n            left: 0,\n            top: 0,\n            width: '100%',\n            height: '100%',\n            display: 'flex',\n            textAlign: 'center',\n            flexDirection: 'column',\n            justifyContent: 'space-evenly',\n          }}\n        >\n          {children}\n        </Card>\n      </Box>\n    )\n  }),\n  {\n    name: 'AglynItemWrapper',\n  },\n)({})\n\nexport type VirtualizedGridProps = VirtuosoGridProps<any> & {\n  sx?: SxProps\n  as?: any\n}\nconst VirtualizedGrid = styled(VirtuosoGrid, {\n  name: 'AglynVirtualizedGrid',\n})<VirtualizedGridProps>({})\n\nexport type GridListItemData<P = any> = { id: MapKey } & P\n\n/* eslint-disable-next-line */\nexport interface GridListProps extends Partial<VirtualizedGridProps> {\n  items?: GridListItemData[]\n  renderItemContent?: (\n    item: GridListProps['items'][number],\n    index: number,\n    items: GridListProps['items'],\n  ) => JSX.Node\n  GridContainerProps?: MuiGridProps\n  GridItemProps?: MuiGridProps\n  ListWrapperProps?: ContainerProps\n  sx?: SxProps\n}\n\nexport const GridList = forwardRef<VirtuosoGridHandle, GridListProps>(\n  function RefRenderFn(props, ref) {\n    const {\n      items = [],\n      renderItemContent = (item) => item,\n      ListWrapperProps = {},\n      GridContainerProps = {},\n      GridItemProps = {},\n      components,\n      ...rest\n    } = props\n\n    const computeItemKey = useCallback(\n      (index: number) => {\n        const item = items[index]\n        return item?.key ?? item?.id ?? items.indexOf(item)\n      },\n      [items],\n    )\n\n    const GridContainer = useMemo(\n      () =>\n        forwardRef<any, MuiGridProps>(function RefRenderFn(\n          { className, ...props },\n          ref,\n        ) {\n          const {\n            className: gridClassName,\n            children,\n            ...restGridProps\n          } = GridContainerProps\n          return (\n            <Container gutterY {...ListWrapperProps}>\n              {children}\n              <Grid\n                ref={ref}\n                className={clsx(\n                  classKey.gridContainer,\n                  gridClassName,\n                  className,\n                )}\n                container\n                {...restGridProps}\n                {...props}\n              />\n            </Container>\n          )\n        }),\n      [ListWrapperProps, GridContainerProps],\n    )\n\n    const GridItem = useMemo(() => {\n      const Component = forwardRef<any, MuiGridProps>(\n        function RefRenderFn(itemProps, ref) {\n          const { className: gridClassName, ...restGridProps } = GridItemProps\n          const { className, ...rest } = itemProps\n          // `rest` carries Virtuoso's per-item props INCLUDING `children`\n          // (the rendered item) — dropping it rendered every cell empty\n          // (AGL-459: blank icon picker).\n          return (\n            <Grid\n              ref={ref}\n              className={clsx(classKey.gridItem, gridClassName, className)}\n              {...restGridProps}\n              {...rest}\n            />\n          )\n        },\n      )\n      Component.displayName = 'GridListItem'\n      Component.aglyn = true\n      return Component\n    }, [GridItemProps])\n\n    const handleItemContent = useCallback(\n      (index: number) => {\n        return (\n          <ItemWrapper>\n            {renderItemContent(items[index], index, items)}\n          </ItemWrapper>\n        )\n      },\n      [items, renderItemContent],\n    )\n\n    return (\n      <VirtualizedGrid\n        ref={ref}\n        computeItemKey={computeItemKey}\n        itemContent={handleItemContent}\n        totalCount={items.length}\n        components={{\n          Item: GridItem,\n          List: GridContainer,\n          ...components,\n        }}\n        {...rest}\n      />\n    )\n  },\n)\n\nGridList.displayName = 'GridList'\nGridList.aglyn = true\n\nexport default GridList\n"],"names":["generateComponentClassKeys","mergeSxProps","styled","Box","Card","Grid","clsx","forwardRef","useCallback","useMemo","VirtuosoGrid","Container","classKey","ItemWrapper","props","ref","children","className","sx","rest","itemWrapper","height","position","paddingTop","itemContent","left","top","width","display","textAlign","flexDirection","justifyContent","name","VirtualizedGrid","GridList","RefRenderFn","items","renderItemContent","item","ListWrapperProps","GridContainerProps","GridItemProps","components","computeItemKey","index","key","id","indexOf","GridContainer","gridClassName","restGridProps","gutterY","gridContainer","container","GridItem","Component","itemProps","gridItem","displayName","aglyn","handleItemContent","totalCount","length","Item","List"],"mappings":"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"}

package/src/lib/components/help-tip.component.d.ts

@@ -0,0 +1,30 @@
+import { type SxProps } from '@mui/material';
+import type { MouseEventHandler, ReactNode } from 'react';
+/** Content shape accepted anywhere a help affordance can attach (AGL-600/601). */
+export interface HelpTipContent {
+    /** One- or two-sentence plain-language explanation shown in the tooltip. */
+    excerpt: ReactNode;
+    /** Optional bold first line, usually the matching docs page/section title. */
+    title?: ReactNode;
+    /** Optional documentation deep link; opens in a new tab. */
+    href?: string;
+}
+export interface HelpTipProps extends HelpTipContent {
+    /** Accessible name for the affordance; defaults from the title. */
+    ariaLabel?: string;
+    sx?: SxProps;
+    /** Forwarded to the icon button — e.g. to stop propagation when the tip
+     * sits inside a clickable parent like an accordion summary. */
+    onClick?: MouseEventHandler<HTMLElement>;
+}
+/**
+ * Unobtrusive question-mark help affordance: hover for a brief explanation,
+ * click (when `href` is set) to open the documentation page in a new tab.
+ * The shared primitive behind the console's docs help system (AGL-599..601).
+ */
+export declare function HelpTip(props: HelpTipProps): import("react").JSX.Element;
+export declare namespace HelpTip {
+    var displayName: string;
+    var aglyn: boolean;
+}
+export default HelpTip;

package/src/lib/components/help-tip.component.js

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright 2026 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.
+ */ 'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { mdiHelpCircleOutline, mdiOpenInNew } from "@aglyn/shared-data-mdi";
+import { mergeSxProps } from "@aglyn/shared-ui-theme";
+import { IconButton, Link, Stack, Tooltip, Typography } from "@mui/material";
+import { useCallback, useRef } from "react";
+import { MdiIcon } from "./mdi-icon/mdi-icon.js";
+/**
+ * Unobtrusive question-mark help affordance: hover for a brief explanation,
+ * click (when `href` is set) to open the documentation page in a new tab.
+ * The shared primitive behind the console's docs help system (AGL-599..601).
+ */ export function HelpTip(props) {
+    const { excerpt, title, href, ariaLabel, sx, onClick } = props;
+    const label = ariaLabel != null ? ariaLabel : typeof title === 'string' ? `Help: ${title}` : 'Help';
+    // Popper places the tooltip when it opens, and recomputes only on scroll, on
+    // a window resize, or when the popper component itself re-renders. The
+    // content can still grow after that — a console excerpt is a chunk fetched
+    // on first open (AGL-2706) — and a tip placed at its title-only width then
+    // widens from where it was put, off the screen at the right edge (AGL-2855).
+    // So the open content reports its own size changes to the popper.
+    const popper = useRef(null);
+    const setPopper = useCallback((instance)=>{
+        popper.current = instance;
+    }, []);
+    const contentObserver = useRef(null);
+    const observeContent = useCallback((node)=>{
+        var _contentObserver_current;
+        (_contentObserver_current = contentObserver.current) == null ? void 0 : _contentObserver_current.disconnect();
+        contentObserver.current = null;
+        // No ResizeObserver means no layout to follow (jsdom).
+        if (!node || typeof ResizeObserver === 'undefined') return;
+        contentObserver.current = new ResizeObserver(()=>{
+            var _popper_current;
+            void ((_popper_current = popper.current) == null ? void 0 : _popper_current.update());
+        });
+        contentObserver.current.observe(node);
+    }, []);
+    const content = /*#__PURE__*/ _jsxs(Stack, {
+        ref: observeContent,
+        spacing: 0.5,
+        sx: {
+            p: 0.5,
+            maxWidth: 280
+        },
+        children: [
+            title ? /*#__PURE__*/ _jsx(Typography, {
+                variant: "subtitle2",
+                component: "span",
+                children: title
+            }) : null,
+            /*#__PURE__*/ _jsx(Typography, {
+                variant: "caption",
+                component: "span",
+                children: excerpt
+            }),
+            href ? /*#__PURE__*/ _jsxs(Link, {
+                href: href,
+                target: "_blank",
+                rel: "noopener noreferrer",
+                variant: "caption",
+                sx: {
+                    display: 'inline-flex',
+                    alignItems: 'center',
+                    gap: 0.5,
+                    color: 'inherit',
+                    fontWeight: 600
+                },
+                children: [
+                    "Open documentation",
+                    /*#__PURE__*/ _jsx(MdiIcon, {
+                        path: mdiOpenInNew.path,
+                        sx: {
+                            fontSize: '1em'
+                        }
+                    })
+                ]
+            }) : null
+        ]
+    });
+    const iconSx = mergeSxProps({
+        color: 'text.disabled',
+        ':hover': {
+            color: 'text.secondary'
+        }
+    }, sx);
+    return /*#__PURE__*/ _jsx(Tooltip, {
+        arrow: true,
+        enterDelay: 150,
+        title: content,
+        slotProps: {
+            popper: {
+                popperRef: setPopper
+            }
+        },
+        children: href ? /*#__PURE__*/ _jsx(IconButton, {
+            component: "a",
+            href: href,
+            target: "_blank",
+            rel: "noopener noreferrer",
+            size: "small",
+            "aria-label": `${label} — open documentation in a new tab`,
+            sx: iconSx,
+            onClick: onClick,
+            children: /*#__PURE__*/ _jsx(MdiIcon, {
+                path: mdiHelpCircleOutline.path,
+                fontSize: "inherit"
+            })
+        }) : /*#__PURE__*/ _jsx(IconButton, {
+            size: "small",
+            "aria-label": label,
+            sx: iconSx,
+            onClick: onClick,
+            children: /*#__PURE__*/ _jsx(MdiIcon, {
+                path: mdiHelpCircleOutline.path,
+                fontSize: "inherit"
+            })
+        })
+    });
+}
+HelpTip.displayName = 'HelpTip';
+HelpTip.aglyn = true;
+export default HelpTip;
+
+//# sourceMappingURL=help-tip.component.js.map

package/src/lib/components/help-tip.component.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/components/help-tip.component.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n'use client'\n\nimport { mdiHelpCircleOutline, mdiOpenInNew } from '@aglyn/shared-data-mdi'\nimport { mergeSxProps } from '@aglyn/shared-ui-theme'\nimport {\n  IconButton,\n  Link,\n  Stack,\n  type SxProps,\n  Tooltip,\n  Typography,\n} from '@mui/material'\nimport { useCallback, useRef } from 'react'\nimport type { MouseEventHandler, ReactNode } from 'react'\nimport { MdiIcon } from './mdi-icon/mdi-icon'\n\n/** The one part of a Popper.js instance a help tip calls. */\ninterface PlacedPopper {\n  update(): unknown\n}\n\n/** Content shape accepted anywhere a help affordance can attach (AGL-600/601). */\nexport interface HelpTipContent {\n  /** One- or two-sentence plain-language explanation shown in the tooltip. */\n  excerpt: ReactNode\n  /** Optional bold first line, usually the matching docs page/section title. */\n  title?: ReactNode\n  /** Optional documentation deep link; opens in a new tab. */\n  href?: string\n}\n\nexport interface HelpTipProps extends HelpTipContent {\n  /** Accessible name for the affordance; defaults from the title. */\n  ariaLabel?: string\n  sx?: SxProps\n  /** Forwarded to the icon button — e.g. to stop propagation when the tip\n   * sits inside a clickable parent like an accordion summary. */\n  onClick?: MouseEventHandler<HTMLElement>\n}\n\n/**\n * Unobtrusive question-mark help affordance: hover for a brief explanation,\n * click (when `href` is set) to open the documentation page in a new tab.\n * The shared primitive behind the console's docs help system (AGL-599..601).\n */\nexport function HelpTip(props: HelpTipProps) {\n  const { excerpt, title, href, ariaLabel, sx, onClick } = props\n\n  const label =\n    ariaLabel ??\n    (typeof title === 'string' ? `Help: ${title}` : 'Help')\n\n  // Popper places the tooltip when it opens, and recomputes only on scroll, on\n  // a window resize, or when the popper component itself re-renders. The\n  // content can still grow after that — a console excerpt is a chunk fetched\n  // on first open (AGL-2706) — and a tip placed at its title-only width then\n  // widens from where it was put, off the screen at the right edge (AGL-2855).\n  // So the open content reports its own size changes to the popper.\n  const popper = useRef<PlacedPopper | null>(null)\n  const setPopper = useCallback((instance: PlacedPopper | null) => {\n    popper.current = instance\n  }, [])\n  const contentObserver = useRef<ResizeObserver | null>(null)\n  const observeContent = useCallback((node: HTMLDivElement | null) => {\n    contentObserver.current?.disconnect()\n    contentObserver.current = null\n    // No ResizeObserver means no layout to follow (jsdom).\n    if (!node || typeof ResizeObserver === 'undefined') return\n    contentObserver.current = new ResizeObserver(() => {\n      void popper.current?.update()\n    })\n    contentObserver.current.observe(node)\n  }, [])\n\n  const content = (\n    <Stack ref={observeContent} spacing={0.5} sx={{ p: 0.5, maxWidth: 280 }}>\n      {title ? (\n        <Typography variant=\"subtitle2\" component=\"span\">\n          {title}\n        </Typography>\n      ) : null}\n      <Typography variant=\"caption\" component=\"span\">\n        {excerpt}\n      </Typography>\n      {href ? (\n        <Link\n          href={href}\n          target=\"_blank\"\n          rel=\"noopener noreferrer\"\n          variant=\"caption\"\n          sx={{\n            display: 'inline-flex',\n            alignItems: 'center',\n            gap: 0.5,\n            color: 'inherit',\n            fontWeight: 600,\n          }}\n        >\n          Open documentation\n          <MdiIcon path={mdiOpenInNew.path} sx={{ fontSize: '1em' }} />\n        </Link>\n      ) : null}\n    </Stack>\n  )\n\n  const iconSx = mergeSxProps(\n    {\n      color: 'text.disabled',\n      ':hover': { color: 'text.secondary' },\n    },\n    sx,\n  )\n\n  return (\n    <Tooltip\n      arrow\n      enterDelay={150}\n      title={content}\n      slotProps={{ popper: { popperRef: setPopper } }}\n    >\n      {href ? (\n        <IconButton\n          component=\"a\"\n          href={href}\n          target=\"_blank\"\n          rel=\"noopener noreferrer\"\n          size=\"small\"\n          aria-label={`${label} — open documentation in a new tab`}\n          sx={iconSx}\n          onClick={onClick}\n        >\n          <MdiIcon path={mdiHelpCircleOutline.path} fontSize=\"inherit\" />\n        </IconButton>\n      ) : (\n        <IconButton\n          size=\"small\"\n          aria-label={label}\n          sx={iconSx}\n          onClick={onClick}\n        >\n          <MdiIcon path={mdiHelpCircleOutline.path} fontSize=\"inherit\" />\n        </IconButton>\n      )}\n    </Tooltip>\n  )\n}\nHelpTip.displayName = 'HelpTip'\nHelpTip.aglyn = true\n\nexport default HelpTip\n"],"names":["mdiHelpCircleOutline","mdiOpenInNew","mergeSxProps","IconButton","Link","Stack","Tooltip","Typography","useCallback","useRef","MdiIcon","HelpTip","props","excerpt","title","href","ariaLabel","sx","onClick","label","popper","setPopper","instance","current","contentObserver","observeContent","node","disconnect","ResizeObserver","update","observe","content","ref","spacing","p","maxWidth","variant","component","target","rel","display","alignItems","gap","color","fontWeight","path","fontSize","iconSx","arrow","enterDelay","slotProps","popperRef","size","aria-label","displayName","aglyn"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;;AAEA,SAASA,oBAAoB,EAAEC,YAAY,QAAQ,yBAAwB;AAC3E,SAASC,YAAY,QAAQ,yBAAwB;AACrD,SACEC,UAAU,EACVC,IAAI,EACJC,KAAK,EAELC,OAAO,EACPC,UAAU,QACL,gBAAe;AACtB,SAASC,WAAW,EAAEC,MAAM,QAAQ,QAAO;AAE3C,SAASC,OAAO,QAAQ,yBAAqB;AA0B7C;;;;CAIC,GACD,OAAO,SAASC,QAAQC,KAAmB;IACzC,MAAM,EAAEC,OAAO,EAAEC,KAAK,EAAEC,IAAI,EAAEC,SAAS,EAAEC,EAAE,EAAEC,OAAO,EAAE,GAAGN;IAEzD,MAAMO,QACJH,oBAAAA,YACC,OAAOF,UAAU,WAAW,CAAC,MAAM,EAAEA,OAAO,GAAG;IAElD,6EAA6E;IAC7E,uEAAuE;IACvE,2EAA2E;IAC3E,2EAA2E;IAC3E,6EAA6E;IAC7E,kEAAkE;IAClE,MAAMM,SAASX,OAA4B;IAC3C,MAAMY,YAAYb,YAAY,CAACc;QAC7BF,OAAOG,OAAO,GAAGD;IACnB,GAAG,EAAE;IACL,MAAME,kBAAkBf,OAA8B;IACtD,MAAMgB,iBAAiBjB,YAAY,CAACkB;YAClCF;SAAAA,2BAAAA,gBAAgBD,OAAO,qBAAvBC,yBAAyBG,UAAU;QACnCH,gBAAgBD,OAAO,GAAG;QAC1B,uDAAuD;QACvD,IAAI,CAACG,QAAQ,OAAOE,mBAAmB,aAAa;QACpDJ,gBAAgBD,OAAO,GAAG,IAAIK,eAAe;gBACtCR;YAAL,OAAKA,kBAAAA,OAAOG,OAAO,qBAAdH,gBAAgBS,MAAM;QAC7B;QACAL,gBAAgBD,OAAO,CAACO,OAAO,CAACJ;IAClC,GAAG,EAAE;IAEL,MAAMK,wBACJ,MAAC1B;QAAM2B,KAAKP;QAAgBQ,SAAS;QAAKhB,IAAI;YAAEiB,GAAG;YAAKC,UAAU;QAAI;;YACnErB,sBACC,KAACP;gBAAW6B,SAAQ;gBAAYC,WAAU;0BACvCvB;iBAED;0BACJ,KAACP;gBAAW6B,SAAQ;gBAAUC,WAAU;0BACrCxB;;YAEFE,qBACC,MAACX;gBACCW,MAAMA;gBACNuB,QAAO;gBACPC,KAAI;gBACJH,SAAQ;gBACRnB,IAAI;oBACFuB,SAAS;oBACTC,YAAY;oBACZC,KAAK;oBACLC,OAAO;oBACPC,YAAY;gBACd;;oBACD;kCAEC,KAAClC;wBAAQmC,MAAM5C,aAAa4C,IAAI;wBAAE5B,IAAI;4BAAE6B,UAAU;wBAAM;;;iBAExD;;;IAIR,MAAMC,SAAS7C,aACb;QACEyC,OAAO;QACP,UAAU;YAAEA,OAAO;QAAiB;IACtC,GACA1B;IAGF,qBACE,KAACX;QACC0C,KAAK;QACLC,YAAY;QACZnC,OAAOiB;QACPmB,WAAW;YAAE9B,QAAQ;gBAAE+B,WAAW9B;YAAU;QAAE;kBAE7CN,qBACC,KAACZ;YACCkC,WAAU;YACVtB,MAAMA;YACNuB,QAAO;YACPC,KAAI;YACJa,MAAK;YACLC,cAAY,GAAGlC,MAAM,kCAAkC,CAAC;YACxDF,IAAI8B;YACJ7B,SAASA;sBAET,cAAA,KAACR;gBAAQmC,MAAM7C,qBAAqB6C,IAAI;gBAAEC,UAAS;;2BAGrD,KAAC3C;YACCiD,MAAK;YACLC,cAAYlC;YACZF,IAAI8B;YACJ7B,SAASA;sBAET,cAAA,KAACR;gBAAQmC,MAAM7C,qBAAqB6C,IAAI;gBAAEC,UAAS;;;;AAK7D;AACAnC,QAAQ2C,WAAW,GAAG;AACtB3C,QAAQ4C,KAAK,GAAG;AAEhB,eAAe5C,QAAO"}

package/src/lib/components/link-navigation-reporter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Bridges a Next.js `<Link>`'s real navigation transition state
+ * (`useLinkStatus`, Next 15.3+/16) to the global loading overlay.
+ *
+ * Rendered as a child of every `<Link>` (via {@link NextLink}). `useLinkStatus`
+ * reads the *enclosing* link's own status context, so only the clicked link's
+ * reporter goes `pending` — exactly one overlay is queued per navigation, and
+ * it stays queued until the destination route is genuinely ready (through slow
+ * dev compiles / RSC fetches).
+ *
+ * This replaces the old `usePathname`/`useSearchParams` heuristic, which
+ * settled the overlay on URL *commit* — before a slow segment had finished
+ * fetching/compiling — so the modal flashed away while the user was still
+ * waiting for the real 200.
+ *
+ * `useLoading()` returns a no-op context when no `LoadingProvider` sits above
+ * it, so this is safe for links rendered outside an app shell.
+ */
+export declare function LinkNavigationReporter(): null;
+export declare namespace LinkNavigationReporter {
+    var displayName: string;
+    var aglyn: boolean;
+}
+export default LinkNavigationReporter;

package/src/lib/components/link-navigation-reporter.js

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2026 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.
+ */ 'use client';
+import { useLinkStatus } from "next/link";
+import { useEffect, useRef } from "react";
+import { useLoading } from "../contexts/loading.context.js";
+/**
+ * Bridges a Next.js `<Link>`'s real navigation transition state
+ * (`useLinkStatus`, Next 15.3+/16) to the global loading overlay.
+ *
+ * Rendered as a child of every `<Link>` (via {@link NextLink}). `useLinkStatus`
+ * reads the *enclosing* link's own status context, so only the clicked link's
+ * reporter goes `pending` — exactly one overlay is queued per navigation, and
+ * it stays queued until the destination route is genuinely ready (through slow
+ * dev compiles / RSC fetches).
+ *
+ * This replaces the old `usePathname`/`useSearchParams` heuristic, which
+ * settled the overlay on URL *commit* — before a slow segment had finished
+ * fetching/compiling — so the modal flashed away while the user was still
+ * waiting for the real 200.
+ *
+ * `useLoading()` returns a no-op context when no `LoadingProvider` sits above
+ * it, so this is safe for links rendered outside an app shell.
+ */ export function LinkNavigationReporter() {
+    const { pending } = useLinkStatus();
+    const { queueLoading } = useLoading();
+    const dequeueRef = useRef(null);
+    useEffect(()=>{
+        if (pending) {
+            // Guard against re-queuing while a navigation is already in flight.
+            if (!dequeueRef.current) dequeueRef.current = queueLoading();
+        } else {
+            dequeueRef.current == null ? void 0 : dequeueRef.current.call(dequeueRef);
+            dequeueRef.current = null;
+        }
+    }, [
+        pending,
+        queueLoading
+    ]);
+    // If the link unmounts mid-navigation, never leave the overlay wedged.
+    useEffect(()=>()=>{
+            dequeueRef.current == null ? void 0 : dequeueRef.current.call(dequeueRef);
+            dequeueRef.current = null;
+        }, []);
+    return null;
+}
+LinkNavigationReporter.displayName = 'LinkNavigationReporter';
+LinkNavigationReporter.aglyn = true;
+export default LinkNavigationReporter;
+
+//# sourceMappingURL=link-navigation-reporter.js.map

package/src/lib/components/link-navigation-reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/components/link-navigation-reporter.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n'use client'\n\nimport { useLinkStatus } from 'next/link'\nimport { useEffect, useRef } from 'react'\nimport { useLoading } from '../contexts/loading.context'\n\n/**\n * Bridges a Next.js `<Link>`'s real navigation transition state\n * (`useLinkStatus`, Next 15.3+/16) to the global loading overlay.\n *\n * Rendered as a child of every `<Link>` (via {@link NextLink}). `useLinkStatus`\n * reads the *enclosing* link's own status context, so only the clicked link's\n * reporter goes `pending` — exactly one overlay is queued per navigation, and\n * it stays queued until the destination route is genuinely ready (through slow\n * dev compiles / RSC fetches).\n *\n * This replaces the old `usePathname`/`useSearchParams` heuristic, which\n * settled the overlay on URL *commit* — before a slow segment had finished\n * fetching/compiling — so the modal flashed away while the user was still\n * waiting for the real 200.\n *\n * `useLoading()` returns a no-op context when no `LoadingProvider` sits above\n * it, so this is safe for links rendered outside an app shell.\n */\nexport function LinkNavigationReporter(): null {\n  const { pending } = useLinkStatus()\n  const { queueLoading } = useLoading()\n  const dequeueRef = useRef<(() => void) | null>(null)\n\n  useEffect(() => {\n    if (pending) {\n      // Guard against re-queuing while a navigation is already in flight.\n      if (!dequeueRef.current) dequeueRef.current = queueLoading()\n    } else {\n      dequeueRef.current?.()\n      dequeueRef.current = null\n    }\n  }, [pending, queueLoading])\n\n  // If the link unmounts mid-navigation, never leave the overlay wedged.\n  useEffect(\n    () => () => {\n      dequeueRef.current?.()\n      dequeueRef.current = null\n    },\n    [],\n  )\n\n  return null\n}\n\nLinkNavigationReporter.displayName = 'LinkNavigationReporter'\nLinkNavigationReporter.aglyn = true\n\nexport default LinkNavigationReporter\n"],"names":["useLinkStatus","useEffect","useRef","useLoading","LinkNavigationReporter","pending","queueLoading","dequeueRef","current","displayName","aglyn"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;AAEA,SAASA,aAAa,QAAQ,YAAW;AACzC,SAASC,SAAS,EAAEC,MAAM,QAAQ,QAAO;AACzC,SAASC,UAAU,QAAQ,iCAA6B;AAExD;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASC;IACd,MAAM,EAAEC,OAAO,EAAE,GAAGL;IACpB,MAAM,EAAEM,YAAY,EAAE,GAAGH;IACzB,MAAMI,aAAaL,OAA4B;IAE/CD,UAAU;QACR,IAAII,SAAS;YACX,oEAAoE;YACpE,IAAI,CAACE,WAAWC,OAAO,EAAED,WAAWC,OAAO,GAAGF;QAChD,OAAO;YACLC,WAAWC,OAAO,oBAAlBD,WAAWC,OAAO,MAAlBD;YACAA,WAAWC,OAAO,GAAG;QACvB;IACF,GAAG;QAACH;QAASC;KAAa;IAE1B,uEAAuE;IACvEL,UACE,IAAM;YACJM,WAAWC,OAAO,oBAAlBD,WAAWC,OAAO,MAAlBD;YACAA,WAAWC,OAAO,GAAG;QACvB,GACA,EAAE;IAGJ,OAAO;AACT;AAEAJ,uBAAuBK,WAAW,GAAG;AACrCL,uBAAuBM,KAAK,GAAG;AAE/B,eAAeN,uBAAsB"}

package/src/lib/components/list-pagination.component.d.ts

@@ -0,0 +1,57 @@
+import type { TablePaginationProps } from '@mui/material/TablePagination';
+export interface ListPaginationProps {
+    /** Zero-based, like MUI's own. */
+    page: number;
+    pageSize: number;
+    /** Rows rendered on the CURRENT page — not the collection's total. */
+    rowCount: number;
+    onPageChange: (page: number) => void;
+    /**
+     * Omit on a list whose page size is not the reader's to choose — the size
+     * menu is then not rendered at all. Most lists should pass it.
+     */
+    onPageSizeChange?: (pageSize: number) => void;
+    /**
+     * The collection's total, when the caller genuinely knows it — a
+     * client-side list, or a server `count()`. Leave undefined for a cursor or
+     * growing-window feed, where nobody knows it without paying for it.
+     */
+    count?: number;
+    /** Cursor/window feeds: whether a further page exists. */
+    hasMore?: boolean;
+    /** Override the count line, e.g. the screens tree's "top-level screens". */
+    labelDisplayedRows?: TablePaginationProps['labelDisplayedRows'];
+    pageSizeOptions?: number[];
+    disabled?: boolean;
+}
+/**
+ * The footer under every paginated list, whatever is behind it.
+ *
+ * The console grew four pagination grammars — a MUI X `DataGrid` footer, a
+ * hand-rolled `TablePagination`, a bare Previous/Next button pair, and a
+ * "Load more" that only ever grew — so the same act took a different control
+ * depending on which list a reader was standing in, and two of the four
+ * offered no way to change the page size at all. This is the one control.
+ *
+ * ## Counting without a count
+ *
+ * A cursor feed cannot say how many rows exist without reading them, which is
+ * the cost pagination is there to avoid. MUI already models this: `count={-1}`
+ * renders "1–10 of more than 10" and leaves Next live.
+ *
+ * The trick is the LAST page, where the total stops being unknown — once no
+ * further page exists, `page × pageSize + rowCount` IS the total. Handing MUI
+ * the real number there is what disables Next, so the control needs no
+ * per-version knowledge of how to reach inside and disable that button. The
+ * count line also stops saying "more than" at exactly the point it would
+ * become a lie.
+ *
+ * `DataGrid` keeps its own footer — it renders one internally and cannot be
+ * given this — but it is fed the same options, default and label from
+ * `const/table-pagination`, so the two read identically.
+ */
+export declare function ListPagination(props: ListPaginationProps): import("react").JSX.Element;
+export declare namespace ListPagination {
+    var displayName: string;
+}
+export default ListPagination;