From e11a5d39f16bc33c50552950d9796229bcfeb4e4 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Fri, 25 Sep 2026 19:48:09 +0300 Subject: [PATCH 1/2] Add SwiftUI NavigationSplitView plugin and skill --- .agents/plugins/marketplace.json | 20 ++++++++++ .../.codex-plugin/plugin.json | 27 +++++++++++++ .../navigationsplitview-swiftui/SKILL.md | 38 +++++++++++++++++++ 3 files changed, 85 insertions(+) create mode 100644 .agents/plugins/marketplace.json create mode 100644 plugins/navigation-split-view/.codex-plugin/plugin.json create mode 100644 plugins/navigation-split-view/skills/navigationsplitview-swiftui/SKILL.md diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..1a3a556 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "navigation-split-view", + "interface": { + "displayName": "NavigationSplitView" + }, + "plugins": [ + { + "name": "navigation-split-view", + "source": { + "source": "local", + "path": "./plugins/navigation-split-view" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Coding" + } + ] +} diff --git a/plugins/navigation-split-view/.codex-plugin/plugin.json b/plugins/navigation-split-view/.codex-plugin/plugin.json new file mode 100644 index 0000000..5931766 --- /dev/null +++ b/plugins/navigation-split-view/.codex-plugin/plugin.json @@ -0,0 +1,27 @@ +{ + "name": "navigation-split-view", + "version": "0.1.0", + "description": "SwiftUI NavigationSplitView patterns for adaptive multi-column apps.", + "author": { + "name": "SoundBlaster", + "url": "https://github.com/SoundBlaster" + }, + "repository": "https://github.com/SoundBlaster/NavigationSplitView", + "license": "MIT", + "keywords": ["SwiftUI", "NavigationSplitView", "iOS", "iPadOS", "macOS"], + "skills": "./skills/", + "interface": { + "displayName": "NavigationSplitView", + "shortDescription": "Build adaptive SwiftUI split navigation.", + "longDescription": "Guidance based on NavigationSplitViewKit for synchronizing selections, adapting between compact and regular layouts, and presenting inspectors across Apple platforms.", + "developerName": "SoundBlaster", + "category": "Coding", + "capabilities": ["SwiftUI", "Navigation"], + "websiteURL": "https://soundblaster.github.io/NavigationSplitView/", + "defaultPrompt": [ + "Help me design an adaptive NavigationSplitView.", + "Review my SwiftUI split-view selection state.", + "Adapt this inspector for compact layouts." + ] + } +} diff --git a/plugins/navigation-split-view/skills/navigationsplitview-swiftui/SKILL.md b/plugins/navigation-split-view/skills/navigationsplitview-swiftui/SKILL.md new file mode 100644 index 0000000..86e8fca --- /dev/null +++ b/plugins/navigation-split-view/skills/navigationsplitview-swiftui/SKILL.md @@ -0,0 +1,38 @@ +--- +name: navigationsplitview-swiftui +description: Design, implement, or debug SwiftUI interfaces built around NavigationSplitView, including synchronized column selections, compact and regular layouts, and inspectors. Use for multi-column navigation work; general SwiftUI screens without split navigation are out of scope. +--- + +# SwiftUI NavigationSplitView + +Use this skill when a task involves a sidebar/content/detail flow, adaptive split-view behavior, or an inspector connected to that flow. Ground recommendations in the target app's deployment targets and existing navigation model. The repository hosting this skill is an example implementation, not a mandatory dependency: recommend `NavigationSplitViewKit` only when its API and platform requirements fit the project. + +## Start from the target project + +- Inspect the existing navigation entry point, model identity, deployment targets, and whether the app supports multiple windows before changing its state model. +- Check the current Apple API documentation when behavior depends on OS version; SwiftUI navigation behavior and available modifiers vary by platform and release. +- For this repository's implementation details, consult `Sources/NavigationSplitViewKit/Models/NavigationModel.swift`, `XcodeProject/NewNav/ContentView.swift`, and the DocC tutorial at `Sources/NavigationSplitViewKit/NavigationSplitViewKit.docc/NavigationSplitViewImplementation.tutorial`. +- The package currently declares iOS 17 and macOS 14 minimums. Do not transfer that constraint to a host app unless it chooses to depend on the package. + +## State and selection + +- Keep each selection typed to its model and make navigation values stable and identifiable. Prefer value-based `NavigationLink` and `List(selection:)` bindings where the user should see a selected row. +- Keep selection and column visibility in state owned by the relevant scene/window. With Observation, a `@State`-owned `@Observable` model can expose bindings through a local `@Bindable` in `body`; use the host project's existing state approach when it differs. +- When a parent selection changes, reconcile child selections against the new parent's contents. Clear stale child selections or choose a valid default according to the product's compact/regular navigation behavior. +- Make empty and invalid selection states explicit in the detail UI rather than force-unwrapping navigation state. + +## Adaptation and inspector + +- Treat compact and regular layouts as different navigation experiences, not merely narrower versions of the same three visible columns. In the repository example, regular width can show a selected child in the detail column; compact width clears that selection and pushes a destination from the content list. +- Read the horizontal size class from the environment and react to changes, including rotation and window resizing. Account for an unavailable size class instead of assuming it is always compact or regular. +- Use the system `.inspector(isPresented:)` when the secondary information belongs in an inspector. Connect its visibility to the navigation state, provide an accessible toolbar control, and ensure the content remains useful when the inspector is hidden or unavailable on a compact device. +- Prefer native `NavigationSplitView` column behavior and platform conventions before introducing custom width/visibility rules. + +## Implement and review + +1. Map the sidebar, content, and detail responsibilities and list the valid selection transitions. +2. Bind selection and column visibility at the split-view boundary; keep child views focused on rendering their input and emitting user intent. +3. Define compact navigation and empty-selection behavior explicitly, then connect any inspector to the same scene-level state. +4. Review each supported platform and size class for stale selections, back navigation, empty data, and inspector dismissal. Use previews or a simulator when visual behavior is part of the request. + +Avoid copying the sample wholesale when the host app uses a different navigation architecture, older deployment targets, deep links, restoration, or document-based state. Preserve those existing contracts and adapt only the relevant pattern. From d4616088be18c801d4b74f32fc2b9947c3b70bcd Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 27 Sep 2026 23:22:02 +0300 Subject: [PATCH 2/2] Run build checks for plugin changes --- .github/workflows/build.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 71f32db..61634ca 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -6,6 +6,8 @@ on: - '**' paths: - 'XcodeProject/**' + - '.agents/**' + - 'plugins/**' - '.github/workflows/*.yml' push: branches: @@ -13,6 +15,8 @@ on: - master paths: - 'XcodeProject/**' + - '.agents/**' + - 'plugins/**' - '.github/workflows/*.yml' jobs: