Svelte: Ignore inherited HTMLAttributes docgen when using utility types

[steciuk]

Demo of a workaround for: #32171

What I did

As described in the issue, when a component's props are defined using a TypeScript utility type like Omit<HTMLAnchorAttributes, 'children'>, autodoc fails to identify these props as originating from svelte/elements. This causes the automatic documentation to be flooded with all inherited HTML attributes.

During some debugging, I found that for props derived from a utility type, the prop.valueDeclaration property is undefined and the existing check fails. However, it seems like the TypeScript compiler retains a link to the original type in prop.links.syntheticOrigin.valueDeclaration.

This PR shows how falling back to this deeper path skips doc generation for inherited props if prop.valueDeclaration is not present (at least for basic cases).

This is intended merely as a starting point for the discussion, as accessing internal-looking properties like links.syntheticOrigin with the mighty help of as any probably isn't the best idea. Just thought this may be helpful.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=<PR_NUMBER>

Summary by CodeRabbit

• Bug Fixes
  • Improves reliability of prop detection in documentation generation, ensuring built-in Svelte element props are correctly ignored in edge cases.

[yannbf]

Thanks for your PR! I'm tagging @JReinhold to take a look once he is available.

[storybook-pr-benchmarking]

Package Benchmarks

^{Commit: 21bc3d3, ran on 26 September 2025 at 08:28:55 UTC}

No significant changes detected, all good. 👏

[JReinhold]

This is interesting work and an interesting problem. It looks pretty harmless to me, I'm tempted to merge as is, as it doesn't seem like it would break anything.

I'm curious if @jasonlyu123 have any thoughts on this?

[coderabbitai]

Walkthrough

The docgen plugin’s prop-ignore logic now falls back to a syntheticOrigin valueDeclaration when valueDeclaration is missing, ensuring props originating from node_modules/svelte/elements.d.ts are still detected and skipped.

Changes

Cohort / File(s)	Summary
Docgen ignore fallback code/frameworks/svelte-vite/src/plugins/generateDocgen.ts	Extend prop origin check to use prop.valueDeclaration ?? prop.links.syntheticOrigin.valueDeclaration before resolving source file, preserving skip behavior for Svelte’s elements.d.ts props when declarations are synthetic/missing.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant P as Docgen Plugin
    participant T as TS Prop Node
    participant D as Declaration Resolver

    Note over P,T: Prop filtering during docgen

    P->>T: Read prop.valueDeclaration
    alt Declaration exists
        T-->>P: valueDeclaration
    else No direct declaration
        P->>T: Check links.syntheticOrigin.valueDeclaration
        T-->>P: syntheticOrigin.valueDeclaration (if present)
    end

    P->>D: Get source file for resolved declaration
    D-->>P: fileName

    alt fileName includes "node_modules/svelte/elements.d.ts"
        Note over P: Ignore prop
        P-->>P: Skip adding prop to docs
    else
        Note over P: Keep prop
        P-->>P: Include prop in docs
    end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• [Bug]: Svelte - Auto-docs includes all inherited HTMLAttributes when using utility types on svelte/elements #32171 — Adds fallback to links.syntheticOrigin.valueDeclaration to correctly ignore inherited HTMLAttributes from svelte/elements, matching the issue’s objective.

Poem

I twitch my whiskers, skim the lore,
Of props that sneak from Svelte’s core.
With gentle hop, I filter right—
Synthetic trails now in my sight.
Doc fields clean, my burrow bright. 🐇✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title accurately and concisely summarizes the primary change: ignoring inherited HTMLAttributes from svelte/elements when utility types are used in docgen, and it clearly relates to the changes described in the PR summary and objectives. It is specific, readable, and meaningful for reviewers scanning the repository history.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

code/frameworks/svelte-vite/src/plugins/generateDocgen.ts (1)

453-456: Prefer public API before TS internals

Before using the internal links.syntheticOrigin (unstable across TS versions), try prop.declarations?.[0] as a safer fallback.

Consider:

-          const __decl =
-            (prop.valueDeclaration ??
-              (prop as any)?.links?.syntheticOrigin?.valueDeclaration) as ts.Declaration | undefined;
+          const __decl =
+            (prop.valueDeclaration ??
+              prop.declarations?.[0] ??
+              (prop as any)?.links?.syntheticOrigin?.valueDeclaration) as ts.Declaration | undefined;

Please verify on TS versions you support (e.g., 5.4–5.6) to ensure behavior is consistent when props are created via utility types.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ff83d3d and c950bf9.

📒 Files selected for processing (1)

• code/frameworks/svelte-vite/src/plugins/generateDocgen.ts (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: normal
• GitHub Check: Core Unit Tests, windows-latest

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 21bc3d3

Command	Status	Duration	Result
nx run-many -t build --parallel=3	✅ Succeeded	48s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-09-26 08:43:32 UTC