@storybook/angular 9.0.0-beta.6 → 9.0.0-beta.7

package/dist/client/docs/__testfixtures__/doc-button/input.mjs

@@ -0,0 +1,201 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-nocheck
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Component, EventEmitter, HostBinding, HostListener, Input, Output, ViewChild, ElementRef, } from '@angular/core';
+export const exportedConstant = 'An exported constant';
+export var ButtonAccent;
+(function (ButtonAccent) {
+    ButtonAccent["Normal"] = "Normal";
+    ButtonAccent["High"] = "High";
+})(ButtonAccent || (ButtonAccent = {}));
+/**
+ * This is a simple button that demonstrates various JSDoc handling in Storybook Docs for Angular.
+ *
+ * It supports [markdown](https://en.wikipedia.org/wiki/Markdown), so you can embed formatted text,
+ * like **bold**, _italic_, and `inline code`.> How you like dem apples?! It's never been easier to
+ * document all your components.
+ *
+ * @string Hello world
+ * @link [Example](http://example.com)
+ * @code `ThingThing`
+ * @html <span class="badge">aaa</span>
+ */
+let InputComponent = class InputComponent {
+    constructor() {
+        /** Appearance style of the button. */
+        this.appearance = 'secondary';
+        /** Sets the button to a disabled state. */
+        this.isDisabled = false;
+        /** Size of the button. */
+        this.size = 'medium';
+        /**
+         * Some input you shouldn't use.
+         *
+         * @deprecated
+         */
+        this.somethingYouShouldNotUse = false;
+        /**
+         * Handler to be called when the button is clicked by a user.
+         *
+         * Will also block the emission of the event if `isDisabled` is true.
+         */
+        this.onClick = new EventEmitter();
+        this._inputValue = 'some value';
+        this.focus = false;
+        /** @ignore */
+        this.ignoredProperty = 'Ignore me';
+        /** Public value. */
+        this.internalProperty = 'Public hello';
+        /** Private value. */
+        this._value = 'Private hello';
+    }
+    /**
+     * This is an internal method that we don't want to document and have added the `ignore`
+     * annotation to.
+     *
+     * @ignore
+     */
+    handleClick(event) {
+        event.stopPropagation();
+        if (!this.isDisabled) {
+            this.onClick.emit(event);
+        }
+    }
+    /** Setter for `inputValue` that is also an `@Input`. */
+    set inputValue(value) {
+        this._inputValue = value;
+    }
+    /** Getter for `inputValue`. */
+    get inputValue() {
+        return this._inputValue;
+    }
+    onClickListener(btn) {
+        console.log('button', btn);
+    }
+    /**
+     * Returns all the CSS classes for the button.
+     *
+     * @ignore
+     */
+    get classes() {
+        return [this.appearance, this.size]
+            .filter((_class) => !!_class)
+            .map((_class) => `btn-${_class}`);
+    }
+    /** Set the private value. */
+    set value(value) {
+        this._value = `${value}`;
+    }
+    /** Get the private value. */
+    get value() {
+        return this._value;
+    }
+    /**
+     * An internal calculation method which adds `x` and `y` together.
+     *
+     * @param x Some number you'd like to use.
+     * @param y Some other number or string you'd like to use, will have `parseInt()` applied before
+     *   calculation.
+     */
+    calc(x, y) {
+        return x + parseInt(`${y}`, 10);
+    }
+    /** A public method using an interface. */
+    publicMethod(things) {
+        console.log(things);
+    }
+    /**
+     * A protected method.
+     *
+     * @param id Some `id`.
+     */
+    protectedMethod(id) {
+        console.log(id);
+    }
+    /**
+     * A private method.
+     *
+     * @param password Some `password`.
+     */
+    privateMethod(password) {
+        console.log(password);
+    }
+    set item(item) {
+        this.processedItem = item;
+    }
+};
+__decorate([
+    ViewChild('buttonRef', { static: false }),
+    __metadata("design:type", ElementRef)
+], InputComponent.prototype, "buttonRef", void 0);
+__decorate([
+    Input(),
+    __metadata("design:type", String)
+], InputComponent.prototype, "appearance", void 0);
+__decorate([
+    Input(),
+    __metadata("design:type", String)
+], InputComponent.prototype, "accent", void 0);
+__decorate([
+    Input(),
+    __metadata("design:type", Object)
+], InputComponent.prototype, "isDisabled", void 0);
+__decorate([
+    Input(),
+    __metadata("design:type", String)
+], InputComponent.prototype, "label", void 0);
+__decorate([
+    Input(),
+    __metadata("design:type", String)
+], InputComponent.prototype, "size", void 0);
+__decorate([
+    Input(),
+    __metadata("design:type", Object)
+], InputComponent.prototype, "someDataObject", void 0);
+__decorate([
+    Input(),
+    __metadata("design:type", Object)
+], InputComponent.prototype, "somethingYouShouldNotUse", void 0);
+__decorate([
+    Output(),
+    __metadata("design:type", Object)
+], InputComponent.prototype, "onClick", void 0);
+__decorate([
+    Input(),
+    __metadata("design:type", String),
+    __metadata("design:paramtypes", [String])
+], InputComponent.prototype, "inputValue", null);
+__decorate([
+    HostListener('click', ['$event.target']),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", void 0)
+], InputComponent.prototype, "onClickListener", null);
+__decorate([
+    HostBinding('class.focused'),
+    __metadata("design:type", Object)
+], InputComponent.prototype, "focus", void 0);
+__decorate([
+    Input('showKeyAlias'),
+    __metadata("design:type", Object)
+], InputComponent.prototype, "showKey", void 0);
+__decorate([
+    Input(),
+    __metadata("design:type", Array),
+    __metadata("design:paramtypes", [Array])
+], InputComponent.prototype, "item", null);
+InputComponent = __decorate([
+    Component({
+        selector: 'doc-button',
+        template: '<button>{{ label }}</button>',
+    })
+], InputComponent);
+export { InputComponent };

package/dist/client/docs/angular-properties.test.mjs

@@ -0,0 +1,34 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+// File hierarchy: __testfixtures__ / some-test-case / input.*
+const inputRegExp = /^input\..*$/;
+describe('angular component properties', () => {
+    const fixturesDir = join(__dirname, '__testfixtures__');
+    readdirSync(fixturesDir, { withFileTypes: true }).forEach((testEntry) => {
+        if (testEntry.isDirectory()) {
+            const testDir = join(fixturesDir, testEntry.name);
+            const testFile = readdirSync(testDir).find((fileName) => inputRegExp.test(fileName));
+            if (testFile) {
+                // TODO: Remove this as soon as the real test is fixed
+                it('true', () => {
+                    expect(true).toEqual(true);
+                });
+                // TODO: Fix this test
+                // it(`${testEntry.name}`, async () => {
+                //   const inputPath = join(testDir, testFile);
+                //   // snapshot the output of compodoc
+                //   const compodocOutput = runCompodoc(inputPath);
+                //   const compodocJson = JSON.parse(compodocOutput);
+                //   await expect(compodocJson).toMatchFileSnapshot(
+                //     join(testDir, `compodoc-${SNAPSHOT_OS}.snapshot`)
+                //   );
+                //   // snapshot the output of addon-docs angular-properties
+                //   const componentData = findComponentByName('InputComponent', compodocJson);
+                //   const argTypes = extractArgTypesFromData(componentData);
+                //   await expect(argTypes).toMatchFileSnapshot(join(testDir, 'argtypes.snapshot'));
+                // });
+            }
+        }
+    });
+});

package/dist/client/docs/compodoc.mjs

@@ -0,0 +1,244 @@
+import { logger } from 'storybook/internal/client-logger';
+import { global } from '@storybook/global';
+export const isMethod = (methodOrProp) => {
+    return methodOrProp.args !== undefined;
+};
+export const setCompodocJson = (compodocJson) => {
+    global.__STORYBOOK_COMPODOC_JSON__ = compodocJson;
+};
+export const getCompodocJson = () => global.__STORYBOOK_COMPODOC_JSON__;
+export const checkValidComponentOrDirective = (component) => {
+    if (!component.name) {
+        throw new Error(`Invalid component ${JSON.stringify(component)}`);
+    }
+};
+export const checkValidCompodocJson = (compodocJson) => {
+    if (!compodocJson || !compodocJson.components) {
+        throw new Error('Invalid compodoc JSON');
+    }
+};
+const hasDecorator = (item, decoratorName) => item.decorators && item.decorators.find((x) => x.name === decoratorName);
+const mapPropertyToSection = (item) => {
+    if (hasDecorator(item, 'ViewChild')) {
+        return 'view child';
+    }
+    if (hasDecorator(item, 'ViewChildren')) {
+        return 'view children';
+    }
+    if (hasDecorator(item, 'ContentChild')) {
+        return 'content child';
+    }
+    if (hasDecorator(item, 'ContentChildren')) {
+        return 'content children';
+    }
+    return 'properties';
+};
+const mapItemToSection = (key, item) => {
+    switch (key) {
+        case 'methods':
+        case 'methodsClass':
+            return 'methods';
+        case 'inputsClass':
+            return 'inputs';
+        case 'outputsClass':
+            return 'outputs';
+        case 'properties':
+        case 'propertiesClass':
+            if (isMethod(item)) {
+                throw new Error("Cannot be of type Method if key === 'propertiesClass'");
+            }
+            return mapPropertyToSection(item);
+        default:
+            throw new Error(`Unknown key: ${key}`);
+    }
+};
+export const findComponentByName = (name, compodocJson) => compodocJson.components.find((c) => c.name === name) ||
+    compodocJson.directives.find((c) => c.name === name) ||
+    compodocJson.pipes.find((c) => c.name === name) ||
+    compodocJson.injectables.find((c) => c.name === name) ||
+    compodocJson.classes.find((c) => c.name === name);
+const getComponentData = (component) => {
+    if (!component) {
+        return null;
+    }
+    checkValidComponentOrDirective(component);
+    const compodocJson = getCompodocJson();
+    if (!compodocJson) {
+        return null;
+    }
+    checkValidCompodocJson(compodocJson);
+    const { name } = component;
+    const metadata = findComponentByName(name, compodocJson);
+    if (!metadata) {
+        logger.warn(`Component not found in compodoc JSON: '${name}'`);
+    }
+    return metadata;
+};
+const displaySignature = (item) => {
+    const args = item.args.map((arg) => `${arg.name}${arg.optional ? '?' : ''}: ${arg.type}`);
+    return `(${args.join(', ')}) => ${item.returnType}`;
+};
+const extractTypeFromValue = (defaultValue) => {
+    const valueType = typeof defaultValue;
+    return defaultValue || valueType === 'number' || valueType === 'boolean' || valueType === 'string'
+        ? valueType
+        : null;
+};
+const extractEnumValues = (compodocType) => {
+    const compodocJson = getCompodocJson();
+    const enumType = compodocJson?.miscellaneous?.enumerations?.find((x) => x.name === compodocType);
+    if (enumType?.childs.every((x) => x.value)) {
+        return enumType.childs.map((x) => x.value);
+    }
+    if (typeof compodocType !== 'string' || compodocType.indexOf('|') === -1) {
+        return null;
+    }
+    try {
+        return compodocType.split('|').map((value) => JSON.parse(value));
+    }
+    catch (e) {
+        return null;
+    }
+};
+export const extractType = (property, defaultValue) => {
+    const compodocType = property.type || extractTypeFromValue(defaultValue);
+    switch (compodocType) {
+        case 'string':
+        case 'boolean':
+        case 'number':
+            return { name: compodocType };
+        case undefined:
+        case null:
+            return { name: 'other', value: 'void' };
+        default: {
+            const resolvedType = resolveTypealias(compodocType);
+            const enumValues = extractEnumValues(resolvedType);
+            return enumValues
+                ? { name: 'enum', value: enumValues }
+                : { name: 'other', value: 'empty-enum' };
+        }
+    }
+};
+const castDefaultValue = (property, defaultValue) => {
+    const compodocType = property.type;
+    // All these checks are necessary as compodoc does not always set the type ie. @HostBinding have empty types.
+    // null and undefined also have 'any' type
+    if (['boolean', 'number', 'string', 'EventEmitter'].includes(compodocType)) {
+        switch (compodocType) {
+            case 'boolean':
+                return defaultValue === 'true';
+            case 'number':
+                return Number(defaultValue);
+            case 'EventEmitter':
+                return undefined;
+            default:
+                return defaultValue;
+        }
+    }
+    else {
+        switch (defaultValue) {
+            case 'true':
+                return true;
+            case 'false':
+                return false;
+            case 'null':
+                return null;
+            case 'undefined':
+                return undefined;
+            default:
+                return defaultValue;
+        }
+    }
+};
+const extractDefaultValueFromComments = (property, value) => {
+    let commentValue = value;
+    property.jsdoctags.forEach((tag) => {
+        if (['default', 'defaultvalue'].includes(tag.tagName.escapedText)) {
+            const dom = new global.DOMParser().parseFromString(tag.comment, 'text/html');
+            commentValue = dom.body.textContent;
+        }
+    });
+    return commentValue;
+};
+const extractDefaultValue = (property) => {
+    try {
+        let value = property.defaultValue?.replace(/^'(.*)'$/, '$1');
+        value = castDefaultValue(property, value);
+        if (value == null && property.jsdoctags?.length > 0) {
+            value = extractDefaultValueFromComments(property, value);
+        }
+        return value;
+    }
+    catch (err) {
+        logger.debug(`Error extracting ${property.name}: ${property.defaultValue}`);
+        return undefined;
+    }
+};
+const resolveTypealias = (compodocType) => {
+    const compodocJson = getCompodocJson();
+    const typeAlias = compodocJson?.miscellaneous?.typealiases?.find((x) => x.name === compodocType);
+    return typeAlias ? resolveTypealias(typeAlias.rawtype) : compodocType;
+};
+export const extractArgTypesFromData = (componentData) => {
+    const sectionToItems = {};
+    const compodocClasses = ['component', 'directive'].includes(componentData.type)
+        ? ['propertiesClass', 'methodsClass', 'inputsClass', 'outputsClass']
+        : ['properties', 'methods'];
+    compodocClasses.forEach((key) => {
+        const data = componentData[key] || [];
+        data.forEach((item) => {
+            const section = mapItemToSection(key, item);
+            const defaultValue = isMethod(item) ? undefined : extractDefaultValue(item);
+            const type = isMethod(item) || (section !== 'inputs' && section !== 'properties')
+                ? { name: 'other', value: 'void' }
+                : extractType(item, defaultValue);
+            const action = section === 'outputs' ? { action: item.name } : {};
+            const argType = {
+                name: item.name,
+                description: item.rawdescription || item.description,
+                type,
+                ...action,
+                table: {
+                    category: section,
+                    type: {
+                        summary: isMethod(item) ? displaySignature(item) : item.type,
+                        required: isMethod(item) ? false : !item.optional,
+                    },
+                    defaultValue: { summary: defaultValue },
+                },
+            };
+            if (!sectionToItems[section]) {
+                sectionToItems[section] = [];
+            }
+            sectionToItems[section].push(argType);
+        });
+    });
+    const SECTIONS = [
+        'properties',
+        'inputs',
+        'outputs',
+        'methods',
+        'view child',
+        'view children',
+        'content child',
+        'content children',
+    ];
+    const argTypes = {};
+    SECTIONS.forEach((section) => {
+        const items = sectionToItems[section];
+        if (items) {
+            items.forEach((argType) => {
+                argTypes[argType.name] = argType;
+            });
+        }
+    });
+    return argTypes;
+};
+export const extractArgTypes = (component) => {
+    const componentData = getComponentData(component);
+    return componentData && extractArgTypesFromData(componentData);
+};
+export const extractComponentDescription = (component) => {
+    const componentData = getComponentData(component);
+    return componentData && (componentData.rawdescription || componentData.description);
+};

package/dist/client/docs/compodoc.test.mjs

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest';
+import { extractType, setCompodocJson } from './compodoc';
+const makeProperty = (compodocType) => ({
+    type: compodocType,
+    name: 'dummy',
+    decorators: [],
+    optional: true,
+});
+const getDummyCompodocJson = () => {
+    return {
+        miscellaneous: {
+            typealiases: [
+                {
+                    name: 'EnumAlias',
+                    ctype: 'miscellaneous',
+                    subtype: 'typealias',
+                    rawtype: 'EnumNumeric',
+                    file: 'src/stories/component-with-enums/enums.component.ts',
+                    description: '',
+                    kind: 161,
+                },
+                {
+                    name: 'TypeAlias',
+                    ctype: 'miscellaneous',
+                    subtype: 'typealias',
+                    rawtype: '"Type Alias 1" | "Type Alias 2" | "Type Alias 3"',
+                    file: 'src/stories/component-with-enums/enums.component.ts',
+                    description: '',
+                    kind: 168,
+                },
+            ],
+            enumerations: [
+                {
+                    name: 'EnumNumeric',
+                    childs: [
+                        {
+                            name: 'FIRST',
+                        },
+                        {
+                            name: 'SECOND',
+                        },
+                        {
+                            name: 'THIRD',
+                        },
+                    ],
+                    ctype: 'miscellaneous',
+                    subtype: 'enum',
+                    description: '<p>Button Priority</p>\n',
+                    file: 'src/stories/component-with-enums/enums.component.ts',
+                },
+                {
+                    name: 'EnumNumericInitial',
+                    childs: [
+                        {
+                            name: 'UNO',
+                            value: '1',
+                        },
+                        {
+                            name: 'DOS',
+                        },
+                        {
+                            name: 'TRES',
+                        },
+                    ],
+                    ctype: 'miscellaneous',
+                    subtype: 'enum',
+                    description: '',
+                    file: 'src/stories/component-with-enums/enums.component.ts',
+                },
+                {
+                    name: 'EnumStringValues',
+                    childs: [
+                        {
+                            name: 'PRIMARY',
+                            value: 'PRIMARY',
+                        },
+                        {
+                            name: 'SECONDARY',
+                            value: 'SECONDARY',
+                        },
+                        {
+                            name: 'TERTIARY',
+                            value: 'TERTIARY',
+                        },
+                    ],
+                    ctype: 'miscellaneous',
+                    subtype: 'enum',
+                    description: '',
+                    file: 'src/stories/component-with-enums/enums.component.ts',
+                },
+            ],
+        },
+    };
+};
+describe('extractType', () => {
+    describe('with compodoc type', () => {
+        setCompodocJson(getDummyCompodocJson());
+        it.each([
+            ['string', { name: 'string' }],
+            ['boolean', { name: 'boolean' }],
+            ['number', { name: 'number' }],
+            // ['object', { name: 'object' }], // seems to be wrong | TODO: REVISIT
+            // ['foo', { name: 'other', value: 'empty-enum' }], // seems to be wrong | TODO: REVISIT
+            [null, { name: 'other', value: 'void' }],
+            [undefined, { name: 'other', value: 'void' }],
+            // ['T[]', { name: 'other', value: 'empty-enum' }], // seems to be wrong | TODO: REVISIT
+            ['[]', { name: 'other', value: 'empty-enum' }],
+            ['"primary" | "secondary"', { name: 'enum', value: ['primary', 'secondary'] }],
+            ['TypeAlias', { name: 'enum', value: ['Type Alias 1', 'Type Alias 2', 'Type Alias 3'] }],
+            // ['EnumNumeric', { name: 'other', value: 'empty-enum' }], // seems to be wrong | TODO: REVISIT
+            // ['EnumNumericInitial', { name: 'other', value: 'empty-enum' }], // seems to be wrong | TODO: REVISIT
+            ['EnumStringValues', { name: 'enum', value: ['PRIMARY', 'SECONDARY', 'TERTIARY'] }],
+        ])('%s', (compodocType, expected) => {
+            expect(extractType(makeProperty(compodocType), null)).toEqual(expected);
+        });
+    });
+    describe('without compodoc type', () => {
+        it.each([
+            ['string', { name: 'string' }],
+            ['', { name: 'string' }],
+            [false, { name: 'boolean' }],
+            [10, { name: 'number' }],
+            // [['abc'], { name: 'object' }], // seems to be wrong | TODO: REVISIT
+            // [{ foo: 1 }, { name: 'other', value: 'empty-enum' }], // seems to be wrong | TODO: REVISIT
+            [undefined, { name: 'other', value: 'void' }],
+        ])('%s', (defaultValue, expected) => {
+            expect(extractType(makeProperty(null), defaultValue)).toEqual(expected);
+        });
+    });
+});

package/dist/client/docs/config.mjs

@@ -0,0 +1,16 @@
+import { SourceType, enhanceArgTypes } from 'storybook/internal/docs-tools';
+import { extractArgTypes, extractComponentDescription } from './compodoc';
+import { sourceDecorator } from './sourceDecorator';
+export const parameters = {
+    docs: {
+        story: { inline: true },
+        extractArgTypes,
+        extractComponentDescription,
+        source: {
+            type: SourceType.DYNAMIC,
+            language: 'html',
+        },
+    },
+};
+export const decorators = [sourceDecorator];
+export const argTypesEnhancers = [enhanceArgTypes];

package/dist/client/docs/index.mjs

@@ -0,0 +1 @@
+export * from './compodoc';

package/dist/client/docs/sourceDecorator.mjs

@@ -0,0 +1,48 @@
+import { SourceType } from 'storybook/internal/docs-tools';
+import { useRef, emitTransformCode, useEffect } from 'storybook/preview-api';
+import { computesTemplateSourceFromComponent } from '../../renderer';
+export const skipSourceRender = (context) => {
+    const sourceParams = context?.parameters.docs?.source;
+    // always render if the user forces it
+    if (sourceParams?.type === SourceType.DYNAMIC) {
+        return false;
+    }
+    // never render if the user is forcing the block to render code, or
+    // if the user provides code
+    return sourceParams?.code || sourceParams?.type === SourceType.CODE;
+};
+/**
+ * Angular source decorator.
+ *
+ * @param storyFn Fn
+ * @param context StoryContext
+ */
+export const sourceDecorator = (storyFn, context) => {
+    const story = storyFn();
+    const source = useRef(undefined);
+    useEffect(() => {
+        if (skipSourceRender(context)) {
+            return;
+        }
+        const { props, userDefinedTemplate } = story;
+        const { component, argTypes, parameters } = context;
+        const template = parameters.docs?.source?.excludeDecorators
+            ? context.originalStoryFn(context.args, context).template
+            : story.template;
+        if (component && !userDefinedTemplate) {
+            const sourceFromComponent = computesTemplateSourceFromComponent(component, props, argTypes);
+            // We might have a story with a Directive or Service defined as the component
+            // In these cases there might exist a template, even if we aren't able to create source from component
+            const newSource = sourceFromComponent || template;
+            if (newSource && newSource !== source.current) {
+                emitTransformCode(newSource, context);
+                source.current = newSource;
+            }
+        }
+        else if (template && template !== source.current) {
+            emitTransformCode(template, context);
+            source.current = template;
+        }
+    });
+    return story;
+};

package/dist/client/docs/types.mjs

@@ -0,0 +1 @@
+export {};