Safely access Apple's SF Symbols using static typing

Apple mentioned in this WWDC Video (4:10) that explicit localization is supported, and we know what suffixes are supported based on name_availability.plist extracted from the app.

This issue is for discussion to support this feature or not and to choose the implementation approach. Implementation details (e.g: Naming) will be discussed separately once the PR is made.

These are the implementations that I have in mind, ordered based on type-safety:

Implementation 1

• Providing localized properties on SFSymbol for all the possible localizations, returns a new type LocalizedSFSymbol.
• Initializing UIImage with LocalizedSFSymbol returns UIImage?.

Example:

extension SFSymbol {
	var ar: LocalizedSFSymbol { LocalizedSFSymbol(rawValue: "\(rawValue).ar") }
	// all other possible localizations, even ".rtl" which is not available for "character"
}

let arabicCharacterImage = UIImage(systemSymbol: .character.ar) // UIImage?

Implementation 2

• Having an internal Dictionary<SFSymbol, Set<Localization>>.
• Providing localized properties on SFSymbol for all the possible localizations, returns a new type LocalizedSFSymbol? based on the Dictionary.
• Initializing UIImage with LocalizedSFSymbol returns UIImage.

Example:

extension SFSymbol {
	var ar: LocalizedSFSymbol? {
		guard localizationDictionary[self]?.contains(.ar) == true else { return nil }
		return LocalizedSFSymbol(rawValue: "\(rawValue).ar") 
	}
	// all other possible localizations, even ".rtl" which is not available for "character"
}

if let arabicCharacterSymbol = SFSymbol.character.ar {
	let arabicCharacterImage = UIImage(systemSymbol: arabicCharacterSymbol) // UIImage
}

Implementation 3

• Providing a new namespace for each symbol with localization.
• For each symbol, The new namespace will have only the localization(s) available for this symbol
• Keeping the default symbols as they are currently for source compatibility.

Example:

extension SFSymbol {
	enum Character {
		static var ar: SFSymbol { SFSymbol(rawValue: "character.ar") }
		// all other localizations available for "character" only
	}
}

let defaultCharacterImage = UIImage(systemSymbol: .character) // UIImage
let arabicCharacterImage = UIImage(systemSymbol: .Character.ar) // UIImage
// or
let arabicCharacterImage = UIImage(systemSymbol: .Localizable.Character.ar) // UIImage

Implementation 4

• Same idea as Implementation 3.
• Instead of keeping the default symbols static in SFSymbol, it would be moved to its dedicated namespace. Avoiding the confusion of .Character and .character.

Example:

extension SFSymbol {
	enum Character {
		static var default: SFSymbol { SFSymbol(rawValue: "character") }
		static var ar: SFSymbol { SFSymbol(rawValue: "character.ar") }
		// all other localizations available for "character" only
	}
}

let defaultCharacterImage = UIImage(systemSymbol: .Character.default) // UIImage
let arabicCharacterImage = UIImage(systemSymbol: .Character.ar) // UIImage

@fredpi @knothed what do you think?

Implements #87.

Following this suggestion by @StevenMagdy, one protocol per localization per availability is created.

The decision for the protocol names fell on hi and hi_v30 as these are shorter, easier to read and look better than HiLocalizable and HiLocalizableV30. What do you think?

Additionally, allSymbols was made into an SFSymbolSet which allows to localize all symbols (via allSymbols.hi) and which exposes allSymbolVariants containing every localization variant of every symbol.

The symbol documentations were adapted to match the actual exposed localizations: when deprecated symbols do not provide some localizations, but only their new versions do, these localizations are not in the documentation of the deprecated symbol to match its actual type. (example in the image)

As can be seen here, there will be a new version of SF Symbols: SF Symbols 4. Currently, the SF Symbols 4 app isn't available to download, but it probably won't last long until we learn all about it.

This issue can be used to collect ideas / track progress on the SF Symbols 4 support.

I believe SFSymbol is naturally a String backed struct, not enum.

public struct SFSymbol: RawRepresentable {
    
    public let rawValue: String
    
    public init(rawValue: String) {
        self.rawValue = rawValue
    }
}

When new symbols were added (like #53), user can do it on their own:

public extension SFSymbol {
    
    @available(iOS 14.0, macOS 11.0, tvOS 14.0, watchOS 7.0, *)
    static let sealFill = SFSymbol(rawValue: "seal.fill")
}

We can also break the massive SFSymbol.swift file into smaller fils (v1, v2, v2.1, deprecated).

I believe all existing functions won't be compromised. I can work on a pr with your permission.

SF Symbols v3 are now officially a thing and the corresponding app to browse them can be downloaded at https://developer.apple.com/sf-symbols/.

I quickly browsed the app and saw the following new features:

• There are new types in addition to Monochrome and Multicolor: Hierarchical & Palette. Fortunately, there is a file embedded in the app that tells us everything about the types for each symbol: layerset_availability.plist. I suggest we add this information to each's symbol documentation (similar to the localized versions).
• There's a new file symbol_categories.plist, but I suggest we just ignore it because there's no real value in adding the symbol category to each's symbol documentation IMO.
• According to Apple, there are > 600 new symbols. As all files that were used to generate the SFSafeSymbols code are still present in the app, it's probably not much work to create an update for these new versions.

SFSafeSymbols should include support for the new symbols introduced with iOS 14 and the other Apple operating systems.

Regarding the structuring I suggest the following design:

enum SFSymbol {
    @available(iOS 13...)
    enum v1 {
        case ...
    }

    @available(iOS 14...)
    enum v2 {
        case ...
    }
}

The SFSymbols 2 app required for parsing the symbol catalog isn't available yet, so I will look into this as soon as the app is available.

This PR adds support for layerset documentation which I stated as a goal for the v3 release (https://github.com/piknotech/SFSafeSymbols/issues/75).

I also updated the whole documentation style to better align with the way documentation is rendered in Xcode 13.

With the new documentation style, an exemplary symbol documentation now looks as follows:

Notably, when the user types the symbol name, they will now only see the documentation summary in the editor, i. e. the symbol preview. It might be suitable to add a note whether localizations or layersets are available. What do you think? @StevenMagdy @knothed

Simple summary:

Extended summary:

In this PR, I shortened the availability descriptions of localizations and layerset iOS 15.0, macOS ..., tvOS ..., watchOS ... to just iOS 15.0. With this, some information is removed, but I think that's okay for the sake of better readability.

@StevenMagdy I noticed that there are still some TODOs in the Symbols Generator project. Are those still relevant? If true, it would be better to track them in a GitHub issue instead of the code. Would you mind removing the TODOs and creating GitHub issues if needed? You may use this branch and PR; I won't commit further until you reviewed and commented the PR.

Also I think that the behavior introduced by the use of the localizationsOfAllVersions(of:) is incorrect: E. g., the legacy a is described as offering multiple localizations, but Apple only guarantees that those are available for the successor (character). Therefore, providing the same localization information for both the legacy and the current symbol name isn't correct, right? If you agree, would you mind changing this behavior?

This looks like a great and useful project. I'm going to try to use it in a personal project.

Looking ahead, though, I can see myself making my own custom additions to SF Symbols. I haven't tried this yet, but Apple documents how you would do this. Does SFSafeSymbols already give us a way to extend its support to our own custom additions?

Hi, I'm using SFSafeSymbols in my new project, but I get +100 Warnings in my log that several names were deprecated / changed in iOS 14.

Is there a way to get a release that's for iOS 14+ ? I installed through CocoaPods btw.

Thanks in advance

I just noticed a strange behavior. In SwiftUILabelExtension, the protocol StringProtocol is always matched to String instead of LocalizedStringKey if you write a string literal in your code. This is inconsistent with other SwiftUI native methods. For example:

// Native SwiftUI:
Text("some text")                      // inferred as LocalizedStringKey
Label("some text", systemImage: "...") // inferred as LocalizedStringKey
    .navigationBarTitle("some text")   // inferred as LocalizedStringKey

// SwiftUILabelExtension:
Label("some text", systemSymbol: .xxx) // hmm... inferred as String... 🤔

So I have to do the following to ensure the text is being localized correctly:

Label("some text" as LocalizedStringKey, systemSymbol: .xxx) // 🤔

I checked the implementation of SwiftUILabelExtension and it seems to be defined in the same way as in SwiftUI's native methods, but I don't know why the compiler doesn't give priority to matching LocalizedStringKey.

public extension Label where Title == Text, Icon == Image {
    
    /// Creates a label with a system symbol image and a title generated from a
    /// localized string.
    ///
    /// - Parameter systemSymbol: The `SFSymbol` describing this image.
    init(_ titleKey: LocalizedStringKey, systemSymbol: SFSymbol) {
        self.init(titleKey, systemImage: systemSymbol.rawValue)
    }
    
    /// Creates a label with a system symbol image and a title generated from a
    /// string.
    ///
    /// - Parameter systemSymbol: The `SFSymbol` describing this image.
    init<S>(_ title: S, systemSymbol: SFSymbol) where S : StringProtocol {
        // 🤔 always goes here with S==String...
        self.init(title, systemImage: systemSymbol.rawValue)
    }
}

I suggest to check if we can find a better way to define the initializer signatures. Because this inconsistent behavior can easily lead to localization bugs, and it is less easy to be found if the app is not fully tested.

This PR improves the package specs (Package.swift and SFSafeSymbols.podspec):

• General: Lower the library requirements to 2016 platforms (iOS 10.0, macOS 10.12, tvOS 10.0, watchOS 3.0).
• Package.swift: Raise the minimum Swift version to 5.3 to match SFSafeSymbols.podspec.
• Package.swift: Remove the library type (static/dynamic) which lets SPM picks it automatically (recommended by Apple). Tested successfully on the repo provided in #61.
• SFSafeSymbols.podspec: Add support for swift 5.4 and 5.5.
• SFSafeSymbols.podspec: Remove static_framework = true. Fixes #78.

In the release documentation, a step should be added that describes the need for a locally run pod spec lint before the start of the release. While the lint is run on a CI, different issues may occur on a local machine – for example: the watchOS simulator issues that @StevenMagdy fixed for Bitrise with this code:

xcrun simctl delete all;
phoneID=$(xcrun simctl create "iPhone 14" com.apple.CoreSimulator.SimDeviceType.iPhone-14);
watchID=$(xcrun simctl create "Apple Watch SE (40mm) (2nd generation)" com.apple.CoreSimulator.SimDeviceType.Apple-Watch-SE-44mm-2nd-generation);
tvID=$(xcrun simctl create "Apple TV" com.apple.CoreSimulator.SimDeviceType.Apple-TV-1080p);
xcrun simctl pair $watchID $phoneID;

This workaround may also be added to the documentation.

If we don't add this step to the release instructions, an issue may occur with a version having been released on Github, but the core contributor that released it being unable to push to CocoaPods.

Hi,

It would be helpful to add the symbol categories from the symbol.categories.plist file in SF Symbols.app to SFSymbol class to make sorting / filtering images in a view easier.