@charcuterie/ui 3.9.0 → 3.11.0

package/src/Card/Card.test.tsx

@@ -6,7 +6,7 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Card.stories.tsx"
 
-const { AllStates, Default, Interactive } =
+const { AccentEdge, AllStates, Default, Interactive } =
   composeStories(stories)
 
 test("a heading turns the card into a named landmark", async () => {
@@ -54,3 +54,94 @@ test("region scoping disambiguates two identical buttons", async () => {
     }),
   ).toHaveAttribute("aria-valuenow", "40")
 })
+
+/**
+ * The bar overlays the entire card, links and buttons included, so
+ * `pointer-events: none` on it is the difference between a card you
+ * can use and one that swallows every click. Driven, not asserted
+ * off a class name — the class is what the fix looks like, and this
+ * is what it is for.
+ */
+test("the accent edge does not swallow a click", async () => {
+  const { canvas } = await mountStory(AccentEdge)
+
+  const open = expectAgentDrivable(canvas, {
+    name: "Open",
+    role: "button",
+  })
+
+  let isClicked = false
+
+  open.addEventListener("click", () => {
+    isClicked = true
+  })
+
+  open.click()
+
+  await expect(isClicked).toBe(true)
+})
+
+const readRadius = (card: Element, isBar: boolean) =>
+  globalThis.getComputedStyle(
+    card,
+    isBar ? "::before" : undefined,
+  ).borderTopLeftRadius
+
+/**
+ * The radius is INHERITED rather than restated, which is what lets
+ * one treatment sit on `rounded-lg`, on `rounded-3xl`, and on
+ * whatever an app overrides it to. Computed styles, because a class
+ * name is the thing that can be right while the paint is wrong.
+ */
+test("the bar takes the card's own radius, whatever it is", async () => {
+  const { canvas } = await mountStory(AccentEdge)
+
+  const wider = expectAgentDrivable(canvas, {
+    name: "A wider radius",
+    role: "region",
+  })
+
+  const stock = expectAgentDrivable(canvas, {
+    name: "Project 1",
+    role: "region",
+  })
+
+  await expect(readRadius(wider, true)).toBe(
+    readRadius(wider, false),
+  )
+  await expect(readRadius(stock, true)).toBe(
+    readRadius(stock, false),
+  )
+
+  // And the two cards genuinely differ, or the assertions above
+  // would pass on a component that hardcoded one radius.
+  await expect(readRadius(wider, false)).not.toBe(
+    readRadius(stock, false),
+  )
+})
+
+/**
+ * `Card` carries `shadow-low`. The accent edge is a second shadow,
+ * and the first version of this fix wrote it onto the card itself —
+ * where an unlayered rule outranks the utility and the elevation
+ * silently goes away.
+ */
+test("the accent edge leaves the card's elevation alone", async () => {
+  const { canvas } = await mountStory(AccentEdge)
+
+  const card = expectAgentDrivable(canvas, {
+    name: "Project 1",
+    role: "region",
+  })
+
+  const cardShadow =
+    globalThis.getComputedStyle(card).boxShadow
+  const barShadow = globalThis.getComputedStyle(
+    card,
+    "::before",
+  ).boxShadow
+
+  await expect(cardShadow).not.toBe("none")
+  await expect(cardShadow).not.toContain("inset")
+  await expect(barShadow).toContain("inset")
+})

package/src/Card/Card.tsx

@@ -9,6 +9,11 @@ import type {
 } from "react"
 
 import { toClassName } from "../toClassName.ts"
+import type { CardAccentEdge } from "./cardAccentEdge.ts"
+import {
+  getAccentEdgeClassName,
+  getAccentEdgeStyle,
+} from "./cardAccentEdge.ts"
 
 export type CardSurface = Extract<
   SurfaceRole,
@@ -18,6 +23,16 @@ export type CardSurface = Extract<
 export type CardPadding = "lg" | "md" | "none" | "sm"
 
 export type CardProps = ComponentPropsWithRef<"section"> & {
+  /**
+   * A coloured bar down the leading edge, following the card's own
+   * corners.
+   *
+   * `{ categorical: 3 }` for a colour a user picked; `{ color }`
+   * for one an app computed — a hue hashed from a repo's name, say,
+   * where ten indices are not enough. See `cardAccentEdge.ts` for
+   * why it is a pseudo-element and not a border.
+   */
+  accentEdge?: CardAccentEdge
   /** Buttons or a badge, laid out beside the heading. */
   actions?: ReactNode
   elevation?: ElevationStep
@@ -79,6 +94,7 @@ const PADDING_CLASS: Record<CardPadding, string> = {
  * a layout fact rather than a density one.
  */
 export const Card = ({
+  accentEdge,
   actions,
   children,
   className,
@@ -87,11 +103,25 @@ export const Card = ({
   heading,
   headingLevel = 2,
   padding = "md",
+  style,
   surface = "raised",
   ...sectionProps
 }: CardProps): ReactNode => {
   const headingId = useUniqueId()
 
+  // The caller's own `style` wins. An accent colour is one custom
+  // property, and silently dropping whatever else the call site set
+  // would be a worse trade than letting it override this one.
+  const accentEdgeStyle =
+    accentEdge == null
+      ? undefined
+      : getAccentEdgeStyle(accentEdge)
+
+  const mergedStyle =
+    accentEdgeStyle == null
+      ? style
+      : { ...accentEdgeStyle, ...style }
+
   const Heading = `h${headingLevel}` as const
 
   return (
@@ -108,8 +138,12 @@ export const Card = ({
         SURFACE_CLASS[surface],
         ELEVATION_CLASS[elevation],
         PADDING_CLASS[padding],
+        accentEdge == null
+          ? undefined
+          : getAccentEdgeClassName(accentEdge),
         className,
       )}
+      style={mergedStyle}
     >
       {heading || actions ? (
         <header className="flex flex-col gap-2 cq-sm:flex-row cq-sm:items-start cq-sm:justify-between">

package/src/Card/cardAccentEdge.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "vitest"
+
+import {
+  ACCENT_EDGE_BASE_CLASS,
+  ACCENT_EDGE_CATEGORICAL_CLASS,
+  ACCENT_EDGE_COLOR_CLASS,
+  ACCENT_EDGE_COLOR_PROPERTY,
+  getAccentEdgeClassName,
+  getAccentEdgeStyle,
+} from "./cardAccentEdge.ts"
+
+describe("getAccentEdgeClassName", () => {
+  test("reads a categorical index off the ten-wide family", () => {
+    const className = getAccentEdgeClassName({
+      categorical: 3,
+    })
+
+    expect(className).toContain(ACCENT_EDGE_BASE_CLASS)
+    expect(className).toContain(
+      ACCENT_EDGE_CATEGORICAL_CLASS[3],
+    )
+  })
+
+  test("threads an app's own colour through one literal", () => {
+    const className = getAccentEdgeClassName({
+      color: "hsl(210 55% 52%)",
+    })
+
+    expect(className).toContain(ACCENT_EDGE_BASE_CLASS)
+    expect(className).toContain(ACCENT_EDGE_COLOR_CLASS)
+  })
+
+  /**
+   * The bar overlays the whole card, links and buttons included, so
+   * this is the difference between a card you can click and one you
+   * cannot.
+   */
+  test("never eats a pointer", () => {
+    expect(
+      getAccentEdgeClassName({ categorical: 1 }),
+    ).toContain("before:pointer-events-none")
+  })
+
+  /**
+   * The card already has a radius; the bar must not restate it.
+   * `inherit` is what makes one component work on `rounded-lg`,
+   * `rounded-xl` and whatever an app overrides it to.
+   */
+  test("takes the card's own radius rather than naming one", () => {
+    expect(
+      getAccentEdgeClassName({ categorical: 1 }),
+    ).toContain("before:rounded-[inherit]")
+  })
+
+  /**
+   * `box-shadow` has no logical form. Without the `rtl:` twin the
+   * bar sits on the left of an Arabic page, which is the trailing
+   * edge there.
+   */
+  test("carries the bar to the other side under rtl", () => {
+    for (const className of [
+      ...Object.values(ACCENT_EDGE_CATEGORICAL_CLASS),
+      ACCENT_EDGE_COLOR_CLASS,
+    ]) {
+      expect(className).toContain("rtl:before:shadow-")
+      expect(className).toContain("inset_-3px")
+    }
+  })
+
+  /**
+   * Tailwind scans source text for COMPLETE class strings, so an
+   * interpolated index generates nothing, paints nothing and
+   * reports nothing. This is the cheap half of that guarantee;
+   * `tailwindCandidates.test.ts` is the half that compiles them.
+   */
+  test("names every categorical index in full", () => {
+    for (const [index, className] of Object.entries(
+      ACCENT_EDGE_CATEGORICAL_CLASS,
+    )) {
+      expect(className).toContain(
+        `var(--color-categorical-${index}-solid)`,
+      )
+    }
+  })
+})
+
+describe("getAccentEdgeStyle", () => {
+  test("writes one custom property for an app's own colour", () => {
+    expect(
+      getAccentEdgeStyle({ color: "hsl(210 55% 52%)" }),
+    ).toStrictEqual({
+      [ACCENT_EDGE_COLOR_PROPERTY]: "hsl(210 55% 52%)",
+    })
+  })
+
+  /**
+   * `undefined`, not `{}`, so a categorical card renders no `style`
+   * attribute at all.
+   */
+  test("writes nothing when the colour came from an index", () => {
+    expect(
+      getAccentEdgeStyle({ categorical: 7 }),
+    ).toBeUndefined()
+  })
+})

package/src/Card/cardAccentEdge.ts

@@ -0,0 +1,135 @@
+/**
+ * A coloured bar down a card's leading edge — and the reason it is
+ * a pseudo-element rather than a border.
+ *
+ * Three apps had grown this shape independently and all three drew
+ * it as a straight border beside a rounded box, so the bar ran past
+ * the curve and stopped square while the card it belonged to was
+ * round. Folio put `border-inline-start` on a WRAPPER around the
+ * card; mail-sifter puts `borderInlineStartWidth: 4` on a
+ * `rounded-xl` anchor; spoolbuddy writes `rounded-lg border-l-3`.
+ * A border is painted on the border box, so none of them can follow
+ * a corner — the notch is not a bug in any one app, it is what that
+ * technique does.
+ *
+ * A pseudo-element overlays the card and takes
+ * `border-radius: inherit`, so the bar follows whatever radius the
+ * card already has and nobody states a radius twice.
+ *
+ * ⚠️ **The shadow goes on the pseudo-element, never on the card.**
+ * `Card` carries `shadow-low` from the elevation scale, and an app
+ * stylesheet is unlayered while Tailwind's utilities sit in
+ * `@layer utilities` — so a `box-shadow` written at the call site
+ * outranks the utility and takes the card's elevation away with it.
+ * That is not hypothetical; it is the version of this fix that was
+ * written first.
+ *
+ * ⚠️ **Not a 3px-wide pseudo-element with a rounded leading edge.**
+ * A `border-radius` of `0.5rem` on a 3px-wide box is clamped by the
+ * browser to fit, so it caps the bar instead of following the
+ * card's curve.
+ *
+ * ⚠️ **`box-shadow` has no logical form**, so the offset is
+ * physical and the `rtl:` variant is what carries the bar to the
+ * other side. A single `inset 3px` would put it on the left of an
+ * Arabic page, which is the trailing edge there.
+ */
+
+import type { CategoricalIndex } from "@charcuterie/tokens"
+
+/**
+ * Which colour the bar takes.
+ *
+ * Two arms, because the fleet has two answers and neither is wrong.
+ * Docket picks a **categorical index** — a colour a user chose for
+ * a project, from the ten-wide contrast-audited family. Folio and
+ * mail-sifter derive a **hue from a name hash**, so a repo added
+ * tomorrow already has a colour and nobody maintains a palette;
+ * that is 360 answers, not ten, and it cannot be an index.
+ *
+ * `intent` is deliberately absent. An intent is a claim the design
+ * system makes — `danger` says what happens if you press the thing
+ * — and no card in this fleet wants its edge to make one. When one
+ * does, that is a third arm and a decision record, not a guess
+ * made here.
+ */
+export type CardAccentEdge =
+  | { categorical: CategoricalIndex; color?: never }
+  | { categorical?: never; color: string }
+
+/**
+ * The custom property an explicit colour is threaded through.
+ *
+ * A property rather than an inline `box-shadow`, because the shadow
+ * string has to stay a COMPLETE literal in the source for Tailwind
+ * to generate it at all. One literal reading one variable covers
+ * every colour an app can compute; interpolating the colour into
+ * the class name would generate nothing, paint nothing, and report
+ * nothing.
+ */
+export const ACCENT_EDGE_COLOR_PROPERTY =
+  "--charcuterie-accent-edge"
+
+/**
+ * The overlay itself. Colour arrives separately.
+ *
+ * `pointer-events: none` is load-bearing rather than tidy: this box
+ * covers the whole card, including every link and button in it.
+ */
+export const ACCENT_EDGE_BASE_CLASS =
+  "relative before:pointer-events-none before:absolute before:inset-0 before:rounded-[inherit] before:content-['']"
+
+/**
+ * Ten indices, written out in full, for the reason
+ * `categoricalStyles.ts` opens with: Tailwind scans source text for
+ * COMPLETE class strings, so a template literal generates nothing
+ * at all and the bar renders invisible with no error and no failing
+ * test. `tailwindCandidates.test.ts` compiles every literal in this
+ * package through the real Tailwind, which is the something that
+ * checks.
+ */
+export const ACCENT_EDGE_CATEGORICAL_CLASS: Record<
+  CategoricalIndex,
+  string
+> = {
+  1: "before:shadow-[inset_3px_0_0_var(--color-categorical-1-solid)] rtl:before:shadow-[inset_-3px_0_0_var(--color-categorical-1-solid)]",
+  2: "before:shadow-[inset_3px_0_0_var(--color-categorical-2-solid)] rtl:before:shadow-[inset_-3px_0_0_var(--color-categorical-2-solid)]",
+  3: "before:shadow-[inset_3px_0_0_var(--color-categorical-3-solid)] rtl:before:shadow-[inset_-3px_0_0_var(--color-categorical-3-solid)]",
+  4: "before:shadow-[inset_3px_0_0_var(--color-categorical-4-solid)] rtl:before:shadow-[inset_-3px_0_0_var(--color-categorical-4-solid)]",
+  5: "before:shadow-[inset_3px_0_0_var(--color-categorical-5-solid)] rtl:before:shadow-[inset_-3px_0_0_var(--color-categorical-5-solid)]",
+  6: "before:shadow-[inset_3px_0_0_var(--color-categorical-6-solid)] rtl:before:shadow-[inset_-3px_0_0_var(--color-categorical-6-solid)]",
+  7: "before:shadow-[inset_3px_0_0_var(--color-categorical-7-solid)] rtl:before:shadow-[inset_-3px_0_0_var(--color-categorical-7-solid)]",
+  8: "before:shadow-[inset_3px_0_0_var(--color-categorical-8-solid)] rtl:before:shadow-[inset_-3px_0_0_var(--color-categorical-8-solid)]",
+  9: "before:shadow-[inset_3px_0_0_var(--color-categorical-9-solid)] rtl:before:shadow-[inset_-3px_0_0_var(--color-categorical-9-solid)]",
+  10: "before:shadow-[inset_3px_0_0_var(--color-categorical-10-solid)] rtl:before:shadow-[inset_-3px_0_0_var(--color-categorical-10-solid)]",
+}
+
+/** The same bar, reading the caller's own colour. */
+export const ACCENT_EDGE_COLOR_CLASS =
+  "before:shadow-[inset_3px_0_0_var(--charcuterie-accent-edge)] rtl:before:shadow-[inset_-3px_0_0_var(--charcuterie-accent-edge)]"
+
+export const getAccentEdgeClassName = (
+  accentEdge: CardAccentEdge,
+): string =>
+  `${ACCENT_EDGE_BASE_CLASS} ${
+    accentEdge.categorical == null
+      ? ACCENT_EDGE_COLOR_CLASS
+      : ACCENT_EDGE_CATEGORICAL_CLASS[
+          accentEdge.categorical
+        ]
+  }`
+
+/**
+ * The inline style an explicit colour needs, and nothing when the
+ * colour came from an index.
+ *
+ * Returns `undefined` rather than `{}` so a card with a categorical
+ * edge and no `style` of its own renders no `style` attribute at
+ * all.
+ */
+export const getAccentEdgeStyle = (
+  accentEdge: CardAccentEdge,
+): Record<string, string> | undefined =>
+  accentEdge.color == null
+    ? undefined
+    : { [ACCENT_EDGE_COLOR_PROPERTY]: accentEdge.color }

package/src/index.ts

@@ -65,6 +65,9 @@ export type {
 export { Alert } from "./Alert/Alert.tsx"
 export type { BadgeProps } from "./Badge/Badge.tsx"
 export { Badge } from "./Badge/Badge.tsx"
+export type { BadgeShapeProps } from "./Badge/useBadgeShape.tsx"
+export type { BadgeButtonProps } from "./BadgeButton/BadgeButton.tsx"
+export { BadgeButton } from "./BadgeButton/BadgeButton.tsx"
 export type {
   BoardMove,
   BoardProps,
@@ -95,6 +98,7 @@ export type {
   CardSurface,
 } from "./Card/Card.tsx"
 export { Card } from "./Card/Card.tsx"
+export type { CardAccentEdge } from "./Card/cardAccentEdge.ts"
 export type { CheckboxProps } from "./Checkbox/Checkbox.tsx"
 export { Checkbox } from "./Checkbox/Checkbox.tsx"
 export type { ColorSchemeSwitcherProps } from "./ColorSchemeSwitcher/ColorSchemeSwitcher.tsx"

package/src/sourceRules.test.ts

@@ -452,7 +452,14 @@ test("the barrel is the only place components are re-exported", async () => {
   // count by the `<Name>/<Name>.tsx` rule; it is not exported from the
   // barrel either, because a consumer sets `min`/`max`/`step` and never
   // does the arithmetic itself.
-  expect(componentNames.length).toBe(52)
+  //
+  // `BadgeButton` — a `Badge` you can press — is +1 -> 53. It is to
+  // `Badge` what `ButtonLink` is to `Button`: a sibling element
+  // sharing one paint, here through `useBadgeShape`, which is a
+  // member of `Badge/` and so stays out of this count and out of the
+  // barrel as a component. Its PROPS type is exported, because a
+  // consumer writing a wrapper needs to name the visual half.
+  expect(componentNames.length).toBe(53)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)