From ba786f253e04be45d3e77e848bcda4fe54ec7e16 Mon Sep 17 00:00:00 2001 From: Terry Sutton Date: Fri, 28 Mar 2025 15:48:47 -0230 Subject: [PATCH] UI lib/component docs (#34515) * Update usage sections * Small style tweaks * Update docs, tan capital S stack everywhere * Fix the colors of the linkedcard. * MInor fixes for all doc pages. * Updates * Spacing --------- Co-authored-by: Ivan Vasilov --- apps/ui-library/app/(app)/layout.tsx | 2 +- apps/ui-library/components/mdx-components.tsx | 6 +- .../ui-library/components/side-navigation.tsx | 2 +- apps/ui-library/config/docs.ts | 2 +- .../docs/nextjs/current-user-avatar.mdx | 29 ++++- .../content/docs/nextjs/dropzone.mdx | 34 +++++- .../docs/nextjs/password-based-auth.mdx | 2 +- .../docs/nextjs/realtime-avatar-stack.mdx | 21 +++- .../content/docs/nextjs/realtime-cursor.mdx | 29 +++-- .../content/docs/react-router/client.mdx | 20 +++- .../docs/react-router/current-user-avatar.mdx | 27 ++++- .../content/docs/react-router/dropzone.mdx | 67 ++++++++--- .../docs/react-router/password-based-auth.mdx | 2 +- .../react-router/realtime-avatar-stack.mdx | 21 +++- .../docs/react-router/realtime-cursor.mdx | 43 ++++++- apps/ui-library/content/docs/react/client.mdx | 19 +++ .../docs/react/current-user-avatar.mdx | 27 ++++- .../content/docs/react/dropzone.mdx | 67 ++++++++--- .../docs/react/password-based-auth.mdx | 110 +++++++++++++----- .../docs/react/realtime-avatar-stack.mdx | 21 +++- .../content/docs/react/realtime-cursor.mdx | 43 ++++++- .../content/docs/tanstack/client.mdx | 32 +++-- .../docs/tanstack/current-user-avatar.mdx | 27 ++++- .../content/docs/tanstack/dropzone.mdx | 67 ++++++++--- .../docs/tanstack/password-based-auth.mdx | 68 +++++++++-- .../docs/tanstack/realtime-avatar-stack.mdx | 21 +++- .../content/docs/tanstack/realtime-cursor.mdx | 43 ++++++- apps/ui-library/public/llms.txt | 8 +- apps/ui-library/registry.json | 2 +- .../clients/tanstack/registry-item.json | 2 +- 30 files changed, 716 insertions(+), 148 deletions(-) diff --git a/apps/ui-library/app/(app)/layout.tsx b/apps/ui-library/app/(app)/layout.tsx index fcb11fde12..51cb622b08 100644 --- a/apps/ui-library/app/(app)/layout.tsx +++ b/apps/ui-library/app/(app)/layout.tsx @@ -19,7 +19,7 @@ export default function AppLayout({ children }: AppLayoutProps) { {/* {children} */}
-
-
+
{gettingStarted.title}
diff --git a/apps/ui-library/config/docs.ts b/apps/ui-library/config/docs.ts index 628e0eb336..eaff6135da 100644 --- a/apps/ui-library/config/docs.ts +++ b/apps/ui-library/config/docs.ts @@ -45,7 +45,7 @@ export const aiEditorsRules: SidebarNavGroup = { export const frameworkTitles: Record = { nextjs: 'Next.js', 'react-router': 'React Router', - tanstack: 'Tanstack Start', + tanstack: 'TanStack Start', react: 'React SPA', } diff --git a/apps/ui-library/content/docs/nextjs/current-user-avatar.mdx b/apps/ui-library/content/docs/nextjs/current-user-avatar.mdx index e02f5e6a4a..9f0bffd341 100644 --- a/apps/ui-library/content/docs/nextjs/current-user-avatar.mdx +++ b/apps/ui-library/content/docs/nextjs/current-user-avatar.mdx @@ -16,9 +16,32 @@ description: Supabase Auth-aware avatar -## Usage +## Introduction The `CurrentUserAvatar` component connects to Supabase Auth to fetch the user data and show an avatar. It uses the `user_metadata` -property which gets populated automatically by Supabase Auth if the user logged in via a provider. If the user doesn't have a profile image, it renders their initials. If the user is logged out, it renders a `?`. +property which gets populated automatically by Supabase Auth if the user logged in via a provider. If the user doesn't have a profile image, it renders their initials. If the user is logged out, it renders a `?` as a fallback, which you can change. -The `CurrentUserAvatar` component integrates with Supabase Auth to display user avatars dynamically. It automatically retrieves the profile image from the `user_metadata` field, which Supabase Auth populates when using provider-based authentication. The component also fallbacks to `?` if the user is unauthenticated. +## Usage + +The `CurrentUserAvatar` component is designed to be used anywhere in your app. Add the `` component to your page and it will render the avatar of the current user, with a fallback. + +```tsx +'use client' + +import { CurrentUserAvatar } from '@/components/current-user-avatar' + +const CurrentUserAvatarDemo = () => { + return ( +
+

Lumon Industries

+ +
+ ) +} + +export default CurrentUserAvatarDemo +``` + +## Props + +This component doesn't accept any props. If you wish to change the fallback, you can do so by changing the `CurrentUserAvatar` component directly. diff --git a/apps/ui-library/content/docs/nextjs/dropzone.mdx b/apps/ui-library/content/docs/nextjs/dropzone.mdx index 947ca43539..ec292d2a74 100644 --- a/apps/ui-library/content/docs/nextjs/dropzone.mdx +++ b/apps/ui-library/content/docs/nextjs/dropzone.mdx @@ -25,7 +25,7 @@ Uploading files should be easy—this component handles the tricky parts for you The File Upload component makes it easy to add file uploads to your app, with built-in support for drag-and-drop, file type restrictions, image previews, and configurable limits on file size and number of files. All the essentials, ready to go. -## Features +**Features** - Drag-and-drop support - Multiple file uploads @@ -40,6 +40,38 @@ The File Upload component makes it easy to add file uploads to your app, with bu - Simply add this `` component to your page and it will handle the rest. - For control over file upload, you can pass in a `props` object to the component. +```tsx +'use client' + +import { + Dropzone, + DropzoneContent, + DropzoneEmptyState, +} from '@/components/dropzone' +import { useSupabaseUpload } from '@/hooks/use-supabase-upload' + +const FileUploadDemo = () => { + const props = useSupabaseUpload({ + bucketName: 'test', + path: 'test', + allowedMimeTypes: ['image/*'], + maxFiles: 2, + maxFileSize: 1000 * 1000 * 10, // 10MB, + }) + + return ( +
+ + + + +
+ ) +} + +export FileUploadDemo +``` + ## Props | Prop | Type | Default | Description | diff --git a/apps/ui-library/content/docs/nextjs/password-based-auth.mdx b/apps/ui-library/content/docs/nextjs/password-based-auth.mdx index 7f128c40ab..3eade617e0 100644 --- a/apps/ui-library/content/docs/nextjs/password-based-auth.mdx +++ b/apps/ui-library/content/docs/nextjs/password-based-auth.mdx @@ -70,7 +70,7 @@ NEXT_PUBLIC_SUPABASE_ANON_KEY= ### Setting up routes and redirect URLs 1. Set the site URL in the [URL Configuration](https://supabase.com/dashboard/project/_/auth/url-configuration) settings in the Supabase Dashboard. -1. Set up the Next.js route users will visit to reset or update their password. First, update the `forgot-password-form.tsx` component with your `forgot-password` route. You'll need to tell Supabase to allow this route as the redirect URL. Go to the [URL Configuration](https://supabase.com/dashboard/project/_/auth/url-configuration) settings and add that route to the list of Redirect URLs. It should look something like: `http://example.com/auth/forgot-password`. +1. Set up the Next.js route that users will visit to reset or update their password. Go to the [URL Configuration](https://supabase.com/dashboard/project/_/auth/url-configuration) settings and add the `forgot-password` route to the list of Redirect URLs. It should look something like: `http://example.com/auth/forgot-password`. 1. Update the redirect paths in the `login-form.tsx` and `update-password-form.tsx` components to point to the logged-in routes in your app. diff --git a/apps/ui-library/content/docs/nextjs/realtime-avatar-stack.mdx b/apps/ui-library/content/docs/nextjs/realtime-avatar-stack.mdx index 3d2d9375f5..9aee437e4e 100644 --- a/apps/ui-library/content/docs/nextjs/realtime-avatar-stack.mdx +++ b/apps/ui-library/content/docs/nextjs/realtime-avatar-stack.mdx @@ -18,4 +18,23 @@ description: Avatar stack in realtime ## Usage -The `RealtimeAvatarStack` renders stacked avatars which are connected to Supabase Realtime. Specifically, it uses the Presence feature. You can use this to show currently online users in a chatroom, game session or collaborative app. +The `RealtimeAvatarStack` component renders stacked avatars which are connected to Supabase Realtime. It uses the Presence feature of Supabase Realtime. You can use this to show currently online users in a chatroom, game session or collaborative app. + +```tsx +import { RealtimeAvatarStack } from '@/components/realtime-avatar-stack' + +export default function Page() { + return ( +
+

Lumon Industries

+ +
+ ) +} +``` + +## Props + +| Prop | Type | Default | Description | +| ---------- | -------- | ------- | ---------------------------------------------------- | +| `roomName` | `string` | `null` | The name of the Supabase Realtime room to connect to | diff --git a/apps/ui-library/content/docs/nextjs/realtime-cursor.mdx b/apps/ui-library/content/docs/nextjs/realtime-cursor.mdx index c8bd255788..170ddb0ee1 100644 --- a/apps/ui-library/content/docs/nextjs/realtime-cursor.mdx +++ b/apps/ui-library/content/docs/nextjs/realtime-cursor.mdx @@ -4,10 +4,8 @@ description: Real-time cursor sharing for collaborative applications ---
- - - - + +
## Installation @@ -25,11 +23,7 @@ description: Real-time cursor sharing for collaborative applications The Realtime Cursors component lets users share their cursor position with others in the same room—perfect for real-time collaboration. It handles all the setup and boilerplate for you, so you can add it to your app with minimal effort. -## Usage - -The Realtime Cursor component is designed to be used in a room. It can be used to build real-time collaborative applications. Add the `` component to your page and it will render realtime cursors from other users in the room. - -## Features +**Features** - Broadcast cursor position to other users in the same room - Customizable cursor appearance @@ -37,6 +31,23 @@ The Realtime Cursor component is designed to be used in a room. It can be used t - Low-latency updates using Supabase Realtime - Room-based isolation for scoped collaboration +## Usage + +The Realtime Cursor component is designed to be used in a room. It can be used to build real-time collaborative applications. Add the `` component to your page and it will render realtime cursors from other users in the room. + +```tsx +'use client' +import { RealtimeCursors } from '@/components/realtime-cursors' + +export default function Page() { + return ( +
+ +
+ ) +} +``` + ## Props | Prop | Type | Description | diff --git a/apps/ui-library/content/docs/react-router/client.mdx b/apps/ui-library/content/docs/react-router/client.mdx index 214297dd5e..dba310eb09 100644 --- a/apps/ui-library/content/docs/react-router/client.mdx +++ b/apps/ui-library/content/docs/react-router/client.mdx @@ -11,5 +11,21 @@ description: Supabase client for React Router -This block provides Supabase clients designed for use with SSR by storing JWT tokens in cookies. If you're -developing a React SPA, use the [React SPA client](/ui/docs/react-router/client) instead. +## Usage + +This block installs Supabase clients for connecting your React Router project to Supabase. They're designed for use in both server-side loaders and actions, as well as client-side components. + +If you've already set up Supabase clients in your project, you can just continue using them. + +### Getting started + +First, add a `.env` file to your project with the following environment variables: + +```env +VITE_SUPABASE_URL= +VITE_SUPABASE_ANON_KEY= +``` + +- If you're using supabase.com, you can find these values in the [Connect modal](https://supabase.com/dashboard/project/_?showConnect=true) under App Frameworks or in your project's [API settings](https://supabase.com/dashboard/project/_/settings/api). + +- If you're using a local instance of supabase, you can find these values by running `supabase start` or `supabase status` (if you already have it running). diff --git a/apps/ui-library/content/docs/react-router/current-user-avatar.mdx b/apps/ui-library/content/docs/react-router/current-user-avatar.mdx index d962179a6b..ed58e790dd 100644 --- a/apps/ui-library/content/docs/react-router/current-user-avatar.mdx +++ b/apps/ui-library/content/docs/react-router/current-user-avatar.mdx @@ -16,9 +16,30 @@ description: Supabase Auth-aware avatar -## Usage +## Introduction The `CurrentUserAvatar` component connects to Supabase Auth to fetch the user data and show an avatar. It uses the `user_metadata` -property which gets populated automatically by Supabase Auth if the user logged in via a provider. If the user doesn't have a profile image, it renders their initials. If the user is logged out, it renders a `?`. +property which gets populated automatically by Supabase Auth if the user logged in via a provider. If the user doesn't have a profile image, it renders their initials. If the user is logged out, it renders a `?` as a fallback, which you can change. -The `CurrentUserAvatar` component integrates with Supabase Auth to display user avatars dynamically. It automatically retrieves the profile image from the `user_metadata` field, which Supabase Auth populates when using provider-based authentication. The component also fallbacks to `?` if the user is unauthenticated. +## Usage + +The `CurrentUserAvatar` component is designed to be used anywhere in your app. Add the `` component to your page and it will render the avatar of the current user, with a fallback. + +```tsx +import { CurrentUserAvatar } from '@/components/current-user-avatar' + +const CurrentUserAvatarDemo = () => { + return ( +
+

Lumon Industries

+ +
+ ) +} + +export default CurrentUserAvatarDemo +``` + +## Props + +This component doesn't accept any props. If you wish to change the fallback, you can do so by changing the `CurrentUserAvatar` component directly. diff --git a/apps/ui-library/content/docs/react-router/dropzone.mdx b/apps/ui-library/content/docs/react-router/dropzone.mdx index c746c1031a..390a4b87bd 100644 --- a/apps/ui-library/content/docs/react-router/dropzone.mdx +++ b/apps/ui-library/content/docs/react-router/dropzone.mdx @@ -21,24 +21,61 @@ description: Displays a control for easier uploading of files directly to Supaba ## Introduction -The File Upload component is designed to allow users to upload files with specific features and restrictions. It supports drag-and-drop functionality, MIME type restrictions, image previews, and configurable limits on file size and number of files. +Uploading files should be easy—this component handles the tricky parts for you. -## Features +The File Upload component makes it easy to add file uploads to your app, with built-in support for drag-and-drop, file type restrictions, image previews, and configurable limits on file size and number of files. All the essentials, ready to go. -1. **Drag-and-Drop**. Support drag-and-drop functionality for adding files. +**Features** -1. **MIME Type Restriction**. Only allow specific MIME types. - -1. **Invalid File Handling**. Allow users to remove invalid files from the list. Display a tooltip with error information for invalid files. - -1. **Image Previews**. Display previews for image files. - -1. **Error Handling**. Show error messages if the upload fails due to network or server errors. - -1. **Success Handling**. Display a success message and clear the file list upon successful upload. - -1. **Configurable Limits**. Allow configuration of file size limits and the maximum number of files. +- Drag-and-drop support +- Multiple file uploads +- File size and count limits +- Image previews for supported file types +- MIME type restrictions +- Invalid file handling +- Success and error states with clear feedback ## Usage -## Examples +- Simply add this `` component to your page and it will handle the rest. +- For control over file upload, you can pass in a `props` object to the component. + +```tsx +import { + Dropzone, + DropzoneContent, + DropzoneEmptyState, +} from '@/components/dropzone' +import { useSupabaseUpload } from '@/hooks/use-supabase-upload' + +const FileUploadDemo = () => { + const props = useSupabaseUpload({ + bucketName: 'test', + path: 'test', + allowedMimeTypes: ['image/*'], + maxFiles: 2, + maxFileSize: 1000 * 1000 * 10, // 10MB, + }) + + return ( +
+ + + + +
+ ) +} + +export FileUploadDemo +``` + +## Props + +| Prop | Type | Default | Description | +| ------------------ | ---------- | ------- | ---------------------------------------------------- | +| `bucketName` | `string` | `null` | The name of the Supabase Storage bucket to upload to | +| `path` | `string` | `null` | The path or subfolder to upload the file to | +| `allowedMimeTypes` | `string[]` | `[]` | The MIME types to allow for upload | +| `maxFiles` | `number` | `1` | Maximum number of files to upload | +| `maxFileSize` | `number` | `1000` | Maximum file size in bytes | diff --git a/apps/ui-library/content/docs/react-router/password-based-auth.mdx b/apps/ui-library/content/docs/react-router/password-based-auth.mdx index 6281d2f512..c2133d9f9a 100644 --- a/apps/ui-library/content/docs/react-router/password-based-auth.mdx +++ b/apps/ui-library/content/docs/react-router/password-based-auth.mdx @@ -70,6 +70,6 @@ VITE_SUPABASE_ANON_KEY= ### Setting up routes and redirect URLs 1. Set the site URL in the [URL Configuration](https://supabase.com/dashboard/project/_/auth/url-configuration) settings in the Supabase Dashboard. -1. Set up the route users will visit to reset or update their password. First, update the `forgot-password.tsx` component with your `update-password` route. You'll need to tell Supabase to allow this route as the redirect URL. Go to the [URL Configuration](https://supabase.com/dashboard/project/_/auth/url-configuration) settings and add that route to the list of Redirect URLs. It should look something like: `http://example.com/update-password`. +1. Set up the route users will visit to reset or update their password. Go to the [URL Configuration](https://supabase.com/dashboard/project/_/auth/url-configuration) settings and add the `forgot-password` route to the list of Redirect URLs. It should look something like: `http://example.com/auth/forgot-password`. 1. Update the redirect paths in the `login.tsx` and `update-password.tsx` components to point to the logged-in routes in your app. diff --git a/apps/ui-library/content/docs/react-router/realtime-avatar-stack.mdx b/apps/ui-library/content/docs/react-router/realtime-avatar-stack.mdx index dd48141fda..08e2b2d126 100644 --- a/apps/ui-library/content/docs/react-router/realtime-avatar-stack.mdx +++ b/apps/ui-library/content/docs/react-router/realtime-avatar-stack.mdx @@ -18,4 +18,23 @@ description: Avatar stack in realtime ## Usage -The `RealtimeAvatarStack` renders stacked avatars which are connected to Supabase Realtime. Specifically, it uses the Presence feature. You can use this to show currently online users in a chatroom, game session or collaborative app. +The `RealtimeAvatarStack` component renders stacked avatars which are connected to Supabase Realtime. It uses the Presence feature of Supabase Realtime. You can use this to show currently online users in a chatroom, game session or collaborative app. + +```tsx +import { RealtimeAvatarStack } from '@/components/realtime-avatar-stack' + +export default function Page() { + return ( +
+

Lumon Industries

+ +
+ ) +} +``` + +## Props + +| Prop | Type | Default | Description | +| ---------- | -------- | ------- | ---------------------------------------------------- | +| `roomName` | `string` | `null` | The name of the Supabase Realtime room to connect to | diff --git a/apps/ui-library/content/docs/react-router/realtime-cursor.mdx b/apps/ui-library/content/docs/react-router/realtime-cursor.mdx index 7a7c47490b..e0d9d6f98d 100644 --- a/apps/ui-library/content/docs/react-router/realtime-cursor.mdx +++ b/apps/ui-library/content/docs/react-router/realtime-cursor.mdx @@ -3,16 +3,16 @@ title: Realtime Cursor description: Real-time cursor sharing for collaborative applications --- - +
+ + +
## Installation ## Folder structure @@ -20,3 +20,36 @@ description: Real-time cursor sharing for collaborative applications ## Introduction + +The Realtime Cursors component lets users share their cursor position with others in the same room—perfect for real-time collaboration. It handles all the setup and boilerplate for you, so you can add it to your app with minimal effort. + +**Features** + +- Broadcast cursor position to other users in the same room +- Customizable cursor appearance +- Presence detection (automatically joins/leaves users) +- Low-latency updates using Supabase Realtime +- Room-based isolation for scoped collaboration + +## Usage + +The Realtime Cursor component is designed to be used in a room. It can be used to build real-time collaborative applications. Add the `` component to your page and it will render realtime cursors from other users in the room. + +```tsx +import { RealtimeCursors } from '@/components/realtime-cursors' + +export default function Page() { + return ( +
+ +
+ ) +} +``` + +## Props + +| Prop | Type | Description | +| ---------- | -------- | ---------------------------------------------------------- | +| `roomName` | `string` | Unique identifier for the shared room or session. | +| `username` | `string` | Name of the current user; used to track and label cursors. | diff --git a/apps/ui-library/content/docs/react/client.mdx b/apps/ui-library/content/docs/react/client.mdx index 2aa3af05b1..a09946ac17 100644 --- a/apps/ui-library/content/docs/react/client.mdx +++ b/apps/ui-library/content/docs/react/client.mdx @@ -10,3 +10,22 @@ description: Supabase client for React Single Page Applications ## Folder structure + +## Usage + +This block installs a Supabase client for connecting your React project to Supabase. It's designed for use in client-side components. + +If you've already set up a Supabase client in your project, you can just continue using that existing setup. + +### Getting started + +First, add a `.env` file to your project with the following environment variables: + +```env +VITE_SUPABASE_URL= +VITE_SUPABASE_ANON_KEY= +``` + +- If you're using supabase.com, you can find these values in the [Connect modal](https://supabase.com/dashboard/project/_?showConnect=true) under App Frameworks or in your project's [API settings](https://supabase.com/dashboard/project/_/settings/api). + +- If you're using a local instance of Supabase, you can find these values by running `supabase start` or `supabase status` (if you already have it running). diff --git a/apps/ui-library/content/docs/react/current-user-avatar.mdx b/apps/ui-library/content/docs/react/current-user-avatar.mdx index d5a5dcd46a..ce3e0cd241 100644 --- a/apps/ui-library/content/docs/react/current-user-avatar.mdx +++ b/apps/ui-library/content/docs/react/current-user-avatar.mdx @@ -13,9 +13,30 @@ description: Supabase Auth-aware avatar -## Usage +## Introduction The `CurrentUserAvatar` component connects to Supabase Auth to fetch the user data and show an avatar. It uses the `user_metadata` -property which gets populated automatically by Supabase Auth if the user logged in via a provider. If the user doesn't have a profile image, it renders their initials. If the user is logged out, it renders a `?`. +property which gets populated automatically by Supabase Auth if the user logged in via a provider. If the user doesn't have a profile image, it renders their initials. If the user is logged out, it renders a `?` as a fallback, which you can change. -The `CurrentUserAvatar` component integrates with Supabase Auth to display user avatars dynamically. It automatically retrieves the profile image from the `user_metadata` field, which Supabase Auth populates when using provider-based authentication. The component also fallbacks to `?` if the user is unauthenticated. +## Usage + +The `CurrentUserAvatar` component is designed to be used anywhere in your app. Add the `` component to your page and it will render the avatar of the current user, with a fallback. + +```tsx +import { CurrentUserAvatar } from '@/components/current-user-avatar' + +const CurrentUserAvatarDemo = () => { + return ( +
+

Lumon Industries

+ +
+ ) +} + +export default CurrentUserAvatarDemo +``` + +## Props + +This component doesn't accept any props. If you wish to change the fallback, you can do so by changing the `CurrentUserAvatar` component directly. diff --git a/apps/ui-library/content/docs/react/dropzone.mdx b/apps/ui-library/content/docs/react/dropzone.mdx index 2dead7ff23..42dd37cb26 100644 --- a/apps/ui-library/content/docs/react/dropzone.mdx +++ b/apps/ui-library/content/docs/react/dropzone.mdx @@ -21,24 +21,61 @@ description: Displays a control for easier uploading of files directly to Supaba ## Introduction -The File Upload component is designed to allow users to upload files with specific features and restrictions. It supports drag-and-drop functionality, MIME type restrictions, image previews, and configurable limits on file size and number of files. +Uploading files should be easy—this component handles the tricky parts for you. -## Features +The File Upload component makes it easy to add file uploads to your app, with built-in support for drag-and-drop, file type restrictions, image previews, and configurable limits on file size and number of files. All the essentials, ready to go. -1. **Drag-and-Drop**. Support drag-and-drop functionality for adding files. +**Features** -1. **MIME Type Restriction**. Only allow specific MIME types. - -1. **Invalid File Handling**. Allow users to remove invalid files from the list. Display a tooltip with error information for invalid files. - -1. **Image Previews**. Display previews for image files. - -1. **Error Handling**. Show error messages if the upload fails due to network or server errors. - -1. **Success Handling**. Display a success message and clear the file list upon successful upload. - -1. **Configurable Limits**. Allow configuration of file size limits and the maximum number of files. +- Drag-and-drop support +- Multiple file uploads +- File size and count limits +- Image previews for supported file types +- MIME type restrictions +- Invalid file handling +- Success and error states with clear feedback ## Usage -## Examples +- Simply add this `` component to your page and it will handle the rest. +- For control over file upload, you can pass in a `props` object to the component. + +```tsx +import { + Dropzone, + DropzoneContent, + DropzoneEmptyState, +} from '@/components/dropzone' +import { useSupabaseUpload } from '@/hooks/use-supabase-upload' + +const FileUploadDemo = () => { + const props = useSupabaseUpload({ + bucketName: 'test', + path: 'test', + allowedMimeTypes: ['image/*'], + maxFiles: 2, + maxFileSize: 1000 * 1000 * 10, // 10MB, + }) + + return ( +
+ + + + +
+ ) +} + +export FileUploadDemo +``` + +## Props + +| Prop | Type | Default | Description | +| ------------------ | ---------- | ------- | ---------------------------------------------------- | +| `bucketName` | `string` | `null` | The name of the Supabase Storage bucket to upload to | +| `path` | `string` | `null` | The path or subfolder to upload the file to | +| `allowedMimeTypes` | `string[]` | `[]` | The MIME types to allow for upload | +| `maxFiles` | `number` | `1` | Maximum number of files to upload | +| `maxFileSize` | `number` | `1000` | Maximum file size in bytes | diff --git a/apps/ui-library/content/docs/react/password-based-auth.mdx b/apps/ui-library/content/docs/react/password-based-auth.mdx index b674afea51..a7ffabcce8 100644 --- a/apps/ui-library/content/docs/react/password-based-auth.mdx +++ b/apps/ui-library/content/docs/react/password-based-auth.mdx @@ -3,6 +3,8 @@ title: Password-based Authentication description: Password-based authentication block for React Single Page Applications --- + + ## Installation { - const checkAuth = async () => { - const client = createClient(); - const { error } = await client.auth.getUser(); +First, add a `.env` file to your project with the following environment variables: - if (error) { - location.href = "/login"; - } - }; - checkAuth(); - }, []); +```env +VITE_SUPABASE_URL= +VITE_SUPABASE_ANON_KEY= ``` -4. Update the redirect upon successful login in `login-form.tsx` and `update-password.tsx` to `/info`. -5. Test the rest of the flows. +- If you're using supabase.com, you can find these values in the [Connect modal](https://supabase.com/dashboard/project/_?showConnect=true) under App Frameworks or in your project's [API settings](https://supabase.com/dashboard/project/_/settings/api). -There few more steps to finish the installation: +- If you're using a local instance of supabase, you can find these values by running `supabase start` or `supabase status` (if you already have it running). -1. Set the `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_ANON_KEY` environment variables in your `.env` file in your project. -1. Add an [email template for sign-up](https://supabase.com/dashboard/project/uznvnxvfhkixgqetwekc/auth/templates) to the Supabase project. For detailed instructions on how to configure your email - templates, including the use of variables like `{{ .SiteURL }}`,`{{ .TokenHash }}`, and `{{ .RedirectTo }}`, refer to our [Email Templates guide](/docs/email-templates). +### Adding email templates - Your signup email template should contain the following HTML: +1. Add an [email template for sign-up](https://supabase.com/dashboard/project/_/auth/templates) to the Supabase project. Your signup email template should contain at least the following HTML: ```html

Confirm your signup

@@ -59,8 +47,74 @@ There few more steps to finish the installation: >Confirm your email

-```` + ``` -1. Set the site URL in the [Supabase dashboard](https://supabase.com/dashboard/project/_/auth/url-configuration). -1. Set the forgot-password route in `forgot-password-form.tsx` component. The route needs to be configured as a redirect URL in the [Supabase dashboard](https://supabase.com/dashboard/project/_/auth/url-configuration). -1. Update the redirect paths in the `login-form.tsx` and `update-password-form.tsx` components to point to the logged-in routes in your app. + For detailed instructions on how to configure your email templates, including the use of variables like `{{ .SiteURL }}`,`{{ .TokenHash }}`, and `{{ .RedirectTo }}`, refer to our [Email Templates guide](https://supabase.com/docs/email-templates). + +1. Add an [email template for reset password](https://supabase.com/dashboard/project/_/auth/templates) to the Supabase project. Your reset password email template should contain at least the following HTML: + + ```html +

Reset Password

+ +

Follow this link to reset the password for your user:

+

+ Reset Password +

+ ``` + +### Setting up routes and redirect URLs + +1. Set the site URL in the [URL Configuration](https://supabase.com/dashboard/project/_/auth/url-configuration) settings in the Supabase Dashboard. +1. Set up the route users will visit to reset or update their password. Go to the [URL Configuration](https://supabase.com/dashboard/project/_/auth/url-configuration) settings and add the `forgot-password` route to the list of Redirect URLs. It should look something like: `http://example.com/auth/forgot-password`. +1. Update the redirect paths in the `login.tsx` and `update-password.tsx` components to point to the logged-in routes in your app. + +1. Add the following code in the authenticated route to redirect to login if the user is unauthenticated. + +## Examples + +### Redirect to `/login` page if the user is unauthenticated + +```ts +import { useEffect } from "react" +import { createClient } from "@supabase/supabase-js" + +export default function AuthenticatedRoute() { + useEffect(() => { + const checkAuth = async () => { + const client = createClient() + const { error } = await client.auth.getUser() + + if (error) { + location.href = "/login" + } + } + checkAuth() + }, []) + + return
Authenticated page
; +} +``` + +### Redirect to `/profile` page if the user is authenticated + +```ts +import { useEffect } from "react"; +import { createClient } from "@supabase/supabase-js" + +export default function AuthenticatedRoute() { + useEffect(() => { + const checkAuth = async () => { + const client = createClient() + const { user } = await client.auth.getUser() + + user ? location.href = "/profile" : location.href = "/login" + } + checkAuth() + }, []) + + return
Profile page
+} +``` diff --git a/apps/ui-library/content/docs/react/realtime-avatar-stack.mdx b/apps/ui-library/content/docs/react/realtime-avatar-stack.mdx index 33ced96f95..663581a848 100644 --- a/apps/ui-library/content/docs/react/realtime-avatar-stack.mdx +++ b/apps/ui-library/content/docs/react/realtime-avatar-stack.mdx @@ -18,4 +18,23 @@ description: Avatar stack in realtime ## Usage -The `RealtimeAvatarStack` renders stacked avatars which are connected to Supabase Realtime. Specifically, it uses the Presence feature. You can use this to show currently online users in a chatroom, game session or collaborative app. +The `RealtimeAvatarStack` component renders stacked avatars which are connected to Supabase Realtime. It uses the Presence feature of Supabase Realtime. You can use this to show currently online users in a chatroom, game session or collaborative app. + +```tsx +import { RealtimeAvatarStack } from '@/components/realtime-avatar-stack' + +export default function Page() { + return ( +
+

Lumon Industries

+ +
+ ) +} +``` + +## Props + +| Prop | Type | Default | Description | +| ---------- | -------- | ------- | ---------------------------------------------------- | +| `roomName` | `string` | `null` | The name of the Supabase Realtime room to connect to | diff --git a/apps/ui-library/content/docs/react/realtime-cursor.mdx b/apps/ui-library/content/docs/react/realtime-cursor.mdx index a439d167ad..d4800cbdc1 100644 --- a/apps/ui-library/content/docs/react/realtime-cursor.mdx +++ b/apps/ui-library/content/docs/react/realtime-cursor.mdx @@ -3,16 +3,16 @@ title: Realtime Cursor description: Real-time cursor sharing for collaborative applications --- - +
+ + +
## Installation ## Folder structure @@ -20,3 +20,36 @@ description: Real-time cursor sharing for collaborative applications ## Introduction + +The Realtime Cursors component lets users share their cursor position with others in the same room—perfect for real-time collaboration. It handles all the setup and boilerplate for you, so you can add it to your app with minimal effort. + +**Features** + +- Broadcast cursor position to other users in the same room +- Customizable cursor appearance +- Presence detection (automatically joins/leaves users) +- Low-latency updates using Supabase Realtime +- Room-based isolation for scoped collaboration + +## Usage + +The Realtime Cursor component is designed to be used in a room. It can be used to build real-time collaborative applications. Add the `` component to your page and it will render realtime cursors from other users in the room. + +```tsx +import { RealtimeCursors } from '@/components/realtime-cursors' + +export default function Page() { + return ( +
+ +
+ ) +} +``` + +## Props + +| Prop | Type | Description | +| ---------- | -------- | ---------------------------------------------------------- | +| `roomName` | `string` | Unique identifier for the shared room or session. | +| `username` | `string` | Name of the current user; used to track and label cursors. | diff --git a/apps/ui-library/content/docs/tanstack/client.mdx b/apps/ui-library/content/docs/tanstack/client.mdx index 7ab51bba1f..bbf7646507 100644 --- a/apps/ui-library/content/docs/tanstack/client.mdx +++ b/apps/ui-library/content/docs/tanstack/client.mdx @@ -1,21 +1,31 @@ --- -title: Tanstack Start -description: Supabase client for Tanstack Start +title: TanStack Start +description: Supabase client for TanStack Start --- ## Installation - - -The easiest way to use Tanstack Start with Supabase is to follow the following steps: - -1. Follow the [official guide](https://ui.shadcn.com/docs/installation/tanstack) for adding shadcn/ui to Tanstack Start -2. Install this block to get the Supabase clients -3. Add VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY to your .env file + ## Folder structure -This block provides Supabase clients designed for use with SSR by storing JWT tokens in cookies. If you're -developing a React SPA, use the [React SPA client](/ui/docs/react-router/client) instead. +## Usage + +This block installs Supabase clients for connecting your TanStack Start project to Supabase. They're designed for use in both server-side loaders and actions, as well as client-side components. + +If you've already set up a Supabase client in your project, you can just continue using that existing setup. + +### Getting started + +First, add a `.env` file to your project with the following environment variables: + +```env +VITE_SUPABASE_URL= +VITE_SUPABASE_ANON_KEY= +``` + +- If you're using supabase.com, you can find these values in the [Connect modal](https://supabase.com/dashboard/project/_?showConnect=true) under App Frameworks or in your project's [API settings](https://supabase.com/dashboard/project/_/settings/api). + +- If you're using a local instance of Supabase, you can find these values by running `supabase start` or `supabase status` (if you already have it running). diff --git a/apps/ui-library/content/docs/tanstack/current-user-avatar.mdx b/apps/ui-library/content/docs/tanstack/current-user-avatar.mdx index 746b06d5cb..59f7b55c52 100644 --- a/apps/ui-library/content/docs/tanstack/current-user-avatar.mdx +++ b/apps/ui-library/content/docs/tanstack/current-user-avatar.mdx @@ -16,9 +16,30 @@ description: Supabase Auth-aware avatar -## Usage +## Introduction The `CurrentUserAvatar` component connects to Supabase Auth to fetch the user data and show an avatar. It uses the `user_metadata` -property which gets populated automatically by Supabase Auth if the user logged in via a provider. If the user doesn't have a profile image, it renders their initials. If the user is logged out, it renders a `?`. +property which gets populated automatically by Supabase Auth if the user logged in via a provider. If the user doesn't have a profile image, it renders their initials. If the user is logged out, it renders a `?` as a fallback, which you can change. -The `CurrentUserAvatar` component integrates with Supabase Auth to display user avatars dynamically. It automatically retrieves the profile image from the `user_metadata` field, which Supabase Auth populates when using provider-based authentication. The component also fallbacks to `?` if the user is unauthenticated. +## Usage + +The `CurrentUserAvatar` component is designed to be used anywhere in your app. Add the `` component to your page and it will render the avatar of the current user, with a fallback. + +```tsx +import { CurrentUserAvatar } from '@/components/current-user-avatar' + +const CurrentUserAvatarDemo = () => { + return ( +
+

Lumon Industries

+ +
+ ) +} + +export default CurrentUserAvatarDemo +``` + +## Props + +This component doesn't accept any props. If you wish to change the fallback, you can do so by changing the `CurrentUserAvatar` component directly. diff --git a/apps/ui-library/content/docs/tanstack/dropzone.mdx b/apps/ui-library/content/docs/tanstack/dropzone.mdx index e6a4281902..cddb750a05 100644 --- a/apps/ui-library/content/docs/tanstack/dropzone.mdx +++ b/apps/ui-library/content/docs/tanstack/dropzone.mdx @@ -21,24 +21,61 @@ description: Displays a control for easier uploading of files directly to Supaba ## Introduction -The File Upload component is designed to allow users to upload files with specific features and restrictions. It supports drag-and-drop functionality, MIME type restrictions, image previews, and configurable limits on file size and number of files. +Uploading files should be easy—this component handles the tricky parts for you. -## Features +The File Upload component makes it easy to add file uploads to your app, with built-in support for drag-and-drop, file type restrictions, image previews, and configurable limits on file size and number of files. All the essentials, ready to go. -1. **Drag-and-Drop**. Support drag-and-drop functionality for adding files. +**Features** -1. **MIME Type Restriction**. Only allow specific MIME types. - -1. **Invalid File Handling**. Allow users to remove invalid files from the list. Display a tooltip with error information for invalid files. - -1. **Image Previews**. Display previews for image files. - -1. **Error Handling**. Show error messages if the upload fails due to network or server errors. - -1. **Success Handling**. Display a success message and clear the file list upon successful upload. - -1. **Configurable Limits**. Allow configuration of file size limits and the maximum number of files. +- Drag-and-drop support +- Multiple file uploads +- File size and count limits +- Image previews for supported file types +- MIME type restrictions +- Invalid file handling +- Success and error states with clear feedback ## Usage -## Examples +- Simply add this `` component to your page and it will handle the rest. +- For control over file upload, you can pass in a `props` object to the component. + +```tsx +import { + Dropzone, + DropzoneContent, + DropzoneEmptyState, +} from '@/components/dropzone' +import { useSupabaseUpload } from '@/hooks/use-supabase-upload' + +const FileUploadDemo = () => { + const props = useSupabaseUpload({ + bucketName: 'test', + path: 'test', + allowedMimeTypes: ['image/*'], + maxFiles: 2, + maxFileSize: 1000 * 1000 * 10, // 10MB, + }) + + return ( +
+ + + + +
+ ) +} + +export FileUploadDemo +``` + +## Props + +| Prop | Type | Default | Description | +| ------------------ | ---------- | ------- | ---------------------------------------------------- | +| `bucketName` | `string` | `null` | The name of the Supabase Storage bucket to upload to | +| `path` | `string` | `null` | The path or subfolder to upload the file to | +| `allowedMimeTypes` | `string[]` | `[]` | The MIME types to allow for upload | +| `maxFiles` | `number` | `1` | Maximum number of files to upload | +| `maxFileSize` | `number` | `1000` | Maximum file size in bytes | diff --git a/apps/ui-library/content/docs/tanstack/password-based-auth.mdx b/apps/ui-library/content/docs/tanstack/password-based-auth.mdx index 5d648efa33..9a453aaf81 100644 --- a/apps/ui-library/content/docs/tanstack/password-based-auth.mdx +++ b/apps/ui-library/content/docs/tanstack/password-based-auth.mdx @@ -1,16 +1,70 @@ --- -title: Tanstack Start -description: Supabase client for Tanstack Start +title: TanStack Start +description: Supabase client for TanStack Start --- + + ## Installation - - -1. Follow the steps in /ui/docs/tanstack/password-based-auth to setup your repo. - -2. Try to access the /info route, you should be redirected to login screen. If you create an account and login and try accessing the /info page, you should see your email. + ## Folder structure + +## Usage + +Once you install the block in your TanStack Start project, you'll get all the necessary pages and components to set up a password-based authentication flow. + +### Getting started + +First, add a `.env` file to your project with the following environment variables: + +```env +VITE_SUPABASE_URL= +VITE_SUPABASE_ANON_KEY= +``` + +- If you're using supabase.com, you can find these values in the [Connect modal](https://supabase.com/dashboard/project/_?showConnect=true) under App Frameworks or in your project's [API settings](https://supabase.com/dashboard/project/_/settings/api). + +- If you're using a local instance of supabase, you can find these values by running `supabase start` or `supabase status` (if you already have it running). + +### Adding email templates + +1. Add an [email template for sign-up](https://supabase.com/dashboard/project/_/auth/templates) to the Supabase project. Your signup email template should contain at least the following HTML: + + ```html +

Confirm your signup

+ +

Follow this link to confirm your user:

+

+ Confirm your email +

+ ``` + + For detailed instructions on how to configure your email templates, including the use of variables like `{{ .SiteURL }}`,`{{ .TokenHash }}`, and `{{ .RedirectTo }}`, refer to our [Email Templates guide](https://supabase.com/docs/email-templates). + +1. Add an [email template for reset password](https://supabase.com/dashboard/project/_/auth/templates) to the Supabase project. Your reset password email template should contain at least the following HTML: + + ```html +

Reset Password

+ +

Follow this link to reset the password for your user:

+

+ Reset Password +

+ ``` + +### Setting up routes and redirect URLs + +1. Set the site URL in the [URL Configuration](https://supabase.com/dashboard/project/_/auth/url-configuration) settings in the Supabase Dashboard. +1. Set up the route users will visit to reset or update their password. Go to the [URL Configuration](https://supabase.com/dashboard/project/_/auth/url-configuration) settings and add the `forgot-password` route to the list of Redirect URLs. It should look something like: `http://example.com/auth/forgot-password`. + +1. Update the redirect paths in the `login.tsx` and `update-password.tsx` components to point to the logged-in routes in your app. diff --git a/apps/ui-library/content/docs/tanstack/realtime-avatar-stack.mdx b/apps/ui-library/content/docs/tanstack/realtime-avatar-stack.mdx index a7d588531c..5f9211e838 100644 --- a/apps/ui-library/content/docs/tanstack/realtime-avatar-stack.mdx +++ b/apps/ui-library/content/docs/tanstack/realtime-avatar-stack.mdx @@ -18,4 +18,23 @@ description: Avatar stack in realtime ## Usage -The `RealtimeAvatarStack` renders stacked avatars which are connected to Supabase Realtime. Specifically, it uses the Presence feature. You can use this to show currently online users in a chatroom, game session or collaborative app. +The `RealtimeAvatarStack` component renders stacked avatars which are connected to Supabase Realtime. It uses the Presence feature of Supabase Realtime. You can use this to show currently online users in a chatroom, game session or collaborative app. + +```tsx +import { RealtimeAvatarStack } from '@/components/realtime-avatar-stack' + +export default function Page() { + return ( +
+

Lumon Industries

+ +
+ ) +} +``` + +## Props + +| Prop | Type | Default | Description | +| ---------- | -------- | ------- | ---------------------------------------------------- | +| `roomName` | `string` | `null` | The name of the Supabase Realtime room to connect to | diff --git a/apps/ui-library/content/docs/tanstack/realtime-cursor.mdx b/apps/ui-library/content/docs/tanstack/realtime-cursor.mdx index 6711ea14b7..0d92b11095 100644 --- a/apps/ui-library/content/docs/tanstack/realtime-cursor.mdx +++ b/apps/ui-library/content/docs/tanstack/realtime-cursor.mdx @@ -3,16 +3,16 @@ title: Realtime Cursor description: Real-time cursor sharing for collaborative applications --- - +
+ + +
## Installation ## Folder structure @@ -20,3 +20,36 @@ description: Real-time cursor sharing for collaborative applications ## Introduction + +The Realtime Cursors component lets users share their cursor position with others in the same room—perfect for real-time collaboration. It handles all the setup and boilerplate for you, so you can add it to your app with minimal effort. + +**Features** + +- Broadcast cursor position to other users in the same room +- Customizable cursor appearance +- Presence detection (automatically joins/leaves users) +- Low-latency updates using Supabase Realtime +- Room-based isolation for scoped collaboration + +## Usage + +The Realtime Cursor component is designed to be used in a room. It can be used to build real-time collaborative applications. Add the `` component to your page and it will render realtime cursors from other users in the room. + +```tsx +import { RealtimeCursors } from '@/components/realtime-cursors' + +export default function Page() { + return ( +
+ +
+ ) +} +``` + +## Props + +| Prop | Type | Description | +| ---------- | -------- | ---------------------------------------------------------- | +| `roomName` | `string` | Unique identifier for the shared room or session. | +| `username` | `string` | Name of the current user; used to track and label cursors. | diff --git a/apps/ui-library/public/llms.txt b/apps/ui-library/public/llms.txt index 06a25248e6..a88fe2f8ee 100644 --- a/apps/ui-library/public/llms.txt +++ b/apps/ui-library/public/llms.txt @@ -49,14 +49,14 @@ Library of components for your project. The components integrate with Supabase a - Avatar stack in realtime - [Realtime Cursor](https://supabase.com/ui/docs/react/realtime-cursor) - Real-time cursor sharing for collaborative applications -- [Tanstack Start](https://supabase.com/ui/docs/tanstack/client) - - Supabase client for Tanstack Start +- [TanStack Start](https://supabase.com/ui/docs/tanstack/client) + - Supabase client for TanStack Start - [Current User Avatar](https://supabase.com/ui/docs/tanstack/current-user-avatar) - Supabase Auth-aware avatar - [Dropzone (File Upload)](https://supabase.com/ui/docs/tanstack/dropzone) - Displays a control for easier uploading of files directly to Supabase Storage -- [Tanstack Start](https://supabase.com/ui/docs/tanstack/password-based-auth) - - Supabase client for Tanstack Start +- [TanStack Start](https://supabase.com/ui/docs/tanstack/password-based-auth) + - Supabase client for TanStack Start - [Realtime Avatar Stack](https://supabase.com/ui/docs/tanstack/realtime-avatar-stack) - Avatar stack in realtime - [Realtime Cursor](https://supabase.com/ui/docs/tanstack/realtime-cursor) diff --git a/apps/ui-library/registry.json b/apps/ui-library/registry.json index 983db290a2..d4cfe3690f 100644 --- a/apps/ui-library/registry.json +++ b/apps/ui-library/registry.json @@ -854,7 +854,7 @@ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "supabase-client-tanstack", "type": "registry:lib", - "title": "Supabase Client for Tanstack Start", + "title": "Supabase Client for TanStack Start", "description": "", "registryDependencies": [], "dependencies": ["@supabase/ssr@latest", "@supabase/supabase-js@latest"], diff --git a/apps/ui-library/registry/default/clients/tanstack/registry-item.json b/apps/ui-library/registry/default/clients/tanstack/registry-item.json index 5c86eee251..7aeaf49dba 100644 --- a/apps/ui-library/registry/default/clients/tanstack/registry-item.json +++ b/apps/ui-library/registry/default/clients/tanstack/registry-item.json @@ -2,7 +2,7 @@ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "supabase-client-tanstack", "type": "registry:lib", - "title": "Supabase Client for Tanstack Start", + "title": "Supabase Client for TanStack Start", "description": "", "registryDependencies": [], "dependencies": ["@supabase/ssr@latest", "@supabase/supabase-js@latest"],