README.md

Vitrine

This library is under active development and name is subject to change in feature release.

Vitrine is a library of components crafted by AREA 17 to use inside Laravel applications.

Components follow the best practices around performance, accessibility, and maintainability.

Installation

This package is not yet available on Packagist. You can install it from GitHub: Add the repository to your composer.json file:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/area17/vitrine-ui.git"
        }
    ]
}

composer require area17/vitrine-ui

If you need specific configuration, you can publish the config file:

You can publish the config file with:

php artisan vendor:publish --tag="vitrine-ui-config"

Usage

Use component

Modal:

<x-vui-modal> ... </x-vui-modal>

Heading

<x-vui-heading> ... </x-vui-heading>

Button

<x-vui-button> ... </x-vui-button>

Some components require CSS/JS:

Add aliases to project vite.config.js:

export default ({ mode }) =>
    defineConfig({
        resolve: {
            alias: {
                "@vitrineUI": resolve(__dirname, "vendor/area17/vitrine-ui"),
                "@vitrineUIComponents": resolve(
                    __dirname,
                    "vendor/area17/vitrine-ui/resources/views/components/",
                ),
            },
        },
    });

Import behaviors

1. Import single component behavior (Recommended!)

import { manageBehaviors } from "@area17/a17-behaviors";
import ModalBehavior from "@vitrineUIComponents/modal/modal";

document.addEventListener("DOMContentLoaded", async function () {
    manageBehaviors.init({ ...ModalBehavior, ...Behaviors });
});

Or

import { manageBehaviors } from "@area17/a17-behaviors";
import * as Behaviors from "./behaviors";
import * as VitrineBehaviors from "./behaviors/vitrine"; /* import only the needed behaviors from VitrineUI */

document.addEventListener("DOMContentLoaded", function () {
    // expose manageBehaviors
    window.A17.behaviors = manageBehaviors;
    // init behaviors!
    // TBD: We may switch to direct import instead of barrel file
    window.A17.behaviors.init({
        ...VitrineBehaviors,
        ...Behaviors,
    });
});

And in your project, create ./behaviors/vitrine.js to list the needed behaviors only :

export { default as Modal } from "@vitrineUI/resources/frontend/scripts/behaviors/Modal.js";
export { default as Pagination } from "@vitrineUI/resources/frontend/scripts/behaviors/Pagination.js";

2. Or use Barrel File : Import all component behaviors (Not recommended!)

import { manageBehaviors } from "@area17/a17-behaviors";
import * as VitrineBehaviors from "@vitrineUI/resources/frontend/scripts/behaviors";

document.addEventListener("DOMContentLoaded", async function () {
    manageBehaviors.init({ ...VitrineBehaviors, ...Behaviors });
});

Custom Events

Custom Events are referenced into a shared object so you can easily use these in new behaviors created outside Vitrine.

import { customEvents } from "@vitrineUI/resources/frontend/scripts/constants/customEvents.js";

/* Trigger openModal() when a modal is opened into the document */
document.addEventListener(customEvents.MODAL_OPENED, this.openModal, false);

Publish Components

You can publish the components using the vitrine-ui:publish command. You can specify components by adding their names as arguments. If you don't specify any components and don't pass the --all option, it will prompt to select components to publish.

Supported options:

• --all : publish all vitrine-ui components
• --view : Publish only the view of the component
• --class : Publish only the class of the component
• --force : Overwrite existing files
• --stories : Publish only the stories for the component

Theming

Each component has default classes that you can customize through its associated JSON file located in the components folder. You can override this config in your Laravel application by updating 'vitrine_path' key set in vitrine-ui config

Configure tailwind for theming in your laravel application tailwind.config.js:

module.exports = {
    content: [join(rootPath, "/resources/frontend/vitrine-ui/**/*.{js,json}")],
};

Example of a component JSON config :

{
    "base": "custom-class",
    "wrapper": "custom-class"
}

The base key will replace the base component classes, which is the root DOM element of the component. For some components, other properties are customizable. Refer to the component's stories to see which properties can be themed.

The configuration will replace existing default vitrine-ui classes. You can change this behavior by specifying merge rules in your component's JSON config and specifying elements.

{
    "rules": {
        "merge": "base"
    },
    "base": "custom-class",
    "wrapper": "custom-class"
}

You can also override the json configuration directly in the component call by passing 'ui' key :

<x-vui-component
    :ui="[
    'json-file-name' => [
        'base' => [
            'custom-class',
        ],
    ],
]"
>
    ...
</x-vui-component>

Add variants

For some components, you can also add variants by including a variant key in the component's JSON config.

{
    "base": "custom-class",
    "wrapper": "custom-class",
    "variant": {
        "primary": "variant-primary-class",
        "secondary": "variant-secondary-class"
    }
}

To use a variant, specify it in the component call:

<x-vui-component variant="primary"> ... </x-vui-component>

Retrieve config CSS classes

You can retrieve CSS classes from the JSON configuration file by calling the Vitrine's helper using the following syntax:

VitrineUI::ui('json_file_name', 'key_in_json_file', array_of_options)

array_of_options can be used for variant mapping.

IDE configuration

Auto-completion for Vitrine's components is supported on PhpStorm and VS Code.

Phpstorm

For Phpstorm, you need to have Laravel idea plugin installed.

Vitrine contains an ide.json file that will be read by the plugin.

This file looks for the components key inside the Vitrine's config file. If your published the config file in your project. You can lose auto-completion feature if you remove the components key inside the published file.

VS Code

VS Code autocompletion support is available from a fork of blade-components plugin.

A packaged version of the plugin can be downloaded here: blade-components-next-1.0.0.vsix.

You can manually install the plugin by following instructions from VS Code documentation.

Please note that this package is currently in development and may not work as expected.

Development

Installation

$ composer install
$ npm install # to install git hooks and linters

Linters and code formatters

We are using a series of tools to prettify and lint the code we write:

• Husky: to install and run the pre-commit hooks
• PHPStan: to do static analysis check on PHP code
• PHP-CS-Fixer: to remove unused dependencies and do some basic formatting
• Prettier: to fully format the code
• Eslint: to find and fix problems in JavaScript files
• Git conflict markers: the pre-commit checker tool also checks if the developer didn't stage any Git conflicted files by looking for conflict markers on the staged files.

These tools are executed automatically on every commit, only on staged files, and for it to work you need to make sure you executed. Composer and NPM are responsible for making sure husky is installed. And these commands are also available if a developer needs to run the commands manually:

Global commands:

• sh tools/linters.sh lint
• sh tools/linters.sh format

Specific commands:

• sh tools/linters.sh phpstan
• sh tools/linters.sh eslint
• sh tools/linters.sh prettify
• sh tools/linters.sh php-cs-fixer

Commands execution also generates a log file with the result at tools/logs/.log, you can check for PHPStan errors on this file, for example. Linter commands have available aliases and can be run through Composer or NPM. For more details take a look to composer.json file and package.json file.

## Testing

```bash
composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

Vitrine library is licensed under the Apache 2.0 license.