Calendar Rule

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

CalendarRule is the scheduling-constraint record that validates or narrows allowed dates for entities such as OrderShipment.

Parent hierarchy:

• Fulfillment & Shipping
• Scheduling Constraints
• Calendar Rule

Primary implementation paths:

• packages/framework/src/Models/CalendarRule.php
• packages/framework/src/Models/CalendarRuleCondition.php
• packages/framework/src/Services/CalendarRule
• packages/admin/src/Livewire/Admin/Settings/CalendarRules
• packages/admin/src/Livewire/Admin/Settings/CalendarRule

What Users Can Do With It

Direct capabilities

Operators can:

• create calendar rules from Settings > Calendar Rules
• edit bilingual titles and active state
• add prerequisite and validation conditions
• delete calendar rules

Indirect capabilities

Other workflows use calendar rules to:

• validate pickup or shipping dates in the order-shipment block
• suggest the next available date when a selected date is invalid
• create customer-specific delivery schedules from application services

Things users cannot do directly

Users do not type raw condition payload JSON in the packaged UI. The condition registry and Livewire forms generate the payload structure behind the scenes.

Where It Is Managed

Channel	Role	Notes
Settings > Calendar Rules	Direct	Packaged list and create flow
Settings > Calendar Rule detail	Direct	Basic information plus conditions
Order > Shipments block	Indirect	Selected pickup or shipping date is validated against the rules
Customer-specific automation	Indirect	Services can create default delivery rules for customers

Sources:

• packages/admin/routes/web.php
• packages/admin/src/Livewire/Admin/Settings/CalendarRules
• packages/admin/src/Livewire/Admin/Settings/CalendarRule
• packages/framework/src/Rules/CalendarRuleValidation.php

Channel-Level Field Coverage

Create flow

The packaged create dialog captures:

• English title
• French title
• entity type

New rules are created inactive by default.

Source:

• packages/admin/src/Livewire/Admin/Settings/CalendarRules/CreateDialog.php

Basic information block

The rule detail page allows operators to edit:

• English title
• French title
• active state

Source:

• packages/admin/src/Livewire/Admin/Settings/CalendarRule/BasicInformationBlock.php

Conditions block

Operators can add or edit:

• prerequisite conditions
• validation conditions
• operator choice
• form-driven payload fields defined by the selected condition type

Sources:

• packages/admin/src/Livewire/Admin/Settings/CalendarRule/Conditions/CreateDialog.php
• packages/framework/src/Models/CalendarRuleCondition.php

Configuration And Data Model

Key model characteristics:

• soft-deletable
• stores bilingual names as structured JSON
• targets an entity type
• owns many conditions

Important fields:

Field	Purpose
entity_type	what kind of thing the rule applies to
filter_type / filter_id	optional scoped ownership such as a customer
default	whether the rule is a default
active	whether the rule is enforced

Sources:

• packages/framework/src/Models/CalendarRule.php
• packages/framework/src/Models/CalendarRuleCondition.php

Relationships

CalendarRule directly relates to:

• conditions()
• prerequisites()
• validations()

Practical dependents:

• order-shipment pickup date validation
• customer-specific delivery schedules

Rules And Downstream Effects

Shipment-date validation

CalendarRuleValidation builds a context from the order shipment, order, and selected shipping service, then asks the calendar-rule orchestrator whether a date passes.

If not, it returns a human-facing error and can include the next available date.

Source:

• packages/framework/src/Rules/CalendarRuleValidation.php

Customer schedule automation

The calendar-rule service can generate default customer delivery schedules with:

• a customer prerequisite
• a weekday validation

Source:

• packages/framework/src/Services/CalendarRule/CalendarRuleService.php

Integrations And Automation

Calendar rules are deeply tied to scheduling rather than shipping-price calculation.

They integrate with:

• order-shipment date selection
• customer-specific scheduling services
• the condition registry and condition-service pipeline

Sources:

• packages/framework/src/Rules/CalendarRuleValidation.php
• packages/framework/src/Services/CalendarRule/CalendarRuleService.php

Where It Appears To End Users

CalendarRule is not shopper facing as a concept, but its effect is very visible.

Customers and operators feel it when:

• a chosen pickup or delivery date is accepted
• a date is rejected with an explanation
• the next available date is suggested

Current Documentation Takeaways

1. CalendarRule is a direct packaged admin feature, not just hidden framework plumbing.
2. It is a supporting configuration node, but it materially changes shipping and pickup date behavior.
3. The actual condition payloads are system-managed through registered forms and services rather than manual free-form editing.

Open Questions

• This pass verified the packaged rule and condition-management flow, but did not audit every registered condition class in the calendar-rule registry.