|
| 1 | +import { useI18n } from "~/context/i18n" |
| 2 | +import { createEffect, createSignal, For, onCleanup, Show, type JSX } from "solid-js" |
| 3 | +import { FileTypeIcon } from "./file-type-icon" |
| 4 | +import type { DocsVariantKey } from "./settings" |
| 5 | + |
| 6 | +/** |
| 7 | + * The frame around a docs code block: a header row with a label (a file name, a terminal mark, |
| 8 | + * "Files", "Usage") and a copy button that's always visible. It only shows with a component's |
| 9 | + * "Vercel square" option (docs-variants.css); the other options keep their own look, so the frame |
| 10 | + * folds away (display: contents) and its header hides. |
| 11 | + */ |
| 12 | +export function CodeFrame(props: { |
| 13 | + variant: DocsVariantKey |
| 14 | + kind: "file" | "terminal" | "code" | "tree" | "usage" | "response" | "config" |
| 15 | + label?: string |
| 16 | + /** The text to copy; leading "$ " prompts are dropped. No copy button without it. */ |
| 17 | + copy?: string |
| 18 | + /** A different terminal mark, for the icon options in the code gallery. */ |
| 19 | + icon?: "window" | "prompt" | "titlebar" |
| 20 | + children: JSX.Element |
| 21 | +}) { |
| 22 | + return ( |
| 23 | + <div data-component="code-frame" data-variant={props.variant} data-kind={props.kind} data-icon={props.icon}> |
| 24 | + <div data-slot="code-head"> |
| 25 | + <span data-slot="code-label"> |
| 26 | + <Show when={props.kind === "file" && props.label}>{(label) => <FileTypeIcon path={label()} />}</Show> |
| 27 | + {props.label} |
| 28 | + </span> |
| 29 | + <Show when={props.copy}>{(text) => <CopyButton text={text()} />}</Show> |
| 30 | + </div> |
| 31 | + {props.children} |
| 32 | + </div> |
| 33 | + ) |
| 34 | +} |
| 35 | + |
| 36 | +/** |
| 37 | + * Copy with visible feedback, text only: "Copy" turns to "Copied" for 1.5s (or "Failed" when the |
| 38 | + * clipboard refuses), and a polite live region says what happened. The three labels share one |
| 39 | + * right-aligned grid cell, so the button keeps the longest label's width and the text's right edge |
| 40 | + * never moves. |
| 41 | + */ |
| 42 | +export function CopyButton(props: { text: string; slot?: "code-copy" | "copy" }) { |
| 43 | + const i18n = useI18n() |
| 44 | + const [state, setState] = createSignal<"idle" | "copied" | "failed">("idle") |
| 45 | + let timer: ReturnType<typeof setTimeout> | undefined |
| 46 | + onCleanup(() => clearTimeout(timer)) |
| 47 | + const show = (next: "copied" | "failed") => { |
| 48 | + setState(next) |
| 49 | + clearTimeout(timer) |
| 50 | + timer = setTimeout(() => setState("idle"), 1500) |
| 51 | + } |
| 52 | + const copy = () => { |
| 53 | + const write = navigator.clipboard?.writeText(props.text.replace(/^\$ /gm, "")) |
| 54 | + if (!write) return show("failed") |
| 55 | + write.then( |
| 56 | + () => show("copied"), |
| 57 | + () => show("failed"), |
| 58 | + ) |
| 59 | + } |
| 60 | + return ( |
| 61 | + <> |
| 62 | + <button |
| 63 | + type="button" |
| 64 | + data-slot={props.slot ?? "code-copy"} |
| 65 | + data-state={state()} |
| 66 | + aria-label={i18n.t("site.code.copy")} |
| 67 | + onClick={copy} |
| 68 | + > |
| 69 | + <span data-slot="copy-labels" aria-hidden="true"> |
| 70 | + <span data-label="idle">{i18n.t("site.action.copy")}</span> |
| 71 | + <span data-label="copied">{i18n.t("site.action.copied")}</span> |
| 72 | + <span data-label="failed">{i18n.t("site.code.failed")}</span> |
| 73 | + </span> |
| 74 | + </button> |
| 75 | + <span data-slot="sr-only" aria-live="polite"> |
| 76 | + {state() === "copied" ? i18n.t("site.code.copied") : state() === "failed" ? i18n.t("site.code.failedHint") : ""} |
| 77 | + </span> |
| 78 | + </> |
| 79 | + ) |
| 80 | +} |
| 81 | + |
| 82 | +/** |
| 83 | + * Lines with the rest folded away. The folded lines stay in the page (hidden="until-found"), so |
| 84 | + * find in page reaches them and opens the block; Copy always copies everything. |
| 85 | + * "marker" (the default, chosen 5 Nov 2026) is a plain "⋯ 8 more lines" row in the gutter where the |
| 86 | + * lines are, GitHub style, that turns to "Show fewer lines" at the end of the revealed range. |
| 87 | + * "fade" and "bar" are the older options, kept for comparison in the gallery. |
| 88 | + */ |
| 89 | +export function CodeCollapse(props: { |
| 90 | + style?: "marker" | "fade" | "bar" |
| 91 | + visible: JSX.Element |
| 92 | + hidden: JSX.Element |
| 93 | + count: number |
| 94 | +}) { |
| 95 | + const [open, setOpen] = createSignal(false) |
| 96 | + let folded: HTMLDivElement | undefined |
| 97 | + createEffect(() => { |
| 98 | + if (!folded) return |
| 99 | + if (open()) folded.removeAttribute("hidden") |
| 100 | + else folded.setAttribute("hidden", "until-found") |
| 101 | + }) |
| 102 | + const style = () => props.style ?? "marker" |
| 103 | + const name = () => (open() ? `Show fewer lines, hide ${props.count}` : `Show ${props.count} more lines`) |
| 104 | + return ( |
| 105 | + <div data-slot="code-collapse" data-style={style()} data-open={open() ? "" : undefined}> |
| 106 | + <div data-slot="collapse-visible">{props.visible}</div> |
| 107 | + <div |
| 108 | + data-slot="collapse-folded" |
| 109 | + ref={(el) => { |
| 110 | + folded = el |
| 111 | + el.setAttribute("hidden", "until-found") |
| 112 | + el.addEventListener("beforematch", () => setOpen(true)) |
| 113 | + }} |
| 114 | + > |
| 115 | + {props.hidden} |
| 116 | + </div> |
| 117 | + <button |
| 118 | + type="button" |
| 119 | + data-slot="code-expand" |
| 120 | + aria-expanded={open()} |
| 121 | + aria-label={name()} |
| 122 | + onClick={() => setOpen(!open())} |
| 123 | + > |
| 124 | + <Show when={style() === "marker"} fallback={open() ? "Show fewer lines" : `Show ${props.count} more lines`}> |
| 125 | + <span data-slot="expand-mark" aria-hidden="true"> |
| 126 | + ⋯ |
| 127 | + </span> |
| 128 | + {open() ? "Show fewer lines" : `${props.count} more lines`} |
| 129 | + </Show> |
| 130 | + </button> |
| 131 | + </div> |
| 132 | + ) |
| 133 | +} |
| 134 | + |
| 135 | +/** Numbered lines for the gallery (marks, focus dimming, a start number, no gutter when plain). */ |
| 136 | +export function CodeLines(props: { |
| 137 | + lines: string[] |
| 138 | + mark?: number[] |
| 139 | + focus?: number[] |
| 140 | + plain?: boolean |
| 141 | + start?: number |
| 142 | +}) { |
| 143 | + return ( |
| 144 | + <pre data-component="code-lines" data-plain={props.plain ? "" : undefined}> |
| 145 | + <For each={props.lines}> |
| 146 | + {(line, index) => { |
| 147 | + const n = (props.start ?? 1) + index() |
| 148 | + return ( |
| 149 | + <code |
| 150 | + data-line={n} |
| 151 | + data-mark={props.mark?.includes(n) ? "" : undefined} |
| 152 | + data-dim={props.focus && !props.focus.includes(n) ? "" : undefined} |
| 153 | + > |
| 154 | + {line || " "} |
| 155 | + {"\n"} |
| 156 | + </code> |
| 157 | + ) |
| 158 | + }} |
| 159 | + </For> |
| 160 | + </pre> |
| 161 | + ) |
| 162 | +} |
0 commit comments