@automattic/jetpack-ai-client 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.3] - 2023-08-09
+### Added
+- AI Client: Introduce disabled prop in AI Control. [#32326]
+- AI Control: Add guideline message. [#32358]
+
+### Changed
+- AI Client: handle token fetching errors by dispatching an event from the SuggestionsEventSource class. [#32350]
+- AI Client: tweak layout and styles to make AI Control mobile friendly. [#32362]
+- AI Control: clean up props. [#32360]
+- Updated package dependencies. [#32166]
+
+### Fixed
+- AI Client: fix TS type definition issue [#32330]
+
+## [0.1.2] - 2023-08-07
+### Added
+- AI Assistant: Add options parameter to request function on useAiSuggestions hook [#32198]
+- AI Client: add @wordpress/compose dependency [#32228]
+- AI Client: Add clear button in AI Control component [#32274]
+- AI Client: Add keyboard shortcut to AIControl [#32239]
+- AI Client: add onError() response support [#32223]
+- AI Client: Export types [#32209]
+- AI Client: Start supporting request options on requestSuggestion callback. [#32303]
+- AI Control: introduce AiStatusIndicator component [#32258]
+
+### Changed
+- AI Client: complete/update/improve doc [#32311]
+- AI Client: rename the prop name of the requesting state of the AiStatusIndicator component [#32279]
+
+### Fixed
+- AI Client: Fix wrong disabled state condition. [#32210]
+
 ## [0.1.1] - 2023-08-01
 ### Added
 - Add AI Client icon components [#32079]
@@ -36,4 +68,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated package dependencies. [#31659]
 - Updated package dependencies. [#31785]
 
+[0.1.3]: https://github.com/Automattic/jetpack-ai-client/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/Automattic/jetpack-ai-client/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/Automattic/jetpack-ai-client/compare/v0.1.0...v0.1.1

package/README.md

@@ -10,118 +10,40 @@ To install the Jetpack AI Client, clone the repository to your local machine and
 npm install @automattic/jetpack-ai-client
 ```
 
-## Usage
+## Libraries & Components
 
-### Example
+### Requesting
 
-```
-import { requestCompletion } from '@automattic/jetpack-ai-client';
-
-const MyComp = ( props ) => {
-  const [ completion, setCompletion ] = useState( '' );
-
-  const newHaiku = async () => {
-    const eventSource = await requestCompletion( 'Write a haiku about WordPress' );
-      eventSource.addEventListener( 'suggestion',  answer => setCompletion( answer.detail ) );
-      eventSource.addEventListener( 'done', event => {
-        console.log( "Full completion", event.detail );
-      } );
-
-      eventSource.addEventListener( 'suggestion', event => {
-        console.log( "Received so far", event.detail );
-      } );
-
-      eventSource.addEventListener( 'error_quota_exceeded', event => {
-        console.log( "You reached the AI query quota for your current plan.", event.detail );
-      } );
-  };
-
-  return (
-    <div>
-      <div> { completion } </div>
-      <button onClick={ newHaiku }>Get new Haiku</button>
-    </div>
-  )
-};
-```
-
-### Requesting a Completion from the Jetpack AI API
-
-You can request a completion from the Jetpack AI API using the `requestCompletion` function. This function takes a prompt and optionally a post ID as parameters and returns an instance of `SuggestionsEventSource`.
-
-```
-import { requestCompletion } from '@automattic/jetpack-ai-client';
-
-// postId is the post where the request is being triggered
-// It's only used for loggin purposes and can be omitted.
-const postId = 123;
-const eventSource = requestCompletion( 'A haiku', postId ))
-
-eventSource.addEventListener('done', event => {
-  console.log( "Full completion", event.detail );
-} );
-
-eventSource.addEventListener('suggestion', event => {
-  console.log( "Received so far", event.detail );
-} );
-```
+#### [askQuestion](./src/ask-question/Readme.md) helper
+Async function that sends a question and optional configurations, retrieves a JWT token, and returns a [SuggestionsEventSource](./src/suggestions-event-source/Readme.md) instance.
 
-### Requesting Images from the Jetpack AI API
+#### [SuggestionsEventSouce](./src/suggestions-event-source/Readme.md) Class
 
-You can fetch images from Jetpack AI using the `requestImages` function. This function takes a prompt and a post ID as parameters and returns a promise that resolves to an array of base64 encoded images.
+Class that connects to an AI model to receive and emit suggestion streams, using EventTarget for handling data chunks.
 
-```
-import { requestImages } from '@automattic/jetpack-ai-client';
-
-requestImages( 'a flower', postId )
-  .then( images => {
-    document.getElementById("imgid").src= image[0]
-  } )
-  .catch( error => {
-    // Handle the error
-  } );
-```
-
-### Using the SuggestionsEventSource Class
-
-The `SuggestionsEventSource` class is a wrapper around `EventSource` that emits events for each chunk of data received, when the stream is closed, and when a full suggestion has been received.
-
-You shouldn't need to instantiate this class. You get one of these by calling `requestCompletion()`.
+#### [useAiSuggestions](./src/hooks/use-ai-suggestions/Readme.md) hook
 
-```
-import { requestCompletion } from '@automattic/jetpack-ai-client';
+A custom React hook that obtains suggestions from an AI by hitting a specific query endpoint.
 
-const eventSource = new SuggestionsEventSource( url );
+#### [JWT](./src/jwt/Readme.md) helper
 
-eventSource.addEventListener( 'done', event => {
-  console.log( "Full completion", event.detail );
-} );
+Library to manage JWT tokens for Jetpack AI across various site types, handling acquisition, caching in localStorage, expiration, and customization of request options.
 
-eventSource.addEventListener( 'suggestion', event => {
-  console.log( "Received so far", event.detail );
-} );
-```
+#### [Data Flow](./src/data-flow/Readme.md) implementation
 
-### Requesting a Token from the Jetpack Site
+Data Flow offers a streamlined way to manage an AI Assistant's state and functionality within a React app, using React context, HOCs, and custom hooks to handle suggestions, errors, and requests.
 
-You can request a token from the Jetpack site using the `requestCompletionAuthToken` function. This function returns a promise that resolves to an object containing the token and the blogId.
+### [Components](./src/components/)
 
-This function behaves properly whether it's called from a Jetpack environment or a WordPress.com one.
+#### [AIControl](./src/components/ai-control/Readme.md)
 
-```
-import { requestCompletionAuthToken } from '@automattic/jetpack-ai-client';
-
-requestCompletionAuthToken()
-  .then(tokenData => {
-    // Do something with the token data
-  })
-  .catch(error => {
-    // Handle the error
-  });
-```
+#### [AiStatusIndicator](./src/components/ai-status-indicator/)
 
+### [Icons](./src/icons/Readme.md)
 ## Contribute
 
+React components useful for when you need to create some UI implementations.
+
 We welcome contributions from the community. Please submit your pull requests on the GitHub repository.
 
 ## Get Help

package/index.ts

@@ -24,3 +24,8 @@ export { default as AIControl } from './src/components/ai-control';
  * Contexts
  */
 export * from './src/data-flow';
+
+/*
+ * Types
+ */
+export * from './src/types';

package/package.json

@@ -1,7 +1,7 @@
 {
 	"private": false,
 	"name": "@automattic/jetpack-ai-client",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"description": "A JS client for consuming Jetpack AI services",
 	"homepage": "https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/ai-client/#readme",
 	"bugs": {
@@ -21,6 +21,8 @@
 	},
 	"type": "module",
 	"devDependencies": {
+		"@storybook/addon-actions": "7.1.0",
+		"@storybook/blocks": "7.1.0",
 		"@storybook/react": "7.1.0",
 		"jest": "^29.6.2",
 		"jest-environment-jsdom": "29.5.0",
@@ -31,15 +33,16 @@
 	},
 	"dependencies": {
 		"@automattic/jetpack-connection": "workspace:*",
-		"@automattic/jetpack-shared-extension-utils": "^0.10.9",
+		"@automattic/jetpack-shared-extension-utils": "^0.11.1",
 		"@microsoft/fetch-event-source": "2.0.1",
-		"@wordpress/api-fetch": "6.34.0",
-		"@wordpress/block-editor": "12.5.0",
-		"@wordpress/components": "25.3.0",
-		"@wordpress/data": "9.7.0",
-		"@wordpress/element": "5.14.0",
-		"@wordpress/i18n": "4.37.0",
-		"@wordpress/icons": "9.28.0",
+		"@wordpress/api-fetch": "6.35.0",
+		"@wordpress/block-editor": "12.6.0",
+		"@wordpress/components": "25.4.0",
+		"@wordpress/compose": "6.15.0",
+		"@wordpress/data": "9.8.0",
+		"@wordpress/element": "5.15.0",
+		"@wordpress/i18n": "4.38.0",
+		"@wordpress/icons": "9.29.0",
 		"classnames": "2.3.2",
 		"debug": "4.3.4",
 		"react": "18.2.0",

package/src/ask-question/index.ts

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import debugFactory from 'debug';
-import requestJwt from '../jwt';
 import SuggestionsEventSource from '../suggestions-event-source';
 /*
  * Types & constants
@@ -62,11 +61,8 @@ export default async function askQuestion(
 ): Promise< SuggestionsEventSource > {
 	debug( 'Asking question: %o. options: %o', question, { postId, fromCache, feature, functions } );
 
-	const { token } = await requestJwt();
-
 	return new SuggestionsEventSource( {
 		question,
-		token,
 		options: { postId, feature, fromCache, functions },
 	} );
 }

package/src/components/ai-control/Readme.md

@@ -0,0 +1,29 @@
+### AIControl
+
+#### Properties
+
+- `disabled` (**boolean**) (Optional): Disables the ai control. Default value is `false`.
+- `value` (**string**): Current input value. Default value is `''`.
+- `placeholder` (**string**) (Optional): Placeholder text for the input field. Default value is `''`.
+- `showAccept` (**boolean**) (Optional): Determines if the accept button is shown. Default value is `false`.
+- `acceptLabel` (**string**) (Optional): Label text for the accept button. Default value is `'Accept'`.
+- `showButtonsLabel` (**boolean**) (Optional): Determines if button labels are shown. Default value is `true`.
+- `isOpaque` (**boolean**) (Optional): Controls the opacity of the component. Default value is `false`.
+- `state` (**RequestingStateProp**) (Optional): Determines the state of the component. Default value is `'init'`.
+- `onChange` (**Function**) (Optional): Handler for input change. Default action is no operation.
+- `onSend` (**Function**) (Optional): Handler to send a request. Default action is no operation.
+- `onStop` (**Function**) (Optional): Handler to stop a request. Default action is no operation.
+- `onAccept` (**Function**) (Optional): Handler to accept the input. Default action is no operation.
+
+#### Example Usage
+
+```jsx
+<AIControl
+  value="Type here"
+  placeholder="Placeholder text"
+  onChange={ handleChange }
+  onSend={ handleSend }
+  onStop={ handleStop }
+  onAccept={ handleAccept }
+/>
+```

package/src/components/ai-control/index.tsx

@@ -2,7 +2,8 @@
  * External dependencies
  */
 import { PlainText } from '@wordpress/block-editor';
-import { Button, Spinner } from '@wordpress/components';
+import { Button } from '@wordpress/components';
+import { useKeyboardShortcut } from '@wordpress/compose';
 import { useRef } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import { Icon, closeSmall, check, arrowUp } from '@wordpress/icons';
@@ -10,8 +11,13 @@ import classNames from 'classnames';
 /**
  * Internal dependencies
  */
-import { aiAssistantIcon } from '../../icons';
 import './style.scss';
+import AiStatusIndicator from '../ai-status-indicator';
+import { GuidelineMessage } from './message';
+/**
+ * Types
+ */
+import type { RequestingStateProp } from '../../types';
 
 // eslint-disable-next-line @typescript-eslint/no-empty-function
 const noop = () => {};
@@ -20,13 +26,14 @@ const noop = () => {};
  * AI Control component.
  *
  * @param {object} props - component props
- * @param {boolean} props.loading - loading state
+ * @param {boolean} props.disabled - is disabled
  * @param {string} props.value - input value
  * @param {string} props.placeholder - input placeholder
  * @param {boolean} props.showAccept - show accept button
  * @param {string} props.acceptLabel - accept button label
  * @param {boolean} props.showButtonsLabel - show buttons label
  * @param {boolean} props.isOpaque - is opaque
+ * @param {string} props.state - requesting state
  * @param {Function} props.onChange - input change handler
  * @param {Function} props.onSend - send request handler
  * @param {Function} props.onStop - stop request handler
@@ -34,31 +41,62 @@ const noop = () => {};
  * @returns {object} - AI Control component
  */
 export default function AIControl( {
-	loading = false,
+	disabled = false,
 	value = '',
 	placeholder = '',
 	showAccept = false,
 	acceptLabel = __( 'Accept', 'jetpack-ai-client' ),
 	showButtonsLabel = true,
 	isOpaque = false,
+	state = 'init',
 	onChange = noop,
 	onSend = noop,
 	onStop = noop,
 	onAccept = noop,
 }: {
-	loading?: boolean;
+	disabled?: boolean;
 	value: string;
 	placeholder?: string;
 	showAccept?: boolean;
 	acceptLabel?: string;
 	showButtonsLabel?: boolean;
 	isOpaque?: boolean;
-	onChange: ( newValue: string ) => void;
-	onSend: ( currentValue: string ) => void;
-	onStop: () => void;
-	onAccept: () => void;
+	state?: RequestingStateProp;
+	onChange?: ( newValue: string ) => void;
+	onSend?: ( currentValue: string ) => void;
+	onStop?: () => void;
+	onAccept?: () => void;
 } ) {
 	const promptUserInputRef = useRef( null );
+	const loading = state === 'requesting' || state === 'suggesting';
+	const showGuideLine = ! ( loading || disabled || value?.length || isOpaque );
+
+	useKeyboardShortcut(
+		'mod+enter',
+		() => {
+			if ( showAccept ) {
+				onAccept?.();
+			}
+		},
+		{
+			target: promptUserInputRef,
+		}
+	);
+
+	useKeyboardShortcut(
+		'enter',
+		e => {
+			e.preventDefault();
+			onSend?.( value );
+		},
+		{
+			target: promptUserInputRef,
+		}
+	);
+
+	const actionButtonClasses = classNames( 'jetpack-components-ai-control__controls-prompt_button', {
+		'has-label': showButtonsLabel,
+	} );
 
 	return (
 		<div className="jetpack-components-ai-control__container">
@@ -67,64 +105,67 @@ export default function AIControl( {
 					'is-opaque': isOpaque,
 				} ) }
 			>
-				<div className="jetpack-components-ai-controlton__icon">
-					{ loading ? (
-						<Spinner className="input-spinner" />
+				<AiStatusIndicator state={ state } />
+
+				<div className="jetpack-components-ai-control__input-wrapper">
+					<PlainText
+						value={ value }
+						onChange={ onChange }
+						placeholder={ placeholder }
+						className="jetpack-components-ai-control__input"
+						disabled={ loading || disabled }
+						ref={ promptUserInputRef }
+					/>
+				</div>
+
+				{ value?.length > 0 && (
+					<Button
+						icon={ closeSmall }
+						className="jetpack-components-ai-control__clear"
+						onClick={ () => onChange( '' ) }
+					/>
+				) }
+
+				<div className="jetpack-components-ai-control__controls-prompt_button_wrapper">
+					{ ! loading ? (
+						<Button
+							className={ actionButtonClasses }
+							onClick={ () => onSend( value ) }
+							isSmall={ true }
+							disabled={ ! value?.length || disabled }
+							label={ __( 'Send request', 'jetpack-ai-client' ) }
+						>
+							<Icon icon={ arrowUp } />
+							{ showButtonsLabel && __( 'Send', 'jetpack-ai-client' ) }
+						</Button>
 					) : (
-						<Icon className="input-icon" icon={ aiAssistantIcon } size={ 24 } />
+						<Button
+							className={ actionButtonClasses }
+							onClick={ onStop }
+							isSmall={ true }
+							label={ __( 'Stop request', 'jetpack-ai-client' ) }
+						>
+							<Icon icon={ closeSmall } />
+							{ showButtonsLabel && __( 'Stop', 'jetpack-ai-client' ) }
+						</Button>
 					) }
 				</div>
 
-				<PlainText
-					value={ value }
-					onChange={ onChange }
-					placeholder={ placeholder }
-					className="jetpack-components-ai-control__input"
-					disabled={ loading }
-					ref={ promptUserInputRef }
-				/>
-
-				<div className="jetpack-components-ai-control__controls">
+				{ showAccept && (
 					<div className="jetpack-components-ai-control__controls-prompt_button_wrapper">
-						{ ! loading ? (
-							<Button
-								className="jetpack-components-ai-control__controls-prompt_button"
-								onClick={ () => onSend( value ) }
-								isSmall={ true }
-								disabled={ value?.length }
-								label={ __( 'Send request', 'jetpack-ai-client' ) }
-							>
-								<Icon icon={ arrowUp } />
-								{ showButtonsLabel && __( 'Send', 'jetpack-ai-client' ) }
-							</Button>
-						) : (
-							<Button
-								className="jetpack-components-ai-control__controls-prompt_button"
-								onClick={ onStop }
-								isSmall={ true }
-								label={ __( 'Stop request', 'jetpack-ai-client' ) }
-							>
-								<Icon icon={ closeSmall } />
-								{ showButtonsLabel && __( 'Stop', 'jetpack-ai-client' ) }
-							</Button>
-						) }
+						<Button
+							className={ actionButtonClasses }
+							onClick={ onAccept }
+							isSmall={ true }
+							label={ acceptLabel }
+						>
+							<Icon icon={ check } />
+							{ showButtonsLabel && acceptLabel }
+						</Button>
 					</div>
-
-					{ showAccept && (
-						<div className="jetpack-components-ai-control__controls-prompt_button_wrapper">
-							<Button
-								className="jetpack-components-ai-control__controls-prompt_button"
-								onClick={ onAccept }
-								isSmall={ true }
-								label={ acceptLabel }
-							>
-								<Icon icon={ check } />
-								{ acceptLabel }
-							</Button>
-						</div>
-					) }
-				</div>
+				) }
 			</div>
+			{ showGuideLine && <GuidelineMessage /> }
 		</div>
 	);
 }

package/src/components/ai-control/message.tsx

@@ -0,0 +1,86 @@
+/**
+ * External dependencies
+ */
+import { ExternalLink } from '@wordpress/components';
+import { createInterpolateElement } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
+import {
+	Icon,
+	warning,
+	info,
+	cancelCircleFilled as error,
+	check as success,
+} from '@wordpress/icons';
+/**
+ * Types
+ */
+import type React from 'react';
+
+import './style.scss';
+
+export const MESSAGE_SEVERITY_WARNING = 'warning';
+export const MESSAGE_SEVERITY_ERROR = 'error';
+export const MESSAGE_SEVERITY_SUCCESS = 'success';
+export const MESSAGE_SEVERITY_INFO = 'info';
+
+const messageSeverityTypes = [
+	MESSAGE_SEVERITY_WARNING,
+	MESSAGE_SEVERITY_ERROR,
+	MESSAGE_SEVERITY_SUCCESS,
+	MESSAGE_SEVERITY_INFO,
+] as const;
+
+export type MessageSeverityProp = ( typeof messageSeverityTypes )[ number ] | null;
+
+export type MessageProps = {
+	icon?: React.ReactNode;
+	children: React.ReactNode;
+	severity: MessageSeverityProp;
+};
+
+const messageIconsMap = {
+	[ MESSAGE_SEVERITY_WARNING ]: warning,
+	[ MESSAGE_SEVERITY_ERROR ]: error,
+	[ MESSAGE_SEVERITY_SUCCESS ]: success,
+	[ MESSAGE_SEVERITY_INFO ]: info,
+};
+
+/**
+ * React component to render a block message.
+ *
+ * @param {MessageProps} props - Component props.
+ * @returns {React.ReactElement }    Banner component.
+ */
+export default function Message( {
+	severity = null,
+	icon = null,
+	children,
+}: MessageProps ): React.ReactElement {
+	return (
+		<div className="jetpack-ai-assistant__message">
+			{ ( severity || icon ) && <Icon icon={ messageIconsMap[ severity ] || icon } /> }
+			<div className="jetpack-ai-assistant__message-content">{ children }</div>
+		</div>
+	);
+}
+
+/**
+ * React component to render a guideline message.
+ *
+ * @returns {React.ReactElement } - Message component.
+ */
+export function GuidelineMessage(): React.ReactElement {
+	return (
+		<Message severity={ MESSAGE_SEVERITY_INFO }>
+			{ createInterpolateElement(
+				__(
+					'AI-generated content could be inaccurate or biased. <link>Learn more</link>',
+					'jetpack-ai-client'
+				),
+				{
+					link: <ExternalLink href="https://automattic.com/ai-guidelines" />,
+				}
+			) }
+		</Message>
+	);
+}

package/src/components/ai-control/stories/index.stories.tsx

@@ -1,11 +1,13 @@
 /**
  * External dependencies
  */
+import { action } from '@storybook/addon-actions';
 import { useState } from '@wordpress/element';
 import React from 'react';
 /**
  * Internal dependencies
  */
+import { REQUESTING_STATES } from '../../../types';
 import AIControl from '../index';
 /**
  * Types
@@ -15,7 +17,26 @@ import type { Meta } from '@storybook/react';
 export default {
 	title: 'JS Packages/AI Client/AI Control',
 	component: AIControl,
-	parameters: {},
+	decorators: [
+		Story => (
+			<div style={ { backgroundColor: 'white' } }>
+				<Story />
+			</div>
+		),
+	],
+	argTypes: {
+		requestingState: {
+			control: {
+				type: 'select',
+			},
+			options: REQUESTING_STATES,
+		},
+	},
+	parameters: {
+		controls: {
+			exclude: /on[A-Z].*/,
+		},
+	},
 } as Meta< typeof AIControl >;
 
 const Template = args => {
@@ -33,9 +54,14 @@ const DefaultArgs = {
 	loading: false,
 	isOpaque: false,
 	placeholder: '',
+	requestingState: 'init',
 	showButtonsLabel: true,
 	showAccept: false,
 	acceptLabel: 'Accept',
+	onChange: action( 'onChange' ),
+	onSend: action( 'onSend' ),
+	onStop: action( 'onStop' ),
+	onAccept: action( 'onAccept' ),
 };
 
 export const Default = Template.bind( {} );