Spotlight

@inject IJSRuntime Js

<div class="dr-col">
    <div @ref="_stage" style="position:relative; height:260px; overflow:hidden;
                              border:1px solid var(--border); border-radius:var(--radius-surface)">
        <div class="dr-col" style="padding:16px">
            <div class="dr-row dr-between">
                <button @ref="_targets[0]" class="btn btn-primary" type="button">Reconcile all</button>
                <span @ref="_targets[1]" class="health-badge health-badge--live">
                    <span class="health-dot"></span> Live
                </span>
            </div>
            <div @ref="_targets[2]" class="stat-row stat-row--divided">
                <span class="stat">
                    <span class="stat-label">Dispatched</span>
                    <span class="stat-value">248</span>
                </span>
                <span class="stat">
                    <span class="stat-label">Backordered</span>
                    <span class="stat-value">12</span>
                </span>
            </div>
        </div>

        <div @ref="_hole" class="spotlight-hole spotlight-ring"></div>
        <div @ref="_tip" class="spotlight-tip">
            <span class="spotlight-tip-title">@Steps[_step].Title</span>
            @Steps[_step].Body
            <div class="spotlight-tip-actions">
                <span class="spotlight-step">@(_step + 1) of @Steps.Length</span>
                <span class="dr-row dr-gap-1">
                    <button class="btn btn-sm" type="button" disabled="@(_step == 0)"
                            @onclick="() => Go(-1)">Back</button>
                    <button class="btn btn-sm btn-primary" type="button"
                            @onclick="() => Go(1)">
                        @(_step == Steps.Length - 1 ? "Done" : "Next")
                    </button>
                </span>
            </div>
        </div>
    </div>
</div>

@code {
    private sealed record Step(string Title, string Body);

    private static readonly Step[] Steps =
    [
        new("Reconcile everything at once", "Applies every pending reservation above the confidence threshold. Each one can still be undone afterwards."),
        new("Watch the connection", "Pulsing means the stream is live. It stops pulsing the moment the connection settles or drops."),
        new("Today against the target", "Both figures update as orders move. A dash means the endpoint did not answer — never a zero."),
    ];

    private ElementReference _stage;
    private ElementReference _hole;
    private ElementReference _tip;
    private readonly ElementReference[] _targets = new ElementReference[Steps.Length];
    private int _step;

    // After every render, because the tip's own size decides where it fits and that is
    // only known once it has been laid out with this step's text in it.
    protected override async Task OnAfterRenderAsync(bool firstRender) => await Place();

    private async Task Go(int by)
    {
        _step = Math.Clamp(_step + by, 0, Steps.Length - 1);
        await Place();
    }

    private async Task Place()
    {
        // The helper measures the target and writes the hole's four values; the app owns
        // which target, the copy and the order. That split is why there is no tour API.
        var rect = await Js.InvokeAsync<object>("drSimpleUi.spotlight.at", _hole, _targets[_step]);
        await Js.InvokeVoidAsync("drSimpleUi.spotlight.tipAt", _tip, rect, 12);
    }
}

// Position the hole over a target. Returns the rectangle it used, in the
// hole's own coordinate space, so a bubble can be placed without measuring
// the target twice.
const rect = drSimpleUi.spotlight.at(hole, target);            // 4px of padding
const wide = drSimpleUi.spotlight.at(hole, target, { pad: 8 });

// Place the bubble under that rectangle, flipped above when the viewport has
// no room below.
drSimpleUi.spotlight.tipAt(tip, rect);
drSimpleUi.spotlight.tipAt(tip, rect, 14);                     // a wider gap

// From Blazor. There is no IDrSimpleUi member for this: both calls take
// element references, which only IJSRuntime can pass. Position after every
// render, not only on a step change — the bubble's own size decides where it
// fits, and that is known only once it has been laid out with this step's
// text in it.
protected override async Task OnAfterRenderAsync(bool firstRender)
{
    var rect = await Js.InvokeAsync<object>("drSimpleUi.spotlight.at", _hole, _targets[_step]);
    await Js.InvokeVoidAsync("drSimpleUi.spotlight.tipAt", _tip, rect, 12);
}

// The element the hole sits in has to be positioned: the hole is placed
// against its offset parent.