Skip to content

Latest commit

 

History

History
99 lines (71 loc) · 3.66 KB

readme.md

File metadata and controls

99 lines (71 loc) · 3.66 KB
Raw

The namespace JSX Project

The ultimate goal of this project is to become obsolete.

Context

namespace JSX provides typings for attributes and properties in HTML tags for various frameworks. This includes things like alignment styles or event listeners.

Typings is a loaded term, some expect FunctionMaybe<'left' | 'center' | 'right'> while others are content with just 'left' | 'center' | 'right'.

The core of the issue is that everything is based on the same underlying data, 'left' | 'center' | 'right', as these possible values come from the HTML specification.

Despite my best efforts, I couldn't find a comprehensive source, such as a JSON file, listing all tag names with their associated attributes/properties, possible values, descriptions, deprecation notices, and links.

One might expect this information to be available from the specification, TypeScript, or MDN. However, that doesn't seem to be the case. While MDN has made efforts to provide such a resource, it remains incomplete and somewhat disorganized.

The most reliable, complete and condensed source of data comes from the namespace JSX files of various modern JavaScript frameworks.

Unfortunately, a namespace JSX files tend to be "write once and forget" files, rarely updated unless the project becomes widely adopted. This is because there's no efficient way to generate or track updates for these files automatically.

Goals

You may be thinking this project provides the glorious json data. Spoiler: sorry to disappoint!

The ultimate goal of this project is to inspire the powers that be—HTML specification authors, MDN contributors, and TypeScript maintainers—to collaborate and provide this data in an easily consumable format.

The Project

This project helps track some of the most popular frameworks namespace JSX by parsing, mapping (when necessary), and merging their interfaces into a unified structure.

This makes it easier to quickly track and visualize whether any attribute or property for an HTML, SVG, or MathML element has been added or updated.

So far, that's better than nothing. It tries to unify the efforts dedicated to updating this data.

Since the project maps interfaces for tag names, attributes, and possible values, there's potential to enhance this data by adding descriptions for what each attribute or property does, deprecation notices, links to MDN, and more.

It's an ambitious, complex, and tedious task—likely the reason why such a comprehensive data file doesn't exist yet. I also refuse to rely on AI or blindly automate this process without carefully verifying the accuracy of the generated data.

Frameworks

List of frameworks so far: Solid, Voby, Vue, Preact, React.

Usage

To use this project, simply check the commit list. Over time, I will be commiting "updates" that show the diffs whenever a framework's namespace JSX changes. At least, that's the idea! See this example https://github.com/potahtml/namespace-jsx-project/commit/670323ea390fbc9d53ce889d7844b25f0e780ab7

Generating the data

  1. Clone this repository and run npm install. This will install the necessary frameworks and TypeScript to pull the data.

  2. Run npm run dev. This will create a jsx directory containing numerous .d.ts files, generated by parsing and merging the namespace JSX data from different frameworks.

  3. Periodically, run npm update followed by npm run dev. This will generate new data and show diffs, allowing you to see whether you need to update your own namespace JSX.

Sponsor

Check out the Sponsor link! With enough support, I'll be able to dedicate more time to this project and work on it more frequently. https://opencollective.com/tito-bouzout