NAME

Uniform::HTMX::PSGI - Explicit framework-agnostic htmx adapter for the PSGI/Plack ecosystem

SYNOPSIS

Pattern A: Implicit Environment Injection (Middleware Friendly)

use Uniform::HTMX::PSGI;

my $app = sub {
    my $env = shift;
    my $hx  = Uniform::HTMX::PSGI->new($env);

    if ($hx->is_htmx) {
        $hx->res_retarget('#status-banner')->apply;

        my $htmx_headers = $env->{'htmx.outbound'} || {};
        return [ 200, [ 'Content-Type' => 'text/html', %$htmx_headers ], [ '<p>Updated!</p>' ] ];
    }
    return [ 200, [ 'Content-Type' => 'text/html' ], [ '<h1>Home</h1>' ] ];
};

Pattern B: Explicit Plack::Response Target Mapping

use Plack::Request;
use Plack::Response;
use Uniform::HTMX::PSGI;

my $app = sub {
    my $env = shift;
    my $req = Plack::Request->new($env);
    my $res = $req->new_response(200);

    my $hx  = Uniform::HTMX::PSGI->new($env);

    if ($hx->is_htmx) {
        $res->content_type('text/html');
        $res->body('<p>Updated Fragment!</p>');

        # Directly updates the $res object headers!
        $hx->res_retarget('#status-banner')->apply($res);
    }

    return $res->finalize;
};

DESCRIPTION

Uniform::HTMX::PSGI maps the core Uniform::HTMX specification layer directly to raw web execution environments built on the PSGI/Plack specification.

METHODS

new( $env )

Validates and instantiates the client context mapper. Requires a valid, active PSGI environment hash reference ($env). Automatically normalizes inbound environment keys via the core parent class.

apply( [ $plack_response ] )

Flushes accumulated response modifiers. If passed an explicit Plack::Response object, it modifies its header stack directly. Otherwise, it stashes compiled headers inside an isolated reference token located at $env->{'htmx.outbound'}.

Returns $self to support method chaining.

AUTHOR

Joshua S. Day <HAX@cpan.org>

LICENSE

Licensed under the same terms as Uniform::HTMX.