Merge pull request #12 from dkyowell/development

v0.2.5.2

Documentation/Changelog.md

@@ -1,8 +1,18 @@
 #  Changelog
 
+## v0.2.5.2
+* Breaking Change: In VStack, VGrid, and Columns the wrapping: parameter is renamed to wrap:.
+* Added .none and .wrap to truncationMode(:).
+* Changed Text: will not truncate unless truncationMode .tail is set.
+* Changed Text: will not wrap unless truncationMode .wrap is set.
+* Changed Table: removed page number from pageHeader and pageFooter blocks
+* Enhanced `PageNumberReader` with ability to report total pages
+* Fixed Text wrap in VStack
+* Fixes various layout issues
+
 ## v0.2.5.1
-* Peformance improvment for Text
-* Breaking Change: In VStack, VGrid, and Columns the pageWrap: parameter is renamed to wrapping:.
+* Performance improvment for Text
+* Breaking Change: In VStack, VGrid, and Columns the pageWrap: parameter is renamed to wrapContents:.
 * Various fixes
 * Moved Examples out of Sources directory
 

Documentation/Documentation.md

@@ -32,11 +32,12 @@ let data = Document().render()
 ```
 
 ## Multipage Components 
-`VStack`, `VGrid`, and `Columns` are components that can allow their content to start a new column or page by setting the `wrapping` parameter to true.
+`VStack`, `VGrid`, and `Columns` are components that can allow their content to start a new column or page by setting the `wrap` parameter to true.
 
 ```swift
-Columns(count: 2, spacing: 36, wrapping: true) {
+Columns(count: 2, spacing: 36, wrap: true) {
   Text("Four score and seventy years ago...")
+        .truncationMode(.wrap)
 }
 ```
 Note: `.flex` spacing does not work within a page wrap block. 
@@ -46,26 +47,27 @@ Page headers and footers can be expressed simply by surrounding a page wrap bloc
 ```swift
 VStack {
   Text("This text will repeat at the top of each page.")
-  Columns(count: 2, spacing: 36, wrapping: true) {
+  Columns(count: 2, spacing: 36, wrap: true) {
     Text("Four score and seventy years ago...")
+        .truncationMode(.wrap)
   }
   Text("This text will repeat at the bottom of each page.")
 }
 ```
 You are not limited to page headers and footers, you could change the `VStack` to an `HStack` in the preceeding example and have a page "leader" and page "trailer". 
 ### Page Numbers
-`PageNumberReader` is a component that provides the current page number for either printing, or adjusting rendered content according to the page number. Here, the page number is printed as a page header, but is supressed on the first page.
+`PageNumberReader` is a component that provides the current page number and optionally the total page count. Computing the page count is optional because it will roughly double the amount of time required to generate a PDF. Here, the page number is printed as a page header, but is supressed on the first page.
 
 ```swift
 VStack {
-  PageNumberReader { pageNo in
+  PageNumberReader(computePageCount: true) { proxy in
     if pageNo > 0 {
-      Text("Page \(pageNo)")
+      Text("Page \(proxy.pageNo) of \(proxy.pageCount)")
         .padding(.horizontal, .max)
         .padding(.bottom, 36)
     }
   }
-  Columns(count: 2, spacing: 36, wrapping: true) {
+  Columns(count: 2, spacing: 36, wrap: true) {
     Text(...)
   }
 }
@@ -167,12 +169,12 @@ You can write your own re-usable composite blocks using any of PDFBlocks' built
 * opacity
 * overlay
 * padding - Padding can be specified as `.max`. So, instead of `.frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)`, you can use         `.padding(bottom: .max, trailing: .max)`.
-
 * proportionalFrame*
 * rotationEffect
 * stroke
 * textFill* 
 * textStroke*
+* truncationMode
 * scaleEffect
 
 ## Issues

Documentation/Roadmap.md

@@ -10,7 +10,6 @@ The following is a list of items that could be added.
 * Clickable regions within documents.
 * Grids: grid layout is limited at present. I would welcome feedback as to what layout support would be useful.
 * Justified `Text`. This could be done poorly easily. Using TextKit and hyphenation would give a better implementation. It seems that NSAttributedString has some support for hyphenation. Need to exlore this as it would be an easier implementation than TextKit.
-* Enhance `PageNumberReader` to provide total pages. This will require a pre-pass of an entire document.
 * Barcodes. This is probably beyond the scope of this project and should be done with another library and used in PDFBlocks as an image.
 * Charts. This is probably beyond the scope of this project and should be done with another library and used in PDFBlocks as an image.
 

Documentation/example-columns.md

@@ -17,8 +17,9 @@ struct ExampleColumns: Block {
             Text("Martin Luther King, Jr.")
                 .fontSize(18)
                 .padding(.bottom, 24)
-            Columns(count: 3, spacing: 18, pageWrap: true) {
+            Columns(count: 3, spacing: 18, wrap: true) {
                 Text(speech)
+                    .truncationMode(.wrap)
                     .fontSize(10)
                     .kerning(-0.25)
             }
@@ -27,3 +28,6 @@ struct ExampleColumns: Block {
     }
 }
 ```
+
+
+The `wrap: true` parameter within `Columns(count: 3, spacing: 18, wrap: true)` indicates that `Columns` should start a new page when its contents overflow the space provided. The modifier `.truncationMode(.wrap)` indicates that `Text(speech)` should wrap its contents to a new column when necessary.  

Documentation/example-report.md

@@ -35,18 +35,18 @@ struct ExampleReport: Block {
                     .bold()
                     .padding(.leading, .max)
             }
-        } pageHeader: { pageNo in
-            HStack(spacing: .flex) {
-                Text("Donor Report")
-                PageNumberReader { pageNo in
-                    Text("Page \(pageNo)")
+        } pageHeader: { 
+            PageNumberReader { proxy in
+                HStack(spacing: .flex) {
+                    Text("Donor Report")
+                    Text("Page \(proxy.pageNo)")
+                }
+                .fontSize(12)
+                .bold()
+                .padding(.bottom, 12)
+                if pageNo > 1 {
+                    TableColumnTitles()
                 }
-            }
-            .fontSize(12)
-            .bold()
-            .padding(.bottom, 12)
-            if pageNo > 1 {
-                TableColumnTitles()
             }
         }
         .font(.system(size: 8))

Documentation/example-stacks.md

@@ -13,6 +13,7 @@ struct ExampleStacks: Block {
             VStack(spacing: .flex) {
                 Columns(count: 2, spacing: 36) {
                     Text(poem)
+                        .truncationMode(.wrap)
                         .fontSize(30)
                 }
                 HStack(spacing: .flex) {
@@ -23,6 +24,7 @@ struct ExampleStacks: Block {
                 }
                 Columns(count: 3, spacing: 18) {
                     Text(poem)
+                        .truncationMode(.wrap)
                         .fontSize(24)
                         .opacity(0.80)
                 }
@@ -34,6 +36,7 @@ struct ExampleStacks: Block {
                 }
                 Columns(count: 4, spacing: 12) {
                     Text(poem)
+                        .truncationMode(.wrap)
                         .fontSize(18)
                         .opacity(0.60)
                 }

Examples/Example+AttributedString.swift

@@ -0,0 +1,33 @@
+/**
+ *  PDF Blocks
+ *  Copyright (c) David Yowell 2024
+ *  MIT license, see LICENSE file for details
+ */
+
+import Foundation
+import PDFBlocks
+import PDFKit
+
+private struct Document: Block {
+    let text: AttributedString = {
+        var result: AttributedString = "One fish.\nTwo fish.\nRed fish.\nBlue fish."
+        if let range = result.range(of: "Blue") {
+            result[range].foregroundColor = .systemBlue
+        }
+        if let range = result.range(of: "Red") {
+            result[range].foregroundColor = .systemRed
+        }
+        return result
+    }()
+
+    var body: some Block {
+        Text(text)
+            .fontSize(64)
+            .fontDesign(.serif)
+            .fontWeight(.semibold)
+    }
+}
+
+#Preview {
+    previewForDocument(Document())
+}

Examples/Example+Columns.swift

@@ -8,68 +8,50 @@ import Foundation
 import PDFBlocks
 import PDFKit
 
-struct ExampleColumns: Block {
-    var body: some Block {
-        VStack(wrapping: true) {
-            Text("I Have a Dream")
-                .italic()
-                .fontSize(36)
-            Text("Martin Luther King, Jr.")
-                .fontSize(18)
-                .padding(.bottom, 24)
-            Columns(count: 3, spacing: 18, wrapping: true) {
-                Text(speech)
-                    .kerning(-0.25)
+public struct ExampleColumns2: Block {
+    let poem = "That time of year thou mayest in me behold, when yellow leaves or none or few do hang upon these boughs which shake against the cold, bare ruined choirs where late the sweet birds sang."
+    public init() {}
+
+    public var body: some Block {
+        Page(size: .letter, margins: .in(1)) {
+            VStack(spacing: .flex) {
+                Columns(count: 2, spacing: 36) {
+                    Text(poem)
+                        .truncationMode(.wrap)
+                        .fontSize(30)
+                }
+                HStack(spacing: .flex) {
+                    Repeat(count: 18) {
+                        Image(.init(systemName: "rhombus.fill"))
+                            .frame(width: 6)
+                    }
+                }
+                Columns(count: 3, spacing: 18) {
+                    Text(poem)
+                        .truncationMode(.wrap)
+                        .fontSize(24)
+                        .opacity(0.80)
+                }
+                HStack(spacing: .flex) {
+                    Repeat(count: 18) {
+                        Image(.init(systemName: "rhombus.fill"))
+                            .frame(width: 6)
+                    }
+                }
+                Columns(count: 4, spacing: 12) {
+                    Text(poem)
+                        .truncationMode(.wrap)
+                        .fontSize(18)
+                        .opacity(0.60)
+                }
             }
         }
+        .italic()
         .fontDesign(.serif)
-        .fontSize(10)
+        .border(Color.black, width: 8)
     }
 }
 
 #Preview {
-    previewForDocument(ExampleColumns())
+    previewForDocument(ExampleColumns2())
 }
-
-private let speech =
-    """
-    Five score years ago, a great American, in whose symbolic shadow we stand today, signed the Emancipation Proclamation. This momentous decree came as a great beacon light of hope to millions of Negro slaves  who had been seared in the flames of withering injustice. It came as a joyous daybreak to end the long night of their captivity.
-
-    But one hundred years later, the Negro still is not free. One hundred years later, the life of the Negro is still sadly crippled by the manacles of segregation and the chains of discrimination. One hundred years later, the Negro lives on a lonely island of poverty in the midst of a vast ocean of material prosperity. One hundred years later, the Negro is still languished in the corners of American society and finds himself in exile in his own land. And so we’ve come here today to dramatize a shameful condition.
-
-    In a sense we’ve come to our nation’s capital to cash a check. When the architects of our republic wrote the magnificent words of the Constitution and the Declaration of Independence, they were signing a promissory note to which every American was to fall heir. This note was a promise that all men, yes, black men as well as white men, would be guaranteed the unalienable rights of life, liberty, and the pursuit of happiness. It is obvious today that America has defaulted on this promissory note insofar as her citizens of color are concerned. Instead of honoring this sacred obligation, America has given the Negro people a bad check, a check which has come back marked insufficient funds.
-
-    But we refuse to believe that the bank of justice is bankrupt. We refuse to believe that there are insufficient funds in the great vaults of opportunity of this nation. And so we’ve come to cash this check, a check that will give us upon demand the riches of freedom and the security of justice.
-
-    We have also come to this hallowed spot to remind America of the fierce urgency of now. This is no time to engage in the luxury of cooling off or to take the tranquilizing drug of gradualism. Now is the time to make real the promises of democracy. Now is the time to rise from the dark and desolate valley of segregation to the sunlit path of racial justice. Now is the time to lift our nation from the quicksands of racial injustice to the solid rock of brotherhood. Now is the time to make justice a reality for all of God’s children.
-
-    It would be fatal for the nation to overlook the urgency of the moment. This sweltering summer of the Negro’s legitimate discontent will not pass until there is an invigorating autumn of freedom and equality. 1963 is not an end, but a beginning. And those who hope that the Negro needed to blow off steam and will now be content will have a rude awakening if the nation returns to business as usual. There will be neither rest nor tranquility in America until the Negro is granted his citizenship rights. The whirlwinds of revolt will continue to shake the foundations of our nation until the bright day of justice emerges.
-
-    But there is something that I must say to my people, who stand on the warm threshold which leads into the palace of justice: in the process of gaining our rightful place, we must not be guilty of wrongful deeds. Let us not seek to satisfy our thirst for freedom by drinking from the cup of bitterness and hatred. We must forever conduct our struggle on the high plane of dignity and discipline. We must not allow our creative protest to degenerate into physical violence. Again and again, we must rise to the majestic heights of meeting physical force with soul force. The marvelous new militancy which has engulfed the Negro community must not lead us to a distrust of all white people, for many of our white brothers, as evidenced by their presence here today, have come to realize that their destiny is tied up with our destiny, and they have come to realize that their freedom is inextricably bound to our freedom. We cannot walk alone.
-
-    And as we walk, we must make the pledge that we shall always march ahead. We cannot turn back. There are those who are asking the devotees of civil rights, “When will you be satisfied?” We can never be satisfied as long as the Negro is the victim of the unspeakable horrors of police brutality. We can never be satisfied as long as our bodies, heavy with the fatigue of travel, cannot gain lodging in the motels of the highways and the hotels of the cities. We cannot be satisfied as long as the Negro’s basic mobility is from a smaller ghetto to a larger one. We can never be satisfied as long as our children are stripped of their selfhood and robbed of their dignity by signs stating for whites only. We cannot be satisfied as long as a Negro in Mississippi cannot vote and a Negro in New York believes he has nothing for which to vote. No, no, we are not satisfied and we will not be satisfied until justice rolls down like waters and righteousness like a mighty stream.
-
-    I am not unmindful that some of you have come here out of great trials and tribulations. Some of you have come fresh from narrow jail cells. Some of you have come from areas where your quest for freedom left you battered by the storms of persecution and staggered by the winds of police brutality. You have been the veterans of creative suffering. Continue to work with the faith that unearned suffering is redemptive. Go back to Mississippi, go back to Alabama, go back to South Carolina, go back to Georgia, go back to Louisiana, go back to the slums and ghettos of our northern cities, knowing that somehow this situation can and will be changed. Let us not wallow in the valley of despair.
-
-    I say to you today, my friends, so even though we face the difficulties of today and tomorrow, I still have a dream. It is a dream deeply rooted in the American dream.
-
-    I have a dream that one day this nation will rise up and live out the true meaning of its creed: “We hold these truths to be self-evident, that all men are created equal.”
-
-    I have a dream that one day on the red hills of Georgia, the sons of former slaves and the sons of former slave owners will be able to sit down together at the table of brotherhood.
-
-    I have a dream that one day even the state of Mississippi, a state sweltering with the heat of injustice, sweltering with the heat of oppression, will be transformed into an oasis of freedom and justice.
-
-    I have a dream that my four little children will one day live in a nation where they will not be judged by the color of their skin but by the content of their character. I have a dream today.
-
-    I have a dream that one day down in Alabama, with its vicious racists, with its governor having his lips dripping with the words of “interposition” and “nullification”, one day right there in Alabama little black boys and black girls will be able to join hands with little white boys and white girls as sisters and brothers. I have a dream today.
-
-    I have a dream that one day every valley shall be exalted, every hill and mountain shall be made low, the rough places will be made plain, and the crooked places will be made straight, and the glory of the Lord shall be revealed, and all flesh shall see it together.
-
-    This is our hope. This is the faith that I go back to the South with. With this faith we will be able to hew out of the mountain of despair a stone of hope. With this faith we will be able to transform the jangling discords of our nation into a beautiful symphony of brotherhood. With this faith we will be able to work together, to pray together, to struggle together, to go to jail together, to stand up for freedom together, knowing that we will be free one day.
-
-    This will be the day, this will be the day when all of God’s children will be able to sing with new meaning: “My country, ‘tis of thee, sweet land of liberty, of thee I sing. Land where my fathers died, land of the pilgrim’s pride, from every mountainside, let freedom ring!”
-
-    And if America is to be a great nation, this must become true. So let freedom ring from the prodigious hilltops of New Hampshire. Let freedom ring from the mighty mountains of New York. Let freedom ring from the heightening Alleghenies of Pennsylvania. Let freedom ring from the snow-capped Rockies of Colorado. Let freedom ring from the curvaceous slopes of California. But not only that: Let freedom ring from Stone Mountain of Georgia. Let freedom ring from Lookout Mountain of Tennessee. Let freedom ring from every hill and molehill of Mississippi. From every mountainside, let freedom ring.
-
-    And when this happens, and when we allow freedom ring, when we let it ring from every village and every hamlet, from every state and every city, we will be able to speed up that day when all of God’s children, black men and white men, Jews and Gentiles, Protestants and Catholics, will be able to join hands and sing in the words of the old Negro spiritual: “Free at last! Free at last! Thank God Almighty, we are free at last!”
-    """