@jackens/nnn 2024.2.19 → 2024.2.24

package/nnn.d.ts

@@ -1,21 +1,220 @@
-import { chartable } from './chartable.js';
-import { eq } from './eq.js';
-import { escape } from './escape.js';
-import { escapeValues } from './escape.js';
-import { fixTypography } from './fixTypography.js';
-import { h } from './h.js';
-import { has } from './has.js';
-import { is } from './is.js';
-import { jcss } from './jcss.js';
-import { jsOnParse } from './jsOnParse.js';
-import { locale } from './locale.js';
-import { nanolight } from './nanolight.js';
-import { nanolightJs } from './nanolightJs.js';
-import { omit } from './pick.js';
-import { pick } from './pick.js';
-import { plUral } from './plUral.js';
-import { pro } from './pro.js';
-import { refsInfo } from './refsInfo.js';
-import { s } from './h.js';
-import { uuid1 } from './uuid1.js';
-export { chartable, eq, escape, escapeValues, fixTypography, h, has, is, jcss, jsOnParse, locale, nanolight, nanolightJs, omit, pick, plUral, pro, refsInfo, s, uuid1 };
+/**
+ * A helper for creating a chart based on a table (conf. <https://jackens.github.io/nnn/chartable/>).
+ *
+ * Options:
+ * - `table`: `HTMLTableElement` to extract data, data series labels and X axis labels
+ * - `headerColumn`: flag indicating that `table` has a header column with X axis labels
+ * - `xGap`: X axis spacing
+ * - `xLabelsMinHeight`: minimal height of X axis labels
+ * - `xLabelsRotate`: flag to rotate X axis labels
+ * - `xReverse`: flag to reverse all data series
+ * - `yGap`: Y axis spacing
+ * - `yLabelsLeftMinWidth`: minimal width of Y axis left labels
+ * - `yLabelsRightMinWidth`: minimal width of Y axis right labels
+ * - `yMax`: number of Y axis lines
+ * - `zLabelsMinWidth`: minimal width of data series labels
+ * - `zyMappings`: mappings per data series
+ */
+export declare const chartable: ({ table, headerColumn, xGap, xLabelsMinHeight, xLabelsRotate, xReverse, yGap, yLabelsLeftMinWidth, yLabelsRightMinWidth, yMax, zLabelsMinWidth, zyMappings }: {
+    table: HTMLTableElement;
+    headerColumn?: boolean | undefined;
+    xGap?: number | undefined;
+    xLabelsMinHeight?: number | undefined;
+    xLabelsRotate?: boolean | undefined;
+    xReverse?: boolean | undefined;
+    yGap?: number | undefined;
+    yLabelsLeftMinWidth?: number | undefined;
+    yLabelsRightMinWidth?: number | undefined;
+    yMax?: number | undefined;
+    zLabelsMinWidth?: number | undefined;
+    zyMappings?: [(label: string) => number, (value: number) => string][] | undefined;
+}) => SVGSVGElement;
+
+/**
+ * A helper that checks equality of the given arguments.
+ */
+export declare const eq: (x: any, y: any) => boolean;
+
+/**
+ * The type of arguments of the `escapeValues` and `escape` helpers.
+ */
+export type EscapeMap = Map<any, (value?: any) => string>;
+
+/**
+ * A generic helper for escaping `values` by given `escapeMap`.
+ */
+export declare const escapeValues: (escapeMap: EscapeMap, values: any[]) => string[];
+
+/**
+ * A generic helper for escaping `values` by given `escapeMap` (in *TemplateStrings* flavor).
+ */
+export declare const escape: (escapeMap: EscapeMap, template: TemplateStringsArray, ...values: any[]) => string;
+
+/**
+ * A helper that implements typographic corrections specific to Polish typography.
+ */
+export declare const fixTypography: (node: Node) => void;
+
+/**
+ * The type of arguments of the `h` and `s` helpers.
+ */
+export type HArgs1 = Partial<Record<PropertyKey, any>> | null | undefined | Node | string | number | HArgs;
+
+/**
+ * The type of arguments of the `h` and `s` helpers.
+ */
+export type HArgs = [string | Node, ...HArgs1[]];
+
+/**
+ * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
+ *
+ * - The first argument of type `string` specifies the tag of the element to be created.
+ * - The first argument of type `Node` specifies the element to be modified.
+ * - All other arguments of type `Partial<Record<PropertyKey, any>>` are mappings of attributes and properties.
+ *   Keys starting with `$` specify *properties* (without the leading `$`) to be set on the element being created or modified.
+ *   (Note that `$` is not a valid attribute name character.)
+ *   All other keys specify *attributes* to be set by `setAttribute`.
+ *   An attribute equal to `false` causes the attribute to be removed by `removeAttribute`.
+ * - All other arguments of type `null` or `undefined` are simply ignored.
+ * - All other arguments of type `Node` are appended to the element being created or modified.
+ * - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
+ * - All other arguments of type `HArgs` are passed to `h` and the results are appended to the element being created or modified.
+ */
+export declare const h: {
+    <T extends keyof HTMLElementTagNameMap>(tag: T, ...args1: HArgs1[]): HTMLElementTagNameMap[T];
+    <N extends Node>(node: N, ...args1: HArgs1[]): N;
+    (tagOrNode: string | Node, ...args1: HArgs1[]): Node;
+};
+
+/**
+ * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
+ *
+ * - The first argument of type `string` specifies the tag of the element to be created.
+ * - The first argument of type `Node` specifies the element to be modified.
+ * - All other arguments of type `Partial<Record<PropertyKey, any>>` are mappings of attributes and properties.
+ *   Keys starting with `$` specify *properties* (without the leading `$`) to be set on the element being created or modified.
+ *   (Note that `$` is not a valid attribute name character.)
+ *   All other keys specify *attributes* to be set by `setAttributeNS`.
+ *   An attribute equal to `false` causes the attribute to be removed by `removeAttributeNS`.
+ * - All other arguments of type `null` or `undefined` are simply ignored.
+ * - All other arguments of type `Node` are appended to the element being created or modified.
+ * - All other arguments of type `string`/`number` are converted to `Text` nodes and appended to the element being created or modified.
+ * - All other arguments of type `HArgs` are passed to `s` and the results are appended to the element being created or modified.
+ */
+export declare const s: {
+    <T extends keyof SVGElementTagNameMap>(tag: T, ...args1: HArgs1[]): SVGElementTagNameMap[T];
+    <N extends Node>(node: N, ...args1: HArgs1[]): N;
+    (tagOrNode: string | Node, ...args1: HArgs1[]): Node;
+};
+
+/**
+ * A replacement for the `in` operator (not to be confused with the `for-in` loop) that works properly.
+ */
+export declare const has: (key: any, ref: any) => boolean;
+
+/**
+ * A helper that checks if the given argument is of a certain type.
+ */
+export declare function is(type: BigIntConstructor, arg: any): arg is bigint;
+export declare function is(type: BooleanConstructor, arg: any): arg is boolean;
+export declare function is(type: NumberConstructor, arg: any): arg is number;
+export declare function is(type: ObjectConstructor, arg: any): arg is Partial<Record<PropertyKey, any>>;
+export declare function is(type: StringConstructor, arg: any): arg is string;
+export declare function is(type: SymbolConstructor, arg: any): arg is symbol;
+export declare function is(type: undefined, arg: any): arg is undefined | null;
+export declare function is<T extends abstract new (...args: any[]) => any>(type: T, arg: any): arg is InstanceType<T>;
+
+/**
+ * The type of arguments of the `jcss` helper.
+ */
+export type JcssNode = {
+    [attributeOrSelector: string]: string | number | JcssNode | undefined;
+};
+
+/**
+ * The type of arguments of the `jcss` helper.
+ */
+export type JcssRoot = Partial<Record<PropertyKey, JcssNode>>;
+
+/**
+ * A simple CSS-in-JS helper.
+ *
+ * The `root` parameter provides a hierarchical description of CSS rules.
+ *
+ * - Keys of sub-objects whose values are NOT objects are treated as CSS attribute, and values are treated as values of those CSS attributes; the concatenation of keys of all parent objects is a CSS rule.
+ * - All keys ignore the part starting with a splitter (default: `$$`) sign until the end of the key (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
+ * - In keys specifying CSS attribute, all uppercase letters are replaced by lowercase letters with an additional `-` character preceding them (e.g. `fontFamily` → `font-family`).
+ * - Commas in keys that makes a CSS rule cause it to “split” and create separate rules for each part (e.g. `{div:{margin:1,'.a,.b,.c':{margin:2}}}` → `div{margin:1}div.a,div.b,div.c{margin:2}`).
+ * - Top-level keys that begin with `@` are not concatenated with sub-object keys.
+ */
+export declare const jcss: (root: JcssRoot, splitter?: string) => string;
+
+/**
+ * `JSON.parse` with “JavaScript turned on”.
+ *
+ * Objects having *exactly* one property which is present in the `handlers` map, i.e. objects of the form:
+ *
+ * ```js
+ * { "«handlerName»": [«params»] }
+ * ```
+ *
+ * are replaced by the result of call
+ *
+ * ```js
+ * handlers['«handlerName»'](...«params»)
+ * ```
+ */
+export declare const jsOnParse: (handlers: Partial<Record<PropertyKey, Function>>, text: string) => any;
+
+/**
+ * Language translations helper.
+ */
+export declare const locale: (map: Partial<Record<PropertyKey, Partial<Record<PropertyKey, string>>>>, defaultVersion: string) => (text: string, version?: string) => string;
+
+/**
+ * A generic helper for syntax highlighting (see also `nanolightJs`).
+ */
+export declare const nanolight: (pattern: RegExp, highlighters: ((chunk: string, index: number) => HArgs1)[], code: string) => HArgs1[];
+
+/**
+ * A helper for highlighting JavaScript.
+ */
+export declare const nanolightJs: (code: string) => HArgs1[];
+
+/**
+ * A helper that implements TypeScript’s `Pick` utility type.
+ */
+export declare const pick: <T extends Partial<Record<PropertyKey, any>>, K extends (keyof T)[]>(obj: Partial<Record<PropertyKey, any>>, keys: any[]) => Pick<T, K[number]>;
+
+/**
+ * A helper that implements TypeScript’s `Omit` utility type.
+ */
+export declare const omit: <T extends Partial<Record<PropertyKey, any>>, K extends (keyof T)[]>(obj: Partial<Record<PropertyKey, any>>, keys: any[]) => Omit<T, K[number]>;
+
+/**
+ * A helper for choosing the correct singular and plural.
+ */
+export declare const plUral: (singular: string, plural2: string, plural5: string, value: number) => string;
+
+/**
+ * A helper that protects calls to nested properties by a `Proxy` that initializes non-existent values with an empty object.
+ */
+export declare const pro: (ref: any) => any;
+
+/**
+ * A helper that provides information about the given `refs`.
+ *
+ * It returns an array of triples: `[«name», «prototype-name», «array-of-own-property-names»]`.
+ */
+export declare const refsInfo: (...refs: any[]) => [string, string, string[]][];
+
+/**
+ * A helper that generates a UUID v1 identifier (with a creation timestamp).
+ *
+ * - The optional `node` parameter should have the format `/^[0123456789abcdef]+$/`.
+ *   Its value will be trimmed to last 12 characters and left padded with zeros.
+ */
+export declare const uuid1: ({ date, node }?: {
+    date?: Date | undefined;
+    node?: string | undefined;
+}) => string;