// What you write
const element = (
  <div className="listing-card" onClick={handleClick}>
    <h2>{listing.title}</h2>
    <p className="price">${(listing.price / 100).toFixed(2)}</p>
  </div>
);

// What Babel/SWC compiles it to (React 17+ JSX transform, no React import needed)
import { jsx as _jsx, jsxs as _jsxs } from 'react/jsx-runtime';

const element = _jsxs('div', {
  className: 'listing-card',
  onClick: handleClick,
  children: [
    _jsx('h2', { children: listing.title }),
    _jsx('p', {
      className: 'price',
      children: `$${(listing.price / 100).toFixed(2)}`,
    }),
  ],
});

// Classic transform (React < 17) — requires `import React from 'react'` in every file
// because JSX compiles to React.createElement()
const el = React.createElement('div', { className: 'card' }, 'Hello');

// Automatic transform (React 17+, default today) — no import needed
// Babel/SWC auto-imports from 'react/jsx-runtime'
import { jsx as _jsx } from 'react/jsx-runtime';
const el = _jsx('div', { className: 'card', children: 'Hello' });

// vite.config.ts — ensure automatic transform is used
{
  "plugins": ["@vitejs/plugin-react"],
  "esbuildOptions": { "jsxImportSource": "react" }
}

// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",         // use automatic transform
    "jsxImportSource": "react"  // import from react/jsx-runtime
  }
}

function ListingDetail({ listing, user, priceHistory }) {
  const isOwner = user?.id === listing.ownerId;
  const priceChange = priceHistory.at(-1) - priceHistory.at(-2);

  return (
    <article className="listing-detail">
      {/* String expressions */}
      <h1>{listing.title}</h1>
      <p>{listing.description.slice(0, 200) + '...'}</p>

      {/* Number expressions */}
      <span className="beds">
        {listing.bedrooms} bed{listing.bedrooms !== 1 ? 's' : ''}
      </span>

      {/* Template literals */}
      <p className="address">{`${listing.street}, ${listing.suburb} ${listing.postcode}`}</p>

      {/* Method calls */}
      <time dateTime={listing.listedAt}>
        {new Date(listing.listedAt).toLocaleDateString('en-AU', {
          day: 'numeric',
          month: 'long',
          year: 'numeric',
        })}
      </time>

      {/* Arithmetic */}
      <span className="price-psm">
        ${(listing.price / listing.floorAreaM2 / 100).toFixed(0)}/m²
      </span>

      {/* Ternary */}
      <span className={`price-change ${priceChange >= 0 ? 'up' : 'down'}`}>
        {priceChange >= 0 ? '▲' : '▼'} $
        {Math.abs(priceChange / 100).toLocaleString()}
      </span>

      {/* Logical AND — renders nothing when false/null/undefined/0... carefully */}
      {isOwner && <EditButton listingId={listing.id} />}

      {/* Nullish coalescing */}
      <p>{listing.description ?? 'No description provided.'}</p>

      {/* Optional chaining in props */}
      <img
        src={listing.photos?.[0]?.url ?? '/placeholder.jpg'}
        alt={listing.title}
      />

      {/* Object expression for inline style */}
      <div style={{ backgroundColor: listing.statusColor, padding: '4px 8px' }}>
        {listing.status}
      </div>

      {/* Immediately Invoked Function Expression (IIFE) — for complex logic inline */}
      {(() => {
        const days = Math.floor(
          (Date.now() - new Date(listing.listedAt)) / 86400000,
        );
        if (days === 0) return <span>Listed today</span>;
        if (days === 1) return <span>Listed yesterday</span>;
        return <span>Listed {days} days ago</span>;
      })()}

      {/* Array.from to generate a range */}
      <div className="star-rating">
        {Array.from({ length: 5 }, (_, i) => (
          <span key={i} className={i < listing.rating ? 'star filled' : 'star'}>
            ★
          </span>
        ))}
      </div>
    </article>
  );
}

// ❌ WRONG — renders "0" to the DOM when count is 0
{
  count && <Badge count={count} />;
}

// ❌ WRONG — renders "NaN" when value is NaN
{
  value && <Chart value={value} />;
}

// ✅ Always use boolean expressions
{
  count > 0 && <Badge count={count} />;
}
{
  count !== 0 && <Badge count={count} />;
}
{
  !!count && <Badge count={count} />;
}
{
  Boolean(count) && <Badge count={count} />;
}

// ✅ Or use ternary with null for the false branch
{
  count ? <Badge count={count} /> : null;
}

function ListingCard({ listing, user, isLoading, error }) {
  // ── Pattern 1: Guard clause before return ──────────────────────────
  // The cleanest pattern for loading/error states — removes all conditional
  // complexity from the return JSX
  if (isLoading) return <ListingCardSkeleton />;
  if (error)
    return (
      <ErrorMessage
        message={error.message}
        onRetry={() => window.location.reload()}
      />
    );
  if (!listing) return null;

  // ── Pattern 2: Ternary ─────────────────────────────────────────────
  // Best for: binary states, toggling between two components
  return (
    <article>
      {listing.isFeatured ? (
        <FeaturedBadge tier={listing.featuredTier} />
      ) : (
        <span className="standard-badge">Standard</span>
      )}

      {/* Nested ternary — use sparingly, extract when 3+ levels deep */}
      <span className="status">
        {listing.status === 'sold'
          ? 'Sold'
          : listing.status === 'under_offer'
            ? 'Under Offer'
            : 'For Sale'}
      </span>

      {/* ── Pattern 3: Logical AND — for optional content ─────────── */}
      {listing.virtualTourUrl && (
        <a href={listing.virtualTourUrl} className="virtual-tour-link">
          Virtual Tour ↗
        </a>
      )}

      {user?.role === 'agent' && listing.agentNotes && (
        <div className="agent-notes">
          <strong>Agent notes:</strong> {listing.agentNotes}
        </div>
      )}

      {/* ── Pattern 4: switch via object map ─────────────────────── */}
      {/* Better than switch/case for JSX — avoids IIFE awkwardness */}
      {{
        sale: <ForSaleTag price={listing.price} />,
        rent: <ForRentTag weekly={listing.weeklyRent} />,
        lease: <ForLeaseTag term={listing.leaseTerm} />,
        sold: <SoldTag soldAt={listing.soldAt} />,
        under_offer: <UnderOfferTag />,
      }[listing.listingType] ?? <span>{listing.listingType}</span>}

      {/* ── Pattern 5: Extract to a variable above return ─────────── */}
      {/* Keeps the JSX tree clean for complex conditions */}
      <PriceSection listing={listing} />
    </article>
  );
}

// Extract complex conditions into a component — single responsibility
function PriceSection({ listing }) {
  const displayPrice = (() => {
    if (listing.priceOnApplication) return 'Price on Application';
    if (listing.priceRange) {
      const [low, high] = listing.priceRange;
      return `$${(low / 100).toLocaleString()} – $${(high / 100).toLocaleString()}`;
    }
    return `$${(listing.price / 100).toLocaleString()}`;
  })();

  return (
    <div className="price-section">
      <span className="price">{displayPrice}</span>
      {!listing.priceOnApplication && listing.listingType === 'sale' && (
        <span className="price-guide">Price Guide</span>
      )}
    </div>
  );
}

function ListingGrid({ listings, savedIds, onSave }) {
  // ── Basic list with key ────────────────────────────────────────────
  // key must be: stable, unique among siblings, predictable
  return (
    <div className="listing-grid">
      {listings.map((listing) => (
        <ListingCard
          key={listing.id} // ✅ database ID — stable and unique
          listing={listing}
          isSaved={savedIds.has(listing.id)}
          onSave={onSave}
        />
      ))}
    </div>
  );
}

// ── Keys on Fragments when the component returns multiple elements ──
function ListingRow({ listing }) {
  return (
    <>
      {/* Each sibling in a list needs a key */}
      {listing.photos.map((photo, i) => (
        // Fragment with key — the short <> syntax can't carry a key
        <React.Fragment key={photo.id}>
          <img src={photo.url} alt={`${listing.title} — photo ${i + 1}`} />
          {photo.caption && <p className="caption">{photo.caption}</p>}
        </React.Fragment>
      ))}
    </>
  );
}

// ── Why index keys are dangerous ───────────────────────────────────
// With index keys, React reuses DOM nodes by position
// Deleting item at index 0 shifts all other items,
// causing them to re-render with wrong state (input values, focus, animations)

// ❌ Dangerous when list is reordered, filtered, or items deleted
{
  listings.map((listing, index) => (
    <ListingCard key={index} listing={listing} />
  ));
}

// ✅ Only safe when list is purely static and never reordered
{
  ['For Sale', 'For Rent', 'Sold'].map((label, i) => (
    <span key={i} className="tag">
      {label}
    </span>
  ));
}

// ── Filtering, sorting inside render ──────────────────────────────
function FilteredListings({ listings, filters }) {
  // Compute derived list inline — React's reconciler handles the diff
  const displayed = listings
    .filter((l) => {
      if (filters.type !== 'all' && l.listingType !== filters.type)
        return false;
      if (filters.minBeds && l.bedrooms < filters.minBeds) return false;
      if (filters.maxPrice && l.price > filters.maxPrice) return false;
      return true;
    })
    .sort((a, b) => {
      if (filters.sort === 'price_asc') return a.price - b.price;
      if (filters.sort === 'price_desc') return b.price - a.price;
      return new Date(b.listedAt) - new Date(a.listedAt);
    });

  return (
    <section>
      <p className="results-count">{displayed.length} properties</p>
      {displayed.length === 0 ? (
        <EmptyState filters={filters} />
      ) : (
        displayed.map((listing) => (
          <ListingCard key={listing.id} listing={listing} />
        ))
      )}
    </section>
  );
}

// ── Nested lists with unique keys ─────────────────────────────────
function AgentPortfolio({ agents }) {
  return (
    <div>
      {agents.map((agent) => (
        <section key={agent.id} className="agent-section">
          <h3>{agent.name}</h3>
          <div className="agent-listings">
            {agent.listings.map((listing) => (
              // Key is unique within this agent's listings
              // Two different agents can both have a listing with key "L001"
              // — that's fine, keys are scoped to their parent list
              <ListingCard key={listing.id} listing={listing} />
            ))}
          </div>
        </section>
      ))}
    </div>
  );
}

// ── Spread props — forward all props to a child ────────────────────
// Common for wrapper components
function Button({ variant = 'primary', size = 'md', children, ...rest }) {
  return (
    <button
      className={`btn btn--${variant} btn--${size}`}
      {...rest} // forwards onClick, disabled, type, aria-*, data-*, etc.
    >
      {children}
    </button>
  );
}

// ── Prop types and defaults with destructuring ─────────────────────
function PriceTag({
  priceCents,
  currency = 'AUD',
  showGuide = true,
  className = '',
  'data-testid': testId, // renaming reserved-ish attributes
}) {
  const formatted = new Intl.NumberFormat('en-AU', {
    style: 'currency',
    currency,
    maximumFractionDigits: 0,
  }).format(priceCents / 100);

  return (
    <div className={`price-tag ${className}`} data-testid={testId}>
      <span className="price-tag__amount">{formatted}</span>
      {showGuide && <span className="price-tag__guide">Price Guide</span>}
    </div>
  );
}

// ── Children patterns ──────────────────────────────────────────────
function Card({ children, header, footer, className = '' }) {
  return (
    <div className={`card ${className}`}>
      {header && <div className="card__header">{header}</div>}
      <div className="card__body">{children}</div>
      {footer && <div className="card__footer">{footer}</div>}
    </div>
  );
}

// Usage — JSX as props
<Card
  header={<h2>3 bed house in Paddington</h2>}
  footer={<ContactAgentButton agentId="a123" />}
>
  <p>Charming terrace with original features...</p>
  <PriceTag priceCents={189500000} />
</Card>;

// ── Render props pattern — function as children ────────────────────
function DataProvider({ query, children }) {
  const { data, loading, error } = useQuery(query);
  return children({ data, loading, error }); // function call inside JSX
}

// Usage
<DataProvider query={LISTINGS_QUERY}>
  {({ data, loading, error }) => {
    if (loading) return <Spinner />;
    if (error) return <Error message={error.message} />;
    return <ListingGrid listings={data.listings} />;
  }}
</DataProvider>;

// ── Component as prop ─────────────────────────────────────────────
function Modal({ trigger: Trigger, content: Content }) {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <>
      <Trigger onClick={() => setIsOpen(true)} />
      {isOpen && (
        <div className="modal-overlay" onClick={() => setIsOpen(false)}>
          <div className="modal-box" onClick={(e) => e.stopPropagation()}>
            <Content onClose={() => setIsOpen(false)} />
          </div>
        </div>
      )}
    </>
  );
}

// Usage — pass component references, not JSX elements
<Modal
  trigger={({ onClick }) => <button onClick={onClick}>Book Inspection</button>}
  content={({ onClose }) => (
    <InspectionForm listingId="L001" onClose={onClose} />
  )}
/>;

// Types for all component props
import type {
  ReactNode,
  ReactElement,
  ComponentPropsWithoutRef,
  CSSProperties,
} from 'react';

// ── Typed prop interfaces ──────────────────────────────────────────
interface Listing {
  id: string;
  title: string;
  price: number;
  bedrooms: number;
  bathrooms: number;
  carSpaces: number;
  floorAreaM2?: number;
  landAreaM2?: number;
  photos: Array<{ id: string; url: string; caption?: string }>;
  status: 'sale' | 'rent' | 'sold' | 'under_offer';
  listingType: 'house' | 'apartment' | 'townhouse' | 'land';
  listedAt: string; // ISO 8601
  description?: string;
}

interface ListingCardProps {
  listing: Listing;
  isSaved?: boolean;
  onSave?: (id: string) => void;
  variant?: 'compact' | 'full';
  className?: string;
}

// ── ReactNode vs ReactElement vs JSX.Element ───────────────────────
// ReactNode = anything that can be rendered: string, number, ReactElement,
//             null, undefined, boolean, array, Fragment
// ReactElement = a React element object (the result of calling jsx() or <Comp/>)
// JSX.Element = alias for ReactElement — prefer ReactNode for props

interface ContainerProps {
  children: ReactNode; // anything renderable — most permissive
  header?: ReactNode; // optional renderable content
  icon?: ReactElement; // must be a React element (not a string)
}

// ── Extending HTML element props ──────────────────────────────────
// ComponentPropsWithoutRef gives you all native HTML props without the ref
interface ButtonProps extends ComponentPropsWithoutRef<'button'> {
  variant?: 'primary' | 'secondary' | 'ghost';
  loading?: boolean;
  // Inherits: onClick, disabled, type, className, aria-*, data-*, etc.
}

function Button({
  variant = 'primary',
  loading,
  children,
  disabled,
  ...rest
}: ButtonProps) {
  return (
    <button
      {...rest}
      disabled={loading || disabled}
      className={`btn btn--${variant} ${loading ? 'btn--loading' : ''}`}
    >
      {loading ? <Spinner size="sm" /> : children}
    </button>
  );
}

// ── Discriminated union props ──────────────────────────────────────
type PriceDisplayProps =
  | { type: 'fixed'; priceCents: number }
  | { type: 'range'; lowCents: number; highCents: number }
  | { type: 'poa' }; // price on application — no price needed;

function PriceDisplay(props: PriceDisplayProps) {
  if (props.type === 'poa') return <span>Price on Application</span>;
  if (props.type === 'range') {
    return (
      <span>
        ${(props.lowCents / 100).toLocaleString()} – $
        {(props.highCents / 100).toLocaleString()}
      </span>
    );
  }
  return <span>${(props.priceCents / 100).toLocaleString()}</span>;
}

// ── Generic components ────────────────────────────────────────────
interface SelectProps<T> {
  options: T[];
  value: T | null;
  onChange: (value: T) => void;
  getLabel: (option: T) => string;
  getValue: (option: T) => string;
  placeholder?: string;
}

function Select<T>({
  options,
  value,
  onChange,
  getLabel,
  getValue,
  placeholder,
}: SelectProps<T>) {
  return (
    <select
      value={value ? getValue(value) : ''}
      onChange={(e) => {
        const selected = options.find((o) => getValue(o) === e.target.value);
        if (selected) onChange(selected);
      }}
    >
      {placeholder && <option value="">{placeholder}</option>}
      {options.map((option) => (
        <option key={getValue(option)} value={getValue(option)}>
          {getLabel(option)}
        </option>
      ))}
    </select>
  );
}

// Usage — TypeScript infers T as Suburb
<Select
  options={suburbs}
  value={selectedSuburb}
  onChange={setSelectedSuburb}
  getLabel={(s) => s.name}
  getValue={(s) => s.id}
  placeholder="Select suburb..."
/>;

// ── Short syntax — no props allowed ───────────────────────────────
function PropertySpecs({ listing }) {
  return (
    <>
      <dt>Bedrooms</dt>
      <dd>{listing.bedrooms}</dd>
      <dt>Bathrooms</dt>
      <dd>{listing.bathrooms}</dd>
      <dt>Car spaces</dt>
      <dd>{listing.carSpaces}</dd>
      {listing.floorAreaM2 && (
        <>
          <dt>Floor area</dt>
          <dd>{listing.floorAreaM2} m²</dd>
        </>
      )}
    </>
  );
}

// ── Long syntax — required when you need a key ─────────────────────
function FeatureList({ features }) {
  return (
    <dl>
      {features.map((feature) => (
        // key is a prop on Fragment, but not passed to children
        <React.Fragment key={feature.id}>
          <dt>{feature.category}</dt>
          <dd>{feature.description}</dd>
        </React.Fragment>
      ))}
    </dl>
  );
}

// ── Real-world use: table rows ─────────────────────────────────────
// <tr> must be a direct child of <tbody>/<thead>/<tfoot>
// A wrapping <div> around multiple <tr> elements would break the table DOM
function AgentTableRow({ agent }) {
  return (
    <>
      <tr className="agent-row" key={agent.id}>
        <td>{agent.name}</td>
        <td>{agent.agency}</td>
        <td>{agent.activeListings}</td>
      </tr>
      {agent.isExpanded &&
        agent.recentListings.map((listing) => (
          <tr key={listing.id} className="listing-sub-row">
            <td colSpan={2}>{listing.title}</td>
            <td>${(listing.price / 100).toLocaleString()}</td>
          </tr>
        ))}
    </>
  );
}

// ── Synthetic event types ──────────────────────────────────────────
function SearchBar({ onSearch, onClear }) {
  const [query, setQuery] = useState('');
  const inputRef = useRef<HTMLInputElement>(null);

  // React.ChangeEvent<HTMLInputElement> — for onChange on input
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setQuery(e.target.value);
  };

  // React.FormEvent<HTMLFormElement> — for onSubmit on form
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();   // prevent page reload
    if (query.trim()) onSearch(query.trim());
  };

  // React.KeyboardEvent<HTMLInputElement> — for keyboard events
  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
    if (e.key === 'Escape') {
      setQuery('');
      onClear();
      inputRef.current?.blur();
    }
    if (e.key === 'ArrowDown') {
      // Focus first suggestion
      e.preventDefault();
      document.querySelector<HTMLLIElement>('.suggestion-item')?.focus();
    }
  };

  // React.MouseEvent<HTMLButtonElement> — for click events
  const handleClearClick = (e: React.MouseEvent<HTMLButtonElement>) => {
    e.stopPropagation();   // prevent bubbling to parent
    setQuery('');
    onClear();
    inputRef.current?.focus();
  };

  return (
    <form onSubmit={handleSubmit} className="search-bar" role="search">
      <input
        ref={inputRef}
        type="search"
        value={query}
        onChange={handleChange}
        onKeyDown={handleKeyDown}
        placeholder="Suburb, postcode, or address..."
        aria-label="Search properties"
        autoComplete="off"
        autoCapitalize="none"
      />
      {query && (
        <button
          type="button"
          onClick={handleClearClick}
          aria-label="Clear search"
        >
          ×
        </button>
      )}
      <button type="submit" aria-label="Submit search">
        Search
      </button>
    </form>
  );
}

// ── Event delegation — handler at parent, target checked ──────────
// More efficient than attaching handlers to every child
function PhotoGallery({ photos, onPhotoAction }) {
  const handleGalleryClick = (e: React.MouseEvent<HTMLDivElement>) => {
    const btn = (e.target as Element).closest('[data-action]') as HTMLElement | null;
    if (!btn) return;

    const action = btn.dataset.action;
    const photoId = btn.dataset.photoId;

    if (action && photoId) {
      onPhotoAction(action, photoId);
    }
  };

  return (
    <div className="photo-gallery" onClick={handleGalleryClick}>
      {photos.map(photo => (
        <div key={photo.id} className="photo-item">
          <img src={photo.url} alt={photo.caption} />
          <div className="photo-controls">
            <button data-action="set-primary" data-photo-id={photo.id}>
              Set as primary
            </button>
            <button data-action="delete" data-photo-id={photo.id}>
              Delete
            </button>
          </div>
        </div>
      ))}
    </div>
  );
}

function PhotoUploader({ onUpload }) {
  const fileInputRef = useRef<HTMLInputElement>(null);
  const previewRef   = useRef<HTMLDivElement>(null);
  const [previews, setPreviews] = useState<string[]>([]);

  const handleFiles = (files: FileList) => {
    const newPreviews = Array.from(files).map(file => URL.createObjectURL(file));
    setPreviews(prev => [...prev, ...newPreviews]);

    // Scroll the preview area to show new images
    requestAnimationFrame(() => {
      previewRef.current?.scrollTo({ left: previewRef.current.scrollWidth, behavior: 'smooth' });
    });

    onUpload(files);
  };

  const openFilePicker = () => fileInputRef.current?.click();

  return (
    <div className="photo-uploader">
      <input
        ref={fileInputRef}
        type="file"
        accept="image/*"
        multiple
        onChange={e => e.target.files && handleFiles(e.target.files)}
        style={{ display: 'none' }}
        aria-hidden="true"
      />

      <button type="button" onClick={openFilePicker}>
        Add photos
      </button>

      <div ref={previewRef} className="photo-previews">
        {previews.map((url, i) => (
          <img key={url} src={url} alt={`Preview ${i + 1}`} className="preview-thumb" />
        ))}
      </div>
    </div>
  );
}

// forwardRef was the mechanism for forwarding refs to child DOM elements
const PriceInput = forwardRef<HTMLInputElement, PriceInputProps>(
  function PriceInput({ currency = 'AUD', onPriceChange, ...rest }, ref) {
    return (
      <div className="price-input-wrapper">
        <span className="currency-symbol">{currency === 'AUD' ? '$' : '€'}</span>
        <input
          ref={ref}         // forwarded ref attaches to the actual DOM element
          type="number"
          min={0}
          step={1000}
          onChange={e => onPriceChange(Number(e.target.value) * 100)}
          {...rest}
        />
      </div>
    );
  }
);

// Usage — parent can call ref.current.focus() on the input inside PriceInput
const priceRef = useRef<HTMLInputElement>(null);
<PriceInput ref={priceRef} currency="AUD" onPriceChange={setPrice} />

// React 19 — ref is just a prop, no forwardRef wrapper needed
function PriceInput({ currency = 'AUD', onPriceChange, ref, ...rest }) {
  return (
    <div className="price-input-wrapper">
      <span className="currency-symbol">$</span>
      <input
        ref={ref}     // ref passed straight through
        type="number"
        min={0}
        step={1000}
        onChange={e => onPriceChange(Number(e.target.value) * 100)}
        {...rest}
      />
    </div>
  );
}

// Usage is identical — the simplification is in the component definition
const priceRef = useRef<HTMLInputElement>(null);
<PriceInput ref={priceRef} onPriceChange={setPrice} />

// TypeScript — ref type in component props
import type { Ref } from 'react';
interface PriceInputProps {
  currency?:      string;
  onPriceChange:  (cents: number) => void;
  ref?:           Ref<HTMLInputElement>;   // React 19: ref in the interface
}

import { use, Suspense, createContext } from 'react';

// ── use() with a Promise ───────────────────────────────────────────
// The component suspends until the promise resolves
// The nearest <Suspense> boundary shows its fallback in the meantime
function ListingDetailContent({ listingPromise }) {
  // Suspends here until listingPromise resolves
  const listing = use(listingPromise);

  return (
    <article className="listing-detail">
      <h1>{listing.title}</h1>
      <PriceTag priceCents={listing.price} />
      <PropertySpecs listing={listing} />
    </article>
  );
}

// Parent — pass a promise (typically created by a data library or fetch)
function ListingPage({ id }) {
  // Create the promise once — don't create it inside a component that re-renders
  const listingPromise = fetchListing(id); // returns Promise<Listing>

  return (
    <Suspense fallback={<ListingDetailSkeleton />}>
      <ListingDetailContent listingPromise={listingPromise} />
    </Suspense>
  );
}

// ── use() called conditionally (unlike hooks — this is legal) ─────
function ListingNotes({ listing, isAgent, notesPromise }) {
  if (!isAgent) return null; // early return before use() — this is allowed

  // use() after a conditional — this is NEW in React 19
  // You cannot call useEffect/useState after a conditional, but use() is different
  const notes = use(notesPromise);

  return (
    <aside className="agent-notes">
      <h3>Agent Notes</h3>
      <p>{notes.text}</p>
    </aside>
  );
}

// ── use() with Context ────────────────────────────────────────────
// use(Context) is the React 19 equivalent of useContext — but callable conditionally
const ThemeContext = (createContext < 'light') | ('dark' > 'light');

function ThemedCard({ listing, showPremiumStyle }) {
  if (!showPremiumStyle) return <StandardCard listing={listing} />;

  // use() after a conditional — still valid
  const theme = use(ThemeContext);

  return (
    <div className={`premium-card premium-card--${theme}`}>
      <ListingCard listing={listing} />
    </div>
  );
}

// app/listings/[id]/page.tsx (Next.js App Router — Server Component by default)
// This component runs on the server — no bundle sent to the browser

async function ListingPage({ params }: { params: { id: string } }) {
  // Direct database access — no API route needed
  // This await runs on the server, not the client
  const listing = await db.listing.findUnique({
    where:   { id: params.id },
    include: { agent: true, photos: true },
  });

  if (!listing) notFound();

  return (
    <main className="listing-page">
      {/* Server Component — rendered to HTML, zero JS */}
      <ListingHeader listing={listing} />

      {/* Streaming: shows skeleton, then resolves independently */}
      <Suspense fallback={<SimilarListingsSkeleton />}>
        <SimilarListings  suburb={listing.suburb} currentId={listing.id} />
      </Suspense>

      {/* Client Component — 'use client' at the top of the file */}
      <SaveButton listingId={listing.id} />

      {/* Server Component — pass serializable data only */}
      <AgentCard agent={listing.agent} />
    </main>
  );
}

// Client component — must be in a separate file with 'use client'
'use client';
function SaveButton({ listingId }: { listingId: string }) {
  const [saved, setSaved] = useState(false);
  return (
    <button
      onClick={() => setSaved(s => !s)}
      className={`save-btn ${saved ? 'saved' : ''}`}
      aria-pressed={saved}
    >
      {saved ? '♥ Saved' : '♡ Save'}
    </button>
  );
}

'use client';
import { useActionState, useOptimistic } from 'react';
import { saveListingAction, submitEnquiry } from './actions';

// ── useActionState (React 19) — form with server action ───────────
function EnquiryForm({ listingId, agentId }) {
  const [state, formAction, isPending] = useActionState(submitEnquiry, {
    success: false,
    error: null,
  });

  return (
    <form action={formAction} className="enquiry-form">
      <input type="hidden" name="listingId" value={listingId} />
      <input type="hidden" name="agentId" value={agentId} />

      <label>
        Your name
        <input name="name" type="text" required disabled={isPending} />
      </label>

      <label>
        Email
        <input name="email" type="email" required disabled={isPending} />
      </label>

      <label>
        Phone
        <input name="phone" type="tel" disabled={isPending} />
      </label>

      <label>
        Message
        <textarea
          name="message"
          rows={4}
          required
          disabled={isPending}
          defaultValue="I'd like to arrange an inspection."
        />
      </label>

      {state.error && (
        <p className="form-error" role="alert">
          {state.error}
        </p>
      )}

      {state.success && (
        <p className="form-success" role="status">
          Enquiry sent! The agent will contact you shortly.
        </p>
      )}

      <button type="submit" disabled={isPending} className="btn btn--primary">
        {isPending ? 'Sending...' : 'Send enquiry'}
      </button>
    </form>
  );
}

// ── useOptimistic — immediate UI feedback before server confirms ───
function SaveListingButton({ listingId, initialSaved }) {
  const [optimisticSaved, setOptimisticSaved] = useOptimistic(initialSaved);

  const handleSave = async () => {
    // Update UI immediately — before server responds
    setOptimisticSaved(!optimisticSaved);
    // Server action runs — UI shows optimistic state during await
    await saveListingAction(listingId);
    // If action succeeds, optimistic state becomes real
    // If action fails, React reverts to the previous state
  };

  return (
    <button
      onClick={handleSave}
      className={`save-btn ${optimisticSaved ? 'saved' : ''}`}
      aria-label={optimisticSaved ? 'Unsave listing' : 'Save listing'}
    >
      {optimisticSaved ? '♥' : '♡'}
    </button>
  );
}