@contractspec/lib.contracts 1.44.0

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 };

package/dist/forms/docs/forms.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@contractspec/lib.contracts/docs";
+
+//#region src/forms/docs/forms.docblock.d.ts
+declare const tech_contracts_forms_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_forms_DocBlocks };

package/dist/forms/docs/forms.docblock.js

@@ -0,0 +1,21 @@
+import { registerDocBlocks } from "../../docs/registry.js";
+
+//#region src/forms/docs/forms.docblock.ts
+const tech_contracts_forms_DocBlocks = [{
+	id: "docs.tech.contracts.forms",
+	title: "Contracts: FormSpec",
+	summary: "This document defines the canonical contracts for declarative forms.",
+	kind: "reference",
+	visibility: "public",
+	route: "/docs/tech/contracts/forms",
+	tags: [
+		"tech",
+		"contracts",
+		"forms"
+	],
+	body: "# Contracts: FormSpec\n\nThis document defines the canonical contracts for declarative forms.\n\n## Overview\n\n- `FormSpec` (in `@contractspec/lib.contracts/forms`) declares:\n  - `meta` (extends `OwnerShipMeta`) + `key`/`version` for stability.\n  - `model` (`@contractspec/lib.schema` `SchemaModel`) as the single source of truth.\n  - `fields` built from `FieldSpec` kinds: `text`, `textarea`, `select`, `checkbox`, `radio`, `switch`, `group`, `array`.\n  - Optional `actions`, `policy.flags`, `constraints` and `renderHints`.\n- Relations DSL provides `visibleWhen`, `enabledWhen`, `requiredWhen` based on predicates.\n- `buildZodWithRelations(spec)` augments the base zod with conditional rules and constraints.\n- React adapter renders with React Hook Form + driver API for UI components (shadcn driver provided).\n\n## Driver API (UI-agnostic)\n\nHost apps supply a driver mapping slots → components:\n\n- Required: `Field`, `FieldLabel`, `FieldDescription`, `FieldError`, `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroup`, `Switch`, `Button`.\n- Optional: `FieldGroup`, `FieldSet`, `FieldLegend` and input group helpers.\n\nUse `createFormRenderer({ driver })` to obtain a `render(spec)` function.\n\n## Arrays and Groups\n\n- `array` items are rendered with `useFieldArray`, honoring `min`/`max` and add/remove controls.\n- `group` composes nested fields and provides optional legend/description.\n\n## Feature Flags\n\n- Declare `policy.flags` on forms to signal gating. Gate usage at host boundary; avoid scattering flags across individual fields.\n\n## Example\n\nSee `packages/hcircle/apps/web-coliving/src/forms/bug-report.spec.ts` for a concrete form spec and `components/forms/BugReportFormDemo.tsx` for rendering with a minimal shadcn driver mapping.\n"
+}];
+registerDocBlocks(tech_contracts_forms_DocBlocks);
+
+//#endregion
+export { tech_contracts_forms_DocBlocks };

package/dist/forms/forms.d.ts

@@ -0,0 +1,266 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { GroupKeyFn, RegistryFilter } from "../registry-utils.js";
+import { AnySchemaModel, ZodSchemaModel } from "@contractspec/lib.schema";
+
+//#region src/forms/forms.d.ts
+type PredicateOp = 'equals' | 'notEquals' | 'in' | 'notIn' | 'gt' | 'gte' | 'lt' | 'lte' | 'truthy' | 'empty' | 'lengthGt' | 'lengthGte' | 'lengthLt' | 'lengthLte';
+interface WhenClause {
+  /** Dot path in form values; arrays may use `$index` within array context. */
+  path: string;
+  op?: PredicateOp;
+  value?: unknown;
+}
+interface Predicate {
+  when?: WhenClause;
+  all?: Predicate[];
+  anyOf?: Predicate[];
+  not?: Predicate;
+}
+interface FormOption {
+  labelI18n: string;
+  value: string | number | boolean;
+  descriptionI18n?: string;
+  disabled?: boolean;
+}
+type OptionsSource = {
+  kind: 'static';
+  options: readonly FormOption[];
+} | {
+  kind: 'resolver';
+  resolverKey: string;
+  /** Dot paths in form values to watch */
+  deps: string[];
+  args?: Record<string, unknown>;
+};
+interface BaseFieldSpec {
+  /** Field kind discriminator. */
+  kind: 'text' | 'textarea' | 'select' | 'checkbox' | 'radio' | 'switch' | 'group' | 'array';
+  /** Field name (dot path relative to the form root or parent context). */
+  name?: string;
+  labelI18n?: string;
+  descriptionI18n?: string;
+  placeholderI18n?: string;
+  required?: boolean;
+  /** Conditional UI behavior */
+  visibleWhen?: Predicate;
+  enabledWhen?: Predicate;
+  requiredWhen?: Predicate;
+  /** UI hints */
+  uiKey?: string;
+  uiProps?: Record<string, unknown>;
+  wrapper?: {
+    orientation?: 'horizontal' | 'vertical';
+  };
+  /** HTML/Native autofill token (supports custom tokens) */
+  autoComplete?: string;
+  /** Keyboard/adaptation hints (web/native). Shape mirrors design-system KeyboardOptions but stays decoupled. */
+  keyboard?: {
+    kind?: string;
+    autoCapitalize?: 'none' | 'sentences' | 'words' | 'characters';
+    autoComplete?: string;
+    autoCorrect?: boolean;
+    enterKeyHint?: 'enter' | 'done' | 'go' | 'next' | 'search' | 'send';
+  };
+  /** Optional computed value hook, provided by host computations map */
+  computeFrom?: {
+    computeKey: string;
+    deps: string[];
+    mode?: 'change' | 'blur-xs' | 'submit';
+    readOnly?: boolean;
+  };
+}
+interface TextFieldSpec extends BaseFieldSpec {
+  kind: 'text';
+  name: string;
+  inputMode?: 'text' | 'email' | 'tel' | 'url' | 'numeric' | 'decimal' | 'search';
+  autoComplete?: string;
+  maxLength?: number;
+  minLength?: number;
+}
+interface TextareaFieldSpec extends BaseFieldSpec {
+  kind: 'textarea';
+  name: string;
+  rows?: number;
+  maxLength?: number;
+  minLength?: number;
+}
+interface SelectFieldSpec extends BaseFieldSpec {
+  kind: 'select';
+  name: string;
+  options: OptionsSource | readonly FormOption[];
+}
+interface CheckboxFieldSpec extends BaseFieldSpec {
+  kind: 'checkbox';
+  name: string;
+}
+interface RadioFieldSpec extends BaseFieldSpec {
+  kind: 'radio';
+  name: string;
+  options: OptionsSource | readonly FormOption[];
+}
+interface SwitchFieldSpec extends BaseFieldSpec {
+  kind: 'switch';
+  name: string;
+}
+interface GroupFieldSpec extends BaseFieldSpec {
+  kind: 'group';
+  /** Optional legend/label at group level */
+  labelI18n?: string;
+  fields: FieldSpec[];
+}
+interface ArrayFieldSpec extends BaseFieldSpec {
+  kind: 'array';
+  /** Root-level field that is an array in the model (e.g., "emails") */
+  name: string;
+  /** Child field spec for each item (e.g., address inside emails[i].address). */
+  of: Exclude<FieldSpec, ArrayFieldSpec | GroupFieldSpec>;
+  min?: number;
+  max?: number;
+}
+type FieldSpec = TextFieldSpec | TextareaFieldSpec | SelectFieldSpec | CheckboxFieldSpec | RadioFieldSpec | SwitchFieldSpec | GroupFieldSpec | ArrayFieldSpec;
+interface FormAction {
+  key: string;
+  labelI18n: string;
+  op?: {
+    name: string;
+    version: number;
+  };
+  success?: {
+    navigateTo?: string;
+    toastI18n?: string;
+  };
+}
+interface ConstraintDecl {
+  key: string;
+  messageI18n: string;
+  paths: string[];
+  args?: Record<string, unknown>;
+}
+type FormValuesFor<M extends AnySchemaModel> = ZodSchemaModel<M>;
+interface FormSpec<M extends AnySchemaModel = AnySchemaModel> {
+  meta: OwnerShipMeta;
+  /** Canonical form data shape */
+  model: M;
+  /** Flat list or tree using groups/arrays */
+  fields: FieldSpec[];
+  policy?: {
+    flags?: string[];
+    pii?: string[];
+  };
+  actions?: FormAction[];
+  renderHints?: {
+    ui: 'shadcn' | 'custom';
+    form: 'react-hook-form';
+  };
+  constraints?: ConstraintDecl[];
+}
+declare class FormRegistry {
+  private items;
+  register(spec: FormSpec): this;
+  list(): FormSpec[];
+  get(key: string, version?: number): FormSpec<AnySchemaModel> | undefined;
+  /** Filter forms by criteria. */
+  filter(criteria: RegistryFilter): FormSpec[];
+  /** List forms with specific tag. */
+  listByTag(tag: string): FormSpec[];
+  /** List forms by owner. */
+  listByOwner(owner: string): FormSpec[];
+  /** Group forms by key function. */
+  groupBy(keyFn: GroupKeyFn<FormSpec>): Map<string, FormSpec[]>;
+  /** Get unique tags from all forms. */
+  getUniqueTags(): string[];
+}
+declare function evalPredicate(values: unknown, pred?: Predicate): boolean;
+type ConstraintHandler = (values: Record<string, unknown>, paths: string[], args?: Record<string, unknown>) => {
+  ok: true;
+} | {
+  ok: false;
+  message?: string;
+  path?: string;
+};
+/**
+ * Wrap the base zod schema with relation-driven refinements (requiredWhen, array min/max)
+ * and optional custom constraints. Call this when wiring RHF resolver.
+ */
+declare function buildZodWithRelations(spec: FormSpec, handlers?: Record<string, ConstraintHandler>): any;
+interface AnyFieldLike {
+  kind: string;
+  name?: string;
+  fields?: readonly AnyFieldLike[];
+  of?: AnyFieldLike;
+}
+type TopLevelNames<F extends readonly AnyFieldLike[]> = F[number] extends {
+  name: infer N extends string;
+} ? N : never;
+type ArrayChildren<F extends readonly AnyFieldLike[]> = F[number] extends {
+  kind: 'array';
+  name: infer N extends string;
+  of: infer C;
+} ? C extends {
+  name: infer CN extends string;
+} ? `${N}.$index.${CN}` : never : never;
+type GroupTopLevelNames<F extends readonly AnyFieldLike[]> = F[number] extends {
+  kind: 'group';
+  fields: infer G extends readonly AnyFieldLike[];
+} ? TopLevelNames<G> : never;
+type GroupArrayChildren<F extends readonly AnyFieldLike[]> = F[number] extends {
+  kind: 'group';
+  fields: infer G extends readonly AnyFieldLike[];
+} ? ArrayChildren<G> : never;
+type PathOfFields<F extends readonly AnyFieldLike[]> = TopLevelNames<F> | ArrayChildren<F> | GroupTopLevelNames<F> | GroupArrayChildren<F>;
+interface TypedWhenClause<P extends string> {
+  path: P;
+  op?: PredicateOp;
+  value?: unknown;
+}
+interface TypedPredicate<P extends string> {
+  when?: TypedWhenClause<P>;
+  all?: TypedPredicate<P>[];
+  anyOf?: TypedPredicate<P>[];
+  not?: TypedPredicate<P>;
+}
+type TypedOptionsSource<P extends string> = {
+  kind: 'static';
+  options: readonly FormOption[];
+} | {
+  kind: 'resolver';
+  resolverKey: string;
+  deps: P[];
+  args?: Record<string, unknown>;
+};
+type EnhanceFields<F extends readonly AnyFieldLike[], P extends string> = { [K in keyof F]: F[K] & {
+  visibleWhen?: TypedPredicate<P>;
+  enabledWhen?: TypedPredicate<P>;
+  requiredWhen?: TypedPredicate<P>;
+} & (F[K] extends {
+  kind: 'select';
+} ? {
+  options: TypedOptionsSource<P> | readonly FormOption[];
+} : unknown) & (F[K] extends {
+  kind: 'radio';
+} ? {
+  options: TypedOptionsSource<P> | readonly FormOption[];
+} : unknown) & {
+  computeFrom?: {
+    computeKey: string;
+    deps: P[];
+    mode?: 'change' | 'blur-xs' | 'submit';
+    readOnly?: boolean;
+  };
+} };
+declare function defineFormSpec<M extends AnySchemaModel, F extends readonly AnyFieldLike[]>(spec: {
+  meta: FormSpec<M>['meta'];
+  model: M;
+  fields: EnhanceFields<F, PathOfFields<F>>;
+  policy?: FormSpec<M>['policy'];
+  actions?: FormSpec<M>['actions'];
+  renderHints?: FormSpec<M>['renderHints'];
+  constraints?: {
+    key: string;
+    messageI18n: string;
+    paths: PathOfFields<F>[];
+    args?: Record<string, unknown>;
+  }[];
+}): FormSpec<M>;
+//#endregion
+export { ArrayFieldSpec, BaseFieldSpec, CheckboxFieldSpec, ConstraintDecl, ConstraintHandler, EnhanceFields, FieldSpec, FormAction, FormOption, FormRegistry, FormSpec, FormValuesFor, GroupFieldSpec, OptionsSource, Predicate, PredicateOp, RadioFieldSpec, SelectFieldSpec, SwitchFieldSpec, TextFieldSpec, TextareaFieldSpec, TypedOptionsSource, TypedPredicate, TypedWhenClause, WhenClause, buildZodWithRelations, defineFormSpec, evalPredicate };