An open source design system that's fully customizable and agent ready
TypeScript
feat(Markdown, RichText, DiffViewer): codeLanguages lists CodeBlock language values (#8489)
Cindy Zhangfabf5e699b56
diff --git a/.changeset/markdown-code-languages.md b/.changeset/markdown-code-languages.mdnew file mode 100644index 0000000000..dcdea03db9--- /dev/null+++ b/.changeset/markdown-code-languages.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feat] `Markdown` takes `codeLanguages`, a list of CodeBlock language values, each imported on its own or made with `createCodeLanguage`. A fence whose language word names a listed value renders with that value, ahead of a built-in language with the same name. A `diff-<name>` fence gets the diff layer over that value.++@cixzhangdiff --git a/.changeset/richtext-code-languages.md b/.changeset/richtext-code-languages.mdnew file mode 100644index 0000000000..c26460fb6a--- /dev/null+++ b/.changeset/richtext-code-languages.md@@ -0,0 +1,7 @@+---+'@astryxdesign/richtext': patch+---++[feat] `RichTextEditor` and `RichTextView` take `codeLanguages`, the same list of CodeBlock language values that `Markdown` takes. A fence named by a listed value is coloured with that value and labelled with its name, so reading and editing match.++@cixzhangdiff --git a/apps/storybook/stories/RichTextEditor.stories.tsx b/apps/storybook/stories/RichTextEditor.stories.tsxindex 24fffbb24b..00243cdc80 100644--- a/apps/storybook/stories/RichTextEditor.stories.tsx+++ b/apps/storybook/stories/RichTextEditor.stories.tsx@@ -12,6 +12,8 @@ import {type RichTextEditorRef,} from '@astryxdesign/richtext';import type {EditorState} from 'lexical';+import {objectiveC} from '@astryxdesign/core/CodeBlock/languages/objective-c';+import {thrift} from '@astryxdesign/core/CodeBlock/languages/thrift';import {BOLD_STAR, ITALIC_STAR, UNORDERED_LIST} from '@lexical/markdown';import {$getRoot} from 'lexical';import {@@ -593,3 +595,31 @@ export const MarkdownParityLongDocument: MarkdownParityStory = {hostWidth: '680px',},};++const OBJC_FENCE = markdownToEditorStateJSON(+ '```objc\n@interface Greeter : NSObject\n@end\n```',+);++const THRIFT_FENCE = markdownToEditorStateJSON(+ '```thrift\n# A user record\nstruct User {\n 1: required string name;\n}\n```',+);++/**+ * Code blocks colour a fence named by a value in `codeLanguages`, as Markdown+ * does, and label it with the value's name; without it the fence stays plain.+ */+export const CodeLanguageModules: Story = {+ render: () => (+ <div style={{display: 'grid', gap: 16, maxWidth: 520}}>+ <div data-testid="listed">+ <RichTextView value={THRIFT_FENCE} codeLanguages={[thrift]} />+ </div>+ <div data-testid="listed-renamed">+ <RichTextView value={OBJC_FENCE} codeLanguages={[objectiveC]} />+ </div>+ <div data-testid="unlisted">+ <RichTextView value={THRIFT_FENCE} />+ </div>+ </div>+ ),+};diff --git a/packages/core/src/CodeBlock/grammar.ts b/packages/core/src/CodeBlock/grammar.tsindex 89d885dc67..c9acde5d51 100644--- a/packages/core/src/CodeBlock/grammar.ts+++ b/packages/core/src/CodeBlock/grammar.ts@@ -37,7 +37,8 @@ export type CodeLanguageTokenize = (/*** A language value: an Astryx module from* `@astryxdesign/core/CodeBlock/languages/<path>`, or a custom language from- * `createCodeLanguage`. Pass it as `language`.+ * `createCodeLanguage`. Pass it as `language`, or list it in `codeLanguages`+ * on Markdown, RichText, and DiffViewer.*/export type CodeLanguage = {/** The identifier the label shows, such as `graphql`; shown verbatim. */@@ -97,7 +98,8 @@ export type CreateCodeLanguageOptions = CodeLanguageMeta & {/*** Make a custom language value from your own tokenize function. It works- * everywhere an Astryx language module does, starting with `language`.+ * everywhere an Astryx language module does: as `language`, and in+ * `codeLanguages` on Markdown, RichText, and DiffViewer.** @example* ```@@ -159,6 +161,20 @@ export function languageKey(language: string | CodeLanguage): string {: (language.identifiers[0] ?? language.name);}+/** Whether two lists name the same values in the same order. */+export function sameCodeLanguageList(+ a: ReadonlyArray<CodeLanguage> | undefined,+ b: ReadonlyArray<CodeLanguage> | undefined,+): boolean {+ if (a === b) {+ return true;+ }+ if (a == null || b == null || a.length !== b.length) {+ return false;+ }+ return a.every((language, i) => language === b[i]);+}+/** The listed value that claims `word`; a later entry wins. */export function listedLanguage(languages: ReadonlyArray<CodeLanguage> | undefined,diff --git a/packages/core/src/Markdown/Markdown.codeLanguages.test.tsx b/packages/core/src/Markdown/Markdown.codeLanguages.test.tsxnew file mode 100644index 0000000000..01e34124ae--- /dev/null+++ b/packages/core/src/Markdown/Markdown.codeLanguages.test.tsx@@ -0,0 +1,137 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Markdown.codeLanguages.test.tsx+ * @input Markdown, CodeBlock language modules, createCodeLanguage+ * @output Markdown FR30 evidence: a fence naming a value in `codeLanguages`+ * renders with it, ahead of a built-in; a later entry wins; a+ * `diff-<identifier>` fence takes the diff layer over it; a custom `code`+ * renderer keeps receiving the fence word+ * @position Markdown FR30 evidence+ */++import {render} from '@testing-library/react';+import {describe, expect, it} from 'vitest';+import {createCodeLanguage} from '../CodeBlock/grammar';+import {objectiveC} from '../CodeBlock/languages/objective-c';+import {thrift} from '../CodeBlock/languages/thrift';+import {Markdown} from './Markdown';++const THRIFT = 'struct User {\n 1: required string name;\n}';++function keywordTexts(root: ParentNode): string[] {+ return Array.from(root.querySelectorAll('.astryx-token-keyword')).map(+ node => node.textContent ?? '',+ );+}++describe('Markdown codeLanguages (Markdown FR30)', () => {+ const fence = '```thrift\n' + THRIFT + '\n```';++ it('paints a fence naming a listed value, and only then', () => {+ const unlisted = render(<Markdown>{fence}</Markdown>);+ expect(keywordTexts(unlisted.container)).toEqual([]);+ const listed = render(+ <Markdown codeLanguages={[thrift]}>{fence}</Markdown>,+ );+ // jsdom has no CSS Custom Highlight API, so CodeBlock falls back to spans.+ expect(keywordTexts(listed.container)).toContain('struct');+ });++ it('labels a matched fence with the value name, not the fence word', () => {+ const fence = '```objc\n@interface A : NSObject\n@end\n```';+ const {container} = render(+ <Markdown codeLanguages={[objectiveC]}>{fence}</Markdown>,+ );+ expect(container.textContent).toContain('objective-c');+ expect(container.querySelector('pre')?.getAttribute('data-language')).toBe(+ 'objective-c',+ );+ });++ it('lets a later entry win a shared identifier', () => {+ const mine = createCodeLanguage({+ name: 'thrift',+ identifiers: ['thrift'],+ tokenize: () => [{type: 'string', start: 0, end: 6}],+ });+ const {container} = render(+ <Markdown codeLanguages={[thrift, mine]}>{fence}</Markdown>,+ );+ expect(keywordTexts(container)).toEqual([]);+ expect(container.querySelector('.astryx-token-string')?.textContent).toBe(+ 'struct',+ );+ });++ it('lets a listed value claim a built-in identifier', () => {+ const myTs = createCodeLanguage({+ name: 'ts',+ identifiers: ['ts'],+ tokenize: () => [{type: 'string', start: 0, end: 5}],+ });+ const fenceTs = '```ts\nconst a = 1;\n```';+ const builtIn = render(<Markdown>{fenceTs}</Markdown>);+ expect(keywordTexts(builtIn.container)).toContain('const');+ const listed = render(+ <Markdown codeLanguages={[myTs]}>{fenceTs}</Markdown>,+ );+ expect(keywordTexts(listed.container)).toEqual([]);+ expect(+ listed.container.querySelector('.astryx-token-string')?.textContent,+ ).toBe('const');+ });++ it('takes the diff layer over a listed value for a diff-<identifier> fence', () => {+ const diff = '```diff-thrift\n+struct User {}\n```';+ const {container} = render(+ <Markdown codeLanguages={[thrift]}>{diff}</Markdown>,+ );+ expect(keywordTexts(container)).toContain('struct');+ expect(container.querySelector('[data-diff="added"]')).not.toBeNull();+ });++ it('does not re-render the document when an inline list names the same values', () => {+ // An inline plugin's render runs each time Markdown renders its blocks.+ let renders = 0;+ const counting = [+ {+ pattern: /marker/g,+ render: () => {+ renders++;+ return 'marker';+ },+ },+ ];+ const doc = 'A marker here.\n\n' + fence;+ const {rerender} = render(+ <Markdown codeLanguages={[thrift]} inlinePlugins={counting}>+ {doc}+ </Markdown>,+ );+ const first = renders;+ rerender(+ <Markdown codeLanguages={[thrift]} inlinePlugins={counting}>+ {doc}+ </Markdown>,+ );+ expect(renders).toBe(first);+ });++ it('keeps a custom code renderer receiving the fence word', () => {+ const seen: unknown[] = [];+ render(+ <Markdown+ codeLanguages={[thrift]}+ components={{+ code: ({language}) => {+ seen.push(language);+ return null;+ },+ }}>+ {fence}+ </Markdown>,+ );+ expect(seen).toEqual(['thrift']);+ });+});diff --git a/packages/core/src/Markdown/Markdown.doc.mjs b/packages/core/src/Markdown/Markdown.doc.mjsindex 9e5639c530..c9946f76e9 100644--- a/packages/core/src/Markdown/Markdown.doc.mjs+++ b/packages/core/src/Markdown/Markdown.doc.mjs@@ -159,6 +159,12 @@ export const docs = {description:"Opt-in autolinking of bare URLs and emails. 'gfm' applies GitHub-Flavored Markdown autolink-literal rules: bare https?://..., www...., <scheme:url>, <email>, and user@host all become links. Trailing sentence punctuation and unbalanced trailing close-parens are excluded; matches inside code spans, code blocks, existing links, and image alt text are skipped. Default behavior (option unset) is unchanged.",},+ {+ name: 'codeLanguages',+ type: 'ReadonlyArray<CodeLanguage>',+ description:+ "CodeBlock language values a fence may name, each imported on its own (e.g. graphql from @astryxdesign/core/CodeBlock/languages/graphql) or made with createCodeLanguage. A fence whose language word is one of a listed value's identifiers renders with it, ahead of a built-in; a diff-<identifier> fence takes the diff layer over it; a later entry wins. Pass the same list to RichTextEditor or RichTextView so read and edit match.",+ },{name: 'components',type: 'MarkdownComponents',@@ -686,6 +692,12 @@ export const docsZh = {description:"可选的裸 URL 和电子邮箱自动链接。设为 'gfm' 启用 GitHub Flavored Markdown 自动链接规则:裸 https?://、www.、<scheme:url>、<email> 以及 user@host 都会变成链接。末尾句末标点和不平衡的末尾右括号会被排除;代码块、现有链接和图片替代文本内部的匹配会被跳过。默认为关闭。",},+ {+ name: 'codeLanguages',+ type: 'ReadonlyArray<CodeLanguage>',+ description:+ '代码块可以命名的 CodeBlock 语言值,每个单独导入(例如从 @astryxdesign/core/CodeBlock/languages/graphql 导入 graphql),或用 createCodeLanguage 创建。语言词属于所列值标识符的代码块用该值渲染,优先于内置语言;后列出的条目优先。',+ },{name: 'components',type: 'MarkdownComponents',diff --git a/packages/core/src/Markdown/Markdown.tsx b/packages/core/src/Markdown/Markdown.tsxindex 36d8422067..e33a355583 100644--- a/packages/core/src/Markdown/Markdown.tsx+++ b/packages/core/src/Markdown/Markdown.tsx@@ -9,7 +9,7 @@* @position Core implementation; renders markdown as Astryx components*/-import {Suspense, useMemo, useRef} from 'react';+import {Suspense, useMemo, useRef, useState} from 'react';import type React from 'react';import {Fragment} from 'react';import * as stylex from '@stylexjs/stylex';@@ -28,6 +28,8 @@ import {import type {TextDisplay} from '../theme/types';import {CodeBlock, Code} from '../CodeBlock';import {parseFenceLanguage} from '../CodeBlock/tokenizer';+import {listedLanguage, sameCodeLanguageList} from '../CodeBlock/grammar';+import type {CodeLanguage} from '../CodeBlock/grammar';import {CheckboxList} from '../CheckboxList/CheckboxList';import {CheckboxListItem} from '../CheckboxList/CheckboxListItem';import {Blockquote} from '../Blockquote/Blockquote';@@ -319,6 +321,15 @@ export interface MarkdownProps<* literal text.*/autolink?: 'gfm';+ /**+ * CodeBlock language values a fence may name: each one imported on its+ * own, such as `graphql` from `@astryxdesign/core/CodeBlock/languages/graphql`,+ * or made with `createCodeLanguage`. A fence whose language word is one of+ * a listed value's identifiers renders with that value, ahead of a built-in+ * with the same identifier; a later entry wins. Without it, fences render+ * as they do today.+ */+ codeLanguages?: ReadonlyArray<CodeLanguage>;}// ---------------------------------------------------------------------------@@ -1326,6 +1337,8 @@ function renderBlock(components: Partial<MarkdownComponents> | undefined,preparedPlugins: PreparedMarkdownPlugins | undefined,t: TranslatorFn,+ // Language values fences may name (component:Markdown FR30).+ codeLanguages: ReadonlyArray<CodeLanguage> | undefined,headingProjection?: MarkdownHeadingProjection,// How many lists enclose this block (spec:AST-061 DEC-6).listDepth = 0,@@ -1500,7 +1513,10 @@ function renderBlock(const diffLanguage = isDiff? fence.language.match(/^\w*/)?.[0] || 'plaintext': undefined;- const language = diffLanguage ?? legacyLanguage;+ const fenceWord = diffLanguage ?? legacyLanguage;+ // A listed language value claims its identifiers ahead of a built-in+ // with the same identifier (component:Markdown FR30).+ const language = listedLanguage(codeLanguages, fenceWord) ?? fenceWord;// A semantic-fence proposal claims its fence before the host's code// renderer (spec:AST-036 FR17). The host renderer, or the default Code// block without one, draws every unclaimed fence and is the fallback@@ -1617,6 +1633,7 @@ function renderBlock(components,preparedPlugins,t,+ codeLanguages,headingProjection,listDepth,),@@ -1660,6 +1677,7 @@ function renderBlock(components,preparedPlugins,t,+ codeLanguages,headingProjection,listDepth,),@@ -1739,6 +1757,7 @@ function renderBlock(components,preparedPlugins,t,+ codeLanguages,headingProjection,listDepth + 1,),@@ -1828,6 +1847,7 @@ function renderBlock(components,preparedPlugins,t,+ codeLanguages,headingProjection,listDepth + 1,),@@ -2114,6 +2134,7 @@ export function Markdown<plugins,inlinePlugins,autolink,+ codeLanguages: codeLanguagesProp,xstyle,className,style,@@ -2122,6 +2143,13 @@ export function Markdown<...props}: MarkdownProps<Plugins>): React.ReactElement {const t = useTranslator();+ // Keep one list while it names the same values, so an inline+ // `codeLanguages={[…]}` does not re-render every block on each parent+ // render (adjusting state during render, not in an Effect).+ const [codeLanguages, setCodeLanguages] = useState(codeLanguagesProp);+ if (!sameCodeLanguageList(codeLanguages, codeLanguagesProp)) {+ setCodeLanguages(codeLanguagesProp);+ }const LinkComponent = useLinkComponent();// Links read the caller's handler when clicked, so a handler recreated on// every caller render does not invalidate the memoized document below.@@ -2384,6 +2412,7 @@ export function Markdown<components,preparedPlugins,t,+ codeLanguages,headingProjection,),);@@ -2405,6 +2434,7 @@ export function Markdown<preparedPlugins,t,headingProjection,+ codeLanguages,]);if (display === 'inline') {diff --git a/packages/lab/src/DiffViewer/DiffViewer.doc.mjs b/packages/lab/src/DiffViewer/DiffViewer.doc.mjsindex d1f9bc55ed..ba9a7b0045 100644--- a/packages/lab/src/DiffViewer/DiffViewer.doc.mjs+++ b/packages/lab/src/DiffViewer/DiffViewer.doc.mjs@@ -112,9 +112,15 @@ export const docs = {},{name: 'language',- type: 'string',+ type: 'string | CodeLanguage',description:- 'Syntax-highlighting language. Defaults to one inferred from the file extension; unknown extensions render as plain text.',+ 'Syntax-highlighting language: a built-in identifier, or a CodeBlock language value imported on its own (e.g. graphql from @astryxdesign/core/CodeBlock/languages/graphql) or made with createCodeLanguage. Defaults to one inferred from the file name or extension among the built-ins and codeLanguages; an unmatched file renders as plain text.',+ },+ {+ name: 'codeLanguages',+ type: 'ReadonlyArray<CodeLanguage>',+ description:+ 'Language values the file name or extension may infer, such as [graphql, dockerfile]; a later entry wins. Pass the same list to every DiffViewer on a review page.',},{name: 'hasLineNumbers',diff --git a/packages/lab/src/DiffViewer/DiffViewer.test.tsx b/packages/lab/src/DiffViewer/DiffViewer.test.tsxindex 7270c4884c..908a76aba0 100644--- a/packages/lab/src/DiffViewer/DiffViewer.test.tsx+++ b/packages/lab/src/DiffViewer/DiffViewer.test.tsx@@ -7,6 +7,10 @@ import {createRef} from 'react';import {DiffViewer} from './DiffViewer';import {parseUnifiedDiff} from './parseUnifiedDiff';import type {DiffViewerLineRef} from './diffTypes';+import {createDiffFile} from './createDiffFile';+import {dockerfile} from '@astryxdesign/core/CodeBlock/languages/dockerfile';+import {graphql} from '@astryxdesign/core/CodeBlock/languages/graphql';+import {createCodeLanguage} from '@astryxdesign/core/CodeBlock';const PATCH = `diff --git a/src/greet.ts b/src/greet.ts--- a/src/greet.ts@@ -72,6 +76,73 @@ describe('DiffViewer', () => {expect(container.querySelector('.astryx-token-keyword')).not.toBeNull();});+ describe('language values (CodeBlock FR13)', () => {+ const keywords = (root: ParentNode) =>+ Array.from(root.querySelectorAll('.astryx-token-keyword')).map(+ node => node.textContent,+ );+ const schema = createDiffFile({+ oldValue: 'type User {}\n',+ newValue: 'type User { name: String }\n',+ newPath: 'api/schema.graphql',+ });++ it('takes a language value as language', () => {+ const plain = render(<DiffViewer file={schema} language="graphql" />);+ expect(keywords(plain.container)).toEqual([]);+ const {container} = render(+ <DiffViewer file={schema} language={graphql} />,+ );+ expect(keywords(container)).toContain('type');+ });++ it('infers a listed value from the file extension or name', () => {+ const unlisted = render(<DiffViewer file={schema} />);+ expect(keywords(unlisted.container)).toEqual([]);+ const listed = render(+ <DiffViewer file={schema} codeLanguages={[dockerfile, graphql]} />,+ );+ expect(keywords(listed.container)).toContain('type');+ const docker = createDiffFile({+ oldValue: 'FROM node:20\n',+ newValue: 'FROM node:22\n',+ newPath: 'Dockerfile',+ });+ const byName = render(+ <DiffViewer file={docker} codeLanguages={[graphql, dockerfile]} />,+ );+ expect(keywords(byName.container)).toContain('FROM');+ });++ it('infers a custom language from its extension', () => {+ const zig = createCodeLanguage({+ name: 'zig',+ identifiers: ['zig'],+ fileExtensions: ['zig'],+ tokenize: () => [{type: 'keyword', start: 0, end: 3}],+ });+ const file = createDiffFile({+ oldValue: 'pub a\n',+ newValue: 'pub b\n',+ newPath: 'src/main.zig',+ });+ const {container} = render(+ <DiffViewer file={file} codeLanguages={[zig]} />,+ );+ expect(keywords(container)).toContain('pub');+ });++ it('infers the newer built-ins from their extensions', () => {+ const rust = createDiffFile({+ oldValue: 'fn a() {}\n',+ newValue: 'fn b() {}\n',+ newPath: 'src/lib.rs',+ });+ const {container} = render(<DiffViewer file={rust} />);+ expect(keywords(container)).toContain('fn');+ });+ });+it('marks changed lines for assistive technology', () => {const {container} = render(<DiffViewer file={FILE} />);const addedCells = container.querySelectorAll('td[data-diff="added"]');diff --git a/packages/lab/src/DiffViewer/DiffViewer.tsx b/packages/lab/src/DiffViewer/DiffViewer.tsxindex f221bbfa78..ada55d1fd5 100644--- a/packages/lab/src/DiffViewer/DiffViewer.tsx+++ b/packages/lab/src/DiffViewer/DiffViewer.tsx@@ -54,6 +54,7 @@ import type {BaseProps} from '@astryxdesign/core';import {ensureHighlightStyles,tokenize,+ type CodeLanguage,type SyntaxToken,type TokenLine,} from '@astryxdesign/core/CodeBlock';@@ -131,10 +132,20 @@ export interface DiffViewerProps extends BaseProps<HTMLDivElement> {*/viewMode?: DiffViewerViewMode;/**- * Syntax-highlighting language. Defaults to one inferred from the file's- * extension; unknown extensions render as plain text.+ * Syntax-highlighting language: a built-in identifier such as `'rust'`, or+ * a language value — a module imported on its own, such as `graphql` from+ * `@astryxdesign/core/CodeBlock/languages/graphql`, or one made with+ * `createCodeLanguage`. Defaults to one inferred from the file's name or+ * extension among the built-ins and `codeLanguages`; an unmatched file+ * renders as plain text.*/- language?: string;+ language?: string | CodeLanguage;+ /**+ * Language values the file's name or extension may infer, such as+ * `[graphql, dockerfile]`; a later entry wins. Pass the same list to every+ * DiffViewer on a review page.+ */+ codeLanguages?: ReadonlyArray<CodeLanguage>;/*** Show the old and new line-number gutters.* @default true@@ -246,18 +257,49 @@ const EXTENSION_LANGUAGES: Record<string, string> = {yml: 'yaml',md: 'markdown',markdown: 'markdown',+ c: 'c',+ h: 'c',+ cpp: 'cpp',+ cc: 'cpp',+ cxx: 'cpp',+ hpp: 'cpp',+ hh: 'cpp',+ sql: 'sql',+ rs: 'rust',+ kt: 'kotlin',+ kts: 'kotlin',+ swift: 'swift',+ go: 'go',};-function inferLanguage(path: string | null): string {+/**+ * The language a file's name or extension infers: a listed value first (a+ * later entry wins), then a built-in, else plain text (CodeBlock FR13).+ */+function inferLanguage(+ path: string | null,+ codeLanguages: ReadonlyArray<CodeLanguage> | undefined,+): string | CodeLanguage {if (path == null) {return 'plaintext';}const base = path.slice(path.lastIndexOf('/') + 1);const dot = base.lastIndexOf('.');- if (dot <= 0) {- return 'plaintext';+ const extension = dot > 0 ? base.slice(dot + 1).toLowerCase() : null;+ if (codeLanguages != null) {+ for (let i = codeLanguages.length - 1; i >= 0; i--) {+ const language = codeLanguages[i];+ if (+ language.fileNames.includes(base) ||+ (extension != null && language.fileExtensions.includes(extension))+ ) {+ return language;+ }+ }}- return EXTENSION_LANGUAGES[base.slice(dot + 1).toLowerCase()] ?? 'plaintext';+ return extension == null+ ? 'plaintext'+ : (EXTENSION_LANGUAGES[extension] ?? 'plaintext');}// ---------------------------------------------------------------------------@@ -337,7 +379,7 @@ function addInlineEmphasis(*/function buildCells(file: DiffViewerFile,- language: string,+ language: string | CodeLanguage,inlineHighlight: DiffViewerInlineHighlight,): LineCell[][] {return file.hunks.map((hunk, hunkIndex) => {@@ -1063,6 +1105,7 @@ export function DiffViewer({file,viewMode = 'unified',language: languageProp,+ codeLanguages,hasLineNumbers = true,isWrapped = false,changeIndicator = 'classic',@@ -1090,7 +1133,7 @@ export function DiffViewer({}, []);const path = file.newPath ?? file.oldPath;- const language = languageProp ?? inferLanguage(path);+ const language = languageProp ?? inferLanguage(path, codeLanguages);const displayPath =file.status === 'renamed' && file.oldPath != null && file.newPath != null? t('@astryx.diffViewer.renamedPath', {diff --git a/packages/richtext/src/CodeBlockHeaderPlugin.tsx b/packages/richtext/src/CodeBlockHeaderPlugin.tsxindex 1d39b7551b..a09f999284 100644--- a/packages/richtext/src/CodeBlockHeaderPlugin.tsx+++ b/packages/richtext/src/CodeBlockHeaderPlugin.tsx@@ -25,6 +25,8 @@ import {Icon} from '@astryxdesign/core/Icon';import {IconButton} from '@astryxdesign/core/IconButton';import {useClipboard} from '@astryxdesign/core/hooks';import {useTranslator} from '@astryxdesign/core/i18n';+import type {CodeLanguage} from '@astryxdesign/core/CodeBlock';+import {listedLanguage} from './codeLanguages';import {fontWeightVars,spacingVars,@@ -119,8 +121,11 @@ function samePlacements(function CodeBlockHeader({placement,+ label,}: {readonly placement: HeaderPlacement;+ /** The matched language value's name, when a listed value claims the fence. */+ readonly label?: string;}): JSX.Element {const [editor] = useLexicalComposerContext();const t = useTranslator();@@ -170,7 +175,7 @@ function CodeBlockHeader({<divdata-richtext-code-header=""{...stylex.props(styles.header, position)}>- <span {...stylex.props(styles.title)}>{placement.language}</span>+ <span {...stylex.props(styles.title)}>{label ?? placement.language}</span>{copyButton}</div>);@@ -180,7 +185,12 @@ function CodeBlockHeader({* Draws a header over each top-level code block and keeps it there as the* document, the editor's size, or the window changes.*/-export function CodeBlockHeaderPlugin(): JSX.Element {+export function CodeBlockHeaderPlugin({+ codeLanguages,+}: {+ /** Language values a fence may name; a matched fence shows the value's name. */+ codeLanguages?: ReadonlyArray<CodeLanguage>;+} = {}): JSX.Element {const [editor] = useLexicalComposerContext();const [placements, setPlacements] = useState<ReadonlyArray<HeaderPlacement>>([],@@ -255,7 +265,17 @@ export function CodeBlockHeaderPlugin(): JSX.Element {return (<>{placements.map(placement => (- <CodeBlockHeader key={placement.key} placement={placement} />+ <CodeBlockHeader+ key={placement.key}+ placement={placement}+ // A fence matched in `codeLanguages` shows the value's name, as+ // Markdown does (spec:AST-061).+ label={+ placement.language == null+ ? undefined+ : listedLanguage(codeLanguages, placement.language)?.name+ }+ />))}</>);diff --git a/packages/richtext/src/CodeSyntaxPlugin.test.tsx b/packages/richtext/src/CodeSyntaxPlugin.test.tsxindex b2419b6536..69569d5b52 100644--- a/packages/richtext/src/CodeSyntaxPlugin.test.tsx+++ b/packages/richtext/src/CodeSyntaxPlugin.test.tsx@@ -3,6 +3,8 @@import {describe, it, expect} from 'vitest';import {render, screen} from '@testing-library/react';import {tokenize} from '@astryxdesign/core/CodeBlock';+import {thrift} from '@astryxdesign/core/CodeBlock/languages/thrift';+import {listedLanguage, sameLanguages} from './codeLanguages';import {renderedTokens} from './CodeSyntaxPlugin';import {RichTextView} from './RichTextView';import {markdownToEditorStateJSON} from './markdownSerializers';@@ -14,6 +16,24 @@ describe('code block syntax colors (spec:AST-061 FR1)', () => {expect(renderedTokens(code, 'ts', code)).toEqual(tokenize(code, 'ts'));});+ it('paints a listed language value, as Markdown does (CodeBlock FR13)', () => {+ const idl = 'struct User {}';+ expect(renderedTokens(idl, 'thrift', idl)?.flat()).toEqual([]);+ expect(+ renderedTokens(idl, listedLanguage([thrift], 'thrift') ?? 'thrift', idl)+ ?.flat()+ .map(t => t.type),+ ).toContain('keyword');+ expect(listedLanguage([thrift], 'graphql')).toBeUndefined();+ });++ it('treats lists naming the same values as the same', () => {+ expect(sameLanguages([thrift], [thrift])).toBe(true);+ expect(sameLanguages(undefined, undefined)).toBe(true);+ expect(sameLanguages([thrift], [])).toBe(false);+ expect(sameLanguages([thrift], undefined)).toBe(false);+ });+it('lays the tokens over the text as one line when line breaks render without text', () => {const rendered = code.replace('\n', '');const [line] = renderedTokens(code, 'ts', rendered) ?? [];diff --git a/packages/richtext/src/CodeSyntaxPlugin.tsx b/packages/richtext/src/CodeSyntaxPlugin.tsxindex 6ec0560735..14fa7a3b8c 100644--- a/packages/richtext/src/CodeSyntaxPlugin.tsx+++ b/packages/richtext/src/CodeSyntaxPlugin.tsx@@ -21,7 +21,7 @@* changes. Browsers without the Highlight API show plain code.*/-import {useEffect} from 'react';+import {useEffect, useState} from 'react';import {useLexicalComposerContext} from '@lexical/react/LexicalComposerContext';import {$isCodeNode, CodeNode} from '@lexical/code';import {$getNodeByKey, type NodeKey} from 'lexical';@@ -29,8 +29,10 @@ import {applyHighlightRangesFlat,TOKEN_TYPES,tokenize,+ type CodeLanguage,type TokenLine,} from '@astryxdesign/core/CodeBlock';+import {listedLanguage, sameLanguages} from './codeLanguages';/** The class the theme adds to every code block (editorTheme.ts). */export const CODE_SYNTAX_CLASS = 'astryx-richtext-code';@@ -71,7 +73,7 @@ function supportsHighlights(): boolean {*/export function renderedTokens(code: string,- language: string,+ language: string | CodeLanguage,rendered: string,): TokenLine[] | null {const lines = tokenize(code, language);@@ -103,9 +105,24 @@ interface Colored {readonly cleanup: () => void;}-export function CodeSyntaxPlugin(): null {+export function CodeSyntaxPlugin({+ codeLanguages,+}: {+ /** Language values a fence may name (component:Markdown FR30). */+ codeLanguages?: ReadonlyArray<CodeLanguage>;+} = {}): null {const [editor] = useLexicalComposerContext();+ // Keep one list while it names the same values, so an inline+ // `codeLanguages={[…]}` does not re-colour every block on each parent+ // render (adjusting state during render, not in an Effect).+ const [languages, setLanguages] = useState(codeLanguages);+ if (!sameLanguages(languages, codeLanguages)) {+ setLanguages(codeLanguages);+ }+ // Synchronizes the editor's code blocks with the CSS highlight registry:+ // Lexical update and mutation listeners colour each block, and the cleanup+ // removes the listeners and every highlight range they added.useEffect(() => {if (!supportsHighlights()) {return undefined;@@ -142,7 +159,7 @@ export function CodeSyntaxPlugin(): null {previous?.cleanup();const tokens = renderedTokens(block.code,- block.language,+ listedLanguage(languages, block.language) ?? block.language,element.textContent ?? '',);if (tokens == null) {@@ -187,7 +204,7 @@ export function CodeSyntaxPlugin(): null {}blocks.clear();};- }, [editor]);+ }, [editor, languages]);return null;}diff --git a/packages/richtext/src/RichTextEditor.doc.mjs b/packages/richtext/src/RichTextEditor.doc.mjsindex 26f4da583c..db8885c886 100644--- a/packages/richtext/src/RichTextEditor.doc.mjs+++ b/packages/richtext/src/RichTextEditor.doc.mjs@@ -138,6 +138,12 @@ export const docs = {description:'Markdown plugins whose nodes the editor draws, each adopted with createRichTextExtension. A plugin node renders exactly as core Markdown renders it and edits as one unit; a node whose plugin is not given here shows its source. Pass the extensions the content was converted with, and create them in a client module. RichTextView takes the same prop.',},+ {+ name: 'codeLanguages',+ type: 'ReadonlyArray<CodeLanguage>',+ description:+ 'CodeBlock language values a fence may name, each imported on its own (e.g. graphql from @astryxdesign/core/CodeBlock/languages/graphql) or made with createCodeLanguage. Pass the same list as Markdown codeLanguages so a matched fence paints and labels the same while reading and editing. RichTextView takes the same prop.',+ },{name: 'transformers',type: 'ReadonlyArray<Transformer>',diff --git a/packages/richtext/src/RichTextEditor.test.tsx b/packages/richtext/src/RichTextEditor.test.tsxindex fe82f6cfda..05be3fff8d 100644--- a/packages/richtext/src/RichTextEditor.test.tsx+++ b/packages/richtext/src/RichTextEditor.test.tsx@@ -318,6 +318,7 @@ describe('RichTextEditor', () => {'plugins','hasMarkdownShortcuts','markdownExtensions',+ 'codeLanguages','transformers','hasAutoFocus','tabEscapeHint',diff --git a/packages/richtext/src/RichTextEditor.tsx b/packages/richtext/src/RichTextEditor.tsxindex c4ffcf8ed9..d64beeffa5 100644--- a/packages/richtext/src/RichTextEditor.tsx+++ b/packages/richtext/src/RichTextEditor.tsx@@ -76,6 +76,7 @@ import {CodeBlockHeaderPlugin} from './CodeBlockHeaderPlugin';import {CodeSyntaxPlugin} from './CodeSyntaxPlugin';import {MarkdownExtensionsPlugin} from './MarkdownExtensionsPlugin';import type {RichTextMarkdownExtension} from './markdownExtensions';+import type {CodeLanguage} from '@astryxdesign/core/CodeBlock';import {TaskCheckboxPlugin} from './TaskCheckboxPlugin';import {type Transformer} from '@lexical/markdown';import {$generateHtmlFromNodes} from '@lexical/html';@@ -442,6 +443,14 @@ export interface RichTextEditorProps extends Omit<* serializable props.*/markdownExtensions?: ReadonlyArray<RichTextMarkdownExtension>;+ /**+ * CodeBlock language values a fence may name, each imported on its own,+ * such as `graphql` from `@astryxdesign/core/CodeBlock/languages/graphql`,+ * or made with `createCodeLanguage`. Pass the same list as `Markdown`'s+ * `codeLanguages`, so reading and editing paint and label the same+ * languages (spec:AST-061).+ */+ codeLanguages?: ReadonlyArray<CodeLanguage>;/** Whether to automatically focus the editor on mount. @default false */hasAutoFocus?: boolean;/**@@ -515,6 +524,7 @@ export const RichTextEditor = function RichTextEditor({hasMarkdownShortcuts = true,transformers = DEFAULT_TRANSFORMERS,markdownExtensions,+ codeLanguages,hasAutoFocus = false,tabEscapeHint: tabEscapeHintFromProps,maxLength,@@ -705,8 +715,8 @@ export const RichTextEditor = function RichTextEditor({hasHorizontalScroll/><TableColumnFloorPlugin />- <CodeBlockHeaderPlugin />- <CodeSyntaxPlugin />+ <CodeBlockHeaderPlugin codeLanguages={codeLanguages} />+ <CodeSyntaxPlugin codeLanguages={codeLanguages} />{markdownExtensions != null && markdownExtensions.length > 0 ? (<MarkdownExtensionsPluginextensions={markdownExtensions}diff --git a/packages/richtext/src/RichTextView.tsx b/packages/richtext/src/RichTextView.tsxindex 825461fd6c..a1a16c5e6c 100644--- a/packages/richtext/src/RichTextView.tsx+++ b/packages/richtext/src/RichTextView.tsx@@ -41,6 +41,7 @@ import {CodeBlockHeaderPlugin} from './CodeBlockHeaderPlugin';import {CodeSyntaxPlugin} from './CodeSyntaxPlugin';import {MarkdownExtensionsPlugin} from './MarkdownExtensionsPlugin';import type {RichTextMarkdownExtension} from './markdownExtensions';+import type {CodeLanguage} from '@astryxdesign/core/CodeBlock';import {TaskCheckboxPlugin} from './TaskCheckboxPlugin';import type {AnyLexicalExtension,@@ -119,6 +120,14 @@ export interface RichTextViewProps extends BaseProps {* serializable props.*/markdownExtensions?: ReadonlyArray<RichTextMarkdownExtension>;+ /**+ * CodeBlock language values a fence may name, each imported on its own,+ * such as `graphql` from `@astryxdesign/core/CodeBlock/languages/graphql`,+ * or made with `createCodeLanguage`. Pass the same list as `Markdown`'s+ * `codeLanguages`, so reading and editing paint and label the same+ * languages (spec:AST-061).+ */+ codeLanguages?: ReadonlyArray<CodeLanguage>;/*** Additional read-only plugins to render inside the composer (e.g. hover* cards, decorators).@@ -202,6 +211,7 @@ export function RichTextView({value,nodes,markdownExtensions,+ codeLanguages,plugins,namespace = 'astryx-view',onParseError,@@ -323,8 +333,8 @@ export function RichTextView({/>{/* After the content, so the copy buttons and checkboxes follow itin tab order. */}- <CodeBlockHeaderPlugin />- <CodeSyntaxPlugin />+ <CodeBlockHeaderPlugin codeLanguages={codeLanguages} />+ <CodeSyntaxPlugin codeLanguages={codeLanguages} />{markdownExtensions != null && markdownExtensions.length > 0 ? (<MarkdownExtensionsPluginextensions={markdownExtensions}diff --git a/packages/richtext/src/__tests__/RichTextCodeLanguages.a11y.chromium.spec.ts b/packages/richtext/src/__tests__/RichTextCodeLanguages.a11y.chromium.spec.tsnew file mode 100644index 0000000000..a5a3ba98a5--- /dev/null+++ b/packages/richtext/src/__tests__/RichTextCodeLanguages.a11y.chromium.spec.ts@@ -0,0 +1,61 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file RichTextCodeLanguages.a11y.chromium.spec.ts+ * @input The built Storybook's "Code language modules" story: one Thrift+ * fence with `codeLanguages={[thrift]}` and the same fence without it+ * @output CodeBlock FR13 for RichText in a real browser: CodeSyntaxPlugin+ * paints a listed value and labels with its name; unlisted stays plain+ * @position spec:AST-061 read/edit parity, CodeBlock FR13 evidence+ */++import {expect, test, type Page} from '@playwright/test';+import {+ DEFAULT_STORYBOOK_DIR,+ serveStorybook,+ type StaticServer,+} from '@astryxdesign/a11y-spec/storybook';++let storybook: StaticServer;+test.beforeAll(async () => {+ storybook = await serveStorybook(+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,+ );+});+test.afterAll(async () => {+ await storybook?.close();+});++/** The keyword-highlighted text inside the element with `testId`. */+async function keywordsIn(page: Page, testId: string) {+ return page.evaluate(id => {+ const root = document.querySelector(`[data-testid="${id}"]`);+ const highlight = CSS.highlights.get('astryx-keyword');+ if (!root || !highlight) {+ return [];+ }+ return Array.from(highlight as unknown as Iterable<Range>)+ .filter(range => root.contains(range.startContainer))+ .map(range => range.toString());+ }, testId);+}++test('RichText code blocks colour and label a listed language value', async ({+ page,+}) => {+ await page.goto(+ `${storybook.origin}/iframe.html?id=richtext-richtexteditor--code-language-modules&viewMode=story`,+ );+ await expect(page.getByText('struct User {').first()).toBeVisible();+ await expect+ .poll(async () => keywordsIn(page, 'listed'))+ .toEqual(expect.arrayContaining(['struct', 'required', 'string']));+ expect(await keywordsIn(page, 'unlisted')).toEqual([]);+ await expect(+ page.locator('[data-testid="listed"] [data-richtext-code-header]'),+ ).toContainText('thrift');+ // An `objc` fence matched by objectiveC is labelled with the value's name.+ await expect(+ page.locator('[data-testid="listed-renamed"] [data-richtext-code-header]'),+ ).toContainText('objective-c');+});diff --git a/packages/richtext/src/codeLanguages.ts b/packages/richtext/src/codeLanguages.tsnew file mode 100644index 0000000000..cb659d4228--- /dev/null+++ b/packages/richtext/src/codeLanguages.ts@@ -0,0 +1,42 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file codeLanguages.ts+ * @input CodeLanguage values from @astryxdesign/core/CodeBlock+ * @output listedLanguage, which finds the listed value a fence word names, and+ * sameLanguages, which compares two lists entry by entry+ * @position Shared by CodeSyntaxPlugin and CodeBlockHeaderPlugin, so RichText+ * resolves a fence as Markdown does (component:Markdown FR30)+ */++import type {CodeLanguage} from '@astryxdesign/core/CodeBlock';++/** The listed value whose identifiers include `word`; a later entry wins. */+export function listedLanguage(+ languages: ReadonlyArray<CodeLanguage> | undefined,+ word: string,+): CodeLanguage | undefined {+ if (languages == null) {+ return undefined;+ }+ for (let i = languages.length - 1; i >= 0; i--) {+ if (languages[i].identifiers.includes(word)) {+ return languages[i];+ }+ }+ return undefined;+}++/** Whether two lists name the same values in the same order. */+export function sameLanguages(+ a: ReadonlyArray<CodeLanguage> | undefined,+ b: ReadonlyArray<CodeLanguage> | undefined,+): boolean {+ if (a === b) {+ return true;+ }+ if (a == null || b == null || a.length !== b.length) {+ return false;+ }+ return a.every((language, i) => language === b[i]);+}