Merge 1a8797e6cc123b1bd9928347ac95901947e42686 into 7278d887cf05fadc9a96478830e5876739b78f53

This makes the API for `Binding` more consistent without requiring any
intermediate bindings for the `Deprecation`.

crates/typst-library/src/diag.rs

@@ -234,18 +234,23 @@ impl From<SyntaxError> for SourceDiagnostic {
 
 /// Destination for a deprecation message when accessing a deprecated value.
 pub trait DeprecationSink {
-    /// Emits the given deprecation message into this sink.
+    /// Emits the given deprecation message into this sink alongside a version
-    fn emit(self, message: &str);
+    /// in which the deprecated item is planned to be removed.
+    fn emit(self, message: &str, until: Option<&str>);
 }
 
 impl DeprecationSink for () {
-    fn emit(self, _: &str) {}
+    fn emit(self, _: &str, _: Option<&str>) {}
 }
 
 impl DeprecationSink for (&mut Engine<'_>, Span) {
     /// Emits the deprecation message as a warning.
-    fn emit(self, message: &str) {
+    fn emit(self, message: &str, version: Option<&str>) {
-        self.0.sink.warn(SourceDiagnostic::warning(self.1, message));
+        self.0.sink.warn(
+            SourceDiagnostic::warning(self.1, message).with_hints(
+                version.map(|v| eco_format!("this will be removed in {}", v)),
+            ),
+        );
     }
 }
 

crates/typst-library/src/foundations/scope.rs

@@ -253,8 +253,8 @@ pub struct Binding {
     span: Span,
     /// The category of the binding.
     category: Option<Category>,
-    /// A deprecation message for the definition.
+    /// The deprecation information if this item is deprecated.
-    deprecation: Option<&'static str>,
+    deprecation: Option<Box<Deprecation>>,
 }
 
 /// The different kinds of slots.
@@ -284,8 +284,8 @@ impl Binding {
     }
 
     /// Marks this binding as deprecated, with the given `message`.
-    pub fn deprecated(&mut self, message: &'static str) -> &mut Self {
+    pub fn deprecated(&mut self, deprecation: Deprecation) -> &mut Self {
-        self.deprecation = Some(message);
+        self.deprecation = Some(Box::new(deprecation));
         self
     }
 
@@ -300,8 +300,8 @@ impl Binding {
     /// - pass `()` to ignore the message.
     /// - pass `(&mut engine, span)` to emit a warning into the engine.
     pub fn read_checked(&self, sink: impl DeprecationSink) -> &Value {
-        if let Some(message) = self.deprecation {
+        if let Some(info) = &self.deprecation {
-            sink.emit(message);
+            sink.emit(info.message, info.until);
         }
         &self.value
     }
@@ -337,8 +337,8 @@ impl Binding {
     }
 
     /// A deprecation message for the value, if any.
-    pub fn deprecation(&self) -> Option<&'static str> {
+    pub fn deprecation(&self) -> Option<&Deprecation> {
-        self.deprecation
+        self.deprecation.as_deref()
     }
 
     /// The category of the value, if any.
@@ -356,6 +356,51 @@ pub enum Capturer {
     Context,
 }
 
+/// Information about a deprecated binding.
+#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
+pub struct Deprecation {
+    /// A deprecation message for the definition.
+    message: &'static str,
+    /// A version in which the deprecated binding is planned to be removed.
+    until: Option<&'static str>,
+}
+
+impl Deprecation {
+    /// Creates new deprecation info with a default message to display when
+    /// emitting the deprecation warning.
+    pub fn new() -> Self {
+        Self { message: "item is deprecated", until: None }
+    }
+
+    /// Set the message to display when emitting the deprecation warning.
+    pub fn with_message(mut self, message: &'static str) -> Self {
+        self.message = message;
+        self
+    }
+
+    /// Set the version in which the binding is planned to be removed.
+    pub fn with_until(mut self, version: &'static str) -> Self {
+        self.until = Some(version);
+        self
+    }
+
+    /// The message to display when emitting the deprecation warning.
+    pub fn message(&self) -> &'static str {
+        self.message
+    }
+
+    /// The version in which the binding is planned to be removed.
+    pub fn until(&self) -> Option<&'static str> {
+        self.until
+    }
+}
+
+impl Default for Deprecation {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 /// The error message when trying to mutate a variable from the standard
 /// library.
 #[cold]

crates/typst-library/src/foundations/symbol.rs

@@ -151,7 +151,7 @@ impl Symbol {
                 modifiers.best_match_in(list.variants().map(|(m, _, d)| (m, d)))
             {
                 if let Some(message) = deprecation {
-                    sink.emit(message)
+                    sink.emit(message, None)
                 }
                 return Ok(self);
             }

crates/typst-library/src/loading/cbor.rs

@@ -33,7 +33,10 @@ pub fn cbor(
 impl cbor {
     /// Reads structured data from CBOR bytes.
     #[func(title = "Decode CBOR")]
-    #[deprecated = "`cbor.decode` is deprecated, directly pass bytes to `cbor` instead"]
+    #[deprecated(
+        message = "`cbor.decode` is deprecated, directly pass bytes to `cbor` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// CBOR data.

crates/typst-library/src/loading/csv.rs

@@ -95,7 +95,10 @@ pub fn csv(
 impl csv {
     /// Reads structured data from a CSV string/bytes.
     #[func(title = "Decode CSV")]
-    #[deprecated = "`csv.decode` is deprecated, directly pass bytes to `csv` instead"]
+    #[deprecated(
+        message = "`csv.decode` is deprecated, directly pass bytes to `csv` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// CSV data.

crates/typst-library/src/loading/json.rs

@@ -67,7 +67,10 @@ pub fn json(
 impl json {
     /// Reads structured data from a JSON string/bytes.
     #[func(title = "Decode JSON")]
-    #[deprecated = "`json.decode` is deprecated, directly pass bytes to `json` instead"]
+    #[deprecated(
+        message = "`json.decode` is deprecated, directly pass bytes to `json` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// JSON data.

crates/typst-library/src/loading/toml.rs

@@ -41,7 +41,10 @@ pub fn toml(
 impl toml {
     /// Reads structured data from a TOML string/bytes.
     #[func(title = "Decode TOML")]
-    #[deprecated = "`toml.decode` is deprecated, directly pass bytes to `toml` instead"]
+    #[deprecated(
+        message = "`toml.decode` is deprecated, directly pass bytes to `toml` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// TOML data.

crates/typst-library/src/loading/xml.rs

@@ -75,7 +75,10 @@ pub fn xml(
 impl xml {
     /// Reads structured data from an XML string/bytes.
     #[func(title = "Decode XML")]
-    #[deprecated = "`xml.decode` is deprecated, directly pass bytes to `xml` instead"]
+    #[deprecated(
+        message = "`xml.decode` is deprecated, directly pass bytes to `xml` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// XML data.

crates/typst-library/src/loading/yaml.rs

@@ -54,7 +54,10 @@ pub fn yaml(
 impl yaml {
     /// Reads structured data from a YAML string/bytes.
     #[func(title = "Decode YAML")]
-    #[deprecated = "`yaml.decode` is deprecated, directly pass bytes to `yaml` instead"]
+    #[deprecated(
+        message = "`yaml.decode` is deprecated, directly pass bytes to `yaml` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         engine: &mut Engine,
         /// YAML data.

crates/typst-library/src/symbols.rs

@@ -1,6 +1,6 @@
 //! Modifiable symbols.
 
-use crate::foundations::{Module, Scope, Symbol, Value};
+use crate::foundations::{Deprecation, Module, Scope, Symbol, Value};
 
 /// Hook up all `symbol` definitions.
 pub(super) fn define(global: &mut Scope) {
@@ -23,7 +23,7 @@ fn extend_scope_from_codex_module(scope: &mut Scope, module: codex::Module) {
 
         let scope_binding = scope.define(name, value);
         if let Some(message) = binding.deprecation {
-            scope_binding.deprecated(message);
+            scope_binding.deprecated(Deprecation::new().with_message(message));
         }
     }
 }

crates/typst-library/src/visualize/curve.rs

@@ -476,26 +476,18 @@ impl Curve {
 
     /// Computes the size of the bounding box of this curve.
     pub fn bbox_size(&self) -> Size {
-        let mut min_x = Abs::inf();
+        let mut min = Point::splat(Abs::inf());
-        let mut min_y = Abs::inf();
+        let mut max = Point::splat(-Abs::inf());
-        let mut max_x = -Abs::inf();
-        let mut max_y = -Abs::inf();
 
         let mut cursor = Point::zero();
         for item in self.0.iter() {
             match item {
                 CurveItem::Move(to) => {
-                    min_x = min_x.min(cursor.x);
-                    min_y = min_y.min(cursor.y);
-                    max_x = max_x.max(cursor.x);
-                    max_y = max_y.max(cursor.y);
                     cursor = *to;
                 }
                 CurveItem::Line(to) => {
-                    min_x = min_x.min(cursor.x);
+                    min = min.min(cursor).min(*to);
-                    min_y = min_y.min(cursor.y);
+                    max = max.max(cursor).max(*to);
-                    max_x = max_x.max(cursor.x);
-                    max_y = max_y.max(cursor.y);
                     cursor = *to;
                 }
                 CurveItem::Cubic(c0, c1, end) => {
@@ -507,17 +499,17 @@ impl Curve {
                     );
 
                     let bbox = cubic.bounding_box();
-                    min_x = min_x.min(Abs::pt(bbox.x0)).min(Abs::pt(bbox.x1));
+                    min.x = min.x.min(Abs::pt(bbox.x0)).min(Abs::pt(bbox.x1));
-                    min_y = min_y.min(Abs::pt(bbox.y0)).min(Abs::pt(bbox.y1));
+                    min.y = min.y.min(Abs::pt(bbox.y0)).min(Abs::pt(bbox.y1));
-                    max_x = max_x.max(Abs::pt(bbox.x0)).max(Abs::pt(bbox.x1));
+                    max.x = max.x.max(Abs::pt(bbox.x0)).max(Abs::pt(bbox.x1));
-                    max_y = max_y.max(Abs::pt(bbox.y0)).max(Abs::pt(bbox.y1));
+                    max.y = max.y.max(Abs::pt(bbox.y0)).max(Abs::pt(bbox.y1));
                     cursor = *end;
                 }
                 CurveItem::Close => (),
             }
         }
 
-        Size::new(max_x - min_x, max_y - min_y)
+        Size::new(max.x - min.x, max.y - min.y)
     }
 }
 

crates/typst-library/src/visualize/image/mod.rs

@@ -178,7 +178,10 @@ pub struct ImageElem {
 impl ImageElem {
     /// Decode a raster or vector graphic from bytes or a string.
     #[func(title = "Decode Image")]
-    #[deprecated = "`image.decode` is deprecated, directly pass bytes to `image` instead"]
+    #[deprecated(
+        message = "`image.decode` is deprecated, directly pass bytes to `image` instead",
+        until = "0.15.0"
+    )]
     pub fn decode(
         span: Span,
         /// The data to decode as an image. Can be a string for SVGs.

crates/typst-library/src/visualize/mod.rs

@@ -24,6 +24,7 @@ pub use self::shape::*;
 pub use self::stroke::*;
 pub use self::tiling::*;
 
+use crate::foundations::Deprecation;
 use crate::foundations::{Element, Scope, Type};
 
 /// Hook up all visualize definitions.
@@ -41,11 +42,14 @@ pub(super) fn define(global: &mut Scope) {
     global.define_elem::<CircleElem>();
     global.define_elem::<PolygonElem>();
     global.define_elem::<CurveElem>();
-    global
+    global.define("path", Element::of::<PathElem>()).deprecated(
-        .define("path", Element::of::<PathElem>())
+        Deprecation::new()
-        .deprecated("the `path` function is deprecated, use `curve` instead");
+            .with_message("the `path` function is deprecated, use `curve` instead"),
-    global
+    );
-        .define("pattern", Type::of::<Tiling>())
+    global.define("pattern", Type::of::<Tiling>()).deprecated(
-        .deprecated("the name `pattern` is deprecated, use `tiling` instead");
+        Deprecation::new()
+            .with_message("the name `pattern` is deprecated, use `tiling` instead")
+            .with_until("0.15.0"),
+    );
     global.reset_category();
 }

crates/typst-macros/src/scope.rs

@@ -1,7 +1,8 @@
 use heck::ToKebabCase;
 use proc_macro2::TokenStream;
 use quote::quote;
-use syn::{Result, parse_quote};
+use syn::punctuated::Punctuated;
+use syn::{MetaNameValue, Result, Token, parse_quote};
 
 use crate::util::{BareType, foundations};
 
@@ -52,13 +53,36 @@ pub fn scope(_: TokenStream, item: syn::Item) -> Result<TokenStream> {
             _ => bail!(child, "unexpected item in scope"),
         };
 
-        if let Some(message) = attrs.iter().find_map(|attr| match &attr.meta {
+        if let Some(attr) = attrs.iter().find(|attr| attr.path().is_ident("deprecated")) {
-            syn::Meta::NameValue(pair) if pair.path.is_ident("deprecated") => {
+            match &attr.meta {
-                Some(&pair.value)
+                syn::Meta::NameValue(pair) if pair.path.is_ident("deprecated") => {
+                    let message = &pair.value;
+                    def = quote! { #def.deprecated(#message) }
+                }
+                syn::Meta::List(list) if list.path.is_ident("deprecated") => {
+                    let args = list.parse_args_with(
+                        Punctuated::<MetaNameValue, Token![,]>::parse_separated_nonempty,
+                    )?;
+
+                    let mut deprecation =
+                        quote! { crate::foundations::Deprecation::new() };
+
+                    if let Some(message) = args.iter().find_map(|pair| {
+                        pair.path.is_ident("message").then_some(&pair.value)
+                    }) {
+                        deprecation = quote! { #deprecation.with_message(#message) }
+                    }
+
+                    if let Some(version) = args.iter().find_map(|pair| {
+                        pair.path.is_ident("until").then_some(&pair.value)
+                    }) {
+                        deprecation = quote! { #deprecation.with_until(#version) }
+                    }
+
+                    def = quote! { #def.deprecated(#deprecation) }
+                }
+                _ => {}
             }
-            _ => None,
-        }) {
-            def = quote! { #def.deprecated(#message) }
         }
 
         definitions.push(def);

docs/src/lib.rs

@@ -17,6 +17,7 @@ use serde::Deserialize;
 use serde_yaml as yaml;
 use std::sync::LazyLock;
 use typst::diag::{StrResult, bail};
+use typst::foundations::Deprecation;
 use typst::foundations::{
     AutoValue, Binding, Bytes, CastInfo, Func, Module, NoneValue, ParamInfo, Repr, Scope,
     Smart, Type, Value,
@@ -381,7 +382,7 @@ fn func_page(
     parent: &str,
     func: &Func,
     path: &[&str],
-    deprecation: Option<&'static str>,
+    deprecation: Option<&Deprecation>,
 ) -> PageModel {
     let model = func_model(resolver, func, path, false, deprecation);
     let name = func.name().unwrap();
@@ -402,7 +403,7 @@ fn func_model(
     func: &Func,
     path: &[&str],
     nested: bool,
-    deprecation: Option<&'static str>,
+    deprecation: Option<&Deprecation>,
 ) -> FuncModel {
     let name = func.name().unwrap();
     let scope = func.scope().unwrap();
@@ -438,7 +439,8 @@ fn func_model(
         oneliner: oneliner(details),
         element: func.element().is_some(),
         contextual: func.contextual().unwrap_or(false),
-        deprecation,
+        deprecation_message: deprecation.map(Deprecation::message),
+        deprecation_until: deprecation.and_then(Deprecation::until),
         details: Html::markdown(resolver, details, nesting),
         example: example.map(|md| Html::markdown(resolver, md, None)),
         self_,
@@ -718,7 +720,7 @@ fn symbols_model(resolver: &dyn Resolver, group: &GroupData) -> SymbolsModel {
             }
         };
 
-        for (variant, c, deprecation) in symbol.variants() {
+        for (variant, c, deprecation_message) in symbol.variants() {
             let shorthand = |list: &[(&'static str, char)]| {
                 list.iter().copied().find(|&(_, x)| x == c).map(|(s, _)| s)
             };
@@ -737,7 +739,9 @@ fn symbols_model(resolver: &dyn Resolver, group: &GroupData) -> SymbolsModel {
                     .filter(|(other, _, _)| other != &variant)
                     .map(|(other, _, _)| complete(other))
                     .collect(),
-                deprecation: deprecation.or_else(|| binding.deprecation()),
+                deprecation_message: deprecation_message
+                    .or_else(|| binding.deprecation().map(Deprecation::message)),
+                deprecation_until: binding.deprecation().and_then(Deprecation::until),
             });
         }
     }

docs/src/model.rs

@@ -89,7 +89,8 @@ pub struct FuncModel {
     pub oneliner: EcoString,
     pub element: bool,
     pub contextual: bool,
-    pub deprecation: Option<&'static str>,
+    pub deprecation_message: Option<&'static str>,
+    pub deprecation_until: Option<&'static str>,
     pub details: Html,
     /// This example is only for nested function models. Others can have
     /// their example directly in their details.
@@ -165,7 +166,8 @@ pub struct SymbolModel {
     pub markup_shorthand: Option<&'static str>,
     pub math_shorthand: Option<&'static str>,
     pub math_class: Option<&'static str>,
-    pub deprecation: Option<&'static str>,
+    pub deprecation_message: Option<&'static str>,
+    pub deprecation_until: Option<&'static str>,
 }
 
 /// Shorthands listed on a category page.

tests/suite/loading/cbor.typ

@@ -1,3 +1,4 @@
 --- cbor-decode-deprecated ---
 // Warning: 15-21 `cbor.decode` is deprecated, directly pass bytes to `cbor` instead
+// Hint: 15-21 this will be removed in 0.15.0
 #let _ = cbor.decode

tests/suite/loading/csv.typ

@@ -32,4 +32,5 @@
 
 --- csv-decode-deprecated ---
 // Warning: 14-20 `csv.decode` is deprecated, directly pass bytes to `csv` instead
+// Hint: 14-20 this will be removed in 0.15.0
 #let _ = csv.decode

tests/suite/loading/json.typ

@@ -11,6 +11,7 @@
 
 --- json-decode-deprecated ---
 // Warning: 15-21 `json.decode` is deprecated, directly pass bytes to `json` instead
+// Hint: 15-21 this will be removed in 0.15.0
 #let _ = json.decode
 
 --- issue-3363-json-large-number ---

tests/suite/loading/toml.typ

@@ -42,4 +42,5 @@
 
 --- toml-decode-deprecated ---
 // Warning: 15-21 `toml.decode` is deprecated, directly pass bytes to `toml` instead
+// Hint: 15-21 this will be removed in 0.15.0
 #let _ = toml.decode

tests/suite/loading/xml.typ

@@ -29,4 +29,5 @@
 
 --- xml-decode-deprecated ---
 // Warning: 14-20 `xml.decode` is deprecated, directly pass bytes to `xml` instead
+// Hint: 14-20 this will be removed in 0.15.0
 #let _ = xml.decode

tests/suite/loading/yaml.typ

@@ -18,4 +18,5 @@
 
 --- yaml-decode-deprecated ---
 // Warning: 15-21 `yaml.decode` is deprecated, directly pass bytes to `yaml` instead
+// Hint: 15-21 this will be removed in 0.15.0
 #let _ = yaml.decode

tests/suite/visualize/curve.typ

@@ -130,6 +130,16 @@
   down, up, down, up, down,
 )
 
+--- curve-stroke-gradient-sharp ---
+#set page(width: auto)
+#let down = curve.line((40pt, 40pt), relative: true)
+#let up = curve.line((40pt, -40pt), relative: true)
+
+#curve(
+  stroke: 4pt + gradient.linear(red, blue).sharp(3),
+  down, up, down, up, down,
+)
+
 --- curve-fill-rule ---
 #stack(
   dir: ltr,

tests/suite/visualize/image.typ

@@ -188,26 +188,31 @@ A #box(image("/assets/images/tiger.jpg", height: 1cm, width: 80%)) B
 --- image-decode-svg ---
 // Test parsing from svg data
 // Warning: 8-14 `image.decode` is deprecated, directly pass bytes to `image` instead
+// Hint: 8-14 this will be removed in 0.15.0
 #image.decode(`<svg xmlns="http://www.w3.org/2000/svg" height="140" width="500"><ellipse cx="200" cy="80" rx="100" ry="50" style="fill:yellow;stroke:purple;stroke-width:2" /></svg>`.text, format: "svg")
 
 --- image-decode-bad-svg ---
 // Error: 15-152 failed to parse SVG (missing root node at 1:1)
 // Warning: 8-14 `image.decode` is deprecated, directly pass bytes to `image` instead
+// Hint: 8-14 this will be removed in 0.15.0
 #image.decode(`<svg height="140" width="500"><ellipse cx="200" cy="80" rx="100" ry="50" style="fill:yellow;stroke:purple;stroke-width:2" /></svg>`.text, format: "svg")
 
 --- image-decode-detect-format ---
 // Test format auto detect
 // Warning: 8-14 `image.decode` is deprecated, directly pass bytes to `image` instead
+// Hint: 8-14 this will be removed in 0.15.0
 #image.decode(read("/assets/images/tiger.jpg", encoding: none), width: 80%)
 
 --- image-decode-specify-format ---
 // Test format manual
 // Warning: 8-14 `image.decode` is deprecated, directly pass bytes to `image` instead
+// Hint: 8-14 this will be removed in 0.15.0
 #image.decode(read("/assets/images/tiger.jpg", encoding: none), format: "jpg", width: 80%)
 
 --- image-decode-specify-wrong-format ---
 // Error: 2-91 failed to decode image (Format error decoding Png: Invalid PNG signature.)
 // Warning: 8-14 `image.decode` is deprecated, directly pass bytes to `image` instead
+// Hint: 8-14 this will be removed in 0.15.0
 #image.decode(read("/assets/images/tiger.jpg", encoding: none), format: "png", width: 80%)
 
 --- image-pixmap-empty ---

tests/suite/visualize/tiling.typ

@@ -161,5 +161,6 @@
 #set page(width: auto, height: auto, margin: 0pt)
 
 // Warning: 10-17 the name `pattern` is deprecated, use `tiling` instead
+// Hint: 10-17 this will be removed in 0.15.0
 #let t = pattern(size: (10pt, 10pt), line(stroke: 4pt, start: (0%, 0%), end: (100%, 100%)))
 #rect(width: 50pt, height: 50pt, fill: t)