Input

# Brok UI: Input (`input`)

Text input with sm/md/lg sizes, invalid, disabled, readonly, file, dark, RTL, and responsive states; composes with label/field/button for forms. Inside a <x-ui.field name> (or with its own name) it self-wires old() repopulation and aria-invalid/aria-describedby from the shared $errors bag.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add input
```

## Usage

```blade
<x-ui.input type="email" value="[email protected]" placeholder="[email protected]" aria-label="{{ __('Email') }}" class="w-full max-w-sm" />
```

## Props

- `type` (string, default `text`) — Native input type (text, email, number, date, and so on).
- `size` (md|sm|lg, default `md`) — Control height and horizontal padding; default is a backward-compatible alias for md.
- `invalid` (bool, default `false`) — Forces the invalid visual state independent of the shared error bag.
- `disabled` (bool, default `false`) — Disables the field and excludes it from submission.
- `value` (mixed|null, default `null`) — Initial value; overridden by a flashed old() value when the field has a resolvable name.

## Use when

- Use when users must enter freeform information that cannot be reliably selected from a list.
- Collecting a single line of free text, a number, an email, a date, or any other native input type value in a form.
- Needing automatic old() repopulation and aria-invalid/aria-describedby wiring off Laravel's shared $errors bag.

## Avoid when

- Do not choose a freeform field when a constrained choice would reduce errors or cognitive load.
- Multi-line text; use textarea instead.
- A fixed set of options to choose from; use select, select-advanced or combobox instead.

## Anti-patterns

- Using freeform entry for a bounded answer set

## Rules

- Use the `<brok:input>` tag (or `<x-ui.input>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/input
- Registry JSON (files, props, contract): https://brokui.dev/r/open/input.json

{{-- A wrapping field with a name shares it down via @aware, so the input can
     self-wire old()/aria-invalid/aria-describedby without the consumer repeating
     it. With no field ancestor (or its own name attribute) this resolves to null
     and nothing below changes — fully backward-compatible. --}}
@aware([
    'name' => null,
    'htmlName' => null,
    'hint' => null,
    'required' => false,
])

@props([
    'type' => 'text',
    'size' => 'md',
    'invalid' => false,
    'disabled' => false,
    'value' => null,
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $input = $styles['input'];

    // @aware leaves $name undefined when there is no wrapping field, so normalise it.
    $awareName = $name ?? null;
    $awareHtmlName = $htmlName ?? null;

    // Effective field name: the @aware value from a wrapping field, else an explicit
    // `name` attribute the consumer set on the input itself.
    $fieldName = $awareName ?? $attributes->get('name');
    $resolvedHtmlName = $awareName
        ? ($awareHtmlName ?? collect(explode('.', $awareName))->reduce(
            fn ($carry, $segment, $index) => $index === 0 ? $segment : $carry.'['.$segment.']',
            ''
        ))
        : $attributes->get('name');

    // The shared error bag drives invalid state + the error message id, so a field
    // wrapper and a standalone named input behave identically after validation.
    $bag = ($errors ?? null) instanceof \Illuminate\Support\ViewErrorBag ? $errors : null;
    $hasBagError = $bag && filled($fieldName) && $bag->has($fieldName);
    $isInvalid = $invalid || $hasBagError;

    $state = $isInvalid ? $input['states']['invalid'] : $input['states']['default'];

    // `default` is a backward-compatible alias for `md` (matches checkbox/switch);
    // any unknown size also falls back to `md`. Resolved at the Blade level so no
    // `default` key leaks into the `_styles.php` size map (and PreviewControls).
    $size = $size === 'default' ? 'md' : (isset($input['sizes'][$size]) ? $size : 'md');
    $classes = trim($input['base'].' '.$state.' '.$input['sizes'][$size]);

    // old($name, $value) repopulates after a failed redirect-back; falls back to the
    // passed value (or null) when there is no flashed input.
    $resolvedValue = filled($fieldName) ? old($fieldName, $value) : $value;

    // Preserve consumer-provided descriptions and add every node owned by the
    // wrapping field. The hint remains associated when an error is also present.
    $describedBy = collect(preg_split('/\s+/', trim((string) $attributes->get('aria-describedby', ''))) ?: [])
        ->when(filled($awareName) && filled($hint ?? null), fn ($ids) => $ids->push($fieldName.'-description'))
        ->when(filled($awareName) && $hasBagError, fn ($ids) => $ids->push($fieldName.'-error'))
        ->filter()
        ->unique()
        ->implode(' ');

    $isRequired = (bool) ($required ?? false) || $attributes->has('required');

    // A named control needs a stable id so the field's <label for> targets it.
    // Respect a consumer-supplied id; default it to the field name otherwise.
    $resolvedId = $attributes->get('id', filled($fieldName) ? $fieldName : null);
@endphp

<input
    type="{{ $type }}"
    @if (filled($resolvedHtmlName)) name="{{ $resolvedHtmlName }}" @endif
    @if (filled($resolvedId)) id="{{ $resolvedId }}" @endif
    @if (! is_null($resolvedValue)) value="{{ $resolvedValue }}" @endif
    data-slot="input"
    @disabled($disabled)
    @required($isRequired)
    @if ($isRequired) aria-required="true" @endif
    @if ($isInvalid) aria-invalid="true" @endif
    @if (filled($describedBy)) aria-describedby="{{ $describedBy }}" @endif
    {{ $attributes->except(['name', 'value', 'id', 'required', 'aria-required', 'aria-describedby'])->merge(['class' => $classes]) }}
/>