@dxos/echo 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/index.ts

@@ -8,7 +8,6 @@ export { DXN, EID, URI } from '@dxos/keys';
 export * as Annotation from './Annotation';
 export * as Database from './Database';
 export * as Entity from './Entity';
-// TODO(burdon): Rename to Error (less problematic than Obj/Object).
 export * as Err from './Err';
 export * as Feed from './Feed';
 export * as Filter from './Filter';
@@ -27,6 +26,7 @@ export * as Registry from './Registry';
 export * as Relation from './Relation';
 export * as Scope from './Scope';
 export * as Tag from './Tag';
+export * as Text from './Text';
 export * as Type from './Type';
 export * as Collection from './Collection';
 export * as View from './View';

package/src/internal/Annotation/annotations.ts

@@ -395,8 +395,11 @@ export const setDescriptionWithSchema = <S extends Schema.Schema.Any>(
   object: Schema.Schema.Type<S>,
   description: string,
 ) => {
-  const accessor = DescriptionAnnotation.get(schema).pipe(Option.getOrElse(() => 'description'));
-  object[accessor] = description;
+  const accessorOpt = DescriptionAnnotation.get(schema);
+  if (Option.isNone(accessorOpt)) {
+    return;
+  }
+  object[accessorOpt.value] = description;
 };
 
 /**
@@ -413,6 +416,57 @@ export const FormInputAnnotation = createAnnotationHelper<boolean>(FormInputAnno
 export const FormInlineAnnotationId = Symbol.for('@dxos/schema/annotation/FormInline');
 export const FormInlineAnnotation = createAnnotationHelper<boolean>(FormInlineAnnotationId);
 
+/**
+ * When set on a `Ref` (or array-of-`Ref`) property, the form OWNS the referenced target(s): "add" creates a
+ * new object of the annotation's typename (instead of opening the existing-object picker) and each target is
+ * rendered inline — its own fields — like {@link FormInlineAnnotation}. The target typename is carried here
+ * (rather than inferred from the element type) so the field can stay `Ref.Ref(Obj.Unknown)` and avoid pulling
+ * the target's type (e.g. query-AST-laden `Trigger`) into the schema's emitted declaration.
+ */
+export const FormCreateAnnotationId = Symbol.for('@dxos/schema/annotation/FormCreate');
+export const FormCreateAnnotation = createAnnotationHelper<string>(FormCreateAnnotationId);
+
+/**
+ * When set on an array property, the form renders it as an ordered,
+ * drag-to-reorder list (drag handles per row). Element order is meaningful and
+ * user-controllable; reordering rewrites the array.
+ */
+export const FormOrderedAnnotationId = Symbol.for('@dxos/schema/annotation/FormOrdered');
+export const FormOrderedAnnotation = createAnnotationHelper<boolean>(FormOrderedAnnotationId);
+
+/**
+ * Annotation carrying one or more named layout DSL templates that control how a
+ * form arranges a schema's fields (consumed by `@dxos/react-ui-form`'s
+ * `Form.Layout` / `Form.FieldSet`). Callers select a variant by name; the
+ * implicit name is `DEFAULT_LAYOUT_NAME` (`'default'`).
+ *
+ * Templates use a minimal XML grammar. Example:
+ *
+ *   FormLayoutAnnotation.set({
+ *     default: `
+ *       <grid cols="2">
+ *         <field name="origin"/>
+ *         <field name="destination"/>
+ *         <field name="provider" span="2"/>
+ *       </grid>
+ *     `,
+ *     card: `
+ *       <grid cols="1">
+ *         <field name="provider"/>
+ *         <field name="number"/>
+ *       </grid>
+ *     `,
+ *   })
+ */
+export const FormLayoutAnnotationId = Symbol.for('@dxos/react-ui-form/annotation/Layout');
+
+export type FormLayoutMap = Record<string, string>;
+
+export const FormLayoutAnnotation = createAnnotationHelper<FormLayoutMap>(FormLayoutAnnotationId);
+
+/** Name used when no explicit form-layout variant is requested. */
+export const DEFAULT_LAYOUT_NAME = 'default';
+
 /**
  * Default field to be used on referenced schema to lookup the value.
  */
@@ -557,6 +611,21 @@ export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
   }
 };
 
+/**
+ * Returns the primary label property key for an entity.
+ * Reads the first accessor from {@link LabelAnnotation}, defaulting to 'name'.
+ */
+export const getLabelProperty = (entity: AnyProperties): string => {
+  const schema = getSchema(entity);
+  if (schema == null) {
+    return 'name';
+  }
+  return LabelAnnotation.get(schema).pipe(
+    Option.flatMap((fields) => Option.fromNullable(fields[0])),
+    Option.getOrElse(() => 'name'),
+  );
+};
+
 /**
  * Get the description of an entity.
  * Accepts both reactive entities and snapshots.

package/src/internal/Annotation/atoms.ts

@@ -0,0 +1,107 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import * as Data from 'effect/Data';
+import * as Option from 'effect/Option';
+
+import { assertArgument } from '@dxos/invariant';
+
+import type * as Annotation from '../../Annotation';
+import type * as Entity from '../../Entity';
+import { snapshotForComparison } from '../common/atom-snapshot';
+import { subscribe } from '../common/proxy/reactive';
+import { isEntity } from '../Entity';
+import { get as getAnnotation } from './entity-dictionary';
+
+/**
+ * Atom family for an annotation value on an entity instance.
+ * Mirrors the object-property atom family: re-emits a fresh reference whenever the entity changes
+ * (so an in-place array mutation is observed) and dedupes primitive values via `!==`.
+ */
+const annotationFamily = Atom.family((target: Entity.Unknown) =>
+  Atom.family(<T>(annotation: Annotation.Annotation<T>): Atom.Atom<Option.Option<T>> => {
+    const read = (): Option.Option<T> => Option.map(getAnnotation(target, annotation), snapshotForComparison);
+
+    return Atom.make<Option.Option<T>>((get) => {
+      let previous = read();
+
+      const unsubscribe = subscribe(target, () => {
+        const next = read();
+        if (!sameOption(previous, next)) {
+          previous = next;
+          get.setSelf(next);
+        }
+      });
+      get.addFinalizer(() => unsubscribe());
+
+      return previous;
+    }).pipe(Atom.keepAlive);
+  }),
+);
+
+/**
+ * Atom family for a single key of a record-valued annotation on an entity instance.
+ * Keyed by a value-equal `Data.tuple([target, annotation, key])` so nested families are avoided.
+ */
+const annotationPropertyFamily = Atom.family(
+  ([target, annotation, key]: readonly [
+    Entity.Unknown,
+    Annotation.Annotation<Record<string, any>>,
+    string,
+  ]): Atom.Atom<any> => {
+    const read = (): unknown =>
+      getAnnotation(target, annotation).pipe(
+        Option.map((value) => snapshotForComparison(value[key])),
+        Option.getOrUndefined,
+      );
+
+    return Atom.make<unknown>((get) => {
+      let previous = read();
+
+      const unsubscribe = subscribe(target, () => {
+        const next = read();
+        if (next !== previous) {
+          previous = next;
+          get.setSelf(next);
+        }
+      });
+      get.addFinalizer(() => unsubscribe());
+
+      return previous;
+    }).pipe(Atom.keepAlive);
+  },
+);
+
+/** Equal when both empty, or both present with the same (snapshotted) value. */
+const sameOption = <T>(a: Option.Option<T>, b: Option.Option<T>): boolean =>
+  Option.isNone(a) || Option.isNone(b) ? Option.isNone(a) && Option.isNone(b) : a.value === b.value;
+
+/**
+ * Reactive atom for an annotation value on an entity instance. Emits a shallow snapshot (a fresh
+ * reference for objects/arrays) so dependent atoms recompute on change. Mirrors {@link makeProperty}.
+ */
+export const makeAtom = <T>(
+  target: Entity.Unknown,
+  annotation: Annotation.Annotation<T>,
+): Atom.Atom<Option.Option<T>> => {
+  assertArgument(isEntity(target), 'target', 'Must be a reactive ECHO entity');
+  return annotationFamily(target)(annotation);
+};
+
+/**
+ * Reactive atom for a single key of a record-valued annotation on an entity instance.
+ */
+export const makeProperty = <V>(
+  target: Entity.Unknown,
+  annotation: Annotation.Annotation<Record<string, V>>,
+  key: string,
+): Atom.Atom<V | undefined> => {
+  assertArgument(isEntity(target), 'target', 'Must be a reactive ECHO entity');
+  // The flattened family key is a single concrete tuple type, so the generic `V` is erased at the
+  // family boundary and recovered here; no typed alternative exists for a per-call-generic family.
+  return annotationPropertyFamily(
+    Data.tuple(target, annotation as Annotation.Annotation<Record<string, any>>, key),
+  ) as Atom.Atom<V | undefined>;
+};

package/src/internal/Annotation/entity-dictionary.ts

@@ -3,72 +3,75 @@
 //
 
 import * as Option from 'effect/Option';
-
-import { deepMapValues } from '@dxos/util';
+import * as Schema from 'effect/Schema';
 
 import type * as Annotation from '../../Annotation';
 import type * as Entity from '../../Entity';
 import { getMetaChecked } from '../common/api/meta';
-import { type Mutable } from '../common/proxy/reactive';
-import { getDatabase } from '../Entity/api';
+import { type Mutable, change } from '../common/proxy/reactive';
 import { isEntity, isSnapshot } from '../Entity/guard';
-import { Ref, getRefSavedTarget } from '../Ref';
-import { getDictionary, setDictionary } from './dictionary';
+import { getDictionary } from './dictionary';
 
 /**
  * Get the value of an annotation from an entity instance or snapshot.
+ *
+ * The value is read-only (schema types are readonly by default). To mutate it, use {@link update}
+ * (which reads it as mutable inside a change transaction); the reactive proxy rejects mutation of the
+ * live value outside an `Obj.update`. Snapshots return a decoded detached copy.
  */
 export const get = <T>(
   target: Entity.Unknown | Entity.Snapshot,
   annotation: Annotation.Annotation<T>,
 ): Option.Option<T> => {
-  if (isEntity(target) || isSnapshot(target)) {
-    const meta = getMetaChecked(target);
-    return getDictionary(meta.annotations, annotation);
-  } else {
-    throw new TypeError('Target is not an annotation target.');
+  if (isSnapshot(target)) {
+    return getDictionary(getMetaChecked(target).annotations, annotation);
+  }
+  if (isEntity(target)) {
+    const annotations = getMetaChecked(target).annotations;
+    // The dictionary slot is typed `unknown`; at runtime it holds the annotation's live value
+    // (the proxy codecs nested refs in both directions), so the read coerces to the declared type.
+    return annotation.key in annotations ? Option.some(annotations[annotation.key] as T) : Option.none();
   }
+  throw new TypeError('Target is not an annotation target.');
 };
 
 /**
  * Set the value of an annotation on an entity instance.
  * Must be called with a mutable entity — i.e. inside an `Obj.update` callback.
+ *
+ * The value is assigned directly to the reactive meta dictionary; the proxy encodes nested Refs and
+ * links their unsaved targets on write (matching ordinary property assignment), so no manual
+ * encode/persist step is needed.
  */
 export const set = <T>(target: Mutable<Entity.Unknown>, annotation: Annotation.Annotation<T>, value: T): void => {
   if (isEntity(target)) {
-    const meta = getMetaChecked(target);
-    // Persist any unsaved Ref targets in the value into the entity's database so
-    // the encoded DXN resolves on read. This mirrors normal property assignment,
-    // where the reactive proxy links unsaved ref targets via `createRef` →
-    // `database.add`. `setDictionary` pre-encodes the value (`Schema.encodeSync`),
-    // so the live Ref never reaches the proxy's link handling and would otherwise
-    // be stored as a dangling reference.
-    persistRefTargets(target, value);
-    setDictionary(meta.annotations, annotation, value);
+    // The dictionary slot is untyped, so the proxy can't validate against the annotation schema;
+    // validate here (without encoding — the proxy encodes nested refs and links targets on assignment).
+    Schema.validateSync(annotation.schema)(value);
+    getMetaChecked(target).annotations[annotation.key] = value;
   } else {
     throw new TypeError('Target is not an annotation target.');
   }
 };
 
 /**
- * Add any unsaved Ref targets found in `value` to the host entity's database, matching the
- * auto-persistence applied to refs assigned to ordinary entity properties. Refs whose target
- * already lives in a database (the host's or a foreign one) are left untouched.
+ * Mutate an existing annotation value in place via a callback, wrapping the mutation in a change
+ * transaction (like `Obj.update`). Use when only an annotation needs to change. No-op when absent.
  */
-const persistRefTargets = (host: Entity.Unknown, value: unknown): void => {
-  const database = getDatabase(host);
-  if (database == null) {
-    return;
-  }
-
-  deepMapValues(value, (current, recurse) => {
-    if (Ref.isRef(current)) {
-      const refTarget = getRefSavedTarget(current);
-      if (refTarget != null && isEntity(refTarget) && getDatabase(refTarget) == null) {
-        database.add(refTarget);
-      }
-      return current;
+export const update = <T>(
+  target: Entity.Unknown,
+  annotation: Annotation.Annotation<T>,
+  mutator: (value: Mutable<T>) => void,
+): void => {
+  change(target, (mutable) => {
+    const current = get(mutable, annotation);
+    if (Option.isSome(current)) {
+      // `get` returns the value read-only; inside this change transaction the live value is mutable.
+      const value = current.value as Mutable<T>;
+      mutator(value);
+      // Validate against the annotation's own schema — the dictionary slot is untyped, so the proxy
+      // can't. Schema validation checks ref structure only (not targets), so it is cycle-safe.
+      Schema.validateSync(annotation.schema)(value);
     }
-    return recurse(current);
   });
 };

package/src/internal/Entity/api.ts

@@ -3,7 +3,7 @@
 //
 
 import { invariant } from '@dxos/invariant';
-import { DXN, EID, URI, type SpaceId } from '@dxos/keys';
+import { DXN, EID, type SpaceId, URI } from '@dxos/keys';
 import { assumeType } from '@dxos/util';
 
 import type { AnyEntity } from '../common/types';

package/src/internal/Entity/guard.ts

@@ -9,7 +9,8 @@ import { KindId, SnapshotKindId } from '../common/types';
  * Returns true if the value is an ECHO entity instance (object or relation).
  */
 export const isEntity = (value: unknown): value is Entity.Unknown => {
-  if (typeof value !== 'object' || value === null) {
+  // (some) type entities are functions since they are class declarations.
+  if (value == null || (typeof value !== 'object' && typeof value !== 'function')) {
     return false;
   }
   return (value as any)[KindId] !== undefined;

package/src/internal/Entity/model.ts

@@ -11,13 +11,13 @@ import { assumeType } from '@dxos/util';
 
 import type * as Database from '../../Database';
 import {
-  type ATTR_PARENT,
-  type ATTR_TYPE,
   ATTR_DELETED,
+  type ATTR_PARENT,
   ATTR_RELATION_SOURCE,
   ATTR_RELATION_TARGET,
   ATTR_SELF_URI,
   ATTR_SELF_URI_LEGACY,
+  type ATTR_TYPE,
   EntityKind,
   KindId,
   ObjectDatabaseId,

package/src/internal/Entity/object.ts

@@ -6,8 +6,9 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
 import { invariant } from '@dxos/invariant';
-import { DXN } from '@dxos/keys';
+import { DXN, type EntityId } from '@dxos/keys';
 
+import type * as Type from '../../Type';
 import { type TypeAnnotation, TypeAnnotationId } from '../Annotation/annotations';
 import { makeTypeJsonSchemaAnnotation } from '../Annotation/util';
 import { EntityKind } from '../common/types';
@@ -71,3 +72,15 @@ export const EchoObjectSchema: {
     );
   };
 };
+
+export const makeObjectType = <Self, _Schema extends Schema.Schema.Any>(
+  dxn: DXN.DXN,
+  schema: _Schema,
+  options?: { id?: EntityId },
+): Type.ObjClass<Self, Schema.Schema.Type<_Schema>, {}> => {
+  const type = EchoObjectSchema(dxn, options)(schema);
+  const constructor = function ObjectType() {};
+  Object.setPrototypeOf(constructor, type);
+  // Boundary cast: constructor/prototype wiring cannot be expressed in TypeScript's type system.
+  return constructor as unknown as Type.ObjClass<Self, Schema.Schema.Type<_Schema>, {}>;
+};

package/src/internal/Entity/relation.ts

@@ -186,3 +186,22 @@ export const getDXNForRelationSchemaRef = (schema: Schema.Schema.Any): DXN.DXN =
 
   return DXN.make(typename);
 };
+
+export const makeRelationType = (options: {
+  dxn: DXN.DXN;
+  source: RelationEndpoint;
+  target: RelationEndpoint;
+  schema: Schema.Schema.Any;
+  id?: EntityId;
+}): Type.RelationClass<unknown, unknown, unknown, unknown, {}> => {
+  const type = EchoRelationSchema({
+    dxn: options.dxn,
+    source: options.source,
+    target: options.target,
+    id: options.id,
+  })(options.schema);
+  const constructor = function RelationType() {};
+  Object.setPrototypeOf(constructor, type);
+  // Boundary cast: constructor/prototype wiring cannot be expressed in TypeScript's type system.
+  return constructor as unknown as Type.RelationClass<unknown, unknown, unknown, unknown, {}>;
+};

package/src/internal/Entity/type-uri.ts

@@ -23,7 +23,9 @@ export const getTypeURIFromSpecifier = (input: Schema.Schema.All | AnyEntity | U
   if (Schema.isSchema(input)) {
     return getSchemaURI(input) ?? raise(new TypeError('Schema has no URI'));
   }
-  if (typeof input === 'object' && input !== null && KindId in input) {
+  // Type entities are normally proxy objects, but class-declared types from
+  // `Type.makeObject` are functions whose prototype chain reaches the entity, so accept functions too.
+  if (input !== null && (typeof input === 'object' || typeof input === 'function') && KindId in input) {
     // `Type.Type` entity. Both in-memory and persisted forms expose the schema
     // they declare via `StaticTypeSchemaSlot`, whose URI is exactly what
     // `Obj.make` stamps on `system.type` — a static declaration carries

package/src/internal/Filter/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './match';