@charcuterie/ui 3.19.1 → 3.20.0

package/dist/MarkdownLine/MarkdownLine.js

@@ -0,0 +1,187 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment } from "react";
+import { FOCUS_RING_CLASS, INTENT_CONTENT_CLASS, } from "../intentStyles.js";
+import { useRouterLink } from "../RouterLink/RouterLinkProvider.js";
+import { getIsRoutedHref } from "../RouterLink/routerLink.js";
+import { toClassName } from "../toClassName.js";
+import { toInlineMarkdownRuns } from "./inlineMarkdown.js";
+/**
+ * The link paint, matched to `.cm-md-link` in the CodeMirror
+ * surface's theme rather than to `TextLink`'s.
+ *
+ * `TextLink` would be the obvious reach and it is the wrong one: it
+ * declares `rounded-xs`, a cursor and a hover rule that belong to a
+ * link in a paragraph, and — the deciding one — it has no way to
+ * inherit the title's own weight, so a link inside a bold title
+ * would un-bold itself. Two rules is the whole of what is shared
+ * with `.cm-md-link`, and sharing them by value is what keeps the
+ * editor and the card showing one answer.
+ */
+const LINK_CLASS = toClassName(INTENT_CONTENT_CLASS.accent, "underline decoration-1 underline-offset-2 hover:decoration-2", FOCUS_RING_CLASS);
+/**
+ * `0.9em` and not a step on the type scale.
+ *
+ * A monospace face at the same `font-size` as the text around it
+ * reads bigger — fixed advance width, taller x-height — so a file
+ * name in a title would shout. `em` rather than a fixed size so a
+ * code span in a 24px heading and one in a 13px card row are both
+ * proportional to their line. This is `.cm-md-code`'s rule, copied
+ * by value for the same reason as the link's.
+ */
+const CODE_CLASS = "font-mono text-[0.9em] text-intent-info-content";
+/**
+ * Position IS the identity here, which is why every `key` in this
+ * file is an index.
+ *
+ * The usual objection to an index key does not reach this component.
+ * The list is a **pure function of `value`** — nothing inserts,
+ * removes or re-orders a run, and no run holds component state for a
+ * key to preserve — so two renders of the same string produce the
+ * same runs in the same order, and two renders of different strings
+ * are a different line entirely. Content cannot stand in for it: a
+ * title like `**Ship** it **Ship**` has two runs with identical text
+ * and identical marks, and keying by either would collide.
+ */
+const toMarkedContent = (run, key) => {
+    /**
+     * AN UNMARKED RUN IS A TEXT NODE, NOT A WRAPPED ONE — and this is
+     * an accessibility fix rather than a saving.
+     *
+     * Every run used to come back inside a keyed `<span>`. It looked
+     * identical, and it silently broke every accessible name on the
+     * page: the name computation **trims** each element child's
+     * contribution before joining them, so
+     * `<span>Deduplicate </span><code>~/archive</code><span> by</span>`
+     * announces as `Deduplicate~/archiveby`. A text node keeps its
+     * spaces, so the same line as text-node / `<code>` / text-node
+     * announces correctly.
+     *
+     * Caught by `Board`'s move handle, which is named after the card's
+     * title. On screen the two are indistinguishable — the spaces are
+     * still painted either way — which is why `MarkdownLine.test.tsx`
+     * asserts the NAME rather than the text.
+     */
+    if (!run.isCode &&
+        !run.isEmphasis &&
+        !run.isStrikethrough &&
+        !run.isStrong) {
+        return run.text;
+    }
+    // Innermost first: the element that carries the text, then the
+    // marks wrapped around it. `<code>` is innermost because it is the
+    // only one that changes the *face* rather than a variation of it.
+    let content = run.isCode ? (_jsx("code", { className: CODE_CLASS, children: run.text })) : (run.text);
+    if (run.isEmphasis) {
+        content = _jsx("em", { children: content });
+    }
+    if (run.isStrong) {
+        content = _jsx("strong", { children: content });
+    }
+    if (run.isStrikethrough) {
+        // `<s>`, not `<del>`. `<del>` means "removed from the document"
+        // and carries an editorial history a title does not have; `<s>`
+        // is "no longer accurate", which is what a struck-through task
+        // name says.
+        content = (_jsx("s", { className: "text-content-secondary", children: content }));
+    }
+    // A `Fragment` rather than a `<span>`: it carries the key React
+    // needs for an array child and adds no element to the DOM, so the
+    // mark element sits directly inside the anchor and the name
+    // computation sees no extra boundary to trim.
+    return _jsx(Fragment, { children: content }, key);
+};
+/**
+ * One line of markdown, drawn with its inline marks and nothing
+ * else.
+ *
+ * A **title** is what this is for. Docket's cards carry names like
+ * ``Ingest 53 movies from `Downloads/MOVIES` into `G:\Movies` ``,
+ * and a grid of them set in one flat weight is a wall the eye cannot
+ * scan — the parts that differ between two cards are exactly the
+ * parts markdown would have marked. So the marks earn their place
+ * by making a list of names *scannable*, which is the same argument
+ * as the priority bar and the project colour, one layer down.
+ *
+ * ### It is not a small `MarkdownView`
+ *
+ * `MarkdownView` renders a document, through CodeMirror, from the
+ * optional `@charcuterie/ui/markdown-editor-codemirror` entry point.
+ * Neither half of that suits a name: an editor state and a syntax
+ * tree per card is an absurd price for forty characters, and the
+ * main entry may not reach the CodeMirror stack at all. This parses
+ * the inline grammar directly and returns spans.
+ *
+ * The two therefore have to agree, and `inlineMarkdown.ts` says how
+ * that is kept true — most importantly that both call the **same**
+ * URL guard, `safeUrls.ts`, which moved up out of the CodeMirror
+ * subpath when this landed.
+ *
+ * ### The `href` prop is the load-bearing one
+ *
+ * A card title is usually itself a link. A title may also *contain*
+ * one. Nested anchors are invalid HTML and the browser silently
+ * closes the outer element, so `href` makes the component emit
+ * **siblings** — the plain runs anchored to `href`, the markdown
+ * links anchored to their own destination — which reads as one
+ * continuous line and behaves as two different destinations.
+ *
+ * ```tsx
+ * <MarkdownLine href={`/tasks/${task.id}`} value={task.title} />
+ * ```
+ *
+ * Anywhere a *string* is required — an `aria-label`, a `title`
+ * attribute, `document.title` — call `toPlainMarkdownText` rather
+ * than re-stripping the markup with a regex of your own. It is the
+ * same parse, so it cannot drift from what is on screen.
+ */
+export const MarkdownLine = ({ className, href, isInsideLink = false, value, }) => {
+    const RouterLink = useRouterLink();
+    const runs = toInlineMarkdownRuns(value);
+    /**
+     * Consecutive runs that share a destination become **one** anchor.
+     *
+     * Not cosmetic: an anchor per run would make `**Ship** it` two tab
+     * stops and two entries in a screen reader's link list for one
+     * destination, and would break the hover underline into pieces at
+     * every mark boundary.
+     */
+    const groups = [];
+    for (const run of runs) {
+        const last = groups.at(-1);
+        if (last && last.href === run.href) {
+            last.runs.push(run);
+            continue;
+        }
+        groups.push({
+            ...(run.href === undefined ? {} : { href: run.href }),
+            runs: [run],
+        });
+    }
+    return (_jsx("span", { className: className, children: groups.map((group, groupIndex) => {
+            const content = group.runs.map(toMarkedContent);
+            if (isInsideLink) {
+                // No anchor, and no link paint either: a word painted as
+                // a link that cannot be followed is worse than plain text.
+                return (_jsx(Fragment
+                // biome-ignore lint/suspicious/noArrayIndexKey: position is the identity — see `toMarkedContent`
+                , { children: content }, groupIndex));
+            }
+            if (group.href !== undefined) {
+                // A destination the injected router cannot serve opens in
+                // a new tab rather than replacing the app: a title that
+                // names a pull request is a reference, and following it
+                // should not lose the board the reader was on.
+                const isRouted = getIsRoutedHref(group.href);
+                const LinkElement = isRouted ? RouterLink : "a";
+                return (_jsx(LinkElement, { className: LINK_CLASS, href: group.href, rel: isRouted ? undefined : "noopener noreferrer", target: isRouted ? undefined : "_blank", children: content }, groupIndex));
+            }
+            if (href === undefined) {
+                // biome-ignore lint/suspicious/noArrayIndexKey: position is the identity — see `toMarkedContent`
+                return _jsx("span", { children: content }, groupIndex);
+            }
+            const isRouted = getIsRoutedHref(href);
+            const LinkElement = isRouted ? RouterLink : "a";
+            return (_jsx(LinkElement, { className: toClassName("hover:underline", FOCUS_RING_CLASS), href: href, children: content }, groupIndex));
+        }) }));
+};
+//# sourceMappingURL=MarkdownLine.js.map

package/dist/MarkdownLine/MarkdownLine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownLine.js","sourceRoot":"","sources":["../../src/MarkdownLine/MarkdownLine.tsx"],"names":[],"mappings":"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"}

package/dist/MarkdownLine/inlineMarkdown.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Markdown's **inline** half, parsed into flat runs of marked text.
+ *
+ * ### Why this is not the CodeMirror parser
+ *
+ * `@charcuterie/ui/markdown-editor-codemirror` already renders
+ * markdown, through `@lezer/markdown`. It is the right answer for a
+ * document and the wrong one for a **name**: an editor instance per
+ * card is a CodeMirror state, a view, a syntax tree and a decoration
+ * set for a string that is usually under sixty characters, and a
+ * backlog grid draws dozens of them at once. The whole CodeMirror
+ * stack is also an *optional peer* of this package on purpose — the
+ * main entry may not reach it, so a title renderer that lives in the
+ * main entry cannot borrow it even if the cost were acceptable.
+ *
+ * So this is a second parser, which is a thing to be nervous about:
+ * two parsers are two answers to "what does this markdown mean", and
+ * that divergence is exactly the bug the consumer's
+ * renderer-agreement test exists to catch. Three things keep it
+ * honest:
+ *
+ *  1. **It is inline-only, and says so.** A `#`, a `>`, a `|` table
+ *     row and a `- ` list marker are literal characters here. There
+ *     is no block level to disagree about, because there is no block
+ *     level.
+ *  2. **The URL guard is shared, not copied.** Both surfaces call
+ *     `toSafeLinkUrl` from `../safeUrls.ts` — one module, one
+ *     allowlist. It moved up out of the CodeMirror subpath when this
+ *     landed, for that reason.
+ *  3. **The flanking rules are CommonMark's**, not a convenient
+ *     approximation. That is what makes `ingest_the_files.sh` a file
+ *     name rather than a title with an italic word in the middle of
+ *     it, and file names in titles are the case this was built for.
+ *
+ * ### The shape it produces
+ *
+ * A **flat** list of runs, not a tree. Marks compose by set union, so
+ * `**bold [link](/x) tail**` is three runs that all carry `isStrong`
+ * and of which one carries an `href` — which is precisely the shape
+ * `MarkdownLine` needs to render a link *beside* the surrounding
+ * anchor rather than inside it. A tree would have to be flattened
+ * back into this before it could be drawn.
+ */
+/**
+ * One run of text, with every mark that covers it.
+ *
+ * `href` is present only on a run that came from `[text](url)` or
+ * from a bare URL — never inherited from the caller's own link. Who
+ * the *plain* text points at is `MarkdownLine`'s question, not the
+ * parser's.
+ */
+export type InlineMarkdownRun = {
+    href?: string;
+    isCode: boolean;
+    isEmphasis: boolean;
+    isStrikethrough: boolean;
+    isStrong: boolean;
+    text: string;
+};
+/**
+ * The inline runs of `value`, in order.
+ *
+ * Exported because a consumer occasionally needs the runs without
+ * React — Docket's search highlighter walks them to find which run a
+ * match landed in — and because it is the seam every test in this
+ * directory drives.
+ */
+export declare const toInlineMarkdownRuns: (value: string) => InlineMarkdownRun[];
+/**
+ * The same string with its markers **gone** — what the title says,
+ * with nothing about how it is painted.
+ *
+ * This is not a convenience. Every `aria-label`, `title` attribute,
+ * `document.title` and confirmation sentence that names a task needs
+ * the words without the punctuation, and deriving it from the same
+ * parse is the only way it cannot drift from what is on screen. A
+ * second regex that "strips markdown" is how the card comes to read
+ * `Ingest 53 movies` while the tooltip reads
+ * `Ingest 53 movies from ⁠`Downloads/MOVIES⁠``.
+ */
+export declare const toPlainMarkdownText: (value: string) => string;
+//# sourceMappingURL=inlineMarkdown.d.ts.map

package/dist/MarkdownLine/inlineMarkdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inlineMarkdown.d.ts","sourceRoot":"","sources":["../../src/MarkdownLine/inlineMarkdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAIH;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,OAAO,CAAA;IACf,UAAU,EAAE,OAAO,CAAA;IACnB,eAAe,EAAE,OAAO,CAAA;IACxB,QAAQ,EAAE,OAAO,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAoqBD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAC/B,OAAO,MAAM,KACZ,iBAAiB,EAC8B,CAAA;AAElD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC9B,OAAO,MAAM,KACZ,MAGU,CAAA"}