@terrazzo/plugin-css 2.0.0-alpha.7 → 2.0.0-beta.1

package/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Minor Changes
 
+- The `baseSelector`, `baseScheme`, and `modeSelectors` options are marked `@deprecated` for remove in 3.0. The new `permutations` API provides all functionality and then some, and should be migrated to as soon as possible.
+
 - [#530](https://github.com/terrazzoapp/terrazzo/pull/530) [`370ed7b`](https://github.com/terrazzoapp/terrazzo/commit/370ed7b0f578a64824124145d7f4936536b37bb3) Thanks [@drwpow](https://github.com/drwpow)! - ⚠️ Breaking change: lint on plugins no longer runs on individual files, rather, the full set once merged.
 
   If your lint plugin is not using the `src` context value, no changes are needed. If it is, you’ll need to instead read from the `sources` array, and look up sources with a token’s `source.loc` filename manually. This change was because lint rules now run on all files in one pass, essentially.
@@ -22,6 +24,12 @@
 
 - [#606](https://github.com/terrazzoapp/terrazzo/pull/606) [`1fc1d99`](https://github.com/terrazzoapp/terrazzo/commit/1fc1d99e7156923e86e872e4750b7e28b6292b20) Thanks [@yuheiy](https://github.com/yuheiy)! - Allow partial utility CSS groups configuration
 
+- [#632](https://github.com/terrazzoapp/terrazzo/pull/632) [`21c61d3`](https://github.com/terrazzoapp/terrazzo/commit/21c61d30c2cb137411deaec673d03cdc14445208) Thanks [@aduth](https://github.com/aduth)! - Fix `transform` option TypeScript type to allow `undefined` or `null` return values
+
+- [#636](https://github.com/terrazzoapp/terrazzo/pull/636) Thanks [@geebru](https://github.com/geebru)! - Add missing CSS logical property directions for utility class generation
+
+- Thanks [@drwpow](https://github.com/drwpow)! - Improve extended typography property CSS generation
+
 ## 0.10.4
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { BuildHookOptions, Plugin, TokenNormalized, TokenTransformed } from "@terrazzo/parser";
+import { BuildHookOptions, Logger, Plugin, TokenNormalized, TokenTransformed, TransformHookOptions } from "@terrazzo/parser";
 
 //#region src/lib.d.ts
 type UtilityCSSGroup = 'bg' | 'border' | 'font' | 'layout' | 'shadow' | 'text';
 type UtilityCSSPrefix = 'bg' | 'border' | 'font' | 'gap' | 'm' | 'p' | 'shadow' | 'text';
+declare const PLUGIN_NAME = "@terrazzo/plugin-css";
 declare const FORMAT_ID = "css";
 declare const FILE_PREFIX = "/* -------------------------------------------\n *  Autogenerated by \u26CB Terrazzo. DO NOT EDIT!\n * ------------------------------------------- */";
 interface CSSPluginOptions {
@@ -13,12 +14,33 @@ interface CSSPluginOptions {
   filename?: string;
   /** Glob patterns to exclude tokens from output */
   exclude?: string[];
-  /** Define mode selectors as media queries or CSS classes */
+  /**
+   * Set the base selector, like ":root" or ":host".
+   * @deprecated use permutations instead.
+   * @default ":root"
+   */
+  baseSelector?: string;
+  /**
+   * Set the color-scheme CSS property for `baseSelector`.
+   * @deprecated use permutations instead.
+   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme
+   * @example "light dark"
+   */
+  baseScheme?: string;
+  /**
+   * Build resolver contexts into media queries
+   */
+  permutations?: Permutation[];
+  /**
+   * Define mode selectors as media queries or CSS classes
+   * @deprecated Migrate to permutations
+   */
   modeSelectors?: ModeSelector[];
   /** Control the final CSS variable name */
   variableName?: (token: TokenNormalized) => string;
   /** Override certain token values */
-  transform?: (token: TokenNormalized, mode: string) => TokenTransformed['value'];
+  transform?: (token: TokenNormalized, /** @deprecated */
+  mode?: string) => TokenTransformed['value'] | undefined | null;
   /** Generate utility CSS from groups */
   utility?: Partial<Record<UtilityCSSGroup, string[]>>;
   /**
@@ -31,15 +53,14 @@ interface CSSPluginOptions {
    * @default false
    */
   skipBuild?: boolean;
-  /**
-   * Set the base selector, like ":root" or ":host".
-   * @default ":root"
-   */
-  baseSelector?: string;
-  /**
-   * Set the color-scheme CSS property for the base selector (e.g.: "light", "dark", "light dark")
-   */
-  baseScheme?: string;
+}
+interface Permutation<T extends Record<string, string> = Record<string, string>> {
+  /** Generate the final CSS string, wrapping content in the selector(s) of your choice. */
+  prepare(css: string): string;
+  /** Input for this permutation. */
+  input: T;
+  /** Provide token(s) to ignore (Note: ignoring tokens that are used as aliases for other tokens could cause visual bugs in generated CSS) */
+  ignore?: string[];
 }
 interface ModeSelector {
   /** The name of the mode to match */
@@ -51,34 +72,79 @@ interface ModeSelector {
   /** Set the color-scheme CSS property for this mode (e.g.: "light", "dark", "light dark") */
   scheme?: string;
 }
-interface CSSRuleDeclaration {
+interface CSSDeclaration {
+  type: 'Declaration';
+  property: string;
   value: string;
-  description?: string;
+  comment?: string;
 }
 interface CSSRule {
-  selectors: string[];
-  nestedQuery?: string;
-  declarations: Record<string, CSSRuleDeclaration>;
-}
-/** Convert CSSRules into a formatted, indented CSS string */
-declare function printRules(rules: CSSRule[]): string;
-interface GetRuleOptions {
-  /** Combine a selector with parent selectors (e.g. if adding a @media-query within another selector list) */
-  parentSelectors?: string[];
+  type: 'Rule';
+  prelude: string[];
+  children: (CSSRule | CSSDeclaration)[];
 }
+/**
+ * Convert CSSRules into a formatted, indented CSS string.
+ * The reason we’re using this homemade version instead of something like css-tree is:
+ *
+ * 1. css-tree doesn’t support comments :(
+ * 2. we are only generating PARTIALS, not full CSS (the user controls the
+ *    wrapper). So with a proper AST, we’d be hacking it a little anyway because
+ *    we never really have a true, valid, finalized document.
+ * 3. we want @terrazzo/plugin-css to run in the browser AND be lean (i.e. don’t
+ *    load Prettier or 25MB of wasm).
+ * 4. we only have to deal with a small subset of CSS—this doesn’t have to be robust
+ *    by any means (even future additions won’t push the limits of the spec).
+ */
+declare function printRules(nodes: (CSSRule | CSSDeclaration)[], {
+  indentChar,
+  indentLv
+}?: {
+  indentChar?: string;
+  indentLv?: number;
+}): string;
+/** Internal printer for individual nodes */
+declare function printNode(node: CSSRule | CSSDeclaration, {
+  indentChar,
+  indentLv
+}: {
+  indentChar: string;
+  indentLv: number;
+}): string;
+/** Infer indentation preferences from a user-defined wrapping method. */
+declare function getIndentFromPrepare(prepare: (css: string) => string): {
+  indentChar: string;
+  indentLv: number;
+};
+/** Syntactic sugar over Rule boilerplate */
+declare function rule(prelude: CSSRule['prelude'], children?: CSSRule['children']): CSSRule;
+/** Syntactic sugar over Declaration boilerplate */
+declare function decl(property: CSSDeclaration['property'], value: CSSDeclaration['value'], comment?: CSSDeclaration['comment']): CSSDeclaration;
+/** Does a node list contain a root-level declaration with this property? */
+declare function hasDecl(list: (CSSRule | CSSDeclaration)[], property: string): boolean;
+/** Add a declaration only if it’s unique (note: CSS, by design, allows duplication—it’s how fallbacks happen. Only use this if fallbacks aren’t needed. */
+declare function addDeclUnique(list: (CSSRule | CSSDeclaration)[], declaration: CSSDeclaration): void;
 //#endregion
-//#region src/build/index.d.ts
+//#region src/build.d.ts
 interface BuildFormatOptions {
+  logger: Logger;
   exclude: CSSPluginOptions['exclude'];
   getTransforms: BuildHookOptions['getTransforms'];
   modeSelectors: CSSPluginOptions['modeSelectors'];
+  permutations: CSSPluginOptions['permutations'];
   utility: CSSPluginOptions['utility'];
   baseSelector: string;
   baseScheme: CSSPluginOptions['baseScheme'];
 }
 //#endregion
+//#region src/transform.d.ts
+interface TransformOptions {
+  transform: TransformHookOptions;
+  options: CSSPluginOptions;
+}
+//#endregion
 //#region src/index.d.ts
 declare function cssPlugin(options?: CSSPluginOptions): Plugin;
 //#endregion
-export { BuildFormatOptions, CSSPluginOptions, CSSRule, CSSRuleDeclaration, FILE_PREFIX, FORMAT_ID, GetRuleOptions, ModeSelector, UtilityCSSGroup, UtilityCSSPrefix, cssPlugin as default, printRules };
+export { BuildFormatOptions, CSSDeclaration, CSSPluginOptions, CSSRule, FILE_PREFIX, FORMAT_ID, ModeSelector, PLUGIN_NAME, Permutation, TransformOptions, UtilityCSSGroup, UtilityCSSPrefix, addDeclUnique, decl, cssPlugin as default, getIndentFromPrepare, hasDecl, printNode, printRules, rule };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/lib.ts","../src/build/index.ts","../src/index.ts"],"sourcesContent":[],"mappings":";;;KAEY,eAAA;KAEA,gBAAA;AAFA,cAIC,SAAA,GAJc,KAAA;AAEf,cAIC,WAAA,GAJe,uJAAA;AAEf,UAMI,gBAAA,CANK;EAET;AAIb;;;EAasB,QAAA,CAAA,EAAA,MAAA;EAAkC;EAE7B,OAAA,CAAA,EAAA,MAAA,EAAA;EAAP;EAAR,aAAA,CAAA,EANM,YAMN,EAAA;EAAO;EAsBF,YAAA,CAAA,EAAY,CAAA,KAAA,EA1BJ,eA0BI,EAAA,GAAA,MAAA;EAcZ;EAIA,SAAA,CAAO,EAAA,CAAA,KAAA,EA1CF,eA6CS,EAAA,IAAA,EAAf,MAAM,EAAA,GA7CkC,gBA6ClC,CAAA,OAAA,CAAA;EAIN;EAkEC,OAAA,CAAA,EAjHL,OAiHmB,CAjHX,MAiHW,CAjHJ,eAiHI,EAAA,MAAA,EAAA,CAAA,CAAA;;;;ACnI/B;EACW,SAAA,CAAA,EAAA,OAAA;EACM;;;;EAIa,SAAA,CAAA,EAAA,OAAA;;;;ACRL;;;;;;;UF0CR,YAAA;;;;;;;;;;UAcA,kBAAA;;;;UAIA,OAAA;;;gBAGD,eAAe;;;iBAIf,UAAA,QAAkB;UAkEjB,cAAA;;;;;;UCnIA,kBAAA;EDPL,OAAA,ECQD,gBDRgB,CAAA,SAAA,CAAA;EAEf,aAAA,ECOK,gBDPW,CAAA,eAAA,CAAA;EAEf,aAAS,ECML,gBDNK,CAAA,eAAA,CAAA;EAET,OAAA,ECKF,gBDLa,CAAA,SAAA,CAAA;EAIP,YAAA,EAAA,MAAgB;EASf,UAAA,ECNJ,gBDMI,CAAA,YAAA,CAAA;;;;AAjBN,iBEKY,SAAA,CFLI,OAAA,CAAA,EEKgB,gBFLhB,CAAA,EEKmC,MFLnC"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/lib.ts","../src/build.ts","../src/transform.ts","../src/index.ts"],"sourcesContent":[],"mappings":";;;KAEY,eAAA;KAEA,gBAAA;AAFA,cAIC,WAAA,GAJc,sBAAA;AAEf,cAIC,SAAA,GAJe,KAAA;AAEf,cAIA,WAAA,GAJW,uJAAA;AAEX,UAMI,gBAAA,CANK;EAET;AAIb;;;EA+ByB,QAAA,CAAA,EAAA,MAAA;EAGd;EAGJ,OAAA,CAAA,EAAA,MAAA,EAAA;EAEoB;;;;AAa3B;EAAuC,YAAA,CAAA,EAAA,MAAA;EAAyB;;;AAShE;AAYA;AAOA;EAmBgB,UAAA,CAAA,EAAU,MAAA;EAChB;;;EACa,YAAA,CAAA,EA7EN,WA6EM,EAAA;EAAY;AAanC;;;EAEI,aAAA,CAAA,EAvFc,YAuFd,EAAA;EAAY;EAAQ,YAAA,CAAA,EAAA,CAAA,KAAA,EArFC,eAqFD,EAAA,GAAA,MAAA;EAgDR;EA2BA,SAAI,CAAA,EAAA,CAAA,KAAA,EA7JT,eA6JS,EAAU;EAA8B,IAAA,CAAA,EAAA,MAAA,EAAA,GA1JrD,gBA0JqD,CAAA,OAAA,CAAA,GAAA,SAAA,GAAA,IAAA;EAA2B;EAAO,OAAA,CAAA,EAxJlF,OAwJkF,CAxJ1E,MAwJ0E,CAxJnE,eAwJmE,EAAA,MAAA,EAAA,CAAA,CAAA;EAK9E;;;;EAIb,SAAA,CAAA,EAAA,OAAA;EAAc;AAKjB;AAKA;;EAA+C,SAAA,CAAA,EAAA,OAAA;;AAA8C,UA9J5E,WA8J4E,CAAA,UA9JtD,MA8JsD,CAAA,MAAA,EAAA,MAAA,CAAA,GA9J7B,MA8J6B,CAAA,MAAA,EAAA,MAAA,CAAA,CAAA,CAAA;;;;EC5M5E,KAAA,EDkDR,CClDQ;EACP;EACC,MAAA,CAAA,EAAA,MAAA,EAAA;;AAEM,UDmDA,YAAA,CCnDA;EACD;EACL,IAAA,EAAA,MAAA;EAEG;EAAgB,MAAA,CAAA,EAAA,MAAA,EAAA;;;;ECvBb,MAAA,CAAA,EAAA,MAAA;;UFkFA,cAAA;;EG7EO,QAAA,EAAA,MAAS;;;;UHoFhB,OAAA;;;aAGJ,UAAU;;;;;;;;;;;;;;;iBAgBP,UAAA,SACN,UAAU;;;;;;;;iBAcJ,SAAA,OACR,UAAU;;;;;;;;iBAiDF,oBAAA;;;;;iBA2BA,IAAA,UAAc,+BAA8B,sBAA2B;;iBAKvE,IAAA,WACJ,mCACH,mCACG,4BACT;;iBAKa,OAAA,QAAe,UAAU;;iBAKzB,aAAA,QAAqB,UAAU,gCAAgC;;;UC5M9D,kBAAA;EDlBL,MAAA,ECmBF,MDnBE;EAEA,OAAA,ECkBD,gBDlBiB,CAAA,SAAA,CAAA;EAEf,aAAA,ECiBI,gBDjBO,CAAA,eAAA,CAAA;EAEX,aAAS,ECgBL,gBDhBK,CAAA,eAAA,CAAA;EAET,YAAA,ECeG,gBDfQ,CAAA,cAAA,CAAA;EAIP,OAAA,ECYN,gBDZsB,CAAA,SAAA,CAAA;EAwBhB,YAAA,EAAA,MAAA;EAKC,UAAA,ECfJ,gBDeI,CAAA,YAAA,CAAA;;;;UEtCD,gBAAA;EFHL,SAAA,EEIC,oBFJc;EAEf,OAAA,EEGD,gBFHiB;AAE5B;;;AAEa,iBGEW,SAAA,CHFF,OAAA,CAAA,EGEsB,gBHFtB,CAAA,EGEyC,MHFzC"}