@visulima/html 0.0.1 → 1.0.0-alpha.2

package/dist/index.d.ts

@@ -0,0 +1,422 @@
+import { Properties } from 'csstype';
+export { Properties as CSSProperties } from 'csstype';
+export { default as sanitizeHtml } from 'sanitize-html';
+
+type FlexibleCSSProperties$1 = {
+    [K in keyof Properties]?: Properties[K] | string | number | null | undefined;
+};
+declare function css(strings: TemplateStringsArray, ...values: unknown[]): string;
+declare function css(value: string | FlexibleCSSProperties$1 | Properties, escape?: boolean): string;
+
+declare const escapeHtml: (value: unknown, isAttribute?: boolean) => string;
+
+declare function html(strings: TemplateStringsArray, ...values: unknown[]): string;
+declare function html(value: string, escape?: boolean): string;
+
+/**
+ * Escapes a string for direct interpolation into an external
+ * CSS style sheet, within a `<style>` element, or in a selector.
+ *
+ * Uses identical logic to
+ * [`CSS.escape`](https://developer.mozilla.org/en-US/docs/Web/API/CSS/escape_static)
+ * in browsers.
+ *
+ * @param str The string to escape.
+ * @returns The escaped string.
+ *
+ * @example Usage
+ * ```ts
+ * import { escapeCss } from "@std/html/unstable-escape-css";
+ * import { assertEquals } from "@std/assert";
+ *
+ * // Invalid in a CSS selector, even though it's a valid HTML ID
+ * const elementId = "123";
+ * // Unsafe for interpolation
+ * const contentInput = `<!-- '" --></style>`;
+ *
+ * const selector = `#${escapeCss(elementId)}`;
+ * const content = `"${escapeCss(contentInput)}"`;
+ *
+ * // Usable as a CSS selector
+ * assertEquals(selector, String.raw`#\31 23`);
+ * // Safe for interpolation
+ * assertEquals(content, String.raw`"\<\!--\ \'\"\ --\>\<\/style\>"`);
+ *
+ * // Usage
+ * `<style>
+ *  ${selector}::after {
+ *    content: ${content};
+ *  }
+ * </style>`;
+ * ```
+ */ declare function escapeCss(str: string): string;
+
+/** Options for {@linkcode escapeJs} */ type EscapeJsOptions = {
+  /**
+   * The number of spaces or tab to use for indentation in the output.
+   * If not specified, no extra whitespace is added.
+   */ space?: number | "\t";
+};
+/**
+ * Escapes a JavaScript object or other data for safe interpolation inside a `<script>` tag.
+ *
+ * The data must be JSON-serializable (plain object, array, string, number (excluding `NaN`/infinities), boolean, or null).
+ *
+ * The output is fully JSON-compatible, with additional escaping of sequences that can be problematic within `<script>` tags.
+ *
+ * @param data The data to escape.
+ * @param options Options for escaping.
+ * @returns The escaped string.
+ *
+ * @example Escaping a string
+ * ```ts
+ * import { escapeJs } from "@std/html/unstable-escape-js";
+ * import { assertEquals } from "@std/assert";
+ * const input = "\u2028\u2029</script>";
+ * assertEquals(escapeJs(input), '"\\u2028\\u2029\\u003c/script>"');
+ * ```
+ *
+ * @example Escaping an object
+ * ```ts
+ * import { escapeJs } from "@std/html/unstable-escape-js";
+ * import { assertEquals } from "@std/assert";
+ * const input = {
+ *   "<SCRIPT>": "</script>",
+ *   "<!--": "\u2028\u2029<>",
+ * };
+ * assertEquals(
+ *  escapeJs(input),
+ *  '{"\\u003cSCRIPT>":"\\u003c/script>","\\u003c!--":"\\u2028\\u2029<>"}',
+ * );
+ * ```
+ *
+ * @example Interpolating arbitrary data in a script tag
+ * ```ts no-assert ignore
+ * // might be nested arbitrarily deeply
+ * declare const data: string | number | Record<string, string> | Record<string, Record<string, string>>;
+ * const scriptHtml = `<script>window.handleData(${escapeJs(data)})</script>`;
+ * ```
+ *
+ * @example Interpolating into a JSON script (e.g. importmap)
+ * ```ts no-assert ignore
+ * const importMap = { imports: { zod: 'https://esm.sh/v131/zod@3.21.4' } };
+ * const importMapHtml = `<script type="importmap">${escapeJs(importMap)}</script>`;
+ * ```
+ */ declare function escapeJs(data: unknown, options?: EscapeJsOptions): string;
+
+/**
+ * Returns whether the given string is a valid custom element name, as per the
+ * requirements defined in
+ * {@link https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name}.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * The element name must not be any of the following:
+ * - `annotation-xml`
+ * - `color-profile`
+ * - `font-face`
+ * - `font-face-src`
+ * - `font-face-uri`
+ * - `font-face-format`
+ * - `font-face-name`
+ * - `missing-glyph`
+ *
+ * @example Usage
+ *
+ * Using a valid custom element name
+ *
+ * ```ts
+ * import { isValidCustomElementName } from "@std/html/unstable-is-valid-custom-element-name";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(isValidCustomElementName("custom-element"), true);
+ * assertEquals(isValidCustomElementName("font-face"), false);
+ * assertEquals(isValidCustomElementName("custom-element@"), false);
+ * ```
+ *
+ * @param elementName The element name to be validate
+ * @returns `true` if the element name is valid, `false` otherwise.
+ */ declare function isValidCustomElementName(elementName: string): boolean;
+
+type Level = 'xml' | 'html4' | 'html5' | 'all';
+interface CommonOptions {
+    level?: Level;
+}
+type EncodeMode = 'specialChars' | 'nonAscii' | 'nonAsciiPrintable' | 'nonAsciiPrintableOnly' | 'extensive';
+interface EncodeOptions extends CommonOptions {
+    mode?: EncodeMode;
+    numeric?: 'decimal' | 'hexadecimal';
+}
+type DecodeScope = 'strict' | 'body' | 'attribute';
+interface DecodeOptions extends CommonOptions {
+    scope?: DecodeScope;
+}
+/** Encodes all the necessary (specified by `level`) characters in the text */
+declare function encode(text: string | undefined | null, { mode, numeric, level }?: EncodeOptions): string;
+/** Decodes a single entity */
+declare function decodeEntity(entity: string | undefined | null, { level }?: CommonOptions): string;
+/** Decodes all entities in the text */
+declare function decode(text: string | undefined | null, { level, scope }?: DecodeOptions): string;
+
+type HtmlTags =
+	| 'a'
+	| 'abbr'
+	| 'address'
+	| 'area'
+	| 'article'
+	| 'aside'
+	| 'audio'
+	| 'b'
+	| 'base'
+	| 'bdi'
+	| 'bdo'
+	| 'blockquote'
+	| 'body'
+	| 'br'
+	| 'button'
+	| 'canvas'
+	| 'caption'
+	| 'cite'
+	| 'code'
+	| 'col'
+	| 'colgroup'
+	| 'data'
+	| 'datalist'
+	| 'dd'
+	| 'del'
+	| 'details'
+	| 'dfn'
+	| 'dialog'
+	| 'div'
+	| 'dl'
+	| 'dt'
+	| 'em'
+	| 'embed'
+	| 'fieldset'
+	| 'figcaption'
+	| 'figure'
+	| 'footer'
+	| 'form'
+	| 'h1'
+	| 'h2'
+	| 'h3'
+	| 'h4'
+	| 'h5'
+	| 'h6'
+	| 'head'
+	| 'header'
+	| 'hgroup'
+	| 'hr'
+	| 'html'
+	| 'i'
+	| 'iframe'
+	| 'img'
+	| 'input'
+	| 'ins'
+	| 'kbd'
+	| 'label'
+	| 'legend'
+	| 'li'
+	| 'link'
+	| 'main'
+	| 'map'
+	| 'mark'
+	| 'math'
+	| 'menu'
+	| 'meta'
+	| 'meter'
+	| 'nav'
+	| 'noscript'
+	| 'object'
+	| 'ol'
+	| 'optgroup'
+	| 'option'
+	| 'output'
+	| 'p'
+	| 'picture'
+	| 'pre'
+	| 'progress'
+	| 'q'
+	| 'rp'
+	| 'rt'
+	| 'ruby'
+	| 's'
+	| 'samp'
+	| 'script'
+	| 'search'
+	| 'section'
+	| 'select'
+	| 'selectedcontent'
+	| 'slot'
+	| 'small'
+	| 'source'
+	| 'span'
+	| 'strong'
+	| 'style'
+	| 'sub'
+	| 'summary'
+	| 'sup'
+	| 'svg'
+	| 'table'
+	| 'tbody'
+	| 'td'
+	| 'template'
+	| 'textarea'
+	| 'tfoot'
+	| 'th'
+	| 'thead'
+	| 'time'
+	| 'title'
+	| 'tr'
+	| 'track'
+	| 'u'
+	| 'ul'
+	| 'var'
+	| 'video'
+	| 'wbr';
+
+type VoidHtmlTags =
+	| 'area'
+	| 'base'
+	| 'br'
+	| 'col'
+	| 'embed'
+	| 'hr'
+	| 'img'
+	| 'input'
+	| 'link'
+	| 'meta'
+	| 'source'
+	| 'track'
+	| 'wbr';
+
+/**
+List of standard HTML tags.
+
+@example
+```
+import htmlTags from 'html-tags';
+
+console.log(htmlTags);
+//=> ['a', 'abbr', 'acronym', …]
+```
+*/
+declare const htmlTags: readonly HtmlTags[];
+
+/**
+List of standard, self-closing HTML tags.
+
+@example
+```
+import {voidHtmlTags} from 'html-tags';
+
+console.log(voidHtmlTags);
+//=> ['area', 'base', 'br', …]
+```
+*/
+declare const voidHtmlTags: readonly VoidHtmlTags[];
+
+type Range$1 =
+  | [from: number, to: number]
+  | [from: number, to: number, whatToInsert: string | null | undefined];
+interface Opts$1 {
+  limitToBeAddedWhitespace: boolean;
+  limitLinebreaksCount: number;
+  mergeType: 1 | 2 | "1" | "2" | undefined;
+}
+declare class Ranges$1 {
+  constructor(originalOpts?: Partial<Opts$1>);
+  ranges: Range$1[];
+  opts: Opts$1;
+  add(
+    originalFrom: number,
+    originalTo?: number,
+    addVal?: undefined | null | string,
+  ): void;
+  add(originalFrom: Range$1[] | Range$1 | null): void;
+  push(
+    originalFrom: number,
+    originalTo?: number,
+    addVal?: undefined | null | string,
+  ): void;
+  push(originalFrom: Range$1[] | Range$1 | null): void;
+  current(): null | Range$1[];
+  wipe(): void;
+  replace(givenRanges: Range$1[]): void;
+  last(): Range$1 | null;
+}
+
+type Range =
+  | [from: number, to: number]
+  | [from: number, to: number, whatToInsert: string | null | undefined];
+type Ranges = Range[] | null;
+interface Attribute {
+  nameStarts: number;
+  nameEnds: number;
+  equalsAt?: number;
+  name: string;
+  valueStarts?: number;
+  valueEnds?: number;
+  value?: string;
+}
+interface Tag {
+  attributes: Attribute[];
+  lastClosingBracketAt: number;
+  lastOpeningBracketAt: number;
+  slashPresent: number;
+  leftOuterWhitespace: number;
+  onlyPlausible: boolean;
+  nameStarts: number;
+  nameContainsLetters: boolean;
+  nameEnds: number;
+  name: string;
+}
+interface CbObj {
+  tag: Tag;
+  deleteFrom: null | number;
+  deleteTo: null | number;
+  insert: null | undefined | string;
+  rangesArr: Ranges$1;
+  proposedReturn: Range | null;
+}
+interface Opts {
+  ignoreTags: string[];
+  ignoreTagsWithTheirContents: string[];
+  onlyStripTags: string[];
+  stripTogetherWithTheirContents: string[];
+  skipHtmlDecoding: boolean;
+  trimOnlySpaces: boolean;
+  stripRecognisedHTMLOnly: boolean;
+  dumpLinkHrefsNearby: {
+    enabled?: boolean;
+    putOnNewLine?: boolean;
+    wrapHeads?: string;
+    wrapTails?: string;
+  };
+  ignoreIndentations: boolean;
+  cb: null | ((cbObj: CbObj) => void);
+  reportProgressFunc: null | ((percDone: number) => void);
+  reportProgressFuncFrom: number;
+  reportProgressFuncTo: number;
+}
+declare const defaults: Opts;
+interface Res {
+  log: {
+    timeTakenInMilliseconds: number;
+  };
+  result: string;
+  ranges: Ranges;
+  allTagLocations: [number, number][];
+  filteredTagLocations: [number, number][];
+}
+/**
+ * Strips HTML tags from strings. No parser, accepts mixed sources.
+ */
+declare function stripHtml(str: string, opts?: Partial<Opts>): Res;
+
+type FlexibleCSSProperties = {
+    [K in keyof Properties]?: Properties[K] | string | number | null | undefined;
+};
+
+export { css, decode, decodeEntity, encode, escapeCss, escapeHtml, escapeJs, html, htmlTags, isValidCustomElementName, stripHtml, defaults as stripHtmlDefaultOptions, voidHtmlTags };
+export type { DecodeOptions, DecodeScope, EncodeMode, EncodeOptions, FlexibleCSSProperties, Level, Attribute as StripHtmlAttribute, CbObj as StripHtmlCbObj, Opts as StripHtmlOptions, Res as StripHtmlResult, Tag as StripHtmlTag };

package/dist/index.js

@@ -0,0 +1,11 @@
+export { default as css } from './packem_shared/css-eLBFmNQq.js';
+export { default as escapeHtml } from './packem_shared/escapeHtml-Cztfu84O.js';
+export { default as html } from './packem_shared/html-B-Khp3Xj.js';
+export { escapeCss } from './packem_shared/escapeCss-gSWL0xVj.js';
+export { escapeJs } from './packem_shared/escapeJs-8hCFOEdN.js';
+export { isValidCustomElementName } from './packem_shared/isValidCustomElementName-Czb_BiVq.js';
+export { decode, decodeEntity, encode } from './packem_shared/encode-jgknlkNE.js';
+export { default as sanitizeHtml } from 'sanitize-html';
+export { stripHtml, defaults as stripHtmlDefaultOptions } from './packem_shared/stripHtmlDefaultOptions-Dj_FII9M.js';
+export { default as htmlTags } from './packem_shared/htmlTags-CnZinEi6.js';
+export { default as voidHtmlTags } from './packem_shared/voidHtmlTags-Db3mUI2j.js';

package/dist/packem_shared/_commonjsHelpers-B85MJLTf.js

@@ -0,0 +1,5 @@
+function getDefaultExportFromCjs (x) {
+	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
+}
+
+export { getDefaultExportFromCjs as g };

package/dist/packem_shared/css-eLBFmNQq.js

@@ -0,0 +1,32 @@
+import { escapeCss } from './escapeCss-gSWL0xVj.js';
+
+const cssObjectToString = (cssObject) => {
+  const styles = [];
+  Object.entries(cssObject).forEach(([key, value]) => {
+    if (value !== void 0 && value !== null) {
+      const cssKey = key.replaceAll(/([A-Z])/g, "-$1").toLowerCase();
+      styles.push(`${cssKey}: ${String(value)};`);
+    }
+  });
+  return styles.join(" ");
+};
+function css(stringsOrValue, ...valuesOrEscape) {
+  if (Array.isArray(stringsOrValue) && "raw" in stringsOrValue) {
+    const strings = stringsOrValue;
+    let result = strings[0] ?? "";
+    for (const [i, element] of valuesOrEscape.entries()) {
+      result += String(element ?? "");
+      result += strings[i + 1] ?? "";
+    }
+    return result;
+  }
+  const value = stringsOrValue;
+  const escape = valuesOrEscape[0];
+  const cssString = typeof value === "string" ? value : cssObjectToString(value);
+  if (escape === true) {
+    return escapeCss(cssString);
+  }
+  return cssString;
+}
+
+export { css as default };