@grom.js/tgx 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-PRESENT Vladislav Deryabkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+![tgx](tgx.png)
+
+[JSX](https://facebook.github.io/jsx/) runtime for composing Telegram messages.
+
+## Installation
+
+```sh
+# Using npm
+npm install @grom.js/tgx
+
+# Using jsr
+deno add jsr:@grom/tgx
+```
+
+Then in your `tsconfig.json`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@grom.js/tgx" // "@grom/tgx" for jsr
+    // ...
+  }
+}
+```
+
+## Example
+
+Usage with [grammY](https://grammy.dev):
+
+```tsx
+import { html } from '@grom.js/tgx'
+import { Bot } from 'grammy'
+
+function Greeting(props: { name: string }) {
+  return <>Hello, <b>{props.name}</b>!</>
+}
+
+const bot = new Bot(/* TOKEN */)
+
+bot.command('start', async (ctx) => {
+  await ctx.reply(
+    html(<Greeting name={ctx.from.first_name} />),
+    { parse_mode: 'HTML' }
+  )
+})
+
+bot.start()
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/_utils/types.d.ts

@@ -0,0 +1,6 @@
+export type StringWithSuggestions<S extends string> = S | (string & {});
+/**
+ * Aliases of all languages that are supported by [libprisma](https://github.com/TelegramMessenger/libprisma)
+ * (library that Telegram uses for highlighting syntax of code blocks).
+ */
+export type PrismLanguage = 'markup' | 'html' | 'xml' | 'svg' | 'mathml' | 'ssml' | 'atom' | 'rss' | 'css' | 'clike' | 'regex' | 'javascript' | 'js' | 'abap' | 'abnf' | 'actionscript' | 'ada' | 'agda' | 'al' | 'antlr4' | 'g4' | 'apacheconf' | 'sql' | 'apex' | 'apl' | 'applescript' | 'aql' | 'c' | 'cpp' | 'arduino' | 'ino' | 'arff' | 'armasm' | 'arm-asm' | 'bash' | 'sh' | 'shell' | 'yaml' | 'yml' | 'markdown' | 'md' | 'arturo' | 'art' | 'asciidoc' | 'adoc' | 'csharp' | 'cs' | 'dotnet' | 'aspnet' | 'asm6502' | 'asmatmel' | 'autohotkey' | 'autoit' | 'avisynth' | 'avs' | 'avro-idl' | 'avdl' | 'awk' | 'gawk' | 'basic' | 'batch' | 'bbcode' | 'shortcode' | 'bbj' | 'bicep' | 'birb' | 'bison' | 'bnf' | 'rbnf' | 'bqn' | 'brainfuck' | 'brightscript' | 'bro' | 'cfscript' | 'cfc' | 'chaiscript' | 'cil' | 'cilkc' | 'cilk-c' | 'cilkcpp' | 'cilk-cpp' | 'cilk' | 'clojure' | 'cmake' | 'cobol' | 'coffeescript' | 'coffee' | 'concurnas' | 'conc' | 'csp' | 'cooklang' | 'ruby' | 'rb' | 'crystal' | 'csv' | 'cue' | 'cypher' | 'd' | 'dart' | 'dataweave' | 'dax' | 'dhall' | 'diff' | 'markup-templating' | 'django' | 'jinja2' | 'dns-zone-file' | 'dns-zone' | 'docker' | 'dockerfile' | 'dot' | 'gv' | 'ebnf' | 'editorconfig' | 'eiffel' | 'ejs' | 'eta' | 'elixir' | 'elm' | 'lua' | 'etlua' | 'erb' | 'erlang' | 'excel-formula' | 'xlsx' | 'xls' | 'fsharp' | 'factor' | 'false' | 'fift' | 'firestore-security-rules' | 'flow' | 'fortran' | 'ftl' | 'func' | 'gml' | 'gamemakerlanguage' | 'gap' | 'gcode' | 'gdscript' | 'gedcom' | 'gettext' | 'po' | 'git' | 'glsl' | 'gn' | 'gni' | 'linker-script' | 'ld' | 'go' | 'go-module' | 'go-mod' | 'gradle' | 'graphql' | 'groovy' | 'less' | 'scss' | 'textile' | 'haml' | 'handlebars' | 'hbs' | 'mustache' | 'haskell' | 'hs' | 'haxe' | 'hcl' | 'hlsl' | 'hoon' | 'hpkp' | 'hsts' | 'json' | 'webmanifest' | 'uri' | 'url' | 'http' | 'ichigojam' | 'icon' | 'icu-message-format' | 'idris' | 'idr' | 'ignore' | 'gitignore' | 'hgignore' | 'npmignore' | 'inform7' | 'ini' | 'io' | 'j' | 'java' | 'scala' | 'php' | 'javadoclike' | 'javadoc' | 'javastacktrace' | 'jolie' | 'jq' | 'typescript' | 'ts' | 'jsdoc' | 'n4js' | 'n4jsd' | 'json5' | 'jsonp' | 'jsstacktrace' | 'julia' | 'keepalived' | 'keyman' | 'kotlin' | 'kt' | 'kts' | 'kusto' | 'latex' | 'tex' | 'context' | 'latte' | 'scheme' | 'lilypond' | 'ly' | 'liquid' | 'lisp' | 'emacs' | 'elisp' | 'emacs-lisp' | 'livescript' | 'llvm' | 'log' | 'lolcode' | 'magma' | 'makefile' | 'mata' | 'matlab' | 'maxscript' | 'mel' | 'mermaid' | 'metafont' | 'mizar' | 'mongodb' | 'monkey' | 'moonscript' | 'moon' | 'n1ql' | 'nand2tetris-hdl' | 'naniscript' | 'nani' | 'nasm' | 'neon' | 'nevod' | 'nginx' | 'nim' | 'nix' | 'nsis' | 'objectivec' | 'objc' | 'ocaml' | 'odin' | 'opencl' | 'openqasm' | 'qasm' | 'oz' | 'parigp' | 'parser' | 'pascal' | 'objectpascal' | 'pascaligo' | 'psl' | 'pcaxis' | 'px' | 'peoplecode' | 'pcode' | 'perl' | 'phpdoc' | 'plant-uml' | 'plantuml' | 'plsql' | 'powerquery' | 'pq' | 'mscript' | 'powershell' | 'processing' | 'prolog' | 'promql' | 'properties' | 'protobuf' | 'stylus' | 'twig' | 'pug' | 'puppet' | 'purebasic' | 'pbfasm' | 'python' | 'py' | 'qsharp' | 'qs' | 'q' | 'qml' | 'qore' | 'r' | 'racket' | 'rkt' | 'cshtml' | 'razor' | 'jsx' | 'tsx' | 'reason' | 'rego' | 'renpy' | 'rpy' | 'rescript' | 'res' | 'rest' | 'rip' | 'roboconf' | 'robotframework' | 'robot' | 'rust' | 'sas' | 'sass' | 'shell-session' | 'sh-session' | 'shellsession' | 'smali' | 'smalltalk' | 'smarty' | 'sml' | 'smlnj' | 'solidity' | 'sol' | 'solution-file' | 'sln' | 'soy' | 'splunk-spl' | 'sqf' | 'squirrel' | 'stan' | 'stata' | 'iecst' | 'supercollider' | 'sclang' | 'swift' | 'systemd' | 'tact' | 't4-templating' | 't4-cs' | 't4' | 'vbnet' | 't4-vb' | 'tap' | 'tcl' | 'tt2' | 'toml' | 'ttcn' | 'ttcn3' | 'ttcn-3' | 'turtle' | 'trickle' | 'typescript-jsdoc' | 'typoscript' | 'tsconfig' | 'unrealscript' | 'uscript' | 'uc' | 'uri' | 'v' | 'vala' | 'vba' | 'vbscript' | 'velocity' | 'verilog' | 'vhdl' | 'vim' | 'visual-basic' | 'vb' | 'warpscript' | 'wasm' | 'web-idl' | 'webidl' | 'wgsl' | 'wiki' | 'wolfram' | 'mathematica' | 'nb' | 'wl' | 'xeora' | 'xeoracube' | 'xml-doc' | 'xojo' | 'xquery' | 'yaml' | 'yml' | 'yang' | 'zig';

package/dist/_utils/types.js

@@ -0,0 +1 @@
+export {};

package/dist/html.d.ts

@@ -0,0 +1,6 @@
+import type { TgxElement } from './types.ts';
+/**
+ * Converts {@link TgxElement} to an HTML string formatted for Telegram's
+ * HTML parse mode.
+ */
+export declare function html(tgx: TgxElement | TgxElement[]): string;

package/dist/html.js

@@ -0,0 +1,46 @@
+/**
+ * Converts {@link TgxElement} to an HTML string formatted for Telegram's
+ * HTML parse mode.
+ */
+export function html(tgx) {
+    return (Array.isArray(tgx) ? tgx : [tgx])
+        .map((el) => {
+        switch (el.type) {
+            case 'plain': return htmlTgxPlainElement(el);
+            case 'fragment': return html(el.subelements);
+            case 'text': return htmlTgxTextElement(el);
+        }
+        throw new Error(`Unknown element: ${el}.`);
+    })
+        .join('');
+}
+function htmlTgxPlainElement({ value }) {
+    if (value == null || typeof value === 'boolean')
+        return '';
+    return sanitize(String(value));
+}
+function htmlTgxTextElement(el) {
+    switch (el.entity.type) {
+        case 'bold': return `<b>${html(el.subelements)}</b>`;
+        case 'italic': return `<i>${html(el.subelements)}</i>`;
+        case 'underline': return `<u>${html(el.subelements)}</u>`;
+        case 'strikethrough': return `<s>${html(el.subelements)}</s>`;
+        case 'spoiler': return `<tg-spoiler>${html(el.subelements)}</tg-spoiler>`;
+        // TODO: Shouldn't we urlencode this?
+        case 'link': return `<a href="${el.entity.url}">${html(el.subelements)}</a>`;
+        case 'custom-emoji': return `<tg-emoji emoji-id="${el.entity.id}">${el.entity.alt}</tg-emoji>`;
+        case 'code': return `<code>${html(el.subelements)}</code>`;
+        case 'codeblock': return (el.entity.language
+            ? `<pre><code class="language-${el.entity.language}">${html(el.subelements)}</code></pre>`
+            : `<pre>${html(el.subelements)}</pre>`);
+        case 'blockquote': return (el.entity.expandable
+            ? `<blockquote expandable>${html(el.subelements)}</blockquote>`
+            : `<blockquote>${html(el.subelements)}</blockquote>`);
+    }
+}
+function sanitize(unsafe) {
+    return unsafe
+        .replaceAll('&', '&amp;') // must be first
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;');
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { html } from './html.ts';

package/dist/index.js

@@ -0,0 +1 @@
+export { html } from "./html.js";

package/dist/jsx.d.ts

@@ -0,0 +1,6 @@
+import type { FunctionComponent, NativeElements, TgxElement, TgxFragmentElement, TgxNode } from './types.ts';
+export declare function render<T extends keyof NativeElements>(type: T, props: NativeElements[T], children: TgxNode): TgxElement;
+export declare function render(type: FunctionComponent, props: any, children: TgxNode): TgxElement;
+export declare function Fragment(props?: {
+    children?: TgxNode;
+}): TgxFragmentElement;

package/dist/jsx.js

@@ -0,0 +1,108 @@
+export function render(type, props, children) {
+    if (typeof type === 'string' && isNativeTag(type)) {
+        return renderNativeElement({
+            tag: type,
+            props: { ...props, children },
+        });
+    }
+    if (typeof type === 'function')
+        return type({ ...props, children });
+    throw new Error(`Invalid JSX component: ${type}.`);
+}
+export function Fragment(props) {
+    return {
+        type: 'fragment',
+        subelements: elementsFromNode(props?.children ?? []),
+    };
+}
+function elementsFromNode(node) {
+    switch (typeof node) {
+        case 'string':
+        case 'number':
+        case 'boolean':
+            return [{ type: 'plain', value: node }];
+    }
+    if (node == null)
+        return [{ type: 'plain', value: node }];
+    if (Array.isArray(node))
+        return node.flatMap(child => elementsFromNode(child));
+    return [node];
+}
+function isNativeTag(tag) {
+    return ([
+        'b',
+        'i',
+        'u',
+        's',
+        'spoiler',
+        'a',
+        'emoji',
+        'code',
+        'codeblock',
+        'blockquote',
+    ]).includes(tag);
+}
+function renderNativeElement(options) {
+    switch (options.tag) {
+        case 'b':
+            return {
+                type: 'text',
+                entity: { type: 'bold' },
+                subelements: elementsFromNode(options.props.children ?? []),
+            };
+        case 'i':
+            return {
+                type: 'text',
+                entity: { type: 'italic' },
+                subelements: elementsFromNode(options.props.children ?? []),
+            };
+        case 'u':
+            return {
+                type: 'text',
+                entity: { type: 'underline' },
+                subelements: elementsFromNode(options.props.children ?? []),
+            };
+        case 's':
+            return {
+                type: 'text',
+                entity: { type: 'strikethrough' },
+                subelements: elementsFromNode(options.props.children ?? []),
+            };
+        case 'spoiler':
+            return {
+                type: 'text',
+                entity: { type: 'spoiler' },
+                subelements: elementsFromNode(options.props.children ?? []),
+            };
+        case 'a':
+            return {
+                type: 'text',
+                entity: { type: 'link', url: options.props.href },
+                subelements: elementsFromNode(options.props.children ?? []),
+            };
+        case 'emoji':
+            return {
+                type: 'text',
+                entity: { type: 'custom-emoji', id: options.props.id, alt: options.props.alt },
+                subelements: [],
+            };
+        case 'code':
+            return {
+                type: 'text',
+                entity: { type: 'code' },
+                subelements: elementsFromNode(options.props.children ?? []),
+            };
+        case 'codeblock':
+            return {
+                type: 'text',
+                entity: { type: 'codeblock', language: options.props.lang },
+                subelements: elementsFromNode(options.props.children ?? []),
+            };
+        case 'blockquote':
+            return {
+                type: 'text',
+                entity: { type: 'blockquote', expandable: !!options.props.expandable },
+                subelements: elementsFromNode(options.props.children ?? []),
+            };
+    }
+}

package/dist/jsx_runtime.d.ts

@@ -0,0 +1,18 @@
+import type { FunctionComponent, NativeElements, TgxElement } from './types.ts';
+import { Fragment } from './jsx.ts';
+declare function jsx(type: any, props: any, key: any): any;
+export { Fragment, jsx, jsx as jsxDEV, jsx as jsxs, };
+export declare namespace JSX {
+    type Element = TgxElement;
+    type ElementType = keyof NativeElements | FunctionComponent;
+    interface ElementAttributesProperty {
+        props: {};
+    }
+    interface ElementChildrenAttribute {
+        children: {};
+    }
+    interface IntrinsicElements extends NativeElements {
+    }
+    interface IntrinsicAttributes {
+    }
+}

package/dist/jsx_runtime.js

@@ -0,0 +1,10 @@
+import { Fragment, render } from "./jsx.js";
+function jsx(type, props, key) {
+    const { children } = props;
+    delete props.children;
+    if (arguments.length > 2) {
+        props.key = key;
+    }
+    return render(type, props, children);
+}
+export { Fragment, jsx, jsx as jsxDEV, jsx as jsxs, };

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+import type { PrismLanguage, StringWithSuggestions } from './_utils/types.ts';
+export interface NativeElements {
+    /**
+     * Bold text.
+     */
+    b: PropsWithChildren;
+    /**
+     * Italic text.
+     */
+    i: PropsWithChildren;
+    /**
+     * Underlined text.
+     */
+    u: PropsWithChildren;
+    /**
+     * Strikethrough text.
+     */
+    s: PropsWithChildren;
+    /**
+     * Spoiler.
+     */
+    spoiler: PropsWithChildren;
+    /**
+     * Inline URL or Telegram (deep) link.
+     *
+     * Read more about Telegram deep links:
+     * https://core.telegram.org/api/links
+     */
+    a: PropsWithChildren<{
+        /**
+         * Link to open.
+         *
+         * @example "https://google.com"
+         * @example "tg://resolve?domain=BotFather"
+         */
+        href: string;
+    }>;
+    /**
+     * Custom Telegram emoji.
+     */
+    emoji: {
+        /**
+         * Unique identifier of the custom emoji.
+         */
+        id: string;
+        /**
+         * Alternative emoji that will be shown instead of the custom emoji in
+         * places where a custom emoji cannot be displayed.
+         */
+        alt: string;
+    };
+    /**
+     * Inline fixed-width code.
+     */
+    code: PropsWithChildren;
+    /**
+     * Fixed-width code block with the optional programming language.
+     */
+    codeblock: PropsWithChildren<{
+        /**
+         * Programming or markup language of the block.
+         *
+         * Telegram uses libprisma for code highlighting,
+         * so the following languages are supported:
+         * https://github.com/TelegramMessenger/libprisma#supported-languages
+         */
+        lang?: StringWithSuggestions<PrismLanguage>;
+    }>;
+    /**
+     * Block quotation. Can be expandable or not.
+     */
+    blockquote: PropsWithChildren<{
+        expandable?: boolean;
+    }>;
+}
+export type TgxNode = TgxNode[] | TgxElement | string | number | boolean | null | undefined;
+export type PropsWithChildren<P = {}> = {
+    children?: TgxNode;
+} & P;
+export type FunctionComponent = (props: any) => TgxElement;
+export type TgxElement = TgxPlainValueElement | TgxFragmentElement | TgxTextElement;
+export interface TgxPlainValueElement {
+    type: 'plain';
+    value: string | number | boolean | null | undefined;
+}
+export interface TgxFragmentElement {
+    type: 'fragment';
+    subelements: TgxElement[];
+}
+export interface TgxTextElement {
+    type: 'text';
+    entity: TextEntity;
+    subelements: TgxElement[];
+}
+export type TextEntity = {
+    type: 'bold';
+} | {
+    type: 'italic';
+} | {
+    type: 'underline';
+} | {
+    type: 'strikethrough';
+} | {
+    type: 'spoiler';
+} | {
+    type: 'link';
+    url: string;
+} | {
+    type: 'custom-emoji';
+    id: string;
+    alt: string;
+} | {
+    type: 'code';
+} | {
+    type: 'codeblock';
+    language?: string;
+} | {
+    type: 'blockquote';
+    expandable: boolean;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@grom.js/tgx",
+  "type": "module",
+  "version": "0.5.0",
+  "description": "JSX runtime for composing Telegram messages",
+  "author": {
+    "name": "Vladislav Deryabkin",
+    "url": "https://evermake.me"
+  },
+  "license": "MIT",
+  "keywords": [
+    "jsx",
+    "telegram"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts"
+    },
+    "./jsx-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./dist/jsx-dev-runtime.d.ts",
+      "import": "./dist/jsx-dev-runtime.js"
+    }
+  },
+  "files": [
+    "./dist/"
+  ],
+  "engines": {
+    "node": "22.x"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "6.2.0",
+    "@types/node": "22.19.1",
+    "@vitest/coverage-v8": "4.0.10",
+    "bumpp": "10.3.1",
+    "eslint": "9.39.1",
+    "eslint-plugin-format": "1.0.2",
+    "taze": "19.9.0",
+    "vitest": "4.0.10"
+  },
+  "scripts": {
+    "build": "rm -rf ./dist/ && tsc --project ./tsconfig.lib.json",
+    "typecheck": "tsc --build --noEmit",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "test": "vitest --config ./vitest.config.ts",
+    "test:coverage": "vitest run --config ./vitest.config.ts --coverage",
+    "deps": "taze --interactive --write --include-locked",
+    "release": "bumpp"
+  }
+}