@dxos/echo 0.8.4-main.ef1bc66f44 → 0.8.4-main.f466a3d56e

package/src/View.ts

@@ -0,0 +1,107 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { QueryAST } from '@dxos/echo-protocol';
+import { JsonPath } from '@dxos/effect';
+import { PublicKey } from '@dxos/keys';
+
+import * as Annotation from './Annotation';
+import * as Filter from './Filter';
+import * as internal from './internal';
+import * as Obj from './Obj';
+import * as Query from './Query';
+import * as Type from './Type';
+
+/**
+ * Stored field metadata (e.g., for UX).
+ */
+export const FieldSchema = Schema.Struct({
+  id: Schema.String,
+  path: JsonPath,
+  visible: Schema.optional(Schema.Boolean),
+
+  // TODO(wittjosiah): Presentation-specific?
+  referencePath: Schema.optional(JsonPath),
+});
+
+export type FieldType = Schema.Schema.Type<typeof FieldSchema>;
+
+export const KeyValueProps = Schema.Record({ key: Schema.String, value: Schema.Any });
+
+export const createFieldId = () => PublicKey.random().truncate();
+
+export const Projection = Schema.Struct({
+  /**
+   * Optional schema override used to customize the underlying schema.
+   */
+  schema: internal.JsonSchemaType.pipe(Schema.optional),
+
+  /**
+   * UX metadata associated with displayed fields (in table, form, etc.)
+   */
+  // TODO(wittjosiah): Should this just be an array of JsonPath?
+  fields: Schema.Array(FieldSchema),
+
+  /**
+   * The id for the field used to pivot the view.
+   * E.g., the field to use for kanban columns or the field to use for map coordinates.
+   */
+  pivotFieldId: Schema.String.pipe(Schema.optional),
+});
+
+export type Projection = Schema.Schema.Type<typeof Projection>;
+
+/**
+ * Views are generated or user-defined projections of a schema's properties.
+ * They are used to configure the visual representation of the data.
+ */
+const ViewSchema = Schema.Struct({
+  /**
+   * Query used to retrieve data.
+   * Can be a user-provided query grammar string or a query AST.
+   */
+  query: Schema.Struct({
+    raw: Schema.optional(Schema.String),
+    ast: QueryAST.Query,
+  }),
+
+  /**
+   * Projection of the data returned from the query.
+   */
+  projection: Projection,
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.view',
+    version: '0.1.0',
+  }),
+  internal.SystemTypeAnnotation.set(true),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--funnel--regular',
+    hue: 'green',
+  }),
+);
+
+export interface View extends Schema.Schema.Type<typeof ViewSchema> {}
+
+/**
+ * View instance type.
+ */
+// NOTE: This interface is explicitly defined rather than derived from the schema to avoid
+//   TypeScript "cannot be named" portability errors. The schema contains QueryAST.Query which
+//   references internal @dxos/echo-protocol module paths. Without this explicit interface,
+//   any schema using Ref.Ref(View) would inherit the non-portable type and fail to compile.
+// TODO(wittjosiah): Find a better solution that doesn't require manually keeping the interface in sync.
+export const View: Type.Obj<View> = ViewSchema as any;
+
+export const make = (props: Partial<Obj.MakeProps<typeof View>>): View => {
+  return Obj.make(View, {
+    query: { ast: Query.select(Filter.nothing()).ast },
+    projection: { fields: [] },
+    ...props,
+  });
+};

package/src/exemplars.test.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Obj from './Obj';
+import { TestSchema } from './testing';
+import type * as Type from './Type';
+
+describe('Exemplars', () => {
+  test('factory', ({ expect }) => {
+    const factory = <S extends Type.AnyObj>(schema: S) => {
+      return (props: Obj.MakeProps<S>) => Obj.make(schema, props);
+    };
+
+    const makePerson = factory(TestSchema.Person);
+    const person = makePerson({ name: 'John Doe' });
+    expect(person.name).toBe('John Doe');
+  });
+});

package/src/index.ts

@@ -9,12 +9,16 @@ export { DXN } 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';
 export * as Format from './Format';
 export * as Hypergraph from './Hypergraph';
+export * as Json from './Json';
 export * as JsonSchema from './JsonSchema';
 export * as Key from './Key';
+export * as Migration from './Migration';
 export * as Obj from './Obj';
 export * as Order from './Order';
 export * as Query from './Query';
@@ -24,3 +28,7 @@ export * as Relation from './Relation';
 export * as SchemaRegistry from './SchemaRegistry';
 export * as Tag from './Tag';
 export * as Type from './Type';
+export * as Collection from './Collection';
+export * as View from './View';
+export * as Dataset from './Dataset';
+export * as Extension from './Extension';

package/src/internal/{annotations → Annotation}/annotations.test.ts

@@ -5,8 +5,7 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { EchoObjectSchema } from '../entities';
-
+import { EchoObjectSchema } from '../Entity';
 import { LabelAnnotation, TypenameSchema, VersionSchema, getLabelWithSchema } from './annotations';
 
 // TODO(dmaretskyi): Use one of the testing schemas.
@@ -20,7 +19,7 @@ type TestObject = Schema.Schema.Type<typeof TestObject>;
 
 const TestEchoSchema = TestObject.pipe(
   EchoObjectSchema({
-    typename: 'dxos.org/type/Test',
+    typename: 'org.dxos.type.test',
     version: '0.1.0',
   }),
 );
@@ -30,10 +29,10 @@ type TestEchoSchema = Schema.Schema.Type<typeof TestEchoSchema>;
 describe('annotations', () => {
   describe('Typename', () => {
     test('should validate typename', ({ expect }) => {
-      // Valid.
-      expect(TypenameSchema.make('dxos.org/type/foo')).to.exist;
-      expect(TypenameSchema.make('dxos.org/type/foo-bar')).to.exist;
-      expect(TypenameSchema.make('dxos.org/type/foo_bar')).to.exist;
+      // Valid (reverse-DNS format).
+      expect(TypenameSchema.make('org.dxos.type.foo')).to.exist;
+      expect(TypenameSchema.make('org.dxos.type.fooBar')).to.exist;
+      expect(TypenameSchema.make('org.dxos.type.foobar')).to.exist;
 
       // Invalid.
       expect(() => TypenameSchema.make('dxn:dxos.org')).to.throw();
@@ -82,6 +81,56 @@ describe('annotations', () => {
       expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
     });
 
+    test('should skip empty string and fallback to next path', ({ expect }) => {
+      const obj: TestObject = {
+        name: '',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Fallback Name');
+    });
+
+    test('should skip whitespace-only string and fallback to next path', ({ expect }) => {
+      const obj: TestObject = {
+        name: '   ',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Fallback Name');
+    });
+
+    test('should return undefined if all paths are empty strings', ({ expect }) => {
+      const obj: TestObject = {
+        name: '',
+        fallbackName: '',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
+    });
+
+    test('should return undefined if all paths are whitespace-only', ({ expect }) => {
+      const obj: TestObject = {
+        name: '  ',
+        fallbackName: '\t\n',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
+    });
+
+    test('should preserve original string with leading/trailing whitespace when valid', ({ expect }) => {
+      const obj: TestObject = {
+        name: '  Valid Name  ',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('  Valid Name  ');
+    });
+
     test('should return label from echo object', ({ expect }) => {
       const obj: TestEchoSchema = {
         id: 'test',

package/src/internal/{annotations → Annotation}/annotations.ts

@@ -13,8 +13,8 @@ import { assertArgument, invariant } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
 import { type Primitive } from '@dxos/util';
 
-import { type AnyProperties, EntityKind, TypeId, getSchema } from '../types';
-
+import { type Mutable } from '../common/proxy';
+import { type AnyProperties, EntityKind, TypeId, getSchema } from '../common/types';
 import { type AnnotationHelper, createAnnotationHelper } from './util';
 
 /**
@@ -87,16 +87,17 @@ export const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN
 
 /**
  * Fully qualified globally unique typename.
- * Example: `dxos.org/type/Message`
- */
-// TODO(burdon): Reconcile with short DXN format.
-// TODO(burdon): Change "/type" => "/schema" throughout.
-export const TypenameSchema = Schema.String.pipe(Schema.pattern(/^[a-zA-Z]\w+\.[a-zA-Z]\w{1,}\/[\w/_-]+$/)).annotations(
-  {
-    description: 'Fully qualified globally unique typename',
-    example: 'dxos.org/type/Message',
-  },
-);
+ * Example: `org.dxos.type.message`
+ */
+// TODO(wittjosiah): Factor out to DXN spec.
+export const TypenameSchema = Schema.String.pipe(
+  Schema.pattern(
+    /^[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(\.[a-zA-Z]([a-zA-Z0-9]{0,62})?)$/,
+  ),
+).annotations({
+  description: 'Fully qualified globally unique typename in reverse-DNS form.',
+  example: 'org.dxos.type.message',
+});
 
 /**
  * Semantic version format: `major.minor.patch`
@@ -175,7 +176,7 @@ export const getSchemaVersion = (schema: Schema.Schema.All): string | undefined
 /**
  * Gets the typename of the object without the version.
  * Returns only the name portion, not the DXN.
- * @example "example.org/type/Contact"
+ * @example "org.example.type.contact"
  *
  * @internal (use Obj.getTypename)
  */
@@ -207,7 +208,7 @@ export const setTypename = (obj: any, typename: DXN): void => {
 /**
  * @returns Object type as {@link DXN}.
  * @returns undefined if the object doesn't have a type.
- * @example `dxn:example.com/type/Person:1.0.0`
+ * @example `dxn:com.example.type.person:1.0.0`
  *
  * @internal (use Obj.getTypeDXN)
  */
@@ -337,6 +338,7 @@ export const LabelAnnotation = createAnnotationHelper<string[]>(LabelAnnotationI
 /**
  * Returns the label for a given object based on {@link LabelAnnotationId}.
  * Lower-level version that requires explicit schema parameter.
+ * Skips empty strings and whitespace-only strings, continuing to the next field.
  */
 // TODO(burdon): Convert to JsonPath?
 export const getLabelWithSchema = <S extends Schema.Schema.Any>(
@@ -352,7 +354,13 @@ export const getLabelWithSchema = <S extends Schema.Schema.Any>(
     );
     const value = getField(object, accessor as JsonPath);
     switch (typeof value) {
-      case 'string':
+      case 'string': {
+        const trimmed = value.trim();
+        if (trimmed.length > 0) {
+          return value;
+        }
+        continue;
+      }
       case 'number':
       case 'boolean':
       case 'bigint':
@@ -435,7 +443,6 @@ export const setDescriptionWithSchema = <S extends Schema.Schema.Any>(
  * Identifies if a property should be included in a form or not.
  * By default, all properties are included in forms, so this is opt-out.
  */
-// TODO(burdon): UI concern.
 export const FormInputAnnotationId = Symbol.for('@dxos/schema/annotation/FormInput');
 export const FormInputAnnotation = createAnnotationHelper<boolean>(FormInputAnnotationId);
 
@@ -467,14 +474,14 @@ interface MakeAnnoationsProps<T> {
 // TODO(wittjosiah): Comment.
 export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): AnnotationHelper<T> => {
   assertArgument(
-    /[a-zA-Z0-9]+\.[a-zA-Z.]+\/[a-zA-Z/]+/.test(props.id),
+    /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*){2,}$/.test(props.id),
     'id',
-    'Annotation id must be in the FQN format (dxos.org/annotation/Example).',
+    'Annotation id must be in the FQN format (org.dxos.annotation.example).',
   );
 
   const getFromAst = (ast: SchemaAST.AST) =>
     SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(ast).pipe(
-      Option.map((meta) => meta[props.id] as unknown),
+      Option.flatMap((meta) => Option.fromNullable(meta[props.id])),
       Option.map(Schema.decodeUnknownSync(props.schema)),
     );
 
@@ -485,3 +492,99 @@ export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): Annotation
       PropertyMeta(props.id, Schema.encodeSync(props.schema)(value)) as <S extends Schema.Schema.Any>(schema: S) => S,
   };
 };
+
+const IconAnnotationSchema = Schema.Struct({
+  /**
+   * Phosphor icon name (e.g., 'ph--user--regular', 'ph--cube--regular', 'ph--link--regular ', etc.)
+   */
+  icon: Schema.String.pipe(Schema.pattern(/^ph--[a-z-]+--[a-z]+$/)),
+
+  /**
+   * Color name.
+   *
+   * List of colors:
+   *  - 'red'
+   *  - 'orange'
+   *  - 'amber'
+   *  - 'yellow'
+   *  - 'lime'
+   *  - 'green'
+   *  - 'emerald'
+   *  - 'teal'
+   *  - 'cyan'
+   *  - 'violet'
+   *  - 'purple'
+   *  - 'fuchsia'
+   *  - 'pink'
+   *  - 'rose'
+   */
+
+  hue: Schema.optional(Schema.String),
+});
+
+export interface IconAnnotation extends Schema.Schema.Type<typeof IconAnnotationSchema> {}
+
+/**
+ * Icon to render in the UI.
+ */
+export const IconAnnotation = makeUserAnnotation<IconAnnotation>({
+  id: 'org.dxos.annotation.icon',
+  schema: IconAnnotationSchema,
+});
+
+/**
+ * Indicates that this entity's icon should be resolved from a property whose value is a `Ref`
+ * to another entity. Consumers (e.g. graph node builders) resolve the ref target and use that
+ * target's schema `IconAnnotation` in place of the static one declared on this schema.
+ *
+ * Useful for wrapper schemas that delegate their visual identity to a referenced sub-entity
+ * (e.g. a generic `Game` whose icon should come from its `variant` ref's typed state).
+ */
+export const IconFromRefAnnotation = makeUserAnnotation<string>({
+  id: 'org.dxos.annotation.icon.from-ref',
+  schema: Schema.String,
+});
+
+/**
+ * Get the label of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getLabel = (entity: AnyProperties): string | undefined => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    return getLabelWithSchema(schema, entity);
+  }
+};
+
+/**
+ * Set the label of an entity.
+ * Must be called within an Obj.update or Relation.update callback.
+ */
+export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    setLabelWithSchema(schema, entity, label);
+  }
+};
+
+/**
+ * Get the description of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getDescription = (entity: AnyProperties): string | undefined => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    return getDescriptionWithSchema(schema, entity);
+  }
+};
+
+/**
+ * Set the description of an entity.
+ * Must be called within an Obj.update or Relation.update callback.
+ */
+export const setDescription = (entity: Mutable<AnyProperties>, description: string) => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    setDescriptionWithSchema(schema, entity, description);
+  }
+};

package/src/internal/{annotations → Annotation}/index.ts

@@ -3,4 +3,5 @@
 //
 
 export * from './annotations';
+export * from './sorting';
 export * from './util';

package/src/internal/{api → Annotation}/sorting.ts

@@ -2,10 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { getTypename } from '../annotations';
-import type { AnyEntity } from '../types';
-
-import { getLabel } from './annotations';
+import type { AnyEntity } from '../common/types';
+import { getLabel, getTypename } from './annotations';
 
 /**
  * String comparison helper for sorting.

package/src/internal/{annotations → Annotation}/util.ts

@@ -9,7 +9,7 @@ import * as SchemaAST from 'effect/SchemaAST';
 import { assertArgument } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
 
-import { EntityKind } from '../types';
+import { EntityKind } from '../common/types';
 
 export interface AnnotationHelper<T> {
   /**

package/src/internal/{api/entity.ts → Entity/api.ts}

@@ -6,8 +6,9 @@ import { invariant } from '@dxos/invariant';
 import { type DXN } from '@dxos/keys';
 import { assumeType } from '@dxos/util';
 
-import { type InternalObjectProps, ObjectDatabaseId, getObjectDXN } from '../entities';
-import type { AnyEntity } from '../types';
+import type { AnyEntity } from '../common/types';
+import { type InternalObjectProps, ObjectDatabaseId } from './model';
+import { getObjectDXN } from './util';
 
 /**
  * Get the DXN of an entity.

package/src/internal/{entities → Entity}/entity.ts

@@ -8,8 +8,8 @@ import type * as Types from 'effect/Types';
 
 import { type ToMutable } from '@dxos/util';
 
-import { type TypeMeta } from '../annotations';
-import { type AnyEntity, type EntityKind, SchemaKindId } from '../types';
+import { type TypeMeta } from '../Annotation';
+import { type AnyEntity, type EntityKind, SchemaKindId } from '../common/types';
 
 // TODO(burdon): Define Schema type for `typename` and use consistently for all DXN-like properties.
 
@@ -22,7 +22,9 @@ export interface EchoTypeSchema<
   ExtraFields = {},
   K extends EntityKind = EntityKind,
   Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
-> extends TypeMeta,
+>
+  extends
+    TypeMeta,
     Schema.AnnotableClass<
       EchoTypeSchema<Self, ExtraFields, K, Fields>,
       EchoTypeSchemaProps<Schema.Schema.Type<Self>, ExtraFields>,
@@ -31,7 +33,7 @@ export interface EchoTypeSchema<
     > {
   /**
    * Schema kind key that marks this as an ECHO schema and indicates its kind.
-   * Makes EchoTypeSchema satisfy the Type.Obj.Any or Type.Relation.Any type.
+   * Makes EchoTypeSchema satisfy the Type.AnyObj or Type.Relation.Any type.
    */
   readonly [SchemaKindId]: K;
 

package/src/internal/{entities → Entity}/index.ts

@@ -2,8 +2,10 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './api';
 export * from './entity';
 export * from './model'; // TODO(burdon): Rename.
 export * from './object';
 export * from './relation';
 export * from './util';
+export * from './version';

package/src/internal/{entities → Entity}/model.ts

@@ -14,58 +14,29 @@ import {
   type ATTR_META,
   type ATTR_PARENT,
   type ATTR_TYPE,
+  ATTR_DELETED,
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  ATTR_SELF_DXN,
   EntityKind,
   KindId,
   type MetaId,
+  ObjectDatabaseId,
+  ObjectDeletedId,
   type ObjectMeta,
+  ObjectVersionId,
   type ParentId,
-  type SchemaId,
-  TypeId,
-  type Version,
-} from '../types';
-
-import {
-  type ATTR_RELATION_SOURCE,
-  type ATTR_RELATION_TARGET,
   RelationSourceDXNId,
   RelationSourceId,
   RelationTargetDXNId,
   RelationTargetId,
-} from './relation';
-
-//
-// Defines the internal model of the echo object.
-//
-
-/**
- * Property name for self DXN when object is serialized to JSON.
- */
-export const ATTR_SELF_DXN = '@dxn';
-
-/**
- * DXN to the object itself.
- */
-export const SelfDXNId = Symbol.for('@dxos/echo/DXN');
-
-/**
- * Property name for deleted when object is serialized to JSON.
- */
-export const ATTR_DELETED = '@deleted';
-
-/**
- * Deletion marker.
- */
-export const ObjectDeletedId = Symbol.for('@dxos/echo/Deleted');
-
-/**
- * Object version accessor symbol.
- */
-export const ObjectVersionId: unique symbol = Symbol.for('@dxos/echo/Version');
+  type SchemaId,
+  SelfDXNId,
+  TypeId,
+  type Version,
+} from '../common/types';
 
-/**
- * Object database accessor symbol.
- */
-export const ObjectDatabaseId = Symbol.for('@dxos/echo/Database');
+export { ATTR_DELETED, ATTR_SELF_DXN, ObjectDatabaseId, ObjectDeletedId, ObjectVersionId, SelfDXNId };
 
 /**
  * Internal runtime representation of an object.
@@ -95,6 +66,8 @@ export interface InternalObjectProps {
 export interface ObjectMetaJSON {
   keys: ForeignKey[];
   tags?: string[];
+  key?: string;
+  version?: string;
 }
 
 /**

package/src/internal/{entities → Entity}/object.ts

@@ -7,9 +7,8 @@ import * as SchemaAST from 'effect/SchemaAST';
 
 import { invariant } from '@dxos/invariant';
 
-import { type TypeAnnotation, TypeAnnotationId, type TypeMeta, makeTypeJsonSchemaAnnotation } from '../annotations';
-import { EntityKind } from '../types';
-
+import { type TypeAnnotation, TypeAnnotationId, type TypeMeta, makeTypeJsonSchemaAnnotation } from '../Annotation';
+import { EntityKind } from '../common/types';
 import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
 
 /**