From 75907eb24ac41deef9e5ce1024ec070d6a9f039a Mon Sep 17 00:00:00 2001 From: Andrey Avtomonov Date: Tue, 19 May 2026 23:33:36 +0200 Subject: [PATCH] docs-site: annotate imperative SQL, add section anchor, drop ClickHouse - Wire numbered red badges to each problematic span in the "Without KTX" SQL with hover sync between SQL gutter, lines, and the notes list. - Add #imperative-vs-declarative anchor on the flow section header so the eyebrow link is shareable; reveals a # glyph on hover/focus. - Align the compiled-SQL note dots to the first-line midpoint (mt-[6px] instead of mt-1) so 4px dots sit at y=8 in a 16px line. - Remove all ClickHouse references from docs-site (primary-sources, quickstart, ktx-setup, contributing, agents-setup, mechanics test, warehouse drivers in the flow diagram). --- docs-site/components/semantic-layer-flow.tsx | 270 ++++++++++++++++-- docs-site/content/agents-setup.md | 2 +- .../content/docs/cli-reference/ktx-setup.mdx | 2 +- .../content/docs/community/contributing.mdx | 1 - .../docs/getting-started/quickstart.mdx | 2 +- .../docs/integrations/primary-sources.mdx | 63 +--- .../tests/product-mechanics-content.test.mjs | 3 +- 7 files changed, 252 insertions(+), 91 deletions(-) diff --git a/docs-site/components/semantic-layer-flow.tsx b/docs-site/components/semantic-layer-flow.tsx index 1a755384..770516ad 100644 --- a/docs-site/components/semantic-layer-flow.tsx +++ b/docs-site/components/semantic-layer-flow.tsx @@ -23,13 +23,19 @@ type AgentNodeData = { subtitle: string; }; +type IssueNote = { + id: number; + label: string; +}; + type ManualSqlNodeData = { variant: "manual"; badge: string; title: string; caption: string; code: string; - notes: string[]; + notes: IssueNote[]; + lineIssues: Record; }; type SlQueryNodeData = { @@ -168,12 +174,30 @@ LIMIT 1000; -- net_revenue and open_tickets are both inflated -- DATE_TRUNC syntax breaks on BigQuery`, notes: [ - "Re-stitches a 4-way join on every question", - "Reinvents net_revenue and the high-value rule", - "Hides a chasm trap across three facts", - "Filters a LEFT JOIN target in WHERE", - "Hardcodes one warehouse's date functions", + { id: 1, label: "Re-stitches a 4-way join on every question" }, + { id: 2, label: "Reinvents net_revenue and the high-value rule" }, + { id: 3, label: "Hides a chasm trap across three facts" }, + { id: 4, label: "Filters a LEFT JOIN target in WHERE" }, + { id: 5, label: "Hardcodes one warehouse's date functions" }, ], + lineIssues: { + 5: [5], + 6: [2, 3], + 7: [3], + 8: [1], + 9: [1], + 10: [1], + 11: [1], + 12: [1], + 13: [1], + 14: [1], + 17: [2], + 18: [4], + 21: [5], + 27: [3], + 28: [3], + 29: [5], + }, }, draggable: false, selectable: false, @@ -340,7 +364,7 @@ const warehouse: WarehouseNode = { data: { variant: "warehouse", title: "Warehouse", - drivers: ["PostgreSQL", "Snowflake", "BigQuery", "ClickHouse"], + drivers: ["PostgreSQL", "Snowflake", "BigQuery"], }, draggable: false, selectable: false, @@ -640,7 +664,91 @@ function CodeBlock({ ); } +function AnnotatedSqlBlock({ + code, + lineIssues, + activeIssue, + onIssueEnter, + onIssueLeave, +}: { + code: string; + lineIssues: Record; + activeIssue: number | null; + onIssueEnter: (n: number) => void; + onIssueLeave: () => void; +}) { + const lines = code.split("\n"); + + return ( +
+
+ + sql + + + agent-authored + +
+ 
+        {lines.map((line, idx) => {
+          const issues = lineIssues[idx] ?? [];
+          const hasIssue = issues.length > 0;
+          const dim =
+            activeIssue !== null && !issues.includes(activeIssue);
+          const active =
+            activeIssue !== null && issues.includes(activeIssue);
+          const classes = [
+            "sl-sql-line",
+            hasIssue ? "is-issue" : "",
+            active ? "is-active" : "",
+            dim ? "is-dim" : "",
+          ]
+            .filter(Boolean)
+            .join(" ");
+          return (
+            

+              
+                {issues.map((n) => (
+                  
+                ))}
+              
+              
+                {line.length ? highlightSql(line) : " "}
+              
+            

+          );
+        })}
+
+
+ ); +} + function ManualSqlNodeView({ data }: NodeProps) { + const [activeIssue, setActiveIssue] = useState(null); + const clearActive = useCallback(() => setActiveIssue(null), []); + return (
) {
- +
    - {data.notes.map((note) => ( -
  • -
  • setActiveIssue(note.id)} + onMouseLeave={clearActive} + onFocus={() => setActiveIssue(note.id)} + onBlur={clearActive} + tabIndex={0} > - × - - {note} -
    • - ))} + + {note.label} + + ); + })}
@@ -781,7 +908,7 @@ function CompiledSqlNodeView({ data }: NodeProps) { className="flex items-start gap-1.5 text-[11.5px] leading-4 text-fd-muted-foreground" >