@homebound/truss 1.137.4 → 2.0.0-next.1

package/build/index.d.ts

@@ -1,5 +1,264 @@
-export * from "./config";
-export { defaultSections } from "./sections/tachyons";
-export { generate } from "./generate";
-export type { IncConfig } from "./methods";
-export { newAliasesMethods, newMethod, newPxMethod, newMethodsForProp, newCoreIncrementMethods, newIncrementMethods, newParamMethod, newSetCssVariablesMethod, } from "./methods";
+import { Properties } from 'csstype';
+import { Code } from 'ts-poet';
+
+/**
+ * A map from human name to font size, i.e. `f12` -> `12px`.
+ *
+ * Or a set of properties, i.e. `f12` -> `{ fontFamily: ..., fontWeight: ... }`.
+ */
+type FontConfig = Record<string, string | Properties>;
+/**
+ * Provides users with an easy way to configure the major/most-often configurable
+ * aspect of a design system, i.e. the palette, fonts, and increments.
+ *
+ * Truss's built-in rules, i.e. `typeScale.ts` for fonts, `skins.ts` for colors,
+ * will read these values to determine their output.
+ *
+ * Note that users can always override whole sections of Truss's default set
+ * of rules by setting `methods["typeScale"] = {}`, see the readme for more
+ * information.
+ */
+interface Config {
+    /** The output path of the `Css.ts` file. */
+    outputPath: string;
+    /**
+     * A map from the human/design system name to color value, i.e. `black` -> `#000000`.
+     *
+     * Design systems can use either physical names, i.e. `Sky50 -> #...`, or logical
+     * names, i.e. `Primary -> #...`, where the logical names are more themeable, but
+     * that's up to each design system to decide.
+     */
+    palette: Record<string, string>;
+    /**
+     * A map from human name to font size, i.e. `f12` -> `12px`.
+     *
+     * Or a set of properties, i.e. `f12` -> `{ fontFamily: ..., fontWeight: ... }`.
+     */
+    fonts: FontConfig;
+    /** The design system's increment in pixels. */
+    increment: number;
+    /** The number of increments to generate for rules like `mt1`, `mt2`, etc. */
+    numberOfIncrements: number;
+    /** Short-hand aliases like `bodyText` --> `["f12", "black"]`. */
+    aliases?: Aliases;
+    /** Type aliases for Only clauses, i.e. `Margin` --> `["marginTop", ...]`. `Margin` and `Padding` are provided. */
+    typeAliases?: Record<string, Array<keyof Properties>>;
+    /** Breakpoints, i.e. `{ sm: 0, md: 500 }`. */
+    breakpoints?: Record<string, number>;
+    /**
+     * Which default methods to include.
+     *
+     * Currently, we support either `tachyons`, `tachyons-rn`, or `none`.
+     * Could eventually support `tailwinds` / `tailwinds-rn` as additional options.
+     */
+    defaultMethods?: "tachyons" | "none" | "tachyons-rn";
+    /**
+     * The target CSS runtime to generate for.
+     *
+     * - `"stylex"` (default): Generates a StyleX-friendly CssBuilder (for IDE autocomplete + types) plus a
+     *   `Css.json` mapping file consumed by the truss Vite plugin, which transforms
+     *   `Css.*.$` expressions into file-local `stylex.create()` + `stylex.props()` calls at build time.
+     * - `"react-native"`: Generates a runtime CssBuilder that accumulates plain style objects,
+     *   intended for React Native usage.
+     */
+    target?: "react-native" | "stylex";
+    /**
+     * The output path for the truss mapping file (only used when target is "stylex").
+     * Defaults to a `.json` sibling of `outputPath` (e.g. `./src/Css.json`).
+     */
+    mappingOutputPath?: string;
+    /**
+     * A map of "section" to list of rules to create application-specific
+     * utility methods.
+     *
+     * I.e. "borderColors" -> () => [`get ml1() { ... }`].
+     *
+     * This can be used to either add new sections or override built-in sections.
+     */
+    sections?: Sections;
+    /** Any extra chunks of code you want appended to the end of the file. */
+    extras?: Array<string | Code>;
+}
+/**
+ * A helper method to define config w/o a trailing cast.
+ *
+ * Based on `vite.config.ts`'s approach.
+ *
+ * We could eventually use this as a place to apply defaults, but currently
+ * just return the passed in `config` object as-is.
+ */
+declare function defineConfig(config: Config): Config;
+/**
+ * A function takes the project's `Config` and produces a list of utility methods to
+ * add to the generated `Css.ts` file.
+ *
+ * I.e. a return value might be:
+ *
+ * ```
+ *   [
+ *     "get mb0() { return this.mb(0); }",
+ *     "get mb1() { return this.mb(1); }",
+ *   ]
+ * ```
+ *
+ * See the `newMethod` and `newParamMethod` functions for more easily
+ * creating the `get ...() { ... }` output.
+ */
+type CreateMethodsFn = (config: Config) => UtilityMethod[];
+/**
+ * A type-alias to clarify strings that are meant to be abbreviation/utility names.
+ */
+type UtilityName = string;
+/**
+ * A type-alias to clarify which method returns types are utility methods.
+ *
+ * I.e. they should be a line of TypeScript code like `get abbr() { ... }`.
+ *
+ * See `newMethod` for a helper method to create the string.
+ */
+type UtilityMethod = string;
+/** A type-alias to clarify groups of utility methods. */
+type SectionName = string;
+/** A type-alias for a group of utility methods. */
+type Sections = Record<SectionName, CreateMethodsFn>;
+/** A type-alias for aliasing existing utility methods as a new utility method. */
+type Aliases = Record<UtilityName, UtilityName[]>;
+
+declare const defaultSections: {
+    readonly border: CreateMethodsFn;
+    readonly borderColor: CreateMethodsFn;
+    readonly borderRadius: CreateMethodsFn;
+    readonly borderStyle: CreateMethodsFn;
+    readonly borderWidth: CreateMethodsFn;
+    readonly boxShadow: CreateMethodsFn;
+    readonly container: CreateMethodsFn;
+    readonly coordinates: CreateMethodsFn;
+    readonly cursor: CreateMethodsFn;
+    readonly display: CreateMethodsFn;
+    readonly flexbox: CreateMethodsFn;
+    readonly float: CreateMethodsFn;
+    readonly fontWeight: CreateMethodsFn;
+    readonly grid: CreateMethodsFn;
+    readonly height: CreateMethodsFn;
+    readonly lineClamp: CreateMethodsFn;
+    readonly objectFit: CreateMethodsFn;
+    readonly opacity: CreateMethodsFn;
+    readonly outline: CreateMethodsFn;
+    readonly overflow: CreateMethodsFn;
+    readonly position: CreateMethodsFn;
+    readonly skins: CreateMethodsFn;
+    readonly spacing: CreateMethodsFn;
+    readonly textAlign: CreateMethodsFn;
+    readonly textDecoration: CreateMethodsFn;
+    readonly textTransform: CreateMethodsFn;
+    readonly typeScale: CreateMethodsFn;
+    readonly typography: CreateMethodsFn;
+    readonly userSelect: CreateMethodsFn;
+    readonly verticalAlign: CreateMethodsFn;
+    readonly visibility: CreateMethodsFn;
+    readonly whitespace: CreateMethodsFn;
+    readonly width: CreateMethodsFn;
+    readonly wordBreak: CreateMethodsFn;
+    readonly zIndex: CreateMethodsFn;
+};
+
+declare function generate(config: Config): Promise<void>;
+
+type Prop = keyof Properties;
+interface StylexEntry {
+    kind: "static" | "param" | "increment-param" | "px-delegate" | "alias" | "cssvar";
+    abbr: string;
+    /** For static: the CSS properties object, e.g. { display: "flex" } */
+    defs?: Record<string, unknown>;
+    /** For param/increment-param: the CSS property name(s) */
+    props?: string[];
+    /** For increment-param: whether to use maybeInc */
+    usesMaybeInc?: boolean;
+    /** For param methods: extra properties to set alongside the main prop */
+    extraDefs?: Record<string, unknown>;
+    /** For aliases: the list of chained abbreviations */
+    aliasTargets?: string[];
+}
+/** Start collecting StylexEntry metadata from method helpers. */
+declare function startStylexCollection(): void;
+/** Stop collecting and return all accumulated entries. */
+declare function stopStylexCollection(): StylexEntry[];
+/**
+ * Given a single abbreviation (i.e. `mt0`) and multiple `{ prop: value }` CSS values, returns
+ * the TypeScript code for a `mt0` utility method that sets those values.
+ */
+declare function newMethod(abbr: UtilityName, defs: Properties): UtilityMethod;
+/**
+ * Given a single abbreviation (i.e. `mt`) and a property name (i.e. `marginTop`), returns the
+ * TypeScript code for a `mt` utility method that accepts a user-provided value of the prop to set.
+ * Use `extraProperties` for additional properties to set.
+ *
+ * I.e. `Css.mt(someValue).$`
+ */
+declare function newParamMethod(abbr: UtilityName, prop: keyof Properties, extraProperties?: Properties): UtilityMethod;
+/**
+ * Given a prop to set (i.e. `marginTop`), and multiple abbr/value pairs (i.e. `{ mt0: "0px", mt1: "4px" }`),
+ * returns a utility method for each abbr/value pair.
+ *
+ * I.e. `mt0() { ...add("marginTop", "0px")... }`
+ *
+ * By default, we also generate a param method for `prop`, i.e. if `prop` is `marginTop`, we'll
+ * make a `marginTop(value)` method for users to pass variable values. You can change the
+ * name of this method by setting `baseName` or disable it completely by setting `baseName`
+ * to `null`.
+ *
+ * @param prop the CSS property we're setting, i.e. `marginTop`
+ * @param defs a map of abbreviation name --> value (a property value or an object of properties to set)
+ * @param baseName the base name to use, i.e. `mt`
+ * @param includePx generate an extra `${baseName}Px` method that calls the base method with a converted px value
+ * @param baseDefs additional properties to set for the base method
+ */
+declare function newMethodsForProp<P extends Prop>(prop: P, defs: Record<UtilityName, Properties[P] | Properties>, baseName?: string | null, includePx?: boolean, valueMethodExtraProperties?: Omit<Properties, P>): UtilityMethod[];
+/**
+ * Given aliases, i.e. `{ bodyText: ["f12", "bold"] }`, returns a utility method
+ * for each alias that calls its corresponding utility classes.
+ */
+declare function newAliasesMethods(aliases: Aliases): UtilityMethod[];
+/**
+ * Makes a utility method that can set CSS custom variables.
+ *
+ * I.e. `newSetCssVariableMethod("dark", { "--Primary": "white" })` will create a
+ * utility method `Css.dark.$ that will set `--Primary` to `white`.
+ *
+ * Currently, this only supports compile-time/hard-coded values. I.e. we don't support
+ * something like `Css.dark({ "--Primary", someRuntimeValue }).$` yet.
+ *
+ * TODO: Create a `Css.set(cssVars).$` method.
+ */
+declare function newSetCssVariablesMethod(abbr: UtilityName, defs: Record<string, string>): UtilityMethod;
+/** An abbreviation and its single or multiple CSS properties to set. */
+type IncConfig = [string, Prop | Prop[]];
+/**
+ * Makes [`mt0`, `mt1`, ...] utility methods for each configured increment
+ * to set `prop` to that given increment's value in pixels.
+ *
+ * I.e. we assume `prop` is a CSS property like `margin` that accepts pixels as values,
+ * and so convert each increment `x` (1, 2, 3) to pixels `Y` (8, 16, 24) and create
+ * a utility method for each `x -> Y` pair, i.e. `mt0 = mt(px(0))`.
+ *
+ * We also create a final param method, i.e. `mt(number)`, for callers that
+ * need to call `mt` with a conditional amount of increments.
+ *
+ * @param config the config
+ * @param abbr the utility prefix, i.e. `mt`
+ * @param props if a CSS prop like `marginTop`, we output "mt0 --> marginTop: 0px", if an array like
+ *   `["marginTop", "marginBottom"]`, we output "my0 --> marginTop: 0px, marginBottom: 0px"
+ * @param opts.auto if set to true, include an `a` suffix for auto values, i.e. `mta`
+ */
+declare function newIncrementMethods(config: Config, abbr: UtilityName, prop: Prop | Prop[], opts?: {
+    auto?: boolean;
+}): UtilityMethod[];
+/**
+ * Creates just the core `<abbr>X` utility methods that set `props` with each increment value.
+ *
+ * See `newIncrementMethods` for handling the `<abbr>Px`, `<abbr>a`, and `<attr>(value)` methods.
+ */
+declare function newCoreIncrementMethods(config: Config, abbr: UtilityName, props: Prop[]): UtilityMethod[];
+declare function newPxMethod(abbr: UtilityName, prop: Prop): UtilityMethod;
+
+export { type Aliases, type Config, type CreateMethodsFn, type FontConfig, type IncConfig, type SectionName, type Sections, type StylexEntry, type UtilityMethod, type UtilityName, defaultSections, defineConfig, generate, newAliasesMethods, newCoreIncrementMethods, newIncrementMethods, newMethod, newMethodsForProp, newParamMethod, newPxMethod, newSetCssVariablesMethod, startStylexCollection, stopStylexCollection };