Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/capevace/livewire-optimistic-ui
A utility package for better Optimistic UI support in Laravel Livewire.
https://github.com/capevace/livewire-optimistic-ui
Last synced: about 2 months ago
JSON representation
A utility package for better Optimistic UI support in Laravel Livewire.
- Host: GitHub
- URL: https://github.com/capevace/livewire-optimistic-ui
- Owner: Capevace
- License: mit
- Created: 2024-06-09T17:25:29.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-06-09T17:54:59.000Z (5 months ago)
- Last Synced: 2024-09-27T03:24:45.657Z (about 2 months ago)
- Language: JavaScript
- Size: 35.2 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Livewire Optimistic UI – A utility package for better Optimistic UI support in Laravel Livewire.
https://github.com/Capevace/livewire-optimistic-ui/assets/10093858/b5fd8cea-a9eb-4fc6-88af-b6809376a774
## Installation
You can install the package via composer:
```bash
composer require capevace/livewire-optimistic-ui
```
## Example
```html
# In your Livewire component's .blade.php file
Add +
@foreach($todos as $task)
@endforeach
```
```php
use Capevace\OptimisticUI\WithOptimisticUI;
use Capevace\OptimisticUI\Optimistic;
/**
* @property-read Collection $todos
*/
class OptimisticPage extends Component
{
use WithOptimisticUI;
#[Optimistic(crud: 'create', model: Task::class, injectOptimisticId: true)]
public function addTask(string $id, string $text): void
{
if (!uuid_is_valid($id) || Task::find($id)) {
return;
}
$task = new Task([
'text' => $text,
]);
$task->id = $id;
$task->save();
}
#[Optimistic(crud: 'delete', model: Task::class)]
public function deleteTask(string $id): void
{
Task::find($id)?->delete();
}
#[Optimistic(crud: 'update', model: Task::class)]
public function editTask(string $id, string $text): void
{
Task::find($id)?->update([
'text' => $text,
]);
}
#[Computed]
public function todos(): Collection
{
return Task::all();
}
public function render(): \Illuminate\View\View
{
return view("messages", [
'todos' => $this->todos,
]);
}
}
```
---
## Usage
### Adding optimistic UI to your Livewire component
You need to wrap your UI with the `x-optimistic::injector` component. This component will handle the optimistic UI for you.
```html
```
You can then call your functions optimistically by using the `$optimistic` object.
```html
@foreach($todos as $task)
@endforeach
```
### Displaying the added items
You can use the `x-optimistic::added` directive to display items that are added optimistically. The component will loop all added items and makes each available in the `$item` variable.
```html
```
## Optimistic Directives
You can add the `x-optimistic` directive to inject the optimistic state of a given item. The ID will be inferred from the `wire:key` attribute or can be passed with `x-optimistic=""`.
```html
```
## Optimistic Functions
To add an optimistic function to your Livewire component, you can use the `#[Optimistic]` attribute.
```php
use Capevace\OptimisticUI\Optimistic;
#[Optimistic(
fn: "update(params[0], { message: params[1] })"
)]
public function changeMessage(string $id, string $message): void
{
Message::find($id)->update([
'message' => $message,
]);
}
```
The Javascript in the `fn` parameter will be executed on the client-side when the function is called. The `params` array contains the parameters passed to the function.
### Locally generated IDs
When creating new items, a new UUID will be generated for the item. This ID identifies the item in transit. If you use this ID to actually create the item, you can support interactions with the items in transit, as they will be queued.
To use this feature, set the `injectOptimisticId` parameter to `true`.
Locally, you'd still be calling `$optimized.addTask(text)`, but the ID will be injected server-side.
```php
#[Optimistic(
fn: "create({ text: params[0] })"
injectOptimisticId: true
)]
public function addTask(string $id, string $text): void
{
if (!uuid_is_valid($id) || Task::find($id)) {
return;
}
$task = new Task([
'text' => $text,
]);
$task->id = $id;
$task->save();
}
```
### Ready-made CRUD functions
The most commonly used functions are implemented out of the box using the `crud` parameter.
Setting this to `create`, `update`, or `delete` will look at your PHP function's parameters using reflection and automatically generate the Javascript function for you.
You also need to supply the `model` parameter, which is then used to only allow updates to `fillable` attributes.
```php
#[Optimistic(crud: 'create', model: Task::class)]
public function addTask(string $id, string $text): void
{
if (!uuid_is_valid($id) || Task::find($id)) {
return;
}
$task = new Task([
'text' => $text,
]);
$task->id = $id;
$task->save();
}
#[Optimistic(crud: 'delete', model: Task::class)]
public function deleteTask(string $id): void
{
Task::find($id)?->delete();
}
#[Optimistic(crud: 'update', model: Task::class)]
public function editTask(string $id, string $text): void
{
Task::find($id)?->update([
'text' => $text,
]);
}
```
## Testing
```bash
composer test
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## Security Vulnerabilities
Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
## Credits
- [Lukas Mateffy](https://github.com/Capevace)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.