Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Addon-docs/Angular: Fix default values in ArgsTable #15881

Merged
merged 13 commits into from
Sep 1, 2021
Merged

Addon-docs/Angular: Fix default values in ArgsTable #15881

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
dec827a
Show defaultValue in ArgsTable
dexster Aug 18, 2021
6d36204
Show defaultValue in ArgsTable
dexster Aug 18, 2021
f792042
Added compodoc defaultValues to table summary
dexster Aug 18, 2021
2de84d9
Swap out DOMParser due to Husky error
dexster Aug 19, 2021
9f24a79
Remove eval and return string
dexster Aug 23, 2021
8473015
DOMParser update
dexster Aug 24, 2021
a0aaf5c
Merge branch 'next' into Fix_defaultvalues_in_Docs
dexster Aug 31, 2021
adda447
Explicit type conversion check for boolean defaultValues
dexster Aug 31, 2021
146e8fd
Update addons/docs/src/frameworks/angular/compodoc.ts
shilman Aug 31, 2021
7651889
Removed console.log
dexster Aug 31, 2021
37ae3dd
Cater for compodoc issues when casting types
dexster Sep 1, 2021
7763757
Merge branch 'Fix_defaultvalues_in_Docs' of https://github.com/dexste…
dexster Sep 1, 2021
a2d0754
Set eventemitter to undefined to allow actions to function correctly
dexster Sep 1, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 71 additions & 5 deletions addons/docs/src/frameworks/angular/__testfixtures__/doc-button/argtypes.snapshot
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@ Object {
"name": "_inputValue",
"table": Object {
"category": "properties",
"defaultValue": Object {
"summary": "some value",
},
"type": Object {
"required": true,
"summary": "string",
Expand All @@ -24,6 +27,9 @@ Private value.",
"name": "_value",
"table": Object {
"category": "properties",
"defaultValue": Object {
"summary": "Private hello",
},
"type": Object {
"required": true,
"summary": "string",
Expand All @@ -39,6 +45,9 @@ Private value.",
"name": "accent",
"table": Object {
"category": "inputs",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": true,
"summary": "ButtonAccent",
Expand All @@ -54,6 +63,9 @@ Private value.",
"name": "appearance",
"table": Object {
"category": "inputs",
"defaultValue": Object {
"summary": "secondary",
},
"type": Object {
"required": true,
"summary": "\\"primary\\" | \\"secondary\\"",
Expand All @@ -73,6 +85,9 @@ Private value.",
"name": "buttonRef",
"table": Object {
"category": "view child",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": true,
"summary": "ElementRef",
Expand All @@ -92,6 +107,9 @@ An internal calculation method which adds \`x\` and \`y\` together.
"name": "calc",
"table": Object {
"category": "methods",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": false,
"summary": "(x: number, y: string | number) => number",
Expand All @@ -102,18 +120,21 @@ An internal calculation method which adds \`x\` and \`y\` together.
},
},
"focus": Object {
"defaultValue": false,
"defaultValue": "false",
"description": "",
"name": "focus",
"table": Object {
"category": "properties",
"defaultValue": Object {
"summary": "false",
},
"type": Object {
"required": true,
"summary": "",
},
},
"type": Object {
"name": "boolean",
"name": "string",
},
},
"inputValue": Object {
Expand All @@ -122,6 +143,9 @@ An internal calculation method which adds \`x\` and \`y\` together.
"name": "inputValue",
"table": Object {
"category": "inputs",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": true,
"summary": "string",
Expand All @@ -138,6 +162,9 @@ Public value.",
"name": "internalProperty",
"table": Object {
"category": "properties",
"defaultValue": Object {
"summary": "Public hello",
},
"type": Object {
"required": true,
"summary": "string",
Expand All @@ -148,11 +175,14 @@ Public value.",
},
},
"isDisabled": Object {
"defaultValue": false,
"defaultValue": "false",
"description": "Sets the button to a disabled state.",
"name": "isDisabled",
"table": Object {
"category": "inputs",
"defaultValue": Object {
"summary": "false",
},
"type": Object {
"required": true,
"summary": "boolean",
Expand All @@ -168,6 +198,9 @@ Public value.",
"name": "item",
"table": Object {
"category": "inputs",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": true,
"summary": "[]",
Expand All @@ -183,6 +216,9 @@ Public value.",
"name": "label",
"table": Object {
"category": "inputs",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": true,
"summary": "string",
Expand All @@ -194,7 +230,7 @@ Public value.",
},
"onClick": Object {
"action": "onClick",
"defaultValue": undefined,
"defaultValue": "new EventEmitter<Event>()",
"description": "

Handler to be called when the button is clicked by a user.
Expand All @@ -204,6 +240,9 @@ Will also block the emission of the event if \`isDisabled\` is true.
"name": "onClick",
"table": Object {
"category": "outputs",
"defaultValue": Object {
"summary": "new EventEmitter<Event>()",
},
"type": Object {
"required": true,
"summary": "EventEmitter",
Expand All @@ -219,6 +258,9 @@ Will also block the emission of the event if \`isDisabled\` is true.
"name": "onClickListener",
"table": Object {
"category": "methods",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": false,
"summary": "(btn: ) => void",
Expand All @@ -238,6 +280,9 @@ A private method.
"name": "privateMethod",
"table": Object {
"category": "methods",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": false,
"summary": "(password: string) => void",
Expand All @@ -253,6 +298,9 @@ A private method.
"name": "processedItem",
"table": Object {
"category": "properties",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": true,
"summary": "T[]",
Expand All @@ -272,6 +320,9 @@ A protected method.
"name": "protectedMethod",
"table": Object {
"category": "methods",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": false,
"summary": "(id?: number) => void",
Expand All @@ -288,6 +339,9 @@ A public method using an interface.",
"name": "publicMethod",
"table": Object {
"category": "methods",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": false,
"summary": "(things: ISomeInterface) => void",
Expand All @@ -303,6 +357,9 @@ A public method using an interface.",
"name": "showKeyAlias",
"table": Object {
"category": "inputs",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": true,
"summary": "",
Expand All @@ -318,6 +375,9 @@ A public method using an interface.",
"name": "size",
"table": Object {
"category": "inputs",
"defaultValue": Object {
"summary": "medium",
},
"type": Object {
"required": true,
"summary": "ButtonSize",
Expand All @@ -333,6 +393,9 @@ A public method using an interface.",
"name": "someDataObject",
"table": Object {
"category": "inputs",
"defaultValue": Object {
"summary": undefined,
},
"type": Object {
"required": true,
"summary": "ISomeInterface",
Expand All @@ -343,11 +406,14 @@ A public method using an interface.",
},
},
"somethingYouShouldNotUse": Object {
"defaultValue": false,
"defaultValue": "false",
"description": "Some input you shouldn't use.",
"name": "somethingYouShouldNotUse",
"table": Object {
"category": "inputs",
"defaultValue": Object {
"summary": "false",
},
"type": Object {
"required": true,
"summary": "boolean",
Expand Down
17 changes: 15 additions & 2 deletions addons/docs/src/frameworks/angular/compodoc.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import {
Pipe,
Property,
Directive,
JsDocTag,
} from './types';

export const isMethod = (methodOrProp: Method | Property): methodOrProp is Method => {
Expand Down Expand Up @@ -156,8 +157,17 @@ export const extractType = (property: Property, defaultValue: any) => {

const extractDefaultValue = (property: Property) => {
try {
// eslint-disable-next-line no-eval
const value = eval(property.defaultValue);
let value = property.defaultValue?.replace(/^'(.*)'$/, '$1');
if (value == null && property.jsdoctags.length > 0) {
property.jsdoctags.forEach((tag: JsDocTag) => {
if (['default', 'defaultvalue'].includes(tag.tagName.escapedText)) {
const tmp = window.document.createElement('DIV');
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this just to unescape HTML? If so, is there a library we can use for this?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I originally used DOMParser code below but husky pre-commit throws this error - 'DOMParser' is not defined.

const dom = new DOMParser().parseFromString(tag.comment, 'text/html');
value = dom.body.textContent;

If I use window.DOMParser then Typescript has errors. If I add // @ts-ignore then all is well. WDYT?

 // @ts-ignore
const dom = new window.DOMParser().parseFromString(tag.comment, 'text/html');
value = dom.body.textContent;

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i like this better if it works 😁

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@shilman It's been done. Can we merge?

tmp.innerHTML = tag.comment;
value = tmp.textContent;
}
});
}

return value;
} catch (err) {
logger.debug(`Error extracting ${property.name}: ${property.defaultValue}`);
Expand Down Expand Up @@ -189,11 +199,13 @@ export const extractArgTypesFromData = (componentData: Class | Directive | Injec
data.forEach((item: Method | Property) => {
const section = mapItemToSection(key, item);
const defaultValue = isMethod(item) ? undefined : extractDefaultValue(item as Property);

const type =
isMethod(item) || (section !== 'inputs' && section !== 'properties')
? { name: 'void' }
: extractType(item as Property, defaultValue);
const action = section === 'outputs' ? { action: item.name } : {};

const argType = {
name: item.name,
description: item.rawdescription || item.description,
Expand All @@ -206,6 +218,7 @@ export const extractArgTypesFromData = (componentData: Class | Directive | Injec
summary: isMethod(item) ? displaySignature(item) : item.type,
required: isMethod(item) ? false : !item.optional,
},
defaultValue: { summary: defaultValue },
},
};

Expand Down
8 changes: 8 additions & 0 deletions addons/docs/src/frameworks/angular/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,13 @@ export interface Method {
rawdescription?: string;
}

export interface JsDocTag {
comment?: string;
tagName?: {
escapedText?: string;
};
}

export interface Property {
name: string;
decorators?: Decorator[];
Expand All @@ -15,6 +22,7 @@ export interface Property {
defaultValue?: string;
description?: string;
rawdescription?: string;
jsdoctags?: JsDocTag[];
}

export interface Class {
Expand Down
19 changes: 19 additions & 0 deletions examples/angular-cli/src/stories/addons/docs/doc-button/doc-button.component.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,25 @@ export enum ButtonAccent {
export class DocButtonComponent<T> {
@ViewChild('buttonRef', { static: false }) buttonRef: ElementRef;

/** Test default value. */
@Input()
public theDefaultValue = 'Default value in component';

/**
* Setting default value here because compodoc won't get the default value for accessors
* @default Another default value
* */
@Input()
get anotherDefaultValue() {
return this._anotherDefaultValue;
}

set anotherDefaultValue(v: string) {
this._anotherDefaultValue = v;
}

_anotherDefaultValue = 'Another default value';

/** Appearance style of the button. */
@Input()
public appearance: 'primary' | 'secondary' = 'secondary';
Expand Down
10 changes: 10 additions & 0 deletions examples/angular-cli/src/stories/addons/docs/doc-button/doc-button.stories.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import { Meta, Story, Canvas, ArgsTable } from '@storybook/addon-docs';
import { DocButtonComponent } from './doc-button.component';

<Meta title='Addons/Docs/DocButtonDefaultValue' />

# ArgsTable in MDX with default values

`theDefaultValue` should show the default value from the component comments

<ArgsTable of={DocButtonComponent}/>
7 changes: 7 additions & 0 deletions examples/angular-cli/src/stories/addons/docs/doc-button/doc-button.stories.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,13 @@ export const Basic = (args) => ({
props: args,
});
Basic.args = { label: 'Args test', isDisabled: false };
Basic.ArgTypes = {
theDefaultValue: {
table: {
defaultValue: { summary: 'Basic default value' },
},
},
};

export const WithTemplate = (args) => ({
props: args,
Expand Down