# GridKit – Agent Skill > **Version:** 1.96.0 | **License:** MIT | **Repository:** https://github.com/mmollay/gridkit > **Demo:** https://gridkit.at ## Purpose You are building or maintaining a web application using **GridKit**, a lightweight PHP component framework for admin dashboards. This skill is the authoritative reference for correct GridKit usage. ## Architecture - **Stack:** PHP 8.2+, Vanilla JS, CSS (Material Design 3) - **Zero Dependencies:** 1 CSS file + 1 JS file, no build process - **Namespace:** `GridKit\` | CSS prefix: `gk-` | Data attributes: `data-gk-` ## Change Workflow **Never modify GridKit files inside a consuming project.** Change the framework at its source, bump `VERSION`, note it in `CHANGELOG.md`, then update the copy your project uses. Local edits in a consuming project are silently lost on the next update and split the codebase in two. A new class goes into `css/blocks.json` with the version that brings it, under the block it belongs to — the index the demo reads its "since" and "New in" marks from. The suite fails on a class that is in a stylesheet and not there, and on a VERSION the changelog has no heading for. To ask whether your copy has a block: `css/blocks.json` names the release that first shipped each class. ## Available Components | Component | Class | Purpose | |-----------|-------|---------| | Table | `GridKit\Table` | Data tables with search, sort, pagination | | Form | `GridKit\Form` | Grid-based forms (16-column), all field types, AJAX submit | | Header | `GridKit\Header` | Fixed header with breadcrumb, user menu | | Sidebar | `GridKit\Sidebar` | Navigation with groups, badges, collapse | | Modal | `GridKit\Modal` | Dialog overlays | | Button | `GridKit\Button` | Filled/Outlined/Text/Tonal, icons, sizes | | Auth | `GridKit\Auth` | Session auth, bcrypt, remember-me | | Theme | `GridKit\Theme` | 6 themes (indigo/ocean/forest/rose/amber/slate), light/dark | | Layout | `GridKit\Layout` | Layout modes (sidebar-first, header-first) | | StatCards | `GridKit\StatCards` | KPI cards with icon, color, format | | FilterChips | `GridKit\FilterChips` | URL-based filter chip buttons | | YearFilter | `GridKit\YearFilter` | Year navigation filter | | TableHeader | `GridKit\TableHeader` | **Unified filter/search bar above tables — Status / Toolbar / Advanced (since v1.10.0)** | | Lang | `GridKit\Lang` | i18n / multilingual support | | Pagination | `GridKit\Pagination` | Server-side pager below the table (`.gk-rowpager`), optional PageSize | | PageSize | `GridKit\PageSize` | Rows per page — lives in the pager bar, not in the table footer | | liveTable (JS) | `GK.liveTable` | AJAX tables (search/filter/sort/pagination live, no reload) | | BelegModal | `GridKit\BelegModal` | PDF / document preview modal with iframe + mobile fallback (since v1.15.0) | | ActionGroup | `GridKit\ActionGroup` | Container for action buttons inside table columns (since v1.16.0) | | SortLink | `GridKit\SortLink` | Sortable column headers for hand-built tables (server-side sort) | | Select | `GridKit\Select` | Searchable single/multi select, optionally AJAX-fed | | Tabs (JS) | `.gk-tabs` / `[data-gk-tabs]` | Tab navigation, two shapes — full tablist semantics and arrow keys since 1.69.0 | | Accordion (JS) | `.gk-accordion` | Collapsible sections, optional single-open (`data-gk-single`) | | Tooltips (JS/CSS) | `title` / `data-gk-tooltip` / `data-gk-tooltip-rich` | Hint popups — plain, CSS-only, or with HTML in them | | Gallery + Lightbox (JS) | `.gk-gallery` / `GK.lightbox` | Image grid with lazy loading and a keyboard-operable viewer | | Image picker | `GridKit\ImagePicker` / `GK.picker` | Choose one image out of many: a compact grid of 16:9 tiles that works like a radio group, folds after two rows, and an enlarged view that can pick (since 1.94.0) | | Announcement (JS/CSS) | `.gk-announce` / `GK.announce` | The line that says "Saved." where the person works, read by a screen reader; empty it draws no box (since 1.93.0) | | Timeline | `.gk-timeline` | A log of steps, one under the other: a real ordered list, each step with a symbol and a word for its state (ok · failed · running · waiting · skipped), title, time, small chips, a detail and — when it broke — a message block (since 1.96.0) | | Portrait video frame | `.gk-video-frame` | A 9:16 frame for a video or picture: never wider than its column or taller than the window, optional guide lines for the zones a platform covers, an empty "being made" state and a failed state, a caption (since 1.96.0) | | Side sheet (JS) | `.gk-sheet` / `GK.sheet` | A panel a row opens: docked right beside the list, full screen and modal on a phone (since 1.91.0) | | Icon | `GridKit\Icon` | Inline SVG icons with a Material Icons fallback — `Icon::svg($name, $px)`: the 2nd argument is an **int** pixel size (default 16), not an options array | ## The one rule to read first: echo or return Half of GridKit prints; half hands you a string. Getting this wrong produces no error and no warning — the page renders, the piece is simply missing. Five agents were given this file and a page to build; not one got a first draft without tripping over this. **These twelve PRINT. Call them as a statement — `render(); ?>`:** | | | | |---|---|---| | `Table::render()` | `Form::render()` | `Sidebar::render()` | | `StatCards::render()` | `FilterChips::render()` | `TableHeader::render()` | | `YearFilter::render()` | `Pagination::render()` | `PageSize::make()->…->render()` | | `ActionGroup::render()` | `Modal::container()` | `BelegModal::container()` | `PageSize::render()` above is an INSTANCE method — build it with the static `PageSize::make('per_page')` first, then chain. Same for `TableHeader::make()`. Everything else in that table is called on an object you constructed with `new`. **These RETURN a string. You must echo it — ``:** | | | | |---|---|---| | `Header::render()` | `Button::render()` | `Button::icon()` | | `Theme::switcher()` | `Theme::attributes()` | `Layout::bodyTag()` | `Theme::density('konsole')` sets how tightly tables are set — `konsole` fits about a third more rows on a screen, `weit` gives them room, and the default leaves the rhythm alone. It names no colour, so it composes with every theme and both modes; an unknown value is ignored. | `Icon::svg()` | `Select::searchable()` | `Layout::asset()` | | `Lang::jsConfig()` | `Pagination::build()` | | `Header::render()` is the exception that catches people: every other component you construct with `new` prints, and this one does not. `render(); ?>` renders nothing at all, silently. The rule behind it, if you want one: a component that owns a block of the page prints it; a helper that produces a fragment for you to place returns it. Header sits on the wrong side of that line for historical reasons and is not going to move, because every existing page echoes it. --- ## Page skeleton Every class lives under the `GridKit\` namespace and is autoloaded by `autoload.php`. A complete page needs nothing beyond that — no template engine, no build step: ```php > ``` `skeleton.php` in the repository is this file, filled in. **`Layout::asset()` stamps a path; it does not resolve one.** It appends the file's modification time so a changed stylesheet is not served from a stale cache — and it hands back whatever path you gave it. So the path has to be one the *browser* can reach from the page: ```php // page inside the GridKit directory echo Layout::asset('css/gridkit.css'); // css/gridkit.css?v=… // page in an app directory beside the checkout echo Layout::asset('../gridkit/css/gridkit.css'); // Composer install — the files live under vendor/ echo Layout::asset('vendor/mmollay/gridkit/css/gridkit.css'); ``` Get it wrong and the stamp still appears, so the URL looks right while the browser gets a 404 and the page renders unstyled. If `vendor/` is outside your document root, copy or symlink its `css/` and `js/` into the public root. `Modal::container()` is **not** in the skeleton above and should not be in yours: since 1.42.0 it emits nothing. `GK.modal.open()` builds its own overlay. The other classes import the same way — the full list is in the table above, each one `GridKit\`: ```php use GridKit\{ActionGroup, Auth, BelegModal, FilterChips, Header, Icon, PageSize, Pagination, Select, SortLink, TableHeader, YearFilter}; ``` A complete working application is in [`examples/invoices/`](examples/invoices/). ### With a sidebar A sidebar is `position: fixed`, so the content beside it needs the wrapper that makes room. Without it everything renders **underneath** the sidebar — silently, because nothing is broken, it is just covered: ```php brand('My app', 'widgets') ->group('Navigation') ->item('Dashboard', '?p=dashboard', 'dashboard', ['active' => true]) ->item('Invoices', '?p=invoices', 'receipt_long', ['badge' => 12]) ->render(); ?>
title('Dashboard')->user('Jane')->render() ?>
``` `gk-with-sidebar` carries the left margin and shrinks when the sidebar collapses; `gk-main` carries the padding — 24px 28px 48px, 16px at the edge of a phone — and caps the content at `--gk-main-max` (1680px; set it on the page to change it). Until 1.92.0 the class was documented here and had no rule, so every page wrote that padding itself. `skeleton.php` in the repository is this file, filled in. ### Inside SSI Panel In SSI Panel the layout loads GridKit, so a view only imports what it uses: ```php layout('layouts/panel'); use GridKit\{Table, Form, StatCards, FilterChips, Button}; ?> start('content') ?> end() ?> ``` ## Six rules for lists Read these before you build a list. They come from two admin lists that were built with GridKit and turned down (since 1.91.0): a user list of 21 rows had nine columns, two selects, a switch and a label in every row, rows 100px tall, and its actions scrolled off the right at 1280px. The approved redesign has six columns and 64px rows — an avatar, the name at 15px semibold over the address at 13px, one coloured count — and a side sheet for everything that changes. 1. **One state, one sign.** A switch shows its state itself. A label beside it saying "allowed" says it again, once per row. In the list, group by the state; the switch lives in the side sheet, with one sentence on what it does. Building block: `->groupBy()` with `.gk-table-group`; `.gk-toggle` with no `.gk-label` beside it, in a `.gk-setting` row (a Form toggle with a hint writes it). 2. **Read in the row, change in the sheet.** A row shows values as text. Selects, switches and delete belong in the side sheet the row opens — and a click anywhere on the row opens it, not only on its name. Building block: `->rowLink()`, i.e. `tr.gk-row-link` + `.gk-row-target`; `.gk-sheet` opened by `GK.sheet.open()`. 3. **Who: one cell, two lines.** Name and address belong together: an avatar, the name, the address underneath. In two columns both break mid-word. A `Table` column writes the two lines with `'sub' => 'email'`; with a label after the name, `.gk-cell-who` moves the label under the name instead of shortening it. Building block: `.gk-cell-who` with `.gk-avatar` + `.gk-cell-sub`. 4. **Colour only for what needs acting on.** Red means something is broken. Counts that are fine stay neutral text, and the breakdown goes in the sheet rather than in three coloured numbers per row. Building block: `.gk-label-red` for the one count that needs attention; `.gk-stat-tile-danger` in the sheet. 5. **Group instead of scrolling.** At most six columns at 1280px; nothing scrolls sideways. What is rarely needed folds into one row that stands for many — and records that are not like the others (profiles among users) are such a group. When the list itself gets narrow — a docked sheet, a phone — the least needed columns give way, by the list's width, not the window's. Building block: `.gk-table-group`; `tr.gk-table-more` with a `.gk-table-more-toggle`; `.gk-col-p2` … `.gk-col-p5` (a column's priority). 6. **Running text is never bold and never narrow.** A sentence in a list is set at normal weight and gets the width it needs (`minWidth` on its column); a second line of detail is quiet text, not a second column. Building block: `.gk-table` cells at weight 400 — add no bold; `.gk-cell-sub` for the second line. The row the rules were drawn from, measured: 64px tall, the whole row the click target (never under 44px), name 15/13px, at most six columns at 1280px, one colour — for what needs acting on. Since 1.92.0 that row is a class: `.gk-table-list` on the wrap (`->size('list')`), so a list needs no CSS of its own. A list that follows all six, by hand — a `Table` writes the same row with `->size('list')`, `->rowLink(['sheet' => 'user-sheet'])`, `'sub' => 'email'` and `'priority'` on the columns that may give way: ```html
UserPlanLast 30 days
With access5
jana@example.com
Life book 17 failing
``` ## Component Reference ### Table ```php // Static (client-side search/sort/pagination — for small datasets) (new Table('my-table')) ->setData($rows) // array of assoc arrays ->search(['name', 'email']) // plain-text column keys only! ->toolbarHtml('
' . Button::render('New', ['icon' => 'add', 'shape' => 'pill'])) ->column('name', 'Name', ['sortable' => true]) ->column('email', 'Email', ['sortable' => true]) ->column('status', 'Status', ['format' => 'html']) // HTML column: not searched ->button('edit', ['icon' => 'edit', 'params' => ['id' => 'id']]) ->button('delete', ['icon' => 'delete', 'params' => ['id' => 'id'], 'color' => 'danger']) ->paginate(25) ->caption('Customers') // what it is a table of — for screen readers only ->render(); ``` Give every table a `caption()` when a page has more than one: the heading above a table is not associated with it, and without a caption a screen reader announces "table" twice. Server-side, straight from MySQL — GridKit builds the `LIKE`, the `WHERE` for every declared filter, the `ORDER BY`, the `COUNT` and the `LIMIT`: ```php (new Table('users')) ->query($db, "SELECT id, name, email, role FROM users ORDER BY name") ->search(['name', 'email']) ->column('name', 'Name', ['sortable' => true]) ->column('email', 'Email', ['sortable' => true]) ->column('role', 'Role', ['format' => 'label']) ->button('edit', ['icon' => 'edit', 'params' => ['id' => 'id']]) ->paginate(25) ->render(); ``` **`filter($column, $type, $opts)`:** a dropdown in the toolbar, bound to the table — this is what "every declared filter" above means. `$type` is `'select'`; `$opts` takes `options` (value → label), `placeholder` (the empty "all" entry) and `label` (accessible name, defaults to the column's label). ```php ->filter('status', 'select', [ 'options' => ['open' => 'Open', 'paid' => 'Paid'], 'placeholder' => 'All statuses', ]) ``` The choice travels as `gk_filter_` and comes back selected after a reload. `setData()` filters in the browser, `query()` adds `` `column` = ? `` to the WHERE, and with `rows()` you read `$_GET['gk_filter_']` where you build the query. Use this for a status dropdown that belongs to a table — not `FilterChips` plus a GET parameter of your own. **⚠️ Search rule:** `search()` searches the column keys you name. If a column contains HTML (badges, links), use a separate plain-text key for search and a `_display` key for rendering. Never put HTML in searchable columns. **Column formats:** `currency`, `percent`, `date`, `datetime`, `boolean`, `label`, `html`, `email`, `number` **A second line inside a cell** (subject, account, reference) — never widens the column: `->column('name', 'Customer', ['sub' => 'city'])`, see below. By hand only where the truncated text needs a `title`, which the option does not write: ```html
Your receipt from Anthropic…
``` **Column `href` and `sub` (since 1.87.0):** the two commonest cell shapes, without building HTML by hand. ```php ->column('name', 'Customer', ['href' => '/customers/{id}', 'sub' => 'city']) ``` `href` wraps the formatted value in ``; `{field}` comes from the row, URL-encoded, and the same targets are allowed as for a row button. `{field}` is a path segment, never a whole target — a scheme belongs in the template, so a stored `https://…` cannot be linked this way. A cell that shows nothing gets no link. `href` and `'format' => 'html'` exclude each other: with html the caller writes the markup, links included, and wrapping that would nest anchors — GridKit leaves the link out and says so. `sub` names a second field, rendered as text under the value in `
` — always text, whatever the cell's format is, and left out when empty. It truncates with an ellipsis and carries no `title`; where the full text has to stay reachable, build that cell by hand. In a `setData()` table a column declared in `search()` searches its second line too, so a row can be found by the text standing under its name; in a `query()` table name the field in `search()` yourself — it has to be a real SQL column there. Both keep the raw value, so sorting and searching go on working — which is what `'format' => 'html'` costs you. There is no `target`: a link opens in the same tab, and middle click does the rest. **`->groupBy($column, $labels)`:** inserts a group row whenever the value changes. Sort the rows by that column first. **`->rowLink($target)` (since 1.91.0):** the whole row opens something — a page, or a side sheet on this page. Use it instead of putting selects, switches or a delete button into every row (see *Six rules for lists*). ```php ->rowLink('/users/{id}') // the row opens a page ->rowLink(['sheet' => 'user-sheet']) // … the side sheet #user-sheet ->rowLink(['sheet' => 'user-sheet', 'url' => 'panels/user.php', 'params' => ['uid' => 'id']]) ->rowLink(['href' => '/users/{id}', 'column' => 'name']) // which cell carries the control ``` The row is not made a control — `role=link` or a `tabindex` on a `` takes away its row role. Its main cell (the first column, or `'column'`) carries ONE real control, `` or ` locked anna@example.org
``` `.gk-avatar-tone-1` … `-5` give initials one of five quiet role pairs (primary, tertiary, info and warning containers, a raised surface) — pick by the person's id modulo 5, never by rank, so a person keeps their colour when the list is sorted. ### Server-side tables (`rows()` + `isAjaxReload()`) Three ways to get data into a table, in order of how much GridKit does for you: ```php ->setData($rows) // client-side: the browser gets everything and // searches, sorts and pages in JavaScript. // Fine up to a few hundred rows. ->query($db, $sql) // GridKit builds the SQL: LIKE for the search, // WHERE for every declared filter, ORDER BY, // COUNT and LIMIT. mysqli only. ->rows($pageRows, $total) // Table::rows() — you ran the query. PDO, SQLite, Postgres, an // HTTP API, an array — anything. Hand over one // page plus the total before LIMIT. ``` `rows()` and `query()` are both **server-driven**: search, filter, sort and paging go back to the server as URL parameters. Read them where you build the query: | Parameter | From | |---|---| | `gk_search` | the search box | | `gk_filter_` | a `filter()` dropdown | | `gk_sort` / `gk_dir` | a sortable column header | | `gk_page` | the pager | **The page must end the request itself.** The reload injects the response body straight into the table's wrapper, so it has to be the fragment and nothing else — otherwise your sidebar, header and script tags land inside the table: ```php $table = (new Table('invoices'))->rows($result['rows'], $result['total']); if (Table::isAjaxReload('invoices')) { $table->render(); // Anything outside the table that should keep up goes in a template, // addressed by a CSS selector. The matched element is replaced whole // (outerHTML), so the template body must itself re-emit an element the // selector matches — here the complete StatCards container, because // (new StatCards('invoice-stats'))->render() writes // data-gk-stats="invoice-stats" onto that container. Emitting only the // inner cards deletes the target on the first reload: no error, and the // stats silently keep their first-load values forever. echo ''; exit; } ``` `Table::isAjaxReload()` without an argument matches any table, which is enough when the page has one. A complete worked example is in [`examples/invoices/`](examples/invoices/). ### Status labels with their own text `labels` maps a stored value to a colour, or to a colour and the text to show — which is what a status column needs once the application runs in more than one language. The value stays `paid`; the cell reads whatever this locale calls it. ```php ->column('status', 'Status', ['format' => 'label', 'labels' => [ 'draft' => 'gray', // colour only 'paid' => ['color' => 'green', 'text' => $t('paid')], // colour + text ]]) ``` **The colours are a fixed list:** `gray`, `green`, `red`, `orange`, `blue`, `plain`. Anything else renders as an unstyled label — `primary`, `success`, `danger` and `warning` are Button and StatCards vocabulary and do **not** work here. **`$t('paid')` above is your own translator, not `Lang::t()`.** `Lang` holds GridKit's own interface strings — "Search…", "No entries found", "Delete". It is not a catalogue for your application, and `Lang::t('paid')` returns the string `paid` because there is no such key. See *Translating your own strings* below. Without a `labels` entry the colour is guessed from a built-in word list (English and German), and the raw value is shown. ### Button ```php // RETURNS a string — echo it. See "echo or return" at the top. echo Button::render('Label', [ 'variant' => 'filled', // filled | outlined | tonal | text 'color' => 'primary', // primary | success | danger | warning | neutral 'icon' => 'add', // Material Icon name 'size' => 'sm', // sm | md (default) | lg 'shape' => 'pill', // rounded (default) | pill | circle | square 'href' => '/path', // renders as 'onclick' => 'jsCode()', 'title' => 'Add a row', // tooltip 'aria' => 'Add a row', // accessible name; see below 'disabled' => false, 'type' => 'submit', // button (default) | submit | reset 'form' => 'form-id', // submit a form this button is NOT inside. // Setting it makes the button a submit button, // because a type="button" cannot submit anything // — the attribute would just sit there inert. ]); // A floating action button — round, fixed, bottom right. echo Button::fab('add', ['color' => 'primary', 'extended' => true, 'label' => 'New']); // Several buttons as one joined group. Button::group() takes finished button // strings and returns the wrapper — it renders nothing of its own. echo Button::group([ Button::render('Day', ['variant' => 'outlined', 'size' => 'sm']), Button::render('Week', ['variant' => 'outlined', 'size' => 'sm']), ]); // Icon-only: pass an empty label. GridKit gives it an accessible name from // the icon, translated for the active locale, so a screen reader does not // read the ligature. Pass 'aria' when the icon alone does not say what the // button does. echo Button::render('', ['icon' => 'delete', 'color' => 'danger']); echo Button::icon('content_copy', ['aria' => 'Copy the invoice number']); ``` ### Header The only component with no section here until 1.46.0, which is why an agent building a dashboard put two theme switchers on the page: `->user()` renders one of its own. **`Header::render()` RETURNS a string** — echo it. It is the one component you build with `new` that does not print (see *echo or return* at the top). ```php echo (new Header()) ->title('Dashboard') // or ->title($html, raw: true) ->breadcrumb(['Home' => '/', 'Invoices' => '/invoices', 'INV-2026-001']) ->sidebarToggle(true) // the hamburger that opens the Sidebar ->fixed(true) // stays at the top of the viewport ->sticky(true) // scrolls away, comes back on scroll up ->search('Search invoices…', 'q') // only for a page you filter yourself ->action(Button::render('New', ['icon' => 'add', 'size' => 'sm'])) ->action(Theme::switcher()) // ONLY if you skip the user menu — see below ->user('Jane Doe', [ 'role' => 'Administrator', // a non-clickable label at the top 'avatar' => '/img/jane.jpg', // initials are used when absent 'theme_switcher' => true, // DEFAULT — the menu carries its own switcher 'menu' => [ ['label' => 'Profile', 'href' => '/profile', 'icon' => 'person'], ['label' => 'Settings', 'href' => '/settings', 'icon' => 'settings'], 'divider', // exactly this string; anything else is ignored ['label' => 'Sign out', 'href' => '/logout', 'icon' => 'logout'], ], ]) ->render(); ``` **The name and role above are yours to supply — `Auth::user()` does not return this array.** It returns the *username* as a plain string, or `null` when nobody is signed in. There is no `name`, `role` or `id` on it, and `$me['role']` against it is a fatal `TypeError: Cannot access offset of type string on string`. The users file holds `username:bcrypt-hash` and nothing more, so a display name or a role has to come from a table of your own, keyed by that username: ```php $profiles = ['jsmith' => ['name' => 'Jane Smith', 'role' => 'Administrator']]; $user = Auth::user(); // 'jsmith', or null when signed out if ($user !== null) { // The fallback has to be a string: ->user() takes one, and handing it the // null that Auth::user() returns when nobody is signed in is a TypeError. $me = $profiles[$user] ?? ['name' => $user, 'role' => '']; echo (new Header())->user($me['name'], ['role' => $me['role']])->render(); } ``` **`->user()` already contains a theme switcher.** Adding `->action(Theme::switcher())` beside it puts twelve theme dots and two mode toggles on the page, with competing active states and no error. Pick one: | You want | Do | |---|---| | a user menu, switcher inside it | `->user($name, […])` — nothing else | | a switcher, no user menu | `->action(Theme::switcher())` | | a user menu with no switcher | `->user($name, ['theme_switcher' => false])` | **`->search()` is not a `Table` search.** It renders a plain input with a name; you read `$_GET['q']` and narrow the data yourself. A `Table` that declares `->search([…])` needs none of it — see the search rule under *TableHeader*. **A quiet line beside the title (`.gk-header-meta`, since 1.92.0)** — "2 users · 4 never used", on the title's baseline. It is the part that gives way: shortened with an ellipsis before the user menu is pushed off the edge, and gone at 768px and below. `Header::title()` writes the `

` only, so the line is for a header written by hand; it takes the breadcrumb's place — use one or the other. ```html

Users

2 users · 4 never used
``` **A header written by hand keeps the user menu BESIDE the actions**, the way `Header` writes it: `.gk-header-right` > `.gk-header-actions` + `.gk-header-user`. On a phone the actions row scrolls sideways (`overflow-x: auto`, so a squeeze cannot push buttons over the avatar), and anything that opens out of it is cut off — a user menu written inside it could not be seen or tapped at 402px. ```html
``` ### Sidebar `Sidebar::render()` PRINTS. It is `position: fixed`, so whatever sits beside it needs the wrapper — see *With a sidebar* above; without it the page renders underneath the sidebar, silently. ```php (new Sidebar('main')) // the id, for collapse state ->brand('My project', 'widgets', 'v2.1') // name, icon, optional version ->group('Navigation') // a heading; items follow it ->item('Dashboard', '?section=dashboard', 'dashboard', ['active' => true]) ->item('Invoices', '?section=invoices', 'receipt_long', ['badge' => 3]) ->item('Reports', '#', 'bar_chart', ['children' => [ ['label' => 'Monthly', 'href' => '/reports/monthly'], ['label' => 'Yearly', 'href' => '/reports/yearly', 'active' => true], ]]) ->divider() ->group('System') ->item('Settings', '?section=settings', 'settings') ->ajaxNav(true) // SPA-lite navigation, see below ->collapsePosition('bottom') // 'top' (default) | 'bottom' ->headerOffset(true) // start below a full-width header ->render(); ``` `->item($label, $href, $icon = '', $opts = [])` — the options are `active`, `badge`, `children` (a submenu, same item shape) and `id` (the submenu's DOM id; one is derived from the label otherwise). `Sidebar::toggleButton()` prints the hamburger for a page with no `Header`; `Header::sidebarToggle(true)` is the usual way. **No `onclick` (since 1.92.0).** The sidebar's controls carry `data-gk-sidebar-action="toggle"`, `"close"` or `"collapse"`, and gridkit.js answers them by delegation — so a page under a Content-Security-Policy without `'unsafe-inline'` keeps a working sidebar. A shell written by hand uses the same attribute instead of `onclick="GK.sidebar.toggle()"`; `GK.sidebar.toggle()`, `open()`, `close()` and `collapse()` stay the API. A toggle that carries `aria-expanded` is kept in step with the sidebar. ### Select `Select::searchable()` RETURNS a string — echo it. It is the standalone form of the widget `Form`'s `'select'` field type renders, for a `…') // raw HTML ->advanced(fn() => renderDateRange(), 'Date & amount') // optional collapsible ->reset('/expenses') // optional reset btn ->render(); ``` API: - `make($id)` static factory - `status(\Closure $renderer)`: top row, full width - `search(string $name, string $value = '', string $placeholder = '…', array $opts = ['live' => '…', 'id' => '…'])` - `filter($contentOrClosure)`: any number of toolbar slots — Closure (echo'd) or raw HTML string - `advanced(\Closure $renderer, string $summary = '', bool $open = false)` — an empty `$summary` takes the translated default ("Advanced filters" / "Erweiterte Filter"). Pass one only to override it. - `reset(string $baseUrl, string $label = '')` — an empty label uses the translation CSS classes (all auto-applied): `gk-tableheader`, `gk-tableheader-status`, `gk-tableheader-toolbar`, `gk-tableheader-advanced`, `gk-tableheader-spacer`. **Do NOT** build your own filter row with raw `gk-toolbar` / `gk-toolbar-stacked` if `TableHeader` fits — every table page must use this for visual consistency. ### StatCards ```php (new StatCards('stats-id')) ->card('Revenue', 12450.80, ['format' => 'currency', 'icon' => 'euro', 'color' => 'primary', 'trend' => '+12%']) ->card('Users', 1284, ['format' => 'number', 'icon' => 'people', 'color' => 'success', 'trend' => '+3.1%']) ->card('Errors', 3, ['format' => 'number', 'icon' => 'error', 'color' => 'danger', 'highlight' => true]) ->card('Rate', 78, ['format' => 'percent', 'icon' => 'speed', 'color' => 'warning']) ->card('Details', '/url', ['icon' => 'arrow_forward', 'href' => '/url']) // clickable ->render(); ``` **Colors:** `primary`, `success`, `danger`, `warning`, `info` **Formats:** `currency`, `number`, `percent` — each follows the active locale, so `12450.80` is `€12,450.80` under `en` and `12.450,80 €` under `de`. `number` rounds to whole numbers like the table column does; pass `'decimals' => 2` to keep some. `percent` shows the digits as given (`12.5` → `12,5 %` under `de`) or `'decimals'` of them — the same in a card and in a table column (`Table::percent()` is the one rule). **`trend`** is printed verbatim, exactly as you pass it — GridKit does no rounding, no sign and no percent sign of its own. A leading `-` colours it as a fall, anything else as a rise. So pass a finished string: `'+12%'`, `'-0.4%'`, `'▲ 3'`. Passing a raw float gives you a bare `-8` in the card. **`->compact()` (since 1.92.0)** renders the same `card()`s as compact tiles — a figure over its word, small enough for a side sheet or a card (`.gk-stat-tiles`, `.gk-stat-tile`). The cards stay the block for an overview page. ```php (new StatCards('user-lage')) ->compact() ->card('failing', 3, ['color' => 'danger']) // the one that needs acting on ->card('open', 12, ['sub' => 'for 3 days', 'href' => '#open']) ->card('done', 40) ->render(); ``` `format` and `decimals` work as on a card; `sub` is a quiet third line; `href` makes the tile a link. `'color' => 'danger'` or `'warning'` (also `'red'`, `'orange'`, and `'highlight' => true`) tones the tile — every other colour stays neutral, because a colour that means nothing costs the one that does (rule 4). `icon` and `trend` belong to the full card and are not shown. By hand a tile may also be a `
Content
'outlined', 'color' => 'neutral', 'onclick' => "..."]) ?>
``` **Footer:** action buttons at the end of a modal belong in `gk-modal-footer` — NOT `gk-form-actions` straight inside the modal, which has no side padding. A compatibility rule catches the old shape. ### Side sheet (`.gk-sheet`, since 1.91.0) Where a record is read in full and changed — the row itself only shows values. On a wide screen it docks at the right edge, 440px (`--gk-sheet-width` on `.gk-root`), and the list beside it stays usable and scrollable: a non-modal dialog. Below 769px it covers the screen and is modal — `aria-modal`, the focus held inside, the page behind it held still. Docked, it is part of the page and lies under the header: below a fixed or sticky GridKit header it starts where the header ends (`--gk-sheet-top`), and the header's user menu, a dropdown or a select list opened beside it lies over it. Give a page's own fixed bar a z-index above 150 if it has to stay over an open sheet. ```html ``` GridKit gives it the dialog role, names it by `.gk-sheet-title` and names a bare `×` close button, as it does for a static modal. `data-gk-sheet` on any button or link opens it (`data-gk-params`, `data-gk-sheet-url` and `data-gk-sheet-title` fill in the options); so does `->rowLink()`. Opening moves the focus to its title (a screen reader starts at the record's name, one Tab reaches the close button), Escape closes it while the focus is inside, and closing gives the focus back to what opened it. One sheet at a time: opening another closes the first. The row whose record it shows carries `aria-current="true"`. An AJAX form inside closes the sheet on `{ok: true}`, not the modal. Hidden is the `hidden` attribute. Without JavaScript the markup still works: render it without `hidden` and it is a docked panel, with a plain link in the close button's place. Add `.gk-sheet-push` to the content area if it should make room for a docked sheet instead of lying under it. **A line under the title (`.gk-sheet-meta`, since 1.92.0)** — the address, when the record last moved, a link. With it the header becomes a grid: the line sits under the title and the close button keeps its corner; links in it carry a dotted underline. The close button is `--gk-target-min` (44px) docked and on a phone. ```html

Anna Probe

anna@example.org · last seen today

``` ### Form (AJAX) ```php (new Form('user-form')) ->action('/api/save-user') ->method('POST') ->ajax() // REQUIRED for AJAX — without it the form does a native POST ->card() // optional: wrap the form in a gk-card. Leave it out inside a // modal or an existing card — Form::card() is off by default ->row() ->field('first_name', 'First name', 'text', ['width' => 8, 'required' => true]) ->field('last_name', 'Last name', 'text', ['width' => 8, 'required' => true]) ->endRow() ->field('email', 'Email', 'email', ['width' => 16]) ->field('role', 'Role', 'select', ['width' => 8, 'options' => ['admin' => 'Admin', 'user' => 'User']]) ->field('active', 'Active', 'toggle') ->submit('Save') ->render(); ``` **Field types.** Twelve have rendering of their own: `textarea` · `select` (searchable) · `multiselect` · `ajaxselect` · `checkbox` · `toggle` · `radio` · `file` (drag & drop) · `richtext` (CKEditor) · `color` · `range` · `choice` (answer tiles, since 1.92.0) Anything else becomes an ``, so every HTML type works: `text`, `number`, `email`, `tel`, `url`, `password`, `date`, `time`, `datetime` (rendered as `datetime-local`), `month`, `week`, `search`, `hidden`. A type that is neither of those raises an `E_USER_WARNING` and falls back to a text box — `'searchable-select'` was documented here for a long time, is not a type, and rendered as a plain text field without a word of complaint. The searchable select is plain `'select'`. **Field options** (the 4th argument of `field()`): | Option | Applies to | Effect | |---|---|---| | `width` | every field | columns out of 16 (default `16`); also `'auto'` or `'220px'` | | `required` | every field | red star + browser validation | | `value` | every field | pre-fill / pre-select. `multiselect` takes an array (or a comma string) and pre-checks the chips; a truthy value checks `checkbox`/`toggle`; `ajaxselect` needs `'displayValue' => 'Acme GmbH'` as well, or the box shows the id-less search field | | `placeholder` | input types, `select`, `multiselect`, `ajaxselect` | the input's placeholder — on `select` the empty-state text, on `multiselect`/`ajaxselect` the search box's. `textarea` and `richtext` are not in that list: they drop it silently, and `rows` is `textarea`'s only extra option | | `options` | `select`, `multiselect`, `radio` | `value => label` map | | `rows` | `textarea` | height in rows (default `3`) | | `preset` | `richtext` | `'full'` (default) or `'basic'` — how much toolbar | | `upload` | `richtext` | a URL. Turns pictures on: an upload button, drag & drop, paste, **alignment** (left/right with text flowing beside it, own line centred), size handles and alt text. Off without it, because an upload button with nowhere to put the file is worse than none. The endpoint takes a POST with the file under `upload` and answers `{"url":"https://…"}`, or `{"error":{"message":"…"}}` — CKEditor's SimpleUploadAdapter contract. **Return an absolute URL**: relative ones work on the page and break the moment the content is mailed. Pictures render as a plain `` in the paragraph with the size as an inline `style`, deliberately not as `
`, so the same content survives being sent as an e-mail | | `min`, `max`, `step` | `range`, `number`, `date`/`time` | bounds (`range` defaults to `0`/`100`/`1` and starts at `min`) | | `->cancel($label, $href)` | — | a link beside the submit button — a method, not a field | | `->hidden($name, $value)` | — | a hidden input — a method, not a field | | `error` | every field | a validation message, rendered red under the field. This is how a classic POST-redisplay shows errors: `['value' => $_POST['email'] ?? '', 'error' => $errors['email'] ?? '']`. The AJAX handler writes into the same slot, so both paths look identical | | `hint` | `toggle` | one sentence on what the switch does — the field becomes a settings row (`.gk-setting`): title and sentence on the left, the switch on the right, no label above it, and the input a `role="switch"` described by the sentence (since 1.92.0) | | `danger` | `toggle` with `hint` | marks a switch that locks someone out: the title in the error colour, the switch red when on | | `options` | `choice` | `value => label`, or `value => ['title' => …, 'hint' => …, 'mark' => …]`; the mark is A, B, C … by position unless given | | `multiple` | `choice` | checkboxes instead of radios, posted as `name[]`; `value` takes an array or a comma string. Cannot be `required` in the browser — GridKit warns and draws no star; check it on the server | **Form Density:** Add `gk-form-compact` class to a `
` or wrapper `
` for compact forms. All elements scale down proportionally: | Element | Normal | Compact | |---------|--------|---------| | Input height | 44px | 34px | | Input padding | 10px 14px | 6px 10px | | Input font | 14px | 13px | | Field margin | 20px | 10px | | Label size | 12px | 11px | | Toggle | 48×28px | 38×22px | | Checkbox | 20×20px | 16×16px | | Select display | 44px | 34px | ```html ...
...
...
...
``` **Settings and choices (since 1.92.0)** — the two fields a side sheet needs most: ```php (new Form('user-7')) ->field('login', 'Sign-in allowed', 'toggle', ['hint' => 'Takes effect at once, also on running sessions.', 'value' => 1]) ->field('lock', 'Lock the account', 'toggle', ['hint' => 'Signs the person out everywhere.', 'danger' => true]) ->field('next', 'What happens now?', 'choice', ['required' => true, 'options' => [ 'fix' => 'Fix it now', 'later' => ['title' => 'Later', 'hint' => 'Stays on the list until next week.'], ]]) ->render(); ``` A `choice` is a radio group (`role="radiogroup"`, named by the field's label) of `.gk-choice` tiles; each input is named by its mark and title and described by its hint. The tile carries the state and the focus ring; where `:has()` is missing the native control stays visible. **`->ajax()` is the opt-in.** It is what renders `data-gk-ajax` on the `
`, and `GK.form.bind()` binds the submit handler to nothing else. Leave it off and the form still renders and still validates, but the browser submits it natively and navigates to the action URL — the JSON below is then shown as a raw page. **Form endpoint must return JSON:** ```php echo json_encode(['ok' => true]); // success echo json_encode(['ok' => true, 'message' => 'Saved!']); // with toast echo json_encode(['ok' => false, 'errors' => ['email' => 'Already exists']]); // validation ``` ### Admin blocks: settings, figures, dots, colours (since 1.92.0) The small parts an admin page kept writing for itself — each a class, light and dark through roles, so a page needs no stylesheet of its own. The Form fields and `StatCards::compact()` above write the first three; by hand they look like this. **A setting (`.gk-setting`)** — rule 1 in the sheet: the switch alone, with one sentence on what it does. `-danger` for a switch that locks someone out. ```html
Sign-in allowed Takes effect at once, also on running sessions.
``` **A value that is only read (`.gk-field-static`)** — a field in the sheet that cannot be changed there, and why: ```html
Plan everything The superuser always has everything.
``` **Compact figures (`.gk-stat-tiles`)** — see `StatCards::compact()`. By hand, a tile that opens something is a `
``` As a definition list the word is the `
` and comes first, as HTML wants it — the figure still stands on top, and a `
` brings no indent: ```html
open
12
``` **A status dot (`.gk-dot`)** — a state or a presence beside its words, never instead of them (`aria-hidden`). Tones `-success`, `-warning`, `-danger`, `-primary`, `-muted`; `-outline` is an empty ring, told apart by its shape ("never"); `-pulse` for something running — it stands still under `prefers-reduced-motion`. ```html today 08:12 never running ``` **Chart colours (`--gk-series-1` … `-5`)** — five categorical slots, the same in every theme (a series follows its entity, never the accent), stepped separately for dark mode. Assign them in order and keep an entity on its slot when a filter removes others; a sixth series folds into "other". `.gk-swatch .gk-swatch-N` is the legend mark, `.gk-series-fill-N` / `.gk-series-stroke-N` colour an SVG mark. Slots 3 to 5 sit under 3:1 on a white ground, so a chart that uses them shows its values as text as well — figures in the legend, or a table. ```html Opus 60 % ``` **A finger-sized button (`.gk-btn-touch`)** — at least `--gk-target-min` (44px) in both directions, the type unchanged (`.gk-btn-lg` grows the text as well). **Actions in a message (`.gk-message-actions`)** — a place on the right of a `.gk-message` for what to do about it; the status band of a page is a message with a button. A long message takes its line and the actions move under it. Written by hand, an outlined button needs its colour class as well: `.gk-btn-outlined` alone has a transparent border (`Button::render()` always writes one). In a message an outlined button stands on the surface, not on the tinted band — its text colour is chosen for the surface (a warning's measured 4.35:1 on the band). **A small message (`.gk-message-sm`)** — for a notice that sits among other things and has to be seen: the sentence above a chat, a hint beside a form. It has the look of `.gk-message` (tone, tint, symbol, `.gk-message-header`) in a smaller box: padding 10px 14px, 13px text, a symbol one step down, and **no margin** — the surroundings set the spacing (`gk-mb-*` still works on it, and a flex column with `gk-gap-*` stacks several). The tone classes give the colours, so it takes all four and none. `.gk-message-compact` is a different thing and unchanged: it keeps the 16px margin of `.gk-message`. ```html
The conversation is stored on our server and never passed on.
``` ```html
2 runs are stuck.
``` **Answer tiles (`.gk-choice`)** — see the Form's `'choice'` field; by hand: ```html ``` **Shown on a phone only (`.gk-show-mobile`)** — the counterpart of `.gk-hide-mobile`: hidden above 768px, its own display below. **Hidden means hidden.** Every element with a `gk-` class disappears with the `hidden` attribute, whatever display its class gives it — `