@agent-native/toolkit 0.20.8 → 0.21.0-nightly-20260925012751

package/src/icons/catalog.spec.ts

@@ -0,0 +1,50 @@
+import { icons } from "@tabler/icons-react";
+import { describe, expect, it } from "vitest";
+
+import {
+  loadTablerCatalog,
+  loadTablerIcon,
+  searchTablerIcons,
+  TABLER_ICON_CATEGORIES,
+  tablerExportName,
+} from "./catalog.js";
+import { TABLER_ICON_GROUPS } from "./tabler-groups.js";
+
+describe("Tabler catalog", () => {
+  it("includes every canonical outline and filled icon once, with a renderable component", async () => {
+    const catalog = await loadTablerCatalog();
+    expect(catalog.map((entry) => tablerExportName(entry.name)).sort()).toEqual(
+      Object.keys(icons).sort(),
+    );
+    expect(new Set(catalog.map((entry) => entry.name)).size).toBe(
+      catalog.length,
+    );
+    expect(catalog.length).toBeGreaterThan(6_000);
+    const components = await Promise.all(
+      catalog.map((entry) => loadTablerIcon(entry.name)),
+    );
+    expect(components.every((component) => component !== null)).toBe(true);
+    expect(new Set(catalog.map((entry) => entry.category))).toEqual(
+      new Set(TABLER_ICON_CATEGORIES),
+    );
+  });
+
+  it("does not truncate browsing or broad searches, and searches tags", async () => {
+    expect(await searchTablerIcons("")).toHaveLength(
+      (await loadTablerCatalog()).length,
+    );
+    expect((await searchTablerIcons("arrow")).length).toBeGreaterThan(120);
+    expect(await searchTablerIcons("arrow", 12)).toHaveLength(12);
+    expect(await searchTablerIcons("programming")).toContain("a-b");
+    expect(await loadTablerIcon("not-a-real-icon")).toBeNull();
+  });
+
+  it("places every source category in exactly one reader-facing group", () => {
+    const assigned = TABLER_ICON_GROUPS.flatMap((group) => group.categories);
+    expect(assigned).toHaveLength(TABLER_ICON_CATEGORIES.length);
+    expect(new Set(assigned)).toEqual(new Set(TABLER_ICON_CATEGORIES));
+    expect(new Set(TABLER_ICON_GROUPS.map((group) => group.id)).size).toBe(
+      TABLER_ICON_GROUPS.length,
+    );
+  });
+});

package/src/icons/catalog.ts

@@ -0,0 +1,153 @@
+import type { ComponentType, SVGProps } from "react";
+
+export type TablerIconComponent = ComponentType<
+  Omit<SVGProps<SVGSVGElement>, "stroke"> & {
+    size?: number | string;
+    stroke?: number;
+  }
+>;
+
+type TablerModule = Record<string, unknown>;
+type ViteImportMeta = ImportMeta & { env: { SSR: boolean; MODE: string } };
+
+export const TABLER_ICON_CATEGORIES = [
+  "system",
+  "communication",
+  "document",
+  "media",
+  "design",
+  "development",
+  "devices",
+  "computers",
+  "database",
+  "charts",
+  "arrows",
+  "shapes",
+  "symbols",
+  "text",
+  "letters",
+  "numbers",
+  "math",
+  "logic",
+  "version-control",
+  "extensions",
+  "e-commerce",
+  "currencies",
+  "buildings",
+  "map",
+  "vehicles",
+  "nature",
+  "animals",
+  "weather",
+  "food",
+  "health",
+  "sport",
+  "games",
+  "photography",
+  "mood",
+  "gestures",
+  "gender",
+  "badges",
+  "electrical",
+  "laundry",
+  "zodiac",
+  "brand",
+] as const;
+
+export type TablerIconCategory = (typeof TABLER_ICON_CATEGORIES)[number];
+
+export interface TablerCatalogEntry {
+  name: string;
+  category: TablerIconCategory;
+  search: string;
+}
+
+let metadataPromise: Promise<TablerCatalogEntry[]> | undefined;
+
+export function tablerExportName(name: string): string {
+  return `Icon${name
+    .split("-")
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("")}`;
+}
+
+export async function loadTablerIcon(
+  name: string,
+): Promise<TablerIconComponent | null> {
+  if (
+    (import.meta as ViteImportMeta).env.SSR &&
+    (import.meta as ViteImportMeta).env.MODE !== "test"
+  ) {
+    throw new Error("Tabler icons are available only in the browser");
+  }
+  const initial = name.charAt(0).toLowerCase();
+  const { default: loaders } = await import("./tabler-chunk-loaders.js");
+  const loadChunk = (
+    loaders as Record<string, () => Promise<{ default: TablerModule }>>
+  )[initial];
+  if (!loadChunk) return null;
+  const { default: catalog } = await loadChunk();
+  const candidate = catalog[tablerExportName(name)];
+  return typeof candidate === "object" || typeof candidate === "function"
+    ? (candidate as TablerIconComponent)
+    : null;
+}
+
+export async function searchTablerIcons(
+  query: string,
+  limit?: number,
+): Promise<string[]> {
+  const catalog = await loadTablerCatalog();
+  const normalized = query.trim().toLowerCase();
+  return catalog
+    .filter((entry) => entry.search.includes(normalized))
+    .map((entry) => entry.name)
+    .slice(0, limit);
+}
+
+export function loadTablerCatalog(): Promise<TablerCatalogEntry[]> {
+  if (
+    (import.meta as ViteImportMeta).env.SSR &&
+    (import.meta as ViteImportMeta).env.MODE !== "test"
+  ) {
+    throw new Error("Tabler catalog is available only in the browser");
+  }
+  metadataPromise ??= import("./tabler-catalog-data.js")
+    .then(({ default: metadata }) => {
+      return metadata
+        .flatMap(([baseName, category, tags, styles]): TablerCatalogEntry[] => {
+          if (
+            !TABLER_ICON_CATEGORIES.includes(category as TablerIconCategory)
+          ) {
+            throw new Error(`Unknown Tabler icon category: ${category}`);
+          }
+          return styles.split(" ").map((style) => {
+            const name = `${baseName}${style === "filled" ? "-filled" : ""}`;
+            return {
+              name,
+              category: category as TablerIconCategory,
+              search: [
+                name,
+                name.replaceAll("-", " "),
+                category.replaceAll("-", " "),
+                tags,
+              ]
+                .join(" ")
+                .toLowerCase(),
+            };
+          });
+        })
+        .sort(
+          (left, right) =>
+            TABLER_ICON_CATEGORIES.indexOf(left.category) -
+              TABLER_ICON_CATEGORIES.indexOf(right.category) ||
+            left.name.localeCompare(right.name),
+        );
+    })
+    .catch((error) => {
+      metadataPromise = undefined;
+      throw error;
+    });
+  return metadataPromise;
+}

package/src/icons/emoji-catalog.spec.ts

@@ -0,0 +1,46 @@
+import data from "emojibase-data/en/data.json";
+import { describe, expect, it } from "vitest";
+
+import { EMOJI_CATEGORIES, loadEmojiCatalog } from "./emoji-catalog.js";
+
+describe("emoji catalog", () => {
+  it("loads the maintained dataset with joined and skin-tone sequences", async () => {
+    const catalog = await loadEmojiCatalog();
+    expect(catalog.length).toBeGreaterThan(1_000);
+    expect(catalog.some((entry) => entry.emoji.includes("\u200d"))).toBe(true);
+    expect(
+      catalog.some((entry) => /[\u{1F3FB}-\u{1F3FF}]/u.test(entry.emoji)),
+    ).toBe(true);
+  });
+
+  it("browses the complete Unicode catalog in group order without standalone components", async () => {
+    const catalog = await loadEmojiCatalog();
+    const expected = data
+      .filter(
+        (entry) =>
+          entry.group !== undefined &&
+          entry.group !== 2 &&
+          entry.order !== undefined,
+      )
+      .flatMap((entry) => [entry, ...(entry.skins ?? [])])
+      .map((entry) => entry.emoji);
+    expect(catalog.map((entry) => entry.emoji).sort()).toEqual(expected.sort());
+    expect(catalog[0].emoji).toBe("😀");
+    expect(catalog.some((entry) => entry.emoji === "🇦")).toBe(false);
+    expect(catalog.some((entry) => entry.emoji === "🏻")).toBe(false);
+    expect(
+      catalog.some(
+        (entry) => entry.emoji === "🇿🇼" && entry.category === "flags",
+      ),
+    ).toBe(true);
+    expect(
+      catalog.some((entry) => entry.emoji === "👋🏽" && entry.skinTone === 3),
+    ).toBe(true);
+    expect(catalog.map((entry) => entry.order)).toEqual(
+      catalog.map((entry) => entry.order).sort((a, b) => a - b),
+    );
+    expect(new Set(catalog.map((entry) => entry.category))).toEqual(
+      new Set(EMOJI_CATEGORIES),
+    );
+  });
+});

package/src/icons/emoji-catalog.ts

@@ -0,0 +1,86 @@
+export const EMOJI_CATEGORIES = [
+  "smileys-emotion",
+  "people-body",
+  "animals-nature",
+  "food-drink",
+  "travel-places",
+  "activities",
+  "objects",
+  "symbols",
+  "flags",
+] as const;
+
+export type EmojiCategory = (typeof EMOJI_CATEGORIES)[number];
+
+export interface EmojiCatalogEntry {
+  emoji: string;
+  label: string;
+  search: string;
+  category: EmojiCategory;
+  order: number;
+  skinTone?: number | number[];
+}
+
+interface EmojibaseEntry {
+  emoji?: string;
+  label?: string;
+  tags?: string[];
+  group?: number;
+  order?: number;
+  tone?: number | number[];
+  skins?: EmojibaseEntry[];
+}
+
+type ViteImportMeta = ImportMeta & { env: { SSR: boolean; MODE: string } };
+
+let emojiCatalogPromise: Promise<EmojiCatalogEntry[]> | undefined;
+
+export function loadEmojiCatalog(): Promise<EmojiCatalogEntry[]> {
+  if (
+    (import.meta as ViteImportMeta).env.SSR &&
+    (import.meta as ViteImportMeta).env.MODE !== "test"
+  ) {
+    throw new Error("Emoji catalog is available only in the browser");
+  }
+  emojiCatalogPromise ??= import("emojibase-data/en/data.json")
+    .then((module) => {
+      const rows = (module.default ?? module) as EmojibaseEntry[];
+      return rows
+        .flatMap((row) => {
+          // Components (including regional letters) are not standalone emoji choices.
+          if (
+            row.group === undefined ||
+            row.group === 2 ||
+            row.order === undefined
+          ) {
+            return [];
+          }
+          const category =
+            EMOJI_CATEGORIES[row.group > 2 ? row.group - 1 : row.group];
+          if (!category) throw new Error(`Unknown emoji group: ${row.group}`);
+          const variants = [row, ...(row.skins ?? [])];
+          return variants.flatMap((variant) => {
+            if (!variant.emoji) return [];
+            const label = variant.label ?? row.label ?? variant.emoji;
+            return [
+              {
+                emoji: variant.emoji,
+                label,
+                search: [label, ...(row.tags ?? [])].join(" ").toLowerCase(),
+                category,
+                order: variant.order ?? row.order!,
+                ...(variant.tone === undefined
+                  ? {}
+                  : { skinTone: variant.tone }),
+              },
+            ];
+          });
+        })
+        .sort((left, right) => left.order - right.order);
+    })
+    .catch((error) => {
+      emojiCatalogPromise = undefined;
+      throw error;
+    });
+  return emojiCatalogPromise;
+}

package/src/icons/icon-colors.ts

@@ -0,0 +1,13 @@
+import type { ResourceIconColor } from "./types.js";
+
+export const resourceIconColorClasses: Record<ResourceIconColor, string> = {
+  gray: "text-[var(--resource-icon-gray)]",
+  brown: "text-[var(--resource-icon-brown)]",
+  orange: "text-[var(--resource-icon-orange)]",
+  yellow: "text-[var(--resource-icon-yellow)]",
+  green: "text-[var(--resource-icon-green)]",
+  blue: "text-[var(--resource-icon-blue)]",
+  purple: "text-[var(--resource-icon-purple)]",
+  pink: "text-[var(--resource-icon-pink)]",
+  red: "text-[var(--resource-icon-red)]",
+};

package/src/icons/icon-persistence.spec.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import { persistedIconValue } from "./ResourceIconPicker.js";
+import type { ResourceIconImage } from "./types.js";
+
+describe("persistedIconValue", () => {
+  it("removes preview-only metadata before saving an uploaded image", () => {
+    const uploaded: ResourceIconImage = {
+      version: 1,
+      kind: "image",
+      authority: "url",
+      assetId: "https://cdn.example.com/logo.png",
+      alt: "Team logo",
+      previewUrl: "blob:temporary-preview",
+    };
+
+    expect(persistedIconValue(uploaded)).toEqual({
+      version: 1,
+      kind: "image",
+      authority: "url",
+      assetId: "https://cdn.example.com/logo.png",
+      alt: "Team logo",
+    });
+    expect(uploaded.previewUrl).toBe("blob:temporary-preview");
+  });
+
+  it("repairs image recents saved by the previous picker", () => {
+    const recent = JSON.parse(
+      JSON.stringify({
+        version: 1,
+        kind: "image",
+        authority: "url",
+        assetId: "https://cdn.example.com/logo.png",
+        previewUrl: "https://cdn.example.com/logo.png",
+      }),
+    );
+
+    expect(Object.keys(persistedIconValue(recent)).sort()).toEqual([
+      "assetId",
+      "authority",
+      "kind",
+      "version",
+    ]);
+  });
+});

package/src/icons/index.ts

@@ -0,0 +1,4 @@
+export * from "./ResourceIcon.js";
+export * from "./ResourceIconPicker.js";
+export * from "./recents.js";
+export * from "./types.js";

package/src/icons/recents.spec.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+
+import { addResourceIconRecent, resourceIconKey } from "./recents.js";
+import type { ResourceIconValue } from "./types.js";
+
+describe("resource icon recents", () => {
+  it("deduplicates the complete value while preserving colored variants", () => {
+    const blue: ResourceIconValue = {
+      version: 1,
+      kind: "library",
+      library: "tabler",
+      name: "book",
+      color: "blue",
+    };
+    const red: ResourceIconValue = { ...blue, color: "red" };
+    expect(addResourceIconRecent([blue, red], blue)).toEqual([blue, red]);
+    expect(resourceIconKey(blue)).not.toBe(resourceIconKey(red));
+  });
+
+  it("bounds recents to 24 by default", () => {
+    const recents: ResourceIconValue[] = Array.from(
+      { length: 30 },
+      (_, index) => ({
+        version: 1,
+        kind: "emoji",
+        emoji: String(index),
+      }),
+    );
+    expect(
+      addResourceIconRecent(recents, {
+        version: 1,
+        kind: "emoji",
+        emoji: "new",
+      }),
+    ).toHaveLength(24);
+  });
+});

package/src/icons/recents.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+
+import type { ResourceIconValue } from "./types.js";
+
+export const RESOURCE_ICON_RECENTS_LIMIT = 24;
+
+export function resourceIconKey(value: ResourceIconValue): string {
+  if (value.kind === "emoji") return `emoji:${value.emoji}`;
+  if (value.kind === "library") {
+    return `library:${value.library}:${value.name}:${value.variant ?? "outline"}:${value.color ?? "default"}`;
+  }
+  return `image:${value.authority}:${value.assetId}`;
+}
+
+export function addResourceIconRecent(
+  recents: readonly ResourceIconValue[],
+  value: ResourceIconValue,
+  limit = RESOURCE_ICON_RECENTS_LIMIT,
+): ResourceIconValue[] {
+  const key = resourceIconKey(value);
+  return [
+    value,
+    ...recents.filter((recent) => resourceIconKey(recent) !== key),
+  ].slice(0, limit);
+}
+
+export function useResourceIconRecents(
+  recents: readonly ResourceIconValue[],
+  onRecentsChange?: (recents: ResourceIconValue[]) => void,
+) {
+  return React.useCallback(
+    (value: ResourceIconValue) => {
+      onRecentsChange?.(addResourceIconRecent(recents, value));
+    },
+    [onRecentsChange, recents],
+  );
+}

package/src/icons/server.tsx

@@ -0,0 +1,53 @@
+import * as React from "react";
+
+import { cn } from "../utils.js";
+import type { ResourceIconProps } from "./ResourceIcon.js";
+
+export * from "./recents.js";
+export * from "./types.js";
+
+export function ResourceIcon({
+  value,
+  size = 20,
+  fallback = null,
+  label,
+  className,
+  resolveImageUrl,
+}: ResourceIconProps) {
+  const accessibility = label
+    ? { role: "img", "aria-label": label }
+    : { "aria-hidden": true as const };
+
+  if (!value) return fallback;
+  if (value.kind === "emoji") {
+    return (
+      <span
+        {...accessibility}
+        className={cn(
+          "inline-flex shrink-0 items-center justify-center",
+          className,
+        )}
+        style={{ fontSize: size, lineHeight: 1 }}
+      >
+        {value.emoji}
+      </span>
+    );
+  }
+  if (value.kind === "image") {
+    const src = resolveImageUrl?.(value);
+    if (!src) return fallback;
+    return (
+      <img
+        src={src}
+        alt={label ?? value.alt ?? ""}
+        className={cn("inline-block shrink-0 object-contain", className)}
+        style={{ width: size, height: size }}
+      />
+    );
+  }
+  return fallback;
+}
+
+export function ResourceIconPicker() {
+  return null;
+}