graphcore-kernel 0.1.0__py3-none-any.whl
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.
- graphcore/__init__.py +5 -0
- graphcore/agent_frontend/__init__.py +8 -0
- graphcore/agent_frontend/api.py +69 -0
- graphcore/agent_frontend/base/__init__.py +11 -0
- graphcore/agent_frontend/base/views.py +167 -0
- graphcore/agent_frontend/client.py +31 -0
- graphcore/agent_frontend/context.py +157 -0
- graphcore/agent_frontend/errors.py +12 -0
- graphcore/agent_frontend/loading.py +54 -0
- graphcore/agent_frontend/registry.py +42 -0
- graphcore/agent_frontend/render.py +207 -0
- graphcore/agent_frontend/server.py +103 -0
- graphcore/agent_frontend/signatures.py +35 -0
- graphcore/agent_frontend/testing.py +45 -0
- graphcore/agent_frontend/tests/__init__.py +0 -0
- graphcore/agent_frontend/tests/fakes.py +114 -0
- graphcore/agent_frontend/tests/test_frontend.py +447 -0
- graphcore/agent_frontend/tests/test_loading.py +83 -0
- graphcore/agent_frontend/tests/test_server.py +109 -0
- graphcore/agent_frontend/tools.py +137 -0
- graphcore/api/__init__.py +4 -0
- graphcore/api/graph_api.py +378 -0
- graphcore/api/predicate_codec.py +81 -0
- graphcore/api/tests/__init__.py +0 -0
- graphcore/api/tests/test_changed_entities.py +109 -0
- graphcore/api/tests/test_graph_api.py +290 -0
- graphcore/api/tests/test_graph_api_access.py +94 -0
- graphcore/api/tests/test_graph_api_grants.py +90 -0
- graphcore/api/tests/test_predicate_codec.py +83 -0
- graphcore/api/tests/test_subtree_query.py +79 -0
- graphcore/apps.py +71 -0
- graphcore/auth/__init__.py +1 -0
- graphcore/auth/authn/README.md +178 -0
- graphcore/auth/authn/__init__.py +3 -0
- graphcore/auth/authn/authenticator.py +120 -0
- graphcore/auth/authn/onboarding.py +105 -0
- graphcore/auth/authn/principals.py +20 -0
- graphcore/auth/authn/resource_metadata.py +43 -0
- graphcore/auth/authn/service_accounts.py +96 -0
- graphcore/auth/authn/testing.py +96 -0
- graphcore/auth/authn/tests/__init__.py +0 -0
- graphcore/auth/authn/tests/test_authenticator.py +145 -0
- graphcore/auth/authn/tests/test_onboarding.py +145 -0
- graphcore/auth/authn/tests/test_service_accounts.py +180 -0
- graphcore/auth/authn/users.py +59 -0
- graphcore/auth/authz/__init__.py +0 -0
- graphcore/auth/authz/access_port.py +120 -0
- graphcore/auth/authz/adapter/__init__.py +0 -0
- graphcore/auth/authz/adapter/default_access_adapter.py +556 -0
- graphcore/auth/authz/adapter/tests/__init__.py +0 -0
- graphcore/auth/authz/adapter/tests/test_default_adapter.py +543 -0
- graphcore/auth/authz/adapter/tests/test_entity_write_hooks.py +207 -0
- graphcore/auth/authz/adapter/tests/test_group_types.py +70 -0
- graphcore/auth/authz/adapter/tests/test_sync_support.py +209 -0
- graphcore/auth/authz/defaults.py +26 -0
- graphcore/auth/authz/kernel_policy.py +191 -0
- graphcore/auth/authz/kernel_writes.py +31 -0
- graphcore/auth/authz/lookups.py +25 -0
- graphcore/auth/authz/policy.py +403 -0
- graphcore/auth/authz/tests/__init__.py +0 -0
- graphcore/auth/authz/tests/test_can_contain.py +150 -0
- graphcore/auth/authz/tests/test_contained_by.py +167 -0
- graphcore/auth/authz/tests/test_creation.py +391 -0
- graphcore/auth/authz/tests/test_delete_permission.py +82 -0
- graphcore/auth/authz/tests/test_granted_to_me.py +160 -0
- graphcore/auth/authz/tests/test_integration.py +637 -0
- graphcore/auth/authz/tests/test_invites.py +184 -0
- graphcore/auth/authz/tests/test_kernel_policy.py +140 -0
- graphcore/auth/authz/tests/test_lockout.py +132 -0
- graphcore/auth/authz/tests/test_policy.py +329 -0
- graphcore/auth/authz/tests/test_primitives.py +73 -0
- graphcore/auth/authz/tests/test_principal_creation.py +62 -0
- graphcore/bootstrap/__init__.py +0 -0
- graphcore/bootstrap/deployment.py +67 -0
- graphcore/bootstrap/signals.py +16 -0
- graphcore/bootstrap/tests/__init__.py +0 -0
- graphcore/bootstrap/tests/test_deployment_seed.py +154 -0
- graphcore/broadcast/__init__.py +4 -0
- graphcore/broadcast/broadcaster.py +201 -0
- graphcore/broadcast/channels.py +56 -0
- graphcore/broadcast/tests/__init__.py +0 -0
- graphcore/broadcast/tests/test_broadcaster.py +444 -0
- graphcore/celery.py +14 -0
- graphcore/docs/AGENT_FRONTEND_TDD.md +389 -0
- graphcore/docs/ARCHITECTURE_PRINCIPLES.md +152 -0
- graphcore/docs/AUTHORIZATION_TECHNICAL_TDD.md +1379 -0
- graphcore/docs/ENTITY_REFERENCE_TDD.md +561 -0
- graphcore/docs/GRAPHAPI_FRONT_DOOR.md +173 -0
- graphcore/docs/RUNTIME.md +90 -0
- graphcore/docs/SCHEDULING_TDD.md +244 -0
- graphcore/docs/STRATEGY_EXECUTION_TDD.md +1043 -0
- graphcore/docs/VIEW_ENTITY_TDD.md +522 -0
- graphcore/docs/VIEW_SYSTEM_TDD.md +307 -0
- graphcore/docs/__init__.py +0 -0
- graphcore/docs/doc_topics.py +97 -0
- graphcore/docs/docs_discovery.py +64 -0
- graphcore/docs/public_api.py +56 -0
- graphcore/domain/__init__.py +0 -0
- graphcore/domain/entity/Entity.py +204 -0
- graphcore/domain/entity/__init__.py +0 -0
- graphcore/domain/entity/deployment/Deployment.py +25 -0
- graphcore/domain/entity/deployment/__init__.py +0 -0
- graphcore/domain/entity/grant/Grant.py +31 -0
- graphcore/domain/entity/grant/__init__.py +0 -0
- graphcore/domain/entity/group/Group.py +48 -0
- graphcore/domain/entity/group/README.md +88 -0
- graphcore/domain/entity/group/__init__.py +0 -0
- graphcore/domain/entity/invite/Invite.py +31 -0
- graphcore/domain/entity/invite/__init__.py +0 -0
- graphcore/domain/entity/request_template/RequestTemplate.py +48 -0
- graphcore/domain/entity/request_template/__init__.py +0 -0
- graphcore/domain/entity/request_template/tests/__init__.py +0 -0
- graphcore/domain/entity/request_template/tests/test_request_template.py +52 -0
- graphcore/domain/entity/service_account/ServiceAccount.py +41 -0
- graphcore/domain/entity/service_account/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/StrategyRequest.py +61 -0
- graphcore/domain/entity/strategy_request/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/tests/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/tests/test_strategy_request_entity.py +35 -0
- graphcore/domain/entity/tests/__init__.py +0 -0
- graphcore/domain/entity/tests/test_entity.py +227 -0
- graphcore/domain/entity/tests/test_grant_group_entities.py +36 -0
- graphcore/domain/entity/tests/test_write_once_fields.py +98 -0
- graphcore/domain/entity/user/User.py +39 -0
- graphcore/domain/entity/user/__init__.py +0 -0
- graphcore/domain/entity/user/tests/__init__.py +0 -0
- graphcore/domain/entity/user/tests/test_user_entity.py +33 -0
- graphcore/domain/entity/view/View.py +37 -0
- graphcore/domain/entity/view/__init__.py +0 -0
- graphcore/domain/entity/view/position.py +78 -0
- graphcore/domain/entity/view/tests/__init__.py +0 -0
- graphcore/domain/entity/view/tests/test_position.py +71 -0
- graphcore/domain/entity/view/tests/test_view_entity.py +134 -0
- graphcore/domain/strategy/BaseStrategy.py +759 -0
- graphcore/domain/strategy/DeploymentStrategies.py +55 -0
- graphcore/domain/strategy/GrantStrategies.py +189 -0
- graphcore/domain/strategy/GroupStrategies.py +193 -0
- graphcore/domain/strategy/InviteStrategies.py +84 -0
- graphcore/domain/strategy/RequestTemplateStrategies.py +126 -0
- graphcore/domain/strategy/ViewStrategies.py +219 -0
- graphcore/domain/strategy/__init__.py +0 -0
- graphcore/domain/strategy/runner.py +84 -0
- graphcore/domain/strategy/session.py +56 -0
- graphcore/domain/strategy/tests/BaseStrategyTest.py +167 -0
- graphcore/domain/strategy/tests/__init__.py +0 -0
- graphcore/domain/strategy/tests/test_BaseStrategies.py +870 -0
- graphcore/domain/strategy/tests/test_grant_strategies.py +245 -0
- graphcore/domain/strategy/tests/test_group_strategies.py +99 -0
- graphcore/domain/strategy/tests/test_runner.py +220 -0
- graphcore/domain/strategy/tests/test_strategy_locks.py +446 -0
- graphcore/domain/strategy/tests/test_utils.py +95 -0
- graphcore/domain/strategy/tests/test_view_strategies.py +436 -0
- graphcore/errors.py +145 -0
- graphcore/execution/README.md +97 -0
- graphcore/execution/StrategyExecutorService.py +333 -0
- graphcore/execution/__init__.py +0 -0
- graphcore/execution/dispatcher.py +19 -0
- graphcore/execution/environments/__init__.py +0 -0
- graphcore/execution/environments/celery.py +59 -0
- graphcore/execution/environments/in_process.py +55 -0
- graphcore/execution/local_session.py +117 -0
- graphcore/execution/redis_run_events.py +74 -0
- graphcore/execution/requests.py +22 -0
- graphcore/execution/run_events.py +85 -0
- graphcore/execution/strategy_context.py +54 -0
- graphcore/execution/tasks.py +34 -0
- graphcore/execution/tests/__init__.py +5 -0
- graphcore/execution/tests/contract.py +171 -0
- graphcore/execution/tests/support.py +310 -0
- graphcore/execution/tests/test_dispatchers.py +76 -0
- graphcore/execution/tests/test_executor.py +368 -0
- graphcore/execution/tests/test_local_session.py +95 -0
- graphcore/execution/tests/test_reconcile_runs.py +134 -0
- graphcore/execution/tests/test_run_events.py +106 -0
- graphcore/execution/tests/test_strategy_context.py +62 -0
- graphcore/gateway/__init__.py +1 -0
- graphcore/gateway/remote.py +35 -0
- graphcore/gateway/tests/__init__.py +0 -0
- graphcore/gateway/tests/test_remote.py +30 -0
- graphcore/graph/EntityService.py +710 -0
- graphcore/graph/__init__.py +0 -0
- graphcore/graph/entity_cache.py +152 -0
- graphcore/graph/tests/__init__.py +4 -0
- graphcore/graph/tests/test_EntityService.py +908 -0
- graphcore/graph/tests/test_EntityService_list.py +170 -0
- graphcore/graph/tests/test_EntityService_model_resolution.py +339 -0
- graphcore/graph/tests/test_EntityService_referrers.py +236 -0
- graphcore/graph/tests/test_EntityService_routing.py +119 -0
- graphcore/graph/tests/test_dependent_on.py +141 -0
- graphcore/graph/tests/test_engine_is_type_agnostic.py +25 -0
- graphcore/graph/tests/test_engine_resolves_read_permission.py +93 -0
- graphcore/graph/tests/test_entity_cache.py +159 -0
- graphcore/graph/tests/test_null_entity_cache.py +12 -0
- graphcore/management/__init__.py +0 -0
- graphcore/management/commands/__init__.py +0 -0
- graphcore/management/commands/dev_reset.py +18 -0
- graphcore/management/commands/graphcore_createadmin.py +65 -0
- graphcore/management/commands/graphcore_policy.py +59 -0
- graphcore/management/commands/graphcore_status.py +98 -0
- graphcore/management/tests/__init__.py +0 -0
- graphcore/management/tests/test_createadmin.py +78 -0
- graphcore/management/tests/test_policy_command.py +46 -0
- graphcore/management/tests/test_status_command.py +85 -0
- graphcore/migrations/0001_initial.py +186 -0
- graphcore/migrations/0002_invite.py +26 -0
- graphcore/migrations/__init__.py +0 -0
- graphcore/models.py +11 -0
- graphcore/persistence/ENTITY_REPOSITORY_TECHNICAL_TDD.md +396 -0
- graphcore/persistence/__init__.py +6 -0
- graphcore/persistence/django/__init__.py +0 -0
- graphcore/persistence/django/backends.py +43 -0
- graphcore/persistence/django/bindings.py +28 -0
- graphcore/persistence/django/cache.py +38 -0
- graphcore/persistence/django/compiler.py +214 -0
- graphcore/persistence/django/identity.py +18 -0
- graphcore/persistence/django/models.py +252 -0
- graphcore/persistence/django/repository.py +525 -0
- graphcore/persistence/django/tests/__init__.py +0 -0
- graphcore/persistence/django/tests/test_backends.py +68 -0
- graphcore/persistence/django/tests/test_compiler.py +269 -0
- graphcore/persistence/django/tests/test_repository.py +472 -0
- graphcore/persistence/django/tests/test_shared_column.py +120 -0
- graphcore/persistence/django/tests/test_threads.py +50 -0
- graphcore/persistence/django/tests/test_update_shape.py +175 -0
- graphcore/persistence/django/threads.py +38 -0
- graphcore/persistence/repository.py +172 -0
- graphcore/persistence/tests/__init__.py +0 -0
- graphcore/persistence/tests/contract.py +688 -0
- graphcore/persistence/tests/evaluate.py +51 -0
- graphcore/persistence/tests/fixtures.py +32 -0
- graphcore/persistence/tests/memory.py +263 -0
- graphcore/persistence/tests/test_memory_repository.py +10 -0
- graphcore/persistence/tests/test_query_types.py +127 -0
- graphcore/public/__init__.py +9 -0
- graphcore/public/api.py +9 -0
- graphcore/public/apps.py +10 -0
- graphcore/public/auth/__init__.py +1 -0
- graphcore/public/auth/grants.py +7 -0
- graphcore/public/auth/onboarding.py +8 -0
- graphcore/public/auth/perms.py +7 -0
- graphcore/public/auth/policy.py +10 -0
- graphcore/public/auth/roles.py +8 -0
- graphcore/public/auth/subjects.py +7 -0
- graphcore/public/entities/__init__.py +32 -0
- graphcore/public/errors.py +19 -0
- graphcore/public/persistence/__init__.py +44 -0
- graphcore/public/persistence/django.py +24 -0
- graphcore/public/scheduling.py +23 -0
- graphcore/public/strategies/__init__.py +85 -0
- graphcore/public/test_settings.py +16 -0
- graphcore/public/testing.py +47 -0
- graphcore/registry/EntityDirectory.py +246 -0
- graphcore/registry/README.md +147 -0
- graphcore/registry/StrategyDirectory.py +308 -0
- graphcore/registry/TYPE_METADATA_PLACEMENT.md +66 -0
- graphcore/registry/__init__.py +0 -0
- graphcore/registry/app_discovery.py +108 -0
- graphcore/registry/decorators.py +77 -0
- graphcore/registry/discovery.py +111 -0
- graphcore/registry/registry.py +79 -0
- graphcore/registry/tests/__init__.py +0 -0
- graphcore/registry/tests/test_agent_frontend_discovery.py +56 -0
- graphcore/registry/tests/test_app_config.py +36 -0
- graphcore/registry/tests/test_discovery.py +147 -0
- graphcore/registry/tests/test_entity_directory_storage.py +73 -0
- graphcore/registry/tests/test_import_package.py +87 -0
- graphcore/registry/tests/test_principal_flag.py +67 -0
- graphcore/registry/tests/test_strategy_directory.py +29 -0
- graphcore/routes/__init__.py +116 -0
- graphcore/routes/tests/__init__.py +0 -0
- graphcore/routes/tests/test_routes.py +90 -0
- graphcore/runtime.py +243 -0
- graphcore/scheduling/__init__.py +0 -0
- graphcore/scheduling/beat_scheduler.py +164 -0
- graphcore/scheduling/beat_tasks.py +63 -0
- graphcore/scheduling/scheduler.py +37 -0
- graphcore/scheduling/tests/__init__.py +0 -0
- graphcore/scheduling/tests/contract.py +136 -0
- graphcore/scheduling/tests/memory.py +42 -0
- graphcore/scheduling/tests/test_beat_scheduler.py +87 -0
- graphcore/scheduling/tests/test_memory_scheduler.py +15 -0
- graphcore/scheduling/tests/test_ticks.py +143 -0
- graphcore/tasks.py +9 -0
- graphcore/test_settings.py +78 -0
- graphcore/testing/__init__.py +0 -0
- graphcore/testing/case.py +112 -0
- graphcore/testing/runner.py +32 -0
- graphcore/testing/settings.py +26 -0
- graphcore/testing/tests/__init__.py +0 -0
- graphcore/testing/tests/agent_view_fixture.py +19 -0
- graphcore/testing/tests/test_case_and_runner.py +219 -0
- graphcore/testing/tests/test_settings_for_apps.py +50 -0
- graphcore/tests/__init__.py +0 -0
- graphcore/tests/ids.py +14 -0
- graphcore/tests/public_api_manifest.py +102 -0
- graphcore/tests/runs.py +7 -0
- graphcore/tests/test_app_discovery.py +90 -0
- graphcore/tests/test_composition_boundaries.py +231 -0
- graphcore/tests/test_docs_discovery.py +108 -0
- graphcore/tests/test_no_print.py +70 -0
- graphcore/tests/test_packaging.py +64 -0
- graphcore/tests/test_public_api_boundaries.py +229 -0
- graphcore/tests/test_public_api_contract.py +62 -0
- graphcore/tests/test_public_api_docs.py +28 -0
- graphcore/tests/test_runtime.py +42 -0
- graphcore/tests/test_shared_type_boundaries.py +128 -0
- graphcore/tests/test_shared_types.py +144 -0
- graphcore/tests/test_test_settings.py +45 -0
- graphcore/transport/__init__.py +0 -0
- graphcore/transport/agent_asgi.py +68 -0
- graphcore/transport/agent_client.py +85 -0
- graphcore/transport/channel_layer.py +68 -0
- graphcore/transport/consumers.py +507 -0
- graphcore/transport/routing.py +6 -0
- graphcore/transport/tests/__init__.py +0 -0
- graphcore/transport/tests/test_agent_client.py +31 -0
- graphcore/transport/tests/test_api_views.py +733 -0
- graphcore/transport/tests/test_channel_layer.py +96 -0
- graphcore/transport/tests/test_consumers.py +963 -0
- graphcore/transport/tests/test_resource_metadata.py +67 -0
- graphcore/transport/urls.py +29 -0
- graphcore/transport/views.py +358 -0
- graphcore/types/__init__.py +4 -0
- graphcore/types/access.py +114 -0
- graphcore/types/api.py +76 -0
- graphcore/types/entities.py +100 -0
- graphcore/types/entity_id.py +85 -0
- graphcore/types/execution.py +41 -0
- graphcore/types/identity.py +20 -0
- graphcore/types/onboarding.py +20 -0
- graphcore/types/query.py +116 -0
- graphcore/types/schedules.py +91 -0
- graphcore/types/strategy.py +73 -0
- graphcore/types/tests/__init__.py +0 -0
- graphcore/types/tests/test_entity_id.py +50 -0
- graphcore/urls.py +5 -0
- graphcore_kernel-0.1.0.dist-info/METADATA +94 -0
- graphcore_kernel-0.1.0.dist-info/RECORD +343 -0
- graphcore_kernel-0.1.0.dist-info/WHEEL +5 -0
- graphcore_kernel-0.1.0.dist-info/entry_points.txt +2 -0
- graphcore_kernel-0.1.0.dist-info/licenses/LICENSE +202 -0
- graphcore_kernel-0.1.0.dist-info/licenses/NOTICE +2 -0
- graphcore_kernel-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,522 @@
|
|
|
1
|
+
# View Entities
|
|
2
|
+
|
|
3
|
+
## Introduction
|
|
4
|
+
|
|
5
|
+
A view is how an entity is shown: which component renders it and the UI
|
|
6
|
+
state that component remembers (collapsed sections, panel sizes, the chosen
|
|
7
|
+
tab). The kernel stores that state as a `View` so it survives reloads,
|
|
8
|
+
follows a user across devices, and can be shared. This document defines how
|
|
9
|
+
views are found, when they are stored, who can see them, and how view
|
|
10
|
+
components are written in a client.
|
|
11
|
+
|
|
12
|
+
A view references the entity it shows; it is never stored under that
|
|
13
|
+
entity. Showing an entity therefore never reads, writes, or rebroadcasts it.
|
|
14
|
+
|
|
15
|
+
This document is part of the view system (`VIEW_SYSTEM_TDD.md`), which
|
|
16
|
+
defines clients, addresses, and the route table.
|
|
17
|
+
|
|
18
|
+
## Definitions
|
|
19
|
+
|
|
20
|
+
- **Client**: as in `VIEW_SYSTEM_TDD.md`: the React frontend (`web`), the
|
|
21
|
+
agent frontend (`agent`). Each client has its own view registry. The kernel
|
|
22
|
+
treats view names and view state as opaque. The agent client stores no
|
|
23
|
+
view state.
|
|
24
|
+
- **Address**: as in `VIEW_SYSTEM_TDD.md`: a path on the deployment
|
|
25
|
+
(`/`, `/e/<backend_id>/<local_id>`, an app route, a client route), the same
|
|
26
|
+
for every client. A **page** is what a client shows at one address.
|
|
27
|
+
- **View component**: a component declared once with
|
|
28
|
+
`defineView(name, Component, options)`. Its **view name** is unique within
|
|
29
|
+
its client's registry.
|
|
30
|
+
- **View**: stored view state. Every view is its own entity, with
|
|
31
|
+
these fields:
|
|
32
|
+
- `component`: a view name, or null to use the default component for the
|
|
33
|
+
shown entity's type;
|
|
34
|
+
- `renders`: the identifier of the entity shown, or null when the view
|
|
35
|
+
shows no single entity (an app home, a dashboard, a settings page);
|
|
36
|
+
- `client`: the client that stores it;
|
|
37
|
+
- `slot`: its name among its siblings;
|
|
38
|
+
- `address`: the page it is on;
|
|
39
|
+
- `state`: a JSON object owned by the component.
|
|
40
|
+
- **Siblings**: entities with the same parent; for a top-level entity, the
|
|
41
|
+
same owner's other top-level entities.
|
|
42
|
+
- **Slot**: a view's name among its siblings. A top-level view on a page
|
|
43
|
+
has the page's address as its slot. A view inside another view has the
|
|
44
|
+
name code gives its placement, which defaults to the view name; code names
|
|
45
|
+
a slot to tell apart two placements of the same component showing the same
|
|
46
|
+
entity.
|
|
47
|
+
- **Placement**: the chain of steps from where a client starts (a page, or
|
|
48
|
+
a view opened by id) down to a view. Each step is a slot and the entity
|
|
49
|
+
shown there.
|
|
50
|
+
|
|
51
|
+
Every view is stored, and every view is the same kind of entity. Two words
|
|
52
|
+
describe how a view came to exist; they are not fields, and code never
|
|
53
|
+
branches on them:
|
|
54
|
+
|
|
55
|
+
- **Implicit view**: stored because code renders a view component at a
|
|
56
|
+
placement and its state changed. Nobody creates it on purpose. It is found
|
|
57
|
+
by where it sits: its slot and `renders` among its siblings.
|
|
58
|
+
- **Explicit view**: created on purpose at runtime, by a user (from the
|
|
59
|
+
gallery), an app, or an agent, with `CreateView`. It is found by its
|
|
60
|
+
id: it opens at `/e/<id>`, a composite shows it by holding its id, and it
|
|
61
|
+
can be shared. It has no slot and no address.
|
|
62
|
+
|
|
63
|
+
Examples, for Alice using the web client:
|
|
64
|
+
|
|
65
|
+
| View | parent | `slot` | `renders` | `address` |
|
|
66
|
+
|---|---|---|---|---|
|
|
67
|
+
| her page for project P | none | `/e/…/P` | P | `/e/…/P` |
|
|
68
|
+
| the outline of document D on that page | the view above | `outline` | D | `/e/…/P` |
|
|
69
|
+
| her settings page | none | `/settings` | none | `/settings` |
|
|
70
|
+
| an explicit view V of P | none | none | P | none |
|
|
71
|
+
| the outline of D inside V | V | `outline` | D | none |
|
|
72
|
+
|
|
73
|
+
## Requirements
|
|
74
|
+
|
|
75
|
+
1. **Rendering never writes.** Any entity renders without a View,
|
|
76
|
+
with the state defaults its component declares. An implicit view is
|
|
77
|
+
created only when its state first changes.
|
|
78
|
+
2. **Showing an entity never touches it.** Creating, changing, or deleting
|
|
79
|
+
a view never reads, writes, or rebroadcasts the entity it shows, and
|
|
80
|
+
needs no permission on that entity beyond what reading it needs.
|
|
81
|
+
3. **Each placement keeps its own state.** The same entity shown at two
|
|
82
|
+
placements keeps separate state. Two placements at the same position
|
|
83
|
+
share state unless code names separate slots.
|
|
84
|
+
4. **Siblings are unique by client, slot, and entity.** Two concurrent
|
|
85
|
+
first changes at the same placement produce one view.
|
|
86
|
+
5. **View state is shared by sharing a view.** A page's views are visible
|
|
87
|
+
only to their owner. Everything rendered inside a view opened by id is
|
|
88
|
+
stored in it and shares its access.
|
|
89
|
+
6. **Web view code is plain React.** A component is declared once and
|
|
90
|
+
rendered as ordinary JSX. Callers pass the entity to show and nothing
|
|
91
|
+
else. No component declares where its state is stored.
|
|
92
|
+
7. **The component is fixed in code or chosen at runtime.** Code can render
|
|
93
|
+
a specific view component, or render an entity and let the stored view,
|
|
94
|
+
then the entity type's default component, decide.
|
|
95
|
+
8. **Clients share addresses, not view names.** State is stored under the
|
|
96
|
+
address a client rendered, so the same place has the same address in
|
|
97
|
+
every client. A view name is resolved only by the client that renders
|
|
98
|
+
it; a name a client does not know resolves to that client's default for
|
|
99
|
+
the entity's type.
|
|
100
|
+
9. **No entity is created under a principal.**
|
|
101
|
+
10. **Deleting a local entity deletes the views that show it.** A view of a
|
|
102
|
+
remote or unreadable entity shows a tombstone and survives.
|
|
103
|
+
11. **A refused write is visible.** A view-state change the caller may not
|
|
104
|
+
store is reported as an error and leaves the state unchanged.
|
|
105
|
+
12. **A page loads in one query.** Every stored view on a page, at any
|
|
106
|
+
depth, is found by one ordinary entity query, and the views inside a
|
|
107
|
+
view opened by id by another. No client computes a key or builds a
|
|
108
|
+
string to find a view.
|
|
109
|
+
|
|
110
|
+
## Architecture
|
|
111
|
+
|
|
112
|
+
### Storage
|
|
113
|
+
|
|
114
|
+
`View` is a typed entity with its own storage model:
|
|
115
|
+
|
|
116
|
+
| Column | Type | Notes |
|
|
117
|
+
| --- | --- | --- |
|
|
118
|
+
| `component` | string, null | mutable |
|
|
119
|
+
| `renders` | string, null | indexed, write-once |
|
|
120
|
+
| `client` | string | write-once |
|
|
121
|
+
| `slot` | string, null | write-once |
|
|
122
|
+
| `address` | string, null | write-once; indexed with `client` |
|
|
123
|
+
| `position_key` | char(64), null | unique, write-once, server-only |
|
|
124
|
+
| `state` | JSON | default `{}` |
|
|
125
|
+
|
|
126
|
+
- `position_key` enforces Requirement 4. The server computes it as the
|
|
127
|
+
lowercase hex SHA-256 of the view's sibling scope (its parent, or its owner
|
|
128
|
+
when it is top-level), `client`, `slot`, and `renders`. It is unique on its
|
|
129
|
+
own, so the constraint needs no base-table column. Clients never read,
|
|
130
|
+
send, or compute it.
|
|
131
|
+
- `View.write_once_fields = ('renders', 'client', 'slot', 'address',
|
|
132
|
+
'position_key')`.
|
|
133
|
+
- `View.dependent_on = ('renders',)`
|
|
134
|
+
(`ENTITY_REFERENCE_TDD.md`, Dependent references).
|
|
135
|
+
|
|
136
|
+
Invariants:
|
|
137
|
+
|
|
138
|
+
- A view has a `slot` exactly when it has a `position_key`.
|
|
139
|
+
- A top-level view with a slot is a page's view: its slot and its
|
|
140
|
+
`address` are the page's address, and its `renders` is the entity the route
|
|
141
|
+
table resolves for the address, or null for an address the table does not
|
|
142
|
+
match.
|
|
143
|
+
- A view inside a page's view has that page's `address`, at every depth. A
|
|
144
|
+
view inside a view without an address has none.
|
|
145
|
+
- A placement has at most 64 steps. A longer one, which only a component
|
|
146
|
+
that renders itself produces, is refused with `InvalidRequest`.
|
|
147
|
+
- An address starts with `/`, has no trailing `/` except `/` itself, and
|
|
148
|
+
has no query or fragment. The server refuses any other form.
|
|
149
|
+
- Only `SetViewState` sets `slot`, and views are never moved, so a
|
|
150
|
+
view's fields cannot disagree with where it is stored.
|
|
151
|
+
- A view's children are views and its own grants. Data entities are never
|
|
152
|
+
stored under a view; a view shows them by reference.
|
|
153
|
+
|
|
154
|
+
### Strategies
|
|
155
|
+
|
|
156
|
+
**`SetViewState`** changes a view's state, creating it first when
|
|
157
|
+
it does not exist.
|
|
158
|
+
|
|
159
|
+
- With a target, the target is the view to change.
|
|
160
|
+
- Without a target (the strategy is on the deployment's allowlist), plain
|
|
161
|
+
parameters name the view by where it sits:
|
|
162
|
+
|
|
163
|
+
```json
|
|
164
|
+
{ "client": "web", "address": "/e/b/l",
|
|
165
|
+
"placement": [{ "slot": "outline", "renders": "gc://b/d" }] }
|
|
166
|
+
|
|
167
|
+
{ "client": "web", "view": "gc://b/v",
|
|
168
|
+
"placement": [{ "slot": "outline", "renders": "gc://b/d" }] }
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Exactly one of `address` (start at that page's view) and `view` (start at
|
|
172
|
+
that view) is given. With `address`, `placement` may be empty, naming the
|
|
173
|
+
page's view itself; with `view`, it has at least one step. The strategy:
|
|
174
|
+
1. starts at the page's view, finding or creating it as a top-level view
|
|
175
|
+
of the caller with `slot` and `address` set to the address; or at `view`,
|
|
176
|
+
which must be a readable view;
|
|
177
|
+
2. walks the placement, finding each step among the current view's
|
|
178
|
+
children by `position_key` and creating it when missing, with the step's
|
|
179
|
+
`slot` and `renders`, the `client`, and the `address` of the view above;
|
|
180
|
+
3. applies the change to the last view.
|
|
181
|
+
|
|
182
|
+
Creating a missing view on the way is how a change deep in the tree is
|
|
183
|
+
stored before anything around it has changed. A unique-constraint failure
|
|
184
|
+
means a concurrent request created that view; the strategy re-reads and
|
|
185
|
+
continues.
|
|
186
|
+
- `state` is shallow-merged into the view's state; a key set to null is
|
|
187
|
+
removed. `component`, when given, replaces the stored one.
|
|
188
|
+
- Returns the view's identifier.
|
|
189
|
+
|
|
190
|
+
**`CreateView`** creates an explicit view.
|
|
191
|
+
|
|
192
|
+
- Params: `renders`, `component`, `state`. The parent is the strategy's
|
|
193
|
+
optional target, as for `CreateEntity`: with one, the view is
|
|
194
|
+
placed in that entity (any data entity that allows it, or another view) and
|
|
195
|
+
shares its access; without one, it is top-level and owned by the caller.
|
|
196
|
+
The `Entity` policy lists `CreateView: Create()`, so any type that
|
|
197
|
+
does not restrict its allowlist can hold views.
|
|
198
|
+
- Returns the view's identifier.
|
|
199
|
+
|
|
200
|
+
**`DeleteEntity`** deletes a view and the views inside it.
|
|
201
|
+
Deleting an implicit view resets that placement, and everything inside it,
|
|
202
|
+
to its defaults.
|
|
203
|
+
|
|
204
|
+
### Policy
|
|
205
|
+
|
|
206
|
+
```python
|
|
207
|
+
policy.define(
|
|
208
|
+
View,
|
|
209
|
+
shareable=True,
|
|
210
|
+
can_contain=[View, Grant],
|
|
211
|
+
strategies={
|
|
212
|
+
SetViewState: Write(),
|
|
213
|
+
CreateView: Create(),
|
|
214
|
+
DeleteEntity: Delete(),
|
|
215
|
+
CreateGrant: ManageAccess(),
|
|
216
|
+
},
|
|
217
|
+
other_strategies=False,
|
|
218
|
+
)
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
- `DeleteEntity` needs `Delete` to run on a view, the same
|
|
222
|
+
permission the deletion itself checks on the view.
|
|
223
|
+
- The deployment's allowlist includes `SetViewState: Create()` and
|
|
224
|
+
`CreateView: Create()`, so a member creates top-level views under
|
|
225
|
+
the creation rule: `Create` on the deployment.
|
|
226
|
+
- A view inside another view needs `Create` on that view, and a view placed
|
|
227
|
+
in an entity needs `Create` on that entity, through the same rule.
|
|
228
|
+
- `User` is defined with `can_contain=[]`.
|
|
229
|
+
- `shareable=True` with no grants leaves a view visible only to its owner.
|
|
230
|
+
Granting on a view shares it and every view inside it: an `editor` changes
|
|
231
|
+
the shared state, a `viewer` sees it and cannot change it.
|
|
232
|
+
|
|
233
|
+
### Lookup
|
|
234
|
+
|
|
235
|
+
All lookups are ordinary `list_entities` queries over `View`:
|
|
236
|
+
|
|
237
|
+
- **A page**: `AllOf(Equal('owner', me), Equal('client', c),
|
|
238
|
+
Equal('address', a))` returns the page's view and every view inside it.
|
|
239
|
+
- **The views inside a view opened by id**:
|
|
240
|
+
`AllOf(ContainsValue('ancestor_ids', v), Equal('client', c))`.
|
|
241
|
+
- **A view**: by identifier.
|
|
242
|
+
- **The views of an entity**: `InValues('renders', ids)`.
|
|
243
|
+
|
|
244
|
+
A client matches the rows to its placements itself: the page's view is the
|
|
245
|
+
top-level row whose slot is the address, and each step below is the child
|
|
246
|
+
of the previous view with that step's `slot` and `renders`. A placement
|
|
247
|
+
whose parent view is absent has no view either, because a view is never
|
|
248
|
+
created without the views above it.
|
|
249
|
+
|
|
250
|
+
The web client batches every page and every view it opens by id in one
|
|
251
|
+
frame into one request. A page costs one round trip however deeply its
|
|
252
|
+
views nest. The one dependent read is a view whose id is itself stored
|
|
253
|
+
state (a panel or gallery card holding it): its views are found once the
|
|
254
|
+
state naming it has loaded.
|
|
255
|
+
|
|
256
|
+
### Deletion
|
|
257
|
+
|
|
258
|
+
- **Deleting a shown entity** deletes every local view whose `renders`
|
|
259
|
+
names it, through `dependent_on`.
|
|
260
|
+
- **Deleting a view, or the entity a view is placed in,** deletes the views
|
|
261
|
+
inside it, through containment.
|
|
262
|
+
- Together these delete every view whose placement runs through a deleted
|
|
263
|
+
entity. On Alice's page for project P, the outline of document D is a child
|
|
264
|
+
of the page's view (`renders = P`). Deleting P deletes the page's view, and
|
|
265
|
+
the outline's view with it, although D still exists.
|
|
266
|
+
- An id held in state (a panel, a gallery card) is a plain value, not a
|
|
267
|
+
reference; when its view is deleted, it renders a tombstone.
|
|
268
|
+
- **A deleted principal's top-level views** fall under the open item for
|
|
269
|
+
top-level entities of a deleted principal (`ENTITY_REFERENCE_TDD.md`).
|
|
270
|
+
|
|
271
|
+
### Frontend
|
|
272
|
+
|
|
273
|
+
#### Declaring a view component
|
|
274
|
+
|
|
275
|
+
```tsx
|
|
276
|
+
function DocOutline({ entityId }: ViewProps) {
|
|
277
|
+
const doc = useEntity(entityId);
|
|
278
|
+
const [state, update] = useViewState({ collapsed: [] as string[] });
|
|
279
|
+
...
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
export const DocOutlineView = defineView('docs.doc_outline', DocOutline, {
|
|
283
|
+
defaultFor: [DOC],
|
|
284
|
+
});
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
An app's frontend entry exports its view components:
|
|
288
|
+
|
|
289
|
+
```ts
|
|
290
|
+
export { DocOutlineView } from './DocOutline';
|
|
291
|
+
export { DocsHomeView } from './DocsHome';
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
The installed-apps codegen imports each app's entry, and the registry
|
|
295
|
+
registers every export declared with `defineView`. `defineView` is the only
|
|
296
|
+
declaration. Two components with the same name, or two claiming
|
|
297
|
+
`defaultFor` on the same entity type, fail when the registry is built. An
|
|
298
|
+
app's entry point is declared with `defineView(name, Component, { entry: true })`.
|
|
299
|
+
|
|
300
|
+
#### What a view component does when rendered
|
|
301
|
+
|
|
302
|
+
The component `defineView` returns takes `entityId?` and `slot?` along with
|
|
303
|
+
the component's own props. Rendering it:
|
|
304
|
+
|
|
305
|
+
1. reads the enclosing `ViewContext`: where the client started and the
|
|
306
|
+
placement so far;
|
|
307
|
+
2. adds the step `slot ?? name` showing `entityId`;
|
|
308
|
+
3. finds its view among the loaded rows;
|
|
309
|
+
4. provides a `ViewContext` with the longer placement to everything inside
|
|
310
|
+
it;
|
|
311
|
+
5. renders the component.
|
|
312
|
+
|
|
313
|
+
At the top of the tree, with no enclosing `ViewContext`, the context is the
|
|
314
|
+
current page's view: the client and the page's address, with a trailing `/`
|
|
315
|
+
dropped, and the empty placement. No component declares it. A placement at
|
|
316
|
+
the top of a page adds a step, so two placements side by side keep separate
|
|
317
|
+
state. The one exception is the main view of a route the library mounts
|
|
318
|
+
(`/`, `/e/<id>`, and app routes): it is the page's view itself rather than
|
|
319
|
+
a step below it. Outside a router there is no page, and state is not
|
|
320
|
+
stored.
|
|
321
|
+
|
|
322
|
+
#### `useViewState`
|
|
323
|
+
|
|
324
|
+
`useViewState(defaults)` returns `[state, update]`.
|
|
325
|
+
|
|
326
|
+
- `state` is the view's stored `state` merged over `defaults`, or `defaults`
|
|
327
|
+
alone when no view exists.
|
|
328
|
+
- `update(patch)` sends `SetViewState`: targeted at the view when it
|
|
329
|
+
exists, or with where it sits when it does not.
|
|
330
|
+
- State comes from the store, which is fed by `entity_update`. A refused
|
|
331
|
+
request is reported as an error and the store is unchanged.
|
|
332
|
+
|
|
333
|
+
`useViewState` takes no view name and no entity: both come from
|
|
334
|
+
`ViewContext`. A plain page component that calls it stores state in its
|
|
335
|
+
page's view.
|
|
336
|
+
|
|
337
|
+
`useCreateView()` returns `createView({ renders, component, state })`,
|
|
338
|
+
which creates a top-level explicit view owned by the user and resolves to
|
|
339
|
+
its id, or null when refused. Code that lists the views it creates keeps
|
|
340
|
+
their ids in its own state.
|
|
341
|
+
|
|
342
|
+
#### `EntityView`
|
|
343
|
+
|
|
344
|
+
`<EntityView entityId={id} slot? />` renders an entity whose component is
|
|
345
|
+
not fixed in code. Its view name is `entity`, and the chosen component
|
|
346
|
+
renders at its step. The component is, in order:
|
|
347
|
+
|
|
348
|
+
1. the stored view's `component`, when this client knows it;
|
|
349
|
+
2. the registry's `defaultFor` component for the entity's type;
|
|
350
|
+
3. `BaseEntity`.
|
|
351
|
+
|
|
352
|
+
Choosing another component from the view toolbar sets `component` through
|
|
353
|
+
`useViewState`'s update path.
|
|
354
|
+
|
|
355
|
+
When `id` names a view, `EntityView` renders that view: its component, its
|
|
356
|
+
`renders`, and its `state`. The client starts there, so everything inside
|
|
357
|
+
it is stored in it.
|
|
358
|
+
|
|
359
|
+
A tombstone renders as a placeholder carrying its cause.
|
|
360
|
+
|
|
361
|
+
#### Routes
|
|
362
|
+
|
|
363
|
+
The web client reads the route table from the server
|
|
364
|
+
(`VIEW_SYSTEM_TDD.md`). `AppRoutes`, mounted as the shell's catch-all,
|
|
365
|
+
renders `/` and one route per app entry; `EntityRoute` renders `/e/<id>`.
|
|
366
|
+
|
|
367
|
+
- `/e/<id>` renders `<EntityView entityId={id} />` as the page's view: for
|
|
368
|
+
a data entity, the principal's view of the page `/e/<id>`; for a view, that
|
|
369
|
+
view.
|
|
370
|
+
- An app route renders the component registered under its view name as the
|
|
371
|
+
page's view, with the route's entity when it has one.
|
|
372
|
+
- `/` renders the registry's `home` view, else `ViewGallery`.
|
|
373
|
+
- Client routes (`/admin`, the auth page) are mounted by `GraphCoreApp`
|
|
374
|
+
beside `AppRoutes` and take precedence over it. Their pages store view state
|
|
375
|
+
in their page's view like any route, with nothing to declare.
|
|
376
|
+
- Public pages (`definePage`) are not views. `GraphCoreRouter` renders them
|
|
377
|
+
outside `GraphCoreProvider`, with no view state and no sign-in.
|
|
378
|
+
|
|
379
|
+
#### Composites
|
|
380
|
+
|
|
381
|
+
A composite lists what it shows in its state, as ids:
|
|
382
|
+
|
|
383
|
+
```tsx
|
|
384
|
+
function HBoxView() {
|
|
385
|
+
const [state, update] = useViewState({
|
|
386
|
+
panels: [] as { entityId: string; slot?: string }[],
|
|
387
|
+
sizes: {} as Record<string, number>,
|
|
388
|
+
});
|
|
389
|
+
return (
|
|
390
|
+
<SplitPane sizes={state.sizes}>
|
|
391
|
+
{state.panels.map(p => (
|
|
392
|
+
<EntityView key={p.slot ?? p.entityId} entityId={p.entityId} slot={p.slot} />
|
|
393
|
+
))}
|
|
394
|
+
</SplitPane>
|
|
395
|
+
);
|
|
396
|
+
}
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
- Adding a panel is one state change on the composite. Removing one never
|
|
400
|
+
deletes what it showed.
|
|
401
|
+
- A panel's own state is an implicit view created the first time it changes.
|
|
402
|
+
- The composite passes a panel's `slot` to keep two panels of one entity
|
|
403
|
+
independent; how it generates one is the composite's choice.
|
|
404
|
+
- A panel holding a view's id renders that view.
|
|
405
|
+
|
|
406
|
+
A composite on a page is a personal layout. A layout others should see is
|
|
407
|
+
an explicit view, shared with them or placed in a shared entity.
|
|
408
|
+
|
|
409
|
+
#### Gallery
|
|
410
|
+
|
|
411
|
+
`ViewGallery` is a composite declared with `{ entry: true }` and rendered at
|
|
412
|
+
`/`. Its state holds the ids of the user's explicit views, as a composite
|
|
413
|
+
holds panels:
|
|
414
|
+
|
|
415
|
+
```tsx
|
|
416
|
+
const [{ views }, update] = useViewState({ views: [] as string[] });
|
|
417
|
+
const createView = useCreateView();
|
|
418
|
+
|
|
419
|
+
const add = async (preset: string) => {
|
|
420
|
+
const id = await createView({ component: preset });
|
|
421
|
+
if (id) await update({ views: [...views, id] });
|
|
422
|
+
};
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
Each card opens `/e/<view id>`. Removing a card removes its id.
|
|
426
|
+
|
|
427
|
+
### Worked examples
|
|
428
|
+
|
|
429
|
+
**Opening a document.** Alice opens `/e/D`. The route renders
|
|
430
|
+
`<EntityView entityId={D} />` as the page's view. The client queries
|
|
431
|
+
Alice's web views at `/e/D`; none exist, so the type's default component
|
|
432
|
+
renders with its defaults. Nothing is written.
|
|
433
|
+
|
|
434
|
+
**Collapsing a section.** Alice collapses a heading. `update` sends
|
|
435
|
+
`SetViewState` with no target, `client: web`, `address: /e/D`, and
|
|
436
|
+
an empty placement. The executor checks the deployment's allowlist;
|
|
437
|
+
persistence checks `Create` on the deployment for a top-level `View`.
|
|
438
|
+
The view is created, owned by Alice, with `slot` and `address` `/e/D`, and
|
|
439
|
+
`entity_update` puts it in her store.
|
|
440
|
+
|
|
441
|
+
**A dashboard written in code.**
|
|
442
|
+
|
|
443
|
+
```tsx
|
|
444
|
+
function ProjectDashboard({ entityId }: ViewProps) {
|
|
445
|
+
const project = useEntity(entityId);
|
|
446
|
+
return (
|
|
447
|
+
<TwoColumns>
|
|
448
|
+
<KanbanBoardView entityId={project.board_id} />
|
|
449
|
+
<DocOutlineView entityId={project.doc_id} />
|
|
450
|
+
</TwoColumns>
|
|
451
|
+
);
|
|
452
|
+
}
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
Rendered at `/e/P` through its `defaultFor`, it is the page's view.
|
|
456
|
+
Collapsing a board column before anything else on the page has changed
|
|
457
|
+
stores two views in one request: the page's view (`slot = /e/P`,
|
|
458
|
+
`renders = P`, empty state) and its child (`slot = kanban_board`,
|
|
459
|
+
`renders = B`) holding the change, both with `address = /e/P`. The board's
|
|
460
|
+
own page, `/e/B`, is unaffected. Reloading `/e/P` finds both in one query.
|
|
461
|
+
|
|
462
|
+
**Creating a view from the gallery.** Alice picks a preset. The gallery
|
|
463
|
+
sends `CreateView` with no target, creating a top-level view V
|
|
464
|
+
owned by Alice, then adds V's id to its own state. The card opens `/e/V`.
|
|
465
|
+
|
|
466
|
+
**Sharing a dashboard.** Alice creates an explicit view V of P and grants
|
|
467
|
+
Bob `editor` on it. Both open it by id. A column Bob collapses is stored as
|
|
468
|
+
a child of V (`slot = kanban_board`, `renders = B`, no address), and Alice
|
|
469
|
+
receives it because she can read V. (V renders the dashboard itself, so its
|
|
470
|
+
board is the first step.)
|
|
471
|
+
|
|
472
|
+
**Deleting a document.** Bob deletes D. Every view with `renders = D` is
|
|
473
|
+
deleted, with the views inside each: Alice's view of the page `/e/D`, the
|
|
474
|
+
outline of D on her project page, and every explicit view of D. A gallery
|
|
475
|
+
card holding a deleted view's id shows a tombstone.
|
|
476
|
+
|
|
477
|
+
## Trade-offs
|
|
478
|
+
|
|
479
|
+
- **State belongs to the placement.** The same document in two places has
|
|
480
|
+
two states. This is Requirement 3.
|
|
481
|
+
- **One view per placement** rather than one document per page. Each
|
|
482
|
+
placement is its own entity with its own access, history, and dependent
|
|
483
|
+
reference, at the cost of a row per placement that has changed.
|
|
484
|
+
- **Where a view sits is plain fields, not a string.** A view stores its
|
|
485
|
+
own `slot` and `renders` and its page's `address`; the client matches rows
|
|
486
|
+
to placements itself. No client builds a key, and the server alone defines
|
|
487
|
+
what makes two siblings the same. The server hashes a view's sibling scope,
|
|
488
|
+
client, slot, and entity for its unique constraint, privately.
|
|
489
|
+
- **One identity rule.** A page's view is a top-level view whose slot is
|
|
490
|
+
the address; every other view's slot is its placement name. Uniqueness among
|
|
491
|
+
siblings, a general kernel notion, covers both.
|
|
492
|
+
- **Lists of views are ids in state** rather than containment. A gallery or
|
|
493
|
+
composite holds the ids it shows, so containment means only nesting.
|
|
494
|
+
Creating a view from the gallery is two writes (create, then add its id);
|
|
495
|
+
when the second fails, the view exists and no gallery lists it.
|
|
496
|
+
- **One state object per placement across component changes.** Switching a
|
|
497
|
+
placement's component keeps its state; each component reads the keys it
|
|
498
|
+
declares and ignores the rest.
|
|
499
|
+
- **Shared state is all-or-nothing.** Everyone with access to a view sees
|
|
500
|
+
the same state; there is no personal layer over a shared view.
|
|
501
|
+
- **A nested change stores the views above it.** The first change deep in
|
|
502
|
+
the tree also creates every view above it that does not exist yet, with
|
|
503
|
+
empty state: at most one row per nesting level, once.
|
|
504
|
+
- **A page query returns every view stored on the page,** including views
|
|
505
|
+
for placements not shown at the moment. Pages hold few views; a page that
|
|
506
|
+
outgrows one result page is read with the query's cursor.
|
|
507
|
+
- **A panel or card whose entity is deleted stays until removed.** Lists
|
|
508
|
+
live in state, which is not a dependent field, so the entry shows a
|
|
509
|
+
tombstone rather than silently disappearing.
|
|
510
|
+
|
|
511
|
+
## Open items
|
|
512
|
+
|
|
513
|
+
- **Views of entities on other deployments.** A client renders a remote
|
|
514
|
+
entity in an iframe of the owning deployment's page. Sharing such a view
|
|
515
|
+
across deployments needs capability subjects (share links), an open item
|
|
516
|
+
in `AUTHORIZATION_TECHNICAL_TDD.md`.
|
|
517
|
+
- **Personal state over shared views.**
|
|
518
|
+
- **Templates**: creating a view from another view's state.
|
|
519
|
+
- **Mobile clients**: their registries and view state
|
|
520
|
+
(`VIEW_SYSTEM_TDD.md`).
|
|
521
|
+
- **Live updates for remote entities shown in views**, inherited from
|
|
522
|
+
`ENTITY_REFERENCE_TDD.md`.
|