# Specification

## Overview

A popup-primitive is a container that, when triggered by an interaction, displays its children on top of other page elements. Popup-primitive is a lightweight implementation of a popup.

This specification is an extension of the [SDS Overlay Specification →]().

## Use Cases

- The popup-primitive acts as a container that can display additional rich content above page contents.
- The popup-primitive can be used standalone or as a building block for more complex components such as toasts and tooltips. If you're looking for a complete out-of-the-box component, see [Popup]() or [Tooltip]().

## Non-goals

- The popup-primitive is not meant to be used for modal-like interactions where the popup has to be explicitly dismissed or captures focus.
- Customizations made outside of [Styling Hooks](#styling-hooks-jump) are not supported.
- Variants are not included in SDS. Variants should be applied at the subsystem layer.

## Features

Inherits the features of [SDS Overlay - Diagram →]().

- Adds features that create popup behavior:
  - Dismiss by clicking on the page
  - Dismiss by keying the `esc` key
  - Adds `role="alert"`

## API

The popup-primitive component should support all [global attributes](https://html.spec.whatwg.org/multipage/dom.html#global-attributes) of HTML elements.

### Custom Element

This specification will apply to a SDS custom element. Still, it can also be implemented in a subsystem's ecosystem with the [subsystems namespace](#namespace-service) used as the prefix to the custom elements definition:

1. `sds-popup-primitive` - This is owned by the Salesforce Design System (SDS) Team.
2. `<namespace>-popup-primitive` - This is owned by a subsystem built on SDS, e.g. `dxp-popup-primitive`

## Anatomy and Appearance

The following DOM structure and named part attribute on the leaf node as documented is **required** to use the SDS primitive popup CSS.

### DOM Structure

```html
<host>
  <div part="backdrop"></div>
  <div part="popup">
    <div part="overlay">
      <slot></slot>
    </div>
  </div>
</host>
```

### Slots

| Slot Name | Description                  | Fallback Content |
| --------- | ---------------------------- | ---------------- |
| `default` | Add the main body of content | empty            |

### Parts

| Part Name  | Description                                   |
| ---------- | --------------------------------------------- |
| `backdrop` | Backdrop element that lives below the overlay |
| `overlay`  | The container of the overlay component        |
| `popup`    | Main container of the component               |

### Properties & Attributes

The overlay inherits from the [SDS overlay component]().

### Events

N/A

## Styling Hooks

#### Box Shadow

| Property Name          | CSS Property | Fallback Value                                         | Description                 |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------------- |
| `--sds-c-popup-shadow` | `box-shadow` | `--sds-s-popup-shadow` &vert;&vert; `--sds-g-shadow-1` | Box shadow of the component |

#### Color

| Property Name                    | CSS Property       | Fallback Value                                                                  | Description                       |
| -------------------------------- | ------------------ | ------------------------------------------------------------------------------- | --------------------------------- |
| `--sds-c-popup-color-background` | `background-color` | `--sds-s-popup-color-background` &vert;&vert; `--sds-g-color-neutral-base-1)`   | Background color of the component |
| `--sds-c-popup-color-border`     | `border-color`     | `--sds-s-popup-color-border` &vert;&vert; `--sds-g-color-border-base-1`         | Border color of the component     |
| `--sds-c-popup-text-color`       | `color`            | `--sds-s-popup-text-color` &vert;&vert; `--sds-g-color-neutral-base-contrast-4` | Text color of the component       |

#### Radius

| Property Name                 | CSS Property    | Fallback Value                                                       | Description                    |
| ----------------------------- | --------------- | -------------------------------------------------------------------- | ------------------------------ |
| `--sds-c-popup-radius-border` | `border-radius` | `--sds-s-popup-radius-border` &vert;&vert; `--sds-g-radius-border-2` | Border radius of the component |

#### Sizing

| Property Name                 | CSS Property  | Fallback Value                                                       | Description                  |
| ----------------------------- | ------------- | -------------------------------------------------------------------- | ---------------------------- |
| `--sds-c-popup-sizing-border` | `border-size` | `--sds-s-popup-sizing-border` &vert;&vert; `--sds-g-sizing-border-1` | Border size of the component |

#### Spacing

| Property Name                        | CSS Property | Fallback Value                                                  | Description                           |
| ------------------------------------ | ------------ | --------------------------------------------------------------- | ------------------------------------- |
| `--sds-c-popup-spacing-block-start`  | `padding`    | `--sds-s-popup-spacing-block` &vert;&vert; `--sds-g-spacing-3`  | Block-start padding of the component  |
| `--sds-c-popup-spacing-block-end`    | `padding`    | `--sds-s-popup-spacing-block` &vert;&vert; `--sds-g-spacing-3`  | Block-end padding of the component    |
| `--sds-c-popup-spacing-inline-start` | `padding`    | `--sds-s-popup-spacing-inline` &vert;&vert; `--sds-g-spacing-3` | Inline-start padding of the component |
| `--sds-c-popup-spacing-inline-end`   | `padding`    | `--sds-s-popup-spacing-inline` &vert;&vert; `--sds-g-spacing-3` | Inline-end padding of the component   |

## Behavior

### States & Interactions

The overlay inherits from the [SDS overlay component]().

## Accessibility

n/a

## Internationalization

The content within your overlay should follow standard usage rules when displayed in bidirectional (RTL) text flows. For example, the text should appear on the right (or start) of the container in RTL.

## Test Plan

- Ensuring slots are consistent and available
- Ensuring opened and closed API and behavior are fully functioning

## Open Questions

- Returning focus to triggering element.