@cosmicdrift/kumiko-bundled-features 0.97.0 → 0.98.0

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-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/client-plugin.tsx

@@ -1,8 +1,15 @@
 // @runtime client
 
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
-import { TAGS_FEATURE_NAME, TAGS_SECTION_EXTENSION_NAME } from "../constants";
+import {
+  TAGS_FEATURE_NAME,
+  TAGS_FILTER_EXTENSION_NAME,
+  TAGS_SCREEN_ID,
+  TAGS_SECTION_EXTENSION_NAME,
+} from "../constants";
 import { defaultTranslations } from "./i18n";
+import { TagFilter } from "./tag-filter";
+import { TagManager } from "./tag-manager";
 import { TagSection } from "./tag-section";
 
 export function tagsClient(): ClientFeatureDefinition {
@@ -10,6 +17,12 @@ export function tagsClient(): ClientFeatureDefinition {
     name: TAGS_FEATURE_NAME,
     extensionSectionComponents: {
       [TAGS_SECTION_EXTENSION_NAME]: TagSection,
+      // Header-slot tag filter for any entityList toolbar.
+      [TAGS_FILTER_EXTENSION_NAME]: TagFilter,
+    },
+    // Standalone Tags management screen (custom screen → TagManager).
+    components: {
+      [TAGS_SCREEN_ID]: TagManager,
     },
     translations: defaultTranslations,
   };

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

@@ -0,0 +1,47 @@
+// @runtime client
+// EntityTags — read-only colored tag row for ANY entity. Drop it on a card or
+// detail view: <EntityTags entityName="note" entityId={id} />. Loads the
+// catalog (for name+color) and the entity's assignments, renders a TagChip per
+// assigned tag. Renders nothing when the entity has no tags.
+
+import { useQuery } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { TagsQueries } from "../constants";
+import { TagChip } from "./tag-chip";
+
+type TagRow = { readonly id: string; readonly name: string; readonly color?: string | null };
+type AssignmentRow = {
+  readonly tagId: string;
+  readonly entityType: string;
+  readonly entityId: string;
+};
+
+export function EntityTags({
+  entityName,
+  entityId,
+}: {
+  readonly entityName: string;
+  readonly entityId: string | null;
+}): ReactNode {
+  const enabled = entityId !== null;
+  const catalog = useQuery<{ rows: readonly TagRow[] }>(TagsQueries.tagList, {}, { enabled });
+  const assignments = useQuery<{ rows: readonly AssignmentRow[] }>(
+    TagsQueries.assignmentList,
+    { filter: { field: "entityId", op: "eq", value: entityId } },
+    { enabled },
+  );
+
+  if (entityId === null) return null;
+  const byId = new Map((catalog.data?.rows ?? []).map((t) => [t.id, t]));
+  const assigned = (assignments.data?.rows ?? []).filter((r) => r.entityType === entityName);
+  if (assigned.length === 0) return null;
+
+  return (
+    <div data-testid="entity-tags" className="flex flex-wrap gap-1">
+      {assigned.map((a) => {
+        const tag = byId.get(a.tagId);
+        return <TagChip key={a.tagId} name={tag?.name ?? a.tagId} color={tag?.color} />;
+      })}
+    </div>
+  );
+}

package/src/tags/web/i18n.ts

@@ -9,21 +9,52 @@ export const defaultTranslations: TranslationsByLocale = {
   de: {
     "tags.section.createMode": "Speichere zuerst den Eintrag, um Tags zu setzen.",
     "tags.section.loading": "Lädt…",
-    "tags.section.label": "Tags",
-    "tags.section.placeholder": "Tags auswählen…",
     "tags.section.empty": "Keine Tags gefunden.",
-    "tags.section.newLabel": "Neuer Tag",
-    "tags.section.create": "Tag anlegen & zuweisen",
     "tags.section.working": "Speichert…",
+    "tags.section.none": "Keine Tags",
+    "tags.section.edit": "Tags bearbeiten",
+    "tags.manage.newLabel": "Neuer Tag",
+    "tags.manage.namePlaceholder": "Tag-Name",
+    "tags.manage.scopeLabel": "Geltungsbereich (Entity-Typ, leer = global)",
+    "tags.manage.scopePlaceholder": "z. B. note (leer = überall)",
+    "tags.manage.create": "Tag anlegen",
+    "tags.manage.edit": "Bearbeiten",
+    "tags.manage.save": "Speichern",
+    "tags.manage.cancel": "Abbrechen",
+    "tags.manage.delete": "Löschen",
+    "tags.manage.toggle": "Tag umschalten",
+    "tags.manage.usage": "{count}×",
+    "tags.manage.deleteConfirmTitle": "Tag „{name}“ löschen?",
+    "tags.manage.deleteConfirmDesc":
+      "Entfernt ihn von {count} Objekten. Das lässt sich nicht rückgängig machen.",
+    "tags.picker.title": "Tags",
+    "tags.picker.done": "Fertig",
+    "tags.filter.label": "Nach Tag filtern",
+    "tags.filter.active": "Tags: {count}",
   },
   en: {
     "tags.section.createMode": "Save the entity first to add tags.",
     "tags.section.loading": "Loading…",
-    "tags.section.label": "Tags",
-    "tags.section.placeholder": "Select tags…",
     "tags.section.empty": "No tags found.",
-    "tags.section.newLabel": "New tag",
-    "tags.section.create": "Create & attach tag",
     "tags.section.working": "Saving…",
+    "tags.section.none": "No tags",
+    "tags.section.edit": "Edit tags",
+    "tags.manage.newLabel": "New label",
+    "tags.manage.namePlaceholder": "Label name",
+    "tags.manage.scopeLabel": "Scope (entity type, empty = global)",
+    "tags.manage.scopePlaceholder": "e.g. note (empty = everywhere)",
+    "tags.manage.create": "Create label",
+    "tags.manage.edit": "Edit",
+    "tags.manage.save": "Save",
+    "tags.manage.cancel": "Cancel",
+    "tags.manage.delete": "Delete",
+    "tags.manage.toggle": "Toggle label",
+    "tags.manage.usage": "{count}×",
+    "tags.manage.deleteConfirmTitle": "Delete label “{name}”?",
+    "tags.manage.deleteConfirmDesc": "Removes it from {count} objects. This can't be undone.",
+    "tags.picker.title": "Tags",
+    "tags.picker.done": "Done",
+    "tags.filter.label": "Filter by tag",
+    "tags.filter.active": "Tags: {count}",
   },
 };

package/src/tags/web/index.ts

@@ -1,4 +1,15 @@
 // @runtime client
-export { TAGS_SECTION_EXTENSION_NAME, TagsHandlers, TagsQueries } from "../constants";
+export {
+  TAGS_FILTER_EXTENSION_NAME,
+  TAGS_SCREEN_ID,
+  TAGS_SECTION_EXTENSION_NAME,
+  TagsHandlers,
+  TagsQueries,
+} from "../constants";
 export { tagsClient } from "./client-plugin";
+export { EntityTags } from "./entity-tags";
+export { contrastText, TagChip } from "./tag-chip";
+export { TagFilter } from "./tag-filter";
+export { TagManager } from "./tag-manager";
+export { TagPicker } from "./tag-picker";
 export { TagSection } from "./tag-section";

package/src/tags/web/tag-chip.tsx

@@ -0,0 +1,63 @@
+// @runtime client
+// TagChip — read-only colored label pill, GitLab-labels style. The tag's `color`
+// (a hex like "#22cc88") drives the background; the text color is chosen for
+// contrast (YIQ luminance) so light and dark labels both stay legible. A tag
+// with no usable color falls back to a neutral chip. Self-contained inline
+// styles (pattern from config-source-badge.tsx) so it renders the same in the
+// picker, on cards and in screenshots without depending on Tailwind tokens.
+
+import type { CSSProperties, ReactNode } from "react";
+
+// YIQ perceived brightness → black text on light backgrounds, white on dark.
+// Returns null for anything that isn't a #rgb/#rrggbb hex so the caller can use
+// its neutral fallback (color is a free-text UI hint, never validated).
+export function contrastText(color: string): "#000000" | "#ffffff" | null {
+  const rgb = hexToRgb(color);
+  if (rgb === null) return null;
+  const yiq = (rgb.r * 299 + rgb.g * 587 + rgb.b * 114) / 1000;
+  return yiq >= 128 ? "#000000" : "#ffffff";
+}
+
+function hexToRgb(color: string): { r: number; g: number; b: number } | null {
+  const match = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(color.trim());
+  if (match === null) return null;
+  const short = match[1] as string;
+  const hex =
+    short.length === 3
+      ? `${short[0]}${short[0]}${short[1]}${short[1]}${short[2]}${short[2]}`
+      : short;
+  return {
+    r: Number.parseInt(hex.slice(0, 2), 16),
+    g: Number.parseInt(hex.slice(2, 4), 16),
+    b: Number.parseInt(hex.slice(4, 6), 16),
+  };
+}
+
+const BASE_STYLE: CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  padding: "0 8px",
+  fontSize: "12px",
+  fontWeight: 500,
+  lineHeight: "20px",
+  borderRadius: "9999px",
+  whiteSpace: "nowrap",
+};
+
+const NEUTRAL = { backgroundColor: "#e5e7eb", color: "#374151" } as const;
+
+export function TagChip({
+  name,
+  color,
+}: {
+  readonly name: string;
+  readonly color?: string | null;
+}): ReactNode {
+  const fg = color != null && color !== "" ? contrastText(color) : null;
+  const palette = fg !== null && color != null ? { backgroundColor: color, color: fg } : NEUTRAL;
+  return (
+    <span data-testid="tag-chip" style={{ ...BASE_STYLE, ...palette }}>
+      {name}
+    </span>
+  );
+}

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

@@ -0,0 +1,88 @@
+// @runtime client
+// TagFilter — a drop-in tag filter for ANY entityList toolbar. Register it as
+// the list's header slot (`screen.slots.header`) and mark `id` filterable is NOT
+// needed — the renderer passes this control the list's screenId, and picking
+// tags resolves the matching row ids and narrows the list via an id-set URL
+// filter (`<screenId>.f.id=…`, applied as `{ field: "id", op: "in" }`). No host
+// schema change: any list gets tag-filtering by mounting this in its header.
+//
+// ponytail: resolves ids from the assignment list (first 500 rows) + an id-IN
+// URL filter — fine for typical tag volumes. For huge assignment sets add a
+// server-side `entitiesByTag` query + a server-side join filter instead.
+
+import {
+  useListUrlState,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { TagsQueries } from "../constants";
+import { TagPicker } from "./tag-picker";
+
+// Tags chosen but zero matching entities → filter to a value that matches no row
+// (so the list shows empty), instead of clearing the filter (which shows all).
+const NO_MATCH = "__tags_no_match__";
+
+type AssignmentRow = {
+  readonly tagId: string;
+  readonly entityType: string;
+  readonly entityId: string;
+};
+
+export function TagFilter({
+  entityName,
+  screenId,
+}: {
+  readonly entityName: string;
+  readonly entityId?: string | null;
+  readonly screenId?: string;
+}): ReactNode {
+  const { Button } = usePrimitives();
+  const t = useTranslation();
+  const [open, setOpen] = useState(false);
+  const [selected, setSelected] = useState<readonly string[]>([]);
+  const assignments = useQuery<{ rows: readonly AssignmentRow[] }>(TagsQueries.assignmentList, {
+    limit: 500,
+  });
+  // Unconditional (Rules of Hooks). The renderer always passes a screenId in the
+  // header slot; the fallback namespace is inert if it ever runs standalone.
+  const urlState = useListUrlState(screenId ?? "__tag-filter__");
+
+  const applyFilter = (tagIds: readonly string[]): void => {
+    setSelected(tagIds);
+    if (tagIds.length === 0) {
+      urlState.setFilter("id", []);
+      return;
+    }
+    const wanted = new Set(tagIds);
+    const ids = [
+      ...new Set(
+        (assignments.data?.rows ?? [])
+          .filter((a) => a.entityType === entityName && wanted.has(a.tagId))
+          .map((a) => a.entityId),
+      ),
+    ];
+    urlState.setFilter("id", ids.length > 0 ? ids : [NO_MATCH]);
+  };
+
+  const label =
+    selected.length > 0
+      ? t("tags.filter.active", { count: selected.length })
+      : t("tags.filter.label");
+
+  return (
+    <>
+      <Button variant="secondary" onClick={() => setOpen(true)} testId="tag-filter-open">
+        {label}
+      </Button>
+      <TagPicker
+        entityType={entityName}
+        value={selected}
+        onChange={applyFilter}
+        open={open}
+        onOpenChange={setOpen}
+      />
+    </>
+  );
+}