{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"featured-card","title":"Featured Card","description":"Feature one offer or status in a sidebar or a panel, such as the storage a team has used, with its progress and a pair of link actions. Search terms: upgrade card, usage card, storage card, sidebar card, promo card.","dependencies":[],"registryDependencies":["@siteplane/base","@siteplane/card","@siteplane/button","@siteplane/progress"],"files":[{"path":"packages/ui/src/components/featured-card/featured-card.tsx","content":"\"use client\";\n\nimport * as React from \"react\";\n\nimport { useSiteplaneMessages } from \"../../system/locale/messages-context\";\nimport { cn } from \"../../system/utils/cn\";\nimport { moveFocusPast } from \"../../system/utils/focus-target-after\";\nimport { Button, CloseButton } from \"../button\";\nimport { Card, CardPanel } from \"../card\";\nimport { Progress, ProgressCircle, ProgressCircleValue } from \"../progress\";\n\nimport \"./featured-card.css\";\n\n/**\n * How the card shows its progress: `bar`, a progress bar under the text, or\n * `circle`, a 64 px ring with the figure in it above the text.\n */\nexport type FeaturedCardIndicator = \"bar\" | \"circle\";\n\nexport interface FeaturedCardProps extends Omit<\n  React.ComponentProps<\"div\">,\n  \"children\" | \"title\"\n> {\n  /** The card's title, one short line such as \"Used space\". */\n  title: React.ReactNode;\n  /** The text under the title. */\n  description?: React.ReactNode;\n  /**\n   * The completion between 0 and 100. The card shows it as a bar or a ring\n   * (`indicator`); without it the card shows its text and actions only.\n   */\n  progress?: number | undefined;\n  /** `bar`, the default, or `circle`. */\n  indicator?: FeaturedCardIndicator | undefined;\n  /**\n   * The accessible name of the progress indicator. The title, when it is\n   * plain text, by default.\n   */\n  progressLabel?: string | undefined;\n  /** The label of the action that takes the offer, such as \"Upgrade plan\". */\n  confirmLabel?: React.ReactNode;\n  /** Called by the confirm action. */\n  onConfirm?: (() => void) | undefined;\n  /**\n   * Called by the close button in the corner and by the dismiss action. The\n   * card shows neither without it; removing the card is the application's.\n   */\n  onDismiss?: (() => void) | undefined;\n  /** The label of the dismiss action: the `featuredCard.dismiss` message by default, \"Dismiss\" in English. */\n  dismissLabel?: React.ReactNode;\n  /** The accessible name of the close button: CloseButton's message by default, \"Close\" in English. */\n  closeLabel?: string | undefined;\n}\n\n/**\n * A compact card that features one offer or status in a sidebar or a panel,\n * such as the storage a team has used: a title and a description, a progress\n * bar under them or a 64 px ring above them, a close button in the corner and\n * a pair of link actions, Dismiss and the offer's own. It is a Card with its\n * compact inset, so it takes the Card's surface and the Card's inset tokens.\n */\nexport function FeaturedCard({\n  className,\n  closeLabel,\n  confirmLabel,\n  description,\n  dismissLabel: dismissLabelProp,\n  indicator = \"bar\",\n  onConfirm,\n  onDismiss,\n  progress,\n  progressLabel,\n  title,\n  ...props\n}: FeaturedCardProps): React.ReactElement {\n  const messages = useSiteplaneMessages(\"featuredCard\");\n  const dismissLabel =\n    dismissLabelProp === undefined ? messages.dismiss : dismissLabelProp;\n  const hasProgress = typeof progress === \"number\" && Number.isFinite(progress);\n  const value = hasProgress ? Math.min(100, Math.max(0, progress)) : null;\n  const indicatorLabel =\n    progressLabel ??\n    (typeof title === \"string\" || typeof title === \"number\"\n      ? String(title)\n      : undefined);\n  const hasConfirm =\n    confirmLabel !== undefined && confirmLabel !== null && confirmLabel !== \"\";\n  // A dismiss that holds the focus hands it to the next element after the\n  // card before the card leaves, as the close of an Alert and of a\n  // Notification does, so the focus never falls back to the page (B4).\n  const dismiss = onDismiss\n    ? (event: React.MouseEvent<HTMLElement>) => {\n        moveFocusPast(\n          event.currentTarget.closest<HTMLElement>(\".sp-featured-card\"),\n        );\n        onDismiss();\n      }\n    : undefined;\n  // The close sits 4 px inside the top-end corner, over the card's inset; the\n  // title keeps clear of it (featured-card.css). It is the card's last part\n  // in the document, so the keyboard reaches it after the actions, as the\n  // close of a Dialog, a Notification and an Alert (B16, 3 November 2026; it\n  // followed the text, before the links).\n  const close = dismiss ? (\n    <CloseButton\n      className=\"absolute end-1 top-1\"\n      label={closeLabel}\n      onClick={dismiss}\n    />\n  ) : null;\n  const text = (\n    <div className=\"sp-featured-card-text\" data-slot=\"featured-card-text\">\n      <p className=\"sp-featured-card-title\" data-slot=\"featured-card-title\">\n        {title}\n      </p>\n      {description === undefined ||\n      description === null ||\n      description === \"\" ? null : (\n        <div\n          className=\"sp-featured-card-description\"\n          data-slot=\"featured-card-description\"\n        >\n          {description}\n        </div>\n      )}\n    </div>\n  );\n  return (\n    <Card\n      className={cn(\"sp-featured-card\", className)}\n      data-dismissible={onDismiss ? \"\" : undefined}\n      data-indicator={value === null ? undefined : indicator}\n      density=\"compact\"\n      {...props}\n    >\n      <CardPanel>\n        {value !== null && indicator === \"circle\" ? (\n          // The ring leads, 12 px above the text, with its figure inside.\n          <div className=\"sp-featured-card-lead\" data-slot=\"featured-card-lead\">\n            <ProgressCircle\n              aria-label={indicatorLabel}\n              display=\"xxs\"\n              value={value}\n            >\n              <ProgressCircleValue />\n            </ProgressCircle>\n            {text}\n          </div>\n        ) : (\n          text\n        )}\n        {value !== null && indicator === \"bar\" ? (\n          <Progress aria-label={indicatorLabel} value={value} />\n        ) : null}\n        {dismiss || hasConfirm ? (\n          <div\n            className=\"sp-featured-card-actions\"\n            data-slot=\"featured-card-actions\"\n          >\n            {dismiss ? (\n              <Button onClick={dismiss} variant=\"link\">\n                {dismissLabel}\n              </Button>\n            ) : null}\n            {hasConfirm ? (\n              <Button onClick={onConfirm} variant=\"link-accent\">\n                {confirmLabel}\n              </Button>\n            ) : null}\n          </div>\n        ) : null}\n        {close}\n      </CardPanel>\n    </Card>\n  );\n}\n","type":"registry:ui","target":"~/src/siteplane/components/featured-card/featured-card.tsx"},{"path":"packages/ui/src/components/featured-card/featured-card.css","content":"@layer theme, base, components, siteplane, utilities;\n\n@layer siteplane {\n  /* A featured card is a Card with its compact 16 px inset:\n   * its parts stack 16 px apart in the Card's panel, the text\n   * (or the ring with the text under it) first, then a progress bar, then the\n   * actions. */\n  :where(.sp-featured-card > .sp-card-panel) {\n    display: flex;\n    flex-direction: column;\n    gap: var(--sp-rw-space-4);\n  }\n\n  /* The 64 px ring leads the text, 12 px above it, at the start of the card. */\n  :where(.sp-featured-card-lead) {\n    display: flex;\n    flex-direction: column;\n    align-items: flex-start;\n    gap: var(--sp-rw-space-3);\n  }\n\n  /* The title over its description, 4 px apart. */\n  :where(.sp-featured-card-text) {\n    display: flex;\n    min-width: 0;\n    flex-direction: column;\n    gap: var(--sp-rw-space-1);\n  }\n\n  /* The title takes the label role, the small title of a toast or a list; the\n   * description is body text in the tertiary colour. Both are 14 px on a\n   * 20 px line, and long values wrap (rulebook K5). */\n  :where(.sp-featured-card-title) {\n    margin: 0;\n    color: var(--sp-rw-fg-primary);\n    font-size: var(--sp-rw-font-14);\n    font-weight: var(--sp-rw-font-weight-label);\n    line-height: var(--sp-rw-line-20);\n    overflow-wrap: anywhere;\n  }\n\n  :where(.sp-featured-card-description) {\n    color: var(--sp-rw-fg-tertiary);\n    font-size: var(--sp-rw-font-14);\n    font-weight: var(--sp-rw-font-weight-default);\n    line-height: var(--sp-rw-line-20);\n    overflow-wrap: anywhere;\n  }\n\n  /* A title that leads the card ends before the close button in the corner:\n   * the close is a 36 px square 4 px inside the corner, so it reaches that far\n   * past the card's inset into the title's line. Under a ring the title\n   * starts below the close and keeps its whole line. */\n  :where(\n    .sp-featured-card[data-dismissible]\n      > .sp-card-panel\n      > .sp-featured-card-text\n      > .sp-featured-card-title\n  ) {\n    padding-inline-end: max(\n      0px,\n      calc(\n        var(--sp-rw-control-sm) + var(--sp-rw-space-1) -\n          var(--card-part-inset-inline, var(--sp-rw-space-4))\n      )\n    );\n  }\n\n  /* The link actions, Dismiss and the offer's own, the action gap apart. */\n  :where(.sp-featured-card-actions) {\n    display: flex;\n    flex-wrap: wrap;\n    align-items: center;\n    gap: var(--sp-rw-action-gap);\n  }\n}\n","type":"registry:ui","target":"~/src/siteplane/components/featured-card/featured-card.css"},{"path":"packages/ui/src/components/featured-card/index.ts","content":"export * from \"./featured-card\";\n","type":"registry:ui","target":"~/src/siteplane/components/featured-card/index.ts"}],"type":"registry:ui","docs":"https://ui.siteplane.io/docs-markdown/components/featured-card.md","categories":["Navigation"],"meta":{"avoidWhen":["Avoid for a message that concerns the whole page or follows an action; use Alert or Toast.","Avoid for several offers at once; show the one that matters most."],"description":"Feature one offer or status in a sidebar or a panel, such as the storage a team has used, with its progress and a pair of link actions.","knownLimitations":["The card does not remove itself: remove it in onDismiss and keep the choice where it should last.","The title is a paragraph, not a heading, so the card adds nothing to the document outline."],"providerNotes":[],"releaseStatus":"preview","searchTerms":["featured card","upgrade card","usage card","storage card","sidebar card","promo card"],"useWhen":["Use in the footer of a sidebar or beside a settings page for one offer or status people can act on, such as storage that runs out.","Use indicator circle when the figure matters most, such as the share of a quota that is used."]}}