@dosgato/templating 0.0.54 → 0.0.57

package/dist/component.d.ts

@@ -1,3 +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';
 /**
@@ -179,8 +183,8 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
     renderedAreas: Map<string, RenderedComponent[]>;
     hadError: boolean;
     autoLabel: string;
-    reqHeaders: Headers;
-    reqUrl: URL;
+    reqHeaders: IncomingHttpHeaders;
+    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
@@ -249,7 +253,7 @@ export declare abstract class Page<DataType extends PageData = any, FetchedType
      * This method will be provided to page templates by the render server. You may call it
      * at any time during fetch, context, or render, to set an HTTP header on the response
      */
-    addHeader: (key: string, value: string) => void;
+    addHeader: (key: string, value: string | undefined) => void;
     protected passError(e: Error, path: string): void;
     constructor(page: PageRecord<DataType>, editMode: boolean);
 }

package/dist/provider.d.ts

@@ -1,19 +1,79 @@
 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;
-    mime: 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;
 }
 /**
  * This class is a parent class for Component, but it can also be used as a standalone
@@ -80,7 +140,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

@@ -66,7 +66,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.54",
+  "version": "0.0.57",
   "description": "A library to support building templates for dosgato CMS.",
   "type": "module",
   "exports": {
@@ -18,6 +18,7 @@
     "txstate-utils": "^1.7.4"
   },
   "devDependencies": {
+    "@types/node": "^18.7.11",
     "eslint-config-standard-with-typescript": "^22.0.0",
     "typescript": "^4.4.2"
   },