Getting Started

First Steps

Installation Add the package via Composer in a Laravel project (if adapted for Laravel, assuming compatibility via Contao integration):
```
composer require contao-thememanager/ctm-accessibility
```
Note: Since this is a Contao package, ensure your Laravel project uses Contao Manager or a bridge like Laravel-Contao for integration.
Configuration Publish the package’s config (if available) and update config/ctm-a11y.php:
```
php artisan vendor:publish --provider="ContaoThememanager\A11y\A11yServiceProvider"
```
Key settings to review:
- enabled_features (e.g., ['skip-links', 'focus-styles', 'aria-labels'])
- default_contrast_mode (e.g., 'high' or 'low').
First Use Case: Enable Skip Links Add the skip-link template to your Contao theme’s layout.html5 (or Laravel Blade equivalent):
```
{{ ContaoThememanager\A11y\A11y::skipLink() }}
```
This renders a hidden anchor (<a href="#main">Skip to content</a>) for keyboard users.

Implementation Patterns

Core Workflows

Dynamic ARIA Attributes Use the package to inject ARIA attributes conditionally in Contao templates or Laravel Blade:

// In a Contao template (e.g., article.html5)
<button {{ ContaoThememanager\A11y\A11y::aria({ expanded: true }) }}>
  Toggle Menu
</button>

Laravel Blade equivalent (if using a bridge):

<button {{ \ContaoThememanager\A11y\Facades\A11y::aria(['expanded' => true]) }}>
  Toggle Menu
</button>

Contrast Mode Toggle Implement a user-preference system for contrast modes (e.g., via Contao’s tl_user or Laravel sessions):

// Set contrast mode (e.g., in a Contao frontend module)
ContaoThememanager\A11y\A11y::setContrastMode('high');

// Or via Laravel session (if integrated)
session(['ctm_a11y_contrast' => 'high']);

Apply styles dynamically in your theme:

<body class="{{ ContaoThememanager\A11y\A11y::contrastClass() }}">
  <!-- Content -->
</body>

Focus Styles for Interactive Elements Enable focus styles globally in your CSS:

/* In your theme's CSS file */
@import 'vendor/contao-thememanager/ctm-accessibility/resources/css/focus-styles.css';

Toggle programmatically:

ContaoThememanager\A11y\A11y::enableFocusStyles(true);

Integration Tips

Contao Hooks: Use Contao’s generatePage hook to inject A11y features dynamically:

public function onGeneratePage()
{
    ContaoThememanager\A11y\A11y::addMetaTags();
}

Laravel Service Providers: Register the package’s service provider in config/app.php:

'providers' => [
    // ...
    ContaoThememanager\A11y\A11yServiceProvider::class,
],

Asset Pipeline: Ensure CSS/JS assets are compiled via Laravel Mix or Contao’s asset system:

// mix.js (Laravel)
mix.copy('vendor/contao-thememanager/ctm-accessibility/resources/js', 'public/js/a11y');

Gotchas and Tips

Pitfalls

Contao-Laravel Compatibility
- The package is Contao-native. If using Laravel, ensure:
  - You’re using a Contao-Laravel bridge.
  - Templates are either Contao .html5 files or Laravel Blade with Contao helper integration.
- Workaround: Create a Laravel facade to wrap Contao’s A11y class:
```
// app/Facades/A11y.php
namespace App\Facades;
use Illuminate\Support\Facades\Facade;
class A11y extends Facade { public static function getFacadeAccessor() { return 'ctm.a11y'; } }
```
CSS/JS Conflicts
- Focus styles or skip links may clash with existing CSS. Use !important sparingly; override via:
```
.ctm-a11y-focus { outline: 2px solid #005fcc !important; }
```
- Test with browser dev tools to inspect computed styles.
Contrast Mode Persistence
- By default, contrast modes may reset on page reload. Store preferences in:
  - Contao: tl_user table or session.
  - Laravel: session() or database (e.g., users table).
Template Overrides
- If modifying Contao templates, always back up original files (e.g., templates/article.html5).
- Use Contao’s replaceInsertTags hook to dynamically inject A11y features.

Debugging

Enabled Features: Check active features via:

print_r(ContaoThememanager\A11y\A11y::getEnabledFeatures());

Contrast Mode: Verify active mode:

echo ContaoThememanager\A11y\A11y::getContrastMode(); // 'high', 'low', or 'none'

Logs: Enable debug mode in config/ctm-a11y.php:
```
'debug' => env('APP_DEBUG', false),
```

Extension Points

Custom ARIA Labels Extend the package by adding custom labels via a service provider:

public function register()
{
    $this->app->singleton('ctm.a11y', function ($app) {
        $a11y = new \ContaoThememanager\A11y\A11y();
        $a11y->addCustomAriaLabel('custom-element', 'Custom label for screen readers');
        return $a11y;
    });
}

Dynamic Feature Toggling Use Contao’s config table or Laravel’s config cache to enable/disable features per environment:
```
// In a Contao backend module
$GLOBALS['TL_CONFIG']['ctm_a11y_skip_links'] = true;
```
Testing
- Keyboard Navigation: Test skip links and focus styles with Tab/Shift+Tab.
- Screen Readers: Use NVDA or VoiceOver to verify ARIA attributes.
- Automated Tools: Run axe-core in CI:
```
npm install @axe-core/cli
axe https://your-site.test --rules="aria-prohibited-attributes"
```

Ctm Accessibility Laravel Package