| 1: | <?php |
| 2: | |
| 3: | namespace LaravelUi5\Core\Ui5\Capabilities; |
| 4: | |
| 5: | use LaravelUi5\Core\Ui5\Contracts\Ui5RegistryInterface; |
| 6: | |
| 7: | /** |
| 8: | * Allows a module or application to contribute configuration data |
| 9: | * to the global LaravelUi5 Shell layer. |
| 10: | * |
| 11: | * The Shell represents the UI container that wraps all UI5 apps. |
| 12: | * It provides global interactions such as navigation overlays, |
| 13: | * help panels, search interfaces, command palettes, and keyboard |
| 14: | * shortcuts. Unlike app-local UI elements, Shell components are |
| 15: | * rendered independently from the active UI5 component and are |
| 16: | * therefore defined at the platform level. |
| 17: | * |
| 18: | * Manifest fragments contributed through this interface are placed |
| 19: | * under the top-level key LaravelUi5ManifestKeys::SHELL. |
| 20: | * |
| 21: | * Only modules implementing this interface can influence Shell |
| 22: | * configuration. The Core does not impose a schema beyond the |
| 23: | * requirement that the returned data must be serializable to JSON. |
| 24: | * |
| 25: | * Typical use cases include: |
| 26: | * - defining keyboard triggers for Navigation, Search, Help |
| 27: | * - enabling or configuring overlays rendered outside the app root |
| 28: | * - contributing global command-palette entries |
| 29: | * - registering static Shell UI elements (e.g. minimal visual cues) |
| 30: | * - platform-wide availability metadata (enable/disable per module) |
| 31: | * |
| 32: | * The returned array must follow the structure expected by the |
| 33: | * corresponding Shell implementation on the frontend. |
| 34: | */ |
| 35: | interface Ui5ShellFragmentInterface |
| 36: | { |
| 37: | /** |
| 38: | * Builds and returns the Shell fragment for this module. |
| 39: | * |
| 40: | * The returned array is inserted under the "shell" manifest key |
| 41: | * and merged with the standard LaravelUi5 manifest structure. |
| 42: | * Implementations must ensure that the fragment is compatible |
| 43: | * with the Shell's configuration schema and does not contain any |
| 44: | * unknown top-level keys outside the "shell" namespace. |
| 45: | * |
| 46: | * @return array<string, mixed> The Shell fragment to be added to the manifest. |
| 47: | */ |
| 48: | public function buildShellFragment(Ui5RegistryInterface $registry, string $namespace): array; |
| 49: | } |
| 50: |