attio 0.0.1-experimental.20241008.3 → 0.0.1-experimental.20241011

package/lib/client/components/action.d.ts

@@ -1,11 +1,31 @@
 import React from "react";
 import { Icon } from "../icon";
 /**
- * Action Button
+ * An “action button” is a button that can appear in the Attio UI,
+ * typically on a record page.
+ *
+ * You must “register” the component that renders this component
+ * using `registerRecordAction()`.
  */
 export declare function Action(props: {
+    /**
+     * A function to execute when the button is clicked (or tapped)
+     */
     onTrigger: () => void;
+    /**
+     * An icon to display in the button, either an `AttioIcon` or
+     * a string `.png` referencing a file in your app’s `assets`
+     * directory.
+     *
+     * If no `icon` prop is provided, it will default to your app’s icon.
+     */
     icon?: Icon;
+    /**
+     * Whether or not the button is disabled. Defaults to `false`.
+     */
     disabled?: boolean;
+    /**
+     * The text content of the button.
+     */
     children: React.ReactNode;
 }): React.JSX.Element;

package/lib/client/components/combobox.d.ts

@@ -1,9 +1,30 @@
 export interface ComboboxOption {
+    /** The value that will be saved into your form data when this option is selected */
     value: string;
+    /** The label the user will see for this option */
     label: string;
+    /**
+     * An optional CSS color to display for this option
+     *
+     * It will be displayed in a little circle next to the label.
+     */
     color?: string;
 }
 export interface ComboboxOptionsProvider {
+    /**
+     * An async function that, given an option value, returns the label and color of the option.
+     *
+     * @param value - The value of the option
+     * @returns - The label and color of the option
+     */
     getOption: (value: string) => Promise<Omit<ComboboxOption, "value">>;
+    /**
+     * An async function that, given a search query, returns a list of "matching" combobox options.
+     *
+     * What "matching" means is up to the developer.
+     *
+     * @param query - The search query
+     * @returns - A list of combobox options
+     */
     search: (query: string) => Promise<Array<ComboboxOption>>;
 }

package/lib/client/components/multistep.d.ts

@@ -1,4 +1,9 @@
 import React from "react";
+/**
+ * A step in a multi-step component.
+ *
+ * @deprecated This is not ready for use yet.
+ */
 export interface Step {
     title: string;
     content: React.ReactNode;
@@ -6,6 +11,8 @@ export interface Step {
 }
 /**
  * A multi-step component
+ *
+ * @deprecated This is not ready for use yet.
  */
 export declare function Multistep(props: {
     initialStep?: number;

package/lib/client/components/row.d.ts

@@ -1,6 +1,9 @@
 import React from "react";
 /**
- * A component for laying children out horizontally.
+ * A component for laying out children horizontally.
+ *
+ * On the web, it can fit up to three children horizontally,
+ * and on mobile, all children will be presented vertically.
  */
 export declare function Row(props: {
     children: React.ReactNode;

package/lib/client/components/section.d.ts

@@ -1,8 +1,16 @@
 import React from "react";
 /**
- * A section of a page
+ * A section of a page with a title.
  */
 export declare function Section(props: {
+    /**
+     * The title of the section.
+     *
+     * It will be displayed in a stronger font than the content of the section.
+     */
     title: string;
+    /**
+     * The content of the section, either text or other components.
+     */
     children?: React.ReactNode;
 }): React.JSX.Element;

package/lib/client/components/text-block.d.ts

@@ -1,8 +1,14 @@
 import React from "react";
 /**
- * A text block
+ * A text block, whose content can optionally be aligned.
  */
 export declare function TextBlock(props: {
+    /**
+     * How to align the content of the text block.
+     */
     align?: "flex-start" | "flex-end" | "center" | "stretch" | "baseline" | "initial" | "inherit";
+    /**
+     * The content of the text block. Usually text, but can also be other components.
+     */
     children: React.ReactNode;
 }): React.JSX.Element;

package/lib/client/forms/array.d.ts

@@ -1,12 +1,16 @@
+import { FormValue } from "./value";
 /**
  * An array form value.
  */
-export interface FormArray<T> {
+export interface FormArray<T> extends FormValue {
     type: "array";
     elementType: T;
+    /**
+     * Make this array optional, i.e. allow `null` or `undefined` values.
+     */
     optional(): FormArray<T>;
 }
 /**
  * Create a new array form value.
  */
-export declare function array<T>(elementType: T): FormArray<T>;
+export declare function array<T extends FormValue | Record<string, FormValue>>(elementType: T): FormArray<T>;

package/lib/client/forms/index.d.ts

@@ -1,5 +1,3 @@
-export { build } from "./build";
 export { array } from "./array";
 export { number } from "./number";
 export { string } from "./string";
-export { connection } from "./connection";

package/lib/client/forms/number.d.ts

@@ -1,11 +1,31 @@
+import { FormValue } from "./value";
 /**
  * A number form value.
  */
-export interface FormNumber {
+export interface FormNumber extends FormValue {
     type: "number";
+    /**
+     * Whether this number is optional, i.e. allows `null` or `undefined` values.
+     */
     isOptional: boolean;
+    /**
+     * Make this number optional, i.e. allow `null` or `undefined` values.
+     */
+    optional(): FormNumber;
+    /**
+     * Set the default value of this number. The default value will be returned if the user
+     * doesn't provide a value.
+     *
+     * NOTE that this is not the same as an initial value!
+     */
     default(value: number): FormNumber;
+    /**
+     * Set the maximum value of this number.
+     */
     max(max: number): FormNumber;
+    /**
+     * Set the minimum value of this number.
+     */
     min(min: number): FormNumber;
 }
 /**

package/lib/client/forms/path.d.ts

@@ -1,12 +1,11 @@
 import { Prettify } from "../util/prettify";
 import { FormArray } from "./array";
-import { FormConnection, Connection } from "./connection";
 import { FormNumber } from "./number";
 import { FormString } from "./string";
 type Assert<TCat, TAnimal> = TCat extends TAnimal ? TCat : never;
 type Join<A extends string | number | null, B extends string | number> = A extends null ? B : `${A}.${B}`;
-export type ValueType = "string" | "number" | "array" | "connection";
-export type SchemaNode = FormString | FormNumber | FormConnection | FormArray<any> | {
+export type ValueType = "string" | "number" | "connection" | "array";
+export type SchemaNode = FormString | FormNumber | FormArray<any> | {
     type: "object";
 };
 type PathWithTypeRecursive<TState, TRoot extends string | number | null> = TState extends FormString ? {
@@ -15,9 +14,6 @@ type PathWithTypeRecursive<TState, TRoot extends string | number | null> = TStat
 } : TState extends FormNumber ? {
     path: TRoot;
     type: "number";
-} : TState extends FormConnection ? {
-    path: TRoot;
-    type: "connection";
 } : TState extends FormArray<infer TElement> ? {
     path: TRoot;
     type: "array";
@@ -32,7 +28,7 @@ export type Path<TState> = PathWithType<TState>["path"];
 export type PathTo<TState, TType extends ValueType> = Extract<PathWithType<TState>, {
     type: TType;
 }>["path"];
-export type ValueOf<TState> = TState extends FormString ? string : TState extends FormNumber ? number : TState extends FormConnection ? Connection : TState extends FormArray<infer TElement> ? Array<ValueOf<TElement>> : {
+export type ValueOf<TState> = TState extends FormString ? string : TState extends FormNumber ? number : TState extends FormArray<infer TElement> ? Array<ValueOf<TElement>> : {
     [K in keyof TState]: K extends string ? ValueOf<TState[K]> : never;
 };
 export {};

package/lib/client/forms/string.d.ts

@@ -1,13 +1,34 @@
+import { FormValue } from "./value";
 /**
  * A string form value.
  */
-export interface FormString {
+export interface FormString extends FormValue {
     type: "string";
+    /**
+     * Whether or not this string is multiline.
+     *
+     * Multiline strings are rendered as textarea fields.
+     */
     isMultiline: boolean;
+    /**
+     * Whether this string is optional, i.e. allows `null` or `undefined` values.
+     */
     isOptional: boolean;
+    /**
+     * Set the default value of this string. The default value will be returned if the user
+     * doesn't provide a value.
+     *
+     * NOTE that this is not the same as an initial value!
+     */
     default(value: string): FormString;
-    multiline(): FormString;
+    /**
+     * Make this string optional, i.e. allow `null` or `undefined` values.
+     */
     optional(): FormString;
+    /**
+     * Make this string multiline, i.e. render as textarea field.
+     */
+    multiline(): FormString;
 }
 /**
  * Create a new string form value.

package/lib/client/forms/value.d.ts

@@ -0,0 +1,6 @@
+/**
+ * An opaque type for form values.
+ */
+export interface FormValue {
+    readonly __brand: unique symbol;
+}

package/lib/client/hooks/index.d.ts

@@ -1,4 +1,5 @@
-export { useDialog } from "./use-dialog.js";
 export { useAsyncCache, AsyncCacheConfig, AsyncFunction } from "./use-async-cache.js";
+export { useDialog } from "./use-dialog.js";
+export { useForm, FormApi, FormSchema } from "./use-form.js";
 export { useQuery } from "./use-query.js";
 export { useRecord } from "./use-record.js";

package/lib/client/hooks/use-async-cache.d.ts

@@ -12,8 +12,57 @@ export interface AsyncCacheConfig {
     [K: string]: AsyncFunction<Array<any>, any> | [AsyncFunction<Array<any>, any>, ...Array<any>];
 }
 /**
- * A hook that returns, and caches, the results of calling multiple async functions,
- * typically to load data.
+ * A hook that returns, and caches, the results of calling one or more async functions,
+ * typically to load data from a third party via server functions.
+ *
+ * The component it is used in will suspend until ALL async functions have resolved.
+ *
+ * ## EXAMPLE USAGE
+ *
+ * ----
+ * ```ts
+ * // load-widgets.server.ts
+ * export default async function loadWidgets() : Promise<Array<Widget>> {
+ *   // fetch widgets from somewhere
+ * }
+ * ```
+ * ----
+ * ```ts
+ * // load-sprockets.server.ts
+ * export default async function loadSprockets(
+ *   material: Material,
+ *   max?: number
+ * ): Promise<Array<Sprocket>> {
+ *   // fetch sprockets from somewhere
+ * }
+ * ```
+ * ----
+ * ```ts
+ * import { useAsyncCache } from "attio/client"
+ *
+ * import loadWidgets from "./load-widgets.server.ts"
+ * import loadSprockets from "./load-sprockets.server.ts"
+ *
+ * ...
+ *
+ * // inside component:
+ *
+ * const results = useAsyncCache({
+ *   // loadWidgets takes zero parameters and can thus be called without an array
+ *   widgets: loadWidgets,
+ *   // loadSprockets takes a `material` parameter, so we call it like this
+ *   ironSprockets: [loadSprockets, "iron"],
+ *   copperSprockets: [loadSprockets, "copper", 42],
+ * })
+ *
+ * const { widgets, ironSprockets, copperSprockets } = results.values
+ *
+ * ...
+ *
+ * // inside an event handler, perhaps, to refetch _only_ the iron sprockets
+ * results.invalidate("ironSprockets")
+ * ```
+ * ----
  */
 export declare function useAsyncCache<Config extends AsyncCacheConfig>(config: Config): {
     values: {

package/lib/client/hooks/use-dialog.d.ts

@@ -1,17 +1,71 @@
+import React from "react";
+/**
+ * Dialog component
+ *
+ * IMPORTANT: The <Dialog/> component should _always_ be rendered in your app.
+ * Do not render it conditionally.
+ */
+interface Dialog extends React.FC<{
+    /**
+     * A required title for the dialog.
+     */
+    title: string;
+    /**
+     * An optional callback that will be called when the dialog is closed.
+     */
+    onClose?: () => void;
+    /**
+     * The content of the dialog.
+     */
+    children: React.ReactNode;
+}> {
+}
 /**
  * This hook allows you to create a modal dialog.
  *
+ * ## EXAMPLE USAGE
+ *
+ * ----
+ * ```tsx
+ * import { useDialog } from "attio/client"
+ *
+ * ...
+ *
+ * // inside component:
+ * const dialog = useDialog()
+ *
+ * return (
+ *   <>
+ *     <Action onTrigger={() => dialog.open()}>Do Stuff</Action>
+ *     <dialog.Dialog>
+ *       Here is my useful UI
+ *     </dialog.Dialog>
+ *   </>
+ * )
+ * ```
+ * ----
+ *
  * @returns An object with the following properties:
  * - `Dialog`: A React component that you should render with the dialog contents as its children.
  * - `open`: Opens the rendered dialog.
  * - `close`: Closes the rendered dialog.
  */
 export declare function useDialog(): {
-    Dialog: React.ComponentType<{
-        title: string;
-        onClose?: () => void;
-        children: React.ReactNode;
-    }>;
+    /**
+     * The dialog component to render.
+     *
+     * IMPORTANT: The <Dialog/> component should _always_ be rendered in your app.
+     * Do not render it conditionally.
+     */
+    Dialog: Dialog;
+    /**
+     * A function to imperatively open the dialog. Often called via an
+     * `onTrigger` prop on an `<Action/>` button.
+     */
     open: () => void;
+    /**
+     * A function to imperatively close the dialog.
+     */
     close: () => void;
 };
+export {};

package/lib/client/hooks/use-form.d.ts

@@ -0,0 +1,177 @@
+import React from "react";
+import { ComboboxOption, ComboboxOptionsProvider } from "../components/combobox";
+import { PathTo, ValueOf } from "../forms/path";
+import { FormValue } from "../forms/value";
+export type FormSchema = Record<string, FormValue>;
+/**
+ * A <Form> component that must wrap all the fields and provide a submit handler.
+ *
+ * @example
+ * ```tsx
+ * <Form onSubmit={(values) => {
+ *   console.log(values)
+ * }}>
+ *   <Input label="Name" data="name" />
+ *   <SubmitButton label="Submit" />
+ * </Form>
+ * ```
+ */
+type Form<TSchema extends FormSchema> = React.FC<{
+    /** The contents of the form, including layout and input components */
+    children: React.ReactNode;
+    /**
+     * The function to call when the form is submitted.
+     *
+     * `onSubmit` will NOT be called if there are validation errors.
+     */
+    onSubmit: (values: ValueOf<TSchema>) => void;
+}>;
+/**
+ * A text, number, or connection input field.
+ */
+type Input<TSchema extends FormSchema> = React.FC<{
+    /** The label of the input field */
+    label: string;
+    /** The path to the value of the input field, e.g. `"name"` or `"address.street"` */
+    data: PathTo<TSchema, "string" | "number" | "connection">;
+    /** The optional placeholder text of the input field */
+    placeholder?: string;
+    /** Whether the input field is disabled */
+    disabled?: boolean;
+}>;
+/**
+ * A combobox input field.
+ */
+type Combobox<TSchema extends FormSchema> = React.FC<{
+    /** The label of the combobox field */
+    label: string;
+    /** The path to the value of the combobox field, e.g. `"mode"` or `"shipping.method"` */
+    data: PathTo<TSchema, "string">;
+    /**
+     * The options of the combobox field
+     *
+     * Either an array of options, or a provider that asynchronously fetches options.
+     */
+    options: Array<ComboboxOption> | ComboboxOptionsProvider;
+    /** The optional placeholder text of the combobox field */
+    placeholder?: string;
+    /** Whether the combobox field is disabled */
+    disabled?: boolean;
+}>;
+/**
+ * A component used to render a collection of inputs.
+ */
+type Collection<TSchema extends FormSchema, TPath extends PathTo<TSchema, "array">> = React.FC<{
+    /** The label of the collection field */
+    label: string;
+    /** The path to the value of the collection field, e.g. `"items"` or `"shipping.items"` */
+    data: TPath;
+    /**
+     * A render prop that receives the path and index of one of the items and renders
+     * the inputs for that item
+     */
+    children: (args: {
+        path: `${TPath}.${number}`;
+        index: number;
+    }) => React.ReactNode;
+}>;
+/**
+ * A component used to group inputs in a collection together
+ */
+type CollectionItem = React.FC<{
+    /** The label of the collection item */
+    label: string;
+    /** The inputs of the collection item */
+    children: React.ReactNode;
+}>;
+/**
+ * A submit button for the form.
+ *
+ * If the form is rendered inside a dialog, the submit button will be placed at the bottom of the dialog.
+ */
+type SubmitButton = React.FC<{
+    /** The label of the submit button */
+    label: string;
+    /**
+     * Whether the submit button is disabled
+     *
+     * It will automatically become disabled while the form is submitting.
+     * You do not need to manage that state.
+     */
+    disabled?: boolean;
+}>;
+interface WithStateProps<TSchema extends FormSchema, TValues extends boolean = false, TSubmitting extends boolean = false, TErrors extends boolean = false> {
+    values?: TValues;
+    submitting?: TSubmitting;
+    errors?: TErrors;
+    children: (state: {
+        values: TValues extends true ? ValueOf<TSchema> : never;
+        submitting: TSubmitting extends true ? boolean : never;
+        errors: TErrors extends true ? Record<string, string> : never;
+    }) => React.ReactNode;
+}
+/**
+ * A component that provides the form state via a render prop.
+ *
+ * You may specifically request various parts of form state, such as
+ * `values`, `submitting`, and `errors`. This component will rerender
+ * whenever any of the values requested change.
+ */
+interface WithState<TSchema extends FormSchema> {
+    (props: WithStateProps<TSchema, true>): React.ReactElement;
+    (props: WithStateProps<TSchema, boolean, true>): React.ReactElement;
+    (props: WithStateProps<TSchema, boolean, boolean, true>): React.ReactElement;
+    <T extends WithStateProps<TSchema>>(props: T): React.ReactElement;
+}
+export interface FormApi<TSchema extends FormSchema> {
+    /**
+     * Submits the form.
+     *
+     * This will validate the form and call the `onSubmit` handler.
+     */
+    submit: () => void;
+    /**
+     * The <Form> component to wrap the fields of this form and provide a submit handler.
+     */
+    Form: Form<TSchema>;
+    /**
+     * An input field for a string, number, or connection.
+     */
+    Input: Input<TSchema>;
+    /**
+     * A combobox input field.
+     */
+    Combobox: Combobox<TSchema>;
+    /**
+     * A component used to render a collection of inputs.
+     */
+    Collection: Collection<TSchema, any>;
+    /**
+     * A component used to group inputs in a collection together.
+     */
+    CollectionItem: CollectionItem;
+    /**
+     * A submit button for the form.
+     */
+    SubmitButton: SubmitButton;
+    /**
+     * A component that provides the form state via a render prop.
+     */
+    WithState: WithState<TSchema>;
+}
+/**
+ * Creates a form API for a given schema and initial values.
+ *
+ * @example
+ * ```tsx
+ * const api = useForm({
+ *   name: Forms.string(),
+ *   age: Forms.number(),
+ * }, {
+ *   name: "John",
+ *   age: 30,
+ * });
+ * ```
+ */
+export declare function useForm<TSchema extends FormSchema>(schema: TSchema, initialValues: Partial<ValueOf<TSchema>>): FormApi<TSchema>;
+export {};

package/lib/client/hooks/use-query.d.ts

@@ -1,6 +1,47 @@
 import { Query } from "../run-query";
-export declare function useQuery<Variables extends Record<string, any>, Result>(
-/** GraphQL query */
-query: Query<Variables, Result>, 
-/** GraphQL query variables */
-variableValues?: Variables): Result;
+/**
+ * A hook that runs a GraphQL query and returns the result.
+ *
+ * Your component will suspend until the query completes.
+ *
+ * If you import the query from a `.graphql` file, and run `attio dev`,
+ * your query variables and result will be strongly typed.
+ *
+ * ## EXAMPLE USAGE
+ *
+ * ----
+ * ```graphql
+ * # get-person.graphql
+ * query getPerson($id: String!) {
+ *   workspace {
+ *     person(id: $id) {
+ *       name {
+ *         first
+ *         last
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ * ----
+ * ```tsx
+ * // Component.tsx
+ * import { useQuery, useRecord } from "attio/client"
+ * import getPersonQuery from "./get-person.graphql"
+ *
+ * ...
+ *
+ * // in component:
+ * const { recordId } = useRecord()
+ * const result = useQuery(getPersonQuery, { id: recordId })
+ *
+ * const firstName : string | null = result.workspace?.person?.name?.first
+ * const lastName : string | null = result.workspace?.person?.name?.last
+ * ```
+ * ----
+ *
+ * @param query - The GraphQL query to run.
+ * @param variableValues - The variables to pass to the query.
+ * @returns The result of the query.
+ */
+export declare function useQuery<Variables extends Record<string, any> | never, Result>(query: Query<Variables, Result>, variableValues?: Variables extends never ? never : Variables): Result;

package/lib/client/hooks/use-record.d.ts

@@ -3,7 +3,12 @@ import { ObjectSlug } from "../object-slug.js";
  * Get information about the current record.
  */
 export declare function useRecord(): {
+    /**
+     * The ID of the current record.
+     */
     recordId: string;
+    /**
+     * The object type of the current record.
+     */
     object: ObjectSlug;
-    epithet: string;
 };

package/lib/client/index.d.ts

@@ -5,8 +5,7 @@ export * as Forms from "./forms/index.js";
 export { FormArray } from "./forms/array.js";
 export { FormNumber } from "./forms/number.js";
 export { FormString } from "./forms/string.js";
-export { FormConnection, Connection } from "./forms/connection.js";
+export { FormValue } from "./forms/value.js";
 export * from "./forms/path.js";
-export { Form } from "./forms/build.js";
 export { Icon, AttioIcon } from "./icon.js";
 export { registerRecordAction } from "./register-record-action.js";