[FEATURE]: autorangePadding

[FEATURE]: autorangePadding — Explicit Control and Introspection of Autorange Padding

Summary

When autorange: true is set on an axis, Plotly silently adds a padding fraction
around the data range. This padding is internally computed, never documented as a
configurable value, and impossible to query without using full_figure_for_development().
This issue proposes:

1. A new per-axis layout attribute autorangePadding to give users explicit control
   over the padding fraction
2. Exposure of the computed padding via get_computed_values() for introspection

---

Problem Statement

Autorange padding causes subtle but persistent issues in several common workflows:

Problem 1 — Multi-figure axis alignment:
Two figures sharing a conceptual x-axis (e.g. a price chart above a volume chart)
will not align perfectly even when their data ranges are identical, because autorange
applies padding independently on each figure. There is no way to force consistent
padding without disabling autorange entirely.

Problem 2 — Controlled range extension:
A user wants autorange but needs extra space on one side for an annotation or legend.
Currently this is impossible without computing the full data range manually and setting
a fixed range — defeating the purpose of autorange.

Problem 3 — Range introspection in production:
Users who need the exact rendered axis range must use full_figure_for_development(),
which is explicitly documented as not for production use. There is no lightweight
alternative.

---

Proposed Solution

1. New Layout Attribute: autorangePadding

Set per axis as a fraction of the total data range:

fig.update_layout(
    xaxis=dict(
        autorange=True,
        autorangePadding=0.05   # 5% padding each side — matches current default behavior
    ),
    yaxis=dict(
        autorange=True,
        autorangePadding=0.0    # no padding — data fills axis edge to edge
    )
)

Default value matches the current implicit behavior so all existing figures are
unaffected.

Asymmetric Padding

For cases where padding is only needed on one side:

fig.update_layout(
    yaxis=dict(
        autorange=True,
        autorangePadding=dict(before=0.0, after=0.15)  # extra headroom at top only
    )
)

before = lower end of the axis, after = upper end, regardless of axis direction.

---

2. Introspection via get_computed_values()

computed = fig.get_computed_values(include=["axis_ranges", "autorange_padding"])

Returns:

{
    "axis_ranges": {
        "xaxis": [-0.5, 10.5],
        "yaxis": [-4.35, 102.1]
    },
    "autorange_padding": {
        "xaxis": {
            "before": 0.05,
            "after": 0.05,
            "pixels": {"before": 18.4, "after": 18.4}
        },
        "yaxis": {
            "before": 0.05,
            "after": 0.05,
            "pixels": {"before": 14.2, "after": 14.2}
        }
    }
}

Both fractional and pixel values are returned, making the result useful for
data-space alignment and pixel-space layout work respectively.

---

3. Companion Utility: match_axis_ranges() (Optional)

A natural extension that syncs axis ranges across multiple figures:

import plotly.utils as pu

pu.match_axis_ranges([fig1, fig2], axis="x")

Computes the union of both figures' data ranges and applies a consistent range to both
so they align exactly — the most common use case motivating this feature.

---

Relationship to get_computed_values()

This feature is a direct extension of the get_computed_values() proposal:

• axis_ranges already proposes returning the final rendered range
• autorange_padding extends that with a breakdown of how much of the range is
  padding vs. actual data span
• autorangePadding is the write-side complement to the read-side introspection

Together they give full round-trip control: set the padding you want, then verify
exactly what was applied.

---

Prior Art

Tool	Equivalent
matplotlib	ax.margins(x=0.05) sets padding; ax.get_xlim() returns final range
Vega-Lite	Explicit "padding" property on scale definitions
D3.js	scale.nice() and direct scale.domain() control

---

Backward Compatibility

• autorangePadding is a new optional attribute. Omitting it preserves current behavior exactly.
• No existing figures, layouts, or workflows are affected unless users explicitly opt in.

---

Acceptance Criteria

• autorangePadding accepted as a per-axis layout attribute (scalar or asymmetric dict)
• Default value matches current implicit padding so existing figures are unchanged
• Computed padding values returned via get_computed_values(include=["autorange_padding"])
• Both fractional and pixel padding values included in the return
• Documented in the axis layout attribute reference
• match_axis_ranges() utility considered as a follow-up or included in scope

---

Related Issues

• Companion to: [FEATURE]: get_computed_values() (https://github.com/plotly/plotly.py/issues/5552)
• Companion to: [FEATURE]: get_subplot_geometry() (https://github.com/plotly/plotly.py/issues/5554)
• Related to any issue requesting consistent axis ranges across multiple figures

---

I am happy to discuss the naming convention for autorangePadding vs autorange_padding
to match the existing attribute style guide, and whether the match_axis_ranges()
utility belongs in this issue or a separate one.

首先檢視 issue 5552 中相關的 get_computed_values() 提案，以及現有的軸版面配置屬性參考。定義 autorangePadding、計算值內省與選用的 match_axis_ranges() 工具之間的範圍。完成的標準是：在不變更現有預設行為的情況下，實作、測試並記錄已達成共識的驗收標準。