@menapo/vicss 0.0.0-stage → 1.1.0

package/dist/vite.d.ts

@@ -0,0 +1,270 @@
+import { Plugin } from "vite";
+//#region src/core/types.d.ts
+/** Token scales a property can draw its values from. */
+type ScaleName = "colors" | "spacing" | "sizes" | "radii" | "fonts" | "fontSizes" | "fontWeights" | "lineHeights" | "letterSpacings" | "shadows" | "textShadows" | "durations" | "easings" | "zIndices" | "opacities" | "blurs" | "aspectRatios" | "breakpoints" | "containers";
+/** A style object as authors write it. Values are checked by `normalizeStyle`. */
+interface StyleObject {
+  [key: string]: StyleValue | StyleObject | undefined;
+}
+type StyleValue = string | number | ConditionalValue | null | undefined;
+/** `{ base: 4, _md: 6, _hover: { _md: 8 } }`: a value per condition. */
+interface ConditionalValue {
+  [condition: string]: StyleValue;
+}
+/** A token tree node: a value, or a group of nodes. `DEFAULT` names the group itself. */
+type TokenTree = {
+  [name: string]: string | number | TokenTree;
+};
+/** A semantic token: one value, or a value per mode (`{ base, _dark }`). */
+type SemanticTokenValue = string | {
+  [modeOrBase: string]: string;
+};
+type SemanticTokenTree = {
+  [name: string]: SemanticTokenValue | SemanticTokenTree;
+};
+/** A utility turns one authored value into a style object (`size: 4` → width and height). */
+interface UtilityDefinition {
+  /** Scale used to type and resolve the utility's value. */
+  readonly scale?: ScaleName;
+  /** `true`-only utilities (`truncate: true`) set this. */
+  readonly boolean?: boolean;
+  readonly transform: (value: string | number | boolean) => StyleObject;
+}
+interface VicssConfig {
+  presets?: VicssConfig[];
+  tokens?: { [scale in ScaleName]?: TokenTree; } & {
+    spacing?: TokenTree | {
+      step: string;
+    };
+  };
+  semanticTokens?: { [scale in ScaleName]?: SemanticTokenTree; };
+  textStyles?: Record<string, StyleObject>;
+  /** Extra named conditions: `"[data-brand=b] &"`, `"@media (…)"`, `"@container (…)"`, `"@supports (…)"`, `"&:is(…)"`. */
+  conditions?: Record<string, string | string[]>;
+  utilities?: Record<string, UtilityDefinition>;
+  /** Element styles by selector, printed in `@layer vicss.global` (PLAN §4.9). */
+  globalCss?: Record<string, StyleObject>;
+  /** `@keyframes` by name: frame selectors (`from`, `to`, `"50%"`) → style. */
+  keyframes?: Record<string, Record<string, StyleObject>>;
+  /** `@font-face` rules, descriptors in camelCase: `{ fontFamily: "Inter", src: "url(…)" }`. */
+  fontFaces?: Array<Record<string, string | number>>;
+  /** How `_dark` and semantic-token dark values are selected (PLAN D12). */
+  darkMode?: "attribute-or-media" | "attribute" | "media" | {
+    selector: string;
+  };
+  /**
+   * What a value outside a property's scale may be (PLAN D8): one level for
+   * every scale, or levels by scale, property or utility name, with
+   * `default` for the rest (`{ default: "tokens", maxWidth: "css" }`).
+   */
+  strict?: Strictness | StrictnessMap;
+  reset?: boolean;
+  include?: string[];
+  exclude?: string[];
+  /** Modules that re-export the vicss runtime (a design system's `./ds`). */
+  importSources?: string[];
+  /** Prefix for token custom properties: `""` gives `--color-accent`. */
+  cssVarPrefix?: string;
+  /**
+   * Colour palettes (PLAN §4.8): styles write `palette.600`, and
+   * `colorPalette: "red"` points it at `colors.red.600` for an element and
+   * its subtree. Off without this key, which reserves the `colors.palette`
+   * group.
+   */
+  palettes?: PalettesConfig;
+  /**
+   * Which tokens app styles may name (PLAN §4.1, public and private
+   * tokens): a token pattern → `"private"` or `"public"`. `"colors"` is the
+   * scale's raw tokens (`tokens.colors`), `"colors.blue"` a token and every
+   * token under it, raw or semantic, and `*` one path segment
+   * (`"colors.*.950"`). The most specific pattern wins; presets mark their
+   * own tokens and the config changes any entry by its pattern.
+   */
+  tokenVisibility?: Record<string, TokenVisibility>;
+  /**
+   * Modules that belong to the design system and may name private tokens:
+   * globs relative to the root, like `include` (`"src/design-system/**"`),
+   * or an installed library's directory (`"node_modules/@acme/ui/**"`).
+   */
+  privateAccess?: string[];
+  /**
+   * The classes a build ships (PLAN §5.5, D31): `prefix` (default `"v"`)
+   * plus a hash of at least `minLength` characters (default 4, 6 in a
+   * library build), or the readable names dev serves (`md:p_6`) with
+   * `readable: true`. Dev serves readable names unless `readable` is false.
+   */
+  classNames?: {
+    prefix?: string;
+    minLength?: number;
+    readable?: boolean;
+  };
+}
+type TokenVisibility = "private" | "public";
+interface PalettesConfig {
+  /** The palette of every element no `colorPalette` applies to: a colour group. */
+  default: string;
+  /**
+   * The colour groups `colorPalette` may name. Default: every top-level
+   * colour group, raw or semantic (`red` for `red.50` … `red.950`, `accent`
+   * for `accent` and `accent.hover`).
+   */
+  names?: string[];
+}
+/**
+ * PLAN D8. `"css"` (the default): a value outside the scale is written as
+ * it is when it is valid CSS for the property, and anything else (a typo of
+ * a token) fails the build. `"warn"`: the same, with a warning for each
+ * value outside the scale. `"tokens"`: only the scale's tokens, CSS-wide
+ * and the scale's keywords, percentages where the scale takes them, and
+ * zero. `"off"`: anything, unchecked.
+ */
+type Strictness = "tokens" | "warn" | "css" | "off";
+/** Levels by scale (`colors`), CSS property (`maxWidth`) or utility (`size`); `default` for the rest. */
+type StrictnessMap = {
+  readonly default?: Strictness;
+} & {
+  readonly [scaleOrProperty: string]: Strictness | undefined;
+};
+//#endregion
+//#region src/core/compile.d.ts
+type Framework = "react" | "preact" | "solid" | "vue" | "svelte" | "astro" | "vanilla";
+//#endregion
+//#region src/vite/critical.d.ts
+/** What the plugin's `critical` option and `critical()` share. */
+interface CriticalOptions {
+  /**
+   * Gzip bytes of a page's inline CSS above which the build warns. The page
+   * is still inlined. Default 14 000: what the first round trip of a new
+   * connection delivers (ten TCP segments), the HTML included.
+   */
+  budget?: number;
+  /**
+   * The JSON file listing each page's inline-style hashes for its
+   * Content-Security-Policy, relative to the output directory; `false`
+   * writes none. Default `vicss-critical.json`.
+   */
+  hashes?: string | false;
+}
+/** `critical()`'s options: the plugin's, and which pages to process. */
+interface CriticalDirOptions extends CriticalOptions {
+  /** Pages to process, by path relative to the directory. Default: every `.html` file. */
+  filter?: (page: string) => boolean;
+  /** Report what would change and write nothing. */
+  dryRun?: boolean;
+}
+/** What each byte of a page's inline CSS is for, to say what to trim when it is over budget. */
+type CriticalPart = "layers" | "tokens" | "global" | "atoms" | "fonts" | "keyframes" | "other";
+interface CriticalPage {
+  /** Relative to the output directory, forward slashes: `index.html`, `blog/post/index.html`. */
+  readonly page: string;
+  /** The page's new HTML; absent when it was left as it was. */
+  readonly html?: string;
+  /** Why the page was left as it was. */
+  readonly skipped?: string;
+  /** Whether `skipped` is a warning: the page links vicss's CSS but could not take critical CSS. */
+  readonly warning?: boolean;
+  /** `sha256-…` of each inline `<style>`, in document order. */
+  readonly hashes: readonly string[];
+  /** The inline CSS, raw and gzipped, all styles together. */
+  readonly bytes: number;
+  readonly gzip: number;
+  /** Raw bytes of the inline CSS by what they are for. */
+  readonly parts: Readonly<Record<CriticalPart, number>>;
+  /** The stylesheets loaded from the end of `<body>` instead, as the output paths of their files. */
+  readonly deferred: readonly string[];
+}
+interface CriticalReport {
+  readonly pages: readonly CriticalPage[];
+  readonly budget: number;
+  /** The hashes file, relative to the output directory, when one was written. */
+  readonly hashesFile?: string;
+  /** One line for a log: how many pages, their sizes. */
+  readonly summary: string;
+  /** Pages over budget, and pages that link vicss's CSS but were left as they were. */
+  readonly warnings: readonly string[];
+}
+/**
+ * Inlines the critical CSS of every page under `dir`: the HTML a framework
+ * writes after `vite build` (Astro, SvelteKit, Vike, React Router
+ * prerendering), which no build hook sees. Pages are rewritten in place,
+ * a page processed before is left alone, and the hashes file is written.
+ */
+export declare function critical(dir: string, options?: CriticalDirOptions): Promise<CriticalReport>;
+//#endregion
+//#region src/vite/plugin.d.ts
+/** Delivery options (PLAN §5.10). Everything else lives in `vicss.config.ts`. */
+interface VicssPluginOptions {
+  /**
+   * A path relative to the Vite root, or the config itself. Default: the
+   * first of `vicss.config.{ts,mts,js,mjs}` in the root, else an empty config.
+   */
+  config?: string | VicssConfig;
+  /** Outer cascade-layer order, e.g. `["reset", "vicss", "app"]`; must contain `"vicss"`. */
+  layers?: string[];
+  /**
+   * The SPA tokens file (PLAN D13), emitted when the client build has an
+   * HTML entry, which links it. `"auto"` (default) and `true` differ only in
+   * that `true` warns when there is no HTML entry; `false` keeps the tokens
+   * at the start of the sheet.
+   */
+  tokensFile?: "auto" | boolean;
+  /**
+   * The attributes `sx()` returns in plain `.js`/`.ts` modules (PLAN §5.12):
+   * `{ className, style }` for `"react"` and `"preact"`, `class` with a style
+   * object for `"vue"` and `"solid"`, `class` with a style string for the
+   * others. Default: the framework the root `package.json` depends on, else
+   * `"vanilla"`. Framework files and JSX modules go by their own framework.
+   * The generated `vicss.d.ts` registers it, which types `sx()`'s result.
+   */
+  framework?: Framework;
+  /**
+   * The generated `vicss.d.ts` (PLAN §5.11), written whenever the config
+   * loads, in dev and in builds, and only when its content changes, with
+   * the lint rules' `vicss.lint.json` next to it (`@menapo/vicss/lint`).
+   * Default: `src/vicss.d.ts` when the root has a `src` directory, else
+   * `app/vicss.d.ts` when it has an `app` one (Nuxt 4, React Router), else
+   * `vicss.d.ts`; `output` is relative to the root; `false` writes neither.
+   */
+  types?: false | {
+    output: string;
+  };
+  /**
+   * Critical CSS for prerendered pages (PLAN D16): in each HTML page the
+   * client build emits, every stylesheet holding vicss's CSS becomes an
+   * inline `<style>` with what the page's markup uses, and the stylesheet
+   * loads from the end of `<body>`, so it no longer blocks the first paint.
+   * The pages' CSP hashes go into `vicss-critical.json`. Pages a framework
+   * writes after the build take `vicss critical <outDir>`, or `critical()`
+   * from this entry. `"prerendered"` takes the defaults; `false`, like
+   * leaving it out, turns it off. Builds only.
+   */
+  critical?: false | "prerendered" | CriticalOptions;
+}
+export declare function vicss(options?: VicssPluginOptions): Plugin[];
+//#endregion
+//#region src/core/literals.d.ts
+/** One declaration of a class, its values literal. */
+interface Literal {
+  /** kebab-case: `padding-inline`, `background-color`. */
+  readonly property: string;
+  /** Tokens replaced by their base values, transitively; other `var()` (a runtime value's) stays. */
+  readonly value: string;
+  /** The property's tier: under one condition, a higher tier wins (`padding-top` over `padding`). */
+  readonly tier: number;
+  /** Condition names it applies under, `[]` for always: `["dark"]`, `["md", "hover"]`. */
+  readonly chain: readonly string[];
+  /**
+   * Where it applies, one entry per alternative of the chain's conditions:
+   * a selector with `&` for the element's class, and its at-rules, outermost
+   * first. The color-scheme modes (`dark`, `light`) are left out, for the
+   * caller to read in `chain`: a mail client needs its own selectors for them.
+   */
+  readonly rules: ReadonlyArray<{
+    readonly selector: string;
+    readonly atRules: readonly string[];
+  }>;
+  /** The value under each mode whose tokens change it: `{ dark: "#f9fafb" }`. */
+  readonly modes?: Readonly<Record<string, string>>;
+}
+//#endregion
+export { type CriticalDirOptions, type CriticalOptions, type CriticalPage, type CriticalPart, type CriticalReport, type Literal, type VicssPluginOptions, vicss as default };