irgen 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to the `irgen` project will be documented in this file.
 
+## [0.2.2] - 2026-01-18
+
+### Core Extensions & Architecture (Phase 10)
+- **Universal Action Model**: Introduced `ActionSpec` type and `onClick` support for buttons, enabling a consistent "invoke operation" or "navigate" behavior across all UI components.
+- **Operation-Backed Forms**: Updated `DeclFormSchema` to support `operationId` in submission configuration, allowing forms to bind directly to backend operations instead of hardcoded URLs.
+- **Micro-Frontend Support**: Added `macro` field to `DeclComponentSchema`, enabling the definition of "Page Templates" (like `TablePage`, `EditorPage`) as single high-level components with props.
+- **Dependency Declaration**: Added `requiredComponentKeys` to `DeclFrontendAppSchema`, allowing extensions and presets to explicitly declare their UI component dependencies.
+- **Active Runtime Signals**: Implemented functional execution of `toast`, `redirect`, `openUrl`, and `downloadAs` signals in the headless runtime (`BaseRuntime`), replacing passive data with active behavior.
+- **Frontend auth contract**: Added `frontend.auth` to declare login/logout operations, login path, and nav visibility rules in a deterministic, policy-driven way.
+- **Form lifecycle upgrades**: Added `form.load` with args/when/mapFields, plus `form.submit.label` for configurable submit text.
+- **Table UX contracts**: Added `table.rowNavigateTo` (row click navigation) and `table.rowActions` with per-row actions and optional confirm dialogs.
+- **Runtime logic evaluation**: Frontend runtime now evaluates logic expressions for path params, action arguments, and field mapping, enabling dynamic behaviors without recompilation.
+- **Frontend build hooks**: Added `build.copyTo`/`build.postbuild` policy to emit postbuild copy scripts in frontend outputs (`copyToPublic` is deprecated).
+- **Component UI variants**: Added `component.props.uiVariant` (`header`/`inline`) and `component.props.layoutVariant` (`header`) to control header-style layouts without card wrappers.
+- **Visual policy (best-effort)**: Emitter reads `policies.frontend.visual` knobs (`navLayout`, `contentWidth`, `density`) without adding schema validation.
+- **Topbar controls (best-effort)**: `visual.topbarControls` controls right-side navbar items (search/notifications/theme/avatar), avatar visibility, and optional custom links.
+- **Branding controls (best-effort)**: `visual.brand` can hide/show logos and override logo src/text/icon in topbar/sidebar.
+- **Nav overrides (best-effort)**: `visual.navItems` can define separate menus for topbar and sidebar, and hide topbar.
+- **Footer/search overrides (best-effort)**: `visual.footerLinks` and `visual.search` allow replacing footer links and search copy without core edits.
+- **Footer layout (best-effort)**: `visual.footer` can disable or compact footer and override footer text.
+- **Form styling (best-effort)**: `visual.form` allows overriding form label/input/error/button/form classes.
+- **Button styling (best-effort)**: `visual.button` allows overriding base/variant button classes.
+- **Table styling (best-effort)**: `visual.table` allows overriding table container/row/cell/action classes.
+- **Tabs styling (best-effort)**: `visual.tabs` allows overriding tabs container/header/button/panel classes.
+- **Marketing blocks (best-effort)**: `visual.marketing` allows overriding hero/features/logos/etc container/title classes.
+- **Card styling (best-effort)**: `visual.cards` allows overriding card/empty/placeholder classes.
+- **Prose styling (best-effort)**: `visual.prose` allows overriding markdown/prose wrapper class.
+- **Motion styling (best-effort)**: `visual.motion` allows overriding page enter + hover/alert/tag motion classes.
+- **Copy overrides (best-effort)**: `visual.copy` allows overriding empty/placeholder/table/tab strings plus common UI labels, including runtime error text.
+- **Token overrides (best-effort)**: `visual.tokens` allows overriding typography/spacing/radius/shadow/color/motion tokens.
+- **Icon overrides (best-effort)**: `visual.icons` allows overriding default UI chrome icons, including docs section + docs item + nav + footer + search modal + row action icons.
+- **SSR fix**: ensure `App.tsx` imports React when using `React.createElement` in generated UI.
+- **Breakpoint overrides (best-effort)**: `visual.breakpoints` allows overriding responsive layout classes (padding/sidebar/docs grid).
+- **Docs/background overrides (best-effort)**: `visual.docs` and `visual.background` control docs labels/sidebar/TOC and decorative gradients.
+- **Labels/avatar overrides (best-effort)**: `visual.labels.sidebarLabel` and `visual.topbarControls.avatar.src` replace hardcoded sidebar label and avatar URL.
+
 ## [0.2.1] - 2026-01-11
 
 ### GitHub Pages (SSG/Hybrid)

package/README.md

@@ -38,6 +38,7 @@ irgen focuses on **architecture and determinism**, not convenience shortcuts. ir
 - **Multi-app Support**: Set `basePath` to deploy multiple apps (e.g., `/admin`, `/docs`) under a single project or domain.
 - **Form Logic & UX**: JSONLogic predicates, dependency-tracked hooks, async select with debounce/pagination/search.
 - **Submission Pipeline**: Lifecycle hooks, confirm dialogs, response handling, and draft persistence.
+- **Auth + Table Contracts**: `frontend.auth` for login/logout flows; `form.load` for prefill; `table.rowNavigateTo` + `table.rowActions` for row navigation/actions.
 
 ### Static Site (HTML-first)
 - **HTML-only output**: emits final HTML (no React hydration), JS is strictly progressive enhancement.
@@ -149,7 +150,7 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for details on:
 - Generation Gap Pattern
 - Port & Adapters (Hexagonal)
 - Frontend Runtime & IR
-- Frontend SSG plan: [docs/FRONTEND-SSG-PLAN.md](docs/FRONTEND-SSG-PLAN.md)
+- Macro System: [docs/MACRO-SYSTEM.md](docs/MACRO-SYSTEM.md)
 
 ## Roadmap
 - [x] Separation of Concerns (Generated vs User space)

package/dist/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import path from "node:path";
+import fs from "node:fs";
 import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
 import { aggregateDecls } from "./dsl/aggregator.js";
 import { registerBuiltins, runMapper } from "./mappers/index.js";
 // Guard: require a modern Node (tsx loader relies on module.register)
@@ -186,13 +188,37 @@ Examples:
             return;
         const { createExtensionContext } = await import("./extensions/context.js");
         const ctx = createExtensionContext();
+        const require = createRequire(import.meta.url);
+        const pickExtensionFn = (mod) => {
+            const candidate = (mod?.default ?? mod?.extension ?? mod);
+            if (typeof candidate === "function")
+                return candidate;
+            if (candidate && typeof candidate === "object") {
+                if (typeof candidate.default === "function")
+                    return candidate.default;
+                if (typeof candidate.extension === "function")
+                    return candidate.extension;
+            }
+            return null;
+        };
+        const resolveExtensionModule = (spec) => {
+            const isPathLike = path.isAbsolute(spec) || spec.startsWith(".") || spec.startsWith("/") || /^[A-Za-z]:[\\/]/.test(spec);
+            if (isPathLike) {
+                const abs = path.isAbsolute(spec) ? spec : path.resolve(process.cwd(), spec);
+                if (!fs.existsSync(abs)) {
+                    throw new Error(`extension module not found: ${spec}`);
+                }
+                return pathToFileURL(abs).href;
+            }
+            const resolved = require.resolve(spec, { paths: [process.cwd()] });
+            return pathToFileURL(resolved).href;
+        };
         for (const modPath of extModules) {
-            const abs = path.isAbsolute(modPath) ? modPath : path.resolve(process.cwd(), modPath);
-            const modUrl = pathToFileURL(abs).href;
+            const modUrl = resolveExtensionModule(modPath);
             const imported = await import(modUrl);
-            const fn = (imported.default ?? imported.extension ?? imported);
+            const fn = pickExtensionFn(imported);
             if (typeof fn === "function") {
-                fn(ctx, imported.options ?? undefined);
+                await fn(ctx, imported.options ?? undefined);
             }
             else {
                 console.warn(`extension module ${modPath} did not export a function`);

package/dist/dsl/frontend-runtime.d.ts

@@ -1,5 +1,5 @@
 import { DeclFrontendApp, DeclComponent } from "../ir/decl/frontend.raw.schema.js";
-export type RuntimeComponent = Omit<DeclComponent, "agentChat" | "cliUsage" | "table"> & {
+export type RuntimeComponent = Omit<DeclComponent, "agentChat" | "cliUsage" | "table" | "macro"> & {
     field: (fieldName: string, type: string, label?: string, validators?: Record<string, any>, config?: any) => void;
     prop: (key: string, value: string) => void;
     agentChat: (data: {
@@ -39,21 +39,25 @@ export type RuntimeComponent = Omit<DeclComponent, "agentChat" | "cliUsage" | "t
             render?: string;
         }>;
     }) => void;
+    useMacro: (type: string, props?: Record<string, any>) => void;
 };
 type FrontendOptions = {
     basePath?: string;
     pwa?: DeclFrontendApp["pwa"];
+    auth?: DeclFrontendApp["auth"];
     meta?: Record<string, any>;
     policies?: Record<string, any>;
     datasources?: DeclFrontendApp["datasources"];
     operations?: DeclFrontendApp["operations"];
     resources?: DeclFrontendApp["resources"];
+    requiredComponentKeys?: string[];
 };
 export declare function datasource(id: string, config: any): void;
 export declare function operation(id: string, config: any): void;
 export declare function resource(id: string, config: any): void;
 export declare function meta(key: string, value: unknown): void;
 export declare function policy(target: string, value: Record<string, any>): void;
+export declare function requiredComponents(keys: string[]): void;
 export declare function page(pName: string, opts: {
     path: string;
     hideHeader?: boolean;
@@ -72,6 +76,7 @@ type FrontendCallbackArgs = {
     resource: typeof resource;
     meta: typeof meta;
     policy: typeof policy;
+    requiredComponents: typeof requiredComponents;
 };
 export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a: FrontendCallbackArgs) => void), maybeFn?: (a: FrontendCallbackArgs) => void): {
     type: "frontend";
@@ -130,7 +135,7 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
     components: {
         type: "component";
         name: string;
-        props?: Record<string, string> | undefined;
+        props?: Record<string, any> | undefined;
         form?: {
             fields: {
                 type: "number" | "date" | "text" | "select" | "textarea" | "checkbox" | "radio" | "datetime" | "time" | "url" | "phone" | "file" | "slider" | "currency" | "tags" | "signature" | "daterange" | "email" | "password";
@@ -193,6 +198,8 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
             }[];
             submit?: {
                 url?: string | undefined;
+                label?: string | undefined;
+                operationId?: string | undefined;
                 method?: "POST" | "PUT" | "PATCH" | undefined;
                 successMessage?: string | undefined;
                 errorMessage?: string | undefined;
@@ -203,6 +210,14 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
                 onError?: any;
                 redirect?: string | undefined;
             } | undefined;
+            load?: {
+                operationId: string;
+                onSuccess?: any;
+                onError?: any;
+                args?: any;
+                when?: any;
+                mapFields?: Record<string, any> | undefined;
+            } | undefined;
         } | undefined;
         entityRef?: string | undefined;
         content?: string | undefined;
@@ -236,16 +251,40 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
         button?: {
             label: string;
             icon?: string | undefined;
+            onClick?: {
+                kind: "invoke";
+                operationId: string;
+                confirmMessage?: string | undefined;
+                args?: any;
+            } | {
+                kind: "navigate";
+                confirmMessage?: string | undefined;
+                to?: any;
+            } | undefined;
             variant?: "primary" | "secondary" | "ghost" | undefined;
         } | undefined;
         table?: {
+            operationId?: string | undefined;
             columns?: {
                 header: string;
                 accessor: string;
                 render?: string | undefined;
             }[] | undefined;
             resourceId?: string | undefined;
-            operationId?: string | undefined;
+            rowNavigateTo?: string | undefined;
+            rowActions?: {
+                label: string;
+                onClick?: {
+                    kind: "invoke";
+                    operationId: string;
+                    confirmMessage?: string | undefined;
+                    args?: any;
+                } | {
+                    kind: "navigate";
+                    confirmMessage?: string | undefined;
+                    to?: any;
+                } | undefined;
+            }[] | undefined;
         } | undefined;
         themeToggle?: boolean | undefined;
         codeBlock?: {
@@ -253,6 +292,7 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
             language: string;
             showLineNumbers: boolean;
         } | undefined;
+        macro?: string | undefined;
         marketing?: {
             kind: "hero" | "features" | "testimonials" | "faq" | "logos" | "cta" | "stats" | "timeline";
             align?: "left" | "center" | undefined;
@@ -270,8 +310,18 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
             }[] | undefined;
             actions?: {
                 label: string;
-                href: string;
                 icon?: string | undefined;
+                href?: string | undefined;
+                onClick?: {
+                    kind: "invoke";
+                    operationId: string;
+                    confirmMessage?: string | undefined;
+                    args?: any;
+                } | {
+                    kind: "navigate";
+                    confirmMessage?: string | undefined;
+                    to?: any;
+                } | undefined;
                 variant?: "primary" | "secondary" | "ghost" | undefined;
             }[] | undefined;
             badge?: string | undefined;
@@ -285,7 +335,7 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
         components: {
             type: "component";
             name: string;
-            props?: Record<string, string> | undefined;
+            props?: Record<string, any> | undefined;
             form?: {
                 fields: {
                     type: "number" | "date" | "text" | "select" | "textarea" | "checkbox" | "radio" | "datetime" | "time" | "url" | "phone" | "file" | "slider" | "currency" | "tags" | "signature" | "daterange" | "email" | "password";
@@ -348,6 +398,8 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
                 }[];
                 submit?: {
                     url?: string | undefined;
+                    label?: string | undefined;
+                    operationId?: string | undefined;
                     method?: "POST" | "PUT" | "PATCH" | undefined;
                     successMessage?: string | undefined;
                     errorMessage?: string | undefined;
@@ -358,6 +410,14 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
                     onError?: any;
                     redirect?: string | undefined;
                 } | undefined;
+                load?: {
+                    operationId: string;
+                    onSuccess?: any;
+                    onError?: any;
+                    args?: any;
+                    when?: any;
+                    mapFields?: Record<string, any> | undefined;
+                } | undefined;
             } | undefined;
             entityRef?: string | undefined;
             content?: string | undefined;
@@ -391,16 +451,40 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
             button?: {
                 label: string;
                 icon?: string | undefined;
+                onClick?: {
+                    kind: "invoke";
+                    operationId: string;
+                    confirmMessage?: string | undefined;
+                    args?: any;
+                } | {
+                    kind: "navigate";
+                    confirmMessage?: string | undefined;
+                    to?: any;
+                } | undefined;
                 variant?: "primary" | "secondary" | "ghost" | undefined;
             } | undefined;
             table?: {
+                operationId?: string | undefined;
                 columns?: {
                     header: string;
                     accessor: string;
                     render?: string | undefined;
                 }[] | undefined;
                 resourceId?: string | undefined;
-                operationId?: string | undefined;
+                rowNavigateTo?: string | undefined;
+                rowActions?: {
+                    label: string;
+                    onClick?: {
+                        kind: "invoke";
+                        operationId: string;
+                        confirmMessage?: string | undefined;
+                        args?: any;
+                    } | {
+                        kind: "navigate";
+                        confirmMessage?: string | undefined;
+                        to?: any;
+                    } | undefined;
+                }[] | undefined;
             } | undefined;
             themeToggle?: boolean | undefined;
             codeBlock?: {
@@ -408,6 +492,7 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
                 language: string;
                 showLineNumbers: boolean;
             } | undefined;
+            macro?: string | undefined;
             marketing?: {
                 kind: "hero" | "features" | "testimonials" | "faq" | "logos" | "cta" | "stats" | "timeline";
                 align?: "left" | "center" | undefined;
@@ -425,8 +510,18 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
                 }[] | undefined;
                 actions?: {
                     label: string;
-                    href: string;
                     icon?: string | undefined;
+                    href?: string | undefined;
+                    onClick?: {
+                        kind: "invoke";
+                        operationId: string;
+                        confirmMessage?: string | undefined;
+                        args?: any;
+                    } | {
+                        kind: "navigate";
+                        confirmMessage?: string | undefined;
+                        to?: any;
+                    } | undefined;
                     variant?: "primary" | "secondary" | "ghost" | undefined;
                 }[] | undefined;
                 badge?: string | undefined;
@@ -480,6 +575,14 @@ export declare function frontend(name: string, optsOrFn: FrontendOptions | ((a:
             purpose?: string | undefined;
         }[] | undefined;
     } | undefined;
+    auth?: {
+        enabled?: boolean | undefined;
+        loginPath?: string | undefined;
+        meOperationId?: string | undefined;
+        logoutOperationId?: string | undefined;
+        hideLoginWhenAuthed?: boolean | undefined;
+    } | undefined;
+    requiredComponentKeys?: string[] | undefined;
 };
 export declare function loadFrontendDsl(entry: string): Promise<DeclFrontendApp>;
 export {};

package/dist/dsl/frontend-runtime.js

@@ -31,6 +31,7 @@ const RUNTIME_HELPERS = [
     "enableThemeToggle",
     "code",
     "table",
+    "useMacro",
 ];
 function stripRuntimeHelpers(comp) {
     for (const key of RUNTIME_HELPERS) {
@@ -60,6 +61,10 @@ export function policy(target, value) {
     assert(_global.__IR_CURRENT_FRONTEND, "policy() harus di dalam frontend()");
     mergePolicy(target, value);
 }
+export function requiredComponents(keys) {
+    assert(_global.__IR_CURRENT_FRONTEND, "requiredComponents() harus di dalam frontend()");
+    _global.__IR_CURRENT_FRONTEND.requiredComponentKeys = keys;
+}
 export function page(pName, opts, cb) {
     assert(_global.__IR_CURRENT_FRONTEND, "page() harus di dalam frontend()");
     const page = {
@@ -104,6 +109,11 @@ export function page(pName, opts, cb) {
                     comp.codeBlock = { snippet, language, showLineNumbers: options?.showLineNumbers ?? true };
                 };
                 comp.table = function (data) { comp.table = data; };
+                comp.useMacro = function (type, props) {
+                    comp.macro = type;
+                    if (props)
+                        comp.props = props;
+                };
                 if (typeof cCb === "function")
                     cCb(comp);
                 stripRuntimeHelpers(comp);
@@ -151,6 +161,11 @@ export function component(name, cb) {
         comp.codeBlock = { snippet, language, showLineNumbers: options?.showLineNumbers ?? true };
     };
     comp.table = function (data) { comp.table = data; };
+    comp.useMacro = function (type, props) {
+        comp.macro = type;
+        if (props)
+            comp.props = props;
+    };
     if (typeof cb === "function")
         cb(comp);
     stripRuntimeHelpers(comp);
@@ -176,6 +191,8 @@ export function frontend(name, optsOrFn, maybeFn) {
         operations: opts?.operations ?? [],
         resources: opts?.resources ?? [],
         ...(opts?.pwa ? { pwa: opts.pwa } : {}),
+        ...(opts?.auth ? { auth: opts.auth } : {}),
+        ...(opts?.requiredComponentKeys ? { requiredComponentKeys: opts.requiredComponentKeys } : {}),
         meta: { ...baseMeta },
     };
     if (opts?.policies) {
@@ -191,6 +208,7 @@ export function frontend(name, optsOrFn, maybeFn) {
         component,
         meta,
         policy,
+        requiredComponents,
     });
     const parsed = DeclFrontendAppSchema.parse(_global.__IR_CURRENT_FRONTEND);
     _global.__IR_CURRENT_FRONTEND = parsed;

package/dist/emit/frontend/frontend-components.d.ts

@@ -0,0 +1,6 @@
+import type { Project } from "ts-morph";
+import type { FrontendComponent, FrontendMarketing } from "../../ir/domain/frontend.js";
+import type { FrontendTargetIR } from "../../ir/target/frontend.js";
+import type { FrontendPolicy } from "../../ir/target/frontend.policy.js";
+export declare function emitComponent(project: Project, frontendDir: string, component: FrontendComponent, ir: FrontendTargetIR): void;
+export declare function emitMarketingComponent(writer: any, m: FrontendMarketing, policy: FrontendPolicy, actionHandlers?: Array<string | null>): void;