trendyol / baklava Goto Github PK

Figma

Implementation

General usage example:

<bl-pagination current-page=1 total-items=200 items-per-page=5 ></bl-pagination>

API Reference:

bl-pagination component

Pagination component is for listing the pages to the users and redirecting them between pages.

Attributes

Events

Baklava Project Tasks List

ref #63

• #68
• #78
• #71
• #76
• #77
• Documentation
  • #69
  • #73
  • #74
  • #89
  • #228
  • #229
  • #224
  • #230
  • #231
  • #235
• #65
• #95
• #96
• #98
• Implementation of publishing mechanism
  • #67
  • #79
  • #80
  • #81
  • #82
  • #83
• Design system
  • #90
  • #91
  • #92
  • #93
  • #94
• Components
  • #84
  • #85
  • #86
  • #87
  • #88
  • #136
  • #135
  • #145
  • #134
  • #239
  • #264
  • #137
  • #138
  • #130
  • #139
  • #140
  • #141
  • #142
  • #143
  • #144
• Technical Challenges
  • #102
  • #103
  • #104
  • #124
  • #146
  • #147
  • #112
  • #113
  • #114

It makes sense to be able to play with CSS property values of the components in Storybook as well as regular component properties. Apparently, there is already a plugin for that: https://storybook.js.org/addons/@ljcl/storybook-addon-cssprops Let's try it.

Currently, our main file in CDN fetches and registers all of the components immediately. It's also possible to hand pick components by users to only download and use them like:

<script type="module" src="https://cdn.jsdelivr.net/npm/@trendyol/[email protected]/dist/components/button/bl-button.js"></script>

But the idea in this issue is to check the possibility and feasibility of lazy loading components dynamically once they are used in the DOM. In this case, user will just include the main file (or another main file for the lazy loading approach) as always. But this time, instead of downloading and registering all of the components, the library will register a placeholder component for all of our components. And this placeholder component will load the actual one in its connectedCallback method. In theory, this will prevent downloading most part of the library on landing pages since, most of the time, a single page use a small part of the all components.

But there are some points we need to consider here:

• This may cause FOUC issues. All components will be rendered with a placeholder component first, and then the real component will be rendered. During this execution, UI may flick.
• For some cases, network waterfall would not be preferable over hand-picking components. Probably lazy-loading should always be optional

Design

Figma Design Document

Implementation

General usage example:

<bl-checkbox checked disabled>single checkbox</bl-checkbox>

Rules

• Indeterminate state can be use with a single checkbox.
• Styling the colors of checkbox component will be possible via bl-checkbox CSS properties. Like

<style>
.checkbox-new {
   --bl-color-primary: rebeccapurple;
}
</style>

<bl-checkbox class="checkbox-new">new label</bl-checkbox>

API Reference:

bl-checkbox component

Checkbox component handles interaction to change checked/unchecked states.

Attributes

Slots

Events

• Readme document should include a section named "How to use" and provide setup information to be able to use Grace in different environments (via CDN, in a Vue project, in a React project)

Design

Figma Design Document

bl-notification Implementation

General usage example:

<bl-notification
    no-animation
    duration="7"
></bl-notification>

<script>
  const el = document.querySelector("bl-notification");

  const addedNotification = el.addNotification({
    caption: "Notification Caption",
    description: "This is a notification",
    variant: "warning",
    icon: "academy",
    primaryAction: {
      label: "Action",
      onClick: notification => {
        notification.remove();
      },
    },
    secondaryAction: {
      label: "Action",
      onClick: async notification => {
        await notification.remove();
        first.remove();
      },
    },
  });

  // some actions
  addedNotification.remove();
  // or
  el.removeNotification(addedNotification.id);
</script>

Rules

• duration attribute sets the default duration of notifications when not provided.
• no-animation attribute disables animation of notifications. Animations will respect the user's preferences regardless of this property.
• Cards animate in from right on desktop and animate in from top on mobile (screens smaller than 480px).
• Last in card will be on top of the notification list on desktop, and last in card will be on bottom of the notification list on mobile.
• Cards has touch support on mobile. User can swipe to up to dismiss the notification.
• This component will act as an interface that will manage notifications. It will have two methods to add and remove notifications.

API Reference

Notification component acts as an interface that will manage notifications. It has two methods to add and remove notifications.

Attributes

Methods

bl-notification-card Implementation

General usage example:

<bl-notification-card
  caption="Caption"
  icon
  variant="error"
  permanent
  duration="7"
  closed
  @bl-notification-card-request-close
  @bl-notification-card-close
>
  Lorem ipsum dolor sit amet consectetur adipisicing elit.

  <bl-button slot="primary-action">Action</bl-button>
  <bl-button slot="secondary-action">Secondary Action</bl-button>
</bl-notification-card

Rules

• duration attribute sets the duration of the notification in seconds. When the duration is over, the notification will be dismissed automatically.
• permanent attribute makes the notification permanent and it will not be dismissed automatically. User can still dismiss it manually.
• closed attribute makes the notification closed and it will not be displayed.
• caption attribute sets the caption of the notification.
• icon attribute sets the icon of the notification. Either boolean or icon name can be provided. True value will use bl-alert default.
• variant attribute sets the variant of the notification. Possible values are info, success, warning, error.
• primary-action slot will be displayed as a primary action button.
• secondary-action slot will be displayed as a secondary action button.
• bl-notification-card-request-close event will be fired when the notification is requested to be closed. If default prevented, the notification will not be closed.
• bl-notification-card-close event will be fired when the notification is closed.

API Reference

Notification card component is a component that will be used to display notifications.

Attributes

Slots

Events

We are using npm ci to install all the dependencies. It uses only package lock file, so npm can skip the first steps (you can find more detailed information here). It does clean install, in other words deletes node_modules. However, we can cache ~/.npm to prevent redownloading all this stuff.

We'll use commitlint with contenional commit format.

• Commit messages should be validated before pushing changes with commitlint and husky.
• Commit rules should be documented.
• Commit templates should be provided (Example)

This is an epic issue for tracking the roadmap to the first stable version of Baklava (previously named as Grace).

Motivation

After using Grace as one of the UI libraries inside Trendyol, now we decided having some major changes in next version because of some new requirements:

Design System

Project evolved from a UI library to a Design System to cover more generic use-cases then some specific areas inside Trendyol.

Multi-platform

Grace V2 will be a "web component" library written with Lit. The main motivation behind this decision is that we (in Trendyol) want to use the same UI library and design guidelines in both Vue and React projects.

More open

We want to maintain Grace project with regular open-source principles, fully managed in GitHub. So contribution guidelines, documentation, release pipelines will be more transparent and clear.

Accessibility in mind

One of the main purposes of Baklava Design System is to provide fully accessible UI elements. This will help to improve A11y all of our projects in Trendyol without repeating work.

Heavily automated

We'll focus on automating releases, tests, documentation generation, PR workflows, and so on, so we'll allow getting more contributions without blocking anyone because of a lack of human resources.

Plan

We are using next branch for the development of version 2. We'll fully re-write components with a refreshed design in this branch, then we'll release the first stable release of V2. On the road, we'll be able to start using alpha/beta releases.

After creating core parts of the new version, we'll expect contributions to finish implementing all of the needed components in the new version.

We'll publish the library to CDN(s) as well as the NPM registry. We plan to promote consuming Grace V2 via CDN since this will give so much benefit for our users to cache the library on the browser.

Tasks

Here is the list of tasks that needs to be done for having the first stable release of V2.

You are very welcome to be part of this initiative. You can pick some tasks from the list and create a PR request by starting and targeting next branch. Please don't miss to check our new Contribution Guideline.

This issue covers creating basic structure of grace next.

• Basic folder structure that shows components, their tests, stories
• Basic setup of linting tools (tslint, commitlint)
• Basic build command
• Running project

• Contribution guideline document should be provided in CONTRIBUTE.md
• This should be referenced from main documents like README.md and storybook
• A template should be provided for Pull-Requests

Design:

Figma Design Document

Implementation:

Font family, size, weight rules will be defined as CSS variables in our default.css files and we'll stick to those options inside every components for all of the texts.

Design

Figma Design Document

Implementation

General usage example:

<bl-select label="Select country" required>
  <bl-select-option value="tr" selected>Turkey</bl-select-option>
  <bl-select-option value="nl">The Netherlands</bl-select-option>
</bl-select>

Rules

• Select

API Reference:

bl-select component

Select component is for getting input from users to select one or multiple options from a given list.

Attributes

Slots

Events

bl-select-option component

Attributes

Slots

67
Figma

Implementation

General usage example:

  <bl-alert
    variant="error"
    caption="Default Caption"
    description="Default Description"
    icon="close_fill"
    closable
  >
    <span slot="caption">
      Awesome Caption!
    </span>
    Some important description.
    <bl-button slot="action">
      Click me!
    </bl-button>
  </bl-alert>

Rules

• closable attribute displays a close button in alert component. Emits an event named bl-close and component will hide itself via css property.
• Component will not have default icon but users can use icon to use default icons according to variants or icon="calendar" to customize icon.
• action slot will only accept bl-button component (else will cause an error) and will override some attributes of the slotted button (variant will be secondary and kind will be text, icon will not be allowed).
• For mobile design bl-button component which can be used in action slot will convert itself to icon-only bl-button.

API Reference:

bl-alert component

Alert component displays an informational message to users with additional features if desired.

Attributes

Slots

Events

• We'll create an issue template for feature requests

• We'll document how to use Grace in a Vue project.
• We'll check possible issues for using v-model with our input components.
• We'll check the possibility to use Grace from CDN instead of importing via NPM.

• We'll create an issue template for reporting bugs

• Every linter should be run before pushing commits (with husky) and in github actions on every push.

tslint, eslint, prettier, csslint, postcss should be considered in this issue.

Our main expectations from those linters are;

• Every coding file that we write should follow the standards that we defined. And those linters should guarantee this to us.
• Linters should prevent doing some basic mistakes by checking some rules.

Hello Might be I can contribute in something in this repository, so I can help you improve that project!

Storybook documentation should be automatically deployed to a different URL for each PRs and also for the main branch. Storybook URL of PR should be automatically mentioned in PR once it's deployed. So visual reviews can be done by checking the published version.

Design

Figma Design Document

Implementation

General usage example:

<bl-radio-group label="Payment Type" name="payment-type" value="cc">
    <bl-radio value="cc">Credit Card</bl-radio>
    <bl-radio value="ideal">iDeal</bl-radio>    
</bl-radio-group>

API Reference:

bl-radio-group component

This component is the wrapper component of the radio options. Field value will be set/red via this component.

Attributes

Events

CSS Custom Properties

bl-radio component

This component defines options for the radio input.

Attributes

Slots

Events

Figma

• Every component should have fully covered (100% code coverage) unit tests. So, implement coverage check.
• Coverage report should be generated.
• Coverage threshold should be checked in commits and also in GitHub Actions.
• Automated visual tests should be implemented for all components. A screenshot comparison would be done in every commit in PRs -> will be evaluated in another issue
• Testing rules and best practices should be documented

Lit doesn't have any builtin solutions for handling slot changes, component specific slots etc. that we need or will need for our components.

Additionally, slots will be used by many of our components. It will prevent code duplication.

In this issue, I will close those:

• TBD

Design:

Figma Design Document

We'll implement this features on this issue;

• Palette colors will be named semantically
• Colors are conform with accessibility standards
• Colors should calculate mathematically. For example here

Design

Figma

Implementation

General usage example:

<bl-dialog caption='Dialog Title'>
      <p> Dialog Content </p>
      <bl-button slot="primary-action">Save Message</bl-button>
      <bl-button slot="secondary-action" kind="danger">Delete Message</bl-button>
      <bl-button slot="tertiary-action">Dismiss</bl-button>
</bl-dialog>

Rules

• By default a dialog contains a close button and a primary action button.
• Dialogs are always closeable. By default it closes by close button, by clicking outside of the dialog and by clicking "esc" on keyboard.
• A dialog should contain at least one content (text, image etc.).
• Dialogs are always centered on the page, with an overlay behind them that hides the page content.
• Only large buttons can be used in the action bar and there can be maximum 3 buttons (primary, secondary and tertiary).

API Reference:

Attributes

Slots

Events

• Defining PR workflow
• Defining main branch workflow
• Defining feature branch workflows (if it's needed)

Design

Figma Design Document

Implementation

General usage example:

<bl-tab-group>
  <bl-tab 
      name="content" caption="content info" slot="tab" selected>Tab item 1</bl-tab>
  <bl-tab-panel tab="content">
    <p>
      Content item 1.
    </p>
  </bl-tab-panel>

  <bl-tab  name="detail" slot="tab" help-text="Some information will be showed in tooltip" notify>Tab item 2</bl-tab>
  <bl-tab-panel  tab="detail">
    <p>
      Content item 2.
    </p>
  </bl-tab-panel>
  
  <bl-tab slot="tab" disabled badge="Coming soon">New feature</bl-tab>

</bl-tab-group>

Rules

• Tab handles (bl-tab components) will stay in single line even if it doesn't fit the screen. Horizontal scrolling will be possible if tabs doesn't fit the screen.
• To show help-text we'll use bl-tooltip component (its work in progress).
• Tab components should respect accessibility attributes inside.
• Styling the colors of badge component will be possible via bl-badge CSS properties. Like

<style>
.tab-badge-new {
   --bl-badge-color: var(--bl-color-primary-background);
   --bl-badge-bg-color: var(--bl-color-danger);
}
</style>

<bl-tab class="tab-badge-new" badge="New">Payment Options</bl-tab>

API Reference:

bl-tab component

Tab component handles interaction to show/hide tab panes.

Attributes

Slots

Events

bl-tab-panel component

Container for the tab contents.

Attributes

Slots

Events

bl-tab-group component

Container for bl-tab and bl-tab-panel components.

Slots

Events

Currently -and commonly- Lit component styles are defined in TS code with css literal function. We consider to use regular CSS files instead. Using CSS files will be more familiar for developers and easier to lint/check. For achieving this there seems 2 options:

lit-css

lit-css is a package to convert CSS files to TS codes in bundling time. This looks like a simple solution but needs to be checked together with Storybook.

es-module-shims

There is an API proposal (and chrome already supports it) for importing CSS files dynamically for web component in runtime like:

import sheet from 'https://site.com/sheet.css' assert { type: 'css' };

es-module-shims is a pollyfill that makes this possible in every browser. This can be a more future-proof solution.

In this issue, we'll try to implement best solution for us.

• We should able to create independent sections in storybook for documenting general stuff (like how to use grace, some general topics etc)
• Every component should have it's own storybook definitions in a file in its own folder (component.story.ts)
• Component storybook should include:
  • Basic documentation about where and how to use this component
  • Reference for the properties and events of this component
  • Demos for the variations of every property and behaviours of the component

• CDN bundle should include every component in separate files.
• Tree shaking should be possible in NPM bundle.

• We'll document how to use Baklava in a React project.
• We'll check if it's needed to generate React components.
• We'll check the possibility to use Baklava from CDN instead of importing via NPM.

Lit doesn't provide any convention for defining and publishing component events but it seems logical to at least create our own. So events of the component will be more visible and we'll avoid code duplication for firing multiple events from many components.

class GrIcon extends LitElement {
   ....
   @event('gr-load') load: EventEmitter<string>;

So for me, requirements are:

• A common function/class to fire type-safe component events with optional parameters (bubbles, cancellable).
• A decorator that accepts optional event name. By default it can use kebab-cased version of the class property name.

Design

Figma Design Document

Implementation

General usage example:

<bl-badge>In Progress</bl-badge>

Rules

• Icon can only be used on Large and Medium badges.
• There are no specific variants for the badge but using our color palette for badge colors is suggested.

Usage Examples

Default background color is --bl-color-accent-primary-background and default color is --bl-color-primary. But any color can be set like this:

<style>
.danger-badge {
--bl-badge-bg-color:var(--bl-color-danger-background);
--bl-badge-color:var(--bl-color-danger);
}
</style>

<bl-badge class="danger-badge">Denied</bl-badge>

The icon can be set like this:

<bl-badge icon="waiting">In Progress</bl-badge>

The size can be set like this:

<bl-badge size="large">In Progress</bl-badge>

API Reference:

Attributes

A default theme uses Rubik font and by-detault we use it directly from Google Fonts. This is not very nice for a copule of reasons as explained in Fontsource project page. In this issue, we'll consider using fontsource to bundling Rubik font together with Grace.