@dxos/echo 0.8.4-main.40e3dcdf1b → 0.8.4-main.43cb759274

package/src/Tag.md

@@ -0,0 +1,88 @@
+# Tag
+
+`Tag` is the ECHO type for labelling other objects. The schema is tiny — `{ label, hue? }` — but the _attachment pattern_ varies by use case. This doc covers what's available and which pattern to use.
+
+## What `Tag` is
+
+Definition: [`Tag.ts`](./src/Tag.ts) — `Schema.Struct({ label: String, hue?: String })` with DXN `org.dxos.type.tag@0.1.0`. Carries the `SystemTypeAnnotation` so it's treated as a built-in type by the ECHO runtime.
+
+Helpers on the same module:
+
+- `Tag.make(props)` — constructor.
+- `Tag.Map` — `Record<string, Tag>` alias used by call-site indexes.
+- `Tag.createTagList(tags)` — `Map → Tag[]`, sorted by label.
+- `Tag.findTagByLabel(tags, name)` — case-insensitive label lookup.
+- `Tag.sortTags(a, b)` — `localeCompare` on label.
+
+### Colour (`hue`)
+
+`hue` is a Tailwind colour name (`red`, `orange`, `amber`, …). The canonical list lives in [`IconAnnotation`'s schema](./src/internal/Annotation/annotations.ts) (search `IconAnnotationSchema`). Surfaces that render chips read `hue` to colour the chip; rendering hashes the tag id as a fallback when `hue` is absent.
+
+## Attachment patterns
+
+Three ways an object can carry tags. Pick the one that matches your storage shape:
+
+### 1. `Obj.getMeta(obj).tags` — DXN refs on the object's metadata
+
+The canonical user-tagging path. Each tag lives as a standalone `Tag` object in the space; the _target_ object holds an array of DXN refs to those tags inside its metadata bag. The form layer's [`ObjectProperties`](../../ui/react-ui-form/src/components/ObjectProperties) writes these via the `pinnedTags` control.
+
+Use when: the target object is mutable. Tags can be added/removed cheaply by editing the metadata.
+
+```ts
+const tag = Obj.make(Tag.Tag, { label: 'important', hue: 'amber' });
+db.add(tag);
+Obj.update(target, (t) => {
+  Obj.getMeta(t).tags = [tag.dxn];
+});
+```
+
+### 2. Container-owned tag map — inverse index on the parent
+
+For containers that hold immutable-in-feed objects (mailboxes hold messages, magazines hold posts), the children can't carry tag refs because they're immutable. Instead, the container holds an inverted `tagId → Ref<child>[]` map. Tag _definitions_ live in the same map alongside the assignments.
+
+Use when: the children are append-only feed records, OR you need a fast "all objects tagged X" query without scanning each child.
+
+Reference shape (from plugin-inbox's [`Mailbox.tags`](../../plugins/plugin-inbox/src/types/Mailbox.ts)):
+
+```ts
+Mailbox.tags: Record<TagId, {
+  label: string,
+  hue?: string,
+  source?: 'provider' | 'user',
+  messages: Ref<Message>[],
+}>
+```
+
+Tag-id strategy depends on origin:
+
+| source                              | tag id                            | rationale                                                                                |
+| ----------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
+| provider-synced (e.g. Gmail labels) | external id (Gmail's `Label_123`) | preserves re-sync idempotence — same external id → same map entry, no duplicates         |
+| user-applied                        | random `EntityId`                 | stable across renames; case-insensitive label dedupe via `findTagByLabel` at create time |
+
+Trade-offs considered and rejected:
+
+- Slug from label (`kebab-case(label)`) — natural dedupe but renaming a tag breaks references that point at the old key.
+- EntityId for everything — uniform but Gmail re-syncs would duplicate provider tags every run unless you also dedupe by label, which loses the external id.
+
+### 3. `HasSubject` relation (deprecated)
+
+The older pattern: a relation with `Source = Tag, Target = Object`. Lives at [`@dxos/types/HasSubject`](../../sdk/types/src/types/HasSubject.ts) and is marked `@deprecated`.
+
+Use when: never, for new code. Existing data is being migrated to one of the two patterns above. The shape is functionally identical to (1), but doing it via a separate relation creates a query overhead (walk all relations for the object) that (1) avoids by inlining the refs.
+
+## Hue conventions
+
+Always store the Tailwind colour name (e.g. `'amber'`), not a hex. Surfaces translate via `data-hue` on the chip, which the design system maps to the right shade. See [`getHashStyles`](../../ui/react-ui-components) for the fallback hash when `hue` is unset.
+
+## plugin-inbox: how the inbox uses Tag
+
+Single source of truth: [`Mailbox.tags`](../../plugins/plugin-inbox/src/types/Mailbox.ts). Pattern 2 (container map). Replaces both the older `Mailbox.labels` (Gmail provider dictionary) and the `HasSubject`-relation user-tagging path with one record.
+
+- Provider labels: `syncLabels` writes `mailbox.tags[gmailLabelId] = { label, source: 'provider', messages: [...] }`. Gmail's id is the map key so re-sync is idempotent.
+- Per-message provider assignments: at sync time, after appending a message to the feed, the sync loop pushes `Ref.make(message)` onto each `mailbox.tags[labelId].messages` it was given.
+- User tags / extractor tags: `Mailbox.applyTag(mailbox, { label, hue? }, message)` find-or-creates a `source: 'user'` entry and pushes a Ref. Idempotent.
+- UI: `Mailbox.buildMessageTagsIndex(mailbox)` inverts the map to `messageId → Tag[]` for `MessageStack` tile chips; `Mailbox.getTagsForMessage(mailbox, message)` for the single-message case in `MessageHeader`.
+- Extractor tagging: extractors that want to tag the source message return `{ tags: [{ label, hue? }] }` in their `ExtractResult`; the `ExtractMessage` dispatcher applies them after persistence. See the trip extractor for an example (`tags: [{ label: 'trip', hue: 'sky' }]`).
+
+Adopting the same pattern in a new plugin: pick this shape when your plugin owns a mutable container with immutable feed-stored children, OR when you want a fast "tagged-with-X" inverted lookup. Copy `applyTag` / `removeTag` / `buildMessageTagsIndex` / `getTagsForMessage` (≈ 80 lines, no plugin-specific logic) and you have a working tag system on day one.

package/src/Tag.ts

@@ -6,6 +6,10 @@
 
 import * as Schema from 'effect/Schema';
 
+import type { ForeignKey } from '@dxos/echo-protocol';
+
+import type * as Database from './Database';
+import * as Filter from './Filter';
 import * as internal from './internal';
 import * as Obj from './Obj';
 import * as Type from './Type';
@@ -14,15 +18,13 @@ export const Tag = Schema.Struct({
   label: Schema.String,
   hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
 }).pipe(
-  Type.object({
-    typename: 'org.dxos.type.tag',
-    version: '0.1.0',
-  }),
   internal.LabelAnnotation.set(['label']),
-  internal.SystemTypeAnnotation.set(true),
+  internal.HiddenAnnotation.set(true),
+  // Shared DXN so `meta.tags` (the `Ref<Tag>` schema) and this type stay in sync.
+  Type.makeObject(internal.TagTypeDXN),
 );
 
-export type Tag = Schema.Schema.Type<typeof Tag>;
+export type Tag = Type.InstanceType<typeof Tag>;
 
 export const make = (props: Obj.MakeProps<typeof Tag>) => Obj.make(Tag, props);
 
@@ -39,3 +41,44 @@ export const findTagByLabel = (tags: Map | undefined, name: string): Tag | undef
   const entry = Object.entries(tags ?? {}).find(([_, tag]) => tag.label.toLowerCase() === name.toLowerCase());
   return entry ? { ...entry[1], id: entry[0] } : undefined;
 };
+
+/**
+ * Finds or creates a {@link Tag} object in the database.
+ *
+ * - With a foreign `key` (system/provider tags): matched by that key; the label is kept current on
+ *   re-sync. Use a stable key (e.g. `{ source: 'google.com/gmail/label', id }`) for tags whose
+ *   identity is external or well-known.
+ * - Without a key (user tags): matched by case-insensitive label among tags that carry **no**
+ *   foreign key, so it never collides with a keyed system/provider tag of the same label.
+ */
+export const findOrCreate = async (
+  db: Pick<Database.Database, 'query' | 'add'>,
+  options: { label: string; hue?: string; key?: ForeignKey },
+): Promise<Tag> => {
+  const { label, hue, key } = options;
+  const withHue = hue ? { hue } : {};
+  if (key) {
+    const [existing] = await db.query(Filter.foreignKeys(Tag, [key])).run();
+    if (existing) {
+      // Keep label (and hue, when provided) current on re-sync. `hue` is only touched when supplied,
+      // so a label-only re-sync (e.g. Gmail) doesn't wipe a user-set colour.
+      if (existing.label !== label || (hue !== undefined && existing.hue !== hue)) {
+        Obj.update(existing, (existing) => {
+          existing.label = label;
+          if (hue !== undefined) {
+            existing.hue = hue;
+          }
+        });
+      }
+      return existing;
+    }
+    return db.add(Obj.make(Tag, { [Obj.Meta]: { keys: [key] }, label, ...withHue }));
+  }
+
+  const lowered = label.toLowerCase();
+  const candidates = await db.query(Filter.type(Tag)).run();
+  const existing = candidates.find(
+    (tag) => tag.label.toLowerCase() === lowered && (Obj.getMeta(tag).keys ?? []).length === 0,
+  );
+  return existing ?? db.add(make({ label, ...withHue }));
+};

package/src/TagIndex.test.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { DXN } from '@dxos/keys';
+
+import * as Obj from './Obj';
+import * as TagIndex from './TagIndex';
+import * as Type from './Type';
+
+/** A minimal item standing in for an immutable feed object. */
+const Item = Schema.Struct({
+  text: Schema.String,
+}).pipe(Type.makeObject(DXN.make('org.dxos.test.TagIndexItem', '0.1.0')));
+
+/** A host object carrying a tag index alongside (a notional feed of) items. */
+const Host = Schema.Struct({
+  tags: TagIndex.field(),
+}).pipe(Type.makeObject(DXN.make('org.dxos.test.TagIndexHost', '0.1.0')));
+
+describe('TagIndex', () => {
+  test('sets, unsets, and inverts feed-object tags', () => {
+    const host = Obj.make(Host, {});
+    const tags = TagIndex.bind(host, 'tags');
+
+    const a = Obj.make(Item, { text: 'a' });
+    const b = Obj.make(Item, { text: 'b' });
+    const urgent = 'dxn:tag:urgent';
+    const later = 'dxn:tag:later';
+
+    tags.setTag(urgent, a.id);
+    tags.setTag(urgent, b.id);
+    tags.setTag(later, b.id);
+    // Idempotent.
+    tags.setTag(urgent, a.id);
+
+    // Filter the feed by tag: tag -> object ids.
+    expect([...tags.objects(urgent)]).toEqual([a.id, b.id]);
+    expect([...tags.objects(later)]).toEqual([b.id]);
+    expect([...tags.objects('dxn:tag:missing')]).toEqual([]);
+
+    // Inverse: object -> tag ids.
+    expect(tags.tags(b.id).sort()).toEqual([later, urgent]);
+    expect(tags.tags(a.id)).toEqual([urgent]);
+    expect(tags.tagIds().sort()).toEqual([later, urgent]);
+
+    // Unset prunes the membership; emptying a tag drops the key.
+    tags.unsetTag(urgent, a.id);
+    expect([...tags.objects(urgent)]).toEqual([b.id]);
+    tags.unsetTag(urgent, b.id);
+    expect([...tags.objects(urgent)]).toEqual([]);
+    expect(tags.tagIds()).toEqual([later]);
+  });
+});

package/src/TagIndex.ts

@@ -0,0 +1,110 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { FormInputAnnotation } from './internal';
+import * as Obj from './Obj';
+
+/**
+ * An inverse tag index: an in-document `Record<tagId, objectId[]>` mapping a tag id to the ids of
+ * the objects carrying that tag.
+ *
+ * Mutable database objects track their tags in `Obj.getMeta(obj).tags` (an array of tag ids).
+ * Immutable feed/queue objects cannot carry their own meta, so this index — managed alongside the
+ * feed on its host object — augments that same process for them. Tags are sparse, so keying by tag
+ * id (rather than object id) keeps the index small and makes "filter the feed by tag" a single
+ * lookup.
+ *
+ * The tag id is an existing {@link Tag} object's id/URI; labels are never duplicated here — they
+ * live on the {@link Tag} object and stay editable in one place.
+ */
+
+/** Read/write accessor over a host object's tag-index field, bound to a single field key. */
+export interface Accessor {
+  /** All tag ids present in the index. */
+  tagIds(): string[];
+  /** Object ids carrying the given tag; `[]` when the tag is absent (filter the feed by tag). */
+  objects(tagId: string): readonly string[];
+  /** Inverse lookup: the tag ids applied to the given object id. */
+  tags(objectId: string): string[];
+  /** Applies a tag to an object (creating the tag entry when absent); idempotent. */
+  setTag(tagId: string, objectId: string): void;
+  /** Removes a tag from an object, pruning the tag entry when it empties. */
+  unsetTag(tagId: string, objectId: string): void;
+}
+
+/**
+ * Schema fragment for a tag-index field. Splice into a host Struct. Optional record, hidden from
+ * forms. Keyed by tag id; the value is the array of object ids carrying that tag.
+ */
+export const field = () =>
+  Schema.Record({ key: Schema.String, value: Schema.Array(Obj.ID) }).pipe(
+    FormInputAnnotation.set(false),
+    Schema.optional,
+  );
+
+/** Binds an {@link Accessor} over `host[key]`; all mutations go through `Obj.update`. */
+export const bind = (host: Obj.Any, key: string): Accessor => {
+  type Record_ = Record<string, string[]>;
+
+  // The field is addressed by a runtime key, so the ECHO object is viewed as a keyed record — a
+  // deliberate type-system boundary (dynamic field access — the field name is a parameter).
+  const asView = (obj: Obj.Any) => obj as unknown as Record<string, Record_ | undefined>;
+  const read = (): Record_ => asView(host)[key] ?? {};
+
+  // Mutate the live typed record in place (do NOT reassign the whole tree); assigning a detached
+  // plain object tree bypasses ECHO's schema-aware conversion and stores arrays as numeric-keyed
+  // objects. Mutating the typed proxy (and assigning real arrays to its values) preserves arrays.
+  const write = (mutate: (record: Record_) => void): void => {
+    Obj.update(host, (host) => {
+      const view = asView(host);
+      if (view[key] === undefined) {
+        view[key] = {};
+      }
+      // Re-read after assignment: the assignment expression yields the plain RHS, not the
+      // ECHO-backed reactive record, so mutating that would not persist.
+      mutate(view[key]!);
+    });
+  };
+
+  // Existence check via `Object.keys` — ECHO's reactive record proxy auto-vivifies missing keys on
+  // direct access, so `record[tagId]` is not reliably `undefined` for absent tags.
+  const has = (record: Record_, tagId: string): boolean => Object.keys(record).includes(tagId);
+
+  return {
+    tagIds: () => Object.keys(read()),
+    objects: (tagId) => {
+      const record = read();
+      return has(record, tagId) ? record[tagId] : [];
+    },
+    tags: (objectId) => {
+      const record = read();
+      return Object.keys(record).filter((tagId) => record[tagId].includes(objectId));
+    },
+    setTag: (tagId, objectId) =>
+      write((record) => {
+        // Use `has` (not `record[tagId]`) for absence — the proxy auto-vivifies missing keys.
+        if (!has(record, tagId)) {
+          record[tagId] = [objectId];
+        } else if (!record[tagId].includes(objectId)) {
+          record[tagId] = [...record[tagId], objectId];
+        }
+      }),
+    unsetTag: (tagId, objectId) =>
+      write((record) => {
+        if (!has(record, tagId)) {
+          return;
+        }
+        const next = record[tagId].filter((existing) => existing !== objectId);
+        if (next.length === 0) {
+          delete record[tagId];
+        } else {
+          record[tagId] = next;
+        }
+      }),
+  };
+};

package/src/Tagging.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { EID, URI } from '@dxos/keys';
+
+import type * as Database from './Database';
+import * as Obj from './Obj';
+import * as Ref from './Ref';
+import type * as Tag from './Tag';
+import * as TagIndex from './TagIndex';
+
+/**
+ * Unified tag handling for objects whether their tags live on the object (mutable database objects)
+ * or alongside it (immutable feed/queue objects).
+ *
+ * - Mutable database objects track their tags in `Obj.getMeta(obj).tags` (an array of `Ref<Tag>`).
+ * - Immutable feed objects can't carry their own meta, so their tags live in a {@link TagIndex} on
+ *   a host object; pass that host via {@link Options.host}.
+ *
+ * Either way the tag id is an existing {@link Tag} object's id/URI, so the same tag applies across
+ * mutable and immutable objects and its label is resolved (and edited) in one place. This API works
+ * in terms of those URI tag ids; on the mutable path it converts to/from the stored `Ref<Tag>`.
+ */
+export interface Options {
+  /** Host object whose tag index holds tags for the (immutable) object. Omit for mutable objects. */
+  host?: Obj.Any;
+  /** Tag-index field name on the host (default `tags`). */
+  key?: string;
+}
+
+const DEFAULT_KEY = 'tags';
+
+/** Returns the tag ids (URIs) applied to an object. */
+export const get = (object: Obj.Any, options: Options = {}): string[] => {
+  const { host, key = DEFAULT_KEY } = options;
+  if (host) {
+    return TagIndex.bind(host, key).tags(object.id);
+  }
+  return Obj.getMeta(object).tags.map((tag) => tag.uri);
+};
+
+/** Applies a tag (by id/URI) to an object (idempotent). */
+export const set = (object: Obj.Any, tagId: string, options: Options = {}): void => {
+  const { host, key = DEFAULT_KEY } = options;
+  if (host) {
+    TagIndex.bind(host, key).setTag(tagId, object.id);
+    return;
+  }
+  // Stored tag refs are canonical EIDs (read-time upgrade normalizes legacy DXN ids); normalize the
+  // incoming id the same way so dedupe compares like-for-like.
+  const id = EID.tryParse(tagId) ?? tagId;
+  Obj.update(object, (object) => {
+    const meta = Obj.getMeta(object);
+    if (!meta.tags.some((tag) => tag.uri === id)) {
+      meta.tags.push(Ref.fromURI(URI.make(id)));
+    }
+  });
+};
+
+/** Removes a tag (by id/URI) from an object. No-op when not present. */
+export const unset = (object: Obj.Any, tagId: string, options: Options = {}): void => {
+  const { host, key = DEFAULT_KEY } = options;
+  if (host) {
+    TagIndex.bind(host, key).unsetTag(tagId, object.id);
+    return;
+  }
+  const id = EID.tryParse(tagId) ?? tagId;
+  Obj.update(object, (object) => {
+    const meta = Obj.getMeta(object);
+    for (let i = meta.tags.length - 1; i >= 0; i--) {
+      if (meta.tags[i].uri === id) {
+        meta.tags.splice(i, 1);
+      }
+    }
+  });
+};
+
+/** Resolves tag ids (URIs) to {@link Tag} object refs via the database. */
+export const resolve = (db: Pick<Database.Database, 'makeRef'>, tagIds: readonly string[]): Ref.Ref<Tag.Tag>[] =>
+  tagIds.map((id) => db.makeRef<Tag.Tag>(URI.make(id)));