Mary

https://github.com/robsontenorio/mary
Admin
maryUI is a library of Blade UI components for Laravel Livewire apps, styled with daisyUI and...
Tokens:110,146
Snippets:711
Trust Score:9.9
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### Start the dev server

Source: https://github.com/robsontenorio/mary/blob/main/README.md

Starts the development server using Yarn to compile assets and watch for changes.

```bash
yarn dev
```

--------------------------------

### Install and bootcamp commands

Source: https://github.com/robsontenorio/mary

Shows the available artisan commands for installing and scaffolding the Mary UI package. The install command can be run interactively or with flags to force a package manager and optionally skip CSS. The bootcamp command scaffolds a demo app.

```bash
php artisan mary:install          # interactive; picks detected package manager
```

```bash
php artisan mary:install --npm --no-css
```

```bash
php artisan mary:install --pnpm    # force pnpm and publish config on collision detection
```

```bash
php artisan mary:bootcamp          # scaffold the demo bootcamp app
```

--------------------------------

### Usage Examples

Source: https://github.com/robsontenorio/mary

Blade usage examples for the DatePicker component.

```blade
<x-datepicker label="Birth date" wire:model="birthdate" />
```

```blade
<x-datepicker
    label="Trip dates"
    wire:model="range"
    :config="['mode' => 'range']"
    error-field="range"
/>
```

--------------------------------

### setup() JSON output structure

Source: https://github.com/robsontenorio/mary

Shows the JSON structure returned by `setup()`, merging `config` over defaults. `type` is 'default' or 'multiple' based on `months == 1`, `firstWeekday` is 0 or 1 depending on `sundayStart`, and `selectedWeekends` is `[0,6]` when `weekendHighlight` is true.

```json
{
  "type": "default" | "multiple",       // based on months == 1
  "displayMonthsCount": <months>,
  "monthsToSwitch": <months>,
  "popups": <popups()>,
  "locale": <locale>,
  "firstWeekday": 0 | 1,                 // sundayStart ? 0 : 1
  "selectedWeekends": [0, 6] | [],       // weekendHighlight ? [0,6] : []
  "selectionDatesMode": false,
  "displayDatesOutside": false,
  "styles": {
    "calendar": "vc w-fit",
    "grid": "vc-grid justify-center",
    "column": "vc-column !min-w-fit !max-w-fit"
  }
}
```

--------------------------------

### Example Spotlight class implementation

Source: https://github.com/robsontenorio/mary

Example implementation of the Spotlight class that must be provided. The search method receives the request and returns a collection of items with 'name', 'link', and optional 'icon' fields. This class is used by the endpoint to handle search requests.

```php
// app/Support/Spotlight.php
namespace App\Support;

use Illuminate\Http\Request;
use Illuminate\Support\Collection;

class Spotlight
{
    public function search(Request $request): Collection
    {
        return collect([
            ['name' => 'Dashboard', 'link' => '/dashboard', 'icon' => '<svg>...</svg>'],
        ]);
    }
}
```

--------------------------------

### Default config JSON for DatePicker setup()

Source: https://github.com/robsontenorio/mary

JSON structure built by setup() merging defaults with user config, excluding plugins. Placeholders are replaced with generated JS and model value.

```json
{
  "dateFormat": "Y-m-d H:i",
  "altInput": true,
  "altInputClass": " ",
  "clickOpens": <!readonly>,
  "defaultDate": "#model#",
  "plugins": ["#plugins#"],
  "disable": ["#disable#"]
}
```

--------------------------------

### setup() Method (DatePicker)

Source: https://github.com/robsontenorio/mary

Builds the configuration JSON for the DatePicker, handling range mode and merging config with defaults.

```APIDOC
## setup(): string

### Description
Builds the configuration JSON for the DatePicker, merging provided config with defaults and handling range mode.

### Behavior
- If `config["mode"] == "range"` and the `wire:model` has a `live` modifier, it rewrites the model to a plain `wire:model` + `live` attribute.
- Builds a JSON config merging `Arr::except($this->config, ["plugins"])` with defaults:

```json
{
  "dateFormat": "Y-m-d H:i",
  "altInput": true,
  "altInputClass": " ",
  "clickOpens": <!readonly>,
  "defaultDate": "#model#",
  "plugins": ["#plugins#"],
  "disable": ["#disable#"]
}
```

- Replaces placeholders `#plugins#`, `#disable#`, and `#model#` with generated JS and model value.
```

--------------------------------

### setup(): string

Source: https://github.com/robsontenorio/mary

Returns a JSON string merging the provided config over the calendar defaults, used to initialize the VanillaCalendarPro instance.

```APIDOC
## setup(): string

### Description
Returns JSON merging `config` over defaults.

### Method
setup

### Returns
- **string** - JSON configuration string.

### Response Example
```json
{
  "type": "default" | "multiple",       // based on months == 1
  "displayMonthsCount": <months>,
  "monthsToSwitch": <months>,
  "popups": <popups()>,
  "locale": <locale>,
  "firstWeekday": 0 | 1,                 // sundayStart ? 0 : 1
  "selectedWeekends": [0, 6] | [],       // weekendHighlight ? [0,6] : []
  "selectionDatesMode": false,
  "displayDatesOutside": false,
  "styles": {
    "calendar": "vc w-fit",
    "grid": "vc-grid justify-center",
    "column": "vc-column !min-w-fit !max-w-fit"
  }
}
```
```

--------------------------------

### Usage Examples

Source: https://github.com/robsontenorio/mary

Blade usage examples for the calendar component with events and configuration.

```blade
<x-calendar
    :events="[
        ['label' => 'Launch', 'date' => '2024-05-01', 'css' => 'vc-primary'],
        ['label' => 'Sprint', 'description' => 'Two weeks', 'range' => ['2024-05-06', '2024-05-17'], 'css' => 'vc-secondary'],
    ]"
    weekend-highlight
/>
```

```blade
<x-calendar
    :months="3"
    locale="pt-BR"
    :config="['selectionDatesMode' => true]"
/>
```

--------------------------------

### Usage Examples

Source: https://github.com/robsontenorio/mary

Blade usage examples for the selection components: Select, Radio, and Toggle.

```blade
<x-select
    label="Country"
    :options="['BR' => 'Brazil', 'US' => 'United States']"
    wire:model="country"
/>
```

```blade
<x-radio
    label="Plan"
    :options="$plans"
    option-value="slug"
    option-label="name"
    option-hint="price"
    inline
    wire:model="plan"
/>
```

```blade
<x-toggle label="Notify me" wire:model="notify" :omit-error="true" />
```

--------------------------------

### Public methods for DatePicker and DateTime

Source: https://github.com/robsontenorio/mary

List of public methods available on both components. DatePicker additionally defines setup(), while DateTime does not.

```php
public function modelName(): ?string;
public function errorFieldName(): ?string;
public function isReadonly(): bool;
public function isDisabled(): bool;
public function setup(): string;   // DatePicker only
public function render(): View|Closure|string;
```

--------------------------------

### Display components usage examples (x-alert, x-breadcrumbs, x-button, x-progress, x-signature, x-theme-toggle, x-toast)

Source: https://github.com/robsontenorio/mary

Blade examples for Mary UI display components: alert with dismissible option, breadcrumbs with items array, button with spinner, progress bar, signature pad, theme toggle, and toast container. Use these as a quick reference for common display component usage.

```blade
<x-alert title="Attention" icon="o-exclamation-triangle" dismissible>
    Something needs attention.
</x-alert>

<x-breadcrumbs :items="[['label' => 'Home', 'link' => '/'], ['label' => 'Users']]" />

<x-button label="Save" icon="o-check" class="btn-primary" spinner="save" />

<x-progress :value="75" />

<x-signature label="Sign here" height="300" clear-text="Reset" wire:model="signatureModel" />

<x-theme-toggle with-label />

<x-toast position="toast-top toast-start" />
```

--------------------------------

### MaryInstallCommand class definition

Source: https://github.com/robsontenorio/mary

Defines the mary:install Artisan command with options for package managers (--yarn, --npm, --bun, --pnpm) and --no-css to skip CSS changes. The handle() method orchestrates installation steps, requiring Laravel ≥ 12.0.

```php
namespace Mary\Console\Commands;

class MaryInstallCommand extends Command
{
    protected $signature = 'mary:install
                            {--yarn : Use yarn as package manager}
                            {--npm : Use npm as package manager}
                            {--bun : Use bun as package manager}
                            {--pnpm : Use pnpm as package manager}
                            {--no-css : Do not place changes on `app.css`}';
    protected $description = 'Command description';
    protected $ds = DIRECTORY_SEPARATOR;

    public function handle(): void;
    public function installLivewire(): void;
    public function setupTailwindDaisy(string $packageManagerCommand): void;
    public function renameComponents(): void;
    public function copyStubs(): void;
    public function askForPackageInstaller(): string;
    public function checkForLaravelVersion(): void;
}
```

--------------------------------

### Catch ProcessFailedException from mary:install command

Source: https://github.com/robsontenorio/mary

Catches the Symfony ProcessFailedException that bubbles up when composer require livewire/livewire or the daisyui/tailwindcss install fails during php artisan mary:install. Use this when invoking the installer programmatically.

```php
try {
    $this->artisan('mary:install', ['--npm' => true]);
} catch (\Symfony\Component\Process\Exception\ProcessFailedException $e) {
    // command failed
}
```

--------------------------------

### Usage of Mary facade

Source: https://github.com/robsontenorio/mary

Example of calling Mary::hello() via the facade, which proxies to Mary\Mary::hello() and returns 'Hello!'.

```php
use Mary\Facades\Mary;

$greeting = Mary::hello(); // "Hello!" (proxied to Mary\Mary::hello)
```

--------------------------------

### Usage example with activate-by-route and external link

Source: https://github.com/robsontenorio/mary

Shows how to use <x-menu-item> inside <x-menu> with route activation, route parameters, and an external link. The parent <x-menu> uses activate-by-route to enable route-based active styling.

```blade
<x-menu activate-by-route>
    <x-menu-item title="Dashboard" icon="o-home" link="/dashboard" />
    <x-menu-item title="Edit user" route="users.edit" :route-params="['id' => 1]" />
    <x-menu-item title="External" link="https://example.com" external />
</x-menu>
```

--------------------------------

### Constructor

Source: https://github.com/robsontenorio/mary

Creates a new Calendar component instance with configurable options for months, locale, weekend highlighting, week start day, and events.

```APIDOC
## Constructor

### Description
Creates a new Calendar component instance.

### Signature
```php
public function __construct(
    public ?string $id = null,
    public ?int $months = 1,
    public ?string $locale = 'en-EN',
    public ?bool $weekendHighlight = false,
    public ?bool $sundayStart = false,
    public ?array $config = [],
    public ?array $events = [],
)
```

### Parameters
- **id** (?string) - Optional - Element id.
- **months** (?int) - Optional - Number of displayed months (drives `type` default/multiple).
- **locale** (?string) - Optional - Calendar locale.
- **weekendHighlight** (?bool) - Optional - Highlights Saturday/Sunday.
- **sundayStart** (?bool) - Optional - Start the week on Sunday (else Monday).
- **config** (array) - Optional - Overrides merged over the calendar defaults in `setup()`.
- **events** (array) - Optional - Event definitions; each item is `['label' => string, 'description' => string|null, 'css' => string, 'date' => 'Y-m-d' | 'range' => ['Y-m-d','Y-m-d']]`.
```

--------------------------------

### Customized config/mary.php

Source: https://github.com/robsontenorio/mary

Example of a customized maryUI configuration file with a component prefix, route prefix, and spotlight class. This is the file you would edit after publishing.

```php
// config/mary.php
return [
    'prefix' => 'mary-',
    'route_prefix' => 'my-components',
    'components' => [
        'spotlight' => ['class' => App\Support\Spotlight::class],
    ],
];
```

--------------------------------

### Clone the maryUI repository

Source: https://github.com/robsontenorio/mary/blob/main/README.md

Clones the maryUI repository into the packages/mary directory of your project root for local development.

```bash
git clone git@github.com:robsontenorio/mary.git packages/mary
```

--------------------------------

### Usage: <x-input>

Source: https://github.com/robsontenorio/mary

Example of using the Input component in a Blade template with a label, icon, hint, and wire:model binding.

```APIDOC
## Usage: <x-input>

### Description
Example of using the Input component in a Blade template with a label, icon, hint, and wire:model binding.

### Example
```blade
<x-input
    label="Full name"
    icon="o-user"
    hint="As printed on your ID"
    wire:model="name"
/>
```
```

--------------------------------

### Calendar public methods

Source: https://github.com/robsontenorio/mary

Lists the component's public methods: `setup()` returns JSON configuration, `popups()` builds event popups, and `render()` returns the view.

```php
public function setup(): string;
public function popups();
public function render(): View|Closure|string;
```

--------------------------------

### Usage example with disabled and separator

Source: https://github.com/robsontenorio/mary

Shows how to render a menu item with a separator before it and disabled styling. The 'separator' attribute adds a visual divider, and 'disabled' marks the item as non-interactive.

```blade
<x-menu-item title="Archived" icon="o-archive" link="/archive" disabled separator />
```

--------------------------------

### Custom Spotlight search class

Source: https://github.com/robsontenorio/mary

Example implementation of the Spotlight class with a search method that filters a collection based on the search term. Returns a collection of items with name, description, link, and icon.

```php
// app/Support/Spotlight.php
namespace App\Support;

use Illuminate\Http\Request;
use Illuminate\Support\Collection;

class Spotlight
{
    public function search(Request $request): Collection
    {
        $term = $request->search ?? '';

        return collect([[
            'name' => 'Users',
            'description' => 'List all users',
            'link' => '/users',
            'icon' => '<svg>...</svg>',
        ]])->filter(fn ($item) => str_contains(strtolower($item['name']), strtolower($term)));
    }
}
```

--------------------------------

### Calendar constructor signature

Source: https://github.com/robsontenorio/mary

Defines the component's public properties and defaults. The `months` parameter drives the calendar type (default vs multiple), `weekendHighlight` toggles weekend styling, `sundayStart` changes the first weekday, and `config` overrides defaults in `setup()`.

```php
public function __construct(
    public ?string $id = null,
    public ?int $months = 1,
    public ?string $locale = 'en-EN',
    public ?bool $weekendHighlight = false,
    public ?bool $sundayStart = false,
    public ?array $config = [],
    public ?array $events = [],
)
```

--------------------------------

### Calendar with configuration and locale

Source: https://github.com/robsontenorio/mary

Blade usage with `months` set to 3, a custom locale, and a `config` override. This example uses the default Monday start (since `sunday-start` is not set).

```blade
<x-calendar
    :months="3"
    locale="pt-BR"
    :config="['selectionDatesMode' => true]"
/>
```

--------------------------------

### Constructor: __construct

Source: https://github.com/robsontenorio/mary

Creates a new Spotlight component instance. Accepts optional parameters to customize the search modal's behavior, appearance, and keyboard shortcuts.

```APIDOC
## Constructor: __construct

### Description
Creates a new Spotlight component instance. Accepts optional parameters to customize the search modal's behavior, appearance, and keyboard shortcuts.

### Signature
```php
public function __construct(
    public ?string $id = null,
    public ?string $shortcut = "meta.g",
    public ?string $alternativeShortcut = "ctrl.g",
    public ?string $searchText = "Search ...",
    public ?string $noResultsText = "Nothing found.",
    public ?string $url = null,
    public ?string $fallbackAvatar = null,
    public ?bool $noWireNavigate = false,
    // Slots
    public mixed $append = null
)
```

### Parameters
- **id** (?string) - Optional - Element id.
- **shortcut** (?string) - Optional - Primary keyboard shortcut (Alpine `@keydown.window` modifier). Default: `meta.g`.
- **alternativeShortcut** (?string) - Optional - Secondary keyboard shortcut. Default: `ctrl.g`.
- **searchText** (?string) - Optional - Placeholder text in the search input. Default: `Search ...`.
- **noResultsText** (?string) - Optional - Message when there are no results. Default: `Nothing found.`.
- **url** (?string) - Optional - Custom JSON endpoint. When `null`, defaults at construction time to `route('mary.spotlight', absolute: false)`.
- **fallbackAvatar** (?string) - Optional - `onerror` image used when a result avatar fails to load.
- **noWireNavigate** (?bool) - Optional - When `true`, result links are plain anchors (no `wire:navigate`). Default: `false`.
- **append** (mixed) - Optional - Slot appended in the modal header.
```

--------------------------------

### Usage: `<x-password>` Blade Component

Source: https://github.com/robsontenorio/mary

Example usage of the Password component in Blade templates, including a basic example and a right-side toggle with a leading icon.

```blade
<x-password label="Password" wire:model="password" />
```

```blade
<x-password label="PIN" icon="o-lock-closed" right wire:model="pin" />
```

--------------------------------

### Step

Source: https://github.com/robsontenorio/mary

Creates a single step with step number, text, icon, and custom classes.

```APIDOC
## Step

### Description
Creates a single step with step number, text, icon, and custom classes.

### Constructor
```php
public function __construct(
    public int $step,
    public string $text,
    public ?string $id = null,
    public ?string $icon = null,
    public ?string $stepClasses = null,
    public ?string $dataContent = null,
);
```

### Parameters
- **step** (int) - Required - The step number.
- **text** (string) - Required - The step text.
- **id** (?string) - Optional - The step ID.
- **icon** (?string) - Optional - Icon name.
- **stepClasses** (?string) - Optional - CSS classes for the step.
- **dataContent** (?string) - Optional - Data content attribute.
```

--------------------------------

### Route definition for GET /mary/spotlight

Source: https://github.com/robsontenorio/mary

Defines the GET route for the spotlight search endpoint. It uses the configured spotlight class from config('mary.components.spotlight.class') and passes the request to its search method. The route is named 'mary.spotlight' and is wrapped in the 'web' middleware with a configurable prefix.

```php
Route::middleware('web')->prefix(config('mary.route_prefix'))->get('/mary/spotlight', function (Request $request) {
    return app()->make(config('mary.components.spotlight.class'))->search($request);
})->name('mary.spotlight');
```

--------------------------------

### Method: `modelName()`

Source: https://github.com/robsontenorio/mary

Returns the first attribute key starting with `wire:model`.

```APIDOC
## [METHOD] `modelName(): ?string`

### Description
Returns the first attribute key starting with `wire:model`.

### Method
modelName

### Return Value
- **?string** - The first attribute key starting with `wire:model`, or `null` if none found.

```

--------------------------------

### Constructor: __construct

Source: https://github.com/robsontenorio/mary

Creates a new Input component instance with configurable properties for labels, icons, hints, validation, and money mask support.

```APIDOC
## Constructor: __construct

### Description
Creates a new Input component instance with configurable properties for labels, icons, hints, validation, and money mask support.

### Method
Constructor

### Parameters
#### Constructor Parameters
- **id** (?string) - Optional - Element id.
- **label** (?string) - Optional - Input label.
- **icon** (?string) - Optional - Leading Heroicon name.
- **iconRight** (?string) - Optional - Trailing Heroicon name.
- **hint** (?string) - Optional - Hint text.
- **hintClass** (?string) - Optional - Hint CSS class. Default: `fieldset-label`
- **prefix** (?string) - Optional - Text rendered before the input.
- **suffix** (?string) - Optional - Text rendered after the input.
- **inline** (?bool) - Optional - Floating-label layout. Default: `false`
- **clearable** (?bool) - Optional - Show a clear-x button. Default: `false`
- **money** (?bool) - Optional - Enable the money mask. Default: `false`
- **locale** (?string) - Optional - Locale used by the money mask. Default: `'en-US'`
- **popover** (?string) - Optional - Help popover content.
- **popoverIcon** (?string) - Optional - Popover icon. Default: `o-question-mark-circle`
- **popoverTriggerClass** (?string) - Optional - Popover trigger class. Default: `''`
- **popoverContentClass** (?string) - Optional - Popover content class. Default: `''`
- **prepend** (mixed) - Optional - Slot before the control.
- **append** (mixed) - Optional - Slot after the control.
- **errorField** (?string) - Optional - Validation field name.
- **errorClass** (?string) - Optional - Error message class. Default: `text-error`
- **omitError** (?bool) - Optional - Suppress inline error rendering. Default: `false`
- **firstErrorOnly** (?bool) - Optional - Render only the first error line. Default: `false`

### Example
```php
public function __construct(
    public ?string $id = null,
    public ?string $label = null,
    public ?string $icon = null,
    public ?string $iconRight = null,
    public ?string $hint = null,
    public ?string $hintClass = 'fieldset-label',
    public ?string $prefix = null,
    public ?string $suffix = null,
    public ?bool $inline = false,
    public ?bool $clearable = false,
    public ?bool $money = false,
    public ?string $locale = 'en-US',
    // Popover
    public ?string $popover = null,
    public ?string $popoverIcon = "o-question-mark-circle",
    public ?string $popoverTriggerClass = '',
    public ?string $popoverContentClass = '',
    // Slots
    public mixed $prepend = null,
    public mixed $append = null,
    // Validations
    public ?string $errorField = null,
    public ?string $errorClass = 'text-error',
    public ?bool $omitError = false,
    public ?bool $firstErrorOnly = false,
)
```
```

--------------------------------

### Main Component

Source: https://github.com/robsontenorio/mary

App shell with collapsible sidebar slot, content slot, and optional footer. Use as <x-main> with sidebar, content, and footer slots.

```APIDOC
## Main Component

### Description
App shell with collapsible sidebar slot, content slot, and optional footer.

### Constructor Parameters
- **sidebar** (mixed) - Optional - Sidebar slot content
- **content** (mixed) - Optional - Main content slot
- **footer** (mixed) - Optional - Footer slot content
- **fullWidth** (?bool) - Optional - Whether to use full width
- **withNav** (?bool) - Optional - Whether to include navigation
- **collapseText** (?string) - Optional - Text for collapse button (default: 'Collapse')
- **collapseIcon** (?string) - Optional - Icon for collapse button (default: 'o-bars-3-bottom-right')
- **collapsible** (?bool) - Optional - Whether sidebar is collapsible

### Usage
Blade tag: `<x-main>`
```

--------------------------------

### Roll back to stable maryUI version

Source: https://github.com/robsontenorio/mary/blob/main/README.md

Removes the local repository configuration and re-requires the stable maryUI package from Packagist.

```bash
composer config --unset repositories.local
composer require robsontenorio/mary
```

--------------------------------

### Require maryUI for local symlink

Source: https://github.com/robsontenorio/mary/blob/main/README.md

Requires the maryUI package with the @dev stability flag to create a local symlink for development.

```bash
composer require robsontenorio/mary:@dev
```

--------------------------------

### Mary\Facades\Mary::hello()

Source: https://github.com/robsontenorio/mary

Static facade method that proxies to `Mary\Mary::hello()`. It is the only accessible static call on the facade, returning the literal string 'Hello!'.

```APIDOC
## [STATIC] Mary\Facades\Mary::hello()

### Description
Proxies to `Mary\Mary::hello()` and returns the literal string 'Hello!'.

### Method
Static method (facade)

### Endpoint
`Mary\Facades\Mary::hello()`

### Parameters
None

### Response
#### Success Response
- **return** (string) - The literal string 'Hello!'.

### Request Example
```php
use Mary\Facades\Mary;

$greeting = Mary::hello(); // "Hello!" (proxied to Mary\Mary::hello)
```
```

--------------------------------

### GET /mary/spotlight

Source: https://github.com/robsontenorio/mary

This endpoint is part of the package's routes. It is defined in the routes file and is accessible without authentication.

```APIDOC
## [GET] /mary/spotlight

### Description
This endpoint is part of the package's routes. It is defined in the routes file and is accessible without authentication.

### Method
GET

### Endpoint
/mary/spotlight

### Response
#### Success Response (200)
- **body** - Default Laravel response (renders the web root layout). No structured JSON payload is returned.

### Auth
None.
```

--------------------------------

### Mary::hello()

Source: https://github.com/robsontenorio/mary

Static method on the Mary class that returns the literal string 'Hello!'. It is a placeholder method; the real functionality of the package is in the view components.

```APIDOC
## [STATIC] Mary::hello()

### Description
Returns the literal string 'Hello!'.

### Method
Static method

### Endpoint
`Mary\Mary::hello()`

### Parameters
None

### Response
#### Success Response
- **return** (string) - The literal string 'Hello!'.

### Request Example
```php
use Mary\Mary;

$greeting = Mary::hello(); // "Hello!"
```
```

--------------------------------

### MaryBootcampCommand class definition

Source: https://github.com/robsontenorio/mary

Defines the mary:bootcamp console command with its signature, description, and directory separator property. The handle() method and copyFile() helper are declared but not implemented in this snippet.

```php
namespace Mary\Console\Commands;

class MaryBootcampCommand extends Command
{
    protected $signature = 'mary:bootcamp';
    protected $description = 'Prepare the app for the bootcamp';
    protected $ds = DIRECTORY_SEPARATOR;

    public function handle();
    private function copyFile(string $source, string $destination): void;
}
```

--------------------------------

### Constructor

Source: https://github.com/robsontenorio/mary

Creates a new MenuItem component instance with configurable properties for navigation items.

```APIDOC
## Constructor

### Description
Creates a new MenuItem component instance with configurable properties for navigation items.

### Signature
```php
public function __construct(
    public ?string $id = null,
    public ?string $title = null,
    public ?string $icon = null,
    public ?string $iconClasses = null,
    public ?string $spinner = null,
    public ?string $link = null,
    public ?string $route = null,
    public ?array $routeParams = [],
    public ?bool $external = false,
    public ?bool $noWireNavigate = false,
    public ?string $badge = null,
    public ?string $badgeClasses = null,
    public ?bool $active = false,
    public ?bool $separator = false,
    public ?bool $hidden = false,
    public ?bool $disabled = false,
    public ?bool $exact = false
)
```

### Parameters
- `id` (?string) - Optional - Element id.
- `title` (?string) - Optional - Item label.
- `icon` (?string) - Optional - Heroicon name.
- `iconClasses` (?string) - Optional - Extra classes for the icon.
- `spinner` (?string) - Optional - Spinner target; `1` means "use the `wire:click` attribute target".
- `link` (?string) - Optional - URL href.
- `route` (?string) - Optional - Named route used when `getHref()` builds `route($route, $routeParams)`.
- `routeParams` (array) - Optional - Params passed to `route()`.
- `external` (?bool) - Optional - Render as an external anchor (no `wire:navigate`).
- `noWireNavigate` (?bool) - Optional - Suppress `wire:navigate`.
- `badge` (?string) - Optional - Badge text value.
- `badgeClasses` (?string) - Optional - Badge class.
- `active` (?bool) - Optional - Force active styling.
- `separator` (?bool) - Optional - Adds a separator before the item.
- `hidden` (?bool) - Optional - When `true`, `render()` returns an empty string.
- `disabled` (?bool) - Optional - Marks the item as disabled.
- `exact` (?bool) - Optional - Active matching only on exact URL equality (see `routeMatches()`).
```

--------------------------------

### modelName() helper method

Source: https://github.com/robsontenorio/mary

Returns the first attribute key that starts with 'wire:model'. Used by many input components.

```php
public function modelName(): ?string
{
    return $this->attributes->whereStartsWith('wire:model')->first();
}
```

--------------------------------

### Usage: Money input with error handling

Source: https://github.com/robsontenorio/mary

Example of using the Input component with money mask, locale, and error field for validation.

```APIDOC
## Usage: Money input with error handling

### Description
Example of using the Input component with money mask, locale, and error field for validation.

### Example
```blade
<x-input
    label="Amount"
    money
    locale="pt-BR"
    error-field="price"
    wire:model="price"
/>
{{-- validation errors render automatically; omit with :omit-error="true" --}}
```
```

--------------------------------

### Constructor: __construct

Source: https://github.com/robsontenorio/mary

Creates a new Tags component instance. Accepts optional parameters for id, label, hint, icons, validation, and popover configuration.

```APIDOC
## Constructor: __construct

### Description
Creates a new Tags component instance. Accepts optional parameters for id, label, hint, icons, validation, and popover configuration.

### Method
Constructor

### Signature
```php
public function __construct(
    public ?string $id = null,
    public ?string $label = null,
    public ?string $hint = null,
    public ?string $hintClass = 'fieldset-label',
    public ?string $icon = null,
    public ?string $iconRight = null,
    public ?bool $inline = false,
    public ?bool $clearable = false,
    public ?string $prefix = null,
    public ?string $suffix = null,
    // Popover
    public ?string $popover = null,
    public ?string $popoverIcon = "o-question-mark-circle",
    public ?string $popoverTriggerClass = '',
    public ?string $popoverContentClass = '',
    // Slots
    public mixed $prepend = null,
    public mixed $append = null,
    // Validations
    public ?string $errorField = null,
    public ?string $errorClass = 'text-error',
    public ?bool $omitError = false,
    public ?bool $firstErrorOnly = false,
)
```

### Parameters
- **id** (?string) - Optional - Element id.
- **label** (?string) - Optional - Label.
- **hint** (?string) - Optional - Hint text.
- **hintClass** (?string) - Optional - Hint class. Default: `fieldset-label`.
- **icon** (?string) - Optional - Leading icon.
- **iconRight** (?string) - Optional - Trailing icon.
- **inline** (?bool) - Optional - Floating label. Default: `false`.
- **clearable** (?bool) - Optional - "Clear all" control. Default: `false`.
- **prefix** (?string) - Optional - Text before the control.
- **suffix** (?string) - Optional - Text after the control.
- **popover** (?string) - Optional - Help popover content.
- **popoverIcon** (?string) - Optional - Popover icon. Default: `o-question-mark-circle`.
- **popoverTriggerClass** (?string) - Optional - Popover trigger class. Default: `''`.
- **popoverContentClass** (?string) - Optional - Popover content class. Default: `''`.
- **prepend** (mixed) - Optional - Slot.
- **append** (mixed) - Optional - Slot.
- **errorField** (?string) - Optional - Validation field.
- **errorClass** (?string) - Optional - Error class. Default: `text-error`.
- **omitError** (?bool) - Optional - Suppress inline errors. Default: `false`.
- **firstErrorOnly** (?bool) - Optional - Only first error line. Default: `false`.
```

--------------------------------

### Spotlight configuration in config/mary.php

Source: https://github.com/robsontenorio/mary

Configuration snippet showing how to set the spotlight class in the Mary configuration file. The 'class' key must point to a class that implements the search method.

```php
// config/mary.php
'components' => [
    'spotlight' => ['class' => 'App\Support\Spotlight'],
],
```

--------------------------------

### modelName(): ?string

Source: https://github.com/robsontenorio/mary

Returns the first attribute key that starts with 'wire:model'. This method is part of the shared input-component helper contract.

```APIDOC
## modelName(): ?string

### Description
Returns the first attribute key that starts with `wire:model`.

### Method
modelName

### Return Type
`?string`

### Example
```php
public function modelName(): ?string
{
    return $this->attributes->whereStartsWith('wire:model')->first();
}
```
```

--------------------------------

### render(): View|Closure|string

Source: https://github.com/robsontenorio/mary

Renders the calendar component as a div with an Alpine init that instantiates the VanillaCalendarPro calendar.

```APIDOC
## render(): View|Closure|string

### Description
Returns a `<div wire:key="calendar-<rand>">` with an Alpine init that instantiates `window.VanillaCalendarPro.Calendar($el, <setup()>)` and calls `calendar.init()`.
```

--------------------------------

### modelName(): ?string

Source: https://github.com/robsontenorio/mary

Returns the first attribute key starting with `wire:model`. This is used to determine the model name for the input component.

```APIDOC
## modelName(): ?string

### Description
Returns the first attribute key starting with `wire:model`.

### Method
modelName

### Return Value
- **?string** - The first attribute key starting with `wire:model`.

### Example
```php
public function modelName(): ?string;
```
```

--------------------------------

### Steps

Source: https://github.com/robsontenorio/mary

Creates a steps container with vertical orientation, color, and custom stepper classes.

```APIDOC
## Steps

### Description
Creates a steps container with vertical orientation, color, and custom stepper classes.

### Constructor
```php
public function __construct(
    public ?string $id = null,
    public bool $vertical = false,
    public ?string $stepsColor = 'step-neutral',
    public ?string $stepperClasses = null,
);
```

### Parameters
- **id** (?string) - Optional - The steps ID.
- **vertical** (bool) - Optional - Whether to display vertically.
- **stepsColor** (?string) - Optional - Color class for steps.
- **stepperClasses** (?string) - Optional - Additional CSS classes for the stepper.
```

--------------------------------

### Constructor

Source: https://github.com/robsontenorio/mary

Creates a new Colorpicker component instance with configurable properties for label, icons, hints, validation, and popover.

```APIDOC
## Constructor

### Description
Creates a new Colorpicker component instance with configurable properties for label, icons, hints, validation, and popover.

### Signature
```php
public function __construct(
    public ?string $id = null,
    public ?string $label = null,
    public ?string $icon = '',
    public ?string $iconRight = null,
    public ?string $hint = null,
    public ?string $hintClass = 'fieldset-label',
    public ?string $prefix = null,
    public ?string $suffix = null,
    public ?bool $inline = false,
    public ?bool $clearable = false,
    // Popover
    public ?string $popover = null,
    public ?string $popoverIcon = "o-question-mark-circle",
    public ?string $popoverTriggerClass = '',
    public ?string $popoverContentClass = '',
    // Validations
    public ?string $errorField = null,
    public ?string $errorClass = 'text-error',
    public ?bool $omitError = false,
    public ?bool $firstErrorOnly = false,
)
```

### Parameters
- `id` (?string) - Optional - Element id.
- `label` (?string) - Optional - Label.
- `icon` (?string) - Optional - Leading icon (defaults to empty string here, unlike most siblings).
- `iconRight` (?string) - Optional - Trailing icon.
- `hint` (?string) - Optional - Hint text.
- `hintClass` (?string) - Optional - Hint class.
- `prefix` (?string) - Optional - Text before the control.
- `suffix` (?string) - Optional - Text after the control.
- `inline` (?bool) - Optional - Floating label.
- `clearable` (?bool) - Optional - Clear button.
- `popover` (?string) - Optional - Help popover content.
- `popoverIcon` (?string) - Optional - Popover icon.
- `popoverTriggerClass` (?string) - Optional - Popover trigger class.
- `popoverContentClass` (?string) - Optional - Popover content class.
- `errorField` (?string) - Optional - Validation field.
- `errorClass` (?string) - Optional - Error class.
- `omitError` (?bool) - Optional - Suppress inline errors.
- `firstErrorOnly` (?bool) - Optional - Only first error line.
```

--------------------------------

### GET /mary/toogle-sidebar

Source: https://github.com/robsontenorio/mary

Registers the sidebar collapsed state in the session. This endpoint is used to persist the sidebar collapse state across requests.

```APIDOC
## [GET] /mary/toogle-sidebar

### Description
Registers the sidebar collapsed state in the session. This endpoint is used to persist the sidebar collapse state across requests.

### Method
GET

### Endpoint
/mary/toogle-sidebar

### Parameters
#### Query Parameters
- **collapsed** (mixed) - Optional - Truthy value stored as the collapsed flag. When falsy/absent, nothing is written.

### Response
#### Success Response (200)
- **body** - Default Laravel response (renders the web root layout). No structured JSON payload is returned.

### Auth
None.
```

--------------------------------

### Form

Source: https://github.com/robsontenorio/mary

Creates a form wrapper with optional actions and separator control.

```APIDOC
## Form

### Description
Creates a form wrapper with optional actions and separator control.

### Constructor
```php
public function __construct(public mixed $actions = null, public ?bool $noSeparator = false);
```

### Parameters
- **actions** (mixed) - Optional - Actions slot content.
- **noSeparator** (?bool) - Optional - Whether to disable separator.
```

--------------------------------

### Add local repository to composer config

Source: https://github.com/robsontenorio/mary/blob/main/README.md

Adds the local maryUI package path to Composer's repositories configuration so it can be used as a path repository.

```bash
composer config repositories.local '{"type": "path", "url": "packages/mary"}'
```

--------------------------------

### render(): View|Closure|string

Source: https://github.com/robsontenorio/mary

Renders the component's Blade template. This is the single public method that returns the view or closure for the component.

```APIDOC
## render(): View|Closure|string

### Description
Renders the component's Blade template. This is the single public method that returns the view or closure for the component.

### Method
render

### Signature
```php
public function render(): View|Closure|string;
```

### Returns
- **View|Closure|string** - The rendered view or closure.
```

--------------------------------

### Select Constructor

Source: https://github.com/robsontenorio/mary

Constructor for the Select component. Accepts various parameters for configuration including options, placeholders, and validation.

```APIDOC
## Select Constructor

### Description
Constructor for the Select component. Accepts various parameters for configuration including options, placeholders, and validation.

### Method
Constructor

### Signature
```php
public function __construct(
    public ?string $id = null,
    public ?string $label = null,
    public ?string $icon = null,
    public ?string $iconRight = null,
    public ?string $hint = null,
    public ?string $hintClass = 'fieldset-label',
    public ?string $prefix = null,
    public ?string $suffix = null,
    public ?string $placeholder = null,
    public ?string $placeholderValue = null,
    public ?bool $inline = false,
    public ?string $optionValue = 'id',
    public ?string $optionLabel = 'name',
    public Collection|array $options = new Collection(),
    // Popover
    public ?string $popover = null,
    public ?string $popoverIcon = "o-question-mark-circle",
    public ?string $popoverTriggerClass = '',
    public ?string $popoverContentClass = '',
    // Slots
    public mixed $prepend = null,
    public mixed $append = null,
    // Validations
    public ?string $errorField = null,
    public ?string $errorClass = 'text-error',
    public ?bool $omitError = false,
    public ?bool $firstErrorOnly = false,
)
```

### Parameters
- **id** (?string) - Optional - Component ID.
- **label** (?string) - Optional - Label text.
- **icon** (?string) - Optional - Icon name.
- **iconRight** (?string) - Optional - Right icon name.
- **hint** (?string) - Optional - Hint text.
- **hintClass** (?string) - Optional - CSS class for hint.
- **prefix** (?string) - Optional - Prefix text.
- **suffix** (?string) - Optional - Suffix text.
- **placeholder** (?string) - Optional - Placeholder option text.
- **placeholderValue** (?string) - Optional - Placeholder option value.
- **inline** (?bool) - Optional - Whether to display inline.
- **optionValue** (?string) - Optional - Field used as option value.
- **optionLabel** (?string) - Optional - Field used as option label.
- **options** (Collection|array) - Optional - Options to render.
- **popover** (?string) - Optional - Popover content.
- **popoverIcon** (?string) - Optional - Popover icon.
- **popoverTriggerClass** (?string) - Optional - CSS class for popover trigger.
- **popoverContentClass** (?string) - Optional - CSS class for popover content.
- **prepend** (mixed) - Optional - Prepend slot content.
- **append** (mixed) - Optional - Append slot content.
- **errorField** (?string) - Optional - Error field name.
- **errorClass** (?string) - Optional - CSS class for error.
- **omitError** (?bool) - Optional - Whether to omit error display.
- **firstErrorOnly** (?bool) - Optional - Whether to show only first error.
```

--------------------------------

### Modal with trap-focus disabled and persistent option

Source: https://github.com/robsontenorio/mary

Use this Blade component to create a modal dialog with the persistent option, which disables trap-focus. The example includes action buttons in the actions slot.

```blade
<x-modal id="confirm" title="Are you sure?" persistent>
    Content...
    <x-slot:actions>
        <x-button label="Cancel" @click="close" />
        <x-button label="Continue" class="btn-primary" />
    </x-slot:actions>
</x-modal>
```

--------------------------------

### render(): View|Closure|string

Source: https://github.com/robsontenorio/mary

Renders the menu item HTML, returning an empty string when hidden is true.

```APIDOC
## render(): View|Closure|string

### Description
Returns `''` when `hidden === true`. Otherwise renders the `<li>`/`<a>` item; it reads the `horizontal`, `activateByRoute`, and `activeBgColor` states via `@aware(...)` from the parent `<x-menu>`. Active styling is applied when `$active` is truthy or (when `activateByRoute`) `routeMatches()` is true.

### Method
render

### Returns
- View|Closure|string - The rendered HTML or an empty string when hidden.
```

--------------------------------

### Catch RuntimeException from mary:bootcamp command

Source: https://github.com/robsontenorio/mary

Catches the \RuntimeException thrown by the private file-copy helper when copy() fails during php artisan mary:bootcamp. The exception message is "Failed to copy {source} to {destination}".

```php
try {
    $this->artisan('mary:bootcamp');
} catch (\RuntimeException $e) {
    // file copy failure
}
```
Tokens:
Raw