typing for `defineExtension` should allow partials

anentropic commented 6 days ago

Description

Docs for custom extensions show:

To define an extension you call the htmx.defineExtension() function:
<script>
  htmx.defineExtension('my-ext', {
    onEvent : function(name, evt) {
        console.log("Fired event: " + name, evt);
    }
  })
</script>
Typically, this is done in a stand-alone javascript file, rather than in an inline script tag. ... Extensions can override the following default extension points to add or change functionality:

However the current typing doesn't allow this - it requires a fully populated HtmxExtension object defining all the methods:

{
    init: function(api) {return null;},
    getSelectors: function() {return null;},
    onEvent : function(name, evt) {return true;},
    transformResponse : function(text, xhr, elt) {return text;},
    isInlineSwap : function(swapStyle) {return false;},
    handleSwap : function(swapStyle, target, fragment, settleInfo) {return false;},
    encodeParameters : function(xhr, parameters, elt) {return null;}
}

Testing

I made a working extension in my project and ignored the typing errors. (This is what prompted making this PR)

Changing the type to Partial<HtmxExtension> in my installed copy of htmx.esm.d.ts makes the typing errors go away and seems to reflect intended usage.

Checklist

[x] I have read the contribution guidelines
[x] I have targeted this PR against the correct branch (master for website changes, dev for source changes)
[x] This is either a bugfix, a documentation update, or a new feature that has been explicitly approved via an issue
[x] I ran the test suite locally (npm run test) and verified that it succeeded

MichaelWest22 commented 6 days ago

The dist/htmx.esm.d.ts is a compiled distribution output file and not an editable source file. This thing is built from the JSDoc comments in the src/htmx.js file like

/**
   * defineExtension initializes the extension and adds it to the htmx registry
   *
   * @see https://htmx.org/api/#defineExtension
   *
   * @param {string} name the extension name
   * @param {HtmxExtension} extension the extension definition
   */
  function defineExtension(name, extension) {

So this is where i think it would need updating. I would suggest making the change here on your local machine and then do a npm run dist to regenerate the esm.d.ts file and retest with this file to confirm it works as expected

anentropic commented 5 days ago

The dist/htmx.esm.d.ts is a compiled distribution output file and not an editable source file. This thing is built from the JSDoc comments in the src/htmx.js file

Ah thanks, I have amended that PR to update the correct file

MichaelWest22 commented 5 days ago

Sorry if you use npm run dist to test the distributed output you need to exclude the dist folder changes from the PR as normally only src/htmx.js is changed in dev PR's to make it easier to review changes. Dist only updates during release process normally

anentropic commented 5 days ago

Sorry if you use npm run dist to test the distributed output you need to exclude the dist folder changes from the PR as normally only src/htmx.js is changed in dev PR's to make it easier to review changes. Dist only updates during release process normally

Sorry yes, I realised that and have force pushed again to remove the latter commit

However that push appears to be stuck in GitHub 'processing' somehow: