sveld 0.35.0 → 0.35.1

package/README.md

@@ -132,6 +132,7 @@ export default class Button extends SvelteComponentTyped<
   - [CLI](#cli)
   - [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check)
   - [Node.js](#nodejs)
+  - [Browser](#browser)
   - [Config File](#config-file)
   - [Publishing to NPM](#publishing-to-npm)
 - [Available Options](#available-options)
@@ -568,6 +569,51 @@ sveld({
 });
 ```
 
+### Browser
+
+`sveld/browser` is a Node-free subpath export for running `sveld` client-side — e.g. an in-browser Svelte playground or REPL that parses whatever `.svelte` source the user typed and renders docs for it live. It bundles with Vite, esbuild, webpack, or Rollup without a `node:fs`/`node:path` polyfill.
+
+It covers parsing one component's source and rendering that result to any output format `sveld` supports (JSON, Markdown, `.d.ts`, Custom Elements Manifest). It does not cover project-wide glob scanning, the config file, or the CLI/Vite plugin (`sveld()`/`pluginSveld()`) — those walk the filesystem and only make sense in Node. Use the main `sveld` entry point for those.
+
+```ts
+import {
+  asNormalizedPath,
+  ComponentParser,
+  buildComponentApiDocument,
+  writeMarkdownCore,
+  writeTsDefinition,
+  buildCustomElementsManifest,
+} from "sveld/browser";
+
+const parser = new ComponentParser();
+const moduleName = "Button";
+const filePath = "Button.svelte";
+const parsed = parser.parseSvelteComponent(source, { moduleName, filePath });
+
+// `parseSvelteComponent` returns component metadata only; add `moduleName`
+// and `filePath` yourself to match the `ComponentDocApi` shape the writers expect.
+const component = { ...parsed, moduleName, filePath: asNormalizedPath(filePath) };
+const components = new Map([[moduleName, component]]);
+
+// JSON
+const jsonDoc = buildComponentApiDocument(components);
+
+// Markdown
+const markdown = writeMarkdownCore(components);
+
+// TypeScript definitions (per component)
+const dts = writeTsDefinition(jsonDoc.components[0]);
+
+// Custom Elements Manifest
+const cem = buildCustomElementsManifest(components, {
+  resolveModulePath: (component) => component.filePath,
+});
+```
+
+`ComponentParser` is stateful but reusable across parses — call `parseSvelteComponent` again on the same instance for the next component instead of constructing a new one each time.
+
+See [`playground/`](playground) in this repo for a working example: it parses Svelte source typed into an editor and renders JSON, Markdown, TypeScript, and Custom Elements Manifest tabs, all client-side.
+
 ### Config File
 
 Put a `sveld.config.js`, `sveld.config.mjs`, or `sveld.config.ts` at your project root to set defaults for the CLI and the programmatic `sveld()` API.

package/lib/ComponentParser.d.ts

@@ -52,6 +52,16 @@ export type ModernRunesTypeNode = {
     typeName?: unknown;
     types?: ModernRunesTypeNode[];
     members?: ModernRunesTypeMember[];
+    /** Declaration-side `<T, U = Default>` (interfaces/type aliases). */
+    typeParameters?: {
+        params?: Array<{
+            name?: string;
+        }>;
+    };
+    /** Reference-side `<string, number>` concrete arguments (`TSTypeReference`). */
+    typeArguments?: {
+        params?: ModernRunesTypeNode[];
+    };
 };
 export type ModernRunesTypeMember = {
     type?: string;
@@ -82,6 +92,13 @@ export interface ParsedComponentTypeScriptMetadata {
     canonicalPropNames: string[];
     localTypeDeclarations: string[];
     typeImportStatements: string[];
+    /**
+     * Whether `canonicalPropsType` mentions one of the component's own
+     * `<script generics="...">` parameters (e.g. `Props<T>`). The semantic
+     * resolver has no binding for `T`, so `resolveTypes` must leave this
+     * component's props as their AST-derived text rather than expand them.
+     */
+    referencesComponentGenerics?: boolean;
 }
 export declare const PARSED_COMPONENT_TYPE_SCRIPT_METADATA: unique symbol;
 export declare function getParsedComponentTypeScriptMetadata(component: {
@@ -251,6 +268,17 @@ export interface SlotPropValue {
     replace: boolean;
 }
 export type SlotProps = Record<string, SlotPropValue>;
+/**
+ * Internal representation of {@link ComponentSlot} used while parsing.
+ *
+ * `slot_props` is either raw TS type text (from a JSDoc `@slot`/`@snippet` tag,
+ * used as-is) or a structured {@link SlotProps} map (from template parsing,
+ * formatted into TS type text once at the end of the parse). Keeping it
+ * structured until then avoids a JSON.stringify/JSON.parse round-trip per slot.
+ */
+export type InternalComponentSlot = Omit<ComponentSlot, "slot_props"> & {
+    slot_props?: string | SlotProps;
+};
 /**
  * Event that is forwarded from a child component or element.
  *

package/lib/ast-guards.d.ts

@@ -7,6 +7,10 @@ export declare function isMemberExpression(node: unknown): node is MemberExpress
 export declare function isObjectExpression(node: unknown): node is ObjectExpression;
 export declare function isCallExpression(node: unknown): node is CallExpression;
 export declare function isCallExpressionNamed(node: unknown, calleeName: string): node is CallExpression;
+/** Unwraps `expr as Type` / `expr satisfies Type`, returning the innermost expression. */
+export declare function unwrapTypeCastExpression(node: unknown): unknown;
+/** The type node from `expr as Type` / `expr satisfies Type`, if `node` is such a cast. */
+export declare function getTypeCastAnnotation(node: unknown): unknown;
 export declare function isNewExpression(node: unknown): node is NewExpression;
 export declare function isNewExpressionNamed(node: unknown, calleeName: string): node is NewExpression;
 export declare function isFunctionDeclaration(node: unknown): node is FunctionDeclaration;

package/lib/browser.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Browser-safe entry point.
+ *
+ * Everything exported here avoids Node built-ins (`node:fs`, `node:path`, ...),
+ * so it bundles for the browser (Vite, esbuild, webpack, Rollup) without a
+ * polyfill. It covers parsing a single component's source and rendering that
+ * result to JSON, Markdown, TypeScript definitions, or a Custom Elements
+ * Manifest — everything except the filesystem-driven project scanning
+ * (`sveld()`/`pluginSveld()`) and CLI, which only make sense in Node.
+ *
+ * @example
+ * ```ts
+ * import { asNormalizedPath, ComponentParser, buildComponentApiDocument } from "sveld/browser";
+ *
+ * const parser = new ComponentParser();
+ * const diagnostics = { moduleName: "Button", filePath: "Button.svelte" };
+ * const parsed = parser.parseSvelteComponent(source, diagnostics);
+ *
+ * // `parseSvelteComponent` returns component metadata only; add the fields
+ * // `ComponentDocApi` needs (`moduleName`, `filePath`) yourself.
+ * const component = {
+ *   ...parsed,
+ *   moduleName: diagnostics.moduleName,
+ *   filePath: asNormalizedPath(diagnostics.filePath),
+ * };
+ *
+ * const doc = buildComponentApiDocument(new Map([[component.moduleName, component]]));
+ * ```
+ */
+export { asNormalizedPath, type NormalizedPath } from "./brands";
+export { default as ComponentParser, type SerializedComponentEvent } from "./ComponentParser";
+export type { SveldDiagnostic, SveldDiagnosticKind } from "./diagnostics";
+export type { ComponentDocApi, ComponentDocs } from "./plugin";
+export { type BuildComponentApiDocumentOptions, buildComponentApiDocument, COMPONENT_API_SCHEMA_VERSION, type ComponentApiDocument, } from "./writer/document-model";
+export type { AppendType, MarkdownWriterBase, TocLine } from "./writer/MarkdownWriterBase";
+export { renderComponentsToMarkdown } from "./writer/markdown-render-utils";
+export { type BuildCustomElementsManifestOptions, buildCustomElementsManifest, type CemAttribute, type CemClassDeclaration, type CemClassField, type CemCustomElementExport, type CemEvent, type CemExport, type CemJavaScriptExport, type CemModule, type CemSlot, type CemType, type CustomElementsManifest, } from "./writer/writer-custom-elements-core";
+export { BrowserWriterMarkdown, type WriteMarkdownCoreOptions, writeMarkdownCore, } from "./writer/writer-markdown-core";
+export { formatTsProps, getContextDefs, getTypeDefs, type WriteTsDefinitionOptions, writeTsDefinition, } from "./writer/writer-ts-definitions-core";