From e8281a98f73c021244f1f042ee58ee4dc3b1fe74 Mon Sep 17 00:00:00 2001 From: Jeff Verkoeyen Date: Thu, 1 Aug 2024 14:54:37 -0400 Subject: [PATCH] Add a "How Slipstream works" article. --- .../Documentation.docc/Slipstream.md | 5 ++ .../Views/Architecture/HowSlipstreamWorks.md | 71 +++++++++++++++++++ .../Documentation.docc/Views/Catalog.md | 9 +++ .../Views/Fundamentals/Fundamentals.md | 4 -- .../TextInputAndOutput/TextInputAndOutput.md | 2 +- 5 files changed, 86 insertions(+), 5 deletions(-) create mode 100644 Sources/Slipstream/Documentation.docc/Views/Architecture/HowSlipstreamWorks.md create mode 100644 Sources/Slipstream/Documentation.docc/Views/Catalog.md diff --git a/Sources/Slipstream/Documentation.docc/Slipstream.md b/Sources/Slipstream/Documentation.docc/Slipstream.md index 4a076ea..2b2e786 100644 --- a/Sources/Slipstream/Documentation.docc/Slipstream.md +++ b/Sources/Slipstream/Documentation.docc/Slipstream.md @@ -52,9 +52,14 @@ print(try renderHTML(HelloWorld())) ### Views +- - - ### Rendering Views - ``renderHTML(_:)`` + +### Architecture + +- diff --git a/Sources/Slipstream/Documentation.docc/Views/Architecture/HowSlipstreamWorks.md b/Sources/Slipstream/Documentation.docc/Views/Architecture/HowSlipstreamWorks.md new file mode 100644 index 0000000..8db98bd --- /dev/null +++ b/Sources/Slipstream/Documentation.docc/Views/Architecture/HowSlipstreamWorks.md @@ -0,0 +1,71 @@ +# How Slipstream works + +A from the ground up explanation of Slipstream's architecture. + +Slipstream is designed to offer a SwiftUI-like approach to building HTML documents +that are compatible with [Tailwind CSS](http://tailwindcss.com). + +## Core Concepts + +### Result Builders + +Slipstream uses Swift [result builders](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0289-result-builders.md) +to enable the construction of HTML documents in a syntax similar to SwiftUI's. +Result builders encourage defining structural data in a hierarchical and declarative +manner, separating intent (what the site should look like) from implementation (how +it's turned into HTML). This separation of concerns allows you to focus on the +design and structure of your web pages without getting bogged down by the +intricacies of HTML generation. + +### View Protocol + +The primary type that Slipstream's result builders work with is the ``View`` protocol. +Like SwiftUI, a View represents a part of an HTML document that can be combined +with other View instances to create a website. The protocol defines a contract +that all views must adhere to, ensuring consistency in how views are constructed and +rendered as HTML. + +```swift +public protocol View { + associatedtype Content: View + @ViewBuilder var body: Self.Content { get } + + func render(_ container: Element) throws +} +``` + +The ``View/body`` property returns the content of the view, and in most cases, is +the only part of the View protocol that you need to implement. The ``ViewBuilder`` +attribute is what enables our use of the SwiftUI-like syntax in the body implementation. + +The ``View/render(_:)`` method, on the other hand, is responsible for converting the +view’s content into HTML elements. You'll only need to implement this method if you +need to generate new types of HTML. + +### W3C HTML Views + +Slipstream provides a catalog of standard [W3C HTML](https://html.spec.whatwg.org/multipage/) +View implementations that can be used to build your website. Visit the to +see the set of Views available in Slipstream. + +### Rendering a View as HTML + +The combination of result builders, the View protocol, and a ``Text`` view is all we +need to build a simple "Hello, world!" example: + +```swift +struct HelloWorld: View { + var body: some View { + Text("Hello, world!") + } +} + +print(try renderHTML(HelloWorld())) +``` + +In this example, the Text view is treated as a single "block" in HelloWorld's body. + +The ``renderHTML(_:)`` method creates a SwiftSoup Document object and then passes this +document to the HelloWorld's ``View/render(_:)`` method, which in turn calls Text's +`render(_:)` method, which appends the string to the Document object. + diff --git a/Sources/Slipstream/Documentation.docc/Views/Catalog.md b/Sources/Slipstream/Documentation.docc/Views/Catalog.md new file mode 100644 index 0000000..db8c9ed --- /dev/null +++ b/Sources/Slipstream/Documentation.docc/Views/Catalog.md @@ -0,0 +1,9 @@ +# Catalog + +Explore the various View implementations included in Slipstream. + +## Topics + +### Text Input and Output + +- ``Text`` diff --git a/Sources/Slipstream/Documentation.docc/Views/Fundamentals/Fundamentals.md b/Sources/Slipstream/Documentation.docc/Views/Fundamentals/Fundamentals.md index 3dbc3a2..b766cbf 100644 --- a/Sources/Slipstream/Documentation.docc/Views/Fundamentals/Fundamentals.md +++ b/Sources/Slipstream/Documentation.docc/Views/Fundamentals/Fundamentals.md @@ -13,7 +13,3 @@ conforms to the ``View`` protocol can act as a view in your website. - ``View`` - ``ViewBuilder`` - -### W3C views - -- ``Text`` diff --git a/Sources/Slipstream/Documentation.docc/Views/TextInputAndOutput/TextInputAndOutput.md b/Sources/Slipstream/Documentation.docc/Views/TextInputAndOutput/TextInputAndOutput.md index 98dff7a..fa12bde 100644 --- a/Sources/Slipstream/Documentation.docc/Views/TextInputAndOutput/TextInputAndOutput.md +++ b/Sources/Slipstream/Documentation.docc/Views/TextInputAndOutput/TextInputAndOutput.md @@ -1,6 +1,6 @@ # Text input and output -Display text. +Add text to your document. To display read-only text, use the built-in ``Text`` view.