Skip to content

Commit a1585ff

Browse files
EhespEhesp
authored
Merge branch '@invertase/v7-development' into @invertase/align-update-angular
2 parents 1a9410d + c341c78 commit a1585ff

File tree

5 files changed

+428
-0
lines changed

5 files changed

+428
-0
lines changed

‎GEMINI.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Firebase UI for Web
2+
3+
A library for building UIs with Firebase, with first class support for Angular and shad (with Shadcn).
4+
5+
## General rules
6+
7+
- The workspace is managed with pnpm. Always use pnpm commands for installation and execution.
8+
- This is a monorepo, with `packages` and `examples` sub-directories.
9+
- Linting is controlled by ESLint, via a root flatconfig `eslint.config.ts` file. Run `pnpm lint:check` for linting errors.
10+
- Formatting is controlled vi Prettier integrated with ESLint via the `.prettierrc` file. Run `pnpm format:check` for formatting errors.
11+
- The workspace uses pnpm cataloges to ensure dependency version alignment. If a dependency exists twice, it should be cataloged.
12+
- Tests can be run for the entire workspace via `pnpm test` or scoped to a package via `test:<name>`.
13+
14+
## Structure
15+
16+
The project structure is setup in a way which provides a framework agnostic set of packages; `core`, `translations` and `styles`.
17+
18+
- `core`: The main entry-point to the package via `initalizeUI`. Firebase UI provides it's own functional exports, which when called wraps the Firebase JS SDK functionality, however manages state, translated error handling and behaviors (configurable by the user).
19+
- `translations`: A package exporting utilities and translation mappings for various languages, which `core` depends on.
20+
- `styles`: A package providing CSS utility classes which frameworks can use to provide consistent styling. The `styles` package works for existing Tailwind users, but also exports a distributable file with compiled "tailwindless" CSS. The CSS styles heavily depend on CSS variables for customization.
21+
22+
Additionally, framework specific packages depend on these agnostic packages to offer full integration with the frameworks:
23+
24+
- `react`: Exposes React UI components (in the form of screens, full page components, or forms, the bare-bones UI forms) & hooks, enabling users to easily build their own UIs or consume the built in ones.
25+
- `angular`: Exposes Angular UI components (in the form of screens, full page components, or forms, the bare-bones UI forms) & DI functionality, enabling users to easily build their own UIs or consume the built in ones. This package depends directly on AngularFire.
26+
27+
The dependency graph is:
28+
29+
```
30+
graph TD
31+
core --> translations;
32+
react --> core;
33+
angular --> core;
34+
angular --> styles;
35+
react --> styles;
36+
shadcn --> react;
37+
```
38+
39+
## Misc
40+
41+
- All packages extend the same base `tsconfig.json` file.
42+
- Where possible, prefer Vitest testing framework.
43+
44+
## Additional Context
45+
46+
- `core`: @./packages/core/GEMINI.md
47+
- `react`: @./packages/react/GEMINI.md
48+
- `styles`: @./packages/styles/GEMINI.md
49+
- `translations`: @./packages/translations/GEMINI.md

‎packages/core/GEMINI.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Firebase UI Core
2+
3+
This document provides context for the `@firebase-ui/core` package.
4+
5+
## Overview
6+
7+
The `@firebase-ui/core` package is the framework-agnostic core of the Firebase UI for Web library. It provides a set of functions and utilities for building UIs with Firebase Authentication. The core package is designed to be used by framework-specific packages like `@firebase-ui/react` and `@firebase-ui/angular`, but it can also be used directly to build custom UIs.
8+
9+
## Usage
10+
11+
The main entry point to the core package is the `initializeUI` function. This function takes a configuration object and returns a `FirebaseUI` instance, which is a `nanostores` store that holds the configuration and state of the UI.
12+
13+
```typescript
14+
import { initializeUI } from "@firebase-ui/core";
15+
import { enUs } from "@firebase-ui/translations";
16+
import { firebaseApp } from "./firebase";
17+
18+
const ui = initializeUI({
19+
app: firebaseApp,
20+
locale: enUs,
21+
behaviors: [
22+
// ...
23+
],
24+
});
25+
```
26+
27+
The `FirebaseUI` instance can then be used to call the various authentication functions, such as `signInWithEmailAndPassword`, `createUserWithEmailAndPassword`, etc.
28+
29+
```typescript
30+
import { initializeUI, signInWithEmailAndPassword } from "@firebase-ui/core";
31+
32+
const ui = initializeUI({
33+
// ... your config
34+
});
35+
36+
async function signIn(email, password) {
37+
await signInWithEmailAndPassword(ui, email, password);
38+
}
39+
```
40+
41+
## Behaviors
42+
43+
Behaviors are a way to customize the functionality of the Firebase UI. They are functions that are executed at different points in the authentication process. For example, the `requireDisplayName` behavior can be used to require the user to enter a display name when signing up.
44+
45+
Behaviors are passed to the `initializeUI` function in the `behaviors` array.
46+
47+
```typescript
48+
import { initializeUI, requireDisplayName } from "@firebase-ui/core";
49+
50+
const ui = initializeUI({
51+
// ...
52+
behaviors: [
53+
requireDisplayName(),
54+
],
55+
});
56+
```
57+
58+
## State Management
59+
60+
The core package uses `nanostores` for state management. The `FirebaseUI` instance is a `nanostores` store that holds the configuration and state of the UI. The state can be one of the following:
61+
62+
* `idle`: The UI is idle.
63+
* `pending`: The UI is waiting for an asynchronous operation to complete.
64+
* `loading`: The UI is loading.
65+
66+
The state can be accessed from the `state` property of the `FirebaseUI` instance.
67+
68+
```typescript
69+
import { useStore } from "@nanostores/react";
70+
import { ui } from "./firebase"; // assuming ui is exported from a firebase config file
71+
72+
function MyComponent() {
73+
const { state } = useStore(ui);
74+
75+
if (state === "pending") {
76+
return <p>Loading...</p>;
77+
}
78+
79+
return <p>Idle</p>;
80+
}
81+
```

‎packages/react/GEMINI.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Firebase UI React
2+
3+
This document provides context for the `@firebase-ui/react` package.
4+
5+
## Overview
6+
7+
The `@firebase-ui/react` package provides a set of React components and hooks to integrate Firebase UI for Web into a React application. It builds on top of `@firebase-ui/core` and `@firebase-ui/styles` to provide a seamless integration with the React ecosystem.
8+
9+
The package offers two main ways to build your UI:
10+
11+
1. **Pre-built Components**: A set of ready-to-use components for common authentication screens (e.g., Sign In, Register).
12+
2. **Hooks**: A collection of React hooks that provide access to the underlying UI state and authentication logic, allowing you to build fully custom UIs.
13+
14+
## Setup
15+
16+
To use the React package, you must first initialize Firebase UI using `initializeUI` from the core package, and then wrap your application with the `FirebaseUIProvider`.
17+
18+
```tsx
19+
// In your main App.tsx or a similar entry point
20+
21+
import { initializeUI } from "@firebase-ui/core";
22+
import { enUs } from "@firebase-ui/translations";
23+
import { FirebaseUIProvider } from "@firebase-ui/react";
24+
import { firebaseApp } from "./firebase"; // Your firebase config
25+
26+
// 1. Initialize the UI
27+
const ui = initializeUI({
28+
app: firebaseApp,
29+
locale: enUs,
30+
// ... other configurations
31+
});
32+
33+
function App() {
34+
// 2. Wrap your app in the provider
35+
return (
36+
<FirebaseUIProvider ui={ui}>
37+
{/* Your application components */}
38+
<SignInScreen />
39+
</FirebaseUIProvider>
40+
);
41+
}
42+
```
43+
44+
## Pre-built Components
45+
46+
The package includes several pre-built "screen" components for a quick setup. These components render a full-page authentication form.
47+
48+
**Example: Sign-In Screen**
49+
50+
```tsx
51+
import { SignInScreen } from "@firebase-ui/react";
52+
53+
function MySignInPage() {
54+
return <SignInScreen />;
55+
}
56+
```
57+
58+
Other available components include `RegisterScreen`, `ForgotPasswordScreen`, etc.
59+
60+
## Hooks
61+
62+
Hooks are the recommended way to build a custom user interface.
63+
64+
### `useUI()`
65+
66+
The main hook is `useUI()`. It returns the entire UI state object from the underlying `nanostores` store. This gives you access to the current `state` (`idle`, `pending`, `error`), any `error` messages, and the `auth` instance.
67+
68+
**Example: Custom Button**
69+
70+
```tsx
71+
import { useUI } from "@firebase-ui/react";
72+
import { signInWithEmailAndPassword } from "@firebase-ui/core";
73+
74+
function CustomSignInButton() {
75+
const ui = useUI();
76+
77+
const handleClick = () => {
78+
// Functions from @firebase-ui/core require the `ui` instance
79+
signInWithEmailAndPassword(ui, "[email protected]", "password");
80+
};
81+
82+
return (
83+
<button onClick={handleClick} disabled={ui.state === "pending"}>
84+
{ui.state === "pending" ? "Signing in..." : "Sign In"}
85+
</button>
86+
);
87+
}
88+
```
89+
90+
### Other Hooks
91+
92+
The package also provides other specialized hooks:
93+
94+
- `useSignInAuthFormSchema()`: Returns a Zod schema for sign-in form validation.
95+
- `useSignUpAuthFormSchema()`: Returns a Zod schema for sign-up form validation.
96+
- `useRecaptchaVerifier()`: A hook to easily integrate a reCAPTCHA verifier.

‎packages/styles/GEMINI.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Firebase UI Styles
2+
3+
This document provides context for the `@firebase-ui/styles` package.
4+
5+
## Overview
6+
7+
The `@firebase-ui/styles` package provides the core styling for all Firebase UI for Web components. It is framework-agnostic and offers multiple ways to be consumed.
8+
9+
1. **CSS Files**: For direct use in projects. It provides different files depending on whether you use Tailwind CSS.
10+
2. **Component Variants**: It exports utilities using `cva` (Class Variance Authority) to programmatically apply styles, which is useful when building custom components.
11+
12+
A key feature of this package is its heavy reliance on CSS variables for theming, allowing for extensive customization of the UI's appearance.
13+
14+
## CSS Usage
15+
16+
Depending on your project's setup, you can include the styles in one of two ways.
17+
18+
### With Tailwind CSS
19+
20+
If your project uses Tailwind CSS, you should import the `tailwind` entry point directly into your main CSS file. This file contains the necessary base styles.
21+
22+
```css
23+
/* In your global styles.css */
24+
@import "@firebase-ui/styles/tailwind";
25+
```
26+
27+
### Without Tailwind CSS
28+
29+
If you are not using Tailwind CSS, you can import the pre-compiled distributed file in your main application entry point (e.g., `main.ts` or `App.tsx`):
30+
31+
```javascript
32+
// In your main application file
33+
import "@firebase-ui/styles";
34+
```
35+
36+
## Component Variants (CVA)
37+
38+
For developers building their own component libraries, this package exports `cva` configurations. This allows you to generate the correct CSS classes for different component variants.
39+
40+
Currently, it exports a `buttonVariant` helper.
41+
42+
### Example
43+
44+
Here is how you might use it in a React component:
45+
46+
```tsx
47+
import { buttonVariant, ButtonVariant } from "@firebase-ui/styles";
48+
import { type ComponentProps } from "react";
49+
50+
interface ButtonProps extends ComponentProps<"button"> {
51+
variant?: ButtonVariant;
52+
}
53+
54+
function Button({ className, variant, ...props }: ButtonProps) {
55+
return (
56+
<button
57+
className={buttonVariant({ variant, className })}
58+
{...props}
59+
/>
60+
);
61+
}
62+
```
63+
64+
## Customization
65+
66+
The look and feel of the components can be customized by overriding the CSS variables defined in this package. You can redefine these variables in your own stylesheet under a `:root` or other selector.
67+
68+
For example, to change the primary color and the radius of cards:
69+
70+
```css
71+
72+
:root {
73+
--fui-primary: #007bff; /* Change to a shade of blue */
74+
--fui-radius-card: 1rem; /* Change to a larger corner radius */
75+
}
76+
```
77+
78+
Here are some of the core variables available for theming:
79+
80+
- `--fui-primary`: The primary color for buttons and links.
81+
- `--fui-primary-hover`: The hover state for primary elements.
82+
- `--fui-primary-surface`: The text color used on primary-colored surfaces.
83+
- `--fui-text`: The main body text color.
84+
- `--fui-background`: The background color for card elements.
85+
- `--fui-border`: The default border color.
86+
- `--fui-radius`: The border radius for inputs.
87+
- `--fui-radius-card`: The border radius for cards.

0 commit comments

Comments
 (0)