@niledatabase/react 4.0.0-alpha.1 → 4.0.0-alpha.11

package/README.md

@@ -1,143 +1,103 @@
-# @niledatabase/react
+<p align="center">
+  <img width="1434" alt="Screen Shot 2024-09-18 at 9 20 04 AM" src="https://github.com/user-attachments/assets/20585883-5cdc-4f15-93d3-dc150e87bc11">
+</p>
 
-## Storybook
+---
 
-[Storybook](https://storybook.thenile.dev)
+# Nile's React SDK
 
-## Usage
-
-In the root of your react application, add a Nile provider. This will add a [QueryClientProvider](https://tanstack.com/query/v4/docs/quick-start) and a [CssVarsProvider](https://mui.com/joy-ui/getting-started/usage/) to your application.
+This package (`@niledatabase/react`) is part of [Nile's Javascript SDK](https://github.com/niledatabase/nile-js/tree/main).
 
-```typescript
-import { NileProvider } from '@niledatabase/react';
-
-function App() {
-  return (
-    <NileProvider>
-      <div>Welcome to my great app</div>
-    </NileProvider>
-  );
-}
-```
+Nile's React package provides:
 
-## Configuration
+- 🎨 UI components for authentication, user management, and tenant management (customizable with Tailwind CSS)
+- 🪝 React hooks for authentication, user management, and tenant management functionality
 
-| Property | Type     | Description                                                       |
-| -------- | -------- | ----------------------------------------------------------------- |
-| tenantId | `string` | ID of the tenant associated.                                      |
-| appUrl   | `string` | the FQDN for a service running a `@niledatabase/server`-like API. |
-| apiUrl   | `string` | the API URL of your database                                      |
+You can browse all the components and explore their properties in [Nile's documentation](https://www.thenile.dev/docs/auth/components/signin) or in [Storybook](https://storybook.thenile.dev). 
 
-## Dependencies
+The components and hooks are designed to work best and provide a secure user experience when used with the generated routes provided by [Nile's Server-Side SDK](https://www.npmjs.com/package/@niledatabase/server).
 
-### React query
+**Nile is a Postgres platform that decouples storage from compute, virtualizes tenants, and supports vertical and horizontal scaling globally to ship B2B applications fast while being safe with limitless scale.** All B2B applications are multi-tenant. A tenant/customer is primarily a company, an organization, or a workspace in your product that contains a group of users. A B2B application provides services to multiple tenants. Tenant is the basic building block of all B2B applications.
 
-The components of this library use [react-query](https://react-query.tanstack.com/) to request data. The `<QueryClientProvider />` used can be customized via the optional `QueryProvider` prop of the `<NileProvider />`.
+## Usage
 
-```typescript
-import { QueryClient, QueryClientProvider } from 'react-query';
+### Installation
 
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      retry: false,
-      refetchOnWindowFocus: false,
-    },
-  },
-});
+```bash
+npm install @niledatabase/react
+```
 
-function MyQueryProvider({ children }) {
-  return (
-    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
-  );
-}
-
-function App() {
-  return (
-    <NileProvider QueryProvider={MyQueryProvider}>
-      <div>Welcome to my great app</div>
-    </NileProvider>
-  );
+### Signup / User Info page
+
+This example uses several components to build a one-page signup / user profile example.
+
+- `<SignedIn>` component renders for authenticated users while `<SignedOut>` renders for un-authenticated users.
+- `<SignUpForm>` component shows a standard email/password signup.
+- `<UserInfo />` component shows information about currently authenticated user - their image, email, name, etc.
+- `<TenantSelector>` component shows the current tenant, allows to switch between tenants and to create new tenants.
+- `<SignOutButton />` component expires the current session
+
+```tsx
+import {
+SignOutButton,
+SignUpForm,
+SignedIn,
+SignedOut,
+TenantSelector,
+UserInfo,
+} from "@niledatabase/react";
+import "@niledatabase/react/styles.css";
+
+export default function SignUpPage() {
+return (
+    <div className="flex flex-col items-center justify-center min-h-screen">
+    <SignedIn className="flex flex-col gap-4">
+        <UserInfo />
+        <TenantSelector className="py-6 mb-10" />
+        <SignOutButton />
+    </SignedIn>
+    <SignedOut>
+        <SignUpForm createTenant />
+    </SignedOut>
+    </div>
+);
 }
 ```
 
-### @mui/joy
+### Social Login (SSO)
 
-Out of the box [mui joy](https://mui.com/joy-ui/getting-started/overview/) is available for use. No set up is required, simply add the dependencies to your code, then use components and functions provided by those libraries.
+Nile-Auth supports multiple social providers. You configure and enable them in [Nile console](https://console.thenile.dev), and then simply drop-in the components. For example, for Discord authentication:
 
-A custom theme can be given to the `NileProvider`, which will theme all components:
+```tsx
+import { DiscordSignInButton } from '@niledatabase/react';
 
-```typescript
 function App() {
   return (
-    <NileProvider theme={theme}>
-      <div>Welcome to my great app</div>
-    </NileProvider>
+    <div>
+      <DiscordSignInButton callbackUrl="/" />
+    </div>
   );
 }
 ```
 
-### useNile
-
-A method exposing the configuration created in `<NileProvider />`. The methods on the instance can be found in [the client src readme](../../lib/nile/src/README.md), or found in the auto-complete of visual studio code.
+### Customizing the components
 
-### Making requests
+Nile’s react package includes a CSS file that you can use to provide a nice default style to the components:
 
-[react-query](https://react-query.tanstack.com/) should be used used to handle loading, error, and cacheing of data.
+```ts
+import "@niledatabase/react/styles.css";
+```
 
-```typescript
-import React, { useEffect } from 'react';
-import { useNile, Queries } from '@niledatabase/react';
-import { useQuery } from '@tanstack/react-query';
+Nile Auth components use CSS variables for theming. This means that you can override the colors and other styles by setting the CSS variables. We support the same CSS variables that [Shadcn uses](https://ui.shadcn.com/docs/theming#list-of-variables). You can modify them in your `global.css` file.
 
-export default function UserTable() {
-  const nile = useNile();
-  const [users, setUsers] = useState();
-  const { data: users = [] } = useQuery(Queries.ListUsers, () => nile.users.listUsers());
-  // with multiple requests
-  // const [{ data: users = [] }, { data: invites = [] }] = useQueries([
-  //   { queryKey: Queries.ListUsers, queryFn: () => nile.users.listUsers({}) },
-  //   { queryKey: Queries.ListInvites, queryFn: () => nile.organizations.listInvites({}) },
-  // ]);
+For "spot changes", you can use the `className` prop of a component to customize it individually:
 
-  return (
-    users.map((user) => {
-      return <div id={user.id}>{`Email: ${user.email}`</div>;
-    })
-  );
-}
+```tsx
+<SignOutButton className="bg-red-500" />
 ```
 
-### UI customization
-
-For theming and display, A combination of [mui joy](https://mui.com/joy-ui/getting-started/overview/) and [material ui](https://mui.com/material-ui/getting-started/overview/) is used. As joy approaches feature parity with material, it will be removed from this codebase. For now, there are helper functions in the theme to support both, with the theming function preferring mui joy settings and colors over material.
-
-For details on theming, see their [theming documentation](https://mui.com/joy-ui/customization/approaches/). You can pass a custom `theme` object to the `NileProvider` and it will merge it with the combined material and joy themes in the `<NileProvider />`.
-
-```typescript
-import { NileProvider } from '@niledatabase/react';
-import { extendTheme } from '@mui/joy/styles';
-const customTheme = extendTheme({
-  colorSchemes: {
-    light: {
-      palette: {
-        primary: {
-          solidBg: '#0078D4',
-          solidHoverBg: '#106EBE',
-          solidActiveBg: '#005A9E',
-          solidDisabledBg: '#F3F2F1',
-          solidDisabledColor: '#A19F9D',
-        },
-      },
-    },
-  },
-});
+## Learn more
 
-function App() {
-  return (
-    <NileProvider theme={customTheme}>
-      <div>Welcome to my great app</div>
-    </NileProvider>
-  );
-}
-```
+- You can learn more about Nile and the SDK in [https://thenile.dev/docs]
+- You can find detailed code examples in [our main repo](https://github.com/niledatabase/niledatabase)
+- Nile SDK interacts with APIs in Nile Auth service. You can learn more about it in the [repository](https://github.com/niledatabase/nile-auth) and the [docs](https://thenile.dev/docs/auth)

package/dist/index.d.mts

@@ -13,7 +13,7 @@ import { BuiltInProviderType, RedirectableProviderType } from 'next-auth/provide
 type EmailSignInInfo = SignInOptions;
 type SignInSuccess = (response: Response) => void;
 type AllowedAny$3 = any;
-type Props$4 = {
+type Props$5 = {
     redirect?: boolean;
     onSuccess?: SignInSuccess;
     onError?: (e: Error, info: EmailSignInInfo) => void;
@@ -24,7 +24,7 @@ type Props$4 = {
     init?: RequestInit;
 };
 
-declare function EmailSigningIn(props: Props$4): React__default.JSX.Element;
+declare function EmailSigningIn(props: Props$5): React__default.JSX.Element;
 
 declare const buttonVariants: (props?: ({
     variant?: "default" | "link" | "destructive" | "outline" | "secondary" | "ghost" | null | undefined;
@@ -41,6 +41,14 @@ type EmailError = void | {
     status: number;
     url: null | string;
 };
+type AllProps = ButtonProps & {
+    callbackUrl?: string;
+    redirect?: boolean;
+    email: string;
+    onSent?: () => void;
+    onFailure?: (error: EmailError) => void;
+    buttonText?: string;
+};
 /**
  * This works when the email identity provider is configured in the admin dashboard.
  * @param props callbackUrl: the url to send the user to from their email
@@ -50,16 +58,12 @@ type EmailError = void | {
  * @param props onFailure:  called if there was a reportable
  * @returns a JSX.Element to render
  */
-declare const EmailSignInButton: React__default.ForwardRefExoticComponent<ButtonProps & {
-    callbackUrl?: string;
-    redirect?: boolean;
-    email: string;
-    onSent?: () => void;
-    onFailure?: (error: EmailError) => void;
-    buttonText?: string;
-} & React__default.RefAttributes<HTMLButtonElement>>;
+declare const EmailSignInButton: {
+    ({ callbackUrl, className, variant, size, asChild, redirect, buttonText, email, onFailure, onSent, ...props }: AllProps): React__default.JSX.Element;
+    displayName: string;
+};
 
-declare function useEmailSignIn(params?: Props$4): _tanstack_react_query.UseMutateFunction<Response, Error, next_auth_react.SignInOptions, unknown>;
+declare function useEmailSignIn(params?: Props$5): _tanstack_react_query.UseMutateFunction<Response, Error, next_auth_react.SignInOptions, unknown>;
 
 /**
  * A component for a Google login button, according to their design language.
@@ -67,53 +71,77 @@ declare function useEmailSignIn(params?: Props$4): _tanstack_react_query.UseMuta
  * @param props callbackUrl: a string to override the URL provided by the context
  * @returns a JSX.Element to render
  */
-declare const GoogleSSOButton: React__default.ForwardRefExoticComponent<ButtonProps & {
-    callbackUrl?: string;
-    buttonText?: string;
-    init?: RequestInit;
-} & React__default.RefAttributes<HTMLButtonElement>>;
+declare const GoogleSSOButton: {
+    ({ callbackUrl, className, variant, size, buttonText, asChild, init, ...props }: ButtonProps & {
+        callbackUrl?: string;
+        buttonText?: string;
+        init?: RequestInit;
+    }): React__default.JSX.Element;
+    displayName: string;
+};
 
-declare const AzureSignInButton: React__default.ForwardRefExoticComponent<ButtonProps & {
-    callbackUrl?: string;
-    buttonText?: string;
-    init?: RequestInit;
-} & React__default.RefAttributes<HTMLButtonElement>>;
+declare const AzureSignInButton: {
+    ({ callbackUrl, className, buttonText, variant, size, init, asChild, ...props }: ButtonProps & {
+        callbackUrl?: string;
+        buttonText?: string;
+        init?: RequestInit;
+    }): React__default.JSX.Element;
+    displayName: string;
+};
 
-declare const DiscordSignInButton: React__default.ForwardRefExoticComponent<ButtonProps & {
-    callbackUrl?: string;
-    buttonText?: string;
-    init?: RequestInit;
-} & React__default.RefAttributes<HTMLButtonElement>>;
+declare const DiscordSignInButton: {
+    ({ callbackUrl, className, buttonText, variant, size, asChild, init, ...props }: ButtonProps & {
+        callbackUrl?: string;
+        buttonText?: string;
+        init?: RequestInit;
+    }): React__default.JSX.Element;
+    displayName: string;
+};
 
-declare const GitHubSignInButton: React__default.ForwardRefExoticComponent<ButtonProps & {
-    callbackUrl?: string;
-    buttonText?: string;
-    init?: RequestInit;
-} & React__default.RefAttributes<HTMLButtonElement>>;
+declare const GitHubSignInButton: {
+    ({ callbackUrl, className, buttonText, variant, size, init, asChild, ...props }: ButtonProps & {
+        callbackUrl?: string;
+        buttonText?: string;
+        init?: RequestInit;
+    }): React__default.JSX.Element;
+    displayName: string;
+};
 
-declare const HubSpotSignInButton: React__default.ForwardRefExoticComponent<ButtonProps & {
-    callbackUrl?: string;
-    buttonText?: string;
-    init?: RequestInit;
-} & React__default.RefAttributes<HTMLButtonElement>>;
+declare const HubSpotSignInButton: {
+    ({ callbackUrl, className, buttonText, variant, size, init, asChild, ...props }: ButtonProps & {
+        callbackUrl?: string;
+        buttonText?: string;
+        init?: RequestInit;
+    }): React__default.JSX.Element;
+    displayName: string;
+};
 
-declare const LinkedInSignInButton: React__default.ForwardRefExoticComponent<ButtonProps & {
-    callbackUrl?: string;
-    buttonText?: string;
-    init?: RequestInit;
-} & React__default.RefAttributes<HTMLButtonElement>>;
+declare const LinkedInSignInButton: {
+    ({ callbackUrl, className, buttonText, variant, size, asChild, init, ...props }: ButtonProps & {
+        callbackUrl?: string;
+        buttonText?: string;
+        init?: RequestInit;
+    }): React__default.JSX.Element;
+    displayName: string;
+};
 
-declare const SlackSignInButton: React__default.ForwardRefExoticComponent<ButtonProps & {
-    callbackUrl?: string;
-    buttonText?: string;
-    init?: ResponseInit;
-} & React__default.RefAttributes<HTMLButtonElement>>;
+declare const SlackSignInButton: {
+    ({ callbackUrl, className, buttonText, variant, size, init, asChild, ...props }: ButtonProps & {
+        callbackUrl?: string;
+        buttonText?: string;
+        init?: RequestInit;
+    }): React__default.JSX.Element;
+    displayName: string;
+};
 
-declare const XSignInButton: React__default.ForwardRefExoticComponent<ButtonProps & {
-    callbackUrl?: string;
-    buttonText?: string;
-    init?: RequestInit;
-} & React__default.RefAttributes<HTMLButtonElement>>;
+declare const XSignInButton: {
+    ({ callbackUrl, className, buttonText, variant, size, init, asChild, ...props }: ButtonProps & {
+        callbackUrl?: string;
+        buttonText?: string;
+        init?: RequestInit;
+    }): React__default.JSX.Element;
+    displayName: string;
+};
 
 type JWT = {
     email: string;
@@ -165,6 +193,7 @@ type Config = {
 type PartialAuthorizer = null | {
     state?: {
         baseUrl?: string;
+        basePath?: string;
         session?: {
             user?: {
                 email?: string | undefined;
@@ -221,6 +250,7 @@ declare class Authorizer {
     initialize(params?: {
         baseUrl?: string;
         session?: NonErrorSession | null | undefined;
+        event?: 'storage' | 'timer' | 'hidden' | 'poll' | 'visibilitychange';
     }): Promise<void>;
     get apiBaseUrl(): string;
     fetchData<T = any>(url: string, init?: RequestInit): Promise<T | undefined>;
@@ -240,6 +270,7 @@ declare class Authorizer {
         baseUrl?: string;
         auth?: Authorizer | PartialAuthorizer;
         fetchUrl?: string;
+        basePath?: string;
     }): Promise<R extends true ? undefined : SignOutResponse>;
     signIn<P extends RedirectableProviderType | undefined = undefined>(provider?: LiteralUnion<P extends RedirectableProviderType ? P | BuiltInProviderType : BuiltInProviderType>, options?: SignInOptions & {
         baseUrl?: string;
@@ -288,7 +319,7 @@ type SignUpInfo = CreateBasicUserRequest & {
     newTenantName?: string;
 };
 type AllowedAny$2 = any;
-type Props$3 = PrefetchParams & {
+type Props$4 = PrefetchParams & {
     onSuccess?: (response: Response, formValues: SignUpInfo) => void;
     onError?: (e: Error, info: SignUpInfo) => void;
     beforeMutate?: (data: AllowedAny$2) => AllowedAny$2;
@@ -299,9 +330,9 @@ type Props$3 = PrefetchParams & {
     redirect?: boolean;
 };
 
-declare function SigningUp({ className, ...props }: Props$3): React__default.JSX.Element;
+declare function SigningUp({ className, ...props }: Props$4): React__default.JSX.Element;
 
-declare function useSignUp<T extends SignUpInfo>(params: Props$3, client?: QueryClient): _tanstack_react_query.UseMutateFunction<any, Error, SignUpInfo, unknown>;
+declare function useSignUp<T extends SignUpInfo>(params: Props$4, client?: QueryClient): _tanstack_react_query.UseMutateFunction<any, Error, SignUpInfo, unknown>;
 
 type AllowedAny$1 = any;
 type LoginInfo = {
@@ -309,7 +340,7 @@ type LoginInfo = {
     password: string;
 };
 type LoginSuccess = (response: AllowedAny$1, formValues: LoginInfo, ...args: AllowedAny$1) => void;
-type Props$2 = ComponentFetchProps & {
+type Props$3 = ComponentFetchProps & {
     beforeMutate?: (data: AllowedAny$1) => AllowedAny$1;
     onSuccess?: LoginSuccess;
     onError?: (error: Error, data: AllowedAny$1) => void;
@@ -320,16 +351,22 @@ type Props$2 = ComponentFetchProps & {
     fetchUrl?: string;
 };
 
-declare function SigningIn({ className, ...props }: Props$2): React__default.JSX.Element;
+declare function SigningIn({ className, ...props }: Props$3): React__default.JSX.Element;
 
-declare function useSignIn(params?: Props$2): _tanstack_react_query.UseMutateFunction<next_auth_react.SignInResponse | undefined, Error, LoginInfo, any>;
+declare function useSignIn(params?: Props$3): _tanstack_react_query.UseMutateFunction<next_auth_react.SignInResponse | undefined, Error, LoginInfo, any>;
 
-declare const SignOutButton: React__default.ForwardRefExoticComponent<ButtonProps & ComponentFetchProps & {
+type Props$2 = ButtonProps & ComponentFetchProps & {
     redirect?: boolean;
     callbackUrl?: string;
     buttonText?: string;
     baseUrl?: string;
-} & React__default.RefAttributes<HTMLButtonElement>>;
+    fetchUrl?: string;
+    basePath?: string;
+};
+declare const SignOutButton: {
+    ({ callbackUrl, redirect, className, buttonText, variant, size, baseUrl, fetchUrl, basePath, auth, asChild, ...props }: Props$2): React__default.JSX.Element;
+    displayName: string;
+};
 
 interface SessionProviderProps {
     children: React__default.ReactNode;
@@ -472,6 +509,7 @@ type Params = PrefetchParams & {
     onSuccess?: (res: Response) => void;
     onError?: (error: Error, data: AllowedAny) => void;
     callbackUrl?: string;
+    basePath?: string;
 };
 type MutateFnParams = {
     email?: string;