https://github.com/reactiumcore/reactium-sdk-core
SDK singleton foundation for Reactium
https://github.com/reactiumcore/reactium-sdk-core
Last synced: 10 months ago
JSON representation
SDK singleton foundation for Reactium
- Host: GitHub
- URL: https://github.com/reactiumcore/reactium-sdk-core
- Owner: ReactiumCore
- License: mit
- Created: 2019-12-11T22:49:55.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-04-13T03:59:25.000Z (about 2 years ago)
- Last Synced: 2024-04-13T12:58:54.013Z (about 2 years ago)
- Language: JavaScript
- Size: 1.92 MB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Reactium SDK Core
Core subset of Reactium SDK singleton and named exports.
## Install
```
npm install --save @atomic-reactor/reactium-sdk-core
```
## Usage
NPM Module
```js
import { Zone, useHookComponent } from '@atomic-reactor/reactium-sdk-core';
```
Reactium projects
```js
// As above or with some enhhancements patched in from reactium-core workspace:
import { Zone, useHookComponent } from '@atomic-reactor/reactium-core/sdk';
```
## API Description
This project is best used with [Reactium](https://github.com/Atomic-Reactor/Reactium) but can also be used independently. See the [API documentation](https://reactiumcore.github.io/reactium-sdk-core/).
**Note:** The API documentation link above is written with lots of examples to by used inside a Reactium app projects, but most examples will work if you import from the NPM module directly.
### SDK Objects
The primary SDK objects in this library are:
* **Cache**: For controlling runtime object cache in node or browser
* **Handle**: Registry that manages React handle references
* **Hook**: Registry for callbacks for async/sync "hook" invocations.
* **Component**: Registry for replaceable React component string tokens.
* **Pulse**: Registry for running recurring processes over time (like cron for React)
* **Zone**: Registry for React components to render in "rendering zones" (i.e. `` component)
* **Prefs**: Allows you to manipulate local storage from React very quickly and easily.
### React Hooks
This SDK comes with a number of React hooks:
* **useHookComponent**: Use a React component registers to Component registry. Allows you to create string token component that can be implemented elsewhere.
* **useDerivedState**: Tool to managed derived React state from props (if you must).
* **useEventEffect**: Quickly and easily add and remove event listeners.
* **useFocusEffect**: Get a true/false state when element is focused.
* **useAsyncEffect**: Like useEffect, but with built-in protection for setting state async.
* **useEventRefs**: Like useRefs, but also an EventTarget for event streaming reference changes.
* **useFocusEffect**: Used to focus a child component on render
* **useFulfilledObject**: Helps you aggregate async data in React when all conditions are met / ready.
* **useHandle**: Use a registered imperative React handle by handle id.
* **useHookComponent**: Used to get re-registered Components and use them in your Component with ease.
* **useIsContainer**: Determines if the element is a child of the container. Useful for traversing the DOM to find out if an event or action happened within the specified container.
* **useRefs**: Manage multiple refs easily.
* **useRegisterHandle**: Register an imperative React handle that can be used anywhere in the app.
* **useRegisterSyncHandle**: Register an imperative React handle that is also a sync state management object. (See useSyncState)
* **useScrollToggle**: Facilitates enabling or disabling body scrolling in the browser.
* **useSelectHandle**: Allows you to "select" state from a registered sync handle, and rerender your React component when the selection changes.
* **useStatus**: Helper hook for walking through enumerated states.
* **useSyncHandle**: Attach your component to a registered imperative handle.
* **useSyncState**: A drop in replacement for useState that avoids async state update getting out of sync with your render. Also an EventTarget for event streaming state updates.
### Browser / App Utilities
* **Registry**: A generic subscribable registry class.
* **registryFactory**: A function that quickly create Registry objects.
* **cxFactory**: A function that will build a React className namespace, for easily passing a CSS context down through components.
* **splitParts**: A function that makes it easy to convert a tokenized string into a map of React components.
* **isWindow**: A function that detects the presence of a global "window" object.
* **isServer**: A function that detects if running on node.js (as opposed to in browser)
* **isServerWindow**: A functions for determining if the window object is actually on the server (using JSDOM) in Reactium.
* **isElectronWindow**: A function for determining if the environment is actually Electron (not the web browser)
### React Components
* **Zone**: A "rendering zone" for other components to dynamically render.
* **HookComponent**: An "abstract component" which can be implemented elsewhere.
## ES Module Exports
As a reference, here is a full list of the library esmodule exports. (Just to make you aware of what is available in your `import` statements)
The default import includes everything, but you may also import just `core` modules (appropriate for node), or `browser` modules (appropriate for React).
From `@atomic-reactor/reactium-sdk-core/browser`:
```js
[Module: null prototype] {
BREAKPOINTS_DEFAULT: { xs: 640, sm: 990, md: 1280, lg: 1440, xl: 1600 },
Component: RegisteredComponents [EventTarget] {
listeners: {},
op: {
has: [Function: bound ],
ensureExists: [Function: bound ],
set: [Function: bound ],
insert: [Function: bound ],
empty: [Function: bound ],
push: [Function: bound ],
coalesce: [Function: bound ],
get: [Function: bound ],
del: [Function: bound del],
withInheritedProps: [Function: bound objectPath]
},
options: { noMerge: true },
_addEventListener: [Function: bound addEventListener],
addEventListener: [Function (anonymous)],
[Symbol(INITIAL_STATE)]: {},
[Symbol(STATE)]: { Zone: [Function: Zone] }
},
ComponentEvent: [class ComponentEvent extends CustomEvent],
ComponentTarget: [class ComponentTarget extends EventTarget],
Fullscreen: FullscreenClass {
initialized: false,
update: [Function: update],
isExpanded: [Function (anonymous)],
isCollapsed: [Function (anonymous)],
collapse: [Function (anonymous)],
expand: [AsyncFunction (anonymous)],
toggle: [Function (anonymous)],
element: HTMLHtmlElement {}
},
FullscreenClass: [class FullscreenClass],
Handle: Handle { handles: { BodyScroll: [Object] }, subscriptions: {} },
HookComponent: [Function: HookComponent],
PassThroughZone: [Function: PassThroughZone],
Prefs: PrefsClass {
storageKey: 'ar-prefs',
clear: [Function (anonymous)],
get: [Function (anonymous)],
set: [Function (anonymous)]
},
PrefsClass: [class PrefsClass],
ReactiumSyncState: [class ReactiumSyncState extends EventTarget],
RegisteredComponents: [class RegisteredComponents extends ReactiumSyncState],
SimpleZone: [Function: SimpleZone],
SplitParts: [class SplitParts] { splitter: [Function: splitter] },
Zone: [Function: Zone],
ZoneRegistry: Zones {
defaultControls: { components: [], controls: [Object] },
[Symbol(INITIALIZED)]: false,
[Symbol(ZONES)]: { subscribers: [Object], components: [Object], controls: [Object] },
[Symbol(UNSUBSCRIBE)]: [Function (anonymous)]
},
Zones: [class Zones],
__esModule: true,
breakpoint: [Function: breakpoint],
breakpoints: [Function: breakpoints],
conditionalDocument: [Function: conditionalDocument],
conditionalWindow: [Function: conditionalWindow],
cxFactory: [Function: cxFactory],
default: {
cxFactory: [Getter],
ComponentEvent: [Getter],
ComponentTarget: [Getter],
FullscreenClass: [Getter],
Fullscreen: [Getter],
Handle: [Getter],
PrefsClass: [Getter],
Prefs: [Getter],
ReactiumSyncState: [Getter],
forwardRefNoop: [Getter],
RegisteredComponents: [Getter],
Component: [Getter],
SplitParts: [Getter],
splitParts: [Getter],
useAsyncEffect: [Getter],
useDerivedState: [Getter],
isTarget: [Getter],
useEventEffect: [Getter],
useFocusEffect: [Getter],
useFulfilledObject: [Getter],
useHandle: [Getter],
useHookComponent: [Getter],
useIsContainer: [Getter],
useRefs: [Getter],
useRegisterHandle: [Getter],
useRegisterSyncHandle: [Getter],
useScrollToggle: [Getter],
useSelectHandle: [Getter],
useStatus: [Getter],
useSyncHandle: [Getter],
useSyncState: [Getter],
conditionalWindow: [Getter],
conditionalDocument: [Getter],
isWindow: [Getter],
isElectronWindow: [Getter],
isBrowserWindow: [Getter],
BREAKPOINTS_DEFAULT: [Getter],
breakpoints: [Getter],
breakpoint: [Getter],
Zone: [Getter],
SimpleZone: [Getter],
PassThroughZone: [Getter],
HookComponent: [Getter],
Zones: [Getter],
ZoneRegistry: [Getter]
},
forwardRefNoop: {
'$$typeof': Symbol(react.forward_ref),
render: [Function (anonymous)]
},
isBrowserWindow: [Function: isBrowserWindow],
isElectronWindow: [Function: isElectronWindow],
isTarget: [Function: isTarget],
isWindow: [Function: isWindow],
splitParts: [Function: splitParts],
useAsyncEffect: [Function: useAsyncEffect],
useDerivedState: [Function: useDerivedState],
useEventEffect: [Function: useEventEffect],
useFocusEffect: [Function: useFocusEffect],
useFulfilledObject: [Function: useFulfilledObject],
useHandle: [Function: useHandle],
useHookComponent: [Function: useHookComponent],
useIsContainer: [Function: useIsContainer],
useRefs: [Function: useRefs],
useRegisterHandle: [Function: useRegisterHandle],
useRegisterSyncHandle: [Function: useRegisterSyncHandle],
useScrollToggle: [Function: useScrollToggle],
useSelectHandle: [Function: useSelectHandle],
useStatus: [Function: useStatus],
useSyncHandle: [Function: useSyncHandle],
useSyncState: [Function: useSyncState]
}
```
From `@atomic-reactor/reactium-sdk-core/core`:
```js
[Module: null prototype] {
Cache: MemoryCache {
_subscribers: {},
_subscribedPaths: {},
set: [Function: put],
_mc: Cache {
put: [Function (anonymous)],
del: [Function (anonymous)],
clear: [Function (anonymous)],
get: [Function (anonymous)],
size: [Function (anonymous)],
memsize: [Function (anonymous)],
debug: [Function (anonymous)],
hits: [Function (anonymous)],
misses: [Function (anonymous)],
keys: [Function (anonymous)],
exportJson: [Function (anonymous)],
importJson: [Function (anonymous)]
}
},
Enums: {
cache: { settings: 90000 },
priority: {
'0': 'neutral',
'500': 'low',
'1000': 'lowest',
core: -2000,
'-2000': 'core',
highest: -1000,
'-1000': 'highest',
high: -500,
'-500': 'high',
neutral: 0,
low: 500,
lowest: 1000
}
},
Hook: HookSDK {
action: { sync: [Object], async: {} },
actionIds: { '@reactium-file-tag': 'sync.@reactium.@reactium-file-tag' },
domains: { '@reactium': [Object] },
flush: [Function (anonymous)],
unregister: [Function (anonymous)],
unregisterDomain: [Function (anonymous)],
_register: [Function (anonymous)],
list: [Function (anonymous)],
_actions: [Function (anonymous)],
run: [Function (anonymous)],
runSync: [Function (anonymous)]
},
MemoryCache: [class MemoryCache],
NotificationTypes: {
REGISTER: 'register',
UNREGISTER: 'unregister',
PROTECT: 'protect',
UNPROTECT: 'unprotect',
BAN: 'ban',
UNBAN: 'unban',
CLEANUP: 'cleanup',
FLUSH: 'flush'
},
Priority: {
'0': 'neutral',
'500': 'low',
'1000': 'lowest',
core: -2000,
'-2000': 'core',
highest: -1000,
'-1000': 'highest',
high: -500,
'-500': 'high',
neutral: 0,
low: 500,
lowest: 1000
},
Pulse: PulseSDK {
Task: null,
[Symbol(6a45d4c2-5e9e-4a4b-9eb0-81ca2bf8bb8d)]: {},
[Symbol(718e6d8e-4c2c-4124-b754-701aee955261)]: {}
},
PulseTask: [class PulseTask] {
ENUMS: {
ERROR: [Object],
DEBUG: false,
DEFAULT: [Object],
STATUS: [Object]
}
},
PulseTaskError: [class PulseTaskError extends Error],
Registry: [class Registry] { MODES: { HISTORY: 'HISTORY', CLEAN: 'CLEAN' } },
RegistryModes: { HISTORY: 'HISTORY', CLEAN: 'CLEAN' },
Server: {
Middleware: Registry {
__name: 'ExpressMiddleware',
__idField: 'name',
__registered: [],
__protected: {},
__unregister: {},
__banned: {},
__subscribers: {},
__mode: 'CLEAN'
}
},
__esModule: true,
abbreviatedNumber: [Function: abbreviatedNumber],
annotationsFactory: [Function: annotationsFactory],
create: [Function: registryFactory],
default: {
Priority: [Getter],
Enums: [Getter],
Hook: [Getter],
MemoryCache: [Getter],
Cache: [Getter],
abbreviatedNumber: [Getter],
PulseTaskError: [Getter],
PulseTask: [Getter],
Pulse: [Getter],
RegistryModes: [Getter],
NotificationTypes: [Getter],
Registry: [Getter],
registryFactory: [Getter],
create: [Getter],
Server: [Getter],
annotationsFactory: [Getter]
},
registryFactory: [Function: registryFactory]
}
```