Detail Views

import { defineCollection, defineTextField } from "@dyrected/core";

export const Pages = defineCollection({
  slug: "pages",
  labels: { singular: "Page", plural: "Pages" },
  admin: {
    useAsTitle: "title",
  },
  detail: false,
  fields: [
    defineTextField({ name: "title", label: "Title", required: true }),
    defineTextField({ name: "slug", label: "Slug", required: true, unique: true }),
  ],
});

import {
  defineCollection,
  defineNumberField,
  defineSelectField,
  defineTextareaField,
  defineTextField,
  displayField,
  displaySection,
} from "@dyrected/core";

export const Products = defineCollection({
  slug: "products",
  labels: { singular: "Product", plural: "Products" },
  admin: {
    useAsTitle: "title",
    defaultColumns: ["title", "sku", "price", "status"],
  },
  detail: [
    displaySection(
      "Product Overview",
      [
        displayField("title", { span: 8 }),
        displayField("sku", { span: 4, display: "copyable" }),
        displayField("description", { span: 12 }),
      ],
      { span: 8, icon: "Package" },
    ),
    displaySection(
      "Pricing & Status",
      [
        displayField("price", { span: 6, display: "currency", currency: "USD", editable: true }),
        displayField("status", {
          span: 6,
          display: "badge",
          badgeColors: { active: "emerald", draft: "zinc", archived: "rose" },
          editable: true,
        }),
      ],
      { span: 4, badge: "Live", badgeColor: "emerald" },
    ),
  ],
  fields: [
    defineTextField({ name: "title", label: "Title", required: true }),
    defineTextField({ name: "sku", label: "SKU", required: true }),
    defineTextareaField({ name: "description", label: "Description" }),
    defineNumberField({ name: "price", label: "Price", required: true }),
    defineSelectField({
      name: "status",
      label: "Status",
      options: [
        { label: "Active", value: "active" },
        { label: "Draft", value: "draft" },
        { label: "Archived", value: "archived" },
      ],
      defaultValue: "draft",
    }),
  ],
});

import {
  defineArrayField,
  defineEmailField,
  defineGlobal,
  defineNumberField,
  defineTextField,
  defineUrlField,
  displayComputed,
  displayField,
  displaySection,
} from "@dyrected/core";

export const SiteSettings = defineGlobal({
  slug: "site-settings",
  label: "Site Settings",
  detail: [
    displaySection(
      "Identity & Contact",
      [
        displayField("siteName", { span: 6, editable: true }),
        displayField("supportEmail", { span: 6, display: "email", editable: true }),
        displayField("rating", { span: 6, display: "star-rating" }),
        displayField("primaryIcon", { span: 6, display: "icon" }),
      ],
      { span: 8, icon: "Settings" },
    ),
    displaySection(
      "Quick Stats",
      [displayComputed("Total Social Links", "count(doc.socialLinks)", { span: 12 })],
      { span: 4 },
    ),
  ],
  fields: [
    defineTextField({ name: "siteName", label: "Site Name", required: true }),
    defineEmailField({ name: "supportEmail", label: "Support Email", required: true }),
    defineNumberField({ name: "rating", label: "Customer Rating", defaultValue: 5 }),
    defineTextField({ name: "primaryIcon", label: "Primary Icon", defaultValue: "Globe" }),
    defineArrayField({
      name: "socialLinks",
      label: "Social Links",
      fields: [
        defineTextField({ name: "platform", label: "Platform" }),
        defineUrlField({ name: "url", label: "URL" }),
      ],
    }),
  ],
});

displayField("internalNotes", {
  label: "Internal Reviewer Notes",
  span: 12,
  editable: true,
})
displayField("stock", {
  label: "Available Units",
  span: 6,
  editable: true,
})
displayField("accentColor", {
  label: "Theme Accent",
  span: 6,
  display: "color",
  editable: true,
})

displayField("orderStatus", {
  display: "badge",
  badgeColors: {
    delivered: "emerald",
    processing: "sky",
    pending: "amber",
    cancelled: "rose",
    "*": "zinc", // Fallback color for any other value
  },
})

displaySection(
  "Publishing Status",
  [
    displayField("status", { span: 6, display: "badge" }),
    displayField("publishedAt", { span: 6, display: "relative" }),
  ],
  {
    span: 12,
    icon: "CalendarCheck",
    badge: "Verified",
    badgeColor: "emerald",
    description: "Review publication state before scheduling social campaigns.",
    collapsible: true,
    collapsedByDefault: false,
  },
);

displayTabs(
  [
    displayTab("Specifications", [
      displayField("dimensions", { span: 6 }),
      displayField("weight", { span: 6 }),
    ], { icon: "Cpu" }),

    displayTab("Reviews", [
      displayRepeat("reviews", [
        displayField("reviewer", { span: 6 }),
        displayField("rating", { span: 6, display: "star-rating" }),
        displayField("comment", { span: 12 }),
      ], { layout: "cards" }),
    ], {
      icon: "Star",
      badge: "count(doc.reviews)",
      badgeColor: "amber",
    }),
  ],
  { span: 12, defaultTab: "Specifications" },
);

displayGrid(
  3,
  [
    displayField("views", { display: "number" }),
    displayField("conversionRate", { display: "percent" }),
    displayField("featured", { display: "boolean" }),
  ],
  { span: 12 },
);

displayField("author.name", { label: "Author", span: 6 });
displayField("price", { display: "currency", currency: "USD", span: 6 });
displayField("rating", { display: "star-rating", span: 6 });
displayField("brandColor", { display: "color", span: 6 });
displayField("palette", { display: "color-swatches", span: 12 });
displayField("apiSecret", { display: "copyable", span: 6 });
displayField("coverImage", { display: "image", aspectRatio: "16/9", objectFit: "cover", align: "center", span: 12 });

displayComputed("Total Categories", "count(doc.categories)", { span: 6 });
displayComputed("Estimated Profit", "doc.price - doc.cost", {
  span: 6,
  format: "currency",
  currency: "USD",
});

displayRepeat(
  "orderItems",
  [
    displayField("productName", { span: 6 }),
    displayField("quantity", { span: 3 }),
    displayField("price", { span: 3, display: "currency" }),
  ],
  {
    layout: "cards",
    columns: 3,
    useAsTitle: "productName",
    emptyText: "No line items in this order",
  },
);

import { displayDivider, displayText } from "@dyrected/core";

export const reviewNotice = [
  displayText("Verify shipping addresses before changing order status to Shipped.", {
    variant: "warning",
    span: 12,
  }),
  displayDivider({ spacing: "md" }),
];

displayCustom("CustomerAnalyticsChart", {
  span: 12,
  props: { period: "30d" },
})

displaySection(
  "Financial Summary",
  [
    displayField("totalRevenue", { span: 6, display: "currency" }),
    displayField("auditNotes", {
      span: 6,
      visible: "user.roles != null and includes(user.roles, 'admin')",
    }),
  ],
  {
    span: 12,
    visible: "doc.status == 'published'",
  },
);

// Tightly grouped 4-column summary bar across desktop; reflows smoothly on mobile
displayGrid(4, [
  displayField("status", {
    display: "badge",
    badgeColors: { active: "emerald", draft: "zinc", archived: "rose" },
    label: "Status",
  }),
  displayField("priority", { display: "badge", label: "Priority" }),
  displayField("phone", { display: "phone", label: "Phone" }),
  displayField("email", { display: "email", label: "Email" }),
]),

// Hero actions placed directly below the top identity strip
displayCustomComponent("AccessCardPreview"),
displayCustomComponent("SendWhatsAppButton"),

displayField("paymentStatus", {
  display: "badge",
  badgeColors: { received: "emerald", pending: "amber", waived: "purple" },
  editable: true,
}),
displayField("deliveryNotes", {
  editable: true,
  hideIfEmpty: true,
}),

// Hide the entire fulfillment card if the guest didn't place an order
displaySection("Order & Fulfillment", [
  // ... fields
], {
  span: 12,
  icon: "Package",
  visible: "doc.wantsAsoebi || doc.wantsAsoOke",
}),

import { displayField } from "@dyrected/core";

displayField("status", {
  label: "Publication Status",
  display: "badge",
  badgeColors: {
    published: "emerald",
    draft: "zinc",
    archived: "rose",
  },
  editable: true,
});

import { displaySection, displayField } from "@dyrected/core";

displaySection("Inventory & Pricing", [
  displayField("sku", { span: 4, display: "copyable" }),
  displayField("price", { span: 4, display: "currency" }),
  displayField("stock", { span: 4, editable: true }),
], {
  icon: "Package",
  badge: "In Stock",
  badgeColor: "emerald",
  collapsible: true,
  columns: 12,
});

import { displayTabs, displayTab, displayField, displayRepeat } from "@dyrected/core";

displayTabs([
  displayTab("Overview", [
    displayField("description"),
    displayField("features"),
  ], { icon: "FileText" }),

  displayTab("Orders", [
    displayRepeat("orders", [
      displayField("orderNumber"),
      displayField("total", { display: "currency" }),
    ], { layout: "table" }),
  ], { icon: "ShoppingCart", badge: "12", badgeColor: "blue" }),
], { span: 12, defaultTab: "Overview" });

import { displayGrid, displayField } from "@dyrected/core";

displayGrid(3, [
  displayField("city"),
  displayField("state"),
  displayField("postalCode"),
], { span: 12 });

import { displayRepeat, displayField } from "@dyrected/core";

displayRepeat("orderItems", [
  displayField("productName", { span: 6 }),
  displayField("quantity", { span: 3 }),
  displayField("unitPrice", { span: 3, display: "currency" }),
], {
  layout: "cards",
  columns: 3,
  useAsTitle: "productName",
  emptyText: "No items in this order",
});

import { displayComputed } from "@dyrected/core";

// JEXL string expression
displayComputed("Estimated Reading Time", 'math.ceil(doc.wordCount / 200) + " min"', {
  span: 4,
});

// Function handler with currency formatting
displayComputed("Grand Total", ({ doc }) => doc.subtotal + doc.tax, {
  span: 4,
  format: "currency",
  currency: "USD",
});

import { displayText } from "@dyrected/core";

displayText("Changes to this customer tier will affect monthly billing immediately.", {
  variant: "warning",
  span: 12,
});

import { displayDivider } from "@dyrected/core";

displayDivider({ spacing: "lg" });

import { displayCustom } from "@dyrected/core";

displayCustom("RevenueChart", {
  props: { timeframe: "30d", showLegend: true },
  span: 12,
});

export type ComputedHandler<TDoc = any> = (context: { doc: TDoc; user?: any; db?: any }) => any | Promise<any>;

export interface DetailComputed<TDoc = any> {
  /** Identifies this item as a computed value. */
  type: "computed";
  /** Unique computed identifier. */
  id?: string;
  /** Human-readable card label. */
  label: string;
  /** JEXL evaluation string. */
  expression?: string;
  /** Computed function handler. */
  handler?: ComputedHandler<TDoc>;
  /** Computed options. */
  options?: DetailComputedOptions<TDoc>;
}

export interface DetailComputedOptions<TDoc = any> {
  /** Unique identifier for the computed metric. */
  id?: string;
  /** JEXL expression string evaluated against `{ doc, user }`. */
  expression?: string;
  /** Async or sync function receiving `{ doc, user, db }` returning the computed value. */
  handler?: ComputedHandler<TDoc>;
  /** Grid width for the computed card. */
  span?: DetailSpan;
  /** Formatting preset for the computed value ('currency', 'percent', 'number', 'date'). */
  format?: string;
  /** Currency code when format is 'currency'. */
  currency?: string;
  /**
   * Visibility condition for this computed card.
   * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
   */
  visible?: string | boolean;
}

export interface DetailCustom<TDoc = any> {
  /** Identifies this item as a custom component. */
  type: "custom";
  /** Registered custom component name. */
  name: string;
  /** Custom component options. */
  options?: DetailCustomOptions<TDoc>;
}

export interface DetailCustomOptions<TDoc = any> {
  /** Grid span in the 12-column layout. */
  span?: DetailSpan;
  /**
   * Visibility condition for this custom component.
   * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
   */
  visible?: string | boolean;
  /** Static or initial props passed into the custom component. */
  props?: Record<string, any>;
  /** Inline render function receiving `{ doc, user }` (Self-hosted React runtimes). */
  render?: (context: { doc: TDoc; user?: any; [key: string]: any }) => any;
}

export interface DetailDivider {
  /** Identifies this item as a divider. */
  type: "divider";
  /** Divider options. */
  options?: DetailDividerOptions;
}

export interface DetailDividerOptions {
  /** Grid span in the surrounding layout. */
  span?: DetailSpan;
  /**
   * Visibility condition for this divider.
   * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
   */
  visible?: string | boolean;
  /** Vertical margin spacing around the divider line. */
  spacing?: "sm" | "md" | "lg" | "none";
}

export interface DetailField {
  /** Identifies this item as a field. */
  type: "field";
  /** Field name or nested path in the document. */
  field: string;
  /** Display options for this field. */
  options?: DisplayFieldOptions;
}

export interface DetailGrid {
  /** Identifies this item as a grid. */
  type: "grid";
  /** Number of balanced columns in this grid. */
  columns: number;
  /** Child items rendered across the grid columns. */
  items: DetailItem[];
  /** Grid container options. */
  options?: DetailGridOptions;
}

export interface DetailGridOptions {
  /** Grid width of the sub-grid container in the surrounding layout. */
  span?: DetailSpan;
  /**
   * Visibility condition for this grid container.
   * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
   */
  visible?: string | boolean;
}

export type DetailItem<TDoc = any> =
  | DetailSection
  | DetailTabs
  | DetailGrid
  | DetailField
  | DetailRepeat
  | DetailComputed<TDoc>
  | DetailDivider
  | DetailText
  | DetailCustom<TDoc>
  | string;

export interface DetailRepeat {
  /** Identifies this item as a repeat container. */
  type: "repeat";
  /** Array field name in the document. */
  field: string;
  /** Item template schemas rendered for each element in the array. */
  items: DetailItem[];
  /** Repeat options. */
  options?: DetailRepeatOptions;
}

export interface DetailRepeatOptions {
  /** Layout style for repeated items: 'table', 'cards', or 'list'. */
  layout?: "table" | "cards" | "list";
  /** Message shown when the repeated array is empty. */
  emptyText?: string;
  /** Grid width of the repeated container. */
  span?: DetailSpan;
  /**
   * Visibility condition for this repeat container.
   * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
   */
  visible?: string | boolean;
  /** Field name in each row to use as the card header title (e.g. 'title', 'key', 'name'). */
  useAsTitle?: string;
  /** Field name in each row to use as the card header title (alias for useAsTitle). */
  titleField?: string;
  /** Static card title prefix or template (e.g. 'Category' or 'Card #{index}'). */
  title?: string;
  /** Optional icon name for card header. */
  icon?: string;
  /** Number of grid columns for cards layout (1, 2, 3, or 4; defaults to 3). */
  columns?: 1 | 2 | 3 | 4;
}

export type DetailSchema<TDoc = any> = DetailItem<TDoc>[];

export interface DetailSection {
  /** Identifies this item as a section. */
  type: "section";
  /** Section heading title. */
  title: string;
  /** Child items rendered inside this section. */
  items: DetailItem[];
  /** Section container options. */
  options?: DetailSectionOptions;
}

export interface DetailSectionOptions {
  /** Lucide icon name displayed in the section header. */
  icon?: string;
  /** Status or counter badge displayed beside the section title. */
  badge?: string;
  /** Color palette name or hex code for the section badge. */
  badgeColor?: string;
  /** Subtitle description displayed beneath the section title. */
  description?: string;
  /** Grid width of the section on the main 12-column layout. */
  span?: DetailSpan;
  /** Internal grid column count for child items. */
  columns?: number;
  /** When true, allows editors to collapse and expand the section. */
  collapsible?: boolean;
  /** Starts the section in collapsed state when collapsible is enabled. */
  collapsedByDefault?: boolean;
  /**
   * Visibility condition for this section.
   * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
   *
   * @example `visible: "user.roles != null and 'admin' in user.roles"`
   */
  visible?: string | boolean;
}

export type DetailSpan = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;

export interface DetailTab {
  /** Identifies this item as a tab. */
  type: "tab";
  /** Tab label shown in the tab bar. */
  label: string;
  /** Child items rendered when this tab is active. */
  items: DetailItem[];
  /** Tab options. */
  options?: DetailTabOptions;
}

export interface DetailTabOptions {
  /** Lucide icon name displayed inside the tab trigger. */
  icon?: string;
  /** Counter or status badge rendered next to the tab label. */
  badge?: string;
  /** Color palette name or hex code for the tab badge. */
  badgeColor?: string;
  /**
   * Visibility condition for this individual tab.
   * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
   */
  visible?: string | boolean;
}

export interface DetailTabs {
  /** Identifies this item as a tab container. */
  type: "tabs";
  /** List of tabs in this container. */
  tabs: DetailTab[];
  /** Tab container options. */
  options?: DetailTabsOptions;
}

export interface DetailTabsOptions {
  /** Grid width of the tabs container on the main layout. */
  span?: DetailSpan;
  /** Label of the tab that should be active on initial render. */
  defaultTab?: string;
  /**
   * Visibility condition for this tab container.
   * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
   */
  visible?: string | boolean;
}

export interface DetailText {
  /** Identifies this item as a text block. */
  type: "text";
  /** Text or markdown content. */
  content: string;
  /** Text options. */
  options?: DetailTextOptions;
}

export interface DetailTextOptions {
  /** Grid width in the 12-column layout. */
  span?: DetailSpan;
  /**
   * Visibility condition for this text block.
   * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
   */
  visible?: string | boolean;
  /** Typography and alert styling variant ('body', 'heading', 'subheading', 'muted', 'caption', 'callout', 'info', 'warning'). */
  variant?: "body" | "heading" | "subheading" | "muted" | "caption" | "callout" | "info" | "warning";
  /** Custom CSS or Tailwind classes applied to the text wrapper. */
  className?: string;
}

export function displayComputed<TDoc = any>(
  label: string,
  expressionOrOptionsOrHandler: string | DetailComputedOptions<TDoc> | ComputedHandler<TDoc>,
  options?: DetailComputedOptions<TDoc>,
): DetailComputed<TDoc>

export function displayCustom<TDoc = any>(name: string, options?: DetailCustomOptions<TDoc>): DetailCustom<TDoc>

export function displayCustomComponent<TDoc = any>(
  name: string,
  options?: DetailCustomOptions<TDoc>,
): DetailCustom<TDoc>

export function displayDivider(options?: DetailDividerOptions): DetailDivider

export function displayField(fieldName: string, options?: DisplayFieldOptions): DetailField

export interface DisplayFieldOptions {
  /** Custom label overriding the field's schema label. */
  label?: string;
  /** When true, hides the field label entirely and renders only the value. */
  hideLabel?: boolean;
  /** Informational tooltip shown next to the label. */
  tooltip?: string;
  /** Grid column span across the 12-column grid. */
  span?: DetailSpan;
  /** Specific visual representation variant (e.g. 'badge', 'currency', 'star', 'copyable'). */
  display?: DisplayVariant;
  /** Preset format for numbers, dates, and currencies ('currency', 'date', 'datetime', 'relative', 'number', 'percent'). */
  format?: "currency" | "date" | "datetime" | "relative" | "number" | "percent" | string;
  /** ISO currency code (e.g. 'USD', 'EUR') when display or format is 'currency'. */
  currency?: string;
  /** Color mapping for badge and tag values (named palette, hex color, Tailwind class, or wildcard). */
  badgeColors?: Record<string, string>;
  /** Column header for object keys when display is 'key-value'. */
  keyLabel?: string;
  /** Column header for object values when display is 'key-value'. */
  valueLabel?: string;
  /** Custom placeholder text when the field value is null, undefined, or empty. */
  emptyText?: string;
  /** When true, hides this entire field item if the value is null or empty. */
  hideIfEmpty?: boolean;
  /**
   * When true, allows inline editing of this field in the Detail View
   * via an interactive toggle.
   */
  editable?: boolean;
  /**
   * Visibility condition for this field item.
   * Can be a boolean or a JEXL expression evaluated against `{ doc, user }`.
   * When false or evaluating to falsy, this item is hidden in the Detail View.
   *
   * @example `visible: "doc.status == 'published'"`
   * @example `visible: false`
   */
  visible?: string | boolean;
  /** Specific aspect ratio constraint for media (e.g., "16/9", "4/3", "1/1", "auto"). */
  aspectRatio?: string;
  /** CSS object-fit behavior for media ('cover', 'contain', 'fill', 'scale-down'). */
  objectFit?: "cover" | "contain" | "fill" | "scale-down";
  /** Media alignment ('left', 'center', 'right'). */
  align?: "left" | "center" | "right";
  /** Fixed pixel width or CSS dimension for media preview. */
  width?: string | number;
  /** Fixed pixel height or CSS dimension for media preview. */
  height?: string | number;
}

export function displayGrid(columns: number, items: DetailItem[], options?: DetailGridOptions): DetailGrid

export function displayRepeat(fieldName: string, items: DetailItem[], options?: DetailRepeatOptions): DetailRepeat

export function displaySection(title: string, items: DetailItem[], options?: DetailSectionOptions): DetailSection

export function displayTab(label: string, items: DetailItem[], options?: DetailTabOptions): DetailTab

export function displayTabs(tabs: DetailTab[], options?: DetailTabsOptions): DetailTabs

export function displayText(content: string, options?: DetailTextOptions): DetailText

export type DisplayVariant =
  | "text"
  | "badge"
  | "code-badge"
  | "code"
  | "copyable"
  | "link"
  | "url"
  | "email"
  | "phone"
  | "currency"
  | "percent"
  | "progress"
  | "star"
  | "star-rating"
  | "boolean"
  | "date"
  | "datetime"
  | "time"
  | "relative"
  | "image"
  | "avatar"
  | "color"
  | "color-swatches"
  | "icon"
  | "key-value"
  | "table"
  | "tags"
  | "badges"
  | "json";

export async function evaluateDetailComputed(
  detail: DetailSchema | boolean | undefined,
  doc: any,
  user: any,
  db: any,
): Promise<any>

export function generateDefaultDetailSchema(schema: {
  fields?: Field[];
  labels?: { singular?: string; plural?: string };
  label?: string;
  slug?: string;
}): DetailSchema

export function isDetailItemVisible(item: DetailItem, doc: any, user?: any): boolean

export function normalizeDetailItem(item: DetailItem): Exclude<DetailItem, string>