Skip to content

Create comprehensive SafeAreaEdges documentation for .NET 10 #3058

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 7 commits into
base: main
Choose a base branch
from
Draft

Create comprehensive SafeAreaEdges documentation for .NET 10 #3058

wants to merge 7 commits into from

Conversation

Copy link
Contributor

Copilot AI commented Oct 12, 2025 •
edited
Loading

SafeAreaEdges Documentation Plan

  • Create comprehensive SafeAreaEdges documentation file (safe-area.md)
    • Overview and purpose
    • SafeAreaEdges enum documentation
    • Usage examples for all controls (ContentPage, Layout, ScrollView, ContentView, Border)
    • Platform-specific behavior and notes
    • Migration guidance from old APIs
    • Common scenarios and best practices
  • Add to TOC for discoverability
  • Verify and update cross-references
    • Link from whats-new/dotnet-10.md
    • Link from ios/platform-specifics/page-safe-area-layout.md
  • Test documentation builds correctly
    • All markdown linting passes
    • No broken cross-references
  • Fix enum type references
    • Corrected C# code to use SafeAreaEdges.None instead of SafeAreaRegions.None
    • Updated all xrefs from Microsoft.Maui.SafeAreaRegions to Microsoft.Maui.SafeAreaEdges
    • Updated enum name in documentation from SafeAreaRegions to SafeAreaEdges
  • Address PR feedback
    • Removed Windows platform section (API doesn't work on Windows)
    • Removed "Reading safe area insets" section
    • Fixed migration example to use "Container" instead of "All"
    • Added documentation for default SafeAreaEdges values by control type
    • Updated Grid example to explicitly set SafeAreaEdges="None" for edge-to-edge content

Summary

Comprehensive SafeAreaEdges documentation for .NET MAUI 10 with all feedback addressed, including default value documentation and updated examples.

Original prompt

This section details on the original issue you should resolve

<issue_title>Create initial docs for SafeAreaEdges</issue_title>
<issue_description>The following pr describes and implements all the behavior for the new SafeAreaEdges apis in .net Maui. dotnet/maui#30337 that have been added in .net10

We need to create all the docs and examples for these new apis.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #3057

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

@learn-build-service-prod
Copy link

Learn Build status updates of commit f1cc7d7:

✅ Validation status: passed

For more details, please refer to the build report.

@learn-build-service-prod
Copy link

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

Learn Build status updates of commit 7b9ee55:

✅ Validation status: passed

File Status Preview URL Details
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/safe-area.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

@learn-build-service-prod
Copy link

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

Learn Build status updates of commit 7b9ee55:

✅ Validation status: passed

File Status Preview URL Details
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/safe-area.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

@learn-build-service-prod
Copy link

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

Learn Build status updates of commit 5338905:

✅ Validation status: passed

File Status Preview URL Details
docs/ios/platform-specifics/page-safe-area-layout.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/safe-area.md ✅Succeeded View (>=net-maui-8.0)
docs/whats-new/dotnet-10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

@learn-build-service-prod
Copy link

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

1 similar comment
@learn-build-service-prod
Copy link

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

Learn Build status updates of commit ad7ddb4:

✅ Validation status: passed

File Status Preview URL Details
docs/ios/platform-specifics/page-safe-area-layout.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/safe-area.md ✅Succeeded View (>=net-maui-8.0)
docs/whats-new/dotnet-10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

Copilot AI changed the title [WIP] Add initial documentation for SafeAreaEdges APIs Create comprehensive SafeAreaEdges documentation for .NET 10 Oct 12, 2025
Copilot finished work on behalf of PureWeen October 12, 2025 15:19
Copilot AI requested a review from PureWeen October 12, 2025 15:19
PureWeen
PureWeen reviewed Oct 13, 2025
View reviewed changes
docs/user-interface/safe-area.md Outdated
```csharp
var page = new ContentPage
{
SafeAreaEdges = SafeAreaRegions.None,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot
Cannot implicitly convert type 'Microsoft.Maui.SafeAreaRegions' to 'Microsoft.Maui.SafeAreaEdges'CS0029

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in commit ad7ddb4. Changed SafeAreaRegions.None to SafeAreaEdges.None and updated all xrefs and enum documentation to use the correct SafeAreaEdges type throughout.

PureWeen
PureWeen reviewed Oct 13, 2025
View reviewed changes
docs/user-interface/safe-area.md Outdated
- The `SoftInput` region includes the soft keyboard
- Behavior can vary based on edge-to-edge display settings and Android version

### Windows
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot this API doesn't do anything on Windows

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed Windows section in commit dee0080.

PureWeen
PureWeen reviewed Oct 13, 2025
View reviewed changes
docs/user-interface/safe-area.md Outdated
- The `SoftInput` region includes the on-screen keyboard when visible
- Safe areas are generally less prominent but still respected

## Reading safe area insets
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot remove this section about reading safe area insets

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the "Reading safe area insets" section in commit dee0080.

PureWeen
PureWeen reviewed Oct 13, 2025
View reviewed changes
docs/user-interface/safe-area.md Outdated
**New approach (.NET 10+):**

```xaml
<ContentPage SafeAreaEdges="All">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot this should be "Container" not call

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed from "All" to "Container" in the migration example in commit dee0080.

@learn-build-service-prod
Copy link

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

Learn Build status updates of commit dee0080:

✅ Validation status: passed

File Status Preview URL Details
docs/ios/platform-specifics/page-safe-area-layout.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/safe-area.md ✅Succeeded View (>=net-maui-8.0)
docs/whats-new/dotnet-10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

Copilot finished work on behalf of PureWeen October 13, 2025 15:55
Copilot AI requested a review from PureWeen October 13, 2025 15:55
@learn-build-service-prod
Copy link

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

Learn Build status updates of commit dee0080:

✅ Validation status: passed

File Status Preview URL Details
docs/ios/platform-specifics/page-safe-area-layout.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/safe-area.md ✅Succeeded View (>=net-maui-8.0)
docs/whats-new/dotnet-10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

Copilot finished work on behalf of PureWeen October 13, 2025 15:59
@learn-build-service-prod
Copy link

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

Learn Build status updates of commit 69a6cf8:

✅ Validation status: passed

File Status Preview URL Details
docs/ios/platform-specifics/page-safe-area-layout.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/safe-area.md ✅Succeeded View (>=net-maui-8.0)
docs/whats-new/dotnet-10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

PureWeen
PureWeen reviewed Oct 13, 2025
View reviewed changes
docs/user-interface/safe-area.md Outdated

```xaml
<ContentPage SafeAreaEdges="None">
<Grid>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot make a note here that by default "Grid" will be set to "Container" so in order for this to go edge to edge you need to set the "Grid" to "Container"

By default ContentPage will already be set to none

All controls deriving from "Layout" will be set to "Container" by default
"ContentView" and "Border" (and any controls deriving from ContentView) will be set to "None" by default

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added default value documentation in commit 69a6cf8. The documentation now includes:

  • A NOTE section explaining default values (ContentPage defaults to None, Layout/Grid defaults to Container, ContentView/Border defaults to None)
  • Updated the Grid example to explicitly set SafeAreaEdges="None" for edge-to-edge content
  • Added an explanatory note about why Grid needs explicit setting

Copilot finished work on behalf of PureWeen October 13, 2025 20:38
Copilot AI requested a review from PureWeen October 13, 2025 20:38
@learn-build-service-prod
Copy link

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

Learn Build status updates of commit 216adbb:

✅ Validation status: passed

File Status Preview URL Details
docs/ios/platform-specifics/page-safe-area-layout.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/safe-area.md ✅Succeeded View (>=net-maui-8.0)
docs/whats-new/dotnet-10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

@learn-build-service-prod
Copy link

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod
Copy link

Learn Build status updates of commit 216adbb:

✅ Validation status: passed

File Status Preview URL Details
docs/ios/platform-specifics/page-safe-area-layout.md ✅Succeeded View (>=net-maui-8.0)
docs/TOC.yml ✅Succeeded View (>=net-maui-8.0)
docs/user-interface/safe-area.md ✅Succeeded View (>=net-maui-8.0)
docs/whats-new/dotnet-10.md ✅Succeeded View (>=net-maui-8.0)

For more details, please refer to the build report.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@PureWeen PureWeen Awaiting requested review from PureWeen

At least 1 approving review is required to merge this pull request.

Assignees

@PureWeen PureWeen

Copilot code review Copilot

Labels

None yet

Projects

MAUI SDK Ongoing
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Create initial docs for SafeAreaEdges

2 participants

@PureWeen