Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs(frontend): enforce canonical table guidance

Josuéd90d48e93430
diff --git a/docs/agents/control-ui-rules.md b/docs/agents/control-ui-rules.md
index fc54ed8e2..0db78e4ce 100644
--- a/docs/agents/control-ui-rules.md
+++ b/docs/agents/control-ui-rules.md
@@ -66,24 +66,26 @@ leaning on either behaviour.
## Tables and row actions
+- Use `@clerum/frontend-table-system` directly or the thin Control UI adapters
+ `TablePanelHeader`, `TableHeaderRow`, `SectionSearchInput`, and
+ `RowActionsMenu`. Those adapters preserve Control UI labels/routes/classes;
+ they do not own a second semantic table implementation.
- Column headers use `--cu-font-size-2xs`, semibold, uppercase, `0.05em`
- letter-spacing. A sortable header is a button with the same type treatment as
- a static one; sorting is signalled by the arrow and a hover color, never by a
- different font size or casing.
+ letter-spacing. Shared sortable headers own the button, indicator, and
+ `aria-sort` semantics.
- Right-align numeric columns and set `font-variant-numeric: tabular-nums` so
digits line up.
- Keep the table element and its header row mounted through loading, empty, and
error states. Only the body changes. An empty result renders a full-width row,
not an unmounted table.
-- Render row actions with `RowActions`. It fixes the order by `kind` (utility,
- then edit, then destructive, then inspect) regardless of array order, supplies
- the right-edge chevron for `inspect`, and collapses everything except
- destructive and inspect into a kebab past `overflowAfter`. Set `hidden` to drop
- an affordance a row cannot support rather than rendering a disabled one.
-- The chevron is the only affordance for opening a detail view. Do not add a
- name link, a left-edge chevron, or a row click as a second route.
-- `app/cost-and-usage/llm-prices` is the reference implementation for a route
- table, including state-dependent row affordances.
+- Ordinary resource rows use `TableRow` (or equivalent shared keyboard
+ behavior) for detail navigation. Stop propagation inside the actions cell so
+ opening a menu never navigates the row.
+- Render all per-record operations with `RowActionsMenu`; do not restore inline
+ edit/delete icon clusters or the removed `RowActions` overflow heuristic.
+- Do not restore `cu-expandable-table`, expandable record rows, or inline detail
+ `<tr>` sections. Move record details to the canonical route; use a modal only
+ for a bounded action that must complete without leaving the list.
## Routing
@@ -99,7 +101,8 @@ leaning on either behaviour.
## Page patterns
-- Use `TablePanelHeader` and `TableHeaderRow` for route tables and sections.
+- Use `TablePanelHeader` and `TableHeaderRow` for route tables and sections;
+ both delegate their semantic behavior to the shared table package.
- Keep the section icon, title, subtitle, search, refresh, and CTAs visible
while initial loading, empty, and error states render in the content area.
Disable header CTAs during initial loading, and let only the content pane
diff --git a/docs/agents/frontend-style-rules.md b/docs/agents/frontend-style-rules.md
index 393228d3e..952e48e89 100644
--- a/docs/agents/frontend-style-rules.md
+++ b/docs/agents/frontend-style-rules.md
@@ -80,6 +80,66 @@ application guidance that must be combined with this shared document.
brightness-filter controls. Use background, border, text color, and shadow
tokens instead of `transform`, `translate`, `top`, `margin`, or `filter`.
+## Tables and record lists
+
+- `packages/frontend-table-system` is the shared semantic and visual boundary
+ for Control UI and Profile UI tables and table-like record lists. Import its
+ `DataViewHeader`, `TableSearch`, `TableViewport`, `DataTable`, `TableRow`,
+ table cells/state rows, `RecordList`, `RecordListRow`, `RowActionMenu`, and
+ sorting helpers instead of creating an application-local table system.
+- Use a semantic `DataTable` for comparable columns and `RecordList` for a
+ repeated record layout that does not need column headers. Do not write raw
+ production `<table>` markup in either web application. Choose the standard,
+ navigable, selection/permission, hierarchy/file, or embedded/diagnostic
+ behavior deliberately; do not encode variants as a growing set of unrelated
+ boolean props.
+- Keep the title, description, search, refresh, and primary CTA in one
+ `DataViewHeader`-based toolbar. Loading, empty, and error states belong in the
+ table/list content area and must not remove the toolbar. Use the established
+ search input and at most the application's primary, secondary, and
+ tertiary/ghost page-action variants. Place route-backed tabs below the page
+ identity and toolbar, and flatten category-wrapper plus child-list double
+ tabs into sibling destinations when no information-architecture decision is
+ required.
+- Fill the available content width. Keep fixed widths for genuinely compact
+ numeric, status, selection, icon, and action cells; allow ordinary text
+ columns to size flexibly. Put secondary metadata such as descriptions,
+ emails, providers, aliases, or namespaces in accurately named columns rather
+ than stacking it under a primary label. Truncate bounded, non-critical text
+ only when its complete value remains accessibly available.
+- Make ordinary record rows navigate to their dedicated detail route. Do not
+ use inline master/detail expansion for normal record tables; reserve
+ expansion or hierarchy for a genuinely specialized tree, file, permission,
+ or selection workflow. Child links, buttons, checkboxes, and menus keep their
+ own destinations/actions and must not activate the row. Remove redundant
+ same-destination inspect links and chevrons.
+- Put every record-specific operation in the shared, accessible three-dot
+ `RowActionMenu` at the far right. The menu includes the detail action when the
+ row itself navigates and has other actions; put that detail action first and
+ keep destructive actions clearly labelled.
+- Use stable sorting with a deterministic default and `aria-sort` for every
+ meaningful data column. Fully loaded collections sort locally without a
+ refetch. Producer-backed paginated data must sort at the producer/API
+ boundary before cursor slicing, bind cursor continuation to the selected
+ order, and reset pagination when ordering changes; sorting only the loaded
+ page is not authoritative.
+- Keep standard rows compact and consistent. Use `TableViewport` for horizontal
+ overflow and for long-list body scrolling so the page title, toolbar, tabs,
+ and semantic sticky table header remain visible. Embedded/diagnostic views
+ may use the less restrictive viewport mode when page-level scrolling is the
+ appropriate contract.
+- Inline record expansion is not a storage location for data. Promote small
+ facts to columns, expose bounded text with an accessible full-value
+ affordance, and move large structured content to the canonical detail route.
+- Preserve specialized selection, permission, file, and tree semantics as
+ explicit variants. Sharing the foundation does not make those workflows
+ ordinary navigable record tables. Embedded diagnostic tables share the
+ structure and typography but may retain product-defined chronological order
+ or local toolbar placement.
+- After migrating a family, prove the superseded component, selector, helper,
+ expansion state, and tests have zero production consumers before deleting
+ them. Do not create a parallel app-local table shell for convenience.
+
## Utilities
- Search the target application's `lib/` before adding string helpers such as
diff --git a/docs/agents/profile-ui-rules.md b/docs/agents/profile-ui-rules.md
index d8269affc..f10c4b718 100644
--- a/docs/agents/profile-ui-rules.md
+++ b/docs/agents/profile-ui-rules.md
@@ -14,8 +14,24 @@ These provider-neutral rules apply only to `profile-ui/**`. Combine them with
folders with `index.tsx` and colocated support such as `types.ts`. Do not
migrate Profile UI to Control UI's `components/ui/` structure.
- Reusable configuration constants live under `app/constants/`.
-- Reuse Profile UI's existing primitives, including `Button`, `TextInput`,
- `SelectControl`, `FormField`, and `EditableList`.
+- Reuse Profile UI's existing form primitives, including `Button`, `TextInput`,
+ `SelectControl`, and `FormField`. Use `@clerum/frontend-table-system` for
+ tables and repeated record lists; the obsolete local `EditableList` has been
+ removed.
+
+## Tables and record lists
+
+- Use the shared `DataTable`/`TableHeaderCell` contract for member, invitation,
+ and permission matrices. Use `RecordList`/`RecordListRow` for settings and
+ connected-account rows that do not need comparable column headers.
+- Ordinary member rows navigate to `PROFILE_ROUTES` detail destinations and
+ place every record-specific operation in the shared `RowActionMenu`.
+- Preserve permission checkboxes and invitation selection as specialized table
+ interactions. They remain explicit controls and must not trigger row
+ navigation.
+- Do not recreate `.members-table` styling or a Profile-only table primitive;
+ use shared modifiers such as `eft-table--wide` and keep only genuine
+ Profile-specific presentation in `app/globals.css`.
## Routing
diff --git a/scripts/style-rules/README.md b/scripts/style-rules/README.md
index 2954b078a..246560c87 100644
--- a/scripts/style-rules/README.md
+++ b/scripts/style-rules/README.md
@@ -16,16 +16,19 @@ as `scripts/prettier/run-on-staged.mjs` — chosen because:
## What's enforced today
-Scope: `desktop-app/ui/**` only.
-
-| Rule ID | Severity | What it catches |
-| --------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
-| `da-no-hex-in-css` | error | `color: #abc` / `border: 1px solid #fff` outside `tokens.css` and the 3 legacy files. |
-| `da-no-raw-font-size` | error\* | `font-size: 14px` / `font-size: 1rem` outside `tokens.css`. Use `var(--font-size-*)`. |
-| `da-no-new-component-css` | error | New `.css` files under `desktop-app/ui/src/` other than the 5 allowlisted ones. |
-| `da-no-hover-motion` | error | Hover states that move, scale, or filter controls. Use background/border/text/shadow token changes. |
-| `da-no-hex-in-tsx` | warn | Hex literals in TS/TSX strings. Reviewer judgment for genuinely dynamic cases. |
-| `da-no-static-inline-style` | warn | JSX `style={{...}}` not containing `--da-grid-cols` or whitelisted runtime values. |
+Scope: `desktop-app/ui/**` plus the shared table-system boundary for production
+source under `control-ui/**` and `profile-ui/**`.
+
+| Rule ID | Severity | What it catches |
+| ------------------------------ | -------- | --------------------------------------------------------------------------------------------------- |
+| `da-no-hex-in-css` | error | `color: #abc` / `border: 1px solid #fff` outside `tokens.css` and the 3 legacy files. |
+| `da-no-raw-font-size` | error\* | `font-size: 14px` / `font-size: 1rem` outside `tokens.css`. Use `var(--font-size-*)`. |
+| `da-no-new-component-css` | error | New `.css` files under `desktop-app/ui/src/` other than the 5 allowlisted ones. |
+| `da-no-hover-motion` | error | Hover states that move, scale, or filter controls. Use background/border/text/shadow token changes. |
+| `da-no-hex-in-tsx` | warn | Hex literals in TS/TSX strings. Reviewer judgment for genuinely dynamic cases. |
+| `da-no-static-inline-style` | warn | JSX `style={{...}}` not containing `--da-grid-cols` or whitelisted runtime values. |
+| `web-no-app-local-table` | error | Raw production `<table>` shells in Control UI or Profile UI instead of the shared table system. |
+| `web-no-retired-table-pattern` | error | Production references to retired app-local table, row-action, tab, or expansion families. |
\*`da-no-raw-font-size` is downgraded to `warn` for the 3 legacy CSS files
to allow boy-scout migration without forcing one big-bang cleanup.
@@ -68,10 +71,10 @@ has the shape:
}
```
-To extend coverage to `control-ui` or `profile-ui`, broaden the `applies`
-predicates and update the allowlist constants. **Do this only after** the
-target app's pattern doc exists — rules without docs cause drift, not
-prevent it.
+Control/Profile checks deliberately exclude tests, E2E fixtures, mocks, and
+the shared package implementation itself. They enforce the documented
+application boundary without banning semantic table markup inside the shared
+system or legitimate non-table disclosure controls.
## Why not Stylelint?
diff --git a/scripts/style-rules/rules.mjs b/scripts/style-rules/rules.mjs
index 290e725e8..563bf3f22 100644
--- a/scripts/style-rules/rules.mjs
+++ b/scripts/style-rules/rules.mjs
@@ -19,6 +19,38 @@ const STYLE_PROP_OPEN = /\bstyle=\{\{/
const MOTIONLESS_HOVER_PROPS = new Set(['filter', 'transform'])
const DESKTOP_UI_PREFIX = 'desktop-app/ui/'
+const WEB_APP_PREFIXES = ['control-ui/', 'profile-ui/']
+const WEB_APP_SOURCE_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx']
+const WEB_APP_NON_PRODUCTION_SEGMENTS = [
+ '/__tests__/',
+ '/e2e/',
+ '/fixtures/',
+ '/mocks/',
+ '/test/',
+ '/tests/',
+]
+const WEB_LEGACY_TABLE_PATTERNS = [
+ {
+ pattern: /\bcu-expandable-table\b|\bcu-expandable-row__[^\s'"`}]*/,
+ message: 'retired Control UI expandable-table class',
+ },
+ {
+ pattern: /\bmembers-table(?:__[a-z0-9-]+)?\b/,
+ message: 'retired Profile UI members-table class',
+ },
+ {
+ pattern: /(?:\b|\/)EditableList(?:\b|\/)/,
+ message: 'retired Profile UI EditableList component',
+ },
+ {
+ pattern: /(?:\b|\/)LlmSecretsSubTabs(?:\b|\/)/,
+ message: 'retired Control UI LlmSecretsSubTabs component',
+ },
+ {
+ pattern: /(?:from\s+['"][^'"]*\/RowActions['"]|<RowActions(?:\s|\/|>))/,
+ message: 'retired Control UI RowActions component',
+ },
+]
// Files where defining hex color tokens is the whole point.
const TOKEN_FILES = ['desktop-app/ui/src/styles/tokens.css']
@@ -67,6 +99,13 @@ function isTsxTarget(file) {
return file.endsWith('.tsx') || file.endsWith('.ts')
}
+function isWebProductionSource(file) {
+ if (!WEB_APP_PREFIXES.some(prefix => file.startsWith(prefix))) return false
+ if (!WEB_APP_SOURCE_EXTENSIONS.some(extension => file.endsWith(extension))) return false
+ if (file.endsWith('.d.ts')) return false
+ return !WEB_APP_NON_PRODUCTION_SEGMENTS.some(segment => file.includes(segment))
+}
+
function collectHoverMotionViolations(line, lineNumber) {
const violations = []
for (const declarationText of line.split(';')) {
@@ -84,6 +123,51 @@ function collectHoverMotionViolations(line, lineNumber) {
}
export const rules = [
+ {
+ id: 'web-no-app-local-table',
+ severity: 'error',
+ description:
+ 'Control UI and Profile UI production views must use @clerum/frontend-table-system instead of raw app-local table markup.',
+ applies(file) {
+ return isWebProductionSource(file)
+ },
+ check({ lines }) {
+ const violations = []
+ lines.forEach((line, i) => {
+ if (/<table(?:\s|>)/.test(line)) {
+ violations.push({
+ line: i + 1,
+ message:
+ 'raw <table> creates a parallel table shell — compose @clerum/frontend-table-system DataTable primitives',
+ })
+ }
+ })
+ return violations
+ },
+ },
+ {
+ id: 'web-no-retired-table-pattern',
+ severity: 'error',
+ description:
+ 'Retired Control/Profile table wrappers and inline-expansion families must not regain production consumers.',
+ applies(file) {
+ return isWebProductionSource(file)
+ },
+ check({ lines }) {
+ const violations = []
+ lines.forEach((line, i) => {
+ for (const legacy of WEB_LEGACY_TABLE_PATTERNS) {
+ if (legacy.pattern.test(line)) {
+ violations.push({
+ line: i + 1,
+ message: `${legacy.message} — use @clerum/frontend-table-system`,
+ })
+ }
+ }
+ })
+ return violations
+ },
+ },
{
id: 'da-no-hex-in-css',
severity: 'error',
diff --git a/scripts/style-rules/rules.test.mjs b/scripts/style-rules/rules.test.mjs
new file mode 100644
index 000000000..502771a18
--- /dev/null
+++ b/scripts/style-rules/rules.test.mjs
@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { rulesForFile } from './rules.mjs'
+
+function violationsFor(file, content) {
+ const lines = content.split(/\r?\n/)
+ return rulesForFile(file).flatMap(rule =>
+ rule.check({
+ file,
+ content,
+ lines,
+ })
+ )
+}
+
+test('rejects raw production tables in Control UI and Profile UI', () => {
+ assert.equal(
+ violationsFor('control-ui/app/agents/page.tsx', '<table><tbody /></table>').length,
+ 1
+ )
+ assert.equal(violationsFor('profile-ui/app/members/page.tsx', '<table />').length, 1)
+})
+
+test('allows shared table-system composition and test fixtures', () => {
+ const shared = '<DataTable><TableBody /></DataTable>'
+ const fixture = '<table><tbody /></table>'
+
+ assert.deepEqual(violationsFor('control-ui/app/agents/page.tsx', shared), [])
+ assert.deepEqual(violationsFor('profile-ui/__tests__/members.test.tsx', fixture), [])
+ assert.deepEqual(violationsFor('packages/frontend-table-system/src/DataTable.tsx', fixture), [])
+})
+
+test('rejects retired production table and expansion families', () => {
+ const examples = [
+ ['control-ui/components/McpServerTable.tsx', 'className="cu-expandable-table"'],
+ ['control-ui/components/ContextTable.tsx', 'className="cu-expandable-row__name"'],
+ ['profile-ui/app/members/page.tsx', 'className="members-table__row"'],
+ ['profile-ui/app/settings/page.tsx', "import EditableList from './EditableList'"],
+ ['control-ui/app/secrets/page.tsx', '<LlmSecretsSubTabs />'],
+ ['control-ui/components/Hosts.tsx', "import RowActions from './RowActions'"],
+ ]
+
+ for (const [file, content] of examples) {
+ assert.equal(violationsFor(file, content).length, 1, `${file} should be rejected`)
+ }
+})
+
+test('does not confuse RowActionsMenu with the retired RowActions component', () => {
+ assert.deepEqual(
+ violationsFor(
+ 'control-ui/components/Hosts.tsx',
+ "import { RowActionsMenu } from '@evenfire/frontend-table-system'\n<RowActionsMenu />"
+ ),
+ []
+ )
+})
diff --git a/scripts/style-rules/run-all.mjs b/scripts/style-rules/run-all.mjs
index e74ef724e..cf368c1f6 100644
--- a/scripts/style-rules/run-all.mjs
+++ b/scripts/style-rules/run-all.mjs
@@ -3,8 +3,8 @@
* Manual / CI entry: run style-rules across the full repo tree (all files
* the rules in rules.mjs claim to cover via `applies()`).
*
- * Currently scoped to desktop-app/ui — extend rules.mjs to add coverage
- * for control-ui / profile-ui when their patterns consolidate.
+ * Covers Desktop renderer style invariants plus the shared Control/Profile
+ * table-system boundary.
*/
import { spawnSync } from 'node:child_process'
import { dirname, resolve } from 'node:path'