feat(addon-doc): add type reference handler for improve documentation

projects/addon-doc/components/documentation/documentation.module.ts

@@ -12,7 +12,6 @@ import {
     TuiNotificationModule,
     TuiPrimitiveTextfieldModule,
     TuiTextfieldControllerModule,
-    TuiTooltipModule,
 } from '@taiga-ui/core';
 import {
     TuiBadgeModule,
@@ -27,12 +26,12 @@ import {TuiDocDocumentationComponent} from './documentation.component';
 import {TuiDocDocumentationPropertyConnectorDirective} from './documentation-property-connector.directive';
 import {TuiShowCleanerPipe} from './pipes/cleaner.pipe';
 import {TuiGetColorPipe} from './pipes/color.pipe';
-import {TuiShowContentTooltip} from './pipes/content-tooltip.pipe';
 import {TuiInspectPipe} from './pipes/inspect.pipe';
 import {TuiGetOpacityPipe} from './pipes/opacity.pipe';
 import {TuiIsOptionalPipe} from './pipes/optional.pipe';
 import {TuiIsPrimitivePolymorpheusContentPipe} from './pipes/primitive-polymorpheus-content.pipe';
 import {TuiStripOptionalPipe} from './pipes/strip-optional.pipe';
+import {TuiDocTypeReferencePipe} from './pipes/type-reference.pipe';
 
 @NgModule({
     imports: [
@@ -42,7 +41,6 @@ import {TuiStripOptionalPipe} from './pipes/strip-optional.pipe';
         TuiBadgeModule,
         TuiSelectModule,
         TuiToggleModule,
-        TuiTooltipModule,
         TuiLinkModule,
         TuiInputNumberModule,
         TuiModeModule,
@@ -63,7 +61,7 @@ import {TuiStripOptionalPipe} from './pipes/strip-optional.pipe';
         TuiIsOptionalPipe,
         TuiShowCleanerPipe,
         TuiStripOptionalPipe,
-        TuiShowContentTooltip,
+        TuiDocTypeReferencePipe,
         TuiDocDocumentationComponent,
         TuiIsPrimitivePolymorpheusContentPipe,
         TuiDocDocumentationPropertyConnectorDirective,

projects/addon-doc/components/documentation/documentation.style.less

@@ -110,3 +110,30 @@
 .t-heading {
     font: var(--tui-font-heading-4);
 }
+
+.t-code-type {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: start;
+}
+
+.t-code-reference {
+    display: inline-flex;
+    color: var(--tui-link);
+    text-decoration: none;
+    align-items: center;
+    justify-content: center;
+    gap: 3px;
+
+    &:after {
+        content: '';
+        font-size: 1rem;
+        width: 1rem;
+        height: 1rem;
+        background: currentColor;
+        // TODO: migrate to <tui-icon /> in v4.0
+        mask: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="1rem" height="1rem" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path><polyline points="15 3 21 3 21 9"></polyline><line x1="10" y1="14" x2="21" y2="3"></line></svg>')
+            center/100%;
+    }
+}

projects/addon-doc/components/documentation/documentation.template.html

@@ -49,25 +49,27 @@
             </td>
             <td class="t-cell">
                 <span class="type">
-                    <code>{{ propertyConnector.documentationPropertyType }}</code>
-                    <tui-tooltip
-                        *ngIf="propertyConnector.documentationPropertyType | tuiShowContentTooltip"
-                        [content]="content"
-                        [describeId]="propertyConnector.attrName"
-                    >
-                        <ng-template #content>
-                            {{ texts[4] }}
+                    <code class="t-code-type">
+                        <ng-container
+                            *ngFor="
+                                let item of propertyConnector.documentationPropertyType | tuiDocTypeReference;
+                                let last = last
+                            "
+                        >
                             <a
-                                href="https://github.com/taiga-family/ng-polymorpheus"
-                                rel="noreferrer"
+                                *ngIf="item.reference; else default"
                                 target="_blank"
-                                tuiLink
-                                tuiMode="onDark"
+                                class="t-code-reference"
+                                [attr.href]="item.reference"
                             >
-                                <code>ng-polymorpheus</code>
+                                {{ item.type }}
                             </a>
-                        </ng-template>
-                    </tui-tooltip>
+                            <ng-template #default>
+                                {{ item.type }}
+                            </ng-template>
+                            <span *ngIf="!last">&nbsp;|&nbsp;</span>
+                        </ng-container>
+                    </code>
                 </span>
             </td>
             <td

projects/addon-doc/components/documentation/pipes/type-reference.pipe.ts

@@ -0,0 +1,31 @@
+import {Inject, Pipe, PipeTransform} from '@angular/core';
+import {
+    TUI_DOC_TYPE_REFERENCE_HANDLER,
+    TUI_DOC_TYPE_REFERENCE_PARSER,
+} from '@taiga-ui/addon-doc/tokens';
+import type {TuiDocTypeReferenceParsed} from '@taiga-ui/addon-doc/utils';
+import {TuiHandler, TuiStringHandler} from '@taiga-ui/cdk';
+
+@Pipe({name: `tuiDocTypeReference`})
+export class TuiDocTypeReferencePipe implements PipeTransform {
+    constructor(
+        @Inject(TUI_DOC_TYPE_REFERENCE_PARSER)
+        private readonly parser: TuiHandler<string, TuiDocTypeReferenceParsed>,
+        @Inject(TUI_DOC_TYPE_REFERENCE_HANDLER)
+        private readonly linkHandler?: TuiStringHandler<string | null> | null,
+    ) {}
+
+    transform(original: string): ReadonlyArray<{
+        type: string;
+        extracted: string;
+        reference: string | null;
+    }> {
+        return this.parser(original)
+            .map(({type, extracted}) => ({
+                type,
+                extracted,
+                reference: this.linkHandler?.(extracted) ?? null,
+            }))
+            .sort((a, b) => b.reference?.localeCompare(a.reference ?? ``) ?? -1);
+    }
+}

projects/addon-doc/components/index.ts

@@ -9,12 +9,12 @@ export * from './documentation/documentation.module';
 export * from './documentation/documentation-property-connector.directive';
 export * from './documentation/pipes/cleaner.pipe';
 export * from './documentation/pipes/color.pipe';
-export * from './documentation/pipes/content-tooltip.pipe';
 export * from './documentation/pipes/inspect.pipe';
 export * from './documentation/pipes/opacity.pipe';
 export * from './documentation/pipes/optional.pipe';
 export * from './documentation/pipes/primitive-polymorpheus-content.pipe';
 export * from './documentation/pipes/strip-optional.pipe';
+export * from './documentation/pipes/type-reference.pipe';
 export * from './example/example.component';
 export * from './example/example.module';
 export * from './example/example.options';

projects/addon-doc/components/main/main.style.less

@@ -57,9 +57,10 @@ code:not(pre code) {
         align-items: center;
         border-radius: 0.25rem;
         font-weight: 500;
-        border: 1px solid var(--tui-base-04);
+        outline: 1px solid var(--tui-base-04);
         font-size: 0.75rem;
-        padding: 0 0.125rem;
+        padding: 0 0.3125rem;
+        margin: 0.125rem 0;
         //noinspection CssInvalidPropertyValue
         text-wrap: wrap;
 

projects/addon-doc/tokens/index.ts

@@ -12,4 +12,5 @@ export * from './scroll-behavior';
 export * from './see-also';
 export * from './source-code';
 export * from './title';
+export * from './type-reference-handler';
 export * from './url-state-handler';

projects/addon-doc/tokens/type-reference-handler.ts

@@ -0,0 +1,12 @@
+import {
+    TuiDocTypeReferenceParsed,
+    tuiTypeReferenceParser,
+} from '@taiga-ui/addon-doc/utils';
+import {tuiCreateToken, TuiHandler, TuiStringHandler} from '@taiga-ui/cdk';
+
+export const TUI_DOC_TYPE_REFERENCE_HANDLER = tuiCreateToken<TuiStringHandler<
+    string | null
+> | null>(null);
+
+export const TUI_DOC_TYPE_REFERENCE_PARSER =
+    tuiCreateToken<TuiHandler<string, TuiDocTypeReferenceParsed>>(tuiTypeReferenceParser);

projects/addon-doc/utils/index.ts

@@ -9,3 +9,4 @@ export * from './raw-load-record';
 export * from './sort-pages';
 export * from './to-flat-map-pages';
 export * from './transliterate-keyboard-layout';
+export * from './type-reference-parser';

projects/addon-doc/utils/test/type-reference-parser.spec.ts

@@ -0,0 +1,58 @@
+import {tuiTypeReferenceParser} from '@taiga-ui/addon-doc';
+
+describe(`tuiTypeReferenceParser`, () => {
+    it(`parse`, () => {
+        expect(
+            tuiTypeReferenceParser(`
+                    PolymorpheusContent<TuiValueContentContext<T | G, K | V>>
+                        | Map<T, boolean>
+                        | ReadonlyArray<string | null>
+                        | readonly string[]
+                        | T
+                        | ReadonlyArray<readonly number[]>
+                        | [TuiDay, number][]
+                        | TuiStringHandler<number>
+                        | null
+                        | readonly [number, number]
+                        | 'positive'
+                        | 'negative'
+                        | -1
+                        | 2
+                        | 0
+                        | void
+                        | CustomEvent<TuiIconError>
+                        | TuiComparator<T>
+                        | readonly T[]
+                        | TuiDay
+                        | [TuiTime, TuiTime]
+                        | T[][]
+            `),
+        ).toEqual([
+            {
+                type: `PolymorpheusContent<TuiValueContentContext<T | G, K | V>>`,
+                extracted: `PolymorpheusContent`,
+            },
+            {type: `Map<T, boolean>`, extracted: `Map`},
+            {type: `ReadonlyArray<string | null>`, extracted: `string`},
+            {type: `readonly string[]`, extracted: `string`},
+            {type: `T`, extracted: `unknown`},
+            {type: `ReadonlyArray<readonly number[]>`, extracted: `number`},
+            {type: `[TuiDay, number][]`, extracted: `TuiDay`},
+            {type: `TuiStringHandler<number>`, extracted: `TuiStringHandler`},
+            {type: `null`, extracted: `null`},
+            {type: `readonly [number, number]`, extracted: `number`},
+            {type: `'positive'`, extracted: `string`},
+            {type: `'negative'`, extracted: `string`},
+            {type: `-1`, extracted: `number`},
+            {type: `2`, extracted: `number`},
+            {type: `0`, extracted: `number`},
+            {type: `void`, extracted: `void`},
+            {type: `CustomEvent<TuiIconError>`, extracted: `CustomEvent`},
+            {type: `TuiComparator<T>`, extracted: `TuiComparator`},
+            {type: `readonly T[]`, extracted: `unknown`},
+            {type: `TuiDay`, extracted: `TuiDay`},
+            {type: `[TuiTime, TuiTime]`, extracted: `TuiTime`},
+            {type: `T[][]`, extracted: `unknown`},
+        ]);
+    });
+});

projects/addon-doc/utils/type-reference-parser.ts

@@ -0,0 +1,30 @@
+export type TuiDocTypeReferenceParsed = ReadonlyArray<{type: string; extracted: string}>;
+
+export function tuiTypeReferenceParser(types: string): TuiDocTypeReferenceParsed {
+    const generics = types.match(/<([^>]+)>/g) ?? [];
+
+    const escaped = generics
+        .reduce(
+            (result, current) => result.replace(current, current.replace(/\|/g, `&`)),
+            types,
+        )
+        .split(`|`)
+        .map(item => item.trim());
+
+    return escaped.reduce<TuiDocTypeReferenceParsed>((result, type) => {
+        let extracted = type
+            .trim()
+            .replace(/readonly /g, ``)
+            .replace(/\[\]/g, ``);
+
+        extracted =
+            extracted.match(/ReadonlyArray<([^>]+)>/)?.[1]?.split(`&`)?.[0] ?? extracted;
+        extracted = extracted.match(/\[([^\]]+)\]/)?.[1]?.split(`,`)?.[0] ?? extracted;
+        extracted = (extracted.split(`<`)?.[0] ?? extracted)?.trim() ?? ``;
+        extracted = Number.isNaN(parseFloat(extracted)) ? extracted : `number`;
+        extracted = /^'(.+)'$|^"(.+)"$|^`(.+)`$/.test(extracted) ? `string` : extracted;
+        extracted = extracted.length === 1 ? `unknown` : extracted;
+
+        return result.concat({type: type.replace(/&/g, `|`), extracted});
+    }, []);
+}

projects/demo/src/modules/app/app.providers.ts

@@ -20,6 +20,7 @@ import {
     TUI_DOC_SEE_ALSO,
     TUI_DOC_SOURCE_CODE,
     TUI_DOC_TITLE,
+    TUI_DOC_TYPE_REFERENCE_HANDLER,
     TUI_DOC_URL_STATE_HANDLER,
     tuiDocExampleOptionsProvider,
     TuiDocSourceCodePathOptions,
@@ -197,6 +198,35 @@ export const APP_PROVIDERS: Provider[] = [
         useFactory: (baseHref: string) => (tree: UrlTree) =>
             String(tree).replace(baseHref, ``),
     },
+    {
+        provide: TUI_DOC_TYPE_REFERENCE_HANDLER,
+        useValue: (type: string) => {
+            switch (type) {
+                case `any`:
+                case `null`:
+                case `unknown`:
+                case `undefined`:
+                case `boolean`:
+                case `string`:
+                case `void`:
+                case `number`:
+                case `Map`:
+                case `Set`:
+                    return null;
+                case `CustomEvent`:
+                case `Element`:
+                    return `https://developer.mozilla.org/en-US/docs/Web/API/${type}`;
+                case `PolymorpheusContent`:
+                    return `https://github.com/taiga-family/ng-polymorpheus`;
+                case `TrackByFunction`:
+                    return `https://angular.dev/api/core/TrackByFunction`;
+                case `SafeResourceUrl`:
+                    return `https://angular.dev/api/platform-browser/SafeResourceUrl`;
+                default:
+                    return `https://github.com/search?q=%2F%28enum%7Ctype%7Cinterface%7Cclass%7Cfunction%7Cconst%29+${type}%28%3C%7C%5Cs%29%2F+language%3ATypeScript+org%3Ataiga-family&type=code`;
+            }
+        },
+    },
     tuiDocExampleOptionsProvider({fullsize: false}),
     tuiLanguageSwitcher(
         async (language: TuiLanguageName): Promise<unknown> =>

projects/demo/src/modules/components/link/link.template.html

@@ -72,8 +72,7 @@
             <ng-template
                 documentationPropertyMode="input"
                 documentationPropertyName="mode"
-                documentationPropertyType="'positive'
-                | 'negative' | null"
+                documentationPropertyType="'positive' | 'negative' | null"
                 [documentationPropertyValues]="modeValues"
                 [(documentationPropertyValue)]="mode"
             >
@@ -82,8 +81,7 @@
             <ng-template
                 documentationPropertyMode="input"
                 documentationPropertyName="icon"
-                documentationPropertyType="string |
-                null"
+                documentationPropertyType="string | null"
                 [documentationPropertyValues]="iconVariants"
                 [(documentationPropertyValue)]="icon"
             >