Keep existing table descriptions — render quick links via header render hook

.github/workflows/run-tests.yml

@@ -0,0 +1,40 @@
+name: "Run Tests"
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.2', '8.3', '8.4']
+        filament: ['3', '4', '5']
+
+    name: PHP ${{ matrix.php }} - Filament ${{ matrix.filament }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: intl, dom, curl, libxml, mbstring, zip
+          coverage: none
+
+      - name: Install dependencies
+        run: |
+          composer require "filament/tables:^${{ matrix.filament }}.0" --no-interaction --no-update
+          composer update --prefer-dist --no-interaction --no-progress
+
+      - name: Run tests
+        run: vendor/bin/pest

CHANGELOG.md

@@ -29,7 +29,3 @@ All notable changes to `quick-links` will be documented in this file.
 ## v1.0.0 - 2025-02-18
 
 Initial release
-
-## 1.0.0 - 202X-XX-XX
-
-- initial release

README.md

@@ -5,8 +5,10 @@
 
 Quickly open resource, models, and other files from within your FilamentPHP table in your PHPstorm editor.
 
-> [!IMPORTANT]
-> This package uses your table's `description` field (see [docs](https://filamentphp.com/docs/3.x/tables/advanced#customizing-the-table-header)), so if there's a description already the quick links won't appear.
+> [!NOTE]
+> The links are rendered through Filament's `tables::header.after` render hook, underneath the table header, so a table that already sets its own `description` keeps it.
+>
+> That spot lives inside the table's header container, which Filament hides when a table has nothing to put in it. A table with no heading, no description, no header actions, no search, no filters and no column manager therefore won't show the links.
 
 ## Installation
 
@@ -78,6 +80,16 @@ return [
 ];
 ```
 
+## Styling
+
+The links are rendered from a Blade view. Publish it if you want to change the markup:
+
+```bash
+php artisan vendor:publish --tag=quick-links-views
+```
+
+It lands in `resources/views/vendor/quick-links/quick-links.blade.php` and receives `$links` (each with a `url` and a `label`), `$prefix` and `$separator`.
+
 ## Conditional disabling
 
 While you can disablee the package entirely by setting the `QUICK_LINKS_ENABLED` environment variable to `false` you can also use a closure to conditionally disable it.
@@ -106,10 +118,20 @@ QuickLinks::disableOn(App\Filament\Resources\OrderResource::class);
 
 Simply add the FQCN(s) (fully qualified class name) to your resource in the `quick-links.disabled` config option.
 
+## Testing
+
+```bash
+composer test
+```
+
+The suite runs against Filament v3, v4 and v5.
+
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
 
+Upgrading from v1? See [UPGRADING](UPGRADING.md).
+
 ## Contributing
 
 Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

UPGRADING.md

@@ -0,0 +1,53 @@
+# Upgrading
+
+## From v1.x to v2.0
+
+### Requirements
+
+- PHP 8.2 or higher (was 8.1).
+- `filament/tables` `^3.0|^4.0|^5.0` is now a declared dependency. The package
+  always needed it, but never asked for it, so Composer may now pull it in or
+  refuse to resolve where it previously stayed quiet.
+
+### `disableIf()` behaves as documented
+
+It used to call the closure immediately and store the result, then apply that
+result the wrong way round. Following the README:
+
+```php
+QuickLinks::disableIf(fn () => auth()->id() === 1);
+```
+
+ran while the service provider booted, when `auth()->id()` is still `null`, and
+disabled the package for everybody. The closure is now stored and evaluated on
+every render, and a closure returning `true` disables the links.
+
+If you inverted your closure to work around the old behaviour, remove the
+inversion.
+
+### Links no longer use the table description
+
+They render through Filament's `tables::header.after` render hook, so a table
+that sets its own `description()` keeps it.
+
+One consequence: that hook sits inside the table's header container, which
+Filament hides when a table has nothing else to show there. A table with no
+heading, no description, no header actions, no search, no filters and no column
+manager will not display the links.
+
+### Return types
+
+`build()` returns a `View` (typed `?Htmlable`) rather than `?HtmlString`, and
+`buildResourceLinks()` and `buildFileLinks()` return arrays shaped
+`['url' => ..., 'label' => ...]` instead of HTML strings.
+
+If you called these directly, render the view or read the array keys instead of
+concatenating the old strings.
+
+### Customising the markup
+
+The markup now lives in a Blade view rather than being built in PHP:
+
+```bash
+php artisan vendor:publish --tag=quick-links-views
+```

composer.json

@@ -24,22 +24,36 @@
         }
     ],
     "require": {
-        "php": "^8.1",
+        "php": "^8.2",
+        "filament/tables": "^3.0|^4.0|^5.0",
+        "livewire/livewire": "^3.5|^4.0",
         "spatie/laravel-package-tools": "^1.15.0"
     },
     "require-dev": {
-        "laravel/pint": "^1.0"
+        "laravel/pint": "^1.25",
+        "orchestra/testbench": "^9.0|^10.0|^11.0",
+        "pestphp/pest": "^3.0|^4.0",
+        "pestphp/pest-plugin-laravel": "^3.0|^4.0"
     },
     "autoload": {
         "psr-4": {
             "Niladam\\QuickLinks\\": "src/"
         }
     },
+    "autoload-dev": {
+        "psr-4": {
+            "Niladam\\QuickLinks\\Tests\\": "tests/"
+        }
+    },
     "scripts": {
-        "format": "vendor/bin/pint"
+        "format": "vendor/bin/pint",
+        "test": "vendor/bin/pest"
     },
     "config": {
-        "sort-packages": true
+        "sort-packages": true,
+        "allow-plugins": {
+            "pestphp/pest-plugin": true
+        }
     },
     "extra": {
         "laravel": {

phpunit.xml.dist

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="./vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+>
+    <testsuites>
+        <testsuite name="Quick Links Test Suite">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>

resources/views/quick-links.blade.php

@@ -0,0 +1,22 @@
+{{--
+    Rendered into TablesRenderHook::HEADER_AFTER, underneath the table's own
+    header, so a table that already defines a description keeps it.
+
+    The `fi-*` classes are Filament's own. From v4 they carry the styling by
+    themselves, while v3 styled the markup with the utility classes sitting
+    alongside them, so both are present to cover every supported major.
+--}}
+<div class="fi-ql fi-ta-header flex flex-col gap-3 p-4 sm:px-6">
+    <p class="fi-ql-links fi-ta-header-description text-sm text-gray-600 dark:text-gray-400">
+        @if (filled($prefix))
+            <span class="fi-ql-prefix">{{ $prefix }}</span>
+        @endif
+
+        @foreach ($links as $link)
+            @if (! $loop->first){!! $separator !!}@endif<a
+                class="fi-ql-link"
+                href="{{ $link['url'] }}"
+            ><strong>{{ $link['label'] }}</strong></a>
+        @endforeach
+    </p>
+</div>