@patoche/balkany NPM

BALKANY

A design system for Angular and React.

What the hell is this?

Balkany is an honest component library, for React and Angular.

🚫✨ It's not really shiny.
🚫🔄 It's not really extensible.
🎯😏 It just suits our needs.

Requirements

To start working on the website you just need to have the following programs installed:

Installation of Balkany's NPM package

Just open your terminal and install @patoche/balkany with your favorite package manager.

// with yarn
yarn add @patoche/balkany

// with npm
...

// Nope. 🙅‍
// There was a trick.
// You should use Yarn! 😛

Usage with React

Balkany created some honest components from scratch, but it is mostly a front for his accessible and extensible components laundering business. 🤫

Kudos to springload for react-accessible-accordion and davidtheclark for react-aria-menubutton. Their quality work save a lot of time and effort. 🙌

🚀 Get started

Here is a quick example to get you started with Balkany's React components.

import * as React from "react";

import { Button } from "@patoche/balkany/react/button";

function App() {
    return (
        <Button variant="contained" color="primary">
            Hello World
        </Button>
    );
}

Yup. That's all you need.

📚 Documentation

Balkany's honest React components are documented here.

Usage with Angular

Balkany embezzled the PrimeNG component kit and laundered it with the Levallois Light theme. 🤭

🐌 Get started

Here is ~~a quick~~ an example to get you started.

1. Import Levallois Light style files

In theory you could just add the following CSS files to the style property in the Angular configuration file, i.e. angular.json :

styles: [
    "node_modules/@patoche/balkany/dist/levallois-light/theme.css",
    "node_modules/primeicons/primeicons.css",
    "node_modules/primeng/resources/primeng.min.css",
    //... Put your own style files here
];

However, the Angular CLI behaves quite weirdly. As you could expect, it changes the import order according to the build mode. 🤦‍
Take a look at issue #9475 of the Angular CLI GitHub repository if you're interested in this nonsense.

A quick workaround however, is to import the styles directly in your own style file, using the CSS @import rule.

@import "../../node_modules/primeicons/primeicons.css";
@import "../../node_modules/primeng/resources/primeng.min.css";
@import "../../node_modules/@patoche/balkany/dist/levallois-light/theme.css";

If your project uses a style preprocessor, you could also add your node_modules directory as an import path for your style files.

To do so, just think of the path to your node_modules directory relative to the sourceRoot property of your angular.json file... 💭

{
    "sourceRoot": "src",
    "stylePreprocessorOptions": {
        "includePaths": [
            "../node_modules/" // 👈 Just put it here
        ]
    }
}

Import rules in the CSS file look quite neat now. ✨

@import "primeicons/primeicons.css";
@import "primeng/resources/primeng.min.css";
@import "@patoche/balkany/dist/levallois-light/theme.css";

You could even take it further but we'll let you figure it out. 😏

2. Add PrimeNG components to your Angular module

Now that we've been through the weird part, you can just include PrimeNG modules normally. 😅

import { NgModule } from "@angular/core";

import { ButtonModule } from "primeng/button";

@NgModule({
    imports: [ButtonModule],
})
export class AppModule {}

3. Using PrimeNG components in you angular templates

You can use your components directly in markup. Balkany's Levallois Light theme will be applied to it. 🎨

<button pButton type="button" label="Click"></button> <p-button label="Click"></p-button>

📚 Documentation

Balkany's honest Angular components are visible here.

And, since Balkany's Angular components are plain simple PrimeNG components, only embezzled and laundered with care, you can find their documentation on the PrimeNG website.

Contributing

👥 Clone Balkany's Bitbucket repository

git clone https://bitbucket.org/renovationman/renovation-man-components-front.git

Oh wait, I'm afraid you need to be part of our organization to do this... We're really sorry but the repository is private at the moment.
But you know, it's really made to suit our needs so... You will probably find something that better fits your needs somewhere else. 🤷‍

📦 Install the dependencies

cd into the freshly cloned repository and run yarn to install the project dependencies.

cd renovation-man-components-front

yarn

👨‍💻 React development

Balkany loves telling stories. So he uses Storybook to develop and document his honest React components.

1️⃣ Prepare the battlefield

In this example we'll guide you step by stey through the creation a new logo component and its documentation in Storybook, from scratch.

First create a new logo directory inside the src/react/components directory, and populate it with an index.tsx file, where you'll define the React component, and a logo.scss file where you'll make it shine. ✨

mkdir src/react/components/logo

touch src/react/components/logo/index.tsx
touch src/react/components/logo/logo.scss

Then create a new logo.stories.tsx file inside the src/react/stories directory.

touch src/react/stories/logo.stories.tsx

2️⃣ Create a new React component

Let's create the logo component class.

Below is a minimum React component that take a variant property and displays either variant of the logo.

// Import everything from React
import * as React from "react";

// Import SCSS style file
import "./logo.scss";

// Import image files directly (svg, jpg, png, webp)
import blackLogo from "../../assets/logo-black.svg";
import defaultLogo from "../../assets/logo-default.svg";

// Component property typings
export type LogoProps = {
    /** Describe individual properties using JSDoc comments */
    variant?: "default" | "black";
};

// Define and export class component
export class Logo extends React.Component<LogoProps> {
    // Define default property values
    static defaultProps: ILogoProps = {
        variant: "default",
    };

    // Define a render function
    render() {
        const { variant } = this.props;

        const logo = variant === "black" ? blackLogo : defaultLogo;

        return <img className="logo" src={logo} />;
    }
}

3️⃣ Load the barrell

This is not mendatory, this is not optimal, this is just convenient.

Open src/react/components/index.ts, and export everything from your component file:

export * from "./logo";

This allows us to import components and typing in a concise way when writing stories:

import { Logo, LogoProps } from "components";

⚠️ Note however that the barrel file is excluded from the NPM package to ensure the component library is tree-shakable. Therefore, when a component imports another, it should do so using a relative path.

4️⃣ Tell the component's tale

Let's write a couple stories for your logo component.

// Import everything from React
import * as React from "react";

// Import the storiesOf helper
import { storiesOf } from "@storybook/react";

// Import your component
import { Logo } from "components";

// Define the stories
storiesOf("Logo", module)
    .add("Default logo", () => (
        <div className="column">
            <Logo />
        </div>
    ))
    .add("Black logo"), () => (
        <div className="column">
            <Logo variant="black" />
        </div>
    ));

We provide the column and row CSS classes as helpers, so you can quickly set a padded flex-layout to organize the elements of your stories.

5️⃣ Test the component in Storybook

Let's start the development server by running the dev:react script.

yarn dev:react

The development server starts on port 3000.

Angular development

TODO: Explain how to customize PrimeNG components TODO: Explain how to create custom Angular components

Deployment

Allright, let's deploy this baby!

Everything is already configured, so you really don't have to do much. 🤷‍

1️⃣ Check the package builds correctly

To do so just run the build script.

yarn build

Ensure you bumped the package version in the package.json file following semantic versioning.

{
    "name": "@patoche/balkany",
    "version": "0.15.4",
    ...
}

⚠️ For the time being, please do not bump to version 1.0.0, even in case of breaking changes!!!

2️⃣ Commit and push your changes to the `master` branch

You're good to go!

The Bitbucket pipeline will build the documentation for both Angular and React component libraries, and handle deployment to https://design.renovationman.com.

It will also build the PrimeNG theme as a CSS file, export the React components, and publish the @patoche/balkany package to NPM.

You can now check the Bitbucket pipeline status here.