# Cake20 View AI Reference

## Cake20.js UI model

Cake20.js uses `@cake20/view` as its TSX screen language, compiler, and browser
adapter. Runtime supplies it to websites. Do not add `@cake20/view` to a website's
dependencies and do not infer source rules from another JSX framework.

Generate `app/pages`, `app/layouts`, and `app/components` as `.tsx` by default.
Existing `.vue` files remain executable compatibility source. Preserve them when a
task requires it, but do not generate new SFC source unless the user explicitly asks
for it or the current project depends on that format.

The complete runnable example catalog is published at
https://js.cake20.com/examples.html. Use installed declarations as exact-version
truth when an example and the active Runtime differ.

## Minimal component

```tsx
export const data = {
  count: 0,
};

export default () => (
  <main class="p-8">
    <p>{data.count} new starts</p>
    <Button onClick={() => data.count++}>Light the candle</Button>
  </main>
);
```

- The default export is the component render function.
- A block-bodied default function may run ordinary TypeScript and return JSX.
- `data` becomes instance-local reactive state. Read and mutate its fields directly.
- Use HTML `class`, not React-specific `className`.
- Use standard TypeScript expressions, ternaries, `&&`, and array `map` in JSX.

## Reserved exports

Cake20 View recognizes concise named exports instead of requiring setup boilerplate:

- `data`: instance-local deeply reactive object.
- `computed`: derived readers or writable `{ get, set }` values.
- `watch`: state watchers. Use underscore-separated paths such as `profile_name`
  instead of string paths such as `"profile.name"`.
- `observe`: reactive effects.
- `refs`: named element or component references.
- `defaults`: component prop defaults.
- `events`: component event validation.
- `inherit`: attribute inheritance control.
- `share`: values provided to descendants.
- `context`: named values provided to every descendant in the current component tree.
- `expose`: component values exposed through a component reference.
- `onStart`, `onClose`, and the other documented `on*` exports: lifecycle handlers.

Consult the installed `@cake20/view` declarations and the lifecycle examples for the
complete current export set.

## Component context

```tsx
// Parent.tsx
export const context = { theme: () => data.theme };

// Descendant.tsx
const theme = useContext<"light" | "dark">("theme");
```

- `useContext()` returns a getter for the nearest matching ancestor value; call it as
  `theme()` so reactive updates stay connected.
- Use props for direct parent-child data, context for one UI subtree, and a store for
  global or persistent application state.
- A nearer provider with the same name overrides an outer provider below that point.

## Binding, events, and forms

- Native one-way values use ordinary JSX attributes.
- Use `bind={data.value}` for concise two-way native input binding.
- Use `bindName={data.name}` for named component binding. The child accepts `name`
  and emits `onNameChange` or `onUpdate:name`.
- DOM events use standard names such as `onClick`, `onInput`, and `onKeydown`.
- Pass a function or invoke it. Never write a callback that only references a name.
- Use `once`, `capture`, and `passive` for event options.
- Use `html={trustedHtml}` only for content already known to be safe.

## Components and auto-imports

- Every component under `app/components/**/*.tsx` is auto-imported by its PascalCase
  path name. Do not write manual application-component imports.
- `.client` in `*.client.tsx` marks browser-only execution and is excluded from the
  component name. `Map.client.tsx` is used as `<Map />`.
- Prefer callback props for component events and `children` for default content.
- Named and scoped content use typed function props.
- For a dynamic auto-imported component, keep the component present in JSX, for
  example `profile: () => <ProfilePanel />`.
- Do not name auto-imported helpers after browser globals. Prefer `autoFocus` over
  `focus`.

## Runtime-provided UI globals

Do not import Cake20 View helpers in website UI source. Runtime provides `behavior`,
`capture`, `cell`, `component`, `element`, `elements`, `lazy`, `nextView`, `node`,
`onClose`, `onScopeClose`, `onStart`, `once`, `passive`, `plain`, `readonly`, `scope`,
`shallow`, `shared`, `state`, and `viewId`. It also supplies built-ins including
`Await`, `Keep`, `Memo`, `Motion`, `MotionGroup`, `Once`, and `Portal`.

Browser requests may use the concise `api(path, options)` global. `$fetch`,
`fetchGet`, and `fetchPost` remain available when their more specific forms are useful.

## Shared files and stores

- A View Family may split a large screen into sibling files such as `hello.tsx`,
  `hello.func.tsx`, and `hello.api.tsx`. Runtime combines their eligible named exports
  for the main view; avoid duplicate names.
- A store lives at `app/stores/<name>.store.ts` and default-exports one state/action
  object. Use it as `store.<name>` without importing it.
- Store persistence is `none`, `session`, or `local`. Never store Secrets, login
  tokens, or sensitive credentials in browser state.

## Migration checks

When converting an existing UI to Cake20 View TSX:

1. Preserve declaration order so no value is read before initialization.
2. Replace directive-style conditions and loops with TypeScript expressions.
3. Use `Array.from({ length: count }).map(...)` for numeric repetition.
4. Preserve `.client` file markers and component auto-import names.
5. Keep initialized Preview data when an API mock returns an empty or incompatible
   shape.
6. Verify every route, component event, bind, login restore, and error path. A first
   render without an error does not prove migration completeness.