@typfolio/core 0.1.0 → 0.2.0

package/typst-packages/local/typfolio/0.1.0/sample.typ

@@ -7,10 +7,20 @@
 // `sample-from-schema(schema, mode: "full")` builds a value from a JSON Schema (a dictionary):
 //   "full"    shape-complete, for editor completion: every property, one array item, non-null shapes.
 //   "minimal" the sparsest value the schema allows, to expose templates that assume optional data.
+// In both, an image field (`contentMediaType: "image/..."`) is a placeholder image's bytes.
 // The sample is not validated against the schema.
 
 #let _is-empty(v) = (type(v) == array or type(v) == dictionary) and v.len() == 0
 
+// A field that holds the path of an image file says so with `contentMediaType: "image/..."`. In the
+// editor and in template checks there is no such file to read, so the sample is the bytes of a grey
+// placeholder image instead, which `image()` draws: write `image(data.logo)`, not `image("/" + ...)`.
+#let _placeholder = bytes("<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"400\" height=\"200\" viewBox=\"0 0 400 200\"><rect width=\"400\" height=\"200\" fill=\"#e6e8eb\"/><path d=\"M0 0L400 200M400 0L0 200\" stroke=\"#c4c8cd\" stroke-width=\"2\"/></svg>")
+#let _is-image(node) = {
+  let media = node.at("contentMediaType", default: none)
+  type(media) == str and media.starts-with("image/")
+}
+
 #let _formats = (
   "date": "2024-01-15",
   "date-time": "2024-01-15T09:30:00Z",
@@ -19,8 +29,9 @@
   "uuid": "123e4567-e89b-12d3-a456-426614174000",
 )
 
-// Resolves a local "#/..." reference against the root schema.
+// Resolves a local "#" or "#/..." reference against the root schema.
 #let _resolve(root, ref) = {
+  if ref == "#" { return root }
   let node = root
   for part in ref.slice(2).split("/") {
     node = node.at(part.replace("~1", "/").replace("~0", "~"))
@@ -28,10 +39,31 @@
   node
 }
 
-// `seen` holds the $ref values being expanded on the current path, so a recursive schema ends at
-// `none` instead of recursing; `depth` bounds anything else.
+// `seen` holds the $ref values being expanded on the current path. A recursive schema is expanded
+// one level (a tree gets one child) and then cut: the cut value is `_cut`, which an array turns into
+// no items and an object into a missing optional property, so a recursive list ends empty instead
+// of holding `none`. `depth` bounds anything else.
+#let _cut = "\u{E000}typfolio-recursion-cut"
+#let _recursing(seen, ref) = seen.filter(r => r == ref).len() >= 2
+
+// An object's properties from their samples: a cut optional property is left out, a cut required
+// one is `none` (the schema demands an endless value there).
+#let _object(node, sampled) = {
+  let required = node.at("required", default: ())
+  let out = (:)
+  for (key, v) in sampled {
+    if v == _cut {
+      if key in required { out.insert(key, none) }
+    } else {
+      out.insert(key, v)
+    }
+  }
+  out
+}
+
 #let _sample(root, node, depth, seen) = {
   if depth > 16 or type(node) != dictionary { return none }
+  if _is-image(node) { return _placeholder }
   let candidates = ()
   if "examples" in node { candidates += node.at("examples") }
   if "default" in node { candidates.push(node.at("default")) }
@@ -45,14 +77,14 @@
   }
   if "$ref" in node {
     let ref = node.at("$ref")
-    if ref in seen { return none }
+    if _recursing(seen, ref) { return _cut }
     return _sample(root, _resolve(root, ref), depth + 1, seen + (ref,))
   }
   for key in ("anyOf", "oneOf") {
     if key in node {
       for branch in node.at(key) {
         let v = _sample(root, branch, depth + 1, seen)
-        if v != none { return v }
+        if v != none and v != _cut { return v }
       }
     }
   }
@@ -70,10 +102,11 @@
     if "properties" in node { t = "object" } else if "items" in node { t = "array" }
   }
   if t == "object" {
-    let out = (:)
+    let sampled = (:)
     for (key, sub) in node.at("properties", default: (:)) {
-      out.insert(key, _sample(root, sub, depth + 1, seen))
+      sampled.insert(key, _sample(root, sub, depth + 1, seen))
     }
+    let out = _object(node, sampled)
     // A partial object default fills in the generated shape rather than replacing it.
     if filled.len() > 0 { out += filled.first() }
     return out
@@ -81,7 +114,9 @@
   if t == "array" {
     let items = node.at("items", default: none)
     if items == none { return () }
-    return range(calc.max(1, node.at("minItems", default: 1))).map(_ => _sample(root, items, depth + 1, seen))
+    let item = _sample(root, items, depth + 1, seen)
+    if item == _cut { return () }
+    return range(calc.max(1, node.at("minItems", default: 1))).map(_ => item)
   }
   if t == "string" { return _formats.at(node.at("format", default: ""), default: "Sample text") }
   if t == "integer" or t == "number" { return node.at("minimum", default: 1) }
@@ -89,9 +124,6 @@
   none
 }
 
-/// Builds a shape-complete sample value from a JSON Schema (a dictionary).
-#let sample-from-schema(schema) = _sample(schema, schema, 0, ())
-
 // Minimal mode. Only `required` properties, nullable values are `none`, arrays are empty unless
 // `minItems` says otherwise, `examples` and `default` are ignored. `$ref` and `allOf` follow full mode.
 #let _is-nullable(node) = {
@@ -108,16 +140,18 @@
 #let _minimal(root, node, depth, seen) = {
   if depth > 16 or type(node) != dictionary { return none }
   if _is-nullable(node) { return none }
+  if _is-image(node) { return _placeholder }
   if "const" in node { return node.at("const") }
   if "enum" in node and node.at("enum").len() > 0 { return node.at("enum").first() }
   if "$ref" in node {
     let ref = node.at("$ref")
-    if ref in seen { return none }
+    if _recursing(seen, ref) { return _cut }
     return _minimal(root, _resolve(root, ref), depth + 1, seen + (ref,))
   }
   for key in ("anyOf", "oneOf") {
     if key in node and node.at(key).len() > 0 {
-      return _minimal(root, node.at(key).first(), depth + 1, seen)
+      let v = _minimal(root, node.at(key).first(), depth + 1, seen)
+      return if v == _cut { none } else { v }
     }
   }
   if "allOf" in node {
@@ -134,18 +168,20 @@
     if "properties" in node { t = "object" } else if "items" in node { t = "array" }
   }
   if t == "object" {
-    let out = (:)
+    let sampled = (:)
     let properties = node.at("properties", default: (:))
     for key in node.at("required", default: ()) {
-      out.insert(key, _minimal(root, properties.at(key, default: none), depth + 1, seen))
+      sampled.insert(key, _minimal(root, properties.at(key, default: none), depth + 1, seen))
     }
-    return out
+    return _object(node, sampled)
   }
   if t == "array" {
     let items = node.at("items", default: none)
     let count = node.at("minItems", default: 0)
     if items == none or count <= 0 { return () }
-    return range(count).map(_ => _minimal(root, items, depth + 1, seen))
+    let item = _minimal(root, items, depth + 1, seen)
+    if item == _cut { return () }
+    return range(count).map(_ => item)
   }
   if t == "string" { return "a" * node.at("minLength", default: 0) }
   if t == "integer" or t == "number" {
@@ -160,7 +196,9 @@
 
 /// Builds a sample value from a JSON Schema (a dictionary). `mode` is "full" or "minimal".
 #let sample-from-schema(schema, mode: "full") = {
-  if mode == "full" { _sample(schema, schema, 0, ()) }
-  else if mode == "minimal" { _minimal(schema, schema, 0, ()) }
-  else { panic("@local/typfolio: sample mode must be \"full\" or \"minimal\", got " + repr(mode)) }
+  // The root is itself an expansion of "#", so a schema that refers to itself recurses one level too.
+  let value = if mode == "full" { _sample(schema, schema, 0, ("#",)) }
+    else if mode == "minimal" { _minimal(schema, schema, 0, ("#",)) }
+    else { panic("@local/typfolio: sample mode must be \"full\" or \"minimal\", got " + repr(mode)) }
+  if value == _cut { none } else { value }
 }