import { useAppState } from '@components/common/context/app.js';
import {
isInPageBuilderIframe,
postToParent
} from '@components/common/page-builder/pageBuilderMode.js';
import React, { useEffect, useState } from 'react';
import {
resolveMetafield,
type MetafieldMeta,
type ShapedMetafieldEntry
} from './resolveMetafield.js';
export interface MetafieldProps {
/** Owner entity type — 'product' | 'category' | 'collection' | 'customer'
* | 'order' | 'shop' | 'blog_post' | 'blog_category' (open set). */
owner: string;
namespace: string;
fieldKey: string;
/**
* The entity carrying `metafields` — ALWAYS provided by the developer
* (owner decision 2026-07-18: the component never fetches or reads entity
* contexts itself). On productView: `const product = useProduct()` and pass
* it; in grids/shelves: the card's item; for shop: the `setting` object
* from the enclosing master's query. Nullish is tolerated at runtime (the
* default renders) so loading/optional data doesn't crash.
*/
entity:
| { uuid?: string; metafields?: ShapedMetafieldEntry[] }
| null
| undefined;
/** Per-call-site override; the manifest's appearance.placeholder is the
* primary default source (design Decision 5). Render-side only. */
defaultValue?: unknown;
render?: (value: unknown, meta: MetafieldMeta) => React.ReactNode;
/** Fast path for plain scalar text when no render prop is given. */
as?: keyof React.JSX.IntrinsicElements;
className?: string;
}
const devWarn = (message: string) => {
if (process.env.NODE_ENV !== 'production') {
// eslint-disable-next-line no-console
console.warn(message);
}
};
/* Page-builder chrome — injected once per document, active only inside the
* PB iframe. Violet dashed hover outline + a "Live data" tag, visually
* distinct from the widget chrome so staged-vs-live stays legible. */
const MF_STYLE_ID = 'evershop-metafield-chrome-style';
const MF_CSS = `
[data-evershop-mf]{position:relative;outline:1px dashed transparent;outline-offset:2px;cursor:pointer}
[data-evershop-mf]:hover{outline-color:#7c3aed}
[data-evershop-mf]:hover::after{content:attr(data-evershop-mf-label);position:absolute;top:-20px;left:0;background:#7c3aed;color:#fff;font-size:10px;line-height:1.4;padding:1px 6px;border-radius:3px;white-space:nowrap;z-index:60}
[data-evershop-mf-ghost]{display:inline-block;border:1px dashed #a78bfa;color:#7c3aed;background:#f5f3ff;font-size:11px;line-height:1.4;padding:2px 8px;border-radius:4px;cursor:pointer}
`;
function ensureChromeStyle(): void {
if (typeof document === 'undefined') return;
if (document.getElementById(MF_STYLE_ID)) return;
const style = document.createElement('style');
style.id = MF_STYLE_ID;
style.textContent = MF_CSS;
document.head.appendChild(style);
}
/**
* Storefront metafield renderer (theme-metafields design § V1b + § V1.1).
*
* Purely presentational: the developer supplies the entity (with its
* `metafields` selection from the page's merged GraphQL query) — the
* component performs no fetching and reads no entity contexts. Its only
* ambient input is the manifest-descriptor projection in app context (the
* theme's DECLARATION, not entity data — per-call-site descriptors would
* reintroduce the dual-declaration drift the manifest killed). Declared
* `visibleToCustomer: false` fields render NOTHING — never the default.
*
* Page-builder mode (V1.1): after hydration inside the PB iframe the
* rendered value gains hover chrome; clicking posts a `metafield-select`
* message to the admin shell, which opens the guideline drawer (info +
* definition status + deep link — values are LIVE data and are never edited
* from the builder). Declared fields that render nothing on the storefront
* (hidden, or unset without a default) show a ghost chip instead so they
* stay discoverable in the canvas. The first render is always the bare
* production element (Editable's two-phase pattern — SSR-stable).
*/
export function Metafield({
owner,
namespace,
fieldKey,
entity,
defaultValue,
render,
as: Tag = 'span',
className
}: MetafieldProps) {
const app = useAppState();
// Two-phase PB detection (Editable.tsx pattern): the first render matches
// SSR; chrome mounts after hydration, only inside the PB iframe.
const [isClient, setIsClient] = useState(false);
useEffect(() => {
setIsClient(true);
}, []);
const inIframe = isClient && isInPageBuilderIframe();
useEffect(() => {
if (inIframe) ensureChromeStyle();
}, [inIframe]);
const ref = `${owner}.${namespace}.${fieldKey}`;
const descriptor = app?.config?.themeMetafieldDescriptors?.[ref];
const entries = entity?.metafields;
const entry = Array.isArray(entries)
? entries.find((m) => m && m.namespace === namespace && m.key === fieldKey)
: undefined;
const resolution = resolveMetafield({
ref,
descriptor,
entry,
defaultValue
});
if ('warn' in resolution && resolution.warn) devWarn(resolution.warn);
const select = () =>
postToParent({
type: 'metafield-select',
ownerType: owner,
ownerUuid: entity?.uuid,
namespace,
fieldKey,
value: entry?.value ?? null,
declared: descriptor ?? null,
resolutionKind: resolution.kind
});
if (resolution.kind === 'hidden' || resolution.kind === 'empty') {
// Declared fields stay discoverable in the builder via a ghost chip;
// the storefront (and the SSR first render) shows nothing.
if (inIframe && descriptor) {
return (
{
// Stop the bridge's canvas-click deselection from racing the
// selection message (it would close the drawer we just opened).
e.preventDefault();
e.stopPropagation();
select();
}}
onKeyDown={(e) => {
if (e.key === 'Enter') {
e.preventDefault();
e.stopPropagation();
select();
}
}}
>
{descriptor.name ?? fieldKey}
);
}
return null;
}
const { value, meta } = resolution;
let rendered: React.ReactNode = null;
if (render) {
rendered = render(value, meta);
} else if (typeof value === 'string' || typeof value === 'number') {
// Default renderer covers plain scalars only; lists, groups, booleans and
// rich_text need a render prop (keeps this component's bundle cost near
// zero — the rich_text Row[] renderer is @components/common/Editor.js).
rendered = {String(value)};
} else {
devWarn(
` "${ref}": non-scalar value needs a render prop — rendered nothing`
);
}
if (!inIframe || rendered === null) {
return <>{rendered}>;
}
// Chrome wrapper: capture-phase click so links/buttons inside a render prop
// never navigate the preview away (the PB link guard's rule) — selecting
// the field is the only click behavior in the canvas.
return (
{
e.preventDefault();
e.stopPropagation();
select();
}}
>
{rendered}
);
}