@manta-eu/react 0.1.9 → 0.2.0

package/src/explain-fact/ExplainFullView.tsx

@@ -0,0 +1,58 @@
+import { useEffect, useState, type ReactNode } from "react";
+import { ConclusionCard } from "./conclusion";
+import { ExplainInspector } from "./inspector";
+import { hasVisiblePremises, ProofTree } from "./proof-tree";
+import { ProofSubjectHeader } from "./ProofSubjectHeader";
+import type { ExplainDisplayMode, NormalizedTree } from "./tree-model";
+import { cn } from "#style";
+
+export type ExplainFullViewProps = {
+  tree: NormalizedTree;
+  substitutedFactNotice?: ReactNode;
+  mode: ExplainDisplayMode;
+  onModeChange: (mode: ExplainDisplayMode) => void;
+  subjectTerm: string;
+  className?: string;
+};
+
+export function ExplainFullView(props: ExplainFullViewProps) {
+  const { tree, mode, onModeChange, subjectTerm, substitutedFactNotice, className } = props;
+
+  const [selectedNodeId, setSelectedNodeId] = useState(tree.root.id);
+
+  useEffect(() => {
+    setSelectedNodeId((current) => (tree.byId[current] ? current : tree.root.id));
+  }, [tree]);
+
+  const selectedNode = tree.byId[selectedNodeId] ?? tree.root;
+  const showsProof = hasVisiblePremises(tree);
+
+  return (
+    <div className={cn("flex min-h-0 flex-col overflow-hidden", className)}>
+      <div className="shrink-0 space-y-2 border-b border-muted-border p-3.5">
+        {substitutedFactNotice}
+
+        <ConclusionCard tree={tree} mode={mode} onModeChange={onModeChange} />
+
+        <ProofSubjectHeader tree={tree} subjectTerm={subjectTerm} />
+      </div>
+
+      <div className={cn("grid min-h-0 flex-1", showsProof && "grid-cols-2")}>
+        {showsProof && (
+          <div className="min-h-0 overflow-auto border-r border-muted-border px-3.5 py-3">
+            <ProofTree
+              tree={tree}
+              mode={mode}
+              selectable
+              selectedNodeId={selectedNode.id}
+              onSelect={(id) => setSelectedNodeId((current) => (current === id ? tree.root.id : id))}
+            />
+          </div>
+        )}
+        <div className="min-h-0 overflow-auto px-3.5 py-3">
+          <ExplainInspector tree={tree} selectedNodeId={selectedNode.id} />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/explain-fact/ExplainStates.tsx

@@ -0,0 +1,92 @@
+import { Database, TriangleAlert, type LucideIcon } from "lucide-react";
+import { EmptyState } from "#components/empty-state/index";
+import { Skeleton } from "#components/skeleton/index";
+import { cn } from "#style";
+
+const skeletonRowWidths = ["w-1/2", "w-2/3", "w-3/5", "w-1/2", "w-2/3", "w-2/5"];
+
+export type ExplainRouteSkeletonProps = {
+  className?: string;
+};
+
+export function ExplainRouteSkeleton(props: ExplainRouteSkeletonProps) {
+  const { className } = props;
+
+  return (
+    <div
+      className={cn("flex min-h-0 flex-col overflow-hidden", className)}
+      aria-busy="true"
+      aria-label="Loading explanation"
+    >
+      <div className="grid min-h-0 flex-1 grid-cols-2">
+        <div className="flex min-h-0 flex-col gap-2 overflow-hidden border-r border-muted-border px-3.5 py-3">
+          <div className="flex items-center gap-2 px-0.5">
+            <Skeleton className="h-4 w-14" />
+            <Skeleton className="h-5 w-28 rounded-full" />
+          </div>
+          <div className="overflow-hidden rounded-md border border-muted-border bg-card/60">
+            {skeletonRowWidths.map((width, index) => (
+              <div
+                key={width + index}
+                className="flex items-center gap-3 border-t border-muted-border px-3 py-2.5 first:border-t-0"
+              >
+                <Skeleton className="size-4 rounded-full" />
+                <Skeleton className={cn("h-3.5", width)} />
+                <Skeleton className="ml-auto h-5 w-12 rounded-full" />
+              </div>
+            ))}
+          </div>
+        </div>
+
+        <div className="flex min-h-0 flex-col gap-4 overflow-hidden px-4 py-3">
+          <div className="flex flex-col gap-2">
+            <Skeleton className="h-5 w-48" />
+            <Skeleton className="h-3.5 w-full" />
+            <Skeleton className="h-3.5 w-2/3" />
+          </div>
+          <Skeleton className="h-8 w-full" />
+          <div className="flex flex-col gap-2">
+            <Skeleton className="h-3 w-28" />
+            <Skeleton className="h-28 w-full" />
+          </div>
+          <div className="flex flex-col gap-2">
+            <Skeleton className="h-3 w-28" />
+            <Skeleton className="h-20 w-full" />
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export type ExplainRouteMessageVariant = "empty" | "error";
+
+const messageIcons: Record<ExplainRouteMessageVariant, LucideIcon> = {
+  empty: Database,
+  error: TriangleAlert,
+};
+
+export type ExplainRouteMessageProps = {
+  variant: ExplainRouteMessageVariant;
+  title: string;
+  detail?: string;
+  className?: string;
+};
+
+export function ExplainRouteMessage(props: ExplainRouteMessageProps) {
+  const { variant, title, detail, className } = props;
+
+  const Icon = messageIcons[variant];
+
+  return (
+    <div className={cn("flex min-h-0 flex-1 flex-col overflow-hidden", className)}>
+      <EmptyState
+        icon={Icon}
+        title={title}
+        description={detail}
+        className={cn("h-full", variant === "error" && "text-error-foreground")}
+        iconClassName={variant === "error" ? "text-error-foreground" : undefined}
+      />
+    </div>
+  );
+}

package/src/explain-fact/ExplainTag.tsx

@@ -0,0 +1,43 @@
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+import { Badge } from "#components/badge/index";
+import { cn } from "#style";
+
+export type ExplainTagVariant = "computes" | "guard" | "absence" | "result" | "success" | "neutral";
+
+const explainTagSpecs: Record<ExplainTagVariant, string> = {
+  computes: "border-warning-foreground/30 bg-warning-foreground/10 text-warning-foreground",
+  guard: "border-muted-foreground/30 bg-muted-foreground/10 text-muted-foreground",
+  absence: "border-error-foreground/30 bg-error-foreground/10 text-error-foreground",
+  result: "border-primary/30 bg-primary/10 text-primary",
+  success: "border-success-foreground/30 bg-success-foreground/10 text-success-foreground",
+  neutral: "border-muted-border bg-muted text-muted-foreground",
+};
+
+const explainTagLabels: Record<ExplainTagVariant, string> = {
+  computes: "Computes",
+  guard: "Guard",
+  absence: "Absence",
+  result: "Result",
+  success: "Success",
+  neutral: "Neutral",
+};
+
+export type ExplainTagProps = {
+  variant: ExplainTagVariant;
+  icon?: LucideIcon;
+  title?: string;
+  children?: ReactNode;
+  className?: string;
+};
+
+export function ExplainTag(props: ExplainTagProps) {
+  const { variant, icon: Icon, title, children, className } = props;
+
+  return (
+    <Badge size="sm" title={title} className={cn("border", explainTagSpecs[variant], className)}>
+      {Icon && <Icon />}
+      {children ?? explainTagLabels[variant]}
+    </Badge>
+  );
+}

package/src/explain-fact/FactNotice.tsx

@@ -0,0 +1,51 @@
+import type { FactProvenance } from "./tree-model";
+import { cn } from "#style";
+
+type FactNoticeSpec = {
+  text: string;
+  className: string;
+};
+
+const truncatedText = "The reasoner did not return the rules that derive this fact.";
+
+const factNoticeSpecs: Record<FactProvenance, FactNoticeSpec> = {
+  explicit: {
+    text: "This fact is stored directly. No rule produced it.",
+    className: "border-muted-border bg-background/50",
+  },
+  unsupported: {
+    text:
+      "The reasoner reports this fact as derived but names no rule that produces it. It is a leftover " +
+      "in the materialization, and rematerializing the datastore removes it.",
+    className: "border-warning-foreground/40 bg-warning-foreground/5",
+  },
+  absent: {
+    text: "This fact is not in the graph. Nothing asserts it and no rule derives it.",
+    className: "border-error-foreground/40 bg-error/5",
+  },
+  derived: { text: truncatedText, className: "border-muted-border bg-background/50" },
+  computed: { text: truncatedText, className: "border-muted-border bg-background/50" },
+};
+
+export type FactNoticeProps = {
+  provenance?: FactProvenance;
+  className?: string;
+};
+
+export function FactNotice(props: FactNoticeProps) {
+  const { provenance, className } = props;
+
+  const spec = factNoticeSpecs[provenance ?? "explicit"];
+
+  return (
+    <p
+      className={cn(
+        "rounded-md border border-dashed p-4 typography-small text-muted-foreground",
+        spec.className,
+        className,
+      )}
+    >
+      {spec.text}
+    </p>
+  );
+}

package/src/explain-fact/FactValue.tsx

@@ -0,0 +1,80 @@
+import {
+  isDateTimeLiteral,
+  isLiteralTerm,
+  isNumericLiteralTerm,
+  literalToDisplayText,
+  parseBooleanLiteral,
+  parseDatalogTermText,
+} from "@manta-eu/datalog-parser";
+import { isPresent } from "@manta-eu/lib/present";
+import { Check, Sparkles, X } from "lucide-react";
+import { useMemo } from "react";
+import { formatMeasureValue } from "../lib/measure";
+import { MaskedValue, maskText } from "../ontology/MaskedValue";
+import { ontologyTermIri } from "../ontology/OntologyTermText";
+import { isBlankNode } from "../ontology/skolem";
+import { usePersonalDataResolution } from "../ontology/use-personal-data";
+import { EntityChip } from "./EntityChip";
+import { useFactMeasure } from "./use-fact-measure";
+import { ValuePill } from "./ValuePill";
+import { cn } from "#style";
+
+export type FactValueProps = {
+  value: string;
+  predicate?: string;
+  className?: string;
+};
+
+export function FactValue(props: FactValueProps) {
+  const { value, predicate, className } = props;
+
+  const measure = useFactMeasure(predicate);
+  const personalData = usePersonalDataResolution(predicate);
+  const term = useMemo(() => parseDatalogTermText(value), [value]);
+  const literal = isPresent(term) && isLiteralTerm(term) ? term : undefined;
+  const boolean = parseBooleanLiteral(value);
+  const isEntityValue = isBlankNode(value) || isPresent(ontologyTermIri(value));
+
+  if (personalData.status !== "resolved" && !isEntityValue) {
+    return <span className={cn("tracking-wider text-muted-foreground", className)}>{maskText}</span>;
+  }
+
+  if (personalData.status === "resolved" && isPresent(personalData.categories) && !isEntityValue) {
+    return <MaskedValue value={literal?.value ?? value} categories={personalData.categories} className={className} />;
+  }
+
+  if (boolean !== undefined) {
+    const Icon = boolean ? Check : X;
+
+    return (
+      <span
+        className={cn(
+          "inline-flex items-center gap-1 typography-small-medium",
+          boolean ? "text-success-foreground" : "text-muted-foreground",
+          className,
+        )}
+      >
+        <Icon className="size-3.5" />
+        {boolean ? "true" : "false"}
+      </span>
+    );
+  }
+
+  if (isPresent(term) && isNumericLiteralTerm(term)) {
+    return <ValuePill className={className}>{formatMeasureValue(term.value, measure)}</ValuePill>;
+  }
+
+  if (literal) {
+    return (
+      <ValuePill className={className}>
+        {isDateTimeLiteral(literal) ? literalToDisplayText(literal) : literal.value}
+      </ValuePill>
+    );
+  }
+
+  if (isEntityValue) {
+    return <EntityChip term={value} icon={Sparkles} className={className} />;
+  }
+
+  return <ValuePill className={className}>{value}</ValuePill>;
+}

package/src/explain-fact/NumDot.tsx

@@ -0,0 +1,23 @@
+import { cn } from "#style";
+
+export type NumDotProps = {
+  number: number;
+  active?: boolean;
+  className?: string;
+};
+
+export function NumDot(props: NumDotProps) {
+  const { number, active, className } = props;
+
+  return (
+    <span
+      className={cn(
+        "inline-flex size-4 shrink-0 items-center justify-center rounded-full typography-tiny-semibold leading-none",
+        active ? "bg-primary text-primary-foreground" : "border border-default-border bg-accent text-muted-foreground",
+        className,
+      )}
+    >
+      {number}
+    </span>
+  );
+}

package/src/explain-fact/PanelLabel.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react";
+import { sectionLabelClass } from "./explain-styles";
+import { cn } from "#style";
+
+export type PanelLabelProps = {
+  children: ReactNode;
+  right?: ReactNode;
+  tickClassName?: string;
+  className?: string;
+};
+
+export function PanelLabel(props: PanelLabelProps) {
+  const { children, right, tickClassName, className } = props;
+
+  return (
+    <div className={cn("flex items-center justify-between gap-2", className)}>
+      <span className="flex items-center gap-2">
+        <span
+          aria-hidden
+          className={cn("w-[3px] shrink-0 self-stretch rounded-[2px]", tickClassName ?? "bg-primary")}
+        />
+        <span className={cn(sectionLabelClass, "text-body-foreground")}>{children}</span>
+      </span>
+      {right}
+    </div>
+  );
+}

package/src/explain-fact/ProofSubjectHeader.tsx

@@ -0,0 +1,24 @@
+import { EntityChip } from "./EntityChip";
+import { PanelLabel } from "./PanelLabel";
+import { hasVisiblePremises } from "./proof-tree";
+import { subjectTypeTerm, type NormalizedTree } from "./tree-model";
+import { cn } from "#style";
+
+export type ProofSubjectHeaderProps = {
+  tree: NormalizedTree;
+  subjectTerm: string;
+  className?: string;
+};
+
+export function ProofSubjectHeader(props: ProofSubjectHeaderProps) {
+  const { tree, subjectTerm, className } = props;
+
+  if (!hasVisiblePremises(tree)) return null;
+
+  return (
+    <div className={cn("flex items-center gap-2 px-0.5", className)}>
+      <PanelLabel className="shrink-0">Because, for</PanelLabel>
+      <EntityChip term={subjectTerm} typeTerm={subjectTypeTerm(tree, subjectTerm)} />
+    </div>
+  );
+}

package/src/explain-fact/ProvenanceBadge.tsx

@@ -0,0 +1,37 @@
+import { Ban, Database, Sparkles, SquareFunction, Unplug, type LucideIcon } from "lucide-react";
+import type { FactProvenance } from "./tree-model";
+import { Badge } from "#components/badge/index";
+import { cn } from "#style";
+
+type ProvenanceBadgeSpec = {
+  label: string;
+  icon: LucideIcon;
+  className: string;
+};
+
+const provenanceBadgeSpecs: Record<FactProvenance, ProvenanceBadgeSpec> = {
+  explicit: { label: "Explicit", icon: Database, className: "text-muted-foreground" },
+  derived: { label: "Derived", icon: Sparkles, className: "text-primary" },
+  computed: { label: "Computed", icon: SquareFunction, className: "text-warning-foreground" },
+  unsupported: { label: "Nothing derives it", icon: Unplug, className: "text-warning-foreground" },
+  absent: { label: "Not in the graph", icon: Ban, className: "text-error-foreground" },
+};
+
+export type ProvenanceBadgeProps = {
+  provenance: FactProvenance;
+  className?: string;
+};
+
+export function ProvenanceBadge(props: ProvenanceBadgeProps) {
+  const { provenance, className } = props;
+
+  const spec = provenanceBadgeSpecs[provenance];
+  const Icon = spec.icon;
+
+  return (
+    <Badge size="base" className={cn("rounded-full border border-muted-border bg-muted", spec.className, className)}>
+      <Icon />
+      {spec.label}
+    </Badge>
+  );
+}

package/src/explain-fact/RuleVariableTypes.tsx

@@ -0,0 +1,81 @@
+import { collectVariableTypeEvidence, resolveVariableTypes } from "@manta-eu/datalog-parser";
+import { isPresent } from "@manta-eu/lib/present";
+import { isNotNil } from "ramda";
+import { useMemo } from "react";
+import { humanizePredicateName } from "../graph/graph-utils";
+import { useOntologyTerms } from "../hooks/use-ontology-terms";
+import { ontologyTermIri, OntologyTermText } from "../ontology/OntologyTermText";
+import { parseDatalogRuleCached } from "../rules/datalog-cache";
+import { article } from "../rules/rule-narrative-format";
+import { cn } from "#style";
+
+export type RuleVariableTypesProps = {
+  ruleText: string;
+  className?: string;
+};
+
+function typeFallbackLabel(typeTerm: string): string {
+  return humanizePredicateName(typeTerm);
+}
+
+export function RuleVariableTypes(props: RuleVariableTypesProps) {
+  const { ruleText, className } = props;
+
+  const evidence = useMemo(() => {
+    const ast = parseDatalogRuleCached(ruleText).ast;
+
+    return ast ? collectVariableTypeEvidence(ast) : [];
+  }, [ruleText]);
+
+  const predicateIris = useMemo(() => {
+    const iris = evidence.flatMap((entry) =>
+      entry.predicateEvidence.map((predicateEvidence) => ontologyTermIri(predicateEvidence.term)),
+    );
+
+    return [...new Set(iris.filter(isNotNil))];
+  }, [evidence]);
+
+  const predicateTerms = useOntologyTerms(predicateIris);
+
+  const variableTypes = useMemo(
+    () =>
+      resolveVariableTypes(evidence, (term) => {
+        const iri = ontologyTermIri(term);
+
+        return iri ? predicateTerms.get(iri) : undefined;
+      }),
+    [evidence, predicateTerms],
+  );
+
+  const typeIris = useMemo(
+    () => [...new Set(variableTypes.map((variableType) => ontologyTermIri(variableType.typeTerm)).filter(isNotNil))],
+    [variableTypes],
+  );
+
+  const typeTerms = useOntologyTerms(typeIris);
+
+  if (!isPresent(variableTypes)) return null;
+
+  return (
+    <div className={cn("flex flex-wrap items-baseline gap-x-3.5 gap-y-1", className)}>
+      {variableTypes.map((variableType) => {
+        const typeIri = ontologyTermIri(variableType.typeTerm);
+        const resolvedLabel = typeIri ? typeTerms.get(typeIri)?.label : undefined;
+        const label = resolvedLabel ?? typeFallbackLabel(variableType.typeTerm);
+
+        return (
+          <span key={variableType.variable} className="typography-tiny">
+            <span className="font-mono text-warning-foreground">{variableType.variable}</span>
+            <span className="text-muted-foreground"> is {article(label)} </span>
+            <OntologyTermText
+              term={variableType.typeTerm}
+              fallbackLabel={typeFallbackLabel(variableType.typeTerm)}
+              resolveInstanceLabel={false}
+              className="typography-tiny-medium text-body-foreground"
+            />
+          </span>
+        );
+      })}
+    </div>
+  );
+}

package/src/explain-fact/SubstitutedFactNotice.tsx

@@ -0,0 +1,29 @@
+import { termTextsEqual } from "@manta-eu/datalog-parser";
+import { Replace } from "lucide-react";
+import { predicateLabel } from "../rules/rule-narrative-format";
+import type { FactSpo } from "./tree-model";
+import { Banner } from "#components/banner/index";
+
+export type SubstitutedFactNoticeProps = {
+  requested: FactSpo;
+  explained?: FactSpo;
+  className?: string;
+};
+
+export function SubstitutedFactNotice(props: SubstitutedFactNoticeProps) {
+  const { requested, explained, className } = props;
+
+  if (!explained || requested.predicate !== explained.predicate) return null;
+  if (termTextsEqual(requested.object, explained.object) !== false) return null;
+
+  return (
+    <Banner
+      size="loose"
+      type="muted"
+      icon={Replace}
+      label={`No fact matches ${predicateLabel(requested.predicate ?? "rdf:type")} ${requested.object}`}
+      description="Explaining the value the graph holds instead."
+      className={className}
+    />
+  );
+}

package/src/explain-fact/ValuePill.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import { Badge } from "#components/badge/index";
+import { cn } from "#style";
+
+export type ValuePillProps = {
+  children: ReactNode;
+  className?: string;
+};
+
+export function ValuePill(props: ValuePillProps) {
+  const { children, className } = props;
+
+  return (
+    <Badge
+      size="base"
+      className={cn("min-w-0 shrink border border-muted-border bg-muted font-mono text-default-foreground", className)}
+    >
+      <span className="min-w-0 truncate">{children}</span>
+    </Badge>
+  );
+}

package/src/explain-fact/conclusion/ConclusionCard.tsx

@@ -0,0 +1,93 @@
+import { Sparkles } from "lucide-react";
+import { FactValue } from "../FactValue";
+import { ProvenanceBadge } from "../ProvenanceBadge";
+import { RuleVariableTypes } from "../RuleVariableTypes";
+import { isTypeFact, type ExplainDisplayMode, type NormalizedTree } from "../tree-model";
+import { ConclusionSubtitle } from "./ConclusionSubtitle";
+import { Tabs, TabsList, TabsTrigger } from "#components/tabs/index";
+import { OntologyTermText } from "#ontology/OntologyTermText";
+import { classLabel, predicateLabel } from "#rules/rule-narrative-format";
+import { cn } from "#style";
+
+type DisplayModeOption = {
+  value: ExplainDisplayMode;
+  label: string;
+};
+
+const displayModeOptions: DisplayModeOption[] = [
+  { value: "labels", label: "Labels" },
+  { value: "datalog", label: "Datalog" },
+];
+
+export type ConclusionCardProps = {
+  tree: NormalizedTree;
+  mode: ExplainDisplayMode;
+  onModeChange?: (mode: ExplainDisplayMode) => void;
+  className?: string;
+};
+
+export function ConclusionCard(props: ConclusionCardProps) {
+  const { tree, mode, onModeChange, className } = props;
+
+  const root = tree.root;
+  const titleTerm = isTypeFact(root) ? root.spo?.object : root.spo?.predicate;
+
+  return (
+    <div className={cn("rounded-md border border-default-border bg-card px-3.5 py-4", className)}>
+      <div className="flex items-center gap-3">
+        <span className="flex size-8 shrink-0 items-center justify-center rounded-sm bg-primary/15 text-primary">
+          <Sparkles className="size-4" />
+        </span>
+
+        <div className="min-w-0 flex-1">
+          <div className="flex items-baseline gap-2.5">
+            <span className="truncate typography-small-semibold text-default-foreground first-letter:uppercase">
+              {titleTerm ? (
+                <OntologyTermText
+                  term={titleTerm}
+                  fallbackLabel={isTypeFact(root) ? classLabel(titleTerm) : predicateLabel(titleTerm)}
+                  className="no-underline"
+                />
+              ) : (
+                root.display
+              )}
+            </span>
+            {root.spo && !isTypeFact(root) && (
+              <FactValue value={root.spo.object} predicate={root.spo.predicate} className="max-w-[50%] shrink-0" />
+            )}
+          </div>
+          <div className="mt-0.5 truncate typography-tiny text-muted-foreground">
+            {mode === "datalog" ? (
+              <span className="font-mono">{root.display}</span>
+            ) : (
+              <ConclusionSubtitle tree={tree} />
+            )}
+          </div>
+        </div>
+
+        <ProvenanceBadge provenance={root.provenance ?? "derived"} />
+        {onModeChange && (
+          <Tabs
+            size="small"
+            value={mode}
+            onValueChange={(next) => {
+              const option = displayModeOptions.find((candidate) => candidate.value === next);
+
+              if (option) onModeChange(option.value);
+            }}
+          >
+            <TabsList>
+              {displayModeOptions.map((option) => (
+                <TabsTrigger key={option.value} value={option.value}>
+                  {option.label}
+                </TabsTrigger>
+              ))}
+            </TabsList>
+          </Tabs>
+        )}
+      </div>
+
+      {mode === "datalog" && root.rule && <RuleVariableTypes ruleText={root.rule} className="mt-2.5" />}
+    </div>
+  );
+}