@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/input-group.usage.gts

@@ -0,0 +1,283 @@
+// Pretui — InputGroup usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { InputGroup } from './input-group';
+
+const INPUT_GROUP_TYPES = ['text', 'email', 'password', 'number', 'search', 'url'];
+
+const CURRENCIES = ['USD', 'EUR', 'GBP', 'JPY'];
+
+const IG_STATES = ['none', 'initial', 'valid', 'invalid', 'loading'];
+
+function labelOf(item: unknown): string {
+  return String(item);
+}
+
+// ── InputGroup ← input-group/usage.gts ───────────────────────────────────
+// Rebuilt as a wrap of boxel-ui's InputGroup — the full contextual surface
+// is now live: <:before>/<:after> yield boxel's Accessories (Button /
+// IconButton / Select / Text), <:default> yields Controls (Input /
+// Textarea) for multi-control groups, and validation graduates to the
+// @state enum + @errorMessage/@helperText rows. The plain <:start>/<:end>
+// blocks are preserved (auto-wrapped in Accessories.Text). Knobs ported
+// from boxel-ui's usage page: state, errorMessage, helperText, placeholder,
+// disabled, value. Dropped upstream knobs: @validIcon/@invalidIcon (kit
+// keeps the default state icons), @inputmode/@name (splat native attrs),
+// boxel-input-group-* css vars (theme tokens own the dress).
+class InputGroupUsage extends Component {
+  typeOptions = INPUT_GROUP_TYPES;
+  stateOptions = IG_STATES;
+  currencies = CURRENCIES;
+  @tracked value = '';
+  @tracked placeholder = 'Amount';
+  @tracked type = 'text';
+  @tracked state = 'none';
+  @tracked errorMessage = 'This amount is invalid.';
+  @tracked helperText = 'Please enter an amount';
+  @tracked disabled = false;
+  @tracked shareUrl = 'https://stack.cards/ctse/pretui';
+  @tracked username = '';
+  @tracked server = '';
+  @tracked currency: string | null = 'USD';
+  setValue = (v: string) => (this.value = v);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setType = (v: string) => (this.type = v);
+  setState = (v: string) => (this.state = v);
+  setErrorMessage = (v: string) => (this.errorMessage = v);
+  setHelperText = (v: string) => (this.helperText = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setShareUrl = (v: string) => (this.shareUrl = v);
+  setUsername = (v: string) => (this.username = v);
+  setServer = (v: string) => (this.server = v);
+  setCurrency = (item: unknown) => (this.currency = item as string);
+  copyShareUrl = () => {
+    navigator.clipboard.writeText(this.shareUrl).catch(() => {});
+  };
+  get stateVal() {
+    return this.state as
+      | 'none'
+      | 'initial'
+      | 'valid'
+      | 'invalid'
+      | 'loading';
+  }
+  // Live per-type validation so the type knob visibly bites: with the state
+  // knob on 'none', a value that mismatches the chosen type paints the
+  // invalid ring immediately (email against digits, url without http, …).
+  get typeMismatch(): string | null {
+    if (!this.value) return null;
+    switch (this.type) {
+      case 'email':
+        return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(this.value)
+          ? null
+          : 'That doesn’t look like an email address.';
+      case 'url':
+        return /^https?:\/\/\S+\.\S+/.test(this.value)
+          ? null
+          : 'A URL here needs to start with http(s)://';
+      case 'number':
+        return Number.isNaN(Number(this.value))
+          ? 'Only digits make sense here.'
+          : null;
+      default:
+        return null;
+    }
+  }
+  get liveState() {
+    if (this.state !== 'none') return this.stateVal;
+    return this.typeMismatch ? ('invalid' as const) : this.stateVal;
+  }
+  get liveErrorMessage() {
+    if (this.state !== 'none') return this.errorMessage;
+    return this.typeMismatch ?? this.errorMessage;
+  }
+  get usage() {
+    let bits = [`@value='${this.value}'`];
+    if (this.placeholder) bits.push(`@placeholder='${this.placeholder}'`);
+    if (this.type !== 'text') bits.push(`@type='${this.type}'`);
+    if (this.state !== 'none') bits.push(`@state='${this.state}'`);
+    if (this.disabled) bits.push('@disabled={{true}}');
+    bits.push('@onInput={{this.setValue}}');
+    return `<InputGroup ${bits.join(' ')}>\n  <:start>$</:start>\n  <:end>.00</:end>\n</InputGroup>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='InputGroup'
+      @description="Extend inputs by adding text, buttons, and selects on either side of textual inputs — a wrap of boxel-ui's InputGroup, so accessories share one hairline and one focus ring with the control. Type here and watch the readout track state."
+      @source={{this.usage}}
+    >
+      <:example>
+        <InputGroup
+          @value={{this.value}}
+          @placeholder={{this.placeholder}}
+          @type={{this.type}}
+          @state={{this.liveState}}
+          @errorMessage={{this.liveErrorMessage}}
+          @helperText={{this.helperText}}
+          @disabled={{this.disabled}}
+          @onInput={{this.setValue}}
+        >
+          <:start>$</:start>
+          <:end>.00</:end>
+        </InputGroup>
+        <p class='pretui-demo-readout' data-test-input-group-readout>
+          type = {{this.type}} · value = “{{this.value}}”
+          {{#if this.typeMismatch}}· mismatch{{/if}}
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @description='The value of the input'
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='placeholder'
+          @value={{this.placeholder}}
+          @description='The placeholder text for the input'
+          @onInput={{this.setPlaceholder}}
+        />
+        <Args.String
+          @name='type'
+          @defaultValue='text'
+          @value={{this.type}}
+          @options={{this.typeOptions}}
+          @description='Native input type — pick number or password to see the control change shape; the readout under the example tracks it.'
+          @onInput={{this.setType}}
+        />
+        <Args.String
+          @name='state'
+          @defaultValue='none'
+          @value={{this.state}}
+          @options={{this.stateOptions}}
+          @description="boxel-ui's validation-state enum — valid/invalid render state icons, invalid enables the errorMessage row, loading disables the group."
+          @onInput={{this.setState}}
+        />
+        <Args.String
+          @name='errorMessage'
+          @value={{this.errorMessage}}
+          @description="Error row under the group; renders while @state='invalid'."
+          @onInput={{this.setErrorMessage}}
+        />
+        <Args.String
+          @name='helperText'
+          @value={{this.helperText}}
+          @description='Helper row under the group.'
+          @onInput={{this.setHelperText}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @description='Whether the input is disabled'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Bool
+          @name='invalid'
+          @description="Kept as sugar for @state='invalid'; @state wins when both are set."
+        />
+        <Args.String
+          @name='controlId'
+          @description="The input's id for label wiring — supplied by a wrapping Field's yielded controlId; replaces boxel-ui's @id."
+        />
+        <Args.Action
+          @name='onInput'
+          @description='Receives the changed value as a string.'
+        />
+        <Args.Yield
+          @name='start'
+          @description="Leading plain-content accessory — auto-wrapped in boxel's Text accessory."
+        />
+        <Args.Yield
+          @name='end'
+          @description='Trailing plain-content accessory — auto-wrapped.'
+        />
+        <Args.Yield
+          @name='before'
+          @description="Yields boxel's Accessories (Button / IconButton / Select / Text) and {elementId} ahead of the control."
+        />
+        <Args.Yield
+          @name='after'
+          @description='Same contextual Accessories, after the control.'
+        />
+        <Args.Yield
+          @name='default'
+          @description="Yields Controls (Input / Textarea), Accessories, and {elementId} — supply your own control row; @value/@placeholder/@type are ignored when present."
+        />
+      </:api>
+    </FreestyleUsage>
+    <FreestyleUsage
+      @name='InputGroup compositions'
+      @description="Composite groups through the contextual blocks — a button accessory wired to an action, a select accessory, and a multi-control default block. The select accessory's dropdown portals to boxel's wormhole, so it wears boxel default colors (accepted wart — no @renderInPlace passthrough)."
+    >
+      <:example>
+        <div class='pretui-ig-stack'>
+          <InputGroup
+            @value={{this.shareUrl}}
+            @placeholder='Share link'
+            @onInput={{this.setShareUrl}}
+          >
+            <:after as |Accessories|>
+              <Accessories.Button
+                {{on 'click' this.copyShareUrl}}
+              >Copy</Accessories.Button>
+            </:after>
+          </InputGroup>
+          <InputGroup @placeholder='Amount' @onInput={{this.setValue}}>
+            <:before as |Accessories|>
+              <Accessories.Text>$</Accessories.Text>
+            </:before>
+            <:after as |Accessories|>
+              <Accessories.Select
+                @placeholder='Currency'
+                @options={{this.currencies}}
+                @selected={{this.currency}}
+                @onChange={{this.setCurrency}}
+                aria-label='Currency'
+                as |item|
+              >
+                <div>{{labelOf item}}</div>
+              </Accessories.Select>
+            </:after>
+          </InputGroup>
+          <InputGroup>
+            <:default as |Controls Accessories group|>
+              <Controls.Input
+                id={{group.elementId}}
+                @placeholder='Username'
+                @onInput={{this.setUsername}}
+              />
+              <Accessories.Text>@</Accessories.Text>
+              <Controls.Input
+                @placeholder='Server'
+                @onInput={{this.setServer}}
+              />
+            </:default>
+          </InputGroup>
+          <p class='pretui-demo-readout'>
+            currency = {{this.currency}} · handle = “{{this.username}}@{{this.server}}”
+          </p>
+        </div>
+      </:example>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-ig-stack {
+        display: grid;
+        gap: 12px;
+      }
+      .pretui-demo-readout {
+        margin: 8px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_INPUT_GROUP: Record<string, unknown> = {
+  InputGroup: InputGroupUsage,
+};

package/bundled-realms/pretui/components/input.examples.gts

@@ -0,0 +1,61 @@
+// Pretui — Input example gallery.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import {
+  DATES,
+  PEOPLE,
+  SUPPLIERS,
+  pick,
+  seedFrom,
+} from '../examples-kit';
+import type { ExampleSpec } from '../examples-kit';
+import { Input } from './input';
+import { Field } from './field';
+
+// ── Input ────────────────────────────────────────────────────────────────
+const INP = seedFrom('Input');
+const inpSupplier = pick(INP, 0, SUPPLIERS);
+const inpBadEmail = pick(INP, 1, PEOPLE).split(' ')[0].toLowerCase() + '@silverpeak';
+const inpLot = 'LOT-' + pick(INP, 2, DATES).replaceAll('-', '').slice(2);
+
+const InputPrefilled: TemplateOnlyComponent = <template>
+  <Field @label='Supplier name' @hint='Public — shows on the order card' as |id|>
+    <Input @controlId={{id}} @value={{inpSupplier}} />
+  </Field>
+</template>;
+
+const InputInvalid: TemplateOnlyComponent = <template>
+  <Field
+    @label='Contact email'
+    @error='This does not look like an email'
+    as |id|
+  >
+    <Input @controlId={{id}} @type='email' @invalid={{true}} @value={{inpBadEmail}} />
+  </Field>
+</template>;
+
+const InputDisabled: TemplateOnlyComponent = <template>
+  <Field @label='Lot code' @hint='Assigned at intake — read-only' as |id|>
+    <Input @controlId={{id}} @disabled={{true}} @value={{inpLot}} />
+  </Field>
+</template>;
+
+export const EXAMPLES_INPUT: Record<string, ExampleSpec[]> = {
+  Input: [
+    {
+      title: 'Prefilled field',
+      note: 'Field supplies the label and the reserved message line.',
+      component: InputPrefilled,
+    },
+    {
+      title: 'Invalid email',
+      note: 'The error replaces the hint without shifting the layout.',
+      component: InputInvalid,
+    },
+    {
+      title: 'Read-only lot code',
+      note: 'Disabled keeps the value legible for reference.',
+      component: InputDisabled,
+    },
+  ],
+};
+

package/bundled-realms/pretui/components/input.gts

@@ -0,0 +1,202 @@
+// Pretui — Input: BoxelInput retrofit in Pretui control dress.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { BoxelInput } from '@cardstack/boxel-ui/components';
+import { emit, firstDefined } from '../pretui-primitives';
+import type { ControlAliasArgs } from '../pretui-primitives';
+
+export interface InputSignature {
+  Args: ControlAliasArgs & {
+    value?: string;
+    placeholder?: string;
+    type?: string;
+    invalid?: boolean;
+    disabled?: boolean;
+    controlId?: string;
+    onInput?: (value: string) => void;
+    /** additive — helper line under the control (boxel-ui machinery) */
+    helperText?: string;
+    /** additive — error line under the control; renders while @invalid */
+    errorMessage?: string;
+    /** additive — native required; also suppresses the optional indicator */
+    required?: boolean;
+    /** additive — renders boxel-ui's 'Optional' indicator above the control */
+    optional?: boolean;
+    /** additive — native readonly */
+    readonly?: boolean;
+    /** alias — React Aria / Base UI spelling of @invalid */
+    isInvalid?: boolean;
+    /** alias for @helperText — the shadcn/Chakra Field spelling */
+    description?: string;
+  };
+  Element: HTMLInputElement;
+}
+
+// Input wraps boxel-ui's BoxelInput, which carries the machinery —
+// validation-state plumbing, aria-invalid/aria-errormessage/aria-describedby
+// wiring, error + helper message rows, optional indicator — while the
+// wrapper div re-dresses it through the semantic-token + --boxel-*
+// custom-property channel (same pattern as EmailInput/PhoneInput; no CSS
+// reaches into boxel-ui markup). The inline style beats the two spots the
+// channel cannot reach — the UA font on native controls and element-local
+// var definitions in boxel's own sheet; splatted attributes land on the
+// inner input, so aria-label / autocomplete / min / max keep working.
+// `--boxel-input-height` is a MIN-height; the natural height is
+// border + padding-block + line-height, and the inherited `normal`
+// line-height overshoots it, so an Input would sit taller than every other
+// control in the kit. The wrapper token channel cannot reach the UA
+// line-height; the inline constant can. Borders, padding-block and
+// --boxel-form-control-line-height-sm add up to
+// --boxel-form-control-height-sm (1.75rem); the line-height token assumes
+// this padding-block, so change them together. A color input keeps
+// BoxelInput's `padding: 0`, or its swatch shrinks inside the fixed box.
+const INPUT_FONT = htmlSafe(
+  'font: inherit; letter-spacing: inherit; line-height: var(--boxel-form-control-line-height-sm); padding-block: 0.25rem;',
+);
+const COLOR_INPUT_FONT = htmlSafe('font: inherit; letter-spacing: inherit;');
+
+export class Input extends Component<InputSignature> {
+  get invalid() {
+    return firstDefined(this.args.invalid, this.args.isInvalid) ?? false;
+  }
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled);
+  }
+  get required() {
+    return firstDefined(this.args.required, this.args.isRequired);
+  }
+  get readonly() {
+    return firstDefined(
+      this.args.readonly,
+      this.args.isReadOnly,
+      this.args.readOnly,
+    );
+  }
+  get helperText() {
+    return firstDefined(this.args.helperText, this.args.description);
+  }
+  get state() {
+    return this.invalid ? 'invalid' : 'none';
+  }
+  get inputStyle() {
+    return this.args.type === 'color' ? COLOR_INPUT_FONT : INPUT_FONT;
+  }
+  handleInput = (value: string) => {
+    emit(
+      [this.args.onInput, this.args.onChange, this.args.onValueChange],
+      value,
+    );
+  };
+  <template>
+    <div
+      class='pretui-inputwrap'
+      data-invalid={{if this.invalid 'true'}}
+      data-test-pretui-input
+    >
+      <BoxelInput
+        @id={{@controlId}}
+        @type={{if @type @type 'text'}}
+        @value={{@value}}
+        @placeholder={{@placeholder}}
+        @disabled={{this.disabled}}
+        @readonly={{this.readonly}}
+        @state={{this.state}}
+        @errorMessage={{unless this.disabled @errorMessage}}
+        @helperText={{this.helperText}}
+        @required={{this.required}}
+        @optional={{@optional}}
+        @onInput={{this.handleInput}}
+        style={{this.inputStyle}}
+        ...attributes
+      />
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        /* the kit's field style, Select's trigger the reference, fed into
+           BoxelInput via its token channel: the --field face, an --input
+           edge, the theme's --ring and --muted-foreground, Button's corner,
+           a --boxel-form-control-height-sm height and --boxel-font-size-xs
+           type */
+        .pretui-inputwrap {
+          width: 100%;
+          font-size: var(--boxel-font-size-xs);
+          letter-spacing: var(--boxel-lsp-xs);
+          --background: var(--field);
+          --border: var(--input);
+          --boxel-form-control-height: var(--boxel-form-control-height-sm);
+          --boxel-input-height: var(--boxel-form-control-height-sm);
+          --boxel-form-control-border-radius: calc(var(--radius) - 2px);
+          /* the helper and error rows and the Optional label, a step below
+             the field's text */
+          --boxel-font-size-sm: var(--boxel-font-size-2xs);
+          --boxel-input-optional-font-size: var(--boxel-font-size-2xs);
+          --boxel-sp-xs: var(--boxel-sp-3xs);
+          /* Select's 0.625rem text inset on both sides, less this edge's 1px
+             border. While the invalid icon shows, BoxelInput reserves its
+             column at the end instead; a search input keeps BoxelInput's
+             start inset, which clears the search icon. */
+          --boxel-sp-sm: calc(0.625rem - 1px);
+          --boxel-input-padding-inline-end: calc(0.625rem - 1px);
+          /* Select's and Autocomplete's states. Hover leaves the edge alone
+             unless the pointer can hover (below). Focus is the kit's 2px --ring
+             outline, laid over the 1px border, which BoxelInput turns --ring. */
+          --boxel-input-hover-border-color: var(--border);
+          --boxel-input-outline: 0 solid transparent;
+          --boxel-input-outline-offset: -1px;
+          --boxel-input-invalid-color: var(--destructive-ink);
+          --boxel-input-invalid-box-shadow: none;
+          --boxel-input-invalid-focus-outline: 2px solid var(--ring);
+          --boxel-input-invalid-focus-box-shadow: none;
+          --boxel-input-disabled-opacity: 0.45;
+          /* read-only stays focusable and copyable, so it isn't dimmed */
+          --boxel-input-readonly-opacity: 1;
+          /* the invalid dress this control takes, from @invalid or an invalid
+             Field: the -ink edge, as on Autocomplete (the fill hue misses a
+             boundary's 3:1), and no tint */
+          --pretui-invalid-border: var(--destructive-ink);
+          --pretui-invalid-background: var(--field);
+        }
+        @media (hover: hover) {
+          /* Select's hover edge: toward --foreground, in both schemes. It
+             mixes from --border, so an invalid field (from @invalid or an
+             invalid Field) keeps its error edge on hover, darkened. */
+          .pretui-inputwrap {
+            --boxel-input-hover-border-color: color-mix(
+              in oklch,
+              var(--foreground) 30%,
+              var(--border)
+            );
+          }
+          /* only hovering the field itself, not its message rows */
+          .pretui-inputwrap:has(input:hover) {
+            --boxel-input-invalid-color: var(--boxel-input-hover-border-color);
+          }
+        }
+        /* forced colors paint a transparent outline, so it only gets a width
+           on focus; at rest it would look the same as the focus ring. Focus
+           swaps the error edge for the ring, which wins over hover. */
+        .pretui-inputwrap:has(input:focus) {
+          --boxel-input-outline: 2px solid transparent;
+          --boxel-input-invalid-color: var(--ring);
+        }
+        /* iOS zooms into inputs under 16px on focus */
+        @media (pointer: coarse) {
+          .pretui-inputwrap {
+            font-size: var(--boxel-form-control-touch-font-size);
+          }
+        }
+        /* a disabled field can't be fixed, so it drops the error edge (and
+           the template drops the error row) */
+        .pretui-inputwrap:has(input:disabled) {
+          --pretui-invalid-border: var(--input);
+        }
+        /* Input owns @invalid, so it applies the invalid edge itself;
+           Field's rule only adds it for a Field-level error */
+        .pretui-inputwrap[data-invalid='true'] {
+          --border: var(--pretui-invalid-border);
+        }
+      }
+    </style>
+  </template>
+}
+

package/bundled-realms/pretui/components/input.md

@@ -0,0 +1,67 @@
+## What it is
+
+The kit's single-line text control. Every typed value that is not a picker goes through it, and the typed-input family — **EmailInput**, **PhoneInput**, **UrlInput**, **PasswordInput**, **NumberInput**, **SearchInput** — is built on the same underlying machinery with format-specific behavior layered on. Reach for `Input` directly for free text; reach for the typed sibling when the value has a shape, because those add validation, `inputmode`, `autocomplete` and affordances you would otherwise re-invent. For multi-line use **Textarea**; for a value chosen from a list use **Select**; for a value chosen from a list _or_ typed freely use **Combobox**.
+
+## The contract
+
+```
+@value?, @placeholder?, @type? (default 'text'), @invalid?, @disabled?, @controlId?
+@onInput?(value: string)
+@helperText?, @errorMessage?, @required?, @optional?
+```
+
+`@onInput` receives the **string value**, not the event. That is the kit-wide convention for controls and it is why call sites never touch `event.target`.
+
+`@controlId` exists so **Field** and **FormField** can mint an id, put it on their `<label for>`, and hand it down. Input does not generate its own id — labelling is the wrapper's job, and this keeps a single owner for the association.
+
+The non-obvious decision: **Input is a retrofit on boxel-ui's `BoxelInput`, not a raw `<input>`.** BoxelInput carries the machinery — validation-state plumbing, `aria-invalid` / `aria-errormessage` / `aria-describedby` wiring, the error and helper message rows, the "Optional" indicator. Pretui keeps its own unchanged signature on the outside and re-dresses the inside through a **token channel**: the wrapper `<div>` redefines `--background`, `--border` and a set of `--boxel-*` dimension knobs, and BoxelInput restyles itself. No Pretui CSS reaches into boxel-ui markup, so a boxel-ui upgrade cannot break the dress.
+
+Two places the channel cannot reach, handled by a single inline `style`: the UA font on native controls, and variables boxel defines on the element itself. Splatted `...attributes` land on the **inner** `<input>`, so `aria-label`, `autocomplete`, `min`, `max` and friends still work.
+
+## Prior art
+
+**Web Awesome `wa-input`** is a full custom element with `label`, `hint`, `clearable`, `password-toggle`, `with-label`/`with-hint` slots, plus the whole constraint-validation surface. **React Spectrum `TextField`** splits `label`/`description`/`errorMessage` as props and returns wiring from `useTextField`, with `validationState` (now `isInvalid`) driving both. **shadcn `Input`** is a styled `<input>` and nothing else — no label, no error, no wiring.
+
+Pretui sits deliberately between them. It does not own its label (Field/FormField does), which avoids the two-labels problem you hit when a form layout also wants to place labels. But unlike shadcn it _does_ carry `@helperText` and `@errorMessage`, because those are ARIA-wired by the layer below and re-implementing them at the wrapper would mean re-implementing the wiring.
+
+The genuine improvement over both: **invalid styling travels through the token channel.** Field sets `data-invalid` on itself, and its stylesheet repoints `--border` on the wrapper — the inner control re-dresses itself. Compare the usual approach of a `.error` class threaded down through every layer. It also means a theme can change what "invalid" looks like by changing one token.
+
+## Accessibility
+
+Native `<input>`; no APG pattern needed. The wiring that matters is inherited from BoxelInput: `aria-invalid` when `@invalid`, `aria-errormessage` pointing at the rendered error row, `aria-describedby` pointing at the helper row.
+
+Honest gaps:
+
+- **`@invalid` and `@errorMessage` are independent.** Passing `@invalid` without `@errorMessage` produces a red control with nothing announced; passing `@errorMessage` without `@invalid` renders nothing (the error row is gated on validation state). Nothing warns you. Always pass both, or use **FormField**, which does it for you.
+- **No accessible name of its own.** An `<Input>` used outside `Field`/`FormField`/`FormField`'s descendants and without an explicit `aria-label` is unlabeled. A placeholder is not a label.
+- `@required` sets the native attribute, which is correct, and suppresses the "Optional" indicator. `@optional` is a purely visual marker with no ARIA meaning — fine, but do not read it as the inverse of `@required`.
+- `@disabled` uses the native attribute, so the control leaves the tab order and its value is not submitted. If you need a read-only-but-focusable field, pass `readonly` through `...attributes` instead.
+- The focus ring is the kit's 2px `--ring` outline laid over the edge, so it still shows in forced-colors mode.
+
+## Theming
+
+Input, **Select** and **Autocomplete** share one field look at rest: a `--field` face with `--foreground` text, an `--input` edge, a `--muted-foreground` placeholder, Button's corner (`calc(var(--radius) - 2px)`), a `--boxel-form-control-height-sm` (1.75rem) height and `--boxel-font-size-xs` text, with the helper and error rows and the Optional label a step below at `--boxel-font-size-2xs`. On touch screens (`pointer: coarse`) the field's text and placeholder are at least 16px (`--boxel-form-control-touch-font-size`), so iOS doesn't zoom into the field on focus.
+
+The three share their states too. Hover pulls the edge 30% toward `--foreground`, only where the pointer can hover, so the edge doesn't stick after a tap. Invalid is a `--destructive-ink` edge, since the `--destructive` fill misses the 3:1 a field boundary needs; hovering the field (not its message rows) darkens it the same 30% toward `--foreground`, and focus swaps it for the ring, as GOV.UK, Carbon and Primer do. Disabled is 0.45 opacity with the usual edge and no error row, invalid or not, since a disabled field can't be fixed; read-only isn't dimmed, since the field can still be focused and its value copied. Focus is a 2px `--ring` outline.
+
+Forwarded into boxel-ui: `--boxel-form-control-height`, `--boxel-input-height`, `--boxel-form-control-border-radius`, `--boxel-font-size-sm` (the helper and error rows), `--boxel-sp-xs`, `--boxel-sp-sm`, and the state knobs `--boxel-input-hover-border-color`, `--boxel-input-outline`, `--boxel-input-outline-offset`, `--boxel-input-invalid-color`, `--boxel-input-invalid-box-shadow`, `--boxel-input-invalid-focus-outline`, `--boxel-input-invalid-focus-box-shadow`, `--boxel-input-disabled-opacity` and `--boxel-input-readonly-opacity`. The end inset goes in through `--boxel-input-padding-inline-end`, so while the invalid icon shows, BoxelInput can swap it for the icon's column. Input also sets `--pretui-invalid-border` and `--pretui-invalid-background`, which tell Field how to dress it when the Field has an error.
+
+A theme must keep `--field` and `--card` visually distinct or inputs vanish into panels; and must not set `--input` equal to `--border` if it wants controls to read as inset rather than as bordered boxes.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| React / Aria / MUI / Ant                           | Pretui Input                          |
+| -------------------------------------------------- | ------------------------------------- |
+| TextField / TextInput / Input                      | this tile + channel wrappers          |
+| `isInvalid` / `error` / `status=error`             | @invalid + **FieldError**             |
+| `isDisabled` / `disabled`                          | @disabled                             |
+| `isReadOnly` / `readOnly`                          | @readonly                             |
+| `isRequired` / `required`                          | @required                             |
+| `prefix` / `suffix` / InputAdornment / addonBefore | **InputGroup**                        |
+| `allowClear` / `onClear`                           | **SearchInput** clear                 |
+| `type=search\|password\|email\|url\|number`        | the channel wrappers, not a type soup |
+
+- [ ] Accept `isInvalid` / `isDisabled` / `isReadOnly` / `isRequired`.
+- [ ] Keep channel wrappers as the home for search/password/email/url/number.