shelving
Version:
Toolkit for using data in JavaScript.
100 lines (99 loc) • 5.56 kB
TypeScript
import type { ImmutableArray } from "../../util/array.js";
import { type ImmutableDictionary } from "../../util/dictionary.js";
import type { AnyCaller } from "../../util/function.js";
import { type PossibleLink } from "../../util/link.js";
import type { Nullish } from "../../util/null.js";
import { type ImmutableURI, type PossibleURI, type PossibleURIParams } from "../../util/uri.js";
import { type ImmutableURL, type PossibleURL } from "../../util/url.js";
/** Set of named meta `<meta />` tags in `{ name: content }` format. */
export type MetaTags = ImmutableDictionary<string | boolean | null | undefined>;
/** Set of named meta `<link />` tags in `{ rel: href }` format. */
export type MetaLinks = ImmutableDictionary<ImmutableURI>;
/** Set of named meta `<link />` tags in `{ rel: href }` format. */
export type PossibleMetaLinks = ImmutableDictionary<Nullish<PossibleLink>>;
/** Set of linked assets in `(href)[]` format. */
export type MetaAssets = ImmutableArray<ImmutableURI>;
/** Set of linked assets in `(href)[]` format. */
export type PossibleMetaAssets = ImmutableArray<Nullish<PossibleLink>>;
/** Type for a meta `Content-Security-Policy` tag in `{ resource: string[] }` format. */
export type MetaCSP = {
readonly [resource: string]: string[];
};
/** Combined meta data for a website page. */
export interface Meta {
/** Base URL for the app (used to resolve `url` and set as `<base>` tag in `<Head>`). */
readonly root?: ImmutableURL | undefined;
/** URL of the current page (used to update history API and as the initial URL for routing). */
readonly url?: ImmutableURL | undefined;
/** Title of the entire application. */
readonly app?: string | undefined;
/** Title of the current page (set as `<title>` in `<Head>` */
readonly title?: string | undefined;
/** Description of the current page. */
readonly description?: string | undefined;
readonly image?: string | undefined;
/** Language code (used for `lang` tag in HTML). */
readonly language?: string | undefined;
readonly csp?: MetaCSP | undefined;
readonly tags?: MetaTags | undefined;
readonly links?: MetaLinks | undefined;
readonly modules?: MetaAssets | undefined;
readonly scripts?: MetaAssets | undefined;
readonly stylesheets?: MetaAssets | undefined;
}
/** Input metadata that can be parsed and converted to proper metadata. */
export interface PossibleMeta extends Omit<Meta, "root" | "url" | "links" | "scripts" | "modules" | "stylesheets"> {
/** Base URL for the app — accepts a string or `URL`, resolved with `requireURL()`. */
readonly root?: PossibleURL | undefined;
/**
* New URL for the page.
* - Resolved using `requireURL()` if set relative to `root`
*/
readonly url?: PossibleURI | undefined;
/**
* Set the params in the URL (not merged with existing params).
* - Added to `url` after it is resolved.
* - Baseically
*/
readonly params?: PossibleURIParams | undefined;
readonly links?: PossibleMetaLinks | undefined;
readonly modules?: PossibleMetaAssets | undefined;
readonly scripts?: PossibleMetaAssets | undefined;
readonly stylesheets?: PossibleMetaAssets | undefined;
}
/** Turn a deconstructed CSP into a string. */
export declare function joinMetaCSP(csp: Nullish<MetaCSP>): string | undefined;
/** Merge two page or site titles together, e.g. `Manchester Runners` + `Messages` becomes `Messages - Manchester Runners` */
export declare function joinTitles(...titles: (string | undefined)[]): string;
/**
* Merge two `MetaData` objects.
* - `title` is merged.
* - `URL` is resolved to an absolute URL, e.g. `./d/e/f` + `/a/b/c` becomes `https://d.com/a/b/c/d/e/f`
* - `stylesheets` and `links` hrefs newly set in `meta2` are absolutified against the merged `url`/`base`, so they stay correct no matter where they are later rendered.
*/
export declare function mergeMeta(meta1: Meta, meta2: PossibleMeta, caller?: AnyCaller): Meta;
/**
* Create a fully-formed `Meta` from a `PossibleMeta`.
* - Like `mergeMeta()` but with no previous `Meta` to merge into — initialises meta from scratch.
*/
export declare function createMeta(meta: PossibleMeta, caller?: AnyCaller): Meta;
/**
* Merge two metadata URLs.
* - New URL is resolved relative to: current URL, new base URL, current base URL
*/
export declare function mergeMetaURL(base: ImmutableURL | undefined, current: ImmutableURL | undefined, next: PossibleURL | undefined, params: PossibleURIParams | undefined, caller?: AnyCaller): ImmutableURL | undefined;
/**
* Merge two metadata tags.
* - New assets are resolved relative to current URL (relative paths) and root URL (absolute paths).
*/
export declare function mergeMetaTags(current: MetaTags | undefined, next: MetaTags | undefined): MetaTags | undefined;
/**
* Merge two metadata link lists.
* - New assets are resolved relative to current URL (relative paths) and root URL (absolute paths).
*/
export declare function mergeMetaLinks(current: MetaLinks | undefined, next: PossibleMetaLinks | undefined, url: ImmutableURL | undefined, root: ImmutableURL | undefined, caller?: AnyCaller): MetaLinks | undefined;
/**
* Merge two metadata asset lists.
* - New assets are resolved relative to current URL (relative paths) and root URL (absolute paths).
*/
export declare function mergeMetaAssets(current: MetaAssets | undefined, next: PossibleMetaAssets | undefined, url: ImmutableURL | undefined, root: ImmutableURL | undefined, caller?: AnyCaller): MetaAssets | undefined;