Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/.changeset/richtext-code-languages.md b/.changeset/richtext-code-languages.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/apps/storybook/stories/RichTextEditor.stories.tsx b/apps/storybook/stories/RichTextEditor.stories.tsx
index 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.ts
index 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.tsx
new file mode 100644
index 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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.tsx
index 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({
<div
data-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.tsx
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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 ? (
<MarkdownExtensionsPlugin
extensions={markdownExtensions}
diff --git a/packages/richtext/src/RichTextView.tsx b/packages/richtext/src/RichTextView.tsx
index 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 it
in tab order. */}
- <CodeBlockHeaderPlugin />
- <CodeSyntaxPlugin />
+ <CodeBlockHeaderPlugin codeLanguages={codeLanguages} />
+ <CodeSyntaxPlugin codeLanguages={codeLanguages} />
{markdownExtensions != null && markdownExtensions.length > 0 ? (
<MarkdownExtensionsPlugin
extensions={markdownExtensions}
diff --git a/packages/richtext/src/__tests__/RichTextCodeLanguages.a11y.chromium.spec.ts b/packages/richtext/src/__tests__/RichTextCodeLanguages.a11y.chromium.spec.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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]);
+}