book-cover-generator 1.9.1 → 1.9.2

package/README.md

@@ -191,25 +191,25 @@ Returns the SVG markup.
 
 Same as `generateCover`, but also tells you which style and palette were chosen. This is useful when either one was random. `body` is the markup inside the outer `<svg>`, for nesting the cover in a larger SVG (its ids are unique to the cover, so several can share a document).
 
-| option      | type               | default                | notes                                             |
-| ----------- | ------------------ | ---------------------- | ------------------------------------------------- |
-| `title`     | `string`           | `'Untitled'`           | a line break (`\n`) breaks the title's line there |
-| `author`    | `string`           | `''`                   | optional                                          |
-| `subtitle`  | `string`           | `''`                   | optional subtitle or tagline                      |
-| `series`    | `string`           | `''`                   | a series line above the title                     |
-| `credit`    | `string`           | `''`                   | a credit under the subtitle ("Translated by…")    |
-| `badge`     | `string`           | `''`                   | a seal in a corner clear of the text              |
-| `texture`   | `boolean`          | `false`                | adds a fine film grain                            |
-| `style`     | `string`           | `'random'`             | a style id, see `styles`                          |
-| `palette`   | `string \| object` | `'random'`             | a palette id, or `{ bg, ink, accents: [...] }`    |
-| `seed`      | `string \| number` | hash of title + author | controls every random choice                      |
-| `width`     | `number`           | `600`                  | px, 50–10000; aspect ratio 1:3 to 3:1             |
-| `height`    | `number`           | `width × 1.5`          | px, 50–10000                                      |
-| `lang`      | `string`           | inferred               | language of the text, such as `'ja'`              |
-| `variants`  | `object`           | `{}`                   | pin a style's choices: `{ scene: 'forest' }`      |
-| `genre`     | `string`           |                        | with a random style, one that suits this genre    |
-| `font`      | `string`           | the style's            | the title's font, one of `FONTS`                  |
-| `titleCase` | `string`           | the style's            | `'upper'` (capitals) or `'normal'` (as typed)     |
+| option      | type               | default              | notes                                             |
+| ----------- | ------------------ | -------------------- | ------------------------------------------------- |
+| `title`     | `string`           | `'Untitled'`         | a line break (`\n`) breaks the title's line there |
+| `author`    | `string`           | `''`                 | optional                                          |
+| `subtitle`  | `string`           | `''`                 | optional subtitle or tagline                      |
+| `series`    | `string`           | `''`                 | a series line above the title                     |
+| `credit`    | `string`           | `''`                 | a credit under the subtitle ("Translated by…")    |
+| `badge`     | `string`           | `''`                 | a seal in a corner clear of the text              |
+| `texture`   | `boolean`          | `false`              | adds a fine film grain (any truthy value)         |
+| `style`     | `string`           | `'random'`           | a style id, see `styles`                          |
+| `palette`   | `string \| object` | `'random'`           | a palette id, or `{ bg, ink, accents: [...] }`    |
+| `seed`      | `string \| number` | the title and author | controls every random choice                      |
+| `width`     | `number`           | `600`                | px, 50–10000; aspect ratio 1:3 to 3:1             |
+| `height`    | `number`           | `width × 1.5`        | px, 50–10000                                      |
+| `lang`      | `string`           | inferred             | language of the text, such as `'ja'`              |
+| `variants`  | `object`           | `{}`                 | pin a style's choices: `{ scene: 'forest' }`      |
+| `genre`     | `string`           |                      | with a random style, one that suits this genre    |
+| `font`      | `string`           | the style's          | the title's font, one of `FONTS`                  |
+| `titleCase` | `string`           | the style's          | `'upper'` (capitals) or `'normal'` (as typed)     |
 
 Styles, palettes, genres and fonts may be given by id or by name, in any case: `'artdeco'`, `'Art Deco'` and `'ART DECO'` are the same style, and a book list or a link can name them as the app's menus do.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "book-cover-generator",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "Generate SVG book covers from a title and an author. 39 styles, 28 palettes, seeded randomizer, zero dependencies.",
   "keywords": [
     "book",

package/src/browser.d.ts

@@ -1,7 +1,27 @@
+/**
+ * Browser helpers to export a cover: rasterise it to PNG, JPEG or WebP, download it, copy it to the
+ * clipboard, or zip several files. `setDpi` and `zipFiles` also work in Node.
+ *
+ * ```js
+ * import { createCover } from '@otsirh/book-cover-generator';
+ * import { downloadCover, rasterize } from '@otsirh/book-cover-generator/browser';
+ *
+ * const { svg } = createCover({ title: 'Dune', author: 'Frank Herbert' });
+ * await downloadCover(svg, 'png', 'dune', { scale: 3, dpi: 300 }); // dune.png, 1800 × 2700 px
+ * const blob = await rasterize(svg, { type: 'image/webp', width: 1600 }); // 1600 × 2400 px
+ * ```
+ *
+ * @module
+ */
+
+/** SVG markup as a `data:` URL, for an `<img>`'s `src`. */
 export declare function svgToDataUrl(svg: string): string;
+/** SVG markup as a Blob of type `image/svg+xml;charset=utf-8`. */
 export declare function svgToBlob(svg: string): Blob;
 
+/** Options for `rasterize`. */
 export interface RasterizeOptions {
+  /** The image's type. Default `'image/png'`; a browser that can't encode it makes a PNG. */
   type?: 'image/png' | 'image/jpeg' | 'image/webp';
   /** Multiplier applied to the SVG's width and height. Default 1. Ignored when `width` or `height` is given. */
   scale?: number;
@@ -22,6 +42,7 @@ export declare function rasterize(svg: string, opts?: RasterizeOptions): Promise
 /** Trigger a file download for a Blob. */
 export declare function downloadBlob(blob: Blob, filename: string): void;
 
+/** The formats `downloadCover` makes: the SVG itself, or a PNG, JPEG (`'jpeg'` or `'jpg'`) or WebP image. */
 export type ExportFormat = 'svg' | 'png' | 'jpeg' | 'jpg' | 'webp';
 /**
  * Download a cover; `basename` gets the right extension appended. Resolves to the file name,

package/src/core.d.ts

@@ -1,3 +1,9 @@
+/**
+ * The SVG, colour and noise helpers the built-in styles use, exported as `svgUtils`.
+ *
+ * @module
+ */
+
 /** Seeded pseudo-random number generator. */
 export interface Rng {
   /** Next float in `[0, 1)`. */
@@ -8,20 +14,32 @@ export interface Rng {
   int(min: number, max: number): number;
   /** `true` with probability `p`. */
   bool(p?: number): boolean;
+  /** One of `arr`'s items, at random (undefined for an empty array). */
   pick<T>(arr: readonly T[]): T;
   /** A shuffled copy. */
   shuffle<T>(arr: readonly T[]): T[];
 }
 
+/** A 32-bit hash of `String(input)` (cyrb53, folded to 32 bits), as an unsigned integer. */
 export declare function hashString(input: unknown): number;
+/**
+ * A seeded random number generator (mulberry32). The seed is hashed as a string, so the same seed
+ * (42 or '42') always gives the same numbers.
+ */
 export declare function createRng(seed: unknown): Rng;
 
+/** `v` kept within `lo`–`hi`. */
 export declare function clamp(v: number, lo: number, hi: number): number;
+/** Linear interpolation: `a` at `t = 0`, `b` at `t = 1` (`t` isn't clamped). */
 export declare function lerp(a: number, b: number, t: number): number;
+/** 0 at `e0` and below, 1 at `e1` and above, and a smooth S-curve in between. */
 export declare function smoothstep(e0: number, e1: number, x: number): number;
 
+/** Whether `v` is a hex colour string, `#rgb` or `#rrggbb` in any case (spaces at either end allowed). */
 export declare function isHex(v: unknown): boolean;
+/** A hex colour (`#rgb` or `#rrggbb`) as `[r, g, b]`, each 0–255. It isn't checked: see `isHex`. */
 export declare function hexToRgb(hex: string): [number, number, number];
+/** `[r, g, b]` as `#rrggbb`; each channel is rounded and clamped to 0–255. */
 export declare function rgbToHex(rgb: readonly number[]): string;
 /** Linear blend of two hex colours; `t = 0` is `a`, `t = 1` is `b`. */
 export declare function mix(a: string, b: string, t: number): string;
@@ -36,19 +54,42 @@ export declare function inkCandidates(p: { readonly ink: string; readonly bg: st
 /** Best text colour on `bg`: the palette's ink or background, or white / near-black. */
 export declare function inkOn(bg: string, p: { readonly ink: string; readonly bg: string }): string;
 
+/** A 2D noise function: a value between -1 and 1 for each point. */
 export type Noise2D = (x: number, y: number) => number;
+/** Smooth 2D value noise from `rng`: values between -1 and 1, changing over about one unit. */
 export declare function makeNoise2D(rng: Rng): Noise2D;
+/**
+ * Fractal noise at (x, y): `octaves` layers of `noise` (default 4), each at twice the frequency and
+ * half the weight of the one before, averaged by weight so it stays in the range of `noise`.
+ */
 export declare function fbm(noise: Noise2D, x: number, y: number, octaves?: number): number;
 /** Midpoint-displacement ridge line with values in `[-1, 1]`. */
 export declare function ridge(rng: Rng, segments?: number, roughness?: number): number[];
 
 /** Round to one decimal place. */
 export declare function n(v: number): number;
+/**
+ * `String(str)` without the characters XML 1.0 forbids: control characters other than tab, LF and
+ * CR, U+FFFE, U+FFFF and lone surrogates.
+ */
 export declare function stripInvalidXml(str: unknown): string;
+/**
+ * `String(str)` made safe for SVG text and attribute values: the characters XML forbids dropped, and
+ * `& < > " '` escaped.
+ */
 export declare function escapeXml(str: unknown): string;
 
+/** A `<rect>`. Numbers are rounded to one decimal; `fill` and `extra` (raw attributes) are written as given. */
 export declare function rect(x: number, y: number, w: number, h: number, fill: string, extra?: string): string;
+/**
+ * A `<circle>` (a negative radius is drawn as 0). Numbers are rounded to one decimal; `fill` and
+ * `extra` are written as given.
+ */
 export declare function circle(cx: number, cy: number, r: number, fill: string, extra?: string): string;
+/**
+ * A `<line>` with a stroke `width` px wide. Numbers are rounded to one decimal; `stroke` and
+ * `extra` are written as given.
+ */
 export declare function line(
   x1: number,
   y1: number,
@@ -60,39 +101,67 @@ export declare function line(
 ): string;
 /** `[[x, y], ...]` to a path `d` string. */
 export declare function pathD(points: ReadonlyArray<readonly number[]>, close?: boolean): string;
+/** A `<path>`; `d`, `fill` and `extra` (raw attributes) are written as given. */
 export declare function path(d: string, fill: string, extra?: string): string;
 /** Path for a quarter disc filling the square (x, y, size), centred on its bottom-left corner. */
 export declare function quarterDisc(x: number, y: number, size: number): string;
 /** Path for a half disc standing on the bottom edge of the square (x, y, size). */
 export declare function halfDisc(x: number, y: number, size: number): string;
 
+/** Options for `grain`. */
 export interface GrainOptions {
+  /** The layer's opacity, 0–1. Default 0.12. */
   opacity?: number;
+  /** White specks instead of black. Default `false`. */
   light?: boolean;
+  /**
+   * The noise's base frequency for a short side of 600 px (it is divided by `u`, so the grain
+   * scales with the cover). Default 0.75.
+   */
   freq?: number;
   /** Filter id suffix, when a cover needs more than one grain filter. Default `'grain'`. */
   id?: string;
   /** Noise seed, so two grain layers don't line up. Default 0. */
   seed?: number;
 }
+/**
+ * A film-grain overlay: a `<filter>` for the cover's `<defs>` (`defs`), and a rectangle the size
+ * of the cover drawn with it (`layer`). `c` is the style's context.
+ */
 export declare function grain(
   c: { id(name: string): string; readonly u: number; readonly W: number; readonly H: number },
   opts?: GrainOptions,
 ): { defs: string; layer: string };
+/**
+ * A soft drop-shadow `<filter>` with this id: the shape over its shadow, blurred by `blur` (a
+ * standard deviation) and moved down by `dy`, both times `u`, at `opacity` (defaults 4, 2 and 0.35).
+ */
 export declare function shadowFilter(
   id: string,
   u: number,
   opts?: { blur?: number; dy?: number; opacity?: number },
 ): string;
+/**
+ * A Gaussian-blur `<filter>` with this id and standard deviation `std` (px), with room around the
+ * shape for the blur.
+ */
 export declare function blurFilter(id: string, std: number): string;
 
 /** `[offset 0–1, colour, opacity?]` */
 export type GradientStop = readonly [offset: number, color: string, opacity?: number];
+/**
+ * A `<linearGradient>` with this id. The vector is in fractions of the shape's box: top to bottom
+ * by default (`x1` 0, `y1` 0, `x2` 0, `y2` 1).
+ */
 export declare function linearGradient(
   id: string,
   stops: readonly GradientStop[],
   vector?: { x1?: number; y1?: number; x2?: number; y2?: number },
 ): string;
+/**
+ * A `<radialGradient>` with this id: centre (`cx`, `cy`) and radius `r` in fractions of the
+ * shape's box (0.5 each by default), and the focal point (`fx`, `fy`) if given.
+ */
 export declare function radialGradient(
   id: string,
   stops: readonly GradientStop[],

package/src/element-types.d.ts

@@ -1,16 +1,38 @@
+/**
+ * `<book-cover>`: a cover on any page, drawn from the element's attributes. Importing this module
+ * defines the element (outside a browser, such as in Node, it loads and defines nothing). See
+ * `BookCover` for its attributes and events.
+ *
+ * ```html
+ * <script type="module" src="https://covers.otsirh.dev/src/element.js"></script>
+ *
+ * <book-cover cover-title="Dune" author="Frank Herbert" cover-style="retro"></book-cover>
+ * <!-- drawn once it comes near the viewport, as a lazy image is -->
+ * <book-cover cover-title="Emma" author="Jane Austen" loading="lazy"></book-cover>
+ * ```
+ *
+ * ```js
+ * // Or from a module (Deno, or a bundler):
+ * import '@otsirh/book-cover-generator/element';
+ * ```
+ *
+ * @module
+ */
+
 import type { CoverOptions, createCover } from './index.js';
 
+// (The class alone: Deno and JSR use these types, as a package there may not declare global ones.
+// element.d.ts adds the tag to `document.createElement`'s types for TypeScript from npm.)
+
 /**
  * `<book-cover>`: a cover on any page, from its attributes (cover-title, author, subtitle, series,
  * credit, badge, cover-style, genre, palette, seed, format, font, case, texture, variant, lang). It
  * fires `cover` (detail: the cover) when it draws, and `cover-error` (detail: the error) when the
  * attributes can't make one. With `loading="lazy"` it draws once it comes near the viewport, as an
  * image does; until then it holds the cover's shape and is named for screen readers.
- *
- * (The class alone: Deno and JSR use these types, as a package there may not declare global ones.
- * element.d.ts adds the tag to `document.createElement`'s types for TypeScript from npm.)
  */
 export declare class BookCover extends HTMLElement {
+  /** The attributes it watches: those that make the cover, and `loading`. */
   static observedAttributes: string[];
   /** The cover drawn last, or null (before the first, or after an error). */
   cover: ReturnType<typeof createCover> | null;

package/src/index.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Draw book covers as SVG from a title and an author. Every random choice (the style, the palette,
+ * the artwork) comes from a seed, by default the title and author, so the same options give the
+ * same cover.
+ *
+ * ```js
+ * import { createCover } from '@otsirh/book-cover-generator';
+ *
+ * const { svg, style, palette } = createCover({
+ *   title: 'Dune',
+ *   author: 'Frank Herbert',
+ *   style: 'retro', // or 'random' (the default): picked from the seed
+ *   seed: 42,
+ * });
+ * ```
+ *
+ * `generateCover` returns the SVG alone, and `createMockup` shows a cover as a book or on a social
+ * card. To make a PNG, JPEG or WebP in a browser, see the `./browser` entry point; for a cover from
+ * an HTML element, `./element`. `registerStyle` adds a style of your own, drawn with the same text and
+ * colour helpers the built-in styles use.
+ *
+ * (On npm the package is `book-cover-generator`: `import { createCover } from 'book-cover-generator'`.)
+ *
+ * @module
+ */
+
 import type { Rng } from './core.js';
 import type { Palette, PaletteId } from './palettes.js';
 import type { FontSpec, FONTS } from './text.js';
@@ -22,11 +48,14 @@ export {
 } from './text.js';
 export { titleBlock, authorFit, fitStack, drawStack, splitLead } from './type.js';
 export { strongAccents, textColor, tintText, fitTitleWith, textPanel, TEXT_CONTRAST } from './styles/util.js';
+/** The SVG, colour and noise helpers the built-in styles use. */
 export * as svgUtils from './core.js';
 
+/** A kind of mockup: a product shot (`flat`, `book`, `ereader`) or a social card (`card`, `square`, `story`). */
 export type MockupKind = 'flat' | 'book' | 'ereader' | 'card' | 'square' | 'story';
 /** The kinds of mockup `createMockup` makes. */
 export declare const mockupKinds: readonly MockupKind[];
+/** Options for `createMockup`. */
 export interface MockupOptions {
   /** Default `'book'`. `card` is 1200 × 630, `square` 1080 × 1080, `story` 1080 × 1920; the others follow the cover's size. */
   kind?: MockupKind;
@@ -68,6 +97,7 @@ export declare const formats: Readonly<{
   square: readonly [number, number];
 }>;
 
+/** The ids of the built-in styles. */
 export type StyleId =
   | 'minimal'
   | 'swiss'
@@ -109,18 +139,29 @@ export type StyleId =
   | 'storybook'
   | 'idea';
 
+/** The families the built-in styles belong to. */
 export type StyleGroup = 'Typographic' | 'Geometric' | 'Pattern' | 'Scenic' | 'Vintage' | 'Genre';
 
 /** A palette you define yourself. All colours must be hex (`#rgb` or `#rrggbb`). */
 export interface CustomPalette {
+  /** The background. */
   bg: string;
+  /** The text colour. */
   ink: string;
+  /** One or more accents; a cover repeats them to make three if there are fewer. */
   accents: readonly string[];
+  /** Its id: what the cover reports as its `palette` (default `'custom'`). `registerPalette` needs one. */
   id?: string;
+  /** Its name as people read it. Default `'Custom'`, or for `registerPalette` its id. */
   name?: string;
+  /** Whether the background is dark. Default: whether `bg` is darker than `ink`. */
   dark?: boolean;
 }
 
+/**
+ * Options for `createCover` and `generateCover`, all optional. An option that isn't valid throws
+ * an error that says why (`texture` excepted: any truthy value turns it on).
+ */
 export interface CoverOptions {
   /** Defaults to `'Untitled'`. Up to 300 characters are used. */
   title?: string;
@@ -134,7 +175,7 @@ export interface CoverOptions {
   credit?: string;
   /** A seal set in a corner clear of the text, such as `'Winner of the Hugo Award'`. Up to 60 characters. */
   badge?: string;
-  /** Add a fine film-grain texture over the cover. Default `false`. */
+  /** Add a fine film-grain texture over the cover. Default `false`; any truthy value (even `'false'`) turns it on. */
   texture?: boolean;
   /** A style id, a registered custom style, or `'random'` (default; picked from the seed). */
   style?: StyleId | 'random' | (string & {});
@@ -142,7 +183,7 @@ export interface CoverOptions {
   genre?: GenreId | (string & {});
   /** A palette id, a custom palette, or `'random'` / `'auto'` (default; picked from the seed). */
   palette?: PaletteId | 'random' | 'auto' | CustomPalette | (string & {});
-  /** Controls every random choice. Defaults to a hash of title + author. */
+  /** Controls every random choice. Defaults to the title and author (`Cover.seed` says which seed was used). */
   seed?: string | number;
   /** Width in px, 50–10000. Default 600. */
   width?: number;
@@ -169,7 +210,9 @@ export interface CoverOptions {
   titleCase?: 'upper' | 'normal';
 }
 
+/** A cover made by `createCover`: its SVG, and the choices it was made with. */
 export interface Cover {
+  /** The SVG document, `width` × `height` px, named for screen readers by its title, author and other text. */
   svg: string;
   /** The markup inside the outer `<svg>`, to nest the cover in another SVG (its ids are unique to the cover). */
   body: string;
@@ -179,28 +222,42 @@ export interface Cover {
   palette: string;
   /** The palette's colours, as the cover used them. */
   colors: { bg: string; ink: string; accents: string[]; dark: boolean };
+  /**
+   * The seed the cover was drawn from: the `seed` option as a string, else one made from the title
+   * and author. The same options with this seed give the same cover.
+   */
   seed: string;
+  /** Width in px. */
   width: number;
+  /** Height in px. */
   height: number;
   /** The language set on the cover (given or inferred), or `''`. */
   lang: string;
   /** The value of each of the style's variants this cover has, pinned or picked by the seed. */
   variants: Record<string, string>;
-  /** The title as set (line breaks as "\n"), and the author, after cleaning. */
+  /** The title as set, after cleaning (line breaks as "\n"; `'Untitled'` when there is none). */
   title: string;
+  /** The author after cleaning, or `''`. */
   author: string;
 }
 
 /** A choice a style lets you pin, such as Silhouette's scene. */
 export interface StyleVariant {
+  /** The name to pin it by, such as `'scene'`. */
   name: string;
+  /** The name as people read it, such as `'Scene'`. */
   label: string;
+  /** The values it can take, each with a label as people read it. */
   values: { value: string; label: string }[];
 }
 
+/** A style as `listStyles()` describes it. */
 export interface StyleInfo {
+  /** Its id, as `createCover({ style })` takes it. */
   id: string;
+  /** Its name as people read it, such as `'Art Deco'`; for a registered style without one, its id. */
   name: string;
+  /** What it looks like, in a sentence; empty for a registered style without one. */
   description: string;
   /** The family the style belongs to; `'Custom'` for registered styles without one. */
   group: StyleGroup | (string & {});
@@ -210,13 +267,16 @@ export interface StyleInfo {
   genres: string[];
 }
 
+/** The ids of the genres in `genres`. */
 export type GenreId = 'literary' | 'thriller' | 'horror' | 'romance' | 'fantasy' | 'children' | 'nonfiction';
 /** The genres styles can suit, as `createCover({ genre })` and `listStyles()` name them. */
 export declare const genres: readonly { readonly id: GenreId; readonly name: string }[];
 
 /** A palette as seen by styles, with derived light/dark colours. */
 export interface ResolvedPalette extends Palette {
+  /** At least three accents: a palette with fewer has them repeated. */
   readonly accents: readonly string[];
+  /** Whether the background is dark: the palette's `dark`, else whether `bg` is darker than `ink`. */
   readonly dark: boolean;
   /** The lighter of `bg` and `ink`. */
   readonly paper: string;
@@ -226,7 +286,9 @@ export interface ResolvedPalette extends Palette {
 
 /** Everything a style's `render` function receives. */
 export interface StyleContext {
+  /** The title after cleaning (`'Untitled'` if there is none), with any line breaks it was typed with as "\n". */
   readonly title: string;
+  /** The author after cleaning, or empty. */
   readonly author: string;
   /**
    * The subtitle, then the credit ("Translated by …"), if any, on a line of its own (after "\n"):
@@ -247,6 +309,7 @@ export interface StyleContext {
   readonly m: number;
   /** Seeded random numbers, unique to this cover and style. */
   readonly rng: Rng;
+  /** The palette, with its lighter and darker colours as `paper` and `night`. */
   readonly p: ResolvedPalette;
   /** Make an id that is unique to this cover, for gradients, filters, masks… */
   id(name: string): string;
@@ -261,10 +324,15 @@ export interface StyleContext {
   readonly titleCase: 'upper' | 'normal' | null;
 }
 
+/** A style to add with `registerStyle`. */
 export interface CoverStyle {
+  /** Its id: a non-empty string without spaces at either end, and not `'random'` (in any case). */
   id: string;
+  /** Its name as people read it. Default: the id. */
   name?: string;
+  /** What it looks like, in a sentence. Default empty. */
   description?: string;
+  /** The family it belongs to, as `listStyles()` reports it. Default `'Custom'`. */
   group?: StyleGroup | (string & {});
   /** Background preference when the palette is picked automatically. */
   prefer?: 'light' | 'dark';
@@ -284,7 +352,9 @@ export interface CoverStyle {
 
 /** Ids of every available style (including registered custom styles). */
 export declare const styles: string[];
+/** Every available style, built-in and registered, as copies: changing them changes no style. */
 export declare function listStyles(): StyleInfo[];
+/** Options for `registerStyle` and `registerPalette`. */
 export interface RegisterOptions {
   /** Allow replacing the built-in style (or palette) with the same id. */
   replace?: boolean;

package/src/index.js

@@ -32,7 +32,7 @@ export { createMockup, mockupKinds } from './mockups.js';
 export { parseBookList } from './books.js';
 
 /** This version of the library (artwork for a seed can change between minor versions). */
-export const version = '1.9.1';
+export const version = '1.9.2';
 
 /** The sizes a cover can have: each side `min` to `max` px, and neither more than `ratio` times the other. */
 export const sizeLimits = Object.freeze({ min: 50, max: 10000, ratio: 3 });
@@ -200,7 +200,7 @@ export function styleIdFor(name) {
   return idFor(name, registry.values());
 }
 
-/** Metadata for every available style: [{ id, name, description, group }] */
+/** Every available style: its id, name, description and group, the genres it suits, and its variants. */
 export function listStyles() {
   return [...registry.values()].map(({ id, name, description, group, variants, genres: suits }) => ({
     id,

package/src/palettes.d.ts

@@ -1,3 +1,4 @@
+/** The ids of the built-in palettes. */
 export type PaletteId =
   | 'parchment'
   | 'bauhaus'
@@ -28,13 +29,17 @@ export type PaletteId =
   | 'thriller'
   | 'dusk';
 
+/** A palette: a background, an ink colour for text, and accents. */
 export interface Palette {
+  /** Its id, as `createCover({ palette })` takes it. */
   readonly id: string;
+  /** Its name as people read it, such as `'Midnight'`. */
   readonly name: string;
   /** Background, as hex. */
   readonly bg: string;
   /** Text colour with strong contrast against `bg`. */
   readonly ink: string;
+  /** Accent colours, as hex (three in each built-in palette). */
   readonly accents: readonly string[];
   /** `true` for dark backgrounds. */
   readonly dark?: boolean;

package/src/text.d.ts

@@ -1,3 +1,4 @@
+/** A font to set text in: a CSS font-family stack, and what fitting text in it needs to know. */
 export interface FontSpec {
   /** Its name as the app's menu shows it (the built-in fonts). */
   name?: string;
@@ -11,6 +12,10 @@ export interface FontSpec {
   mono?: boolean;
 }
 
+/**
+ * The built-in fonts. Each is a stack of system fonts, as an SVG drawn into a canvas (for PNG or
+ * JPEG export) can't load web fonts.
+ */
 export declare const FONTS: Readonly<{
   serif: FontSpec;
   didone: FontSpec;
@@ -23,9 +28,13 @@ export declare const FONTS: Readonly<{
   mono: FontSpec;
 }>;
 
+/** The type `measureText` measures with: a font, its weight and style, and letter-spacing. */
 export interface TextSpec {
+  /** The font. */
   font: FontSpec;
+  /** Font weight. Default 400. */
   weight?: number;
+  /** Italic. Default `false`. */
   italic?: boolean;
   /** In em. */
   letterSpacing?: number;
@@ -43,6 +52,12 @@ export type TextMeasurer = (
  * string and font at a reference size of 100 px, and other sizes are scaled from it. Pass `null` to restore the default.
  */
 export declare function setTextMeasurer(fn: TextMeasurer | null): void;
+/**
+ * The width in px of `text` at `size` px, letter-spacing included: measured with the function set
+ * by `setTextMeasurer`, else with a canvas, else from the built-in fonts' character widths (other
+ * fonts are estimated). Throws a TypeError if that function returns anything but a finite width of
+ * 0 or more.
+ */
 export declare function measureText(text: string, size: number, spec: TextSpec): number;
 /** Throw a TypeError if `maxWidth` is missing or `maxHeight` is NaN. */
 export declare function checkBox(fn: string, o: { maxWidth: number; maxHeight?: number }): void;
@@ -60,9 +75,13 @@ export declare const LINE_BREAK: RegExp;
 export declare function typedLines(text: string): number;
 /** Where some text was drawn. */
 export interface TextBox {
+  /** Left edge, in px. */
   x0: number;
+  /** Top edge, in px. */
   y0: number;
+  /** Right edge, in px. */
   x1: number;
+  /** Bottom edge, in px. */
   y1: number;
 }
 /** Note that text was drawn in this box (drawText and drawStack do it), so a badge can be placed clear of it. */
@@ -74,23 +93,32 @@ export declare function clipGraphemes(str: string, max: number, options?: { unit
 /** Split a string into user-perceived characters. */
 export declare function graphemes(str: string): string[];
 
+/** Options for `fitText`: the box to fit, and how to set the text. */
 export interface FitOptions {
   /** Box width in px. */
   maxWidth: number;
   /** Largest font size in px. */
   maxSize: number;
-  /** Box height in px (cap height of the first line to the last baseline). */
+  /**
+   * Box height in px: from the top of the first line (its cap height, or its marks when it has
+   * accents or marks above, such as É, Thai or Devanagari) to the last baseline.
+   */
   maxHeight?: number;
   /** Smallest font size in px before words are broken and truncated. */
   minSize?: number;
+  /** The font. Default `FONTS.sans`. */
   font?: FontSpec;
+  /** Font weight. Default 400. */
   weight?: number;
+  /** Italic. Default `false`. */
   italic?: boolean;
   /** In em. Ignored for scripts whose letters join (Arabic…), which browsers don't letter-space. */
   letterSpacing?: number;
   /** Multiple of the font size. */
   lineHeight?: number;
+  /** The most lines to wrap to. Default 5. */
   maxLines?: number;
+  /** Set the text in capitals. Default `false`. */
   upper?: boolean;
   /** Even out line lengths (default `true`). */
   balance?: boolean;
@@ -100,18 +128,27 @@ export interface FitOptions {
   hyphenate?: number;
 }
 
+/** Text fitted to a box by `fitText`, ready for `drawText`. */
 export interface TextFit {
+  /** The lines, as set (in capitals with `upper`); empty for empty text. */
   lines: string[];
+  /** Font size in px (0 for empty text). */
   size: number;
+  /** The widest line's width in px. */
   width: number;
   /** From the top of the first line (its cap height, or its accents and marks where they reach higher) to the baseline of the last. */
   height: number;
+  /** The font. */
   font: FontSpec;
+  /** Font weight. */
   weight: number;
+  /** Whether it is italic. */
   italic: boolean;
+  /** Letter-spacing in em (0 for scripts whose letters join). */
   letterSpacing: number;
   /** The pitch between baselines, as a multiple of the size: the requested line height, or more where a line's accents or marks would reach the line above. */
   lineHeight: number;
+  /** Cap height as a fraction of the size: the font's `cap`, else 0.72. */
   cap: number;
   /** Room above the first line's cap height for its accents and marks, as a fraction of the size. */
   above?: number;
@@ -121,12 +158,17 @@ export interface TextFit {
   truncated: boolean;
 }
 
+/** Where and how `drawText` sets a fit. */
 export interface DrawOptions {
+  /** The x of the anchor point, in px. */
   x: number;
   /** Top of the text block: the cap height of the first line, or its accents and marks where they reach higher. */
   y: number;
+  /** How the lines align on `x`, as SVG's `text-anchor`. Default `'start'`. */
   anchor?: 'start' | 'middle' | 'end';
+  /** Text colour. Default `'#000'`. */
   fill?: string;
+  /** Opacity, 0–1. Default 1. */
   opacity?: number;
   /** Extra raw SVG attributes for the wrapping `<g>`. */
   attrs?: string;
@@ -142,7 +184,11 @@ export declare function baselineOf(fit: TextFit, y: number, i: number): number;
 export declare function markExtent(text: string): { above: number; below: number };
 /** Room below a line for descenders and marks, in em. */
 export declare function descentOf(line: string): number;
-/** Attributes shared by every line of a text block (escaped), for its wrapping `<g>`. */
+/**
+ * Attributes shared by every line of a text block, for its wrapping `<g>`: the font family and fill
+ * are escaped, `attrs` is written as given (raw SVG). Unlike the fitting options, `size` and
+ * `letterSpacing` are in px here (`drawText` passes a fit's letter-spacing × its size).
+ */
 export declare function textGroupAttrs(o: {
   font: FontSpec;
   fill: string;

package/src/type.d.ts

@@ -3,6 +3,7 @@ import type { StyleContext } from './index.js';
 
 /** A justified stack: every line spans the full width at its own size. */
 export interface StackFit {
+  /** Tells a stack from a `TextFit`. */
   kind: 'stack';
   /**
    * `descent` is the room below each line for descenders and marks, and `above` the room above
@@ -13,30 +14,50 @@ export interface StackFit {
   height: number;
   /** Room needed below the last baseline, in px. */
   descent: number;
+  /** The widest line's width in px. */
   width: number;
   /** The largest line size. */
   size: number;
+  /** The font. */
   font: FontSpec;
+  /** Font weight (`fitStack` defaults to 700). */
   weight: number;
+  /** Whether it is italic. */
   italic: boolean;
+  /** Letter-spacing in em (0 for scripts whose letters join). */
   letterSpacing: number;
   /** Space between lines, as a fraction of the lower line's size. */
   gap: number;
+  /** Cap height as a fraction of each line's size: the font's `cap`, else 0.72. */
   cap: number;
 }
 
+/** Options for `titleBlock`. */
 export interface TitleBlockOptions {
+  /** Box width in px. */
   maxWidth: number;
+  /** Box height in px, for all of it: the series line, the lead, the title and the subtitle. */
   maxHeight: number;
-  /** Largest title size in px. */
+  /** Largest title size in px (a short one-word title, such as "Dune", may grow to 1.6 times this). */
   maxSize: number;
+  /**
+   * Smallest title size in px (default as for `fitText`). Rather than set the title smaller or cut
+   * it, the leading article rejoins the title, then the subtitle and then the series line are left out.
+   */
   minSize?: number;
+  /** The title's font. Default `FONTS.serif`; the cover's `font` option wins. */
   font?: FontSpec;
+  /** The title's weight. Default 400 (at most 700 when the cover's `font` option swaps in a serif). */
   weight?: number;
+  /** Set the title in italics. Default `false`. */
   italic?: boolean;
+  /** Set the title in capitals. Default `false`; the cover's `titleCase` option wins. */
   upper?: boolean;
+  /** The title's letter-spacing in em. Default 0. */
   letterSpacing?: number;
+  /** The title's line height, as a multiple of its size. Default 1.05. */
   lineHeight?: number;
+  /** The most title lines. Default 5 (or as many as the title was typed on, if more). */
   maxLines?: number;
   /**
    * Set a leading article of three letters or more ("The", "Les", "Der") as a small line above the
@@ -47,19 +68,25 @@ export interface TitleBlockOptions {
   stack?: boolean;
   /** Include the subtitle under the title. Default `true`. */
   subtitle?: boolean;
+  /** The font of the subtitle and the series line. Default: the title's. */
   subtitleFont?: FontSpec;
   /** `false` to leave out the cover's series line (for a style that sets it itself). */
   series?: false;
+  /** Set the subtitle in italics. Default `true`, except in `FONTS.mono`. */
   subtitleItalic?: boolean;
+  /** Set the subtitle in spaced capitals. Default `false`. */
   subtitleUpper?: boolean;
+  /** Largest subtitle size in px. Default 3.6% of the cover's short side. */
   subtitleSize?: number;
   /** Use this text instead of the cover's title. */
   text?: string;
 }
 
+/** A title laid out by `titleBlock`, ready to draw. */
 export interface TitleBlock {
   /** From the top of the first line to the bottom of the block. */
   height: number;
+  /** The widest line's width in px (the title's, the lead's, the subtitle's or the series line's). */
   width: number;
   /** The main title size (the largest line, for stacks). */
   size: number;
@@ -71,6 +98,11 @@ export interface TitleBlock {
   lines: number;
   /** The title was cut with an ellipsis because it didn't fit. */
   truncated: boolean;
+  /**
+   * The block as SVG, its top at `y`. `fill` colours the title, `leadFill` the lead and the series
+   * line, and `subtitleFill` the subtitle (both default to `fill`); `attrs` (raw SVG attributes)
+   * go on every part.
+   */
   draw(o: {
     x: number;
     y: number;
@@ -90,6 +122,10 @@ export declare function splitLead(title: string): { lead: string; main: string }
 export declare function stackLines(text: string): string[];
 /** Fit a justified stack, or `null` when the text doesn't suit one. */
 export declare function fitStack(text: string, opts: FitOptions & { gap?: number }): StackFit | null;
+/**
+ * Render a stack as SVG `<text>` elements, its top at `y` (as for `drawText`); `lineFills` colours
+ * lines one by one.
+ */
 export declare function drawStack(fit: StackFit, opts: DrawOptions & { lineFills?: (string | undefined)[] }): string;
 /** Fit the title (with a demoted leading article and the subtitle) into a box. */
 export declare function titleBlock(c: StyleContext, opts: TitleBlockOptions): TitleBlock;