@maias/core 0.2.0

package/dist/maias-schema.gen.js

@@ -0,0 +1,497 @@
+// GENERATED from schema/maias.schema.json — do not edit; run `npm run sync-schema`.
+export const MAIAS_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "urn:maias:schema:1.1",
+    "title": "MAIAS — Mobile App Information Architecture Schema",
+    "description": "Formal definition of MAIAS documents, spec v1.1. YAML is the primary serialisation; an equivalent JSON document validates identically. Semantic rules that cannot be expressed here (unique IDs/paths, dangling targets, registry membership, reachability) are enforced by `maias validate` lint — see docs/spec/README.md.",
+    "type": "object",
+    "properties": {
+        "maias": {
+            "type": "string",
+            "pattern": "^1\\.[0-9]+$",
+            "description": "Spec version header, e.g. \"1.0\". Always a quoted string."
+        },
+        "app": {
+            "$ref": "#/$defs/app"
+        },
+        "screens": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+                "$ref": "#/$defs/screen"
+            },
+            "description": "All screen definitions."
+        }
+    },
+    "required": [
+        "maias",
+        "app",
+        "screens"
+    ],
+    "patternProperties": {
+        "^x_": {}
+    },
+    "additionalProperties": false,
+    "$defs": {
+        "screenId": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$",
+            "description": "snake_case screen identifier."
+        },
+        "flowName": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$",
+            "description": "snake_case flow name."
+        },
+        "path": {
+            "type": "string",
+            "pattern": "^/[a-z0-9-]+(/([a-z0-9-]+|:[a-z][a-z0-9_]*))*$",
+            "description": "Kebab-case URL path with optional :param segments, e.g. /map/location/:id."
+        },
+        "presentation": {
+            "type": "string",
+            "enum": [
+                "push",
+                "replace",
+                "modal",
+                "sheet"
+            ],
+            "description": "How the target screen is presented. Default: push."
+        },
+        "screenType": {
+            "description": "Core screen type, or an x_-prefixed custom type.",
+            "anyOf": [
+                {
+                    "type": "string",
+                    "enum": [
+                        "action",
+                        "action_sheet",
+                        "container",
+                        "detail",
+                        "form",
+                        "informational",
+                        "list",
+                        "map",
+                        "marketing",
+                        "menu",
+                        "search",
+                        "status"
+                    ]
+                },
+                {
+                    "type": "string",
+                    "pattern": "^x_[a-z][a-z0-9_]*$"
+                }
+            ]
+        },
+        "app": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "description": {
+                    "type": "string"
+                },
+                "links": {
+                    "type": "object",
+                    "properties": {
+                        "scheme": {
+                            "type": "string",
+                            "pattern": "^[a-z][a-z0-9-]*$",
+                            "description": "App URL scheme for deep links, e.g. shopfront → shopfront://…"
+                        }
+                    },
+                    "required": [
+                        "scheme"
+                    ],
+                    "patternProperties": {
+                        "^x_": {}
+                    },
+                    "additionalProperties": false
+                },
+                "navigation": {
+                    "$ref": "#/$defs/navigationRegistry"
+                },
+                "flows": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": {
+                        "$ref": "#/$defs/flow"
+                    }
+                }
+            },
+            "required": [
+                "name",
+                "navigation",
+                "flows"
+            ],
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "navigationRegistry": {
+            "type": "object",
+            "description": "Every screen must appear in exactly one of primary.screens / secondary.screens (lint-enforced).",
+            "properties": {
+                "primary": {
+                    "$ref": "#/$defs/navigationGroup"
+                },
+                "secondary": {
+                    "$ref": "#/$defs/navigationGroup"
+                }
+            },
+            "required": [
+                "primary",
+                "secondary"
+            ],
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "navigationGroup": {
+            "type": "object",
+            "properties": {
+                "label": {
+                    "type": "string"
+                },
+                "screens": {
+                    "type": "array",
+                    "uniqueItems": true,
+                    "items": {
+                        "$ref": "#/$defs/screenId"
+                    },
+                    "description": "Screen IDs; primary = tab order."
+                }
+            },
+            "required": [
+                "screens"
+            ],
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "flow": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "$ref": "#/$defs/flowName"
+                },
+                "description": {
+                    "type": "string"
+                },
+                "entry_screen": {
+                    "$ref": "#/$defs/screenId"
+                },
+                "screens": {
+                    "type": "array",
+                    "minItems": 1,
+                    "uniqueItems": true,
+                    "items": {
+                        "$ref": "#/$defs/screenId"
+                    }
+                }
+            },
+            "required": [
+                "name",
+                "entry_screen",
+                "screens"
+            ],
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "screen": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "$ref": "#/$defs/screenId"
+                },
+                "title": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "type": {
+                    "$ref": "#/$defs/screenType"
+                },
+                "path": {
+                    "$ref": "#/$defs/path"
+                },
+                "description": {
+                    "type": "string",
+                    "description": "What the screen does and why it exists. Lint warns when absent."
+                },
+                "presentation": {
+                    "$ref": "#/$defs/presentation"
+                },
+                "auth": {
+                    "type": "string",
+                    "enum": [
+                        "none",
+                        "required"
+                    ],
+                    "description": "Access gate. Default: none."
+                },
+                "deep_link": {
+                    "type": "boolean",
+                    "description": "Externally addressable at <scheme>://<path>. Default: false."
+                },
+                "back": {
+                    "$ref": "#/$defs/backLink"
+                },
+                "features": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Named content/capability blocks (documentation-level)."
+                },
+                "actions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/actionEntry"
+                    },
+                    "description": "Interactive elements that don't navigate."
+                },
+                "elements": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/element"
+                    },
+                    "description": "UI element declarations, in render order."
+                },
+                "states": {
+                    "$ref": "#/$defs/states"
+                },
+                "navigation": {
+                    "$ref": "#/$defs/screenNavigation"
+                },
+                "data": {
+                    "$ref": "#/$defs/data"
+                }
+            },
+            "required": [
+                "id",
+                "title",
+                "type",
+                "path"
+            ],
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "backLink": {
+            "type": "object",
+            "description": "Declared back affordance (since spec 1.1): where the header back button leads. When label is omitted, renderers use the target screen's title.",
+            "properties": {
+                "label": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "target": {
+                    "$ref": "#/$defs/screenId"
+                }
+            },
+            "required": [
+                "target"
+            ],
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "actionEntry": {
+            "description": "Plain string, or {label, external?} for actions that leave the app.",
+            "oneOf": [
+                {
+                    "type": "string"
+                },
+                {
+                    "type": "object",
+                    "properties": {
+                        "label": {
+                            "type": "string"
+                        },
+                        "external": {
+                            "type": "boolean"
+                        }
+                    },
+                    "required": [
+                        "label"
+                    ],
+                    "patternProperties": {
+                        "^x_": {}
+                    },
+                    "additionalProperties": false
+                }
+            ]
+        },
+        "element": {
+            "type": "object",
+            "description": "A design-system-neutral UI element. `type` beyond the core taxonomy is allowed by design (fallback guarantee); lint warns when an unknown type lacks the x_ prefix.",
+            "properties": {
+                "label": {
+                    "type": "string"
+                },
+                "type": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9_]*$",
+                    "description": "Core taxonomy type (see docs/spec/05-elements.md) or x_-prefixed custom type."
+                },
+                "target": {
+                    "$ref": "#/$defs/screenId"
+                },
+                "presentation": {
+                    "$ref": "#/$defs/presentation"
+                }
+            },
+            "required": [
+                "type"
+            ],
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "states": {
+            "type": "object",
+            "description": "Non-default screen states. The default state is the screen's own `elements`.",
+            "properties": {
+                "empty": {
+                    "$ref": "#/$defs/stateVariant"
+                },
+                "loading": {
+                    "$ref": "#/$defs/stateVariant"
+                },
+                "error": {
+                    "$ref": "#/$defs/stateVariant"
+                }
+            },
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "stateVariant": {
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string"
+                },
+                "elements": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/element"
+                    },
+                    "description": "Full replacement element list for this state."
+                }
+            },
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "screenNavigation": {
+            "type": "object",
+            "properties": {
+                "primary": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/navigationItem"
+                    },
+                    "description": "Tab-bar items; only meaningful on primary screens."
+                },
+                "secondary": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/navigationItem"
+                    },
+                    "description": "Contextual links to other screens."
+                },
+                "actions": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/$defs/navigationAction"
+                    },
+                    "description": "Non-navigating interactions."
+                }
+            },
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "navigationItem": {
+            "type": "object",
+            "properties": {
+                "label": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "target": {
+                    "$ref": "#/$defs/screenId"
+                },
+                "presentation": {
+                    "$ref": "#/$defs/presentation"
+                }
+            },
+            "required": [
+                "label",
+                "target"
+            ],
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "navigationAction": {
+            "type": "object",
+            "properties": {
+                "label": {
+                    "type": "string",
+                    "minLength": 1
+                },
+                "external": {
+                    "type": "boolean",
+                    "description": "True when the action leaves the app (web link, share sheet, …)."
+                }
+            },
+            "required": [
+                "label"
+            ],
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        },
+        "data": {
+            "type": "object",
+            "properties": {
+                "reads": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Data keys the screen consumes."
+                },
+                "writes": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Data keys the screen creates or mutates."
+                }
+            },
+            "patternProperties": {
+                "^x_": {}
+            },
+            "additionalProperties": false
+        }
+    }
+};

package/dist/model.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Typed object model for MAIAS documents, mirroring spec v1.0 (docs/spec/) 1:1.
+ * `x_`-prefixed extension fields may appear on any object; they are typed as
+ * an index signature so they survive typed access without casts.
+ */
+export type Presentation = 'push' | 'replace' | 'modal' | 'sheet';
+export type AuthGate = 'none' | 'required';
+export type CoreScreenType = 'action' | 'action_sheet' | 'container' | 'detail' | 'form' | 'informational' | 'list' | 'map' | 'marketing' | 'menu' | 'search' | 'status';
+/** Core screen types plus `x_`-prefixed custom types. */
+export type ScreenType = CoreScreenType | `x_${string}`;
+export declare const CORE_SCREEN_TYPES: readonly CoreScreenType[];
+/** The 29 core element types (spec chapter 5). Custom types are `x_`-prefixed. */
+export declare const CORE_ELEMENT_TYPES: readonly string[];
+export interface Extensible {
+    [key: `x_${string}`]: unknown;
+}
+export interface Element extends Extensible {
+    type: string;
+    label?: string;
+    target?: string;
+    presentation?: Presentation;
+}
+export interface NavigationItem extends Extensible {
+    label: string;
+    target: string;
+    presentation?: Presentation;
+}
+export interface NavigationAction extends Extensible {
+    label: string;
+    external?: boolean;
+}
+/** Screen `actions` entries: plain string or labelled object. */
+export type ActionEntry = string | NavigationAction;
+export interface ScreenNavigation extends Extensible {
+    primary?: NavigationItem[];
+    secondary?: NavigationItem[];
+    actions?: NavigationAction[];
+}
+/** Declared back affordance (spec §4.3, since 1.1). Label defaults to the target screen's title. */
+export interface BackLink extends Extensible {
+    target: string;
+    label?: string;
+}
+export interface StateVariant extends Extensible {
+    description?: string;
+    elements?: Element[];
+}
+export interface ScreenStates extends Extensible {
+    empty?: StateVariant;
+    loading?: StateVariant;
+    error?: StateVariant;
+}
+export interface ScreenData extends Extensible {
+    reads?: string[];
+    writes?: string[];
+}
+export interface Screen extends Extensible {
+    id: string;
+    title: string;
+    type: ScreenType | string;
+    path: string;
+    description?: string;
+    presentation?: Presentation;
+    auth?: AuthGate;
+    deep_link?: boolean;
+    back?: BackLink;
+    features?: string[];
+    actions?: ActionEntry[];
+    elements?: Element[];
+    states?: ScreenStates;
+    navigation?: ScreenNavigation;
+    data?: ScreenData;
+}
+export interface Flow extends Extensible {
+    name: string;
+    description?: string;
+    entry_screen: string;
+    screens: string[];
+}
+export interface NavigationGroup extends Extensible {
+    label?: string;
+    screens: string[];
+}
+export interface NavigationRegistry extends Extensible {
+    primary: NavigationGroup;
+    secondary: NavigationGroup;
+}
+export interface AppLinks extends Extensible {
+    scheme: string;
+}
+export interface App extends Extensible {
+    name: string;
+    description?: string;
+    links?: AppLinks;
+    navigation: NavigationRegistry;
+    flows: Flow[];
+}
+export interface MaiasDocument extends Extensible {
+    maias: string;
+    app: App;
+    screens: Screen[];
+}
+/** JSON path into the document: object keys and array indices. */
+export type DocPath = (string | number)[];

package/dist/model.js

@@ -0,0 +1,58 @@
+/**
+ * Typed object model for MAIAS documents, mirroring spec v1.0 (docs/spec/) 1:1.
+ * `x_`-prefixed extension fields may appear on any object; they are typed as
+ * an index signature so they survive typed access without casts.
+ */
+export const CORE_SCREEN_TYPES = [
+    'action',
+    'action_sheet',
+    'container',
+    'detail',
+    'form',
+    'informational',
+    'list',
+    'map',
+    'marketing',
+    'menu',
+    'search',
+    'status',
+];
+/** The 29 core element types (spec chapter 5). Custom types are `x_`-prefixed. */
+export const CORE_ELEMENT_TYPES = [
+    // Text
+    'title',
+    'heading',
+    'paragraph',
+    'caption',
+    'bullets',
+    'label_value',
+    // Layout
+    'divider',
+    'spacer',
+    'card',
+    // Actions
+    'button',
+    'icon_button',
+    'link',
+    'chips',
+    // Inputs
+    'text_field',
+    'search_bar',
+    'toggle',
+    'checkbox',
+    'radio_group',
+    'dropdown',
+    'slider',
+    // Media
+    'image',
+    'avatar',
+    'map',
+    'video',
+    // Lists & collections
+    'list_item',
+    'empty_state',
+    // Feedback & status
+    'banner',
+    'progress',
+    'segmented_control',
+];

package/dist/parse.d.ts

@@ -0,0 +1,36 @@
+import { Document, LineCounter } from 'yaml';
+import type { MaiasDocument, DocPath } from './model.js';
+import { type Diagnostic } from './diagnostics.js';
+export type SourceFormat = 'yaml' | 'json';
+/**
+ * A parsed MAIAS document. Wraps the `yaml` Document (which preserves comments
+ * and source ranges for round-trip edits and line-referenced diagnostics)
+ * together with the plain-data view used by validation and graph utilities.
+ *
+ * JSON input is parsed through the same YAML parser (JSON is a YAML subset),
+ * so positions and edits work identically; `format` records the original
+ * serialisation so `toString()` can emit it back.
+ */
+export declare class ParsedDocument {
+    readonly ydoc: Document;
+    private readonly lineCounter;
+    readonly format: SourceFormat;
+    constructor(ydoc: Document, lineCounter: LineCounter, format: SourceFormat);
+    /** Plain-data view. Recomputed on each call — cheap, and edits stay visible. */
+    get data(): MaiasDocument;
+    /** 1-based line/col for a JSON path, when resolvable. */
+    position(path: DocPath): {
+        line: number;
+        col: number;
+    } | undefined;
+    /** Serialise. YAML keeps comments and (for unedited nodes) original layout. */
+    toString(): string;
+}
+export interface ParseResult {
+    parsed?: ParsedDocument;
+    diagnostics: Diagnostic[];
+}
+/** Parse MAIAS source text (YAML or JSON). Syntax errors come back as diagnostics, never throws. */
+export declare function parse(text: string, opts?: {
+    format?: SourceFormat;
+}): ParseResult;