Skip to content

Commit

Permalink
chore: add documentation using vitepress
Browse files Browse the repository at this point in the history
  • Loading branch information
@flozero
flozero committed Aug 30, 2024
1 parent 63d1c6f commit 559b61d
Show file tree
Hide file tree
Showing 3 changed files with 3 additions and 284 deletions.
265 changes: 1 addition & 264 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,267 +21,4 @@ Tailwind Buddy addresses common challenges in managing Tailwind classes for comp

This library is inspired by [CVA](https://cva.style/docs) and [tailwind-variants](https://github.com/nextui-org/tailwind-variants), offering our unique approach to solving common Tailwind challenges.

## Installation

```bash
pnpm add @busbud/tailwind-buddy
```

## Setup compose function

Tailwind buddy expose a `setupCompose` function. Create a `tailwind-buddy-interface.ts`

```ts
import { setupCompose } from "@busbud/tailwind-buddy";

export type Screens = "sm" | "md";
export const screens: Screens[] = ["sm", "md"];
export const compose = setupCompose<Screens>(screens);
```

## Usage

Let's create a button component with two variants, featuring different background colors on mobile and desktop.

```tsx
import { compose } from "../tailwind-buddy-interface.ts";
import type { VariantsProps } from "@busbud/tailwind-buddy";

interface ButtonBaseProps
extends React.ButtonHTMLAttributes<HTMLButtonElement> {
as?: React.ElementType;
}

export const buttonVariants = compose({
slots: {
root: "px-4 py-2 rounded",
},
variants: {
intent: {
primary: "bg-blue-500 text-white",
secondary: "bg-gray-200 text-black",
},
size: {
small: "text-sm",
large: "text-lg",
},
},
defaultVariants: {
intent: "primary",
size: "small",
},
responsiveVariants: ["intent"],
})<ButtonBaseProps>();

export type ButtonProps = VariantsProps<typeof buttonVariants>;

// Usage in a React component
import { twMerge } from "tailwind-merge";

export const Button: React.FC<React.PropsWithChildren<ButtonProps>> = ({
as: Component = "button",
intent,
size,
className,
children,
...restProps
}) => {
const { root } = buttonVariants;

return (
<Component
className={twMerge(
root({
intent: {
initial: "primary",
md: "secondary",
},
size,
className,
})
)}
{...restProps}
>
{children}
</Component>
);
};
```

In this example, we've created a button component with `intent` and `size` variants. The `intent` variant is responsive, changing from `primary` on mobile to `secondary` on desktop.

## Working with Slots

Slots allow you to break down components into smaller parts while using the same props. Here's an example:

```tsx
export const cardVariants = compose({
slots: {
root: "rounded overflow-hidden",
header: "p-4 bg-gray-100",
body: "p-4",
},
variants: {
size: {
small: {
root: "max-w-sm",
header: "text-sm",
body: "text-base",
},
large: {
root: "max-w-lg",
header: "text-lg",
body: "text-xl",
},
},
},
defaultVariants: {
size: "small",
},
})();

export const Card = () => {
// Usage
const { root, header, body } = cardVariants;

return (
<div className={twMerge(root({ size: "large" }))}>
<div className={twMerge(header({ size: "large" }))}>header</div>
<div className={twMerge(body())}>body</div>
</div>
);
};
```

## Compound Variants

Compound variants allow you to apply styles when multiple variant conditions are met:

```tsx
export const buttonVariants = compose({
// ... previous definitions ...
compoundVariants: [
{
conditions: {
intent: "primary",
size: "large",
},
class: "font-bold",
},
],
})();
```

## Responsive Variants

To enable responsive variants:

1. Add the variant to the `responsiveVariants` array in your compose function.
2. Update your Tailwind config to include necessary classes in the safelist.

```tsx
// In your variant definition
export const buttonVariants = compose({
// ... other configurations ...
responsiveVariants: ["intent"],
})();

// Usage in a React component
import { twMerge } from "tailwind-merge";

// class .font-bold will be applied as the condition is fulfilled.
export const Button: React.FC<{}> = () => {
const { root } = buttonVariants;

return (
<button
className={twMerge(
root({
intent: "primary",
size: large,
})
)}
>
Go
</button>
);
};

// In your Tailwind config
import { generateSafeList } from "@busbud/tailwind-buddy";
import { buttonVariants } from "./path-to-your-variants";

// As you now Expect responsive for this component make sure to import the buttonVariants
export default {
// ... other Tailwind configurations ...
theme: {
screens: screens, // ["sm", "md"]
},
safelist: generateSafeList([buttonVariants]), // those values are required to align with tailwind breakpoints and make them available as in the example above
//
};
```

## extraPerformanceDisabled

We do not support writing a variant definition using template string. You can enable it by updating your setupCompose:

```ts
export const compose = setupCompose<Screens>(screens, {
extraPerformanceDisabled: true,
});
```

Take in consideration that this is going to drop the performance hard check the benchmarks for more information.

## Tailwind Autocomplete in VSCode (Optional)

For Tailwind class autocomplete in VSCode, add the following to your `.vscode/settings.json`:

```json
{
"editor.quickSuggestions": {
"strings": "on"
},
"css.validate": false,
"editor.inlineSuggest.enabled": true,
"tailwindCSS.classAttributes": [
"class",
"className",
".*Styles.",
".*Classes."
],
"tailwindCSS.experimental.classRegex": ["@tw\\s\\*/\\s+[\"'`]([^\"'`]*)"]
}
```

With this setup, you can use `/** @tw */` before your Tailwind classes to enable autocompletion.

## Local Development

1. Install pnpm: `npm i -g pnpm`
2. In the root folder:
- `nvm use`
- `pnpm install`
3. In the `core` folder:
- `pnpm build -w`
- For unit tests: `pnpm test:unit`

For a "real world example":

1. In the `ui` folder:
- `pnpm install`
- `pnpm build -w`
2. In the `sandbox` folder:
- `pnpm install`
- `pnpm dev`

## Contributing

First easy contribution would be to help on improving the documentation.

After that make sure to look at [good first issue label on github.](https://github.com/busbud/tailwind-buddy/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)

## Benchmarks

![Screenshot 2024-08-30 at 2 31 12 AM](https://github.com/user-attachments/assets/af963ec2-1e8e-49e2-898f-452b2454a303)
## [Documentation](https://busbud.github.io/tailwind-buddy)
4 changes: 1 addition & 3 deletions packages/core/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1 @@
# Tailwind Buddy: Your Friendly Helper for Composing Tailwind Classes 🎨

Go to our [main documentation](https://github.com/busbud/tailwind-buddy) to know how to use the package
## [Documentation](https://busbud.github.io/tailwind-buddy)
18 changes: 1 addition & 17 deletions packages/ui/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1 @@
# This is the design system example project that is using tailwind buddy

[Refer to the document for more](../../README.md)

## Run the project

```
pnpm install
pnpm build
or
pnpm build -w #if you want to have live update
```

[Go to sandbox to now check your updates](../sandbox/README.md)
## [Documentation](https://busbud.github.io/tailwind-buddy)

0 comments on commit 559b61d

Please sign in to comment.