Skip to content

Commit e61819a

Browse files
aspauldingcodeaspauldingcode
committed
also place wiki in here but yk
1 parent f9c885f commit e61819a

1 file changed

Lines changed: 351 additions & 0 deletions

File tree

‎wiki.adoc‎

Lines changed: 351 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,351 @@
1+
= TintedThemingSwift
2+
:toc: left
3+
:toclevels: 3
4+
:sectlinks:
5+
:sectanchors:
6+
:source-highlighter: rouge
7+
:icons: font
8+
9+
A comprehensive Swift package for working with Base16 and Base24 color themes from the TintedTheming/Schemes project.
10+
11+
== Quick Start
12+
13+
[source,swift]
14+
----
15+
import TintedThemingSwift
16+
17+
let loader = TintedThemesLoader.shared
18+
let themes = try await loader.loadAllBase16Themes()
19+
----
20+
21+
== Core Types
22+
23+
=== Base16Theme
24+
25+
A struct representing a Base16 color theme with 16 colors following the Base16 specification.
26+
27+
==== Properties
28+
29+
[source,swift]
30+
----
31+
public let id: UUID // Unique identifier
32+
public let name: String // Theme name
33+
public let author: String // Theme author
34+
public let variant: String // "light" or "dark"
35+
36+
// Base16 color palette (hex strings without #)
37+
public let base00: String // Default Background
38+
public let base01: String // Lighter Background
39+
public let base02: String // Selection Background
40+
public let base03: String // Comments, Invisibles
41+
public let base04: String // Dark Foreground
42+
public let base05: String // Default Foreground
43+
public let base06: String // Light Foreground
44+
public let base07: String // Light Background
45+
public let base08: String // Variables, Red
46+
public let base09: String // Integers, Orange
47+
public let base0A: String // Classes, Yellow
48+
public let base0B: String // Strings, Green
49+
public let base0C: String // Support, Cyan
50+
public let base0D: String // Functions, Blue
51+
public let base0E: String // Keywords, Purple
52+
public let base0F: String // Deprecated, Brown
53+
----
54+
55+
==== Methods
56+
57+
[source,swift]
58+
----
59+
public init(name: String, author: String, variant: String = "dark",
60+
base00: String, base01: String, ..., base0F: String)
61+
62+
public var allColors: [String] // All 16 colors as array
63+
public func color(at index: Int) -> String? // Get color by index (0-15)
64+
public var semanticColors: [String: String] // Semantic color mapping
65+
public var isLight: Bool // True if light theme
66+
public var isDark: Bool // True if dark theme
67+
----
68+
69+
==== Default Themes
70+
71+
[source,swift]
72+
----
73+
static let defaultDark: Base16Theme // Built-in dark theme
74+
static let defaultLight: Base16Theme // Built-in light theme
75+
----
76+
77+
=== Base24Theme
78+
79+
A struct representing a Base24 color theme with 24 colors, extending Base16 with 8 additional colors.
80+
81+
==== Properties
82+
83+
[source,swift]
84+
----
85+
public let id: UUID // Unique identifier
86+
public let name: String // Theme name
87+
public let author: String // Theme author
88+
89+
// Base16 colors (base00-base0F) - same as Base16Theme
90+
// Extended Base24 colors
91+
public let base10: String // Extended color 1
92+
public let base11: String // Extended color 2
93+
public let base12: String // Extended color 3
94+
public let base13: String // Extended color 4
95+
public let base14: String // Extended color 5
96+
public let base15: String // Extended color 6
97+
public let base16: String // Extended color 7
98+
public let base17: String // Extended color 8
99+
----
100+
101+
==== Methods
102+
103+
[source,swift]
104+
----
105+
public init(name: String, author: String,
106+
base00: String, ..., base17: String)
107+
108+
public var allColors: [String] // All 24 colors as array
109+
public func color(at index: Int) -> String? // Get color by index (0-23)
110+
public var asBase16Theme: Base16Theme // Convert to Base16 theme
111+
----
112+
113+
== Theme Loader
114+
115+
=== TintedThemesLoader
116+
117+
Main class for loading themes from the tinted-theming/schemes repository with caching support.
118+
119+
==== Singleton Access
120+
121+
[source,swift]
122+
----
123+
public static let shared: TintedThemesLoader
124+
----
125+
126+
==== Base16 Theme Loading
127+
128+
[source,swift]
129+
----
130+
// Load all Base16 themes (uses cache when available)
131+
public func loadAllBase16Themes() async throws -> [Base16Theme]
132+
133+
// Force refresh from network, ignoring cache
134+
public func refreshThemes() async throws -> [Base16Theme]
135+
136+
// Get cached themes immediately (no network call)
137+
public func getCachedThemes() -> [Base16Theme]
138+
139+
// Load specific theme by name
140+
public func loadBase16Theme(named name: String) async throws -> Base16Theme?
141+
142+
// Load multiple themes by name (concurrent)
143+
public func loadBase16Themes(named names: [String]) async -> [Base16Theme]
144+
145+
// Load only light variant themes
146+
public func loadLightThemes() async throws -> [Base16Theme]
147+
148+
// Load only dark variant themes
149+
public func loadDarkThemes() async throws -> [Base16Theme]
150+
----
151+
152+
==== Base24 Theme Loading
153+
154+
[source,swift]
155+
----
156+
// Load all Base24 themes
157+
public func loadAllBase24Themes() async throws -> [Base24Theme]
158+
159+
// Load specific Base24 theme by name
160+
public func loadBase24Theme(named name: String) async throws -> Base24Theme?
161+
162+
// Load multiple Base24 themes by name (concurrent)
163+
public func loadBase24Themes(named names: [String]) async -> [Base24Theme]
164+
----
165+
166+
== Color Extensions
167+
168+
=== SwiftUI Integration
169+
170+
Available on iOS 14.0+, macOS 11.0+, watchOS 7.0+, tvOS 14.0+
171+
172+
==== Color from Hex
173+
174+
[source,swift]
175+
----
176+
Color(hex: String) // Create Color from hex string
177+
----
178+
179+
==== Base16Theme SwiftUI Colors
180+
181+
[source,swift]
182+
----
183+
// Individual base colors
184+
var swiftUIBase00Color: Color // Through swiftUIBase0FColor
185+
186+
// Semantic color aliases
187+
var swiftUIBackgroundColor: Color // base00
188+
var swiftUIForegroundColor: Color // base05
189+
var swiftUISelectionColor: Color // base02
190+
var swiftUICommentColor: Color // base03
191+
var swiftUIErrorColor: Color // base08
192+
var swiftUIWarningColor: Color // base09
193+
var swiftUISuccessColor: Color // base0B
194+
var swiftUILinkColor: Color // base0D
195+
----
196+
197+
==== Base24Theme SwiftUI Colors
198+
199+
[source,swift]
200+
----
201+
// All Base16 colors plus extended colors
202+
var swiftUIBase10Color: Color // Through swiftUIBase17Color
203+
// Same semantic aliases as Base16Theme
204+
----
205+
206+
=== UIKit Integration
207+
208+
Available on iOS 13.0+, tvOS 13.0+, watchOS 6.0+
209+
210+
==== UIColor from Hex
211+
212+
[source,swift]
213+
----
214+
UIColor(hex: String) // Create UIColor from hex string
215+
----
216+
217+
==== Base16Theme UIKit Colors
218+
219+
[source,swift]
220+
----
221+
// Individual base colors
222+
var uiBase00Color: UIColor // Through uiBase0FColor
223+
224+
// Semantic color aliases
225+
var uiBackgroundColor: UIColor // base00
226+
var uiForegroundColor: UIColor // base05
227+
var uiSelectionColor: UIColor // base02
228+
var uiCommentColor: UIColor // base03
229+
var uiErrorColor: UIColor // base08
230+
var uiWarningColor: UIColor // base09
231+
var uiSuccessColor: UIColor // base0B
232+
var uiLinkColor: UIColor // base0D
233+
----
234+
235+
=== AppKit Integration
236+
237+
Available on macOS 10.15+
238+
239+
==== NSColor from Hex
240+
241+
[source,swift]
242+
----
243+
NSColor(hex: String) // Create NSColor from hex string
244+
----
245+
246+
==== Base16Theme AppKit Colors
247+
248+
[source,swift]
249+
----
250+
// Individual base colors
251+
var nsBase00Color: NSColor // Through nsBase0FColor
252+
253+
// Semantic color aliases
254+
var nsBackgroundColor: NSColor // base00
255+
var nsForegroundColor: NSColor // base05
256+
var nsSelectionColor: NSColor // base02
257+
var nsCommentColor: NSColor // base03
258+
var nsErrorColor: NSColor // base08
259+
var nsWarningColor: NSColor // base09
260+
var nsSuccessColor: NSColor // base0B
261+
var nsLinkColor: NSColor // base0D
262+
----
263+
264+
== Usage Examples
265+
266+
=== Basic Theme Loading
267+
268+
[source,swift]
269+
----
270+
// Load all themes
271+
let themes = try await TintedThemesLoader.shared.loadAllBase16Themes()
272+
273+
// Load specific theme
274+
let theme = try await TintedThemesLoader.shared.loadBase16Theme(named: "monokai")
275+
276+
// Use cached themes
277+
let cachedThemes = TintedThemesLoader.shared.getCachedThemes()
278+
----
279+
280+
=== SwiftUI Integration Example
281+
282+
[source,swift]
283+
----
284+
struct ContentView: View {
285+
let theme = Base16Theme.defaultDark
286+
287+
var body: some View {
288+
VStack {
289+
Text("Hello, World!")
290+
.foregroundColor(theme.swiftUIForegroundColor)
291+
}
292+
.background(theme.swiftUIBackgroundColor)
293+
}
294+
}
295+
----
296+
297+
=== UIKit Integration Example
298+
299+
[source,swift]
300+
----
301+
class ViewController: UIViewController {
302+
let theme = Base16Theme.defaultDark
303+
304+
override func viewDidLoad() {
305+
super.viewDidLoad()
306+
view.backgroundColor = theme.uiBackgroundColor
307+
308+
let label = UILabel()
309+
label.textColor = theme.uiForegroundColor
310+
label.text = "Themed Label"
311+
}
312+
}
313+
----
314+
315+
== Protocol Conformance
316+
317+
* **Codable**: Both `Base16Theme` and `Base24Theme` can be encoded/decoded to/from JSON
318+
* **Identifiable**: Both themes have unique `id` properties
319+
* **Hashable**: Both themes can be used in Sets and as Dictionary keys
320+
* **Equatable**: Themes can be compared for equality based on name and author
321+
322+
The package provides comprehensive theming support with automatic caching, concurrent loading, and seamless integration with SwiftUI, UIKit, and AppKit color systems.
323+
324+
[NOTE]
325+
====
326+
This package is a Swift API implementation for the https://github.com/tinted-theming/schemes[TintedTheming/Schemes] project.
327+
====
328+
329+
== Installation
330+
331+
=== Swift Package Manager
332+
333+
. Open your project in Xcode
334+
. Go to File → Add Package Dependencies
335+
. Enter the repository URL:
336+
+
337+
[source]
338+
----
339+
https://github.com/aspauldingcode/TintedThemingSwift.git
340+
----
341+
342+
== Troubleshooting
343+
344+
[WARNING]
345+
====
346+
Ensure your deployment target meets the minimum requirements:
347+
- iOS 15.0+
348+
- macOS 12.0+
349+
- watchOS 8.0+
350+
- tvOS 15.0+
351+
====

0 commit comments

Comments
 (0)