Download the PHP package bensondevs/fiddy without Composer

Fiddy

Filament Interactive and Descriptive Display — rich Image, Title, and Description components for Filament 5.

Fiddy layers presentation (avatar, title, description, hint, icons) on top of familiar Filament forms, infolists, tables, and filters — with one shared Content / Option model and a single presenter for everything.

Table of contents

• Installation
• Forms
  • Select
  • Numeric input
• Infolists
  • Entry
  • Image entry
  • Timestamp entry
• Tables
  • Column
  • Timestamp column
• Filters
  • Select filter
• Presentation
  • On the model
  • No presenter, no contract
  • Separate presenter
  • Resolution order
• License

Installation

Requires Filament ^5 and PHP ^8.2.

The service provider and assets register automatically.

If the app uses Laravel Boost, run php artisan boost:install (or boost:update) after requiring Fiddy. Boost discovers this package’s AI guidelines and the fiddy-development skill automatically — no extra registration.

Forms

Select

FiddySelect renders rich HTML options: image, title, description, hint, and icons — from parallel arrays, associative payloads, relationships, presenters, or FiddyComponentsPresentable. Agents using Laravel Boost should load the fiddy-development skill for the full Option / Content API.

Without a presenter or presentable model, Fiddy guesses name|title, email|description, phone|hint, and Spatie Media Library default collection when available.

Presentation methods

Same priority as Presentation:

presentOptionUsing closure arguments

Fiddy injects the related / option model being presented:

The closure must return an Option instance.

Static option helpers

Keyed like options(); each accepts array|Arrayable|Closure|null:

• Text: descriptions(), hints()
• Media: images() / prefixImages(), suffixImages(), circularImages(bool|Closure)
• Icons: icons() / prefixIcons(), suffixIcons(); titleIcons() / titlePrefixIcons() / titleSuffixIcons(); same for description* and hint*

Option fluent API

Build dropdown rows with Option::make($value) inside closures, toOption(), or asOption(). Icons accept string | BackedEnum | Htmlable | null.

Option has no aboveTitle / aboveDescription (those exist only on Content).

Numeric input

FiddyNumericInput masks thousand separators in the UI while keeping a clean numeric state. Use money() for currency-aware prefixes and separators, and spellAmount() for live spelled helper text.

Repeater

FiddyRepeater extends Filament’s repeater with rich item headers via Fiddy Content: label, description, prefix/suffix icons, and icon color. Closures receive the same injections as Filament’s itemLabel ($state, $key, $index, …). Nested fields used in $state should be live() so headers update as you type.

Infolists

Entry

FiddyEntry shows a related BelongsTo / HasOne record as rich Content — same stack as FiddyColumn (presentUsing, presentContentUsing, presentable asEntryContent(), or attribute guessing). Closure injections and the full Content fluent API match the column docs below.

Image entry

FiddyImageEntry extends Filament’s image entry with click-to-preview (on by default) and soft rounded() corners alongside Filament’s circular(). Images are capped with max-width / max-height (default 8rem) instead of a fixed height; use Filament’s imageWidth() / imageHeight() / imageSize() for explicit sizes, and Fiddy’s maxImageWidth() / maxImageHeight() to change the cap.

Timestamp entry

FiddyTimestampEntry mirrors the FiddyTimestampColumn API (same trait methods, positions, and closure arguments).

Tables

Column

FiddyColumn extends Filament’s TextColumn and renders a related BelongsTo / HasOne model as rich HTML via Content. When no related model is found, the cell shows the placeholder -.

Related record resolution

The column state is the related model, not a scalar attribute. Resolution order:

1. relatedRecord(Model|Closure|null) — explicit override. A Closure is evaluated with Filament’s usual column injections (including the table row as record) and must return a Model (or null).
2. Otherwise, if the column name is a BelongsTo / HasOne relation on the row model, that relation’s result is used (FiddyColumn::make('author') → $row->author).
3. Otherwise, data_get($row, $name) is used (supports dotted paths like author.manager when the value is a Model).

Presentation methods

Same resolution priority as Presentation:

presentContentUsing closure arguments

Fiddy injects the related model (not the table row) into the closure:

Also available via Filament’s normal column evaluation (Livewire component, column instance, etc.).

The closure must return a Content instance (or anything else is treated as empty / placeholder).

Display helpers

BelongsTo / HasOne relations named like the column are eager-loaded automatically when the table query runs.

Note: searchable / sortable use those fixed fallback attribute lists on the related table. Passing $attribute into Content::title(..., $attribute) / description(...) records metadata on the Content object for its own helpers; it does not currently change which columns FiddyColumn::searchable() / sortable() query.

Content fluent API

Build cells with Content::make() inside closures, presenters (toContent()), or asColumnContent() / asEntryContent(). Icons accept string | BackedEnum | Htmlable | null (e.g. Heroicon enums or SVG HTML).

Text

Media

Icons (prefix / suffix pairs; short aliases set the prefix)

Content also provides ::guess(Model), ::fromEnum(UnitEnum), and ::resolveImageUrl(Model) (avatar_url, then Spatie Media Library default collection).

Timestamp column

FiddyTimestampColumn formats a datetime attribute as HTML Content: title is the translated datetime (M j, Y g:i A in the column timezone). Optional subject and relative-diff lines attach above or below that title. The same API is shared with FiddyTimestampEntry via FormatsTimestampContent.

Subject and relative difference

Position layout when both subject and diff are enabled:

• Both bottom: subject → description line; diff → hint line
• Both top / above: subject → above-title; diff → above-description
• Mixed positions follow the same slotting (first top line, second top line, first bottom line, second bottom line)

Icon helpers on the timestamp

Icon types: string | BackedEnum | Htmlable | null.

Filters

Select filter

FiddySelectFilter reuses the same rich option presentation as FiddySelect (presentUsing, presentOptionUsing, static helpers, enum, presentable asOption()). Dropdown wiring is forwarded to a nested FiddySelect.

Active chips are separate: presentable models use asFilterIndicator() → Indicator; otherwise the relationship title attribute (or enum label/icon via Indicator::fromEnum). Presenters do not affect chips.

Indicator fluent API

Presentation

Select, Column, Entry, and filter chips all render from the same Option / Content DTOs. You can fill those three ways: put presentation on the model (or enum), let Fiddy guess conventional attributes, or wire a separate Presenter class.

On the model

Implement FiddyComponentsPresentable. No presentUsing() is needed — Fiddy detects the interface automatically.

Wire components with a relationship (or attribute) only:

Enums can implement the same contract for custom option / content / chip markup.

No presenter, no contract

If the related model has conventional attributes, Fiddy guesses without a presenter or presentable interface:

• Title: name or title
• Description: email or description
• Hint: phone or hint
• Image: avatar_url, or Spatie Media Library default collection when available

Enums without FiddyComponentsPresentable still work via Filament HasLabel / HasIcon / HasDescription and ->enum(Status::class).

Separate presenter

Prefer a presenter when presentation should stay off the Eloquent model, or when one class should drive Select, Column, Entry, and filter surfaces together.

Declare the presenter on the model with HasFiddyPresenter — no hand-written asOption / asColumnContent / asEntryContent / asFilterIndicator, and no presentUsing() on each component:

HasFiddyPresenter builds filter chips from the presenter’s toOption() title (and prefix icon when set). Override asFilterIndicator() on the model if chips need different markup.

Or wire the presenter per component with presentUsing() (highest priority after inline closures):

Notes:

• The presenter constructor takes a Model. Enums use FiddyComponentsPresentable or Filament contracts instead of presentUsing / HasFiddyPresenter.
• Component-level presentUsing(...) alone does not affect filter chips. Chips use asFilterIndicator() (including the trait default) on presentable models, otherwise the relationship title attribute.
• presentUsing(...) on a component wins over a model that also implements FiddyComponentsPresentable.

You can also pass an inline closure with presentOptionUsing(...) / presentContentUsing(...) when you only need one surface.

Resolution order

Highest priority first:

1. Inline closure (presentOptionUsing / presentContentUsing)
2. ->presentUsing(SomePresenter::class) → toOption() / toContent()
3. Model or enum implements FiddyComponentsPresentable
4. Attribute / enum-contract guessing

License

MIT