@_linked/shape-ui 2.0.0 → 2.2.0

package/src/shape/propertyTypes.ts

@@ -0,0 +1,86 @@
+import type { PropertyShapeWire } from '@_linked/core/shapes/nodeShapeWire';
+import { shacl } from '@_linked/core/ontologies/shacl';
+import { xsd } from '@_linked/core/ontologies/xsd';
+
+/**
+ * Classifies a SHACL property shape into a UI-level type.
+ * Used by form fields (DynamicFormField) and table filter widgets
+ * to determine the appropriate input control and filter operators.
+ */
+export type PropertyUiType =
+  | 'text'
+  | 'number'
+  | 'date'
+  | 'datetime'
+  | 'boolean'
+  | 'url'
+  | 'iri-single'
+  | 'iri-multi'
+  | 'enum-literal'
+  | 'enum-iri';
+
+export function getPropertyUiType(property: PropertyShapeWire): PropertyUiType | null {
+  const nodeKind = property.nodeKind;
+  if (!nodeKind) return null;
+
+  // Enum: sh:in with values present.
+  //
+  // `sh:in`, the metamodel spelling. The DTO's `inValues` is still read for a host that
+  // hands one over, but nothing in this package produces it any more.
+  // (was: accepts BOTH forms. The DTO calls it `inValues` — `{id, label}` pairs with a derived
+  // display label); the metamodel calls it `in` and keeps members as members. The table
+  // now receives the metamodel form, and keying only on `inValues` silently downgraded
+  // every enum column to a free-text filter and a free-text batch-edit input.
+  const enumValues =
+    ((property as {inValues?: unknown[]}).inValues) ??
+    ((property as unknown as {in?: unknown[]}).in);
+  if (enumValues && enumValues.length > 0) {
+    if (nodeKind.id === shacl.Literal.id) return 'enum-literal';
+    return 'enum-iri';
+  }
+
+  // Object / IRI properties
+  if (
+    nodeKind.id === shacl.IRI.id ||
+    nodeKind.id === shacl.BlankNode.id ||
+    nodeKind.id === shacl.BlankNodeOrIRI.id
+  ) {
+    return property.maxCount === 1 ? 'iri-single' : 'iri-multi';
+  }
+
+  // Literal properties — classify by datatype
+  if (nodeKind.id === shacl.Literal.id) {
+    const dt = property.datatype?.id;
+    if (!dt) return 'text';
+
+    if (dt === xsd.boolean.id) return 'boolean';
+
+    if (dt === xsd.date.id) return 'date';
+
+    if (dt === xsd.dateTime.id) return 'datetime';
+
+    if (
+      dt === xsd.integer.id ||
+      dt === xsd.long?.id ||
+      dt === xsd.decimal?.id ||
+      dt === xsd.float?.id ||
+      dt === xsd.double?.id
+    ) {
+      return 'number';
+    }
+
+    if (dt === 'http://www.w3.org/2001/XMLSchema#anyURI') return 'url';
+
+    return 'text';
+  }
+
+  return 'text';
+}
+
+/**
+ * Returns whether a property UI type represents an integer (vs floating point).
+ */
+export function isIntegerType(property: PropertyShapeWire): boolean {
+  const dt = property.datatype?.id;
+  return dt === xsd.integer.id || dt === xsd.long?.id;
+}

package/src/shape/propertyVisibility.ts

@@ -0,0 +1,180 @@
+import type { PropertyShapeWire } from '@_linked/core/shapes/nodeShapeWire';
+
+/**
+ * `hidden` is a REMOVAL, not the weakest shown category.
+ *
+ * `optional` is still displayed — it fills the "add another field" picker and is rendered
+ * in `full` and in `form-edit` whenever the instance has a value. So mapping
+ * `linked_core:displayHidden` onto `optional` did nothing at all. Hidden needs its own
+ * value that every mode filters, including the "nothing qualified, show everything"
+ * fallback.
+ */
+export type PropertyVisibility = 'required' | 'used' | 'optional' | 'hidden';
+
+export interface PropertyUsageData {
+  count: number;
+  total: number;
+  percentage: number;
+}
+
+/** Code analysis classification from analyze-shape-usage.ts */
+export type CodeClassification =
+  | 'essential'
+  | 'common'
+  | 'contextual'
+  | 'display'
+  | 'unused';
+
+export interface CodeUsageData {
+  classification: CodeClassification;
+  writeRefs: number;
+  readRefs: number;
+}
+
+/** Per-shape code usage manifest (keyed by shape class name → property label) */
+export type CodeUsageManifest = Record<string, Record<string, CodeUsageData>>;
+
+export interface ClassifiedProperty {
+  property: PropertyShapeWire;
+  visibility: PropertyVisibility;
+  usage?: PropertyUsageData;
+  codeUsage?: CodeUsageData;
+}
+
+/**
+ * Classify properties using three signals (in priority order):
+ *
+ *   1. Shape constraints (SHACL): minCount > 0 → required
+ *   2. Code analysis: essential/common → used; contextual/display/unused → optional
+ *   3. Data usage (SPARQL): percentage >= threshold → used
+ *
+ * The code analysis signal is the primary differentiator for non-required
+ * properties — it reflects how the shape is actually used when submitting
+ * data in the project's code.
+ */
+export function classifyProperties(
+  properties: PropertyShapeWire[],
+  usageData: Record<string, PropertyUsageData> | null,
+  options?: {
+    usageThreshold?: number;
+    codeUsage?: Record<string, CodeUsageData> | null;
+  }
+): ClassifiedProperty[] {
+  const threshold = options?.usageThreshold ?? 1;
+  const codeUsage = options?.codeUsage ?? null;
+
+  return properties.map((prop) => {
+    const usage = usageData?.[prop.label];
+    const code = codeUsage?.[prop.label];
+    // Display metadata the shape itself declares. Read structurally so this works for
+    // both the metamodel and the derived DTO, which has no home for these fields.
+    const display = prop as unknown as {
+      displayHidden?: boolean;
+      displayRank?: number;
+    };
+
+    let visibility: PropertyVisibility;
+
+    // 0. The shape says not to render it. This outranks everything below, including
+    //    minCount: a required property can still be one a person should not be shown.
+    if (display.displayHidden === true) {
+      visibility = 'hidden';
+    }
+    // 1. SHACL constraint: minCount > 0 means required
+    else if (prop.minCount > 0) {
+      visibility = 'required';
+    }
+    // 1b. A declared display rank is the shape stating the property matters. It is a
+    //     first-party statement, so it outranks the inferred signals below.
+    else if (display.displayRank != null) {
+      visibility = 'used';
+    }
+    // 2. Code analysis: essential/common properties are "used"
+    else if (
+      code &&
+      (code.classification === 'essential' || code.classification === 'common')
+    ) {
+      visibility = 'used';
+    }
+    // 3. Data usage: >= threshold% of instances have this property
+    else if (usage && usage.percentage >= threshold) {
+      visibility = 'used';
+    }
+    // 4. Code analysis: display properties are optional but may be shown in views
+    else {
+      visibility = 'optional';
+    }
+
+    return { property: prop, visibility, usage, codeUsage: code };
+  });
+}
+
+export type VisibilityMode = 'auto' | 'full' | 'form-add' | 'form-edit';
+
+/**
+ * Returns true if a property value is considered "populated" (has meaningful data).
+ * Handles all data types: primitives, objects ({id, label}), arrays, numbers.
+ */
+function hasValue(val: any): boolean {
+  if (val === undefined || val === null) return false;
+  if (typeof val === 'string') return val !== '';
+  if (typeof val === 'number') return true; // 0 is a valid value
+  if (typeof val === 'boolean') return true;
+  if (Array.isArray(val)) return val.length > 0;
+  if (typeof val === 'object') return Object.keys(val).length > 0;
+  return true;
+}
+
+/**
+ * Filter properties to only those that should be visible in a given context.
+ *
+ * - auto: required + used (for tables); falls back to all if nothing qualifies
+ * - full: all properties
+ * - form-add: required + used (essential/common from code); falls back to all
+ * - form-edit: required + used + properties with data on this instance; falls back to all
+ */
+export function getVisibleProperties(
+  classified: ClassifiedProperty[],
+  mode: VisibilityMode,
+  instanceData?: Record<string, any>
+): ClassifiedProperty[] {
+  // Removed before any mode gets a say, and before the fallback below can reinstate it.
+  const visible = classified.filter((c) => c.visibility !== 'hidden');
+
+  let result: ClassifiedProperty[];
+
+  switch (mode) {
+    case 'full':
+      return visible;
+
+    case 'auto':
+      result = visible.filter(
+        (c) => c.visibility === 'required' || c.visibility === 'used'
+      );
+      break;
+
+    case 'form-add':
+      result = visible.filter(
+        (c) => c.visibility === 'required' || c.visibility === 'used'
+      );
+      break;
+
+    case 'form-edit':
+      result = visible.filter((c) => {
+        if (c.visibility === 'required') return true;
+        if (c.visibility === 'used') return true;
+        if (instanceData && hasValue(instanceData[c.property.label]))
+          return true;
+        return false;
+      });
+      break;
+
+    default:
+      return visible;
+  }
+
+  // Fallback: if filtering yields nothing, show all NON-HIDDEN properties. This handles
+  // shapes that haven't declared any minCount/required yet — but it must not be a back
+  // door that reinstates what the shape explicitly hid.
+  return result.length > 0 ? result : visible;
+}

package/src/shape/shapeDependencies.ts

@@ -0,0 +1,183 @@
+import type { NodeShapeWire } from '@_linked/core/shapes/nodeShapeWire';
+import { shacl } from '@_linked/core/ontologies/shacl';
+
+/**
+ * A dependency link: a child property depends on a parent property.
+ * When the parent's value changes, the child should be narrowed or reset.
+ */
+export interface PropertyDependency {
+  /** The parent property label (e.g., "agent") */
+  parentLabel: string;
+  /** The dependent property label (e.g., "team") */
+  childLabel: string;
+  /** The shape URI of the parent's valueShape (e.g., Player shape URI) */
+  parentValueShapeId: string;
+  /** The label of the property on the parent's valueShape that links to the child's valueShape
+   *  (e.g., "currentTeam" on the Player shape) */
+  linkingPropertyLabel: string;
+  /** The full predicate URI of the linking property — needed for SPARQL queries */
+  linkingPropertyPath: string;
+  /** The shape URI of the child's valueShape (e.g., Team shape URI) */
+  childValueShapeId: string;
+}
+
+const IRI_NODE_KINDS = new Set([
+  shacl.IRI.id,
+  shacl.BlankNode.id,
+  shacl.BlankNodeOrIRI.id,
+]);
+
+function isIriProperty(p: NodeShapeWire['propertyShapes'][number]): boolean {
+  return !!p.nodeKind && IRI_NODE_KINDS.has(p.nodeKind.id) && !!p.valueShape?.id;
+}
+
+/**
+ * Compute dependency relationships between IRI properties on a shape.
+ *
+ * Algorithm: For each pair of IRI properties (A, B) on the same shape,
+ * check if A's valueShape has a property whose valueShape matches B's valueShape.
+ * If so, B depends on A via that linking property.
+ *
+ * Only looks 1 level deep and breaks cycles: if A→B and B→A are both found,
+ * only the first-discovered direction is kept.
+ */
+export function computeDependencies(
+  shape: NodeShapeWire,
+  allShapes: Record<string, NodeShapeWire>
+): PropertyDependency[] {
+  const candidates: PropertyDependency[] = [];
+
+  const iriProperties = (shape.propertyShapes || []).filter(isIriProperty);
+
+  for (const propA of iriProperties) {
+    // Look up the full shape definition for A's valueShape
+    const aValueShape = allShapes[propA.valueShape!.id];
+    if (!aValueShape?.propertyShapes) continue;
+
+    for (const propB of iriProperties) {
+      if (propA.label === propB.label) continue;
+      if (!propB.valueShape?.id) continue;
+
+      // Check if A's valueShape has a property pointing to B's valueShape
+      for (const linkProp of aValueShape.propertyShapes) {
+        if (linkProp.valueShape?.id === propB.valueShape!.id) {
+          const pathObj = Array.isArray(linkProp.path)
+            ? linkProp.path[0]
+            : linkProp.path;
+          candidates.push({
+            parentLabel: propA.label,
+            childLabel: propB.label,
+            parentValueShapeId: propA.valueShape!.id,
+            linkingPropertyLabel: linkProp.label,
+            linkingPropertyPath: pathObj?.id || '',
+            childValueShapeId: propB.valueShape!.id,
+          });
+          break; // Only one linking path per A→B pair
+        }
+      }
+    }
+  }
+
+  // Break cycles: if A→B and B→A both exist, keep only the first one found.
+  // Also ensure no field ends up as a child of ALL other fields (deadlock).
+  return removeCycles(candidates);
+}
+
+/**
+ * Remove circular dependencies from the candidate list.
+ * When A→B and B→A both exist, keep only the first direction found.
+ * Then ensure no field is blocked by all other fields (prune so at least
+ * one field per connected component has no parents).
+ */
+function removeCycles(deps: PropertyDependency[]): PropertyDependency[] {
+  const kept: PropertyDependency[] = [];
+  const edges = new Set<string>(); // "parent->child" strings
+
+  for (const dep of deps) {
+    const forward = `${dep.parentLabel}->${dep.childLabel}`;
+    const reverse = `${dep.childLabel}->${dep.parentLabel}`;
+
+    // If the reverse direction is already kept, skip this one
+    if (edges.has(reverse)) continue;
+
+    edges.add(forward);
+    kept.push(dep);
+  }
+
+  // Ensure at least one root (a field with no parents) exists.
+  // If every field is someone's child, remove the dependency that has the
+  // most children as parent (it's the most "primary" field).
+  const allChildren = new Set(kept.map((d) => d.childLabel));
+  const allParents = new Set(kept.map((d) => d.parentLabel));
+  const roots = [...allParents].filter((p) => !allChildren.has(p));
+
+  if (roots.length === 0 && kept.length > 0) {
+    // No root — every field is a child. Break the cycle by finding the
+    // field that is a child the fewest times and removing its parent deps.
+    const childCount = new Map<string, number>();
+    for (const d of kept) {
+      childCount.set(d.childLabel, (childCount.get(d.childLabel) || 0) + 1);
+    }
+    // Pick the field that appears as parent most often to be the root
+    const parentCount = new Map<string, number>();
+    for (const d of kept) {
+      parentCount.set(d.parentLabel, (parentCount.get(d.parentLabel) || 0) + 1);
+    }
+    let bestRoot = '';
+    let bestCount = -1;
+    for (const [label, count] of parentCount) {
+      if (count > bestCount) {
+        bestCount = count;
+        bestRoot = label;
+      }
+    }
+    // Remove all deps where bestRoot is a child
+    return kept.filter((d) => d.childLabel !== bestRoot);
+  }
+
+  return kept;
+}
+
+/**
+ * Build a lookup map: childLabel → PropertyDependency[]
+ * A child can depend on multiple parents (rare but possible).
+ */
+export function buildDependencyMap(
+  deps: PropertyDependency[]
+): Map<string, PropertyDependency[]> {
+  const map = new Map<string, PropertyDependency[]>();
+  for (const dep of deps) {
+    const existing = map.get(dep.childLabel) || [];
+    existing.push(dep);
+    map.set(dep.childLabel, existing);
+  }
+  return map;
+}
+
+/**
+ * Extract the IDs that a child field should be narrowed to,
+ * based on the parent instance data and the linking property.
+ */
+export function extractNarrowingIds(
+  instanceData: Record<string, any>,
+  linkingPropertyLabel: string
+): string[] {
+  const linkedValue = instanceData[linkingPropertyLabel];
+  if (!linkedValue) return [];
+
+  if (Array.isArray(linkedValue)) {
+    return linkedValue
+      .map((v) => (typeof v === 'object' ? v.id : v))
+      .filter(Boolean);
+  }
+
+  if (typeof linkedValue === 'object' && linkedValue.id) {
+    return [linkedValue.id];
+  }
+
+  if (typeof linkedValue === 'string') {
+    return [linkedValue];
+  }
+
+  return [];
+}

package/src/shape/tableFilters.ts

@@ -0,0 +1,223 @@
+import type { PropertyShapeWire } from '@_linked/core/shapes/nodeShapeWire';
+import { humanizeEnumLabel } from './nodeDisplay.js';
+import { getPropertyUiType, type PropertyUiType } from './propertyTypes.js';
+
+// ─── Filter operators ────────────────────────────────────────────────
+export type FilterOperator =
+  | 'contains'
+  | 'equals'
+  | 'startsWith'
+  | 'endsWith'
+  | 'gt'
+  | 'lt'
+  | 'gte'
+  | 'lte'
+  | 'before'
+  | 'after'
+  | 'is'
+  | 'isNot'
+  | 'in'; // multi-select enum
+
+export interface FilterOperatorOption {
+  value: FilterOperator;
+  label: string;
+}
+
+// ─── Internal filter model (decoupled from TanStack) ─────────────────
+export interface TableFilter {
+  id: string; // unique filter ID
+  columnId: string;
+  columnLabel: string;
+  operator: FilterOperator;
+  /** Single value or array of values for multi-select (enum OR) */
+  value: string | string[];
+  isActive: boolean;
+}
+
+// ─── Operator sets by UI type ────────────────────────────────────────
+const STRING_OPERATORS: FilterOperatorOption[] = [
+  { value: 'contains', label: 'contains' },
+  { value: 'equals', label: 'equals' },
+  { value: 'startsWith', label: 'starts with' },
+  { value: 'endsWith', label: 'ends with' },
+];
+
+const NUMBER_OPERATORS: FilterOperatorOption[] = [
+  { value: 'equals', label: '=' },
+  { value: 'gt', label: '>' },
+  { value: 'lt', label: '<' },
+  { value: 'gte', label: '>=' },
+  { value: 'lte', label: '<=' },
+];
+
+const DATE_OPERATORS: FilterOperatorOption[] = [
+  { value: 'equals', label: 'equals' },
+  { value: 'before', label: 'before' },
+  { value: 'after', label: 'after' },
+];
+
+const BOOLEAN_OPERATORS: FilterOperatorOption[] = [
+  { value: 'is', label: 'is' },
+  { value: 'isNot', label: 'is not' },
+];
+
+const IRI_OPERATORS: FilterOperatorOption[] = [
+  { value: 'contains', label: 'contains' },
+  { value: 'equals', label: 'equals' },
+];
+
+const ENUM_OPERATORS: FilterOperatorOption[] = [
+  { value: 'in', label: 'is one of' },
+  { value: 'equals', label: 'equals' },
+];
+
+/**
+ * Returns the available filter operators for a property based on its SHACL type.
+ */
+export function getOperatorsForProperty(property: PropertyShapeWire): FilterOperatorOption[] {
+  const uiType = getPropertyUiType(property);
+  return getOperatorsForUiType(uiType);
+}
+
+export function getOperatorsForUiType(uiType: PropertyUiType | null): FilterOperatorOption[] {
+  switch (uiType) {
+    case 'number':
+      return NUMBER_OPERATORS;
+    case 'date':
+    case 'datetime':
+      return DATE_OPERATORS;
+    case 'boolean':
+      return BOOLEAN_OPERATORS;
+    case 'iri-single':
+    case 'iri-multi':
+      return IRI_OPERATORS;
+    case 'enum-literal':
+    case 'enum-iri':
+      return ENUM_OPERATORS;
+    case 'text':
+    case 'url':
+    default:
+      return STRING_OPERATORS;
+  }
+}
+
+/**
+ * Apply a filter to a cell value. Returns true if the row should be included.
+ */
+export function applyFilter(cellValue: any, filter: TableFilter): boolean {
+  if (!filter.isActive) return true;
+
+  const { operator, value } = filter;
+
+  // Multi-select enum: "in" operator
+  if (operator === 'in' && Array.isArray(value)) {
+    if (value.length === 0) return true;
+    const cellStr = extractStringValue(cellValue);
+    return value.some((v) => cellStr.toLowerCase() === v.toLowerCase());
+  }
+
+  const filterVal = typeof value === 'string' ? value : String(value);
+  if (!filterVal) return true;
+
+  const cellStr = extractStringValue(cellValue);
+
+  switch (operator) {
+    case 'contains':
+      return cellStr.toLowerCase().includes(filterVal.toLowerCase());
+    case 'equals':
+      return cellStr.toLowerCase() === filterVal.toLowerCase();
+    case 'startsWith':
+      return cellStr.toLowerCase().startsWith(filterVal.toLowerCase());
+    case 'endsWith':
+      return cellStr.toLowerCase().endsWith(filterVal.toLowerCase());
+
+    case 'gt':
+      return toNumber(cellStr) > toNumber(filterVal);
+    case 'lt':
+      return toNumber(cellStr) < toNumber(filterVal);
+    case 'gte':
+      return toNumber(cellStr) >= toNumber(filterVal);
+    case 'lte':
+      return toNumber(cellStr) <= toNumber(filterVal);
+
+    case 'before':
+      return new Date(cellStr) < new Date(filterVal);
+    case 'after':
+      return new Date(cellStr) > new Date(filterVal);
+
+    case 'is':
+      return cellStr.toLowerCase() === filterVal.toLowerCase();
+    case 'isNot':
+      return cellStr.toLowerCase() !== filterVal.toLowerCase();
+
+    default:
+      return true;
+  }
+}
+
+/**
+ * Apply all active filters to a row. Returns true if the row passes all filters (AND logic).
+ * Same-column filters with 'in' operator use OR within the column.
+ */
+export function applyAllFilters(
+  row: Record<string, any>,
+  filters: TableFilter[]
+): boolean {
+  const activeFilters = filters.filter((f) => f.isActive);
+  if (activeFilters.length === 0) return true;
+
+  // Group filters by column for same-column OR handling
+  const byColumn = new Map<string, TableFilter[]>();
+  for (const f of activeFilters) {
+    const group = byColumn.get(f.columnId) || [];
+    group.push(f);
+    byColumn.set(f.columnId, group);
+  }
+
+  // Each column group must pass (AND across columns)
+  for (const [columnId, columnFilters] of byColumn) {
+    const cellValue = row[columnId];
+    // Within a column, ANY filter passing counts (OR within column)
+    const columnPasses = columnFilters.some((f) => applyFilter(cellValue, f));
+    if (!columnPasses) return false;
+  }
+
+  return true;
+}
+
+/**
+ * Generate a unique filter ID.
+ */
+let filterCounter = 0;
+export function generateFilterId(): string {
+  return `filter-${++filterCounter}-${Date.now()}`;
+}
+
+/**
+ * Format a filter for display as a badge label.
+ */
+export function formatFilterLabel(filter: TableFilter): string {
+  const { columnLabel, operator, value } = filter;
+  if (operator === 'in' && Array.isArray(value)) {
+    return `${columnLabel}: ${value.map(humanizeEnumLabel).join(', ')}`;
+  }
+  const opLabel = [...STRING_OPERATORS, ...NUMBER_OPERATORS, ...DATE_OPERATORS, ...BOOLEAN_OPERATORS, ...ENUM_OPERATORS]
+    .find((o) => o.value === operator)?.label || operator;
+  return `${columnLabel} ${opLabel} ${value}`;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+function extractStringValue(val: any): string {
+  if (val == null) return '';
+  if (typeof val === 'string') return val;
+  if (typeof val === 'number' || typeof val === 'boolean') return String(val);
+  if (typeof val === 'object') {
+    return val.label || val.name || val.id || String(val);
+  }
+  return String(val);
+}
+
+function toNumber(val: string): number {
+  const n = parseFloat(val);
+  return isNaN(n) ? 0 : n;
+}