Initial identifier instance custom renderer

A custom renderer to ensure the instance use,
not just the identifier definitions are
properly made uneditable.

app/assets/javascripts/vue_shared/components/rich_content_editor/services/build_custom_renderer.js

 import renderBlockHtml from './renderers/render_html_block';
 import renderKramdownList from './renderers/render_kramdown_list';
 import renderKramdownText from './renderers/render_kramdown_text';
+import renderIdentifierInstanceText from './renderers/render_identifier_instance_text';
 import renderIdentifierParagraph from './renderers/render_identifier_paragraph';
 import renderEmbeddedRubyText from './renderers/render_embedded_ruby_text';
 import renderFontAwesomeHtmlInline from './renderers/render_font_awesome_html_inline';
@@ -9,7 +10,7 @@ const htmlInlineRenderers = [renderFontAwesomeHtmlInline];
 const htmlBlockRenderers = [renderBlockHtml];
 const listRenderers = [renderKramdownList];
 const paragraphRenderers = [renderIdentifierParagraph];
-const textRenderers = [renderKramdownText, renderEmbeddedRubyText];
+const textRenderers = [renderKramdownText, renderEmbeddedRubyText, renderIdentifierInstanceText];
 
 const executeRenderer = (renderers, node, context) => {
   const availableRenderer = renderers.find(renderer => renderer.canRender(node, context));

app/assets/javascripts/vue_shared/components/rich_content_editor/services/renderers/build_uneditable_token.js

@@ -32,6 +32,8 @@ export const buildUneditableCloseTokens = (token, tagType = TAG_TYPES.block) =>
 
 // Complete helpers (open plus close)
 
+export const buildTextToken = content => buildToken('text', null, { content });
+
 export const buildUneditableTokens = token => {
   return [...buildUneditableOpenTokens(token), buildUneditableCloseToken()];
 };

app/assets/javascripts/vue_shared/components/rich_content_editor/services/renderers/render_identifier_instance_text.js

+import { buildTextToken, buildUneditableInlineTokens } from './build_uneditable_token';
+
+/*
+Use case examples:
+- Majority: two bracket pairs, back-to-back, each with content (including spaces)
+  - `[environment terraform plans][terraform]`
+  - `[an issue labelled `~"master:broken"`][broken-master-issues]`
+- Minority: two bracket pairs the latter being empty or only one pair with content (including spaces)
+  - `[this link][]`
+  - `[this link]`
+
+Regexp notes:
+  - `(?:\[.+?\]){1}`: Always one bracket pair with content (including spaces)
+  - `(?:\[\]|\[.+?\])?`: Optional second pair that may or may not contain content (including spaces)
+  - `(?!:)`: Never followed by a `:` which is reserved for identifier definition syntax (`[identifier]: /the-link`)
+  - Each of the three parts is non-captured, but the match as a whole is captured
+*/
+const identifierInstanceRegex = /((?:\[.+?\]){1}(?:\[\]|\[.+?\])?(?!:))/g;
+
+const isIdentifierInstance = literal => {
+  // Reset lastIndex as global flag in regexp are stateful (https://stackoverflow.com/a/11477448)
+  identifierInstanceRegex.lastIndex = 0;
+  return identifierInstanceRegex.test(literal);
+};
+
+const canRender = ({ literal }) => isIdentifierInstance(literal);
+
+const tokenize = text => {
+  const matches = text.split(identifierInstanceRegex);
+  const tokens = matches.map(match => {
+    const token = buildTextToken(match);
+    return isIdentifierInstance(match) ? buildUneditableInlineTokens(token) : token;
+  });
+
+  return tokens.flat();
+};
+
+const render = (_, { origin }) => tokenize(origin().content);
+
+export default { canRender, render };

changelogs/unreleased/36574-custom-renderer-identifiers-instances.yml

+---
+title: Add a custom HTML renderer to the Static Site Editor for markdown identifier instance syntax
+merge_request: 36574
+author:
+type: added

spec/frontend/vue_shared/components/rich_content_editor/services/renderers/build_uneditable_token_spec.js

 import {
+  buildTextToken,
   buildUneditableOpenTokens,
   buildUneditableCloseToken,
   buildUneditableCloseTokens,
@@ -19,6 +20,13 @@ import {
 } from './mock_data';
 
 describe('Build Uneditable Token renderer helper', () => {
+  describe('buildTextToken', () => {
+    it('returns an object literal representing a text token', () => {
+      const text = originToken.content;
+      expect(buildTextToken(text)).toStrictEqual(originToken);
+    });
+  });
+
   describe('buildUneditableOpenTokens', () => {
     it('returns a 2-item array of tokens with the originToken appended to an open token', () => {
       const result = buildUneditableOpenTokens(originToken);

spec/frontend/vue_shared/components/rich_content_editor/services/renderers/mock_data.js

@@ -29,6 +29,7 @@ const buildMockUneditableCloseToken = type => {
 
 export const originToken = {
   type: 'text',
+  tagName: null,
   content: '{:.no_toc .hidden-md .hidden-lg}',
 };
 export const uneditableCloseToken = buildMockUneditableCloseToken('div');

spec/frontend/vue_shared/components/rich_content_editor/services/renderers/render_identifier_instance_text_spec.js

+import renderer from '~/vue_shared/components/rich_content_editor/services/renderers/render_identifier_instance_text';
+import { buildUneditableInlineTokens } from '~/vue_shared/components/rich_content_editor/services/renderers/build_uneditable_token';
+
+import { buildMockTextNode, normalTextNode } from './mock_data';
+
+const mockTextStart = 'Majority example ';
+const mockTextMiddle = '[environment terraform plans][terraform]';
+const mockTextEnd = '.';
+const identifierInstanceStartTextNode = buildMockTextNode(mockTextStart);
+const identifierInstanceEndTextNode = buildMockTextNode(mockTextEnd);
+
+describe('Render Identifier Instance Text renderer', () => {
+  describe('canRender', () => {
+    it.each`
+      node                                                                     | target
+      ${normalTextNode}                                                        | ${false}
+      ${identifierInstanceStartTextNode}                                       | ${false}
+      ${identifierInstanceEndTextNode}                                         | ${false}
+      ${buildMockTextNode(mockTextMiddle)}                                     | ${true}
+      ${buildMockTextNode('Minority example [environment terraform plans][]')} | ${true}
+      ${buildMockTextNode('Minority example [environment terraform plans]')}   | ${true}
+    `(
+      'should return $target when the $node validates against identifier instance syntax',
+      ({ node, target }) => {
+        expect(renderer.canRender(node)).toBe(target);
+      },
+    );
+  });
+
+  describe('render', () => {
+    it.each`
+      start            | middle                               | end
+      ${mockTextStart} | ${mockTextMiddle}                    | ${mockTextEnd}
+      ${mockTextStart} | ${'[environment terraform plans][]'} | ${mockTextEnd}
+      ${mockTextStart} | ${'[environment terraform plans]'}   | ${mockTextEnd}
+    `(
+      'should return inline editable, uneditable, and editable tokens in sequence',
+      ({ start, middle, end }) => {
+        const buildMockTextToken = content => ({ type: 'text', tagName: null, content });
+
+        const startToken = buildMockTextToken(start);
+        const middleToken = buildMockTextToken(middle);
+        const endToken = buildMockTextToken(end);
+
+        const content = `${start}${middle}${end}`;
+        const contentToken = buildMockTextToken(content);
+        const contentNode = buildMockTextNode(content);
+        const context = { origin: jest.fn().mockReturnValueOnce(contentToken) };
+        expect(renderer.render(contentNode, context)).toStrictEqual(
+          [startToken, buildUneditableInlineTokens(middleToken), endToken].flat(),
+        );
+      },
+    );
+  });
+});