Can I use composition API?

[ozum]

Hi,

Can I use vue-styleguidist with composition API?

Thanks,

[elevatebart]

Hi @ozum,

Great question. A short answer would be: No, but we want to.

With the new composition API, explicitly specified props are still valid and useful. Those will work with styleguidist today.
For now, nothing is parsed out of the setup function.

Do you have an example of what component you would like to parse and document?

[ozum]

@elevatebart, thanks for the answer. I know, it is too early to ask for composition API support, but great to hear it's on your roadmap.

Do you have an example of what component you would like to parse and document?

Currently not, I'm adopting to new API slowly, and trying to design a workflow for it.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 30 days if no further activity occurs. Thank you for your contributions.

[MechJosh0]

@elevatebart Do you have an example of what component you would like to parse and document?

I'm interested in vue-styleguidist working with Vue composition API. I have it working nicely with Storybook creating the documentation for me, but it's only picking up props and slots, not any properties provided in the setup method. Using Typescript I'm hoping it will be able to document as much as I write.

Here is a basic button component using composition API and Typescript.

<script lang="ts">
import { defineComponent, SetupContext } from "@vue/composition-api";

interface IProps {
	rounded: Boolean;
	disabled: Boolean;
	whiteText: Boolean;
}

export default defineComponent({
	props: {
		/**
		 * Rounded edges
		 */
		rounded: {
			type: Boolean,
			default: false,
		},
		/**
		 * Disabled button
		 */
		disabled: {
			type: Boolean,
			default: false,
		},
		/**
		 * Whether or not the text is white
		 */
		whiteText: {
			type: Boolean,
			default: false,
		},
	},
	setup(props: IProps, context: SetupContext) {
		/**
		 * My clicked event
		 */
		const clicked: (arg0: MouseEvent) => void = (e) => {
			context.emit("clicked", e);
		};

		return {
			clicked,
		};
	},
});
</script>

<template>
	<button :class="{ white: whiteText, rounded }" :disabled="disabled" @click="clicked">
		<!-- @slot The text shown inside the button -->
		<slot />
	</button>
</template>

<style lang="scss" scoped>
button.white {
	color: white;
}

button.rounded {
	border-radius: 10px;
}
</style>

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 30 days if no further activity occurs. Thank you for your contributions.

[elevatebart]

In this case vue-styleguidist detects all props but not the event.
I feel that it would be easy to detect it looking for context.emit.

[Mootook]

For the docgen-api, are there plans to more specifically parse the contents the setup() function if a component is using it?
My vue3 project components are mostly working with the composition api, and using jsdoc internally. It'd be nice if the docgen-api could extract that...i.e.

export default {
  name: 'LoadingSkeleon',
  props: {
    show: {
      type: Boolean,
      required: false,
      default: false
    }
  },
  setup (props, { emit}) {
    /**
     * Number of loading cards (skeletons) to show while fetching data
     * to populate component
     * @type {number}
     */
    const loadingCardsCount = 3
    return { loadingCardsCount }
  }
}

[elevatebart]

Hi @Mootook

What is the expected output in this case of vue-docgen-api for this component?
Do you expect loadingCardsCount to be part of the public API of your component?

I really am interested.

[Mootook]

@elevatebart To be a honest, I'm not quite sure. I don't have extensive experience with creating documented components, just jsdoc for productivity and intellisense purposes.
I would initially expect it to be considered data, but seeing as the api doesn't already expose the data () property of a vue component (assuming because it's private?), that solution may not be flush.

This question probably has bigger implications though for the vue3's usage of composable functions, which I don't have a clear thought on as I store all of my reusable state logic in 'src/composables'.

A component with a setup() then, for example:

setup(props) {
  const { isFetchingData, toggleIsFetchingData }  = useDataFetch()
  return { isFetchingData, toggleIsFetchingData }
}

I would expect to make some reference to its use of the data fetch composable. By storing the toggleIsFetchingData() in methods array, or grouping this stuff in a composables list.

[elevatebart]

+1 @Mootook
docgen only exposes whatever is public so no data or internals (that could change if refactoring).

The solution could be to render pure JSDoc/TSDoc alongside rendered components. We could have a list of exposed composable objects on the side that are rendered in the same website.

For now, though, the vue 3 version of styleguidist is in a pickle because of the use of JSX.

[Mootook]

@elevatebart I think keeping data private/internal is better but that may just be for my use case.

That solution seems nice, in my opinion.

Ah yea, I remember seeing an issue about that somewhere. Could you link the issue if you get a chance? I can't seem to find it or remember what repo it was opened in.

[Sociopacific]

In the case of using new syntax <script setup> vue-docgen-api doesn't work at all. Are there any solutions to this problem?

[elevatebart]

@RDMStreet could you make this claim a little more concrete?
I fail to see how "doesn't work at all" makes any sense.

This syntax should work naturally without changes:
https://github.com/vuejs/rfcs/blob/sfc-improvements/active-rfcs/0000-sfc-script-setup.md#declaring-props-or-additional-options

I know this proposal is still in flux.
vuejs/rfcs#229

If I start implementing it immediately, it may force the VueJs core team into bad decisions.

If you want things to go a little faster, please start working on a proposal for what the props extraction should look like. Maybe starting with this:
https://github.com/vuejs/rfcs/blob/sfc-improvements/active-rfcs/0000-sfc-script-setup.md#with-typescript

[elevatebart]

@Mootook the issue about JSX was open on vue-next : vuejs/core#1033

[dhruvkb]

@elevatebart the current implementation of script setup (https://github.com/vuejs/rfcs/blob/master/active-rfcs/0040-script-setup.md#declaring-props-and-emits) uses defineProps and defineEmits to define the props and events for a component. I'm writing props similar to this:

<script setup>
const props = defineProps({
  /**
   * the first prop for the component
   */
  propOne: {
	type: String,
    default: 'one'
  }
})

// ... code that uses `props`
</script>

It seems that vue-docgen-api cannot read the documentation comments associated with it. Is there a workaround or plans to support this?

[elevatebart]

There are plans to support this but time is a commodity that young/first fatherhood tends to rarify.
If you have time to look into how to implement it I would love to help you write a Pull Request.

[dhruvkb]

@elevatebart congratulations! I'd love to write a PR for this but the sheer complexity of the codebase is daunting. Nevertheless, I'll get on it soon and will definitely request for help if I'm stuck. Thanks for the amazing work you've done on this project.

[rafaelmagalhaes]

Any updates on this??

[messenjer]

The composition API is supported since version 4.44.0. We can document defineProps, defineEmits : https://vue-styleguidist.github.io/docs/Documenting.html#setup-syntax

[Juliiii]

Can support @vue/composition-api?

My code is like this.

<script>
import { defineComponent } from "@vue/composition-api";

const name = "MyButton";
const props = {
    text: {  type: String  },
  }

export default defineComponent({
  name,
  props,
  setup(props, { emit }) {
    return {
      btnClick: () => {
        emit("btnClick", this.text);
      },
    };
  },
});
</script>

Now, when i use vue-docgen-api, i can not get the name, props and event.

[elevatebart]

Hello @Juliiii ,

You are right!
This use case does not work because vue-docgen-api is a static analysis tool.
For speed reasons, It does not try to execute the code it sees, it only "looks" at the code and find patterns.

If you write the same code the way below, props and name will be recognized:

<script>
import { defineComponent } from "@vue/composition-api";

export default defineComponent({
  name: "MyButton",
  props: {
    text: {  type: String  },
  },
  setup(props, { emit }) {
    return {
      btnClick: () => {
        emit("btnClick", this.text);
      },
    };
  },
});
</script>

I hope this helps !

[Leo-Nicolle]

Hi there! Thanks for this great tool, I love it !
I just wanted to ask if there is a way to add my custom content when using setup scripts (Just like you would do above export default defineComponent in the regular syntax.)

[rlynjb]

@elevatebart Do you have an example of what component you would like to parse and document?

I'm interested in vue-styleguidist working with Vue composition API. I have it working nicely with Storybook creating the documentation for me, but it's only picking up props and slots, not any properties provided in the setup method. Using Typescript I'm hoping it will be able to document as much as I write.

Here is a basic button component using composition API and Typescript.

<script lang="ts">
import { defineComponent, SetupContext } from "@vue/composition-api";

interface IProps {
	rounded: Boolean;
	disabled: Boolean;
	whiteText: Boolean;
}

export default defineComponent({
	props: {
		/**
		 * Rounded edges
		 */
		rounded: {
			type: Boolean,
			default: false,
		},
		/**
		 * Disabled button
		 */
		disabled: {
			type: Boolean,
			default: false,
		},
		/**
		 * Whether or not the text is white
		 */
		whiteText: {
			type: Boolean,
			default: false,
		},
	},
	setup(props: IProps, context: SetupContext) {
		/**
		 * My clicked event
		 */
		const clicked: (arg0: MouseEvent) => void = (e) => {
			context.emit("clicked", e);
		};

		return {
			clicked,
		};
	},
});
</script>

<template>
	<button :class="{ white: whiteText, rounded }" :disabled="disabled" @click="clicked">
		<!-- @slot The text shown inside the button -->
		<slot />
	</button>
</template>

<style lang="scss" scoped>
button.white {
	color: white;
}

button.rounded {
	border-radius: 10px;
}
</style>

is there any update on this?

[Juliiii]

你好！我已经收到你的邮件，我会尽快回复你的~