Title: [language-server] TypeScript interface for element definitions (including for custom elements) · Issue #58483 · angular/angular · GitHub
Open Graph Title: [language-server] TypeScript interface for element definitions (including for custom elements) · Issue #58483 · angular/angular
X Title: [language-server] TypeScript interface for element definitions (including for custom elements) · Issue #58483 · angular/angular
Description: Wasn't sure if this belongs here or in https://github.com/angular/vscode-ng-language-service Which @angular/* package(s) are relevant/related to the feature request? @angular/language-service Description This is not a duplicate of #12045...
Open Graph Description: Wasn't sure if this belongs here or in https://github.com/angular/vscode-ng-language-service Which @angular/* package(s) are relevant/related to the feature request? @angular/language-service Descr...
X Description: Wasn't sure if this belongs here or in https://github.com/angular/vscode-ng-language-service Which @angular/* package(s) are relevant/related to the feature request? @angular/language-service D...
Opengraph URL: https://github.com/angular/angular/issues/58483
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[language-server] TypeScript interface for element definitions (including for custom elements)","articleBody":"Wasn't sure if this belongs here or in https://github.com/angular/vscode-ng-language-service\n\n### Which @angular/* package(s) are relevant/related to the feature request?\n\n`@angular/language-service`\n\n### Description\n\nThis is not a duplicate of\n\n- https://github.com/angular/angular/issues/12045\n\nInstead, this asks for an interface that we can easily augment to add type definitions for elements (built-in or custom, i.e. regardless if element names have hyphens or not).\n\nToday Custom Elements (a.k.a Web Components) are more prevalent than ever, and they can be used in many major frameworks with type checking (React, Preact, Vue, Svelte, Solid.js) and other frameworks without type checking (Angular, etc).\n\nIn this day and age, we need to be able to easily add type definitions for elements, especially custom elements, but it can be useful to be able to extend built-in element types too in case Angular definitions are not caught up with new elements landing in browsers.\n\n### Proposed solution\n\nAllow a TypeScript interface to be augmented, where the defintion of an element name to element type can be provided.\n\nThe proposal in \n\n- https://github.com/angular/angular/issues/12045\n\ncould map schemas to a TypeScript type for TypeScript users specifically (and to other types in other languages), but at least TypeScript users would have a cleaner simpler way to get moving. Implementing a cross-language schema is more difficult, plus JavaScript/TypeScript is what most people are using (I don't know if other language support even exists).\n\nAngular is the only remaining major framework to not have the ability for a specific TypeScript interface to be augmented:\n\n- **Solid.js**: augment `solid-js` module's `JSX.IntrinsicElements`\n- **Vue**: augment `vue` module's `GlobalComponents`\n- **Svelte**: augment the global `svelteHTML.IntrinsicElements` or augment `svelte/elements` module's `SvelteHTMLElements`\n- **React**: augment `react` module's `JSX.IntrinsicElements`\n- **Preact**: augment `preact` module's `JSX.IntrinsicElements` with the same definition as for react with react compat enabled\n- **Angular**: n/a\n\nThe usage could look this,\n\n```ts\n// `angular` module\n\nexport type GlobalCSSValues = 'inherit' | 'initial' | 'etc'\n\n// augmentable interface\nexport interface CSSProperties {\n\tvisibility: 'hidden' | 'visible' | 'collapse' | GlobalCSSValues\n\tdisplay: 'none' | 'block' | 'inline' | 'etc' | GlobalCSSValues\n\t// ... etc ...\n}\n\n// augmentable interface\nexport interface IntrinsicElements {\n div: { /* ... */ }\n button: : { /* ... */ }\n // ... etc ...\n}\n```\n```ts\n// user code\n\ndeclare module 'angular' {\n // user adds additional element definitions\n interface IntrinsicElements {\n 'my-element': {\n // this covers type checking for `[foo]=` property bindings\n foo?: number\n\n // this covers type checking for `[attr.foo]=` attribute bindings\n 'attr.foo'?: `${number}` | number\n\n // this covers type checking for `(some-event)=` event bindings\n 'on.some-event'?: SomeEvent\n }\n // plus generic types for Angular's special bindings can be provided out of the box (insead of the user writing them here):\n & type Obj = {\n\t// [class.foo]= bindings\n\t[K in `class.${string}`]?: boolean\n } & {\n\t// [style.known]= bindings\n\t[K in keyof CSSProperties as `style.${keyof CSSProperties}`]?: CSSProperties[K]\n } & {\n\t// [style.unknown]= bindings\n\t[K in `style.${string}`]?: string\n }\n }\n}\n\nclass SomeEvent extends Event { /* ... */ }\n```\n\nor similar.\n\nHere's an example of the special `style.` and `class.` binding types in TypeScript playground:\n\n[TypeScript playground](https://www.typescriptlang.org/play/?#code/C4TwDgpgBA4gNgewEYEM4GEDKmBqaCuEAzlALxQDkAlgHYAWEATlcBVAD6W0tVpucUIwAMYUAUGID0kqCnwBzALYQawFEjjRawJgDMUwiGO16D0LJgAKjBJEbAqxKAG8xASABuVIlSRU4LCAAXJR0VAAm4Sr8lF4+GhAxFMIIcHAoYESJHLCIqBjYeHCERO7h3mDpwZQ0CDTZAhoIwgDWSbQB9UlCojnwyGgWRSXu0lAAdJNQPROTYgC+EqCQUADySABWZC6jMgDawulEROO6CAgAuuR+NOU08qVuewDSULRQAAaHKMfjACTOIjAZj3eYfC4AfhCSHOmhQNAWUAAZDsoFAxnsgSBNKdzlcoDc7g8xGiXm8aFAWhAQAhdFALNZbEwHE4fp8sTiAVSaXSGTY7CyiGDISE+Uz7I4iC8LgsJCkaECoAgAIwhdZbciuNxnBAhZUAJgAzAAadEyJg2RhQAAU8nO4QAlLKxPLFQh9WrNtstckjicdRQ9UbTWMLQgrbb7U7Fi66m7DZ6NTs3L6fv7zoGoMDCCGZAgWs7XcAlQAWRPe9yp34BkL6OBZXNKgsxotKgCs5c1lY5EFxCEzFA0KDoFEbYYjdoQjsLceLCAAbJ3kxQe+NykRKigQAOhyOx4xLTbJ9OW7OlQB2Jc+1frzfbkKDxCtUdmpsLIA)\n\n\nThe generic `style.` and `class.` stuff can be provided as a default with a helper from `angular`, for example:\n\n```ts\n// user code\n\nimport type {IntrinsicBindings} from 'angular'\n\ndeclare module 'angular' {\n // user adds additional element definitions\n interface IntrinsicElements {\n 'my-element': IntrinsicBindings & {\n // this covers type checking for `[foo]=` property bindings\n foo?: number\n\n // this covers type checking for `[attr.foo]=` attribute bindings\n 'attr.foo'?: `${number}` | number\n\n // this covers type checking for `(some-event)=` event bindings\n 'on.some-event'?: SomeEvent\n }\n }\n}\n\nclass SomeEvent extends Event { /* ... */ }\n```\n\nHeck, you could even require the syntax to match, for sake of consistency with template syntax, and it is possible thanks to TypeScript template string types:\n\n```ts\n// user code\n\nimport type {IntrinsicBindings} from 'angular'\n\ndeclare module 'angular' {\n // user adds additional element definitions\n interface IntrinsicElements {\n 'my-element': IntrinsicBindings & {\n // this covers type checking for `[foo]=` property bindings\n foo?: number\n\n // this covers type checking for `[attr.foo]=` attribute bindings\n '[attr.foo]'?: `${number}` | number\n\n // this covers type checking for `(some-event)=` event bindings\n '(some-event)'?: SomeEvent\n }\n }\n}\n\nclass SomeEvent extends Event { /* ... */ }\n```\n```ts\n// and similar for the builtin props:\nexport type IntrinsicBindings = {\n // [class.foo]= bindings\n [K in `[class.${string}]`]?: boolean\n} & {\n // [style.known]= bindings\n [K in keyof CSSProperties as `[style.${keyof CSSProperties}]`]?: CSSProperties[K]\n} & {\n // [style.unknown]= bindings\n [K in `[style.${string}]`]?: string\n}\n```\n\nLibrary authors making custom element libraries can then make their own mapped-type helpers to map their element class properties, for example, to property, attribute, and event types, and they can even expand the `class.` and `style.` types if needed.\n\nFor example, given a class like this:\n\n```js\nimport {attribute, element, event} from 'some-lib' // For example, https://github.com/lume/element\n\nexport\n@element('my-element')\nclass MyElement extends HTMLElement {\n @attribute foo: \"foo\" | \"bar\" = \"foo\" // the initial value when no foo attribute is set (or foo attribute is removed)\n\n @event 'onsome-event': ((event: SomeEvent) => void) | null = null\n\n // ... implementation omitted ...\n}\n\nclass SomeEvent extends Event { /* ... */ }\n```\n\nthen a custom element author can define their own mapped type (as they already will be doing for React, Preact, Solid, Vue, Svelte, and others) to make it easy to define element types for their specific custom element library:\n\n```ts\nimport type {ElementAttributesForAngular} from 'some-lib/angular-types'\n\ndeclare module 'angular' {\n interface IntrinsicElements {\n // pick the properties to be used for Angular template types (any not listed are omitted from template type checking)\n 'my-element': ElementAttributesForAngular\u003cMyEl, 'foo' | 'onsome-event'>\n }\n}\n```\n\n### Alternatives considered\n\nImplement a schema, and the tooling needed to map that to TypeScript (and other language) definitions like in #12045? Good luck! I imagine that's why #12045 has been open for 8 years since 2016.\n\nA TypeScript interface would much easier to provide because TypeScript is the current foundation, and it would be immediately usable by a large amount of web developers. \n\nPeople can also use TypeScript definitions as a source for mapping to other languages, so even having just TypeScript support would be a better starting point than a more difficult schema idea.\n\nThere are already tools like [TypeScript-to-Flow](https://transform.tools/typescript-to-flow) converters, so starting with a TypeScript interface right now, would be valuable a lot more quickly than #12045.","author":{"url":"https://github.com/trusktr","@type":"Person","name":"trusktr"},"datePublished":"2024-11-03T00:03:32Z","url":"https://github.com/angular/angular/issues/58483"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:a72c7092-1fd7-278d-8710-50a2f11dc424 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | B480:785A9:1752862:1D953AA:6B013A33 |
| html-safe-nonce | 5f526d5faf97573ee4ac2f841d8fa08b0ba97783ca7e1ce571652a58e8aba201 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCNDgwOjc4NUE5OjE3NTI4NjI6MUQ5NTNBQTo2QjAxM0EzMyIsInZpc2l0b3JfaWQiOiIyMTUxMDY4ODc4MDQwNTQ1ODQzIiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 2d3c13a047084b897be1e7d180eefec37012d2b0e435d7fbfcc39b6216536370 |
| hovercard-subject-tag | issue:2630875269 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/angular/angular/58483/issue_layout |
| twitter:image | https://opengraph.githubassets.com/b92d32e56eae2008476d817fb4018495ed9722429295f77ea4acd5b96d4cfb4e/angular/angular/issues/58483 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/b92d32e56eae2008476d817fb4018495ed9722429295f77ea4acd5b96d4cfb4e/angular/angular/issues/58483 |
| og:image:alt | Wasn't sure if this belongs here or in https://github.com/angular/vscode-ng-language-service Which @angular/* package(s) are relevant/related to the feature request? @angular/language-service Descr... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | trusktr |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/angular/angular git https://github.com/angular/angular.git |
| octolytics-dimension-user_id | 139426 |
| octolytics-dimension-user_login | angular |
| octolytics-dimension-repository_id | 24195339 |
| octolytics-dimension-repository_nwo | angular/angular |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 24195339 |
| octolytics-dimension-repository_network_root_nwo | angular/angular |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width