# Theme Almanac ## Package docs status This page is generated from package source documentation in `the Capell packages repository` and the checked-in manifest. Source documentation is not distribution status. Before running a Composer command, verify that the exact package and compatible 1.x release are available through public Packagist or the authenticated marketplace account. | Field | Value | | --- | --- | | Composer package | `capell-app/theme-almanac` | | Package slug | `theme-almanac` | | Product group | Capell Themes | | Tier | premium | | Bundle | `themes` | | Runtime contexts | `frontend` | | Capell version | `^1.0` | | Catalogue role | extension | | Release channel | Labs | | Source repository | `capell-app/packages` | | Source path | `packages/theme-almanac` | | Docs source | `packages/theme-almanac/docs` | | Manifest | [`capell.json`](https://github.com/capell-app/packages/edit/main/packages/theme-almanac/capell.json) | ## What This Plugin Adds Theme Almanac is an **Available**, **No schema impact** Capell theme in the **Capell Themes** product group. It ships as `capell-app/theme-almanac` and extends these surfaces: frontend. Theme Almanac adds a month-addressed living calendar, day ledgers, bounded season navigation, recurring-series discovery, honest booking fallbacks, and three vertical-distinct presets. Editors maintain ordinary calendar content while visitors receive a complete semantic list of day pages that progressively gains patina, today state, keyboard movement, ledger previews, and countdowns. Evidence: [`src/AlmanacThemeServiceProvider.php`](src/AlmanacThemeServiceProvider.php), [`src/Enums/WidgetComponentEnum.php`](src/Enums/WidgetComponentEnum.php), [`resources/views/sections/month-grid-living-ledger.blade.php`](resources/views/sections/month-grid-living-ledger.blade.php), [`src/Support/Demo/AlmanacDemoContent.php`](src/Support/Demo/AlmanacDemoContent.php), [`resources/js/almanac-frontend.js`](resources/js/almanac-frontend.js), [`resources/css/theme-almanac.css`](resources/css/theme-almanac.css). Status details: - Status: Available - Tier: premium - Bundle: themes - Composer package: `capell-app/theme-almanac` - Namespace: `Capell\ThemeAlmanac` - Theme key: `almanac` ## Why It Matters **For developers:** The package centralises calendar expansion in Actions, structured boundaries in Data objects, optional integrations in availability classes, and active-theme JavaScript in the shared frontend-resource seam. **For teams:** Recurring venues can publish sessions, ordinary hours, closures, past notes, and booking paths as one calendar-led website instead of maintaining a separate events microsite. Evidence: [`src/Actions/ExpandOccurrencesForMonthAction.php`](src/Actions/ExpandOccurrencesForMonthAction.php), [`src/Actions/ResolveCalendarMonthPageAction.php`](src/Actions/ResolveCalendarMonthPageAction.php), [`src/Support/Availability/BookingsAvailability.php`](src/Support/Availability/BookingsAvailability.php), [`src/Support/Availability/NewsletterAvailability.php`](src/Support/Availability/NewsletterAvailability.php), [`src/Support/Availability/CommentsAvailability.php`](src/Support/Availability/CommentsAvailability.php), [`resources/views/sections/day-ledger-session-rail.blade.php`](resources/views/sections/day-ledger-session-rail.blade.php), [`resources/views/sections/series-recurring-index.blade.php`](resources/views/sections/series-recurring-index.blade.php), [`resources/views/sections/booking-slot-card.blade.php`](resources/views/sections/booking-slot-card.blade.php). ## Screens And Workflow Screenshot contract: `docs/screenshots.json`. ![Almanac - Spring Tide marketplace plate](screenshots/almanac-spring-tide.svg) ![Almanac - Projection Room marketplace plate](screenshots/almanac-projection-room.svg) - Almanac - Spring Tide marketplace plate (frontend, required). - Almanac - Projection Room marketplace plate (frontend, required). - Almanac - Harvest Table marketplace plate (frontend, required). - Almanac canonical month homepage (frontend, optional). - Almanac programme directory (frontend, optional). - Almanac day ledger detail (frontend, optional). - Almanac contact and year heatmap (frontend, optional). - Almanac closed-season state (frontend, optional). - Almanac missing-date recovery (frontend, optional). - Almanac next-opening conversion surface (frontend, optional). ## Technical Shape - Service providers: `Capell\ThemeAlmanac\AlmanacThemeServiceProvider`. - Actions: `ExpandOccurrencesForMonthAction`, `InstallAlmanacThemeDemoAction`, `ResolveCalendarHomepageRedirectAction`, `ResolveCalendarMonthPageAction`. - Data objects: `CalendarDayData`, `CalendarMonthData`, `CalendarSessionData`. - Command signatures: `capell:theme-almanac-demo`. - Console command classes: `DemoCommand`. - Manifest contributions: `admin-page: Capell\ThemeAlmanac\Manifest\ThemeManagementPageContribution`. - Health checks: `Capell\ThemeAlmanac\Health\ThemeAlmanacHealthCheck`. - Blade views: `packages/theme-almanac/resources/views/components/booking-slot-action.blade.php`, `packages/theme-almanac/resources/views/components/comments-thread.blade.php`, `packages/theme-almanac/resources/views/components/contact-channel.blade.php`, `packages/theme-almanac/resources/views/components/newsletter-capture.blade.php`, `packages/theme-almanac/resources/views/components/site-search.blade.php`, `packages/theme-almanac/resources/views/sections/booking-slot-card.blade.php`, `packages/theme-almanac/resources/views/sections/contact.blade.php`, `packages/theme-almanac/resources/views/sections/countdown-next-opening.blade.php`, `packages/theme-almanac/resources/views/sections/cta--seasonline.blade.php`, `packages/theme-almanac/resources/views/sections/cta.blade.php`, `packages/theme-almanac/resources/views/sections/day-ledger-session-rail.blade.php`, `packages/theme-almanac/resources/views/sections/footer.blade.php`, `and 12 more`. - Cache tags: `theme-almanac`. ## Data Model This theme has no schema impact. It relies on core Capell site, page, locale, and theme records instead of declaring package-owned tables. ## Install Impact - Required packages: `capell-app/core`, `capell-app/theme-foundation`, `capell-app/frontend`, `capell-app/layout-builder`. - Admin navigation: declares `admin-page: ThemeManagementPageContribution`; each Filament page or resource controls its own navigation visibility. - Admin/editor extensions: none declared. - Permissions: none declared in `capell.json`. - Public routes: none declared. - Database changes: no package migrations declared. - Config: no package config files. - Settings: no package settings declared. - Queues or schedules: none declared. - Cache tags: `theme-almanac`. - Commands: `capell:theme-almanac-demo`. ## Common Pitfalls - Keep required Capell packages on compatible v4 releases: `capell-app/core`, `capell-app/theme-foundation`, `capell-app/frontend`, `capell-app/layout-builder`. - Keep public Blade and cached HTML free of authoring markers, model IDs, permissions, signed editor URLs, and lazy database queries. - Custom write integrations must preserve invalidation for `theme-almanac` cache tags. ## Troubleshooting | Symptom | Likely cause | Check | Fix | | --- | --- | --- | --- | | Package surface is missing after install | Provider or manifest is not loaded | Confirm `capell.json`, package `composer.json`, and provider registration | Reinstall the package, refresh Composer autoload, and clear host caches | | Public output leaks unexpected state | Render data, cache variation, or authoring boundary has regressed | Check public Blade, cache tags, and public-output safety tests | Move data loading out of Blade and rerun the package public-output tests | ## Quick Start 1. Install the package: `composer require capell-app/theme-almanac`. 2. No package-specific setup command or migrations are declared. 3. Open the Almanac - Spring Tide marketplace plate and confirm the public output renders without admin state. ## Next Steps - [Package docs](README.md) - [Overview](overview.md) - [Troubleshooting](#troubleshooting) - [Screenshot contract](screenshots.json) - [Marketplace assets](assets/marketplace/) - [Capell content language plan](../../docs/CONTENT_LANGUAGE_PLAN.md) - [Capell documentation design system](../../docs/DESIGN_SYSTEM.md) - [Capell and package ERD notes](../../docs/erd/capell-and-package-erds.md) - Related packages: [Theme Foundation](../theme-foundation/README.md), [Layout Builder](../layout-builder/README.md), [Bookings](../bookings/README.md), [Events](../events/README.md), [Form Builder](../form-builder/README.md), [Newsletter](../newsletter/README.md), [Search](../search/README.md), [Comments](../comments/README.md). - Focused tests: `vendor/bin/pest packages/theme-almanac/tests --configuration=phpunit.xml`.