@pitlane/theme 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -1,325 +1,7 @@
-import { ElementProps, Handle, MixinDescriptor, RemixElement, css as css$1 } from "remix/ui";
+import { A as DimensionToken, B as UntypedToken, E as BorderToken, F as NumberToken, I as ShadowToken, L as StrokeStyleToken, M as FontFamilyToken, N as FontWeightToken, O as ColorToken, P as GradientToken, R as TokenType, T as AnyToken, j as DurationToken, k as CubicBezierToken, z as TransitionToken } from "./schema-CRP607Pg.mjs";
+import { a as DeepPartialTokens, c as ScaleFn, d as ThemePatch, f as TokenTree, i as createTheme, l as ThemeInit, m as Tokens, n as ThemeProps, o as Merged, p as TokenValue, r as ThemeResult, s as ScalableToken, t as ThemeComponent, u as ThemeMode } from "./theme-Ck-4suI4.mjs";
+import { ElementProps, MixinDescriptor, css as css$1 } from "remix/ui";
 import * as CSS from "csstype";
-//#region src/brands.d.ts
-/**
- * The twelve DTCG token types, in canonical order.
- *
- * @internal
- */
-declare const TOKEN_TYPES: readonly ["color", "dimension", "duration", "fontFamily", "fontWeight", "number", "cubicBezier", "shadow", "border", "transition", "gradient", "strokeStyle"];
-/** The twelve DTCG token `$type` values. @see {@link AnyToken} */
-type TokenType = (typeof TOKEN_TYPES)[number];
-declare const COLOR: unique symbol;
-declare const DIMENSION: unique symbol;
-declare const DURATION: unique symbol;
-declare const FONT_FAMILY: unique symbol;
-declare const FONT_WEIGHT: unique symbol;
-declare const NUMBER: unique symbol;
-declare const CUBIC_BEZIER: unique symbol;
-declare const SHADOW: unique symbol;
-declare const BORDER: unique symbol;
-declare const TRANSITION: unique symbol;
-declare const GRADIENT: unique symbol;
-declare const STROKE_STYLE: unique symbol;
-/** Compile-time brand for a `color` token. */
-type ColorToken = string & {
-  readonly [COLOR]: true;
-};
-/** Compile-time brand for a `dimension` token. */
-type DimensionToken = string & {
-  readonly [DIMENSION]: true;
-};
-/** Compile-time brand for a `duration` token. */
-type DurationToken = string & {
-  readonly [DURATION]: true;
-};
-/** Compile-time brand for a `fontFamily` token. */
-type FontFamilyToken = string & {
-  readonly [FONT_FAMILY]: true;
-};
-/** Compile-time brand for a `fontWeight` token. */
-type FontWeightToken = string & {
-  readonly [FONT_WEIGHT]: true;
-};
-/** Compile-time brand for a `number` token. */
-type NumberToken = string & {
-  readonly [NUMBER]: true;
-};
-/** Compile-time brand for a `cubicBezier` token. */
-type CubicBezierToken = string & {
-  readonly [CUBIC_BEZIER]: true;
-};
-/** Compile-time brand for a `shadow` token. */
-type ShadowToken = string & {
-  readonly [SHADOW]: true;
-};
-/** Compile-time brand for a `border` token. */
-type BorderToken = string & {
-  readonly [BORDER]: true;
-};
-/** Compile-time brand for a `transition` token. */
-type TransitionToken = string & {
-  readonly [TRANSITION]: true;
-};
-/** Compile-time brand for a `gradient` token. */
-type GradientToken = string & {
-  readonly [GRADIENT]: true;
-};
-/** Compile-time brand for a `strokeStyle` token. */
-type StrokeStyleToken = string & {
-  readonly [STROKE_STYLE]: true;
-};
-/**
- * Maps each {@link TokenType} to its token brand.
- *
- * @internal
- */
-interface BrandByType {
-  color: ColorToken;
-  dimension: DimensionToken;
-  duration: DurationToken;
-  fontFamily: FontFamilyToken;
-  fontWeight: FontWeightToken;
-  number: NumberToken;
-  cubicBezier: CubicBezierToken;
-  shadow: ShadowToken;
-  border: BorderToken;
-  transition: TransitionToken;
-  gradient: GradientToken;
-  strokeStyle: StrokeStyleToken;
-}
-/**
- * The union of all twelve token brands. Brands are compile-time tags
- * naming each token's type; they let {@link css} reject a dimension
- * where a color belongs. They exist only in the type system — every
- * ref is a plain string at runtime, so brands cost nothing — and they
- * are theme-independent, so tokens minted by two different
- * {@link createTheme} calls mix freely in one {@link css} call.
- */
-type AnyToken = BrandByType[TokenType];
-//#endregion
-//#region src/types.d.ts
-/**
- * A DTCG group node: an optional `$type` shared by descendants, plus
- * nested groups and tokens.
- *
- * @internal
- */
-interface TokenGroup {
-  $type?: TokenType;
-  $description?: string;
-  $extensions?: Record<string, unknown>;
-  [key: string]: unknown;
-}
-/**
- * The input document {@link createTheme} accepts, shaped by the
- * [W3C DTCG format](https://www.designtokens.org/tr/drafts/format/). A
- * node with a `$value` is a token; every other key is a group, and
- * groups nest to any depth. A token's type comes from its own
- * `$type`, from the token it aliases, or from the nearest ancestor
- * group's `$type`, in that order.
- *
- * Each `$type` fixes the accepted `$value` forms and how the value
- * serializes into CSS:
- *
- * | `$type` | Accepted `$value` | Serializes to |
- * | --- | --- | --- |
- * | `color` | CSS color string, or `{ colorSpace, components, alpha?, hex? }` | the string as written, `hex` when present, or the color-space function (`oklch(…)`, `color(display-p3 …)`) |
- * | `dimension` | `"16px"`, or `{ value, unit }` with `px` or `rem` | the string verbatim, or concatenation |
- * | `duration` | `"200ms"`, or `{ value, unit }` with `ms` or `s` | the string verbatim, or concatenation |
- * | `fontFamily` | string or non-empty array of strings | quoted where needed, comma-joined |
- * | `fontWeight` | number 1–1000, or a DTCG keyword like `"semi-bold"` | the number (keywords map to numbers) |
- * | `number` | number | the number |
- * | `cubicBezier` | `[x1, y1, x2, y2]` | `cubic-bezier(…)` |
- * | `shadow` | `{ color, offsetX, offsetY, blur?, spread?, inset? }`, or an array of them | a CSS shadow list, `inset` first when `inset` is `true` |
- * | `border` | `{ color, width, style }` | `width style color` |
- * | `transition` | `{ duration, timingFunction, delay? }` | `duration timing-function delay` |
- * | `gradient` | array of `{ color, position }` stops | a color-stop list for use inside `linear-gradient(…)` |
- * | `strokeStyle` | keyword or object | the keyword, or `dashed` for the object form |
- *
- * Gradient stop positions must be literal numbers, though stop colors
- * may be aliases. `typography` tokens throw — they need one variable
- * per subproperty, which is not built.
- *
- * Only the object form of a `dimension` or `duration` is unit-checked.
- * The string form is emitted verbatim, which is the way in for units
- * the DTCG format does not cover (`em`, `ch`, `%`) and for computed
- * values such as `clamp(…)`.
- *
- * A `$value` of `"{path.to.token}"` is an alias: it resolves to
- * `var()` indirection in the emitted CSS, not a copied value, which is
- * what makes mode overrides cascade. Aliases work as full token values
- * and inside composite sub-values (e.g. a shadow's `color`), and they
- * are type-checked — a token with an explicit `$type` only aliases a
- * token of that same type. Unknown targets and reference cycles throw.
- *
- * @see {@link createTheme}
- * @see {@link TokenTree} for the resulting accessor shape.
- * @see {@link DeepPartialTokens} for the mode-override shape.
- */
-type DTCGDocument = TokenGroup;
-type GroupType<N, Inherited> = N extends {
-  $type: infer Ty extends TokenType;
-} ? Ty : Inherited;
-type BrandOf<Ty> = Ty extends TokenType ? BrandByType[Ty] : never;
-type TokenTypeOf<N, Root, Inherited> = N extends {
-  $type: infer Ty extends TokenType;
-} ? Ty : N extends {
-  $value: `{${infer P}}`;
-} ? TypeAtPath<Root, P, Root, GroupType<Root, undefined>> : Inherited extends TokenType ? Inherited : never;
-type MatchKey<N, S extends string> = keyof N extends (infer K) ? K extends string | number ? `${K}` extends S ? K : never : never : never;
-type TypeAtPath<N, P extends string, Root, Inherited> = P extends `${infer Head}.${infer Rest}` ? MatchKey<N, Head> extends (infer K) ? [K] extends [never] ? never : TypeAtPath<N[K & keyof N], Rest, Root, GroupType<N[K & keyof N], Inherited>> : never : MatchKey<N, P> extends (infer K) ? [K] extends [never] ? never : TokenTypeOf<N[K & keyof N], Root, Inherited> : never;
-type TreeOf<N, Root, Inherited> = { [K in Exclude<keyof N, `$${string}`>]: N[K] extends {
-  $value: unknown;
-} ? BrandOf<TokenTypeOf<N[K], Root, Inherited>> : TreeOf<N[K], Root, GroupType<N[K], Inherited>>; };
-/**
- * The accessor shape for a document `T`: the same nesting as the
- * document, with every token leaf replaced by its branded `var(--…)`
- * reference string. Numeric keys index with brackets
- * (`t.color.gray[900]`).
- *
- * An `any` document (e.g. from `JSON.parse`) short-circuits to
- * `unknown` — mapping over `any` would otherwise recurse without
- * bound.
- *
- * @see {@link ThemeResult}
- */
-type TokenTree<T> = 0 extends 1 & T ? unknown : TreeOf<T, T, GroupType<T, undefined>>;
-/**
- * The mode-override shape for a document `T`: every group is optional
- * and each token node is reduced to `{ $value }`. A mode overrides a
- * token's value only, never its `$type` or structure.
- *
- * An `any` document short-circuits to `unknown`, as in
- * {@link TokenTree}.
- *
- * @see {@link ThemeOptions}
- */
-type DeepPartialTokens<T> = 0 extends 1 & T ? unknown : { [K in Exclude<keyof T, `$${string}`>]?: T[K] extends {
-  $value: unknown;
-} ? {
-  $value: unknown;
-} : DeepPartialTokens<T[K]>; };
-//#endregion
-//#region src/theme.d.ts
-/**
- * Options for {@link createTheme}.
- *
- * @see {@link DeepPartialTokens} for the override shape.
- */
-interface ThemeOptions<T> {
-  /**
-   * Per-appearance token overrides. Each mode is a partial of the
-   * base document that may set `$value` only; its overrides emit
-   * inside an `@media (prefers-color-scheme: <mode>)` block, so the
-   * OS appearance setting flips the affected variables with no
-   * attribute selectors and no JavaScript.
-   */
-  modes?: {
-    /** Overrides applied under `prefers-color-scheme: light`. */
-    light?: DeepPartialTokens<T>;
-    /** Overrides applied under `prefers-color-scheme: dark`. */
-    dark?: DeepPartialTokens<T>;
-  };
-}
-/**
- * Props for the {@link ThemeComponent}. `nonce` sets the `nonce`
- * attribute on the emitted `<style>` element for Content Security
- * Policy setups.
- */
-type ThemeProps = {
-  /** CSP nonce forwarded to the `<style>` element's `nonce` attribute. */
-  nonce?: string;
-};
-/**
- * The `<Theme />` component returned by {@link createTheme}. Render it
- * once near the document root (e.g. inside `<head>`). It renders a
- * `<style data-pitlane-theme>` element holding the base `:root`
- * declarations plus one `@media` block per configured mode, streams
- * identically on the server and the client, and escapes the style
- * text so token values cannot break out of the tag.
- *
- * @see {@link ThemeProps} for the `nonce` prop.
- */
-type ThemeComponent = (handle: Handle<ThemeProps>) => () => RemixElement;
-/**
- * The object returned by {@link createTheme}: the typed token
- * accessor, the `raw` resolver, and the `<Theme />` component.
- */
-interface ThemeResult<T> {
-  /**
-   * Same-shape accessor over the document: every token leaf is a
-   * branded `var(--…)` reference string. Numeric keys index with
-   * brackets (`t.color.gray[900]`).
-   *
-   * @see {@link TokenTree}
-   */
-  token: TokenTree<T>;
-  /**
-   * Resolves a token ref to its serialized base-mode value, chasing
-   * aliases and composite sub-value references to the end. It always
-   * answers for the base mode, even when a dark override exists,
-   * since mode resolution happens in CSS rather than in JavaScript.
-   * Because refs are plain strings, two themes that mint the same
-   * token path produce identical refs and `raw` cannot tell them
-   * apart, answering for its own theme.
-   *
-   * @param ref - A branded token ref from this theme's accessor.
-   * @throws ThemeError if `ref` names a variable this theme never
-   * minted.
-   */
-  raw(ref: AnyToken): string;
-  /** The `<Theme />` component. @see {@link ThemeComponent} */
-  Theme: ThemeComponent;
-}
-/**
- * Compiles a DTCG design-token document into a typed accessor, a
- * `raw` resolver, and a `<Theme />` component. All validation and
- * serialization happen eagerly here: a malformed document throws
- * {@link ThemeError} rather than emitting broken CSS.
- *
- * Each token becomes a CSS custom property named after its
- * kebab-cased path — `color.gray.900` becomes `--color-gray-900`.
- * Two paths that collide after kebab-casing throw, as do names
- * containing `.`, `{`, or `}`, which the alias syntax reserves.
- *
- * Author the document in TypeScript, not imported JSON: `createTheme`
- * infers a `const` type parameter, so an inline object needs no
- * `as const`, but a JSON import widens its literals and the token
- * brands degrade.
- *
- * @param config - The token document. Groups nest to any depth; a
- * node with a `$value` is a token.
- * @param options - Optional per-mode overrides ({@link ThemeOptions}).
- * @returns The {@link ThemeResult}: `token`, `raw`, and `Theme`.
- * @throws ThemeError on any validation failure (unknown or
- * unresolvable `$type`, reserved characters, variable collision,
- * unknown or wrong-typed alias, alias cycle, invalid value, or a bad
- * mode override).
- *
- * @see {@link DTCGDocument} for the document shape, the accepted
- * `$value` forms, and alias semantics.
- *
- * @example
- * ```ts
- * export let { token: t, raw, Theme } = createTheme(
- *     {
- *         color: {
- *             $type: "color",
- *             white: { $value: "#fff" },
- *             gray: { 900: { $value: "#171717" } },
- *             bg: { $value: "{color.white}" }, // alias → var() indirection
- *         },
- *     },
- *     { modes: { dark: { color: { bg: { $value: "{color.gray.900}" } } } } },
- * );
- *
- * t.color.bg; // "var(--color-bg)"
- * raw(t.color.bg); // "#fff" (base mode, alias chased to the end)
- * ```
- */
-declare function createTheme<const T extends DTCGDocument>(config: T, options?: ThemeOptions<T>): ThemeResult<T>;
-//#endregion
 //#region src/props.d.ts
 type Wide = "inherit" | "initial" | "unset" | "revert" | "revert-layer";
 type ColorLike = ColorToken | "transparent" | "currentColor" | Wide;
@@ -541,6 +223,78 @@ type ThemedCSSMixin<node extends Element = Element> = MixinDescriptor<node, [sty
  */
 declare function css<node extends Element = Element>(styles: ThemedCSSProps): ThemedCSSMixin<node>;
 //#endregion
+//#region src/scale.d.ts
+/**
+ * Turns one token into a multiplier, so a scale does not have to name
+ * every step. The returned function produces
+ * `calc(<base> * <steps>)`, keeping whichever brand the base carried.
+ *
+ * Use this for a token you did not declare as a scale. A token
+ * declared with `s.scale()` is already a multiplier, and its base is
+ * `t.spacing.token` when you need it.
+ *
+ * The result is a CSS string like any other, so it also works as an
+ * authored token value.
+ *
+ * @param base - The token to multiply
+ * @returns A function from steps to a token of the same type
+ *
+ * @example
+ * ```ts
+ * import { scale } from "@pitlane/theme";
+ *
+ * let step = scale(t.tracking.tight);
+ * css({ letterSpacing: step(2) }); // calc(var(--tracking-tight) * 2)
+ * ```
+ */
+declare function scale<base extends ScalableToken>(base: base): (steps: number) => base;
+/**
+ * A `light-dark()` color, resolved by the browser against the
+ * `color-scheme` property. A subtree that sets `color-scheme` flips
+ * whatever the media query says, which is what a theme toggle needs.
+ *
+ * Both arguments may be token references, so a mode override of either
+ * primitive still reaches the result.
+ *
+ * `light-dark()` is color-only. Use `modes` for anything else.
+ *
+ * @param light - The color for a light `color-scheme`
+ * @param dark - The color for a dark `color-scheme`
+ * @returns The `light-dark()` function text
+ *
+ * @example
+ * ```ts
+ * tokens: { surface: { page: lightDark("#ffffff", "#1a1a1a") } }
+ * ```
+ */
+declare function lightDark(light: string, dark: string): string;
+//#endregion
+//#region src/tokens.d.ts
+/**
+ * The error {@link createTheme} throws for every structural failure:
+ * one problem, one sentence.
+ *
+ * | Failure | Message shape |
+ * | --- | --- |
+ * | No schema entry | `"space.md" has no schema entry` |
+ * | Unknown reference | `"color.bg" references unknown token "color.nope"` |
+ * | Reference type mismatch | `"color.bg" references "space.md" of type "dimension" where "color" is required` |
+ * | Reference to an untyped token | `"color.bg" references untyped token "animate.spin"` |
+ * | Reference cycle | `Reference cycle: color.a → color.b → color.a` |
+ * | Variable collision | `Tokens "a.b" and "a-b" both produce the CSS variable --a-b` |
+ * | Reserved characters | `Token or group name "a.b" contains characters reserved by references (".", "{", "}")` |
+ * | Empty identifier | `Token path segment "!!" produces an empty CSS identifier` |
+ * | Unknown mode token | `Mode "dark" overrides unknown token "color.nope"` |
+ *
+ * Bad token *values* raise `ValidationError` from `remix/data-schema`
+ * instead, because there may be several and each carries its own path.
+ *
+ * @see {@link createTheme}
+ */
+declare class ThemeError extends Error {
+  name: string;
+}
+//#endregion
 //#region src/tva.d.ts
 type VariantShape = Record<string, Record<string, ThemedCSSProps>>;
 type VariantValue<K> = K extends "true" | "false" ? boolean : K;
@@ -693,30 +447,4 @@ type ClassValue = string | number | null | undefined | false | readonly ClassVal
  */
 declare function cx(...inputs: ClassValue[]): string;
 //#endregion
-//#region src/tokens.d.ts
-/**
- * The error {@link createTheme} throws for every validation and
- * serialization failure. Validation is eager, so a bad document never
- * emits CSS. Every message names the offending token path.
- *
- * | Condition | Message shape |
- * | --- | --- |
- * | Unknown `$type` | `"color.brand" has unknown $type "sparkles"` |
- * | Unresolvable `$type` | `"color.brand" has no resolvable $type` |
- * | Typography token | `"heading": typography tokens are not supported in v1` |
- * | Reserved character in a name | `Token or group name "a.b" contains characters reserved by DTCG references (".", "{", "}")` |
- * | Empty CSS identifier | `Token path segment "!" produces an empty CSS identifier` |
- * | Malformed node | `"color.bg" is neither a group nor a token` |
- * | Variable-name collision | `Tokens "a" and "b" both produce the CSS variable --x` |
- * | Alias to a missing token | `"color.bg" references unknown token "color.white"` |
- * | Alias to a wrong-typed token | `"x" references "space.sm" of type "dimension" where "color" is required` |
- * | Alias cycle | `Alias cycle: a → b → a` |
- * | Invalid value for a declared type | `"x" has an invalid color value: …` — also `unknown colorSpace`, `unknown fontWeight keyword`, and `unknown strokeStyle keyword`; an empty `fontFamily` array counts |
- * | Bad mode override | `Mode override "x" does not exist in the base document`, `Mode override "x" may only set $value`, or (via a cross-type alias) the wrong-typed-alias message |
- * | Unminted `raw()` ref | `raw(): "var(--x)" names a var this theme never minted` |
- */
-declare class ThemeError extends Error {
-  name: string;
-}
-//#endregion
-export { type AnyToken, type BorderToken, type ClassValue, type ColorToken, type CombinedTVAFn, type CubicBezierToken, type DTCGDocument, type DeepPartialTokens, type DimensionToken, type DurationToken, type FontFamilyToken, type FontWeightToken, type GradientToken, type NumberToken, type ShadowToken, type StrokeStyleToken, type TVAConfig, type TVAFn, type TVAProps, type ThemeComponent, ThemeError, type ThemeOptions, type ThemeProps, type ThemeResult, type ThemedCSSMixin, type ThemedCSSProps, type TokenTree, type TokenType, type TransitionToken, combine, createTheme, css, cx, tva };
+export { type AnyToken, type BorderToken, type ClassValue, type ColorToken, type CombinedTVAFn, type CubicBezierToken, type DeepPartialTokens, type DimensionToken, type DurationToken, type FontFamilyToken, type FontWeightToken, type GradientToken, type Merged, type NumberToken, type ScalableToken, type ScaleFn, type ShadowToken, type StrokeStyleToken, type TVAConfig, type TVAFn, type TVAProps, type ThemeComponent, ThemeError, type ThemeInit, type ThemeMode, type ThemePatch, type ThemeProps, type ThemeResult, type ThemedCSSMixin, type ThemedCSSProps, type TokenTree, type TokenType, type TokenValue, type Tokens, type TransitionToken, type UntypedToken, combine, createTheme, css, cx, lightDark, scale, tva };