@spearwolf/shadow-objects 0.6.0 → 0.8.0

package/README.md

@@ -1,69 +1,40 @@
-# Welcome to _shadow-ents_ :wave:
+_hi! welcome to .._
+# shadow-objects 🧛
 
-shadow-objects is a JavaScript library that's all about making your life easier when dealing with components and web workers. It's like having a superpower for your web development! :muscle:
+## Introduction
 
-![architecture overview](./docs/architecture@2x.png)
+_Shadow-objects_ is a standalone entity component framework.
+The original idea is visualized in this overview:
 
-> _ents_ is short for latin _"entitatis"_, which translates to _"shadow entities"_
-
-
-## Quick Tour
-
-### Offloading to Web Workers :construction_worker:
-
-shadow-objects takes the heavy lifting off your main thread and moves it to web workers. This means your components stay light and breezy, just like a hibiscus flower in the wind. :hibiscus:
-
-### Entities :ghost:
-
-Yes, we've got entities too! In shadow-objects, an _entity_ belongs to a _view-component_, but it lives in a _web worker_. That's why we call them _shadow-entities_. They're like the secret agents of your app, working behind the scenes in their own separate world.
-
-### Shadow Objects :package:
-
-The _shadow-objects_ are simple functions or classes created by the user (you!) and form logical units of code  in which the real work is done behind the scenes.
-
-Shadow-objects reside within the context of an entity and have access to the entity's properties and events, which mirror the properties and events of the view-components.
-
-Any number of independent shadow-objects can be attached to an entity.
-
-Shadow-objects can also provide any _context_ to other shadow-objects:
-- a _context_ has a name and can consist of any JavaScript value or object.
-- a _context_ is inherited by subtrees through the hierarchy of entities.
+![architecture overview](https://raw.githubusercontent.com/spearwolf/shadow-objects/main/packages/shadow-objects/docs/architecture%402x.png)
 
+> _ents_ is short for latin _"entitatis"_, which translates to _"shadow entities"_
 
-### View Components :eyes:
-
-
-A `<view-component/>` is a virtual component in the view that serves as an access point for the entities.
-
-The _shadow-ents_ package provides the custom element `<shadow-objects>` as view component. As a HTML element in the DOM, these might form their own hierarchy.
-This hierarchy is mirrored by the entities in the worker, keeping everything in sync.
-
-In the future, implementations as _react_ or _angular_ components are also conceivable.
-
-
-### Component Context :brain:
-
-The _component-context_ is the root of a view-component hierarchy. It's like the conductor of an orchestra, creating a web worker and making sure the entities and their components are in harmony.
-
-### Kernel :nut_and_bolt:
-
-Inside the worker, there's the _kernel_. It's the counterpart to the component-context, taking care of the lifecycle of the entities and their _shadow-objects_.
-
-### Tokens :label:
+> [!IMPORTANT]
+> _Dear adventurer, be warned: everything here is highly experimental and in active development and constant flux!_
 
-When a view-component is created, you can apply a string-based token. The kernel uses these to decide which shadow-objects to create within each entity. It's like giving your components a secret handshake!
+The components are created in the view space. Hierarchical. In your browser. There is a JavaScript API for this. But to keep things simple, there are also ready-to-use web components.
 
-### Event and Property Synchronization :arrows_counterclockwise:
+```html
+<shae-worker-env local? src="./my-personal-shadow-objects.js" />
 
-View-components can send events to their entities, which are then passed on to the shadow-objects. This also works the other way around. However, property synchronization only goes one way, from view-components to entities.
+<shae-ent ns? token="foo">
+  <shae-ent ns? token="bar">
+    <shae-prop name="myNumbers" value="1 2 3" type="integer[]" />
+  </shae-ent>
+</shae-ent>
+```
 
-- - -
+> [!WARNING]
+> Sorry, at this point there should be a precise and crisp introduction to the concepts of the framework, but unfortunately this is not currently available.
+> Instead of that, a few insights into the implementation will follow
 
-So, that's a quick tour of shadow-objects! It's all about making your web ui faster and more responsive, and assembling your code in a more structured and streamlined way. Give it a try and see the difference it can make in your projects! :rocket:
+TODO ... add documentation here ... !
 
-More in-depth documentation here:
-- [ShadowEnv](./src/view/README.md)
-- [ComponentContext](./src/view/ComponentContext.md)
-- [ViewComponent](./src/view/ViewComponent.md)
+Here is the big class graph overview:
+![class graph overview](https://raw.githubusercontent.com/spearwolf/shadow-objects/main/packages/shadow-objects/src/view/ClassGraphOverview.drawio.svg)
 
-> _but dear adventurer, be warned: everything here is highly experimental and in active development and constant flux!_
+More in-depth docs here:
+- [ShadowEnv](https://github.com/spearwolf/shadow-objects/blob/main/packages/shadow-objects/src/view/README.md)
+- [ComponentContext](https://github.com/spearwolf/shadow-objects/blob/main/packages/shadow-objects/src/view/ComponentContext.md)
+- [ViewComponent](https://github.com/spearwolf/shadow-objects/blob/main/packages/shadow-objects/src/view/ViewComponent.md)