@shopify/ui-extensions 2025.10.13 → 2025.10.14

package/src/docs/shared/components/Stack.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Stack',
   description:
-    'Organizes elements horizontally or vertically along the block or inline axis. Use to structure layouts, group related components, or control spacing between elements.',
-  category: 'Polaris web components',
+    'The stack component organizes elements horizontally or vertically along the block or inline axis. Use stack to structure layouts, group related components, control spacing between elements, or create flexible arrangements that adapt to content.' +
+    '\n\nStacks support gap spacing, alignment, wrapping, and distribution properties to create consistent, responsive layouts without custom CSS. For complex multi-column layouts with precise grid positioning, use [grid](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/grid).',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

package/src/docs/shared/components/Summary.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Summary',
   description:
     'Provides a clickable label for collapsible Details content. Use to create clear, accessible disclosure controls that show or hide additional information.',
-  category: 'Polaris web components',
-  subCategory: 'Interactive',
+  category: 'Web components',
+  subCategory: 'Typography and content',
   related: [],
 };
 

package/src/docs/shared/components/Switch.ts

@@ -2,8 +2,10 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Switch',
-  description: 'Give users a clear way to toggle options on or off.',
-  category: 'Polaris web components',
+  description:
+    'The switch component provides a clear way for users to toggle options or settings on and off. Use switch for binary controls that take effect immediately, like enabling features, activating settings, or controlling visibility.' +
+    "\n\nSwitches provide instant visual feedback and are ideal for settings that don't require a save action to apply changes. For selections that require explicit submission, use [checkbox](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/checkbox) instead.",
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/Table.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Table',
   description:
-    'Display data clearly in rows and columns, helping users view, analyze, and compare information. Automatically renders as a list on small screens and a table on large ones.',
-  category: 'Polaris web components',
+    'The table component displays data clearly in rows and columns, helping users view, analyze, and compare structured information. Use table to present datasets, product lists, order details, or any tabular content that benefits from organized rows and columns.' +
+    '\n\nTables automatically adapt to screen size, rendering as lists on small screens and tables on larger ones for optimal readability across devices.',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

package/src/docs/shared/components/TableBody.ts

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TableBody',
+  name: 'Table body',
   description:
-    'Define the main content area of a table, containing rows and cells that display data.',
-  category: 'Polaris web components',
+    'The table body component represents the main content area of a table, containing the data rows. Use table body as a child of table to structure your table data, with each table row within the body representing a single record or entry.' +
+    '\n\nTable body must contain table row components, which in turn contain table cell components for the actual data values.',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

package/src/docs/shared/components/TableCell.ts

@@ -1,9 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TableCell',
-  description: 'Display data within a cell in a table row.',
-  category: 'Polaris web components',
+  name: 'Table cell',
+  description:
+    'The table cell component represents a single data cell within a table row. Use table cell as a child of table row to display individual data values, with each cell corresponding to a column in the table.' +
+    '\n\nTable cell automatically inherits styling and alignment from its parent table structure and supports text content or other inline components.',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

package/src/docs/shared/components/TableHeader.ts

@@ -1,9 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TableHeader',
-  description: 'Display column names at the top of a table.',
-  category: 'Polaris web components',
+  name: 'Table header',
+  description:
+    'The table header component represents a single column header within a table header row. Use table header as a child of table header row to define column headings and optionally enable column sorting.' +
+    '\n\nTable header provides semantic meaning for screen readers and can include sorting controls when configured. Each header corresponds to a column in the table body.',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

package/src/docs/shared/components/TableHeaderRow.ts

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TableHeaderRow',
+  name: 'Table header row',
   description:
-    'Define a header row in a table, displaying column names and enabling sorting.',
-  category: 'Polaris web components',
+    'The table header row component represents the header row of a table, containing column headings. Use table header row as the first child of table (before table body) to define the table structure and provide column labels.' +
+    '\n\nTable header row must contain table header components for each column. These headers provide context for the data columns and can support sorting functionality.',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

package/src/docs/shared/components/TableRow.ts

@@ -1,9 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TableRow',
-  description: 'Display a row of data within the body of a table.',
-  category: 'Polaris web components',
+  name: 'Table row',
+  description:
+    'The table row component represents a single row of data within a table body. Use table row as a child of table body to structure individual records or entries in the table.' +
+    '\n\nTable row must contain table cell components, with each cell representing a data value for the corresponding column. The number of cells should match the number of headers in the table.',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

package/src/docs/shared/components/Text.ts

@@ -3,8 +3,9 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Text',
   description:
-    'Displays inline text with specific visual styles or tones. Use to emphasize or differentiate words or phrases within a Paragraph or other block-level components.',
-  category: 'Polaris web components',
+    'The text component displays inline text with specific visual styles or tones. Use text to emphasize or differentiate words or phrases within paragraphs or other block-level components, applying weight, color, or semantic styling.' +
+    '\n\nText supports multiple visual variants, alignment options, and line clamping for flexible inline typography control. For block-level text content, use [paragraph](/docs/api/{API_NAME}/{API_VERSION}/web-components/typography-and-content/paragraph).',
+  category: 'Web components',
   subCategory: 'Typography and content',
   related: [],
 };

package/src/docs/shared/components/TextArea.ts

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TextArea',
+  name: 'Text area',
   description:
-    'Collect longer text content from users with a multi-line input that expands automatically.',
-  category: 'Polaris web components',
+    'The text area component captures multi-line text input. Use it to collect descriptions, notes, comments, or other extended text content.' +
+    '\n\nThe component supports configurable height, character limits, and validation. For single-line text input, use [text field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/text-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/TextField.ts

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'TextField',
+  name: 'Text field',
   description:
-    'Lets users enter or edit text within a single-line input. Use to collect short, free-form information from users.',
-  category: 'Polaris web components',
+    'The text field component captures single-line text input. Use it to collect short, free-form information like names, titles, or identifiers.' +
+    '\n\nThe component supports various input configurations including placeholders, character limits, and validation. For multi-line text entry, use [text area](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/text-area). For specialized input types, use [email field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/email-field), [URL field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/url-field), [password field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/password-field), or [search field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/search-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/Thumbnail.ts

@@ -3,8 +3,9 @@ import {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Thumbnail',
   description:
-    'Display a small preview image representing content, products, or media.',
-  category: 'Polaris web components',
+    'The thumbnail component displays small preview images representing content, products, or media items. Use thumbnail to provide visual identification in lists, tables, or cards where space is constrained and quick recognition is important.' +
+    '\n\nThumbnails support multiple sizes, alt text for accessibility, and fallback states for missing images. For full-size images, use [image](/docs/api/{API_NAME}/{API_VERSION}/web-components/media-and-visuals/image). For user profile images, use [avatar](/docs/api/{API_NAME}/{API_VERSION}/web-components/media-and-visuals/avatar).',
+  category: 'Web components',
   subCategory: 'Media and visuals',
   related: [],
 };

package/src/docs/shared/components/Time.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Time',
   description:
     'Represents a specific point or duration in time. Use to display dates, times, or durations clearly and consistently. May include a machine-readable `datetime` attribute for improved accessibility and functionality.',
-  category: 'Polaris web components',
-  subCategory: 'Titles and text',
+  category: 'Web components',
+  subCategory: 'Typography and content',
   related: [],
 };
 

package/src/docs/shared/components/Tooltip.ts

@@ -3,9 +3,10 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Tooltip',
   description:
-    'Displays helpful information in a small overlay when users hover or focus on an element. Use to provide additional context without cluttering the interface.',
-  category: 'Polaris web components',
-  subCategory: 'Typography and content',
+    'The tooltip component displays helpful information in a small overlay when users hover over or focus on an element. Use tooltip to provide additional context, explain functionality, or clarify terms without cluttering the interface with permanent text.' +
+    '\n\nTooltips support keyboard accessibility, positioning options, and activation on both hover and focus for inclusive interaction patterns.',
+  category: 'Web components',
+  subCategory: 'Overlays',
   related: [],
 };
 

package/src/docs/shared/components/URLField.ts

@@ -1,10 +1,11 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'URLField',
+  name: 'URL field',
   description:
-    'Collect URLs from users with built-in formatting and validation.',
-  category: 'Polaris web components',
+    'The URL field component collects URLs from users with built-in formatting and validation. Use URL field for website addresses, link destinations, or any URL input to provide URL-specific keyboard layouts and automatic validation.' +
+    '\n\nURL fields support protocol prefixing, validation, and help text to guide users toward entering properly formatted web addresses. For general text input, use [text field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/text-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/UnorderedList.ts

@@ -1,11 +1,12 @@
 import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 
 const data: SharedReferenceEntityTemplateSchema = {
-  name: 'UnorderedList',
+  name: 'Unordered list',
   description:
-    'Displays a bulleted list of related items. Use to present collections of items or options where the sequence isn’t critical.',
-  category: 'Polaris web components',
-  subCategory: 'Layout and structure',
+    "The unordered list component displays a bulleted list of related items where sequence isn't critical. Use unordered list to present collections of features, options, requirements, or any group of items where order doesn't affect meaning." +
+    '\n\nUnordered lists automatically add bullet points and support nested lists for hierarchical content organization. For sequential items where order is important, use [ordered list](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/ordered-list).',
+  category: 'Web components',
+  subCategory: 'Typography and content',
   related: [],
 };
 

package/src/extension.ts

@@ -1,10 +1,31 @@
+/**
+ * Defines the structure of a render extension, which displays UI in the Shopify admin.
+ */
 export interface RenderExtension<Api, ComponentsSet extends string> {
+  /**
+   * The API object providing access to extension capabilities, data, and methods. The specific API type depends on the extension target and determines what functionality is available to your extension, such as authentication, storage, data access, and GraphQL querying.
+   */
   api: Api;
+  /**
+   * The set of UI components available for rendering your extension. This defines which Polaris components and custom components can be used to build your extension's interface. The available components vary by extension target.
+   */
   components: ComponentsSet;
+  /**
+   * The render function output. Your extension's render function should return void or a Promise that resolves to void. Use this to perform any necessary setup, rendering, or async operations when your extension loads.
+   */
   output: void | Promise<void>;
 }
 
+/**
+ * Defines the structure of a runnable extension, which executes logic and returns data without rendering UI.
+ */
 export interface RunnableExtension<Api, Output> {
+  /**
+   * The API object providing access to extension capabilities and methods. The specific API type depends on the extension target and determines what functionality is available to your extension.
+   */
   api: Api;
+  /**
+   * The function output. Your extension function should return the expected output type or a Promise that resolves to that type. The output type is determined by your specific extension target and use case.
+   */
   output: Output | Promise<Output>;
 }

package/src/shared.ts

@@ -1,5 +1,5 @@
 /**
- * Union of supported API versions
+ * The supported GraphQL Admin API versions. Use this to specify which API version your GraphQL queries should execute against. Each version includes specific features, bug fixes, and breaking changes. The `unstable` version provides access to the latest features but may change without notice.
  */
 export type ApiVersion =
   | '2023-04'
@@ -851,8 +851,9 @@ export type CountryCode =
 
 export interface Country {
   /**
-   * The ISO-3166-1 code for this country.
-   * @see https://www.iso.org/iso-3166-country-codes.html
+   * The two-letter country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. This is the internationally recognized standard for representing countries and territories.
+   *
+   * @example 'CA' for Canada, 'US' for United States.
    */
   isoCode: CountryCode;
 }
@@ -922,8 +923,9 @@ export type StorefrontApiVersion =
 
 export interface Country {
   /**
-   * The ISO-3166-1 code for this country.
-   * @see https://www.iso.org/iso-3166-country-codes.html
+   * The two-letter country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. This is the internationally recognized standard for representing countries and territories.
+   *
+   * @example 'CA' for Canada, 'US' for United States.
    */
   isoCode: CountryCode;
 }

package/src/surfaces/admin/api/action/action.ts

@@ -4,25 +4,28 @@ import type {Data} from '../shared';
 import type {ResourcePickerApi} from '../resource-picker/resource-picker';
 import type {PickerApi} from '../picker/picker';
 
+/**
+ * The `ActionExtensionApi` object provides methods for action extensions that render in modal overlays. Access the following properties on the `ActionExtensionApi` object to interact with the current context, control the modal, and display picker dialogs.
+ */
 export interface ActionExtensionApi<ExtensionTarget extends AnyExtensionTarget>
   extends StandardApi<ExtensionTarget> {
   /**
-   * Closes the extension. Calling this method is equivalent to the merchant clicking the "x" in the corner of the overlay.
+   * Closes the extension modal. Use this when your extension completes its task or the merchant wants to exit. Equivalent to clicking the close button in the overlay corner.
    */
   close: () => void;
 
   /**
-   * Information about the currently viewed or selected items.
+   * An array of currently viewed or selected resource identifiers. Use this to access the IDs of items in the current context, such as selected products in an index page or the product being viewed on a details page. The available IDs depend on the extension target and user interactions.
    */
   data: Data;
 
   /**
-   * Renders the [Resource Picker](resource-picker), allowing users to select a resource for the extension to use as part of its flow.
+   * Opens the [Resource Picker](/docs/api/admin-extensions/{API_VERSION}/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
    */
   resourcePicker: ResourcePickerApi;
 
   /**
-   * Renders a custom [Picker](picker) dialog allowing users to select values from a list.
+   * Opens a custom [Picker](/docs/api/admin-extensions/{API_VERSION}/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
    */
   picker: PickerApi;
 }

package/src/surfaces/admin/api/action/examples/handle-errors.jsx

@@ -0,0 +1,47 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [error, setError] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  const handleFulfill = async () => {
+    setLoading(true);
+    setError(null);
+    
+    try {
+      const orderId = data.selected[0]?.id;
+      
+      const response = await fetch(`/api/orders/${orderId}/fulfill`, {
+        method: 'POST',
+      });
+      
+      const result = await response.json();
+      
+      if (!response.ok) {
+        throw new Error(result.error || 'Fulfillment failed');
+      }
+      
+      console.log('Order fulfilled:', result);
+      shopify.close();
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <s-admin-action title="Fulfill Order">
+      {error && <s-banner status="critical">{error}</s-banner>}
+      <s-button onClick={handleFulfill} disabled={loading}>
+        {loading ? 'Fulfilling...' : 'Fulfill Order'}
+      </s-button>
+    </s-admin-action>
+  );
+}

package/src/surfaces/admin/api/action/examples/process-selected-products.jsx

@@ -0,0 +1,33 @@
+import {render} from 'preact';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+
+  const handleProcess = async () => {
+    const productIds = data.selected.map((item) => item.id);
+
+    const response = await fetch('/api/bulk-process', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({productIds}),
+    });
+
+    if (response.ok) {
+      console.log('Products processed successfully');
+      shopify.close();
+    } else {
+      console.error('Failed to process products');
+    }
+  };
+
+  return (
+    <s-admin-action title="Bulk Process">
+      <s-text>Processing {data.selected.length} products</s-text>
+      <s-button onClick={handleProcess}>Process Products</s-button>
+    </s-admin-action>
+  );
+}

package/src/surfaces/admin/api/action/examples/select-additional-resources.jsx

@@ -0,0 +1,46 @@
+import {render} from 'preact';
+import {useState} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [selected, setSelected] = useState(null);
+
+  const currentProductId = data.selected[0]?.id;
+
+  const handleSelectProducts = async () => {
+    const selectedProducts = await shopify.resourcePicker({
+      type: 'product',
+      multiple: 5,
+      action: 'select',
+    });
+
+    if (selectedProducts) {
+      setSelected(selectedProducts);
+      
+      await fetch('/api/create-bundle', {
+        method: 'POST',
+        headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({
+          mainProduct: currentProductId,
+          components: selectedProducts.map((p) => p.id),
+        }),
+      });
+      
+      shopify.close();
+    }
+  };
+
+  return (
+    <s-admin-action title="Create Bundle">
+      <s-text>Main product: {currentProductId}</s-text>
+      <s-button onClick={handleSelectProducts}>
+        Select Component Products
+      </s-button>
+      {selected && <s-text>Selected {selected.length} products</s-text>}
+    </s-admin-action>
+  );
+}

package/src/surfaces/admin/api/block/block.ts

@@ -4,35 +4,41 @@ import type {Data} from '../shared';
 import type {ResourcePickerApi} from '../resource-picker/resource-picker';
 import type {PickerApi} from '../picker/picker';
 
+/**
+ * The `Navigation` object provides methods for navigating between extensions and admin pages.
+ */
 export interface Navigation {
   /**
-   * Navigate to a specific route.
+   * Navigates to a specific extension or admin route. Currently supports navigating from a block extension to an action extension on the same resource page.
    *
+   * @param url - The destination URL, typically in the format 'extension://extension-handle' for other extensions
    * @example navigation.navigate('extension://my-admin-action-extension-handle')
    */
   navigate: (url: string | URL) => void;
 }
 
+/**
+ * The `BlockExtensionApi` object provides methods for block extensions that render inline content on admin pages. Access the following properties on the `BlockExtensionApi` object to interact with the current context, navigate to other extensions, and display picker dialogs.
+ */
 export interface BlockExtensionApi<ExtensionTarget extends AnyExtensionTarget>
   extends StandardApi<ExtensionTarget> {
   /**
-   * Information about the currently viewed or selected items.
+   * An array of currently viewed or selected resource identifiers. Use this to access the IDs of items in the current context, such as selected products in an index page or the product being viewed on a details page. The available IDs depend on the extension target and user interactions.
    */
   data: Data;
 
   /**
-   * Provides methods to navigate to other features in the Admin. Currently, only navigation from an admin block to an admin action extension *on the same resource page* is supported.
-   * For example, you can navigate from an admin block on the product details page (`admin.product-details.block.render`) to an admin action on the product details page (`admin.product-details.action.render`).
+   * Navigates to other extensions or admin pages. Currently supports navigation from a block to an action extension on the same resource page. For example, navigate from a product details block (`admin.product-details.block.render`) to a product details action (`admin.product-details.action.render`).
    */
   navigation: Navigation;
 
   /**
-   * Renders the [Resource Picker](resource-picker), allowing users to select a resource for the extension to use as part of its flow.
+   * Opens the [Resource Picker API](/docs/api/admin-extensions/{API_VERSION}/target-apis/utility-apis/resource-picker-api) modal for selecting products, variants, or collections. Use this to let merchants choose resources that your extension needs to work with.
    */
   resourcePicker: ResourcePickerApi;
 
   /**
-   * Renders a custom [Picker](picker) dialog allowing users to select values from a list.
+   * Opens a custom [Picker API](/docs/api/admin-extensions/{API_VERSION}/target-apis/utility-apis/picker-api) dialog for selecting from a list of custom options. Use this when you need merchants to choose from app-specific data that isn't a standard Shopify resource.
    */
   picker: PickerApi;
 }

package/src/surfaces/admin/api/block/examples/display-product-info.jsx

@@ -0,0 +1,46 @@
+import {render} from 'preact';
+import {useState, useEffect} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [product, setProduct] = useState(null);
+
+  useEffect(() => {
+    const fetchProduct = async () => {
+      const productId = data.selected[0]?.id;
+
+      const {data: productData} = await shopify.query(
+        `query GetProduct($id: ID!) {
+          product(id: $id) {
+            title
+            totalInventory
+            status
+          }
+        }`,
+        {variables: {id: productId}},
+      );
+
+      setProduct(productData.product);
+    };
+
+    fetchProduct();
+  }, [data]);
+
+  return (
+    <s-admin-block heading="Product Information">
+      {product ? (
+        <>
+          <s-text>Title: {product.title}</s-text>
+          <s-text>Inventory: {product.totalInventory}</s-text>
+          <s-text>Status: {product.status}</s-text>
+        </>
+      ) : (
+        <s-spinner />
+      )}
+    </s-admin-block>
+  );
+}

package/src/surfaces/admin/api/block/examples/navigate-to-action.jsx

@@ -0,0 +1,50 @@
+import {render} from 'preact';
+import {useState, useEffect} from 'preact/hooks';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  const {data} = shopify;
+  const [eligible, setEligible] = useState(false);
+  const [checking, setChecking] = useState(true);
+
+  useEffect(() => {
+    const checkEligibility = async () => {
+      const productId = data.selected[0]?.id;
+
+      if (!productId) {
+        setChecking(false);
+        return;
+      }
+
+      const response = await fetch(`/api/products/${productId}/check-eligibility`, {
+        method: 'GET',
+        headers: {'Content-Type': 'application/json'},
+      });
+
+      const {eligible} = await response.json();
+      setEligible(eligible);
+      setChecking(false);
+    };
+
+    checkEligibility();
+  }, [data]);
+
+  const handleNavigate = () => {
+    shopify.navigation.navigate('extension://my-product-action-extension-handle');
+  };
+
+  return (
+    <s-admin-block heading="Advanced Actions">
+      {checking ? (
+        <s-spinner />
+      ) : eligible ? (
+        <s-button onClick={handleNavigate}>Launch Advanced Workflow</s-button>
+      ) : (
+        <s-text>Product not eligible for advanced actions</s-text>
+      )}
+    </s-admin-block>
+  );
+}