carbon-design-system / sveld Goto Github PK

If we have the following component:

<script>
  /**
   * @type {string}
   */
  export let a;
</script>

it has a required prop a, but the generated prop types mark it as optional:

export interface ComponentProps {
  a?: string;
}

Is this inteded behaviour? I imagine it may be misleading for the users of typings to not know which props are required.

https://github.com/IBM/sveld/blob/main/src/writer/writer-ts-definitions.ts#L146

A more reliable approach would be to:

• obtain the folder path
• normalize it using path.normalize
• replace the starting portion

Example:

Entry point: src/nested/index.js
TS: types/Component.svelte

Great work on the plugin. Just wondering if webpack would be supported in the near future?

I get a parse error if one of my components contains sass/scss. Is there a way to have either sveld preprocess or just ignore the styles section?

Svelte supports component doc comments, however this documentation is not shown when sveld generated types are present. To fix this, I propose copying that documentation to the typescript class.

Example:

Button.svelte

<script>
  export let type = "button";
  export let primary = false;
</script>

<!-- @component A button component -->

<button {...$$restProps} {type} class:primary on:click>
  <slot>Click me</slot>
</button>

Generated Interface (diff from current state):

 import { SvelteComponentTyped } from "svelte";

 export interface ButtonProps extends svelte.JSX.HTMLAttributes<HTMLElementTagNameMap["button"]> {
   /**
    * @default "button"
    */
   type?: string;

   /**
    * @default false
    */
   primary?: boolean;
 }

+/** A button component */
 export default class Button extends SvelteComponentTyped<
   ButtonProps,
   { click: WindowEventMap["click"] },
   { default: {} }
 > {}

The current output looks like this.

export { default as Button } from "./components/Buttons/Button.svelte";
export { default as LinkButton } from "./components/Buttons/LinkButton.svelte";
export { default as JellyButton } from "./components/Buttons/JellyButton.svelte";
...

Is it possible to make it like this?

export { default as Button, ButtonProps } from "./components/Buttons/Button.svelte";
export { default as LinkButton, LinkButtonProps } from "./components/Buttons/LinkButton.svelte";
export { default as JellyButton, JellyButtonProps } from "./components/Buttons/JellyButton.svelte";

Or some other solution..

I want to be able to use sveld programmatically in Node.js.

The CLI doesn't fit my use case as I want to tap into the onAppend callback when generating the Markdown file.

I also don't want it to be coupled with Rollup only.

import sveld from "sveld";

sveld({
  glob: true,
  markdown: true,
  markdownOptions: {
    onAppend: (type, document, components) => {
      if (type === "h1")
        document.append(
          "quote",
          `${components.size} components exported from ${pkg.name}@${pkg.version}.`
        );
    },
  },
  json: true,
  jsonOptions: {
    outFile: "docs/src/COMPONENT_API.json",
  },
});

/**
* Provide a writable store to maintain list selection.
* @type { Writable<T> | Writable<T[]> }
* @default undefined
* 
*/
//@ts-ignore
export let selected: Writable<T> = getContext('selected'); 

This results in the following JSON coming through to us from site-plugin-sveld.

{
"name": "selected",
"kind": "let",
"isFunction": false,
"isFunctionDeclaration": false,
"constant": false,
"reactive": false
},

Removing the //@ts-ignore brings back the description.
It would be great if we could still get the @type emitted even if it's not used for creating the types. Obviously related to #49 though.

First of all, huge thanks for this library! 🎉 It's a joy to work with.

I'm running into an issue with global exports defined in <script context="module" /> blocks. The generated type annotation does not properly reflect the static export.

Say for example I have the following single component:

<!-- welcome.svelte -->
<script context="module">
  /**
   * Log something
   * @type {(message: string) => void}
   */
  export function log(message) {
    console.log(message);
  }
</script>

<script>
  /**
   * Welcome message
   * @type string
   */
  export let message = 'there';
</script>

<h1>Hi {message}</h1>

To generate type definitions with Sveld I'd add the following index.js file:

export { default, default as Welcome, log } from './welcome.svelte';

Say I publish this package as my-cool-welcome-svelte-component, then in another typescript-powered Svelte app I can import the component and log() as expected:

<script lang="ts">
  import Welcome, { log } from 'my-cool-welcome-svelte-component';
  log('something interesting');
</script>

<Welcome message="cool user" />

However, TS will error and say that log is not exported by my-cool-welcome-svelte-component. I am not a TypeScript expert, so please forgive if my thinking is incorrect, but the issue appears to be that log will be typed as a static class method rather than a normal export.

Currently the types/welcome.svelte.d.ts looks as follows:

/// <reference types="svelte" />
import { SvelteComponentTyped } from "svelte";

export interface WelcomeProps, {
  /**
   * Welcome message
   * @default 'there'
   */
  message: string;
}

export default class Welcome extends SvelteComponentTyped<
  WelcomeProps,
  { },
  { default: {} }
> {
  /**
   * Log something
   */
  log: (message: string) => void;
}

Is there an issue with my setup or is this a limitation of Sveld? If it's a limitation, do you guys by chance have an idea how one could still make log() appear as a normal export type log = (message: string) => void;?

As per docs :

sveld({
  input: "./src/index.js",
  glob: true,
  markdown: true,
  markdownOptions: {
    onAppend: (type, document, components) => {
      if (type === "h1")
        document.append("quote", `${components.size} components exported from ${pkg.name}@${pkg.version}.`);
    },
  },
  json: true,
  jsonOptions: {
    outFile: "docs/src/COMPONENT_API.json",
  },
});

But

  const dir = fs.lstatSync(input).isFile() ? path.dirname(input) : input;
  const entry = fs.readFileSync(input, "utf-8");

throws error as fs.readFileSync fails on a directory

I tried to implement something in carbon-components-svelte but on build it caused changes like this all over COMPONENT_API.json:

   "components": [
     {
       "moduleName": "Accordion",
-      "filePath": "src/Accordion/Accordion.svelte",
+      "filePath": "src\\Accordion\\Accordion.svelte",
       "props": [
         {
           "name": "align",

Because Windows 😑

Hi,
I try to make documentation for a function:

    /**
     * get Theme object
     * @param {string} status
     * @param {string} size
     * @param {string} disabled
     * @param {string} theme
     * @returns {object}
     */
    export function getTheme(status,size,disabled,theme) {

In Markdown and JSON I get the whole code from inside the function inside the markdown/JSON (value attribute) in "Prop" list.
How to avoid this?

Thank you!

I'm currently creating a component library using SvelteKit's package feature, and am interested in using sveld to automatically generate markdown tables for my component API docs. When attempting to initialize sveld as a vite plugin, the build fails stating that sveld is not a function.

While Vite does offer loose compatibility with rollup plugins, it seems that either I misconfigured something, or sveld uses a function specific to rollup only.

Hello,

how do I get more information about an event in Markdown/JSON?

    /**
     * Will be fired if value has been changed
     * @event change
     */
    function handleChange(e) {
        dispatch("change", {
            value: value //passing argument
        })
    }

I also tried: https://jsdoc.app/tags-event.html
/**

• Snowball event.
• @event snowball
• @type {object}
• @Property {boolean} isPacked - Indicates whether the snowball is tightly packed.
  */

But there is no description and detail is always empty.

Thank you!

Ref: carbon-design-system/carbon-components-svelte#1636 (comment)

Currently, the getSvelteEntry relies purely on package.json for the Svelte entry point. It will throw an error if the "svelte" field is absent in the root package.json.

The plugin that allows programmatic usage should allow the entry point to be specified.

E.g.,

sveld({
  entry: "src/index.js",
  glob: true,
  markdown: true,
  markdownOptions: {
    onAppend: (type, document, components) => {
      if (type === "h1")
        document.append(
          "quote",
          `${components.size} components exported from ${pkg.name}@${pkg.version}.`
        );
    },
  },
  json: true,
  jsonOptions: {
    outFile: "docs/src/COMPONENT_API.json",
  },
});

Hey, my name is Chris and I'm the project lead and core contributor to Skeleton:
https://skeleton.dev/

We're in the process of integrating Sveld to automatically document our various components in our library. Unfortunately we're running into a couple issues with the new @slot and @event description fields introduced here:

• https://github.com/carbon-design-system/sveld/releases/tag/v0.18.0

Here's how we're defining our JSDoc comments for a component. This includes 3x Slots and 1x forwarded Event:

Issue 1 - First Slot Always Dropped

NOTE we do not use the default slot on this particular component.

Per our JSDoc definitions above you'll see we're adding an empty @slot definition, which should come out to a total of 4x slots. But we've noted that regardless of how we structure or order the comments, the first @slot definition is always pruned. The only work around we've discovered is to insert an empty slot to be "sacrificed".

Issue 2 - @event changes types

We've applied a single on:click event to our template. This should be forwarded up. Here's what that looks like if we do not specify a JSDocs comment, just allow Sveld to auto-document it:

The above is correct, though missing the description obviously since one isn't specified.

However, when we do specify a description, we see two issues:

• The type information incorrectly changes from forwarded -> dispatched
• We lose the element value - though I believe this is due to the fact it's being treated as "dispatched"

FYI we're still testing, so we might update this post or create another if we discover other issues. However, these are the two most pressing we've encountered.

Hi everyone,

I'm still new to Svelte and typescript, and have been looking for the best way to type-check props objects I use to construct my components, as well as validate the props passed to my components.

I'm not sure if this is what Sveld does, and I don't know how to ask the right question as I'm still a beginner. What I'm hoping Sveld does is give me some single way to define an interface for data I would pass as component props that would also be used to validate my component props. I apologize if I don't understand the purpose of the project, I've taken a look at the carbon components usage of sveld and seen the generated types folder, but am still unsure of how things works as alot of internal functions are called. Are we supposed to include the types from the types folder and use that exported default class as an interface?

I'll describe my problem with Svelte in hopes that either Sveld is the solution I'm looking for, or someone can point me in the right direction :)

For example, if I had a Todo component, then I want to make sure that the 'text' prop passed to it is a string (this I have achieved using the prop-types library from React), but I also want to check that any Todo "items" I have saved in a list are of type Todo, which isn't possible using prop-types, I would need a typescript interface for this.

// App.svelte
let todos: TodoInterface[] = [ {'text': 'test'}]; // Need to statically type check data I pass as props
...
{#each todos as todo}
<Todo text={todo.text} />  // But also want to validate props at runtime
...

Now I have to define an interface, and then write the same type 'string' for prop-types to validate props passed to my component at runtime.

// Todo.svelte
const propTypes = {
      text: PropTypes.string.isRequired = ""
 };

  // Interface for Todo items
 export interface TodoInterface {
      text: string;
  }

PropTypes.checkPropTypes(propTypes, $$props, "prop", "Todo");

Would Sveld solve this issue? If not, is there a way to resolve it? All I'm trying to accomplish is write better code.
Again, I apologize if my misunderstanding of Sveld annoys anyone.

Thanks.

The export function myFunc() {} syntax is treated the same way as export let myFunc = () => {}, even though it shouldn't be. As mentioned in the Svelte docs, export function () {} makes it a read-only export that exposes that function to the parent component (to be used with bind:this). However, I have the following component:

<script>
  export function showSnackbar(options) {
    // some code
  }
</script>

<slot {showSnackbar} />

(irrelevant code removed - full component can be found here)
And this generates typings as if showSnackbar is a prop that accepts a function, and uses the full implementation code as the default value. .d.ts:

/// <reference types="svelte" />
import { SvelteComponentTyped } from "svelte";

export interface SnackbarContainerProps {
  /**
   * @default () => { const { component = Snackbar, props = {}, duration = 4000 } = options; const key = { component, props }; key.props.closeCallback = function close() { clearTimeout(key.timeoutID); removeSnackbar(key, true); }; key.timeoutID = setTimeout(removeSnackbar, duration, key, false); registeredSnackbars.add(key); registeredSnackbars = registeredSnackbars; return { close: key.props.closeCallback, expired: new Promise(resolve => (key.resolveExpiredPromise = resolve)), }; }
   */
  showSnackbar?: () => any;
}

export default class SnackbarContainer extends SvelteComponentTyped<
  SnackbarContainerProps,
  {},
  { default: { showSnackbar: () => any } }
> {}

I think this might be a Svelte limitation (as I don't see how can this be properly represented with SvelteComponentTyped), but even then maybe it's best to ignore function exports.

When parsing a Svelte component that imports paths with an alias (paths defined in tsconfig.json) such as $lib, Sveld cannot substitute the correct path.

Example:
Given an import path:
import ExampleComponent from '$lib/components/ExampleComponent.svelte';
results into error:

[Error: ENOENT: no such file or directory, open '/Users/xyz/Documents/example-project/src/lib/$lib/components/ExampleComponent.svelte']

QuickFix:
I added the following two lines to line 108 in sveld/lib/parse-export.js

node.source.value = node.source.value.replace('$lib/','')
console.log("-->parsing ImportDeclaration",node.source.value)

sveltejs/svelte#8512

With SvelteComponentTyped being depreciated, the types must instead use SvelteComponents

Hello. I have been trying to use sveld for my package but failed to do so, so I tried cloning this repo and running the multi-export example, but it did not work as expected.

Reproduction steps:

• Clone the repo
• cd sveld/integration/multi-export
• Run yarn install and yarn add sveld
• Run rm -r types and rm COMPONENT_* (to remove the existing generated types and generate them again)
• yarn build

Results:
It produces the component types in the root (multi-export) directory and the following index.d.ts in the types directory:

export { default as Button } from "./..Button";
export { default as Link } from "./..Link";
export { default as Quote } from "./..Quote";

Environment:

• Node v12.18.2
• Yarn v1.22.4
• Windows 10 (20H2 update, Build 19042)

If you re-export an imported component in context="module", it currently throws this error: Cannot read properties of null (reading 'type').

I do this in the Chart component of LayerChart to simplify accessing layercake's Svg and Html components (which LayerChart is built upon).

<script context="module" lang="ts">
  import { LayerCake, Svg, Html } from 'layercake';
  export { Svg, Html };
</script>

This can be tested on https://sveld.onrender.com/ with this snippet.

as a workaround, I found you can redeclare them:

<script context="module" lang="ts">
  import { LayerCake, Svg as _Svg, Html as _Html } from 'layercake';

  export const Svg = _Svg;
  export const Html = _Html;
</script>

Note: this used to work, but I recently worked on upgrading all my dependencies, and upgrading vite-plugin-sveld from 1.0.3 to 1.1.0, which bumped sveld from 0.8.3 to 0.18.0 (based on package-lock.json), is when the problem started.

Thanks for the awesome project btw.

Imagine you have a JS file which exports some enum:

export default Object.freeze({
  TOP_LEFT: 'top left',
  TOP_RIGHT: 'top right',
});

You want your prop to be one of the values from that enum, so you write the following in your Svelte component:

<script>
  import ThatEnum from 'path/to/enum';
  /**
   * @type {typeof import('path/to/enum').default}
   */
  export let position = ThatEnum.TOP_LEFT;
</script>

The generated typings lack the information on the default value of this prop:

export interface ComponentProps {
  position?: typeof import("path/to/enum").default;
}

Version 0.8.0 depends on TypeScript. typescript should be moved to the direct dependencies.

Currently, the name of a default slot is "__default__"; to avoid clashing, it should be null.

We have a component that returns props, using the spread syntax:

<slot {...returnProps} />

It fails to build with this error:

[!] (plugin plugin-sveld) TypeError: Cannot read property '0' of undefined
TypeError: Cannot read property '0' of undefined
    at /home/ghost/Desktop/polykit/node_modules/sveld/lib/ComponentParser.js:281:34

Have you considered (or tried) generating typed web components instead of Svelte components?
i.e. generating types that extend from regular HTMLAttributes not svelte.JSX.HTMLAttributes etc.

I just wanted to check to see if this was a route you'd explored before running into roadblocks.
(I'm not overly familiar with SvelteJS so you might be able to tell me this is a bad idea!)

Unfortunately the change to introduce a typed SvelteComponent was an accidental breaking change for people doing this: const foo: typeof SvelteComponent = SomeSpecificComponent because there was a type error now. Therefore the typing was reverted on SvelteComponent, the strongly typed component is instead exported through a new extendable class SvelteComponentTyped. This should become extends SvelteComponentTyped<...>.
Sorry for the inconvenience.

When creating a const String variable inside <script></script> which contains the string <style> (e.g. while injecting a css style into an iframe later on), I receive CompileError [ParseError]: <script> must have a closing tag as an error and sveld stops generating.

The code works fine under normal Svelte conditions. Wondering if another preprocessor must run before rollup-plugin.js:164

Example:

<script>
const css=`<style>
		body{ color: white; }
		a:link { color: #ccc; }
		ins { background: green; text-decoration: none; }
		del { background:red;text-decoration: none; }
</style>`
....
</script>

Output:

CompileError [ParseError]: <script> must have a closing tag
    at error (/Users/xyz/node_modules/sveld/node_modules/svelte/compiler.js:13213:20)
    at Parser$1.error (/Users/xyz/code/improve-carbon/node_modules/sveld/node_modules/svelte/compiler.js:13291:10)
    at Object.read_script [as read] (/Users/xyz/code/improve-carbon/node_modules/sveld/node_modules/svelte/compiler.js:9001:17)
    at tag (/Users/xyz/code//node_modules/sveld/node_modules/svelte/compiler.js:12237:34)
    at new Parser$1 (/Users/xyz/code/node_modules/sveld/node_modules/svelte/compiler.js:13250:22)
    at parse$b (/Users/xyz/code//node_modules/sveld/node_modules/svelte/compiler.js:13390:21)
    at compile (/Users/xyz/code/node_modules/sveld/node_modules/svelte/compiler.js:44085:18)
    at ComponentParser.parseSvelteComponent (/Users//code//node_modules/sveld/lib/ComponentParser.js:240:48)
    at /Users/xyz//node_modules/sveld/lib/rollup-plugin.js:164:112
    at step (/Users/xyz//node_modules/sveld/lib/rollup-plugin.js:67:23) {
  code: 'unclosed-script',
  start: { line: 35, column: 13, character: 1064 },
  end: { line: 35, column: 13, character: 1064 },
  pos: 1064,
  filename: undefined,
  frame: '33: \n' +
    "34:   if (themeValue === 'g90' || themeValue === 'g80' || themeValue === 'g100') { //dark mode\n" +
    '35:     const css="\n' +

Currently, installing sveld produced the following warning:

warning "sveld > [email protected]" has incorrect peer dependency "svelte@^3.23.0"

It would be wonderful if Sveld could generate proper typescript declarations for typescript components (ie: lang="ts), rather than only JS-annotated types.

In the documentation / README - it says -

TypeScript definitions are outputted to the types folder by default.

Is there a configuration parameter to configure to a different folder, (say dist / typings ) ?

Hi,

I am getting:

npx sveld --json --markdown The 'tag' option is used when generating a custom element. Did you forget the 'customElement: true' compile option? .[..]/node_modules/rollup/dist/shared/rollup.js:158

yes it is a custom element and it works fine and it is defined with "true" in rollup.

In the slot props, the values seem to be copied as they are instead of detecting their type. For example, I have the following snippet:

<script>
const selfControl = {
  toggle() {
    // implementation redacted for brevity
  },
};
</script>

<li>
  <slot name="handle" toggle={selfControl.toggle}>
    <Button on:click={selfControl.toggle}>{label}</Button>
  </slot>
</li>

The generated .d.ts file contains the following:

// Props definition excluded
  export default class AccordionSection extends SvelteComponentTyped<
      AccordionSectionProps,
      {},
      {default: {}
;
handle: { toggle: {selfControl.toggle} }
;}
    > {}

(The formatting gets messed up if there is any error in the generation)
It also prints this error in the console:

SyntaxError: Property or signature expected. (26:20)
  24 |       {default: {}
  25 | ;
> 26 | handle: { toggle: {selfControl.toggle} }
     |                    ^
  27 | ;}
  28 |     > {}

A similar thing happens when forwarding the slots. We make use of slot forwarding as can be seen in all of the slots of this component. The generated .d.ts file has the following:

// Props definition excluded
  export default class Autocomplete extends SvelteComponentTyped<
      AutocompleteProps,
      {change: WindowEventMap["change"];},
      {["loading-options"]: { slot: loading-options }
;
["more-options"]: { loadMoreOptions: any }
;
["not-enough-input"]: { slot: not-enough-input }
;
["too-many-options"]: { slot: too-many-options }
;}
    > {}

As expected, it prints the following error:

SyntaxError: ';' expected. (38:44)
  36 |       AutocompleteProps,
  37 |       {change: WindowEventMap["change"];},
> 38 |       {["loading-options"]: { slot: loading-options }
     |                                            ^
  39 | ;
  40 | ["more-options"]: { loadMoreOptions: any }
  41 | ;

In this case, slot is not even a prop that this slot accepts.

sveltejs/kit#6170

These files are also treated as svelte components.

Pushed a fix in #26

It would be handy if Sveld could grab any other present @tags in the JSDoc comment block and add them to the props exported per entity found. We would like to use things like @see to point to external docs and also use things like custom @Childof and @Parentof to help show relationships.

FYI we are using Sveld through vite-plugin-sveld on a svelte kit project and we don't see any extra tags come through when adding them (just in case the Sveld CLI behaves differently.

The following settings will not work

/** @type {string} */
let className = "";
export { className as class };

After some debugging, I found out that there seems to be a bug here:
https://github.com/IBM/sveld/blob/d54c27b31cb8eb7e6d6085b254eb09833f5b6b77/src/rollup-plugin.ts#L65
path.relative is used to relativize the import paths, but under Microsoft Windows, path.relative will use backslashes instead of slashes. This is undesired for import paths, which always uses slashes.
If needed, I can provide a test project, will take me a couple of hours to prepare though.
sveld version: 0.8.0

In the example svelte file Test.svelte with the contents:

<script>
    export const x = () => console.log('works')
</script>

it generates

  /// <reference types="svelte" />
  import { SvelteComponentTyped } from "svelte";
  
  
  
    export interface TestProps  {
      
    }
  

  export default class Test extends SvelteComponentTyped<
      TestProps,
      {},
      {}
    > {
      
    
    x: () => console.log('works');
    }
    ```

Would it be possible to introduce TypeScript generic type parameters support? TS recognizes @template tags from JSDoc annotations for type parameters, if that would be of any help.

From what I've tested, sveld would currently generate prop and slot typings with the type parameter(s) included, but because the exported class and interface do not have a type parameter list, it is invalid.

I am wondering if it's possible to annotate setContext calls such that the exposed variables are typed.

For example:

<!-- MyLogger.svelte -->
<script context="module">
  import { setContext } from 'svelte';
  /**
   * Log something
   * @type {(message: string) => void}
   */
  function log(message) {
    console.log(message);
  }

  setContext('my-logger', log);
</script>

My problem is that even though log has type annotations, when someone gets the function via getContext('my-logger') the type is unknown.

I wonder if there's a way to add type annotations to setContext.

Tooltip's tooltipBodyId does not appear in type definition.

The cause may be here:

export let ... style is not used.

When I use tooltipBodyId, error is reported by svelte language server in lang=ts.

It'll also issued by svelte-check.

Error: Type '{ open: boolean; tooltipBodyId: string; hideIcon: true; }' is not assignable to type 'IntrinsicAttributes & TooltipProps'.
  Property 'tooltipBodyId' does not exist on type 'IntrinsicAttributes & TooltipProps'. (ts)

<Tooltip {open} tooltipBodyId="tooltip-body" hideIcon>
  <p id="tooltip-body">Copied!</p>

Follow #70, it is now possible to generate type definition for exported module functions. E.g.:

<script context="module">
  /**
   * Log something
   * @type {(message: string) => void}
   */
  export function log(message) {
    console.log(message);
  }
</script>

is now turned into the following type definition:

/**
 * Log something
 */
export type log = (message: string) => void;

The problem is that this type definition will throw log only refers to a type, but is being used as a value here:

<script lang="ts">
  import { log } from 'my-component';

  function logNow() {
    log('Hi');
  }
</script>

The issue is that we actually want log() to be declared as a function:

declare function log(message: string): void;

Ideally, the JS doc string would look as follows but I assume this isn't supported yet (given the static () => any type):

<script context="module">
  /**
   * Log something
   * @function log
   * @param {string} message
   * @return {void}
   */
  export function log(message) {
    console.log(message);
  }
</script>

Is there any way sveld supports creating function declaration at the moment or would you be open to adding it?