@omerdlw/base-framework 1.0.0 → 1.0.2

package/templates/AGENTS.md

@@ -0,0 +1,165 @@
+# Base Framework — AI Agent & Developer Mastery Guide
+
+> **This project is powered by `@omerdlw/base-framework`.**  
+> Read this file first before reading or modifying any code. It contains the exact architectural boundaries, rules, patterns, and code recipes you must follow without exception.
+
+---
+
+## 1. Quick Tech Stack & Foundations
+
+- **Engine:** Next.js 16 (App Router), React 19
+- **Core Framework:** `@omerdlw/base-framework` (Microkernel & Declarative UI Modules)
+- **Styling:** Tailwind CSS v4 (`@theme`, OKLCH semantic color tokens, `.center`, `.skeleton-block`)
+- **Motion:** Motion (v13) with hardware GPU acceleration (`translate3d`, `scale`)
+- **Icons:** `@iconify-icon/react` via `<Icon icon="solar:..." />`
+
+---
+
+## 2. The 4-Layer Architectural Hierarchy
+
+Code in this project strictly follows a four-layer dependency hierarchy:
+
+```
+Layer 4: src/app (Routing, Next.js page composition & layout orchestration)
+   ↓ imports
+Layer 3: src/features (Domain capabilities: auth, account, social, checkout)
+   ↓ imports
+Layer 2: src/infrastructure (Adapters: database, HTTP client, proxy, rate limiting)
+   ↓ imports
+Layer 1: @omerdlw/base-framework (Microkernel, first-party modules, atoms, tokens, result)
+```
+
+### Strict Architectural Boundaries:
+- `src/features/*` must **never** import from `src/app/*`.
+- `src/infrastructure/*` must **never** import from `src/features/*` or `src/app/*`.
+- Every feature in `src/features/` **must** have an `index.ts` barrel export.
+- Server database and adapter files **must** begin with `import "server-only";`.
+- Server Actions **must** begin with `"use server";` and return `Result<T, E>` (`ok()` or `err()`).
+
+---
+
+## 3. The 5 Golden Rules of Base Framework
+
+### Rule 1: Declarative Chrome (`usePage`)
+**Never** build custom top navigation bars, ad-hoc sticky headers, or scattered floating buttons.  
+All route-level visual state (title, dock card, loading state, background, modals) **must** be declared using `usePage()` from `@omerdlw/base-framework/kernel`:
+
+```tsx
+"use client";
+
+import { usePage } from "@omerdlw/base-framework/kernel";
+
+export default function MyPage() {
+  const page = usePage({
+    title: "Dashboard",
+    dock: {
+      description: "Project metrics and activity",
+      icon: "solar:widget-bold",
+    },
+    loading: false,
+  });
+
+  return <main>...</main>;
+}
+```
+
+### Rule 2: Result Pattern for All Async Operations
+Never return raw unchecked errors or throw unhandled exceptions from server actions or infrastructure operations. Always wrap return values with `Result<T, E>` from `@omerdlw/base-framework/result`:
+
+```tsx
+"use server";
+
+import "server-only";
+import { ok, err, type Result } from "@omerdlw/base-framework/result";
+
+export async function updateProfile(username: string): Promise<Result<{ id: string }, string>> {
+  if (!username) return err("Username is required");
+  // Save to DB...
+  return ok({ id: "user_123" });
+}
+```
+
+### Rule 3: Bridge Server Actions to Feedback with `toast.fromResult`
+When consuming Server Actions in the UI, do not write manual `try/catch` and `if (res.error)` blocks. Use `toast.fromResult()`:
+
+```tsx
+"use client";
+
+import { useToast } from "@omerdlw/base-framework/modules/notification";
+import { updateProfile } from "@/features/account/actions";
+
+export function ProfileForm() {
+  const { toast } = useToast();
+
+  const handleSubmit = async (name: string) => {
+    const result = await updateProfile(name);
+    toast.fromResult(result, {
+      success: "Profile updated successfully!",
+    });
+  };
+
+  return <form>...</form>;
+}
+```
+
+### Rule 4: Subpath Imports Only
+Always import from the exact subpaths exposed by `@omerdlw/base-framework`:
+
+| What you need | Where to import it |
+| :--- | :--- |
+| `usePage`, `defineModule` | `@omerdlw/base-framework/kernel` |
+| `CoreProvider` | `@omerdlw/base-framework/provider` |
+| `ok`, `err`, `isResult`, `type Result` | `@omerdlw/base-framework/result` |
+| `globalEvents`, `EVENT_TYPES` | `@omerdlw/base-framework/events` |
+| `useToast` | `@omerdlw/base-framework/modules/notification` |
+| `useDockActions`, `useDockStatus` | `@omerdlw/base-framework/modules/dock` |
+| `useModal`, `useModalContext` | `@omerdlw/base-framework/modules/modal` |
+| `useAmbientTheme` | `@omerdlw/base-framework/modules/ambient` |
+| `cn`, `report`, `createStore` | `@omerdlw/base-framework/utils` |
+| `useClickOutside`, `useGlobalEvent` | `@omerdlw/base-framework/hooks` |
+| `Button`, `Icon`, `Spinner`, `Tooltip` | `@omerdlw/base-framework/atoms` |
+
+### Rule 5: Modals and Surfaces Must Be Declared or Scoped
+Do not create floating unmanaged `fixed z-50` dialog div wrappers.
+- For sheets/drawers sliding up from the dock: use `useDockActions().openSurface(...)`.
+- For standard dialogs: register them in `usePage({ modal: { ... } })` or trigger with `useModal().openModal(...)`.
+
+---
+
+## 4. Standard Next.js Root Layout Recipe
+
+In `src/app/providers.tsx`:
+
+```tsx
+"use client";
+
+import { CoreProvider } from "@omerdlw/base-framework/provider";
+import { dockModule } from "@omerdlw/base-framework/modules/dock";
+import { modalModule } from "@omerdlw/base-framework/modules/modal";
+import { notificationModule } from "@omerdlw/base-framework/modules/notification";
+import { ambientModule } from "@omerdlw/base-framework/modules/ambient";
+import { backgroundModule } from "@omerdlw/base-framework/modules/background";
+import { controlsModule } from "@omerdlw/base-framework/modules/controls";
+import { loadingModule } from "@omerdlw/base-framework/modules/loading";
+
+const modules = [
+  dockModule,
+  modalModule,
+  notificationModule,
+  ambientModule,
+  backgroundModule,
+  controlsModule,
+  loadingModule,
+];
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <CoreProvider modules={modules}>{children}</CoreProvider>;
+}
+```
+
+In `src/app/globals.css`:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@omerdlw/base-framework";
+```

package/dist/hooks/use-async-action.d.ts

@@ -1,3 +0,0 @@
-import { UseAsyncActionOptions, UseAsyncActionResult } from "./types";
-export declare function useAsyncAction<TArgs extends unknown[] = unknown[], TResult = unknown>(actionFn: (...args: TArgs) => Promise<TResult>, options?: UseAsyncActionOptions<TResult>): UseAsyncActionResult<TArgs, TResult>;
-//# sourceMappingURL=use-async-action.d.ts.map

package/dist/hooks/use-async-action.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-async-action.d.ts","sourceRoot":"","sources":["../../src/hooks/use-async-action.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEtE,wBAAgB,cAAc,CAC5B,KAAK,SAAS,OAAO,EAAE,GAAG,OAAO,EAAE,EACnC,OAAO,GAAG,OAAO,EAEjB,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EAC9C,OAAO,GAAE,qBAAqB,CAAC,OAAO,CAAM,GAC3C,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,CAmEtC"}

package/dist/hooks/use-debounce.d.ts

@@ -1,2 +0,0 @@
-export declare function useDebounce<T>(value: T, delay?: number): T;
-//# sourceMappingURL=use-debounce.d.ts.map

package/dist/hooks/use-debounce.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-debounce.d.ts","sourceRoot":"","sources":["../../src/hooks/use-debounce.ts"],"names":[],"mappings":"AAIA,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,GAAE,MAAY,GAAG,CAAC,CAS/D"}

package/dist/hooks/use-intersection-observer.d.ts

@@ -1,4 +0,0 @@
-import { type RefObject } from "react";
-import { UseIntersectionObserverOptions, UseIntersectionObserverResult } from "./types";
-export declare function useIntersectionObserver<T extends Element = Element>(targetRef: RefObject<T | null> | null | undefined, options?: UseIntersectionObserverOptions): UseIntersectionObserverResult;
-//# sourceMappingURL=use-intersection-observer.d.ts.map

package/dist/hooks/use-intersection-observer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-intersection-observer.d.ts","sourceRoot":"","sources":["../../src/hooks/use-intersection-observer.ts"],"names":[],"mappings":"AAEA,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAGpE,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,EAC9B,MAAM,SAAS,CAAC;AAEjB,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EACjE,SAAS,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,EACjD,OAAO,GAAE,8BAAmC,GAC3C,6BAA6B,CAiD/B"}

package/dist/hooks/use-media-query.d.ts

@@ -1,2 +0,0 @@
-export declare function useMediaQuery(query: string, serverFallback?: boolean): boolean;
-//# sourceMappingURL=use-media-query.d.ts.map

package/dist/hooks/use-media-query.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-media-query.d.ts","sourceRoot":"","sources":["../../src/hooks/use-media-query.ts"],"names":[],"mappings":"AAKA,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,cAAc,GAAE,OAAe,GAC9B,OAAO,CAuBT"}

package/dist/hooks/use-mounted.d.ts

@@ -1,2 +0,0 @@
-export declare function useMounted(): boolean;
-//# sourceMappingURL=use-mounted.d.ts.map

package/dist/hooks/use-mounted.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-mounted.d.ts","sourceRoot":"","sources":["../../src/hooks/use-mounted.ts"],"names":[],"mappings":"AAMA,wBAAgB,UAAU,IAAI,OAAO,CAMpC"}

package/dist/hooks/use-server-action.d.ts

@@ -1,4 +0,0 @@
-import { type Result } from "@/result";
-import { UseServerActionOptions, UseServerActionResult } from "./types";
-export declare function useServerAction<TArgs extends unknown[] = unknown[], T = unknown, E = string>(actionFn: (...args: TArgs) => Promise<Result<T, E>>, options?: UseServerActionOptions<T, E>): UseServerActionResult<TArgs, T, E>;
-//# sourceMappingURL=use-server-action.d.ts.map

package/dist/hooks/use-server-action.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-server-action.d.ts","sourceRoot":"","sources":["../../src/hooks/use-server-action.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAEhE,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAExE,wBAAgB,eAAe,CAC7B,KAAK,SAAS,OAAO,EAAE,GAAG,OAAO,EAAE,EACnC,CAAC,GAAG,OAAO,EACX,CAAC,GAAG,MAAM,EAEV,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EACnD,OAAO,GAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAM,GACzC,qBAAqB,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CA6EpC"}

package/dist/hooks/use-storage-state.d.ts

@@ -1,5 +0,0 @@
-import { UseStorageStateOptions } from "./types";
-export declare function useStorageState<T>(key: string, initialValue: T, options?: UseStorageStateOptions<T>): [T, (next: T | ((prev: T) => T)) => void, () => void];
-export declare function useLocalStorage<T>(key: string, initialValue: T, options?: Omit<UseStorageStateOptions<T>, "storage">): [T, (next: T | ((prev: T) => T)) => void, () => void];
-export declare function useSessionStorage<T>(key: string, initialValue: T, options?: Omit<UseStorageStateOptions<T>, "storage">): [T, (next: T | ((prev: T) => T)) => void, () => void];
-//# sourceMappingURL=use-storage-state.d.ts.map

package/dist/hooks/use-storage-state.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-storage-state.d.ts","sourceRoot":"","sources":["../../src/hooks/use-storage-state.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAajD,wBAAgB,eAAe,CAAC,CAAC,EAC/B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,EACf,OAAO,GAAE,sBAAsB,CAAC,CAAC,CAAM,GACtC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,MAAM,IAAI,CAAC,CAgHvD;AAED,wBAAgB,eAAe,CAAC,CAAC,EAC/B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,GACnD,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,MAAM,IAAI,CAAC,CAEvD;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,EACf,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,GACnD,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,MAAM,IAAI,CAAC,CAEvD"}

package/dist/modules/theme.d.ts

@@ -1,3 +0,0 @@
-export { ThemeProvider, defineTheme, defineThemeSpec, useTheme as useModuleTheme, } from "@/theme";
-export type { ResolvedTheme, ThemeConfig, ThemeEntry, ThemeSpec, } from "@/theme";
-//# sourceMappingURL=theme.d.ts.map

package/dist/modules/theme.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/modules/theme.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,WAAW,EACX,eAAe,EACf,QAAQ,IAAI,cAAc,GAC3B,MAAM,SAAS,CAAC;AACjB,YAAY,EACV,aAAa,EACb,WAAW,EACX,UAAU,EACV,SAAS,GACV,MAAM,SAAS,CAAC"}

package/dist/utils/json.d.ts

@@ -1,3 +0,0 @@
-export declare function safeJsonParse<T = unknown>(text: unknown, fallback?: T | null): T | null;
-export declare function safeJsonStringify(value: unknown, fallback?: string): string;
-//# sourceMappingURL=json.d.ts.map

package/dist/utils/json.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/utils/json.ts"],"names":[],"mappings":"AAAA,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EACvC,IAAI,EAAE,OAAO,EACb,QAAQ,GAAE,CAAC,GAAG,IAAW,GACxB,CAAC,GAAG,IAAI,CAOV;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,GAAE,MAAW,GACpB,MAAM,CAMR"}