112 lines
4.6 KiB
Markdown
112 lines
4.6 KiB
Markdown
# Cooldown Button Component
|
||
|
||
A square Blazor button with a 12-second cooldown animation: when clicked, the button greys out and a circular transparency wedge dials open clockwise, progressively revealing the normal button state underneath.
|
||
|
||
---
|
||
|
||
## Visual Design
|
||
|
||
The button has two visual states:
|
||
|
||
**Idle state** – A solid square button with the project's standard `--paper` background and `--primary` border. Hover inverts or brightens the paper. Click triggers a brief scale-down.
|
||
|
||
**Cooldown state** – The native button fades to `opacity: 0` while an absolutely-positioned overlay covers it. The overlay uses a `conic-gradient` CSS mask to create a "dialling open" effect. A number in the centre shows the remaining seconds.
|
||
|
||
---
|
||
|
||
## Core Technique: Conic-Gradient Mask
|
||
|
||
The cooldown reveal is accomplished with a **conic-gradient mask** applied to the overlay `<div>`:
|
||
|
||
```
|
||
mask-image: conic-gradient(
|
||
transparent 0deg,
|
||
transparent {angle}deg,
|
||
#000 {angle}deg,
|
||
#000 360deg
|
||
);
|
||
```
|
||
|
||
- **`transparent`** – lets the button underneath show through (revealed area)
|
||
- **`#000` (black)** – fully masks the overlay, making it visible (greyed-out area)
|
||
|
||
At `angle = 0deg`, transparent covers nothing and the mask is entirely black → the overlay is fully opaque (button completely greyed out).
|
||
|
||
At `angle = 360deg`, transparent covers the full circle and black covers nothing → the overlay is fully transparent (button completely visible).
|
||
|
||
The angle animates linearly from 0 to 360 over the cooldown duration. Because `conic-gradient` starts at the 12 o'clock position and sweeps clockwise, the reveal begins at the top of the button and rotates around, like a clock hand or a dial opening.
|
||
|
||
---
|
||
|
||
## Implementation Architecture
|
||
|
||
### Component Parameters
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|------------------|-------------------|---------|------------------------------------|
|
||
| `ChildContent` | `RenderFragment` | `null` | Text or content inside the button |
|
||
| `OnClick` | `EventCallback` | — | Fired when the button is clicked |
|
||
| `CooldownSeconds`| `int` | `12` | Duration of the cooldown in seconds|
|
||
| `Size` | `int` | `120` | Width and height in pixels (square)|
|
||
|
||
### Timer Loop
|
||
|
||
A `System.Timers.Timer` fires every ~33 ms (≈30 fps) during the cooldown:
|
||
|
||
```
|
||
OnTick:
|
||
elapsed = UtcNow - startTime
|
||
if elapsed >= CooldownSeconds → end cooldown, dispose timer
|
||
_elapsedAngle = (elapsed / CooldownSeconds) * 360
|
||
_remainingSeconds = CooldownSeconds - (int)elapsed
|
||
InvokeAsync(StateHasChanged)
|
||
```
|
||
|
||
On each tick, `_elapsedAngle` is written into the overlay's inline `style` attribute, causing Blazor to re-render the `mask-image`. The timer is disposed in `Dispose()` to prevent leaks.
|
||
|
||
### Disposal
|
||
|
||
The component implements `IDisposable` to clean up the timer when the component is removed from the render tree. This follows the same pattern used by `SearchDialogComponent` and `BuildChartComponent` elsewhere in the codebase.
|
||
|
||
---
|
||
|
||
## CSS Masking Details
|
||
|
||
Two vendor-prefixed properties are set to ensure cross-browser support:
|
||
|
||
```
|
||
mask-image: conic-gradient(...);
|
||
-webkit-mask-image: conic-gradient(...);
|
||
```
|
||
|
||
The overlay uses `pointer-events: none` and `user-select: none` so that interaction passes through to the button underneath (which is disabled and transparent).
|
||
|
||
An `rgba(22, 22, 24, 0.82)` semi-transparent background on the overlay produces the greyed-out appearance. The mask controls *where* this background is visible.
|
||
|
||
---
|
||
|
||
## Usage on the Home Page
|
||
|
||
The component is added to `Pages/Pages/Home/HomePage.razor` inside the first `PaperComponent`:
|
||
|
||
```razor
|
||
<CooldownButtonComponent CooldownSeconds="12"
|
||
Size="120"
|
||
OnClick="OnCooldownClick">
|
||
Click Me
|
||
</CooldownButtonComponent>
|
||
```
|
||
|
||
The `OnCooldownClick` handler in the page's `@code` block currently returns `Task.CompletedTask` (a no-op). This is the extension point where real work (e.g. triggering a game action, calling an API, showing a toast) would go.
|
||
|
||
---
|
||
|
||
## Adapting the Component
|
||
|
||
- **Change cooldown duration** – set `CooldownSeconds` to any positive integer.
|
||
- **Change button size** – set `Size` to any pixel dimension (button remains square).
|
||
- **Custom content** – pass any Blazor markup as `ChildContent` (text, icons, spinners).
|
||
- **Handle the click** – attach a handler to `OnClick` that returns `Task` or `void`.
|
||
|
||
The `--cooldown-size` CSS custom property is set inline on the wrapper so that the label, overlay, and button all scale together.
|