/*
 * meow_lazygrid.h — SDK 2 维虚拟化宫格（§12.4：meow_lazygrid，M7.4 主界面前置）。
 *
 * 定位：给「卡片/图标宫格」提供**二维虚拟化**——应用入口宫格、图标墙、设置快捷卡等。
 * 只实例化**可见行**（视口内），行高/列几何 + gap；滚动复用 §12.3 meow_scroll（fling/snap），
 * 与 meow_listview 同款惯性；命中 meow_lazygrid_hit/tap_at 把滚动+网格坐标映射回 item idx。
 *
 * 设计（仿 meow_listview 的 vsource 思想 + meow_scroll 滚动 + meow_box 列几何）：
 *   - 数据源：count_fn() 返回总项数（任意长），bind_fn(index, item) 仅当 item「进入视口」
 *     （绑定到固定池槽）时调一次；回滚命中同槽不重绑（同 listview 池语义）。
 *   - 固定 item 池：池容量 = 视口行数 + 2（× cols），静态有界（≤MEOW_LAZYGRID_POOL_MAX）。
 *   - 列几何：cols + cell_w + cell_h + gap；行高 row_h = cell_h + gap；按 scroll offset 推可见行。
 *   - 渲染：默认 renderer 画「圆角卡片（icon+名+状态）」；App 也可经 set_item_draw 完全自绘
 *     （主界面卡片宫格用：icon+名+后台标注）。支持选中高亮/禁用变淡/空态占位。
 *   - 滚动：接 meow_scroll（meow_lazygrid_scroll 返回会话；track/fling/snap 与 listview 同款）。
 *
 * 内存纪律（M7 §5.2）：静态有界 item 池（冷路径 create/set_vsource 分配，热路径 draw/hit/scroll
 * 零 malloc），与 listview 池同源；不常驻 count 个 item 对象。
 *
 * 非 meow_widget：lazygrid 是**自包含控件**（不注册进 z 序/绘制注册表），由宿主（launcher session）
 * 在 draw 阶段调 meow_lazygrid_draw、命中阶段调 meow_lazygrid_hit/tap_at、滚动喂 meow_scroll——
 * 与 meow_scroll/meow_box 同为「正交模块」，不侵入 struct meow_widget（全追加式）。
 */
#ifndef MEOW_UI_LAZYGRID_H
#define MEOW_UI_LAZYGRID_H

#include "meow_ui_types.h"   /* meow_img 前向 + 基础类型（子头不引伞头，避免相对路径依赖） */
#include "meow_ui_theme.h"   /* meow_theme（draw 取语义色） */
#include "meow_ui_scroll.h"  /* meow_scroll（滚动集成；子头引依赖子头，同 widgets.h→theme.h） */

#ifdef __cplusplus
extern "C" {
#endif

typedef struct meow_lazygrid meow_lazygrid;

/* ---- cell / item ---- */
/* 单格数据（bind 回调填充；SDK 固定池持有；App 跨 bind 用 user 存业务态/图/index）。 */
typedef struct meow_lazygrid_item {
    const char     *title;      /* 主文本（名；必填，NULL 视为空格） */
    const char     *subtitle;   /* 副文本（状态/后台标注），可空 */
    const meow_img *icon;       /* 可选：格内图标（NULL=无） */
    int             enabled;    /* 1=可交互；0=变淡不响应 */
    void           *user;       /* App 私有（跨 bind 保存业务态；SDK 不碰） */
} meow_lazygrid_item;

/* 数据源：count 返回总项数（>=0，任意长）；bind 在 item 进入视口时调一次填充 item。
 * 二者均不常驻 item 对象；count 每帧实时查（支持动态长度/搜索过滤）。 */
typedef int  (*meow_lazygrid_count_fn)(void *ctx);
typedef void (*meow_lazygrid_bind_fn)(int index, meow_lazygrid_item *item, void *ctx);

/* 完全自绘回调（覆盖默认 renderer）：index=项号；x,y,w,h=格矩形（已裁剪到宫格视口）；
 * state=MEOW_LAZYGRID_ST_* 状态位（选中/禁用组合）。App 用 §3 绘制 API 自绘整格。 */
typedef void (*meow_lazygrid_draw_fn)(int index, int x, int y, int w, int h,
                                      int state, void *ctx);
/* state 位（draw 回调收到）。 */
#define MEOW_LAZYGRID_ST_SELECTED (1u<<0)
#define MEOW_LAZYGRID_ST_DISABLED (1u<<1)

/* 命中/点击回调（idx=项号；App 在 tap_at 命中后触发动作）。 */
typedef void (*meow_lazygrid_tap_fn)(int idx, void *ctx);

#define MEOW_LAZYGRID_POOL_MAX 96   /* 池容量上限（固定；保证静态有界） */

/* ---- 生命周期（冷路径 create/free；热路径 draw/hit/scroll 零 malloc）----
 * cols=列数（>=1，越界 clamp）；cell_w/cell_h=格宽高；gap=格间距（水平与垂直同用）。 */
meow_lazygrid *meow_lazygrid_create(int x, int y, int w, int h, int cols,
                                    int cell_w, int cell_h, int gap);
void           meow_lazygrid_free(meow_lazygrid *g);

/* ---- 几何配置 ---- */
void meow_lazygrid_set_rect(meow_lazygrid *g, int x, int y, int w, int h);  /* 视口矩形（绝对坐标） */
void meow_lazygrid_set_cols(meow_lazygrid *g, int cols);
void meow_lazygrid_set_cell(meow_lazygrid *g, int cell_w, int cell_h, int gap);

/* ---- 数据源 + 渲染 ---- */
int  meow_lazygrid_set_vsource(meow_lazygrid *g, meow_lazygrid_count_fn count,
                               meow_lazygrid_bind_fn bind, void *ctx);
int  meow_lazygrid_set_item_draw(meow_lazygrid *g, meow_lazygrid_draw_fn draw,
                                 void *ctx);   /* NULL=用默认卡片 renderer */
int  meow_lazygrid_set_empty_text(meow_lazygrid *g, const char *text);

/* ---- 滚动（像素级；可视行数按 offset 实时推） ---- */
void meow_lazygrid_set_scroll(meow_lazygrid *g, int off);
void meow_lazygrid_scroll_by(meow_lazygrid *g, int dy);
int  meow_lazygrid_scroll(meow_lazygrid *g);
int  meow_lazygrid_max_scroll(meow_lazygrid *g);   /* max(0, 内容高 - 视口高) */
int  meow_lazygrid_row_h(const meow_lazygrid *g);  /* 行高（=cell_h+gap） */
/* 便捷：包一个 meow_scroll 会话（set/max/get/redraw 指回本宫格；redraw 只刷视口区）。
 * App 在 on_touch_move 喂 meow_scroll_track、松手 meow_scroll_fling。返回 NULL=池满。 */
meow_scroll *meow_lazygrid_scroll_attach(meow_lazygrid *g);

/* ---- 选中 / 命中 ---- */
void meow_lazygrid_set_on_tap(meow_lazygrid *g, meow_lazygrid_tap_fn cb, void *ctx);
void meow_lazygrid_set_sel(meow_lazygrid *g, int idx);   /* 越界 clamp；<0 清除；标脏 */
int  meow_lazygrid_sel(const meow_lazygrid *g);
int  meow_lazygrid_hit(meow_lazygrid *g, int x, int y);  /* 命中项 idx（滚动+网格坐标映射）；-1=未命中/禁用 */
int  meow_lazygrid_tap_at(meow_lazygrid *g, int x, int y); /* 命中：置选中 + 回调 + 返回 idx/-1 */

/* ---- 绘制 ---- */
void meow_lazygrid_draw(meow_lazygrid *g, const meow_theme *th);

#ifdef __cplusplus
}
#endif
#endif /* MEOW_UI_LAZYGRID_H */