@lssm/lib.contracts 1.43.0 → 1.43.2

package/dist/data-views/registry.js

@@ -0,0 +1,82 @@
+import { filterBy, getUniqueTags, groupBy, init_registry_utils } from "../registry-utils.js";
+
+//#region src/data-views/registry.ts
+init_registry_utils();
+/**
+* Generate a unique key for a data view spec.
+*/
+function dataViewKey(spec) {
+	return `${spec.meta.key}.v${spec.meta.version}`;
+}
+/**
+* Registry for managing data view specifications.
+*/
+var DataViewRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	/**
+	* Register a data view spec.
+	* @throws Error if a spec with the same key already exists.
+	*/
+	register(spec) {
+		const key = dataViewKey(spec);
+		if (this.items.has(key)) throw new Error(`Duplicate data view ${key}`);
+		this.items.set(key, spec);
+		return this;
+	}
+	/**
+	* List all registered data view specs.
+	*/
+	list() {
+		return [...this.items.values()];
+	}
+	/**
+	* Get a data view by key and optional version.
+	* If version is not specified, returns the latest version.
+	*/
+	get(name, version) {
+		if (version != null) return this.items.get(`${name}.v${version}`);
+		let candidate;
+		let max = -Infinity;
+		for (const spec of this.items.values()) {
+			if (spec.meta.key !== name) continue;
+			if (spec.meta.version > max) {
+				max = spec.meta.version;
+				candidate = spec;
+			}
+		}
+		return candidate;
+	}
+	/**
+	* Filter data views by criteria.
+	*/
+	filter(criteria) {
+		return filterBy(this.list(), criteria);
+	}
+	/**
+	* List data views with specific tag.
+	*/
+	listByTag(tag) {
+		return this.list().filter((d) => d.meta.tags?.includes(tag));
+	}
+	/**
+	* List data views by owner.
+	*/
+	listByOwner(owner) {
+		return this.list().filter((d) => d.meta.owners?.includes(owner));
+	}
+	/**
+	* Group data views by key function.
+	*/
+	groupBy(keyFn) {
+		return groupBy(this.list(), keyFn);
+	}
+	/**
+	* Get unique tags from all data views.
+	*/
+	getUniqueTags() {
+		return getUniqueTags(this.list());
+	}
+};
+
+//#endregion
+export { DataViewRegistry, dataViewKey };

package/dist/data-views/runtime.d.ts

@@ -1,4 +1,5 @@
-import { DataViewRegistry, DataViewSpec } from "./data-views.js";
+import { DataViewSpec } from "./spec.js";
+import { DataViewRegistry } from "./registry.js";
 import "./index.js";
 
 //#region src/data-views/runtime.d.ts

package/dist/data-views/spec.d.ts

@@ -0,0 +1,32 @@
+import { ExperimentRef } from "../experiments/spec.js";
+import { DataViewConfig, DataViewMeta, DataViewSource, DataViewStates } from "./types.js";
+
+//#region src/data-views/spec.d.ts
+
+/**
+ * Complete specification for a data view.
+ */
+interface DataViewSpec {
+  meta: DataViewMeta;
+  source: DataViewSource;
+  view: DataViewConfig;
+  states?: DataViewStates;
+  policy?: {
+    flags?: string[];
+    pii?: string[];
+  };
+  experiments?: ExperimentRef[];
+}
+/**
+ * Reference to a data view spec.
+ */
+interface DataViewRef {
+  key: string;
+  version: number;
+}
+/**
+ * Helper to define a data view spec with type safety.
+ */
+declare function defineDataView(spec: DataViewSpec): DataViewSpec;
+//#endregion
+export { DataViewRef, DataViewSpec, defineDataView };

package/dist/data-views/spec.js

@@ -0,0 +1,10 @@
+//#region src/data-views/spec.ts
+/**
+* Helper to define a data view spec with type safety.
+*/
+function defineDataView(spec) {
+	return spec;
+}
+
+//#endregion
+export { defineDataView };

package/dist/data-views/types.d.ts

@@ -0,0 +1,157 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { EventRef, OpRef, PresentationRef } from "../features/types.js";
+import "../features/index.js";
+
+//#region src/data-views/types.d.ts
+/**
+ * Supported data view kinds.
+ */
+type DataViewKind = 'list' | 'detail' | 'table' | 'grid';
+/**
+ * Metadata for a data view spec.
+ */
+interface DataViewMeta extends OwnerShipMeta {
+  /** Canonical entity slug (e.g., "space", "resident"). */
+  entity: string;
+}
+/**
+ * Source configuration for fetching data in a data view.
+ */
+interface DataViewSource {
+  /** Primary query used to fetch items for this view. */
+  primary: OpRef;
+  /** Optional operation used to fetch a single item (detail views). */
+  item?: OpRef;
+  /** Optional record mutation operations (used for inline editing or actions). */
+  mutations?: {
+    create?: OpRef;
+    update?: OpRef;
+    delete?: OpRef;
+  };
+  /** Events that should trigger refresh when emitted. */
+  refreshEvents?: EventRef[];
+}
+/**
+ * Display formatting hints for data view fields.
+ */
+type DataViewFieldFormat = 'text' | 'number' | 'currency' | 'percentage' | 'date' | 'dateTime' | 'boolean' | 'badge';
+/**
+ * Field definition within a data view.
+ */
+interface DataViewField {
+  /** Unique identifier for the field within the view. */
+  key: string;
+  /** Human-friendly label for headers/tooltips. */
+  label: string;
+  /** Dot-path into the data item (e.g., "address.city"). */
+  dataPath: string;
+  /** Optional description surfaced in tooltips or docs. */
+  description?: string;
+  /** Optional formatting hint for renderers. */
+  format?: DataViewFieldFormat;
+  /** When true, the field can be used for sorting. */
+  sortable?: boolean;
+  /** When true, the field can be used for filtering. */
+  filterable?: boolean;
+  /** Optional width hint for table layouts. */
+  width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';
+  /** Optional presentation override (e.g., card component). */
+  presentation?: PresentationRef;
+}
+/**
+ * Filter definition for a data view.
+ */
+interface DataViewFilter {
+  key: string;
+  label: string;
+  field: string;
+  type: 'search' | 'enum' | 'number' | 'date' | 'boolean';
+  options?: {
+    value: string;
+    label: string;
+  }[];
+}
+/**
+ * Action that can be triggered from a data view.
+ */
+interface DataViewAction {
+  key: string;
+  label: string;
+  kind: 'navigation' | 'operation';
+  /** Operation invoked when kind === 'operation'. */
+  operation?: OpRef;
+  /** Optional feature flag gating the action. */
+  requiresFlag?: string;
+}
+/**
+ * Section configuration for detail views.
+ */
+interface DataViewSections {
+  title?: string;
+  description?: string;
+  fields: string[];
+}
+/**
+ * Base configuration shared by all data view kinds.
+ */
+interface DataViewBaseConfig {
+  kind: DataViewKind;
+  fields: DataViewField[];
+  primaryField?: string;
+  secondaryFields?: string[];
+  filters?: DataViewFilter[];
+  actions?: DataViewAction[];
+}
+/**
+ * List view configuration.
+ */
+interface DataViewListConfig extends DataViewBaseConfig {
+  kind: 'list';
+  layout?: 'card' | 'compact';
+}
+/**
+ * Detail view configuration.
+ */
+interface DataViewDetailConfig extends DataViewBaseConfig {
+  kind: 'detail';
+  sections?: DataViewSections[];
+}
+/**
+ * Table column configuration.
+ */
+interface DataViewTableColumn {
+  field: string;
+  label?: string;
+  width?: 'auto' | 'xs' | 'sm' | 'md' | 'lg';
+  align?: 'left' | 'center' | 'right';
+}
+/**
+ * Table view configuration.
+ */
+interface DataViewTableConfig extends DataViewBaseConfig {
+  kind: 'table';
+  columns?: DataViewTableColumn[];
+  rowSelectable?: boolean;
+  density?: 'comfortable' | 'compact';
+}
+/**
+ * Grid view configuration.
+ */
+interface DataViewGridConfig extends DataViewBaseConfig {
+  kind: 'grid';
+  columns?: number;
+}
+/**
+ * Union of all data view configurations.
+ */
+type DataViewConfig = DataViewListConfig | DataViewDetailConfig | DataViewTableConfig | DataViewGridConfig;
+/**
+ * Presentation references for different view states.
+ */
+interface DataViewStates {
+  empty?: PresentationRef;
+  error?: PresentationRef;
+  loading?: PresentationRef;
+}
+//#endregion
+export { DataViewAction, DataViewBaseConfig, DataViewConfig, DataViewDetailConfig, DataViewField, DataViewFieldFormat, DataViewFilter, DataViewGridConfig, DataViewKind, DataViewListConfig, DataViewMeta, DataViewSections, DataViewSource, DataViewStates, DataViewTableColumn, DataViewTableConfig };

package/dist/experiments/spec-resolver.d.ts

@@ -1,7 +1,7 @@
-import "../operations/index.js";
 import { ResourceRefDescriptor } from "../resources.js";
 import { HandlerCtx } from "../types.js";
 import { OpKind, OperationSpec } from "../operations/operation.js";
+import "../operations/index.js";
 import { AnySchemaModel } from "@lssm/lib.schema";
 
 //#region src/experiments/spec-resolver.d.ts

package/dist/features/index.d.ts

@@ -0,0 +1,5 @@
+import { EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, OpRef, PresentationRef } from "./types.js";
+import { FeatureRegistry } from "./registry.js";
+import { InstallFeatureDeps, installFeature } from "./install.js";
+import { validateFeatureTargetsV2 } from "./validation.js";
+export { type EventRef, type FeatureModuleMeta, type FeatureModuleSpec, type FeatureRef, FeatureRegistry, type InstallFeatureDeps, type OpRef, type PresentationRef, installFeature, validateFeatureTargetsV2 };

package/dist/features/index.js

@@ -0,0 +1,5 @@
+import { FeatureRegistry } from "./registry.js";
+import { installFeature } from "./install.js";
+import { validateFeatureTargetsV2 } from "./validation.js";
+
+export { FeatureRegistry, installFeature, validateFeatureTargetsV2 };

package/dist/features/install.d.ts

@@ -0,0 +1,22 @@
+import { PresentationSpec } from "../presentations/presentations.js";
+import { CapabilityRegistry } from "../capabilities/capabilities.js";
+import "../capabilities/index.js";
+import { OperationSpecRegistry } from "../operations/registry.js";
+import { FeatureModuleSpec } from "./types.js";
+import { FeatureRegistry } from "./registry.js";
+import { PresentationRegistry } from "../presentations/registry.js";
+import "../presentations/index.js";
+
+//#region src/features/install.d.ts
+/** Dependencies for installing a feature. */
+interface InstallFeatureDeps {
+  features: FeatureRegistry;
+  ops?: OperationSpecRegistry;
+  presentations?: PresentationRegistry;
+  descriptors?: PresentationSpec[];
+  capabilities?: CapabilityRegistry;
+}
+/** Validate and register a feature against optional registries/descriptors. */
+declare function installFeature(feature: FeatureModuleSpec, deps: InstallFeatureDeps): FeatureRegistry;
+//#endregion
+export { InstallFeatureDeps, installFeature };

package/dist/features/install.js

@@ -0,0 +1,36 @@
+//#region src/features/install.ts
+/** Validate and register a feature against optional registries/descriptors. */
+function installFeature(feature, deps) {
+	if (deps.ops && feature.operations) {
+		for (const o of feature.operations) if (!deps.ops.getSpec(o.key, o.version)) throw new Error(`installFeature: operation not found ${o.key}.v${o.version}`);
+	}
+	if (deps.presentations && feature.presentations) {
+		for (const p of feature.presentations) if (!deps.presentations.get(p.key, p.version)) throw new Error(`installFeature: presentation not found ${p.key}.v${p.version}`);
+	}
+	if (feature.presentationsTargets && deps.descriptors) for (const req of feature.presentationsTargets) {
+		const d = deps.descriptors.find((x) => x.meta.key === req.key && x.meta.version === req.version);
+		if (!d) throw new Error(`installFeature: V2 descriptor not found ${req.key}.v${req.version}`);
+		for (const t of req.targets) if (!d.targets.includes(t)) throw new Error(`installFeature: descriptor ${req.key}.v${req.version} missing target ${t}`);
+	}
+	if (feature.opToPresentation && feature.opToPresentation.length > 0) for (const link of feature.opToPresentation) {
+		if (deps.ops) {
+			if (!deps.ops.getSpec(link.op.key, link.op.version)) throw new Error(`installFeature: linked op not found ${link.op.key}.v${link.op.version}`);
+		}
+		if (deps.presentations) {
+			if (!deps.presentations.get(link.pres.key, link.pres.version)) throw new Error(`installFeature: linked presentation not found ${link.pres.key}.v${link.pres.version}`);
+		}
+	}
+	if (deps.capabilities && feature.capabilities?.provides) {
+		for (const cap of feature.capabilities.provides) if (!deps.capabilities.get(cap.key, cap.version)) throw new Error(`installFeature: capability not registered ${cap.key}.v${cap.version}`);
+	}
+	if (feature.capabilities?.requires?.length) {
+		if (!deps.capabilities) throw new Error(`installFeature: capability registry required to validate capability requirements for ${feature.meta.key}`);
+		const provided = feature.capabilities.provides ?? [];
+		for (const req of feature.capabilities.requires) if (!deps.capabilities.satisfies(req, provided)) throw new Error(`installFeature: capability requirement not satisfied ${req.key}${req.version ? `.v${req.version}` : ""}`);
+	}
+	deps.features.register(feature);
+	return deps.features;
+}
+
+//#endregion
+export { installFeature };

package/dist/features/registry.d.ts

@@ -0,0 +1,26 @@
+import { GroupKeyFn, RegistryFilter } from "../registry-utils.js";
+import { FeatureModuleSpec } from "./types.js";
+
+//#region src/features/registry.d.ts
+/** In-memory registry for FeatureModuleSpec. */
+declare class FeatureRegistry {
+  private items;
+  /** Register a feature module. Throws when the key already exists. */
+  register(f: FeatureModuleSpec): this;
+  /** List all registered feature modules. */
+  list(): FeatureModuleSpec[];
+  /** Get a feature by its key (slug). */
+  get(key: string): FeatureModuleSpec | undefined;
+  /** Filter features by criteria. */
+  filter(criteria: RegistryFilter): FeatureModuleSpec[];
+  /** List features with specific tag. */
+  listByTag(tag: string): FeatureModuleSpec[];
+  /** List features by owner. */
+  listByOwner(owner: string): FeatureModuleSpec[];
+  /** Group features by key function. */
+  groupBy(keyFn: GroupKeyFn<FeatureModuleSpec>): Map<string, FeatureModuleSpec[]>;
+  /** Get unique tags from all features. */
+  getUniqueTags(): string[];
+}
+//#endregion
+export { FeatureRegistry };

package/dist/features/registry.js

@@ -0,0 +1,49 @@
+import { filterBy, getUniqueTags, groupBy, init_registry_utils } from "../registry-utils.js";
+
+//#region src/features/registry.ts
+init_registry_utils();
+function keyOf(f) {
+	return f.meta.key;
+}
+/** In-memory registry for FeatureModuleSpec. */
+var FeatureRegistry = class {
+	items = /* @__PURE__ */ new Map();
+	/** Register a feature module. Throws when the key already exists. */
+	register(f) {
+		const key = keyOf(f);
+		if (this.items.has(key)) throw new Error(`Duplicate feature ${key}`);
+		this.items.set(key, f);
+		return this;
+	}
+	/** List all registered feature modules. */
+	list() {
+		return [...this.items.values()];
+	}
+	/** Get a feature by its key (slug). */
+	get(key) {
+		return this.items.get(key);
+	}
+	/** Filter features by criteria. */
+	filter(criteria) {
+		return filterBy(this.list(), criteria);
+	}
+	/** List features with specific tag. */
+	listByTag(tag) {
+		return this.list().filter((f) => f.meta.tags?.includes(tag));
+	}
+	/** List features by owner. */
+	listByOwner(owner) {
+		return this.list().filter((f) => f.meta.owners?.includes(owner));
+	}
+	/** Group features by key function. */
+	groupBy(keyFn) {
+		return groupBy(this.list(), keyFn);
+	}
+	/** Get unique tags from all features. */
+	getUniqueTags() {
+		return getUniqueTags(this.list());
+	}
+};
+
+//#endregion
+export { FeatureRegistry };

package/dist/features/types.d.ts

@@ -0,0 +1,88 @@
+import { PresentationTarget } from "../presentations/presentations.js";
+import { OwnerShipMeta } from "../ownership.js";
+import { CapabilityRef, CapabilityRequirement } from "../capabilities/capabilities.js";
+import "../capabilities/index.js";
+import { ExperimentRef } from "../experiments/spec.js";
+import { ImplementationRef } from "../operations/operation.js";
+import "../operations/index.js";
+
+//#region src/features/types.d.ts
+/** Minimal metadata to identify and categorize a feature module. */
+type FeatureModuleMeta = OwnerShipMeta;
+interface OpRef {
+  /** Operation key (OperationSpec.meta.key). */
+  key: string;
+  /** Operation version (OperationSpec.meta.version). */
+  version: number;
+}
+interface EventRef {
+  /** Event key. */
+  key: string;
+  /** Event version. */
+  version: number;
+}
+interface PresentationRef {
+  /** Presentation key. */
+  key: string;
+  /** Presentation version. */
+  version: number;
+}
+/**
+ * Reference to a data view spec.
+ */
+interface DataViewRef {
+  key: string;
+  version: number;
+}
+/**
+ * Reference to a form spec.
+ */
+interface FormRef {
+  key: string;
+  version: number;
+}
+/** Group operations/events/presentations into an installable feature. */
+interface FeatureModuleSpec {
+  meta: FeatureModuleMeta;
+  /** Contract operations included in this feature. */
+  operations?: OpRef[];
+  /** Events declared/emitted by this feature. */
+  events?: EventRef[];
+  /** Presentations associated to this feature. */
+  presentations?: PresentationRef[];
+  /** Experiments related to this feature. */
+  experiments?: ExperimentRef[];
+  /** Capability bindings exposed/required by this feature. */
+  capabilities?: {
+    provides?: CapabilityRef[];
+    requires?: CapabilityRequirement[];
+  };
+  /** Optional: link ops to presentations for traceability (e.g., ui for op) */
+  opToPresentation?: {
+    op: OpRef;
+    pres: PresentationRef;
+  }[];
+  /** Optional: declare per-presentation target requirements (V2 descriptors) */
+  presentationsTargets?: {
+    /** Presentation key. */
+    key: string;
+    /** Presentation version. */
+    version: number;
+    /** Required targets that must be supported by the descriptor. */
+    targets: PresentationTarget[];
+  }[];
+  /**
+   * Explicit implementation file mappings for the entire feature module.
+   * Used for tracking and verifying that this feature is correctly implemented.
+   */
+  implementations?: ImplementationRef[];
+  /** Data views associated with this feature. */
+  dataViews?: DataViewRef[];
+  /** Forms associated with this feature. */
+  forms?: FormRef[];
+}
+interface FeatureRef {
+  key: string;
+}
+//#endregion
+export { DataViewRef, EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, FormRef, OpRef, PresentationRef };

package/dist/features/validation.d.ts

@@ -0,0 +1,8 @@
+import { PresentationSpec } from "../presentations/presentations.js";
+import { FeatureModuleSpec } from "./types.js";
+
+//#region src/features/validation.d.ts
+/** Ensure declared target requirements exist on the provided descriptors. */
+declare function validateFeatureTargetsV2(feature: FeatureModuleSpec, descriptors: PresentationSpec[]): boolean;
+//#endregion
+export { validateFeatureTargetsV2 };

package/dist/features/validation.js

@@ -0,0 +1,14 @@
+//#region src/features/validation.ts
+/** Ensure declared target requirements exist on the provided descriptors. */
+function validateFeatureTargetsV2(feature, descriptors) {
+	if (!feature.presentationsTargets || feature.presentationsTargets.length === 0) return true;
+	for (const req of feature.presentationsTargets) {
+		const d = descriptors.find((x) => x.meta.key === req.key && x.meta.version === req.version);
+		if (!d) throw new Error(`V2 descriptor not found ${req.key}.v${req.version}`);
+		for (const t of req.targets) if (!d.targets.includes(t)) throw new Error(`Descriptor ${req.key}.v${req.version} missing target ${t}`);
+	}
+	return true;
+}
+
+//#endregion
+export { validateFeatureTargetsV2 };