@cosmicdrift/kumiko-bundled-features 0.97.1 → 0.100.0

package/src/tags/handlers/update-tag.write.ts

@@ -0,0 +1,31 @@
+import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_TAG_ACCESS } from "../constants";
+import { tagExecutor } from "../executor";
+import { type UpdateTagPayload, updateTagPayloadSchema } from "../schemas";
+
+// update-tag — edits a catalog tag (rename / recolor / re-scope). Optimistic-
+// locked: the client sends the `version` it read (mirrors tenant:update). Only
+// the fields present in the payload go into `changes`, and the executor merges
+// shallowly, so any omitted field is preserved (color/scope accept "" to clear).
+// A stale version returns version_conflict; the UI refetches and retries.
+export function createUpdateTagHandler(access: AccessRule = DEFAULT_TAG_ACCESS): WriteHandlerDef {
+  return {
+    name: "update-tag",
+    schema: updateTagPayloadSchema,
+    access,
+    handler: async (event, ctx) => {
+      const payload = event.payload as UpdateTagPayload; // @cast-boundary engine-payload
+      const changes: Record<string, unknown> = {};
+      if (payload.name !== undefined) changes["name"] = payload.name;
+      if (payload.color !== undefined) changes["color"] = payload.color;
+      if (payload.scope !== undefined) changes["scope"] = payload.scope;
+      return tagExecutor.update(
+        { id: payload.id, version: payload.version, changes },
+        event.user,
+        ctx.db,
+      );
+    },
+  };
+}
+
+export const updateTagHandler: WriteHandlerDef = createUpdateTagHandler();

package/src/tags/index.ts

@@ -2,7 +2,11 @@ export { tagAssignmentAggregateId } from "./aggregate-id";
 export {
   DEFAULT_TAG_ACCESS,
   DEFAULT_TAG_ROLES,
+  TAGS_COLUMN_RENDERER_NAME,
   TAGS_FEATURE_NAME,
+  TAGS_FILTER_EXTENSION_NAME,
+  TAGS_SCREEN_ID,
+  TAGS_SECTION_EXTENSION_NAME,
   TagsHandlers,
   TagsQueries,
 } from "./constants";
@@ -16,21 +20,27 @@ export {
   createCreateTagHandler,
   createTagHandler,
 } from "./handlers/create-tag.write";
+export {
+  createDeleteTagHandler,
+  deleteTagHandler,
+} from "./handlers/delete-tag.write";
 export {
   createRemoveTagHandler,
   removeTagHandler,
 } from "./handlers/remove-tag.write";
 export {
-  createRenameTagHandler,
-  renameTagHandler,
-} from "./handlers/rename-tag.write";
+  createUpdateTagHandler,
+  updateTagHandler,
+} from "./handlers/update-tag.write";
 export {
   type AssignTagPayload,
   assignTagPayloadSchema,
   type CreateTagPayload,
   createTagPayloadSchema,
+  type DeleteTagPayload,
+  deleteTagPayloadSchema,
   type RemoveTagPayload,
-  type RenameTagPayload,
   removeTagPayloadSchema,
-  renameTagPayloadSchema,
+  type UpdateTagPayload,
+  updateTagPayloadSchema,
 } from "./schemas";

package/src/tags/schemas.ts

@@ -3,17 +3,36 @@ import { z } from "zod";
 export const createTagPayloadSchema = z.object({
   name: z.string().min(1).max(64),
   color: z.string().max(32).optional(),
+  scope: z.string().max(64).optional(),
 });
 export type CreateTagPayload = z.infer<typeof createTagPayloadSchema>;
 
-// rename-tag — id + the version the client read (optimistic lock, mirrors
-// tenant:update) + the new name. The executor merges shallowly, so color stays.
-export const renameTagPayloadSchema = z.object({
+// update-tag — id + the version the client read (optimistic lock, mirrors
+// tenant:update) + the fields to change. name/color/scope are each optional so
+// the management UI can rename, recolor or re-scope independently; the executor
+// shallow-merges, so any field left undefined is preserved. color/scope accept ""
+// to clear them. At least one mutable field must be present (no-op guard).
+export const updateTagPayloadSchema = z
+  .object({
+    id: z.string().min(1),
+    version: z.number().int().nonnegative(),
+    name: z.string().min(1).max(64).optional(),
+    color: z.string().max(32).optional(),
+    scope: z.string().max(64).optional(),
+  })
+  .refine((p) => p.name !== undefined || p.color !== undefined || p.scope !== undefined, {
+    message: "update-tag needs at least one of name, color or scope",
+  });
+export type UpdateTagPayload = z.infer<typeof updateTagPayloadSchema>;
+
+// delete-tag — hard-deletes the catalog tag AND cascades a soft-delete over
+// every assignment carrying it (no FK, so the handler does the cascade). No
+// version: deleting a label is a destructive "make it gone" intent — last writer
+// wins toward deletion rather than 409-ing on a concurrent rename. Idempotent.
+export const deleteTagPayloadSchema = z.object({
   id: z.string().min(1),
-  version: z.number().int().nonnegative(),
-  name: z.string().min(1).max(64),
 });
-export type RenameTagPayload = z.infer<typeof renameTagPayloadSchema>;
+export type DeleteTagPayload = z.infer<typeof deleteTagPayloadSchema>;
 
 // assign + remove share the (tag, entity) reference shape.
 const entityTagRef = {

package/src/tags/web/__tests__/entity-tags.test.tsx

@@ -0,0 +1,107 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { TagsQueries } from "../../constants";
+import { EntityTags } from "../entity-tags";
+import { defaultTranslations } from "../i18n";
+
+type TagRow = { id: string; name: string; color?: string };
+type AssignmentRow = { tagId: string; entityType: string; entityId: string };
+
+let catalogRows: readonly TagRow[] = [];
+let assignmentRows: readonly AssignmentRow[] = [];
+
+beforeEach(() => {
+  catalogRows = [];
+  assignmentRows = [];
+});
+
+const useQuerySpy = mock((type: string) => ({
+  data: type === TagsQueries.tagList ? { rows: catalogRows } : { rows: assignmentRows },
+  loading: false,
+  error: null,
+  refetch: mock(async () => {}),
+}));
+
+const actual_renderer = await import("@cosmicdrift/kumiko-renderer");
+mock.module("@cosmicdrift/kumiko-renderer", () => ({
+  ...actual_renderer,
+  useQuery: useQuerySpy,
+}));
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()} fallbackBundles={[defaultTranslations]}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+describe("EntityTags", () => {
+  test("renders a chip per assigned tag, joined to the catalog by id", () => {
+    catalogRows = [
+      { id: "t1", name: "important", color: "#ef4444" },
+      { id: "t2", name: "project-x", color: "#3b82f6" },
+    ];
+    assignmentRows = [
+      { tagId: "t1", entityType: "note", entityId: "n1" },
+      { tagId: "t2", entityType: "note", entityId: "n1" },
+    ];
+
+    render(
+      <Wrapper>
+        <EntityTags entityName="note" entityId="n1" />
+      </Wrapper>,
+    );
+
+    expect(screen.getByTestId("entity-tags")).toBeTruthy();
+    expect(screen.getByText("important")).toBeTruthy();
+    expect(screen.getByText("project-x")).toBeTruthy();
+  });
+
+  test("renders nothing when the entity has no assignments", () => {
+    catalogRows = [{ id: "t1", name: "important" }];
+    assignmentRows = [];
+
+    render(
+      <Wrapper>
+        <EntityTags entityName="note" entityId="n1" />
+      </Wrapper>,
+    );
+
+    expect(screen.queryByTestId("entity-tags")).toBeNull();
+    expect(screen.queryByTestId("tag-chip")).toBeNull();
+  });
+
+  test("ignores assignments belonging to a different entityType", () => {
+    catalogRows = [{ id: "t1", name: "important" }];
+    assignmentRows = [{ tagId: "t1", entityType: "invoice", entityId: "n1" }];
+
+    render(
+      <Wrapper>
+        <EntityTags entityName="note" entityId="n1" />
+      </Wrapper>,
+    );
+
+    expect(screen.queryByTestId("entity-tags")).toBeNull();
+  });
+
+  test("renders nothing for a not-yet-saved entity (entityId null)", () => {
+    catalogRows = [{ id: "t1", name: "important" }];
+    assignmentRows = [{ tagId: "t1", entityType: "note", entityId: "n1" }];
+
+    render(
+      <Wrapper>
+        <EntityTags entityName="note" entityId={null} />
+      </Wrapper>,
+    );
+
+    expect(screen.queryByTestId("entity-tags")).toBeNull();
+  });
+});

package/src/tags/web/__tests__/tag-chip.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { contrastText } from "../tag-chip";
+
+// contrastText is the only non-trivial logic in TagChip: the YIQ pick must put
+// white on dark labels and black on light ones, and reject non-hex input so the
+// chip falls back to neutral instead of rendering an invalid CSS color.
+describe("contrastText", () => {
+  test("white text on dark colors", () => {
+    expect(contrastText("#000000")).toBe("#ffffff");
+    expect(contrastText("#1e3a8a")).toBe("#ffffff"); // dark blue
+  });
+
+  test("black text on light colors", () => {
+    expect(contrastText("#ffffff")).toBe("#000000");
+    expect(contrastText("#fde68a")).toBe("#000000"); // light yellow
+  });
+
+  test("supports 3-digit shorthand hex", () => {
+    expect(contrastText("#fff")).toBe("#000000");
+    expect(contrastText("#000")).toBe("#ffffff");
+  });
+
+  test("trims surrounding whitespace", () => {
+    expect(contrastText("  #ffffff  ")).toBe("#000000");
+  });
+
+  test("returns null for non-hex / malformed input", () => {
+    expect(contrastText("")).toBeNull();
+    expect(contrastText("rebeccapurple")).toBeNull();
+    expect(contrastText("#12")).toBeNull();
+    expect(contrastText("#1234")).toBeNull();
+    expect(contrastText("22cc88")).toBeNull(); // missing #
+  });
+});

package/src/tags/web/__tests__/tag-filter.test.tsx

@@ -0,0 +1,124 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { fireEvent, render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { TagsQueries } from "../../constants";
+import { defaultTranslations } from "../i18n";
+import { TagFilter } from "../tag-filter";
+
+type TagRow = { id: string; name: string; color?: string };
+type AssignmentRow = { tagId: string; entityType: string; entityId: string };
+
+let catalogRows: readonly TagRow[] = [];
+let assignmentRows: readonly AssignmentRow[] = [];
+const setFilterSpy = mock((_field: string, _values: readonly string[]) => {});
+
+beforeEach(() => {
+  catalogRows = [
+    { id: "t1", name: "urgent", color: "#ef4444" },
+    { id: "t2", name: "backend", color: "#3b82f6" },
+  ];
+  assignmentRows = [
+    { tagId: "t1", entityType: "note", entityId: "n1" },
+    { tagId: "t2", entityType: "note", entityId: "n2" },
+  ];
+  setFilterSpy.mockClear();
+});
+
+const useQuerySpy = mock((type: string) => ({
+  data: type === TagsQueries.tagList ? { rows: catalogRows } : { rows: assignmentRows },
+  loading: false,
+  error: null,
+  refetch: mock(async () => {}),
+}));
+
+const actual_renderer = await import("@cosmicdrift/kumiko-renderer");
+mock.module("@cosmicdrift/kumiko-renderer", () => ({
+  ...actual_renderer,
+  useQuery: useQuerySpy,
+  useListUrlState: () => ({
+    sort: null,
+    q: "",
+    page: 1,
+    filters: {},
+    setSort: mock(() => {}),
+    setQ: mock(() => {}),
+    setPage: mock(() => {}),
+    setFilter: setFilterSpy,
+    clearFilters: mock(() => {}),
+  }),
+}));
+
+// Headless picker stub: a button that reports a tag selection back through the
+// real onChange contract — no Dialog/cmdk popover to drive.
+const StubPicker = ({
+  onChange,
+}: {
+  readonly value: readonly string[];
+  readonly onChange: (next: readonly string[]) => void;
+  readonly entityType: string;
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+}): ReactNode => (
+  <button type="button" data-testid="picker-pick-t1" onClick={() => onChange(["t1"])}>
+    pick urgent
+  </button>
+);
+mock.module("../tag-picker", () => ({ TagPicker: StubPicker }));
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()} fallbackBundles={[defaultTranslations]}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+describe("TagFilter", () => {
+  test("idle → just the filter button, no chips, no clear", () => {
+    render(
+      <Wrapper>
+        <TagFilter entityName="note" screenId="note-list" />
+      </Wrapper>,
+    );
+    expect(screen.getByTestId("tag-filter-open")).toBeTruthy();
+    expect(screen.queryByTestId("tag-chip")).toBeNull();
+    expect(screen.queryByTestId("tag-filter-clear")).toBeNull();
+  });
+
+  test("picking a tag → narrows the list to its entity ids + shows the selected chip + clear", () => {
+    render(
+      <Wrapper>
+        <TagFilter entityName="note" screenId="note-list" />
+      </Wrapper>,
+    );
+
+    fireEvent.click(screen.getByTestId("picker-pick-t1"));
+
+    // urgent (t1) is assigned to n1 → list narrows to that id set
+    expect(setFilterSpy).toHaveBeenCalledWith("id", ["n1"]);
+    // the active selection is visible as a chip + a clear affordance
+    expect(screen.getByText("urgent")).toBeTruthy();
+    expect(screen.getByTestId("tag-filter-clear")).toBeTruthy();
+  });
+
+  test("clear → drops the filter and the chip", () => {
+    render(
+      <Wrapper>
+        <TagFilter entityName="note" screenId="note-list" />
+      </Wrapper>,
+    );
+    fireEvent.click(screen.getByTestId("picker-pick-t1"));
+    setFilterSpy.mockClear();
+
+    fireEvent.click(screen.getByTestId("tag-filter-clear"));
+
+    expect(setFilterSpy).toHaveBeenCalledWith("id", []);
+    expect(screen.queryByText("urgent")).toBeNull();
+  });
+});

package/src/tags/web/__tests__/tag-section.test.tsx

@@ -11,7 +11,7 @@ import { TagsHandlers, TagsQueries } from "../../constants";
 import { defaultTranslations } from "../i18n";
 import { TagSection, tagSelectionDelta } from "../tag-section";
 
-type TagRow = { id: string; name: string };
+type TagRow = { id: string; name: string; color?: string };
 type AssignmentRow = { tagId: string; entityType: string; entityId: string };
 
 let catalogRows: readonly TagRow[] = [];
@@ -44,6 +44,36 @@ mock.module("@cosmicdrift/kumiko-renderer", () => ({
   useQuery: useQuerySpy,
 }));
 
+// The real picker is a Dialog wrapping TagManager (cmdk/Radix popovers) — its
+// interaction is the picker's own test + e2e territory. Here we swap a headless
+// stub that just exposes the onChange contract via two buttons, so we can pin
+// what TagSection does with a new selection (the assign/remove diff) without
+// driving a modal. Same contract as the real picker's onChange.
+const StubPicker = ({
+  value,
+  onChange,
+}: {
+  readonly value: readonly string[];
+  readonly onChange: (next: readonly string[]) => void;
+  readonly entityType: string;
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+}): ReactNode => (
+  <div data-testid="stub-picker">
+    <button type="button" data-testid="picker-add-t2" onClick={() => onChange([...value, "t2"])}>
+      add t2
+    </button>
+    <button
+      type="button"
+      data-testid="picker-remove-t1"
+      onClick={() => onChange(value.filter((v) => v !== "t1"))}
+    >
+      remove t1
+    </button>
+  </div>
+);
+mock.module("../tag-picker", () => ({ TagPicker: StubPicker }));
+
 function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
   return (
     <LocaleProvider resolver={createStaticLocaleResolver()} fallbackBundles={[defaultTranslations]}>
@@ -52,51 +82,8 @@ function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
   );
 }
 
-// The real combobox is cmdk + Radix — its popover is e2e/primitive-test
-// territory (see note above). To pin the onSelectionChange → assign/remove
-// wiring we swap in a headless stub that renders one toggle button per option
-// and fires onChange with the toggled selection — same contract, no popover.
-const StubInput: typeof defaultPrimitives.Input = (props) => {
-  if (props.kind === "combobox" && props.multiple === true) {
-    const value = props.value;
-    return (
-      <div data-testid="stub-combobox">
-        {props.options.map((o) => {
-          const selected = value.includes(o.value);
-          return (
-            <button
-              key={o.value}
-              type="button"
-              data-testid={`tag-opt-${o.value}`}
-              onClick={() =>
-                props.onChange(selected ? value.filter((v) => v !== o.value) : [...value, o.value])
-              }
-            >
-              {o.label}
-            </button>
-          );
-        })}
-      </div>
-    );
-  }
-  return <input data-testid={`stub-${props.id}`} />;
-};
-
-function StubComboboxWrapper({ children }: { readonly children: ReactNode }): ReactNode {
-  return (
-    <LocaleProvider resolver={createStaticLocaleResolver()} fallbackBundles={[defaultTranslations]}>
-      <PrimitivesProvider value={{ ...defaultPrimitives, Input: StubInput }}>
-        {children}
-      </PrimitivesProvider>
-    </LocaleProvider>
-  );
-}
-
-// The combobox's assign/remove toggle drives onChange with the full new
-// selection; the component diffs it against the current tags via this helper.
-// Popover interaction itself (cmdk + Radix in jsdom) is covered by the
-// combobox primitive's own tests + e2e — here we pin the diff that turns a
-// selection into assign/remove calls.
+// The picker's onChange drives the full new selection; the section diffs it
+// against the current assignments via this helper to decide assign vs remove.
 describe("tagSelectionDelta", () => {
   test("addition only", () => {
     expect(tagSelectionDelta(["a"], ["a", "b"])).toEqual({ added: ["b"], removed: [] });
@@ -113,9 +100,9 @@ describe("tagSelectionDelta", () => {
 });
 
 describe("TagSection", () => {
-  test("renders assigned tags as combobox chips", () => {
+  test("renders assigned tags as colored chips + an Edit-tags button", () => {
     catalogRows = [
-      { id: "t1", name: "important" },
+      { id: "t1", name: "important", color: "#ef4444" },
       { id: "t2", name: "project-x" },
     ];
     assignmentRows = [{ tagId: "t1", entityType: "note", entityId: "note-1" }];
@@ -126,41 +113,28 @@ describe("TagSection", () => {
       </Wrapper>,
     );
 
-    expect(screen.getByTestId("combobox-tags-section-select")).toBeTruthy();
-    // assigned → chip shown in the trigger; unassigned t2 lives in the (closed) dropdown
+    expect(screen.getByTestId("tags-section")).toBeTruthy();
+    // assigned → chip shown; unassigned t2 is not rendered (it lives in the picker)
     expect(screen.getByText("important")).toBeTruthy();
     expect(screen.queryByText("project-x")).toBeNull();
+    expect(screen.getByTestId("tags-section-edit")).toBeTruthy();
   });
 
-  test("create-and-attach dispatches create-tag, then assign-tag with the new id", async () => {
-    catalogRows = [];
+  test("no assigned tags → renders no chips, just the Edit-tags button", () => {
+    catalogRows = [{ id: "t1", name: "important" }];
     assignmentRows = [];
-    dispatchSpy.mockClear();
 
     render(
       <Wrapper>
-        <TagSection entityName="note" entityId="note-9" />
+        <TagSection entityName="note" entityId="note-1" />
       </Wrapper>,
     );
 
-    fireEvent.change(document.getElementById("tags-section-new") as HTMLInputElement, {
-      target: { value: "urgent" },
-    });
-    fireEvent.click(screen.getByTestId("tags-section-create"));
-
-    await waitFor(() =>
-      expect(dispatchSpy).toHaveBeenCalledWith(TagsHandlers.createTag, { name: "urgent" }),
-    );
-    await waitFor(() =>
-      expect(dispatchSpy).toHaveBeenCalledWith(TagsHandlers.assignTag, {
-        tagId: "tag-new",
-        entityType: "note",
-        entityId: "note-9",
-      }),
-    );
+    expect(screen.queryByTestId("tag-chip")).toBeNull();
+    expect(screen.getByTestId("tags-section-edit")).toBeTruthy();
   });
 
-  test("#524/3: selection change dispatches assign for additions, remove for removals", async () => {
+  test("picker selection dispatches assign for additions, remove for removals", async () => {
     catalogRows = [
       { id: "t1", name: "important" },
       { id: "t2", name: "project-x" },
@@ -169,13 +143,13 @@ describe("TagSection", () => {
     dispatchSpy.mockClear();
 
     render(
-      <StubComboboxWrapper>
+      <Wrapper>
         <TagSection entityName="note" entityId="note-1" />
-      </StubComboboxWrapper>,
+      </Wrapper>,
     );
 
-    // t2 is unselected → toggling it on adds it → assign-tag with t2
-    fireEvent.click(screen.getByTestId("tag-opt-t2"));
+    // t1 assigned → picking [t1, t2] adds t2 → assign-tag
+    fireEvent.click(screen.getByTestId("picker-add-t2"));
     await waitFor(() =>
       expect(dispatchSpy).toHaveBeenCalledWith(TagsHandlers.assignTag, {
         tagId: "t2",
@@ -184,8 +158,8 @@ describe("TagSection", () => {
       }),
     );
 
-    // t1 is selected → toggling it off removes it → remove-tag with t1
-    fireEvent.click(screen.getByTestId("tag-opt-t1"));
+    // t1 assigned → picking [] removes t1 → remove-tag
+    fireEvent.click(screen.getByTestId("picker-remove-t1"));
     await waitFor(() =>
       expect(dispatchSpy).toHaveBeenCalledWith(TagsHandlers.removeTag, {
         tagId: "t1",
@@ -195,7 +169,7 @@ describe("TagSection", () => {
     );
   });
 
-  test("create-mode (no entityId yet) shows the save-first hint instead of the manager", () => {
+  test("create-mode (no entityId yet) shows the save-first hint instead of the section", () => {
     render(
       <Wrapper>
         <TagSection entityName="note" entityId={null} />

package/src/tags/web/__tests__/tags-cell.test.tsx

@@ -0,0 +1,94 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { TagsQueries } from "../../constants";
+import { defaultTranslations } from "../i18n";
+import { TagsCell } from "../tags-cell";
+
+type TagRow = { id: string; name: string; color?: string };
+type AssignmentRow = { tagId: string; entityType: string; entityId: string };
+
+let catalogRows: readonly TagRow[] = [];
+let assignmentRows: readonly AssignmentRow[] = [];
+
+beforeEach(() => {
+  catalogRows = [];
+  assignmentRows = [];
+});
+
+const useQuerySpy = mock((type: string) => ({
+  data: type === TagsQueries.tagList ? { rows: catalogRows } : { rows: assignmentRows },
+  loading: false,
+  error: null,
+  refetch: mock(async () => {}),
+}));
+
+const actual_renderer = await import("@cosmicdrift/kumiko-renderer");
+mock.module("@cosmicdrift/kumiko-renderer", () => ({
+  ...actual_renderer,
+  useQuery: useQuerySpy,
+}));
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()} fallbackBundles={[defaultTranslations]}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+function renderCell(rowId: string): void {
+  render(
+    <Wrapper>
+      <TagsCell value={rowId} row={{ id: rowId }} column={{ field: "tags" }} />
+    </Wrapper>,
+  );
+}
+
+describe("TagsCell", () => {
+  test("renders a chip per tag assigned to the row's id, joined to the catalog", () => {
+    catalogRows = [
+      { id: "t1", name: "important", color: "#ef4444" },
+      { id: "t2", name: "project-x", color: "#3b82f6" },
+    ];
+    assignmentRows = [
+      { tagId: "t1", entityType: "note", entityId: "n1" },
+      { tagId: "t2", entityType: "note", entityId: "n1" },
+      { tagId: "t1", entityType: "note", entityId: "n2" }, // a different row
+    ];
+
+    renderCell("n1");
+
+    expect(screen.getByTestId("tags-cell")).toBeTruthy();
+    expect(screen.getByText("important")).toBeTruthy();
+    expect(screen.getByText("project-x")).toBeTruthy();
+  });
+
+  test("renders nothing when the row has no assigned tags", () => {
+    catalogRows = [{ id: "t1", name: "important" }];
+    assignmentRows = [{ tagId: "t1", entityType: "note", entityId: "other-row" }];
+
+    renderCell("n1");
+
+    expect(screen.queryByTestId("tags-cell")).toBeNull();
+  });
+
+  test("renders nothing for an empty row id", () => {
+    catalogRows = [{ id: "t1", name: "important" }];
+    assignmentRows = [{ tagId: "t1", entityType: "note", entityId: "n1" }];
+
+    render(
+      <Wrapper>
+        <TagsCell value="" row={{}} column={{ field: "tags" }} />
+      </Wrapper>,
+    );
+
+    expect(screen.queryByTestId("tags-cell")).toBeNull();
+  });
+});