ali
/
jey_theme
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
jey_theme/CLAUDE.md

13 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this app is

Frappe/ERPNext v15 app that does three things:

  1. Overrides the desk UI with a multi-theme visual system (CSS + JS bundle).
  2. Hides the Quality Management and Subcontracting modules app-wide (URL/API/bootinfo/permissions).
  3. Maintains a custom Taxes Az workspace on every migrate.

Installed into frappe-bench as a normal app. Python code is at jey_theme/ (Frappe app package). Frontend assets live at jey_theme/public/{css,js}.

Commands

Run from frappe-bench/ (the bench root), not this app dir.

  • bench build --app jey_theme — required after CSS edits (jey_theme.bundle.css → hashed file in public/dist/css/). JS is served raw and needs only a hard reload.
  • bench migrate — runs the after_migrate hook that rebuilds the Taxes Az workspace from setup/taxes_workspace.py.
  • bench execute jey_theme.setup.taxes_workspace.setup — re-run the workspace setup without a full migrate.
  • bench restart — reload Python workers after editing access_control.py or hooks.py.
  • No test suite, no linter config in this repo.

Architecture

Python: access control (jey_theme/access_control.py + hooks.py)

Goal: make blocked modules invisible and unreachable for every user, including Administrator.

  • BLOCKED_MODULES / BLOCKED_DOCTYPES_EXTRA — edit these frozensets to change what's blocked.
  • Three defense layers wired in hooks.py:
    • before_request — blocks /api/resource/<Doctype>, /app/<slug>, and form_dict-based calls at the HTTP boundary (catches Administrator, who bypasses has_permission).
    • has_permission = {"*": ...} — per-doc deny for non-admin users who have role access.
    • extend_bootinfo — strips blocked items from allowed_modules, modules, user.can_*, workspaces.pages, workspace_sidebar_item, module_wise_workspaces, app_data, desktop_icons, etc., so the client router/sidebar never sees them.
  • Slug/doctype/workspace sets are cached on frappe.local per-request.
  • When adding a new block vector: extend extend_bootinfo rather than relying only on has_permission, because the client has many independent boot-derived UIs.

Python: desk layout engine (jey_theme/desk_layout.py + desk_overrides.py)

Configurable, non-destructive (variant A) control of desk workspaces/cards/links, driven by a JSON config. Lets a System Manager, inline on /desk, hide, block, add and reorder links. The companion editor is the separate jey_layout app (install on the design machine only); the engine here is enforced on every site. The Workspace DB records are never modified — fully reversible, survives ERPNext migrations (everything is applied at request time, server-side → no client flash).

Config (jey_theme/config/desk_layout.json = shipped snapshot; per machine the editor writes a working copy in jey_layout/config/desk_layout.json):

{ "workspaces": { "<ws>": {
    "state": "visible|hidden|blocked",
    "cards": { "<untranslated card label>": {"state": "visible|hidden"} },
    "links": { "<Type>::<link_to>": {"state": "visible|hidden|blocked"} },  // hide/block of any link
    "added": { "<Type>::<link_to>": {"link_type","link_to","label","card"} },// injected links
    "order": { "<card label>": ["<key>", ...] }                              // per-card link order
} } }

Key for every link = link_type::link_to (Type ∈ DocType/Report/Page).

  • hide = the item is filtered OUT of the data the server sends (sidebar / get_desktop_page cards+links) → absent in the DOM. URL still works.
  • block = ALSO denied at the access layer, gated to PRODUCTION only (where jey_layout is absent / jey_design_mode is 0; the design machine keeps access so admins can manage). Two enforcement paths:
    • doctypes → permission_query_conditions (* → returns 1=0, so the list is EMPTY for everyone incl. System Manager) + has_permission (per-doc deny, every ptype: read/create/write/delete) + extend_bootinfo (stripped from can_*). NOT before_request: a blunt URL/API block on a doctype breaks search_link/dynamic links, whereas permission hooks are bypassed by ignore_permissions so those internal reads keep working. Code-enforced ⇒ SM-proof (lives in code+config, not DocPerm, so a System Manager can't undo it from the UI). Administrator is the only break-glass bypass.
    • reports / pages / workspaces → before_request (HTTP/URL/API, catches Administrator too) + has_permission (per-doc). Truly unreachable for everyone.
  • add / reorder = structural overlay: get_desktop_page injects added links into their card and reorders per order. Applied ALWAYS (even in edit mode); only hide/block is gated by enforcement.

Files

  • desk_layout.py — loads config; _cache()/_build() parse it ONCE per request (ungated, fail-open) into hide/block sets on frappe.local. Two accessor families with DIFFERENT gates: VISUAL overlay (should_hide_*, hidden_or_blocked_workspaces) is gated on is_enforcing(); ACCESS-block (prod_blocked_doctypes/_reports/ _pages/_workspaces) is gated on not is_design_mode() (block bites on prod only). _ws_entry() + added_links()/order_map()/apply_order() are the structural (always-on) overlay. is_enforcing(): production → always; design machine → not is_editing() (Redis key jey_layout_editing). is_design_mode() defaults to ON exactly when the jey_layout app is installed (test machines); jey_design_mode in site_config overrides (0/1). Tolerates missing refs.
  • desk_overrides.py — wraps get_workspace_sidebar_items/get_desktop_page via override_whitelisted_methods. get_desktop_page does inject → reorder (always) → hide/block filter (only when enforcing). _build_link_item shapes an injected link like frappe's so the client renders it natively. Card labels in output are translated, so matching forward-translates config labels (_(label)).
  • access_control.py — enforcement. Static BLOCKED_MODULES (Quality/Subcontracting)
    • config reports/pages/workspaces are denied at before_request (HTTP, catches Administrator) and has_permission. Config-blocked doctypes are denied via permission_query_conditions (* → 1=0) + has_permission (per-doc) ONLY — not before_request (keeps search_link/dynamic links working). extend_bootinfo strips blocked modules/doctypes (can_*) and hidden/blocked workspaces from boot, and sets bootinfo.jey_design_mode. All hooks are wrapped fail-open (never break the desk; has_permission returns True on error, before_request re-raises only the intended PermissionError; errors → Error Log).

Edit vs applied model (no "preview"): on the design machine, the normal desk is the applied result; "✎ Edit layout" flips jey_layout_editing and reloads to show all items + controls; "✓ Done editing" reloads back to applied. Export copies the working file into this snapshot for shipping.

⚠️ Edge gotcha — DO NOT load the editor via app_include. app_include_js/css assets are added to the HTTP Link: rel=preload response header. On this deployment the desk's total response headers are ~4 KB and the edge proxy's proxy_buffer_size is 4 KB; two extra app_include entries pushed it over → 502 "upstream sent too big header" (local nginx has a bigger buffer, so it only failed through the edge). Instead jey_theme.js loads jey_layout's JS/CSS dynamically (design mode only, via bootinfo.jey_design_mode), adding nothing to the header. Proper infra fix (not required by the app): raise the edge's proxy_buffer_size/large_client_header_buffers.

Python: Taxes Az workspace (jey_theme/setup/taxes_workspace.py)

Idempotent setup run via after_migrate.

  • Builds a Workspace named Taxes Az with six cards (Declarations, Setup, Tools, E-Taxes Setup, E-Taxes Reference, E-Taxes Documents), a Workspace Sidebar listing every doctype, and a Desktop Icon that routes via the sidebar.
  • The doctype list is a static snapshot in DECLARATIONS_DOCTYPES / SETUP_DOCTYPES / TOOLS_DOCTYPES (taxes_az) and ETAXES_SETUP_DOCTYPES / ETAXES_REFERENCE_DOCTYPES / ETAXES_DOCUMENT_DOCTYPES (invoice_az). Adding a DocType to either app does NOT auto-include it — append to the tuple and re-migrate.
  • _cleanup_obsolete() removes legacy docs owned by this app (currently "Taxes"). Only touches records where app == "jey_theme" — never deletes ERPNext/other-app docs.

Frontend: multi-theme system

JS entry: jey_theme/public/js/jey_theme.js (served raw via app_include_js, not bundled). CSS: one file, jey_theme/public/css/jey_theme.bundle.css — the former shared.css / theme_chrome.css / theme_modern.css were concatenated into it (in that order, still marked by /* ===== <name>.css ===== */ banners) so the desk's preload header stays under the edge proxy's 4 KB buffer. Edit the bundle directly; there are no separate source files to regenerate it from.

  • CSS changes need bench build --app jey_theme. app_include_css names the bundle, and esbuild emits the hashed public/dist/css/jey_theme.bundle.<HASH>.css that sites/assets/assets.json actually points the browser at. Editing the bundle alone changes nothing in the browser.
  • JS changes need only a hard reload — but /assets/jey_theme/js/jey_theme.js is a hashless path under a 1-year nginx cache, so it really does have to be a hard reload (or a cache-disabled session).
  • Theme selector lives in data-jey-theme on <html>, stored in localStorage("jey-theme"). Default: chrome. Set before first paint by an IIFE at the top of jey_theme.js.
  • Themes supported: chrome (metallic rings), silk (warm ivory & champagne-gold glass-neumorphism, ported from public/silk_dashboard_crisp.html — that mockup is silk's design reference; keep the two in sync). No dark/light variants — each theme is self-contained.
  • Theme-specific CSS MUST be wrapped in [data-jey-theme="themename"]. Keyframes MUST be prefixed jey-<theme>-* to avoid cross-theme name collisions.
  • Shared CSS (checkboxes, icon base sizing, switcher UI, column-resize rules, the card icon-tile defaults) lives in the shared.css section without theme selectors.

Frosted glass (silk, and any future glass theme) — two rules that cost real debugging time:

  • One backdrop-filter per stack. A frosted element inside another frosted element paints as an opaque white block on real GPUs; headless Chrome (SwiftShader) renders it correctly, so it passes every test render. Only the outermost surface gets the filter — currently .widget, .form-page, .frappe-list .result-container, .navbar-search-bar, .dropdown-navbar-user, .desktop-navbar-modal-search, .jey-chrome. Everything nested (icon tiles, chips, count pills, buttons) gets a translucent fill and no filter. There's a backstop rule near the Modals section, but don't rely on it — check with the live-DOM audit (walk every element, flag any whose ancestor also has a non-none computed backdropFilter).
  • On silk it's the translucency, not the blur, that reads as glass. The fabric is near-uniform, so a strong blur averages it into a flat opaque panel. Light blur (6px) over a very translucent warm fill is what lets it show through.

Frontend: per-theme icons

  • THEME_ICONS[themeName] in jey_theme.js maps icon keys to inline SVG path strings. Missing keys fall back to THEME_ICONS.chrome, then _fallback.
  • JS replaces <img class="app-icon"> / .folder-icon with inline <svg class="jey-icon"> per current theme.
  • window.jeyRebuildIcons() tears down and rebuilds all icon DOM — called on theme switch.
  • SVGs may carry a cls (e.g. ico-buying) for shared CSS animations.

Frontend: early-paint tricks in jey_theme.js

The top IIFE runs before paint to avoid FOUC:

  • Sets data-jey-theme immediately.
  • Defaults container_fullwidth = "true" on fresh install.
  • Reads all jey-col-widths:<Doctype>:<field> localStorage keys and injects a <style id="jey-col-resize-styles"> with per-grid column widths, plus a MutationObserver that stamps data-jey-grid on grids as they appear.

Keep this IIFE minimal and synchronous — anything slow here delays first paint.

Adding a new theme

  1. Append a /* ===== theme_mytheme.css ===== */ section to jey_theme/public/css/jey_theme.bundle.css, with every rule wrapped in [data-jey-theme="mytheme"]. Prefix keyframes jey-mytheme-*. Do NOT add a new file/app_include_css entry — extra preload-header lines are what the single bundle exists to avoid.
  2. Add THEME_ICONS.mytheme = { ... } in jey_theme.js (only override keys you care about).
  3. Add an entry to the JEY_THEMES array in the switcher section of jey_theme.js, and a .jey-theme-preview--mytheme swatch in the bundle's shared section.
  4. bench build --app jey_theme.

Rules

  • Themes can change anything (layout, positioning, colors, fonts, visibility, animations, DOM structure) — not just icons. Use JS (jeyRebuildIcons / theme-switch hooks) for DOM restructuring.
  • Never add [data-theme="dark"] or light/dark variant rules — themes are self-contained (no inherited dark/light axis).
  • Don't touch ERPNext-owned records in setup scripts; gate deletes on app == "jey_theme".