vue-docgen-api: Doesn't understand or properly parse Proxy components

Current behavior

Take this file for example:

Simple.vue

<template>
    <div>
        <slot />
        <slot name="namedSlot" />
    </div>
</template>

<script>
export default {
    props: {
        color: {
            type: String,
            default: '#112233',
        },
        disabled: {
            type: Boolean,
            default: false,
        },
        size: {
            type: String,
            default: 'medium',
            validator: (size) => ['small', 'medium', 'large'].includes(size),
        }
    },
    methods: {
        emitEvents() {
            this.$emit('eventType1');
            this.$emit('eventType2', true);
            this.$emit('eventType3', 'string');
        },
    },
};
</script>

It’s parsed as such:

Simple.parsed.json

{
    "exportName": "default",
    "displayName": "Simple",
    "description": "",
    "tags": {},
    "props": [
        {
            "name": "color",
            "type": {
                "name": "string"
            },
            "defaultValue": {
                "func": false,
                "value": "'#112233'"
            }
        },
        {
            "name": "disabled",
            "type": {
                "name": "boolean"
            },
            "defaultValue": {
                "func": false,
                "value": "false"
            }
        },
        {
            "name": "size",
            "type": {
                "name": "string"
            },
            "defaultValue": {
                "func": false,
                "value": "'medium'"
            },
            "values": [
                "small",
                "medium",
                "large"
            ]
        }
    ],
    "events": [
        {
            "name": "eventType1"
        },
        {
            "name": "eventType2",
            "type": {
                "names": [
                    "undefined"
                ]
            }
        },
        {
            "name": "eventType3",
            "type": {
                "names": [
                    "undefined"
                ]
            }
        }
    ],
    "slots": [
        {
            "name": "default"
        },
        {
            "name": "namedSlot"
        }
    ]
}

However if we have a component that does nothing other than proxying its attributes, props, and listeners to a child component:

SimpleProxy.vue

<template>
    <simple v-bind="$attrs" v-on="$listeners">
        <template
            v-for="(_, slot) of $slots"
            #[slot]
        >
            <slot :name="slot" />
        </template>
    </simple>
</template>

<script>
import Simple from 'Simple.vue';

export default {
    inheritAttrs: false,

    components: {
        Simple,
    },
};
</script>

Then it’s parsed as such:

SimpleProxy.parsed.json

{
    "exportName": "default",
    "displayName": "SimpleProxy",
    "description": "",
    "tags": {},
    "slots": [
        {
            "name": "default",
            "scoped": true,
            "bindings": [
                {
                    "name": "name",
                    "title": "binding"
                }
            ]
        }
    ]
}

I would expect Simple.vue and SimpleProxy.vue to have the exact same parsed output, at least in terms of documenting the valid attributes, props, and events.

To reproduce

Reproduction Repo: vue-docgen-bugs

Expected behavior

I would expect Simple.vue and SimpleProxy.vue to have the exact same parsed output, at least in terms of documenting the valid attributes, props, and events.

[pretzelhammer]

1. analyze the template to find the usage of $attrs (for props) and $events (for events)

I just updated my original comment to include proxying slots, so it would be a little bit more complicated than this, but the remaining steps sound fine.

Would you be interested in trying to implement these changes yourself?

I currently have a workaround in my codebase, I explicitly annotate which child components get proxied in the JSDoc of the parent component, e.g.

<script>
import Simple from './Simple.vue';

/**
* @proxyProps ./Simple.vue
* @proxyEvents ./Simple.vue
* @proxySlots ./Simple.vue
*/
export default {
    name: 'ProxySimple',
    components: {
        Simple,
    },
};
</script>

I use the annotations to grab, parse, and merge the results of the child component with the parent component. Since my workaround currently suits my needs I don’t have extra time to implement this feature directly into vue-docgen-api, but it would still be nice if it existed by default in the library.

[thomasaull]

Hey @elevatebart,

I’m quite short on time aswell at the moment, so probably not anytime soon I’m afraid… Don’t feel pressured though. I think it’s good this issue is open again, so maybe other people become aware of it 😃