Clarify paths with respect to package.json exports

[justinfagnani]

Paths in manifests are meant to be fully resolvable by tools. Without package exports tools can just look up files relative to the package root. But with package exports there are two complications:

1. Paths should be resolved via the package exports, as opposed to the filesystem.
2. Types stop having their own paths with TypeScript's export support. Instead they have a "types" export condition on the .js path they're associated with. This means a reference to a type needs to use the .js path and either needs to include the "types" condition, or tool needs assume it.

See also #59 and #96

[maxpatiiuk]

Same question. There are many different "paths" for a file:

1. The .ts path
2. The .d.ts output path in dist/
3. The .js output path in dist/ (may be different)
4. The runtime import path (may be different per "exports"). May even be different depending on export condition
5. A file might document public APIs but not be directly importable (not included in "exports"). Does such file not have a "path" at all? Or such APIs might be importable from a barrel file elsewhere.
6. The path of the file in the UI (the table of contents, the api-reference URL) - partially covered by the "demos" field.

The .ts path is not valuable to the outside users if the code is not open source. Yet, it is valuable for internal checker tools (I wrote scanners that detect common public API mistakes - those need to know the source code path).
The .d.ts path and .js path is probably not valuable either - most people should be interested in the runtime import path. This should use the default export condition?
If a file A is not directly importable because of "exports", but is re-exported in a module B which is importable, should the "exports" array be empty for the file A? And then file B would have 0 "declarations", but list A's "exports"?

[maxpatiiuk]

Same question for the TypeReference.module field in the spec:

custom-elements-manifest/schema.d.ts

Line 182 in d2f79f0

module?: string;

It gets really tricky with "exports"

If my web component uses a type imported from an external library, getting the correct import path is tricky.
For example:

// my-component.ts
import { createEvent } from "my-lib";
class MyComponent extends LitElement {
  myEvent = createEvent();
}

// my-lib/dist/index.d.ts
export { createEvent, type EventEmitter } from "./events.js";

// my-lib/dist/events.d.ts
type EventEmitter<T> = ...;
declare function createEvent<T>(...): EventEmitter<T>;

The type of MyComponent.myEvent is EventEmitter. You can find that out using TypeScript's type checker:

const eventEmitterType = checker.getTypeAtLocation(myEventProperty);

Yet, that tells you nothing about where such type can be imported from.
eventEmitterType.aliasSymbol.declarations[0].getSourceFile().fileName will print the absolute path to my-lib/dist/events.d.ts - not portable, and not "exports" compliant.

The fact that my-lib/dist/events.d.ts is not directly importable because of the "exports" map, and that its exports are re-exported in the my-lib/dist/index.d.ts barrel file is not captured in any TypeScript's public API.

TypeScript inserts correct import path in its emitted .d.ts, but the logic for that is behind private APIs that are called by program.emit().

My solution for now is to hardcode the resolution for common libs, encourage teams to refactor out barrel files, and fallback to ReturnType<typeof createEvent> instead of inlining the return type (looks ugly in the docs, but at least it type checks). For types were fallback is not possible, I emit a build error (fortunately, rare cases)