The frontend framework from Garden Party
Garden Party is a Ruby on Rails application. It's administrative section is plain old Rails views, and the app part is written with VueJS 3.
The CSS used in the project had to be both available to VueJS components as to administrative views, so:
- you can use only the CSS, without VueJS
- you should be able to pick only the CSS components you need by using the SCSS files
- styles are not scoped in VueJS components
- if you don't use VueJS, components won't be dynamic/reactive, you will need to do things yourselves (an integration with stimulus is welcome).
- Code: https://gitlab.com/experimentslabs/garden-party/rise-ui/
- Issues: https://gitlab.com/experimentslabs/garden-party/rise-ui/-/issues
- Development chat (Matrix): #rise-ui-dev:matrix.org
- Code of conduct
- Contribution guide
- Migration guide
Add the dependency to your project:
yarn add @experiments-labs/rise_ui
Read the Using styles and Integration with VueJS to continue.
Styles are exposed in /styles/*
in the package, and matches src/stylesheets
in the repository.
src/stylesheets
├── style.scss # Entrypoint: Use everything
│
├── components # HTML components without a VueJS equivalent, prefixed with "_". E.g.: _card
├── _components.scss # Convenient index
│
├── core # Anything but selectors: variables, mixins, common placeholders...
├── _core.scss # Convenient index
│
├── helpers # Helper classes, prefixed with "-". E.g.: -mtd
├── _helpers.scss # Convenient index
│
├── lib # Custom library overrides
├── _lib.scss # Convenient index
│
├── reset # HTML tags
├── _reset.scss # Convenient index
│
├── themes # Themes: CSS variable definitions
├── _themes.scss # Defines light and dark theme.
│
├── vue_components # HTML components without a VueJS equivalent, prefixed with "_". E.g.: _card
└── _vue_components.scss # Convenient index
Styles for specific VueJS components are exposed in /components/*
in the package, and matches src/components/*
in
the repository.
To use everything:
// some_entrypoint.js
import '@experiments-labs/rise_ui/styles.css'
Note: Importing the whole CSS file is okay for quick prototyping but should be avoided as the file contains inlined fonts, and is about 5Mb. See this Vite issue describing the situation.
To import only the styles you need:
// your_stylesheet.scss
// Core
@use '@experiments-labs/rise_ui/styles/reset';
@use '@experiments-labs/rise_ui/styles/themes';
@use '@experiments-labs/rise_ui/styles/...';
// Components
@use '@experiments-labs/rise_ui/components/Button/Button';
@use '@experiments-labs/rise_ui/components/...';
This is a bit long; improvements are welcome.
To keep this project consistent, we follow this convention when it comes to naming:
-
-*
is for helpers (e.g.:-mtd
for "margin top default") -
_*
is for components without a VueJS counterpart (e.g.:_card
) -
rui-*
is for VueJS components (e.g.:rui-button
)
We try to follow the BEM convention for components parts and variants.
In your entry point (sometimes main.js
):
//...
import RiseUI from 'rise_ui'
import 'rise_ui/dist/style.css'
const app = createVue(App)
.use(RiseUI)
//...
You can pass an object of options to app.use()
:
app.use(RiseUI, {
// These are the defaults; you should set them to "false" if you don't don't want
// to add the dependencies.
// Check "src/library.js" for the "componentsLibraries" constant to have a list
// of these components.
useDebounce: true, // Whether to enable components relying on "debounce" library
usePopper: true, // Whether to enable components relying on "floating-vue" library
useVanillaPicker: true, // Whether to enable components relying on "vanilla-picker" library
useVueMultiselect: true, // Whether to enable components relying on "vue-multiselect" library
// Check "I18n" below for these options
useVueI18n: false,
locale: 'en',
locales: {},
// Check "Object attributes in form errors" below
i18nObjectAttributesPath: null,
// Check "Icons" below
iconsFile: null
})
To enable components relying on other dependency, you will have to manually add these to your project.
Components can be imported from @experiments-labs/rise_ui/components/*
and from the index @experiments-labs/rise_ui/components
:
import RuiButton from '@experiments-labs/rise_ui/components/Button/Button.vue'
import RuiIcon from '@experiments-labs/rise_ui/components/Icon/Icon.vue'
// Or
import { RuiButton, RuiIcon } from '@experiments-labs/rise_ui/components'
Note: Check documentation for usage and override examples.
RiseUI was meant to be used with vue-i18n
. If you don't want to handle internationalization in your application, a fallback $t
method is injected globally in Vue components, so components that use internationalization still render.
The available translations are en and fr (in src/locales
) for now, feel free to contribute with more.
Rise UI options are:
-
useVueI18n
: whether to usevue-i18n
or provide and use a fake$t
method. -
locale
: default locale to use when not usingvue-i18n
-
locales
: Custom object of translations to use when not usingvue-i18n
RuiFormError
component was meant to be used with a Rails API where for errors usually looks like:
{
"name": [
"is blank"
]
}
While Rails translates the messages, the fields names are provided as-is and should be translated to the user.
i18nObjectAttributesPath
is a string representing the path in the translations object where the model attributes translations can be found.
In a Rails project, it's usually activerecord.attributes
.
To use it with custom attributes, create the translations in the locales
option like:
const locales = {
en: {
object_attributes: {
my_model: {
name: 'Name',
some_field: 'Some field'
}
}
}
}
Refer to the RuiFormErrors
component for usage.
RiseUI comes with a few icons, originally used on Garden Party. If you want to use your own, you should provide an SVG icon set, with valid icons for RiseUI plus yours.
Note: This section is incomplete and really needs improvement.
From package.json
's scripts
section:
# Start documentation project to preview components as you develop them
yarn dev
# Builds the library
yarn build
# Builds the documentation
yarn build:docs
# Lint javascript an vue files. Use --fix to auto-fix issues
yarn lint:js
# Lint SCSS and css files. Use --fix to auto-fix issues
yarn lint:style
# Runs the tests
yarn test
Any text editor with support for syntax coloration will work, however we feel more comfortable to use a tool allowing us to quickly jump from file to file, access documentation and other things that "takes time"...
Note: If you successfully use Vim/Emacs with plugins, what is your setup?
All the changes are documented in the CHANGELOG.