A11y Docs: PDF and Document Accessibility for Statamic

Fixed, where the refusal was in the wrong place

A refused publish is now drawn in the gate's panel, not under the title. Statamic renders a validation error next to the blueprint field it is keyed to and drops it silently otherwise, so the refusal had to name a field, and "this entry links to 1 document that people using a screen reader cannot read" then appeared under the Title input and read as a fault in the title. Reported from a live site.

A11y Gate 0.9 lets a panel block name a refusalKey and draws whatever it finds under it, so the refusal now appears in the block that already lists the documents on that page. It falls back to keying a field in two cases, because a refusal nobody sees is worse than one in the wrong place: an A11y Gate older than 0.9, asked through PanelExtensions::supports(), and a blueprint without the panel field on it.

Needs A11y Gate 0.9 or newer for the new placement. Nothing else changes, and the gate is optional as before. Upgrading re-checks nothing.

Added, because the documentation promised it

Withdraw accessibility exemption, on an asset, one or many. The documentation described withdrawal from the first release and there was no way to do it: the column existed, active() filtered on it, and nothing in the control panel ever set it. An exemption was permanent once granted.

The row is not deleted. It records who ended it and when, and an already-withdrawn exemption is left alone rather than re-stamped, so the time in the record is the time somebody decided. The action appears only where there is an active exemption to withdraw.

Fixed, where an upgrade did not arrive

docs:install now applies migrations added after the tables were created. It returned early on "the tables exist", so a column added in a later release never reached a site that installed an earlier one. Run it after upgrading; it reports "already installed" when there is nothing to do.

Upgrading re-checks nothing.

Added

Linked documents are reported inside A11y Gate's entry panel. The gate reads a page's rendered HTML and cannot open a linked PDF, so an entry linking to an untagged document read as passing there while this addon refused the same save. Two addons giving an author opposite answers on one screen is worse than either being absent.

The block lists the documents an entry links to, names what is wrong in the same words the dashboard and the queue use, and links to the remediation queue. Its tone is error only when a finding is critical, so its colour means what the gate's does. It says so when the documents have never been checked, because silence there reads as "checked, and fine".

Registered only when A11y Gate is installed. Upgrading re-checks nothing.

Fixed, where the addon was saying something untrue

docs:report --pdf explains why a snap-confined browser produces no file. Ubuntu ships Chromium as a snap, which is what Laravel Forge installs, and a snap gets a private /tmp and cannot write outside the user's home directory. It exits cleanly and reports the bytes it wrote, to a path nothing else can see, so the export failed with an error that read as though the browser had crashed.

Measured on a Forge server: --pdf=/tmp/report.pdf produced no file, and the same run with a destination inside the site produced a valid 17728-byte tagged PDF.

The error now says the browser exited cleanly but wrote nothing to that path, and where the binary looks snap-confined and the destination is outside the home directory it names one that works. Write to storage/report.pdf rather than /tmp.

Upgrading re-checks nothing.

Fixed

docs:report --pdf no longer reports failure while the file is being written. The check clears PHP's stat cache and retries for up to a second before giving up, and includes the process exit code so a real failure is still diagnosable.

This did not find the cause. 1.1.4 did.

Upgrading re-checks nothing.

Fixed, where the documentation could not be followed

The Document accessibility fieldtype is selectable. It shipped hidden from the field picker, so the install the documentation describes could not be completed: it says to add a field of type "Document accessibility" to the asset blueprint, and that option was not there. The status column could only be turned on by editing YAML by hand.

The fieldtype now carries a title, an icon and a category. It stays out of a form's field picker, where it has no meaning.

Found by installing on a real site and following the instructions as written. Upgrading re-checks nothing.

Fixed, and it took the control panel down

A 500 on the control panel login page. Forge and similar deploys cache routes. A cache built before this addon was installed contains none of its control panel routes, and the navigation item is registered on every control panel request including login, so it asked for a route that was not there:

production.ERROR: Route [statamic.cp.a11y-docs.dashboard] not defined.

The whole control panel returned 500, and removing the addon did not clear it because the route cache still had to be rebuilt.

The nav item is now skipped when its route is missing. A missing menu entry is visible and harmless; a 500 on login is neither. If you hit this, run php artisan optimize:clear after installing.

Upgrading re-checks nothing.

Changed, and the install steps are different

Results go in the addon's own SQLite file by default, so a flat-file Statamic site needs no database. Most Statamic sites are flat-file, and requiring one before somebody can try an addon is a reason not to try it.

Install is now:

composer require bpmore/statamic-a11y-docs
php please docs:install
php please vendor:publish --tag=a11y-docs
php please docs:check

docs:install replaces php please migrate. It creates the three tables on the configured connection and provisions job_batches, which Laravel needs for a batched scan and does not create itself.

To keep the tables in a database the site already runs, set A11Y_DOCS_CONNECTION to one of its connection names, or set connection in the config, and run the command again. The command asks before creating tables on a connection the site administers.

Upgrading re-checks nothing, but results already stored in a site's own database stay there. Point connection at it to keep reading them.

Fixed, in the package rather than the code

The 1.0.4 tag on the public repository was cut at its first commit, before the licence and package metadata existed, so Packagist was serving a release with no LICENSE.md, no homepage or support keys, and a wcag keyword the rest of the project contradicts. This release carries all of it.

No code changed. Upgrading re-checks nothing.

Fixed, both found by looking at the screen

Every badge in the addon rendered grey, including "No problems found" and "2 problems · critical". Badge's prop is color; the addon passed variant, which is Button's, and Badge sets inheritAttrs: false, so it was discarded with no error.

The publish gate blocked silently. Clicking Save & Publish on an entry linking to a failing document did nothing visible: no message, no toast, no console error. The gate worked, and Statamic only renders a validation error next to the blueprint field it is keyed to. The message was keyed to published, a sidebar toggle. It is now keyed to a field the control panel will show.

Upgrading re-checks nothing.