@manta-eu/react 0.1.8 → 0.1.10

package/src/shacl/ShaclFormProvider.tsx

@@ -0,0 +1,113 @@
+import type { IRI } from "@manta-eu/rdf-lib/namespaces";
+import type { SerializationFormat, ShaclFormElement } from "@ulb-darmstadt/shacl-form";
+import type { ReactNode, RefObject } from "react";
+import { createContext, use, useCallback, useEffect, useMemo, useState, useRef } from "react";
+
+export type ShaclShapesSource = {
+  turtle: string | null;
+  shapeIris: readonly IRI[];
+  isLoading: boolean;
+  error: string | null;
+  onSelectShape: (shapeIri?: IRI) => void;
+  refetch: () => void;
+};
+
+export type ShaclFormContextValue = {
+  shapesGraph: string | null;
+  valuesGraph: string | null;
+  valuesSubject: string | null;
+  isValid: boolean;
+  viewMode: boolean;
+  formRef: RefObject<ShaclFormElement | null>;
+  availableShapeIris: Set<IRI>;
+  isLoadingShapes: boolean;
+  shapesError: string | null;
+  setShapesGraph: (shapes: string) => void;
+  setValuesGraph: (values: string | null, subject?: string) => void;
+  setViewMode: (viewMode: boolean) => void;
+  setIsValid: (isValid: boolean) => void;
+  serialize: (format?: SerializationFormat) => string | null;
+  validate: () => Promise<boolean>;
+  loadShapes: (shapeIri?: IRI) => void;
+  refetchShapes: () => void;
+};
+
+const ShaclFormContext = createContext<ShaclFormContextValue | undefined>(undefined);
+
+export type ShaclFormProviderProps = {
+  children: ReactNode;
+  shapes: ShaclShapesSource;
+};
+
+export function ShaclFormProvider(props: ShaclFormProviderProps) {
+  const { children, shapes } = props;
+
+  const formRef = useRef<ShaclFormElement | null>(null);
+  const [shapesGraph, setShapesGraphState] = useState<string | null>(null);
+  const [valuesGraph, setValuesGraphState] = useState<string | null>(null);
+  const [valuesSubject, setValuesSubject] = useState<string | null>(null);
+  const [isValid, setIsValid] = useState(false);
+  const [viewMode, setViewMode] = useState(false);
+
+  const availableShapeIris = useMemo(() => new Set<IRI>(shapes.shapeIris), [shapes.shapeIris]);
+
+  useEffect(() => {
+    if (shapes.turtle) {
+      setShapesGraphState(shapes.turtle);
+    }
+  }, [shapes.turtle]);
+
+  const setShapesGraph = useCallback((next: string) => {
+    setShapesGraphState(next);
+  }, []);
+
+  const setValuesGraph = useCallback((values: string | null, subject?: string) => {
+    setValuesGraphState(values);
+    if (subject !== undefined) {
+      setValuesSubject(subject);
+    }
+  }, []);
+
+  const serialize = useCallback((format?: SerializationFormat): string | null => {
+    if (!formRef.current) return null;
+    return formRef.current.serialize(format);
+  }, []);
+
+  const validate = useCallback(async (): Promise<boolean> => {
+    if (!formRef.current) return false;
+    const report = await formRef.current.validate();
+    return report.conforms;
+  }, []);
+
+  const value: ShaclFormContextValue = {
+    shapesGraph,
+    valuesGraph,
+    valuesSubject,
+    isValid,
+    viewMode,
+    formRef,
+    availableShapeIris,
+    isLoadingShapes: shapes.isLoading,
+    shapesError: shapes.error,
+    setShapesGraph,
+    setValuesGraph,
+    setViewMode,
+    setIsValid,
+    serialize,
+    validate,
+    loadShapes: shapes.onSelectShape,
+    refetchShapes: shapes.refetch,
+  };
+
+  return <ShaclFormContext.Provider value={value}>{children}</ShaclFormContext.Provider>;
+}
+
+export function useShaclForm(): ShaclFormContextValue {
+  const context = use(ShaclFormContext);
+
+  if (!context) {
+    throw new Error("useShaclForm must be used within a ShaclFormProvider");
+  }
+
+  return context;
+}

package/src/shacl/form-appearance.ts

@@ -0,0 +1,214 @@
+import { isFullIri } from "@manta-eu/rdf-lib/namespaces";
+import { formatPropertyLabel } from "../lib/iri-labels";
+
+/** Shadow-root styling: page-level `shacl-form` rules cannot reach inside, but the app's color tokens do inherit. */
+const shaclFormCss = `
+form {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+/* A grid gives the label its own line; the shipped fixed-width side label overruns generated names. */
+.property-instance {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 0.25rem 0.5rem;
+  padding: 0;
+}
+
+.property-instance > label {
+  grid-column: 1 / -1;
+}
+
+/* Booleans ship as a native checkbox; restyle as a switch so on/off rows read like every other field. */
+.property-instance > .editor[type="checkbox"] {
+  appearance: none;
+  justify-self: start;
+  width: 2rem;
+  height: 1.125rem;
+  margin: 0.125rem 0;
+  padding: 0;
+  position: relative;
+  border: 1px solid var(--color-input-border);
+  border-radius: 9999px;
+  background-color: var(--color-input);
+  cursor: pointer;
+  transition: background-color 120ms ease, border-color 120ms ease;
+}
+
+.property-instance > .editor[type="checkbox"]::before {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 2px;
+  width: 0.75rem;
+  height: 0.75rem;
+  border-radius: 9999px;
+  background-color: var(--color-muted-foreground);
+  transform: translateY(-50%);
+  transition: left 120ms ease, background-color 120ms ease;
+}
+
+.property-instance > .editor[type="checkbox"]:checked {
+  border-color: var(--color-accent-foreground);
+  background-color: var(--color-accent-foreground);
+}
+
+.property-instance > .editor[type="checkbox"]:checked::before {
+  left: calc(100% - 0.75rem - 2px);
+  background-color: var(--color-base-background);
+}
+
+.property-instance label,
+.mode-view .property-instance label {
+  width: auto;
+  padding: 0;
+  color: var(--color-muted-foreground);
+  font-size: var(--text-sm);
+  font-weight: 500;
+  line-height: 1.4;
+}
+
+/* Labels carry the property IRI as a tooltip; the shipped "help" underline made every row look like a warning. */
+.property-instance label[title] {
+  cursor: default;
+  text-decoration: none;
+}
+
+.editor:not([type="checkbox"]) {
+  width: 100%;
+  box-sizing: border-box;
+  border: 1px solid var(--color-input-border);
+  border-radius: var(--radius);
+  background-color: var(--color-input);
+  color: var(--color-default-foreground);
+  font-size: var(--text-sm);
+  padding: 0.375rem 0.625rem;
+}
+
+.editor:focus {
+  border-color: var(--color-active-border);
+  outline: none;
+  box-shadow: 0 0 0 1px var(--color-active-border);
+}
+
+.property-instance.valid::before,
+.validation-error {
+  left: 0;
+}
+
+.collapsible::part(label) {
+  color: var(--color-default-foreground);
+  font-size: var(--text-sm);
+  font-weight: 600;
+}
+
+/* Remove-value and add-value controls are secondary to the fields themselves. */
+.add-button,
+button {
+  color: var(--color-muted-foreground);
+  font-size: var(--text-sm);
+  opacity: 0.6;
+}
+
+.add-button:hover,
+button:hover {
+  opacity: 1;
+}
+`;
+
+let formSheet: CSSStyleSheet | null = null;
+
+/** Adopts the sheet instead of swapping the theme, which would re-initialize the form and lose in-progress edits. */
+export function applyFormStyles(root: ShadowRoot | null | undefined): void {
+  if (!root) return;
+
+  if (!formSheet) {
+    formSheet = new CSSStyleSheet();
+    formSheet.replaceSync(shaclFormCss);
+  }
+
+  const adopted = root.adoptedStyleSheets ?? [];
+
+  if (adopted.includes(formSheet)) return;
+
+  root.adoptedStyleSheets = [...adopted, formSheet];
+}
+
+/** View mode renders the label as `<iri>:`, which would humanize to nothing. */
+function labelIri(raw: string): string {
+  return raw.trim().replace(/:$/, "");
+}
+
+/** Generated shapes carry no `sh:name`, so the form labels rows with the raw property IRI; restate it as a name. */
+export function formLabelText(raw: string): string | null {
+  const text = labelIri(raw);
+
+  if (!isFullIri(text)) return null;
+
+  return formatPropertyLabel(text);
+}
+
+function propertyPathsByBlankNode(turtle: string): Map<string, string> {
+  const paths = new Map<string, string>();
+  let current: string | null = null;
+
+  for (const line of turtle.split("\n")) {
+    const subject = /^(\S+)(?:\s|$)/.exec(line)?.[1];
+
+    if (subject) current = subject.startsWith("_:") ? subject : null;
+
+    const path = /\bsh:path\s+<?([^\s;>]+)>?\s*;?/.exec(line)?.[1];
+
+    if (current && path) paths.set(current, path);
+  }
+
+  return paths;
+}
+
+/** RDFox emits `sh:property` in arbitrary order, reshuffling fields on every open; reorder by path local name. */
+export function sortShapeProperties(turtle: string): string {
+  const paths = propertyPathsByBlankNode(turtle);
+  const localName = (node: string) => {
+    const path = paths.get(node) ?? node;
+    return path.split(/[#/:]/).pop()?.toLowerCase() ?? path;
+  };
+
+  // The label stops at Turtle punctuation: `\S+` would swallow an adjacent `.` or `;` into the list.
+  return turtle.replace(/\bsh:property\s+((?:_:[^\s,;.]+\s*,\s*)*_:[^\s,;.]+)/g, (_match, list: string) => {
+    const nodes = list
+      .split(",")
+      .map((node) => node.trim())
+      .sort((a, b) => localName(a).localeCompare(localName(b)));
+
+    return `sh:property ${nodes.join(" , ")}`;
+  });
+}
+
+function humanizeFormLabels(root: ShadowRoot): void {
+  for (const label of root.querySelectorAll("label")) {
+    const humanized = formLabelText(label.textContent ?? "");
+
+    if (!humanized) continue;
+
+    label.title = labelIri(label.textContent ?? "");
+    label.textContent = humanized;
+  }
+}
+
+/**
+ * Rows arrive after `ready`, so one pass misses some. A rewritten label no longer looks like an
+ * IRI, so there is no re-entry.
+ */
+export function observeFormLabels(root: ShadowRoot | null | undefined): () => void {
+  if (!root) return () => {};
+
+  humanizeFormLabels(root);
+
+  const observer = new MutationObserver(() => humanizeFormLabels(root));
+  observer.observe(root, { childList: true, subtree: true });
+
+  return () => observer.disconnect();
+}

package/src/shacl/index.ts

@@ -0,0 +1,17 @@
+export {
+  findShapeForTypes,
+  getAllRegisteredShapes,
+  getShapeForType,
+  hasShapeForType,
+  registerShape,
+  type ShapeRegistryEntry,
+} from "./shape-registry";
+export { jsonLdToTurtle } from "./jsonld-to-turtle";
+export { ShaclForm, type ShaclFormProps } from "./ShaclForm";
+export {
+  ShaclFormProvider,
+  useShaclForm,
+  type ShaclFormContextValue,
+  type ShaclFormProviderProps,
+  type ShaclShapesSource,
+} from "./ShaclFormProvider";

package/src/shacl/jsonld-to-turtle.ts

@@ -0,0 +1,91 @@
+import { arrayWrap } from "@manta-eu/lib/array";
+import type { JsonLdValue } from "@manta-eu/rdf-lib/jsonld";
+import { compactUri, isFullIri, isIsoDatetime, isPrefixedIri, toTurtlePrefixes } from "@manta-eu/rdf-lib/namespaces";
+
+function compactIriForTurtle(iri: string): string {
+  const compacted = compactUri(iri);
+  if (compacted === iri && isFullIri(iri)) {
+    return `<${iri}>`;
+  }
+  return compacted;
+}
+
+export function jsonLdToTurtle(jsonLd: Record<string, unknown>, subjectIri: string): string {
+  const lines: string[] = [toTurtlePrefixes(), ""];
+
+  const formattedSubject = isFullIri(subjectIri) ? `<${subjectIri}>` : subjectIri;
+  const predicates: string[] = [];
+
+  const typeValue = jsonLd["@type"];
+  if (typeValue) {
+    const types = arrayWrap(typeValue);
+    for (const t of types) {
+      if (typeof t === "string") {
+        predicates.push(`  a ${compactIriForTurtle(t)}`);
+      }
+    }
+  }
+
+  for (const [key, value] of Object.entries(jsonLd)) {
+    if (key.startsWith("@")) continue;
+
+    const formattedValue = formatValue(value as JsonLdValue);
+    if (formattedValue !== null) {
+      const predicate = compactIriForTurtle(key);
+      predicates.push(`  ${predicate} ${formattedValue}`);
+    }
+  }
+
+  if (predicates.length > 0) {
+    lines.push(`${formattedSubject}`);
+    lines.push(predicates.join(" ;\n") + " .");
+  }
+
+  return lines.join("\n");
+}
+
+function formatValue(value: JsonLdValue): string | null {
+  if (value === null || value === undefined) {
+    return null;
+  }
+
+  if (typeof value === "string") {
+    if (isFullIri(value)) {
+      return `<${value}>`;
+    }
+
+    if (isIsoDatetime(value)) {
+      return `"${value}"^^xsd:dateTime`;
+    }
+
+    if (isPrefixedIri(value)) {
+      return value;
+    }
+
+    const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+    return `"${escaped}"`;
+  }
+
+  if (typeof value === "number") {
+    return Number.isInteger(value) ? String(value) : `"${value}"^^xsd:decimal`;
+  }
+
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+
+  if (typeof value === "object" && !Array.isArray(value)) {
+    if (value["@id"]) {
+      const id = value["@id"];
+      if (isFullIri(id)) {
+        return `<${id}>`;
+      }
+      return id;
+    }
+    if (value["@value"] !== undefined) {
+      return formatValue(value["@value"] as JsonLdValue);
+    }
+  }
+
+  return null;
+}

package/src/shacl/shacl-form-types.ts

@@ -0,0 +1,62 @@
+// Loaded via side-effect import in ShaclForm.tsx.
+
+import "react";
+
+declare module "@ulb-darmstadt/shacl-form" {
+  export type SerializationFormat =
+    | "text/turtle"
+    | "application/ld+json"
+    | "application/n-triples"
+    | "application/n-quads";
+
+  /** Mirrors the shipped ValidationReport; `validate` resolves this, never a boolean. */
+  export interface ShaclFormValidationReport {
+    conforms: boolean;
+    results: unknown[];
+  }
+
+  export interface ShaclFormQuad {
+    subject: { value: string; termType: string };
+    predicate: { value: string };
+    object: { value: string; termType: string; datatype?: { value: string } };
+  }
+
+  // The n3 Store `toRDF` returns, narrowed to what this repo reads
+  export interface ShaclFormStore extends Iterable<ShaclFormQuad> {
+    readonly size: number;
+  }
+
+  export interface ShaclFormElement extends HTMLElement {
+    serialize(format?: SerializationFormat, graph?: ShaclFormStore): string;
+    toRDF(graph?: ShaclFormStore): ShaclFormStore;
+    validate(ignoreEmptyValues?: boolean): Promise<ShaclFormValidationReport>;
+  }
+
+  export interface ShaclFormChangeEvent extends CustomEvent {
+    detail: {
+      valid: boolean;
+      report?: ShaclFormValidationReport;
+    };
+  }
+}
+
+declare module "react" {
+  // eslint-disable-next-line @typescript-eslint/no-namespace -- augmenting JSX needs a namespace.
+  namespace JSX {
+    interface IntrinsicElements {
+      "shacl-form": import("react").DetailedHTMLProps<
+        import("react").HTMLAttributes<HTMLElement> & {
+          "data-shape-subject"?: string;
+          "data-shapes"?: string;
+          "data-values"?: string;
+          "data-values-subject"?: string;
+          "data-language"?: string;
+          "data-view"?: string;
+          "data-collapse"?: string;
+          "data-value-subject"?: string;
+        },
+        HTMLElement
+      >;
+    }
+  }
+}

package/src/shacl/shape-registry.ts

@@ -0,0 +1,40 @@
+import { expandPrefix } from "@manta-eu/rdf-lib/namespaces";
+
+export type ShapeRegistryEntry = {
+  shapeTurtle: string;
+  targetClass: string;
+};
+
+const shapeRegistry = new Map<string, ShapeRegistryEntry>();
+
+export function registerShape(targetClass: string, shapeTurtle: string): void {
+  const expandedClass = expandPrefix(targetClass);
+  shapeRegistry.set(expandedClass, {
+    shapeTurtle,
+    targetClass: expandedClass,
+  });
+}
+
+export function getShapeForType(rdfType: string): ShapeRegistryEntry | undefined {
+  const expandedType = expandPrefix(rdfType);
+  return shapeRegistry.get(expandedType);
+}
+
+export function hasShapeForType(rdfType: string): boolean {
+  const expandedType = expandPrefix(rdfType);
+  return shapeRegistry.has(expandedType);
+}
+
+export function findShapeForTypes(rdfTypes: string[]): ShapeRegistryEntry | undefined {
+  for (const rdfType of rdfTypes) {
+    const shape = getShapeForType(rdfType);
+    if (shape) {
+      return shape;
+    }
+  }
+  return undefined;
+}
+
+export function getAllRegisteredShapes(): ShapeRegistryEntry[] {
+  return Array.from(shapeRegistry.values());
+}

package/src/shared/graph-derived-queries.ts

@@ -0,0 +1,52 @@
+import {
+  useActionPlanByIriQuery,
+  useActionPlanDiffQuery,
+  useActionPlanRulesQuery,
+  useActionPlanRunHistoryQuery,
+  useActionPlanSamplesQuery,
+  useActionPlansQuery,
+  useConversationStartersQuery,
+  useCoverageRulesQuery,
+  useCurrentFactValueQuery,
+  useExplainRdFoxFactQuery,
+  useGetActionPlansSummaryQuery,
+  useMemoriesQuery,
+  useMemorySchemasQuery,
+  useNodePropertiesQuery,
+  useNodeRelationshipsQuery,
+  useRulesQuery,
+  useShaclShapesQuery,
+  useSparqlQueryQuery,
+  useUserPreferencesQuery,
+  useValidateActionPlanQuery,
+} from "@manta-eu/client";
+import type { QueryClient } from "@tanstack/react-query";
+import { invalidateQueries, type QueryWithGetKey } from "#lib/tanstack-query";
+
+// Queries whose resolver reads the active datastore's knowledge graph, so any graph write can change them.
+export const graphDerivedQueries: QueryWithGetKey[] = [
+  useActionPlanByIriQuery,
+  useActionPlanDiffQuery,
+  useActionPlanRulesQuery,
+  useActionPlanRunHistoryQuery,
+  useActionPlanSamplesQuery,
+  useActionPlansQuery,
+  useConversationStartersQuery,
+  useCoverageRulesQuery,
+  useCurrentFactValueQuery,
+  useExplainRdFoxFactQuery,
+  useGetActionPlansSummaryQuery,
+  useMemoriesQuery,
+  useMemorySchemasQuery,
+  useNodePropertiesQuery,
+  useNodeRelationshipsQuery,
+  useRulesQuery,
+  useShaclShapesQuery,
+  useSparqlQueryQuery,
+  useUserPreferencesQuery,
+  useValidateActionPlanQuery,
+];
+
+export async function invalidateGraphDerivedQueries(queryClient: QueryClient): Promise<void> {
+  await invalidateQueries(queryClient, [...graphDerivedQueries, ["ldo-ui"], ["rule-sample-facts"]]);
+}

package/src/shared/query-keys.ts

@@ -0,0 +1,14 @@
+export const actionPlanByIriQueryKey = "ActionPlanByIri";
+
+import { useGetActionPlansSummaryQuery } from "@manta-eu/client";
+import type { QueryClient } from "@tanstack/react-query";
+import { useActionPlansQueryKeyRoot } from "../hooks/useActionPlans";
+import { invalidateQueries, type KeyLike } from "#lib/tanstack-query";
+
+export async function invalidateActionPlanQueries(queryClient: QueryClient, planGraphIri?: string): Promise<void> {
+  const keys: KeyLike[] = [useActionPlansQueryKeyRoot, useGetActionPlansSummaryQuery, [actionPlanByIriQueryKey]];
+  if (planGraphIri) {
+    keys.push(["ldo-ui", planGraphIri]);
+  }
+  await invalidateQueries(queryClient, keys);
+}

package/src/storybook/StoryPreview.tsx

@@ -0,0 +1,23 @@
+import type { ReactNode } from "react";
+import { cn } from "../style";
+
+export type StoryPreviewArgs = {
+  title: string;
+  children: ReactNode;
+  contentClassName?: string;
+  parentClassName?: string;
+};
+
+const defaultContentClassName = "flex flex-wrap gap-6";
+
+export function StoryPreview(props: StoryPreviewArgs) {
+  const { title, children, contentClassName = defaultContentClassName, parentClassName } = props;
+  return (
+    <div className="flex flex-col gap-8 p-8 bg-background text-default-foreground">
+      <div className={cn("bg-card w-fit p-6 rounded-md", parentClassName)}>
+        <h2 className="mb-6 typography-small-header">{title}</h2>
+        <div className={contentClassName}>{children}</div>
+      </div>
+    </div>
+  );
+}

package/src/storybook/index.ts

@@ -0,0 +1 @@
+export { StoryPreview, type StoryPreviewArgs } from "./StoryPreview";

package/src/style.ts

@@ -0,0 +1,22 @@
+/* eslint-disable @manta-eu/no-direct-clsx */
+import clsx, { type ClassValue } from "clsx";
+import { twMerge, type ClassNameValue } from "tailwind-merge";
+
+export type { ClassValue } from "clsx";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+// The variant props of a `tv()` configuration, read from the configuration rather than from the
+// helper `tv()` returns. `tv()` leaves three of its six type parameters uninferred, so the emitted
+// declaration of an exported helper writes `unknown` where a constraint demands a variant map.
+export type VariantPropsOf<Config extends { variants: Record<string, Record<string, unknown>> }> = {
+  [Key in keyof Config["variants"]]?: keyof Config["variants"][Key] extends "true" | "false"
+    ? boolean
+    : keyof Config["variants"][Key];
+};
+
+// The `class` and `className` a `tv()` helper accepts alongside its variants. It mirrors
+// tailwind-variants own ClassProp, which allows one of the two and never both.
+export type ClassProp = { class?: ClassNameValue; className?: never } | { class?: never; className?: ClassNameValue };

package/src/templates/HtmlMessageDisplay.tsx

@@ -0,0 +1,16 @@
+import { sanitizeHtml } from "./HtmlMessagePreview";
+import { messageSurfaceClassName } from "./message-surface";
+import { cn } from "#style";
+
+export type HtmlMessageDisplayProps = {
+  body: string;
+  className?: string;
+};
+
+// Renders already-final HTML bytes; no mustache pass.
+export function HtmlMessageDisplay(props: HtmlMessageDisplayProps) {
+  const { body, className } = props;
+  return (
+    <div className={cn(messageSurfaceClassName, className)} dangerouslySetInnerHTML={{ __html: sanitizeHtml(body) }} />
+  );
+}