docs(mobile/v4): native-ui component audit — close the gaps between code and docs

app/Services/DocsSearchService.php

@@ -110,7 +110,51 @@ public function getNavigation(string $platform, string $version): array
             usort($sections[$section], fn ($a, $b) => $a['order'] <=> $b['order']);
         }
 
-        return $sections;
+        // Order the sections themselves to match the sidebar (each section
+        // directory's `_index.md` front-matter `order` — the same source
+        // ShowDocumentationController sorts by). Nested subsections (e.g.
+        // plugins/core) rank right after their parent. JSON objects keep key
+        // order, so API consumers get the sidebar order for free. Unknown
+        // sections trail in their original grouping order (stable sort).
+        $rank = $this->sectionRanks($platform, $version);
+        $slugs = array_keys($sections);
+        usort($slugs, fn ($a, $b) => ($rank[$a] ?? PHP_INT_MAX) <=> ($rank[$b] ?? PHP_INT_MAX));
+
+        $ordered = [];
+        foreach ($slugs as $slug) {
+            $ordered[$slug] = $sections[$slug];
+        }
+
+        return $ordered;
+    }
+
+    /**
+     * Sidebar rank per section slug for one platform/version: top-level
+     * sections rank by their `_index.md` front-matter `order` (scaled so
+     * children can interleave); a nested subsection ranks just after its
+     * parent, offset by its own `order`. Sections without an `_index.md`
+     * get no rank (callers push them to the end).
+     *
+     * @return array<string, int>
+     */
+    protected function sectionRanks(string $platform, string $version): array
+    {
+        $base = "{$this->docsPath}/{$platform}/{$version}";
+        $rank = [];
+
+        foreach (glob("{$base}/*/_index.md") ?: [] as $index) {
+            $slug = basename(dirname($index));
+            $order = YamlFrontMatter::parse(file_get_contents($index))->matter('order') ?? 9999;
+            $rank[$slug] = $order * 10000;
+
+            foreach (glob("{$base}/{$slug}/*/_index.md") ?: [] as $nested) {
+                $nestedSlug = basename(dirname($nested));
+                $nestedOrder = YamlFrontMatter::parse(file_get_contents($nested))->matter('order') ?? 9999;
+                $rank[$nestedSlug] = $rank[$slug] + 1 + min($nestedOrder, 9998);
+            }
+        }
+
+        return $rank;
     }
 
     public function getPlatforms(): array