@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/CodeBlock/CodeBlock.tsx

@@ -0,0 +1,274 @@
+import {
+  Fragment,
+  forwardRef,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+  type HTMLAttributes,
+} from 'react';
+import clsx from 'clsx';
+import { Check, Copy, WrapText, X } from 'lucide-react';
+import { useTranslation } from '../../i18n';
+import { Button } from '../Button';
+import { LiveRegion } from '../LiveRegion';
+import { Tabs } from '../Tabs';
+import { Tooltip } from '../Tooltip';
+import {
+  LANGUAGE_LABELS,
+  highlightedLineSet,
+  tokenizeLines,
+  type CodeBlockLanguage,
+} from './highlight';
+import { resolveActiveSample, setSynced, useSyncedSample } from './sampleSync';
+import styles from './CodeBlock.module.scss';
+
+export type { CodeBlockLanguage } from './highlight';
+
+/** One tab of a multi-sample block (e.g. the same request in cURL and Python). */
+export interface CodeBlockSample {
+  /** Stable id, unique within `samples`. Shared ids are what `syncKey` keeps in step. */
+  id: string;
+  /** Visible tab label (e.g. `'cURL'`, `'Python'`). */
+  label: string;
+  /** The source. Copied verbatim; one trailing newline is not rendered. */
+  code: string;
+  /** Grammar for highlighting. Unknown values render as plain text. */
+  language?: CodeBlockLanguage | (string & {});
+}
+
+/** 1-based line numbers and inclusive `[from, to]` ranges, e.g. `[2, [5, 7]]`. */
+export type CodeBlockHighlightLines = readonly (number | readonly [number, number])[];
+
+/** Body max-height step; maps to `var(--measure-<step>)`. */
+export type CodeBlockMaxHeight = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export interface CodeBlockProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'onChange'> {
+  /** Single-sample mode: the source. Ignored when `samples` is set. */
+  code?: string;
+  /**
+   * Single-sample mode: grammar for highlighting — `'json'`, `'bash'`,
+   * `'javascript'`, `'typescript'`, `'python'`, `'go'`, `'kotlin'`, `'java'`,
+   * `'csharp'` or `'rust'` (aliases `sh`, `shell`, `js`, `ts`, `py`, `golang`,
+   * `kt`, `kts`, `cs`, `c#`, `rs`). Anything else renders as plain text.
+   */
+  language?: CodeBlockLanguage | (string & {});
+  /**
+   * Header label in single-sample mode. Defaults to a one-item `samples`
+   * entry's `label`, else the language name (`JSON`, `Bash`…), else "Plain
+   * text". Also names the body (single-sample) or the sample tabs (multi-sample).
+   */
+  title?: string;
+  /** Multi-sample mode: 2+ samples render as tabs. Wins over `code`/`language`. */
+  samples?: readonly CodeBlockSample[];
+  /** Controlled active sample id. Wins over `syncKey` and the user's own pick. */
+  activeSampleId?: string;
+  /** Initial sample id when uncontrolled and nothing is synced. Defaults to the first sample. */
+  defaultSampleId?: string;
+  /** Called with the new id when the user picks a tab in THIS block (not when a synced block changes it). */
+  onSampleChange?: (id: string) => void;
+  /**
+   * Blocks sharing a `syncKey` switch together: picking `py` in one selects
+   * `py` in every block with the same key that has a `py` sample. In-memory,
+   * per page load; for uncontrolled blocks (controlled blocks sharing one state
+   * don't need it).
+   */
+  syncKey?: string;
+  /** Lines to emphasise (visual only — explain the emphasis in prose). */
+  highlightLines?: CodeBlockHighlightLines;
+  /**
+   * Caps the body height; the body scrolls inside it (it is always a focusable, named region).
+   * `xs` 200px · `sm` 320px · `md` 448px · `lg` 640px · `xl` 800px. Default: no cap.
+   */
+  maxHeight?: CodeBlockMaxHeight;
+  /** Initial state of the wrap-lines toggle. Default `false` (long lines scroll horizontally). */
+  defaultWrap?: boolean;
+}
+
+const MAX_HEIGHT_CLASS: Record<CodeBlockMaxHeight, string> = {
+  xs: styles.maxXs,
+  sm: styles.maxSm,
+  md: styles.maxMd,
+  lg: styles.maxLg,
+  xl: styles.maxXl,
+};
+
+const COPIED_MS = 1500;
+
+/**
+ * Syntax-highlighted code sample with copy, wrap toggle and optional language tabs.
+ * @see docs/components/CodeBlock.md
+ */
+export const CodeBlock = forwardRef<HTMLDivElement, CodeBlockProps>(function CodeBlock(
+  {
+    code = '',
+    language,
+    title,
+    samples,
+    activeSampleId,
+    defaultSampleId,
+    onSampleChange,
+    syncKey,
+    highlightLines,
+    maxHeight,
+    defaultWrap = false,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const t = useTranslation();
+  // Sanitised like Tabs does: React's `:r0:` ids are valid ids but not CSS-safe.
+  const prefix = useId().replace(/[^a-zA-Z0-9_-]/g, '_');
+  const [localPick, setLocalPick] = useState<string>();
+  const [wrap, setWrap] = useState(defaultWrap);
+  const [copyStatus, setCopyStatus] = useState<'idle' | 'copied' | 'failed'>('idle');
+  const [copyCount, setCopyCount] = useState(0);
+  const synced = useSyncedSample(syncKey);
+
+  const list: readonly CodeBlockSample[] = samples?.length
+    ? samples
+    : [{ id: 'code', label: '', code, language }];
+  const multi = list.length > 1;
+  const activeId = resolveActiveSample(
+    list.map((s) => s.id),
+    { controlled: activeSampleId, synced, own: localPick, fallback: defaultSampleId },
+  );
+  const active = list.find((s) => s.id === activeId) ?? list[0];
+  const lines = useMemo(
+    () => tokenizeLines(active.code, active.language),
+    [active.code, active.language],
+  );
+  const highlighted = highlightedLineSet(highlightLines, lines.length);
+  const lang = active.language;
+  const label =
+    title ||
+    (samples?.length === 1 && samples[0].label) ||
+    (lang && Object.hasOwn(LANGUAGE_LABELS, lang)
+      ? LANGUAGE_LABELS[lang as CodeBlockLanguage]
+      : t('codeBlock.plainText'));
+
+  // Keyed on copyCount so a re-click restarts the window; cleanup also clears on unmount.
+  useEffect(() => {
+    if (copyStatus === 'idle') return;
+    const id = setTimeout(() => setCopyStatus('idle'), COPIED_MS);
+    return () => clearTimeout(id);
+  }, [copyStatus, copyCount]);
+
+  const copy = async () => {
+    const text = active.code;
+    let ok = true;
+    try {
+      // Called synchronously inside the click so the user-activation gate holds;
+      // a missing `navigator.clipboard` throws here and lands in the catch.
+      await navigator.clipboard.writeText(text);
+    } catch {
+      ok = false;
+    }
+    setCopyStatus(ok ? 'copied' : 'failed');
+    setCopyCount((n) => n + 1);
+  };
+
+  const pick = (id: string) => {
+    setLocalPick(id);
+    if (syncKey !== undefined) setSynced(syncKey, id);
+    onSampleChange?.(id);
+  };
+
+  // {...props} first so the root's ref and className composition win (Pattern B);
+  // the ARIA-bearing structure lives on children consumers cannot reach.
+  return (
+    <div {...props} ref={ref} className={clsx(styles.root, className)}>
+      <div className={styles.header}>
+        {multi ? (
+          <Tabs
+            items={list.map(({ id, label: tabLabel }) => ({ id, label: tabLabel }))}
+            activeId={active.id}
+            onChange={pick}
+            panelIdPrefix={prefix}
+            aria-label={title}
+          />
+        ) : (
+          <span id={`${prefix}-label`} className={styles.title}>
+            {label}
+          </span>
+        )}
+        <div className={styles.actions}>
+          <Tooltip content={t('codeBlock.wrap')}>
+            <Button
+              variant="ghost"
+              size="sm"
+              iconOnly
+              aria-label={t('codeBlock.wrap')}
+              aria-pressed={wrap}
+              selected={wrap}
+              onClick={() => setWrap((w) => !w)}
+            >
+              <WrapText aria-hidden="true" />
+            </Button>
+          </Tooltip>
+          <Tooltip
+            content={copyStatus === 'failed' ? t('codeBlock.copyFailed') : t('codeBlock.copy')}
+          >
+            <Button
+              variant="ghost"
+              size="sm"
+              iconOnly
+              aria-label={t('codeBlock.copy')}
+              onClick={copy}
+            >
+              {copyStatus === 'copied' ? (
+                <Check aria-hidden="true" />
+              ) : copyStatus === 'failed' ? (
+                <X aria-hidden="true" />
+              ) : (
+                <Copy aria-hidden="true" />
+              )}
+            </Button>
+          </Tooltip>
+        </div>
+      </div>
+      {/* Always mounted (Rule 10): the copy outcome is announced, the button keeps its name. */}
+      <LiveRegion announceKey={copyCount}>
+        {copyStatus === 'copied'
+          ? t('codeBlock.copied')
+          : copyStatus === 'failed'
+            ? t('codeBlock.copyFailed')
+            : null}
+      </LiveRegion>
+      <pre
+        className={clsx(styles.body, wrap && styles.wrap, maxHeight && MAX_HEIGHT_CLASS[maxHeight])}
+        // Always a tab stop: wrap-off lines overflow horizontally, and APG gives
+        // a tabpanel without focusable content tabIndex=0. Multi: the tabpanel
+        // named by its tab. Single: a group named by the header label, since a
+        // bare <pre> may not carry a name.
+        role={multi ? 'tabpanel' : 'group'}
+        id={multi ? `${prefix}-${active.id}-panel` : undefined}
+        aria-labelledby={multi ? `${prefix}-${active.id}-tab` : `${prefix}-label`}
+        tabIndex={0}
+      >
+        <code className={styles.lines}>
+          {lines.map((tokens, i) => (
+            // Index keys: lines are derived wholesale from `code` and hold no state.
+            // Lines are inline-blocks, so the '\n' between them is a real rendered
+            // break: selection-copy, innerText and textContent all keep blank lines.
+            <Fragment key={i}>
+              {i > 0 && '\n'}
+              <span
+                data-line=""
+                data-highlighted={highlighted.has(i + 1) ? '' : undefined}
+                className={styles.line}
+              >
+                {tokens.map((token, j) => (
+                  <span key={j} className={styles[token.key]}>
+                    {token.content}
+                  </span>
+                ))}
+              </span>
+            </Fragment>
+          ))}
+        </code>
+      </pre>
+    </div>
+  );
+});

package/src/components/CodeBlock/highlight.ts

@@ -0,0 +1,179 @@
+import { Prism, normalizeTokens } from 'prism-react-renderer';
+
+export type CodeBlockLanguage =
+  | 'json'
+  | 'bash'
+  | 'javascript'
+  | 'typescript'
+  | 'python'
+  | 'go'
+  | 'kotlin'
+  | 'java'
+  | 'csharp'
+  | 'rust';
+
+export type SyntaxKey =
+  | 'keyword'
+  | 'string'
+  | 'number'
+  | 'comment'
+  | 'function'
+  | 'property'
+  | 'punctuation'
+  | 'plain';
+
+export interface CodeToken {
+  content: string;
+  key: SyntaxKey;
+}
+
+export const LANGUAGE_LABELS: Record<CodeBlockLanguage, string> = {
+  json: 'JSON',
+  bash: 'Bash',
+  javascript: 'JavaScript',
+  typescript: 'TypeScript',
+  python: 'Python',
+  go: 'Go',
+  kotlin: 'Kotlin',
+  java: 'Java',
+  csharp: 'C#',
+  rust: 'Rust',
+};
+
+// prism-react-renderer ships no bash grammar; register a small one once.
+// Prism is a shared singleton: any consumer of the same prism-react-renderer instance sees it.
+if (!Prism.languages.bash) {
+  const variable = /\$(?:\w+|\{[^}]*\})/;
+  Prism.languages.bash = {
+    comment: { pattern: /(^|\s)#.*/, lookbehind: true },
+    string: [
+      {
+        pattern: /"(?:\\[\s\S]|[^"\\])*"/,
+        greedy: true,
+        inside: { variable },
+      },
+      { pattern: /'[^']*'/, greedy: true },
+    ],
+    variable,
+    function: { pattern: /(^|[;|&]\s*)[\w.][\w.-]*/m, lookbehind: true },
+    parameter: /--?[\w-]+/,
+    operator: /&&|\|\||[|;<>]/,
+    punctuation: /\\/,
+  };
+}
+
+// Nor Java / C#: both are C-like, so extend `clike` (comments, punctuation, functions) with their keywords.
+// Needs a lowercase letter, so ALL_CAPS constants stay plain (as do `T`, `IO`, `URL`).
+const pascalCase = /\b[A-Z]\w*[a-z]\w*\b/;
+if (!Prism.languages.java) {
+  Prism.languages.java = Prism.languages.extend('clike', {
+    keyword:
+      /\b(?:abstract|assert|break|case|catch|class|const|continue|default|do|else|enum|exports|extends|final|finally|for|goto|if|implements|import|instanceof|interface|module|native|new|non-sealed|null|package|permits|private|protected|public|record|requires|return|sealed|static|strictfp|super|switch|synchronized|this|throw|throws|transient|try|var|void|volatile|while|yield|boolean|byte|char|double|float|int|long|short)\b/,
+    string: {
+      pattern: /"""[\s\S]*?"""|"(?:\\.|[^"\\\r\n])*"|'(?:\\.|[^'\\\r\n]){1,6}'/,
+      greedy: true,
+    },
+    number: /\b0x[\da-f_]+l?\b|(?:\b\d[\d_]*\.?[\d_]*|\B\.\d[\d_]*)(?:e[+-]?\d[\d_]*)?[dfl]?/i,
+    'class-name': pascalCase,
+  });
+  Prism.languages.insertBefore('java', 'class-name', {
+    annotation: { pattern: /@\w+/, alias: 'builtin' },
+  });
+}
+if (!Prism.languages.csharp) {
+  Prism.languages.csharp = Prism.languages.extend('clike', {
+    keyword:
+      /\b(?:abstract|as|async|await|base|bool|break|byte|case|catch|char|checked|class|const|continue|decimal|default|delegate|do|double|dynamic|else|enum|event|explicit|extern|finally|fixed|float|for|foreach|get|goto|if|implicit|in|init|int|interface|internal|is|lock|long|namespace|nameof|new|null|object|operator|out|override|params|partial|private|protected|public|readonly|record|ref|required|return|sbyte|sealed|set|short|sizeof|stackalloc|static|string|struct|switch|this|throw|try|typeof|uint|ulong|unchecked|unsafe|ushort|using|var|virtual|void|volatile|when|where|while|with|yield)\b/,
+    // Raw `"""`, verbatim `@"` / `$@"` / `@$"`, regular / interpolated, char.
+    string: {
+      pattern:
+        /\$*"""[\s\S]*?"""|(?:\$@|@\$|@)"(?:""|[^"])*"|\$?"(?:\\.|[^"\\\r\n])*"|'(?:\\.|[^'\\\r\n]){1,6}'/,
+      greedy: true,
+    },
+    number:
+      /\b0x[\da-f_]+\b|(?:\b\d[\d_]*\.?[\d_]*|\B\.\d[\d_]*)(?:e[+-]?\d[\d_]*)?(?:ul|lu|[dfmlu])?/i,
+    'class-name': pascalCase,
+  });
+  // Before (greedy) `string`, so `[Route("api/[controller]")]` is matched (and coloured) whole.
+  Prism.languages.insertBefore('csharp', 'string', {
+    attribute: {
+      // The lookahead (end of line, identifier, next `[`, comment) rejects `[Foo, Bar],` / `[Key] = 1` initializers.
+      pattern:
+        /^(\s*)\[(?:\w+:\s*)?[A-Z](?:"(?:\\.|[^"\\\r\n])*"|\[[^\]\r\n]*\]|[^\]"\r\n])*\](?=[ \t]*(?:$|[\w[]|\/[/*]))/m,
+      lookbehind: true,
+      greedy: true,
+      alias: 'builtin',
+    },
+  });
+}
+
+const ALIASES: Record<string, string> = {
+  shell: 'bash',
+  sh: 'bash',
+  js: 'javascript',
+  ts: 'typescript',
+  py: 'python',
+  golang: 'go',
+  kt: 'kotlin',
+  kts: 'kotlin',
+  cs: 'csharp',
+  'c#': 'csharp',
+  rs: 'rust',
+};
+
+const KEY_BY_TYPE: Record<string, SyntaxKey> = {};
+const TYPE_GROUPS: Record<Exclude<SyntaxKey, 'plain'>, string[]> = {
+  keyword: ['keyword', 'builtin', 'important', 'atrule', 'boolean'],
+  string: ['string', 'char', 'attr-value', 'url', 'regex', 'template-string'],
+  number: ['number', 'constant'],
+  comment: ['comment', 'prolog', 'doctype', 'cdata'],
+  function: ['function', 'class-name'],
+  property: ['property', 'attr-name', 'tag', 'variable', 'parameter', 'selector'],
+  punctuation: ['punctuation', 'operator'],
+};
+for (const [key, types] of Object.entries(TYPE_GROUPS)) {
+  for (const type of types) KEY_BY_TYPE[type] = key as SyntaxKey;
+}
+
+const keyOf = (types: string[]): SyntaxKey => {
+  for (const type of types) if (KEY_BY_TYPE[type]) return KEY_BY_TYPE[type];
+  return 'plain';
+};
+
+/** One array of merged tokens per rendered line. Unknown languages render as plain text. */
+export function tokenizeLines(code: string, language?: string): CodeToken[][] {
+  const src = code.replace(/\r\n?/g, '\n').replace(/\n$/, '');
+  const name = language && (Object.hasOwn(ALIASES, language) ? ALIASES[language] : language);
+  // Allow-list: Prism bundles ~40 grammars (and helpers like `extend`) we don't style.
+  const grammar = name && Object.hasOwn(LANGUAGE_LABELS, name) && Prism.languages[name];
+  if (!grammar) return src.split('\n').map((l) => [{ content: l, key: 'plain' as const }]);
+
+  return normalizeTokens(Prism.tokenize(src, grammar)).map((line) => {
+    const out: CodeToken[] = [];
+    for (const { types, content, empty } of line) {
+      // normalizeTokens pads blank lines with a "\n" token; it would add a second line box.
+      if (empty) continue;
+      const key = keyOf(types);
+      const last = out[out.length - 1];
+      if (last?.key === key) last.content += content;
+      else out.push({ content, key });
+    }
+    return out;
+  });
+}
+
+/** Expands `[a, b]` ranges and single numbers into a 1-based set clipped to 1..lineCount. */
+export function highlightedLineSet(
+  spec: readonly (number | readonly [number, number])[] | undefined,
+  lineCount: number,
+): ReadonlySet<number> {
+  const set = new Set<number>();
+  for (const item of spec ?? []) {
+    const [a, b] = typeof item === 'number' ? [item, item] : item;
+    if (!Number.isInteger(a) || !Number.isInteger(b)) continue;
+    for (let n = Math.max(1, Math.min(a, b)); n <= Math.min(lineCount, Math.max(a, b)); n++) {
+      set.add(n);
+    }
+  }
+  return set;
+}

package/src/components/CodeBlock/index.ts

@@ -0,0 +1,8 @@
+export { CodeBlock } from './CodeBlock';
+export type {
+  CodeBlockProps,
+  CodeBlockSample,
+  CodeBlockHighlightLines,
+  CodeBlockMaxHeight,
+  CodeBlockLanguage,
+} from './CodeBlock';

package/src/components/CodeBlock/sampleSync.ts

@@ -0,0 +1,42 @@
+import { useCallback, useSyncExternalStore } from 'react';
+
+// In-memory only: no window, no storage. Module-level state is per-page-load,
+// which is the scope a syncKey is meant to span.
+const values = new Map<string, string>();
+const listeners = new Map<string, Set<() => void>>();
+
+export function getSynced(key: string): string | undefined {
+  return values.get(key);
+}
+
+export function setSynced(key: string, sampleId: string): void {
+  values.set(key, sampleId);
+  listeners.get(key)?.forEach((onChange) => onChange());
+}
+
+export function subscribeSynced(key: string, onChange: () => void): () => void {
+  const set = listeners.get(key) ?? new Set<() => void>();
+  set.add(onChange);
+  listeners.set(key, set);
+  return () => {
+    set.delete(onChange);
+    if (set.size === 0 && listeners.get(key) === set) listeners.delete(key);
+  };
+}
+
+export function useSyncedSample(key: string | undefined): string | undefined {
+  const subscribe = useCallback(
+    (onChange: () => void) => (key === undefined ? () => {} : subscribeSynced(key, onChange)),
+    [key],
+  );
+  const getSnapshot = useCallback(() => (key === undefined ? undefined : getSynced(key)), [key]);
+  return useSyncExternalStore(subscribe, getSnapshot, () => undefined);
+}
+
+export function resolveActiveSample(
+  ids: readonly string[],
+  opts: { controlled?: string; synced?: string; own?: string; fallback?: string },
+): string {
+  const candidates = [opts.controlled, opts.synced, opts.own, opts.fallback];
+  return candidates.find((id): id is string => id !== undefined && ids.includes(id)) ?? ids[0];
+}