Phui

Appearance

Nodes ​

Classes in the Phui\Nodes namespace. A node is a description of part of the UI. Nodes are built with fluent setters that return static, so calls chain.

Node ​

abstract class Phui\Nodes\Node

Base class for every node. Extended by ElementNode and ComponentNode.

php
getKey(): string

Returns the node's reconciliation key.

php
setKey(?string $key): static

Sets the reconciliation key. null restores positional identity.

php
static when(bool $condition, Node $node): Node

Returns $node, rendered when $condition is true and hidden when it is false. A hidden node keeps its slot among its siblings across rebuilds, so it needs no key, and it renders nothing and takes no space.

php
static each(
    array $items,
    callable $render,
    callable $key,
): array

Maps $items to an array of nodes, assigning every node a key and guaranteeing those keys are unique among siblings. Both callables receive ($item, $index), indexed from zero over the reindexed array. $render returns a node, or a falsy value to omit that item. $key returns that node's key, cast to string, and throws InvalidArgumentException if the value is empty or repeats.

php
Node::each(
    $this->users,
    fn (User $user) => Text::make($user->name),
    fn (User $user) => (string) $user->id,
)

ElementNode ​

abstract class Phui\Nodes\ElementNode extends Node

Base class for nodes that draw directly to the screen. Extended by Text, Container, Canvas and VirtualContainer.

Sizing ​

php
grow(): static

Fills the available space on both axes.

php
growX(): static

Fills the available width.

php
growY(): static

Fills the available height.

php
fit(): static

Sizes to the content on both axes.

php
fitX(): static

Sizes to the content width.

php
fitY(): static

Sizes to the content height.

php
fixedX(int $value): static

Sets the width to $value columns.

php
fixedY(int $value): static

Sets the height to $value rows.

php
percentX(int $value): static

Sets the width to $value percent of the parent's content box.

php
percentY(int $value): static

Sets the height to $value percent of the parent's content box.

php
minSizeX(int $value): static

Clamps the width to at least $value columns.

php
minSizeY(int $value): static

Clamps the height to at least $value rows.

php
maxSizeX(int $value): static

Clamps the width to at most $value columns.

php
maxSizeY(int $value): static

Clamps the height to at most $value rows.

Spacing ​

php
padding(
    ?int $all = null,
    ?int $top = null,
    ?int $right = null,
    ?int $bottom = null,
    ?int $left = null,
): static

Sets padding inside the border. $all sets all four edges, and any named edge passed alongside it overrides that edge.

php
margin(
    ?int $all = null,
    ?int $top = null,
    ?int $right = null,
    ?int $bottom = null,
    ?int $left = null,
): static

Sets margin outside the border. $all sets all four edges, and any named edge passed alongside it overrides that edge.

php
paddingX(int $value): static

Sets the left and right padding.

php
paddingY(int $value): static

Sets the top and bottom padding.

php
marginX(int $value): static

Sets the left and right margin.

php
marginY(int $value): static

Sets the top and bottom margin.

Borders ​

php
border(
    BorderCharSet|string|null $chars = new BorderCharSet,
    bool $top = true,
    bool $right = true,
    bool $bottom = true,
    bool $left = true,
): static

Draws a border on each enabled edge, occupying one cell per drawn edge. $chars accepts a BorderCharSet, a string naming a preset, or null to remove the border.

php
borderTitle(
    string|StyledString|null $title = null,
    string|StyledString|null $subtitle = null,
): static

Sets the border's title and subtitle. null leaves that value unchanged.

php
borderColour(
    Colour|string|null $line = null,
    Colour|string|null $bg = null,
): static

Sets the border's line and background colours. null leaves that value unchanged.

Colour and utilities ​

php
bgColour(Colour|string|null $colour): static

Sets the background colour. null clears it.

php
tw(string $classes): static

Applies space-separated Tailwind-style utilities.

Mouse handlers ​

php
onMouseDown(Closure $handler): static

Registers a handler called with a MouseClickEvent when the mouse button presses down on the node.

php
onMouseUp(Closure $handler): static

Registers a handler called with a MouseClickEvent when the mouse button releases over the node.

php
onScroll(Closure $handler): static

Registers a handler called with a MouseScrollEvent.

php
onMouseMove(Closure $handler): static

Registers a handler called with a MouseMoveEvent.

php
clearEventHandlers(?string $eventType = null): static

Removes handlers for $eventType, or all handlers when null.

Refs ​

php
ref(ElementRef $ref): static

Binds an ElementRef to this node.

php
getRef(): ?ElementRef

Returns the bound ref, or null when none is bound.

ContainerNode ​

interface Phui\Nodes\ContainerNode

Implemented by nodes that lay out children. Adds the following to the ElementNode surface.

php
children(array|Closure $children): static

Sets the children. A Closure(Space): array is re-evaluated on each rebuild.

php
axis(AxisType|string $type): static

Lays children out along the horizontal or vertical axis.

php
gap(int $value): static

Sets the space between children.

php
alignX(AlignmentType|string $type): static

Aligns children horizontally: start, center or end.

php
alignY(AlignmentType|string $type): static

Aligns children vertically: start, center or end.

Scrolling ​

php
scroll(
    ScrollType|string|null $type = ScrollType::Thin,
): static

Enables scrolling on both axes. $type selects the scrollbar style: thin, thick, double or dotted. null scrolls without drawing a scrollbar. A scrollbar is painted only when its axis overflows.

php
scrollX(
    ScrollType|string|null $type = ScrollType::Thin,
): static

Enables scrolling on the x axis.

php
scrollY(
    ScrollType|string|null $type = ScrollType::Thin,
): static

Enables scrolling on the y axis.

php
scrollColour(
    Colour|string|null $thumb = null,
    Colour|string|null $track = null,
): static

Sets the scrollbar thumb and track colours on both axes.

php
scrollXColour(
    Colour|string|null $thumb = null,
    Colour|string|null $track = null,
): static

Sets the scrollbar thumb and track colours on the x axis.

php
scrollYColour(
    Colour|string|null $thumb = null,
    Colour|string|null $track = null,
): static

Sets the scrollbar thumb and track colours on the y axis.

Text ​

final class Phui\Nodes\Text extends ElementNode

Renders a string. Sizes to its content by default.

php
static make(
    StyledString|string|Closure $content = '',
    ?string $key = null,
): self

Creates a text node. A Closure(Space) is re-evaluated on each rebuild; text built from a Space must have an externally determined width, set by growX() or fixedX().

php
content(
    StyledString|string|Closure $content,
): static

Replaces the content.

php
getContent(): StyledString|string

Returns the current content.

php
align(
    AlignmentType|string $alignment = AlignmentType::Start,
): static

Aligns lines within the node's width: start, center or end.

php
wrap(
    TextWrapType|string $type = TextWrapType::Word,
): static

Sets wrapping: none, character or word.

php
colour(Colour|string $colour): static

Sets the foreground colour.

php
bold(bool $enabled = true): static

Toggles bold.

php
dim(bool $enabled = true): static

Toggles dim.

php
italic(bool $enabled = true): static

Toggles italic.

php
underline(bool $enabled = true): static

Toggles underline.

php
reverse(bool $enabled = true): static

Swaps the foreground and background colours.

php
strikethrough(bool $enabled = true): static

Toggles strikethrough.

Container ​

final class Phui\Nodes\Container extends ElementNode implements ContainerNode

Lays out children along an axis. Horizontal by default.

php
static make(
    array $children = [],
    ?string $key = null,
): self

Creates a container node.

php
Container::make([
    Text::make('Name'),
    Text::make('Value'),
])->axis('vertical')->gap(1)

Space ​

final readonly class Phui\Nodes\Space

The space available for content as of the last settled layout. Passed to content and children closures so they can build for the room they are given. When the available space differs from the size the content was built for, the closure is re-invoked until the two agree.

php
public int $width

The available width in columns.

php
public int $height

The available height in rows.

php
isResolved(): bool

Returns false on the first pass, before the slot has been laid out. Builders can return a placeholder until it is true.

BorderCharSet ​

final readonly class Phui\Style\BorderCharSet

The six characters a border is drawn from, passed to border().

php
__construct(
    public string $horizontal = '─',
    public string $vertical = '│',
    public string $topLeft = '┌',
    public string $topRight = '┐',
    public string $bottomLeft = '└',
    public string $bottomRight = '┘',
)

Creates a character set. Defaults to the square set.

php
static square(): self
static squareHeavy(): self
static rounded(): self
static roundedHeavy(): self
static double(): self

Return the built-in character sets.

php
static fromString(string $name): self

Returns the built-in set named $name: square, square-heavy, rounded, rounded-heavy or double. Case-insensitive and trimmed. Throws InvalidArgumentException for any other name.

Enums ​

ScrollType ​

enum Phui\Style\ScrollType: string

The scrollbar style passed to scroll(). Cases: Thin, Thick, Double, Dotted.

php
getYThumbChar(): string
getYTrackChar(): string
getXThumbChar(): string
getXTrackChar(): string

Return the characters the case draws its thumb and track from, per axis.

Value enums ​

enum Phui\Style\AxisType: string

The axis passed to axis(). Cases: Horizontal, Vertical.

enum Phui\Style\AlignmentType: string

The alignment passed to alignX(), align() and intoView(). Cases: Start, Center, End.

enum Phui\Style\TextWrapType: string

The wrapping mode passed to wrap(). Cases: None, Character, Word.

Released under the MIT License.