README

User-Interface Scaffolding for Laravel. Powered by TailwindCSS.

Prerequisites

Since this package relies on a few 3rd party packages, you will need to have the following installed and configured in your project:

Installation

Require with composer: composer require arkecosystem/ui
Publish all the assets / views with php artisan vendor:publish --provider="ARKEcosystem\UserInterface\UserInterfaceServiceProvider" --tag="css" --tag="fonts" --force. If you need custom pagination, then also run php artisan vendor:publish --provider="ARKEcosystem\UserInterface\UserInterfaceServiceProvider" --tag="pagination"
Import the vendor css assets in your app.css file
Import the vendor tailwind.config.js file in your own tailwind config and build on top of that if you need additional changes
Use the components in your project with <x-ark-component>
Add the following snippet to your webpack.mix.js file to be able to use the @ui alias:

mix.webpackConfig({
        resolve: {
            alias: {
                '@ui': path.resolve(__dirname, 'vendor/arkecosystem/ui/resources/assets/')
            }
        }
    })
    ...

Protip: instead of running step 3 manually, you can add the following to your post-autoload-dump property in composer.json:

"post-autoload-dump": [
    "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
    "@php artisan package:discover --ansi",
    "@php artisan vendor:publish --provider=\"ARKEcosystem\\UserInterface\\UserInterfaceServiceProvider\" --tag=\"css\" --tag=\"fonts\""
],

Protip: you can publish individual assets by using their tag, e.g. --tag="css", --tag="images", etc

Protip 2: in order to lazy-load icons, you will need to publish them by using their tag, e.g. --tag=\"icons\"

Navbar / Avatar Component

The navigation bar makes use of our own PHP implementation of picasso to generate a default avatar (in line with the Desktop Wallet). You will need to set this up in your project as follows:

Pass an $identifier value to the navbar component be used as seed for the generation of the image

Clipboard

Add clipboard to Laravel Mix config

.copy('vendor/arkecosystem/ui/resources/assets/js/clipboard.js', 'public/js/clipboard.js')

Add clipboard to any pages that need it

@push('scripts')
    <script src="{{ mix('js/clipboard.js')}}"></script>
@endpush

Install tippy.js

yarn add tippy.js

Add the following snippet to your resources/app.js

window.initClipboard = () => {
    tippy('.clipboard', {
        trigger: 'click',
        content: (reference) => reference.getAttribute('tooltip-content'),
        onShow(instance) {
            setTimeout(() => {
                instance.hide();
            }, 3000);
        },
    });
}

Modals

Install body-scroll-lock

yarn add body-scroll-lock

Import the modal script in your resources/js/app.js file

import Modal from "@ui/js/modal";

window.Modal = Modal;

WYSIWYG Markdown editor

Install the npm dependencies

yarn add @toast-ui/editor@^2.5.2 codemirror@^5.62.0

Ensure to import the markdown script inside the <head> tag of your template.

@push('scripts')
    <x-ark-pages-includes-markdown-scripts />
@endpush

Assigning to the window object is now done in the markdown script itself, therefore there is no need to import and assign this script manually!

Configure webpack.mix with the markdown plugin

// Import the following script in the `webpack.mix.js` file
require('./vendor/arkecosystem/ui/laravel-mix/markdownPlugin.js');

// If the Tailwind Config file in your project is `tailwind.config.js`
// you dont need to pass any argument
mix.markdown('tailwind.app.config.js')

Add the markdown component to your form

<x-ark-markdown name="about" />

You can change the height and the toolbar preset:

<x-ark-markdown name="about"
    height="300px"
    toolbar="full"
/>

You can choose to limit the characters to be inserted:

<x-ark-markdown name="about"
    chars-limit="1000"
/>

Accepts full for all the plugins and basic for only text related buttons.

If you use the image upload plugin your page will need to have the csrf_token in the metadata.

<meta name="csrf-token" content="{{ csrf_token() }}">

Tags input

Add taggle dependency yarn add taggle and ensure to copy the scripts to the public directory:

// webpack.mix.js file
    mix.copy('node_modules/taggle/dist/taggle.min.js', 'public/js/taggle.js')

Add the Tags script to the main js file

import Tags from "@ui/js/tags";

window.Tags = Tags;

Ensure to import the taggle scripts

@push('scripts')
    <script src="{{ mix('js/taggle.js')}}"></script>
@endpush

Use the component like the rest of the components. It accepts tags and allowed-tags props.

<x-ark-tags :tags="['tag1', 'tag2']" name="tags" :allowed-tags="['taga', 'tagb']" />

User tagger input

Add tributejs dependency yarn add tributejs and ensure to copy the scripts to the public directory:

// webpack.mix.js file
    mix.copy('node_modules/tributejs/dist/tribute.min.js', 'public/js/tribute.js')

Import the user tagger script into the main js file and import the styles in your css file

import "@ui/js/user-tagger.js";

@import "../../vendor/arkecosystem/ui/resources/assets/css/_user_tagger.css";

Ensure to import the tributejs scripts in the places where the component will be used

@push('scripts')
    <script src="{{ mix('js/tribute.js')}}"></script>
@endpush

Use the component like you use the textarea input

<x-ark-user-tagger
    name="body"
    :placeholder="trans('forms.review.create_message_length')"
    rows="5"
    wire:model="body"
    maxlength="1000"
    required
    hide-label
>{{ $body }}</x-ark-user-tagger>

This component makes a GET request to the /api/users/autocomplete endpoint with the query as q, that query should be used to search the users and should return them in the following format:

Note: You can change the the URL by using the endpoint prop.

[
    {
        "name":"Foo Bar",
        "username":"foo.bar",
        "avatar":"SVG AVATAR OR URL"
    },
    {
        "name":"Other user",
        "username":"user_name",
        "avatar":"SVG AVATAR OR URL"
    },
    ...
]

The component accepts a usersInContext prop that expects an array of usernames. These usernames will be sent in the search query request as context and can be used to show those users first in the response. Useful to show the user in the conversation first.

Honeypot

Install dependency

composer require lukeraymonddowning/honey

Setup honeypot

php artisan honey:install

Database Migration

php artisan migrate

Livewire modals

To use the Livewire modals, use the ARKEcosystem\UserInterface\Http\Livewire\Concerns\HasModal trait in your component class. The trait adds the closeModal and openModal methods that toggle the modalShown property that is the one you should use to whether show or hide the modal.

Important: If you need to use a different variable to close the modal, or you can't make use of the trait for a reason, make sure to emit the modalClosed event as that is required for proper handling of the modals on the frontend! If you fail to emit this event, the browser window will not be scrollable after the modal disappears.

Alpine modals

Important: for the modals to work properly, they expect a nav element inside a header element to be used for the header component. If you use the navbar from the UI lib (see navbar.blade.php) these elements are already used, but for custom navbars you may need to make adjustments.

There's a few ways you can make use of the new modals in conjunction with Alpine:

For JS-only modals, you need to use the <x-ark-js-modal /> component. You need to initiate the modal with a name (using the name attribute) and it can be opened by calling Livewire.emit('openModal', 'name-of-my-modal')

<x-ark-js-modal name="name-of-my-modal'">
    @slot('description')
        My Description
    @endslot
</x-ark-js-modal>

<button onclick="Livewire.emit('openModal', 'name-of-my-modal')">Open modal</button>

Alternatively, if you wrap the modal inside another Alpine component, you can use the Modal.alpine() method to init the modal (don't forget to call the init method on x-init).

The Modal.alpine() method accepts an object as the first argument. This object will be merged with the original Modal data.

Inside that component, you can use the show() method to show the modal:

<div
    x-data="Modal.alpine({}, 'optionalNameOfTheModal')"
    x-init="init"
>
    <button type="button" @click="show">Show modal</button>

    <x-ark-js-modal
        class="w-full max-w-2xl text-left"
        title-class="header-2"
        :init="false"
    >
        @slot('description')
            My Description
        @endslot
    </x-ark-modal>
</div>

Note that it is also possible to hook into the lifecycle methods of the modal. You can override the onBeforeHide, onBeforeShow, onHidden, and onShown properties with custom methods if you require so.

<div
    x-data="Modal.alpine({
        onHidden: () => {
            alert('The modal was hidden')
        },
        onBeforeShow: () => {
            alert('The modal is about to be shown')
        }
    }"
    x-init="init"
>
    <button type="button" @click="show">Show modal</button>

    <x-ark-js-modal
        class="w-full max-w-2xl text-left"
        title-class="header-2"
        :init="false"
    >
        @slot('description')
            My Description
        @endslot
    </x-ark-js-modal>
</div>

import Modal from "@ui/js/modal";

window.Modal = Modal;

Tooltips

Install tippy.js

yarn add tippy.js

Add to webpack mix

.js('vendor/arkecosystem/ui/resources/assets/js/tippy.js', 'public/js')

Add tippy to any pages that need it

@push('scripts')
    <script src="{{ mix('js/tippy.js')}}" defer></script>
@endpush

Slider

Install swiper

yarn add -D swiper

Add swiper to Laravel Mix config

.copy('node_modules/swiper/swiper-bundle.min.js', 'public/js/swiper.js')

Add swiper to any pages that need it

@push('scripts')
    <script src="{{ mix('js/swiper.js')}}"></script>
@endpush

Include swiper CSS

@import "../../node_modules/swiper/swiper-bundle.min.css";

Add the following to the app.js file:

import Slider from "@ui/js/slider";

window.Slider = Slider

Date Picker

Install pikaday

yarn add -D pikaday

Include pikaday CSS

@import "../../node_modules/pikaday/css/pikaday.css";
@import '../../vendor/arkecosystem/ui/resources/assets/css/_pikaday.css';

Notifications Indicator

Add this to your user migration table

$table->timestamp('seen_notifications_at')->nullable();

use Domain\Components\NotificationsIndicator;
...
Livewire::component('notifications-indicator', NotificationsIndicator::class);

Prism Codeblock

Add prism js to Laravel webpack mix

.js('vendor/arkecosystem/ui/resources/assets/js/prism.js', 'public/js')

Add prism to any pages that need it

@push('scripts')
    <script src="{{ mix('js/prism.js')}}"></script>
@endpush

Include prism CSS

@import "../vendor/ark/_prism-theme.css";

Install prism.js

yarn add -D prism-themes prismjs

Add the following snippet to resources/prism.js

import "../vendor/ark/prism";

document.addEventListener("DOMContentLoaded", () => {
    document
        .querySelectorAll("pre")
        .forEach((pre) => useHighlight(pre, { omitLineNumbers: false }));
});

Image Collection Sortable

Install Livewire Sortable

yarn add -D livewire-sortable

Add the following snippet to your resources/app.js

import 'livewire-sortable'
// Or.
require('livewire-sortable')

Add imagesReordered method to handle index reordering when an image is sorted.

public function imagesReordered(array $ids): void
{
    Media::setNewOrder($ids);
}

Then, you can use upload-image-collection component with sortable functionality.

<x-ark-upload-image-collection id="media" :images="$this->imageCollection" sortable />

Tabs

Add the following to the app.js file:

import "@ui/js/tabs.js";

<x-ark-tabbed>
    <x-slot name="tabs">
        <x-ark-tab name="tab-1" />
        <x-ark-tab name="tab-2" />
        <x-ark-tab name="tab-3" />
    </x-slot>
    
    <x-ark-tab-panel name="tab-1">...</x-ark-tab-panel>
    <x-ark-tab-panel name="tab-2">...</x-ark-tab-panel>
    <x-ark-tab-panel name="tab-3">...</x-ark-tab-panel>
</x-ark-tabbed>

For the available parameters, please refer to the EXAMPLE.md

Error Pages

There are also default error pages you can use for your Laravel project

Run php artisan vendor:publish --provider="ARKEcosystem\UserInterface\UserInterfaceServiceProvider" --tag="error-pages"
Add the following snippet to your menus.php lang file:

'error' => [
    '401' => '401 Unauthorized',
    '404' => '403 Forbidden',
    '404' => '404 Not Found',
    '419' => '419 Unauthorized',
    '429' => '429 Too Many Requests',
    '500' => '500 Internal Server Error',
    '503' => '503 Unavailable',
]

Please test if the pages work by manually going to a url that should throw an error

Available Components

<x-ark-accordion>
<x-ark-accordion-group>
<x-ark-alert>
<x-ark-breadcrumbs>
<x-ark-checkbox>
<x-ark-clipboard>
<x-ark-dropdown>
<x-ark-expandable>
<x-ark-input>
<x-ark-navbar>
<x-ark-radio>
<x-ark-secondary-menu>
<x-ark-select>
<x-ark-sidebar-link>
<x-ark-tags>
<x-ark-textarea>
<x-ark-toggle>
<x-ark-upload-image-single>
<x-ark-upload-image-collection>
<x-ark-font-loader>
<x-ark-tabs>

See the example file for more in-depth usage examples

Livewire Pagination Scroll

Add the following to app.js file:

import "@ui/js/page-scroll";

Use the HasPagination trait on Livewire Components:

use ARKEcosystem\UserInterface\Http\Livewire\Concerns\HasPagination;

class Articles {
    use HasPagination;
}

Add event trigger at the bottom of the component template:

<div>
    ...

    <x-ark-pagination :results="$articles" class="mt-8" />

    <script>
        window.addEventListener('livewire:load', () => window.livewire.on('pageChanged', () => scrollToQuery('#article-list')));
    </script>
</div>

Pagination

Publish the pagination assets

php artisan vendor:publish --provider="ARKEcosystem\UserInterface\UserInterfaceServiceProvider" --tag="pagination"

Add the following to the app.js file:

import Pagination from "@ui/js/pagination";

window.Pagination = Pagination

All set, now you can use the pagination component

<x-ark-pagination :results="$results"  />

Footer

Add the following snippet to your urls.php lang file:

'discord'  => 'https://discord.ark.io/',
'facebook' => 'https://facebook.ark.io/',
'github'   => 'https://github.com/ArkEcosystem',
'linkedin' => 'https://www.linkedin.com/company/ark-ecosystem',
'reddit'   => 'https://reddit.ark.io/',
'twitter'  => 'https://twitter.ark.io/',
'youtube'  => 'https://youtube.ark.io/',

Available Styles

It's advised to make use of the styles for generic components so we keep them similar throughout projects

Buttons
Tables
Tabs

In-progress

more styles, and proper configuration to define where styles are published

Blade Support

Avatar

In config/app.php under aliases, add the following entry:

'Avatar' => ARKEcosystem\UserInterface\Support\Avatar::class,

Date Format

In config/app.php under aliases, add the following entry:

'DateFormat' => ARKEcosystem\UserInterface\Support\DateFormat::class,

Format Read Time method for blade (generally used for blog date/time output)

In config/app.php under providers, add the following entry:

ARKEcosystem\UserInterface\Providers\FormatReadTimeServiceProvider::class,

SVG Lazy-Loading Icons

In config/app.php under providers, add the following entry:

ARKEcosystem\UserInterface\Providers\SvgLazyServiceProvider::class,

This will initiate the svgLazy directive and allow you to load icons from the arkecosystem/ui package. For example:

@svgLazy('checkmark', 'w-5 h-5')

This will insert the following HTML:

<svg lazy="/icons/checkmark.svg" class="w-5 h-5" />

Protip: You will need lazy.js in order for this to work

Development

If components require changes or if you want to create additional components, you can do so as follows:

Vendor folder

This approach is recommended to test out smaller changes. You can publish the views by running php artisan vendor:publish --tag=views, and they will show up in the views/vendor/ark folder. From there you can edit them to your liking and your project will make use of these modified files. Make sure to later commit them to this repository when you have made your changes to keep the files throughout projects in sync.

Components Folder

When you create a views/components folder, you can create new blade files inside it and they will automatically become available through <x-your-component> to be used in your project. This way you can create new components, test them, and then copy them to the arkecosystem/ui repo when finished.

Afterwards you can add new components to the local package and use it in your project for testing.

Icons

If you need to add, replace or delete an icon:

move the new icon in or remove it from /resources/assets/icons
run yarn run generate-icon-preview
open icons.html and check if the icon is present

Tailwind Configuration

There are a few tailwind configuration additions on which the components rely (e.g. colors and additional shadows) and are therefore expected to use the tailwind config in this repository as basis (you can import it and extend it further if needed).

arkecosystem / ui

Maintainers

Details