Merge pull request #67 from touying-typ/refactor

Touying 0.5.0

README.md

@@ -2,7 +2,7 @@
 
 [Touying](https://github.com/touying-typ/touying) (投影 in chinese, /tóuyǐng/, meaning projection) is a powerful and efficient package for creating presentation slides in Typst. Partial code is inherited from [Polylux](https://github.com/andreasKroepelin/polylux). Therefore, many concepts and APIs remain consistent with Polylux.
 
-Touying provides an object-oriented programming (OOP) style syntax, allowing the simulation of "global variables" through a global singleton, which makes it easy to write themes for Touying. Touying does not rely on `counter` and `locate` to implement `#pause`, resulting in better performance.
+Touying provides automatically injected global configurations. Besides, Touying does not rely on `counter` and `locate` to implement `#pause`, resulting in better performance.
 
 If you like it, consider [giving a star on GitHub](https://github.com/touying-typ/touying). Touying is a community-driven project, feel free to suggest any ideas and contribute.
 
@@ -99,14 +99,10 @@ Before you begin, make sure you have installed the Typst environment. If not, yo
 To use Touying, you only need to include the following code in your document:
 
 ```typst
-#import "@preview/touying:0.4.2": *
+#import "@preview/touying:0.5.0": *
+#import themes.simple: *
 
-#let s = themes.simple.register(aspect-ratio: "16-9")
-#let (init, slides) = utils.methods(s)
-#show: init
-
-#let (slide, empty-slide) = utils.slides(s)
-#show: slides
+#show: simple-theme.with(aspect-ratio: "16-9")
 
 = Title
 
@@ -131,38 +127,20 @@ It's simple. Congratulations on creating your first Touying slide! 🎉
 In fact, Touying provides various styles for writing slides. For example, the above example uses first-level and second-level titles to create new slides. However, you can also use the `#slide[..]` format to access more powerful features provided by Touying.
 
 ```typst
-#import "@preview/touying:0.4.2": *
+#import "@preview/touying:0.5.0": *
+#import themes.university: *
 #import "@preview/cetz:0.2.2"
-#import "@preview/fletcher:0.4.4" as fletcher: node, edge
+#import "@preview/fletcher:0.5.1" as fletcher: node, edge
 #import "@preview/ctheorems:1.1.2": *
+#import "@preview/numbly:0.1.0": numbly
 
 // cetz and fletcher bindings for touying
 #let cetz-canvas = touying-reducer.with(reduce: cetz.canvas, cover: cetz.draw.hide.with(bounds: true))
 #let fletcher-diagram = touying-reducer.with(reduce: fletcher.diagram, cover: fletcher.hide)
 
-// Register university theme
-// You can replace it with other themes and it can still work normally
-#let s = themes.university.register(aspect-ratio: "16-9")
-
-// Set the numbering of section and subsection
-#let s = (s.methods.numbering)(self: s, section: "1.", "1.1")
-
-// Set the speaker notes configuration
-// #let s = (s.methods.show-notes-on-second-screen)(self: s, right)
-
-// Global information configuration
-#let s = (s.methods.info)(
-  self: s,
-  title: [Title],
-  subtitle: [Subtitle],
-  author: [Authors],
-  date: datetime.today(),
-  institution: [Institution],
-)
-
 // Pdfpc configuration
 // typst query --root . ./example.typ --field value --one "<pdfpc-file>" > ./example.pdfpc
-#let s = (s.methods.append-preamble)(self: s, pdfpc.config(
+#pdfpc.config(
   duration-minutes: 30,
   start-time: datetime(hour: 14, minute: 10, second: 0),
   end-time: datetime(hour: 14, minute: 40, second: 0),
@@ -176,7 +154,7 @@ In fact, Touying provides various styles for writing slides. For example, the ab
     alignment: "vertical",
     direction: "inward",
   ),
-))
+)
 
 // Theorems configuration by ctheorems
 #show: thmrules.with(qed-symbol: $square$)
@@ -191,15 +169,26 @@ In fact, Touying provides various styles for writing slides. For example, the ab
 #let example = thmplain("example", "Example").with(numbering: none)
 #let proof = thmproof("proof", "Proof")
 
-// Extract methods
-#let (init, slides, touying-outline, alert, speaker-note) = utils.methods(s)
-#show: init
+#show: university-theme.with(
+  aspect-ratio: "16-9",
+  // config-common(handout: true),
+  config-info(
+    title: [Title],
+    subtitle: [Subtitle],
+    author: [Authors],
+    date: datetime.today(),
+    institution: [Institution],
+    logo: emoji.school,
+  ),
+)
+
+#set heading(numbering: numbly("{1}.", default: "1.1"))
+
+#title-slide()
 
-#show strong: alert
+== Outline <touying:hidden>
 
-// Extract slide functions
-#let (slide, empty-slide) = utils.slides(s)
-#show: slides
+#components.adaptive-columns(outline(title: none, indent: 1em))
 
 = Animation
 
@@ -221,9 +210,9 @@ Meanwhile, #pause we can also use `#meanwhile` to #pause display other content s
 ]
 
 
-== Complex Animation - Mark-Style
+== Complex Animation
 
-At subslide #utils.touying-wrapper((self: none) => str(self.subslide)), we can
+At subslide #touying-fn-wrapper((self: none) => str(self.subslide)), we can
 
 use #uncover("2-")[`#uncover` function] for reserving space,
 
@@ -232,7 +221,7 @@ use #only("2-")[`#only` function] for not reserving space,
 #alternatives[call `#only` multiple times \u{2717}][use `#alternatives` function #sym.checkmark] for choosing one of the alternatives.
 
 
-== Complex Animation - Callback-Style
+== Callback Style Animation
 
 #slide(repeat: 3, self => [
   #let (uncover, only, alternatives) = utils.methods(self)
@@ -249,12 +238,12 @@ use #only("2-")[`#only` function] for not reserving space,
 
 == Math Equation Animation
 
-Touying equation with `pause`:
+Equation with `pause`:
 
-#touying-equation(`
+$
   f(x) &= pause x^2 + 2x + 1  \
-        &= pause (x + 1)^2  \
-`)
+       &= pause (x + 1)^2  \
+$
 
 #meanwhile
 
@@ -365,15 +354,13 @@ Fletcher Animation in Touying:
 #lorem(200)
 
 
-// appendix by freezing last-slide-number
-#let s = (s.methods.appendix)(self: s)
-#let (slide, empty-slide) = utils.slides(s)
+#show: appendix
+
+= Appendix
 
 == Appendix
 
-#slide[
-  Please pay attention to the current slide number.
-]
+Please pay attention to the current slide number.
 ```
 
 ![image](https://github.com/touying-typ/touying/assets/34951714/5ac2b11c-9e77-4389-ade6-682c9fc3e1fb)

changelog.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## v0.5.0
+
+This is a significant disruptive version update. Touying has removed many mistakes that resulted from incorrect decisions. We have redesigned numerous features. The goal of this version is to make Touying more user-friendly, more flexible, and more powerful.
+
+**Major changes include:**
+
+- Avoiding closures and OOP syntax, which makes Touying's configuration simpler and allows for the use of document comments to provide more auto-completion information for the slide function.
+  - The existing `#let slide(self: none, ..args) = { .. }` is now `#let slide(..args) = touying-slide-wrapper(self => { .. })`, where `self` is automatically injected.
+  - We can use `config-xxx` syntax to configure Touying, for example, `#show: university-theme.with(aspect-ratio: "16-9", config-colors(primary: blue))`.
+- The `touying-slide` function no longer includes parameters like `section`, `subsection`, and `title`. These will be automatically inserted into the slide as invisible level 1, 2, or 3 headings via `self.headings` (controlled by the `slide-level` configuration).
+  - We can leverage the powerful headings provided by Typst to support numbering, outlines, and bookmarks.
+  - Headings within the `#slide[= XXX]` function will be adjusted to level `slide-level + 1` using the `offset` parameter.
+  - We can use labels on headings to control many aspects, such as supporting  the `<touying:hidden>` and other special labels, implementing short headings, or recalling a slide with `#touying-recall()`.
+- Touying now supports the normal use of `set` and `show` rules at any position, without requiring them to be in specific locations.
+
+A simple usage example is shown below, and more examples can be found in the `examples` directory:
+
+```typst
+#import "@preview/touying:0.5.0": *
+#import themes.university: *
+
+#show: university-theme.with(
+  aspect-ratio: "16-9",
+  config-info(
+    title: [Title],
+    subtitle: [Subtitle],
+    author: [Authors],
+    date: datetime.today(),
+    institution: [Institution],
+    logo: emoji.school,
+  ),
+)
+
+#set heading(numbering: "1.1")
+
+#title-slide()
+
+= The Section
+
+== Slide Title
+
+#lorem(40)
+```
+
+**Theme Migration Guide:**
+
+For detailed changes to specific themes, you can refer to the `themes` directory. Generally, if you want to migrate an existing theme, you should:
+
+1. Rename the `register` function to `xxx-theme` and remove the `self` parameter.
+2. Add a `show: touying-slides.with(..)` configuration.
+   - Change `self.methods.colors` to `config-colors(primary: rgb("#xxxxxx"))`.
+   - Change `self.page-args` to `config-page()`.
+   - Change `self.methods.slide = slide` to `config-methods(slide: slide)`.
+   - Change `self.methods.new-section-slide = new-section-slide` to `config-methods(new-section-slide: new-section-slide)`.
+   - Change private theme variables like `self.xxx-footer` to `config-store(footer: [..])`, which you can access through `self.store.footer`.
+   - Move the configuration of headers and footers into the `slide` function rather than in the `xxx-theme` function.
+   - You can directly use `set` or `show` rules in `xxx-theme` or configure them through `config-methods(init: (self: none, body) => { .. })` to fully utilize the `self` parameter.
+3. For `states.current-section-with-numbering`, you can use `utils.display-current-heading(level: 1)` instead.
+   - If you only need the previous heading regardless of whether it is a section or a subsection, use `utils.display-current-heading()`.
+4. The `alert` function can be replaced with `config-methods(alert: utils.alert-with-primary-color)`.
+5. The `touying-outline()` function is no longer needed; you can use `components.adaptive-columns(outline())` instead. Consider using `components.progressive-outline()` or `components.custom-progressive-outline()`.
+6. Replace `states.slide-counter.display() + " / " + states.last-slide-number` with `context utils.slide-counter.display() + " / " + utils.last-slide-number`. That is, we no longer use `states` but `utils`.
+7. Remove the `slides` function; we no longer need this function. Instead of implicitly injecting `title-slide()`, explicitly use `#title-slide()`. If necessary, consider adding it in the `xxx-theme` function.
+8. Change `#let slide(self: none, ..args) = { .. }` to `#let slide(..args) = touying-slide-wrapper(self => { .. })`, where `self` is automatically injected.
+   - Change specific parameter configurations to `self = utils.merge-dicts(self, config-page(fill: self.colors.neutral-lightest))`.
+   - Remove `self = utils.empty-page(self)` and use `config-common(freeze-slide-counter: true)` and `config-page(margin: 0em)` instead.
+   - Change `(self.methods.touying-slide)()` to `touying-slide()`.
+9. You can insert visible headings into slides by configuring `config-common(subslide-preamble: self => text(1.2em, weight: "bold", utils.display-current-heading(depth: self.slide-level)))`.
+10. Finally, don't forget to add document comments to your functions so your users can get better auto-completion hints, especially when using the Tinymist plugin.
+
+**Other Changes:**
+
+- feat: implemented fake frozen states support, allowing you to use numbering and `#pause` normally. This behavior can be controlled with `enable-frozen-states-and-counters`, `frozen-states`, and `frozen-counters` in `config-common()`.
+- feat: implemented `label-only-on-last-subslide` functionality to prevent non-unique label warnings when working with `@equation` and `@figure` in conjunction with `#pause` animations.
+- feat: added the `touying-recall(<label>)` function to replay a specific slide.
+- feat: implemented `nontight-list-enum-and-terms`, which defaults to `true` and forces `list`, `enum`, and `terms` to have their `tight` parameter set to `false`. You can control spacing size with `#set list(spacing: 1em)`.
+- feat: replaced `list` with `terms` implementation to achieve `align-list-marker-with-baseline`, which is off by default.
+- feat: implemented `scale-list-items`, scaling list items by a factor, e.g., `scale-list-items: 0.8` scales list items by 0.8.
+- feat: supported direct use of `#pause` and `#meanwhile` in math expressions, such as `$x + pause y$`.
+- feat: provided `#pause` and `#meanwhile` support for most layout functions, such as `grid` and `table`.
+- feat: added `#show: appendix` support, essentially equivalent to `#show: touying-set-config.with((appendix: true))`.
+- feat: Introduced special labels `<touying:hidden>`, `<touying:unnumbered>`, `<touying:unoutlined>`, `<touying:unbookmarked>` to simplify control over heading behavior.
+- feat: added basic `utils.short-heading` support to display short headings using labels, such as displaying `<sec:my-section>` as "My Section".
+- feat: added `#components.adaptive-columns()` to achieve adaptive columns that span a page, typically used with the `outline()` function.
+- feat: added `#show: magic.bibliography-as-footnote.with(bibliography("ref.bib"))` to display the bibliography in footnotes.
+- feat: added components like `custom-progressive-outline`, `mini-slides`.
+- feat: removed `touying-outline()`, which can be directly replaced with `outline()`.
+- fix: replaced potentially incompatible code, such as `type(s) == "string"` and `locate(loc => { .. })`.
+- fix: Fixed some bugs.
+
+
 ## v0.4.2
 
 - theme(metropolis): decoupled text color with `neutral-dark` (Breaking change)

examples/aqua-zh.typ

@@ -1,21 +1,22 @@
 #import "../lib.typ": *
-
-#let s = themes.aqua.register(aspect-ratio: "16-9", lang: "zh")
-#let s = (s.methods.info)(
-  self: s,
-  title: [标题],
-  subtitle: [副标题],
-  author: [作者],
-  date: datetime.today(),
-  institution: [机构],
+#import themes.aqua: *
+
+#show: aqua-theme.with(
+  aspect-ratio: "16-9",
+  config-info(
+    title: [标题],
+    subtitle: [副标题],
+    author: [作者],
+    date: datetime.today(),
+    institution: [机构],
+  ),
 )
-#let (init, slides, touying-outline, alert) = utils.methods(s)
-#show: init
 
-#show strong: alert
+#set text(lang: "zh")
+
+#title-slide()
 
-#let (slide, empty-slide, title-slide, outline-slide, focus-slide) = utils.slides(s)
-#show: slides
+#outline-slide()
 
 = 第一节
 
@@ -31,10 +32,12 @@
 
 == 总结
 
-#align(center + horizon)[
-  #set text(size: 3em, weight: "bold", s.colors.primary)
+#slide(self => [
+  #align(center + horizon)[
+    #set text(size: 3em, weight: "bold", self.colors.primary)
 
-  THANKS FOR ALL
+    THANKS FOR ALL
 
-  敬请指正！
-]
+    敬请指正！
+  ]
+])

examples/aqua.typ

@@ -1,38 +1,38 @@
 #import "../lib.typ": *
-
-#let s = themes.aqua.register(aspect-ratio: "16-9", lang: "en")
-#let s = (s.methods.info)(
-  self: s,
-  title: [Title],
-  subtitle: [Subtitle],
-  author: [Authors],
-  date: datetime.today(),
-  institution: [Institution],
+#import themes.aqua: *
+
+#show: aqua-theme.with(
+  aspect-ratio: "16-9",
+  config-info(
+    title: [Title],
+    subtitle: [Subtitle],
+    author: [Authors],
+    date: datetime.today(),
+    institution: [Institution],
+  ),
 )
-#let (init, slides, touying-outline, alert) = utils.methods(s)
-#show: init
 
-#show strong: alert
+#title-slide()
 
-#let (slide, empty-slide, title-slide, outline-slide, focus-slide) = utils.slides(s)
-#show: slides
+#outline-slide()
 
 = The Section
 
 == Slide Title
 
-#slide[
-  #lorem(40)
-]
+#lorem(40)
 
 #focus-slide[
   Another variant with primary color in background...
 ]
 
 == Summary
 
-#align(center + horizon)[
-  #set text(size: 3em, weight: "bold", s.colors.primary)
-  THANKS FOR ALL
-]
+#slide(self => [
+  #align(center + horizon)[
+    #set text(size: 3em, weight: "bold", fill: self.colors.primary)
+    THANKS FOR ALL
+  ]
+])
+