discord-tsx-builder 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toan
+
+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,295 @@
+# discord-tsx-builder
+
+![alt text](./assets/banner.png "DiscordTsx Banner")
+
+Represent Discord Embeds and Components using TSX instead of raw JSON or long builder chains.
+
+## Install
+
+```bash
+npm install discord-tsx-builder
+```
+
+```bash
+pnpm add discord-tsx-builder
+```
+
+```bash
+yarn add discord-tsx-builder
+```
+
+## Use in another project
+
+`discord-tsx-builder` is a normal npm library. In your own project:
+
+1. Install `discord-tsx-builder`
+2. Set TS JSX runtime config
+3. Write TSX with `discord-tsx-builder` tags
+4. Recommended: run postbuild transform to bake payload objects into built JS
+
+### TS config
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "discord-tsx-builder",
+    "moduleResolution": "nodenext"
+  }
+}
+```
+
+`moduleResolution: "nodenext"` (or `node16`/`bundler`) is important so `discord-tsx-builder/jsx-runtime` resolves correctly.
+
+## Postbuild mode (Highly Recommended)
+
+After `tsc`, run the transformer:
+
+```bash
+discord-tsx-builder-postbuild ./dist
+```
+
+This rewrites compiled `_jsx/_jsxs` trees rooted at `<DiscordEmbed>` / `<DiscordComponent>` into object literals directly in emitted JS.
+
+Example:
+
+`<Text>hello</Text>` becomes:
+
+```ts
+{ type: 10, content: "hello" }
+```
+
+Suggested scripts in consumer project:
+
+```json
+{
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "discord-tsx-builder-postbuild ./dist"
+  }
+}
+```
+
+## Runtime mode
+
+TSX is converted to object payloads when code executes.
+
+```tsx
+import { DiscordEmbed, Title, Description } from "discord-tsx-builder";
+
+const name = "World";
+const embed = (
+  <DiscordEmbed color="#ffffff">
+    <Title>Discord Tsx Builder Testing</Title>
+    <Description>Hello {name}</Description>
+  </DiscordEmbed>
+);
+
+// embed is plain JSON-like data at runtime
+```
+
+## Tag reference
+
+All tags are exported from `discord-tsx-builder`.
+
+### Embed root
+
+Use `<DiscordEmbed>` as the root.
+
+Props:
+
+- `color?: string | number` (`"#ffffff"` or `16777215`)
+
+Supported children:
+
+- `<Title>`
+- `<Description>`
+- `<Url>`
+- `<Timestamp>`
+- `<Color>`
+- `<Author>`
+- `<Footer>`
+- `<Image>`
+- `<Thumbnail>`
+- `<Fields>`
+- `<Field>`
+
+### Embed tags
+
+`<Title>`:
+
+- Children text -> `title`
+
+`<Description>`:
+
+- Children text -> `description`
+
+`<Url>`:
+
+- `url` prop or children text -> `url`
+
+`<Timestamp>`:
+
+- `value` prop or children text -> `timestamp`
+
+`<Color>`:
+
+- `value` prop or children text -> `color` (hex strings are converted to int)
+
+`<Image>`:
+
+- `url` prop or children text -> `image.url`
+
+`<Thumbnail>` (inside embed):
+
+- `url` or `src` prop or children text -> `thumbnail.url`
+
+`<Author>`:
+
+- Props: `name`, `iconUrl` (`icon_url` also accepted), `url`
+- Children alternatives: `<AuthorName>`, `<AuthorIconUrl>`, `<AuthorUrl>`
+
+`<Footer>`:
+
+- Props: `text`, `iconUrl` (`icon_url` also accepted)
+- Children alternatives: `<FooterText>`, `<FooterIconUrl>`
+
+`<Fields>`:
+
+- Grouping wrapper for `<Field>`
+
+`<Field>`:
+
+- Props: `name`, `value`, `inline`
+- Or children: `<FieldName>`, `<FieldValue>`
+- Requires both name and value
+
+### Components root
+
+Use `<DiscordComponent>` as the root. It returns:
+
+- `{ components: [...] }` for legacy-only layouts
+- `{ components: [...], flags: 32768 }` when v2 components are used
+
+If you are setting components in a response, set the components and the flags separately.
+`interaction.reply({ components: components.components, flags: components.flags })`
+
+### Legacy components
+
+`<ActionRow>`:
+
+- Children: interactive components only (`<Button>` or any select menu)
+- Select rule: a select menu must be the only child in the row
+- Button rule: max 5 buttons in the row
+
+`<Button>`:
+
+- Props: `customId`, `style`, `label`, `emoji`, `url`, `disabled`, `skuId`
+- If `label` is omitted, children text becomes label
+- `style` accepts number or one of: `primary`, `secondary`, `success`, `danger`, `link`, `premium`
+
+`<StringSelectMenu>`:
+
+- Props: `customId`, `placeholder`, `minValues`, `maxValues`, `disabled`
+- Options can come from `options` prop array or `<Option>` children
+
+`<UserSelectMenu>`, `<RoleSelectMenu>`, `<MentionableSelectMenu>`, `<ChannelSelectMenu>`:
+
+- Props: `customId`, `placeholder`, `minValues`, `maxValues`, `disabled`, `defaultValues`
+- `<ChannelSelectMenu>` also supports `channelTypes`
+
+`<Option>`:
+
+- Props: `label`, `value`, `description`, `emoji`, `default`
+- Used by `<StringSelectMenu>`
+
+### V2 components
+
+`<Container>`:
+
+- Props: `accentColor` (`accent_color` also accepted), `spoiler`
+- Children supported: `<Text>`, `<Section>`, `<MediaGallery>`, `<File>`, `<Separator>`, `<ActionRow>`, `<Button>`, select menus
+- If `<Button>`/select appears directly, it is wrapped into an action row automatically
+
+`<Text>`:
+
+- Children text -> `{ type: 10, content: ... }`
+
+`<Section>`:
+
+- Needs at least one text block
+- Text via direct text, `<Text>`, or `<SectionText>`
+- Accessory via `<SectionAccessory>` with one child: `<Button>` or `<Thumbnail>`
+
+`<Thumbnail>` (inside section accessory or top-level v2):
+
+- Props: `url` or `src`, optional `description`, `spoiler`
+
+`<MediaGallery>`:
+
+- Props: `items` array (optional)
+- Or `<MediaItem>` children
+
+`<MediaItem>`:
+
+- Props: `url` or `src`, optional `description`, `spoiler`
+
+`<File>`:
+
+- Props: `url` or `src`
+
+`<Separator>`:
+
+- Props: `divider`, `spacing`
+
+### Top-level children allowed in `<DiscordComponent>`
+
+- Legacy: `<ActionRow>`
+- V2: `<Container>`, `<Section>`, `<Text>`, `<Thumbnail>`, `<MediaGallery>`, `<File>`, `<Separator>`
+- Interactive tags at top-level (`<Button>` or select menus) are auto-wrapped into action rows and treated as v2
+
+See full usage in:
+
+- [examples/tag-showcase.tsx](./examples/tag-showcase.tsx)
+
+## How Babel is handled
+
+You do not need Babel config in your app.
+
+- Your app still builds with `tsc` (or your normal TS pipeline).
+- `discord-tsx-builder` runtime mode needs no Babel.
+- `discord-tsx-builder-postbuild` internally uses Babel parser/traverse/generator APIs to parse emitted JS and rewrite only the Discord TSX runtime call trees.
+- Those Babel packages are regular runtime dependencies of `discord-tsx-builder`, so running the CLI in another project works after install.
+
+So: no `.babelrc`, no Babel plugin setup, no manual AST wiring in your project.
+
+## Comparison (raw JSON vs builders vs discord-tsx-builder)
+
+See:
+
+- [examples/raw-json.ts](./examples/raw-json.ts)
+- [examples/discordjs-builders.md](./examples/discordjs-builders.md)
+- [examples/runtime-vs-postbuild.tsx](./examples/runtime-vs-postbuild.tsx)
+- [examples/README.md](./examples/README.md)
+
+## Validation rules
+
+- Select menus inside `<ActionRow>` must be the only child in that row.
+- V2 components automatically set message flag `32768` (`IsComponentsV2`).
+
+## Local example commands
+
+```bash
+yarn examples:check
+yarn examples:runtime
+yarn examples:postbuild
+```
+
+## Tests
+
+```bash
+yarn test:runtime
+yarn test:build
+yarn test
+```
+

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./tags.js";
+export * from "./runtime.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./tags.js";
+export * from "./runtime.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC"}

package/dist/jsx-dev-runtime.d.ts

@@ -0,0 +1,2 @@
+export { Fragment, jsxDEV } from "./jsx-runtime.js";
+//# sourceMappingURL=jsx-dev-runtime.d.ts.map

package/dist/jsx-dev-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-dev-runtime.d.ts","sourceRoot":"","sources":["../src/jsx-dev-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/jsx-dev-runtime.js

@@ -0,0 +1,2 @@
+export { Fragment, jsxDEV } from "./jsx-runtime.js";
+//# sourceMappingURL=jsx-dev-runtime.js.map

package/dist/jsx-dev-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-dev-runtime.js","sourceRoot":"","sources":["../src/jsx-dev-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,17 @@
+import type { DiscordTagComponent } from "./tags.js";
+export declare const Fragment: unique symbol;
+type JsxType = DiscordTagComponent<unknown> | ((props: Record<string, unknown>) => unknown) | typeof Fragment;
+export declare function jsx(type: JsxType, props: Record<string, unknown> | null, key?: unknown): unknown;
+export declare function jsxs(type: JsxType, props: Record<string, unknown> | null, key?: unknown): unknown;
+export declare function jsxDEV(type: JsxType, props: Record<string, unknown> | null, key: unknown, _isStaticChildren: boolean, _source: unknown, _self: unknown): unknown;
+export declare namespace JSX {
+    type Element = unknown;
+    interface ElementChildrenAttribute {
+        children: unknown;
+    }
+    interface IntrinsicElements {
+        [elemName: string]: Record<string, unknown>;
+    }
+}
+export {};
+//# sourceMappingURL=jsx-runtime.d.ts.map

package/dist/jsx-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-runtime.d.ts","sourceRoot":"","sources":["../src/jsx-runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD,eAAO,MAAM,QAAQ,eAA6C,CAAC;AAEnE,KAAK,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,GAAG,OAAO,QAAQ,CAAC;AAoC9G,wBAAgB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAEhG;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,CAEjG;AAED,wBAAgB,MAAM,CACpB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACrC,GAAG,EAAE,OAAO,EACZ,iBAAiB,EAAE,OAAO,EAC1B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO,GACb,OAAO,CAET;AAED,yBAAiB,GAAG,CAAC;IACnB,KAAY,OAAO,GAAG,OAAO,CAAC;IAC9B,UAAiB,wBAAwB;QACvC,QAAQ,EAAE,OAAO,CAAC;KACnB;IACD,UAAiB,iBAAiB;QAChC,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC7C;CACF"}

package/dist/jsx-runtime.js

@@ -0,0 +1,36 @@
+import { renderRoot } from "./runtime.js";
+export const Fragment = Symbol.for("discord-tsx-builder.fragment");
+function isTagComponent(value) {
+    return typeof value === "function" && "$$discordTag" in value;
+}
+function baseCreateElement(type, props, key) {
+    const normalizedProps = props ?? {};
+    if (key !== undefined) {
+        normalizedProps.key = key;
+    }
+    if (type === Fragment) {
+        return normalizedProps.children ?? null;
+    }
+    if (isTagComponent(type)) {
+        const element = {
+            __discordTsxElement: true,
+            tag: type.$$discordTag,
+            props: normalizedProps
+        };
+        return renderRoot(element);
+    }
+    if (typeof type === "function") {
+        return type(normalizedProps);
+    }
+    throw new Error("Invalid JSX tag passed to discord-tsx-builder runtime.");
+}
+export function jsx(type, props, key) {
+    return baseCreateElement(type, props, key);
+}
+export function jsxs(type, props, key) {
+    return baseCreateElement(type, props, key);
+}
+export function jsxDEV(type, props, key, _isStaticChildren, _source, _self) {
+    return baseCreateElement(type, props, key);
+}
+//# sourceMappingURL=jsx-runtime.js.map

package/dist/jsx-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-runtime.js","sourceRoot":"","sources":["../src/jsx-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA0B,MAAM,cAAc,CAAC;AAGlE,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;AAInE,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,UAAU,IAAI,cAAc,IAAI,KAAK,CAAC;AAChE,CAAC;AAED,SAAS,iBAAiB,CACxB,IAAa,EACb,KAAqC,EACrC,GAAa;IAEb,MAAM,eAAe,GAAG,KAAK,IAAI,EAAE,CAAC;IACpC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,eAAe,CAAC,GAAG,GAAG,GAAG,CAAC;IAC5B,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO,eAAe,CAAC,QAAQ,IAAI,IAAI,CAAC;IAC1C,CAAC;IAED,IAAI,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,OAAO,GAAsB;YACjC,mBAAmB,EAAE,IAAI;YACzB,GAAG,EAAE,IAAI,CAAC,YAAY;YACtB,KAAK,EAAE,eAAe;SACvB,CAAC;QACF,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC,eAAe,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,IAAa,EAAE,KAAqC,EAAE,GAAa;IACrF,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAa,EAAE,KAAqC,EAAE,GAAa;IACtF,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,MAAM,CACpB,IAAa,EACb,KAAqC,EACrC,GAAY,EACZ,iBAA0B,EAC1B,OAAgB,EAChB,KAAc;IAEd,OAAO,iBAAiB,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;AAC7C,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,20 @@
+import type { TagName } from "./tags.js";
+export interface DiscordTsxElement {
+    __discordTsxElement: true;
+    tag: TagName | (string & {});
+    props: Record<string, unknown>;
+}
+export type DiscordTsxNode = DiscordTsxElement | string | number | boolean | null | undefined | DiscordTsxNode[];
+export interface DiscordComponentsPayload {
+    components: Record<string, unknown>[];
+    flags?: number;
+}
+export declare const MessageFlags: {
+    readonly IsComponentsV2: number;
+};
+export declare function isDiscordTsxElement(value: unknown): value is DiscordTsxElement;
+export declare function normalizeChildren(input: unknown): DiscordTsxNode[];
+export declare function renderDiscordEmbed(node: DiscordTsxNode): Record<string, unknown>;
+export declare function renderDiscordComponents(node: DiscordTsxNode): DiscordComponentsPayload;
+export declare function renderRoot(node: DiscordTsxNode): unknown;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,WAAW,iBAAiB;IAChC,mBAAmB,EAAE,IAAI,CAAC;IAC1B,GAAG,EAAE,OAAO,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,MAAM,cAAc,GACtB,iBAAiB,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT,cAAc,EAAE,CAAC;AAErB,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,YAAY;;CAEf,CAAC;AAsCX,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAO9E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,EAAE,CAUlE;AAijBD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGhF;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,wBAAwB,CAGtF;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAcxD"}