@cosmicdrift/kumiko-bundled-features 0.61.0 → 0.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -31,6 +31,7 @@
     "./custom-fields": "./src/custom-fields/index.ts",
     "./custom-fields/web": "./src/custom-fields/web/index.ts",
     "./tags": "./src/tags/index.ts",
+    "./tags/web": "./src/tags/web/index.ts",
     "./billing-foundation": "./src/billing-foundation/index.ts",
     "./subscription-stripe": "./src/subscription-stripe/index.ts",
     "./subscription-mollie": "./src/subscription-mollie/index.ts",

package/src/tags/constants.ts

@@ -8,6 +8,12 @@ import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
 
 export const TAGS_FEATURE_NAME = "tags";
 
+// Registry name for the drop-in <TagSection> component. Apps reference it in a
+// screen schema via `component: { react: { __component: TAGS_SECTION_EXTENSION_NAME } }`
+// after mounting tagsClient(); the component is also importable directly for
+// standalone use from `@cosmicdrift/kumiko-bundled-features/tags/web`.
+export const TAGS_SECTION_EXTENSION_NAME = "TagSection";
+
 // Qualified handler names (QN format: scope:type:name). Clients reference the
 // object instead of magic strings (mirror custom-fields' Handlers/Queries).
 export const TagsHandlers = {

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

@@ -0,0 +1,126 @@
+import { 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, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { TagsHandlers, TagsQueries } from "../../constants";
+import { defaultTranslations } from "../i18n";
+import { TagSection } from "../tag-section";
+
+type TagRow = { id: string; name: string };
+type AssignmentRow = { tagId: string; entityType: string; entityId: string };
+
+let catalogRows: readonly TagRow[] = [];
+let assignmentRows: readonly AssignmentRow[] = [];
+
+// createTag returns the new id; assign/remove return data-less success.
+const dispatchSpy = mock(async (type: string) =>
+  type === TagsHandlers.createTag
+    ? { isSuccess: true, data: { id: "tag-new" } }
+    : { isSuccess: true, data: undefined },
+);
+
+// useQuery is called twice (catalog + assignments) — branch on the QN.
+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,
+  useDispatcher: mock(() => ({ write: dispatchSpy, query: mock(), batch: mock() })),
+  useQuery: useQuerySpy,
+}));
+
+function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <LocaleProvider resolver={createStaticLocaleResolver()} fallbackBundles={[defaultTranslations]}>
+      <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
+    </LocaleProvider>
+  );
+}
+
+describe("TagSection", () => {
+  test("shows assigned + available tags and dispatches assign/remove with the right QN + payload", async () => {
+    catalogRows = [
+      { id: "t1", name: "important" },
+      { id: "t2", name: "project-x" },
+    ];
+    assignmentRows = [{ tagId: "t1", entityType: "note", entityId: "note-1" }];
+    dispatchSpy.mockClear();
+
+    render(
+      <Wrapper>
+        <TagSection entityName="note" entityId="note-1" />
+      </Wrapper>,
+    );
+
+    // Assigned tag → remove button; unassigned catalog tag → assign button.
+    expect(screen.getByTestId("tags-section-remove-t1")).toBeTruthy();
+    expect(screen.getByTestId("tags-section-assign-t2")).toBeTruthy();
+    expect(screen.queryByTestId("tags-section-assign-t1")).toBeNull();
+
+    fireEvent.click(screen.getByTestId("tags-section-assign-t2"));
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(TagsHandlers.assignTag, {
+        tagId: "t2",
+        entityType: "note",
+        entityId: "note-1",
+      }),
+    );
+
+    fireEvent.click(screen.getByTestId("tags-section-remove-t1"));
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith(TagsHandlers.removeTag, {
+        tagId: "t1",
+        entityType: "note",
+        entityId: "note-1",
+      }),
+    );
+  });
+
+  test("create-and-attach dispatches create-tag, then assign-tag with the new id", async () => {
+    catalogRows = [];
+    assignmentRows = [];
+    dispatchSpy.mockClear();
+
+    render(
+      <Wrapper>
+        <TagSection entityName="note" entityId="note-9" />
+      </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",
+      }),
+    );
+  });
+
+  test("create-mode (no entityId yet) shows the save-first hint instead of the manager", () => {
+    render(
+      <Wrapper>
+        <TagSection entityName="note" entityId={null} />
+      </Wrapper>,
+    );
+    expect(screen.getByTestId("tags-section-create-mode")).toBeTruthy();
+    expect(screen.queryByTestId("tags-section")).toBeNull();
+  });
+});

package/src/tags/web/client-plugin.tsx

@@ -0,0 +1,21 @@
+// @runtime client
+// Client-feature factory for tags. Mounted via
+// createKumikoApp({ clientFeatures: [tagsClient()] }) — registers TagSection
+// under TAGS_SECTION_EXTENSION_NAME and contributes the default translations.
+// Required even for standalone <TagSection> use, otherwise its i18n keys render
+// raw.
+
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { TAGS_FEATURE_NAME, TAGS_SECTION_EXTENSION_NAME } from "../constants";
+import { defaultTranslations } from "./i18n";
+import { TagSection } from "./tag-section";
+
+export function tagsClient(): ClientFeatureDefinition {
+  return {
+    name: TAGS_FEATURE_NAME,
+    extensionSectionComponents: {
+      [TAGS_SECTION_EXTENSION_NAME]: TagSection,
+    },
+    translations: defaultTranslations,
+  };
+}

package/src/tags/web/i18n.ts

@@ -0,0 +1,25 @@
+// @runtime client
+// Default translation bundle for the tags UI. tagsClient() hangs it into the
+// LocaleProvider as a fallback bundle — apps override individual keys via
+// tagsClient({ translations: { de: { ... } } }). Keys follow `tags.<area>.<slug>`.
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  de: {
+    "tags.section.createMode": "Speichere zuerst den Eintrag, um Tags zu setzen.",
+    "tags.section.loading": "Lädt…",
+    "tags.section.none": "Keine Tags.",
+    "tags.section.newLabel": "Neuer Tag",
+    "tags.section.create": "Tag anlegen & zuweisen",
+    "tags.section.working": "Speichert…",
+  },
+  en: {
+    "tags.section.createMode": "Save the entity first to add tags.",
+    "tags.section.loading": "Loading…",
+    "tags.section.none": "No tags.",
+    "tags.section.newLabel": "New tag",
+    "tags.section.create": "Create & attach tag",
+    "tags.section.working": "Saving…",
+  },
+};

package/src/tags/web/index.ts

@@ -0,0 +1,4 @@
+// @runtime client
+export { TAGS_SECTION_EXTENSION_NAME, TagsHandlers, TagsQueries } from "../constants";
+export { tagsClient } from "./client-plugin";
+export { TagSection } from "./tag-section";

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

@@ -0,0 +1,204 @@
+// @runtime client
+// TagSection — drop-in tag manager for ANY entity. Given an entityName +
+// entityId it shows the entity's current tags and lets the user attach an
+// existing tag, create-and-attach a new one, or detach a tag. Tag writes are
+// immediate (assign/remove are idempotent), so the section owns its own state
+// and refetches after each action — it is NOT part of a host form's save.
+//
+// Two ways to mount (both need tagsClient() registered once, for i18n):
+//   - standalone:   <TagSection entityName="note" entityId={noteId} />
+//   - extension:    a screen-schema section with
+//                   component: { react: { __component: TAGS_SECTION_EXTENSION_NAME } }
+//                   (RenderEdit passes { entityName, entityId }).
+
+import {
+  useDispatcher,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { TagsHandlers, TagsQueries } from "../constants";
+
+type TagRow = { readonly id: string; readonly name: string; readonly color?: string | null };
+type AssignmentRow = {
+  readonly tagId: string;
+  readonly entityType: string;
+  readonly entityId: string;
+};
+type TagListResponse = { readonly rows: readonly TagRow[] };
+type AssignmentListResponse = { readonly rows: readonly AssignmentRow[] };
+
+// Structural shape of a dispatcher write result for the generic action wrapper.
+// The real WriteResult (a discriminated union) is assignable to this; narrowing
+// on `isSuccess` reaches `error.i18nKey` without importing server-side types.
+type ActionResult =
+  | { readonly isSuccess: true }
+  | { readonly isSuccess: false; readonly error: { readonly i18nKey: string } };
+
+export function TagSection({
+  entityName,
+  entityId,
+}: {
+  readonly entityName: string;
+  readonly entityId: string | null;
+}): ReactNode {
+  const { Banner, Button, Field, Input, Text } = usePrimitives();
+  const t = useTranslation();
+  const dispatcher = useDispatcher();
+  const enabled = entityId !== null;
+  const catalog = useQuery<TagListResponse>(TagsQueries.tagList, {}, { enabled });
+  const assignments = useQuery<AssignmentListResponse>(
+    TagsQueries.assignmentList,
+    { filter: { field: "entityId", op: "eq", value: entityId } },
+    { enabled },
+  );
+  const [newName, setNewName] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [errorKey, setErrorKey] = useState<string | null>(null);
+
+  if (entityId === null) {
+    return (
+      <Banner variant="info" testId="tags-section-create-mode">
+        <Text>{t("tags.section.createMode")}</Text>
+      </Banner>
+    );
+  }
+  if (
+    (catalog.loading && catalog.data === null) ||
+    (assignments.loading && assignments.data === null)
+  ) {
+    return (
+      <Banner variant="loading" testId="tags-section-loading">
+        <Text>{t("tags.section.loading")}</Text>
+      </Banner>
+    );
+  }
+  const queryError = catalog.error ?? assignments.error;
+  if (queryError) {
+    return (
+      <Banner variant="error" testId="tags-section-error">
+        <Text>{t(queryError.i18nKey, queryError.i18nParams)}</Text>
+      </Banner>
+    );
+  }
+
+  const catalogTags = catalog.data?.rows ?? [];
+  const byId = new Map(catalogTags.map((tg) => [tg.id, tg]));
+  const assignedRows = (assignments.data?.rows ?? []).filter((r) => r.entityType === entityName);
+  const assignedIds = new Set(assignedRows.map((r) => r.tagId));
+  const assignedTags = assignedRows.map((r) => byId.get(r.tagId) ?? { id: r.tagId, name: r.tagId });
+  const available = catalogTags.filter((tg) => !assignedIds.has(tg.id));
+
+  const refetch = async (): Promise<void> => {
+    await Promise.all([catalog.refetch(), assignments.refetch()]);
+  };
+
+  const run = async (action: () => Promise<ActionResult>): Promise<void> => {
+    setBusy(true);
+    setErrorKey(null);
+    try {
+      const result = await action();
+      if (!result.isSuccess) {
+        setErrorKey(result.error.i18nKey);
+        return;
+      }
+      await refetch();
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const assign = (tagId: string): Promise<void> =>
+    run(() =>
+      dispatcher.write(TagsHandlers.assignTag, { tagId, entityType: entityName, entityId }),
+    );
+
+  const detach = (tagId: string): Promise<void> =>
+    run(() =>
+      dispatcher.write(TagsHandlers.removeTag, { tagId, entityType: entityName, entityId }),
+    );
+
+  const createAndAssign = async (): Promise<void> => {
+    const name = newName.trim();
+    if (name === "") return;
+    setBusy(true);
+    setErrorKey(null);
+    try {
+      const created = await dispatcher.write<{ id: string }>(TagsHandlers.createTag, { name });
+      if (!created.isSuccess) {
+        setErrorKey(created.error.i18nKey);
+        return;
+      }
+      const assigned = await dispatcher.write(TagsHandlers.assignTag, {
+        tagId: created.data.id,
+        entityType: entityName,
+        entityId,
+      });
+      if (!assigned.isSuccess) {
+        setErrorKey(assigned.error.i18nKey);
+        return;
+      }
+      setNewName("");
+      await refetch();
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <div data-testid="tags-section">
+      {assignedTags.length === 0 ? (
+        <Text>{t("tags.section.none")}</Text>
+      ) : (
+        assignedTags.map((tg) => (
+          <Button
+            key={tg.id}
+            variant="secondary"
+            disabled={busy}
+            onClick={() => void detach(tg.id)}
+            testId={`tags-section-remove-${tg.id}`}
+          >
+            {`${tg.name} ✕`}
+          </Button>
+        ))
+      )}
+
+      {available.map((tg) => (
+        <Button
+          key={tg.id}
+          variant="secondary"
+          disabled={busy}
+          onClick={() => void assign(tg.id)}
+          testId={`tags-section-assign-${tg.id}`}
+        >
+          {`+ ${tg.name}`}
+        </Button>
+      ))}
+
+      <Field id="tags-section-new" label={t("tags.section.newLabel")}>
+        <Input
+          kind="text"
+          id="tags-section-new"
+          name="newTag"
+          value={newName}
+          onChange={setNewName}
+        />
+      </Field>
+      <Button
+        variant="primary"
+        disabled={busy || newName.trim() === ""}
+        onClick={() => void createAndAssign()}
+        testId="tags-section-create"
+      >
+        {busy ? t("tags.section.working") : t("tags.section.create")}
+      </Button>
+
+      {errorKey !== null && (
+        <Banner variant="error" testId="tags-section-action-error">
+          <Text>{t(errorKey)}</Text>
+        </Banner>
+      )}
+    </div>
+  );
+}