feat: component and prop suggestions from remote API

[adamdehaven]

The extension provides intelligent auto-completion for MDC components and their props when provided with a mdc.componentMetadataURL in your VS Code project's settings.

Completions

Component Names

When typing a colon (:) at the start of a line, it suggests available component names.

Component props

Within MDC component YAML frontmatter sections (between ---), it provides contextual property suggestions with proper types and documentation.

Configuration

Configure component suggestions by setting the mdc.componentMetadataURL in your VS Code settings.

The URL can be your deployed site, or even a locally running server.

This URL should return JSON data that matches the following interface:

interface MDCComponentData {
  /** The kebab-case name of the component */
  mdc_name: string
  /** Component description */
  description?: string
  /** Markdown-formatted documentation */
  documentation_markdown?: string
  /** URL to component documentation */
  docs_url?: string
  /** Component metadata from `@nuxtlabs/nuxt-component-meta` */
  component_meta: { ... }
}

/** The endpoint should return an array of data */
type MDCMetadataResponse = MDCComponentData[]

The extension caches component metadata for 6 hours and provides a command MDC: Refresh Component Metadata to manually update the cache.

To customize the cache TTL you may customize the value for mdc.componentMetadataCacheTTL in settings. Defaults to 360 minutes (6 hours).

---

Notes

1. I decided to wrap the native nuxt-component-meta in a top-level component_meta property to allow a custom endpoint to provide other contextual, top-level data for each component (e.g. description). This does require a bit of an opinionated interface; however, would be easy to spin up with a project already utilizing nuxt-component-meta (source).
2. This PR builds on top of feat(*): add document formatting and code folding providers #41 and can be used simultaneously, but I stripped those changes out from this PR so that it could also be edited or merged separately.
3. If the mdc.componentMetadataURL property is not provided in a project's .vscode/settings.json or globally, the extension will log but not error.

[adamdehaven]

@farnabaz I have a working version of this I can demo. Happy to chat on the interface as well

[farnabaz]

What if, instead of fetching from API, we check for the existence of .nuxt/component-meta.mjs file and read meta directly from this file

[adamdehaven]

I like the zero-config approach, but started a discussion here as to why I'm using an enhanced interface.

[farnabaz]

This looks great 🔥
I was thinking about the usability of this feature for all users, I like to unlock this feature with zero config if possible

If we read meta from .nuxt/component-meta.mjs we do not need the URL setup which will reduce the extra step.

And about the visual, what do you have in your mind?

[adamdehaven]

This looks great 🔥 I was thinking about the usability of this feature for all users, I like to unlock this feature with zero config if possible

If we read meta from .nuxt/component-meta.mjs we do not need the URL setup which will reduce the extra step.

I agree that zero config would be ideal; however, for my use-case, especially for the block components, I want to supplement the metadata with a description of the component, along with a docs link as you can see here:

Without providing this extra data, you can get component name completion, but there is no way to provide a "detail" or "description" of the component (the documentation_markdown property allows rendering any markdown). Is having this extra data worth the enhanced interface?

Since nuxt-component-meta doesn't allow for providing this extra data, it creates the need for the enhanced response interface.

Thoughts?

[farnabaz]

I see, how are you generating this documentation_markdown?

Maybe we could find a solution to define these docs inside components and extract them in nuxt-component-meta.

I don't mean to remote URL support, we can check the URL and as a fallback check the .nuxt/component-meta.mjs file.

Later we'll see how to extract and extract documentation from component files

[adamdehaven]

I see, how are you generating this documentation_markdown?

I have a cached event handler in my Nitro server that essentially grabs the list of available components from /api/component-meta and then loops through each one via map to add additional properties, and then injects the nuxt-component-meta into the top-level component_meta property of the response.

Maybe we could find a solution to define these docs inside components and extract them in nuxt-component-meta.

Originally I thought about using extendComponentMeta from here but we determined this wasn't production ready I believe?

I don't mean to remote URL support, we can check the URL and as a fallback check the .nuxt/component-meta.mjs file.

Yes, I think the default componentMetadataURL setting could be to read from the .nuxt/component-meta.mjs data; however, wouldn't we still need to fetch from a URL like http://localhost:3000/api/component-meta from the VS Code extension? I'm not sure it would have access directly to .nuxt/component-meta.mjs. Another issue with this approach is that the completions would only be available if your local server is running (I guess that's true for the remote URL as well?)

[adamdehaven]

@farnabaz if we merge #45, I'll want to refactor this PR to match the new reactive config updates.