# BondFormation

> Two atoms with their valence electrons on a ring around each symbol, placed as in a Lewis diagram.

Page: https://fframes-kit.pages.dev/docs/chemistry/bond-formation/
Cargo feature: `chemistry` (`fframes-kit = { version = "..", features = ["chemistry"] }`)

Two atoms with their valence electrons on a ring around each symbol, placed as in a Lewis
diagram. From `at` over `duration` seconds they bond:

- **`BondType::Ionic`**: the left atom's electrons arc over to the gaps of the right one. The
  empty ring fades and both atoms get their charge.
- **`BondType::Covalent`**: the atoms move together until their rings overlap. The electrons
  each one lacks pair up between them in `shared_color`, and a label counts the shared pairs.

`valence`, `missing` and `bond_electrons` give the numbers it uses. Gallery scenes:
`BondFormation` (sodium chloride) and `CovalentBond` (oxygen).

Gallery clip of `BondFormation`: https://fframes-kit.pages.dev/media/scenes/BondFormation-b89e4131.mp4

Gallery clip of `CovalentBond`: https://fframes-kit.pages.dev/media/scenes/CovalentBond-fd064b75.mp4

```rust
use fframes_kit::prelude::*;

fn figures<'a>(ui: &mut Ui<'a, '_, '_>) -> Svgr<'a> {
    let salt = ui.show(BondFormation {
        center: (0.0, 1.8),
        at: 1.0,
        ..ui.defaults()
    });
    let oxygen = ui.show(BondFormation {
        kind: BondType::Covalent,
        left: 8,
        right: 8,
        center: (0.0, -1.8),
        at: 1.0,
        ..ui.defaults()
    });
    svgr!(<g>{salt}{oxygen}</g>)
}
```

## API

Components are plain structs. Set the fields you need and fill the rest with `..ui.defaults()`: the defaults below come from the current theme (`theme.` values are fields of `Theme`).

### BondFormation

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `BondType` | `BondType::Ionic` | Ionic (the left atom gives electrons away) or covalent (the atoms share pairs). |
| `left` | `u32` | `11` | Atomic number of the left atom; the electron donor when ionic. |
| `right` | `u32` | `17` | Atomic number of the right atom; the electron acceptor when ionic. |
| `center` | `(f64, f64)` | `(0.0, 0.0)` | The middle between the two atoms, in units of `ui.space`. |
| `distance` | `f32` | `520.0` | Pixels between the atom centres at the start; covalent atoms then move closer until their rings overlap. |
| `radius` | `f32` | `130.0` | Radius in pixels of each valence ring; the nucleus and electron sizes follow it. |
| `at` | `f32` | `1.0` | Seconds after the container's start when the bonding begins. |
| `duration` | `f32` | `1.5` | Seconds the electron transfer (and, when covalent, the approach) takes. |
| `labels` | `bool` | `true` | Writes the ion charges (ionic) or the number of shared pairs (covalent) once bonded; `false` for none. |
| `nucleus_color` | `Color` | `theme.colors.accent` | Colour of the nucleus discs behind the symbols. |
| `ring_color` | `Color` | `theme.colors.muted` | Colour of the valence rings. |
| `electron_color` | `Color` | `theme.colors.highlight` | Colour of the electrons. |
| `shared_color` | `Color` | `Color::hex("#69db7c")` | Colour the shared electron pairs and the "shared pairs" label turn to when covalent. |
| `text_color` | `Color` | `theme.colors.text` | Colour of the ion charge labels. |
| `stroke_width` | `f32` | `theme.stroke.thin` | Outline width in pixels of the valence rings. |
| `enter` | `Option<EnterAnim>` | `None` | How the valence rings appear; `None` shows them from the start. |
| `exit` | `Option<ExitAnim>` | `None` | How the valence rings leave at the end of the container; `None` stays. |
| `parts_enter` | `Option<FadeIn>` | `None` | Fade in of the nuclei, electrons, symbols and labels; `None` for none. |
| `parts_exit` | `Option<FadeOut>` | `None` | Fade out of the nuclei, electrons, symbols and labels before the end; `None` for none. |

Feature `chemistry` · [Source](https://github.com/khanhthanhdev/fframes-kit/blob/main/fframes-kit/src/kits/chemistry/bond_formation.rs#L89)