Skip to content

Commit

Permalink
Merge pull request #17 from busbud/feat/adding-documentation
Browse files Browse the repository at this point in the history 
feat: adding documentation
  • Loading branch information
@flozero
flozero committed Aug 30, 2024
2 parents 936486f + e3137c0 commit 3b69b99
Show file tree
Hide file tree
Showing 40 changed files with 32,183 additions and 286 deletions.
63 changes: 63 additions & 0 deletions .github/workflows/deploy-documentation.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Sample workflow for building and deploying a VitePress site to GitHub Pages
#
name: Deploy VitePress site to Pages

on:
# Runs on pushes targeting the `main` branch. Change this to `master` if you're
# using the `master` branch as the default branch.
push:
branches: [main]

# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: pages
cancel-in-progress: false

jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # Not needed if lastUpdated is not enabled
- uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Install dependencies
run: pnpm install
- name: Build with VitePress
run: pnpm docs:build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist

# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
needs: build
runs-on: ubuntu-latest
name: Deploy
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
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
//
};
```

## disablePerformance

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, {
disablePerformance: 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 10 20 51 AM](https://github.com/user-attachments/assets/152ca2a5-cc42-4987-adb1-65c052c8cd51)
## [Documentation](https://busbud.github.io/tailwind-buddy)
8 changes: 6 additions & 2 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,17 @@
"commit": "commit",
"tailwindbuddy:release": "pnpm --filter './packages/core' release",
"tailwindbuddy:test": "pnpm --filter './packages/core' test:ci",
"tailwindbuddy:build": "pnpm --filter './packages/core' build"
"tailwindbuddy:build": "pnpm --filter './packages/core' build",
"docs:dev": "vitepress dev packages/documentation",
"docs:build": "vitepress build packages/documentation",
"docs:preview": "vitepress preview packages/documentation"
},
"devDependencies": {
"@commitlint/cli": "^19.2.1",
"@commitlint/config-conventional": "^19.1.0",
"@commitlint/prompt-cli": "^19.2.0",
"husky": "3.1.0"
"husky": "3.1.0",
"vitepress": "^1.3.4"
},
"husky": {
"hooks": {
Expand Down
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)
Loading

0 comments on commit 3b69b99

Please sign in to comment.