feat(markdown): support directives, add callout and tabs

api-goldens/element-ng/markdown/directives/tabs/index.api.md

@@ -0,0 +1,17 @@
+## Public API Report File for "@siemens/element-ng_markdown_directives_tabs"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { InputSignal } from '@angular/core';
+import { Node as Node_2 } from 'mdast';
+import { Parent } from 'mdast';
+import { Type } from '@angular/core';
+
+// @public
+export const siMarkdownTabsetDirective: () => TypeHandler;
+
+// (No @packageDocumentation comment for this package)
+
+```

api-goldens/element-ng/markdown/index.api.md

@@ -23,6 +23,7 @@ import { RootContent } from 'mdast';
 import { Signal } from '@angular/core';
 import { TemplateRef } from '@angular/core';
 import { Transformer as Transformer_2 } from 'unified';
+import { TranslatableString } from '@siemens/element-translate-ng/translate-types';
 import { Type } from '@angular/core';
 
 // @public
@@ -58,8 +59,16 @@ export interface ComputedAsyncOptions<T, R> {
     params: () => R;
 }
 
+// @public
+export interface DirectiveNode extends Parent {
+    attributes: Record<string, string | undefined>;
+    name: string;
+    // (undocumented)
+    type: 'containerDirective' | 'leafDirective' | 'textDirective';
+}
+
 // @public (undocumented)
-export type ExtendedRootContent = RootContent | Footnotes | Citations;
+export type ExtendedRootContent = RootContent | Footnotes | Citations | DirectiveNode;
 
 // @public
 export interface Footnotes extends Parent {
@@ -81,6 +90,20 @@ export interface PluginWithOptions {
 // @public
 export const SI_MARKDOWN_CONTROL: InjectionToken<SiMarkdownControl>;
 
+// @public (undocumented)
+export class SiMarkdownCalloutComponent implements SiMarkdownExtensionComponent {
+    // (undocumented)
+    readonly callouts: Record<CalloutType, Callout>;
+    // (undocumented)
+    readonly icons: Record<"elementLightOn", string>;
+    // (undocumented)
+    readonly node: _angular_core.InputSignal<Node_2>;
+    // (undocumented)
+    readonly options: _angular_core.InputSignal<unknown>;
+    // (undocumented)
+    readonly parent: _angular_core.InputSignal<Parent>;
+}
+
 // @public
 export interface SiMarkdownCitation extends SourceReference {
     identifier?: string;
@@ -118,9 +141,13 @@ export interface SiMarkdownControl {
     templates: Signal<Map<string, TemplateRef<any>>>;
 }
 
+// @public
+export const siMarkdownDirective: (directives: ReadonlyMap<string, TypeHandler>) => SiMarkdownExtension;
+
 // @public
 export interface SiMarkdownExtension {
     codeTypes?: TypeHandler[];
+    directives?: TypeHandler[];
     plugins?: PluginWithOptions[];
     types?: TypeHandler[];
 }
@@ -177,6 +204,7 @@ export class SiMarkdownOptions {
     installExtension(extension: SiMarkdownExtension): SiMarkdownOptions;
     installUnifiedPlugin(plugin: UnifiedPlugin, options?: UnifiedPluginOptions): SiMarkdownOptions;
     makeProcessor(meta: SiMarkdownMetadata): Processor<Root, Root, SiMarkdownRoot, undefined, undefined>;
+    registerDirective(directives: TypeHandler | TypeHandler[]): SiMarkdownOptions;
     setCodeHighlighter(highlighter?: SiMarkdownHighlighter): SiMarkdownOptions;
 }
 

docs/components/chat-messages/markdown.md

@@ -111,6 +111,94 @@ by the Element integrations, such as emoji shortcodes.
 > **Bundle size:** KaTeX, Mermaid, Highlight.js, and additional `unified` plugins increase the
 > application bundle size. Import and configure only the integrations your Markdown content requires.
 
+### Directives
+
+Directives add named, component-backed elements to Markdown. The renderer supports the directive
+syntax provided by [`remark-directive`](https://github.com/remarkjs/remark-directive): inline
+directives use `:name[label]{attributes}`, leaf directives use `::name{attributes}`, and container
+directives wrap Markdown content with matching colon fences, at least three colons.
+
+```md
+:::name{attribute=value}
+Normal **Markdown** content.
+:::
+```
+
+Register a directive handler with `registerDirective()`. A handler maps a directive name to an
+Angular component that implements `SiMarkdownExtensionComponent`; that component receives the
+parsed directive node, its parent, and any registered options as signal inputs.
+
+Example:
+
+```md
+::notice{message="Scheduled maintenance starts at 22:00."}
+```
+
+```ts
+import { Component, input } from '@angular/core';
+import {
+  makeSiMarkdownOptions,
+  type SiMarkdownDirectiveNode,
+  type SiMarkdownExtensionComponent
+} from '@siemens/element-ng/markdown';
+import { type Node, type Parent } from 'mdast';
+
+@Component({
+  selector: 'si-markdown-notice',
+  template: '<div class="notice">{{ node().attributes.message }}</div>'
+})
+class MarkdownNoticeComponent implements SiMarkdownExtensionComponent {
+  readonly node = input.required<SiMarkdownDirectiveNode>();
+  readonly parent = input.required<Parent>();
+  readonly options = input<unknown>();
+}
+
+protected readonly markdownOptions = makeSiMarkdownOptions().registerDirective({
+  type: 'notice',
+  component: MarkdownNoticeComponent
+});
+```
+
+#### Callout
+
+The `callout` container directive is integrated by default. Use its optional `type` attribute to
+choose a visual severity: `success`, `info`, `warning`, `danger`, `caution`, `critical`, `note`,
+or `tip`. `note` is the default.
+
+```md
+:::callout{type=warning heading="Optional heading"}
+This action cannot be undone.
+:::
+```
+
+#### Tabs
+
+The tabset directive is an opt-in directive that adds Element tabset. Register
+`siMarkdownTabsetDirective()` to enable the `tabset` container directive. Its child `tab`
+directives map to `si-tab`; only their `heading` attribute is used. Use a longer fence for the
+outer `tabset` when nesting `tab` directives.
+
+```ts
+import { makeSiMarkdownOptions } from '@siemens/element-ng/markdown';
+import { siMarkdownTabsetDirective } from '@siemens/element-ng/markdown/directives/tabs';
+
+protected readonly markdownOptions = makeSiMarkdownOptions().registerDirective(
+  siMarkdownTabsetDirective()
+);
+```
+
+```md
+::::tabset{height=12rem}
+:::tab{heading="First tab"}
+First tab content.
+:::
+
+:::tab{heading="Second tab"}
+Second tab content.
+:::
+::::
+```
+
 ### Custom extension
 
 An extension can install `unified` plugin(s) and associate the AST node types produced by that

package.json

@@ -113,6 +113,7 @@
     "ol": "10.10.0",
     "ol-ext": "4.0.38",
     "ol-mapbox-style": "13.4.2",
+    "remark-directive": "^4.0.0",
     "remark-gemoji": "^8.0.0",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",