# Template Layout Clarity Design

## Goal

Clarify the behavior of label templates so users can distinguish between:

- editing a single label canvas
- printing or exporting that label onto a paper layout such as `A4` three-column sheets

The immediate target is the `A4 三列小标签` template and the new-label template preview flow.

## Problem

The current editor model is based on a single label canvas plus separate paper/layout settings. That is valid for printing, but the template UX suggests a different mental model:

- the template card and preview imply a full-sheet A4 layout
- creating the template opens a single small label canvas
- users interpret this as the template being wrong or incomplete

This is not primarily a rendering bug. It is a mismatch between template semantics and presentation.

## Decision

Keep the editor model unchanged:

- the editing canvas continues to represent one label
- paper size, margins, gaps, and repetition continue to live in print/layout settings

Improve the template system so flat-paper templates communicate sheet layout clearly without pretending that the main canvas is the entire sheet.

## Scope

In scope:

- improve `A4 三列小标签` template semantics
- improve template preview rendering for sheet-based blank templates
- improve template card copy for flat-paper templates
- show a clear in-product hint after creating a sheet-layout template
- add regression tests for preview/layout metadata

Out of scope:

- converting the editor to a full-sheet canvas model
- rewriting print/export architecture
- changing roll-label behavior unless needed for consistency

## UX Behavior

### Template cards

Flat-paper templates should present themselves as:

- single-label editing templates
- with predefined sheet layout for print/export

For example, `A4 三列小标签` should describe both:

- single label size: `63.5 × 38.1 mm`
- output sheet layout: `A4 / 3 columns / margins and gaps preset`

### Template preview

The preview for flat-paper blank templates should render the full sheet layout, not just a single isolated label block.

The preview should visually show:

- paper boundary
- repeated label cells across the sheet
- the selected label cell highlighted
- optional lightweight grid/index markers for density and rhythm

Business templates can keep showing content blocks inside one label, but flat-paper blank templates should prioritize layout structure.

### After creation

When a user creates a flat-paper template:

- the main editor still opens on a single label canvas
- the app should show a short non-blocking hint that editing is per-label and printing/export uses the preset sheet layout

Example intent:

- “当前编辑的是单个标签；打印/导出时将按 A4 三列版式排版。”

## Data Model

No architectural change to the tab or canvas model.

Template metadata may be extended with layout-oriented preview hints if needed, for example:

- `previewMode: "sheet"` for flat-paper blank templates
- optional highlighted cell index or preview emphasis metadata

This metadata must remain optional so existing business templates continue to work.

## Rendering Design

### Template preview generation

`static/label-templates.js` should distinguish between:

- object preview items for content templates
- sheet preview descriptors for flat-paper layout templates

Recommended approach:

1. Keep the existing normalized preview item pipeline for content-based previews.
2. Add a dedicated sheet-preview builder for flat-paper blank templates.
3. Let `index.html` render either:
   - a sheet layout preview
   - or the existing single-label content preview

### New-label modal preview

The modal preview should use actual paper dimensions, label dimensions, margins, and gaps to compute:

- column count
- row count
- each label cell position

This should match the same layout logic already used by print layout preview closely enough that the modal preview is trustworthy.

## Error Handling

If preview metadata is missing or invalid:

- fall back to the existing simple preview
- never block template creation

If a flat-paper template cannot compute more than one cell:

- still show a clear single-cell preview with sheet framing
- avoid misleading “full-sheet” language

## Testing

Add or extend tests to verify:

- `A4 三列小标签` exposes flat-paper metadata correctly
- preview generation for flat-paper templates returns multi-cell sheet structure
- content templates still return object-level preview items
- fallback behavior remains valid for templates without content

Manual verification after implementation should cover:

- selecting `A4 三列小标签` in the new-label modal
- confirming the preview shows an A4 multi-cell sheet
- creating the template and seeing the single-label editor plus explanatory hint
- opening print/layout preview and confirming it remains consistent with the template preview

## Risks

- Mixing sheet-preview and content-preview code paths can make preview rendering harder to reason about if not isolated.
- If modal preview logic diverges from print preview logic, users will lose trust quickly.

Mitigation:

- centralize sheet cell calculations into one reusable helper
- keep content preview and sheet preview as separate explicit modes

## Recommended Implementation Order

1. Add failing tests for flat-paper template preview semantics.
2. Introduce a reusable sheet-layout preview builder.
3. Update modal preview rendering and template card copy.
4. Add the post-creation hint for flat-paper templates.
5. Run regression checks on existing business templates and object previews.
