@estiva-app/ui 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/src/CommandPalette.mdx

@@ -90,7 +90,10 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
   send the highlight to the first or last row; the palette stops that.
 - **The field is named by its placeholder**, so say what it asks for.
 - **A form's fields go in `Field`s.** Mark the missing ones with `error` inside
-  `onSubmit`, and the first of them takes focus. `working` locks the fields,
+  `onSubmit`, and the first of them takes focus. The level is the package
+  **Form** (`enterSends={false}`), so work a mark out from what is typed — a
+  field that is filled must stop saying it is missing, or the Form will not
+  send again. `working` locks the fields,
   puts its words on the button and beside it, and holds focus on the form so
   Esc still closes it; when it clears, focus goes to the first field that needs
   something, or back where it was. `error` is what went wrong, beside the
@@ -111,7 +114,8 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
 | | Home / End | move the text cursor; the lit row stays |
 | inside a level | Backspace at the start of the field, or the chip's ✕ | back, with focus in the field |
 | a form | Tab / Shift+Tab | between the fields, never out of the window |
-| | Ctrl+Enter | submits; if a field needs something, focus goes to the first |
+| | Enter in a text field | nothing; Enter in a text area is a new line |
+| | Ctrl+Enter, or the button | submits; if a field needs something, focus goes to the first |
 | | Backspace in an empty text field | back. In a form that is one list, Backspace anywhere; in a list inside a form with text fields, nothing |
 | | while working | nothing but Esc |
 | | Esc in an open list | closes the list first |

package/src/CommandPalette.stories.tsx

@@ -155,7 +155,11 @@ function Demo({ start, where, modKey, label }: { start: Start; where?: string; m
 
   // ── The form keeps what was typed while the palette is open.
   const [draft, setDraft] = useState({ title: '', notes: '', kind: 'one', group: '' })
-  const [missing, setMissing] = useState<{ title?: string; group?: string }>({})
+  // What a field needs is worked out from the draft once a send has been tried, so a field that is
+  // filled stops saying so at once. A mark left standing would keep the Form from ever sending.
+  const [tried, setTried] = useState(false)
+  const need = { title: draft.title.trim() ? undefined : 'Give it a title.', group: draft.group ? undefined : 'Choose a group.' }
+  const missing: { title?: string; group?: string } = tried ? need : {}
   const [working, setWorking] = useState(false)
   const [refused, setRefused] = useState(false)
   const [kind, setKind] = useState('one')
@@ -264,8 +268,7 @@ function Demo({ start, where, modKey, label }: { start: Start; where?: string; m
   }, [frame, level, asked, recent, searching])
 
   const submitForm = async () => {
-    const need = { title: draft.title.trim() ? undefined : 'Give it a title.', group: draft.group ? undefined : 'Choose a group.' }
-    setMissing(need)
+    setTried(true)
     setRefused(false)
     if (need.title || need.group) return
     setWorking(true)

package/src/CommandPalette.test.tsx

@@ -316,6 +316,21 @@ describe('CommandPaletteForm', () => {
     expect(onSubmit).toHaveBeenCalledTimes(1)
   })
 
+  it('sends nothing on a plain Enter in a field; the button sends, through the same Form submit', async () => {
+    const onSubmit = vi.fn()
+    const user = userEvent.setup()
+    render(<Form onSubmit={onSubmit} />)
+    const title = screen.getByRole('textbox', { name: 'Title' }) as HTMLInputElement
+    await waitFor(() => expect(document.activeElement).toBe(title))
+    await user.keyboard('A{Enter}')
+    expect(onSubmit).not.toHaveBeenCalled()
+    expect(title.value).toBe('A')
+    const button = screen.getByRole('button', { name: 'Create item' })
+    expect(button.getAttribute('type')).toBe('submit')
+    await user.click(button)
+    expect(onSubmit).toHaveBeenCalledTimes(1)
+  })
+
   it('puts focus on the first field that needs something', async () => {
     const user = userEvent.setup()
     render(<Form />)

package/src/CommandPalette.tsx

@@ -19,6 +19,7 @@ import { Button } from './Button'
 import { InputChip } from './ChipInput'
 import { EmptyState } from './EmptyState'
 import { FieldLine } from './Field'
+import { Form } from './Form'
 import { Kbd } from './Kbd'
 import { EnterHint, MenuItemBody, menuItemClassName } from './Menu'
 import { ScrollArea } from './ScrollArea'
@@ -484,15 +485,18 @@ export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWa
   const busy = !!working
   const busyRef = useRef(busy)
   busyRef.current = busy
-  const returnTo = useRef<HTMLElement | null>(null)
 
   /** A field that says it needs something: Base UI marks the `Field` itself. */
   const firstInvalid = () => frameRef.current?.querySelector<HTMLElement>('[data-invalid]')?.querySelector<HTMLElement>(CONTROL) ?? null
 
+  /*
+    The form's one way in: its button (type="submit") and Ctrl+Enter both
+    arrive here through the package Form's submit, so Base UI's field check
+    runs for both. The guard stays: a waiting button is focusable while
+    disabled, so it is not the browser that stops it.
+  */
   const submit = () => {
     if (busyRef.current || submitWaits) return
-    const active = document.activeElement
-    returnTo.current = active instanceof HTMLElement && frameRef.current?.contains(active) ? active : null
     onSubmit()
     // If the caller marked fields instead of starting, the first of them
     // takes focus: the key list's "focus goes to the first".
@@ -502,26 +506,12 @@ export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWa
   }
 
   /*
-    The lock must not lose focus.
-
-    Locking disables the fields, and a disabled field drops focus to the page
-    — measured in the prototype, where after Ctrl+Enter no key but Esc ever
-    worked again, even after the error came back. So while the form works,
-    focus sits on the form's own box, where its keys still arrive; when it
-    stops, focus goes to the first field that needs something, or back where
-    it was, or to the first field.
+    The lock must not lose focus — measured in the prototype, where after
+    Ctrl+Enter no key but Esc ever worked again. The package Form does it now
+    (UIG-7): while it works, focus sits on the form, where its keys still
+    arrive; when it stops, focus goes to the first field that needs something,
+    or back where it was, or to the first field.
   */
-  useLayoutEffect(() => {
-    if (busy) {
-      frameRef.current?.focus()
-      return
-    }
-    if (document.activeElement !== frameRef.current) return
-    const was = returnTo.current
-    const target = firstInvalid() ?? (was?.isConnected && !(was as HTMLButtonElement).disabled ? was : null) ?? firstControl(popupRef.current)
-    target?.focus()
-    // Runs when the lock changes, and reads the DOM it leaves behind.
-  }, [busy])
 
   /*
     Backspace goes back only where nothing typed is lost: from an empty text
@@ -541,12 +531,8 @@ export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWa
   const measure = () => setBackNamed(backWorksFrom(document.activeElement))
   useLayoutEffect(measure)
 
+  // Ctrl+Enter is the Form's; plain Enter in a field sends nothing here (`enterSends={false}`).
   const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
-    if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
-      e.preventDefault()
-      submit()
-      return
-    }
     if (e.key === 'Backspace' && !e.ctrlKey && !e.metaKey && !e.altKey && backWorksFrom(e.target as Element)) {
       e.preventDefault()
       back()
@@ -565,27 +551,29 @@ export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWa
         {icon != null && <span className="flex shrink-0 items-center text-text-secondary">{icon}</span>}
         <LevelChip chip={chip} onBack={back} />
       </div>
-      <ScrollArea viewportClassName="max-h-[420px]" contentClassName="flex flex-col px-5 py-4">
-        {/* `contents`: the fieldset only locks; the fields lay out as if it
-            were not there. */}
-        <fieldset data-command-palette-fields="" disabled={busy} className="contents">
+      {/* The package Form, from the fields to the button (UIG-7). The chip row
+          stays outside it, so its ✕ still goes back while the form works; the
+          button row is inside it, so focus that was on the button is held.
+          The fields are found through data-command-palette-fields. */}
+      <Form data-command-palette-fields="" busy={busy} enterSends={false} onSubmit={submit} className="flex min-h-0 flex-col">
+        <ScrollArea viewportClassName="max-h-[420px]" contentClassName="flex flex-col px-5 py-4">
           <div className="flex flex-col gap-4">{children}</div>
-        </fieldset>
-      </ScrollArea>
-      <div className="flex shrink-0 items-center gap-3 px-5 pb-4">
-        <div className="min-w-0 flex-1">
-          {working ? <FieldLine>{working.line}</FieldLine> : error ? <FieldLine tone="error">{error}</FieldLine> : null}
+        </ScrollArea>
+        <div className="flex shrink-0 items-center gap-3 px-5 pb-4">
+          <div className="min-w-0 flex-1">
+            {working ? <FieldLine>{working.line}</FieldLine> : error ? <FieldLine tone="error">{error}</FieldLine> : null}
+          </div>
+          <Button
+            type="submit"
+            variant="primary"
+            disabled={busy}
+            disabledReason={busy ? undefined : submitWaits}
+            leadingIcon={busy ? <IconLoader2 size={16} stroke={1.5} className="animate-spin" /> : undefined}
+          >
+            {working ? working.button : submitLabel}
+          </Button>
         </div>
-        <Button
-          variant="primary"
-          onClick={submit}
-          disabled={busy}
-          disabledReason={busy ? undefined : submitWaits}
-          leadingIcon={busy ? <IconLoader2 size={16} stroke={1.5} className="animate-spin" /> : undefined}
-        >
-          {working ? working.button : submitLabel}
-        </Button>
-      </div>
+      </Form>
       <Footer keys={keys} />
     </div>
   )

package/src/Form.mdx

@@ -36,7 +36,10 @@ import { Button, Field, Form, TextInput } from '@estiva-app/ui'
 ```
 
 - **`onSubmit` takes nothing.** The page's own submit is already prevented;
-  there is no event to stop.
+  there is no event to stop. Every way of sending — Enter, Ctrl+Enter, a
+  submit button — arrives here the same way, after the same field check.
+- **`enterSends={false}`** keeps Enter in a one-line field from sending, where
+  only Ctrl+Enter may: a form inside **CommandPalette**, which uses it.
 - **`busy` switches off every field and button inside**, so they do not
   each need `disabled={busy}`. A button outside the form that sends it —
   a dialog's footer, with `form="<id>"` and the form's `id` — is outside,
@@ -57,10 +60,17 @@ import { Button, Field, Form, TextInput } from '@estiva-app/ui'
 
 ## Keys
 
+The same in every form (Katerina, 16 September).
+
 | Key | Does |
 |---|---|
-| Enter, in a one-line field | Sends the form. |
+| Enter, in a one-line field | Sends the form — with or without a submit button, however many fields. Not with `enterSends={false}`. |
+| Shift+Enter or Alt+Enter, in a one-line field | Nothing — the browser would send the form on its own; the form stops it. |
 | Enter, in a Textarea | A new line; it does not send. |
+| Enter, in a list or a people picker | Picks; it does not send. |
+| Enter, in a field that handles Enter itself | What the field does; the form does not send. |
+| Ctrl+Enter (Cmd+Enter), anywhere inside | Sends the form. |
+| Any of these, while busy | Nothing: a form that is sending does not send again. |
 | Tab, while busy | Nothing inside takes focus. |
 
 ## Props

package/src/Form.test.tsx

@@ -54,6 +54,109 @@ describe('Form', () => {
     expect(onSubmit).toHaveBeenCalledTimes(1)
   })
 
+  describe('the keys, the same in every form', () => {
+    function Keys({ onSubmit, enterSends }: { onSubmit: () => void; enterSends?: boolean }) {
+      return (
+        <Form onSubmit={onSubmit} enterSends={enterSends} aria-label="Probe">
+          <Field label="One">
+            <TextInput />
+          </Field>
+          <Field label="Two">
+            <TextInput />
+          </Field>
+          <Field label="Words">
+            <Textarea />
+          </Field>
+          <input role="combobox" aria-label="Pick" aria-expanded="false" aria-controls="none" />
+        </Form>
+      )
+    }
+
+    it('Enter in a one-line field sends, even with two fields and no submit button', async () => {
+      const user = userEvent.setup()
+      const onSubmit = vi.fn()
+      render(<Keys onSubmit={onSubmit} />)
+      await user.type(screen.getByRole('textbox', { name: 'Two' }), 'x{Enter}')
+      expect(onSubmit).toHaveBeenCalledTimes(1)
+    })
+
+    it('Enter in a text area is a new line; Ctrl+Enter and Cmd+Enter there send', async () => {
+      const user = userEvent.setup()
+      const onSubmit = vi.fn()
+      render(<Keys onSubmit={onSubmit} />)
+      const words = screen.getByRole('textbox', { name: 'Words' }) as HTMLTextAreaElement
+      await user.type(words, 'a{Enter}b')
+      expect(words.value).toBe('a\nb')
+      expect(onSubmit).not.toHaveBeenCalled()
+      await user.keyboard('{Control>}{Enter}{/Control}')
+      expect(onSubmit).toHaveBeenCalledTimes(1)
+      await user.keyboard('{Meta>}{Enter}{/Meta}')
+      expect(onSubmit).toHaveBeenCalledTimes(2)
+    })
+
+    it("Enter in a picker's input does not send", async () => {
+      const user = userEvent.setup()
+      const onSubmit = vi.fn()
+      render(<Keys onSubmit={onSubmit} />)
+      await user.type(screen.getByRole('combobox', { name: 'Pick' }), 'x{Enter}')
+      expect(onSubmit).not.toHaveBeenCalled()
+    })
+
+    it('a field that handles its own Enter keeps it', async () => {
+      const user = userEvent.setup()
+      const onSubmit = vi.fn()
+      render(
+        <Form onSubmit={onSubmit} aria-label="Probe">
+          <TextInput aria-label="Own" onKeyDown={(event) => event.key === 'Enter' && event.preventDefault()} />
+        </Form>,
+      )
+      await user.type(screen.getByRole('textbox', { name: 'Own' }), 'x{Enter}')
+      expect(onSubmit).not.toHaveBeenCalled()
+    })
+
+    it('with enterSends off, Enter in a one-line field does nothing and Ctrl+Enter sends', async () => {
+      const user = userEvent.setup()
+      const onSubmit = vi.fn()
+      render(<Keys onSubmit={onSubmit} enterSends={false} />)
+      const one = screen.getByRole('textbox', { name: 'One' }) as HTMLInputElement
+      await user.type(one, 'x{Enter}')
+      expect(onSubmit).not.toHaveBeenCalled()
+      expect(one.value).toBe('x')
+      await user.keyboard('{Control>}{Enter}{/Control}')
+      expect(onSubmit).toHaveBeenCalledTimes(1)
+    })
+
+    it('Shift+Enter and Alt+Enter in a one-line field send nothing, even with a submit button', async () => {
+      const onSubmit = vi.fn()
+      render(<Harness onSubmit={onSubmit} />)
+      const field = screen.getByRole('textbox', { name: 'First' })
+      // The browser's implicit submission is the default action of this keydown: prevented, it does not happen.
+      for (const modifier of [{ shiftKey: true }, { altKey: true }]) {
+        expect(fireEvent.keyDown(field, { key: 'Enter', ...modifier })).toBe(false)
+      }
+      expect(onSubmit).not.toHaveBeenCalled()
+    })
+
+    it('Enter with a submit button in the form sends once, not twice', async () => {
+      const user = userEvent.setup()
+      const onSubmit = vi.fn()
+      render(<Harness onSubmit={onSubmit} />)
+      await user.type(screen.getByRole('textbox', { name: 'First' }), 'x{Enter}')
+      expect(onSubmit).toHaveBeenCalledTimes(1)
+    })
+
+    it('does not send again while busy', async () => {
+      const onSubmit = vi.fn()
+      const { rerender } = render(<Harness onSubmit={onSubmit} />)
+      act(() => screen.getByRole('textbox', { name: 'First' }).focus())
+      rerender(<Harness onSubmit={onSubmit} busy />)
+      const form = screen.getByRole('form', { name: 'Probe' })
+      fireEvent.keyDown(form, { key: 'Enter', ctrlKey: true })
+      fireEvent.submit(form)
+      expect(onSubmit).not.toHaveBeenCalled()
+    })
+  })
+
   it('does not send while a field shows its error', async () => {
     const user = userEvent.setup()
     const onSubmit = vi.fn()

package/src/Form.tsx

@@ -1,4 +1,4 @@
-import { useLayoutEffect, useRef, type FormHTMLAttributes, type ReactNode } from 'react'
+import { useLayoutEffect, useRef, type FormHTMLAttributes, type KeyboardEvent, type ReactNode } from 'react'
 import { Fieldset } from '@base-ui/react/fieldset'
 import { Form as BaseForm } from '@base-ui/react/form'
 import { cn } from './cn'
@@ -27,26 +27,57 @@ import { FormBusyContext, useFormBusy } from './formBusy'
  * When `busy` ends, focus goes to the first invalid field, else to what sent
  * the form, else to the first control. That is `CommandPalette`'s order
  * too, so the two read the same (UIG-29).
+ *
+ * The keys are ours, the same in every form (Katerina, 16 September): Enter in
+ * a one-line field sends; Enter in a text area is a new line; Enter in a list
+ * or a people picker picks; Ctrl+Enter (Cmd+Enter) sends from anywhere inside.
+ * The form sends on Enter itself rather than leaving it to the browser, whose
+ * implicit submission depends on whether the form has a submit button and how
+ * many fields it holds. `enterSends={false}` keeps Enter in a one-line field
+ * from sending, for a form where only Ctrl+Enter may send (`CommandPalette`).
+ * Every way of sending goes through the form's submit, so Base UI's field
+ * check runs for each.
  */
 export interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, 'onSubmit' | 'children' | 'noValidate'> {
   /** Enter in a field, or a submit button. The page's own submit is already prevented. */
   onSubmit: () => void | Promise<void>
   /** While sending: every field and button inside is switched off, and focus waits on the form. */
   busy?: boolean
+  /**
+   * Whether Enter in a one-line field sends. On by default. Off where only
+   * Ctrl+Enter may send — a form inside `CommandPalette`. Ctrl+Enter sends either way.
+   */
+  enterSends?: boolean
   children: ReactNode
 }
 
 const CONTROL = 'input:not([type="hidden"]), textarea, select, button, [role="checkbox"], [role="combobox"], [tabindex]:not([tabindex="-1"])'
 
+/** The inputs a person types one line into; a picker's input (`role="combobox"`) is not one. */
+const ONE_LINE = new Set(['', 'text', 'search', 'email', 'url', 'tel', 'password', 'number'])
+
 function usable(element: Element | null): element is HTMLElement {
   return element instanceof HTMLElement && element.isConnected && element.matches(CONTROL) && !element.matches(':disabled') && element.getAttribute('aria-disabled') !== 'true'
 }
 
-export function Form({ onSubmit, busy: ownBusy = false, className, children, ...props }: FormProps) {
+/** A marked field's own control: Base UI marks the control and the `Field` around it. */
+function firstInvalid(form: HTMLElement): HTMLElement | undefined {
+  for (const marked of form.querySelectorAll('[data-invalid]')) {
+    if (usable(marked)) return marked
+    const inside = Array.from(marked.querySelectorAll(CONTROL)).find(usable)
+    if (inside) return inside
+  }
+  return undefined
+}
+
+export function Form({ onSubmit, busy: ownBusy = false, enterSends = true, className, children, ...props }: FormProps) {
   // A form inside a busy form is busy too.
   const outerBusy = useFormBusy()
   const busy = ownBusy || outerBusy
   const form = useRef<HTMLFormElement>(null)
+  // Read at submit time: a form that is sending does not send again (Ctrl+Enter reaches it while busy).
+  const busyNow = useRef(busy)
+  busyNow.current = busy
   // What had focus when the form went busy, and whether the form took focus from it.
   const sender = useRef<Element | null>(null)
   const holding = useRef(false)
@@ -77,12 +108,39 @@ export function Form({ onSubmit, busy: ownBusy = false, className, children, ...
     holding.current = false
     // Someone who moved focus on while waiting keeps it where they put it.
     if (document.activeElement !== element && document.activeElement !== document.body) return
-    const invalid = Array.from(element.querySelectorAll('[data-invalid]')).find(usable)
-    const target = invalid ?? (usable(sender.current) ? sender.current : Array.from(element.querySelectorAll(CONTROL)).find(usable))
+    const target = firstInvalid(element) ?? (usable(sender.current) ? sender.current : Array.from(element.querySelectorAll(CONTROL)).find(usable))
     sender.current = null
     target?.focus()
   }, [busy])
 
+  /*
+    Bubble phase, after the field's own handler: a picker picks on Enter and
+    says so by preventing it, and a field that handles Enter itself does too.
+  */
+  const onKeyDown = (event: KeyboardEvent<HTMLFormElement>) => {
+    props.onKeyDown?.(event)
+    if (event.key !== 'Enter' || event.defaultPrevented || event.nativeEvent.isComposing) return
+    const target = event.target
+    const inInput = target instanceof HTMLInputElement
+    /*
+      In an input the browser sends a form on its own — on Enter with Shift or
+      Alt too (measured in Chrome: Shift+Enter sent Peek's comment box, 16
+      September) — so the form stops that every time and sends only by these
+      rules. A text area's Enter is a new line and a button's Enter presses it:
+      those are left to the browser.
+    */
+    if (inInput) event.preventDefault()
+    if (event.altKey || event.shiftKey) return
+    if (event.ctrlKey || event.metaKey) {
+      event.preventDefault()
+      form.current?.requestSubmit()
+      return
+    }
+    if (!inInput) return
+    const oneLine = ONE_LINE.has((target.getAttribute('type') ?? '').toLowerCase()) && target.getAttribute('role') !== 'combobox'
+    if (enterSends && oneLine) form.current?.requestSubmit()
+  }
+
   return (
     <BaseForm
       ref={form}
@@ -100,8 +158,10 @@ export function Form({ onSubmit, busy: ownBusy = false, className, children, ...
         if (next && !form.current?.contains(next)) lastInside.current = null
         props.onBlur?.(event)
       }}
+      onKeyDown={onKeyDown}
       onSubmit={(event) => {
         event.preventDefault()
+        if (busyNow.current) return
         void onSubmit()
       }}
     >