feat(types): add type declarations to all @webref/* packages

[nberlette]

Closes #1900.

Overview

This PR contains just the type-related changes from the original draft PR #1901, applied to the latest commit on the main branch. In addition to new index.d.ts files, each package.json manifest has also been updated with a new types and exports fields.

Changes

• feat(types): add type declarations for @webref/css package
• feat(types): update @webref/css package manifest
• feat(types): add types to @webref/css6 package
• feat(types): add type declarations for @webref/elements package
• feat(types): add type declarations for @webref/events package
• feat(types): add type declarations for @webref/idl package

[nberlette]

Whoops! I accidentally forgot to trim the synchronous APIs from the type declarations - I'm patching them now and verifying the types accurately reflect what each package actually exposes to the runtime.

[Copilot]

Pull request overview

This PR introduces TypeScript declaration files and updates package manifests so @webref/* packages advertise their types and use an explicit exports entrypoint map.

Changes:

• Add index.d.ts type declarations for @webref/css, @webref/css (v6 line), @webref/elements, @webref/events, and @webref/idl.
• Update each package’s package.json to include types and an exports map (and add repository.directory metadata).

Reviewed changes

Copilot reviewed 5 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/css/package.json	Adds types + exports for @webref/css entrypoint
packages/css/index.d.ts	New TS declarations for CSS consolidated API
packages/css6/package.json	Adds types + exports for the v6 package line
packages/css6/index.d.ts	New TS declarations for CSS v6 extracts
packages/elements/package.json	Adds types + exports for @webref/elements
packages/elements/index.d.ts	New TS declarations for elements API
packages/events/package.json	Adds types + exports for @webref/events
packages/events/index.d.ts	New TS declarations for events API
packages/idl/package.json	Adds types + exports for @webref/idl
packages/idl/index.d.ts	New TS declarations for IDL API and WebIDL parse shapes

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Adds TypeScript declarations across the @webref/* packages to improve editor/TS support, and updates each package manifest to publish those typings (and introduce package exports maps).

Changes:

• Add index.d.ts declaration files for @webref/css, @webref/css6, @webref/elements, @webref/events, and @webref/idl
• Update each package’s package.json to include "types" and an "exports" map (plus repository.directory)
• Export ./css.json explicitly from @webref/css

Reviewed changes

Copilot reviewed 5 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/idl/package.json	Adds types + exports + repository.directory to publish typings and control entrypoints
packages/idl/index.d.ts	New TS declarations for listAll / parseAll and IDL file handles
packages/events/package.json	Adds types + exports + repository.directory
packages/events/index.d.ts	New TS declarations for events data returned by listAll()
packages/elements/package.json	Adds types + exports + repository.directory
packages/elements/index.d.ts	New TS declarations for elements data returned by listAll()
packages/css6/package.json	Adds types + exports + repository.directory
packages/css6/index.d.ts	New TS declarations for raw CSS v6 extracts returned by listAll()
packages/css/package.json	Adds types + exports + repository.directory, and exports ./css.json
packages/css/index.d.ts	New TS declarations for consolidated CSS APIs (listAll, index)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tidoust]

Thanks! One thing that's currently missing is a test for each package that makes sure that the data in the package actually aligns with these types.

Another thing that would seem useful to me would be to automate the creation of some of these types, leveraging the underlying JSON schemas in Reffy. The entry points are:

• Schema of the consolidated CSS file
• Schema of individual CSS extracts
• Schema of element extracts
• Schema of the consolidated events file
  (There is no schema for IDL since the extracts are raw text file)

There seem to be tools that can convert JSON schemas to TypeScript types, such as json-schema-to-typescript.

Note: the schema for the consolidated CSS file is incomplete in Reffy and allows additional keys. This exercise reveals that it would be useful to complete the schema and review new keys when they get introduced, be it only to trap typos such as "computed value".

FYI, we're going to drop support for the css6 package soon-ish, it may not be worth creating types for it.

[tidoust]

Ah, this reveals a bug in the extraction logic, which fails to turn that into computedValue. That seems to come from the SVG spec. I'll look into fixing that.

[nberlette]

Since you've fixed this, I'll go ahead and remove this field entirely

[tidoust]

No need to change anything, just noting that this one only seems to appear once in the data, in the definition of transform-style.

[nberlette]

@tidoust Thanks for the feedback! Those are all great suggestions.

I'll write unit tests today to ensure all of the types align correctly with the actual runtime data the packages contain. This should help with alerting maintainers of potential package drift in the future.

I can also automate the generation of the types themselves, but I'm not sure if I'll also be able to preserve all of the field-level documentation comments.. I'll look into it :)