From 916ebd6fa2f3ff9353aa6df6be7e3518efc7ad92 Mon Sep 17 00:00:00 2001
From: Derek Sifford <dereksifford@gmail.com>
Date: Wed, 10 Jul 2019 19:08:07 -0400
Subject: [PATCH] [@wordpress/escape-html] add new definitions (#36685)

---
 types/wordpress__escape-html/index.d.ts       | 76 +++++++++++++++++++
 types/wordpress__escape-html/tsconfig.json    | 19 +++++
 types/wordpress__escape-html/tslint.json      |  1 +
 .../wordpress__escape-html-tests.ts           | 19 +++++
 4 files changed, 115 insertions(+)
 create mode 100644 types/wordpress__escape-html/index.d.ts
 create mode 100644 types/wordpress__escape-html/tsconfig.json
 create mode 100644 types/wordpress__escape-html/tslint.json
 create mode 100644 types/wordpress__escape-html/wordpress__escape-html-tests.ts

diff --git a/types/wordpress__escape-html/index.d.ts b/types/wordpress__escape-html/index.d.ts
new file mode 100644
index 0000000000..3bf62fb1ac
--- /dev/null
+++ b/types/wordpress__escape-html/index.d.ts
@@ -0,0 +1,76 @@
+// Type definitions for @wordpress/escape-html 1.4
+// Project: https://github.com/WordPress/gutenberg/tree/master/packages/escape-html/README.md
+// Definitions by: Derek Sifford <https://github.com/dsifford>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 3.5
+
+/**
+ * Returns a string with ampersands escaped.
+ *
+ * @remarks
+ * Note that this is an imperfect implementation, where only ampersands which do not appear as a
+ * pattern of named, decimal, or hexadecimal character references are escaped. Invalid named
+ * references (i.e. ambiguous ampersand) are are still permitted.
+ *
+ * See: {@link https://w3c.github.io/html/syntax.html#character-references }
+ * See: {@link https://w3c.github.io/html/syntax.html#ambiguous-ampersand }
+ * See: {@link https://w3c.github.io/html/syntax.html#named-character-references }
+ *
+ * @param value - Original string.
+ */
+export function escapeAmpersand(value: string): string;
+
+/**
+ * Returns an escaped attribute value.
+ *
+ * @remarks
+ * See: {@link https://w3c.github.io/html/syntax.html#elements-attributes }
+ *
+ * "[...] the text cannot contain an ambiguous ampersand [...] must not contain
+ * any literal U+0022 QUOTATION MARK characters (")"
+ *
+ * Note we also escape the greater than symbol, as this is used by wptexturize to
+ * split HTML strings. This is a WordPress specific fix
+ *
+ * Note that if a resolution for Trac#45387 comes to fruition, it is no longer
+ * necessary for `__unstableEscapeGreaterThan` to be used.
+ *
+ * See: {@link https://core.trac.wordpress.org/ticket/45387 }
+ *
+ * @param value - Attribute value.
+ */
+export function escapeAttribute(value: string): string;
+
+/**
+ * Returns an escaped HTML element value.
+ *
+ * @remarks
+ * See: {@link https://w3c.github.io/html/syntax.html#writing-html-documents-elements }
+ *
+ * "the text must not contain the character U+003C LESS-THAN SIGN (<) or an
+ * ambiguous ampersand."
+ *
+ * @param value - Element value.
+ */
+export function escapeHTML(value: string): string;
+
+/**
+ * Returns a string with less-than sign replaced.
+ *
+ * @param value - Original string.
+ */
+export function escapeLessThan(value: string): string;
+
+/**
+ * Returns a string with quotation marks replaced.
+ *
+ * @param value - Original string.
+ */
+export function escapeQuotationMark(value: string): string;
+
+/**
+ * Returns `true` if the given attribute name is valid, or `false` otherwise.
+ *
+ * @param name - Attribute name to test.
+ */
+export function isValidAttributeName(name: string): boolean;
diff --git a/types/wordpress__escape-html/tsconfig.json b/types/wordpress__escape-html/tsconfig.json
new file mode 100644
index 0000000000..78e9e62e7c
--- /dev/null
+++ b/types/wordpress__escape-html/tsconfig.json
@@ -0,0 +1,19 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": ["es6"],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "baseUrl": "../",
+        "typeRoots": ["../"],
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true,
+        "paths": {
+            "@wordpress/escape-html": ["wordpress__escape-html"]
+        }
+    },
+    "files": ["index.d.ts", "wordpress__escape-html-tests.ts"]
+}
diff --git a/types/wordpress__escape-html/tslint.json b/types/wordpress__escape-html/tslint.json
new file mode 100644
index 0000000000..3db14f85ea
--- /dev/null
+++ b/types/wordpress__escape-html/tslint.json
@@ -0,0 +1 @@
+{ "extends": "dtslint/dt.json" }
diff --git a/types/wordpress__escape-html/wordpress__escape-html-tests.ts b/types/wordpress__escape-html/wordpress__escape-html-tests.ts
new file mode 100644
index 0000000000..0397ed60de
--- /dev/null
+++ b/types/wordpress__escape-html/wordpress__escape-html-tests.ts
@@ -0,0 +1,19 @@
+import * as eh from '@wordpress/escape-html';
+
+// $ExpectType string
+eh.escapeAmpersand('foo');
+
+// $ExpectType string
+eh.escapeAttribute('foo');
+
+// $ExpectType string
+eh.escapeHTML('foo');
+
+// $ExpectType string
+eh.escapeLessThan('foo');
+
+// $ExpectType string
+eh.escapeQuotationMark('foo');
+
+// $ExpectType boolean
+eh.isValidAttributeName('foo');