Git Product home page Git Product logo

homeday-blocks's Introduction

Release and publish Storybook deployment Coverage Status This project is using Percy.io for visual regression testing.

Homeday Blocks

A library of Vue components and tokens used across Homeday projects - here

Local setup

Fork the main repository, clone your fork to your local machine and add the main repo as upstream.

$ git clone [email protected]:YOUR_USERNAME/homeday-blocks.git
$ cd homeday-blocks
$ git remote add upstream [email protected]:homeday-de/homeday-blocks.git

Prerequisites

Homeday Blocks requires Node.js version 14.17.0 (.nvmrc). It's recommended to manage multiple versions of Node on the same machine with nvm or nvm-windows.

Don't forget to setup the deeper shell integration in your console to take full advantage of nvm. You can achieve this by adding the following alias into your ~/.bashrc, or ~/.zshrc file:

alias cd="cdnvm(){ cd $1; if [[ -f .nvmrc && -s .nvmrc && -r .nvmrc ]]; then <.nvmrc nvm install; elif [[ $(nvm current) != $(nvm version default) ]]; then nvm use default; fi; };cdnvm"

Project setup

Download and install dependencies

For a breif explanation of what is being install, please read our setup documentation file.

OSX

To install all our dependencies on OSX, run scripts/setup.osx.sh.

Ubuntu

To install all our dependencies on Ubuntu, run scripts/setup.ubuntu.sh.

It is recommended to run the setup script everytime you pull from the master branch. This way you can always be sure to have all the project dependencies up to date.

Lints and fixes files

npm run lint

Storybook

Development

npm run serve:storybook

Build

npm run build:storybook

Build the library

npm run build

For a brief explanation of how the library is built, checkout this documentation.

Testing

To just run all unit tests:

npm run test:unit

To watch for changes while writing tests:

npm run test:unit:watch

To watch for changes while writing tests for a single component:

npm run test:unit:watch ComponentName

Screenshot tests on Percy

Make sure you've PERCY_TOKEN exported first and the project is built.

The token can be obtained from Percy dashboard if you've access to it.

npm run test:percy

You can also follow build statuses in https://percy.io/Homeday/homeday-blocks

Gotchas

  • tests/ is an alias for <rootDir>/tests/

TypeScript

For a basic explanation of what it is and how to use it, please read TYPESCRIPT.md.

Generators

We use Hygen as a code generator tool to save time when we need to scaffold some structure.

Just run:

npm run new component
npm run new service

And follow the wizzard in order to generate a base component structure or a service.

Contribution guide

This project follows Git Feature Branch Workflow. See project setup to get started locally. That means that all code changes enter the project by PR to master branch. Once you open the PR with suggested changes, the checks for build and coverage will run. If those fail, your PR needs some more work. :)

Each PR should be reviewed by at least two team members. Once reviewed and approved, it can be merged. Please follow the following convention when merging the PR:

  1. Use "Squash and merge" to merge the PR.
  2. Use a meaningful title when merging your PR.
  3. Give title a semantic meaning through emojis. Please use emoji first, then the text.
  4. 💥 - marks breaking changes (MAJOR version change)
  5. ✨ - marks new feature (MINOR version change)
  6. The other gitmojis are either a patch or have no effect at all.

It is important to follow this convention, because our automated releases are based on it.

Examples

Major change

💥 Removed HdNotNeeded component

Minor change

✨ Added HdAwesomeComponent

Patch

🐛 Fixed that annoying bug

Version release

Releasing a new version is as easy as pushing your changes to master 😎

Consuming in other projects

import { HdDynamicForm } from 'homeday-blocks';

Customize configuration

See Configuration Reference.

Services

Together with the components, Homeday Blocks also provides useful services that can be reused across projects. You can read more about them in the services documentation.

Infrastructure

Homeday Blocks has its own infrastructure repository: blocks-infra. Whenever changes need to be made, you can do it in the repository and "deploy". If it is an emergency, you can also use AWS Console but your next step is to update it in the repository to avoid future inconsistencies.

homeday-blocks's People

Contributors

alieslamifard avatar aym3nb avatar dependabot-preview[bot] avatar dependabot[bot] avatar drapisarda avatar hesambayat avatar ilyasmez avatar ivandata avatar kuroski avatar leandroinacio avatar limhenry avatar majakomel avatar metal-gogo avatar mlande avatar olegivaniv avatar originalexe avatar peterchencc avatar petterhd avatar sinisag avatar suscasasola avatar viniciuskneves avatar volcanioo avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

homeday-blocks's Issues

SCSS Method getShade works on lightness value instead of percentage

getShade() ( in styles/_colors.scss) works on the lightness property of the passed color (in a HSL way). This means that the same variation value generates different results for different colours. Other than that, getShade() could also shot an error. Example:
getShade($crusta-orange, 29)
generates
image

We could solve this

  • using SCSS lighten method, but then we have to change how we measure the variations
  • force $new-lightness to be alwasy >= 0 with an if .

Extract HdInputPassword from HdInput

Currently HdInput has some extra logic on top to handle password type. It could be extracted into another component to make it clear and don't overwhelm HdInput with logic.
We're currently developing also HdInputFormatter that should be possible to handle formatting inside HdInput but it is build on top of HdInput to not add extra logic layer into it.

We shouldn't scope homeday blocks styles with vue's keyword `scoped`.

I've seen on our codebase that the components in homeday-blocks have scoped styles. For instance: https://github.com/homeday-de/homeday-blocks/blob/develop/src/components/HdToast.vue#L71

However, on Vue styleguide says:

  • Component libraries, however, should prefer a class-based strategy instead of using the scoped attribute.
  • This makes overriding internal styles easier, with human-readable class names that don’t have too high specificity, but are still very unlikely to result in a conflict.

Since we are using BEM, this could namespace our styles, and with this, we will avoid using v-deep in our other protects: https://github.com/homeday-de/customer-app/blob/f170f72fc484dbf6e0500611a24b8326c94b1df4/src/components/buyer-feedback/slides/Finance.vue#L57

Unit test fails

I cloned the repo and installed the dependencies. When I run the unit test, it fails.

Summary of failing test:

 FAIL  tests/unit/components/notifications/HdNotifications.spec.js
  ● HdNotifications › fires the heightChange event when height of the notifications changes

    expect(received).toBeTruthy()

    Received: undefined

      46 |     await wrapper.vm.$nextTick();
      47 | 
    > 48 |     expect(wrapper.emitted('heightChange')).toBeTruthy();
         |                                             ^
      49 |   });
      50 | });
      51 | 

We should be using `rem` instead of `pixels`.

We should be using rem instead of pixels

Pixels vs. Relative Units in CSS: why it’s still a big deal makes an amazing job explaining why this is important. I'll quote a couple of important points:

The most important reason for using responsive and unitless values in our CSS is for supporting our users that rely on zooming. If you read the Web Content Accessibility Guidelines, our users need to be able to zoom the viewport without loss of content or functionality, or restrictions imposed by CSS values or viewport scaling settings.

Design systems and threads of consistency
As someone who works on the O’Reilly Media Design System, weaving threads of consistency across brand, style, and UI components is a top priority. Consistency across a system empowers designers and developers to craft great app experiences for the end-user. That said, the most important thread that connects all elements of a design system tapestry is established accessibility best practices — for colors, typography, components, patterns.

Summarizing em vs. rem difference:

  • The translation of rem units to pixel value is determined by the font size of the HTML element. This font size is influenced by inheritance from the browser font size setting unless explicitly overridden with a unit not subject to inheritance.

  • The translation of em units to pixel values are determined by the font size of the element they’re used on. This font size is influenced by inheritance from parent elements unless explicitly overridden with a unit not subject to inheritance.

Note: For me, this makes rem more predictable than em, therefore, I prefer rem over em.

When to Use Em vs. Rem

This Comprehensive Guide: When to Use Em vs. Rem makes a great guideline for sizing units. I'm going to copy their bullet-point recap:

  • rem and em units are computed into pixel values by the browser, based on font sizes in your design.

  • em units are based on the font size of the element they’re used on.

  • rem units are based on the font size of the HTML element.

  • em units can be influenced by font size inheritance from any parent element

  • rem units can be influenced by font size inheritance from browser font settings.

  • Use em units for sizing that should scale depending on the font size of an element other than the root.

  • Use rem units for sizing that doesn’t need em units, and that should scale depending on browser font size settings.

  • Use rem units unless you’re sure you need em units, including on font sizes.

  • Use rem units on media queries.

  • Don’t use em or rem in multi-column layout widths - use % instead.

  • Don’t use em or rem if scaling would unavoidably cause a layout element to break.

Tip

When creating layouts it’s often easier to think in pixels but output in rem units. You can have pixel to rem calculations done automatically via a preprocessor like Sass, or a postprocessor like PostCSS with the PXtoRem plugin.

References

Rewrite HdResponsive to use MediaQueryList.addListener

For the HdResponsive component, right now we rely on the resize event to check and update the matching breakpoints. It's throttled so there is no huge performance hit, but we could instead set up listeners on each media query, which fire only once (when the change happens).

More docs here: https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList/addListener

It is well supported in all browsers we care about. The only "complexity" is that the recommendation is to use addEventListener instead of addListener, but addEventListener is not available in Safari. This can be solved by checking for existence and calling the appropriate one. Their functionality is the same.

All the buttons should have the same sized border

The full color .btn (--primary --secondary ...) have no border. So if I use a button with a transparent bg and I change the class to color it (homeday homepage header ctas) the button looks like it is moving.

Improve accessibility on HdIcons

Without HdIcon we could use an svg asset like this:

<template>
  <img
    src="@/assets/img/icons/some.svg"
    width="16"
    height="16"
    alt="Some alt text to describe image"
  >
</template>

With HdIcon we can make it inline the svg with the following code:

<template>
  <hd-icon
    :src="someIcon"
    width="16px"
    height="16px"
  />
</template>

<script>
import { HdIcon } from 'homeday-blocks';
import { someIcon } from 'homeday-blocks/src/assets/small-icons';

export default {
  name: 'componentName',
  components: {
    HdIcon,
  },
  data() {
    someIcon,
  },
};
</script>

This is awesome! This gives us a lot of versatility and styling power. And the best part is that we are getting the icons directly from the design system.

The downside of using the component HdIcon on this case is that we lose the accessibility on the image. I believe that we should make a11y a first-class citizen on Homeday Blocks.

I suggest we implement accessibility on HdIcon adding the props:

  • title: string, optional, if not provided could work as an empty alt attribute.
  • id: string, optional, if not provided could be autogenerated
  • description: string, optional

I add a couple of screenshots from this accessible svgs post describing how could accessibility be implemented 😁.

image

image


Reference:

Forward HdInput attributes to <input>

We currently map a lot of properties from HdInput to <input>: https://github.com/homeday-de/homeday-blocks/blob/develop/src/components/form/HdInput.vue#L12-L28

For some of them it might make sense as they are transformed or have some other usage inside the component, as the required property, for example.

The problem is: if we need to forward new attributes that won't need any transformation or will be used inside the component, we need to add a new property and attach it to <input>.

To avoid this problem, a good approach is to forward all the attributes from HdInput to <input>.

nuxt-link support for HdLink

Currently HdLink supports router-link and it would be interesting to have nuxt-link support as well.

Bootstrap Vue supports something similar and even custom ones if needed: https://github.com/bootstrap-vue/bootstrap-vue/blob/5bf6733595091cc204d3acc0641f8f0301bcbe9c/src/components/link/link.js#L66

I think we don't need something that fancy but that is how they select the tag to be used: https://github.com/bootstrap-vue/bootstrap-vue/blob/5bf6733595091cc204d3acc0641f8f0301bcbe9c/src/utils/router.js#L90-L105

We can adopt a similar strategy or make router-link/nuxt-link by default only and add others if needed in the future.

Refactor <HdLink> exposed modifiers

Currently the modifiers are hard coded inside the component and replicated inside the story itself.
We should follow the approach from HdButton where we expose those modifiers via Object and reuse them to create all available stories.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.