@object-ui/fields 17.1.0 → 17.3.0

package/src/__tests__/spec-symbol-batch7.test.ts

@@ -0,0 +1,126 @@
+/**
+ * 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.
+ */
+
+/**
+ * `@object-ui/fields` ↔ `@objectstack/spec` symbol-collision guards
+ * (objectui#3161, objectstack#4115 ledger batch 7).
+ *
+ * Two symbols, two different verdicts:
+ *
+ *  - `isFileIdToken` was a character-for-character copy of the spec's function
+ *    under the spec's own name. It is a re-export now, and the gate below is
+ *    REFERENCE IDENTITY — not behaviour. A faithful copy passes every behaviour
+ *    test ever written for it (objectui#3003, re-proved on
+ *    `isAggregatedViewContainer` in objectui#3169), so `toBe` is the only
+ *    assertion that can tell a re-export from a fork.
+ *
+ *  - `FieldWidgetProps` is now `FieldWidgetComponentProps`. The spec owns that
+ *    name for the DECLARED widget-plugin props contract; this package's is the
+ *    React interface its widgets implement. The pins record what still makes
+ *    re-exporting impossible (`field` is the far richer `FieldMetadata` here)
+ *    and, since objectui#3222, what no longer does: the validation slot is the
+ *    spec's `error` on both sides.
+ *
+ * The other direction — "the spec must not start owning the NEW names" — is not
+ * asserted here because `scripts/check-spec-symbol-derivation.mjs` already
+ * answers it on every CI run, for every name in the package rather than the
+ * handful a test would remember to list.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { isFileIdToken as specIsFileIdToken } from '@objectstack/spec/data';
+import type { FieldWidgetProps as SpecFieldWidgetProps } from '@objectstack/spec/ui';
+
+import { isFileIdToken, fileIdOf } from '../widgets/file-value';
+import type { FieldWidgetComponentProps } from '../widgets/types';
+
+describe('isFileIdToken IS the spec function', () => {
+  it('is the same function object, not an equivalent one', () => {
+    // The whole point. Every value/behaviour assertion below this line would
+    // also pass against a re-forked copy; this one would not.
+    expect(isFileIdToken).toBe(specIsFileIdToken);
+  });
+
+  it('is the arbiter the rest of the module routes through', () => {
+    // `fileIdOf` must keep agreeing with the shared predicate, so a future
+    // "small local tweak" to the id shape cannot be reintroduced one caller at
+    // a time.
+    for (const value of ['abc123', 'AbC-_9', 'x'.repeat(64)]) {
+      expect(specIsFileIdToken(value)).toBe(true);
+      expect(fileIdOf(value)).toBe(value);
+    }
+    for (const value of ['https://example.com/f.png', '/api/v1/storage/files/1', 'a.b', 'x'.repeat(65)]) {
+      expect(specIsFileIdToken(value)).toBe(false);
+      expect(fileIdOf(value)).toBeUndefined();
+    }
+  });
+});
+
+/* -------------------------------------------------------------------------- */
+/* Compile-time pins. A violation is a `tsc` error, not a runtime failure.     */
+/* This package's tsconfig.json includes its tests, so `type-check` compiles   */
+/* them (scripts/check-type-check-coverage.mjs keeps that true).              */
+/* -------------------------------------------------------------------------- */
+
+type Assert<T extends true> = T;
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type Extends<A, B> = [A] extends [B] ? true : false;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type HasKey<T, K extends string> = K extends keyof T ? true : false;
+
+describe('FieldWidgetComponentProps is the RENDERED layer of the spec contract', () => {
+  it('is pinned at compile time', () => {
+    // The import above is itself half the tripwire: the day the spec stops
+    // exporting `FieldWidgetProps`, this file stops compiling and the rename's
+    // reason is up for re-triage (the plain name could come back).
+    type _SpecIsReal = Assert<Equal<IsAny<SpecFieldWidgetProps>, false>>;
+
+    // The validation-message slot no longer diverges. objectui#3161 could only
+    // RECORD that the declared contract called it `error` while every widget
+    // here read `errorMessage`; objectui#3222 resolved it in the direction the
+    // contract points — this package adopted `error`, and the form renderer
+    // started producing it, so the name and the delivery landed together.
+    // Both sides are pinned: the spec still owns the name, and this package
+    // still spells it the same way.
+    type _SpecNamesItError = Assert<HasKey<SpecFieldWidgetProps, 'error'>>;
+    type _LocalNamesItErrorToo = Assert<HasKey<FieldWidgetComponentProps, 'error'>>;
+    type _SameOptionalStringSlot = Assert<
+      Equal<FieldWidgetComponentProps['error'], SpecFieldWidgetProps['error']>
+    >;
+    // The old name is gone, not kept as an alias. An alias would be exactly the
+    // lenient second dialect AGENTS.md #0.1 forbids — and the reason a missed
+    // call site would have gone quiet again.
+    type _OldNameRetired = Assert<Equal<HasKey<FieldWidgetComponentProps, 'errorMessage'>, false>>;
+
+    // …and the reason nobody noticed used to sit right here: three pins
+    // asserting that `[key: string]: any` was still present, and that
+    // `props.required` / `props.error` therefore read as `any`. objectui#3221
+    // removed that index signature, so those pins have gone red on purpose and
+    // are gone with it. What replaces them is the inverse claim — the type is
+    // now CLOSED, so a key the spec declares and this one does not can finally
+    // be reported as missing. That is what made objectui#3222's rename
+    // decidable by the compiler instead of by a symbol guard.
+    type _NoStringIndexSignature = Assert<Equal<Extends<string, keyof FieldWidgetComponentProps>, false>>;
+    // `required` is the one key that stayed behind, and deliberately so
+    // (objectui#3222): the required marker has a single author — the form
+    // renderer's `<FormLabel>` — and lowering the flag into widget props gives
+    // it a second, i.e. the double-display failure that also keeps the
+    // validation TEXT out of the widget. The a11y state a widget could
+    // legitimately carry is `aria-required`, and `AriaAttributes` already
+    // supplies that key with no contract change at all.
+    type _RequiredIsAbsent = Assert<Equal<HasKey<FieldWidgetComponentProps, 'required'>, false>>;
+
+    // `data-*` stays open (it is open in HTML too), but as a template-literal
+    // key — the distinction that keeps `keyof` finite above. A pin, because
+    // widening it back to `[key: string]` would silently restore the defect
+    // while every assertion here still read as "closed".
+    type _DataAttributesStayOpen = Assert<Extends<'data-testid', keyof FieldWidgetComponentProps>>;
+
+    expect(true).toBe(true);
+  });
+});

package/src/__tests__/validation-feedback.test.tsx

@@ -10,7 +10,16 @@
  * P3.2 Field Widget Polish - Validation Feedback
  *
  * Tests that field widgets consistently handle validation feedback:
- * errorMessage prop, aria-invalid attribute, and disabled states.
+ * `error` prop, aria-invalid attribute, and disabled states.
+ *
+ * The slot is `error` — the name `@objectstack/spec/ui`'s
+ * `FieldWidgetPropsSchema` gives it — since objectui#3222. These are the
+ * CONSUMER half only: they prove a widget handed a message marks its control
+ * invalid. That was true before #3222 too, under the name `errorMessage`, and
+ * it did not help anyone, because no host ever passed the prop. The PRODUCER
+ * half is `form-error-delivery.test.tsx` in `@object-ui/components` plus
+ * `widget-aria-invalid-e2e.test.tsx` next to this file; a rename alone would
+ * have swapped one dead key for another.
  */
 
 import { describe, it, expect, vi } from 'vitest';
@@ -32,23 +41,23 @@ const noop = vi.fn();
 
 describe('P3.2 Validation Feedback', () => {
   // ---------------------------------------------------------------
-  // aria-invalid on errorMessage
+  // aria-invalid on `error`
   // ---------------------------------------------------------------
   describe('aria-invalid attribute', () => {
-    it('EmailField sets aria-invalid when errorMessage provided', () => {
+    it('EmailField sets aria-invalid when `error` provided', () => {
       render(
         <EmailField
           value=""
           onChange={noop}
           field={{ type: 'email' } as any}
-          errorMessage="Invalid email"
+          error="Invalid email"
         />
       );
       const input = screen.getByRole('textbox');
       expect(input).toHaveAttribute('aria-invalid', 'true');
     });
 
-    it('EmailField does not set aria-invalid without errorMessage', () => {
+    it('EmailField does not set aria-invalid without `error`', () => {
       render(
         <EmailField
           value=""
@@ -60,52 +69,52 @@ describe('P3.2 Validation Feedback', () => {
       expect(input).not.toHaveAttribute('aria-invalid', 'true');
     });
 
-    it('UrlField sets aria-invalid when errorMessage provided', () => {
+    it('UrlField sets aria-invalid when `error` provided', () => {
       render(
         <UrlField
           value=""
           onChange={noop}
           field={{ type: 'url' } as any}
-          errorMessage="Invalid URL"
+          error="Invalid URL"
         />
       );
       const input = screen.getByDisplayValue('');
       expect(input).toHaveAttribute('aria-invalid', 'true');
     });
 
-    it('PhoneField sets aria-invalid when errorMessage provided', () => {
+    it('PhoneField sets aria-invalid when `error` provided', () => {
       render(
         <PhoneField
           value=""
           onChange={noop}
           field={{ type: 'phone' } as any}
-          errorMessage="Invalid phone"
+          error="Invalid phone"
         />
       );
       const input = screen.getByRole('textbox');
       expect(input).toHaveAttribute('aria-invalid', 'true');
     });
 
-    it('TextAreaField sets aria-invalid when errorMessage provided', () => {
+    it('TextAreaField sets aria-invalid when `error` provided', () => {
       render(
         <TextAreaField
           value=""
           onChange={noop}
           field={{ type: 'textarea' } as any}
-          errorMessage="Required"
+          error="Required"
         />
       );
       const textarea = screen.getByRole('textbox');
       expect(textarea).toHaveAttribute('aria-invalid', 'true');
     });
 
-    it('CurrencyField sets aria-invalid when errorMessage provided', () => {
+    it('CurrencyField sets aria-invalid when `error` provided', () => {
       render(
         <CurrencyField
           value={0}
           onChange={noop}
           field={{ type: 'currency' } as any}
-          errorMessage="Must be positive"
+          error="Must be positive"
         />
       );
       const input = screen.getByRole('spinbutton');

package/src/__tests__/widget-aria-invalid-e2e.test.tsx

@@ -0,0 +1,265 @@
+/**
+ * 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.
+ */
+
+/**
+ * End-to-end: a REAL widget, inside the REAL form renderer, announces an
+ * invalid field to assistive tech (objectui#3222).
+ *
+ * The two halves of this contract have unit tests of their own — the widgets
+ * mark themselves invalid when handed an `error`
+ * (`validation-feedback.test.tsx`), and the form renderer produces one
+ * (`form-error-delivery.test.tsx` in `@object-ui/components`). Neither alone
+ * would have caught the actual defect, because the defect was precisely that
+ * the two halves never met: the widgets read `errorMessage`, the spec's
+ * published contract said `error`, and NOTHING in `packages/` or `apps/`
+ * produced either. Seven widgets computed `aria-invalid={!!errorMessage}` from
+ * a value that was `undefined` forever, so `aria-invalid` had never once been
+ * set on a failing field.
+ *
+ * So this file joins them: real react-hook-form validation, real widget, one
+ * assertion per widget that the control is `aria-invalid="true"` after the
+ * failure and `"false"` before it. `aria-invalid="false"` up front is the load
+ * bearing half of each pair — `<FormControl>` is a Radix `Slot` that hands its
+ * child a correct `aria-invalid`, and the widget's own attribute is written
+ * AFTER the props spread, so it wins. A widget computing it from a prop nobody
+ * passes does not merely miss the signal, it OVERWRITES the correct one with
+ * `false`.
+ *
+ * The widgets are registered raw rather than through `registerAllFields()`,
+ * which wraps every loader in `React.lazy`: an unbounded module load inside a
+ * bounded `findBy`/`waitFor` window is the repo's known flake generator
+ * (AGENTS.md 测试纪律, objectui#3010). Same component, no Suspense boundary.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor, cleanup } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { ComponentRegistry } from '@object-ui/core';
+// Module scope: pulls in the form renderer's registration side effect.
+import '@object-ui/components';
+
+import { EmailField } from '../widgets/EmailField';
+import { PhoneField } from '../widgets/PhoneField';
+import { UrlField } from '../widgets/UrlField';
+import { TextAreaField } from '../widgets/TextAreaField';
+import { CurrencyField } from '../widgets/CurrencyField';
+import { PercentField } from '../widgets/PercentField';
+import { RichTextField } from '../widgets/RichTextField';
+import { TextField } from '../widgets/TextField';
+import { SelectField } from '../widgets/SelectField';
+
+/**
+ * The widgets that read the validation slot, by their form-path key: the seven
+ * from objectui#3222, plus `select` (objectui#3306) — the widget whose control
+ * is a Radix trigger rather than a native input, where every aria-* used to be
+ * swallowed by the non-DOM `Select.Root`.
+ */
+const WIDGETS = [
+  ['email', EmailField],
+  ['phone', PhoneField],
+  ['url', UrlField],
+  ['textarea', TextAreaField],
+  ['currency', CurrencyField],
+  ['percent', PercentField],
+  ['markdown', RichTextField],
+  ['select', SelectField],
+] as const;
+
+beforeAll(() => {
+  for (const [type, Widget] of WIDGETS) {
+    ComponentRegistry.register(type, Widget as any, { namespace: 'field', skipFallback: true });
+  }
+}, 30000);
+
+beforeEach(() => {
+  if (!(Element.prototype as any).scrollIntoView) {
+    (Element.prototype as any).scrollIntoView = () => {};
+  }
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function renderForm(field: any, defaultValue: unknown) {
+  const Form = ComponentRegistry.get('form')!;
+  return render(
+    <Form
+      schema={{
+        type: 'form',
+        mode: 'create',
+        showSubmit: true,
+        showCancel: false,
+        submitLabel: 'Create',
+        defaultValues: { [field.name]: defaultValue },
+        fields: [field],
+        onSubmit: () => {},
+      }}
+    />,
+  );
+}
+
+/**
+ * The control the widget rendered, located through the form row rather than by
+ * role — the seven widgets render `input[type=email|tel|url|number]` and
+ * `textarea` between them, and the point of the assertion is the ATTRIBUTE,
+ * not which element type carries it.
+ */
+function controlOf(name: string): Element {
+  const control = document.querySelector(
+    `[data-field="${name}"] input, [data-field="${name}"] textarea`,
+  );
+  if (!control) throw new Error(`no control rendered for field "${name}"`);
+  return control;
+}
+
+const submit = () => fireEvent.click(screen.getByRole('button', { name: /create/i }));
+
+describe('field widgets announce an invalid field to AT (objectui#3222)', () => {
+  // `field:textarea` because the bare `textarea` key is a BUILTIN_FIELD_TYPE in
+  // the form renderer and never reaches the registry — it is the prefixed id
+  // (`mapFieldTypeToFormType`) that resolves to this package's widget.
+  it.each([
+    ['email', 'email', ''],
+    ['phone', 'phone', ''],
+    ['url', 'url', ''],
+    ['field:textarea', 'notes', ''],
+    ['currency', 'amount', null],
+    ['percent', 'ratio', null],
+    ['markdown', 'body', ''],
+  ] as const)(
+    'a required %s field is aria-invalid only AFTER validation fails',
+    async (type, name, emptyValue) => {
+      renderForm({ name, label: name, type, required: true }, emptyValue);
+
+      // Before the submit there is no error, and the widget must say so —
+      // this is the half that a Slot-provided `aria-invalid` cannot fake.
+      expect(controlOf(name)).toHaveAttribute('aria-invalid', 'false');
+
+      submit();
+
+      await waitFor(() => {
+        expect(controlOf(name)).toHaveAttribute('aria-invalid', 'true');
+      });
+    },
+  );
+
+  it('the message itself is rendered once, by the form — not by the widget', async () => {
+    // Responsibility split (the ruling's scope item 3): the widget consumes
+    // `error` for `aria-invalid` ONLY. `<FormMessage/>` owns the text; a widget
+    // that printed it too would show the user the same sentence twice.
+    renderForm({ name: 'email', label: 'Email', type: 'email', required: true }, '');
+
+    submit();
+
+    await waitFor(() => expect(screen.getAllByText('Email is required')).toHaveLength(1));
+    // And the message is NOT inside the control the widget rendered.
+    expect(controlOf('email')).not.toHaveTextContent('Email is required');
+  });
+
+  it('a widget that does NOT read `error` is still marked invalid, by the Slot', async () => {
+    // The counterpart that makes the diagnosis precise: `TextField` never
+    // computed its own `aria-invalid`, so `<FormControl>`'s Slot value reached
+    // its input untouched and it announced invalid fields correctly all along.
+    // Only the seven widgets that DID compute one were broken — they wrote
+    // theirs after the props spread, so `!!undefined` won.
+    //
+    // Pinned because the obvious "cleanup" here is to stop forwarding `error`
+    // to widgets that do not declare a use for it. That cannot be known (a
+    // third-party widget is exactly the case the contract exists for), and
+    // withholding it would recreate declared-≠-delivered one widget at a time.
+    ComponentRegistry.register('plaintext', TextField as any, { namespace: 'field', skipFallback: true });
+    renderForm({ name: 'title', label: 'Title', type: 'plaintext', required: true }, '');
+
+    submit();
+
+    await waitFor(() => expect(controlOf('title')).toHaveAttribute('aria-invalid', 'true'));
+  });
+
+  it('clears the invalid state when the field becomes valid again', async () => {
+    renderForm({ name: 'email', label: 'Email', type: 'email', required: true }, '');
+
+    submit();
+    await waitFor(() => expect(controlOf('email')).toHaveAttribute('aria-invalid', 'true'));
+
+    fireEvent.change(controlOf('email'), { target: { value: 'a@example.com' } });
+
+    await waitFor(() => expect(controlOf('email')).toHaveAttribute('aria-invalid', 'false'));
+  });
+});
+
+describe('field:select announces validation state on its TRIGGER (objectui#3306)', () => {
+  // Radix `Select.Root` renders no DOM element and silently drops every prop
+  // it does not recognise. The widget used to spread its DOM pass-through onto
+  // Root, so `aria-invalid` / `aria-describedby` / `aria-required` all
+  // vanished: a failed required select showed the red message while assistive
+  // tech was told nothing. The real control is the focusable
+  // `<button role="combobox">` the trigger renders — that is where every
+  // assertion below reads from, never a wrapper.
+  //
+  // `field:select` (not bare `select`) because `select` is a
+  // BUILTIN_FIELD_TYPE in the form renderer and never reaches the registry —
+  // same reason as `field:textarea` above.
+  const OPTIONS = [
+    { label: 'Alpha', value: 'alpha' },
+    { label: 'Beta', value: 'beta' },
+  ];
+
+  const selectField = {
+    name: 'choice',
+    label: 'Choice',
+    type: 'field:select',
+    required: true,
+    options: OPTIONS,
+  };
+
+  /** The trigger button, by role — fails loudly if it stops being a combobox. */
+  function trigger(): Element {
+    const el = document.querySelector('[data-field="choice"] [role="combobox"]');
+    if (!el) throw new Error('no select trigger rendered for field "choice"');
+    return el;
+  }
+
+  it('a required select is aria-invalid only AFTER validation fails, on the trigger', async () => {
+    renderForm(selectField, null);
+
+    // The explicit "false" half is load-bearing, same as the widgets above: a
+    // valid field SAYS it is valid rather than staying mute.
+    expect(trigger()).toHaveAttribute('aria-invalid', 'false');
+
+    submit();
+
+    // Prove the failure actually rendered before reading aria off it — an
+    // error variant that silently produces no error tests nothing.
+    await waitFor(() =>
+      expect(screen.getAllByText('Choice is required')).toHaveLength(1),
+    );
+    expect(trigger()).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  it('carries aria-required on the trigger — the state channel of objectui#3290', () => {
+    renderForm(selectField, null);
+
+    // Root would swallow it; the trigger is "the control" for a Radix select.
+    expect(trigger()).toHaveAttribute('aria-required', 'true');
+  });
+
+  it('aria-describedby on the trigger references the rendered error message', async () => {
+    renderForm(selectField, null);
+
+    submit();
+
+    const message = await screen.findByText('Choice is required');
+    // The association is only real if the id chain closes: the trigger must
+    // point at the exact element carrying the message text.
+    expect(message.id).not.toBe('');
+    const describedBy = trigger().getAttribute('aria-describedby') ?? '';
+    expect(describedBy.split(/\s+/)).toContain(message.id);
+  });
+});