@foundationui/smart-input - npm Package Compare versions

Comparing version 1.0.65 to 1.0.66

dist/cjs/SmartInput.d.ts

@@ -7,7 +7,24 @@ import React, { HTMLAttributes, MutableRefObject } from 'react';
     /**
-     * The controlled value of the input. Declare a state variable for this in the parent component.
+     * The ID of the model to use for completions. If not provided, a sample completion will be displayed.
      */
+    modelId?: string;
+    /**
+     * The ID of the user using the input. Providing this helps the model learn a particular user's style,
+     * including if they prefer not to use completions at all.
+     */
+    userId?: string;
+    /**
+     * An object that will help the model generate better completions.
+     * Pass anything that you think is relevant to making the completions better or more personalized.
+     */
+    context?: any;
+    /**
+     * A ref to the underlying contenteditable div. This can be used to focus the editor, select text, etc.
+     */
+    /**
+     * The controlled value of the input.
+     */
     value: string;
     /**
-     * Called whenever the value of the input changes. Use this to update the state variable for the controlled `value` property.
+     * Called whenever the value of the input changes. Use this to update the controlled `value` property.
      */
@@ -29,18 +46,4 @@ onChange: (newValue: string) => void;
     /**
-     * The ID of the model to use for completions. If not provided, a sample completion will be displayed.
+     * A ref to the underlying contenteditable wrapper element. This can be used to focus the editor, select text, etc.
      */
-    modelId?: string;
-    /**
-     * The ID of the user using the input. Providing this helps the model learn a particular user's style,
-     * including if they prefer not to use completions at all.
-     */
-    userId?: string;
-    /**
-     * An object that will be passed to the model when fetching completions. This can be used to provide context for the completions.
-     * Pass anything that you think is relevant to making the completions better or more personalized (e.g. the current user id, additional form data, etc.)
-     */
-    context?: any;
-    /**
-     * A ref to the underlying contenteditable div. This can be used to focus the editor, select text, etc.
-     */
     editorRef?: MutableRefObject<any>;
@@ -54,13 +57,13 @@ /**
      */
-    onBlur?: React.FocusEventHandler<HTMLDivElement>;
+    onBlur?: React.FocusEventHandler<HTMLElement>;
     /**
      * Called when the input gains focus.
      */
-    onFocus?: React.FocusEventHandler<HTMLDivElement>;
+    onFocus?: React.FocusEventHandler<HTMLElement>;
     /**
      * Called when a key is pressed while the input is focused.
      */
-    onKeyDown?: React.KeyboardEventHandler<HTMLDivElement>;
+    onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
     /**
-     * The value to display when the input is empty.
+     * The value to display when the input is empty. If not provided, no placeholder is displayed.
      */
@@ -67,0 +70,0 @@ placeholder?: string;

dist/cjs/SmartInputFetcher.d.ts

@@ -44,3 +44,8 @@ import { ICompletionResponse } from './protocol';
     constructor(apiUrl: string, addCompletion: (text: string, completion: ICompletionResponse) => void, modelId?: string | undefined, getCompletion?: ((text: string) => string | null) | undefined);
-    fetchCompletion: import("./util/debounce").DebouncedFunction<any[], (text: string, context: any) => Promise<ICompletionResponse | null>>;
+    fetchCompletion: import("./util/debounce").DebouncedFunction<any[], (arg: {
+        text: string;
+        context?: any;
+        user?: string;
+        safeMode?: boolean;
+    }) => Promise<ICompletionResponse | null>>;
     updateCompletion(completionSid: string, arg: {
@@ -50,3 +55,3 @@ seen?: boolean;
     }): void;
-    sendEvents: (text: string, context: any, userId?: string | undefined) => void;
+    sendEvents: (text: string, context: any, user?: string | undefined) => void;
 }

dist/esm/SmartInput.d.ts

@@ -7,7 +7,24 @@ import React, { HTMLAttributes, MutableRefObject } from 'react';
     /**
-     * The controlled value of the input. Declare a state variable for this in the parent component.
+     * The ID of the model to use for completions. If not provided, a sample completion will be displayed.
      */
+    modelId?: string;
+    /**
+     * The ID of the user using the input. Providing this helps the model learn a particular user's style,
+     * including if they prefer not to use completions at all.
+     */
+    userId?: string;
+    /**
+     * An object that will help the model generate better completions.
+     * Pass anything that you think is relevant to making the completions better or more personalized.
+     */
+    context?: any;
+    /**
+     * A ref to the underlying contenteditable div. This can be used to focus the editor, select text, etc.
+     */
+    /**
+     * The controlled value of the input.
+     */
     value: string;
     /**
-     * Called whenever the value of the input changes. Use this to update the state variable for the controlled `value` property.
+     * Called whenever the value of the input changes. Use this to update the controlled `value` property.
      */
@@ -29,18 +46,4 @@ onChange: (newValue: string) => void;
     /**
-     * The ID of the model to use for completions. If not provided, a sample completion will be displayed.
+     * A ref to the underlying contenteditable wrapper element. This can be used to focus the editor, select text, etc.
      */
-    modelId?: string;
-    /**
-     * The ID of the user using the input. Providing this helps the model learn a particular user's style,
-     * including if they prefer not to use completions at all.
-     */
-    userId?: string;
-    /**
-     * An object that will be passed to the model when fetching completions. This can be used to provide context for the completions.
-     * Pass anything that you think is relevant to making the completions better or more personalized (e.g. the current user id, additional form data, etc.)
-     */
-    context?: any;
-    /**
-     * A ref to the underlying contenteditable div. This can be used to focus the editor, select text, etc.
-     */
     editorRef?: MutableRefObject<any>;
@@ -54,13 +57,13 @@ /**
      */
-    onBlur?: React.FocusEventHandler<HTMLDivElement>;
+    onBlur?: React.FocusEventHandler<HTMLElement>;
     /**
      * Called when the input gains focus.
      */
-    onFocus?: React.FocusEventHandler<HTMLDivElement>;
+    onFocus?: React.FocusEventHandler<HTMLElement>;
     /**
      * Called when a key is pressed while the input is focused.
      */
-    onKeyDown?: React.KeyboardEventHandler<HTMLDivElement>;
+    onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
     /**
-     * The value to display when the input is empty.
+     * The value to display when the input is empty. If not provided, no placeholder is displayed.
      */
@@ -67,0 +70,0 @@ placeholder?: string;

dist/esm/SmartInputFetcher.d.ts

@@ -44,3 +44,8 @@ import { ICompletionResponse } from './protocol';
     constructor(apiUrl: string, addCompletion: (text: string, completion: ICompletionResponse) => void, modelId?: string | undefined, getCompletion?: ((text: string) => string | null) | undefined);
-    fetchCompletion: import("./util/debounce").DebouncedFunction<any[], (text: string, context: any) => Promise<ICompletionResponse | null>>;
+    fetchCompletion: import("./util/debounce").DebouncedFunction<any[], (arg: {
+        text: string;
+        context?: any;
+        user?: string;
+        safeMode?: boolean;
+    }) => Promise<ICompletionResponse | null>>;
     updateCompletion(completionSid: string, arg: {
@@ -50,3 +55,3 @@ seen?: boolean;
     }): void;
-    sendEvents: (text: string, context: any, userId?: string | undefined) => void;
+    sendEvents: (text: string, context: any, user?: string | undefined) => void;
 }

dist/index.d.ts

@@ -8,7 +8,24 @@ import React, { HTMLAttributes, MutableRefObject } from 'react';
     /**
-     * The controlled value of the input. Declare a state variable for this in the parent component.
+     * The ID of the model to use for completions. If not provided, a sample completion will be displayed.
      */
+    modelId?: string;
+    /**
+     * The ID of the user using the input. Providing this helps the model learn a particular user's style,
+     * including if they prefer not to use completions at all.
+     */
+    userId?: string;
+    /**
+     * An object that will help the model generate better completions.
+     * Pass anything that you think is relevant to making the completions better or more personalized.
+     */
+    context?: any;
+    /**
+     * A ref to the underlying contenteditable div. This can be used to focus the editor, select text, etc.
+     */
+    /**
+     * The controlled value of the input.
+     */
     value: string;
     /**
-     * Called whenever the value of the input changes. Use this to update the state variable for the controlled `value` property.
+     * Called whenever the value of the input changes. Use this to update the controlled `value` property.
      */
@@ -30,18 +47,4 @@ onChange: (newValue: string) => void;
     /**
-     * The ID of the model to use for completions. If not provided, a sample completion will be displayed.
+     * A ref to the underlying contenteditable wrapper element. This can be used to focus the editor, select text, etc.
      */
-    modelId?: string;
-    /**
-     * The ID of the user using the input. Providing this helps the model learn a particular user's style,
-     * including if they prefer not to use completions at all.
-     */
-    userId?: string;
-    /**
-     * An object that will be passed to the model when fetching completions. This can be used to provide context for the completions.
-     * Pass anything that you think is relevant to making the completions better or more personalized (e.g. the current user id, additional form data, etc.)
-     */
-    context?: any;
-    /**
-     * A ref to the underlying contenteditable div. This can be used to focus the editor, select text, etc.
-     */
     editorRef?: MutableRefObject<any>;
@@ -55,13 +58,13 @@ /**
      */
-    onBlur?: React.FocusEventHandler<HTMLDivElement>;
+    onBlur?: React.FocusEventHandler<HTMLElement>;
     /**
      * Called when the input gains focus.
      */
-    onFocus?: React.FocusEventHandler<HTMLDivElement>;
+    onFocus?: React.FocusEventHandler<HTMLElement>;
     /**
      * Called when a key is pressed while the input is focused.
      */
-    onKeyDown?: React.KeyboardEventHandler<HTMLDivElement>;
+    onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
     /**
-     * The value to display when the input is empty.
+     * The value to display when the input is empty. If not provided, no placeholder is displayed.
      */
@@ -68,0 +71,0 @@ placeholder?: string;

dist/umd/SmartInput.d.ts

@@ -7,7 +7,24 @@ import React, { HTMLAttributes, MutableRefObject } from 'react';
     /**
-     * The controlled value of the input. Declare a state variable for this in the parent component.
+     * The ID of the model to use for completions. If not provided, a sample completion will be displayed.
      */
+    modelId?: string;
+    /**
+     * The ID of the user using the input. Providing this helps the model learn a particular user's style,
+     * including if they prefer not to use completions at all.
+     */
+    userId?: string;
+    /**
+     * An object that will help the model generate better completions.
+     * Pass anything that you think is relevant to making the completions better or more personalized.
+     */
+    context?: any;
+    /**
+     * A ref to the underlying contenteditable div. This can be used to focus the editor, select text, etc.
+     */
+    /**
+     * The controlled value of the input.
+     */
     value: string;
     /**
-     * Called whenever the value of the input changes. Use this to update the state variable for the controlled `value` property.
+     * Called whenever the value of the input changes. Use this to update the controlled `value` property.
      */
@@ -29,18 +46,4 @@ onChange: (newValue: string) => void;
     /**
-     * The ID of the model to use for completions. If not provided, a sample completion will be displayed.
+     * A ref to the underlying contenteditable wrapper element. This can be used to focus the editor, select text, etc.
      */
-    modelId?: string;
-    /**
-     * The ID of the user using the input. Providing this helps the model learn a particular user's style,
-     * including if they prefer not to use completions at all.
-     */
-    userId?: string;
-    /**
-     * An object that will be passed to the model when fetching completions. This can be used to provide context for the completions.
-     * Pass anything that you think is relevant to making the completions better or more personalized (e.g. the current user id, additional form data, etc.)
-     */
-    context?: any;
-    /**
-     * A ref to the underlying contenteditable div. This can be used to focus the editor, select text, etc.
-     */
     editorRef?: MutableRefObject<any>;
@@ -54,13 +57,13 @@ /**
      */
-    onBlur?: React.FocusEventHandler<HTMLDivElement>;
+    onBlur?: React.FocusEventHandler<HTMLElement>;
     /**
      * Called when the input gains focus.
      */
-    onFocus?: React.FocusEventHandler<HTMLDivElement>;
+    onFocus?: React.FocusEventHandler<HTMLElement>;
     /**
      * Called when a key is pressed while the input is focused.
      */
-    onKeyDown?: React.KeyboardEventHandler<HTMLDivElement>;
+    onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
     /**
-     * The value to display when the input is empty.
+     * The value to display when the input is empty. If not provided, no placeholder is displayed.
      */
@@ -67,0 +70,0 @@ placeholder?: string;

dist/umd/SmartInputFetcher.d.ts

@@ -44,3 +44,8 @@ import { ICompletionResponse } from './protocol';
     constructor(apiUrl: string, addCompletion: (text: string, completion: ICompletionResponse) => void, modelId?: string | undefined, getCompletion?: ((text: string) => string | null) | undefined);
-    fetchCompletion: import("./util/debounce").DebouncedFunction<any[], (text: string, context: any) => Promise<ICompletionResponse | null>>;
+    fetchCompletion: import("./util/debounce").DebouncedFunction<any[], (arg: {
+        text: string;
+        context?: any;
+        user?: string;
+        safeMode?: boolean;
+    }) => Promise<ICompletionResponse | null>>;
     updateCompletion(completionSid: string, arg: {
@@ -50,3 +55,3 @@ seen?: boolean;
     }): void;
-    sendEvents: (text: string, context: any, userId?: string | undefined) => void;
+    sendEvents: (text: string, context: any, user?: string | undefined) => void;
 }

package.json

 {
   "name": "@foundationui/smart-input",
-  "version": "1.0.65",
+  "version": "1.0.66",
   "description": "Smart input/textarea component for React. Learns to provide inline, tab-completeable suggestions.",
@@ -5,0 +5,0 @@ "type": "module",

README.md

 # `<SmartInput>`
 
-Drop-in `<input>` and `<textarea>` replacement that that provides inline, tab-completable suggestions similar to GitHub Copilot.
+Drop-in `<input>` and `<textarea>` replacement that that provides inline, tab-completable suggestions like GitHub Copilot for any app.
 
-The component automatically learns user inputs and makes better suggestions over time. We don't call it smart for nothing!
+The component automatically learns from user input and makes better suggestions over time. We don't call it smart for nothing!
 
@@ -25,3 +25,3 @@ ```jsx
 
-Check out the interactive examples:
+Examples:
 
@@ -46,2 +46,54 @@ - [Tailwind](https://jsbin.com/difibux/edit?html,js,output)
 
+## How it works
+
+`<SmartInput>` learns to complete the text you intend to write just like GitHub Copilot. It's not very smart at first, but it quickly learns to be useful. Start by creating a model on [foundation-ui.com](https://foundation-ui.com) then set the `modelId` property:
+
+```jsx
+<SmartInput modelId={'your unique model id'} />
+```
+
+As you enter keystrokes into `<SmartInput>`, at first it won't do anything at all but learn. Once it's confident enough, it'll start suggesting completions. You can control how confident you want `<SmartInput>` to be, which users should get completions, and other settings from your admin console on [foundation-ui.com](https://app.foundation-ui.com).
+
+### Learning user style & preferences
+
+Not all users write the same way, and not all users want completions! Not yet. `<SmartInput>` learns how to be most helpful to each user if you set the `userId` property:
+
+```jsx
+<SmartInput userId={'a unique, stable id from your app'} />
+```
+
+### Providing context
+
+To generate the best completions, give `<SmartInput>` whatever extra context you think would be useful. Provide data as a JSON object:
+
+```jsx
+<SmartInput
+  context={{
+    emailSubject: 'This is too easy to integrate into my app',
+    to: '[e-mail]',
+  }}
+/>
+```
+
+### Bootstrap data
+
+`<SmartInput>` can start learning without any data. If you want to accelerate the process, you can upload a list of strings to [foundation-ui.com](https://foundation-ui.com) to bootstrap the model.
+
+### Deploy to prod
+
+`<SmartInput>` is designed with security in mind. In addition to the controls provided for your model on [foundation-ui.com](https://foundation-ui.com), you can set the `safeMode` property to prevent showing completions:
+
+```jsx
+<SmartInput safeMode />
+```
+
+While in safe mode, `<SmartInput>` will learn from user keystrokes, but will not show any completions unless the `userId` has been whitelisted on [foundation-ui.com](https://foundation-ui.com).
+
+Therefore we recommend as the safest path to production:
+
+0. (optional) Bootstrap your model with data on [foundation-ui.com](https://foundation-ui.com)
+1. Replace one of the inputs in your app with `<SmartInput safeMode />`
+2. Whitelist internal users, tune settings, and review model performance on [foundation-ui.com](https://foundation-ui.com) until you are satisfied with the results
+3. Turn off `safeMode`
+
 ## API
@@ -51,20 +103,24 @@
 
-#### `modelId: String`
+#### `modelId: string | undefined`
 
-The identifier of your model. Can be shared across different inputs, or unique per input. If you don't specify one, sample completions will be generated.
+The identifier of your model. Can be shared across different inputs, or unique per input. If you don't specify one, it will show an example completion without querying a model.
 
-#### `value: String`
+#### `userId: string | undefined`
 
-The controlled text value of the content.
+The ID of the user using the input. Providing this helps the model learn a particular user's style, including if they prefer not to use completions at all.
 
-#### `onChange: Function`
+#### `context: Object | undefined`
 
-Arguments: `newValue: String`
+An object that will help the model generate better completions. Pass anything that you think is relevant to making the completions better or more personalized.
 
-Invoked whenever the text value of the content changes. Use this to update the value for the controlled component.
+#### `value: string`
 
-#### `renderText: Function`
+The controlled value of the input.
 
-Arguments: `props: Any`
+#### `onChange: (newValue: string) => void`
 
+Invoked whenever the text value of the content changes. Use this to update the controlled `value`.
+
+#### `renderText: (props: any) => React.ReactElement`
+
 Invoked to display normal text, returns a React element. You should use an inline display element (e.g. `span`) and spread props, like so:
@@ -78,6 +134,4 @@
 
-#### `renderCompletion: Function`
+#### `renderCompletion: (props: any) => React.ReactElement`
 
-Arguments: `props: Any`
-
 Invoked to display completion text, returns a React element. You should use an inline display element (e.g. `span`) and spread props, like so:
@@ -91,37 +145,52 @@
 
-#### `multiline: Boolean` (optional)
+#### `renderPlaceholder: undefined | (props: any) => React.ReactElement`
 
-Whether or not to allow multiline text.
+Invoked to display placeholder text, returns a React element. You should use an inline display element (e.g. `span`) and spread props, like so:
 
-#### `onBlur: React.FocusEventHandler<HTMLDivElement>` (optional)
+```jsx
+renderCompletion={props => <span {...props} />}
+```
 
-Standard onBlur handler, analogous to that provided by `<input>` and `<textarea>` elements.
+You may add whatever styling you like like via `style`, `className`, etc.
 
-#### `onFocus: React.FocusEventHandler<HTMLDivElement>` (optional)
+**_WARNING_**: if you want to set `style`, make sure to merge the `style` from `props` like so:
 
-Standard onFocus handler, analogous to that provided by `<input>` and `<textarea>` elements.
+```jsx
+renderCompletion={props => <span {...props} style={{...props.style, color: 'red' }} />}
+```
 
-#### `onKeyDown: React.KeyboardEventHandler<HTMLDivElement>` (optional)
+#### `placeholder: string | undefined`
 
-Standard onKeyDown handler, analogous to that provided by `<input>` and `<textarea>` elements. Note that this handler is called after any keyboard events captured by `<SmartInput>` (e.g. `Tab` to accept a suggestion).
+The text to display when value is empty. If not provided, no placeholder is displayed.
 
-#### `placeholder: String` (optional)
+#### `multiline: boolean | undefined`
 
-The text to display when value is empty.
+Whether or not to allow multiline text. Default `false`.
 
-#### `disabled: Boolean` (optional)
+#### `onBlur: React.FocusEventHandler<HTMLElement> | undefined`
 
-Whether the input is editable. If true, the input is read-only.
+Standard `onBlur` handler, analogous to the one from `<input>` and `<textarea>` elements.
 
-#### `safeMode: Boolean` (optional)
+#### `onFocus: React.FocusEventHandler<HTMLElement> | undefined`
 
-Whether to run in safe mode. In safe mode, no completions will be generated or request to the user, but your input will still collect
-data to learn to generate comlpetions.
+Standard `onFocus` handler, analogous to the one from `<input>` and `<textarea>` elements.
 
-#### `className: string` (optional)
+#### `onKeyDown: React.KeyboardEventHandler<HTMLElement> | undefined`
 
-Class name for the SmartInput wrapper div.
+Standard `onKeyDown` handler, analogous to the one from `<input>` and `<textarea>` elements. Note that this handler is called after any keyboard events captured by `<SmartInput>` (e.g. `Tab` to accept a suggestion).
 
-#### `style: React.CSSProperties` (optional)
+#### `disabled: boolean | undefined`
 
-Standard React CSS style property, applied to SmartInput wrapper div.
+Whether the input is editable. If `true`, the input is read-only.
+
+#### `safeMode: boolean | undefined`
+
+Whether to run in safe mode. In safe mode, no completions will be shown, but your input will still collect data to learn to generate completions. You can see the completions that would have been shown to your users on [foundation-ui.com](https://foundation-ui.com)
+
+#### `container: React.ElementType<P> | undefined`
+
+Element to use as the wrapper component. If not provided, the component will render as a `<div>` with `contenteditable="true"`.
+
+#### `containerProps: P | undefined`
+
+Props that will get passed to the `container` element, when one is provided.

No alert changes

Improved metrics

Total package byte prevSize

564554

increased by0.72%

Lines of code

2897

increased by0.98%

Number of lines in readme file

192

increased by56.1%

No dependency changes