# ui global

> The retained Menu and HUD and their primitives, generated from the shipped declarations.

Generated from the declarations in `@disko-game/build/types`. See
[Menus & HUD](/games/menus-and-hud) for a guide.

## The `ui` global

The retained Menu and HUD.

```ts
declare const ui: Disko.Ui;
```

## UI

### Disko.UiStyle

A frozen style created by `ui.style`.

```ts
interface UiStyle {
    readonly kind: "ui-style";
    readonly declarations: UiStyleDeclarations;
}
```

### Disko.UiStyleDeclarations

Style declarations: sizes in pixels or CSS-like strings, colors as tokens or hex.

```ts
interface UiStyleDeclarations {
    readonly [property: string]: string | number | boolean | undefined;
}
```

### Disko.UiTheme

A frozen theme created by `ui.theme`.

```ts
interface UiTheme {
    readonly kind: "ui-theme";
    readonly [token: string]: unknown;
}
```

### Disko.UiRequest

A request to the game when a control is used, created by `ui.request`.

```ts
interface UiRequest {
    readonly __uiRequest: never;
}
```

### Disko.UiLocalCommand

A local client-side command such as `ui.open(modal)`.

```ts
interface UiLocalCommand {
    readonly __uiLocalCommand: never;
}
```

### Disko.UiSwap

A content replacement pushed with `ui.push`.

```ts
interface UiSwap {
    readonly __uiSwap: never;
}
```

### Disko.UiNode

A retained UI node.

```ts
interface UiNode {
    readonly id: number;
    readonly kind: string;
    readonly options: {
        readonly [option: string]: unknown;
    };
    readonly children: readonly UiNode[];
}
```

### Disko.UiContent

Content accepted wherever children are.

```ts
type UiContent = UiNode | readonly UiNode[];
```

### Disko.UiTrigger

A semantic trigger, independent of the input device.

```ts
type UiTrigger = "activate" | "submit" | "input" | "change" | "commit" | "drop";
```

### Disko.UiTargetReference

A node, or a target relative to the source: itself, its nearest form or slot.

```ts
type UiTargetReference = UiNode | "this" | "form" | "slot";
```

### Disko.UiValue

A value carried by UI controls and local commands.

```ts
type UiValue = JsonValue;
```

### Disko.UiRequirement

Gates a node on a permission. Recipients without it do not receive the node and its subtree (`denied: "hide"`, the default), or receive them disabled and without server requests (`denied: "disable"`).

```ts
type UiRequirement = Permission | {
    readonly permission: Permission;
    readonly denied?: "hide" | "disable";
};
```

### Disko.UiOptions

Options shared by every UI primitive.

```ts
interface UiOptions {
    readonly key?: string;
    readonly style?: UiStyle | UiStyleDeclarations;
    readonly accessibleName?: string;
    readonly children?: UiContent;
    readonly on?: {
        readonly [Trigger in UiTrigger]?: UiRequest | UiLocalCommand;
    };
    readonly requires?: UiRequirement;
    readonly text?: string;
    readonly label?: string;
    readonly name?: string;
    readonly alt?: string;
    readonly asset?: PackageAsset | string;
    readonly heading?: number;
    readonly enabled?: boolean;
    readonly visible?: boolean;
    readonly selected?: boolean;
    readonly checked?: boolean;
    readonly open?: boolean;
    readonly dismiss?: "local";
    readonly value?: UiValue;
    readonly drag?: {
        readonly kind: string;
        readonly value?: UiValue;
    };
    readonly drop?: {
        readonly accept: string;
        readonly value?: UiValue;
    };
    readonly [option: string]: unknown;
}
```

| Member | Description |
| --- | --- |
| `requires` | Hides or disables this node for players without the permission. |
| `name` | Form field name. |
| `alt` | Alternative text of an image. |
| `[index]` | Direct style properties are accepted beside `style`. |

### Disko.UiPlayerOptions

Options of a primitive that shows one player.

```ts
interface UiPlayerOptions extends UiOptions {
    readonly player: Player;
}
```

### Disko.UiValueSchema

The closed schema of the values a request carries.

```ts
type UiValueSchema = {
    readonly type: "null";
} | {
    readonly type: "boolean";
} | {
    readonly type: "integer" | "number";
    readonly minimum: number;
    readonly maximum: number;
} | {
    readonly type: "text";
    readonly maximumBytes: number;
    readonly choices?: readonly string[];
} | {
    readonly type: "list";
    readonly items: UiValueSchema;
    readonly maximumItems: number;
} | {
    readonly type: "record";
    readonly fields: readonly {
        readonly name: string;
        readonly optional?: boolean;
        readonly schema: UiValueSchema;
    }[];
};
```

### Disko.UiSwapMethod

How the response content is placed at the target.

```ts
type UiSwapMethod = "replace" | "children" | "append" | "prepend" | "before" | "after" | "remove";
```

### Disko.UiConcurrencyPolicy

```ts
type UiConcurrencyPolicy = "drop" | "replace" | "parallel" | "queue";
```

### Disko.UiRequestOptions

Options of `ui.request`.

```ts
interface UiRequestOptions {
    readonly event: string;
    readonly target?: UiTargetReference;
    readonly swap?: UiSwapMethod;
    readonly values?: "none" | "control" | "form";
    readonly triggerPolicy?: "immediate" | {
        readonly type: "immediate";
    } | {
        readonly type: "debounce" | "throttle";
        readonly millis: number;
    };
    readonly concurrency?: UiConcurrencyPolicy | {
        readonly type: UiConcurrencyPolicy;
        readonly limit?: number;
    };
    readonly payloadSchema?: UiValueSchema;
    readonly requires?: Permission;
}
```

| Member | Description |
| --- | --- |
| `event` | The `ui-request` event name the game receives. |
| `target` | Where the response goes; defaults to the source (`"this"`). |
| `swap` | Defaults to `"replace"`. |
| `values` | Values collected by the client; defaults to `"none"`. |
| `concurrency` | Defaults to `"queue"` with a limit of one. |
| `payloadSchema` | Defaults to `{ type: "null" }`. |
| `requires` | Only players with this permission can use the request; for the others the control is disabled and carries no request. |

### Disko.UiPrimitive

A UI primitive constructor.

```ts
type UiPrimitive = (options?: UiOptions) => UiNode;
```

### Disko.Ui

The retained UI API: Menu, HUD and their primitives.

```ts
interface Ui {
    fragment(...children: UiNode[]): UiNode;
    request(options: UiRequestOptions): UiRequest;
    swap(options: {
        readonly target: UiNode;
        readonly method?: UiSwapMethod;
        readonly content?: UiContent;
    }): UiSwap;
    style(declarations?: UiStyleDeclarations): UiStyle;
    theme(tokens?: {
        readonly [token: string]: unknown;
    }): UiTheme;
    menu(content: UiContent, options?: {
        readonly placement?: "viewport-center";
    }): UiNode;
    hud(content: UiContent): UiNode;
    push(swaps: UiSwap | readonly UiSwap[]): void;
    push(player: Player, swaps: UiSwap | readonly UiSwap[]): void;
    remove(target: UiNode): UiSwap;
    show(target?: UiTargetReference): UiLocalCommand;
    hide(target?: UiTargetReference): UiLocalCommand;
    open(target?: UiTargetReference): UiLocalCommand;
    close(target?: UiTargetReference): UiLocalCommand;
    focus(target?: UiTargetReference): UiLocalCommand;
    blur(target?: UiTargetReference): UiLocalCommand;
    reset(target?: UiTargetReference): UiLocalCommand;
    transition(target: UiTargetReference | undefined, value: UiValue): UiLocalCommand;
    box: UiPrimitive;
    stack: UiPrimitive;
    row: UiPrimitive;
    grid: UiPrimitive;
    overlay: UiPrimitive;
    scroll: UiPrimitive;
    slot: UiPrimitive;
    spacer: UiPrimitive;
    text: UiPrimitive;
    richtext: UiPrimitive;
    image: UiPrimitive;
    icon: UiPrimitive;
    shape: UiPrimitive;
    button: UiPrimitive;
    link: UiPrimitive;
    form: UiPrimitive;
    input: UiPrimitive;
    area: UiPrimitive;
    toggle: UiPrimitive;
    slider: UiPrimitive;
    select: UiPrimitive;
    option: UiPrimitive;
    progress: UiPrimitive;
    activity: UiPrimitive;
    status: UiPrimitive;
    alert: UiPrimitive;
    list: UiPrimitive;
    item: UiPrimitive;
    table: UiPrimitive;
    header: UiPrimitive;
    body: UiPrimitive;
    footer: UiPrimitive;
    cell: UiPrimitive;
    modal: UiPrimitive;
    popover: UiPrimitive;
    tabs: UiPrimitive;
    tab: UiPrimitive;
    panel: UiPrimitive;
    disclosure: UiPrimitive;
    flag(options: UiPlayerOptions): UiNode;
    connection(options: UiPlayerOptions): UiNode;
    playerName(options: UiPlayerOptions): UiNode;
}
```

| Member | Description |
| --- | --- |
| `menu()` | Sets the Menu, shown while the room is not playing or on Esc. |
| `hud()` | Sets the HUD of the running match. |
| `push()` | Publishes swaps to everyone, or only to one player. |
| `flag()` | A player's country flag; `player` is required. |
| `connection()` | A player's connection quality; `player` is required. |
| `playerName()` | A player's name in the room's color with its badge, rendered by the client; the node holds only the player's identity. `player` is required. |