Home: bring the Documents list to parity with Settings → Documents

[HMarzban]

Summary

Home shows a short Documents card for a signed-in person. Settings → Documents shows the Merged list with many more features. This issue brings the Home card to parity with Settings → Documents by reusing the Settings code, not by building a second list.

The maintainer's request, quoted exactly:

"let's update the list of document that we show up in the pwa version in the landing page like what we did in the document setting pannel"

Screenshots of both surfaces will be added by the maintainer.

This issue overturns earlier rulings. #247 and apps/webapp/CLAUDE.md §Documents list Favorites say Home reads the Owner live list only (scope: 'owned'). #247 also says Home has no sort, no search, no row menu, no grid and no Date buckets. The request above reverses those rules. The Open decisions section asks which of them change.

Why

• A person who joined a pad cannot find it from Home today. Home lists only pads they own.
• The same document shows different marks on Home and in Settings. Home has no avatars, no owner name and no ⋮ menu.
• A person must open Settings to rename, favorite or copy the link of a pad they see on Home.
• One list implementation is cheaper to keep correct than two.

Current behaviour

Home card: apps/webapp/src/components/pages/home/HomeDocuments.tsx, mounted in HomePage.tsx inside HomeCollapseRegion.

• It calls useOwnerDocuments({ scope: 'owned', searchQuery: '', sortKey: 'lastOpenedAt_desc' }) with refetchOnWindowFocus: 'always'.
• It shows the first 8 rows of the first page (HOME_DOCUMENTS_LIMIT). The page size is 20 (DOCUMENTS_PAGE_SIZE). Both read from code, not measured.
• Each row is a button: LuFileText, DocumentRowLabel (title, star, lock, eye) and documentListDate. That date reads "Never opened" when lastOpenedAt is null.
• "See all" shows only when total > 8. It opens Settings on the Documents tab.
• The card hides while loading, on error and when the list is empty.
• The gate is sign-in and isAuthServiceAvailable only. It is not gated on isPWAInstalled. So the same card shows in a browser tab and in the installed app. The rule "Do not gate that list on isPWAInstalled" must stay.
• Command jump (components/commandJump/CommandJump.tsx) uses the same query key (owned, empty search, lastOpenedAt_desc). It fetches only while its dialog is open.

Settings list: apps/webapp/src/components/settings/components/DocumentsSection.tsx, loaded with next/dynamic from SettingsPanel.tsx.

• Rows: DocumentListRow, DocumentGridTile, DocumentRowMenu, DocumentMembersCluster, DocumentRowLabel.
• List items: buildDocumentsListItems (Favorites hairline and Date buckets).
• Data: useOwnerDocuments, useDocumentMembers (RPC get_document_member_previews), useOwnerDocumentsCache for every optimistic write.
• Session picks: docsplus:my-docs-scope, docsplus:my-docs-sort, docsplus:my-docs-view.

Feature	Home today	Settings → Documents
Data scope	Owner live list (owned)	Merged list (all) by default; Show filter all / owned / joined
Joined rows	Never	Yes, with the owner's name
Sort	Fixed Last opened	Last modified (default), Last opened, Date created, Name A→Z, Name Z→A
Search	No	Yes, debounced 350 ms (read from code, not measured)
List / grid	List only	Both
Favorites pinned, star	Pinned, star shown	Pinned, star, hairline after the block
Date buckets	No	Yes, on date sorts
Collaborator avatars	No	DocumentMembersCluster, up to 4 faces
⋮ menu	No	Open in new tab, Copy link, Rename, Duplicate, Favorite, Private, Read-only, Delete
Rename (F2)	No	Inline in list; dialog in grid
Delete with Undo	No	Inline Undo banner, 6 s (read from code, not measured)
Trash entry	No	Yes
Empty states	Card hidden	"No documents yet." with Create; Joined has its own text
Row cap	8, then See all	Pages of 20 with Load more

Backend. No new route is needed. GET /documents?scope=all already returns the Merged list (buildMemberScopeTiers in apps/hocuspocus.server/src/api/services/documents.service.ts). It pins only the caller's own Favorites, and it sorts a non-owned row as never opened.

Bug found during research (Owner live list pin order). buildDocumentsOrderBy pins with favorites: { _count: 'desc' }. That counts the Favorite rows of every user, not only the caller's. isFavorite counts only the caller's row. So a row can pin above others with no star, and a row with two Favorite rows outranks a row with one. The Home screenshot shows this: an unstarred row sits between two starred rows. The Merged list tiers use favorites: { some: mine } and are correct. This bug also reaches Settings "Owned by me" and Command jump.

Proposed behaviour

1. A signed-in person opens /, in a tab or in the installed app. The Documents card shows the Merged list by default: owned rows plus Joined rows.
2. Rows look and act like Settings list rows. A Joined row names its owner. A shared pad shows its avatar cluster. Favorites pin first with a star and a hairline.
3. The ⋮ menu offers the same actions as in Settings for the same row, following ownership. A Joined row offers only Open in new tab and Copy link.
4. A write from Home (rename, favorite, private, delete) updates every documents list, because useOwnerDocumentsCache already patches every key under ['documents', uid].
5. "See all" opens Settings → Documents. Settings shows the same scope and sort as Home.
6. A signed-out visitor sees no card and no documents request.
7. On a phone, the card still collapses when the keyboard opens, like the footer.

Scope

• Slice 1, backend. Pin only the caller's Favorites on the Owner live list. Use the favorites: { some: { userId } } rule that the Merged list tiers already use. Deploy before slice 2.
• Slice 2, data. Home reads the Merged list. Home and Settings read the same scope and sort session keys, so they share one query key.
• Slice 3, rows. Home renders DocumentListRow and buildDocumentsListItems, with useDocumentMembers for the visible rows. Load them on the client after the profile arrives, so signed-out / loads no extra JS.
• Slice 4, controls. Add the controls the maintainer picks below. Reuse the Settings Select, labels and session keys.
• Slice 5, delete and rename. Lift the delete-and-Undo flow out of DocumentsSection so Home and Settings share it. Pick the rename path that survives keyboard collapse on a phone.

Out of scope

• Command jump scope. It stays "places and owned pads" (CONTEXT.md §Pad tools).
• Trash on Home.
• A visit table or visit-ordered Recents (Do not add visit-based Recents #260). Joined lists memberships, not visits.
• Folders (Do not add folders #259).
• New design tokens, sizes or species. Build from .cursor/docs/design-system.md §DocumentsSection and §Landing & history as written.
• Gating the card on isPWAInstalled.
• Caching the list in Cache Storage, the service worker, or Home GSSP.

Open decisions

Each item needs a maintainer ruling. The recommendation is mine, with the reason.

1. Default scope. Recommend the Merged list (all). That is the request, and it matches Settings.
2. Show filter on Home. Recommend yes, a compact Select that shares docsplus:my-docs-scope. Then Home and Settings never disagree.
3. Sort control and default. Recommend a sort Select that shares docsplus:my-docs-sort, default Last modified. Under Last opened, every Joined row sorts as never opened, so an 8-row card can hide every Joined row. This reverses Honest install line, Documents on Home, and a quiet Home Install #247, which chose Last opened.
4. Search on Home. Recommend no. The slug card is already a text field. On a phone, focus raises the keyboard, and HomeCollapseRegion then collapses the card that holds the search field. Command jump already searches owned pads.
5. Grid view. Recommend no. The card is max-w-2xl, and 8 rows of paper previews make Home very tall. See all gives the grid.
6. Avatars. Recommend yes. One batched RPC for the visible rows, and a solo pad shows nothing.
7. ⋮ menu. Recommend yes, the same DocumentRowMenu. Its phone sheet already falls back to <body> when no dialog wraps it. Home already mounts GlobalDialog for the confirms.
8. Rename on a phone. Inline rename raises the keyboard, and the card collapses under the input. Recommend RenameDocumentDialog on Home below sm, and inline rename on desktop.
9. Delete on Home. Recommend yes, with the same inline Undo banner inside the Home card, lifted into shared code. The alternative is to leave Delete out of the Home menu.
10. Date buckets. Recommend yes, through buildDocumentsListItems, so both lists use one builder. The cost is header rows inside an 8-row card.
11. Row cap and See all. Recommend keep 8 rows and See all, with no Load more. See all shows when total > 8.
12. Empty states. Recommend: hide the card only when the Merged list is empty. When the Show filter narrows to zero rows, show the Settings empty text inside the card, so the filter stays reachable.
13. Honest install line, Documents on Home, and a quiet Home Install #247 status. Recommend updating Honest install line, Documents on Home, and a quiet Home Install #247's acceptance list to point here, or closing that part of it once this ships.

Acceptance criteria

• Signed-in owner: Home lists owned rows and Joined rows in one order. Each row matches Settings for the same scope and sort.
• Owner Favorites pin first with a star. No row pins without a star (slice 1).
• A Joined row names its owner. It has no star. Its ⋮ shows only Open in new tab and Copy link. F2 does nothing on it.
• A person with Joined rows only and no owned pads sees those rows. A person with no rows sees no card.
• A private or deleted pad the caller does not own never appears.
• Visitor or signed-out: no card, and no request to /documents or get_document_member_previews.
• Auth unavailable or fetch error: the card hides with no toast, and the slug card still works.
• The card shows in a browser tab and in the installed app. It is not gated on isPWAInstalled.
• A rename, Favorite, Private or Delete from Home also shows in Settings → Documents without a reload, and the reverse.
• See all opens Settings → Documents with the same scope and sort as Home.
• Each control the maintainer approves works on Home. Each control he rejects is absent.
• Phone: the card collapses when the keyboard opens. No input the person is typing in collapses with it.
• Phone: the ⋮ menu opens the documentRowMenu sheet. Back and Escape close it. Every target is at least 44 px.
• Light and dark, in every theme, the card uses only the tokens and recipes in design-system.md.
• Performance: Home and Settings with the same scope and sort share one query key, so See all does not refetch the documents page inside staleTime.
• Performance: Home makes one /documents request and at most one members request per visit.
• Performance: the JS that a signed-out visitor loads on / does not grow. Compare the next build route table before and after.

Verification

1. Run make dev-local. Confirm the webapp port first, because it is not always 3000.
2. Sign in as an owner who has a Favorite, a private pad, and a pad shared with a second account. Check Home against Settings → Documents for each scope and sort.
3. Sign in as a second account that has only joined pads. Check the Joined rows and their owner names.
4. Sign out. Check the network panel for no documents request.
5. Check light and dark.
6. Check the installed app and a browser tab.
7. Check the phone shell with a mobile user agent on iOS Safari and Android Chrome. The mobile shell is user-agent gated, so a narrow window alone does not produce it.
8. Never run next build while the dev server uses the same .next directory. Stop the server first for the bundle check.

References

• apps/webapp/src/components/pages/home/HomeDocuments.tsx, HomePage.tsx, HomeCollapseRegion.tsx
• apps/webapp/src/components/settings/components/DocumentsSection.tsx, DocumentListRow.tsx, DocumentRowMenu.tsx, DocumentMembersCluster.tsx, DocumentRowLabel.tsx
• apps/webapp/src/components/settings/hooks/useOwnerDocuments.ts, documentsCache.ts, useDocumentMembers.ts
• apps/webapp/src/components/settings/utils/documentsListItems.ts, documentListDate.ts, documentsQueryKey.ts
• apps/webapp/src/components/commandJump/CommandJump.tsx
• apps/hocuspocus.server/src/api/services/documents.service.ts (buildDocumentsOrderBy, buildMemberScopeTiers)
• apps/hocuspocus.server/src/api/controllers/documents.controller.ts (list scope)
• CONTEXT.md §Documents list, §Document access, §Pad tools
• apps/webapp/CLAUDE.md §Documents list Favorites, §Landing Page Shell And PWA, §Settings Takeover And The Owner List Cache
• .cursor/docs/design-system.md §DocumentsSection, §Landing & history
• Related: Honest install line, Documents on Home, and a quiet Home Install #247 (Documents on Home, rulings this overturns), Deepen the installed PWA #249 (PWA epic), Command jump to a place or an owned pad #254 (Command jump), Do not add visit-based Recents #260 (no visit-based Recents), Do not add folders #259 (no folders), Run the PWA device checklist and close each #249 child that passes #355 (PWA device checklist), Documents list later UX pass #221 (Settings list UX pass, closed)

[HMarzban]

Maintainer ruling, 2026-10-05

The maintainer approved recommended variant (a) from a local visual preview. The preview is not linked, because it stays local. Each item takes the recommendation in Open decisions.

• 390-scope (decision 1) → the Merged list (all). → This overturns Honest install line, Documents on Home, and a quiet Home Install #247 and the apps/webapp/CLAUDE.md rule that Home reads the Owner live list only. The maintainer ruled this.
• 390-show-filter (decision 2) → yes, a compact Select that shares docsplus:my-docs-scope. → Home and Settings never disagree on scope.
• 390-sort (decision 3) → yes, a shared sort Select, default Last modified. → An 8-row card no longer hides every Joined row.
• 390-search (decision 4) → no. → Command jump stays the search for owned pads.
• 390-grid (decision 5) → no. → See all gives the grid.
• 390-avatars (decision 6) → yes, one batched request for the visible rows. → A solo pad shows no faces.
• 390-menu (decision 7) → yes, the same DocumentRowMenu. → Actions follow ownership, as in Settings.
• 390-phone-rename (decision 8) → RenameDocumentDialog below sm, inline rename on desktop. → The input never collapses with the card.
• 390-delete (decision 9) → yes, with the shared inline Undo banner. → Slice 5 lifts that flow out of DocumentsSection.
• 390-date-buckets (decision 10) → yes, through buildDocumentsListItems. → Both lists use one builder.
• 390-row-cap (decision 11) → 8 rows and See all, with no Load more. → See all shows when total > 8.
• 390-empty (decision 12) → hide the card only when the Merged list is empty. → When the Show filter gives zero rows, the card shows the Settings empty text.
• 390-247-status (decision 13, housekeeping) → not ruled. → It stays open. Honest install line, Documents on Home, and a quiet Home Install #247 does not change.

Design-system notes from the preview

• The empty state's "Create document" stays a quiet action. It is not a second primary button on Home (house rule P4).
• The card title keeps its shipped size.

Acceptance changes

• Replace "Each control the maintainer approves works on Home" with: Home shows the Show Select and the sort Select. Home shows no search field and no grid toggle.
• The sort default is Last modified. Home and Settings share the scope and sort session keys.
• Delete from Home shows the shared inline Undo banner inside the card.
• Below sm, Rename opens RenameDocumentDialog. On desktop, Rename is inline.
• When the Show filter gives zero rows, the card stays and shows the Settings empty text. The filter stays reachable.
• "Create document" in an empty state is not btn-primary.
• Every other criterion stays as written.

Next

1. Ship slice 1, the backend pin fix, first. Then slices 2 to 5.
2. In the same change, update apps/webapp/CLAUDE.md and CONTEXT.md where they state the old Home rule. Today that is the HomeDocuments bullet in apps/webapp/CLAUDE.md and the Owner live list entry in CONTEXT.md §Documents list. Command jump keeps scope: 'owned'.
3. Leave 390-247-status open until the maintainer rules on it.