@estiva-app/ui 0.16.0 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "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

@@ -76,10 +76,16 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
 - **`pending` while rows are still on their way; `empty` only once none are.**
   Pass `empty` while a search is running and the page says "nothing" before it
   knows.
-- **Rows that arrive late do not take the highlight.** Base UI keeps the
-  highlight's position rather than its row, so a group arriving above the lit
-  row would hand the highlight — and Enter — to something else. The palette
-  walks it back to the row you had. Typing starts again from the first row.
+- **`notes` are what a person should know about the rows and cannot act on** —
+  "2 more where you cannot open them", "the search was refused, so this list
+  is incomplete". Quiet lines under the rows, never rows: the arrows do not stop
+  on them.
+- **Rows that arrive late do not take the highlight you moved to.** Base UI keeps
+  the highlight's position rather than its row, so a group arriving above the
+  lit row would hand the highlight — and Enter — to something else. Once you have
+  moved the highlight on a level, the palette walks it back to the row you had.
+  Until you have, the first row is lit, whichever row that becomes. Typing starts
+  again from the first row.
 - **Home and End move the text cursor, and nothing else.** Base UI would also
   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.
@@ -117,7 +123,7 @@ import { CommandPalette, CommandPaletteSearch } from '@estiva-app/ui'
 
 **`CommandPaletteSearch`** — `query` and `onQueryChange` (the field, controlled),
 `placeholder` (also the field's name), `groups` (`{ label, rows }`, a group
-with no rows is not drawn), `chip?` (`{ label, leading?, onBack }`), `pending?`,
+with no rows is not drawn), `chip?` (`{ label, leading?, onBack }`), `pending?`, `notes?`,
 `empty?`, and `children` for what sits above the rows.
 
 **A row** — `id`, `label`, `description?`, `icon?` or `leading?`, `onSelect`,

package/src/CommandPalette.stories.tsx

@@ -365,6 +365,8 @@ function Demo({ start, where, modKey, label }: { start: Start; where?: string; m
                     : undefined
             }
             pending={level.kind === 'first' && searching ? 'Searching…' : undefined}
+            // What the later group left out: a line to read, not a row to pick.
+            notes={level.kind === 'first' && q && !searching && LATER.some((l) => l.toLowerCase().includes(q)) ? ['1 more in a place you cannot open.'] : undefined}
             empty={
               level.kind === 'first' && q && !searching
                 ? `Nothing is called “${q}”.`
@@ -388,7 +390,7 @@ const story = (start: Start): Story => ({
 /** The first level: rows in groups, the first one lit. ↑ ↓ stop at the ends, Tab goes into a place, Ctrl+Backspace forgets a recent row. */
 export const FirstLevel: Story = story('first')
 
-/** Typing: the rows that match now, a line while a later group is on its way, and that group arriving without moving the lit row. */
+/** Typing: the rows that match now, a line while a later group is on its way, that group arriving without moving the lit row, and a note about what it left out. */
 export const WhileRowsArrive: Story = story('arriving')
 
 /** Nothing matches: the empty line, where the first row would be. */

package/src/CommandPalette.test.tsx

@@ -39,6 +39,7 @@ function Search({
   onOpenChange = () => {},
   modKey,
   pending,
+  notes,
   empty,
 }: {
   groups: CommandPaletteGroup[]
@@ -47,12 +48,13 @@ function Search({
   onOpenChange?: (open: boolean) => void
   modKey?: string
   pending?: string
+  notes?: string[]
   empty?: string
 }) {
   const [query, setQuery] = useState(initialQuery)
   return (
     <CommandPalette open onOpenChange={onOpenChange} label="Palette" where="In Item one" modKey={modKey}>
-      <CommandPaletteSearch query={query} onQueryChange={setQuery} placeholder="Search" groups={groups} chip={chip} pending={pending} empty={empty} />
+      <CommandPaletteSearch query={query} onQueryChange={setQuery} placeholder="Search" groups={groups} chip={chip} pending={pending} notes={notes} empty={empty} />
     </CommandPalette>
   )
 }
@@ -201,6 +203,17 @@ describe('CommandPaletteSearch — rows', () => {
     await waitFor(() => expect(lit()).toBe('Two'))
   })
 
+  it('lets rows arriving above take the first place while the highlight has not been moved', async () => {
+    const early: CommandPaletteGroup = { label: 'Early', rows: [row('One'), row('Two')] }
+    const late: CommandPaletteGroup = { label: 'Late', rows: [row('Late one')] }
+    const { rerender } = render(<Search groups={[early]} />)
+    await focusedField()
+    await waitFor(() => expect(lit()).toBe('One'))
+    rerender(<Search groups={[late, early]} />)
+    await waitFor(() => expect(screen.getAllByRole('option')).toHaveLength(3))
+    await waitFor(() => expect(lit()).toBe('Late one'))
+  })
+
   it('names in the footer only the keys that work on the lit row', async () => {
     const user = userEvent.setup()
     render(
@@ -232,6 +245,16 @@ describe('CommandPaletteSearch — rows', () => {
     expect(await screen.findByText('Nothing here yet.')).toBeTruthy()
   })
 
+  it('draws notes as lines under the rows, which the arrows do not stop on', async () => {
+    const user = userEvent.setup()
+    render(<Search groups={[{ label: 'Group', rows: [row('One'), row('Two')] }]} notes={['2 more you cannot open.']} />)
+    await focusedField()
+    expect(await screen.findByText('2 more you cannot open.')).toBeTruthy()
+    expect(screen.getAllByRole('option')).toHaveLength(2)
+    await user.keyboard('{ArrowDown}{ArrowDown}{ArrowDown}')
+    expect(lit()).toBe('Two')
+  })
+
   it('says rows are on their way', async () => {
     render(<Search groups={[{ label: 'Group', rows: [row('One')] }]} pending="Searching…" />)
     expect(await screen.findByText('Searching…')).toBeTruthy()

package/src/CommandPalette.tsx

@@ -221,6 +221,13 @@ export interface CommandPaletteSearchProps {
   chip?: CommandPaletteChip
   /** A line under the rows while more are on their way — "Searching…". */
   pending?: string
+  /**
+   * Quiet lines under the rows, for what a person should know about them and
+   * cannot act on — "2 more where you cannot open them", "the search was
+   * refused, so this list is incomplete". Plain lines, never rows: the arrows
+   * do not stop on them.
+   */
+  notes?: string[]
   /** The line when there are no rows. Leave it out while rows are still on their way. */
   empty?: string
   /** Above the rows: a `CommandPaletteWorking`, `CommandPaletteAnswer` or `CommandPaletteQuote`. */
@@ -229,7 +236,7 @@ export interface CommandPaletteSearchProps {
 
 type ListGroup = { value: string; items: CommandPaletteRow[] }
 
-export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups, chip, pending, empty, children }: CommandPaletteSearchProps) {
+export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups, chip, pending, notes = [], empty, children }: CommandPaletteSearchProps) {
   const { modKey, popupRef } = usePalette('CommandPaletteSearch')
   const back = useBack(chip, popupRef)
   const items = useMemo<ListGroup[]>(() => groups.filter((g) => g.rows.length > 0).map((g) => ({ value: g.label, items: g.rows })), [groups])
@@ -254,14 +261,22 @@ export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups
     arrow keys, exactly as a person would. It does so only when Base UI moved
     the highlight by itself ("none") — never after an arrow, the pointer, or
     typing, which starts again from the first row.
+
+    And only once the person has moved the highlight on this level. Until then
+    the lit row is simply the first one, and a row that arrives above it — a
+    thread's own rows, a moment after opening — becomes the first one.
   */
   const inputRef = useRef<HTMLInputElement>(null)
   const reported = useRef<{ id?: string; reason?: string }>({})
   const settled = useRef<{ id?: string; query: string; level?: string } | null>(null)
+  /** The person has moved the highlight since the text or the level last changed. */
+  const moved = useRef(false)
   useLayoutEffect(() => {
     const before = settled.current
     const now = reported.current
-    if (before?.id && now.reason === 'none' && now.id !== before.id && before.query === query && before.level === chip?.label) {
+    const sameLevel = before?.query === query && before?.level === chip?.label
+    if (!sameLevel) moved.current = false
+    if (moved.current && before?.id && now.reason === 'none' && now.id !== before.id && sameLevel) {
       const ids = rows.map((r) => r.id)
       const want = ids.indexOf(before.id)
       const at = now.id === undefined ? -1 : ids.indexOf(now.id)
@@ -347,6 +362,7 @@ export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups
       onItemHighlighted={(row, details) => {
         const id = (row as CommandPaletteRow | undefined)?.id
         reported.current = { id, reason: details.reason }
+        if (details.reason !== 'none') moved.current = true
         setLitId(id)
       }}
     >
@@ -410,6 +426,11 @@ export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups
             </>
           )}
         </Autocomplete.Status>
+        {notes.map((note) => (
+          <div key={note} className="flex min-h-8 items-center px-3">
+            <FieldLine>{note}</FieldLine>
+          </div>
+        ))}
         <Autocomplete.Empty className="flex items-center px-3 [&:not(:empty)]:min-h-10">
           {empty && <EmptyState scope="section" message={empty} />}
         </Autocomplete.Empty>