@graphcore/react-kernel 0.2.2 → 0.2.5

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.
@@ -0,0 +1,16 @@
1
+ import { Entity } from '../state/entityGraph';
2
+ /**
3
+ * A form's draft over a live entity. `value` follows the entity until the
4
+ * first `edit`, then holds the draft while others' saves arrive. `base` is
5
+ * the version the draft started from: send it to a strategy that refuses a
6
+ * stale write, so a save never silently overwrites a change it never showed.
7
+ * `stale` is true once the entity has moved past `base`.
8
+ */
9
+ export declare function useEditable<T extends object>(entity: Entity | null | undefined, read: (entity: Entity) => T): {
10
+ value: T;
11
+ edit: (patch: Partial<T>) => void;
12
+ reset: () => void;
13
+ editing: boolean;
14
+ base: number;
15
+ stale: boolean;
16
+ };
@@ -0,0 +1,16 @@
1
+ export type StrategyRequest = {
2
+ strategy_name: string;
3
+ target_entity_id: string | null;
4
+ param_config?: Record<string, unknown>;
5
+ };
6
+ /**
7
+ * Runs strategies for a component. `run` resolves to the run's `ret_val`, or to
8
+ * `null` when the run fails or is refused; `error` then holds the failure (a
9
+ * `StrategyError` carries its `code`) until the next run or `clearError`.
10
+ */
11
+ export declare function useStrategy(): {
12
+ run: <R = Record<string, unknown>>(request: StrategyRequest) => Promise<R | null>;
13
+ busy: boolean;
14
+ error: Error;
15
+ clearError: () => void;
16
+ };
@@ -18,8 +18,8 @@ export type { AccessGrant, AccessPanelProps, AccessRole, AccessSummary, SendStra
18
18
  export { useEntityQuery } from '../state/useEntityQuery';
19
19
  export type { EntityQueryOptions } from '../state/useEntityQuery';
20
20
  export { onResync } from '../state/resyncEvents';
21
- export { allOf, anyOf, containsAny, containsValue, equal, inValues } from '../api/predicate';
22
- export type { Predicate } from '../api/predicate';
21
+ export { allOf, anyOf, containsAny, containsValue, equal, inValues, range } from '../api/predicate';
22
+ export type { Bounds, Predicate } from '../api/predicate';
23
23
  export { collectPages, definePage } from '../pages/definePage';
24
24
  export type { AppModule, DefinedPage, PageOptions } from '../pages/definePage';
25
25
  export { GraphCoreRouter } from '../components/Routes/GraphCoreRouter';
@@ -33,6 +33,7 @@ export type { DefinedView, PlacementProps, ViewOptions, ViewProps } from '../vie
33
33
  export { useCreateView, useViewState } from '../views/useViewState';
34
34
  export type { CreateView, ViewStateUpdate } from '../views/useViewState';
35
35
  export { EntityView } from '../views/EntityView';
36
+ export { usePlacementContext } from '../views/PlacementContext';
36
37
  export type { EntityViewProps } from '../views/EntityView';
37
38
  export { BaseEntity } from '../components/Entity';
38
39
  export type { UIHooks, UIHooksProps } from '../components/Entity';
@@ -47,10 +48,15 @@ export type { AppViews, ViewRegistry } from '../registry/viewRegistry';
47
48
  export { baseViews } from '../registry/baseViews';
48
49
  export { useViewRegistry } from '../registry/registry-context';
49
50
  export { useWebSocketConsumer } from '../hooks/useWebSocketConsumer';
51
+ export { useStrategy } from '../hooks/useStrategy';
52
+ export type { StrategyRequest } from '../hooks/useStrategy';
53
+ export { useEditable } from '../hooks/useEditable';
54
+ export { StrategyForm } from '../components/Strategy/StrategyForm';
55
+ export type { StrategyFormProps } from '../components/Strategy/StrategyForm';
50
56
  export { StrategyRequests } from '../utils/StrategyRequestBuilder';
51
57
  export { useDeploymentEntityId } from '../state/deploymentStore';
52
58
  export { ENTITY_ROUTE, entityIdFromParams, entityPath, findEntityId } from '../utils/entityPath';
53
- export { entityGraph, useChildren, useEntities, useEntity, useRecursiveChildren, } from '../state/entityGraph';
59
+ export { entityGraph, useChildren, useEntities, useEntity, useEntityIdByKey, useRecursiveChildren, } from '../state/entityGraph';
54
60
  export type { Entity, EntityStore } from '../state/entityGraph';
55
61
  export { useStrategyRequest, useGraphCoreBridge, useBridgeStatus } from '../state/graphCoreBridge/hooks';
56
62
  export type { GraphCoreBridge } from '../state/graphCoreBridge/types';
@@ -4,5 +4,6 @@ export declare const getAttributes: (entity: EntityData) => Record<string, unkno
4
4
  export declare const getAttr: (entity: EntityData, key: string) => unknown;
5
5
  export declare const getFields: (entity: EntityData) => Record<string, unknown>;
6
6
  export declare function typeShortName(entity: EntityData | string): string;
7
+ /** The server's `display_name`, else the type's short name, else the id. */
7
8
  export declare function getDisplayName(entity: EntityData): string;
8
9
  export {};
@@ -1,5 +1,11 @@
1
1
  import { EntityGraphChildrenOptions, Entity, EntityGraphRecursiveChildrenOptions, EntityTreeNode } from './types';
2
2
  export declare const useEntity: (entityId: string | null | undefined) => Entity | null;
3
+ /** The identifier of the entity holding `key`, cached for the session since
4
+ * identifiers are permanent, and whether no entity holds it. */
5
+ export declare const useEntityIdByKey: (key: string | null | undefined) => {
6
+ entityId: string | null;
7
+ notFound: boolean;
8
+ };
3
9
  export declare const useEntities: (entityIds: string[]) => Entity[];
4
10
  export declare const useChildren: (parentId: string | null | undefined, options?: EntityGraphChildrenOptions) => Entity[];
5
11
  export declare const useRecursiveChildren: (rootId: string | null | undefined, options?: EntityGraphRecursiveChildrenOptions) => EntityTreeNode | null;
@@ -1,5 +1,5 @@
1
1
  export { entityGraph } from './entityGraph';
2
2
  export { entityStore } from './store';
3
- export { useChildren, useEntities, useEntity, useRecursiveChildren, } from './hooks';
3
+ export { useChildren, useEntities, useEntity, useEntityIdByKey, useRecursiveChildren, } from './hooks';
4
4
  export type { Entity, EntityGraphChildrenOptions, EntityGraphRecursiveChildrenOptions, EntityTreeNode, EntityStore, } from './types';
5
5
  export { getAttributes, getAttr, getFields, getDisplayName, typeShortName } from './entityAccessors';
@@ -5,6 +5,9 @@ type EntityGraphState = {
5
5
  entityIds: string[];
6
6
  requestedEntityIds: Set<string>;
7
7
  notFoundEntityIds: Set<string>;
8
+ idsByKey: Record<string, string>;
9
+ requestedKeys: Set<string>;
10
+ notFoundKeys: Set<string>;
8
11
  };
9
12
  /** An entity older than the one held; tombstones and `forbidden` stubs always apply. */
10
13
  export declare const isOlderThanHeld: (incoming: Entity | undefined, held: Entity | undefined) => boolean;
@@ -1,6 +1,8 @@
1
1
  export interface Entity {
2
2
  entity_id: string;
3
3
  entity_type_id?: string;
4
+ /** What people call this entity: the type's `display_field`, else name, title or slug. */
5
+ display_name?: string | null;
4
6
  children_ids?: string[];
5
7
  parent_ids?: string[];
6
8
  deleted?: boolean;
@@ -44,4 +46,10 @@ export interface EntityStore {
44
46
  markNotFound(entityId: string): void;
45
47
  isNotFound(entityId: string): boolean;
46
48
  clearEntityFlags(entityId?: string): void;
49
+ readIdForKey(key: string): string | null;
50
+ resolveKey(key: string, entityId: string): void;
51
+ markKeyRequested(key: string): void;
52
+ isKeyRequested(key: string): boolean;
53
+ markKeyNotFound(key: string): void;
54
+ isKeyNotFound(key: string): boolean;
47
55
  }
@@ -18,6 +18,7 @@ export interface GraphCoreBridge {
18
18
  disconnect: (reason?: string) => void;
19
19
  dispose: () => void;
20
20
  fetchEntity: (id: string) => void;
21
+ fetchEntityByKey: (key: string) => void;
21
22
  subscribe: (ids: string[]) => void;
22
23
  executeStrategy: (strategyRequest: any, options?: {
23
24
  awaitResponse?: boolean;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * The last results of each `useEntityQuery` this session, by query key, so a
3
+ * remounted view shows them while it refetches. Cleared with the entity store.
4
+ */
5
+ export type QueryResult = {
6
+ key: string;
7
+ ids: string[];
8
+ cursor: string | null;
9
+ };
10
+ export declare function rememberResult(result: QueryResult): void;
11
+ export declare function recallResult(key: string): QueryResult | undefined;
12
+ export declare function clearQueryResults(): void;
@@ -3,6 +3,13 @@ type ResourceState<T> = {
3
3
  state: 'loading' | 'hasValue' | 'hasError';
4
4
  error: unknown;
5
5
  };
6
+ /** What a manifest declares, by key: the apply on migrate owns these fields. */
7
+ export type DeclaredInfo = {
8
+ manifest: string;
9
+ app_id: string | null;
10
+ entity_type_id: string;
11
+ fields: string[];
12
+ };
6
13
  export declare const ensureStrategyDirectoryLoaded: () => Promise<Record<string, any>>;
7
14
  export declare const refreshStrategyDirectory: () => Promise<Record<string, any>>;
8
15
  export declare const ensureAvailableEntitiesLoaded: () => Promise<Record<string, any>>;
@@ -11,4 +18,7 @@ export declare const useStrategyDirectoryState: () => ResourceState<Record<strin
11
18
  export declare const useAvailableEntitiesState: () => ResourceState<Record<string, any>>;
12
19
  export declare const useStrategyDirectoryLoadable: () => ResourceState<Record<string, any>>;
13
20
  export declare const useAvailableEntitiesLoadable: () => ResourceState<Record<string, any>>;
21
+ export declare const useDeclaredLoadable: () => ResourceState<Record<string, DeclaredInfo>>;
22
+ /** The declaration behind `key`, once the directory has loaded. */
23
+ export declare const useDeclared: (key: string | null | undefined) => DeclaredInfo | undefined;
14
24
  export {};
@@ -6,18 +6,24 @@ export type EntityQueryOptions = {
6
6
  /** Only entities granted to the viewer or their groups; grants to everyone do not count. */
7
7
  grantedToMe?: boolean;
8
8
  limit?: number;
9
+ /** Fetch every page, and show the results only once the last one arrives. */
10
+ all?: boolean;
9
11
  enabled?: boolean;
10
12
  };
11
13
  /**
12
14
  * The readable entities of `typeIds` matching `parentId` and `where`, a page at
13
- * a time. The first page is refetched when a save or delete of these types may
14
- * change which entities match, and after a resync, so the server stays the
15
- * judge of the predicate and of access.
15
+ * a time, or every page with `all`. A query run before in this session shows
16
+ * its last results at once and refetches them, with `refreshing` true.
17
+ * `loading` is true only while there is nothing to show, so an empty `ids`
18
+ * with `loading` false means none match. The results are refetched when a
19
+ * save or delete of these types may change which entities match, and after a
20
+ * resync, so the server stays the judge of the predicate and of access.
16
21
  */
17
- export declare function useEntityQuery({ typeIds, parentId, where, grantedToMe, limit, enabled, }: EntityQueryOptions): {
22
+ export declare function useEntityQuery({ typeIds, parentId, where, grantedToMe, limit, all, enabled, }: EntityQueryOptions): {
18
23
  ids: string[];
19
24
  hasMore: boolean;
20
25
  loading: boolean;
26
+ refreshing: boolean;
21
27
  loadMore: () => void;
22
28
  refresh: () => void;
23
29
  };
@@ -38,9 +38,8 @@ export namespace StrategyRequests {
38
38
  * @param {string|number|null} parentId - Parent entity ID (the target), or null for the top level
39
39
  * @param {string} entityTypeId - Entity type ID (e.g., 'graphcore.View')
40
40
  * @param {Object} initialAttributes - Initial attributes for the new entity
41
- * @param {string} entityUuid - Optional custom UUID for the entity
42
41
  */
43
- function createEntity(parentId: string | number | null, entityTypeId: string, initialAttributes?: any, entityUuid?: string): {
42
+ function createEntity(parentId: string | number | null, entityTypeId: string, initialAttributes?: any): {
44
43
  strategy_name: string;
45
44
  target_entity_id: any;
46
45
  param_config: {};
@@ -1,15 +1,24 @@
1
1
  import { default as React } from 'react';
2
- export interface EntityViewProps {
3
- entityId: string | null | undefined;
2
+ interface PlacementOptions {
4
3
  /** Tells apart two placements of the same entity at the same position. */
5
4
  slot?: string;
6
5
  className?: string;
7
6
  }
7
+ export type EntityViewProps = PlacementOptions & {
8
+ /** Entity ids the placed view reads with `usePlacementContext`. Never stored. */
9
+ context?: string[];
10
+ } & ({
11
+ entityId: string | null | undefined;
12
+ entityKey?: never;
13
+ } | {
14
+ entityKey: string;
15
+ entityId?: never;
16
+ });
8
17
  /**
9
- * Renders an entity with the view chosen for this placement: the component
10
- * stored in its view, else its type's `defaultFor` view, else `BaseEntity`.
11
- * A view renders as itself: its component over the entity it shows, with
12
- * everything inside it stored in it.
18
+ * Renders an entity, named by id or by key, with the view chosen for this
19
+ * placement: the component stored in its view, else its type's `defaultFor`
20
+ * view, else `BaseEntity`. A view renders as itself: its component over the
21
+ * entity it shows, with everything inside it stored in it.
13
22
  */
14
- export declare function EntityView({ entityId, slot, className }: EntityViewProps): React.JSX.Element;
23
+ export declare function EntityView({ entityId, entityKey, context, slot, className }: EntityViewProps): React.JSX.Element;
15
24
  export default EntityView;
@@ -0,0 +1,4 @@
1
+ export declare const NO_PLACEMENT_CONTEXT: string[];
2
+ export declare const PlacementContext: import('react').Context<string[]>;
3
+ /** The entity ids this view's placer passed to its `EntityView`; empty when it passed none. */
4
+ export declare const usePlacementContext: () => string[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@graphcore/react-kernel",
3
- "version": "0.2.2",
3
+ "version": "0.2.5",
4
4
  "description": "GraphCore React frontend \u2014 EntityView, WebSocket plumbing, and view registry for building GraphCore-powered applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {