// ~/src/siteplane/components/featured-card/featured-card.tsx "use client"; import * as React from "react"; import { useSiteplaneMessages } from "../../system/locale/messages-context"; import { cn } from "../../system/utils/cn"; import { moveFocusPast } from "../../system/utils/focus-target-after"; import { Button, CloseButton } from "../button"; import { Card, CardPanel } from "../card"; import { Progress, ProgressCircle, ProgressCircleValue } from "../progress"; import "./featured-card.css"; /** * How the card shows its progress: `bar`, a progress bar under the text, or * `circle`, a 64 px ring with the figure in it above the text. */ export type FeaturedCardIndicator = "bar" | "circle"; export interface FeaturedCardProps extends Omit< React.ComponentProps<"div">, "children" | "title" > { /** The card's title, one short line such as "Used space". */ title: React.ReactNode; /** The text under the title. */ description?: React.ReactNode; /** * The completion between 0 and 100. The card shows it as a bar or a ring * (`indicator`); without it the card shows its text and actions only. */ progress?: number | undefined; /** `bar`, the default, or `circle`. */ indicator?: FeaturedCardIndicator | undefined; /** * The accessible name of the progress indicator. The title, when it is * plain text, by default. */ progressLabel?: string | undefined; /** The label of the action that takes the offer, such as "Upgrade plan". */ confirmLabel?: React.ReactNode; /** Called by the confirm action. */ onConfirm?: (() => void) | undefined; /** * Called by the close button in the corner and by the dismiss action. The * card shows neither without it; removing the card is the application's. */ onDismiss?: (() => void) | undefined; /** The label of the dismiss action: the `featuredCard.dismiss` message by default, "Dismiss" in English. */ dismissLabel?: React.ReactNode; /** The accessible name of the close button: CloseButton's message by default, "Close" in English. */ closeLabel?: string | undefined; } /** * A compact card that features one offer or status in a sidebar or a panel, * such as the storage a team has used: a title and a description, a progress * bar under them or a 64 px ring above them, a close button in the corner and * a pair of link actions, Dismiss and the offer's own. It is a Card with its * compact inset, so it takes the Card's surface and the Card's inset tokens. */ export function FeaturedCard({ className, closeLabel, confirmLabel, description, dismissLabel: dismissLabelProp, indicator = "bar", onConfirm, onDismiss, progress, progressLabel, title, ...props }: FeaturedCardProps): React.ReactElement { const messages = useSiteplaneMessages("featuredCard"); const dismissLabel = dismissLabelProp === undefined ? messages.dismiss : dismissLabelProp; const hasProgress = typeof progress === "number" && Number.isFinite(progress); const value = hasProgress ? Math.min(100, Math.max(0, progress)) : null; const indicatorLabel = progressLabel ?? (typeof title === "string" || typeof title === "number" ? String(title) : undefined); const hasConfirm = confirmLabel !== undefined && confirmLabel !== null && confirmLabel !== ""; // A dismiss that holds the focus hands it to the next element after the // card before the card leaves, as the close of an Alert and of a // Notification does, so the focus never falls back to the page (B4). const dismiss = onDismiss ? (event: React.MouseEvent) => { moveFocusPast( event.currentTarget.closest(".sp-featured-card"), ); onDismiss(); } : undefined; // The close sits 4 px inside the top-end corner, over the card's inset; the // title keeps clear of it (featured-card.css). It is the card's last part // in the document, so the keyboard reaches it after the actions, as the // close of a Dialog, a Notification and an Alert (B16, 3 November 2026; it // followed the text, before the links). const close = dismiss ? ( ) : null; const text = (

{title}

{description === undefined || description === null || description === "" ? null : (
{description}
)}
); return ( {value !== null && indicator === "circle" ? ( // The ring leads, 12 px above the text, with its figure inside.
{text}
) : ( text )} {value !== null && indicator === "bar" ? ( ) : null} {dismiss || hasConfirm ? (
{dismiss ? ( ) : null} {hasConfirm ? ( ) : null}
) : null} {close}
); } // ~/src/siteplane/components/featured-card/featured-card.css @layer theme, base, components, siteplane, utilities; @layer siteplane { /* A featured card is a Card with its compact 16 px inset: * its parts stack 16 px apart in the Card's panel, the text * (or the ring with the text under it) first, then a progress bar, then the * actions. */ :where(.sp-featured-card > .sp-card-panel) { display: flex; flex-direction: column; gap: var(--sp-rw-space-4); } /* The 64 px ring leads the text, 12 px above it, at the start of the card. */ :where(.sp-featured-card-lead) { display: flex; flex-direction: column; align-items: flex-start; gap: var(--sp-rw-space-3); } /* The title over its description, 4 px apart. */ :where(.sp-featured-card-text) { display: flex; min-width: 0; flex-direction: column; gap: var(--sp-rw-space-1); } /* The title takes the label role, the small title of a toast or a list; the * description is body text in the tertiary colour. Both are 14 px on a * 20 px line, and long values wrap (rulebook K5). */ :where(.sp-featured-card-title) { margin: 0; color: var(--sp-rw-fg-primary); font-size: var(--sp-rw-font-14); font-weight: var(--sp-rw-font-weight-label); line-height: var(--sp-rw-line-20); overflow-wrap: anywhere; } :where(.sp-featured-card-description) { color: var(--sp-rw-fg-tertiary); font-size: var(--sp-rw-font-14); font-weight: var(--sp-rw-font-weight-default); line-height: var(--sp-rw-line-20); overflow-wrap: anywhere; } /* A title that leads the card ends before the close button in the corner: * the close is a 36 px square 4 px inside the corner, so it reaches that far * past the card's inset into the title's line. Under a ring the title * starts below the close and keeps its whole line. */ :where( .sp-featured-card[data-dismissible] > .sp-card-panel > .sp-featured-card-text > .sp-featured-card-title ) { padding-inline-end: max( 0px, calc( var(--sp-rw-control-sm) + var(--sp-rw-space-1) - var(--card-part-inset-inline, var(--sp-rw-space-4)) ) ); } /* The link actions, Dismiss and the offer's own, the action gap apart. */ :where(.sp-featured-card-actions) { display: flex; flex-wrap: wrap; align-items: center; gap: var(--sp-rw-action-gap); } } // ~/src/siteplane/components/featured-card/index.ts export * from "./featured-card";