@mapples/types 1.1.0 → 1.1.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.
@@ -8,8 +8,8 @@ import { SvgProps } from 'react-native-svg';
8
8
  * @interface RegisteredComponent
9
9
  * @template T - The props type for the component (must extend object)
10
10
  *
11
- * @property {string} type - Unique identifier for the component type
12
- * @property {ComponentType<PropsWithChildren<T>>} Component - The actual React component
11
+ * @property type - Unique identifier for the component type
12
+ * @property Component - The actual React component
13
13
  *
14
14
  * @example
15
15
  * ```typescript
@@ -20,7 +20,9 @@ import { SvgProps } from 'react-native-svg';
20
20
  * ```
21
21
  */
22
22
  export interface RegisteredComponent<T extends object = object> {
23
+ /** Unique string identifier for the component type (e.g. `'Button'`, `'TextInput'`) */
23
24
  type: string;
25
+ /** The actual React component to render for this type */
24
26
  Component: ComponentType<PropsWithChildren<T>>;
25
27
  }
26
28
  /**
@@ -42,8 +44,8 @@ export type RegisteredComponents = Record<string, RegisteredComponent>;
42
44
  * Configuration for data properties that can be bound to components.
43
45
  *
44
46
  * @interface DataProp
45
- * @property {string} key - The key identifier for the data property
46
- * @property {boolean} active - Whether this data property is currently active
47
+ * @property key - The key identifier for the data property
48
+ * @property active - Whether this data property is currently active
47
49
  */
48
50
  export interface DataProp {
49
51
  key: string;
@@ -55,10 +57,13 @@ export interface DataProp {
55
57
  */
56
58
  export type DataProps = Partial<Record<string, DataProp>>;
57
59
  /**
58
- * SVG asset source (e.g. for icon components). Expects a default export that is an SVG component.
59
- * @public
60
+ * Represents a lazily-imported SVG module whose default export is an SVG component.
61
+ * Matches the shape produced by `import()` of an `.svg` file with a default export.
62
+ *
63
+ * @interface SvgSource
60
64
  */
61
65
  export interface SvgSource {
66
+ /** The SVG React component exported as the default of an SVG module */
62
67
  default: ComponentType<SvgProps>;
63
68
  }
64
69
  //# sourceMappingURL=components.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE1D;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CAClC"}
1
+ {"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC5D,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,SAAS,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CAClC"}
package/dist/index.d.ts CHANGED
@@ -1,11 +1,7 @@
1
- /**
2
- * @packageDocumentation
3
- * @module @mapples/types
4
- *
5
- * TypeScript type definitions for the Mapples Open Kit: component registration,
6
- * actions, mapplets, and shared contracts used across @mapples packages.
7
- */
8
1
  export * from './components';
2
+ export * from './style';
9
3
  export * from './action';
10
4
  export * from './mapplet';
5
+ export * from './navigation';
6
+ export * from './navigationValidator';
11
7
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC"}
package/dist/index.js CHANGED
@@ -1,11 +1,7 @@
1
- /**
2
- * @packageDocumentation
3
- * @module @mapples/types
4
- *
5
- * TypeScript type definitions for the Mapples Open Kit: component registration,
6
- * actions, mapplets, and shared contracts used across @mapples packages.
7
- */
8
1
  export * from './components';
2
+ export * from './style';
9
3
  export * from './action';
10
4
  export * from './mapplet';
5
+ export * from './navigation';
6
+ export * from './navigationValidator';
11
7
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC"}
package/dist/mapplet.d.ts CHANGED
@@ -6,8 +6,8 @@ import { Action } from './action';
6
6
  * @interface MappletType
7
7
  * @template State - The type of the application state (must extend object)
8
8
  *
9
- * @property {State} [state] - Optional initial state object for the Mapplet
10
- * @property {(action: Action) => void} [onAction] - Optional callback function to handle actions emitted by the Mapplet
9
+ * @property [state] - Optional initial state object for the Mapplet
10
+ * @property [onAction] - Optional callback function to handle actions emitted by the Mapplet
11
11
  *
12
12
  * @example
13
13
  * ```typescript
@@ -0,0 +1,183 @@
1
+ /**
2
+ * Navigation document schema — the JSON persisted in `Navigation.data`.
3
+ *
4
+ * The backend treats `Navigation.data` as opaque (the same way `Page.data` is
5
+ * opaque and typed client-side). This module owns its shape: a single atomic
6
+ * document that supports nesting, ordering, and per-navigator/per-screen
7
+ * options. See the proposal §4 for the full rationale.
8
+ *
9
+ * @module navigation
10
+ */
11
+ /**
12
+ * The kind of navigator a {@link NavigatorNode} represents.
13
+ *
14
+ * - `stack` — push/pop screens with a header (cards, modals).
15
+ * - `tabs` — bottom tab bar switching between sibling routes.
16
+ * - `drawer` — side drawer switching between sibling routes.
17
+ */
18
+ export type NavigatorType = 'stack' | 'tabs' | 'drawer';
19
+ /**
20
+ * The root navigation document stored in `Navigation.data`.
21
+ *
22
+ * Navigators are held in a flat map keyed by id (mirroring how `RenderDom`
23
+ * stores `childComponents`) so nesting is expressed by reference rather than
24
+ * by physical containment, keeping reorder/move operations cheap.
25
+ *
26
+ * @interface NavigationDocument
27
+ */
28
+ export interface NavigationDocument {
29
+ /** Schema version. Always `1` for the current model. */
30
+ version: 1;
31
+ /** Id of the navigator that renders at the application root. */
32
+ rootNavigatorId: string;
33
+ /** Flat map of every navigator in the document, keyed by {@link NavigatorNode.id}. */
34
+ navigators: Record<string, NavigatorNode>;
35
+ }
36
+ /**
37
+ * A single navigator (stack, tabs, or drawer) and its ordered child routes.
38
+ *
39
+ * @interface NavigatorNode
40
+ */
41
+ export interface NavigatorNode {
42
+ /** Stable unique id, used as the key in {@link NavigationDocument.navigators}. */
43
+ id: string;
44
+ /** The kind of navigator. Determines which {@link NavigatorOptions} apply. */
45
+ type: NavigatorType;
46
+ /** Human-readable name, unique within the document; used as the route name. */
47
+ name: string;
48
+ /** Id of the route shown first. Defaults to the first entry of {@link routes}. */
49
+ initialRouteId?: string;
50
+ /** Child routes in display order (tab/drawer order, or stack base order). */
51
+ routes: RouteNode[];
52
+ /** Presentation/styling options scoped to this navigator. */
53
+ options?: NavigatorOptions;
54
+ }
55
+ /**
56
+ * A single route within a navigator — either a page leaf or a nested navigator.
57
+ *
58
+ * @interface RouteNode
59
+ */
60
+ export interface RouteNode {
61
+ /** Stable unique id for this route. */
62
+ id: string;
63
+ /** Route name, unique within the parent navigator. */
64
+ name: string;
65
+ /** What this route renders: a page leaf or a nested navigator. */
66
+ target: {
67
+ kind: 'page';
68
+ pageUuid: string;
69
+ } | {
70
+ kind: 'navigator';
71
+ navigatorId: string;
72
+ };
73
+ /** How the screen is presented. Valid only when the parent navigator is a `stack`. */
74
+ presentation?: 'card' | 'modal' | 'transparentModal';
75
+ /** Per-screen option overrides (header, tab/drawer label & icon). */
76
+ options?: ScreenOptions;
77
+ /** Reserved for deep linking. No v1 UI. */
78
+ path?: string;
79
+ /** Reserved for a state condition guard. No v1 UI. */
80
+ guard?: string;
81
+ }
82
+ /**
83
+ * Navigator-level presentation options. Only the field matching the
84
+ * navigator's {@link NavigatorType} is meaningful at runtime.
85
+ *
86
+ * @interface NavigatorOptions
87
+ */
88
+ export interface NavigatorOptions {
89
+ /** Header options — applies to `stack` navigators. */
90
+ header?: HeaderOptions;
91
+ /** Tab bar options — applies to `tabs` navigators. */
92
+ tabBar?: TabBarOptions;
93
+ /** Drawer options — applies to `drawer` navigators. */
94
+ drawer?: DrawerOptions;
95
+ }
96
+ /**
97
+ * Styling and behaviour of a stack navigator's header.
98
+ *
99
+ * Colour fields accept either a raw value or a theme reference of the form
100
+ * `ref(theme:<uuid>:<name>)`.
101
+ *
102
+ * @interface HeaderOptions
103
+ */
104
+ export interface HeaderOptions {
105
+ /** Whether the header is shown. */
106
+ visible?: boolean;
107
+ /** Header title text. */
108
+ title?: string;
109
+ /** Header background — raw value or `ref(theme:<uuid>:<name>)`. */
110
+ backgroundColor?: string;
111
+ /** Tint applied to header buttons/icons. */
112
+ tintColor?: string;
113
+ /** Title text styling. */
114
+ titleStyle?: {
115
+ fontFamily?: string;
116
+ fontSize?: number;
117
+ color?: string;
118
+ };
119
+ /** Whether the back button is shown. */
120
+ backVisible?: boolean;
121
+ /** Whether the header's bottom shadow/border is shown. */
122
+ shadowVisible?: boolean;
123
+ }
124
+ /**
125
+ * Styling and behaviour of a tabs navigator's tab bar.
126
+ *
127
+ * @interface TabBarOptions
128
+ */
129
+ export interface TabBarOptions {
130
+ /** Whether the tab bar is shown. */
131
+ visible?: boolean;
132
+ /** Tab bar background colour. */
133
+ backgroundColor?: string;
134
+ /** Tint for the active tab. */
135
+ activeTintColor?: string;
136
+ /** Tint for inactive tabs. */
137
+ inactiveTintColor?: string;
138
+ /** Whether tab labels are shown. */
139
+ labelVisible?: boolean;
140
+ /** Tab label text styling. */
141
+ labelStyle?: {
142
+ fontFamily?: string;
143
+ fontSize?: number;
144
+ };
145
+ }
146
+ /**
147
+ * Styling and behaviour of a drawer navigator.
148
+ *
149
+ * @interface DrawerOptions
150
+ */
151
+ export interface DrawerOptions {
152
+ /** Which edge the drawer opens from. */
153
+ position?: 'left' | 'right';
154
+ /** How the drawer animates relative to the screen. */
155
+ drawerType?: 'front' | 'back' | 'slide';
156
+ /** Drawer background colour. */
157
+ backgroundColor?: string;
158
+ /** Tint for the active drawer item. */
159
+ activeTintColor?: string;
160
+ /** Tint for inactive drawer items. */
161
+ inactiveTintColor?: string;
162
+ /** Drawer width in points. */
163
+ width?: number;
164
+ }
165
+ /**
166
+ * Per-screen option overrides. Extends {@link HeaderOptions} (each field
167
+ * optional) and adds tab/drawer item presentation for the screen.
168
+ *
169
+ * Icon fields accept a reference of the form `ref(icon:<uuid>:<name>)`.
170
+ *
171
+ * @interface ScreenOptions
172
+ */
173
+ export interface ScreenOptions extends Partial<HeaderOptions> {
174
+ /** Tab bar icon — `ref(icon:<uuid>:<name>)`. */
175
+ tabIcon?: string;
176
+ /** Tab bar label override. */
177
+ tabLabel?: string;
178
+ /** Drawer icon — `ref(icon:<uuid>:<name>)`. */
179
+ drawerIcon?: string;
180
+ /** Drawer label override. */
181
+ drawerLabel?: string;
182
+ }
183
+ //# sourceMappingURL=navigation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../src/navigation.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Navigation document schema — the JSON persisted in `Navigation.data`.
3
+ *
4
+ * The backend treats `Navigation.data` as opaque (the same way `Page.data` is
5
+ * opaque and typed client-side). This module owns its shape: a single atomic
6
+ * document that supports nesting, ordering, and per-navigator/per-screen
7
+ * options. See the proposal §4 for the full rationale.
8
+ *
9
+ * @module navigation
10
+ */
11
+ //# sourceMappingURL=navigation.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"navigation.js","sourceRoot":"","sources":["../src/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}
@@ -0,0 +1,58 @@
1
+ import { NavigationDocument } from './navigation';
2
+ /**
3
+ * Codes for the invariants enforced by {@link validateNavigationDocument}.
4
+ *
5
+ * - `ROOT_MISSING` — {@link NavigationDocument.rootNavigatorId} has no matching navigator.
6
+ * - `NAVIGATOR_TARGET_MISSING` — a `navigator` route points at an absent navigator.
7
+ * - `NAVIGATOR_CYCLE` — navigator nesting is not a tree (a cycle or shared child exists).
8
+ * - `INITIAL_ROUTE_INVALID` — `initialRouteId` is not one of the navigator's routes.
9
+ * - `DUPLICATE_ROUTE_NAME` — two routes share a name within one navigator.
10
+ * - `PRESENTATION_NOT_STACK` — a `presentation` is set on a non-stack navigator's route.
11
+ */
12
+ export type NavigationValidationCode = 'ROOT_MISSING' | 'NAVIGATOR_TARGET_MISSING' | 'NAVIGATOR_CYCLE' | 'INITIAL_ROUTE_INVALID' | 'DUPLICATE_ROUTE_NAME' | 'PRESENTATION_NOT_STACK';
13
+ /**
14
+ * A single validation failure produced by {@link validateNavigationDocument}.
15
+ *
16
+ * @interface NavigationValidationError
17
+ */
18
+ export interface NavigationValidationError {
19
+ /** Machine-readable invariant code. */
20
+ code: NavigationValidationCode;
21
+ /** Human-readable explanation of the failure. */
22
+ message: string;
23
+ /** Id of the navigator the error relates to, when applicable. */
24
+ navigatorId?: string;
25
+ /** Id of the route the error relates to, when applicable. */
26
+ routeId?: string;
27
+ }
28
+ /**
29
+ * The outcome of validating a {@link NavigationDocument}.
30
+ *
31
+ * @interface NavigationValidationResult
32
+ */
33
+ export interface NavigationValidationResult {
34
+ /** `true` when {@link errors} is empty. */
35
+ valid: boolean;
36
+ /** Every invariant violation found. */
37
+ errors: NavigationValidationError[];
38
+ }
39
+ /**
40
+ * Validate the structural invariants of a {@link NavigationDocument}.
41
+ *
42
+ * Enforces:
43
+ * - `rootNavigatorId` resolves to an existing navigator;
44
+ * - every `navigator`-kind route target resolves to an existing navigator;
45
+ * - navigator nesting forms a tree (no cycles; each navigator reached by at
46
+ * most one parent);
47
+ * - each navigator's `initialRouteId`, when set, names one of its routes;
48
+ * - route names are unique within their parent navigator;
49
+ * - `presentation` is only set on routes whose parent navigator is a `stack`.
50
+ *
51
+ * The check is exhaustive: all violations are collected rather than failing on
52
+ * the first.
53
+ *
54
+ * @param doc - The navigation document to validate.
55
+ * @returns A {@link NavigationValidationResult} listing any violations.
56
+ */
57
+ export declare function validateNavigationDocument(doc: NavigationDocument): NavigationValidationResult;
58
+ //# sourceMappingURL=navigationValidator.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"navigationValidator.d.ts","sourceRoot":"","sources":["../src/navigationValidator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAiB,MAAM,cAAc,CAAC;AAEjE;;;;;;;;;GASG;AACH,MAAM,MAAM,wBAAwB,GAChC,cAAc,GACd,0BAA0B,GAC1B,iBAAiB,GACjB,uBAAuB,GACvB,sBAAsB,GACtB,wBAAwB,CAAC;AAE7B;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,uCAAuC;IACvC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;IACf,uCAAuC;IACvC,MAAM,EAAE,yBAAyB,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,kBAAkB,GACtB,0BAA0B,CA2B5B"}
@@ -0,0 +1,134 @@
1
+ /**
2
+ * Validate the structural invariants of a {@link NavigationDocument}.
3
+ *
4
+ * Enforces:
5
+ * - `rootNavigatorId` resolves to an existing navigator;
6
+ * - every `navigator`-kind route target resolves to an existing navigator;
7
+ * - navigator nesting forms a tree (no cycles; each navigator reached by at
8
+ * most one parent);
9
+ * - each navigator's `initialRouteId`, when set, names one of its routes;
10
+ * - route names are unique within their parent navigator;
11
+ * - `presentation` is only set on routes whose parent navigator is a `stack`.
12
+ *
13
+ * The check is exhaustive: all violations are collected rather than failing on
14
+ * the first.
15
+ *
16
+ * @param doc - The navigation document to validate.
17
+ * @returns A {@link NavigationValidationResult} listing any violations.
18
+ */
19
+ export function validateNavigationDocument(doc) {
20
+ const errors = [];
21
+ const navigators = doc.navigators ?? {};
22
+ // rootNavigatorId must resolve.
23
+ if (!navigators[doc.rootNavigatorId]) {
24
+ errors.push({
25
+ code: 'ROOT_MISSING',
26
+ message: `rootNavigatorId "${doc.rootNavigatorId}" does not exist in navigators`,
27
+ navigatorId: doc.rootNavigatorId,
28
+ });
29
+ }
30
+ // Count how many routes target each navigator, to detect shared children.
31
+ const parentCount = {};
32
+ for (const navigator of Object.values(navigators)) {
33
+ validateNavigator(navigator, navigators, parentCount, errors);
34
+ }
35
+ // Navigator nesting must be a tree: no navigator may have more than one
36
+ // parent, and following nested targets from the root must not revisit a
37
+ // navigator (cycle detection).
38
+ detectSharedChildren(parentCount, errors);
39
+ detectCycles(doc, navigators, errors);
40
+ return { valid: errors.length === 0, errors };
41
+ }
42
+ /** Validate a single navigator's routes and per-navigator invariants. */
43
+ function validateNavigator(navigator, navigators, parentCount, errors) {
44
+ const routes = navigator.routes ?? [];
45
+ const seenNames = new Set();
46
+ for (const route of routes) {
47
+ // Route names unique within the navigator.
48
+ if (seenNames.has(route.name)) {
49
+ errors.push({
50
+ code: 'DUPLICATE_ROUTE_NAME',
51
+ message: `Duplicate route name "${route.name}" in navigator "${navigator.name}"`,
52
+ navigatorId: navigator.id,
53
+ routeId: route.id,
54
+ });
55
+ }
56
+ seenNames.add(route.name);
57
+ // presentation only valid under a stack parent.
58
+ if (route.presentation !== undefined && navigator.type !== 'stack') {
59
+ errors.push({
60
+ code: 'PRESENTATION_NOT_STACK',
61
+ message: `Route "${route.name}" sets presentation but parent navigator "${navigator.name}" is "${navigator.type}", not "stack"`,
62
+ navigatorId: navigator.id,
63
+ routeId: route.id,
64
+ });
65
+ }
66
+ // navigator targets must resolve, and contribute to the parent count.
67
+ if (route.target.kind === 'navigator') {
68
+ const targetId = route.target.navigatorId;
69
+ if (!navigators[targetId]) {
70
+ errors.push({
71
+ code: 'NAVIGATOR_TARGET_MISSING',
72
+ message: `Route "${route.name}" targets navigator "${targetId}" which does not exist`,
73
+ navigatorId: navigator.id,
74
+ routeId: route.id,
75
+ });
76
+ }
77
+ else {
78
+ parentCount[targetId] = (parentCount[targetId] ?? 0) + 1;
79
+ }
80
+ }
81
+ }
82
+ // initialRouteId, when set, must name one of the routes.
83
+ if (navigator.initialRouteId !== undefined &&
84
+ !routes.some((r) => r.id === navigator.initialRouteId)) {
85
+ errors.push({
86
+ code: 'INITIAL_ROUTE_INVALID',
87
+ message: `initialRouteId "${navigator.initialRouteId}" is not a route of navigator "${navigator.name}"`,
88
+ navigatorId: navigator.id,
89
+ });
90
+ }
91
+ }
92
+ /** Flag any navigator targeted by more than one route (not a tree). */
93
+ function detectSharedChildren(parentCount, errors) {
94
+ for (const [navigatorId, count] of Object.entries(parentCount)) {
95
+ if (count > 1) {
96
+ errors.push({
97
+ code: 'NAVIGATOR_CYCLE',
98
+ message: `Navigator "${navigatorId}" is nested under ${count} routes; navigators must form a tree`,
99
+ navigatorId,
100
+ });
101
+ }
102
+ }
103
+ }
104
+ /**
105
+ * Walk the navigator nesting from the root, flagging any navigator revisited
106
+ * on a single path (a cycle).
107
+ */
108
+ function detectCycles(doc, navigators, errors) {
109
+ const reported = new Set();
110
+ const walk = (navigatorId, path) => {
111
+ if (path.has(navigatorId)) {
112
+ if (!reported.has(navigatorId)) {
113
+ reported.add(navigatorId);
114
+ errors.push({
115
+ code: 'NAVIGATOR_CYCLE',
116
+ message: `Navigator "${navigatorId}" participates in a nesting cycle`,
117
+ navigatorId,
118
+ });
119
+ }
120
+ return;
121
+ }
122
+ const navigator = navigators[navigatorId];
123
+ if (!navigator)
124
+ return; // missing targets already reported elsewhere.
125
+ const nextPath = new Set(path).add(navigatorId);
126
+ for (const route of navigator.routes ?? []) {
127
+ if (route.target.kind === 'navigator') {
128
+ walk(route.target.navigatorId, nextPath);
129
+ }
130
+ }
131
+ };
132
+ walk(doc.rootNavigatorId, new Set());
133
+ }
134
+ //# sourceMappingURL=navigationValidator.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"navigationValidator.js","sourceRoot":"","sources":["../src/navigationValidator.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,60 @@
1
+ /**
2
+ * @fileoverview Cross-cutting style value types shared by the runtime renderer
3
+ * and tooling that emits `RenderDom` (e.g. the Figma connector).
4
+ *
5
+ * These are *data* contracts — plain serializable shapes that travel inside a
6
+ * node's `props`. They intentionally live in `@mapples/types` (which has no
7
+ * React Native runtime dependency) so both the renderer and any producer can
8
+ * depend on the same definition without pulling in `expo-linear-gradient`.
9
+ *
10
+ * @packageDocumentation
11
+ * @public
12
+ */
13
+ /**
14
+ * A single stop in a {@link LinearGradient}.
15
+ *
16
+ * @property color - A CSS/RN color string (e.g. `rgba(…)`), already folded with
17
+ * the paint and per-stop opacity by the producer.
18
+ * @property position - Normalized offset along the gradient axis, `0`–`1`.
19
+ *
20
+ * @public
21
+ */
22
+ export interface GradientStop {
23
+ color: string;
24
+ position: number;
25
+ }
26
+ /**
27
+ * Structured linear-gradient payload carried on `RenderDomNode.props.gradient`.
28
+ *
29
+ * React Native has no native gradient style, so a gradient travels as data and
30
+ * is rendered by the container components in `@mapples/ui` (which wrap
31
+ * `expo-linear-gradient`). `start`/`end` are normalized object-space
32
+ * coordinates (`0`–`1`), matching Figma's `gradientHandlePositions`: `{x:0,y:0}`
33
+ * is the top-left of the node's box, `{x:1,y:1}` the bottom-right.
34
+ *
35
+ * This shape is the **runtime-owned contract**: producers such as the Figma
36
+ * connector emit exactly this. Keep it in sync with
37
+ * `@mapplesorg/figma-connector`'s `LinearGradient` type.
38
+ *
39
+ * @public
40
+ */
41
+ export interface LinearGradient {
42
+ type: 'linear';
43
+ stops: GradientStop[];
44
+ start: {
45
+ x: number;
46
+ y: number;
47
+ };
48
+ end: {
49
+ x: number;
50
+ y: number;
51
+ };
52
+ }
53
+ /**
54
+ * Any gradient payload a node may carry. Currently only linear gradients are
55
+ * supported; widening this union (radial, angular) is the extension point.
56
+ *
57
+ * @public
58
+ */
59
+ export type Gradient = LinearGradient;
60
+ //# sourceMappingURL=style.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"style.d.ts","sourceRoot":"","sources":["../src/style.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,KAAK,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChC,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,CAAC"}
package/dist/style.js ADDED
@@ -0,0 +1,13 @@
1
+ /**
2
+ * @fileoverview Cross-cutting style value types shared by the runtime renderer
3
+ * and tooling that emits `RenderDom` (e.g. the Figma connector).
4
+ *
5
+ * These are *data* contracts — plain serializable shapes that travel inside a
6
+ * node's `props`. They intentionally live in `@mapples/types` (which has no
7
+ * React Native runtime dependency) so both the renderer and any producer can
8
+ * depend on the same definition without pulling in `expo-linear-gradient`.
9
+ *
10
+ * @packageDocumentation
11
+ * @public
12
+ */
13
+ //# sourceMappingURL=style.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"style.js","sourceRoot":"","sources":["../src/style.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}
package/package.json CHANGED
@@ -1,12 +1,13 @@
1
1
  {
2
2
  "name": "@mapples/types",
3
- "version": "1.1.0",
3
+ "version": "1.1.2",
4
4
  "main": "dist/index.js",
5
5
  "types": "dist/index.d.ts",
6
6
  "scripts": {
7
7
  "build": "tsc -b tsconfig.build.json",
8
8
  "lint": "eslint .",
9
9
  "type-check": "tsc --noEmit",
10
+ "test": "jest",
10
11
  "clean": "rm -rf dist"
11
12
  },
12
13
  "author": {