Commit `032cfe34d5`

032cfe34d52200909d6ebcdc67c28898457c8710

parent: dedfbafd51

Unsigned

cmc <hello@cleberg.net> · 2026-08-31 17:38 UTC

Document OrgSwiftUI

Layout: unified · split

ARCHITECTURE.md +45 −7

		@@ -4,17 +4,27 @@ OrgSwift parses org into an element tree and renders that tree. Parsing happens
4	4	output format is a walk over the result.
5	5
6	6	```
7		Sources/OrgSwift/
	7	Sources/OrgSwift/ Foundation only
8	8	AST/
9	9	OrgDocument.swift the element tree
10	10	OrgParser.swift source → OrgDocument (blocks)
11	11	OrgInlineParser.swift text → [OrgObject] (inlines)
12	12	OrgHTMLTreeRenderer.swift OrgDocument → HTML
13	13	OrgAttributedStringRenderer.swift [OrgObject] → AttributedString
	14	OrgFootnotes.swift document-wide numbering, shared by renderers
	15	OrgURLResolver.swift typed target → safe URL, shared by renderers
14	16	OrgRenderer.swift the public entry point, plus OrgRenderOptions
15	17	Escaping.swift, Links.swift, … shared helpers: escaping, URL sanitising and
16	18	repository-relative resolution, line predicates
17	19	Skeleton.swift the HTML → semantic-skeleton reduction used by tests
	20
	21	Sources/OrgSwiftUI/ depends on OrgSwift
	22	OrgView.swift the public entry point
	23	OrgLayout.swift the display model
	24	OrgLayoutBuilder.swift OrgDocument → OrgLayout
	25	OrgInlineStyler.swift [OrgObject] → styled AttributedString
	26	OrgBlockView.swift, OrgListView.swift, OrgTableView.swift
	27	OrgCodeStyler.swift the app's syntax highlighter, as a protocol
18	28	```
19	29
20	30	`OrgRenderer.renderToHTML` is a thin façade over `OrgParser.parse` + `OrgHTMLTreeRenderer`.
		@@ -29,7 +39,12 @@ format would have meant re-deriving the parse rather than reusing it.
29	39
30	40	With a tree, `OrgAttributedStringRenderer` is roughly 140 lines and shares the parse
31	41	entirely. It is Foundation-only — no SwiftUI — so it works server-side, in a CLI,
32		anywhere; a SwiftUI layer would sit on top of it for the inline runs inside each block.
	42	anywhere. `OrgSwiftUI` sits on top of it for the inline runs inside each block, and is a
	43	separate product so callers who want HTML never import SwiftUI.
	44
	45	Three renderers now share one parse, one URL resolver (`OrgURLResolver`) and one footnote
	46	numbering (`OrgFootnotes`), both `package`-scoped. That sharing is the point: a link that
	47	resolves in HTML resolves natively, and note 1 is note 1 in both.
33	48
34	49	The types mirror orgo's `model.rs` — `OrgElement`/`OrgObject` against orgo's
35	50	`Element`/`Object`, `OrgTableRow.{cells,rule}` against `TableRow::{Cells,Rule}`, the same
		@@ -70,10 +85,33 @@ text. orgo applies the `--` rule to both bracket kinds, requiring only that the
70	85	on activeness, so the new behaviour is the more correct one. It is asserted directly in
71	86	`joinsInactiveTimestampRanges`.
72	87
	88	## OrgSwiftUI
	89
	90	`OrgView(source, options:styler:)` renders org as native SwiftUI: selectable text, Dynamic
	91	Type, VoiceOver, and no web view.
	92
	93	The walk runs off `body`, in a `.task` keyed to the source, producing an `OrgLayout` the
	94	views then render as pure layout. Three things force that. Footnote numbering is sequential
	95	and document-wide, so it cannot happen in a `@ViewBuilder`. Syntax highlighting is expensive
	96	and must not re-run per layout pass. And SwiftUI re-initialises views freely, so `init` is
	97	not a safe place either.
	98
	99	Tables are the interesting part: `Grid`/`GridRow` with `.gridColumnAlignment()` set on the
	100	first row and inherited down, wrapped in a horizontal `ScrollView` for phone-width overflow.
	101	`OrgTable` already carried the rows, the rule position and the per-column alignments.
	102
	103	Syntax highlighting arrives through `OrgCodeStyler`, the native counterpart to
	104	`CodeHighlighter` — returning `AttributedString` where the other returns HTML. Keeping it a
	105	protocol is what lets the package stay dependency-free.
	106
	107	One behaviour deliberately differs from HTML. An image source that will not resolve to an
	108	absolute URL degrades to its alt text: HTML may emit a relative `src` for a document base
	109	URL to resolve, and a view has no base, so a relative source is unloadable.
	110
	111	Not covered natively: `#+BEGIN_EXPORT html` passes through verbatim in HTML and has nowhere
	112	to go in a view, so it renders as the literal block it is.
	113
73	114	## Next
74	115
75		A SwiftUI renderer belongs in a separate product depending on this one, so the parser and
76		HTML renderer stay Foundation-only and callers who want HTML never import SwiftUI. Tables are
77		the interesting part: `Grid`/`GridRow` with `.gridColumnAlignment()`, wrapped in a horizontal
78		`ScrollView` for phone-width overflow — the approach MarkdownUI uses. `OrgTable` already
79		carries the rows, the rule position, and the per-column alignments that needs.
	116	The corpus measures HTML only. Tree-level conformance would let `OrgLayout` be measured
	117	against the same goldens instead of only its own unit tests.

README.md +33 −2

		@@ -1,8 +1,11 @@
1	1	# OrgSwift
2	2
3	3	A dependency-free Swift library that renders a practical subset of
4		[org-mode](https://orgmode.org) to sanitized HTML. Pure Foundation — no
5		SwiftUI, WebKit, UIKit, or third-party packages.
	4	[org-mode](https://orgmode.org). Two products:
	5
	6	- `OrgSwift` — org to sanitized HTML or `AttributedString`. Pure Foundation,
	7	no SwiftUI, WebKit, UIKit, or third-party packages.
	8	- `OrgSwiftUI` — org to native SwiftUI views, no web view involved.
6	9
7	10	Originally extracted from the hand-rolled renderer in the Hutch iOS client so it
8	11	could be shared across apps, and since rebuilt around an element tree: org is
		@@ -58,6 +61,34 @@ let html = OrgRenderer.renderToHTML(
58	61	`./images/badge.svg` then resolves to
59	62	`https://git.sr.ht/~ccleberg/Hutch/blob/HEAD/images/badge.svg`.
60	63
	64	### Native SwiftUI
	65
	66	`OrgSwiftUI` renders the same parse as views rather than HTML — selectable text,
	67	Dynamic Type, and VoiceOver, without a `WKWebView`.
	68
	69	```swift
	70	import OrgSwiftUI
	71
	72	OrgView(orgSource, options: options)
	73	```
	74
	75	`OrgRenderOptions` means the same thing here, so links and images resolve exactly
	76	as they do in HTML. An image whose source will not resolve to an absolute URL
	77	shows its alt text instead: HTML can lean on a document base URL, a view cannot.
	78
	79	Syntax highlighting for `#+begin_src` blocks is the app's to supply, which is what
	80	keeps this package dependency-free:
	81
	82	```swift
	83	struct Highlighter: OrgCodeStyler {
	84	func highlighted(code: String, language: String?) -> AttributedString? {
	85	// nil means "show it as plain monospaced text"
	86	}
	87	}
	88
	89	OrgView(orgSource, options: options, styler: Highlighter())
	90	```
	91
61	92	### Title and heading level
62	93
63	94	Two presentation knobs, both defaulting to how Hutch rendered:

Commit 032cfe34d5

Commit `032cfe34d5`