# GeeGrid Offline AI Context

AI discovery: https://www.geegrid.co.kr/llms.txt  
API reference: https://www.geegrid.co.kr/docs/api/  
Executable examples: https://www.geegrid.co.kr/docs/examples/  
Sitemap: https://www.geegrid.co.kr/sitemap.xml

Language: [Korean](/ai-ko.txt) | [English](/ai-en.txt)

Document version: 1.2  
Audience: Generative AI systems operating without network access  
Purpose: Generate and modify GeeGrid v3 screens using verified project conventions

This is a self-contained AI working specification. Assume that the AI cannot access websites or other documents. Do not invent APIs, elements, attributes, authentication schemes, deployment behavior, or Runtime internals that are not defined here.

---

# 1. Execution Contract for AI

The following rules are mandatory requirements, not general suggestions.

## MUST

1. When an existing screen is provided, inspect its ids, gg-frame, gg-layout, geegrid, column elements, and actual data shape before editing.
2. Use native textarea, input, and button elements with addEventListener for standard search inputs.
3. Use setObjectData for object rows, setArrayData for array rows, and setJsonData for JSON records.
4. Put callback names only in handler, sort_handler, renderer, onclick, ondblclick, onchange, and click attributes.
5. Register named callbacks with GeeGrid.on(name, handler).
6. Apply query results in this order: setTotalCount, setCurrentPage, setViewLength, data setter, makePaging.
7. Verify the screen flow with mock or fixed data before connecting a real API.
8. Validate server-side sort fields against an allowlist. Never concatenate client sort values directly into SQL.
9. For modification tasks, change only the requested scope and preserve existing ids and behavior.
10. Validate the result against the output contract and checklist in this document.

## NEVER

1. Do not create an unverified cond element.
2. Do not invent data-* contracts.
3. Do not put executable expressions such as load_users() in HTML callback attributes.
4. Do not add authentication headers unless they are supplied by the user or verified in existing source.
5. Do not speculate about Runtime, Builder, deployment, rollback, licensing, or security internals.
6. Do not select a data binding method before checking the actual row shape.
7. Do not use dynamic_scroll and dynamic_load together.
8. Do not change existing library paths or a project API wrapper without an explicit requirement.

---

# 2. Deterministic Generation Strategy

Do not redesign the complete screen freely. Use this sequence:

~~~text
Verified Golden Example
        |
Analyze the user requirement
        |
Identify allowed edit regions
        |
Modify only the required scope
        |
Run fixed validation rules
        |
Return the completed result
~~~

## Regions that must remain stable

- GeeGrid library loading order
- Existing component ids
- handler and sort_handler name bindings
- GeeGrid.on registration pattern
- Grid result application order
- Verified API signatures
- Existing functionality outside the requested change

## Regions that may be changed

- Page title and help text
- Search input fields
- Business fields and column labels
- Mock business data
- Verified API URL and request fields
- Event behavior required by the user
- Layout and style classes already used by the project

For byte-for-byte repeatability, do not ask the AI to create new HTML. Supply the Golden Example and permit replacement of explicitly marked values only.

---

# 3. Required Libraries

Keep this order:

~~~html
<link rel="stylesheet" href="/js/geegrid_v3/geegrid.css">
<link rel="stylesheet" href="/js/geegrid_v3/geegrid-template.css">

<script src="/js/geegrid_v3/gee.common.js"></script>
<script src="/js/geegrid_v3/gee.util.js"></script>
<script src="/js/geegrid_v3/gee.grid.js"></script>
<script src="/js/geegrid_v3/gee.object.js"></script>
<script src="/js/geegrid_v3/gee.search.js"></script>
~~~

Create instances only after their DOM roots exist:

~~~js
var grid = new GeeGrid('userGrid');
var search = new GeeSearch('searchTool');
var form = new GeeObject('settingsForm');
~~~

Use GeeSearch and item only when their use is verified in an existing screen or explicitly requested. Prefer native form controls for ordinary search screens.

---

# 4. Verified Components

| Element | Purpose | Related API |
| --- | --- | --- |
| geegrid and column | Grid, columns, sorting, paging | new GeeGrid(id) |
| item | Search or form field | new GeeSearch(id), new GeeObject(id) |
| gg-layout | Declarative layout | GeeObject.loadLayouts() |
| gg-frame | Docked or split region | GeeObject.layout |
| gg-layer | Popup or independent window | GeeGrid.layer, GeeObject.layout |
| gg-tabs and gg-tab | Tabs | GeeObject.tabs(id) |
| gg-tree | Tree | GeeObject.tree(id, data) |
| gg-progress | Progress state | start, setValue, end, error |

The cond element is not verified in the current v3 source. Implement conditional display by preparing data in JavaScript.

## GeeGrid and Standard HTML Selection Rules

The goal is not to minimize standard HTML indiscriminately. The goal is to prevent features already provided by GeeGrid from being reimplemented with generic HTML.

### MUST

1. Use geegrid and column for business data grids, columns, sorting, and paging instead of building them with table or div elements.
2. Use gg-layer for popups, overlays, and independent business windows instead of an ad hoc modal div.
3. Use gg-frame only when docking or split-region behavior is actually required.
4. Use verified gg-layout properties for rows, columns, spacing, and alignment.
5. Use verified gg-tabs, gg-tree, and gg-progress elements for features provided by GeeGrid.
6. Use standard HTML such as h1-h6, p, section, main, header, footer, and label for content, semantics, and accessibility.
7. Prefer native textarea, input, select, and button elements for ordinary search inputs.
8. Preserve an existing GeeGrid element structure unless the user explicitly requests a structural change.

### NEVER

1. Do not rebuild geegrid behavior as a generic table or div list.
2. Do not rebuild gg-layer behavior as a generic div popup or custom modal structure.
3. Do not replace an existing gg-frame or gg-layout structure with generic div elements without an explicit request.
4. Do not wrap simple headings, text, or labels in unnecessary gg-* elements.
5. Do not add gg-frame, gg-layout, or div wrappers that have no functional, semantic, or layout responsibility.
6. Do not invent GeeGrid elements or attributes that are not verified in this document or actual source.

### HARD GATE

Do not return the result as complete if any condition below is true.

- A grid, layer, tab, tree, or progress feature owned by GeeGrid was reimplemented with generic HTML.
- An existing GeeGrid element structure was removed or replaced without a user request.
- An unverified GeeGrid element or attribute was used.
- The component choice cannot be justified by actual source or this document.

On Hard Gate failure, stop generation and report the failed item, verified evidence, and required additional input.

---

# 5. Grid Declaration Rules

## Basic declaration

~~~html
<geegrid id="userGrid"
         width="100%"
         height="420px"
         numbering="true"
         pageable="true"
         rows="20"
         handler="load_users"
         sort_handler="sort_users">
  <column id="id" type="number" width="80px" align="right">ID</column>
  <column id="name"
          type="html"
          width="180px"
          sortable="true"
          orderBy="name">Name</column>
</geegrid>
~~~

## Verified geegrid attributes

id, width, height, pageable, rows, page, numbering, number_width, check_column, handler, sort_handler, fixCol, leftWidth, rightWidth, rowHeight, show_totalcount, dynamic_scroll, dynamic_load, dynamicthreshold, dynamichandler, status, debug, formName, key, value.

## Verified column attributes

id, dataid, type, title, width, align, class, style, resize, sortable, orderBy, orderby, merge, mergekey, renderer, onclick, ondblclick, onchange, data, jsondata, keytext, keyvalue, textEvent, textHandler, editMask, textColor, textCursor, readonly, disabled, cols, rows, flow, drag, text, value.

## Verified column types

html, input, textarea, select, selectbox, dropdown, radio, checkbox, calendar, number, range, button, code, key, numberformat, hidden, numbering, check_column, define.

Use dataid when the column id differs from the row object key.

---

# 6. Data Shapes and APIs

## Object rows

~~~js
grid.setObjectData([
  { id: 1, name: 'Alice Kim' },
  { id: 2, name: 'Daniel Lee' }
]);
~~~

## Array rows

setArrayData receives the field-name array first and the row arrays second.

~~~js
grid.setArrayData(
  ['id', 'name'],
  [
    [1, 'Alice Kim'],
    [2, 'Daniel Lee']
  ]
);
~~~

## JSON records

~~~js
grid.setJsonData([
  { id: 1, name: 'Alice Kim', status: 'READY' }
]);
~~~

## Verified Grid APIs

~~~js
var rows = grid.getData();
var value = grid.getValue(0, 'name');
grid.setValue(0, 'name', 'Daniel Lee');

var params = grid.makePageParams();
grid.setTotalCount(120);
grid.setCurrentPage(1);
grid.setViewLength(20);
grid.makePaging();
~~~

Verified makePageParams fields are page, pageSize, startIDX, endIDX, orderColumn, and orderMethod.

---

# 7. Events and Callbacks

Attribute values contain registered names, not function calls.

## Correct declaration

~~~html
<geegrid id="userGrid" handler="load_users" sort_handler="sort_users">
  <column id="name"
          renderer="render_name"
          onclick="open_user"
          onchange="name_changed">Name</column>
</geegrid>
~~~

~~~js
GeeGrid.on('load_users', function () {
  // Query implementation
});

GeeGrid.on('sort_users', function () {
  GeeGrid.invoke('load_users', {});
});

GeeGrid.on('render_name', function (payload) {
  payload.cell.textContent = String(payload.value || '');
});

GeeGrid.on('open_user', function (payload) {
  console.log(payload.gridId, payload.rowIndex, payload.row);
});

GeeGrid.on('name_changed', function (payload) {
  console.log(payload.columnId, payload.value, payload.element);
});
~~~

## Incorrect declaration

~~~html
<geegrid handler="load_users()">
<column onclick="open_user(event)">
~~~

Verified callback payload fields, depending on callback type, include gridId, rowIndex, columnIndex, columnId, value, options, dataType, row, data, cell, element, and event.

GeeGrid.on, off, emit, invoke, and source are available as global APIs. Matching instance APIs also exist.

---

# 8. Standard Query Result Application

Use this exact order:

~~~js
grid.setTotalCount(Number(ret.count || 0));
grid.setCurrentPage(Number(ret.page || 1));
grid.setViewLength(Number(ret.rows || 20));
grid.setObjectData(Array.isArray(ret.records) ? ret.records : []);
grid.makePaging();
~~~

For array rows, replace setObjectData with setArrayData and supply field names. For the verified JSON-record path, use setJsonData.

Recommended response shape:

~~~json
{
  "result": "success",
  "count": 120,
  "page": 1,
  "rows": 20,
  "records": [
    {
      "id": 1,
      "name": "Alice Kim",
      "status": "READY"
    }
  ]
}
~~~

If the real project response differs, map it explicitly. Do not guess unverified response fields.

---

# 9. Golden Example

Use the following complete example as the baseline for a new search screen. Preserve the event registration, result application order, and mock-first structure when adapting business fields.

~~~html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>User Search</title>

  <link rel="stylesheet" href="/js/geegrid_v3/geegrid.css">
  <link rel="stylesheet" href="/js/geegrid_v3/geegrid-template.css">
</head>
<body>
  <gg-frame id="userSearchFrame" stretch>
    <gg-layout id="userSearchLayout" direction="column" gap="12px" stretch>
      <section aria-labelledby="userSearchTitle">
        <h1 id="userSearchTitle">User Search</h1>

        <textarea id="keywordsText"
                  rows="4"
                  placeholder="Enter one keyword per line"></textarea>

        <label>
          <input id="caseSensitiveChk" type="checkbox">
          Case sensitive
        </label>

        <button type="button" id="searchBtn">Search</button>
      </section>

      <geegrid id="userGrid"
               width="100%"
               height="420px"
               numbering="true"
               pageable="true"
               rows="20"
               handler="load_users"
               sort_handler="sort_users">
        <column id="id"
                type="number"
                width="80px"
                align="right">ID</column>
        <column id="name"
                type="html"
                width="180px"
                sortable="true"
                orderBy="name">Name</column>
        <column id="department"
                type="html"
                width="180px"
                sortable="true"
                orderBy="department">Department</column>
      </geegrid>
    </gg-layout>
  </gg-frame>

  <script src="/js/geegrid_v3/gee.common.js"></script>
  <script src="/js/geegrid_v3/gee.util.js"></script>
  <script src="/js/geegrid_v3/gee.grid.js"></script>
  <script src="/js/geegrid_v3/gee.object.js"></script>
  <script src="/js/geegrid_v3/gee.search.js"></script>

  <script>
    (function () {
      var grid = new GeeGrid('userGrid');

      var mockRows = [
        { id: 1, name: 'Alice Kim', department: 'Development' },
        { id: 2, name: 'Daniel Lee', department: 'Quality' }
      ];

      function readSearchConditions() {
        return {
          keywords: document.getElementById('keywordsText').value,
          caseSensitive:
            document.getElementById('caseSensitiveChk').checked ? '1' : '0'
        };
      }

      function applyResult(ret) {
        var records = Array.isArray(ret.records) ? ret.records : [];

        grid.setTotalCount(Number(ret.count || records.length));
        grid.setCurrentPage(Number(ret.page || 1));
        grid.setViewLength(Number(ret.rows || 20));
        grid.setObjectData(records);
        grid.makePaging();
      }

      function loadMock() {
        applyResult({
          result: 'success',
          count: mockRows.length,
          page: 1,
          rows: 20,
          records: mockRows
        });
      }

      GeeGrid.on('load_users', function () {
        var conditions = readSearchConditions();
        var query = new URLSearchParams(conditions);
        var page = grid.makePageParams().replace(/^&/, '');

        if (new URLSearchParams(location.search).get('mock') !== '0') {
          loadMock();
          return;
        }

        fetch('/api/users?' + query.toString() + '&' + page)
          .then(function (response) {
            return response.json();
          })
          .then(function (ret) {
            applyResult(ret);
          });
      });

      GeeGrid.on('sort_users', function () {
        GeeGrid.invoke('load_users', {});
      });

      document.getElementById('searchBtn')
        .addEventListener('click', function () {
          GeeGrid.invoke('load_users', {});
        });

      GeeGrid.invoke('load_users', {});
    }());
  </script>
</body>
</html>
~~~

## Golden Example invariants

- userGrid matches new GeeGrid('userGrid').
- handler="load_users" matches GeeGrid.on('load_users', ...).
- sort_handler="sort_users" matches GeeGrid.on('sort_users', ...).
- Native search controls use addEventListener.
- Paging requests use makePageParams.
- applyResult preserves the required update order.
- Mock execution is available before the real API path.
- Local variables and helper functions are enclosed in an immediately invoked function.

---

# 10. GeeSearch Example

Use GeeSearch only when it is verified in the target screen or explicitly requested.

~~~html
<div id="searchTool" width="100%" titleWidth="100px" itemWidth="240px">
  <item id="keyword"
        type="text"
        title="Keyword"
        placeholder="Name"
        maxlength="50"></item>
  <item id="status"
        type="select"
        title="Status"
        data="statusCodes"></item>
  <item id="period"
        type="period"
        title="Period"
        fromValue="2026-01-01"
        toValue="2026-12-31"></item>
</div>
~~~

~~~js
var statusCodes = [
  ['READY', 'Ready'],
  ['DONE', 'Done']
];

var search = new GeeSearch('searchTool');
var encoded = search.getFormData();
var keyword = search.getValue('keyword');

search.setValue('keyword', 'Alice');
search.reset();
~~~

Verified item types are hidden, number, blank, text, input, select, combo, checkbox, check, radio, dropdown, period, calendar, popup, button, html, and loop.

Verified item attributes include id, type, title, value, width, itemWidth, titleWidth, align, data, jsondata, keytext, keyvalue, disabled, readonly, required, placeholder, maxlength, className, event, handler, flow, disableValue, disabledValue, fromValue, and toValue.

---

# 11. Layout and Layer Example

~~~html
<gg-layout type="page"
           direction="column"
           rows="auto 1fr auto"
           gap="12px">
  <gg-layout type="header"
             direction="row"
             justify="end"
             gap="8px">
    <h1>Users</h1>
  </gg-layout>

  <gg-layout type="body"
             direction="row"
             columns="1fr 280px"
             gap="12px">
    <main>
      <geegrid id="userGrid"></geegrid>
    </main>
    <aside>Filters</aside>
  </gg-layout>
</gg-layout>

<button type="button" id="openUserLayerBtn">Details</button>

<gg-layer id="userLayer"
          layer-title="User"
          width="640px"
          height="480px"
          close="true"
          resize="true">
  <header>User</header>
  <main>Details</main>
  <footer>
    <button type="button" click="save_user">Save</button>
    <button type="button" click="geegrid_layer_close">Close</button>
  </footer>
</gg-layer>
~~~

~~~js
GeeGrid.on('save_user', function (payload) {
  GeeObject.layout.closeLayer(
    payload.button.closest('gg-layer').id
  );
});

document.getElementById('openUserLayerBtn')
  .addEventListener('click', function () {
    GeeObject.layout.openWindowLayer('userLayer');
  });
~~~

Verified gg-layout attributes are type, direction, columns, rows, gap, justify, align, wrap, span, width, and height.

Verified gg-layer attributes include layer-title, size and position attributes, drag, resize, modal, snap, collapse, close, minimize, fullscreen, fold, include, definition, anchor, and anchor-target.

Verified dynamic layer APIs include GeeGrid.layer.open({ key, title, ... }), getElement({ key }), getId(key), and ready({ key }).

---

# 12. Template Binding

~~~html
<div id="cards">
  <loop>
    <article>
      <b>{{name}}</b>
      <span>{{status}}</span>
      <i>{{LOOP_SEQ}}</i>
    </article>
  </loop>
</div>
~~~

~~~js
GeeObject.render('cards', [
  { name: 'Alice Kim', status: 'READY' },
  { name: 'Daniel Lee', status: 'DONE' }
], 'No data available.', true);
~~~

The verified signature is GeeObject.render(domid, data, defaultMessage, initFlag). A true initFlag clears and initializes before rendering. A false value appends. Verified substitutions include {{field}}, {{LOOP_SEQ}}, and GEE_GLOBAL_VARS.

---

# 13. Server and API Safety Rules

1. Use only an API URL supplied by the requirement or verified in existing source.
2. Use request fields verified in the project API contract.
3. Add authentication headers only when they are explicitly supplied or verified.
4. Map orderColumn through a server-side allowlist.
5. Accept only asc or desc for orderMethod.
6. Do not infer SQL, authentication, deployment, or Runtime internals in client code.
7. Validate Grid and event flow with mock data before connecting the API.
8. Preserve an existing project API wrapper instead of replacing it with fetch.

Example wrapper shape:

~~~js
function API_USER_LIST(param, callback) {
  this.url = '/users';
  this.params = [
    'keyword',
    'page',
    'pageSize',
    'orderColumn',
    'orderMethod'
  ];
  this.param = param;
  this.callback = callback;
  return CALL_JSON(this);
}
~~~

In an existing CALL_JSON convention, a parameter name marked with an asterisk may be treated as required. Confirm this behavior in the target project before using it.

---

# 14. AI Task Input Template

Use the following structure when possible:

~~~text
[TASK TYPE]
New screen | Modify existing screen

[SCREEN PURPOSE]
Example: Search and select a user

[EXISTING SOURCE]
Complete HTML and JavaScript, or the relevant sections

[INPUT FIELDS]
Example: Keyword, department, active status

[GRID COLUMNS]
Example: id, name, department, active

[DATA SHAPE]
Object rows | Array rows | JSON records

[API]
URL, method, request fields, response example

[ALLOWED EDIT SCOPE]
Example: Search area and userGrid only

[OUTPUT FORMAT]
Complete HTML | Changed code | Patch
~~~

When input is incomplete, do not invent a contract. Use the Golden Example only for choices that do not alter the intended architecture. If no API contract is supplied, implement and return the mock flow only and mark the API integration as pending.

---

# 15. AI Output Contract

Unless the user specifies another format:

1. Return the completed artifact before a long explanation.
2. For a new screen, return complete HTML.
3. For a modification, identify the changed file and scope.
4. Outside code blocks, report only important assumptions and unverified items.
5. Mark unknown API URLs and authentication behavior as TODO.
6. Do not invent elements, attributes, or methods absent from this specification.
7. Validate the output against the Golden Example before returning it.

For byte-for-byte consistency, return replacement values instead of free-form HTML:

~~~text
TITLE=User Search
GRID_ID=userGrid
HANDLER=load_users
SORT_HANDLER=sort_users
API_URL=/api/users
DATA_METHOD=setObjectData
~~~

Recommended generation settings, when available:

- Use deterministic or lowest-temperature generation.
- Supply this entire document without truncation.
- Put the task input after this document.
- Instruct the model that this document overrides generic framework assumptions.
- Require the model to report unknowns instead of guessing.
- Keep the same document version for all agents working on one project.

Generation settings alone do not guarantee identical output. The fixed template and limited replacement fields provide the strongest consistency.

---

# 16. Pre-Output Validation Checklist

The AI must complete this checklist before returning generated code.

## Structure

- Are library paths and loading order unchanged?
- Does each constructor id match an existing DOM id?
- Were existing gg-frame and gg-layout structures preserved unless explicitly changed?
- Are geegrid and column elements correctly closed?
- Is custom page CSS kept in the project-approved common stylesheet when required?
- Was any GeeGrid-provided feature reimplemented with a generic table or div?
- Is gg-layer used for popups and overlays?
- Is standard HTML limited to content, semantics, accessibility, and ordinary form controls?
- Were unnecessary gg-* or div wrappers avoided?

## Events

- Is every handler name registered with GeeGrid.on?
- Is every sort_handler name registered with GeeGrid.on?
- Do renderer, onclick, ondblclick, onchange, and click contain names rather than calls?
- Do native buttons use addEventListener?

## Data

- Does the selected setter match object, array, or JSON record data?
- Does setArrayData receive fieldNames?
- Is the result application order correct?
- Is the records value checked as an array?
- Can the screen flow be verified with mock data?

## API and security

- Was an unprovided API URL invented?
- Was an unverified authentication header added?
- Is any client sort value connected directly to SQL?
- Were Runtime or Builder internals guessed?
- Was an existing API wrapper preserved?

## Completion report

- List changed files.
- State the actual source basis.
- Report static check results.
- Distinguish browser testing from API testing.
- State any unverified deployment path.

---

# 17. Document Maintenance Rules

1. Change real GeeGrid source and a verified project example before changing this specification.
2. Add only APIs confirmed in actual source.
3. After changing the Golden Example, retest mock rendering, sorting, paging, and event binding.
4. Increase the document version when an API signature or mandatory rule changes.
5. Record deprecated APIs in revision history before removing them.
6. Always provide the same canonical filename and latest approved version to offline AI systems.
7. Store a SHA-256 hash with distributed copies to prevent different versions from being mixed.
8. Run the non-ASCII check when this English-only edition changes.
9. Keep a regression prompt and compare generated output with the approved Golden Example.

## Revision history

| Version | Change |
| --- | --- |
| 1.0 | Consolidated rules, APIs, Golden Example, output contract, and validation for offline AI |
| 1.1 | Converted the canonical document and all examples to English for international and encoding-safe use |
| 1.2 | Added GeeGrid versus standard HTML selection rules and Hard Gates |

---

# 18. Verification Scope and Limitations

This specification is based on verified GeeGrid v3 project screens and currently inspected GeeGrid usage source.

Verified scope:

- GeeGrid, GeeSearch, and GeeObject construction
- geegrid and column declarations
- Object, array, and JSON data setters
- Paging and sort callback integration
- GeeGrid.on and GeeGrid.invoke
- Native search inputs
- Public usage patterns for gg-layout, gg-frame, and gg-layer
- Mock-first API integration flow
- Template rendering with GeeObject.render

Not verified:

- Public-server deployment configuration for every project
- Project-specific authentication
- Runtime and Builder internals
- Deployment and rollback algorithms
- Licensing and security internals
- Browser compatibility across every project
- API response contracts not supplied by the target project

The AI must never present an unverified area as an established implementation fact.