New and use

web/apps/photos/src/components/Collections/CollectionHeader.tsx

@@ -29,7 +29,7 @@ import {
     isArchivedCollection,
     isPinnedCollection,
 } from "ente-gallery/services/magic-metadata";
-import type { Collection } from "ente-media/collection";
+import { CollectionOrder, type Collection } from "ente-media/collection";
 import { ItemVisibility } from "ente-media/file-metadata";
 import {
     GalleryItemsHeaderAdapter,
@@ -277,9 +277,13 @@ const CollectionOptions: React.FC<CollectionHeaderProps> = ({
         setActiveCollectionID(ALL_SECTION);
     });
 
-    const pinAlbum = wrap(() => changeCollectionOrder(activeCollection, 1));
+    const pinAlbum = wrap(() =>
+        changeCollectionOrder(activeCollection, CollectionOrder.pinned),
+    );
 
-    const unpinAlbum = wrap(() => changeCollectionOrder(activeCollection, 0));
+    const unpinAlbum = wrap(() =>
+        changeCollectionOrder(activeCollection, CollectionOrder.default),
+    );
 
     const hideAlbum = wrap(async () => {
         await changeCollectionVisibility(

web/apps/photos/src/utils/collection.ts

@@ -6,6 +6,7 @@ import { updateMagicMetadata } from "ente-gallery/services/magic-metadata";
 import {
     type Collection,
     CollectionMagicMetadataProps,
+    type CollectionOrder,
     CollectionPublicMagicMetadataProps,
     CollectionSubType,
 } from "ente-media/collection";
@@ -21,6 +22,7 @@ import {
     isIncomingShare,
     moveToCollection,
     restoreToCollection,
+    updateCollectionOrder,
     updateCollectionVisibility,
 } from "ente-new/photos/services/collection";
 import {
@@ -213,24 +215,8 @@ export const changeCollectionSortOrder = async (
 
 export const changeCollectionOrder = async (
     collection: Collection,
-    order: number,
-) => {
-    try {
-        const updatedMagicMetadataProps: CollectionMagicMetadataProps = {
-            order,
-        };
-
-        const updatedMagicMetadata = await updateMagicMetadata(
-            updatedMagicMetadataProps,
-            collection.magicMetadata,
-            collection.key,
-        );
-
-        await updateCollectionMagicMetadata(collection, updatedMagicMetadata);
-    } catch (e) {
-        log.error("change collection order failed", e);
-    }
-};
+    order: CollectionOrder,
+) => updateCollectionOrder(await collection1To2(collection), order);
 
 export const changeCollectionSubType = async (
     collection: Collection,

web/packages/media/collection.ts

@@ -637,6 +637,29 @@ export const CollectionSubType = {
 export type CollectionSubType =
     (typeof CollectionSubType)[keyof typeof CollectionSubType];
 
+/**
+ * Ordering of the collection - Whether it is pinned or not.
+ */
+export const CollectionOrder = {
+    /**
+     * The default / normal value. No special semantics, behaves "unpinned" and
+     * will retain its natural sort position.
+     */
+    default: 0,
+    /**
+     * The collection is "pinned" by moving to the beginning of the sort order.
+     *
+     * Multiple collections can be pinned, in which case they'll be sorted
+     * amongst themselves under the otherwise applicable sort order.
+     *
+     *     -- [pinned collections] -- [other collections] --
+     */
+    pinned: 1,
+} as const;
+
+export type CollectionOrder =
+    (typeof CollectionOrder)[keyof typeof CollectionOrder];
+
 /**
  * Mutable private metadata associated with a {@link Collection}.
  *
@@ -646,6 +669,12 @@ export type CollectionSubType =
  * See: [Note: Private magic metadata is called magic metadata on remote]
  */
 export interface CollectionPrivateMagicMetadataData {
+    /**
+     * The subtype of the collection type (if applicable).
+     *
+     * Expected to be one of {@link CollectionSubType}.
+     */
+    subType?: number;
     /**
      * The (owner specific) visibility of the collection.
      *
@@ -660,20 +689,10 @@ export interface CollectionPrivateMagicMetadataData {
      * instead of the expected enum.
      */
     visibility?: number;
-    /**
-     * The subtype of the collection type (if applicable).
-     *
-     * Expected to be one of {@link CollectionSubType}.
-     */
-    subType?: number;
     /**
      * An overrride to the sort ordering used for the collection.
      *
-     * - For pinned collections, this will be set to `1`. Pinned collections
-     *   will be moved to the beginning of the sort order.
-     *
-     * - Otherwise, the collection is a normal (unpinned) collection, and will
-     *   retain its natural sort position.
+     * Expected to be one of {@link CollectionOrder}.
      */
     order?: number;
 }
@@ -684,8 +703,8 @@ export interface CollectionPrivateMagicMetadataData {
  * See: [Note: Use looseObject for metadata Zod schemas]
  */
 const CollectionPrivateMagicMetadataData = z.looseObject({
-    visibility: z.number().nullish().transform(nullToUndefined),
     subType: z.number().nullish().transform(nullToUndefined),
+    visibility: z.number().nullish().transform(nullToUndefined),
     order: z.number().nullish().transform(nullToUndefined),
 });
 

web/packages/new/photos/services/collection.ts

@@ -17,6 +17,7 @@ import {
     type Collection,
     type Collection2,
     type CollectionNewParticipantRole,
+    type CollectionOrder,
     type CollectionPrivateMagicMetadataData,
     type CollectionShareeMagicMetadataData,
     type CollectionType,
@@ -457,6 +458,23 @@ export const updateCollectionVisibility = async (
         ? updateCollectionPrivateMagicMetadata(collection, { visibility })
         : updateCollectionShareeMagicMetadata(collection, { visibility });
 
+/**
+ * Change the pinned state of a collection on remote.
+ *
+ * Remote only, does not modify local state.
+ *
+ * This function works only for collections owned by the user.
+ *
+ * @param collection The collection whose order we want to change.
+ *
+ * @param order Whether on not the collection is pinned.
+ */
+export const updateCollectionOrder = async (
+    collection: Collection2,
+    order: CollectionOrder,
+) =>
+    updateCollectionPrivateMagicMetadata(collection, { order })
+
 /**
  * Update the private magic metadata contents of a collection on remote.
  *