sebnitu/vrembem

A CSS component library based on the BEM methodology.

Vrembem

A component library based on the BEM methodology.

About

Vrembem is a front-end component library written to make available common web interface patterns. This allows developers and designers to implement robust components into their web projects while keeping them flexible and customizable through the use of the BEM methodology and Sass CSS extension language.

This Vrembem repository is managed as a monorepo that contains all available components. Include all components using the convenient all-in-one vrembem package.

Quick Links

• Documentation
• Components
• Changelog

Getting Started

Using CDN

If you'd like to use Vrembem for prototyping or just want to take it for a test drive, you can leverage the unpkg CDN version of a component or the entire Vrembem library.

<!-- Include Vrembem styles -->
<link rel="stylesheet" href="https://unpkg.com/vrembem/dist/styles.css">

<!-- Render a component -->
<button data-modal-open="modal-id" class="link">Open modal</button>
<div id="modal-id" class="modal modal_size_sm">
  <div class="modal__dialog dialog" role="dialog" aria-modal="true">
    <p>Hello, world!</p>
    <button data-modal-close class="link">Close</button>
  </div>
</div>

<!-- Include Vrembem JavaScript -->
<script src="https://unpkg.com/vrembem"></script>

<!-- Instantiate the component rendered in the document -->
<script>
  const modal = new vrembem.Modal();
  modal.init();
</script>

Also see example.html for a more comprehensive working demo of using Vrembem via CDN.

CDN References

Vrembem packages all bundles in two areas, dist contains all compressed production ready bundles and dev contains uncompressed versions (all using the same file names). Components that ship with JavaScript include 4 bundles:

Type	Extension	Description
UMD	.umd.js	Universal Module Definition bundles that can be used directly in the browser via a <script> tag. This is the default file from pkg.unpkg pointing to scripts.umd.js.
ESM	.esm.js	ES Module bundles that are intended for use with modern bundlers like Webpack 2 or Rollup. This is the default file from pkg.module pointing to scripts.esm.js.
CJS	.js	CommonJS bundles that are intended for older bundlers like Browserify or Webpack 1. This is the default file from pkg.main pointing to scripts.js.
Modern	.modern.js	Modern bundles specially designed to work in all modern browsers. Specifically compiles down to browsers that support <script type="module"> which are smaller and faster to execute than the esm bundle.

CDN Link Format

# Styles
Uncompressed: https://unpkg.com/[COMPONENT]/dev/styles.css
Compressed:   https://unpkg.com/[COMPONENT]/dist/styles.css

# Scripts
Uncompressed: https://unpkg.com/[COMPONENT]/dev/scripts.umd.js
Compressed:   https://unpkg.com/[COMPONENT]/dist/scripts.umd.js

For example, if you wanted to include the styles and scripts for the @vrembem/drawer component, you could use the following link and script tags:

<!-- Component specific styles (expanded or compressed) -->
<link rel="stylesheet" href="https://unpkg.com/@vrembem/drawer/dev/styles.css">
<link rel="stylesheet" href="https://unpkg.com/@vrembem/drawer/dist/styles.css">

<!-- Component specific scripts -->
<script src="https://unpkg.com/@vrembem/drawer/dev/scripts.umd.js"></script>
<script src="https://unpkg.com/@vrembem/drawer/dist/scripts.umd.js"></script>

<!-- A modern bundle specially designed to work in all modern browsers with UMD fallback -->
<script type="module" src="https://unpkg.com/@vrembem/drawer/dist/scripts.modern.js"></script>
<script nomodule src="https://unpkg.com/@vrembem/drawer/dist/scripts.umd.js"></script>

Using NPM

To use a Vrembem component, you'll first need to install it as a dependency. For this example we'll be using the modal component:

npm install @vrembem/modal

CSS

Include the component in your build's Sass manifest file:

@use "@vrembem/modal";

Vrembem uses Sass' module system, pass in custom variables using the with keyword.

@use "@vrembem/modal" with (
  $background: #fff,
  $background-alpha: 0.9
);

JavaScript

Some packages also have included modules for their functionality. You can include these in your JavaScript files by importing, instantiate and initialize:

// Import your component
import Modal from "@vrembem/modal";

// Instantiate and initialize
const modal = new Modal();
modal.init();

Alternatively, you can use the autoInit option to auto initialize and optionally omit saving the instance to a variable if the returned API won't be needed later.

new Modal({ autoInit: true });

HTML

Include the component's markup into your project. Use the online docs for information and code examples such as markup and available modifiers for each component.

<button data-modal-open="[unique-id]">Modal</button>
<div id="[unique-id]" class="modal">
  <div class="modal__dialog" role="dialog" aria-modal="true">
    <button data-modal-close>Close</button>
    ...
  </div>
</div>

All-in-one

It's also possible to include all Vrembem components using the single all-in-one vrembem package:

npm install vrembem

Via your project's Sass manifest file:

@use "vrembem";

Override default variables using Sass' module system and the with keyword. Variables are prefixed by their component name. You can also customize core variables which all components inherit from using the $core- prefix.

@use "vrembem" with (
  $core-prefix-block: "vb-",
  $modal-background: #fff,
  $modal-background-alpha: 0.9
);

Via your project's JavaScript manifest file:

// Import all under the vb namespace
import * as vb from "vrembem";
const drawer = new vb.Drawer({ autoInit: true });

// Or import individual components
import { Drawer } from "vrembem";
const drawer = new Drawer({ autoInit: true });

Note that core helpers do not need to be initialized since they're just a set of helpful utility functions.

Copyright and License

Vrembem and Vrembem documentation copyright (c) 2024 Sebastian Nitu. Vrembem is released under the MIT license and Vrembem documentation is released under Creative Commons.

vrembem's Issues

Add responsive table modifier

Problem

Currently, the only responsive support we have for tables is to wrap a large table in the scroll-box base component. This is fine in some cases, but there's a need for a more comprehensive responsive table modifier.

Possible Solution

In more complex tables, it's sometimes a better user experience to treat each row as it's own table on mobile. We could introduces a table modifier such as table_responsive along with the data-mobile-label attribute to handle those cases.

<table class="table table_responsive">
  <thead>
    <tr>
      <th>#</th>
      <th>User</th>
      <th>Email</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td data-mobile-label="#">1</td>
      <td data-mobile-label="User">someone</td>
      <td data-mobile-label="Email">[email protected]</td>
    </tr>
    <tr>
      <td data-mobile-label="#">2</td>
      <td data-mobile-label="User">else</td>
      <td data-mobile-label="Email">[email protected]</td>
    </tr>
    <tr>
      <td data-mobile-label="#">3</td>
      <td data-mobile-label="User">another</td>
      <td data-mobile-label="Email">[email protected]</td>
    </tr>
  </tbody>
</table>

References and resources

• MDN Responsive browser compatibility table
• CSS-Tricks Accessible, Simple, Responsive Tables

Add documentation to README.md in all packages

Problem

Not all packages have fully documented README.md files.

Solution

We should add documentation in all package and component README.md files. This should be closely paralleled with the web documentation and cover things like:

• Installation
  • Styles
  • JavaScript
  • Markup
    • component__element
    • data-attr
    • Notes
• Modifiers
  • component_modifier
    • component_modifier_key
• Customization
  • Sass Variables
  • JavaScript Options
• Events
• API
  • api.method()

Starter Template

Documentation Status

Here's a checklist to track which components have their README.md documentation added.

• Base
• Breadcrumb
• Button
• Button-group
• Card
• Checkbox
• Core
• Dialog
• Drawer
• Grid
• Icon
• Icon-action
• Input
• Level
• Media
• Menu
• Modal
• Notice
• Popover
• Radio
• Section
• Switch
• Table
• Utility
• Vrembem

Add MIT license information to readme and root

Would like to do something similar to how I have BaseWeb setup. Just need to add the "Copyright and License" section at the bottom of the readme and include the LICENSE file in the root directory. License will be MIT.

Example

Rebuild tasks in Gulp

The base tasks were ok, but I think it's just easier to run everything through Gulp, especially with how complex the npm tasks got.

Use map module in core mixins

Problem

Core mixins are currently using aliased functions instead of the Sass' core map module.

Solution

Import the @use to bring in Sass' core module for maps instead of using aliased functions.

@use "sass:map";

map.get(var.$breakpoints, "md");

Reference: sass:map

Convert Vrembem to use Sass' module system

This conversion has already started with media and button-group components. The goal is to have every component converted to the module system and necessarily updated the vrembem global package which includes all other components and forward them with appropriate namespaces:

@forward "@vrembem/arrow" as arrow-*;
@forward "@vrembem/base" as base-*;
...

This should allow for the inclusion of the vrembem package this way:

@use "vrembem" with (
  $arrow-radius: 3px,
  $base-heading-line-height: 2
  ...
);

^ The above should be reflected in it's use in the docs stylesheets.

For individual component includes, the syntax would just reflect how you'd expect without the forward namespaces set in the global vrembem:

@use "@vrembem/arrow" with (
  $radius: 6px
);

@use "@vrembem/base" with (
  $heading-line-height: 3
);

Reference: https://sass-lang.com/blog/the-module-system-is-launched

Make component breakpoints override-able on a per component basis

Problem

Currently most components that have modifiers with breakpoint keys don't allow for custom breakpoint maps unless the global core map is changed.

Solution

All components should have their modifiers with breakpoint keys written in such a way that it uses the components variable for breakpoints map (while still defaulting to core.$breakpoints) and the @each loop they use should pass the $value instead of the $key to the media query mixin:

@each $key, $value in var.$breakpoints {
  @include core.media-max($value) {
    ...
  }
}

Refactor Vrembem to be a monorepo and use Lerna to manage packages.

Monorepo

It's time to convert Vrembem into a monorepo and treat each component as it's own package. This is going to allow me to do things like:

@import "@vrembem/core";
@import "@vrembem/menu";
@import "@vrembem/drawer";

I plan on using Lerna to manage this repo and it's packages.

Component Package

Each package should have a few files which I can use to build a template out of for future components. All components will have the following:

• _all.scss (maybe)
• _mixins.scss (maybe)
• _variables.scss
• [component].scss
• package.json
• README.md

JavaScript components

• [component].js
• [component].test.js (or __test__ dir)

Questions

Some questions I've ran into as I research and learn about monorepos.

• Should I have a test directory (__test__) in each package like is created from lerna create?
• Do I need an import file like _all.scss that imports all a component's core and modifier files?
• Should there be a src and dist directory within each component package?
• If I define a main and style value in package.json and I point to a file that's not in the root directory?
• For style in package.json, do I point to the import scss file or the compiled css file?

Add icon size modifiers

Should take the form of: icon_size_[key]. Size scale could possibly jump based on the line-height allowing for nice alignment next to text.

1 * $line-height
2 * $line-height
3 * $line-height

Dependabot can't resolve your JavaScript dependency files

Dependabot can't resolve your JavaScript dependency files.

As a result, Dependabot couldn't update your dependencies.

The error Dependabot encountered was:

Error whilst updating feather-icons in /docs/package-lock.json:
No matching version found for vrembem@^1.1.0.

If you think the above is an error on Dependabot's side please don't hesitate to get in touch - we'll do whatever we can to fix it.

View the update logs.

Only apply margins to top and left when gap and wrap modifiers are used

Margin should only be applied to top and left when _gap and _wrap modifiers are used together.

• Applied to wrapper
• Applied to buttons

Should also test this doesn't break any intended functionality.

Add build script for processing image assets in demo examples

Currently doesn't exist. Specifically needed for the favicon and hero background example.

Split variables into their own files

Component variables should be split into their own files, probably called variables.scss within their respective component directories.

Add drawer API call to switch between modal and normal states

Problem

There's currently no way to manually toggle a drawer's modal state via API call. There are some use cases where having this ability would be helpful. If we're wanting to toggle a drawers modal state based on conditions independent of a breakpoint, for example.

Solution

Introduce an API call that targets a drawer or set of drawers which toggle's it's modal state. It should have the ability to switch between modal or the normal state.

Improve API documentation

Problem

The API documentation in README.md is currently all in tables. This leaves no room for real code examples, parameter descriptions or anything else.

Possible Solution

Could possibly take inspiration from jest-puppeteer and format it this way:

Example: https://github.com/smooth-code/jest-puppeteer#api

Refactor the media component to have a more generic media object

Currently, media is defined using two media children items:

• media__img
• media__icon

This refactor should create a new more generic element, possibly media__obj. This should cover the cases of both icons and images. This may also require a new modifier to adjust the spacing between the media object and the body.

Components review

Look through all available components and compile a list of all that need:

• Updated demo examples
• Updated variables
• Updated file splits
• Need responsive modifiers

Improve dismissible component

Problem

The dismissible component is not very robust and is pretty minimal in it's usefulness.

Possible Solution

Here are some ideas on ways to improve the dismissible component:

• Add it's own styles. These styles would admittedly be minimal since it's essentially a class that applies display: none;, but I'd like for it to not assume the existance of other utility components (e.g. display_none as found in @vrembem/utility).
• Add more style options, possible fade or slide transitions.
• Add a delay once the "dismiss" event occurs and "remove" after a period of time.
• Add custom event emitters

Update

It may be worth just remove this component for now until a more useful one is created.

Fully comment and document the drawer component files

Make sure that it's clear all the things I'm doing within the Scss and JavaScript files of the drawer component. It would be nice to clearly define the options, what they do and how to enable/disable features.

Create a "feedback" button on the bottom left or right of docs

Create a button that should open a modal with either a form or some links of places to report bugs and help update/fix the documentation.

Make JavaScript components more modular

Problem

Current Vrembem JavaScript components are written in a single file. This can make it hard to understand their features, test and keep organized.

Possible Solution

Similar to the recent modular update on scroll-stash, should break up the index file to feature modules with a consistent structure for core and settings modules.

General Structure

Here's a concept for a general component structure:

• core.js - Consists of the core definition of the component and the API that gets exposed for distribution. Every component would attach to it's API settings, init and destroy and check autoInit here.
• settings.js - Contains the default options object.
• <feature>.js - The rest of the module exports would be grouped by feature. For example, if the component has state management, that would be included via a state module defined in src/state.js.

JavaScropt Components

A list of JS components that would need this update:

• Drawer
• Modal
• Checkbox

Compile a list of template examples

I've already started work on the GitHub project dashboard template, but I want to also include a few more examples with varied layouts and component usage.

Create github template page

Create a template of a dashboard project page from github using only internal components.

Provide package.js as an object available for demo pages

This will allow me to pull the project name, description, version, author info and github repo url and use them in the demo pages without having to hardcode them.

Update copyright text

Re-write the copyright text to include information on the licenses (MIT) Vrembem is published under and also a general copyright for the docs templates and styles.

Fix horizontal scrolling on components and tables in docs on mobile

There’s a few components and tables in the docs currently causing horizontal scrolling. This could be fixed by:

• Wrapping components in the utility scroll-box wrapper
• Creating a responsive modifier for tables

New plugin: dropdown component

Just need a simple JavaScript plugin for on-click events on the dropdown component. The functionality would be something like:

• Click event on a dropdown trigger toggles the dropdown.
• Clicking inside the dropdown should not close it.
• Dropdown styles open until the trigger is clicked again or another element in the DOM is clicked.
• Esc key could also dismiss the open dropdowns.

Add notice for when a search produces no results

This should display a simple message of No results found for "..." or something similar.

Example:

Create tests for my JavaScript components

It's time I research and look into unit testing for my JavaScript components. My initial research has led me to Mocha.js which I'll use for my first tests and see how I can incorporate it into my workflow.

Other notes

• Jasmine
• Mocha.js
• What every unit test needs
• Understanding prototypes and inheritance in JavaScript
• Class basic syntax

Add breakpoint modifiers to button-group component

There's a need to add both _full and _stack modifier styles based on a specific breakpoint.

Example implementation:

@each $key, $value in core.$breakpoints {
  @include core.media-max($value) {
    .button-group_full_#{$key} {
      ...
    }
  }
}

Add a panel component

The panel is another container component that's more general purpose than a card and more focused than a section and more agnostic about it's contents.

Possible component structure:

• .panel
  • .panel__header
  • .panel__body
  • .panel__footer

Details to come...

Add comments to JavaScript plugins

I need to add comments and fully document the available JavaScript plugins. This will help me to create the JavaScript documentation later and also create a standard for plugins in the future.

Automate GitHub releases and changelog updates

Problem

Though I'm using Lerna to manage my version bumps and NPM publishing, I'm currently having to manually create GitHub releases and change log bumps.

Possible Solution

A few things to look into for possible solutions:

• GitHub Actions
• Babel Actions Script

Add responsive styles for components that need them

Some components should have responsive modifier styles. These would probably be the larger more complex components and layout components.

Rebuild docs in Jekyll

What I had setup as the default setup is alright, but I think using Jekyll gives me way more flexibility and utility over the custom build.

New plugin: onscroll component

A JavaScript component that can be used to update a component based on how far down the page something was scrolled. This is used in my personal website to show/hide navigational tools.

Separate layout components from the standard block components

This should also be done in the demo pages and be searchable by their type. The following are layout components:

• container
• grid
• level
• section
• spacing

The general idea behind layout components is that they deal with how a page is structured and how children components are positioned and/or spaced.

Add docs page for utility components

The new utility components are finished and there are many of them. These mainly take the form of modifier classes which change single properties of the components they are applied to. This cut back on a lot of redundant modifiers that many components were using (such as alignment and justify for flex based components).

So now I'd just like to throw together a single docs page that shows all the available utility classes.

Add JS and SCSS linting

I've added this in the past. I'll update this issue with details after I do a little research.

Improve mobile-label styles on responsive table modifier

Problem

The current styles are too heavy for how often the labels get repeated.

Possible Solution

Mobile label styles should not inherit the styles from th since they appear much more often and end up feeling too heavy and bold as a result. A solution might be adding custom variables for setting the label styles with some defaults that soften their look:

$mobile-label-background: rgba(core.$black, 0.03) !default;
$mobile-label-color: core.$color-subtle !default;
$mobile-label-font-weight: core.font-weight("semi-bold") !default;

Add tags to demo pages

Add tags for both component and template example demo pages. This can be hooked into the homepage search functionality.

New component: Drawer

A container component that slides in from the left or right. It typically contains menus, search or other content for your app.

The work for those component is located in the following branch:

component/drawer

Features

• Allow for multiple drawers on a page
• The ability to save state (open or closed) using localStorage
• Allow for component switching (between drawer and modal depending on screen size)
• Should have sliding animation
• Left or right positioning or static

Inspiration

• Drawers in Material Design
• Drawers in Material Web Components
• Bootstrap drawers

Rename JS breakpoint variable to breakpoints

To help keep CSS and JS variables in parody, breakpoints should be used for the name of both variables.

Add docs page for core files

Just a simple page explaining the core files and what they provide in terms of variables, mixins and functions.

Add clear icon-action for home search

This should appear once something is typed in the search field.

Example:

Add docs page for getting started

This can be just outputting the readme into docs form. Explains how to use Vrembem etc.

Should drawer component be refactored?

I'm starting to re-think the drawer component. Here's why:

What's the problem?

As I developed the current iteration of drawer, I started to realize how context depended the component actually is. This causes a problem in BEM because any component created should be context independent. This means all the required styles to make a drawer function correctly should all be enclosed within the base drawer component. Here's how this looks currently:

<div class="drawer">
  <!-- The drawer content goes here... -->
</div>

But the thing is, I actually need more context to make a drawer work correctly. So I had to add "optional sub-components" for the parent and main sibling elements. So our component now looks like this:

<div class="drawer-parent">
  <div class="drawer">
    <!-- The drawer content goes here... -->
  </div>
  <div class="drawer-sibling">
    <!-- This is the main content area -->
  </div>
</div>

As you can see, this breaks the BEM methodology. It's true that the "drawer" is literally the element that slides in and out of the content area (drawer-parent) but it's not a true component without it's parent and sibling counter parts.

The proposed solution

My suggestion is to refactor the way we're defining the drawer component. So instead of having a parent sub-component, that should actually be the drawer itself and it should contain "drawer__item"'s and a single "drawer__main" containing the main content area.

<div class="drawer">
  <div class="drawer__item">
    <!-- The drawer content goes here... -->
  </div>
  <div class="drawer__main">
    <!-- This is the main content area -->
  </div>
</div>

Text size modifiers should scale child components

The utility modifiers of text_size_* should ideally scale components predictably. An example of this would be if text_size_small is added to a foot section, all components within that section should scale together and retain proportions with one another.

Add x and y gap modifiers to the `level` component

Problem

There are many situations where I want to make the horizontal and vertical gap spacing different. This creates a limitation of the existing _gap modifier which handles both directions simultaneously.

Possible Solution

One possible solution to this would be to introduces x and y modifiers that allow you to target horizontal and vertical spacing directly. The modifiers might look like this:

• level_x_gap_[key]
• level_y_gap_[key]

This could also have a similar modifier for media and maybe other components who has a type of "stacking" behavior.

Alternate Solution

Another option may be adding breakpoint variants to the spacing utility. This would allow for vertical spacing to take place using the utility and could be adjusted or removed based on the breakpoint.

• spacing-[breakpoint]-[size]

This could be confusing, especially when you see things like spacing-md-sm?

Add docs page for drawer component

With a new component comes a new docs page. This should detail all required classes, elements and available options such as:

• Save state
• Drawer/modal switcher
• Position modifiers

This component relies very heavily on JavaScript for most of it's features so finding a way to document JS components better would be great and can later be incorporated into the Modal component docs.