feat: add HTMX typing, working off of @kitajs/html types.

[jaymanmdev]

In my personal project, I have types based off off of: https://github.com/kitajs/html/blob/master/htmx.d.ts

My revision: https://github.com/jaymanmdev/pokemon-roundest-with-htmx/blob/dev/src/htmx.d.ts - lines 1-3 are changed to extend Hono's HTML JSX interface.

We could make this a part of Hwy potentially? It probably doesn't fit as part of Hono. Whilst Hono is used widely with HTMX, Hwy is built for HTMX in a way. I am proposing a PR to add my revised d.ts file into Hwy - not sure where it would fit though. :)

[sjc5]

I wonder if it would work if you added it to the types in tsconfig.json

{
  "compilerOptions": {
    "types": ["@kitajs/html/htmx.d.ts"]
  }
}

Similar to this discussion: https://github.com/orgs/honojs/discussions/1767

Did you try that by any chance?

If that worked, I think it would be ideal, because then we can just make it part of the Hwy templater to add if your project (1) is in TypeScript and (2) is using HTMX (not relevant just yet, but we may offer more than just HTMX in the templater eventually). And potentially a new docs section on types and how to set them up if you didn't use the templater. (If it's not clear, by "templater" I am talking about create-hwy.)

I don't mind adding extra devDependencies for types, and ideally they're really easy to delete for users that don't want them, so this approach would be nice.

[jaymanmdev]

Hm, I haven't tried that. I don't think it would though? Hono's JSX interface is different. I'll give it a try real quick though. I agree it would be more convenient as a CLI option or something.

[jaymanmdev]

@sjc5 I have tried it in my personal project and it doesn't seem to work. Hono has a completely different JSX interface unfortunately.

Edit: My revised version wouldn't be terrible. We could still use it in the templater and make it apart of Hwy at something like hwy/types/htmx.d.ts or something like that, and then add:

"types": ["hwy/types/htmx.d.ts"]

only if the user chooses to use HTMX in their project.

Kita doesn't export the namespace either :/ I tried using kita still and doing something like:

import { type Htmx } from "@kitajs/html/htmx.js";

declare namespace Hono {
    interface HTMLAttributes extends Htmx.Attributes {}
}

to simplify our revision but it isn't going to be possible.

[sjc5]

Ok let me do a little thinking about how we want to structure the export in the lib, and whether we want to do a new package, or just keep in hwy core but make sure to isolate the export.

In the meantime, @jaymanmdev could you prepare a version of htmx.d.ts that adds in comments crediting (1) kita, (2) typed-htmx (what kita copied from), and (3) htmx itself? Make sure it includes their original licenses (MIT, or whatever) and copyright notices / dates / authors.

Then I'll figure out where would be best to export from and create a skeleton and have you fill it in. And over time, if we can convince Kita or typed-htmx to export specific types, then we can replace in this file without having users have to change their installed packages or their tsconfig.json.

[jaymanmdev]

Ok let me do a little thinking about how we want to structure the export in the lib, and whether we want to do a new package, or just keep in hwy core but make sure to isolate the export.

In the meantime, @jaymanmdev could you prepare a version of htmx.d.ts that adds in comments crediting (1) kita, (2) typed-htmx (what kita copied from), and (3) htmx itself? Make sure it includes their original licenses (MIT, or whatever) and copyright notices / dates / authors.

Then I'll figure out where would be best to export from and create a skeleton and have you fill it in. And over time, if we can convince Kita or typed-htmx to export specific types, then we can replace in this file without having users have to change their installed packages or their tsconfig.json.

Sure thing! Would you like me to inline the Licenses or link them? And should I keep in the original comments by typed-htmx and kita describing the types or strip them out?

[sjc5]

Ok let me do a little thinking about how we want to structure the export in the lib, and whether we want to do a new package, or just keep in hwy core but make sure to isolate the export. In the meantime, @jaymanmdev could you prepare a version of htmx.d.ts that adds in comments crediting (1) kita, (2) typed-htmx (what kita copied from), and (3) htmx itself? Make sure it includes their original licenses (MIT, or whatever) and copyright notices / dates / authors. Then I'll figure out where would be best to export from and create a skeleton and have you fill it in. And over time, if we can convince Kita or typed-htmx to export specific types, then we can replace in this file without having users have to change their installed packages or their tsconfig.json.

Sure thing! Would you like me to inline the Licenses or link them? And should I keep in the original comments by typed-htmx and kita describing the types or strip them out?

I think I'd do something like this (not the full licenses, just references to them):

/*
 * Adapted from @kita/html/htmx.d.ts, copied from source on ________, 2023
 * Also based on prior code from typed-htmx and htmx.org
 * 
 * # @kita/html/htmx.d.ts
 * - Original license: MIT (or whatever)
 * - Copyright 1975 Jon Snow
 * - Link to <file/repo>: _______________
 * 
 * # typed-htmx
 * ...
 * 
 * # htmx.org
 * ...
 */

Does that make sense?

[jaymanmdev]

Ok let me do a little thinking about how we want to structure the export in the lib, and whether we want to do a new package, or just keep in hwy core but make sure to isolate the export. In the meantime, @jaymanmdev could you prepare a version of htmx.d.ts that adds in comments crediting (1) kita, (2) typed-htmx (what kita copied from), and (3) htmx itself? Make sure it includes their original licenses (MIT, or whatever) and copyright notices / dates / authors. Then I'll figure out where would be best to export from and create a skeleton and have you fill it in. And over time, if we can convince Kita or typed-htmx to export specific types, then we can replace in this file without having users have to change their installed packages or their tsconfig.json.

Sure thing! Would you like me to inline the Licenses or link them? And should I keep in the original comments by typed-htmx and kita describing the types or strip them out?

I think I'd do something like this (not the full licenses, just references to them):

/*
 * Adapted from @kita/html/htmx.d.ts, copied from source on ________, 2023
 * Also based on prior code from typed-htmx and htmx.org
 * 
 * # @kita/html/htmx.d.ts
 * - Original license: MIT (or whatever)
 * - Copyright 1975 Jon Snow
 * - Link to <file/repo>: _______________
 * 
 * # typed-htmx
 * ...
 * 
 * # htmx.org
 * ...
 */

Does that make sense?

That makes sense :)

I was doing this:

/*
Author: Viet Dinh (Desdaemon)
Date: July 23rd, 2023
License: ISC (https://github.com/Desdaemon/typed-htmx/blob/main/LICENSE)
*/
/*
Author: @kitajs/html (license created by arthurfiorette)
Date: July 21st, 2023 (initially created), July 23rd, 2023 (revised)
License: Apache 2.0 (https://github.com/kitajs/html/blob/master/LICENSE)
*/
/*

*/

[sjc5]

Yep awesome, we're on the same page. Thanks!

[jaymanmdev]

Yep awesome, we're on the same page. Thanks!

Is my approach alright? or would you prefer something like your approach?

[sjc5]

Yep awesome, we're on the same page. Thanks!

Is my approach alright? or would you prefer something like your approach?

Nope what you're doing there looks great, any version of this that is clear / complete is great :)

[jaymanmdev]

Yep awesome, we're on the same page. Thanks!

Is my approach alright? or would you prefer something like your approach?

Nope what you're doing there looks great, any version of this that is clear / complete is great :)

Alrighty, cool! I'll get one over to you in a couple minutes.

[sjc5]

Yep awesome, we're on the same page. Thanks!

Is my approach alright? or would you prefer something like your approach?

Nope what you're doing there looks great, any version of this that is clear / complete is great :)

Alrighty, cool! I'll get one over to you in a couple minutes.

No rush at all, I won't decide on where to export from until at earliest tomorrow night, maybe later

[jaymanmdev]

No worries, is this complete enough? any revisions that should be made?

// These types have been adapted from https://github.com/kitajs/html/blob/master/htmx.d.ts - Also based on prior source from Desdaemon/typed-htmx and bigskysoftware/htmx

/*
Author: Desdaemon/typed-htmx - (license created by Desdaemon)
Date: July 23rd, 2023
License: ISC (https://github.com/Desdaemon/typed-htmx/blob/main/LICENSE)
*/
/*
Author: kitajs/html (license created and revised by arthurfiorette)
Date: July 21st, 2023 (initially created), July 23rd, 2023 (revised)
License: Apache 2.0 (https://github.com/kitajs/html/blob/master/LICENSE)
*/
/*
Author: bigskysoftware/htmx (license created by 1cg, revised by carson)
Date: April 14th, 2020 (initially created), April 27th, 2020 (revised)
License: BSD 2-Clause "Simplified" (https://github.com/bigskysoftware/htmx/blob/master/LICENSE)
*/

[sjc5]

That looks good @jaymanmdev, only thing is I try to keep comment line widths within the prettier default (80 chars)

Ok, I think we can probably do this in ~/packages/core/package.json:

Old

  "main": "dist/index.js",
  "files": [
    "dist"
  ],

New

  "exports": {
    ".": "./dist/index.js",
    "./types/htmx": "./types/htmx.d.ts"
  },
  "files": [
    "dist",
    "types"
  ],

Then just add your file into at ~/packages/core/types/htmx.d.ts. I'd like to keep it simple and out of the build step, but I think this should work.

If you want to do a PR with those changes against main, that would be great.

[jaymanmdev]

That looks good @jaymanmdev, only thing is I try to keep comment line widths within the prettier default (80 chars)

Ok, I think we can probably do this in ~/packages/core/package.json:

Old

  "main": "dist/index.js",
  "files": [
    "dist"
  ],

New

  "exports": {
    ".": "./dist/index.js",
    "./types/htmx": "./types/htmx.d.ts"
  },
  "files": [
    "dist",
    "types"
  ],

Then just add your file into at ~/packages/core/types/htmx.d.ts. I'd like to keep it simple and out of the build step, but I think this should work.

If you want to do a PR with those changes against main, that would be great.

Alrighty, will do! :)

[jaymanmdev]

@sjc5 there is already a packages/core/src/types.ts file. What should we do about this? Should we move these out into a separate types directory too? And should I put it in core/types/htmx.d.ts or core/src/types/htmx.d.ts?

[sjc5]

Let's keep it out of source and just right in the package root for now.

The types inside the src folder are internal types (and exported from the index file to the extent they should be in the main package). Best to treat them totally separate/distinct.

So I'd use the exact names / locations mentioned above

[jaymanmdev]

".": "./dist/index.js",
    "./types/htmx": "./types/htmx.d.ts"

Ah, yep, that makes sense! I'll submit the PR in just a minute.

Edit: PR created.

[sjc5]

Awesome thanks very much @jaymanmdev, I'll get a beta version of this out tomorrow and if all seems well get that merged in and released. I'm thinking to make it a 0.7.2 because 0.8.0 isn't ready yet, but no reason to postpone this.

[jaymanmdev]

Awesome thanks very much @jaymanmdev, I'll get a beta version of this out tomorrow and if all seems well get that merged in and released. I'm thinking to make it a 0.7.2 because 0.8.0 isn't ready yet, but no reason to postpone this.

Sounds good @sjc5! :)