@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/CodeBlock/CodeBlock.test.tsx

@@ -314,6 +314,99 @@ describe('CodeBlock', () => {
     expect(navigator.clipboard.writeText).toHaveBeenCalled();
   });
 
+  describe('endContent', () => {
+    const run = () => (
+      <button type="button" onClick={onRun}>
+        Run in terminal
+      </button>
+    );
+    let onRun: ReturnType<typeof vi.fn<() => void>>;
+    beforeEach(() => {
+      onRun = vi.fn<() => void>();
+    });
+
+    it('renders caller controls before Copy in the header', () => {
+      render(<CodeBlock code="npm test" language="bash" endContent={run()} />);
+      const action = screen.getByRole('button', {name: 'Run in terminal'});
+      const copy = screen.getByRole('button', {name: 'Copy code'});
+      expect(action.parentElement).toBe(copy.parentElement);
+      expect(
+        action.compareDocumentPosition(copy) & Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+      expect(screen.getByText('bash')).toBeInTheDocument();
+    });
+
+    it('never creates a header: with no title or label the controls sit in the corner', () => {
+      const {container} = render(
+        <CodeBlock
+          code="npm test"
+          language="bash"
+          hasLanguageLabel={false}
+          endContent={run()}
+        />,
+      );
+      expect(container.querySelector('.astryx-code-block-header')).toBeNull();
+      const action = screen.getByRole('button', {name: 'Run in terminal'});
+      const copy = screen.getByRole('button', {name: 'Copy code'});
+      const cluster = action.parentElement;
+      expect(cluster).toBe(copy.parentElement);
+      expect(cluster?.parentElement).toBe(container.querySelector('pre'));
+      expect(
+        action.compareDocumentPosition(copy) & Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+    });
+
+    it('keeps its place when Copy is hidden', () => {
+      const {container} = render(
+        <CodeBlock code="npm test" hasCopyButton={false} endContent={run()} />,
+      );
+      expect(screen.queryByRole('button', {name: 'Copy code'})).toBeNull();
+      const action = screen.getByRole('button', {name: 'Run in terminal'});
+      expect(action.parentElement?.parentElement).toBe(
+        container.querySelector('pre'),
+      );
+    });
+
+    it('sits outside the disclosure and never toggles it, by pointer or keyboard', () => {
+      render(
+        <CodeBlock
+          code={LONG_CODE}
+          language="javascript"
+          title="example"
+          isCollapsible
+          endContent={run()}
+        />,
+      );
+      const header = screen
+        .getAllByRole('button')
+        .find(el => el.hasAttribute('aria-expanded'));
+      const action = screen.getByRole('button', {name: 'Run in terminal'});
+      expect(header!.contains(action)).toBe(false);
+      fireEvent.click(action);
+      fireEvent.keyDown(action, {key: 'Enter'});
+      fireEvent.keyDown(action, {key: ' '});
+      expect(onRun).toHaveBeenCalledTimes(1);
+      expect(header).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    it('treats a falsy endContent as absent: no corner column without Copy', () => {
+      const {container} = render(
+        <CodeBlock code="npm test" hasCopyButton={false} endContent={false} />,
+      );
+      const root = container.querySelector('pre');
+      // Only the code viewport: no empty cluster beside it.
+      expect(root?.children).toHaveLength(1);
+      expect(screen.queryAllByRole('button')).toHaveLength(0);
+    });
+
+    it('leaves caller controls unnamed and unstyled by CodeBlock', () => {
+      render(<CodeBlock code="npm test" language="bash" endContent={run()} />);
+      const action = screen.getByRole('button', {name: 'Run in terminal'});
+      expect(action.getAttribute('class')).toBeNull();
+      expect(action).not.toHaveAttribute('aria-label');
+    });
+  });
+
   it('does not nest the copy button inside the collapsible header role="button"', () => {
     render(
       <CodeBlock
@@ -561,7 +654,10 @@ describe('CodeBlock', () => {
       expect(screen.getByRole('group')).toHaveAttribute('aria-label', 'Code');
 
       const copyButton = screen.getByRole('button', {name: 'Copy code'});
-      expect(copyButton.parentElement).toBe(container.querySelector('pre'));
+      // Headerless: Copy sits in the corner cluster, a direct child of the root.
+      expect(copyButton.parentElement?.parentElement).toBe(
+        container.querySelector('pre'),
+      );
       await act(async () => {
         fireEvent.click(copyButton);
       });

package/src/CodeBlock/CodeBlock.tsx

@@ -32,7 +32,7 @@ import {
   durationVars,
   easeVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import {useClipboard} from '../hooks/useClipboard';
 import {useScrollableArea} from '../hooks/useScrollableArea';
 import {Icon} from '../Icon';
@@ -45,7 +45,14 @@ import {
   flatTokensToLines,
   SYNC_TOKENIZE_THRESHOLD,
 } from './tokenizer';
-import type {SyntaxToken, TokenLine} from './tokenizer';
+import type {CodeLanguageInput, SyntaxToken, TokenLine} from './tokenizer';
+import type {CodeLanguage} from './grammar';
+import {
+  isCustomCodeLanguage,
+  languageKey,
+  languageLabel as languageWord,
+  sameCodeLanguage,
+} from './grammar';
 import {ensureHighlightStyles} from './highlightStyles';
 import {applyHighlightRangesChunked} from './highlightRanges';
 import {themeProps} from '../utils/themeProps';
@@ -127,6 +134,15 @@ const styles = stylex.create({
   viewport: {
     minHeight: 0,
   },
+  // With no header, Copy sits in its own inline-end column beside the code
+  // viewport rather than over it, so no line, scrolled or wrapped, runs under
+  // the button. The column is as wide as its content; the single row still
+  // lets a root sized from outside bound the viewport.
+  rootCorner: {
+    display: 'grid',
+    gridTemplateColumns: 'minmax(0, 1fr) auto',
+    gridTemplateRows: 'minmax(0, 1fr)',
+  },
   headerRow: {
     display: 'flex',
     alignItems: 'center',
@@ -392,10 +408,32 @@ const styles = stylex.create({
     // reaches it via the `code-block-copy-button` target on the Button.
     color: 'var(--color-syntax-comment)',
   },
-  copyButtonAbsolute: {
-    position: 'absolute',
-    top: spacingVars['--spacing-2'],
-    insetInlineEnd: spacingVars['--spacing-2'],
+  // The controls of a headerless block: caller controls, then Copy, in the
+  // second column (cornerClusterMd/Sm give its height).
+  cornerCluster: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+    alignSelf: 'start',
+    marginInline: spacingVars['--spacing-2'],
+  },
+  // The header's controls: caller controls, then Copy.
+  headerControls: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+    flexShrink: 0,
+  },
+  // The cluster is exactly as tall as the first line's row (its block padding
+  // on both sides plus its line box), and centres its controls in it, so any
+  // control height sits on the first line: a one-line block reads as one row
+  // with even space above and below, and a block that grows keeps its
+  // controls where they were.
+  cornerClusterMd: {
+    blockSize: `calc(2 * ${spacingVars['--spacing-3']} + ${typeScaleVars['--text-code-size']} * ${typeScaleVars['--text-code-leading']})`,
+  },
+  cornerClusterSm: {
+    blockSize: `calc(2 * ${spacingVars['--spacing-3']} + ${typeScaleVars['--text-supporting-size']} * ${typeScaleVars['--text-code-leading']})`,
   },
 });
 
@@ -510,7 +548,15 @@ function renderLines(
 export interface CodeBlockProps extends BaseProps<HTMLPreElement> {
   ref?: React.Ref<HTMLPreElement>;
   code: string;
-  language?: string;
+  /**
+   * The code's 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`. A string selects only a built-in grammar; the label
+   * shows the string, or the value's `name`.
+   * @default 'plaintext'
+   */
+  language?: string | CodeLanguage;
   title?: string;
   hasLanguageLabel?: boolean;
   hasLineNumbers?: boolean;
@@ -526,6 +572,14 @@ export interface CodeBlockProps extends BaseProps<HTMLPreElement> {
   isDiff?: boolean;
   hasCopyButton?: boolean;
   onCopy?: () => void;
+  /**
+   * Your own controls, shown just before Copy: in the header when the block
+   * has one, otherwise beside the code in the top inline-end corner, never
+   * over it. It never creates a header, and activating it never collapses the
+   * block. You own each control's label, state, and action; ghost `sm`
+   * IconButtons match Copy's size and variant.
+   */
+  endContent?: React.ReactNode;
   isWrapped?: boolean;
   maxHeight?: number | string;
   isCollapsible?: boolean;
@@ -549,6 +603,12 @@ export interface CodeBlockProps extends BaseProps<HTMLPreElement> {
    * @default 'card'
    */
   container?: 'card' | 'section';
+  /**
+   * @deprecated Pass a custom language as `language` instead:
+   * `language={createCodeLanguage({name, identifiers, tokenize})}` takes this
+   * same function as `tokenize`. Still works exactly as released and wins
+   * over `language`'s grammar; `astryx upgrade` rewrites static uses.
+   */
   tokenizer?: (
     code: string,
     language: string,
@@ -594,27 +654,49 @@ function isSafari(): boolean {
  */
 function useTokenLines(
   code: string,
-  language: string,
+  languageProp: CodeLanguageInput,
   customTokenizer?: CodeBlockProps['tokenizer'],
 ): TokenLine[] {
+  // Keep one language while it paints the same, so an inline
+  // `createCodeLanguage({...})` — the form the `tokenizer` codemod writes —
+  // tokenizes once, as `tokenizer` did (adjusting state during render).
+  const [language, setLanguage] = useState(languageProp);
+  if (!sameCodeLanguage(language, languageProp)) {
+    setLanguage(languageProp);
+  }
   const [asyncTokenResult, setAsyncTokenResult] = useState<{
     code: string;
-    language: string;
+    language: CodeLanguageInput;
     tokens: TokenLine[];
   } | null>(null);
 
   const syncTokens = useMemo(() => {
     if (customTokenizer) {
-      return flatTokensToLines(customTokenizer(code, language), code);
+      return flatTokensToLines(
+        customTokenizer(code, languageWord(language)),
+        code,
+      );
     }
-    if (code.length >= SYNC_TOKENIZE_THRESHOLD) {
+    // A custom language paints synchronously at any length, as `tokenizer`
+    // does, so the codemod's rewrite keeps the same first paint (FR13).
+    if (
+      code.length >= SYNC_TOKENIZE_THRESHOLD &&
+      !isCustomCodeLanguage(language)
+    ) {
       return null;
     }
     return tokenize(code, language);
   }, [code, language, customTokenizer]);
 
+  // Synchronizes long code with a scheduler-yielding tokenize task: it starts
+  // when the code, language, or tokenizer changes, and the
+  // cleanup aborts the previous one.
   useEffect(() => {
-    if (code.length < SYNC_TOKENIZE_THRESHOLD || customTokenizer) {
+    if (
+      code.length < SYNC_TOKENIZE_THRESHOLD ||
+      customTokenizer ||
+      isCustomCodeLanguage(language)
+    ) {
       return;
     }
 
@@ -879,6 +961,7 @@ export function CodeBlock({
   isDiff = false,
   hasCopyButton = true,
   onCopy,
+  endContent,
   isWrapped = false,
   maxHeight,
   isCollapsible = false,
@@ -948,14 +1031,18 @@ export function CodeBlock({
   // With the diff layer on, the label and viewport name say so: `diff` over
   // plaintext, `tsx diff` over a language — so a diff keeps its header,
   // collapse control, and a name that still matches a `diff` fence.
+  // A language value labels with its `name` and reflects its first
+  // identifier as `data-language`, so theme selectors keep matching (FR13).
+  const languageName = languageWord(language);
+  const languageAttr = languageKey(language);
   const languageLabel = !hasLanguageLabel
     ? null
     : isDiff
-      ? language === 'plaintext'
+      ? languageName === 'plaintext'
         ? 'diff'
-        : `${language} diff`
-      : language !== 'plaintext'
-        ? language
+        : `${languageName} diff`
+      : languageName !== 'plaintext'
+        ? languageName
         : null;
   const showHeader = title != null || languageLabel != null;
 
@@ -1001,6 +1088,10 @@ export function CodeBlock({
         }
       : undefined;
 
+  // Caller controls render before Copy; together they are the block's controls,
+  // in the header when there is one and in the corner cluster otherwise.
+  const hasEndContent = isRenderable(endContent);
+  const hasControls = hasCopyButton || hasEndContent;
   const copyButtonEl = hasCopyButton ? (
     <IconButton
       variant="ghost"
@@ -1019,7 +1110,7 @@ export function CodeBlock({
         e.stopPropagation();
         void handleCopy();
       }}
-      xstyle={[styles.copyButton, !showHeader && styles.copyButtonAbsolute]}
+      xstyle={styles.copyButton}
       {...themeProps('code-block-copy-button')}
     />
   ) : null;
@@ -1027,7 +1118,11 @@ export function CodeBlock({
   const headerEl = showHeader ? (
     <div
       {...mergeProps(
-        themeProps('code-block-header', {size, language, container}),
+        themeProps('code-block-header', {
+          size,
+          language: languageAttr,
+          container,
+        }),
         stylex.props(
           styles.headerRow,
           hasLineNumbers ? styles.headerWithDivider : styles.headerCompact,
@@ -1060,7 +1155,7 @@ export function CodeBlock({
         )}>
         <span
           {...mergeProps(
-            themeProps('code-block-title', {size, language}),
+            themeProps('code-block-title', {size, language: languageAttr}),
             stylex.props(styles.headerTitle),
           )}>
           {canCollapse && (
@@ -1081,7 +1176,12 @@ export function CodeBlock({
           {languageLabel}
         </span>
       </div>
-      {copyButtonEl}
+      {hasControls ? (
+        <div {...stylex.props(styles.headerControls)}>
+          {hasEndContent ? endContent : null}
+          {copyButtonEl}
+        </div>
+      ) : null}
     </div>
   ) : null;
 
@@ -1130,9 +1230,10 @@ export function CodeBlock({
     <pre
       ref={ref}
       {...mergeProps(
-        themeProps('code-block', {size, language, container}),
+        themeProps('code-block', {size, language: languageAttr, container}),
         stylex.props(
           styles.root,
+          hasControls && !showHeader && styles.rootCorner,
           dynamicStyles.width(widthProp),
           containerStyles[container],
           xstyle,
@@ -1160,7 +1261,16 @@ export function CodeBlock({
       ) : (
         codeBody
       )}
-      {!showHeader && copyButtonEl}
+      {hasControls && !showHeader ? (
+        <div
+          {...stylex.props(
+            styles.cornerCluster,
+            size === 'sm' ? styles.cornerClusterSm : styles.cornerClusterMd,
+          )}>
+          {hasEndContent ? endContent : null}
+          {copyButtonEl}
+        </div>
+      ) : null}
     </pre>
   );
 

package/src/CodeBlock/CodeLanguage.test.tsx

@@ -0,0 +1,173 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CodeLanguage.test.tsx
+ * @input CodeBlock, language modules, createCodeLanguage
+ * @output CodeBlock FR13 evidence: a language value passed as `language`
+ *   paints, labels with its name, and reflects its first identifier; a string
+ *   never reaches a module; the `tokenizer` prop still wins; server rendering
+ *   paints in the first render
+ * @position CodeBlock FR13 evidence
+ */
+
+import {render, screen} from '@testing-library/react';
+import {renderToString} from 'react-dom/server';
+import {describe, expect, it} from 'vitest';
+import {CodeBlock} from './CodeBlock';
+import {createCodeLanguage} from './grammar';
+import {objectiveC} from './languages/objective-c';
+import {thrift} from './languages/thrift';
+
+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('a language value as `language` (FR13)', () => {
+  it('paints and labels with the value; a string never reaches a module', () => {
+    const plain = render(
+      <CodeBlock code={THRIFT} language="thrift" highlightMode="spans" />,
+    );
+    expect(keywordTexts(plain.container)).toEqual([]);
+
+    const {container} = render(
+      <CodeBlock code={THRIFT} language={thrift} highlightMode="spans" />,
+    );
+    expect(keywordTexts(container)).toEqual(
+      expect.arrayContaining(['struct', 'required', 'string']),
+    );
+    expect(screen.getAllByText('thrift').length).toBeGreaterThan(0);
+  });
+
+  it('reflects the first identifier as data-language', () => {
+    const {container} = render(
+      <CodeBlock code="@interface A\n@end" language={objectiveC} />,
+    );
+    expect(container.querySelector('pre')?.getAttribute('data-language')).toBe(
+      'objective-c',
+    );
+  });
+
+  it('paints a custom language made with createCodeLanguage', () => {
+    const zig = createCodeLanguage({
+      name: 'zig',
+      identifiers: ['zig'],
+      tokenize: () => [{type: 'keyword', start: 0, end: 3}],
+    });
+    const {container} = render(
+      <CodeBlock
+        code="pub fn main() void {}"
+        language={zig}
+        highlightMode="spans"
+      />,
+    );
+    expect(keywordTexts(container)).toEqual(['pub']);
+    expect(container.querySelector('pre')?.getAttribute('data-language')).toBe(
+      'zig',
+    );
+  });
+
+  it('labels with the value name and reflects its first identifier', () => {
+    const zig = createCodeLanguage({
+      name: 'Zig Lang',
+      identifiers: ['zig', 'ziglang'],
+      tokenize: () => [],
+    });
+    const {container} = render(
+      <CodeBlock code="const a = 1;" language={zig} />,
+    );
+    expect(screen.getByText('Zig Lang')).toBeInTheDocument();
+    expect(container.querySelector('pre')?.getAttribute('data-language')).toBe(
+      'zig',
+    );
+  });
+
+  it('paints a custom language synchronously at any length, as tokenizer does', () => {
+    const long = 'pub '.repeat(600);
+    const zig = createCodeLanguage({
+      name: 'zig',
+      identifiers: ['zig'],
+      tokenize: code =>
+        Array.from(code.matchAll(/pub/g), match => ({
+          type: 'keyword',
+          start: match.index ?? 0,
+          end: (match.index ?? 0) + 3,
+        })),
+    });
+    const html = renderToString(
+      <CodeBlock code={long} language={zig} highlightMode="spans" />,
+    );
+    expect(html.match(/astryx-token-keyword/g)?.length).toBe(600);
+    const {container} = render(
+      <CodeBlock code={long} language={zig} highlightMode="spans" />,
+    );
+    expect(keywordTexts(container)).toHaveLength(600);
+  });
+
+  it('keeps the tokenizer prop winning, as released', () => {
+    const tokenizer = () => [{type: 'string', start: 0, end: 6}];
+    const builtIn = render(
+      <CodeBlock
+        code="const x = 1;"
+        language="ts"
+        tokenizer={tokenizer}
+        highlightMode="spans"
+      />,
+    );
+    expect(keywordTexts(builtIn.container)).toEqual([]);
+    expect(
+      builtIn.container.querySelector('.astryx-token-string')?.textContent,
+    ).toBe('const ');
+    const value = render(
+      <CodeBlock
+        code={THRIFT}
+        language={thrift}
+        tokenizer={tokenizer}
+        highlightMode="spans"
+      />,
+    );
+    expect(keywordTexts(value.container)).toEqual([]);
+  });
+
+  it('tokenizes an inline custom language once across re-renders', () => {
+    let calls = 0;
+    const tokenize = () => {
+      calls++;
+      return [{type: 'keyword', start: 0, end: 3}];
+    };
+    const make = () =>
+      createCodeLanguage({name: 'zig', identifiers: ['zig'], tokenize});
+    const {rerender} = render(
+      <CodeBlock code="pub fn" language={make()} highlightMode="spans" />,
+    );
+    for (let i = 0; i < 5; i++) {
+      rerender(
+        <CodeBlock code="pub fn" language={make()} highlightMode="spans" />,
+      );
+    }
+    expect(calls).toBe(1);
+  });
+
+  it('renders plain, not throwing, when a custom language has no function', () => {
+    const missing = createCodeLanguage({
+      name: 'zig',
+      identifiers: ['zig'],
+      tokenize: undefined as unknown as () => [],
+    });
+    const {container} = render(
+      <CodeBlock code="pub fn" language={missing} highlightMode="spans" />,
+    );
+    expect(keywordTexts(container)).toEqual([]);
+    expect(container.textContent).toContain('pub fn');
+  });
+
+  it('paints a language value in the server render', () => {
+    const html = renderToString(
+      <CodeBlock code={THRIFT} language={thrift} highlightMode="spans" />,
+    );
+    expect(html).toContain('astryx-token-keyword');
+  });
+});