Download the PHP package jiannius/atom without Composer

Atom

A Laravel UI component library built on Tailwind + Alpine + Livewire 4. Atom ships ~50 anonymous Blade components, a Livewire trait, an atom() runtime singleton for dispatching modals/toasts/alerts/confirms from PHP, a set of Laravel macros, and a pre-built JS/CSS bundle that the package serves itself — there is nothing to npm install in your host app.

• Composer: jiannius/atom
• Namespace: Jiannius\Atom\
• Custom Blade syntax: <atom:button>, <atom:input.text>, <atom:button.group> …

Requirements

Installation

The service provider (Jiannius\Atom\AtomServiceProvider) auto-registers via Laravel's package discovery. It will:

• Mount its routes under /atom/* (asset serving + action endpoint).
• Register all components under the atom view namespace.
• Install the <atom:...> Blade tag compiler.
• Swap Laravel's Date facade for Jiannius\Atom\Services\Carbon.
• Mix macros onto Eloquent\Builder, Query\Builder, ComponentAttributeBag, Request, Str, Stringable, and Arr.
• Register the artisan command atom:purge-editor-images.

No publishing step is required to get started.

Page boilerplate

Use <atom:html> once at the top of any full-page Blade view. It writes the <html>, <head>, meta tags, Tailwind base, atom's bundled CSS/JS, and your host app's Vite entry.

Useful <atom:html> props (all optional):

The package's own JS/CSS bundle is served from /atom/{file} (immutable, hashed via dist/manifest.json); you do not need to add it to your Vite config.

Component directory

With the package installed and APP_ENV=local, visit /atom/docs in your app for a browsable directory of every component: live previews, copyable code snippets, auto-generated prop tables, and searchable icon/logo galleries. The routes are not registered outside the local environment.

Service provider entry points (reference)

If something feels magic, the answer is almost always in src/AtomServiceProvider.php (boot order: routes → migrations → translations → views → components → tag compiler → date facade swap → macros → asset routes → /atom/action/{name} POST endpoint).

The <atom:...> tag syntax

src/Services/TagCompiler.php rewrites tags before Blade compiles:

Dot paths map to subdirectories. The classic <x-atom::...> form still works — <atom:...> is preferred for terseness.

Quickstart example

A typical Livewire 4 form using Atom:

Helpers

The atom() singleton

app('atom') (aliased) is a single entry point for runtime UI dispatch. Inside a Livewire component, prefer the trait methods ($this->toast(...)) — they delegate here but are shorter. Use app('atom')->... from controllers, jobs, or anywhere outside the component class.

All heading, subheading, and message strings are auto-passed through t() for translation.

Global functions (src/Helpers.php)

Examples:

The AtomComponent Livewire trait

use Jiannius\Atom\Traits\AtomComponent; on any Livewire component to get:

• WithPagination + WithFileUploads automatically.
• Reserved state buckets:
  • $_breadcrumbs — auto-populated from your optional breadcrumbs($crumbs) method.
  • $_table — sort, checkboxes, select-all, max rows, show-trashed (consumed by <atom:table> — see Table selection).
  • $_editor.images — temporary upload URLs for the rich text editor.
• Short methods that delegate to app('atom'):

Names the trait occupies

A trait method loses to a method of the same name on the class itself — with no error. So a component that defines one of these shadows atom's version. Whether that matters depends entirely on who calls the name, and the two halves are not equally risky.

Safe to shadow — nothing in atom ever calls these on your component. They're sugar that delegates to app('atom'), there for you to call and no one else. Define your own toast() and you get yours; you'll know, because you wrote it.

modal, command, toast, alert, confirm, action, wirekey, verifyRecaptcha

action is protected (see Upgrading to 3.25) — shadow it if you like, but define yours protected too. A public function action() on your component is callable from the browser as $wire.action(...), which is the exposure 3.25 removed.

Silent if shadowed — atom or Livewire invokes these by name, so redefining one kills the feature behind it with nothing to show for it. All of them are prefixed for exactly this reason; the prefix is the protection.

Yours to define: breadcrumbs (optional), tableQuery (required for tableSelection()), tableSelectionQuery (override for sticky selection).

Nothing else is reserved. The computed property feeding <atom:table :paginate="..."> is yours to name: atom neither defines nor looks for items, rows, records, data, or anything like them. tests/Feature/AtomComponentSurfaceTest.php pins this list, so it can't drift from the trait without a failing test.

The Enum trait

use Jiannius\Atom\Traits\Enum; on backed enums to get the convention used by Atom's status badges and selects:

Macros

Eloquent / Query Builder (src/Macros/Builder.php)

filter() knows about: named scopes (search, byFoo), enum casts, JSON columns, date columns, and the key:operator syntax ('price:>=' => 100).

Request (src/Macros/Request.php)

Str / Stringable (src/Macros/Str.php)

Arr (src/Macros/Arr.php)

ComponentAttributeBag (src/Macros/ComponentAttributeBag.php)

Used inside component templates:

Component catalog

All components live in components/. Open components/<name>/index.blade.php (or components/<name>.blade.php) to see the canonical @props([...]) list. The tables below list the most-used props per component.

Form inputs

Buttons & links

Display & typography

Heading levels

<atom:heading> renders a <div> unless you pass level, because most headings in an app UI are card titles, stat labels and table captions — visual, not structural. size and level are deliberately independent: size is how big it looks, level is where it sits in the document outline.

<atom:layouts.sidebar> supplies the page's <h1> itself, from its title prop — visually hidden, since the visible title comes from <atom:breadcrumbs>, which is a nav landmark and emits no heading element. So you do not need an <h1> in the page body; start at level="2".

Pass level where a section genuinely nests, and leave it off elsewhere:

A suggested mapping when a heading is structural: xl → level="1" (only outside the sidebar layout), lg → 2, default → 3, sm/xs → 4.

Feedback & overlays

The four window-level overlays (alert, toast, confirm) are usually dropped once in your root layout — drop them in <atom:layouts.sidebar> or near <atom:html> and dispatch from anywhere.

Layout & navigation

Remembering collapsed groups

An expandable group's open state lives in Alpine, so it resets on every page load. Give it a persist-key and it's remembered in localStorage instead:

expanded is only the starting state. A stored value always wins, so a group rendered :expanded="false" that the user has expanded stays open across reloads. That precedence is the point of the feature, and the answer to "why is my :expanded="false" ignored?"

Three things worth knowing:

• The key is namespaced under atom:navlist-group:, so passing "sidebar" can't collide with your app's own localStorage entries.
• Pass a key that's stable across pages — never one derived from the current route, or the group forgets itself the moment the user navigates.
• Two groups sharing a key sync. Not guarded, because that's usually what you want when the same nav renders in more than one layout.

Storage access is wrapped both ways: hardened browsers and Safari private mode throw on localStorage, and an uncaught throw would take the Alpine component down and stop the group toggling at all. It degrades to today's behaviour instead. Persistence is per-browser only — there's no server-side or cross-device state.

Miscellaneous

Table selection

Add checkbox to a header column and :checkbox="$item->id" to the matching cell:

Ticked ids collect in $_table.checkboxes and survive pagination and sorting, so a selection can span pages. The header checkbox selects or deselects the current page only. Bulk-action buttons go in the checked slot — that bar replaces the table header while anything is selected and shows the running count.

Cross-page "Select all N" — :select-all

Once a subset is ticked, a Select all N button appears. It sets a $_table.select_all flag rather than materialising an id list, so it costs the same for 20 rows or 200,000. Ticking an individual row or the header exits the mode.

Requires a tableQuery() on the component — the full scoped and filtered query:

Bulk actions then run off tableSelection(), which covers both modes:

Selection that survives a filter — :sticky-selection

By default a filter change, a search, or the trashed toggle clears the selection — the ticked rows may no longer be on screen, and a bulk action over invisible rows is a nasty surprise. Pass :sticky-selection for the opposite trade: keep the ids so a user can build one batch across several searches (tick 2, search, tick 1 more, act on all 3).

select_all still drops on a filter change — it means "everything matching this query", which stops being true the moment the query changes. The trashed toggle still clears everything, since live and soft-deleted rows aren't one result set. A persistent Clear selection appears in the checked bar, because part of the selection is off-screen and the user can't untick what they can't see.

The header slot also stays on screen instead of being swapped out for the checked bar — the two stack. Searching while holding a selection is the whole flow, and a table that hides its own search box the moment you tick a row can't support it.

Reviewing the batch — "Show selected"

A search hides part of the selection, so the checked bar carries a Show selected toggle that lists the selection instead of the filtered rows, search ignored. Flipping back restores the search results. Render the rows from tableRowsQuery() to wire it up:

The computed property is yours to name; <atom:table :paginate="$this->items"> is the only thing that has to agree with it. What atom owns is listed under Names the trait occupies.

Ticked rows stay unticked-able while the toggle is on, which is how a user prunes a batch they can no longer find by searching. The flag clears with the selection, and falls back to the filtered rows if the last row is unticked while it's on — otherwise the table would empty out and take its own toggle with it.

Note this is a filter to the selection, not a union with it: the search keeps returning what actually matches, so a 500-row batch never floods a result set and the paginator total stays honest.

This prop requires tableSelectionQuery() — the scoped but unfiltered base the checked ids resolve against:

Without it, ids ticked under an earlier filter get silently intersected away by the current one: the bar reads 3 selected and the delete hits 1. It defaults to tableQuery(), so a table that doesn't opt in is unaffected. It deliberately does not default to a bare newQuery() on the model — that would make the prop work with no override, but stays tenant-safe only where scoping is a global scope, and the consuming app is the only party that can say what "unfiltered but still scoped" means.

Clearing from a custom filter control

<atom:table.search>, <atom:select.filter> and <atom:date-picker.range> already dispatch the event. A hand-rolled control opts in the same way:

The AsEditorContent cast

Use this when you want a column to behave as Tiptap rich-text content with automatic image persistence:

What it does on save:

1. Scans the HTML for Livewire temporary preview URLs (/livewire-{hash}/preview-file/...).
2. Resizes each via Intervention Image (max width 1000, quality 80).
3. Persists to Storage::disk(env('FILESYSTEM_DISK')) under <configured folder>/editor/.
4. Rewrites the URLs back into the HTML, serializes the result.

get() lazily unserialize()s, falling back to the raw value if it isn't serialized.

Pair with the scheduled command to clean up images no longer referenced:

Actions

Named PHP classes you can invoke from PHP or, if they opt in, from the browser.

Resolution order:

1. App\Actions\{Name} (host app — wins).
2. Jiannius\Atom\Actions\{Name} (package fallback).

From PHP

Any action, any public method:

From the browser

Atom mounts POST /atom/action/{name} and the front-end exposes window.atom.action(name, params). That endpoint is public — no auth, reachable by anyone who can load the app — so it only runs actions that opt in by implementing Jiannius\Atom\Contracts\WebAction:

The endpoint:

• Answers 404 for anything that did not opt in — the same answer an unknown action gets, so it cannot be used to enumerate your action classes.
• Only ever calls handle(). method is a PHP-side convenience; over HTTP it is stripped from the params and ignored.
• Encodes the return value straight to the caller. Return the columns you mean to expose, not whole models.
• Does not rate-limit.

Gating who may call it

Declare authorize() on the action. The endpoint calls it before handle() and answers 403 when it returns false:

Actions without authorize() are callable by anyone, including guests — which is right for something like GetOptions (country and dial-code lists on public forms) and wrong for almost everything else. An action inheriting from an opted-in parent inherits the contract.

Upgrading to 3.25

3.25 makes the trait's action() helper protected. It was public, and Livewire exposes every public method a component declares — a trait method included, because reflection reports the using class as the declaring class. So on every component using AtomComponent, in every app:

reached any App\Actions\* class and any method on it, with no WebAction contract, no authorize(), and no allowlist. That is the hole 3.19 closed on POST /atom/action, standing open through Livewire the whole time. On a guest-facing page it was reachable without signing in.

What breaks: JS that calls the helper on the wire proxy. Find it with both spellings — Livewire proxies an exposed method under its own name, so the obvious grep misses most of it:

Migration, per hit: move the call to the public route, which has been the gated path since 3.19 — window.atom.action(name, params) — and opt the action in with implements \Jiannius\Atom\Contracts\WebAction plus an authorize(). See From the browser. If the call passed method, split that method into its own action; the route ignores method.

What does not change: server-side $this->action(...) inside a component, and atom()->action(...) from anywhere. Both still reach any action and any method — being protected only closes the browser door.

Upgrading to 3.20

3.20 closes three holes in GetOptions, the one action the package ships web-callable without authentication. All three were reachable by an anonymous caller:

• The option name picked a method. {"name":"purge-cache"} invoked purgeCache() on your subclass. method_exists() matches private, protected and inherited methods, and the call was made from inside the class, so all of them were reachable.
• The option name built a file path. {"name":"../../composer"} escaped resources/json/ and read the file.
• An unknown name threw, returning 500 with the absolute path in the log — an unauthenticated log flooder that also fired on an honest typo (country instead of countries).

What you must do, in every app with its own App\Actions\GetOptions: declare each option set in $auth (needs a signed-in caller) or $guest (readable by anyone). Undeclared sets return [] — the select goes empty — and log a warning naming the set. See GetOptions above.

Assume $auth unless you can say why a stranger may read every row. Sets like contacts, users, documents or taxes were guest-readable before this release; declaring them $guest keeps them that way.

$auth gates who is signed in, not which rows they get. Scope the queries too.

Upgrading to 3.19

Before 3.19 the endpoint ran any class in App\Actions\ — unauthenticated, and with the caller choosing which public method to invoke. It is now closed by default, so any action your JS calls goes dark until you opt it in.

1. Find them: grep -rn "atom.action(" resources/ (and any .js outside resources/). Each name maps to a class — Foo.Bar → App\Actions\Foo\Bar.
2. For each, add implements \Jiannius\Atom\Contracts\WebAction. Nothing else changes.
3. While you are in each file, decide whether it should have been public at all. Add authorize() to anything that reads or writes user data — before 3.19 it had no gate, so assume none of them do.
4. If you have your own App\Actions\GetOptions, make it extends \Jiannius\Atom\Actions\GetOptions — otherwise it shadows the package class without the contract and every remote-option select (<atom:select options="users">) in the app 404s.
5. If any JS passed method in the params, split that method into its own action — the endpoint ignores method now.
6. Check the app's CLAUDE.md/AGENTS.md. Atom's guidelines are copied into it rather than read from vendor/, and Boost rewrites that file on composer update — so the new rules arrive on their own, but any hand-edits you made to the atom section are overwritten at the same time. Re-apply them, or keep them outside that section.

Anything you do not opt in stays fully callable from PHP; only the browser path is affected.

If you miss one, the log says so. A refused action that exists writes a warning naming the class and the endpoint:

Requests for actions that don't exist stay silent, so this doesn't turn into noise from probing.

GetOptions: shared option lists

Jiannius\Atom\Actions\GetOptions loads option arrays from JSON files. It merges:

• Package JSON at <package>/json/{name}.json
• App JSON at resource_path('json/{name}.json')

with the app-side values taking precedence. Results are cached under _options.

Built-in JSON sets: countries, postcodes, colors. Override any of them by creating resources/json/colors.json in your host app.

To serve options from your database instead, create App\Actions\GetOptions extending the package class (it shadows it, and extending is what carries the WebAction contract that remote-option selects need). Each option set needs two things: a camelCase method, and its name declared in $auth or $guest.

Reach it by passing the set name as a string on options — that is what makes the select fetch rather than render a static list:

:options="[...]" (an array) is a static list; name is the field name and never selects an option set.

Why the declaration: the option name arrives in the request body, and it used to be turned straight into a method call. Anything zero-arg on your subclass was reachable from a browser, authenticated or not. Now the name only selects among the sets you listed, and a name in neither list returns an empty array.

• $auth — needs a signed-in caller. Everything backed by app data belongs here. A guest gets 403.
• $guest — readable by anyone. Only for sets where every row a stranger could pull back is safe to hand over.
• Undeclared — returns []. If a method of that name exists, a warning is logged naming the class and the set, so a select that has gone empty is diagnosable.

The package's own sets (countries, states, dialcodes, currencies, colors, postcodes) are always readable — guest address and phone forms need them — and you don't re-declare them.

$auth is a coarse gate: signed in or not. It does not scope rows. A signed-in user of tenant A calling a set that returns every tenant's rows still gets every tenant's rows, so scope the query itself as well.

Translation

t('Some string', $countOrParams, $params) is the translation shim. Almost every UI string in components passes through it, so to translate your app you just drop standard Laravel translation files under lang/{locale}/.

Front-end JS API

resources/js/atom.js is built to dist/ and served by the package; it boots automatically when <atom:html> renders. It exposes:

• window.atom.action(name, params) — POST to /atom/action/{name} (actions implementing WebAction only; see Actions).
• window.dd(...args) — console.log dump.
• window.empty(value) — truthy-empty helper.
• Alpine factories: modal, editor, select, tooltip, dropdown, lightbox, telInput, emailInput, breadcrumbs, datePicker, timePicker, dateRange, calendar, plus chart variants.
• $clipboard Alpine magic.
• Prototype additions on Array, Number, String (see resources/js/prototypes/).
• Alpine plugins loaded: @alpinejs/intersect, @marcreichel/alpine-autosize.

Conventions worth knowing

• Window-level Livewire events are prefixed atom- (atom-modal-show, atom-modal-close, atom-toast-show, atom-alert-show, atom-confirm-show). Grep by this prefix when tracing overlay state.
• <atom:button type="delete"> auto-dispatches confirmed on accept, which (unless overridden) calls $wire.delete().
• Date handling everywhere goes through Jiannius\Atom\Services\Carbon because of the Date::use() swap in the service provider.
• Components prefer Arr::toCssClasses([...]) and match over conditional class strings. See components/button/index.blade.php for the canonical pattern.
• The bundled dist/ directory is committed; the package serves it itself. If you fork and edit JS/CSS sources, run npm run build and commit dist/.
• atom.css defines [x-cloak] { display: none !important }, so x-cloak works out of the box in any app loading atom's stylesheet — Tailwind ships no such rule, and without one the attribute is inert. The !important matters: [x-cloak] and a utility like .flex have equal specificity, so otherwise the winner is whichever stylesheet loads last. Alpine strips the attribute on init, so the rule only ever hides pre-boot markup — which also means x-cloak must sit on an element Alpine will initialise (one carrying x-data, or inside one), or it stays hidden forever. tests/Feature/XCloakTest.php enforces both halves.

Artisan commands

License

MIT. See LICENSE.md.