@gntik-ai/blocks 0.0.0-stage → 0.6.0

package/src/builders/CodePanel/CodePanel.tsx

@@ -0,0 +1,239 @@
+import { useRef, useState } from 'react';
+import { CircleX, FileCode, Info, TriangleAlert } from '@gntik-ai/icons';
+import { CodeEditor, DiffEditor, type CodeEditorProps, type MonacoLoader, type Monaco } from '@gntik-ai/editor';
+import { Tabs, TabsList, TabsPanel, TabsTab, Toggle, ToggleGroup, cn } from '@gntik-ai/ui';
+import { NO_MARKERS, usePanelMarkers, useValidity, type CodePanelMarker, type MonacoReady } from './markers';
+import { codeFiles, codeProblems, type CodeFile, type CodeProblem, type ProblemSeverity } from './fixtures';
+
+export type { CodePanelMarker, MonacoReady } from './markers';
+export type { CodeFile, CodeProblem, ProblemSeverity } from './fixtures';
+
+type CodeEditorInstance = Parameters<NonNullable<CodeEditorProps['onMount']>>[0];
+type View = 'code' | 'diff';
+
+const SEVERITY: Record<ProblemSeverity, { label: string; icon: typeof CircleX; className: string }> = {
+  error: { label: 'Error', icon: CircleX, className: 'text-destructive-text' },
+  warning: { label: 'Warning', icon: TriangleAlert, className: 'text-warning-text' },
+  info: { label: 'Info', icon: Info, className: 'text-muted-foreground' },
+};
+
+export interface CodePanelProps {
+  files?: CodeFile[];
+  readOnly?: boolean;
+  markers?: readonly CodePanelMarker[];
+  /** Fires when the merged error count crosses zero (warnings do not invalidate). */
+  onValidityChange?: (valid: boolean) => void;
+  /** Configure consumer language services; optionally return their cleanup function. */
+  onMonacoReady?: MonacoReady;
+  problems?: CodeProblem[];
+  /** Path of the file opened first (uncontrolled; defaults to the first file). */
+  defaultFile?: string;
+  /** Path of the open file (controlled). Pair with `onActiveFileChange`. */
+  activeFile?: string;
+  /** Called with the path of the file to open (tab click, arrow keys, or a problem in another file). */
+  onActiveFileChange?: (path: string) => void;
+  /** Heading level of the "Problems" heading, to fit the page outline (default 3). */
+  headingLevel?: 2 | 3 | 4 | 5 | 6;
+  defaultView?: View;
+  /** Editor height (px or CSS length). */
+  height?: number | string;
+  /** Called with the file path and its new text on every edit. */
+  onChange?: (path: string, value: string) => void;
+  /** Called when a problem is picked in the list (the editor also jumps to it). */
+  onProblemSelect?: (problem: CodeProblem) => void;
+  /** Monaco loader passed to the editors (self-hosting, tests). Monaco loads lazily by default. */
+  loader?: MonacoLoader;
+  className?: string;
+}
+
+function basename(path: string) {
+  return path.split('/').pop() ?? path;
+}
+
+/**
+ * Multi-file code panel: file tabs, Monaco editor (or diff against the previous version) and
+ * a problems list that jumps to the reported line. Monaco is loaded lazily by @gntik-ai/editor.
+ */
+export function CodePanel({
+  files = codeFiles,
+  problems: suppliedProblems = codeProblems,
+  readOnly,
+  markers = NO_MARKERS,
+  onValidityChange,
+  onMonacoReady,
+  defaultFile,
+  activeFile: activeProp,
+  onActiveFileChange,
+  headingLevel = 3,
+  defaultView = 'code',
+  height = 360,
+  onChange,
+  onProblemSelect,
+  loader,
+  className,
+}: CodePanelProps) {
+  const collectMarkers = markers !== NO_MARKERS || onMonacoReady !== undefined || onValidityChange !== undefined;
+  const markerState = usePanelMarkers(markers, onMonacoReady, collectMarkers);
+  const problems = [...suppliedProblems, ...markers, ...markerState.problems];
+  const [innerActive, setInnerActive] = useState(defaultFile ?? files[0]?.path ?? '');
+  const active = activeProp ?? innerActive;
+  const setActive = (path: string) => {
+    if (path === active) return;
+    setInnerActive(path);
+    onActiveFileChange?.(path);
+  };
+  const ProblemsHeading = `h${headingLevel}` as const;
+  const [view, setView] = useState<View>(defaultView);
+  const [values, setValues] = useState<Record<string, string>>({});
+  const editors = useRef(new Map<string, CodeEditorInstance>());
+  const pending = useRef<CodeProblem | null>(null);
+
+  const currentFile = files.find((f) => f.path === active);
+  const canDiff = currentFile?.original !== undefined;
+  const effectiveView: View = canDiff ? view : 'code';
+  const errors = problems.filter((p) => p.severity === 'error').length;
+  useValidity(errors, onValidityChange);
+  const warnings = problems.filter((p) => p.severity === 'warning').length;
+
+  const reveal = (ed: CodeEditorInstance, problem: CodeProblem) => {
+    try {
+      ed.setPosition({ lineNumber: problem.line, column: problem.column ?? 1 });
+      ed.revealLineInCenter(problem.line);
+      ed.focus();
+    } catch {
+      /* editor not ready or disposed */
+    }
+  };
+
+  const selectProblem = (problem: CodeProblem) => {
+    onProblemSelect?.(problem);
+    setActive(problem.file);
+    setView('code');
+    const ed = editors.current.get(problem.file);
+    if (ed && ed.getModel() && problem.file === active && effectiveView === 'code') reveal(ed, problem);
+    else pending.current = problem;
+  };
+
+  const onMount = (path: string) => (ed: CodeEditorInstance, monaco: Monaco) => {
+    markerState.mount(path, ed, monaco);
+    editors.current.set(path, ed);
+    const p = pending.current;
+    if (p && p.file === path) {
+      pending.current = null;
+      reveal(ed, p);
+    }
+  };
+
+  const valueOf = (f: CodeFile) => values[f.path] ?? f.content;
+
+  return (
+    <section
+      aria-label="Code panel"
+      className={cn('flex flex-col overflow-hidden rounded-lg border border-border bg-card shadow-sm', className)}
+    >
+      <Tabs value={active} onValueChange={(v) => setActive(String(v))} className="gap-0">
+        <div className="flex flex-col gap-2 border-b border-border bg-secondary/35 px-3 pt-1 sm:flex-row sm:items-end sm:justify-between">
+          <TabsList aria-label="Open files" className="-mb-px gap-4 overflow-x-auto border-b-0">
+            {files.map((f) => {
+              const count = problems.filter((p) => p.file === f.path).length;
+              return (
+                <TabsTab
+                  key={f.path}
+                  value={f.path}
+                  icon={FileCode}
+                  count={count || undefined}
+                  className="font-mono text-[12px]"
+                >
+                  {basename(f.path)}
+                </TabsTab>
+              );
+            })}
+          </TabsList>
+          <ToggleGroup
+            aria-label="Editor view"
+            size="sm"
+            value={[effectiveView]}
+            onValueChange={(v) => v[0] && setView(v[0] as View)}
+            className="mb-2 self-start sm:self-auto"
+          >
+            <Toggle value="code">Edit</Toggle>
+            <Toggle value="diff" disabled={!canDiff}>
+              Diff
+            </Toggle>
+          </ToggleGroup>
+        </div>
+        {files.map((f) => (
+          <TabsPanel key={f.path} value={f.path} className="rounded-none">
+            {effectiveView === 'diff' && f.original !== undefined ? (
+              <DiffEditor
+                original={f.original}
+                modified={valueOf(f)}
+                language={f.language}
+                height={height}
+                aria-label={`${f.path} changes`}
+                loader={loader}
+                readOnly={readOnly}
+                onMount={(diff, monaco) => {
+                  const editor = diff.getModifiedEditor?.();
+                  if (editor) onMount(f.path)(editor, monaco);
+                }}
+              />
+            ) : (
+              <CodeEditor
+                value={valueOf(f)}
+                language={f.language}
+                height={height}
+                aria-label={f.path}
+                loader={loader}
+                readOnly={readOnly}
+                onMount={onMount(f.path)}
+                onChange={(v) => {
+                  setValues((prev) => ({ ...prev, [f.path]: v }));
+                  onChange?.(f.path, v);
+                }}
+              />
+            )}
+          </TabsPanel>
+        ))}
+      </Tabs>
+      <div className="border-t border-border">
+        <div className="flex items-center gap-3 bg-secondary/35 px-3 py-2">
+          <ProblemsHeading className="text-[12px] font-semibold tracking-wide text-foreground uppercase">
+            Problems
+          </ProblemsHeading>
+          <span className="font-mono text-[11px] text-muted-foreground">
+            {errors} {errors === 1 ? 'error' : 'errors'} · {warnings} {warnings === 1 ? 'warning' : 'warnings'}
+          </span>
+        </div>
+        {problems.length === 0 ? (
+          <p className="px-3 py-3 text-[12.5px] text-muted-foreground">No problems detected.</p>
+        ) : (
+          <ul aria-label="Problems" className="max-h-40 overflow-y-auto py-1">
+            {problems.map((p) => {
+              const sev = SEVERITY[p.severity];
+              const SevIcon = sev.icon;
+              return (
+                <li key={p.id}>
+                  <button
+                    type="button"
+                    onClick={() => selectProblem(p)}
+                    className="flex w-full items-start gap-2 px-3 py-1.5 text-start text-[12.5px] hover:bg-secondary/60 focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring"
+                  >
+                    <SevIcon size={14} aria-hidden className={cn('mt-0.5 shrink-0', sev.className)} />
+                    <span className="sr-only">{sev.label}:</span>
+                    <span className="min-w-0 flex-1 text-foreground">{p.message}</span>
+                    <span className="shrink-0 font-mono text-[11px] text-muted-foreground">
+                      {basename(p.file)}:{p.line}
+                      {p.column !== undefined ? `:${p.column}` : ''}
+                      {p.source ? ` · ${p.source}` : ''}
+                    </span>
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </div>
+    </section>
+  );
+}

package/src/builders/CodePanel/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Code panel',
+  family: 'builders',
+  status: 'beta',
+  description:
+    'Multi-file code panel with optional readOnly, owned line markers, onValidityChange and onMonacoReady, merging every Monaco marker owner into Problems; the lazy loader example injects inline YAML schemas and same-origin yaml workers under CSP. The open file can be controlled (activeFile, onActiveFileChange) and the heading level set (headingLevel). Optional readOnly prevents editor edits. markers accepts CodePanelMarker entries {id,owner,file,line,column?,endLine?,endColumn?,severity,message,source?}; each owner is reserved for its consumer diagnostics service. The Problems list merges problems, consumer markers, and Monaco model markers from every owner, including worker-backed YAML schema errors. onValidityChange(valid) fires only when errors cross zero (initially clean emits nothing); warnings do not invalidate. onMonacoReady(monaco) configures consumer services once per Monaco instance and may return cleanup. loader can configure monaco-yaml before mounting; the only supported YAML path is consumer-injected, with enableSchemaRequest:false and an inline schema. examples/diagnostics.tsx demonstrates a semantic-worker owner next to schema diagnostics. See packages/editor/README.md for the lazy Vite yaml.worker recipe, Monaco 0.57 compatibility alias, and CSP worker-src self blob: with same-origin scripts and assets. Supplying markers (including []), onMonacoReady or onValidityChange enables model-marker collection; readOnly controls editing independently. Omitting diagnostics extensions preserves the original supplied-problems-only view. No kit runtime dependency on monaco-yaml.',
+  uses: ['Tabs', 'ToggleGroup', 'Toggle', 'CodeEditor', 'DiffEditor'],
+};

package/src/builders/CodePanel/examples/controlled.tsx

@@ -0,0 +1,15 @@
+import { useState } from 'react';
+import { CodePanel } from '../CodePanel';
+
+/** The page owns the open file (e.g. to sync it with the URL) and places the panel under an h2. */
+export default function ControlledCodePanel() {
+  const [file, setFile] = useState('deploy.yaml');
+  return (
+    <div className="flex flex-col gap-2">
+      <p className="text-[12.5px] text-muted-foreground">
+        Open file: <span className="font-mono text-foreground">{file}</span>
+      </p>
+      <CodePanel activeFile={file} onActiveFileChange={setFile} headingLevel={4} />
+    </div>
+  );
+}

package/src/builders/CodePanel/examples/diagnostics.tsx

@@ -0,0 +1,40 @@
+import type { MonacoLoader } from '@gntik-ai/editor';
+import { CodePanel, type CodePanelMarker, type MonacoReady } from '../CodePanel';
+
+/** Inject the lazy same-origin loader from the editor README; the kit adds no YAML dependency. */
+export default function YamlDiagnosticsExample({
+  loader,
+  onMonacoReady,
+  markers,
+  readOnly = false,
+  onValidityChange,
+}: {
+  loader: MonacoLoader;
+  onMonacoReady?: MonacoReady;
+  markers?: readonly CodePanelMarker[];
+  readOnly?: boolean;
+  onValidityChange?: (valid: boolean) => void;
+}) {
+  return (
+    <CodePanel
+      files={[{ path: 'flow.yaml', language: 'yaml', content: 'count: wrong\n' }]}
+      problems={[]}
+      loader={loader}
+      onMonacoReady={onMonacoReady}
+      markers={
+        markers ?? [
+          {
+            id: 'terminal',
+            owner: 'semantic-worker',
+            severity: 'warning',
+            file: 'flow.yaml',
+            line: 1,
+            message: 'Review the terminal step.',
+          },
+        ]
+      }
+      readOnly={readOnly}
+      onValidityChange={onValidityChange}
+    />
+  );
+}

package/src/builders/CodePanel/fixtures.ts

@@ -0,0 +1,95 @@
+export interface CodeFile {
+  /** File path, shown as the tab label. */
+  path: string;
+  /** Monaco language id. */
+  language: string;
+  content: string;
+  /** Previous version; enables the diff view for this file. */
+  original?: string;
+}
+
+export type ProblemSeverity = 'error' | 'warning' | 'info';
+
+export interface CodeProblem {
+  id: string;
+  severity: ProblemSeverity;
+  message: string;
+  /** Path of the file the problem belongs to. */
+  file: string;
+  line: number;
+  column?: number;
+  /** Tool that reported it, e.g. "tsc" or "schema". */
+  source?: string;
+}
+
+const handlerBefore = `import { listProjects } from './store';
+
+export async function handler(req: Request) {
+  const projects = await listProjects();
+  return Response.json(projects);
+}
+`;
+
+const handlerAfter = `import { listProjects } from './store';
+
+export async function handler(req: Request) {
+  const limit = Number(new URL(req.url).searchParams.get('limit') ?? 20);
+  const projects = await listProjects({ limit });
+  return Response.json({ items: projects, limit });
+}
+`;
+
+export const codeFiles: CodeFile[] = [
+  { path: 'src/handler.ts', language: 'typescript', content: handlerAfter, original: handlerBefore },
+  {
+    path: 'deploy.yaml',
+    language: 'yaml',
+    content: `name: projects-api
+region: eu-west
+replicas: 2
+resources:
+  cpu: 500m
+  memory: 512Mi
+`,
+  },
+  {
+    path: 'settings.json',
+    language: 'json',
+    content: `{
+  "timeoutMs": 30000,
+  "retries": 3,
+  "logLevel": "info"
+}
+`,
+  },
+];
+
+export const codeProblems: CodeProblem[] = [
+  {
+    id: 'p1',
+    severity: 'error',
+    message: 'Expected 0 arguments, but got 1.',
+    file: 'src/handler.ts',
+    line: 5,
+    column: 43,
+    source: 'tsc',
+  },
+  {
+    id: 'p2',
+    severity: 'warning',
+    message: "'req' is declared but only read once; consider a typed query parser.",
+    file: 'src/handler.ts',
+    line: 3,
+    column: 31,
+    source: 'lint',
+  },
+  {
+    id: 'p3',
+    severity: 'info',
+    message: 'replicas: 2 is below the recommended minimum of 3 for production.',
+    file: 'deploy.yaml',
+    line: 3,
+    column: 1,
+    source: 'schema',
+  },
+];

package/src/builders/CodePanel/marker-store.ts

@@ -0,0 +1,90 @@
+import type { CodeEditorProps, Monaco } from '@gntik-ai/editor';
+import type { CodePanelMarker } from './markers';
+import type { CodeProblem } from './fixtures';
+
+type Editor = Parameters<NonNullable<CodeEditorProps['onMount']>>[0];
+const SEVERITY = { error: 8, warning: 4, info: 2 } as const;
+
+/** A cached external-store snapshot for Monaco's asynchronously produced diagnostics. */
+export function createMarkerStore() {
+  const models = new Map<string, ReturnType<Editor['getModel']>>();
+  const owners = new Map<string, Set<string>>();
+  const listeners = new Set<() => void>();
+  let api: Monaco | null = null;
+  let markers: readonly CodePanelMarker[] = [];
+  let snapshot: CodeProblem[] = [];
+  const refresh = () => {
+    if (!api?.editor.getModelMarkers) return;
+    const paths = new Map<string, string>();
+    for (const [path, model] of models) if (model?.uri) paths.set(model.uri.toString(), path);
+    const injectedOwners = new Set(markers.map((m) => m.owner));
+    const next: CodeProblem[] = [];
+    for (const marker of api.editor.getModelMarkers({})) {
+      const file = paths.get(marker.resource.toString());
+      if (!file || injectedOwners.has(marker.owner)) continue;
+      next.push({
+        id: `monaco:${marker.owner}:${file}:${marker.startLineNumber}:${marker.startColumn}:${next.length}`,
+        file,
+        line: marker.startLineNumber,
+        column: marker.startColumn,
+        message: marker.message,
+        severity: marker.severity === 8 ? 'error' : marker.severity === 4 ? 'warning' : 'info',
+        source: marker.source ?? marker.owner,
+      });
+    }
+    if (JSON.stringify(next) === JSON.stringify(snapshot)) return;
+    snapshot = next;
+    listeners.forEach((listener) => listener());
+  };
+  const clear = () => {
+    if (!api?.editor.setModelMarkers) return;
+    for (const [path, model] of models) {
+      if (!model || model.isDisposed?.()) continue;
+      for (const owner of owners.get(path) ?? []) api.editor.setModelMarkers(model, owner, []);
+    }
+  };
+  const apply = (next: readonly CodePanelMarker[]) => {
+    markers = next;
+    if (!api?.editor.setModelMarkers) return;
+    for (const [path, model] of models) {
+      if (!model || model.isDisposed?.()) continue;
+      const groups = new Map<string, CodePanelMarker[]>();
+      for (const marker of markers)
+        if (marker.file === path) groups.set(marker.owner, [...(groups.get(marker.owner) ?? []), marker]);
+      const previous = owners.get(path) ?? new Set<string>();
+      for (const owner of new Set([...previous, ...groups.keys()])) {
+        api.editor.setModelMarkers(
+          model,
+          owner,
+          (groups.get(owner) ?? []).map((marker) => ({
+            severity: SEVERITY[marker.severity],
+            message: marker.message,
+            source: marker.source ?? owner,
+            startLineNumber: marker.line,
+            startColumn: marker.column ?? 1,
+            endLineNumber: marker.endLine ?? marker.line,
+            endColumn: marker.endColumn ?? (marker.column ?? 1) + 1,
+          })),
+        );
+      }
+      owners.set(path, new Set(groups.keys()));
+    }
+    refresh();
+  };
+  return {
+    refresh,
+    clear,
+    apply,
+    mount(path: string, editor: Editor, monaco: Monaco) {
+      api = monaco;
+      models.set(path, editor.getModel());
+    },
+    getSnapshot: () => snapshot,
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}

package/src/builders/CodePanel/markers.ts

@@ -0,0 +1,62 @@
+import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
+import type { CodeEditorProps, Monaco } from '@gntik-ai/editor';
+import type { CodeProblem } from './fixtures';
+import { createMarkerStore } from './marker-store';
+
+/** Consumer line marker. Use a distinct owner for each external diagnostics service. */
+export interface CodePanelMarker extends CodeProblem {
+  owner: string;
+  endLine?: number;
+  endColumn?: number;
+}
+
+export type MonacoReady = (monaco: Monaco) => void | (() => void);
+type Editor = Parameters<NonNullable<CodeEditorProps['onMount']>>[0];
+export const NO_MARKERS: readonly CodePanelMarker[] = [];
+
+/** Observe Monaco's public marker API; schemas and their workers remain consumer-owned. */
+export function usePanelMarkers(
+  markers: readonly CodePanelMarker[],
+  onReady: MonacoReady | undefined,
+  enabled: boolean,
+) {
+  const [store] = useState(createMarkerStore);
+  const problems = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+  const [monaco, setMonaco] = useState<Monaco | null>(null);
+  const [revision, setRevision] = useState(0);
+  const ready = useRef(onReady);
+  useLayoutEffect(() => {
+    ready.current = onReady;
+  });
+  useEffect(() => {
+    if (!monaco || !enabled) return;
+    const subscription = monaco.editor.onDidChangeMarkers?.(store.refresh);
+    const cleanup = ready.current?.(monaco);
+    store.refresh();
+    return () => {
+      subscription?.dispose();
+      cleanup?.();
+      store.clear();
+    };
+  }, [monaco, store, enabled]);
+  useEffect(() => {
+    if (enabled) store.apply(markers);
+  }, [store, markers, monaco, revision, enabled]);
+  const mount = (path: string, editor: Editor, api: Monaco) => {
+    store.mount(path, editor, api);
+    setMonaco(api);
+    setRevision((v) => v + 1);
+  };
+  return { problems: enabled ? problems : [], mount };
+}
+
+export function useValidity(errors: number, onChange: ((valid: boolean) => void) | undefined) {
+  const wasValid = useRef(true);
+  useEffect(() => {
+    const valid = errors === 0;
+    if (wasValid.current !== valid) {
+      wasValid.current = valid;
+      onChange?.(valid);
+    }
+  }, [errors, onChange]);
+}