@dosgato/templating 0.0.55 → 0.0.58

package/dist/component.d.ts

@@ -1,5 +1,7 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import type { IncomingHttpHeaders } from 'http';
+import type { ParsedUrlQuery } from 'querystring';
 import { ResourceProvider } from './provider.js';
 import { APIClient } from './render.js';
 /**
@@ -182,7 +184,7 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
     hadError: boolean;
     autoLabel: string;
     reqHeaders: IncomingHttpHeaders;
-    reqUrl: URL;
+    reqQuery: ParsedUrlQuery;
     /**
      * For logging errors during rendering without crashing the render. If your fetch, setContext,
      * render, or renderVariation functions throw, the error will be logged but the page render will

package/dist/provider.d.ts

@@ -1,19 +1,100 @@
 export interface CSSBlock {
+    /**
+     * The CSS as a string. Provide either this or `path`.
+     */
     css?: string;
+    /**
+     * A file path to the CSS. The rendering server will read the file on startup.
+     */
     path?: string;
+    /**
+     * This CSS is actually SASS and requires a compile. The rendering server will
+     * perform the compilation on startup.
+     */
+    sass?: boolean;
+    /**
+     * A version string following SEMVER. If multiple blocks are provided with the same name,
+     * the one with the highest version number will be chosen. If blocks of different major
+     * versions are provided, an alert will appear in the log.
+     */
     version?: string;
+    /**
+     * The CSS provided by this block applies to elements that are not on screen at
+     * page load, i.e. modals and dialogs.
+     *
+     * Setting it true will improve our time-to-first-paint, but any CSS that does
+     * apply to elements on screen at page load will cause a visible re-render that
+     * may disturb the user.
+     */
     async?: boolean;
 }
 export interface JSBlock {
+    /**
+     * The javascript as a string. Provide either this or `path`.
+     */
     js?: string;
+    /**
+     * A file path to the javascript. The rendering server will read the file on startup.
+     */
     path?: string;
+    /**
+     * A version string following SEMVER. If multiple blocks are provided with the same name,
+     * the one with the highest version number will be chosen. If blocks of different major
+     * versions are provided, an alert will appear in the log.
+     */
     version?: string;
+    /**
+     * The javascript provided by this block does not need to run before the DOM finishes
+     * loading. For instance, if the javascript only places event listeners and does not
+     * modify the DOM or create globals on first run, it is eligible for this flag.
+     *
+     * Setting it true will improve our time-to-first paint, but any DOM manipulations on
+     * first run will cause visible repaints that may disturb the user.
+     *
+     * Additionally, you cannot depend on load order of any async JS, so libraries like
+     * jquery that create globals intended for later use must be loaded synchronously
+     * (unless their dependents are smart enough to wait for the global to be defined).
+     */
     async?: boolean;
 }
 export interface FileDeclaration {
+    /**
+     * The path to the file.
+     */
     path: string;
+    /**
+     * A version string following SEMVER. If multiple files are provided with the same name,
+     * the one with the highest version number will be chosen.
+     */
+    version?: string;
+    /**
+     * The mime type of the file. If omitted, it will be automatically detected from the
+     * file data.
+     *
+     * If needed, you may also specify a non-default charset with e.g. `text/html; charset=ascii`
+     */
+    mime?: string;
+}
+export interface SCSSInclude {
+    /**
+     * The SASS code as a string. This SCSS should generally only include functions
+     * and mixins. Regular CSS should be included as its own block so it can be de-duplicated.
+     *
+     * Variables don't make much sense because we only have one version of a block every
+     * time it's used, whereas variables usually change from page template to page template.
+     * Use CSS variables instead.
+     */
+    scss?: string;
+    /**
+     * A file path to the SASS code.
+     */
+    path?: string;
+    /**
+     * A version string following SEMVER. If multiple blocks are provided with the same name,
+     * the one with the highest version number will be chosen. If blocks of different major
+     * versions are provided, an alert will appear in the log.
+     */
     version?: string;
-    mime: string;
 }
 /**
  * This class is a parent class for Component, but it can also be used as a standalone
@@ -46,6 +127,19 @@ export declare abstract class ResourceProvider {
      * and the user has clicked something.
      */
     static cssBlocks: Map<string, CSSBlock>;
+    /**
+     * A template can provide SASS mixins and functions for use by other SASS-based CSS
+     * blocks.
+     *
+     * These includes can be utilized by other SASS with the SASS `@use` and `@include`
+     * commands, e.g.
+     * ```
+     * @use 'my-mixin-name' as mx;
+     * .someclass { @include mx.somemixin(); }
+     * ```
+     * In this case `my-mixin-name` is the key used for this Map.
+     */
+    static scssIncludes: Map<string, SCSSInclude>;
     /**
      * Same as cssBlocks() but for javascript.
      *
@@ -80,7 +174,8 @@ export declare abstract class ResourceProvider {
     /**
      * Template code will need to generate HTML and CSS that points at the static files
      * provided above. In order to do so, we need information from the template registry (since
-     * we have to deduplicate with other registered templates at startup time).
+     * we have to deduplicate with other registered templates at startup time, and the structure
+     * of the webpath in general is the render server's concern).
      *
      * In order to avoid an ES6 dependency on the registry, we will have the registry write
      * back to this map as templates are registered.

package/dist/provider.js

@@ -32,6 +32,19 @@ export class ResourceProvider {
  * and the user has clicked something.
  */
 ResourceProvider.cssBlocks = new Map();
+/**
+ * A template can provide SASS mixins and functions for use by other SASS-based CSS
+ * blocks.
+ *
+ * These includes can be utilized by other SASS with the SASS `@use` and `@include`
+ * commands, e.g.
+ * ```
+ * @use 'my-mixin-name' as mx;
+ * .someclass { @include mx.somemixin(); }
+ * ```
+ * In this case `my-mixin-name` is the key used for this Map.
+ */
+ResourceProvider.scssIncludes = new Map();
 /**
  * Same as cssBlocks() but for javascript.
  *
@@ -66,7 +79,8 @@ ResourceProvider.files = new Map();
 /**
  * Template code will need to generate HTML and CSS that points at the static files
  * provided above. In order to do so, we need information from the template registry (since
- * we have to deduplicate with other registered templates at startup time).
+ * we have to deduplicate with other registered templates at startup time, and the structure
+ * of the webpath in general is the render server's concern).
  *
  * In order to avoid an ES6 dependency on the registry, we will have the registry write
  * back to this map as templates are registered.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dosgato/templating",
-  "version": "0.0.55",
+  "version": "0.0.58",
   "description": "A library to support building templates for dosgato CMS.",
   "type": "module",
   "exports": {