Whenever we needed to import types from another file with JSDoc, we've been using this syntax with @typedef:

TypeScript 5.5 introduced support for a new @import keyword, which would allow us to rewrite that example as:

/**
 * @import { ColorTypes, PlainColorObject, TryColorOptions } from "./types.js";
 */

A comparison between the generated .d.ts outputs:

// Before (@typedef)
export type ColorTypes = import("./types.js").ColorTypes;
export type PlainColorObject = import("./types.js").PlainColorObject;
export type TryColorOptions = import("./types.js").TryColorOptions;
// After (@import)
import type { ColorTypes } from "./types.js";
import type { TryColorOptions } from "./types.js";
import type { PlainColorObject } from "./types.js";

Using this syntax has a few advantages. Namely:

1. It avoids polluting the exports of many files, since the @typedef syntax would actually re-export every imported type (as can be seen from the output above)
2. It is less verbose/easier to type than repeated @typedefs
3. It makes LSP functionality like "jump to definition" work properly. With @typedef, trying to jump to an imported type's definition would just go to the @typedef line, rather than the actual source

This change also shouldn't cause color.js to be incompatible with consumers' older TypeScript versions, since everything type-related in the package gets compiled to .d.ts anyway. We'd just need to upgrade color.js's TypeScript dependency from our current pinned v5.4.5 to v5.5.0 or later.

See: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html#the-jsdoc-import-tag