@kirigami/php-prepros 1.1.0 → 1.6.0

package/src/libraries/curl.class.php

@@ -1,19 +1,36 @@
 <?php
 
+
+
+if(!boolval(PREPROS::$config->network ?? false)) STD::error("CURL Error: Network option is not activated.");
+
+
 class CURL {
 
+	// Mimics a Google Chrome (stable) browser on Windows 11, desktop, requesting
+	// a top-level document. Windows 11 still reports "Windows NT 10.0" in the UA
+	// string; the real version is only exposed through the Sec-CH-UA-Platform-Version
+	// client hint ("15.0.0"). Accept advertises every image format modern Chrome
+	// supports, AVIF included.
 	const HEADERS = [
-		'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36',
-		'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9',
+		'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36',
+		'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7',
 		'Accept-Language: fr-CA,fr;q=0.9,en-US;q=0.8,en;q=0.7',
-		'Sec-Ch-Ua: "Not_A Brand";v="99", "Google Chrome";v="109", "Chromium";v="109"',
+		// Accept-Encoding is intentionally left to CURLOPT_ENCODING so curl only
+		// advertises what it can actually transparently decode.
+		'Sec-Ch-Ua: "Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
 		'Sec-Ch-Ua-Mobile: ?0',
 		'Sec-Ch-Ua-Platform: "Windows"',
+		'Sec-Ch-Ua-Platform-Version: "15.0.0"',
+		'Sec-Ch-Ua-Arch: "x86"',
+		'Sec-Ch-Ua-Bitness: "64"',
+		'Sec-Ch-Ua-Full-Version-List: "Google Chrome";v="131.0.6778.86", "Chromium";v="131.0.6778.86", "Not_A Brand";v="24.0.0.0"',
 		'Sec-Fetch-Dest: document',
 		'Sec-Fetch-Mode: navigate',
 		'Sec-Fetch-Site: none',
 		'Sec-Fetch-User: ?1',
 		'Upgrade-Insecure-Requests: 1',
+		'Priority: u=0, i',
 	];
 
     

package/src/libraries/fs.class.php

@@ -48,6 +48,126 @@ class FS
 	}
 
 
+	/**
+	 * Lists the immediate child pages of the calling template.
+	 *
+	 * Scans the directories directly below the folder of the file that
+	 * called this function, keeps the ones that hold an `_index.php`, parses
+	 * that file's first PHPDOC block via {@see FS::phpFileInfo()} and returns
+	 * the pages ordered by `@position` ascending (a missing `@position`
+	 * counts as 999999), then by folder name.
+	 *
+	 * Only usable while a render is in progress (`PREPROS::$file` set).
+	 *
+	 * @param  string $anchor Path whose folder is scanned; defaults to the page
+	 *                         currently being rendered (`PREPROS::$file`), so it
+	 *                         works the same called straight from a template, from
+	 *                         a layout partial, or from a helper function.
+	 * @return object[]         One `stdClass` per child: the parsed PHPDOC
+	 *                          of its `_index.php`, plus a `->file` key
+	 *                          holding that file's absolute path.
+	 * @throws \Exception       When called outside of a render.
+	 */
+	public static function getChildren(string $anchor = ''): array
+	{
+		if (PREPROS::$file === '') throw new Exception('FS::getChildren() can only be called during a render.');
+		if (!$anchor) $anchor = PREPROS::$file;
+		if (!$anchor || !$dir = realpath(pathinfo($anchor, PATHINFO_DIRNAME))) return [];
+
+		$children = [];
+		foreach (glob($dir . '/*', GLOB_ONLYDIR) as $subdir) {
+			$index = $subdir . '/_index.php';
+			if (!is_file($index)) continue;
+			$info = FS::phpFileInfo($index) ?: new stdClass;
+			$info = clone $info;
+			$info->file = realpath($index);
+			$position = (isset($info->position) && is_numeric($info->position)) ? (int) $info->position : 999999;
+			$children[] = ['position' => $position, 'name' => pathinfo($subdir, PATHINFO_BASENAME), 'info' => $info];
+		}
+
+		usort($children, fn($a, $b) => ($a['position'] <=> $b['position']) ?: strnatcasecmp($a['name'], $b['name']));
+
+		return array_column($children, 'info');
+	}
+
+
+	/**
+	 * Builds the breadcrumb trail of the calling page.
+	 *
+	 * Only runs when the calling file opts in with `@breadcrumb true` (or
+	 * `@breadcrumb 1`) in its first PHPDOC block; otherwise returns `[]`.
+	 *
+	 * Starting from the folder *above* the caller's own folder (the current
+	 * page is never part of its own trail), it walks the parent directories
+	 * upward, collecting the `_index.php` of each one via
+	 * {@see FS::phpFileInfo()}. The walk stops at the source root, or at the
+	 * first ancestor `_index.php` that does not carry an active `@breadcrumb`
+	 * tag — that page is a pure separator and is left out of the result.
+	 * Directories with no `_index.php` are skipped without breaking the chain.
+	 *
+	 * Only usable while a render is in progress (`PREPROS::$file` set).
+	 *
+	 * @param  string $anchor Path the trail is walked from; defaults to the page
+	 *                         currently being rendered (`PREPROS::$file`), so it
+	 *                         works the same called straight from a template, from
+	 *                         a layout partial, or from a helper function.
+	 * @return object[]         One `stdClass` per ancestor page, ordered from
+	 *                          the top-most ancestor down to the nearest
+	 *                          parent: the parsed PHPDOC of its `_index.php`,
+	 *                          plus a `->file` key holding that file's
+	 *                          absolute path.
+	 * @throws \Exception       When called outside of a render.
+	 */
+	public static function getBreadcrumb(string $anchor = ''): array
+	{
+		if (PREPROS::$file === '') throw new Exception('FS::getBreadcrumb() can only be called during a render.');
+		if (!$anchor) $anchor = PREPROS::$file;
+		if (!$anchor || !$dir = realpath(pathinfo($anchor, PATHINFO_DIRNAME))) return [];
+
+		$self = FS::phpFileInfo($anchor) ?: new stdClass;
+		if (!self::truthy($self->breadcrumb ?? null)) return [];
+
+		if (!$root = realpath(PREPROS::$config->root)) return [];
+		$root = rtrim(str_replace('\\', '/', $root), '/');
+		$dir  = rtrim(str_replace('\\', '/', $dir), '/');
+
+		$trail = [];
+		while (true) {
+			$parent = str_replace('\\', '/', dirname($dir));
+			if ($parent === $dir) break;                                      // filesystem root
+			$dir = $parent;
+			if (strncmp($dir . '/', $root . '/', strlen($root) + 1) !== 0) break; // above the source root
+
+			$index = $dir . '/_index.php';
+			if (is_file($index)) {
+				$info = FS::phpFileInfo($index) ?: new stdClass;
+				if (!self::truthy($info->breadcrumb ?? null)) break;          // separator page: stop, exclude it
+				$info = clone $info;
+				$info->file = realpath($index);
+				$trail[] = $info;
+			}
+
+			if ($dir === $root) break;
+		}
+
+		return array_reverse($trail);
+	}
+
+
+	/**
+	 * Loose truthiness test for a PHPDOC tag value (`true` / `1` / `yes` /
+	 * `on`, case-insensitive). PHPDOC values always come through as strings,
+	 * but bool/int are handled too for callers that pass a raw value.
+	 */
+	private static function truthy(mixed $v): bool
+	{
+		if (is_bool($v)) return $v;
+		if (is_int($v))  return $v === 1;
+		if (!is_string($v)) return false;
+		return in_array(strtolower(trim($v)), ['1', 'true', 'yes', 'on'], true);
+	}
+
+
 	public static function phpFileInfo(string $file): object|bool
 	{
 		static $files = [];
@@ -62,17 +182,52 @@ class FS
 				}
 			}
 			if (empty($block)) return new stdClass;
-			if (!preg_match_all('#@([a-z0-9]+)[\s\t]+([^\n]+)#msi', $block, $m)) $files[$file] = new stdClass;
-			else {
-				$info = [];
-				foreach ($m[1] as $k => $v) $info[trim($v)] = trim($m[2][$k]);
-				$files[$file] = (object)$info;
-			}
+			$files[$file] = (object) self::parseDocBlock($block);
 		}
 		return $files[$file];
 	}
 
 
+	/**
+	 * Parses the `@tag value` lines of a PHPDOC block into a `tag => value` map.
+	 *
+	 * Only lines whose first non-whitespace character (past an optional `*`
+	 * gutter) is an `@` start a tag — so an `@word` dropped mid-sentence in the
+	 * block's prose is ignored and can't clobber a real tag. A tag's value may
+	 * wrap onto the following *indented* (hanging-indent) continuation lines,
+	 * up to the next `@tag`, a blank line, a flush-left prose line, or the end
+	 * of the block; continuation lines are joined with a single space.
+	 *
+	 * @param  string $block Raw `/** … *&#47;` doc-comment text.
+	 * @return array<string,string>
+	 */
+	private static function parseDocBlock(string $block): array
+	{
+		$info    = [];
+		$current = null;
+
+		foreach (preg_split('/\r\n|\r|\n/', $block) as $line) {
+			// Drop the opening `/**`, a ` * ` gutter, and the closing ` */`.
+			$line = preg_replace('#^\s*/\*\*+#', '', $line);
+			$line = preg_replace('#\s*\*/\s*$#', '', $line);
+			$line = preg_replace('#^[ \t]*\*[ \t]?#', '', $line, 1);
+
+			if (preg_match('/^[ \t]*@([A-Za-z0-9_]+)[ \t]*(.*)$/', $line, $m)) {
+				$current = trim($m[1]);
+				$info[$current] = trim($m[2]);
+			} elseif (trim($line) === '') {
+				$current = null;                                   // blank line ends a value
+			} elseif ($current !== null && preg_match('/^[ \t]/', $line)) {
+				$info[$current] = trim($info[$current] . ' ' . trim($line));   // hanging indent → continuation
+			} else {
+				$current = null;                                   // flush-left prose ends a value
+			}
+		}
+
+		return $info;
+	}
+
+
 	public static function rmdir(string $dir, bool $removeSelf = true): bool
 	{
 		if (!file_exists($dir)) return true;

package/src/libraries/html.class.php

@@ -1,16 +1,16 @@
 <?php
 
 /**
- * HtmlFormatter — formateur HTML pour Kirigami
- * Utilise Dom\HTMLDocument (PHP 8.4, moteur Lexbor) pour parser,
- * puis re-sérialise avec indentation.
- * Les blocs <script> et <style> sont indentés au bon niveau mais non reformatés.
+ * HtmlFormatter — HTML formatter for Kirigami
+ * Uses Dom\HTMLDocument (PHP 8.4, Lexbor engine) to parse, then re-serializes
+ * with indentation.
+ * <script> and <style> blocks are indented at the right level but not reformatted.
  */
 class HTML
 {
     private const INDENT = 4;
 
-    // Attributs booléens HTML5 — écrits sans valeur
+    // HTML5 boolean attributes — written without a value
     private const BOOLEAN_ATTRS = [
         'allowfullscreen', 'async', 'autofocus', 'autoplay', 'checked',
         'controls', 'default', 'defer', 'disabled', 'formnovalidate',
@@ -19,7 +19,7 @@ class HTML
         'readonly', 'required', 'reversed', 'selected', 'webkit-playsinline',
     ];
 
-    // Éléments inline — leur présence dans un parent n'empêche pas le rendu inline
+    // Inline elements — their presence in a parent doesn't prevent inline rendering
     private const INLINE = [
         'a', 'abbr', 'acronym', 'b', 'bdo', 'big', 'br', 'button', 'cite',
         'code', 'dfn', 'em', 'i', 'img', 'input', 'kbd', 'label', 'map',
@@ -28,21 +28,35 @@ class HTML
     ];
 
     private const RAW  = ['script', 'style'];
+    // Whitespace-significant elements: their text content is emitted byte for
+    // byte, never re-indented or collapsed (a code block must keep its line
+    // breaks and leading spaces; a <textarea> its exact value).
+    private const VERBATIM = ['pre', 'textarea'];
     private const VOID = [
         'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
         'link', 'meta', 'source', 'track', 'wbr',
     ];
 
+    /** Verbatim blocks stashed during a format() run, keyed by placeholder. */
+    private static array $verbatim = [];
+
     public static function format(string $html): string
     {
         $dom = Dom\HTMLDocument::createFromString($html, LIBXML_NOERROR);
 
+        self::$verbatim = [];
         $output = '';
         foreach ($dom->childNodes as $node) {
             $output .= static::renderNode($node, 0);
         }
 
+        // Collapse runs of blank lines — but not inside <pre>/<textarea>, whose
+        // content was swapped out for a placeholder above.
         $output = preg_replace('/\n{3,}/', "\n\n", $output);
+        if (self::$verbatim) {
+            $output = strtr($output, self::$verbatim);
+            self::$verbatim = [];
+        }
 
         return rtrim($output) . "\n";
     }
@@ -69,6 +83,44 @@ class HTML
             return "{$pad}<{$tag}{$attrs}>\n";
         }
 
+        // `<pre><code>` (a fenced code block): re-indent the code to this
+        // element's depth so the HTML source stays readable. The exact leading
+        // run added here is stripped again before display — at build time by
+        // @kirigami/plugin-highlight, otherwise by the small de-indent script
+        // Kirigami injects (prepros.head). Relative indentation is preserved.
+        if ($tag === 'pre') {
+            $code = self::soleCodeChild($node);
+            if ($code !== null) {
+                $childPad = str_repeat(' ', ($depth + 1) * self::INDENT);
+                $lines    = explode("\n", $code->innerHTML);
+
+                $min = PHP_INT_MAX;
+                foreach ($lines as $line) {
+                    if (trim($line) === '') continue;
+                    $min = min($min, strlen($line) - strlen(ltrim($line, ' ')));
+                }
+                $min = $min === PHP_INT_MAX ? 0 : $min;
+
+                $body = implode("\n", array_map(
+                    static fn(string $line) => trim($line) === '' ? '' : $childPad . substr($line, $min),
+                    $lines
+                ));
+                $token = "\x01VERB" . count(self::$verbatim) . "\x01";
+                self::$verbatim[$token] = "\n" . rtrim($body, "\n") . "\n{$pad}";
+                return "{$pad}<pre><code" . static::renderAttrs($code) . ">{$token}</code></pre>\n";
+            }
+        }
+
+        // Whitespace-significant: emit the inner HTML exactly as parsed, so a
+        // bare <pre>/<textarea> keeps its line breaks and indentation. Only the
+        // opening tag is padded to the current depth.
+        if (in_array($tag, self::VERBATIM, true)) {
+            /** @var DOMElement $node */
+            $token = "\x01VERB" . count(self::$verbatim) . "\x01";
+            self::$verbatim[$token] = $node->innerHTML;
+            return "{$pad}<{$tag}{$attrs}>" . $token . "</{$tag}>\n";
+        }
+
         if ($isRaw) {
             /** @var DOMElement $node */
             $inner = trim($node->innerHTML, "\n\r");
@@ -78,7 +130,7 @@ class HTML
             $childPad = str_repeat(' ', ($depth + 1) * self::INDENT);
             $lines    = explode("\n", $inner);
 
-            // Calcule le niveau d'indentation minimal existant (ignore les lignes vides)
+            // Compute the existing minimum indentation level (ignoring blank lines)
             $minIndent = PHP_INT_MAX;
             foreach ($lines as $line) {
                 if (trim($line) === '') continue;
@@ -86,7 +138,7 @@ class HTML
             }
             $minIndent = $minIndent === PHP_INT_MAX ? 0 : $minIndent;
 
-            // Dédente puis ré-indente au bon niveau
+            // Dedent then re-indent at the right level
             $indented = implode("\n", array_map(
                 static fn(string $line) => trim($line) !== ''
                     ? $childPad . substr($line, $minIndent)
@@ -102,11 +154,11 @@ class HTML
             return "{$pad}<{$tag}{$attrs}></{$tag}>\n";
         }
 
-        // Si tous les enfants sont inline ET que ça ressemble à un flux de texte
-        // (du vrai texte, ou un seul élément enfant), on re-sérialise en une seule ligne.
-        // Sans looksLikeTextFlow, un <section> qui contient plusieurs gros <a> côte à côte
-        // (ex: une grille de logos) se retrouverait aussi collé sur une seule ligne,
-        // puisque <a> est dans INLINE — ce n'est pas ce qu'on veut.
+        // If all children are inline AND it looks like a text flow (real text,
+        // or a single child element), re-serialize on a single line.
+        // Without looksLikeTextFlow, a <section> holding several large <a> side
+        // by side (e.g. a logo grid) would also end up crammed onto one line,
+        // since <a> is in INLINE — which is not what we want.
         if (static::hasOnlyInlineChildren($node) && static::looksLikeTextFlow($node)) {
             $inner = trim(static::renderInline($node));
             return "{$pad}<{$tag}{$attrs}>{$inner}</{$tag}>\n";
@@ -120,9 +172,9 @@ class HTML
         return "{$pad}<{$tag}{$attrs}>\n{$inner}{$pad}</{$tag}>\n";
     }
 
-    // Sérialise le contenu inline d'un nœud sur une seule ligne, en réduisant
-    // tout groupe d'espaces/tabs/retours à la ligne du texte source à une seule espace
-    // (équivalent au comportement de collapse des espaces en HTML).
+    // Serializes a node's inline content on a single line, collapsing any run
+    // of spaces/tabs/newlines in the source text to a single space (equivalent
+    // to HTML's whitespace-collapsing behavior).
     private static function renderInline(Dom\Node $node): string
     {
         $out = '';
@@ -150,9 +202,10 @@ class HTML
         return $out;
     }
 
-    // Distingue "du texte qui contient un peu d'inline" (Cliquez <a>ici</a>.) d'un
-    // conteneur qui aligne simplement plusieurs blocs inline côte à côte (grille de <a><img></a>).
-    // Vrai si : il y a du texte significatif parmi les enfants, OU un seul enfant élément.
+    // Tells "text that contains a bit of inline" (Click <a>here</a>.) apart from
+    // a container that just lines up several inline blocks side by side (a grid
+    // of <a><img></a>).
+    // True if: there is meaningful text among the children, OR a single child element.
     private static function looksLikeTextFlow(Dom\Node $node): bool
     {
         $elementCount = 0;
@@ -167,8 +220,8 @@ class HTML
         return $elementCount <= 1;
     }
 
-    // Vérifie que tous les descendants directs sont inline (texte, void inline, éléments inline)
-    // Les éléments inline eux-mêmes ne doivent pas contenir d'éléments block
+    // Checks that every direct descendant is inline (text, inline void, inline elements)
+    // The inline elements themselves must not contain block elements
     private static function hasOnlyInlineChildren(Dom\Node $node): bool
     {
         foreach ($node->childNodes as $child) {
@@ -181,7 +234,7 @@ class HTML
             if (!in_array(strtolower($child->nodeName), self::INLINE, true)) {
                 return false;
             }
-            // Récursif : l'élément inline ne doit pas contenir d'éléments block
+            // Recursive: the inline element must not contain block elements
             if (!static::hasOnlyInlineChildren($child)) {
                 return false;
             }
@@ -189,6 +242,23 @@ class HTML
         return true;
     }
 
+    // The lone <code> child of a <pre> (a fenced code block), or null when the
+    // <pre> holds anything else — raw text, several elements, markup to keep.
+    private static function soleCodeChild(Dom\Node $node): ?Dom\Node
+    {
+        $code = null;
+        foreach ($node->childNodes as $child) {
+            if ($child->nodeType === XML_TEXT_NODE) {
+                if (trim($child->nodeValue) !== '') return null;
+                continue;
+            }
+            if ($code !== null || $child->nodeType !== XML_ELEMENT_NODE) return null;
+            if (strtolower($child->nodeName) !== 'code') return null;
+            $code = $child;
+        }
+        return $code;
+    }
+
     private static function renderText(Dom\Node $node, int $depth): string
     {
         $text = trim($node->nodeValue);