@hybridcore/ui 1.6.29 → 1.6.30

package/dist/components/paginated-list/logic.js

@@ -1,56 +1,93 @@
-import { useThemeProps as _ } from "@mui/material";
-import { useState as u } from "react";
-const q = (h) => {
-  const P = _({ props: h, name: "HCPaginatedList" }), {
-    title: w,
-    data: d = [],
-    payload: t,
+import { useThemeProps as Y } from "@mui/material";
+import { useState as w } from "react";
+import Z from "../../hooks/useInfinitePaging.js";
+const ae = (I) => {
+  const h = Y({ props: I, name: "HCPaginatedList" }), {
+    title: R,
+    data: r = [],
+    payload: s,
     totalCount: x,
-    onChange: s,
-    onItemClick: a,
-    selectionMode: g = !1,
-    selected: r = [],
-    onSelectionChange: l,
-    sx: L,
-    ...b
-  } = P, [m, f] = u(0), [v, C] = u(10), [N, R] = u([]), i = (t == null ? void 0 : t.pageNumber) !== void 0 ? t.pageNumber : m, c = (t == null ? void 0 : t.rows) !== void 0 ? t.rows : v, I = (e, o) => {
-    f(o), s && s({ ...t, pageNumber: o, rows: c });
-  }, T = (e) => {
-    const o = parseInt(e.target.value, 10);
-    C(o), f(0), s && s({ ...t, pageNumber: 0, rows: o });
-  }, E = (e) => {
-    const n = r.indexOf(e.id) === -1 ? [...r, e.id] : r.filter((p) => p !== e.id);
-    l == null || l(n, e);
-  }, S = (e) => () => {
-    if (g) {
-      E(e);
+    variant: l = "list",
+    itemIcon: b,
+    metaSeparator: v = "•",
+    maxCards: C = 4,
+    cardsLayout: g = "rail",
+    infinite: D = !1,
+    resetKey: M,
+    loadingMore: N = !1,
+    rowsPerPage: S = 10,
+    onViewAll: T,
+    onChange: a,
+    onItemClick: i,
+    selectionMode: p = !1,
+    selected: c = [],
+    onSelectionChange: f,
+    sx: y,
+    ...E
+  } = h, [G, m] = w(0), [A, H] = w(S), [K, O] = w([]), d = (s == null ? void 0 : s.pageNumber) !== void 0 ? s.pageNumber : G, o = (s == null ? void 0 : s.rows) !== void 0 ? s.rows : A, V = (e, t) => {
+    m(t), a && a({ ...s, pageNumber: t, rows: o });
+  }, _ = (e) => {
+    const t = parseInt(e.target.value, 10);
+    H(t), m(0), a && a({ ...s, pageNumber: 0, rows: t });
+  }, j = (e) => {
+    const n = c.indexOf(e.id) === -1 ? [...c, e.id] : c.filter((u) => u !== e.id);
+    f == null || f(n, e);
+  }, k = (e) => () => {
+    if (p) {
+      j(e);
       return;
     }
-    a == null || a(e);
-  }, D = (e) => (o) => {
-    g || (o.stopPropagation(), R(
-      (n) => n.includes(e.id) ? n.filter((p) => p !== e.id) : [...n, e.id]
+    i == null || i(e);
+  }, q = (e) => (t) => {
+    p || (t.stopPropagation(), O(
+      (n) => n.includes(e.id) ? n.filter((u) => u !== e.id) : [...n, e.id]
     ));
-  }, H = s ? x || 0 : d.length, M = s ? d : d.slice(i * c, (i + 1) * c), O = { ...P };
+  }, z = a ? x || 0 : r.length, P = l === "cards" && g === "grid" && D, {
+    displayData: B,
+    hasMore: F,
+    isLoadingMore: J,
+    scrollRef: Q,
+    sentinelRef: U
+  } = Z({
+    data: r,
+    totalCount: x,
+    page: d,
+    rowsPerPage: o,
+    payload: s,
+    onChange: a,
+    resetKey: M,
+    loadingMore: N,
+    enabled: P
+  }), W = a ? r : r.slice(d * o, (d + 1) * o), L = P ? B : W, X = { ...h };
   return {
-    title: w,
-    displayData: M,
-    count: H,
-    page: i,
-    rowsPerPage: c,
-    expanded: N,
-    selectionMode: g,
-    selected: r,
-    handleChangePage: I,
-    handleChangeRowsPerPage: T,
-    handleItemClick: S,
-    handleExpandToggle: D,
-    onItemClick: a,
-    ownerState: O,
-    sx: L,
-    other: b
+    title: R,
+    variant: l,
+    itemIcon: b,
+    metaSeparator: v,
+    onViewAll: T,
+    cardsLayout: g,
+    isInfinite: P,
+    hasMore: F,
+    isLoadingMore: J,
+    refs: { scrollRef: Q, sentinelRef: U },
+    // The rail is a preview and caps itself; the grid is the whole page and does not.
+    displayData: l === "cards" && g === "rail" ? L.slice(0, C) : L,
+    count: z,
+    page: d,
+    rowsPerPage: o,
+    expanded: K,
+    selectionMode: p,
+    selected: c,
+    handleChangePage: V,
+    handleChangeRowsPerPage: _,
+    handleItemClick: k,
+    handleExpandToggle: q,
+    onItemClick: i,
+    ownerState: X,
+    sx: y,
+    other: E
   };
 };
 export {
-  q as usePaginatedListLogic
+  ae as usePaginatedListLogic
 };

package/dist/components/paginated-list/styled.js

@@ -1,18 +1,24 @@
-import { styled as t, Paper as n, Box as a, List as o } from "@mui/material";
-const s = t(n, {
+import { styled as a, Paper as o, Box as e, List as s, Button as d, Typography as i } from "@mui/material";
+const g = a(o, {
   name: "HCPaginatedList",
   slot: "Root"
 })(() => ({
   display: "flex",
   flexDirection: "column",
   height: "100%"
-})), d = t(a, {
+})), c = a(e, {
   name: "HCPaginatedList",
   slot: "Header"
-})(({ theme: i }) => ({
+})(({ theme: t }) => ({
   flex: "0 0 auto",
-  padding: i.spacing(1.25, 2)
-})), l = t(a, {
+  padding: t.spacing(1.25, 2),
+  // The `cards` variant hangs "View all" off the right of the title line; the
+  // list variant has a title and nothing else, so the row is harmless there.
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  gap: t.spacing(1)
+})), p = a(e, {
   name: "HCPaginatedList",
   slot: "Content"
 })(() => ({
@@ -22,32 +28,163 @@ const s = t(n, {
   flex: "1 1 auto",
   minHeight: 0,
   overflow: "hidden"
-})), g = t(o, {
+})), C = a(s, {
   name: "HCPaginatedList",
   slot: "List"
 })(() => ({
   flex: 1,
   overflowY: "auto"
-})), r = t("div", {
+})), f = a("div", {
   name: "HCPaginatedList",
   slot: "Pagination"
-})(({ theme: i }) => ({
-  borderTop: `1px solid ${i.palette.divider}`,
+})(({ theme: t }) => ({
+  borderTop: `1px solid ${t.palette.divider}`,
   ".MuiToolbar-root": {
     minHeight: 24,
-    paddingLeft: i.spacing(1)
+    paddingLeft: t.spacing(1)
   },
   ".MuiTablePagination-actions .MuiButtonBase-root": {
-    padding: i.spacing(0.5)
+    padding: t.spacing(0.5)
   },
   ".MuiTablePagination-displayedRows": {
     lineHeight: 1
   }
+})), x = a(d, {
+  name: "HCPaginatedList",
+  slot: "ViewAll"
+})(() => ({
+  textTransform: "none",
+  flex: "0 0 auto"
+})), l = 320, L = a(e, {
+  name: "HCPaginatedList",
+  slot: "CardRail",
+  shouldForwardProp: (t) => t !== "grid"
+})(({ theme: t, grid: n }) => ({
+  minHeight: 0,
+  display: "flex",
+  alignItems: "stretch",
+  gap: t.spacing(2),
+  ...n ? {
+    // Wraps and lets the *page* scroll. No `overflow` here on purpose: the rail
+    // has no bounded height, so `auto` would produce no scrollbar and leave the
+    // sentinel permanently in view, pulling page after page.
+    flex: "1 1 auto",
+    flexWrap: "wrap",
+    alignContent: "flex-start"
+  } : {
+    flex: "0 0 auto",
+    overflow: "hidden"
+  }
+})), P = a(e, {
+  name: "HCPaginatedList",
+  slot: "Card"
+})(({ theme: t }) => ({
+  // Equal shares of the row: the rail does not scroll, so cards divide the width
+  // rather than spilling out of it. `flex-basis: 0` stops a long title widening its
+  // card; the grid overrides the basis so cards wrap instead of shrinking to slivers.
+  flex: "1 1 0",
+  minWidth: 0,
+  // Height follows the content, capped so one long summary cannot make a card
+  // twice its neighbours.
+  maxHeight: l,
+  display: "flex",
+  flexDirection: "column",
+  gap: t.spacing(1),
+  padding: t.spacing(2),
+  borderRadius: t.shape.borderRadius,
+  backgroundColor: t.palette.background.paper,
+  overflow: "hidden"
+})), m = a(e, {
+  name: "HCPaginatedList",
+  slot: "CardHeader"
+})(({ theme: t }) => ({
+  display: "flex",
+  alignItems: "flex-start",
+  gap: t.spacing(1)
+})), H = a(e, {
+  name: "HCPaginatedList",
+  slot: "CardIcon"
+})(() => ({
+  flex: "0 0 auto",
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center"
+})), u = a(i, {
+  name: "HCPaginatedList",
+  slot: "CardTitle"
+})(() => ({
+  // Clamped, not truncated: a one-line ellipsis loses too much of a headline.
+  display: "-webkit-box",
+  WebkitBoxOrient: "vertical",
+  WebkitLineClamp: 3,
+  overflow: "hidden"
+})), y = a(i, {
+  name: "HCPaginatedList",
+  slot: "CardDescription"
+})(({ theme: t }) => ({
+  // `0 1 auto`, not `1`: a short summary ends under itself instead of pushing the
+  // footer to the cap. Growing it also stopped the clamp from biting.
+  flex: "0 1 auto",
+  minHeight: 0,
+  color: t.palette.text.secondary,
+  display: "-webkit-box",
+  WebkitBoxOrient: "vertical",
+  WebkitLineClamp: 5,
+  overflow: "hidden",
+  // `-webkit-box-orient` is non-standard and some prefixers drop it, leaving the
+  // clamp inert; the height cap makes the cut deterministic either way.
+  maxHeight: "calc(5 * 1.5em)"
+})), b = a(e, {
+  name: "HCPaginatedList",
+  slot: "CardFooter"
+})(() => ({
+  flex: "0 0 auto",
+  // Pushed to the card's foot so the date and the arrow sit on one line across
+  // the whole rail, whatever each summary's length.
+  marginTop: "auto",
+  paddingTop: 8,
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+  gap: 8
+})), w = a(i, {
+  name: "HCPaginatedList",
+  slot: "CardMeta"
+})(({ theme: t }) => ({
+  color: t.palette.text.secondary,
+  whiteSpace: "nowrap"
+})), h = a(e, {
+  name: "HCPaginatedList",
+  slot: "CardAction"
+})(({ theme: t }) => ({
+  display: "flex",
+  alignItems: "center",
+  color: t.palette.text.secondary
+})), v = a(e, {
+  name: "HCPaginatedList",
+  slot: "LoadMore"
+})(({ theme: t }) => ({
+  flex: "1 0 100%",
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  minHeight: t.spacing(5)
 }));
 export {
-  l as PaginatedListContent,
-  d as PaginatedListHeader,
-  g as PaginatedListList,
-  r as PaginatedListPagination,
-  s as PaginatedListRoot
+  P as PaginatedListCard,
+  h as PaginatedListCardAction,
+  y as PaginatedListCardDescription,
+  b as PaginatedListCardFooter,
+  m as PaginatedListCardHeader,
+  H as PaginatedListCardIcon,
+  w as PaginatedListCardMeta,
+  L as PaginatedListCardRail,
+  u as PaginatedListCardTitle,
+  p as PaginatedListContent,
+  c as PaginatedListHeader,
+  C as PaginatedListList,
+  v as PaginatedListLoadMore,
+  f as PaginatedListPagination,
+  g as PaginatedListRoot,
+  x as PaginatedListViewAll
 };

package/dist/hooks/useInfinitePaging.js

@@ -0,0 +1,51 @@
+import { useRef as o, useState as $, useMemo as k, useCallback as j, useEffect as E } from "react";
+const q = "120px", F = ({
+  data: r,
+  totalCount: L,
+  page: s,
+  rowsPerPage: u,
+  payload: v,
+  onChange: l,
+  resetKey: N,
+  loading: O = !1,
+  loadingMore: B = !1,
+  enabled: t = !0
+}) => {
+  const I = o(null), p = o(null), e = !!l, [x, y] = $(u), f = o(/* @__PURE__ */ new Map()), M = o(null), R = `${N ?? ""}`, A = o(R), c = o(null);
+  A.current !== R && (A.current = R, f.current.clear(), c.current = null, M.current = null), t && e && r !== M.current && (M.current = r, s === 0 && f.current.clear(), f.current.set(s, r), c.current === s && (c.current = null));
+  const D = k(() => !t || !e ? r : Array.from(f.current.keys()).sort((n, i) => n - i).flatMap((n) => f.current.get(n) ?? []), [t, e, r, s]), G = e ? L ?? 0 : r.length, S = k(() => t ? e ? D : r.slice(0, x) : r, [t, e, D, r, x]), m = t && S.length < G, _ = j(() => {
+    if (!e) {
+      y((i) => i + u);
+      return;
+    }
+    const n = s + 1;
+    c.current === null && (c.current = n, l == null || l({
+      ...v,
+      pageNumber: n,
+      rows: u
+    }));
+  }, [e, u, s, l, v]);
+  return E(() => {
+    if (!t || !m || O) return;
+    const n = p.current;
+    if (!n || typeof IntersectionObserver > "u") return;
+    const i = new IntersectionObserver(
+      (T) => {
+        T.some((V) => V.isIntersecting) && _();
+      },
+      { root: I.current, rootMargin: q }
+    );
+    return i.observe(n), () => i.disconnect();
+  }, [t, m, O, _]), E(() => {
+    t && !e && y(u);
+  }, [t, e, u, R, r.length]), {
+    displayData: S,
+    hasMore: m,
+    isLoadingMore: B || c.current !== null,
+    scrollRef: I,
+    sentinelRef: p
+  };
+};
+export {
+  F as default
+};

package/dist/main.d.ts

@@ -286,6 +286,24 @@ export declare interface ChartProps {
      * timeline. Date-dimension charts only.
      */
     skipEmptyDates?: boolean;
+    /**
+     * Fill the band between the line and the axis, fading from the series' own
+     * color down to transparent. Off by default: without it the chart draws a
+     * stroke only, which is the look every consumer had before this prop existed.
+     *
+     * Applies to **single-series** line charts only. A gradient under every line of
+     * a multi-series chart buries the lines beneath it, so the fill is skipped there
+     * even when this is on — which lets a deployment turn it on theme-wide without
+     * having to exempt its multi-series panels one by one.
+     *
+     * Line-type charts only.
+     */
+    areaFill?: boolean;
+    /**
+     * Dash pattern for the line stroke as am5 `[dash, gap]` pixel lengths, e.g.
+     * `[6, 4]`. Unset draws a solid line. Line-type charts only.
+     */
+    strokeDasharray?: number[];
     sx?: SxProps<Theme>;
 }
 
@@ -1558,7 +1576,7 @@ export { Map_2 as Map }
 export declare const MetricCard: (props: MetricCardProps) => JSX_2.Element;
 
 export declare type MetricCardComponentOverride<Theme = unknown> = {
-    defaultProps?: MetricCardProps;
+    defaultProps?: Partial<MetricCardProps>;
     styleOverrides?: ComponentsOverrides_2<Theme>["HCMetricCard"];
 };
 
@@ -1607,11 +1625,27 @@ export declare interface MetricCardProps {
     showChart?: boolean;
     chartType?: MetricChartType;
 
+    // Color of the sparkline — line stroke, column fill and the gradient stops all
+    // derive from it. Defaults to `theme.palette.divider`, the muted look the card
+    // shipped with. Set it per deployment through
+    // `components.HCMetricCard.defaultProps` to brand the chart.
+    chartColor?: string;
+
+    // How the area under a line sparkline is filled:
+    //   "gradient" — fades from the series colour down to transparent
+    //   "solid"    — a flat translucent wash
+    //   "none"     — stroke only
+    // Defaults to "gradient" for the `panel` layout and "solid" for `overlay`, the look
+    // each layout already had.
+    chartFill?: MetricChartFill;
+
     sx?: SxProps<Theme>;
 }
 
 export declare type MetricChangeType = "percentage" | "absolute";
 
+declare type MetricChartFill = "none" | "solid" | "gradient";
+
 export declare interface MetricChartSnapshot {
     metric: string;
     value: number;
@@ -1778,6 +1812,9 @@ export declare type PackedCirclesProps = ChartProps;
 
 export declare const PaginatedList: (inProps: PaginatedListProps) => JSX_2.Element;
 
+/** How the `cards` variant arranges itself — see `PaginatedListProps.cardsLayout`. */
+declare type PaginatedListCardsLayout = "rail" | "grid";
+
 export declare type PaginatedListComponentOverride<Theme = unknown> = {
     defaultProps?: Partial<PaginatedListProps>;
     styleOverrides?: ComponentsOverrides_2<Theme>["HCPaginatedList"];
@@ -1788,11 +1825,63 @@ export declare interface PaginatedListItem {
     title: string;
     description: string;
     icon?: React.ReactNode;
+    /**
+     * Footnote line under the card — a date, a source, an author. Empty segments drop
+     * out so a missing field leaves no dangling separator. Same contract as
+     * `DataListItem.meta`, so a list moved between the two keeps its mapping.
+     * `cards` variant only.
+     */
+    meta?: (string | number | null | undefined)[];
 }
 
 export declare interface PaginatedListProps {
     title?: string;
     data: PaginatedListItem[];
+    variant?: PaginatedListVariant;
+    /**
+     * Mark for cards carrying no `icon` of their own — a widget's mapping has no field
+     * for one, so the deployment names it. A component, not an element, so a theme file
+     * needs no JSX; sized and tinted by the `cardIcon` slot. `cards` variant only.
+     */
+    itemIcon?: React.ElementType;
+    /** Joins `item.meta` segments. Matches `DataListProps.metaSeparator`. */
+    metaSeparator?: string;
+    /**
+     * How many cards the rail draws; the rest is reached through `onViewAll` rather
+     * than a sideways scroll. Ignored under `cardsLayout: "grid"`.
+     */
+    maxCards?: number;
+    /**
+     * How the cards are arranged. `rail` (default) is one capped row with no pager — a
+     * preview. `grid` wraps every card onto as many rows as it takes and brings the
+     * pager back. One setting rather than separate wrap/cap/pager flags: the three
+     * always move together.
+     */
+    cardsLayout?: PaginatedListCardsLayout;
+    /**
+     * Reveal rows as the grid is scrolled instead of drawing a pager. `grid` layout
+     * only — a rail shows one screenful by design and has nothing to scroll into.
+     */
+    infinite?: boolean;
+    /**
+     * Server-side infinite scroll accumulates the pages it receives. Change this
+     * whenever the query behind `data` changes — a new filter, sort or search — and
+     * the accumulated rows are dropped so the grid restarts at the first page.
+     */
+    resetKey?: string | number;
+    /** Set while a page request is in flight, to draw the footer spinner. */
+    loadingMore?: boolean;
+    /**
+     * Rows per page when the payload does not say. A grid needs more than a column to
+     * fill a screen, and an unfilled screen leaves the sentinel in view — which fetches
+     * the next page before the reader moves. Matches `DataListProps.rowsPerPage`.
+     */
+    rowsPerPage?: number;
+    /**
+     * Renders the header's "View all" affordance. Omitted, the affordance is not
+     * drawn at all — the rail simply shows its page. `cards` variant only.
+     */
+    onViewAll?: () => void;
     totalCount?: number;
     payload?: Partial<FV.SearchDTO>;
     onChange?: (params: Partial<FV.SearchDTO>) => void;
@@ -1815,6 +1904,13 @@ export declare interface PaginatedListSnapshot {
     data: PaginatedListItem[];
 }
 
+/**
+ * How the list presents its items. `list` (default) is the paginated column the
+ * widget shipped with; `cards` is a row of cards that hands the rest to `onViewAll`.
+ * Chosen through `HCPaginatedList.defaultProps`, so call sites stay brand-agnostic.
+ */
+declare type PaginatedListVariant = "list" | "cards";
+
 export declare const PhoneInput: (props: PhoneInputProps) => JSX_2.Element;
 
 export declare type PhoneInputComponentOverride<Theme = unknown> = {
@@ -3353,7 +3449,7 @@ declare module "@mui/material/styles" {
   }
 
   interface ComponentsPropsList {
-    HCMetricCard: MetricCardProps;
+    HCMetricCard: Partial<MetricCardProps>;
   }
 
   interface Components<Theme = unknown> {
@@ -3933,7 +4029,23 @@ declare module "@mui/material/styles" {
 
 declare module "@mui/material/styles" {
   interface ComponentNameToClassKey {
-    HCPaginatedList: "root" | "header" | "content" | "list" | "pagination";
+    HCPaginatedList:
+      | "root"
+      | "header"
+      | "content"
+      | "list"
+      | "pagination"
+      | "viewAll"
+      | "cardRail"
+      | "card"
+      | "cardHeader"
+      | "cardIcon"
+      | "cardTitle"
+      | "cardDescription"
+      | "cardFooter"
+      | "cardMeta"
+      | "cardAction"
+      | "loadMore";
   }
 
   interface ComponentsPropsList {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hybridcore/ui",
   "description": "Hybrid Core UI Library",
-  "version": "1.6.29",
+  "version": "1.6.30",
   "author": "Hybrid Core",
   "license": "ISC",
   "type": "module",