Skip to content

A platform for community discussion. Free, open, simple.

DEV: Type the d-element dynamic-tag helper (#41687)

Sérgio Saquetim87fab4376cd4
diff --git a/frontend/discourse/app/ui-kit/helpers/d-element.gjs b/frontend/discourse/app/ui-kit/helpers/d-element.gjs
deleted file mode 100644
index da618ff41ed..00000000000
--- a/frontend/discourse/app/ui-kit/helpers/d-element.gjs
+++ /dev/null
@@ -1,82 +0,0 @@
-/* eslint-disable ember/no-classic-components */
-import ClassicComponent from "@ember/component";
-
-const empty = <template>
- {{! eslint-disable ember/template-no-yield-only }}{{yield}}
-</template>;
-const shortcuts = {
- div: <template>
- <div ...attributes>{{yield}}</div>
- </template>,
- span: <template>
- <span ...attributes>{{yield}}</span>
- </template>,
- form: <template>
- <form ...attributes>{{yield}}</form>
- </template>,
- a: <template>
- <a ...attributes>{{yield}}</a>
- </template>,
- button: <template>
- <button ...attributes>{{yield}}</button>
- </template>,
- td: <template>
- <td ...attributes>{{yield}}</td>
- </template>,
- aside: <template>
- <aside ...attributes>{{yield}}</aside>
- </template>,
-};
-
-/**
- * Returns a wrapper component with the given tagname, or an empty wrapper for an empty string.
- * Similar to the reference implementation of RFC389, with higher-performance shortcuts for common elements.
- *
- * Can be used directly in a template:
- *
- * ```hbs
- * {{#let (element @tagName) as |Wrapper|}}
- * <Wrapper class="pt-10 pb-10 ps-20 box-shadow" ...attributes>
- * Content
- * </Wrapper>
- * {{/let}}
- * ```
- *
- * Or in js:
- *
- * ```gjs
- * class MyComponent {
- * get wrapper(){
- * return element(this.args.tagName);
- * }
- *
- * <template>
- * <this.wrapper>
- * Content
- * </this.wrapper>
- * </template>
- * }
- * ```
- */
-export default function dElement(tagName) {
- if (typeof tagName !== "string") {
- throw new Error(
- `element helper only accepts string literals, you passed ${tagName}`
- );
- }
-
- if (tagName === null || tagName === undefined) {
- return null;
- } else if (tagName === "") {
- return empty;
- } else if (shortcuts[tagName]) {
- return shortcuts[tagName];
- } else {
- return <template>
- <ClassicComponent
- @tagName={{tagName}}
- ...attributes
- >{{yield}}</ClassicComponent>
- </template>;
- }
-}
diff --git a/frontend/discourse/app/ui-kit/helpers/d-element.gts b/frontend/discourse/app/ui-kit/helpers/d-element.gts
new file mode 100644
index 00000000000..cf3a168e1ec
--- /dev/null
+++ b/frontend/discourse/app/ui-kit/helpers/d-element.gts
@@ -0,0 +1,135 @@
+/* eslint-disable ember/no-classic-components */
+import ClassicComponent from "@ember/component";
+import type { TemplateOnlyComponent } from "@ember/component/template-only";
+import type { ComponentLike } from "@glint/template";
+
+/** The tag names that have a dedicated, higher-performance shortcut wrapper. */
+type ShortcutTag = "div" | "span" | "form" | "a" | "button" | "td" | "aside";
+
+/**
+ * A wrapper component for a single known tag, typed with the matching element so
+ * that `...attributes` and named attributes are checked against that element.
+ */
+type ElementWrapper<T extends keyof HTMLElementTagNameMap> =
+ TemplateOnlyComponent<{
+ Element: HTMLElementTagNameMap[T];
+ Blocks: { default: [] };
+ }>;
+
+/**
+ * A pass-through wrapper: it renders its block with no surrounding element, so it
+ * declares no `Element` (it does not accept `...attributes`).
+ */
+const empty: TemplateOnlyComponent<{ Blocks: { default: [] } }> = <template>
+ {{! eslint-disable ember/template-no-yield-only }}{{yield}}
+</template>;
+
+const shortcuts: { [K in ShortcutTag]: ElementWrapper<K> } = {
+ div: <template>
+ <div ...attributes>{{yield}}</div>
+ </template>,
+ span: <template>
+ <span ...attributes>{{yield}}</span>
+ </template>,
+ form: <template>
+ <form ...attributes>{{yield}}</form>
+ </template>,
+ a: <template>
+ <a ...attributes>{{yield}}</a>
+ </template>,
+ button: <template>
+ <button ...attributes>{{yield}}</button>
+ </template>,
+ td: <template>
+ <td ...attributes>{{yield}}</td>
+ </template>,
+ aside: <template>
+ <aside ...attributes>{{yield}}</aside>
+ </template>,
+};
+
+/**
+ * Returns a wrapper component that renders the given tag name, or an empty
+ * pass-through wrapper for an empty string. Modeled on the reference
+ * implementation of RFC389, with higher-performance shortcuts for common
+ * elements.
+ *
+ * When the tag name is a known HTML tag, the wrapper is typed with the matching
+ * element, so consumers get per-tag attribute checking (for example `href` on
+ * an anchor, `disabled` on a button); any other string falls back to a generic
+ * `HTMLElement` wrapper.
+ *
+ * Can be used directly in a template:
+ *
+ * ```hbs
+ * {{#let (dElement @tagName) as |Wrapper|}}
+ * <Wrapper class="pt-10 pb-10 ps-20 box-shadow" ...attributes>
+ * Content
+ * </Wrapper>
+ * {{/let}}
+ * ```
+ *
+ * Or in js:
+ *
+ * ```gjs
+ * class MyComponent {
+ * get wrapper() {
+ * return dElement(this.args.tagName);
+ * }
+ *
+ * <template>
+ * <this.wrapper>
+ * Content
+ * </this.wrapper>
+ * </template>
+ * }
+ * ```
+ *
+ * @param tagName - The HTML tag name to render, or an empty string for a
+ * pass-through wrapper that renders its block with no surrounding element.
+ * @returns A wrapper component that renders its block inside the given element.
+ */
+// The conditional distributes over unions, so a runtime-chosen tag such as
+// `"a" | "button"` yields a wrapper accepting any attribute valid on either arm.
+export default function dElement<T extends string>(
+ tagName: T
+): ComponentLike<{
+ Element: T extends keyof HTMLElementTagNameMap
+ ? HTMLElementTagNameMap[T]
+ : HTMLElement;
+ Blocks: { default: [] };
+}>;
+
+export default function dElement(
+ tagName: string
+): ComponentLike<{ Element: HTMLElement; Blocks: { default: [] } }> {
+ if (typeof tagName !== "string") {
+ throw new Error(
+ `element helper only accepts string literals, you passed ${tagName}`
+ );
+ }
+
+ // The concrete wrapper is one of several component shapes (element-typed
+ // shortcut, block-only pass-through, or classic-component fallback); the public
+ // overload above is the real contract, so the body erases the exact shape.
+ let wrapper: unknown;
+
+ if (tagName === "") {
+ wrapper = empty;
+ } else if (shortcuts[tagName as ShortcutTag]) {
+ wrapper = shortcuts[tagName as ShortcutTag];
+ } else {
+ wrapper = <template>
+ {{! @glint-nocheck: @ember/component (ClassicComponent) is not glint-typed }}
+ <ClassicComponent
+ @tagName={{tagName}}
+ ...attributes
+ >{{yield}}</ClassicComponent>
+ </template>;
+ }
+
+ return wrapper as ComponentLike<{
+ Element: HTMLElement;
+ Blocks: { default: [] };
+ }>;
+}
diff --git a/frontend/discourse/type-tests/ui-kit/d-element-test.gts b/frontend/discourse/type-tests/ui-kit/d-element-test.gts
new file mode 100644
index 00000000000..ed4bdd623af
--- /dev/null
+++ b/frontend/discourse/type-tests/ui-kit/d-element-test.gts
@@ -0,0 +1,44 @@
+import dElement from "discourse/ui-kit/helpers/d-element";
+
+declare const condition: boolean;
+declare const dynamicTag: string;
+
+// A single known tag yields a wrapper typed with that exact element.
+const Anchor = dElement("a");
+const Button = dElement("button");
+
+// A runtime-chosen union of known tags yields a wrapper that accepts any
+// attribute valid on either arm.
+const AnchorOrButton = dElement(condition ? "a" : "button");
+
+// An empty string (pass-through) and a dynamic tag name fall back to a generic
+// wrapper that only accepts global attributes.
+const Passthrough = dElement("");
+const Dynamic = dElement(dynamicTag);
+
+// Asserts the signature keeps per-tag attribute checking. Each valid usage must
+// compile; each invalid usage must be flagged (a missing error fails
+// pnpm lint:types via the glint-expect-error directives).
+const Test = <template>
+ {{! Per-tag attributes are accepted on the matching element }}
+ <Anchor href="/x">ok</Anchor>
+ <Button type="submit" disabled={{true}}>ok</Button>
+
+ {{! A union wrapper accepts attributes valid on either arm }}
+ <AnchorOrButton href="/x" type="submit" disabled={{true}}>ok</AnchorOrButton>
+
+ {{! The pass-through and dynamic fallbacks accept global attributes }}
+ <Passthrough class="c">ok</Passthrough>
+ <Dynamic class="c" data-x="y">ok</Dynamic>
+
+ {{! @glint-expect-error - disabled is button-only, not valid on an anchor }}
+ <Anchor disabled={{true}}>bad</Anchor>
+
+ {{! @glint-expect-error - href is anchor-only, not valid on a button }}
+ <Button href="/x">bad</Button>
+
+ {{! @glint-expect-error - an unknown attribute is rejected even on a union }}
+ <AnchorOrButton totallybogusattr="x">bad</AnchorOrButton>
+</template>;
+
+export default Test;