@m2c2kit/build-helpers 0.3.13 → 0.3.14

package/dist/index.d.ts

@@ -66,13 +66,21 @@ interface ExtraFile {
 }
 interface CopyAssetsOptions {
     /**
-     * Name of m2c2kit package or array of names of m2c2kit packages that need
-     * assets copied, e.g., `@m2c2kit/assessment-symbol-search` or
-     * `["@m2c2kit/assessment-symbol-search", "@m2c2kit/session"]`, or a
-     * PackageAndExtras object, e.g.,
-     * {name: "@m2c2kit/session", extras: [{ source: "assets/index.html*", dest: "" }]}
+     * For assets in an external m2c2kit package, the name of the m2c2kit package
+     * or array of names of m2c2kit packages that need assets copied, e.g.,
+     * `@m2c2kit/assessment-symbol-search` or
+     * `["@m2c2kit/assessment-symbol-search", "@m2c2kit/survey"]`, or a
+     * `PackageAndExtras` object, e.g.,
+     * `{name: "@m2c2kit/survey", extras: [{ source: "assets/index.html*", dest: "" }]}`
      */
-    package: string | PackageAndExtras | Array<string | PackageAndExtras>;
+    package?: string | PackageAndExtras | Array<string | PackageAndExtras>;
+    /**
+     * For assets within this package, the _id_ or _ids_ of the
+     * assessment(s) to copy assets for. If the assessment is not within this
+     * package, then the assessment _package name_ should be provided in the
+     * `package` option.
+     */
+    id?: string | Array<string>;
     /**
      * Output folder, e.g. `dist` or `build`.
      */
@@ -84,33 +92,71 @@ interface CopyAssetsOptions {
     verbose?: boolean;
 }
 /**
- * Copies assets from an m2c2kit package to the bundle output folder.
+ * Copies m2c2kit assets to the bundle output folder.
  *
  * @remarks Assets such as images, fonts, CSS, and WebAssembly files are
  * needed by assessments. This plugin copies those assets from their
- * respective packages to the output folder. What is copied depends on the
- * package that is specified.
- * - `@m2c2kit/session`: assets folder contents **except** `index.html`
- * - `@m2c2kit/db`: `data.js` and `data.html`
- * - `@m2c2kit/survey`: assets folder contents
- * - All other packages are assumed to be assessments, and their assets folder
- * **and** the wasm file from the required version of `@m2c2kit/core` are
- * copied. Note that the assessment's package name must be used, not its
- * m2c2kit game `id`.
+ * respective packages to the output folder.
+ *
+ * Packages and ids are assumed to be assessments (see exception below), and
+ * their assets folders **and** the wasm file from the required version of
+ * `@m2c2kit/core` are copied.
  *
  * At the end of the copy process, the `index.html` file from the `src` folder
- * is copied to the output folder. This `index.html` file will have been created
- * by the CLI or the user.
+ * is copied to the output folder. This `index.html` file will have been
+ * created by the CLI or the user.
+ *
+ * A typical use case: Here, there is a new assessment with the id
+ * `my-new-assessment` being developed in this package. In addition, two
+ * existing assessments, `@m2c2kit/assessment-symbol-search` and
+ * `@m2c2kit/assessment-grid-memory`, are being used.
+ *
+ * @example
+ * ```
+ * copyAssets({
+ *   id: "my-new-assessment",
+ *   package: [
+ *     "@m2c2kit/assessment-symbol-search",
+ *     "@m2c2kit/assessment-grid-memory"
+ *   ],
+ *  outputFolder: "dist",
+ * })
+ * ```
+ *
+ * Exception: if the `package` option is specified and it includes
+ * `@m2c2kit/db`, `@m2c2kit/survey`, or `@m2c2kit/session`, then the following
+ * assets are copied:
+ * - `@m2c2kit/db`: `data.js` and `data.html`
+ * - `@m2c2kit/survey`: assets css folder contents
+ * - `@m2c2kit/session`: assets folder contents, except `index.html`
+ *
+ * A typical use case: Here, in addition to assessments, a survey will be
+ * administered, and thus survey CSS assets are needed.
+ *
+ * @example
+ * ```
+ * copyAssets({
+ *   id: "my-new-assessment",
+ *   package: [
+ *     "@m2c2kit/assessment-symbol-search",
+ *     "@m2c2kit/assessment-grid-memory",
+ *     "@m2c2kit/survey"
+ *   ],
+ *  outputFolder: "dist",
+ * })
+ * ```
  *
  * If the `index.html` from `@m2c2kit/session` or `@m2c2kit/survey` is needed, it
  * can be added as an extra file to copy, but this will be done only in special
  * cases, such as when creating library demos within this repository.
  *
+ * This is a very atypical, unusual use case: Here, the `index.html` file from
+ * `@m2c2kit/survey` is copied to the output folder on every build.
+ *
  * @example
  * ```
  * copyAssets({
  *   package: [
- *     "@m2c2kit/session",
  *     "@m2c2kit/assessment-symbol-search",
  *     {
  *       name: "@m2c2kit/survey",
@@ -125,13 +171,13 @@ interface CopyAssetsOptions {
  * ```
  *
  * Usually, the `index.html` **should not** be copied from `@m2c2kit/session` or
- * `@m2c2kit/survey` on every build with the `extras` options because the
+ * `@m2c2kit/survey` on every build with the `extras` option because the
  * `index.html` file in the `src` folder should be used. Thus, the `extras`
  * option is only for special cases, such as when creating library demos within
  * this repository (see `@m2c2kit/assessments-demo`).
  *
  * @param options - {@link CopyAssetsOptions}
- * @returns
+ * @returns the copyAssets rollup plugin
  */
 declare function copyAssets(options: CopyAssetsOptions): Plugin;