"use client"

/**
 * ListPageViewFrame — shared horizontal gutter + optional centered max-width
 * for list-hub **view bodies** (folder icon grid, finder panel chrome,
 * OS-style folder explorer, dashboard slices, etc.).
 *
 * MUST be used instead of ad-hoc `mx-4 lg:mx-6` + `mx-auto max-w-*` pairs on
 * each page — see `apps/web/AGENTS.md` §4.5 and
 * `.cursor/rules/exxat-list-page-view-shells.mdc`.
 *
 * MUST NOT wrap `DataTable` when its toolbar already applies the same inset
 * (avoid double gutter — `table-edge-inset.ts`, `exxat-data-tables.mdc`); use this for **non-table** view branches or
 * **sections below** the shared toolbar.
 *
 * Promotion note: this file lived at
 * `apps/web/components/data-views/list-page-view-frame.tsx` until
 * 2026-05-20. It moved into `@exxatdesignux/ui` because the gutter / max-
 * width contract is entity-agnostic and other consumers (a future docs
 * site, partner apps) need the same rhythm without dragging in the whole
 * `data-views/` family.
 */

import * as React from "react"

import { cn } from "../../lib/utils"

/** Default horizontal rhythm for view bodies under `ListPageTemplate` (matches `FolderGridView`). */
export const LIST_PAGE_VIEW_FRAME_GUTTER = "mx-4 mb-6 lg:mx-6"

/** Typical max width for icon grids / dense tile views on ultra-wide monitors. */
export const LIST_PAGE_VIEW_FRAME_MAX_ICON_GRID = "max-w-6xl"

/** Slightly wider shell when a view includes toolbar + breadcrumbs + grid (e.g. OS folder explorer). */
export const LIST_PAGE_VIEW_FRAME_MAX_WIDE = "max-w-7xl"

export interface ListPageViewFrameProps extends React.HTMLAttributes<HTMLDivElement> {
  children: React.ReactNode
  /**
   * When set, children are wrapped in `mx-auto w-full min-w-0` + this
   * max-width so the block stays centered inside the primary page column.
   */
  maxWidthClassName?: string
  /** Override outer gutter; default `LIST_PAGE_VIEW_FRAME_GUTTER`. */
  gutterClassName?: string
}

export function ListPageViewFrame({
  children,
  className,
  maxWidthClassName,
  gutterClassName = LIST_PAGE_VIEW_FRAME_GUTTER,
  ...rest
}: ListPageViewFrameProps) {
  return (
    <div className={cn(gutterClassName, className)} {...rest}>
      {maxWidthClassName ? (
        <div className={cn("mx-auto w-full min-w-0", maxWidthClassName)}>{children}</div>
      ) : (
        children
      )}
    </div>
  )
}