Merge pull request #2407 from Shopify/njo/pos-print

Add PrintApi and PrintPreview to point-of-sale

packages/ui-extensions-react/src/surfaces/point-of-sale.ts

@@ -37,6 +37,7 @@ export type {
   PinLength,
   PinPadActionType,
   PinPadProps,
+  PrintPreviewProps,
   RadioButtonListProps,
   ScreenPresentationProps,
   SecondaryActionProps,

packages/ui-extensions-react/src/surfaces/point-of-sale/components.ts

@@ -14,6 +14,7 @@ export {List} from './components/List/List';
 export {Navigator} from './components/Navigator/Navigator';
 export {NumberField} from './components/NumberField/NumberField';
 export {PinPad} from './components/PinPad/PinPad';
+export {PrintPreview} from './components/PrintPreview/PrintPreview';
 export {POSBlock} from './components/POSBlock/POSBlock';
 export {POSBlockRow} from './components/POSBlock/POSBlockRow';
 export {RadioButtonList} from './components/RadioButtonList/RadioButtonList';

packages/ui-extensions-react/src/surfaces/point-of-sale/components/PrintPreview/PrintPreview.ts

@@ -0,0 +1,10 @@
+import {
+  PrintPreview as BasePrintPreview,
+  PrintPreviewProps,
+} from '@shopify/ui-extensions/point-of-sale';
+import {createRemoteReactComponent} from '@remote-ui/react';
+
+export const PrintPreview = createRemoteReactComponent<
+  typeof BasePrintPreview,
+  PrintPreviewProps
+>(BasePrintPreview);

packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/print-api.doc.ts

@@ -0,0 +1,42 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {generateCodeBlock} from '../helpers/generateCodeBlock';
+
+const generateCodeBlockForPrintApi = (title: string, fileName: string) =>
+  generateCodeBlock(title, 'print-api', fileName);
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Print API',
+  description: `
+The Print API provides access to printing functionality.
+`,
+  isVisualComponent: false,
+  type: 'APIs',
+  definitions: [
+    {
+      title: 'PrintApi',
+      description: '',
+      type: 'PrintApiContent',
+    },
+  ],
+  category: 'APIs',
+  related: [
+    {
+      name: 'PrintPreview Component',
+      subtitle: 'See how to use the Print API with a PrintPreview.',
+      url: '/api/pos-ui-extensions/components/printpreview',
+    },
+  ],
+  examples: {
+    description: 'Examples of using the Print API',
+    examples: [
+      {
+        codeblock: generateCodeBlockForPrintApi(
+          'Print directly from the tile',
+          'print',
+        ),
+      },
+    ],
+  },
+};
+
+export default data;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/components/PrintPreview.doc.ts

@@ -0,0 +1,35 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+import {generateCodeBlock} from '../helpers/generateCodeBlock';
+
+const generateCodeBlockForPrintPreview = (title: string, fileName: string) =>
+  generateCodeBlock(title, 'print-preview', fileName);
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'PrintPreview',
+  description: 'Renders a `PrintPreview`.',
+  isVisualComponent: true,
+  type: 'component',
+  definitions: [
+    {
+      title: 'PrintPreview',
+      description: '',
+      type: 'PrintPreviewProps',
+    },
+  ],
+  category: 'Components',
+  related: [
+    {
+      name: 'Print API',
+      subtitle: 'See how to use the Print API.',
+      url: '/api/pos-ui-extensions/apis/print-api',
+    },
+  ],
+  defaultExample: {
+    codeblock: generateCodeBlockForPrintPreview(
+      'Render a PrintPreview and a button for printing',
+      'default.example',
+    ),
+  },
+};
+
+export default data;

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/print-api/print.ts

@@ -0,0 +1,14 @@
+import {Tile, extension} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension('pos.home.tile.render', (root, api) => {
+  const tile = root.createComponent(Tile, {
+    title: 'My app',
+    subtitle: 'Hello world!',
+    enabled: true,
+    onPress: () => {
+      api.print.print('/documents/test-print');
+    },
+  });
+
+  root.append(tile);
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/print-api/print.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import {
+  Tile,
+  reactExtension,
+  useApi,
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const TileComponent = () => {
+  const api = useApi();
+  return (
+    <Tile
+      title="My app"
+      subtitle="Hello world!"
+      onPress={() => {
+        api.print.print('documents/test-print');
+      }}
+      enabled
+    />
+  );
+};
+
+export default reactExtension('pos.home.tile.render', () => {
+  return <TileComponent />;
+});

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/print-preview/default.example.ts

@@ -0,0 +1,38 @@
+import {
+  Button,
+  PrintPreview,
+  Screen,
+  extension,
+} from '@shopify/ui-extensions/point-of-sale';
+
+export default extension(
+  'pos.home.modal.render',
+  (root, api) => {
+    const homeScreen = root.createComponent(
+      Screen,
+      {
+        name: 'Home',
+        title: 'Home',
+      },
+    );
+
+    const printButton = root.createComponent(
+      Button,
+      {
+        title: 'Print',
+        onPress: api.print.print,
+      },
+    );
+
+    const printPreview = root.createComponent(
+      PrintPreview,
+      {
+        src: '/documents/test-print',
+      },
+    );
+
+    homeScreen.append(printPreview);
+
+    root.append(homeScreen);
+  },
+);

packages/ui-extensions/docs/surfaces/point-of-sale/reference/examples/print-preview/default.example.tsx

@@ -0,0 +1,27 @@
+import React from 'react';
+
+import {
+  Screen,
+  reactExtension,
+  Button,
+  useApi,
+} from '@shopify/ui-extensions-react/point-of-sale';
+
+const Modal = () => {
+  const api = useApi<'pos.home.modal.render'>();
+
+  return (
+    <Screen name="Home" title="Home">
+      <Button
+        title="Print"
+        onPress={api.print.print}
+      />
+      <PrintPreview src="/documents/test-print" />
+    </Screen>
+  );
+};
+
+export default reactExtension(
+  'pos.home.modal.render',
+  () => <Modal />,
+);

packages/ui-extensions/docs/surfaces/point-of-sale/staticPages/pages/versions.doc.ts

@@ -49,6 +49,7 @@ Refer to the [migration guide](/docs/api/pos-ui-extensions/migrating) for more i
 ### Features
 
 - Removed \`customValidator\` prop from the [FormattedTextField](/docs/api/pos-ui-extensions/apis/formatted-text-field) component.
+- Added [PrintApi](/docs/api/pos-ui-extensions/apis/print-api) and a [PrintPreview](/docs/api/pos-ui-extensions/components/printpreview) component.
       `,
     },
     {

packages/ui-extensions/src/surfaces/point-of-sale/api.ts

@@ -44,6 +44,8 @@ export type {
   DraftOrderApiContent,
 } from './api/draft-order-api/draft-order-api';
 
+export type {PrintApi, PrintApiContent} from './api/print-api/print-api';
+
 export type {
   PaginationParams,
   ProductSortType,

packages/ui-extensions/src/surfaces/point-of-sale/api/print-api/print-api.ts

@@ -0,0 +1,16 @@
+/**
+ * Access the print API for printing functionality
+ */
+export interface PrintApiContent {
+  /** Trigger a print dialog
+   * @param src the source to print. Omit to use the current PrintPreview contents.
+   */
+  print(src?: string): void;
+}
+
+/**
+ * Interface for printing
+ */
+export interface PrintApi {
+  print: PrintApiContent;
+}

packages/ui-extensions/src/surfaces/point-of-sale/api/standard/standard-api.ts

@@ -1,15 +1,17 @@
-import type {ConnectivityApi} from '../connectivity-api/connectivity-api';
-import type {DeviceApi} from '../device-api/device-api';
-import type {LocaleApi} from '../locale-api/locale-api';
-import type {SessionApi} from '../session-api/session-api';
-import type {ToastApi} from '../toast-api/toast-api';
-import type {ProductSearchApi} from '../product-search-api/product-search-api';
+import {ConnectivityApi} from '../connectivity-api/connectivity-api';
+import {DeviceApi} from '../device-api/device-api';
+import {LocaleApi} from '../locale-api/locale-api';
+import {SessionApi} from '../session-api/session-api';
+import {ToastApi} from '../toast-api/toast-api';
+import {ProductSearchApi} from '../product-search-api/product-search-api';
+import {PrintApi} from '../print-api/print-api';
 
 export type StandardApi<T> = {[key: string]: any} & {
   extensionPoint: T;
 } & LocaleApi &
   ToastApi &
   SessionApi &
+  PrintApi &
   ProductSearchApi &
   DeviceApi &
   ConnectivityApi;

packages/ui-extensions/src/surfaces/point-of-sale/components.ts

@@ -54,6 +54,8 @@ export {POSBlock} from './components/POSBlock/POSBlock';
 export type {POSBlockProps} from './components/POSBlock/POSBlock';
 export {POSBlockRow} from './components/POSBlock/POSBlockRow';
 export type {POSBlockRowProps} from './components/POSBlock/POSBlockRow';
+export {PrintPreview} from './components/PrintPreview/PrintPreview';
+export type {PrintPreviewProps} from './components/PrintPreview/PrintPreview';
 export {RadioButtonList} from './components/RadioButtonList/RadioButtonList';
 export type {RadioButtonListProps} from './components/RadioButtonList/RadioButtonList';
 export {Screen} from './components/Screen/Screen';

packages/ui-extensions/src/surfaces/point-of-sale/components/PrintPreview/PrintPreview.ts

@@ -0,0 +1,13 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+export interface PrintPreviewProps {
+  /**
+   * The source to print.
+   */
+  src: string;
+}
+
+export const PrintPreview = createRemoteComponent<
+  'PrintPreview',
+  PrintPreviewProps
+>('PrintPreview');