# flagstaff/box

> Every export of flagstaff/box, with its signature and doc comment: box, boxComponent, plus 3 types.

Source: https://flagstaff.interlace.tools/docs/api/box

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

```ts
import { box, boxComponent } from 'flagstaff/box';
```

## Functions

### box

Draw `text` in a box, as a string. The many callers who want only this want only this.

```ts
function box(text: string, options?: BoxOptions): string;
```

| Parameter | Type |
| :-- | :-- |
| `text` | `string` |
| `options` (optional) | `BoxOptions` |

**Returns** `string`

### boxComponent

A box as a component: the text off a terminal, the drawing on one (R1).

```ts
function boxComponent(options?: BoxOptions): Component<BoxState>;
```

| Parameter | Type |
| :-- | :-- |
| `options` (optional) | `BoxOptions` |

**Returns** `Component<BoxState>`

## Interfaces

### BoxOptions

```ts
interface BoxOptions {
    /** A registered border's name, or a style of your own. Default `round`. */
    border?: string | BorderStyle;
    /** Cells of padding left and right of the text, and rows above and below. Default 1 / 0. */
    padding?: {
        x?: number;
        y?: number;
    };
    /** A title written into the top border. Truncated with `…` if the box is too narrow. */
    title?: string;
    /** Columns the whole box may occupy, borders included. Text wraps to fit. Default 80. */
    width?: number;
    /**
     * A url or a path the box's text points at — `file://…` for a path a terminal should be
     * able to open, which is the case R12 is named after. The title is left alone: it is a
     * label for the box, and a link around it would claim the border is clickable too.
     */
    href?: string;
    /**
     * The terminal the link is rendered for. Omitted, the real process is read through this
     * package's seam. Supply one and the whole path is pure.
     */
    terminal?: Terminal;
}
```

### BoxState

```ts
interface BoxState {
    text: string;
    title?: string;
    /** Per-state destination, overriding the one the component was built with. */
    href?: string;
}
```

## Types

### Terminal

The slice of the world paratext needs in order to answer. Derived from `linkFor` rather
than imported: `paratext/link` publishes the functions, not the type, and a second
specifier for a type would put `paratext` in this package's graph for something
`verbatimModuleSyntax` erases anyway.

```ts
type Terminal = Parameters<typeof linkFor>[0];
```