@object-ui/fields 17.2.0 → 17.5.0

package/src/standard-widgets.test.tsx

@@ -61,7 +61,14 @@ describe('Standard Field Widgets', () => {
           field={{ ...fieldMock, currency: 'EUR' } as any}
         />
       );
-      expect(screen.getByText('EUR')).toBeInTheDocument();
+      // Was `EUR`, the bare code: the adornment came from a hand-written
+      // `currency === 'USD' ? '$' : currency` ternary, so every currency but one
+      // fell through to its code. objectui#4414 converged the symbol on the
+      // single `Intl` channel the readonly branch of this same widget already
+      // formatted through, which answers `€` here — a DOCUMENTED change, pinned
+      // in full (with the locale-dependence it brings) in
+      // `__tests__/CurrencyField.symbol.test.tsx`.
+      expect(screen.getByText('€')).toBeInTheDocument();
     });
   });
 

package/src/widgets/AddressField.postalCode.test.tsx

@@ -0,0 +1,257 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Postal-code round trip of the composite `address` widget (objectstack#5143).
+ *
+ * The widget used to read and write the part name `zipCode`. The platform
+ * stores — and `/api/v1/data/**` serves back — `postalCode`, the name
+ * `@objectstack/spec`'s `AddressValueSchema` declares. The two never met:
+ *
+ *  - opening a stored address showed an EMPTY ZIP box (the stored
+ *    `postalCode` had no input reading it), and
+ *  - anything typed into that box was written back as `zipCode`, which the
+ *    enforced value schema strips (`$strip`) — destroying it at the contract
+ *    boundary: lost outright on a new record, and on an existing one silently
+ *    discarded while the stale stored code survived.
+ *
+ * Four of five parts round-tripped, which is what made it survive review.
+ *
+ * These tests pin BOTH directions, plus the read-time compatibility limb for
+ * data the broken build already wrote:
+ *
+ *  1. stored `postalCode` reaches the ZIP input;
+ *  2. every edit writes the postal code back under `postalCode` and never
+ *     under `zipCode` — verified against `AddressValueSchema.parse`, i.e. the
+ *     platform's own contract, not a local restatement of it;
+ *  3. a legacy `zipCode`-shaped value still DISPLAYS, and the first edit of
+ *     any part migrates it onto `postalCode` instead of writing the split
+ *     shape back out.
+ *
+ * Reverse verification (measured, not presumed — `git show origin/main` of the
+ * widget, this file unchanged): 9 of 12 go red — 1, 2, 5, 6, 7, 8, 9, 10, 12.
+ * The three that stay GREEN are worth naming, because one of them refines the
+ * issue's stated mechanism:
+ *
+ *  - 3 stays green. The old widget spread the WHOLE stored object through on
+ *    every write (`{...address, [part]: v}`), so an untouched `postalCode`
+ *    survived an edit of an unrelated part. The issue's "saving drops the
+ *    postal code" therefore does NOT reproduce for a value nobody touched;
+ *    the loss the old code really caused is test 6's: a postal code the user
+ *    TYPES is written under a key `AddressValueSchema` strips, so the typed
+ *    correction is silently discarded and the stale stored code stays — and on
+ *    a new record (test 12) it is lost outright. 3 is kept as a contract pin
+ *    for the pass-through, not as evidence of the fix.
+ *  - 4 stays green: it pins the legacy READ, and the old code read that key
+ *    natively. It is meaningful as a pair with 5, which no revert satisfies.
+ *  - 11 stays green: it reads the spec, not the widget. That is the point —
+ *    it fails only if the CONTRACT moves under us.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { AddressValueSchema } from '@objectstack/spec/data';
+import { AddressField, type AddressValue } from './AddressField';
+
+const field = { name: 'billing_address', type: 'address' } as any;
+
+const ZIP_LABEL = 'ZIP / Postal Code';
+
+/** The document the REST API served back in the issue's evidence. */
+const STORED: AddressValue = {
+  street: '中策路 1 号',
+  city: '杭州',
+  state: '浙江',
+  postalCode: '310018',
+  country: 'CN',
+};
+
+/** The same address as written by builds up to 17.0.0-rc.1 (the broken key). */
+const LEGACY = {
+  street: '中策路 1 号',
+  city: '杭州',
+  state: '浙江',
+  zipCode: '310018',
+  country: 'CN',
+} as AddressValue;
+
+/** Resolve a sub-input exactly as a browser does on label activation. */
+function subInput(labelText: string): HTMLInputElement {
+  const label = screen.getByText(labelText);
+  const forId = label.getAttribute('for');
+  expect(forId, `label "${labelText}" must carry htmlFor`).toBeTruthy();
+  const control = document.getElementById(forId!);
+  expect(control, `htmlFor of "${labelText}" must resolve`).not.toBeNull();
+  return control as HTMLInputElement;
+}
+
+/** The most recent object the widget handed to `onChange`. */
+function lastWrite(written: AddressValue[]): AddressValue {
+  expect(written.length, 'the widget must have written at least once').toBeGreaterThan(0);
+  return written[written.length - 1];
+}
+
+/**
+ * Controlled harness — the widget is controlled, so a round trip needs a
+ * parent that stores what the widget writes and feeds it straight back.
+ */
+function Harness({ initial, onWrite }: { initial: AddressValue; onWrite: (v: AddressValue) => void }) {
+  const [value, setValue] = React.useState<AddressValue>(initial);
+  return (
+    <AddressField
+      value={value}
+      onChange={(next) => {
+        onWrite(next);
+        setValue(next);
+      }}
+      field={field}
+    />
+  );
+}
+
+describe('AddressField — postal code round trip (objectstack#5143)', () => {
+  it('1. loads the stored `postalCode` into the ZIP input', () => {
+    render(<AddressField value={STORED} onChange={vi.fn()} field={field} />);
+
+    expect(subInput(ZIP_LABEL).value).toBe('310018');
+    // The four parts that always worked must keep working.
+    expect(subInput('Street Address').value).toBe('中策路 1 号');
+    expect(subInput('City').value).toBe('杭州');
+    expect(subInput('State / Province').value).toBe('浙江');
+    expect(subInput('Country').value).toBe('CN');
+  });
+
+  it('2. keeps the postal code when an UNRELATED part is edited, under `postalCode`', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={STORED} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput('City'), { target: { value: '宁波' } });
+
+    const last = lastWrite(written);
+    expect(last.city).toBe('宁波');
+    expect(last.postalCode).toBe('310018');
+    expect(Object.keys(last)).not.toContain('zipCode');
+    // …and it is still on screen after the write is fed back in.
+    expect(subInput(ZIP_LABEL).value).toBe('310018');
+  });
+
+  it('3. the written address survives the enforced platform value contract', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={STORED} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput('City'), { target: { value: '宁波' } });
+
+    // `AddressValueSchema` is `$strip`: an unknown part name is DROPPED, which
+    // is how a `zipCode`-shaped write lost the postal code on the way to
+    // storage. Parsing the widget's own output is the end-to-end pin.
+    const parsed = AddressValueSchema.parse(lastWrite(written));
+    expect(parsed.postalCode).toBe('310018');
+  });
+
+  it('4. still DISPLAYS a legacy `zipCode`-shaped value written by earlier builds', () => {
+    render(<AddressField value={LEGACY} onChange={vi.fn()} field={field} />);
+
+    expect(subInput(ZIP_LABEL).value).toBe('310018');
+  });
+
+  it('5. migrates a legacy value onto `postalCode` on the first edit of any part', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={LEGACY} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput('Street Address'), { target: { value: '中策路 2 号' } });
+
+    const last = lastWrite(written);
+    expect(last.street).toBe('中策路 2 号');
+    expect(last.postalCode).toBe('310018');
+    expect(Object.keys(last)).not.toContain('zipCode');
+    expect(AddressValueSchema.parse(last).postalCode).toBe('310018');
+  });
+
+  it('6. writes an edit of the ZIP box itself under `postalCode`', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={STORED} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput(ZIP_LABEL), { target: { value: '310019' } });
+
+    const last = lastWrite(written);
+    expect(last.postalCode).toBe('310019');
+    expect(Object.keys(last)).not.toContain('zipCode');
+    expect(subInput(ZIP_LABEL).value).toBe('310019');
+    // The sharpest statement of the bug: under the old key the CORRECTION was
+    // stripped by the contract and the stale stored code survived, with no
+    // error anywhere — the user saw 310019 in the box and 310018 in the record.
+    expect(AddressValueSchema.parse(last).postalCode).toBe('310019');
+  });
+
+  it('7. prefers the canonical key when a record carries both', () => {
+    const both = { ...STORED, zipCode: '999999' } as AddressValue;
+    const written: AddressValue[] = [];
+    render(<Harness initial={both} onWrite={(v) => written.push(v)} />);
+
+    expect(subInput(ZIP_LABEL).value).toBe('310018');
+
+    fireEvent.change(subInput('City'), { target: { value: '宁波' } });
+
+    const last = lastWrite(written);
+    expect(last.postalCode).toBe('310018');
+    expect(Object.keys(last)).not.toContain('zipCode');
+  });
+
+  it('8. clearing the ZIP box clears the postal code instead of resurrecting the legacy value', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={LEGACY} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput(ZIP_LABEL), { target: { value: '' } });
+
+    const last = lastWrite(written);
+    expect(last.postalCode).toBe('');
+    expect(Object.keys(last)).not.toContain('zipCode');
+    expect(subInput(ZIP_LABEL).value).toBe('');
+  });
+
+  it('9. formats the postal code in read-only mode, canonical and legacy alike', () => {
+    const canonical = render(
+      <AddressField value={STORED} onChange={vi.fn()} field={field} readonly />,
+    );
+    expect(canonical.container.textContent).toContain('浙江 310018');
+    canonical.unmount();
+
+    const legacy = render(
+      <AddressField value={LEGACY} onChange={vi.fn()} field={field} readonly />,
+    );
+    expect(legacy.container.textContent).toContain('浙江 310018');
+  });
+
+  it('10. binds the ZIP sub-input to the canonical part name, and nothing to the legacy one', () => {
+    const { baseElement } = render(
+      <AddressField value={STORED} onChange={vi.fn()} field={field} />,
+    );
+
+    expect(subInput(ZIP_LABEL).id).toMatch(/-postalCode$/);
+    const ids = Array.from(baseElement.querySelectorAll('[id]')).map((el) => el.id);
+    expect(ids.filter((id) => id.endsWith('-zipCode'))).toEqual([]);
+  });
+
+  it('11. spells the part the way the spec spells it (direction guard)', () => {
+    const specParts = Object.keys(AddressValueSchema.shape);
+    expect(specParts).toContain('postalCode');
+    expect(specParts).not.toContain('zipCode');
+  });
+
+  it('12. a postal code entered on a NEW record reaches storage instead of being stripped', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={{}} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput(ZIP_LABEL), { target: { value: '310018' } });
+
+    // Nothing stored to mask the loss: under the old key the parse produced an
+    // address with no postal code at all.
+    expect(AddressValueSchema.parse(lastWrite(written)).postalCode).toBe('310018');
+  });
+});

package/src/widgets/AddressField.tsx

@@ -1,110 +1,179 @@
-import React from 'react';
+import React, { useId } from 'react';
 import { Input, Label, EmptyValue } from '@object-ui/components';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
+import { toHostGroupProps } from './toHostGroupProps';
+// The value shape and the single-line formatting rule now live in a pure module
+// so the display (read) cell renderer formats a stored address exactly the way
+// this widget's readonly branch does — one rule, not two copies that drift
+// (objectui#4037). Behaviour here is unchanged; only the definition moved.
+import {
+  formatAddress,
+  readPostalCode,
+  type AddressValue,
+  type LegacyAddressValue,
+} from './address-format';
 
-/**
- * Address data structure
- */
-export interface AddressValue {
-  street?: string;
-  city?: string;
-  state?: string;
-  zipCode?: string;
-  country?: string;
-}
+// Re-exported through its declaring module rather than bare, so the spec-symbol
+// guard resolves the name to where it is actually defined: `address-format`
+// imports `AddressValue` from `@objectstack/spec/data` (objectui#4167), and a
+// bare `export type { AddressValue }` here would read to that guard as a second,
+// local declaration of a name the spec owns.
+export type { AddressValue } from './address-format';
 
 /**
  * Address field widget - provides a structured address input
- * Supports street, city, state, zip code, and country
+ * Supports street, city, state, postal code, and country
  */
-export function AddressField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<AddressValue>) {
+export function AddressField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<AddressValue>) {
   const address = value || {};
+  // DOM pass-through (objectui#3318): the whitelist spread goes onto the FIRST
+  // sub-input (street) — one carrier for the form renderer's aria-describedby;
+  // the composite's validation state goes onto EVERY focusable sub-input via
+  // `aria-invalid={!!error}` (a form-level failure means the whole address is
+  // missing/invalid, and whichever sub-input the user reaches must announce it).
+  //
+  // Two keys are held back from that spread and land on the group CONTAINER
+  // instead (objectui#3961), because they address the field as a WHOLE:
+  //
+  //  - `id` — the host's control id. It never reached the DOM at all: it was
+  //    spread here and then overwritten one line later by `id={subId('street')}`
+  //    (objectui#3343), which is why the form's "Shipping Address" label pointed
+  //    at an id no element carried. The sub-input ids stay exactly as they are;
+  //    only the host id moves out to the element it was always meant to name.
+  //  - `aria-labelledby` — the host's label, associated by IDREF. On the street
+  //    input it would be actively wrong: `aria-labelledby` OVERRIDES a control's
+  //    `<label for>`, so the first sub-input would be announced as "Shipping
+  //    Address" and its own "Street Address" label would vanish.
+  //
+  // Everything else (`aria-describedby`, `name`, focus handlers …) deliberately
+  // stays on the first sub-input: a description or error must be announced when
+  // focus lands on something focusable, and a container is not.
+  const {
+    id: _hostId,
+    'aria-labelledby': _hostLabelledBy,
+    ...domProps
+  } = toDomProps(props);
+  // The pair held back above, in the one spelling every group-labelled widget
+  // uses for it — and computed HERE, before the readonly early return below,
+  // because that return used to drop both keys on the floor: a published label
+  // id with no consumer in the document (objectui#3990). See `toHostGroupProps`.
+  const hostGroupProps = toHostGroupProps(props);
+  // Sub-input ids (objectui#3343): `useId()` prefix + sub-field name — the
+  // `groupId` paradigm of RadioField / CheckboxesField. Hardcoded literals
+  // ("street", "city", …) collide as soon as a form renders two address
+  // fields, and every label's htmlFor then resolves to the FIRST match.
+  const groupId = useId();
+  const subId = (name: keyof AddressValue) => `${groupId}-${name}`;
+
+  // Read through the legacy key, write only the canonical one (objectstack#5143).
+  const postalCode = readPostalCode(address);
 
   const handleFieldChange = (fieldName: keyof AddressValue, fieldValue: string) => {
+    // Normalize while we are here: the object we write back never carries
+    // `zipCode`, and a legacy postal code is carried forward under
+    // `postalCode`. Without the carry, editing an unrelated part of a
+    // legacy-shaped address would write the postal code straight back out of
+    // the record — the very data loss this fixes, one build later.
+    const canonical: LegacyAddressValue = { ...address };
+    delete canonical.zipCode;
     onChange({
-      ...address,
+      ...canonical,
+      ...(postalCode ? { postalCode } : null),
       [fieldName]: fieldValue,
     });
   };
 
-  const formatAddress = (addr: AddressValue): string => {
-    const parts = [
-      addr.street,
-      addr.city,
-      [addr.state, addr.zipCode].filter(Boolean).join(' '),
-      addr.country,
-    ].filter(Boolean);
-    return parts.join(', ');
-  };
-
   if (readonly) {
+    // Readonly the composite collapses to ONE formatted line — no sub-inputs and
+    // no sub-labels — so that line is the surface the host label names, and
+    // `EmptyValue` is the same surface with nothing in it (objectui#3990). The
+    // placeholder's own `aria-label` ("No value") is outranked by
+    // `aria-labelledby` per accname, and on its `generic` role an author name was
+    // never exposed anyway.
     const formatted = formatAddress(address);
-    return formatted ? <span className="text-sm">{formatted}</span> : <EmptyValue />;
+    return formatted ? (
+      <span {...hostGroupProps} className="text-sm">{formatted}</span>
+    ) : (
+      <EmptyValue {...hostGroupProps} />
+    );
   }
 
   return (
-    <div className="space-y-3">
+    // `role="group"` only when a host actually named this container
+    // (objectui#3961): an unnamed group adds nothing for assistive tech, and
+    // standalone rendering — the inline grid editor, a bare SDUI node — must stay
+    // byte-identical to what it was before. That condition now lives in
+    // `toHostGroupProps` so this container and the readonly line above cannot
+    // answer differently (objectui#3990).
+    <div className="space-y-3" {...hostGroupProps}>
       <div>
-        <Label htmlFor="street" className="text-xs">Street Address</Label>
+        <Label htmlFor={subId('street')} className="text-xs">Street Address</Label>
         <Input
-          id="street"
+          {...domProps}
+          id={subId('street')}
           type="text"
           value={address.street || ''}
           onChange={(e) => handleFieldChange('street', e.target.value)}
           placeholder="123 Main St"
           disabled={readonly || props.disabled}
           className={props.className}
+          aria-invalid={!!error}
         />
       </div>
       
       <div className="grid grid-cols-2 gap-3">
         <div>
-          <Label htmlFor="city" className="text-xs">City</Label>
+          <Label htmlFor={subId('city')} className="text-xs">City</Label>
           <Input
-            id="city"
+            id={subId('city')}
             type="text"
             value={address.city || ''}
             onChange={(e) => handleFieldChange('city', e.target.value)}
             placeholder="San Francisco"
             disabled={readonly || props.disabled}
+            aria-invalid={!!error}
           />
         </div>
         
         <div>
-          <Label htmlFor="state" className="text-xs">State / Province</Label>
+          <Label htmlFor={subId('state')} className="text-xs">State / Province</Label>
           <Input
-            id="state"
+            id={subId('state')}
             type="text"
             value={address.state || ''}
             onChange={(e) => handleFieldChange('state', e.target.value)}
             placeholder="CA"
             disabled={readonly || props.disabled}
+            aria-invalid={!!error}
           />
         </div>
       </div>
       
       <div className="grid grid-cols-2 gap-3">
         <div>
-          <Label htmlFor="zipCode" className="text-xs">ZIP / Postal Code</Label>
+          <Label htmlFor={subId('postalCode')} className="text-xs">ZIP / Postal Code</Label>
           <Input
-            id="zipCode"
+            id={subId('postalCode')}
             type="text"
-            value={address.zipCode || ''}
-            onChange={(e) => handleFieldChange('zipCode', e.target.value)}
+            value={postalCode || ''}
+            onChange={(e) => handleFieldChange('postalCode', e.target.value)}
             placeholder="94102"
             disabled={readonly || props.disabled}
+            aria-invalid={!!error}
           />
         </div>
         
         <div>
-          <Label htmlFor="country" className="text-xs">Country</Label>
+          <Label htmlFor={subId('country')} className="text-xs">Country</Label>
           <Input
-            id="country"
+            id={subId('country')}
             type="text"
             value={address.country || ''}
             onChange={(e) => handleFieldChange('country', e.target.value)}
             placeholder="United States"
             disabled={readonly || props.disabled}
+            aria-invalid={!!error}
           />
         </div>
       </div>

package/src/widgets/AddressField.uniqueIds.test.tsx

@@ -0,0 +1,93 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Unique sub-input ids for the composite `address` widget (objectui#3343).
+ *
+ * The widget used to hardcode literal ids ("street", "city", "state",
+ * "postalCode" — spelled "zipCode" until objectstack#5143 —, "country") on its
+ * sub-inputs. Two address fields in one form —
+ * e.g. billing + shipping — then produced duplicate DOM ids, and every
+ * `Label htmlFor` resolved to the FIRST match in the document: each sub-label
+ * of the second field clicked/announced the first field's input.
+ *
+ * The fix follows the `groupId` paradigm of RadioField / CheckboxesField:
+ * a `useId()` prefix + the sub-field name. These tests pin it by rendering
+ * TWO instances in one form:
+ *
+ * 1. every `[id]` in the document is globally unique (red again if anyone
+ *    reverts to hardcoded literals — both instances would emit id="street");
+ * 2. each sub-label of the SECOND instance resolves — via the exact
+ *    mechanism browsers use for label activation, `for` → getElementById —
+ *    to an input inside its OWN instance, and focusing it lands there.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render, within } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { AddressField } from './AddressField';
+
+const field = { name: 'address', type: 'address' } as any;
+
+const SUB_LABELS = [
+  'Street Address',
+  'City',
+  'State / Province',
+  'ZIP / Postal Code',
+  'Country',
+];
+
+function renderTwoInOneForm() {
+  return render(
+    <form>
+      <div data-testid="address-a">
+        <AddressField value={{}} onChange={vi.fn()} field={field} />
+      </div>
+      <div data-testid="address-b">
+        <AddressField value={{}} onChange={vi.fn()} field={field} />
+      </div>
+    </form>,
+  );
+}
+
+describe('AddressField — unique sub-input ids (objectui#3343)', () => {
+  it('two address fields in one form produce globally unique DOM ids', () => {
+    const { baseElement } = renderTwoInOneForm();
+    const ids = Array.from(baseElement.querySelectorAll('[id]')).map((el) => el.id);
+    // 5 sub-inputs per instance — both instances must actually render ids.
+    expect(ids.length).toBeGreaterThanOrEqual(10);
+    const duplicates = ids.filter((id, i) => ids.indexOf(id) !== i);
+    expect(duplicates).toEqual([]);
+  });
+
+  it("each sub-label of the SECOND field focuses that field's own input", () => {
+    const { getByTestId } = renderTwoInOneForm();
+    const first = getByTestId('address-a');
+    const second = getByTestId('address-b');
+
+    for (const text of SUB_LABELS) {
+      const label = within(second).getByText(text);
+      const forId = label.getAttribute('for');
+      expect(forId, `label "${text}" must carry htmlFor`).toBeTruthy();
+
+      // Exactly what the browser does on label click / SR announcement:
+      // resolve `for` against the document.
+      const control = document.getElementById(forId!);
+      expect(control, `htmlFor of "${text}" must resolve`).not.toBeNull();
+      expect(control!.tagName).toBe('INPUT');
+      expect(
+        second.contains(control),
+        `"${text}" must resolve into its OWN field, not the first one`,
+      ).toBe(true);
+      expect(first.contains(control)).toBe(false);
+
+      (control as HTMLInputElement).focus();
+      expect(control).toHaveFocus();
+    }
+  });
+});

package/src/widgets/AvatarField.tsx

@@ -2,16 +2,17 @@ import React from 'react';
 import { Avatar, AvatarFallback, AvatarImage, Button } from '@object-ui/components';
 import { Upload, X } from 'lucide-react';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 
 /**
  * Avatar field widget - provides an avatar/profile picture uploader
  * Supports image URLs or file uploads
  */
-export function AvatarField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<string>) {
+export function AvatarField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<string>) {
   const [isHovered, setIsHovered] = React.useState(false);
   const fileInputRef = React.useRef<HTMLInputElement>(null);
   
-  const avatarField = (field || (props as any).schema) as any;
+  const avatarField = field as any;
 
   const handleFileSelect = (event: React.ChangeEvent<HTMLInputElement>) => {
     const file = event.target.files?.[0];
@@ -92,11 +93,17 @@ export function AvatarField({ value, onChange, field, readonly, ...props }: Fiel
           className="hidden"
         />
         <Button
+          // DOM pass-through onto the widget's real focusable control — the
+          // upload button is the keyboard path to the hidden file input
+          // (objectui#3318).
+          {...toDomProps(props)}
           type="button"
           variant="outline"
           size="sm"
           onClick={() => fileInputRef.current?.click()}
           disabled={readonly || props.disabled}
+          // AFTER the spread so this widget's own computation wins (#3222).
+          aria-invalid={!!error}
         >
           <Upload className="w-4 h-4 mr-2" />
           {value ? 'Change' : 'Upload'} Avatar