@manta-eu/react 0.1.9 → 0.2.0

package/src/hooks/use-entity.ts

@@ -0,0 +1,149 @@
+import { isQueryableTermIri } from "@manta-eu/datalog-parser";
+import { isPresent } from "@manta-eu/lib/present";
+import { useQuery, type UseQueryResult } from "@tanstack/react-query";
+import { createLens, type Options, type Schema, type SchemaInterface } from "ldkit";
+import { useSparqlOptions } from "./use-sparql-options";
+
+type Batch = { iris: Set<string>; result: Promise<Map<string, unknown>> };
+
+const batchWindowMs = 0;
+const maxBatchIris = 100;
+
+const batchesByOptions = new WeakMap<Options, Map<Schema, Batch>>();
+
+async function runQuery<S extends Schema>(schema: S, iris: string[], options: Options) {
+  const lens = createLens(schema, options);
+  const found = await lens.findByIris(iris);
+
+  return new Map<string, unknown>(found.map((entity) => [entity.$id, entity]));
+}
+
+function openBatch<S extends Schema>(schema: S, options: Options, bySchema: Map<Schema, Batch>): Batch {
+  const iris = new Set<string>();
+
+  const result = new Promise<Map<string, unknown>>((resolve, reject) => {
+    setTimeout(() => {
+      if (bySchema.get(schema) === batch) bySchema.delete(schema);
+
+      runQuery(schema, [...iris], options).then(resolve, reject);
+    }, batchWindowMs);
+  });
+
+  const batch: Batch = { iris, result };
+
+  return batch;
+}
+
+function claimBatches<S extends Schema>(schema: S, iris: string[], options: Options) {
+  const bySchema = batchesByOptions.get(options) ?? new Map<Schema, Batch>();
+
+  batchesByOptions.set(options, bySchema);
+
+  const claims: { batch: Batch; iris: string[] }[] = [];
+  let remaining = iris;
+
+  while (remaining.length > 0) {
+    const open = bySchema.get(schema);
+    const batch = open && open.iris.size < maxBatchIris ? open : openBatch(schema, options, bySchema);
+    bySchema.set(schema, batch);
+
+    const claimed = remaining.slice(0, maxBatchIris - batch.iris.size);
+    for (const iri of claimed) batch.iris.add(iri);
+
+    claims.push({ batch, iris: claimed });
+    remaining = remaining.slice(claimed.length);
+  }
+
+  return claims;
+}
+
+export function loadEntities<S extends Schema>(schema: S, iris: readonly string[], options: Options) {
+  const unique = [...new Set(iris)];
+
+  const parts = claimBatches(schema, unique, options).map((claim) =>
+    claim.batch.result.catch(() => runQuery(schema, claim.iris, options)),
+  );
+
+  const merged =
+    parts.length === 1
+      ? parts[0]
+      : Promise.all(parts).then((maps) => new Map<string, unknown>(maps.flatMap((map) => [...map])));
+
+  return merged as Promise<Map<string, SchemaInterface<S>>>;
+}
+
+export const entityQueryKey = <S extends Schema>(iri: string, schema: S) => ["ldo-ui", "entity", iri, schema] as const;
+export const entitiesQueryKey = <S extends Schema>(schema: S) => ["ldo-ui", "entities", schema] as const;
+export const entitiesByIrisQueryKey = <S extends Schema>(iris: readonly string[], schema: S) =>
+  ["ldo-ui", "entities-by-iris", iris, schema] as const;
+
+const entityStaleTime = 5 * 60 * 1000;
+
+export type UseEntityOptions<S extends Schema> = {
+  schema: S;
+  iri: string;
+  enabled?: boolean;
+};
+
+export function useEntity<S extends Schema>(config: UseEntityOptions<S>) {
+  const { schema, iri, enabled = true } = config;
+  const options = useSparqlOptions();
+
+  return useQuery({
+    queryKey: entityQueryKey(iri, schema),
+    queryFn: async () => (await loadEntities(schema, [iri], options)).get(iri) ?? null,
+    staleTime: entityStaleTime,
+    // Blank nodes reach these views as terms SPARQL can't name; `<term>` would be malformed.
+    enabled: enabled && isQueryableTermIri(iri),
+  });
+}
+
+export type UseEntitiesByIrisOptions<S extends Schema> = {
+  schema: S;
+  iris: readonly string[];
+  enabled?: boolean;
+};
+
+export function useEntitiesByIris<S extends Schema>(config: UseEntitiesByIrisOptions<S>) {
+  const { schema, iris, enabled = true } = config;
+  const options = useSparqlOptions();
+
+  const queryableIris = iris.filter(isQueryableTermIri);
+
+  return useQuery({
+    queryKey: entitiesByIrisQueryKey(iris, schema),
+    queryFn: async () => {
+      const byIri = await loadEntities(schema, queryableIris, options);
+
+      return iris.map((iri) => byIri.get(iri));
+    },
+    staleTime: entityStaleTime,
+    enabled: enabled && isPresent(queryableIris),
+  });
+}
+
+export type UseEntitiesOptions<S extends Schema> = {
+  schema: S;
+  enabled?: boolean;
+};
+
+// A local copy of ldkit's internal `Unite`, which only re-maps the keys of its argument. ldkit does
+// not export it, so an inferred return type names a `node_modules/...` path no consumer can resolve.
+export type Entity<T> = T extends Record<string, unknown> ? { [Key in keyof T]: T[Key] } : T;
+
+export function useEntities<S extends Schema>(
+  config: UseEntitiesOptions<S>,
+): UseQueryResult<Entity<SchemaInterface<S>>[], Error> {
+  const { schema, enabled = true } = config;
+  const options = useSparqlOptions();
+
+  return useQuery({
+    queryKey: entitiesQueryKey(schema),
+    queryFn: async () => {
+      const lens = createLens(schema, options);
+      return lens.find();
+    },
+    staleTime: entityStaleTime,
+    enabled,
+  });
+}

package/src/hooks/use-font-face.ts

@@ -0,0 +1,38 @@
+import { isPresent } from "@manta-eu/lib/present";
+import { useEffect, useState } from "react";
+
+export type FontFaceState = "idle" | "loading" | "loaded" | "failed";
+
+// Loads `url` into document.fonts under `family` for as long as the caller is mounted.
+export function useFontFace(family: string, url: string | undefined, descriptors: FontFaceDescriptors): FontFaceState {
+  const [state, setState] = useState<FontFaceState>("idle");
+  const { weight, style } = descriptors;
+
+  useEffect(() => {
+    if (!isPresent(url)) {
+      setState("idle");
+      return;
+    }
+
+    let active = true;
+    const face = new FontFace(family, `url(${JSON.stringify(url)})`, { weight, style });
+    setState("loading");
+    face
+      .load()
+      .then((loaded) => {
+        if (!active) return;
+        document.fonts.add(loaded);
+        setState("loaded");
+      })
+      .catch(() => {
+        if (active) setState("failed");
+      });
+
+    return () => {
+      active = false;
+      document.fonts.delete(face);
+    };
+  }, [family, url, weight, style]);
+
+  return state;
+}

package/src/hooks/use-graph-refresh-after-turn.ts

@@ -0,0 +1,13 @@
+import { useQueryClient } from "@tanstack/react-query";
+import { useEffect, useRef } from "react";
+import { invalidateGraphDerivedQueries } from "#shared/graph-derived-queries";
+
+export function useGraphRefreshAfterTurn(isStreaming: boolean) {
+  const queryClient = useQueryClient();
+  const wasStreamingRef = useRef(isStreaming);
+
+  useEffect(() => {
+    if (wasStreamingRef.current && !isStreaming) void invalidateGraphDerivedQueries(queryClient);
+    wasStreamingRef.current = isStreaming;
+  }, [isStreaming, queryClient]);
+}

package/src/hooks/use-install-prompt.ts

@@ -0,0 +1,67 @@
+import { useEffect, useState } from "react";
+
+type BeforeInstallPromptEvent = Event & {
+  prompt: () => Promise<void>;
+  userChoice: Promise<{ outcome: "accepted" | "dismissed" }>;
+};
+
+export type InstallOutcome = "accepted" | "dismissed" | "unavailable";
+
+function runningStandalone(): boolean {
+  if (typeof window === "undefined") return false;
+  const displayModeStandalone = window.matchMedia?.("(display-mode: standalone)").matches ?? false;
+  const iosStandalone = (window.navigator as unknown as { standalone?: boolean }).standalone === true;
+  return displayModeStandalone || iosStandalone;
+}
+
+function isIosSafari(): boolean {
+  if (typeof window === "undefined") return false;
+  const ua = window.navigator.userAgent;
+  const isIosDevice = /iphone|ipad|ipod/i.test(ua) || (ua.includes("Macintosh") && "ontouchend" in document);
+  const isWebkit = /webkit/i.test(ua) && !/crios|fxios|edgios/i.test(ua);
+  return isIosDevice && isWebkit;
+}
+
+export type InstallPromptState = {
+  /** Chrome/Android captured a beforeinstallprompt and can show the native prompt. */
+  canPrompt: boolean;
+  /** iOS Safari has no prompt API - the user must add to home screen manually. */
+  isIos: boolean;
+  /** The app is already running installed (standalone display mode). */
+  isInstalled: boolean;
+  promptInstall: () => Promise<InstallOutcome>;
+};
+
+export function useInstallPrompt(): InstallPromptState {
+  const [deferredPrompt, setDeferredPrompt] = useState<BeforeInstallPromptEvent | null>(null);
+  const [isInstalled, setIsInstalled] = useState<boolean>(runningStandalone);
+
+  useEffect(() => {
+    const onBeforeInstallPrompt = (event: Event) => {
+      event.preventDefault();
+      setDeferredPrompt(event as BeforeInstallPromptEvent);
+    };
+    const onInstalled = () => {
+      setIsInstalled(true);
+      setDeferredPrompt(null);
+    };
+
+    window.addEventListener("beforeinstallprompt", onBeforeInstallPrompt);
+    window.addEventListener("appinstalled", onInstalled);
+    return () => {
+      window.removeEventListener("beforeinstallprompt", onBeforeInstallPrompt);
+      window.removeEventListener("appinstalled", onInstalled);
+    };
+  }, []);
+
+  async function promptInstall(): Promise<InstallOutcome> {
+    if (!deferredPrompt) return "unavailable";
+
+    await deferredPrompt.prompt();
+    const { outcome } = await deferredPrompt.userChoice;
+    setDeferredPrompt(null);
+    return outcome;
+  }
+
+  return { canPrompt: deferredPrompt !== null, isIos: isIosSafari(), isInstalled, promptInstall };
+}

package/src/hooks/use-instance-labels.ts

@@ -0,0 +1,11 @@
+import { createResolvedTermsContext, type ResolvedTerms } from "./resolved-terms";
+
+export type InstanceLabel = string | null;
+
+export type InstanceLabelsContextValue = ResolvedTerms<InstanceLabel>;
+
+const resolver = createResolvedTermsContext<InstanceLabel>();
+
+export const InstanceLabelsContext = resolver.Context;
+export const useInstanceLabels = resolver.useResolvedTerms;
+export const useInstanceLabel = resolver.useResolvedTerm;

package/src/hooks/use-is-mobile.ts

@@ -0,0 +1,7 @@
+import { useMediaQuery } from "usehooks-ts";
+
+const maxMobileWidth = 768;
+
+export function useIsMobile() {
+  return useMediaQuery(`(max-width: ${maxMobileWidth - 1}px)`);
+}

package/src/hooks/use-latest-rendered-template.ts

@@ -0,0 +1,55 @@
+import { expandPrefix, isValidFullIri } from "@manta-eu/rdf-lib/namespaces";
+import { DataFactory } from "ldkit/rdf";
+import { SELECT } from "ldkit/sparql";
+import { useSparqlSelect } from "./use-sparql-construct";
+
+const df = new DataFactory();
+
+const snapshotOfIri = expandPrefix(":snapshotOf");
+const textIri = expandPrefix("schema:text");
+const contentTypeIri = expandPrefix(":contentType");
+const dateCreatedIri = expandPrefix("schema:dateCreated");
+
+export type LatestRenderedTemplate = {
+  text: string;
+  contentType: string | undefined;
+  dateCreated: string | undefined;
+};
+
+export const latestRenderedTemplateQueryKey = (templateIri: string) =>
+  ["ldo-ui", "latest-rendered-template", templateIri] as const;
+
+// Walk from a template instance to its most recent m:RenderedTemplate via m:snapshotOf. The shape
+// declares snapshotOf as sh:maxCount 1 optional but `template.clj/render!!` always writes it, so
+// this is the only link the FE needs. schema:text lives inline on RenderedTemplate — zero S3 fetch.
+export function useLatestRenderedTemplate(templateIri: string) {
+  const safe = isValidFullIri(templateIri);
+  const template = safe ? df.namedNode(templateIri) : undefined;
+
+  const query = template
+    ? SELECT`?text ?contentType ?date`.WHERE`
+        ?rt <${snapshotOfIri}> ${template} ;
+            <${textIri}> ?text .
+        OPTIONAL { ?rt <${contentTypeIri}> ?contentType }
+        OPTIONAL { ?rt <${dateCreatedIri}> ?date }
+      `.ORDER_BY`DESC(?date)`
+        .LIMIT(1)
+        .build()
+    : "";
+
+  const queryResult = useSparqlSelect({
+    query,
+    queryKey: latestRenderedTemplateQueryKey(templateIri),
+    enabled: safe,
+  });
+
+  const row = queryResult.data?.[0];
+  const text = row?.get("text")?.value;
+  const contentType = row?.get("contentType")?.value;
+  const dateCreated = row?.get("date")?.value;
+
+  return {
+    data: text ? ({ text, contentType, dateCreated } satisfies LatestRenderedTemplate) : undefined,
+    error: queryResult.error,
+  };
+}

package/src/hooks/use-manual-actions.ts

@@ -0,0 +1,157 @@
+import { MantaManualActionSchema } from "@manta-eu/ldo";
+import { isPresent } from "@manta-eu/lib/present";
+import { m } from "@manta-eu/rdf-lib/namespaces";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { createLens, type Options } from "ldkit";
+import { extractTypeName, extractLabel } from "../lib/iri-labels";
+import type { LensEntity } from "./lens-entity";
+import { useSparqlOptions } from "./use-sparql-options";
+
+export const manualActionStatuses = ["PENDING", "COMPLETED", "REJECTED", "RETRY"] as const;
+
+export type ManualActionStatus = (typeof manualActionStatuses)[number];
+
+export type ManualActionResolution = Exclude<ManualActionStatus, "PENDING">;
+
+export type ManualActionResolving = {
+  subjectIri: string;
+  resolution: ManualActionResolution;
+};
+
+function normalizeResolution(value: string | undefined): "COMPLETED" | "RETRY" | null {
+  return value === "COMPLETED" || value === "RETRY" ? value : null;
+}
+
+function normalizeManualActionStatus(value: string | undefined): ManualActionStatus | null {
+  if (!value) return null;
+  const localName = value.split(/[#/]/).pop() ?? value;
+  const upper = localName.toUpperCase();
+  return (manualActionStatuses as readonly string[]).includes(upper) ? (upper as ManualActionStatus) : null;
+}
+
+export type ManualAction = {
+  subjectIri: string;
+  subjectLabel: string | null;
+  typeIri: string;
+  typeName: string;
+  status: ManualActionStatus | null;
+  assignees: string[];
+  label?: string | null;
+  description?: string | null;
+  observedValue?: string | null;
+  aboutIri?: string | null;
+  retryable?: boolean;
+  defaultResolution?: "COMPLETED" | "RETRY" | null;
+  // No `m:status` yet: the plan has not run as far as this step.
+  unstarted?: boolean;
+};
+
+export type ManualActionReadOptions = {
+  includeUnstarted?: boolean;
+};
+
+export type UseManualActionsOptions = ManualActionReadOptions & {
+  planGraphIri: string;
+  enabled?: boolean;
+  refetchIntervalMs?: number | false;
+};
+
+export type ManualActionEntity = LensEntity<typeof MantaManualActionSchema>;
+
+export function toManualAction(entity: ManualActionEntity, options: ManualActionReadOptions = {}): ManualAction | null {
+  const { includeUnstarted = false } = options;
+  const types = [...entity.type].sort();
+  const typeIri = types.find((type) => type !== m.ManualAction) ?? types[0];
+  if (!typeIri) return null;
+  if (!entity.status && !includeUnstarted) return null;
+  const subjectLabel = extractLabel(entity.$id);
+  return {
+    subjectIri: entity.$id,
+    subjectLabel: subjectLabel || null,
+    typeIri,
+    typeName: extractTypeName(typeIri),
+    status: normalizeManualActionStatus(entity.status ?? undefined),
+    assignees: entity.assignee.map(String),
+    label: entity.label || null,
+    description: entity.description || null,
+    observedValue: entity.observedValue || null,
+    aboutIri: entity.about ?? null,
+    retryable: String(entity.retryable) === "true",
+    defaultResolution: normalizeResolution(entity.defaultResolution ?? undefined),
+    unstarted: !entity.status,
+  };
+}
+
+function compareIris(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+export function toManualActions(entities: ManualActionEntity[], options: ManualActionReadOptions = {}): ManualAction[] {
+  return entities
+    .map((entity) => toManualAction(entity, options))
+    .filter((action): action is ManualAction => action !== null)
+    .sort((a, b) => compareIris(a.typeIri, b.typeIri) || compareIris(a.subjectIri, b.subjectIri));
+}
+
+async function findManualActionsInGraph(
+  options: Options,
+  planGraphIri: string,
+  readOptions: ManualActionReadOptions = {},
+): Promise<ManualAction[]> {
+  const lens = createLens(MantaManualActionSchema, { ...options, defaultGraph: planGraphIri });
+  const entities = await lens.find();
+  return toManualActions(entities, readOptions);
+}
+
+function manualActionsQueryKey(planGraphIri: string) {
+  return ["ldo-ui", planGraphIri, "manual-actions"] as const;
+}
+
+export function useManualActions(config: UseManualActionsOptions) {
+  const { planGraphIri, enabled = true, refetchIntervalMs = false, includeUnstarted = false } = config;
+  const options = useSparqlOptions();
+
+  return useQuery<ManualAction[]>({
+    queryKey: [...manualActionsQueryKey(planGraphIri), options, { includeUnstarted }],
+    queryFn: () => findManualActionsInGraph(options, planGraphIri, { includeUnstarted }),
+    enabled: enabled && !!planGraphIri,
+    refetchInterval: refetchIntervalMs,
+    refetchIntervalInBackground: true,
+    refetchOnMount: "always",
+    refetchOnWindowFocus: "always",
+  });
+}
+
+export function useInvalidateManualActions() {
+  const queryClient = useQueryClient();
+  return (planGraphIri: string) => queryClient.invalidateQueries({ queryKey: manualActionsQueryKey(planGraphIri) });
+}
+
+export type UseManualActionsForPlansOptions = {
+  planGraphIris: string[];
+  enabled?: boolean;
+  refetchIntervalMs?: number | false;
+};
+
+async function findManualActionsForPlans(options: Options, planGraphIris: string[]) {
+  const perGraph = await Promise.all(
+    planGraphIris.map(async (iri) => [iri, await findManualActionsInGraph(options, iri)] as const),
+  );
+  return new Map(perGraph.filter(([, actions]) => isPresent(actions)));
+}
+
+export function useManualActionsForPlans(config: UseManualActionsForPlansOptions) {
+  const { planGraphIris, enabled = true, refetchIntervalMs = false } = config;
+  const options = useSparqlOptions();
+  const sortedIris = [...planGraphIris].sort();
+
+  return useQuery<Map<string, ManualAction[]>>({
+    queryKey: ["ldo-ui", "manual-actions-for-plans", sortedIris, options],
+    queryFn: () => findManualActionsForPlans(options, sortedIris),
+    enabled: enabled && isPresent(sortedIris),
+    refetchInterval: refetchIntervalMs,
+    refetchIntervalInBackground: true,
+    refetchOnMount: "always",
+    refetchOnWindowFocus: "always",
+  });
+}

package/src/hooks/use-ontology-terms.ts

@@ -0,0 +1,10 @@
+import type { OntologyTerm } from "../lib/ontology-terms";
+import { createResolvedTermsContext, type ResolvedTerms } from "./resolved-terms";
+
+export type OntologyTermsContextValue = ResolvedTerms<OntologyTerm>;
+
+const resolver = createResolvedTermsContext<OntologyTerm>();
+
+export const OntologyTermsContext = resolver.Context;
+export const useOntologyTerms = resolver.useResolvedTerms;
+export const useOntologyTerm = resolver.useResolvedTerm;

package/src/hooks/use-redirect-endpoint.ts

@@ -0,0 +1,9 @@
+import { createContext, useContext } from "react";
+
+export const defaultRedirectEndpoint = "/redirect";
+
+export const RedirectEndpointContext = createContext<string>(defaultRedirectEndpoint);
+
+export function useRedirectEndpoint(): string {
+  return useContext(RedirectEndpointContext);
+}

package/src/hooks/use-should-auto-focus-input.ts

@@ -0,0 +1,7 @@
+import { useMediaQuery } from "usehooks-ts";
+
+const supportsPreciseHoverQuery = "(hover: hover) and (pointer: fine)";
+
+export function useShouldAutoFocusInput() {
+  return useMediaQuery(supportsPreciseHoverQuery);
+}

package/src/hooks/use-sparql-construct.ts

@@ -0,0 +1,58 @@
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import type { QueryContext } from "ldkit";
+import type { RDF } from "ldkit/rdf";
+import { withAbortSignal } from "../engine";
+import { collectBindings, collectQuadsToGraph, type RdfGraph } from "../lib/rdf-helpers";
+import { useSparqlEngine, useSparqlOptions } from "./use-sparql-options";
+
+function optionsToContext(options: ReturnType<typeof useSparqlOptions>): QueryContext {
+  return options as unknown as QueryContext;
+}
+
+export type UseSparqlConstructOptions = {
+  query: string;
+  queryKey: readonly unknown[];
+  enabled?: boolean;
+  keepPreviousData?: boolean;
+  staleTime?: number;
+};
+
+export function useSparqlConstruct(config: UseSparqlConstructOptions) {
+  const { query, queryKey, enabled = true, staleTime } = config;
+  const engine = useSparqlEngine();
+  const options = useSparqlOptions();
+
+  return useQuery<RdfGraph>({
+    queryKey,
+    queryFn: async ({ signal }) => {
+      const stream = await engine.queryQuads(query, optionsToContext(withAbortSignal(options, signal)));
+      return collectQuadsToGraph(stream);
+    },
+    enabled: enabled && !!query,
+    staleTime,
+    placeholderData: config.keepPreviousData ? keepPreviousData : undefined,
+  });
+}
+
+export type UseSparqlSelectOptions = {
+  query: string;
+  queryKey: readonly unknown[];
+  enabled?: boolean;
+  staleTime?: number;
+};
+
+export function useSparqlSelect(config: UseSparqlSelectOptions) {
+  const { query, queryKey, enabled = true, staleTime } = config;
+  const engine = useSparqlEngine();
+  const options = useSparqlOptions();
+
+  return useQuery<RDF.Bindings[]>({
+    queryKey,
+    queryFn: async ({ signal }) => {
+      const stream = await engine.queryBindings(query, optionsToContext(withAbortSignal(options, signal)));
+      return collectBindings(stream);
+    },
+    enabled: enabled && !!query,
+    staleTime,
+  });
+}

package/src/hooks/use-sparql-options.ts

@@ -0,0 +1,39 @@
+import type { Options, QueryEngine, QueryContext } from "ldkit";
+import { createContext, useContext } from "react";
+
+export type SparqlContextValue = {
+  options: Options;
+  writeOptions?: Options;
+  engine: QueryEngine;
+};
+
+export const SparqlContext = createContext<SparqlContextValue | null>(null);
+
+function useSparqlContext(): SparqlContextValue {
+  const ctx = useContext(SparqlContext);
+  if (!ctx) {
+    throw new Error("useSparqlOptions/useSparqlEngine must be used within a SparqlOptionsProvider");
+  }
+  return ctx;
+}
+
+export function useSparqlOptions(): Options {
+  return useSparqlContext().options;
+}
+
+export function useSparqlEngine(): QueryEngine {
+  return useSparqlContext().engine;
+}
+
+/** Throws unless the provider was given `writeOptions` — the read `options` write to the wrong endpoint. */
+export function useSparqlWriteOptions(): Options {
+  const { writeOptions } = useSparqlContext();
+  if (!writeOptions) {
+    throw new Error("useSparqlWriteOptions requires writeOptions on the SparqlOptionsProvider");
+  }
+  return writeOptions;
+}
+
+export function optionsToContext(options: Options): QueryContext {
+  return options as unknown as QueryContext;
+}

package/src/hooks/use-sparql-query.ts

@@ -0,0 +1,54 @@
+import { useQuery, type UseQueryResult } from "@tanstack/react-query";
+import { type Options, createLens, type Schema } from "ldkit";
+import type { LensEntity } from "./lens-entity";
+
+export type UseSparqlQueryOptions<S extends Schema> = {
+  schema: S;
+  options: Options;
+  iri?: string;
+  enabled?: boolean;
+  queryKey: readonly unknown[];
+};
+
+export function useLensFind<S extends Schema>(
+  config: UseSparqlQueryOptions<S>,
+): UseQueryResult<LensEntity<S>[], Error> {
+  const { schema, options, enabled = true, queryKey } = config;
+
+  return useQuery({
+    queryKey,
+    queryFn: async () => {
+      const lens = createLens(schema, options);
+      return lens.find();
+    },
+    enabled,
+  });
+}
+
+export function useLensFindByIri<S extends Schema>(
+  config: UseSparqlQueryOptions<S> & { iri: string },
+): UseQueryResult<LensEntity<S> | null, Error> {
+  const { schema, options, iri, enabled = true, queryKey } = config;
+
+  return useQuery({
+    queryKey,
+    queryFn: async () => {
+      const lens = createLens(schema, options);
+      return lens.findByIri(iri);
+    },
+    enabled: enabled && !!iri,
+  });
+}
+
+export function useLensCount<S extends Schema>(config: Omit<UseSparqlQueryOptions<S>, "iri">) {
+  const { schema, options, enabled = true, queryKey } = config;
+
+  return useQuery({
+    queryKey,
+    queryFn: async () => {
+      const lens = createLens(schema, options);
+      return lens.count();
+    },
+    enabled,
+  });
+}