@tangle-network/ui 11.16.11 → 11.17.0

package/src/primitives/chip.test.tsx

@@ -0,0 +1,178 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import * as React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { Chip } from "./chip";
+import { IconTile, initialsOf } from "./icon-tile";
+import { Tag } from "./tag";
+import { CATEGORY_TONES, TONE_CLASSES, toneFor } from "./tone";
+
+function FilterRow() {
+  const [on, setOn] = React.useState<Record<string, boolean>>({ Drafts: true, Scheduled: false });
+  return (
+    <div>
+      {Object.keys(on).map((name) => (
+        <Chip
+          key={name}
+          selected={on[name]}
+          onSelectedChange={(next) => setOn((prev) => ({ ...prev, [name]: next }))}
+        >
+          {name}
+        </Chip>
+      ))}
+    </div>
+  );
+}
+
+describe("Chip", () => {
+  it("is a native button that runs onClick when it is an action chip", async () => {
+    const onClick = vi.fn();
+    render(<Chip onClick={onClick}>Draft a launch post</Chip>);
+    const chip = screen.getByRole("button", { name: "Draft a launch post" });
+    expect(chip).toHaveAttribute("type", "button");
+    expect(chip).not.toHaveAttribute("aria-pressed");
+    await userEvent.click(chip);
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it("toggles from the keyboard with Space and Enter and reports aria-pressed", async () => {
+    const user = userEvent.setup();
+    render(<FilterRow />);
+    const drafts = screen.getByRole("button", { name: "Drafts" });
+    const scheduled = screen.getByRole("button", { name: "Scheduled" });
+    expect(drafts).toHaveAttribute("aria-pressed", "true");
+    expect(scheduled).toHaveAttribute("aria-pressed", "false");
+
+    await user.tab();
+    expect(drafts).toHaveFocus();
+    await user.keyboard(" ");
+    expect(drafts).toHaveAttribute("aria-pressed", "false");
+
+    await user.tab();
+    expect(scheduled).toHaveFocus();
+    await user.keyboard("{Enter}");
+    expect(scheduled).toHaveAttribute("aria-pressed", "true");
+  });
+
+  // Selection must survive greyscale: the check replaces the icon only when on.
+  it("shows a check glyph only while selected", () => {
+    const { rerender } = render(
+      <Chip selected={false} icon={<svg data-testid="icon" />}>
+        Video
+      </Chip>,
+    );
+    expect(screen.getByTestId("icon")).toBeInTheDocument();
+    expect(document.querySelector(".lucide-check")).toBeNull();
+    rerender(
+      <Chip selected icon={<svg data-testid="icon" />}>
+        Video
+      </Chip>,
+    );
+    expect(screen.queryByTestId("icon")).toBeNull();
+    expect(document.querySelector(".lucide-check")).not.toBeNull();
+  });
+
+  it("does not toggle while disabled", () => {
+    const onSelectedChange = vi.fn();
+    render(
+      <Chip selected={false} disabled onSelectedChange={onSelectedChange}>
+        Archived
+      </Chip>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Archived" }));
+    expect(onSelectedChange).not.toHaveBeenCalled();
+  });
+
+  it("lets a consumer onClick veto the toggle with preventDefault", () => {
+    const onSelectedChange = vi.fn();
+    render(
+      <Chip selected={false} onClick={(e) => e.preventDefault()} onSelectedChange={onSelectedChange}>
+        Locked
+      </Chip>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Locked" }));
+    expect(onSelectedChange).not.toHaveBeenCalled();
+  });
+});
+
+describe("Tag", () => {
+  it("is a static label with no tab stop of its own", async () => {
+    render(<Tag tone="teal">Research</Tag>);
+    expect(screen.getByText("Research")).toBeInTheDocument();
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("removes from the keyboard through a named remove button", async () => {
+    const user = userEvent.setup();
+    const onRemove = vi.fn();
+    render(<Tag onRemove={onRemove}>ada@example.com</Tag>);
+    await user.tab();
+    const remove = screen.getByRole("button", { name: "Remove ada@example.com" });
+    expect(remove).toHaveFocus();
+    await user.keyboard("{Enter}");
+    await user.keyboard(" ");
+    expect(onRemove).toHaveBeenCalledTimes(2);
+  });
+
+  it("takes an explicit remove label when the label is not plain text", () => {
+    render(
+      <Tag onRemove={() => {}} removeLabel="Remove the LinkedIn channel">
+        <strong>LinkedIn</strong>
+      </Tag>,
+    );
+    expect(screen.getByRole("button", { name: "Remove the LinkedIn channel" })).toBeInTheDocument();
+  });
+});
+
+describe("IconTile", () => {
+  it("falls back from a broken image to the glyph, then to initials", () => {
+    const { container, rerender } = render(<IconTile src="https://example.invalid/logo.png" name="Acme Robotics" />);
+    const img = container.querySelector("img");
+    expect(img).not.toBeNull();
+    fireEvent.error(img as HTMLImageElement);
+    expect(container.querySelector("img")).toBeNull();
+    expect(container.textContent).toBe("AR");
+
+    rerender(<IconTile name="Acme Robotics" icon={<svg data-testid="glyph" />} />);
+    expect(screen.getByTestId("glyph")).toBeInTheDocument();
+  });
+
+  it("is decorative unless it is given a label", () => {
+    const { container, rerender } = render(<IconTile name="Acme" />);
+    expect(container.firstElementChild).toHaveAttribute("aria-hidden", "true");
+    rerender(<IconTile name="Acme" label="Acme workspace" />);
+    expect(screen.getByRole("img", { name: "Acme workspace" })).toBeInTheDocument();
+  });
+
+  it.each([
+    ["Acme Robotics", "AR"],
+    ["acme", "AC"],
+    ["jane.doe", "JD"],
+    ["  ", ""],
+    ["李 小龍", "李小"],
+    ["🦊 fox", "🦊F"],
+  ])("derives the initials of %j as %j", (name, initials) => {
+    expect(initialsOf(name)).toBe(initials);
+  });
+});
+
+describe("toneFor", () => {
+  it("gives a key the same categorical tone every time", () => {
+    expect(toneFor("linkedin")).toBe(toneFor("linkedin"));
+    expect(CATEGORY_TONES).toContain(toneFor("linkedin"));
+  });
+
+  it("spreads keys across the categorical set", () => {
+    const used = new Set(Array.from({ length: 64 }, (_, i) => toneFor(`project-${i}`)));
+    expect(used.size).toBe(CATEGORY_TONES.length);
+  });
+
+  // The sandbox-ui style bundle and Tailwind read class names statically, so
+  // every tone's classes must name their own tone's tokens literally.
+  it.each(CATEGORY_TONES)("writes %s's classes against its own tokens", (tone) => {
+    for (const value of Object.values(TONE_CLASSES[tone])) {
+      expect(value).toContain(`--tone-${tone}-`);
+      expect(value).not.toMatch(new RegExp(`--tone-(?!${tone}-)`));
+    }
+  });
+});

package/src/primitives/chip.tsx

@@ -0,0 +1,108 @@
+import { Check } from "lucide-react";
+import * as React from "react";
+import { focusRing } from "../lib/focus";
+import { cn } from "../lib/utils";
+import { TONE_CLASSES, type Tone } from "./tone";
+
+/**
+ * A label the user presses: a native `<button>` shaped like a `Tag`.
+ *
+ * Two kinds, chosen by whether `selected` is passed:
+ *
+ * - **Action** (`selected` omitted): runs `onClick` — a suggested prompt, an
+ *   "add filter" entry point.
+ * - **Filter / toggle** (`selected` is a boolean): a toggle button with
+ *   `aria-pressed`. Pressing it calls `onSelectedChange(!selected)`; the caller
+ *   owns the state. Use it for a set of filters (each independently on or off)
+ *   or a single on/off option such as "Plan first".
+ *
+ * Selection is never shown by colour alone: a selected chip gains a check in
+ * place of its icon, a stronger border and a deeper fill, and assistive tech
+ * reads it from `aria-pressed`.
+ *
+ * For a removable label, use `Tag` with `onRemove`; a button cannot contain a
+ * second button.
+ */
+export interface ChipProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+  children: React.ReactNode;
+  /** Categorical tone, or `neutral` (the default). */
+  tone?: Tone;
+  /** `soft` fills the chip; `outline` keeps only the border until selected. */
+  emphasis?: "soft" | "outline";
+  size?: "sm" | "md";
+  /** Leading glyph, drawn in the tone's icon colour. A selected chip shows a check instead. */
+  icon?: React.ReactNode;
+  /** Makes the chip a toggle button; omit for an action chip. */
+  selected?: boolean;
+  onSelectedChange?: (selected: boolean) => void;
+}
+
+const SIZE = {
+  sm: "h-6 gap-1 px-2 text-xs [&_svg]:size-3",
+  md: "h-8 gap-1.5 px-3 text-sm [&_svg]:size-3.5",
+} as const;
+
+const Chip = React.forwardRef<HTMLButtonElement, ChipProps>(
+  (
+    {
+      className,
+      children,
+      tone = "neutral",
+      emphasis = "soft",
+      size = "sm",
+      icon,
+      selected,
+      onSelectedChange,
+      onClick,
+      type = "button",
+      disabled,
+      ...props
+    },
+    ref,
+  ) => {
+    const classes = TONE_CLASSES[tone];
+    const toggle = selected !== undefined;
+    const on = selected === true;
+    const glyph = on ? <Check /> : icon;
+    return (
+      <button
+        ref={ref}
+        type={type}
+        disabled={disabled}
+        aria-pressed={toggle ? on : undefined}
+        onClick={(event) => {
+          onClick?.(event);
+          if (toggle && !event.defaultPrevented) onSelectedChange?.(!on);
+        }}
+        className={cn(
+          // The pseudo-element widens a small chip's hit area on touch screens
+          // without changing its drawn size or the row's layout.
+          "relative inline-flex min-w-0 max-w-full shrink-0 cursor-pointer select-none items-center rounded-md border font-medium transition-[background-color,border-color,color] duration-150 ease-out before:absolute before:inset-x-0 before:-inset-y-1 before:content-[''] pointer-coarse:before:-inset-y-2.5",
+          SIZE[size],
+          emphasis === "outline" && !on ? classes.outline : classes.surface,
+          // A selected chip keeps its fill under the pointer; the rest-state
+          // hover would read as half-deselecting it.
+          !disabled && !on && classes.hover,
+          on && classes.selected,
+          disabled && "cursor-not-allowed opacity-50",
+          focusRing,
+          className,
+        )}
+        {...props}
+      >
+        {glyph ? (
+          <span aria-hidden="true" className={cn("inline-flex shrink-0", classes.icon)}>
+            {glyph}
+          </span>
+        ) : null}
+        {/* The full text on hover, since a long label truncates. */}
+        <span className="min-w-0 truncate" title={typeof children === "string" ? children : undefined}>
+          {children}
+        </span>
+      </button>
+    );
+  },
+);
+Chip.displayName = "Chip";
+
+export { Chip };

package/src/primitives/icon-tile.stories.tsx

@@ -0,0 +1,74 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Folder, Globe } from "lucide-react";
+import type { ReactNode } from "react";
+import { IconTile } from "./icon-tile";
+
+function BothThemes({ children }: { children: ReactNode }) {
+  return (
+    <div className="grid gap-4 p-4 lg:grid-cols-2">
+      {(["dark", "light"] as const).map((theme) => (
+        <div
+          key={theme}
+          data-theme={theme}
+          className="min-w-0 rounded-xl border border-[var(--border-subtle)] bg-[var(--bg-root)] p-4 text-[var(--text-primary)]"
+        >
+          {children}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// A 1x1 transparent PNG stands in for a loaded logo; the second URL never
+// resolves, so that row shows the fallback a broken favicon gets.
+const LOGO = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=";
+
+const PROJECTS: { name: string; src?: string; icon?: ReactNode; note: string }[] = [
+  { name: "Acme Robotics", src: LOGO, note: "Image" },
+  { name: "Northwind Traders", src: "https://logo.invalid/northwind.png", note: "Broken image → initials" },
+  { name: "Website", icon: <Globe />, note: "Glyph" },
+  { name: "Shared drive", icon: <Folder />, note: "Glyph" },
+  { name: "Quarterly enterprise procurement working group for the EMEA region", note: "Long name → initials" },
+  { name: "x", note: "One letter" },
+  { name: "李 小龍", note: "Non-Latin" },
+];
+
+const meta: Meta<typeof IconTile> = {
+  title: "Primitives/IconTile",
+  component: IconTile,
+  parameters: { layout: "fullscreen" },
+};
+export default meta;
+type Story = StoryObj<typeof IconTile>;
+
+/** A project list: the tone comes from the name, so a project keeps its colour everywhere. */
+export const ProjectList: Story = {
+  render: () => (
+    <BothThemes>
+      <ul className="flex flex-col gap-2">
+        {PROJECTS.map((p) => (
+          <li key={p.name} className="flex min-w-0 items-center gap-3">
+            <IconTile name={p.name} src={p.src} icon={p.icon} />
+            <span className="min-w-0 flex-1 truncate text-sm font-medium">{p.name}</span>
+            <span className="shrink-0 text-xs text-[var(--text-muted)]">{p.note}</span>
+          </li>
+        ))}
+      </ul>
+    </BothThemes>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <BothThemes>
+      <div className="flex items-end gap-3">
+        {(["xs", "sm", "md", "lg"] as const).map((size) => (
+          <IconTile key={size} size={size} name="Tangle Network" />
+        ))}
+        {(["xs", "sm", "md", "lg"] as const).map((size) => (
+          <IconTile key={`g-${size}`} size={size} tone="cyan" icon={<Globe />} />
+        ))}
+      </div>
+    </BothThemes>
+  ),
+};

package/src/primitives/icon-tile.tsx

@@ -0,0 +1,96 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+import { type CategoryTone, TONE_CLASSES, toneFor } from "./tone";
+
+/**
+ * A square identity mark for a row or card: a project, a channel, an account,
+ * a file kind. It shows the first of these that is available:
+ *
+ * 1. `src` — an image (a logo or favicon). If it fails to load, the tile falls
+ *    through to the next option instead of showing a broken image.
+ * 2. `icon` — a glyph, drawn in the tone's icon colour.
+ * 3. `name` — up to two initials.
+ *
+ * The tone is categorical. Omit it to derive a stable one from `name`, so the
+ * same project gets the same colour on every screen. A tile is decorative
+ * unless `label` is given: next to a visible name it would only repeat it.
+ */
+export interface IconTileProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+  /** Defaults to a tone derived from `name`, or violet when there is no name. */
+  tone?: CategoryTone;
+  size?: "xs" | "sm" | "md" | "lg";
+  src?: string;
+  icon?: React.ReactNode;
+  /** The thing's name. Supplies the initials and the derived tone. */
+  name?: string;
+  /** Accessible name. Give it only when no visible label names the thing. */
+  label?: string;
+}
+
+const SIZE = {
+  xs: "size-5 rounded-[5px] text-[10px] [&_svg]:size-3",
+  sm: "size-6 rounded-md text-[11px] [&_svg]:size-3.5",
+  md: "size-8 rounded-md text-xs [&_svg]:size-4",
+  lg: "size-10 rounded-lg text-sm [&_svg]:size-5",
+} as const;
+
+/** Up to two initials: the first letters of the first two words, or of the one word. */
+export function initialsOf(name: string): string {
+  const words = name.trim().split(/[\s._-]+/u).filter(Boolean);
+  if (words.length === 0) return "";
+  // Array.from splits by code point, so an emoji or astral letter stays whole.
+  const first = (word: string) => Array.from(word)[0] ?? "";
+  const letters = words.length === 1 ? Array.from(words[0]).slice(0, 2).join("") : first(words[0]) + first(words[1]);
+  return letters.toLocaleUpperCase();
+}
+
+const IconTile = React.forwardRef<HTMLSpanElement, IconTileProps>(
+  ({ className, tone, size = "md", src, icon, name, label, ...props }, ref) => {
+    const [failedSrc, setFailedSrc] = React.useState<string | null>(null);
+    const imgRef = React.useRef<HTMLImageElement>(null);
+    // A server-rendered image that failed before hydration never fires onError
+    // again, so check it once mounted.
+    React.useEffect(() => {
+      const img = imgRef.current;
+      if (img?.complete && img.naturalWidth === 0 && src) setFailedSrc(src);
+    }, [src]);
+    const resolvedTone = tone ?? (name ? toneFor(name) : "violet");
+    const classes = TONE_CLASSES[resolvedTone];
+    const showImage = Boolean(src) && failedSrc !== src;
+    const initials = name ? initialsOf(name) : "";
+    return (
+      <span
+        ref={ref}
+        role={label ? "img" : undefined}
+        aria-label={label}
+        aria-hidden={label ? undefined : true}
+        className={cn(
+          "inline-flex shrink-0 select-none items-center justify-center overflow-hidden border font-semibold",
+          SIZE[size],
+          showImage ? "border-[var(--border-subtle)] bg-[var(--surface-neutral-bg)]" : classes.surface,
+          !showImage && icon ? classes.icon : null,
+          className,
+        )}
+        {...props}
+      >
+        {showImage ? (
+          <img
+            ref={imgRef}
+            src={src}
+            alt=""
+            className="size-full object-cover"
+            onError={() => setFailedSrc(src ?? null)}
+            draggable={false}
+          />
+        ) : icon ? (
+          icon
+        ) : (
+          initials
+        )}
+      </span>
+    );
+  },
+);
+IconTile.displayName = "IconTile";
+
+export { IconTile };

package/src/primitives/index.ts

@@ -136,6 +136,18 @@ export type { PageHeaderProps } from "./page-header";
 export { StatusPill } from "./status-pill";
 export type { StatusPillProps, StatusTone } from "./status-pill";
 
+export { Tag } from "./tag";
+export type { TagProps } from "./tag";
+
+export { Chip } from "./chip";
+export type { ChipProps } from "./chip";
+
+export { IconTile, initialsOf } from "./icon-tile";
+export type { IconTileProps } from "./icon-tile";
+
+export { CATEGORY_TONES, TONE_CLASSES, toneFor } from "./tone";
+export type { CategoryTone, Tone, ToneClasses } from "./tone";
+
 export { MetricStrip, Metric } from "./metric-strip";
 export type { MetricStripProps, MetricProps } from "./metric-strip";