feat(docs): Add a shortcode to add icon to component types (#3508)

Co-authored-by: Maxime Lardenois <maxime.lardenois@orange.com>
Co-authored-by: Hannah Issermann <hannah.issermann@orange.com>

Author: 3 people

site/src/components/TableOfContents.astro

@@ -1,23 +1,26 @@
 ---
 import type { MarkdownHeading } from 'astro'
 import { generateToc, type TocEntry } from '@libs/toc'
+import { getComponentSVG } from '@libs/utils'
 
 interface Props {
   headings?: MarkdownHeading[]
   entries?: TocEntry[]
+  types?: string[]
 }
 
-const { entries, headings } = Astro.props
+const { entries, headings, types } = Astro.props
 
-const toc = entries ? entries : generateToc(headings ?? [])
+const toc = entries ? entries : generateToc(headings ?? [], types)
 ---
 
 <ul>
   {
     toc.map(({ children, slug, text }) => {
+      const isComponent = text.includes('[[comp]]')
       return (
         <li>
-          <a href={`#${slug}`}>{text}</a>
+          <a href={`#${slug}`} class:list={[{'d-flex align-items-center': isComponent}]}>{text.replace('[[comp]]', '')}{isComponent ? <Fragment set:html={getComponentSVG('bs-medium-icon ms-2xsmall')} /> : null}</a>
           {children.length > 0 && <Astro.self entries={children} />}
         </li>
       )

site/src/content/docs/components/alerts.mdx

@@ -123,7 +123,7 @@ In case an alert is dynamically added, there are several use cases:
 - The alert is informational and needs a user action but isn’t urgent, you can make it appear inside a `<div role="status">`. The dynamic alert message should reference where to find this action. [More information about the `role="status"`](https://a11y-guidelines.orange.com/en/articles/aria-status-messages/). [See a valid example](#live-example).
 - The alert requires a user action, either add the `role="alert"` directly on the `<div class="alert" role="alert">` and add a way to access to it easily, **or**, focus the newly added alert and once it’s closed, give the focus back to the element that triggered the alert. If the second choice is applied here, you may want to add a focustrap to this alert. [More information about the `role="alert"`](https://a11y-guidelines.orange.com/en/articles/aria-live-alert/).
 
-## <svg class="hl-small-icon me-scaled-2xsmall mb-xsmall" width="1rem" height="1rem" aria-hidden="true"><use xlink:href={getVersionedDocsPath('assets/img/ouds-web-sprite.svg#component-atom')} /></svg>Alert message
+## [[comp]] Alert message
 
 Alert message is a UI element that provides system feedback, indicates status changes, or prompts required actions through clear, prominent, persistent, and actionable communication.
 
@@ -713,7 +713,7 @@ myAlert.addEventListener('closed.bs.alert', event => {
 })
 ```
 
-## <svg class="hl-small-icon me-scaled-2xsmall mb-xsmall" width="1rem" height="1rem" aria-hidden="true"><use xlink:href={getVersionedDocsPath('assets/img/ouds-web-sprite.svg#component-atom')} /></svg>Inline alert
+## [[comp]] Inline alert
 
 Inline alert is a lightweight UI element integrated into the content flow. It conveys information, system feedback, and status changes through short, prominent, persistent, and non-actionable messages.
 

site/src/content/docs/components/badges.mdx

@@ -83,7 +83,7 @@ Keep in mind that visually impaired and blind users will lack the visual context
 
 Several examples are provided below, but they need to be adapted for actual use cases.
 
-## <svg class="hl-small-icon me-scaled-2xsmall mb-xsmall" width="1rem" height="1rem" aria-hidden="true"><use xlink:href={getVersionedDocsPath('assets/img/ouds-web-sprite.svg#component-atom')} /></svg>Badge
+## [[comp]] Badge
 
 Badge is a UI element that highlights system notifications, statuses, or the categorisation of information through colour alone.
 
@@ -163,7 +163,7 @@ Badges are available in four sizes. Default size is medium.
   <p class="badge"><span class="visually-hidden">Medium badge (default)</span></p>
   <p class="badge badge-large"><span class="visually-hidden">Large badge</span></p>`} />
 
-## <svg class="hl-small-icon me-scaled-2xsmall mb-xsmall" width="1rem" height="1rem" aria-hidden="true"><use xlink:href={getVersionedDocsPath('assets/img/ouds-web-sprite.svg#component-atom')} /></svg>Badge - Count
+## [[comp]] Badge - Count
 
 Badge - count is a UI element that highlights system notifications, status, or the categorisation of information through colour and numerical value.
 
@@ -215,7 +215,7 @@ Badges - count are available in two sizes. Add `.badge-large` to have a larger b
 <Example class="d-flex align-items-center gap-large" code={`<p class="badge badge-count">12<span class="visually-hidden">errors</span></p>
   <p class="badge badge-count badge-large">12<span class="visually-hidden">errors</span></p>`} />
 
-## <svg class="hl-small-icon me-scaled-2xsmall mb-xsmall" width="1rem" height="1rem" aria-hidden="true"><use xlink:href={getVersionedDocsPath('assets/img/ouds-web-sprite.svg#component-atom')} /></svg>Badge - Icon
+## [[comp]] Badge - Icon
 
 Badge - icon is a UI element that highlights system notifications, statuses, or the categorisation of information through colour and iconography.
 

site/src/content/docs/components/buttons.mdx

@@ -68,7 +68,7 @@ Generally speaking, you should always ask yourself which tag is appropriate for
 
 When navigation buttons are used for global navigation (between pages or within content), they should be wrapped in a `<nav>` tag, which must have an explicit (accessible) name defined using, for example, an `aria-label` attribute.
 
-## <svg class="hl-small-icon me-scaled-2xsmall mb-xsmall" width="1rem" height="1rem" aria-hidden="true"><use xlink:href={getVersionedDocsPath('assets/img/ouds-web-sprite.svg#component-atom')} /></svg>Button
+## [[comp]] Button
 
 Button is a UI element that triggers an action or event, used to initiate tasks or confirm an action. Button comes in various layouts, styles, and states to convey hierarchy or emphasis.
 
@@ -548,15 +548,15 @@ Loading state can also be combined with all kind of buttons, including icons.
   </div>
   `} />
 
-### Skeleton
+#### Skeleton
 
 <SkeletonRedirect component="button" />
 
 <Example buttonLabel="button skeleton" code={`<div aria-busy="true" inert>
     <button type="button" class="btn btn-default">Default</button>
   </div>`} />
 
-## Layout
+### Layout
 
 #### Block buttons
 
@@ -594,7 +594,7 @@ Additional utilities can be used to adjust the alignment of buttons when horizon
 
 If you don’t want the button text to wrap, you can add the `.text-nowrap` class to the button. In Sass, you can set `$btn-white-space: nowrap` to disable text wrapping for each button.
 
-## <svg class="hl-small-icon me-scaled-2xsmall mb-xsmall" width="1rem" height="1rem" aria-hidden="true"><use xlink:href={getVersionedDocsPath('assets/img/ouds-web-sprite.svg#component-atom')} /></svg>Navigation button
+## [[comp]] Navigation button
 
 Navigation button is a UI element that enables movement between different pages within a multi-page interface. Navigation button is typically arranged in a sequence to indicate the user’s current position and provide controls for accessing previous, next, or specific pages.
 

site/src/content/docs/components/chips.mdx

@@ -84,7 +84,7 @@ Here is a table summarizing the pseudo elements that are used by the different v
 
 {/* | Filter expand chip | Used       | Used      | */}
 
-## <svg class="hl-small-icon me-scaled-2xsmall mb-xsmall" width="1rem" height="1rem" aria-hidden="true"><use xlink:href={getVersionedDocsPath('assets/img/ouds-web-sprite.svg#component-atom')} /></svg>Filter chip
+## [[comp]] Filter chip
 
 Filter chip is a UI element that enables users to select or deselect options within a series, commonly used to capture filtering decisions.
 
@@ -309,7 +309,7 @@ document.querySelectorAll('.chip-suggestion').forEach(chipElement => {
 })
 ```
 
-## <svg class="hl-small-icon me-scaled-2xsmall mb-xsmall" width="1rem" height="1rem" aria-hidden="true"><use xlink:href={getVersionedDocsPath('assets/img/ouds-web-sprite.svg#component-atom')} /></svg>Suggestion chip
+## [[comp]] Suggestion chip
 
 Suggestion chip is a UI element that presents recommended or predictive options based on the user's input or context, often utilised to capture filtering decisions.
 
@@ -442,7 +442,7 @@ The following example shows every possible renderings depending on the suggestio
 
 ## Layout
 
-This part explains global truth among all the chip variants.
+This layout section applies to both chip component types.
 
 ### Overflowing
 

site/src/content/docs/components/tags.mdx

@@ -87,7 +87,7 @@ Keep in mind that visually impaired and blind users will lack the visual context
 
 Several examples are provided below, but they need to be adapted for actual use cases.
 
-## <svg class="hl-small-icon me-scaled-2xsmall mb-xsmall" width="1rem" height="1rem" aria-hidden="true"><use xlink:href={getVersionedDocsPath('assets/img/ouds-web-sprite.svg#component-atom')} /></svg>Tag
+## [[comp]] Tag
 
 Tag is a UI element that shows brief information, such as a label, keyword, or category.
 
@@ -423,7 +423,7 @@ Tags can be added side by side. They require horizontal and vertical spacing bet
     <li class="tag">Label 6</li>
   </ul>`} />
 
-## <svg class="hl-small-icon me-scaled-2xsmall mb-xsmall" width="1rem" height="1rem" aria-hidden="true"><use xlink:href={getVersionedDocsPath('assets/img/ouds-web-sprite.svg#component-atom')} /></svg>Input tag
+## [[comp]] Input tag
 
 Input tag is a UI element that renders an entered value as a tag, allowing it to display brief information like a label, keyword, or category.
 

site/src/layouts/DocsLayout.astro

@@ -150,7 +150,7 @@ const multipleComponents = componentsVersions.length > 1 ? 's' : ''
             <hr class="d-none d-md-block my-small ms-large" />
             <div class="collapse bd-toc-collapse ms-md-xsmall" id="tocContents">
               <nav id="TableOfContents" aria-labelledby="docs-toc">
-                <TableOfContents headings={headings} />
+                <TableOfContents headings={headings} types={frontmatter.types} />
               </nav>
             </div>
           )

site/src/libs/astro.ts

@@ -9,7 +9,7 @@ import type { Element, Text } from 'hast'
 import rehypeAutolinkHeadings from 'rehype-autolink-headings'
 import { getConfig } from './config'
 import { rehypeBsTable } from './rehype'
-import { remarkBsConfig, remarkBsDocsref } from './remark'
+import { remarkBsComp, remarkBsConfig, remarkBsDocsref } from './remark'
 import { configurePrism } from './prism'
 import {
   docsDirectory,
@@ -83,7 +83,7 @@ export function oudsWeb(): AstroIntegration[] {
                 ],
                 rehypeBsTable
               ],
-              remarkPlugins: [remarkBsConfig, remarkBsDocsref]
+              remarkPlugins: [remarkBsConfig, remarkBsDocsref, remarkBsComp]
             }
           })
         },

site/src/libs/remark.ts

@@ -4,13 +4,16 @@ import type { Plugin } from 'unified'
 import { visit } from 'unist-util-visit'
 import { getConfig } from './config'
 import { getVersionedDocsPath } from './path'
+import { getComponentSVG } from './utils'
 
 // [[config:foo]]
 // [[config:foo.bar]]
 const configRegExp = /\[\[config:(?<name>[\w\.]+)]]/g
 // [[docsref:/foo]]
 // [[docsref:/foo/bar#baz]]
 const docsrefRegExp = /\[\[docsref:(?<path>[\w\.\/#-]+)]]/g
+// [[comp]]
+const compRegExp = /\[\[comp\]\]\s*/
 
 // A remark plugin to replace config values embedded in markdown (or MDX) files.
 // For example, [[config:foo]] will be replaced with the value of the `foo` key in the `config.yml` file.
@@ -86,6 +89,34 @@ export const remarkBsDocsref: Plugin<[], Root> = function () {
   }
 }
 
+// A remark plugin to add an svg to component titles.
+export const remarkBsComp: Plugin<[], Root> = function () {
+  return function remarkBsCompPlugin(ast) {
+    // https://github.com/syntax-tree/mdast#nodes
+    // https://github.com/syntax-tree/mdast-util-mdx-jsx#nodes
+    visit(ast, ['text'], (node, index, parent) => {
+      switch (node.type) {
+        case 'text': {
+          if (node.value.match(compRegExp)) {
+            parent.children = [{
+              type: 'html',
+              value: getComponentSVG('hl-small-icon me-scaled-2xsmall mb-xsmall')
+            }, ...parent.children]
+            node.value = replaceCompInText(node.value)
+          }
+          break
+        }
+      }
+    })
+  }
+}
+
+function replaceCompInText(text: string) {
+  return text.replace(compRegExp, (_match, path) => {
+    return ``
+  })
+}
+
 export function replaceConfigInText(text: string) {
   return text.replace(configRegExp, (_match, path) => {
     const value = getConfigValueAtPath(path)

site/src/libs/toc.ts

@@ -2,11 +2,12 @@ import type { MarkdownHeading } from 'astro'
 import { getConfig } from './config'
 
 // Generate a tree like structure from a list of headings.
-export function generateToc(allHeadings: MarkdownHeading[]) {
+export function generateToc(allHeadings: MarkdownHeading[], types?: string[]) {
   const headings = allHeadings.filter(
     (heading) => heading.depth >= getConfig().toc.min && heading.depth <= getConfig().toc.max
   )
 
+  const hasComponentTypes: boolean = !!headings.find((heading) => heading.slug === 'component-types')
   const toc: TocEntry[] = []
 
   for (const heading of headings) {
@@ -15,6 +16,10 @@ export function generateToc(allHeadings: MarkdownHeading[]) {
       continue
     }
 
+    if (hasComponentTypes && heading.depth === 2 && types?.includes(heading.text)) {
+      heading.text = `[[comp]] ${heading.text}`
+    }
+
     const previousEntry = toc[toc.length - 1]
 
     if (heading.depth === previousEntry.depth) {