feat: followers settings schema and behavior (#1211)

- adds IWithFollowersBehavior which exposes getFollowers and setFollowersAccess on all item-backed entities
- adds a new SiteUiSchemaFollowers and adds the toEditor/fromEditor logic
- adds convertFeaturesToLegacyCapabilities and migrateLegacyCapabilitiesToFeatures functions that get executed when we call updateSite and fetchSite respectively

packages/common/src/core/HubItemEntity.ts

@@ -1,10 +1,12 @@
 import {
   IGroup,
   IItem,
+  getGroup,
   removeItemResource,
   setItemAccess,
   shareItemWithGroup,
   unshareItemWithGroup,
+  updateGroup,
 } from "@esri/arcgis-rest-portal";
 import { IArcGISContext } from "../ArcGISContext";
 import HubError from "../HubError";
@@ -29,10 +31,11 @@ import {
 } from "./behaviors";
 
 import { IWithThumbnailBehavior } from "./behaviors/IWithThumbnailBehavior";
-import { IHubItemEntity, SettableAccessLevel } from "./types";
+import { AccessLevel, IHubItemEntity, SettableAccessLevel } from "./types";
 import { sharedWith } from "./_internal/sharedWith";
 import { IWithDiscussionsBehavior } from "./behaviors/IWithDiscussionsBehavior";
 import { setDiscussableKeyword } from "../discussions";
+import { IWithFollowersBehavior } from "./behaviors/IWithFollowersBehavior";
 
 const FEATURED_IMAGE_FILENAME = "featuredImage.png";
 
@@ -46,7 +49,8 @@ export abstract class HubItemEntity<T extends IHubItemEntity>
     IWithThumbnailBehavior,
     IWithFeaturedImageBehavior,
     IWithPermissionBehavior,
-    IWithDiscussionsBehavior
+    IWithDiscussionsBehavior,
+    IWithFollowersBehavior
 {
   protected context: IArcGISContext;
   protected entity: T;
@@ -222,6 +226,30 @@ export abstract class HubItemEntity<T extends IHubItemEntity>
     this.entity.access = access;
   }
 
+  /**
+   * Returns the followers group
+   */
+  async getFollowersGroup(): Promise<IGroup> {
+    return getGroup(
+      this.entity.followersGroupId,
+      this.context.userRequestOptions
+    );
+  }
+
+  /**
+   * Sets the access level of the followers group
+   * @param access
+   */
+  async setFollowersGroupAccess(access: SettableAccessLevel): Promise<void> {
+    await updateGroup({
+      group: {
+        id: this.entity.followersGroupId,
+        access,
+      },
+      authentication: this.context.session,
+    });
+  }
+
   /**
    * Return a list of groups the Entity is shared to.
    * @returns

packages/common/src/core/behaviors/IWithFollowersBehavior.ts

@@ -0,0 +1,16 @@
+import { IGroup } from "@esri/arcgis-rest-types";
+import { SettableAccessLevel } from "../types";
+
+/**
+ * Followers behavior for Item-Backed Entities
+ */
+export interface IWithFollowersBehavior {
+  /**
+   * Get the followers group
+   */
+  getFollowersGroup(): Promise<IGroup>;
+  /**
+   * Set the access level of the followers group
+   */
+  setFollowersGroupAccess(access: SettableAccessLevel): Promise<void>;
+}

packages/common/src/core/schemas/internal/getEntityEditorSchemas.ts

@@ -55,6 +55,8 @@ export async function getEntityEditorSchemas(
           import("../../../sites/_internal/SiteUiSchemaEdit"),
         "hub:site:create": () =>
           import("../../../sites/_internal/SiteUiSchemaCreate"),
+        "hub:site:followers": () =>
+          import("../../../sites/_internal/SiteUiSchemaFollowers"),
       }[type as SiteEditorType]();
       uiSchema = await siteModule.buildUiSchema(
         i18nScope,

packages/common/src/core/schemas/internal/subsetSchema.ts

@@ -12,6 +12,13 @@ export function subsetSchema(
   props: string[]
 ): IConfigurationSchema {
   const subset: IConfigurationSchema = cloneObject(schema);
+
+  // 1. remove un-specified properties from the "required" array
+  subset.required = [...subset.required].filter((required) =>
+    props.includes(required)
+  );
+
+  // 2. filter the rest of the schema down to the specified properties
   Object.keys(subset.properties).forEach((key) => {
     if (props.indexOf(key) === -1) {
       delete subset.properties[key];

packages/common/src/core/schemas/shared/HubItemEntitySchema.ts

@@ -30,6 +30,19 @@ export const HubItemEntitySchema: IConfigurationSchema = {
     categories: ENTITY_CATEGORIES_SCHEMA,
     isDiscussable: ENTITY_IS_DISCUSSABLE_SCHEMA,
     _thumbnail: ENTITY_IMAGE_SCHEMA,
+    _followers: {
+      type: "object",
+      properties: {
+        groupAccess: {
+          ...ENTITY_ACCESS_SCHEMA,
+          enum: ["private", "org", "public"],
+        },
+        showFollowAction: {
+          type: "boolean",
+          default: true,
+        },
+      },
+    },
     view: {
       type: "object",
       properties: {

packages/common/src/core/traits/IWithFollowers.ts

@@ -3,5 +3,5 @@
  */
 export interface IWithFollowers {
   /** followers group id */
-  followersGroupId: string;
+  followersGroupId?: string;
 }

packages/common/src/core/types/IHubItemEntity.ts

@@ -7,14 +7,16 @@ import {
   IWithDiscussions,
 } from "../traits";
 import { IHubLocation } from "./IHubLocation";
+import { IWithFollowers } from "../traits/IWithFollowers";
 
 /**
  * Properties exposed by Entities that are backed by Items
  */
 export interface IHubItemEntity
   extends IHubEntityBase,
     IWithPermissions,
-    IWithDiscussions {
+    IWithDiscussions,
+    IWithFollowers {
   /**
    * Access level of the item ("private" | "org" | "public")
    */
@@ -128,3 +130,20 @@ export interface IHubItemEntity
    */
   protected?: boolean;
 }
+
+export type IHubItemEntityEditor<T> = Omit<T, "extent"> & {
+  /**
+   * Thumbnail image. This is only used on the Editor and is
+   * persisted in the fromEditor method on the Class
+   */
+  _thumbnail?: any;
+  /**
+   * Follower group settings. These settings are only used in the
+   * Editor and is persisted appropriately in the fromEditor
+   * method on the Class
+   */
+  _followers?: {
+    groupAccess?: AccessLevel;
+    showFollowAction?: boolean;
+  };
+};

packages/common/src/core/types/IHubSite.ts

@@ -6,8 +6,7 @@ import {
   IWithPermissions,
   IWithSlug,
 } from "../traits/index";
-import { IHubItemEntity } from "./IHubItemEntity";
-import { IWithFollowers } from "../traits/IWithFollowers";
+import { IHubItemEntity, IHubItemEntityEditor } from "./IHubItemEntity";
 
 /**
  * DRAFT: Under development and more properties will likely be added
@@ -19,8 +18,7 @@ export interface IHubSite
     IWithCatalog,
     IWithLayout,
     IWithPermissions,
-    IWithVersioningBehavior,
-    IWithFollowers {
+    IWithVersioningBehavior {
   /**
    * Array of minimal page objects
    */
@@ -83,10 +81,4 @@ export interface IHubSite
   legacyTeams: string[];
 }
 
-export type IHubSiteEditor = Omit<IHubSite, "extent"> & {
-  /**
-   * Thumbnail image. This is only used on the Editor and is
-   * persisted in the fromEditor method on the Class
-   */
-  _thumbnail?: any;
-};
+export type IHubSiteEditor = IHubItemEntityEditor<IHubSite> & {};

packages/common/src/sites/HubSite.ts

@@ -46,7 +46,7 @@ import { cloneObject } from "../util";
 import { PropertyMapper } from "../core/_internal/PropertyMapper";
 import { getPropertyMap } from "./_internal/getPropertyMap";
 
-import { IHubSiteEditor, IModel } from "../index";
+import { IHubSiteEditor, IModel, SettableAccessLevel } from "../index";
 import { SiteEditorType } from "./_internal/SiteSchema";
 
 /**
@@ -403,10 +403,15 @@ export class HubSite
    * @returns
    */
   toEditor(editorContext: IEntityEditorContext = {}): IHubSiteEditor {
-    // Cast the entity to it's editor
+    // 1. Cast entity to editor
     const editor = cloneObject(this.entity) as IHubSiteEditor;
 
-    // Add other transforms here...
+    // 2. Apply transforms to relevant entity values so they
+    // can be consumed by the editor
+    editor._followers = {};
+    editor._followers.showFollowAction =
+      this.entity.features["hub:site:feature:follow"];
+
     return editor;
   }
 
@@ -418,6 +423,9 @@ export class HubSite
   async fromEditor(editor: IHubSiteEditor): Promise<IHubSite> {
     const isCreate = !editor.id;
 
+    // 1. Perform any pre-save operations e.g. storing
+    // image resources on the item, setting access, etc.
+
     // Setting the thumbnailCache will ensure that
     // the thumbnail is updated on next save
     if (editor._thumbnail) {
@@ -436,18 +444,29 @@ export class HubSite
 
     delete editor._thumbnail;
 
-    // convert back to an entity. Apply any reverse transforms used in
-    // of the toEditor method
+    // set the followers group access
+    if (editor._followers?.groupAccess) {
+      await this.setFollowersGroupAccess(
+        editor._followers.groupAccess as SettableAccessLevel
+      );
+    }
+
+    // 2. Convert editor values back to an entity e.g. apply
+    // any reverse transforms used in the toEditor method
     const entity = cloneObject(editor) as IHubSite;
 
+    entity.features = {
+      ...entity.features,
+      "hub:site:feature:follow": editor._followers?.showFollowAction,
+    };
+
     // copy the location extent up one level
     entity.extent = editor.location?.extent;
 
-    // create it if it does not yet exist...
+    // 3. create or update the in-memory entity and save
     if (isCreate) {
       throw new Error("Cannot create content using the Editor.");
     } else {
-      // ...otherwise, update the in-memory entity and save it
       this.entity = entity;
       await this.save();
     }

packages/common/src/sites/HubSites.ts

@@ -37,6 +37,7 @@ import { setDiscussableKeyword } from "../discussions";
 import { applyDefaultCollectionMigration } from "./_internal/applyDefaultCollectionMigration";
 import { reflectCollectionsToSearchCategories } from "./_internal/reflectCollectionsToSearchCategories";
 import { convertCatalogToLegacyFormat } from "./_internal/convertCatalogToLegacyFormat";
+import { convertFeaturesToLegacyCapabilities } from "./_internal/capabilities/convertFeaturesToLegacyCapabilities";
 export const HUB_SITE_ITEM_TYPE = "Hub Site Application";
 export const ENTERPRISE_SITE_ITEM_TYPE = "Site Application";
 
@@ -345,6 +346,20 @@ export async function updateSite(
   // with the existing structure on the most current model.
   // TODO: Remove once the application is plumbed to work off an IHubCatalog
   modelToUpdate = convertCatalogToLegacyFormat(modelToUpdate, currentModel);
+  /**
+   * Site capabilities are currently saved as an array on the
+   * site.data.values.capabilities. We want to migragte these
+   * legacy capabilities over to features in the new permissions
+   * system; however, we must continue persisting updates to
+   * these features in the legacy capabilities array until the
+   * existing site capabilities in our application are plumbed
+   * to work off of permissions
+   * TODO: Remove once site capabilities use permissions
+   */
+  modelToUpdate = convertFeaturesToLegacyCapabilities(
+    modelToUpdate,
+    currentModel
+  );
 
   // send updates to the Portal API and get back the updated site model
   const updatedSiteModel = await updateModel(

packages/common/src/sites/_internal/SiteBusinessRules.ts

@@ -7,6 +7,7 @@ export const SiteDefaultFeatures: IFeatureFlags = {
   "hub:site:events": false,
   "hub:site:content": true,
   "hub:site:discussions": false,
+  "hub:site:feature:follow": true,
 };
 
 /**
@@ -23,6 +24,7 @@ export const SitePermissions = [
   "hub:site:events",
   "hub:site:content",
   "hub:site:discussions",
+  "hub:site:feature:follow",
   "hub:site:workspace:overview",
   "hub:site:workspace:dashboard",
   "hub:site:workspace:details",
@@ -81,6 +83,11 @@ export const SitesPermissionPolicies: IPermissionPolicy[] = [
     permission: "hub:site:discussions",
     dependencies: ["hub:site:view"],
   },
+  {
+    permission: "hub:site:feature:follow",
+    dependencies: ["hub:site:view"],
+    entityConfigurable: true,
+  },
   {
     permission: "hub:site:workspace:overview",
     dependencies: ["hub:site:view"],

packages/common/src/sites/_internal/SiteSchema.ts

@@ -2,7 +2,11 @@ import { IConfigurationSchema } from "../../core";
 import { HubItemEntitySchema } from "../../core/schemas/shared/HubItemEntitySchema";
 
 export type SiteEditorType = (typeof SiteEditorTypes)[number];
-export const SiteEditorTypes = ["hub:site:edit", "hub:site:create"] as const;
+export const SiteEditorTypes = [
+  "hub:site:edit",
+  "hub:site:create",
+  "hub:site:followers",
+] as const;
 
 /**
  * defines the JSON schema for a Hub Site's editable fields

packages/common/src/sites/_internal/SiteUiSchemaEdit.ts

@@ -8,9 +8,9 @@ import { IHubSite } from "../../core/types";
 
 /**
  * @private
- * construct edit uiSchema for Hub Projects - this defines
- * how the schema properties should be rendered in the
- * project editing experience
+ * constructs the edit uiSchema for Hub Sites.
+ * This defines how the schema properties should
+ * be rendered in the site editing experience
  */
 export const buildUiSchema = async (
   i18nScope: string,