@omerdlw/base-framework 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (171) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +121 -52
  3. package/dist/atoms/index.d.ts +0 -1
  4. package/dist/atoms/index.d.ts.map +1 -1
  5. package/dist/atoms/index.js +1 -64
  6. package/dist/atoms/index.js.map +1 -1
  7. package/dist/error/index.js +22 -25
  8. package/dist/error/index.js.map +1 -1
  9. package/dist/hooks/index.d.ts +2 -9
  10. package/dist/hooks/index.d.ts.map +1 -1
  11. package/dist/hooks/index.js +97 -540
  12. package/dist/hooks/index.js.map +1 -1
  13. package/dist/hooks/types.d.ts +3 -45
  14. package/dist/hooks/types.d.ts.map +1 -1
  15. package/dist/hooks/use-controllable-state.d.ts +1 -1
  16. package/dist/hooks/use-controllable-state.d.ts.map +1 -1
  17. package/dist/hooks/use-global-event.d.ts +0 -2
  18. package/dist/hooks/use-global-event.d.ts.map +1 -1
  19. package/dist/hooks/use-hotkey.d.ts +1 -1
  20. package/dist/hooks/use-hotkey.d.ts.map +1 -1
  21. package/dist/index.js +11283 -11772
  22. package/dist/index.js.map +1 -1
  23. package/dist/kernel/adapters.d.ts.map +1 -1
  24. package/dist/kernel/index.d.ts +1 -0
  25. package/dist/kernel/index.d.ts.map +1 -1
  26. package/dist/kernel/index.js +10 -81
  27. package/dist/kernel/index.js.map +1 -1
  28. package/dist/kernel/installed.d.ts.map +1 -1
  29. package/dist/kernel/page-controller.d.ts.map +1 -1
  30. package/dist/kernel/provider.d.ts.map +1 -1
  31. package/dist/modules/ambient/constants.d.ts +1 -1
  32. package/dist/modules/ambient/constants.d.ts.map +1 -1
  33. package/dist/modules/ambient/index.js +180 -326
  34. package/dist/modules/ambient/index.js.map +1 -1
  35. package/dist/modules/ambient/module.d.ts.map +1 -1
  36. package/dist/modules/background/constants.d.ts +4 -2
  37. package/dist/modules/background/constants.d.ts.map +1 -1
  38. package/dist/modules/background/context.d.ts +3 -0
  39. package/dist/modules/background/context.d.ts.map +1 -1
  40. package/dist/modules/background/hooks.d.ts +1 -1
  41. package/dist/modules/background/index.d.ts +2 -2
  42. package/dist/modules/background/index.d.ts.map +1 -1
  43. package/dist/modules/background/index.js +1172 -1270
  44. package/dist/modules/background/index.js.map +1 -1
  45. package/dist/modules/background/overlay.d.ts +1 -1
  46. package/dist/modules/background/overlay.d.ts.map +1 -1
  47. package/dist/modules/background/types.d.ts +1 -1
  48. package/dist/modules/background/types.d.ts.map +1 -1
  49. package/dist/modules/context-menu/constants.d.ts +1 -1
  50. package/dist/modules/context-menu/constants.d.ts.map +1 -1
  51. package/dist/modules/context-menu/context.d.ts.map +1 -1
  52. package/dist/modules/context-menu/hooks.d.ts.map +1 -1
  53. package/dist/modules/context-menu/index.js +133 -238
  54. package/dist/modules/context-menu/index.js.map +1 -1
  55. package/dist/modules/controls/constants.d.ts +1 -1
  56. package/dist/modules/controls/constants.d.ts.map +1 -1
  57. package/dist/modules/controls/hooks.d.ts +1 -1
  58. package/dist/modules/controls/index.js +28 -162
  59. package/dist/modules/controls/index.js.map +1 -1
  60. package/dist/modules/controls/types.d.ts +1 -1
  61. package/dist/modules/controls/types.d.ts.map +1 -1
  62. package/dist/modules/dock/cards.d.ts +2 -2
  63. package/dist/modules/dock/constants.d.ts +1 -1
  64. package/dist/modules/dock/constants.d.ts.map +1 -1
  65. package/dist/modules/dock/context.d.ts +10 -6
  66. package/dist/modules/dock/context.d.ts.map +1 -1
  67. package/dist/modules/dock/hooks.d.ts +5 -5
  68. package/dist/modules/dock/hooks.d.ts.map +1 -1
  69. package/dist/modules/dock/index.d.ts +1 -1
  70. package/dist/modules/dock/index.d.ts.map +1 -1
  71. package/dist/modules/dock/index.js +2060 -2080
  72. package/dist/modules/dock/index.js.map +1 -1
  73. package/dist/modules/dock/runtime/dock.d.ts.map +1 -1
  74. package/dist/modules/dock/types.d.ts +1 -1
  75. package/dist/modules/dock/types.d.ts.map +1 -1
  76. package/dist/modules/index.js +10789 -11027
  77. package/dist/modules/index.js.map +1 -1
  78. package/dist/modules/loading/constants.d.ts +4 -2
  79. package/dist/modules/loading/constants.d.ts.map +1 -1
  80. package/dist/modules/loading/context.d.ts +3 -0
  81. package/dist/modules/loading/context.d.ts.map +1 -1
  82. package/dist/modules/loading/hooks.d.ts +1 -1
  83. package/dist/modules/loading/hooks.d.ts.map +1 -1
  84. package/dist/modules/loading/index.d.ts +2 -2
  85. package/dist/modules/loading/index.d.ts.map +1 -1
  86. package/dist/modules/loading/index.js +118 -222
  87. package/dist/modules/loading/index.js.map +1 -1
  88. package/dist/modules/loading/types.d.ts +1 -1
  89. package/dist/modules/loading/types.d.ts.map +1 -1
  90. package/dist/modules/media/constants.d.ts +2 -1
  91. package/dist/modules/media/constants.d.ts.map +1 -1
  92. package/dist/modules/media/context.d.ts +3 -0
  93. package/dist/modules/media/context.d.ts.map +1 -1
  94. package/dist/modules/media/index.d.ts +2 -2
  95. package/dist/modules/media/index.d.ts.map +1 -1
  96. package/dist/modules/media/index.js +61 -218
  97. package/dist/modules/media/index.js.map +1 -1
  98. package/dist/modules/modal/constants.d.ts +1 -1
  99. package/dist/modules/modal/constants.d.ts.map +1 -1
  100. package/dist/modules/modal/context.d.ts.map +1 -1
  101. package/dist/modules/modal/hooks.d.ts +2 -2
  102. package/dist/modules/modal/index.js +20 -366
  103. package/dist/modules/modal/index.js.map +1 -1
  104. package/dist/modules/notification/constants.d.ts +4 -2
  105. package/dist/modules/notification/constants.d.ts.map +1 -1
  106. package/dist/modules/notification/context.d.ts +4 -0
  107. package/dist/modules/notification/context.d.ts.map +1 -1
  108. package/dist/modules/notification/hooks.d.ts +1 -1
  109. package/dist/modules/notification/index.d.ts +2 -3
  110. package/dist/modules/notification/index.d.ts.map +1 -1
  111. package/dist/modules/notification/index.js +70 -154
  112. package/dist/modules/notification/index.js.map +1 -1
  113. package/dist/modules/notification/module.d.ts.map +1 -1
  114. package/dist/provider.js +255 -257
  115. package/dist/provider.js.map +1 -1
  116. package/dist/theme.d.ts +1 -0
  117. package/dist/theme.d.ts.map +1 -1
  118. package/dist/theme.js +2 -2
  119. package/dist/theme.js.map +1 -1
  120. package/dist/utils/index.d.ts +5 -6
  121. package/dist/utils/index.d.ts.map +1 -1
  122. package/dist/utils/index.js +1 -57
  123. package/dist/utils/index.js.map +1 -1
  124. package/dist/utils/number.d.ts +0 -1
  125. package/dist/utils/number.d.ts.map +1 -1
  126. package/dist/utils/object.d.ts +0 -2
  127. package/dist/utils/object.d.ts.map +1 -1
  128. package/dist/utils/string.d.ts +0 -3
  129. package/dist/utils/string.d.ts.map +1 -1
  130. package/dist/utils/timing.d.ts +0 -1
  131. package/dist/utils/timing.d.ts.map +1 -1
  132. package/docs/README.md +124 -0
  133. package/docs/architecture-and-rules.md +129 -0
  134. package/docs/core-engine.md +196 -0
  135. package/docs/custom-modules.md +267 -0
  136. package/docs/getting-started.md +199 -0
  137. package/docs/modules/README.md +176 -0
  138. package/docs/modules/ambient.md +150 -0
  139. package/docs/modules/background.md +195 -0
  140. package/docs/modules/context-menu.md +248 -0
  141. package/docs/modules/controls.md +159 -0
  142. package/docs/modules/dock.md +734 -0
  143. package/docs/modules/error-boundary.md +160 -0
  144. package/docs/modules/kernel.md +266 -0
  145. package/docs/modules/loading.md +157 -0
  146. package/docs/modules/media.md +196 -0
  147. package/docs/modules/modal.md +229 -0
  148. package/docs/modules/notification.md +161 -0
  149. package/docs/modules/result.md +135 -0
  150. package/docs/testing.md +160 -0
  151. package/docs/theming.md +185 -0
  152. package/package.json +50 -2
  153. package/templates/AGENTS.md +165 -0
  154. package/dist/hooks/use-async-action.d.ts +0 -3
  155. package/dist/hooks/use-async-action.d.ts.map +0 -1
  156. package/dist/hooks/use-debounce.d.ts +0 -2
  157. package/dist/hooks/use-debounce.d.ts.map +0 -1
  158. package/dist/hooks/use-intersection-observer.d.ts +0 -4
  159. package/dist/hooks/use-intersection-observer.d.ts.map +0 -1
  160. package/dist/hooks/use-media-query.d.ts +0 -2
  161. package/dist/hooks/use-media-query.d.ts.map +0 -1
  162. package/dist/hooks/use-mounted.d.ts +0 -2
  163. package/dist/hooks/use-mounted.d.ts.map +0 -1
  164. package/dist/hooks/use-server-action.d.ts +0 -4
  165. package/dist/hooks/use-server-action.d.ts.map +0 -1
  166. package/dist/hooks/use-storage-state.d.ts +0 -5
  167. package/dist/hooks/use-storage-state.d.ts.map +0 -1
  168. package/dist/modules/theme.d.ts +0 -3
  169. package/dist/modules/theme.d.ts.map +0 -1
  170. package/dist/utils/json.d.ts +0 -3
  171. package/dist/utils/json.d.ts.map +0 -1
@@ -3,5 +3,5 @@ export declare const CONTROLS_EDGE_INSET = 4;
3
3
  export declare const CONTROLS_DOCK_GAP = 8;
4
4
  export declare const CONTROLS_DOCK_ELEMENT_ID = "dock-card-stack";
5
5
  export declare const CONTROL_SIDE_NAMES: readonly ["left", "right"];
6
- export declare const controlsTheme: import("../theme").ThemeSpec<ControlsThemeSlot>;
6
+ export declare const controlsTheme: import("@/theme").ThemeSpec<ControlsThemeSlot>;
7
7
  //# sourceMappingURL=constants.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/modules/controls/constants.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAC1D,eAAO,MAAM,kBAAkB,4BAA4C,CAAC;AAE5E,eAAO,MAAM,aAAa,iDAAiD,CAAC"}
1
+ {"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/modules/controls/constants.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAC1D,eAAO,MAAM,kBAAkB,4BAA4C,CAAC;AAE5E,eAAO,MAAM,aAAa,gDAAiD,CAAC"}
@@ -10,6 +10,6 @@ export declare function useControlsModel(): {
10
10
  layout: ControlsLayout | null;
11
11
  left: import("./types").ControlsPairItem[];
12
12
  right: import("./types").ControlsPairItem[];
13
- theme: import("../theme").ResolvedTheme<import("./types").ControlsThemeSlot>;
13
+ theme: import("@/theme").ResolvedTheme<import("./types").ControlsThemeSlot>;
14
14
  };
15
15
  //# sourceMappingURL=hooks.d.ts.map
@@ -2,38 +2,8 @@
2
2
  import { createContext, useState, useEffect, useMemo, isValidElement, createElement, useSyncExternalStore, Fragment as Fragment$1, use, useId, useCallback, useContext, useRef, useLayoutEffect, cloneElement, Children } from 'react';
3
3
  import { createPortal } from 'react-dom';
4
4
  import { usePathname } from 'next/navigation';
5
- import 'clsx';
6
- import 'tailwind-merge';
7
5
  import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
8
6
 
9
- function getOrCreateGlobalContext(name, defaultValue) {
10
- const sym = /* @__PURE__ */ Symbol.for(`@omerdlw/base-framework/context/${name}`);
11
- const store = globalThis;
12
- if (!store[sym]) {
13
- store[sym] = createContext(defaultValue);
14
- }
15
- return store[sym];
16
- }
17
-
18
- // src/theme.tsx
19
- function defineThemeSpec(id) {
20
- return Object.freeze({ id });
21
- }
22
- var EMPTY = /* @__PURE__ */ new Map();
23
- var ThemeContext = getOrCreateGlobalContext("ThemeContext", EMPTY);
24
- function useTheme(spec) {
25
- const config = useContext(ThemeContext).get(spec.id);
26
- if (!config) {
27
- throw new Error(
28
- `Theme "${spec.id}" is missing. Add its theme file to src/config/ and list it in src/config/index.ts.`
29
- );
30
- }
31
- return {
32
- slots: config.slots,
33
- styles: config.styles ?? {}
34
- };
35
- }
36
-
37
7
  // src/kernel/constants.ts
38
8
  var DEFAULT_SOURCE = "dynamic";
39
9
  var REGISTRY_SOURCES = Object.freeze({
@@ -85,6 +55,14 @@ var REGISTRY_SCOPE_KINDS = Object.freeze({
85
55
  WORKSPACE: "workspace"
86
56
  });
87
57
  REGISTRY_SCOPE_KINDS.APP;
58
+ function getOrCreateGlobalContext(name, defaultValue) {
59
+ const sym = /* @__PURE__ */ Symbol.for(`@omerdlw/base-framework/context/${name}`);
60
+ const store = globalThis;
61
+ if (!store[sym]) {
62
+ store[sym] = createContext(defaultValue);
63
+ }
64
+ return store[sym];
65
+ }
88
66
 
89
67
  // src/utils/string.ts
90
68
  function trimToNull(value) {
@@ -293,93 +271,6 @@ function useRequiredContext(context, hookName, providerName) {
293
271
  return value;
294
272
  }
295
273
  var useIsomorphicLayoutEffect = isBrowser ? useLayoutEffect : useEffect;
296
- var EventEmitter = class {
297
- events = /* @__PURE__ */ new Map();
298
- debounceTimers = /* @__PURE__ */ new Map();
299
- subscribe(event, callback) {
300
- if (typeof event !== "string" || !event || typeof callback !== "function") {
301
- return () => {
302
- };
303
- }
304
- const listeners = this.events.get(event) || /* @__PURE__ */ new Set();
305
- listeners.add(callback);
306
- this.events.set(event, listeners);
307
- return () => {
308
- listeners.delete(callback);
309
- if (listeners.size === 0) this.events.delete(event);
310
- };
311
- }
312
- emit(event, payload) {
313
- const listeners = this.events.get(event);
314
- if (!listeners || listeners.size === 0) return;
315
- const snapshot = Array.from(listeners);
316
- for (const callback of snapshot) {
317
- try {
318
- callback(payload);
319
- } catch (error) {
320
- report(`Event listener (${String(event)})`, error);
321
- }
322
- }
323
- }
324
- emitDebounced(event, payload, waitMs = 100) {
325
- const existing = this.debounceTimers.get(event);
326
- if (existing) clearTimeout(existing);
327
- const timer = setTimeout(() => {
328
- this.debounceTimers.delete(event);
329
- this.emit(event, payload);
330
- }, waitMs);
331
- this.debounceTimers.set(event, timer);
332
- }
333
- cancelDebounced(event) {
334
- if (event) {
335
- const timer = this.debounceTimers.get(event);
336
- if (timer) {
337
- clearTimeout(timer);
338
- this.debounceTimers.delete(event);
339
- }
340
- } else {
341
- for (const timer of this.debounceTimers.values()) {
342
- clearTimeout(timer);
343
- }
344
- this.debounceTimers.clear();
345
- }
346
- }
347
- unsubscribeAll(event) {
348
- this.cancelDebounced(event);
349
- if (event) this.events.delete(event);
350
- else this.events.clear();
351
- }
352
- hasListeners(event) {
353
- return Boolean(this.events.get(event)?.size);
354
- }
355
- getListenerCount(event) {
356
- return this.events.get(event)?.size || 0;
357
- }
358
- getAllEvents() {
359
- return [...this.events.keys()];
360
- }
361
- };
362
- var GLOBAL_EVENTS_KEY = /* @__PURE__ */ Symbol.for("__base_framework_global_events__");
363
- var _global = globalThis;
364
- _global[GLOBAL_EVENTS_KEY] ?? (_global[GLOBAL_EVENTS_KEY] = new EventEmitter());
365
- function createNoopHandle(status = "rejected", reason = "unknown") {
366
- const handle = Object.assign(() => false, {
367
- active: false,
368
- dispose: () => false,
369
- instanceId: null,
370
- key: "",
371
- priority: 0,
372
- reason,
373
- source: "",
374
- status,
375
- type: "",
376
- update: () => handle,
377
- updatedAt: 0,
378
- validation: "warn"
379
- });
380
- return handle;
381
- }
382
- createNoopHandle();
383
274
  var RegistryContext = getOrCreateGlobalContext(
384
275
  "RegistryContext",
385
276
  null
@@ -842,56 +733,12 @@ function useRegistry(config, metadata) {
842
733
  );
843
734
  useAppliedRegistryConfig(payload, context, componentSlices);
844
735
  }
845
- function createPageControllerStore() {
846
- const listeners = /* @__PURE__ */ new Set();
847
- let stack = [];
848
- const notify = () => {
849
- listeners.forEach((listener) => {
850
- try {
851
- listener();
852
- } catch (error) {
853
- report("Page controller listener", error);
854
- }
855
- });
856
- };
857
- return {
858
- getSnapshot() {
859
- const top = stack[stack.length - 1];
860
- return top?.controllerRef?.current || null;
861
- },
862
- notify,
863
- register(id, controllerRef) {
864
- stack = stack.filter((item) => item.id !== id);
865
- stack.push({ controllerRef, id });
866
- notify();
867
- },
868
- subscribe(listener) {
869
- listeners.add(listener);
870
- return () => {
871
- listeners.delete(listener);
872
- };
873
- },
874
- unregister(id) {
875
- stack = stack.filter((item) => item.id !== id);
876
- notify();
877
- }
878
- };
879
- }
880
- var fallbackStandaloneStore = createPageControllerStore();
881
- getOrCreateGlobalContext(
882
- "PageControllerContext",
883
- null
884
- );
885
- getOrCreateGlobalContext(
886
- "PageControllerStoreContext",
887
- fallbackStandaloneStore
888
- );
889
736
  function defineModule(coreModule) {
890
737
  return Object.freeze({ ...coreModule });
891
738
  }
892
739
  createStore(void 0);
893
740
 
894
- // src/kernel/adapters.tsx
741
+ // src/kernel/adapters.ts
895
742
  function useModuleRegistration(id, value, options) {
896
743
  const coreModule = useInstalledModules().find(
897
744
  (candidate) => candidate.id === id
@@ -900,6 +747,25 @@ function useModuleRegistration(id, value, options) {
900
747
  useRegistry(config, pickRegistryMetadata(options));
901
748
  }
902
749
 
750
+ // src/theme.tsx
751
+ function defineThemeSpec(id) {
752
+ return Object.freeze({ id });
753
+ }
754
+ var EMPTY = /* @__PURE__ */ new Map();
755
+ var ThemeContext = getOrCreateGlobalContext("ThemeContext", EMPTY);
756
+ function useTheme(spec) {
757
+ const config = useContext(ThemeContext).get(spec.id);
758
+ if (!config) {
759
+ throw new Error(
760
+ `Theme "${spec.id}" is missing. Ensure its theme configuration is provided to <ThemeProvider themes={[...]}> (e.g. in src/config/ or your theme setup).`
761
+ );
762
+ }
763
+ return {
764
+ slots: config.slots,
765
+ styles: config.styles ?? {}
766
+ };
767
+ }
768
+
903
769
  // src/modules/controls/constants.ts
904
770
  var CONTROLS_EDGE_INSET = 4;
905
771
  var CONTROLS_DOCK_GAP = 8;