feat: add custom document ordering to collections

[stevenle]

Summary

Adds support for custom document ordering in collections via a new customSorting collection schema option. Editors can now drag documents to reorder them or use "Move to top/bottom" actions, with the order persisted as a fractional-index string in sys.sortKey.

Key Changes

• Fractional indexing library (packages/root-cms/shared/sort-key.ts): Vendored implementation from rocicorp/fractional-indexing for generating sort keys that maintain order through insertions without rewriting existing keys.

• CMS UI enhancements:

  • Added "Custom order" sort option to collection pages when customSorting is enabled
  • Implemented drag-and-drop reordering using @hello-pangea/dnd with visual drag handles
  • Added "Assign positions" banner for bulk-initializing sort keys on existing docs (e.g., when enabling custom sorting on a collection with existing docs)
  • Added "Move to top/bottom" actions in the doc actions menu
  • Compact and comfortable list views both support reordering

• Backend integration:

  • cmsSetDocSortKey(): Updates a single doc's sort key across draft/published/scheduled copies
  • cmsAssignSortKeys(): Batch-assigns sort keys with Firestore batch write chunking (500 writes per batch)
  • fetchMaxSortKey(): Queries the current maximum sort key in a collection
  • Sort key updates intentionally skip sys.modifiedAt to avoid marking docs as edited

• Client API (RootCMSClient.listDocs()): Automatically orders results by sys.sortKey when customSorting is enabled and no explicit orderBy is provided.

• Sorting utilities (doc-sort.ts): sortDocsCustomOrder() function that sorts docs by sort key (keyed docs first) with keyless docs at the end (newest first) for visibility.

• Schema updates: Added customSorting?: boolean option to the Collection type and serialized it in the app context.

Implementation Details

• Sort keys are base-62 strings that sort correctly by code point, matching Firestore's string field ordering
• Reordering is non-destructive: moving a doc only writes a new key to that doc, not to neighbors
• Published/scheduled doc copies are updated best-effort; failures don't block the operation
• Keyless docs (created before custom sorting was enabled or via imports) are displayed at the end with a banner offering one-click position assignment
• Comprehensive test coverage for fractional indexing, sort key assignment, and UI rendering

https://claude.ai/code/session_018Xgdd2x1BnTarkWKftet4q

[stevenle]

@jeremydw fable kinda nailed this impl pretty well. i just tested and everything looks pretty good to me. for newly added customSorting: true collections, there's a user-friendly message bar at the top of the collection that indicates the collection needs "sortKey" added to the docs and a button to auto assign those values. (that's the only 1-time setup step)

lmk if any feedback.

[jeremydw]

Wow, that's great. Two comments:

1. I wonder if we should have some tooltip or something that explains what "custom order" does?
2. How does the ordering play with draft/published states? What if you want to reorder something and leave that in draft for review first.

[stevenle]

i don't think a tooltip is necessary, it's opt-in at the moment so devs would need to know it exists and would probably have a pre-existing defined purpose for it, hopefully it's clear enough from that.

re: draft/published, there's a comment about it in the PR desc but basically it currently changes the position in draft mode but doesn't change the modifiedAt time (so the "draft" badge wouldn't appear). i think ai did this to avoid having it show the draft badge, but rethinking this now and it'd probably make sense to show the draft badge as an indication that it requires republishing.