@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/tags/web/tag-manager.tsx

@@ -0,0 +1,391 @@
+// @runtime client
+// TagManager — the shared tag-catalog UI, GitLab-labels style. Built ONCE,
+// mounted twice:
+//   - standalone:  <TagManager />                       → the Tags admin screen
+//                  (see all labels + create/recolor/re-scope/delete, no select).
+//   - in a picker: <TagManager entityType selection />  → adds a select toggle
+//                  per (scope-matching) tag and reports the chosen ids back.
+//
+// Catalog edits (create/update/delete) are immediate writes against the
+// per-tenant catalog. Selection is buffered by the caller (TagPicker) and only
+// applied on confirm — managing labels and picking them are separate concerns.
+
+import {
+  useDispatcher,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { TagsHandlers, TagsQueries } from "../constants.js";
+import { TagChip } from "./tag-chip.js";
+
+type TagRow = {
+  readonly id: string;
+  readonly name: string;
+  readonly color?: string | null;
+  readonly scope?: string | null;
+  readonly version: number;
+};
+type AssignmentRow = { readonly tagId: string };
+
+// A small fixed palette so labels stay visually distinct without a color-wheel
+// dependency; the hex field below still accepts any custom value.
+const PRESET_COLORS = [
+  "#ef4444",
+  "#f97316",
+  "#eab308",
+  "#22c55e",
+  "#14b8a6",
+  "#3b82f6",
+  "#6366f1",
+  "#a855f7",
+  "#ec4899",
+  "#6b7280",
+] as const;
+
+type Selection = {
+  readonly value: readonly string[];
+  readonly onChange: (next: readonly string[]) => void;
+};
+
+function ColorPicker({
+  value,
+  onChange,
+  idPrefix,
+}: {
+  readonly value: string;
+  readonly onChange: (next: string) => void;
+  readonly idPrefix: string;
+}): ReactNode {
+  const { Input } = usePrimitives();
+  return (
+    <div className="flex items-center gap-2">
+      <div className="flex flex-wrap gap-1">
+        {PRESET_COLORS.map((c) => (
+          // kumiko-lint-ignore primitives-discipline color swatch needs a raw colored button — Button is variant-styled. kumiko-lint-ignore no-inline-styles Preset swatch color is user-defined (hex), no finite token palette possible
+          <button
+            key={c}
+            type="button"
+            aria-label={c}
+            data-testid={`${idPrefix}-swatch-${c}`}
+            onClick={() => onChange(c)}
+            style={{
+              width: 22,
+              height: 22,
+              borderRadius: 4,
+              backgroundColor: c,
+              border: value.toLowerCase() === c ? "2px solid #111827" : "1px solid #d1d5db",
+            }}
+          />
+        ))}
+      </div>
+      <div className="w-28">
+        <Input
+          kind="text"
+          id={`${idPrefix}-hex`}
+          name={`${idPrefix}-hex`}
+          value={value}
+          onChange={onChange}
+          // kumiko-lint-ignore i18n-ui-strings Hex color value as an example placeholder, not UI text
+          placeholder="#22cc88"
+        />
+      </div>
+    </div>
+  );
+}
+
+export function TagManager({
+  entityType,
+  selection,
+}: {
+  readonly entityType?: string;
+  readonly selection?: Selection;
+}): ReactNode {
+  const { Banner, Button, Field, Input, Dialog, Text } = usePrimitives();
+  const t = useTranslation();
+  const dispatcher = useDispatcher();
+
+  const catalog = useQuery<{ rows: readonly TagRow[] }>(TagsQueries.tagList, {});
+  const assignments = useQuery<{ rows: readonly AssignmentRow[] }>(TagsQueries.assignmentList, {});
+
+  const [newName, setNewName] = useState("");
+  const [newColor, setNewColor] = useState("");
+  const [newScope, setNewScope] = useState(entityType ?? "");
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [editName, setEditName] = useState("");
+  const [editColor, setEditColor] = useState("");
+  const [editScope, setEditScope] = useState("");
+  const [deleting, setDeleting] = useState<TagRow | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [errorKey, setErrorKey] = useState<string | null>(null);
+
+  if (catalog.loading && catalog.data === null) {
+    return (
+      <Banner variant="loading" testId="tag-manager-loading">
+        <Text>{t("tags.section.loading")}</Text>
+      </Banner>
+    );
+  }
+  const queryError = catalog.error ?? assignments.error;
+  if (queryError) {
+    return (
+      <Banner variant="error" testId="tag-manager-error">
+        <Text>{t(queryError.i18nKey, queryError.i18nParams)}</Text>
+      </Banner>
+    );
+  }
+
+  const usage = new Map<string, number>();
+  for (const a of assignments.data?.rows ?? []) usage.set(a.tagId, (usage.get(a.tagId) ?? 0) + 1);
+
+  const selecting = selection !== undefined;
+  const allTags = catalog.data?.rows ?? [];
+  const tags = selecting
+    ? allTags.filter((tag) => {
+        const scope = tag.scope ?? "";
+        return scope === "" || scope === entityType;
+      })
+    : allTags;
+
+  const refetch = async (): Promise<void> => {
+    await Promise.all([catalog.refetch(), assignments.refetch()]);
+  };
+
+  const apply = async (writes: () => Promise<boolean>): Promise<void> => {
+    setBusy(true);
+    setErrorKey(null);
+    try {
+      if (await writes()) await refetch();
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const writeOk = async (type: string, payload: Record<string, unknown>): Promise<boolean> => {
+    const result = await dispatcher.write(type, payload);
+    if (!result.isSuccess) {
+      setErrorKey(result.error.i18nKey);
+      return false;
+    }
+    return true;
+  };
+
+  const createTag = (): void => {
+    const name = newName.trim();
+    if (name === "") return;
+    void apply(async () => {
+      const created = await dispatcher.write<{ id: string }>(TagsHandlers.createTag, {
+        name,
+        ...(newColor.trim() !== "" && { color: newColor.trim() }),
+        ...(newScope.trim() !== "" && { scope: newScope.trim() }),
+      });
+      if (!created.isSuccess) {
+        setErrorKey(created.error.i18nKey);
+        return false;
+      }
+      setNewName("");
+      setNewColor("");
+      if (selection !== undefined) selection.onChange([...selection.value, created.data.id]);
+      return true;
+    });
+  };
+
+  const startEdit = (tag: TagRow): void => {
+    setEditingId(tag.id);
+    setEditName(tag.name);
+    setEditColor(tag.color ?? "");
+    setEditScope(tag.scope ?? "");
+  };
+
+  const saveEdit = (tag: TagRow): void => {
+    const name = editName.trim();
+    if (name === "") return;
+    void apply(async () => {
+      const ok = await writeOk(TagsHandlers.updateTag, {
+        id: tag.id,
+        version: tag.version,
+        name,
+        color: editColor.trim(),
+        scope: editScope.trim(),
+      });
+      if (ok) setEditingId(null);
+      return ok;
+    });
+  };
+
+  const confirmDelete = async (): Promise<void> => {
+    const target = deleting;
+    if (target === null) return;
+    await apply(async () => {
+      const ok = await writeOk(TagsHandlers.deleteTag, { id: target.id });
+      if (ok && selection?.value.includes(target.id)) {
+        selection.onChange(selection.value.filter((id) => id !== target.id));
+      }
+      return ok;
+    });
+    setDeleting(null);
+  };
+
+  const toggle = (id: string): void => {
+    if (selection === undefined) return;
+    const has = selection.value.includes(id);
+    selection.onChange(has ? selection.value.filter((x) => x !== id) : [...selection.value, id]);
+  };
+
+  return (
+    <div data-testid="tag-manager" className="flex flex-col gap-4">
+      {/* Create row */}
+      <div className="flex flex-col gap-2 rounded-md border p-3">
+        <Field id="tag-manager-new-name" label={t("tags.manage.newLabel")}>
+          <Input
+            kind="text"
+            id="tag-manager-new-name"
+            name="newTagName"
+            value={newName}
+            onChange={setNewName}
+            placeholder={t("tags.manage.namePlaceholder")}
+          />
+        </Field>
+        <ColorPicker value={newColor} onChange={setNewColor} idPrefix="tag-manager-new-color" />
+        {!selecting && (
+          <Field id="tag-manager-new-scope" label={t("tags.manage.scopeLabel")}>
+            <Input
+              kind="text"
+              id="tag-manager-new-scope"
+              name="newTagScope"
+              value={newScope}
+              onChange={setNewScope}
+              placeholder={t("tags.manage.scopePlaceholder")}
+            />
+          </Field>
+        )}
+        <div>
+          <Button
+            variant="primary"
+            disabled={busy || newName.trim() === ""}
+            onClick={() => createTag()}
+            testId="tag-manager-create"
+          >
+            {busy ? t("tags.section.working") : t("tags.manage.create")}
+          </Button>
+        </div>
+      </div>
+
+      {/* Catalog list */}
+      {tags.length === 0 ? (
+        <Banner variant="info" testId="tag-manager-empty">
+          <Text>{t("tags.section.empty")}</Text>
+        </Banner>
+      ) : (
+        <div className="flex flex-col gap-1">
+          {tags.map((tag) =>
+            editingId === tag.id ? (
+              <div
+                key={tag.id}
+                data-testid={`tag-manager-edit-${tag.id}`}
+                className="flex flex-col gap-2 rounded-md border p-3"
+              >
+                <Input
+                  kind="text"
+                  id={`tag-edit-name-${tag.id}`}
+                  name="editName"
+                  value={editName}
+                  onChange={setEditName}
+                />
+                <ColorPicker
+                  value={editColor}
+                  onChange={setEditColor}
+                  idPrefix={`tag-edit-color-${tag.id}`}
+                />
+                <Input
+                  kind="text"
+                  id={`tag-edit-scope-${tag.id}`}
+                  name="editScope"
+                  value={editScope}
+                  onChange={setEditScope}
+                  placeholder={t("tags.manage.scopePlaceholder")}
+                />
+                <div className="flex gap-2">
+                  <Button
+                    variant="primary"
+                    disabled={busy || editName.trim() === ""}
+                    onClick={() => saveEdit(tag)}
+                    testId={`tag-manager-save-${tag.id}`}
+                  >
+                    {t("tags.manage.save")}
+                  </Button>
+                  <Button variant="secondary" disabled={busy} onClick={() => setEditingId(null)}>
+                    {t("tags.manage.cancel")}
+                  </Button>
+                </div>
+              </div>
+            ) : (
+              <div
+                key={tag.id}
+                data-testid={`tag-manager-row-${tag.id}`}
+                className="flex items-center gap-2 rounded-md px-2 py-1 hover:bg-muted"
+              >
+                {selecting && (
+                  <Button
+                    variant={selection?.value.includes(tag.id) ? "primary" : "secondary"}
+                    onClick={() => toggle(tag.id)}
+                    testId={`tag-manager-toggle-${tag.id}`}
+                  >
+                    {selection?.value.includes(tag.id) ? "✓" : "+"}
+                  </Button>
+                )}
+                <TagChip name={tag.name} color={tag.color} />
+                {!selecting && (tag.scope ?? "") !== "" && (
+                  <Text variant="small">{`@${tag.scope}`}</Text>
+                )}
+                <Text variant="small">
+                  {t("tags.manage.usage", { count: usage.get(tag.id) ?? 0 })}
+                </Text>
+                <div className="ml-auto flex gap-1">
+                  <Button
+                    variant="secondary"
+                    disabled={busy}
+                    onClick={() => startEdit(tag)}
+                    testId={`tag-manager-edit-btn-${tag.id}`}
+                  >
+                    {t("tags.manage.edit")}
+                  </Button>
+                  <Button
+                    variant="danger"
+                    disabled={busy}
+                    onClick={() => setDeleting(tag)}
+                    testId={`tag-manager-delete-btn-${tag.id}`}
+                  >
+                    {t("tags.manage.delete")}
+                  </Button>
+                </div>
+              </div>
+            ),
+          )}
+        </div>
+      )}
+
+      {errorKey !== null && (
+        <Banner variant="error" testId="tag-manager-action-error">
+          <Text>{t(errorKey)}</Text>
+        </Banner>
+      )}
+
+      <Dialog
+        open={deleting !== null}
+        onOpenChange={(open) => {
+          if (!open) setDeleting(null);
+        }}
+        title={t("tags.manage.deleteConfirmTitle", { name: deleting?.name ?? "" })}
+        description={t("tags.manage.deleteConfirmDesc", {
+          count: usage.get(deleting?.id ?? "") ?? 0,
+        })}
+        confirmLabel={t("tags.manage.delete")}
+        variant="danger"
+        onConfirm={confirmDelete}
+        testId="tag-manager-delete-dialog"
+      />
+    </div>
+  );
+}

package/packages/bundled-features/src/tags/web/tag-picker.tsx

@@ -0,0 +1,55 @@
+// @runtime client
+// TagPicker — the shared "manage + pick labels" modal. Wraps TagManager in
+// select-mode inside a Dialog: the user can create/recolor/delete labels (those
+// hit the catalog immediately) and toggle which ones apply (buffered). On
+// confirm ("Done") the chosen ids are handed back to the caller via onChange;
+// Cancel/✕ discards the selection (catalog edits stay). Scope-filtered to the
+// caller's entityType so only global + matching labels are offered.
+
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { TagManager } from "./tag-manager.js";
+
+export function TagPicker({
+  entityType,
+  value,
+  onChange,
+  open,
+  onOpenChange,
+}: {
+  readonly entityType?: string;
+  readonly value: readonly string[];
+  readonly onChange: (next: readonly string[]) => void;
+  readonly open: boolean;
+  readonly onOpenChange: (open: boolean) => void;
+}): ReactNode {
+  const { Dialog } = usePrimitives();
+  const t = useTranslation();
+  const [buffer, setBuffer] = useState<readonly string[]>(value);
+  const [wasOpen, setWasOpen] = useState(open);
+  // Syncing on the open transition alone, not on `value`: both call sites derive
+  // `value` freshly each render, so a value-keyed effect discarded the in-flight
+  // selection on every parent re-render.
+  if (open !== wasOpen) {
+    setWasOpen(open);
+    if (open) setBuffer(value);
+  }
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={onOpenChange}
+      title={t("tags.picker.title")}
+      confirmLabel={t("tags.picker.done")}
+      onConfirm={async () => {
+        onChange(buffer);
+      }}
+      testId="tag-picker-dialog"
+    >
+      <TagManager
+        {...(entityType !== undefined && { entityType })}
+        selection={{ value: buffer, onChange: setBuffer }}
+      />
+    </Dialog>
+  );
+}

package/packages/bundled-features/src/tags/web/tag-section.tsx

@@ -0,0 +1,179 @@
+// @runtime client
+// TagSection — drop-in tag editor for ANY entity, GitLab-labels style. Shows the
+// entity's tags as colored chips plus an "Edit tags" button that opens the
+// shared TagPicker modal (pick + manage). Applying the picker diffs the
+// selection against the current assignments and runs idempotent assign/remove
+// writes — so the section owns its state and refetches after each change; 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.js";
+import { TagChip } from "./tag-chip.js";
+import { TagPicker } from "./tag-picker.js";
+
+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[] };
+
+// What changed between the entity's current tags and the picker's new selection.
+export function tagSelectionDelta(
+  prev: readonly string[],
+  next: readonly string[],
+): { readonly added: readonly string[]; readonly removed: readonly string[] } {
+  const prevSet = new Set(prev);
+  const nextSet = new Set(next);
+  return {
+    added: next.filter((id) => !prevSet.has(id)),
+    removed: prev.filter((id) => !nextSet.has(id)),
+  };
+}
+
+export function TagSection({
+  entityName,
+  entityId,
+}: {
+  readonly entityName: string;
+  readonly entityId: string | null;
+}): ReactNode {
+  const { Banner, Button, Text } = usePrimitives();
+  const t = useTranslation();
+  const dispatcher = useDispatcher();
+  const enabled = entityId !== null;
+  const catalog = useQuery<TagListResponse>(TagsQueries.tagList, {}, { enabled });
+  // entityType server-side, not just entityId: it collapses the parent-ref
+  // read gate to this one host entity instead of every registered one.
+  const assignments = useQuery<AssignmentListResponse>(
+    TagsQueries.assignmentList,
+    {
+      filters: [
+        { field: "entityType", op: "eq", value: entityName },
+        { field: "entityId", op: "eq", value: entityId },
+      ],
+    },
+    { enabled },
+  );
+  const [pickerOpen, setPickerOpen] = useState(false);
+  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 byId = new Map((catalog.data?.rows ?? []).map((tg) => [tg.id, tg]));
+  const assignedIds = (assignments.data?.rows ?? []).map((r) => r.tagId);
+
+  const refetch = async (): Promise<void> => {
+    await Promise.all([catalog.refetch(), assignments.refetch()]);
+  };
+
+  const writeOk = async (type: string, payload: Record<string, unknown>): Promise<boolean> => {
+    const result = await dispatcher.write(type, payload);
+    if (!result.isSuccess) {
+      setErrorKey(result.error.i18nKey);
+      return false;
+    }
+    return true;
+  };
+
+  const onPicked = (next: readonly string[]): void => {
+    const { added, removed } = tagSelectionDelta(assignedIds, next);
+    if (added.length === 0 && removed.length === 0) return;
+    setBusy(true);
+    setErrorKey(null);
+    void (async () => {
+      try {
+        for (const tagId of added) {
+          if (!(await writeOk(TagsHandlers.assignTag, { tagId, entityType: entityName, entityId })))
+            break;
+        }
+        for (const tagId of removed) {
+          if (!(await writeOk(TagsHandlers.removeTag, { tagId, entityType: entityName, entityId })))
+            break;
+        }
+      } finally {
+        // Unconditional: even a partial failure may have persisted some
+        // writes server-side — skipping refetch here would leave the UI
+        // stale relative to those, undetected until the next interaction.
+        await refetch();
+        setBusy(false);
+      }
+    })();
+  };
+
+  return (
+    <div data-testid="tags-section" className="flex flex-col gap-2">
+      <div className="flex flex-wrap items-center gap-1">
+        {assignedIds.length === 0 ? (
+          <Text variant="small">{t("tags.section.none")}</Text>
+        ) : (
+          assignedIds.map((id) => {
+            const tag = byId.get(id);
+            return <TagChip key={id} name={tag?.name ?? id} color={tag?.color} />;
+          })
+        )}
+        <Button
+          variant="secondary"
+          disabled={busy}
+          onClick={() => setPickerOpen(true)}
+          testId="tags-section-edit"
+        >
+          {busy ? t("tags.section.working") : t("tags.section.edit")}
+        </Button>
+      </div>
+
+      <TagPicker
+        entityType={entityName}
+        value={assignedIds}
+        onChange={onPicked}
+        open={pickerOpen}
+        onOpenChange={setPickerOpen}
+      />
+
+      {errorKey !== null && (
+        <Banner variant="error" testId="tags-section-action-error">
+          <Text>{t(errorKey)}</Text>
+        </Banner>
+      )}
+    </div>
+  );
+}

package/packages/bundled-features/src/tags/web/tags-cell.tsx

@@ -0,0 +1,46 @@
+// @runtime client
+// TagsCell — a reusable columnRenderer that shows an entity's tags as colored
+// chips inline in a list row. Drop it into ANY entityList by declaring a labeled
+// virtual column (no host-schema change), after mounting tagsClient():
+//   columns: [
+//     "title",
+//     { field: "tags", label: "Tags",
+//       renderer: { react: { __component: TAGS_COLUMN_RENDERER_NAME } } },
+//   ]
+// It reads the row's id (entity ids are unique, so entityType is unnecessary)
+// and renders a TagChip per assigned tag; renders nothing when the row has none.
+//
+// ponytail: bulk-loads the assignment list (first 500) + the catalog once and
+// filters per row — kumiko's useQuery dedupes the identical (type, payload)
+// calls, so the whole column shares two queries, not two-per-row. For huge
+// assignment sets add a server-side entitiesByTag query + join filter.
+
+import { type ColumnRendererProps, useQuery } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { TagsQueries } from "../constants.js";
+import { TagChip } from "./tag-chip.js";
+
+type TagRow = { readonly id: string; readonly name: string; readonly color?: string | null };
+type AssignmentRow = { readonly tagId: string; readonly entityId: string };
+
+export function TagsCell({ row }: ColumnRendererProps): ReactNode {
+  const entityId = String(row["id"] ?? "");
+  const catalog = useQuery<{ rows: readonly TagRow[] }>(TagsQueries.tagList, {});
+  const assignments = useQuery<{ rows: readonly AssignmentRow[] }>(TagsQueries.assignmentList, {
+    limit: 500,
+  });
+  if (entityId === "") return null;
+  const byId = new Map((catalog.data?.rows ?? []).map((t) => [t.id, t]));
+  const tagIds = (assignments.data?.rows ?? [])
+    .filter((a) => a.entityId === entityId)
+    .map((a) => a.tagId);
+  if (tagIds.length === 0) return null;
+  return (
+    <div className="flex flex-wrap gap-1" data-testid="tags-cell">
+      {tagIds.map((id) => {
+        const tag = byId.get(id);
+        return <TagChip key={id} name={tag?.name ?? id} color={tag?.color} />;
+      })}
+    </div>
+  );
+}