cc-agentic-framework 1.14.1

package/framework/modules/coding/skills/coding/implementing-ios/UIKIT-PATTERNS.md

@@ -0,0 +1,470 @@
+# UIKit Patterns
+
+Modern UIKit patterns for iOS development. Use UIKit when SwiftUI doesn't meet requirements or for legacy projects.
+
+---
+
+## When to Use UIKit
+
+- Complex custom layouts not expressible in SwiftUI
+- Heavy use of UIKit-only components
+- Legacy app maintenance
+- Performance-critical list rendering
+- Complex gesture handling
+- Custom view controller transitions
+
+---
+
+## Modern Collection Views
+
+### Diffable Data Sources
+
+Type-safe, crash-free data management for collection views.
+
+```swift
+// MARK: - Setup
+class ItemListViewController: UIViewController {
+    enum Section { case main }
+
+    typealias DataSource = UICollectionViewDiffableDataSource<Section, Item>
+    typealias Snapshot = NSDiffableDataSourceSnapshot<Section, Item>
+
+    private var collectionView: UICollectionView!
+    private var dataSource: DataSource!
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        configureCollectionView()
+        configureDataSource()
+    }
+
+    private func configureCollectionView() {
+        collectionView = UICollectionView(
+            frame: view.bounds,
+            collectionViewLayout: createLayout()
+        )
+        collectionView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        view.addSubview(collectionView)
+    }
+
+    private func configureDataSource() {
+        // Cell Registration (iOS 14+)
+        let cellRegistration = UICollectionView.CellRegistration<UICollectionViewListCell, Item> {
+            cell, indexPath, item in
+            var config = cell.defaultContentConfiguration()
+            config.text = item.name
+            config.secondaryText = item.description
+            cell.contentConfiguration = config
+            cell.accessories = [.disclosureIndicator()]
+        }
+
+        dataSource = DataSource(collectionView: collectionView) {
+            collectionView, indexPath, item in
+            collectionView.dequeueConfiguredReusableCell(
+                using: cellRegistration,
+                for: indexPath,
+                item: item
+            )
+        }
+    }
+
+    // MARK: - Apply Snapshot
+    func updateItems(_ items: [Item], animated: Bool = true) {
+        var snapshot = Snapshot()
+        snapshot.appendSections([.main])
+        snapshot.appendItems(items)
+        dataSource.apply(snapshot, animatingDifferences: animated)
+    }
+}
+```
+
+### Compositional Layout
+
+Flexible, powerful layouts with minimal code.
+
+```swift
+// MARK: - List Layout
+private func createListLayout() -> UICollectionViewLayout {
+    var config = UICollectionLayoutListConfiguration(appearance: .insetGrouped)
+    config.headerMode = .supplementary
+    config.trailingSwipeActionsConfigurationProvider = { indexPath in
+        let deleteAction = UIContextualAction(style: .destructive, title: "Delete") {
+            [weak self] _, _, completion in
+            self?.deleteItem(at: indexPath)
+            completion(true)
+        }
+        return UISwipeActionsConfiguration(actions: [deleteAction])
+    }
+    return UICollectionViewCompositionalLayout.list(using: config)
+}
+
+// MARK: - Grid Layout
+private func createGridLayout() -> UICollectionViewLayout {
+    let itemSize = NSCollectionLayoutSize(
+        widthDimension: .fractionalWidth(0.5),
+        heightDimension: .fractionalHeight(1.0)
+    )
+    let item = NSCollectionLayoutItem(layoutSize: itemSize)
+    item.contentInsets = NSDirectionalEdgeInsets(top: 8, leading: 8, bottom: 8, trailing: 8)
+
+    let groupSize = NSCollectionLayoutSize(
+        widthDimension: .fractionalWidth(1.0),
+        heightDimension: .fractionalWidth(0.5)
+    )
+    let group = NSCollectionLayoutGroup.horizontal(layoutSize: groupSize, subitems: [item])
+
+    let section = NSCollectionLayoutSection(group: group)
+    section.contentInsets = NSDirectionalEdgeInsets(top: 16, leading: 16, bottom: 16, trailing: 16)
+
+    return UICollectionViewCompositionalLayout(section: section)
+}
+
+// MARK: - Orthogonal Scrolling (Horizontal in Vertical)
+private func createCarouselLayout() -> UICollectionViewLayout {
+    let itemSize = NSCollectionLayoutSize(
+        widthDimension: .fractionalWidth(0.85),
+        heightDimension: .fractionalHeight(1.0)
+    )
+    let item = NSCollectionLayoutItem(layoutSize: itemSize)
+
+    let groupSize = NSCollectionLayoutSize(
+        widthDimension: .fractionalWidth(0.85),
+        heightDimension: .absolute(200)
+    )
+    let group = NSCollectionLayoutGroup.horizontal(layoutSize: groupSize, subitems: [item])
+
+    let section = NSCollectionLayoutSection(group: group)
+    section.orthogonalScrollingBehavior = .groupPagingCentered
+    section.interGroupSpacing = 16
+
+    return UICollectionViewCompositionalLayout(section: section)
+}
+```
+
+### Multiple Sections
+
+```swift
+enum Section: Int, CaseIterable {
+    case featured
+    case categories
+    case items
+}
+
+private func createMultiSectionLayout() -> UICollectionViewLayout {
+    UICollectionViewCompositionalLayout { sectionIndex, environment in
+        guard let section = Section(rawValue: sectionIndex) else { return nil }
+
+        switch section {
+        case .featured:
+            return self.createFeaturedSection()
+        case .categories:
+            return self.createCategoriesSection()
+        case .items:
+            return self.createItemsSection()
+        }
+    }
+}
+```
+
+---
+
+## Cell Configuration
+
+### Content Configuration (iOS 14+)
+
+```swift
+// MARK: - Standard Configurations
+let cellRegistration = UICollectionView.CellRegistration<UICollectionViewListCell, Item> {
+    cell, indexPath, item in
+
+    var config = cell.defaultContentConfiguration()
+    config.text = item.name
+    config.secondaryText = item.subtitle
+    config.image = UIImage(systemName: item.iconName)
+
+    // Customize appearance
+    config.textProperties.font = .preferredFont(forTextStyle: .headline)
+    config.secondaryTextProperties.color = .secondaryLabel
+
+    cell.contentConfiguration = config
+}
+
+// MARK: - Custom Content Configuration
+struct ItemContentConfiguration: UIContentConfiguration {
+    var item: Item?
+
+    func makeContentView() -> UIView & UIContentView {
+        ItemContentView(configuration: self)
+    }
+
+    func updated(for state: UIConfigurationState) -> ItemContentConfiguration {
+        var updated = self
+        // Adjust for state (highlighted, selected, etc.)
+        return updated
+    }
+}
+
+class ItemContentView: UIView, UIContentView {
+    var configuration: UIContentConfiguration {
+        didSet { apply(configuration: configuration) }
+    }
+
+    private let titleLabel = UILabel()
+    private let iconView = UIImageView()
+
+    init(configuration: ItemContentConfiguration) {
+        self.configuration = configuration
+        super.init(frame: .zero)
+        setupViews()
+        apply(configuration: configuration)
+    }
+
+    private func setupViews() {
+        // Layout setup
+    }
+
+    private func apply(configuration: UIContentConfiguration) {
+        guard let config = configuration as? ItemContentConfiguration else { return }
+        titleLabel.text = config.item?.name
+    }
+}
+```
+
+---
+
+## View Controller Lifecycle
+
+### Lifecycle Methods
+
+```swift
+class DetailViewController: UIViewController {
+
+    // MARK: - Lifecycle
+
+    override func loadView() {
+        // Only for programmatic view creation
+        // Don't call super.loadView()
+        view = CustomView()
+    }
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        // One-time setup
+        // Views are loaded but not sized
+        setupNavigationBar()
+        setupSubviews()
+        configureDataSource()
+    }
+
+    override func viewWillAppear(_ animated: Bool) {
+        super.viewWillAppear(animated)
+        // Called every time view appears
+        // Update UI with latest data
+        refreshData()
+    }
+
+    override func viewDidAppear(_ animated: Bool) {
+        super.viewDidAppear(animated)
+        // View is visible and interactive
+        // Start animations, analytics
+        startAnimations()
+    }
+
+    override func viewWillDisappear(_ animated: Bool) {
+        super.viewWillDisappear(animated)
+        // Clean up before leaving
+        stopAnimations()
+    }
+
+    override func viewDidDisappear(_ animated: Bool) {
+        super.viewDidDisappear(animated)
+        // View is no longer visible
+        pauseExpensiveOperations()
+    }
+
+    // MARK: - Trait Changes
+
+    override func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {
+        super.traitCollectionDidChange(previousTraitCollection)
+        // Respond to trait changes (size class, dark mode, etc.)
+        if traitCollection.hasDifferentColorAppearance(comparedTo: previousTraitCollection) {
+            updateColors()
+        }
+    }
+}
+```
+
+---
+
+## Programmatic UI
+
+### Auto Layout DSL
+
+```swift
+class ProfileView: UIView {
+    private let avatarImageView = UIImageView()
+    private let nameLabel = UILabel()
+    private let bioLabel = UILabel()
+    private let stackView = UIStackView()
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        setupViews()
+        setupConstraints()
+    }
+
+    private func setupViews() {
+        avatarImageView.translatesAutoresizingMaskIntoConstraints = false
+        avatarImageView.contentMode = .scaleAspectFill
+        avatarImageView.clipsToBounds = true
+        avatarImageView.layer.cornerRadius = 40
+
+        nameLabel.translatesAutoresizingMaskIntoConstraints = false
+        nameLabel.font = .preferredFont(forTextStyle: .headline)
+        nameLabel.adjustsFontForContentSizeCategory = true
+
+        bioLabel.translatesAutoresizingMaskIntoConstraints = false
+        bioLabel.font = .preferredFont(forTextStyle: .body)
+        bioLabel.textColor = .secondaryLabel
+        bioLabel.numberOfLines = 0
+        bioLabel.adjustsFontForContentSizeCategory = true
+
+        stackView.translatesAutoresizingMaskIntoConstraints = false
+        stackView.axis = .vertical
+        stackView.spacing = 8
+        stackView.addArrangedSubview(nameLabel)
+        stackView.addArrangedSubview(bioLabel)
+
+        addSubview(avatarImageView)
+        addSubview(stackView)
+    }
+
+    private func setupConstraints() {
+        NSLayoutConstraint.activate([
+            avatarImageView.topAnchor.constraint(equalTo: topAnchor, constant: 16),
+            avatarImageView.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 16),
+            avatarImageView.widthAnchor.constraint(equalToConstant: 80),
+            avatarImageView.heightAnchor.constraint(equalToConstant: 80),
+
+            stackView.topAnchor.constraint(equalTo: avatarImageView.topAnchor),
+            stackView.leadingAnchor.constraint(equalTo: avatarImageView.trailingAnchor, constant: 16),
+            stackView.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -16),
+            stackView.bottomAnchor.constraint(lessThanOrEqualTo: bottomAnchor, constant: -16)
+        ])
+    }
+}
+```
+
+### Stack Views
+
+```swift
+class FormView: UIView {
+    private lazy var stackView: UIStackView = {
+        let stack = UIStackView()
+        stack.axis = .vertical
+        stack.spacing = 16
+        stack.alignment = .fill
+        stack.distribution = .fill
+        stack.translatesAutoresizingMaskIntoConstraints = false
+        return stack
+    }()
+
+    func addField(_ field: UIView) {
+        stackView.addArrangedSubview(field)
+    }
+
+    func addSpacing(_ spacing: CGFloat) {
+        let spacer = UIView()
+        spacer.heightAnchor.constraint(equalToConstant: spacing).isActive = true
+        stackView.addArrangedSubview(spacer)
+    }
+}
+```
+
+---
+
+## Coordinator Pattern
+
+```swift
+protocol Coordinator: AnyObject {
+    var childCoordinators: [Coordinator] { get set }
+    var navigationController: UINavigationController { get }
+    func start()
+}
+
+class AppCoordinator: Coordinator {
+    var childCoordinators: [Coordinator] = []
+    var navigationController: UINavigationController
+
+    init(navigationController: UINavigationController) {
+        self.navigationController = navigationController
+    }
+
+    func start() {
+        let homeVC = HomeViewController()
+        homeVC.coordinator = self
+        navigationController.pushViewController(homeVC, animated: false)
+    }
+
+    func showDetail(for item: Item) {
+        let detailVC = DetailViewController(item: item)
+        detailVC.coordinator = self
+        navigationController.pushViewController(detailVC, animated: true)
+    }
+
+    func showSettings() {
+        let settingsCoordinator = SettingsCoordinator(navigationController: navigationController)
+        childCoordinators.append(settingsCoordinator)
+        settingsCoordinator.start()
+    }
+}
+```
+
+---
+
+## Accessibility
+
+```swift
+class AccessibleButton: UIButton {
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        setupAccessibility()
+    }
+
+    private func setupAccessibility() {
+        isAccessibilityElement = true
+        accessibilityTraits = .button
+        accessibilityLabel = "Action button"
+        accessibilityHint = "Double-tap to perform action"
+    }
+
+    func updateAccessibility(label: String, hint: String? = nil) {
+        accessibilityLabel = label
+        accessibilityHint = hint
+    }
+}
+
+// Dynamic Type Support
+label.font = .preferredFont(forTextStyle: .body)
+label.adjustsFontForContentSizeCategory = true
+```
+
+---
+
+## Best Practices
+
+1. **Use Diffable Data Sources** - Type-safe, no crashes
+2. **Use Compositional Layout** - Flexible, powerful
+3. **Use Cell Registration** - Type-safe cell configuration
+4. **Use Content Configuration** - Modern cell content
+5. **Programmatic UI** - Better version control, no merge conflicts
+6. **Coordinator Pattern** - Decouple navigation
+7. **Support Dynamic Type** - Accessibility requirement
+8. **Use semantic colors** - Dark Mode support
+
+---
+
+**See Also:**
+- [SKILL.md](./SKILL.md) - Main skill overview
+- [SWIFTUI-PATTERNS.md](./SWIFTUI-PATTERNS.md) - SwiftUI patterns
+- [HIG-COMPLIANCE.md](./HIG-COMPLIANCE.md) - Design guidelines

package/framework/modules/coding/skills/coding/structuring-code/CHECKLISTS.md

@@ -0,0 +1,151 @@
+# Code Structure Checklists
+
+Quick reference checklists for evaluating code structure quality.
+
+---
+
+## File Organization Checklist
+
+### Single Responsibility
+- [ ] Each file has one clear purpose
+- [ ] File name describes its content accurately
+- [ ] You can explain what the file does in one sentence
+- [ ] Related types/helpers are colocated (not scattered)
+
+### File Size
+- [ ] All files are under 500 lines (hard limit)
+- [ ] Files 400-500 lines are flagged for proactive splitting
+- [ ] Very small files (<30 lines) serve a real purpose (not over-split)
+- [ ] Target range is 100-400 lines for most files
+
+### Directory Structure
+- [ ] Related files are colocated (feature-based organization)
+- [ ] Directory depth is shallow (2-4 levels typically)
+- [ ] Directory names clearly indicate contents
+- [ ] No empty or near-empty directories
+- [ ] Index/barrel files used purposefully (public API, not everywhere)
+
+### Naming
+- [ ] File names match primary exports
+- [ ] Naming conventions are consistent across project
+- [ ] No vague names (utils, helpers, misc, common)
+- [ ] Test files are clearly identified (.test, .spec, _test)
+
+---
+
+## Readability Checklist
+
+### Naming Quality
+- [ ] Variable names reveal purpose without comments
+- [ ] Function names are verb + noun (action-oriented)
+- [ ] Class/type names are nouns (domain language)
+- [ ] Boolean names use is/has/can/should prefixes
+- [ ] No single-letter variables (except loop indices)
+- [ ] No cryptic abbreviations
+
+### Function Design
+- [ ] Functions are small and focused (under 50 lines typically)
+- [ ] Each function does one thing
+- [ ] Parameter count is reasonable (3-4 max, or use options object)
+- [ ] Nesting depth is shallow (max 3 levels)
+- [ ] Early returns used to reduce nesting
+- [ ] No "and" in function names (sign of multiple responsibilities)
+
+### Comments
+- [ ] Comments explain WHY, not WHAT
+- [ ] No commented-out code (use version control)
+- [ ] No obvious comments restating the code
+- [ ] Documentation comments on public APIs
+- [ ] TODOs have context (date, ticket, author)
+- [ ] No misleading or outdated comments
+
+### Style Consistency
+- [ ] Code follows project conventions
+- [ ] Formatting is consistent (use automated tools)
+- [ ] Whitespace groups related code logically
+- [ ] Import order follows project standard
+
+---
+
+## DRY Compliance Checklist
+
+### Duplication Detection
+- [ ] No obvious copy-paste code blocks
+- [ ] Similar patterns have been evaluated for extraction
+- [ ] Same bug doesn't need fixing in multiple places
+- [ ] Same logic isn't implemented differently in different places
+
+### Extraction Quality
+- [ ] Extracted code has clear, descriptive name
+- [ ] Abstraction hides complexity (doesn't add it)
+- [ ] Parameters are minimal and meaningful
+- [ ] Changes to one use case don't break others
+
+### Avoiding Over-Engineering
+- [ ] Abstractions exist because of real duplication (not speculation)
+- [ ] No "framework" built for one use case
+- [ ] Similar code that will evolve differently is kept separate
+- [ ] Rule of three considered before extracting
+
+---
+
+## PR Review Structure Checklist
+
+Use this when reviewing pull requests for structural quality.
+
+### New Files
+- [ ] File placement follows project conventions
+- [ ] File names are descriptive and consistent
+- [ ] File size is reasonable for the content
+- [ ] Related files are colocated appropriately
+
+### Modified Files
+- [ ] Changes don't push file over reasonable size limits
+- [ ] New code follows existing patterns in the file
+- [ ] No new duplication introduced
+- [ ] File organization still makes sense after changes
+
+### New Functions/Methods
+- [ ] Names are clear and action-oriented
+- [ ] Size is appropriate (not too long)
+- [ ] Parameter count is reasonable
+- [ ] Single responsibility is maintained
+
+### Duplication Check
+- [ ] New code doesn't duplicate existing code
+- [ ] If similar code exists, extraction was considered
+- [ ] If not extracted, there's a good reason (documented if non-obvious)
+
+### Overall Structure
+- [ ] Changes improve or maintain codebase quality
+- [ ] No new technical debt introduced without acknowledgment
+- [ ] Structure supports future changes (not blocking)
+
+---
+
+## Quick Assessment (5-Minute Review)
+
+For rapid structural assessment when full review isn't possible.
+
+### Pass/Fail Indicators
+
+**Immediate concerns (flag for review):**
+- [ ] Any file over 500 lines (hard limit exceeded)
+- [ ] Any function over 150 lines
+- [ ] Nesting deeper than 5 levels
+- [ ] Obvious copy-paste blocks (10+ lines repeated)
+- [ ] Cryptic names requiring comments to understand
+
+**Yellow flags (note for discussion):**
+- [ ] Files 400-500 lines (approaching limit)
+- [ ] Functions 100-150 lines
+- [ ] Nesting 4-5 levels
+- [ ] Subtle duplication patterns
+- [ ] Vague naming (utils, helpers)
+
+**Green indicators (good signs):**
+- [ ] Clear file and function names
+- [ ] Small, focused functions
+- [ ] Shallow nesting with early returns
+- [ ] Consistent style throughout
+- [ ] Appropriate use of abstractions