Documentation

Generating Documentation

Props

To document component properties, add TSDoc comments using the /** ... */ format. In most use cases Sveld will automatically parse relevant information - including the property name, type, value, and your description.

/** Set the preferred search method. */
export let mode = 'fuzz';

The CssClasses class denotes properties that use Tailwind utility classes. Set this to aid IntelliSense features.

import type { CssClasses } from '$lib';

/** Provide classes to set vertical item spacing. */
export let spacing: CssClasses = 'space-y-1';

For advanced or custom types, you may need to specify this information. This can be accomplished using the @type tag with block-style comments. Specify the type in curly brackets immediately following the tag.

/**
 * Bind this to your form data, represents the "files" data from the input.
 * @type {FileList}
 */
export let files: FileList;

Ensure you document Context API getContext values to provide Intellisense for child components. However, we intentionally exclude these values from the Props table.

/** Provide classes to set the hover background color. */
export let hover: string = getContext('hover');

See the Accordion component for a reference using both parent and child components.

Slots

Slot documentation is handle via TSDoc block comments at the top of your script tag (by convention). Note that Sveld does not currently support descriptions for the default slot. Instead, we recommend you opt for a Usage tab example and instructions to illustrate the use of this slot.

// Slots
/**
 * @slot lead - Provide a leading element, such as an icon.
 * @slot content - Provide the alert message text.
 */

Events

Sveld will automatically document forwarded events. You should not attempt to document these! However, dispatched events may be documented similar to props - with a TSDocs comment applied directly above the dispatch() method. Provide the event response in curly brackets, followed by the event name, a dash, and then the event description.

/** @event {{ event: DragEvent }} dragover - When a file is dragged over. */
dispatch('dragover', event);

Using Documentation

Now that our components are ready, it's time to create the documentation page that displays all of the information derived by Sveld. We provide a boilerplate template in /src/routes/(inner)/template/+page.svelte. Copy this to the appropriate file route location and use our recommend naming convention (e.g. /routes/components/your-new-component/+page.svelte).

Documentation Tables

To populate each documentation table we'll need to import our Sveld documentation data. Follow the instructions below:

1. Create a duplicate of your component import statement, e.g. import Avatar from '$lib/components/Avatar/Avatar.svelte';
2. Rename the import reference using the convention: Avatar -> sveldAvatar.
3. Append the following URL parameters to the end of your import statement, e.g.: .../Accordion.svelte?raw&sveld.
4. Finally, pass the import reference to the DocShell settings like so: components: [{ sveld: sveldAvatar }]

DocShell Settings

We can provide settings to our DocShell component using const settings: DocsShellSettings. This allows you to populate all relevant settings on the page.

Below are existing documentation pages we recommend you reference:

• Buttons showcases how to document Tailwind Element classes.
• Accordion makes use of most Component settings utilizing Sveld.
• Paginator uses Dispatched Event documentation.

Examples

When showcasing examples of new features we typically handle this by one of two methods:

• Sandbox (e.g. App Shell) - which provide a dynamic and interactive example that can be adjusted live.
• Static (e.g. App Bar) - with multiple static examples displaying various configurations.

Dynamic examples are preferred, but remember the overall goal is to showcase how the feature operates.

Usage

In addition to examples, you should provide multiple use case demonstrations using the Preview component to help end developers understand how to make use of your new components and features.

Keyboard Interactions

Finally, don't forget to document relevant keyboard interactions for accessibility. Provide these to the DocShell settings.