@charcuterie/ui 3.19.2 → 3.21.0

package/src/Board/BoardCard.tsx

@@ -3,6 +3,11 @@ import type { ReactNode } from "react"
 import { useState } from "react"
 
 import { Button } from "../Button/Button.tsx"
+import type { CardAccentEdge } from "../Card/cardAccentEdge.ts"
+import {
+  getAccentEdgeClassName,
+  getAccentEdgeStyle,
+} from "../Card/cardAccentEdge.ts"
 import {
   FOCUS_RING_CLASS,
   INTENT_SOLID_FILL_CLASS,
@@ -12,32 +17,14 @@ import { TextLink } from "../TextLink/TextLink.tsx"
 import { toClassName } from "../toClassName.ts"
 import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
 
-export type BoardItem = {
-  /**
-   * The leading colour bar. Priority, in the consumer this was built
-   * for — *"Priority is styled as a leading colour bar, and **never**
-   * a coloured word before the title."*
-   *
-   * Pair it with `accentLabel`. A bar is colour and nothing else, so
-   * on its own it fails WCAG 1.4.1 outright and is invisible to
-   * every screen reader; the label rides along in a
-   * `VisuallyHidden` so the same fact reaches both channels. Docket's
-   * first board painted these `--color-danger-9` — a Radix-style
-   * scale this token set has never had — so every bar was
-   * transparent while every "is it rendered" assertion passed. The
-   * families here are `--color-intent-<intent>-<role>`; there is no
-   * numeric scale to reach for.
-   */
-  accentIntent?: IntentName
-  /** What the bar means, in words. "Priority 0". */
+type BoardItemFields = {
+  /** What the bar means, in words. "Priority 0", "Movies and Shows". */
   accentLabel?: string
   /**
    * Under the title and metadata, spanning the card: a live run
    * line, a gate explanation, a due date. A `ProgressBar` goes here.
    */
   footer?: ReactNode
-  /** Where the title navigates. Routed through `RouterLinkProvider`. */
-  href?: string
   /**
    * Visibly present but not actionable — Docket's *gated*: a task
    * whose phase has not opened yet. Paint only; it does not disable
@@ -57,13 +44,105 @@ export type BoardItem = {
    * beside it when there is room. `Badge` is what goes here.
    */
   meta?: ReactNode
-  /** Fires when there is no `href` — for a board that opens a modal. */
-  onSelect?: () => void
+  /**
+   * The card's name, in **words**.
+   *
+   * Always a plain string, even when `titleContent` draws something
+   * richer, because this is what the move handle and the drag
+   * announcements are named after — and a control named after a
+   * `ReactNode` is a control with no name at all.
+   */
   title: string
   /** The trailing cluster: an assignee avatar, an elapsed-time chip. */
   trailing?: ReactNode
 }
 
+/**
+ * The leading colour bar, in one of two shapes — and the second one
+ * exists because the first cannot follow a corner.
+ *
+ * `accentIntent` is an inset pill: a `w-1` span inside the card,
+ * beside the content. It was built for priority — *"Priority is
+ * styled as a leading colour bar, and **never** a coloured word
+ * before the title."* An intent is a claim the design system makes
+ * (`danger` says what happens if you press the thing), so this arm
+ * is for a bar that means a STATE.
+ *
+ * `accentEdge` is the card's own edge — `Card`'s treatment, the same
+ * pseudo-element, so it takes `border-radius: inherit` and wraps the
+ * corner at `cq-lg` where this card grows one. It carries a
+ * CATEGORICAL colour or a computed one, which is what an identity
+ * needs: a project, a repo, a source. The owner asked for exactly
+ * this on Docket's board — *"The Board has no colors. That could
+ * use project colors on the sides at least."* — after reporting the
+ * same treatment missing from the task rows.
+ *
+ * The two are mutually exclusive by type, not by convention. Both
+ * paint a leading bar in the same place, and a card wearing two of
+ * them is a card whose leading edge means two things.
+ *
+ * ⚠️ Either arm pairs with `accentLabel`. A bar is colour and
+ * nothing else, so on its own it fails WCAG 1.4.1 outright and is
+ * invisible to every screen reader; the label rides along in a
+ * `VisuallyHidden` so the same fact reaches both channels. Docket's
+ * first board painted its bars `--color-danger-9` — a Radix-style
+ * scale this token set has never had — so every bar was transparent
+ * while every "is it rendered" assertion passed.
+ */
+type BoardItemAccent =
+  | { accentEdge?: never; accentIntent?: IntentName }
+  | { accentEdge: CardAccentEdge; accentIntent?: never }
+
+/**
+ * Who owns the card title's link — the board, or the caller.
+ *
+ * A union rather than three loose optionals, because the two halves
+ * genuinely cannot coexist. `href` wraps the title in a `TextLink`
+ * and `onSelect` wraps it in a `<button>`; a `titleContent` that
+ * contains its own anchor would then be an anchor inside an anchor
+ * (which the HTML parser silently un-nests, dropping the rest of the
+ * card's link) or an anchor inside a button (which is invalid and
+ * unreachable by keyboard). Both look completely correct on screen.
+ *
+ * So the type refuses the combination outright, and a caller who
+ * needs a rich title takes the navigation with it:
+ *
+ * ```tsx
+ * {
+ *   title: toPlainMarkdownText(task.title),
+ *   titleContent: (
+ *     <MarkdownLine href={`/tasks/${task.id}`} value={task.title} />
+ *   ),
+ * }
+ * ```
+ */
+type BoardItemTitleLink =
+  | {
+      /** Where the title navigates. Routed through `RouterLinkProvider`. */
+      href?: string
+      /** Fires when there is no `href` — for a board that opens a modal. */
+      onSelect?: () => void
+      titleContent?: never
+    }
+  | {
+      href?: never
+      onSelect?: never
+      /**
+       * Drawn instead of `title`, inside the card's own clamping box
+       * — so it still truncates the way every other card does.
+       *
+       * It **owns its navigation**: the board adds no link around it,
+       * which is why `href` and `onSelect` are refused beside it.
+       * `title` is still required, and is still the name every
+       * control on the card is announced by.
+       */
+      titleContent: ReactNode
+    }
+
+export type BoardItem = BoardItemAccent &
+  BoardItemFields &
+  BoardItemTitleLink
+
 export type BoardCardProps = {
   item: BoardItem
   laneLabel: string
@@ -137,12 +216,15 @@ export const BoardCard = ({
 }: BoardCardProps): ReactNode => {
   const [isMenuVisible, setIsMenuVisible] = useState(false)
 
-  const titleContent = (
+  const titleBlock = (
     // `line-clamp-none` before `truncate`, because `line-clamp-2`
     // sets `display: -webkit-box` and `text-overflow` has nothing to
     // ellipsise inside one.
+    //
+    // A `titleContent` is clamped by the same box as a plain one —
+    // it replaces the card's *words*, not the card's shape.
     <span className="line-clamp-2 cq-sm:line-clamp-none cq-sm:block cq-sm:truncate">
-      {item.title}
+      {item.titleContent ?? item.title}
     </span>
   )
 
@@ -155,10 +237,36 @@ export const BoardCard = ({
         // cannot do this to itself — it is the container, and a
         // container query never matches its own container.
         "cq-lg:mb-2 cq-lg:rounded-lg cq-lg:border cq-lg:bg-surface-raised cq-lg:p-3 cq-lg:shadow-low",
+        // The edge is drawn on THIS box, which is why it needs no
+        // shape of its own: the box is a row below `cq-lg` and a
+        // rounded card above it, and `border-radius: inherit` gives
+        // the right answer at both — a straight stripe down a row
+        // that has no corner, and a bar that wraps the card's
+        // corner once it grows one.
+        //
+        // `ps-2` is what keeps the content off it. The bar is 3px
+        // and overlays rather than displaces, so without this the
+        // first mark sits on top of it; at `cq-lg` the card's own
+        // `p-3` is already wider than the bar.
+        item.accentEdge != null &&
+          toClassName(
+            "ps-2",
+            getAccentEdgeClassName(item.accentEdge),
+          ),
         item.isDimmed && "opacity-60",
       )}
       data-board-card={item.key}
+      {...(item.accentEdge == null
+        ? {}
+        : { style: getAccentEdgeStyle(item.accentEdge) })}
     >
+      {/* The label the bar cannot say. An edge has no content of
+          its own — it is a pseudo-element — so unlike the pill
+          arm below there is nowhere inside it to put the words. */}
+      {item.accentEdge != null && item.accentLabel ? (
+        <VisuallyHidden>{item.accentLabel}</VisuallyHidden>
+      ) : null}
+
       {item.accentIntent ? (
         <span
           className={toClassName(
@@ -191,7 +299,7 @@ export const BoardCard = ({
                   href={item.href}
                   intent="neutral"
                 >
-                  {titleContent}
+                  {titleBlock}
                 </TextLink>
               ) : item.onSelect ? (
                 <button
@@ -202,10 +310,10 @@ export const BoardCard = ({
                   onClick={item.onSelect}
                   type="button"
                 >
-                  {titleContent}
+                  {titleBlock}
                 </button>
               ) : (
-                titleContent
+                titleBlock
               )}
             </div>
 

package/src/MarkdownEditor/markdownSpans.ts

@@ -69,7 +69,20 @@ export type MarkdownSpan = {
   text: string
 }
 
-export type MarkdownLineKind =
+/**
+ * `MarkdownEditorLine`, not `MarkdownLine` — renamed in 3.18.0 when
+ * `MarkdownLine` became a **component**, and a barrel cannot export
+ * one name as both a type and a value.
+ *
+ * The editor's name gave way rather than the component's for two
+ * reasons. It is the lower-level of the two — the painted layer's
+ * view of one line of a *document*, which is a thing only
+ * `MarkdownEditor` has ever needed — and it had no consumer outside
+ * this package in any repo in the fleet, checked before the rename.
+ * A component that renders a title is the name a call site reaches
+ * for; a line-kind union is not.
+ */
+export type MarkdownEditorLineKind =
   | "blockquote"
   | "code"
   | "heading"
@@ -78,8 +91,8 @@ export type MarkdownLineKind =
   | "table"
   | "thematicBreak"
 
-export type MarkdownLine = {
-  kind: MarkdownLineKind
+export type MarkdownEditorLine = {
+  kind: MarkdownEditorLineKind
   spans: MarkdownSpan[]
 }
 
@@ -352,7 +365,7 @@ const toTableSpans = (text: string): MarkdownSpan[] => {
   return spans
 }
 
-const toBlockLine = (line: string): MarkdownLine => {
+const toBlockLine = (line: string): MarkdownEditorLine => {
   const spans: MarkdownSpan[] = []
 
   const indent = INDENT_PATTERN.exec(line)?.[0] ?? ""
@@ -440,7 +453,7 @@ const toBlockLine = (line: string): MarkdownLine => {
  */
 export const toMarkdownLines = (
   text: string,
-): MarkdownLine[] => {
+): MarkdownEditorLine[] => {
   let isInsideFence = false
 
   return text.split("\n").map((line) => {

package/src/MarkdownLine/MarkdownLine.mdx

@@ -0,0 +1,135 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as MarkdownLineStories from "./MarkdownLine.stories";
+
+<Meta of={MarkdownLineStories} />
+
+# MarkdownLine
+
+**One line of markdown, drawn with its inline marks and nothing else.** Reach for it
+wherever a stored string is a *name* rather than a document — a card title, a lane heading,
+a table cell, a breadcrumb.
+
+<Canvas of={MarkdownLineStories.Default} />
+
+## Props
+
+<Controls />
+
+## Why marks belong in a title
+
+A grid of task names set in one flat weight is a wall. The parts that tell two cards apart —
+the path, the urgency, the thing that is already done — are exactly the parts markdown would
+have marked, so the marks are doing the same job the priority bar and the project colour do
+one layer up: making a list **scannable**.
+
+<Canvas of={MarkdownLineStories.WhyItHelps} />
+
+## It is inline-only, and it is one line
+
+| Rendered | Literal text |
+| --- | --- |
+| `**bold**`, `__bold__` | `# heading` |
+| `*italic*`, `_italic_` | `- list item`, `1. list item` |
+| `` `code` `` | `> blockquote` |
+| `~~strikethrough~~` | `\| table \| row \|` |
+| `[text](url)`, `<url>`, bare `https://…` and `www.…` | `![image](url)` |
+
+A newline collapses to a space. Every surface that draws one of these clamps to one or two
+lines anyway, so a hard break would only push the second half of a title out of a box that
+was measured for one line.
+
+## File names are not markup
+
+The case this component is most often asked to get wrong.
+
+<Canvas of={MarkdownLineStories.FileNames} />
+
+`ingest_the_files.sh` keeps its underscores because CommonMark's flanking rules say an
+underscore **inside a word** opens nothing — the rule that makes `_` and `*` genuinely
+different characters, and the one a hand-rolled "strip the markdown" regex always misses.
+`2 * 3 * 4` is arithmetic for the same reason: a delimiter followed by a space cannot open.
+
+## `href` — a link inside a link
+
+<Canvas of={MarkdownLineStories.AsALink} />
+
+A card title is usually a link to the card, and a title may also *contain* a link. An anchor
+inside an anchor is invalid HTML: the parser closes the outer one at the inner one's start
+tag, so the text after the inner link silently stops opening the card. It looks completely
+correct and half of it does not work.
+
+So `href` is a prop rather than something you wrap the component in. Given one, the plain
+runs become anchors to `href` and a markdown link stays a **sibling** anchor with its own
+destination:
+
+```tsx
+<MarkdownLine href={`/tasks/${task.id}`} value={task.title} />
+```
+
+Consecutive runs sharing a destination are merged into one anchor, so `**Ship** it` is a
+single tab stop and one entry in a screen reader's link list.
+
+A markdown link **splits** the line into more than one anchor, and each is named by the words
+it covers — `Ship`, `#53`, `tonight`. That is honest, and it is not good: `tonight` is a poor
+name for a link to a task. Naming all three after the whole line was tried and is worse — two
+links with the same name are ambiguous to anything driving the page by name, and this
+library's own `expectAgentDrivable` refuses it. The conclusion is a design one rather than an
+API one: **a link usually belongs in a task's description**, where it has a sentence around
+it, rather than in its title.
+
+<Canvas of={MarkdownLineStories.Routed} />
+
+An in-app destination goes through the injected `RouterLinkProvider`; an off-origin one
+does not, and opens in a new tab. A title that names a pull request is a reference, and
+following it should not lose the board the reader was on.
+
+## `isInsideLink` — when the card is already the link
+
+<Canvas of={MarkdownLineStories.InsideACardLink} />
+
+The third and last answer to *who owns the link here*. `href` says this component does;
+neither says the markdown links do; `isInsideLink` says **nobody** — draw the marks and emit
+no anchor at all.
+
+Reach for it whenever the line sits inside a link the caller already owns, which is what a
+whole-card link is. The trap it closes has teeth even when no author ever typed a link: a
+**bare URL autolinks**, so a captured note whose title ends in `https://…` would nest an
+anchor without anybody writing `[]()`.
+
+## Anywhere a string is required
+
+`aria-label`, `title`, `document.title`, a confirmation sentence — call `toPlainMarkdownText`
+rather than writing a regex that strips the markup:
+
+```ts
+import { toPlainMarkdownText } from "@charcuterie/ui"
+
+document.title = `${toPlainMarkdownText(task.title)} — Docket`
+```
+
+It is the **same parse** the component renders from, so it cannot drift. A second stripper is
+how a card comes to read `Ingest 53 movies` while its own tooltip reads
+``Ingest 53 movies from `Downloads/MOVIES` ``.
+
+## A refused URL keeps its source
+
+<Canvas of={MarkdownLineStories.RefusedUrl} />
+
+URLs cross `safeUrls.ts` — an allowlist of `http`, `https`, `mailto` and `tel` — before they
+reach an `href`, the same module `MarkdownView` and the CodeMirror editor use. A scheme that
+does not survive it produces **no anchor at all**, and every character of the source stays on
+screen. A reader who can see `[click me](javascript:…)` is better served than one shown a
+confident blue word that silently refuses to work.
+
+## Not a small `MarkdownView`
+
+`MarkdownView` renders a *document*, through CodeMirror, from the optional
+`@charcuterie/ui/markdown-editor-codemirror` entry point. Neither half suits a name: an
+editor state, a syntax tree and a decoration set per card is an absurd price for forty
+characters, and the main entry may not reach the CodeMirror stack at all.
+
+So this is a second parser, which is worth being nervous about — two parsers are two answers
+to "what does this markdown mean". Three things keep them honest: this one is **inline-only**,
+so there is no block level to disagree about; both call the **same** URL guard; and the
+flanking rules here are CommonMark's rather than a convenient approximation.