# @graphprotocol/gds-react

React components for The Graph Design System.

## Installation

```bash
pnpm add @graphprotocol/gds-react
```

### Peer Dependencies

This package requires the following peer dependencies:

```bash
pnpm add react react-dom react-is tailwindcss
```

## Setup

1. Ensure [Tailwind CSS is installed and configured](https://tailwindcss.com/docs/installation) in your project (preferably with Vite).

2. Replace the `tailwind` import in your main CSS file with `@graphprotocol/gds-react`:

   ```diff
   - @import 'tailwindcss';
   + @import '@graphprotocol/gds-react';
   ```

3. [Register source paths](https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources) relative to your CSS file:

   ```diff
     @import '@graphprotocol/gds-react';
   + @source '../src';
   ```

   `@graphprotocol/gds-react` disables Tailwind's default content scanning as an optimization measure, so you must explicitly register your source paths using `@source` directives. Make sure to include all paths where Tailwind classes are used.

4. Wrap your app with `GDSProvider`:

   ```tsx
   import { GDSProvider } from '@graphprotocol/gds-react'

   function App() {
     return <GDSProvider>{/* your app */}</GDSProvider>
   }
   ```

   The provider accepts optional props:
   - `theme` - `'dark'` (default), `'light'`, or `'system'`
   - `direction` - `'ltr'` (default) or `'rtl'`
   - `language` - defaults to `'en'` as long as `direction` is `'ltr'`

5. Optional recommended steps:
   - If you use VS Code (or a fork like Cursor), install the [Tailwind CSS IntelliSense extension](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss).
     - If it doesn't automatically recognize GDS-specific classes like `text-16`, it is likely because it cannot find the CSS file that registers GDS's Tailwind theme and plugin (which can happen in monorepos or projects with unusual/complex directory structures). Add the following to `.vscode/settings.json` and customize the paths to match your project:

       ```json
       {
         "tailwindCSS.experimental.configFile": {
           "packages/ui/globals.css": "packages/ui/**"
         }
       }
       ```

   - If you use Prettier, install [`prettier-plugin-tailwindcss`](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) and add it to your config (e.g. `.prettierrc`):

     ```json
     {
       "plugins": ["prettier-plugin-tailwindcss"],
       "tailwindPreserveWhitespace": true,
       "tailwindFunctions": ["cn"],
       "overrides": [
         {
           "files": "packages/ui/**",
           "options": {
             "tailwindStylesheet": "packages/ui/globals.css"
           }
         }
       ]
     }
     ```

     Make sure to customize the paths to match your project (`files` should match any file that contains classes, and `tailwindStylesheet` should point to your main CSS file, from which you imported GDS).

That's it, you're ready to use GDS utilities and components!

## Usage

```tsx
import { Button, Card, Input } from '@graphprotocol/gds-react'

function Example() {
  return (
    <Card>
      <Input label="Enter text..." />
      <Button variant="primary">Submit</Button>
    </Card>
  )
}
```

## Exports

- `@graphprotocol/gds-react` - Styled components
- `@graphprotocol/gds-react/base` - Base/primitive (mostly unstyled) components
- `@graphprotocol/gds-react/hooks` - React hooks that are useful when working with GDS components
- `@graphprotocol/gds-react/icons` - React components for `gds-icons`
- `@graphprotocol/gds-react/utils` - React-specific utility functions

## License

MIT
