feat: Provide ability to override concat settings.

- Useful for apps that need to set a particular order of concatenation
for CSS files in the final build artifact (for stuff such as, for
instance, reset stylesheets, which are lower priority than CSS Blocks.)

Author: Tim Lindvall

packages/@css-blocks/ember-app/src/index.ts

@@ -1,4 +1,4 @@
-import { CSSBlocksEmberOptions, ResolvedCSSBlocksEmberOptions, getConfig } from "@css-blocks/ember-utils";
+import { BroccoliConcatOptions, CSSBlocksEmberOptions, ResolvedCSSBlocksEmberOptions, getConfig } from "@css-blocks/ember-utils";
 import broccoliConcat = require("broccoli-concat");
 import BroccoliDebug = require("broccoli-debug");
 import funnel = require("broccoli-funnel");
@@ -198,23 +198,29 @@ const EMBER_ADDON: AddonImplementation<CSSBlocksApplicationAddon> = {
     let env = this.env!;
 
     if (type === "css") {
-      if (!env.isApp) {
+      if (!env.isApp || env.config.broccoliConcat === "SKIP") {
         return tree;
       }
-      // TODO: THIS IS WRONG - FIX THESE HARCODED PATHS THIS IS A BLOCKER AAAUGH
+
+      // Merge default concat options with the options provided by the app.
+      let concatOptions: BroccoliConcatOptions;
+      if (env.config.broccoliConcat) {
+        concatOptions = Object.assign(
+          {},
+          buildDefaultBroccoliConcatOptions(env),
+          env.config.broccoliConcat,
+        );
+      } else {
+        concatOptions = buildDefaultBroccoliConcatOptions(env);
+      }
+
+      // Create the concatenated file...
       const concatTree = broccoliConcat(
         tree,
-        {
-          inputFiles: ["assets/css-blocks.css", "assets/@css-blocks-fixtures-v2/ember-app.css"],
-          outputFile: "assets/@css-blocks-fixtures-v2/ember-app.css",
-          sourceMapConfig: {
-            enabled: true,
-            extensions: ["css"],
-            inline: true,
-            mapCommentType: "block",
-          },
-        },
+        concatOptions,
       );
+
+      // Then overwrite the original file with our final build artifact.
       const mergedTree = mergeTrees([tree, concatTree], { overwrite: true });
       return new BroccoliDebug(mergedTree, "css-blocks:css-postprocess");
     }
@@ -223,6 +229,24 @@ const EMBER_ADDON: AddonImplementation<CSSBlocksApplicationAddon> = {
   },
 };
 
+/**
+ * Build a default broccoli-concat config, using given enviroment settings.
+ * @param env - The addon environment.
+ * @returns - Default broccoli-concat options, accounting for current env settings.
+ */
+function buildDefaultBroccoliConcatOptions(env: AddonEnvironment): BroccoliConcatOptions {
+  return {
+    inputFiles: ["assets/css-blocks.css", `assets/${env.modulePrefix}.css`],
+    outputFile: `assets/${env.modulePrefix}.css`,
+    sourceMapConfig: {
+      enabled: true,
+      extensions: ["css"],
+      inline: true,
+      mapCommentType: "block",
+    },
+  };
+}
+
 type MaybeCSSBlocksTree = MaybeCSSBlocksTreePlugin | string;
 interface MaybeCSSBlocksTreePlugin {
   _inputNodes: Array<MaybeCSSBlocksTree> | undefined;

packages/@css-blocks/ember-utils/src/options.ts

@@ -5,12 +5,63 @@ import type { OptiCSSOptions } from "opticss";
 
 type Writeable<T> = { -readonly [P in keyof T]: T[P] };
 
+/**
+ * Sourcemap options provided by fast-sourcemap-concat, which is used
+ * by broccoli-concat to build sourcemaps. This is *not* an exhaustive
+ * list, so a catch-all is provided for undocumented props if needed.
+ */
+export interface BroccoliConcatSourcemapOptions {
+  enabled?: boolean;
+  extensions?: string[];
+  inline?: boolean;
+  mapCommentType?: "block" | "line";
+  [propName: string]: unknown;
+}
+
+/**
+ * Options provided by broccoli-concat, which the ember-app plugin uses
+ * to combine CSS files together during the post-process step. You can
+ * use these options to control the order in which files are concatenated,
+ * or other options related to concatenation.
+ */
+export interface BroccoliConcatOptions {
+  outputFile?: string;
+  header?: string;
+  headerFiles?: string[];
+  /**
+   * The files to contatenate together during the postprocess step. Do keep
+   * in mind this you'll have access only to the files in the CSS postprocess
+   * tree for ember-app. You can use globs if preferred.
+   *
+   * Any top-level files that are processed by Ember CLI will likely be stored
+   * at "styles/<name-of-file>.css". You can use a plugin such as broccoli-debug
+   * to determine the structure of your styles after processing.
+   *
+   * Your CSS Blocks file will be available by default
+   * at "styles/css-blocks.css", but will vary if the "output" property is set
+   * in your CSS Blocks options.
+   */
+  inputFiles?: string[];
+  footerFiles?: string[];
+  footer?: string;
+  sourceMapConfig?: BroccoliConcatSourcemapOptions;
+  allowNone?: boolean;
+}
+
 export interface CSSBlocksEmberOptions {
   output?: string;
   aliases?: ObjectDictionary<string>;
   analysisOpts?: AnalysisOptions;
   parserOpts?: Writeable<ParserOptions>;
   optimization?: Partial<OptiCSSOptions>;
+  /**
+   * Options that control the behavior of broccoli-concat, which is used
+   * to concatenate CSS files together by ember-app during postprocess.
+   * If this is set to "SKIP", broccoli-concat will *not* run.
+   * You'll need to add additional processing to add the CSS Blocks
+   * compiled content to your final CSS build artifact.
+   */
+  broccoliConcat?: BroccoliConcatOptions | "SKIP";
 }
 
 export interface ResolvedCSSBlocksEmberOptions {
@@ -19,12 +70,14 @@ export interface ResolvedCSSBlocksEmberOptions {
   analysisOpts: AnalysisOptions;
   parserOpts: ParserOptions;
   optimization: Partial<OptiCSSOptions>;
+  broccoliConcat: BroccoliConcatOptions | "SKIP";
 }
 
 export function getConfig(root: string, isProduction: boolean, options: CSSBlocksEmberOptions): ResolvedCSSBlocksEmberOptions {
   if (!options.aliases) options.aliases = {};
   if (!options.analysisOpts) options.analysisOpts = {};
   if (!options.optimization) options.optimization = {};
+  if (!options.broccoliConcat) options.broccoliConcat = {};
 
   if (!options.parserOpts) {
     options.parserOpts = config.searchSync(root) || {};