# Components

A PascalCase `.qml` file defines a reusable QML type whose root object is its public base.
Choose the smallest useful base and expose only the contract consumers need.

```qml
// SaveButton.qml
import QtQuick
import QtQuick.Controls

Button {
    id: root
    required property string documentName
    signal saveRequested(string documentName)

    text: "Save"
    Accessible.name: "Save " + root.documentName
    onClicked: root.saveRequested(root.documentName)
}
```

```qml
SaveButton {
    documentName: editor.title
    onSaveRequested: documentName => editor.save(documentName)
}
```

Prefer a signal for user intent over a callback stored in `property var`.
Use a property alias only when the nested property is deliberately part of the component's API.
An internal id remains private to the component.

## Choosing a form

- Use an inline component for a local repeated type.
- Use a neighboring PascalCase file for directory-local reuse.
- Use the project's QML module and `qmldir` conventions for shared types.
- Use `QtObject` from `QtQml` for non-visual state without visual children.
- Reuse a Qt Quick Control before recreating its interaction, focus, styling, and accessibility behavior.

A default property can make child composition concise, but expose one only when arbitrary child content is the component's intended contract.
Do not add aliases, callbacks, or lifecycle hooks speculatively.