gistfile1.txt

Instructions for AI coding assistants to help them do a better job creating basic SharePoint Embedded apps.
SharePoint Embedded is a API only version of SharePoint that uses FileStorageContainers as a new file storage primitive.  The API that’s used is the Microsoft Graph API.  A FileStorageContainer typically supports the same file related functions as a drive.  And documents or files inside a FileStorageContainer behave the same as a drive item.
Look and Feel
•	Unless instructed otherwise, you should create a modern webapp with san serif fonts and minimalist ux.
SharePoint Embedded
•	Overview - https://learn.microsoft.com/en-us/sharepoint/dev/embedded/overview 
Authentication Information
•	Use MSAL to create a public client application.
•	The user should provide you a client id and a tenant id.
•	They should have already configured the client to support the require oauth scopes, including FileStorageContainer.selected.
•	Apps authenticate with a delegate token.  Only authenticated users can access this app.
•	Apps should support logout.
API Information
•	Unless stated otherwise, you are using v1.0 of the Microsoft Graph API.  You can find detailed documentation here.  https://learn.microsoft.com/en-us/graph/traverse-the-graph?view=graph-rest-1.0&tabs=http 
File Storage Container
•	Every app that uses SharePoint Embedded must have a Container Type Id.  You will use this the find your File Storage Containers.
•	You can find information about listing the File Storage Containers a user has access to here: https://learn.microsoft.com/en-us/graph/api/filestorage-list-containers?view=graph-rest-1.0&tabs=http
•	Authenticated users should also be able to create a File Storage Container.  https://learn.microsoft.com/en-us/graph/api/filestoragecontainer-post?view=graph-rest-1.0&tabs=http 
•	A FileStorageContainer’s “id” property is the same as a Drive Id.
•	A user may want to view the drive info properties and you should add for that.
Files
•	You can find common tasks a user might want to do with drive items here https://learn.microsoft.com/en-us/graph/api/resources/driveitem?view=graph-rest-1.0
•	A user should be able to list the files inside of a File Storage Container using the regular Graph APIs with a Drive Id format.  You can get the root following these details https://learn.microsoft.com/en-us/graph/api/driveitem-get?view=graph-rest-1.0&tabs=http and you can get children following these details https://learn.microsoft.com/en-us/graph/api/driveitem-list-children?view=graph-rest-1.0&tabs=http 
•	A user will want to upload one or more files and you should enabled that.
•	A user will likely want to edit Word Excel PowerPoint files.  You should use the webUrl property to enable that on click.  
•	A user will want to preview PDFs, images, movies, and you should use the drive item preview capability to do that by just clicking on the name.  Check out this instructions for preview and for removing the onedrive banner at the top -- https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/tutorials/using-file-preview 
•	The list of files should automatically refresh as files are added deleted or restored.
Additional File Storage Container Functionality
•	Once someone has selected a File Storage Container, add this functionality as part of the same screen where we can see files.
•	Start with permissions.  You should be able to list, add, update and delete permissions.
o	List - https://learn.microsoft.com/en-us/graph/api/filestoragecontainer-list-permissions?view=graph-rest-1.0&tabs=http 
o	Add - https://learn.microsoft.com/en-us/graph/api/filestoragecontainer-post-permissions?view=graph-rest-1.0&tabs=http 
o	Update - https://learn.microsoft.com/en-us/graph/api/filestoragecontainer-update-permissions?view=graph-rest-1.0&tabs=http 
o	Delete - https://learn.microsoft.com/en-us/graph/api/filestoragecontainer-delete-permissions?view=graph-rest-1.0&tabs=http 
•	Now add recycle bin – 
o	Get - https://learn.microsoft.com/en-us/graph/api/filestoragecontainer-list-recyclebinitem?view=graph-rest-1.0&tabs=http 
o	Restore - https://learn.microsoft.com/en-us/graph/api/filestoragecontainer-restore-recyclebinitem?view=graph-rest-1.0&tabs=http 
o	Hard Delete - https://learn.microsoft.com/en-us/graph/api/filestoragecontainer-delete-recyclebinitem?view=graph-rest-1.0&tabs=http 
o	Settings - https://learn.microsoft.com/en-us/graph/api/filestoragecontainer-update-recyclebinsettings?view=graph-rest-1.0&tabs=http 
Additional File Drive Item Functionality
Add full support for
•	Viewing versions
•	Downloading
•	List, add, delete permissions
•	Create folders, and managing all for of the folder navigation with breadcrumbs
•	Get analytics
Search Functionality

  API Overview

  - Use the Microsoft Graph /search/query endpoint (POST) to search for driveItems
  - Documentation: https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/content-experiences/search-content
  - Reference: https://learn.microsoft.com/en-us/graph/search-concept-files

  Request Format

  POST https://graph.microsoft.com/v1.0/search/query

  {
    "requests": [{
      "entityTypes": ["driveItem"],
      "query": {
        "queryString": "{searchTerm} AND ContainerTypeId:{containerTypeId}"
      },
      "sharePointOneDriveOptions": {
        "includeHiddenContent": true
      }
    }]
  }

  Response Structure

  The response is nested: response.value[0].hitsContainers[0].hits contains the array of search results. Each hit includes:
  - hitId - unique identifier
  - summary - text snippet with custom XML tags for highlighting
  - resource - the driveItem with full metadata including parentReference.siteId and parentReference.sharepointIds.listItemUniqueId

  Summary Formatting

  Search summaries contain custom XML tags that must be processed for display:
  - <c0>term</c0> - highlighted search terms, replace with styled <mark> or <span>
  - <ddd/> - truncation marks, replace with "..."

  Building Edit URLs for Office Documents

  To open Office files (doc, docx, xls, xlsx, ppt, pptx) in SharePoint's editor, construct a URL from the hit resource:

  function buildEditUrlFromHit(resource) {
    // Required properties
    const siteId = resource.parentReference?.siteId;
    const webUrl = resource.webUrl;
    const listItemUniqueId = resource.parentReference?.sharepointIds?.listItemUniqueId;

    if (!siteId || !webUrl || !listItemUniqueId) return null;

    // Extract hostname from siteId (format: "hostname,guid,guid")
    const hostname = siteId.split(',')[0];

    // Extract site path from webUrl (e.g., "/contentstorage/CSP_xxx")
    const sitePath = '/' + webUrl.split('/').slice(3, 5).join('/');

    // Format sourcedoc parameter
    const sourcedoc = encodeURIComponent(`{${listItemUniqueId.toUpperCase()}}`);

    // Build final URL
    return `https://${hostname}${sitePath}/_layouts/15/Doc.aspx?sourcedoc=${sourcedoc}&file=${encodeURIComponent(resource.name)}&action=edit&mobileredirect=true`;
  }

  Click Behavior

  When a user clicks on a search result:
  1. Office documents (doc, docx, xls, xlsx, ppt, pptx) - Open using the constructed SharePoint edit URL in a new tab
  2. PDFs, images, videos - Use the driveItem preview API (POST /drives/{driveId}/items/{itemId}/preview) and display in an iframe
  3. Other files - Navigate to the container/folder containing the file

  UX Requirements

  - Debounce search input (300-500ms) to avoid excessive API calls
  - Require minimum 2 characters before searching
  - Show loading indicator during search
  - Display "No results found" message when search returns empty
  - Show result count
  - Display search summaries with highlighted terms below each result name

Admin Functionality
•	Add a way to view API call history, full URL request response timing and headers.  This should be a flyout of some kind.
Test Suite Requirements
•	There should be a robust automated test suite