TGCardViewController

Provides a card-based view controller for mapping applications where the card's content is in sync with a map, similar to how Apple Maps works. For an application of this see the TripKitUI SDK and TripGo by SkedGo.

Installation and usage

Install

.package(url: "https://github.com/skedgo/TGCardViewController.git", from: "1.7.5")

Add it to your app

1. Create a TGCardViewController subclass and use it in your storyboard

2. Override init(coder:) so that the instance from the storyboard isn't used, but instead TGCardViewController.xib:

   import TGCardViewController
   
   class CardViewController: TGCardViewController {
   
     required init(coder aDecoder: NSCoder) {
       // When loading from the storyboard we don't want to use the controller
       // as defined in the storyboard but instead use the TGCardViewController.xib
       super.init(nibName: "TGCardViewController", bundle: TGCardViewController.bundle)
     }
   
     ...
   }
   

3. Create a TGCard subclass, that represents the card at the top level, and add then push that in your view controller's viewDidLoad:

     override func viewDidLoad() {
       rootCard = MyRootCard()
       super.viewDidLoad()
     }
   

Specs

1. Basic functionality of cards

Behaviour:

• Card positions:
  1. collapsed: Only shows header of card
  2. peaking: Shows half of card's content and the map content
  3. extended: Shows card fully, map shows a little bit on top but is greyed out
• Pushing a card from another card
  • ☑ Adds (x) button unless it’s the root card
  • ☑ Card has a preferred position which is used when pushing
  • ☑ Animation: Slide up from the bottom; fading black view on card below with alpha from 0% to 25%
  • ☑ Pass on appearance callbacks appropriately to involved cards
• Popping a card
  • ☑ Tap (x) to pop card
  • ☑ When popping top card, restore card position of card below when something got pushed on it
  • ☑ Animation: Slide back down; fading out black view on card below with alpha from 25% to 0%
  • ☑ Pass on appearance callbacks appropriately to involved cards
• Cards are draggable
  • ☑ Snap to collapsed (only title), peaking (near half-way showing both map and card content), extended (still shows a bit of the map on top, but darkened)
  • ☑ Cards can be dragged up and down anywhere on the card
  • ☑ Tap title when collapsed: go to peaking
  • ☑ Tap title when peaking: go to extended
  • ☑ Tap title when extended: do nothing
  • ☑ Tap map when extended: go to peaking
• Cards are scrollable
  • ☑ Cards typically have scrolling content: when scrolling down the card's header stays at the top and a bit of the map still keeps peaking through at the top.
  • ☑ When scrolling down show a thin separator line between the card's scrolling content and the card's header
  • ☑ When scrolling to the top and keeping to scroll, start dragging card

Styles:

• ☑ Animation curve for push and pop
• ☑ Blurry view under status bar (like Maps app)
• ☑ When rotating device and card is collapsed, make sure card ends up in correct position

2. Card content and gestures

Card types:

• Plain card
  • ☑ On top: Title, (x), optional subtitle and optional accessory view
  • ☑ Add accessory view
  • ☑ Content can be scrollable and size adjusts to content. If it fits, it shouldn’t be scrollable
  • ☑ Add optional floaty button
• Table card
  • ☑ Same as plain card, but with a table view as its content
  • ☑ Allow specifying plain (e.g., for departures) or grouped style (e.g., for profile)
• Collection card
  • ☑ Same as plain card, but with a collection view as its content
  • ☑ Allow specifying collection view layout
• Hosting card
  • ☑ Allow using a SwiftUI view as the card's content
• Paging card
  • ☑ Handles list of child cards on the same hierarchical level which can be paged programatically and through gestures
  • ☑ Has header view: Used for titles (child cards shouldn't show them then) and navigation; Header view is separate from sticky bar, i.e., you can have both.
  • ☑ Re-uses the top card's map manager
  • ☑ Pass on appearance callbacks appropriately to child cards

Card styles:

• ☑ Rounded corners to cards
• ☑ Grab handle for cards
• ☑ Nice close buttons (and next button for paging cards)
• ☑ Title and subtitle styling
• ☑ Add mini drop shadow to card views
• ☑ Bottom view

3. Map content

Map content:

• ☑ Cards can optionally have map content
• ☑ When showing the content, the insets should be respected to account for the card overlapping the map
• ☑ If there’s no map content: Show card always extended and don't allow dragging it down (or just snap back up when using tries)

Map buttons:

• ☑ Optional list of buttons that float on the right above the card or in the top right corner (when collapsed or peaking)
• ☑ When dragging up the card to extended, the buttons fade away

4. Large width (iPad + iPhone in landscape)

• ☑ Move card to the side with min (iPhone Plus) and max (iPad) width
• ☑ Make sure transitions work when changing size and traits

5. UIKit features

• ☑ State restoration, using NSUserActivity
• ☑ VoiceOver Accessibility
• ☑ Keyboard shortcuts

End-user documentation

Keyboard shortcuts

• Card controller
  • ⌃+↑: Expand card
  • ⌃+↓: Expand/collapse card
  • ⌘+w: Pop card or dismiss modal
• Table view cards
  • ↑: Highlight previous item
  • ↓: Highlight next item
  • ⌘+↑: Highlight item at start of list
  • ⌘+↓: Highlight item at end of list
  • Space or enter: select item
  • Esc: deselect
• Paging cards
  • ⌃+←: Previous card
  • ⌃+→: Next card