@resistdesign/voltra 3.0.0-alpha.13 → 3.0.0-alpha.15

package/History-DMHOF02n.d.ts

@@ -0,0 +1,203 @@
+/**
+ * @packageDocumentation
+ *
+ * Shared EasyLayout core types.
+ */
+/**
+ * Raw layout template input.
+ */
+type EasyLayoutTemplate = string;
+/**
+ * Supported track units.
+ */
+type TrackUnit = {
+    kind: "fr";
+    value: number;
+} | {
+    kind: "px";
+    value: number;
+} | {
+    kind: "pct";
+    value: number;
+};
+/**
+ * Track specification for rows/columns.
+ */
+type TrackSpec = TrackUnit;
+/**
+ * Parsed layout representation shared by web/native implementations.
+ */
+type EasyLayoutParsed = {
+    areaGrid: string[][];
+    rowTracks: TrackSpec[];
+    colTracks: TrackSpec[];
+    areaNames: string[];
+};
+/**
+ * 1-based area bounds in row/column space.
+ */
+type AreaBounds = {
+    name: string;
+    rowStart: number;
+    rowEnd: number;
+    colStart: number;
+    colEnd: number;
+};
+/**
+ * Shared core payload for parsed template + computed bounds.
+ */
+type EasyLayoutCore = {
+    parsed: EasyLayoutParsed;
+    bounds: Record<string, AreaBounds>;
+};
+
+/**
+ * @packageDocumentation
+ *
+ * Platform-agnostic history state machine and path helpers.
+ */
+/**
+ * A normalized location entry in history.
+ */
+type HistoryLocation = {
+    /**
+     * Normalized pathname. Always starts with `/`.
+     */
+    path: string;
+    /**
+     * Optional query string (including leading `?`).
+     */
+    search?: string;
+    /**
+     * Optional hash fragment (including leading `#`).
+     */
+    hash?: string;
+    /**
+     * Optional app-defined state payload.
+     */
+    state?: unknown;
+    /**
+     * Stable entry key, unique per history entry.
+     */
+    key: string;
+};
+/**
+ * An entry inside the history stack.
+ */
+type HistoryEntry = {
+    location: HistoryLocation;
+};
+/**
+ * History listener callback.
+ */
+type HistoryListener = (location: HistoryLocation) => void;
+/**
+ * Path parts extracted from a route string.
+ */
+type HistoryPathParts = Pick<HistoryLocation, "path" | "search" | "hash">;
+/**
+ * Shared history controller interface.
+ *
+ * This is intentionally platform-agnostic. Web/native adapters can translate
+ * platform events into calls on this interface.
+ */
+type HistoryController = {
+    /**
+     * Current location.
+     */
+    location: HistoryLocation;
+    /**
+     * Number of entries in the history stack.
+     */
+    length: number;
+    /**
+     * Active entry index in the history stack.
+     */
+    index: number;
+    /**
+     * Push a new history entry.
+     *
+     * `replaceSearch` controls behavior when `path` does not include `?query`:
+     * - `false`/unset: carry forward current `search`.
+     * - `true`: clear current `search`.
+     */
+    push: (path: string, opts?: {
+        state?: unknown;
+        replaceSearch?: boolean;
+    }) => void;
+    /**
+     * Replace the current history entry.
+     *
+     * `replaceSearch` follows the same behavior as {@link push}.
+     */
+    replace: (path: string, opts?: {
+        state?: unknown;
+        replaceSearch?: boolean;
+    }) => void;
+    /**
+     * Move by delta within the history stack.
+     */
+    go: (delta: number) => void;
+    /**
+     * Move back one entry.
+     */
+    back: () => void;
+    /**
+     * Move forward one entry.
+     */
+    forward: () => void;
+    /**
+     * Subscribe to location changes.
+     */
+    listen: (listener: HistoryListener) => () => void;
+};
+/**
+ * Parse a path-like value into normalized path/search/hash parts.
+ *
+ * Supports full URLs and path-only strings.
+ *
+ * Examples:
+ * ```ts
+ * parseHistoryPath("voltra://host/books/42?tab=info#top")
+ * // { path: "/books/42", search: "?tab=info", hash: "#top" }
+ *
+ * parseHistoryPath("books/42")
+ * // { path: "/books/42" }
+ * ```
+ */
+declare const parseHistoryPath: (inputPath: string) => HistoryPathParts;
+/**
+ * Build a path string from normalized path/search/hash parts.
+ *
+ * Missing prefixes are normalized:
+ * - `search: "q=1"` -> `?q=1`
+ * - `hash: "section"` -> `#section`
+ *
+ * Example:
+ * ```ts
+ * buildHistoryPath({ path: "books/42", search: "tab=info" })
+ * // "/books/42?tab=info"
+ * ```
+ */
+declare const buildHistoryPath: ({ path, search, hash, }: HistoryPathParts) => string;
+/**
+ * Create an in-memory history implementation.
+ *
+ * @param initialPath - Initial path used for the first entry.
+ * @returns History controller backed by an in-memory stack.
+ *
+ * Behavior notes:
+ * - `go(delta)` clamps to valid bounds `[0, length - 1]`.
+ * - `push` after `back` drops forward entries.
+ * - listeners are called only when active location changes.
+ *
+ * Example:
+ * ```ts
+ * const history = createMemoryHistory("/home?tab=all");
+ * history.push("/details/42");
+ * history.back();
+ * ```
+ */
+declare const createMemoryHistory: (initialPath?: string) => HistoryController;
+
+export { type AreaBounds as A, type EasyLayoutParsed as E, type HistoryController as H, type TrackSpec as T, type EasyLayoutTemplate as a, type EasyLayoutCore as b, type HistoryEntry as c, type HistoryListener as d, type HistoryLocation as e, type HistoryPathParts as f, type TrackUnit as g, buildHistoryPath as h, createMemoryHistory as i, parseHistoryPath as p };

package/{SearchTypes-DRAJCGzB.d.ts → ItemRelationshipInfoTypes-DgpBz7hD.d.ts}

@@ -307,271 +307,4 @@ declare namespace ItemRelationshipInfoTypes {
   export { type ItemRelationshipInfoTypes_BaseItemRelationshipInfo as BaseItemRelationshipInfo, type ItemRelationshipInfoTypes_ItemRelationshipDestinationItemInfo as ItemRelationshipDestinationItemInfo, type ItemRelationshipInfoTypes_ItemRelationshipInfo as ItemRelationshipInfo, ItemRelationshipInfoTypes_ItemRelationshipInfoIdentifyingKeys as ItemRelationshipInfoIdentifyingKeys, ItemRelationshipInfoTypes_ItemRelationshipInfoKeys as ItemRelationshipInfoKeys, type ItemRelationshipInfoTypes_ItemRelationshipInfoType as ItemRelationshipInfoType, type ItemRelationshipInfoTypes_ItemRelationshipOriginInfo as ItemRelationshipOriginInfo, type ItemRelationshipInfoTypes_ItemRelationshipOriginItemInfo as ItemRelationshipOriginItemInfo, type ItemRelationshipInfoTypes_ItemRelationshipOriginatingItemInfo as ItemRelationshipOriginatingItemInfo };
 }
 
-/**
- * Search-related types used by list/search APIs.
- */
-
-/**
- * The logical operators for a search criteria.
- * */
-declare enum LogicalOperators {
-    /**
-     * Require all criteria to match.
-     * */
-    AND = "AND",
-    /**
-     * Require any criteria to match.
-     * */
-    OR = "OR"
-}
-/**
- * The comparison operators for a field criterion.
- * */
-declare enum ComparisonOperators {
-    /**
-     * Field value equals the criterion value.
-     * */
-    EQUALS = "EQUALS",
-    /**
-     * Field value does not equal the criterion value.
-     * */
-    NOT_EQUALS = "NOT_EQUALS",
-    /**
-     * Field value is greater than the criterion value.
-     * */
-    GREATER_THAN = "GREATER_THAN",
-    /**
-     * Field value is greater than or equal to the criterion value.
-     * */
-    GREATER_THAN_OR_EQUAL = "GREATER_THAN_OR_EQUAL",
-    /**
-     * Field value is less than the criterion value.
-     * */
-    LESS_THAN = "LESS_THAN",
-    /**
-     * Field value is less than or equal to the criterion value.
-     * */
-    LESS_THAN_OR_EQUAL = "LESS_THAN_OR_EQUAL",
-    /**
-     * Field value is in the provided options.
-     * */
-    IN = "IN",
-    /**
-     * Field value is not in the provided options.
-     * */
-    NOT_IN = "NOT_IN",
-    /**
-     * Field value contains the criterion value as a substring.
-     * */
-    LIKE = "LIKE",
-    /**
-     * Field value does not contain the criterion value as a substring.
-     * */
-    NOT_LIKE = "NOT_LIKE",
-    /**
-     * Field value exists and is not null.
-     * */
-    EXISTS = "EXISTS",
-    /**
-     * Field value is missing or null.
-     * */
-    NOT_EXISTS = "NOT_EXISTS",
-    /**
-     * Field value is not empty.
-     * */
-    IS_NOT_EMPTY = "IS_NOT_EMPTY",
-    /**
-     * Field value is empty.
-     * */
-    IS_EMPTY = "IS_EMPTY",
-    /**
-     * Field value is within an inclusive range.
-     * */
-    BETWEEN = "BETWEEN",
-    /**
-     * Field value is outside an inclusive range.
-     * */
-    NOT_BETWEEN = "NOT_BETWEEN",
-    /**
-     * Field value array contains the criterion value.
-     * */
-    CONTAINS = "CONTAINS",
-    /**
-     * Field value array does not contain the criterion value.
-     * */
-    NOT_CONTAINS = "NOT_CONTAINS",
-    /**
-     * Field value starts with the criterion value.
-     * */
-    STARTS_WITH = "STARTS_WITH",
-    /**
-     * Field value ends with the criterion value.
-     * */
-    ENDS_WITH = "ENDS_WITH",
-    /**
-     * Field value does not start with the criterion value.
-     * */
-    DOES_NOT_START_WITH = "DOES_NOT_START_WITH",
-    /**
-     * Field value does not end with the criterion value.
-     * */
-    DOES_NOT_END_WITH = "DOES_NOT_END_WITH"
-}
-/**
- * The field criterion for a search criteria.
- * */
-type FieldCriterion = {
-    /**
-     * Field name to compare.
-     * */
-    fieldName: string;
-    /**
-     * Comparison operator to apply.
-     * */
-    operator?: ComparisonOperators;
-    /**
-     * Custom operator label when using backend-specific operators.
-     * */
-    customOperator?: string;
-    /**
-     * Primary comparison value.
-     * */
-    value?: any;
-    /**
-     * Comparison value options (e.g., IN/BETWEEN).
-     * */
-    valueOptions?: any[];
-};
-/**
- * The criteria for a search.
- * */
-type SearchCriteria = {
-    /**
-     * Logical operator to apply across field criteria.
-     * */
-    logicalOperator: LogicalOperators;
-    /**
-     * Field-level criteria to evaluate.
-     * */
-    fieldCriteria: FieldCriterion[];
-};
-/**
- * The results from a request to list items.
- * */
-type ListItemsResults<ItemType extends Record<any, any>> = {
-    /**
-     * Cursor for paging into the next page, when available.
-     * */
-    cursor?: string;
-    /**
-     * Items returned by the request.
-     * */
-    items: ItemType[];
-};
-/**
- * The information used to sort a list of items by a specified field.
- * */
-type SortField = {
-    /**
-     * Field name to sort by.
-     * */
-    field?: string;
-    /**
-     * Whether to reverse sort order.
-     * */
-    reverse?: boolean;
-};
-/**
- * The data used to page a specific set of search results that uses full paging.
- * @see SupportedTags.fullPaging
- * */
-type StandardExpandedPagingCursor = {
-    /**
-     * Current page number.
-     * */
-    currentPage?: number;
-    /**
-     * Total number of pages available.
-     * */
-    totalPages?: number;
-};
-/**
- * The information for paging through a list of items.
- * */
-type PagingInfo = {
-    /**
-     * Items per page to request.
-     * */
-    itemsPerPage?: number;
-    /**
-     * Cursor token for paging.
-     * */
-    cursor?: string;
-};
-/**
- * Configuration for full-text search requests.
- * */
-type TextSearchConfig = {
-    /**
-     * Text query to search for.
-     * */
-    query: string;
-    /**
-     * Index mode to use when searching.
-     * */
-    mode?: "lossy" | "exact";
-    /**
-     * Optional index field name.
-     * */
-    indexField?: string;
-};
-/**
- * The configuration for listing and searching for items.
- * */
-type ListItemsConfig = PagingInfo & {
-    /**
-     * Structured search criteria.
-     * */
-    criteria?: SearchCriteria;
-    /**
-     * Sort fields to apply.
-     * */
-    sortFields?: SortField[];
-    /**
-     * Full-text search configuration.
-     * */
-    text?: TextSearchConfig;
-};
-/**
- * A configuration for listing relationships.
- * */
-type ListRelationshipsConfig = PagingInfo & {
-    /**
-     * Relationship origin info used to filter related records.
-     * */
-    relationshipItemOrigin: ItemRelationshipOriginItemInfo;
-};
-/**
- * The results from a request to list relationships.
- * */
-type ListRelationshipsResults = ListItemsResults<ItemRelationshipInfo>;
-
-type SearchTypes_ComparisonOperators = ComparisonOperators;
-declare const SearchTypes_ComparisonOperators: typeof ComparisonOperators;
-type SearchTypes_FieldCriterion = FieldCriterion;
-type SearchTypes_ListItemsConfig = ListItemsConfig;
-type SearchTypes_ListItemsResults<ItemType extends Record<any, any>> = ListItemsResults<ItemType>;
-type SearchTypes_ListRelationshipsConfig = ListRelationshipsConfig;
-type SearchTypes_ListRelationshipsResults = ListRelationshipsResults;
-type SearchTypes_LogicalOperators = LogicalOperators;
-declare const SearchTypes_LogicalOperators: typeof LogicalOperators;
-type SearchTypes_PagingInfo = PagingInfo;
-type SearchTypes_SearchCriteria = SearchCriteria;
-type SearchTypes_SortField = SortField;
-type SearchTypes_StandardExpandedPagingCursor = StandardExpandedPagingCursor;
-type SearchTypes_TextSearchConfig = TextSearchConfig;
-declare namespace SearchTypes {
-  export { SearchTypes_ComparisonOperators as ComparisonOperators, type SearchTypes_FieldCriterion as FieldCriterion, type SearchTypes_ListItemsConfig as ListItemsConfig, type SearchTypes_ListItemsResults as ListItemsResults, type SearchTypes_ListRelationshipsConfig as ListRelationshipsConfig, type SearchTypes_ListRelationshipsResults as ListRelationshipsResults, SearchTypes_LogicalOperators as LogicalOperators, type SearchTypes_PagingInfo as PagingInfo, type SearchTypes_SearchCriteria as SearchCriteria, type SearchTypes_SortField as SortField, type SearchTypes_StandardExpandedPagingCursor as StandardExpandedPagingCursor, type SearchTypes_TextSearchConfig as TextSearchConfig };
-}
-
-export { type BaseItemRelationshipInfo as B, ComparisonOperators as C, type ExpandComplexType as E, type FieldCriterion as F, HelperTypes$1 as H, type ItemRelationshipInfo as I, type ListRelationshipsConfig as L, type SearchCriteria as S, type TypeInfoDataItem as T, type ListItemsResults as a, type ListItemsConfig as b, TypeOperation as c, type TypeKeyword as d, type TypeInfoField as e, type TypeInfoMap as f, type TypeInfo as g, type ItemRelationshipInfoType as h, TypeInfo$1 as i, type SortField as j, ItemRelationshipInfoKeys as k, ItemRelationshipInfoTypes as l, SearchTypes as m, type TypeInfoPack as n, ItemRelationshipInfoIdentifyingKeys as o, type LiteralValue as p, type ItemRelationshipOriginatingItemInfo as q, type ItemRelationshipOriginInfo as r };
+export { type BaseItemRelationshipInfo as B, type ExpandComplexType as E, HelperTypes$1 as H, type ItemRelationshipInfo as I, type LiteralValue as L, type TypeInfoDataItem as T, type TypeInfoPack as a, ItemRelationshipInfoIdentifyingKeys as b, type TypeInfoMap as c, type ItemRelationshipOriginatingItemInfo as d, TypeOperation as e, type TypeInfo as f, type ItemRelationshipInfoType as g, ItemRelationshipInfoKeys as h, type ItemRelationshipOriginInfo as i, type TypeInfoField as j, TypeInfo$1 as k, type TypeKeyword as l, ItemRelationshipInfoTypes as m, type ItemRelationshipOriginItemInfo as n };

package/README.md

@@ -18,10 +18,13 @@ yarn add @resistdesign/voltra
 
 Prefer the public entrypoints below to keep imports stable and IDE auto-imports clean.
 
+The root import `@resistdesign/voltra` is intentionally unsupported to avoid
+cross-runtime bundling issues.
+
 Preferred:
 
 ```ts
-import {IaC} from "@resistdesign/voltra";
+import * as IaC from "@resistdesign/voltra/iac";
 import {Packs} from "@resistdesign/voltra/iac";
 import {addDNS} from "@resistdesign/voltra/iac/packs";
 ```
@@ -34,12 +37,14 @@ import addDNS from "@resistdesign/voltra/iac/packs/dns";
 
 Public entrypoints:
 
-- `@resistdesign/voltra`
 - `@resistdesign/voltra/api`
 - `@resistdesign/voltra/app`
 - `@resistdesign/voltra/common`
+- `@resistdesign/voltra/web`
+- `@resistdesign/voltra/native`
 - `@resistdesign/voltra/iac`
 - `@resistdesign/voltra/iac/packs`
+- `@resistdesign/voltra/build`
 
 ------------
 
@@ -94,6 +99,194 @@ App features include form generation via TypeInfo-driven AutoForm/AutoField with
 | ORM: TypeScript Type Driven Auto-generated Data Contexts with Relationships | Form Generation: AutoForm/AutoField + constraints/relations     | Typed Build Spec Creation                                     |
 |                                                                             | Form Engine: validation, defaults, denied ops, custom type flow | Typed Resource Parameters                                     |
 
+## EasyLayout (Web + Native + Core)
+
+EasyLayout now has:
+
+- Shared core parsing/math in `@resistdesign/voltra/app` (`Utils.parseTemplate`, `Utils.computeTrackPixels`, etc.).
+- Web rendering via CSS Grid in `@resistdesign/voltra/web`.
+- Native coordinate computation in `@resistdesign/voltra/native`.
+
+### Template syntax
+
+```text
+header header, 1fr
+side main, 2fr
+\ 100px 1fr
+```
+
+- Row lines: `<areas>, <row-track>` (row track optional)
+- Column line: `\ <col-track> <col-track> ...`
+- Supported units: `fr`, `px`, `%`
+- Named areas must form rectangles
+
+### Web usage
+
+```tsx
+import { Utils as WebUtils } from "@resistdesign/voltra/web";
+
+const { layout: Layout, areas } = WebUtils.getEasyLayout(undefined, undefined, {
+  gap: 12,
+  padding: 16,
+})`
+  header header, 1fr
+  side main, 2fr
+  \ 1fr 2fr
+`;
+```
+
+### Native usage
+
+```tsx
+import { Utils as NativeUtils } from "@resistdesign/voltra/native";
+
+const layout = NativeUtils.makeNativeEasyLayout(`
+  header header, 100px
+  side main, 1fr
+  \\ 1fr 2fr
+`);
+
+const coords = layout.computeNativeCoords({
+  width: 320,
+  height: 240,
+  padding: 12,
+  gap: 8,
+});
+```
+
+### Web vs Native
+
+| Runtime | Rendering model | Output |
+|---------|------------------|--------|
+| Web | CSS Grid (browser layout engine) | CSS template strings |
+| Native | Computed absolute layout | `{ left, top, width, height }` per area |
+
+## Routing (Web + Native)
+
+Voltra ships a render-agnostic Route core in `@resistdesign/voltra/app` plus platform adapters.
+
+Web usage (auto-wires `window.history`):
+
+```tsx
+import { Utils as WebUtils } from "@resistdesign/voltra/web";
+
+const { Route } = WebUtils;
+```
+
+Native usage (adapter-driven):
+
+```tsx
+import { Utils as NativeUtils } from "@resistdesign/voltra/native";
+
+const { Route, RouteProvider, createManualRouteAdapter } = NativeUtils;
+const { adapter, updatePath } = createManualRouteAdapter("/home");
+```
+
+For React Native navigation libraries, Voltra is optimized for react-navigation as the primary native default. Provide a RouteAdapter that maps navigation state to a path and call `RouteProvider`.
+
+Native navigation mapping example:
+
+```tsx
+import { Utils as NativeUtils } from "@resistdesign/voltra/native";
+
+const { createNavigationStateRouteAdapter, buildPathFromRouteChain } = NativeUtils;
+
+const adapter = createNavigationStateRouteAdapter({
+  getState: () => navigationRef.getRootState(),
+  subscribe: (listener) => navigationRef.addListener("state", listener),
+  toPath: (state) =>
+    buildPathFromRouteChain(
+      state.routes.map((route) => ({
+        name: route.name,
+        params: route.params as Record<string, any>,
+      })),
+      {
+        Home: "home",
+        Book: "books/:id",
+      },
+    ),
+  navigate: (path) => {
+    const routeName = path === "/home" ? "Home" : "Book";
+    navigationRef.navigate(routeName);
+  },
+});
+```
+
+For RN web builds, keep your navigation library linking config in sync with the same route patterns used in `buildPathFromRouteChain`.
+
+## Form Suites (Web + Native + BYOCS)
+
+Voltra's form system is split into a platform-agnostic core and platform suites:
+
+- Core contracts live under `src/app/forms/core` (field kinds, suite resolution, renderer factories).
+- Web DOM suite lives under `src/web/forms`.
+- React Native suite lives under `src/native/forms`.
+
+### Web Usage
+
+```tsx
+import { Forms } from "@resistdesign/voltra/web";
+
+const { AutoField } = Forms.createWebFormRenderer();
+```
+
+Override a single renderer:
+
+```tsx
+import { Forms } from "@resistdesign/voltra/web";
+
+const { AutoField } = Forms.createWebFormRenderer({
+  suite: Forms.withRendererOverride("string", (ctx) => {
+    return <input value={(ctx.value as string) || ""} onChange={(e) => ctx.onChange(e.target.value)} />;
+  }),
+});
+```
+
+### Native Usage
+
+```tsx
+import { Forms } from "@resistdesign/voltra/native";
+
+const { AutoField } = Forms.createNativeFormRenderer();
+```
+
+### BYOCS (Bring Your Own Component Suite)
+
+Provide partial overrides (renderers and/or primitives). Missing renderers are filled from the default suite and validated.
+
+```tsx
+import { Forms } from "@resistdesign/voltra/web";
+
+const { AutoField } = Forms.createWebFormRenderer({
+  suite: {
+    primitives: {
+      Button: ({ children }) => <button className="my-button">{children}</button>,
+    },
+    renderers: {
+      boolean: (ctx) => (
+        <label>
+          <input
+            type="checkbox"
+            checked={!!ctx.value}
+            onChange={(e) => ctx.onChange(e.target.checked)}
+          />
+          {ctx.label}
+        </label>
+      ),
+    },
+  },
+});
+```
+
+### Relation + Custom Type Hooks
+
+Renderers emit actions via:
+
+- `onRelationAction(payload)` for relation fields
+- `onCustomTypeAction(payload)` for custom types
+
+Use these to wire modals, selectors, or editors without baking UI into the core engine.
+
 ## Docs Site
 
 The docs site is both reference documentation and a canonical usage example.