File Coverage

=head1 NAME

HTML::D3 - A simple Perl module for generating charts using D3.js.

=head1 VERSION

Version 0.20

=cut

=head1 SYNOPSIS

    use HTML::D3;

    my $chart = HTML::D3->new(
        width => 1024,
        height => 768,
        title => 'Sample Bar Chart'
    );

    my $data = [
        ['Category 1', 10],
        ['Category 2', 20],
        ['Category 3', 30]
    ];

    my $html = $chart->render_bar_chart($data);
    print $html;

    $chart = HTML::D3->new(title => 'Sales Data');

    $data = [
        ['Product A', 100],
        ['Product B', 150],
        ['Product C', 200]
    ];

    $html = $chart->render_line_chart($data);
    print $html;

=head1 DESCRIPTION

HTML::D3 is a Perl module that provides functionality to create simple charts using D3.js.
The module generates HTML and JavaScript code to render the chart in a web browser.

=head1 METHODS

The C<=head3 API SPECIFICATION> subsections use L<Params::Validate::Strict>
schema syntax (C<< type => 'arrayref' >> etc.) as a documentation convention.
The module is also used at runtime in C<new()> to validate constructor
arguments; it is therefore a required runtime dependency.  The schemas describe
the parameter contract in machine-readable notation and can be plumbed into a
WAF or test generator if desired.

=head2 new

    my $chart = HTML::D3->new(%args);

Creates a new HTML::D3 object.
Accepts the following optional arguments:

=over 4

=item * C<width> - The width of the chart (default: 800).

=item * C<height> - The height of the chart (default: 600).

=item * C<title> - The title of the chart (default: 'Chart').

=item * C<responsive> - If true, SVG elements are rendered with
C<viewBox> and C<width="100%" height="auto"> instead of fixed pixel
dimensions, so the chart scales fluidly with its container.
For snippet methods the per-call C<< opts => { responsive => 1 } >>
takes precedence over this object-level setting (default: 0).

=back

=cut

=head2 render_bar_chart

    my $html = $chart->render_bar_chart($data);

Generates HTML and JavaScript code to render a bar chart. Accepts the following arguments:

=over 4

=item * C<$data> - An array reference containing data points. Each data point should
be an array reference with two elements: the label (string) and the value (numeric).

=back

Returns a string containing the HTML and JavaScript code for the chart.

=head3 Errors

=over 4

=item * Throws C<Data is not optional> when C<$data> is C<undef>.

=item * Throws C<Data must be an array of arrays> when C<$data> is not an ARRAY reference.

=back

=head3 API SPECIFICATION

=head4 Input

    {
        data => {
                type => 'arrayref',
                element_type => [ 'string', 'number' ]
        }
    }

    Each element of C<$data> is C<[ Str, Num ]>; passing C<undef> or a
    non-arrayref dies.

=head4 Output

    Str -- complete HTML5 document starting with C<< <!DOCTYPE html> >>;
           D3.js loaded from CDN; bar chart rendered with C<d3.scaleBand>.

=cut

=head2 render_animated_bar_chart

    my $html = $chart->render_animated_bar_chart($data);

Generates HTML and JavaScript code to render a bar chart where each bar grows
upward from the baseline on page load.  Bars are staggered so they rise
one-after-another from left to right.
Accepts the following arguments:

=over 4

=item * C<$data> - An array reference of data points.  Each data point is an
array reference with two elements: the label (string) and the value (numeric).

=back

Returns a string containing the complete HTML5 document.

=head3 Errors

=over 4

=item * Throws C<Data is not optional> when C<$data> is C<undef>.

=item * Throws C<Data must be an array of arrays> when C<$data> is not an ARRAY reference.

=back

=head3 API SPECIFICATION

=head4 Input

    {
        data => { type => 'arrayref' },
    }

    Each element of C<$data> is C<[ Str, Num ]>; passing C<undef> or a
    non-arrayref dies.

=head4 Output

    Str -- complete HTML5 document; each bar animates from height=0 upward
           using C<d3.transition()> with a staggered per-bar delay.

=cut

=head2 render_line_chart

    my $html = $chart->render_line_chart($data);

Generates HTML and JavaScript code to render a line chart. Accepts the following arguments:

=over 4

=item * C<$data> - An array reference containing data points. Each data point should
be an array reference with two elements: the label (string) and the value (numeric).

=back

Returns a string containing the HTML and JavaScript code for the chart.

=head3 Errors

=over 4

=item * Throws C<Data must be an array of arrays> when C<$data> is not an ARRAY reference.

=back

=head3 API SPECIFICATION

=head4 Input

    {
        data => { type => 'arrayref' },
    }

    Each element of C<$data> is C<[ Str, Num ]>; passing C<undef> or a
    non-arrayref dies.

=head4 Output

    Str -- complete HTML5 document; line chart with C<d3.scalePoint> and C<d3.line()>.

=cut

=head2 render_animated_line_chart

    my $html = $chart->render_animated_line_chart($data);

Generates HTML and JavaScript code to render a line chart where the line
draws itself from left to right on page load, followed by each data-point
circle fading in once the line is complete.
Accepts the following arguments:

=over 4

=item * C<$data> - An array reference of data points.  Each data point is an
array reference with two elements: the label (string) and the value (numeric).

=back

Returns a string containing the complete HTML5 document.

=head3 Errors

=over 4

=item * Throws C<Data must be an array of arrays> when C<$data> is not an ARRAY reference.

=back

=head3 API SPECIFICATION

=head4 Input

    {
        data => { type => 'arrayref' },
    }

    Each element of C<$data> is C<[ Str, Num ]>; passing C<undef> or a
    non-arrayref dies.

=head4 Output

    Str -- complete HTML5 document; the line path animates via
           C<stroke-dashoffset> with C<d3.easeLinear>; data-point circles
           fade in with C<opacity> after the line transition completes.

=cut

=head2 render_pie_chart

    my $html = $chart->render_pie_chart($data);
    my $html = $chart->render_pie_chart($data, { separator => ':' });

Generates HTML and JavaScript code to render a pie chart.
Each slice is coloured with C<d3.schemeCategory10>; percentage labels appear
inside each slice and a colour legend is shown to the right of the pie.
Accepts the following arguments:

=over 4

=item * C<$data> - An array reference of data points.  Each data point is an
array reference with two elements: the label (string) and the value (numeric).

=item * C<%opts> - Optional hashref of options.

=over 8

=item * C<separator> (string, default C<'/'>) - Character shown between the
label and value in the SVG legend.

=back

=back

Returns a string containing the complete HTML5 document.

=head3 Errors

=over 4

=item * Throws C<Data is not optional> when C<$data> is C<undef>.

=item * Throws C<Data must be an array of arrays> when C<$data> is not an ARRAY reference.

=back

=head3 API SPECIFICATION

=head4 Input

    {
        data => {
                type => 'arrayref',
                element_type => [ 'string', 'number' ]
        },
        opts => { type => 'hashref', optional => 1, default => {} },
    }

    Each element of C<$data> is C<[ Str, Num ]>; passing C<undef> or a
    non-arrayref dies.
    Recognised C<opts> key: C<separator> (string, default C<'/'>)
    - character shown between label and value in the SVG legend.

=head4 Output

    Str -- complete HTML5 document; pie rendered with C<d3.pie()> and
           C<d3.arc()>; slices coloured with C<d3.schemeCategory10>;
           percentage label inside each slice; legend to the right.

=cut

=head2 render_animated_pie_chart

    my $html = $chart->render_animated_pie_chart($data);
    my $html = $chart->render_animated_pie_chart($data, { separator => ':' });

Generates HTML and JavaScript code to render an animated pie chart where each
slice fans out from zero angle on page load using C<attrTween> and
C<d3.interpolate>.  Percentage labels fade in once all slices are drawn.
Accepts the following arguments:

=over 4

=item * C<$data> - An array reference of data points.  Each data point is an
array reference with two elements: the label (string) and the value (numeric).

=item * C<%opts> - Optional hashref of options.

=over 8

=item * C<separator> (string, default C<'/'>) - Character shown between the
label and value in the SVG legend.

=back

=back

Returns a string containing the complete HTML5 document.

=head3 Errors

=over 4

=item * Throws C<Data is not optional> when C<$data> is C<undef>.

=item * Throws C<Data must be an array of arrays> when C<$data> is not an ARRAY reference.

=back

=head3 API SPECIFICATION

=head4 Input

    {
        data => {
                type => 'arrayref',
                element_type => [ 'string', 'number' ]
        },
        opts => { type => 'hashref', optional => 1, default => {} },
    }

    Each element of C<$data> is C<[ Str, Num ]>; passing C<undef> or a
    non-arrayref dies.
    Recognised C<opts> key: C<separator> (string, default C<'/'>)
    - character shown between label and value in the SVG legend.

=head4 Output

    Str -- complete HTML5 document; slices animate via C<attrTween> with
           C<d3.interpolate> (1000 ms); percentage labels fade in afterwards.

=cut

=head2 render_pie_chart_snippet

    my $fragment = $chart->render_pie_chart_snippet(\@slices);
    my $fragment = $chart->render_pie_chart_snippet(\@slices, \%opts);
    # $fragment->{svg_id} - always 'pie_chart'
    # $fragment->{html}   - embeddable fragment; caller must load D3 v7

Generates an embeddable pie or donut chart fragment for use in existing HTML
layouts.  Returns C<{ svg_id =E<gt> 'pie_chart', html =E<gt> Str }>.  The
caller is responsible for loading D3 v7 before embedding the fragment.

=head3 Data format

Each element of C<\@slices> is C<[$label, $value]> or C<[$label, $value, \%extra]>.
Negative values are silently converted to their absolute value.  Zero-value
slices are silently omitted.  C<\%extra> key/value pairs are shown as
additional rows in the hover tooltip.

=head3 Options (C<\%opts>)

=over 4

=item * C<animated> (bool, default 0) - fan slices in from arc-length 0 on
first render using C<attrTween> / C<d3.easeBackOut> (800 ms, staggered).
Respects C<prefers-reduced-motion>.

=item * C<donut> (bool, default 0) - render as a donut chart (inner radius
38% of outer radius); the total sum appears in the centre hole.

=item * C<sort_slices> (string, default C<'none'>) - C<'value'> for
largest-first, C<'label'> for alphabetical, C<'none'> for input order.

=item * C<max_slices> (int, default 0) - when E<gt> 0, only the top N-1
slices are shown individually; the rest are collapsed into an C<"Other"> slice.

=item * C<legend> (bool, default 1) - render an HTML legend panel beside the chart.

=item * C<color_scheme> (string, default C<'tableau10'>) - D3 categorical
colour scheme.  Supported: C<tableau10>, C<category10>, C<set2>, C<set3>,
C<paired>.

=item * C<separator> (string, default C<'/'>) - Character shown between the
label and value in each legend entry (e.g. C<'/'> produces
C<Label / 12.34 (42.0%)>, C<':'> produces C<Label : 12.34 (42.0%)>).

=back

=head3 Errors

=over 4

=item * Throws C<Data must be an array of arrays> when C<\@slices> is not an ARRAY reference.

=back

=head3 API SPECIFICATION

=head4 Input

    {
        data => { type => 'arrayref' },
        opts => { type => 'hashref', optional => 1, default => {} },
    }

    Each element of C<$data> is C<[ Str, Num ]> or C<[ Str, Num, HashRef ]>;
    passing C<undef> or a non-arrayref dies.
    Recognised C<opts> keys: C<animated> (boolean, default C<0>),
    C<donut> (boolean, default C<0>), C<sort_slices> (string: C<'value'>,
    C<'label'>, or C<'none'>; default C<'none'>), C<max_slices> (integer,
    default C<0>), C<legend> (boolean, default C<1>),
    C<color_scheme> (string, default C<'tableau10'>),
    C<separator> (string, default C<'/'> - shown between label and value in
    legend entries).

=head4 Output

    HashRef -- C<{ svg_id =E<gt> 'pie_chart', html =E<gt> Str }>;
               embeddable fragment; no DOCTYPE, no page shell, no D3 CDN tag.

=cut

=head2 render_heatmap_snippet

    my $fragment = $chart->render_heatmap_snippet(\@triples);
    my $fragment = $chart->render_heatmap_snippet(\@triples, \%opts);
    # $fragment->{svg_id} - always 'heatmap'
    # $fragment->{html}   - embeddable fragment; caller must load D3 v7

Generates an embeddable grid heatmap for use in existing HTML layouts.
Each cell sits at the intersection of an X-axis label and a Y-axis label;
its colour encodes the cell's numeric value using a sequential D3 colour
scale.  Returns C<{ svg_id =E<gt> 'heatmap', html =E<gt> Str }>.  The
caller is responsible for loading D3 v7 before embedding the fragment.

=head3 Data format

Each element of C<\@triples> is C<[$x_label, $y_label, $value]>.
C<$value> must be numeric or C<undef> (C<undef> rows are silently
skipped).  Zero is a valid value and maps to the lightest cell colour.
The caller is responsible for any aggregation: if multiple triples share
the same (x_label, y_label) pair, the last one wins.

=head3 Options (C<\%opts>)

=over 4

=item * C<color_scheme> (string, default C<'YlOrRd'>) - D3 sequential
colour scheme.  Supported: C<YlOrRd>, C<Blues>, C<Greens>, C<Purples>,
C<RdPu>, C<YlGnBu>.

=item * C<x_label> (string, default C<''>) - Axis title below the X axis.
The value is JavaScript-escaped (backslash, double-quote, newline, carriage
return) before being embedded in the page; other characters are taken
literally.

=item * C<y_label> (string, default C<''>) - Axis title left of the Y axis.
Same JS-escaping as C<x_label> applies.

=item * C<val_label> (string, default C<'Value'>) - Tooltip value label.
Same JS-escaping as C<x_label> applies.

=item * C<show_values> (bool, default 0) - Print value inside each cell.
Auto-suppressed when any cell is narrower than 28 px.

=item * C<cell_padding> (int 0-8, default 2) - Gap in pixels between cells.

=item * C<legend> (bool, default 1) - Render a colour-scale legend bar.

=item * C<animated> (bool, default 0) - Fade cells in on first load.
Respects C<prefers-reduced-motion>.

=back

=head3 Errors

=over 4

=item * Dies with C<Data must be an array of arrays> when C<\@triples>
is not an ARRAY reference.

=item * Dies with C<Each data point must be an array reference> when a
triple element is not an arrayref.

=item * Dies with C<Each data point must have at least 3 elements> when
a triple has fewer than 3 elements.

=item * Dies with C<Value must be numeric> when C<$value> is defined but
not numeric.

=item * Dies with C<Unknown color_scheme: E<lt>nameE<gt>> for an
unsupported C<color_scheme> value.

=item * Dies with C<cell_padding must be between 0 and 8> when
C<cell_padding> is outside the valid range.

=back

=head3 Side Effects

Appends a tooltip C<div> to the page when the fragment is rendered in
the browser.

=head3 API SPECIFICATION

=head4 Input

    {
        data => { type => 'arrayref' },
        opts => { type => 'hashref', optional => 1, default => {} },
    }

    Each element of C<$data> is C<[ Str, Str, Num|undef ]>.
    Recognised C<opts> keys: C<color_scheme> (string, default C<'YlOrRd'>),
    C<x_label> (string, default C<''>), C<y_label> (string, default C<''>),
    C<val_label> (string, default C<'Value'>), C<show_values> (boolean,
    default C<0>), C<cell_padding> (integer 0-8, default C<2>),
    C<legend> (boolean, default C<1>), C<animated> (boolean, default C<0>).

=head4 Output

    HashRef -- C<{ svg_id =E<gt> 'heatmap', html =E<gt> Str }>;
               embeddable fragment; no DOCTYPE, no page shell, no D3 CDN tag.

=cut