# components/

This guide was generated by `xuda-cli`.

You can remove all generated folder guides later with:

~~~bash
npm run clean:readmes
~~~

Use this folder for reusable UI screens, panels, widgets, and feature views.

## What belongs here

- screens rendered from the root app
- panel components loaded with `<panel program="...">`
- feature-level UI such as students, tasks, profiles, dashboards, or settings

## File rules

- file type: `.xu`
- each file compiles to a Xuda `component`
- the component id comes from:
  1. `<meta>.id`
  2. `<mount>.id`
  3. the file basename

## Recommended blocks

- `<meta lang="json5">`
- `<params lang="json5">` when the component receives inputs
- `<fields lang="json5">`
- `<actions lang="json5">`
- `<events lang="json5">`
- `<datasource lang="json5">` when the component owns a datasource
- `<template>`
- optional `<script>`
- optional `<style>`
- optional `<mount>`

## Important rules

- the root app belongs in `App.xu`, not here
- use `<single-view>` or `<multi-view>` as the top-level UI wrapper
- use friendly attributes such as `bind`, `if`, `:content`, and `@click`
- add a `<mount>` block only when the component should mount directly into an HTML file
- if the component is only used through `<panel program="...">`, it usually does not need `<mount>`

## Example

~~~xml
<meta lang="json5">
{
  id: "student_list",
  menuTitle: "Student List",
  uiFramework: "@xuda.io/xuda-framework-plugin-tailwind"
}
</meta>

<fields lang="json5">
{
  show_details_v: { type: "boolean", value: false }
}
</fields>

<actions lang="json5">
{
  toggleDetails: [
    { action: "update", name: { value: "@show_details_v: !@show_details_v" } }
  ]
}
</actions>

<template>
  <single-view>
    <section class="p-6 space-y-4">
      <h1>Students</h1>
      <button class="rounded-full px-4 py-2 bg-sky-600 text-white" @click="toggleDetails">
        Toggle details
      </button>

      <div if="@show_details_v">
        <panel program="student_details" />
      </div>
    </section>
  </single-view>
</template>
~~~

## When to use `<mount>`

Use `<mount>` only when this component should mount into a specific HTML file and selector.

~~~xml
<mount>
{
  id: "marketing_hero",
  file: "landing.html",
  selector: "#hero"
}
</mount>
~~~