@navecss/core 0.2.0 → 0.3.0

package/dist/vite.d.ts

@@ -0,0 +1,430 @@
+import { AtomName, AtomDefinition } from './atoms.js';
+
+/**
+ * The few shapes of Vite's (and Rollup's) own objects the plugin touches, declared here rather
+ * than imported: `@navecss/core/vite` takes no dependency and no peer, and a type import from
+ * `vite` would make the peer real for every consumer who type-checks it. Each interface is a
+ * structural subset of the real one, so Vite's own `Plugin` type accepts the plugin as it is.
+ */
+interface LoggerLike {
+    warn(message: string, options?: unknown): void;
+}
+interface ResolvedConfigLike {
+    readonly root: string;
+    readonly command: string;
+    /**
+     * The config object the host was handed, which every environment of one invocation shares.
+     */
+    readonly inlineConfig?: object;
+    readonly cacheDir?: string;
+    /**
+     * Set when the config asks for a builder, so one process builds every environment.
+     */
+    readonly builder?: unknown;
+    readonly css?: {
+        readonly devSourcemap?: boolean;
+        readonly transformer?: string;
+    };
+    readonly build?: {
+        readonly lib?: unknown;
+        readonly sourcemap?: unknown;
+    };
+    readonly logger: LoggerLike;
+    /**
+     * The plugins of the build, Vite's own among them.
+     */
+    readonly plugins?: readonly PluginLike[];
+}
+/**
+ * A plugin as another plugin finds it in an environment's list: by name, with a `transform` that
+ * is a function or Rolldown's `{ handler }` object.
+ */
+interface PluginLike {
+    readonly name: string;
+    readonly transform?: unknown;
+}
+/**
+ * A module of a dev server's module graph: its id and URL, the modules that import it and the
+ * ones it imports (static and dynamic alike).
+ */
+interface GraphModuleLike {
+    readonly id: string | null;
+    readonly url: string;
+    readonly importers: ReadonlySet<GraphModuleLike>;
+    readonly importedModules: ReadonlySet<GraphModuleLike>;
+}
+/**
+ * The builder `buildApp` is given: its environments by name, and whether each has been built.
+ */
+interface BuilderLike {
+    readonly environments: Readonly<Record<string, {
+        readonly isBuilt: boolean;
+    }>>;
+}
+/**
+ * The environment a hook runs for: a name, whether it renders for a browser or a server, and the
+ * plugins it runs.
+ */
+interface EnvironmentLike {
+    readonly name: string;
+    readonly config: {
+        readonly command?: string;
+        readonly consumer: string;
+        readonly inlineConfig?: object;
+        readonly root?: string;
+    };
+    readonly plugins: readonly PluginLike[];
+}
+/**
+ * A location in the shape Rollup reports one: 1-based line, 0-based column.
+ */
+interface LogLocation {
+    readonly file?: string;
+    readonly line: number;
+    readonly column: number;
+}
+interface PluginLog {
+    readonly message: string;
+    readonly id?: string;
+    readonly loc?: LogLocation;
+}
+interface IncomingSourceMap {
+    readonly sources: readonly string[];
+    readonly sourceRoot?: string | undefined;
+    readonly sourcesContent?: readonly (string | null)[] | undefined;
+    readonly names?: readonly string[] | undefined;
+    readonly mappings: string;
+}
+/**
+ * What the host tells a `transform` hook about the module besides its text.
+ */
+interface TransformMeta {
+    readonly moduleType?: string;
+}
+interface TransformContext {
+    error(error: PluginLog): never;
+    warn(warning: PluginLog): void;
+    addWatchFile(id: string): void;
+    getCombinedSourcemap(): IncomingSourceMap;
+    /**
+    The environment the module is being transformed for; `client` when a host gives none.
+     */
+    readonly environment?: EnvironmentLike;
+    /**
+     * The host's parse of `code`, an ESTree (read as an `AstNode`).
+     */
+    parse(code: string, options?: {
+        readonly lang?: 'dts' | 'js' | 'jsx' | 'ts' | 'tsx';
+    }): unknown;
+    /**
+     * Resolves `source` as imported from `importer`.
+     */
+    resolve?(source: string, importer: string): Promise<{
+        readonly id: string;
+    } | null>;
+    /**
+     * Loads, and so transforms, the module `options.id`.
+     */
+    load?(options: {
+        readonly id: string;
+    }): Promise<unknown>;
+}
+/**
+ * What the dev server hands `hotUpdate`: the file that changed.
+ */
+interface HotUpdateOptions {
+    readonly file: string;
+    /**
+     * The modules the changed file belongs to, which the update is about to reload.
+     */
+    readonly modules?: readonly GraphModuleLike[];
+}
+/**
+ * The environment `hotUpdate` runs in: its module graph, and the channel to its client.
+ */
+interface HotUpdateContext {
+    readonly environment: {
+        readonly config?: {
+            readonly command?: string;
+            readonly consumer?: string;
+            readonly inlineConfig?: object;
+        };
+        readonly hot: {
+            send(payload: {
+                type: 'full-reload';
+            }): void;
+        };
+        readonly moduleGraph: {
+            getModuleById(id: string): unknown;
+            invalidateModule(module: never): void;
+        };
+        readonly name: string;
+        transformRequest?(url: string): Promise<unknown>;
+    };
+}
+interface BundleContext {
+    error(error: PluginLog): never;
+    warn(warning: PluginLog | string): void;
+    readonly environment?: EnvironmentLike;
+}
+/**
+ * What the module graph holds about one module: its transformed text, and who imports it.
+ */
+interface ModuleInfoLike {
+    readonly code: string | null;
+    readonly importers: readonly string[];
+    readonly dynamicImporters: readonly string[];
+    /**
+     * The ids the module imports, statically and dynamically, externals included.
+     */
+    readonly importedIds?: readonly string[];
+    readonly dynamicallyImportedIds?: readonly string[];
+}
+/**
+ * What `renderChunk` and `buildEnd` are given: the environment, and the ways to fail or warn.
+ */
+interface RenderContext {
+    error(error: PluginLog | string): never;
+    warn(warning: PluginLog | string): void;
+    readonly environment: EnvironmentLike;
+    /**
+     * The ids of every module the environment's build loaded, externals included.
+     */
+    getModuleIds?(): IterableIterator<string>;
+    /**
+     * What the module graph holds about the module `id`, or `null` when it holds none.
+     */
+    getModuleInfo?(id: string): ModuleInfoLike | null;
+    /**
+     * Resolves `source` as imported from `importer`.
+     */
+    resolve?(source: string, importer?: string): Promise<{
+        readonly id: string;
+    } | null>;
+    /**
+     * The host's parse of `code`, an ESTree (read as an `AstNode`).
+     */
+    parse?(code: string): unknown;
+}
+interface RenderedChunk {
+    readonly modules: Readonly<Record<string, unknown>>;
+}
+interface BundleEntry {
+    readonly type: string;
+    readonly fileName: string;
+    readonly source?: string | Uint8Array;
+}
+interface TransformResultLike {
+    readonly code: string;
+    readonly map: string;
+}
+
+/**
+ * The options that choose which atoms the Vite plugin ships, and their validation. A value a
+ * type would refuse in TypeScript is refused here too, so a JavaScript config gets the same
+ * answer; every text opens `navePlugin(): `, the prefix of the plugin's config-level messages.
+ */
+
+interface UsedAtomOptions {
+    /**
+     * Which atoms the build ships. `'used'` (the default): the atoms your `cx()` calls and your
+     * written Nave classes name, plus those in `keep` and `keepFor`. Under the default the build
+     * filters the atomic layer of every stylesheet it can reach, and the dev server serves the same
+     * set as far as it has read; a stylesheet imported with `?inline` or `?raw` ships every atom
+     * with a warning; a `cx()` call whose atoms the build cannot read fails the build, and is an
+     * error in the dev server.
+     * `'all'`: every atom, and no `cx()` call is read, as with the PostCSS plugin.
+     */
+    atomic?: 'all' | 'used';
+    /**
+     * Atoms always shipped, whether or not the build reads a use of them: every atom your own
+     * `cx.dynamic()` calls can take, and the atom of each Nave class written where the build cannot
+     * read it, such as in a server template or in CMS text.
+     */
+    keep?: readonly AtomName[];
+    /**
+     * By package name: the atoms a dependency's own `cx()` calls can produce, for a package whose
+     * calls the build cannot read. They ship as if they were in `keep`, beside the atoms of the
+     * package's calls the build does read. The calls it cannot read are not changed, so any other
+     * atom they apply has no rule unless the build ships it for another reason. An empty list is
+     * accepted: it says those calls produce no atom, so the list adds none, and a `cx.dynamic()` call
+     * in the package still fails the build, as it does with no entry. A package in your own workspace
+     * is your code, not a dependency. The entry stands in for the package's own calls only: a
+     * re-export of `cx` in the package that the build reads and a module of yours takes (imports,
+     * re-exports or reads off a namespace, directly or through re-exports of it that the build reads,
+     * as `export ... from` or an import exported unchanged, in this package or another) still fails
+     * the build, because the calls your module makes through it would ship with no rule, and the
+     * message says how to clear it. Listing here a package that only re-exports it does not clear a
+     * take of yours, since a re-export is not a call. A server build that leaves the package external
+     * does not read it, so a take only your server code makes is judged by what the client build
+     * read: it fails the build as above when the client build read the re-export it takes and the
+     * build can read the take, and gets a warning naming `ssr.noExternal` when the build cannot tell,
+     * because no environment read the file the server loads, or your file reaches the package in a
+     * way the build cannot read as a take (a `require()`, say, or a `#` import); with separate client
+     * and server commands, the next client command judges what the last build of each server recorded
+     * of server files that still exist.
+     */
+    keepFor?: Readonly<Record<string, readonly AtomName[]>>;
+    /**
+     * Modules that re-export `cx` from `@navecss/core/cx` unchanged, as
+     * `export { cx } from '@navecss/core/cx'`, in your code or in a dependency: a file that imports
+     * `cx` from one is read as if it imported it from `@navecss/core/cx`. The build follows a listed
+     * module one step. A relative entry (`'./src/ui/index.ts'`) is a path from Vite's `root`. A
+     * package name or subpath, an alias or an absolute path matches an import written the same way.
+     * A `#` entry matches an import written the same way only where that import resolves to a listed
+     * file, since a `#` import resolves through the `package.json` nearest the file that writes it.
+     * Every entry also matches an import that resolves to its file through a specifier naming that
+     * file or, for an `index` file, its directory; in your code, an import that reaches the file
+     * through any other specifier fails the build instead. A relative entry that resolves to no file
+     * is ignored, and so is an entry naming `@navecss/core/cx`, which the build always reads. The
+     * same setting, with the same entries, as `@navecss/eslint-plugin`'s `cxModules`, which reads a
+     * relative entry from the working directory instead of Vite's `root`.
+     */
+    cxModules?: readonly string[];
+}
+
+interface HtmlHook {
+    readonly order: 'pre';
+    handler(html: string, context: {
+        readonly filename?: string;
+    }): undefined;
+}
+interface NaveCollectPlugin {
+    readonly name: 'nave:collect';
+    readonly enforce: 'post';
+    transform(this: TransformContext, code: string, id: string, meta?: TransformMeta): Promise<undefined>;
+    readonly transformIndexHtml: HtmlHook;
+    buildStart(this: RenderContext): Promise<void>;
+    buildEnd(this: RenderContext, error?: unknown): Promise<void>;
+}
+
+/**
+ * A module worker is bundled by a build of its own, which runs the plugins of `worker.plugins`
+ * and none of the build's. The code it ships is code the build reads, so the plugin adds this one:
+ * it reads each module of that build as a module of the client environment, into the state the
+ * build's own plugins share, and reports nothing itself (its problems are reported once, with
+ * the rest, when the build ends), except that a worker's import of `cx` through an alias fails
+ * its own build, since no later step sees the worker's module graph.
+ */
+
+interface NaveWorkerPlugin {
+    readonly name: 'nave:collect-worker';
+    readonly enforce: 'post';
+    transform(this: TransformContext, code: string, id: string, meta?: TransformMeta): Promise<undefined>;
+    buildEnd(this: RenderContext, error?: unknown): Promise<void>;
+}
+
+/**
+ * The config the plugin adds under the default. `cx.dynamic()` resolves through the map of the
+ * atoms in `keep` and every `keepFor` list, handed to it as a `define` constant: static data,
+ * folded into the bundle in a build, and in dev the same map behind the console texts. And
+ * `@navecss/core` is bundled into every server environment, so that constant folds into a server
+ * build's `cx.dynamic()` too, and it is left out of the dev server's prebundling, so a
+ * prebundled dependency keeps its import of `cx` and the plugin reads the calls it makes.
+ */
+
+interface UsedConfig {
+    readonly define: Record<string, string>;
+    /**
+     * The dev server serves `@navecss/core` as its own modules, not one prebundled chunk.
+     */
+    readonly optimizeDeps: {
+        readonly exclude: string[];
+    };
+    /**
+     * A module worker is bundled by a build of its own: this adds the plugin that reads its code.
+     */
+    readonly worker: {
+        readonly plugins: () => NaveWorkerPlugin[];
+    };
+}
+
+/**
+ * Nave Vite plugin: expands `@nave` directives in every stylesheet Vite compiles, fails the build
+ * when one survives into its CSS output, and by default filters the atomic layer of every stylesheet it can reach down to the atoms the build reads a use for.
+ *
+ * Setup:
+ *   import { navePlugin } from '@navecss/core/vite'
+ *   export default { plugins: [navePlugin()] }               // Nave atoms only, fails on a problem
+ *   navePlugin({ extend: myAtoms })                          // Nave + consumer atoms
+ *   navePlugin({ extend: './my-atoms.mjs' })                 // the same, from a module Vite watches
+ *   navePlugin({ onUnknown: 'warn' })                        // report a problem and skip it
+ *   navePlugin({ keep: ['grid'] })                           // atoms a cx.dynamic() call can take
+ *   navePlugin({ cxModules: ['./src/ui/index.ts'] })         // modules that re-export cx
+ *   navePlugin({ atomic: 'all' })                            // ship every atom, read no cx() call
+ *
+ * `navePlugin()` returns two plain Vite plugin objects with no dependency and no peer, in an array
+ * that `plugins` takes as one entry. The first runs in Vite's normal order, after Vite's own CSS
+ * step, so a stylesheet reached through `@import`, a Sass or Less file, a CSS Module, and a Vue
+ * or Svelte style block are all read as the CSS they compile to. It never runs before Vite's CSS
+ * step: that order misses `@import`-reached files and breaks Sass `@mixin`. The second runs in
+ * post order and reads the JavaScript. Neither adds runtime machinery to the browser bundle.
+ */
+
+interface NaveViteOptions extends UsedAtomOptions {
+    /**
+     * Consumer-defined atoms merged with Nave built-in atoms. Consumer atoms win on name collision.
+     * These atoms resolve via @nave only. No global class. Not available in cx().
+     *
+     * A string is a path to a module instead, resolved against Vite's project root, whose default
+     * export is the atom map. The module is loaded again whenever its bytes change and Vite watches
+     * it, so editing it re-runs the stylesheets that use it with no restart. An atom object written
+     * inline here is not a file Vite can watch.
+     */
+    extend?: Record<string, AtomDefinition> | string;
+    /**
+     * Behaviour on a problem in a @nave directive: an unknown atom name, no atom named at all,
+     * anything but a name between the names (a comma, a string), a {} block, or a place the
+     * directive cannot expand. Under 'error', every such problem in one stylesheet is reported in
+     * one error.
+     * 'warn'  — log and skip
+     * 'error' — fail the build (default)
+     * 'ignore' — silently skip
+     */
+    onUnknown?: 'warn' | 'error' | 'ignore';
+}
+/**
+ * The first plugin object. Its `name` is the public string `nave`, the prefix of every message it
+ * prints.
+ */
+interface NaveVitePlugin {
+    readonly name: 'nave';
+    config(config?: unknown, env?: {
+        readonly command?: string;
+    }): UsedConfig | undefined;
+    configEnvironment(name: string, options: {
+        readonly consumer?: string;
+    }): {
+        resolve: {
+            noExternal: string[];
+        };
+    } | undefined;
+    configResolved(config: ResolvedConfigLike): void;
+    configureServer(server: unknown): void;
+    closeBundle(this: {
+        readonly environment?: object;
+    }): void;
+    readonly buildApp: {
+        handler(this: {
+            warn(message: string): void;
+        }, builder: BuilderLike): Promise<void>;
+        readonly order: 'post';
+    };
+    transform(this: TransformContext, code: string, id: string): Promise<TransformResultLike | undefined>;
+    hotUpdate(this: HotUpdateContext, options: HotUpdateOptions): Promise<never[] | undefined> | never[] | undefined;
+    renderChunk(this: RenderContext, code: string, chunk: RenderedChunk): Promise<undefined>;
+    readonly generateBundle: {
+        handler(this: BundleContext, options: unknown, bundle: Record<string, BundleEntry>): void;
+        readonly order: 'post';
+    };
+}
+/**
+ * What `navePlugin()` returns: the same two plugin objects whatever the options.
+ */
+type NavePlugins = [NaveVitePlugin, NaveCollectPlugin];
+/**
+ * The Nave Vite plugin: one entry in `plugins`.
+ */
+declare function navePlugin(options?: NaveViteOptions): NavePlugins;
+
+export { type NavePlugins, type NaveViteOptions, type NaveVitePlugin, navePlugin as default, navePlugin };