Better documentation of available meta properties and how to use them

[kristianmandrup]

Double-Check

• Read the entire Kitbook docs.
• Check that there isn't already an issue that requests a similar feature.

Clear description of the requested feature

From looking through the docs it was unclear which _meta properties were available. Your video helped answer a lot of other questions, such as the ability to use the kit vite plugin for configuration, but again now clear what is available to configure tbh.

Ah, just found this in the docs: https://kitbook.vercel.app/docs/1-variants/DefaultSlot

But it's not clear how to write the variant code to create this "image". I again had to go to the kitbook code base to find DefaultSlot.variants.ts

export const Text: Variant<Component> = {
  _meta: {
    slot: 'Just a bit of plain text.',
  },
}
export const HTML: Variant<Component> = {
  _meta: {
    slot: 'Try some <i>italics</i>',
  },
}

Suggested solution

Digging through the codebase I found this very useful VariantMeta interface. Would be great to include it in the docs with the comments expanded as markdown text.

export interface VariantMeta {
  description?: string
  /** overrides Kitbook-wide viewports */
  viewports?: Viewport[]
  /** overrides Kitbook-wide language selection, pass an empty array to use just Kitbook's first language */
  languages?: Language[]
  /** contexts won't be HMRed as context must be set on component init which requires remounting the component */
  contexts?: MockedContext[]
  /** can pass in a string to be @html rendered or a Svelte Component for the default slot - you may find Compositions easier to work with than passing in a default slot but it's here. For named slots, use a Composition. */
  slot?: string | any
  /** don't hydrate variant on client by turning off scripts on iframe */
  csr?: false
  /** don't render on server by waiting until iframe is running client side to render variant  */
  ssr?: false
  tests?: {
    /** skips default snapshot test, but not additional tests */
    skip?: boolean
    /** each additional test will take viewports into account and run once per applicable viewport but will not take languages into account */
    additional?: Record<string, Test>
    /** When running Playwright screenshot tests, wait until there are no network operations for at least 500ms, discouraged except when needing to test hydrated views. Defaults to `false`. */
    clientSideRendered?: boolean
  }
}

I now found this "sort of documented" in the https://kitbook.vercel.app/docs/1-variants/refactor-variants page.

Alternative

No response

Additional context

No response

[jacob-8]

Glad to see you've been digging in! The reason I haven't thoroughly documented each item is that I haven't fully solidified my API, and intellisense gives good tips. I've been using Kitbook for a long time now, so you'd think I'd have figured it out, but I'm still discovering new use cases and trying to brainstorm the easiest way to implement them with the least boilerplate. For example, I used to have the props under a property called props and then I tried props root level to cut out a little boilerplate. While it was convenient, when it comes to adding any other config, it's kind of annoying to need to place it all under _meta. So through trial and error, I've realized it is a bad idea.

I also have a few other potential changes in the slow-cooker: notably alignment with the barebones of the Storybook CSF conventions (if they're not ditching regular CSF for Svelte CSF completely, see here); and Svelte 5 support.