Skip to content

Commit

Permalink
feat(addon-doc): add type reference handler for improve documentation (
Browse files Browse the repository at this point in the history
  • Loading branch information
splincode authored Dec 1, 2023
1 parent 40af9f3 commit e139770
Show file tree
Hide file tree
Showing 14 changed files with 215 additions and 34 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@ import {
TuiNotificationModule,
TuiPrimitiveTextfieldModule,
TuiTextfieldControllerModule,
TuiTooltipModule,
} from '@taiga-ui/core';
import {
TuiBadgeModule,
Expand All @@ -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: [
Expand All @@ -42,7 +41,6 @@ import {TuiStripOptionalPipe} from './pipes/strip-optional.pipe';
TuiBadgeModule,
TuiSelectModule,
TuiToggleModule,
TuiTooltipModule,
TuiLinkModule,
TuiInputNumberModule,
TuiModeModule,
Expand All @@ -63,7 +61,7 @@ import {TuiStripOptionalPipe} from './pipes/strip-optional.pipe';
TuiIsOptionalPipe,
TuiShowCleanerPipe,
TuiStripOptionalPipe,
TuiShowContentTooltip,
TuiDocTypeReferencePipe,
TuiDocDocumentationComponent,
TuiIsPrimitivePolymorpheusContentPipe,
TuiDocDocumentationPropertyConnectorDirective,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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%;
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

This file was deleted.

Original file line number Diff line number Diff line change
@@ -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);
}
}
2 changes: 1 addition & 1 deletion projects/addon-doc/components/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
5 changes: 3 additions & 2 deletions projects/addon-doc/components/main/main.style.less
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
1 change: 1 addition & 0 deletions projects/addon-doc/tokens/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
12 changes: 12 additions & 0 deletions projects/addon-doc/tokens/type-reference-handler.ts
Original file line number Diff line number Diff line change
@@ -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);
1 change: 1 addition & 0 deletions projects/addon-doc/utils/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
58 changes: 58 additions & 0 deletions projects/addon-doc/utils/test/type-reference-parser.spec.ts
Original file line number Diff line number Diff line change
@@ -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`},
]);
});
});
30 changes: 30 additions & 0 deletions projects/addon-doc/utils/type-reference-parser.ts
Original file line number Diff line number Diff line change
@@ -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});
}, []);
}
30 changes: 30 additions & 0 deletions projects/demo/src/modules/app/app.providers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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> =>
Expand Down
6 changes: 2 additions & 4 deletions projects/demo/src/modules/components/link/link.template.html
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,7 @@
<ng-template
documentationPropertyMode="input"
documentationPropertyName="mode"
documentationPropertyType="'positive'
| 'negative' | null"
documentationPropertyType="'positive' | 'negative' | null"
[documentationPropertyValues]="modeValues"
[(documentationPropertyValue)]="mode"
>
Expand All @@ -82,8 +81,7 @@
<ng-template
documentationPropertyMode="input"
documentationPropertyName="icon"
documentationPropertyType="string |
null"
documentationPropertyType="string | null"
[documentationPropertyValues]="iconVariants"
[(documentationPropertyValue)]="icon"
>
Expand Down

0 comments on commit e139770

Please sign in to comment.