Skip to content

Commit 4e8ad0b

Browse files
koppenkoppen
authored
Merge pull request #17 from substancelab/readme
Add README
2 parents 1d32902 + fc8842d commit 4e8ad0b

File tree

1 file changed

+227
-14
lines changed

1 file changed

+227
-14
lines changed

‎README.md‎

Lines changed: 227 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,250 @@
1-
# Flowbite::ViewComponents
1+
# Flowbite ViewComponents
22

3-
Unofficial, open source implementation of Flowbite for use in Rails, built using ViewComponents.
3+
[![Gem Version](https://badge.fury.io/rb/flowbite-view_components.svg)](https://rubygems.org/gems/flowbite-view_components)
4+
[![Ruby Tests](https://github.com/substancelab/flowbite-view_components/workflows/Ruby/badge.svg)](https://github.com/substancelab/flowbite-view_components/actions)
45

5-
TODO: Delete this and the text below, and describe your gem
6+
Unofficial, open source implementation of [Flowbite](https://flowbite.com/) components for Rails applications, built using [ViewComponent](https://viewcomponent.org/).
67

7-
Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/flowbite/view_components`. To experiment with that code, run `bin/console` for an interactive prompt.
8+
Flowbite ViewComponents provides a comprehensive library of UI components following the Flowbite design system, implemented as Rails ViewComponents with full Tailwind CSS integration and dark mode support.
9+
10+
## Features
11+
12+
- **Full Flowbite Design System**: Faithful implementation of Flowbite components
13+
- **Rails Native**: Built specifically for Rails using ViewComponent
14+
- **Tailwind CSS Integration**: Seamless integration with Tailwind CSS
15+
- **Dark Mode Support**: Built-in dark theme variants
16+
- **Form Helpers**: Comprehensive form input components with validation states
17+
- **Accessibility First**: ARIA attributes and semantic HTML
18+
- **Type Safety**: Comprehensive test coverage and input validation
819

920
## Installation
1021

11-
TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
22+
Add the gem to your application's Gemfile:
23+
24+
```ruby
25+
gem 'flowbite-view_components'
26+
```
1227

13-
Install the gem and add to the application's Gemfile by executing:
28+
Then execute:
1429

1530
```bash
16-
bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
31+
bundle install
32+
```
33+
34+
### Configuration
35+
36+
Make sure you have Tailwind CSS installed in your Rails application. We recommend using the [tailwindcss-rails](https://github.com/rails/tailwindcss-rails) gem:
37+
38+
```ruby
39+
gem "tailwindcss-rails", ">= 4.3.0"
1740
```
1841

19-
If bundler is not being used to manage dependencies, install the gem by executing:
42+
### Flowbite Setup
43+
44+
Install Flowbite as an npm dependency:
2045

2146
```bash
22-
gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
47+
npm install flowbite
48+
```
49+
50+
Add Flowbite to your Tailwind CSS configuration. In your `app/assets/tailwind/application.css`:
51+
52+
```css
53+
@import "flowbite/src/themes/default";
54+
@plugin "flowbite/plugin";
55+
@import "../builds/tailwind/flowbite_view_components";
2356
```
2457

25-
## Usage
58+
## Usage examples
59+
60+
### Basic Form Field
61+
62+
```erb
63+
<% form_with model: @user do |form| %>
64+
<%= render Flowbite::InputField::Text.new(
65+
attribute: :name,
66+
form: form,
67+
label: {content: "Full Name"},
68+
hint: {content: "Enter your full name"}
69+
) %>
70+
71+
<%= render Flowbite::InputField::Email.new(
72+
attribute: :email,
73+
form: form
74+
) %>
75+
76+
<%= render Flowbite::Button.new(
77+
type: :submit,
78+
content: "Save User"
79+
) %>
80+
<% end %>
81+
```
82+
83+
### Button Examples
84+
85+
```erb
86+
<!-- Default button -->
87+
<%= render Flowbite::Button.new do %>
88+
Click me
89+
<% end %>
90+
91+
<!-- Outline button with color -->
92+
<%= render Flowbite::Button::Outline.new(style: :blue) do %>
93+
Outline Button
94+
<% end %>
95+
96+
<!-- Pill button -->
97+
<%= render Flowbite::Button::Pill.new(style: :green) do %>
98+
Pill Button
99+
<% end %>
100+
```
101+
102+
### Custom Input Options
103+
104+
```erb
105+
<%= render Flowbite::InputField::Text.new(
106+
attribute: :username,
107+
form: form,
108+
size: :lg,
109+
input: {
110+
options: {
111+
placeholder: "Enter username",
112+
maxlength: 50,
113+
class: "custom-class"
114+
}
115+
}
116+
) %>
117+
```
118+
119+
### Custom Labels
120+
121+
```erb
122+
<%= render Flowbite::InputField::Email.new(
123+
attribute: :email,
124+
form: form,
125+
label: {
126+
content: "Email Address",
127+
options: {class: "font-bold"}
128+
}
129+
) %>
130+
```
131+
132+
### Disabled and Error States
133+
134+
```erb
135+
<!-- Disabled field -->
136+
<%= render Flowbite::InputField::Text.new(
137+
attribute: :name,
138+
form: form,
139+
disabled: true
140+
) %>
141+
142+
<!-- Field with hint -->
143+
<%= render Flowbite::InputField::Password.new(
144+
attribute: :password,
145+
form: form,
146+
hint: "Must be at least 8 characters long"
147+
) %>
148+
```
149+
150+
## Available Components
151+
152+
### Form Components
153+
154+
#### Input Fields (Complete form fields with labels, hints, and error handling)
155+
- **Checkbox**: `Flowbite::InputField::Checkbox`
156+
- **Date**: `Flowbite::InputField::Date`
157+
- **Email**: `Flowbite::InputField::Email`
158+
- **File**: `Flowbite::InputField::File`
159+
- **Number**: `Flowbite::InputField::Number`
160+
- **Password**: `Flowbite::InputField::Password`
161+
- **Phone**: `Flowbite::InputField::Phone`
162+
- **Radio Button**: `Flowbite::InputField::RadioButton`
163+
- **Select**: `Flowbite::InputField::Select`
164+
- **Text**: `Flowbite::InputField::Text`
165+
- **Textarea**: `Flowbite::InputField::Textarea`
166+
- **URL**: `Flowbite::InputField::Url`
167+
168+
#### Basic Input Components (Input elements without labels or wrappers)
169+
- **Checkbox**: `Flowbite::Input::Checkbox`
170+
- **Date**: `Flowbite::Input::Date`
171+
- **Email**: `Flowbite::Input::Email`
172+
- **File**: `Flowbite::Input::File`
173+
- **Number**: `Flowbite::Input::Number`
174+
- **Password**: `Flowbite::Input::Password`
175+
- **Phone**: `Flowbite::Input::Phone`
176+
- **Radio Button**: `Flowbite::Input::RadioButton`
177+
- **Select**: `Flowbite::Input::Select`
178+
- **Textarea**: `Flowbite::Input::Textarea`
179+
- **URL**: `Flowbite::Input::Url`
180+
181+
#### Form Utilities
182+
- **Hint**: `Flowbite::Input::Hint`
183+
- **Label**: `Flowbite::Input::Label`
184+
- **Validation Error**: `Flowbite::Input::ValidationError`
185+
186+
### UI Components
187+
188+
#### Buttons
189+
- **Button**: `Flowbite::Button` (default solid button)
190+
- **Outline Button**: `Flowbite::Button::Outline`
191+
- **Pill Button**: `Flowbite::Button::Pill`
26192

27-
TODO: Write usage instructions here
28193

29194
## Development
30195

31-
After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
196+
After checking out the repo, run `bin/setup` to install dependencies.
197+
198+
To run tests:
199+
200+
```bash
201+
bundle exec rake test
202+
```
203+
204+
To check code style:
32205

33-
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
206+
```bash
207+
bundle exec rake standard
208+
```
209+
210+
To install this gem onto your local machine:
211+
212+
```bash
213+
bundle exec rake install
214+
```
215+
216+
### Component Previews
217+
218+
This library includes Lookbook previews for all components. To view them:
219+
220+
1. Add Lookbook to your development dependencies
221+
2. Run `rails server`
222+
3. Visit `/rails/lookbook`
34223

35224
## Contributing
36225

37-
Bug reports and pull requests are welcome on GitHub at https://github.com/koppen/flowbite-view_components.
226+
Bug reports and pull requests are welcome on GitHub at [https://github.com/substancelab/flowbite-view_components](https://github.com/substancelab/flowbite-view_components).
227+
228+
### Development Guidelines
229+
230+
- All components should follow Flowbite design system specifications
231+
- Use keyword arguments for component initialization
232+
- Include comprehensive tests for all components
233+
- Follow the existing naming conventions
234+
- Ensure accessibility standards are met
235+
236+
## Support
237+
238+
- [Flowbite Documentation](https://flowbite.com/docs/)
239+
- [ViewComponent Documentation](https://viewcomponent.org/)
240+
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
241+
242+
## Other Flowbite component libraries
243+
244+
* https://flowbite-react.com/
245+
* https://flowbite-svelte.com/
246+
* https://flowbite-vue.com/
247+
248+
## License
249+
250+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)