feat(badge): support array values in DescriptionCard and unify badge interface

- DescriptionCard badge field now accepts array values, rendering multiple badges
- Extract shared BadgeVariant type and BadgeOptions interface into badge-utils.ts
- DataTable's BadgeCellOptions now extends shared BadgeOptions
- Add badgeLabelMap and defaultBadgeVariant to DescriptionCard FieldMeta
- Deprecate BadgeVariantType in favor of shared BadgeVariant
- Add resolveBadgeVariant/resolveBadgeLabel shared utilities
- Add example of array badge usage in vite-app

Author: IzumiSy

examples/vite-app/src/pages/dashboard/orders/[id]/page.tsx

@@ -68,6 +68,7 @@ const OrderDetailPage = () => {
   const orderData = {
     orderId: id,
     status: "processing",
+    tags: ["wholesale", "priority", "fragile"],
     customer: "Acme Corporation",
     totalAmount: 3450.0,
     currency: "USD",
@@ -109,6 +110,18 @@ const OrderDetailPage = () => {
                 },
               },
             },
+            {
+              key: "tags",
+              label: "Tags",
+              type: "badge",
+              meta: {
+                badgeVariantMap: {
+                  wholesale: "outline-info",
+                  priority: "error",
+                  fragile: "warning",
+                },
+              },
+            },
             { key: "customer", label: "Customer" },
             {
               key: "totalAmount",

packages/core/src/components/badge-utils.ts

@@ -0,0 +1,53 @@
+import type { BadgeProps } from "./badge";
+
+/**
+ * Variant union accepted by the app-shell `<Badge>` component.
+ * Shared across DataTable, DescriptionCard, and any other badge consumers.
+ */
+export type BadgeVariant = NonNullable<BadgeProps["variant"]>;
+
+/**
+ * Common options for badge rendering.
+ */
+export interface BadgeOptions {
+  /**
+   * Maps each value (stringified) to a Badge variant. Values not in the
+   * map fall back to `defaultBadgeVariant`.
+   */
+  badgeVariantMap?: Record<string, BadgeVariant>;
+  /**
+   * Maps each value (stringified) to a display label. Values not in the
+   * map render the raw value (or sentence-cased value if enabled).
+   */
+  badgeLabelMap?: Record<string, string>;
+  /** Variant used when the value is not in `badgeVariantMap`. Default: `"neutral"`. */
+  defaultBadgeVariant?: BadgeVariant;
+}
+
+/**
+ * Resolve badge variant for a given value string.
+ * Supports case-insensitive lookup as a fallback.
+ */
+export function resolveBadgeVariant(
+  value: string,
+  options: BadgeOptions | undefined,
+): BadgeVariant {
+  const map = options?.badgeVariantMap;
+  if (map) {
+    const direct = map[value];
+    if (direct) return direct;
+    const lower = map[value.toLowerCase()];
+    if (lower) return lower;
+  }
+  return options?.defaultBadgeVariant ?? "neutral";
+}
+
+/**
+ * Resolve badge display label for a given value string.
+ */
+export function resolveBadgeLabel(
+  value: string,
+  options: BadgeOptions | undefined,
+): string | undefined {
+  return options?.badgeLabelMap?.[value];
+}

packages/core/src/components/data-table/cell-renderers.tsx

@@ -1,9 +1,9 @@
 import type { ReactNode } from "react";
 import { Link } from "react-router";
 import { Badge } from "@/components/badge";
+import { resolveBadgeVariant, resolveBadgeLabel } from "@/components/badge-utils";
 import type {
   BadgeCellOptions,
-  BadgeVariant,
   Column,
   DateCellOptions,
   LinkCellOptions,
@@ -79,7 +79,10 @@ function renderMoney<TRow extends Record<string, unknown>>(
   // `maxDecimals` raises the cap above the currency default while keeping the
   // minimum at the currency default (e.g. 2 for USD). Lets a JPY column stay
   // at 0 decimals while a USD price-detail column shows up to 4.
-  const formatOptions: Intl.NumberFormatOptions = { style: "currency", currency };
+  const formatOptions: Intl.NumberFormatOptions = {
+    style: "currency",
+    currency,
+  };
   if (options?.maxDecimals != null) {
     formatOptions.maximumFractionDigits = options.maxDecimals;
   }
@@ -119,9 +122,8 @@ function renderDate(value: unknown, options: DateCellOptions | undefined): React
 function renderBadge(value: unknown, options: BadgeCellOptions | undefined): ReactNode {
   if (isEmpty(value)) return PLACEHOLDER;
   const key = String(value);
-  const variant: BadgeVariant =
-    options?.badgeVariantMap?.[key] ?? options?.defaultBadgeVariant ?? "neutral";
-  const label = options?.badgeLabelMap?.[key] ?? key;
+  const variant = resolveBadgeVariant(key, options);
+  const label = resolveBadgeLabel(key, options) ?? key;
   return <Badge variant={variant}>{label}</Badge>;
 }
 

packages/core/src/components/data-table/types.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { BadgeProps } from "@/components/badge";
+import type { BadgeOptions } from "@/components/badge-utils";
 import type {
   CollectionControl,
   Filter,
@@ -28,8 +28,7 @@ import type {
  */
 export type ColumnCellType = "text" | "number" | "money" | "date" | "badge" | "link";
 
-/** Variant union accepted by the app-shell `<Badge>` component. */
-export type BadgeVariant = NonNullable<BadgeProps["variant"]>;
+export type { BadgeVariant } from "@/components/badge-utils";
 
 /** Options for `type: "number"` cells. */
 export interface NumberCellOptions {
@@ -70,20 +69,7 @@ export interface DateCellOptions {
 }
 
 /** Options for `type: "badge"` cells. */
-export interface BadgeCellOptions {
-  /**
-   * Maps each cell value (stringified) to a Badge variant. Values not in the
-   * map fall back to `defaultBadgeVariant`.
-   */
-  badgeVariantMap?: Record<string, BadgeVariant>;
-  /**
-   * Maps each cell value (stringified) to a display label. Values not in the
-   * map render the raw cell value.
-   */
-  badgeLabelMap?: Record<string, string>;
-  /** Variant used when the value is not in `badgeVariantMap`. Default: `"neutral"`. */
-  defaultBadgeVariant?: BadgeVariant;
-}
+export interface BadgeCellOptions extends BadgeOptions {}
 
 /** Options for `type: "link"` cells. `href` is required. */
 export interface LinkCellOptions<TRow extends Record<string, unknown>> {

packages/core/src/components/description-card/DescriptionCard.test.tsx

@@ -42,4 +42,32 @@ describe("DescriptionCard", () => {
 
     expect(screen.getByText("NOT_RECEIVED")).toBeDefined();
   });
+
+  it("renders multiple badges from array value", () => {
+    render(
+      <DescriptionCard
+        title="Order"
+        data={{ tags: ["urgent", "fragile", "international"] }}
+        fields={[
+          {
+            key: "tags",
+            label: "Tags",
+            type: "badge",
+            meta: {
+              badgeVariantMap: {
+                urgent: "error",
+                fragile: "warning",
+                international: "outline-info",
+              },
+            },
+          },
+        ]}
+      />,
+      { wrapper },
+    );
+
+    expect(screen.getByText("Urgent")).toBeDefined();
+    expect(screen.getByText("Fragile")).toBeDefined();
+    expect(screen.getByText("International")).toBeDefined();
+  });
 });

packages/core/src/components/description-card/field-renderers.test.tsx

@@ -53,6 +53,42 @@ describe("renderField", () => {
       const { container } = render(renderField(makeField({ type: "badge", value: null })));
       expect(container.textContent).toBe("–");
     });
+
+    it("renders multiple badges from array value", () => {
+      const { container } = render(
+        renderField(makeField({ type: "badge", value: ["urgent", "fragile"] })),
+      );
+      expect(container.textContent).toContain("Urgent");
+      expect(container.textContent).toContain("Fragile");
+    });
+
+    it("renders multiple badges with variant map", () => {
+      const { container } = render(
+        renderField(
+          makeField({
+            type: "badge",
+            value: ["urgent", "low"],
+            meta: { badgeVariantMap: { urgent: "error", low: "neutral" } },
+          }),
+        ),
+      );
+      expect(container.textContent).toContain("Urgent");
+      expect(container.textContent).toContain("Low");
+    });
+
+    it("renders dash for empty array", () => {
+      const { container } = render(renderField(makeField({ type: "badge", value: [] })));
+      expect(container.textContent).toBe("–");
+    });
+
+    it("skips null values in array", () => {
+      const { container } = render(
+        renderField(makeField({ type: "badge", value: ["active", null, "featured"] })),
+      );
+      expect(container.textContent).toContain("Active");
+      expect(container.textContent).toContain("Featured");
+      expect(container.textContent).not.toContain("–");
+    });
   });
 
   describe("date", () => {

packages/core/src/components/description-card/field-renderers.tsx

@@ -5,7 +5,9 @@ import { Link } from "react-router";
 import { Badge } from "../badge";
 import { Tooltip } from "../tooltip";
 import { Copy, Check, ExternalLink } from "lucide-react";
-import type { ResolvedField, DateFormat, BadgeVariantType } from "./types";
+import type { ResolvedField, DateFormat } from "./types";
+import type { BadgeVariant } from "../badge-utils";
+import { resolveBadgeVariant, resolveBadgeLabel } from "../badge-utils";
 import { useDescriptionCardT } from "./i18n";
 
 // ============================================================================
@@ -335,25 +337,38 @@ function TextFieldRenderer({ field }: { field: ResolvedField }) {
  * Render a badge field
  */
 function BadgeFieldRenderer({ field }: { field: ResolvedField }) {
-  if (isEmpty(field.value)) {
+  const values = Array.isArray(field.value)
+    ? (field.value as unknown[])
+    : field.value != null
+      ? [field.value]
+      : [];
+
+  if (values.every((v) => isEmpty(v))) {
     return <span className="astw:text-sm astw:font-medium astw:text-foreground">{EMPTY_DASH}</span>;
   }
 
-  const value = String(field.value);
-  const variantMap = field.meta?.badgeVariantMap || {};
+  const badgeOptions = {
+    badgeVariantMap: field.meta?.badgeVariantMap,
+    badgeLabelMap: field.meta?.badgeLabelMap,
+    defaultBadgeVariant: field.meta?.defaultBadgeVariant ?? ("outline-neutral" as BadgeVariant),
+  };
   const sentenceCaseBadges = field.meta?.sentenceCaseBadges ?? true;
 
-  // Try to find a matching variant (case-insensitive)
-  const lowerValue = value.toLowerCase();
-  const variant: BadgeVariantType =
-    variantMap[value] || variantMap[lowerValue] || "outline-neutral";
-  const displayValue = sentenceCaseBadges ? toSentenceCase(value) : value;
+  const badges = values
+    .filter((v) => !isEmpty(v))
+    .map((raw, i) => {
+      const value = String(raw);
+      const variant = resolveBadgeVariant(value, badgeOptions);
+      const label = resolveBadgeLabel(value, badgeOptions);
+      const displayValue = label ?? (sentenceCaseBadges ? toSentenceCase(value) : value);
+      return (
+        <Badge key={i} variant={variant} className="astw:w-fit">
+          {displayValue}
+        </Badge>
+      );
+    });
 
-  return (
-    <Badge variant={variant} className="astw:w-fit">
-      {displayValue}
-    </Badge>
-  );
+  return <div className="astw:flex astw:flex-wrap astw:gap-1">{badges}</div>;
 }
 
 /**

packages/core/src/components/description-card/index.ts

@@ -17,3 +17,5 @@ export type {
   DateFormat,
   BadgeVariantType,
 } from "./types";
+
+export type { BadgeVariant } from "../badge-utils";

packages/core/src/components/description-card/types.ts

@@ -1,4 +1,5 @@
 import type { CSSProperties, ReactNode } from "react";
+import type { BadgeVariant } from "../badge-utils";
 
 // ============================================================================
 // FIELD TYPES
@@ -10,22 +11,9 @@ import type { CSSProperties, ReactNode } from "react";
 export type FieldType = "text" | "badge" | "money" | "date" | "link" | "address" | "reference";
 
 /**
- * Badge variant mapping for automatic status coloring
+ * @deprecated Use `BadgeVariant` from `@tailor-platform/app-shell` instead.
  */
-export type BadgeVariantType =
-  | "default"
-  | "success"
-  | "warning"
-  | "error"
-  | "neutral"
-  | "subtle-success"
-  | "subtle-warning"
-  | "subtle-error"
-  | "outline-success"
-  | "outline-warning"
-  | "outline-error"
-  | "outline-info"
-  | "outline-neutral";
+export type BadgeVariantType = BadgeVariant;
 
 /**
  * Behavior when a field value is empty/null/undefined
@@ -48,7 +36,14 @@ export interface FieldMeta {
   /** Show copy button for this field */
   copyable?: boolean;
   /** Map field values to badge variants */
-  badgeVariantMap?: Record<string, BadgeVariantType>;
+  badgeVariantMap?: Record<string, BadgeVariant>;
+  /**
+   * Maps each value (stringified) to a display label. Values not in the
+   * map render the raw value (or sentence-cased value if enabled).
+   */
+  badgeLabelMap?: Record<string, string>;
+  /** Variant used when the value is not in `badgeVariantMap`. Default: `"outline-neutral"`. */
+  defaultBadgeVariant?: BadgeVariant;
   /** Render badge labels in sentence case by default; set false to keep the original value */
   sentenceCaseBadges?: boolean;
   /** Key path to currency code in data object (for money fields) */

packages/core/src/index.ts

@@ -84,6 +84,7 @@ export { useOverrideBreadcrumb } from "./hooks/use-override-breadcrumb";
 
 // Components
 export { Badge, badgeVariants, type BadgeProps } from "./components/badge";
+export type { BadgeVariant, BadgeOptions } from "./components/badge-utils";
 export { DescriptionCard, type DescriptionCardProps } from "./components/description-card";
 export {
   ActivityCard,