@menapo/vicss 0.0.0-stage → 1.1.0

package/dist/config.d.ts

@@ -0,0 +1,821 @@
+//#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/config/refs.d.ts
+declare const GROUP: unique symbol;
+/**
+ * A group of tokens (`colors.gray`), which names no token of its own: index
+ * it to reach one. An interface, so a group is not a value per mode
+ * (`{ [mode: string]: string }`) either, which a plain object of strings
+ * would be.
+ */
+interface TokenGroupRef {
+  readonly [GROUP]: "a group of tokens: name one of its tokens";
+}
+type Key = string | number;
+/** `{ base, _dark }`: a semantic token's value per mode, which is one token. */
+type IsModeMap<T> = [keyof T] extends ["base" | `_${string}`] ? "base" extends keyof T ? true : false : false;
+type Named<T> = Exclude<keyof T, "DEFAULT" | symbol>;
+type RefNode<T, P extends string, Semantic extends boolean> = T extends string | number ? `{${P}}` : Semantic extends true ? IsModeMap<T> extends true ? `{${P}}` : Group<T, P, Semantic> : Group<T, P, Semantic>;
+/** A group with `DEFAULT` is a token itself, and still a group. */
+type Group<T, P extends string, Semantic extends boolean> = ("DEFAULT" extends keyof T ? `{${P}}` : TokenGroupRef) & { readonly [K in Named<T>]-?: RefNode<NonNullable<T[K]>, `${P}.${K & Key}`, Semantic>; };
+/** The config and its presets, depth first, to a depth no real config reaches. */
+type Layers<C, Depth extends unknown[] = []> = Depth["length"] extends 6 ? C : C | (C extends {
+  readonly presets?: infer P;
+} ? P extends readonly (infer Preset)[] ? Layers<Preset, [...Depth, unknown]> : never : never);
+/** A tree that declares no names: `TokenTree`'s index signature. */
+type Unnamed<T> = T extends unknown ? (string extends keyof T ? true : never) : never;
+/**
+ * A layer's scales of field `F`, but those whose names its type does not
+ * declare (a `dtcg()` result, a preset typed `VicssConfig`): an index
+ * signature would turn every path into a reference, typos included, and
+ * `noUncheckedIndexedAccess` each one into `| undefined`.
+ */
+type Field<L, F extends "tokens" | "semanticTokens"> = L extends unknown ? F extends keyof L ? { [S in keyof NonNullable<L[F]> as [Unnamed<NonNullable<NonNullable<L[F]>[S]>>] extends [never] ? S : never]: NonNullable<L[F]>[S]; } : never : never;
+type Intersect<U> = (U extends unknown ? (u: U) => void : never) extends ((i: infer I) => void) ? I : never;
+type ScaleRef<T, S extends string, Semantic extends boolean> = S extends keyof T ? RefNode<NonNullable<T[S]>, S, Semantic> : unknown;
+/**
+ * What the callback of `defineConfig(config, (tokens) => …)` receives: every
+ * scale `config` and its presets define, raw and semantic, as a tree of
+ * references. `tokens.colors.gray[900]` is `"{colors.gray.900}"`; a group
+ * that is no token (`tokens.colors.gray`) is a `TokenGroupRef`, which no
+ * config value accepts.
+ */
+type TokenRefs<C> = Layers<C> extends (infer L) ? Intersect<Field<L, "tokens">> extends (infer Raw) ? Intersect<Field<L, "semanticTokens">> extends (infer Semantic) ? { readonly [S in (keyof Raw | keyof Semantic) & ScaleName]: ScaleRef<Raw, S, false> & ScaleRef<Semantic, S, true>; } : never : never : never;
+/**
+ * What the callback returns: any config key but `tokens` and `presets`,
+ * which the references are built from, so they stay in the first argument.
+ */
+type DerivedConfig = Omit<VicssConfig, "tokens" | "presets"> & {
+  readonly tokens?: never;
+  readonly presets?: never;
+};
+//#endregion
+//#region src/config/presets/reset.d.ts
+/**
+ * The `reset` preset: `presets: [reset]` is `reset: true`, a modern reset in
+ * the `vicss.reset` layer (PLAN §4.9, D15; the rules are in
+ * `src/core/reset.ts`). It is opt-in because a reset is the app's choice: a
+ * component library's preset must never carry it.
+ */
+export declare const reset: {
+  reset: true;
+};
+//#endregion
+//#region src/config/presets/shorthands.d.ts
+export declare const shorthands: {
+  utilities: Record<string, UtilityDefinition>;
+};
+//#endregion
+//#region src/config/presets/tailwind.d.ts
+export declare const tailwind: {
+  tokens: {
+    colors: {
+      red: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      orange: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      amber: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      yellow: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      lime: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      green: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      emerald: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      teal: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      cyan: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      sky: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      blue: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      indigo: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      violet: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      purple: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      fuchsia: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      pink: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      rose: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      slate: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      gray: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      zinc: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      neutral: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      stone: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      mauve: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      olive: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      mist: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      taupe: {
+        50: string;
+        100: string;
+        200: string;
+        300: string;
+        400: string;
+        500: string;
+        600: string;
+        700: string;
+        800: string;
+        900: string;
+        950: string;
+      };
+      black: string;
+      white: string;
+    };
+    spacing: {
+      step: string;
+    };
+    sizes: {
+      "3xs": string;
+      "2xs": string;
+      xs: string;
+      sm: string;
+      md: string;
+      lg: string;
+      xl: string;
+      "2xl": string;
+      "3xl": string;
+      "4xl": string;
+      "5xl": string;
+      "6xl": string;
+      "7xl": string;
+    };
+    breakpoints: {
+      sm: string;
+      md: string;
+      lg: string;
+      xl: string;
+      "2xl": string;
+    };
+    containers: {
+      "3xs": string;
+      "2xs": string;
+      xs: string;
+      sm: string;
+      md: string;
+      lg: string;
+      xl: string;
+      "2xl": string;
+      "3xl": string;
+      "4xl": string;
+      "5xl": string;
+      "6xl": string;
+      "7xl": string;
+    };
+    fonts: {
+      sans: string;
+      serif: string;
+      mono: string;
+    };
+    fontSizes: {
+      xs: string;
+      sm: string;
+      base: string;
+      lg: string;
+      xl: string;
+      "2xl": string;
+      "3xl": string;
+      "4xl": string;
+      "5xl": string;
+      "6xl": string;
+      "7xl": string;
+      "8xl": string;
+      "9xl": string;
+    };
+    fontWeights: {
+      thin: string;
+      extralight: string;
+      light: string;
+      normal: string;
+      medium: string;
+      semibold: string;
+      bold: string;
+      extrabold: string;
+      black: string;
+    };
+    letterSpacings: {
+      tighter: string;
+      tight: string;
+      normal: string;
+      wide: string;
+      wider: string;
+      widest: string;
+    };
+    lineHeights: {
+      tight: string;
+      snug: string;
+      normal: string;
+      relaxed: string;
+      loose: string;
+    };
+    radii: {
+      xs: string;
+      sm: string;
+      md: string;
+      lg: string;
+      xl: string;
+      "2xl": string;
+      "3xl": string;
+      "4xl": string;
+    };
+    shadows: {
+      "2xs": string;
+      xs: string;
+      sm: string;
+      md: string;
+      lg: string;
+      xl: string;
+      "2xl": string;
+    };
+    textShadows: {
+      "2xs": string;
+      xs: string;
+      sm: string;
+      md: string;
+      lg: string;
+    };
+    easings: {
+      in: string;
+      out: string;
+      "in-out": string;
+    };
+    blurs: {
+      xs: string;
+      sm: string;
+      md: string;
+      lg: string;
+      xl: string;
+      "2xl": string;
+      "3xl": string;
+    };
+    aspectRatios: {
+      video: string;
+    };
+  };
+  textStyles: {
+    xs: {
+      fontSize: string;
+      lineHeight: string;
+    };
+    sm: {
+      fontSize: string;
+      lineHeight: string;
+    };
+    base: {
+      fontSize: string;
+      lineHeight: string;
+    };
+    lg: {
+      fontSize: string;
+      lineHeight: string;
+    };
+    xl: {
+      fontSize: string;
+      lineHeight: string;
+    };
+    "2xl": {
+      fontSize: string;
+      lineHeight: string;
+    };
+    "3xl": {
+      fontSize: string;
+      lineHeight: string;
+    };
+    "4xl": {
+      fontSize: string;
+      lineHeight: string;
+    };
+    "5xl": {
+      fontSize: string;
+      lineHeight: string;
+    };
+    "6xl": {
+      fontSize: string;
+      lineHeight: string;
+    };
+    "7xl": {
+      fontSize: string;
+      lineHeight: string;
+    };
+    "8xl": {
+      fontSize: string;
+      lineHeight: string;
+    };
+    "9xl": {
+      fontSize: string;
+      lineHeight: string;
+    };
+  };
+  keyframes: {
+    spin: {
+      to: {
+        transform: string;
+      };
+    };
+    ping: {
+      "75%, 100%": {
+        transform: string;
+        opacity: string;
+      };
+    };
+    pulse: {
+      "50%": {
+        opacity: string;
+      };
+    };
+    bounce: {
+      "0%, 100%": {
+        transform: string;
+        animationTimingFunction: string;
+      };
+      "50%": {
+        transform: string;
+        animationTimingFunction: string;
+      };
+    };
+  };
+};
+//#endregion
+//#region src/config/dtcg.d.ts
+/** Where a group's tokens go: a scale, the text styles, or nowhere (`false`). */
+type DtcgTarget = ScaleName | "textStyles";
+interface DtcgOptions {
+  /**
+   * Group path (DTCG names joined with `.`, as in an alias) → scale, or
+   * `false` to leave the group out without a warning. The longest matching
+   * path wins, and it beats the group-name and `$type` rules. A path that
+   * names no group is an error, so a typo cannot pass silently.
+   */
+  scales?: Record<string, DtcgTarget | false>;
+  /**
+   * Resolver files: modifier → context → the vicss mode its values become
+   * (`"dark"` or `"_dark"`), `"base"` for the unconditioned values, or
+   * `false` to ignore the context. Unlisted contexts: the modifier's
+   * `default` (else its first context) is `"base"`, and every other context
+   * is the mode of the same name in camelCase (`high-contrast` →
+   * `highContrast`), which the config must declare as a condition unless it
+   * is `dark` or `light`.
+   */
+  modes?: Record<string, Record<string, string | false>>;
+  /** Receives one message per kind of skipped token. Defaults to `console.warn`. */
+  onWarn?: (message: string) => void;
+}
+/** The token part of a config: spread it into `defineConfig`, or pass it in `presets`. */
+type DtcgConfig = Pick<VicssConfig, "tokens" | "semanticTokens" | "textStyles" | "tokenVisibility">;
+/**
+ * Reads DTCG 2025.10 tokens: a path or `file:` URL of a `.tokens.json`,
+ * `.tokens` or `.resolver.json` file, or a parsed object. A relative path is
+ * relative to the vicss config file being loaded, else to `process.cwd()`
+ * (a config built in `vite.config.ts`); `new URL("./x", import.meta.url)` is
+ * relative to the calling module everywhere, which a preset package needs.
+ * Files a resolver references are read relative to the resolver.
+ *
+ * ```ts
+ * export default defineConfig({ presets: [dtcg("./tokens.resolver.json")] });
+ * ```
+ */
+/**
+ * A `file:` URL (`new URL("./tokens.json", import.meta.url)`), by its shape:
+ * the declarations stay free of the DOM's and Node's `URL`, which a config-
+ * only or Workers program does not have.
+ */
+interface FileUrl {
+  readonly href: string;
+  readonly protocol: string;
+}
+export declare function dtcg(source: string | FileUrl | object, options?: DtcgOptions): DtcgConfig;
+//#endregion
+//#region src/config/index.d.ts
+/**
+ * Types the config of a project: `export default defineConfig({ … })`.
+ *
+ * With a second argument, the values that name tokens are typed too (PLAN
+ * D32): `defineConfig({ presets, tokens }, ({ colors }) => ({ semanticTokens:
+ * { colors: { text: colors.gray[900] } } }))`. The callback receives every
+ * token of the first argument and its presets, each the brace string the
+ * config takes (`"{colors.gray.900}"`), and returns any key but `tokens` and
+ * `presets`; a key it returns replaces the first argument's.
+ */
+export declare function defineConfig(config: VicssConfig): VicssConfig;
+export declare function defineConfig<C extends VicssConfig>(config: C, derive: (tokens: TokenRefs<C>) => DerivedConfig): VicssConfig;
+/**
+ * Types a design system shared as a preset: `presets: [myPreset]`. Its token
+ * names stay in its type, for the callback of `defineConfig`.
+ */
+export declare function definePreset<P extends VicssConfig>(preset: P): P;
+//#endregion
+export type { DerivedConfig, DtcgConfig, DtcgOptions, DtcgTarget, FileUrl, PalettesConfig, ScaleName, SemanticTokenTree, Strictness, StrictnessMap, StyleObject, TokenGroupRef, TokenRefs, TokenTree, TokenVisibility, UtilityDefinition, VicssConfig };