Material Library

Material Library

The Material Library is a per-project catalogue of physical materials — boards, tiles, panels, slabs — that can be applied to surfaces. Every material captures its real-world dimensions, joint width, minimum piece constraints, default orientation and visual style.

Feature line from the README: 🎨 Material library with size, thickness, joints, and styles.

What a material is

A material is defined by the following fields:

Field	Meaning
Name	Unique label shown in dropdowns, legends and the cut list.
Unit width / Unit height	The native size of one piece in mm.
Thickness	Physical thickness in mm. Used by the PDF export and overlap rules.
Default joint	Default gap between adjacent pieces in mm. Patterns can override this.
Minimum piece width / height	Pieces smaller than this are flagged as waste during optimisation.
Default orientation	horizontal (long side along X) or vertical (long side along Y).
Style	Three colours — fill, label, joint — used for on-canvas rendering.

The library is stored in each project (project.materials) and persisted together with the rest of the project state.

Managing materials

The material list lives in the bottom panel of the editor. From there you can:

• Add material — opens the editor in "create" mode.
• Edit an existing entry — opens the same dialog, prefilled.
• Delete an entry — removes it after a confirmation prompt; surfaces that referenced it are reset to "no material".

The Material Editor dialog

MaterialEditor.tsx powers a modal with three groups:

1. Identity — name and default orientation.
2. Dimensions — unit width, unit height and thickness. All accept compound units (600, 60 cm, 0.6 m); parseLength rejects invalid values with a focused error message.
3. Constraints & joints — default joint, minimum piece width and height. The dialog validates that:
   • Width, height and thickness are positive.
   • minPieceWidth ≤ unitWidth and minPieceHeight ≤ unitHeight.
4. Style — colour pickers for the piece fill, the label text and the joint outline.

Submitting dispatches either addMaterialCommand or updateMaterialCommand, both of which are undoable.

Assigning a material to a surface

In the Properties panel for a selected surface, the Material dropdown lists every material in the project plus an — None — entry. Once a material is chosen:

1. Pieces are tiled across the surface using the assigned placement pattern.
2. The piece fill / label / joint colours come from the material style.
3. The pattern panel becomes the "Pattern settings" section, and pattern length units accept either millimetres or percentages of the material unit width.

Validation and protection

• Renaming a material to a name that is already in use is rejected with a toast.
• The library prevents deleting a material that is referenced by an active layout without first clearing those references.
• Editing a material that drives a layout triggers regeneration the next time Generate material layout is clicked.

Where this lives in the codebase

• UI — src/features/materials/MaterialEditor.tsx, src/features/materials/MaterialList.tsx
• Domain factory — src/domain/materials/material.ts
• Defaults & types — src/types/material.ts
• Commands — src/domain/commands/builtin/materialCommands.ts

Related pages

• Surfaces, Openings and Connections
• Placement Patterns
• Auto-generated Cut Lists and Layouts