Skip to content

Latest commit

 

History

History
146 lines (114 loc) · 7.22 KB

frontend-patterns.md

File metadata and controls

146 lines (114 loc) · 7.22 KB

Frontend Patterns (React/TypeScript)

Canonical frontend conventions for frontend/. Most are mechanically enforced. Deep how-to: ../../guides/frontend.md.

Pattern Rule Enforcement
Colors Theme classes only: bg-theme-*, text-theme-* hardcoded-color-check.sh + pattern-validation.sh
Navigation Flat structure — no submenus pattern-validation.sh
Actions ALL in PageContainer — none in page content review
State Global notifications only — no local success/error review
Imports Path aliases for cross-feature: @/shared/, @/features/; an extension's own tree via its alias (@system/) pattern-validation.sh (extension trees, public and private; three or more ../ fails) + convert-relative-imports.sh (on-demand fixer, core only)
Logging No console.* at any level — use import { logger } from '@/shared/utils/logger' console-log-check.sh + pattern-validation.sh (both via scripts/list-console-sites.sh)
Types No any — proper TypeScript types required no-any-type-check.sh + pattern-validation.sh

Imports: why the alias, and what actually enforces it

This row used to cite scripts/convert-relative-imports.sh as the enforcement. That script is real and useful, but it never enforced anything, for three separate reasons — and each one alone is enough:

  1. Nothing fails on it. No hook, gate or CI step runs it. The only caller is the /cleanup all skill (.claude/skills/cleanup/SKILL.md:38), which a person invokes on demand and which rewrites files rather than failing.
  2. It cannot see an extension. It hardcodes SRC_ROOT="frontend/src", so it never descends into extensions/*/frontend/src.
  3. It cannot emit the alias this row is about. Its output alphabet is @/shared/ and @/features/ only (scripts/convert-relative-imports.sh:68-83); there is no branch that can ever produce @system/.

It stays the right tool for converting core by hand. The row now also cites the scan that actually fails a build.

With no gate reaching them, the system extension had drifted to 61 imports climbing three or more directories, across 30 files (IMP-003653cb5634).

Three climbs is the threshold. ../../types stays inside a feature and reads as local; ../../../ has already left it, and that is the form that breaks on a move — silently, because TypeScript resolves whatever the new path lands on and a file moved one level can start importing a different module that still type-checks.

The scan covers PUBLIC and private extension frontends. An earlier draft covered public trees only, justified by the rule that a tracked core file may not name a private extension — true, and already solved by the SPLIT LEDGER the console-log and core-purity guards use: known debt is grandfathered per file with a count in .claude/hooks/deep-relative-import-baseline.txt, and private paths go in the gitignored .local.txt sibling beside it. Excluding them would have left 125 of the 128 offending files fleet-wide unguarded.

The ledger is a ratchet in BOTH directions. A listed file that grows fails; a listed file that shrinks, is fixed or is deleted fails too, so an entry cannot outlive the debt it describes. A missing tracked baseline fails closed. Only single-quoted from '...' is matched; a double-quoted or dynamic import() form is a known, accepted gap.

Logging: the console ledger

The rule is every console level, not just log. It used to be log/debug/info only, in three places that each kept their own copy of the pattern, so console.warn and console.error accumulated for the life of the tree while every guard reported clean (IMP-1f4b84af602c).

scripts/list-console-sites.sh is now the single definition of what counts; the edit hook and the pattern-validation.sh check both call it. Sites that already existed are grandfathered in two ledgers — .claude/hooks/console-log-baseline.txt (tracked, core and public extensions) and .claude/hooks/console-log-baseline.local.txt (gitignored, private extensions, whose paths must not reach the public mirror).

If the gate fails with "N new console call(s)", the fix is the logger, not the ledger. Regenerate the ledgers only when you have legitimately REMOVED sites:

bash scripts/generate-console-log-baseline.sh

Entries are path|source line, one per occurrence, so a third copy of an already-grandfathered line is still a new site.

Access control (CRITICAL — kept in CLAUDE.md core)

Frontend MUST use permissions ONLY — NEVER roles for access control:

// ✅ CORRECT
currentUser?.permissions?.includes('users.manage')

// ❌ FORBIDDEN
currentUser?.roles?.includes('admin')
user.role === 'manager'

Backend: current_user.has_permission?('name') — NEVER permissions.include?() (returns objects). Advisory nudge: permission-not-roles-check.sh. The principle stays in the core because it is a security boundary; the hook is a backstop, not the source of truth.

Extension state (Redux)

Extensions compose into the platform through featureRegistry — routes, nav items, settings tabs, channels, component slots. State is the same shape of seam, via injectReducer from @/shared/services.

An extension that defines a Redux slice must register its reducer, or the slice exists nowhere and every selector reading it gets undefined. That is not hypothetical: an extension shipped a complete slice mounted in no store, and it went unnoticed only because nothing rendered the components that would have thrown on first render.

// extension register() — beside the featureRegistry calls
import { injectReducer } from '@/shared/services';
import billingReducer from '@myext/shared/slices/billingSlice';

export function register(): void {
  injectReducer('billing', billingReducer);
  featureRegistry.registerRoutes('myext', [ /* ... */ ]);
}

Type it from the extension side — core must never name an extension, so it exposes an empty, augmentable ExtensionState that declaration merging fills:

// beside the slice
declare module '@/shared/services' {
  interface ExtensionState {
    billing: BillingState;
  }
}

Three properties worth understanding rather than working around:

  • Ordering is already safe. register() runs synchronously at module load (extensionLoader's eager glob), and runtime extensions are awaited in index.tsx — both before the first render. A reducer injected from register() is present before anything selects it.
  • RootState applies Partial<> to extension state, deliberately. Slices genuinely do not exist until register() runs, and a runtime extension that exceeds the boot timeout registers after the first render. So read with ?. and a fallback. Asserting the slice is present would type-check and then throw — the exact failure this seam replaced.
  • injectReducer is idempotent. Re-registering a key is a no-op, so HMR and a double-invoked register() cannot reset live slice state.

Do NOT create a second store inside an extension. Two stores means two sources of truth, and breaks devtools and cross-cutting selectors.

Covered by frontend/src/shared/services/injectReducer.test.ts.