@_linked/shape-ui 2.0.0 → 2.2.0

package/src/shape/useFormDependencies.ts

@@ -0,0 +1,257 @@
+import type { NodeShapeWire } from '@_linked/core/shapes/nodeShapeWire';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  type PropertyDependency,
+  buildDependencyMap,
+  computeDependencies,
+  extractNarrowingIds,
+} from './shapeDependencies.js';
+import { getShapeParamsFromUri } from './naming.js';
+
+/**
+ * Dependency state for a single child field.
+ * Passed down to DynamicFormField via props.
+ */
+export interface FieldDependencyState {
+  /** IDs the child should be narrowed to (null = show all, [] = show none) */
+  narrowedIds: string[] | null;
+  /** Whether the parent field has a value selected */
+  parentHasValue: boolean;
+  /** Human-readable parent labels (for "Select X first" hint) */
+  parentLabels: string[];
+  /** Whether narrowing data is currently being fetched */
+  loading: boolean;
+}
+
+/**
+ * Hook that computes and manages field dependencies for a form.
+ * Infers dependency relationships from the shape graph, tracks parent
+ * field changes, and fetches narrowing data.
+ */
+/** Read one instance's data. Injected so this hook holds no control-plane dependency. */
+export type ReadInstance = (
+  shapeIri: string,
+  instanceId: string,
+) => Promise<{rows: Record<string, unknown>[]}>;
+
+export function useFormDependencies(
+  shape: NodeShapeWire | null,
+  allShapes: Record<string, NodeShapeWire> | null,
+  projectId: string | null,
+  readInstance?: ReadInstance,
+) {
+  // Compute static dependency graph (only changes when shape changes)
+  const dependencies = useMemo(() => {
+    if (!shape || !allShapes) return [];
+    return computeDependencies(shape, allShapes);
+  }, [shape?.id, allShapes]);
+
+  const depMap = useMemo(() => buildDependencyMap(dependencies), [dependencies]);
+
+  // State for narrowing results
+  const [narrowedIds, setNarrowedIds] = useState<Map<string, string[] | null>>(
+    new Map()
+  );
+  const [parentHasValue, setParentHasValue] = useState<Map<string, boolean>>(
+    new Map()
+  );
+  const [loading, setLoading] = useState<Map<string, boolean>>(new Map());
+
+  // Abort controllers for in-flight fetches
+  const fetchControllers = useRef<Map<string, AbortController>>(new Map());
+
+  /**
+   * Called when a parent field value changes.
+   * Fetches the parent instance data and extracts narrowing IDs for dependent fields.
+   */
+  const onParentValueChange = useCallback(
+    async (parentLabel: string, parentValue: any) => {
+      // Find all dependencies where this property is the parent
+      const childDeps = dependencies.filter((d) => d.parentLabel === parentLabel);
+      if (childDeps.length === 0) return;
+
+      // Extract parent instance ID
+      const parentId = parentValue
+        ? typeof parentValue === 'object'
+          ? parentValue.id
+          : typeof parentValue === 'string'
+          ? parentValue
+          : null
+        : null;
+
+      // Update parentHasValue for all children of this parent
+      setParentHasValue((prev) => {
+        const next = new Map(prev);
+        for (const dep of childDeps) {
+          next.set(dep.childLabel, !!parentId);
+        }
+        return next;
+      });
+
+      if (!parentId || !projectId) {
+        // Parent cleared — remove narrowing for all children
+        setNarrowedIds((prev) => {
+          const next = new Map(prev);
+          for (const dep of childDeps) {
+            next.set(dep.childLabel, null);
+          }
+          return next;
+        });
+        return;
+      }
+
+      // Cancel any in-flight fetch for this parent
+      const existing = fetchControllers.current.get(parentLabel);
+      if (existing) existing.abort();
+      const controller = new AbortController();
+      fetchControllers.current.set(parentLabel, controller);
+
+      // Set loading state
+      setLoading((prev) => {
+        const next = new Map(prev);
+        for (const dep of childDeps) {
+          next.set(dep.childLabel, true);
+        }
+        return next;
+      });
+
+      try {
+        // Convert parent valueShape URI to package:label format for getInstanceData
+        const parentShapeParam = getShapeParamsFromUri(
+          childDeps[0].parentValueShapeId
+        );
+        if (!readInstance) return;
+        const result = await readInstance(parentShapeParam, parentId);
+
+        if (controller.signal.aborted) return;
+
+        const instanceData = Array.isArray(result?.rows)
+          ? result.rows[0]
+          : result?.rows;
+
+        if (!instanceData) {
+          // Could not fetch parent data — allow all options
+          setNarrowedIds((prev) => {
+            const next = new Map(prev);
+            for (const dep of childDeps) {
+              next.set(dep.childLabel, null);
+            }
+            return next;
+          });
+          return;
+        }
+
+        // Extract narrowing IDs for each child
+        setNarrowedIds((prev) => {
+          const next = new Map(prev);
+          for (const dep of childDeps) {
+            const ids = extractNarrowingIds(
+              instanceData,
+              dep.linkingPropertyLabel
+            );
+            next.set(dep.childLabel, ids.length > 0 ? ids : null);
+          }
+          return next;
+        });
+      } catch (err) {
+        if (!controller.signal.aborted) {
+          console.warn(
+            'Failed to fetch parent instance for narrowing:',
+            err
+          );
+          // On error, don't narrow (show all options)
+          setNarrowedIds((prev) => {
+            const next = new Map(prev);
+            for (const dep of childDeps) {
+              next.set(dep.childLabel, null);
+            }
+            return next;
+          });
+        }
+      } finally {
+        if (!controller.signal.aborted) {
+          setLoading((prev) => {
+            const next = new Map(prev);
+            for (const dep of childDeps) {
+              next.set(dep.childLabel, false);
+            }
+            return next;
+          });
+        }
+      }
+    },
+    [dependencies, projectId]
+  );
+
+  /**
+   * Initialize dependency state from existing form data (draft restore / edit mode).
+   * Call this after loading initial data to set parentHasValue for pre-filled fields.
+   */
+  const initFromData = useCallback(
+    (data: Record<string, any>) => {
+      if (!data) return;
+      // Find all parent labels and trigger onParentValueChange for each that has a value
+      const parentLabels = new Set(dependencies.map((d) => d.parentLabel));
+      for (const label of parentLabels) {
+        if (data[label] !== undefined && data[label] !== null) {
+          onParentValueChange(label, data[label]);
+        }
+      }
+    },
+    [dependencies, onParentValueChange]
+  );
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      fetchControllers.current.forEach((c) => c.abort());
+    };
+  }, []);
+
+  /** Check if a property has any parent dependencies */
+  const hasDependency = useCallback(
+    (label: string) => depMap.has(label),
+    [depMap]
+  );
+
+  /** Check if a property is a parent (has children that depend on it) */
+  const isParent = useCallback(
+    (label: string) => dependencies.some((d) => d.parentLabel === label),
+    [dependencies]
+  );
+
+  /** Get the parent labels for a given child */
+  const getParentLabels = useCallback(
+    (childLabel: string) =>
+      (depMap.get(childLabel) || []).map((d) => d.parentLabel),
+    [depMap]
+  );
+
+  /** Build FieldDependencyState for a given property label */
+  const getDependencyState = useCallback(
+    (label: string): FieldDependencyState | undefined => {
+      if (!depMap.has(label)) return undefined;
+      return {
+        narrowedIds: narrowedIds.get(label) ?? null,
+        parentHasValue: parentHasValue.get(label) ?? true,
+        parentLabels: getParentLabels(label),
+        loading: loading.get(label) ?? false,
+      };
+    },
+    [depMap, narrowedIds, parentHasValue, loading, getParentLabels]
+  );
+
+  return {
+    dependencies,
+    depMap,
+    narrowedIds,
+    parentHasValue,
+    loading,
+    onParentValueChange,
+    initFromData,
+    hasDependency,
+    isParent,
+    getParentLabels,
+    getDependencyState,
+  };
+}

package/src/shape/validation.ts

@@ -0,0 +1,121 @@
+import {enumOptions} from './nodeDisplay.js';
+import type { PropertyShapeWire } from '@_linked/core/shapes/nodeShapeWire';
+import { shacl } from '@_linked/core/ontologies/shacl';
+
+export interface FieldError {
+  propertyLabel: string;
+  message: string;
+}
+
+/**
+ * Validate a single field value against its PropertyShape constraints.
+ * Returns an error message string, or empty string if valid.
+ */
+export function validateField(
+  property: PropertyShapeWire,
+  value: any,
+): string {
+  const nodeKind = property.nodeKind?.id;
+  const isIRI =
+    nodeKind === shacl.IRI.id ||
+    nodeKind === shacl.BlankNode.id ||
+    nodeKind === shacl.BlankNodeOrIRI.id;
+
+  // Required check (minCount > 0)
+  if (property.minCount > 0) {
+    if (isIRI) {
+      // For IRI properties, value is an object or array of objects
+      const isEmpty =
+        value === undefined ||
+        value === null ||
+        (Array.isArray(value) && value.length === 0);
+      if (isEmpty) return 'At least one selection is required';
+    } else {
+      if (value === undefined || value === null || value === '') {
+        return 'This field is required';
+      }
+    }
+  }
+
+  // Skip further validation if value is empty (optional fields)
+  if (value === undefined || value === null || value === '') return '';
+
+  // sh:in — value must be in the allowed set
+  const choices = enumOptions(property);
+  if (choices.length > 0) {
+    if (isIRI) {
+      const selected = Array.isArray(value) ? value : [value];
+      const allowedIds = new Set(choices.map((v) => v.id));
+      const invalid = selected.find((s) => !allowedIds.has(s.id));
+      if (invalid) return 'Must be one of the allowed values';
+    } else {
+      const allowedIds = new Set(choices.map((v) => v.id));
+      if (!allowedIds.has(String(value))) {
+        return 'Must be one of the allowed values';
+      }
+    }
+  }
+
+  // Literal-only constraints
+  if (nodeKind === shacl.Literal.id) {
+    const strVal = typeof value === 'string' ? value : String(value);
+
+    // sh:pattern
+    if (property.pattern) {
+      try {
+        const re = new RegExp(property.pattern);
+        if (!re.test(strVal)) return 'Value must match the required format';
+      } catch {
+        // Invalid regex in shape definition — skip
+      }
+    }
+
+    // sh:minLength
+    if (property.minLength != null && strVal.length < property.minLength) {
+      return `Must be at least ${property.minLength} characters`;
+    }
+
+    // sh:maxLength
+    if (property.maxLength != null && strVal.length > property.maxLength) {
+      return `Must be at most ${property.maxLength} characters`;
+    }
+
+    // Numeric range constraints
+    const numVal = typeof value === 'number' ? value : parseFloat(strVal);
+    if (!isNaN(numVal)) {
+      if (property.minInclusive != null && numVal < Number(property.minInclusive)) {
+        return `Must be at least ${property.minInclusive}`;
+      }
+      if (property.maxInclusive != null && numVal > Number(property.maxInclusive)) {
+        return `Must be at most ${property.maxInclusive}`;
+      }
+      if (property.minExclusive != null && numVal <= Number(property.minExclusive)) {
+        return `Must be greater than ${property.minExclusive}`;
+      }
+      if (property.maxExclusive != null && numVal >= Number(property.maxExclusive)) {
+        return `Must be less than ${property.maxExclusive}`;
+      }
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Validate all fields at once (for submit-time gate).
+ * Returns an array of errors; empty array means all valid.
+ */
+export function validateAllFields(
+  properties: PropertyShapeWire[],
+  data: Record<string, any>,
+): FieldError[] {
+  const errors: FieldError[] = [];
+  for (const prop of properties) {
+    if (!prop.nodeKind) continue; // skip incomplete shapes
+    const msg = validateField(prop, data[prop.label]);
+    if (msg) {
+      errors.push({ propertyLabel: prop.label, message: msg });
+    }
+  }
+  return errors;
+}

package/src/tokens.css

@@ -0,0 +1,25 @@
+/*
+ * The few tokens the data manager still defines itself.
+ *
+ * It used to be 67. Measuring them against `@_linked/css` showed almost all were either
+ * Tailwind primitives the theme already assumes, or re-namings of tokens the theme has
+ * under better names — `--card-*` is `--surface-*`, `--input-*` is `--field-*`,
+ * `--z-tooltip` is `--layer-tooltip`, `--typography-xs-size` is `--text-xs`. Those were
+ * renamed in the components rather than shipped here. The families that were genuinely
+ * missing went into the theme instead of here: `--intent-*` and `--table-*`
+ * (linked-cm/css#11), and the named `--space-*` scale (linked-cm/css#12) that a CSS module
+ * needs because Tailwind's `--spacing()` is a compile-time function and cannot resolve in a
+ * stylesheet compiled on its own.
+ *
+ * What is left is genuinely local: pagination has no counterpart in the theme's component
+ * families. Values come from Create Now's light theme so the two do not drift on day one.
+ * Import before your own theme; anything you define afterwards wins.
+ */
+
+:root {
+  --pagination-button-border: var(--color-gray-200);
+  --pagination-button-hover-border: var(--color-tertiary-500);
+  --pagination-button-hover-text: var(--color-tertiary-500);
+  --pagination-text: var(--color-gray-500);
+  --pagination-text-bold: var(--color-gray-900);
+}

package/src/types.ts

@@ -0,0 +1,20 @@
+/**
+ * CSS modules, for the compiler.
+ *
+ * `tsc` only COPIES these into `lib` (see `copy-to-lib`); the class-name hashing and scoping is
+ * the consuming bundler's job, as in `@_linked/primitives`. A consumer therefore needs a
+ * bundler that understands CSS modules — which any app rendering these components already has.
+ *
+ * The binding is called `styles`, not `classes`, on purpose. `@_linked/primitives` declares the
+ * same ambient module, and inside this workspace its *source* is symlinked, so both
+ * declarations are visible and `const classes` in each is a duplicate identifier. Ambient
+ * module declarations merge; the names inside them must not collide. Renaming is the whole fix.
+ *
+ * The declaration cannot simply be dropped either: primitives' version reaches us only through
+ * the workspace symlink, so a clean `npm ci` in CI has no declaration at all and every
+ * `import style from './X.module.css'` fails.
+ */
+declare module '*.module.css' {
+  const styles: {readonly [key: string]: string};
+  export default styles;
+}

package/src/utils/helper.ts

@@ -0,0 +1,35 @@
+import { Capacitor } from '@capacitor/core';
+
+// currently use for generate
+export function generateRandomName(format: string) {
+  const timestamp = new Date().getTime();
+  const randomString = Math.random().toString(15).substring(7); // Generate a random string
+
+  return format
+    ? `${timestamp}_${randomString}.${format}`
+    : `${timestamp}_${randomString}`;
+}
+
+/**
+ * Fixes the image path for Android devices during development.
+ * Replaces 'localhost' with the appropriate site root URL.
+ * @param croppedImage
+ * @returns
+ */
+export function replaceLocalhostWithSiteRoot(croppedImage: string): string {
+  let imageSrc = croppedImage;
+  if (
+    imageSrc &&
+    process.env.NODE_ENV !== 'production' &&
+    Capacitor.getPlatform() === 'android'
+  ) {
+    if (imageSrc.includes('localhost')) {
+      imageSrc = imageSrc.replace(
+        /http\:\/\/localhost\:\d+/,
+        process.env.SITE_ROOT
+      );
+    }
+  }
+
+  return imageSrc;
+}

package/src/write.test.ts

@@ -0,0 +1,174 @@
+import {beforeEach, describe, expect, jest, test} from '@jest/globals';
+import type {NodeShapeWire} from '@_linked/core/shapes/nodeShapeWire';
+
+/**
+ * The DSL write path.
+ *
+ * The read moved to the DSL a while ago; the write was still a control-plane RPC that took
+ * a project id. These pin the two things that made that a problem: the write names no
+ * project, and it goes through the same builder — and therefore the same routing — as the
+ * read. A read routed one way and a write routed another is how a form saves into the
+ * wrong dataset without anyone noticing.
+ *
+ * The builders are mocked. What is asserted is the shape of the call; core's own suite
+ * covers the SPARQL.
+ */
+
+const createFrom = jest.fn();
+const createWithId = jest.fn();
+const createSet = jest.fn();
+const updateFrom = jest.fn();
+const updateFor = jest.fn();
+const updateSet = jest.fn();
+
+jest.unstable_mockModule('@_linked/core/queries/CreateBuilder', () => ({
+  CreateBuilder: {
+    from: (...args: unknown[]) => {
+      createFrom(...args);
+      const b: Record<string, unknown> = {};
+      b.withId = (id: unknown) => (createWithId(id), b);
+      b.set = (data: unknown) => (createSet(data), b);
+      b.exec = async () => undefined;
+      return b;
+    },
+  },
+}));
+
+jest.unstable_mockModule('@_linked/core/queries/UpdateBuilder', () => ({
+  UpdateBuilder: {
+    from: (...args: unknown[]) => {
+      updateFrom(...args);
+      const b: Record<string, unknown> = {};
+      b.for = (id: unknown) => (updateFor(id), b);
+      b.set = (data: unknown) => (updateSet(data), b);
+      b.exec = async () => undefined;
+      return b;
+    },
+  },
+}));
+
+const {createInstanceWithDsl, updateInstanceWithDsl, mintInstanceIri} = await import(
+  './write.js'
+);
+
+const shape: NodeShapeWire = {
+  id: 'https://id.linked.cm/app/vocab#Article',
+  label: 'Article',
+  propertyShapes: [
+    {id: 'p1', label: 'title', path: {id: 'http://schema.org/name'}},
+    {id: 'p2', label: 'author', path: {id: 'http://schema.org/author'}},
+    {id: 'p3', label: 'tags', path: {id: 'http://schema.org/keywords'}},
+  ],
+} as NodeShapeWire;
+
+beforeEach(() => {
+  [createFrom, createWithId, createSet, updateFrom, updateFor, updateSet].forEach((m) =>
+    m.mockClear(),
+  );
+});
+
+describe('creating', () => {
+  test('names the shape and no project', async () => {
+    await createInstanceWithDsl(shape, {title: 'Dune'}, {dataRoot: 'https://ex.org/data'});
+    expect(createFrom).toHaveBeenCalledWith(shape.id);
+    // The portability claim, asserted rather than asserted-in-prose: nothing in the call
+    // carries a project, a branch or a dataset.
+    expect(JSON.stringify(createSet.mock.calls)).not.toMatch(/project|branch|dataset/i);
+  });
+
+  test('mints an id under the host dataRoot', async () => {
+    const {id} = await createInstanceWithDsl(
+      shape,
+      {title: 'Dune'},
+      {dataRoot: 'https://ex.org/data/'},
+    );
+    // Trailing slash on dataRoot must not produce a double slash.
+    expect(id).toMatch(/^https:\/\/ex\.org\/data\/article\/[0-9a-f-]{36}$/);
+    expect(createWithId).toHaveBeenCalledWith(id);
+  });
+
+  test('refuses to invent a namespace when dataRoot is missing', async () => {
+    // A node created under a guessed IRI is worse than a failed create: it is unreachable
+    // and it is already written.
+    await expect(createInstanceWithDsl(shape, {title: 'Dune'})).rejects.toThrow(/dataRoot/);
+  });
+
+  test('drops empty values instead of writing empty literals', async () => {
+    await createInstanceWithDsl(
+      shape,
+      {title: 'Dune', author: '', tags: undefined},
+      {dataRoot: 'https://ex.org/data'},
+    );
+    expect(createSet).toHaveBeenCalledWith({title: 'Dune'});
+  });
+
+  test('drops fields the shape does not declare', async () => {
+    await createInstanceWithDsl(
+      shape,
+      {title: 'Dune', removedLastWeek: 'x'},
+      {dataRoot: 'https://ex.org/data'},
+    );
+    expect(createSet).toHaveBeenCalledWith({title: 'Dune'});
+  });
+
+  test('writes a relation as a reference, without its display label', async () => {
+    // The form carries {id, label} so a draft can show a name. The label is display state;
+    // writing it would put a second, immediately stale copy of it in the graph.
+    await createInstanceWithDsl(
+      shape,
+      {author: {id: 'https://ex.org/person/1', label: 'Ada'}},
+      {dataRoot: 'https://ex.org/data'},
+    );
+    expect(createSet).toHaveBeenCalledWith({author: {id: 'https://ex.org/person/1'}});
+  });
+
+  test('does the same for every member of a multi-valued relation', async () => {
+    await createInstanceWithDsl(
+      shape,
+      {tags: [{id: 'urn:t/1', label: 'alpha'}, {id: 'urn:t/2', label: 'beta'}]},
+      {dataRoot: 'https://ex.org/data'},
+    );
+    expect(createSet).toHaveBeenCalledWith({tags: [{id: 'urn:t/1'}, {id: 'urn:t/2'}]});
+  });
+
+  test('accepts a caller-supplied id', async () => {
+    const {id} = await createInstanceWithDsl(
+      shape,
+      {title: 'Dune'},
+      {id: 'https://ex.org/data/article/fixed'},
+    );
+    expect(id).toBe('https://ex.org/data/article/fixed');
+  });
+});
+
+describe('updating', () => {
+  test('targets the instance by id and names no project', async () => {
+    await updateInstanceWithDsl(shape, 'https://ex.org/data/article/1', {title: 'Dune'});
+    expect(updateFrom).toHaveBeenCalledWith(shape.id);
+    expect(updateFor).toHaveBeenCalledWith('https://ex.org/data/article/1');
+  });
+
+  test('clears an emptied field rather than dropping it', async () => {
+    // The opposite of create, and deliberately so: clearing a field the viewer emptied is
+    // the whole point of an edit form.
+    await updateInstanceWithDsl(shape, 'urn:a/1', {title: '', author: undefined});
+    expect(updateSet).toHaveBeenCalledWith({title: null, author: null});
+  });
+
+  test('is a no-op when nothing in the payload is recognisable', async () => {
+    await updateInstanceWithDsl(shape, 'urn:a/1', {goneFromTheShape: 'x'});
+    expect(updateFrom).not.toHaveBeenCalled();
+  });
+});
+
+describe('mintInstanceIri', () => {
+  test('uses the shape label as the path segment, lowercased', () => {
+    expect(mintInstanceIri(shape, 'https://ex.org/d')).toContain('/article/');
+  });
+
+  test('falls back to a generic segment for a shape with no label', () => {
+    expect(mintInstanceIri({id: 'urn:s'} as NodeShapeWire, 'https://ex.org/d')).toContain(
+      '/instance/',
+    );
+  });
+});