@charcuterie/ui 4.7.1 → 4.9.0

package/src/ProgressCard/ProgressCard.mdx

@@ -0,0 +1,43 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+import * as ProgressCardStories from "./ProgressCard.stories";
+
+<Meta of={ProgressCardStories} />
+
+# ProgressCard
+
+A progress-first card with a large value over a filled band and distinct metric blocks.
+Use it for transfers, imports, backups, or other measurable work. `Card` owns the shell;
+`ProgressBar` owns clamping, the named ARIA widget, and indeterminate motion.
+
+<Canvas of={ProgressCardStories.Playground} />
+
+## Ownership
+
+The library owns layout, responsive typography, metric contrast, and whole-card intent.
+The app supplies identity, media, formatted values, actions, and meaningful issue text.
+Neither an absent diagnosis nor a numeric percentage implies a warning here.
+
+`intent` colors the entire card; `progressIntent` colors the fill independently.
+`valueText` is app-formatted text, while `value` and `max` drive measurable progress.
+Set `isIndeterminate` when progress cannot yet be measured and use a state such as
+"Preparing" for `valueText`. Set `isValueEmphasized={false}` for terminal state text.
+The band overlay stays outside the progressbar role so its content retains semantics.
+
+<Controls />
+
+## Layouts and states
+
+`band` is the default. `hierarchy` places the same headline above a thin progress track.
+Metrics stack when their own content area is narrow, even if media makes the whole card
+wide. The viewport does not decide this. Labels should be unique.
+
+<Canvas of={ProgressCardStories.AllVariants} />
+<Canvas of={ProgressCardStories.AllStates} />
+<Canvas of={ProgressCardStories.Responsive} />
+
+## App-owned controls
+
+Action slots use the same controls as the rest of the app. The card does not define cancel,
+retry, or confirmation policy. Additional issue details belong in `children`.
+
+<Canvas of={ProgressCardStories.Interactive} />

package/src/ProgressCard/ProgressCard.stories.tsx

@@ -0,0 +1,178 @@
+import { playgroundParameters } from "@charcuterie/storybook-config/story-parameters"
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import { intentArgType } from "../argTypes.storyHelpers.ts"
+import { Button } from "../Button/Button.tsx"
+import {
+  ContainerBoard,
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { ProgressCard } from "./ProgressCard.tsx"
+
+const metrics = [
+  { label: "Speed", value: "17.2 MB/s" },
+  { label: "Remaining", value: "9m" },
+  { label: "Finishes", value: "4:44 AM" },
+]
+
+const meta = {
+  title: "Components/Feedback/ProgressCard",
+  component: ProgressCard,
+  parameters: { layout: "padded" },
+  argTypes: {
+    intent: intentArgType,
+    progressIntent: intentArgType,
+  },
+  args: {
+    "aria-label": "Archive transfer",
+    header: "Archive transfer",
+    layout: "band",
+    metrics,
+    progressLabel: "Transfer progress",
+    status: "Transferring",
+    value: 82.5,
+    valueText: "82.5%",
+  },
+} satisfies Meta<typeof ProgressCard>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Playground: Story = {
+  parameters: playgroundParameters,
+}
+
+export const AllVariants: Story = {
+  render: (props) => (
+    <StoryGrid columns={2}>
+      {(["band", "hierarchy"] as const).map((layout) => (
+        <StoryCell
+          align="stretch"
+          key={layout}
+          label={layout}
+        >
+          <ProgressCard
+            {...props}
+            aria-label={`Transfer ${layout}`}
+            layout={layout}
+          />
+        </StoryCell>
+      ))}
+    </StoryGrid>
+  ),
+}
+
+export const AllStates: Story = {
+  render: (props) => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="Preparing">
+        <ProgressCard
+          {...props}
+          aria-label="Preparing transfer"
+          isIndeterminate
+          isValueEmphasized={false}
+          metrics={[]}
+          status={undefined}
+          valueText="Preparing"
+        />
+      </StoryCell>
+      <StoryCell align="stretch" label="Warning">
+        <ProgressCard
+          {...props}
+          aria-label="Transfer warning"
+          intent="warning"
+          progressIntent="warning"
+          status="Needs attention"
+        >
+          <p className="mt-2 text-intent-warning-content text-sm">
+            The source stopped responding.
+          </p>
+        </ProgressCard>
+      </StoryCell>
+      <StoryCell align="stretch" label="Failed">
+        <ProgressCard
+          {...props}
+          aria-label="Failed transfer"
+          intent="danger"
+          isValueEmphasized={false}
+          metrics={[]}
+          progressIntent="danger"
+          status={undefined}
+          valueText="Failed"
+        />
+      </StoryCell>
+      <StoryCell align="stretch" label="Complete">
+        <ProgressCard
+          {...props}
+          aria-label="Complete transfer"
+          isValueEmphasized={false}
+          metrics={[]}
+          progressIntent="success"
+          status={undefined}
+          value={100}
+          valueText="Complete"
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+export const Responsive: Story = {
+  render: (props) => (
+    <ContainerBoard>
+      {(width) => (
+        <ProgressCard
+          {...props}
+          aria-label={`Transfer at ${width}`}
+          header="ARCHIVE_TRANSFER_WITH_A_VERY_LONG_UNBROKEN_NAME"
+          media={
+            <span className="rounded-md bg-surface-sunken p-2">
+              07
+            </span>
+          }
+          actions={
+            <Button
+              appearance="outline"
+              intent="danger"
+              size="sm"
+            >
+              Cancel
+            </Button>
+          }
+        />
+      )}
+    </ContainerBoard>
+  ),
+}
+
+const ControlledProgressCard = () => {
+  const [isCanceled, setIsCanceled] = useState(false)
+  return (
+    <ProgressCard
+      aria-label="Cancelable transfer"
+      header="Archive transfer"
+      actions={
+        <Button
+          appearance="outline"
+          intent="danger"
+          isDisabled={isCanceled}
+          onClick={() => setIsCanceled(true)}
+        >
+          Cancel
+        </Button>
+      }
+      isValueEmphasized={!isCanceled}
+      metrics={isCanceled ? [] : metrics}
+      progressLabel="Transfer progress"
+      status={isCanceled ? undefined : "Transferring"}
+      value={82.5}
+      valueText={isCanceled ? "Canceled" : "82.5%"}
+    />
+  )
+}
+
+export const Interactive: Story = {
+  render: () => <ControlledProgressCard />,
+}

package/src/ProgressCard/ProgressCard.test.tsx

@@ -0,0 +1,118 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, within } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import {
+  DESKTOP,
+  setViewport,
+} from "../viewport.testHelpers.ts"
+import * as stories from "./ProgressCard.stories.tsx"
+
+const {
+  Playground,
+  AllVariants,
+  AllStates,
+  Responsive,
+  Interactive,
+} = composeStories(stories)
+
+test("the large value overlays a real named progressbar and the metrics stay outside it", async () => {
+  const { canvas } = await mountStory(Playground)
+  const card = expectAgentDrivable(canvas, {
+    role: "region",
+    name: "Archive transfer",
+  })
+  const bar = within(card).getByRole("progressbar", {
+    name: "Transfer progress",
+  })
+  const percentage = within(card).getByText("82.5%")
+  await expect(bar).toHaveAttribute("aria-valuenow", "82.5")
+  await expect(bar).not.toContainElement(percentage)
+  await expect(
+    bar.getBoundingClientRect().height,
+  ).toBeGreaterThan(50)
+  await expect(
+    bar.getBoundingClientRect().top,
+  ).toBeLessThan(percentage.getBoundingClientRect().top)
+  await expect(
+    within(card).getAllByRole("term"),
+  ).toHaveLength(3)
+})
+
+test("both layouts preserve progress semantics", async () => {
+  const { canvas } = await mountStory(AllVariants)
+  for (const layout of ["band", "hierarchy"]) {
+    const card = expectAgentDrivable(canvas, {
+      role: "region",
+      name: `Transfer ${layout}`,
+    })
+    await expect(
+      within(card).getByRole("progressbar"),
+    ).toHaveAttribute("aria-valuenow", "82.5")
+    await expect(
+      within(card).getByText("82.5%"),
+    ).toBeVisible()
+  }
+})
+
+test("issues tint the complete card and indeterminate progress has no invented value", async () => {
+  const { canvas } = await mountStory(AllStates)
+  const warning = expectAgentDrivable(canvas, {
+    role: "region",
+    name: "Transfer warning",
+  })
+  await expect(warning).toHaveClass(
+    "bg-intent-warning-surface",
+  )
+  await expect(
+    canvas.getByRole("region", { name: "Failed transfer" }),
+  ).toHaveClass("bg-intent-danger-surface")
+  const preparing = canvas.getByRole("region", {
+    name: "Preparing transfer",
+  })
+  await expect(
+    within(preparing).getByRole("progressbar"),
+  ).not.toHaveAttribute("aria-valuenow")
+  await expect(
+    within(preparing).queryByRole("term"),
+  ).not.toBeInTheDocument()
+})
+
+test("the card fits each container width with a long title, media, and actions", async () => {
+  await setViewport(DESKTOP)
+  const { canvas } = await mountStory(Responsive)
+  for (const width of ["15rem", "24rem", "34rem"]) {
+    const card = expectAgentDrivable(canvas, {
+      role: "region",
+      name: `Transfer at ${width}`,
+    })
+    await expect(card.scrollWidth).toBeLessThanOrEqual(
+      card.clientWidth,
+    )
+    const metrics = card.querySelector("dl") as HTMLElement
+    await expect(
+      getComputedStyle(metrics).gridTemplateColumns.split(
+        " ",
+      ),
+    ).toHaveLength(width === "34rem" ? 3 : 1)
+  }
+})
+
+test("the app action remains keyboard-operable above the progress band", async () => {
+  const { canvas } = await mountStory(Interactive)
+  const card = expectAgentDrivable(canvas, {
+    role: "region",
+    name: "Cancelable transfer",
+  })
+  const cancel = within(card).getByRole("button", {
+    name: "Cancel",
+  })
+  cancel.focus()
+  await userEvent.keyboard("{Enter}")
+  await expect(
+    within(card).getByText("Canceled"),
+  ).toBeVisible()
+  await expect(cancel).toBeDisabled()
+})

package/src/ProgressCard/ProgressCard.tsx

@@ -0,0 +1,152 @@
+import type { IntentName } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+
+import { Card, type CardProps } from "../Card/Card.tsx"
+import { INTENT_APPEARANCE_CLASS } from "../intentStyles.ts"
+import { ProgressBar } from "../ProgressBar/ProgressBar.tsx"
+import { toClassName } from "../toClassName.ts"
+
+export type ProgressCardMetric = {
+  label: string
+  value: ReactNode
+}
+
+export type ProgressCardLayout = "band" | "hierarchy"
+
+export type ProgressCardProps = Omit<
+  CardProps,
+  "heading" | "footer"
+> & {
+  "aria-label": string
+  /** App-owned identity: a title, an identifier, or a format mark. */
+  header: ReactNode
+  /** Whole-card intent is independent of the progress fill. */
+  intent?: IntentName
+  isIndeterminate?: boolean
+  isValueEmphasized?: boolean
+  layout?: ProgressCardLayout
+  max?: number
+  media?: ReactNode
+  metrics?: readonly ProgressCardMetric[]
+  progressIntent?: IntentName
+  progressLabel: string
+  status?: string
+  value?: number
+  /** App-formatted percentage or terminal state; never inferred from intent. */
+  valueText: string
+}
+
+/** A progress-first card. The app owns state, formatting, actions, and diagnosis. */
+export const ProgressCard = ({
+  actions,
+  children,
+  className,
+  header,
+  intent = "neutral",
+  isIndeterminate = false,
+  isValueEmphasized = true,
+  layout = "band",
+  max,
+  media,
+  metrics = [],
+  progressIntent = "accent",
+  progressLabel,
+  status,
+  value,
+  valueText,
+  ...cardProps
+}: ProgressCardProps): ReactNode => {
+  const headline = (
+    <div
+      className={toClassName(
+        "relative flex flex-wrap items-end justify-between gap-2",
+        layout === "band" ? "p-3" : "mb-3",
+      )}
+    >
+      {status ? (
+        <span className="min-w-0 wrap-anywhere font-medium text-content-secondary text-sm">
+          {status}
+        </span>
+      ) : null}
+      <span
+        className={toClassName(
+          "min-w-0 wrap-anywhere text-end tabular-nums",
+          isValueEmphasized
+            ? "font-bold text-4xl leading-none tracking-tight cq-sm:text-[3.25rem]"
+            : "font-semibold text-xl",
+        )}
+      >
+        {valueText}
+      </span>
+    </div>
+  )
+
+  return (
+    <Card
+      {...cardProps}
+      className={toClassName(
+        "relative rounded-2xl",
+        intent === "neutral"
+          ? undefined
+          : INTENT_APPEARANCE_CLASS[intent].soft,
+        "text-content-primary",
+        className,
+      )}
+    >
+      <div className="flex gap-3.5">
+        {media ? (
+          <div className="flex shrink-0 flex-col items-start gap-2">
+            {media}
+          </div>
+        ) : null}
+        <div className="min-w-0 flex-1">
+          <div className="flex flex-wrap items-start justify-between gap-3">
+            <div className="min-w-0 flex-1 basis-40 wrap-anywhere">
+              {header}
+            </div>
+            {actions ? (
+              <div className="relative z-10 flex flex-wrap items-center gap-2">
+                {actions}
+              </div>
+            ) : null}
+          </div>
+          <div className="mt-5">
+            {layout === "hierarchy" ? headline : null}
+            <ProgressBar
+              intent={progressIntent}
+              isIndeterminate={isIndeterminate}
+              label={progressLabel}
+              max={max}
+              overlay={
+                layout === "band" ? headline : undefined
+              }
+              value={value}
+            />
+          </div>
+          {metrics.length > 0 ? (
+            <div className="@container">
+              <dl className="mt-3 grid grid-cols-1 gap-2 cq-sm:grid-cols-3">
+                {metrics.map(
+                  ({ label, value: metricValue }) => (
+                    <div
+                      className="flex items-baseline justify-between gap-2 rounded-lg border border-border-subtle bg-surface-sunken/70 px-2.5 py-2 cq-sm:block"
+                      key={label}
+                    >
+                      <dt className="min-w-0 wrap-anywhere font-semibold text-content-muted text-xs uppercase tracking-wide">
+                        {label}
+                      </dt>
+                      <dd className="m-0 min-w-0 wrap-anywhere font-semibold text-lg tabular-nums cq-sm:mt-1">
+                        {metricValue ?? "—"}
+                      </dd>
+                    </div>
+                  ),
+                )}
+              </dl>
+            </div>
+          ) : null}
+          {children}
+        </div>
+      </div>
+    </Card>
+  )
+}

package/src/index.ts

@@ -334,6 +334,12 @@ export type {
   NavBarProps,
 } from "./NavBar/NavBar.tsx"
 export { NavBar } from "./NavBar/NavBar.tsx"
+/**
+ * What a `Menu` in anchor mode hangs off: an element, or a virtual
+ * one that is only a rectangle. A context menu passes the second,
+ * holding the point that was pressed.
+ */
+export type { AnchoredOverlayAnchor } from "./Overlay/useAnchoredOverlay.ts"
 export type {
   PickerOption,
   PickerProps,
@@ -358,6 +364,12 @@ export {
   toProgressPercent,
   toProgressValue,
 } from "./ProgressBar/progressValue.ts"
+export type {
+  ProgressCardLayout,
+  ProgressCardMetric,
+  ProgressCardProps,
+} from "./ProgressCard/ProgressCard.tsx"
+export { ProgressCard } from "./ProgressCard/ProgressCard.tsx"
 export type {
   QueryBuilderLabels,
   QueryBuilderProps,

package/src/sourceRules.test.ts

@@ -251,6 +251,8 @@ test("a container-query component is never storied in a shrink-to-fit cell", ()
     // answer neither, because a track is about the same width in
     // both.
     "PortraitTiles",
+    // Metrics query the space remaining beside the media, not the entire card.
+    "ProgressCard",
     // `Stepper`'s container is the one that decides whether a
     // `horizontal` sequence is actually horizontal. Below `--cq-md`
     // it falls back to the vertical column, because four steps side
@@ -612,7 +614,8 @@ test("the barrel is the only place components are re-exported", async () => {
   // consumer deciding whether an item is on screen must ask the
   // question the same way the bars are placed, or the two answers
   // drift by a day and nothing says so.
-  expect(componentNames.length).toBe(66)
+  // ProgressCard composes Card and ProgressBar for progress-first dashboards.
+  expect(componentNames.length).toBe(67)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)