@borisj74/bv-ds 0.1.0

package/src/components/Notification/Notification.tsx

@@ -0,0 +1,102 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import clsx from "clsx";
+
+export type NotificationVariant = "default" | "success" | "warning" | "error" | "gray";
+
+export interface NotificationProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+  /** Colours the default featured-icon ring (ignored if `leadingMedia` set). */
+  variant?: NotificationVariant;
+  title: ReactNode;
+  description?: ReactNode;
+  /** Left media slot (icon / avatar / progress). Overrides the default ring icon. */
+  leadingMedia?: ReactNode;
+  /** Full-bleed image (the "Image" type) rendered below the text. */
+  imageUrl?: string;
+  /** Action row — compose link/text buttons. */
+  actions?: ReactNode;
+  /** Renders an x-close button top-right. */
+  onDismiss?: () => void;
+}
+
+const RING: Record<NotificationVariant, string> = {
+  default: "border-fg-brand-primary text-fg-brand-primary",
+  success: "border-fg-success-primary text-fg-success-primary",
+  warning: "border-fg-warning-primary text-fg-warning-primary",
+  error: "border-fg-error-primary text-fg-error-primary",
+  gray: "border-fg-quaternary text-fg-quaternary",
+};
+
+const GLYPH: Record<NotificationVariant, string> = {
+  default: "M10 13.33V10M10 6.67h.01M18.33 10a8.33 8.33 0 1 1-16.66 0 8.33 8.33 0 0 1 16.66 0Z",
+  gray: "M10 13.33V10M10 6.67h.01M18.33 10a8.33 8.33 0 1 1-16.66 0 8.33 8.33 0 0 1 16.66 0Z",
+  success: "M6.25 10l2.5 2.5 5-5M18.33 10a8.33 8.33 0 1 1-16.66 0 8.33 8.33 0 0 1 16.66 0Z",
+  warning: "M10 6.67V10m0 3.33h.01M18.33 10a8.33 8.33 0 1 1-16.66 0 8.33 8.33 0 0 1 16.66 0Z",
+  error: "M10 6.67V10m0 3.33h.01M18.33 10a8.33 8.33 0 1 1-16.66 0 8.33 8.33 0 0 1 16.66 0Z",
+};
+
+const XClose = () => (
+  <svg viewBox="0 0 20 20" fill="none" className="size-5" aria-hidden>
+    <path d="M15 5 5 15M5 5l10 10" stroke="currentColor" strokeWidth="1.67" strokeLinecap="round" strokeLinejoin="round" />
+  </svg>
+);
+
+const FeaturedIcon = ({ variant }: { variant: NotificationVariant }) => (
+  <span className={clsx("relative inline-flex size-5 shrink-0 items-center justify-center", RING[variant].split(" ")[1])}>
+    <span className={clsx("absolute inset-[-20%] rounded-full border-2 opacity-30", RING[variant].split(" ")[0])} />
+    <span className={clsx("absolute inset-[-45%] rounded-full border-2 opacity-10", RING[variant].split(" ")[0])} />
+    <svg viewBox="0 0 20 20" fill="none" className="relative size-5" aria-hidden>
+      <path d={GLYPH[variant]} stroke="currentColor" strokeWidth="1.67" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  </span>
+);
+
+/**
+ * Toast / inline notification. One component: `variant` colours the default
+ * featured-icon ring; `leadingMedia` overrides it with any node (avatar, custom
+ * icon, progress). `imageUrl` adds the full-bleed image type, `actions` the CTA
+ * row, `onDismiss` the x-close. `shadow-lg` approximates Figma's 3-layer lg.
+ */
+export function Notification({
+  variant = "default",
+  title,
+  description,
+  leadingMedia,
+  imageUrl,
+  actions,
+  onDismiss,
+  className,
+  ...rest
+}: NotificationProps) {
+  return (
+    <div
+      className={clsx(
+        "relative flex w-full items-start gap-xl rounded-xl border border-border-secondary-alt bg-bg-primary-alt p-xl shadow-lg",
+        className,
+      )}
+      {...rest}
+    >
+      {leadingMedia ?? <FeaturedIcon variant={variant} />}
+
+      <div className="flex min-w-0 flex-1 flex-col gap-lg pr-8">
+        <div className="flex flex-col gap-xs">
+          <p className="text-sm font-semibold text-fg-primary">{title}</p>
+          {description && <p className="text-sm text-fg-secondary">{description}</p>}
+        </div>
+        {imageUrl && <img src={imageUrl} alt="" className="h-40 w-full rounded-md object-cover" />}
+        {actions && <div className="flex items-center gap-lg">{actions}</div>}
+      </div>
+
+      {onDismiss && (
+        <button
+          type="button"
+          onClick={onDismiss}
+          aria-label="Dismiss"
+          className="absolute right-2 top-2 flex size-9 items-center justify-center rounded-md text-fg-quaternary transition-colors hover:text-fg-quaternary-hover"
+        >
+          <XClose />
+        </button>
+      )}
+    </div>
+  );
+}

package/src/components/Notification/index.ts

@@ -0,0 +1,2 @@
+export { Notification } from "./Notification";
+export type { NotificationProps, NotificationVariant } from "./Notification";

package/src/components/NumberInput/NumberInput.tsx

@@ -0,0 +1,114 @@
+import { type ReactNode } from "react";
+import clsx from "clsx";
+import { FieldWrapper, boxClasses } from "../InputField/inputFieldShared";
+
+export type NumberInputLayout = "horizontal" | "vertical";
+
+export interface NumberInputProps {
+  layout?: NumberInputLayout;
+  value?: number;
+  onChange?: (value: number) => void;
+  min?: number;
+  max?: number;
+  step?: number;
+  label?: ReactNode;
+  hint?: ReactNode;
+  required?: boolean;
+  destructive?: boolean;
+  disabled?: boolean;
+  className?: string;
+  "aria-label"?: string;
+}
+
+/**
+ * Standalone numeric counter (NOT an `InputField` type). `horizontal` flanks the
+ * value with −/+ buttons; `vertical` stacks up/down chevrons on the right. Reuses
+ * the input family's `FieldWrapper` + `boxClasses`. Controlled via
+ * `value`/`onChange`, clamped to `min`/`max` by `step`.
+ */
+export function NumberInput({
+  layout = "horizontal",
+  value = 0,
+  onChange,
+  min = -Infinity,
+  max = Infinity,
+  step = 1,
+  label,
+  hint,
+  required,
+  destructive,
+  disabled,
+  className,
+  "aria-label": ariaLabel,
+}: NumberInputProps) {
+  const clamp = (n: number) => Math.min(max, Math.max(min, n));
+  const set = (n: number) => onChange?.(clamp(n));
+  const dec = () => set(value - step);
+  const inc = () => set(value + step);
+
+  const Minus = (
+    <svg viewBox="0 0 20 20" fill="none" className="size-5" aria-hidden>
+      <path d="M4.167 10h11.666" stroke="currentColor" strokeWidth="1.67" strokeLinecap="round" />
+    </svg>
+  );
+  const Plus = (
+    <svg viewBox="0 0 20 20" fill="none" className="size-5" aria-hidden>
+      <path d="M10 4.167v11.666M4.167 10h11.666" stroke="currentColor" strokeWidth="1.67" strokeLinecap="round" />
+    </svg>
+  );
+  const Chevron = ({ up }: { up: boolean }) => (
+    <svg viewBox="0 0 12 12" fill="none" className={clsx("size-3", up && "rotate-180")} aria-hidden>
+      <path d="M3 4.5 6 7.5 9 4.5" stroke="currentColor" strokeWidth="1.2" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  );
+
+  const numberEl = (
+    <input
+      type="text"
+      inputMode="numeric"
+      aria-label={ariaLabel ?? (typeof label === "string" ? label : "Number")}
+      value={value}
+      disabled={disabled}
+      onChange={(e) => {
+        const n = Number(e.target.value.replace(/[^\d.-]/g, ""));
+        if (!Number.isNaN(n)) set(n);
+      }}
+      className={clsx(
+        "min-w-0 flex-1 bg-transparent py-md text-md text-text-primary outline-none",
+        layout === "horizontal" ? "px-lg text-center" : "px-lg text-left",
+      )}
+    />
+  );
+
+  const box =
+    layout === "horizontal" ? (
+      <div className={clsx(boxClasses(destructive), "gap-0 overflow-hidden p-0")}>
+        <button type="button" onClick={dec} disabled={disabled} aria-label="Decrease" className="flex items-center justify-center border-r border-border-primary p-2.5 text-fg-quaternary hover:bg-bg-primary-hover disabled:opacity-60">
+          {Minus}
+        </button>
+        {numberEl}
+        <button type="button" onClick={inc} disabled={disabled} aria-label="Increase" className="flex items-center justify-center border-l border-border-primary p-2.5 text-fg-quaternary hover:bg-bg-primary-hover disabled:opacity-60">
+          {Plus}
+        </button>
+      </div>
+    ) : (
+      <div className={clsx(boxClasses(destructive), "gap-0 overflow-hidden p-0")}>
+        {numberEl}
+        <div className="flex flex-col self-stretch border-l border-border-primary">
+          <button type="button" onClick={inc} disabled={disabled} aria-label="Increase" className="flex flex-1 items-center justify-center px-md text-fg-quaternary hover:bg-bg-primary-hover disabled:opacity-60">
+            <Chevron up />
+          </button>
+          <span className="h-px w-full bg-border-primary" />
+          <button type="button" onClick={dec} disabled={disabled} aria-label="Decrease" className="flex flex-1 items-center justify-center px-md text-fg-quaternary hover:bg-bg-primary-hover disabled:opacity-60">
+            <Chevron up={false} />
+          </button>
+        </div>
+      </div>
+    );
+
+  return (
+    <FieldWrapper label={label} required={required} hint={hint} destructive={destructive} className={className}>
+      {box}
+    </FieldWrapper>
+  );
+}

package/src/components/NumberInput/index.ts

@@ -0,0 +1,2 @@
+export { NumberInput } from "./NumberInput";
+export type { NumberInputProps, NumberInputLayout } from "./NumberInput";

package/src/components/PageHeader/PageHeader.tsx

@@ -0,0 +1,88 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import clsx from "clsx";
+
+export type PageHeaderStyle =
+  | "simple"
+  | "avatar"
+  | "bannerAvatar"
+  | "bannerAvatarCentered"
+  | "bannerSimpleCentered"
+  | "bannerSimple";
+
+export interface PageHeaderProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "title" | "style"> {
+  style?: PageHeaderStyle;
+  title: ReactNode;
+  description?: ReactNode;
+  /** Avatar / featured visual (avatar styles). */
+  avatar?: ReactNode;
+  /** Trailing actions row (buttons). */
+  actions?: ReactNode;
+  /** Optional breadcrumbs slot above the title. */
+  breadcrumbs?: ReactNode;
+  /** Banner background image (banner styles); falls back to `bg-tertiary`. */
+  bannerUrl?: string;
+}
+
+/**
+ * Page header — one component over the 6 Figma `Style`s. `banner*` styles render
+ * a banner strip the content overlaps; `*Centered` styles centre the text;
+ * `avatar` styles show the `avatar` slot. Breakpoint handled with Tailwind
+ * responsive prefixes. Constrained to `container-max-width-desktop` (1280) with
+ * container padding.
+ */
+export function PageHeader({
+  style = "simple",
+  title,
+  description,
+  avatar,
+  actions,
+  breadcrumbs,
+  bannerUrl,
+  className,
+  ...rest
+}: PageHeaderProps) {
+  const isBanner = style.startsWith("banner");
+  const isCentered = style.endsWith("Centered");
+  const hasAvatar = style === "avatar" || style === "bannerAvatar" || style === "bannerAvatarCentered";
+
+  return (
+    <div
+      className={clsx(
+        "mx-auto w-full max-w-screen-xl px-container-padding-mobile md:px-container-padding-desktop",
+        className,
+      )}
+      {...rest}
+    >
+      {isBanner && (
+        <div
+          className="h-32 w-full rounded-2xl bg-bg-tertiary bg-cover bg-center md:h-40"
+          style={bannerUrl ? { backgroundImage: `url(${bannerUrl})` } : undefined}
+        />
+      )}
+
+      <div className={clsx("flex flex-col gap-xl", isCentered && "items-center text-center", isBanner && "px-md")}>
+        {breadcrumbs}
+
+        {hasAvatar && avatar && (
+          <div className={clsx("shrink-0", isBanner && "-mt-10", isCentered && "flex justify-center")}>
+            {avatar}
+          </div>
+        )}
+
+        <div
+          className={clsx(
+            "flex w-full gap-xl",
+            isCentered ? "flex-col items-center" : "flex-col items-start justify-between md:flex-row md:items-center",
+          )}
+        >
+          <div className={clsx("flex flex-col gap-xxs", isCentered && "max-w-width-lg items-center")}>
+            <h1 className="text-xl font-semibold text-text-primary">{title}</h1>
+            {description && <p className="text-md text-text-tertiary">{description}</p>}
+          </div>
+          {actions && <div className="flex shrink-0 items-center gap-lg">{actions}</div>}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/PageHeader/index.ts

@@ -0,0 +1,2 @@
+export { PageHeader } from "./PageHeader";
+export type { PageHeaderProps, PageHeaderStyle } from "./PageHeader";

package/src/components/Pagination/Pagination.tsx

@@ -0,0 +1,124 @@
+import { type HTMLAttributes } from "react";
+import clsx from "clsx";
+import { PaginationNumberBase, type PaginationNumberShape } from "../PaginationNumberBase";
+import { PaginationButtonGroupBase } from "../PaginationButtonGroupBase";
+
+export type PaginationType = "default" | "minimal" | "buttonGroup";
+
+export interface PaginationProps extends HTMLAttributes<HTMLDivElement> {
+  /** 1-based current page. */
+  page: number;
+  /** Total page count. */
+  total: number;
+  onPageChange?: (page: number) => void;
+  /** default = Prev / numbers / Next · minimal = Prev / "Page x of y" / Next · buttonGroup = bordered group. */
+  type?: PaginationType;
+  /** Number-cell shape (default/minimal). */
+  shape?: PaginationNumberShape;
+  /** Max page cells before collapsing the middle with ellipsis. Default 7. */
+  maxVisible?: number;
+}
+
+type PageToken = number | "ellipsis";
+
+/**
+ * Build the visible page tokens: always first + last + current±2, with an
+ * `"ellipsis"` marker inserted wherever consecutive pages are skipped.
+ */
+function pageTokens(current: number, total: number, maxVisible: number): PageToken[] {
+  if (total <= maxVisible) {
+    return Array.from({ length: total }, (_, i) => i + 1);
+  }
+  const wanted = new Set<number>([1, total, current, current - 1, current - 2, current + 1, current + 2]);
+  const sorted = [...wanted].filter((p) => p >= 1 && p <= total).sort((a, b) => a - b);
+  const out: PageToken[] = [];
+  let prev = 0;
+  for (const p of sorted) {
+    if (p - prev > 1) out.push("ellipsis");
+    out.push(p);
+    prev = p;
+  }
+  return out;
+}
+
+const Arrow = ({ dir }: { dir: "left" | "right" }) => (
+  <svg viewBox="0 0 20 20" fill="none" className="size-5" aria-hidden>
+    <path d={dir === "left" ? "M15.83 10H4.17M4.17 10l5 5M4.17 10l5-5" : "M4.17 10h11.66M15.83 10l-5 5M15.83 10l-5-5"} stroke="currentColor" strokeWidth="1.67" strokeLinecap="round" strokeLinejoin="round" />
+  </svg>
+);
+
+const PrevNext = ({ dir, disabled, onClick }: { dir: "left" | "right"; disabled: boolean; onClick: () => void }) => (
+  <button
+    type="button"
+    disabled={disabled}
+    onClick={onClick}
+    className="flex items-center gap-xs text-sm font-semibold text-text-tertiary disabled:opacity-50"
+  >
+    {dir === "left" && <Arrow dir="left" />}
+    {dir === "left" ? "Previous" : "Next"}
+    {dir === "right" && <Arrow dir="right" />}
+  </button>
+);
+
+/**
+ * Number/button-based pagination. `default` = Previous · number cells · Next;
+ * `minimal` = Previous · "Page x of y" · Next; `buttonGroup` = a bordered
+ * connected group. Composes `PaginationNumberBase` + `PaginationButtonGroupBase`.
+ * Collapses the middle with ellipsis past `maxVisible` (always shows first/last
+ * + current±2).
+ */
+export function Pagination({
+  page,
+  total,
+  onPageChange,
+  type = "default",
+  shape = "square",
+  maxVisible = 7,
+  className,
+  ...rest
+}: PaginationProps) {
+  const go = (p: number) => p >= 1 && p <= total && onPageChange?.(p);
+  const tokens = pageTokens(page, total, maxVisible);
+
+  if (type === "buttonGroup") {
+    return (
+      <div className={clsx("inline-flex overflow-hidden rounded-md border border-border-primary [&>*:last-child]:border-r-0", className)} {...rest}>
+        <PaginationButtonGroupBase cellType="leadingIcon" onClick={() => go(page - 1)} />
+        {tokens.map((t, i) =>
+          t === "ellipsis" ? (
+            <span key={`e${i}`} className="flex min-h-9 min-w-9 items-center justify-center border-r border-border-primary bg-bg-primary p-md text-sm font-semibold text-text-quaternary">
+              …
+            </span>
+          ) : (
+            <PaginationButtonGroupBase key={t} cellType="number" active={t === page} onClick={() => go(t)}>
+              {t}
+            </PaginationButtonGroupBase>
+          ),
+        )}
+        <PaginationButtonGroupBase cellType="trailingIcon" onClick={() => go(page + 1)} />
+      </div>
+    );
+  }
+
+  return (
+    <div className={clsx("flex w-full items-center justify-between gap-md", className)} {...rest}>
+      <PrevNext dir="left" disabled={page <= 1} onClick={() => go(page - 1)} />
+      {type === "minimal" ? (
+        <span className="text-sm font-medium text-text-secondary">Page {page} of {total}</span>
+      ) : (
+        <div className="flex items-center gap-xxs">
+          {tokens.map((t, i) =>
+            t === "ellipsis" ? (
+              <span key={`e${i}`} className="flex size-9 items-center justify-center text-sm font-medium text-text-quaternary">…</span>
+            ) : (
+              <PaginationNumberBase key={t} shape={shape} active={t === page} onClick={() => go(t)}>
+                {t}
+              </PaginationNumberBase>
+            ),
+          )}
+        </div>
+      )}
+      <PrevNext dir="right" disabled={page >= total} onClick={() => go(page + 1)} />
+    </div>
+  );
+}

package/src/components/Pagination/index.ts

@@ -0,0 +1,2 @@
+export { Pagination } from "./Pagination";
+export type { PaginationProps, PaginationType } from "./Pagination";

package/src/components/PaginationButtonGroupBase/PaginationButtonGroupBase.tsx

@@ -0,0 +1,69 @@
+import { type ButtonHTMLAttributes, type ReactNode } from "react";
+import clsx from "clsx";
+
+export type PaginationButtonGroupType = "number" | "leadingIcon" | "trailingIcon" | "iconOnly";
+
+export interface PaginationButtonGroupBaseProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> {
+  /** number cell · leading/trailing icon+label · icon-only arrow. */
+  cellType?: PaginationButtonGroupType;
+  /** Active/current cell — applies the hover background + darker text. */
+  active?: boolean;
+  /** Number or label text. */
+  children?: ReactNode;
+  /** Override the default arrow glyph. */
+  icon?: ReactNode;
+}
+
+const ArrowLeft = () => (
+  <svg viewBox="0 0 20 20" fill="none" className="size-5" aria-hidden>
+    <path d="M15.83 10H4.17M4.17 10l5 5M4.17 10l5-5" stroke="currentColor" strokeWidth="1.67" strokeLinecap="round" strokeLinejoin="round" />
+  </svg>
+);
+const ArrowRight = () => (
+  <svg viewBox="0 0 20 20" fill="none" className="size-5" aria-hidden>
+    <path d="M4.17 10h11.66M15.83 10l-5 5M15.83 10l-5-5" stroke="currentColor" strokeWidth="1.67" strokeLinecap="round" strokeLinejoin="round" />
+  </svg>
+);
+
+/**
+ * One cell of a button-group pagination bar (the bordered Page/Card-button-group
+ * style). `cellType` picks number / leading-icon (Previous) / trailing-icon
+ * (Next) / icon-only. Carries a right divider; `active` highlights it.
+ */
+export function PaginationButtonGroupBase({
+  cellType = "number",
+  active = false,
+  children,
+  icon,
+  className,
+  ...rest
+}: PaginationButtonGroupBaseProps) {
+  const isIcon = cellType === "iconOnly";
+  const isLeading = cellType === "leadingIcon";
+  const isTrailing = cellType === "trailingIcon";
+  const isNumber = cellType === "number";
+
+  return (
+    <button
+      type="button"
+      aria-current={active && isNumber ? "page" : undefined}
+      className={clsx(
+        "flex min-h-9 items-center justify-center border-r border-border-primary text-sm font-semibold outline-none transition-colors",
+        "focus-visible:relative focus-visible:z-10 focus-visible:ring-2 focus-visible:ring-utility-brand-500",
+        isNumber ? "min-w-9 p-md" : isIcon ? "p-md" : "gap-xs px-lg py-md",
+        active ? "bg-bg-primary-hover text-text-secondary-hover" : "bg-bg-primary hover:bg-bg-primary-hover",
+        isNumber && !active && "text-text-quaternary",
+        (isLeading || isTrailing) && "text-text-secondary",
+        className,
+      )}
+      {...rest}
+    >
+      {isLeading && (icon ?? <ArrowLeft />)}
+      {(isLeading || isTrailing) && <span className="px-xxs">{children ?? (isLeading ? "Previous" : "Next")}</span>}
+      {isTrailing && (icon ?? <ArrowRight />)}
+      {isNumber && children}
+      {isIcon && (icon ?? <ArrowRight />)}
+    </button>
+  );
+}

package/src/components/PaginationButtonGroupBase/index.ts

@@ -0,0 +1,5 @@
+export { PaginationButtonGroupBase } from "./PaginationButtonGroupBase";
+export type {
+  PaginationButtonGroupBaseProps,
+  PaginationButtonGroupType,
+} from "./PaginationButtonGroupBase";

package/src/components/PaginationCards/PaginationCards.tsx

@@ -0,0 +1,72 @@
+import { type HTMLAttributes } from "react";
+import clsx from "clsx";
+import { PaginationDotGroup } from "../PaginationDotGroup";
+
+export type PaginationCardsVariant = "default" | "minimal" | "advanced";
+
+export interface PaginationCardsProps extends HTMLAttributes<HTMLDivElement> {
+  page: number;
+  total: number;
+  onPageChange?: (page: number) => void;
+  /** default = arrows + dots · minimal = dots + "Page x of y" · advanced = bordered card. */
+  variant?: PaginationCardsVariant;
+}
+
+const ArrowBtn = ({ dir, disabled, onClick }: { dir: "left" | "right"; disabled: boolean; onClick: () => void }) => (
+  <button
+    type="button"
+    aria-label={dir === "left" ? "Previous" : "Next"}
+    disabled={disabled}
+    onClick={onClick}
+    className="flex size-9 items-center justify-center rounded-md border border-border-primary bg-bg-primary text-fg-secondary shadow-xs disabled:opacity-50"
+  >
+    <svg viewBox="0 0 20 20" fill="none" className="size-5" aria-hidden>
+      <path d={dir === "left" ? "M12.5 15l-5-5 5-5" : "M7.5 15l5-5-5-5"} stroke="currentColor" strokeWidth="1.67" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  </button>
+);
+
+/**
+ * Card/dot-based pagination. `default` = arrow buttons flanking a dot pager;
+ * `minimal` = dots + "Page x of y"; `advanced` = the same in a bordered card.
+ * Composes `PaginationDotGroup`.
+ */
+export function PaginationCards({
+  page,
+  total,
+  onPageChange,
+  variant = "default",
+  className,
+  ...rest
+}: PaginationCardsProps) {
+  const go = (p: number) => p >= 1 && p <= total && onPageChange?.(p);
+  const dots = <PaginationDotGroup count={total} current={page - 1} />;
+
+  const body =
+    variant === "minimal" ? (
+      <>
+        {dots}
+        <span className="text-sm font-medium text-text-secondary">Page {page} of {total}</span>
+      </>
+    ) : (
+      <>
+        <ArrowBtn dir="left" disabled={page <= 1} onClick={() => go(page - 1)} />
+        {dots}
+        <ArrowBtn dir="right" disabled={page >= total} onClick={() => go(page + 1)} />
+      </>
+    );
+
+  return (
+    <div
+      className={clsx(
+        "flex items-center gap-lg",
+        variant === "default" && "justify-between",
+        variant === "advanced" && "rounded-xl border border-border-secondary bg-bg-primary p-lg shadow-xs",
+        className,
+      )}
+      {...rest}
+    >
+      {body}
+    </div>
+  );
+}

package/src/components/PaginationCards/index.ts

@@ -0,0 +1,2 @@
+export { PaginationCards } from "./PaginationCards";
+export type { PaginationCardsProps, PaginationCardsVariant } from "./PaginationCards";

package/src/components/PaginationDotGroup/PaginationDotGroup.tsx

@@ -0,0 +1,66 @@
+import { type HTMLAttributes } from "react";
+import clsx from "clsx";
+import {
+  PaginationDotIndicator,
+  type PaginationDotSize,
+  type PaginationDotVariant,
+} from "../PaginationDotIndicator";
+
+export interface PaginationDotGroupProps
+  extends HTMLAttributes<HTMLDivElement> {
+  /** Total indicators. */
+  count?: number;
+  /** Active index. */
+  current?: number;
+  size?: PaginationDotSize;
+  variant?: PaginationDotVariant;
+  /** Floating pill on a translucent blurred background (carousel overlay). */
+  framed?: boolean;
+}
+
+/**
+ * Row of `PaginationDotIndicator`s (carousel pager). `count`/`current` drive the
+ * dots; `framed` wraps them in a blurred translucent pill for image overlays.
+ * Line variant stretches indicators to fill. framed uses the
+ * `alpha-white-90` token.
+ */
+export function PaginationDotGroup({
+  count = 3,
+  current = 0,
+  size = "md",
+  variant = "dot",
+  framed = false,
+  className,
+  ...rest
+}: PaginationDotGroupProps) {
+  const gap =
+    variant === "line"
+      ? size === "lg"
+        ? "gap-lg"
+        : "gap-md"
+      : size === "lg"
+        ? "gap-xl"
+        : "gap-lg";
+
+  return (
+    <div
+      className={clsx(
+        "flex items-center justify-center",
+        gap,
+        framed && "rounded-full bg-alpha-white-90 p-md backdrop-blur-sm",
+        className,
+      )}
+      {...rest}
+    >
+      {Array.from({ length: count }).map((_, i) => (
+        <PaginationDotIndicator
+          key={i}
+          current={i === current}
+          size={size}
+          variant={variant}
+          className={variant === "line" ? "h-1.5 min-w-0 flex-1" : undefined}
+        />
+      ))}
+    </div>
+  );
+}

package/src/components/PaginationDotGroup/index.ts

@@ -0,0 +1,2 @@
+export { PaginationDotGroup } from "./PaginationDotGroup";
+export type { PaginationDotGroupProps } from "./PaginationDotGroup";