# SharePoint Document Library Browser

## Purpose

This Yeeflow Custom Code control presents a SharePoint document library as an expandable file browser inside a Yeeflow page or form. It is designed for read-only discovery and navigation: users can inspect folders and files, expand nested folders, refresh the current listing, and open an item in SharePoint.

## When to use it

Use the control when users need document-library visibility without leaving the Yeeflow process until they choose a specific item. Typical examples include sales quotation folders, project documentation, procurement evidence, customer files, policies, contracts, and departmental knowledge libraries.

Do not use this control when the requirement includes upload, rename, delete, move, inline content preview, file download through Yeeflow, selection writeback, or document editing. Those capabilities are not implemented in this source.

## Supported placement

Observed in the source:

- The component reads only `context.params`, the named Connection, and `context.modules.fetch`.
- It does not read form-field values and does not write to fields or variables.
- It ignores the host `readonly` flag because it exposes no data-mutation actions.

Likely compatible placements are Dashboard pages, Approval Forms, and Data List custom forms, provided the runtime exposes Custom Code connections and the fetch wrapper. Validate each placement in the target tenant. Public-form support is not claimed.

## Required connection

The Custom Code declares one connection:

| Connection ID | Required | Purpose |
| --- | --- | --- |
| `sharePointConnection` | Yes | Microsoft Graph / SharePoint OAuth HTTP Connection used for all site, drive, and drive-item GET requests. |

Create or select a managed Connection whose identity is authorized to read the target site and document library. Apply the least privilege allowed by the tenant. Do not store tokens in Custom Code parameters.

At runtime, the source first checks `context.connections.sharePointConnection`, then falls back to `context.getConnection('sharePointConnection')`. Requests are sent through `context.modules.fetch` with the connection object. The source also recognizes common connection authorization fields when the runtime exposes them.

## Input parameters

| Parameter | Yeeflow type | Required | Purpose | Example |
| --- | --- | --- | --- | --- |
| `siteUrl` | Variable | Yes | HTTPS URL of the SharePoint site. | `https://contoso.sharepoint.com/sites/Sales` |
| `libraryNameOrId` | Variable | Yes | Document-library display name or Microsoft Graph drive ID. | `Documents` |
| `folderPath` | Variable | No | Path below the library root. Leave empty for the root. | `Sales Quotations/2026` |
| `title` | String | No | Browser heading. | `Sales Documents` |

### `siteUrl`

Provide the full HTTPS URL of the SharePoint team site, not a document or folder sharing URL. The code parses the hostname and site path, removes trailing slashes, and asks Microsoft Graph to resolve the site.

Examples:

- `https://contoso.sharepoint.com/sites/Sales`
- `https://contoso.sharepoint.com/teams/Operations`

Non-HTTPS values and URLs without a hostname are rejected.

### `libraryNameOrId`

Provide either the document-library display name or its Microsoft Graph drive ID. Matching is case-insensitive. The code queries all drives exposed for the resolved site and selects the first exact ID or name match.

If a library was renamed, update this parameter or use the stable drive ID.

### `folderPath`

Provide a path relative to the document-library root. Do not include the site URL or library name. Forward and backward slashes are accepted and normalized. Leading, trailing, and repeated slashes are removed.

Examples:

- Empty value: display the library root
- `Sales Quotations`: display only the direct children of that folder
- `Sales Quotations/2026/Approved`: start at a nested folder

`.` and `..` path segments are rejected. The configured path is encoded segment by segment before it is sent to Microsoft Graph.

### `title`

Optional static heading above the browser. If empty, the component displays `SharePoint documents`.

## Configuration steps

1. Confirm the target SharePoint site URL and document-library name or drive ID.
2. Create or select a Microsoft Graph / SharePoint OAuth HTTP Connection in Yeeflow.
3. Ensure the connection identity can read the target site, drive, folders, and files according to tenant policy.
4. Add a Custom Code control to the intended Yeeflow page or form.
5. Paste or upload `sharepoint-document-library-browser.tsx`.
6. Bind the declared `sharePointConnection` connection slot.
7. Configure `siteUrl` and `libraryNameOrId`.
8. Leave `folderPath` empty for the library root, or enter a path relative to that root.
9. Optionally set `title`.
10. Preview the control and confirm the initial listing, nested-folder expansion, Open links, and Refresh behavior.
11. Repeat the test in the final published runtime and with an account representing the intended audience.

## Retrieval and display behavior

On initial load, the component:

1. Resolves the configured SharePoint site.
2. Retrieves the site's drives and finds the configured document library.
3. Loads the root or configured folder.
4. Requests only `id`, `name`, `folder`, `file`, `webUrl`, `size`, `lastModifiedDateTime`, and `parentReference` for each item.
5. Follows every Microsoft Graph `@odata.nextLink` for that folder.
6. Sorts folders before files, then sorts by name without case sensitivity.

Nested folders load lazily when expanded. Loaded child collections are cached in component state until Refresh or a relevant parameter/connection change clears the browser state.

## User interaction

- Select the chevron or folder name to expand or collapse a folder.
- Select a file name or Open to open its SharePoint `webUrl` in a new tab.
- Select Refresh to resolve the site and library again and reload the starting location.
- On screens narrower than 760 px, Name and Open remain visible while Type, Modified, and Size are hidden.

The component displays dedicated messages for loading, empty locations, empty expanded folders, missing configuration, missing Connection, unsupported runtime fetch, invalid paths, missing sites or libraries, and Microsoft Graph request errors.

## Example business scenarios

### Sales quotation library

Show the `Sales Quotations` folder from a central Documents library inside a sales dashboard. Users expand opportunity folders and open the latest quotation in SharePoint.

### Project documentation

Bind `folderPath` to a trusted expression that resolves to a project folder such as `Projects/PRJ-1042`. Validate that the expression cannot produce an unintended site or path.

### Policy library

Leave `folderPath` empty to expose the approved policy library root. Users browse by department and open the authoritative file in SharePoint.

## Limitations and assumptions

- Display and navigation only; there is no SharePoint mutation or Yeeflow writeback.
- File content is not downloaded or previewed inside the component.
- The Open link is present only when Microsoft Graph returns `webUrl`.
- Date text uses the browser locale and timezone.
- Loading a folder follows all pagination links, so very large folders may take time and generate multiple API requests.
- Folder children are loaded on demand, not as one recursive initial query.
- The component does not implement search, filtering, paging controls, breadcrumb navigation, column sorting, permissions editing, or item selection.
- Connection and `context.modules.fetch` behavior must be verified in each Yeeflow runtime.
- The source uses a legacy React class lifecycle method for broad runtime compatibility.

## Security and governance

- Use a dedicated least-privilege managed Connection.
- Restrict who can configure dynamic site, library, and folder expressions.
- Confirm that users should see every item readable by the Connection identity in the configured location.
- Do not place secrets, access tokens, or authorization headers in `siteUrl`, `libraryNameOrId`, `folderPath`, or `title`.
- Review the tenant's Microsoft Graph consent, conditional-access, data-residency, auditing, and external-sharing policies.
- Validate displayed Graph error messages before exposing the control to broad audiences.
- The SharePoint logo in template artwork is used only to identify compatibility with Microsoft SharePoint.

## Testing checklist

- [ ] Custom Code loads without compile or runtime errors.
- [ ] The intended Connection is bound to `sharePointConnection`.
- [ ] A valid HTTPS site URL resolves successfully.
- [ ] The library resolves by display name.
- [ ] The library resolves by drive ID, if that configuration is used.
- [ ] Empty `folderPath` displays the library root.
- [ ] A valid nested `folderPath` displays only that folder's children.
- [ ] Spaces and non-ASCII path segments resolve correctly.
- [ ] `.` and `..` path segments are rejected.
- [ ] Folders appear before files and names are alphabetically ordered.
- [ ] Nested folders load when expanded and collapse correctly.
- [ ] Empty nested folders show `This folder is empty.`
- [ ] File type, modified time, and size are formatted correctly.
- [ ] File name and Open actions open the expected SharePoint item in a new tab.
- [ ] Refresh reloads the configured location.
- [ ] Parameter or Connection changes reset and reload the listing.
- [ ] Microsoft Graph pagination is exercised with a folder large enough to return `@odata.nextLink`.
- [ ] Missing configuration, missing Connection, permission failures, missing library, and missing folder show readable errors.
- [ ] Narrow-screen layout keeps Name and Open usable.
- [ ] Dashboard, Approval Form, and Data List placements are tested separately before being claimed as supported.

## Troubleshooting

### Configure Site URL and Document Library Name or ID

One or both required parameters resolved to an empty value. Check the expression result, not only the value shown in the Designer.

### Select a Microsoft Graph Connection

Bind the declared `sharePointConnection` slot and confirm the Connection is available in the published runtime.

### The Yeeflow runtime did not provide `context.modules.fetch`

The current placement or runtime does not expose the required fetch wrapper. Test in a supported Custom Code surface or confirm platform support.

### Document library was not found by name or ID

Confirm that the site is correct, the Connection can enumerate its drives, and the library display name or drive ID exactly matches after case normalization.

### Access denied or Microsoft Graph request failed

Review the Connection identity, tenant consent, site access, library permissions, conditional-access rules, and the HTTP status returned by Microsoft Graph.

### Folder cannot be found

Enter a path relative to the library root. Remove the site URL and library name, check each segment's spelling, and avoid `.` or `..`.

### A folder is slow to open

The folder may contain enough items to require several Graph pages. The component follows all pages before displaying the completed child collection.

### Refresh previously showed a configuration error

Version 1.0.0 of this published source includes a corrected Refresh event binding that explicitly calls `reload()` without passing the React click event as configuration.