docs(admin): add LoadingOptions interface and AppNav type sources for app-home docs

[MitchLillie]

Summary

Fixes two issues in the app-home-ui-extension docs pipeline.

Issue #2537 — LoadingOptions interface for docs consistency

Context: Tim (docs) noticed that the App Bridge (iframe) loading API has a LoadingOptions interface that renders in the docs as an expandable properties table with an isLoading?: boolean row. The UI Extension equivalent only had LoadingApi = (isLoading?: boolean) => void, which renders as a raw function signature — inconsistent with the App Bridge docs presentation.

The fix is documentation-only: LoadingOptions is added as a standalone @publicDocs interface so the docs can reference it via <TypeDefinition typeName="LoadingOptions" /> and render the properties table. The calling convention is unchanged — shopify.loading(true) / shopify.loading(false) stays exactly as-is. LoadingOptions is a parallel type for docs presentation, not a change to the function signature.

Issue #2539 — s-app-nav not appearing in generated docs

Root cause: Henry added AppNav.d.ts (a generated declaration file synced from admin-web/polaris) and deliberately did not add AppNav to components.d.ts — because components.d.ts covers all admin targets, but <s-app-nav> is only available in the admin.app.home.render target.

The problem is that the type harvester (@shopify/generate-docs) only processes .ts files, not .d.ts files. The one exception is components.d.ts, which the build script temporarily copies to components.ts before running the harvester. AppNav.d.ts is never copied, so AppNav is invisible to the harvester and never appears in the generated JSON. Additionally, AppNav.d.ts is auto-generated — adding @publicDocs to it would be wiped on the next sync.

Fix:

1. AppNavTypes.ts — A hand-written (non-generated) .ts file that exports a documented AppNav interface. Because it's a .ts file with @publicDocs, the type harvester picks it up and writes it into the app_home generated_docs_data_v2.json the next time yarn docs:admin runs. The file uses a local type ComponentChildren = any alias so TypeScript compiles cleanly, while the harvester's getTypeNameFromValueDeclaration() reads the raw source text and records "ComponentChildren" as the type value, preserving the correct name in generated docs.

2. AppNav.ab.doc.ts — Routes AppNav into the correct pipeline. The .ab.doc.ts suffix means tsconfig.ab.docs.json (app_home pipeline) includes it, and tsconfig.ext.docs.json (admin_extensions pipeline) excludes it. AppNav only appears in app-home-ui-extension docs, not in regular admin extension docs.

---

How to test

LoadingOptions

1. Run yarn docs:admin and inspect docs/surfaces/admin/generated/app_home/generated_docs_data_v2.json: a LoadingOptions key should appear with an isLoading?: boolean member.
2. Confirm LoadingApi is still "value": "(isLoading?: boolean) => void" — the signature is unchanged.
3. In the paired world PR, the loading-api page should render a properties table under "Inputs" (showing isLoading) rather than a raw function signature.

AppNav in generated docs

1. Run yarn docs:admin and inspect docs/surfaces/admin/generated/app_home/generated_docs_data_v2.json: an AppNav key should appear with id and children members.
2. Confirm AppNav does NOT appear in docs/surfaces/admin/generated/admin_extensions/*/generated_docs_data_v2.json.
3. In the paired world PR, the app-nav page should render correctly at /docs/api/app-home-ui-extension/2026-07-rc/web-components/navigation/app-nav.

Related

• Closes https://github.com/shop/issues-admin-extensibility/issues/2537
• Closes https://github.com/shop/issues-admin-extensibility/issues/2539
• Paired world PR with JSON data and MDX page updates (to follow)

[github-actions]

🚨🚨🚨 Docs migration in progress 🚨🚨🚨

We are actively migrating UI extension reference docs to MDX in the areas/platforms/shopify-dev zone of the monorepo. This impacts docs for the following surfaces:

• Admin UI extensions
• App Home
• Checkout UI extensions
• Customer account UI extensions
• POS UI extensions

During this migration, please be aware of the following:

.doc.ts files are being deprecated. Changes to .doc.ts files in this repo will not be reflected in the new MDX-based docs. If you need to update docs for a reference that has already been migrated, make your changes directly in the areas/platforms/shopify-dev zone of the monorepo instead.

Doc comments in .ts source files (the comment blocks above types and functions) are also affected. Generating docs from these comments currently requires a newer version of the @shopify/generate-docs library that isn't yet available. Updates to doc comments may not produce the expected output until the migration is complete.

Examples that previously lived in this repo are being moved to the areas/platforms/shopify-dev zone of the monorepo and should be authored there going forward.

What should I do?

• If your PR includes changes to .doc.ts files, doc comments, or examples, please reach out to us in #devtools-proj-templated-refs so we can help ensure your updates are captured correctly.
• If your PR is limited to source code changes (non-docs), you can ignore this notice.

Thanks for your patience while we complete the migration! 🙏