page-builder（页面构建器）

Page Builder Patterns

Universal patterns for building pages. These apply to both public-facing and admin pages.

When to Use

• Building list pages with filtering, search, pagination
• Building detail/edit pages with forms
• Rendering mixed-type feeds or lists
• Any page that fetches and displays data

Core Principle

Remote-First: Put logic in data.remote.ts, keep pages as pure renderers.

See using-remote-functions/REMOTE-FIRST.md for the full pattern.

Page Types

Route Structure

src/routes/
└── [section]/
    ├── +page.svelte          # List page
    ├── data.remote.ts        # Remote functions (queries, forms)
    └── [slug]/
        └── +page.svelte      # Detail page

Key Patterns

1. Component Mapping

Map data types to components for clean rendering:

<script>
  const components = new Map([
    ['article', ArticleCard],
    ['video', VideoCard],
    ['cta', CTABanner]
  ])
</script>

{#each items as item, index (index)}
  {@const Component = components.get(item.type)}
  <Component {...item.props} />
{/each}

2. Filter Forms (Auto-Submit)

Native forms that update URL params on input:

<script>
  let form: HTMLFormElement
  function submitForm() { form.requestSubmit() }
  function debouncedSubmit() {
    clearTimeout(timer)
    timer = setTimeout(submitForm, 300)
  }
</script>

<form bind:this={form}>
  <input name="search" oninput={debouncedSubmit} />
  <select name="status" onchange={submitForm} />
</form>

3. Form Initialization

Populate forms with existing data:

<script>
  import { initForm } from '$lib/utils/form.svelte'

  initForm(updateItem, () => ({
    id: item.id,
    name: item.name ?? '',
    status: item.status ?? 'draft'
  }))
</script>

4. Pagination

<script>
  import Pagination from '$lib/ui/Pagination.svelte'
</script>

<Pagination count={totalItems} perPage={20} />

Form Components

All accept:

• label - Field label
• description - Helper text
• issues - Validation errors from field.issues()
• ...rest - Spread from field.as('type')

Remote Function Patterns

Query with Filters

const filtersSchema = z.object({
	search: z.string().catch(''),
	status: z.string().catch(''),
	page: z.number().catch(1)
})

export const getItems = query('unchecked', async (searchParams: URLSearchParams) => {
	const { locals } = getRequestEvent()
	const filters = parseSearchParams(filtersSchema, searchParams)
	return locals.service.getFiltered(filters)
})

Form with Validation

export const updateItem = form(
	z.object({
		id: z.string(),
		name: z.string().min(1, 'Required'),
		status: z.enum(['draft', 'published'])
	}),
	async (data) => {
		const { locals } = getRequestEvent()
		await locals.service.update(data.id, data)
		return { success: true }
	}
)

Reference Files

• LIST-PAGE.md - Full list page patterns
• DETAIL-PAGE.md - Form and detail patterns
• FEED-PAGE.md - Mixed-type feed rendering